toolroll 0.9.69 → 0.9.70

package/dist/project-sandbox.d.ts

@@ -0,0 +1,59 @@
+export type ProjectSandbox = {
+    readDeny: string[];
+    machLookup: string[];
+};
+export declare const PROJECT_SANDBOX_DEFAULT: ProjectSandbox;
+export declare const MAX_READ_DENY = 100;
+export declare const MAX_MACH_LOOKUP = 30;
+/** A read-deny entry: `~/…` (the home folder of whoever runs the build) or an absolute path; normalized, no `..`, no
+ * pattern; `~` or `/` alone never (that would deny everything a build needs). */
+export declare function validReadDeny(one: string): boolean;
+/** Services no project can add, whatever it asks: the keychain and security services, the pasteboard, Launch Services
+ * and Apple Events (what a build would open or script another application with), the privacy database, the window
+ * server. Each name or prefix here matches the service and everything beneath it. */
+export declare const MACH_NEVER: readonly string[];
+/** A mach service a project may add: an exact reverse-DNS name, or a prefix ending `.*` after at least three labels
+ * (`com.example.tool.*`); never one of MACH_NEVER, nor a prefix that would reach one. */
+export declare function validMachLookup(one: string): boolean;
+/** Entries as a setting keeps them: trimmed, distinct, sorted; refused whole when any is invalid or there are too many. */
+export declare function parseSandboxList(lines: readonly string[], valid: (one: string) => boolean, max: number): {
+    ok: true;
+    list: string[];
+} | {
+    ok: false;
+    problem: string;
+};
+export declare const parseReadDeny: (lines: readonly string[]) => {
+    ok: true;
+    list: string[];
+} | {
+    ok: false;
+    problem: string;
+};
+export declare const parseMachLookup: (lines: readonly string[]) => {
+    ok: true;
+    list: string[];
+} | {
+    ok: false;
+    problem: string;
+};
+/** A stored or sealed setting, read strictly: anything unreadable reads as the narrowest (no extra services) but keeps
+ * whatever read-denies are valid (never fewer than were asked for). */
+export declare function sandboxOf(raw: {
+    readDeny?: unknown;
+    machLookup?: unknown;
+}): ProjectSandbox;
+/** A read-deny entry as the path it names for a launch whose home folder is `home`. */
+export declare const readDenyPath: (one: string, home: string) => string;
+/** What an approval's sandbox terms say, one line each, for every surface that asks for a yes (scope.ts describeScope,
+ * the console's scope view): the fence policy and its read denies always, the macOS services when there are any. */
+export declare function sandboxTermsWords(profile: {
+    fencePolicy?: 2;
+    readDeny?: readonly string[];
+    machLookup?: readonly string[];
+}): {
+    reads: string;
+    mach: string | null;
+};
+/** The setting in a sentence, for the CLI and the settings page. */
+export declare function readDenyWords(list: readonly string[]): string;

package/dist/project-sandbox.js

@@ -0,0 +1,83 @@
+/**
+ * A project's sandbox settings (docs/plans/sandbox-parity.md C9), an approver's, each sealed into new scopes:
+ *
+ * - `readDeny`: what its builds and checks may not read (Anthropic's sandbox runtime `denyRead`). Under fence policy v2
+ *   the home folder is readable as in the sandbox runtime; this is how a project hides `~/.ssh` and the like again.
+ *   Narrowing only: it applies to running launches' next start too (flows, coding sessions read it live).
+ * - `machLookup`: macOS services its builds may also reach (the sandbox runtime `allowMachLookup`), for toolchains the
+ *   deny-default baseline breaks (Go's TLS, Playwright). Widening: sealed, and only a person's password yes seals it.
+ */
+import { isAbsolute, normalize } from "node:path";
+export const PROJECT_SANDBOX_DEFAULT = { readDeny: [], machLookup: [] };
+export const MAX_READ_DENY = 100;
+export const MAX_MACH_LOOKUP = 30;
+/** A read-deny entry: `~/…` (the home folder of whoever runs the build) or an absolute path; normalized, no `..`, no
+ * pattern; `~` or `/` alone never (that would deny everything a build needs). */
+export function validReadDeny(one) {
+    if (one.length === 0 || one.length > 400 || one.includes("\0") || /[*?[\]{}]/.test(one))
+        return false;
+    const path = one.startsWith("~/") ? one.slice(2) : isAbsolute(one) ? one.slice(1) : null;
+    if (path === null || path === "" || path.endsWith("/"))
+        return false;
+    return path.split("/").every(part => part !== "" && part !== "." && part !== "..") && normalize(`/${path}`) === `/${path}`;
+}
+/** Services no project can add, whatever it asks: the keychain and security services, the pasteboard, Launch Services
+ * and Apple Events (what a build would open or script another application with), the privacy database, the window
+ * server. Each name or prefix here matches the service and everything beneath it. */
+export const MACH_NEVER = ["com.apple.security", "com.apple.SecurityServer", "com.apple.securityd", "com.apple.pasteboard",
+    "com.apple.coreservices.launchservicesd", "com.apple.lsd", "com.apple.coreservices.appleevents", "com.apple.tccd", "com.apple.windowserver",
+    "com.apple.CoreServices.coreservicesd"];
+/** A mach service a project may add: an exact reverse-DNS name, or a prefix ending `.*` after at least three labels
+ * (`com.example.tool.*`); never one of MACH_NEVER, nor a prefix that would reach one. */
+export function validMachLookup(one) {
+    if (one.length > 200)
+        return false;
+    const prefix = one.endsWith(".*");
+    const name = prefix ? one.slice(0, -2) : one;
+    const labels = name.split(".");
+    if (!/^[A-Za-z0-9][A-Za-z0-9_-]*(\.[A-Za-z0-9_@-]+)+$/.test(name) || labels.length < (prefix ? 3 : 2))
+        return false;
+    const lower = name.toLowerCase();
+    return !MACH_NEVER.some(never => { const blocked = never.toLowerCase(); return lower === blocked || lower.startsWith(blocked) || (prefix && blocked.startsWith(`${lower}.`)); });
+}
+/** Entries as a setting keeps them: trimmed, distinct, sorted; refused whole when any is invalid or there are too many. */
+export function parseSandboxList(lines, valid, max) {
+    const list = [...new Set(lines.map(one => one.trim()).filter(one => one !== ""))].sort();
+    const bad = list.find(one => !valid(one));
+    if (bad !== undefined)
+        return { ok: false, problem: `“${bad.slice(0, 80)}” isn't a valid entry` };
+    if (list.length > max)
+        return { ok: false, problem: `at most ${max} entries` };
+    return { ok: true, list };
+}
+export const parseReadDeny = (lines) => parseSandboxList(lines, validReadDeny, MAX_READ_DENY);
+export const parseMachLookup = (lines) => parseSandboxList(lines, validMachLookup, MAX_MACH_LOOKUP);
+/** A stored or sealed setting, read strictly: anything unreadable reads as the narrowest (no extra services) but keeps
+ * whatever read-denies are valid (never fewer than were asked for). */
+export function sandboxOf(raw) {
+    const strings = (value) => Array.isArray(value) ? value.filter((one) => typeof one === "string") : [];
+    const readDeny = parseReadDeny(strings(raw.readDeny));
+    const mach = parseMachLookup(strings(raw.machLookup));
+    return {
+        readDeny: readDeny.ok ? readDeny.list : strings(raw.readDeny).filter(validReadDeny),
+        machLookup: mach.ok ? mach.list : [],
+    };
+}
+/** A read-deny entry as the path it names for a launch whose home folder is `home`. */
+export const readDenyPath = (one, home) => one.startsWith("~/") ? `${home}/${one.slice(2)}` : one;
+/** What an approval's sandbox terms say, one line each, for every surface that asks for a yes (scope.ts describeScope,
+ * the console's scope view): the fence policy and its read denies always, the macOS services when there are any. */
+export function sandboxTermsWords(profile) {
+    const reads = profile.fencePolicy === 2
+        ? `your home folder, as in Anthropic's sandbox runtime${(profile.readDeny ?? []).length === 0 ? "" : `, except ${(profile.readDeny ?? []).join(", ")}`}; never Toolroll's own folders; other tasks' work read, never written`
+        : "not your home folder's credentials and agent settings (approved before home reads opened)";
+    return {
+        reads,
+        mach: (profile.machLookup ?? []).length === 0 ? null : `also reaches these macOS services: ${(profile.machLookup ?? []).join(", ")}`,
+    };
+}
+/** The setting in a sentence, for the CLI and the settings page. */
+export function readDenyWords(list) {
+    return list.length === 0 ? "Builds and checks can read your home folder, as in Anthropic's sandbox runtime; Toolroll's own folders stay out of reach, and other tasks' work is read, never written."
+        : `Builds and checks can read your home folder except ${list.length === 1 ? list[0] : `${list.length} paths (${list.slice(0, 3).join(", ")}${list.length > 3 ? ", …" : ""})`}.`;
+}

package/dist/project-tools.d.ts

@@ -1,6 +1,6 @@
 import type { Store, ToolActionInfo } from "./store.js";
 import { type BrokerOptions } from "./tool-broker.js";
-import type { FenceMethod } from "./agent-fence.js";
+import { type FenceMethod, type LaunchFence } from "./agent-fence.js";
 import type { ProviderId } from "./contracts/provider.js";
 import { type SecretStoreKind } from "./tool-secret-store.js";
 import { type ToolSecret, type ToolSpec } from "./contracts/integration-metadata.js";
@@ -105,10 +105,11 @@ export type FoundTool = {
  */
 export declare function discoverTools(repo: string, codexServers: unknown[] | null, home?: string, environment?: NodeJS.ProcessEnv): FoundTool[];
 /** Start the server once, ask for its tools, and stop it: the proof a build can use it. */
-export declare function testTool(spec: ToolSpec, values: Record<string, string>, options?: {
+export declare function testTool(spec: ToolSpec, values: Record<string, string>, options: {
     timeoutMs?: number;
     env?: NodeJS.ProcessEnv;
     omitEnv?: readonly string[];
+    server: ToolServer;
 }): Promise<{
     ok: true;
     tools: string[];
@@ -121,10 +122,11 @@ export declare function testTool(spec: ToolSpec, values: Record<string, string>,
  * its description, what input it takes, and whether it says it only reads.
  * A subagent is offered these, each under its own rule.
  */
-export declare function listProjectToolActions(spec: ToolSpec, values: Record<string, string>, options?: {
+export declare function listProjectToolActions(spec: ToolSpec, values: Record<string, string>, options: {
     timeoutMs?: number;
     env?: NodeJS.ProcessEnv;
     omitEnv?: readonly string[];
+    server: ToolServer;
 }): Promise<{
     ok: true;
     actions: ToolActionInfo[];
@@ -146,10 +148,11 @@ export type ToolCall = {
  * "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 declare function callProjectTool(spec: ToolSpec, values: Record<string, string>, name: string, args: Record<string, unknown>, options?: {
+export declare function callProjectTool(spec: ToolSpec, values: Record<string, string>, name: string, args: Record<string, unknown>, options: {
     timeoutMs?: number;
     env?: NodeJS.ProcessEnv;
     omitEnv?: readonly string[];
+    server: ToolServer;
 }): Promise<ToolCall>;
 /** The exact servers one launch gets, and those left out with why (`repo`: the project, from the run's record). */
 export type ToolLaunch = {
@@ -259,10 +262,11 @@ export declare function addToolTo(store: ToolWrites, repo: string, input: ToolSp
 /** Take one tool away from every build now, with its stored secrets. */
 export declare function removeToolFrom(store: ToolWrites, repo: string, name: string, by: string, now: Date, home?: string): boolean;
 /** Test one tool of a project and keep the answer on it. */
-export declare function testToolOf(store: ToolWrites, repo: string, name: string, now: Date, options?: {
+export declare function testToolOf(store: ToolWrites & ToolServerStore, repo: string, name: string, now: Date, options?: {
     home?: string | undefined;
     timeoutMs?: number;
     omitEnv?: readonly string[];
+    available?: () => boolean;
 }): Promise<ToolTest | null>;
 /** Where a tool stands, in a few words: what a person reads first. */
 export declare function toolStanding(tool: ProjectTool, secretsSet: readonly string[]): {
@@ -289,3 +293,23 @@ export declare function toolSecretStorage(): {
 };
 /** A command line split into program and arguments, honouring "double" and 'single' quotes. */
 export declare function splitCommandLine(line: string): string[];
+/** What a tool server started outside a build needs of the store: the plane's own records of its state and pools. */
+export type ToolServerStore = Pick<Store, "databaseFile" | "listWorktrees" | "unfencedAgentsAllowed">;
+/** How a tool server started outside a build runs (toolServerFor): inside `fence`, or with none where there is nothing to
+ * fence (a store with no database file) or an instance operator allowed unconfined agents; or not at all. */
+export type ToolServer = {
+    fence: LaunchFence | null;
+} | {
+    problem: string;
+};
+/**
+ * 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 declare function toolServerFor(store: ToolServerStore, repo: string, options?: {
+    home?: string;
+    available?: () => boolean;
+}): ToolServer;

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/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>;
+};