dev.on_timeout salvage-if-done: a timed-out dev session with a finished, gate-green product is retried and then deferred like an empty one

[wsquared]

Summary

A dev session that hits session_timeout_min with a finished, gate-green product in the worktree is routed like one that produced nothing: decide_dev (escalation.py) returns RETRY while max_dev_attempts lasts, then defers. The review side distinguishes these cases through review.on_timeout = "salvage-if-done"; the dev side has no equivalent.

Observed (0.11.1)

Setup: an unattended nightly sweep run with [limits] session_timeout_min = 180, max_dev_attempts = 2 and [scm] isolation = "worktree"; the dev adapter is Claude Code.

One story, two dev attempts, both session-end status timeout after 10800 s.

• Attempt 1 was killed re-running the deterministic gates after a successful review-fix round. Its worktree held a 486-line diff; the snapshot at refs/attempt-preserve-dirty/<run>-<baseline>-1 built and its changed test files passed.
• Attempt 2 was killed in the same phase with the deterministic gates green.
• Journal: dev-decision action: retry, reason: dev session timeout, then action: defer.
• The kept unit branch merged to main by hand the next morning after every [verify] command passed in the worktree.

Proposal

A [dev] on_timeout policy mirroring the review-side modes:

• retry (default, current behaviour).
• salvage-if-done: on timeout / stalled / over_budget, if the spec frontmatter shows the product finalized (done, or in-review reset forward, as review.on_timeout already tests) and the [verify] commands pass against the worktree, proceed to review instead of rolling back; otherwise retry.
• defer: give up on the first timeout-like verdict.

The post-kill reconcile already rescues a finished session whose artifact is on disk (policy.py comment on dev_stall_nudges); this extends it to a session killed during verification before the artifact was written. With salvage-if-done a timeout costs one verify pass instead of the attempt plus a from-scratch retry (#777). Related: #271 (the review-side salvage this mirrors), #764.

[wsquared]

Contained downstream as a reporter rather than a salvage path, since a plugin hook cannot change a dev decision. Posting the shape because two of the hazards took real measurement to find, and anyone implementing salvage-if-done inside the harness will meet both.

A post_run script reads state.json for phase: deferred tasks and the journal for each one's last unit-closed (kept, non-empty branch), runs the policy's own [verify] commands in each kept worktree, and writes a report the digest renders. It never merges and runs no git write command; it emits commands for a human.

The one that actually broke it: spawnSync with captured output caps at maxBuffer. With encoding: 'utf8', a real gate overruns the 1 MB default and the call dies ENOBUFS having never completed. Our whole unit suite passed because fake gates emit almost nothing; the first live run against the real deferred story returned blocked: `pnpm test` could not run: spawnSync /bin/sh ENOBUFS. Nothing reads a gate's output, so the fix is stdio: 'ignore'. Worth noting because the failure mimics a red gate rather than announcing itself, and because it only appears against a real suite.

A spawn that could not run is not a red gate. Before the fix, the same code path reported ENOBUFS as blocked, which reads to a human as "your code fails". Runner failures and non-zero exits deserve different verdicts.

Absence of evidence is not a pass. An empty [verify] list makes "every command exited 0" vacuously true, and so does a list of whitespace-only strings (a blank command exits 0 under a shell). Both now report not-verifiable. Relatedly, the verdict names the commands it rests on, because pnpm db:check in our list exits 0 printing db:check: skipped whenever the database is unreachable and CI is unset, which is exactly the unattended-local condition a nightly runs in. A generic disclosure beats special-casing it, since the next gate to grow a skip path is covered too.

Verifying a worktree does not license merging a branch. The gates run against the worktree; the commands merge a ref. So a pass requires the worktree clean, on its task's branch, and with HEAD unmoved across the gates, and the merge squashes the verified sha rather than the branch name, so a branch that advances afterwards cannot be merged as if verified. The post-gate cleanliness check ignores untracked paths, or the gates' own build output would void every verdict.

Result against the run in the report: the deferred story comes back pass, with verified 24f755b5...; passed pnpm typecheck, pnpm test, pnpm lint, pnpm db:check, pnpm docs:check. Every earlier reading I had of that same story was an artifact of gates that never ran.

This is strictly weaker than the [dev] on_timeout = "salvage-if-done" proposed here, because it reports after the fact instead of preventing the retry: the night still spends a second attempt and still defers. It converts a silent loss into a next-morning decision, which is worth having, but the retry cost (#777) is untouched by it.