rnxsim 0.1.313 → 0.1.315

package/cli/commands/agent-wrapper.ts

@@ -0,0 +1,986 @@
+// agent-wrapper — long-running bridge process between sootsim desktop and a
+// local coding agent (codex / claude).
+//
+// shipped as an internal sootsim CLI subcommand so it survives `bun build
+// --compile` bundling. callers spawn it as:
+//
+//   sootsim agent-wrapper \
+//     --session-id <id> --project-id <id> --provider codex \
+//     --cwd <path> --prompt-in <fifo> --events-out <fifo> \
+//     [--transcript <file>]
+//
+// protocol:
+//   prompt.in  — newline-delimited prompt text from electron / the CLI.
+//   events.out — newline-delimited JSON events (see `sootsim/agent-events`).
+//   transcript — append-only raw stdout/stderr of the spawned agent turn.
+//
+// stage 7 scope (codex): replaced the per-turn `codex exec` spawn with a
+// persistent `codex app-server` JSON-RPC child. one thread/start per session
+// (or thread/resume if we find a prior thread for the cwd), one turn/start
+// per prompt. notifications are translated into structured AgentEvents with
+// real filesTouched, file-diff deltas, and plan updates.
+//
+// claude still uses the stage 3 per-turn spawn via `claude -p`; stage 8
+// replaces it with `--output-format stream-json --verbose --resume`.
+
+import { execFile, spawn, type ChildProcess } from 'node:child_process'
+import { randomUUID } from 'node:crypto'
+import {
+  constants as fsConstants,
+  createReadStream,
+  createWriteStream,
+  existsSync,
+  openSync,
+} from 'node:fs'
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import readline from 'node:readline'
+import { promisify } from 'node:util'
+import { decodeAgentPromptEnvelope } from '../../src/agent-prompt'
+import { spawnCodexClient, type CodexClient } from '../../src/codex-client'
+import type { AgentEvent } from '../../src/agent-events'
+
+const CODEX_APPROVAL_POLICY = 'never'
+const CODEX_THREAD_SANDBOX = 'danger-full-access'
+const CODEX_TURN_SANDBOX_POLICY = { type: 'dangerFullAccess' } as const
+const CODEX_SERVICE_TIER = 'fast' as const
+const CODEX_REASONING_EFFORT = 'medium' as const
+
+const execFileP = promisify(execFile)
+
+async function resolveAgentBinary(
+  provider: 'codex' | 'claude',
+  override: string | undefined,
+): Promise<{ ok: true; path: string } | { ok: false; message: string }> {
+  const bin = override || provider
+  // absolute or relative path — check directly
+  if (bin.includes('/') || bin.includes('\\')) {
+    if (existsSync(bin)) return { ok: true, path: bin }
+    return { ok: false, message: `agent binary not found at path: ${bin}` }
+  }
+  try {
+    const { stdout } = await execFileP('which', [bin], { timeout: 1500 })
+    const resolved = stdout.trim()
+    if (resolved) return { ok: true, path: resolved }
+    return { ok: false, message: `${bin} not found on PATH` }
+  } catch {
+    return {
+      ok: false,
+      message:
+        `${bin} not found on PATH. install the ${provider} CLI and retry, or pass ` +
+        `--${provider}-bin /path/to/${provider} to agent start.`,
+    }
+  }
+}
+
+interface WrapperArgs {
+  sessionId?: string
+  projectId?: string
+  provider?: string
+  cwd?: string
+  promptIn?: string
+  eventsOut?: string
+  transcript?: string
+  codexBin?: string
+  claudeBin?: string
+  claudeSessionUuid?: string
+  freshThread?: boolean
+}
+
+function parseWrapperArgs(argv: string[]): WrapperArgs {
+  const map: Record<string, keyof WrapperArgs> = {
+    '--session-id': 'sessionId',
+    '--project-id': 'projectId',
+    '--provider': 'provider',
+    '--cwd': 'cwd',
+    '--prompt-in': 'promptIn',
+    '--events-out': 'eventsOut',
+    '--transcript': 'transcript',
+    '--codex-bin': 'codexBin',
+    '--claude-bin': 'claudeBin',
+    '--claude-session-uuid': 'claudeSessionUuid',
+  }
+  const out: WrapperArgs = {}
+  for (let i = 0; i < argv.length; i++) {
+    const flag = argv[i]
+    if (flag === '--fresh-thread') {
+      out.freshThread = true
+      continue
+    }
+    const key = map[flag]
+    if (!key) continue
+    out[key] = argv[i + 1] as never
+    i++
+  }
+  return out
+}
+
+/** drives one prompt end-to-end. emits turn-started on entry and exactly one
+ *  terminal event (turn-completed OR error) before resolving. never throws. */
+type TurnRunner = (text: string) => Promise<void>
+
+export async function runAgentWrapper(argv: string[]): Promise<number> {
+  const args = parseWrapperArgs(argv)
+
+  if (
+    !args.sessionId ||
+    !args.projectId ||
+    !args.provider ||
+    !args.cwd ||
+    !args.promptIn ||
+    !args.eventsOut
+  ) {
+    process.stderr.write(
+      'usage: rnxsim agent-wrapper --session-id <id> --project-id <id>\n' +
+        '                            --provider codex|claude --cwd <path>\n' +
+        '                            --prompt-in <fifo> --events-out <fifo>\n' +
+        '                            [--transcript <file>]\n' +
+        '                            [--codex-bin <path>] [--claude-bin <path>]\n',
+    )
+    return 2
+  }
+  if (args.provider !== 'codex' && args.provider !== 'claude') {
+    process.stderr.write(`unknown provider: ${args.provider}\n`)
+    return 2
+  }
+
+  const { sessionId, projectId, cwd, promptIn, eventsOut } = args
+  const provider = args.provider as 'codex' | 'claude'
+
+  // keep the events.out write end open for the whole process lifetime. opening
+  // and closing per event would SIGPIPE briefly between writers.
+  //
+  // IMPORTANT: open with O_RDWR (not O_WRONLY/'a') so the wrapper itself
+  // holds a reader fd on the FIFO. without this, the bootstrap reader
+  // (startSession's waitForFirstEvent) attaches briefly to consume `ready`,
+  // then closes — leaving the wrapper's O_WRONLY fd as the only handle on
+  // a reader-less FIFO. the next write (prompt-received / turn-started /
+  // turn-message …) triggers SIGPIPE / EPIPE and the wrapper dies silently
+  // before any client ws subscription lands. O_RDWR makes the FIFO appear
+  // to always have a reader, so writes buffer in the kernel until the
+  // daemon attaches to drain.
+  if (!existsSync(eventsOut)) {
+    process.stderr.write(`events-out FIFO missing: ${eventsOut}\n`)
+    return 3
+  }
+  if (!existsSync(promptIn)) {
+    process.stderr.write(`prompt-in FIFO missing: ${promptIn}\n`)
+    return 3
+  }
+  const eventsFd = openSync(eventsOut, fsConstants.O_RDWR | fsConstants.O_APPEND)
+  const eventsStream = createWriteStream(eventsOut, { fd: eventsFd, flags: 'a' })
+
+  function emit(event: Partial<AgentEvent> & { type: AgentEvent['type'] }): void {
+    const line = JSON.stringify({ ts: Date.now(), ...event }) + '\n'
+    eventsStream.write(line)
+  }
+
+  // transcript is optional; append mode so multiple turns accumulate.
+  let transcriptStream: ReturnType<typeof createWriteStream> | null = null
+  if (args.transcript) {
+    try {
+      await fs.mkdir(path.dirname(args.transcript), { recursive: true })
+      transcriptStream = createWriteStream(args.transcript, { flags: 'a' })
+    } catch (err) {
+      emit({
+        type: 'error',
+        message: `transcript open failed: ${(err as Error).message}`,
+      } as AgentEvent)
+    }
+  }
+
+  // defensive: an EPIPE from a stale reader would otherwise bubble to
+  // uncaughtException and tear the wrapper down mid-turn. the O_RDWR open
+  // above prevents the common case, but a rogue close on the read side
+  // can still briefly surface here. log it and move on — the FIFO
+  // self-heals on the next reader attach.
+  eventsStream.on('error', (err) => {
+    const message = `[events-out] stream error: ${(err as Error).message}\n`
+    try {
+      if (transcriptStream) transcriptStream.write(message)
+      else process.stderr.write(message)
+    } catch {}
+  })
+
+  // preflight: resolve the agent binary once up front. emitting ready without
+  // this check means the first `agent prompt` silently completes with an empty
+  // turn-completed — users think "the agent said nothing" instead of "codex
+  // isn't installed."
+  const bin = await resolveAgentBinary(
+    provider,
+    provider === 'codex' ? args.codexBin : args.claudeBin,
+  )
+  if (!bin.ok) {
+    emit({ type: 'error', message: bin.message } as AgentEvent)
+    // give the reader a moment to drain before we exit
+    await new Promise((r) => setTimeout(r, 50))
+    eventsStream.end()
+    return 4
+  }
+  const resolvedAgentBin = bin.path
+
+  // for codex: boot the persistent app-server now. any startup failure is a
+  // clean error event before we advertise ready.
+  let codexClient: CodexClient | null = null
+  let codexThreadId: string | null = null
+  if (provider === 'codex') {
+    try {
+      codexClient = spawnCodexClient({
+        bin: resolvedAgentBin,
+        cwd,
+        env: {
+          SOOTSIM_CLI_IDENTITY: sessionId,
+          SOOTSIM_PROJECT_ID: projectId,
+        },
+      })
+      // surface stderr into the transcript without cluttering events.
+      codexClient.on('__stderr__', (p) => {
+        const text = (p as { text?: string })?.text
+        if (text) transcriptStream?.write(`[codex-stderr] ${text}`)
+      })
+      // capture async errors so they don't kill the wrapper silently.
+      void codexClient.exited.then(({ code, signal }) => {
+        if (!shuttingDown) {
+          emit({
+            type: 'error',
+            message: `codex app-server exited (code=${code}, signal=${signal ?? ''})`,
+          } as AgentEvent)
+          shutdown(5)
+        }
+      })
+      // 30s cap on the boot sequence — if codex hangs on init/thread setup,
+      // emit an error instead of silently never advertising ready.
+      await withTimeout(
+        (async () => {
+          await codexClient!.request('initialize', {
+            clientInfo: { name: 'sootsim', title: null, version: '0.1.0' },
+            capabilities: null,
+          })
+          // prefer an existing non-archived thread for this cwd unless the
+          // caller explicitly asked for a fresh one.
+          codexThreadId = await resolveCodexThread(codexClient!, cwd, {
+            fresh: args.freshThread === true,
+          })
+        })(),
+        30_000,
+        'codex app-server boot timed out after 30s',
+      )
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err)
+      emit({
+        type: 'error',
+        message: `codex app-server init failed: ${message}`,
+      } as AgentEvent)
+      try {
+        codexClient?.kill()
+      } catch {}
+      eventsStream.end()
+      return 4
+    }
+  }
+
+  emit({
+    type: 'ready',
+    sessionId,
+    projectId,
+    provider,
+    cwd,
+  } as AgentEvent)
+
+  // serialize turn execution per-session — queue prompts while one is in
+  // flight. both codex and claude serialize per-session internally, but
+  // gating here keeps wrapper event ordering honest.
+  let turnInFlight = false
+  let currentClaudeChild: ChildProcess | null = null
+  const pendingPrompts: string[] = []
+
+  const { promise: exitPromise, resolve: resolveExit } = createDeferred<number>()
+
+  let shuttingDown = false
+  function shutdown(code: number, emitExit = true): void {
+    if (shuttingDown) return
+    shuttingDown = true
+    clearInterval(orphanWatchdog)
+    try {
+      currentClaudeChild?.kill('SIGTERM')
+    } catch {}
+    try {
+      void codexClient?.shutdown(800)
+    } catch {}
+    if (emitExit) emit({ type: 'exited', code } as AgentEvent)
+    eventsStream.end(() => {
+      try {
+        transcriptStream?.end()
+      } catch {}
+      resolveExit(code)
+    })
+    ;(setTimeout(() => resolveExit(code), 1500) as unknown as NodeJS.Timeout).unref()
+  }
+
+  // orphan watchdog: if our session dir / FIFOs are deleted out from under
+  // us (test cleanup did `rm -rf tmpdir` without calling endSession, the
+  // daemon crashed, the user force-nuked app-data) we can't be reached by
+  // anyone anyway — stop holding fds and spinning. poll every 10s to keep
+  // cost negligible; tests override via SOOTSIM_WRAPPER_WATCHDOG_MS.
+  const watchdogMs = (() => {
+    const raw = Number(process.env.SOOTSIM_WRAPPER_WATCHDOG_MS)
+    return Number.isFinite(raw) && raw > 0 ? raw : 10_000
+  })()
+  const orphanWatchdog = setInterval(() => {
+    if (shuttingDown) return
+    const eventsOutExists = existsSync(eventsOut)
+    const promptInExists = existsSync(promptIn)
+    if (!eventsOutExists || !promptInExists) {
+      process.stderr.write(
+        `[wrapper] session fifos gone (eventsOut=${eventsOutExists} promptIn=${promptInExists}), exiting\n`,
+      )
+      // once events.out is gone there is no recipient for an exit event. a
+      // final write only introduces a broken-pipe race into clean orphan
+      // shutdown; normal exits and prompt-only loss still report over the wire.
+      shutdown(0, eventsOutExists)
+    }
+  }, watchdogMs)
+  ;(orphanWatchdog as unknown as NodeJS.Timeout).unref()
+
+  process.on('SIGTERM', () => shutdown(143))
+  process.on('SIGINT', () => shutdown(130))
+  // detached: true takes us out of the parent's process group, but SIGHUP
+  // can still propagate in edge cases (e.g. crashed parent terminal). exit
+  // cleanly instead of being killed uncleanly with no `exited` event.
+  process.on('SIGHUP', () => shutdown(129))
+  process.on('uncaughtException', (err) => {
+    emit({
+      type: 'error',
+      message: `uncaught: ${(err as Error).message}`,
+    } as AgentEvent)
+    shutdown(1)
+  })
+
+  // build the per-turn runner for whichever provider this is.
+  const runTurn: TurnRunner =
+    provider === 'codex' && codexClient
+      ? buildCodexTurnRunner({
+          client: codexClient,
+          getThreadId: () => codexThreadId,
+          setThreadId: (id) => (codexThreadId = id),
+          emit,
+          transcript: transcriptStream,
+          onTurnSettled: () => {
+            turnInFlight = false
+            const next = pendingPrompts.shift()
+            if (next) void invokeTurn(next)
+          },
+        })
+      : buildClaudeTurnRunner({
+          resolvedBin: resolvedAgentBin,
+          sessionId,
+          projectId,
+          // prefer the uuid persisted on the AgentSession (passed in by
+          // startSession so `~/.claude/projects/<cwd>/<uuid>.jsonl` is
+          // reused across wrapper restarts). fall back to a fresh uuid for
+          // standalone invocations (tests, ad-hoc debugging).
+          claudeSessionUuid: args.claudeSessionUuid ?? randomUUID(),
+          cwd,
+          emit,
+          transcript: transcriptStream,
+          setChild: (c) => (currentClaudeChild = c),
+          onTurnSettled: () => {
+            turnInFlight = false
+            const next = pendingPrompts.shift()
+            if (next) void invokeTurn(next)
+          },
+        })
+
+  async function invokeTurn(text: string): Promise<void> {
+    turnInFlight = true
+    try {
+      await runTurn(text)
+    } catch (err) {
+      emit({
+        type: 'error',
+        message: `turn failed: ${(err as Error).message}`,
+      } as AgentEvent)
+      turnInFlight = false
+      const next = pendingPrompts.shift()
+      if (next) void invokeTurn(next)
+    }
+  }
+
+  // open prompt.in with O_RDWR so our own write end keeps the FIFO alive
+  // across external writer open/close cycles. `sootsim agent prompt` opens,
+  // writes one line, closes — without a self-writer the reader would EOF
+  // after the first prompt and subsequent prompts would be lost.
+  const promptFd = openSync(promptIn, fsConstants.O_RDWR)
+  const promptStream = createReadStream('', { fd: promptFd, autoClose: false })
+  const rl = readline.createInterface({ input: promptStream, crlfDelay: Infinity })
+
+  rl.on('line', (rawLine) => {
+    const prompt = decodeAgentPromptEnvelope(rawLine)
+    if (!prompt) return
+    const text = prompt.text
+    emit({
+      type: 'prompt-received',
+      text: prompt.displayText ?? text,
+      ...(prompt.inspectSummary ? { inspectSummary: prompt.inspectSummary } : {}),
+      ...(prompt.inspectTrace ? { inspectTrace: prompt.inspectTrace } : {}),
+    } as AgentEvent)
+    if (turnInFlight) {
+      pendingPrompts.push(text)
+      return
+    }
+    void invokeTurn(text)
+  })
+
+  promptStream.on('error', (err) => {
+    emit({
+      type: 'error',
+      message: `prompt-in read failed: ${err.message}`,
+    } as AgentEvent)
+  })
+
+  return exitPromise
+}
+
+// --- codex app-server integration ---
+
+export function extractCodexThreadId(
+  started: { threadId?: string; thread?: { id?: string } } | undefined,
+): string | null {
+  return started?.threadId ?? started?.thread?.id ?? null
+}
+
+async function resolveCodexThread(
+  client: CodexClient,
+  cwd: string,
+  opts: { fresh?: boolean } = {},
+): Promise<string> {
+  // try to reuse the most recent active thread for this cwd. if anything
+  // goes wrong, or the caller requested a fresh thread, use thread/start.
+  if (!opts.fresh) {
+    try {
+      const res = (await client.request('thread/list', {
+        cwd,
+        limit: 1,
+        archived: false,
+      })) as { threads?: Array<{ id: string }> } | undefined
+      const existing = res?.threads?.[0]?.id
+      if (existing) {
+        try {
+          await client.request('thread/resume', {
+            threadId: existing,
+            // codex 0.121 rejects `persistExtendedHistory: true` with "requires
+            // experimentalApi capability". we don't need extended rollouts for
+            // v1 — thread history on resume is already sufficient.
+            persistExtendedHistory: false,
+            approvalPolicy: CODEX_APPROVAL_POLICY,
+            sandbox: CODEX_THREAD_SANDBOX,
+            serviceTier: CODEX_SERVICE_TIER,
+          })
+          return existing
+        } catch {
+          // fall through to start a fresh thread
+        }
+      }
+    } catch {
+      // thread/list not available in this codex build; just start a new one.
+    }
+  }
+  const started = (await client.request('thread/start', {
+    cwd,
+    experimentalRawEvents: false,
+    // codex 0.121 rejects `persistExtendedHistory: true` without the
+    // `experimentalApi` capability (which we don't opt into). extended
+    // rollouts aren't needed for v1 — the default short history is fine.
+    persistExtendedHistory: false,
+    approvalPolicy: CODEX_APPROVAL_POLICY,
+    sandbox: CODEX_THREAD_SANDBOX,
+    serviceTier: CODEX_SERVICE_TIER,
+  })) as { threadId?: string; thread?: { id?: string } } | undefined
+  const threadId = extractCodexThreadId(started)
+  if (!threadId) {
+    throw new Error('thread/start returned no threadId')
+  }
+  return threadId
+}
+
+interface CodexTurnDeps {
+  client: CodexClient
+  getThreadId: () => string | null
+  setThreadId: (id: string) => void
+  emit: (event: Partial<AgentEvent> & { type: AgentEvent['type'] }) => void
+  transcript: ReturnType<typeof createWriteStream> | null
+  onTurnSettled: () => void
+}
+
+function buildCodexTurnRunner(deps: CodexTurnDeps): TurnRunner {
+  const { client, emit, transcript } = deps
+
+  // install notification handlers once; they feed the per-turn state via a
+  // module-local map keyed by turnId. a new turn clears its bucket on entry.
+  interface TurnState {
+    started: number
+    resolve: () => void
+    filesTouched: Set<string>
+    pendingEmit: string
+  }
+  const turns = new Map<string, TurnState>()
+  let latestTurnId: string | null = null
+
+  client.on('turn/started', (params) => {
+    const p = params as { threadId?: string; turn?: { id?: string; startedAt?: number } }
+    const turnId = p?.turn?.id
+    if (!turnId) return
+    latestTurnId = turnId
+    const state = turns.get(turnId) ?? {
+      started: Date.now(),
+      resolve: () => {},
+      filesTouched: new Set<string>(),
+      pendingEmit: '',
+    }
+    if (!turns.has(turnId)) turns.set(turnId, state)
+    emit({ type: 'turn-started', turnId } as AgentEvent)
+  })
+
+  client.on('item/agentMessage/delta', (params) => {
+    const p = params as { delta?: string }
+    if (!p?.delta) return
+    transcript?.write(p.delta)
+    emit({ type: 'turn-message', delta: p.delta } as AgentEvent)
+  })
+
+  client.on('item/reasoning/textDelta', (params) => {
+    const p = params as { delta?: string }
+    if (!p?.delta) return
+    emit({ type: 'turn-reasoning', delta: p.delta } as AgentEvent)
+  })
+
+  client.on('item/reasoning/summaryTextDelta', (params) => {
+    const p = params as { delta?: string }
+    if (!p?.delta) return
+    emit({ type: 'turn-reasoning', delta: p.delta } as AgentEvent)
+  })
+
+  // intentionally NOT subscribing to `turn/diff/updated` — the notification
+  // carries an aggregated unified diff for the whole turn with no per-file
+  // attribution, which would force consumers (HMR halo) to key on an empty
+  // path. `item/completed` with type=fileChange delivers the same information
+  // per-file, so we rely on that instead.
+
+  client.on('turn/plan/updated', (params) => {
+    const p = params as {
+      plan?: Array<{ step: string; status: string }>
+      turnId?: string
+    }
+    if (!Array.isArray(p?.plan)) return
+    emit({
+      type: 'turn-plan',
+      steps: p.plan.map((s, i) => ({
+        id: String(i),
+        title: s.step,
+        status: s.status,
+      })),
+    } as AgentEvent)
+  })
+
+  client.on('item/started', (params) => {
+    const p = params as {
+      item?: { type?: string; command?: string; tool?: string }
+      turnId?: string
+    }
+    const item = p?.item
+    if (!item) return
+    if (item.type === 'commandExecution' && item.command) {
+      emit({
+        type: 'tool-call',
+        name: 'commandExecution',
+        args: { command: item.command },
+      } as AgentEvent)
+    } else if (item.type === 'mcpToolCall' || item.type === 'dynamicToolCall') {
+      emit({
+        type: 'tool-call',
+        name: item.tool ?? item.type,
+        args: {},
+      } as AgentEvent)
+    }
+  })
+
+  client.on('item/completed', (params) => {
+    const p = params as {
+      item?: {
+        type?: string
+        status?: string
+        changes?: Array<{
+          path: string
+          kind: { type?: string; move_path?: string | null }
+          diff?: string
+        }>
+      }
+      turnId?: string
+    }
+    const item = p?.item
+    if (!item) return
+    if (item.type !== 'fileChange') return
+    if (item.status !== 'completed') return
+    if (!Array.isArray(item.changes)) return
+    const turnId = p?.turnId
+    const state = turnId ? turns.get(turnId) : null
+    for (const change of item.changes) {
+      const kindType = change.kind?.type
+      const kind: 'add' | 'modify' | 'delete' =
+        kindType === 'add' ? 'add' : kindType === 'delete' ? 'delete' : 'modify'
+      emit({
+        type: 'file-edited',
+        path: change.path,
+        kind,
+        diff: change.diff,
+      } as AgentEvent)
+      state?.filesTouched.add(change.path)
+      // a rename (`update` with move_path) touches two files — track both so
+      // HMR halo can highlight the new path too.
+      const movePath = change.kind?.move_path
+      if (movePath && movePath !== change.path) {
+        state?.filesTouched.add(movePath)
+      }
+    }
+  })
+
+  client.on('turn/completed', (params) => {
+    const p = params as {
+      threadId?: string
+      turn?: {
+        id?: string
+        status?: string
+        durationMs?: number | null
+        startedAt?: number | null
+      }
+    }
+    const turnId = p?.turn?.id
+    if (!turnId) return
+    const state = turns.get(turnId)
+    const filesTouched = state ? Array.from(state.filesTouched) : []
+    const durationMs = p.turn?.durationMs ?? (state ? Date.now() - state.started : 0)
+    emit({
+      type: 'turn-completed',
+      turnId,
+      filesTouched,
+      durationMs,
+    } as AgentEvent)
+    state?.resolve()
+    turns.delete(turnId)
+  })
+
+  client.on('error', (params) => {
+    const p = params as {
+      error?: { message?: string }
+      turnId?: string
+    }
+    const msg = p?.error?.message ?? 'codex reported an error'
+    emit({ type: 'error', message: msg } as AgentEvent)
+    if (p.turnId) {
+      const state = turns.get(p.turnId)
+      state?.resolve()
+      turns.delete(p.turnId)
+    }
+  })
+
+  return async function codexRunTurn(text: string): Promise<void> {
+    const threadId = deps.getThreadId()
+    if (!threadId) {
+      emit({ type: 'error', message: 'no active codex thread' } as AgentEvent)
+      deps.onTurnSettled()
+      return
+    }
+    const { promise, resolve } = createDeferred<void>()
+    // we don't know the turnId until turn/started arrives. register a
+    // placeholder and patch it up in the notification handler.
+    const pendingId = `pending-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
+    turns.set(pendingId, {
+      started: Date.now(),
+      resolve,
+      filesTouched: new Set(),
+      pendingEmit: '',
+    })
+    try {
+      const res = (await client.request('turn/start', {
+        threadId,
+        input: [{ type: 'text', text, text_elements: [] }],
+        approvalPolicy: CODEX_APPROVAL_POLICY,
+        sandboxPolicy: CODEX_TURN_SANDBOX_POLICY,
+        serviceTier: CODEX_SERVICE_TIER,
+        effort: CODEX_REASONING_EFFORT,
+      })) as { turn?: { id?: string } } | undefined
+      const actualTurnId = res?.turn?.id ?? latestTurnId
+      if (actualTurnId && actualTurnId !== pendingId) {
+        // hoist the placeholder bucket onto the real turnId so future
+        // notifications accumulate into it.
+        const placeholder = turns.get(pendingId)
+        if (placeholder) {
+          turns.delete(pendingId)
+          const existing = turns.get(actualTurnId)
+          if (existing) {
+            for (const f of placeholder.filesTouched) existing.filesTouched.add(f)
+            existing.resolve = placeholder.resolve
+          } else {
+            turns.set(actualTurnId, placeholder)
+          }
+        }
+      }
+    } catch (err) {
+      turns.delete(pendingId)
+      const message = err instanceof Error ? err.message : String(err)
+      emit({ type: 'error', message: `turn/start failed: ${message}` } as AgentEvent)
+      emit({
+        type: 'turn-completed',
+        filesTouched: [] as string[],
+        durationMs: 0,
+      })
+      deps.onTurnSettled()
+      return
+    }
+    // safety timeout so a lost turn/completed notification doesn't wedge
+    // the wrapper forever. 10min is far beyond normal codex turn duration.
+    const timeout = (
+      setTimeout(() => resolve(), 10 * 60 * 1000) as unknown as NodeJS.Timeout
+    ).unref()
+    try {
+      await promise
+    } finally {
+      clearTimeout(timeout)
+      deps.onTurnSettled()
+    }
+  }
+}
+
+// --- claude per-turn spawn via --output-format stream-json ---
+//
+// each prompt spawns a fresh `claude --print --output-format stream-json
+// --verbose --permission-mode bypassPermissions --session-id <uuid>` process.
+// stdout is a newline-delimited stream of well-typed objects; we translate
+// them into our AgentEvent wire format. the deterministic session uuid means
+// successive spawns all land in the same `~/.claude/projects/<cwd>/<uuid>.jsonl`
+// file, so turn-over-turn state is preserved without a long-lived child.
+
+interface ClaudeStreamEvent {
+  type?: string
+  subtype?: string
+  message?: {
+    content?: Array<{
+      type?: string
+      text?: string
+      name?: string
+      id?: string
+      input?: { file_path?: string; path?: string; [k: string]: unknown }
+    }>
+  }
+  duration_ms?: number
+  total_cost_usd?: number
+  result?: string
+  is_error?: boolean
+  permission_denials?: Array<{ tool_name?: string; tool_input?: unknown }>
+  session_id?: string
+}
+
+const CLAUDE_FILE_TOOLS = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit'])
+
+interface ClaudeTurnDeps {
+  resolvedBin: string
+  sessionId: string
+  projectId: string
+  claudeSessionUuid: string
+  cwd: string
+  emit: (event: Partial<AgentEvent> & { type: AgentEvent['type'] }) => void
+  transcript: ReturnType<typeof createWriteStream> | null
+  setChild: (child: ChildProcess | null) => void
+  onTurnSettled: () => void
+}
+
+function buildClaudeTurnRunner(deps: ClaudeTurnDeps): TurnRunner {
+  return async function claudeRunTurn(text: string): Promise<void> {
+    const {
+      resolvedBin,
+      sessionId,
+      projectId,
+      claudeSessionUuid,
+      cwd,
+      emit,
+      transcript,
+      setChild,
+    } = deps
+    const startedAt = Date.now()
+    emit({ type: 'turn-started' } as AgentEvent)
+
+    const child = spawn(
+      resolvedBin,
+      [
+        '--print',
+        '--output-format',
+        'stream-json',
+        '--verbose',
+        '--permission-mode',
+        'bypassPermissions',
+        '--session-id',
+        claudeSessionUuid,
+        text,
+      ],
+      {
+        cwd,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        env: {
+          ...process.env,
+          SOOTSIM_CLI_IDENTITY: sessionId,
+          SOOTSIM_PROJECT_ID: projectId,
+        },
+      },
+    )
+    setChild(child)
+
+    const filesTouched = new Set<string>()
+    let completedEmitted = false
+
+    function processEvent(ev: ClaudeStreamEvent): void {
+      const type = ev.type
+      if (!type) return
+      if (type === 'assistant' && Array.isArray(ev.message?.content)) {
+        for (const item of ev.message!.content!) {
+          if (item.type === 'text' && item.text) {
+            transcript?.write(item.text)
+            emit({ type: 'turn-message', delta: item.text } as AgentEvent)
+          } else if (item.type === 'tool_use' && item.name) {
+            emit({
+              type: 'tool-call',
+              name: item.name,
+              args: item.input ?? {},
+            } as AgentEvent)
+            const filePath = item.input?.file_path ?? item.input?.path
+            if (typeof filePath === 'string' && CLAUDE_FILE_TOOLS.has(item.name)) {
+              filesTouched.add(filePath)
+              emit({
+                type: 'file-edited',
+                path: filePath,
+                kind: 'modify',
+              } as AgentEvent)
+            }
+          }
+        }
+      } else if (type === 'result') {
+        completedEmitted = true
+        if (Array.isArray(ev.permission_denials)) {
+          for (const denial of ev.permission_denials) {
+            emit({
+              type: 'approval-needed',
+              kind: denial.tool_name ?? 'unknown',
+              detail: denial.tool_input ?? null,
+            } as AgentEvent)
+          }
+        }
+        if (ev.is_error && typeof ev.result === 'string') {
+          emit({ type: 'error', message: ev.result } as AgentEvent)
+        }
+        emit({
+          type: 'turn-completed',
+          filesTouched: Array.from(filesTouched),
+          durationMs: ev.duration_ms ?? Date.now() - startedAt,
+          // suppress cost on failed turns so the 7-day rolling history in
+          // `recordTurnTelemetry` reflects work the agent actually did, not
+          // rate-limited / user-aborted attempts.
+          costUsd: ev.is_error ? undefined : ev.total_cost_usd,
+        } as AgentEvent)
+      }
+    }
+
+    // parse stdout line-by-line; claude emits one JSON object per line in
+    // stream-json mode, but chunks can split mid-line so we buffer.
+    let leftover = ''
+    child.stdout?.setEncoding('utf8')
+    child.stdout?.on('data', (chunk: string) => {
+      leftover += chunk
+      let idx: number
+      while ((idx = leftover.indexOf('\n')) >= 0) {
+        const line = leftover.slice(0, idx)
+        leftover = leftover.slice(idx + 1)
+        const trimmed = line.trim()
+        if (!trimmed) continue
+        let parsed: ClaudeStreamEvent
+        try {
+          parsed = JSON.parse(trimmed) as ClaudeStreamEvent
+        } catch {
+          // non-JSON noise (e.g. pre-init stderr crossover) — skip.
+          continue
+        }
+        try {
+          processEvent(parsed)
+        } catch (err) {
+          emit({
+            type: 'error',
+            message: `claude event handler failed: ${(err as Error).message}`,
+          } as AgentEvent)
+        }
+      }
+    })
+
+    child.stderr?.setEncoding('utf8')
+    child.stderr?.on('data', (chunk: string) => {
+      transcript?.write(`[claude-stderr] ${chunk}`)
+    })
+
+    child.on('error', (err) => {
+      emit({
+        type: 'error',
+        message: `spawn failed: ${err.message}`,
+      } as AgentEvent)
+    })
+
+    const { promise, resolve } = createDeferred<void>()
+    child.on('exit', (code) => {
+      if (!completedEmitted) {
+        // claude exited without emitting a `result` event — usually a crash,
+        // rate-limit, or SIGTERM. emit a terminal event so the queue drains.
+        emit({
+          type: 'turn-completed',
+          filesTouched: Array.from(filesTouched),
+          durationMs: Date.now() - startedAt,
+        } as AgentEvent)
+        if (code !== 0 && code !== null) {
+          emit({
+            type: 'error',
+            message: `claude exited with code ${code}`,
+          } as AgentEvent)
+        }
+      }
+      setChild(null)
+      resolve()
+    })
+    try {
+      await promise
+    } finally {
+      deps.onTurnSettled()
+    }
+  }
+}
+
+function createDeferred<T>(): {
+  promise: Promise<T>
+  resolve: (value: T) => void
+} {
+  let resolve!: (value: T) => void
+  const promise = new Promise<T>((res) => {
+    resolve = res
+  })
+  return { promise, resolve }
+}
+
+function withTimeout<T>(p: Promise<T>, ms: number, message: string): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const t = setTimeout(() => reject(new Error(message)), ms)
+    p.then(
+      (v) => {
+        clearTimeout(t)
+        resolve(v)
+      },
+      (err: unknown) => {
+        clearTimeout(t)
+        reject(err instanceof Error ? err : new Error(String(err)))
+      },
+    )
+  })
+}