Ticket #71 verification — mandatory completion handoff, batched review, loop guards — 2026-11-03
Parent spec #66 (conversation surfaces and approval trust), child ticket #71 (mandatory end-of-turn handoff with batched review and loop guards). Worktree: /tmp/opencode/ensemble-worktrees/55-71-handoff, branch feat/v55-71, base 814feac (= local integration/ensemble-v5.5 tip with #67 bubbles, #68 approvals, #69 settings, #70 activity/handoff-waiting merged; no newer tip to merge).
Environment
export PATH=/home/tristan/.nvm/versions/node/v26.12.1/bin:/home/tristan/.local/bin:/usr/local/bin:/usr/bin:/bin(npm test spawns sh, so the system directories stay on PATH; the ticket brief's narrower PATH breaks npm test with spawn sh ENOENT.) node --version: v26.12.1. npm ci run (worktree had no node_modules). Observed host opencode --version: 2.2.5; pinned host types 2.2.1 for checking (declarations are not compatibility proof — see the runtime guide). Live runs use the dependency-free fake providers except test:live, which ran against the available host/model catalog with no skips.
Command results
| Exact command | Result |
|---|---|
npm run check | Exit 0; strict no-emit TypeScript check. |
npm test | Exit 0; 351 passed, 0 failed, 0 skipped (includes 8 new completion-handoff.test.ts + 6 new completion-batch-service.test.ts). |
npm run test:live:fake | Exit 0; fake live-check passed; ticket #71 block green (both non-leader turns handed to the leader, ticket #71 completion handoff and batch review verified live). One transient pre-existing flake observed on a re-run (link text rich-fixture timing, untouched by this ticket); the recorded run is clean. |
npm run test:live:fake:empty | Exit 0; fake empty-catalog live-check passed; no skips. |
npm run test:live | Exit 0; live-check passed; no skips. |
Unit and live checks ran separately (unit first, then live); live results reported here, not folded into the unit count.
Reproduction evidence (red → green)
src/v2/completion-handoff.test.ts was written first against the old code and failed as required (missing exports). After the fix the same file passes 8/8: chain terminates at COMPLETION_CHAIN_MAX (3), ping-pong and repeated recipients reroute to the leader while the default route home to the leader is never refused, completion keys scope one hop per finished task per recipient, grouping collects only pending unbatched completions per recipient (oldest first), batch copy lists sender/title/outcome/path with $Name grammar, review decisions parse per-item actions and refuse bad input, and closure needs every item decided.
src/v2/completion-batch-service.test.ts was written first and failed as required (no completion hop queued). After the fix it passes 6/6: non-leader completion auto-handoffs to the leader with finished content and Handed to $Nova (no delegate child, one hop under its own completion: key); explicit handoff satisfies the obligation (no automatic hop on top); leader turns terminate without a forced handoff; two completions produce one Review 3 completions batch with per-item decisions (partial disposition keeps the batch open, full disposition closes it; end/dismiss/delegate each recorded; delegation created once); a non-leader batch recipient hands onward to the leader on full disposition (delegate refused leader-only, item stays undecided); and the onward chain terminates at the depth cap with Completion closed for $Sage and no duplicate hop.
Debugging those tests exposed two real truths worth recording: (1) the single-hop quiet-window defer must re-schedule() after consolidating, or a lone completion sits past its retryAfter with nobody pumping the queue; (2) synthesis reassigns the finished turn to the leader, so completion tests match turns by title/kind instead of the original assignee.
Behavior notes
- Mandatory handoff fires on success finalizes for non-leader assignees that are neither completion nor batch hops and have no explicit handoff child; the hop carries the finished reply, is keyed
completion:<workspace>:<finishedTask>:<recipient>, parks inside the ~1 s batch quiet window (retryAfter), postsHanded to $Leader, and the finisher finalizes immediately (the hop is a post-turn delivery, not a wait — only explicit children holdawaitingChildren, so a grouped completion can never wedge its finisher). - Batch consolidation parents ≥2 pending completions into one review turn (
completion+batch,itemIDs), extends the open batch on later arrivals, excludes grouped items from the pump while the batch is open, andmaybeSynthesizenever auto-closes a batch parent — closure is only viaensemble_reviewwith every item decided. Leaders end the batch; non-leaders hand it onward (default leader) under the same loop guards. delegateinside review stays leader-only, so mandatory handoff never becomes delegate-after-handoff by another name; no duplicate work is queued (per-item refusals leave items undecided and the batch open).- Copy follows
$Name/!Namefor agents and@file-only everywhere (batch listings, refusal and closure notices,AGENTS.md, runtime identity,init-block.tscontract + Tools table + newEnd-of-turn handoffsection). - Compatibility: #67 bubbles/completions, #68 approval trust (native rows still settle only via host/user), #69 settings, #70 activity states and handoff waiting, queue semantics, DMs, wizards/dialogs untouched — six existing tests were updated to the new contract by filtering
handoff.completionout of explicit-hop counts and pinning the new hop where relevant (handoff-service,handoff-waiting,peer-turn-service,serviceoutside-roster + restart-recovery).
Constants
COMPLETION_CHAIN_MAX = 3,COMPLETION_QUIET_WINDOW_MS = 1_000(src/v2/handoff.ts); explicit caps unchanged (HANDOFF_MAX_DEPTH = 1,HANDOFF_MAX_PER_RUN = 3).- Refusal/closure copy:
Handoff refused: …,Completion closed for $Name: …,Review closed: …,Batch stays open: n of m decided.,Only $Owner can review this batch.
Uncertainty
- Live runs were recorded against host 2.2.5 while typechecking against 2.2.1 declarations; no new host APIs are used (text anchors only), but declaration parity is not runtime proof — see the runtime guide.
- The ~1 s batch window is a heuristic: parallel live turns land well inside it (one joint fan-out message creates both turns atomically), but completions seconds apart stay single direct hops by design.
- Batch review presentation parks in
awaitingChildrenlike any parent with live children; the TUI renders the genericWaiting for $Name…wait rather than a batch-specific verb.
v5.5 review fixes (2026-11-03)
Five findings fixed after the two-axis review, each verified red→green where applicable:
cross_projectapprovals now label asworkspace;promote_memorystaysmemory; legacy stored sources cannot override the kind mapping. Label tests cover every kind.resolveApproval's stale guard now includespromote_memory.- Approval-gated/interrupted pending work shows
waiting for you…(with needs-you marker) instead of a hardcodedqueued; genuinely queued work stays queued. Unit tests cover both. - Removed the always-empty ternary in
batchReviewText. - Live exactly-once completion assertion restored: recent completion lines must each appear exactly once in the visible pane, with the snapshot terminal total matching; accumulator dedup remains unit-tested.
Commands on the fix branch (Node v26.12.1, host OpenCode v2.2.5 vs pinned types 2.2.1):
| Command | Result |
|---|---|
npm run check | exit 0 |
npm test | 354 passed, 0 failed |
npm run test:live | passed |
npm run test:live:fake | passed |
npm run test:live:fake:empty | passed |
No skips. Remaining uncertainty unchanged: no live macOS run; native permission round-trip covered by fake-ctx tests (fake provider emits text only); batching is live-proven for two items.