tumwater 0.2.0 → 0.4.0

package/dist/src/agent/codex/codex-backend.js

@@ -0,0 +1,279 @@
+/** The codex adapter for the agent seam (plans/codex-backend.md §4, §5, §6): it shapes one
+ * run's argv/stdin/env, translates codex's `exec --json` stream, reads the authoritative
+ * rollout after the process exits, and classifies the exit's stderr — everything
+ * backend-specific. src/agent/run-agent.ts owns the spawn and records this run in the session
+ * ledger; codex mints its own session id (a thread id, or the resumed record's id) in the
+ * stream's `thread.started`, which the runner's stream-mint pass appends to the ledger and
+ * `invocation` returns so a later `exec resume` can reach it.
+ *
+ * Sessions resume by id, out of the team's `CODEX_HOME`. A continue takes the ledger's newest
+ * record of this run's kind and resumes only when it is codex's, has this cwd, carries a UUID
+ * id, and `findRollout` finds its rollout under the run's home — anything else mints a fresh
+ * thread and the existing `handoff` path takes over (design §4). Together with the `resumable`
+ * hook, that is every resume point's one rule.
+ *
+ * Registration lives in src/agent/run-agent.ts beside the pi, claude and opencode adapters; a
+ * test selects codex by setting `config.agent = "codex"` on a run. A run carrying a note gets
+ * the notes path in its environment (the `tumwater-notes` command on PATH reads it), as the
+ * pi and claude adapters do. */
+import fs from "node:fs";
+import { loadConfigSafe } from "../../config/config.js";
+import { resolvedBackendConfig } from "../../config/config-views.js";
+import { backendRunEnv } from "../../process/run-marker.js";
+import { resolveBinForBackend } from "../../pi/pi-bin.js";
+import { teamRootOf, nearestTumwaterRoot } from "../../paths.js";
+import { warnEventBestEffort, TUMWATER_SOURCE } from "../../events/events.js";
+import { errorMessage } from "../../text/text.js";
+import { codexHome, readCodexCatalog } from "./codex-catalog.js";
+import { resumableSession } from "../session-ledger.js";
+import { codexArgs, codexEffort } from "./codex-args.js";
+import { codexEnv } from "./codex-env.js";
+import { codexHookTrust } from "./codex-hook-trust.js";
+import { codexHookArg, codexHookTrustArg, codexWriteGuardDefinition } from "./codex-write-guard.js";
+import { findRollout, rolloutLines } from "./codex-rollout.js";
+import { codexTranslator } from "./codex-stream.js";
+/** A codex thread id (a UUID format, e.g. `01a15c9d-6762-7931-814e-a3e6e64c1b51`). The
+ * stream mints it in `thread.started`; the pre-spawn ledger record carries the session name
+ * instead, so this regex is what tells a resume that a record holds a real, stream-minted id
+ * worth resuming (design §4). */
+const THREAD_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+/** The oldest codex CLI the team targets, the sibling of `OPENCODE_MIN_VERSION`
+ * (src/agent/opencode/opencode-backend.ts) and `CLAUDE_MIN_VERSION`
+ * (src/agent/claude/claude-backend.ts): doctor's `codex version` row fails an installed CLI
+ * below this floor (plans/codex-backend.md "Hand steps", H1). */
+export const CODEX_MIN_VERSION = "0.163.0";
+/** The wall-clock bound `prepare` gives each trust lookup, mirroring lookupCodexHookTrust's
+ * own 15 s default (plans/codex-write-guard.md "Trust (parts 4–5)"). Settable so a test can
+ * shorten the bound (to 500 ms) without waiting out the real 15 s; a hand run keeps the
+ * default. */
+let codexTrustLookupTimeoutMs = 15_000;
+/** The test seam for the trust lookup bound: a test sets it to 500 ms and returns it to the
+ * 15 s default in a finally, so a hanging app-server case stays fast without a config knob. */
+export function setCodexTrustLookupTimeoutMs(ms) {
+    codexTrustLookupTimeoutMs = ms;
+}
+/** The write-guard trust `prepare` has resolved, keyed by home and hook definition, so one
+ * process looks each up at most once and a run's invocation never spawns `app-server` again. */
+const writeGuardTrust = new Map();
+/** One in-flight resolution per (home, definition) key, so concurrent runs share a single
+ * `app-server` instead of starting one each (plans/codex-write-guard.md "Trust (parts 4–5)"). */
+const writeGuardInFlight = new Map();
+/** The (home, definition) keys whose `off` warning has already been logged, so a failed lookup
+ * warns once per process instead of once per run. */
+const writeGuardWarned = new Set();
+/** Warn once per process per (home, definition) that the write guard is off. The warning rides
+ * the best-effort event feed on the run's root, skipped when there is no root (a hand run's
+ * prepared look-up must not mint a `.tumwater`). A `trust` result logs nothing. */
+function warnGuardOffOnce(key, root, state) {
+    if (state.kind !== "off")
+        return;
+    if (writeGuardWarned.has(key))
+        return;
+    writeGuardWarned.add(key);
+    if (root !== undefined) {
+        warnEventBestEffort(root, TUMWATER_SOURCE, `codex write guard off: ${state.reason}`);
+    }
+}
+/** The (home, definition) cache key shared by the single-flight and the resolved-trust map. */
+function writeGuardKey(home, definition) {
+    return `${home ?? ""}|${JSON.stringify(definition)}`;
+}
+/** The session this run uses: for a continue, the ledger's newest record of this kind when it
+ * is codex's, has this cwd, carries a UUID thread id, and `findRollout` finds its rollout
+ * under the run's home; otherwise the run is fresh (no pre-minted id — the stream names it).
+ * Returns the id and whether this is a resume, so `invocation` can name it and build `exec
+ * resume`. */
+function resolveCodexSession(run, home) {
+    if (run.continueSession && home !== undefined) {
+        const record = resumableSession(run.sessionDir, {
+            kind: run.kind,
+            agent: "codex",
+            cwd: run.cwd,
+        });
+        if (record !== null && THREAD_ID_RE.test(record.id) && findRollout(home, record.id) !== null) {
+            return { sessionId: record.id, resumed: true };
+        }
+    }
+    return { resumed: false };
+}
+/** Classify codex's stderr: the seam's stderr half for a CLI that died before emitting a
+ * `turn.failed` (the stream's own failures are classified by the translator). A run the
+ * harness killed has its own cause and is never classified here (design finding 12). The
+ * codex CLI surfaces login/model/usage failures as stream JSON, so a bare nonzero exit with
+ * no stream carries no signal this part has a verdict for — it stays unclassified and the
+ * parser's own event-derived flags stand. */
+function classifyCodexExit(info) {
+    if (info.killed)
+        return {};
+    return {};
+}
+/** The agent-backend seam's codex adapter. */
+export const codexBackend = {
+    id: "codex",
+    label: "Codex",
+    defaultBin: "codex",
+    binEnv: "TUMWATER_CODEX_BIN",
+    resolveBin(config) {
+        return resolveBinForBackend(config, this);
+    },
+    invocation(run) {
+        // The notes path rides beside the run marker, as the pi and claude adapters' envs do
+        // (withNotesPath); from part 2/4 the run saves its note through the `tumwater-notes`
+        // command on PATH, so codex configures no MCP server for notes.
+        const base = backendRunEnv(run);
+        // A team home of its own (`CODEX_HOME`) keeps team sessions and trust entries out of the
+        // operator's `~/.codex` (design §4, finding 10); unset leaves the operator's home.
+        const home = codexHome(resolvedBackendConfig(run.config, "codex"));
+        const env = codexEnv(base, { home });
+        const { sessionId, resumed } = resolveCodexSession(run, home);
+        const thinking = run.config.thinking;
+        // The effort (parts 5/9 and 8/9): ride the thinking level through the decoder, then gate
+        // it on the model's cataloged effort levels — a level the model does not list is never
+        // sent (codexEffort's `levels` half). No home (no catalog) leaves the value unclamped, as
+        // before part 8/9.
+        const catalog = home === undefined ? new Map() : readCodexCatalog(home);
+        const effort = thinking === undefined ? undefined : codexEffort(thinking, catalog.get(run.config.model ?? "")?.levels);
+        // The write guard's trust (part 6/9): `prepare` resolved it under this run's env and
+        // home and stored it keyed by (home, definition), so `invocation` reads it synchronously.
+        // With trust it rides the hook and its trust entry as two `-c` values (after the
+        // harness's own keys, before `-m`); with `off` or no state it passes neither, since an
+        // untrusted hook would be skipped silently anyway. tumwater never passes
+        // `--dangerously-bypass-hook-trust` (findings 1 and 4).
+        const definition = codexWriteGuardDefinition();
+        const trust = writeGuardTrust.get(writeGuardKey(home, definition));
+        const guardArgs = trust?.kind === "trust"
+            ? ["-c", codexHookArg(definition), "-c", codexHookTrustArg(trust.trust)]
+            : undefined;
+        const { args, stdin } = codexArgs({
+            model: run.config.model ?? "",
+            ...(effort !== undefined ? { effort } : {}),
+            ...(resumed && sessionId !== undefined ? { resumeId: sessionId } : {}),
+            ...(guardArgs !== undefined ? { guardArgs } : {}),
+            args: resolvedBackendConfig(run.config, "codex").args,
+            prompt: run.prompt,
+        });
+        // A resumed run returns its id so the runner's pre-spawn ledger record carries it; a fresh
+        // run has none until the stream names it (the runner's stream-mint pass appends it).
+        return { args, stdin, env, ...(resumed && sessionId !== undefined ? { sessionId } : {}) };
+    },
+    async prepare(run) {
+        // Resolve the write guard's trust under the same env and home invocation will use (the
+        // run's CODEX_HOME, plans/codex-write-guard.md "Trust (parts 4–5)"), so the trust an
+        // invocation later reads was looked up under the run's own config. It never throws a run
+        // away: a failed lookup records `off` (and warns once) and the run continues without the
+        // guard's trust.
+        const base = backendRunEnv(run);
+        const home = codexHome(resolvedBackendConfig(run.config, "codex"));
+        const env = codexEnv(base, { home });
+        const root = nearestTumwaterRoot(run.sessionDir);
+        const definition = codexWriteGuardDefinition();
+        const key = writeGuardKey(home, definition);
+        // Single-flight per (home, definition): a run whose key is being resolved (or already
+        // resolved) shares the one in-flight lookup, so concurrent runs start one `app-server`.
+        const settled = writeGuardTrust.get(key);
+        if (settled !== undefined) {
+            warnGuardOffOnce(key, root, settled);
+            return;
+        }
+        const inFlight = writeGuardInFlight.get(key);
+        if (inFlight !== undefined) {
+            await inFlight;
+            const after = writeGuardTrust.get(key);
+            if (after !== undefined)
+                warnGuardOffOnce(key, root, after);
+            return;
+        }
+        const promise = (async () => {
+            try {
+                const trust = await codexHookTrust(root, {
+                    bin: run.agentBin,
+                    env,
+                    cwd: run.cwd,
+                    definition,
+                    timeoutMs: codexTrustLookupTimeoutMs,
+                });
+                writeGuardTrust.set(key, { kind: "trust", trust });
+            }
+            catch (error) {
+                writeGuardTrust.set(key, { kind: "off", reason: errorMessage(error) });
+            }
+        })();
+        writeGuardInFlight.set(key, promise);
+        await promise;
+        writeGuardInFlight.delete(key);
+        const state = writeGuardTrust.get(key);
+        if (state !== undefined)
+            warnGuardOffOnce(key, root, state);
+    },
+    translator() {
+        return codexTranslator();
+    },
+    imageInput(model) {
+        // Answer from the model catalog (part 8/9): a model reads images when its catalog entry's
+        // `input_modalities` say so; a model missing from the catalog — or a run with no home to
+        // read — answers false, the safe direction, so a blind image read is never silently
+        // assumed readable. The home is the team's `backends.codex.configDir`, found by walking
+        // up from the process's working directory to its `.tumwater` root and loading the config
+        // there, the same root the runs' home and account live under (like opencode's cache).
+        if (model === undefined)
+            return false;
+        const root = teamRootOf(process.cwd());
+        const { config } = loadConfigSafe(root);
+        const home = codexHome(resolvedBackendConfig(config ?? {}, "codex"));
+        if (home === undefined)
+            return false;
+        return readCodexCatalog(home).get(model)?.images === true;
+    },
+    resumable(dir, opts) {
+        const record = resumableSession(dir, { kind: opts.kind, agent: "codex", cwd: opts.cwd });
+        if (record === null || !THREAD_ID_RE.test(record.id))
+            return false;
+        const root = teamRootOf(dir);
+        const { config } = loadConfigSafe(root);
+        const home = codexHome(resolvedBackendConfig(config ?? {}, "codex"));
+        if (home === undefined)
+            return false;
+        return findRollout(home, record.id) !== null;
+    },
+    afterRun(run, invocation, translator) {
+        const ct = translator;
+        const home = codexHome(resolvedBackendConfig(run.config, "codex"));
+        const id = invocation.sessionId ?? ct.sessionId?.();
+        const fresh = invocation.sessionId === undefined;
+        // The rollout is authoritative, so its loss is worth one warning: a fresh run keeps the
+        // stream's own usage as a fallback, a resumed run records none (design §5, finding 4).
+        const fallback = () => {
+            ct.flagUsagePartial();
+            if (!fresh)
+                return [];
+            const usage = ct.turnCompletedUsage();
+            return usage !== undefined ? [JSON.stringify({ type: "run_usage", ...usage })] : [];
+        };
+        if (home === undefined || id === undefined)
+            return fallback();
+        const rollout = findRollout(home, id);
+        if (rollout === null)
+            return fallback();
+        let text;
+        try {
+            text = fs.readFileSync(rollout, "utf8");
+        }
+        catch {
+            return fallback();
+        }
+        // The stream never exposes the turn id — only the thread id that names the rollout file
+        // (real captures' `task_started.turn_id` is a different UUID), so the reader selects the
+        // last block, this run's, from the file the thread id located.
+        const { lines, switchedTo } = rolloutLines(text, {
+            requestedModel: run.config.model ?? "",
+        });
+        if (lines.length === 0)
+            return fallback();
+        // Codex can switch models on a usage limit by itself (finding 24): warn once and record
+        // the model that actually ran in the rollout's reading.
+        if (switchedTo !== undefined)
+            ct.flagModelSwitched(run.config.model ?? "", switchedTo);
+        return lines;
+    },
+    classifyExit: classifyCodexExit,
+};

package/dist/src/agent/codex/codex-catalog.js

@@ -0,0 +1,97 @@
+/** The Codex model catalog (plans/codex-backend.md design finding 14 — "Spend, free-ness,
+ * window, images" part 8/9): tumwater reads a Codex model's effort levels, default effort,
+ * context window and image input from `$CODEX_HOME/models_cache.json`, the file the CLI itself
+ * refreshes and `codex debug models` prints. Before part 8/9 the adapter assumed every Codex
+ * model had every effort and read every image; the catalog refines both, and seats the context
+ * window `seamContextWindow` reports for a codex seam. There are no prices in the catalog — the
+ * whole file knows nothing of cost — so free-ness never reads here; the codex account
+ * (codex-account.ts) owns billing.
+ *
+ * A missing, unreadable or malformed file reads as an empty catalog, the same "no data" policy
+ * pi's models.json reader uses: the adapter then answers blind (no effort gating, no images,
+ * no window), which is the safe direction for the window and image checks. The parse itself is
+ * pure and build-agnostic — no registry, config or subprocess — so the adapter, pi's
+ * seamContextWindow and the doctor can read one answer without dragging a runtime in. */
+import os from "node:os";
+import path from "node:path";
+import { cachedByStat } from "../../files/stat-cache.js";
+import { finiteNumber, isJsonObject } from "../../files/json-object.js";
+import { readJsonFile } from "../../files/json-files.js";
+import { expandHomeTilde } from "../../files/files.js";
+/** The team's Codex home for a run: `backends.codex.configDir`, a leading `~` expanded, else
+ * the CLI's default `~/.codex` — a run with no configured home keeps the operator's
+ * `CODEX_HOME`, which is exactly Codex's own default home, so the catalog and the sessions
+ * live there too and a known home always exists. Pure. Shared by the adapter, pi's
+ * seamContextWindow and the codex-account seed, so all three read one home. */
+export function codexHome(config) {
+    const dir = config.configDir;
+    if (dir === undefined)
+        return path.join(os.homedir(), ".codex");
+    return expandHomeTilde(dir, os.homedir());
+}
+/** Where a home's model catalog lives: `$CODEX_HOME/models_cache.json`. */
+export function codexModelsPath(home) {
+    return path.join(home, "models_cache.json");
+}
+/** Per-catalog cache of the parsed entries, keyed by the models_cache path: the status
+ * surfaces read the window every poll while the file changes only when the CLI refreshes it —
+ * and it grows with the model catalog — so an unchanged file costs one stat per poll instead
+ * of a re-read plus a JSON.parse of the whole file. Any write invalidates via
+ * dev/ino/mtime/size (stat-cache.cachedByStat, the same freshness check pi's providers use). */
+const catalogCache = new Map();
+/** The parsed model catalog from `$CODEX_HOME/models_cache.json`, keyed by model slug, or an
+ * empty map when the file is missing, unreadable, malformed or not shaped like what the CLI
+ * writes. A model's entry is kept only when it names a usable slug and context_window; a
+ * missing `effective_context_window_percent` reads as no window (the model is dropped), since
+ * the window is the whole point of the entry. The returned map is a copy — callers may treat
+ * their result as their own. */
+export function readCodexCatalog(home) {
+    const modelsPath = codexModelsPath(home);
+    return (cachedByStat(catalogCache, modelsPath, modelsPath, () => {
+        const out = new Map();
+        // readJsonFile is the shared "missing or torn reads as no data" policy for a JSON
+        // object file; the nested `models` array gets the same isJsonObject/Array guards.
+        const doc = readJsonFile(modelsPath);
+        if (doc === null)
+            return out;
+        const models = doc.models;
+        if (!Array.isArray(models))
+            return out;
+        for (const model of models) {
+            const entry = parseModelEntry(model);
+            if (entry !== undefined)
+                out.set(entry.slug, entry.entry);
+        }
+        return out;
+    }, (models) => new Map([...models].map(([slug, entry]) => [slug, { ...entry, levels: [...entry.levels] }]))) ?? new Map());
+}
+/** One catalog model entry as the map needs it: the slug to key by plus the parsed entry. The
+ * entry is kept only when the slug and context window are usable; any other missing field
+ * (levels, modalities, default level) just reads as absent on the entry. */
+function parseModelEntry(model) {
+    if (!isJsonObject(model) || typeof model.slug !== "string")
+        return undefined;
+    const context = finiteNumber(model.context_window, Number.NaN);
+    const percent = finiteNumber(model.effective_context_window_percent, Number.NaN);
+    if (!Number.isFinite(context) || !Number.isFinite(percent))
+        return undefined;
+    const levels = [];
+    if (Array.isArray(model.supported_reasoning_levels)) {
+        for (const level of model.supported_reasoning_levels) {
+            if (isJsonObject(level) && typeof level.effort === "string")
+                levels.push(level.effort);
+        }
+    }
+    const modalities = model.input_modalities;
+    return {
+        slug: model.slug,
+        entry: {
+            levels,
+            ...(typeof model.default_reasoning_level === "string"
+                ? { defaultLevel: model.default_reasoning_level }
+                : {}),
+            contextWindow: Math.round((context * percent) / 100),
+            images: Array.isArray(modalities) && modalities.includes("image"),
+        },
+    };
+}

package/dist/src/agent/codex/codex-env.js

@@ -0,0 +1,18 @@
+/** Build the codex process environment from `base`. Never mutates `base`. */
+export function codexEnv(base, opts = {}) {
+    const env = {};
+    for (const [key, value] of Object.entries(base)) {
+        if (key === "CLAUDECODE")
+            continue;
+        if (key.startsWith("CODEX_"))
+            continue;
+        if (key.startsWith("CLAUDE_CODE_"))
+            continue;
+        if (key === "OPENAI_API_KEY" || key === "CODEX_API_KEY")
+            continue;
+        env[key] = value;
+    }
+    if (opts.home)
+        env.CODEX_HOME = opts.home;
+    return env;
+}

package/dist/src/agent/codex/codex-hook-trust.js

@@ -0,0 +1,246 @@
+/** How tumwater learns the write guard's trust from codex itself (plans/codex-write-guard.md
+ * "Trust (parts 4–5)", findings 2–3): codex runs a session-flag PreToolUse hook only when its
+ * `trusted_hash` matches the hash codex computed for the hook's definition, and that hash is
+ * opaque — no simple digest of any command or JSON spelling matched (finding 3). So this module
+ * asks codex's own `hooks/list` RPC for the hook's `key` and `currentHash`, and caches the
+ * answer per build and codex version so a run's argv never spawns `app-server` again. The
+ * answer is never hardcoded: the key (`/<session-flags>/config.toml:pre_tool_use:0:0` on
+ * 0.163.0) and the hash both come from this lookup.
+ *
+ * The lookup spawns `app-server` in its own process group under the run's env and a bounded
+ * deadline, kills the group whether it succeeds, times out, or fails, and makes no model
+ * request and needs no login (an empty `CODEX_HOME` is enough — finding 3). Part 5/9 wires it
+ * into a run before the codex adapter's synchronous invocation. */
+import { spawn } from "node:child_process";
+import { codexHookArg } from "./codex-write-guard.js";
+import { readJsonFile, writeJsonAtomic } from "../../files/json-files.js";
+import { releaseChildHandles, signalTree } from "../../process/process.js";
+import { codexHookTrustPath } from "../../paths.js";
+import { PACKAGE_JSON, packageVersion } from "../../version.js";
+/** The JSON-RPC request/notification sequence one lookup sends over `app-server`'s stdio: the
+ * `initialize` handshake (carrying tumwater's own version), the `initialized` notification,
+ * then `hooks/list` for the one cwd. The reply to `id: 2` carries the hooks. */
+function hookListMessages(cwd) {
+    const version = packageVersion(PACKAGE_JSON).version;
+    return [
+        {
+            jsonrpc: "2.0",
+            id: 1,
+            method: "initialize",
+            params: { clientInfo: { name: "tumwater", version: version ?? "unknown" } },
+        },
+        { jsonrpc: "2.0", method: "initialized" },
+        { jsonrpc: "2.0", id: 2, method: "hooks/list", params: { cwds: [cwd] } },
+    ];
+}
+/** The first hook in `hooks/list`'s `result.data[*].hooks` with `source: "sessionFlags"`,
+ * `eventName: "preToolUse"` and `command` exactly the guard definition's (finding 3), or null
+ * when none matches. The key and hash are returned as codex reports them. */
+function findTrust(result, definition) {
+    if (typeof result !== "object" || result === null)
+        return null;
+    const data = result.data;
+    if (!Array.isArray(data))
+        return null;
+    for (const group of data) {
+        if (typeof group !== "object" || group === null)
+            continue;
+        const hooks = group.hooks;
+        if (!Array.isArray(hooks))
+            continue;
+        for (const hook of hooks) {
+            if (typeof hook !== "object" || hook === null)
+                continue;
+            const h = hook;
+            if (h.source !== "sessionFlags" || h.eventName !== "preToolUse")
+                continue;
+            if (h.command !== definition.command)
+                continue;
+            if (typeof h.key === "string" && typeof h.currentHash === "string") {
+                return { key: h.key, hash: h.currentHash };
+            }
+        }
+    }
+    return null;
+}
+/** A short name for a JSON-RPC `error` value, for the rejection message. */
+function describeError(error) {
+    if (typeof error === "string")
+        return error;
+    if (typeof error === "object" && error !== null) {
+        const message = error.message;
+        if (typeof message === "string")
+            return message;
+    }
+    return JSON.stringify(error);
+}
+/** Ask codex for the guard hook's trust. Spawns `<bin> -c <codexHookArg(definition)>
+ * app-server` in `cwd` under `env`, in its own process group, sends the JSON-RPC sequence
+ * above over stdio, and resolves with the trust from the first matching `hooks/list` hook.
+ *
+ * It rejects on a timeout (`timeoutMs`), on the child exiting before the reply, on a JSON-RPC
+ * `error`, and on codex listing no session-flag PreToolUse hook with this command. The child's
+ * process group is SIGKILLed whether the lookup settles by success, failure, or timeout, so no
+ * `app-server` outlives the call. */
+export function lookupCodexHookTrust(opts) {
+    const timeoutMs = opts.timeoutMs ?? 15_000;
+    return new Promise((resolve, reject) => {
+        const child = spawn(opts.bin, ["-c", codexHookArg(opts.definition), "app-server"], {
+            cwd: opts.cwd,
+            env: opts.env,
+            detached: true,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        let settled = false;
+        let buffer = "";
+        const finish = (err, trust) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            signalTree(child, "SIGKILL");
+            releaseChildHandles(child);
+            if (err !== null)
+                reject(err);
+            else
+                resolve(trust);
+        };
+        const timer = setTimeout(() => {
+            finish(new Error(`codex hook trust lookup timed out after ${timeoutMs} ms`));
+        }, timeoutMs);
+        timer.unref?.();
+        const onLine = (line) => {
+            let msg;
+            try {
+                msg = JSON.parse(line);
+            }
+            catch {
+                return; // A non-JSON-RPC line (a notice, a prompt) is not our reply.
+            }
+            if (typeof msg !== "object" || msg === null)
+                return;
+            const m = msg;
+            if (m.error !== undefined) {
+                finish(new Error(`codex hooks/list errored: ${describeError(m.error)}`));
+                return;
+            }
+            if (m.id !== 2)
+                return;
+            const trust = findTrust(m.result, opts.definition);
+            if (trust !== null)
+                finish(null, trust);
+            else
+                finish(new Error("codex listed no session-flag PreToolUse hook with this command"));
+        };
+        child.stdout?.setEncoding("utf8");
+        child.stdout?.on("data", (chunk) => {
+            buffer += chunk;
+            let nl = buffer.indexOf("\n");
+            while (nl >= 0) {
+                const line = buffer.slice(0, nl);
+                buffer = buffer.slice(nl + 1);
+                if (line.trim() !== "")
+                    onLine(line);
+                nl = buffer.indexOf("\n");
+            }
+        });
+        child.on("error", (err) => finish(err instanceof Error ? err : new Error(String(err))));
+        child.on("close", (code) => {
+            if (!settled) {
+                finish(new Error(`codex app-server exited (code ${code ?? "signal"}) before answering hooks/list`));
+            }
+        });
+        for (const message of hookListMessages(opts.cwd)) {
+            try {
+                child.stdin?.write(JSON.stringify(message) + "\n");
+            }
+            catch {
+                // The pipe is gone (a failed spawn); the error handler settles the lookup.
+            }
+        }
+    });
+}
+/** The trimmed output of `<bin> --version`, or "" when the probe fails or prints nothing. It
+ * keys the trust cache, so a codex upgrade re-looks-up the guard's trust for the new build.
+ * Async (spawn, not spawnSync): a hung binary's probe must not block the event loop — every
+ * run's `prepare` awaits this, and a blocking probe would freeze the whole agent while waiting
+ * out its deadline. The child's group is killed whether it succeeds or times out. */
+function codexVersion(bin, env, cwd, timeoutMs) {
+    return new Promise((resolve) => {
+        const child = spawn(bin, ["--version"], {
+            env,
+            cwd,
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        let out = "";
+        let done = false;
+        const finish = (value) => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            signalTree(child, "SIGKILL");
+            releaseChildHandles(child);
+            resolve(value);
+        };
+        const timer = setTimeout(() => finish(""), timeoutMs);
+        timer.unref?.();
+        child.stdout?.setEncoding("utf8");
+        child.stdout?.on("data", (chunk) => {
+            out += chunk;
+        });
+        child.on("error", () => finish(""));
+        child.on("close", () => finish(out.trim()));
+    });
+}
+/** Whether a cached value is a usable `{key, hash}` entry. */
+function isTrust(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        typeof value.key === "string" &&
+        typeof value.hash === "string");
+}
+/** Resolve the guard hook's trust, cached per codex version and hook definition in
+ * `.tumwater/state/codex-hook-trust.json` so a run's argv never spawns `app-server` again.
+ * Returns the trust, rejecting on a failed lookup.
+ *
+ * The cache key is the trimmed `<bin> --version` output plus `JSON.stringify(definition)`, so
+ * a changed codex version, a changed hook command, or a changed `timeout` (which changes the
+ * hash, finding 3) each re-look-up; each entry is `{key, hash, checkedAt}`. A hit resolves
+ * without spawning `app-server`; a miss looks up and writes the entry atomically.
+ *
+ * `root` undefined (a hand run with no `.tumwater` root) looks up and caches nothing and never
+ * creates a `.tumwater` directory — a hand run once minted a phantom `$TMPDIR/.tumwater` and
+ * reddened every suite on the host (plans/codex-write-guard.md "Visibility"). */
+export async function codexHookTrust(root, opts) {
+    const timeoutMs = opts.timeoutMs ?? 15_000;
+    if (root === undefined)
+        return lookupCodexHookTrust(opts);
+    const file = codexHookTrustPath(root);
+    // The version probe and the app-server lookup share one deadline (timeoutMs): a failed
+    // lookup — a hung binary, an app-server that never answers — never delays a run past the
+    // bound, and the probe never blocks the event loop (it is async, not spawnSync). The probe
+    // is a quick identity read, so its own slice is capped at a third of the deadline — a slow
+    // probe never starves the app-server lookup of its budget, and the sum of the two always
+    // stays within the one deadline.
+    const deadline = Date.now() + timeoutMs;
+    const version = await codexVersion(opts.bin, opts.env, opts.cwd, Math.floor(timeoutMs / 3));
+    const cacheKey = `${version}${JSON.stringify(opts.definition)}`;
+    const cache = readJsonFile(file);
+    const hit = cache?.[cacheKey];
+    if (isTrust(hit))
+        return { key: hit.key, hash: hit.hash };
+    const trust = await lookupCodexHookTrust({
+        ...opts,
+        timeoutMs: Math.max(1, deadline - Date.now()),
+    });
+    const next = { ...(cache ?? {}) };
+    next[cacheKey] = { key: trust.key, hash: trust.hash, checkedAt: Date.now() };
+    try {
+        writeJsonAtomic(file, next);
+    }
+    catch {
+        // A cache write failure must never fail the lookup whose result it is only persisting.
+    }
+    return trust;
+}