@sagentlab/navarch-runtime 0.1.78 → 0.1.80

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. |
@@ -920,3 +941,37 @@ over the project's session model for the selected adapter only; switching agent
 types does not reuse another adapter's pin. Reconnect without `--model` to return
 to project-controlled model selection. Older identities without a model keep
 using the control-plane execution policy.
+
+
+### Pi on your own machine
+
+Select **Pi (local)** in Connect an agent, or set `NAVARCH_AGENT=pi-local`
+and `NAVARCH_RUNTIMES=pi-local`. Use a current Pi CLI with native MCP support
+and Node.js 22.19 or newer. Host mode requires `NAVARCH_WORKTREE_GUARD=off`:
+Pi's shell tools do not enforce the runtime's worktree boundary. The UI's
+connect and supervise commands include this opt-out. Use a dedicated worker.
+Docker is not advertised for this adapter yet.
+
+The initial model is `qwen3.8-flash-next-iq2_xs`, served by a local
+OpenAI-compatible endpoint at `http://127.0.0.1:8080/v1`. Start that model server
+separately. Set `NAVARCH_PI_LOCAL_BASE_URL` in the worker environment for a
+different endpoint (for example, Ollama's `http://127.0.0.1:11434/v1`).
+`NAVARCH_PI_BIN` overrides the executable; `NAVARCH_PI_EXTRA_ARGS` adds CLI
+arguments. `--model` at connect pins this machine's model as for other agents.
+
+Bare model IDs use the generated `local` provider. Exact `provider/model`
+references use the machine's existing Pi catalog and credentials from
+`~/.pi/agent/models.json` and `auth.json` (or `PI_CODING_AGENT_DIR`). Run
+`pi --list-models` to inspect that catalog. The UI puts the local default first
+and labels public cloud suggestions by provider; suggestions do not imply
+credentials or access. Custom model IDs remain editable.
+
+Per-session configuration lives in a temporary agent directory, including
+Navarch's authenticated `mcp.json`. Pi runs without persisted sessions,
+automatically loaded extensions, skills, or project configuration. Temporary
+configuration is removed at exit. Hosted Pi keeps its separate `pi` runtime,
+DeepSeek provider, and billing policy; local sessions use `pi-local` and the
+project's `pi_local_model` policy.
+
+Pi CLI and model configuration reference:
+https://github.com/earendil-works/pi/tree/main/packages/coding-agent/docs

package/dist/adapters/index.cjs

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.runQoderAdapter = exports.qoderAdapter = exports.runAcpAdapter = exports.acpAdapter = exports.runPiAdapter = exports.piAdapter = exports.runOpenCodeAdapter = exports.openCodeAdapter = exports.runGeminiAdapter = exports.geminiAdapter = exports.runCodexAdapter = exports.codexAdapter = exports.runClaudeCodeAdapter = exports.claudeCodeAdapter = void 0;
+exports.runQoderAdapter = exports.qoderAdapter = exports.runAcpAdapter = exports.acpAdapter = exports.runPiAdapter = exports.piAdapter = exports.runLocalPiAdapter = exports.localPiAdapter = exports.runOpenCodeAdapter = exports.openCodeAdapter = exports.runGeminiAdapter = exports.geminiAdapter = exports.runCodexAdapter = exports.codexAdapter = exports.runClaudeCodeAdapter = exports.claudeCodeAdapter = void 0;
 exports.selectAdapter = selectAdapter;
 const claude_cjs_1 = require("./claude.cjs");
 Object.defineProperty(exports, "claudeCodeAdapter", { enumerable: true, get: function () { return claude_cjs_1.claudeCodeAdapter; } });
@@ -14,6 +14,9 @@ Object.defineProperty(exports, "runGeminiAdapter", { enumerable: true, get: func
 const opencode_cjs_1 = require("./opencode.cjs");
 Object.defineProperty(exports, "openCodeAdapter", { enumerable: true, get: function () { return opencode_cjs_1.openCodeAdapter; } });
 Object.defineProperty(exports, "runOpenCodeAdapter", { enumerable: true, get: function () { return opencode_cjs_1.runOpenCodeAdapter; } });
+const pi_local_cjs_1 = require("./pi-local.cjs");
+Object.defineProperty(exports, "localPiAdapter", { enumerable: true, get: function () { return pi_local_cjs_1.localPiAdapter; } });
+Object.defineProperty(exports, "runLocalPiAdapter", { enumerable: true, get: function () { return pi_local_cjs_1.runLocalPiAdapter; } });
 const pi_cjs_1 = require("./pi.cjs");
 Object.defineProperty(exports, "piAdapter", { enumerable: true, get: function () { return pi_cjs_1.piAdapter; } });
 Object.defineProperty(exports, "runPiAdapter", { enumerable: true, get: function () { return pi_cjs_1.runPiAdapter; } });
@@ -44,6 +47,8 @@ function selectAdapter(agentType) {
             return qoder_cjs_1.qoderAdapter;
         case "claude-code":
             return claude_cjs_1.claudeCodeAdapter;
+        case "pi-local":
+            return pi_local_cjs_1.localPiAdapter;
         case "pi":
             // Managed hosted runtime (#885): reachable only on a managed runner
             // executing a `runtime: "pi"` claim — config.cts never produces "pi"

package/dist/adapters/pi-local.cjs

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.localPiAdapter = void 0;
+exports.runLocalPiAdapter = runLocalPiAdapter;
+const pi_cjs_1 = require("./pi.cjs");
+/** BYO Pi: native MCP, operator provider catalog, and a local OpenAI-compatible default. */
+async function runLocalPiAdapter(options) {
+    if (options.dockerExec)
+        throw new Error("Pi (local) requires host mode");
+    if (options.signal?.aborted)
+        return { exitCode: null, timedOut: false, killedByLeaseLoss: true, stdout: "", stderr: "" };
+    const model = options.model ?? "qwen3.8-flash-next-iq2_xs";
+    const args = ["--mode", "json", "--no-session", "--no-extensions", "--no-skills", "--no-approve", ...options.extraArgs,
+        "--model", model.includes("/") ? model : `local/${model}`];
+    if (options.reasoningEffort)
+        args.push("--thinking", options.reasoningEffort === "max" ? "xhigh" : options.reasoningEffort);
+    args.push("-p", options.prompt);
+    return (0, pi_cjs_1.attachPiOutput)(await (0, pi_cjs_1.runOnHost)(options, args, true));
+}
+exports.localPiAdapter = { agentType: "pi-local", run: runLocalPiAdapter };

package/dist/adapters/pi.cjs

@@ -8,7 +8,9 @@ exports.buildHostedPiBudgetExtension = buildHostedPiBudgetExtension;
 exports.resolveHostedPiModel = resolveHostedPiModel;
 exports.buildPiProviderConfig = buildPiProviderConfig;
 exports.parsePiJsonEvents = parsePiJsonEvents;
+exports.attachPiOutput = attachPiOutput;
 exports.runPiAdapter = runPiAdapter;
+exports.runOnHost = runOnHost;
 const node_child_process_1 = require("node:child_process");
 const node_fs_1 = require("node:fs");
 const node_os_1 = __importDefault(require("node:os"));
@@ -245,18 +247,51 @@ async function runPiAdapter(options) {
         : await runOnHost(options, args);
     return attachPiOutput(raw);
 }
-async function runOnHost(options, args) {
-    // Isolated agent dir so the generated provider config never touches (or
-    // reads) an operator's ~/.pi configuration/credentials.
+async function runOnHost(options, args, local = false) {
+    // Hosted sessions never read operator auth; BYO sessions copy only provider
+    // config and credentials. Both paths clean up their isolated agent directory.
     const agentDir = await node_fs_1.promises.mkdtemp(node_path_1.default.join(node_os_1.default.tmpdir(), "navarch-pi-agent-"));
-    await node_fs_1.promises.writeFile(node_path_1.default.join(agentDir, "models.json"), buildPiProviderConfig(), { mode: 0o600 });
-    const budgetExtensionPath = node_path_1.default.join(agentDir, BUDGET_EXTENSION_NAME);
-    await node_fs_1.promises.writeFile(budgetExtensionPath, buildHostedPiBudgetExtension(), {
-        mode: 0o600,
-    });
-    const env = { ...options.env, PI_CODING_AGENT_DIR: agentDir };
-    const boundedArgs = withBudgetExtension(args, budgetExtensionPath);
     try {
+        if (local) {
+            const sourceDir = options.env.PI_CODING_AGENT_DIR ?? process.env.PI_CODING_AGENT_DIR ?? node_path_1.default.join(node_os_1.default.homedir(), ".pi", "agent");
+            for (const name of ["models.json", "auth.json"]) {
+                try {
+                    await node_fs_1.promises.copyFile(node_path_1.default.join(sourceDir, name), node_path_1.default.join(agentDir, name));
+                    await node_fs_1.promises.chmod(node_path_1.default.join(agentDir, name), 0o600);
+                }
+                catch (error) {
+                    if (error.code !== "ENOENT")
+                        throw error;
+                }
+            }
+            const model = options.model ?? "qwen3.8-flash-next-iq2_xs";
+            if (!model.includes("/")) {
+                const configPath = node_path_1.default.join(agentDir, "models.json");
+                const config = JSON.parse(await node_fs_1.promises.readFile(configPath, "utf8").catch(() => "{}"));
+                config.providers ??= {};
+                // Explicit provider/model references use the machine's catalog unchanged.
+                config.providers.local = {
+                    baseUrl: options.env.NAVARCH_PI_LOCAL_BASE_URL ?? process.env.NAVARCH_PI_LOCAL_BASE_URL ?? "http://127.0.0.1:8080/v1",
+                    api: "openai-completions", apiKey: "local",
+                    models: [{ id: model, reasoning: false, input: ["text"], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 } }],
+                };
+                await node_fs_1.promises.writeFile(configPath, JSON.stringify(config), { mode: 0o600 });
+            }
+            if (options.mcpConfigPath) {
+                await node_fs_1.promises.copyFile(options.mcpConfigPath, node_path_1.default.join(agentDir, "mcp.json"));
+                await node_fs_1.promises.chmod(node_path_1.default.join(agentDir, "mcp.json"), 0o600);
+            }
+        }
+        else {
+            await node_fs_1.promises.writeFile(node_path_1.default.join(agentDir, "models.json"), buildPiProviderConfig(), { mode: 0o600 });
+        }
+        const budgetExtensionPath = node_path_1.default.join(agentDir, BUDGET_EXTENSION_NAME);
+        if (!local)
+            await node_fs_1.promises.writeFile(budgetExtensionPath, buildHostedPiBudgetExtension(), {
+                mode: 0o600,
+            });
+        const env = { ...options.env, PI_CODING_AGENT_DIR: agentDir };
+        const boundedArgs = local ? args : withBudgetExtension(args, budgetExtensionPath);
         return await new Promise((resolve) => {
             let stdout = "";
             let stderr = "";

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

@@ -25,6 +25,7 @@ exports.RUNTIME_AGENT_TYPES = [
     "opencode",
     "acp",
     "qoder",
+    "pi-local",
 ];
 function isRuntimeAgentType(value) {
     return typeof value === "string" && exports.RUNTIME_AGENT_TYPES.includes(value);
@@ -105,7 +106,12 @@ function loadRuntimeConfig(env = process.env) {
     // fails closed there (adapters/opencode.cts). Advertising it anyway meant
     // the machine claimed OpenCode tasks it could only fail, one lease at a
     // time; keep it out of the claim instead of discovering this per session.
-    const runnableRuntimes = requestedRuntimes.filter((runtime) => runtime !== "opencode" || !opencodeBlockedOnHost(sandboxMode, worktreeGuard));
+    const runnableRuntimes = requestedRuntimes.filter((runtime) => runtime === "pi-local"
+        ? sandboxMode === "host" && !worktreeGuard
+        : runtime !== "opencode" || !opencodeBlockedOnHost(sandboxMode, worktreeGuard));
+    if (requestedRuntimes.includes("pi-local") && runnableRuntimes.length === 0) {
+        throw new Error("Pi (local) requires NAVARCH_SANDBOX_MODE=host and NAVARCH_WORKTREE_GUARD=off");
+    }
     if (requestedRuntimes.includes("opencode") && runnableRuntimes.length === 0) {
         throw new Error(exports.OPENCODE_HOST_GUARD_MESSAGE);
     }
@@ -143,6 +149,8 @@ function loadRuntimeConfig(env = process.env) {
         opencodeExtraArgs: envList(env, "NAVARCH_OPENCODE_EXTRA_ARGS", []),
         acpBin: env.NAVARCH_ACP_BIN ?? "dsh",
         acpExtraArgs: envList(env, "NAVARCH_ACP_EXTRA_ARGS", ["--profile", "acp"]),
+        piBin: env.NAVARCH_PI_BIN ?? "pi",
+        piExtraArgs: envList(env, "NAVARCH_PI_EXTRA_ARGS", []),
         qoderBin: env.NAVARCH_QODER_BIN ?? "qoder",
         qoderExtraArgs: envList(env, "NAVARCH_QODER_EXTRA_ARGS", []),
         gitAuthorName: env.NAVARCH_GIT_AUTHOR_NAME ?? "sagentlab",
@@ -169,6 +177,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/dist/session.cjs

@@ -46,9 +46,10 @@ function resolveSessionExecution(config, claimed) {
     const execution = claimed.context_bundle.execution ?? {
         profile: claimed.task.execution_profile ?? "standard",
         model: runtime === "codex" ? "gpt-6-astra"
-            : runtime === "gemini" ? "auto"
-                : runtime === "opencode" || runtime === "acp" || runtime === "qoder" ? "default"
-                    : "claude-opus-5-5",
+            : runtime === "pi-local" ? "qwen3.8-flash-next-iq2_xs"
+                : runtime === "gemini" ? "auto"
+                    : runtime === "opencode" || runtime === "acp" || runtime === "qoder" ? "default"
+                        : "claude-opus-5-5",
         reasoning_effort: "medium",
     };
     return {
@@ -865,6 +866,8 @@ function adapterCommand(config, runtime) {
             return { bin: config.opencodeBin, extraArgs: config.opencodeExtraArgs };
         case "acp":
             return { bin: config.acpBin, extraArgs: config.acpExtraArgs };
+        case "pi-local":
+            return { bin: config.piBin, extraArgs: config.piExtraArgs };
         case "qoder":
             return { bin: config.qoderBin, extraArgs: config.qoderExtraArgs };
     }

package/package.json

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