Share the managed process lifecycle for structured providers

src/main/claude/claude-agent-sdk-exit-proof.test.ts

@@ -11,6 +11,7 @@ import {
   proveClaudeChildExit,
   type ClaudeChildTreeReaper
 } from './claude-agent-sdk-exit-proof'
+import { managedChild } from './claude-child-exit-proof-fixture'
 import { GRACEFUL_EXIT_MS } from './claude-child-exit-proof-ladder'
 
 // The descendant models an MCP server: it either cooperates or, when it traps
@@ -99,11 +100,13 @@ async function proveExitWithRetries(
 }
 
 function spawnScript(script: string): ReturnType<typeof spawnProcess> {
-  return spawnProcess({
+  const child = spawnProcess({
     program: process.execPath,
     args: ['-e', script],
     stdio: ['pipe', 'pipe', 'pipe']
   })
+  managedChild(child)
+  return child
 }
 
 function firstStdoutLine(child: ReturnType<typeof spawnProcess>): Promise<string> {
@@ -112,28 +115,19 @@ function firstStdoutLine(child: ReturnType<typeof spawnProcess>): Promise<string
   })
 }
 
-function observeExit(child: EventEmitter): { exitPromise: Promise<void>; exited: () => boolean } {
-  let exited = false
-  const exitPromise = new Promise<void>((resolve) => {
-    child.once('exit', () => {
-      exited = true
-      resolve()
-    })
-  })
-  return { exitPromise, exited: () => exited }
-}
-
 /** `null` models a spawn that failed before a pid existed. */
 function mockChild(
   pid: number | null = 424242
 ): EventEmitter &
-  Pick<SpawnedProcess, 'pid' | 'kill' | 'stdin'> & { kill: ReturnType<typeof vi.fn> } {
-  const child = new EventEmitter()
-  return Object.assign(child, {
+  Pick<SpawnedProcess, 'pid' | 'kill' | 'stdin' | 'stderr'> & { kill: ReturnType<typeof vi.fn> } {
+  const child = Object.assign(new EventEmitter(), {
     pid: pid ?? undefined,
     stdin: new PassThrough(),
+    stderr: new PassThrough(),
     kill: vi.fn(() => true)
-  }) as never
+  })
+  // oxlint-disable-next-line typescript/consistent-type-assertions -- SAFETY: The proof reads only pid, events, kill, stdin and stderr from this fixture.
+  return child as never
 }
 
 /** A tree whose verdict is scripted per reap, recording when it was armed. */
@@ -200,7 +194,7 @@ describe('claude child exit proof', () => {
       await ageDescendantPastTheCaptureSecond()
 
       try {
-        const proven = await proveExitWithRetries({ child, ...observeExit(child) })
+        const proven = await proveExitWithRetries({ managed: managedChild(child) })
         // Evaluated AT the boundary, not by polling until a deferred sweep timer
         // wins: true releases the lease, so a descendant still running here is
         // exactly the orphan the proof exists to prevent. False would be the
@@ -237,7 +231,7 @@ describe('claude child exit proof', () => {
       await ageDescendantPastTheCaptureSecond()
 
       try {
-        const proven = await proveExitWithRetries({ child, ...observeExit(child) })
+        const proven = await proveExitWithRetries({ managed: managedChild(child) })
         expect({ proven, descendant: descendantState(descendantPid) }).toEqual({
           proven: true,
           descendant: 'exited'
@@ -263,7 +257,7 @@ describe('claude child exit proof', () => {
         descendantPid: number
       }
       try {
-        const proven = await proveExitWithRetries({ child, ...observeExit(child) })
+        const proven = await proveExitWithRetries({ managed: managedChild(child) })
         expect({ proven, descendant: descendantState(descendantPid) }).toEqual({
           proven: true,
           descendant: 'exited'
@@ -282,36 +276,34 @@ describe('claude child exit proof', () => {
   it('arms the snapshot before stdin closes and verifies it after a clean exit', async () => {
     const child = spawnScript(COOPERATIVE_CHILD)
     expect(await firstStdoutLine(child)).toBe('ready')
-    const exit = observeExit(child)
+    const managed = managedChild(child)
     const tree = mockTree(['exited'])
     let exitedWhenArmed: boolean | null = null
     tree.capture.mockImplementation(async () => {
-      exitedWhenArmed = exit.exited()
+      exitedWhenArmed = managed.rootVerdict === 'exited'
     })
 
-    await expect(proveClaudeChildExit({ child, ...exit, tree })).resolves.toBe(true)
+    await expect(proveClaudeChildExit({ managed, tree })).resolves.toBe(true)
     // The snapshot is the only proof that survives the root: taken while it lived,
     // verified once it left. A reap before the exit would have been the forced ladder.
     expect(exitedWhenArmed).toBe(false)
     expect(tree.reap).toHaveBeenCalledTimes(1)
-    expect(exit.exited()).toBe(true)
+    expect(managed.rootVerdict).toBe('exited')
   }, 20_000)
 
   it('proves a clean close of a childless root with one snapshot and no signal', async () => {
     const child = spawnScript(COOPERATIVE_CHILD)
     expect(await firstStdoutLine(child)).toBe('ready')
 
-    await expect(proveClaudeChildExit({ child, ...observeExit(child) })).resolves.toBe(true)
+    await expect(proveClaudeChildExit({ managed: managedChild(child) })).resolves.toBe(true)
   }, 20_000)
 
   it('reports an unprovable exit as false rather than assuming the child died', async () => {
     vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] })
     try {
       const tree = mockTree(['exited'])
       const proof = proveClaudeChildExit({
-        child: mockChild(),
-        exitPromise: new Promise<void>(() => {}),
-        exited: () => false,
+        managed: managedChild(mockChild()),
         tree
       })
       await new Promise((resolve) => setImmediate(resolve))
@@ -330,18 +322,18 @@ describe('claude child exit proof', () => {
     vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] })
     try {
       const child = mockChild()
-      const exit = observeExit(child)
+      const managed = managedChild(child)
       const tree = mockTree(['live'])
       tree.reap.mockImplementation(async () => {
         child.emit('exit', null, 'SIGKILL')
         return 'live'
       })
-      const proof = proveClaudeChildExit({ child, ...exit, tree })
+      const proof = proveClaudeChildExit({ managed, tree })
       await new Promise((resolve) => setImmediate(resolve))
       await vi.advanceTimersByTimeAsync(GRACEFUL_EXIT_MS)
 
       await expect(proof).resolves.toBe(false)
-      expect(exit.exited()).toBe(true)
+      expect(managed.rootVerdict).toBe('exited')
       // One verification per attempt: the retried close re-verifies, this one does not.
       expect(tree.reap).toHaveBeenCalledTimes(1)
       expect(vi.getTimerCount()).toBe(0)
@@ -352,16 +344,18 @@ describe('claude child exit proof', () => {
 
   it('re-verifies an unproven tree on a retried close instead of trusting the dead root', async () => {
     const child = mockChild()
+    const managed = managedChild(child)
+    child.emit('exit', 0, null)
     const tree = mockTree(['exited'])
 
-    await expect(
-      proveClaudeChildExit({ child, exitPromise: Promise.resolve(), exited: () => true, tree })
-    ).resolves.toBe(true)
+    await expect(proveClaudeChildExit({ managed, tree })).resolves.toBe(true)
     expect(tree.reap).toHaveBeenCalledTimes(1)
   })
 
   it('stays unproven for a root that left before any snapshot could be armed', async () => {
     const child = mockChild()
+    const managed = managedChild(child)
+    child.emit('exit', 0, null)
     const captureDescendants = vi.fn(async () => snapshotOf(4243))
     const terminateDescendants = vi.fn()
     const tree = createClaudeChildTreeReaper(child, {
@@ -371,9 +365,7 @@ describe('claude child exit proof', () => {
       terminateDescendants
     })
 
-    await expect(
-      proveClaudeChildExit({ child, exitPromise: Promise.resolve(), exited: () => true, tree })
-    ).resolves.toBe(false)
+    await expect(proveClaudeChildExit({ managed, tree })).resolves.toBe(false)
     // A dead root's descendants have reparented: walking its pid now could only
     // sweep a stranger, so no walk is attempted and nothing is proven.
     expect(captureDescendants).not.toHaveBeenCalled()

src/main/claude/claude-agent-sdk-exit-proof.ts

@@ -361,6 +361,8 @@ export function createClaudeChildTreeReaper(
  */
 export function proveClaudeChildExit(input: ClaudeChildExitProofInput): Promise<boolean> {
   return proveClaudeChildExitWithReaper(input, () =>
-    createClaudeChildTreeReaper(input.child, { exited: input.exited })
+    createClaudeChildTreeReaper(input.managed.child, {
+      exited: () => input.managed.rootVerdict === 'exited'
+    })
   )
 }

src/main/claude/claude-agent-sdk-process-spawn.test.ts

@@ -121,32 +121,21 @@ describe('claude agent SDK process spawn', () => {
       spawn.spawn(sdkOptions())
       expect(spawn.supervised).toBe(specSupervised)
 
-      let exited = false
-      let settle = (): void => {}
-      const exitPromise = new Promise<void>((resolve) => {
-        settle = resolve
-      })
-      // Claude leaves shortly after stdin ends, so the ladder never needs its forced rung.
+      const managed = spawn.managed
+      if (!managed) {
+        throw new Error('Claude spawner did not retain its managed child')
+      }
+      // Claude leaves shortly after stdin ends, before the forced stop.
       process.child.stdin.on('finish', () =>
-        setTimeout(() => {
-          exited = true
-          settle()
-        }, 10)
+        setTimeout(() => process.child.emit('exit', 0, null), 10)
       )
       const tree = {
         capture: vi.fn(async () => {}),
         reap: vi.fn(async () => 'exited' as const),
         treeVerdict: 'exited' as const
       }
-      await proveClaudeChildExitWithReaper(
-        {
-          child: process.child,
-          exitPromise,
-          exited: () => exited,
-          tree,
-          supervised: spawn.supervised
-        },
-        () => tree
+      await expect(proveClaudeChildExitWithReaper({ managed, tree }, () => tree)).resolves.toBe(
+        true
       )
       // SIGTERM to an unsupervised Claude on Windows is TerminateProcess; a skipped one leaves it running.
       if (specSupervised) {
@@ -176,8 +165,8 @@ describe('claude agent SDK process spawn', () => {
     process.child.stderr.write('claude: not signed in')
     await new Promise((resolve) => setImmediate(resolve))
 
-    expect(spawn.stderrTail).toMatch(/claude: not signed in$/)
-    expect(spawn.stderrTail.length).toBe(8192)
+    expect(spawn.managed?.stderrTail()).toMatch(/claude: not signed in$/)
+    expect(spawn.managed?.stderrTail().length).toBe(8192)
   })
 
   it('hands a Windows .cmd shim to Orca\u2019s argument encoder', () => {

src/main/claude/claude-agent-sdk-process-spawn.ts

@@ -1,25 +1,27 @@
 import type { SpawnOptions as ClaudeAgentSdkSpawnOptions } from '@anthropic-ai/claude-agent-sdk'
 import { spawnProcess } from '../../shared/child-process/run-process'
-import { createProviderSpawnSpec } from '../provider-process/provider-process-supervisor'
+import {
+  spawnManagedProviderProcess,
+  type ManagedProviderProcess
+} from '../provider-process/managed-provider-process'
+import { claudeChildClosePolicy } from './claude-child-exit-proof-ladder'
 
 /** Derived rather than imported: only src/shared/child-process may name node:child_process. */
 type ClaudeCodeChild = ReturnType<typeof spawnProcess>
 
-const STDERR_TAIL_MAX_BYTES = 8192
-
 export type ClaudeCodeProcessSpawn = {
   /** Pass as the SDK's `spawnClaudeCodeProcess`; the SDK never learns the pid because it never owns it. */
   spawn: (options: ClaudeAgentSdkSpawnOptions) => ClaudeCodeChild
   /** The retained child, so Orca keeps its own tree-kill and exit-proof ladder. Null until the SDK spawns. */
   readonly child: ClaudeCodeChild | null
+  readonly managed: ManagedProviderProcess | null
   /**
    * Ownership proof: the durable lease adjudicates on this pid plus start time plus the spawn
    * token. On POSIX it is the provider supervisor's, which outlives Claude by construction.
    */
   readonly pid: number | undefined
   /** The spawn spec's verdict, so the close ladder never re-decides it. False until the SDK spawns. */
   readonly supervised: boolean
-  readonly stderrTail: string
 }
 
 function definedEnv(env: Record<string, string | undefined>): Record<string, string> {
@@ -46,50 +48,39 @@ export function createClaudeCodeProcessSpawn(
   spawnImpl: typeof spawnProcess = spawnProcess,
   platform: NodeJS.Platform = process.platform
 ): ClaudeCodeProcessSpawn {
-  let child: ClaudeCodeChild | null = null
-  let stderrTail = ''
-  let supervised = false
+  let managed: ManagedProviderProcess | null = null
   return {
     spawn: (options) => {
-      const spec = createProviderSpawnSpec(
+      // SDK abort would kill the child outside Orca's ladder, losing observed exit proof.
+      managed = spawnManagedProviderProcess(
         {
           command: options.command,
           args: [...options.args],
           ...(options.cwd === undefined ? {} : { cwd: options.cwd })
         },
-        definedEnv(options.env),
-        platform
+        {
+          spawnImpl,
+          platform,
+          inheritedEnv: definedEnv(options.env),
+          site: 'claude-stream-json-teardown',
+          policy: claudeChildClosePolicy,
+          acceptClose: (result) => result.root === 'exited' && result.tree === 'exited'
+        }
       )
-      // Why `options.signal` is dropped: it would let the SDK kill the child outside
-      // Orca's ladder, and close() may never report an exit it did not observe.
-      const spawned = spawnImpl({
-        program: spec.program,
-        args: spec.args,
-        cwd: spec.cwd,
-        env: spec.env,
-        detached: spec.detached,
-        stdio: ['pipe', 'pipe', 'pipe']
-      })
-      child = spawned
-      supervised = spec.supervised
-      // The SDK drains stderr only for its own local spawn, so a custom spawner must:
-      // otherwise the child blocks on a full pipe and exit errors lose their tail.
-      spawned.stderr.setEncoding('utf8').on('data', (chunk: string) => {
-        stderrTail = (stderrTail + chunk).slice(-STDERR_TAIL_MAX_BYTES)
-      })
-      return spawned
+      // The SDK drains stderr only for its own local spawn; the managed process drains it here.
+      return managed.child
     },
     get child() {
-      return child
+      return managed?.child ?? null
+    },
+    get managed() {
+      return managed
     },
     get pid() {
-      return child?.pid
+      return managed?.child.pid
     },
     get supervised() {
-      return supervised
-    },
-    get stderrTail() {
-      return stderrTail
+      return managed?.supervised ?? false
     }
   }
 }

src/main/claude/claude-child-exit-proof-fixture.ts

@@ -0,0 +1,31 @@
+import type { EventEmitter } from 'node:events'
+import type { spawnProcess, SpawnedProcess } from '../../shared/child-process/run-process'
+import {
+  spawnManagedProviderProcess,
+  type ManagedProviderProcess
+} from '../provider-process/managed-provider-process'
+import { claudeChildClosePolicy } from './claude-child-exit-proof-ladder'
+
+const managedChildren = new WeakMap<object, ManagedProviderProcess>()
+
+export function managedChild(
+  child: Pick<SpawnedProcess, 'pid' | 'kill' | 'stdin' | 'stderr'> & EventEmitter
+): ManagedProviderProcess {
+  const existing = managedChildren.get(child)
+  if (existing) {
+    return existing
+  }
+  const managed = spawnManagedProviderProcess(
+    { command: 'fixture-provider', args: [] },
+    {
+      // oxlint-disable-next-line typescript/consistent-type-assertions -- SAFETY: The managed process reads only the fixture's owned pid, events, kill, stdin and stderr.
+      spawnImpl: () => child as ReturnType<typeof spawnProcess>,
+      platform: 'win32',
+      site: 'claude-proof-fixture',
+      policy: claudeChildClosePolicy,
+      acceptClose: (result) => result.root === 'exited' && result.tree === 'exited'
+    }
+  )
+  managedChildren.set(child, managed)
+  return managed
+}