tumwater 0.1.2 → 0.2.0

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

@@ -0,0 +1,255 @@
+// 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
+ * 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; opencode mints its own session id
+ * (a `ses_…` id, or the resumed record's id), which `invocation` returns so the ledger can
+ * carry it.
+ *
+ * Sessions resume by id from the cwd the session started in, out of the run's shared database
+ * (opencodeDbPath). A continue takes the ledger's newest record of this run's kind and resumes
+ * only when it is opencode's, has this cwd, and `opencode session export <id> --standalone`
+ * actually finds it — `--session` silently creates a missing session, so the existence check is
+ * the only thing that stops a follow-up running against an empty session. Anything else mints a
+ * 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
+ * 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 { 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 { opencodeDbPath, teamRootOf } from "../../paths.js";
+import { resumableSession } from "../session-ledger.js";
+import { opencodeArgs } from "./opencode-args.js";
+import { opencodeConfigContent, operatorMcpNames } from "./opencode-config.js";
+import { outputLimits } from "../../pi-extension/bounded-output.js";
+import { seamContextWindow } from "../../pi/pi-models.js";
+import { opencodeModelKey, readOpencodeCache } from "./opencode-catalog.js";
+import { opencodeEnv } from "./opencode-env.js";
+import { mintOpencodeSessionId } from "./opencode-session-id.js";
+import { opencodeExportLines, opencodeTranslator } from "./opencode-stream.js";
+/** How long a post-run `opencode session export` may take before it gives up (design §6): the
+ * export measured 0.18 s live, so 10 s is a generous bound on a slow or wedged CLI. Used for
+ * both the resume-existence check and the reconciling export. */
+const EXPORT_TIMEOUT_MS = 10_000;
+/** The minimum OpenCode CLI version this harness accepts (plans/opencode-backend.md "Which
+ * OpenCode", part 7/7): 2.0.32, the version H1 verified live. V1 is maintenance-only and has
+ * the git-repo hang (issue 55037), so doctor fails an installed CLI below this and names
+ * `brew install opencode`. */
+export const OPENCODE_MIN_VERSION = "2.0.32";
+/** The repository's root (initial) commit hash, or undefined when git cannot answer (not a
+ * repo, or git missing). `git rev-list --max-parents=0 HEAD` is the same read OpenCode makes
+ * to key its shell spill by the tree's root commit. Read-only. */
+function rootCommitOf(root) {
+    try {
+        const res = spawnSync("git", ["-C", root, "rev-list", "--max-parents=0", "HEAD"], {
+            encoding: "utf8",
+            timeout: 5_000,
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        const line = res.stdout?.trim();
+        return line !== undefined && /^[0-9a-f]{40}$/i.test(line) ? line : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The tree's shell spill dir OpenCode writes (finding 17, part 7/7):
+ * `~/.local/share/opencode/shell/<root commit>/`, keyed by the repository's root commit hash and
+ * OUTSIDE `.tumwater/`, so only a `session delete` or an explicit spill prune reaches it. Empty
+ * string when the root commit cannot be read — callers then skip spill work (doctor reports no
+ * spill dir; retention prunes no spill files). */
+export function opencodeSpillDir(root) {
+    const commit = rootCommitOf(root);
+    if (commit === undefined)
+        return "";
+    return path.join(os.homedir(), ".local", "share", "opencode", "shell", commit);
+}
+/** The catalog cache key for a run's resolved model id (part 6d/7): a bare gateway id gets the
+ * `opencode/` provider prefix, a provider-qualified id passes as is — the same rule
+ * opencodeArgs uses to build the `--model` arg and opencode-catalog.ts uses to key the cache,
+ * so an invocation's lookup always matches the key a run is priced and billed by. */
+function catalogModelKey(model) {
+    return opencodeModelKey(model);
+}
+/** Run `opencode session export <id> --standalone` (the same database the run used, bounded at
+ * 10 s) and return whether it reported success — the existence check that decides a resume.
+ * Nonzero exit, a timeout, or a spawn failure all read as "no such session", which is the safe
+ * direction: `--session` would otherwise silently create a missing session. */
+function opencodeSessionExists(id, env, bin, cwd) {
+    try {
+        const res = spawnSync(bin, ["session", "export", id, "--standalone"], {
+            env,
+            cwd,
+            timeout: EXPORT_TIMEOUT_MS,
+            stdio: "ignore",
+        });
+        return res.status === 0;
+    }
+    catch {
+        return false;
+    }
+}
+/** Run the reconciling export after a successful run and return its two canonical lines
+ * (`run_cost`, `run_usage`) from the session's `info`. Anything that goes wrong — a spawn or
+ * timeout, a nonzero exit, unparseable or malformed output — returns `[]`, and the caller
+ * (afterRun) reports `opencode_usage_partial` so the run keeps its streamed numbers. */
+function opencodeExport(result) {
+    let res;
+    try {
+        res = spawnSync(result.bin, ["session", "export", result.id, "--standalone"], {
+            env: result.env,
+            cwd: result.cwd,
+            timeout: EXPORT_TIMEOUT_MS,
+            encoding: "utf8",
+        });
+    }
+    catch {
+        return [];
+    }
+    if (res.status !== 0 || !res.stdout)
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(res.stdout);
+    }
+    catch {
+        return [];
+    }
+    return opencodeExportLines(parsed);
+}
+/** The session id this run uses: for a continue, the ledger's newest record of this kind when it
+ * is opencode's, has this cwd, and the export finds the session; otherwise a freshly minted id.
+ * Returns the id; the runner records it in the ledger. */
+function resolveOpencodeSession(run, env) {
+    if (run.continueSession) {
+        const record = resumableSession(run.sessionDir, {
+            kind: run.kind,
+            agent: "opencode",
+            cwd: run.cwd,
+        });
+        if (record !== null && opencodeSessionExists(record.id, env, run.agentBin, run.cwd)) {
+            return { sessionId: record.id };
+        }
+    }
+    return { sessionId: mintOpencodeSessionId() };
+}
+/** Classify opencode's stderr: on a nonzero exit, a free-tier refusal is a provider failure
+ * (moves the job to its fallback) and an unknown model or variant is a permanent config error.
+ * A run the harness killed has its own cause and is never classified here. The structured
+ * signals (the stream's `error` lines) are classified by the translator; this is the stderr
+ * half for a CLI that died before emitting one. */
+function classifyOpencodeExit(info) {
+    if (info.killed)
+        return {};
+    if (info.code !== 0 && /FreeTierError/i.test(info.stderr)) {
+        return { transientBackend: true, backendKind: "server" };
+    }
+    if (info.code !== 0 && /Model unavailable|Variant unavailable/i.test(info.stderr)) {
+        return { configError: true };
+    }
+    return {};
+}
+/** The agent-backend seam's opencode adapter. */
+export const opencodeBackend = {
+    id: "opencode",
+    label: "OpenCode",
+    defaultBin: "opencode",
+    binEnv: "TUMWATER_OPENCODE_BIN",
+    resolveBin(config) {
+        return resolveBackendBin(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);
+        // 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)
+        // .bash` (16,000 at 128k and above, scaled down below), with the ~40 chars/line line cap
+        // pi's "12k chars ≈ 300 lines" read budget implies. An unknown window (no catalog entry)
+        // keeps the 128k values. The window is part 6e/7's `seamContextWindow` for this run's
+        // model.
+        const maxBytes = outputLimits(seamContextWindow({ agent: "opencode", model: run.config.model }, root)).bash;
+        const configContent = opencodeConfigContent({
+            cwd: run.cwd,
+            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
+        // (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 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
+        // model as a `#level` suffix, and drop a level the catalog does not list — an unlisted
+        // variant would otherwise be a permanent config error from OpenCode (finding 9).
+        const model = run.config.model ?? "";
+        const thinking = run.config.thinking;
+        const entry = readOpencodeCache(root).models[catalogModelKey(model)];
+        const variant = thinking !== undefined && thinking !== "" && entry?.efforts?.includes(thinking) ? thinking : undefined;
+        const { args, stdin } = opencodeArgs({
+            model,
+            ...(variant !== undefined ? { variant } : {}),
+            sessionId,
+            title: run.sessionName,
+            args: resolvedAgentConfig(run.config, "opencode").args,
+            prompt: run.prompt,
+        });
+        return { args, stdin, env, sessionId };
+    },
+    translator() {
+        return opencodeTranslator();
+    },
+    imageInput(model) {
+        // Answer from the catalog cache (part 6d/7): a model reads images when its catalog entry
+        // says so; a model missing from the cache answers false — the safe direction, so a blind
+        // image read is never silently assumed readable. The cache is per-root, found by walking up
+        // from the process's working directory to its `.tumwater`, the same root the runs' shared
+        // database and cache live under.
+        if (model === undefined)
+            return false;
+        return readOpencodeCache(teamRootOf(process.cwd())).models[catalogModelKey(model)]?.images === true;
+    },
+    resumable(dir, opts) {
+        const record = resumableSession(dir, { kind: opts.kind, agent: "opencode", cwd: opts.cwd });
+        if (record === null)
+            return false;
+        const root = teamRootOf(dir);
+        const dbPath = opencodeDbPath(root);
+        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
+        // `run.agentBin` the invocation runs (they must not disagree, or a follow-up is silently
+        // skipped). The team's config is loaded from the root `dir` lives under.
+        const { config } = loadConfigSafe(root);
+        const bin = config !== undefined ? opencodeBackend.resolveBin(config).bin : "opencode";
+        return opencodeSessionExists(record.id, env, bin, opts.cwd ?? path.dirname(dir));
+    },
+    afterRun(run, invocation, translator) {
+        if (invocation.sessionId === undefined)
+            return [];
+        const lines = opencodeExport({
+            id: invocation.sessionId,
+            env: invocation.env,
+            bin: run.agentBin,
+            cwd: run.cwd,
+        });
+        if (lines.length === 0) {
+            // The export is authoritative, so its loss is worth one warning: the run keeps its
+            // streamed numbers and the caller surfaces `opencode_usage_partial` in the event feed.
+            translator.noteOpencodeUsagePartial();
+        }
+        return lines;
+    },
+    classifyExit: classifyOpencodeExit,
+};

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

@@ -0,0 +1,184 @@
+// 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
+ * `.tumwater/state/opencode-models.json` that survives a failed fetch, and
+ * `opencodeModelFree` as the one predicate part 6b/7's seam reads. No seam is wired here: that
+ * is part 6b/7 (the budget gate), part 6c/7 (a billedAt demotion on an observed cost) and
+ * 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 { readJsonFile, writeJsonAtomic } from "../../files/json-files.js";
+import { opencodeModelsPath } from "../../paths.js";
+import { logEventBestEffort } from "../../events/events.js";
+import { opencodeQualifiedModel } from "./opencode-args.js";
+/** models.dev's catalog, the data OpenCode caches in its database `kv` table (finding 10). */
+const CATALOG_URL = "https://models.dev/api.json";
+/** The fetch bound (finding 10; the plan's 30 s): OpenCode prices from the same endpoint at
+ * 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 defaultFetch = async (url, timeoutMs) => {
+    const res = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
+    if (!res.ok)
+        throw new Error(`models.dev catalog ${res.status} ${res.statusText}`);
+    return res.json();
+};
+/** GET models.dev's catalog, bounded at 30 s. Returns the parsed JSON body, or the injected
+ * (or default) fetch throws on a failure. So a spare `opencode` binary is never needed just to
+ * cable this up; the version check that forces a refresh lives in refreshOpencodeCatalog. */
+export async function fetchOpencodeCatalog(fetchFn = defaultFetch) {
+    return fetchFn(CATALOG_URL, CATALOG_FETCH_TIMEOUT_MS);
+}
+/** Parse models.dev's `api.json` into the models the config routes through OpenCode: always the
+ * `opencode` provider, plus every provider named in `providers` (the config's
+ * `opencode/<provider>/…` routes — `opencode-go` and so on). The live `GET /api.json` returns
+ * 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. */
+export function parseOpencodeCatalog(body, providers) {
+    const out = {};
+    const root = 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)) {
+        if (provider !== "opencode" && !providers.includes(provider))
+            continue;
+        const providerInfo = providerRaw;
+        if (providerInfo?.models === undefined)
+            continue;
+        for (const [id, raw] of Object.entries(providerInfo.models)) {
+            const m = raw;
+            // 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 input = cost?.input ?? 0;
+            const output = cost?.output ?? 0;
+            const model = { free: cost !== undefined && input === 0 && output === 0 };
+            if (cost !== undefined) {
+                model.inputPerM = input;
+                model.outputPerM = output;
+            }
+            if (m?.limit?.context !== undefined)
+                model.context = m.limit.context;
+            if (m?.modalities?.input !== undefined)
+                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;
+        }
+    }
+    return out;
+}
+/** True when the catalog says the model is free and no run has marked it billed (part 6c/7).
+ * A model missing from the cache, a priced one, and a free one with `billedAt` set are all not
+ * free — the safe direction for a budget gate. */
+export function opencodeModelFree(cache, model) {
+    const entry = cache.models[model];
+    return entry !== undefined && entry.free && entry.billedAt === undefined;
+}
+/** The catalog cache key for an opencode run's resolved selector: the `<provider>/<model>`
+ * form part 6a/7 keys the cache by. Delegates the bare-gateway-prefix rule to
+ * opencode-args.ts's opencodeQualifiedModel (the single home), so the key a run is priced by
+ * always matches the id a run is invoked by. */
+export function opencodeModelKey(selector) {
+    return opencodeQualifiedModel(selector);
+}
+/** Demote a catalog-free model the moment a run bills it (part 6c/7): when a run reports a
+ * nonzero cost on a model the cache calls free, mark that entry priced (`billedAt`) in the
+ * cache and log `opencode_free_model_billed` {model, costUsd} once. A subsequent priced run on
+ * the same model sees `billedAt` already set and stays silent, and the next
+ * `opencodeModelFree` answer for it is false. A run reporting $0, a priced model, or an
+ * unknown model leaves the cache untouched — a $0 run never demotes (missing and priced
+ * models are already "not free" to opencodeModelFree). Best-effort like observeClaudeAccount:
+ * the caller wraps the write/log in try/catch so an unwritable cache or feed never fails the
+ * run that observed it. Returns the cache after the observation, or null when nothing changed. */
+export function observeOpencodeRun(root, run, opts) {
+    const cache = readOpencodeCache(root);
+    const entry = cache.models[run.model];
+    if (entry === undefined || !entry.free || entry.billedAt !== undefined || run.costUsd <= 0) {
+        return null;
+    }
+    entry.billedAt = opts.now !== undefined ? opts.now() : Date.now();
+    writeOpencodeCache(root, cache);
+    const log = opts.log !== undefined ? opts.log : (e) => logEventBestEffort(root, e);
+    log({ source: opts.source, type: "opencode_free_model_billed", model: run.model, costUsd: run.costUsd });
+    return cache;
+}
+/** 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. */
+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)) {
+        return {
+            fetchedAt: existing.fetchedAt,
+            cliVersion: typeof existing.cliVersion === "string" ? existing.cliVersion : undefined,
+            models: existing.models,
+        };
+    }
+    return { fetchedAt: 0, models: {} };
+}
+/** Persist the catalog cache atomically under `.tumwater/state/`. */
+export function writeOpencodeCache(root, cache) {
+    writeJsonAtomic(opencodeModelsPath(root), cache);
+}
+/** Read the installed opencode CLI's version, undefined when it cannot be read (no binary, a
+ * timeout, or a spawn failure). A changed version forces a catalog refresh: OpenCode serves from
+ * the same models.dev data, so a new CLI may route to providers the old cache does not know.
+ * `bin` is the configured opencode binary (default `opencode` on PATH), so the seed probes the
+ * same binary the runs spawn. */
+function readCliVersion(bin = "opencode") {
+    try {
+        const res = spawnSync(bin, ["--version"], { stdio: "pipe", encoding: "utf8", timeout: 5_000 });
+        const version = res.stdout?.trim();
+        return version === undefined || version === "" ? undefined : version;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** 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). */
+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 &&
+        (version === undefined || current.cliVersion === version);
+    if (fresh)
+        return current;
+    let body;
+    try {
+        body = await fetchOpencodeCatalog(opts.fetch);
+    }
+    catch {
+        opts.warn?.(`open code model catalog fetch failed; keeping the cached copy`);
+        return current.fetchedAt === 0 ? { fetchedAt: 0, cliVersion: version, models: {} } : current;
+    }
+    const parsed = parseOpencodeCatalog(body, opts.providers);
+    for (const key of Object.keys(parsed)) {
+        const fresh = parsed[key];
+        const old = current.models[key];
+        if (fresh !== undefined && old?.billedAt !== undefined)
+            fresh.billedAt = old.billedAt;
+    }
+    const cache = { fetchedAt: now, cliVersion: version, models: parsed };
+    writeOpencodeCache(root, cache);
+    return cache;
+}

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

@@ -0,0 +1,188 @@
+// 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.
+ *
+ * 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
+ * operator server named `tumwater` is disabled like any other (a later config replaces a
+ * server object whole, design decision 8 and plans/opencode-backend.md "The invocation"). No
+ * XDG/config files are read here except the operator's global opencode config, and that only
+ * to enumerate its MCP server names (operatorMcpNames): a broken or missing file yields `[]`
+ * here, and doctor reports it in part 7/7. */
+import fs from "node:fs";
+import path from "node:path";
+/** 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"];
+/** The six gate-safe denials (plans/opencode-backend.md "The invocation", findings 11–12).
+ * `read` is never denied — it trips the free-tier gate. `shell`, `glob`, `grep`, `edit` and
+ * `write` stay allowed for parity with pi. */
+const DENIED_PERMISSIONS = [
+    { action: "execute", resource: "*", effect: "deny" },
+    { action: "subagent", resource: "*", effect: "deny" },
+    { action: "webfetch", resource: "*", effect: "deny" },
+    { action: "websearch", resource: "*", effect: "deny" },
+    { action: "question", resource: "*", effect: "deny" },
+    { action: "skill", resource: "*", effect: "deny" },
+];
+/** True at `i` when a `//` line comment or a `/*`-style block comment starts there. */
+function isCommentStart(src, i) {
+    return src[i] === "/" && (src[i + 1] === "/" || src[i + 1] === "*");
+}
+/** Advance `j` past any whitespace and comments, for a position that is never inside a string.
+ * Returns the index of the next significant (non-comment, non-whitespace) character, or
+ * `src.length` when the input ends in comments/whitespace. */
+function skipWhitespaceAndComments(src, j) {
+    while (j < src.length) {
+        const c = src[j];
+        if (c === " " || c === "\t" || c === "\n" || c === "\r") {
+            j += 1;
+            continue;
+        }
+        if (c === "/" && src[j + 1] === "/") {
+            while (j < src.length && src[j] !== "\n")
+                j += 1;
+            continue;
+        }
+        if (c === "/" && src[j + 1] === "*") {
+            j += 2;
+            while (j < src.length && !(src[j] === "*" && src[j + 1] === "/"))
+                j += 1;
+            j += 2;
+            continue;
+        }
+        break;
+    }
+    return j;
+}
+/** Strip comments and trailing commas from a JSONC string so a strict JSON parse succeeds.
+ * Walks the string so a `//` or a block-comment opener, and `,}` / `,]`, inside a normal
+ * double-quoted string value survive (escape sequences included); comments and trailing
+ * commas are removed only outside strings, where they are legal JSONC but not JSON. A
+ * trailing comma is dropped when the next significant character — past any whitespace AND
+ * any comment — is a closing brace or bracket, so a comma then a comment then `}` strips
+ * correctly. */
+function stripJsonc(src) {
+    let out = "";
+    let inString = false;
+    let i = 0;
+    while (i < src.length) {
+        const c = src[i];
+        const next = src[i + 1];
+        if (inString) {
+            out += c;
+            if (c === "\\" && next !== undefined) {
+                out += next;
+                i += 2;
+            }
+            else {
+                if (c === '"')
+                    inString = false;
+                i += 1;
+            }
+            continue;
+        }
+        if (c === '"') {
+            inString = true;
+            out += c;
+            i += 1;
+            continue;
+        }
+        if (isCommentStart(src, i)) {
+            i = skipWhitespaceAndComments(src, i);
+            continue;
+        }
+        if (c === ",") {
+            // A trailing comma may be followed by whitespace and comments before the closing
+            // brace/bracket (`,\n  // c\n }`); look past all of it to decide, without touching a
+            // comma inside a string value.
+            const j = skipWhitespaceAndComments(src, i + 1);
+            if (src[j] === "}" || src[j] === "]") {
+                i += 1;
+                continue;
+            }
+        }
+        out += c;
+        i += 1;
+    }
+    return out;
+}
+/** Read the MCP server names in the operator's global opencode config. Each name is a server
+ * the managed config must explicitly disable (config merges, so it cannot be removed). Reads
+ * both config shapes: the keys of V2's `mcp.servers` plus V1-shaped `mcp.<name>` keys other
+ * than `servers`. Returns `[]` for a missing file, an unreadable file, or one that does not
+ * parse; doctor reports a broken one in part 7/7. `homeDir` is the operator's home directory;
+ * the process's own `XDG_CONFIG_HOME` env, when set, wins over `~/.config` (the XDG default). */
+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 {
+            continue;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(file.endsWith(".jsonc") ? stripJsonc(text) : text);
+        }
+        catch {
+            return [];
+        }
+        const mcp = parsed?.mcp;
+        if (mcp === undefined || mcp === null)
+            return [];
+        if (typeof mcp !== "object" || Array.isArray(mcp))
+            return [];
+        const names = new Set();
+        const servers = mcp.servers;
+        if (typeof servers === "object" && servers !== null && !Array.isArray(servers)) {
+            for (const key of Object.keys(servers))
+                names.add(key);
+        }
+        // V1-shaped `mcp.<name>` keys, other than the V2 `servers` grouping.
+        for (const key of Object.keys(mcp)) {
+            if (key !== "servers")
+                names.add(key);
+        }
+        return [...names];
+    }
+    return [];
+}
+/** True when the worktree has a `CLAUDE.md` and no `AGENTS.md`: OpenCode reads `AGENTS.md`
+ * only, so the managed config injects `CLAUDE.md` — but only when the repo has no `AGENTS.md`,
+ * exactly the mirror of claude's `shouldAppendAgents`. */
+function shouldInjectClaudeMd(cwd) {
+    return fs.existsSync(path.join(cwd, "CLAUDE.md")) && !fs.existsSync(path.join(cwd, "AGENTS.md"));
+}
+/** Build the injected opencode config JSON string. Never reads the worktree beyond the
+ * CLAUDE.md/AGENTS.md probe. */
+export function opencodeConfigContent(opts) {
+    const config = {
+        snapshots: false,
+        update: "disable",
+        permissions: DENIED_PERMISSIONS,
+    };
+    if (opts.toolOutput !== undefined) {
+        config.tool_output = { max_lines: opts.toolOutput.maxLines, max_bytes: opts.toolOutput.maxBytes };
+    }
+    const servers = {};
+    for (const name of opts.operatorMcpNames) {
+        // Every operator server is disabled alike: an operator server named `tumwater` gets no
+        // special treatment now that tumwater ships no MCP server of its own (part 3/4).
+        servers[name] = { disabled: true };
+    }
+    if (Object.keys(servers).length > 0)
+        config.mcp = { servers };
+    if (shouldInjectClaudeMd(opts.cwd))
+        config.instructions = ["CLAUDE.md"];
+    return JSON.stringify(config);
+}

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

@@ -0,0 +1,36 @@
+// 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
+ * hands the result here alongside the injected config and the session database path.
+ *
+ * Inherited OpenCode session variables are scrubbed (every `OPENCODE_*` except the operator's
+ * `OPENCODE_API_KEY`, plus the bare `OPENCODE` and `AI_AGENT`): a run spawned from inside an
+ * OpenCode session must not attach to that session's server, config or database, and `AI_AGENT`
+ * must not leak so the shell tool sets its own (finding 16). The set half disables Claude Code
+ * interop and its skills, auto-update and the file watcher, and isolates the run to its own
+ * database and injected config.
+ *
+ * No shell-timeout variable exists in 2.0.32 (finding 16), so none is set; the dialect tells
+ * the model to pass `timeout` for the check (§5). `XDG_CONFIG_HOME` and its siblings are NOT
+ * set: OpenCode's shell-tool children inherit the environment, and pointing XDG at a private
+ * dir would stop `git` reading `~/.config/git/config`, losing commits' author identity (§3). */
+/** Build the opencode process environment from `base`. Never mutates `base`. */
+export function opencodeEnv(base, opts) {
+    const env = {};
+    for (const [key, value] of Object.entries(base)) {
+        // Everything an inherited OpenCode session set is scrubbed — server, config, database,
+        // client and session id — except the operator's API key, which is operator intent and must
+        // survive. `AI_AGENT` goes too, so the shell tool sets its own (finding 16).
+        if (key === "OPENCODE" || (key.startsWith("OPENCODE_") && key !== "OPENCODE_API_KEY") || key === "AI_AGENT")
+            continue;
+        env[key] = value;
+    }
+    env.OPENCODE_DISABLE_CLAUDE_CODE = "1";
+    env.OPENCODE_DISABLE_CLAUDE_CODE_SKILLS = "1";
+    env.OPENCODE_DISABLE_AUTOUPDATE = "1";
+    env.OPENCODE_DISABLE_FILEWATCHER = "1";
+    env.OPENCODE_DB = opts.dbPath;
+    env.OPENCODE_CONFIG_CONTENT = opts.configContent;
+    return env;
+}