VFX-E-1508¶

Title¶

StaleRunEntry

Explanation¶

cancel_run was asked to stop a run whose registry entry says running — but this workspace's run lock is free, which proves no process is running it. The entry is residue, not a live run. Nothing was cancelled, because nothing is running.

A run's registry entry is written when the run starts and updated when it ends. There are two ways that second update never happens, and this code covers both:

• The server was killed outright — SIGKILL, TerminateProcess, a machine that lost power, a container stopped without a grace period — so it never reached the completing write at all.
• The completing write itself failed — a full disk, a permissions change mid-run. The run finished and its verdict was returned to the caller; only the bookkeeping was lost. The server announces that on its stderr ("produced a verdict, but recording its completion failed"), which is how you tell this case from the first one.

Either way the entry keeps saying running permanently. There is no reaper, no lease and no startup reconciliation pass, deliberately: nothing can distinguish an abandoned run from a genuinely long one without the liveness signal the lock already is.

That lock is what makes this answer possible. It is a file handle held open for the whole of a run, and the operating system releases it when the holding process dies, however it dies. So a running entry sitting beside a free lock is a proof, not a guess.

get_run_status and list_runs still report such an entry as running, and that is intentional: reading the lock means briefly acquiring it, and a read-only tool that took the run lock could make a concurrent run_suite call fail. cancel_run is not read-only, so it is the tool that answers this question — which makes it the way to tell a phantom running entry from a real one.

Nothing changes on its own here, which is why this error is not retryable: the identical call reports the identical thing until the run's directory under <outputDir> is removed.

Common causes¶

• The MCP server process was killed while a run was in progress, rather than shut down.
• The machine lost power, or a container running the server was stopped without a grace period.
• A run's completing registry write failed (a full disk, a permissions change mid-run); the server reported it on stderr and returned the verdict, leaving the entry at running.
• A run directory was copied or restored from a backup taken while a run was in flight.

Fixes¶

• Check the server's stderr first: a "produced a verdict, but recording its completion failed" line means the run finished and only its record was lost, so the verdict it reported to its caller stands.
• Otherwise treat the run as over with an unknown outcome — it was killed, so no verdict was ever determined.
• Read whatever the run did produce with get_run_events or explain_run; the partial event stream is still on disk.
• Remove the run's directory under the workspace's output directory (.vouchfx/runs/<runId> by default) to clear the entry.
• Start the run again with run_suite if you still need its verdict — the free lock means the workspace is available.