@sagentlab/navarch-runtime 0.1.133 → 0.1.135

package/README.md

@@ -71,6 +71,35 @@ 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.
 
+#### Project Playwright suites under Codex on macOS
+
+The same denial stops a project's own `playwright test` from launching
+Chromium inside a Codex session, and the sandbox cannot download the suite's
+browser either. On macOS, every Codex build, verify, and QA session therefore
+gets `navarch_browser.start_playwright_browser`, with or without `browser-use`.
+The tool:
+
+1. reads the Playwright version the checkout installed (from
+   `node_modules/playwright-core`, `playwright` or `@playwright/test`
+   `package.json`; nothing in the checkout is executed);
+2. installs that exact `playwright-core` with `npm install --ignore-scripts`,
+   plus its Chromium, into `<workspace>/playwright-server/<version>`, once per
+   machine;
+3. starts that version's browser server under `/usr/bin/sandbox-exec` with
+   Navarch's own profile (`playwrightServerProfile` in
+   `src/playwright-server.cts`), and returns `PW_TEST_CONNECT_WS_ENDPOINT`.
+
+The agent runs the repository's usual `playwright test` command with that
+variable set. The test code stays inside Codex's sandbox, and only the browser
+runs outside it. The browser's sandbox allows Chromium's
+`MachPortRendezvousServer` registration, reads of system paths and its own
+install, writes to a per-lease directory, and connections to loopback only.
+So `file://` reads of the user's files, other hosts, and the server-side
+`request` API to other hosts all fail, even through CDP. DNS lookups are not
+blocked. The endpoint path is a per-lease secret, and the server stops with
+the lease. Playwright's connect mode ignores config launch options (headed,
+channel, `executablePath`, launch args) and serves Chromium projects only.
+
 Call the tool with `url`, `source_commit_sha`, and `evidence_role` (`before` or
 `after`). Optional `wait_for_selector` and `settle_ms` let a scene finish loading.
 The URL's deployed SHA must be checked by the agent: the supplied SHA is metadata,

package/dist/adapters/acp.cjs

@@ -1,9 +1,14 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.acpAdapter = void 0;
 exports.runAcpAdapter = runAcpAdapter;
+exports.probeAcpSteering = probeAcpSteering;
 const node_child_process_1 = require("node:child_process");
 const node_fs_1 = require("node:fs");
+const node_os_1 = __importDefault(require("node:os"));
 const node_stream_1 = require("node:stream");
 const kill_agent_cjs_1 = require("../kill-agent.cjs");
 const types_cjs_1 = require("./types.cjs");
@@ -16,6 +21,21 @@ const types_cjs_1 = require("./types.cjs");
  * gets no chance to release what it is holding.
  */
 const CANCEL_GRACE_MS = 2_000;
+/** How long the steering probe waits for the agent to answer `initialize`. */
+const PROBE_TIMEOUT_MS = 10_000;
+/**
+ * What an ACP agent that answered the probe's `initialize` with protocol v1
+ * can do: `session/cancel` and a further `session/prompt` on the same session
+ * are core v1 methods, so an interrupt stops the running prompt and starts the
+ * next one on the held connection. ACP has no input into a running prompt, so
+ * steer stays `none`, and a queued message still waits for the session loop's
+ * turn boundary.
+ */
+const ACP_NATIVE_STEERING = Object.freeze({
+    steer: "none",
+    queue: "boundary",
+    interrupt: "native",
+});
 /**
  * Generic Agent Client Protocol v1 adapter. DeepSeek Harness is the default
  * implementation (`dsh --profile acp`), while NAVARCH_ACP_BIN and
@@ -36,19 +56,33 @@ async function runAcpAdapter(options) {
     const rawStdout = [];
     const stderr = [];
     const protocolInput = new node_stream_1.PassThrough();
-    const messages = [];
+    // Agent messages of the current prompt only: after an interrupt, the report
+    // is what the last prompt produced, not the text of the turn it cut short.
+    let messages = [];
     const thoughts = [];
     let costUsd;
     let timedOut = false;
     let killedByLeaseLoss = false;
     let sessionId;
     let stopReason;
-    // Resolved once the in-flight prompt request settles, however it settles, so
+    // Settles once the in-flight prompt request settles, however it settles, so
     // cancellation can wait for the agent instead of racing the kill.
-    let settlePrompt = () => undefined;
-    const promptSettled = new Promise((resolve) => {
-        settlePrompt = resolve;
-    });
+    let promptSettled = Promise.resolve();
+    // Native interrupt (docs/navarch/live-steering.md section 5.3, row `acp`).
+    const live = options.liveInput;
+    let attached = false;
+    let promptRunning = false;
+    // This adapter sent `session/cancel` to stop the running prompt for an interrupt.
+    let interruptCancelSent = false;
+    // Interrupt inputs that wait for the running prompt to return, in the order they were sent.
+    const held = [];
+    const detach = () => {
+        if (!attached)
+            return;
+        attached = false;
+        held.length = 0;
+        live?.attach(null);
+    };
     child.stdout.on("data", (chunk) => {
         options.onActivity?.();
         rawStdout.push(chunk);
@@ -86,6 +120,9 @@ async function runAcpAdapter(options) {
     const controller = new AbortController();
     let abortProtocol = Promise.resolve();
     controller.signal.addEventListener("abort", () => {
+        // A timeout, lease loss or task cancel ends the session: no interrupt may
+        // start another prompt, and the session takes back what was not sent.
+        detach();
         abortProtocol = (async () => {
             if (sessionId) {
                 await connection.agent.notify(acp.methods.agent.session.cancel, { sessionId }).catch(() => undefined);
@@ -110,7 +147,7 @@ async function runAcpAdapter(options) {
         onAbort();
     try {
         const context = connection.agent;
-        await context.request(acp.methods.agent.initialize, {
+        const initialized = await context.request(acp.methods.agent.initialize, {
             protocolVersion: acp.PROTOCOL_VERSION,
             clientCapabilities: {},
         });
@@ -122,17 +159,68 @@ async function runAcpAdapter(options) {
         let configOptions = created.configOptions ?? [];
         configOptions = await setConfigOption(context, acp.methods.agent.session.setConfigOption, sessionId, configOptions, "model", options.model === "default" ? undefined : options.model);
         await setConfigOption(context, acp.methods.agent.session.setConfigOption, sessionId, configOptions, "reasoning_effort", options.reasoningEffort);
-        let response;
-        try {
-            response = await context.request(acp.methods.agent.session.prompt, {
-                sessionId,
-                prompt: [{ type: "text", text: options.prompt }],
+        // The probe saw protocol v1; an agent that now answers another version
+        // takes no interrupt, which then waits for the turn boundary.
+        if (live && initialized.protocolVersion === acp.PROTOCOL_VERSION && !controller.signal.aborted) {
+            const activeSessionId = sessionId;
+            attached = true;
+            live.attach({
+                // ACP has no input into a running prompt.
+                send: () => false,
+                interrupt: (input) => {
+                    if (!attached)
+                        return false;
+                    held.push(input);
+                    if (promptRunning && !interruptCancelSent) {
+                        interruptCancelSent = true;
+                        void connection.agent.notify(acp.methods.agent.session.cancel, { sessionId: activeSessionId })
+                            .catch(() => undefined);
+                    }
+                    return true;
+                },
             });
         }
-        finally {
-            settlePrompt();
+        let prompt = [{ type: "text", text: options.prompt }];
+        // The interrupt inputs `prompt` carries, and whether the first one stopped a prompt.
+        let carried = null;
+        for (;;) {
+            messages = [];
+            promptRunning = true;
+            interruptCancelSent = false;
+            const request = context.request(acp.methods.agent.session.prompt, { sessionId, prompt });
+            promptSettled = request.then(() => undefined, () => undefined);
+            // An interrupt that was waiting when the channel attached (steering hands
+            // it over at once) arrived before the first prompt ran: stop that prompt.
+            if (held.length > 0 && !interruptCancelSent) {
+                interruptCancelSent = true;
+                void context.notify(acp.methods.agent.session.cancel, { sessionId }).catch(() => undefined);
+            }
+            if (carried) {
+                // The agent reads it as the next prompt on the same session. ACP has no
+                // read receipt, and the ack cannot wait for the whole prompt, so the
+                // message counts as taken once its prompt is sent. The first input owns
+                // the stop; the rest were sent while it was pending.
+                carried.inputs.forEach((input, index) => live?.consumed(input.id, true, index === 0 && carried.stoppedTurn));
+                carried = null;
+            }
+            let response;
+            try {
+                response = await request;
+            }
+            finally {
+                promptRunning = false;
+            }
+            stopReason = response.stopReason;
+            // A `cancelled` prompt that an interrupt asked for is not the end of the
+            // session: the interrupt's prompt follows. One that a timeout, lease loss
+            // or task cancel asked for is.
+            if (controller.signal.aborted || held.length === 0)
+                break;
+            const inputs = held.splice(0);
+            carried = { inputs, stoppedTurn: interruptCancelSent && stopReason === "cancelled" };
+            prompt = inputs.map((input) => ({ type: "text", text: input.text }));
         }
-        stopReason = response.stopReason;
+        detach();
         await Promise.race([
             context.request(acp.methods.agent.session.close, { sessionId }).catch(() => undefined),
             new Promise((resolve) => setTimeout(resolve, options.timeoutMs > 0 ? Math.min(5_000, options.timeoutMs) : 5_000)),
@@ -143,6 +231,7 @@ async function runAcpAdapter(options) {
             stderr.push(`\n${describeError(error)}`);
     }
     finally {
+        detach();
         clearTimeout(timer);
         options.signal?.removeEventListener("abort", onAbort);
         await abortProtocol;
@@ -274,8 +363,87 @@ async function terminateChild(child, options, forceContainerKill) {
 function describeError(error) {
     return error instanceof Error ? `${error.name}: ${error.message}` : String(error);
 }
+/**
+ * Probe results by command line. A pass is kept for the life of the runtime. A
+ * failure is kept for a while only, because the agent may be installed or fixed
+ * later, and probing it again for every claim would delay each session by up
+ * to the probe timeout.
+ */
+const acpProbeCache = new Map();
+const PROBE_FAILURE_TTL_MS = 10 * 60_000;
+/**
+ * Native interrupt needs an agent that speaks ACP v1, where `session/cancel`
+ * and a further `session/prompt` on the same session are core methods. The
+ * probe starts the agent, sends `initialize`, and stops it. Only the host is
+ * probed: the probe has no sandbox container to reach the Docker agent, so
+ * Docker keeps `interrupt: restart`, as does an agent that fails to start,
+ * answers late, or reports another protocol version.
+ */
+async function probeAcpSteering(context) {
+    if (context.sandboxMode !== "host")
+        return null;
+    const key = JSON.stringify([context.bin, ...context.extraArgs]);
+    let probe = acpProbeCache.get(key);
+    if (!probe) {
+        probe = speaksAcpV1(context).catch(() => false);
+        acpProbeCache.set(key, probe);
+        const cached = probe;
+        void cached.then((passed) => {
+            if (passed)
+                return;
+            setTimeout(() => {
+                if (acpProbeCache.get(key) === cached)
+                    acpProbeCache.delete(key);
+            }, PROBE_FAILURE_TTL_MS).unref();
+        });
+    }
+    return (await probe) ? ACP_NATIVE_STEERING : null;
+}
+async function speaksAcpV1(context) {
+    const acp = await import("@agentclientprotocol/sdk");
+    const child = (0, node_child_process_1.spawn)(context.bin, context.extraArgs, {
+        detached: process.platform !== "win32",
+        // No session exists yet, so an agent that writes state at startup writes it
+        // in the temporary directory, not in the runtime's working directory.
+        cwd: node_os_1.default.tmpdir(),
+        env: { ...process.env, ...context.env },
+        stdio: ["pipe", "pipe", "ignore"],
+    });
+    const exited = new Promise((resolve) => {
+        child.once("error", () => resolve());
+        child.once("close", () => resolve());
+    });
+    child.stdin.on("error", () => undefined);
+    const connection = acp.client({ name: "navarch-runtime" }).connect(acp.ndJsonStream(node_stream_1.Writable.toWeb(child.stdin), node_stream_1.Readable.toWeb(child.stdout)));
+    let timer;
+    try {
+        return await Promise.race([
+            connection.agent.request(acp.methods.agent.initialize, {
+                protocolVersion: acp.PROTOCOL_VERSION,
+                clientCapabilities: {},
+            }).then((response) => response.protocolVersion === acp.PROTOCOL_VERSION, () => false),
+            exited.then(() => false),
+            new Promise((resolve) => {
+                timer = setTimeout(() => resolve(false), PROBE_TIMEOUT_MS);
+            }),
+        ]);
+    }
+    finally {
+        clearTimeout(timer);
+        connection.close();
+        if (child.exitCode === null && child.signalCode === null) {
+            (0, kill_agent_cjs_1.killAgent)(child, "SIGTERM");
+            await Promise.race([exited, new Promise((resolve) => setTimeout(resolve, 1_000))]);
+            if (child.exitCode === null && child.signalCode === null)
+                (0, kill_agent_cjs_1.killAgent)(child);
+        }
+    }
+}
 exports.acpAdapter = {
     agentType: "acp",
     run: runAcpAdapter,
+    // The claim's baseline record. The probe upgrades it to ACP_NATIVE_STEERING
+    // on a host whose agent speaks ACP v1.
     steering: types_cjs_1.TURN_RESTART_STEERING,
+    probeSteering: probeAcpSteering,
 };

package/dist/adapters/codex.cjs

@@ -200,6 +200,10 @@ async function codexMcpArgs(path, env) {
             continue;
         args.push("-c", `mcp_servers.${key}.url=${tomlString(server.url)}`);
         args.push("-c", `mcp_servers.${key}.required=${isPlatformServer(name)}`);
+        // start_playwright_browser installs a Playwright version and its Chromium
+        // on first use, which can outlast Codex's 60 s default.
+        if (name === "navarch_browser")
+            args.push("-c", `mcp_servers.${key}.tool_timeout_sec=600`);
         const envHeaders = {};
         let headerIndex = 0;
         for (const [header, value] of Object.entries(server.headers ?? {})) {

package/dist/browser-evidence.cjs

@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.captureSchema = void 0;
+exports.navarchBrowserTools = navarchBrowserTools;
 exports.installEvidenceBrowser = installEvidenceBrowser;
 exports.launchCaptureBrowser = launchCaptureBrowser;
 exports.startBrowserEvidence = startBrowserEvidence;
@@ -14,9 +15,27 @@ const streamableHttp_js_1 = require("@modelcontextprotocol/sdk/server/streamable
 const playwright_1 = require("playwright");
 const zod_1 = require("zod");
 const local_browser_cjs_1 = require("./local-browser.cjs");
+const playwright_server_cjs_1 = require("./playwright-server.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"));
+const BROWSER_USE_RUNTIMES = ["codex", "claude-code", "antigravity", "opencode", "acp", "muse"];
+/**
+ * Which navarch_browser tools a host session gets. `browserUse` adds capture
+ * and local_browser_* for browser-use tasks. `playwrightSuites` adds
+ * start_playwright_browser to every macOS Codex build/verify/qa session,
+ * because Codex's seatbelt cannot launch the project's own Playwright suite's
+ * Chromium whether or not the task asked for browser-use.
+ */
+function navarchBrowserTools(input) {
+    if (input.mcpConfigPath || input.sandboxMode !== "host" || !["build", "verify", "qa"].includes(input.taskType)) {
+        return { browserUse: false, playwrightSuites: false };
+    }
+    return {
+        browserUse: input.requiredCapabilities?.includes("browser-use") === true && BROWSER_USE_RUNTIMES.includes(input.runtime),
+        playwrightSuites: input.runtime === "codex" && input.platform === "darwin",
+    };
+}
 async function installEvidenceBrowser() {
     const cli = node_path_1.default.join(node_path_1.default.dirname(require.resolve("playwright/package.json")), "cli.js");
     await (0, node_util_1.promisify)(node_child_process_1.execFile)(process.execPath, [cli, "install", "chromium"], {
@@ -48,7 +67,8 @@ 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.
  * The lease gets the narrow capture operation plus the loopback-only
- * local_browser_* tools (local-browser.cts). */
+ * local_browser_* tools (local-browser.cts), and on macOS Codex hosts the
+ * project's own Playwright browser server (playwright-server.cts). */
 async function startBrowserEvidence(options) {
     const token = (0, node_crypto_1.randomBytes)(32).toString("hex");
     const fetchImpl = options.fetchImpl ?? fetch;
@@ -211,6 +231,8 @@ async function startBrowserEvidence(options) {
             }
         });
         (0, local_browser_cjs_1.registerLocalBrowserTools)(server, localBrowser);
+        if (options.playwrightServer)
+            (0, playwright_server_cjs_1.registerPlaywrightServerTool)(server, options.playwrightServer);
         res.on("close", () => { void transport.close(); void server.close(); });
         try {
             await server.connect(transport);
@@ -261,6 +283,7 @@ async function startBrowserEvidence(options) {
             http.closeAllConnections();
             await browser?.close().catch(() => undefined);
             await localBrowser.close();
+            await options.playwrightServer?.close();
             await activeCapture?.catch(() => undefined);
             await stopped;
         },

package/dist/browser-probe.cjs

@@ -81,7 +81,8 @@ async function probeBrowserCapability(config, deps = {}) {
             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."),
+                    "Codex sessions browse local services through Navarch's local_browser tools and run Playwright suites " +
+                    "against start_playwright_browser, both outside it."),
                 checked_at: now().toISOString(),
             };
         }

package/dist/playwright-server.cjs

@@ -0,0 +1,388 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.playwrightServerShape = exports.PLAYWRIGHT_SERVER_DIRNAME = void 0;
+exports.playwrightServerProfile = playwrightServerProfile;
+exports.projectPlaywrightVersion = projectPlaywrightVersion;
+exports.createPlaywrightServer = createPlaywrightServer;
+exports.registerPlaywrightServerTool = registerPlaywrightServerTool;
+const node_child_process_1 = require("node:child_process");
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const zod_1 = require("zod");
+const dependency_cache_cjs_1 = require("./dependency-cache.cjs");
+const kill_agent_cjs_1 = require("./kill-agent.cjs");
+const logger_cjs_1 = require("./logger.cjs");
+const sandbox_cjs_1 = require("./sandbox.cjs");
+const log = (0, logger_cjs_1.createLogger)("playwright-server");
+/**
+ * Chromium for the project's own Playwright suite, outside Codex's seatbelt.
+ *
+ * Codex's macOS seatbelt denies Chromium's Mach port registration
+ * (`bootstrap_check_in ... MachPortRendezvousServer: Permission denied
+ * (1100)`) and has no setting that allows it, so a verify session could run
+ * every project check except `playwright test` and ended BLOCKED (ShiftSwap
+ * task da9bc52c, 2026-10-27). The agent cannot install the suite's browser
+ * either: the sandbox has no CDN egress.
+ *
+ * Only the browser moves. The supervisor installs the exact `playwright-core`
+ * version the checkout uses, plus its Chromium, into a runtime cache, and
+ * starts that version's browser server under Navarch's own seatbelt
+ * (`playwrightServerProfile`). The suite itself, test code included, still
+ * runs in the agent's shell inside Codex's sandbox and reaches the server
+ * through Playwright's `PW_TEST_CONNECT_WS_ENDPOINT`. A connected client can
+ * drive the browser (CDP included), so the browser's own sandbox is the
+ * boundary: it may register Chromium's rendezvous port, read system paths and
+ * its own install, write only a private directory, and connect only to
+ * loopback. `file://` reads of the user's files, other hosts, and the
+ * server-side `request` API to other hosts all fail there.
+ */
+exports.PLAYWRIGHT_SERVER_DIRNAME = "playwright-server";
+const READY_MARKER = "NAVARCH_PLAYWRIGHT_SERVER";
+const START_TIMEOUT_MS = 60_000;
+const NPM_TIMEOUT_MS = 5 * 60_000;
+const BROWSER_INSTALL_TIMEOUT_MS = 10 * 60_000;
+const MAX_PACKAGE_JSON_BYTES = 1024 * 1024;
+const COMPLETE_MARKER = ".navarch-complete";
+// Stable and pre-release versions such as 1.57.0-alpha-1760000000000.
+const VERSION_PATTERN = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z][0-9A-Za-z.-]{0,48})?$/;
+/**
+ * Runs inside the sandbox with the cached playwright-core. Exits when the
+ * supervisor's end of stdin closes, so a crashed runtime leaves no browser.
+ */
+const LAUNCHER_SCRIPT = `
+const { chromium } = require(process.argv[2]);
+chromium.launchServer({ host: "127.0.0.1", port: 0, wsPath: "/" + process.argv[3], headless: true }).then((server) => {
+  process.stdout.write(${JSON.stringify(READY_MARKER)} + " " + server.wsEndpoint() + "\\n");
+  const stop = () => server.close().finally(() => process.exit(0));
+  process.stdin.on("end", stop);
+  process.stdin.on("error", stop);
+  process.stdin.resume();
+  process.on("SIGTERM", stop);
+}, (error) => {
+  process.stderr.write(String((error && error.stack) || error));
+  process.exit(1);
+});
+`;
+/**
+ * Seatbelt for the browser server and its Chromium. Parameters are canonical
+ * paths: NODE_ROOT (the Node install), PLAYWRIGHT_CORE (the cached package),
+ * BROWSERS (Playwright's browser cache), PRIVATE (this lease's scratch dir).
+ * The user's home is readable only through those, and nothing else is
+ * writable. Chromium's own helper sandboxes nest inside this one.
+ */
+function playwrightServerProfile() {
+    return [
+        "(version 1)",
+        "(deny default)",
+        '(import "system.sb")',
+        "(allow process-fork)",
+        "(allow process-exec)",
+        "(allow signal (target same-sandbox))",
+        "(allow process-info* (target same-sandbox))",
+        "(allow sysctl-read)",
+        "(allow mach-lookup)",
+        // The one grant Codex's seatbelt lacks: the browser process registering
+        // <bundle id>.MachPortRendezvousServer.<pid> for its child processes.
+        '(allow mach-register (global-name-regex #"\\.MachPortRendezvousServer\\.[0-9]+$"))',
+        "(allow ipc-posix-shm*)",
+        "(allow iokit-open)",
+        "(allow file-read-metadata)",
+        "(allow file-read*",
+        '  (literal "/") (subpath "/System") (subpath "/usr") (subpath "/bin") (subpath "/sbin") (subpath "/opt")',
+        '  (subpath "/Library") (subpath "/private/etc") (subpath "/private/var/db") (subpath "/dev")',
+        '  (subpath (param "NODE_ROOT")) (subpath (param "PLAYWRIGHT_CORE")) (subpath (param "BROWSERS"))',
+        '  (subpath (param "PRIVATE")))',
+        '(allow file-write* (subpath (param "PRIVATE")) (literal "/dev/null"))',
+        '(allow network-bind (local ip "localhost:*"))',
+        '(allow network-inbound (local ip "localhost:*"))',
+        '(allow network-outbound (remote ip "localhost:*"))',
+        "",
+    ].join("\n");
+}
+/**
+ * The Playwright version a checkout's suite uses, from the installed
+ * package.json files under `directory` (relative to the worktree). Only the
+ * version string is read; nothing from the checkout is executed.
+ */
+async function projectPlaywrightVersion(worktreePath, directory = ".") {
+    const root = node_path_1.default.resolve(worktreePath);
+    const projectDir = node_path_1.default.resolve(root, directory);
+    if (projectDir !== root && !projectDir.startsWith(`${root}${node_path_1.default.sep}`)) {
+        throw new Error(`directory must stay inside the checkout: ${directory}`);
+    }
+    const shown = node_path_1.default.relative(root, projectDir) || ".";
+    for (const name of ["playwright-core", "playwright", "@playwright/test"]) {
+        const file = node_path_1.default.join(projectDir, "node_modules", name, "package.json");
+        let raw;
+        try {
+            const stat = await node_fs_1.promises.stat(file);
+            if (!stat.isFile() || stat.size > MAX_PACKAGE_JSON_BYTES)
+                continue;
+            raw = await node_fs_1.promises.readFile(file, "utf8");
+        }
+        catch {
+            continue;
+        }
+        let version;
+        try {
+            version = JSON.parse(raw).version;
+        }
+        catch {
+            continue;
+        }
+        if (typeof version === "string" && VERSION_PATTERN.test(version))
+            return version;
+        throw new Error(`${shown}/node_modules/${name}/package.json has no usable version.`);
+    }
+    throw new Error(`No Playwright install under ${shown}/node_modules. Use the directory whose prepared dependencies include ` +
+        "@playwright/test (pass it as `directory`).");
+}
+const installs = new Map();
+/** One sandboxed browser server per lease, started on first use. */
+function createPlaywrightServer(options) {
+    const runner = options.runner ?? sandbox_cjs_1.nodeCommandRunner;
+    const env = options.env ?? process.env;
+    const token = (0, node_crypto_1.randomBytes)(24).toString("hex");
+    let running;
+    let queue = Promise.resolve();
+    let closed = false;
+    const assertActive = () => {
+        if (closed || !options.isActive())
+            throw new Error("The Playwright browser server's lease is no longer active.");
+    };
+    async function stop() {
+        const child = running?.child;
+        running = undefined;
+        if (!child || child.exitCode !== null || child.signalCode !== null)
+            return;
+        const exited = new Promise((resolve) => child.once("exit", () => resolve()));
+        child.stdin?.end();
+        const timer = setTimeout(() => (0, kill_agent_cjs_1.killAgent)(child), 5_000);
+        await exited;
+        clearTimeout(timer);
+    }
+    /** Installs playwright-core@version and its Chromium once per machine; returns the package dir. */
+    function ensureInstalled(version) {
+        const key = `${node_path_1.default.resolve(options.cacheRoot)}\0${version}`;
+        let pending = installs.get(key);
+        if (!pending) {
+            pending = install(version).finally(() => installs.delete(key));
+            installs.set(key, pending);
+        }
+        return pending;
+    }
+    async function install(version) {
+        const entry = node_path_1.default.join(options.cacheRoot, version);
+        const coreDir = node_path_1.default.join(entry, "node_modules", "playwright-core");
+        const npmEnv = (0, dependency_cache_cjs_1.npmEnvironment)(env);
+        if (env.PLAYWRIGHT_BROWSERS_PATH)
+            npmEnv.PLAYWRIGHT_BROWSERS_PATH = env.PLAYWRIGHT_BROWSERS_PATH;
+        if (!(await exists(node_path_1.default.join(entry, COMPLETE_MARKER)))) {
+            await node_fs_1.promises.mkdir(options.cacheRoot, { recursive: true, mode: 0o700 });
+            const staging = node_path_1.default.join(options.cacheRoot, `.tmp-${version}-${(0, node_crypto_1.randomBytes)(4).toString("hex")}`);
+            await node_fs_1.promises.mkdir(staging, { mode: 0o700 });
+            try {
+                await node_fs_1.promises.writeFile(node_path_1.default.join(staging, "package.json"), '{"private":true}\n');
+                const result = await runner.run(options.npmBin ?? "npm", [
+                    "install",
+                    "--ignore-scripts",
+                    "--no-audit",
+                    "--no-fund",
+                    "--no-package-lock",
+                    "--strict-ssl=true",
+                    "--cache",
+                    node_path_1.default.join(options.cacheRoot, ".npm"),
+                    "--logs-dir",
+                    node_path_1.default.join(options.cacheRoot, ".logs"),
+                    `playwright-core@${version}`,
+                ], { cwd: staging, env: npmEnv, timeoutMs: NPM_TIMEOUT_MS });
+                if (result.code !== 0) {
+                    log.warn(`npm install playwright-core@${version} exited ${result.code}: ${tail(result.stderr || result.stdout)}`);
+                    throw new Error(`The runtime could not install playwright-core@${version} (npm exited ${result.code}).`);
+                }
+                await node_fs_1.promises.writeFile(node_path_1.default.join(staging, COMPLETE_MARKER), `${new Date().toISOString()}\n`);
+                await node_fs_1.promises.rename(staging, entry).catch(async (error) => {
+                    // Another runtime process finished the same version first.
+                    if (!(await exists(node_path_1.default.join(entry, COMPLETE_MARKER))))
+                        throw error;
+                });
+            }
+            finally {
+                await node_fs_1.promises.rm(staging, { recursive: true, force: true }).catch(() => undefined);
+            }
+        }
+        // Idempotent; also restores a browser removed from Playwright's cache.
+        const browser = await runner.run(process.execPath, [node_path_1.default.join(coreDir, "cli.js"), "install", "chromium"], {
+            cwd: entry,
+            env: npmEnv,
+            timeoutMs: BROWSER_INSTALL_TIMEOUT_MS,
+        });
+        if (browser.code !== 0) {
+            log.warn(`playwright-core@${version} install chromium exited ${browser.code}: ${tail(browser.stderr || browser.stdout)}`);
+            throw new Error(`The runtime could not install Chromium for Playwright ${version}.`);
+        }
+        return coreDir;
+    }
+    async function launch(version, coreDir) {
+        const privateDir = node_path_1.default.join(options.workDir, exports.PLAYWRIGHT_SERVER_DIRNAME);
+        await node_fs_1.promises.rm(privateDir, { recursive: true, force: true });
+        await node_fs_1.promises.mkdir(privateDir, { recursive: true, mode: 0o700 });
+        const launcher = node_path_1.default.join(privateDir, "launcher.cjs");
+        await node_fs_1.promises.writeFile(launcher, LAUNCHER_SCRIPT, "utf8");
+        const nodePath = await node_fs_1.promises.realpath(process.execPath);
+        const canonicalCore = await node_fs_1.promises.realpath(coreDir);
+        const browsersPath = playwrightBrowsersPath(env, canonicalCore);
+        await node_fs_1.promises.mkdir(browsersPath, { recursive: true });
+        // <prefix>/bin/node: the prefix holds Node's own files. Never widen that
+        // to the home directory itself (for example ~/bin/node).
+        let nodeRoot = node_path_1.default.dirname(node_path_1.default.dirname(nodePath));
+        const home = node_path_1.default.resolve(env.HOME ?? node_os_1.default.homedir());
+        if (home === nodeRoot || home.startsWith(`${nodeRoot}${node_path_1.default.sep}`) || nodeRoot === node_path_1.default.sep)
+            nodeRoot = node_path_1.default.dirname(nodePath);
+        const params = {
+            NODE_ROOT: nodeRoot,
+            PLAYWRIGHT_CORE: canonicalCore,
+            BROWSERS: await node_fs_1.promises.realpath(browsersPath),
+            PRIVATE: await node_fs_1.promises.realpath(privateDir),
+        };
+        const args = [
+            "-p",
+            playwrightServerProfile(),
+            ...Object.entries(params).flatMap(([name, value]) => ["-D", `${name}=${value}`]),
+            nodePath,
+            node_path_1.default.join(params.PRIVATE, "launcher.cjs"),
+            canonicalCore,
+            token,
+        ];
+        const childEnv = { TMPDIR: params.PRIVATE };
+        for (const name of ["HOME", "PATH", "LANG", "PLAYWRIGHT_BROWSERS_PATH"]) {
+            if (env[name] !== undefined)
+                childEnv[name] = env[name];
+        }
+        const child = (options.spawnServer ?? defaultSpawn)("/usr/bin/sandbox-exec", args, { cwd: params.PRIVATE, env: childEnv });
+        return new Promise((resolve, reject) => {
+            let stdout = "";
+            let stderr = "";
+            const timer = setTimeout(() => fail(new Error("did not start within 60 s")), START_TIMEOUT_MS);
+            const fail = (error) => {
+                clearTimeout(timer);
+                (0, kill_agent_cjs_1.killAgent)(child);
+                reject(new Error(`The Playwright ${version} browser server could not start: ${error.message}${launchDetail(stderr)}`));
+            };
+            child.stdout?.on("data", (chunk) => {
+                stdout += chunk.toString();
+                const match = new RegExp(`${READY_MARKER} (ws://127\\.0\\.0\\.1:\\d+/${token})`).exec(stdout);
+                if (!match)
+                    return;
+                clearTimeout(timer);
+                running = { child, endpoint: match[1], version };
+                resolve(match[1]);
+            });
+            child.stderr?.on("data", (chunk) => {
+                if (stderr.length < 64_000)
+                    stderr += chunk.toString();
+            });
+            child.on("error", fail);
+            child.on("exit", (code, signal) => {
+                if (running?.child === child)
+                    running = undefined;
+                fail(new Error(`exited ${signal ?? code}`));
+            });
+        });
+    }
+    return {
+        /** Secret part of the endpoint, for redaction. */
+        token,
+        start(args) {
+            const next = queue.then(async () => {
+                assertActive();
+                if ((options.platform ?? process.platform) !== "darwin") {
+                    throw new Error("Navarch's Playwright browser server is only needed and supported on macOS hosts.");
+                }
+                const version = await projectPlaywrightVersion(options.worktreePath, args.directory);
+                const live = running;
+                if (live && live.version === version && live.child.exitCode === null && live.child.signalCode === null) {
+                    return { endpoint: live.endpoint, version, reused: true };
+                }
+                await stop();
+                const coreDir = await ensureInstalled(version);
+                assertActive();
+                const endpoint = await launch(version, coreDir);
+                if (closed || !options.isActive()) {
+                    await stop();
+                    assertActive();
+                }
+                log.info(`playwright-core ${version} browser server started for ${options.worktreePath}`);
+                return { endpoint, version, reused: false };
+            });
+            queue = next.catch(() => undefined);
+            return next;
+        },
+        async close() {
+            closed = true;
+            await queue.catch(() => undefined);
+            await stop();
+        },
+    };
+}
+exports.playwrightServerShape = {
+    directory: zod_1.z.string().min(1).max(500).default(".")
+        .describe("Directory inside the checkout whose node_modules holds @playwright/test (where you run `playwright test`)."),
+};
+/** Registers start_playwright_browser on a lease's navarch-browser MCP server. */
+function registerPlaywrightServerTool(server, playwright) {
+    server.registerTool("start_playwright_browser", {
+        description: "Start Chromium for this checkout's own Playwright test suite outside the coding-agent sandbox, where Codex's macOS sandbox cannot launch it. Navarch installs the browser for the exact Playwright version the checkout uses. Returns PW_TEST_CONNECT_WS_ENDPOINT: run the project's usual `playwright test` command in your shell with it set. The suite still runs in your sandbox; the browser reaches only this machine's loopback services.",
+        inputSchema: exports.playwrightServerShape,
+    }, async (args) => {
+        try {
+            const { endpoint, version, reused } = await playwright.start(args);
+            return { content: [{ type: "text", text: [
+                            `Playwright browser server ${reused ? "already running" : "ready"}: Playwright ${version} with its own Chromium, outside the coding-agent sandbox.`,
+                            "Run the project's suite exactly as the repository runs it, with this variable set in the same command:",
+                            `  PW_TEST_CONNECT_WS_ENDPOINT=${endpoint}`,
+                            `Example: PW_TEST_CONNECT_WS_ENDPOINT=${endpoint} node node_modules/@playwright/test/cli.js test`,
+                            "- This is the same suite, not a substitute: report the command and its result as the e2e check.",
+                            "- Pages reach only loopback services on this machine (the config's webServer, http://localhost:<port>); other hosts and file:// URLs are refused.",
+                            "- The config's browser launch options (headed, channel, executablePath, launch args) do not apply, and only Chromium projects can connect.",
+                        ].join("\n") }] };
+        }
+        catch (error) {
+            return { isError: true, content: [{ type: "text", text: String(error) }] };
+        }
+    });
+}
+function playwrightBrowsersPath(env, coreDir) {
+    const configured = env.PLAYWRIGHT_BROWSERS_PATH;
+    // "0" keeps browsers inside the package (readable through PLAYWRIGHT_CORE).
+    if (configured === "0")
+        return node_path_1.default.join(coreDir, ".local-browsers");
+    if (configured)
+        return node_path_1.default.resolve(configured);
+    return node_path_1.default.join(env.HOME ?? node_os_1.default.homedir(), "Library", "Caches", "ms-playwright");
+}
+function defaultSpawn(bin, args, options) {
+    return (0, node_child_process_1.spawn)(bin, args, { cwd: options.cwd, env: options.env, stdio: ["pipe", "pipe", "pipe"], detached: true });
+}
+function launchDetail(stderr) {
+    const lines = stderr.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+    const line = lines.find((item) => /FATAL:|Error:|Executable doesn't exist/.test(item)) ?? lines.at(-1);
+    return line ? ` (${line.slice(0, 300)})` : "";
+}
+function tail(text) {
+    return text.trim().split(/\r?\n/).slice(-3).join(" | ").slice(0, 500);
+}
+async function exists(file) {
+    try {
+        await node_fs_1.promises.access(file);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/session.cjs

@@ -39,6 +39,7 @@ const agent_auth_cjs_1 = require("./agent-auth.cjs");
 const agent_model_cjs_1 = require("./agent-model.cjs");
 const github_credential_cjs_1 = require("./github-credential.cjs");
 const browser_evidence_cjs_1 = require("./browser-evidence.cjs");
+const playwright_server_cjs_1 = require("./playwright-server.cjs");
 const git_grant_cjs_1 = require("./git-grant.cjs");
 const commit_attribution_cjs_1 = require("./commit-attribution.cjs");
 /** Filename the generated platform MCP config is written under inside the session metadata directory. */
@@ -680,13 +681,25 @@ async function runClaimedSession(deps, claimed, sessionId, lifecycle) {
         }
         steering?.start();
         await gitWorktree.prepare();
-        if (!config.mcpConfigPath && config.sandboxMode === "host"
-            && ["build", "verify", "qa"].includes(task.task_type)
-            && task.required_capabilities?.includes("browser-use")
-            && ["codex", "claude-code", "antigravity", "opencode", "acp", "muse"].includes(runtime)) {
+        const { browserUse, playwrightSuites } = (0, browser_evidence_cjs_1.navarchBrowserTools)({
+            taskType: task.task_type, requiredCapabilities: task.required_capabilities, runtime,
+            platform: process.platform, sandboxMode: config.sandboxMode, mcpConfigPath: config.mcpConfigPath,
+        });
+        if (browserUse || playwrightSuites) {
+            const isActive = () => !leaseLost && !sessionClosing && !deps.shutdownSignal?.aborted;
+            const playwrightServer = playwrightSuites
+                ? (0, playwright_server_cjs_1.createPlaywrightServer)({
+                    worktreePath: gitWorktree.worktreePath,
+                    workDir,
+                    cacheRoot: node_path_1.default.join(config.workspaceRoot, playwright_server_cjs_1.PLAYWRIGHT_SERVER_DIRNAME),
+                    isActive,
+                })
+                : undefined;
+            if (playwrightServer)
+                registry.register(playwrightServer.token);
             browserEvidence = await (0, browser_evidence_cjs_1.startBrowserEvidence)({
                 apiBase: api.getBaseUrl(), machineToken: api.getToken() ?? "", leaseId,
-                isActive: () => !leaseLost && !sessionClosing && !deps.shutdownSignal?.aborted,
+                isActive, playwrightServer,
             });
             registry.register(browserEvidence.token);
             const mcp = JSON.parse(await node_fs_1.promises.readFile(mcpConfigPath, "utf8"));
@@ -700,7 +713,10 @@ async function runClaimedSession(deps, claimed, sessionId, lifecycle) {
             }
             mcp.mcpServers.navarch_browser = browserConfig;
             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. 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 (browserUse)
+                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 (playwrightServer)
+                promptText += "\n\nCodex's macOS sandbox kills Chromium at startup (`bootstrap_check_in ... MachPortRendezvousServer: Permission denied`), so the project's own Playwright suite cannot launch a browser in your shell, and you cannot install Playwright's browsers there either. When a task needs that suite, call navarch_browser's start_playwright_browser (pass `directory` when @playwright/test is installed below the checkout root), then run the repository's usual `playwright test` command with the returned PW_TEST_CONNECT_WS_ENDPOINT set. The suite still runs in your sandbox; only Chromium runs outside it, installed by Navarch for the checkout's exact Playwright version and limited to this machine's loopback services. Never skip, waive, or replace the suite because of the sandbox; report the command you ran and its result.\n";
         }
         if (gitWorktree.hostedCheckpointRestoreFailure) {
             log.warn(`hosted checkpoint for ${leaseId} could not be restored: ` +

package/package.json

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