Skip to content
179 changes: 179 additions & 0 deletions src/main/agent-hooks/ended-process-reconciliation.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,179 @@
import { mkdtempSync, rmSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { afterEach, beforeEach, describe, expect, it } from 'vitest'
import { makePaneKey } from '../../shared/stable-pane-id'
import { AgentHookServer } from './server'

const LEAF = '11111111-1111-4111-8111-111111111111'
const PANE = makePaneKey('tab-1', LEAF)

let dir: string

beforeEach(() => {
dir = mkdtempSync(join(tmpdir(), 'orca-ended-process-'))
})

afterEach(() => {
rmSync(dir, { recursive: true, force: true })
})

async function startServer(): Promise<AgentHookServer> {
const server = new AgentHookServer()
await server.start({ env: 'production', userDataPath: dir })
return server
}

function claudeRow(server: AgentHookServer, state: 'working' | 'waiting' | 'done'): void {
server.ingestTerminalStatus({
paneKey: PANE,
tabId: 'tab-1',
worktreeId: 'wt-1',
connectionId: null,
payload: { state, prompt: 'review the PR', agentType: 'claude' }
})
}

/** A row carrying a resumable provider session — the only shape `dropStatusEntry` retains. */
function resumableClaudeRow(server: AgentHookServer): void {
server.ingestRemote(
{
paneKey: PANE,
tabId: 'tab-1',
worktreeId: 'wt-1',
source: 'claude',
hookEventName: 'UserPromptSubmit',
launchToken: 'dead-launch-token',
providerSession: { key: 'session_id', id: 'resume-me' },
payload: { state: 'working', prompt: 'review the PR', agentType: 'claude' }
},
'conn-a'
)
}

function paneState(server: AgentHookServer): string {
return server.getStatusSnapshotForPane(PANE)[0]?.state ?? 'missing'
}

// The teardown that normally clears a dead pane depends on the spawn-time ptyPaneKey mapping, which
// a restored PTY may never rebuild — leaving the row and its latches with nothing left to retire
// them. See PLAN-STA-4612 §4.2.
describe('reconcileEndedProcessForPaneKeys', () => {
it('retires a working row whose process is certifiably dead', async () => {
const server = await startServer()
try {
claudeRow(server, 'working')
expect(paneState(server)).toBe('working')

expect(server.reconcileEndedProcessForPaneKeys([PANE])).toBe(1)

expect(paneState(server)).toBe('missing')
} finally {
server.stop()
}
})

it('retires a waiting row — a wait whose owner is dead is not a wait', async () => {
const server = await startServer()
try {
claudeRow(server, 'waiting')

expect(server.reconcileEndedProcessForPaneKeys([PANE])).toBe(1)

expect(paneState(server)).toBe('missing')
} finally {
server.stop()
}
})

it('clears Claude latches even when the stored row already reads done', async () => {
// An interrupted lead suppresses the gate while leaving the latch set, so a row can read `done`
// with a latch that would re-gate `working` on the pane's very next event.
const server = await startServer()
try {
claudeRow(server, 'done')
server._getStateForTests().claudeRunningNonAgentTaskPaneKeys.add(PANE)
server._getStateForTests().claudeActiveSessionCronPaneKeys.add(PANE)

expect(server.reconcileEndedProcessForPaneKeys([PANE])).toBe(1)

expect(server._getStateForTests().claudeRunningNonAgentTaskPaneKeys.has(PANE)).toBe(false)
expect(server._getStateForTests().claudeActiveSessionCronPaneKeys.has(PANE)).toBe(false)
} finally {
server.stop()
}
})

it('is a no-op for a pane with nothing to retire', async () => {
const server = await startServer()
try {
expect(server.reconcileEndedProcessForPaneKeys([PANE])).toBe(0)
} finally {
server.stop()
}
})

it('keeps the resume identity a paired dismissal minted when the shell outlived the agent', async () => {
// The renderer's confirmed-shell route calls agentStatus:drop FIRST, which deliberately mints a
// providerSessionOnly remnant, then this. That remnant carries no state claim — it cannot gate a
// pane `working` — and the pane's PTY is still there to resume into, so retiring the pane's live
// claims must not take it. Without the option it goes with everything else.
const server = await startServer()
try {
resumableClaudeRow(server)
server.dropStatusEntry(PANE)
const afterDrop = server.getStatusSnapshotForPane(PANE)[0]
expect(afterDrop?.providerSessionOnly).toBe(true)
expect(afterDrop?.providerSession?.id).toBe('resume-me')

expect(
server.reconcileEndedProcessForPaneKeys([PANE], { preserveResumeIdentity: true })
).toBe(1)

const kept = server.getStatusSnapshotForPane(PANE)[0]
expect(kept?.providerSessionOnly).toBe(true)
expect(kept?.providerSession?.id).toBe('resume-me')
expect(kept?.launchToken).toBeUndefined()
// The live claims still went: a latch left behind would re-gate the pane on its next event.
expect(server._getStateForTests().claudeRunningNonAgentTaskPaneKeys.has(PANE)).toBe(false)

// The retained identity must not recreate dead launch authority after restart.
server.flushStatusPersistSync()
server.stop()
const restarted = await startServer()
expect(restarted.getStatusSnapshotForPane(PANE)[0]?.launchToken).toBeUndefined()
expect(restarted.getHydratedAuthorityCommitments()).toHaveLength(0)
restarted.stop()
} finally {
server.stop()
}
})

it('takes the resume identity too on a certified PTY exit, where no pane is left to resume into', async () => {
const server = await startServer()
try {
resumableClaudeRow(server)
server.dropStatusEntry(PANE)

expect(server.reconcileEndedProcessForPaneKeys([PANE])).toBe(1)

expect(paneState(server)).toBe('missing')
} finally {
server.stop()
}
})

it('drops the session owner so a rebound pane is not read as a session replacement', async () => {
const server = await startServer()
try {
claudeRow(server, 'working')
server._getStateForTests().claudeSessionOwnerByPaneKey.set(PANE, 'session-a')

server.reconcileEndedProcessForPaneKeys([PANE])

expect(server._getStateForTests().claudeSessionOwnerByPaneKey.has(PANE)).toBe(false)
} finally {
server.stop()
}
})
})
40 changes: 38 additions & 2 deletions src/main/agent-hooks/restored-subagent-liveness-sweep.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -211,7 +211,10 @@ describe('restored subagent liveness sweep', () => {
}
})

it('does not probe a hydrated Claude pane without restored rows', async () => {
it('reaps a hydrated non-terminal row with no roster at all (STA-4612)', async () => {
// A restored roster is only one shape of stranded claim. A lead row left `working` with no
// children has nothing left to retire it — no child event, no inventory, no hook — so it holds
// the pane working for good and locks its agent out of hibernation.
const server = await restartWithInFlightSubagent({ subagents: [] })
const probeLiveLocalPty = vi.fn(() => false)
try {
Expand All @@ -220,9 +223,42 @@ describe('restored subagent liveness sweep', () => {
probeLiveLocalPty,
persistedPtyIdByPaneKey: { [PANE]: PTY }
})
).toBe(1)

expect(probeLiveLocalPty).toHaveBeenCalled()
expect(paneStatus(server).state).toBe('missing')
} finally {
server.stop()
}
})

it('keeps a hydrated non-terminal row with no roster when its PTY is still live', async () => {
const server = await restartWithInFlightSubagent({ subagents: [] })
try {
expect(
await sweepWith(server, {
probeLiveLocalPty: () => true,
persistedPtyIdByPaneKey: { [PANE]: PTY }
})
).toBe(0)

expect(probeLiveLocalPty).not.toHaveBeenCalled()
expect(paneStatus(server).state).toBe('working')
} finally {
server.stop()
}
})

it('keeps a hydrated non-terminal row with no roster when the probe cannot prove either state', async () => {
const server = await restartWithInFlightSubagent({ subagents: [] })
try {
expect(
await sweepWith(server, {
probeLiveLocalPty: () => null,
persistedPtyIdByPaneKey: { [PANE]: PTY }
})
).toBe(0)

expect(paneStatus(server).state).toBe('working')
} finally {
server.stop()
}
Expand Down
105 changes: 93 additions & 12 deletions src/main/agent-hooks/server.ts
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ import { ORCA_HOOK_PROTOCOL_VERSION } from '../../shared/agent-hook-types'
import {
clearAllListenerCaches,
clearPaneCacheState,
paneHasStateClaims,
clearClaudeAnsweredQuestionWait,
createHookListenerState,
getEndpointFileName,
Expand Down Expand Up @@ -2594,28 +2595,87 @@ export class AgentHookServer {
this.notifyStatusChangeListeners()
}

/** The resume-identity remnant of a dropped row: a `providerSessionOnly` entry carries no state
* claim — it cannot gate a pane `working` — so it survives teardowns that end the pane's live
* claims. Returns null when the row has no resumable session to keep. */
private toRetainedProviderSessionRow(
entry: EnrichedAgentHookEventPayload | null | undefined
): EnrichedAgentHookEventPayload | null {
if (
!entry?.providerSession ||
!entry.payload.agentType ||
entry.payload.agentType === 'unknown'
) {
return null
}
const { launchToken: _launchToken, ...resumeIdentity } = entry
return { ...resumeIdentity, providerSessionOnly: true, retainedForLiveness: true }
}
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved

/** Drop only the status row (user dismissal); do NOT wipe prompt/tool caches since the pane's agent may still be alive. Use clearPaneState for PTY-teardown. */
dropStatusEntry(paneKey: string): void {
const deleted = this.deleteStatusEntry(paneKey, { preserveAuthority: true })
if (!deleted) {
return
}
if (
deleted.providerSession &&
deleted.payload.agentType &&
deleted.payload.agentType !== 'unknown'
) {
const retained: EnrichedAgentHookEventPayload = {
...deleted,
providerSessionOnly: true,
retainedForLiveness: true
}
const retained = this.toRetainedProviderSessionRow(deleted)
if (retained) {
this.state.lastStatusByPaneKey.set(deleted.paneKey, retained)
}
this.scheduleStatusPersist()
this.notifyStatusChangeListeners()
}

/** Retire panes whose owning process is certifiably dead.
*
* The ordinary teardown already does this: every attributable PTY exit reaches
* `clearProviderPtyState`, which resolves the pane key and calls `clearPaneState`. But that
* resolution depends on the spawn-time `ptyPaneKey` mapping, which a restored/reattached PTY may
* never rebuild — so those panes keep a `working` row and its latches for good, with no hook left
* to retire them. This is the same operation reached from the runtime's own pane-key knowledge,
* so a dead pane is cleaned up identically however its keys were resolved. */
reconcileEndedProcessForPaneKeys(
paneKeys: Iterable<string>,
options?: {
/** The pane's PTY outlived its agent (a confirmed shell foreground), so the session can still
* be resumed in place — keep the `providerSessionOnly` remnant the paired `agentStatus:drop`
* minted for exactly this case. A certified PTY exit passes nothing: there is no pane left to
* resume into, and dropping it matches what `clearProviderPtyState` already does. */
preserveResumeIdentity?: boolean
}
): number {
let cleared = 0
for (const paneKey of paneKeys) {
const resolvedPaneKey = this.resolvePaneKeyAlias(paneKey)
if (!this.hasLiveClaimsForPaneKey(resolvedPaneKey)) {
continue
}
const retained = options?.preserveResumeIdentity
? this.toRetainedProviderSessionRow(
this.state.lastStatusByPaneKey.get(resolvedPaneKey) as
| EnrichedAgentHookEventPayload
| undefined
)
: null
this.clearPaneState(resolvedPaneKey)
if (retained) {
this.state.lastStatusByPaneKey.set(resolvedPaneKey, retained)
this.scheduleStatusPersist()
this.notifyStatusChangeListeners()
}
cleared += 1
}
return cleared
}

/** Anything a dead pane could still be asserting: a row, or a latch that would re-gate one through
* `resolveClaudePaneState` on the pane's next event even after the row reads `done`. The list
* itself lives beside `clearPaneCacheState`, so adding a latch cannot leave this behind in a
* different file. */
private hasLiveClaimsForPaneKey(paneKey: string): boolean {
return paneHasStateClaims(this.state, paneKey)
}

/** Clear statuses proven to belong to one lost SSH transport. */
clearStatusEntriesForConnection(connectionId: string): void {
const normalizedConnectionId = connectionId.trim()
Expand Down Expand Up @@ -2646,6 +2706,7 @@ export class AgentHookServer {
this.state.claudeLeadStateByPaneKey.delete(paneKey)
this.state.claudeRunningNonAgentTaskPaneKeys.delete(paneKey)
this.state.claudeActiveSessionCronPaneKeys.delete(paneKey)
this.state.claudeSessionOwnerByPaneKey.delete(paneKey)
}
}
}
Expand Down Expand Up @@ -2833,9 +2894,15 @@ export class AgentHookServer {
enriched.payload.agentType === 'claude' &&
enriched.connectionId === null &&
isLocalExecutionHost(enriched.worktreeId) &&
claudeRosterHasRestoredSnapshotSubagent(
// Why: a restored roster is only one shape of stranded claim. A lead row left non-terminal,
// or a background-task/cron latch nothing will refresh, strands the pane just as
// permanently — and unlike the roster case there is no child event left to reap it.
(claudeRosterHasRestoredSnapshotSubagent(
this.state.claudeSubagentRosterByPaneKey.get(paneKey)
) &&
) ||
enriched.payload.state !== 'done' ||
this.state.claudeRunningNonAgentTaskPaneKeys.has(paneKey) ||
this.state.claudeActiveSessionCronPaneKeys.has(paneKey)) &&
!this.runtimeObservedStatusPaneKeys.has(paneKey)
) {
candidates.push({ paneKey, entry: enriched })
Expand Down Expand Up @@ -2863,6 +2930,20 @@ export class AgentHookServer {
continue
}
if (!reapRestoredClaudeSubagentsForDeadPane(this.state, paneKey)) {
// Why: the roster reap only speaks for restored child rows. A pane whose PTY is provably
// gone and whose claim is a lead row or a latch has nothing for it to reap, so retire the
// pane the same way an observed exit would — otherwise the widened candidate set is inert.
//
// Why delete rather than downgrade to `done` like the reap branch below: that branch has a
// real turn to describe — a parent whose children it just reaped — while these panes' only
// claim IS the stale non-terminal row. Rewriting a `waiting`/`blocked` row to `done` would
// invent a completion that never happened, and leaving it non-terminal keeps the bug. This
// sweep stands in for the exit Orca never observed, so it does what that exit does:
// `clearProviderPtyState` -> `clearPaneState`.
if (this.hasLiveClaimsForPaneKey(paneKey)) {
this.clearPaneState(paneKey)
changedPanes += 1
}
continue
}
changedPanes += 1
Expand Down
3 changes: 3 additions & 0 deletions src/main/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2719,6 +2719,9 @@ void app.whenReady().then(async () => {
agentHookServer.attestCompatibilityAuthority(candidate),
retireAgentHookCompatibilityAuthority: (paneKey) =>
agentHookServer.retirePaneAuthority(paneKey),
reconcileAgentStatusForEndedProcess: (paneKeys) => {
agentHookServer.reconcileEndedProcessForPaneKeys(paneKeys)
},
canRecoverPersistentLocalPtys: () => getDaemonProvider() !== null,
// Why: source codex-home here (runs in window AND serve) so aiVault.listSessions includes managed-Codex sessions; registerCoreHandlers is window-only.
getAdditionalAiVaultCodexHomePaths: () =>
Expand Down
Loading