@sagentlab/navarch-runtime 0.1.92 → 0.1.95

package/README.md

@@ -9,6 +9,16 @@ 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.
 
+The same server offers interactive `local_browser_open`, `local_browser_click`,
+`local_browser_fill`, `local_browser_press`, `local_browser_snapshot`, and
+`local_browser_screenshot` tools for walking through a service the agent starts
+on this machine. That browser is limited to loopback (`localhost`,
+`*.localhost`, `127.0.0.0/8`, `::1`). Every request, WebSocket, or navigation
+to any other host is aborted and listed in the tool result. The agent's own
+sandbox can already reach these services, so the tools add a browser without
+adding network reach. Each lease gets one tab at a time, a fresh context per
+viewport, and at most 300 actions.
+
 Install the runtime's pinned browser once on the agent host (and after a
 Playwright version update):
 
@@ -36,9 +46,13 @@ lifetime, so restart the agent after fixing the browser to re-probe.
 `navarch-runtime doctor` runs the same check.
 
 Codex's macOS seatbelt denies Chromium's Mach port registration
-(`bootstrap_check_in ... MachPortRendezvousServer: Permission denied`), so a
-sandboxed Codex machine on macOS does not take browser tasks. Run those with
-another agent such as Claude Code, or use Docker mode. Docker mode is not
+(`bootstrap_check_in ... MachPortRendezvousServer: Permission denied`), and
+`--single-process` crashes once a second page opens. When Node runs in the
+sandbox and only Chromium fails, the probe still passes, with that reason. Codex
+sessions then browse local services through the `local_browser_*` tools above,
+and the session prompt tells them to. With an operator `NAVARCH_MCP_CONFIG_PATH`
+those tools are absent, so the machine does not take browser tasks; run those
+with another agent such as Claude Code, or use Docker mode. Docker mode is not
 probed because its image supplies the browser. Set `NAVARCH_BROWSER_PROBE=off`
 to trust the configured capability list without a check.
 
@@ -316,13 +330,14 @@ own budgets. An absolute limit covers all guidance/remediation turns within the
 claim, rather than resetting with each turn. These are runtime limits, not
 provider spending caps.
 
-After a watchdog stop or lease loss during a turn, before worktree cleanup, the runtime attempts a private
+After a watchdog stop, lease loss during a turn, or exhausted delivery correction
+turns, before worktree cleanup, the runtime attempts a private
 local recovery checkpoint at
 `<workspaceRoot>/checkpoints/<project>/<task>/<session>/`. It contains a Git
 bundle of committed history, a binary patch for dirty tracked files, untracked
 non-ignored files, and recovery instructions. The bundle excludes repository
 configuration and broker credentials. Checkpoints are not pushed or uploaded;
-timeout reports and runtime logs name their location. They survive session cleanup and need
+failure reports and runtime logs name their location. They survive session cleanup and need
 manual recovery and removal on that machine. Ignored files, agent conversation
 state, and checkpoints across machine/disk loss are not provided.
 
@@ -490,7 +505,9 @@ as an explicit read-only mount.
 - **Codex:** the runtime passes a one-off native permission profile with
   `approval_policy="on-request"` and `approvals_reviewer="auto_review"`.
   Codex's OS sandbox grants read/write access only to the allowed roots and
-  denies the surrounding multi-session workspace. Its network policy allows
+  denies the surrounding multi-session workspace. After preparing the worktree,
+  the runtime explicitly grants its resolved linked Git metadata directory write
+  access so staging and committing work inside the sandbox. Its network policy allows
   GitHub and GitHub-hosted content so authenticated `gh` and git operations
   required by the task stay inside the sandbox. Other destinations remain
   blocked and eligible escalations are decided by the automatic reviewer

package/dist/browser-evidence.cjs

@@ -13,6 +13,7 @@ const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
 const streamableHttp_js_1 = require("@modelcontextprotocol/sdk/server/streamableHttp.js");
 const playwright_1 = require("playwright");
 const zod_1 = require("zod");
+const local_browser_cjs_1 = require("./local-browser.cjs");
 const node_child_process_1 = require("node:child_process");
 const node_util_1 = require("node:util");
 const node_path_1 = __importDefault(require("node:path"));
@@ -46,7 +47,8 @@ const captureShape = {
 exports.captureSchema = zod_1.z.object(captureShape);
 /** Runs in the supervisor, outside the coding agent's OS sandbox. Fresh
  * contexts have no user cookies, arbitrary script execution, or file access.
- * Only the narrow capture operation is exposed to the lease. */
+ * The lease gets the narrow capture operation plus the loopback-only
+ * local_browser_* tools (local-browser.cts). */
 async function startBrowserEvidence(options) {
     const token = (0, node_crypto_1.randomBytes)(32).toString("hex");
     const fetchImpl = options.fetchImpl ?? fetch;
@@ -57,6 +59,10 @@ async function startBrowserEvidence(options) {
     let browser;
     let activeCapture;
     let attempts = 0;
+    const localBrowser = (0, local_browser_cjs_1.createLocalBrowser)({
+        launch: options.launch ?? launchCaptureBrowser,
+        isActive: () => !closed && options.isActive(),
+    });
     const assertActive = () => {
         if (closed || !options.isActive())
             throw new Error("Browser evidence lease is no longer active.");
@@ -204,6 +210,7 @@ async function startBrowserEvidence(options) {
                 return { isError: true, content: [{ type: "text", text: String(error) }] };
             }
         });
+        (0, local_browser_cjs_1.registerLocalBrowserTools)(server, localBrowser);
         res.on("close", () => { void transport.close(); void server.close(); });
         try {
             await server.connect(transport);
@@ -253,6 +260,7 @@ async function startBrowserEvidence(options) {
             const stopped = new Promise((resolve) => http.close(() => resolve()));
             http.closeAllConnections();
             await browser?.close().catch(() => undefined);
+            await localBrowser.close();
             await activeCapture?.catch(() => undefined);
             await stopped;
         },

package/dist/browser-probe.cjs

@@ -74,8 +74,19 @@ async function probeBrowserCapability(config, deps = {}) {
     const platform = deps.platform ?? process.platform;
     if (codexSandboxNeedsProbe(config, platform)) {
         const sandboxFailure = await probeCodexSandbox(config, deps);
+        if (sandboxFailure?.browserOnly && !config.mcpConfigPath) {
+            // Node runs in the sandbox, so the agent can start its services there;
+            // only Chromium cannot. Sessions get the supervisor's local_browser_*
+            // tools (local-browser.cts) instead, which reach the same loopback.
+            return {
+                status: "passed",
+                reason: truncate(`Headless Chromium cannot start inside the Codex sandbox (${sandboxFailure.detail}); ` +
+                    "Codex sessions browse local services through Navarch's local_browser tools, which run outside it."),
+                checked_at: now().toISOString(),
+            };
+        }
         if (sandboxFailure) {
-            return { status: "failed", reason: truncate(sandboxFailure), checked_at: now().toISOString() };
+            return { status: "failed", reason: truncate(sandboxFailure.reason), checked_at: now().toISOString() };
         }
     }
     return { status: "passed", checked_at: now().toISOString() };
@@ -215,8 +226,9 @@ async function probeCodexSandbox(config, deps) {
             // sandbox view: a path outside the granted read roots, not an old CLI.
             const hidden = /bwrap: execvp .*No such file or directory/.test(output);
             const opensslConfig = /OpenSSL configuration error/.test(output);
-            return ("Could not verify a browser inside the Codex sandbox: `codex sandbox` did not run the probe " +
-                `(${result.timedOut ? "timed out" : output.trim() ? summarizeLaunchFailure(output) : `exit ${result.code}`}). ` +
+            const detail = result.timedOut ? "timed out" : output.trim() ? summarizeLaunchFailure(output) : `exit ${result.code}`;
+            const reason = ("Could not verify a browser inside the Codex sandbox: `codex sandbox` did not run the probe " +
+                `(${detail}). ` +
                 (hidden
                     ? "The sandbox cannot see that executable; add its install directory to NAVARCH_GUARD_EXTRA_ROOTS, " +
                         "or run browser tasks with another agent."
@@ -224,19 +236,22 @@ async function probeCodexSandbox(config, deps) {
                         ? "Node cannot read its OpenSSL config inside the sandbox, so Codex sessions cannot run node either; " +
                             "update the Navarch runtime, or add that file's directory to NAVARCH_GUARD_EXTRA_ROOTS."
                         : "Update the Codex CLI, or run browser tasks with another agent."));
+            return { reason, detail, browserOnly: false };
         }
         const detail = result.timedOut ? "the launch timed out." : summarizeLaunchFailure(output);
         const machPort = /bootstrap_check_in|MachPortRendezvous|mach_port_rendezvous/i.test(output);
-        return (`Headless Chromium cannot start inside the Codex sandbox: ${detail} ` +
+        const reason = (`Headless Chromium cannot start inside the Codex sandbox: ${detail} ` +
             (machPort
                 ? "Codex's macOS sandbox denies Chromium's Mach port registration. "
                 : "") +
             "Run browser tasks with another agent (for example Claude Code), use NAVARCH_SANDBOX_MODE=docker, " +
             "or run Codex without its sandbox.");
+        return { reason, detail, browserOnly: true };
     }
     catch (error) {
         log.warn(`codex sandbox browser probe could not run: ${String(error)}`);
-        return `Could not verify a browser inside the Codex sandbox: ${summarizeLaunchFailure(String(error))}`;
+        const detail = summarizeLaunchFailure(String(error));
+        return { reason: `Could not verify a browser inside the Codex sandbox: ${detail}`, detail, browserOnly: false };
     }
     finally {
         await node_fs_1.promises.rm(probeRoot, { recursive: true, force: true }).catch(() => undefined);

package/dist/cli.cjs

@@ -248,7 +248,7 @@ async function startCommand(flags) {
         log.warn(`not advertising browser-use: ${browserProbe.reason}`);
     }
     else if (browserProbe.status === "passed") {
-        log.info("browser probe passed; advertising browser-use");
+        log.info(`browser probe passed; advertising browser-use${browserProbe.reason ? ` (${browserProbe.reason})` : ""}`);
     }
     const config = {
         ...configuredConfig,

package/dist/exit-conditions.cjs

@@ -359,7 +359,10 @@ function mapExitCondition(result) {
     // including when that response says the task could not start. Treat an
     // explicit leading blocked verdict as a failed lease so the dispatcher can
     // retry/escalate it instead of falsely moving unfinished work to Done.
-    if (/^blocked(?:\s|:|$)/i.test(reportText.trim())) {
+    // Build agents also use an explicit outcome marker. A zero process exit
+    // means the conversation finished, not that the requested build succeeded.
+    if (/^blocked(?:\s|:|$)/i.test(reportText.trim()) ||
+        /^Build outcome:\s*(?:FAILED|BLOCKED)\b/i.test(reportText.trim())) {
         return {
             leaseOutcome: "failed",
             exitStatus: "failed",

package/dist/local-browser.cjs

@@ -0,0 +1,279 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.localBrowserShapes = void 0;
+exports.isLoopbackUrl = isLoopbackUrl;
+exports.createLocalBrowser = createLocalBrowser;
+exports.registerLocalBrowserTools = registerLocalBrowserTools;
+const node_net_1 = require("node:net");
+const playwright_1 = require("playwright");
+const zod_1 = require("zod");
+/**
+ * Interactive browser for services the agent starts on this machine.
+ *
+ * Codex's macOS seatbelt denies Chromium's Mach port registration
+ * (`bootstrap_check_in ... MachPortRendezvousServer: Permission denied`), so
+ * no browser can start inside a Codex session there, and `--single-process`
+ * crashes as soon as a second page opens. This Chromium runs in the
+ * supervisor instead, next to capture_visual_evidence, and is limited to
+ * loopback: the agent's own sandbox can already reach localhost, so these
+ * tools add a browser without adding network reach. Every request, WebSocket,
+ * and navigation to any other host is aborted and reported back.
+ */
+const MAX_ACTIONS = 300;
+const ACTION_TIMEOUT_MS = 10_000;
+const NAVIGATION_TIMEOUT_MS = 30_000;
+const MAX_SNAPSHOT_CHARS = 12_000;
+const MAX_LOG_LINES = 15;
+/** http(s)/ws(s) on localhost, *.localhost, 127.0.0.0/8, or ::1, without embedded credentials. */
+function isLoopbackUrl(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return false;
+    }
+    if (!["http:", "https:", "ws:", "wss:"].includes(url.protocol) || url.username || url.password)
+        return false;
+    const host = url.hostname.toLowerCase().replace(/^\[|\]$/g, "");
+    if (host === "localhost" || host.endsWith(".localhost"))
+        return true;
+    if ((0, node_net_1.isIP)(host) === 4)
+        return host.split(".")[0] === "127";
+    return host === "::1";
+}
+const loopbackUrl = zod_1.z.string().refine(isLoopbackUrl, "Only services on this machine are reachable: use http://localhost:<port> or http://127.0.0.1:<port>.");
+const selector = zod_1.z.string().min(1).max(500).describe("Playwright selector, e.g. `text=Sign in`, `role=button[name=\"Save\"]`, or CSS.");
+exports.localBrowserShapes = {
+    open: {
+        url: loopbackUrl,
+        viewport: zod_1.z.enum(["desktop", "mobile"]).default("desktop"),
+    },
+    click: { selector },
+    fill: { selector, value: zod_1.z.string().max(10_000) },
+    press: {
+        key: zod_1.z.string().min(1).max(50).describe("Key or chord, e.g. `Enter`, `Tab`, `Control+A`."),
+        selector: selector.optional(),
+    },
+    snapshot: {},
+    screenshot: { full_page: zod_1.z.boolean().default(false) },
+};
+function createLocalBrowser(options) {
+    let browser;
+    let context;
+    let page;
+    let viewport;
+    let actions = 0;
+    let closed = false;
+    let creatingPage = false;
+    let queue = Promise.resolve();
+    let notes = [];
+    const blocked = new Set();
+    const logs = [];
+    const log = (line) => {
+        logs.push(line.slice(0, 500));
+        if (logs.length > MAX_LOG_LINES)
+            logs.shift();
+    };
+    const block = (url) => {
+        try {
+            blocked.add(new URL(url).origin);
+        }
+        catch {
+            blocked.add(url.slice(0, 100));
+        }
+    };
+    function track(next) {
+        page = next;
+        next.on("console", (message) => {
+            if (["error", "warning"].includes(message.type()))
+                log(`console.${message.type()}: ${message.text()}`);
+        });
+        next.on("pageerror", (error) => log(`pageerror: ${error.message}`));
+    }
+    async function ensureContext(wanted) {
+        if (context && viewport === wanted)
+            return context;
+        await context?.close().catch(() => undefined);
+        context = undefined;
+        page = undefined;
+        try {
+            browser ??= await options.launch();
+        }
+        catch {
+            throw new Error("The local browser could not start. On the agent host run `navarch-runtime browser-install`.");
+        }
+        const created = await browser.newContext({
+            ...(wanted === "mobile" ? playwright_1.devices["iPhone 13"] : { viewport: { width: 1440, height: 900 } }),
+            acceptDownloads: false,
+            // Service workers would answer fetches before the route below sees them.
+            serviceWorkers: "block",
+        });
+        await created.route("**/*", (route) => {
+            const url = route.request().url();
+            if (isLoopbackUrl(url))
+                return route.continue();
+            block(url);
+            return route.abort("blockedbyclient");
+        });
+        await created.routeWebSocket(() => true, (socket) => {
+            if (isLoopbackUrl(socket.url()))
+                return socket.connectToServer();
+            block(socket.url());
+            return socket.close({ code: 1008, reason: "Only loopback services are reachable." });
+        });
+        created.on("page", (opened) => {
+            if (creatingPage || opened === page)
+                return;
+            track(opened);
+            notes.push("A new tab opened; it is now the active page.");
+        });
+        context = created;
+        viewport = wanted;
+        return created;
+    }
+    function currentPage() {
+        if (!page || page.isClosed())
+            throw new Error("No page is open. Call local_browser_open first.");
+        return page;
+    }
+    async function snapshot(heading) {
+        const active = currentPage();
+        let tree;
+        try {
+            tree = await active.locator("body").ariaSnapshot({ timeout: 5_000 });
+        }
+        catch (error) {
+            tree = `(accessibility snapshot unavailable: ${String(error).split("\n")[0]})`;
+        }
+        if (tree.length > MAX_SNAPSHOT_CHARS)
+            tree = `${tree.slice(0, MAX_SNAPSHOT_CHARS)}\n… (truncated)`;
+        const lines = [
+            ...(heading ? [heading] : []),
+            ...notes,
+            ...(active.url().startsWith("chrome-error://")
+                ? ["The last navigation failed or tried to leave this machine and was blocked. Use local_browser_open to continue."]
+                : []),
+            `URL: ${active.url()}`,
+            `Title: ${await active.title().catch(() => "")}`,
+            `Viewport: ${viewport}`,
+            ...(logs.length ? ["Recent console/page errors:", ...logs.map((line) => `  ${line}`)] : []),
+            ...(blocked.size
+                ? [`Blocked non-loopback requests (this browser reaches only this machine): ${[...blocked].slice(-10).join(", ")}`]
+                : []),
+            "",
+            tree,
+        ];
+        notes = [];
+        return [{ type: "text", text: lines.join("\n") }];
+    }
+    /** Runs tool calls one at a time; a lease ending stops further use. */
+    function run(action) {
+        const next = queue.then(async () => {
+            if (closed || !options.isActive())
+                throw new Error("The local browser lease is no longer active.");
+            if (++actions > MAX_ACTIONS)
+                throw new Error(`This lease reached its ${MAX_ACTIONS} local browser actions.`);
+            return action();
+        });
+        queue = next.catch(() => undefined);
+        return next;
+    }
+    async function settle(active) {
+        await active.waitForLoadState("load", { timeout: 5_000 }).catch(() => undefined);
+    }
+    return {
+        open(args) {
+            return run(async () => {
+                if (!isLoopbackUrl(args.url))
+                    throw new Error("Only loopback URLs are reachable.");
+                const created = await ensureContext(args.viewport ?? "desktop");
+                if (!page || page.isClosed()) {
+                    creatingPage = true;
+                    try {
+                        track(await created.newPage());
+                    }
+                    finally {
+                        creatingPage = false;
+                    }
+                }
+                const response = await currentPage().goto(args.url, { waitUntil: "load", timeout: NAVIGATION_TIMEOUT_MS });
+                return snapshot(`HTTP ${response?.status() ?? "(no response)"}`);
+            });
+        },
+        click(args) {
+            return run(async () => {
+                const active = currentPage();
+                await active.locator(args.selector).first().click({ timeout: ACTION_TIMEOUT_MS });
+                await settle(active);
+                return snapshot();
+            });
+        },
+        fill(args) {
+            return run(async () => {
+                await currentPage().locator(args.selector).first().fill(args.value, { timeout: ACTION_TIMEOUT_MS });
+                return snapshot();
+            });
+        },
+        press(args) {
+            return run(async () => {
+                const active = currentPage();
+                if (args.selector)
+                    await active.locator(args.selector).first().press(args.key, { timeout: ACTION_TIMEOUT_MS });
+                else
+                    await active.keyboard.press(args.key);
+                await settle(active);
+                return snapshot();
+            });
+        },
+        snapshot() {
+            return run(() => snapshot());
+        },
+        screenshot(args) {
+            return run(async () => {
+                const bytes = await currentPage().screenshot({ type: "png", fullPage: args.full_page ?? false, timeout: ACTION_TIMEOUT_MS });
+                return [
+                    { type: "text", text: `Screenshot of ${currentPage().url()} (${viewport}). Not uploaded; use capture_visual_evidence for PR evidence.` },
+                    { type: "image", data: bytes.toString("base64"), mimeType: "image/png" },
+                ];
+            });
+        },
+        async close() {
+            closed = true;
+            await queue.catch(() => undefined);
+            await context?.close().catch(() => undefined);
+            await browser?.close().catch(() => undefined);
+            browser = undefined;
+            context = undefined;
+            page = undefined;
+        },
+    };
+}
+const toolResult = (call) => call().then((content) => ({ content }), (error) => ({ isError: true, content: [{ type: "text", text: String(error) }] }));
+/** Registers the local_browser_* tools on a lease's navarch-browser MCP server. */
+function registerLocalBrowserTools(server, browser) {
+    server.registerTool("local_browser_open", {
+        description: "Open a page served on this machine (http://localhost:<port> or 127.0.0.1) in Navarch's browser, which runs outside the coding-agent sandbox. Start your dev server first. Reuses one tab; switching viewport starts a fresh session. Returns the page's accessibility snapshot, console errors, and any blocked non-loopback requests.",
+        inputSchema: exports.localBrowserShapes.open,
+    }, (args) => toolResult(() => browser.open(args)));
+    server.registerTool("local_browser_click", {
+        description: "Click the first element matching a Playwright selector on the open local page, then return the updated snapshot.",
+        inputSchema: exports.localBrowserShapes.click,
+    }, (args) => toolResult(() => browser.click(args)));
+    server.registerTool("local_browser_fill", {
+        description: "Replace the value of an input, textarea, or contenteditable on the open local page, then return the snapshot.",
+        inputSchema: exports.localBrowserShapes.fill,
+    }, (args) => toolResult(() => browser.fill(args)));
+    server.registerTool("local_browser_press", {
+        description: "Press a key (optionally focused on a selector) on the open local page, then return the snapshot.",
+        inputSchema: exports.localBrowserShapes.press,
+    }, (args) => toolResult(() => browser.press(args)));
+    server.registerTool("local_browser_snapshot", {
+        description: "Return the open local page's URL, title, accessibility snapshot, console errors, and blocked requests.",
+        inputSchema: exports.localBrowserShapes.snapshot,
+    }, () => toolResult(() => browser.snapshot()));
+    server.registerTool("local_browser_screenshot", {
+        description: "Return a PNG of the open local page for inspection. Not uploaded as evidence.",
+        inputSchema: exports.localBrowserShapes.screenshot,
+    }, (args) => toolResult(() => browser.screenshot(args)));
+}

package/dist/session.cjs

@@ -232,13 +232,14 @@ async function runClaimedSession(deps, claimed, sessionId, lifecycle) {
     let retainWorktree = false;
     let heartbeatInFlight = null;
     let heartbeatWorkspaceUpdate = null;
+    let completingLease = false;
     const sessionOutcome = {};
-    const checkpointForRecovery = async (result) => {
+    const checkpointForRecovery = async (result, reason) => {
         if (result.checkpointPath || result.retainedWorktreePath)
             return;
         try {
             result.checkpointPath = await gitWorktree.saveCheckpoint();
-            log.warn(`session ${leaseId} stopped for ${leaseLost ? "lease loss" : result.capacityError ? "provider capacity" : result.timeoutReason ?? "duration"}; recovery checkpoint: ${result.checkpointPath}`);
+            log.warn(`session ${leaseId} stopped for ${reason ?? (leaseLost ? "lease loss" : result.capacityError ? "provider capacity" : result.timeoutReason ?? "duration")}; recovery checkpoint: ${result.checkpointPath}`);
         }
         catch (error) {
             retainWorktree = true;
@@ -285,7 +286,15 @@ async function runClaimedSession(deps, claimed, sessionId, lifecycle) {
                 log.warn(`lease heartbeat failed for ${leaseId}: ${String(err)} — retrying on the next heartbeat while the confirmed lease remains valid.`);
                 return;
             }
-            log.warn(`lease heartbeat failed for ${leaseId}: ${String(err)} — killing session.`);
+            if (completingLease && isTerminalLeaseHeartbeatError(err)) {
+                // Completion can release the lease before its HTTP response arrives.
+                // Keep awaiting/re-sending that report to resolve the ambiguous write;
+                // there is no agent turn to kill during this phase.
+                log.info(`lease ${leaseId} is no longer active while completion is pending; awaiting completion acknowledgement.`);
+            }
+            else {
+                log.warn(`lease heartbeat failed for ${leaseId}: ${String(err)} — killing session.`);
+            }
             leaseLost = true;
             leaseGone = isTerminalLeaseHeartbeatError(err);
             heartbeatGuard.stop();
@@ -385,14 +394,6 @@ async function runClaimedSession(deps, claimed, sessionId, lifecycle) {
                 await node_fs_1.promises.mkdir(tmpDir, { recursive: true, mode: 0o700 });
                 Object.assign(sessionEnv, { TMPDIR: tmpDir, TMP: tmpDir, TEMP: tmpDir });
             }
-            codexGuardArgs = (0, worktree_guard_cjs_1.codexWorktreeGuardArgs)({
-                workDir,
-                worktreePath: gitWorktree.worktreePath,
-                repositoryPath: gitWorktree.repositoryPath,
-                workspaceRoot: config.workspaceRoot,
-                extraRoots: config.guardExtraRoots,
-                codexBin: config.codexBin,
-            });
         }
         else if (runtime === "gemini") {
             geminiGuardMounts = (0, worktree_guard_cjs_1.geminiSandboxMounts)({
@@ -459,12 +460,22 @@ async function runClaimedSession(deps, claimed, sessionId, lifecycle) {
             const mcp = JSON.parse(await node_fs_1.promises.readFile(mcpConfigPath, "utf8"));
             mcp.mcpServers.navarch_browser = browserEvidence.config;
             await node_fs_1.promises.writeFile(mcpConfigPath, JSON.stringify(mcp), { mode: 0o600 });
-            promptText += "\n\nNavarch supplies capture_visual_evidence through navarch_browser. Use it first for desktop/mobile screenshots of the verified preview URL and source commit. It runs outside the coding-agent sandbox, uploads images as task artifacts, and the runtime attaches them to the delivery PR before completion. Inspect the returned images before accepting the UI. Do not use GitHub's upload UI or add capture tools to the target repository. If the base commit has no runnable UI, report before evidence as not applicable with the base SHA and reason; still capture the current head. Authentication or interactive walkthroughs may require the existing browser tools.\n";
+            promptText += "\n\nNavarch supplies capture_visual_evidence through navarch_browser. Use it first for desktop/mobile screenshots of the verified preview URL and source commit. It runs outside the coding-agent sandbox, uploads images as task artifacts, and the runtime attaches them to the delivery PR before completion. Inspect the returned images before accepting the UI. Do not use GitHub's upload UI or add capture tools to the target repository. If the base commit has no runnable UI, report before evidence as not applicable with the base SHA and reason; still capture the current head. For interactive walkthroughs of a service you start on this machine, use navarch_browser's local_browser_open, local_browser_click, local_browser_fill, local_browser_press, local_browser_snapshot, and local_browser_screenshot with http://localhost:<port> or http://127.0.0.1:<port>. That browser also runs outside the sandbox and reaches only this machine's loopback services; prefer it over launching Chromium yourself, which Codex's macOS sandbox kills at startup.\n";
         }
         if (gitWorktree.hostedCheckpointRestoreFailure) {
             log.warn(`hosted checkpoint for ${leaseId} could not be restored: ` +
                 `${(0, redact_cjs_1.redactText)(gitWorktree.hostedCheckpointRestoreFailure, registry.list())}; starting without it.`);
         }
+        if (config.sandboxMode === "host" && config.worktreeGuard && runtime === "codex") {
+            codexGuardArgs = (0, worktree_guard_cjs_1.codexWorktreeGuardArgs)({
+                workDir,
+                worktreePath: gitWorktree.worktreePath,
+                repositoryPath: gitWorktree.repositoryPath,
+                workspaceRoot: config.workspaceRoot,
+                extraRoots: config.guardExtraRoots,
+                codexBin: config.codexBin,
+            });
+        }
         const restoredCheckpoint = gitWorktree.restoredHostedCheckpoint;
         if (restoredCheckpoint) {
             log.info(`resumed hosted checkpoint ${restoredCheckpoint.sha.slice(0, 12)} for ${leaseId} ` +
@@ -701,11 +712,14 @@ async function runClaimedSession(deps, claimed, sessionId, lifecycle) {
                         });
                         continue;
                     }
+                    await checkpointForRecovery(result, "incomplete delivery");
                     deliveryFailureSummary =
                         `Session ended without delivering the task: ${delivery.reason}. ` +
                             `${deliveryCorrectionRetries} correction turn(s) did not recover it. ` +
-                            "The session worktree is deleted at teardown. Pushed commits remain on origin; " +
-                            "uncommitted or unpushed work may be lost. The task needs another attempt.";
+                            (result.checkpointPath
+                                ? `Local recovery checkpoint: ${result.checkpointPath}. `
+                                : `Recovery worktree retained: ${result.retainedWorktreePath}. `) +
+                            "The task needs another attempt.";
                     log.warn(`failing ${leaseId}: ${deliveryFailureSummary}`);
                     mapping.leaseOutcome = "failed";
                     mapping.exitStatus = "failed";
@@ -757,6 +771,7 @@ async function runClaimedSession(deps, claimed, sessionId, lifecycle) {
                 transcript_url: completion.transcript_url,
             };
             try {
+                completingLease = true;
                 await (0, completion_retry_cjs_1.completeWithTransientRetry)(() => api.completeLease(leaseId, completion), {
                     onRetry: (attempt, delayMs, err) => log.warn(`completion for ${leaseId} did not reach the control plane (${(0, redact_cjs_1.redactText)(String(err), knownSecrets)}); re-sending in ${delayMs / 1000}s (${attempt}).`),
                 });
@@ -778,10 +793,11 @@ async function runClaimedSession(deps, claimed, sessionId, lifecycle) {
                 if (!rejection)
                     throw err;
                 const redactedRejection = (0, redact_cjs_1.redactText)(rejection.message, knownSecrets);
+                const rejectionDetail = describeResponseBody(`${(0, redact_cjs_1.redactText)(rejection.code, knownSecrets)}: ${redactedRejection}`);
                 const remediable = mapping.leaseOutcome === "completed" && rejection.remediable;
                 if (remediable && completionRemediationRetries < COMPLETION_REMEDIATION_RETRIES) {
                     completionRemediationRetries += 1;
-                    log.warn(`completion for ${leaseId} needs more work; restarting agent turn ${completionRemediationRetries}/${COMPLETION_REMEDIATION_RETRIES} in the same worktree.`);
+                    log.warn(`completion for ${leaseId} needs more work (${rejectionDetail}); restarting agent turn ${completionRemediationRetries}/${COMPLETION_REMEDIATION_RETRIES} in the same worktree.`);
                     // A new turn is a fresh agent invocation: the rejection alone would
                     // reach an agent that has never seen the task.
                     nextPrompt = (0, prompt_cjs_1.renderCompletionRemediationPrompt)({
@@ -794,22 +810,24 @@ async function runClaimedSession(deps, claimed, sessionId, lifecycle) {
                     continue;
                 }
                 if (remediable) {
-                    log.warn(`completion for ${leaseId} is still not ready after ${COMPLETION_REMEDIATION_RETRIES} retries; failing with the control-plane rejection.`);
+                    log.warn(`completion for ${leaseId} is still not ready after ${COMPLETION_REMEDIATION_RETRIES} retries (${rejectionDetail}); failing with the control-plane rejection.`);
                 }
                 else {
                     // Not something another turn can fix (e.g. review_evidence_tampered).
                     // Fail the lease once, keeping this attempt's real report, cost and
                     // evidence — this is a rejected attempt, not a crashed session.
-                    log.error(`completion for ${leaseId} was rejected as ${rejection.code}, which is not remediable; failing the lease.`);
+                    log.error(`completion for ${leaseId} was rejected (${rejectionDetail}), which is not remediable; failing the lease.`);
                 }
                 try {
                     await (0, completion_retry_cjs_1.completeWithTransientRetry)(() => api.completeLease(leaseId, {
                         ...completion,
                         status: "failed",
-                        report: remediable
-                            ? redactedRejection
-                            : `${redactedRejection}\n\n---\n\n${completion.report}`,
-                        failure_summary: redactedRejection,
+                        report: `${redactedRejection}\n\n---\n\n${completion.report}`,
+                        // Keep the agent's blocker first: the API bounds failure_summary,
+                        // and retry attribution must not lose it behind a delivery error.
+                        failure_summary: remediable
+                            ? `${completion.report.slice(0, 1000)}\n\nControl-plane rejection:\n${redactedRejection.slice(0, 800)}`
+                            : redactedRejection,
                         exit_status: "failed",
                     }));
                 }
@@ -824,6 +842,9 @@ async function runClaimedSession(deps, claimed, sessionId, lifecycle) {
                 }
                 break;
             }
+            finally {
+                completingLease = false;
+            }
         }
     }
     catch (err) {

package/dist/worktree-guard.cjs

@@ -291,6 +291,13 @@ function codexWorktreeGuardArgs(options, platform = process.platform) {
         [node_path_1.default.resolve(options.repositoryPath)]: "write",
         [sessionGhConfigDir(options.workDir)]: "read",
     };
+    // Codex protects a linked worktree's gitdir with a more specific read-only
+    // rule. A write grant on the bare repository alone does not override it:
+    // fetch/checkout/commit fail on FETCH_HEAD, HEAD.lock, or index.lock. Grant
+    // the runtime-created gitdir explicitly, without reopening session metadata.
+    const gitdir = linkedWorktreeGitDir(options.worktreePath, options.repositoryPath);
+    if (gitdir)
+        filesystem[gitdir] = "write";
     const overlapsWorkspace = (root) => isPathInside(root, workspaceRoot) || (linux && isPathInside(workspaceRoot, root));
     const readRoots = [
         ...codexToolReadRoots(process.env, platform),
@@ -333,6 +340,36 @@ function codexWorktreeGuardArgs(options, platform = process.platform) {
         `permissions.${CODEX_GUARD_PROFILE}.network.domains=${tomlInlineTable(CODEX_GITHUB_NETWORK_DOMAINS)}`,
     ];
 }
+function linkedWorktreeGitDir(worktreePath, repositoryPath) {
+    let dotGit;
+    try {
+        dotGit = (0, node_fs_1.readFileSync)(node_path_1.default.join(worktreePath, ".git"), "utf8");
+    }
+    catch (error) {
+        // A regular checkout has a .git directory; tests may use virtual paths.
+        const code = error.code;
+        if (code === "ENOENT" || code === "EISDIR")
+            return undefined;
+        throw error;
+    }
+    const match = /^gitdir: (.+)\s*$/m.exec(dotGit);
+    if (!match)
+        return undefined;
+    const canonical = (root) => {
+        try {
+            return (0, node_fs_1.realpathSync)(root);
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return node_path_1.default.resolve(root);
+            throw error;
+        }
+    };
+    const gitdir = canonical(node_path_1.default.resolve(worktreePath, match[1].trim()));
+    const repository = canonical(repositoryPath);
+    // Never turn a pointer outside the runtime's repository into a new grant.
+    return gitdir !== repository && isPathInside(gitdir, repository) ? gitdir : undefined;
+}
 /**
  * Mounts only the current session roots into Gemini CLI's native sandbox.
  * Gemini mounts cwd itself; explicit same-path mounts keep the shared gitdir,

package/package.json

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