@sagentlab/navarch-runtime 0.1.107 → 0.1.111

package/README.md

@@ -4,7 +4,7 @@
 
 Host-mode build, verify, and QA leases requiring `browser-use` receive a
 `navarch_browser` MCP server with `capture_visual_evidence` in Codex, Claude,
-Gemini, OpenCode, and ACP sessions. It runs Chromium in the runtime process's
+Antigravity, OpenCode, and ACP sessions. It runs Chromium in the runtime process's
 environment, outside the coding agent's OS sandbox, with a fresh browser
 context for desktop and touch-enabled mobile captures. It neither uses the
 operator's browser profile nor executes agent-provided scripts.
@@ -93,7 +93,7 @@ when the run finishes, so the task view can follow a connected run live.
 Live snapshots hold the current turn's stderr back until the turn ends.
 
 The machine operator selects **Claude Code**, **OpenAI Codex**, **Google
-Gemini CLI**, **OpenCode**, or an **Agent Client Protocol (ACP)** agent when connecting a worker. Any selected agent can
+Antigravity CLI**, **OpenCode**, or an **Agent Client Protocol (ACP)** agent when connecting a worker. Any selected agent can
 run any unpinned project task; task eligibility depends on capabilities and
 project gates. A task pinned to a runtime waits for a worker that advertises
 that adapter and runs on it — see "Choosing an agent" below.
@@ -116,7 +116,7 @@ Before generating the command, prepare the machine:
 - install Node.js 20 or later (the standard installation includes `npm` and
   `npx`) and Git;
 - install the coding-agent CLI selected in Navarch — `claude`, `codex`,
-  `gemini`, `opencode`, `dsh` for the default ACP integration, or `qoder` — and complete its normal authentication flow; and
+  `agy`, `opencode`, `dsh` for the default ACP integration, or `qoder` — and complete its normal authentication flow; and
 - for Docker-backed sessions, install and start Docker and use an image that
   contains the selected agent CLI and the repository toolchain, with provider
   credentials supplied through the approved machine or project configuration.
@@ -131,7 +131,7 @@ node --version       # 20 or later
 npm --version
 npx --version
 git --version
-codex --version      # or: claude / gemini / opencode / qoder / dsh --version
+codex --version      # or: claude / agy / opencode / qoder / dsh --version
 ```
 
 Every command above must succeed before the long-running worker starts. See
@@ -239,11 +239,11 @@ The from-source flow — `git clone` + `./install.sh` + `node bin/navarch.cjs
 
 | Command | Purpose |
 |---|---|
-| `register --token <t> --name <n> [--agent claude-code\|codex\|gemini\|opencode\|acp\|qoder] […]` | Registers this machine, saves its local agent choice, and prints the token once. |
-| `connect --token <t> --name <n> [--agent claude-code\|codex\|gemini\|opencode\|acp\|qoder] [--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\|acp\|qoder]` | Runs the daemon. A start-time agent choice overrides the saved choice. |
-| `supervise [--agent claude-code\|codex\|gemini\|opencode\|acp\|qoder]` | Runs the daemon under the update supervisor, enabling drain-safe automatic updates and rollback. |
-| `doctor [--agent claude-code\|codex\|gemini\|opencode\|acp\|qoder]` | Prints resolved config + Docker/registration status; no side effects. |
+| `register --token <t> --name <n> [--agent claude-code\|codex\|antigravity\|opencode\|acp\|qoder] […]` | Registers this machine, saves its local agent choice, and prints the token once. |
+| `connect --token <t> --name <n> [--agent claude-code\|codex\|antigravity\|opencode\|acp\|qoder] [--project <id>] […]` | Connects this machine to one project, saves its local agent choice, and prints the token once. |
+| `start [--agent claude-code\|codex\|antigravity\|opencode\|acp\|qoder]` | Runs the daemon. A start-time agent choice overrides the saved choice. |
+| `supervise [--agent claude-code\|codex\|antigravity\|opencode\|acp\|qoder]` | Runs the daemon under the update supervisor, enabling drain-safe automatic updates and rollback. |
+| `doctor [--agent claude-code\|codex\|antigravity\|opencode\|acp\|qoder]` | Prints resolved config + Docker/registration status; no side effects. |
 
 ### Running multiple agents on one machine
 
@@ -457,7 +457,7 @@ unchanged across the deployment.
 | `NAVARCH_SANDBOX_PROFILE` | `trusted-development` | Named security profile for Docker sessions (`src/sandbox-profile.cts`): `trusted-development` (image-default user, uncapped, open egress), `untrusted-code` (non-root, 2 CPU / 4g / 512 PIDs, deny-by-default egress, read-only shared git), `elevated-verification` (non-root, 4 CPU / 8g / 2048 PIDs, egress limited to GitHub plus package registries). The default is the exact pre-profile flag set. |
 | `NAVARCH_SANDBOX_EGRESS_NETWORK` | _(unset)_ | Docker network that enforces a profile's egress allowlist. Docker cannot filter by domain itself, so an allowlist profile without this fails closed to `--network=none` and records the denial. |
 | `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 adapter: `claude-code`, `codex`, `gemini`, `opencode`, `acp`, or `qoder`. Overrides the choice saved by `connect`/`register`; `start --agent` has highest priority. |
+| `NAVARCH_AGENT` | saved choice, then `claude-code` | Local choice of agent adapter: `claude-code`, `codex`, `agy`, `opencode`, `acp`, or `qoder`. Overrides the choice saved by `connect`/`register`; `start --agent` has highest priority. |
 | `NAVARCH_RUNTIMES` | resolved local agent choice | Comma list of installed/authenticated adapters advertised to dispatch. Unpinned tasks run on the preferred agent; a task runtime pin selects the matching adapter. Unrecognized ids are dropped with a warning that names them, so a typo cannot silently shrink the advertised set. |
 | `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`. |
@@ -465,8 +465,8 @@ unchanged across the deployment.
 | `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`. Runtime sessions default to an empty `--setting-sources` list so machine/user/project hooks cannot leak into temporary checkouts. The generated host-mode settings retain only the user-level `apiKeyHelper` needed for authentication; supply `--setting-sources=<sources>` here to opt into other settings deliberately. |
 | `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_ANTIGRAVITY_BIN` | `agy` | Path/name of the Antigravity CLI binary, version 1.3.1+. |
+| `NAVARCH_ANTIGRAVITY_EXTRA_ARGS` | — | Comma list: only `--agent`, `--model`, `--effort`, `--sandbox`, `--dangerously-skip-permissions`; protocol, deadline and resume flags are owned by Navarch. |
 | `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_ACP_BIN` | `dsh` | Path/name of an Agent Client Protocol v1 stdio server. DeepSeek Harness is the default implementation. |
@@ -484,15 +484,14 @@ unchanged across the deployment.
 ## Worktree boundary guard (host mode)
 
 A machine typically runs several sessions concurrently (`NAVARCH_MAX_SESSIONS`),
-each in its own git worktree. The runtime enforces the same boundary for all
-supported coding agents, using each CLI's native enforcement point:
+each in its own git worktree. The runtime enforces adapter-specific boundaries where verified; unsupported guarded paths fail
+closed rather than claim equivalent isolation:
 
 Every adapter receives an empty, session-owned `GH_CONFIG_DIR` and, when the
 project supplies GitHub credentials, the lease-scoped `GITHUB_TOKEN`. This
 keeps `gh` independent of the operator's selected account and prevents tasks
 from reading unrelated GitHub credentials. Docker already mounts the session
-metadata directory; Gemini's nested host sandbox receives the `gh` directory
-as an explicit read-only mount.
+metadata directory.
 
 - **Claude Code:** the runtime uses `--permission-mode auto`, which sends
   approval decisions through Claude Code's background safety classifier. It
@@ -525,12 +524,13 @@ as an explicit read-only mount.
   the same write roots. Without these, iOS builds and simulator tests fail
   under the sandbox with
   `access to /Library/Developer/PrivateFrameworks/CoreSimulator.framework is blocked`.
-- **Gemini:** the runtime uses Gemini CLI's native sandbox with only the
-  current worktree, shared gitdir, session `gh` config, and approved extra
-  roots mounted. The `gh` config and lease MCP settings are read-only; 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.
+- **Antigravity:** guarded host execution and read-only Navi are unsupported.
+  Use an isolated Docker image containing authenticated `agy` 1.3.1+ and Node,
+  or explicitly disable the machine-wide guard only on a dedicated trusted
+  worker. Antigravity's global MCP servers, permissions, plugins and hooks
+  remain active: the lease relay is not an exclusive tool boundary. Navarch
+  does not automatically add `--dangerously-skip-permissions`; preconfigure
+  scoped permissions or explicitly opt into that flag on an isolated worker.
 - **OpenCode:** the CLI cannot currently express a host-side boundary for all
   shell side effects, so with the guard enabled it is resolved out of the
   machine's advertised runtimes at startup — and a machine that offers only
@@ -611,9 +611,10 @@ export NAVARCH_AGENT=claude-code
 # 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
+# Google Antigravity CLI — requires authenticated agy 1.3.1+.
+# Use Docker with agy + Node installed, or an explicit guard opt-out only
+# on a dedicated trusted worker. Gemini auth/config is not transferred.
+export NAVARCH_AGENT=antigravity
 
 # OpenCode — requires an authenticated `opencode` CLI (or
 # NAVARCH_OPENCODE_BIN pointing at it). A guarded host refuses to start with
@@ -631,16 +632,16 @@ export NAVARCH_AGENT=acp
 export NAVARCH_AGENT=qoder
 
 # Advanced compatibility mode: advertise every installed adapter. On a guarded
-# host, `opencode` is dropped from this list (see the boundary notes above);
+# host, `opencode` and `antigravity` are dropped from this list (see the boundary notes above);
 # the rest are advertised as written.
-export NAVARCH_RUNTIMES=claude-code,codex,gemini,opencode,acp,qoder
+export NAVARCH_RUNTIMES=claude-code,codex,antigravity,opencode,acp,qoder
 ```
 
 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. For normal projects,
 the locally selected `NAVARCH_AGENT` handles every unpinned task. A task with a
-runtime override (for example `gemini`) is claimed only by a worker that
+runtime override (for example `antigravity`) is claimed only by a worker that
 advertises that adapter, and the claim returns it as the session runtime.
 Sandbox projects remain constrained to Claude Code, so they claim only unpinned
 or `claude-code`-pinned tasks. List only adapters this worker can really run:
@@ -657,10 +658,10 @@ 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 ...`, `gemini --model ...`, or `opencode run
+`claude -p --model ... --effort ...`, `agy --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 any `provider/model`
+effort on completion. Antigravity uses the `default` sentinel to preserve the CLI account model;
+explicit low/medium/high effort is supported without inventing higher levels. OpenCode accepts any `provider/model`
 reference (the platform default is `opencode/x-preview-f-free`, Ox Alpha Free
 (Unlimited) on OpenCode Zen), or `default` to preserve the authenticated
 account's selection. ACP sessions use the agent's advertised default model and
@@ -709,24 +710,66 @@ 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 runs headlessly with `--output-format stream-json` and the
-prompt piped on stdin, which Gemini uses as the prompt when stdin is not a
-TTY. 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.
-
-Gemini's native sandbox launcher converts piped stdin back into a `--prompt`
-argument for its child. When that sandbox follows Linux argv rules (a Linux
-host, a Docker session, or a `docker`/`podman` sandbox chosen through
-`GEMINI_SANDBOX`), the adapter rejects prompts of 128 KiB or more; macOS
-`sandbox-exec` has no per-string limit, so there the adapter only rejects
-prompts that would approach the 1 MiB total argv limit (about 900 KiB once
-shell-quoted). Both rejections carry an explicit diagnostic; reducing context or
-selecting another runtime preserves the worktree boundary. Navarch Docker
-mode disables the nested Gemini sandbox by default and can still pipe larger
-prompts. All Gemini runs reject prompts above 8 MiB because Gemini's stdin
-reader silently truncates input beyond that limit. These checks use UTF-8 bytes.
+### Antigravity CLI contract and migration
+
+The Antigravity adapter requires **agy 1.3.1 or later**. It validates
+`agy --version` locally before each turn, then runs
+`agy --input-format stream-json --output-format stream-json`, writes one
+`{"event":"user","message":{"content":"..."}}` line, and closes stdin.
+Only text prompts are supported. It never sends `control_request` or
+`control_response`, which the CLI explicitly rejects. The final response
+comes from `event: "result"` / `result.response`, not accumulated tool or
+assistant progress. Raw `init`, `step_update` (including tool progress), and
+`result` events remain available in the live transcript.
+
+An OS exit of zero is insufficient: a missing/malformed/duplicate result,
+wrong conversation ID, non-`SUCCESS` status, `AGY_ERROR`, nonempty or malformed
+`denied_actions`, permission-denial notices, or a partial-timeout warning
+fails the turn. Antigravity may soft-deny a required action while exiting zero.
+The runtime owns deadlines; it does not set `--print-timeout`, whose expiration
+can return partial output with exit zero. The vendor changelog states the
+headless default became unlimited in 1.2.6, despite the older reference table.
+Cancellation sends SIGINT to the owned process group, escalates to SIGKILL,
+and closes lease MCP sockets and generated configuration; Docker cancellation
+stops the session container.
+
+Each corrective turn resumes only the verified Antigravity conversation from
+this lease, using `--conversation <id>`. Provider, workspace, model, turn count
+and monotonic cumulative usage are checked. No implicit `--continue`, arbitrary
+extra-argument session ID, Gemini ID, persisted cross-lease ID, or credential
+migration is accepted. Cumulative input/output counters are differenced on
+resume. USD cost stays unknown; cache-read inclusion is not sufficiently
+specified to invent an inclusive cache split. Raw counters remain in the
+transcript.
+
+MCP definitions use Antigravity's documented workspace `.agents/mcp_config.json`
+stdio format. The runtime exclusively creates a secret-free config pointing to
+a short-lived private Unix-socket relay. MCP-specific HTTP lease headers stay in the parent runtime's memory, not the AG config, argv, or relay child's environment. The existing managed Git credential helper still receives the machine token needed for its authorized refresh endpoint; this bridge does not eliminate all child-process credentials. The
+source staging JSON uses Navarch-owned environment references, resolved by
+Navarch itself; no Antigravity interpolation or alternate config-root API is
+assumed. The repository must already ignore `/.agents/mcp_config.json` in a local `.gitignore`; Navarch never edits ignore rules. A post-run index check rejects forced staging/committing without rewriting history. Existing `.agents/mcp_config.json`, symlinked directories, unsupported
+transports, or socket paths over 100 bytes fail closed. Configuration and
+sockets are removed after the child exits; changed files are preserved and
+reported as cleanup failures. Existing global/user config is never edited.
+Host sockets use a short private system-temp directory. Docker requires a short session metadata path (socket pathname at most 100 bytes), the same-path metadata mount, and Node in the image;
+Windows is unsupported for this relay. Live authenticated AG/Docker compatibility
+has not been verified by the offline suite.
+
+`gemini` is a retired identity, not an alias. Existing machine configuration,
+credentials, task pins, session history and provider IDs remain untouched.
+Selecting or advertising `gemini` fails with migration guidance; a stale claim
+hits a tombstone adapter that starts no process. Install from the
+[official Antigravity instructions](https://antigravity.google/docs/cli/install/),
+authenticate in an interactive `agy` session, then deliberately choose
+`--agent antigravity` / `NAVARCH_AGENT=antigravity`, update `NAVARCH_RUNTIMES`
+and existing project/task pins. `NAVARCH_GEMINI_*` values are not reused.
+API-key mode requires the operator's `modelProvider: "gemini"` settings and
+`GEMINI_API_KEY`; Navarch does not create keys or rewrite auth settings.
+
+Primary contracts checked October 12, 2026:
+[headless input/output](https://antigravity.google/docs/cli/headless/),
+[release changes](https://antigravity.google/docs/changelog), and
+[MCP configuration](https://antigravity.google/docs/mcp/).
 
 The OpenCode adapter uses `opencode run --format json` with the prompt on
 stdin, and normalizes `text` and `step_finish` JSONL events into
@@ -759,9 +802,6 @@ rejects any single argv or environment string over 128 KiB
 (`MAX_ARG_STRLEN`), so an argv prompt made large review sessions fail with
 `spawn E2BIG` before the agent started. Docker-mode sessions forward the same
 stdin through `docker exec -i`.
-Gemini's own sandbox relaunch is an exception to this transport guarantee,
-as described above; moving the initial spawn to stdin does not remove its
-internal argv limit.
 
 ## Architecture
 
@@ -782,7 +822,7 @@ cli.cts
                   (adapters/types.cts) by NAVARCH_AGENT, then .run(...):
                     - claudeCodeAdapter (adapters/claude.cts) — `claude -p --mcp-config <path> --output-format stream-json --verbose < prompt`
                     - codexAdapter      (adapters/codex.cts)  — `codex exec - --json -c mcp_servers.*=... < prompt`
-                    - geminiAdapter     (adapters/gemini.cts) — `gemini --output-format stream-json < prompt`
+                    - antigravityAdapter (adapters/antigravity.cts) — `agy --input-format stream-json --output-format stream-json`
                     - openCodeAdapter   (adapters/opencode.cts) — `opencode run --format json < prompt`
                     - acpAdapter        (adapters/acp.cts) — ACP v1 JSON-RPC/stdio; defaults to `dsh --profile acp`
                     - qoderAdapter      (adapters/qoder.cts) — `qoder -p --output-format json < prompt`
@@ -878,15 +918,14 @@ 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/antigravity.cts` and `antigravity-mcp.cts` — strict streams, denial/timeout false-green prevention, usage/resume identity, private lease relay and cleanup (`tests/adapters/antigravity*.test.cts`).
+- `adapters/gemini.cts` — retired-provider tombstone (`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, Gemini, and OpenCode (`tests/adapters/conformance.test.cts`).
+  Claude, Codex, 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
@@ -920,8 +959,7 @@ 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.
+- A full authenticated Antigravity 1.3.1+ task with scoped permissions, real AG stdio MCP loading, existing global customizations, Docker image, resume, PR delivery and cancellation. Mock/relay tests are not that proof.
 - 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.

package/dist/adapters/antigravity-mcp.cjs

@@ -0,0 +1,221 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ANTIGRAVITY_STDIO_RELAY = void 0;
+exports.prepareAntigravityMcp = prepareAntigravityMcp;
+const node_child_process_1 = require("node:child_process");
+const node_util_1 = require("node:util");
+const node_fs_1 = require("node:fs");
+const node_net_1 = __importDefault(require("node:net"));
+const node_path_1 = __importDefault(require("node:path"));
+const streamableHttp_js_1 = require("@modelcontextprotocol/sdk/client/streamableHttp.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/shared/stdio.js");
+/** No auth values in this code, config, argv or socket path. The stdio child
+ * has no HTTP credentials: it relays bytes to the owning runtime process.
+ */
+exports.ANTIGRAVITY_STDIO_RELAY = `const net=require('node:net');const socket=net.createConnection(process.argv[1]);socket.on('error',()=>{process.stderr.write('Navarch MCP relay unavailable\\n');process.exitCode=1;process.stdin.destroy();});process.stdin.pipe(socket);socket.pipe(process.stdout);socket.on('close',()=>process.stdin.destroy());`;
+/**
+ * AG has no documented per-run MCP-config flag or env interpolation. Use its
+ * documented workspace stdio format, exclusively created and removed here.
+ * Global AG configuration still loads; this is NOT an exclusive tool boundary.
+ */
+async function prepareAntigravityMcp(options) {
+    if (!options.mcpConfigPath)
+        return { close: async () => undefined, failed: () => false };
+    if (process.platform === "win32")
+        throw new Error("Unix socket isolation required");
+    const cwd = node_path_1.default.resolve(options.cwd);
+    const parent = node_path_1.default.dirname(node_path_1.default.resolve(options.mcpConfigPath));
+    if (await node_fs_1.promises.realpath(cwd) !== cwd || await node_fs_1.promises.realpath(parent) !== parent)
+        throw new Error("Symlinked MCP parent refused");
+    const parsed = JSON.parse(await node_fs_1.promises.readFile(options.mcpConfigPath, "utf8"));
+    if (!record(parsed) || !record(parsed.mcpServers))
+        throw new Error("Invalid MCP source");
+    const servers = Object.entries(parsed.mcpServers).map(([name, raw]) => {
+        if (!/^[A-Za-z0-9_-]+$/.test(name) || !record(raw))
+            throw new Error("Invalid MCP server");
+        // Navarch's lease servers use Streamable HTTP. Never silently convert SSE
+        // or executable configs to a different transport.
+        if (raw.type !== "http" || typeof raw.url !== "string")
+            throw new Error("Unsupported lease MCP transport");
+        const url = new URL(raw.url);
+        if (!["https:", "http:"].includes(url.protocol) || url.username || url.password)
+            throw new Error("Invalid lease MCP URL");
+        if (url.protocol === "http:" && !["localhost", "127.0.0.1", "[::1]"].includes(url.hostname))
+            throw new Error("Insecure remote MCP refused");
+        if (raw.headers !== undefined && !record(raw.headers))
+            throw new Error("Invalid MCP headers");
+        const headers = {};
+        for (const [key, value] of Object.entries(raw.headers ?? {})) {
+            if (typeof value !== "string")
+                throw new Error("Invalid MCP header");
+            // This is Navarch's staging format, resolved by OUR bridge, not AG.
+            const ref = /^\{env:([A-Z_][A-Z0-9_]*)\}$/.exec(value);
+            if (ref && options.env[ref[1]] === undefined)
+                throw new Error("Missing lease MCP value");
+            headers[key] = ref ? options.env[ref[1]] : value;
+        }
+        return [name, { url, headers }];
+    });
+    if (servers.length === 0)
+        return { close: async () => undefined, failed: () => false };
+    if (await node_fs_1.promises.lstat(node_path_1.default.join(cwd, ".git")).catch(() => null)) {
+        // A normal git add -A must not publish the transient relay config. Require
+        // repository-local ignore coverage, which is also visible in the mounted
+        // Docker checkout. Do not rewrite tracked .gitignore or global excludes.
+        const { stdout } = await (0, node_util_1.promisify)(node_child_process_1.execFile)("git", ["-C", cwd, "check-ignore", "--no-index", "--verbose", "--", ".agents/mcp_config.json"], { timeout: 5_000, maxBuffer: 1024 * 1024 });
+        const match = /^(\.gitignore|\.agents\/\.gitignore):\d+:([^\t\n]+)\t\.agents\/mcp_config\.json\r?\n?$/.exec(stdout);
+        if (!match || match[2].startsWith("!"))
+            throw new Error("Repository-local MCP ignore rule required");
+    }
+    const agentsDir = node_path_1.default.join(cwd, ".agents");
+    const configPath = node_path_1.default.join(agentsDir, "mcp_config.json");
+    let createdAgentsDir = false;
+    try {
+        await node_fs_1.promises.mkdir(agentsDir, { mode: 0o700 });
+        createdAgentsDir = true;
+    }
+    catch (error) {
+        if (error.code !== "EEXIST")
+            throw error;
+    }
+    const agentsStat = await node_fs_1.promises.lstat(agentsDir);
+    if (!agentsStat.isDirectory() || agentsStat.isSymbolicLink())
+        throw new Error("Unsafe .agents directory");
+    // Reserve before making any sockets. wx refuses user-owned files/symlinks.
+    const config = await node_fs_1.promises.open(configPath, "wx", 0o600);
+    const owned = await config.stat();
+    let configText = "";
+    let tempDir;
+    let relayFailed = false;
+    let closed = false;
+    const relays = [];
+    const close = async () => {
+        if (closed)
+            return;
+        closed = true;
+        await config.close().catch(() => undefined);
+        for (const relay of relays) {
+            for (const socket of relay.sockets)
+                socket.destroy();
+            await Promise.allSettled([...relay.transports].map((transport) => transport.close()));
+            await new Promise((resolve) => relay.server.close(() => resolve()));
+        }
+        if (tempDir)
+            await node_fs_1.promises.rm(tempDir, { recursive: true, force: true });
+        // Do not erase a replacement supplied by the agent/user. No secret is in
+        // this file, but failure to remove our exact config is still a failed run.
+        let cleanupError = false;
+        // The transient config must never become a delivered repository file.
+        // Detect index/commit contamination without rewriting either user-owned
+        // history or the index; cleanup still removes our owned working file.
+        if (await node_fs_1.promises.lstat(node_path_1.default.join(cwd, ".git")).catch(() => null)) {
+            try {
+                await (0, node_util_1.promisify)(node_child_process_1.execFile)("git", ["--literal-pathspecs", "-C", cwd, "ls-files", "--error-unmatch", "--", ".agents/mcp_config.json"], { timeout: 5_000, maxBuffer: 1024 * 1024 });
+                cleanupError = true;
+            }
+            catch (error) {
+                if (error.code !== 1)
+                    cleanupError = true;
+            }
+        }
+        try {
+            const current = await node_fs_1.promises.lstat(configPath);
+            if (current.isFile() && !current.isSymbolicLink() && current.ino === owned.ino && current.dev === owned.dev && await node_fs_1.promises.readFile(configPath, "utf8") === configText) {
+                await node_fs_1.promises.unlink(configPath);
+            }
+            else
+                cleanupError = true;
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                cleanupError = true;
+        }
+        if (createdAgentsDir)
+            await node_fs_1.promises.rmdir(agentsDir).catch(() => undefined);
+        if (cleanupError)
+            throw new Error("MCP config ownership changed");
+    };
+    try {
+        // Containers need the same-path session mount. Host workers use the
+        // short system temp root so ordinary per-project config directories do
+        // not exceed AF_UNIX's path limit. Neither directory holds credentials.
+        const socketRoot = options.dockerExec ? parent : await node_fs_1.promises.realpath("/tmp");
+        tempDir = await node_fs_1.promises.mkdtemp(node_path_1.default.join(socketRoot, "agy-"));
+        await node_fs_1.promises.chmod(tempDir, 0o700);
+        const mcpServers = {};
+        for (const [index, [name, target]] of servers.entries()) {
+            const socketPath = node_path_1.default.join(tempDir, `${index}.sock`);
+            if (Buffer.byteLength(socketPath) > 100)
+                throw new Error("Session metadata path too long for Unix socket");
+            const sockets = new Set();
+            const transports = new Set();
+            const server = node_net_1.default.createServer({ allowHalfOpen: true }, (socket) => {
+                sockets.add(socket);
+                const transport = new streamableHttp_js_1.StreamableHTTPClientTransport(target.url, { requestInit: { headers: target.headers }, reconnectionOptions: { maxReconnectionDelay: 1000, initialReconnectionDelay: 100, reconnectionDelayGrowFactor: 1.5, maxRetries: 1 } });
+                transports.add(transport);
+                const fail = () => { if (!closed)
+                    relayFailed = true; socket.destroy(); void transport.close().catch(() => undefined); };
+                transport.onerror = fail;
+                let initializeId;
+                transport.onmessage = (message) => {
+                    if ("id" in message && message.id === initializeId && "result" in message && record(message.result) && typeof message.result.protocolVersion === "string") {
+                        transport.setProtocolVersion(message.result.protocolVersion);
+                    }
+                    if (!socket.destroyed)
+                        socket.write((0, stdio_js_1.serializeMessage)(message));
+                };
+                transport.onclose = () => socket.end();
+                const started = transport.start();
+                let ready = started;
+                const pending = new Set();
+                const buffer = new stdio_js_1.ReadBuffer({ maxBufferSize: 16 * 1024 * 1024 });
+                socket.on("data", (chunk) => {
+                    try {
+                        buffer.append(chunk);
+                        let message;
+                        while ((message = buffer.readMessage()) !== null) {
+                            const current = message;
+                            if ("method" in current && current.method === "initialize" && "id" in current)
+                                initializeId = current.id;
+                            // Do not serialize complete HTTP requests: cancellation must be
+                            // able to overtake an outstanding tools/call.
+                            const operation = ready.then(() => transport.send(current));
+                            if ("method" in current && ["initialize", "notifications/initialized"].includes(current.method))
+                                ready = operation;
+                            pending.add(operation);
+                            void operation.then(() => pending.delete(operation), () => { pending.delete(operation); fail(); });
+                        }
+                    }
+                    catch {
+                        fail();
+                    }
+                });
+                void started.catch(fail);
+                socket.on("end", () => { void Promise.all([...pending]).then(() => socket.end(), fail); });
+                socket.on("error", fail);
+                socket.on("close", () => { sockets.delete(socket); transports.delete(transport); void transport.close().catch(() => undefined); });
+            });
+            relays.push({ server, sockets, transports });
+            await new Promise((resolve, reject) => { server.once("error", reject); server.listen(socketPath, () => { server.removeListener("error", reject); resolve(); }); });
+            server.on("error", () => { if (!closed)
+                relayFailed = true; });
+            await node_fs_1.promises.chmod(socketPath, 0o600);
+            mcpServers[name] = {
+                command: options.dockerExec ? "node" : process.execPath,
+                args: ["-e", exports.ANTIGRAVITY_STDIO_RELAY, socketPath],
+            };
+        }
+        configText = JSON.stringify({ mcpServers }, null, 2);
+        await config.writeFile(configText, "utf8");
+        await config.close();
+        return { close, failed: () => relayFailed };
+    }
+    catch (error) {
+        await close();
+        throw error;
+    }
+}
+function record(value) { return value !== null && typeof value === "object" && !Array.isArray(value); }