fix: Claude monitor wakes no longer fire a completion alert per line#32520

Problem

When a Claude agent arms a native Monitor and ends its turn, Claude Code wakes it once per Monitor output line. Each wake becomes a new T3 run that finishes in a second or two while the monitor is still pending, so every line fired a desktop "Thread completed" notification with sound, and a push completion.

Reproduced on main (e455200077) with the dev server on a fresh database and the reporter's prompt (a background loop appending one line every 8 s, a Monitor on the file, no t3_background_wait). The web client was set to "Notifications with sound", with Notification recording calls and the window unfocused. 22 Monitor lines produced 22 runs, which produced 22 "Thread completed" notifications and 22 sounds in 2 min 44 s. A variant sent from the composer with a different Claude model (6 lines at 5 s) produced 7 runs and 7 notifications.

Change

• Server: the thread shell gets an optional latestRunBackgroundWake. It is true only when the latest run answers a background progress wake: a background-task, command or monitor notification with outcome updated (one per Monitor line), that is not a delegated completion, on a run the user has not steered a follow-up into. Terminal wakes ("Command … finished", "Monitor … was stopped") are not progress wakes. The SQL shell query and the in-memory shell builder compute it the same way, and the awareness snapshot the push relay reads uses it.
• Shared: monitorHoldsWakeCompletion (in packages/shared) is true while the latest run is a progress wake and a monitor is still in pendingBackgroundTasks.
• Web/desktop: ThreadNotificationCoordinator holds that completion instead of alerting. When the monitor leaves, the newest completion alerts once. Any progress-wake completion waits the same 5 s the push relay already uses to confirm completions, so a terminal wake that starts right after does not alert twice. While the environment is disconnected the grace pauses, and the next live snapshot restarts it only if that completion is still the latest.
• Push: projectThreadAwarenessV2 reports a held completion as running, so the Live Activity stays alive and the push alert comes once, when the monitor ends. A thread the user has settled still drops it.

Runs the user starts, steered runs, terminal wakes, delegated completions, schedules and threads with an awaited PR watch alert as before. A progress-wake completion with no monitor pending now alerts after the 5 s grace instead of at once, and progress wakes inside that window collapse into one alert. A Monitor the agent re-arms alerts once per arm (on its terminal wake), not once per line. An older server omits the field, so clients keep today's behaviour.

Scope and approval

Fixes pingdotgg/t3code#32497

Verification

Head 9fc1b016f1 (main merged). vp run check:changed passes: format, lint, knip, typecheck of 37 packages, 134 tests in 7 files, React compiler. Two independent reviews of the full diff against main found no defects.

Focused tests, each new case checked to fail without its fix:

• packages/shared/src/agentAwareness.test.ts (26): a held wake reports running, also beside other pending work; a released wake, a wake with only a command pending and a user run report completed; a settled monitor-held thread drops out.
• apps/server/src/orchestration-v2/ProjectionStore.test.ts + apps/server/src/relay/AgentAwarenessRelay.test.ts (73): the wake-classification table, through both the SQL and in-memory shell paths, covers background-task, monitor and command progress wakes (true) and a subagent, a delegated completion, a steered follow-up, "Command finished" and "Monitor stopped" (false).
• apps/web/src/components/ThreadNotificationCoordinator.logic.test.ts (9): the grace for a released hold and for an unheld wake completion, cancellation by a following run, pause and restart.
• apps/web/src/components/ThreadNotificationCoordinator.badge.browser.test.ts (11): the coordinator end to end through a monitor, with and without a disconnect during the grace.

Evidence

Before d313b2aff3 (main), after 175298a8cd for the real-app rows and 5e31e6c283 for F4. Later commits only change settled threads, test rows and a main merge, none of which these rows reach. Environment: T3 Browser panel, Chromium 157 headless on Linux, no device emulation, 1440×900 CSS viewport, DPR 2, dark theme, real UTC clock. Each side ran its own dev server on a fresh database (T3CODE_DEV_SEED=0) with a real Claude turn on a synthetic scratch project; the page records Notification() calls and Web Audio starts with document.hasFocus() false and "Notifications with sound" selected. The model label is masked. Recordings have no audio track: the counts are Web Audio starts, not speaker or OS delivery.

R1: the reporter's scenario (driver prompt: 6 lines at 5 s, Monitor 60 s, no t3_background_wait)

In R1-after the first run and "Command finished" were each replaced by the next run before the client saw them complete, so the client never had those completions to alert on (the same happened to two runs before). R2 shows both alerting on the head.

R2: the user steers into a wake run, after only (r2-after.mp4): 9 runs, 4 alerts / 4 audio starts: the user's first run (15:01:25), the steered wake run (15:01:34), "Command finished" (15:01:52), "Monitor stopped" (15:02:27). The other progress wakes alerted 0 times.

F4: hold released with no following run, labelled harness (real ThreadNotificationCoordinator, synthetic shell snapshots, real timers). Steps: 0 s user run running, 1 s completed, 3 s wake running with a Monitor pending, 5 s wake completed, 10 s Monitor removed with no new run, 12 s unchanged re-emit, observed to 25 s.

R3: push awareness, read-only server transcript (r3-server-awareness.jsonl): ProjectionStore.getAgentAwarenessSnapshot through projectThreadAwarenessV2 reports running (non-null) for a completed progress wake with a Monitor pending, and completed after the Monitor ends. On main the same shells project completed (r3-before-projected.json).

F8–F10: disconnects and cancellation during the grace, labelled harness (real ThreadNotificationCoordinator, gate and shell presenter of each revision; synthetic shells and Notification, real timers). Before e5b0718a8a (main), after 5ff188ef57. Same environment line as above. Steps: F8 1 s wake completion → 2 s disconnect → 8 s reconnect to the same completion → 10 s unchanged re-emit. F9 16 s completion → 17 s disconnect → 23 s reconnect with a successor running → 24 s successor completes. F10 32 s five completions → 33 s archive, stop, thread removal, coordinator cleanup, environment removal → 39 s restore; 48 s completion → 49 s notifications off → 55 s back on.

P3: settling a monitor-held thread, production projection transcript (ProjectionStore.getAgentAwarenessSnapshot on fresh SQLite through projectThreadAwarenessV2). Held completion, settled, unsettled: before completed → null → completed, after running → null → running. Controls (active run, awaited monitor/command/background task, subagent, pending input, pending approval) project the same on both sides. p3-before.jsonl / p3-after.jsonl; an independent rebuild at 5ff188ef57 matched all 12 steps (comparison.json).

Fixture matrix: matrix.md. F8–F10 and P3 tables with every step: evidence-snippet.md. Their drivers (uploaded, not committed): harness.ts, harness-driver.mjs, awareness-capture.mjs.

What else changed: nothing visible. The sidebar still flips Working/Done on each wake. Titles, replies and timestamps differ between real runs.

Run listings, recorder logs and per-run alert timestamps for R1-R3 are in the first capture pass's index (its F4 and R2 entries are superseded by the ones above): Evidence.md. Drivers (uploaded, not committed): driver-prompt.txt, recorder.js, steer-on-wake.js, awareness-reader.mjs, harness.ts, harness-driver.mjs.

Not checked: real OS notification presentation on macOS and Windows, and push/APNs delivery to a phone (no T3 Connect here). The push path is covered by the awareness tests and the read-only awareness transcript. The sidebar still flips between Working and Done on each wake; this PR only changes alerts.

AI-assisted; verified with the tests and tools listed above.