Skip to content

armgit / orca

Public Imported from GitHub
0

Orca is the place for working with a fleet of agents (e.g. Grok Bot, Claude Code). Run any coding agent with your own subscription. Available on desktop, mobile and remote runtime.

fix(agent-session): report an ACP or Pi CLI the supervisor could not spawn as missing (#36229)

Neil24795f5bd191
diff --git a/src/main/acp/acp-agent-connection.test.ts b/src/main/acp/acp-agent-connection.test.ts
index 9999dcf63cc..7e0bccfb3f6 100644
--- a/src/main/acp/acp-agent-connection.test.ts
+++ b/src/main/acp/acp-agent-connection.test.ts
@@ -12,6 +12,8 @@ import {
type AcpAgentConnectionOptions
} from './acp-agent-connection'
import { AcpAuthRequiredError } from './acp-errors'
+import { PROVIDER_SPAWN_FAILURE_MARKER } from '../provider-process/provider-spawn-failure-report'
+import { providerExecutableMissing } from '../provider-process/provider-executable-missing'
import { AcpScriptedAgent, deferred, tick } from './acp-scripted-agent.test-support'
const teardown = vi.hoisted(() =>
@@ -30,10 +32,16 @@ const grace =
process.platform === 'win32' ? ROOT_ONLY_GRACEFUL_EXIT_MS : PROVIDER_SUPERVISOR_MAX_STOP_MS
const start = { cwd: '/execution-host/folder', mcpServers: [] }
const prompt = [{ type: 'text', text: 'hello' }] as const
+/** What the supervisor writes when it cannot spawn the agent's CLI. */
+const SPAWN_ENOENT_REPORT = `${PROVIDER_SPAWN_FAILURE_MARKER}${JSON.stringify({
+ thrown: false,
+ code: 'ENOENT',
+ message: 'spawn fixture-acp-agent ENOENT'
+})}\n`
function fixture(
options: AcpAgentConnectionOptions = {},
- behavior: { pid?: number | null; exitOnEnd?: boolean } = {}
+ behavior: { pid?: number | null; exitOnEnd?: boolean; cwd?: string } = {}
) {
const agent = new AcpScriptedAgent()
const child = Object.assign(createFakePipedChild(), {
@@ -55,7 +63,7 @@ function fixture(
{
command: 'fixture-acp-agent',
args: ['--acp'],
- cwd: start.cwd,
+ cwd: behavior.cwd ?? start.cwd,
env: { ACP_ACCOUNT_HOME: '/host/account', STRIPPED: 'overlay' },
envToDelete: ['STRIPPED']
},
@@ -76,6 +84,22 @@ afterEach(async () => {
})
describe('ACP process-owning connection', () => {
+ // The supervisor (POSIX only) reports the failed spawn on stderr and exits 127.
+ it.skipIf(process.platform === 'win32')(
+ 'marks the exit of a CLI the supervisor could not spawn as a missing executable',
+ async () => {
+ const onExit = vi.fn()
+ const { connection, child } = fixture({ onExit }, { cwd: process.cwd() })
+ child.stderr.write(SPAWN_ENOENT_REPORT)
+ await tick()
+ child.emit('exit', 127, null)
+ child.emit('close', 127, null)
+ await vi.waitFor(() => expect(onExit).toHaveBeenCalledOnce())
+ expect(providerExecutableMissing(onExit.mock.calls[0][0])).toBe(true)
+ expect(connection.spawnAbsence).toBe('executable')
+ }
+ )
+
it('spawns through the supervisor with the host launch and exposes typed session calls', async () => {
const { connection, spawn, child, agent } = fixture()
await connection.spawned
diff --git a/src/main/acp/acp-agent-connection.ts b/src/main/acp/acp-agent-connection.ts
index cbc0dde48fa..516ce945d91 100644
--- a/src/main/acp/acp-agent-connection.ts
+++ b/src/main/acp/acp-agent-connection.ts
@@ -6,6 +6,10 @@ import {
type ProviderProcessExit
} from '../provider-process/managed-provider-process'
import type { ProviderProcessLaunch } from '../provider-process/provider-process-launch'
+import {
+ withProviderSpawnAbsence,
+ type ProviderSpawnAbsence
+} from '../provider-process/provider-executable-missing'
import { AcpConnectionClosedError, AcpSignInPromptError } from './acp-errors'
import { resolveAcpPeerOptions, type AcpPeerOptions } from './acp-peer-limits'
import { AcpSessionRuntime, type AcpSessionRuntimeOptions } from './acp-session-runtime'
@@ -138,9 +142,11 @@ export class AcpAgentConnection extends AcpSessionRuntime {
super.close(new AcpConnectionClosedError('The agent printed a sign-in link Orca cannot read'))
child.stderr.on('error', (error) => super.close(error))
managed.onExit((exit) => {
- const error =
+ const error = withProviderSpawnAbsence(
lifecycle.error ??
- new AcpConnectionClosedError(managed.stderrTail().trim() || `${launch.command} exited`)
+ new AcpConnectionClosedError(managed.stderrTail().trim() || `${launch.command} exited`),
+ managed.spawnAbsence
+ )
super.close(error)
try {
options.onExit?.(error, { expected: lifecycle.closing, exit })
@@ -162,6 +168,11 @@ export class AcpAgentConnection extends AcpSessionRuntime {
return this.managed.rootVerdict
}
+ /** What a spawn ENOENT proved absent: the agent's CLI or its launch folder. */
+ get spawnAbsence(): ProviderSpawnAbsence | null {
+ return this.managed.spawnAbsence
+ }
+
/** Null tree means no observation. */
get lastCloseResult(): Readonly<ManagedProviderProcess['lastCloseResult']> {
return this.managed.lastCloseResult
diff --git a/src/main/acp/acp-scripted-connection.test-fixture.ts b/src/main/acp/acp-scripted-connection.test-fixture.ts
index 09a1295b6dd..05f15498a1f 100644
--- a/src/main/acp/acp-scripted-connection.test-fixture.ts
+++ b/src/main/acp/acp-scripted-connection.test-fixture.ts
@@ -1,5 +1,9 @@
import type { ProviderProcessExit } from '../provider-process/managed-provider-process'
import type { ProviderProcessLaunch } from '../provider-process/provider-process-launch'
+import {
+ withProviderSpawnAbsence,
+ type ProviderSpawnAbsence
+} from '../provider-process/provider-executable-missing'
import type { AcpAgentConnectionOptions } from './acp-agent-connection'
import { AcpConnectionClosedError } from './acp-errors'
import { AcpSessionRuntime } from './acp-session-runtime'
@@ -11,6 +15,7 @@ export const PID = 4242
export class FakeAcpChild extends AcpSessionRuntime implements AcpStructuredConnection {
readonly agent: AcpScriptedAgent
readonly pid: number | undefined = PID
+ spawnAbsence: ProviderSpawnAbsence | null = null
readonly spawned = Promise.resolve()
stderr = ''
processTreeUnproven = false
@@ -73,8 +78,11 @@ export class FakeAcpChild extends AcpSessionRuntime implements AcpStructuredConn
return
}
this.exitedWith = status
- const error =
- this.lostWith ?? new AcpConnectionClosedError(this.stderr || `${this.launch.command} exited`)
+ // As the real connection: a spawn ENOENT marks the exit error with what it proved absent.
+ const error = withProviderSpawnAbsence(
+ this.lostWith ?? new AcpConnectionClosedError(this.stderr || `${this.launch.command} exited`),
+ this.spawnAbsence
+ )
super.close(error)
this.connectionOptions.onExit?.(error, { expected: this.closing, exit: status })
for (const listener of this.exitListeners.splice(0)) {
diff --git a/src/main/acp/acp-structured-child-lifecycle.ts b/src/main/acp/acp-structured-child-lifecycle.ts
index 48f0fb19624..158f0f1ed6f 100644
--- a/src/main/acp/acp-structured-child-lifecycle.ts
+++ b/src/main/acp/acp-structured-child-lifecycle.ts
@@ -4,7 +4,13 @@ import { ProviderAcquisitionStarts } from '../provider-process/provider-acquisit
import { isAcpReadySession, type AcpStructuredChild } from './acp-structured-child'
import type { AcpStructuredConnection } from './acp-structured-connection'
import { closeAcpSessionJournal, endAcpStructuredSession } from './acp-structured-session'
-import { agentSessionFailureFact, providerDiagnostic } from '../../shared/agent-session-failure'
+import {
+ agentSessionFailureFact,
+ providerDiagnostic,
+ type SubmissionRejectionFact
+} from '../../shared/agent-session-failure'
+import { withProviderSpawnAbsence } from '../provider-process/provider-executable-missing'
+import { providerStartupFailureFact } from '../native-chat/agent-session-wire/structured-agent-session-failure-text'
import {
ACP_STOP_GRACE_MS,
type AcpStructuredSessionAdapterDeps
@@ -15,6 +21,18 @@ import {
} from '../native-chat/agent-session-wire/structured-agent-session-logger'
import { windDownAcpTurn } from './acp-structured-stop'
+/** An agent that never ran names its missing CLI or folder; any other end while starting is its exit. */
+function acpStartupEndFailure(session: AcpStructuredChild): SubmissionRejectionFact {
+ const stderr = session.connection.stderrTail()
+ if (session.closeRequested) {
+ return agentSessionFailureFact('hostStopped', { detail: providerDiagnostic(stderr, 'person') })
+ }
+ const absence = session.connection.spawnAbsence
+ return absence
+ ? providerStartupFailureFact(withProviderSpawnAbsence(new Error(stderr), absence))
+ : agentSessionFailureFact('providerExited', { detail: providerDiagnostic(stderr, 'person') })
+}
+
export class AcpStructuredChildren {
readonly sessions = new Map<string, AcpStructuredChild>()
readonly starts = new ProviderAcquisitionStarts<AcpStructuredConnection>()
@@ -156,12 +174,7 @@ export class AcpStructuredChildren {
cause: session.closeRequested ? 'requested-close' : 'unexpected-exit',
reason:
session.connection.stderrTail() || `${session.spec.agent} ACP agent ended while starting`,
- failure: agentSessionFailureFact(
- session.closeRequested ? 'hostStopped' : 'providerExited',
- {
- detail: providerDiagnostic(session.connection.stderrTail(), 'person')
- }
- )
+ failure: acpStartupEndFailure(session)
})
}
if (this.sessions.get(session.sessionId) === session) {
diff --git a/src/main/acp/acp-structured-connection.ts b/src/main/acp/acp-structured-connection.ts
index f78fa4113cc..a4a3ded7c6a 100644
--- a/src/main/acp/acp-structured-connection.ts
+++ b/src/main/acp/acp-structured-connection.ts
@@ -16,6 +16,7 @@ export type AcpStructuredConnection = Pick<
| 'spawned'
| 'pid'
| 'exited'
+ | 'spawnAbsence'
| 'stderrTail'
| 'exitStatus'
| 'onExit'
diff --git a/src/main/acp/acp-structured-session-adapter.ts b/src/main/acp/acp-structured-session-adapter.ts
index 94b8a31bf87..c4a4dd83c44 100644
--- a/src/main/acp/acp-structured-session-adapter.ts
+++ b/src/main/acp/acp-structured-session-adapter.ts
@@ -21,6 +21,7 @@ import { rejectedAcpDispatch, type AcpStructuredSession } from './acp-structured
import type { ProviderStartAttempt } from '../provider-process/provider-acquisition-starts'
import { waitForAcpExit, type AcpStructuredConnection } from './acp-structured-connection'
import { AcpConnectionClosedError } from './acp-errors'
+import { withProviderSpawnAbsence } from '../provider-process/provider-executable-missing'
import { applyAcpMessageOptions } from './acp-message-execution-options'
import { AgentSessionOptionRejectedError } from '../native-chat/agent-session-wire/structured-agent-session-option-error'
import { awaitAcpTurnEnd, interruptAcpTurn } from './acp-structured-stop'
@@ -135,6 +136,10 @@ export class AcpStructuredSessionAdapter implements SessionAdapter {
)
throw connection ? closed : new AgentSessionPreSpawnError(closed)
}
+ // Once the exit is proven, the start's error names a CLI or folder the spawn found missing.
+ if (error instanceof Error && connection?.exited) {
+ withProviderSpawnAbsence(error, connection.spawnAbsence)
+ }
if (connection && exitedOnItsOwn && !isAgentSessionPreSpawnError(error)) {
throw new AgentSessionAcquisitionExitProvenError(
withObservedProviderExit(
diff --git a/src/main/acp/acp-structured-spawn-absence.test.ts b/src/main/acp/acp-structured-spawn-absence.test.ts
new file mode 100644
index 00000000000..5297878092d
--- /dev/null
+++ b/src/main/acp/acp-structured-spawn-absence.test.ts
@@ -0,0 +1,62 @@
+import { afterEach, describe, expect, it } from 'vitest'
+import { closeProviderTimelineRigs } from '../native-chat/agent-session-timeline/provider-timeline-assembler-test-support'
+import { providerStartupFailureFact } from '../native-chat/agent-session-wire/structured-agent-session-failure-text'
+import { openAcpAdapterRig, type AcpAdapterRig } from './acp-structured-adapter.test-support'
+import { AcpConnectionClosedError } from './acp-errors'
+
+afterEach(async () => {
+ await closeProviderTimelineRigs()
+})
+
+/** The supervisor's exit after it could not spawn the agent's CLI. */
+function spawnEnoent(rig: AcpAdapterRig): void {
+ const child = rig.child()
+ child.stderr = 'spawn grok ENOENT'
+ child.spawnAbsence = 'executable'
+ child.exit({ code: 127, signal: null, processless: false })
+}
+
+describe('an ACP CLI the supervisor could not spawn', () => {
+ it('ends a start that exits during the handshake as a missing CLI', async () => {
+ const rig = await openAcpAdapterRig({
+ script: (agent) => agent.on('initialize', () => spawnEnoent(rig))
+ })
+
+ await rig.acquire()
+
+ expect(rig.ended).toMatchObject([{ cause: 'unexpected-exit', failure: { kind: 'cliMissing' } }])
+ expect(providerStartupFailureFact(rig.openFailure())).toMatchObject({ kind: 'cliMissing' })
+ })
+
+ it('refuses an acquisition the exit lands in as a missing CLI', async () => {
+ const rig = await openAcpAdapterRig()
+
+ const refused = await rig.acquire({ onSpawned: async () => spawnEnoent(rig) }).then(
+ () => null,
+ (error: unknown) => error
+ )
+
+ expect(refused).toBeInstanceOf(Error)
+ expect(providerStartupFailureFact(refused)).toMatchObject({ kind: 'cliMissing' })
+ })
+
+ it('marks a start whose stream closed before the exit report, once its close proves the exit', async () => {
+ // No grace: the exit lands only when the adapter's close proves it.
+ const rig = await openAcpAdapterRig({ deps: { stopGraceMs: 0 } })
+
+ const refused = await rig
+ .acquire({
+ onSpawned: async () => {
+ rig.child().spawnAbsence = 'executable'
+ throw new AcpConnectionClosedError('the agent closed its stream')
+ }
+ })
+ .then(
+ () => null,
+ (error: unknown) => error
+ )
+
+ expect(rig.child().exited).toBe(true)
+ expect(providerStartupFailureFact(refused)).toMatchObject({ kind: 'cliMissing' })
+ })
+})
diff --git a/src/main/codex/codex-structured-session-close.ts b/src/main/codex/codex-structured-session-close.ts
index c436d9612f8..c3eba93b1a6 100644
--- a/src/main/codex/codex-structured-session-close.ts
+++ b/src/main/codex/codex-structured-session-close.ts
@@ -35,7 +35,8 @@ export function handleCodexSessionExit(input: {
sessionId: input.sessionId,
// Preserve the initiating close reason when its exit arrives.
reason: ((input.closedByOrca && session.orcaClose?.reason) || input.error).message,
- // Orca-initiated closes are host faults, regardless of the exit report.
+ // Orca-initiated closes are host faults, regardless of the exit report. No spawn ENOENT reaches
+ // here: a session registers only after the CLI answered thread/start, so the acquire path owns it.
failure: input.closedByOrca
? agentSessionFailureFact('hostFault')
: agentSessionFailureFact('providerExited', { detail: providerDiagnosticOf(input.error) }),
diff --git a/src/main/jsonl-rpc/agent-connection.test.ts b/src/main/jsonl-rpc/agent-connection.test.ts
index 2a2dcc2a883..c555aa90b05 100644
--- a/src/main/jsonl-rpc/agent-connection.test.ts
+++ b/src/main/jsonl-rpc/agent-connection.test.ts
@@ -6,6 +6,8 @@ import { ROOT_ONLY_GRACEFUL_EXIT_MS } from '../provider-process/provider-process
import { PROVIDER_SUPERVISOR_MAX_STOP_MS } from '../provider-process/provider-process-supervisor'
import type { terminateProviderProcessTree } from '../provider-process/provider-process-teardown'
import { JsonlRpcAgentConnection, type JsonlRpcAgentConnectionOptions } from './agent-connection'
+import { PROVIDER_SPAWN_FAILURE_MARKER } from '../provider-process/provider-spawn-failure-report'
+import { providerExecutableMissing } from '../provider-process/provider-executable-missing'
const teardown = vi.hoisted(() =>
vi.fn<typeof terminateProviderProcessTree>(async () => 'unverifiable')
@@ -14,12 +16,18 @@ vi.mock('../provider-process/provider-process-teardown', () => ({
terminateProviderProcessTree: teardown
}))
const opened: { connection: JsonlRpcAgentConnection; exit: () => void }[] = []
+/** What the supervisor writes when it cannot spawn the agent's CLI. */
+const SPAWN_ENOENT_REPORT = `${PROVIDER_SPAWN_FAILURE_MARKER}${JSON.stringify({
+ thrown: false,
+ code: 'ENOENT',
+ message: 'spawn fixture-rpc-agent ENOENT'
+})}\n`
const grace =
process.platform === 'win32' ? ROOT_ONLY_GRACEFUL_EXIT_MS : PROVIDER_SUPERVISOR_MAX_STOP_MS
function fixture(
options: JsonlRpcAgentConnectionOptions = {},
- behavior: { exitOnEnd?: boolean; processless?: boolean } = {}
+ behavior: { exitOnEnd?: boolean; processless?: boolean; cwd?: string } = {}
) {
const child = Object.assign(createFakePipedChild(), {
pid: behavior.processless ? undefined : 9_999_999,
@@ -38,7 +46,7 @@ function fixture(
{
command: 'fixture-rpc-agent',
args: ['--mode', 'rpc'],
- cwd: '/execution-host/folder',
+ cwd: behavior.cwd ?? '/execution-host/folder',
env: { PI_CODING_AGENT_DIR: '/host/account', STRIPPED: 'overlay' },
envToDelete: ['STRIPPED']
},
@@ -58,6 +66,25 @@ afterEach(async () => {
})
describe('JSON-lines RPC process ownership', () => {
+ // The supervisor (POSIX only) reports the failed spawn on stderr and exits 127.
+ it.skipIf(process.platform === 'win32')(
+ 'marks the exit of a CLI the supervisor could not spawn as a missing executable',
+ async () => {
+ const onExit = vi.fn()
+ const { connection, child } = fixture({ onExit }, { cwd: process.cwd() })
+ const pending = connection.request('get_state').catch((error: unknown) => error)
+ child.stderr.write(SPAWN_ENOENT_REPORT)
+ await new Promise((resolve) => setImmediate(resolve))
+ child.emit('exit', 127, null)
+ child.stdout.end()
+ child.emit('close', 127, null)
+ await vi.waitFor(() => expect(onExit).toHaveBeenCalledOnce())
+ expect(providerExecutableMissing(onExit.mock.calls[0][0])).toBe(true)
+ expect(providerExecutableMissing(await pending)).toBe(true)
+ expect(connection.spawnAbsence).toBe('executable')
+ }
+ )
+
it('uses host-resolved launch data and exposes ordinary RPC replies', async () => {
const { connection, child, spawn } = fixture()
expect(spawn).toHaveBeenCalledExactlyOnceWith(
diff --git a/src/main/jsonl-rpc/agent-connection.ts b/src/main/jsonl-rpc/agent-connection.ts
index e4dc3302f3d..9d5a9750cbf 100644
--- a/src/main/jsonl-rpc/agent-connection.ts
+++ b/src/main/jsonl-rpc/agent-connection.ts
@@ -8,6 +8,10 @@ import {
} from '../provider-process/managed-provider-process'
import type { ProviderProcessLaunch } from '../provider-process/provider-process-launch'
import type { ProviderProcessCloseResult } from '../provider-process/provider-process-close'
+import {
+ withProviderSpawnAbsence,
+ type ProviderSpawnAbsence
+} from '../provider-process/provider-executable-missing'
import {
JsonlRpcPeer,
JsonlRpcStreamClosedError,
@@ -80,13 +84,16 @@ export class JsonlRpcAgentConnection {
managed.child.stderr.on('error', this.onError)
managed.onExit((exit) => {
clearTimeout(this.streamExitTimer)
- const error = withProviderDiagnostic(
- new Error(
- exit.processless
- ? 'Agent process could not start'
- : `Agent process exited (code ${exit.code ?? 'none'}, signal ${exit.signal ?? 'none'})`
+ const error = withProviderSpawnAbsence(
+ withProviderDiagnostic(
+ new Error(
+ exit.processless
+ ? 'Agent process could not start'
+ : `Agent process exited (code ${exit.code ?? 'none'}, signal ${exit.signal ?? 'none'})`
+ ),
+ providerDiagnostic(managed.stderrTail(), 'person')
),
- providerDiagnostic(managed.stderrTail(), 'person')
+ managed.spawnAbsence
)
this.peer.finishOnInputEnd(error)
const stdout = managed.child.stdout
@@ -140,6 +147,10 @@ export class JsonlRpcAgentConnection {
get processless(): boolean {
return this.managed.processless
}
+ /** What a spawn ENOENT proved absent: the agent's CLI or its launch folder. */
+ get spawnAbsence(): ProviderSpawnAbsence | null {
+ return this.managed.spawnAbsence
+ }
get lastCloseResult(): ManagedProviderProcess['lastCloseResult'] {
return this.managed.lastCloseResult
}
diff --git a/src/main/pi/pi-scripted-child.test-fixture.ts b/src/main/pi/pi-scripted-child.test-fixture.ts
index 356570f9351..a8484650add 100644
--- a/src/main/pi/pi-scripted-child.test-fixture.ts
+++ b/src/main/pi/pi-scripted-child.test-fixture.ts
@@ -23,6 +23,7 @@ class ScriptedPiConnection implements PiRpcConnection {
closed = false
rootVerdict: PiRpcConnection['rootVerdict'] = 'live'
processless = false
+ spawnAbsence: PiRpcConnection['spawnAbsence'] = null
lastCloseResult: PiRpcConnection['lastCloseResult'] = null
readonly pid: number
readonly file: string
diff --git a/src/main/pi/rpc-exit-classification.ts b/src/main/pi/rpc-exit-classification.ts
new file mode 100644
index 00000000000..f6e4f582dc5
--- /dev/null
+++ b/src/main/pi/rpc-exit-classification.ts
@@ -0,0 +1,54 @@
+import {
+ agentSessionFailureFact,
+ providerDiagnostic,
+ providerDiagnosticOf,
+ type SubmissionRejectionFact
+} from '../../shared/agent-session-failure'
+import {
+ AgentSessionAcquisitionExitProvenError,
+ AgentSessionAcquisitionRootExitObservedError
+} from '../native-chat/agent-session-wire/structured-agent-session-adapter'
+import { providerStartupFailureFact } from '../native-chat/agent-session-wire/structured-agent-session-failure-text'
+import {
+ providerSpawnAbsent,
+ withProviderSpawnAbsence
+} from '../provider-process/provider-executable-missing'
+import { JsonlRpcResponseError } from '../jsonl-rpc/peer'
+import type { PiRpcConnection } from './rpc-session'
+
+/** How an unexpected Pi exit reads; a Pi that never ran names its missing CLI or folder. */
+export function piExitFailure(error: Error, cause: Error): SubmissionRejectionFact {
+ if (providerSpawnAbsent(error)) {
+ return providerStartupFailureFact(error)
+ }
+ return agentSessionFailureFact('providerExited', {
+ detail:
+ providerDiagnosticOf(cause) ??
+ providerDiagnosticOf(error) ??
+ (cause instanceof JsonlRpcResponseError
+ ? providerDiagnostic(cause.message, 'person')
+ : undefined)
+ })
+}
+
+/** What a failed Pi start throws once its close settled; null while the root's exit is unproven. */
+export function piStartExitError(
+ error: unknown,
+ connection: Pick<PiRpcConnection, 'processless' | 'spawnAbsence'>,
+ result: Awaited<ReturnType<PiRpcConnection['close']>> | null
+): Error | null {
+ if (result?.killDelivered && result.root !== 'exited') {
+ return new AgentSessionAcquisitionRootExitObservedError(error, 'kill-delivered')
+ }
+ if (result?.root !== 'exited') {
+ return null
+ }
+ // The start's own error may predate the exit report that proved the CLI or folder missing.
+ const cause = withProviderSpawnAbsence(
+ error instanceof Error ? error : new Error(String(error)),
+ connection.spawnAbsence
+ )
+ return connection.processless
+ ? new AgentSessionAcquisitionExitProvenError(cause)
+ : new AgentSessionAcquisitionRootExitObservedError(cause)
+}
diff --git a/src/main/pi/rpc-session-adapter.test-fixture.ts b/src/main/pi/rpc-session-adapter.test-fixture.ts
index c1f96760fea..050b610b45b 100644
--- a/src/main/pi/rpc-session-adapter.test-fixture.ts
+++ b/src/main/pi/rpc-session-adapter.test-fixture.ts
@@ -35,6 +35,7 @@ export class FakeConnection implements PiRpcConnection {
closed = false
rootVerdict: 'live' | 'unverifiable' | 'exited' = 'live'
processless = false
+ spawnAbsence: PiRpcConnection['spawnAbsence'] = null
deferExit = false
closeError?: Error
lastCloseResult: PiRpcConnection['lastCloseResult'] = null
diff --git a/src/main/pi/rpc-session-adapter.ts b/src/main/pi/rpc-session-adapter.ts
index 9ce016aaeee..e290cfc5b5c 100644
--- a/src/main/pi/rpc-session-adapter.ts
+++ b/src/main/pi/rpc-session-adapter.ts
@@ -5,7 +5,6 @@ import {
AgentSessionPreSpawnError,
AgentSessionAcquisitionRootExitObservedError,
AgentSessionAcquisitionExitUnprovenError,
- AgentSessionAcquisitionExitProvenError,
launchPreparationFailure,
type AgentSessionAcquisition,
type StructuredAgentSessionAcquireInput,
@@ -13,6 +12,7 @@ import {
} from '../native-chat/agent-session-wire/structured-agent-session-adapter'
import { providerSpawnedProcessIdentity } from '../provider-process/provider-spawned-process-identity'
import { ProviderAcquisitionStarts } from '../provider-process/provider-acquisition-starts'
+import { piStartExitError } from './rpc-exit-classification'
import { compactPiRpcSession } from './rpc-compaction'
import { buildPiRpcLaunch } from './rpc-launch'
import type { PiRpcResolvedLaunch } from './rpc-launch-resolution'
@@ -106,14 +106,9 @@ export class PiRpcSessionAdapter implements StructuredAgentSessionAdapter {
: new AgentSessionPreSpawnError(error)
}
const result = await session.close(false).catch(() => null)
- if (result?.killDelivered && result.root !== 'exited') {
- throw new AgentSessionAcquisitionRootExitObservedError(error, 'kill-delivered')
- }
- if (result?.root === 'exited') {
- if (session.connection.processless) {
- throw new AgentSessionAcquisitionExitProvenError(error)
- }
- throw new AgentSessionAcquisitionRootExitObservedError(error)
+ const exited = piStartExitError(error, session.connection, result)
+ if (exited) {
+ throw exited
}
this.starts.retainFailed(id, session.connection)
throw new AgentSessionAcquisitionExitUnprovenError(error)
diff --git a/src/main/pi/rpc-session-spawn-absence.test.ts b/src/main/pi/rpc-session-spawn-absence.test.ts
new file mode 100644
index 00000000000..74741fe9f36
--- /dev/null
+++ b/src/main/pi/rpc-session-spawn-absence.test.ts
@@ -0,0 +1,42 @@
+import { afterEach, describe, expect, it } from 'vitest'
+import { withMissingProviderExecutable } from '../provider-process/provider-executable-missing'
+import { providerStartupFailureFact } from '../native-chat/agent-session-wire/structured-agent-session-failure-text'
+import {
+ closePiRpcAdapterFixtures,
+ reportedEvent,
+ restart,
+ setup
+} from './rpc-session-adapter.test-fixture'
+
+afterEach(closePiRpcAdapterFixtures)
+
+describe('a Pi CLI the supervisor could not spawn', () => {
+ it('ends the session as a missing CLI, not a provider exit', async () => {
+ const h = await setup()
+
+ h.connection.exit(
+ withMissingProviderExecutable(new Error('Agent process exited (code 127, signal none)'))
+ )
+ await h.adapter.drainObservedExits()
+
+ expect(reportedEvent(h.lifecycle, 'ended')).toMatchObject({
+ cause: 'unexpected-exit',
+ failure: { kind: 'cliMissing' }
+ })
+ })
+
+ it('refuses the start as a missing CLI when it exits while acquiring', async () => {
+ const h = await setup()
+
+ const refused = await restart(h, (child) => {
+ child.spawnAbsence = 'executable'
+ child.closed = true
+ }).then(
+ () => null,
+ (error: unknown) => error
+ )
+
+ expect(refused).toBeInstanceOf(Error)
+ expect(providerStartupFailureFact(refused)).toMatchObject({ kind: 'cliMissing' })
+ })
+})
diff --git a/src/main/pi/rpc-session.ts b/src/main/pi/rpc-session.ts
index f9c974d2df9..0b95575eaa9 100644
--- a/src/main/pi/rpc-session.ts
+++ b/src/main/pi/rpc-session.ts
@@ -1,8 +1,3 @@
-import {
- agentSessionFailureFact,
- providerDiagnostic,
- providerDiagnosticOf
-} from '../../shared/agent-session-failure'
import type {
StructuredAgentSessionAcquireInput,
StructuredAgentSessionLifecycleEvent,
@@ -16,7 +11,7 @@ import {
type JsonlRpcAgentConnectionOptions
} from '../jsonl-rpc/agent-connection'
import type { ProviderProcessLaunch } from '../provider-process/provider-process-launch'
-import { JsonlRpcResponseError } from '../jsonl-rpc/peer'
+import { piExitFailure } from './rpc-exit-classification'
import { PiRpcTurns } from './rpc-turns'
import { PiRpcDialogCallbacks } from './rpc-dialog-callbacks'
import { PiRpcOptionObservations, type PiRpcOptionWrite } from './rpc-options'
@@ -37,6 +32,7 @@ export type PiRpcConnection = Pick<
| 'closed'
| 'rootVerdict'
| 'processless'
+ | 'spawnAbsence'
| 'lastCloseResult'
| 'onExit'
>
@@ -293,14 +289,7 @@ export class PiRpcSession {
observedAt,
cause: this.requestedClose ? 'requested-close' : 'unexpected-exit',
reason: cause.message,
- failure: agentSessionFailureFact('providerExited', {
- detail:
- providerDiagnosticOf(cause) ??
- providerDiagnosticOf(error) ??
- (cause instanceof JsonlRpcResponseError
- ? providerDiagnostic(cause.message, 'person')
- : undefined)
- })
+ failure: piExitFailure(error, cause)
})
}