@sagentlab/navarch-runtime 0.1.10 → 0.1.12

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 agent CLI a session runs is either **Claude Code** or **OpenAI Codex**,
-selected by the local machine via `--agent` or `NAVARCH_AGENT` (default
-`claude-code`) — see
-"Choosing an agent (Claude Code vs. Codex)" below.
+The control plane selects **Claude Code**, **OpenAI Codex**, or **Google
+Gemini CLI** from the project's default and any task override. Workers
+advertise the adapters they can run, so tasks wait for an eligible runtime
+and capability match — 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)
@@ -19,31 +19,66 @@ the API contract.
 
 ## Quick start on a fresh machine
 
+For a project machine, use the command generated by **Onboard → Connect an
+agent** or **Project settings → Connect an agent**. It includes a single-use,
+project-scoped enrollment token and the correct control-plane origin. The
+recommended npm package requires Node.js 20 or later:
+
 ```sh
-git clone <this repo> && cd sagentlab/runtime
-./install.sh          # checks node, npm install, npm run build
-export NAVARCH_API_BASE=https://navarch.example.com
-node bin/navarch.cjs register --token <enrollment-token> --name my-machine-1
-node bin/navarch.cjs supervise
+# Run the two commands copied from Navarch. Their values resemble:
+npx --yes @sagentlab/navarch-runtime@latest connect \
+  --token flmt_<single-use-token> --project <project-id> \
+  --name <machine-name> --agent codex \
+  --capabilities shell,browser-use --max-sessions 5 \
+  --api-base https://www.sagentlab.com --config-dir ~/.navarch/<project-slug>
+npx --yes @sagentlab/navarch-runtime@latest supervise \
+  --config-dir ~/.navarch/<project-slug>
 ```
 
-Or, once dependencies are installed:
+Keep the same config directory for `connect`, `supervise`, `doctor`, and later
+upgrades. `connect` stores the machine identity in `<config-dir>/machine.json`
+with mode `0600`; the raw machine token is not shown again. Do not copy that
+file or the enrollment command into logs.
+
+In another terminal, verify the machine without starting a second worker:
 
 ```sh
-npm run build
-NAVARCH_API_BASE=https://navarch.example.com npm run register -- --token <enrollment-token> --name my-machine-1
-npm run supervise
+npx --yes @sagentlab/navarch-runtime@latest doctor \
+  --config-dir ~/.navarch/<project-slug>
 ```
 
-`register` is the one command that prints the machine's auth token — exactly
-once, to stdout. It is stored at `$NAVARCH_CONFIG_DIR/machine.json` (default
-`~/.navarch/machine.json`, mode `0600`) and never echoed again. For
-twelve-factor deployments (systemd `EnvironmentFile`, container secrets),
-skip `register` and set `NAVARCH_MACHINE_TOKEN` + `NAVARCH_MACHINE_ID`
-directly.
+For the BYO-key sandbox path, follow the generated Claude/Docker command
+exactly. Docker must be running, and `NAVARCH_DOCKER_IMAGE` must identify an
+image containing Git, Node.js 20 or later, Claude Code 2.1.83 or later, and
+the build/test tools required by the repository. The current default
+`node:20-slim` image does not satisfy those requirements; a first-party image
+is tracked in [issue #229](https://github.com/sagentlab/navarch/issues/229).
+The complete public flow is in
+[the Navarch quickstart](../docs/navarch/quickstart.md).
+
+### Install from source
 
-Run `node bin/navarch.cjs doctor` any time to print resolved config, Docker
-availability, and registration status without starting the daemon.
+Use this path for runtime development or when validating an unreleased runtime
+change:
+
+```sh
+git clone https://github.com/sagentlab/navarch.git
+cd navarch/runtime
+./install.sh
+node bin/navarch.cjs connect <options copied from Navarch>
+node bin/navarch.cjs supervise --config-dir ~/.navarch/<project-slug>
+```
+
+The installer checks Node, installs the locked package dependencies, and builds
+the runtime. The UI-generated npm commands remain the source of truth for the
+token, project, agent, capacity, API origin, and config directory; translate
+those same options to `node bin/navarch.cjs` for a source install.
+
+The operator-only `register` command enrolls a globally managed machine. It is
+not the normal public onboarding path. `register` prints the machine auth token
+once and stores the same `machine.json` identity used by `connect`. For
+twelve-factor deployments (systemd `EnvironmentFile`, container secrets), set
+`NAVARCH_MACHINE_TOKEN` and `NAVARCH_MACHINE_ID` directly.
 
 ### Connecting an agent to one project
 
@@ -60,7 +95,7 @@ project only (it will never be dispatched work from any other project).
 
 ```sh
 npx @sagentlab/navarch-runtime connect --token flmt_<...> --project <project-id> \
-    --name my-agent-1 --agent codex --api-base https://navarch.example.com \
+    --name my-agent-1 --agent codex --api-base https://www.sagentlab.com \
     --config-dir ~/.navarch/my-agent-1
 npx @sagentlab/navarch-runtime supervise --config-dir ~/.navarch/my-agent-1
 ```
@@ -74,10 +109,10 @@ The from-source flow — `git clone` + `./install.sh` + `node bin/navarch.cjs
 
 | Command | Purpose |
 |---|---|
-| `register --token <t> --name <n> [--agent claude-code\|codex] […]` | Registers this machine, saves its local agent choice, and prints the token once. |
-| `connect --token <t> --name <n> [--agent claude-code\|codex] [--project <id>] […]` | Connects this machine to one project, saves its local agent choice, and prints the token once. |
-| `start [--agent claude-code\|codex]` | Runs the daemon. A start-time agent choice overrides the saved choice. |
-| `supervise [--agent claude-code\|codex]` | Runs the daemon under the update supervisor, enabling drain-safe automatic updates and rollback. |
+| `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. |
 | `doctor` | Prints resolved config + Docker/registration status; no side effects. |
 
 ### Running multiple agents on one machine
@@ -117,7 +152,7 @@ restart, not a new dispatch:
 - The replacement turn uses the same worktree (and the same sandbox container
   in Docker mode), so committed and uncommitted changes from the interrupted
   turn remain available. It should inspect those changes before continuing.
-- The replacement turn is not a resumed Claude Code or Codex conversation.
+- The replacement turn is not a resumed agent CLI conversation.
   The corrected prompt carries the prior task context and guidance instead.
 - Transcript, token, and cost accounting is cumulative across turns: the
   upload includes every turn under a separate label, and reported token and
@@ -211,7 +246,7 @@ unchanged across the deployment.
 | `NAVARCH_CONFIG_DIR` | `~/.navarch` | Per-instance state root. Equivalent to `--config-dir`; use a different directory for every agent on the same host. |
 | `NAVARCH_WORKSPACE_ROOT` | `<config dir>/sandboxes` | Persistent bare repo caches plus isolated per-session worktrees. |
 | `NAVARCH_MAX_SESSIONS` | `5` | Local concurrent-session capacity cap — see `src/capacity.cts`. |
-| `NAVARCH_CAPABILITIES` | `shell` (`docker-sandbox,shell` in Docker mode) | Comma list reported at heartbeat/claim time. |
+| `NAVARCH_CAPABILITIES` | `shell,browser-use` (`docker-sandbox,shell` in Docker mode) | Comma list reported at heartbeat/claim time. Docker mode does not advertise browser use until the configured image provides it. |
 | `NAVARCH_OWNER_ZONE` | `sagentlab` | `sagentlab` or `customer-<slug>-premises` (project-plan.md §3.11). |
 | `NAVARCH_POLL_INTERVAL_MS` | `5000` | Claim-loop poll interval. |
 | `NAVARCH_HEARTBEAT_INTERVAL_MS` | `60000` | Machine-level heartbeat interval. |
@@ -219,16 +254,19 @@ unchanged across the deployment.
 | `NAVARCH_SESSION_TIMEOUT_MS` | `2700000` (45 min) | Hard kill timeout for a single session. |
 | `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` | `node:20-slim` | Image used for the per-session container. |
-| `NAVARCH_AGENT` | saved choice, then `claude-code` | Local choice of agent CLI: `claude-code` or `codex`. Overrides the choice saved by `connect`/`register`; `start --agent` has highest priority. |
+| `NAVARCH_DOCKER_IMAGE` | `node:20-slim` | Image used for the per-session container. The image must contain the selected agent CLI, Git, Node.js 20+, and project build/test tools; the default is only a low-level runtime fallback and is not sufficient for BYO-key sandbox sessions ([issue #229](https://github.com/sagentlab/navarch/issues/229)). |
+| `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_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`. |
 | `NAVARCH_CLAUDE_BIN` | `claude` | Path/name of the Claude Code CLI binary. |
 | `NAVARCH_CLAUDE_EXTRA_ARGS` | — | Comma list of extra CLI args appended after `--mcp-config` (Claude Code). `--allowedTools`/`--disallowedTools` layer rules onto auto mode; an explicit `--permission-mode`, `--permission-prompt-tool`, or bypass flag replaces the unattended default `--permission-mode auto`. |
 | `NAVARCH_CODEX_BIN` | `codex` | Path/name of the Codex CLI binary. |
 | `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_MCP_CONFIG_PATH` | — | Path to the platform MCP config passed as `--mcp-config`. |
-| `NAVARCH_WORKTREE_GUARD` | on | Host-mode Claude and Codex sessions get a per-session worktree boundary guard (see below). Set `off` to disable. |
+| `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. |
 
 ## Worktree boundary guard (host mode)
@@ -251,6 +289,12 @@ supported coding agents, using each CLI's native enforcement point:
   user or checked-in legacy `sandbox_mode` from silently disabling the
   generated profile; Codex authentication still comes from `CODEX_HOME`, and
   repository instructions such as `AGENTS.md` still load.
+- **Gemini:** the runtime uses Gemini CLI's native sandbox with only the
+  current worktree, shared gitdir, and approved extra roots mounted. The
+  lease MCP config is translated to a read-only temporary settings file;
+  header 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.
 
 The resulting boundary is:
 
@@ -284,12 +328,11 @@ The auto-review launch paths were verified live on 2026-07-20 with Claude Code
 permission profile plus `approvals_reviewer="auto_review"`). Both completed an
 unattended smoke task successfully.
 
-## Choosing an agent (Claude Code vs. Codex)
+## Choosing an agent
 
-Each machine chooses its own agent CLI. Pass `--agent` while connecting to
-persist the choice in local `machine.json`, override it for one daemon start
-with `start --agent`, or set `NAVARCH_AGENT` in the machine's service
-environment:
+Each worker advertises the agent CLIs it can actually execute. Existing
+single-runtime installs keep using `--agent`/`NAVARCH_AGENT`; multi-runtime
+workers set `NAVARCH_RUNTIMES` to the installed and authenticated adapters:
 
 ```sh
 # Claude Code (default) — requires the `claude` CLI installed and
@@ -300,12 +343,22 @@ export NAVARCH_AGENT=claude-code
 # this machine (or NAVARCH_CODEX_BIN pointing at it), analogous to the
 # Claude Code prerequisite above.
 export NAVARCH_AGENT=codex
+
+# Google Gemini CLI — requires an authenticated `gemini` CLI (or
+# NAVARCH_GEMINI_BIN pointing at it).
+export NAVARCH_AGENT=gemini
+
+# Or let one worker serve tasks selected for any installed adapter.
+export NAVARCH_RUNTIMES=claude-code,codex,gemini
 ```
 
-Priority is `start --agent` → `NAVARCH_AGENT` → the locally saved choice →
-`claude-code`. The control plane does not choose the adapter.
+For the legacy single-runtime setting, priority is `start --agent` →
+`NAVARCH_AGENT` → the locally saved choice → `claude-code`.
+`NAVARCH_RUNTIMES` expands what the worker advertises; the control plane then
+resolves `tasks.runtime_override` → `projects.default_runtime` and returns the
+selected adapter with the claim.
 
-Both adapters implement the same `AgentAdapter` interface
+All three 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
@@ -314,10 +367,12 @@ 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=...` or
-`claude -p --model ... --effort ...`) and records the effective model, profile,
-and effort on completion. Machine-wide extra arguments still configure other
-CLI behavior; project/task policy wins for model and effort.
+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.
 
 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
@@ -327,6 +382,12 @@ not placed in argv. The JSONL parser accepts the verified top-level
 `item.completed` / `turn.completed` shape and retains the older `msg`
 envelope as a compatibility fallback.
 
+The Gemini adapter uses official headless `--prompt` and `--output-format
+stream-json` flags. It resets pre-tool assistant text, retains the final
+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.
+
 ## Architecture
 
 ```
@@ -346,6 +407,7 @@ cli.cts
                   (adapters/types.cts) by NAVARCH_AGENT, then .run(...):
                     - claudeCodeAdapter (adapters/claude.cts) — `claude -p <prompt> --mcp-config <path>`
                     - codexAdapter      (adapters/codex.cts)  — `codex exec <prompt> --json -c mcp_servers.*=...`
+                    - geminiAdapter     (adapters/gemini.cts) — `gemini --prompt <prompt> --output-format stream-json`
                   heartbeating the lease every NAVARCH_LEASE_HEARTBEAT_INTERVAL_MS throughout either;
                   a failed heartbeat aborts the run (kills the process) and marks the outcome as lease-lost
                5. mapExitCondition (exit-conditions.cts) → redact.cts scrubs the transcript → upload.cts PUTs it
@@ -360,7 +422,7 @@ cli.cts
 
 `adapter.cts` (top-level) is now a backward-compat re-export of
 `adapters/claude.cts` — new code should import `adapters/index.cts` (for
-`selectAdapter`) or `adapters/claude.cts` / `adapters/codex.cts` directly.
+`selectAdapter`) or an adapter module directly.
 
 `api.cts` is the single choke point for every HTTP call; nothing else in the
 package talks to `fetch` directly for control-plane traffic.
@@ -411,8 +473,8 @@ tests cover:
   plus Claude's and Codex's usage/report parsing (`tests/exit-conditions.test.cts`).
 - `redact.cts` — exact-value and pattern-based redaction (`tests/redact.test.cts`).
 - `capacity.cts` — capacity math and acquire/release bookkeeping (`tests/capacity.test.cts`).
-- `config.cts` — env var parsing and defaults, including `NAVARCH_AGENT`/
-  `NAVARCH_CODEX_BIN`/`NAVARCH_CODEX_EXTRA_ARGS` (`tests/config.test.cts`).
+- `config.cts` — env var parsing and defaults for every selectable adapter
+  (`tests/config.test.cts`).
 - `sandbox.cts` — command construction (flags, env-via-stdin, credential-helper
   argv hygiene) against an injected fake `CommandRunner`, plus `isDockerAvailable()`
   degrading to `false` instead of throwing when Docker is absent (`tests/sandbox.test.cts`).
@@ -422,6 +484,11 @@ tests cover:
 - `adapters/codex.cts` — arg construction on both the host path (mocked `spawn`)
   and the docker-exec path (fake `CommandRunner`), and usage/report-text
   attachment from fixed JSONL fixtures (`tests/adapters/codex.test.cts`).
+- `adapters/gemini.cts` — host/Docker invocation, cancellation, sandbox/MCP
+  credential hygiene, parser drift, and normalized report/usage extraction
+  (`tests/adapters/gemini.test.cts`).
+- `adapters/types.cts` — the shared process-result boundary is exercised for
+  Claude, Codex, and Gemini (`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
@@ -454,6 +521,8 @@ secrets absent from disk after exit"):
   flags, per-run MCP override keys, stdin behavior, and JSONL event/usage
   shape are now verified locally; the next dogfood run covers their
   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.
 - 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/claude.cjs

@@ -12,7 +12,7 @@ const exit_conditions_cjs_1 = require("../exit-conditions.cjs");
  * exit-conditions.cts#parseClaudeJsonResult) for exit-conditions.cts to map
  * onto a complete()/fail() call.
  *
- * This is one of two implementations of the AgentAdapter interface
+ * This is one implementation of the AgentAdapter interface
  * (adapters/types.cts) — see adapters/codex.cts for the Codex CLI sibling
  * session.cts picks between via NAVARCH_AGENT (config.cts's `agentType`).
  *

package/dist/adapters/gemini.cjs

@@ -0,0 +1,229 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.geminiAdapter = void 0;
+exports.runGeminiAdapter = runGeminiAdapter;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+/**
+ * Headless Google Gemini CLI adapter. Gemini's `stream-json` output gives the
+ * same normalized boundary as the Claude and Codex adapters: raw process
+ * signals plus an optional final report and token counts. Gemini CLI does not
+ * report USD cost, so costUsd remains absent.
+ *
+ * The CLI reads MCP servers from settings rather than accepting Claude's
+ * `--mcp-config` flag. The adapter converts the lease-scoped config into a
+ * temporary system-settings file and restricts the run to those server names.
+ */
+async function runGeminiAdapter(options) {
+    const args = ["--prompt", options.prompt];
+    const env = { ...options.env };
+    if (!hasArg(options.extraArgs, "--output-format", "-o")) {
+        args.push("--output-format", "stream-json");
+    }
+    if (!hasArg(options.extraArgs, "--skip-trust")) {
+        args.push("--skip-trust");
+    }
+    if (!hasExplicitApprovalMode(options.extraArgs)) {
+        // Navarch sessions have no interactive operator. Host sessions still use
+        // Gemini's sandbox below when the worktree guard is enabled.
+        args.push("--approval-mode", "yolo");
+    }
+    const sandboxMounts = [...(options.geminiSandboxMounts ?? [])];
+    if (options.mcpConfigPath) {
+        const mcp = await prepareGeminiMcpSettings(options.mcpConfigPath, env);
+        env.GEMINI_CLI_SYSTEM_SETTINGS_PATH = mcp.settingsPath;
+        sandboxMounts.push(`${mcp.settingsPath}:${mcp.settingsPath}:ro`);
+        if (mcp.serverNames.length > 0 && !hasArg(options.extraArgs, "--allowed-mcp-server-names")) {
+            args.push("--allowed-mcp-server-names", mcp.serverNames.join(","));
+        }
+    }
+    if (!hasArg(options.extraArgs, "--sandbox", "-s")) {
+        if (options.geminiSandboxMounts) {
+            args.push("--sandbox");
+            env.SANDBOX_MOUNTS = sandboxMounts.join(",");
+        }
+        else {
+            // YOLO mode enables Gemini's own sandbox implicitly. Disable that
+            // nested sandbox when Navarch already supplied Docker isolation, or
+            // when an operator explicitly disabled the host worktree guard.
+            args.push("--sandbox=false");
+        }
+    }
+    args.push(...options.extraArgs);
+    if (options.model)
+        args.push("--model", options.model);
+    const runOptions = { ...options, env };
+    const raw = runOptions.dockerExec
+        ? await runViaDocker(runOptions, args)
+        : await runOnHost(runOptions, args);
+    return attachGeminiOutput(raw);
+}
+function hasArg(args, ...flags) {
+    return args.some((arg) => flags.some((flag) => arg === flag || arg.startsWith(`${flag}=`)));
+}
+function hasExplicitApprovalMode(args) {
+    return hasArg(args, "--approval-mode", "--yolo", "-y");
+}
+async function prepareGeminiMcpSettings(mcpConfigPath, env) {
+    const parsed = JSON.parse(await node_fs_1.promises.readFile(mcpConfigPath, "utf8"));
+    const mcpServers = {};
+    for (const [name, server] of Object.entries(parsed.mcpServers ?? {})) {
+        const httpUrl = server.httpUrl ?? (server.type === "http" ? server.url : undefined);
+        if (!httpUrl && !server.url)
+            continue;
+        const headers = {};
+        let headerIndex = 0;
+        for (const [header, value] of Object.entries(server.headers ?? {})) {
+            const envName = `NAVARCH_GEMINI_MCP_${safeEnvSegment(name)}_${headerIndex++}`;
+            env[envName] = value;
+            headers[header] = `\${${envName}}`;
+        }
+        mcpServers[name] = {
+            ...(httpUrl ? { httpUrl } : { url: server.url }),
+            ...(Object.keys(headers).length > 0 ? { headers } : {}),
+        };
+    }
+    const settingsPath = `${mcpConfigPath}.gemini-settings.json`;
+    await node_fs_1.promises.writeFile(settingsPath, JSON.stringify({ mcpServers }, null, 2), { mode: 0o600 });
+    await node_fs_1.promises.chmod(settingsPath, 0o600);
+    return { settingsPath, serverNames: Object.keys(mcpServers) };
+}
+function safeEnvSegment(value) {
+    return value.toUpperCase().replace(/[^A-Z0-9_]/g, "_");
+}
+function parseGeminiStream(stdout) {
+    const events = [];
+    for (const line of stdout.split(/\r?\n/)) {
+        if (!line.trim())
+            continue;
+        try {
+            const event = JSON.parse(line);
+            if (event && typeof event === "object")
+                events.push(event);
+        }
+        catch {
+            // Parser drift must not turn a successfully completed CLI run into a
+            // runtime crash. Unknown lines remain available in the transcript.
+        }
+    }
+    return events;
+}
+function attachGeminiOutput(result) {
+    const events = parseGeminiStream(result.stdout);
+    if (events.length === 0)
+        return result;
+    let reportText = "";
+    let tokensIn;
+    let tokensOut;
+    for (const event of events) {
+        if (event.type === "tool_use") {
+            // Gemini emits pre-tool assistant text as message deltas. Only retain
+            // the answer produced after the last tool call as the completion report.
+            reportText = "";
+        }
+        else if (event.type === "message" &&
+            event.role === "assistant" &&
+            typeof event.content === "string") {
+            reportText = event.delta === false ? event.content : reportText + event.content;
+        }
+        else if (event.type === "result" && event.stats) {
+            const reportedInput = nonNegativeMetric(event.stats.input_tokens);
+            const reportedOutput = nonNegativeMetric(event.stats.output_tokens);
+            if (reportedInput !== undefined)
+                tokensIn = reportedInput;
+            if (reportedOutput !== undefined)
+                tokensOut = reportedOutput;
+        }
+    }
+    return {
+        ...result,
+        ...(tokensIn !== undefined ? { tokensIn } : {}),
+        ...(tokensOut !== undefined ? { tokensOut } : {}),
+        ...(reportText.trim() ? { reportText: reportText.trim() } : {}),
+    };
+}
+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", (err) => {
+            clearTimeout(timer);
+            options.signal?.removeEventListener("abort", onAbort);
+            stderr += `\n${String(err)}`;
+            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 command = `[ -f /tmp/session.env ] && . /tmp/session.env; cd repo 2>/dev/null; ${[
+        options.bin,
+        ...args,
+    ].map(shellQuote).join(" ")}`;
+    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 (err) {
+        return {
+            exitCode: null,
+            timedOut: false,
+            killedByLeaseLoss,
+            stdout: "",
+            stderr: String(err),
+        };
+    }
+    finally {
+        options.signal?.removeEventListener("abort", onAbort);
+    }
+}
+function shellQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+exports.geminiAdapter = {
+    agentType: "gemini",
+    run: runGeminiAdapter,
+};

package/dist/adapters/index.cjs

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.runCodexAdapter = exports.codexAdapter = exports.runClaudeCodeAdapter = exports.claudeCodeAdapter = void 0;
+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; } });
@@ -8,6 +8,9 @@ Object.defineProperty(exports, "runClaudeCodeAdapter", { enumerable: true, get:
 const codex_cjs_1 = require("./codex.cjs");
 Object.defineProperty(exports, "codexAdapter", { enumerable: true, get: function () { return codex_cjs_1.codexAdapter; } });
 Object.defineProperty(exports, "runCodexAdapter", { enumerable: true, get: function () { return codex_cjs_1.runCodexAdapter; } });
+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; } });
 /**
  * Picks the AgentAdapter (adapters/types.cts) session.cts should run a
  * session with, keyed off config.cts's `agentType` (NAVARCH_AGENT). This is
@@ -19,10 +22,12 @@ function selectAdapter(agentType) {
     switch (agentType) {
         case "codex":
             return codex_cjs_1.codexAdapter;
+        case "gemini":
+            return gemini_cjs_1.geminiAdapter;
         case "claude-code":
             return claude_cjs_1.claudeCodeAdapter;
         default: {
-            // Exhaustiveness guard: config.cts only ever produces the two values
+            // Exhaustiveness guard: config.cts only ever produces the values
             // above, but fall back to Claude Code rather than throwing if this
             // widens in the future without every caller being updated.
             const _exhaustive = agentType;

package/dist/api.cjs

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.NavarchApiClient = exports.NavarchApiError = void 0;
+exports.NavarchApiClient = exports.NavarchTransportError = exports.NavarchApiError = void 0;
 class NavarchApiError extends Error {
     status;
     body;
@@ -12,6 +12,18 @@ class NavarchApiError extends Error {
     }
 }
 exports.NavarchApiError = NavarchApiError;
+/** A request that failed before the control plane returned an HTTP response. */
+class NavarchTransportError extends Error {
+    method;
+    endpoint;
+    constructor(method, endpoint, cause) {
+        super(`Navarch API ${method} ${endpoint} transport failed: ${describeError(cause)}`, { cause });
+        this.method = method;
+        this.endpoint = endpoint;
+        this.name = "NavarchTransportError";
+    }
+}
+exports.NavarchTransportError = NavarchTransportError;
 /**
  * Typed client for the Navarch control-plane API surface WP-07 depends on:
  * dispatch/claim, per-lease heartbeat, complete, and broker/issue
@@ -44,11 +56,20 @@ class NavarchApiClient {
             }
             headers.authorization = `Bearer ${this.token}`;
         }
-        const response = await this.fetchImpl(`${this.baseUrl}${pathname}`, {
-            method,
-            headers,
-            body: body === undefined ? undefined : JSON.stringify(body),
-        });
+        const requestUrl = `${this.baseUrl}${pathname}`;
+        let response;
+        try {
+            response = await this.fetchImpl(requestUrl, {
+                method,
+                headers,
+                body: body === undefined ? undefined : JSON.stringify(body),
+            });
+        }
+        catch (err) {
+            // Include enough request/cause context to diagnose DNS, connection, and
+            // TLS failures. Deliberately omit headers and URL credentials/query data.
+            throw new NavarchTransportError(method, safeEndpoint(requestUrl, pathname), err);
+        }
         if (response.status === 204)
             return null;
         const text = await response.text();
@@ -133,3 +154,25 @@ function safeJsonParse(text) {
         return null;
     }
 }
+function safeEndpoint(requestUrl, pathname) {
+    try {
+        const parsed = new URL(requestUrl);
+        return `${parsed.origin}${parsed.pathname}`;
+    }
+    catch {
+        return pathname;
+    }
+}
+function describeError(err) {
+    if (!(err instanceof Error))
+        return String(err);
+    let detail = `${err.name}: ${err.message}`;
+    const cause = err.cause;
+    if (cause instanceof Error) {
+        detail += `; cause: ${cause.name}: ${cause.message}`;
+    }
+    else if (cause && typeof cause === "object" && "code" in cause) {
+        detail += `; cause code: ${String(cause.code)}`;
+    }
+    return detail;
+}

package/dist/claim-loop.cjs

@@ -5,6 +5,7 @@ const node_crypto_1 = require("node:crypto");
 const api_cjs_1 = require("./api.cjs");
 const logger_cjs_1 = require("./logger.cjs");
 const log = (0, logger_cjs_1.createLogger)("claim");
+const MAX_CLAIM_BACKOFF_MS = 60_000;
 /**
  * Polls dispatch/claim on an interval, gated by available capacity
  * (implementation-plan.md WP-07 "Claim loop: poll dispatch, receive context
@@ -20,6 +21,8 @@ class ClaimLoop {
     timer = null;
     stopped = false;
     claimInFlight = false;
+    consecutiveFailures = 0;
+    nextClaimAt = 0;
     quiescenceWaiters = new Set();
     constructor(api, config, capacity, runSession) {
         this.api = api;
@@ -31,6 +34,8 @@ class ClaimLoop {
         if (this.timer)
             return;
         this.stopped = false;
+        this.consecutiveFailures = 0;
+        this.nextClaimAt = 0;
         this.timer = setInterval(() => void this.tick(), this.config.pollIntervalMs);
     }
     stop() {
@@ -52,7 +57,10 @@ class ClaimLoop {
         await new Promise((resolve) => this.quiescenceWaiters.add(resolve));
     }
     async tick() {
-        if (this.stopped || this.claimInFlight || !this.capacity.hasCapacity())
+        if (this.stopped ||
+            this.claimInFlight ||
+            !this.capacity.hasCapacity() ||
+            Date.now() < this.nextClaimAt)
             return;
         this.claimInFlight = true;
         try {
@@ -64,8 +72,14 @@ class ClaimLoop {
                 available_capacity: this.capacity.available(),
                 capabilities: this.config.capabilities,
                 agent_type: this.config.agentType,
+                runtimes: this.config.runtimes,
                 session_id: sessionId,
             });
+            if (this.consecutiveFailures > 0) {
+                log.info(`claim polling recovered after ${this.consecutiveFailures} failed attempt(s)`);
+            }
+            this.consecutiveFailures = 0;
+            this.nextClaimAt = 0;
             if (!claimed)
                 return;
             this.capacity.acquire(claimed.lease_id);
@@ -75,16 +89,20 @@ class ClaimLoop {
                 .finally(() => this.capacity.release(claimed.lease_id));
         }
         catch (err) {
+            this.consecutiveFailures += 1;
+            const retryDelayMs = Math.min(MAX_CLAIM_BACKOFF_MS, this.config.pollIntervalMs * 2 ** this.consecutiveFailures);
+            this.nextClaimAt = Date.now() + retryDelayMs;
             // NavarchApiError's message is only the status line ("… failed with
             // 500"); the control plane's actual error text lives in `.body`. Log it
             // so a server-side claim failure is diagnosable from the runtime alone
             // instead of an opaque bare status.
             if (err instanceof api_cjs_1.NavarchApiError) {
                 const detail = typeof err.body === "string" ? err.body : JSON.stringify(err.body);
-                log.warn(`claim failed: ${err.message}${detail ? ` — ${detail}` : ""}`);
+                log.warn(`claim failed (attempt ${this.consecutiveFailures}; retrying in ${retryDelayMs}ms): ` +
+                    `${err.message}${detail ? ` — ${detail}` : ""}`);
             }
             else {
-                log.warn(`claim failed: ${String(err)}`);
+                log.warn(`claim failed (attempt ${this.consecutiveFailures}; retrying in ${retryDelayMs}ms): ${String(err)}`);
             }
         }
         finally {

package/dist/cli.cjs

@@ -65,7 +65,7 @@ function agentFromFlag(flags) {
     if (value === undefined)
         return undefined;
     if (!(0, config_cjs_1.isRuntimeAgentType)(value)) {
-        throw new Error("--agent must be either 'claude-code' or 'codex'.");
+        throw new Error("--agent must be one of 'claude-code', 'codex', or 'gemini'.");
     }
     return value;
 }
@@ -276,11 +276,11 @@ function helpText() {
 
 Usage:
   navarch-runtime register --token <enrollment-token> --name <machine-name> \\
-      [--config-dir <path>] [--agent claude-code|codex] [--capabilities a,b] [--max-sessions N] [--owner-zone z] [--api-base url]
+      [--config-dir <path>] [--agent claude-code|codex|gemini] [--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] [--project <project-id>] [--capabilities a,b] [--max-sessions N] [--api-base url]
-  navarch-runtime start [--config-dir <path>] [--agent claude-code|codex]
-  navarch-runtime supervise [--config-dir <path>] [--agent claude-code|codex]
+      [--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]
   navarch-runtime doctor [--config-dir <path>]
 
 Use a different --config-dir (or NAVARCH_CONFIG_DIR) for every agent instance.

package/dist/config.cjs

@@ -8,7 +8,7 @@ exports.loadRuntimeConfig = loadRuntimeConfig;
 const node_path_1 = __importDefault(require("node:path"));
 const node_os_1 = __importDefault(require("node:os"));
 function isRuntimeAgentType(value) {
-    return value === "claude-code" || value === "codex";
+    return value === "claude-code" || value === "codex" || value === "gemini";
 }
 function envInt(env, name, fallback) {
     const raw = env[name];
@@ -38,7 +38,9 @@ function loadRuntimeConfig(env = process.env) {
     // default. Docker isolation is an explicit operator opt-in, not a
     // prerequisite for claiming ordinary shell work.
     const sandboxMode = env.NAVARCH_SANDBOX_MODE === "docker" ? "docker" : "host";
-    const defaultCapabilities = sandboxMode === "docker" ? ["docker-sandbox", "shell"] : ["shell"];
+    const defaultCapabilities = sandboxMode === "docker" ? ["docker-sandbox", "shell"] : ["shell", "browser-use"];
+    const agentType = isRuntimeAgentType(env.NAVARCH_AGENT) ? env.NAVARCH_AGENT : "claude-code";
+    const runtimes = envList(env, "NAVARCH_RUNTIMES", [agentType]).filter(isRuntimeAgentType);
     return {
         apiBase: env.NAVARCH_API_BASE ?? "http://localhost:3000",
         workspaceRoot: env.NAVARCH_WORKSPACE_ROOT ?? node_path_1.default.join(configDir, "sandboxes"),
@@ -52,11 +54,14 @@ function loadRuntimeConfig(env = process.env) {
         // interval must stay comfortably under that TTL.
         leaseHeartbeatIntervalMs,
         sessionTimeoutMs: envInt(env, "NAVARCH_SESSION_TIMEOUT_MS", 45 * 60 * 1000),
-        agentType: isRuntimeAgentType(env.NAVARCH_AGENT) ? env.NAVARCH_AGENT : "claude-code",
+        agentType,
+        runtimes: runtimes.length > 0 ? runtimes : [agentType],
         claudeBin: env.NAVARCH_CLAUDE_BIN ?? "claude",
         claudeExtraArgs: envList(env, "NAVARCH_CLAUDE_EXTRA_ARGS", []),
         codexBin: env.NAVARCH_CODEX_BIN ?? "codex",
         codexExtraArgs: envList(env, "NAVARCH_CODEX_EXTRA_ARGS", []),
+        geminiBin: env.NAVARCH_GEMINI_BIN ?? "gemini",
+        geminiExtraArgs: envList(env, "NAVARCH_GEMINI_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/machine-store.cjs

@@ -48,7 +48,9 @@ async function resolveMachineIdentity(configDir, apiBaseFallback) {
             token: envToken,
             name: process.env.NAVARCH_MACHINE_NAME ?? envId,
             api_base: process.env.NAVARCH_API_BASE ?? apiBaseFallback,
-            agent_type: process.env.NAVARCH_AGENT === "codex" || process.env.NAVARCH_AGENT === "claude-code"
+            agent_type: process.env.NAVARCH_AGENT === "codex" ||
+                process.env.NAVARCH_AGENT === "claude-code" ||
+                process.env.NAVARCH_AGENT === "gemini"
                 ? process.env.NAVARCH_AGENT
                 : undefined,
         };

package/dist/session.cjs

@@ -22,7 +22,7 @@ const worktree_guard_cjs_1 = require("./worktree-guard.cjs");
 /** Filename the generated platform MCP config is written under inside the session metadata directory. */
 const MCP_CONFIG_FILENAME = "mcp-config.json";
 const GIT_CREDENTIAL_HELPER_FILENAME = "git-credential-navarch.cjs";
-const PR_REQUIRED_COMPLETION_RETRIES = 2;
+const COMPLETION_REMEDIATION_RETRIES = 2;
 const log = (0, logger_cjs_1.createLogger)("session");
 /**
  * Runs one claimed task end to end (implementation-plan.md WP-07):
@@ -30,8 +30,8 @@ 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 configured agent adapter (Claude Code or Codex, per
- *      NAVARCH_AGENT — adapters/index.cts#selectAdapter), heartbeating the
+ *   4. run the adapter selected by the claim (Claude Code, Codex, or Gemini;
+ *      adapters/index.cts#selectAdapter), heartbeating the
  *      lease throughout
  *   5. redact + upload the transcript, map the exit condition, complete the
  *      lease (recording which agent_type ran it)
@@ -46,9 +46,14 @@ const log = (0, logger_cjs_1.createLogger)("session");
 async function runSession(deps, claimed, sessionId) {
     const { api, config } = deps;
     const { lease_id: leaseId, task, context_bundle: bundle } = claimed;
+    const runtime = claimed.runtime ?? config.agentType;
     const execution = bundle.execution ?? {
         profile: task.execution_profile ?? "standard",
-        model: config.agentType === "codex" ? "gpt-5.6-sol" : "best",
+        model: runtime === "codex"
+            ? "gpt-5.6-sol"
+            : runtime === "gemini"
+                ? "auto"
+                : "best",
         reasoning_effort: "medium",
     };
     const executionReport = {
@@ -98,7 +103,7 @@ async function runSession(deps, claimed, sessionId) {
             evidence_urls: [],
             cost: { tokens_in: 0, tokens_out: 0, cost_usd: 0 },
             exit_status: "crashed",
-            agent_type: config.agentType,
+            agent_type: runtime,
             ...executionReport,
         });
         secrets = {};
@@ -122,6 +127,7 @@ async function runSession(deps, claimed, sessionId) {
     let pendingGuidance = [];
     let activeAbortController = null;
     let leaseLost = false;
+    let leaseGone = false;
     let heartbeatInFlight = null;
     const pollLease = () => {
         if (heartbeatInFlight)
@@ -146,6 +152,7 @@ async function runSession(deps, claimed, sessionId) {
             .catch((err) => {
             log.warn(`lease heartbeat failed for ${leaseId}: ${String(err)} — killing session.`);
             leaseLost = true;
+            leaseGone = isTerminalLeaseHeartbeatError(err);
             activeAbortController?.abort();
         })
             .finally(() => {
@@ -167,7 +174,7 @@ async function runSession(deps, claimed, sessionId) {
             evidence_urls: [],
             cost: { tokens_in: 0, tokens_out: 0, cost_usd: 0 },
             exit_status: "crashed",
-            agent_type: config.agentType,
+            agent_type: runtime,
             ...executionReport,
         })
             .catch((err) => log.warn(`complete() after docker-unavailable also failed: ${String(err)}`));
@@ -208,11 +215,12 @@ async function runSession(deps, claimed, sessionId) {
     // machine. Host-mode Claude gets a generated PreToolUse hook; host-mode
     // Codex gets an OS-enforced native permission profile over the same roots.
     // Docker mode already has a container boundary. NAVARCH_WORKTREE_GUARD=off
-    // opts out for either agent.
+    // opts out for any agent.
     let claudeSettingsPath = null;
     let codexGuardArgs;
+    let geminiGuardMounts;
     if (config.sandboxMode === "host" && config.worktreeGuard) {
-        if (config.agentType === "claude-code") {
+        if (runtime === "claude-code") {
             if (config.claudeExtraArgs.includes("--settings")) {
                 log.warn("NAVARCH_CLAUDE_EXTRA_ARGS supplies --settings; skipping the generated worktree-guard settings for this session.");
             }
@@ -227,7 +235,7 @@ async function runSession(deps, claimed, sessionId) {
                 claudeSettingsPath = guard.settingsPath;
             }
         }
-        else {
+        else if (runtime === "codex") {
             codexGuardArgs = (0, worktree_guard_cjs_1.codexWorktreeGuardArgs)({
                 workDir,
                 worktreePath: gitWorktree.worktreePath,
@@ -236,6 +244,15 @@ async function runSession(deps, claimed, sessionId) {
                 extraRoots: config.guardExtraRoots,
             });
         }
+        else {
+            geminiGuardMounts = (0, worktree_guard_cjs_1.geminiSandboxMounts)({
+                workDir,
+                worktreePath: gitWorktree.worktreePath,
+                repositoryPath: gitWorktree.repositoryPath,
+                workspaceRoot: config.workspaceRoot,
+                extraRoots: config.guardExtraRoots,
+            });
+        }
     }
     try {
         await gitWorktree.prepare();
@@ -243,17 +260,16 @@ async function runSession(deps, claimed, sessionId) {
             await sandbox.create();
             await sandbox.injectEnv(toEnvMap(secrets, gitCredentialRefresh, config.gitAuthorName, config.gitAuthorEmail));
         }
-        // Picks the Claude Code or Codex adapter per NAVARCH_AGENT
-        // (config.cts's `agentType`) — see adapters/index.cts#selectAdapter.
-        // Both adapters implement the same AgentAdapter.run() shape
+        // The control plane resolves the project default/task override before
+        // claim and returns one of this worker's advertised runtimes.
+        // All adapters implement the same AgentAdapter.run() shape
         // (adapters/types.cts), so nothing else in this function branches on
         // which agent is running.
-        const adapter = (0, index_cjs_1.selectAdapter)(config.agentType);
-        const bin = config.agentType === "codex" ? config.codexBin : config.claudeBin;
-        const extraArgs = config.agentType === "codex" ? config.codexExtraArgs : config.claudeExtraArgs;
+        const adapter = (0, index_cjs_1.selectAdapter)(runtime);
+        const { bin, extraArgs } = adapterCommand(config, runtime);
         const attempts = [];
         let nextPrompt = null;
-        let prRequiredCompletionRetries = 0;
+        let completionRemediationRetries = 0;
         while (true) {
             // Guidance can arrive while the worktree/sandbox is being prepared.
             // It is already included in deliveredGuidance, so clear the pending
@@ -279,6 +295,7 @@ async function runSession(deps, claimed, sessionId) {
                 env: toEnvMap(secrets, gitCredentialRefresh, config.gitAuthorName, config.gitAuthorEmail),
                 settingsPath: claudeSettingsPath,
                 codexGuardArgs,
+                geminiSandboxMounts: geminiGuardMounts,
                 cwd: sandbox ? undefined : gitWorktree.worktreePath,
                 dockerExec: sandbox ? { containerName: sandbox.name, runner: sandbox_cjs_1.nodeCommandRunner } : undefined,
                 signal: activeAbortController.signal,
@@ -287,8 +304,15 @@ async function runSession(deps, claimed, sessionId) {
             attempts.push(turnResult);
             // Close the small race between a naturally completed turn and the next
             // scheduled heartbeat. If guidance landed, run another turn before the
-            // lease can be completed.
-            await pollLease();
+            // lease can be completed. A terminal heartbeat response means the
+            // control plane has already disposed of the lease, so neither retry the
+            // heartbeat nor attempt completion against that stale lease.
+            if (!leaseGone)
+                await pollLease();
+            if (leaseGone) {
+                log.warn(`session ${leaseId} stopped without completion because its lease is no longer active.`);
+                return;
+            }
             if (!leaseLost && pendingGuidance.length > 0)
                 continue;
             const result = {
@@ -349,7 +373,7 @@ async function runSession(deps, claimed, sessionId) {
                 },
                 transcript_url: transcriptUrl,
                 exit_status: mapping.exitStatus,
-                agent_type: config.agentType,
+                agent_type: runtime,
                 ...executionReport,
             };
             try {
@@ -357,17 +381,21 @@ async function runSession(deps, claimed, sessionId) {
                 break;
             }
             catch (err) {
-                const rejection = mapping.leaseOutcome === "completed" ? prRequiredRejectionMessage(err) : null;
+                if (isAlreadyReleasedCompletionError(err)) {
+                    log.warn(`completion skipped for ${leaseId}: the lease was already released.`);
+                    return;
+                }
+                const rejection = mapping.leaseOutcome === "completed" ? completionRemediationMessage(err) : null;
                 if (!rejection)
                     throw err;
                 const redactedRejection = (0, redact_cjs_1.redactText)(rejection, knownSecrets);
-                if (prRequiredCompletionRetries < PR_REQUIRED_COMPLETION_RETRIES) {
-                    prRequiredCompletionRetries += 1;
-                    log.warn(`completion for ${leaseId} requires a pull request; restarting agent turn ${prRequiredCompletionRetries}/${PR_REQUIRED_COMPLETION_RETRIES} in the same worktree.`);
+                if (completionRemediationRetries < COMPLETION_REMEDIATION_RETRIES) {
+                    completionRemediationRetries += 1;
+                    log.warn(`completion for ${leaseId} needs more work; restarting agent turn ${completionRemediationRetries}/${COMPLETION_REMEDIATION_RETRIES} in the same worktree.`);
                     nextPrompt = redactedRejection;
                     continue;
                 }
-                log.warn(`completion for ${leaseId} still requires a pull request after ${PR_REQUIRED_COMPLETION_RETRIES} retries; failing with the control-plane rejection.`);
+                log.warn(`completion for ${leaseId} is still not ready after ${COMPLETION_REMEDIATION_RETRIES} retries; failing with the control-plane rejection.`);
                 await api.completeLease(leaseId, {
                     ...completion,
                     status: "failed",
@@ -390,7 +418,7 @@ async function runSession(deps, claimed, sessionId) {
             evidence_urls: [],
             cost: { tokens_in: 0, tokens_out: 0, cost_usd: 0 },
             exit_status: "crashed",
-            agent_type: config.agentType,
+            agent_type: runtime,
             ...executionReport,
         })
             .catch((completeErr) => log.warn(`complete() after crash also failed: ${String(completeErr)}`));
@@ -405,6 +433,16 @@ async function runSession(deps, claimed, sessionId) {
         await node_fs_1.promises.rm(workDir, { recursive: true, force: true }).catch(() => undefined);
     }
 }
+function adapterCommand(config, runtime) {
+    switch (runtime) {
+        case "claude-code":
+            return { bin: config.claudeBin, extraArgs: config.claudeExtraArgs };
+        case "codex":
+            return { bin: config.codexBin, extraArgs: config.codexExtraArgs };
+        case "gemini":
+            return { bin: config.geminiBin, extraArgs: config.geminiExtraArgs };
+    }
+}
 function sumReportedUsage(attempts, key) {
     const reported = attempts.flatMap((attempt) => {
         const value = attempt[key];
@@ -412,16 +450,28 @@ function sumReportedUsage(attempts, key) {
     });
     return reported.length > 0 ? reported.reduce((sum, value) => sum + value, 0) : undefined;
 }
-function prRequiredRejectionMessage(err) {
+function completionRemediationMessage(err) {
     if (!(err instanceof api_cjs_1.NavarchApiError) || err.status !== 409)
         return null;
     if (typeof err.body !== "object" || err.body === null || Array.isArray(err.body))
         return null;
     const body = err.body;
-    return body.code === "pr_required" && typeof body.error === "string"
+    return (body.code === "pr_required" || body.code === "pr_not_ready") &&
+        typeof body.error === "string"
         ? body.error
         : null;
 }
+function isTerminalLeaseHeartbeatError(err) {
+    return err instanceof api_cjs_1.NavarchApiError && [403, 404, 410].includes(err.status);
+}
+function isAlreadyReleasedCompletionError(err) {
+    if (!(err instanceof api_cjs_1.NavarchApiError) || err.status !== 409)
+        return false;
+    if (typeof err.body !== "object" || err.body === null || Array.isArray(err.body))
+        return false;
+    const body = err.body;
+    return body.error === "lease already released";
+}
 /** Uppercases + sanitizes secret names into shell-safe env var names for injectEnv(). */
 function toEnvMap(secrets, credentialRefreshOrAuthorName, gitAuthorNameOrEmail = "sagentlab", gitAuthorEmail = "z@sagentlab.com") {
     // Keep the existing `(secrets, authorName, authorEmail)` call shape while

package/dist/worktree-guard.cjs

@@ -5,9 +5,12 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.guardHookScriptPath = guardHookScriptPath;
 exports.prepareWorktreeGuard = prepareWorktreeGuard;
+exports.codexToolReadRoots = codexToolReadRoots;
 exports.codexWorktreeGuardArgs = codexWorktreeGuardArgs;
+exports.geminiSandboxMounts = geminiSandboxMounts;
 const node_path_1 = __importDefault(require("node:path"));
 const node_fs_1 = require("node:fs");
+const node_os_1 = __importDefault(require("node:os"));
 const CODEX_GUARD_PROFILE = "navarch-worktree";
 /**
  * Tools the hook screens. Everything else — the lease-scoped Navarch MCP
@@ -55,6 +58,33 @@ async function prepareWorktreeGuard(options) {
     await node_fs_1.promises.writeFile(settingsPath, JSON.stringify(settings, null, 2), "utf8");
     return { settingsPath, configPath, hookScriptPath };
 }
+/**
+ * Read-only roots required by Codex's own tools and installed skills.
+ *
+ * Deliberately exclude the CODEX_HOME root itself: it may contain auth.json
+ * and user configuration. Package executables, installed skill instructions,
+ * plugin code, the operator's executable directory, and browser/toolchain
+ * installations are sufficient for helpers such as apply_patch, npm, gh, and
+ * browser evidence tooling.
+ */
+function codexToolReadRoots(env = process.env) {
+    const homeDir = env.HOME?.trim() || node_os_1.default.homedir();
+    const codexHome = env.CODEX_HOME?.trim() || node_path_1.default.join(homeDir, ".codex");
+    return [
+        node_path_1.default.join(codexHome, "packages"),
+        node_path_1.default.join(codexHome, "skills"),
+        node_path_1.default.join(codexHome, "plugins"),
+        node_path_1.default.join(homeDir, ".agents", "skills"),
+        node_path_1.default.join(homeDir, ".local", "bin"),
+        "/opt/homebrew",
+        // AppKit loads this bundle even for headless Chromium. Without it,
+        // Playwright browsers abort before launch on macOS with
+        // "required built-in appearance SystemAppearance not found".
+        "/System/Library/CoreServices/SystemAppearance.bundle",
+        node_path_1.default.join(homeDir, "Library", "Caches", "ms-playwright"),
+        node_path_1.default.join(homeDir, ".cache", "ms-playwright"),
+    ];
+}
 /**
  * Builds one-off Codex permission-profile arguments for a host session.
  *
@@ -78,6 +108,12 @@ function codexWorktreeGuardArgs(options) {
         [node_path_1.default.resolve(options.worktreePath)]: "write",
         [node_path_1.default.resolve(options.repositoryPath)]: "write",
     };
+    for (const root of codexToolReadRoots()) {
+        const resolved = node_path_1.default.resolve(root);
+        if (isPathInside(resolved, node_path_1.default.resolve(options.workspaceRoot)))
+            continue;
+        filesystem[resolved] = "read";
+    }
     for (const root of options.extraRoots ?? []) {
         const resolved = node_path_1.default.resolve(root);
         // Match the Claude hook's denied-root precedence: an extra root cannot
@@ -106,6 +142,21 @@ function codexWorktreeGuardArgs(options) {
         `permissions.${CODEX_GUARD_PROFILE}.network.enabled=true`,
     ];
 }
+/**
+ * Mounts only the current session roots into Gemini CLI's native sandbox.
+ * Gemini mounts cwd itself; explicit same-path mounts keep the shared gitdir
+ * and approved external roots reachable without exposing sibling sessions.
+ */
+function geminiSandboxMounts(options) {
+    const workspaceRoot = node_path_1.default.resolve(options.workspaceRoot);
+    const roots = [options.worktreePath, options.repositoryPath];
+    for (const root of options.extraRoots ?? []) {
+        const resolved = node_path_1.default.resolve(root);
+        if (!isPathInside(resolved, workspaceRoot))
+            roots.push(resolved);
+    }
+    return [...new Set(roots.map((root) => node_path_1.default.resolve(root)))].map((root) => `${root}:${root}:rw`);
+}
 function isPathInside(candidate, root) {
     const relative = node_path_1.default.relative(root, candidate);
     return relative === "" || (!relative.startsWith("..") && !node_path_1.default.isAbsolute(relative));

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sagentlab/navarch-runtime",
-  "version": "0.1.10",
-  "description": "Navarch machine-side session manager: registers a machine, claims tasks from the control-plane dispatcher, runs them via the Claude Code or Codex adapter, and reports results back.",
+  "version": "0.1.12",
+  "description": "Navarch machine-side session manager: claims delivery tasks and runs them through Claude Code, Codex, or Gemini CLI.",
   "type": "commonjs",
   "license": "MIT",
   "repository": {
@@ -15,10 +15,11 @@
     "ai-agent",
     "claude-code",
     "codex",
+    "gemini-cli",
     "task-runner"
   ],
   "bin": {
-    "navarch-runtime": "./bin/navarch.cjs"
+    "navarch-runtime": "bin/navarch.cjs"
   },
   "files": [
     "dist",