toolroll 0.9.68 → 0.9.70

package/dist/scope.js

@@ -41,6 +41,8 @@ export { isAcpProfile };
 import { createHash, randomBytes, scryptSync, timingSafeEqual } from "node:crypto";
 import { networkFromValue, networkWords } from "./egress.js";
 import { isWritesMode, writesWords } from "./writes-mode.js";
+import { checkAccessWords, isCheckAccess } from "./check-access.js";
+import { MAX_MACH_LOOKUP, MAX_READ_DENY, sandboxTermsWords, validMachLookup, validReadDeny } from "./project-sandbox.js";
 import { z } from "zod";
 import {} from "./contracts/acceptance-terms.js";
 import { parseContract } from "./contracts/contract.js";
@@ -354,9 +356,31 @@ export function profileFromJson(json) {
     const writes = p["writes"];
     if (writes !== undefined && !isWritesMode(writes))
         return null;
-    const withNetwork = { ...(network === undefined ? {} : { network }), ...(writes === undefined ? {} : { writes }) };
+    // Check access is sealed only when wider than sandboxed: an explicit "sandboxed", or any other word, is not this code's.
+    const sealedAccess = p["checkAccess"];
+    if (sealedAccess !== undefined && (sealedAccess === "sandboxed" || !isCheckAccess(sealedAccess)))
+        return null;
+    const checkAccess = sealedAccess;
+    // Sandbox parity (v133): the policy version is exactly 2 when present; the lists, when present, are non-empty, sorted,
+    // distinct and valid (project-sandbox.ts), as only this code writes them.
+    const policy = p["fencePolicy"];
+    if (policy !== undefined && policy !== 2)
+        return null;
+    const sealedList = (key, valid, max) => {
+        const list = p[key];
+        if (list === undefined)
+            return undefined;
+        return Array.isArray(list) && list.length > 0 && list.length <= max && list.every(one => typeof one === "string" && valid(one))
+            && list.every((one, at) => at === 0 || list[at - 1] < one) ? [...list] : null;
+    };
+    const readDeny = sealedList("readDeny", validReadDeny, MAX_READ_DENY);
+    const machLookup = sealedList("machLookup", validMachLookup, MAX_MACH_LOOKUP);
+    if (readDeny === null || machLookup === null)
+        return null;
+    const withNetwork = { ...(network === undefined ? {} : { network }), ...(writes === undefined ? {} : { writes }), ...(checkAccess === undefined ? {} : { checkAccess }),
+        ...(policy === undefined ? {} : { fencePolicy: 2 }), ...(readDeny === undefined ? {} : { readDeny }), ...(machLookup === undefined ? {} : { machLookup }) };
     if (p["provider"] === "claude") {
-        if (exactKeys(p, [...PROVIDER_KEYS, "permissionArgv"], ["timeoutKind", "network", "writes"]) &&
+        if (exactKeys(p, [...PROVIDER_KEYS, "permissionArgv"], ["timeoutKind", "network", "writes", "checkAccess", "fencePolicy", "readDeny", "machLookup"]) &&
             str(p["model"]) &&
             (p["permissionArgv"] === "auto" || p["permissionArgv"] === "acceptEdits" || p["permissionArgv"] === "bypassPermissions") &&
             num(p["maxTurns"]) && num(p["repairMaxTurns"]) &&
@@ -378,7 +402,7 @@ export function profileFromJson(json) {
         return null;
     }
     if (p["provider"] === "codex" || p["provider"] === "openrouter") {
-        if (exactKeys(p, [...PROVIDER_KEYS, "sandboxMode"], ["timeoutKind", "network", "writes"]) &&
+        if (exactKeys(p, [...PROVIDER_KEYS, "sandboxMode"], ["timeoutKind", "network", "writes", "checkAccess", "fencePolicy", "readDeny", "machLookup"]) &&
             str(p["model"]) &&
             (p["sandboxMode"] === "workspace-write" || p["sandboxMode"] === "danger-full-access") &&
             p["maxTurns"] === "unsupported" && p["repairMaxTurns"] === "unsupported" &&
@@ -400,7 +424,7 @@ export function profileFromJson(json) {
         return null;
     }
     if (p["provider"] === "gemini") {
-        if (exactKeys(p, [...PROVIDER_KEYS, "approvalArgv"], ["timeoutKind", "network", "writes"]) &&
+        if (exactKeys(p, [...PROVIDER_KEYS, "approvalArgv"], ["timeoutKind", "network", "writes", "checkAccess", "fencePolicy", "readDeny", "machLookup"]) &&
             str(p["model"]) &&
             (p["approvalArgv"] === "auto_edit" || p["approvalArgv"] === "yolo") &&
             p["maxTurns"] === "unsupported" && p["repairMaxTurns"] === "unsupported" &&
@@ -422,7 +446,7 @@ export function profileFromJson(json) {
         return null;
     }
     if (typeof p["provider"] === "string" && isAcpProvider(p["provider"])) {
-        if (exactKeys(p, [...PROVIDER_KEYS, "permission", "idleTimeoutSeconds", "repairIdleTimeoutSeconds"], ["network", "writes"]) &&
+        if (exactKeys(p, [...PROVIDER_KEYS, "permission", "idleTimeoutSeconds", "repairIdleTimeoutSeconds"], ["network", "writes", "checkAccess", "fencePolicy", "readDeny", "machLookup"]) &&
             str(p["model"]) &&
             p["permission"] === "full" &&
             p["maxTurns"] === "unsupported" && p["repairMaxTurns"] === "unsupported" &&
@@ -1271,6 +1295,9 @@ export function describeScope(scope, readiness = NO_READINESS) {
         // What the build may reach (egress.ts), part of what the yes agrees to.
         ...(scope.profile === null || scope.profile === undefined ? [] : [`  network      ${networkWords(scope.profile.network ?? null).replace(/^Network: /, "")}`]),
         ...(scope.profile === null || scope.profile === undefined ? [] : [`  writes       ${writesWords(scope.profile.writes)}`]),
+        ...(scope.profile?.checkAccess === undefined ? [] : [`  checks       ${checkAccessWords(scope.profile.checkAccess)}`]),
+        // Its sandbox terms (project-sandbox.ts), part of what the yes agrees to: what it reads, and any widening.
+        ...(scope.profile === null || scope.profile === undefined ? [] : ((terms) => [`  reads        ${terms.reads}`, ...(terms.mach === null ? [] : [`  services     ${terms.mach}`])])(sandboxTermsWords(scope.profile))),
         `  reference    ${scope.digest}`,
         `  approved     ${describeApproval(approval)}`,
     ];

package/dist/scout-browser-lock.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The scout browser helper's pinned install (scout-browser.ts ensureScoutBrowserHelper): its manifest and lockfile,
+ * generated once with `npm install --package-lock-only --registry https://registry.npmjs.org/` for @playwright/mcp
+ * 0.0.82. `npm ci` installs exactly this tree and refuses any tarball whose sha512 differs. Changing a version here is
+ * a supply-chain change: regenerate both and review the diff.
+ */
+export declare const SCOUT_BROWSER_MANIFEST: {
+    readonly name: "toolroll-scout-browser";
+    readonly private: true;
+    readonly dependencies: {
+        readonly "@playwright/mcp": "0.0.82";
+    };
+};
+export declare const SCOUT_BROWSER_LOCK: {
+    readonly name: "toolroll-scout-browser";
+    readonly lockfileVersion: 3;
+    readonly requires: true;
+    readonly packages: {
+        readonly "": {
+            readonly name: "toolroll-scout-browser";
+            readonly dependencies: {
+                readonly "@playwright/mcp": "0.0.82";
+            };
+        };
+        readonly "node_modules/@playwright/mcp": {
+            readonly version: "0.0.82";
+            readonly resolved: "https://registry.npmjs.org/@playwright/mcp/-/mcp-0.0.82.tgz";
+            readonly integrity: "sha512-OCqftfb8H4dnqm/njbTBRk3seUvUPttOlJUxCtEzXGETYOlRH5Qt3bbXIjmZIuWAxD9RF+yg1ASrPeXvm0y5cA==";
+            readonly license: "Apache-2.0";
+            readonly dependencies: {
+                readonly playwright: "1.64.0-alpha-1789764292000";
+                readonly "playwright-core": "1.64.0-alpha-1789764292000";
+            };
+            readonly bin: {
+                readonly "playwright-mcp": "cli.js";
+            };
+            readonly engines: {
+                readonly node: ">=18";
+            };
+        };
+        readonly "node_modules/playwright": {
+            readonly version: "1.64.0-alpha-1789764292000";
+            readonly resolved: "https://registry.npmjs.org/playwright/-/playwright-1.64.0-alpha-1789764292000.tgz";
+            readonly integrity: "sha512-3Ngs4ERGdC912uW3srEDtNVey4u1wSaQ/EFcKhxMpz0by0K6nidaJgM087pLpJc1osytiVnL7ack5gvgPArPNw==";
+            readonly license: "Apache-2.0";
+            readonly dependencies: {
+                readonly "playwright-core": "1.64.0-alpha-1789764292000";
+            };
+            readonly bin: {
+                readonly playwright: "cli.js";
+            };
+            readonly engines: {
+                readonly node: ">=20";
+            };
+        };
+        readonly "node_modules/playwright-core": {
+            readonly version: "1.64.0-alpha-1789764292000";
+            readonly resolved: "https://registry.npmjs.org/playwright-core/-/playwright-core-1.64.0-alpha-1789764292000.tgz";
+            readonly integrity: "sha512-ZgRaybFv4rRy7QMGnYprEGFdNJnvapNqcaER2w96bDQA+40BWIle1el1Yh9KHD3E6XYmieMB+r+UxFTCauTGGQ==";
+            readonly license: "Apache-2.0";
+            readonly bin: {
+                readonly "playwright-core": "cli.js";
+            };
+            readonly engines: {
+                readonly node: ">=20";
+            };
+        };
+    };
+};

package/dist/scout-browser-lock.js

@@ -0,0 +1,69 @@
+/**
+ * The scout browser helper's pinned install (scout-browser.ts ensureScoutBrowserHelper): its manifest and lockfile,
+ * generated once with `npm install --package-lock-only --registry https://registry.npmjs.org/` for @playwright/mcp
+ * 0.0.82. `npm ci` installs exactly this tree and refuses any tarball whose sha512 differs. Changing a version here is
+ * a supply-chain change: regenerate both and review the diff.
+ */
+export const SCOUT_BROWSER_MANIFEST = {
+    "name": "toolroll-scout-browser",
+    "private": true,
+    "dependencies": {
+        "@playwright/mcp": "0.0.82"
+    }
+};
+export const SCOUT_BROWSER_LOCK = {
+    "name": "toolroll-scout-browser",
+    "lockfileVersion": 3,
+    "requires": true,
+    "packages": {
+        "": {
+            "name": "toolroll-scout-browser",
+            "dependencies": {
+                "@playwright/mcp": "0.0.82"
+            }
+        },
+        "node_modules/@playwright/mcp": {
+            "version": "0.0.82",
+            "resolved": "https://registry.npmjs.org/@playwright/mcp/-/mcp-0.0.82.tgz",
+            "integrity": "sha512-OCqftfb8H4dnqm/njbTBRk3seUvUPttOlJUxCtEzXGETYOlRH5Qt3bbXIjmZIuWAxD9RF+yg1ASrPeXvm0y5cA==",
+            "license": "Apache-2.0",
+            "dependencies": {
+                "playwright": "1.64.0-alpha-1789764292000",
+                "playwright-core": "1.64.0-alpha-1789764292000"
+            },
+            "bin": {
+                "playwright-mcp": "cli.js"
+            },
+            "engines": {
+                "node": ">=18"
+            }
+        },
+        "node_modules/playwright": {
+            "version": "1.64.0-alpha-1789764292000",
+            "resolved": "https://registry.npmjs.org/playwright/-/playwright-1.64.0-alpha-1789764292000.tgz",
+            "integrity": "sha512-3Ngs4ERGdC912uW3srEDtNVey4u1wSaQ/EFcKhxMpz0by0K6nidaJgM087pLpJc1osytiVnL7ack5gvgPArPNw==",
+            "license": "Apache-2.0",
+            "dependencies": {
+                "playwright-core": "1.64.0-alpha-1789764292000"
+            },
+            "bin": {
+                "playwright": "cli.js"
+            },
+            "engines": {
+                "node": ">=20"
+            }
+        },
+        "node_modules/playwright-core": {
+            "version": "1.64.0-alpha-1789764292000",
+            "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.64.0-alpha-1789764292000.tgz",
+            "integrity": "sha512-ZgRaybFv4rRy7QMGnYprEGFdNJnvapNqcaER2w96bDQA+40BWIle1el1Yh9KHD3E6XYmieMB+r+UxFTCauTGGQ==",
+            "license": "Apache-2.0",
+            "bin": {
+                "playwright-core": "cli.js"
+            },
+            "engines": {
+                "node": ">=20"
+            }
+        }
+    }
+};

package/dist/scout-browser.d.ts

@@ -17,6 +17,12 @@ export type BrowserStarter = (launch: BrowserLaunch, options: BrowserOptions) =>
 export type BrowserOptions = {
     /** The browser tool's environment: the scout's own, its proxy settings included. */
     env: Record<string, string | undefined>;
+    /** Toolroll's helpers folder (in its state folder) the pinned browser is installed in, and the scout's proxy: the
+     * launch contract's trusted inputs, from the plane, never from the launch. */
+    contract?: {
+        helpers: string;
+        proxy: string;
+    };
     /** Where it saves screenshots (its `--output-dir`), also its working folder. */
     folder: string;
     /** The whole start and check, from spawn to screenshot (review 828: at most 60 seconds). */
@@ -24,7 +30,8 @@ export type BrowserOptions = {
 };
 /** The public page the check opens through the scout's proxy. */
 export declare const PREFLIGHT_PAGE = "https://example.com/";
-/** How a scout gets its browser: started for real, or, for a test's stub agent, a placeholder that starts nothing. */
+/** How a scout gets its browser: started for real under its launch contract, or, for a test's stub agent, a placeholder
+ * that starts nothing. */
 export declare function starterFor(agentInjected: boolean): BrowserStarter;
 /** Start the browser tool outside the fence and check it opens a public page and saves a screenshot. */
 export declare function startScoutBrowser(launch: BrowserLaunch, options: BrowserOptions): Promise<BrowserStart>;
@@ -46,3 +53,55 @@ export type McpSession = {
 };
 /** A client of the browser's HTTP transport, as the scout's own is: every step answers by `deadline`, or says why not. */
 export declare function openSession(url: string, deadline: number, late: string): McpSession;
+/** The pinned browser tool, installed once into Toolroll's helpers folder. */
+export declare const SCOUT_BROWSER_PACKAGE = "@playwright/mcp@0.0.82";
+/** The names of the worker's environment the browser tool gets: an allowlist, never a denylist. */
+export declare const SCOUT_BROWSER_ENV: readonly string[];
+/** What the run records of the exception it ran under. */
+export declare const SCOUT_BROWSER_CONTAINMENT = "Chrome's sandbox";
+/** Where the pinned browser lives under `helpers`. */
+export declare function scoutBrowserHelper(helpers: string): {
+    folder: string;
+    cli: string;
+    browsers: string;
+};
+/** The scout's browser tool: the pinned helper, run by Toolroll's own Node, headless, on its bundled Chrome. */
+export declare function scoutBrowserTool(helpers: string): BrowserLaunch;
+/**
+ * Why a browser launch breaks its contract, or null when it holds. Every input it trusts is the plane's: the helpers
+ * folder and the proxy come from `options.contract`, never from the launch. The executable must be Toolroll's own
+ * Node; the script the pinned helper's, inside a private helpers folder; the arguments exactly the expected ones (no
+ * way to switch Chrome's sandbox off, point at another browser or executable, or drop the proxy); the working folder
+ * the image folder; the environment only allowlisted names.
+ */
+export declare function browserContractProblem(launch: BrowserLaunch, options: BrowserOptions): string | null;
+/** The pinned lockfile's digest, recorded when the helper is installed and checked before every use. */
+export declare const SCOUT_BROWSER_LOCK_DIGEST: string;
+/** The npm of the Node running Toolroll (`lib/node_modules/npm/bin/npm-cli.js` beside it), run by that Node by path:
+ * never an `npm` found on PATH. Null where this Node has none beside it (a bundled runtime). */
+export declare function ownNpm(execPath?: string): string | null;
+/**
+ * Install the pinned browser into the helpers folder once. The worker runs this outside every fence, so nothing a build
+ * could have written may steer it: npm is Toolroll's own Node's, run by path; HOME is the staging folder and the user
+ * and global npm configurations are an empty file there (no ~/.npmrc, no global npmrc, no registry, script or Node
+ * option from either); the registry is pinned; install scripts never run; `npm ci` installs exactly the pinned lockfile
+ * (scout-browser-lock.ts) and refuses a tarball whose integrity differs; the installed versions are checked against it
+ * before ready.json is written. The npm cache and Chrome for Testing stay in the folder, never in the user's caches.
+ * Residual: Chrome for Testing comes from Playwright's own download over HTTPS, without a pinned hash.
+ */
+export declare function ensureScoutBrowserHelper(helpers: string, timeoutMs?: number): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+}>;
+/** How the helper's npm runs in `staging`: Toolroll's own npm by path, with its home, user and global configuration
+ * the staging folder's own empty ones, the registry and cache pinned; the environment only these names. */
+export declare function helperNpm(staging: string, npm: string): {
+    env: Record<string, string>;
+    args: string[];
+};
+/** What of an installed tree differs from the pinned lockfile (a package missing or at another version), or null. */
+export declare function lockDrift(folder: string): string | null;
+/** The production starter: the pinned helper in place, then the launch held to its contract, then started. */
+export declare function startContractedBrowser(launch: BrowserLaunch, options: BrowserOptions): Promise<BrowserStart>;

package/dist/scout-browser.js

@@ -10,21 +10,32 @@
  *
  * Playwright MCP 0.0.82 has no per-client token for its HTTP transport; it answers only on 127.0.0.1, only for
  * that host name (its own host check), and only while this run's scout does.
+ *
+ * An explicit exception (docs/plans/sandbox-parity.md C4, owner Q-A): Toolroll can't fence this process without
+ * switching Chrome's sandbox off, so its launch is held to a contract instead, and refused when any part fails
+ * (`browserContractProblem`): the pinned Playwright MCP and its Chrome for Testing are installed in Toolroll's own
+ * helpers folder (inside the state folder every build's fence denies) and run by Toolroll's own Node; its arguments are
+ * exactly the expected ones (Chrome's sandbox on, the scout's proxy on, its image folder as its output and working
+ * folder); its environment is an allowlist. The run records which exception it ran under.
  */
 import { spawn } from "node:child_process";
 import { request as httpRequest } from "node:http";
 import { connect, createServer } from "node:net";
-import { readdirSync, rmSync } from "node:fs";
-import { join } from "node:path";
+import { createHash } from "node:crypto";
+import { lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, isAbsolute } from "node:path";
+import { run } from "./exec.js";
+import { SCOUT_BROWSER_LOCK, SCOUT_BROWSER_MANIFEST } from "./scout-browser-lock.js";
 import { sleep } from "./sleep.js";
 /** The public page the check opens through the scout's proxy. */
 export const PREFLIGHT_PAGE = "https://example.com/";
 const PREFLIGHT_TIMEOUT_MS = 60_000;
 const CLOSE_GRACE_MS = 5_000;
 const IMAGE = /\.(png|jpe?g)$/i;
-/** How a scout gets its browser: started for real, or, for a test's stub agent, a placeholder that starts nothing. */
+/** How a scout gets its browser: started for real under its launch contract, or, for a test's stub agent, a placeholder
+ * that starts nothing. */
 export function starterFor(agentInjected) {
-    return agentInjected ? unstarted : startScoutBrowser;
+    return agentInjected ? unstarted : startContractedBrowser;
 }
 const unstarted = async () => ({ ok: true, server: { url: "http://127.0.0.1:9/mcp", close: async () => undefined } });
 /** Start the browser tool outside the fence and check it opens a public page and saves a screenshot. */
@@ -227,3 +238,188 @@ function oneLine(text) {
     // eslint-disable-next-line no-control-regex
     return text.replace(/[\u0000-\u001f\u007f-\u009f]+/g, " ").trim().slice(0, 200);
 }
+// ---- the launch contract (docs/plans/sandbox-parity.md C4) ----
+/** The pinned browser tool, installed once into Toolroll's helpers folder. */
+export const SCOUT_BROWSER_PACKAGE = "@playwright/mcp@0.0.82";
+const HELPER_NAME = "scout-browser-0.0.82";
+/** The names of the worker's environment the browser tool gets: an allowlist, never a denylist. */
+export const SCOUT_BROWSER_ENV = ["PATH", "HOME", "USER", "LOGNAME", "LANG", "LC_ALL", "LC_CTYPE", "TZ", "TMPDIR",
+    "HTTP_PROXY", "HTTPS_PROXY", "http_proxy", "https_proxy"];
+/** What the run records of the exception it ran under. */
+export const SCOUT_BROWSER_CONTAINMENT = "Chrome's sandbox";
+/** Where the pinned browser lives under `helpers`. */
+export function scoutBrowserHelper(helpers) {
+    const folder = join(helpers, HELPER_NAME);
+    return { folder, cli: join(folder, "node_modules", "@playwright", "mcp", "cli.js"), browsers: join(folder, "browsers") };
+}
+/** The scout's browser tool: the pinned helper, run by Toolroll's own Node, headless, on its bundled Chrome. */
+export function scoutBrowserTool(helpers) {
+    return { command: process.execPath, args: [scoutBrowserHelper(helpers).cli, "--headless", "--browser", "chromium"] };
+}
+/** A folder of Toolroll's own: a real folder (no link at it), this user's, private (0700). */
+function privateFolder(path) {
+    try {
+        const held = lstatSync(path);
+        return held.isDirectory() && !held.isSymbolicLink() && (process.getuid === undefined || held.uid === process.getuid()) && (held.mode & 0o077) === 0;
+    }
+    catch {
+        return false;
+    }
+}
+const within = (child, parent) => { const rel = relative(parent, child); return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel); };
+/**
+ * Why a browser launch breaks its contract, or null when it holds. Every input it trusts is the plane's: the helpers
+ * folder and the proxy come from `options.contract`, never from the launch. The executable must be Toolroll's own
+ * Node; the script the pinned helper's, inside a private helpers folder; the arguments exactly the expected ones (no
+ * way to switch Chrome's sandbox off, point at another browser or executable, or drop the proxy); the working folder
+ * the image folder; the environment only allowlisted names.
+ */
+export function browserContractProblem(launch, options) {
+    const contract = options.contract;
+    if (contract === undefined)
+        return "the browser has no launch contract";
+    const real = (path) => { try {
+        return realpathSync(path);
+    }
+    catch {
+        return null;
+    } };
+    if (real(launch.command) === null || real(launch.command) !== real(process.execPath))
+        return "the browser isn't run by Toolroll's own Node";
+    if (!privateFolder(contract.helpers))
+        return "Toolroll's helpers folder isn't a private folder of its own";
+    const helper = scoutBrowserHelper(contract.helpers);
+    const script = launch.args[0] === undefined ? null : real(launch.args[0]);
+    const helpers = real(contract.helpers);
+    if (script === null || helpers === null || !within(script, helpers) || script !== real(helper.cli))
+        return "the browser tool isn't the pinned one in Toolroll's helpers folder";
+    const expected = [launch.args[0], "--headless", "--browser", "chromium", "--isolated", "--output-dir", options.folder, "--proxy-server", contract.proxy, "--proxy-bypass", "<-loopback>"];
+    if (launch.args.length !== expected.length || launch.args.some((one, index) => one !== expected[index]))
+        return "the browser's arguments aren't the contract's (Chrome's sandbox and the scout's proxy stay on)";
+    const extra = Object.keys(options.env).filter(name => options.env[name] !== undefined && !SCOUT_BROWSER_ENV.includes(name));
+    if (extra.length > 0)
+        return `the browser's environment carries names outside its allowlist (${extra.slice(0, 5).join(", ")})`;
+    if (options.env["HTTPS_PROXY"] !== contract.proxy || options.env["HTTP_PROXY"] !== contract.proxy)
+        return "the browser's environment doesn't point at the scout's proxy";
+    return null;
+}
+/** The registry the helper is installed from: pinned, whatever any npm configuration says. */
+const NPM_REGISTRY = "https://registry.npmjs.org/";
+const sha256 = (text) => createHash("sha256").update(text).digest("hex");
+/** The pinned lockfile's digest, recorded when the helper is installed and checked before every use. */
+export const SCOUT_BROWSER_LOCK_DIGEST = sha256(JSON.stringify(SCOUT_BROWSER_LOCK));
+/** The npm of the Node running Toolroll (`lib/node_modules/npm/bin/npm-cli.js` beside it), run by that Node by path:
+ * never an `npm` found on PATH. Null where this Node has none beside it (a bundled runtime). */
+export function ownNpm(execPath = process.execPath) {
+    const cli = join(dirname(dirname(execPath)), "lib", "node_modules", "npm", "bin", "npm-cli.js");
+    try {
+        return realpathSync(cli);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Install the pinned browser into the helpers folder once. The worker runs this outside every fence, so nothing a build
+ * could have written may steer it: npm is Toolroll's own Node's, run by path; HOME is the staging folder and the user
+ * and global npm configurations are an empty file there (no ~/.npmrc, no global npmrc, no registry, script or Node
+ * option from either); the registry is pinned; install scripts never run; `npm ci` installs exactly the pinned lockfile
+ * (scout-browser-lock.ts) and refuses a tarball whose integrity differs; the installed versions are checked against it
+ * before ready.json is written. The npm cache and Chrome for Testing stay in the folder, never in the user's caches.
+ * Residual: Chrome for Testing comes from Playwright's own download over HTTPS, without a pinned hash.
+ */
+export async function ensureScoutBrowserHelper(helpers, timeoutMs = 600_000) {
+    const helper = scoutBrowserHelper(helpers);
+    if (helperReady(helper.folder))
+        return { ok: true };
+    const npm = ownNpm();
+    if (npm === null)
+        return { ok: false, reason: "Toolroll's own Node has no npm beside it, so the pinned browser can't be installed" };
+    try {
+        mkdirSync(helpers, { recursive: true, mode: 0o700 });
+    }
+    catch { /* checked next */ }
+    if (!privateFolder(helpers))
+        return { ok: false, reason: "Toolroll's helpers folder isn't a private folder of its own" };
+    const staging = mkdtempSync(join(helpers, ".install-"));
+    try {
+        writeFileSync(join(staging, "package.json"), JSON.stringify(SCOUT_BROWSER_MANIFEST), { mode: 0o600 });
+        writeFileSync(join(staging, "package-lock.json"), JSON.stringify(SCOUT_BROWSER_LOCK), { mode: 0o600 });
+        const { env, args } = helperNpm(staging, npm);
+        const installed = await run(process.execPath, [...args, "ci", "--ignore-scripts", "--no-audit", "--no-fund"], { cwd: staging, env, envAllowlist: [], timeoutMs });
+        if (installed.code !== 0)
+            return { ok: false, reason: `the pinned browser couldn't be installed (npm exit ${installed.code})` };
+        const drift = lockDrift(staging);
+        if (drift !== null)
+            return { ok: false, reason: `the installed browser isn't the pinned one (${drift})` };
+        const browsers = await run(process.execPath, [join(staging, "node_modules", "playwright", "cli.js"), "install", "chromium"], { cwd: staging, env, envAllowlist: [], timeoutMs });
+        if (browsers.code !== 0)
+            return { ok: false, reason: `the pinned browser's Chrome couldn't be installed (exit ${browsers.code})` };
+        rmSync(join(staging, "npm-cache"), { recursive: true, force: true });
+        writeFileSync(join(staging, "ready.json"), JSON.stringify({ package: SCOUT_BROWSER_PACKAGE, lock: SCOUT_BROWSER_LOCK_DIGEST }), { mode: 0o600 });
+        try {
+            renameSync(staging, helper.folder);
+        }
+        catch {
+            if (!helperReady(helper.folder))
+                return { ok: false, reason: "the pinned browser couldn't be put in place" };
+        }
+        return { ok: true };
+    }
+    finally {
+        rmSync(staging, { recursive: true, force: true });
+    }
+}
+/** How the helper's npm runs in `staging`: Toolroll's own npm by path, with its home, user and global configuration
+ * the staging folder's own empty ones, the registry and cache pinned; the environment only these names. */
+export function helperNpm(staging, npm) {
+    // Two empty files: npm refuses to load one file as both.
+    const user = join(staging, "user.npmrc"), global = join(staging, "global.npmrc");
+    for (const file of [user, global])
+        writeFileSync(file, "", { mode: 0o600 });
+    const env = {
+        PATH: [dirname(process.execPath), "/usr/bin", "/bin"].join(":"), HOME: staging, PLAYWRIGHT_BROWSERS_PATH: join(staging, "browsers"),
+        NPM_CONFIG_USERCONFIG: user, NPM_CONFIG_GLOBALCONFIG: global, npm_config_userconfig: user, npm_config_globalconfig: global,
+    };
+    return { env, args: [npm, "--no-update-notifier", `--registry=${NPM_REGISTRY}`, "--userconfig", user, "--globalconfig", global, "--cache", join(staging, "npm-cache")] };
+}
+/** Whether a helper folder holds the pinned install: its ready note names this lockfile, and its tree still matches. */
+function helperReady(folder) {
+    try {
+        const ready = JSON.parse(readFileSync(join(folder, "ready.json"), "utf8"));
+        return ready.lock === SCOUT_BROWSER_LOCK_DIGEST && lockDrift(folder) === null;
+    }
+    catch {
+        return false;
+    }
+}
+/** What of an installed tree differs from the pinned lockfile (a package missing or at another version), or null. */
+export function lockDrift(folder) {
+    for (const [path, entry] of Object.entries(SCOUT_BROWSER_LOCK.packages)) {
+        if (path === "" || entry.version === undefined)
+            continue;
+        let version;
+        try {
+            version = JSON.parse(readFileSync(join(folder, path, "package.json"), "utf8")).version;
+        }
+        catch {
+            version = undefined;
+        }
+        if (version !== entry.version)
+            return `${path.replace(/^node_modules\//, "")} is ${typeof version === "string" ? version : "missing"}, pinned ${entry.version}`;
+    }
+    return null;
+}
+/** The production starter: the pinned helper in place, then the launch held to its contract, then started. */
+export async function startContractedBrowser(launch, options) {
+    if (options.contract === undefined)
+        return { ok: false, reason: "the browser has no launch contract" };
+    const installed = await ensureScoutBrowserHelper(options.contract.helpers);
+    if (!installed.ok)
+        return installed;
+    const env = { ...options.env, PLAYWRIGHT_BROWSERS_PATH: scoutBrowserHelper(options.contract.helpers).browsers };
+    const problem = browserContractProblem(launch, { ...options, env: options.env });
+    if (problem !== null)
+        return { ok: false, reason: problem };
+    return startScoutBrowser(launch, { ...options, env });
+}

package/dist/scout.d.ts

@@ -3,7 +3,6 @@ import type { Store } from "./store.js";
 import { type ParsedDecision, type Problem } from "./decision.js";
 import { type ParsedReport, type ReportProblem } from "./scout-report.js";
 import type { Runner } from "./builder.js";
-import { type ToolSpec } from "./project-tools.js";
 import * as browserCheck from "./scout-browser.js";
 /** The scout's own headless browser: the pinned Playwright tool, saving its
  * screenshots straight into the run's image folder. */
@@ -16,7 +15,10 @@ export declare const SCOUT_BROWSER = "toolroll-browser";
  * clean-tree proof.
  */
 export declare const SCOUT_ALLOWED_TOOLS: readonly string[];
-export declare function scoutBrowserLaunch(tool: Pick<ToolSpec, "command" | "args"> | null, imageFolder: string, proxy: string): browserCheck.BrowserLaunch | null;
+export declare function scoutBrowserLaunch(tool: {
+    command: string | null;
+    args: readonly string[];
+} | null, imageFolder: string, proxy: string): browserCheck.BrowserLaunch | null;
 /** What the fenced scout gets: the running browser's loopback address, nothing it could launch itself. */
 export declare function scoutBrowser(url: string): Record<string, unknown>;
 /** The scout's environment while its proxy runs (review 827): web fetch and the provider's own traffic go through
@@ -62,8 +64,11 @@ export type ScoutRequest = {
     outputDir?: string;
     /** The project's own demo or dev server, the one non-public address the scout's browser may open. */
     demoUrl?: string | null;
-    /** The browser to launch; left out, the catalog's Playwright entry. Null runs the scout without one. */
-    browserTool?: Pick<ToolSpec, "command" | "args"> | null;
+    /** The browser to launch; left out, the pinned helper in Toolroll's helpers folder. Null runs the scout without one. */
+    browserTool?: {
+        command: string | null;
+        args: readonly string[];
+    } | null;
 };
 export type ReportArtifact = {
     key: string;

package/dist/scout.js

@@ -16,7 +16,7 @@ import { skillsContext } from "./project-skills.js";
 import { createHash, randomUUID } from "node:crypto";
 import { mkdtempSync, realpathSync, rmSync, unlinkSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
-import { join, relative, isAbsolute } from "node:path";
+import { dirname, join, relative, isAbsolute } from "node:path";
 import { run } from "./exec.js";
 import { auditOf } from "./provider.js";
 import { currentClaim, heartbeat } from "./claim.js";
@@ -32,7 +32,7 @@ import { openLiveLog } from "./live.js";
 import { proveTreeUntouched, snapshotIgnored } from "./tree-proof.js";
 import { redactSecretLines, scanForSecrets } from "./evidence.js";
 import { CLAUDE_LIMITS } from "./scope.js";
-import { catalogTool, projectToolsOf, toolLaunchFor } from "./project-tools.js";
+import { projectToolsOf, toolLaunchFor } from "./project-tools.js";
 import { grantOf, researchToolsOf } from "./mcp-connect.js";
 import { startScoutProxy } from "./scout-net.js";
 import * as browserCheck from "./scout-browser.js";
@@ -312,7 +312,11 @@ async function scoutWith(store, request, outputDir) {
     // Every scout runs behind its public-web-only proxy (reviews 826, 827): its browser, when this install has one,
     // and its web fetch both go through it. A proxy that cannot start leaves the scout without the web, reading only
     // the checkout, never with an unfiltered one.
-    const browserTool = request.browserTool === undefined ? catalogTool("playwright") : request.browserTool;
+    // The pinned browser in Toolroll's helpers folder, run under its launch contract (scout-browser.ts); none where the
+    // plane has no state folder.
+    const database = store.databaseFile();
+    const helpers = database === null || database === "" || database === ":memory:" ? null : join(dirname(realpathSync(database)), "helpers");
+    const browserTool = request.browserTool === undefined ? (helpers === null ? null : browserCheck.scoutBrowserTool(helpers)) : request.browserTool;
     const demoUrl = request.demoUrl ?? null;
     let proxy = null;
     let browserServer = null;
@@ -324,9 +328,11 @@ async function scoutWith(store, request, outputDir) {
         // The preflight (run 2356, review 828): the worker starts the browser outside the fence and opens a public page
         // through the proxy before research begins. One that can't start is said once, in the brief and the report, and
         // the scout researches without it.
+        // Its environment is an allowlist of the worker's, with the scout's proxy (the launch contract).
         const started = launch === null || proxy === null ? null : await browserCheck.starterFor(agent !== undefined)(launch, {
-            env: { ...withoutEnv(process.env, [...AGENT_ENV_DENYLIST, ...PROXY_BYPASS_ENV]), ...scoutProxyEnv(proxy.url) },
+            env: { ...Object.fromEntries(browserCheck.SCOUT_BROWSER_ENV.filter(name => !(name in scoutProxyEnv(proxy.url)) && process.env[name] !== undefined).map(name => [name, process.env[name]])), ...scoutProxyEnv(proxy.url) },
             folder: imageFolder,
+            ...(helpers === null ? {} : { contract: { helpers, proxy: proxy.url } }),
         }).catch((error) => ({ ok: false, reason: error instanceof Error ? error.message : String(error) }));
         if (started !== null && started.ok)
             browserServer = started.server;
@@ -367,6 +373,10 @@ async function scoutWith(store, request, outputDir) {
             clock,
             onStreamEvent: observe,
         });
+        // The run says which exception its browser ran under: Chrome's own sandbox, not Toolroll's fence (recorded after the
+        // gateway, whose tool record would replace it).
+        if (browserServer !== null)
+            store.recordRunBrowser(request.runId, { containment: browserCheck.SCOUT_BROWSER_CONTAINMENT, tool: browserCheck.SCOUT_BROWSER_PACKAGE }, new Date());
     }
     finally {
         if (pulseTimer !== undefined)