toolroll 0.9.69 → 0.9.71

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)

package/dist/serve.js

@@ -16,6 +16,7 @@ import { boundProjectSummary, browserCrewFromIndex, browserCrewOf, browserNaviga
 import { sharedActionPayload } from './chat-actions.js';
 import { prepareCodingContext } from './coding-context.js';
 import { CodingWorkspace } from './coding-workspace.js';
+import { codingSessionPermissions } from './coding-provider.js';
 import { CONSOLE_FORMS, readForm } from "./contracts/console-api.js";
 import { createFlowRooms, flowFingerprint } from "./flow-live.js";
 import {} from "./google-mail.js";
@@ -195,7 +196,7 @@ export function createDecisionServer(options) {
         const database = store.handle.prepare('PRAGMA database_list').all().find(row => row['name'] === 'main')?.['file'];
         if (typeof database === 'string' && database !== '') {
             try {
-                coding = new CodingWorkspace({ database: `${database}.coding.sqlite`, worktreeRoot: join(dirname(database), 'coding-worktrees'), admissionPaused: () => updateAdmissionPaused(store.raw()), authorize: (actor, repo) => codingActorAllowed(actor) && codingProjectAllowed(repo), context: input => prepareCodingContext(store, { ...input, root: join(dirname(database), 'coding-context') }) });
+                coding = new CodingWorkspace({ database: `${database}.coding.sqlite`, worktreeRoot: join(dirname(database), 'coding-worktrees'), permissions: codingSessionPermissions(store, join(dirname(database), 'coding-worktrees')), admissionPaused: () => updateAdmissionPaused(store.raw()), authorize: (actor, repo) => codingActorAllowed(actor) && codingProjectAllowed(repo), context: input => prepareCodingContext(store, { ...input, root: join(dirname(database), 'coding-context') }) });
             }
             catch (error) {
                 codingProblem = error instanceof Error ? error.message : 'The coding workspace could not open.';
@@ -450,6 +451,7 @@ export function createDecisionServer(options) {
         access: projectAccessOf(repo),
         network: { setting: store.projectNetwork(repo), canChange: who.via === "cookie" && who.role === "approver" && !store.isDemo() && store.accountCanAccess(who.name, repo) },
         writes: { setting: store.projectWrites(repo), canChange: who.via === "cookie" && who.role === "approver" && !store.isDemo() && store.accountCanAccess(who.name, repo) },
+        sandbox: { setting: store.projectSandbox(repo), canChange: who.via === "cookie" && who.role === "approver" && !store.isDemo() && store.accountCanAccess(who.name, repo) },
         checkAccess: {
             setting: store.projectCheckAccess(repo), changed: store.projectCheckAccessChange(repo),
             canNarrow: who.via === "cookie" && who.role === "approver" && !store.isDemo() && store.accountCanAccess(who.name, repo),

package/dist/server/render-tasks.js

@@ -2,6 +2,7 @@
 import { networkWords } from "../egress.js";
 import { writesWords } from "../writes-mode.js";
 import { checkAccessWords } from "../check-access.js";
+import { sandboxTermsWords } from "../project-sandbox.js";
 import { ACP_AGENTS, isAcpProfile } from "../acp-agents.js";
 import { html, htmlString, joinHtml, postForm, replaceMarkup, reauth } from "../html.js";
 import { closedQuestionReason, closedQuestionWords } from "../decision.js";
@@ -542,7 +543,9 @@ export function profileWords(scope) {
                 ? html `<p class="meta">Runs on <span class="mono">${ACP_AGENTS[profile.provider].name} (via ACP) · ${profile.model}</span> — full access inside the OS fence; the agent runs any tool it chooses and nothing asks. No turn limit: stops after ${Math.round(profile.timeoutSeconds / 60)} min, or ${Math.round(profile.idleTimeoutSeconds / 60)} min silent; repairs on ${repair}, ${Math.round(profile.repairTimeoutSeconds / 60)} min, or ${Math.round(profile.repairIdleTimeoutSeconds / 60)} min silent.</p>`
                 : html `<p class="meta">Runs on <span class="mono">${profile.provider} · ${profile.model}</span> — ${profile.sandboxMode === "danger-full-access" ? "FULL permissions via --dangerously-bypass-approvals-and-sandbox; nothing asks" : "workspace-write sandbox"}, no turn limit (${Math.round(profile.timeoutSeconds / 60)} min ${profile.timeoutKind === "idle" ? "without progress" : "per attempt"}); repairs on ${repair}, ${Math.round(profile.repairTimeoutSeconds / 60)} min</p>`;
     // What the build may reach is part of what is approved (egress.ts): said on every approval form.
-    return html `${base}<p class="meta" data-scope-network>${networkWords(profile.network ?? null)}</p><p class="meta" data-scope-writes>Writes: ${writesWords(profile.writes)}.</p>${profile.checkAccess === undefined ? "" : html `<p class="meta" data-scope-checks>Checks: ${checkAccessWords(profile.checkAccess)}.</p>`}`;
+    // Its sandbox terms (project-sandbox.ts): what it reads always, and any widening, part of what the yes agrees to.
+    const terms = sandboxTermsWords(profile);
+    return html `${base}<p class="meta" data-scope-network>${networkWords(profile.network ?? null)}</p><p class="meta" data-scope-writes>Writes: ${writesWords(profile.writes)}.</p>${profile.checkAccess === undefined ? "" : html `<p class="meta" data-scope-checks>Checks: ${checkAccessWords(profile.checkAccess)}.</p>`}<p class="meta" data-scope-reads>Reads: ${terms.reads}.</p>${terms.mach === null ? "" : html `<p class="meta" data-scope-mach>${terms.mach.charAt(0).toUpperCase()}${terms.mach.slice(1)}.</p>`}`;
 }
 export const ROLE_NOUN = { plan: "Planner", build: "Builder", repair: "Repair", review: "Reviewer" };
 export function agentsStandingWords(view) {

package/dist/server/route-table.js

@@ -285,6 +285,7 @@ post("settings", "settings.project-live-view", "/settings/project/live-view", {
 post("settings", "settings.project-network", "/settings/project/network", { scope: "step-up", callers: ["cookie"] });
 post("settings", "settings.project-writes", "/settings/project/writes", { scope: "step-up", callers: ["cookie"] });
 post("settings", "settings.project-check-access", "/settings/project/check-access", { scope: "step-up", callers: ["cookie"] });
+post("settings", "settings.project-sandbox", "/settings/project/sandbox", { scope: "step-up", callers: ["cookie"] });
 post("settings", "settings.project-delete", "/settings/project/delete", { scope: "step-up", ...operator("An instance operator deletes projects.", "/settings/project") });
 // Lead sweeps (docs/plans/lead-fan-out.md): the table, and cancelling what isn't ready. The handler shows a sweep only in
 // a project the reader can see, and acts only for an approver.

package/dist/server/settings.js

@@ -82,6 +82,7 @@ import { parseProjectConcurrency, saveProjectConcurrency } from "../project-conc
 import { MAX_NETWORK_HOSTS, normalizeHost } from "../egress.js";
 import { isWritesMode } from "../writes-mode.js";
 import { isCheckAccess, signInsUnavailableWords, widerThan } from "../check-access.js";
+import { parseMachLookup, parseReadDeny } from "../project-sandbox.js";
 import { projectDeleteConfirmHtml, projectSettingsHtml } from "../project-delete-ui.js";
 import { deleteProject, holdingsWords } from "../project-delete.js";
 import { applySavedKnowledge, changeKnowledge, knowledgeVersion, knowledgeView } from "../project-knowledge.js";
@@ -2487,6 +2488,7 @@ ${modeWords(terms)
         "settings.project-network": projectNetwork,
         "settings.project-writes": projectWrites,
         "settings.project-check-access": projectCheckAccess,
+        "settings.project-sandbox": projectSandbox,
         "settings.project-delete": projectDelete,
         "settings.policy-send": policySave,
         "settings.approval-send": approvalSave,
@@ -2624,5 +2626,30 @@ ${modeWords(terms)
             return back("problem", "Check access changed meanwhile, and this would now widen it. Nothing changed.");
         return back("said", changed.before === changed.after ? "Nothing changed." : "Saved. Tasks scoped from now on use it; tasks already approved keep what they were approved with.");
     }
+    // Settings → Project → Home folder (project-sandbox.ts, sandbox parity C9): what the project's builds and checks may not
+    // read, and the macOS services they may also use. An approver for the project changes it with
+    // their password typed now; the ledger keeps before → after. New scopes seal it; approved ones keep theirs.
+    async function projectSandbox(ctx) {
+        const { who, response, now, posted } = ctx;
+        const body = readForm(posted, CONSOLE_FORMS.projectSandbox);
+        const repo = body.get("repo") ?? "";
+        if (!consoleProjects().includes(repo) || !visible(repo))
+            return refuse(response, who, 403, "That project is outside your access.", "/settings/project");
+        if (who.via !== "cookie" || who.role !== "approver" || store.isDemo() || !store.accountCanAccess(who.name, repo))
+            return refuse(response, who, 403, "An approver for this project changes its sandbox.", "/settings/project");
+        const back = sayTo(response, `/settings/project?repo=${encodeURIComponent(repo)}`, "#sandbox");
+        const lines = (name) => (body.get(name) ?? "").split(/\r?\n/);
+        const parsed = { readDeny: parseReadDeny(lines("read-deny")), machLookup: parseMachLookup(lines("mach")) };
+        for (const one of Object.values(parsed))
+            if (!one.ok)
+                return back("problem", `${one.problem.charAt(0).toUpperCase()}${one.problem.slice(1)}. Nothing changed.`);
+        if (!authenticateCredential(who, body.get("password") ?? "").ok)
+            return back("problem", "Enter your Toolroll password to change the project's sandbox.");
+        const wanted = { readDeny: parsed.readDeny.ok ? parsed.readDeny.list : [], machLookup: parsed.machLookup.ok ? parsed.machLookup.list : [] };
+        const changed = store.setProjectSandbox(repo, wanted, who.name, now);
+        if (changed === null)
+            return back("problem", "An approver for this project changes its sandbox. Nothing changed.");
+        return back("said", JSON.stringify(changed.before) === JSON.stringify(changed.after) ? "Nothing changed." : "Saved. Tasks scoped from now on use it; tasks already approved keep what they were approved with.");
+    }
     return { registrations, modelsView };
 }