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
This commit is contained in:
Neil
2026-11-10 00:38:10 -08:00
committed by GitHub
parent 115976acca
commit 92a08cdd1d
8 changed files with 218 additions and 8 deletions
@@ -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 })
}
@@ -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'
})
})
})
@@ -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
@@ -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 }
})
})
})
@@ -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.
@@ -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
}
}
@@ -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)
@@ -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({