fix(loop): a card moved under its drive is not blocked at the hand-off (#398)

[mabry1985]

Fixes #398. #416 (already on main) fixed half of it, this PR fixes the remaining live defect, and the issue's stated root cause turned out to be wrong. Evidence for each symptom is below.

What the three terminal cards actually were

I read the board's own record for each card (~/.protoagent/protoEngineer-ba4c/.beads/issues.jsonl, read-only) against the timeline in the issue.

card	what put it in blocked	the reason it had	why the board showed ''
bd-6agq	the PM agent, via board_block_feature, after mark_ready was refused	Board shared-file gate prevents concurrent readiness with #3360a … Unblock and mark ready after bd-ezs7 merges (06:17:54Z)	br list omits comments. Fixed by #416
bd-w535	the PM agent, a deliberate hold, re-blocked daily	five blocked: comments, each with a reason	same, #416
bd-p8ft	the loop's drive, at the review hand-off	open_review expects in_progress, got 'ready' (07:12:30Z)	same, #416. The block itself is the defect fixed here

The shared-file gate never blocks a card. It raises from mark_ready and the card stays in backlog. It also never refused bd-6agq for colliding with its own dependency. Pairs linked by depends_on in either direction have been exempt since v0.37.0 (#159, test_shared_file_gate_passes_with_a_depends_on_edge). It refused bd-6agq because of bd-ezs7 (#3360a), an unrelated card sharing plugins/delegates/adapters.py with no edge between them. The operator had asked for no edge there. That is the case the issue itself calls "a real conflict a human should resolve". dag_blocked: false is also correct by construction: dag_blocked means ready but waiting on an open blocker, and a card flagged blocked is not in the ready lane.

The empty blocked_reason was #414, fixed by #416. The listing now carries the comment thread for blocked rows, and flag_blocked refuses a terminal block that has no reason.

The live defect: bd-p8ft

agent.log and the bead comments give this sequence. The loop's own CI-fix round (attempt 2/2) claimed bd-p8ft at 07:02:31 and started building it (in_progress, PR #3364 attached). At 07:05:38 the PM called board_requeue_ci_fix. The tool accepted, because a card mid-round has the same in_progress + open PR shape as a card parked by a CI bounce. The requeue moved the card to ready. The next ticks skipped it as hot-file, overlapping bd-ezs7 and bd-p8ft itself, i.e. its own live drive. At 07:12:30 the round finished, open_review refused expects in_progress, got 'ready', and the drive's catch-all flag_blocked(str(exc)) classified that as terminal.

That is the "hold that became permanent on its own" described in the issue.

The fix (reworked after adversarial review, commit 527bf99)

The first cut respected a move only at the review hand-off. Review found five defects: a first build requeued mid-round lost its work, because the PR went unrecorded and the next round ran resume=False and force-pushed over it; every other build-end path still blocked over a move; a held or done card still got a PR; the trail comment could throw into a re-block; and an unreadable card counted as still owned. The rework:

A drive owns its card only while it is in_progress, and asks before every edge that would change it. It re-reads the card before starting another attempt, before publishing, after publishing, at the hand-off, and at every block site. All eight block sites now go through _block_or_stand_aside. A drive that has lost its card stands aside (_stand_aside):

• it does not block, retry or send the card to review; a failure it hit is recorded in the trail comment instead;
• if it opened a PR, it records the PR on the card with the state untouched (new store.record_pr_url), so the next round runs resume=True on that branch;
• it keeps the worktree: a held, done or elsewhere-reviewed card gets no PR, and the work stays unpushed where it is (compatible with fix(loop): save stranded work to a branch before any edge removes it (#405, #400) #434: nothing is destroyed, and fix(loop): save stranded work to a branch before any edge removes it (#405, #400) #434's set-aside saves such a tree if a later build runs);
• it resets the drive's fix budgets, so the next round starts fresh;
• it leaves one best-effort comment. A cancel still takes the Cancel during a coder run still opens the PR — then open_review refuses it, leaving an orphaned red PR nobody owns #211 edge, which closes the PR.

It fails toward not overwriting. An unreadable card is never assumed to be the drive's own. A refused hand-off names the state it found (expects in_progress, got 'ready'), and that is used. With nothing to go on the answer is unknown: the drive stands aside, and the sweep reconciles a card left in_progress with no drive.

The trigger is closed. board_requeue_feature, board_requeue_ci_fix, POST …/ci and POST …/review refuse a card the loop is still working. That check uses worked_by_the_loop: a live drive, a claimed build or a running review gate, the same three signals #437's attach uses. The message says to wait for the round or cancel the card.

Merged with main (latest: 113a190, which includes #431). #435 moved the #378 decomposition ask into _park_for_split, which blocks the card as too-wide. That park now asks first like every other drive-side block, so a held card isn't re-blocked or given a split task (new test, red without the guard). Task drives follow the same rule (6ff0e71). #432's _task_dispatch_failed exempted only a delivered card. A re-read that failed still blocked, and a human hold placed mid-dispatch was blocked over. It now blocks only a card still in_progress. An unreadable card is logged and left for the sweep, and any other move stands (tests/test_task_drive_ownership_398.py; against main 81a9787 the unreadable and hold tests fail, and the in-flight pin passes). A store-level race between the drive's own open_review read and its write (reviewer's R6) is now reachable only by a direct in-process store.requeue while the drive lives, which no external edge can issue any more.

Tests: tests/test_requeue_under_drive_398.py (real br)

• The requeue verbs and routes refuse a card under a live round, move nothing and queue nothing; after the round ends the guard lifts.
• A first build moved to ready: the PR is recorded, the card stays unblocked, and the next claim carries the PR (so resume=True).
• Held mid-round: no PR, the hold kept, the worktree kept. Marked done mid-round: no PR.
• A requeued card whose round then fails to publish is not blocked.
• A held card with a transient error: 1 dispatch (not 3), the hold intact, and the sweep leaves it alone.
• The stand-aside comment failing never becomes a block. An unreadable card after a refusal is read from the refusal.
• The drive's fix budgets are reset. A refusal while the card is still in_progress still blocks.
• record_pr_url on ready/blocked/done cards through real br (classified REAL in the seam registry).
• _moved_under_drive's fail-toward-not-overwriting table.

Red-check: the new file against the previous head (0a218ff): 14 failed, 1 passed. Each failure is behavioural: the requeue was accepted (state: ready), pr_url was '', a PR was opened for a held or done card, the card was blocked after the move, there were 3 dispatches, the hold was overwritten by the comment failure, and the budgets were not reset. The pass is the in-progress refusal pin, which should pass on both. The reviewer's reproducers R1, R2, R3a, R3b, R4, R5, R7 and R9 now fail, meaning the bad behaviour they asserted no longer happens. R2b (cancel contrast), R6 and R8 (pure git) still pass.

Full suite passes on br 0.2.16 and 0.1.23: 1918 passed, 13 skipped. ruff check and ruff format --check are clean. docs/lifecycle.md has a new "A card moved under its build" section, and the rows in docs/tools.md and docs/api.md are updated.

🤖 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 54650a8081f9. 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 527bf99b46c7. No verdict was posted.
A new push will re-trigger the review.