@app-vitals/agent-runtime 0.0.1 → 0.1.0

package/claude.unit.test.ts

@@ -0,0 +1,3042 @@
+/**
+ * Tests for agent/src/runtime/claude.ts
+ *
+ * Strategy: use createRunClaude(spawner, sessions, model, workspace)
+ * to inject all dependencies directly. No mock.module() calls needed anywhere.
+ * Note: Identity injection removed — identity is now handled via CLAUDE.md in the workspace.
+ */
+
+import "./test-env.ts";
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+import {
+  existsSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { ErrorCapturingClient } from "@app-vitals/agent-lib/sentry";
+import { TEST_AGENT_HOME } from "./test-env.ts";
+
+const MODEL = "claude-opus-4-6";
+const WORKSPACE = join(TEST_AGENT_HOME, "workspace");
+
+// ─── Import module under test ─────────────────────────────────────────────────
+
+const {
+  createRunClaude,
+  setLiveClaudeConfig,
+  dominantModel,
+  ClaudeTimeoutError,
+  reportClaudeError,
+  ClaudeRunError,
+} = await import("./claude.ts");
+
+// ─── Stream-json fixtures (hand-authored per the public CLI schema) ───────────
+
+const cleanMultiTurn = await import(
+  "./fixtures/stream-json/clean-multi-turn.ts"
+);
+const truncatedNoResult = await import(
+  "./fixtures/stream-json/truncated-no-result.ts"
+);
+const cleanExitNoResult = await import(
+  "./fixtures/stream-json/clean-exit-no-result.ts"
+);
+const progressPhases = await import(
+  "./fixtures/stream-json/progress-phases.ts"
+);
+const skillAttribution = await import(
+  "./fixtures/stream-json/skill-attribution.ts"
+);
+
+// ─── Shared test session store ────────────────────────────────────────────────
+
+const mockGetSession = mock((_key: string): string | undefined => undefined);
+const mockSetSession = mock((_key: string, _id: string): void => {});
+const mockClearSession = mock((_key: string): void => {});
+const testSessions = {
+  get: mockGetSession,
+  set: mockSetSession,
+  clear: mockClearSession,
+};
+
+let capturedMessages: string[] = [];
+let capturedExceptions: unknown[] = [];
+const fakeSentryClient: ErrorCapturingClient = {
+  captureException: (err: unknown) => {
+    capturedExceptions.push(err);
+  },
+  captureMessage: (message: string) => {
+    capturedMessages.push(message);
+  },
+};
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function bodyStream(content: string): ReadableStream<Uint8Array> {
+  const enc = new TextEncoder();
+  return new ReadableStream({
+    start(controller) {
+      controller.enqueue(enc.encode(content));
+      controller.close();
+    },
+  });
+}
+
+/**
+ * Emits each NDJSON line as its OWN stream chunk (with a trailing newline), so
+ * the parser under test is exercised across real chunk boundaries rather than
+ * one giant buffered string.
+ */
+function ndjsonStream(lines: string[]): ReadableStream<Uint8Array> {
+  const enc = new TextEncoder();
+  return new ReadableStream({
+    start(controller) {
+      for (const line of lines) {
+        controller.enqueue(enc.encode(`${line}\n`));
+      }
+      controller.close();
+    },
+  });
+}
+
+function ndjsonProc(lines: string[], stderr = "", exitCode = 0): FakeProc {
+  return {
+    stdout: ndjsonStream(lines),
+    stderr: bodyStream(stderr),
+    exited: Promise.resolve(exitCode),
+    kill: () => {},
+  };
+}
+
+interface FakeProc {
+  stdout: ReadableStream<Uint8Array>;
+  stderr: ReadableStream<Uint8Array>;
+  exited: Promise<number>;
+  kill: () => void;
+}
+
+function fakeProc(stdout: string, stderr = "", exitCode = 0): FakeProc {
+  return {
+    stdout: bodyStream(stdout),
+    stderr: bodyStream(stderr),
+    exited: Promise.resolve(exitCode),
+    kill: () => {},
+  };
+}
+
+/**
+ * A fake proc whose stdout emits one NDJSON line every `intervalMs`, for
+ * `count` lines — used to exercise idle-reset-vs-ceiling timer races with
+ * short REAL timeouts (consistent with this file's existing convention of
+ * small millisecond literals rather than fake-timer injection).
+ *
+ * When `autoCloseAfterDrip` is true, the stream closes itself (and `exited`
+ * resolves with 0) right after the last line — simulating a process that
+ * finishes cleanly before any timer fires. When false, the stream is left
+ * open after the last line (no close(), no result line) and only `kill()`
+ * (called by the idle/ceiling timer under test) closes it — simulating a
+ * process a timer has to forcibly stop.
+ */
+function drippingProc(
+  line: string,
+  intervalMs: number,
+  count: number,
+  autoCloseAfterDrip = false,
+): FakeProc {
+  const enc = new TextEncoder();
+  let resolveExited!: (code: number) => void;
+  const exited = new Promise<number>((r) => {
+    resolveExited = r;
+  });
+  let streamController!: ReadableStreamDefaultController<Uint8Array>;
+  let closed = false;
+  const close = (code: number) => {
+    if (closed) return;
+    closed = true;
+    streamController.close();
+    resolveExited(code);
+  };
+  const stdout = new ReadableStream<Uint8Array>({
+    start(controller) {
+      streamController = controller;
+      (async () => {
+        for (let i = 0; i < count; i++) {
+          if (closed) return;
+          controller.enqueue(enc.encode(`${line}\n`));
+          await new Promise((r) => setTimeout(r, intervalMs));
+        }
+        if (autoCloseAfterDrip) close(0);
+      })();
+    },
+  });
+  return {
+    stdout,
+    stderr: bodyStream(""),
+    exited,
+    kill: () => close(143),
+  };
+}
+
+function hangingProc(): FakeProc & { triggerKill: () => void } {
+  let resolveExited!: (code: number) => void;
+  const exited = new Promise<number>((r) => {
+    resolveExited = r;
+  });
+  const kill = () => resolveExited(143);
+  return {
+    stdout: bodyStream(""),
+    stderr: bodyStream(""),
+    exited,
+    kill,
+    triggerKill: kill,
+  };
+}
+
+/**
+ * A single terminal stream-json `result` line (the CLI emits exactly one on a
+ * clean finish). Its shape is byte-identical to the old `--output-format json`
+ * single blob, plus the `type`/`subtype` discriminator.
+ */
+function jsonOutput(
+  result: string,
+  sessionId = "sess-abc",
+  isError = false,
+): string {
+  return JSON.stringify({
+    type: "result",
+    subtype: isError ? "error" : "success",
+    result,
+    session_id: sessionId,
+    is_error: isError,
+  });
+}
+
+// ─── runClaude tests ──────────────────────────────────────────────────────────
+
+describe("runClaude", () => {
+  // biome-ignore lint/suspicious/noExplicitAny: mock return type
+  let mockSpawn: any;
+  let runClaude: ReturnType<typeof createRunClaude>;
+
+  beforeEach(() => {
+    mockGetSession.mockClear();
+    mockSetSession.mockClear();
+    mockClearSession.mockClear();
+    capturedMessages = [];
+    capturedExceptions = [];
+    mockSpawn = mock(
+      () =>
+        fakeProc(jsonOutput("Hello from Claude")) as ReturnType<
+          typeof Bun.spawn
+        >,
+    );
+    runClaude = createRunClaude(
+      mockSpawn as typeof Bun.spawn,
+      testSessions,
+      MODEL,
+      WORKSPACE,
+      fakeSentryClient,
+    );
+  });
+
+  test("calls spawn with claude as the command", async () => {
+    await runClaude("test message");
+    expect(mockSpawn).toHaveBeenCalledTimes(1);
+    const [cmd] = mockSpawn.mock.calls[0] as [string[]];
+    expect(cmd[0]).toBe("claude");
+  });
+
+  test("passes -p flag for non-interactive mode", async () => {
+    await runClaude("test");
+    const [cmd] = mockSpawn.mock.calls[0] as [string[]];
+    expect(cmd).toContain("-p");
+  });
+
+  test("passes --output-format stream-json --verbose", async () => {
+    await runClaude("test");
+    const [cmd] = mockSpawn.mock.calls[0] as [string[]];
+    const idx = cmd.indexOf("--output-format");
+    expect(idx).toBeGreaterThan(-1);
+    expect(cmd[idx + 1]).toBe("stream-json");
+    expect(cmd).toContain("--verbose");
+  });
+
+  test("passes --model from config", async () => {
+    await runClaude("test");
+    const [cmd] = mockSpawn.mock.calls[0] as [string[]];
+    const idx = cmd.indexOf("--model");
+    expect(idx).toBeGreaterThan(-1);
+    expect(cmd[idx + 1]).toBe("claude-opus-4-6");
+  });
+
+  test("does not pass --fallback-model when not configured", async () => {
+    await runClaude("test");
+    const [cmd] = mockSpawn.mock.calls[0] as [string[]];
+    expect(cmd).not.toContain("--fallback-model");
+  });
+
+  test("does not pass --effort when not configured", async () => {
+    await runClaude("test");
+    const [cmd] = mockSpawn.mock.calls[0] as [string[]];
+    expect(cmd).not.toContain("--effort");
+  });
+
+  test("passes --effort when configured", async () => {
+    const runClaudeWithEffort = createRunClaude(
+      mockSpawn as typeof Bun.spawn,
+      testSessions,
+      MODEL,
+      WORKSPACE,
+      fakeSentryClient,
+      [],
+      undefined,
+      "xhigh",
+    );
+    await runClaudeWithEffort("test");
+    const [cmd] = mockSpawn.mock.calls[0] as [string[]];
+    const idx = cmd.indexOf("--effort");
+    expect(idx).toBeGreaterThan(-1);
+    expect(cmd[idx + 1]).toBe("xhigh");
+  });
+
+  test("passes --fallback-model when configured", async () => {
+    const runClaudeWithFallback = createRunClaude(
+      mockSpawn as typeof Bun.spawn,
+      testSessions,
+      MODEL,
+      WORKSPACE,
+      fakeSentryClient,
+      [],
+      "claude-sonnet-4-6",
+    );
+    await runClaudeWithFallback("test");
+    const [cmd] = mockSpawn.mock.calls[0] as [string[]];
+    const idx = cmd.indexOf("--fallback-model");
+    expect(idx).toBeGreaterThan(-1);
+    expect(cmd[idx + 1]).toBe("claude-sonnet-4-6");
+  });
+
+  test("passes correct cwd, stdout, stderr spawn options", async () => {
+    await runClaude("test");
+    const [, opts] = mockSpawn.mock.calls[0] as [
+      string[],
+      { cwd: string; stdout: string; stderr: string },
+    ];
+    expect(opts.cwd).toBe(join(TEST_AGENT_HOME, "workspace"));
+    expect(opts.stdout).toBe("pipe");
+    expect(opts.stderr).toBe("pipe");
+  });
+
+  test("strips SENTRY_DSN from the spawned child's env but keeps unrelated vars", async () => {
+    const priorSentryDsn = process.env.SENTRY_DSN;
+    process.env.SENTRY_DSN = "https://fake@sentry.example/123";
+    try {
+      await runClaude("test");
+      const [, opts] = mockSpawn.mock.calls[0] as [
+        string[],
+        { env: Record<string, string | undefined> },
+      ];
+      expect(opts.env.SENTRY_DSN).toBeUndefined();
+      expect(opts.env.PATH).toBe(process.env.PATH);
+    } finally {
+      if (priorSentryDsn === undefined) {
+        delete process.env.SENTRY_DSN;
+      } else {
+        process.env.SENTRY_DSN = priorSentryDsn;
+      }
+    }
+  });
+
+  test("layers extraEnv on top of the spawned child's env alongside existing vars", async () => {
+    await runClaude("test", undefined, undefined, undefined, {
+      MY_VAR: "my-value",
+    });
+    const [, opts] = mockSpawn.mock.calls[0] as [
+      string[],
+      { env: Record<string, string | undefined> },
+    ];
+    expect(opts.env.MY_VAR).toBe("my-value");
+    expect(opts.env.PATH).toBe(process.env.PATH);
+  });
+
+  test("passes message as last arg without identity injection", async () => {
+    await runClaude("my prompt");
+    const [cmd] = mockSpawn.mock.calls[0] as [string[]];
+    const lastArg = cmd[cmd.length - 1];
+    expect(lastArg).toBe("my prompt");
+  });
+
+  test("passes raw message when resuming an existing session", async () => {
+    mockGetSession.mockReturnValueOnce("existing-sid");
+    await runClaude("follow-up question", "chan:ts");
+    const [cmd] = mockSpawn.mock.calls[0] as [string[]];
+    const lastArg = cmd[cmd.length - 1];
+    expect(lastArg).toBe("follow-up question");
+  });
+
+  test("returns result and sessionId on success", async () => {
+    const output = await runClaude("hello");
+    expect(output.result).toBe("Hello from Claude");
+    expect(output.sessionId).toBe("sess-abc");
+  });
+
+  test("returns usage from JSON output when present", async () => {
+    const usageJson = JSON.stringify({
+      type: "result",
+      subtype: "success",
+      result: "Hello with usage",
+      session_id: "sess-usage",
+      is_error: false,
+      usage: {
+        input_tokens: 100,
+        output_tokens: 50,
+        cache_read_input_tokens: 25,
+        cache_creation_input_tokens: 10,
+      },
+    });
+    mockSpawn.mockReturnValue(
+      fakeProc(usageJson) as ReturnType<typeof Bun.spawn>,
+    );
+    const output = await runClaude("hello");
+    expect(output.usage).toEqual({
+      input_tokens: 100,
+      output_tokens: 50,
+      cache_read_input_tokens: 25,
+      cache_creation_input_tokens: 10,
+    });
+  });
+
+  test("returns undefined usage when not in JSON output", async () => {
+    // Default mockSpawn produces jsonOutput("Hello from Claude") which has no usage field
+    const output = await runClaude("hello");
+    expect(output.usage).toBeUndefined();
+  });
+
+  test("without sessionKey does not call getSession or setSession", async () => {
+    await runClaude("hello");
+    expect(mockGetSession).not.toHaveBeenCalled();
+    expect(mockSetSession).not.toHaveBeenCalled();
+  });
+
+  test("with sessionKey calls getSession to look up existing session", async () => {
+    await runClaude("hello", "chan:ts");
+    expect(mockGetSession).toHaveBeenCalledWith("chan:ts");
+  });
+
+  test("adds -r flag when existing session is found", async () => {
+    mockGetSession.mockReturnValueOnce("existing-sid");
+    await runClaude("hello", "chan:ts");
+    const [cmd] = mockSpawn.mock.calls[0] as [string[]];
+    const rIdx = cmd.indexOf("-r");
+    expect(rIdx).toBeGreaterThan(-1);
+    expect(cmd[rIdx + 1]).toBe("existing-sid");
+  });
+
+  test("omits -r flag when no existing session", async () => {
+    mockGetSession.mockReturnValueOnce(undefined);
+    await runClaude("hello", "chan:ts");
+    const [cmd] = mockSpawn.mock.calls[0] as [string[]];
+    expect(cmd).not.toContain("-r");
+  });
+
+  test("saves session after successful run when sessionKey provided", async () => {
+    await runClaude("hello", "chan:ts");
+    expect(mockSetSession).toHaveBeenCalledWith("chan:ts", "sess-abc");
+  });
+
+  test("throws on non-zero exit code", async () => {
+    mockSpawn.mockReturnValue(
+      fakeProc("", "claude: command not found", 127) as ReturnType<
+        typeof Bun.spawn
+      >,
+    );
+    await expect(runClaude("hello")).rejects.toThrow("claude exited 127");
+  });
+
+  test("non-zero exit error includes stderr in message", async () => {
+    mockSpawn.mockReturnValue(
+      fakeProc("", "auth failure", 1) as ReturnType<typeof Bun.spawn>,
+    );
+    await expect(runClaude("hello")).rejects.toThrow("auth failure");
+  });
+
+  test("non-zero exit falls back to stdout when stderr is empty", async () => {
+    mockSpawn.mockReturnValue(
+      fakeProc("stdout fallback msg", "", 2) as ReturnType<typeof Bun.spawn>,
+    );
+    await expect(runClaude("hello")).rejects.toThrow("stdout fallback msg");
+  });
+
+  test("throws on is_error=true in response", async () => {
+    mockSpawn.mockReturnValue(
+      fakeProc(jsonOutput("tool call failed", "sess-abc", true)) as ReturnType<
+        typeof Bun.spawn
+      >,
+    );
+    await expect(runClaude("hello")).rejects.toThrow(
+      "claude error: tool call failed",
+    );
+  });
+
+  test("saves the session id from a ClaudeRunError on is_error=true (CSI-1.2: a real session exists even when the run itself errored)", async () => {
+    mockSpawn.mockReturnValue(
+      fakeProc(jsonOutput("tool error", "sess-abc", true)) as ReturnType<
+        typeof Bun.spawn
+      >,
+    );
+    await expect(runClaude("hello", "chan:ts")).rejects.toThrow();
+    expect(mockSetSession).toHaveBeenCalledWith("chan:ts", "sess-abc");
+  });
+
+  test("throws ClaudeTimeoutError when process exceeds timeoutMs", async () => {
+    const proc = hangingProc();
+    const mockSpawnTimeout = mock(
+      () => proc as unknown as ReturnType<typeof Bun.spawn>,
+    );
+    const runClaudeWithTimeout = createRunClaude(
+      mockSpawnTimeout as typeof Bun.spawn,
+      testSessions,
+      MODEL,
+      WORKSPACE,
+      fakeSentryClient,
+      undefined,
+      undefined,
+      undefined,
+      1000, // 1s ceiling headroom — well clear of the idle timeout below
+      10, // 10ms idle timeout — hangingProc never emits a line, so idle fires first
+    );
+
+    const { ClaudeTimeoutError } = await import("./claude.ts");
+    const err = await runClaudeWithTimeout("hello").catch((e) => e);
+    expect(err).toBeInstanceOf(ClaudeTimeoutError);
+    const timeoutErr = err as InstanceType<typeof ClaudeTimeoutError>;
+    expect(timeoutErr.reason).toBe("idle");
+    // Must report the idle window (10ms) that actually fired, not the 1000ms
+    // ceiling headroom that never lapsed.
+    expect(timeoutErr.timeoutMs).toBe(10);
+  });
+
+  test("throws ClaudeTimeoutError on an idle-reason stale-session timeout and does not retry (spawn called once)", async () => {
+    const proc = hangingProc();
+    const mockSpawnTimeout = mock(
+      () => proc as unknown as ReturnType<typeof Bun.spawn>,
+    );
+
+    mockGetSession.mockClear();
+    mockSetSession.mockClear();
+    mockClearSession.mockClear();
+    // Simulate an existing session so we enter the stale-session catch block
+    mockGetSession.mockReturnValueOnce("stale-sid");
+
+    const runClaudeWithTimeout = createRunClaude(
+      mockSpawnTimeout as typeof Bun.spawn,
+      testSessions,
+      MODEL,
+      WORKSPACE,
+      fakeSentryClient,
+      undefined,
+      undefined,
+      undefined,
+      5000, // ceiling far away — idle must fire first, deterministically
+      10, // 10ms idle timeout — hangingProc never emits a line, so idle fires
+    );
+
+    const { ClaudeTimeoutError } = await import("./claude.ts");
+    const err = await runClaudeWithTimeout("hello", "chan:ts").catch((e) => e);
+    expect(err).toBeInstanceOf(ClaudeTimeoutError);
+    expect((err as InstanceType<typeof ClaudeTimeoutError>).reason).toBe(
+      "idle",
+    );
+    // Idle is the genuine-hang signal — the safety rail prevents retry even
+    // with an existing session available to resume. Spawn called once.
+    expect(mockSpawnTimeout).toHaveBeenCalledTimes(1);
+  });
+
+  test("a ceiling-reason timeout IS retried once when a session id is available to resume", async () => {
+    // Fresh hangingProc() per spawn call — a real proc's stdout stream can
+    // only be consumed once, so the mock must hand back a new instance on
+    // each invocation (same pattern as the existing resume-retry tests).
+    let call = 0;
+    const mockSpawnCeiling = mock(() => {
+      call++;
+      if (call === 1) {
+        return hangingProc() as unknown as ReturnType<typeof Bun.spawn>;
+      }
+      return fakeProc(jsonOutput("recovered", "existing-sid")) as ReturnType<
+        typeof Bun.spawn
+      >;
+    });
+
+    mockGetSession.mockClear();
+    mockSetSession.mockClear();
+    mockClearSession.mockClear();
+    mockGetSession.mockReturnValueOnce("existing-sid");
+
+    const runClaudeCeilingRetry = createRunClaude(
+      mockSpawnCeiling as typeof Bun.spawn,
+      testSessions,
+      MODEL,
+      WORKSPACE,
+      fakeSentryClient,
+      undefined,
+      undefined,
+      undefined,
+      10, // 10ms ceiling — fires deterministically before idle
+      5000, // idle far away — ceiling must fire first
+    );
+
+    const result = await runClaudeCeilingRetry("hello", "chan:ts");
+    expect(result.result).toBe("recovered");
+    expect(result.recoveredFromError).toBe(true);
+    expect(mockSpawnCeiling).toHaveBeenCalledTimes(2);
+
+    const [secondCmd] = mockSpawnCeiling.mock.calls[1] as unknown as [string[]];
+    const rIdx = secondCmd.indexOf("-r");
+    expect(rIdx).toBeGreaterThan(-1);
+    expect(secondCmd[rIdx + 1]).toBe("existing-sid");
+  });
+
+  test("a fresh call that captures a session id mid-attempt (off the init line) is retried once with -r <that id>", async () => {
+    // First attempt: emits a system/init line (captures a session id via the
+    // new early-session-id path), then exits non-zero with no accumulated
+    // usage — this throws a plain Error carrying NO sessionId of its own, so
+    // the only way this retry can happen is via the mid-attempt capture, not
+    // via err.sessionId.
+    let call = 0;
+    const mockSpawn = mock(() => {
+      call++;
+      if (call === 1) {
+        return {
+          stdout: ndjsonStream([
+            JSON.stringify({
+              type: "system",
+              subtype: "init",
+              session_id: "early-sid",
+            }),
+          ]),
+          stderr: bodyStream("socket closed"),
+          exited: Promise.resolve(1),
+          kill: () => {},
+        } as unknown as ReturnType<typeof Bun.spawn>;
+      }
+      return fakeProc(jsonOutput("recovered", "early-sid")) as ReturnType<
+        typeof Bun.spawn
+      >;
+    });
+
+    mockGetSession.mockClear();
+    mockSetSession.mockClear();
+    mockClearSession.mockClear();
+    mockGetSession.mockReturnValue(undefined); // fresh — no existing session
+
+    const runClaudeFreshRetry = createRunClaude(
+      mockSpawn as typeof Bun.spawn,
+      testSessions,
+      MODEL,
+      WORKSPACE,
+      fakeSentryClient,
+    );
+
+    const result = await runClaudeFreshRetry("hello", "chan:ts");
+
+    expect(result.result).toBe("recovered");
+    expect(result.recoveredFromError).toBe(true);
+    expect(mockSpawn).toHaveBeenCalledTimes(2);
+
+    // First (fresh) call must NOT have passed -r.
+    const [firstCmd] = mockSpawn.mock.calls[0] as unknown as [string[]];
+    expect(firstCmd.indexOf("-r")).toBe(-1);
+
+    // Retry must resume with the id captured mid-first-attempt.
+    const [secondCmd] = mockSpawn.mock.calls[1] as unknown as [string[]];
+    const rIdx = secondCmd.indexOf("-r");
+    expect(rIdx).toBeGreaterThan(-1);
+    expect(secondCmd[rIdx + 1]).toBe("early-sid");
+    expect(mockSetSession).toHaveBeenCalledWith("chan:ts", "early-sid");
+  });
+
+  test("the early-session-id callback fires before the per-call onProgress callback for the same run", async () => {
+    const lines = [
+      JSON.stringify({
+        type: "system",
+        subtype: "init",
+        session_id: "sess-cb",
+      }),
+      JSON.stringify({
+        type: "assistant",
+        message: {
+          id: "msg_1",
+          role: "assistant",
+          model: MODEL,
+          usage: {
+            input_tokens: 1,
+            output_tokens: 1,
+            cache_read_input_tokens: 0,
+            cache_creation_input_tokens: 0,
+          },
+        },
+      }),
+      jsonOutput("done", "sess-cb"),
+    ];
+    const mockSpawnEarly = mock(
+      () => ndjsonProc(lines) as ReturnType<typeof Bun.spawn>,
+    );
+    const runClaudeEarly = createRunClaude(
+      mockSpawnEarly as typeof Bun.spawn,
+      testSessions,
+      MODEL,
+      WORKSPACE,
+      fakeSentryClient,
+    );
+
+    const calls: string[] = [];
+    await runClaudeEarly(
+      "hello",
+      undefined,
+      () => calls.push("progress"),
+      undefined,
+      undefined,
+      () => calls.push("early"),
+    );
+
+    expect(calls).toEqual(["early", "progress"]);
+  });
+
+  // ─── Abort / cancel ──────────────────────────────────────────────────────────
+
+  /**
+   * Wrap a real AbortController's signal so addEventListener/removeEventListener
+   * calls for the "abort" event are counted. Not a bare mock — event dispatch
+   * still works, so a listener that is actually added will still fire on abort.
+   * The counts prove the listener is removed after the run (no leak across the
+   * long-lived signal).
+   */
+  function countedSignal() {
+    const controller = new AbortController();
+    const real = controller.signal;
+    let added = 0;
+    let removed = 0;
+    const wrapped = {
+      get aborted() {
+        return real.aborted;
+      },
+      get reason() {
+        return real.reason;
+      },
+      addEventListener(type: string, cb: EventListener, opts?: unknown) {
+        if (type === "abort") added++;
+        real.addEventListener(type, cb, opts as AddEventListenerOptions);
+      },
+      removeEventListener(type: string, cb: EventListener, opts?: unknown) {
+        if (type === "abort") removed++;
+        real.removeEventListener(type, cb, opts as EventListenerOptions);
+      },
+    } as unknown as AbortSignal;
+    return {
+      signal: wrapped,
+      abort: () => controller.abort(),
+      counts: () => ({ added, removed }),
+    };
+  }
+
+  test("aborting the signal kills the process and throws ClaudeAbortedError", async () => {
+    const proc = hangingProc();
+    const mockSpawnAbort = mock(
+      () => proc as unknown as ReturnType<typeof Bun.spawn>,
+    );
+    const runClaudeAbort = createRunClaude(
+      mockSpawnAbort as typeof Bun.spawn,
+      testSessions,
+      MODEL,
+      WORKSPACE,
+      fakeSentryClient,
+      undefined,
+      undefined,
+      undefined,
+      5000,
+      5000,
+    );
+
+    const ctl = countedSignal();
+    const { ClaudeAbortedError } = await import("./claude.ts");
+    const runPromise = runClaudeAbort(
+      "hello",
+      undefined,
+      undefined,
+      ctl.signal,
+    );
+    // Abort shortly after the run starts.
+    setTimeout(() => ctl.abort(), 5);
+    const err = await runPromise.catch((e) => e);
+    expect(err).toBeInstanceOf(ClaudeAbortedError);
+  });
+
+  test("the abort listener is removed after the run (no leak across a long-lived signal)", async () => {
+    // A run that finishes cleanly (no abort) must still remove its listener.
+    const mockSpawnClean = mock(
+      () =>
+        fakeProc(jsonOutput("done")) as unknown as ReturnType<typeof Bun.spawn>,
+    );
+    const runClaudeClean = createRunClaude(
+      mockSpawnClean as typeof Bun.spawn,
+      testSessions,
+      MODEL,
+      WORKSPACE,
+      fakeSentryClient,
+    );
+
+    const ctl = countedSignal();
+    await runClaudeClean("hello", undefined, undefined, ctl.signal);
+    const { added, removed } = ctl.counts();
+    expect(added).toBe(1);
+    expect(removed).toBe(1);
+  });
+
+  test("the abort listener is removed even across a resume-retry (no second leaked listener)", async () => {
+    // First spawn fails (retryable), second succeeds — the retry path must not
+    // leak a second listener on the shared signal.
+    let call = 0;
+    const mockSpawnRetry = mock(() => {
+      call++;
+      if (call === 1) {
+        return fakeProc("", "socket closed", 1) as unknown as ReturnType<
+          typeof Bun.spawn
+        >;
+      }
+      return fakeProc(
+        jsonOutput("recovered", "sess-r"),
+      ) as unknown as ReturnType<typeof Bun.spawn>;
+    });
+
+    mockGetSession.mockClear();
+    mockGetSession.mockReturnValueOnce("existing-sid");
+
+    const runClaudeRetry = createRunClaude(
+      mockSpawnRetry as typeof Bun.spawn,
+      testSessions,
+      MODEL,
+      WORKSPACE,
+      fakeSentryClient,
+    );
+
+    const ctl = countedSignal();
+    await runClaudeRetry("hello", "chan:ts", undefined, ctl.signal);
+    expect(mockSpawnRetry).toHaveBeenCalledTimes(2);
+    const { added, removed } = ctl.counts();
+    // Every _spawn attempt adds exactly one listener and removes it — no net leak.
+    expect(added).toBe(removed);
+  });
+
+  test("abort wins over a racing timeout: exit 143 classified as aborted, not a timeout/run error", async () => {
+    // The proc's kill() yields exit 143. Both the (very short) timeout and the
+    // abort race to kill it — but the aborted check must win, so the thrown
+    // error is ClaudeAbortedError, never ClaudeTimeoutError or ClaudeRunError.
+    const proc = hangingProc();
+    const mockSpawnRace = mock(
+      () => proc as unknown as ReturnType<typeof Bun.spawn>,
+    );
+    const runClaudeRace = createRunClaude(
+      mockSpawnRace as typeof Bun.spawn,
+      testSessions,
+      MODEL,
+      WORKSPACE,
+      fakeSentryClient,
+      undefined,
+      undefined,
+      undefined,
+      5000, // ceiling far away
+      5000, // idle far away — so only the abort fires
+    );
+
+    const ctl = countedSignal();
+    const { ClaudeAbortedError, ClaudeTimeoutError } = await import(
+      "./claude.ts"
+    );
+    const runPromise = runClaudeRace("hello", undefined, undefined, ctl.signal);
+    setTimeout(() => ctl.abort(), 5);
+    const err = await runPromise.catch((e) => e);
+    expect(err).toBeInstanceOf(ClaudeAbortedError);
+    expect(err).not.toBeInstanceOf(ClaudeTimeoutError);
+  });
+
+  test("an aborted run is NOT retried even when an existing session would otherwise be resumed", async () => {
+    const proc = hangingProc();
+    const mockSpawnAbortRetry = mock(
+      () => proc as unknown as ReturnType<typeof Bun.spawn>,
+    );
+
+    mockGetSession.mockClear();
+    mockGetSession.mockReturnValueOnce("existing-sid");
+
+    const runClaudeAbortRetry = createRunClaude(
+      mockSpawnAbortRetry as typeof Bun.spawn,
+      testSessions,
+      MODEL,
+      WORKSPACE,
+      fakeSentryClient,
+    );
+
+    const ctl = countedSignal();
+    const { ClaudeAbortedError } = await import("./claude.ts");
+    const runPromise = runClaudeAbortRetry(
+      "hello",
+      "chan:ts",
+      undefined,
+      ctl.signal,
+    );
+    setTimeout(() => ctl.abort(), 5);
+    const err = await runPromise.catch((e) => e);
+    expect(err).toBeInstanceOf(ClaudeAbortedError);
+    // Aborted runs skip the resume-retry path — spawn called exactly once.
+    expect(mockSpawnAbortRetry).toHaveBeenCalledTimes(1);
+  });
+
+  test("_saveSessionFromError persists a ClaudeAbortedError's session id so the session stays resumable", async () => {
+    // hangingProc emits a system/init line carrying a session id before abort.
+    const enc = new TextEncoder();
+    let ctrl!: ReadableStreamDefaultController<Uint8Array>;
+    let resolveExited!: (code: number) => void;
+    const exited = new Promise<number>((r) => {
+      resolveExited = r;
+    });
+    const proc = {
+      stdout: new ReadableStream<Uint8Array>({
+        start(c) {
+          ctrl = c;
+          c.enqueue(
+            enc.encode(
+              `${JSON.stringify({ type: "system", subtype: "init", session_id: "abort-sid" })}\n`,
+            ),
+          );
+        },
+      }),
+      stderr: bodyStream(""),
+      exited,
+      kill: () => {
+        ctrl.close();
+        resolveExited(143);
+      },
+    };
+    const mockSpawnAbortSave = mock(
+      () => proc as unknown as ReturnType<typeof Bun.spawn>,
+    );
+
+    mockSetSession.mockClear();
+    const runClaudeAbortSave = createRunClaude(
+      mockSpawnAbortSave as typeof Bun.spawn,
+      testSessions,
+      MODEL,
+      WORKSPACE,
+      fakeSentryClient,
+      undefined,
+      undefined,
+      undefined,
+      5000,
+      5000,
+    );
+
+    const ctl = countedSignal();
+    const { ClaudeAbortedError } = await import("./claude.ts");
+    const runPromise = runClaudeAbortSave(
+      "hello",
+      "chat:thread-1",
+      undefined,
+      ctl.signal,
+    );
+    setTimeout(() => ctl.abort(), 10);
+    const err = await runPromise.catch((e) => e);
+    expect(err).toBeInstanceOf(ClaudeAbortedError);
+    expect(mockSetSession).toHaveBeenCalledWith("chat:thread-1", "abort-sid");
+  });
+
+  test("idle-reset-on-activity: frequent stdout lines keep resetting the idle timer, so no timeout occurs even past the idle window", async () => {
+    // 6 lines at 15ms apart = 90ms total elapsed, well past the 20ms idle
+    // timeout if it were never reset — but each line resets it, so the
+    // idle timer never actually lapses. Ceiling (500ms) has ample headroom.
+    // The stream auto-closes right after the last line, so the run finishes
+    // cleanly (streamIncomplete: true — no result event) instead of hanging.
+    const proc = drippingProc(
+      JSON.stringify({ type: "system", subtype: "init" }),
+      15,
+      6,
+      true, // autoCloseAfterDrip
+    );
+    const mockSpawnActivity = mock(
+      () => proc as unknown as ReturnType<typeof Bun.spawn>,
+    );
+
+    const runClaudeWithIdleReset = createRunClaude(
+      mockSpawnActivity as typeof Bun.spawn,
+      testSessions,
+      MODEL,
+      WORKSPACE,
+      fakeSentryClient,
+      undefined,
+      undefined,
+      undefined,
+      500, // 500ms ceiling — plenty of headroom
+      20, // 20ms idle timeout — shorter than total elapsed time, but reset each 15ms line
+    );
+
+    const output = await runClaudeWithIdleReset("hello");
+    // Stream never got a `result` event but finished cleanly (no timeout) —
+    // proves the idle timer never fired despite total elapsed time exceeding
+    // its window, because each line kept resetting it.
+    expect(output.streamIncomplete).toBe(true);
+  });
+
+  test("idle-fires-despite-ceiling-headroom: stdout goes silent past the idle timeout well before the ceiling would fire", async () => {
+    const proc = hangingProc(); // never emits a line — silent from the start
+    const mockSpawnIdle = mock(
+      () => proc as unknown as ReturnType<typeof Bun.spawn>,
+    );
+
+    const runClaudeIdleOnly = createRunClaude(
+      mockSpawnIdle as typeof Bun.spawn,
+      testSessions,
+      MODEL,
+      WORKSPACE,
+      fakeSentryClient,
+      undefined,
+      undefined,
+      undefined,
+      5000, // 5s ceiling — nowhere near firing in this test
+      15, // 15ms idle timeout — fires quickly since stdout is silent
+    );
+
+    const { ClaudeTimeoutError } = await import("./claude.ts");
+    const err = await runClaudeIdleOnly("hello").catch((e) => e);
+    expect(err).toBeInstanceOf(ClaudeTimeoutError);
+    const timeoutErr = err as InstanceType<typeof ClaudeTimeoutError>;
+    expect(timeoutErr.reason).toBe("idle");
+    // Must report the idle window (15ms) that actually fired, not the 5000ms
+    // ceiling that never came close.
+    expect(timeoutErr.timeoutMs).toBe(15);
+  });
+
+  test("ceiling-fires-despite-continuous-activity: stdout lines keep resetting idle indefinitely, but total elapsed exceeds the ceiling", async () => {
+    // Lines arrive every 5ms — always resetting the idle timer well before
+    // its 30ms window lapses — but the process runs long enough (well past
+    // 25ms) that the 25ms ceiling fires first regardless of activity.
+    const proc = drippingProc(
+      JSON.stringify({ type: "system", subtype: "init" }),
+      5,
+      50, // enough lines to keep the drip going past the ceiling
+    );
+
+    const mockSpawnCeiling = mock(
+      () => proc as unknown as ReturnType<typeof Bun.spawn>,
+    );
+
+    const runClaudeCeiling = createRunClaude(
+      mockSpawnCeiling as typeof Bun.spawn,
+      testSessions,
+      MODEL,
+      WORKSPACE,
+      fakeSentryClient,
+      undefined,
+      undefined,
+      undefined,
+      25, // 25ms ceiling — fires despite continuous sub-idle-window activity
+      30, // 30ms idle timeout — never lapses since lines arrive every 5ms
+    );
+
+    const { ClaudeTimeoutError } = await import("./claude.ts");
+    const err = await runClaudeCeiling("hello").catch((e) => e);
+    expect(err).toBeInstanceOf(ClaudeTimeoutError);
+    expect((err as InstanceType<typeof ClaudeTimeoutError>).reason).toBe(
+      "ceiling",
+    );
+  });
+
+  test("non-zero exit with JSON stdout throws ClaudeRunError with api_error_status", async () => {
+    const json = JSON.stringify({
+      type: "result",
+      subtype: "error",
+      result: "You've hit your org's monthly usage limit",
+      session_id: "sess-x",
+      is_error: true,
+      api_error_status: 429,
+    });
+    mockSpawn.mockReturnValue(
+      fakeProc(json, "", 1) as ReturnType<typeof Bun.spawn>,
+    );
+    const { ClaudeRunError } = await import("./claude.ts");
+    try {
+      await runClaude("hello");
+      throw new Error("expected throw");
+    } catch (err) {
+      expect(err).toBeInstanceOf(ClaudeRunError);
+      const e = err as InstanceType<typeof ClaudeRunError>;
+      expect(e.apiErrorStatus).toBe(429);
+      expect(e.resultMessage).toContain("monthly usage limit");
+    }
+  });
+});
+
+// ─── Process-tree kill on timeout ─────────────────────────────────────────────
+
+/**
+ * Unlike every other test in this file (which injects a fully synthetic
+ * FakeProc), these spawn a REAL subprocess through the same `spawner`
+ * injection seam — because the behavior under test only exists at the OS
+ * level: a `claude` CLI that forked its own children (an install, a build)
+ * leaves those children running when only the direct child is signalled.
+ * A fake proc can't express that.
+ *
+ * The stub script forks a long-lived grandchild, records its pid to a temp
+ * file, and then waits forever without writing to stdout — so the ceiling
+ * timer is what ends the run, exactly like a session that blew its budget.
+ *
+ * Without the fix these don't just leak a process, they hang: the orphaned
+ * grandchild inherited the stdout pipe, so `_consumeStream` never sees EOF
+ * and the run never settles at all. Both tests therefore fail (by timeout)
+ * against a bare `proc.kill()`.
+ *
+ * Linux-only (procfs); self-skips elsewhere, matching the agent's runtime.
+ */
+const canSpawnRealProcs =
+  process.platform === "linux" && existsSync("/proc/self/task");
+
+/** False for a pid that is gone OR an unreaped zombie (SIGKILLed orphan). */
+function pidIsAlive(pid: number): boolean {
+  let stat: string;
+  try {
+    stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+  } catch {
+    return false;
+  }
+  const close = stat.lastIndexOf(")");
+  return stat.slice(close + 2, close + 3) !== "Z";
+}
+
+async function waitForPidDeath(
+  pid: number,
+  timeoutMs = 1500,
+): Promise<boolean> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (!pidIsAlive(pid)) return true;
+    await Bun.sleep(10);
+  }
+  return !pidIsAlive(pid);
+}
+
+describe.if(canSpawnRealProcs)("process-tree kill on timeout", () => {
+  test("a ceiling timeout kills the spawned CLI's forked descendant, not just the CLI itself", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "shipwright-treekill-"));
+    const pidFile = join(dir, "grandchild.pid");
+    const script = join(dir, "stub-claude.sh");
+    // `sleep 300 &` stands in for an install/build the CLI kicked off; the
+    // parent then blocks on `wait` and never writes to stdout, so only the
+    // ceiling timer can end it.
+    writeFileSync(
+      script,
+      `#!/bin/sh\nsleep 300 &\necho $! > "${pidFile}"\nwait\n`,
+    );
+
+    // Thin wrapper around the real Bun.spawn: swaps the `claude` argv for the
+    // stub script while passing every option through untouched (cwd, env, and
+    // — critically — whatever cgroup option the implementation adds).
+    const realSpawner = ((
+      _cmd: string[],
+      opts: Bun.SpawnOptions.OptionsObject<"ignore", "pipe", "pipe">,
+    ) => Bun.spawn(["sh", script], opts)) as unknown as typeof Bun.spawn;
+
+    const runClaudeRealProc = createRunClaude(
+      realSpawner,
+      testSessions,
+      MODEL,
+      WORKSPACE,
+      fakeSentryClient,
+      undefined,
+      undefined,
+      undefined,
+      300, // 300ms ceiling — fires quickly, keeps the suite fast
+      5000, // idle far away: the ceiling is the trigger under test
+    );
+
+    try {
+      const err = await runClaudeRealProc("hello").catch((e) => e);
+      expect(err).toBeInstanceOf(ClaudeTimeoutError);
+      expect((err as InstanceType<typeof ClaudeTimeoutError>).reason).toBe(
+        "ceiling",
+      );
+
+      const grandchildPid = Number.parseInt(
+        readFileSync(pidFile, "utf8").trim(),
+        10,
+      );
+      expect(Number.isInteger(grandchildPid)).toBe(true);
+      // The whole point: before the process-tree kill, this grandchild was
+      // reparented to init and kept running past the timeout.
+      expect(await waitForPidDeath(grandchildPid)).toBe(true);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("an AbortSignal kills the spawned CLI's forked descendant too", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "shipwright-treekill-abort-"));
+    const pidFile = join(dir, "grandchild.pid");
+    const script = join(dir, "stub-claude.sh");
+    writeFileSync(
+      script,
+      `#!/bin/sh\nsleep 300 &\necho $! > "${pidFile}"\nwait\n`,
+    );
+
+    const realSpawner = ((
+      _cmd: string[],
+      opts: Bun.SpawnOptions.OptionsObject<"ignore", "pipe", "pipe">,
+    ) => Bun.spawn(["sh", script], opts)) as unknown as typeof Bun.spawn;
+
+    const runClaudeRealProc = createRunClaude(
+      realSpawner,
+      testSessions,
+      MODEL,
+      WORKSPACE,
+      fakeSentryClient,
+      undefined,
+      undefined,
+      undefined,
+      10_000, // neither timer should fire — the abort is the trigger
+      10_000,
+    );
+
+    try {
+      const ctl = new AbortController();
+      const runPromise = runClaudeRealProc(
+        "hello",
+        undefined,
+        undefined,
+        ctl.signal,
+      );
+      // Give the stub time to fork and record its grandchild pid.
+      const deadline = Date.now() + 1500;
+      while (!existsSync(pidFile) && Date.now() < deadline) await Bun.sleep(10);
+      ctl.abort();
+
+      const { ClaudeAbortedError } = await import("./claude.ts");
+      const err = await runPromise.catch((e) => e);
+      expect(err).toBeInstanceOf(ClaudeAbortedError);
+
+      const grandchildPid = Number.parseInt(
+        readFileSync(pidFile, "utf8").trim(),
+        10,
+      );
+      expect(await waitForPidDeath(grandchildPid)).toBe(true);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});
+
+// ─── Stale session fallback tests ─────────────────────────────────────────────
+
+describe("resume retry", () => {
+  test("retries the same resumed session once when it fails, then succeeds", async () => {
+    let callCount = 0;
+    const mockSpawn = mock(() => {
+      callCount++;
+      if (callCount === 1) {
+        // First call (resume) fails
+        return fakeProc("", "socket closed", 1) as ReturnType<typeof Bun.spawn>;
+      }
+      // Second call (retry, same resumed session) succeeds
+      return fakeProc(jsonOutput("recovered", "stale-sess-id")) as ReturnType<
+        typeof Bun.spawn
+      >;
+    });
+
+    mockGetSession.mockClear();
+    mockSetSession.mockClear();
+    mockClearSession.mockClear();
+    capturedMessages = [];
+    capturedExceptions = [];
+    mockGetSession.mockReturnValue("stale-sess-id");
+
+    const runClaude = createRunClaude(
+      mockSpawn as typeof Bun.spawn,
+      testSessions,
+      MODEL,
+      WORKSPACE,
+      fakeSentryClient,
+    );
+
+    const result = await runClaude("hello", "chan:ts");
+
+    expect(result.result).toBe("recovered");
+    expect(result.sessionId).toBe("stale-sess-id");
+    expect(result.recoveredFromError).toBe(true);
+    expect(mockClearSession).not.toHaveBeenCalled();
+    expect(mockSetSession).toHaveBeenCalledWith("chan:ts", "stale-sess-id");
+    expect(mockSpawn).toHaveBeenCalledTimes(2);
+
+    // Verify both calls resumed the SAME session id via -r
+    const [firstCmd] = mockSpawn.mock.calls[0] as unknown as [string[]];
+    const [secondCmd] = mockSpawn.mock.calls[1] as unknown as [string[]];
+    const firstRIdx = firstCmd.indexOf("-r");
+    const secondRIdx = secondCmd.indexOf("-r");
+    expect(firstRIdx).toBeGreaterThan(-1);
+    expect(secondRIdx).toBeGreaterThan(-1);
+    expect(firstCmd[firstRIdx + 1]).toBe("stale-sess-id");
+    expect(secondCmd[secondRIdx + 1]).toBe("stale-sess-id");
+  });
+
+  test("passes extraEnv to both the initial attempt and the resume-retry attempt", async () => {
+    let callCount = 0;
+    const mockSpawn = mock(() => {
+      callCount++;
+      if (callCount === 1) {
+        // First call (resume) fails
+        return fakeProc("", "socket closed", 1) as ReturnType<typeof Bun.spawn>;
+      }
+      // Second call (retry, same resumed session) succeeds
+      return fakeProc(jsonOutput("recovered", "stale-sess-id")) as ReturnType<
+        typeof Bun.spawn
+      >;
+    });
+
+    mockGetSession.mockClear();
+    mockSetSession.mockClear();
+    mockClearSession.mockClear();
+    capturedMessages = [];
+    capturedExceptions = [];
+    mockGetSession.mockReturnValue("stale-sess-id");
+
+    const runClaude = createRunClaude(
+      mockSpawn as typeof Bun.spawn,
+      testSessions,
+      MODEL,
+      WORKSPACE,
+      fakeSentryClient,
+    );
+
+    await runClaude("hello", "chan:ts", undefined, undefined, {
+      MY_VAR: "retry-value",
+    });
+
+    expect(mockSpawn).toHaveBeenCalledTimes(2);
+    const [, firstOpts] = mockSpawn.mock.calls[0] as unknown as [
+      string[],
+      { env: Record<string, string | undefined> },
+    ];
+    const [, secondOpts] = mockSpawn.mock.calls[1] as unknown as [
+      string[],
+      { env: Record<string, string | undefined> },
+    ];
+    expect(firstOpts.env.MY_VAR).toBe("retry-value");
+    expect(secondOpts.env.MY_VAR).toBe("retry-value");
+  });
+
+  test("per-call onProgress still fires on the second _spawn attempt during a resume-retry", async () => {
+    let callCount = 0;
+    const mockSpawn = mock(() => {
+      callCount++;
+      if (callCount === 1) {
+        // First call (resume) fails
+        return fakeProc("", "socket closed", 1) as ReturnType<typeof Bun.spawn>;
+      }
+      // Second call (retry, same resumed session) succeeds and streams
+      // stream-json turns, so per-call onProgress has something to fire on.
+      return ndjsonProc(cleanMultiTurn.lines) as ReturnType<typeof Bun.spawn>;
+    });
+
+    mockGetSession.mockClear();
+    mockSetSession.mockClear();
+    mockClearSession.mockClear();
+    capturedMessages = [];
+    capturedExceptions = [];
+    mockGetSession.mockReturnValue("stale-sess-id");
+
+    const runClaude = createRunClaude(
+      mockSpawn as typeof Bun.spawn,
+      testSessions,
+      MODEL,
+      WORKSPACE,
+      fakeSentryClient,
+    );
+
+    const progress: Array<Record<string, unknown>> = [];
+    const result = await runClaude("hello", "chan:ts", (mu, phase) => {
+      if (phase === undefined) progress.push(structuredClone(mu));
+    });
+
+    expect(result.recoveredFromError).toBe(true);
+    expect(mockSpawn).toHaveBeenCalledTimes(2);
+    // Progress must have fired during the retried (second) _spawn attempt.
+    expect(progress).toHaveLength(cleanMultiTurn.expectedProgressCount);
+    expect(progress[progress.length - 1]).toEqual(
+      cleanMultiTurn.expectedAccumulated,
+    );
+  });
+
+  test("does not retry when there is no existing session (fresh call fails)", async () => {
+    const mockSpawn = mock(
+      () => fakeProc("", "auth failure", 1) as ReturnType<typeof Bun.spawn>,
+    );
+
+    mockGetSession.mockClear();
+    mockGetSession.mockReturnValue(undefined);
+
+    const runClaude = createRunClaude(
+      mockSpawn as typeof Bun.spawn,
+      testSessions,
+      MODEL,
+      WORKSPACE,
+    );
+
+    await expect(runClaude("hello")).rejects.toThrow("auth failure");
+    expect(mockSpawn).toHaveBeenCalledTimes(1);
+  });
+
+  test("throws if both resume attempts fail, preserving the session mapping", async () => {
+    const mockSpawn = mock(
+      () => fakeProc("", "total failure", 1) as ReturnType<typeof Bun.spawn>,
+    );
+
+    // Stateful in-memory session store double — NOT the module-level spy mocks.
+    const store = new Map<string, string>([["chan:ts", "stale-sess"]]);
+    const clearSpy = mock((_key: string): void => {});
+    const statefulSessions = {
+      get: (key: string) => store.get(key),
+      set: (key: string, id: string) => {
+        store.set(key, id);
+      },
+      clear: clearSpy,
+    };
+
+    const runClaude = createRunClaude(
+      mockSpawn as typeof Bun.spawn,
+      statefulSessions,
+      MODEL,
+      WORKSPACE,
+      fakeSentryClient,
+    );
+
+    await expect(runClaude("hello", "chan:ts")).rejects.toThrow(
+      "total failure",
+    );
+    expect(mockSpawn).toHaveBeenCalledTimes(2);
+    expect(clearSpy).not.toHaveBeenCalled();
+    // The mapping must still point at the original session id.
+    expect(store.get("chan:ts")).toBe("stale-sess");
+    // Retry-exhausted case is reported to Sentry with the ORIGINAL error.
+    expect(capturedExceptions).toHaveLength(1);
+    expect((capturedExceptions[0] as Error).message).toContain("total failure");
+  });
+
+  test("does not report to Sentry when the retry succeeds", async () => {
+    let callCount = 0;
+    const mockSpawn = mock(() => {
+      callCount++;
+      if (callCount === 1) {
+        return fakeProc("", "socket closed", 1) as ReturnType<typeof Bun.spawn>;
+      }
+      return fakeProc(jsonOutput("recovered", "stale-sess-id")) as ReturnType<
+        typeof Bun.spawn
+      >;
+    });
+
+    mockGetSession.mockClear();
+    mockSetSession.mockClear();
+    mockClearSession.mockClear();
+    capturedExceptions = [];
+    mockGetSession.mockReturnValue("stale-sess-id");
+
+    const runClaude = createRunClaude(
+      mockSpawn as typeof Bun.spawn,
+      testSessions,
+      MODEL,
+      WORKSPACE,
+      fakeSentryClient,
+    );
+
+    const result = await runClaude("hello", "chan:ts");
+
+    expect(result.recoveredFromError).toBe(true);
+    expect(capturedExceptions).toHaveLength(0);
+  });
+});
+
+// ─── Connection-lost-mid-response retry (error-7616867192) ────────────────────
+//
+// A transient network drop between the Claude Code CLI and the Anthropic API
+// mid-response throws a ClaudeRunError whose result text contains "Connection
+// lost mid-response" (Sentry issue 7616867192 / SENTRY-47). Per human
+// decision (Dave, 2026-09-08), `_spawn` retries this specific failure exactly
+// once — discarding the partial response and re-running the whole spawn from
+// scratch — regardless of whether a session exists to resume. This is
+// independent of (and orthogonal to) the session-resume retry above.
+
+function connectionLostJson(sessionId = "sess-cl"): string {
+  return JSON.stringify({
+    type: "result",
+    subtype: "error",
+    result:
+      "API Error: Connection lost mid-response. The response above may be incomplete.",
+    session_id: sessionId,
+    is_error: true,
+  });
+}
+
+describe("connection-lost-mid-response retry", () => {
+  test("retries once even with no existing session to resume, then succeeds", async () => {
+    let callCount = 0;
+    const mockSpawn = mock(() => {
+      callCount++;
+      if (callCount === 1) {
+        return fakeProc(connectionLostJson(), "", 1) as ReturnType<
+          typeof Bun.spawn
+        >;
+      }
+      return fakeProc(jsonOutput("recovered", "sess-cl")) as ReturnType<
+        typeof Bun.spawn
+      >;
+    });
+
+    mockGetSession.mockClear();
+    mockGetSession.mockReturnValue(undefined);
+    capturedMessages = [];
+    capturedExceptions = [];
+
+    const runClaude = createRunClaude(
+      mockSpawn as typeof Bun.spawn,
+      testSessions,
+      MODEL,
+      WORKSPACE,
+      fakeSentryClient,
+    );
+
+    const result = await runClaude("hello");
+
+    expect(result.result).toBe("recovered");
+    expect(mockSpawn).toHaveBeenCalledTimes(2);
+    expect(capturedMessages).toHaveLength(1);
+    expect(capturedMessages[0]).toContain("Connection lost mid-response");
+    expect(capturedExceptions).toHaveLength(0);
+  });
+
+  test("does not retry a second time when the retry also hits connection-lost-mid-response", async () => {
+    const mockSpawn = mock(
+      () =>
+        fakeProc(connectionLostJson(), "", 1) as ReturnType<typeof Bun.spawn>,
+    );
+
+    mockGetSession.mockClear();
+    mockGetSession.mockReturnValue(undefined);
+    capturedMessages = [];
+    capturedExceptions = [];
+
+    const { ClaudeRunError } = await import("./claude.ts");
+    const runClaude = createRunClaude(
+      mockSpawn as typeof Bun.spawn,
+      testSessions,
+      MODEL,
+      WORKSPACE,
+      fakeSentryClient,
+    );
+
+    await expect(runClaude("hello")).rejects.toBeInstanceOf(ClaudeRunError);
+    expect(mockSpawn).toHaveBeenCalledTimes(2);
+    // Logged once, for the one retry attempt — not on the second failure.
+    expect(capturedMessages).toHaveLength(1);
+  });
+
+  test("an unrelated is_error failure is NOT retried via _spawn's own connection-lost mechanism, but IS retried once via the widened outer gate (it carries a session id)", async () => {
+    // This failure is not connection-lost-mid-response, so `_spawn`'s own
+    // dedicated single retry (and its Sentry captureMessage) never fires —
+    // capturedMessages stays empty throughout. But per the widened retry
+    // gate (see `_runClaude`), ANY ClaudeRunError that carries a session id
+    // (this one does: result.session_id = "sess-x") is now eligible for
+    // _runClaude's own one-shot outer retry, even on a fresh call with no
+    // existingSessionId — this is the acceptance-criterion behavior, not a
+    // connection-lost special case.
+    const mockSpawn = mock(
+      () =>
+        fakeProc(
+          jsonOutput(
+            "You've hit your org's monthly usage limit",
+            "sess-x",
+            true,
+          ),
+          "",
+          1,
+        ) as ReturnType<typeof Bun.spawn>,
+    );
+
+    mockGetSession.mockClear();
+    mockGetSession.mockReturnValue(undefined);
+    capturedMessages = [];
+    capturedExceptions = [];
+
+    const runClaude = createRunClaude(
+      mockSpawn as typeof Bun.spawn,
+      testSessions,
+      MODEL,
+      WORKSPACE,
+      fakeSentryClient,
+    );
+
+    await expect(runClaude("hello")).rejects.toThrow("monthly usage limit");
+    // Outer gate retried once (both attempts fail identically) — one retry
+    // only, matching the existing one-retry-only contract.
+    expect(mockSpawn).toHaveBeenCalledTimes(2);
+    // The retry used -r sess-x, the session id carried by the error.
+    const [secondCmd] = mockSpawn.mock.calls[1] as unknown as [string[]];
+    const rIdx = secondCmd.indexOf("-r");
+    expect(rIdx).toBeGreaterThan(-1);
+    expect(secondCmd[rIdx + 1]).toBe("sess-x");
+    // No connection-lost captureMessage — this path is unrelated to that
+    // mechanism.
+    expect(capturedMessages).toHaveLength(0);
+    // The exhausted-retry Sentry capture still fires with the ORIGINAL error.
+    expect(capturedExceptions).toHaveLength(1);
+  });
+});
+
+// ─── Session persistence on failure (CSI-1.2) ─────────────────────────────────
+//
+// _saveSession only ran after a successful spawn, so a first-message timeout
+// or error never persisted the session id the CLI had already created —
+// leaving the Slack thread unable to resume. These tests assert the failure
+// path now saves whatever session id was captured, even though the run
+// itself still throws.
+
+describe("session persistence on failure", () => {
+  test("immediate timeout with no existing session still saves the captured session id", async () => {
+    // hangingProc never emits a line, so idle timeout fires with no
+    // earlySessionId captured off a `system`/`init` line either — this test
+    // uses a dripping proc that emits exactly one init line (carrying a
+    // session id) before going silent, so the idle timer still fires but a
+    // sessionId is available on the resulting ClaudeTimeoutError.
+    const proc = drippingProc(
+      JSON.stringify({
+        type: "system",
+        subtype: "init",
+        session_id: "fresh-sess-id",
+      }),
+      1000, // only fires once at start via the drip loop's initial enqueue+wait
+      1,
+    );
+    const mockSpawnTimeout = mock(
+      () => proc as unknown as ReturnType<typeof Bun.spawn>,
+    );
+
+    mockGetSession.mockClear();
+    mockSetSession.mockClear();
+    mockGetSession.mockReturnValue(undefined);
+
+    const runClaudeWithTimeout = createRunClaude(
+      mockSpawnTimeout as typeof Bun.spawn,
+      testSessions,
+      MODEL,
+      WORKSPACE,
+      fakeSentryClient,
+      undefined,
+      undefined,
+      undefined,
+      5000, // ceiling — nowhere near firing
+      15, // idle timeout — fires quickly since stdout only emits the one line
+    );
+
+    const { ClaudeTimeoutError } = await import("./claude.ts");
+    const err = await runClaudeWithTimeout("hello", "chan:ts").catch((e) => e);
+    expect(err).toBeInstanceOf(ClaudeTimeoutError);
+    expect((err as InstanceType<typeof ClaudeTimeoutError>).sessionId).toBe(
+      "fresh-sess-id",
+    );
+    // No existing session, so no retry happens — the outer catch must save
+    // the session id from the initial attempt's failure directly.
+    expect(mockSetSession).toHaveBeenCalledWith("chan:ts", "fresh-sess-id");
+  });
+
+  test("resumed-session retry that also times out saves the most-recently-known session id", async () => {
+    let callCount = 0;
+    const mockSpawnRetry = mock(() => {
+      callCount++;
+      if (callCount === 1) {
+        // First call (resume) fails with a non-timeout error — enters the
+        // retry branch.
+        return fakeProc("", "socket closed", 1) as ReturnType<typeof Bun.spawn>;
+      }
+      // Retry attempt hangs and times out, but still captures a session id
+      // off its own init line before the idle timer kills it.
+      return drippingProc(
+        JSON.stringify({
+          type: "system",
+          subtype: "init",
+          session_id: "retry-sess-id",
+        }),
+        1000,
+        1,
+      ) as unknown as ReturnType<typeof Bun.spawn>;
+    });
+
+    mockGetSession.mockClear();
+    mockSetSession.mockClear();
+    mockGetSession.mockReturnValue("stale-sess-id");
+
+    const runClaudeWithRetryTimeout = createRunClaude(
+      mockSpawnRetry as typeof Bun.spawn,
+      testSessions,
+      MODEL,
+      WORKSPACE,
+      fakeSentryClient,
+      undefined,
+      undefined,
+      undefined,
+      5000, // ceiling — nowhere near firing
+      15, // idle timeout — fires quickly on the retry's silent stdout
+    );
+
+    const err = await runClaudeWithRetryTimeout("hello", "chan:ts").catch(
+      (e) => e,
+    );
+    // The retry contract rethrows the ORIGINAL (first-attempt) error
+    // unchanged, even though the retry itself failed with a timeout — only
+    // the session-persistence side effect changes.
+    expect(err).toBeInstanceOf(Error);
+    expect((err as Error).message).toContain("socket closed");
+    expect(mockSpawnRetry).toHaveBeenCalledTimes(2);
+    // The mapping must point at the retry's session id — the most recently
+    // known one — not the original stale session id.
+    expect(mockSetSession).toHaveBeenCalledWith("chan:ts", "retry-sess-id");
+    expect(mockSetSession).toHaveBeenLastCalledWith("chan:ts", "retry-sess-id");
+  });
+
+  test("does not save when no sessionId was ever captured (process crashes before any stdout)", async () => {
+    const mockSpawnCrash = mock(
+      () => fakeProc("", "segfault", 139) as ReturnType<typeof Bun.spawn>,
+    );
+
+    mockGetSession.mockClear();
+    mockSetSession.mockClear();
+    mockGetSession.mockReturnValue(undefined);
+
+    const runClaudeCrash = createRunClaude(
+      mockSpawnCrash as typeof Bun.spawn,
+      testSessions,
+      MODEL,
+      WORKSPACE,
+      fakeSentryClient,
+    );
+
+    await expect(runClaudeCrash("hello", "chan:ts")).rejects.toThrow(
+      "segfault",
+    );
+    expect(mockSetSession).not.toHaveBeenCalled();
+  });
+
+  test("a session store write failure on the initial-attempt catch does not mask the original error", async () => {
+    // No existing session, so no retry happens — this exercises the
+    // initial `catch (err)` call site's guard directly.
+    const proc = drippingProc(
+      JSON.stringify({
+        type: "system",
+        subtype: "init",
+        session_id: "fresh-sess-id",
+      }),
+      1000,
+      1,
+    );
+    const mockSpawnTimeout = mock(
+      () => proc as unknown as ReturnType<typeof Bun.spawn>,
+    );
+
+    const throwingSetSession = mock((_key: string, _id: string) => {
+      throw new Error("disk full");
+    });
+    const throwingSessions = {
+      get: (_key: string): string | undefined => undefined,
+      set: throwingSetSession,
+      clear: (_key: string) => {},
+    };
+
+    const runClaudeWithTimeout = createRunClaude(
+      mockSpawnTimeout as typeof Bun.spawn,
+      throwingSessions,
+      MODEL,
+      WORKSPACE,
+      fakeSentryClient,
+      undefined,
+      undefined,
+      undefined,
+      5000, // ceiling — nowhere near firing
+      15, // idle timeout — fires quickly since stdout only emits the one line
+    );
+
+    const { ClaudeTimeoutError } = await import("./claude.ts");
+    const err = await runClaudeWithTimeout("hello", "chan:ts").catch((e) => e);
+    // The persistence failure must never replace the original timeout error.
+    expect(err).toBeInstanceOf(ClaudeTimeoutError);
+    expect((err as InstanceType<typeof ClaudeTimeoutError>).sessionId).toBe(
+      "fresh-sess-id",
+    );
+    expect(throwingSetSession).toHaveBeenCalledWith("chan:ts", "fresh-sess-id");
+  });
+
+  test("a session store write failure on the retry catch does not mask the original error or skip Sentry capture", async () => {
+    let callCount = 0;
+    const mockSpawnRetry = mock(() => {
+      callCount++;
+      if (callCount === 1) {
+        // First call (resume) fails with a non-timeout error — enters the
+        // retry branch.
+        return fakeProc("", "socket closed", 1) as ReturnType<typeof Bun.spawn>;
+      }
+      // Retry attempt hangs and times out, but still captures a session id
+      // off its own init line before the idle timer kills it.
+      return drippingProc(
+        JSON.stringify({
+          type: "system",
+          subtype: "init",
+          session_id: "retry-sess-id",
+        }),
+        1000,
+        1,
+      ) as unknown as ReturnType<typeof Bun.spawn>;
+    });
+
+    const throwingSetSession = mock((_key: string, _id: string) => {
+      throw new Error("disk full");
+    });
+    const throwingSessions = {
+      get: (_key: string): string | undefined => "stale-sess-id",
+      set: throwingSetSession,
+      clear: (_key: string) => {},
+    };
+
+    capturedExceptions = [];
+    const runClaudeWithRetryTimeout = createRunClaude(
+      mockSpawnRetry as typeof Bun.spawn,
+      throwingSessions,
+      MODEL,
+      WORKSPACE,
+      fakeSentryClient,
+      undefined,
+      undefined,
+      undefined,
+      5000, // ceiling — nowhere near firing
+      15, // idle timeout — fires quickly on the retry's silent stdout
+    );
+
+    const err = await runClaudeWithRetryTimeout("hello", "chan:ts").catch(
+      (e) => e,
+    );
+    // The retry contract rethrows the ORIGINAL (first-attempt) error
+    // unchanged, even though the retry's own session-persistence write
+    // threw.
+    expect(err).toBeInstanceOf(Error);
+    expect((err as Error).message).toContain("socket closed");
+    expect(mockSpawnRetry).toHaveBeenCalledTimes(2);
+    expect(throwingSetSession).toHaveBeenCalledWith("chan:ts", "retry-sess-id");
+    // Sentry capture of the ORIGINAL error must still run despite the
+    // persistence failure.
+    expect(capturedExceptions).toHaveLength(1);
+    expect((capturedExceptions[0] as Error).message).toContain("socket closed");
+  });
+
+  test("saves the captured session id immediately on the init line, before the run settles (ESP-1.1)", async () => {
+    // Simulates the orchestrator process itself dying mid-run (OOM, pod
+    // restart, redeploy) — not just the spawned `claude` CLI child being
+    // killed. If persistence only happens at settle time (via _saveSession /
+    // _saveSessionFromError), a process death between the init line and the
+    // run settling loses the session id even though the CLI session itself
+    // is already durably resumable. `autoCloseAfterDrip: false` keeps
+    // `exited` pending indefinitely — nothing settles until we `.kill()` it
+    // below — so this test can only pass if the write happens off the init
+    // line itself, not off any catch/finally.
+    const intervalMs = 20;
+    const proc = drippingProc(
+      JSON.stringify({
+        type: "system",
+        subtype: "init",
+        session_id: "early-write-sess-id",
+      }),
+      intervalMs,
+      3, // several drips — exited must stay pending well past the first one
+      false, // never auto-closes; only kill() (called below) settles it
+    );
+    const mockSpawnEarly = mock(
+      () => proc as unknown as ReturnType<typeof Bun.spawn>,
+    );
+
+    mockGetSession.mockClear();
+    mockSetSession.mockClear();
+    mockGetSession.mockReturnValue(undefined);
+
+    const runClaudeEarly = createRunClaude(
+      mockSpawnEarly as typeof Bun.spawn,
+      testSessions,
+      MODEL,
+      WORKSPACE,
+      fakeSentryClient,
+    );
+
+    // Deliberately NOT awaited yet — the run must still be in flight when we
+    // assert below.
+    const pending = runClaudeEarly("hello", "chan:ts");
+
+    // Wait just long enough for the first drip (the init line) to land, but
+    // nowhere near long enough for the process to settle (it never will,
+    // short of the kill() below).
+    await new Promise((r) => setTimeout(r, intervalMs + 30));
+
+    expect(mockSetSession).toHaveBeenCalledWith(
+      "chan:ts",
+      "early-write-sess-id",
+    );
+
+    // Clean up: kill the dripping proc so `exited` resolves, then let the
+    // pending run settle (successfully or not — irrelevant here) so no
+    // dangling timer/promise leaks into later tests.
+    proc.kill();
+    await pending.catch(() => {});
+  });
+});
+
+// ─── _enqueue serialization tests ────────────────────────────────────────────
+
+describe("_enqueue (via runClaude with sessionKey)", () => {
+  beforeEach(() => {
+    mockGetSession.mockReset();
+    mockSetSession.mockReset();
+    mockClearSession.mockReset();
+  });
+
+  test("second call with same key waits for first to complete before spawning", async () => {
+    let spawnCount = 0;
+    let resolveFirst!: (code: number) => void;
+    const firstExited = new Promise<number>((r) => {
+      resolveFirst = r;
+    });
+
+    const mockSpawn = mock(() => {
+      spawnCount++;
+      const exited = spawnCount === 1 ? firstExited : Promise.resolve(0);
+      return {
+        stdout: bodyStream(jsonOutput(`result-${spawnCount}`)),
+        stderr: bodyStream(""),
+        exited,
+      } as ReturnType<typeof Bun.spawn>;
+    });
+    const runClaude = createRunClaude(
+      mockSpawn as typeof Bun.spawn,
+      testSessions,
+      MODEL,
+      WORKSPACE,
+    );
+
+    const p1 = runClaude("msg1", "serial-key");
+    const p2 = runClaude("msg2", "serial-key");
+
+    await new Promise((r) => setTimeout(r, 0));
+    expect(spawnCount).toBe(1);
+
+    resolveFirst(0);
+    await p1;
+
+    await new Promise((r) => setTimeout(r, 0));
+    expect(spawnCount).toBe(2);
+
+    await p2;
+  });
+
+  test("calls with different keys run concurrently (not serialized)", async () => {
+    const mockSpawn = mock(() => {
+      return {
+        stdout: bodyStream(jsonOutput("ok")),
+        stderr: bodyStream(""),
+        exited: Promise.resolve(0),
+      } as ReturnType<typeof Bun.spawn>;
+    });
+    const runClaude = createRunClaude(
+      mockSpawn as typeof Bun.spawn,
+      testSessions,
+      MODEL,
+      WORKSPACE,
+    );
+
+    const [r1, r2] = await Promise.all([
+      runClaude("msg1", "key-a"),
+      runClaude("msg2", "key-b"),
+    ]);
+
+    expect(r1.result).toBe("ok");
+    expect(r2.result).toBe("ok");
+  });
+
+  test("second call still runs after first call throws", async () => {
+    let callCount = 0;
+    const mockSpawn = mock(() => {
+      callCount++;
+      const exitCode = callCount === 1 ? 1 : 0;
+      return {
+        stdout: bodyStream(callCount === 1 ? "" : jsonOutput("recovered")),
+        stderr: bodyStream(callCount === 1 ? "error on first" : ""),
+        exited: Promise.resolve(exitCode),
+      } as ReturnType<typeof Bun.spawn>;
+    });
+    const runClaude = createRunClaude(
+      mockSpawn as typeof Bun.spawn,
+      testSessions,
+      MODEL,
+      WORKSPACE,
+    );
+
+    const p1 = runClaude("msg1", "error-key");
+    const p2 = runClaude("msg2", "error-key");
+
+    await expect(p1).rejects.toThrow();
+    const r2 = await p2;
+    expect(r2.result).toBe("recovered");
+  });
+});
+
+// ─── extraAllowedTools tests ──────────────────────────────────────────────────
+
+describe("extraAllowedTools", () => {
+  // biome-ignore lint/suspicious/noExplicitAny: mock return type
+  let mockSpawn: any;
+
+  // Extracts the tool names listed after --allowedTools, up to the next flag
+  function extractAllowedTools(cmd: string[]): string[] {
+    const allowedIdx = cmd.indexOf("--allowedTools");
+    const tools: string[] = [];
+    for (let i = allowedIdx + 1; i < cmd.length; i++) {
+      if (cmd[i].startsWith("-")) break;
+      tools.push(cmd[i]);
+    }
+    return tools;
+  }
+
+  beforeEach(() => {
+    mockGetSession.mockClear();
+    mockSetSession.mockClear();
+    mockClearSession.mockClear();
+    capturedMessages = [];
+    capturedExceptions = [];
+    mockSpawn = mock(
+      () =>
+        fakeProc(jsonOutput("Hello from Claude")) as ReturnType<
+          typeof Bun.spawn
+        >,
+    );
+  });
+
+  test("empty extraAllowedTools produces identical args to no extraAllowedTools", async () => {
+    const runClaudeDefault = createRunClaude(
+      mockSpawn as typeof Bun.spawn,
+      testSessions,
+      MODEL,
+      WORKSPACE,
+      fakeSentryClient,
+    );
+    const runClaudeEmpty = createRunClaude(
+      mockSpawn as typeof Bun.spawn,
+      testSessions,
+      MODEL,
+      WORKSPACE,
+      fakeSentryClient,
+      [],
+    );
+
+    await runClaudeDefault("test");
+    const [defaultCmd] = mockSpawn.mock.calls[0] as [string[]];
+
+    mockSpawn.mockClear();
+
+    await runClaudeEmpty("test");
+    const [emptyCmd] = mockSpawn.mock.calls[0] as [string[]];
+
+    expect(emptyCmd).toEqual(defaultCmd);
+  });
+
+  test("non-empty extraAllowedTools are appended after existing tools in --allowedTools", async () => {
+    const runClaude = createRunClaude(
+      mockSpawn as typeof Bun.spawn,
+      testSessions,
+      MODEL,
+      WORKSPACE,
+      fakeSentryClient,
+      ["mcp__my_server__my_tool", "mcp__other__tool"],
+    );
+
+    await runClaude("test");
+    const [cmd] = mockSpawn.mock.calls[0] as [string[]];
+
+    expect(cmd.indexOf("--allowedTools")).toBeGreaterThan(-1);
+    const toolsInCmd = extractAllowedTools(cmd);
+
+    expect(toolsInCmd).toContain("mcp__my_server__my_tool");
+    expect(toolsInCmd).toContain("mcp__other__tool");
+  });
+
+  test("extraAllowedTools appear after built-in tools (not before)", async () => {
+    const runClaude = createRunClaude(
+      mockSpawn as typeof Bun.spawn,
+      testSessions,
+      MODEL,
+      WORKSPACE,
+      fakeSentryClient,
+      ["mcp__extra__tool"],
+    );
+
+    await runClaude("test");
+    const [cmd] = mockSpawn.mock.calls[0] as [string[]];
+
+    const allowedIdx = cmd.indexOf("--allowedTools");
+    const extraIdx = cmd.indexOf("mcp__extra__tool");
+    const skillIdx = cmd.indexOf("Skill"); // built-in floor tool, last in FLOOR_TOOLS order
+
+    expect(extraIdx).toBeGreaterThan(allowedIdx);
+    expect(extraIdx).toBeGreaterThan(skillIdx);
+  });
+
+  test("dedup: allowedTools includes a built-in tool (Bash, from DB), final args contains it exactly once", async () => {
+    const runClaude = createRunClaude(
+      mockSpawn as typeof Bun.spawn,
+      testSessions,
+      MODEL,
+      WORKSPACE,
+      fakeSentryClient,
+      ["Bash", "mcp__extra__tool"], // Bash is no longer hardcoded; now DB/extraAllowedTools-only
+    );
+
+    await runClaude("test");
+    const [cmd] = mockSpawn.mock.calls[0] as [string[]];
+
+    const toolsInCmd = extractAllowedTools(cmd);
+
+    // Count occurrences of Bash
+    const bashCount = toolsInCmd.filter((tool) => tool === "Bash").length;
+    expect(bashCount).toBe(1);
+    expect(toolsInCmd).toContain("mcp__extra__tool");
+  });
+
+  test("dedup: empty allowedTools still contains exactly the 7 FLOOR_TOOLS with no duplicates", async () => {
+    const runClaudeEmpty = createRunClaude(
+      mockSpawn as typeof Bun.spawn,
+      testSessions,
+      MODEL,
+      WORKSPACE,
+      fakeSentryClient,
+      [], // empty extraAllowedTools
+    );
+
+    await runClaudeEmpty("test");
+    const [cmd] = mockSpawn.mock.calls[0] as [string[]];
+
+    const toolsInCmd = extractAllowedTools(cmd);
+
+    // Verify exactly the 7 FLOOR_TOOLS
+    const floorTools = [
+      "Read",
+      "Write",
+      "Edit",
+      "Glob",
+      "Grep",
+      "TodoWrite",
+      "Skill",
+    ];
+    expect(toolsInCmd).toEqual(floorTools);
+
+    // Verify no duplicates: unique count equals total count
+    const uniqueTools = new Set(toolsInCmd);
+    expect(uniqueTools.size).toBe(toolsInCmd.length);
+  });
+
+  test("dedup: multiple overlapping tools, only unique entries in final args", async () => {
+    const runClaude = createRunClaude(
+      mockSpawn as typeof Bun.spawn,
+      testSessions,
+      MODEL,
+      WORKSPACE,
+      fakeSentryClient,
+      ["Bash", "Write", "mcp__tool1", "Read", "mcp__tool2"], // Write and Read are floor; Bash comes from DB
+    );
+
+    await runClaude("test");
+    const [cmd] = mockSpawn.mock.calls[0] as [string[]];
+
+    const toolsInCmd = extractAllowedTools(cmd);
+
+    // Verify no duplicates
+    const uniqueTools = new Set(toolsInCmd);
+    expect(uniqueTools.size).toBe(toolsInCmd.length);
+
+    // Verify all expected tools are present
+    expect(toolsInCmd).toContain("Bash");
+    expect(toolsInCmd).toContain("Write");
+    expect(toolsInCmd).toContain("Read");
+    expect(toolsInCmd).toContain("mcp__tool1");
+    expect(toolsInCmd).toContain("mcp__tool2");
+  });
+
+  test("empty liveClaudeConfig.allowedTools: Bash/WebSearch/WebFetch/Agent are NOT in final args, only the 7 floor tools are present", async () => {
+    const runClaudeEmpty = createRunClaude(
+      mockSpawn as typeof Bun.spawn,
+      testSessions,
+      MODEL,
+      WORKSPACE,
+      fakeSentryClient,
+      [], // simulates liveClaudeConfig.allowedTools === [] (no AgentTool rows / config bundle 404)
+    );
+
+    await runClaudeEmpty("test");
+    const [cmd] = mockSpawn.mock.calls[0] as [string[]];
+
+    const toolsInCmd = extractAllowedTools(cmd);
+
+    expect(toolsInCmd).not.toContain("Bash");
+    expect(toolsInCmd).not.toContain("WebSearch");
+    expect(toolsInCmd).not.toContain("WebFetch");
+    expect(toolsInCmd).not.toContain("Agent");
+
+    expect(toolsInCmd).toEqual([
+      "Read",
+      "Write",
+      "Edit",
+      "Glob",
+      "Grep",
+      "TodoWrite",
+      "Skill",
+    ]);
+  });
+
+  test("liveClaudeConfig.allowedTools includes Bash and Agent (from DB): final args include them exactly once each alongside the 7 floor tools", async () => {
+    const runClaude = createRunClaude(
+      mockSpawn as typeof Bun.spawn,
+      testSessions,
+      MODEL,
+      WORKSPACE,
+      fakeSentryClient,
+      ["Bash", "Agent"], // simulates liveClaudeConfig.allowedTools seeded from AgentTool DB rows
+    );
+
+    await runClaude("test");
+    const [cmd] = mockSpawn.mock.calls[0] as [string[]];
+
+    const toolsInCmd = extractAllowedTools(cmd);
+
+    const bashCount = toolsInCmd.filter((tool) => tool === "Bash").length;
+    const agentCount = toolsInCmd.filter((tool) => tool === "Agent").length;
+    expect(bashCount).toBe(1);
+    expect(agentCount).toBe(1);
+
+    for (const floorTool of [
+      "Read",
+      "Write",
+      "Edit",
+      "Glob",
+      "Grep",
+      "TodoWrite",
+      "Skill",
+    ]) {
+      expect(toolsInCmd).toContain(floorTool);
+    }
+
+    const uniqueTools = new Set(toolsInCmd);
+    expect(uniqueTools.size).toBe(toolsInCmd.length);
+  });
+});
+
+// ─── totalCostUsd and modelUsage from JSON output ────────────────────────────
+
+describe("runClaude — totalCostUsd and modelUsage", () => {
+  // biome-ignore lint/suspicious/noExplicitAny: mock return type
+  let mockSpawn: any;
+  let runClaude: ReturnType<typeof createRunClaude>;
+
+  beforeEach(() => {
+    mockGetSession.mockClear();
+    mockSetSession.mockClear();
+    mockClearSession.mockClear();
+    capturedMessages = [];
+    capturedExceptions = [];
+    mockSpawn = mock(
+      () =>
+        fakeProc(jsonOutput("Hello from Claude")) as ReturnType<
+          typeof Bun.spawn
+        >,
+    );
+    runClaude = createRunClaude(
+      mockSpawn as typeof Bun.spawn,
+      testSessions,
+      MODEL,
+      WORKSPACE,
+      fakeSentryClient,
+    );
+  });
+
+  test("returns totalCostUsd from JSON output when total_cost_usd is present", async () => {
+    const json = JSON.stringify({
+      type: "result",
+      subtype: "success",
+      result: "Hello",
+      session_id: "sess-cost",
+      is_error: false,
+      total_cost_usd: 0.0042,
+    });
+    mockSpawn.mockReturnValue(fakeProc(json) as ReturnType<typeof Bun.spawn>);
+    const output = await runClaude("hello");
+    expect(output.totalCostUsd).toBe(0.0042);
+  });
+
+  test("returns modelUsage from JSON output when modelUsage is present", async () => {
+    const modelUsage = {
+      "claude-sonnet-4-6": {
+        inputTokens: 10,
+        outputTokens: 5,
+        cacheReadInputTokens: 0,
+        cacheCreationInputTokens: 0,
+        webSearchRequests: 0,
+        costUSD: 0.0021,
+        contextWindow: 200000,
+        maxOutputTokens: 8192,
+      },
+    };
+    const json = JSON.stringify({
+      type: "result",
+      subtype: "success",
+      result: "Hello",
+      session_id: "sess-usage",
+      is_error: false,
+      modelUsage,
+    });
+    mockSpawn.mockReturnValue(fakeProc(json) as ReturnType<typeof Bun.spawn>);
+    const output = await runClaude("hello");
+    expect(output.modelUsage).toEqual(modelUsage);
+  });
+
+  test("returns undefined totalCostUsd and modelUsage when not in JSON output", async () => {
+    // Default mockSpawn produces jsonOutput("Hello from Claude") which has no extra fields
+    const output = await runClaude("hello");
+    expect(output.totalCostUsd).toBeUndefined();
+    expect(output.modelUsage).toBeUndefined();
+  });
+});
+
+// ─── stream-json parsing / onProgress ────────────────────────────────────────
+
+describe("runClaude — stream-json parsing", () => {
+  beforeEach(() => {
+    mockGetSession.mockReset();
+    mockSetSession.mockReset();
+    mockClearSession.mockReset();
+    capturedMessages = [];
+    capturedExceptions = [];
+  });
+
+  test("clean multi-turn, multi-model session returns the result event's authoritative totals byte-identically", async () => {
+    const mockSpawn = mock(
+      () => ndjsonProc(cleanMultiTurn.lines) as ReturnType<typeof Bun.spawn>,
+    );
+    const runClaude = createRunClaude(
+      mockSpawn as typeof Bun.spawn,
+      testSessions,
+      MODEL,
+      WORKSPACE,
+      fakeSentryClient,
+    );
+
+    const output = await runClaude("go");
+
+    expect(output.result).toBe(cleanMultiTurn.expected.result);
+    expect(output.sessionId).toBe(cleanMultiTurn.expected.sessionId);
+    expect(output.totalCostUsd).toBe(cleanMultiTurn.expected.totalCostUsd);
+    // Byte-identical to the terminal result event's modelUsage (NOT the
+    // running accumulator, which lacks costUSD).
+    expect(output.modelUsage).toEqual(cleanMultiTurn.expected.modelUsage);
+    expect(output.streamIncomplete).toBeUndefined();
+  });
+
+  test("onProgress fires once per distinct message id with the running accumulated total (deduped)", async () => {
+    const mockSpawn = mock(
+      () => ndjsonProc(cleanMultiTurn.lines) as ReturnType<typeof Bun.spawn>,
+    );
+    const progress: Array<Record<string, unknown>> = [];
+    const runClaude = createRunClaude(
+      mockSpawn as typeof Bun.spawn,
+      testSessions,
+      MODEL,
+      WORKSPACE,
+      fakeSentryClient,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      (mu, phase) => {
+        // Isolate the usage-triggered fires (phase undefined) from the
+        // separate phase-triggered fires (CFB-2.1) this same callback also
+        // now receives — this test is specifically about usage accumulation.
+        if (phase === undefined) progress.push(structuredClone(mu));
+      },
+    );
+
+    await runClaude("go");
+
+    // msg_1 (deduped from 2 lines), msg_2, msg_3 → exactly 3 progress events.
+    expect(progress).toHaveLength(cleanMultiTurn.expectedProgressCount);
+    // The final accumulated snapshot matches the fixture's own expected sums.
+    expect(progress[progress.length - 1]).toEqual(
+      cleanMultiTurn.expectedAccumulated,
+    );
+  });
+
+  test("per-call onProgress fires once per distinct message id with the running accumulated total (deduped)", async () => {
+    const mockSpawn = mock(
+      () => ndjsonProc(cleanMultiTurn.lines) as ReturnType<typeof Bun.spawn>,
+    );
+    const progress: Array<Record<string, unknown>> = [];
+    // No construction-time onProgress bound — only the per-call one.
+    const runClaude = createRunClaude(
+      mockSpawn as typeof Bun.spawn,
+      testSessions,
+      MODEL,
+      WORKSPACE,
+      fakeSentryClient,
+    );
+
+    await runClaude("go", undefined, (mu, phase) => {
+      if (phase === undefined) progress.push(structuredClone(mu));
+    });
+
+    expect(progress).toHaveLength(cleanMultiTurn.expectedProgressCount);
+    expect(progress[progress.length - 1]).toEqual(
+      cleanMultiTurn.expectedAccumulated,
+    );
+  });
+
+  test("both a construction-time onProgress and a per-call onProgress fire together on the same turn with an identical snapshot", async () => {
+    const mockSpawn = mock(
+      () => ndjsonProc(cleanMultiTurn.lines) as ReturnType<typeof Bun.spawn>,
+    );
+    const constructionProgress: Array<Record<string, unknown>> = [];
+    const perCallProgress: Array<Record<string, unknown>> = [];
+    const runClaude = createRunClaude(
+      mockSpawn as typeof Bun.spawn,
+      testSessions,
+      MODEL,
+      WORKSPACE,
+      fakeSentryClient,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      (mu, phase) => {
+        if (phase === undefined) constructionProgress.push(structuredClone(mu));
+      },
+    );
+
+    await runClaude("go", undefined, (mu, phase) => {
+      if (phase === undefined) perCallProgress.push(structuredClone(mu));
+    });
+
+    expect(constructionProgress).toHaveLength(
+      cleanMultiTurn.expectedProgressCount,
+    );
+    expect(perCallProgress).toHaveLength(cleanMultiTurn.expectedProgressCount);
+    // Identical snapshots on every turn.
+    expect(perCallProgress).toEqual(constructionProgress);
+  });
+
+  test("skips malformed / non-JSON lines without losing already-accumulated usage", async () => {
+    const linesWithGarbage = [
+      cleanMultiTurn.lines[0],
+      "this is not json at all",
+      ...cleanMultiTurn.lines.slice(1, 2),
+      "{ broken json",
+      ...cleanMultiTurn.lines.slice(2),
+    ];
+    const mockSpawn = mock(
+      () => ndjsonProc(linesWithGarbage) as ReturnType<typeof Bun.spawn>,
+    );
+    const runClaude = createRunClaude(
+      mockSpawn as typeof Bun.spawn,
+      testSessions,
+      MODEL,
+      WORKSPACE,
+      fakeSentryClient,
+    );
+
+    const output = await runClaude("go");
+    expect(output.result).toBe(cleanMultiTurn.expected.result);
+    expect(output.modelUsage).toEqual(cleanMultiTurn.expected.modelUsage);
+  });
+
+  test("truncated stream with no result event surfaces the accumulated partial usage (distinct return shape)", async () => {
+    const mockSpawn = mock(
+      () => ndjsonProc(truncatedNoResult.lines) as ReturnType<typeof Bun.spawn>,
+    );
+    const runClaude = createRunClaude(
+      mockSpawn as typeof Bun.spawn,
+      testSessions,
+      MODEL,
+      WORKSPACE,
+      fakeSentryClient,
+    );
+
+    const output = await runClaude("go");
+    expect(output.streamIncomplete).toBe(true);
+    expect(output.modelUsage).toEqual(truncatedNoResult.expectedAccumulated);
+    expect(output.result).toBe("");
+  });
+
+  test("clean exit with no result event still surfaces the session id captured off the leading system/init line", async () => {
+    const mockSpawn = mock(
+      () => ndjsonProc(cleanExitNoResult.lines) as ReturnType<typeof Bun.spawn>,
+    );
+    const runClaude = createRunClaude(
+      mockSpawn as typeof Bun.spawn,
+      testSessions,
+      MODEL,
+      WORKSPACE,
+      fakeSentryClient,
+    );
+
+    const output = await runClaude("go");
+    expect(output.streamIncomplete).toBe(true);
+    expect(output.sessionId).toBe(cleanExitNoResult.expectedSessionId);
+    expect(output.modelUsage).toEqual(cleanExitNoResult.expectedAccumulated);
+  });
+
+  test("truncated non-zero exit with no result event falls back to the init line's session id on ClaudeRunError", async () => {
+    const mockSpawn = mock(
+      () =>
+        ndjsonProc(truncatedNoResult.lines, "", 1) as ReturnType<
+          typeof Bun.spawn
+        >,
+    );
+    const runClaude = createRunClaude(
+      mockSpawn as typeof Bun.spawn,
+      testSessions,
+      MODEL,
+      WORKSPACE,
+      fakeSentryClient,
+    );
+
+    const { ClaudeRunError } = await import("./claude.ts");
+    try {
+      await runClaude("go");
+      throw new Error("expected throw");
+    } catch (err) {
+      expect(err).toBeInstanceOf(ClaudeRunError);
+      const e = err as InstanceType<typeof ClaudeRunError>;
+      // No `result` event ever arrived — session id must fall back to the
+      // one captured off the leading system/init line, not result?.session_id.
+      expect(e.sessionId).toBe(truncatedNoResult.expectedSessionId);
+      expect(e.modelUsage).toEqual(truncatedNoResult.expectedAccumulated);
+    }
+  });
+
+  test("timeout mid-stream throws ClaudeTimeoutError carrying the accumulated partial usage", async () => {
+    // A proc whose stdout emits two assistant turns then never closes / never
+    // emits a result — forcing the timeout path.
+    let resolveExited!: (code: number) => void;
+    const exited = new Promise<number>((r) => {
+      resolveExited = r;
+    });
+    const enc = new TextEncoder();
+    // Mirror real proc.kill() semantics: killing the process closes stdout so
+    // the reader drains to `done` instead of hanging forever.
+    let streamController!: ReadableStreamDefaultController<Uint8Array>;
+    const stdout = new ReadableStream<Uint8Array>({
+      start(controller) {
+        streamController = controller;
+        controller.enqueue(enc.encode(`${truncatedNoResult.lines[0]}\n`));
+        controller.enqueue(enc.encode(`${truncatedNoResult.lines[1]}\n`));
+        controller.enqueue(enc.encode(`${truncatedNoResult.lines[2]}\n`));
+        // stream intentionally left open — no close(), no result line
+      },
+    });
+    const proc = {
+      stdout,
+      stderr: bodyStream(""),
+      exited,
+      kill: () => {
+        streamController.close();
+        resolveExited(143);
+      },
+    };
+    const mockSpawn = mock(
+      () => proc as unknown as ReturnType<typeof Bun.spawn>,
+    );
+
+    const runClaudeWithTimeout = createRunClaude(
+      mockSpawn as typeof Bun.spawn,
+      testSessions,
+      MODEL,
+      WORKSPACE,
+      fakeSentryClient,
+      undefined,
+      undefined,
+      undefined,
+      1000, // 1s ceiling headroom — idle timer below should fire first
+      10, // 10ms idle timeout — stream goes silent after the 3 initial lines
+    );
+
+    const { ClaudeTimeoutError } = await import("./claude.ts");
+    try {
+      await runClaudeWithTimeout("go");
+      throw new Error("expected timeout");
+    } catch (err) {
+      expect(err).toBeInstanceOf(ClaudeTimeoutError);
+      const e = err as InstanceType<typeof ClaudeTimeoutError>;
+      expect(e.reason).toBe("idle");
+      expect(e.partialModelUsage).toEqual(
+        truncatedNoResult.expectedAccumulated,
+      );
+      // The init line (first of the 3 emitted lines) carries a session id —
+      // it must survive onto the timeout error even though the process was
+      // killed before any terminal `result` event arrived.
+      expect(e.sessionId).toBe(truncatedNoResult.expectedSessionId);
+    }
+  });
+});
+
+// ─── progress phases ──────────────────────────────────────────────────────────
+
+describe("runClaude — progress phases derived from message.content", () => {
+  test("fires the expected collapsed phase sequence, in order, via onProgress", async () => {
+    const mockSpawn = mock(
+      () => ndjsonProc(progressPhases.lines) as ReturnType<typeof Bun.spawn>,
+    );
+    const phases: Array<string | undefined> = [];
+    const runClaude = createRunClaude(
+      mockSpawn as typeof Bun.spawn,
+      testSessions,
+      MODEL,
+      WORKSPACE,
+      fakeSentryClient,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      (_mu, phase) => {
+        if (phase !== undefined) phases.push(phase);
+      },
+    );
+
+    await runClaude("go");
+
+    expect(phases).toEqual(progressPhases.expectedPhaseSequence);
+  });
+
+  test("fires the same collapsed phase sequence via the per-call onProgress", async () => {
+    const mockSpawn = mock(
+      () => ndjsonProc(progressPhases.lines) as ReturnType<typeof Bun.spawn>,
+    );
+    const phases: Array<string | undefined> = [];
+    const runClaude = createRunClaude(
+      mockSpawn as typeof Bun.spawn,
+      testSessions,
+      MODEL,
+      WORKSPACE,
+      fakeSentryClient,
+    );
+
+    await runClaude("go", undefined, (_mu, phase) => {
+      if (phase !== undefined) phases.push(phase);
+    });
+
+    expect(phases).toEqual(progressPhases.expectedPhaseSequence);
+  });
+
+  test("fires a phase for a tool_use-only line with no usage field (before the usage guard)", async () => {
+    // msg_1 in the fixture carries a thinking block + a tool_use block and NO
+    // top-level `usage` field — the existing `if (!message?.id || !message.usage)
+    // return;` guard must not suppress the phase fire for this line.
+    const mockSpawn = mock(
+      () => ndjsonProc(progressPhases.lines) as ReturnType<typeof Bun.spawn>,
+    );
+    const phases: Array<string | undefined> = [];
+    const runClaude = createRunClaude(
+      mockSpawn as typeof Bun.spawn,
+      testSessions,
+      MODEL,
+      WORKSPACE,
+      fakeSentryClient,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      (_mu, phase) => {
+        if (phase !== undefined) phases.push(phase);
+      },
+    );
+
+    await runClaude("go");
+
+    // "thinking" and "reading" both come from msg_1, the usage-less line.
+    expect(phases[0]).toBe("thinking");
+    expect(phases[1]).toBe("reading");
+  });
+
+  test("never surfaces secret/path substrings embedded in tool_use.input anywhere in fired phases", async () => {
+    const mockSpawn = mock(
+      () => ndjsonProc(progressPhases.lines) as ReturnType<typeof Bun.spawn>,
+    );
+    const phases: Array<string | undefined> = [];
+    const runClaude = createRunClaude(
+      mockSpawn as typeof Bun.spawn,
+      testSessions,
+      MODEL,
+      WORKSPACE,
+      fakeSentryClient,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      (_mu, phase) => {
+        phases.push(phase);
+      },
+    );
+
+    await runClaude("go");
+
+    const serialized = JSON.stringify(phases);
+    for (const secret of progressPhases.forbiddenSubstrings) {
+      expect(serialized).not.toContain(secret);
+    }
+  });
+
+  test("passes the accumulated usage snapshot alongside the phase even when only the phase changed", async () => {
+    const mockSpawn = mock(
+      () => ndjsonProc(progressPhases.lines) as ReturnType<typeof Bun.spawn>,
+    );
+    const calls: Array<[Record<string, unknown>, string | undefined]> = [];
+    const runClaude = createRunClaude(
+      mockSpawn as typeof Bun.spawn,
+      testSessions,
+      MODEL,
+      WORKSPACE,
+      fakeSentryClient,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      (mu, phase) => {
+        calls.push([structuredClone(mu), phase]);
+      },
+    );
+
+    await runClaude("go");
+
+    // The very first call (msg_1's thinking block, no usage field yet) must
+    // still receive a (possibly empty) modelUsage snapshot object alongside
+    // the phase — never undefined/omitted.
+    expect(calls[0][0]).toEqual({});
+    expect(calls[0][1]).toBe("thinking");
+  });
+});
+
+// ─── dominantModel ────────────────────────────────────────────────────────────
+
+describe("dominantModel", () => {
+  test("returns the model with the highest outputTokens", () => {
+    const result = dominantModel({
+      "claude-sonnet-4-6": {
+        inputTokens: 100,
+        outputTokens: 50,
+        cacheReadInputTokens: 0,
+        cacheCreationInputTokens: 0,
+        costUSD: 0.001,
+      },
+      "claude-opus-4-8": {
+        inputTokens: 200,
+        outputTokens: 200,
+        cacheReadInputTokens: 0,
+        cacheCreationInputTokens: 0,
+        costUSD: 0.01,
+      },
+    });
+    expect(result).toBe("claude-opus-4-8");
+  });
+
+  test("returns undefined for empty modelUsage", () => {
+    expect(dominantModel({})).toBeUndefined();
+  });
+
+  test("handles single model", () => {
+    const result = dominantModel({
+      "claude-haiku-4-6": {
+        inputTokens: 10,
+        outputTokens: 5,
+        cacheReadInputTokens: 0,
+        cacheCreationInputTokens: 0,
+        costUSD: 0.0001,
+      },
+    });
+    expect(result).toBe("claude-haiku-4-6");
+  });
+
+  test("breaks ties deterministically — returns one of the tied models", () => {
+    const result = dominantModel({
+      "model-a": {
+        inputTokens: 10,
+        outputTokens: 100,
+        cacheReadInputTokens: 0,
+        cacheCreationInputTokens: 0,
+        costUSD: 0.001,
+      },
+      "model-b": {
+        inputTokens: 10,
+        outputTokens: 100,
+        cacheReadInputTokens: 0,
+        cacheCreationInputTokens: 0,
+        costUSD: 0.001,
+      },
+    });
+    expect(result === "model-a" || result === "model-b").toBe(true);
+  });
+});
+
+// ─── liveClaudeConfig / setLiveClaudeConfig tests ────────────────────────────
+
+describe("liveClaudeConfig", () => {
+  // biome-ignore lint/suspicious/noExplicitAny: mock return type
+  let mockSpawn: any;
+
+  beforeEach(() => {
+    mockGetSession.mockClear();
+    mockSetSession.mockClear();
+    mockClearSession.mockClear();
+    capturedMessages = [];
+    capturedExceptions = [];
+    mockSpawn = mock(
+      () =>
+        fakeProc(jsonOutput("Hello from Claude")) as ReturnType<
+          typeof Bun.spawn
+        >,
+    );
+  });
+
+  test("setLiveClaudeConfig changes --model for module-level runClaude", async () => {
+    setLiveClaudeConfig({ model: "claude-haiku-4-6" });
+
+    // createRunClaude() with no explicit model should pick up liveClaudeConfig
+    const runClaudeDefault = createRunClaude(
+      mockSpawn as typeof Bun.spawn,
+      testSessions,
+      undefined,
+      WORKSPACE,
+      fakeSentryClient,
+    );
+
+    await runClaudeDefault("test");
+    const [cmd] = mockSpawn.mock.calls[0] as [string[]];
+    const idx = cmd.indexOf("--model");
+    expect(idx).toBeGreaterThan(-1);
+    expect(cmd[idx + 1]).toBe("claude-haiku-4-6");
+  });
+
+  test("explicit model passed to createRunClaude overrides liveClaudeConfig", async () => {
+    setLiveClaudeConfig({ model: "claude-haiku-4-6" });
+
+    // Explicit model param takes precedence
+    const runClaudeExplicit = createRunClaude(
+      mockSpawn as typeof Bun.spawn,
+      testSessions,
+      "claude-opus-4-6",
+      WORKSPACE,
+      fakeSentryClient,
+    );
+
+    await runClaudeExplicit("test");
+    const [cmd] = mockSpawn.mock.calls[0] as [string[]];
+    const idx = cmd.indexOf("--model");
+    expect(idx).toBeGreaterThan(-1);
+    expect(cmd[idx + 1]).toBe("claude-opus-4-6");
+  });
+
+  test("setLiveClaudeConfig merges partial patches", async () => {
+    setLiveClaudeConfig({ model: "claude-sonnet-4-6", effortLevel: "xhigh" });
+
+    const runClaudeDefault = createRunClaude(
+      mockSpawn as typeof Bun.spawn,
+      testSessions,
+      undefined,
+      WORKSPACE,
+      fakeSentryClient,
+    );
+
+    await runClaudeDefault("test");
+    const [cmd] = mockSpawn.mock.calls[0] as [string[]];
+
+    const modelIdx = cmd.indexOf("--model");
+    expect(cmd[modelIdx + 1]).toBe("claude-sonnet-4-6");
+
+    const effortIdx = cmd.indexOf("--effort");
+    expect(effortIdx).toBeGreaterThan(-1);
+    expect(cmd[effortIdx + 1]).toBe("xhigh");
+  });
+});
+
+// ─── reportClaudeError ──────────────────────────────────────────────────────
+//
+// SENTRY-46: a ClaudeTimeoutError with reason:"ceiling" is the intentional
+// 1hr hard-ceiling backstop firing on a legitimately long-running session —
+// expected, not a defect — so it must be downgraded to captureMessage rather
+// than captureException (which creates an actionable Sentry Issue that keeps
+// re-triggering error-patrol as "regressed"). reason:"idle" (a genuine hang)
+// and any other error must remain unchanged (captureException).
+
+describe("reportClaudeError", () => {
+  beforeEach(() => {
+    capturedMessages = [];
+    capturedExceptions = [];
+  });
+
+  test("a ceiling-reason ClaudeTimeoutError calls captureMessage, not captureException", () => {
+    const err = new ClaudeTimeoutError(3_600_000, "ceiling");
+
+    reportClaudeError(fakeSentryClient, err);
+
+    expect(capturedExceptions).toHaveLength(0);
+    expect(capturedMessages).toHaveLength(1);
+    expect(capturedMessages[0]).toContain("3600s");
+  });
+
+  test("an idle-reason ClaudeTimeoutError calls captureException, not captureMessage", () => {
+    const err = new ClaudeTimeoutError(1_500_000, "idle");
+
+    reportClaudeError(fakeSentryClient, err);
+
+    expect(capturedMessages).toHaveLength(0);
+    expect(capturedExceptions).toHaveLength(1);
+    expect(capturedExceptions[0]).toBe(err);
+  });
+
+  test("a non-ClaudeTimeoutError calls captureException, not captureMessage", () => {
+    const err = new Error("some other failure");
+
+    reportClaudeError(fakeSentryClient, err);
+
+    expect(capturedMessages).toHaveLength(0);
+    expect(capturedExceptions).toHaveLength(1);
+    expect(capturedExceptions[0]).toBe(err);
+  });
+
+  test("does not throw when sentryClient is undefined", () => {
+    expect(() =>
+      reportClaudeError(
+        undefined,
+        new ClaudeTimeoutError(3_600_000, "ceiling"),
+      ),
+    ).not.toThrow();
+    expect(() => reportClaudeError(undefined, new Error("boom"))).not.toThrow();
+  });
+});
+
+// ─── run telemetry (first-turn baseline, counts, skill attribution) ──────────
+
+describe("runClaude — run telemetry", () => {
+  beforeEach(() => {
+    mockGetSession.mockReset();
+    mockSetSession.mockReset();
+    mockClearSession.mockReset();
+  });
+
+  test("a clean session returns the fixture's expected telemetry alongside the result", async () => {
+    const mockSpawn = mock(
+      () => ndjsonProc(skillAttribution.lines) as ReturnType<typeof Bun.spawn>,
+    );
+    const runClaude = createRunClaude(
+      mockSpawn as typeof Bun.spawn,
+      testSessions,
+      MODEL,
+      WORKSPACE,
+      fakeSentryClient,
+    );
+
+    const output = await runClaude("go");
+
+    expect(output.result).toBe("done");
+    expect(output.telemetry).toEqual(skillAttribution.expectedTelemetry);
+  });
+
+  test("a resumed session (-r) drops the first-turn baseline but keeps counts and attribution", async () => {
+    mockGetSession.mockImplementation(() => "sess-prior");
+    const mockSpawn = mock(
+      () => ndjsonProc(skillAttribution.lines) as ReturnType<typeof Bun.spawn>,
+    );
+    const runClaude = createRunClaude(
+      mockSpawn as typeof Bun.spawn,
+      testSessions,
+      MODEL,
+      WORKSPACE,
+      fakeSentryClient,
+    );
+
+    const output = await runClaude("go", "thread-1");
+
+    const cmd = (mockSpawn.mock.calls[0] as unknown[])[0] as string[];
+    expect(cmd).toContain("-r");
+    expect(output.telemetry?.firstTurn).toBeUndefined();
+    expect(output.telemetry?.turns).toBe(
+      skillAttribution.expectedTelemetry.turns,
+    );
+    expect(output.telemetry?.skillUsage).toEqual(
+      skillAttribution.expectedTelemetry.skillUsage,
+    );
+  });
+
+  test("a clean exit with no result event still carries telemetry on the streamIncomplete shape", async () => {
+    const mockSpawn = mock(
+      () => ndjsonProc(cleanExitNoResult.lines) as ReturnType<typeof Bun.spawn>,
+    );
+    const runClaude = createRunClaude(
+      mockSpawn as typeof Bun.spawn,
+      testSessions,
+      MODEL,
+      WORKSPACE,
+      fakeSentryClient,
+    );
+
+    const output = await runClaude("go");
+
+    expect(output.streamIncomplete).toBe(true);
+    expect(output.telemetry?.turns).toBeGreaterThan(0);
+    expect(output.telemetry?.firstTurn).toBeDefined();
+  });
+
+  test("a non-zero exit after usage was seen attaches partialTelemetry to the ClaudeRunError", async () => {
+    const mockSpawn = mock(
+      () =>
+        ndjsonProc(truncatedNoResult.lines, "boom", 1) as ReturnType<
+          typeof Bun.spawn
+        >,
+    );
+    const runClaude = createRunClaude(
+      mockSpawn as typeof Bun.spawn,
+      testSessions,
+      MODEL,
+      WORKSPACE,
+      fakeSentryClient,
+    );
+
+    let caught: unknown;
+    try {
+      await runClaude("go");
+    } catch (err) {
+      caught = err;
+    }
+    expect(caught).toBeInstanceOf(ClaudeRunError);
+    const telemetry = (caught as InstanceType<typeof ClaudeRunError>)
+      .partialTelemetry;
+    expect(telemetry?.turns).toBeGreaterThan(0);
+    expect(telemetry?.firstTurn).toBeDefined();
+  });
+});