From 92a08cdd1d3fb1e020b6ce282b236eb9dfc1eb2a Mon Sep 17 00:00:00 2001 From: Neil <4138956+nwparker@users.noreply.github.com> Date: Tue, 10 Nov 2026 00:38:10 -0800 Subject: [PATCH] feat(attention): record why a finished agent turn left its workspace read (#40703) An agent row can turn bold while its workspace never becomes unread, and every path that drops the finish on the way to the unread flag was silent, so the next occurrence could not be traced. Each drop site now leaves one `agent_finish_dropped` breadcrumb (mirrored to main.trace.ndjson) with its cause, workspace and pane: - paired-host mirror: a restored, unconfirmed done, or a done skipped as a host replay; - hook lane: a pane it does not consider live, completion notifications off for the pane, a new turn end swallowed because an earlier hook end used up the turn with no working state in between, a pane pruned during the quiet window, or a held turn-end revision that expired; - dispatcher: a fresh active hook status, a superseded snapshot, an attention-policy rejection, or a viewed pane. No behaviour changes. Refs #40340 --- .../attention/agent-finish-drop-breadcrumb.ts | 58 ++++++++++++++++++ ...ordinator-turn-end-drop-breadcrumb.test.ts | 59 +++++++++++++++++++ .../agent-completion-hook-observer.ts | 12 ++++ .../agent-finish-drop-breadcrumb.test.ts | 41 +++++++++++++ .../dispatch-terminal-notification.ts | 18 ++++++ .../agent-hook-completion-notifications.ts | 6 +- .../agent-hook-completion-revision-hold.ts | 13 +++- .../web-session-tabs-sync/store-patch.ts | 19 ++++-- 8 files changed, 218 insertions(+), 8 deletions(-) create mode 100644 src/renderer/src/attention/agent-finish-drop-breadcrumb.ts create mode 100644 src/renderer/src/components/terminal-pane/agent-completion/agent-completion-coordinator-turn-end-drop-breadcrumb.test.ts create mode 100644 src/renderer/src/components/terminal-pane/notifications/agent-finish-drop-breadcrumb.test.ts diff --git a/src/renderer/src/attention/agent-finish-drop-breadcrumb.ts b/src/renderer/src/attention/agent-finish-drop-breadcrumb.ts new file mode 100644 index 00000000000..9c42d0049e4 --- /dev/null +++ b/src/renderer/src/attention/agent-finish-drop-breadcrumb.ts @@ -0,0 +1,58 @@ +import { recordRendererCrashBreadcrumb } from '@/lib/crash-breadcrumb-recorder' + +/** Why a finished agent turn did not mark its workspace unread. */ +export type AgentFinishDropCause = + | 'fresh-active-hook-status' + | 'superseded-snapshot' + | 'muted-workspace' + | 'coordinator-only-news' + | 'no-live-session' + | 'unknown-surface' + | 'superseded-surface' + | 'viewed' + | 'pane-pruned-before-quiet-window' + | 'held-revision-expired' + | 'pane-not-live' + | 'hook-lane-disabled' + | 'turn-end-not-counted' + | 'restored-unconfirmed' + | 'host-replay-skipped' + +/** Every path that drops a finish was silent, so a missing unread could not be traced (#40340). */ +export function recordAgentFinishDropped( + cause: AgentFinishDropCause, + subject: { workspaceId?: string; paneKey?: string | null } +): void { + recordRendererCrashBreadcrumb('agent_finish_dropped', { + cause, + ...(subject.workspaceId ? { workspaceId: subject.workspaceId } : {}), + ...(subject.paneKey ? { paneKey: subject.paneKey } : {}) + }) +} + +/** A finish waiting out its quiet window is lost when its pane's coordinator is pruned. */ +export function recordPrunedPendingFinish( + workspaceId: string, + paneKey: string, + coordinator: { hasPendingHookDoneCompletion: () => boolean } +): void { + if (coordinator.hasPendingHookDoneCompletion()) { + recordAgentFinishDropped('pane-pruned-before-quiet-window', { workspaceId, paneKey }) + } +} + +/** The hook lane ignores updates for a pane it does not consider live; only a finish matters here. */ +export function recordFinishOnPaneNotLive( + workspaceId: string, + paneKey: string, + state: string +): void { + if (state === 'done') { + recordAgentFinishDropped('pane-not-live', { workspaceId, paneKey }) + } +} + +/** Completion notifications are off for this pane (setting, or waiting for a fresh working state). */ +export function recordHookLaneDisabled(workspaceId: string, paneKey: string): void { + recordAgentFinishDropped('hook-lane-disabled', { workspaceId, paneKey }) +} diff --git a/src/renderer/src/components/terminal-pane/agent-completion/agent-completion-coordinator-turn-end-drop-breadcrumb.test.ts b/src/renderer/src/components/terminal-pane/agent-completion/agent-completion-coordinator-turn-end-drop-breadcrumb.test.ts new file mode 100644 index 00000000000..9a6ebf5bd65 --- /dev/null +++ b/src/renderer/src/components/terminal-pane/agent-completion/agent-completion-coordinator-turn-end-drop-breadcrumb.test.ts @@ -0,0 +1,59 @@ +import { beforeEach, describe, expect, it, vi } from 'vitest' + +const { recordAgentFinishDropped } = vi.hoisted(() => ({ recordAgentFinishDropped: vi.fn() })) +vi.mock('@/attention/agent-finish-drop-breadcrumb', () => ({ recordAgentFinishDropped })) + +import { createAgentCompletionCoordinator } from './agent-completion-coordinator' +import { useAgentCompletionCoordinatorLifecycle } from './agent-completion-coordinator-test-harness' + +// #40340: the crumb must name a swallowed new turn end, never a revision of one already announced. +describe('turn-end-not-counted breadcrumb', () => { + useAgentCompletionCoordinatorLifecycle() + beforeEach(() => recordAgentFinishDropped.mockClear()) + + function hookCoordinator() { + const dispatchCompletion = vi.fn() + const coordinator = createAgentCompletionCoordinator({ + paneKey: 'tab-1:leaf-1', + statusLane: 'hook', + getPtyId: () => 'pty-1', + inspectProcess: vi.fn(), + dispatchCompletion, + isLive: () => true + }) + coordinator.observeHookStatus({ + state: 'working', + prompt: 'first turn', + agentType: 'claude', + stateStartedAt: 2_000 + }) + const done = { state: 'done' as const, prompt: 'first turn', agentType: 'claude' } + coordinator.observeHookStatus({ ...done, stateStartedAt: 2_400, turnCompletedAt: 2_500 }) + vi.runAllTimers() + return { coordinator, dispatchCompletion, done } + } + + it('records nothing for a revision of the announced end', () => { + const { coordinator, dispatchCompletion, done } = hookCoordinator() + expect(dispatchCompletion).toHaveBeenCalledTimes(1) + + coordinator.observeHookStatus({ + ...done, + stateStartedAt: 2_400, + turnCompletedAt: 2_500, + turnEndedAt: 2_600 + }) + + expect(recordAgentFinishDropped).not.toHaveBeenCalled() + }) + + it('records a different end swallowed with no working state in between', () => { + const { coordinator, done } = hookCoordinator() + + coordinator.observeHookStatus({ ...done, stateStartedAt: 3_400, turnCompletedAt: 3_500 }) + + expect(recordAgentFinishDropped).toHaveBeenCalledWith('turn-end-not-counted', { + paneKey: 'tab-1:leaf-1' + }) + }) +}) diff --git a/src/renderer/src/components/terminal-pane/agent-completion/agent-completion-hook-observer.ts b/src/renderer/src/components/terminal-pane/agent-completion/agent-completion-hook-observer.ts index 41f1ced6fe6..81d10a70fb8 100644 --- a/src/renderer/src/components/terminal-pane/agent-completion/agent-completion-hook-observer.ts +++ b/src/renderer/src/components/terminal-pane/agent-completion/agent-completion-hook-observer.ts @@ -4,6 +4,7 @@ import type { AgentCompletionStatusSnapshot } from './agent-completion-coordinator-types' import type { LastCompletionIdentity } from './agent-completion-identity-store' +import { recordAgentFinishDropped } from '@/attention/agent-finish-drop-breadcrumb' type HookObserverState = { workingStatusObserved: boolean @@ -160,6 +161,17 @@ export function createAgentCompletionHookObserver({ state.lastCompletionIdentity?.lastTurnCompletedAtNotified === turnCompletedAt || state.lastCompletedTurn === state.currentTurn) ) { + if ( + state.lastCompletionSource === 'hook' && + identity !== state.lastCompletionIdentity?.identity && + !turnCompletedAtAlreadyHandled(turnCompletedAt) && + state.lastCompletionIdentity?.lastTurnCompletedAtNotified !== turnCompletedAt + ) { + // An earlier, different hook end used up this turn and no working state followed, so this + // new end is swallowed. Revisions of the announced end and title or exit announcements are + // not drops. + recordAgentFinishDropped('turn-end-not-counted', { paneKey: options.paneKey }) + } consumeStampedTailForCurrentCoordinator(turnCompletedAt) options.dispatchHookLifecycle?.(payload) return diff --git a/src/renderer/src/components/terminal-pane/notifications/agent-finish-drop-breadcrumb.test.ts b/src/renderer/src/components/terminal-pane/notifications/agent-finish-drop-breadcrumb.test.ts new file mode 100644 index 00000000000..54592b91c49 --- /dev/null +++ b/src/renderer/src/components/terminal-pane/notifications/agent-finish-drop-breadcrumb.test.ts @@ -0,0 +1,41 @@ +import { beforeEach, describe, expect, it, vi } from 'vitest' + +vi.mock('../../../store/index', async () => + (await import('./notification-dispatch-test-harness')).createNotificationDispatchStoreModuleMock() +) + +import { + makeAgentStatus, + PANE_KEY, + resetNotificationDispatchMockState +} from './notification-dispatch-test-harness' +import { dispatchTerminalNotification } from './dispatch-terminal-notification' + +describe('a dropped agent finish (#40340)', () => { + const recordBreadcrumb = vi.fn() + + beforeEach(() => { + const state = resetNotificationDispatchMockState() + state.agentStatusByPaneKey[PANE_KEY] = makeAgentStatus(PANE_KEY, { state: 'working' }) + vi.stubGlobal('window', { + api: { + notifications: { dispatch: vi.fn().mockResolvedValue({ delivered: true }) }, + crashReports: { recordBreadcrumb } + } + }) + }) + + it('leaves a breadcrumb naming why it marked nothing unread', () => { + const dispatched = dispatchTerminalNotification('wt-1', { + source: 'agent-task-complete', + paneKey: PANE_KEY, + terminalTitle: 'codex' + }) + + expect(dispatched).toBe(false) + expect(recordBreadcrumb).toHaveBeenCalledWith({ + name: 'agent_finish_dropped', + data: { cause: 'fresh-active-hook-status', workspaceId: 'wt-1', paneKey: PANE_KEY } + }) + }) +}) diff --git a/src/renderer/src/components/terminal-pane/notifications/dispatch-terminal-notification.ts b/src/renderer/src/components/terminal-pane/notifications/dispatch-terminal-notification.ts index 98e082a98bd..8903740da23 100644 --- a/src/renderer/src/components/terminal-pane/notifications/dispatch-terminal-notification.ts +++ b/src/renderer/src/components/terminal-pane/notifications/dispatch-terminal-notification.ts @@ -40,6 +40,7 @@ import { deliverAgentAttentionNotification, readAgentAttentionNotificationSound } from '../../../attention/agent-attention-notification-delivery' +import { recordAgentFinishDropped } from '@/attention/agent-finish-drop-breadcrumb' const AGENT_NOTIFICATION_SNAPSHOT_MAX_AGE_MS = 10_000 @@ -114,6 +115,10 @@ export function dispatchTerminalNotification( hasFreshActiveHookStatus(storedAgentStatus, explicitTitleAgentType) ) { // Confirmed exit proves completion even when a title-only idle signal races behind active hook state. + recordAgentFinishDropped('fresh-active-hook-status', { + workspaceId: worktreeId, + paneKey: event.paneKey + }) return false } // A dead process may never emit done; stale active hooks cannot label its completion prompt/state. @@ -132,6 +137,10 @@ export function dispatchTerminalNotification( event.paneKey ? state.agentLaunchConfigByPaneKey[event.paneKey] : undefined )) ) { + recordAgentFinishDropped('superseded-snapshot', { + workspaceId: worktreeId, + paneKey: event.paneKey + }) return false } const agentNotificationStateStartedAt = @@ -154,8 +163,17 @@ export function dispatchTerminalNotification( createTerminalAttentionSurface(state) ) if (!attentionDecision.admitted) { + if (event.source === 'agent-task-complete') { + recordAgentFinishDropped(attentionDecision.cause, { + workspaceId: worktreeId, + paneKey: event.paneKey + }) + } return false } + if (event.source === 'agent-task-complete' && attentionDecision.unread === null) { + recordAgentFinishDropped('viewed', { workspaceId: worktreeId, paneKey: event.paneKey }) + } // Desktop settings are applied in main after independent mobile delivery. diff --git a/src/renderer/src/hooks/agent-hook-completion-notifications.ts b/src/renderer/src/hooks/agent-hook-completion-notifications.ts index 442a154bddd..a1ad8aaf375 100644 --- a/src/renderer/src/hooks/agent-hook-completion-notifications.ts +++ b/src/renderer/src/hooks/agent-hook-completion-notifications.ts @@ -20,6 +20,7 @@ import { discardHookLaneCompletionRequests, submitHookLaneCompletion } from './agent-hook-completion-revision-hold' +import * as finishDrops from '@/attention/agent-finish-drop-breadcrumb' type CoordinatorEntry = { worktreeId: string @@ -84,8 +85,9 @@ function pruneClosedPaneCoordinators(): void { } lastPrunedLivenessSnapshot = livenessSnapshot const tabIndex = buildTabIndex(livenessSnapshot.tabsByWorktree) - for (const paneKey of coordinatorsByPaneKey.keys()) { + for (const [paneKey, entry] of coordinatorsByPaneKey) { if (!paneCanReceiveHookCompletion(paneKey, tabIndex)) { + finishDrops.recordPrunedPendingFinish(entry.worktreeId, paneKey, entry.coordinator) disposeCoordinatorForPaneKey(paneKey) } } @@ -211,6 +213,7 @@ function createCoordinator(paneKey: string, worktreeId: string): AgentCompletion dispatchHookLifecycle: (payload) => dispatchAgentHookTerminalLifecycle(paneKey, payload), dispatchCompletion: (title, meta) => { if (!hookLaneDispatchEnabled(paneKey)) { + finishDrops.recordHookLaneDisabled(worktreeId, paneKey) return } const snapshot = meta?.agentStatus @@ -261,6 +264,7 @@ export function observeAgentHookCompletionForNotification({ if (seedOnly !== true) { pruneClosedPaneCoordinators() if (!paneCanReceiveHookCompletion(paneKey)) { + finishDrops.recordFinishOnPaneNotLive(worktreeId, paneKey, payload.state) return } } diff --git a/src/renderer/src/hooks/agent-hook-completion-revision-hold.ts b/src/renderer/src/hooks/agent-hook-completion-revision-hold.ts index 9a0d39b35bd..62f71755c57 100644 --- a/src/renderer/src/hooks/agent-hook-completion-revision-hold.ts +++ b/src/renderer/src/hooks/agent-hook-completion-revision-hold.ts @@ -2,6 +2,7 @@ import { useAppStore } from '@/store' import type { AgentCompletionStatusSnapshot } from '@/components/terminal-pane/agent-completion/agent-completion-coordinator-types' import { NOTIFICATION_COOLDOWN_MS } from '../../../shared/notification-burst-cooldown' import type { NotificationDispatchResult } from '../../../shared/notification-settings-types' +import { recordAgentFinishDropped } from '@/attention/agent-finish-drop-breadcrumb' export type HookLaneCompletionSubmit = ( onResult: (result: NotificationDispatchResult | null) => void @@ -42,7 +43,11 @@ function clearTimer(requests: PaneRequests): void { } } -function armHeldTimer(requests: PaneRequests, submitAfterCooldown: () => void): void { +function armHeldTimer( + paneKey: string, + requests: PaneRequests, + submitAfterCooldown: () => void +): void { const held = requests.held if (!held) { return @@ -51,6 +56,7 @@ function armHeldTimer(requests: PaneRequests, submitAfterCooldown: () => void): const cooldownEndsAt = requests.cooldownEndsAt if (cooldownEndsAt !== null && cooldownEndsAt > held.expiresAt) { requests.held = null + recordAgentFinishDropped('held-revision-expired', { paneKey }) return } // Use fixed expiry so repeated revisions cannot retain an unanswered request forever. @@ -60,6 +66,7 @@ function armHeldTimer(requests: PaneRequests, submitAfterCooldown: () => void): requests.timer = null if (cooldownEndsAt === null) { requests.held = null + recordAgentFinishDropped('held-revision-expired', { paneKey }) return } submitAfterCooldown() @@ -88,7 +95,7 @@ function submitNow( clearTimer(requests) return } - armHeldTimer(requests, () => submitHeld(paneKey, requests)) + armHeldTimer(paneKey, requests, () => submitHeld(paneKey, requests)) }) if (!sent && requests.requestSeq === seq) { requests.cooldownEndsAt = 0 @@ -140,7 +147,7 @@ export function submitHookLaneCompletion( expiresAt: requests.held?.expiresAt ?? Date.now() + 2 * NOTIFICATION_COOLDOWN_MS } const paneRequests = requests - armHeldTimer(requests, () => submitHeld(paneKey, paneRequests)) + armHeldTimer(paneKey, requests, () => submitHeld(paneKey, paneRequests)) return } clearTimer(requests) diff --git a/src/renderer/src/runtime/web-session-tabs-sync/store-patch.ts b/src/renderer/src/runtime/web-session-tabs-sync/store-patch.ts index c1684c62eb3..2fd734daa09 100644 --- a/src/renderer/src/runtime/web-session-tabs-sync/store-patch.ts +++ b/src/renderer/src/runtime/web-session-tabs-sync/store-patch.ts @@ -30,6 +30,7 @@ import { type HostSessionMirrorPatchVerdict, type HostSessionMirrorSettle } from './mirror-settle' +import { recordAgentFinishDropped } from '@/attention/agent-finish-drop-breadcrumb' /** Commit a reconciliation patch and return a receipt for its host evidence. */ export function applyWebSessionTabsStorePatch( @@ -101,10 +102,14 @@ export function applyWebSessionTabsStorePatch( } const notificationStatus = clientOwnedNotification ? remapped : accepted // Why: an unverifiable `done` restates an earlier turn or none, never a completion. - if ( - !notificationStatus || - (notificationStatus.state === 'done' && notificationStatus.restoredUnconfirmed) - ) { + if (!notificationStatus) { + continue + } + if (notificationStatus.state === 'done' && notificationStatus.restoredUnconfirmed) { + recordAgentFinishDropped('restored-unconfirmed', { + workspaceId: notificationStatus.worktreeId ?? snapshot.worktree, + paneKey: notificationStatus.paneKey + }) continue } const currentClientStateStartedAt = clientOwnedNotification @@ -168,6 +173,12 @@ export function applyWebSessionTabsStorePatch( state.agentStatusByPaneKey[notificationStatus.paneKey] )) if (!notifyCompletion && notificationStatus.state !== 'working') { + if (notificationStatus.state === 'done') { + recordAgentFinishDropped('host-replay-skipped', { + workspaceId: notificationStatus.worktreeId ?? snapshot.worktree, + paneKey: notificationStatus.paneKey + }) + } continue } acceptedNotificationStatuses.push({