catherd-cli 0.2.1 → 1.1.0

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

@@ -0,0 +1,317 @@
+import { CatherdError } from "../../domain/errors.ts";
+import type { Rung } from "../../domain/ids.ts";
+import type { Access, RunStatus } from "../../domain/record.ts";
+import {
+  type AccessShell,
+  type BackendAdapter,
+  compareVersions,
+  type EventDelta,
+  extractVersion,
+  type FinishedRun,
+  type Outcome,
+  type Probe,
+  type RunRequest,
+  type SpawnPlan,
+} from "../backend.ts";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { claudeHome } from "../../infra/paths.ts";
+import { dockerSocket, scratchShell, writableRoots } from "../access.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"],
+};
+
+/**
+ * Spec §5 for headless Claude Code. Its Bash runs unsandboxed unless the user turned Claude Code's own
+ * sandbox on (`sandbox.enabled`); then these settings, merged over the user's, add the lock and temp dirs,
+ * loopback binds, the Docker socket and `docker` itself (which cannot run inside that sandbox). Outbound
+ * domains stay the user's `sandbox.network.allowedDomains`: doctor's `access:claude-code` row says when
+ * the registry is not among them. `network: false` drops the network grants and the web tools (and with
+ * them Docker: the socket and `docker *` are network grants) and sets `allowLocalBinding: false`, so the
+ * user's own `true` does not carry over (their allowedDomains and other array grants merge in and stay;
+ * doctor says `network: false` is not enforced by claude-code's shell). With the user's sandbox on, `enabled: true`
+ * goes in too, so a merge that replaces the whole `sandbox` object cannot turn it off.
+ */
+export function claudeAccessArgs(access: Access, network = true, repo?: string): string[] {
+  const base = CLAUDE_ACCESS[access];
+  if (access !== "workspace-write") return base;
+  const sock = dockerSocket();
+  const sandbox = {
+    ...(claudeSandboxOn(repo) ? { enabled: true } : {}),
+    filesystem: { allowWrite: writableRoots() },
+    ...(network
+      ? {
+          network: { allowLocalBinding: true, ...(sock ? { allowUnixSockets: [sock] } : {}) },
+          excludedCommands: ["docker *"],
+        }
+      : // a boolean overrides the user's own `allowLocalBinding: true`; their array grants cannot be revoked here
+        { network: { allowLocalBinding: false } }),
+  };
+  const args = [...base, "--settings", JSON.stringify({ sandbox })];
+  if (!network) {
+    const i = args.indexOf("--disallowedTools") + 1;
+    args[i] = [args[i], "WebFetch", "WebSearch"].join(",");
+  }
+  return args;
+}
+
+/** `sandbox.enabled` in one settings file, when it says true or false; undefined when absent or unreadable. */
+function sandboxEnabledIn(file: string): boolean | undefined {
+  try {
+    const on = JSON.parse(readFileSync(file, "utf8"))?.sandbox?.enabled;
+    return typeof on === "boolean" ? on : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Whether Claude Code's Bash sandbox is on for a worker in `repo` (`sandbox.enabled`): the most specific
+ * settings file that says wins, as Claude Code layers them: the user's settings.json, then the project's
+ * .claude/settings.json and .claude/settings.local.json (Claude Code has no user-level settings.local.json).
+ */
+export function claudeSandboxOn(repo: string = process.cwd()): boolean {
+  const files = [
+    join(claudeHome(), "settings.json"),
+    join(repo, ".claude", "settings.json"),
+    join(repo, ".claude", "settings.local.json"),
+  ];
+  return files.map(sandboxEnabledIn).findLast((on) => on !== undefined) ?? false;
+}
+
+/**
+ * Spec §5: with Claude Code's own sandbox off (its default) a headless worker's Bash is an unsandboxed
+ * shell, which doctor probes as is. With it on, only a model turn runs inside it, so doctor says what to
+ * check instead of spending one.
+ */
+async function accessShell(): Promise<AccessShell | string> {
+  if (claudeSandboxOn())
+    return "Claude Code's own sandbox is on (sandbox.enabled): catherd passes the lock, temp, loopback and Docker grants in --settings; outbound HTTPS reaches only sandbox.network.allowedDomains, so add registry.npmjs.org and the hosts your checks need there";
+  return scratchShell("an unsandboxed shell (Claude Code's sandbox is off)", []);
+}
+
+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",
+      ...claudeAccessArgs(r.access, r.network, r.repo),
+      // --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 } : {}),
+  };
+}
+
+const EDIT_TOOLS = new Set(["Write", "Edit", "MultiEdit", "NotebookEdit"]);
+
+/** Spec §3.7: the main thread's last tool call (a command, a file edit, another tool) or its text. */
+function claudeActivity(e: Record<string, any>): string | undefined {
+  if (e.type !== "assistant" || e.parent_tool_use_id) return undefined;
+  const c = (e.message?.content ?? []).at(-1);
+  if (c?.type === "tool_use") {
+    const input = c.input ?? {};
+    if (typeof input.command === "string") return `$ ${input.command}`;
+    if (typeof input.file_path === "string")
+      return `${EDIT_TOOLS.has(c.name) ? "edit" : String(c.name)} ${input.file_path}`;
+    return String(c.name ?? "tool");
+  }
+  if (c?.type === "text" && typeof c.text === "string") return c.text;
+  return undefined;
+}
+
+function parse(line: string): EventDelta {
+  const e = parseClaudeLine(line);
+  if (!e) return {};
+  const d: EventDelta = { lastEvent: eventName(e) };
+  const activity = claudeActivity(e);
+  if (activity) d.activity = activity;
+  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 },
+  accessShell,
+  // 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;
+}

package/src/adapters/codex/home.ts

@@ -0,0 +1,47 @@
+import { existsSync, lstatSync, readdirSync, readlinkSync, statSync, symlinkSync, unlinkSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { dataDir } from "../../infra/paths.ts";
+import { ensurePrivateDir } from "../../infra/store.ts";
+
+export const userCodexHome = (): string => process.env.CODEX_HOME || join(homedir(), ".codex");
+
+/** Where isolated runs keep their Codex home; computing it creates nothing. */
+export const isolatedCodexHomePath = (): string => join(dataDir(), "codex-home");
+
+/** Isolated runs only: `--ignore-user-config` alone still loads the global AGENTS.md, so the home goes too. */
+export function isolatedCodexHome(): string {
+  const home = isolatedCodexHomePath();
+  ensurePrivateDir(home);
+  const auth = join(userCodexHome(), "auth.json");
+  const link = join(home, "auth.json");
+  if (!existsSync(auth)) return home;
+  // lstat, not existsSync: a broken link "does not exist" yet still blocks symlinkSync with EEXIST.
+  const current = lstatSync(link, { throwIfNoEntry: false });
+  if (current?.isSymbolicLink() && readlinkSync(link) !== auth) unlinkSync(link);
+  else if (current) return home;
+  symlinkSync(auth, link);
+  return home;
+}
+
+function mtimeMs(file: string): number | null {
+  try {
+    return statSync(file).mtimeMs;
+  } catch {
+    return null; // vanished between readdir and stat
+  }
+}
+
+export function generatedImages(home: string, thread: string | null, sinceMs: number): string[] {
+  if (!thread) return [];
+  const dir = join(home, "generated_images", thread);
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((f) => /\.(png|webp|jpe?g)$/i.test(f))
+    .map((f) => join(dir, f))
+    .filter((f) => {
+      const m = mtimeMs(f);
+      return m !== null && m >= sinceMs - 1000;
+    })
+    .sort();
+}