toolroll 0.9.68 → 0.9.70

package/dist/project-tools.js

@@ -24,11 +24,15 @@ import { createHash } from "node:crypto";
 import { spawn } from "node:child_process";
 import { chmodSync, existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
+import { realpathSync } from "node:fs";
 import { dirname, isAbsolute, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { scanForSecrets } from "./evidence.js";
 import { namedPath } from "./names.js";
 import { startToolBroker } from "./tool-broker.js";
+import { buildCacheFolder, fenceFor, linuxFenceAvailable, macosFenceAvailable, runFolders } from "./agent-fence.js";
+import { confined, ContainmentRefusal } from "./exec.js";
+import { poolRootOf } from "./worktree.js";
 import { isAcpProvider } from "./acp-agents.js";
 import { SecretStoreError, destroyOwnFile, prepareSecretFolder, registerSecretFolder, pathIn, readOwnFile, readSealed, removeValue, secretBackend, secretFolder, secretStorage, serviceOf, withSecretLock, withSecretLockAsync, writeOwnFile, writeSealed } from "./tool-secret-store.js";
 import { ACCESS, GRANTED, REFRESH, mintRunToken, mintsRunTokens, oneAtATime, runScope, scopeList, signedIn } from "./oauth-run-token.js";
@@ -507,7 +511,7 @@ function toolNames(result) {
     return Array.isArray(tools) ? tools.map(one => one.name).filter((name) => typeof name === "string").slice(0, 200) : [];
 }
 /** Start the server once, ask for its tools, and stop it: the proof a build can use it. */
-export async function testTool(spec, values, options = {}) {
+export async function testTool(spec, values, options) {
     const answer = await exchange(spec, values, { method: "tools/list", params: {}, doing: "listing its tools" }, options);
     return answer.ok ? { ok: true, tools: toolNames(answer.result) } : answer;
 }
@@ -516,7 +520,7 @@ export async function testTool(spec, values, options = {}) {
  * its description, what input it takes, and whether it says it only reads.
  * A subagent is offered these, each under its own rule.
  */
-export async function listProjectToolActions(spec, values, options = {}) {
+export async function listProjectToolActions(spec, values, options) {
     const answer = await exchange(spec, values, { method: "tools/list", params: {}, doing: "listing its tools" }, options);
     return answer.ok ? { ok: true, actions: toolActions(answer.result) } : answer;
 }
@@ -537,7 +541,7 @@ export function toolActions(result) {
  * "Use a tool" step. The answer's text parts are kept; a tool that says it
  * failed (isError) is an answer, not trouble reaching it.
  */
-export async function callProjectTool(spec, values, name, args, options = {}) {
+export async function callProjectTool(spec, values, name, args, options) {
     const answer = await exchange(spec, values, { method: "tools/call", params: { name, arguments: args }, doing: `using ${name}` }, options);
     if (!answer.ok)
         return answer;
@@ -552,9 +556,14 @@ function exchange(spec, values, request, options) {
     if (missing.length > 0)
         return Promise.resolve({ ok: false, problem: `Set ${missing.join(", ")} first.` });
     const timeoutMs = options.timeoutMs ?? 60_000;
-    return spec.transport === "http" ? exchangeHttp(spec, values, timeoutMs, request) : exchangeStdio(spec, values, timeoutMs, options.env ?? process.env, options.omitEnv ?? [], request);
+    if (spec.transport === "http")
+        return exchangeHttp(spec, values, timeoutMs, request);
+    // A local server starts only in the server fence its caller made (toolServerFor), never bare.
+    if ("problem" in options.server)
+        return Promise.resolve({ ok: false, problem: options.server.problem });
+    return exchangeStdio(spec, values, timeoutMs, options.env ?? process.env, options.omitEnv ?? [], request, options.server.fence);
 }
-function exchangeStdio(spec, values, timeoutMs, base, omit, request) {
+function exchangeStdio(spec, values, timeoutMs, base, omit, request, fence) {
     return new Promise(resolve => {
         const env = { ...base };
         for (const name of omit)
@@ -562,9 +571,14 @@ function exchangeStdio(spec, values, timeoutMs, base, omit, request) {
         Object.assign(env, values);
         let child;
         try {
-            child = spawn(spec.command, spec.args, { env, stdio: ["pipe", "pipe", "pipe"], detached: process.platform !== "win32" });
+            const launch = confined(spec.command, spec.args, { ...(fence ?? {}), temp: env["TMPDIR"] });
+            child = spawn(launch.file, launch.args, { env: { ...env, ...launch.env }, stdio: ["pipe", "pipe", "pipe"], detached: process.platform !== "win32" });
         }
         catch (error) {
+            if (error instanceof ContainmentRefusal) {
+                resolve({ ok: false, problem: error.message });
+                return;
+            }
             resolve({ ok: false, problem: `It could not start: ${error instanceof Error ? error.message : "unknown error"}.` });
             return;
         }
@@ -1004,7 +1018,8 @@ export async function testToolOf(store, repo, name, now, options = {}) {
     const tool = projectToolsOf(store, repo).find(one => one.name === name);
     if (tool === undefined)
         return null;
-    const outcome = await testTool(tool.spec, readToolSecrets(repo, name, options.home), { ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }), ...(options.omitEnv === undefined ? {} : { omitEnv: options.omitEnv }) });
+    const server = toolServerFor(store, repo, { ...(options.home === undefined ? {} : { home: options.home }), ...(options.available === undefined ? {} : { available: options.available }) });
+    const outcome = await testTool(tool.spec, readToolSecrets(repo, name, options.home), { server, ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }), ...(options.omitEnv === undefined ? {} : { omitEnv: options.omitEnv }) });
     const test = outcome.ok ? { at: now.toISOString(), ok: true, tools: outcome.tools, problem: null } : { at: now.toISOString(), ok: false, tools: [], problem: outcome.problem };
     store.recordProjectToolTest(repo, name, JSON.stringify(test));
     return test;
@@ -1093,3 +1108,24 @@ export function splitCommandLine(line) {
         parts.push(current);
     return parts;
 }
+/**
+ * The server fence for a project tool started outside a build (docs/plans/sandbox-parity.md C2): discovery, its Test
+ * button, a flow's "Use a tool" step, a subagent's call. As the broker's servers are fenced: Toolroll's state, every
+ * other launch's folder and the checkout pools denied, and nothing a build writes (its project's caches) read, so no
+ * byte a build wrote can load into a process that holds the tool's secrets. Required: where this machine can't confine
+ * it, it doesn't start unless an instance operator allowed unconfined agents.
+ */
+export function toolServerFor(store, repo, options = {}) {
+    const databaseFile = store.databaseFile();
+    if (databaseFile === null || databaseFile === "" || databaseFile === ":memory:")
+        return { fence: null };
+    const available = options.available ?? (() => macosFenceAvailable() || linuxFenceAvailable());
+    if (!available())
+        return store.unfencedAgentsAllowed() ? { fence: null }
+            : { problem: "This machine can't confine the tool's server (no macOS sandbox, no working bubblewrap), so it was not started." };
+    const home = options.home ?? homedir();
+    const poolRoots = [join(dirname(databaseFile), "worktrees"), ...store.listWorktrees().map(record => poolRootOf(record.path, record.repo))];
+    const cache = buildCacheFolder(repo, home);
+    const untrusted = existsSync(cache) ? [realpathSync(cache)] : [];
+    return { fence: fenceFor("tool-server", { databaseFile, worktree: null, home, boundary: null, binding: null, runFolders: runFolders(null), poolRoots, extra: untrusted }) };
+}

package/dist/release.d.ts

@@ -30,7 +30,7 @@
  */
 /** The pull-request checks a release waits for, by exact job name (.github/workflows/ci.yml). Every one must have
  * concluded `success` on the gated commit; src/ci-workflow.test.ts holds the workflow to this list. */
-export declare const REQUIRED_PR_CHECKS: readonly ["node 22 · ubuntu-latest", "node 24 · ubuntu-latest", "linux native containment · delegated cgroup v2", "Windows Job Object containment"];
+export declare const REQUIRED_PR_CHECKS: readonly ["node 22 · ubuntu-latest", "node 24 · ubuntu-latest", "linux native containment · delegated cgroup v2", "linux fence · sandbox-runtime", "Windows Job Object containment"];
 /** The checks a release tag runs (.github/workflows/publish.yml), awaited before Homebrew moves. */
 export declare const RELEASE_TAG_CHECKS: readonly ["node 22 · macos-latest", "node 24 · macos-latest", "publish"];
 export declare const RELEASE_STEPS: readonly ["gate", "approval", "check", "complete", "quiet", "deploy", "link", "ci", "merge", "tree", "tag", "publish", "homebrew", "done"];

package/dist/release.js

@@ -37,6 +37,7 @@ export const REQUIRED_PR_CHECKS = [
     "node 22 · ubuntu-latest",
     "node 24 · ubuntu-latest",
     "linux native containment · delegated cgroup v2",
+    "linux fence · sandbox-runtime",
     "Windows Job Object containment",
 ];
 /** The checks a release tag runs (.github/workflows/publish.yml), awaited before Homebrew moves. */

package/dist/result-follow-ups.js

@@ -1,15 +1,4 @@
-/** Follow-ups on any result: "Run checks" and "Add tests".
- *
- * Run checks runs the project's quick or full check on the result's exact
- * commit, in a fresh checkout, after the build has finished. A person (or a
- * pull request opening) asks; the ask is a ledger entry; a worker runs it
- * once and seals its log and a receipt beside the result. A pass upgrades
- * what the result's Checks row says; a failure stays visible. Nothing here
- * rewrites the build's own check or reruns crew work.
- *
- * Add tests files a small task, unapproved like any other filing, to write
- * tests for that change. */
-import { fencedCheckoutCommands } from "./invoke.js";
+import { checkoutRunner, ranAtLine, widestRan } from "./invoke.js";
 import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -188,6 +177,8 @@ export async function runFollowUpCheck(store, root, request, deps = {}) {
     const folder = mkdtempSync(join(deps.scratch ?? tmpdir(), "toolroll-checks-"));
     const checkout = join(folder, "checkout");
     const log = [];
+    // How each command actually ran (check-access.ts): the widest is on the receipt and in the log.
+    const ranAt = [];
     const bound = (text) => { const hits = scanForSecrets(text); return boundStreamHeadTail(hits.length > 0 ? redactSecretLines(text, hits) : text, 24 * 1024); };
     const note = (label, command, result) => log.push(`=== ${label} ===\n$ ${command}\n(exit ${result.code}${result.notFound ? ", could not start" : ""}${result.timedOut ? ", timed out" : ""})\n\n--- stdout ---\n${bound(result.stdout)}\n\n--- stderr ---\n${bound(result.stderr)}`);
     let result;
@@ -199,10 +190,11 @@ export async function runFollowUpCheck(store, root, request, deps = {}) {
         }
         else {
             const setup = store.liveWorktreeSetup(target.repo);
+            // Worked out again right before each command (check-access.ts): a narrowing meanwhile applies to the next one.
             let ready = true;
             if (setup !== null) {
                 const shell = approvedCommandShell(setup.command);
-                const prepared = await runWithIsolatedDatabase(fencedCheckoutCommands(store, target.repo, checkout, runner), shell.file, shell.args, { cwd: checkout, timeoutMs: setup.timeoutMs, processGroup: true, envAllowlist: SETUP_ENV_ALLOWLIST, omitEnv: SETUP_ENV_DENYLIST });
+                const prepared = await runWithIsolatedDatabase(checkoutRunner(store, target.repo, checkout, runner, [runId], level => ranAt.push(level)), shell.file, shell.args, { cwd: checkout, timeoutMs: setup.timeoutMs, processGroup: true, envAllowlist: SETUP_ENV_ALLOWLIST, omitEnv: SETUP_ENV_DENYLIST });
                 note("Approved project setup", setup.command, prepared);
                 if (prepared.code !== 0 || prepared.timedOut || prepared.notFound) {
                     ready = false;
@@ -217,7 +209,7 @@ export async function runFollowUpCheck(store, root, request, deps = {}) {
                 }
                 else {
                     const shell = approvedCommandShell(live.command);
-                    const ran = await runWithIsolatedDatabase(fencedCheckoutCommands(store, target.repo, checkout, runner), shell.file, shell.args, { cwd: checkout, timeoutMs: live.timeoutMs, processGroup: true, envAllowlist: SETUP_ENV_ALLOWLIST, omitEnv: SETUP_ENV_DENYLIST });
+                    const ran = await runWithIsolatedDatabase(checkoutRunner(store, target.repo, checkout, runner, [runId], level => ranAt.push(level)), shell.file, shell.args, { cwd: checkout, timeoutMs: live.timeoutMs, processGroup: true, envAllowlist: SETUP_ENV_ALLOWLIST, omitEnv: SETUP_ENV_DENYLIST });
                     note(`${CHECK_LEVEL_WORDS[target.level]} check`, live.command, ran);
                     result = ran.timedOut ? { ran: false, failure: "The check ran out of time." } : ran.notFound ? { ran: false, failure: "The check couldn't start." } : { ran: true, exitCode: ran.code };
                 }
@@ -231,10 +223,13 @@ export async function runFollowUpCheck(store, root, request, deps = {}) {
         rmSync(folder, { recursive: true, force: true });
     }
     const at = now();
+    const ranLine = ranAtLine(widestRan(ranAt));
+    if (ranLine !== null)
+        log.push(ranLine);
     const text = log.length === 0 ? "No command started." : log.join("\n\n");
     const logId = storeEvidence(store, root, runId, "structured-output", `follow-up-check-${request}.log`, Buffer.from(text, "utf8"), FOLLOW_UP_LOG, at, { captureStatus: "ok" });
     const logArtifact = store.getArtifact(logId);
-    const receipt = JSON.stringify({ version: 1, request, run: runId, head: target.head, tested: target.head, level: target.level,
+    const receipt = JSON.stringify({ version: 1, request, run: runId, head: target.head, tested: target.head, level: target.level, checkAccess: widestRan(ranAt),
         command: { repo: target.command.repo, command: target.command.command, digest: target.command.digest, approvedBy: target.command.approvedBy },
         result, log: { artifactId: logArtifact.id, sha256: logArtifact.sha256, bytesStored: logArtifact.bytesStored, truncated: logArtifact.truncated } }, null, 1);
     storeEvidence(store, root, runId, "structured-output", `follow-up-check-${request}.json`, Buffer.from(receipt, "utf8"), FOLLOW_UP_RECEIPT, at, { captureStatus: "ok" });

package/dist/sandbox-launch.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sandbox-launch.js

@@ -0,0 +1,148 @@
+/**
+ * The Linux launch helper (sandbox-runtime.ts): `node sandbox-launch.js`, handed one launch in its environment
+ * (TOOLROLL_SANDBOX_LAUNCH). It changes into the launch's folder (Anthropic's sandbox-runtime anchors its mandatory
+ * write denies there), starts the runtime's network relays to this run's proxy when the network is confined, asks the
+ * runtime for the bubblewrap + seccomp command, runs it (setting it up again, from a fresh look, if the sandbox failed
+ * before the launch itself started), passes on the signals it gets, and when the command ends removes the mount points
+ * the runtime made and stops the relays. It exits with the command's status. Nothing runs if
+ * the runtime refuses: the helper exits 126 with the reason.
+ */
+import { spawn } from "node:child_process";
+import { checkLinuxDependencies, cleanupBwrapMountPoints, getLinuxDependencyStatus, initializeLinuxNetworkBridge, wrapCommandWithSandboxLinux } from "@anthropic-ai/sandbox-runtime/dist/sandbox/linux-sandbox-utils.js";
+import { SANDBOX_LAUNCH_SPEC, shellQuote, withRuntimeTemp } from "./sandbox-runtime.js";
+const REFUSED = 126;
+/** The status a launch stopped before it ran ends with (128 + SIGTERM). */
+const STOPPED = 143;
+/** Why the runtime can't sandbox here now (bubblewrap, socat or its seccomp helper gone), or null: asked again before
+ * each attempt, never remembered from an earlier look. */
+function missing() {
+    const checked = checkLinuxDependencies();
+    if (checked.errors.length > 0)
+        return checked.errors.join("; ");
+    return getLinuxDependencyStatus().hasSeccompApply ? null : "the sandbox runtime's seccomp helper isn't available";
+}
+async function main() {
+    const raw = process.env[SANDBOX_LAUNCH_SPEC];
+    delete process.env[SANDBOX_LAUNCH_SPEC];
+    if (raw === undefined) {
+        process.stderr.write("toolroll sandbox: no launch was given\n");
+        return REFUSED;
+    }
+    const spec = JSON.parse(raw);
+    process.chdir(spec.cwd);
+    // A stop at any point: what is running is passed it, and nothing starts after it.
+    let stopping = false;
+    let child = null;
+    for (const signal of ["SIGTERM", "SIGINT", "SIGHUP"])
+        process.on(signal, () => { stopping = true; try {
+            child?.kill(signal);
+        }
+        catch { /* gone */ } });
+    const network = spec.terms.network;
+    let bridge = null;
+    // The relays share the launch's process group: they are waited for (SIGKILL after a moment), so when the helper exits
+    // nothing of the launch is left in it to read as the agent's leftover.
+    const stopBridge = async () => {
+        await Promise.all([bridge?.httpBridgeProcess, bridge?.socksBridgeProcess].map(one => new Promise(done => {
+            if (one === undefined || one.exitCode !== null || one.signalCode !== null) {
+                done();
+                return;
+            }
+            const force = setTimeout(() => { try {
+                one.kill("SIGKILL");
+            }
+            catch { /* gone */ } }, 1_000);
+            one.once("exit", () => { clearTimeout(force); done(); });
+            try {
+                one.kill("SIGTERM");
+            }
+            catch {
+                clearTimeout(force);
+                done();
+            }
+        })));
+    };
+    try {
+        if (network.kind === "proxy")
+            bridge = await initializeLinuxNetworkBridge(network.httpPort, network.socksPort ?? network.httpPort);
+        // The runtime reads the temp folder it gives the command when it builds it (withRuntimeTemp, sandbox-runtime.ts).
+        if (spec.temp !== undefined)
+            process.env["CLAUDE_CODE_TMPDIR"] = spec.temp;
+        else
+            withRuntimeTemp(undefined, () => undefined);
+        // The command first says it started, on a descriptor of its own (3), before anything of the launch runs. A sandbox
+        // whose setup failed (bubblewrap couldn't mount over a path another launch removed after the runtime looked)
+        // never ran the launch, so it is set up again from a fresh look, a few times; one that started is never re-run.
+        const started = `printf 1 >&3 || exit 125; exec 3>&-; exec ${shellQuote([spec.file, ...spec.args])}`;
+        for (let attempt = 1;; attempt++) {
+            // Stopped during setup or between attempts: nothing starts.
+            if (stopping)
+                return STOPPED;
+            const gone = missing();
+            if (gone !== null)
+                throw new Error(`the sandbox can't be made here: ${gone}`);
+            const command = await wrapCommandWithSandboxLinux({
+                command: started,
+                needsNetworkRestriction: network.kind === "proxy",
+                ...(bridge === null || network.kind !== "proxy" ? {} : {
+                    httpSocketPath: bridge.httpSocketPath, socksSocketPath: bridge.socksSocketPath, httpProxyPort: network.httpPort,
+                    ...(network.socksPort === undefined ? {} : { socksProxyPort: network.socksPort }),
+                    ...(network.token === undefined ? {} : { proxyAuthToken: network.token }),
+                }),
+                readConfig: spec.terms.readConfig,
+                writeConfig: spec.terms.writeConfig,
+            });
+            // bubblewrap, and the runtime's seccomp filter inside it: anything less is not this sandbox.
+            if (!/\bbwrap\b/.test(command) || !command.includes("apply-seccomp"))
+                throw new Error("the sandbox runtime returned a command without its sandbox or its seccomp filter");
+            if (stopping)
+                return STOPPED;
+            const run = spawn("/bin/sh", ["-c", command], { stdio: ["inherit", "inherit", "pipe", "pipe"] });
+            child = run;
+            let ran = false;
+            const held = [];
+            run.stdio[3].on("data", () => { if (!ran) {
+                ran = true;
+                for (const one of held.splice(0))
+                    process.stderr.write(one);
+            } });
+            run.stdio[3].on("error", () => undefined);
+            run.stderr.on("data", (chunk) => { if (ran)
+                process.stderr.write(chunk);
+            else
+                held.push(chunk); });
+            const status = await new Promise(done => {
+                run.on("error", () => done(REFUSED));
+                run.on("close", (code, signal) => done(code ?? (signal === null ? 1 : 128 + ({ SIGKILL: 9, SIGTERM: 15, SIGINT: 2, SIGHUP: 1 }[signal] ?? 1))));
+            });
+            if (!ran && stopping)
+                return STOPPED;
+            if (ran || attempt >= 3) {
+                if (!ran)
+                    for (const one of held)
+                        process.stderr.write(one);
+                return status;
+            }
+            try {
+                cleanupBwrapMountPoints();
+            }
+            catch { /* the next look is fresh either way */ }
+            await new Promise(done => setTimeout(done, 50 * attempt));
+        }
+    }
+    catch (error) {
+        if (child === null) {
+            process.stderr.write(`toolroll sandbox: nothing was started: ${error instanceof Error ? error.message : String(error)}\n`);
+            return REFUSED;
+        }
+        return 1;
+    }
+    finally {
+        try {
+            cleanupBwrapMountPoints();
+        }
+        catch { /* best effort: the runtime's own exit handler retries */ }
+        await stopBridge();
+    }
+}
+void main().then(code => process.exit(code));

package/dist/sandbox-runtime.d.ts

@@ -0,0 +1,62 @@
+import type { FsReadRestrictionConfig, FsWriteRestrictionConfig } from "@anthropic-ai/sandbox-runtime";
+/** The engine and its exact version, as the console and the words say it. */
+export declare const SANDBOX_RUNTIME: {
+    name: string;
+    version: string;
+};
+/** "Anthropic's sandbox-runtime 0.0.79": how every surface names the engine. */
+export declare const sandboxRuntimeWords: () => string;
+/**
+ * One launch's sandbox, as the runtime's own config: what it may not read (and the exact paths read again inside
+ * those), where it may write (and what stays unwritable there), the extra macOS services it may look up, and its
+ * network (open, or only through this run's proxy; a tool broker rides the runtime's second relay).
+ */
+export type SrtTerms = {
+    readConfig: FsReadRestrictionConfig;
+    writeConfig: FsWriteRestrictionConfig;
+    allowMachLookup: string[];
+    network: {
+        kind: "open";
+    } | {
+        kind: "proxy";
+        httpPort: number;
+        socksPort?: number;
+        token?: string;
+        localServices: boolean;
+        unixSockets: string[];
+    };
+};
+/** A deny-by-default profile, as the runtime's are: inside another sandbox one can't be applied (an allow-by-default one
+ * still can, so it proves nothing). */
+export declare const SEATBELT_PROBE = "(version 1)(deny default)(allow process-exec)(allow process-fork)(allow file-read*)(allow sysctl-read)(allow mach-lookup)";
+/** Why the runtime can't sandbox here, or null when it can (checked before every launch; nothing runs bare). */
+export declare function sandboxRuntimeProblem(platform?: NodeJS.Platform): string | null;
+/** POSIX shell words. */
+export declare function shellQuote(words: readonly string[]): string;
+/**
+ * The runtime sets a sandboxed command's TMPDIR itself (to $CLAUDE_CODE_TMPDIR of the process asking, or /tmp/claude):
+ * the launch's own temp folder when it has one, so it keeps it; otherwise /tmp/claude, made if missing.
+ */
+export declare function withRuntimeTemp<T>(temp: string | undefined, make: () => T): T;
+/** The runtime's macOS invocation for `file args` run from `cwd`: a command line for /bin/sh. */
+export declare function srtMacosCommand(file: string, args: readonly string[], terms: SrtTerms, cwd?: string, temp?: string): string;
+/** The Linux helper (sandbox-launch.ts) and the environment variable its launch is handed in. */
+export declare const SANDBOX_LAUNCH_SPEC = "TOOLROLL_SANDBOX_LAUNCH";
+export declare const sandboxLaunchHelper: () => string;
+/** What the Linux helper is given: the command, where it runs, and the terms. */
+export type SandboxLaunchSpec = {
+    file: string;
+    args: string[];
+    cwd: string;
+    terms: SrtTerms;
+    temp?: string;
+};
+/**
+ * `file args` inside the runtime's sandbox, as a spawn: on macOS `/bin/sh -c <its command>`; on Linux the helper,
+ * handed the launch in its environment (never its arguments, which other users can list).
+ */
+export declare function srtSpawn(file: string, args: readonly string[], terms: SrtTerms, cwd?: string, temp?: string, platform?: NodeJS.Platform): {
+    file: string;
+    args: string[];
+    env: Record<string, string>;
+};

package/dist/sandbox-runtime.js

@@ -0,0 +1,140 @@
+/**
+ * The sandbox engine: Anthropic's sandbox-runtime (`@anthropic-ai/sandbox-runtime`, pinned in package.json). Every
+ * macOS Seatbelt profile and every Linux bubblewrap + seccomp invocation a fenced launch runs under is generated by
+ * its own code, per launch, from a small static config (read denies with exact re-allows, write roots with denies
+ * inside them, mach services, the run's proxy). Toolroll adds only what that config says (agent-fence.ts srtTermsOf);
+ * the rules themselves, their baseline and their limits are the sandbox runtime's.
+ *
+ * macOS: its profile builder runs in this process (it is synchronous), with this process's working folder set to the
+ * launch's for the call, because the runtime anchors its mandatory write denies (.git/hooks, .vscode, shell profiles)
+ * at the working folder. Linux: its builder is asynchronous, anchored at the working folder too, and leaves mount
+ * points to clean up after the command, so each Linux launch runs through a small helper process
+ * (sandbox-launch.ts) that changes into the launch's folder, asks the runtime for the command, runs it and cleans up.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { wrapCommandWithSandboxMacOS } from "@anthropic-ai/sandbox-runtime/dist/sandbox/macos-sandbox-utils.js";
+import { checkLinuxDependencies, getLinuxDependencyStatus } from "@anthropic-ai/sandbox-runtime/dist/sandbox/linux-sandbox-utils.js";
+const require = createRequire(import.meta.url);
+/** The engine and its exact version, as the console and the words say it. */
+export const SANDBOX_RUNTIME = (() => {
+    const name = "@anthropic-ai/sandbox-runtime";
+    try {
+        const manifest = JSON.parse(readFileSync(join(dirname(require.resolve(name)), "..", "package.json"), "utf8"));
+        return { name, version: typeof manifest.version === "string" ? manifest.version : "unknown" };
+    }
+    catch {
+        return { name, version: "unknown" };
+    }
+})();
+/** "Anthropic's sandbox-runtime 0.0.79": how every surface names the engine. */
+export const sandboxRuntimeWords = () => `Anthropic's sandbox-runtime ${SANDBOX_RUNTIME.version}`;
+const SANDBOX_EXEC = "/usr/bin/sandbox-exec";
+/** A deny-by-default profile, as the runtime's are: inside another sandbox one can't be applied (an allow-by-default one
+ * still can, so it proves nothing). */
+export const SEATBELT_PROBE = "(version 1)(deny default)(allow process-exec)(allow process-fork)(allow file-read*)(allow sysctl-read)(allow mach-lookup)";
+/** Why the runtime can't sandbox here, or null when it can (checked before every launch; nothing runs bare). */
+export function sandboxRuntimeProblem(platform = process.platform) {
+    if (platform === "darwin") {
+        if (!existsSync(SANDBOX_EXEC))
+            return "this Mac has no sandbox-exec";
+        const probe = spawnSync(SANDBOX_EXEC, ["-p", SEATBELT_PROBE, "/usr/bin/true"], { timeout: 5_000, stdio: "ignore" });
+        return probe.status === 0 ? null : "sandbox-exec can't start a sandbox here (is this already inside one?)";
+    }
+    if (platform === "linux") {
+        const checked = checkLinuxDependencies();
+        if (checked.errors.length > 0)
+            return checked.errors.join("; ");
+        if (!getLinuxDependencyStatus().hasSeccompApply)
+            return "the sandbox runtime's seccomp helper isn't available for this processor";
+        // The runtime finds nested protected names (a subfolder's .git/hooks, .vscode, shell profiles) with ripgrep.
+        if (spawnSync("rg", ["--version"], { timeout: 5_000, stdio: "ignore" }).status !== 0)
+            return "ripgrep (rg) is not installed";
+        const probe = spawnSync("bwrap", ["--ro-bind", "/", "/", "--unshare-pid", "--unshare-user", "--proc", "/proc", "--new-session", "--", "true"], { timeout: 5_000, stdio: "ignore" });
+        return probe.status === 0 ? null : "bubblewrap can't start a sandbox here (unprivileged user namespaces may be off)";
+    }
+    return `the sandbox runtime has no sandbox for ${platform}`;
+}
+/** POSIX shell words. */
+export function shellQuote(words) {
+    return words.map(word => /^[A-Za-z0-9_@%+=:,./-]+$/.test(word) ? word : `'${word.replace(/'/g, `'\\''`)}'`).join(" ");
+}
+/**
+ * The runtime sets a sandboxed command's TMPDIR itself (to $CLAUDE_CODE_TMPDIR of the process asking, or /tmp/claude):
+ * the launch's own temp folder when it has one, so it keeps it; otherwise /tmp/claude, made if missing.
+ */
+export function withRuntimeTemp(temp, make) {
+    const before = { code: process.env["CLAUDE_CODE_TMPDIR"], old: process.env["CLAUDE_TMPDIR"] };
+    delete process.env["CLAUDE_TMPDIR"];
+    if (temp !== undefined && temp !== "")
+        process.env["CLAUDE_CODE_TMPDIR"] = temp;
+    else {
+        delete process.env["CLAUDE_CODE_TMPDIR"];
+        try {
+            mkdirSync("/tmp/claude", { recursive: true, mode: 0o700 });
+        }
+        catch { /* someone else's: writes there fail */ }
+    }
+    try {
+        return make();
+    }
+    finally {
+        if (before.code === undefined)
+            delete process.env["CLAUDE_CODE_TMPDIR"];
+        else
+            process.env["CLAUDE_CODE_TMPDIR"] = before.code;
+        if (before.old !== undefined)
+            process.env["CLAUDE_TMPDIR"] = before.old;
+    }
+}
+/** The runtime's macOS invocation for `file args` run from `cwd`: a command line for /bin/sh. */
+export function srtMacosCommand(file, args, terms, cwd = process.cwd(), temp) {
+    const network = terms.network;
+    const params = {
+        command: shellQuote([file, ...args]),
+        needsNetworkRestriction: network.kind === "proxy",
+        ...(network.kind === "proxy" ? {
+            httpProxyPort: network.httpPort,
+            ...(network.socksPort === undefined ? {} : { socksProxyPort: network.socksPort }),
+            ...(network.token === undefined ? {} : { proxyAuthToken: network.token }),
+            allowLocalBinding: network.localServices,
+            ...(network.unixSockets.length === 0 ? {} : { allowUnixSockets: network.unixSockets }),
+        } : {}),
+        ...(terms.allowMachLookup.length === 0 ? {} : { allowMachLookup: terms.allowMachLookup }),
+        readConfig: terms.readConfig,
+        writeConfig: terms.writeConfig,
+    };
+    // The runtime anchors its mandatory write denies at this process's working folder: the launch's, for this call.
+    const before = process.cwd();
+    process.chdir(cwd);
+    try {
+        return withRuntimeTemp(temp, () => wrapCommandWithSandboxMacOS(params));
+    }
+    finally {
+        process.chdir(before);
+    }
+}
+/** The Linux helper (sandbox-launch.ts) and the environment variable its launch is handed in. */
+export const SANDBOX_LAUNCH_SPEC = "TOOLROLL_SANDBOX_LAUNCH";
+export const sandboxLaunchHelper = () => {
+    const beside = fileURLToPath(new URL("./sandbox-launch.js", import.meta.url));
+    // Run from the sources (the test suite), the built helper is the package's own.
+    return existsSync(beside) ? beside : fileURLToPath(new URL("../dist/sandbox-launch.js", import.meta.url));
+};
+/**
+ * `file args` inside the runtime's sandbox, as a spawn: on macOS `/bin/sh -c <its command>`; on Linux the helper,
+ * handed the launch in its environment (never its arguments, which other users can list).
+ */
+export function srtSpawn(file, args, terms, cwd = process.cwd(), temp, platform = process.platform) {
+    if (platform === "darwin") {
+        const command = srtMacosCommand(file, args, terms, cwd, temp);
+        if (!command.includes(SANDBOX_EXEC))
+            throw new Error("the sandbox runtime returned the command unsandboxed");
+        return { file: "/bin/sh", args: ["-c", command], env: {} };
+    }
+    const spec = { file, args: [...args], cwd, terms, ...(temp === undefined ? {} : { temp }) };
+    return { file: process.execPath, args: [sandboxLaunchHelper()], env: { [SANDBOX_LAUNCH_SPEC]: JSON.stringify(spec) } };
+}

package/dist/scope.d.ts

@@ -4,6 +4,7 @@ import { isAcpProfile, type AcpProviderId } from "./acp-agents.js";
 export { isAcpProfile };
 import { type NetworkProfile } from "./egress.js";
 import { type WritesMode } from "./writes-mode.js";
+import { type CheckAccess } from "./check-access.js";
 import { type EvidenceKind } from "./contracts/acceptance-terms.js";
 import { type AcceptanceCriterion, type AcceptanceProblem, type ScopeTerms } from "./contracts/scope.js";
 import type { Store, Mutation } from "./store.js";
@@ -78,6 +79,15 @@ export type ClaudeProfile = {
     /** Where the build may write (writes-mode.ts), resolved when the scope was written; absent on approvals sealed before
      * write allowlists, which keep writing anywhere their fence allows. */
     writes?: WritesMode;
+    /** How far its checks reach beyond the check fence (check-access.ts), sealed when wider than sandboxed; absent: sandboxed. */
+    checkAccess?: Exclude<CheckAccess, "sandboxed">;
+    /** The fence policy it was sealed under (agent-fence.ts FencePolicy): 2 from 0.9.70 (the home folder read as in
+     * Anthropic's sandbox runtime, less `readDeny`); absent on approvals sealed before, which keep v1's home denies. */
+    fencePolicy?: 2;
+    /** What its builds and checks may not read (project-sandbox.ts), sealed when the project lists any. */
+    readDeny?: string[];
+    /** macOS services its builds may also reach (project-sandbox.ts), sealed when the project lists any. */
+    machLookup?: string[];
 };
 export type CodexShapedProfile = {
     provider: "codex" | "openrouter";
@@ -98,6 +108,15 @@ export type CodexShapedProfile = {
     /** Where the build may write (writes-mode.ts), resolved when the scope was written; absent on approvals sealed before
      * write allowlists, which keep writing anywhere their fence allows. */
     writes?: WritesMode;
+    /** How far its checks reach beyond the check fence (check-access.ts), sealed when wider than sandboxed; absent: sandboxed. */
+    checkAccess?: Exclude<CheckAccess, "sandboxed">;
+    /** The fence policy it was sealed under (agent-fence.ts FencePolicy): 2 from 0.9.70 (the home folder read as in
+     * Anthropic's sandbox runtime, less `readDeny`); absent on approvals sealed before, which keep v1's home denies. */
+    fencePolicy?: 2;
+    /** What its builds and checks may not read (project-sandbox.ts), sealed when the project lists any. */
+    readDeny?: string[];
+    /** macOS services its builds may also reach (project-sandbox.ts), sealed when the project lists any. */
+    machLookup?: string[];
 };
 export type GeminiProfile = {
     provider: "gemini";
@@ -120,6 +139,15 @@ export type GeminiProfile = {
     /** Where the build may write (writes-mode.ts), resolved when the scope was written; absent on approvals sealed before
      * write allowlists, which keep writing anywhere their fence allows. */
     writes?: WritesMode;
+    /** How far its checks reach beyond the check fence (check-access.ts), sealed when wider than sandboxed; absent: sandboxed. */
+    checkAccess?: Exclude<CheckAccess, "sandboxed">;
+    /** The fence policy it was sealed under (agent-fence.ts FencePolicy): 2 from 0.9.70 (the home folder read as in
+     * Anthropic's sandbox runtime, less `readDeny`); absent on approvals sealed before, which keep v1's home denies. */
+    fencePolicy?: 2;
+    /** What its builds and checks may not read (project-sandbox.ts), sealed when the project lists any. */
+    readDeny?: string[];
+    /** macOS services its builds may also reach (project-sandbox.ts), sealed when the project lists any. */
+    machLookup?: string[];
 };
 /**
  * An agent over the Agent Client Protocol (acp-agents.ts, docs/plans/acp-adapter.md).
@@ -143,6 +171,15 @@ export type AcpProfile = {
     /** Where the build may write (writes-mode.ts), resolved when the scope was written; absent on approvals sealed before
      * write allowlists, which keep writing anywhere their fence allows. */
     writes?: WritesMode;
+    /** How far its checks reach beyond the check fence (check-access.ts), sealed when wider than sandboxed; absent: sandboxed. */
+    checkAccess?: Exclude<CheckAccess, "sandboxed">;
+    /** The fence policy it was sealed under (agent-fence.ts FencePolicy): 2 from 0.9.70 (the home folder read as in
+     * Anthropic's sandbox runtime, less `readDeny`); absent on approvals sealed before, which keep v1's home denies. */
+    fencePolicy?: 2;
+    /** What its builds and checks may not read (project-sandbox.ts), sealed when the project lists any. */
+    readDeny?: string[];
+    /** macOS services its builds may also reach (project-sandbox.ts), sealed when the project lists any. */
+    machLookup?: string[];
 };
 export type ExecutionProfile = ClaudeProfile | CodexShapedProfile | GeminiProfile | AcpProfile;
 /** Whether a profile's clock is a no-progress window (an ACP profile has both clocks; its overall one is a deadline). */