fix(loop): save stranded work to a branch before any edge removes it (#405, #400)

[mabry1985]

Fixes #405. Fixes #400. #400's own root cause needed correcting, and the correction is below.

What was wrong

1. Stranded work was destroyed (#405). When a coder dies before its candidate is promoted, the only copy of its work is left in that worktree. Every automatic edge that could reach that tree deleted it:

Edge	What it did
re-dispatch → create_worktree	ran git worktree remove --force + git branch -D on the exact path the next build reuses
promote_worktree	force-cleared a stale canonical tree before moving the winner in
reap_feature_worktree (merge, closed PR, cancel, done, health sweep)	force-removed the canonical and every candidate
stop()	force-removed the in-flight tree, including a finished implementation waiting on its gate

2. The brief contradicted itself at the publish step (#400). It said both "You cannot run shell commands (edit-only)" and "Push the branch if you can".

3. The board committed its own node_modules symlink into PRs. create_worktree links the main checkout's node_modules into every tree. Most repos ignore it as node_modules/, with a trailing slash, and that pattern matches only a real directory, not a symlink. So stage_all's add -A staged the link and it rode into the PR.

Evidence (bd-ezs7, protoEngineer, 2026-09-06). From the log and board DB, read-only:

• 23:25:50: codex reports turn complete (stopReason=end_turn); the coder-monitor: comment records elapsed_s: 480.7.
• After that: no .g2, no verified, no exhausted, and no exception. The drive task stayed alive: at 00:15 the claim scan skips bd-ezs7 as hot-file overlapping itself.
• The installed plugin was d105175. Its acceptance-test timeout killed only /bin/sh and then did an unbounded await proc.wait(). That is the hang bug: gate/test subprocesses inherit the server's stdin and are killed shell-only — a hung pnpm strands drives for hours and leaks orphans #423 fixed.
• 07:15 UTC: the PM requeued the card. The 170 lines survived only because the hung drive still held the file claim. A re-dispatch would have force-removed them.

#400's root cause, corrected:

• The coder was never meant to publish. The board commits, pushes and opens the PR itself (open_pr).
• Nothing was published because the drive hung. bug: gate/test subprocesses inherit the server's stdin and are killed shell-only — a hung pnpm strands drives for hours and leaks orphans #423 already fixed that (08ed8e2, v0.54.0; test_a_timed_out_acceptance_test_returns_instead_of_hanging_the_drive).
• What A coder can complete with real edits and publish nothing — no commit, no branch, no PR, no failure recorded #400 still had right: the brief's push instruction contradicted the edit-only contract, and the stranded tree could have been silently destroyed. This PR fixes both.

The fix

Save to a branch, then proceed (worktree.preserve_worktree).

• Target: before any edge removes a tree holding work that exists nowhere else, its work goes onto a new branch, stranded/<tree id>/<UTC stamp>.
• What the commit holds: the tree's HEAD plus its working state. It is staged through stage_all into a private GIT_INDEX_FILE, so the tree, its index and its branch are untouched. commit-tree is used so no hooks run; there is no signing prompt, and the identity is pinned.
• No overwrite: update-ref <ref> <commit> "" refuses to overwrite an existing branch.
• Verified: the branch's tree is read back and compared before the tree may go.

What counts as work (worktree.unpublished_work):

• every uncommitted change: modified, staged, deleted, untracked;
• on a candidate branch, also commits that no other ref holds. For those, the branch points at the tree's HEAD.
• Not counted: .proto/.cursor scratch and the board's node_modules links.

Edge	Now
fresh build (_drive)	first discards its own previous attempt explicitly, as retries always did. Then saves every stranded tree the card owns, removes them, and posts a card comment: each branch, its diffstat, git diff origin/<base>...stranded/…, and how to cherry-pick it. Then it builds on.
shutdown	saves the tree, comments on the card, reaps it. The next boot rebuilds as before, so no toil on a plugin roll.
by-id reap	saves the tree, logs the branch, reaps it
create_worktree / promote_worktree	save the tree, then clear it. This backstops callers other than the drive.

Block only when saving fails. If the commit or branch step fails, the tree is kept exactly as it is: work that could not be saved is never destroyed. What happens next depends on the edge:

• a fresh build blocks the card as stranded-work, a class that does not self-heal. The reason names the path, what the tree holds, why saving failed, and how to recover or discard it.
• the reap keeps the tree and logs it once.
• shutdown keeps the tree, and the next dispatch retries.
• create_worktree / promote_worktree raise StrandedWorkError.

Other changes:

• stage_all excludes untracked, un-ignored node_modules symlinks, alongside CODER_SCRATCH.
• The brief now says: edit-only; do NOT commit or push. The loop commits what you left, runs the pre-PR checks and pushes. Do NOT open a PR. The existing open_pr adopts a coder-made DRAFT PR as-is, and the auto-merge blockers never check isDraft — a draft burns auto_merge_max and parks the card #207 wording and test still hold.
• Max-Mode's losers are the drive's own judged candidates, so they are now discarded by path, like the solve ladder's. Two store.reaps assertions in tests/test_loop.py now read store.removes.

Tests

tests/test_stranded_work_405.py runs real git against a bare origin + clone. tests/test_brief_publication_400.py checks the brief.

• A re-dispatch saves tracked / staged / untracked work (parametrized) as one commit on the tree's HEAD, then rebuilds fresh. A candidate commit is kept as the branch tip.
• The board's droppings are neither work nor saved, even alongside real work.
• An existing stranded/… branch is never overwritten. If saving fails, the tree is kept and the call refuses; once the branch is freed it saves and proceeds (the recovery path).
• Promotion saves a stranded canonical tree, then promotes.
• The reap saves the dirty candidate and still reaps everything.
• commit_worktree no longer carries the node_modules link under a node_modules/ ignore.
• The drive saves stranded work, comments where it went (branch, diffstat, diff command), and builds on. It blocks as stranded-work only when saving fails, with no coder dispatched.
• Shutdown saves the interrupted tree, comments, and reaps it; a clean tree is reaped as before.
• The brief no longer hands the coder a publishing step, and says the loop publishes.

Red-check: I ran the final two test files against a pristine git archive origin/main. 14 of 15 fail, each on the defect itself: "the untracked change was destroyed, not saved", "the coder's commit was dropped with its branch", "unsaved work was destroyed", "the commit carried the board's link: ['feature.py', 'node_modules']", "the drive built over stranded work without saving it", "shutdown reaped an in-flight tree holding work without saving it", "the brief still asks the coder to push".

The 15th, test_a_drive_still_discards_its_own_failed_attempt, is a labelled regression guard. It passes on main by construction. With the drive's own-attempt discard removed, it fails: the drive saves and comments on its own leftovers.

unpublished_work and preserve_worktree are new local-git seams. Both are registered REAL in tests/test_external_seams.py, taking the contract from 23 to 25 REAL; the README is updated to match.

Gates: ruff format --check . ✓ · ruff check . ✓ · pytest -q → 1918 passed, 13 skipped (exit 0).

Notes

• stranded/* branches accumulate: one per saved tree. They are listed in the card comment; clear them with git branch --list 'stranded/*' / git branch -D.
• feat(board): salvage an existing worktree without a coder — gate, commit, push and PR it for a stranded card #427 (publish a stranded tree without a coder) follows as a separate PR. It can reuse stranded_worktrees() / preserve_worktree().

Review round (2f3c8ea): the gaps adversarial review found

An adversarial review found that "every edge that removes a tree holding unpublished work saves it first" did not hold yet. Each gap is now closed, with a real-git test:

#	Gap	Fix
1	Committed-but-unpushed work on the card's own branch was destroyed. This covers the verified candidate coder_seam commits before open_pr pushes it: a plugin roll or a failed push lost it.	Every branch counts: commits held by HEAD and its branch and by no other ref. Content already published doesn't count: if git merge-tree --write-tree into origin/<branch>, origin/<base> or origin/HEAD would change nothing, the commits are published. So rebased and squash-merged history never reads as stranded. Auto-merge now reaps before deleting the PR branch, while that tracking ref still proves it.
2	Cancel removed the tree unsaved, and raced the route's save-first reap.	Every removal goes through one save-then-remove (discard_worktree), locked per tree path. Two edges hitting one tree get one save and one removal.
3	Our own naming caused failed saves. The ref dropped the slug and was stamped to the second, so saves collided about 5 times in 10.	stranded/<tree dir>/<UTC ms>, retried with a -2… suffix on a taken name, never an overwrite.
4	A saved tree that git wouldn't remove was reported removed, re-saved on every sweep, then blocked as "could not be saved". Husks were kept forever.	After a verified save the tree is deleted anyway (never a locked one), and reports say truthfully whether it went. A husk is moved aside to .worktrees/.stranded/, bytes intact, with its branch's commits saved. The discard command works on a husk.
5	Detached-HEAD commits were lost.	HEAD is counted and saved. The branch tip becomes a second parent when HEAD has moved off it.
6	A fresh build swept the operator's live test-rung tree.	Card sweeps skip feat-<id>.test*; the test-rung diagnostic reaps its own trees.
7	A nested git repo was half-saved (only a gitlink) and its files deleted.	That tree is refused and kept whole. At a fresh build the card blocks as stranded-work with a clear reason.
8	A terminal block (for example, a PAT push rejected for workflow scope) removed the finished, committed tree.	Drive-side block and cancel removals save first.

Docs: saves run with hooks off (-c core.hooksPath=/dev/null, since update-ref fires reference-transaction); this is tested with a rejecting hook. The brief only promises pre-PR checks when local_gate_cmd is set. The _promote_adopted_draft docstring and the changelog now match what the code does.

Red-check: the new/changed tests were run against a pristine git archive of the prior PR head dd4c684. 26 fail, including:

• "the card branch's unpushed commit is gone"
• "the detached HEAD's commit was lost with its tree"
• blocking contains "reference already exists"
• "the saved tree was never removed"
• "the husk still blocks its path"
• the nested repo's files deleted (FileNotFoundError)
• the test-rung tree swept
• the rejecting hook failing the save
• "the blocked card's finished commit was lost with its tree"
• the operator cancel leaving no stranded/ branch
• "the brief promised a check no gate will run"

Five pass there. Three are labelled regression guards, each proven by mutation to fail without its fix:

• published history is not stranded work: fails with the content check disabled;
• the drive discards its own failed attempt: fails without the own-attempt discard;
• an auto-merged card is reaped before its branch goes: fails without reap-before-delete.

The other two (the node_modules link commit, and the brief's push line) were already fixed in dd4c684 and red-checked against origin/main earlier.

Gates: ruff format --check . ✓ · ruff check . ✓ · pytest -q → 1934 passed, 13 skipped (exit 0). Seam registry: 27 REAL (preserve_worktree, _tree_status, _unique_commits, _create_stranded_ref; unpublished_work now reads through them).

Merged main (#430, #437), 2026-09-10. The only conflict was the worktree seam contract: main's #402 made pr_identity REAL, so with #405's four stranded-work seams it is now 28 REAL / 3 EXEMPT / 0 UNCOVERED, and the README says so. #437 adds no worktree removal, so save-before-remove still covers every edge. Gates after the merge: ruff format --check . ✓ · ruff check . ✓ · pytest -q → 2072 passed, 16 skipped (exit 0).

Merged main again (#431, #438, #436, #433), 2026-09-11. #436 overlaps this PR by design, not just textually. A drive whose card is moved on under it (held, done, requeued, cancelled) stands aside. It blocks nothing, and a held or done card gets no PR, so the finished work stays unpushed in its tree. The combined contract:

• Every drive-side block takes fix(loop): a card moved under its drive is not blocked at the hand-off (#398) #436's gate (_block_or_stand_aside). The removal after a real block is this PR's save-then-remove (_discard_tree), never a bare remove_worktree. That is how all six conflicting sites are resolved, and the stranded-work block goes through the gate too.
• A build that stood aside has let go of its tree, so shutdown leaves it alone. The by-id reap and the card's next fresh build save its work to stranded/… before removing it. No stand-aside path blocks or overwrites the card.
• New fix: a retry that rebuilds removes the drive's own failed attempt unsaved (by design). But fix(loop): a card moved under its drive is not blocked at the hand-off (#398) #436's ownership check ran before the retry's prompt was built, which includes a KG fetch. A hold landing in that window lost the tree. The drive now re-reads the card right before that removal.

tests/test_moved_build_tree_405.py (real git, real br):

• a card held mid-build → the build stands aside with no PR → shutdown leaves the tree → the reap saves it to stranded/… → the card keeps the human's state, reason and class, with no PR;
• the hold is lifted → the next round's clean-up saves the first round's work before building fresh;
• a hold landing while a retry is prepared keeps the failed attempt's tree.

Red-check: the first two fail on main (nothing is saved) and on this PR's previous head d302afb (the held card gets a PR). The third fails with the re-read reverted: the retry is dispatched on the held card.

Seam ratchet, recomputed from the scanner: worktree.py 31 = 28 REAL / 3 EXEMPT / 0 UNCOVERED; store.py 49 = 33 REAL / 16 UNCOVERED (= MAX_UNCOVERED_STORE).

Gates: ruff format --check . ✓ · ruff check . ✓ · pytest -q → 2173 passed, 16 skipped (exit 0).

🤖 Generated with Claude Code

https://claude.ai/code/session_01F2V6GRejF7mNukAoYjj2Av

[protoreview]

⚠️ QA panel exhausted — this PR has not been reviewed.
The review panel failed after 2 attempt(s) on head 44d435c205f3. No verdict was posted.
A new push will re-trigger the review.

[protoreview]

⚠️ QA panel exhausted — this PR has not been reviewed.
The review panel failed after 2 attempt(s) on head d302afbe9176. No verdict was posted.
A new push will re-trigger the review.