toolroll 0.9.62 → 0.9.65

package/dist/acp-inspect.d.ts

@@ -0,0 +1,23 @@
+import { type AcpProviderId } from "./acp-agents.js";
+export type AcpInspection = {
+    found: false;
+    binary: string;
+} | {
+    found: true;
+    binary: string;
+    /** The PATH entry that matched, and where it really is. */
+    path: string;
+    realpath: string;
+    /** A native executable (Mach-O/ELF), or a script with a shebang line. */
+    kind: "native" | "script" | "unknown";
+    /** For a script: the nearest package.json's name and version, read, never run. */
+    package: {
+        name: string;
+        version: string;
+    } | null;
+    size: number;
+};
+/** Find an agent's binary on PATH, and describe it without running it. */
+export declare function inspectAcpAgent(provider: AcpProviderId, env?: Readonly<Record<string, string | undefined>>): AcpInspection;
+/** The words a screen says for an inspection: "installed at …, version …" or "not installed". */
+export declare function inspectionWords(inspection: AcpInspection): string;

package/dist/acp-inspect.js

@@ -0,0 +1,109 @@
+/**
+ * What can be known about an ACP agent's binary without running it
+ * (docs/plans/acp-adapter.md § Identity): nothing outside the one spawning
+ * gateway executes an ACP agent — not readiness, not the providers screen,
+ * not a version probe. So readiness and the screens look, and never run:
+ * PATH lookup, realpath, lstat, and for a script launcher a bounded read of
+ * the nearest package.json for its name and version.
+ *
+ * None of this is evidence an agent may run. That is its conformance check
+ * (attestation), which this only helps describe.
+ */
+import { closeSync, constants, fstatSync, lstatSync, openSync, readSync, realpathSync, statSync } from "node:fs";
+import { delimiter, dirname, isAbsolute, join } from "node:path";
+import { ACP_AGENTS } from "./acp-agents.js";
+/** The most bytes read from a launcher (its first line) or a package.json. */
+const READ_CAP = 64 * 1024;
+/** How many folders up from the launcher a package.json is looked for. */
+const PACKAGE_DEPTH = 6;
+/** Read at most `cap` bytes from the start of a regular file, without following a final symlink. */
+function readHead(file, cap) {
+    let fd = null;
+    try {
+        fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | (constants.O_NONBLOCK ?? 0));
+        if (!fstatSync(fd).isFile())
+            return null;
+        const buffer = Buffer.alloc(cap);
+        const read = readSync(fd, buffer, 0, cap, 0);
+        return buffer.subarray(0, read);
+    }
+    catch {
+        return null;
+    }
+    finally {
+        if (fd !== null)
+            closeSync(fd);
+    }
+}
+function kindOf(head) {
+    if (head === null || head.length < 4)
+        return "unknown";
+    if (head[0] === 0x23 && head[1] === 0x21)
+        return "script"; // "#!"
+    const magic = head.readUInt32BE(0);
+    // ELF, Mach-O (both byte orders, 32/64-bit) and fat binaries.
+    if (magic === 0x7f454c46 || [0xfeedface, 0xfeedfacf, 0xcefaedfe, 0xcffaedfe, 0xcafebabe, 0xbebafeca].includes(magic))
+        return "native";
+    return "unknown";
+}
+/** The nearest package.json above a script, by bounded read; its name and plain version, or null. */
+function packageOf(realpath) {
+    let folder = dirname(realpath);
+    for (let depth = 0; depth < PACKAGE_DEPTH; depth += 1) {
+        const head = readHead(join(folder, "package.json"), READ_CAP);
+        if (head !== null) {
+            try {
+                const parsed = JSON.parse(head.toString("utf8"));
+                const name = parsed["name"];
+                const version = parsed["version"];
+                if (typeof name === "string" && typeof version === "string" && name.length <= 214 && /^\d+\.\d+\.\d+$/.test(version))
+                    return { name, version };
+            }
+            catch {
+                // A package.json past the cap or not JSON says nothing.
+            }
+            return null;
+        }
+        const up = dirname(folder);
+        if (up === folder)
+            break;
+        folder = up;
+    }
+    return null;
+}
+/** Find an agent's binary on PATH, and describe it without running it. */
+export function inspectAcpAgent(provider, env = process.env) {
+    const binary = ACP_AGENTS[provider].binary;
+    for (const folder of (env["PATH"] ?? "").split(delimiter)) {
+        if (folder === "" || !isAbsolute(folder))
+            continue;
+        const path = join(folder, binary);
+        try {
+            lstatSync(path);
+        }
+        catch {
+            continue;
+        }
+        let realpath;
+        try {
+            realpath = realpathSync(path);
+            const stat = statSync(realpath);
+            if (!stat.isFile() || (stat.mode & 0o111) === 0)
+                continue;
+            const head = readHead(realpath, 4096);
+            const kind = kindOf(head);
+            return { found: true, binary, path, realpath, kind, package: kind === "script" ? packageOf(realpath) : null, size: stat.size };
+        }
+        catch {
+            continue;
+        }
+    }
+    return { found: false, binary };
+}
+/** The words a screen says for an inspection: "installed at …, version …" or "not installed". */
+export function inspectionWords(inspection) {
+    if (!inspection.found)
+        return `\`${inspection.binary}\` is not installed on this computer's PATH`;
+    const version = inspection.package === null ? "" : ` (${inspection.package.name} ${inspection.package.version})`;
+    return `installed at ${inspection.realpath}${version}`;
+}

package/dist/agent-board.d.ts

@@ -20,8 +20,6 @@ export declare const QUESTIONS_PER_ATTEMPT = 10;
 export declare const QUESTION_PAGE_EVERY_MS: number;
 /** The board's one note on a run whose agent asked past the caps (set once). */
 export declare const QUESTIONS_OVERFLOW_NOTE = "The agent asked more questions than the board takes; see its transcript.";
-/** Notification kinds held while the person watches the run, and re-checked when the watch lapses. */
-export declare const WATCHED_KINDS: ReadonlySet<string>;
 export declare const AGENT_BOARD_SCHEMA = "\nCREATE TABLE IF NOT EXISTS agent_turn (\n  id          INTEGER PRIMARY KEY,\n  run         INTEGER NOT NULL REFERENCES run(id) ON DELETE CASCADE,\n  attempt_key TEXT NOT NULL,\n  state       TEXT NOT NULL CHECK (state IN ('busy','idle','crashed')),\n  at          TEXT NOT NULL\n);\nCREATE INDEX IF NOT EXISTS agent_turn_run ON agent_turn (run, id);\nCREATE TABLE IF NOT EXISTS agent_now (\n  task_ref         INTEGER PRIMARY KEY REFERENCES task_ref(id) ON DELETE CASCADE,\n  run              INTEGER NOT NULL REFERENCES run(id) ON DELETE CASCADE,\n  attempt_key      TEXT NOT NULL,\n  state            TEXT NOT NULL CHECK (state IN ('busy','idle','crashed')),\n  state_at         TEXT NOT NULL,\n  transcript_bytes INTEGER NOT NULL DEFAULT 0,\n  transcript_at    TEXT NOT NULL,\n  stuck_at         TEXT,\n  said             TEXT CHECK (said IN ('working','blocked','done')),\n  said_note        TEXT,\n  said_at          TEXT,\n  status_offset    INTEGER NOT NULL DEFAULT 0,\n  diff_files       INTEGER,\n  diff_at          TEXT\n);\nCREATE TABLE IF NOT EXISTS agent_question (\n  id          INTEGER PRIMARY KEY,\n  run         INTEGER NOT NULL REFERENCES run(id) ON DELETE CASCADE,\n  task_ref    INTEGER NOT NULL REFERENCES task_ref(id) ON DELETE CASCADE,\n  attempt_key TEXT NOT NULL,\n  key         TEXT NOT NULL,\n  question    TEXT NOT NULL,\n  asked_at    TEXT NOT NULL,\n  closed_at   TEXT,\n  closed_how  TEXT CHECK (closed_how IN ('answered','ended')),\n  answer_note INTEGER REFERENCES task_steer(id),\n  answered_by TEXT,\n  UNIQUE (run, key)\n);\nCREATE INDEX IF NOT EXISTS agent_question_open ON agent_question (task_ref) WHERE closed_at IS NULL;\nCREATE TABLE IF NOT EXISTS agent_seen (\n  account TEXT NOT NULL,\n  run     INTEGER NOT NULL REFERENCES run(id) ON DELETE CASCADE,\n  seen_at TEXT NOT NULL,\n  PRIMARY KEY (account, run)\n);\nCREATE TABLE IF NOT EXISTS agent_view (\n  view       TEXT PRIMARY KEY,\n  account    TEXT NOT NULL,\n  run        INTEGER NOT NULL,\n  expires_at TEXT NOT NULL\n);\nCREATE INDEX IF NOT EXISTS agent_view_run ON agent_view (run, account);\nCREATE INDEX IF NOT EXISTS agent_board_open ON run (task_ref, id) WHERE role = 'builder' AND outcome IS NULL;\nCREATE INDEX IF NOT EXISTS agent_board_recent ON run (finished_at, task_ref, id) WHERE role = 'builder' AND outcome IS NOT NULL;\nCREATE INDEX IF NOT EXISTS agent_board_repair ON run (parent_run, id) WHERE role = 'repair';\n";
 /** Added to agent_now after the table first shipped (store.ts addColumn): the oldest open tool call's kind and start. */
 export declare const AGENT_NOW_COLUMNS: readonly [string, string][];
@@ -194,15 +192,30 @@ export declare function releaseAgentView(store: Store, view: string, at: Date):
 export declare function watchingAgentUntil(store: Store, account: string, run: number, at: Date): string | null;
 /** Someone has this exact run open right now. */
 export declare function watchingAgent(store: Store, account: string, run: number, at: Date): boolean;
+export declare const neverHeld: (kind: string) => boolean;
 /**
- * A watched ping, decided when its delivery is claimed (every chat, phone and browser asks here, after the
- * permanent rules in store.pingAllowed): held until the watch lapses while this person has the run open; then
- * skipped when they have already seen the finished run (an answered question is resolved, so never claimed);
- * otherwise sent. Anything that is not a watched kind about a run is sent.
+ * A notification's subject (cockpit §3, R11): the run it is about — its own, or for a ping about a task the task's
+ * live build — so any ping, not only the agent's own kinds, can be held while its person watches that agent. Null:
+ * about nothing a person watches. Its version is the notification's own identity (its dedupe key), so a newer fact
+ * about the same subject is a new ping.
+ */
+export declare function attentionSubjectOf(store: Store, row: {
+    kind: string;
+    run: number | null;
+    taskRef?: number | null;
+}): {
+    run: number;
+} | null;
+/**
+ * A watched ping (cockpit §3, R11), decided when its delivery is claimed AND again at every channel's final send
+ * fence, after the permanent rules in store.pingAllowed: held until the watch lapses while this person has its
+ * subject's agent open; then skipped when it was news about a finished run they have since seen; otherwise sent.
+ * A ping about nothing anyone watches is sent. (A delivery already handed to the network can't be recalled.)
  */
 export declare function watchedPing(store: Store, row: {
     kind: string;
     run: number | null;
+    taskRef?: number | null;
 }, account: string, now: Date): {
     hold: string;
 } | "skip" | "send";

package/dist/agent-board.js

@@ -46,8 +46,6 @@ export const QUESTIONS_PER_ATTEMPT = 10;
 export const QUESTION_PAGE_EVERY_MS = 5 * 60_000;
 /** The board's one note on a run whose agent asked past the caps (set once). */
 export const QUESTIONS_OVERFLOW_NOTE = "The agent asked more questions than the board takes; see its transcript.";
-/** Notification kinds held while the person watches the run, and re-checked when the watch lapses. */
-export const WATCHED_KINDS = new Set(["agent-question", "run-finished", "build-failed"]);
 export const AGENT_BOARD_SCHEMA = `
 CREATE TABLE IF NOT EXISTS agent_turn (
   id          INTEGER PRIMARY KEY,
@@ -435,19 +433,42 @@ export function watchingAgentUntil(store, account, run, at) {
 export function watchingAgent(store, account, run, at) {
     return watchingAgentUntil(store, account, run, at) !== null;
 }
+/** Kinds no watch ever holds: a security alert and the evening digest reach people as they are (store.pingAllowed).
+ * Nothing held may delay them either: a channel's ordering never keeps one behind a held ping (neverHeld). */
+const NEVER_HELD = new Set(["secret-detected", "security-release", "evening-digest"]);
+export const neverHeld = (kind) => NEVER_HELD.has(kind);
+/** Kinds that are news only until the finished run is seen: a ping about one already opened is not sent at all. */
+const SEEN_SETTLES = new Set(["run-finished", "build-failed"]);
 /**
- * A watched ping, decided when its delivery is claimed (every chat, phone and browser asks here, after the
- * permanent rules in store.pingAllowed): held until the watch lapses while this person has the run open; then
- * skipped when they have already seen the finished run (an answered question is resolved, so never claimed);
- * otherwise sent. Anything that is not a watched kind about a run is sent.
+ * A notification's subject (cockpit §3, R11): the run it is about — its own, or for a ping about a task the task's
+ * live build — so any ping, not only the agent's own kinds, can be held while its person watches that agent. Null:
+ * about nothing a person watches. Its version is the notification's own identity (its dedupe key), so a newer fact
+ * about the same subject is a new ping.
+ */
+export function attentionSubjectOf(store, row) {
+    if (NEVER_HELD.has(row.kind))
+        return null;
+    if (row.run !== null)
+        return { run: row.run };
+    if (row.taskRef === undefined || row.taskRef === null)
+        return null;
+    const live = store.handle.prepare("SELECT id FROM run WHERE task_ref = ? AND role = 'builder' AND outcome IS NULL ORDER BY id DESC LIMIT 1").get(row.taskRef);
+    return live === undefined ? null : { run: Number(live["id"]) };
+}
+/**
+ * A watched ping (cockpit §3, R11), decided when its delivery is claimed AND again at every channel's final send
+ * fence, after the permanent rules in store.pingAllowed: held until the watch lapses while this person has its
+ * subject's agent open; then skipped when it was news about a finished run they have since seen; otherwise sent.
+ * A ping about nothing anyone watches is sent. (A delivery already handed to the network can't be recalled.)
  */
 export function watchedPing(store, row, account, now) {
-    if (row.run === null || !WATCHED_KINDS.has(row.kind))
+    const subject = attentionSubjectOf(store, row);
+    if (subject === null)
         return "send";
-    const until = watchingAgentUntil(store, account, row.run, now);
+    const until = watchingAgentUntil(store, account, subject.run, now);
     if (until !== null)
         return { hold: until };
-    if (row.kind === "agent-question")
+    if (!SEEN_SETTLES.has(row.kind) || row.run === null)
         return "send";
     const seen = store.handle.prepare("SELECT 1 AS hit FROM agent_seen WHERE account = ? AND run = ?").get(account, boardRunOf(store, row.run));
     return seen === undefined ? "send" : "skip";

package/dist/agent-fence.d.ts

@@ -1,5 +1,18 @@
+import type { LoopbackMode } from "./egress.js";
+/** Beside the database: where Linux builds' network bridges are made (its name reads as secret wherever it is). */
+export declare const BRIDGE_DIR = "bridge-secrets";
 /** How a launch was fenced, as recorded on the run and said on the task. */
 export type FenceMethod = "codex-profile" | "macos-sandbox" | "linux-bubblewrap" | "claude-rules" | "none";
+/** Only the plane's recorded repository may supply an own-Git exemption. */
+export type WorktreeBinding = {
+    main: string;
+    gitdir: string;
+};
+export declare class CheckoutBindingError extends Error {
+}
+export declare const HARDENED_GIT_ARGS: readonly ["--no-optional-locks", "-c", "core.fsmonitor=false", "-c", "core.hooksPath=/dev/null"];
+export declare function checkoutGitEnv(base?: Readonly<NodeJS.ProcessEnv>): Record<string, string>;
+export declare function trustedWorktreeBinding(repository: string, worktree: string, poolRoots?: readonly (string | null)[]): WorktreeBinding;
 /**
  * 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
@@ -14,11 +27,17 @@ export declare function agentFence(options: {
     home?: string;
     extra?: readonly string[];
     boundary?: TaskBoundary | null;
+    binding?: WorktreeBinding | null;
+    runFolders?: RunFolders;
 }): string[];
-/** The task's boundary: `shell` joins the OS fence; `fileTools` only Claude's file-tool deny rules. */
+/** The task's boundary: `shell` joins the OS fence; `fileTools` only Claude's file-tool deny rules; `readOnly` and
+ * `lookup` are other tasks' git metadata and checkout roots (see FenceGrants). */
 export type TaskBoundary = {
+    protectedShell?: string[];
     shell: string[];
     fileTools: string[];
+    readOnly: string[];
+    lookup: string[];
 };
 /**
  * Everything outside a task's own folders that a build could otherwise
@@ -32,19 +51,187 @@ export declare function taskBoundary(options: {
     worktree: string;
     provider: string;
     home?: string;
+    binding?: WorktreeBinding | null;
 }): TaskBoundary;
+/** Where launches keep their private folders (the system temp folder), and this launch's own tool folder. */
+export type RunFolders = {
+    root: string;
+    own: string | null;
+};
+/** The prefixes of every launch's private folders: its tools' config, a Codex build's own home, and a Linux build's
+ * network bridge (egress-bridge.ts). */
+export declare const RUN_FOLDER_PREFIXES: readonly ["so-tools-", "so-codex-", "so-net-"];
+export declare function runFolders(own: string | null, root?: string): RunFolders;
+/**
+ * What a fence gives back beside its denied paths. Each is narrow and none
+ * ever writes: `readOnly` is read, never written (other tasks' git
+ * metadata); `readable` is read and run inside a denied folder (the shared
+ * dependencies this checkout links); `lookup` is only looked up, never
+ * listed or read (the deps root and the copy linked, other tasks' checkout
+ * roots); `runFolders` denies every launch folder in the temp folder but
+ * this launch's own (macOS: by pattern, so a later one is denied too);
+ * `pool` denies the plane's checkout pools whole and gives this build's own
+ * checkout back (CheckoutPool).
+ */
+export type FenceGrants = {
+    readOnly: string[];
+    readable: string[];
+    lookup: string[];
+    runFolders?: RunFolders;
+    pool?: CheckoutPool;
+    network?: NetworkFence;
+};
+/**
+ * A launch's network confinement (egress.ts, docs/plans/agent-baseline-hardening.md arc 1). `open`: the network as it
+ * always was. `allowlist`: nothing leaves the machine but through the run's own proxy (`proxyPort`); the run's tool
+ * broker (`brokerPorts`) stays reachable; on macOS this Mac's other local services are reachable only under
+ * `loopback: "any"` (all of them: Seatbelt can't refuse one local port once it admits the rest); unix sockets only
+ * under `socketRoots` (the run's own temp folder and checkout). On Linux the agent gets a network of its own and
+ * reaches the proxy and broker through `bridge` (a folder of unix sockets the plane serves, and the forwarder that
+ * carries them onto the namespace's own loopback).
+ */
+export type NetworkFence = {
+    mode: "open";
+} | {
+    mode: "allowlist";
+    proxyPort: number;
+    brokerPorts: number[];
+    loopback: LoopbackMode;
+    socketRoots: string[];
+    bridge?: {
+        folder: string;
+        forwarder: string;
+        node: string;
+    };
+    /** Linux: the run's own folders a private /tmp gives back (its checkout, its launch folder), when they are there. */
+    keep?: string[];
+};
+/**
+ * Services a sandboxed process could ask to act outside the sandbox for it (macOS): open a URL in a browser (Launch
+ * Services), script another application (Apple Events), fetch in the background (nsurlsessiond), look a name up
+ * (the DNS service: a lookup is itself a message out), or read and write the clipboard. Denied when the network is
+ * confined; the run's proxy resolves names for it.
+ */
+export declare const DELEGATION_SERVICES: readonly string[];
+export declare const NO_GRANTS: FenceGrants;
+/**
+ * The plane's checkout pools, denied whole: every project's worktrees, and any made there after launch. `agentFence`
+ * drops a path at or above the checkout, so the deny lives here and each sandbox gives back, right after it, only
+ * `own` (this build's checkout, read and written) and `lookup` (the folders between, looked up, never listed).
+ */
+export type CheckoutPool = {
+    deny: string[];
+    own: string | null;
+    lookup: string[];
+    gitPaths?: string[];
+};
+/**
+ * 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 declare function checkoutPool(options: {
+    roots: readonly (string | null)[];
+    worktree: string | null;
+    binding?: WorktreeBinding | null;
+    home?: string;
+}, list?: (path: string) => string[]): CheckoutPool;
+/** 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 declare function fenceGrants(options: {
+    databaseFile: string | null;
+    worktree: string | null;
+    boundary?: TaskBoundary | null;
+    runFolders?: RunFolders;
+    linked?: {
+        repo: string;
+        setupDigest: string | null;
+    } | null;
+    poolRoots?: readonly (string | null)[];
+    binding?: WorktreeBinding | null;
+    home?: string;
+}): FenceGrants;
+/**
+ * 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 declare function fencedGitEnv(base?: Readonly<Record<string, string | undefined>>): Record<string, string>;
 /**
  * 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.
+ * 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 declare function codexFenceArgv(fence: readonly string[], fullAccess: boolean, grants?: FenceGrants): string[];
+/**
+ * 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 declare function codexPool(pool: CheckoutPool, list?: (path: string) => string[]): {
+    read: string[];
+    deny: string[];
+    write: string[];
+};
+/** 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 declare const SPLIT_SECRET_PATTERNS: readonly ["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 declare function flattened(fence: readonly string[], grants?: FenceGrants, list?: (path: string) => string[]): {
+    deny: string[];
+    readOnly: string[];
+};
+/** 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 declare function claudeFenceSettings(fence: readonly string[], readOnly?: readonly string[]): string;
+/**
+ * The folders the user owns above each path (never `/`, nor the path itself), and each `roots` folder itself when the
+ * user owns it. A Seatbelt path rule follows the name, not the folder: renaming one of these would bring a fenced path
+ * back under a name no rule mentions. A folder the user doesn't own can't be renamed by a build anyway.
+ */
+export declare function ownedAncestors(paths: readonly string[], roots?: readonly string[], uid?: number | undefined): string[];
+/**
+ * A Seatbelt profile that allows everything except reading or writing the
+ * fenced paths, less what `grants` gives back (a later Seatbelt rule
+ * outranks an earlier one). Whatever the paths, the process can't read
+ * another's arguments and environment (`kern.procargs`, which `ps -E` and
+ * KERN_PROCARGS2 use) or inspect a process outside its own sandbox:
+ * `process-info*` limited by target alone doesn't stop the sysctl. It can't
+ * take another process's task port either (`task_for_pid`, what lldb attaches
+ * with; a task name port too), so a tool server's or Toolroll's own memory
+ * and environment stay out of reach. Last, every folder of the user's above
+ * a fenced or read-only path and above the temp folder (and the temp folder
+ * itself) can't be renamed or removed, though what is inside them stays
+ * writable as before. The checkout pools are denied first, and the build's own
+ * checkout given back right after, so every later deny still holds inside it.
+ */
+export declare function macosFenceProfile(fence: readonly string[], grants?: FenceGrants): string;
+/**
+ * The network half of the macOS fence. Every outbound connection is denied, then loopback is given back as the launch
+ * allows: every local port under `loopback: "any"`, else the run's proxy and broker alone. (Seatbelt admits a port an
+ * allow names whatever a deny after it says, so a local port can't be refused once all are admitted: the choice is all
+ * or none, plus the run's own.) Filters name the remote end only: a `local ip` filter would admit any outbound
+ * connection.
  */
-export declare function codexFenceArgv(fence: readonly string[], fullAccess: boolean): string[];
-/** Claude's own file tools refuse the fenced paths in every mode (its shell is fenced by the macOS sandbox). */
-export declare function claudeFenceSettings(fence: readonly string[]): string;
-/** A Seatbelt profile that allows everything except reading or writing the fenced paths. */
-export declare function macosFenceProfile(fence: readonly string[]): string;
+export declare function macosNetworkRules(network: NetworkFence | undefined): string[];
 export declare const SANDBOX_EXEC = "/usr/bin/sandbox-exec";
 /**
  * Whether this machine can run an agent inside the macOS fence (checked once). Not from inside another
@@ -58,13 +245,19 @@ export declare function macosFenceAvailable(platform?: NodeJS.Platform, probe?:
     stderr: string;
 }): boolean;
 /** The spawn that runs `file args` inside the macOS fence (same process: sandbox-exec replaces itself with the agent). */
-export declare function macosFenced(file: string, args: readonly string[], fence: readonly string[]): {
+export declare function macosFenced(file: string, args: readonly string[], fence: readonly string[], grants?: FenceGrants): {
     file: string;
     args: string[];
 };
 export declare function linuxFenceAvailable(platform?: NodeJS.Platform, probe?: () => boolean): boolean;
-/** The spawn that runs `file args` inside the Linux fence: the whole filesystem as it is, except each fenced path masked. */
-export declare function linuxFenced(file: string, args: readonly string[], fence: readonly string[]): {
+/** The spawn that runs `file args` inside the Linux fence: the whole filesystem as it is, the checkout pools masked
+ * and the build's own checkout bound back read-write over them, then every fenced path masked whole (an empty
+ * folder, or /dev/null for a file), so what is made there after launch is masked too; then only the explicit grants
+ * bound back read-only (bubblewrap binds from the original root, so a grant inside a mask still reaches its files). */
+export declare function linuxFenced(file: string, args: readonly string[], fence: readonly string[], grants?: FenceGrants): {
     file: string;
     args: string[];
 };
+/** The host's own sockets a process in a mounted filesystem could still talk to (D-Bus, the display, container
+ * engines), wherever they exist here. */
+export declare function linuxHostSockets(uid?: number | undefined, home?: string, tmp?: string): string[];