tumwater 0.2.0 → 0.4.0

package/dist/src/agent/codex/codex-write-guard.js

@@ -0,0 +1,86 @@
+/** codex's half of the write guard (src/agent/write-guard.ts holds the rule): a PreToolUse hook on
+ * `apply_patch`, installed by part 6/9, refuses an `apply_patch` that writes under the team root
+ * but outside the run's worktree. The entry point is write-guard-hook.ts beside this file.
+ *
+ * Codex's hook takes no argument naming the worktree, unlike claude's: codex trusts a hook by a
+ * hash of its whole definition, so a command constant per build needs one trust lookup, while a
+ * per-worktree argument would need one per slot (plans/codex-write-guard.md finding 3). The run's
+ * directory is the payload's `cwd`, which is codex's session cwd and cannot be moved by a shell
+ * `cd`, since every shell call is its own `zsh -lc`; with no `cwd` the hook returns null and lets
+ * the patch run. */
+import { fileURLToPath } from "node:url";
+import { shellQuote, strayWriteRefusal } from "../write-guard.js";
+import { patchWritePaths } from "./codex-patch-paths.js";
+/** The tool a codex PreToolUse hook sees for file edits; anything else is not this hook's
+ * business. */
+const APPLY_PATCH = "apply_patch";
+/** The refusal for one codex PreToolUse payload (the hook's stdin, parsed), or null to let the
+ * patch run. It acts only when `tool_name` is `"apply_patch"` and `tool_input.command` is a
+ * string; each path the patch writes is refused with `strayWriteRefusal(path, cwd)` in order if it
+ * is under the team root but outside the worktree, a relative path resolving from `cwd` as
+ * codex resolves it. A payload naming no `cwd`, or too broken to read, returns null and the patch
+ * runs. */
+export function codexWriteRefusal(payload) {
+    if (typeof payload !== "object" || payload === null)
+        return null;
+    const { tool_name: tool, tool_input: input, cwd } = payload;
+    if (tool !== APPLY_PATCH)
+        return null;
+    if (typeof cwd !== "string" || cwd === "")
+        return null;
+    if (typeof input !== "object" || input === null)
+        return null;
+    const command = input.command;
+    if (typeof command !== "string")
+        return null;
+    for (const target of patchWritePaths(command)) {
+        const refusal = strayWriteRefusal(target, cwd);
+        if (refusal !== null)
+            return refusal;
+    }
+    return null;
+}
+/** Seconds codex waits for the hook before running the tool anyway (the same timeout claude's
+ * hook gets). */
+const HOOK_TIMEOUT_SECONDS = 30;
+/** The matcher the PreToolUse hook is registered with; codex sends only `apply_patch` here. */
+const HOOK_MATCHER = "^apply_patch$";
+/** `s` as a TOML basic string, escaping `\`, `"` and every control character (U+0000–U+001F
+ * and DEL), so a nodeBin or hook path with any of them still round-trips through a `-c` value. */
+export function tomlString(s) {
+    let out = '"';
+    for (const ch of s) {
+        const code = ch.codePointAt(0);
+        if (ch === "\\")
+            out += "\\\\";
+        else if (ch === '"')
+            out += '\\"';
+        else if (code < 0x20 || code === 0x7f)
+            out += `\\u${code.toString(16).padStart(4, "0")}`;
+        else
+            out += ch;
+    }
+    return out + '"';
+}
+/** The codex write guard's definition: the PreToolUse hook on `apply_patch` that runs the
+ * compiled write-guard-hook.js with this process's node, falling back to `node` on PATH when
+ * that binary has moved (as claude's and the notes shim do). The hook path resolves from this
+ * module, so a staged build (.tumwater/build/<sha>) runs its own copy and gets its own hash. */
+export function codexWriteGuardDefinition(nodeBin = process.execPath) {
+    const hook = fileURLToPath(new URL("./write-guard-hook.js", import.meta.url));
+    const command = `n=${shellQuote(nodeBin)}; [ -x "$n" ] || n=node; exec "$n" ${shellQuote(hook)}`;
+    return { matcher: HOOK_MATCHER, command, timeout: HOOK_TIMEOUT_SECONDS };
+}
+/** The `-c` value that installs `definition` as the session's PreToolUse hook, in codex's
+ * `hooks.PreToolUse=[{matcher=…,hooks=[{type="command",command=…,timeout=…}]}]` inline-table
+ * shape (finding 1). */
+export function codexHookArg(definition) {
+    return `hooks.PreToolUse=[{matcher=${tomlString(definition.matcher)},hooks=[{type="command",command=${tomlString(definition.command)},timeout=${definition.timeout}}]}]`;
+}
+/** The `-c` value that trusts the hook identified by `trust.key` at `trust.hash`, in the
+ * inline-table spelling `hooks.state={<key>={trusted_hash=<hash>}}`. The dotted
+ * `hooks.state."<key>".trusted_hash=` spelling is ignored by codex because the key contains
+ * dots (finding 2). */
+export function codexHookTrustArg(trust) {
+    return `hooks.state={${tomlString(trust.key)}={trusted_hash=${tomlString(trust.hash)}}}`;
+}

package/dist/src/agent/codex/write-guard-hook.js

@@ -0,0 +1,12 @@
+/** The PreToolUse hook codex runs before each `apply_patch` in a team run (part 6/9 installs it
+ * through `-c`): `node write-guard-hook.js` with codex's hook payload on stdin. To block the patch
+ * it prints a `deny` decision with the refusal as its reason, in the shape finding 5 showed codex
+ * accepts: the model reads only the reason, so a denial by exit code would not carry it. It prints
+ * nothing to let the patch run, and exits 0 either way. Any failure of its own (bad JSON, a throw)
+ * prints nothing, so a broken hook lets the patch run and the stray-write warning in runner-run.ts
+ * still sees a stray write. The stdin read and the deny-decision printing are runGuardHook's
+ * (src/agent/write-guard.ts), shared with the claude PreToolUse hook; only the refusal computation
+ * differs. */
+import { runGuardHook } from "../write-guard.js";
+import { codexWriteRefusal } from "./codex-write-guard.js";
+runGuardHook((payload) => codexWriteRefusal(payload));

package/dist/src/agent/image-input.js

@@ -9,34 +9,37 @@ import { BORROW_ORDER, resolveTierFallbacks } from "../config/config-fallbacks.j
 import { seamAgent } from "../config/model-selector.js";
 import { modelLabel } from "./backend-traits.js";
 import { piModelImageInput, piPairFree, piModelsPath, readPiProviders } from "../pi/pi-models.js";
-import { agentBackend } from "./agent-backend.js";
+import { piListedImageInput } from "../pi/pi-listed-models.js";
+import { backendById } from "./agent-backend.js";
 import { imageProbeEntryFresh, imageProbeKey } from "../doctor/image-probe.js";
 /** One seam's image-input capability (plans/image-input.md "Capability"): `true` when the
  * seam's backend declares image support, `false` when it is text-only, `null` when it cannot
- * be answered from what the team knows (an unknown pair, a backend with no hook and no
- * catalog entry — the doctor's `tier models` check already fails such pairs).
+ * be answered from what the team knows (a pair neither models.json nor the pi listing names, a
+ * backend with no hook and no catalog entry).
  *
  * The backend bookends: a backend with an `imageInput` hook (claude → true) owns the answer;
  * the default pi backend leaves it to models.json's `input` field, where absent means text-only
- * (pi's own default for a custom model). `probes` is the doctor's live-probe cache (part 2/5): a
- * claimed pi seam whose probe FAILED reads false — a claim is only as good as the verified
+ * (pi's own default for a custom model); a pair absent from models.json answers what
+ * `pi --list-models` last said (src/pi/pi-listed-models.ts), else null.
+ * `probes` is the doctor's live-probe cache (part 2/5): a claimed pi seam whose probe FAILED
+ * reads false — a claim is only as good as the verified
  * answer — while a cached pass (or an unprobed claim) stands on the catalog. claude seams are
  * never probed, so the hook answer is never overridden. */
-export function seamImageInput(seam, providers, probes) {
-    const agent = seamAgent(seam);
-    const backend = agentBackend(agent);
+export function seamImageInput(seam, providers, probes, listed = null) {
+    const backendId = seamAgent(seam);
+    const backend = backendById(backendId);
     // A backend with an imageInput hook owns the answer outright (claude: true for every model).
     if (backend?.imageInput !== undefined)
         return backend.imageInput(seam.model);
     // An unknown backend without a hook has no catalog to consult — unknown, never assume.
-    if (agent !== "pi")
+    if (backendId !== "pi")
         return null;
-    const base = piModelImageInput(providers, seam.provider, seam.model);
+    const base = piModelImageInput(providers, seam.provider, seam.model) ?? piListedImageInput(listed, seam.provider, seam.model);
     if (base !== true)
         return base;
     // A claimed pi seam whose live probe failed (fresh, claim unchanged) reads false. Only pi is
-    // probed, so the probe key carries the pi agent.
-    const entry = probes?.[imageProbeKey(agent, seam.provider, seam.model)];
+    // probed, so the probe key carries the pi backend.
+    const entry = probes?.[imageProbeKey(backendId, seam.provider, seam.model)];
     if (entry?.verdict === "fail" && imageProbeEntryFresh(entry))
         return false;
     return true;
@@ -48,13 +51,13 @@ export function seamImageInput(seam, providers, probes) {
  * and takes the first tier whose model reads images. `regime` picks the pair set (see
  * RerouteRegime); `modelsPath` and `account` are injectable so tests need no real pi install
  * or account. */
-export function imageReroute(config, role, regime = "primary", modelsPath = piModelsPath(), account = null, probes, providers = null) {
+export function imageReroute(config, role, regime = "primary", modelsPath = piModelsPath(), account = null, probes, providers = null, listed = null) {
     const tier = roleSeamTier(config, role);
     const candidates = BORROW_ORDER[tier].filter((t) => t !== tier);
     if (candidates.length === 0)
         return null;
     const providerMap = providers ?? readPiProviders(modelsPath);
-    const capable = (rc) => seamImageInput(rc, providerMap, probes) === true;
+    const capable = (rc) => seamImageInput(rc, providerMap, probes, listed) === true;
     if (regime === "primary") {
         for (const t of candidates) {
             const rc = withModelOverrides(config, t, {});
@@ -65,7 +68,9 @@ export function imageReroute(config, role, regime = "primary", modelsPath = piMo
     }
     // Fallback regime: only the tiers' free fallback pairs qualify (resolveTierFallbacks over the
     // price check), never a priced primary model — a reroute must not spend past the cap.
-    const resolved = resolveTierFallbacks(config, (p) => piPairFree(providerMap, p.provider, p.model, account));
+    const resolved = resolveTierFallbacks(config, (p) => 
+    // The free-ness lookup reads the one claude account held here (part 2a/9).
+    piPairFree(providerMap, p, (b) => (b === "claude" ? account : null)));
     for (const t of candidates) {
         const pair = resolved[t].pair;
         if (!pair)
@@ -81,25 +86,25 @@ export function imageReroute(config, role, regime = "primary", modelsPath = piMo
     return null;
 }
 /** The config of imageReroute, for callers that want only the target model. */
-export function imageRerouteTarget(config, role, regime = "primary", modelsPath = piModelsPath(), account = null, probes, providers = null) {
-    return imageReroute(config, role, regime, modelsPath, account, probes, providers)?.config ?? null;
+export function imageRerouteTarget(config, role, regime = "primary", modelsPath = piModelsPath(), account = null, probes, providers = null, listed = null) {
+    return imageReroute(config, role, regime, modelsPath, account, probes, providers, listed)?.config ?? null;
 }
 /** A seam's model as one readable token, the same label the doctor's `image input` check uses
  * (`claude/<id>` for a claude seam, `provider/model` for pi). The one home of the label, so
  * the surface strings (the images alert, the role page, the status rows) and the doctor report
  * cannot drift, and delegates to backend-traits' modelLabel. */
-export function seamImageLabel(agent, provider, model) {
-    return modelLabel(agent, provider, model);
+export function seamImageLabel(backend, provider, model) {
+    return modelLabel(backend, provider, model);
 }
-/** Compute RoleImageInfo for one loop. `modelsPath` and `probes` are injectable; the providers
+/** Compute RoleImageInfo for one role. `modelsPath` and `probes` are injectable; the providers
  * catalog is read (stat-cached) here and also handed to imageReroute so a poll that asks many
- * loops still parses the catalog once. All reads mirror the doctor's `image input` check, so
+ * roles still parses the catalog once. All reads mirror the doctor's `image input` check, so
  * the surface and the check agree about capability. */
-export function roleImageInfo(config, role, modelsPath = piModelsPath(), probes) {
+export function roleImageInfo(config, role, modelsPath = piModelsPath(), probes, listed = null) {
     const providers = readPiProviders(modelsPath);
     const rc = configForRole(config, role);
-    const imageInput = seamImageInput(rc, providers, probes);
-    const rr = imageReroute(config, role, "primary", modelsPath, null, probes, providers);
+    const imageInput = seamImageInput(rc, providers, probes, listed);
+    const rr = imageReroute(config, role, "primary", modelsPath, null, probes, providers, listed);
     const imageRerouteStr = rr
         ? `${rr.tier} (${seamImageLabel(rr.config.agent, rr.config.provider, rr.config.model)})`
         : null;

package/dist/src/agent/notes-shim.js

@@ -1,8 +1,7 @@
-// vocabulary: plain
 /** Installing the per-team `tumwater-notes` shim every backend's run finds on its PATH
  * (plans/notes-command.md "Reaching it from a run"): run-agent calls `ensureNotesShim(root)`
  * before building each invocation, and the backend prepends the returned dir to the run's
- * PATH (agentBaseEnv's `binDir`, src/process/run-marker.ts). The shim is a two-line `sh`
+ * PATH (backendBaseEnv's `binDir`, src/process/run-marker.ts). The shim is a two-line `sh`
  * script that execs the compiled notes CLI, so a model's shell — pi's, Claude Code's or
  * OpenCode's — runs the same command on every backend.
  *
@@ -14,7 +13,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { distDir } from "../build/build-info.js";
-import { writeTextAtomic } from "../files/files.js";
+import { readTextOrNull, writeTextAtomic } from "../files/files.js";
 import { notesShimDir } from "../paths.js";
 /** The shim's file name — the command name every run sees on its PATH. */
 export const NOTES_SHIM_NAME = "tumwater-notes";
@@ -22,17 +21,17 @@ export const NOTES_SHIM_NAME = "tumwater-notes";
  * The shim is written atomically with mode 0755, only when its content differs from what is
  * already there (a redeploy that changes `<dist>` rewrites it). Never throws: a failure to
  * write is the caller's to absorb — run-agent logs one warning and runs without the shim. */
-export function ensureNotesShim(root) {
+export function ensureNotesShim(root, execPath = process.execPath) {
     const dir = notesShimDir(root);
     const target = path.join(dir, NOTES_SHIM_NAME);
-    const content = `#!/bin/sh\nexec "${process.execPath}" "${path.join(distDir(), "src", "notes-cli.js")}" "$@"\n`;
-    let needsWrite = true;
-    try {
-        needsWrite = fs.readFileSync(target, "utf8") !== content;
-    }
-    catch {
-        // Absent or unreadable — write it.
-    }
+    // Prefer the recorded node binary, falling back to `node` on PATH when it is gone — a
+    // Homebrew node upgrade under the running team deletes the old keg while the team keeps
+    // running on it, so `process.execPath` names a file that no longer exists (BUGS.md
+    // 2026-10-21). The `[ -x "$n" ]` check answers at run time, so a shim written long ago
+    // still survives an upgrade, and the running orchestrator's repeated rewrites stop
+    // restoring the broken path.
+    const content = `#!/bin/sh\nn="${execPath}"; [ -x "$n" ] || n=node; exec "$n" "${path.join(distDir(), "src", "notes-cli.js")}" "$@"\n`;
+    const needsWrite = readTextOrNull(target) !== content; // absent or unreadable — write it
     if (needsWrite) {
         writeTextAtomic(target, content);
     }

package/dist/src/agent/opencode/opencode-args.js

@@ -1,4 +1,3 @@
-// vocabulary: plain
 /** Building one OpenCode run's command line (plans/opencode-backend.md "The invocation") —
  * pure argv construction plus the prompt-on-stdin pairing, with no subprocess, backend
  * registration, or session database. Part 5/7 wires this into the adapter; this module turns

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

@@ -1,4 +1,3 @@
-// vocabulary: plain
 /** The opencode adapter for the agent seam (plans/opencode-backend.md "The invocation",
  * "Sessions", §6). It shapes one run's argv/stdin/env, translates opencode's `run --format
  * json` into the canonical stream, runs the authoritative session export after the process
@@ -15,16 +14,17 @@
  * fresh id (design §4).
  *
  * Registration lives in src/agent/run-agent.ts beside the pi and claude adapters; a test selects
- * opencode by setting `config.agent = "opencode"` on a run. A run carrying a notebook gets the
+ * opencode by setting `config.agent = "opencode"` 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 { spawnSync } from "node:child_process";
 import os from "node:os";
 import path from "node:path";
+import { ensureParentDir } from "../../files/files.js";
 import { loadConfigSafe } from "../../config/config.js";
-import { resolvedAgentConfig } from "../../config/config-views.js";
-import { agentBaseEnv, withNotesPath } from "../../process/run-marker.js";
-import { resolveBackendBin } from "../../pi/pi-bin.js";
+import { resolvedBackendConfig } from "../../config/config-views.js";
+import { backendRunEnv } from "../../process/run-marker.js";
+import { resolveBinForBackend } from "../../pi/pi-bin.js";
 import { opencodeDbPath, teamRootOf } from "../../paths.js";
 import { resumableSession } from "../session-ledger.js";
 import { opencodeArgs } from "./opencode-args.js";
@@ -164,13 +164,15 @@ export const opencodeBackend = {
     defaultBin: "opencode",
     binEnv: "TUMWATER_OPENCODE_BIN",
     resolveBin(config) {
-        return resolveBackendBin(config, this);
+        return resolveBinForBackend(config, this);
     },
     invocation(run) {
         // The shared database and injected config are per-root, built the same way for every run of
         // this team so a resume's export check reads the same OPENCODE_DB the original run wrote.
         const root = teamRootOf(run.sessionDir);
         const dbPath = opencodeDbPath(root);
+        // opencode will not create the database's parent directory and its server dies without it.
+        ensureParentDir(dbPath);
         // Window-scaled tool-output caps (part 6f/7): OpenCode's `tool_output` default is about
         // three times pi's tuned budgets, so every turn would re-send far more tool output than a
         // pi run — critical on the 200K free model's window. Cap it at pi's `outputLimits(window)
@@ -184,10 +186,10 @@ export const opencodeBackend = {
             operatorMcpNames: operatorMcpNames(process.env, os.homedir()),
             toolOutput: { maxLines: Math.round(maxBytes / 40), maxBytes },
         });
-        // The notebook path rides beside the run marker, as the pi and claude adapters' envs do
+        // 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 OpenCode configures no tumwater MCP server for notes.
-        const base = withNotesPath(agentBaseEnv(run.runMarker, undefined, run.binDir), run.notesPath);
+        const base = backendRunEnv(run);
         const env = opencodeEnv(base, { dbPath, configContent });
         const { sessionId } = resolveOpencodeSession(run, env);
         // The thinking variant (part 6d/7): ride the catalog's effort levels for the resolved
@@ -202,7 +204,7 @@ export const opencodeBackend = {
             ...(variant !== undefined ? { variant } : {}),
             sessionId,
             title: run.sessionName,
-            args: resolvedAgentConfig(run.config, "opencode").args,
+            args: resolvedBackendConfig(run.config, "opencode").args,
             prompt: run.prompt,
         });
         return { args, stdin, env, sessionId };
@@ -226,6 +228,7 @@ export const opencodeBackend = {
             return false;
         const root = teamRootOf(dir);
         const dbPath = opencodeDbPath(root);
+        ensureParentDir(dbPath);
         const env = { ...process.env, OPENCODE_DB: dbPath };
         // Resolve the binary exactly as the run's invocation does — same env → backends.opencode.bin
         // → default precedence — so a configured custom binary's resume guard agrees with the

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

@@ -1,4 +1,3 @@
-// vocabulary: plain
 /** The data half of OpenCode free-ness (plans/opencode-backend.md §7; part 6a/7): a bounded
  * fetch of models.dev's `api.json` — the catalog OpenCode itself caches (finding 10) — a parse
  * that keeps only the providers the config routes through OpenCode, a cache at
@@ -8,7 +7,10 @@
  * part 7/7 (a startup-cache seed and doctor), so this module's only callers today are its own
  * tests. */
 import { spawnSync } from "node:child_process";
+import { isJsonObject, validEntries } from "../../files/json-object.js";
 import { readJsonFile, writeJsonAtomic } from "../../files/json-files.js";
+import { errorMessage } from "../../text/text.js";
+import { DAY_MS } from "../../text/datetime.js";
 import { opencodeModelsPath } from "../../paths.js";
 import { logEventBestEffort } from "../../events/events.js";
 import { opencodeQualifiedModel } from "./opencode-args.js";
@@ -18,7 +20,7 @@ const CATALOG_URL = "https://models.dev/api.json";
  * most once a day, so a slow or wedged network must not hold the team up. */
 const CATALOG_FETCH_TIMEOUT_MS = 30_000;
 /** How long a fetched cache is trusted before it is refreshed. */
-const CATALOG_CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+const CATALOG_CACHE_TTL_MS = DAY_MS;
 const defaultFetch = async (url, timeoutMs) => {
     const res = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
     if (!res.ok)
@@ -37,26 +39,25 @@ export async function fetchOpencodeCatalog(fetchFn = defaultFetch) {
  * the provider map at the top level; OpenCode's cached copy wraps that same map under a `body`
  * key (the 2.0.32 capture in test/fixtures), so both shapes are accepted. Each kept model is
  * keyed `<provider>/<model>`. A model never present yields no entry, so an unknown model is
- * automatically "not free" to opencodeModelFree. */
+ * automatically "not free" to opencodeModelFree. The body is untrusted network data: a malformed
+ * provider or model is skipped, never thrown on. */
 export function parseOpencodeCatalog(body, providers) {
     const out = {};
-    const root = body;
+    const root = isJsonObject(body) ? body : {};
     // models.dev's api.json IS the provider map; OpenCode's cached copy wraps that map under `body`.
-    const wrapped = root?.body;
-    const catalog = typeof wrapped === "object" && wrapped !== null && !Array.isArray(wrapped)
-        ? wrapped
-        : (body ?? {});
-    for (const [provider, providerRaw] of Object.entries(catalog)) {
+    const wrapped = root.body;
+    const catalog = isJsonObject(wrapped) ? wrapped : root;
+    for (const [provider, providerInfo] of Object.entries(catalog)) {
         if (provider !== "opencode" && !providers.includes(provider))
             continue;
-        const providerInfo = providerRaw;
-        if (providerInfo?.models === undefined)
+        if (!isJsonObject(providerInfo) || !isJsonObject(providerInfo.models))
             continue;
-        for (const [id, raw] of Object.entries(providerInfo.models)) {
-            const m = raw;
+        for (const [id, m] of Object.entries(providerInfo.models)) {
+            if (!isJsonObject(m))
+                continue;
             // Only a present cost block marks a model free: a missing cost block is unknown price data,
             // and treating it as $0 is the unsafe direction for a budget gate.
-            const cost = m?.cost;
+            const cost = isJsonObject(m.cost) ? m.cost : undefined;
             const input = cost?.input ?? 0;
             const output = cost?.output ?? 0;
             const model = { free: cost !== undefined && input === 0 && output === 0 };
@@ -64,16 +65,19 @@ export function parseOpencodeCatalog(body, providers) {
                 model.inputPerM = input;
                 model.outputPerM = output;
             }
-            if (m?.limit?.context !== undefined)
+            if (isJsonObject(m.limit) && m.limit.context !== undefined)
                 model.context = m.limit.context;
-            if (m?.modalities?.input !== undefined)
+            if (isJsonObject(m.modalities) && Array.isArray(m.modalities.input)) {
                 model.images = m.modalities.input.includes("image");
-            const efforts = m?.reasoning_options
-                ?.filter((r) => r.type === "effort")
-                .flatMap((r) => r.values ?? []);
-            if (efforts !== undefined && efforts.length > 0)
-                model.efforts = efforts;
-            out[`${provider}/${id}`] = model;
+            }
+            if (Array.isArray(m.reasoning_options)) {
+                const efforts = m.reasoning_options
+                    .flatMap((r) => isJsonObject(r) && r.type === "effort" && Array.isArray(r.values) ? r.values : []);
+                if (efforts.length > 0)
+                    model.efforts = efforts;
+            }
+            if (isOpencodeCatalogModel(model))
+                out[`${provider}/${id}`] = model;
         }
     }
     return out;
@@ -113,20 +117,32 @@ export function observeOpencodeRun(root, run, opts) {
     log({ source: opts.source, type: "opencode_free_model_billed", model: run.model, costUsd: run.costUsd });
     return cache;
 }
+function isOpencodeCatalogModel(value) {
+    if (!isJsonObject(value) || typeof value.free !== "boolean")
+        return false;
+    const numbers = [value.inputPerM, value.outputPerM, value.context, value.billedAt];
+    if (!numbers.every((n) => n === undefined || (typeof n === "number" && Number.isFinite(n))))
+        return false;
+    if (value.images !== undefined && typeof value.images !== "boolean")
+        return false;
+    return (value.efforts === undefined ||
+        (Array.isArray(value.efforts) && value.efforts.every((e) => typeof e === "string")));
+}
 /** Read the cached catalog, or an empty one (fetchedAt 0, no models) when the file is missing
  * or malformed — the harness's no-data policy, so a torn write reads as "needs a refresh".
  * Exported so the opencode backend's adapter (part 6d/7) and doctor can read the same cache
  * without triggering a network fetch. The synchronous read the sync poll surfaces
  * (pollBudgetGate, collectBudget) use to thread the catalog-cache into their free-ness reads
  * (part 6b/7); the async refresh (which runs once per process at the startup gate) is what
- * fills the file in. */
+ * fills the file in. Entries that are not well-formed catalog models are dropped, so a foreign
+ * entry reads as a model missing from the cache — not free. */
 export function readOpencodeCache(root) {
     const existing = readJsonFile(opencodeModelsPath(root));
-    if (existing !== null && typeof existing.fetchedAt === "number" && existing.models !== undefined && typeof existing.models === "object" && !Array.isArray(existing.models)) {
+    if (existing !== null && typeof existing.fetchedAt === "number" && isJsonObject(existing.models)) {
         return {
             fetchedAt: existing.fetchedAt,
             cliVersion: typeof existing.cliVersion === "string" ? existing.cliVersion : undefined,
-            models: existing.models,
+            models: validEntries(existing.models, isOpencodeCatalogModel),
         };
     }
     return { fetchedAt: 0, models: {} };
@@ -150,16 +166,21 @@ function readCliVersion(bin = "opencode") {
         return undefined;
     }
 }
+/** Whether the cache is missing or older than CATALOG_CACHE_TTL_MS at `now`. The age rule
+ * refreshOpencodeCatalog and the poll-driven refresh (newOpencodeCatalogRefresh) share. */
+export function opencodeCatalogStale(cache, now) {
+    return cache.fetchedAt === 0 || now - cache.fetchedAt >= CATALOG_CACHE_TTL_MS;
+}
 /** Return a cache fresh enough to price by, fetching and persisting when the current one is
  * missing, stale (older than 24 h) or fetched by a different `opencode --version`. A failed
  * fetch keeps the old cache (logging one warning) so the team still prices by the last good
- * data; `billedAt` from the old cache survives a successful refresh (part 6c/7). */
+ * data; `billedAt` from the old cache survives a successful refresh (part 6c/7). A failed cache
+ * write warns and returns the fetched catalog, so the next start fetches again. */
 export async function refreshOpencodeCatalog(root, opts) {
     const now = opts.now !== undefined ? opts.now() : Date.now();
     const version = opts.cliVersion !== undefined ? opts.cliVersion : readCliVersion(opts.cliBin);
     const current = readOpencodeCache(root);
-    const fresh = current.fetchedAt !== 0 &&
-        now - current.fetchedAt < CATALOG_CACHE_TTL_MS &&
+    const fresh = !opencodeCatalogStale(current, now) &&
         (version === undefined || current.cliVersion === version);
     if (fresh)
         return current;
@@ -179,6 +200,11 @@ export async function refreshOpencodeCatalog(root, opts) {
             fresh.billedAt = old.billedAt;
     }
     const cache = { fetchedAt: now, cliVersion: version, models: parsed };
-    writeOpencodeCache(root, cache);
+    try {
+        writeOpencodeCache(root, cache);
+    }
+    catch (err) {
+        opts.warn?.(`could not save the open code model catalog: ${errorMessage(err)}`);
+    }
     return cache;
 }

package/dist/src/agent/opencode/opencode-config.js

@@ -1,12 +1,12 @@
-// vocabulary: plain
 /** Building one OpenCode run's injected config (`OPENCODE_CONFIG_CONTENT`) (plans/opencode-
  * backend.md "The invocation") — pure JSON construction, with no subprocess. The config
  * applies after the operator's global and project files, so only managed config wins over it:
  * the gate-safe isolation switches (snapshots off, updates off, six denials), `enabled →
  * disabled: true` for every operator MCP server (config merges, so disabling is the only way
- * to remove one), and an `instructions` entry mirroring claude's AGENTS.md handling. No
- * tool is disabled beyond the six gate-safe denials — denying `read` trips the free-tier gate
- * (finding 11). Part 5/7 wires this string into the run's environment.
+ * to remove one), an `instructions` entry mirroring claude's AGENTS.md handling, and tumwater's
+ * write-guard plugin (write-guard-plugin/index.ts), which refuses a write outside the run's
+ * worktree. No tool is disabled beyond the six gate-safe denials — denying `read` trips the
+ * free-tier gate (finding 11). Part 5/7 wires this string into the run's environment.
  *
  * From part 3/4 tumwater no longer adds an MCP server of its own: run notes ride the
  * `tumwater-notes` command on PATH, so every operator MCP server is disabled alike — an
@@ -17,6 +17,9 @@
  * here, and doctor reports it in part 7/7. */
 import fs from "node:fs";
 import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { readTextOrNull } from "../../files/files.js";
+import { isJsonObject } from "../../files/json-object.js";
 /** The operator's global opencode config lives in `$XDG_CONFIG_HOME/opencode/` (or
  * `~/.config/opencode/`), in `config.json`, `opencode.json` or `opencode.jsonc`. */
 const OPERATOR_CONFIG_FILES = ["config.json", "opencode.json", "opencode.jsonc"];
@@ -123,13 +126,9 @@ export function operatorMcpNames(env, homeDir) {
     const configHome = env.XDG_CONFIG_HOME ?? path.join(homeDir, ".config");
     const dir = path.join(configHome, "opencode");
     for (const file of OPERATOR_CONFIG_FILES) {
-        let text;
-        try {
-            text = fs.readFileSync(path.join(dir, file), "utf8");
-        }
-        catch {
+        const text = readTextOrNull(path.join(dir, file));
+        if (text === null)
             continue;
-        }
         let parsed;
         try {
             parsed = JSON.parse(file.endsWith(".jsonc") ? stripJsonc(text) : text);
@@ -138,13 +137,11 @@ export function operatorMcpNames(env, homeDir) {
             return [];
         }
         const mcp = parsed?.mcp;
-        if (mcp === undefined || mcp === null)
-            return [];
-        if (typeof mcp !== "object" || Array.isArray(mcp))
+        if (!isJsonObject(mcp))
             return [];
         const names = new Set();
         const servers = mcp.servers;
-        if (typeof servers === "object" && servers !== null && !Array.isArray(servers)) {
+        if (isJsonObject(servers)) {
             for (const key of Object.keys(servers))
                 names.add(key);
         }
@@ -163,6 +160,13 @@ export function operatorMcpNames(env, homeDir) {
 function shouldInjectClaudeMd(cwd) {
     return fs.existsSync(path.join(cwd, "CLAUDE.md")) && !fs.existsSync(path.join(cwd, "AGENTS.md"));
 }
+/** The write-guard plugin's `plugins` entry: a `file://` URL of the directory holding its
+ * compiled `index.js`, since OpenCode 2.x loads a configured plugin path only as a directory.
+ * Resolved from this module, so a staged build (.tumwater/build/<sha>) loads its own copy. */
+export function writeGuardPluginEntry() {
+    const entry = fileURLToPath(new URL("./write-guard-plugin/index.js", import.meta.url));
+    return pathToFileURL(path.dirname(entry)).href;
+}
 /** Build the injected opencode config JSON string. Never reads the worktree beyond the
  * CLAUDE.md/AGENTS.md probe. */
 export function opencodeConfigContent(opts) {
@@ -170,6 +174,7 @@ export function opencodeConfigContent(opts) {
         snapshots: false,
         update: "disable",
         permissions: DENIED_PERMISSIONS,
+        plugins: [writeGuardPluginEntry()],
     };
     if (opts.toolOutput !== undefined) {
         config.tool_output = { max_lines: opts.toolOutput.maxLines, max_bytes: opts.toolOutput.maxBytes };

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

@@ -1,4 +1,3 @@
-// vocabulary: plain
 /** Building the environment for one opencode run (plans/opencode-backend.md "The invocation")
  * — pure scrub-and-set over a base environment, with no subprocess. The caller layers the
  * run-marker and the macOS preload on first (claude's adapter shows the pie pattern), then

package/dist/src/agent/opencode/opencode-session-id.js

@@ -1,4 +1,3 @@
-// vocabulary: plain
 /** Minting an OpenCode session id (plans/opencode-backend.md "Sessions", finding 3) — a pure
  * reproduction of OpenCode's `Identifier.descending()` (packages/schema/src/identifier.ts), so
  * a fresh run's `--session` id is accepted by the free-tier gate. A `ses_…` id in any other
@@ -12,7 +11,7 @@ import crypto from "node:crypto";
 const ALPHABET = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
 /** Per-process minting state, mirroring OpenCode's per-millisecond counter: the counter
  * restarts at 1 for each new millisecond, and increments within the same millisecond so two
- * ids minted in one tick still differ in their hex. */
+ * ids minted in one millisecond still differ in their hex. */
 let lastMintMs = -1;
 let counter = 0;
 /** Mint an OpenCode session id. `now` is a Unix-millisecond epoch (injected for tests);

package/dist/src/agent/opencode/opencode-stream.js

@@ -251,7 +251,7 @@ export function opencodeTranslator(opts = {}) {
  * the run's real cost and token totals. Anything malformed returns `[]`; part 5/7 logs
  * `opencode_usage_partial` when this is empty. */
 export function opencodeExportLines(exportJson) {
-    if (typeof exportJson !== "object" || exportJson === null || Array.isArray(exportJson))
+    if (!isJsonObject(exportJson))
         return [];
     const info = exportJson.info;
     if (typeof info !== "object" || info === null)