toolroll 0.9.103 → 0.9.105

package/dist/agent-fence.js

@@ -1,26 +1,3 @@
-/**
- * The agent fence: what no build, plan, scout or repair agent may read or write, whatever its permission mode. Agents
- * run as the operator's own OS user, so without it an agent could read the approver's remembered login
- * (`up-login.txt`), runner and coordinator tokens, provider keys, project tool secrets, other runs' evidence, or the
- * live database — and use them to approve its own work. The fence closes that at the operating system, not in the
- * model's instructions.
- *
- * The sandbox itself is Anthropic's sandbox-runtime (sandbox-runtime.ts): every macOS Seatbelt profile and every Linux
- * bubblewrap + seccomp invocation is generated by its code, with its baseline, its mandatory write denies (shell
- * profiles, .git/hooks, .vscode, .mcp.json and the rest) and its limits. This module decides only the few static rules
- * Toolroll passes it (srtTermsOf): Toolroll's own state and database denied to read and write; the build's own
- * checkout writable; other tasks' checkouts read, never written; the project's read-deny list; under policy v1 (an
- * approval sealed before 0.9.70) the home configuration denied by name; a sign-ins check's exact files read again; the
- * run's proxy as its only way out when its network is confined. On macOS every launch also gets a pseudo-terminal of its
- * own and no other terminal, a project check's launch Chromium's own service, and only a build's agent the keychain
- * (sandbox-runtime.ts seatbeltRulesFor, static rules).
- *
- * Codex (every platform) fences its own agent's commands with its own sandbox: a permission profile with the same
- * denies (codexFenceArgv). Claude also gets Read/Edit deny rules for its own file tools.
- *
- * A build's fence also holds its task boundary (`taskBoundary`): under v1 the home configuration and the repositories
- * beside its own; under v2 only the primary checkout write-denied.
- */
 import { INSTANCE_DIR } from "./console-instance.js";
 import { ACP_AGENTS, ACP_PROVIDER_IDS } from "./acp-agents.js";
 import { spawnSync } from "node:child_process";
@@ -39,7 +16,6 @@ import { SEATBELT_PROBE, sandboxRuntimeProblem, srtSpawn } from "./sandbox-runti
 import { protectedStorageDenies, protectedStorageNames } from "./protected-storage.js";
 import { ensureSecretsDir, legacyLoginFileOf, SECRETS_DIR, secretsDirOf } from "./login-secrets.js";
 import { getDefaultWritePaths } from "@anthropic-ai/sandbox-runtime";
-/** Names that are secrets wherever the database lives (used when its folder is shared with other things). */
 const SENSITIVE_NAME = /(^up-login\.txt$|token|secret|login|password|credential|vapid|keys?\b|\.pem$|\.key$|^backups$|^evidence$|^remote$|^sign-in\.json$|^monitoring\.json$)/i;
 function real(path) {
     try {
@@ -55,7 +31,6 @@ function inside(child, parent) {
 }
 export class CheckoutBindingError extends Error {
 }
-/** One small file read only as the regular file it is: never through a link, never blocking on a FIFO; null otherwise. */
 function regularText(path) {
     let fd = null;
     try {
@@ -82,8 +57,6 @@ export function trustedWorktreeBinding(repository, worktree, poolRoots = []) {
     const fail = () => new CheckoutBindingError("The checkout's Git pointer was changed or its trusted binding could not be verified.");
     const registry = join(main, ".git", "worktrees");
     try {
-        // The registry may legitimately contain the destination of an attacker link.
-        // Check the recorded name before accepting that destination as this run's checkout.
         if (realpathSync(worktree) !== join(realpathSync(dirname(worktree)), basename(worktree)))
             throw fail();
         for (const root of poolRoots) {
@@ -92,8 +65,6 @@ export function trustedWorktreeBinding(repository, worktree, poolRoots = []) {
             const components = [];
             for (let component = resolve(worktree); component !== dirname(component); component = dirname(component)) {
                 components.push(component);
-                // Permit system aliases above the trusted pool (e.g. /var -> /private/var),
-                // but no redirect at or below it, including older checkout names.
                 if (real(component) !== real(root) && component !== resolve(root))
                     continue;
                 for (const one of components)
@@ -104,10 +75,6 @@ export function trustedWorktreeBinding(repository, worktree, poolRoots = []) {
         }
         if (!lstatSync(join(main, ".git")).isDirectory() || !lstatSync(registry).isDirectory())
             throw fail();
-        // The trusted checkout's own worktree registry, never the candidate's configurable Git pointer — read as files, with
-        // no git at all (eval-harness review 2, finding 6): the repository's config is shared with every build, so an
-        // include naming a FIFO could hold a git read (and dispatch) up; a FIFO or link planted as a registry file is never
-        // opened as one (regularText).
         for (const entry of readdirSync(registry)) {
             const path = join(registry, entry);
             if (!lstatSync(path).isDirectory() || !inside(real(path), real(registry)))
@@ -127,33 +94,16 @@ export function trustedWorktreeBinding(repository, worktree, poolRoots = []) {
     }
     throw fail();
 }
-/**
- * Every path an agent must not reach: the Toolroll state folder
- * beside the database (all of it, except the folder that holds this run's
- * own worktree), the database itself with its journal files, and
- * `~/.toolroll` or an older `~/.standing-orders` (provider keys and project tool secrets). When the
- * database sits anywhere else (a shared folder), only the database and
- * secret-looking entries there are fenced.
- */
 export function agentFence(options) {
     const fence = new Set();
-    /** The console's run folder: kept by its own pathname through canonicalization (and its target's too). */
     let runFolder = null;
     const home = real(options.home ?? homedir());
     const worktree = options.worktree === null ? null : real(options.worktree);
     if (options.databaseFile !== null && options.databaseFile !== "" && options.databaseFile !== ":memory:") {
         const database = real(options.databaseFile);
         const state = dirname(database);
-        // By name, there or not (a journal made later is denied too wherever a fence denies by name: Seatbelt and Codex).
         for (const suffix of ["", "-wal", "-shm", "-journal"])
             fence.add(database + suffix);
-        // The console's run folder (its discovery sockets, console-instance.ts) beside the database, wherever that is: no
-        // build may add, rename or remove anything in it while a console listens there. It is made (owner-only) before any
-        // build starts if it isn't there yet, so a build can never be the one to create it — and the fence always has a
-        // Whatever is at that path is fenced, always — a folder, a file, a link (the path itself, never only where a link
-        // points), a folder holding anything at all — so no build can replace it; when nothing is there it is made first.
-        // If it can't be made, the path is fenced anyway: a sandbox that can't cover a missing path refuses to launch
-        // rather than run unfenced. The name is Toolroll's own; nothing else belongs there.
         runFolder = join(state, INSTANCE_DIR);
         const present = () => { try {
             lstatSync(runFolder);
@@ -166,48 +116,34 @@ export function agentFence(options) {
             try {
                 mkdirSync(runFolder, { mode: 0o700 });
             }
-            catch { /* fenced below either way */ }
+            catch { }
         }
         fence.add(runFolder);
         const runnerFolder = join(state, RUNNER_PROCESS_DIR);
         try {
             ensureRunnerProcessFolder(runnerFolder);
         }
-        catch { /* both the name and its target stay denied */ }
+        catch { }
         fence.add(runnerFolder);
         fence.add(real(runnerFolder));
-        // A copy may first appear after launch. Fence its permanent namespace even when empty.
         const backups = join(state, "backups");
         try {
             mkdirSync(backups, { mode: 0o700 });
         }
-        catch { /* name and target remain denied */ }
+        catch { }
         fence.add(backups);
         fence.add(real(backups));
-        // Saved credentials (the remembered login, login-secrets.ts) live in a reserved owner-only folder, made here before
-        // any launch and denied whole, so one first written after this launch is behind this fence too: a listing can't
-        // name a file that isn't there yet, and bubblewrap can't deny one. If it can't be made or proven, its name is
-        // denied anyway (and nothing is saved there).
         const secrets = secretsDirOf(state);
         try {
             ensureSecretsDir(state);
         }
-        catch { /* name and target remain denied */ }
+        catch { }
         fence.add(secrets);
         fence.add(real(secrets));
-        // An older version's login beside the database: listed below when it is there; by name, there or not, where the
-        // sandbox denies a missing path without making it (Seatbelt; Codex's profile gets the same list). On Linux a
-        // missing path would be stubbed into being for the launch, and nothing writes that name any more.
         const legacyLogin = legacyLoginFileOf(state);
         if (process.platform === "darwin" || existsSync(legacyLogin))
             fence.add(legacyLogin);
-        // Only a folder that is Toolroll's own (~/.config/toolroll or an older name,
-        // the desktop app's "Toolroll") is fenced whole: a database kept
-        // in a shared folder (a projects folder, a test's temp folder) must not
-        // fence its neighbours, the repositories agents build among them.
         const dedicated = state !== home && state !== sep && !existsSync(join(state, ".git")) && /standing[\s_-]?orders|toolroll|nightorders/i.test(basename(state));
-        // The entries this run's worktree needs stay reachable: the one it lives
-        // under, and the repository its git metadata belongs to.
         const keep = new Set();
         for (const needed of [worktree, options.binding?.main ?? null]) {
             if (needed !== null && inside(needed, state))
@@ -221,23 +157,19 @@ export function agentFence(options) {
             entries = [];
         }
         for (const entry of entries) {
-            // A repository is work, never a secret.
             if (keep.has(entry) || existsSync(join(state, entry, ".git")))
                 continue;
             if (dedicated || SENSITIVE_NAME.test(entry))
                 fence.add(join(state, entry));
         }
     }
-    // The plane's private views of repositories for its own git (git-views.ts): made first, so no build is the one to
-    // create them, and denied by name whether or not that worked (a sandbox that can't cover the path refuses to launch).
     try {
         ensureGitViewsRoot(home);
     }
-    catch { /* fenced by name below either way */ }
+    catch { }
     fence.add(gitViewsRoot(home));
     for (const secrets of existingFolders(home, { dot: true }))
         fence.add(secrets);
-    // v104: the folder the audit stream writes to holds the whole instance's history.
     if (options.databaseFile !== null && options.databaseFile !== "" && options.databaseFile !== ":memory:") {
         const stream = readMonitoring(dirname(real(options.databaseFile))).folder?.path;
         if (stream !== undefined)
@@ -245,12 +177,9 @@ export function agentFence(options) {
     }
     for (const path of options.extra ?? [])
         fence.add(real(path));
-    // Secret, state, database, explicit-extra and home-config denies are never exemptible.
     for (const path of options.boundary?.protectedShell ?? [])
         fence.add(real(path));
     const protectedPaths = new Set([...fence].flatMap(path => path === runFolder || [RUNNER_PROCESS_DIR, "backups", SECRETS_DIR].includes(basename(path)) ? [path, real(path)] : [real(path)]));
-    // Protected storage (chat apps, browser profiles, password managers): every launch, every policy, never exemptible,
-    // kept by the name it was resolved under as well as where it leads.
     const storage = options.protectedStorage ?? protectedStorageDenies(home);
     for (const path of storage) {
         protectedPaths.add(path);
@@ -267,34 +196,15 @@ export function agentFence(options) {
         return false;
     }).sort();
 }
-/**
- * Credentials and agent configuration in the home folder. A build is the
- * operator's own OS user, so without this it could read their SSH keys,
- * cloud logins or another agent's sign-in, or rewrite their own Claude or
- * Codex setup for the next interactive session.
- */
 const HOME_CONFIGURATION = [
     ".claude", ".claude.json", ".codex", ".gemini", ".ssh", ".aws", ".gnupg", ".netrc", ".git-credentials", ".kube", join(".config", "gh"), join(".docker", "config.json"),
-    // Every ACP agent's own configuration and sign-in (acp-agents.ts): fenced from every build but that agent's own.
     ...ACP_PROVIDER_IDS.flatMap(id => ACP_AGENTS[id].home),
 ];
-/** What a provider's own CLI reads to sign in and keep its sessions. The OS fence around Claude and Gemini holds
- * their whole process, so those stay reachable there; Codex fences only its agent's commands, so it keeps none. */
 const PROVIDER_HOME = {
     claude: [".claude", ".claude.json"], gemini: [".gemini"], codex: [], openrouter: [],
-    // Each ACP agent keeps its own configuration and sign-in where its row says (acp-agents.ts).
     ...Object.fromEntries(ACP_PROVIDER_IDS.map(id => [id, ACP_AGENTS[id].home])),
 };
-/** What Claude's own file tools refuse inside its home: the CLI reads these itself, its model never needs to. */
 const CLAUDE_FILE_TOOL_HOME = [".claude.json", join(".claude", ".credentials.json"), join(".claude", "settings.json"), join(".claude", "settings.local.json"), ".npmrc"];
-/**
- * Everything outside a task's own folders that a build could otherwise
- * reach: the home configuration above, the other repositories beside its
- * project (and other tasks' worktrees beside its own), and the project's
- * primary checkout — all but its `.git`, which the worktree's git needs.
- * The task's worktree, the files Toolroll makes for the run (in the
- * system temp folder) and everything else stay as they are.
- */
 export function taskBoundary(options) {
     const home = real(options.home ?? homedir());
     const worktree = real(options.worktree);
@@ -303,9 +213,6 @@ export function taskBoundary(options) {
     const needed = [worktree, main, gitdir].filter((path) => path !== null);
     const own = new Set(PROVIDER_HOME[options.provider] ?? []);
     const present = (names) => names.map(name => join(home, name)).filter(path => existsSync(path)).map(real);
-    // Policy v2 (docs/plans/sandbox-parity.md §1.2): the home folder, the repositories beside this one and the project's
-    // primary checkout are read as Anthropic's sandbox runtime reads them; only writes to the primary checkout stay denied.
-    // Protected storage by name, under both policies (protected-storage.ts): never part of the v1-only home configuration.
     const storage = options.storage?.names ?? protectedStorageNames(home);
     if ((options.policy ?? 1) === 2)
         return v2Boundary(worktree, main, gitdir, storage);
@@ -313,8 +220,6 @@ export function taskBoundary(options) {
     const protectedShell = [...shell, ...storage];
     const repository = (path) => existsSync(join(path, ".git"));
     for (const parent of new Set([dirname(worktree), ...(main === null ? [] : [dirname(main)])])) {
-        // Home contains toolchain clones such as .nvm and .oh-my-zsh. The
-        // explicit configuration fence above owns home, not repository discovery.
         if (real(parent) === home)
             continue;
         let entries = [];
@@ -352,14 +257,9 @@ export function taskBoundary(options) {
     }
     const { readOnly, lookup } = siblingGitData(main, gitdir);
     const fileTools = options.provider === "claude" ? present(CLAUDE_FILE_TOOL_HOME).filter(path => !shell.has(path)) : [];
-    // By name too, present or not: a build started while ~/.codex is absent must never make it (and later swap it for a
-    // link while a sign-ins check reads through it). The sandbox runtime takes them as read and write denies by name.
     const homeNames = HOME_CONFIGURATION.filter(name => !own.has(name)).map(name => join(home, name)).sort();
     return { protectedShell, shell: [...shell].sort(), fileTools: fileTools.sort(), readOnly: [...readOnly].sort(), lookup: [...lookup].sort(), homeNames };
 }
-/** A v2 boundary: nothing of the home folder, the repositories beside this one or the primary checkout is denied to
- * read; the primary checkout (all but its `.git`, which this worktree's Git needs) is never written; other tasks' Git
- * metadata is read, never written, as under v1. */
 function v2Boundary(worktree, main, gitdir, storage) {
     const noWrite = new Set();
     if (main !== null && main !== worktree) {
@@ -381,11 +281,6 @@ function v2Boundary(worktree, main, gitdir, storage) {
         readOnly.add(path);
     return { protectedShell: [...storage], shell: [], fileTools: [], readOnly: [...readOnly].sort(), lookup: [...lookup].sort(), homeNames: [] };
 }
-/**
- * Git needs this worktree's metadata and the shared objects/refs, but must not prune or rewrite the metadata of another
- * task's checkout. It still reads that metadata (gc keeps what a sibling's HEAD and index reach) and looks up the
- * checkout it names: a checkout it can't see is one `git worktree prune` deletes the entry of.
- */
 function siblingGitData(main, gitdir) {
     const readOnly = new Set();
     const lookup = new Set();
@@ -399,8 +294,6 @@ function siblingGitData(main, gitdir) {
             entries = [];
         }
         for (const entry of entries) {
-            // Only a plain folder, by the name git gave it: a link a build planted here (to ~/.toolroll, say) is never
-            // followed into a grant, which a sandbox that lets the more specific path win would honour over the fence.
             const path = join(siblings, entry);
             if (path === gitdir)
                 continue;
@@ -422,8 +315,6 @@ function siblingGitData(main, gitdir) {
             if (pointer === undefined || pointer === "" || !isAbsolute(pointer))
                 continue;
             const checkout = dirname(real(pointer));
-            // The entry's pointer is build-writable: look up only a checkout whose own .git names this entry back, as git
-            // links a real one, so a planted pointer can't lift a fenced path's metadata.
             if (worktreeGitDir(checkout) !== path)
                 continue;
             lookup.add(checkout);
@@ -432,21 +323,13 @@ function siblingGitData(main, gitdir) {
     }
     return { readOnly, lookup };
 }
-/** The prefixes of every launch's private folders: its tools' config and a Codex build's own home (and a check's). */
 export const RUN_FOLDER_PREFIXES = ["so-tools-", "so-codex-", "so-net-", "so-cmd-"];
 export function runFolders(own, root) {
-    // The system's own roots (not one a caller names): on a Mac, checks' launch folders are under the short one too.
     const also = root === undefined && process.platform === "darwin" && existsSync(CHECK_LAUNCH_ROOT_MACOS) ? [CHECK_LAUNCH_ROOT_MACOS] : [];
     return { root: real(root ?? tmpdir()), own: own === null ? null : real(own), ...(also.length === 0 ? {} : { also }) };
 }
-/** Where a check's launch folder is made on a Mac: a short shared folder, so its TMPDIR leaves room for a unix socket
- * path (about 104 bytes). */
 export const CHECK_LAUNCH_ROOT_MACOS = "/private/tmp";
-/** The folder a check's launch folder is made in: on a Mac the short one, elsewhere the system temp folder. */
 export const checkLaunchRoot = () => process.platform === "darwin" && existsSync(CHECK_LAUNCH_ROOT_MACOS) ? CHECK_LAUNCH_ROOT_MACOS : tmpdir();
-/** Every other launch's private folder in the system temp folder now, each only as the real folder it is (a link planted
- * there is never followed, nor fenced in its target's place) and this user's own. A shared root (`also`, /private/tmp on
- * a Mac) is never listed: anyone may plant entries there, so it is fenced by name pattern alone. */
 function otherRunFolders(folders) {
     let entries = [];
     try {
@@ -468,33 +351,23 @@ function otherRunFolders(folders) {
         }
     });
 }
-/** Every root launch folders are made under (the system temp folder, and on a Mac the short shared one). */
 export const runRoots = (folders) => [folders.root, ...(folders.also ?? [])];
 export { isWritesMode, WRITES_DEFAULT } from "./writes-mode.js";
-/** Claude's transcript folder for a working folder: its path with every character but a letter or digit made `-`
- * (Claude Code's own naming; a name over 200 characters gets a suffix, so it is granted by prefix). */
 export function claudeProjectFolder(home, cwd) {
     const slug = cwd.replace(/[^a-zA-Z0-9]/g, "-");
     return slug.length > 200 ? { path: join(home, ".claude", "projects", slug.slice(0, 200)), byPrefix: true } : { path: join(home, ".claude", "projects", slug), byPrefix: false };
 }
-/**
- * A folder a write grant may name: made when absent, then only as the real folder it is — never a link, nor reached
- * through one (its real path is its parent's real path and its own name). A build can rewrite what it may write, so a
- * folder it was given could otherwise come back as a link to anywhere and be granted, followed, on its next launch.
- * Null when it isn't such a folder: nothing is granted, and the write it was for fails.
- */
 export function grantFolder(path, create = true) {
     if (create) {
         try {
             mkdirSync(path, { recursive: true, mode: 0o700 });
         }
-        catch { /* checked below */ }
+        catch { }
     }
     try {
         const held = lstatSync(path);
         if (held.isSymbolicLink() || !held.isDirectory())
             return null;
-        // Nor through a link of this user's anywhere above it (a system alias, /var → /private/var, is root's and fine).
         const uid = process.getuid?.();
         for (let folder = dirname(resolve(path)); folder !== dirname(folder); folder = dirname(folder)) {
             const above = lstatSync(folder);
@@ -508,42 +381,23 @@ export function grantFolder(path, create = true) {
         return null;
     }
 }
-/**
- * The data folders an ACP agent writes besides a ~/.local/share|state root, per agent, only where known: Goose's
- * sessions and state; Qwen Code (a Gemini CLI fork) its history and temp, as Gemini measured. An agent not listed
- * (Cursor, Cline: their settings sit among their data) writes nothing of its own under a workspace build until its
- * layout is measured; a project using one chooses `anywhere`.
- */
 const ACP_DATA = {
     goose: [".local/share/goose", ".local/state/goose"],
     qwen: [".qwen/tmp", ".qwen/history"],
 };
-/** The suffix Claude Code gives a transcript folder whose name it shortened: `-` and a hash, nothing else. */
 const CLAUDE_SHORTENED = "-[a-z0-9]+(/|$)";
-/** A file and the temporary names it is replaced through (`name.tmp-1`, `name.json.12345`), never a folder below it. */
 const ATOMIC_NAMES = "([.~][^/]*)?$";
-/** The parts of a repository's shared Git data a commit in a worktree writes: objects, refs and their logs (and the
- * packed refs). Its config, hooks, info, other worktrees' data and submodules' are never among them. */
 function commitGitData(common) {
     const made = (path) => { try {
         mkdirSync(path, { recursive: true });
     }
-    catch { /* granted as named */ } return real(path); };
+    catch { } return real(path); };
     return {
         subpaths: ["objects", "refs", "logs"].map(name => grantFolder(join(common, name))).filter((path) => path !== null),
         prefixes: [{ path: join(common, "packed-refs"), suffix: ATOMIC_NAMES }],
-        // Alternates there would let objects come from anywhere.
         readOnly: [made(join(common, "objects", "info"))],
     };
 }
-/**
- * What a `workspace` build writes and what it loses (arc 2): its checkout, its checkout's Git data (less the shared
- * repository's config, hooks and info, which Git runs or reads as commands), its own launch folder (its temp is there),
- * its project's cache folder, the terminal devices, and only the provider state its CLI must write (measured: Claude's
- * transcript folder for this checkout; Gemini's history, temp and project list; an ACP agent's own folders). The
- * folders named here are made first, so the provider never has to make them where it can't. `deny` is what this
- * provider must not even read (Claude's live sessions' keys).
- */
 export function writeAllowlist(options) {
     const home = real(options.home);
     const worktree = real(options.worktree);
@@ -554,15 +408,13 @@ export function writeAllowlist(options) {
     const made = (path) => { try {
         mkdirSync(path, { recursive: true, mode: 0o700 });
     }
-    catch { /* granted as named either way */ } return real(path); };
+    catch { } return real(path); };
     const grant = (path, create = true) => { const at = grantFolder(path, create); if (at !== null)
         subpaths.add(at); };
     if (options.binding !== null) {
         const common = real(join(options.binding.main, ".git"));
         const gitdir = real(options.binding.gitdir);
         grant(gitdir, false);
-        // The shared Git data a commit writes, and nothing Git reads as commands or settings: the shared config (filters,
-        // hooks path, fsmonitor), hooks, info (attributes, excludes), other worktrees' data and submodules' stay as they are.
         const data = commitGitData(common);
         for (const path of data.subpaths)
             subpaths.add(path);
@@ -570,13 +422,12 @@ export function writeAllowlist(options) {
             prefixes.set(`${one.path}\0${one.suffix}`, one);
         for (const path of data.readOnly)
             readOnly.add(path);
-        // This worktree's own settings file, present (empty) so it is held read-only everywhere, a bind included.
         const own = join(gitdir, "config.worktree");
         try {
             if (!existsSync(own))
                 writeFileSync(own, "", { mode: 0o644, flag: "wx" });
         }
-        catch { /* held read-only by name */ }
+        catch { }
         readOnly.add(own);
     }
     if (options.launchFolder !== null)
@@ -599,8 +450,6 @@ export function writeAllowlist(options) {
         prefixes.set("gemini", { path: join(home, ".gemini", "projects.json"), suffix: ATOMIC_NAMES });
     }
     else if (Object.hasOwn(ACP_AGENTS, options.provider)) {
-        // An ACP agent's configuration stays read-only whole (its MCP servers, hooks, plugins, agents and commands could
-        // otherwise be planted for the operator's next session of it); only its known data folders are written (ACP_DATA).
         for (const name of ACP_AGENTS[options.provider].home)
             if (/^\.local\/(share|state)\//.test(name))
                 grant(join(home, name));
@@ -609,13 +458,10 @@ export function writeAllowlist(options) {
     }
     return { writes: { subpaths: [...subpaths].sort(), prefixes: [...prefixes.values()].sort((a, b) => a.path.localeCompare(b.path)) }, readOnly: [...readOnly].sort(), deny: [...deny].sort() };
 }
-/** Where a project's builds keep their package caches: one folder per project (one trust domain), never used by the
- * plane's own tools, below the user's cache folder. */
 export function buildCacheFolder(repo, home = homedir(), platform = process.platform, env = process.env) {
     const root = platform === "darwin" ? join(home, "Library", "Caches") : env["XDG_CACHE_HOME"] !== undefined && isAbsolute(env["XDG_CACHE_HOME"]) ? env["XDG_CACHE_HOME"] : join(home, ".cache");
     return join(root, "toolroll-builds", createHash("sha256").update(real(repo)).digest("hex").slice(0, 16));
 }
-/** The environment that points a build's package managers at its project's cache folder, not the user's own. */
 export function buildCacheEnv(folder) {
     const at = (name) => join(folder, name);
     return {
@@ -626,14 +472,6 @@ export function buildCacheEnv(folder) {
     };
 }
 export const NO_GRANTS = { readOnly: [], readable: [], lookup: [] };
-/**
- * The pool deny for one launch. `roots` come from the plane's own records (the pool beside the database, and the one
- * the recorded checkout was made in), never from the checkout. A root that holds this checkout's own Git data (the
- * binding's gitdir or the repository's .git) is never denied whole: it is split around that data instead, entry by
- * entry, so it is denied as far as it can be (fail closed by denying more, never by refusing). A root inside the
- * checkout, the home folder, a folder above it or / is left alone: the first is the build's own work, the others the
- * whole machine.
- */
 export function checkoutPool(options, list = path => readdirSync(path)) {
     const own = options.worktree === null ? null : real(options.worktree);
     const home = real(options.home ?? homedir());
@@ -652,7 +490,7 @@ export function checkoutPool(options, list = path => readdirSync(path)) {
         }
         if (needed.includes(path))
             return;
-        const entries = list(path); // An unreadable pool must refuse preparation, never silently widen access.
+        const entries = list(path);
         for (const entry of entries)
             split(join(path, entry));
     };
@@ -671,15 +509,10 @@ export function checkoutPool(options, list = path => readdirSync(path)) {
             lookup.add(folder);
     return { deny: [...deny].sort(), own: holding.length === 0 ? null : own, lookup: [...lookup].sort(), ...(needed.length === 0 ? {} : { gitPaths: needed }) };
 }
-/** The grants for one build: its task boundary's git rules, the shared dependencies its checkout links, and the
- * checkout pools (`poolRoots`, from the plane's records) denied around its own checkout. */
 export function fenceGrants(options) {
     const readable = [];
     const lookup = [...options.boundary?.lookup ?? []];
     if (options.databaseFile !== null && options.databaseFile !== "" && options.databaseFile !== ":memory:" && options.worktree !== null && options.linked != null) {
-        // The link note names the copy as the plane wrote it; the sandbox sees real paths. The note is in the build's own
-        // checkout, so it is only a hint: the copy must be a ready one the plane made for this run's project under the
-        // setup it stamped on this checkout, or nothing is granted.
         const written = join(dirname(options.databaseFile), DEPS_FOLDER);
         const deps = join(dirname(real(options.databaseFile)), DEPS_FOLDER);
         const key = linkedKey(options.worktree, written) ?? linkedKey(options.worktree, deps);
@@ -696,7 +529,6 @@ export function fenceGrants(options) {
         ...(options.boundary?.homeNames === undefined || options.boundary.homeNames.length === 0 ? {} : { homeNames: [...options.boundary.homeNames] }),
         ...(pool === undefined || pool.deny.length === 0 ? {} : { pool }) };
 }
-/** The setup a shared copy was installed by (its ready note), or null. */
 function readySetup(deps, key) {
     try {
         const setup = JSON.parse(readFileSync(join(deps, key, "ready.json"), "utf8")).setup;
@@ -706,11 +538,6 @@ function readySetup(deps, key) {
         return null;
     }
 }
-/**
- * Git settings every fenced build runs with (GIT_CONFIG_COUNT, after any the
- * caller already set): `git gc` never expires a reflog, so it never rewrites
- * another task's reflog, which the fence would refuse mid-collection.
- */
 export function fencedGitEnv(base = process.env) {
     const count = Number.parseInt(base["GIT_CONFIG_COUNT"] ?? "0", 10);
     const start = Number.isInteger(count) && count > 0 ? count : 0;
@@ -719,10 +546,8 @@ export function fencedGitEnv(base = process.env) {
     settings.forEach(([key, value], index) => { env[`GIT_CONFIG_KEY_${start + index}`] = key; env[`GIT_CONFIG_VALUE_${start + index}`] = value; });
     return env;
 }
-/** The repository a git worktree belongs to (its `.git` file names the main repository's git folder). */
 function worktreeGitDir(worktree) {
     try {
-        // The candidate's own pointer file: a FIFO or link there is never opened (review 2, finding 6).
         const text = regularText(join(worktree, ".git"));
         const pointer = text === null ? undefined : /^gitdir:\s*(.+)$/m.exec(text)?.[1]?.trim();
         return pointer === undefined ? null : real(isAbsolute(pointer) ? pointer : join(worktree, pointer));
@@ -732,15 +557,6 @@ function worktreeGitDir(worktree) {
     }
 }
 const toml = (value) => `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
-/**
- * Codex's own sandbox, fenced. Auto: the `:workspace` profile Codex's
- * `--sandbox workspace-write` already gives (workspace and temp writes, no
- * network). Full access: the same profile widened to write anywhere with
- * network on, instead of no sandbox at all. Either way the fenced paths are
- * denied, which in Codex outranks any write or read grant. The checkout pools
- * are never `flattened` (which leaves what is made after launch readable): see
- * `codexPool`, which denies them around the build's own checkout, written back.
- */
 export function codexFenceArgv(fence, fullAccess, grants = NO_GRANTS) {
     const access = codexFilesystem(fence, fullAccess, grants);
     const filesystem = [...access].map(([path, mode]) => `${toml(path)}=${toml(mode)}`);
@@ -748,19 +564,11 @@ export function codexFenceArgv(fence, fullAccess, grants = NO_GRANTS) {
         "-c", 'default_permissions="standing-orders"',
         "-c", `permissions.standing-orders.extends=${grants.writes === undefined ? '":workspace"' : '":read-only"'}`,
         "-c", `permissions.standing-orders.filesystem={${filesystem.join(",")}}`,
-        // Codex's command sandbox can't route through a proxy: its commands reach the network only when the run's sealed
-        // network is open (and Full access asked for it), and are offline otherwise.
         ...(codexNetworkOn(fullAccess, grants) ? ["-c", "permissions.standing-orders.network.enabled=true"] : []),
         ...(fullAccess ? ["-c", 'approval_policy="never"'] : []),
     ];
 }
 const codexNetworkOn = (fullAccess, grants) => fullAccess && (grants.network === undefined || grants.network.mode === "open");
-/**
- * The same permission profile as codexFenceArgv, as the config overrides a Codex app-server thread takes
- * (`thread/start` and `thread/resume` `config`; checked against codex-cli 0.156: the thread reports
- * `activePermissionProfile` standing-orders, and its commands are refused the denied paths). Approval policy is the
- * caller's own (an interactive session asks).
- */
 export function codexFenceConfig(fence, fullAccess, grants = NO_GRANTS) {
     return {
         default_permissions: "standing-orders",
@@ -769,29 +577,18 @@ export function codexFenceConfig(fence, fullAccess, grants = NO_GRANTS) {
         ...(codexNetworkOn(fullAccess, grants) ? { "permissions.standing-orders.network.enabled": true } : {}),
     };
 }
-/** Each path of a Codex permission profile and its access, the strongest last (a deny outranks a grant). */
 function codexFilesystem(fence, fullAccess, grants) {
     const { deny, readOnly } = flattened(fence, grants);
-    // Codex's harness reads its own launch files outside the command sandbox.
-    // Deny the namespace, including folders created after this policy was built.
     if (grants.runFolders !== undefined) {
         for (const root of runRoots(grants.runFolders)) {
             for (const prefix of RUN_FOLDER_PREFIXES)
                 deny.push(join(root, `${prefix}*`), join(root, `${prefix}*`, "**"));
         }
     }
-    // Launch folders can already be in the base fence when invoke appends them.
-    // TOML forbids duplicate keys, even with identical values. Normalize aliases
-    // at this boundary and apply stronger access restrictions last.
     const access = new Map();
     const pool = grants.pool;
-    // Codex lets the more specific path win: no read grant inside a pool, but the build's own checkout.
     const pooled = (path) => pool !== undefined && pool.deny.some(one => path === one || inside(path, one))
         && !(pool.own !== null && (path === pool.own || inside(path, pool.own)));
-    // Full access writes anywhere its fence allows, unless the build writes only its workspace (arc 2): then exactly its
-    // allowlist, in either mode, beside the workspace Codex's own profile gives.
-    // Codex's own workspace profile also writes the shared temp folders; a workspace build starts from its read-only
-    // profile instead, with exactly the allowlist (its checkout among it) written back.
     if (grants.writes !== undefined)
         for (const path of grants.writes.subpaths)
             access.set(real(path), "write");
@@ -806,22 +603,16 @@ function codexFilesystem(fence, fullAccess, grants) {
             access.set(path, "read");
         for (const path of held.deny)
             access.set(path, pool.readable === true && !(pool.sealed ?? []).some(one => path === one || inside(path, one)) ? "read" : "deny");
-        // A sealed folder (flows' scratch) is denied whole, but on the way to this launch's own folder (Codex can't deny an
-        // ancestor and still reach inside it: its other entries are denied one by one, by codexPool, from the same split).
         for (const sealed of pool.sealed ?? [])
             if (!(pool.own !== null && (pool.own === sealed || inside(pool.own, sealed))))
                 access.set(sealed, "deny");
         for (const path of held.write)
             access.set(path, "write");
     }
-    // What no launch writes (homeWriteDenies): read-only, where Codex writes at all (Full access, or an allowlist).
-    // Never inside a denied path: Codex lets the more specific path win, so a read there would bring it back.
     const deniedPaths = deny.filter(one => !one.includes("*")).map(real);
     for (const path of grants.writeDenies ?? []) {
         const leads = resolvedPath(path);
         const denied = (one) => access.get(one) === "deny" || deniedPaths.some(den => one === den || inside(one, den));
-        // A name that leads into a denied path (a linked ~/.ssh into a read-denied folder) is denied by its own name too,
-        // never read back.
         if (denied(leads)) {
             access.set(path, "deny");
             continue;
@@ -830,15 +621,11 @@ function codexFilesystem(fence, fullAccess, grants) {
             continue;
         access.set(path, "read");
     }
-    // Denies are keyed where they resolve; the console's run folder is also denied by its
-    // own pathname, so a link there stays unreplaceable, not only its target.
     for (const path of deny) {
         access.set(real(path), "deny");
         if (basename(path) === INSTANCE_DIR)
             access.set(path, "deny");
     }
-    // Protected storage: denied by name and real path, and nothing granted inside it (Codex lets the more specific path
-    // win, so a grant there would reopen it).
     const storage = grants.protectedStorage ?? [];
     if (storage.length > 0) {
         for (const [path, mode] of [...access])
@@ -851,12 +638,6 @@ function codexFilesystem(fence, fullAccess, grants) {
     }
     return access;
 }
-/**
- * Codex cannot deny an ancestor and still traverse it to the own checkout. Deny existing
- * siblings individually, from the trusted pool roots and a fresh listing, never through
- * flattened or name patterns. A project added after launch is covered on the next launch;
- * Seatbelt and bubblewrap retain the stronger whole-pool rule for later-created projects.
- */
 export function codexPool(pool, list = path => readdirSync(path)) {
     const deny = new Set();
     const read = new Set(pool.lookup);
@@ -881,7 +662,6 @@ export function codexPool(pool, list = path => readdirSync(path)) {
             deny.add(path);
             return;
         }
-        // Only ancestors needed for traversal stay readable, never writable in Full access.
         read.add(path);
         for (const entry of list(path))
             split(join(path, entry));
@@ -890,20 +670,7 @@ export function codexPool(pool, list = path => readdirSync(path)) {
         split(root);
     return { read: [...read].sort(), deny: [...deny].sort(), write: own === null ? [] : [own] };
 }
-/** Secret-looking names denied by pattern inside a folder `flattened` makes read-only, so one written there after
- * launch is denied too (the database and its journals, tokens, login and other text files). */
 export const SPLIT_SECRET_PATTERNS = ["orders.db*", "*token*", "up-login*", "*.txt", "*secret*", "*password*", "*credential*", "*.pem", "*.key"];
-/**
- * A fence as plain denied and read-only paths, for a sandbox that can't
- * grant inside a denied folder (Codex: a deny outranks any grant): a denied
- * folder holding something readable becomes read-only, with each of its
- * entries not on the way to what is readable denied instead. Fails closed: a
- * folder that can't be listed stays denied whole and its grant is dropped.
- * Residual: an entry made after launch in a read-only folder is denied only
- * when its name matches SPLIT_SECRET_PATTERNS; any other new entry there is
- * readable (never writable) until the next launch. The macOS fence has no
- * such gap: it denies the folder and grants back only the readable path.
- */
 export function flattened(fence, grants = NO_GRANTS, list = path => readdirSync(path)) {
     const deny = [];
     const readOnly = new Set(grants.readOnly);
@@ -935,28 +702,16 @@ export function flattened(fence, grants = NO_GRANTS, list = path => readdirSync(
     };
     for (const path of fence)
         split(path);
-    // Fail closed: a grant equal to or inside a denied path is dropped, so no read grant can outrank a deny (Codex lets
-    // the more specific path win). Patterns stay as Codex patterns; they can't contain a grant here.
     const denied = deny.filter(path => !path.includes("*"));
     return { deny, readOnly: [...readOnly].filter(path => !denied.some(one => path === one || inside(path, one))) };
 }
-/** Claude's own file tools refuse the fenced paths in every mode (its shell is fenced by the macOS sandbox), and
- * never edit a read-only one. */
 export function claudeFenceSettings(fence, readOnly = []) {
     const rules = [...fence.flatMap(path => [`Read(/${path})`, `Read(/${path}/**)`, `Edit(/${path})`, `Edit(/${path}/**)`]), ...readOnly.flatMap(path => [`Edit(/${path})`, `Edit(/${path}/**)`])];
     return JSON.stringify({ permissions: { deny: rules } });
 }
 const SANDBOX_EXEC = "/usr/bin/sandbox-exec";
-/** A process already inside a Seatbelt sandbox (an agent's, or a flow check zone's) can't apply another: sandbox-exec says so. */
 const NESTED_SANDBOX = /sandbox_apply: Operation not permitted/;
 let seatbeltWorks = null;
-/**
- * Whether this machine can run an agent inside the macOS fence (checked once). Not from inside another
- * sandbox: a Toolroll a fenced process starts (the end-to-end journeys a flow's check zone runs) can't nest
- * its fence, and would otherwise fail every launch. Its agents stay inside the outer fence, which every
- * child inherits, and are recorded with the fence they actually got. Any other probe failure keeps the
- * fence on, so a launch fails loudly rather than running unfenced.
- */
 export function macosFenceAvailable(platform = process.platform, probe) {
     if (platform !== "darwin" || !existsSync(SANDBOX_EXEC))
         return false;
@@ -977,8 +732,6 @@ export function macosFenceAvailable(platform = process.platform, probe) {
     });
     return seatbeltWorks;
 }
-/** Whether the sandbox runtime can sandbox here on Linux (checked once): bubblewrap, socat, its seccomp helper and
- * ripgrep installed, and unprivileged user namespaces allowed. A machine that can't is no Linux fence at all. */
 let linuxWorks = null;
 export function linuxFenceAvailable(platform = process.platform, probe = () => sandboxRuntimeProblem("linux") === null) {
     if (platform !== "linux")
@@ -993,19 +746,10 @@ export function linuxFenceAvailable(platform = process.platform, probe = () => s
     }
     return linuxWorks;
 }
-/** Thrown when no sandbox can be made for a launch: the spawn road refuses it. */
 export class LinuxFenceUnavailable extends Error {
 }
-/**
- * The runtime's config for a launch (sandbox-runtime.ts SrtTerms), from its fence: every fenced path denied to read and
- * write (with the exact paths read again inside them), the pools' other checkouts write-denied (and, under v1, read-
- * denied) around the build's own, the flows' scratch folders sealed, the launch's writes (its allowlist, or anywhere
- * outside the denies), its mach services and its network.
- */
 export function srtTermsOf(fence, grants = NO_GRANTS) {
     const denyRead = new Set(fence.map(real));
-    // A readable grant's own folder is read too: bundlers (esbuild) find node_modules by listing it. The runtime can't
-    // grant a listing without the folder's files, so the shared copy's folder is read whole (its ready note among them).
     const allowRead = new Set(grants.readable.flatMap(path => grants.exactFiles?.includes(path) === true ? [real(path)] : [real(path), real(dirname(path))]));
     const denyWrite = new Set([...fence, ...grants.readOnly].map(real));
     for (const path of grants.writeDenies ?? [])
@@ -1016,17 +760,11 @@ export function srtTermsOf(fence, grants = NO_GRANTS) {
     }
     for (const file of grants.signIns?.read ?? [])
         allowRead.add(file);
-    // Every other launch's private folder unread by pattern (one made after this launch too), this launch's own read
-    // again. Writes are denied to those there at launch, under every root: the runtime can't write back inside a write
-    // deny, so a pattern would take this launch's own folder too (one made after launch is writable under `anywhere`).
     const folders = grants.runFolders;
     if (folders !== undefined) {
         for (const root of runRoots(folders)) {
             for (const prefix of RUN_FOLDER_PREFIXES)
                 denyRead.add(join(root, `${prefix}*`));
-            // And by name, each there right before the launch (this runs at the spawn): on Linux the runtime gives a pattern
-            // no mask where a path it allows lies beside its matches. Written: only where the launch writes anywhere (under a
-            // write allowlist they are out of its writes already).
             for (const path of otherRunFolders({ root, own: folders.own })) {
                 denyRead.add(path);
                 if (grants.writes === undefined)
@@ -1038,15 +776,11 @@ export function srtTermsOf(fence, grants = NO_GRANTS) {
     }
     const pool = grants.pool;
     if (pool !== undefined) {
-        // Under v1 the pools are unread too, the build's own checkout read again; under v2 they are read (owner Q-C).
         if (pool.readable !== true)
             for (const root of pool.deny)
                 denyRead.add(root);
-        // The build's own checkout is read again inside whatever is denied around it (the pools, a flow's sealed scratch).
         if (pool.own !== null)
             allowRead.add(pool.own);
-        // Never written but the build's own checkout: the runtime can't write back inside a write deny, so each other
-        // entry on the way is denied instead (codexPool's split, as Codex takes it).
         for (const path of codexPool(pool).deny)
             denyWrite.add(path);
         for (const sealed of pool.sealed ?? []) {
@@ -1055,7 +789,6 @@ export function srtTermsOf(fence, grants = NO_GRANTS) {
                 denyWrite.add(sealed);
         }
     }
-    // Protected storage last: denied to read and write by name and real path, and no read grant inside it survives.
     const storage = grants.protectedStorage ?? [];
     const isProtected = (path) => storage.some(one => path === one || inside(path, one) || real(path) === one || inside(real(path), one));
     for (const path of storage) {
@@ -1067,11 +800,7 @@ export function srtTermsOf(fence, grants = NO_GRANTS) {
             allowRead.delete(path);
     const readConfig = { denyOnly: [...denyRead].sort(), allowWithinDeny: [...allowRead].sort() };
     const writes = grants.writes;
-    // A sign-ins check also writes Codex's session and log folders and its own Claude transcripts (never inside a
-    // write deny: under policy v1 the home configuration stays unwritten whole).
     const signInWrites = [...grants.signIns?.writes ?? [], ...(grants.signIns?.transcripts ?? []).map(folder => join(folder, "*.jsonl"))];
-    // Writing anywhere: everything but the denies. The launch's own checkout and folder are named too, so a backend that
-    // binds a read deny's re-allowed paths back (bubblewrap) binds those back writable.
     const allowOnly = writes === undefined ? ["/", ...(pool?.own == null ? [] : [real(pool.own)]), ...(folders?.own == null ? [] : [folders.own])]
         : [...writes.subpaths, ...writes.prefixes.map(one => `${one.path}*`), ...signInWrites, ...getDefaultWritePaths({ denyRead: readConfig.denyOnly, allowRead: readConfig.allowWithinDeny })];
     const network = grants.network;
@@ -1087,15 +816,9 @@ export function srtTermsOf(fence, grants = NO_GRANTS) {
         },
     };
 }
-/** The spawn that runs `file args` from `cwd` inside the sandbox runtime's sandbox (sandbox-runtime.ts srtSpawn), and the
- * environment it needs beside the caller's. */
 export function sandboxedSpawn(file, args, fence, grants = NO_GRANTS, cwd, temp) {
     return srtSpawn(file, args, srtTermsOf(fence, grants), cwd ?? process.cwd(), temp);
 }
-/**
- * What each agent's fence gives it, by permission mode: the one table "What an agent can reach" in
- * docs/guide/security.md shows (fenceSummaryMarkdown; a test holds them equal).
- */
 export const FENCE_SUMMARY = [
     {
         agent: "**Claude, Gemini, ACP agents**",
@@ -1108,40 +831,22 @@ export const FENCE_SUMMARY = [
         full: "the same reads and writes, with the fence; its commands reach the network only when the project's network is open",
     },
 ];
-/** FENCE_SUMMARY as the security guide's markdown table. */
 export function fenceSummaryMarkdown() {
     return ["| | Auto | Full access |", "|---|---|---|", ...FENCE_SUMMARY.map(row => `| ${row.agent} | ${row.auto} | ${row.full} |`)].join("\n");
 }
-/** The sign-in files a `sign-ins` check reads, by fixed name under the person's home (never from the environment, so no
- * caller's CLAUDE_CONFIG_DIR or GH_CONFIG_DIR points a grant at .ssh): Claude's account and settings (and, on Linux,
- * its credentials file; on a Mac they are in the keychain), gh's hosts and config, and Codex's config and sign-in. */
 const SIGN_IN_FILES = (platform) => [
     ".claude.json", join(".claude", "settings.json"), ...(platform === "linux" ? [join(".claude", ".credentials.json")] : []),
     join(".config", "gh", "hosts.yml"), join(".config", "gh", "config.yml"), join(".codex", "config.toml"), join(".codex", "auth.json"),
 ];
-/**
- * A `sign-ins` check's grants (sandbox parity C10, srt-style): each sign-in file by its name, read by the check itself
- * through its sandbox. Nothing privileged reads or copies one: the sandbox resolves the name in its own view, so a link
- * planted there into Toolroll's state leads to a denied path (Seatbelt checks the resolved file; bubblewrap resolves
- * inside its mount namespace, where the state is masked). On a Mac, the checkout's own Claude transcript folder (made
- * when absent, only as the real folder it is), whose session files alone are written; and Codex's session and log
- * folders (when ~/.codex is there), never its config.
- */
 export function signInGrants(home, checkout, platform = process.platform) {
     const base = real(home);
-    // Read by name, but only a name that is itself now: every folder from the home folder down a real one, the file a
-    // regular file with one name (never a link, never a hard link to something else). The sandbox resolves it again.
     const read = SIGN_IN_FILES(platform).map(name => join(base, name)).filter(path => signInIsItself(base, path));
     const transcript = claudeProjectFolder(base, real(checkout));
-    // A transcript folder Claude would name by prefix (a very long checkout path) isn't granted: never a prefix of others.
     const folder = transcript.byPrefix || !existsSync(join(base, ".claude")) ? null : grantFolder(transcript.path);
     const codex = join(base, ".codex");
     const writes = grantFolder(codex, false) === null ? [] : ["sessions", "log"].map(name => grantFolder(join(codex, name))).filter((path) => path !== null);
     return { read, transcripts: folder === null || platform !== "darwin" ? [] : [folder], writes, mach: platform === "darwin" ? ["com.apple.trustd.agent"] : [] };
 }
-/** Whether a sign-in file is itself, now: every folder from the (real) home folder down a real folder, the file a
- * regular file with one name (never a link, never a hard link to something else). Checked when granted and again right
- * before the launch (invoke.ts); the sandbox resolves the name a third time. */
 export function signInIsItself(base, path) {
     let at = base;
     const parts = relative(base, path).split(sep);
@@ -1162,48 +867,32 @@ export function signInIsItself(base, path) {
 }
 export const FENCE_POLICY_CURRENT = 2;
 export const LEGACY_SANDBOX = { policy: 1, readDeny: [], machLookup: [] };
-/** A build's sandbox terms, exactly as its approval sealed them: an approval from before 0.9.70 is policy v1 (the home
- * configuration denied) with nothing listed. */
 export function launchSandboxOf(profile) {
     return { policy: profile.fencePolicy ?? 1, readDeny: profile.readDeny ?? [], machLookup: profile.machLookup ?? [] };
 }
-/** The one place a launch's fence is made (docs/plans/sandbox-parity.md C1): its denies, its grants, and
- * `confinement: "required"`, so the spawn road refuses it where no OS fence applies rather than running it bare. */
 export function fenceFor(kind, ctx) {
     const home = ctx.home === undefined ? {} : { home: ctx.home };
-    // The project's read denies join the fence by name, there or not (the runtime denies a path that isn't there yet).
-    // Protected storage, resolved once for this launch, from the plane's own environment (protected-storage.ts).
     const storage = ctx.storage?.denies ?? protectedStorageDenies(ctx.home ?? homedir());
     const fence = agentFence({ databaseFile: ctx.databaseFile, worktree: ctx.worktree, ...home, boundary: ctx.boundary, binding: ctx.binding, runFolders: ctx.runFolders, extra: [...ctx.extra ?? [], ...ctx.readDeny ?? []], protectedStorage: storage });
     const found = fenceGrants({ databaseFile: ctx.databaseFile, worktree: ctx.worktree, boundary: ctx.boundary, runFolders: ctx.runFolders, linked: ctx.linked ?? null, binding: ctx.binding, ...home, poolRoots: ctx.poolRoots });
-    // Toolroll's own install, the sandbox runtime's package and the Node running them, never written by anything it
-    // launches: rewriting the code that fences a build would switch the fence off.
     const made = { ...found, readOnly: [...new Set([...found.readOnly, ...toolrollInstall(ctx.worktree, ctx.home ?? homedir(), ctx.binding?.main ?? null)])].sort() };
     const written = ctx.writes ?? null;
     const exact = ctx.exactFile ?? null;
     const grants = {
         ...made,
         ...(written === null ? {} : { writes: written.writes, readOnly: [...new Set([...made.readOnly, ...written.readOnly])].sort() }),
-        // One exact file, granted as the shared dependencies are, and never written (Claude's Edit rules read `readOnly`).
         ...(exact === null ? {} : { readable: [...made.readable, exact], exactFiles: [exact], readOnly: [...new Set([...made.readOnly, ...(written?.readOnly ?? []), exact])].sort() }),
         ...(ctx.network === undefined ? {} : { network: ctx.network }),
         ...(ctx.machLookup === undefined || ctx.machLookup.length === 0 ? {} : { machLookup: [...ctx.machLookup] }),
-        // A project's checks may drive a browser (Playwright's Chromium), and so may a flow's script zone whose browser use
-        // a person approved (the caller proves it at launch); builds, tool servers and every other flow launch don't get it.
         ...(kind === "check" || (kind === "flow" && ctx.browser === true) ? { browser: true } : {}),
-        // A build's agent signs in from the keychain (Claude Code does); nothing else it launches reaches it.
         ...(kind === "build" ? { keychain: true } : {}),
-        // Under a write allowlist these are out of reach already; where the launch writes anywhere, they are denied by name.
         writeDenies: homeWriteDenies(ctx.home ?? homedir(), ctx.binding, ctx.provider ?? null),
         protectedStorage: storage,
         ...(made.pool === undefined ? {} : { pool: { ...made.pool, ...(ctx.policy === 2 ? { readable: true } : {}),
-                // Flows' scratch folders in the pool (and any the caller names) stay denied whole, at every policy version.
                 sealed: sealedScratch(ctx.poolRoots, ctx.scratchRoots ?? []) } }),
     };
     return { kind, fence, fenceGrants: grants, confinement: "required" };
 }
-/** The flows' scratch folders inside the checkout pools (`flow-checks` beside the checkouts) and any a caller names,
- * each denied by name whether or not it is there yet, and where it is a link, where it leads too. */
 export function sealedScratch(poolRoots, named) {
     const out = new Set();
     for (const path of [...poolRoots.filter((root) => root !== null).map(root => join(real(root), "flow-checks")), ...named.map(one => join(real(dirname(one)), basename(one)))]) {
@@ -1212,18 +901,10 @@ export function sealedScratch(poolRoots, named) {
             if (lstatSync(path).isSymbolicLink())
                 out.add(realpathSync(path));
         }
-        catch { /* not there, or dangling: denied by name */ }
+        catch { }
     }
     return [...out].sort();
 }
-/**
- * Toolroll's own install as no launch may write it: this package's folder (its compiled code, the sandbox launch
- * helper among it), the sandbox runtime's package wherever it was installed, and the Node running them with the
- * folder it lives in (its npm and global packages beside it), as the real folders they are. Never a folder that holds
- * the launch's own checkout or its repository (a build of Toolroll's own source, run from it: that repository's other
- * files are the primary checkout's, write-denied already), the home folder or one above it, and nothing the user
- * doesn't own (root's folders are out of a build's reach already).
- */
 export function toolrollInstall(worktree, home, repository = null) {
     const own = worktree === null ? null : real(worktree);
     const repo = repository === null ? null : real(repository);
@@ -1246,37 +927,21 @@ export function toolrollInstall(worktree, home, repository = null) {
     return [...new Set(candidates)].filter(path => path !== dirname(path) && path !== homeReal && !inside(homeReal, path)
         && !(own !== null && (own === path || inside(own, path))) && !(repo !== null && (repo === path || inside(repo, path))) && ours(path)).sort();
 }
-/** Names that run code or reconfigure tools for whoever opens the project next: the sandbox runtime's DANGEROUS_FILES
- * (@anthropic-ai/sandbox-runtime sandbox-utils), and the names its mandatory denies can't hold when they are made
- * after a launch starts (`.envrc`, package-manager and Claude settings). */
 export const PROTECTED_FILES = [".gitconfig", ".gitmodules", ".bashrc", ".bash_profile", ".zshrc", ".zprofile", ".profile", ".ripgreprc", ".mcp.json",
     ".envrc", ".npmrc", ".yarnrc", ".yarnrc.yml", ".claude/settings.json", ".claude/settings.local.json", ".git/config"];
-/** Folders protected whole, wherever they are (the runtime's dangerous directories, with Git's hooks). */
 export const PROTECTED_DIRS = [".vscode", ".idea", ".claude/commands", ".claude/agents", ".git/hooks"];
-/**
- * The handoff's backstop (builder.ts commit): the changed paths (relative, from Git) that are protected names at any
- * depth, in any case. The sandbox runtime denies these when a launch starts; one made after it started (a new nested
- * folder's `.envrc`, say) gets through the sandbox, and a result that holds it is refused.
- */
 export function protectedChanges(changed) {
     const files = PROTECTED_FILES.map(one => one.toLowerCase());
     return changed.filter(path => {
         const lower = `/${path.toLowerCase()}`;
-        // A protected folder's own name too (a link committed as `pkg/.vscode`), not only what is in it.
         return files.some(name => lower.endsWith(`/${name}`)) || PROTECTED_DIRS.some(dir => lower.includes(`/${dir.toLowerCase()}/`) || lower.endsWith(`/${dir.toLowerCase()}`));
     });
 }
-/**
- * The handoff's backstop for links (builder.ts commit): a staged symbolic link (Git mode 120000) whose path is a
- * protected name or a folder on the way to one (`pkg/.claude`, `.vscode`, `lib/.git`), at any depth, in any case. A
- * link there would lead whoever opens the project to settings, hooks or commands kept anywhere.
- */
 export function protectedLinks(links) {
     const entries = [...PROTECTED_FILES, ...PROTECTED_DIRS].map(one => one.toLowerCase().split("/"));
     return links.filter(path => {
         const parts = path.toLowerCase().split("/").filter(one => one !== "");
         return entries.some(entry => {
-            // The link's last parts are the entry's first ones (the whole entry, or a folder on the way to it).
             for (let take = 1; take <= Math.min(entry.length, parts.length); take++) {
                 if (parts.slice(parts.length - take).join("/") === entry.slice(0, take).join("/"))
                     return true;
@@ -1285,18 +950,10 @@ export function protectedLinks(links) {
         });
     });
 }
-/** The home folder's own persistence points beyond the protected names (login items, systemd user units and autostart,
- * Git's, gh's, pip's and fish's configuration, the shells' other startup files, SSH and GnuPG, and the folders on a
- * login PATH). Under `.config/` each also stands under $XDG_CONFIG_HOME. */
 export const HOME_PERSISTENCE = ["Library/LaunchAgents", ".config/systemd/user", ".config/autostart", ".config/git", ".config/gh", ".config/pip",
     ".config/fish", ".pip", ".zshenv", ".zlogin", ".bash_login", ".ssh", ".gnupg", ".local/bin", "bin"];
-/** The sign-in folders and files at home no launch writes, but an agent its own exact sign-in files (OWN_SIGN_INS). */
 const HOME_SIGN_INS = [".codex", ".claude.json", ".claude/.credentials.json"];
-/** The exact sign-in files an agent's own launch still writes (Claude's account and credentials). Codex's harness
- * refreshes its sign-in outside the sandbox, so its commands write none. Configuration and persistence names stay
- * denied for every agent. */
 const OWN_SIGN_INS = { claude: [".claude.json", ".claude/.credentials.json"] };
-/** `path` as it resolves now: through every link above it (and at it), however much of it exists. */
 function resolvedPath(path) {
     let head = path;
     const rest = [];
@@ -1311,16 +968,6 @@ function resolvedPath(path) {
     }
     return path;
 }
-/**
- * What no launch writes, whatever its writes, as static write denies for the sandbox runtime (whose own protected names
- * are anchored at the launch's folder only) and Codex's profile: the home folder's protected names (shell profiles, Git
- * and tool configuration), its persistence points and sign-ins (but the launch's own agent's exact sign-in files), and
- * the bound repository's own Git config, hooks and submodules (a linked worktree reaches them through its `.git`
- * file). Each by its name and by where it leads now (a linked ~/.config or LaunchAgents is denied at both ends). On
- * Linux only those there at launch: the runtime holds an absent name with a stand-in nothing can read for the launch's
- * length, and the person's own git and shells then fail on their ~/.gitconfig and ~/.bashrc (measured). Under a write
- * allowlist an absent one is out of reach anyway; under `anywhere` it can be made (an accepted limit).
- */
 export function homeWriteDenies(home, binding, provider, platform = process.platform, env = process.env) {
     const base = real(home);
     const own = new Set(OWN_SIGN_INS[provider ?? ""] ?? []);
@@ -1332,9 +979,6 @@ export function homeWriteDenies(home, binding, provider, platform = process.plat
     const git = binding === null ? [] : ["config", "hooks", "modules"].map(name => join(real(join(binding.main, ".git")), name));
     return [...new Set([...paths, ...git].flatMap(path => [path, resolvedPath(path)]))].sort();
 }
-/** A tool server's grants from its build's: never the agent's network or write allowlist (a server keeps its own state
- * where it always has), and never the build's own checkout or launch folder read back (nothing a build wrote loads in a
- * process that holds a tool's secrets). */
 export function serverGrantsOf(grants) {
     const { network: _agentOnly, writes: _agentWrites, keychain: _agentKeychain, browser: _checkOnly, ...rest } = grants;
     return {