tumwater 0.1.3 → 0.2.0

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

@@ -1,8 +1,7 @@
 /** Building the environment for one claude run (plans/agent-backends.md "The claude
  * invocation", "Findings" 2 and 4) — pure scrub-and-set over a base environment, with no
  * subprocess. The caller layers the run-marker, the macOS LaunchServices preload, and the
- * notebook on first (src/pi/pi-backend.ts's `withNotesPath` shows the pi adapter doing the
- * same), then hands the result here.
+ * notebook on first (src/process/run-marker.ts's `withNotesPath`), then hands the result here.
  *
  * Inherited Claude Code session variables break auth: spawned from inside a Claude Code
  * session, a child that keeps `CLAUDECODE`, `CLAUDE_CODE_*`, `CLAUDE_AGENT_SDK_*` or the host's
@@ -13,7 +12,7 @@
  *
  * The set half disables auto-memory, backgrounded Bash tasks (finding 4: claude refuses a long
  * foreground command, backgrounds it, and abandons it when `-p` ends, which would report work
- * never verified), the auto-updater (a mid-fleet self-update must not swap the binary under a
+ * never verified), the auto-updater (a mid-team self-update must not swap the binary under a
  * run), telemetry, and error reporting; and raises the Bash timeouts so a slow suite runs in
  * the foreground. `BASH_MAX_TIMEOUT_MS` is derived from `quietTimeoutSeconds` so claude's own
  * Bash timeout fires before tumwater's quiet kill and the model sees a tool error rather than a
@@ -80,5 +79,10 @@ export function claudeEnv(base, opts) {
     env.DISABLE_AUTOUPDATER = "1";
     env.DISABLE_TELEMETRY = "1";
     env.DISABLE_ERROR_REPORTING = "1";
+    // A team config dir (plans/notes-command.md "Keeping funes out of team runs"): force claude's
+    // own config and transcripts under it, so a funes hook on ~/.claude/projects never indexes
+    // team runs. Unset leaves any inherited CLAUDE_CONFIG_DIR (or claude's default) untouched.
+    if (opts.configDir)
+        env.CLAUDE_CONFIG_DIR = opts.configDir;
     return env;
 }

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

@@ -14,7 +14,7 @@
  * on the seam's optional `warnings()` — src/agent/run-agent.ts forwards each as an
  * `agent_unknown_event` warning after the run. `cost_unknown` is recorded the same way when a
  * run produced no authoritative `run_cost`. */
-import { isJsonObject, objectOrEmpty, nonNegativeNumber, parseJsonObject } from "../../files/json-object.js";
+import { canonicalUsageBlock, isJsonObject, objectOrEmpty, nonNegativeNumber, parseJsonObject } from "../../files/json-object.js";
 /** claude's tool names → the canonical pi names the readers already know. Glob/Grep are kept
  * lower-cased; MultiEdit collapses onto edit (pi has one edit tool). Anything else is
  * lower-cased so a future tool still reads as a name rather than as `undefined`. */
@@ -37,20 +37,10 @@ function str(value) {
 }
 /** claude's usage block → pi's canonical usage block, with `cost.total` 0 because the run's
  * authoritative cost rides the final `run_cost` event (a split-block message repeats its usage
- * on every event, so summing per event would double-count — the fold takes it once). */
+ * on every event, so summing per event would double-count — the fold takes it once). The
+ * wire-field reads stay here; the block's assembly is the shared canonicalUsageBlock. */
 function canonicalUsage(usage) {
-    const input = nonNegativeNumber(usage?.input_tokens, 0);
-    const cacheRead = nonNegativeNumber(usage?.cache_read_input_tokens, 0);
-    const cacheWrite = nonNegativeNumber(usage?.cache_creation_input_tokens, 0);
-    const output = nonNegativeNumber(usage?.output_tokens, 0);
-    return {
-        input,
-        cacheRead,
-        cacheWrite,
-        output,
-        totalTokens: input + cacheRead + cacheWrite + output,
-        cost: { total: 0 },
-    };
+    return canonicalUsageBlock(nonNegativeNumber(usage?.input_tokens, 0), nonNegativeNumber(usage?.cache_read_input_tokens, 0), nonNegativeNumber(usage?.cache_creation_input_tokens, 0), nonNegativeNumber(usage?.output_tokens, 0), 0);
 }
 /** One claude content block → one pi content block, or undefined for a block pi has no
  * vocabulary for (dropped, like any other unmapped native shape). `tool_use` becomes pi's
@@ -76,7 +66,7 @@ function canonicalBlock(block) {
             return {
                 type: "toolCall",
                 id: str(block.id) ?? "",
-                name: Object.hasOwn(TOOL_NAMES, name) ? TOOL_NAMES[name] : name.toLowerCase(),
+                name: Object.hasOwn(TOOL_NAMES, name) ? (TOOL_NAMES[name]) : name.toLowerCase(),
                 arguments: args,
             };
         }
@@ -347,7 +337,8 @@ export function claudeTranslator(opts = {}) {
                 return out;
             }
             case "tool_progress":
-                // A 30 s heartbeat of a running tool call: known, and the open call already tracks liveness.
+                // A 30 s heartbeat of a running tool call: known, and the open call already tracks
+                // liveness.
                 return [];
             default:
                 record(type ?? "unknown");

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

@@ -0,0 +1,107 @@
+/** The seam's answer to "who in this team can read images" (plans/image-input.md
+ * "Capability"). One resolver, `seamImageInput`, is the only place that rule lives; the doctor
+ * (src/doctor/doctor-model-checks.ts) and the later reroute parts both read it, so the answer
+ * is never reached two ways. It lives at runtime level because it needs the backend registry:
+ * a claude seam is always capable through the AgentBackend.imageInput hook, a pi seam reads the
+ * model's `input` in models.json, and any other backend answers null unless it declares a hook. */
+import { configForRole, roleSeamTier, withModelOverrides } from "../config/config-views.js";
+import { BORROW_ORDER, resolveTierFallbacks } from "../config/config-fallbacks.js";
+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 { 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).
+ *
+ * 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
+ * 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);
+    // 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")
+        return null;
+    const base = piModelImageInput(providers, 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)];
+    if (entry?.verdict === "fail" && imageProbeEntryFresh(entry))
+        return false;
+    return true;
+}
+/** The image-capable reroute target for `role`, or null when no peer tier can read images
+ * (plans/image-input.md "Reroute target"). Walks the role's seam tier through BORROW_ORDER,
+ * skipping the tier itself — small → default → strong, default → strong → small, strong →
+ * default (a strong-tier seam never drops to small, the same rule as the budget fallback) —
+ * 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) {
+    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;
+    if (regime === "primary") {
+        for (const t of candidates) {
+            const rc = withModelOverrides(config, t, {});
+            if (capable(rc))
+                return { tier: t, config: rc };
+        }
+        return null;
+    }
+    // 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));
+    for (const t of candidates) {
+        const pair = resolved[t].pair;
+        if (!pair)
+            continue;
+        const rc = withModelOverrides(config, t, {
+            provider: pair.provider,
+            model: pair.model,
+            thinking: pair.thinking,
+        });
+        if (capable(rc))
+            return { tier: t, config: rc };
+    }
+    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;
+}
+/** 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);
+}
+/** Compute RoleImageInfo for one loop. `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
+ * the surface and the check agree about capability. */
+export function roleImageInfo(config, role, modelsPath = piModelsPath(), probes) {
+    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 imageRerouteStr = rr
+        ? `${rr.tier} (${seamImageLabel(rr.config.agent, rr.config.provider, rr.config.model)})`
+        : null;
+    return { imageInput, imageReroute: imageRerouteStr };
+}

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

@@ -0,0 +1,41 @@
+// 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`
+ * 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.
+ *
+ * The `<dist>` in the exec path is the shared distDir (src/build/build-info.ts), derived from
+ * this module's own location so a staged build (.tumwater/build/<sha>) points its shim at its
+ * own copy rather than the installed package's. The script is written
+ * atomically and made executable, only when its content differs, so a redeploy re-points it
+ * without churning the file. */
+import fs from "node:fs";
+import path from "node:path";
+import { distDir } from "../build/build-info.js";
+import { 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";
+/** Install the `tumwater-notes` shim under `<root>/.tumwater/bin` and return that directory.
+ * 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) {
+    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.
+    }
+    if (needsWrite) {
+        writeTextAtomic(target, content);
+    }
+    fs.chmodSync(target, 0o755);
+    return dir;
+}

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

@@ -0,0 +1,61 @@
+// 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
+ * its inputs (the resolved model, the catalog's variant, the session choice, the session
+ * name, and the configured passthrough args) into the invocation's argv and stdin.
+ *
+ * The environment is built separately (opencode-env.ts) so each concern has one module.
+ *
+ * `.args` passthrough: a passthrough arg equal to a flag the harness itself sets would be
+ * appended AFTER the harness's own copy and OpenCode's parser is last-wins, so it would
+ * silently override the resolved model, the session choice, or the isolation flags. Each is
+ * rejected by opencodeArgs with the offending arg named, matching the same rejection in
+ * claudeArgs and the reserved set from plans/opencode-backend.md "Config and routing". */
+/** Flags the harness invocation sets. A passthrough arg equal to one of these is rejected by
+ * opencodeArgs with the offending arg named, so an operator's `backends.opencode.args` can
+ * never silently override the resolved model, the session choice, or the isolation flags. This
+ * is the reserved set from plans/opencode-backend.md "Config and routing"; part 3 adds
+ * `--title`, which tumwater now sets (finding 6). */
+import { appendPassthroughArgs } from "../agent-args.js";
+export const HARNESS_OPENCODE_FLAGS = new Set([
+    "run",
+    "--format",
+    "--model",
+    "-m",
+    "--session",
+    "-s",
+    "--continue",
+    "-c",
+    "--fork",
+    "--standalone",
+    "--server",
+    "--attach",
+    "--auto",
+    "--yolo",
+    "--dangerously-skip-permissions",
+    "--agent",
+    "--thinking",
+    "--dir",
+    "--title",
+]);
+/** Build one run's opencode argv and stdin. The prompt is never an argv element (OpenCode
+ * reads a non-TTY stdin to EOF, and the runner closes it). A model with no `/` names a model
+ * on OpenCode's own gateway and gets the `opencode/` provider; anything with a slash is the
+ * provider-qualified id and passes as is. Throws on a passthrough arg that repeats a harness
+ * flag, since OpenCode's last-wins parser would otherwise silently override what the harness
+ * asked for. */
+/** The opencode-namespaced model id: a bare id (no `/`) names a model on OpenCode's own
+ * gateway and gets the `opencode/` provider; an id bearing a slash is provider-qualified and
+ * passes as-is. The single home of this routing rule — shared by the argv builder
+ * (opencodeArgs, here) and the catalog's cache key (opencode-catalog.ts's opencodeModelKey) —
+ * so the id a run is invoked with always matches the id a run is priced by. */
+export function opencodeQualifiedModel(model) {
+    return model.includes("/") ? model : `opencode/${model}`;
+}
+export function opencodeArgs(opts) {
+    const model = opencodeQualifiedModel(opts.model) + (opts.variant !== undefined ? `#${opts.variant}` : "");
+    const args = ["run", "--standalone", "--format", "json", "--auto", "--model", model, "--session", opts.sessionId, "--title", opts.title];
+    appendPassthroughArgs(args, opts.args, HARNESS_OPENCODE_FLAGS, "opencodeArgs");
+    return { args, stdin: opts.prompt };
+}

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,
+};