@sagentlab/navarch-runtime 0.1.24 → 0.1.26

package/README.md

@@ -6,10 +6,10 @@ it. Plain Node/TypeScript, zero production dependencies, no Next.js coupling
 — this directory is a self-contained package you can `npx` on any fresh
 machine.
 
-The machine operator selects **Claude Code**, **OpenAI Codex**, or **Google
-Gemini CLI** when connecting a worker. Any selected agent can run any project
-task; task eligibility depends on capabilities and project gates, not agent
-type — see "Choosing an agent" below.
+The machine operator selects **Claude Code**, **OpenAI Codex**, **Google
+Gemini CLI**, or **OpenCode** when connecting a worker. Any selected agent can
+run any project task; task eligibility depends on capabilities and project
+gates, not agent type — see "Choosing an agent" below.
 
 See [`docs/agent-platform-project-plan.md`](../docs/agent-platform-project-plan.md)
 §3.8/§3.9/§3.11 and [`docs/navarch/implementation-plan.md`](../docs/navarch/implementation-plan.md)
@@ -125,10 +125,10 @@ The from-source flow — `git clone` + `./install.sh` + `node bin/navarch.cjs
 
 | Command | Purpose |
 |---|---|
-| `register --token <t> --name <n> [--agent claude-code\|codex\|gemini] […]` | Registers this machine, saves its local agent choice, and prints the token once. |
-| `connect --token <t> --name <n> [--agent claude-code\|codex\|gemini] [--project <id>] […]` | Connects this machine to one project, saves its local agent choice, and prints the token once. |
-| `start [--agent claude-code\|codex\|gemini]` | Runs the daemon. A start-time agent choice overrides the saved choice. |
-| `supervise [--agent claude-code\|codex\|gemini]` | Runs the daemon under the update supervisor, enabling drain-safe automatic updates and rollback. |
+| `register --token <t> --name <n> [--agent claude-code\|codex\|gemini\|opencode] […]` | Registers this machine, saves its local agent choice, and prints the token once. |
+| `connect --token <t> --name <n> [--agent claude-code\|codex\|gemini\|opencode] [--project <id>] […]` | Connects this machine to one project, saves its local agent choice, and prints the token once. |
+| `start [--agent claude-code\|codex\|gemini\|opencode]` | Runs the daemon. A start-time agent choice overrides the saved choice. |
+| `supervise [--agent claude-code\|codex\|gemini\|opencode]` | Runs the daemon under the update supervisor, enabling drain-safe automatic updates and rollback. |
 | `doctor` | Prints resolved config + Docker/registration status; no side effects. |
 
 ### Running multiple agents on one machine
@@ -273,7 +273,7 @@ unchanged across the deployment.
 | `NAVARCH_GIT_AUTHOR_NAME` / `NAVARCH_GIT_AUTHOR_EMAIL` | `sagentlab` / `z@sagentlab.com` | Git identity forced into session commits so host-level personal config is not inherited; override both for a project-authorized bot. |
 | `NAVARCH_SANDBOX_MODE` | `host` | `host` uses the resources already available to the agent process. Set `docker` explicitly for container isolation. |
 | `NAVARCH_DOCKER_IMAGE` | `ghcr.io/sagentlab/navarch-sandbox-agent:0.1.0` | Version-pinned per-session image with Node 20, git, GitHub CLI, ripgrep, jq, SSH, and Claude Code 2.1.218. Override with an image tag or digest you control. |
-| `NAVARCH_AGENT` | saved choice, then `claude-code` | Local choice of agent CLI: `claude-code`, `codex`, or `gemini`. Overrides the choice saved by `connect`/`register`; `start --agent` has highest priority. |
+| `NAVARCH_AGENT` | saved choice, then `claude-code` | Local choice of agent CLI: `claude-code`, `codex`, `gemini`, or `opencode`. Overrides the choice saved by `connect`/`register`; `start --agent` has highest priority. |
 | `NAVARCH_RUNTIMES` | selected `NAVARCH_AGENT` | Comma list of installed/authenticated adapters advertised to dispatch. The control plane chooses among these per project/task. |
 | `NAVARCH_UPDATE_CHANNEL` | `stable` | Release channel advertised by the worker (`stable` or `canary`); the server-managed machine channel remains authoritative. |
 | `NAVARCH_AUTO_UPDATE` | on under `supervise` | Set `off`, `false`, or `0` to report releases without staging or activating them. Automatic activation is always off under plain `start`. |
@@ -283,6 +283,8 @@ unchanged across the deployment.
 | `NAVARCH_CODEX_EXTRA_ARGS` | — | Comma list of extra CLI args appended after the generated MCP `-c` overrides and `--json` (Codex). |
 | `NAVARCH_GEMINI_BIN` | `gemini` | Path/name of the Google Gemini CLI binary. |
 | `NAVARCH_GEMINI_EXTRA_ARGS` | — | Comma list of extra CLI args appended after the generated MCP settings, `stream-json`, and unattended defaults (Gemini). |
+| `NAVARCH_OPENCODE_BIN` | `opencode` | Path/name of the OpenCode CLI binary. |
+| `NAVARCH_OPENCODE_EXTRA_ARGS` | — | Comma list of extra CLI args appended after `run`, the prompt, and the generated `--format json` argument. Explicit `--format`, `--model`, or `--variant` values replace the corresponding per-session default. |
 | `NAVARCH_MCP_CONFIG_PATH` | — | Path to the platform MCP config passed as `--mcp-config`. |
 | `NAVARCH_WORKTREE_GUARD` | on | Host-mode sessions get an adapter-native per-session worktree boundary guard (see below). Set `off` to disable. |
 | `NAVARCH_GUARD_EXTRA_ROOTS` | — | `path.delimiter`-separated (`:` on POSIX) extra directories the worktree guard allows beyond the session worktree, shared bare repo, and temp dirs. |
@@ -327,6 +329,14 @@ as an explicit read-only mount.
   values remain environment-variable references rather than literals.
   Docker-mode sessions disable Gemini's implicit YOLO sandbox to avoid nesting
   it inside Navarch's already isolated session container.
+- **OpenCode:** the CLI cannot currently express a host-side boundary for all
+  shell side effects. With the guard enabled, host launches therefore fail
+  closed before the CLI starts. Run OpenCode in Docker with an operator-owned
+  image that contains an authenticated `opencode` binary, or set
+  `NAVARCH_WORKTREE_GUARD=off` only when the whole machine is already isolated.
+  OpenCode receives a private, per-session config, project config discovery is
+  disabled, and lease MCP headers are referenced through child-only environment
+  variables instead of being copied into its config file or argv.
 
 The resulting boundary is:
 
@@ -382,8 +392,13 @@ export NAVARCH_AGENT=codex
 # NAVARCH_GEMINI_BIN pointing at it).
 export NAVARCH_AGENT=gemini
 
+# OpenCode — requires an authenticated `opencode` CLI (or
+# NAVARCH_OPENCODE_BIN pointing at it). The guarded host path fails closed;
+# use a Docker image containing OpenCode for the normal isolated path.
+export NAVARCH_AGENT=opencode
+
 # Advanced compatibility mode: advertise every installed adapter.
-export NAVARCH_RUNTIMES=claude-code,codex,gemini
+export NAVARCH_RUNTIMES=claude-code,codex,gemini,opencode
 ```
 
 For the legacy single-runtime setting, priority is `start --agent` →
@@ -392,7 +407,7 @@ For the legacy single-runtime setting, priority is `start --agent` →
 the locally selected `NAVARCH_AGENT` handles every claimed task. Sandbox
 projects remain constrained to Claude Code.
 
-All three adapters implement the same `AgentAdapter` interface
+All four BYO adapters implement the same `AgentAdapter` interface
 (`src/adapters/types.cts`) and run either directly on the host or via
 `docker exec` in the session's sandbox container, exactly like the Claude
 adapter always has — `session.cts` picks one (`src/adapters/index.cts`'s
@@ -402,11 +417,13 @@ through to `complete()` unchanged by whatever happened during the run.
 The control plane also resolves the project's model and the task's execution
 profile on every claim. The runtime passes those values as per-session CLI
 overrides (`codex exec --model ... -c model_reasoning_effort=...`,
-`claude -p --model ... --effort ...`, or `gemini --model ...`) and records the
-effective model, profile, and effort on completion. Gemini currently uses its
-`auto` model default and does not expose a reasoning-effort flag. Machine-wide
-extra arguments still configure other CLI behavior; dispatched model policy
-wins.
+`claude -p --model ... --effort ...`, `gemini --model ...`, or `opencode run
+--model ... --variant ...`) and records the effective model, profile, and
+effort on completion. Gemini currently uses its `auto` model default and does
+not expose a reasoning-effort flag. OpenCode accepts `default` to preserve the
+authenticated account's selection, or any `provider/model` reference.
+Machine-wide extra arguments still configure other CLI behavior; dispatched
+model policy wins.
 
 The Codex CLI invocation was verified against `codex-cli 0.144.1` on
 2026-07-18. The runtime uses `codex exec "<prompt>" --json` and translates
@@ -422,6 +439,13 @@ post-tool answer as the report, and reads aggregate `input_tokens` and
 `output_tokens` from the terminal `result` event. Gemini does not report USD
 cost, so an unknown value remains absent rather than becoming zero.
 
+The OpenCode adapter uses `opencode run "<prompt>" --format json`, closes
+stdin immediately, and normalizes `text` and `step_finish` JSONL events into
+the shared report/token/cost boundary. It translates the lease MCP document
+to OpenCode's remote-server config with OAuth disabled and environment-backed
+headers. Missing accounting fields stay absent rather than becoming a
+fabricated zero.
+
 ## Architecture
 
 ```
@@ -521,8 +545,12 @@ tests cover:
 - `adapters/gemini.cts` — host/Docker invocation, cancellation, sandbox/MCP
   credential hygiene, parser drift, and normalized report/usage extraction
   (`tests/adapters/gemini.test.cts`).
+- `adapters/opencode.cts` — real fake-binary invocation covering the prompt,
+  isolated config and MCP header references, JSONL normalization, timeout,
+  lease cancellation, and fail-closed host boundary
+  (`tests/adapters/opencode.test.cts`).
 - `adapters/types.cts` — the shared process-result boundary is exercised for
-  Claude, Codex, and Gemini (`tests/adapters/conformance.test.cts`).
+  Claude, Codex, Gemini, and OpenCode (`tests/adapters/conformance.test.cts`).
 - `worktree-guard.cts` + `bin/worktree-guard-hook.cjs` — generated settings/
   config shape, native Codex permission-profile construction, and the hook's
   containment verdicts (in-worktree vs. sibling session vs. home dir, symlink
@@ -557,6 +585,9 @@ secrets absent from disk after exit"):
   production composition.
 - A full Gemini task that uses an authenticated Gemini CLI to claim, edit,
   open a PR, report usage/evidence, and clean up its session sandbox.
+- A full OpenCode task in an operator-owned Docker image that contains an
+  authenticated OpenCode CLI, including lease MCP access, cancellation, PR
+  creation, attribution, and cleanup.
 - Whether Docker-mode Codex should opt into
   `--dangerously-bypass-approvals-and-sandbox`. It is intentionally not a
   default: host mode is not an external sandbox, and silently disabling

package/dist/adapters/index.cjs

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.runGeminiAdapter = exports.geminiAdapter = exports.runCodexAdapter = exports.codexAdapter = exports.runClaudeCodeAdapter = exports.claudeCodeAdapter = void 0;
+exports.runOpenCodeAdapter = exports.openCodeAdapter = exports.runGeminiAdapter = exports.geminiAdapter = exports.runCodexAdapter = exports.codexAdapter = exports.runClaudeCodeAdapter = exports.claudeCodeAdapter = void 0;
 exports.selectAdapter = selectAdapter;
 const claude_cjs_1 = require("./claude.cjs");
 Object.defineProperty(exports, "claudeCodeAdapter", { enumerable: true, get: function () { return claude_cjs_1.claudeCodeAdapter; } });
@@ -11,6 +11,9 @@ Object.defineProperty(exports, "runCodexAdapter", { enumerable: true, get: funct
 const gemini_cjs_1 = require("./gemini.cjs");
 Object.defineProperty(exports, "geminiAdapter", { enumerable: true, get: function () { return gemini_cjs_1.geminiAdapter; } });
 Object.defineProperty(exports, "runGeminiAdapter", { enumerable: true, get: function () { return gemini_cjs_1.runGeminiAdapter; } });
+const opencode_cjs_1 = require("./opencode.cjs");
+Object.defineProperty(exports, "openCodeAdapter", { enumerable: true, get: function () { return opencode_cjs_1.openCodeAdapter; } });
+Object.defineProperty(exports, "runOpenCodeAdapter", { enumerable: true, get: function () { return opencode_cjs_1.runOpenCodeAdapter; } });
 /**
  * Picks the AgentAdapter (adapters/types.cts) session.cts should run a
  * session with, keyed off config.cts's `agentType` (NAVARCH_AGENT). This is
@@ -24,6 +27,8 @@ function selectAdapter(agentType) {
             return codex_cjs_1.codexAdapter;
         case "gemini":
             return gemini_cjs_1.geminiAdapter;
+        case "opencode":
+            return opencode_cjs_1.openCodeAdapter;
         case "claude-code":
             return claude_cjs_1.claudeCodeAdapter;
         default: {

package/dist/adapters/opencode.cjs

@@ -0,0 +1,262 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.openCodeAdapter = void 0;
+exports.runOpenCodeAdapter = runOpenCodeAdapter;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+/**
+ * Headless OpenCode adapter, fixture-pinned to the OpenCode 1.18 JSON/config
+ * contract:
+ *
+ *   opencode run "<prompt>" --format json [--model provider/model]
+ *
+ * OpenCode merges configuration from several machine and project locations,
+ * so each Navarch session gets an isolated XDG/config directory, disables
+ * project discovery, and supplies its complete policy as both a private file
+ * and the highest-precedence inline config. Provider credentials remain in
+ * OpenCode's data store or the child environment; only MCP env references are
+ * written to disk.
+ */
+async function runOpenCodeAdapter(options) {
+    if (options.opencodeHostGuard && !options.dockerExec) {
+        return {
+            exitCode: 1,
+            timedOut: false,
+            killedByLeaseLoss: false,
+            stdout: "",
+            stderr: "OpenCode cannot enforce Navarch's host worktree boundary for shell side effects. " +
+                "Use NAVARCH_SANDBOX_MODE=docker, or explicitly set NAVARCH_WORKTREE_GUARD=off " +
+                "only on an otherwise isolated machine.",
+        };
+    }
+    const env = { ...options.env };
+    await prepareOpenCodeConfig(options.mcpConfigPath, env);
+    const args = ["run", options.prompt];
+    if (!hasArg(options.extraArgs, "--format"))
+        args.push("--format", "json");
+    args.push(...options.extraArgs);
+    if (options.model && options.model !== "default" && !hasArg(options.extraArgs, "--model", "-m")) {
+        args.push("--model", options.model);
+    }
+    if (options.reasoningEffort && !hasArg(options.extraArgs, "--variant")) {
+        args.push("--variant", options.reasoningEffort);
+    }
+    const runOptions = { ...options, env };
+    const raw = runOptions.dockerExec
+        ? await runViaDocker(runOptions, args)
+        : await runOnHost(runOptions, args);
+    return attachOpenCodeOutput(raw);
+}
+function hasArg(args, ...flags) {
+    return args.some((arg) => flags.some((flag) => arg === flag || arg.startsWith(`${flag}=`)));
+}
+async function prepareOpenCodeConfig(mcpConfigPath, env) {
+    if (!mcpConfigPath) {
+        throw new Error("OpenCode requires a per-session MCP config path for isolated execution.");
+    }
+    const parsed = JSON.parse(await node_fs_1.promises.readFile(mcpConfigPath, "utf8"));
+    const mcp = {};
+    for (const [name, server] of Object.entries(parsed.mcpServers ?? {})) {
+        const url = server.httpUrl ?? server.url;
+        if (!url)
+            continue;
+        const headers = {};
+        let headerIndex = 0;
+        for (const [header, value] of Object.entries(server.headers ?? {})) {
+            const existingEnv = envReference(value);
+            if (existingEnv) {
+                const referencedValue = env[existingEnv] ?? process.env[existingEnv];
+                if (referencedValue === undefined) {
+                    throw new Error(`OpenCode MCP header references missing environment variable ${existingEnv}.`);
+                }
+                env[existingEnv] = referencedValue;
+                headers[header] = value;
+                continue;
+            }
+            const envName = `NAVARCH_OPENCODE_MCP_${safeEnvSegment(name)}_${headerIndex++}`;
+            env[envName] = value;
+            headers[header] = `{env:${envName}}`;
+        }
+        mcp[name] = {
+            type: "remote",
+            url,
+            enabled: true,
+            oauth: false,
+            ...(Object.keys(headers).length > 0 ? { headers } : {}),
+        };
+    }
+    const config = {
+        $schema: "https://opencode.ai/config.json",
+        autoupdate: false,
+        share: "disabled",
+        plugin: [],
+        mcp,
+        permission: {
+            "*": "allow",
+            external_directory: "deny",
+            question: "deny",
+            doom_loop: "deny",
+        },
+    };
+    const configPath = `${mcpConfigPath}.opencode.json`;
+    const configDir = `${mcpConfigPath}.opencode-config`;
+    const xdgConfigHome = `${mcpConfigPath}.opencode-xdg`;
+    await node_fs_1.promises.mkdir(configDir, { recursive: true, mode: 0o700 });
+    await node_fs_1.promises.mkdir(xdgConfigHome, { recursive: true, mode: 0o700 });
+    await node_fs_1.promises.writeFile(configPath, JSON.stringify(config, null, 2), { mode: 0o600 });
+    await node_fs_1.promises.chmod(configPath, 0o600);
+    env.OPENCODE_CONFIG = configPath;
+    env.OPENCODE_CONFIG_DIR = configDir;
+    env.OPENCODE_CONFIG_CONTENT = JSON.stringify(config);
+    env.OPENCODE_DISABLE_PROJECT_CONFIG = "true";
+    env.XDG_CONFIG_HOME = xdgConfigHome;
+}
+function safeEnvSegment(value) {
+    return value.toUpperCase().replace(/[^A-Z0-9_]/g, "_");
+}
+function envReference(value) {
+    return value.match(/^\{env:([A-Z_][A-Z0-9_]*)\}$/)?.[1] ?? null;
+}
+function attachOpenCodeOutput(result) {
+    const events = parseOpenCodeEvents(result.stdout);
+    if (events.length === 0)
+        return result;
+    let tokensIn;
+    let tokensOut;
+    let costUsd;
+    let finalMessageId;
+    const textByMessage = new Map();
+    for (const event of events) {
+        const part = event.part;
+        if (event.type === "text" && part?.type === "text" && typeof part.text === "string") {
+            const messageId = part.messageID ?? "unknown";
+            const parts = textByMessage.get(messageId) ?? [];
+            parts.push(part.text);
+            textByMessage.set(messageId, parts);
+            finalMessageId = messageId;
+        }
+        if (event.type !== "step_finish" || part?.type !== "step-finish")
+            continue;
+        const input = nonNegativeMetric(part.tokens?.input);
+        const cacheRead = nonNegativeMetric(part.tokens?.cache?.read);
+        const cacheWrite = nonNegativeMetric(part.tokens?.cache?.write);
+        const output = nonNegativeMetric(part.tokens?.output);
+        const cost = nonNegativeMetric(part.cost);
+        if (input !== undefined || cacheRead !== undefined || cacheWrite !== undefined) {
+            tokensIn = (tokensIn ?? 0) + (input ?? 0) + (cacheRead ?? 0) + (cacheWrite ?? 0);
+        }
+        if (output !== undefined)
+            tokensOut = (tokensOut ?? 0) + output;
+        if (cost !== undefined)
+            costUsd = (costUsd ?? 0) + cost;
+    }
+    const reportText = finalMessageId
+        ? textByMessage.get(finalMessageId)?.join("\n").trim()
+        : undefined;
+    return {
+        ...result,
+        ...(tokensIn !== undefined ? { tokensIn } : {}),
+        ...(tokensOut !== undefined ? { tokensOut } : {}),
+        ...(costUsd !== undefined ? { costUsd } : {}),
+        ...(reportText ? { reportText } : {}),
+    };
+}
+function parseOpenCodeEvents(stdout) {
+    const events = [];
+    for (const line of stdout.split(/\r?\n/)) {
+        if (!line.trim().startsWith("{"))
+            continue;
+        try {
+            const event = JSON.parse(line);
+            if (event && typeof event === "object" && typeof event.type === "string")
+                events.push(event);
+        }
+        catch {
+            // Keep unknown lines in the transcript and degrade to raw output.
+        }
+    }
+    return events;
+}
+function nonNegativeMetric(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+async function runOnHost(options, args) {
+    return new Promise((resolve) => {
+        let stdout = "";
+        let stderr = "";
+        let timedOut = false;
+        let killedByLeaseLoss = false;
+        const child = (0, node_child_process_1.spawn)(options.bin, args, {
+            cwd: options.cwd,
+            env: { ...process.env, ...options.env },
+        });
+        child.stdin?.end();
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill("SIGKILL");
+        }, options.timeoutMs);
+        const onAbort = () => {
+            killedByLeaseLoss = true;
+            child.kill("SIGKILL");
+        };
+        options.signal?.addEventListener("abort", onAbort, { once: true });
+        child.stdout.on("data", (data) => {
+            stdout += data.toString();
+        });
+        child.stderr.on("data", (data) => {
+            stderr += data.toString();
+        });
+        child.on("error", (error) => {
+            clearTimeout(timer);
+            options.signal?.removeEventListener("abort", onAbort);
+            stderr += `\n${String(error)}`;
+            resolve({ exitCode: null, timedOut, killedByLeaseLoss, stdout, stderr });
+        });
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            options.signal?.removeEventListener("abort", onAbort);
+            resolve({ exitCode: code, timedOut, killedByLeaseLoss, stdout, stderr });
+        });
+    });
+}
+async function runViaDocker(options, args) {
+    const { containerName, runner } = options.dockerExec;
+    const quoted = [options.bin, ...args].map(shellQuote).join(" ");
+    const command = `[ -f /tmp/session.env ] && . /tmp/session.env; cd repo 2>/dev/null; ${quoted}`;
+    let killedByLeaseLoss = false;
+    const onAbort = () => {
+        killedByLeaseLoss = true;
+        runner.run("docker", ["kill", containerName]).catch(() => undefined);
+    };
+    options.signal?.addEventListener("abort", onAbort, { once: true });
+    try {
+        const forwardedEnv = Object.keys(options.env).flatMap((name) => ["--env", name]);
+        const result = await runner.run("docker", ["exec", ...forwardedEnv, containerName, "sh", "-c", command], { timeoutMs: options.timeoutMs, env: { ...process.env, ...options.env } });
+        return {
+            exitCode: result.code,
+            timedOut: false,
+            killedByLeaseLoss,
+            stdout: result.stdout,
+            stderr: result.stderr,
+        };
+    }
+    catch (error) {
+        return {
+            exitCode: null,
+            timedOut: false,
+            killedByLeaseLoss,
+            stdout: "",
+            stderr: String(error),
+        };
+    }
+    finally {
+        options.signal?.removeEventListener("abort", onAbort);
+    }
+}
+function shellQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+exports.openCodeAdapter = {
+    agentType: "opencode",
+    run: runOpenCodeAdapter,
+};

package/dist/cli.cjs

@@ -66,7 +66,7 @@ function agentFromFlag(flags) {
     if (value === undefined)
         return undefined;
     if (!(0, config_cjs_1.isRuntimeAgentType)(value)) {
-        throw new Error("--agent must be one of 'claude-code', 'codex', or 'gemini'.");
+        throw new Error("--agent must be one of 'claude-code', 'codex', 'gemini', or 'opencode'.");
     }
     return value;
 }
@@ -250,8 +250,8 @@ async function superviseCommand(flags) {
     // Resolve and pin the adapter before spawning the worker. The supervisor
     // passes machine credentials through the environment, so the child no
     // longer reads machine.json for identity fields (including agent_type).
-    // Without an explicit worker argument, a saved Codex/Gemini selection
-    // therefore falls back to Claude Code.
+    // Without an explicit worker argument, any saved non-Claude selection
+    // would therefore fall back to Claude Code.
     const agentType = agentFromFlag(flags) ??
         (process.env.NAVARCH_AGENT ? config.agentType : identity.agent_type ?? config.agentType);
     const workerArgs = ["--agent", agentType];
@@ -296,11 +296,11 @@ function helpText() {
 
 Usage:
   navarch-runtime register --token <enrollment-token> --name <machine-name> \\
-      [--config-dir <path>] [--agent claude-code|codex|gemini] [--capabilities a,b] [--max-sessions N] [--owner-zone z] [--api-base url]
+      [--config-dir <path>] [--agent claude-code|codex|gemini|opencode] [--capabilities a,b] [--max-sessions N] [--owner-zone z] [--api-base url]
   navarch-runtime connect --token <enrollment-token> --name <machine-name> \\
-      [--config-dir <path>] [--agent claude-code|codex|gemini] [--project <project-id>] [--capabilities a,b] [--max-sessions N] [--api-base url]
-  navarch-runtime start [--config-dir <path>] [--agent claude-code|codex|gemini]
-  navarch-runtime supervise [--config-dir <path>] [--agent claude-code|codex|gemini]
+      [--config-dir <path>] [--agent claude-code|codex|gemini|opencode] [--project <project-id>] [--capabilities a,b] [--max-sessions N] [--api-base url]
+  navarch-runtime start [--config-dir <path>] [--agent claude-code|codex|gemini|opencode]
+  navarch-runtime supervise [--config-dir <path>] [--agent claude-code|codex|gemini|opencode]
   navarch-runtime doctor [--config-dir <path>]
 
 Use a different --config-dir (or NAVARCH_CONFIG_DIR) for every agent instance.

package/dist/config.cjs

@@ -11,7 +11,10 @@ const node_os_1 = __importDefault(require("node:os"));
 /** Published image containing git, GitHub CLI, and the pinned Claude Code CLI. */
 exports.DEFAULT_SANDBOX_IMAGE = "ghcr.io/sagentlab/navarch-sandbox-agent:0.1.0";
 function isRuntimeAgentType(value) {
-    return value === "claude-code" || value === "codex" || value === "gemini";
+    return (value === "claude-code" ||
+        value === "codex" ||
+        value === "gemini" ||
+        value === "opencode");
 }
 function envInt(env, name, fallback) {
     const raw = env[name];
@@ -77,6 +80,8 @@ function loadRuntimeConfig(env = process.env) {
         codexExtraArgs: envList(env, "NAVARCH_CODEX_EXTRA_ARGS", []),
         geminiBin: env.NAVARCH_GEMINI_BIN ?? "gemini",
         geminiExtraArgs: envList(env, "NAVARCH_GEMINI_EXTRA_ARGS", []),
+        opencodeBin: env.NAVARCH_OPENCODE_BIN ?? "opencode",
+        opencodeExtraArgs: envList(env, "NAVARCH_OPENCODE_EXTRA_ARGS", []),
         gitAuthorName: env.NAVARCH_GIT_AUTHOR_NAME ?? "sagentlab",
         gitAuthorEmail: env.NAVARCH_GIT_AUTHOR_EMAIL ?? "z@sagentlab.com",
         mcpConfigPath: env.NAVARCH_MCP_CONFIG_PATH ?? null,

package/dist/mcp-config.cjs

@@ -15,10 +15,13 @@
 // Pure and side-effect free (no filesystem access) so it's trivially unit
 // testable; session.cts is the only caller that writes the result to disk.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.NAVARCH_LEASE_HEADER = void 0;
+exports.NAVARCH_MCP_LEASE_ENV = exports.NAVARCH_MCP_AUTH_ENV = exports.NAVARCH_LEASE_HEADER = void 0;
 exports.buildNavarchMcpConfig = buildNavarchMcpConfig;
+exports.buildEnvReferencedNavarchMcpConfig = buildEnvReferencedNavarchMcpConfig;
 /** The header app/api/mcp/route.ts's lib/navarch/mcp/context.ts reads to identify which lease is calling. */
 exports.NAVARCH_LEASE_HEADER = "X-Navarch-Lease-Id";
+exports.NAVARCH_MCP_AUTH_ENV = "NAVARCH_OPENCODE_MCP_AUTHORIZATION";
+exports.NAVARCH_MCP_LEASE_ENV = "NAVARCH_OPENCODE_MCP_LEASE_ID";
 /**
  * Builds the `.mcp.json`-shaped config object Claude Code's `--mcp-config`
  * flag expects: a remote "http" (streamable HTTP) server entry with the
@@ -39,3 +42,29 @@ function buildNavarchMcpConfig(opts) {
         },
     };
 }
+/**
+ * OpenCode reads `{env:NAME}` substitutions natively. Build its staging MCP
+ * document without bearer values so even the short-lived source JSON is safe
+ * to write in session metadata before the adapter converts it.
+ */
+function buildEnvReferencedNavarchMcpConfig(opts) {
+    const serverName = opts.serverName ?? "navarch";
+    return {
+        config: {
+            mcpServers: {
+                [serverName]: {
+                    type: "http",
+                    url: `${opts.apiBase.replace(/\/+$/, "")}/api/mcp`,
+                    headers: {
+                        Authorization: `{env:${exports.NAVARCH_MCP_AUTH_ENV}}`,
+                        [exports.NAVARCH_LEASE_HEADER]: `{env:${exports.NAVARCH_MCP_LEASE_ENV}}`,
+                    },
+                },
+            },
+        },
+        env: {
+            [exports.NAVARCH_MCP_AUTH_ENV]: `Bearer ${opts.machineToken}`,
+            [exports.NAVARCH_MCP_LEASE_ENV]: opts.leaseId,
+        },
+    };
+}

package/dist/session.cjs

@@ -32,7 +32,7 @@ const log = (0, logger_cjs_1.createLogger)("session");
  *   2. fetch secrets from the broker at session start (managed GitHub git
  *      credentials are subsequently refreshed by a lease-scoped helper)
  *   3. optionally stand up a Docker sandbox when explicitly configured
- *   4. run the adapter selected by the claim (Claude Code, Codex, or Gemini;
+ *   4. run the adapter selected by the claim (Claude Code, Codex, Gemini, or OpenCode;
  *      adapters/index.cts#selectAdapter), heartbeating the
  *      lease throughout
  *   5. redact + upload the transcript, map the exit condition, complete the
@@ -55,7 +55,9 @@ async function runSession(deps, claimed, sessionId) {
             ? "gpt-5.6-sol"
             : runtime === "gemini"
                 ? "auto"
-                : "best",
+                : runtime === "opencode"
+                    ? "default"
+                    : "best",
         reasoning_effort: "medium",
     };
     const executionReport = {
@@ -215,17 +217,23 @@ async function runSession(deps, claimed, sessionId) {
     // path valid in whichever environment it actually runs.
     let mcpConfigPath = config.mcpConfigPath;
     if (!mcpConfigPath) {
-        const mcpConfig = (0, mcp_config_cjs_1.buildNavarchMcpConfig)({
+        const mcpOptions = {
             apiBase: api.getBaseUrl(),
             machineToken: api.getToken() ?? "",
             leaseId,
-        });
-        await node_fs_1.promises.writeFile(node_path_1.default.join(workDir, MCP_CONFIG_FILENAME), JSON.stringify(mcpConfig, null, 2), "utf8");
+        };
+        const mcpConfig = runtime === "opencode"
+            ? (0, mcp_config_cjs_1.buildEnvReferencedNavarchMcpConfig)(mcpOptions)
+            : { config: (0, mcp_config_cjs_1.buildNavarchMcpConfig)(mcpOptions), env: {} };
+        Object.assign(sessionEnv, mcpConfig.env);
+        await node_fs_1.promises.writeFile(node_path_1.default.join(workDir, MCP_CONFIG_FILENAME), JSON.stringify(mcpConfig.config, null, 2), "utf8");
         mcpConfigPath = node_path_1.default.join(workDir, MCP_CONFIG_FILENAME);
     }
     // Worktree boundary guard (worktree-guard.cts): several sessions share this
     // machine. Host-mode Claude gets a generated PreToolUse hook; host-mode
-    // Codex gets an OS-enforced native permission profile over the same roots.
+    // Codex gets an OS-enforced native permission profile over the same roots;
+    // Gemini gets a native sandbox mount list; OpenCode fails closed on the
+    // guarded host path because its CLI cannot express the full boundary.
     // Docker mode already has a container boundary. NAVARCH_WORKTREE_GUARD=off
     // opts out for any agent.
     let claudeSettingsPath = null;
@@ -256,7 +264,7 @@ async function runSession(deps, claimed, sessionId) {
                 extraRoots: config.guardExtraRoots,
             });
         }
-        else {
+        else if (runtime === "gemini") {
             geminiGuardMounts = (0, worktree_guard_cjs_1.geminiSandboxMounts)({
                 workDir,
                 worktreePath: gitWorktree.worktreePath,
@@ -311,6 +319,7 @@ async function runSession(deps, claimed, sessionId) {
                 settingsPath: claudeSettingsPath,
                 codexGuardArgs,
                 geminiSandboxMounts: geminiGuardMounts,
+                opencodeHostGuard: runtime === "opencode" && config.sandboxMode === "host" && config.worktreeGuard,
                 cwd: sandbox ? undefined : gitWorktree.worktreePath,
                 dockerExec: sandbox ? { containerName: sandbox.name, runner: sandbox_cjs_1.nodeCommandRunner } : undefined,
                 signal: activeAbortController.signal,
@@ -526,6 +535,8 @@ function adapterCommand(config, runtime) {
             return { bin: config.codexBin, extraArgs: config.codexExtraArgs };
         case "gemini":
             return { bin: config.geminiBin, extraArgs: config.geminiExtraArgs };
+        case "opencode":
+            return { bin: config.opencodeBin, extraArgs: config.opencodeExtraArgs };
     }
 }
 function sumReportedUsage(attempts, key) {
@@ -556,6 +567,10 @@ function verificationFailureReport(taskType, report) {
 /** Rejection codes another agent turn in the same worktree can plausibly fix. */
 const REMEDIABLE_REJECTION_CODES = new Set([
     "pr_required",
+    // A video-deliverable build that completed without registering its render:
+    // the file usually already exists in the worktree, so the remediation turn
+    // only has to call register_artifact and PUT the upload.
+    "artifact_required",
     "pr_not_ready",
     "review_attestation_required",
     "review_attestation_invalid",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sagentlab/navarch-runtime",
-  "version": "0.1.24",
-  "description": "Navarch machine-side session manager: claims delivery tasks and runs them through Claude Code, Codex, or Gemini CLI.",
+  "version": "0.1.26",
+  "description": "Navarch machine-side session manager: claims delivery tasks and runs them through Claude Code, Codex, Gemini, or OpenCode.",
   "type": "commonjs",
   "license": "MIT",
   "repository": {
@@ -16,6 +16,7 @@
     "claude-code",
     "codex",
     "gemini-cli",
+    "opencode",
     "task-runner"
   ],
   "bin": {