fix(loop): a timed-out card is parked for its split, and the ask is dispatched (#378)

[mabry1985]

Fixes #378. #379 and #380 did most of it; this closes the three gaps they left, plus five defects an adversarial review found in this PR's first cut.

What was still wrong on main

#379 capped large in the breadth gate. #380 made a repeated CoderTimeout ask the board's own agent to split the card. I reproduced each of the following on origin/main:

1. The ask was never picked up. request_decomposition files its task through create_feature, which puts every bead in backlog. The puller's queue is br ready --label ready, so the A task assigned to the agent itself should be dispatched to it, not parked forever #311 self-dispatch path never saw it. On real br 0.2.16 the task sat backlog and was absent from ready_queue().
2. The ask waited for the ladder to run out. On smart → reasoning → opus a card timed out three times (dispatched a, b, c, asked timeouts=3) before anything asked for a split.
3. The card was then rebuilt anyway. The block beside the ask was the self-healing transient. The sweep requeued the card it had just asked to split and rebuilt it whole, up to 2 more full timeouts.

Defects the review found in the first cut (each reproduced, R1–R5)

• R1: an infra (pre-first-token) timeout was counted. After the operator fixed the infra, the card's first genuine timeout parked it. (The fix(loop): adapter chatter is not evidence the model ran (#422) #428 review independently confirmed this one.)
• R2: a fix-round timeout on a card that had already built was parked. The split's cancel would have closed its open PR, and the count never reset after a successful build.
• R5: the re-park reason lied, and unblocking gave no real retry. A re-park that filed nothing still said "parked for a split", and after an unblock the count was still at the threshold.
• R3/R4: the task's steps were unexecutable. Slices marked ready while the parked card still claimed their files were refused by the shared-file gate (R3). Cancelling the card released its dependents before any slice had landed (R4).
• Plausible, also fixed: a lost decompose-asked label write could leave an orphan task and file a duplicate at the next park.

The fix

What counts (drive, new step 1.7, after the pre-model block and before the climb):

• A CoderTimeout counts only on a fresh build that reached the model. An infra timeout is blocked by loop: an infra dispatch failure climbs the model ladder and leaves the card pinned at the top tier #339 above it and never counts. A fix round (a kept worktree, or a card whose PR is open) takes the ordinary timeout path, because a card that built in one dispatch is not too wide.
• The count is durable (a budget: label) and clears when a build reaches review.

The park, in the one safe order (_park_for_split):

1. File the decompose task. request_decomposition leaves it in backlog, invisible to the puller.
2. Park the card under its own class too-wide. The sweep never re-runs it and the operator is told once. The reason is built from what step 1 returned: it names the task, or says plainly that none was filed and what to do.
3. Release the task to ready. The agent that picks it up ends by cancelling this card, so the card must already be parked.

Operator reset:

• clear_blocked on a too-wide park also drops the budget:timeout label.
• The unblock tool and the /unblock route drop the running loop's cached count (loop.forget_timeout_count), since that cache wins over the label (F5: every fix budget lives in memory, so a restart refunds them all #259).
• So a retry after raising coder_timeout_s is a real attempt. Other blocks keep their count, so the sweep's self-heal can't reset it.

The split's own steps. The spec lists the card's dependents and orders the work so each step passes the gates the next one relies on:

1. Create the slices and leave them in backlog.
2. Re-point every dependent onto the slice(s) it needs.
3. Cancel the card.
4. Mark the slices ready.

Idempotent on the task. A repeat ask finds the task already filed for the card (by its title), heals a lost label, and returns the open task so the re-park can name and release it. It returns None once that split has closed.

A pre-first-token timeout still blocks as dispatch-infra (#339). 0 still switches all of this off. The docs and manifest are updated, and "never for a pre-first-token timeout" now holds for the count as well as the ask.

Tests (tests/test_timeout_decompose_378.py, plus two adjusted existing tests)

• drive: 3-rung ladder → a, b, one climb, then park too-wide naming the task. The order is ask < park < release.
• drive → sweep: a parked card is not requeued, and the operator is told once with the task id.
• drive: a re-park that files nothing says NO split task was filed, what to do, and releases nothing.
• drive: an infra timeout is never counted; the next genuine one counts 1 and is not parked.
• drive: a fix round on a card with an open PR is never parked and never counted, and climbs as usual.
• drive: a keep-worktree fix round that times out is not counted.
• drive: a build that reaches review clears the count.
• drive: after an operator unblock (store reset + forget_timeout_count), the retry's first timeout is not re-parked.
• store: clear_blocked resets the count only for a too-wide park. The ask files in backlog (never releases itself), lists dependents, and gives the steps in the safe order. It is idempotent on the task: it heals a lost label, returns an open task, and returns None once that split has closed.
• real br:
  • the drive parks a real card naming its split; the split is ready, in the queue, and self-dispatched to the board's own agent with its assignee intact (R6's check, folded in);
  • the split's steps executed in order pass every gate, the dependent is not released early, and it is released once the slices land. The wrong order is shown to be refused by the shared-file gate.
  • a lost label write cannot file a duplicate;
  • an unblock resets a real parked card's count.

Two existing tests change:

• test_the_timeout_counter_survives_a_restart used a pre-first-token timeout, which no longer counts, so it now records model work first.
• The feat: a repeated coder timeout asks the agent to split the card #380 integration test now expects a repeat ask to return the same open task rather than None.

Red-checks: all 15 new tests fail against this PR's previous head. The reviewer's reproducers pass on that head and, on this one, R1, R2 and R5 now fail as intended. R3 and R6 fail by premise, because the store's ask now comes out in backlog and the drive releases it; the real-br tests above cover both properties end to end. R4 pins a raw br fact (a cancel releases dependents), which the new step order handles.

Mutation checks (13, all caught):

• counting infra timeouts;
• parking a fix round with an open PR;
• parking a keep-worktree round;
• no count reset at review;
• a reason that always claims a split;
• releasing before parking;
• an unblock that keeps the count;
• a no-op forget_timeout_count;
• an ask that promotes itself;
• label-only idempotency;
• a spec that cancels before re-pointing;
• plus the earlier threshold and park-class mutations.

Gates: ruff format --check, ruff check, full suite 1918 passed / 13 skipped.

Intended behaviour (not gaps)

• architectural stays uncapped in the breadth gate. That was the fix: cap large in the breadth gate — the design gate is not a size gate #379 decision: it's decision-shaped and should spawn children.
• A slice that itself times out twice gets its own decompose ask. The store's recursion guard covers the decompose task; a slice is an ordinary card. Each split narrows the card, so this is bounded, and the operator is told at every park.
• Max-mode timeouts: fix(loop): max-mode hands the drive the failure that killed every candidate (#425) #429 hands the drive a CoderTimeout when every candidate timed out, so they reach this counter too once both are merged. The drive-level test of that combination lives in fix(loop): max-mode hands the drive the failure that killed every candidate (#425) #429's tests/test_max_mode_provider_425.py. It skips, naming this PR, until the park is on its base.

🤖 Generated with Claude Code

https://claude.ai/code/session_01F2V6GRejF7mNukAoYjj2Av

[protoreview]

QA panel review — PASS

code-review-structural · head 92eec5483efb · formal

⚠️ PR advanced 1 commit(s) during this round (92eec5483efb → a0a344bc2cf2); 0 finding(s) in the delta were demoted to possibly addressed.

This review is a total panel failure, not a clean pass. All finders timed out or hit a gateway error, and the verifier confirmed there were no findings to verify because the panel never produced any. The empty array below reflects infrastructure failure, not an absence of defects. Do not rely on this result for merge decisions — re-run the review workflow (or at minimum the structural pass, which was also skipped) before treating PR #435 as reviewed. No prior requests exist, so no dispositions are owed.

No findings — the review came back clean.

findings JSON (machine-readable)

[]

---

4 panel step(s) hit their time budget and were skipped this round: find_correctness, find_removed_behavior, find_crossfile, find_conventions. The verdict stands on the remaining angles; a finding only that step would have caught could be missed — the next push re-runs the full panel.

[protoreview]

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