catherd-cli 0.2.1 → 1.0.0

package/src/adapters/backend.ts

@@ -0,0 +1,144 @@
+import type { ErrorCode } from "../domain/errors.ts";
+import type { ADAPTER_IDS, Rung } from "../domain/ids.ts";
+import type { BillingMode } from "../domain/cost.ts";
+import type { Access, ExitInfo, RunStatus, Tokens } from "../domain/record.ts";
+
+type AdapterId = (typeof ADAPTER_IDS)[number];
+
+export interface Probe {
+  installed: boolean;
+  version: string | null;
+  versionOk: boolean;
+  /** null when the CLI offers no way to ask */
+  loggedIn: boolean | null;
+  /** how the CLI is logged in, in a word or two ("ChatGPT", "API key"), when it says */
+  login?: string;
+  /** the billing mode that login implies, when it implies one: doctor compares it with the profiles' */
+  billing?: BillingMode;
+  problems: { code: ErrorCode; message: string; fix: string }[];
+}
+
+export interface DiscoveredModel {
+  id: string;
+  efforts: string[];
+  context: number | null;
+  imageIn: boolean;
+}
+
+export interface RunRequest {
+  rung: Rung;
+  access: Access;
+  thread: string | null;
+  isolated: boolean;
+  repo: string;
+  briefPath: string;
+  replyPath: string;
+  dispatchDir: string;
+}
+
+/**
+ * `env` holds only the adapter's overrides, never PWD. Admission writes them to spec.json with PWD added
+ * and nothing else, so no credential reaches disk; the `_supervise` process builds the worker's env at
+ * spawn time with `workerEnv(process.env, spec.env, spec.cwd)`, the only place secrets are scrubbed.
+ */
+export interface SpawnPlan {
+  cmd: string;
+  args: string[];
+  env: Record<string, string>;
+  cwd: string;
+  stdinPath: string | null;
+}
+
+export interface EventDelta {
+  thread?: string;
+  tokens?: Tokens;
+  /** the input tokens of one model request, from an event that reports them per request (the harness cost) */
+  requestInput?: number;
+  costUsd?: number;
+  lastEvent?: string;
+  failure?: string;
+  limit?: boolean;
+  tooOld?: boolean;
+  retrying?: boolean;
+  /** the stream's terminal event: the supervisor may kill a CLI that lingers after it */
+  final?: boolean;
+  /** a tool call starting (`open`) or ending: while one is open the run is busy, however quiet */
+  item?: { id: string; open: boolean };
+}
+
+export interface FinishedRun {
+  request: RunRequest;
+  eventLines: string[];
+  reply: string;
+  stderr: string;
+  exit: ExitInfo;
+  startedAtMs: number;
+}
+
+export interface Outcome {
+  status: RunStatus;
+  thread: string | null;
+  tokens: Tokens;
+  costUsd: number | null;
+  images: string[];
+  error: { code: string; message: string } | null;
+  /** The role's reply, for a CLI that streams it rather than writing the reply file (absent: the file is the reply). */
+  reply?: string;
+}
+
+/** What earlier records on the same thread already counted, so a session total becomes this run's share. */
+export interface Spent {
+  tokens: Tokens;
+  costUsd: number;
+}
+
+export interface BackendAdapter {
+  id: AdapterId;
+  minVersion: string;
+  probe(): Promise<Probe>;
+  /** The models the backend offers; in `repo` when given, for a backend whose listing depends on it. */
+  listModels(repo?: string): Promise<DiscoveredModel[]>;
+  /**
+   * Refuses a rung this backend cannot run and readies the backend's own config, before admission writes
+   * anything (spec §6.3: variants are validated before dispatch). Throws a CatherdError.
+   */
+  prepare?(req: { rung: Rung; access: Access; isolated: boolean; repo: string }): Promise<void>;
+  plan(req: RunRequest): SpawnPlan;
+  parse(line: string): EventDelta;
+  finalize(run: FinishedRun): Outcome;
+  /**
+   * Spec §6.3: the backend's own account of a finished session, for a stream that undercounts. Returns
+   * `o` refined; never throws (the caller also cuts it off after a timeout and keeps `o`).
+   */
+  settle?(o: Outcome, run: FinishedRun, prior: Spent): Promise<Outcome>;
+  enforcement: Record<Access, "enforced" | "advisory">;
+  errors: { limit: RegExp[]; tooOld: RegExp[] };
+  resume: { supported: boolean; sameAccessOnly: boolean; threadPattern: RegExp };
+  interrupt?(thread: string, cwd: string): Promise<void>;
+  /** `sinceMs`: when this run started, so what an earlier run on the thread left behind does not count */
+  isBusy?(thread: string, cwd: string, sinceMs?: number): Promise<boolean>;
+  /** Spec §4.5: this backend's own stand-in for a rung on a usage limit, when the profile names none. */
+  failoverFor?(rung: Rung, repo?: string): Rung | null;
+  /**
+   * Spec §10.3: whether a workspace-write worker of this backend can write `dir` (the heavy-lock dir, so
+   * `catherd lock` works inside it); null when it cannot be tested on this machine.
+   */
+  canWrite?(dir: string): Promise<{ ok: boolean; fix?: string } | null>;
+  /** Spec §10.3: why this backend's isolation is weak; doctor warns when a profile uses it. */
+  isolationNote?: string;
+  graceAfterFinalMs: number | null;
+}
+
+export function extractVersion(s: string): string | null {
+  return /(\d+)\.(\d+)\.(\d+)/.exec(s)?.[0] ?? null;
+}
+
+export function compareVersions(a: string, b: string): number {
+  const pa = a.split(".").map(Number);
+  const pb = b.split(".").map(Number);
+  for (let i = 0; i < 3; i++) {
+    const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+    if (d !== 0) return d;
+  }
+  return 0;
+}

package/src/adapters/claude-code/events.ts

@@ -0,0 +1,86 @@
+import { type Tokens, ZERO_TOKENS } from "../../domain/record.ts";
+
+interface ClaudeResult {
+  isError: boolean;
+  text: string;
+  apiStatus: number | null;
+  tokens: Tokens;
+  costUsd: number | null;
+}
+
+export interface ClaudeFold {
+  thread: string | null;
+  result: ClaudeResult | null;
+  limit: boolean;
+  lastEvent: string | null;
+}
+
+/** A usage or rate limit, in the result text Claude Code prints. */
+export const CLAUDE_LIMIT = [/usage limit/i, /hit your (?:usage )?limit/i, /rate[ _-]?limit/i];
+/** What an older `claude` prints for a flag catherd passes (commander's messages). */
+export const CLAUDE_TOO_OLD = [
+  /unknown option '--/i,
+  /option '--[\w-]+ <[\w.]+>' argument '[^']*' is invalid/i,
+];
+
+type Event = Record<string, any>;
+
+export function parseClaudeLine(line: string): Event | null {
+  if (!line.trim().startsWith("{")) return null;
+  try {
+    const e = JSON.parse(line) as unknown;
+    return e && typeof e === "object" && !Array.isArray(e) ? (e as Event) : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Spec §4.3's convention: input counts cached and freshly cached tokens too. */
+export function claudeTokens(u: Event | undefined): Tokens {
+  if (!u) return { ...ZERO_TOKENS };
+  const n = (k: string) => (typeof u[k] === "number" ? (u[k] as number) : 0);
+  const cached = n("cache_read_input_tokens");
+  return {
+    input: n("input_tokens") + n("cache_creation_input_tokens") + cached,
+    cached,
+    output: n("output_tokens"),
+  };
+}
+
+export function eventName(e: Event): string {
+  if (e.type === "system") return e.subtype === "api_retry" ? "retrying" : `system/${e.subtype ?? "?"}`;
+  if (e.type === "assistant") {
+    const c = (e.message?.content ?? []).at(-1) as Event | undefined;
+    return c?.type === "tool_use" ? `tool_use/${c.name}` : `assistant/${c?.type ?? "?"}`;
+  }
+  if (e.type === "user") return "tool_result";
+  return String(e.type ?? "?");
+}
+
+const limited = (e: Event): boolean =>
+  (e.type === "rate_limit_event" && e.rate_limit_info?.status === "rejected") ||
+  (e.type === "assistant" && e.error === "rate_limit") ||
+  (e.type === "result" &&
+    e.is_error === true &&
+    (e.api_error_status === 429 || CLAUDE_LIMIT.some((r) => r.test(String(e.result ?? "")))));
+
+/** Tokens and cost come from the final `result` event only: assistant events repeat one message's usage. */
+export function foldClaudeEvents(lines: string[]): ClaudeFold {
+  const f: ClaudeFold = { thread: null, result: null, limit: false, lastEvent: null };
+  for (const line of lines) {
+    const e = parseClaudeLine(line);
+    if (!e) continue;
+    f.lastEvent = eventName(e);
+    if (typeof e.session_id === "string" && e.session_id) f.thread ??= e.session_id;
+    if (limited(e)) f.limit = true;
+    if (e.type === "result")
+      f.result = {
+        isError: e.is_error === true,
+        text: typeof e.result === "string" ? e.result : "",
+        apiStatus: typeof e.api_error_status === "number" ? e.api_error_status : null,
+        tokens: claudeTokens(e.usage),
+        costUsd: typeof e.total_cost_usd === "number" ? e.total_cost_usd : null,
+      };
+  }
+  return f;
+}

package/src/adapters/claude-code/index.ts

@@ -0,0 +1,223 @@
+import { CatherdError } from "../../domain/errors.ts";
+import type { Rung } from "../../domain/ids.ts";
+import type { Access, RunStatus } from "../../domain/record.ts";
+import {
+  type BackendAdapter,
+  compareVersions,
+  type EventDelta,
+  extractVersion,
+  type FinishedRun,
+  type Outcome,
+  type Probe,
+  type RunRequest,
+  type SpawnPlan,
+} from "../backend.ts";
+import { jsonOf, runCli } from "../cli.ts";
+import {
+  CLAUDE_LIMIT,
+  CLAUDE_TOO_OLD,
+  claudeTokens,
+  eventName,
+  foldClaudeEvents,
+  parseClaudeLine,
+} from "./events.ts";
+import { CLAUDE_ALIASES, CLAUDE_EFFORTS, CLAUDE_MODELS } from "./models.ts";
+import { listClaudeModels } from "./models-api.ts";
+
+/** The version whose flags catherd was verified against (`claude --help`, 2026-09-25). */
+const CLAUDE_MIN_VERSION = "2.1.282";
+const THREAD = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/** How long a `claude` query (version, login) may take before it counts as failed. */
+export const claudeShell = { timeoutMs: 15_000 };
+
+const READ_TOOLS = ["Read", "Glob", "Grep", "WebFetch", "WebSearch"];
+const NEVER = ["git commit", "git push", "git reset --hard"].map((c) => `Bash(${c} *)`);
+
+/**
+ * Spec §6.2 access → Claude Code permission flags (advisory: Bash can still write where it likes).
+ * `dontAsk` denies anything not allowed; `--permission-prompts none` (always passed) denies any prompt.
+ * Read-only gets no Bash at all, as catherd-ro on opencode: `rg --pre=<cmd>` executes and
+ * `git diff --output=<file>` writes, so no Bash pattern is read-only. It reads with Read, Glob and Grep.
+ */
+export const CLAUDE_ACCESS: Record<Access, string[]> = {
+  "read-only": [
+    "--permission-mode",
+    "dontAsk",
+    "--allowedTools",
+    READ_TOOLS.join(","),
+    "--disallowedTools",
+    "Edit,Write,NotebookEdit,Bash",
+  ],
+  "workspace-write": [
+    "--permission-mode",
+    "acceptEdits",
+    "--allowedTools",
+    [...READ_TOOLS, "Edit", "Write", "NotebookEdit", "Bash"].join(","),
+    "--disallowedTools",
+    NEVER.join(","),
+  ],
+  full: ["--permission-mode", "bypassPermissions"],
+};
+
+function plan(r: RunRequest): SpawnPlan {
+  if (r.thread !== null && !THREAD.test(r.thread))
+    throw new CatherdError("E_ADMIT_THREAD", `"${r.thread}" is not a Claude Code session id`, {
+      fix: "pass the thread from the earlier RunRecord",
+    });
+  return {
+    cmd: "claude",
+    args: [
+      "-p",
+      "--output-format",
+      "stream-json",
+      "--verbose",
+      "--model",
+      r.rung.model,
+      // "default" leaves the effort to Claude Code (spec §5.1); Haiku has none
+      ...(r.rung.effort === "default" ? [] : ["--effort", r.rung.effort]),
+      // a fresh session gets its id from catherd, so the thread is known before the first event
+      ...(r.thread === null ? ["--session-id", crypto.randomUUID()] : ["--resume", r.thread]),
+      "--permission-prompts",
+      "none",
+      ...CLAUDE_ACCESS[r.access],
+      // --bare would also drop OAuth, so a Claude plan could not log in; --safe-mode keeps auth
+      ...(r.isolated ? ["--safe-mode"] : []),
+    ],
+    env: {},
+    cwd: r.repo,
+    stdinPath: r.briefPath,
+  };
+}
+
+/** Spec §6.2: full model ids only, and an effort the model has. */
+async function prepare(req: { rung: Rung; access: Access; isolated: boolean }): Promise<void> {
+  const { model, effort } = req.rung;
+  const full = CLAUDE_ALIASES[model];
+  if (full || !model.startsWith("claude-"))
+    throw new CatherdError("E_BACKEND_MODEL_UNKNOWN", `"${model}" is not a full Claude model id`, {
+      fix: `use the full id${full ? `, ${full}` : ", e.g. claude-opus-5-5"}`,
+    });
+  const known = CLAUDE_MODELS.find((m) => m.id === model);
+  const efforts = known ? known.efforts : CLAUDE_EFFORTS;
+  if (effort !== "default" && !efforts.includes(effort))
+    throw new CatherdError("E_BACKEND_MODEL_UNKNOWN", `${model} has no effort "${effort}"`, {
+      fix: efforts.length ? `use one of: default, ${efforts.join(", ")}` : `use ${model}#default`,
+    });
+  if (req.access === "full" && process.getuid?.() === 0 && !process.env.IS_SANDBOX)
+    throw new CatherdError(
+      "E_ADMIT_RUNG",
+      "claude refuses full access (bypassPermissions) when run as root",
+      {
+        fix: "run catherd as a normal user, or give this role workspace-write access",
+      },
+    );
+}
+
+function finalize(run: FinishedRun): Outcome {
+  const f = foldClaudeEvents(run.eventLines);
+  const res = f.result;
+  const stopped = run.exit.reason;
+  const failed = res === null || res.isError;
+  const status: RunStatus =
+    stopped === "cancelled"
+      ? "cancelled"
+      : stopped === "idle-timeout" || stopped === "wall-timeout"
+        ? "timeout"
+        : !failed
+          ? "ok"
+          : res === null && CLAUDE_TOO_OLD.some((r) => r.test(run.stderr))
+            ? "cli-too-old"
+            : f.limit
+              ? "limit"
+              : "failed";
+  const lastErr = run.stderr.trim().split("\n").at(-1) ?? "";
+  const message =
+    res?.isError && res.text
+      ? res.text
+      : lastErr || (res ? "" : `no result event (${stopped}, exit ${run.exit.code ?? run.exit.signal})`);
+  return {
+    status,
+    thread: f.thread ?? run.request.thread,
+    tokens: res?.tokens ?? claudeTokens(undefined),
+    costUsd: res?.costUsd ?? null,
+    images: [],
+    error: status === "ok" ? null : { code: status, message: message || status },
+    ...(res && !res.isError ? { reply: res.text } : {}),
+  };
+}
+
+function parse(line: string): EventDelta {
+  const e = parseClaudeLine(line);
+  if (!e) return {};
+  const d: EventDelta = { lastEvent: eventName(e) };
+  if (typeof e.session_id === "string" && e.session_id) d.thread = e.session_id;
+  if (e.type === "system" && e.subtype === "api_retry") d.retrying = true;
+  if (e.type === "rate_limit_event" && e.rate_limit_info?.status === "rejected") d.limit = true;
+  // each assistant message of the main thread carries its own request's usage; `result` sums the session
+  if (e.type === "assistant" && !e.parent_tool_use_id && e.message?.usage)
+    d.requestInput = claudeTokens(e.message.usage).input;
+  if (e.type === "result") {
+    const f = foldClaudeEvents([line]);
+    d.final = true;
+    d.tokens = f.result?.tokens;
+    if (typeof e.total_cost_usd === "number") d.costUsd = e.total_cost_usd;
+    if (e.is_error === true) d.failure = String(e.result ?? "error");
+    if (f.limit) d.limit = true;
+  }
+  return d;
+}
+
+async function probe(): Promise<Probe> {
+  const v = await runCli("claude", ["--version"], claudeShell);
+  if (!v)
+    return {
+      installed: false,
+      version: null,
+      versionOk: false,
+      loggedIn: null,
+      problems: [
+        {
+          code: "E_BACKEND_MISSING",
+          message: "claude is not on PATH",
+          fix: "npm i -g @anthropic-ai/claude-code",
+        },
+      ],
+    };
+  const version = extractVersion(v.out);
+  const versionOk = version !== null && compareVersions(version, CLAUDE_MIN_VERSION) >= 0;
+  const status = jsonOf((await runCli("claude", ["auth", "status", "--json"], claudeShell))?.out) as {
+    loggedIn?: unknown;
+  } | null;
+  const loggedIn = status?.loggedIn === true;
+  const problems: Probe["problems"] = [];
+  if (!versionOk)
+    problems.push({
+      code: "E_BACKEND_TOO_OLD",
+      message: `claude ${version ?? "?"} is older than ${CLAUDE_MIN_VERSION}`,
+      fix: "claude update",
+    });
+  if (!loggedIn)
+    problems.push({
+      code: "E_BACKEND_NOT_LOGGED_IN",
+      message: "claude is not logged in",
+      fix: "claude auth login",
+    });
+  return { installed: true, version, versionOk, loggedIn, problems };
+}
+
+export const claudeCodeAdapter: BackendAdapter = {
+  id: "claude-code",
+  minVersion: CLAUDE_MIN_VERSION,
+  probe,
+  listModels: () => listClaudeModels(),
+  prepare,
+  plan,
+  parse,
+  finalize,
+  enforcement: { "read-only": "advisory", "workspace-write": "advisory", full: "advisory" },
+  errors: { limit: CLAUDE_LIMIT, tooOld: CLAUDE_TOO_OLD },
+  resume: { supported: true, sameAccessOnly: false, threadPattern: THREAD },
+  // the `result` event is the last thing claude prints; a CLI still running 30 s later is stuck
+  graceAfterFinalMs: 30_000,
+};

package/src/adapters/claude-code/models-api.ts

@@ -0,0 +1,65 @@
+import type { DiscoveredModel } from "../backend.ts";
+import { CLAUDE_ALIASES, CLAUDE_EFFORTS, CLAUDE_MODELS } from "./models.ts";
+
+export const ANTHROPIC_MODELS_URL = "https://api.anthropic.com/v1/models";
+
+interface ApiModel {
+  id?: unknown;
+  max_input_tokens?: unknown;
+  capabilities?: {
+    image_input?: { supported?: unknown };
+    effort?: Record<string, { supported?: unknown } | unknown>;
+  };
+}
+
+const supported = (v: unknown) => (v as { supported?: unknown } | undefined)?.supported === true;
+
+function fromApi(m: ApiModel): DiscoveredModel | null {
+  if (typeof m.id !== "string" || !m.id.startsWith("claude-") || m.id in CLAUDE_ALIASES) return null;
+  const known = CLAUDE_MODELS.find((k) => k.id === m.id);
+  const effort = m.capabilities?.effort;
+  return {
+    id: m.id,
+    // a model without effort support lists no effort, so its only rung is #default (Haiku 4.5)
+    efforts: effort ? CLAUDE_EFFORTS.filter((e) => supported(effort[e])) : [...(known?.efforts ?? [])],
+    context: typeof m.max_input_tokens === "number" ? m.max_input_tokens : (known?.context ?? null),
+    imageIn: m.capabilities?.image_input ? supported(m.capabilities.image_input) : (known?.imageIn ?? false),
+  };
+}
+
+/**
+ * Spec §5.2: Claude's models are the shipped list, refreshed from the Models API when an Anthropic API
+ * key is present. The API's entries win; shipped models it does not list stay (a Claude plan login may
+ * reach models an API key does not). Any failure keeps the shipped list.
+ */
+export async function listClaudeModels(
+  o: { key?: string | null; fetchImpl?: typeof fetch; timeoutMs?: number } = {},
+): Promise<DiscoveredModel[]> {
+  const shipped = CLAUDE_MODELS.map((m) => ({ ...m, efforts: [...m.efforts] }));
+  const key = o.key === undefined ? process.env.ANTHROPIC_API_KEY?.trim() || null : o.key;
+  if (!key) return shipped;
+  const fetchImpl = o.fetchImpl ?? globalThis.fetch;
+  const listed: DiscoveredModel[] = [];
+  let after: string | null = null;
+  try {
+    for (let page = 0; page < 20; page++) {
+      const url = `${ANTHROPIC_MODELS_URL}?limit=1000${after ? `&after_id=${encodeURIComponent(after)}` : ""}`;
+      const res = await fetchImpl(url, {
+        headers: { "x-api-key": key, "anthropic-version": "2023-06-01" },
+        signal: AbortSignal.timeout(o.timeoutMs ?? 15_000),
+      });
+      if (!res.ok) return shipped;
+      const body = (await res.json()) as { data?: ApiModel[]; has_more?: unknown; last_id?: unknown };
+      for (const m of body.data ?? []) {
+        const d = fromApi(m);
+        if (d) listed.push(d);
+      }
+      if (body.has_more !== true || typeof body.last_id !== "string") break;
+      after = body.last_id;
+    }
+  } catch {
+    return shipped;
+  }
+  if (listed.length === 0) return shipped;
+  return [...listed, ...shipped.filter((s) => !listed.some((l) => l.id === s.id))];
+}

package/src/adapters/claude-code/models.ts

@@ -0,0 +1,26 @@
+import type { DiscoveredModel } from "../backend.ts";
+
+export const CLAUDE_EFFORTS = ["low", "medium", "high", "xhigh", "max"];
+
+/**
+ * Spec §5.2: Claude's models come from a shipped list (Claude Code has no model listing; research
+ * 2026-09-25-models.md §1.1). Full ids only: an alias resolves differently per provider.
+ */
+export const CLAUDE_MODELS: DiscoveredModel[] = [
+  { id: "claude-fable-5-1", efforts: CLAUDE_EFFORTS, context: 1_000_000, imageIn: true },
+  { id: "claude-opus-5-5", efforts: CLAUDE_EFFORTS, context: 1_000_000, imageIn: true },
+  { id: "claude-sonnet-5", efforts: CLAUDE_EFFORTS, context: 1_000_000, imageIn: true },
+  { id: "claude-haiku-4-5-20251001", efforts: [], context: 200_000, imageIn: true },
+];
+
+/** Claude Code aliases and dateless short ids that name a different model per provider or over time. */
+export const CLAUDE_ALIASES: Record<string, string> = {
+  fable: "claude-fable-5-1",
+  best: "claude-fable-5-1",
+  opus: "claude-opus-5-5",
+  opusplan: "claude-opus-5-5",
+  default: "claude-opus-5-5",
+  sonnet: "claude-sonnet-5",
+  haiku: "claude-haiku-4-5-20251001",
+  "claude-haiku-4-5": "claude-haiku-4-5-20251001",
+};

package/src/adapters/cli.ts

@@ -0,0 +1,74 @@
+import { scrubSecrets } from "../infra/env.ts";
+import { log } from "../infra/log.ts";
+import { killGroup } from "../infra/proc.ts";
+
+export interface CliResult {
+  ok: boolean;
+  out: string;
+  err: string;
+}
+
+/** Process groups of CLI calls still running: an exiting catherd (Ctrl-C is exit 130) kills them. */
+const live = new Set<number>();
+let hooked = false;
+function track(pid: number): void {
+  live.add(pid);
+  if (hooked) return;
+  hooked = true;
+  // a detached group gets no terminal SIGINT, and process.exit skips the timeout, so kill it on the way out
+  process.on("exit", () => {
+    for (const g of live) killGroup(g, "SIGKILL");
+  });
+}
+
+/**
+ * Runs `bin <args>` without catherd's secrets and with no stdin; null when `bin` is not on PATH. A call
+ * past `timeoutMs` is killed with every process it started (it runs in its own process group) and is
+ * reported as failed, so neither a wedged CLI nor a child holding its pipes stalls the caller.
+ */
+export async function runCli(
+  bin: string,
+  args: string[],
+  o: { timeoutMs: number; env?: Record<string, string>; cwd?: string },
+): Promise<CliResult | null> {
+  if (!Bun.which(bin, { PATH: process.env.PATH ?? "" })) return null;
+  log("debug", "spawn", { argv: [bin, ...args], env: o.env ?? {} });
+  const p = Bun.spawn([bin, ...args], {
+    cwd: o.cwd,
+    env: { ...scrubSecrets(process.env), ...o.env },
+    stdin: "ignore",
+    stdout: "pipe",
+    stderr: "pipe",
+    detached: true,
+  });
+  track(p.pid);
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const late = new Promise<null>((resolve) => {
+    timer = setTimeout(() => resolve(null), o.timeoutMs);
+  });
+  try {
+    const done = await Promise.race([
+      Promise.all([p.exited, new Response(p.stdout).text(), new Response(p.stderr).text()]),
+      late,
+    ]);
+    if (!done) {
+      killGroup(p.pid, "SIGKILL");
+      return { ok: false, out: "", err: `${bin} ${args.join(" ")} timed out after ${o.timeoutMs} ms` };
+    }
+    const [code, out, err] = done;
+    return { ok: code === 0, out, err };
+  } finally {
+    clearTimeout(timer);
+    live.delete(p.pid);
+  }
+}
+
+/** The JSON a CLI printed, or null for empty or unreadable output. */
+export function jsonOf(out: string | undefined): unknown {
+  if (!out?.trim()) return null;
+  try {
+    return JSON.parse(out);
+  } catch {
+    return null;
+  }
+}

package/src/adapters/codex/events.ts

@@ -0,0 +1,65 @@
+import { type Tokens, ZERO_TOKENS } from "../../domain/record.ts";
+
+export interface CodexFold {
+  thread: string | null;
+  tokens: Tokens;
+  turnFailed: boolean;
+  failure: string | null;
+  limit: boolean;
+  tooOld: boolean;
+  lastEvent: string | null;
+}
+
+/**
+ * An account limit, not any error that says "try again later" (an overloaded server does too). A rate
+ * limit codex retried until it gave up reads "exceeded retry limit, last status: 429 Too Many Requests".
+ */
+export const CODEX_LIMIT = [
+  /usage limit/i,
+  /rate limit reached/i,
+  /quota exceeded/i,
+  /status: 429|too many requests/i,
+];
+export const CODEX_TOO_OLD = [/not supported when using Codex with a ChatGPT account/i];
+
+type Event = Record<string, any>;
+
+export function parseCodexLine(line: string): Event | null {
+  if (!line.trim().startsWith("{")) return null;
+  try {
+    return JSON.parse(line) as Event;
+  } catch {
+    return null;
+  }
+}
+
+/** Only `turn.failed` fails a run: an `error` event mid-stream is a transient reconnect. */
+export function foldCodexEvents(lines: string[]): CodexFold {
+  const f: CodexFold = {
+    thread: null,
+    tokens: { ...ZERO_TOKENS },
+    turnFailed: false,
+    failure: null,
+    limit: false,
+    tooOld: false,
+    lastEvent: null,
+  };
+  for (const line of lines) {
+    const e = parseCodexLine(line);
+    if (!e) continue;
+    f.lastEvent = e.item?.type ? `${e.type}/${e.item.type}` : e.type;
+    const msg: string = e.message ?? e.error?.message ?? e.item?.message ?? "";
+    if (CODEX_TOO_OLD.some((r) => r.test(msg))) f.tooOld = true;
+    if (e.type === "thread.started") f.thread = e.thread_id ?? null;
+    else if (e.type === "turn.completed" && e.usage) {
+      f.tokens.input += e.usage.input_tokens ?? 0;
+      f.tokens.cached += e.usage.cached_input_tokens ?? 0;
+      f.tokens.output += e.usage.output_tokens ?? 0;
+    } else if (e.type === "turn.failed") {
+      f.turnFailed = true;
+      f.failure = msg || "turn failed";
+      if (CODEX_LIMIT.some((r) => r.test(msg))) f.limit = true;
+    }
+  }
+  return f;
+}