@sagentlab/navarch-runtime 0.1.112 → 0.1.117

package/README.md

@@ -1,5 +1,7 @@
 # navarch-runtime
 
+Conversation mirror isolation and lifecycle fixes are included in runtime 0.1.115.
+
 ## Managed visual evidence
 
 Host-mode build, verify, and QA leases requiring `browser-use` receive a
@@ -93,7 +95,8 @@ 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
-Antigravity CLI**, **OpenCode**, or an **Agent Client Protocol (ACP)** agent when connecting a worker. Any selected agent can
+Antigravity CLI**, **OpenCode**, an **Agent Client Protocol (ACP)** agent, **Qoder**,
+**Pi (local)**, or **Muse Code (experimental)** 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 +119,8 @@ 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`,
-  `agy`, `opencode`, `dsh` for the default ACP integration, or `qoder` — and complete its normal authentication flow; and
+  `agy`, `opencode`, `dsh` for the default ACP integration, `qoder`, `pi`,
+  or `muse` — 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.
@@ -239,11 +243,11 @@ The from-source flow — `git clone` + `./install.sh` + `node bin/navarch.cjs
 
 | Command | Purpose |
 |---|---|
-| `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. |
+| `register --token <t> --name <n> [--agent claude-code\|codex\|antigravity\|opencode\|acp\|qoder\|muse\|pi-local] […]` | 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\|muse\|pi-local] [--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\|muse\|pi-local]` | Runs the daemon. A start-time agent choice overrides the saved choice. |
+| `supervise [--agent claude-code\|codex\|antigravity\|opencode\|acp\|qoder\|muse\|pi-local]` | Runs the daemon under the update supervisor, enabling drain-safe automatic updates and rollback. |
+| `doctor [--agent claude-code\|codex\|antigravity\|opencode\|acp\|qoder\|muse\|pi-local]` | Prints resolved config + Docker/registration status; no side effects. |
 
 ### Running multiple agents on one machine
 
@@ -457,7 +461,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`, `agy`, `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`, `antigravity`, `opencode`, `acp`, `qoder`, `muse`, or `pi-local`. 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`. |
@@ -473,11 +477,14 @@ unchanged across the deployment.
 | `NAVARCH_ACP_EXTRA_ARGS` | `--profile,acp` | Comma list of arguments used to start the ACP server. Override this together with `NAVARCH_ACP_BIN` for another ACP-compatible coding agent. |
 | `NAVARCH_QODER_BIN` | `qoder` | Path/name of the Qoder CLI binary. |
 | `NAVARCH_QODER_EXTRA_ARGS` | — | Comma list of extra CLI args appended after the unattended defaults (`--setting-sources`, `--permission-mode auto`, `--output-format json`). An explicit `--output-format`, `--permission-mode`, `--settings`, `--model`, or `--reasoning-effort` here replaces the per-session default. Qoder selects its own account models; pin one via `--model` here or `connect --model` to override. |
+| `NAVARCH_MUSE_BIN` | `muse` | Path/name of the native Muse Code CLI. Requires authenticated experimental `muse serve` SDK access; the npm SDK does not install the CLI. See [Muse Code setup](../docs/navarch/muse-code.md). |
+| `NAVARCH_MUSE_EXTRA_ARGS` | — | Comma list of arguments passed to `muse serve`. Permission/sandbox bypass flags are rejected. Configure narrow native approval rules rather than enabling blanket approval. |
 | `NAVARCH_MCP_CONFIG_PATH` | — | Path to the platform MCP config passed as `--mcp-config`. |
-| `NAVARCH_WORKTREE_GUARD` | on | Host-mode sessions get an adapter-native per-session worktree boundary guard (see below). Set `off` to disable it for every runtime on the machine — required to run OpenCode on the host. |
+| `NAVARCH_WORKTREE_GUARD` | on | Host-mode sessions get an adapter-native per-session worktree boundary guard (see below). Set `off` to disable it for every runtime on the machine — required to run OpenCode or Muse on an already-isolated host. |
 | `NAVARCH_NAVI_CONVERSATIONS` | on | Serve read-only Navi repository conversations on this machine. Only the `claude-code` adapter on the host sandbox with the worktree guard on is supported; `navarch-runtime doctor` prints the `navi_chat:` state and reason. Set `off` to stop polling for conversations. |
 | `NAVARCH_NAVI_WORKSPACE_CHAT` | off | Explicitly enable writable Navi chat on a supported Claude Code host runtime. Owners can choose **Edit and run commands**; automatic permission review and the worktree guard remain active. Commands run on this host, not in a hard sandbox. Changes stay under `<workspaceRoot>/chat-workspaces/<conversationId>/repo` until the operator removes them. See [workspace chat](../docs/navarch/navi-workspace-chat.md). |
 | `NAVARCH_CONVERSATION_POLL_MS` | `5000` | Idle poll interval for queued conversation turns (1000–30000). |
+| `NAVARCH_CONVERSATION_MIRROR` | on | Seed new conversation checkouts from a per-repository mirror under `<workspaceRoot>/conversation-mirrors/` (fetch + local clone with independent object files) instead of a full network clone. Set `off` to always clone directly. |
 | `NAVARCH_CONVERSATION_TURN_TIMEOUT_MS` | `540000` | Time limit for one conversation turn's agent process (at most nine minutes). |
 | `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. |
 
@@ -542,6 +549,18 @@ metadata directory.
   OpenCode receives a private, per-session config, project config discovery is
   disabled, and lease MCP headers are referenced through child-only environment
   variables instead of being copied into its config file or argv.
+- **Muse Code (experimental):** guarded hosts do not advertise Muse; a
+  Muse-only guarded worker fails closed before claiming. Use a custom Docker
+  image with native Muse, its authentication, Node.js, and the matching Navarch
+  runtime's `navarch-muse-mcp-bridge` executable. Use a dedicated clean Muse
+  configuration with no unrelated MCP servers, plugins, or hooks: session MCP
+  is additive to native configuration. The default image contains
+  neither Muse nor its bridge. A host guard opt-out is an explicit operator
+  choice for an already-isolated worker and removes the boundary machine-wide;
+  generated Muse setup commands never make that choice. Muse uses
+  `denyUnmatched`, verified by a session readback, and rejects interactive
+  approval requests. Preconfigure narrow rules for required shell/write actions
+  and the actual Navarch MCP tool namespace. See [Muse Code setup](../docs/navarch/muse-code.md).
 - **ACP agents:** the protocol client rejects every unattended permission
   escalation. The agent remains responsible for enforcing its declared file
   sandbox; use Navarch Docker mode when the ACP server itself does not provide
@@ -578,7 +597,16 @@ Because bubblewrap starts from an empty `/` and Codex re-executes its own binary
 inside it, the profile also grants read access to the Codex executable's
 install directory (resolved from `NAVARCH_CODEX_BIN` or `PATH`, following
 symlinks) plus mise and nvm tool installs, so a Codex or Node installed under
-`$HOME` still starts. `$HOME` and `CODEX_HOME` themselves are never granted.
+`$HOME` still starts. Codex also keeps per-run `codex-linux-sandbox` helper links in
+`$CODEX_HOME/tmp/arg0` and re-executes them by name inside that view; without a
+read grant on that one directory every sandboxed command fails with
+`bwrap: execvp codex-linux-sandbox: No such file or directory` (reproduced on
+Codex 0.158.0, 0.160.0, and 0.162.1). For hoisted npm installs the sibling
+`@openai/codex-<platform>` package holding the native binary is granted too.
+`$HOME` and `CODEX_HOME` themselves are never granted. Helper-directory aliases
+and unresolvable paths are refused; native-package grants require the official
+package layout, and canonical workspace overlap is rejected even through aliases.
+These checks assume the operator trusts the installed CLI/package contents.
 To verify the linked-worktree boundary on a Linux host with Codex installed,
 run `NAVARCH_TEST_REAL_CODEX=1 npm test -- tests/codex-linux-sandbox.test.cts`
 from `runtime/`. The smoke test uses local shell commands and makes no model calls.
@@ -631,10 +659,15 @@ export NAVARCH_AGENT=acp
 # `connect --model` can pin one explicitly.
 export NAVARCH_AGENT=qoder
 
-# Advanced compatibility mode: advertise every installed adapter. On a guarded
-# 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,antigravity,opencode,acp,qoder
+# Muse Code (experimental, runtime 0.1.117+) — see the dedicated setup
+# guide before starting: native authenticated `muse serve`, narrow approval
+# rules, clean native configuration, and deliberate isolation are required.
+export NAVARCH_AGENT=muse
+
+# Advanced compatibility mode: advertise every installed, configured adapter.
+# On a guarded host, `opencode`, `antigravity` and `muse` are dropped (see the
+# boundary notes above); the rest are advertised as written.
+export NAVARCH_RUNTIMES=claude-code,codex,antigravity,opencode,acp,qoder,muse
 ```
 
 For the legacy single-runtime setting, priority is `start --agent` →
@@ -648,10 +681,10 @@ or `claude-code`-pinned tasks. List only adapters this worker can really run:
 in Docker mode that means CLIs installed in `NAVARCH_DOCKER_IMAGE`, otherwise
 pinned tasks for a missing adapter are claimed and then fail.
 
-All five BYO adapters implement the same `AgentAdapter` interface
-(`src/adapters/types.cts`) and run either directly on the host or via
-`docker exec` in the session's sandbox container, exactly like the Claude
-adapter always has — `session.cts` picks one (`src/adapters/index.cts`'s
+The BYO adapters implement the same `AgentAdapter` interface
+(`src/adapters/types.cts`). Supported isolation modes are adapter-specific;
+Muse uses `muse serve` over stdio on an explicitly isolated host or through
+`docker exec -i` in a prepared custom container — `session.cts` picks one (`src/adapters/index.cts`'s
 `selectAdapter`) at the start of each session and passes `agent_type`
 through to `complete()` unchanged by whatever happened during the run.
 
@@ -666,6 +699,10 @@ 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
 set the standard `reasoning_effort` configuration option when it is available.
+Muse uses the account-owned `default` model; Navarch adds no Muse project-model
+column or public model catalog. Its SDK integration is experimental and has no
+Navi conversation capability. Read [Muse Code setup and limitations](../docs/navarch/muse-code.md)
+before using private repositories, especially Muse Contributor data settings.
 Machine-wide extra arguments still configure other CLI behavior; dispatched
 model policy wins.
 
@@ -826,6 +863,7 @@ cli.cts
                     - 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`
+                    - museAdapter       (adapters/muse.cts) — experimental Muse Session Protocol via `muse serve`
                   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

package/bin/muse-mcp-bridge.cjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+"use strict";
+require("../dist/muse-mcp-bridge.cjs").main();

package/dist/adapters/index.cjs

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.runQoderAdapter = exports.qoderAdapter = exports.runAcpAdapter = exports.acpAdapter = exports.runPiAdapter = exports.piAdapter = exports.runLocalPiAdapter = exports.localPiAdapter = exports.runOpenCodeAdapter = exports.openCodeAdapter = exports.runGeminiAdapter = exports.geminiAdapter = exports.runAntigravityAdapter = exports.antigravityAdapter = exports.runCodexAdapter = exports.codexAdapter = exports.runClaudeCodeAdapter = exports.claudeCodeAdapter = void 0;
+exports.runMuseAdapter = exports.museAdapter = exports.runQoderAdapter = exports.qoderAdapter = exports.runAcpAdapter = exports.acpAdapter = exports.runPiAdapter = exports.piAdapter = exports.runLocalPiAdapter = exports.localPiAdapter = exports.runOpenCodeAdapter = exports.openCodeAdapter = exports.runGeminiAdapter = exports.geminiAdapter = exports.runAntigravityAdapter = exports.antigravityAdapter = 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; } });
@@ -29,6 +29,9 @@ Object.defineProperty(exports, "runAcpAdapter", { enumerable: true, get: functio
 const qoder_cjs_1 = require("./qoder.cjs");
 Object.defineProperty(exports, "qoderAdapter", { enumerable: true, get: function () { return qoder_cjs_1.qoderAdapter; } });
 Object.defineProperty(exports, "runQoderAdapter", { enumerable: true, get: function () { return qoder_cjs_1.runQoderAdapter; } });
+const muse_cjs_1 = require("./muse.cjs");
+Object.defineProperty(exports, "museAdapter", { enumerable: true, get: function () { return muse_cjs_1.museAdapter; } });
+Object.defineProperty(exports, "runMuseAdapter", { enumerable: true, get: function () { return muse_cjs_1.runMuseAdapter; } });
 /**
  * Picks the AgentAdapter (adapters/types.cts) session.cts should run a
  * session with, keyed off config.cts's `agentType` (NAVARCH_AGENT). This is
@@ -50,6 +53,8 @@ function selectAdapter(agentType) {
             return acp_cjs_1.acpAdapter;
         case "qoder":
             return qoder_cjs_1.qoderAdapter;
+        case "muse":
+            return muse_cjs_1.museAdapter;
         case "claude-code":
             return claude_cjs_1.claudeCodeAdapter;
         case "pi-local":

package/dist/adapters/muse.cjs

@@ -0,0 +1,433 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.museAdapter = exports.MUSE_HOST_GUARD_MESSAGE = void 0;
+exports.runMuseAdapter = runMuseAdapter;
+exports.sumMuseSessionCost = sumMuseSessionCost;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+const node_crypto_1 = require("node:crypto");
+const kill_agent_cjs_1 = require("../kill-agent.cjs");
+const version_cjs_1 = require("../version.cjs");
+const CANCEL_GRACE_MS = 2_000;
+const SHUTDOWN_GRACE_MS = 30_000;
+const TERMINATE_GRACE_MS = 2_000;
+exports.MUSE_HOST_GUARD_MESSAGE = "Muse Code cannot yet prove Navarch's host worktree boundary. Use a custom " +
+    "NAVARCH_SANDBOX_MODE=docker image with Muse installed, or explicitly set " +
+    "NAVARCH_WORKTREE_GUARD=off only on an otherwise isolated machine.";
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value) ? value : undefined;
+}
+function count(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+}
+function deferred() {
+    let resolve;
+    const promise = new Promise((done) => { resolve = done; });
+    return { promise, resolve };
+}
+async function waitWithin(promise, ms) {
+    let timer;
+    await Promise.race([promise, new Promise((resolve) => { timer = setTimeout(resolve, ms); })]);
+    clearTimeout(timer);
+}
+/**
+ * Muse Session Protocol through the pinned official SDK's framed Connection.
+ * Own the child here (rather than the facade's private child) so Navarch can
+ * register its PID, stream raw output and kill its complete process group.
+ * The facade intentionally does not forward session-scoped MCP configuration.
+ * No `exec --json` fallback: its event contract is a different surface.
+ */
+async function runMuseAdapter(options) {
+    const empty = { exitCode: null, timedOut: false, killedByLeaseLoss: false, stdout: "", stderr: "" };
+    if (options.signal?.aborted)
+        return { ...empty, killedByLeaseLoss: true };
+    if (!options.dockerExec && options.museHostGuard !== false)
+        throw new Error(exports.MUSE_HOST_GUARD_MESSAGE);
+    if (!options.cwd || !node_path_1.default.isAbsolute(options.cwd))
+        throw new Error("Muse requires an absolute session worktree.");
+    if (options.extraArgs.some((arg) => /^(--yolo|--disable-sandbox|--disable-approval)(=|$)/.test(arg))) {
+        throw new Error("Muse permission and sandbox bypass flags are not supported by Navarch.");
+    }
+    const sourceServers = await readMcpServers(options.mcpConfigPath, options.env);
+    const sdk = await import("@muse-code/sdk");
+    const bridge = await prepareBridge(sourceServers, options);
+    try {
+        return await runMuseProcess(options, bridge.servers, sdk);
+    }
+    finally {
+        if (bridge.dir)
+            await node_fs_1.promises.rm(bridge.dir, { recursive: true, force: true });
+    }
+}
+async function runMuseProcess(options, mcpServers, sdk) {
+    const child = spawnMuse(options);
+    child.stdout.setEncoding("utf8");
+    child.stderr.setEncoding("utf8");
+    child.stdin.on("error", () => undefined); // A dead host is handled by its exit/EOF.
+    let stdout = "";
+    let stderr = "";
+    let timedOut = false;
+    let killedByLeaseLoss = false;
+    let processCode = null;
+    let sessionId;
+    let turnId;
+    let durable = false;
+    let terminal;
+    let authError;
+    let protocolFailed = false;
+    const closed = deferred();
+    const stopped = deferred();
+    const completed = deferred();
+    const items = new Map();
+    const usage = new Map();
+    const pending = [];
+    let cancelling;
+    const diagnostic = (message) => { stderr += `${stderr ? "\n" : ""}${message}`; };
+    child.on("error", (error) => { diagnostic(`Muse process failed: ${error.message}`); closed.resolve(); });
+    child.on("exit", (code) => {
+        processCode = code;
+        // A descendant may keep stdio open after its root exits.
+        if (!options.dockerExec)
+            (0, kill_agent_cjs_1.killAgent)(child);
+    });
+    child.on("close", (code) => { processCode = code; closed.resolve(); });
+    child.stderr.on("data", (chunk) => {
+        stderr += chunk;
+        options.onActivity?.();
+        options.onOutput?.("stderr", chunk);
+    });
+    const connection = new sdk.Connection({
+        incoming: (async function* () {
+            for await (const chunk of child.stdout) {
+                const text = String(chunk);
+                stdout += text;
+                options.onActivity?.();
+                options.onOutput?.("stdout", text);
+                yield text;
+            }
+        })(),
+        write: (chunk) => new Promise((resolve, reject) => {
+            child.stdin.write(chunk, (error) => error ? reject(error) : resolve());
+        }),
+    });
+    const cancel = () => cancelling ??= (async () => {
+        if (sessionId && turnId) {
+            // Admission is not cancellation completion. Give the host a bounded
+            // chance to settle before killing; never keep a lost lease alive.
+            void connection.command("turn/cancel", { sessionId, turnId }, { maxAttempts: 1 }).catch(() => undefined);
+            await waitWithin(Promise.race([completed.promise, closed.promise]), CANCEL_GRACE_MS);
+        }
+        if (options.dockerExec) {
+            await options.dockerExec.runner.run("docker", ["kill", options.dockerExec.containerName], { timeoutMs: 10_000 }).catch(() => undefined);
+        }
+        (0, kill_agent_cjs_1.killAgent)(child);
+    })();
+    const stop = () => { stopped.resolve(); void cancel(); };
+    const onAbort = () => { killedByLeaseLoss = true; stop(); };
+    const timer = options.timeoutMs > 0 ? setTimeout(() => { timedOut = true; stop(); }, options.timeoutMs) : undefined;
+    options.signal?.addEventListener("abort", onAbort, { once: true });
+    if (options.signal?.aborted)
+        onAbort();
+    const consume = (notification) => {
+        const params = record(notification.params);
+        if (!params || params.sessionId !== sessionId)
+            return;
+        if (notification.method === "view/gap") {
+            protocolFailed = true;
+            diagnostic("Muse event stream has a gap; refusing an incomplete result.");
+            stop();
+            return;
+        }
+        if (notification.method === "item/completed") {
+            const item = record(params.item);
+            if (!item || item.turnId !== turnId || item.kind !== "agentMessage" || typeof item.itemId !== "string")
+                return;
+            const previous = items.get(item.itemId);
+            if (!previous || Number(item.revision) >= Number(previous.revision))
+                items.set(item.itemId, item);
+        }
+        else if (params.turnId === turnId && notification.method === "session/tokenUsage") {
+            if (typeof params.viewCursor === "string")
+                usage.set(params.viewCursor, params);
+        }
+        else if (params.turnId === turnId && notification.method === "turn/completed") {
+            terminal = params;
+            const error = record(params.error);
+            if (params.terminal === "failed" && error?.kind === "authRequired") {
+                authError = "Muse authentication is required. Open muse and run /login on this machine.";
+            }
+            completed.resolve();
+        }
+    };
+    connection.onNotification((notification) => {
+        if (!turnId) {
+            // Events can precede the acknowledgement. Do not assume commandId is
+            // turnId; use the authoritative ack, then drain in wire order.
+            if (pending.length >= 10_000) {
+                protocolFailed = true;
+                diagnostic("Muse sent too many events before acknowledging the turn.");
+                stop();
+            }
+            else
+                pending.push(notification);
+        }
+        else
+            consume(notification);
+    });
+    connection.onProtocolError(() => {
+        protocolFailed = true;
+        diagnostic("Muse sent an invalid MSP frame; refusing to continue.");
+        stop();
+    });
+    // Unattended agents cannot invent approval or answer interactive questions.
+    // denyUnmatched is also selected below; unexpected requests abort the turn.
+    connection.onServerRequest(async () => {
+        protocolFailed = true;
+        diagnostic("Muse requested interactive approval or input; operator action is required.");
+        stop();
+        throw new sdk.MspError({ code: -32601, message: "Navarch cannot approve interactive requests", data: { kind: "methodNotFound", retryable: false } });
+    });
+    try {
+        options.onProcessStarted?.(child.pid);
+        const run = async () => {
+            const initialized = await connection.request("initialize", {
+                clientInfo: { name: "navarch_runtime", version: version_cjs_1.RUNTIME_VERSION },
+                capabilities: { requestedCapabilities: Object.keys(mcpServers).length ? ["sessionMcp"] : [], userInputDialogs: false },
+            });
+            const schema = record(initialized.schema);
+            if (typeof schema?.fingerprint !== "string")
+                throw new Error("Muse initialization did not provide a schema fingerprint.");
+            if (sdk.checkServedFingerprint(schema.fingerprint))
+                diagnostic("Muse schema fingerprint differs from the pinned SDK; unknown fields are tolerated.");
+            if (Object.keys(mcpServers).length && (!Array.isArray(initialized.grantedCapabilities) || !initialized.grantedCapabilities.includes("sessionMcp"))) {
+                throw new Error("Muse did not grant sessionMcp; the task cannot run without its lease-scoped tools.");
+            }
+            durable = initialized.sessionDurability === undefined || initialized.sessionDurability === "durable";
+            connection.notify("initialized");
+            await connection.flush();
+            if (timedOut || killedByLeaseLoss || protocolFailed)
+                return;
+            const config = Object.keys(mcpServers).length ? { mcpServers } : undefined;
+            const opened = options.resumeSessionId
+                ? await connection.command("session/resume", { sessionId: options.resumeSessionId, excludeItems: true, ...(config ? { config } : {}) }, { maxAttempts: 1 })
+                : await connection.command("session/start", {
+                    workspaceRoot: options.cwd,
+                    approvalMode: "denyUnmatched",
+                    ...(options.model && options.model !== "default" ? { modelId: options.model } : {}),
+                    ...(config ? { config } : {}),
+                }, { maxAttempts: 1 });
+            const session = record(opened.session);
+            if (typeof session?.sessionId !== "string" || typeof session.workspaceRoot !== "string"
+                || !node_path_1.default.isAbsolute(session.workspaceRoot) || await node_fs_1.promises.realpath(session.workspaceRoot) !== await node_fs_1.promises.realpath(options.cwd)
+                || session.activeTurnId !== null) {
+                throw new Error("Muse returned an unexpected session identity, worktree, or active turn.");
+            }
+            if (options.resumeSessionId && session.sessionId !== options.resumeSessionId)
+                throw new Error("Muse resumed a different session.");
+            sessionId = session.sessionId;
+            if (options.resumeSessionId) {
+                if (!durable)
+                    throw new Error("Muse cannot resume this session on an ephemeral host.");
+                if (record(opened.history)?.mode !== "none")
+                    throw new Error("Muse resume returned unexpected history; refusing replay.");
+                await connection.command("session/setApprovalMode", { sessionId, mode: "denyUnmatched" }, { maxAttempts: 1 });
+                if (options.model && options.model !== "default" && session.modelId !== options.model) {
+                    throw new Error("Muse resumed with a different model than the dispatched policy.");
+                }
+            }
+            // An older host may ignore additive fields. Prove the selected approval
+            // posture before sending any model-visible prompt.
+            let approvalMode = options.resumeSessionId ? undefined : record(session.approvalMode)?.mode;
+            if (approvalMode !== "denyUnmatched" && durable) {
+                const state = await connection.request("session/read", { sessionId, excludeItems: true });
+                approvalMode = record(record(state.session)?.approvalMode)?.mode;
+            }
+            if (approvalMode !== "denyUnmatched") {
+                throw new Error("Muse did not confirm denyUnmatched approval mode; refusing to start a turn.");
+            }
+            if (timedOut || killedByLeaseLoss || protocolFailed)
+                return;
+            const ack = await connection.command("turn/start", {
+                sessionId,
+                input: [{ type: "text", text: options.prompt }],
+                ...(options.reasoningEffort ? { reasoningEffort: options.reasoningEffort } : {}),
+            }, { maxAttempts: 1 });
+            if (typeof ack.turnId !== "string" || ack.disposition !== "started")
+                throw new Error("Muse did not start the requested turn.");
+            turnId = ack.turnId;
+            for (const notification of pending.splice(0))
+                consume(notification);
+            await Promise.race([completed.promise, connection.closed]);
+            if (!terminal && !timedOut && !killedByLeaseLoss)
+                throw new Error("Muse closed before the turn completed.");
+        };
+        await Promise.race([run(), stopped.promise]);
+    }
+    catch (error) {
+        if (error instanceof sdk.MspError && error.kind === "authRequired") {
+            authError = "Muse authentication is required. Open muse and run /login on this machine.";
+        }
+        if (!timedOut && !killedByLeaseLoss)
+            diagnostic(error instanceof Error ? error.message : "Muse protocol request failed.");
+    }
+    finally {
+        await cancelling;
+        // EOF releases Muse's writer lease. A bounded shutdown always reaps the
+        // child, including a host that ignores EOF or died during a request.
+        child.stdin.end();
+        await waitWithin(Promise.race([closed.promise, stopped.promise]), SHUTDOWN_GRACE_MS);
+        await cancelling;
+        if (child.exitCode === null && child.signalCode === null) {
+            (0, kill_agent_cjs_1.killAgent)(child, "SIGTERM");
+            await waitWithin(closed.promise, TERMINATE_GRACE_MS);
+            if (child.exitCode === null && child.signalCode === null)
+                (0, kill_agent_cjs_1.killAgent)(child);
+            if (options.dockerExec)
+                await options.dockerExec.runner.run("docker", ["kill", options.dockerExec.containerName], { timeoutMs: 10_000 }).catch(() => undefined);
+            await waitWithin(closed.promise, TERMINATE_GRACE_MS);
+        }
+        // The root may have exited while detached shell/MCP descendants remain.
+        // Reap our owned host process group even after a clean root exit.
+        if (!options.dockerExec)
+            (0, kill_agent_cjs_1.killAgent)(child);
+        await waitWithin(closed.promise, TERMINATE_GRACE_MS);
+        await connection.close().catch(() => undefined);
+        clearTimeout(timer);
+        options.signal?.removeEventListener("abort", onAbort);
+    }
+    if (processCode === 5)
+        diagnostic("This Muse build has the experimental SDK/serve surface disabled. No CLI fallback was attempted.");
+    const successful = !protocolFailed && terminal?.terminal === "completed" && processCode === 0;
+    if (terminal && terminal.terminal !== "completed" && !timedOut && !killedByLeaseLoss && !authError) {
+        diagnostic(`Muse turn did not complete successfully (${String(terminal.terminal)}).`);
+    }
+    const reportText = [...items.values()].flatMap((item) => typeof item.text === "string" ? [item.text] : []).join("\n").trim();
+    return {
+        exitCode: timedOut || killedByLeaseLoss ? null : successful ? 0 : processCode === null ? null : 1,
+        timedOut, killedByLeaseLoss, stdout, stderr,
+        ...(reportText ? { reportText } : {}),
+        ...(authError ? { authError } : {}),
+        ...(durable && sessionId && terminal ? { agentSessionId: sessionId } : {}),
+        ...normalizedUsage([...usage.values()], !options.resumeSessionId),
+    };
+}
+function normalizedUsage(events, fresh) {
+    if (!events.length)
+        return {};
+    let tokensIn = 0;
+    let tokensOut = 0;
+    let cacheHitTokensIn = 0;
+    let completeCache = true;
+    for (const event of events) {
+        const usage = record(event.usage);
+        const input = count(event.promptTokens);
+        const output = count(usage?.outputTokens);
+        if (input === undefined || output === undefined)
+            return {}; // No fabricated partial total.
+        tokensIn += input;
+        tokensOut += output;
+        const cache = count(usage?.cacheReadTokens);
+        if (cache === undefined || cache > input)
+            completeCache = false;
+        else
+            cacheHitTokensIn += cache;
+    }
+    if (!Number.isSafeInteger(tokensIn) || !Number.isSafeInteger(tokensOut))
+        return {};
+    const cost = record(record(events.at(-1)?.cumulative)?.cost);
+    return {
+        tokensIn, tokensOut,
+        ...(completeCache ? { cacheHitTokensIn } : {}),
+        ...(cost?.partial === false && typeof cost.usd === "number" && Number.isFinite(cost.usd) && cost.usd >= 0
+            ? { sessionCostUsd: cost.usd, ...(fresh ? { costUsd: cost.usd } : {}) } : {}),
+    };
+}
+/** Replace each provider session's cumulative estimate, never sum it per turn. */
+function sumMuseSessionCost(attempts) {
+    const sessions = new Map();
+    attempts.forEach((attempt, index) => sessions.set(attempt.agentSessionId ?? `attempt:${index}`, attempt.sessionCostUsd));
+    if (!sessions.size || [...sessions.values()].some((cost) => cost === undefined))
+        return undefined;
+    return [...sessions.values()].reduce((sum, cost) => sum + cost, 0);
+}
+async function prepareBridge(source, options) {
+    if (!Object.keys(source).length)
+        return { servers: {} };
+    if (!options.mcpMetadataDir || !node_path_1.default.isAbsolute(options.mcpMetadataDir))
+        throw new Error("Muse MCP needs a task-owned metadata directory.");
+    const dir = await node_fs_1.promises.mkdtemp(node_path_1.default.join(options.mcpMetadataDir, "muse-mcp-"));
+    try {
+        const configPath = node_path_1.default.join(dir, "servers.json");
+        const content = JSON.stringify(source);
+        await node_fs_1.promises.writeFile(configPath, content, { mode: 0o600 });
+        const digest = (0, node_crypto_1.createHash)("sha256").update(content).digest("hex");
+        const servers = Object.fromEntries(Object.keys(source).map((name) => [name, {
+                transport: "stdio", framing: "lineDelimitedJson", mode: "required",
+                command: options.dockerExec ? "navarch-muse-mcp-bridge" : process.execPath,
+                args: [...(options.dockerExec ? [] : [node_path_1.default.resolve(__dirname, "../../bin/muse-mcp-bridge.cjs")]), configPath, name, digest],
+            }]));
+        return { servers, dir };
+    }
+    catch (error) {
+        await node_fs_1.promises.rm(dir, { recursive: true, force: true });
+        throw error;
+    }
+}
+async function readMcpServers(configPath, env) {
+    if (!configPath)
+        return {};
+    const parsed = record(JSON.parse(await node_fs_1.promises.readFile(configPath, "utf8")));
+    const source = record(parsed?.mcpServers);
+    if (!source)
+        throw new Error("Muse MCP configuration must contain mcpServers.");
+    const result = Object.create(null);
+    const strings = (value) => {
+        const entries = value === undefined ? {} : record(value);
+        if (!entries)
+            throw new Error("Muse MCP environment/headers must be string maps.");
+        return Object.fromEntries(Object.entries(entries).map(([key, raw]) => {
+            if (typeof raw !== "string")
+                throw new Error("Muse MCP environment/headers must be string maps.");
+            const name = raw.match(/^\{env:([A-Z_][A-Z0-9_]*)\}$/)?.[1];
+            const value = name ? env[name] ?? process.env[name] : raw;
+            if (value === undefined)
+                throw new Error(`Muse MCP configuration references missing environment variable ${name}.`);
+            return [key, value];
+        }));
+    };
+    for (const [name, value] of Object.entries(source)) {
+        const server = record(value);
+        if (!server)
+            throw new Error("Muse MCP server configuration is invalid.");
+        const url = server.httpUrl ?? server.url;
+        if (typeof url === "string" && /^https?:\/\//.test(url) && (!server.type || ["http", "streamable-http"].includes(String(server.type)))) {
+            result[name] = { transport: "streamableHttp", url, headers: strings(server.headers), mode: "required" };
+        }
+        else if (typeof server.command === "string" && (!server.type || server.type === "stdio") && (!server.args || Array.isArray(server.args) && server.args.every((arg) => typeof arg === "string"))) {
+            result[name] = { transport: "stdio", command: server.command, args: server.args, env: strings(server.env), mode: "required" };
+        }
+        else
+            throw new Error("Muse MCP server transport is unsupported; no servers were silently dropped.");
+    }
+    return result;
+}
+function spawnMuse(options) {
+    const env = { ...process.env, ...options.env };
+    delete env.MUSE_PERMISSION_PROFILE_FAIL_OPEN;
+    const args = ["serve", ...options.extraArgs];
+    if (!options.dockerExec)
+        return (0, node_child_process_1.spawn)(options.bin, args, { cwd: options.cwd, env, detached: process.platform !== "win32", stdio: "pipe" });
+    return (0, node_child_process_1.spawn)("docker", [
+        "exec", "-i", ...Object.keys(options.env).filter((name) => name !== "MUSE_PERMISSION_PROFILE_FAIL_OPEN").flatMap((name) => ["--env", name]),
+        options.dockerExec.containerName, "sh", "-c",
+        '[ ! -f /tmp/session.env ] || . /tmp/session.env; unset MUSE_PERMISSION_PROFILE_FAIL_OPEN; cd "$1" || exit 1; shift; exec "$@"',
+        "sh", options.cwd, options.bin, ...args,
+    ], { env, detached: process.platform !== "win32", stdio: "pipe" });
+}
+// Read-only Navi conversations are deliberately absent: an approval mode is
+// not a filesystem read boundary, and the SDK cannot yet prove that contract.
+exports.museAdapter = { agentType: "muse", run: runMuseAdapter };

package/dist/agent-auth.cjs

@@ -43,7 +43,8 @@ function matchingLine(text) {
 function detectAgentAuthFailure(result) {
     if (result.killedByLeaseLoss || result.timedOut || result.capacityError)
         return null;
-    if (result.authError)
+    // Muse exposes authRequired as a typed terminal error, never assistant prose.
+    if (result.authError && result.exitCode !== 0)
         return { detail: result.authError };
     const claude = (0, exit_conditions_cjs_1.parseClaudeJsonResult)(result.stdout) ?? (0, exit_conditions_cjs_1.parseClaudeJsonResult)(result.stderr);
     if (claude) {