feat(board): salvage a stranded card's worktree without a coder (#427)

[mabry1985]

Fixes #427.

Stacked on #434 (base fix/publish-reap-400-405). The salvage relies on three things #434 adds:

• the stage_all fix, so a salvage commit can't carry the board's node_modules link;
• promote_worktree's save-before-clear;
• the tree enumeration and per-path tree lock that feature_worktrees and hold_trees sit on.

Merge #434 first. ⚠ Retarget this PR to main before #434's branch is deleted: deleting a stacked PR's base branch can close the child instead of retargeting it.

What was missing

When a card's worktree already held finished work, the only way to publish it was to dispatch a coder, because every publication step (gate, commit, push, PR) sat behind a dispatch. On 2026-09-07 bd-ezs7's recovery stalled exactly there. The finished 170 lines were stranded in feat-bd-ezs7.g1, and the coder delegate was down for an unrelated reason: protoCLI under Node v26 failed every model call.

What this adds

board_salvage_feature(feature_id, force=False, tree="") and POST /features/{fid}/salvage ({force?, tree?}). They run the board's own publishing steps with no coder in the path. The crash salvage (_salvage_verified_candidate) now shares its two halves: _gate_tree (fixups + gate) and _open_tree_pr.

It is an operator override: it skips the drive's goal, requirement-ledger and source-issue checks. CI still applies, and so does the review gate when it is on.

1. Refuses, changing nothing:

   • while a live drive or another salvage owns the card;
   • for a card that isn't stranded. Only in_progress with no drive, or blocked, qualifies; a ready card could be claimed mid-publish, so the operator blocks it first;
   • when no worktree of the card has changes vs base, or several do and tree doesn't pick one.

2. Every tree is proven first. worktree.own_worktree checks that the tree is its own top level and that the repo registered it. A leftover with no .git, a husk, or a separate clone under the card's tree name is left untouched and named in the refusal.

3. The gate runs where the tree stands. format_cmd fixups run first, as in a drive, so they may rewrite files even when the gate then refuses. A red gate publishes nothing and returns gate-red with the output's tail.

4. force=true on a red gate:

   • a new PR opens as a draft carrying the output;
   • an existing PR is converted (gh pr ready --undo) and the output is posted on it as a comment;
   • draft in the record is read back from GitHub. A refused conversion is reported as "NOT a draft";
   • in a repo without drafts nothing is opened, and the error names the branch already pushed, plus the gh pr create command.

   The output is fenced with more backticks than it contains.

5. Publish, then review. A candidate tree is promoted to the card's canonical branch, then committed, pushed and opened (or pushed onto the card's PR). Under the claim lock, the card goes to in_review:

   • a card parked in_progress goes through open_review;
   • a card blocked out of in_review (CI-fix rounds spent, or a review-gate block) goes straight back there, on its own PR.

   With review_gate on, the salvage runs the gate inline, as a drive does. The reconcile only picks up review-pending when merge_poll is on.

6. A cancel mid-publish stops it before the PR, or closes the PR it has just opened (cancelled, 409). The salvage holds its trees (hold_trees, reentrant for its own promotion), so the cancel's reap waits, then saves and removes the tree as usual.

7. The reservation. The card is reserved in _inflight_files, the same claim a drive holds, and only the salvage that made it releases it (identity check). The claim scan (reserved, not counted as a livelock), boot recovery, the orphan sweep, the blocked sweep and the worktree sweep all skip a reserved card. feat(board): attach an externally opened PR to the card it belongs to (#402) #437's claim-guarded re-reads treat a card reserved during their gh round-trip as owned.

HTTP status by outcome: published 200 · gate-red / refused / cancelled 409 · not-found 404 · loop-not-running 503 · error 502. The record carries branch. The route is on the bearer-gated operator surface. It and the tool reach the running loop through request_salvage, as board_dispatch does.

docs/lifecycle.md also states the hung-drive limitation. The salvage refuses while a drive owns the card, and no verb stops a drive on its own. Cancelling the card or restarting the host saves the tree to a stranded/… branch and removes it, so that branch then has to be published by hand.

Review round

An adversarial review found seven defects. All are fixed, each with a test.

#	Finding	Fix
6	A leftover feat-… dir with no .git let git answer for the main checkout: the salvage counted the operator's own commit as the card's work and committed onto the operator's branch	own_worktree guard on every tree; commits_ahead refuses non-trees
1	force on a card with an open PR adopted the READY PR and reported "draft"	convert + comment + read back; fake gh models "already exists"
2	A card blocked out of in_review failed open_review's precondition after its block was cleared	returns to in_review on its PR
3	review_gate on + merge_poll off: nothing ever reviewed a salvaged PR	inline review gate
4	A cancel during the publish still opened a PR, and its reap could remove the tree mid-gate	cancel checked before and after the PR; trees held
5	The claim scan and boot recovery ignored the reservation, and the salvage released another holder's claim	both skip; release by identity
—	Fence escape; repos without drafts; docs gaps	fixed / reported truthfully / documented

#437 overlaps, resolved in the merge: #437's _tools() docs guard verbatim; #437's board_dispatch row (⚠️, after board_deliver), so this PR's duplicate is dropped; __all__ exports both attach_external_pr and request_salvage; the worktree seam contract is 30 REAL / 3 EXEMPT / 0 UNCOVERED; board_salvage_feature joins the async-aware never-raise sweep.

Tests

tests/test_salvage_427.py has 27 tests:

• real git: a bare origin + clone, with a real commit and push;
• a real br board, so every card transition is the store's own;
• only _gh faked. It models pr create "already exists", repos without drafts, pr ready --undo, pr close, pr view state/isDraft, and the comments API.

Red-check (the final test file run against pristine git archive exports):

• vs d302afb (fix(loop): save stranded work to a branch before any edge removes it (#405, #400) #434's head, no salvage): 26/26 fail.
• vs 6ea90ee (this PR before the review round): 16 fail, one per new or changed behaviour. 10 pass: the unchanged behaviour, plus the blocked-sweep skip, which already existed.

Mutation-checked on the fixed code. Reverting each guard fails its test:

• inline review gate
• hold_trees
• the pre-PR and post-PR cancel checks
• --undo
• draft read-back
• own_worktree filter ("committed into another repo")
• fence width
• blocked-sweep skip
• the three reservation-window re-reads

Gates: ruff format --check . ✓ · ruff check . ✓ · pytest -q → 2201 passed, 16 skipped (exit 0), on main through #433.

Later merges (main #431, #438, #436 and #433, via #434):

• fix(loop): a card moved under its drive is not blocked at the hand-off (#398) #436's requeue refusal and feat(board): attach an externally opened PR to the card it belongs to (#402) #437's attach both read _inflight_files, so neither can move a card that is being salvaged.
• A build that stands aside from a held card (Shared-file gate lands a dependent card in terminal-blocked with an empty reason, and leaves dag_blocked false #398) leaves exactly what the salvage publishes. A new end-to-end test (tests/test_moved_build_tree_405.py, real git and real br) holds a card mid-build, and then the salvage publishes the finished tree as it stands.
• fix(loop): a stalled br call costs one read, not the whole tick (#404) #431 makes a stalled br read raise. The salvage now turns that into an error record, and still releases its reservation, where it used to raise into the route as a 500. The test fails without it.
• Seam ratchet, recomputed from the scanner: worktree.py 33 = 30 REAL / 3 EXEMPT / 0 UNCOVERED; store.py 49 = 33 REAL / 16 UNCOVERED.

Residual risk

• In a repo without draft PRs, force onto an existing PR leaves it ready. The record, the card comment and the PR comment all say so, and CI plus the review gate still stand between it and a merge.
• The real-br tests run on br 0.2.16 locally. CI's full-suite leg uses br 0.1.23.

🤖 Generated with Claude Code

https://claude.ai/code/session_01F2V6GRejF7mNukAoYjj2Av

[protoreview]

QA panel review — PASS

code-review-structural · head df542732f6ca · formal

⚠️ PR advanced 2 commit(s) during this round (df542732f6ca → 62f12192563a); 0 finding(s) in the delta were demoted to possibly addressed.

All four review angles (correctness, removed-behavior, conventions, and the partial structural pass) returned zero findings, and the verifier confirmed the empty array stands as-is. Overall risk is low; there is nothing to fix first. The panel did not disagree on any point. The one coverage gap worth noting: the structural pass was only partial, so dependency-graph and cross-module concerns may not be fully exercised — if the diff touches shared interfaces or public APIs, a targeted follow-up on those seams is advisable.

No findings — the review came back clean.

findings JSON (machine-readable)

[]