Skip to content

Ticket #70 verification — truthful activity states and handoff waiting — 2026-11-03 ​

Parent spec #66 (conversation surfaces and approval trust), child ticket #70 (truthful activity states plus a correct handoff-wait contract). Worktree: /tmp/opencode/ensemble-worktrees/55-70-activity, branch feat/v55-70, base 3e9175a (= local integration/ensemble-v5.5 tip with #67 bubbles, #68 approvals, #69 settings merged; no newer tip to merge).

Environment ​

sh
export PATH=/home/tristan/.nvm/versions/node/v26.12.1/bin:/home/tristan/.local/bin:$PATH

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 commandResult
npm run checkExit 0; strict no-emit TypeScript check.
npm testExit 0; 337 passed, 0 failed, 0 skipped (includes 8 new activity-state.test.ts + 2 new handoff-waiting.test.ts).
npm run test:live:fakeExit 0; fake live-check passed; no skips. Animation observed across working frames (◐◑).
npm run test:live:fake:emptyExit 0; fake empty-catalog live-check passed; no skips.
npm run test:liveExit 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/tui/activity-state.test.ts was written first against the old behavior and failed as required: activityStateForTask did not exist, and the old activityDetailForTask derived every non-turn/handoff task — including approval-gated work, parents awaiting children, and retrying backoff — as the generic checking the details… working line. After the fix the same file passes 8/8: approval-gated and native-blocked work derive as waiting for you… (waiting kind), a parent awaiting children derives as Waiting for $Child…, retrying work names retrying…, entries older than ACTIVITY_STALE_AFTER_MS (120s) read stale, and copy follows the $Name grammar with no @ addressing.

Service-level hang proof is src/v2/handoff-waiting.test.ts: parentless handoff anchors to the sender's newest open task pins the orphan-hop hole (a handoff issued from a session with no live run parents its hop on the sender's newest open task instead of undefined). sender waits on the handoff with a visible wait and no double-queue pins the contract end to end (parent holds awaitingChildren with Waiting for $Sage… while the hop is in flight; a peer ensemble_delegate after the handoff is refused leader-only; exactly one hop row and one correlation-linked relay land). Debugging that test exposed a real scheduling truth worth recording: with equal 2000 ms waits the parent tail and the hop reply race, so the test staggers waits (sender 500 ms, hop 4000 ms) to make the hold deterministically observable — the mechanism (parent tail reads a fresh snapshot, children.length > 0 holds awaitingChildren, maybeSynthesize completes after delivery) was verified in a throwaway trace, not assumed.

What changed ​

Pure activity seam (src/v2/tui/workrows.ts): new waitingForLine (Waiting for $Name…), waitingForYouLine (waiting for you…), workingLine (working…, detail when available), retryingLine, new working/retrying verb kinds with frame routing (working spins, retrying breathes calm), activityStateForTask (needs-you first, then waiting-for-children, then retrying, then asking for hops/turns, then working…; the generic default is reserved for genuinely unknown activity), isActivityTaskStale (claimed but lease lapsed) and isActivityStale (streaming row older than the bound), and splitActivityGroups now threads pendingApprovalIDs/nativeBlockedIDs/ agentNameFor and hides stale claims from the live surface (WORK rows still list them, so nothing silently drops). activityDetailForTask is kept for existing callers.

src/v2/tui/app.tsx: the group live-activity memo passes the approval and native-blocked sets plus the agent-name resolver into splitActivityGroups, and filters leaked streaming rows older than the staleness bound before they can wedge an activity line.

Handoff contract (src/v2/service.ts, src/v2/handoff.ts, src/v2/init-block.ts): new exported newestOpenSenderTaskID pure helper; toolHandoff anchors runless hops to the sender's newest open task (depth and per-run caps follow the anchor), and the tool result, ack, and duplicate copy state the wait (Your turn stays open until the answer arrives here — do not call ensemble_delegate after a handoff (leader-only; would double-queue)). Handoff/delegate tool descriptions, the init-block addressing line, Tools-table rows, handoff steps, the identity prompt, and the mention-normalized system line now say leaders delegate while peers hand off (which already queues the hop). No coordination semantics changed beyond the stated anchor.

Harness determinism (scripts/lib/live-harness.sh, scripts/live-check-fake.sh): new live_capture_all_text / live_require_all_text bounded settle poll; the rich-markdown block settles until all ten markers co-occur in one capture before the unchanged asserts/counts run. Group-burst anchors now expect the truthful working… verb (· working frame collector, reduced-motion frame-0 line); DM-surface checking the details… anchors are untouched (task-less streaming still uses the thinking fallback). The ≥2-frame animation observation is intact and the assertions were not weakened.

Compatibility and acceptance mapping ​

  • Bubbles/inline completions/settings stylization: untouched surfaces; test:live:fake slice G and bubble/inline probes pass unchanged.
  • Approvals trust (#68): native rows still settle only via host/user; the activity seam consumes the same nativeBlockedSubtaskIDs set, so approval-blocked work keeps its needs-you marker and never poses as working.
  • $Name/@ rules: new copy uses $Name only; tests assert no @Name in group messages; wizard/dialogs/DM durability/coordination semantics unchanged (full unit suite green, no queue.ts lifecycle edits).
  • Acceptance: hang test fails before / passes after ✓; per-state verbs (working, waiting-for-agent, waiting-for-user, queued static, retrying, stale-hidden) ✓; stale lines resolve instead of hanging ✓; sender waits on handoff with Waiting for $Name… and no double-queue ✓; unit plus live text-anchor assertions pass ✓.

Uncertainty ​

  • Staleness bound (120 s) is a product choice, not a measured heartbeat gap: the lease/heartbeat machinery (60 s / ~20 s) is the liveness signal for task-backed lines, the age bound only guards leaked streaming rows. A slower host render could in principle need longer than the 20 s rich-markdown settle window; the window matches LIVE_STEP_TIMEOUT convention and passed repeatedly here, but it is a timeout, not a proof.
  • The runless-hop anchor picks the sender's newest open task as a heuristic; a sender with two unrelated open tasks could anchor to the wrong one. The alternative (refusing runless handoffs) was rejected as a bigger behavior change; the hop still runs exactly once either way.
  • 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 per the runtime guide this is tested behavior, not a compatibility proof.

Released under the MIT License.