toolroll 0.9.68 → 0.9.70

package/dist/egress.d.ts

@@ -96,6 +96,8 @@ export declare function runNetworkFromValue(value: unknown): RunNetworkRecord |
 export type EgressProxy = {
     /** The proxy's address with this run's credentials, for HTTPS_PROXY and the like. */
     url: string;
+    /** This run's credential alone: a client presenting it (with any user name: the sandbox runtime names its own) is served. */
+    secret: string;
     port: number;
     counts: () => EgressCounts;
     close: () => Promise<void>;

package/dist/egress.js

@@ -6,8 +6,8 @@
  * and the project's added hosts), and that snapshot is what the approval binds and the launch enforces. Nothing at
  * launch re-derives it from settings changed since or from files the agent wrote.
  *
- * The launch enforces it at the operating system (agent-fence.ts: Seatbelt's network rules on macOS, a network
- * namespace on Linux) and reaches the world through one proxy of its own (startEgressProxy), which admits only the
+ * The launch enforces it at the operating system (Anthropic's sandbox-runtime: its Seatbelt network rules on macOS, a
+ * network namespace on Linux with the proxy relayed in) and reaches the world through one proxy of its own (startEgressProxy), which admits only the
  * snapshot's hosts. The proxy never decrypts TLS: it restricts where a build connects, not what it sends there.
  */
 import { createServer, request as httpRequest } from "node:http";
@@ -272,7 +272,7 @@ export async function startEgressProxy(options) {
     const upstreamPort = options.upstreamPort ?? ((port) => port);
     const lookup = options.lookup ?? (async (host) => (await dnsLookup(host, { all: true, verbatim: true })).map(one => one.address));
     const secret = randomBytes(24).toString("base64url");
-    const expected = Buffer.from(`Basic ${Buffer.from(`run:${secret}`).toString("base64")}`);
+    const expected = Buffer.from(secret);
     const sockets = new Set();
     const byHost = new Map();
     let connections = 0, refused = 0, otherHosts = 0;
@@ -300,8 +300,16 @@ export async function startEgressProxy(options) {
         }
         catch { /* a listener's trouble is not the build's */ }
     };
+    /** Basic credentials whose password is this run's secret, whatever the user name (the sandbox runtime puts its own
+     * attribution there). */
     const authorized = (incoming) => {
-        const given = Buffer.from(String(incoming.headers["proxy-authorization"] ?? ""));
+        const header = String(incoming.headers["proxy-authorization"] ?? "");
+        const basic = /^Basic ([A-Za-z0-9+/=]+)$/.exec(header)?.[1];
+        if (basic === undefined)
+            return false;
+        const decoded = Buffer.from(basic, "base64").toString("utf8");
+        const colon = decoded.indexOf(":");
+        const given = Buffer.from(colon < 0 ? "" : decoded.slice(colon + 1));
         return given.length === expected.length && timingSafeEqual(given, expected);
     };
     /** The addresses a request may reach, or why it may not. */
@@ -412,6 +420,7 @@ export async function startEgressProxy(options) {
     const port = typeof address === "object" && address !== null ? address.port : 0;
     return {
         url: `http://run:${secret}@127.0.0.1:${port}`,
+        secret,
         port,
         counts: () => ({ connections, refused, hosts: [...byHost].map(([host, one]) => ({ host, ...one })).sort((a, b) => b.connections + b.refused - (a.connections + a.refused) || a.host.localeCompare(b.host)), otherHosts }),
         close: () => new Promise(done => {

package/dist/exec.d.ts

@@ -183,18 +183,24 @@ export declare class ContainmentRefusal extends Error {
     readonly name = "ContainmentRefusal";
 }
 /**
- * The command as it runs inside the agent fence (sandbox-exec or bubblewrap wrapping it), or as it is when it has no
- * fence. A spawn whose confinement is required and that no backend here can wrap is refused (ContainmentRefusal):
- * nothing runs, and nothing falls back to running it unwrapped.
+ * The command as it runs inside the agent fence (Anthropic's sandbox-runtime wrapping it: agent-fence.ts
+ * sandboxedSpawn), with the environment that needs beside the caller's, or as it is when it has no fence. A spawn whose
+ * confinement is required and that no sandbox here can wrap is refused (ContainmentRefusal): nothing runs, and nothing
+ * falls back to running it unwrapped.
  */
 export declare function confined(file: string, args: readonly string[], bag: {
     fence?: readonly string[] | undefined;
     fenceGrants?: FenceGrants | undefined;
     confinement?: "required" | undefined;
+    cwd?: string | undefined;
+    temp?: string | undefined;
 }): {
     file: string;
     args: string[];
+    env: Record<string, string>;
 };
+/** A spawn's environment with what its sandbox needs added (nothing added: the caller's, as it was). */
+export declare function withSandboxEnv<T extends Record<string, string | undefined>>(env: T | undefined, added: Record<string, string>): T | Record<string, string | undefined> | undefined;
 /** Run IDs are local to a database. Connections to the same file share
  * custody; separate files and separate in-memory databases never do. */
 export declare function runOwnerTag(store: Store, runId: number): string;
@@ -298,6 +304,14 @@ export type AcpControl = {
         group: number;
     }[] | null;
 };
+/**
+ * Whether a listed process is the agent's launch (`names`): by its listed name, or on Linux by the program it runs,
+ * since a listing there shows the main thread's name, which Node 24 sets to "MainThread".
+ */
+export declare function agentNamed(row: {
+    pid: number;
+    name: string;
+}, names: readonly string[], programOf?: (pid: number) => string | null): boolean;
 /** How long each shutdown step waits: session/close's answer, then exit after stdin closes, then exit after SIGTERM. */
 export declare const ACP_SHUTDOWN_MS: {
     readonly close: 2000;

package/dist/exec.js

@@ -7,9 +7,9 @@
  * walks repos it has never seen, and one broken repo must not end the scan.
  */
 import { ACP_LINE_CAP, createAcpConversation } from "./acp-client.js";
-import { linuxFenceAvailable, linuxFenced, macosFenceAvailable, macosFenced } from "./agent-fence.js";
+import { linuxFenceAvailable, macosFenceAvailable, sandboxedSpawn } from "./agent-fence.js";
 import { execFile, execFileSync, spawn } from "node:child_process";
-import { realpathSync } from "node:fs";
+import { readlinkSync, realpathSync } from "node:fs";
 import { observeProcessTree, stopProcessTree } from "./process-tree.js";
 import { jsonlDiscriminants } from "./jsonl-discriminants.js";
 import { createContainer, currentContainment } from "./containment.js";
@@ -48,22 +48,35 @@ export class ContainmentRefusal extends Error {
     name = "ContainmentRefusal";
 }
 /**
- * The command as it runs inside the agent fence (sandbox-exec or bubblewrap wrapping it), or as it is when it has no
- * fence. A spawn whose confinement is required and that no backend here can wrap is refused (ContainmentRefusal):
- * nothing runs, and nothing falls back to running it unwrapped.
+ * The command as it runs inside the agent fence (Anthropic's sandbox-runtime wrapping it: agent-fence.ts
+ * sandboxedSpawn), with the environment that needs beside the caller's, or as it is when it has no fence. A spawn whose
+ * confinement is required and that no sandbox here can wrap is refused (ContainmentRefusal): nothing runs, and nothing
+ * falls back to running it unwrapped.
  */
 export function confined(file, args, bag) {
     const fence = bag.fence ?? [];
-    if (fence.length > 0 && macosFenceAvailable())
-        return macosFenced(file, args, fence, bag.fenceGrants);
-    if (fence.length > 0 && linuxFenceAvailable())
-        return linuxFenced(file, args, fence, bag.fenceGrants);
+    // A fence is only ever made by fenceFor (agent-fence.ts), which marks it required: one without the mark was put
+    // together some other way, and would run bare wherever no OS fence applies. Nothing runs.
+    if (fence.length > 0 && bag.confinement !== "required")
+        throw new ContainmentRefusal("This process was given a fence that isn't marked required, so it was not started.");
+    if (fence.length > 0 && (macosFenceAvailable() || linuxFenceAvailable())) {
+        try {
+            return sandboxedSpawn(file, args, fence, bag.fenceGrants, bag.cwd, bag.temp);
+        }
+        catch (error) {
+            throw new ContainmentRefusal(`The sandbox couldn't be made, so nothing was started: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
     if (bag.confinement === "required") {
         throw new ContainmentRefusal(fence.length === 0
             ? "This process must run inside the agent fence, and it was given none."
             : "This machine can't confine a build (no macOS sandbox, no working bubblewrap), so nothing was started.");
     }
-    return { file, args: [...args] };
+    return { file, args: [...args], env: {} };
+}
+/** A spawn's environment with what its sandbox needs added (nothing added: the caller's, as it was). */
+export function withSandboxEnv(env, added) {
+    return Object.keys(added).length === 0 ? env : { ...(env ?? process.env), ...added };
 }
 /** A spawn callback refused custody AFTER the child existed: the caller
  * must reap exactly this child before answering. */
@@ -92,7 +105,9 @@ function rejectedChild(error, child) {
  */
 function spawnContained(file, args, spawnOptions, label, bag, contain = true) {
     // The agent fence wraps the target itself (sandbox-exec then execs it, same pid).
-    ({ file, args } = confined(file, args, bag));
+    const sandboxed = confined(file, args, { ...bag, cwd: spawnOptions.cwd, temp: spawnOptions.env?.["TMPDIR"] });
+    ({ file, args } = sandboxed);
+    spawnOptions = { ...spawnOptions, env: withSandboxEnv(spawnOptions.env, sandboxed.env) };
     // The policy refusal comes first: nothing is reserved, recorded or
     // spawned for a spawn that cannot be contained as required.
     const effective = contain ? currentContainment() : null;
@@ -553,7 +568,7 @@ export function run(file, args, options = {}) {
     // whose confinement is required and can't be wrapped refuses before anything runs.
     let wrapped;
     try {
-        wrapped = confined(file, args, options);
+        wrapped = confined(file, args, { ...options, cwd, temp: childEnv?.["TMPDIR"] });
     }
     catch (error) {
         if (!(error instanceof ContainmentRefusal))
@@ -568,7 +583,7 @@ export function run(file, args, options = {}) {
             encoding: "utf8",
             shell: false,
             windowsHide: true,
-            ...(childEnv === undefined ? {} : { env: childEnv }),
+            ...((env => env === undefined ? {} : { env }))(withSandboxEnv(childEnv, wrapped.env)),
         }, (error, stdout, stderr) => {
             if (error === null) {
                 resolve({ result: { code: 0, stdout, stderr, timedOut: false, notFound: false }, transient: false });
@@ -1373,7 +1388,7 @@ function processRows() {
  * wrapper around it), down to the agent's own process (the first whose command is the agent's launch, `names`), then
  * every live, non-zombie process beneath it, with its group. The agent itself and any wrapper are never counted.
  */
-function liveUnderAgent(root, names) {
+function liveUnderAgent(root, names, rootIsWrapper = false) {
     const rows = processRows();
     if (rows === null)
         return null;
@@ -1381,9 +1396,10 @@ function liveUnderAgent(root, names) {
     for (const row of rows)
         children.set(row.parent, [...(children.get(row.parent) ?? []), row]);
     const self = rows.find(row => row.pid === root);
-    const named = (row) => names.some(name => row.name === name || row.name.endsWith(`/${name}`));
+    const named = (row) => agentNamed(row, names);
     // The agent: the root when it is the agent (macOS sandbox-exec execs in place), else the first named descendant.
-    let agent = self !== undefined && named(self) ? root : null;
+    // On Linux the root is the sandbox launch helper (sandbox-launch.ts, itself node): never taken for the agent.
+    let agent = !rootIsWrapper && self !== undefined && named(self) ? root : null;
     const pending = [...(children.get(root) ?? [])];
     while (agent === null && pending.length > 0) {
         const row = pending.shift();
@@ -1404,6 +1420,27 @@ function liveUnderAgent(root, names) {
     }
     return found;
 }
+/** The program a Linux process runs (its /proc exe), or null: elsewhere, or unreadable. */
+function linuxProgramOf(pid) {
+    if (process.platform !== "linux")
+        return null;
+    try {
+        return readlinkSync(`/proc/${pid}/exe`).replace(/ \(deleted\)$/, "").split("/").pop() || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Whether a listed process is the agent's launch (`names`): by its listed name, or on Linux by the program it runs,
+ * since a listing there shows the main thread's name, which Node 24 sets to "MainThread".
+ */
+export function agentNamed(row, names, programOf = linuxProgramOf) {
+    if (names.some(name => row.name === name || row.name.endsWith(`/${name}`)))
+        return true;
+    const program = programOf(row.pid);
+    return program !== null && names.includes(program);
+}
 /** How long each shutdown step waits: session/close's answer, then exit after stdin closes, then exit after SIGTERM. */
 export const ACP_SHUTDOWN_MS = { close: 2_000, eof: 5_000, term: 5_000 };
 /** How long each handshake step (initialize, session/new, choosing the model) may take before the agent is stopped. */
@@ -1612,7 +1649,7 @@ export function runAcpSession(file, args, options = {}) {
                             forceKill();
                         });
                 },
-                liveDescendants: () => process.platform === "win32" ? null : exited() || child.pid === undefined ? [] : liveUnderAgent(child.pid, agentNames),
+                liveDescendants: () => process.platform === "win32" ? null : exited() || child.pid === undefined ? [] : liveUnderAgent(child.pid, agentNames, child.spawnargs.some(arg => arg.endsWith("sandbox-launch.js"))),
             });
         }
         catch { /* the caller's own failure */ }

package/dist/flow-actions.d.ts

@@ -75,4 +75,5 @@ export declare function toolWaiting(store: Store, stage: FlowStage, repo: string
 export declare function useTool(store: Store, stage: FlowStage, card: FlowCardRow, repo: string, io: {
     callTool?: ToolCaller;
     toolHome?: string;
+    fenceAvailable?: () => boolean;
 }): Promise<ActionOutcome>;

package/dist/flow-actions.js

@@ -25,7 +25,7 @@ import { googleAccessToken, googleConnected } from "./google-mail.js";
 import { ADDRESS, readEmailSettings } from "./email-settings.js";
 import { readFlowSecrets, scrubSecrets } from "./flow-secrets.js";
 export { readEmailSettings, saveEmailSettings } from "./email-settings.js";
-import { callProjectTool, projectToolsOf, readToolSecrets } from "./project-tools.js";
+import { callProjectTool, projectToolsOf, readToolSecrets, toolServerFor } from "./project-tools.js";
 import { ALL_CREDENTIAL_ENV } from "./provider.js";
 const clip = (text, cap) => text.length <= cap ? text : `${text.slice(0, cap - 1)}…`;
 const blank = (text) => redactSecretAssignments(redactSecretLines(text, scanForSecrets(text)));
@@ -189,7 +189,8 @@ export async function useTool(store, stage, card, repo, io) {
     const text = { title: card.title, description: card.description, note: card.note, outputs: card.outputs };
     const args = fillJson(JSON.parse(call.args), one => fillFlowText(one, text));
     const values = readToolSecrets(repo, tool.name, io.toolHome);
-    const answer = await (io.callTool ?? ((spec, secrets, name, given) => callProjectTool(spec, secrets, name, given, { timeoutMs: 120_000, omitEnv: ALL_CREDENTIAL_ENV })))(tool.spec, values, call.name, args);
+    const answer = await (io.callTool ?? ((spec, secrets, name, given) => callProjectTool(spec, secrets, name, given, { timeoutMs: 120_000, omitEnv: ALL_CREDENTIAL_ENV,
+        server: toolServerFor(store, repo, { ...(io.toolHome === undefined ? {} : { home: io.toolHome }), ...(io.fenceAvailable === undefined ? {} : { available: io.fenceAvailable }) }) })))(tool.spec, values, call.name, args);
     if (!answer.ok)
         return { state: "retry", said: `${call.server}: ${answer.problem}` };
     const said = blank(scrub(clip(answer.text, 64_000), values));

package/dist/flow-code.d.ts

@@ -1,5 +1,6 @@
 import type { Runner } from "./backend.js";
-import type { FlowScriptRow } from "./store.js";
+import { type FencePolicy, type LaunchFence } from "./agent-fence.js";
+import type { FlowScriptRow, Store } from "./store.js";
 import { projectFile } from "./project-file.js";
 export { projectFile };
 export { LANGUAGE_WORDS, SCRIPT_LANGUAGES, type ScriptLanguage } from "./flows.js";
@@ -17,7 +18,9 @@ export type CodeRun = {
     secrets: Record<string, string>;
     scratch: string;
     shell: Runner;
-    fence: readonly string[];
+    /** Where it runs from (flowLaunch): its fence, and the launch folder its input and an inline script are written to;
+     * null only where there is nothing to fence (a store with no database file). */
+    launch: FlowLaunch | null;
 };
 /** `printed`: everything it printed (secrets blanked), for a trigger to read items from; `output` is what a card keeps. */
 export type CodeResult = {
@@ -49,3 +52,29 @@ export declare function cardsFromOutput(stdout: string): {
     title: string;
     description: string | null;
 }[];
+/**
+ * Where one flow launch runs (docs/plans/sandbox-parity.md C1): the fence `fenceFor` makes for a flow's setup, script
+ * or trigger, around `folder` (a copy of the card's work, bound to its project, or a clean folder), with a launch folder
+ * of its own for its input, an inline script and its temp files; writes as the project's writes setting allows (its
+ * folder, the copy's Git data, its project's caches); the scratch pool denied around its own folder; and its network
+ * open, as flows' scripts have always had it (they reach the services their secrets are for; no approval seals a
+ * network for them). The fence is required: where this machine can't confine it, it runs only when an instance operator
+ * allowed unconfined agents, and otherwise nothing runs and the card says why.
+ */
+export type FlowLaunch = {
+    folder: string;
+    env: Record<string, string>;
+    fence?: LaunchFence;
+    dispose(): void;
+};
+export declare function flowLaunch(store: Store, options: {
+    repo: string;
+    folder: string;
+    scratch: string;
+    copy: boolean;
+    available?: () => boolean;
+    policy?: FencePolicy;
+    home?: string;
+}): FlowLaunch | null | {
+    problem: string;
+};

package/dist/flow-code.js

@@ -15,9 +15,13 @@
  *   keys are out of reach), under a time limit, with the setup's plain
  *   environment rather than this process's.
  */
-import { chmodSync, existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { randomBytes } from "node:crypto";
-import { join } from "node:path";
+import { homedir, tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { buildCacheEnv, buildCacheFolder, checkLaunchRoot, fenceFor, linuxFenceAvailable, macosFenceAvailable, runFolders, taskBoundary, trustedWorktreeBinding, writeAllowlist } from "./agent-fence.js";
+import { readDenyPath } from "./project-sandbox.js";
+import { poolRootOf } from "./worktree.js";
 import { SETUP_ENV_ALLOWLIST, SETUP_ENV_DENYLIST } from "./builder.js";
 import { redactSecretLines, scanForSecrets } from "./evidence.js";
 import { scrubSecrets } from "./flow-secrets.js";
@@ -51,7 +55,10 @@ export async function runCode(run) {
     const language = script.language;
     const tag = randomBytes(6).toString("hex");
     mkdirSync(run.scratch, { recursive: true });
-    const inputFile = join(run.scratch, `flow-input-${tag}.json`);
+    // The input and an inline script live in the launch's own folder, the one place beside its working folder its fence
+    // gives back (every other launch folder, and every other flow copy in the scratch pool, stay out of reach).
+    const files = run.launch?.folder ?? run.scratch;
+    const inputFile = join(files, `flow-input-${tag}.json`);
     let scriptFile = null;
     try {
         writeFileSync(inputFile, JSON.stringify(run.input), { mode: 0o600 });
@@ -61,7 +68,7 @@ export async function runCode(run) {
                 return { state: "failed", exitCode: null, output: "", printed: "", goTo: null, log: "", said: `${script.name} runs ${script.file}, which isn't a file in the project.` };
         }
         else {
-            const own = join(run.scratch, `flow-script-${tag}.${EXTENSION[language]}`);
+            const own = join(files, `flow-script-${tag}.${EXTENSION[language]}`);
             writeFileSync(own, `${script.body}\n`, { mode: 0o700 });
             chmodSync(own, 0o700);
             scriptFile = own;
@@ -71,7 +78,7 @@ export async function runCode(run) {
         // first without breaking anything. Only our own paths are in the command; the card is only data.
         const ran = await run.shell("/bin/sh", ["-c", 'exec "$@" < "$FLOW_INPUT"', "flow-script", runtime.file, ...runtime.args], {
             cwd: run.cwd, timeoutMs: script.timeoutMinutes * 60_000, envAllowlist: SETUP_ENV_ALLOWLIST, omitEnv: SETUP_ENV_DENYLIST, processGroup: true,
-            env: { ...run.env, ...run.secrets, FLOW_INPUT: inputFile }, fence: run.fence,
+            env: { ...run.env, ...run.secrets, ...(run.launch?.env ?? {}), FLOW_INPUT: inputFile }, ...(run.launch?.fence ?? {}),
         });
         const printed = codeOutput(ran.stdout, run.secrets);
         const all = scrubSecrets(ran.stdout.slice(0, 1_000_000), run.secrets);
@@ -148,3 +155,48 @@ export function cardsFromOutput(stdout) {
         return asItem(trimmed);
     }).filter((one) => one !== null);
 }
+export function flowLaunch(store, options) {
+    const databaseFile = store.databaseFile();
+    if (databaseFile === null || databaseFile === "" || databaseFile === ":memory:")
+        return null;
+    const available = options.available ?? (() => macosFenceAvailable() || linuxFenceAvailable());
+    const fenced = available();
+    // Asked first: a launch with no fence of its own (an instance operator allowed it, as inside another sandbox) makes
+    // its folder in the temp folder it was given, never among the fenced launches' (which an outer sandbox may hold).
+    if (!fenced && !store.unfencedAgentsAllowed()) {
+        return { problem: "This machine can't confine the flow's script (no macOS sandbox, no working bubblewrap), so it didn't run. Install bubblewrap, socat and ripgrep (Linux), or an instance operator allows unconfined agents with `toolroll config unconfined-agents allow`." };
+    }
+    let own;
+    try {
+        own = realpathSync(mkdtempSync(join(fenced ? checkLaunchRoot() : tmpdir(), "so-cmd-")));
+    }
+    catch (error) {
+        return { problem: `The flow's launch folder couldn't be made, so nothing ran: ${error instanceof Error ? error.message : String(error)}` };
+    }
+    const dispose = () => rmSync(own, { recursive: true, force: true });
+    const temp = join(own, "tmp");
+    mkdirSync(temp, { mode: 0o700 });
+    const env = { TMPDIR: temp, TMP: temp, TEMP: temp };
+    if (!fenced)
+        return { folder: own, env, dispose };
+    try {
+        const poolRoots = [join(dirname(databaseFile), "worktrees"), options.scratch, ...store.listWorktrees().map(record => poolRootOf(record.path, record.repo))];
+        // Its scratch folder is a pool root (so another flow's copy is out of reach) and sealed: never read, at any policy.
+        // A copy is held to its project by the plane's own record of the repository, never what the copy says.
+        const binding = options.copy ? trustedWorktreeBinding(options.repo, options.folder, poolRoots) : null;
+        // The policy its flow sealed; nothing sealed is v1 (the home configuration denied), never a wider one implicitly.
+        const home = options.home ?? homedir();
+        const boundary = taskBoundary({ worktree: options.folder, provider: "command", home, binding, policy: options.policy ?? 1 });
+        const cache = buildCacheFolder(options.repo, home);
+        const allowed = store.projectWrites(options.repo) !== "workspace" ? null : writeAllowlist({ provider: "command", home, worktree: options.folder, binding, launchFolder: own, cache });
+        // The project's read denies apply to flows as to builds (read live: a flow seals no list, and these only narrow).
+        const readDeny = store.projectSandbox(options.repo).readDeny.map(one => readDenyPath(one, home));
+        const fence = fenceFor("flow", { databaseFile, worktree: options.folder, home, boundary, readDeny, policy: options.policy ?? 1, scratchRoots: [options.scratch], binding, runFolders: runFolders(own), poolRoots, extra: allowed?.deny ?? [],
+            writes: allowed === null ? null : { writes: allowed.writes, readOnly: allowed.readOnly }, network: { mode: "open" } });
+        return { folder: own, env: { ...env, ...(allowed === null ? {} : buildCacheEnv(cache)) }, fence, dispose };
+    }
+    catch {
+        dispose();
+        return { problem: "The flow's copy couldn't be bound to its project, so nothing ran." };
+    }
+}

package/dist/flow-steps.d.ts

@@ -14,6 +14,10 @@ export type StepIo = {
     dir: string | null;
     /** Where temporary copies of a card's work are made. */
     scratch: string;
+    /** Whether this machine can confine a script (tests only; default: the macOS sandbox or bubblewrap is here). */
+    fenceAvailable?: () => boolean;
+    /** The home folder a launch is fenced around (tests only; default: this user's). */
+    home?: string;
     evidenceRoot?: string;
     /** The branch a card with no result yet is checked against. */
     base: string;

package/dist/flow-steps.js

@@ -35,8 +35,7 @@ import { JEV_MODEL, askJev, readJevAnswers, sortLog, sortRequest, sortState, sor
 import { claudeDraftRunner, DRAFT_CHARS, DRAFT_TIMEOUT, draftPrompt, wholeDraft } from "./flow-draft.js";
 import { overruns, passOn, TEXT_LIMITS, writeWithin } from "./text-limits.js";
 import { readFlowSecrets, sendingReady, runRequest, sendEmail, toolWaiting, useTool } from "./flow-actions.js";
-import { cleanFolder, runCode } from "./flow-code.js";
-import { agentFence } from "./agent-fence.js";
+import { cleanFolder, flowLaunch, runCode } from "./flow-code.js";
 import { readProviderKey } from "./keys.js";
 import { replyInChannel } from "./chat-inbox.js";
 import { recordSent, threadOf } from "./flow-replies.js";
@@ -362,13 +361,16 @@ async function runCheck(store, flow, stage, script, card, now, io) {
         if (added.code !== 0)
             return { state: "retry", said: `Couldn't make a copy of${where}: ${added.stderr.trim().split("\n")[0]?.slice(0, 160) ?? "git refused"}.` };
     }
+    const launch = flowLaunch(store, { repo: flow.repo, folder: path, scratch: io.scratch, copy, policy: store.flowFencePolicy(flow.id), ...(io.fenceAvailable === undefined ? {} : { available: io.fenceAvailable }), ...(io.home === undefined ? {} : { home: io.home }) });
     try {
-        const fence = agentFence({ databaseFile: store.databaseFile(), worktree: path });
+        if (launch !== null && "problem" in launch)
+            return { state: "failed", said: launch.problem };
         let log = "";
         const setup = copy ? store.liveWorktreeSetup(flow.repo) : null;
         if (setup !== null) {
             const shell = approvedCommandShell(setup.command);
-            const prepared = await io.shell(shell.file, shell.args, { cwd: path, timeoutMs: setup.timeoutMs, envAllowlist: SETUP_ENV_ALLOWLIST, omitEnv: SETUP_ENV_DENYLIST, processGroup: true, fence });
+            const prepared = await io.shell(shell.file, shell.args, { cwd: path, timeoutMs: setup.timeoutMs, envAllowlist: SETUP_ENV_ALLOWLIST, omitEnv: SETUP_ENV_DENYLIST, processGroup: true,
+                ...(launch === null ? {} : { env: launch.env, ...(launch.fence ?? {}) }) });
             log += `$ ${setup.command}\n${prepared.stdout}${prepared.stderr}\n`;
             if (prepared.code !== 0)
                 return { state: "failed", said: `The project's setup failed before ${script.name} ran (exit ${prepared.code}).\n${tail(`${prepared.stdout}\n${prepared.stderr}`)}`, log, exitCode: prepared.code };
@@ -383,7 +385,7 @@ async function runCheck(store, flow, stage, script, card, now, io) {
             answers: (stage.routes ?? []).map(one => one.answer),
         };
         const env = { FLOW_NAME: flow.name, FLOW_CARD_ID: String(card.id), FLOW_CARD_TITLE: card.title, FLOW_COMMIT: commit ?? "", FLOW_SCRIPT: script.name, FLOW_PROJECT: flow.repo };
-        const ran = await runCode({ script, cwd: path, root: copy ? path : flow.repo, input, env, secrets, scratch: io.scratch, shell: io.shell, fence });
+        const ran = await runCode({ script, cwd: path, root: copy ? path : flow.repo, input, env, secrets, scratch: io.scratch, shell: io.shell, launch });
         log += ran.log;
         const output = ran.output === "" ? undefined : ran.output;
         // Where it ran goes at the end of the first line: "run-tests failed (exit 1) on main."
@@ -398,6 +400,8 @@ async function runCheck(store, flow, stage, script, card, now, io) {
         return { state: "passed", said: `${script.name} ran${where} and picked ${route.answer}.`, log, exitCode: 0, to: route.to, ...(output === undefined ? {} : { output }) };
     }
     finally {
+        if (launch !== null && !("problem" in launch))
+            launch.dispose();
         if (copy)
             await io.git("git", ["-C", flow.repo, "worktree", "remove", "--force", path], { timeoutMs: 60_000 }).catch(() => undefined);
         rmSync(path, { recursive: true, force: true });

package/dist/flow-triggers.d.ts

@@ -141,6 +141,10 @@ export type TriggerIo = {
     /** v90: how a schedule's script runs (default: the same runner as gh) and where (default: beside the database). */
     shell?: Runner;
     scratch?: string;
+    /** Whether this machine can confine a script (tests only; default: the macOS sandbox or bubblewrap is here). */
+    fenceAvailable?: () => boolean;
+    /** The home folder a launch is fenced around (tests only; default: this user's). */
+    home?: string;
 };
 export type TriggerPass = {
     added: number;

package/dist/flow-triggers.js

@@ -859,21 +859,26 @@ async function fireScript(store, trigger, config, now, io, scheduled) {
     if (missing.length > 0)
         return done(false, `${script.name} needs the secret${missing.length === 1 ? "" : "s"} ${missing.join(", ")}. Save ${missing.length === 1 ? "it" : "them"} on the flow first.`);
     // Loaded when a script first runs: the runner reaches the builder's modules, which reach back to these triggers.
-    const { cardsFromOutput, cleanFolder, runCode } = await import("./flow-code.js");
-    const { agentFence } = await import("./agent-fence.js");
+    const { cardsFromOutput, cleanFolder, flowLaunch, runCode } = await import("./flow-code.js");
     const scratch = io.scratch ?? join(io.dir ?? tmpdir(), "flow-scratch");
     const folder = cleanFolder(scratch, `flow-trigger-${trigger.id}`);
     // Its cards run on their own only if it ran the very code a grant signed: pinned just before and just after the run.
     const pin = scheduled && grantSignsScriptOf(store, flow.id, trigger.id, now) ? () => scriptProvenanceOf(store, flow.repo, script.name) : null;
     const before = pin === null ? null : await pin();
     let ran;
+    // A full boundary around its clean folder, though it has no checkout (flow-code.ts flowLaunch).
+    const launch = flowLaunch(store, { repo: flow.repo, folder, scratch, copy: false, policy: store.flowFencePolicy(flow.id), ...(io.fenceAvailable === undefined ? {} : { available: io.fenceAvailable }), ...(io.home === undefined ? {} : { home: io.home }) });
     try {
+        if (launch !== null && "problem" in launch)
+            return done(false, launch.problem);
         ran = await runCode({ script, cwd: folder, root: flow.repo, scratch, shell: io.shell ?? io.gh,
             input: { flow: { id: flow.id, name: flow.name }, trigger: trigger.id, lastRun: trigger.lastAt }, secrets: Object.fromEntries((config.secrets ?? []).map(name => [name, saved[name]])),
             env: { FLOW_NAME: flow.name, FLOW_TRIGGER_ID: String(trigger.id), FLOW_PROJECT: flow.repo, FLOW_LAST_RUN: trigger.lastAt ?? "" },
-            fence: agentFence({ databaseFile: store.databaseFile(), worktree: folder }) });
+            launch });
     }
     finally {
+        if (launch !== null && !("problem" in launch))
+            launch.dispose();
         rmSync(folder, { recursive: true, force: true });
     }
     if (ran.state === "failed")

package/dist/invoke.d.ts

@@ -21,7 +21,9 @@ import { type VersionProbe } from "./attest.js";
 import type { Store } from "./store.js";
 import type { RunOptions } from "./exec.js";
 import type { Runner } from "./worktree.js";
-import { type WritesMode } from "./agent-fence.js";
+import { type NetworkFence, type SignInGrants } from "./agent-fence.js";
+import { type CheckAccess } from "./check-access.js";
+import { type WritesMode, type LaunchSandbox, type FenceGrants } from "./agent-fence.js";
 import { type NetworkProfile } from "./egress.js";
 export type { ProviderRunner } from "./provider.js";
 export type ProviderUsage = {
@@ -109,6 +111,7 @@ export declare function invokeAgent(store: Store, runId: number, spec: AgentSpec
     accumulateUsage?: boolean;
     network?: LaunchNetwork;
     writes?: WritesMode;
+    sandbox?: LaunchSandbox;
 }): Promise<InvokeResult>;
 /**
  * A build's setup and check commands, run in its fence (arc 2): the same denies as its agent's (Toolroll's state,
@@ -117,11 +120,55 @@ export declare function invokeAgent(store: Store, runId: number, spec: AgentSpec
  * Their network stays as it was. A machine without an OS fence runs them as before; a fence that can't be prepared
  * (a checkout whose binding no longer proves) runs nothing.
  */
-export declare function fencedCommands(store: Store, runId: number, writes: WritesMode, inner: Runner, available?: () => boolean): Runner;
+export declare function fencedCommands(store: Store, runId: number, writes: WritesMode, inner: Runner, available?: () => boolean, access?: CheckAccess, network?: NetworkProfile, sandbox?: LaunchSandbox): Runner;
 /**
  * A project's checks run in a checkout of a result's commit made for them (result-follow-ups.ts, batch-checks.ts), in
  * the same fence as a build's commands: Toolroll's state, credentials, other projects and runs denied; under the
  * project's writes setting, only that checkout, its Git data, its own temp folder, the project's caches and its check
  * database writable. Where nothing can confine them, they run only when an instance operator allowed unconfined agents.
  */
-export declare function fencedCheckoutCommands(store: Store, repo: string, checkout: string, inner: Runner, available?: () => boolean): Runner;
+export declare function fencedCheckoutCommands(store: Store, repo: string, checkout: string, inner: Runner, available?: () => boolean, access?: CheckAccess, network?: NetworkProfile, sandbox?: LaunchSandbox): Runner;
+/**
+ * A `sign-ins` check's launch (check-access.ts, sandbox parity C10): its exact sign-in files, read by the check itself
+ * through its sandbox (agent-fence.ts signInGrants: nothing privileged reads or copies one), its own transcript folder
+ * and Codex's session and log folders; Codex, gh and XDG pointed at the real folders; and the network the check runs
+ * under: open, or its allowlist through a proxy of its own (on Linux, relayed in by the sandbox runtime). Nothing about it is
+ * started unless all of it is.
+ */
+export declare function signInsLaunch(store: Store, own: string, temp: string, checkout: string, policy: NetworkProfile, gitPaths: readonly string[], platform?: NodeJS.Platform): Promise<{
+    grants: SignInGrants;
+    network: NetworkFence;
+    env: Record<string, string>;
+    close(): Promise<void>;
+} | {
+    problem: string;
+}>;
+/** How a check at `access` actually runs here: unsandboxed where no OS fence exists (and an operator allowed that), else
+ * as asked. Recorded on every check's receipt, so a check that ran without a sandbox is never shown as sandboxed. */
+export declare function actualCheckAccess(store: Store, access: CheckAccess): CheckAccess;
+/**
+ * A check of saved results, in their own checkout (batch-checks.ts, result-follow-ups.ts), worked out right before each
+ * command: never wider than any of those results' own checks ran, nor than the project allows now; under sign-ins, the
+ * narrowest of their sealed check networks and the project's current one. A result with no sealed network runs it
+ * sandboxed.
+ */
+export declare function checkoutLaunchOf(store: Store, repo: string, runIds: readonly number[], platform?: NodeJS.Platform): {
+    access: CheckAccess;
+    network: NetworkProfile | undefined;
+};
+/** The widest level a check's commands actually ran at (what its receipt says). */
+export declare const widestRan: (levels: readonly CheckAccess[]) => CheckAccess;
+/** A check log's line for how its commands ran, when wider than sandboxed (shown with the log). */
+export declare const ranAtLine: (level: CheckAccess) => string | null;
+/** A saved result's check command runner (batch-checks.ts, result-follow-ups.ts): its level and network worked out right
+ * now (checkoutLaunchOf), and how it actually runs told to `ran`. */
+export declare function checkoutRunner(store: Store, repo: string, checkout: string, inner: Runner, runIds: readonly number[], ran: (level: CheckAccess) => void, platform?: NodeJS.Platform): Runner;
+/**
+ * A saved result's checks' sandbox terms (sandbox parity C9), never wider than any of those results' own approvals nor
+ * the project now: v2 only when every result's approval sealed v2; every read deny any of them sealed or the project
+ * lists now; mach services only those all of them sealed and the project still lists. A result with
+ * no readable approval counts as v1 with nothing listed.
+ */
+export declare function checkoutSandboxOf(store: Store, repo: string, runIds: readonly number[]): LaunchSandbox;
+/** The digest of a launch's whole fence (its denied paths and grants, canonical), as stamped on its run (C11). */
+export declare function fenceDigest(fence: readonly string[], grants: FenceGrants): string;