feat: truly-idle alerting — server-authoritative terminal.idle bell/shade + persistent green

[danshapiro]

Truly-idle alerting semantics (Track 4)

The bell used to ring on every terminal.turn.complete — including subagent finishes and turn ends with another prompt already queued. This PR makes the bell/shade edge for terminal-mode CLI panes (claude/codex/opencode/amplifier) a server-authoritative truly-idle edge, and makes green a persistent idle state. Fresh-agent (fresh*) panes are untouched.

Pinned wire contract (shared with the Rust track)

• Busy/blue: existing activity protocol, unchanged.
• terminal.turn.complete: still emitted at turn boundaries; the client no longer rings/shades on it for terminal CLI panes.
• NEW terminal.idle: { terminalId, at (server epoch ms), reason: 'grace' | 'queue-empty' } — once per busy→truly-idle transition, after a 2000ms grace (TERMINAL_IDLE_GRACE_MS) with no new session-file activity AND no queued prompt; never after crash/interrupt/exit; subagent completions mid-turn never produce it.

Server (legacy Node)

• server/coding-cli/truly-idle-emitter.ts: provider-agnostic per-terminal state machine fed by each tracker's existing changed + turn.complete streams. One-shot unref'd grace timers armed only at turn boundaries — zero polling, no per-pane intervals (chokidar untouched; the amplifier events tailer is reused, not rewritten — no new file watching was needed at all: the queued/subagent knowledge already lives in the tracker state machines).
• Wired for all four trackers in server/index.ts → wsHandler.broadcastTerminalIdle (disposed on shutdown).

Client

• Blue = busy (unchanged).
• Green = persistent idle (resolvePaneIdleGreen): shown when the pane's CLI session is known (activity record, bound sessionRef, or resume id) and not busy. Replaces one-shot needs-attention green for the four CLI panes; fresh-agent panes keep the attention green.
• Bell + tab shading: fire ONLY on a terminal.idle edge; deduped per terminal by monotonic at in its own namespace (lastIdleAtByTerminalId), reset on real server restart. Never on turn.complete; never on crash/exit (TERM-18 preserved — trackers remove state on exit and the emitter cancels + never emits).
• Shade-clear paths unchanged (tab activation / click-in-tab via dismissTabGreen; 'type' mode untouched).
• Removed: client terminal.turn.complete bell path, latestTurnCompletions replay-to-green loops, completionSeq dedupe machinery, and client BEL minting for all four CLI modes (isServerAuthoritativeTurnCompleteMode now covers opencode + amplifier; custom CLI modes keep the BEL path).

Legacy-health findings per CLI (Task 1)

• claude: healthy — PTY submit→busy, Stop-hook BEL→idle+completion, deadman self-heal (unit suite green).
• codex: healthy — app-server turn events + JSONL reconcile + BEL, queued-submit re-arm to pending, completion only when landing idle (unit suite green). The user-reported "codex/amplifier never turn blue" was NOT reproducible against the legacy trackers' unit/ws suites; consistent with it being the Rust server's gap (owned by another track).
• amplifier: healthy — events.jsonl tailer→reducer→tracker with provisional-busy grace + force-read backstop (unit suite green).
• opencode: terminal mode DOES have a tracker (opencode-activity-tracker.ts, SSE ownership reducer, busy-only records + turn.complete) — healthy.
• No legacy fixes were required; 1018 coding-cli unit tests green at base and after changes.

Queued/subagent detection per CLI (Task 2)

• claude: tracker in-flight submit/BEL ledger — phase stays busy while queued turns remain, so mid-queue completions arrive "while busy" → emitter holds the bell; final drain emits reason: 'queue-empty'. Subagent stops don't fire the Stop hook; stray BELs are filtered (countTrackerTurnCompleteSignals) and BELs while idle are ignored.
• codex: tracker queuedSubmitAt re-arms busy→pending at turn clear (emitter treats it as queue evidence) and only records a completion when landing idle — queue drained by construction.
• amplifier: prompt:submit/prompt:complete records via the existing incremental tailer; a queued prompt starts a new prompt:submit inside the grace window → cancels. Subagent files are rejected by the locator/reducer (session:fork, parent_id) and never feed the tracker.
• opencode: grace-only fallback (no queue signal available; parallel track researching).

Suppression cases proven (test names)

Emitter (test/unit/server/coding-cli/truly-idle-emitter.test.ts):

• back-to-back turns → suppresses the bell between back-to-back turns and emits once at the very end
• queued prompt at turn end → holds the bell while a queued prompt keeps the terminal busy, then emits queue-empty after the queue drains, treats a codex busy->pending re-arm as queue evidence
• crash/exit → never emits after a crash/exit (activity remove), even with a grace timer armed (+ ws-level does not broadcast terminal.idle when the terminal exits inside the grace window in test/server/ws-terminal-idle.test.ts)
• deadman/signal loss (covers subagent-free fabrications) → never emits on a deadman/signal-loss idle flip…, never emits on a codex busy->unknown deadman flip
  Client:
• turn.complete never bells → never bells or shades on terminal.turn.complete (informational only for terminal CLI panes) (test/e2e/turn-complete-notification-flow.test.tsx), ignores latestTurnCompletions in activity list responses… (App.ws-bootstrap.test.tsx)
• reconnect replay → rings exactly once when a reconnect replays the same terminal.idle edge; slice-level dedupes idle edges per terminal by monotonic at…
• both shade-clear paths → bells and highlights on background completion, clears on tab click (default click mode), click mode: clicking the already-active tab clears attention, type mode: attention persists after tab switch, clears on terminal input
• persistent green → shows persistent idle green on a claude pane header whenever the session is known and not busy (pane-activity-indicator-flow.test.tsx) + resolvePaneIdleGreen unit matrix (pane-activity.test.ts)

Playwright (legacy-chromium, passing 2x)

test/e2e-browser/specs/truly-idle-alerting.spec.ts — fake CLAUDE_CMD CLI drives the full production pipeline (no Redux shortcuts): PTY submit → blue; BEL + quiet 2s grace → terminal.idle → persistent green header + tab shade + exactly one alert edge (stable across a settle window); activating the tab clears the shade while green persists. Added to MATRIX_SPECS; the rust leg is test.fixme annotated "pending rust terminal.idle emitter — feat/rust-terminal-activity-idle" so it flips on trivially.

Verification

• Typecheck (client + server tsconfig) clean; npm run lint 0 errors (10 pre-existing warnings in untouched files).
• Focused suites green 2x (1904 tests each run); PW spec green 2x (25.5s / 26.1s).
• Coordinated npm test: client 3982 passed, server 4547 passed, electron 350 passed — all green.

Deferred

• Amplifier/codex/opencode Playwright legs (claude leg covers the shared pipeline end-to-end; per-CLI queue semantics are unit-proven).
• Rust-server terminal.idle emitter + flipping the PW rust leg on (owned by feat/rust-terminal-activity-idle).
• docs/index.html: untouched — the mock has no attention/indicator visuals to update; the default visual experience is unchanged.

🤖 Generated with Amplifier