@sagentlab/navarch-runtime 0.1.78 → 0.1.79

package/README.md

@@ -22,6 +22,26 @@ are returned as capture errors; the runtime does not relax host permissions.
 Docker sessions continue to use their image's tooling, and an operator-supplied
 `NAVARCH_MCP_CONFIG_PATH` remains authoritative.
 
+### Browser capability probe
+
+`browser-use` is advertised only after a startup launch check passes. When
+`start` boots, the runtime launches its headless Chromium on the host. Then,
+for every advertised runtime that wraps agent shells in an OS sandbox
+(currently Codex, unless it runs with `--dangerously-bypass-approvals-and-sandbox`
+or `danger-full-access`), it launches Chromium again through `codex sandbox`
+with the same permission policy a session gets. If either launch fails, the
+runtime claims without `browser-use` and reports the reason on every machine
+heartbeat; the Agents page shows it. The result is cached for the process
+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
+probed because its image supplies the browser. Set `NAVARCH_BROWSER_PROBE=off`
+to trust the configured capability list without a check.
+
 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,
@@ -403,6 +423,7 @@ unchanged across the deployment.
 | `NAVARCH_WORKSPACE_ROOT` | `<config dir>/sandboxes` | Persistent bare repo caches plus isolated per-session worktrees. |
 | `NAVARCH_MAX_SESSIONS` | `5` | Local concurrent-session capacity cap — see `src/capacity.cts`. |
 | `NAVARCH_CAPABILITIES` | `shell,browser-use` (`docker-sandbox,shell` in Docker mode) | Comma list reported at heartbeat/claim time. Docker mode does not advertise browser use until the configured image provides it. |
+| `NAVARCH_BROWSER_PROBE` | on | Advertise `browser-use` only after a startup headless-Chromium launch (host, plus each sandboxed runtime) succeeds. `off` trusts `NAVARCH_CAPABILITIES` without a check. |
 | `NAVARCH_OWNER_ZONE` | `sagentlab` | `sagentlab` or `customer-<slug>-premises` (project-plan.md §3.11). |
 | `NAVARCH_POLL_INTERVAL_MS` | `30000` | Claim-loop poll interval. |
 | `NAVARCH_HEARTBEAT_INTERVAL_MS` | `60000` | Machine-level heartbeat interval. |

package/dist/browser-evidence.cjs

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.captureSchema = void 0;
 exports.installEvidenceBrowser = installEvidenceBrowser;
+exports.launchCaptureBrowser = launchCaptureBrowser;
 exports.startBrowserEvidence = startBrowserEvidence;
 const node_http_1 = require("node:http");
 const node_crypto_1 = require("node:crypto");
@@ -21,6 +22,17 @@ async function installEvidenceBrowser() {
         timeout: 180_000,
     });
 }
+/** The runtime's own headless Chromium, shared by evidence capture and the startup probe. */
+function launchCaptureBrowser() {
+    return playwright_1.chromium.launch({
+        headless: true,
+        chromiumSandbox: true,
+        timeout: 20_000,
+        // Do not pass the supervisor's provider or machine credentials to Chrome.
+        env: Object.fromEntries(["HOME", "PATH", "TMPDIR", "TEMP", "TMP", "SystemRoot"]
+            .flatMap((key) => process.env[key] ? [[key, process.env[key]]] : [])),
+    });
+}
 const captureShape = {
     url: zod_1.z.string().url().refine((value) => {
         const url = new URL(value);
@@ -60,14 +72,7 @@ async function startBrowserEvidence(options) {
         const images = [];
         try {
             try {
-                browser = await (options.launch?.() ?? playwright_1.chromium.launch({
-                    headless: true,
-                    chromiumSandbox: true,
-                    timeout: 20_000,
-                    // Do not pass the supervisor's provider or machine credentials to Chrome.
-                    env: Object.fromEntries(["HOME", "PATH", "TMPDIR", "TEMP", "TMP", "SystemRoot"]
-                        .flatMap((key) => process.env[key] ? [[key, process.env[key]]] : [])),
-                }));
+                browser = await (options.launch?.() ?? launchCaptureBrowser());
             }
             catch {
                 throw new Error("Runtime browser could not start. On the agent host run navarch-runtime browser-install. Check host browser permissions; do not change the task repository or CI to install capture tooling.");

package/dist/browser-probe.cjs

@@ -0,0 +1,277 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BROWSER_CAPABILITY = void 0;
+exports.probeBrowserCapability = probeBrowserCapability;
+exports.capabilitiesAfterBrowserProbe = capabilitiesAfterBrowserProbe;
+exports.codexSandboxNeedsProbe = codexSandboxNeedsProbe;
+exports.codexSandboxProbeArgs = codexSandboxProbeArgs;
+exports.summarizeLaunchFailure = summarizeLaunchFailure;
+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_path_1 = __importDefault(require("node:path"));
+const codex_cjs_1 = require("./adapters/codex.cjs");
+const browser_evidence_cjs_1 = require("./browser-evidence.cjs");
+const logger_cjs_1 = require("./logger.cjs");
+const worktree_guard_cjs_1 = require("./worktree-guard.cjs");
+const log = (0, logger_cjs_1.createLogger)("browser-probe");
+exports.BROWSER_CAPABILITY = "browser-use";
+const HOST_PROBE_TIMEOUT_MS = 30_000;
+const SANDBOX_PROBE_TIMEOUT_MS = 45_000;
+const PROBE_START_MARKER = "NAVARCH_BROWSER_PROBE_START";
+const PROBE_OK_MARKER = "NAVARCH_BROWSER_PROBE_OK";
+const MAX_REASON_LENGTH = 480;
+/**
+ * Probes once per runtime process (the result is cached by the caller for the
+ * process lifetime; a restart re-probes). A machine on 2026-10-01 advertised
+ * browser-use by default while Codex's macOS seatbelt killed every Chromium
+ * launch at `bootstrap_check_in ... MachPortRendezvousServer: Permission
+ * denied`, so nine milestone QA runs ended BLOCKED for environment reasons.
+ * The runtime's own capture browser still worked there because it runs
+ * outside the agent sandbox, which is why the probe also launches Chromium
+ * through each sandbox an advertised runtime wraps its shell in.
+ */
+async function probeBrowserCapability(config, deps = {}) {
+    const now = deps.now ?? (() => new Date());
+    const skipped = (reason) => ({
+        status: "skipped",
+        reason,
+        checked_at: now().toISOString(),
+    });
+    if (!config.capabilities.includes(exports.BROWSER_CAPABILITY)) {
+        return skipped("browser-use is not in this machine's configured capabilities.");
+    }
+    if (!config.browserProbe) {
+        return skipped("NAVARCH_BROWSER_PROBE=off: browser-use is advertised without a launch check.");
+    }
+    if (config.sandboxMode === "docker") {
+        return skipped("Docker sessions use the sandbox image's browser; the host was not probed.");
+    }
+    const launchHost = deps.launchHost ?? (async () => {
+        const browser = await (0, browser_evidence_cjs_1.launchCaptureBrowser)();
+        try {
+            const page = await browser.newPage();
+            await page.setContent("<title>navarch-probe</title>");
+        }
+        finally {
+            await browser.close();
+        }
+    });
+    try {
+        await withTimeout(launchHost(), HOST_PROBE_TIMEOUT_MS, "headless Chromium launch timed out");
+    }
+    catch (error) {
+        return {
+            status: "failed",
+            reason: truncate(`Headless Chromium could not start on this machine: ${summarizeLaunchFailure(String(error))} ` +
+                "Run `navarch-runtime browser-install`, then restart the agent."),
+            checked_at: now().toISOString(),
+        };
+    }
+    const platform = deps.platform ?? process.platform;
+    if (codexSandboxNeedsProbe(config, platform)) {
+        const sandboxFailure = await probeCodexSandbox(config, deps);
+        if (sandboxFailure) {
+            return { status: "failed", reason: truncate(sandboxFailure), checked_at: now().toISOString() };
+        }
+    }
+    return { status: "passed", checked_at: now().toISOString() };
+}
+/** Withholds `browser-use` when the probe failed; any other verdict keeps the configured list. */
+function capabilitiesAfterBrowserProbe(capabilities, probe) {
+    return probe.status === "failed"
+        ? capabilities.filter((capability) => capability !== exports.BROWSER_CAPABILITY)
+        : capabilities;
+}
+/**
+ * Codex runs agent shell commands under its own OS sandbox (seatbelt on
+ * macOS, Landlock/seccomp on Linux) unless the operator bypassed it. Every
+ * advertised runtime must be able to run a browser task: the control plane,
+ * not this machine, picks which adapter a claimed task runs under.
+ */
+function codexSandboxNeedsProbe(config, platform) {
+    if (config.sandboxMode !== "host" || platform === "win32")
+        return false;
+    const runtimes = new Set([config.agentType, ...(config.runtimes ?? [])]);
+    return runtimes.has("codex") && !codexSandboxBypassed(config.codexExtraArgs);
+}
+function codexSandboxBypassed(args) {
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === "--dangerously-bypass-approvals-and-sandbox")
+            return true;
+        const value = arg === "--sandbox" || arg === "-s"
+            ? args[index + 1]
+            : arg.startsWith("--sandbox=") || arg.startsWith("-s=")
+                ? arg.slice(arg.indexOf("=") + 1)
+                : (arg === "-c" || arg === "--config") && /^sandbox_mode=/.test(args[index + 1] ?? "")
+                    ? args[index + 1].slice("sandbox_mode=".length)
+                    : undefined;
+        if (value?.replace(/["']/g, "") === "danger-full-access")
+            return true;
+    }
+    return false;
+}
+/**
+ * `codex sandbox` arguments reproducing the policy a host session runs under:
+ * the operator's explicit policy when NAVARCH_CODEX_EXTRA_ARGS has one,
+ * otherwise Navarch's generated worktree-guard profile, otherwise the user's
+ * own Codex configuration (guard off). `--ignore-user-config` and approval
+ * settings only affect `codex exec`, so they are not forwarded.
+ */
+function codexSandboxProbeArgs(config, roots) {
+    if ((0, codex_cjs_1.hasExplicitPermissionPolicy)(config.codexExtraArgs)) {
+        const forwarded = [];
+        const args = config.codexExtraArgs;
+        for (let index = 0; index < args.length; index += 1) {
+            const arg = args[index];
+            const next = args[index + 1];
+            if ((arg === "-c" || arg === "--config" || arg === "-p" || arg === "--profile") && next !== undefined) {
+                forwarded.push(arg, next);
+                index += 1;
+            }
+            else if (arg.startsWith("--config=")) {
+                forwarded.push("-c", arg.slice("--config=".length));
+            }
+            else if ((arg === "--sandbox" || arg === "-s") && next !== undefined) {
+                forwarded.push("-c", `sandbox_mode=${JSON.stringify(next)}`);
+                index += 1;
+            }
+            else if (arg.startsWith("--sandbox=") || arg.startsWith("-s=")) {
+                forwarded.push("-c", `sandbox_mode=${JSON.stringify(arg.slice(arg.indexOf("=") + 1))}`);
+            }
+        }
+        return forwarded;
+    }
+    if (!config.worktreeGuard)
+        return [];
+    const workspaceRoot = node_path_1.default.join(roots.probeRoot, "workspace");
+    return (0, worktree_guard_cjs_1.codexWorktreeGuardArgs)({
+        workDir: node_path_1.default.join(workspaceRoot, "session"),
+        worktreePath: roots.worktreePath,
+        repositoryPath: node_path_1.default.join(workspaceRoot, "repo"),
+        workspaceRoot,
+        extraRoots: [...config.guardExtraRoots, ...roots.readRoots],
+    }).filter((arg) => arg !== "--ignore-user-config");
+}
+const PROBE_SCRIPT = `
+process.stdout.write(${JSON.stringify(PROBE_START_MARKER)} + "\\n");
+(async () => {
+  const { chromium } = require(process.env.NAVARCH_PROBE_PLAYWRIGHT);
+  const browser = await chromium.launch({ headless: true, timeout: 20000 });
+  try {
+    const page = await browser.newPage();
+    await page.setContent("<title>navarch-probe</title>");
+  } finally {
+    await browser.close();
+  }
+  process.stdout.write(${JSON.stringify(PROBE_OK_MARKER)} + "\\n");
+})().catch((error) => {
+  process.stderr.write(String((error && error.stack) || error));
+  process.exit(1);
+});
+`;
+async function probeCodexSandbox(config, deps) {
+    const probeRoot = await node_fs_1.promises.mkdtemp(node_path_1.default.join(deps.tmpDir ?? node_os_1.default.tmpdir(), "navarch-browser-probe-"));
+    try {
+        const worktreePath = node_path_1.default.join(probeRoot, "workspace", "worktree");
+        await node_fs_1.promises.mkdir(worktreePath, { recursive: true });
+        const scriptPath = node_path_1.default.join(worktreePath, "probe.cjs");
+        await node_fs_1.promises.writeFile(scriptPath, PROBE_SCRIPT, "utf8");
+        const playwrightDir = await node_fs_1.promises.realpath(deps.playwrightDir?.() ?? node_path_1.default.dirname(require.resolve("playwright/package.json")));
+        const args = codexSandboxProbeArgs(config, {
+            probeRoot,
+            worktreePath,
+            // Node and the runtime's Playwright install (with its playwright-core
+            // sibling) must be readable for the probe to start; the browser cache
+            // itself is a guard read root already.
+            readRoots: [node_path_1.default.dirname(await node_fs_1.promises.realpath(process.execPath)), node_path_1.default.dirname(playwrightDir)],
+        });
+        const env = { NAVARCH_PROBE_PLAYWRIGHT: playwrightDir };
+        for (const key of ["HOME", "PATH", "TMPDIR", "CODEX_HOME", "PLAYWRIGHT_BROWSERS_PATH", "XDG_CACHE_HOME"]) {
+            if (process.env[key])
+                env[key] = process.env[key];
+        }
+        const result = await (deps.run ?? runToCompletion)(config.codexBin, ["sandbox", ...args, "--", process.execPath, scriptPath], { cwd: worktreePath, env, timeoutMs: SANDBOX_PROBE_TIMEOUT_MS });
+        if (result.code === 0 && result.stdout.includes(PROBE_OK_MARKER))
+            return null;
+        const output = `${result.stderr}\n${result.stdout}`;
+        if (!result.stdout.includes(PROBE_START_MARKER)) {
+            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}`}). ` +
+                "Update the Codex CLI, or run browser tasks with another agent.");
+        }
+        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} ` +
+            (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.");
+    }
+    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))}`;
+    }
+    finally {
+        await node_fs_1.promises.rm(probeRoot, { recursive: true, force: true }).catch(() => undefined);
+    }
+}
+/** The one line of a Chromium/Playwright launch failure an operator can act on. */
+function summarizeLaunchFailure(output) {
+    const lines = output.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+    const fatal = lines.find((line) => /FATAL:|bootstrap_check_in/.test(line));
+    if (fatal) {
+        // "[pid=1][err] [1001/210406.593317:FATAL:base/apple/mach_port_rendezvous_mac.cc:159] Check failed: ..."
+        return fatal.replace(/^.*FATAL:[^\]]*\]\s*/, "");
+    }
+    const missing = lines.find((line) => /Executable doesn't exist/.test(line));
+    if (missing)
+        return "Chromium is not installed for the runtime's Playwright.";
+    const message = lines.find((line) => /Error:/.test(line)) ?? lines[0] ?? "unknown error";
+    return message.replace(/^.*?Error:\s*/, "");
+}
+function truncate(text) {
+    return text.length > MAX_REASON_LENGTH ? `${text.slice(0, MAX_REASON_LENGTH - 1)}…` : text;
+}
+function withTimeout(promise, ms, message) {
+    let timer;
+    return Promise.race([
+        promise,
+        new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new Error(message)), ms);
+        }),
+    ]).finally(() => clearTimeout(timer));
+}
+function runToCompletion(bin, args, options) {
+    return new Promise((resolve) => {
+        let stdout = "";
+        let stderr = "";
+        let timedOut = false;
+        const child = (0, node_child_process_1.spawn)(bin, args, { cwd: options.cwd, env: options.env, stdio: ["ignore", "pipe", "pipe"] });
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill("SIGKILL");
+        }, options.timeoutMs);
+        child.stdout.on("data", (chunk) => {
+            if (stdout.length < 64_000)
+                stdout += chunk.toString();
+        });
+        child.stderr.on("data", (chunk) => {
+            if (stderr.length < 64_000)
+                stderr += chunk.toString();
+        });
+        child.on("error", (error) => {
+            clearTimeout(timer);
+            resolve({ code: null, stdout, stderr: `${stderr}\n${String(error)}`, timedOut });
+        });
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            resolve({ code, stdout, stderr, timedOut });
+        });
+    });
+}

package/dist/cli.cjs

@@ -19,6 +19,7 @@ const update_coordinator_cjs_1 = require("./update-coordinator.cjs");
 const supervisor_cjs_1 = require("./supervisor.cjs");
 const worktree_janitor_cjs_1 = require("./worktree-janitor.cjs");
 const browser_evidence_cjs_1 = require("./browser-evidence.cjs");
+const browser_probe_cjs_1 = require("./browser-probe.cjs");
 const log = (0, logger_cjs_1.createLogger)("cli");
 const PACKAGE_NAME = "@sagentlab/navarch-runtime";
 /** Accepted `--agent` ids as usage metavariables, generated from one source of truth. */
@@ -235,8 +236,22 @@ async function connectCommand(flags) {
 async function startCommand(flags) {
     const baseConfig = configFromFlags(flags);
     const identity = await (0, machine_store_cjs_1.resolveMachineIdentity)(baseConfig.configDir, baseConfig.apiBase);
-    const config = configFromFlags(flags, identity);
-    warnUnknownRuntimes(config);
+    const configuredConfig = configFromFlags(flags, identity);
+    warnUnknownRuntimes(configuredConfig);
+    // Probe before the first heartbeat or claim so browser-use is never
+    // advertised on a machine whose agents cannot start a browser. The verdict
+    // holds for this process; restarting the runtime probes again.
+    const browserProbe = await (0, browser_probe_cjs_1.probeBrowserCapability)(configuredConfig);
+    if (browserProbe.status === "failed") {
+        log.warn(`not advertising browser-use: ${browserProbe.reason}`);
+    }
+    else if (browserProbe.status === "passed") {
+        log.info("browser probe passed; advertising browser-use");
+    }
+    const config = {
+        ...configuredConfig,
+        capabilities: (0, browser_probe_cjs_1.capabilitiesAfterBrowserProbe)(configuredConfig.capabilities, browserProbe),
+    };
     const api = new api_cjs_1.NavarchApiClient({ baseUrl: identity.api_base, token: identity.token });
     const capacity = new capacity_cjs_1.CapacityTracker(config.maxSessions);
     const runtimeShutdown = new AbortController();
@@ -279,7 +294,7 @@ async function startCommand(flags) {
         // capacity slot.
         runtimeShutdown.abort();
         void capacity.waitForIdle().then(() => process.exit(CREDENTIALS_REJECTED_EXIT_CODE));
-    });
+    }, browserProbe);
     updateCoordinatorRef.current = new update_coordinator_cjs_1.RuntimeUpdateCoordinator({
         config,
         claimLoop,
@@ -377,6 +392,8 @@ async function doctorCommand(flags) {
     console.log(`worktree_guard:  ${config.worktreeGuard ? "on" : "off"}`);
     console.log(`runtimes:        ${config.runtimes?.join(", ") ?? config.agentType}`);
     console.log(`docker:          ${dockerOk ? "available" : "NOT AVAILABLE (docker-backed sessions will fail)"}`);
+    const browserProbe = await (0, browser_probe_cjs_1.probeBrowserCapability)(config);
+    console.log(`browser:         ${browserProbe.status.toUpperCase()}${browserProbe.reason ? ` — ${browserProbe.reason}` : ""}`);
     if (!identity) {
         console.log(`machine:         not registered — run \`${invocation("register")}\``);
         return;

package/dist/config.cjs

@@ -169,6 +169,7 @@ function loadRuntimeConfig(env = process.env) {
         // Reads only the quota numbers providers already write to disk, so it is on
         // by default; operators who would rather share nothing can opt out.
         reportUsageLimits: !["off", "false", "0"].includes(env.NAVARCH_USAGE_LIMITS ?? ""),
+        browserProbe: !["off", "false", "0"].includes(env.NAVARCH_BROWSER_PROBE ?? ""),
         codexHome: defaultCodexHome(env),
         claudeConfigPath: defaultClaudeConfigPath(env),
     };

package/dist/heartbeat-loop.cjs

@@ -34,6 +34,7 @@ class MachineHeartbeatLoop {
     onResult;
     onHealthy;
     onCredentialsRejected;
+    browserProbe;
     timer = null;
     heartbeatInFlight = false;
     heartbeatPending = false;
@@ -48,7 +49,9 @@ class MachineHeartbeatLoop {
      * then: without this the runtime would warn every interval forever while
      * claiming nothing, which is indistinguishable from an idle agent.
      */
-    onCredentialsRejected) {
+    onCredentialsRejected, 
+    /** Cached for the process lifetime; a restart re-probes. */
+    browserProbe) {
         this.api = api;
         this.machineId = machineId;
         this.config = config;
@@ -57,6 +60,7 @@ class MachineHeartbeatLoop {
         this.onResult = onResult;
         this.onHealthy = onHealthy;
         this.onCredentialsRejected = onCredentialsRejected;
+        this.browserProbe = browserProbe;
     }
     start() {
         if (this.timer)
@@ -101,6 +105,7 @@ class MachineHeartbeatLoop {
                     const result = await this.api.machineHeartbeat(this.machineId, {
                         available_capacity: this.draining ? 0 : this.capacity.available(),
                         capabilities: this.config.capabilities,
+                        ...(this.browserProbe ? { browser_probe: this.browserProbe } : {}),
                         ...(agentUsage ? { agent_usage: agentUsage } : {}),
                         // Explicit null when unpinned, so the control plane clears a model
                         // this machine reported before its pin was removed.

package/package.json

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