@sagentlab/navarch-runtime 0.1.111 → 0.1.116

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
@@ -478,6 +480,7 @@ unchanged across the deployment.
 | `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. |
 
@@ -578,7 +581,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.

package/dist/cli.cjs

@@ -303,7 +303,10 @@ async function startCommand(flags) {
         // runSession checkpoints or retains the worktree before releasing its
         // capacity slot.
         runtimeShutdown.abort();
-        void capacity.waitForIdle().then(() => process.exit(CREDENTIALS_REJECTED_EXIT_CODE));
+        // Mirror warming can outlive its conversation's capacity slot. Wait for
+        // its killed process and private-cache cleanup before exiting too.
+        void Promise.all([capacity.waitForIdle(), conversationLoop.drain()])
+            .then(() => process.exit(CREDENTIALS_REJECTED_EXIT_CODE));
     }, browserProbe);
     updateCoordinatorRef.current = new update_coordinator_cjs_1.RuntimeUpdateCoordinator({
         config,

package/dist/config.cjs

@@ -195,6 +195,7 @@ function loadRuntimeConfig(env = process.env) {
         browserProbe: !["off", "false", "0"].includes(env.NAVARCH_BROWSER_PROBE ?? ""),
         naviWorkspaceChat: ["on", "true", "1"].includes(env.NAVARCH_NAVI_WORKSPACE_CHAT ?? ""),
         naviConversations: !["off", "false", "0"].includes(env.NAVARCH_NAVI_CONVERSATIONS ?? ""),
+        conversationMirror: !["off", "false", "0"].includes(env.NAVARCH_CONVERSATION_MIRROR ?? ""),
         // The server stops waiting for a capability advertisement after 90 s and
         // asks for a poll at least every 30 s; the floor only bounds control-plane load.
         conversationPollIntervalMs: Math.min(30_000, Math.max(1_000, envInt(env, "NAVARCH_CONVERSATION_POLL_MS", 5_000))),

package/dist/conversation/loop.cjs

@@ -7,6 +7,7 @@ const worktree_guard_cjs_1 = require("../worktree-guard.cjs");
 const capability_cjs_1 = require("./capability.cjs");
 const journal_cjs_1 = require("./journal.cjs");
 const turn_runner_cjs_1 = require("./turn-runner.cjs");
+const mirror_cjs_1 = require("./mirror.cjs");
 const workspace_cjs_1 = require("./workspace.cjs");
 const MAX_BACKOFF_MS = 60_000;
 /** After a turn, poll fast for a while: a follow-up is likely and the poll is the only delivery path. */
@@ -16,6 +17,8 @@ const SWEEP_INTERVAL_MS = 30_000;
 const PRUNE_INTERVAL_MS = 6 * 60 * 60_000;
 /** The server keeps idempotency records for 24 hours; keep ours longer. */
 const JOURNAL_RETENTION_MS = 48 * 60 * 60_000;
+/** A repository mirror nobody has asked about for this long is removed; the next conversation rebuilds it. */
+const MIRROR_RETENTION_MS = 14 * 24 * 60 * 60_000;
 /**
  * Polls for queued Navi conversation turns and runs each on this machine's
  * configured adapter. Polling is also the capability advertisement: this loop
@@ -34,6 +37,7 @@ class ConversationLoop {
     lastPruneAt = -Infinity;
     active = new Set();
     journal;
+    mirrors;
     log;
     now;
     outcomes = [];
@@ -42,6 +46,13 @@ class ConversationLoop {
         this.journal = options.journal ?? new journal_cjs_1.ConversationJournal(options.config.workspaceRoot);
         this.log = options.log ?? (0, logger_cjs_1.createLogger)("navi");
         this.now = options.now ?? Date.now;
+        this.mirrors = options.config.conversationMirror
+            ? new mirror_cjs_1.ConversationMirrors(options.config.workspaceRoot, {
+                ...(options.gitRunner ? { runner: options.gitRunner } : {}),
+                ...(options.shutdownSignal ? { signal: options.shutdownSignal } : {}),
+                log: this.log,
+            })
+            : null;
     }
     /** Outcomes of turns this process ran, newest last; used for latency reporting and tests. */
     get recentOutcomes() {
@@ -59,6 +70,7 @@ class ConversationLoop {
             return;
         }
         this.stopped = false;
+        this.mirrors?.resume();
         this.failures = 0;
         this.log.info(`Navi conversations advertised on the ${this.options.config.agentType} adapter (${this.options.config.naviWorkspaceChat ? "read-only + workspace" : "read-only"}).`);
         this.schedule(0);
@@ -68,12 +80,14 @@ class ConversationLoop {
         if (this.timer)
             clearTimeout(this.timer);
         this.timer = null;
+        this.mirrors?.stop();
     }
     /** Stops new polls and waits for one already on the wire. Running turns finish on their own slots. */
     async drain() {
         this.stop();
         await this.polling;
         await this.housekeeping_;
+        await this.mirrors?.drain();
     }
     schedule(delayMs) {
         if (this.stopped)
@@ -173,6 +187,7 @@ class ConversationLoop {
         if (at - this.lastPruneAt >= PRUNE_INTERVAL_MS) {
             this.lastPruneAt = at;
             await this.journal.prune(JOURNAL_RETENTION_MS, this.options.config.workspaceRoot).catch(() => undefined);
+            await this.mirrors?.prune(MIRROR_RETENTION_MS, at).catch(() => undefined);
         }
     }
     async settle(journal) {
@@ -209,10 +224,11 @@ class ConversationLoop {
             ...(shutdownSignal ? { signal: shutdownSignal } : {}),
             ...this.options.turnOverrides,
             log: this.log,
-            prepareWorkspace: async ({ conversationId, repositoryUrl, mode, signal }) => {
+            prepareWorkspace: async ({ conversationId, repositoryUrl, workingBranch, mode, signal }) => {
                 const workspace = await (0, workspace_cjs_1.prepareConversationWorkspace)({
-                    workspaceRoot: config.workspaceRoot, conversationId, repositoryUrl, env, signal, mode,
+                    workspaceRoot: config.workspaceRoot, conversationId, repositoryUrl, workingBranch, env, signal, mode,
                     ...(this.options.gitRunner ? { runner: this.options.gitRunner } : {}),
+                    ...(this.mirrors ? { mirrors: this.mirrors } : {}),
                 });
                 const guard = await (0, worktree_guard_cjs_1.prepareWorktreeGuard)({
                     workDir: workspace.metaDir,

package/dist/conversation/mirror.cjs

@@ -0,0 +1,225 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConversationMirrors = void 0;
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+const sandbox_cjs_1 = require("../sandbox.cjs");
+/** Incremental fetch of an existing mirror; a full first clone runs in the background instead. */
+const MIRROR_FETCH_TIMEOUT_MS = 60_000;
+const MIRROR_CLONE_TIMEOUT_MS = 15 * 60_000;
+const LOCAL_CLONE_TIMEOUT_MS = 3 * 60_000;
+const MIRRORS_DIR = "conversation-mirrors";
+/**
+ * Machine-level bare mirrors that seed Navi conversation checkouts.
+ *
+ * A fresh network clone of a large repository took ~35 s per new conversation,
+ * which was nearly all of the first answer's latency. With a mirror, a new
+ * conversation costs one incremental `git fetch` from GitHub plus a local,
+ * local `git clone` without a second network transfer.
+ *
+ * - The fetch uses the machine's own git credentials on every new
+ *   conversation, so a machine that lost access still fails the turn instead
+ *   of answering from a stale copy.
+ * - Checkouts copy their objects, without hardlinks or alternates. Writable
+ *   chat must not be able to change another conversation's object inodes.
+ * - The first conversation of a repository on a machine keeps the direct
+ *   clone; the mirror is built afterwards in the background and published by
+ *   an atomic rename, so an interrupted build is never mistaken for a mirror.
+ */
+class ConversationMirrors {
+    options;
+    root;
+    runner;
+    /** Serializes git operations per mirror within this process. */
+    locks = new Map();
+    building = new Map();
+    warming = new AbortController();
+    paused = false;
+    constructor(workspaceRoot, options = {}) {
+        this.options = options;
+        this.root = node_path_1.default.join(workspaceRoot, MIRRORS_DIR);
+        this.runner = options.runner ?? sandbox_cjs_1.nodeCommandRunner;
+    }
+    /** Mirror location for a validated https repository URL. */
+    mirrorPath(url) {
+        return node_path_1.default.join(this.root, `${(0, node_crypto_1.createHash)("sha256").update(url).digest("hex").slice(0, 32)}.git`);
+    }
+    /**
+     * Refreshes the repository's mirror and clones `checkout` from it. Returns
+     * false (leaving no checkout behind) when there is no usable mirror, so the
+     * caller clones from the network instead.
+     */
+    async seedCheckout(options) {
+        const mirror = this.mirrorPath(options.url);
+        if (!(await this.usableMirror(mirror)))
+            return false;
+        return this.locked(mirror, () => this.withDiskLock(mirror, false, async () => {
+            if (!(await this.usableMirror(mirror)))
+                return false;
+            const fetched = await this.runner.run("git", ["--git-dir", mirror, "fetch", "--quiet", "--prune", "--no-tags", "--", options.url, "+refs/heads/*:refs/heads/*"], { cwd: this.root, env: options.env, timeoutMs: MIRROR_FETCH_TIMEOUT_MS, signal: options.signal });
+            if (fetched.code !== 0) {
+                if (options.signal?.aborted)
+                    return false;
+                // Lost access, or a damaged mirror. Either way it must not seed this
+                // conversation; the direct clone decides whether the turn can run and
+                // a successful one rebuilds the mirror.
+                this.options.log?.warn(`conversation mirror fetch failed with exit ${fetched.code}; cloning directly`);
+                await node_fs_1.promises.rm(mirror, { recursive: true, force: true }).catch(() => undefined);
+                return false;
+            }
+            const now = new Date();
+            await node_fs_1.promises.utimes(mirror, now, now).catch(() => undefined);
+            let branch = options.branch;
+            if (!branch) {
+                // Fetch updates refs, not the bare repository's symbolic HEAD. Query
+                // the current remote default instead of silently using its old value.
+                const remoteHead = await this.runner.run("git", ["ls-remote", "--symref", "--exit-code", "--", options.url, "HEAD"], { cwd: this.root, env: options.env, timeoutMs: MIRROR_FETCH_TIMEOUT_MS, signal: options.signal });
+                const ref = /^ref: (refs\/heads\/[A-Za-z0-9][A-Za-z0-9._/-]*)\tHEAD$/m.exec(remoteHead.stdout)?.[1];
+                if (remoteHead.code !== 0 || !ref || ref.includes(".."))
+                    return false;
+                branch = ref.slice("refs/heads/".length);
+                const updated = await this.runner.run("git", ["--git-dir", mirror, "symbolic-ref", "HEAD", ref], { cwd: this.root, env: options.env, timeoutMs: 30_000, signal: options.signal });
+                if (updated.code !== 0)
+                    return false;
+            }
+            const cloned = await this.runner.run("git", ["clone", "--quiet", "--local", "--no-hardlinks", "--no-tags", "--branch", branch, "--", mirror, options.checkout], 
+            // Only this clone reads a local path, and only the mirror this runtime built.
+            { cwd: node_path_1.default.dirname(options.checkout), env: { ...options.env, GIT_ALLOW_PROTOCOL: "file" }, timeoutMs: LOCAL_CLONE_TIMEOUT_MS, signal: options.signal });
+            if (cloned.code === 0) {
+                // The agent's `git fetch`/`git log origin/...` must see GitHub, not this machine's mirror path.
+                const repointed = await this.runner.run("git", ["-C", options.checkout, "remote", "set-url", "origin", options.url], { cwd: options.checkout, env: options.env, timeoutMs: 30_000, signal: options.signal });
+                if (repointed.code === 0)
+                    return true;
+            }
+            this.options.log?.warn(`conversation checkout from mirror failed with exit ${cloned.code}; cloning directly`);
+            await node_fs_1.promises.rm(options.checkout, { recursive: true, force: true }).catch(() => undefined);
+            return false;
+        }));
+    }
+    /**
+     * Builds the repository's mirror in the background if it does not exist.
+     * Called after a direct clone succeeded with the same credentials, so it
+     * never delays a turn and never runs for a repository this machine cannot read.
+     */
+    warm(url, env, signal) {
+        if (this.paused || signal?.aborted || this.options.signal?.aborted)
+            return Promise.resolve();
+        const mirror = this.mirrorPath(url);
+        const pending = this.building.get(mirror);
+        if (pending)
+            return pending;
+        const controller = new AbortController();
+        const signals = [this.warming.signal, signal, this.options.signal].filter((s) => !!s);
+        const abort = () => controller.abort();
+        for (const source of signals) {
+            source.addEventListener("abort", abort, { once: true });
+            if (source.aborted)
+                abort();
+        }
+        const build = this.locked(mirror, () => this.withDiskLock(mirror, undefined, async () => {
+            if (controller.signal.aborted || await this.usableMirror(mirror))
+                return;
+            const partial = await node_fs_1.promises.mkdtemp(`${mirror}.partial-`);
+            try {
+                const result = await this.runner.run("git", ["clone", "--quiet", "--bare", "--no-tags", "--", url, partial], { cwd: this.root, env, timeoutMs: MIRROR_CLONE_TIMEOUT_MS, signal: controller.signal });
+                if (controller.signal.aborted)
+                    return;
+                if (result.code !== 0 || !(await regularFile(node_path_1.default.join(partial, "HEAD")))) {
+                    throw new Error(`git clone --bare failed with exit ${result.code}`);
+                }
+                await node_fs_1.promises.rename(partial, mirror);
+            }
+            finally {
+                await node_fs_1.promises.rm(partial, { recursive: true, force: true }).catch(() => undefined);
+            }
+        }))
+            // A credential helper can put secrets in stderr or spawn errors. Cache
+            // diagnostics must not copy those values into persistent runtime logs.
+            .catch(() => this.options.log?.warn("conversation mirror build failed; direct cloning remains available"))
+            .finally(() => {
+            for (const source of signals)
+                source.removeEventListener("abort", abort);
+            this.building.delete(mirror);
+        });
+        this.building.set(mirror, build);
+        return build;
+    }
+    resume() {
+        this.paused = false;
+        if (this.warming.signal.aborted)
+            this.warming = new AbortController();
+    }
+    stop() {
+        this.paused = true;
+        this.warming.abort();
+    }
+    async drain() {
+        this.stop();
+        await Promise.allSettled([...this.building.values()]);
+    }
+    /** Removes mirrors (and abandoned partial builds) no conversation has used for `maxAgeMs`. */
+    async prune(maxAgeMs, now = Date.now()) {
+        if (!(await directory(this.root)))
+            return;
+        const entries = await node_fs_1.promises.readdir(this.root, { withFileTypes: true }).catch(() => []);
+        for (const entry of entries) {
+            if (!entry.isDirectory() || !/^[0-9a-f]{32}\.git(\.partial(?:-[A-Za-z0-9]+)?)?$/.test(entry.name))
+                continue;
+            const mirror = node_path_1.default.join(this.root, entry.name).replace(/\.partial(?:-[A-Za-z0-9]+)?$/, "");
+            if (this.locks.has(mirror))
+                continue;
+            await this.locked(mirror, () => this.withDiskLock(mirror, undefined, async () => {
+                const target = node_path_1.default.join(this.root, entry.name);
+                const stat = await node_fs_1.promises.lstat(target).catch(() => null);
+                if (!stat?.isDirectory() || now - stat.mtimeMs < maxAgeMs)
+                    return;
+                await node_fs_1.promises.rm(target, { recursive: true, force: true }).catch(() => undefined);
+            }));
+        }
+    }
+    async usableMirror(mirror) {
+        return await directory(this.root) && await directory(mirror) && await regularFile(node_path_1.default.join(mirror, "HEAD"));
+    }
+    /** Other runtime processes fall back to direct clones while this cache is busy.
+     * A crashed holder leaves a stale lock; never steal it based only on age. */
+    async withDiskLock(mirror, unavailable, work) {
+        await node_fs_1.promises.mkdir(this.root, { recursive: true, mode: 0o700 });
+        if (!(await directory(this.root)))
+            return unavailable;
+        const lock = `${mirror}.lock`;
+        try {
+            await node_fs_1.promises.mkdir(lock, { mode: 0o700 });
+        }
+        catch (error) {
+            if (error.code === "EEXIST")
+                return unavailable;
+            throw error;
+        }
+        try {
+            return await work();
+        }
+        finally {
+            await node_fs_1.promises.rm(lock, { recursive: true, force: true });
+        }
+    }
+    locked(mirror, work) {
+        const previous = this.locks.get(mirror) ?? Promise.resolve();
+        const next = previous.catch(() => undefined).then(work);
+        const tail = next.catch(() => undefined);
+        this.locks.set(mirror, tail);
+        void tail.then(() => { if (this.locks.get(mirror) === tail)
+            this.locks.delete(mirror); });
+        return next;
+    }
+}
+exports.ConversationMirrors = ConversationMirrors;
+async function directory(file) {
+    return node_fs_1.promises.lstat(file).then((stat) => stat.isDirectory(), () => false);
+}
+async function regularFile(file) {
+    return node_fs_1.promises.lstat(file).then((stat) => stat.isFile(), () => false);
+}

package/dist/conversation/turn-runner.cjs

@@ -298,7 +298,9 @@ async function runConversationTurn(deps, conversationId, turnId) {
             if (snapshot.mode === "workspace" && !deps.workspaceEnabled)
                 throw new Error("Workspace chat is disabled on this machine");
             prompt = (0, prompt_cjs_1.buildConversationPrompt)(snapshot, journal.turnId);
-            prepared = await deps.prepareWorkspace({ conversationId, repositoryUrl, mode: snapshot.mode ?? "read_only", signal: controller.signal });
+            // Older servers omit the working branch: the checkout stays on the default branch.
+            const workingBranch = (0, workspace_cjs_1.validWorkingBranch)(claim.workingBranch);
+            prepared = await deps.prepareWorkspace({ conversationId, repositoryUrl, workingBranch, mode: snapshot.mode ?? "read_only", signal: controller.signal });
         }
         catch (error) {
             if (!run.lost)

package/dist/conversation/workspace.cjs

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.conversationEnv = conversationEnv;
 exports.validRepositoryUrl = validRepositoryUrl;
+exports.validWorkingBranch = validWorkingBranch;
 exports.conversationRoot = conversationRoot;
 exports.prepareConversationWorkspace = prepareConversationWorkspace;
 exports.removeConversationWorkspace = removeConversationWorkspace;
@@ -50,6 +51,22 @@ function validRepositoryUrl(value) {
         return null;
     return `https://github.com/${fullName}.git`;
 }
+/**
+ * The project's working branch from the claim, checked as strictly as the
+ * hosted path's `buildWorkingBranchCheckoutCommand`
+ * (worker/hosted-agent/delivery.ts): a plain ref name that cannot be read as a
+ * git option. Absent (an older server, or no working branch) is null; anything
+ * else that is not a plain name throws, so the turn never runs on a branch it
+ * was not given.
+ */
+function validWorkingBranch(value) {
+    if (value === undefined || value === null)
+        return null;
+    if (typeof value !== "string" || value.length > 255 || !/^[A-Za-z0-9][A-Za-z0-9._/-]*$/.test(value) || value.includes("..")) {
+        throw new Error("working branch is not a valid branch name");
+    }
+    return value;
+}
 function conversationRoot(workspaceRoot, conversationId) {
     return node_path_1.default.join(workspaceRoot, "conversations", (0, journal_cjs_1.assertUuid)(conversationId, "conversation id"));
 }
@@ -62,11 +79,18 @@ function conversationRoot(workspaceRoot, conversationId) {
  * The clone uses the machine's own git credentials (the same ones a local
  * `git clone` would use), never a Navarch server-side provider credential.
  * A repository this machine cannot read fails the turn instead of falling back.
+ * With `mirrors`, a new checkout is seeded from this machine's refreshed
+ * mirror of the repository instead of a full network clone (see mirror.cts).
  */
 async function prepareConversationWorkspace(options) {
     const url = validRepositoryUrl(options.repositoryUrl);
     if (!url)
         throw new Error("repository URL is not a plain https URL");
+    const branch = validWorkingBranch(options.workingBranch);
+    // The marker records what the checkout was cloned from, so a changed
+    // repository or working branch is noticed. Default-branch checkouts keep the
+    // bare URL that earlier runtimes wrote.
+    const identity = branch ? `${url}\nbranch=${branch}` : url;
     const runner = options.runner ?? sandbox_cjs_1.nodeCommandRunner;
     const root = options.mode === "workspace"
         ? node_path_1.default.join(options.workspaceRoot, "chat-workspaces", (0, journal_cjs_1.assertUuid)(options.conversationId, "conversation id"))
@@ -83,7 +107,7 @@ async function prepareConversationWorkspace(options) {
     if (options.mode === "workspace") {
         await node_fs_1.promises.writeFile(node_path_1.default.join(workspace.metaDir, "preserve-workspace"), "Workspace chat: retain until the operator removes it.\n", { mode: 0o600 });
     }
-    if (hasCheckout && recorded === url)
+    if (hasCheckout && recorded === identity)
         return workspace;
     if (options.mode === "workspace") {
         const exists = await node_fs_1.promises.lstat(workspace.checkout).then(() => true, (error) => {
@@ -94,7 +118,7 @@ async function prepareConversationWorkspace(options) {
         if (exists)
             throw new Error("Checkout identity changed; preserving the existing workspace. Start a new conversation.");
     }
-    // New conversation, a changed repository URL, or an interrupted clone.
+    // New conversation, a changed repository URL or working branch, or an interrupted clone.
     await node_fs_1.promises.rm(workspace.checkout, { recursive: true, force: true });
     const env = {
         ...options.env,
@@ -104,12 +128,17 @@ async function prepareConversationWorkspace(options) {
         GIT_CONFIG_KEY_0: "core.hooksPath",
         GIT_CONFIG_VALUE_0: process.platform === "win32" ? "NUL" : "/dev/null",
     };
-    const result = await runner.run("git", ["clone", "--quiet", "--filter=blob:none", "--no-tags", "--", url, workspace.checkout], { cwd: root, env, timeoutMs: CLONE_TIMEOUT_MS, signal: options.signal });
-    if (result.code !== 0) {
-        await node_fs_1.promises.rm(workspace.checkout, { recursive: true, force: true }).catch(() => undefined);
-        throw new Error(`git clone failed with exit ${result.code}: ${result.stderr.slice(-500)}`);
+    const seeded = await options.mirrors?.seedCheckout({ url, branch, checkout: workspace.checkout, env, signal: options.signal }) ?? false;
+    if (!seeded) {
+        const result = await runner.run("git", ["clone", "--quiet", "--filter=blob:none", "--no-tags", ...(branch ? ["--branch", branch] : []), "--", url, workspace.checkout], { cwd: root, env, timeoutMs: CLONE_TIMEOUT_MS, signal: options.signal });
+        if (result.code !== 0) {
+            await node_fs_1.promises.rm(workspace.checkout, { recursive: true, force: true }).catch(() => undefined);
+            throw new Error(`git clone failed with exit ${result.code}: ${result.stderr.slice(-500)}`);
+        }
+        // This machine can read the repository: build the mirror for the next conversation.
+        void options.mirrors?.warm(url, env, options.signal);
     }
-    await node_fs_1.promises.writeFile(marker, url, { encoding: "utf8", mode: 0o600 });
+    await node_fs_1.promises.writeFile(marker, identity, { encoding: "utf8", mode: 0o600 });
     return workspace;
 }
 async function removeConversationWorkspace(workspaceRoot, conversationId) {

package/dist/worktree-guard.cjs

@@ -8,6 +8,7 @@ exports.readClaudeApiKeyHelper = readClaudeApiKeyHelper;
 exports.prepareWorktreeGuard = prepareWorktreeGuard;
 exports.codexToolReadRoots = codexToolReadRoots;
 exports.codexExecutableReadRoots = codexExecutableReadRoots;
+exports.codexHelperReadRoots = codexHelperReadRoots;
 exports.macosDeveloperWriteRoots = macosDeveloperWriteRoots;
 exports.sessionGhConfigDir = sessionGhConfigDir;
 exports.sessionCodexTmpDir = sessionCodexTmpDir;
@@ -175,7 +176,7 @@ function codexExecutableReadRoots(bin, env = process.env) {
     const roots = [node_path_1.default.dirname(resolved), node_path_1.default.dirname(real)];
     const packageRoot = /^(.*\/node_modules\/(?:@[^/]+\/)?[^/]+)\//.exec(real)?.[1];
     if (packageRoot)
-        roots.push(packageRoot);
+        roots.push(packageRoot, ...siblingPlatformPackages(packageRoot, env));
     const homeDir = env.HOME?.trim() || node_os_1.default.homedir();
     const sensitive = [homeDir, env.CODEX_HOME?.trim() || node_path_1.default.join(homeDir, ".codex")].flatMap((dir) => {
         try {
@@ -187,6 +188,131 @@ function codexExecutableReadRoots(bin, env = process.env) {
     });
     return [...new Set(roots.map((root) => node_path_1.default.resolve(root)))].filter((root) => !sensitive.some((target) => isPathInside(target, root)));
 }
+/**
+ * npm installs the vendored native binary as a sibling package
+ * (`@openai/codex-linux-x64`) when the layout is hoisted (a local or
+ * `--prefix` install) and nests it under the wrapper only for some global
+ * installs. The wrapper's own root alone then leaves the binary unmounted.
+ */
+function siblingPlatformPackages(packageRoot, env) {
+    const scopeDir = node_path_1.default.dirname(packageRoot);
+    if (node_path_1.default.basename(packageRoot) !== "codex" || node_path_1.default.basename(scopeDir) !== "@openai")
+        return [];
+    // These are npm aliases of @openai/codex, not arbitrary similarly named siblings.
+    // See codex-cli/scripts/build_npm_package.py and bin/codex.js in Codex 0.162.1.
+    const targets = {
+        "codex-linux-x64": ["linux", "x64", "x86_64-unknown-linux-musl"],
+        "codex-linux-arm64": ["linux", "arm64", "aarch64-unknown-linux-musl"],
+        "codex-darwin-x64": ["darwin", "x64", "x86_64-apple-darwin"],
+        "codex-darwin-arm64": ["darwin", "arm64", "aarch64-apple-darwin"],
+        "codex-win32-x64": ["win32", "x64", "x86_64-pc-windows-msvc"],
+        "codex-win32-arm64": ["win32", "arm64", "aarch64-pc-windows-msvc"],
+    };
+    const homeDir = env.HOME?.trim() || node_os_1.default.homedir();
+    const codexHome = canonicalPathWithMissingTail(env.CODEX_HOME?.trim() || node_path_1.default.join(homeDir, ".codex"));
+    if (!codexHome)
+        return [];
+    try {
+        return (0, node_fs_1.readdirSync)(scopeDir).flatMap((name) => {
+            const target = targets[name];
+            if (!target)
+                return [];
+            try {
+                const real = (0, node_fs_1.realpathSync)(node_path_1.default.join(scopeDir, name));
+                if (!(0, node_fs_1.statSync)(real).isDirectory())
+                    return [];
+                // Existing managed package roots are already allowed, but credentials,
+                // config and arbitrary other CODEX_HOME descendants must not be added.
+                if (isPathInside(real, codexHome) && !isPathInside(real, node_path_1.default.join(codexHome, "packages")))
+                    return [];
+                const manifestPath = (0, node_fs_1.realpathSync)(node_path_1.default.join(real, "package.json"));
+                const manifestStat = (0, node_fs_1.statSync)(manifestPath);
+                if (!isPathInside(manifestPath, real) || !manifestStat.isFile() || manifestStat.size > 64 * 1024)
+                    return [];
+                const manifest = JSON.parse((0, node_fs_1.readFileSync)(manifestPath, "utf8"));
+                const [platform, arch, triple] = target;
+                if (manifest.name !== "@openai/codex" || !Array.isArray(manifest.os) || !manifest.os.includes(platform)
+                    || !Array.isArray(manifest.cpu) || !manifest.cpu.includes(arch))
+                    return [];
+                const native = (0, node_fs_1.realpathSync)(node_path_1.default.join(real, "vendor", triple, "bin", platform === "win32" ? "codex.exe" : "codex"));
+                if (!isPathInside(native, real) || !(0, node_fs_1.statSync)(native).isFile())
+                    return [];
+                return [real];
+            }
+            catch {
+                return [];
+            }
+        });
+    }
+    catch {
+        return [];
+    }
+}
+/** Resolve existing ancestors without treating a dangling link as a missing directory. */
+function canonicalPathWithMissingTail(root) {
+    let current = node_path_1.default.resolve(root);
+    const missing = [];
+    for (;;) {
+        try {
+            return node_path_1.default.join((0, node_fs_1.realpathSync)(current), ...missing.reverse());
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                return undefined;
+            try {
+                (0, node_fs_1.lstatSync)(current);
+                return undefined; // Existing but unresolvable (for example a dangling symlink).
+            }
+            catch (statError) {
+                if (statError.code !== "ENOENT")
+                    return undefined;
+            }
+            const parent = node_path_1.default.dirname(current);
+            if (parent === current)
+                return undefined;
+            missing.push(node_path_1.default.basename(current));
+            current = parent;
+        }
+    }
+}
+/**
+ * Where Codex keeps its per-run `codex-linux-sandbox` helper links.
+ *
+ * Codex creates `$CODEX_HOME/tmp/arg0/<run>/codex-linux-sandbox` (a link
+ * to its own binary) and puts that directory first on PATH. The Linux sandbox
+ * re-executes the helper by that bare name inside bwrap's empty `/`, so
+ * without this read grant every sandboxed command fails with
+ * `bwrap: execvp codex-linux-sandbox: No such file or directory`. The grant
+ * is limited to `tmp/arg0`, which holds only those links; auth.json and the
+ * rest of CODEX_HOME stay unmounted.
+ */
+function codexHelperReadRoots(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");
+    // CODEX_HOME itself may be an operator-owned alias. Below it, only the
+    // actual helper directories are accepted; aliases must not broaden this grant.
+    try {
+        if (!(0, node_fs_1.statSync)(codexHome).isDirectory())
+            return [];
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            return [];
+    }
+    for (const root of [node_path_1.default.join(codexHome, "tmp"), node_path_1.default.join(codexHome, "tmp", "arg0")]) {
+        try {
+            const info = (0, node_fs_1.lstatSync)(root);
+            if (info.isSymbolicLink() || !info.isDirectory())
+                return [];
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                return [];
+        }
+    }
+    const helperRoot = node_path_1.default.join(codexHome, "tmp", "arg0");
+    return canonicalPathWithMissingTail(helperRoot) ? [helperRoot] : [];
+}
 function resolveExecutable(bin, env) {
     const candidates = bin.includes("/")
         ? [node_path_1.default.resolve(bin)]
@@ -298,10 +424,18 @@ function codexWorktreeGuardArgs(options, platform = process.platform) {
     const gitdir = linkedWorktreeGitDir(options.worktreePath, options.repositoryPath);
     if (gitdir)
         filesystem[gitdir] = "write";
-    const overlapsWorkspace = (root) => isPathInside(root, workspaceRoot) || (linux && isPathInside(workspaceRoot, root));
+    const canonicalWorkspace = canonicalPathWithMissingTail(workspaceRoot);
+    const overlapsWorkspace = (root) => {
+        const canonicalRoot = canonicalPathWithMissingTail(root);
+        if (!canonicalRoot || !canonicalWorkspace)
+            return true;
+        return isPathInside(root, workspaceRoot) || (linux && isPathInside(workspaceRoot, root))
+            || isPathInside(canonicalRoot, canonicalWorkspace) || (linux && isPathInside(canonicalWorkspace, canonicalRoot));
+    };
     const readRoots = [
         ...codexToolReadRoots(process.env, platform),
         ...(linux && options.codexBin ? codexExecutableReadRoots(options.codexBin) : []),
+        ...(linux ? codexHelperReadRoots() : []),
     ];
     for (const root of readRoots) {
         const resolved = node_path_1.default.resolve(root);
@@ -390,7 +524,7 @@ function geminiSandboxMounts(options) {
 }
 function isPathInside(candidate, root) {
     const relative = node_path_1.default.relative(root, candidate);
-    return relative === "" || (!relative.startsWith("..") && !node_path_1.default.isAbsolute(relative));
+    return relative === "" || (relative !== ".." && !relative.startsWith(`..${node_path_1.default.sep}`) && !node_path_1.default.isAbsolute(relative));
 }
 function tomlInlineTable(table) {
     return `{${Object.entries(table)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sagentlab/navarch-runtime",
-  "version": "0.1.111",
+  "version": "0.1.116",
   "description": "Navarch machine-side session manager: claims delivery tasks and runs them through local coding agents.",
   "type": "commonjs",
   "license": "MIT",