fix(runtime): refuse a run ID the workflow engine already records before planning (#1258)

[mrthankyou]

Fixes #1258.

Problem

Planning only checks whether the run directory exists. After ultrafuzz clean <run>, which removes the run directory but leaves the engine's run record (#1257), run --run-id <run> goes through planning and the execution snapshot, and fails only at submission.

Reproduced on unstable (5c1a9775) with the built CLI on Damn Vulnerable DeFi v4.1.0 trimmed to Unstoppable. The setup was a finished private smoke run, clean dvd-unstoppable-smoke --yes, then a relaunch with the same ID. It ran for 365 s, then failed with:

WORKFLOW_SUBMISSION_FAILED -> DETACHED_ADMISSION_FAILED (exit 4)
code: RUN_EXISTS
message: "Run already exists: ultrafuzz-dvd-unstoppable-smoke"

It left a new 1.0 GB partial run directory behind.

Fix

startRun checks before planRun (workflowRunAlreadyRecorded, packages/runtime/src/start-run.ts):

• Which launches: only an explicit --run-id, and only when the project root has the engine's database, smithers.db. The engine creates that on the first launch, so a project with no engine records skips the query. The fake engine the runtime tests use never creates it, so existing tests are unaffected.
• How: it asks the engine through its own interface, inspect ultrafuzz-<run-id> --format json, which answered in under a second here. It accepts both the bare inspection and the { ok, data } envelope.
• Refusal: only when the engine reports that exact run. run then fails with RUN_ALREADY_EXISTS, the same code as an existing run directory. The message names the engine's run status and suggests another ID or resume, and doesn't name the engine (CLI product-surface rule).
• Anything else: RUN_NOT_FOUND, a failed or timed-out query, or any other answer lets the launch go ahead as before. Submission still rejects a duplicate.

Why not node:sqlite: reading smithers.db directly would also avoid a subprocess, but on Node 22 and 24 node:sqlite prints an experimental-feature warning on stderr, and it would tie the check to the engine's schema.

Verification

• Real engine, same project: the duplicate-ID launch now fails in 2 s with RUN_ALREADY_EXISTS: run dvd-unstoppable-smoke already exists in the workflow engine's records (finished), … and leaves no run directory. A fresh ID gets past the check and continues to the next step (governance, since no policy was set).
• New runtime tests:
  • with smithers.db present and the engine reporting the run, startRun refuses it before creating the run directory or calling up;
  • with RUN_NOT_FOUND, it goes ahead to up;
  • without smithers.db, the engine is not asked.
• Strict eslint, prettier and the docs check are clean.

Not in scope

clean still leaves the engine record, worktree registrations and branches behind (#1257, which has a reproduction comment). Until that's fixed, a cleaned run's ID stays taken. This PR makes that fail immediately and say so.

🤖 Generated with Claude Code

Confidence Score: 4/5

The PR is not yet safe to merge because the existing database-location gap can still let a recorded run ID reach costly planning.

Findings

1.  Database check misses recorded runs ▶

Fix with agent prompt

### Issue 1
packages/runtime/src/start-run.ts:undefined-748
For a project below `HOME`, the workflow engine can keep its store under `.smithers` rather than at `projectRoot/smithers.db`. After `clean` removes the run directory, this check skips inspection even though the engine still records the ID. The duplicate then goes through planning and fails only at submission, repeating the costly path this PR is meant to prevent.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

The PR adds a pre-planning inspection for explicit run IDs when the project-root engine database exists, refusing IDs already recorded by the workflow engine. It also documents the behavior and adds bare and enveloped inspection tests. The previously reported database-location gap remains.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  A[Start run with explicit ID] --> B{Project-root smithers.db exists?}
  B -->|No| P[Plan run]
  B -->|Yes| I[Inspect engine run ID]
  I -->|Matching run| R[Return RUN_ALREADY_EXISTS]
  I -->|Other response| P

Loading

_{Reviews (2) · Last reviewed commit: "test(runtime): cover the bare inspect re..."}

[greptile-apps]

Database check misses recorded runs

For a project below HOME, the workflow engine can keep its store under .smithers rather than at projectRoot/smithers.db. After clean removes the run directory, this check skips inspection even though the engine still records the ID. The duplicate then goes through planning and fails only at submission, repeating the costly path this PR is meant to prevent.

Knowledge Base Used: Runtime orchestration

Prompt To Fix With AI

This is a comment left during a code review.
Path: packages/runtime/src/start-run.ts
Line: 748

Comment:
**Database check misses recorded runs**

For a project below `HOME`, the workflow engine can keep its store under `.smithers` rather than at `projectRoot/smithers.db`. After `clean` removes the run directory, this check skips inspection even though the engine still records the ID. The duplicate then goes through planning and fails only at submission, repeating the costly path this PR is meant to prevent.

**Knowledge Base Used:** [Runtime orchestration](https://app.greptile.com/monad-foudnation/-/custom-context/knowledge-base/monad-developers/ultrafuzz/-/docs/runtime-orchestration.md)

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.