toolroll 0.9.69 → 0.9.71

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

@@ -23,7 +23,7 @@ import type { RunOptions } from "./exec.js";
 import type { Runner } from "./worktree.js";
 import { type NetworkFence, type SignInGrants } from "./agent-fence.js";
 import { type CheckAccess } from "./check-access.js";
-import { type WritesMode } from "./agent-fence.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 = {
@@ -111,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,
@@ -119,21 +120,28 @@ 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, access?: CheckAccess, network?: NetworkProfile): 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, access?: CheckAccess, network?: NetworkProfile): 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): its exact sign-in files and its own transcript folder
- * (agent-fence.ts signInGrants), Codex's config and sign-in copied into a home of the launch's own (private, gone with
- * the launch; ~/.codex itself stays fenced), gh pointed at its own folder, and the network the check runs under:
- * open, or its allowlist through a proxy of its own (on Linux, carried in by a bridge). Nothing about it is started
- * unless all of it is.
+ * 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.
  */
+/**
+ * Whether a check with sign-ins also reaches the keychain (macOS securityd: any item every program may read, not only
+ * the sign-ins). Only while the project's sign-ins level stands as a person set it: widening to sign-ins takes an
+ * instance operator's password typed now (operate.ts project check-access, Settings → Project → Check access), and the
+ * one who set it must still be an approver for the project and an instance operator now. Anything else: no keychain.
+ */
+export declare function signInsKeychain(store: Store, repo: string | null): boolean;
 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;
@@ -162,3 +170,12 @@ 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;