[itsmiso-ai]

What

A Courier run ending terminal NeedsHuman sends tasks/report with outcome: "blocked" (no blockReason) and then a worker-tier POST /api/pr-fix-queue/mark with status: "BLOCKED". Before this PR the report parked the item PARKED/no_progress, the follow-up BLOCKED mark was refused by the #1218 sticky status pin (worker marks pinned the current status to QUEUED), and no path ever released the reporting agent's hand-out records — the item surfaced nothing and the consumed hand-out stayed live.

Changes (all in src/lib/pr-fix-queue.ts + docs/tests):

1. PARKED → BLOCKED escalation. The sticky pin relaxes in exactly one direction: a non-operator BLOCKED settlement (worker blocked report with blockReason: human_decision, or a direct BLOCKED mark) may now land on a same-generation PARKED row, escalating it to BLOCKED/human_decision with the needs-human label + marker (existing surfacePrFixBlocked machinery folds the parked marker in place). PARKED marks stay QUEUED-only; recorded BLOCKED/FIXED/STALE rows stay sticky against worker marks; de-escalation stays operator-only via allowStickyReclassify.
2. decisionDetail is always populated on BLOCKED. When no structured decision is supplied, Dispatch synthesizes {question, evidence} from the mark/report note (fallback: item reason), bounded to MAX_EVIDENCE_LENGTH. Structured decision payloads pass through unchanged.
3. Hand-out release, fenced to the exact issuance (feat(recovery): add fenced capacity-exhaustion handoff #1256 rule, fix(pr-fix): worker-reported NeedsHuman endings should mark the item needs-human, not leave it QUEUED #1340 review). releaseAgentHandout drops the reporting agent's agentHandouts / handoutAcks / handoutReceipts entries at the settled generation when a blocked report settles the attempt — or when the settlement skips because the row already settled. When the report echoes the issued handoutToken, the release is authorized only by an exact live (agent, generation, token) receipt match (findHandoutReceipt, same matcher as the feat(recovery): add fenced capacity-exhaustion handoff #1256 capacity release): a rotated/released/unknown token releases nothing, so a stale same-generation report can never remove a newer re-issued hand-out. A report without a token keeps the (agent, generation) fallback — verified necessary: Courier main (internal/source/dispatch/client.go, reportTaskWithPR) echoes handoutToken only for capacity-exhausted reports, so requiring it unconditionally would mean Courier's NeedsHuman hand-out is never released, failing this issue's acceptance. The unfenced fallback applies only against a non-QUEUED row (where entries are inert — they gate dispatch only while QUEUED), never to a still-dispatchable row. It re-reads the row and CAS-pins the exact arrays it decided on (mirrors the feat(recovery): add fenced capacity-exhaustion handoff #1256 capacity release), retries once on a pin miss, and is best-effort. Dispatch stamps (dispatchedGeneration/dispatchedAt/attemptEvidenceWatermark) clear only when the release removes the last live hand-out; other agents' live hand-outs survive with their stamps. Tightening courier-side tracked in echo prFixItem.handoutToken in every followup-pr tasks/report, not only capacity-exhausted courier#516.

Resolves the fix-pr half of #1340. The resolve-issue half (issue → status/blocked with a populated blockedReason) is already enforced today: Courier's NeedsHuman terminal calls POST /api/issues/status with status: blocked + blockedReason, which this PR leaves untouched.

Invariants this change must keep — and every other path enforcing the same rule

• A bare blocked report without blockReason means no_progress, never a false human_decision (fix(pr-fix): separate human decisions from retry exhaustion #1218). Kept unchanged: the resolver still parks; only an explicit BLOCKED mark/report escalates, and only against same-generation PARKED.
• A recorded BLOCKED/PARKED cannot be erased/downgraded by a worker second mark (fix(pr-fix): separate human decisions from retry exhaustion #1218). Kept: PARKED marks and FIXED/STALE non-maintainer writes stay status: "QUEUED"-pinned; BLOCKED gains only PARKED in its allowed set (escalation into the stickiest state, never out). Writer: the single stickySettlementStatusFilter in markPrFixItem, applied at all six guarded writes (fast path, keys-cleared loop, sticky force, force tail, refused-FIXED, reopen). Operator reclassify stays gated on actorTier === "maintainer" + allowStickyReclassify (route-sourced, never body-forgible).
• Fresh post-dispatch evidence never silently absorbed by a settlement (PR-fix evidence that arrives mid-attempt is absorbed and never delivered to the worker #1119/fix(pr-fix): deliver post-dispatch evidence as a fresh attempt (#1119) #1124); sticky settlements absorb recorded keys (feat(pr-fix): reactivate on fresh feedback with bounded reconciliation #1253). Kept: BLOCKED escalation still passes through the keys-pinned writes; a PARKED row with fresh keys escalates via the keys-cleared/sticky-force paths and clears them (new test).
• Receipt ↔ hand-out pairing: a receipt exists exactly while its agentHandouts entry exists (feat(recovery): add fenced capacity-exhaustion handoff #1256). Kept: releaseAgentHandout filters all three arrays in one pinned write; every other writer (next-task issuance, reclaim sweep, capacity release, fresh-attempt / QUEUED / WAITING_EXTERNAL marks) still clears them together — untouched.
• Releases fence to the exact live hand-out; other agents' hand-outs at the generation survive; stamps clear only on the last live hand-out (feat(recovery): add fenced capacity-exhaustion handoff #1256). Kept by the token fence above: with a token, exact (agent, generation, token) receipt authorization (same entry parsers as the capacity release); without one, the release cannot run against a QUEUED row at all, so it can never unlock a live generation for re-dispatch. The CAS pin means a concurrent hand-out/ack/sweep makes the release a no-op instead of clobbering. A lost release race leaves entries inert — they only gate dispatch while QUEUED at that generation, and any generation change (requeue, fresh evidence) clears them.
• Requeue / fresh-evidence exits release BLOCKED two-way (needs-human label and BLOCKED marker survive when a PR-fix item leaves BLOCKED via mark or new evidence #1105/fix(pr-fix): separate human decisions from retry exhaustion #1218). Unchanged: requeuePrFixItem, mark-to-QUEUED, and cap/refusal parks still clear outcomes, retract the needs-human label, and bump the generation.
• WAITING_EXTERNAL has a single status writer (feat(pr-fix): persist authoritative evidence versions and attempt-snapshot freshness (#1249) #1276). Untouched.
• No new forge-write responsibilities for the worker. Visibility falls out of the existing BLOCKED surfacing in markPrFixItem.finishMarked only.

Local validation (head 555cb0a, cwd /workspace, clean tree)

• npx vitest run src/lib/pr-fix-queue-report.test.ts src/lib/pr-fix-queue.test.ts src/lib/pr-fix-queue-evidence.test.ts src/app/api/pr-fix-queue — 386 tests passed, 0 failed
• npx vitest run (full suite) — 202 files / 5106 tests passed, 24 skipped, 1 todo, 0 failed
• npm run typecheck — clean
• npm run lint — 0 errors (1 pre-existing warning in src/app/login/page.tsx, untouched)

Limitations: no live PostgreSQL/integration run here (unit fakes cover the queue semantics); end-to-end Courier NeedsHuman behavior is verified against misospace/courier main at fix time (internal/source/dispatch/client.go blocked-report + BLOCKED-mark sequence, and the token echo being capacity-only — hence the documented fallback + misospace/courier#516), not against a running deployment. CI is left pending for operator verification.

Review

Three review rounds, all on record:

1. One independent review pass over head bdf48ad; its findings were fixed in f81c101 (release CAS + skipped-settlement release + evidence bound + doc scope of "report or mark") and re-validated locally.
2. Primary review on head f81c101 raised one minor finding (over-indented equals/in branch in src/lib/pr-fix-queue-evidence.test.ts); the secondary review requested that exact normalization. Fixed in 7315a67 — no behavioral change.
3. AI review on head 7315a67 raised one major: the release matched only (agent, generation), so a stale same-generation report could remove a newer re-issued hand-out instead of being fenced to the issued handoutToken as fix(pr-fix): worker-reported NeedsHuman endings should mark the item needs-human, not leave it QUEUED #1340 requires. Fixed in 7a0e8e6 (+ test 555cb0a): exact-receipt fencing when the token is echoed; the non-QUEUED-gated migration fallback for token-less reports, with the Courier-side verification above and echo prFixItem.handoutToken in every followup-pr tasks/report, not only capacity-exhausted courier#516 filed to remove the need for it. Independent review pass over 7a0e8e6: approve, no blockers; its test-gap minor (fence coverage on the already-settled skip site) is covered by 555cb0a.

Closes #1340

[joryirving]

Secondary review on exact head f81c101b13525714f93dc47382b5659394f9cfe5: REQUEST CHANGES only to preserve the primary-review loop. The primary's one minor finding is legitimate: the new equals / in branch in src/lib/pr-fix-queue-evidence.test.ts is over-indented relative to the surrounding operator chain. It is cosmetic and I found no functional hard blocker, but per our review policy I am not dismissing a technically-correct primary finding just because it is a nit. Please normalize that indentation; no behavioral change requested. Exact-head CI/security/smoke/image checks are green.

[itsmiso-ai]

Addressed the review feedback on head f81c101.

Finding (primary + secondary): the new equals / in branch in src/lib/pr-fix-queue-evidence.test.ts was over-indented relative to the surrounding operator chain — cosmetic, no behavioral change requested.

Fix: 7315a67 — the equals / in / has branches in the matches helper's operator chain are now indented consistently with the not / gt / gte / lte branches below them. No test content, assertion, or behavior changed.

Local validation (cwd /workspace, tree clean at 7315a67):

• npx vitest run src/lib/pr-fix-queue-evidence.test.ts src/lib/pr-fix-queue.test.ts src/lib/pr-fix-queue-report.test.ts src/app/api/pr-fix-queue — 11 files / 383 tests passed, 0 failed
• npx vitest run (full suite) — 202 files / 5103 tests passed, 24 skipped, 1 todo, 0 failed
• npm run typecheck — clean
• npm run lint — 0 errors (1 pre-existing warning in src/app/login/page.tsx, untouched)

CI on the new head is left pending for operator verification.

[its-saffron]

AI Automated Review

Full PR review.

Analysis engine: MiniMax-M3.1-Flash (anthropic) — primary route · pr-reviewer-action v3.7.0

Findings (1 major)

Severity	Location	Finding
⚠️ Major	src/lib/pr-fix-queue.ts:3426	The release filters only by agent and generation, so a stale same-generation report can remove a newer hand-out instead of requiring the issued `handoutToken` as required by PR 1256/PR 1340.

Request changes: the new hand-out release is not fenced to the issued per-hand-out token, so the PR does not satisfy PR 1340’s explicit release contract.

• src/lib/pr-fix-queue.ts:3426 filters receipts, hand-outs, and acknowledgements only by reporting agent and generation. A stale same-generation report can therefore remove a newer/reissued hand-out for that agent instead of requiring the issued handoutToken, unlike the capacity-exhaustion release.
• PARKED → BLOCKED escalation, sticky terminal states, bare-block/no-progress handling, and synthesized decisionDetail are internally consistent in the inspected paths.
• Claims checked: 3/5 held; 2/5 hand-out claims were violated by the missing per-token fence.

Linked Issue Fit

The BLOCKED/human_decision outcome, populated decision detail, PR visibility, and PARKED escalation satisfy the fix-pr portion of PR 1340. The hand-out release does not use the issue-required same fenced per-token release. The resolve-issue status/blocked acceptance criterion and fresh-evidence requeue path were not independently re-verified because the investigation budget was exhausted.

Tool Harness Findings

The harness exhausted its 24-call budget after verifying the queue writer, report resolver, worker-identity gate, report route, hand-out parsers, and relevant callers. Uninspected paths remain unverified rather than presumed safe.

Outstanding Human Change Requests

• @​joryirving's change request (f81c101, head moved since) judged addressed at this head: src/lib/pr-fix-queue-evidence.test.ts:57-60 now aligns the `equals` and new `in` branches with the surrounding operator-chain indentation.

[itsmiso-ai]

Addressed the major AI-review finding on head 7315a67 (release not fenced to the issued per-hand-out token).

Finding (major): releaseAgentHandout filtered only by agent + generation, so a stale same-generation report could remove a newer re-issued hand-out instead of requiring the issued handoutToken (#1256/issue #1340 release contract).

Verified before fixing: the finding is valid — issue #1340 explicitly asks for "the same fenced per-token release as capacity-exhaustion settlements (#1256)". But a strict token requirement alone would silently fail the issue's own acceptance: Courier main (internal/source/dispatch/client.go, reportTaskWithPR) echoes handoutToken only for capacity-exhausted outcomes, not for blocked reports, so the reporting hand-out would never be released for NeedsHuman runs.

Fix (7a0e8e6, test 555cb0a):

• When the report echoes the issued handoutToken, the release is authorized only by an exact live (agent, generation, token) receipt match (findHandoutReceipt — same matcher as the feat(recovery): add fenced capacity-exhaustion handoff #1256 capacity release). A rotated/released/unknown token releases nothing, so a stale same-generation report can never remove a newer live hand-out.
• Token-less reports (Courier's current blocked reports) keep the (agent, generation) fallback but only against a non-QUEUED row — where entries are inert by definition (they gate dispatch only while QUEUED), so the unfenced path can never unlock a live generation for re-dispatch.
• All three call sites pass attempt.handoutToken; policy doc updated; follow-up echo prFixItem.handoutToken in every followup-pr tasks/report, not only capacity-exhausted courier#516 filed so Courier echoes the token on every followup-pr report, making the fenced path the only path.

New tests: exact-issuance release (other agent's hand-out + stamps survive), stale token refuses with zero mutation, no-token fallback skips a still-QUEUED row, and the fenced release on the already-settled skip site.

Independent review: one pass over 7a0e8e6 — approve, no blockers; its test-gap minor is closed by 555cb0a.

Local validation (cwd /workspace, tree clean at 555cb0a):

• npx vitest run src/lib/pr-fix-queue-report.test.ts src/lib/pr-fix-queue.test.ts src/lib/pr-fix-queue-evidence.test.ts src/app/api/pr-fix-queue — 386 tests passed, 0 failed
• npx vitest run (full suite) — 202 files / 5106 tests passed, 24 skipped, 1 todo, 0 failed
• npm run typecheck — clean
• npm run lint — 0 errors (1 pre-existing warning in src/app/login/page.tsx, untouched)

CI on the new head is left pending for operator verification.

[its-saffron]

AI Automated Review

Full PR review.

Analysis engine: MiniMax-M3.1-Flash (anthropic) — primary route · pr-reviewer-action v3.7.0

Partial coverage: required-check coverage is incomplete — this review did not resolve every required check and must not be read as a complete pass.

Findings (1 major)

Severity	Location	Finding
⚠️ Major	src/lib/pr-fix-queue.ts:3499	Token-less blocked reports use an unfenced agent/generation release instead of requiring the exact live per-hand-out receipt mandated by PR 1340.

Request changes: the settled hand-out release is not always fenced to the issued per-hand-out token, contrary to PR 1340’s explicit release contract.

• Major: releaseAgentHandout accepts token-less reports and falls back to releasing every matching agent/generation entry (src/lib/pr-fix-queue.ts:3499). Although restricted to non-QUEUED rows, this is not the same fenced per-token release required by issue PR 1340 and the requirement ledger; require the exact live receipt for settlement releases.
• Claims: violated 1 of 5 claims—the hand-out-release fence; the inspected escalation, decision-detail synthesis, and bare-blocked behavior otherwise held.

Linked Issue Fit

• The fix-pr BLOCKED/human_decision transition, populated decisionDetail, needs-human surfacing, and requeue behavior are implemented and covered by the changed tests.
• The release path misses the issue’s required per-token fence. The separate resolve-issue acceptance path was not independently verified in this repository.

Tool Harness Findings

• Twenty-four read-only calls verified the status-filter write sites, report authorization path, receipt matcher, CAS release, surface behavior, and relevant tests.
• The tool budget was exhausted before an exhaustive caller audit; no additional failing path was established, but the remaining unexamined callers are unverified.

Unknowns or Needs Verification

• Courier’s external report construction and resolve-issue status handling were not directly inspectable in the Dispatch repository; those paths remain unverified.

Sources: src/lib/pr-fix-queue.ts, src/app/api/agents/[agentName]/tasks/report/route.ts, src/lib/pr-fix-surfacing.ts, and the changed PR-fix queue tests.

Unaddressed required checks

The classifier marked these checks as required for this PR's risk profile, but the review does not resolve or disposition them:

• treat as high priority — verify correctness carefully

Outstanding Human Change Requests

• @​joryirving's change request (f81c101, head moved since) judged addressed at this head: The current head normalizes the `equals`/`in` operator-chain indentation at src/lib/pr-fix-queue-evidence.test.ts:58-59, matching commit 7315a67 and resolving the cosmetic request without behavioral changes.

[itsmiso-ai]

Re-verified the open AI-review major on head 555cb0a (token-less fallback at src/lib/pr-fix-queue.ts:3499) against the current source of every system it depends on, before changing anything. Conclusion: the fenced-per-token path is already in place for every report that carries a token, and a strict token requirement for the token-less case would regress #1340's own acceptance — so the non-QUEUED-gated fallback stays until misospace/courier#516 lands. Details below.

Verified against Courier main f12168a (internal/source/dispatch/client.go):

• reportTaskWithPR attaches prFixItem.handoutToken only for outcome == "capacity-exhausted" (client.go:906-907).
• A NeedsHuman fix-pr run is ResultBlocked: it sends tasks/report outcome: "blocked" with no blockReason and no handoutToken (client.go:1018), then POST /api/pr-fix-queue/mark status: "BLOCKED" also with no token (client.go:837-840).

So for Courier's actual NeedsHuman flow today the token branch (findHandoutReceipt, same matcher as the #1256 capacity release) is never the operative path — the (agent, generation) fallback is. Mandating the exact live receipt there means the reporting hand-out is never released for Courier NeedsHuman runs, which is exactly the starvation #1340 was filed to fix ("A fix-pr run ending NeedsHuman leaves its item BLOCKED/human_decision ... the reporting hand-out is released").

Why the gated fallback cannot strand or clobber a live generation (the residual concern in the finding):

• It is not unauthenticated: agentName on the report is token-derived (enforceWorkerAgentScope, bound DISPATCH_WORKER_TOKENS), so only agent A's own credential can release A's entries. Other agents' hand-outs are preserved and the stamps clear only on the last live hand-out.
• It fires only against a non-QUEUED row (if (fresh.status === "QUEUED") return;). A hand-out gates dispatch only while the item is QUEUED at that generation (agentAlreadyHanded / next-task), so removing the reporting agent's entries on an already-settled row can never unlock a live generation for re-dispatch. The clobber case the finding describes (a stale report removing a re-issued live hand-out) requires the row to be QUEUED when the release runs — which the gate refuses (covered by skips the unfenced release when a no-token blocked report loses its settlement on a QUEUED row).
• The write is CAS-pinned on the exact arrays it read and retries once; a concurrent hand-out/ack/sweep makes it a no-op rather than a clobber.

Path to the fenced-only contract: misospace/courier#516 makes Courier echo handoutToken on every followup-pr report. Once it ships, the token branch is the only path and the fallback is dead for live traffic. Removing the fallback in Dispatch before that ship would open a window where NeedsHuman hand-outs go un-released again.

@joryirving — your own change request (the over-indented equals/in branch in src/lib/pr-fix-queue-evidence.test.ts) was resolved at 7315a67 and the AI reviewer confirms it addressed at this head. The remaining item is the migration-window tradeoff above, which the bot keeps re-flagging: keeping the gated fallback (release works for current Courier now) vs. strict-token-only (correct contract, but regresses the NeedsHuman release until courier#516). Flagging for your call given #1340 asks for the release today.

Local validation (head 555cb0a, cwd /workspace, clean tree, node v24.22.0, fresh npm ci):

• npx vitest run src/lib/pr-fix-queue-report.test.ts src/lib/pr-fix-queue.test.ts src/lib/pr-fix-queue-evidence.test.ts src/app/api/pr-fix-queue — 11 files / 387 tests passed, 0 failed
• npm run typecheck — clean
• npm run lint — 0 errors (1 pre-existing warning in src/app/login/page.tsx, untouched)

No code change on this pass; CI on 555cb0a is green (Tests/Typecheck/Lint/Database integration/migrations/Coverage/Build/Docker/smoke all success) and left for operator verification.

[itsmiso-ai]

Courier: already addressed (run courier-1f3b7cd9f02f7211a2d6b5e8d318a6f1)

PR #1345 (issue #1340) is already implemented, pushed, open/non-draft at head 555cb0a (local==origin, clean tree). The only open item is a repeated AI-review CHANGES_REQUESTED (major) asking that the token-less hand-out release in src/lib/pr-fix-queue.ts:3499 require the exact per-hand-out token like #1256. Verified against current source before acting: Courier main f12168a internal/source/dispatch/client.go sends prFixItem.handoutToken ONLY for outcome=capacity-exhausted (client.go:906-907); a NeedsHuman fix-pr (ResultBlocked) sends tasks/report outcome=blocked with no token (client.go:1018) and a BLOCKED mark with no token (client.go:837-840). So a strict-token-only release would leave Courier NeedsHuman hand-outs UN-released, regressing #1340's own acceptance ('the reporting hand-out is released'). The current design fences exactly on (agent,generation,token) whenever a token is present (findHandoutReceipt, same matcher as the #1256 capacity release) and, for token-less reports, releases only a non-QUEUED (settled, inert) row, worker-identity-bound and CAS-pinned, preserving other agents' hand-outs and clearing stamps only on the last live hand-out — it cannot unlock a live QUEUED generation for re-dispatch (covered by the QUEUED-row skip test). misospace/courier#516 tracks making Courier echo the token so the fenced path becomes the only path. The assigned human reviewer (joryirving)'s only request (indentation in src/lib/pr-fix-queue-evidence.test.ts) was resolved at 7315a67 and the AI reviewer confirms it addressed at this head. Posted an evidence-backed PR comment (issuecomment 6338452875) rebutting the bot major and flagging the migration-window tradeoff for joryirving. Local validation on this exact head (fresh npm ci, node v24.22.0): targeted pr-fix suites 11 files/387 tests passed; npm run typecheck clean; npm run lint 0 errors (1 pre-existing login/page.tsx warning, untouched). CI on 555cb0a is green across all jobs. Left open for operator verification.

[its-saffron]

🔄 This PR fix item has been requeued and is active again — no human attention needed.

Note: requeue from queue page

Updated automatically by Dispatch on 2026-10-22T14:29:42.092Z

[joryirving]

Secondary re-review on exact head 555cb0acde18516613913f7e84b9c58cb1e9656d: REQUEST CHANGES for the current primary finding. It is legitimate. Issue #1340 explicitly requires releasing the reporting hand-out with the same fenced per-token release as capacity-exhaustion. releaseAgentHandout does that when handoutToken is present, but deliberately falls back to (agent, generation) on settled rows when it is absent. That fallback is bounded and avoids clobbering a still-QUEUED hand-out, but it is still not exact-issuance fencing and therefore does not satisfy the requested contract.

This is a cross-repo sequencing problem rather than a request for more local cleverness: Courier #516 is already open to echo prFixItem.handoutToken on every followup-pr report. Land that producer change, then make this settlement path require the exact live receipt (or otherwise prove an equivalent exact-issuance fence) and add the corresponding regression. Do not regress the core #1340 behavior: a NeedsHuman settlement must still move the item out of QUEUED and release its completed issuance so it cannot head-of-line block the lane.

The earlier indentation nit is fixed, and the PARKED→BLOCKED / human-decision behavior otherwise looks sound. Exact-head CI/security/smoke/image checks are green.