pi-better-subagents 0.1.20 → 0.1.22

package/README.md

@@ -29,7 +29,7 @@ Try it for one run:
 pi -e npm:pi-better-subagents
 ```
 
-Linux sandboxing uses `bubblewrap` when available, for example from `sudo apt-get install bubblewrap`.
+Linux sandboxing uses `bubblewrap` when available, for example from `sudo apt-get install bubblewrap`. It is the same shared mechanism [`pi-better-sandbox`](https://github.com/1aboveio/pi-better-harness/tree/main/packages/pi-better-sandbox#readme) applies to Pi's foreground tools: writes only, reads and network untouched. See [usage notes](https://github.com/1aboveio/pi-better-harness/blob/main/packages/pi-better-subagents/docs/usage.md#write-sandbox).
 
 ## When To Use
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-subagents",
-  "version": "0.1.20",
+  "version": "0.1.22",
   "description": "Pi extension for detached, sandboxed subagent runs that keep the foreground session free.",
   "license": "MIT",
   "type": "module",
@@ -30,11 +30,15 @@
     "access": "public"
   },
   "scripts": {
-    "pretest": "node ../../scripts/sync-shared-log-utils.mjs",
-    "prepack": "node ../../scripts/sync-shared-log-utils.mjs",
+    "pretest": "node ../../scripts/sync-shared-log-utils.mjs && node ../../scripts/sync-shared-sandbox-core.mjs",
+    "prepack": "node ../../scripts/sync-shared-log-utils.mjs && node ../../scripts/sync-shared-sandbox-core.mjs",
     "typecheck": "node -e \"console.log('pi-better-subagents: typecheck skipped for legacy mixed TS/MJS package')\"",
     "test": "node --import tsx --test tests/*.test.mjs",
     "test:cross-session": "node --import tsx --test --test-name-pattern \"callback session isolation\" tests/extension_health_lifecycle.test.mjs",
+    "pretest:macos-sandbox": "node ../../scripts/sync-shared-sandbox-core.mjs",
+    "test:macos-sandbox": "bash tests/test_sandbox_applied.sh && bash tests/test_sandbox_deny_outside.sh && bash tests/test_sandbox_wrapper_argv.sh && node --import tsx --test tests/sandbox_profile.test.mjs",
+    "pretest:linux-sandbox": "node ../../scripts/sync-shared-sandbox-core.mjs",
+    "test:linux-sandbox": "node --import tsx --test tests/linux_bubblewrap.integration.mjs",
     "verify": "npm run typecheck && npm test"
   },
   "files": [

package/sandbox.ts

@@ -1,20 +1,23 @@
 /**
- * OS-level write sandbox for subagent children.
+ * Subagent policy adapter over the shared OS write-sandbox mechanism.
  *
- * Kernel-enforced confinement: the child may READ anywhere and use the network
- * (so web_fetch and the model API keep working), but may only WRITE under a
- * single directory plus the system paths pi itself needs to function. Unlike the
- * cooperative guardrails layer (which pattern-matches tool inputs), this cannot
- * be evaded by a crafted bash command — the write syscall itself is denied.
- *
- * Backends are selected here so callers retain a platform-neutral support query
- * and command-wrapper contract. Linux support adds a backend without changing
- * detached spawning policy in the extension.
+ * The mechanism itself — backend discovery, canonical containment, profile and
+ * mount construction, ordered argv wrapping — lives in `sandbox-core` and is
+ * vendored here as `shared-sandbox-core.ts`. This file holds only the subagent
+ * shape of that call: the detached child's writable directory is the whole
+ * policy, and the wrapped executable is always the pi binary. Detached spawning
+ * policy (default-on, explicit request, explicit opt-out) stays in index.ts and
+ * is passed through unchanged.
  */
 
-import { platform } from "node:os";
-import { accessSync, constants, realpathSync, statSync, writeFileSync } from "node:fs";
-import { delimiter, resolve } from "node:path";
+import {
+    buildSandboxCommand as buildSharedSandboxCommand,
+    maybeBuildSandboxCommand as maybeBuildSharedSandboxCommand,
+    sandboxSupported as sharedSandboxSupported,
+    type SandboxCommand,
+    type SandboxCommandArgs as SharedSandboxCommandArgs,
+    type SandboxRequest,
+} from "./shared-sandbox-core.ts";
 
 type SandboxCommandArgs = {
     profilePath: string;
@@ -24,115 +27,20 @@ type SandboxCommandArgs = {
     piArgs: string[];
 };
 
-type SandboxCommand = { file: string; fileArgs: string[] };
-
-type SandboxBackend = {
-    buildCommand(args: SandboxCommandArgs): SandboxCommand;
-};
-
-type SandboxRequest = {
-    sandboxEnabled: boolean;
-    explicitSandbox: boolean;
-};
-
-/** Quote a path as an SBPL string literal. */
-function sbpl(path: string): string {
-    return `"${path.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
-}
-
-/** Build the existing macOS sandbox-exec wrapper and SBPL profile. */
-function buildMacOSSandboxCommand(args: SandboxCommandArgs): SandboxCommand {
-    // Match on the real (symlink-resolved) path — sandbox-exec evaluates the
-    // canonical path, so /tmp/x must be written as /private/tmp/x.
-    let dir = args.writableDir;
-    try { dir = realpathSync(dir); } catch { /* not yet created; use as given */ }
-
-    const profile = [
-        "(version 1)",
-        "(allow default)",          // permissive base: reads, exec, network
-        "(deny file-write*)",       // ...then deny all writes...
-        `(allow file-write* (subpath ${sbpl(dir)}))`,               // ...except here
-        `(allow file-write* (subpath ${sbpl(`${args.home}/.pi`)}))`, // pi state
-        '(allow file-write* (subpath "/private/var/folders"))',      // macOS temp / our runtime
-        '(allow file-write* (subpath "/private/tmp"))',
-        '(allow file-write* (subpath "/dev"))',                      // /dev/null etc.
-        "",
-    ].join("\n");
-    writeFileSync(args.profilePath, profile);
-
-    return {
-        file: "/usr/bin/sandbox-exec",
-        fileArgs: ["-f", args.profilePath, args.piBin, ...args.piArgs],
-    };
-}
-
-const macOSSandboxBackend: SandboxBackend = {
-    buildCommand: buildMacOSSandboxCommand,
-};
-
-/** Resolve an executable from PATH without starting it or probing namespaces. */
-function executableFromPath(name: string): string | undefined {
-    const path = process.env.PATH;
-    if (!path) return undefined;
-
-    for (const entry of path.split(delimiter)) {
-        const candidate = resolve(entry || ".", name);
-        try {
-            if (!statSync(candidate).isFile()) continue;
-            accessSync(candidate, constants.X_OK);
-            return candidate;
-        } catch {
-            // A PATH entry may disappear or be inaccessible between lookup and use.
-        }
-    }
-    return undefined;
-}
-
-function buildLinuxSandboxCommand(bwrap: string, args: SandboxCommandArgs): SandboxCommand {
-    // The caller creates the selected work directory before it reaches this
-    // boundary. Canonicalizing it before bind-mounting keeps symlink aliases from
-    // widening the writable root.
-    const dir = realpathSync(args.writableDir);
+/** Map the subagent's single-writable-directory shape onto the shared policy. */
+function sharedArgs(args: SandboxCommandArgs): SharedSandboxCommandArgs {
     return {
-        file: bwrap,
-        fileArgs: [
-            "--ro-bind", "/", "/",
-            "--bind", dir, dir,
-            "--bind", "/tmp", "/tmp",
-            "--dev", "/dev",
-            "--",
-            args.piBin, ...args.piArgs,
-        ],
+        profilePath: args.profilePath,
+        // Subagents have no write-deny list: the run directory is the policy.
+        policy: { writableRoot: args.writableDir, home: args.home },
+        execPath: args.piBin,
+        execArgs: args.piArgs,
     };
 }
 
-function linuxSandboxBackend(): SandboxBackend | undefined {
-    const bwrap = executableFromPath("bwrap");
-    if (!bwrap) return undefined;
-    return { buildCommand: (args) => buildLinuxSandboxCommand(bwrap, args) };
-}
-
-function selectedSandboxBackend(): SandboxBackend | undefined {
-    const currentPlatform = platform();
-    if (currentPlatform === "darwin") return macOSSandboxBackend;
-    if (currentPlatform === "linux") return linuxSandboxBackend();
-    return undefined;
-}
-
-function sandboxUnavailableMessage(): string {
-    const currentPlatform = platform();
-    if (currentPlatform === "linux") {
-        return "Linux sandbox requires executable bubblewrap (bwrap) on PATH. Install bubblewrap or pass sandbox:false.";
-    }
-    if (currentPlatform === "darwin") {
-        return "macOS sandbox requires /usr/bin/sandbox-exec. Pass sandbox:false if it is unavailable.";
-    }
-    return `sandbox is unsupported on ${currentPlatform}. Pass sandbox:false on this platform.`;
-}
-
 /** True when an OS write-sandbox backend can be applied on this platform. */
 export function sandboxSupported(): boolean {
-    return selectedSandboxBackend() !== undefined;
+    return sharedSandboxSupported();
 }
 
 /**
@@ -144,14 +52,13 @@ export function maybeBuildSandboxCommand(
     args: SandboxCommandArgs,
     request: SandboxRequest,
 ): SandboxCommand | undefined {
-    if (!request.sandboxEnabled) return undefined;
-
-    const backend = selectedSandboxBackend();
-    if (!backend) {
-        if (request.explicitSandbox) throw new Error(sandboxUnavailableMessage());
-        return undefined;
-    }
-    return backend.buildCommand(args);
+    // `sandbox:false` is this surface's opt-out, and the only one its operator
+    // has: a subagent has no slash commands. A caller that states its own remedy
+    // keeps it.
+    return maybeBuildSharedSandboxCommand(sharedArgs(args), {
+        ...request,
+        remedy: request.remedy ?? "Pass sandbox:false to run this subagent unconfined.",
+    });
 }
 
 /**
@@ -160,5 +67,5 @@ export function maybeBuildSandboxCommand(
  * bypass the request-policy helper above.
  */
 export function buildSandboxCommand(args: SandboxCommandArgs): SandboxCommand {
-    return (selectedSandboxBackend() ?? macOSSandboxBackend).buildCommand(args);
+    return buildSharedSandboxCommand(sharedArgs(args));
 }

package/shared-navigator.ts

@@ -909,13 +909,13 @@ function createOverlayComponent(
           width,
           deps.truncate,
           fg,
-          { minRows: detailRows },
+          { minRows: detailRows, bottomFooter: false, logTailRows },
         );
       } else {
         transcriptDetail = null;
         transcriptComponent = null;
         contentLines = mode === "detail"
-          ? buildDetailLines(detail, width, deps.truncate, fg, { expandedSections, logTailRows, minRows: detailRows })
+          ? buildDetailLines(detail, width, deps.truncate, fg, { expandedSections, logTailRows, minRows: detailRows, bottomFooter: false })
           : buildListLines(overlayState, width, deps.truncate, fg);
       }
       if (mode !== "detail") return contentLines;
@@ -994,9 +994,11 @@ function buildTranscriptDetailLines(
   width: number,
   truncate: (s: string, width: number) => string,
   fg: (color: string, value: string) => string,
-  options: { minRows?: number } = {},
+  options: { minRows?: number; bottomFooter?: boolean; logTailRows?: number } = {},
 ): string[] {
   const actions = [...(detail.footerActions ?? ["x close"]), "Esc close"].join(" · ");
+  const tailRows = options.logTailRows ?? DEFAULT_LOG_TAIL_ROWS;
+  const shownTranscriptLines = transcriptLines.length ? transcriptLines.slice(-tailRows) : ["   (no transcript yet)"];
   const lines: string[] = [
     fg("accent", rule(detail.title, width)),
     dim(`   ← main · ${actions}`, fg),
@@ -1005,10 +1007,11 @@ function buildTranscriptDetailLines(
   ];
   if (detail.subtitle) lines.push(`   summary  ${detail.subtitle}`);
   for (const item of detail.metadata) lines.push(`   ${item.label.padEnd(8, " ").slice(0, 8)} ${item.value}`);
-  lines.push("", dim(section("transcript", width), fg));
+  lines.push("", dim(section(`transcript · latest ${tailRows} rows`, width), fg));
   if (detail.transcriptDiagnostic) lines.push(`   ${dim(detail.transcriptDiagnostic, fg)}`);
-  lines.push(...(transcriptLines.length ? transcriptLines : ["   (no transcript yet)"]));
+  lines.push(...shownTranscriptLines);
   lines.push("");
+  if (options.bottomFooter === false) return lines.map((line) => safeTruncate(line, width, truncate));
   const footerLines = [dim(`   ← main · ${actions}`, fg), dim(rule("", width), fg)];
   padBeforeFooter(lines, footerLines.length, options.minRows);
   lines.push(...footerLines);
@@ -1092,10 +1095,11 @@ function buildDetailLines(
   width: number,
   truncate: (s: string, width: number) => string,
   fg: (color: string, value: string) => string,
-  options: { expandedSections?: Set<string>; logTailRows?: number; minRows?: number } = {},
+  options: { expandedSections?: Set<string>; logTailRows?: number; minRows?: number; bottomFooter?: boolean } = {},
 ): string[] {
   if (!detail) {
     const lines = [rule("Work unavailable", width), dim("   ← back · Esc close", fg), ""];
+    if (options.bottomFooter === false) return lines.map((line) => safeTruncate(line, width, truncate));
     const footerLines = [dim(rule("", width), fg)];
     padBeforeFooter(lines, footerLines.length, options.minRows);
     lines.push(...footerLines);
@@ -1149,14 +1153,17 @@ function buildDetailLines(
       for (const raw of shown) lines.push(raw ? `   ${raw}` : "   ");
     }
   } else {
-    const evidenceLabel = /log/i.test(detail.evidence.label) ? `${detail.evidence.label} · latest ${tailRows} rows` : detail.evidence.label;
+    const tailEvidence = isTailEvidence(detail);
+    const evidenceLabel = tailEvidence ? `${detail.evidence.label} · latest ${tailRows} rows` : detail.evidence.label;
     lines.push(dim(section(evidenceLabel, width), fg));
     const wrapped = /log/i.test(detail.evidence.label)
       ? wrapLogText(body, width - 6)
-      : body.split(/\r?\n/);
-    for (const raw of wrapped) lines.push(raw ? `   ${raw}` : "   ");
+      : wrapEvidenceText(body, width - 6);
+    const shown = tailEvidence ? wrapped.slice(-tailRows) : wrapped;
+    for (const raw of shown) lines.push(raw ? `   ${raw}` : "   ");
   }
   lines.push("");
+  if (options.bottomFooter === false) return lines.map((line) => safeTruncate(line, width, truncate));
   const footerLines = [dim(`   ← back · ${actions}`, fg), dim(rule("", width), fg)];
   padBeforeFooter(lines, footerLines.length, options.minRows);
   lines.push(...footerLines);
@@ -1182,7 +1189,11 @@ function applyDefaultExpandedSections(detail: BackgroundWorkDetail | null, expan
 }
 
 function isFoldableEvidence(detail: BackgroundWorkDetail): boolean {
-  return !/log/i.test(detail.evidence.label);
+  return !isTailEvidence(detail);
+}
+
+function isTailEvidence(detail: BackgroundWorkDetail): boolean {
+  return /log|transcript/i.test(detail.evidence.label);
 }
 
 function sectionHeader(label: string, width: number): string {

package/shared-sandbox-core.ts

@@ -0,0 +1,462 @@
+// Generated from packages/sandbox-core/index.ts. Do not edit directly.
+/**
+ * OS-level write sandbox mechanism shared by Pi extensions.
+ *
+ * Kernel-enforced confinement: the sandboxed process may READ anywhere and use
+ * the network (so web_fetch and the model API keep working), but may only WRITE
+ * under a single canonical root plus the system paths pi itself needs. Unlike a
+ * cooperative guardrails layer (which pattern-matches tool inputs), this cannot
+ * be evaded by a crafted bash command — the write syscall itself is denied.
+ *
+ * This module owns the mechanism only: backend discovery, canonical path
+ * containment, write-deny compilation, macOS SBPL profile construction, Linux
+ * Bubblewrap mount construction, ordered executable/argv wrapping, and support
+ * diagnostics. It owns no Pi tool, TUI, background-task, or subagent lifecycle
+ * policy — callers decide when a sandbox is requested and what it may write.
+ *
+ * Every platform/filesystem dependency is reachable through the optional
+ * `SandboxSeams` argument so callers can plan deterministically in tests.
+ */
+
+import { platform as osPlatform } from "node:os";
+import {
+    accessSync,
+    closeSync,
+    constants,
+    existsSync,
+    mkdirSync,
+    openSync,
+    realpathSync,
+    statSync,
+    writeFileSync,
+} from "node:fs";
+import { basename, delimiter, dirname, join, resolve, sep } from "node:path";
+
+/** Identifies which kernel mechanism a plan will use. */
+export type SandboxBackendId = "macos-seatbelt" | "linux-bubblewrap";
+
+/**
+ * What a sandboxed process may write. `writableRoot` and `denyWrite` entries may
+ * be relative or contain symlinks; they are canonicalized before use.
+ */
+export type SandboxWritePolicy = {
+    /** The single directory subtree the sandboxed process may write under. */
+    writableRoot: string;
+    /**
+     * Concrete paths that stay non-writable even inside `writableRoot`. A
+     * directory entry denies its whole subtree; a file entry denies that file.
+     *
+     * An entry need not exist. The Linux backend needs a mount point, so it
+     * materializes an absent entry as an empty file (see `materializeDenyPath`);
+     * an entry that has to be a *directory* must therefore already exist when the
+     * command is built. Callers denying their own state directory create it
+     * first, which they do anyway to write into it.
+     */
+    denyWrite?: readonly string[];
+    /** Home directory whose `~/.pi` state stays writable on macOS. */
+    home: string;
+};
+
+/** The executable and argv to run inside the sandbox, preserved verbatim. */
+export type SandboxTarget = {
+    execPath: string;
+    execArgs: readonly string[];
+};
+
+export type SandboxCommandArgs = SandboxTarget & {
+    /** Where the macOS backend writes its generated SBPL profile. */
+    profilePath: string;
+    policy: SandboxWritePolicy;
+};
+
+/** The wrapper command to spawn: the backend executable and its full argv. */
+export type SandboxCommand = { file: string; fileArgs: string[] };
+
+/** The caller's default-on / explicit-request / opt-out decision. */
+export type SandboxRequest = {
+    sandboxEnabled: boolean;
+    explicitSandbox: boolean;
+    /**
+     * What this caller's operator can actually do about a missing backend,
+     * appended when an explicit request has to be refused. Surfaces differ: a
+     * subagent tool takes `sandbox:false`, a foreground session takes
+     * `/sandbox off`, so the remedy cannot be stated here.
+     */
+    remedy?: string;
+};
+
+/** Injectable platform and filesystem dependencies. Defaults hit the real OS. */
+export type SandboxSeams = {
+    /** Defaults to `os.platform()`. */
+    platform?: () => string;
+    /** Defaults to a PATH scan that stats and access-checks without executing. */
+    lookupExecutable?: (name: string) => string | undefined;
+    /** Defaults to `fs.realpathSync`. Must throw when the path does not exist. */
+    canonicalize?: (path: string) => string;
+    /** Defaults to `fs.writeFileSync`. */
+    writeProfile?: (path: string, contents: string) => void;
+    /**
+     * Defaults to creating an empty placeholder file for an absent denied path
+     * (see `materializeDenyPath`). Returns whether the path exists afterwards.
+     * Injected by tests that plan Linux argv for paths that do not exist on the
+     * host running them.
+     */
+    materializeDenyPath?: (path: string) => boolean;
+};
+
+/** A policy with every path canonicalized, deduplicated, and ordered. */
+export type CompiledSandboxWritePolicy = {
+    readonly writableRoot: string;
+    readonly denyWrite: readonly string[];
+    readonly home: string;
+};
+
+/** Why a write target is or is not permitted by a compiled policy. */
+export type WriteAccessDecision =
+    | { allowed: true; path: string }
+    | {
+          allowed: false;
+          path: string;
+          reason: "outside-writable-root" | "write-denied";
+          /** The compiled deny entry that matched, for `write-denied` only. */
+          deniedBy?: string;
+      };
+
+/** What the current platform can enforce, and why it cannot when it cannot. */
+export type SandboxSupport =
+    | { supported: true; platform: string; backend: SandboxBackendId; executable: string }
+    | {
+          supported: false;
+          platform: string;
+          backend: undefined;
+          executable: undefined;
+          reason: string;
+      };
+
+type SandboxBackend = {
+    id: SandboxBackendId;
+    executable: string;
+    buildCommand(args: SandboxCommandArgs, seams: SandboxSeams): SandboxCommand;
+};
+
+const MACOS_SANDBOX_EXEC = "/usr/bin/sandbox-exec";
+
+function currentPlatform(seams: SandboxSeams): string {
+    return (seams.platform ?? osPlatform)();
+}
+
+/**
+ * Resolve `path` to an absolute canonical path. Symlinks are resolved on the
+ * longest existing ancestor so a target that does not exist yet still
+ * canonicalizes through its real parent chain.
+ */
+export function canonicalizePath(path: string, seams: SandboxSeams = {}): string {
+    const canonicalize = seams.canonicalize ?? realpathSync;
+    const absolute = resolve(path);
+    try {
+        return canonicalize(absolute);
+    } catch {
+        // Not created yet (or unreadable): canonicalize the parent instead.
+    }
+    const parent = dirname(absolute);
+    if (parent === absolute) return absolute;
+    return join(canonicalizePath(parent, seams), basename(absolute));
+}
+
+function compile(
+    policy: SandboxWritePolicy,
+    seams: SandboxSeams,
+    strictRoot: boolean,
+): CompiledSandboxWritePolicy {
+    // The Linux backend has always required the writable root to exist before it
+    // bind-mounts it; the macOS backend has always tolerated a not-yet-created
+    // one. Keep both behaviors rather than unifying them here.
+    const writableRoot = strictRoot
+        ? (seams.canonicalize ?? realpathSync)(policy.writableRoot)
+        : canonicalizePath(policy.writableRoot, seams);
+
+    const denyWrite = [
+        ...new Set((policy.denyWrite ?? []).map((entry) => canonicalizePath(entry, seams))),
+    ].sort();
+
+    return { writableRoot, denyWrite, home: policy.home };
+}
+
+/**
+ * Canonicalize a write policy once so containment checks and backend rules
+ * agree on exactly which paths they are talking about.
+ */
+export function compileWritePolicy(
+    policy: SandboxWritePolicy,
+    seams: SandboxSeams = {},
+): CompiledSandboxWritePolicy {
+    return compile(policy, seams, false);
+}
+
+function contains(root: string, target: string): boolean {
+    if (target === root) return true;
+    return target.startsWith(root.endsWith(sep) ? root : `${root}${sep}`);
+}
+
+/**
+ * Decide whether an in-process write to `target` is permitted by a compiled
+ * policy. This is the same containment rule the kernel backends enforce, for
+ * callers that mutate files directly instead of spawning a child.
+ */
+export function evaluateWriteAccess(
+    target: string,
+    policy: CompiledSandboxWritePolicy,
+    seams: SandboxSeams = {},
+): WriteAccessDecision {
+    const path = canonicalizePath(target, seams);
+    if (!contains(policy.writableRoot, path)) {
+        return { allowed: false, path, reason: "outside-writable-root" };
+    }
+    for (const denied of policy.denyWrite) {
+        if (contains(denied, path)) {
+            return { allowed: false, path, reason: "write-denied", deniedBy: denied };
+        }
+    }
+    return { allowed: true, path };
+}
+
+/** Quote a path as an SBPL string literal. */
+function sbpl(path: string): string {
+    return `"${path.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+
+/** Build the macOS sandbox-exec wrapper and its SBPL profile. */
+function buildMacOSSandboxCommand(args: SandboxCommandArgs, seams: SandboxSeams): SandboxCommand {
+    // Match on the real (symlink-resolved) path — sandbox-exec evaluates the
+    // canonical path, so /tmp/x must be written as /private/tmp/x.
+    const policy = compile(args.policy, seams, false);
+
+    const profile = [
+        "(version 1)",
+        "(allow default)",          // permissive base: reads, exec, network
+        "(deny file-write*)",       // ...then deny all writes...
+        `(allow file-write* (subpath ${sbpl(policy.writableRoot)}))`,   // ...except here
+        `(allow file-write* (subpath ${sbpl(`${policy.home}/.pi`)}))`,  // pi state
+        '(allow file-write* (subpath "/private/var/folders"))',         // macOS temp / our runtime
+        '(allow file-write* (subpath "/private/tmp"))',
+        '(allow file-write* (subpath "/dev"))',                         // /dev/null etc.
+        // Deny rules come last: SBPL applies the last matching rule, so these
+        // carve holes back out of the allowances above.
+        ...policy.denyWrite.map((path) => `(deny file-write* (subpath ${sbpl(path)}))`),
+        "",
+    ].join("\n");
+    (seams.writeProfile ?? writeFileSync)(args.profilePath, profile);
+
+    return {
+        file: MACOS_SANDBOX_EXEC,
+        fileArgs: ["-f", args.profilePath, args.execPath, ...args.execArgs],
+    };
+}
+
+const macOSSandboxBackend: SandboxBackend = {
+    id: "macos-seatbelt",
+    executable: MACOS_SANDBOX_EXEC,
+    buildCommand: buildMacOSSandboxCommand,
+};
+
+/** Resolve an executable from PATH without starting it or probing namespaces. */
+export function executableFromPath(name: string): string | undefined {
+    const path = process.env.PATH;
+    if (!path) return undefined;
+
+    for (const entry of path.split(delimiter)) {
+        const candidate = resolve(entry || ".", name);
+        try {
+            if (!statSync(candidate).isFile()) continue;
+            accessSync(candidate, constants.X_OK);
+            return candidate;
+        } catch {
+            // A PATH entry may disappear or be inaccessible between lookup and use.
+        }
+    }
+    return undefined;
+}
+
+/**
+ * Give an absent denied path something the kernel can hold out.
+ *
+ * A mount needs a mount point. `--ro-bind-try` skips a source that does not
+ * exist, so before this a denied path that had not been created yet was not
+ * denied at all: inside the sandbox `echo secret > .env.local` simply created
+ * it. `.env` and `.env.local` are absent in most projects, which made the
+ * packaged defaults hold on macOS — SBPL denies by resolved path, existing or
+ * not — and not on Linux.
+ *
+ * Nothing bubblewrap offers closes that without a mount point, and every
+ * bubblewrap operation that would create one (`--dir`, `--file`, `--tmpfs`)
+ * creates it through the read-write bind of the project, which is to say on the
+ * real filesystem anyway. So the placeholder is created here, deliberately and
+ * visibly, rather than as a side effect of a mount operation.
+ *
+ * An empty regular file is the least destructive placeholder: a later
+ * `cp .env.example .env` overwrites it, where an empty *directory* at that path
+ * would fail. Callers whose denied entry has to be a directory create it before
+ * building the command, and an entry that already exists — file or directory —
+ * is bound as it is. The file is created with O_EXCL, so anything that appears
+ * in the meantime is bound rather than clobbered, and it is left in place
+ * afterwards because a resumed task re-runs the launch vector it captured and
+ * its `--ro-bind` sources have to still be there.
+ *
+ * Returns false when the placeholder could not be created. That is not a hole:
+ * the confined process runs as this same user, so a path this process cannot
+ * create is a path that process cannot create either.
+ */
+function materializeDenyPath(path: string): boolean {
+    if (existsSync(path)) return true;
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        closeSync(openSync(path, "wx"));
+        return true;
+    } catch {
+        // Re-check rather than trust the errno. EEXIST from the O_EXCL create
+        // means the path appeared in between, which is the outcome we wanted and
+        // not ours to overwrite; EEXIST from the mkdir means a parent is a
+        // regular file, and nothing can exist under it. Only the first leaves a
+        // source a bind can use.
+        return existsSync(path);
+    }
+}
+
+/**
+ * Whether a denied path lies in a region this backend binds read-write.
+ *
+ * Everywhere else is already covered by the read-only bind of `/`, so a
+ * placeholder there would deny nothing that is not denied already — and would
+ * scatter empty files across the host for the sake of it. Materializing is
+ * confined to the two regions that are genuinely writable inside the sandbox:
+ * the writable root, and the `/tmp` rebind that pi's own tooling needs.
+ */
+function writableInsideLinuxSandbox(path: string, writableRoot: string): boolean {
+    return contains(writableRoot, path) || contains("/tmp", path);
+}
+
+function buildLinuxSandboxCommand(
+    bwrap: string,
+    args: SandboxCommandArgs,
+    seams: SandboxSeams,
+): SandboxCommand {
+    // The caller creates the selected work directory before it reaches this
+    // boundary. Canonicalizing it before bind-mounting keeps symlink aliases from
+    // widening the writable root.
+    const policy = compile(args.policy, seams, true);
+    const materialize = seams.materializeDenyPath ?? materializeDenyPath;
+    const denyBinds = policy.denyWrite.flatMap((path) => {
+        const mountable = writableInsideLinuxSandbox(path, policy.writableRoot) && materialize(path);
+        return [mountable ? "--ro-bind" : "--ro-bind-try", path, path];
+    });
+    return {
+        file: bwrap,
+        fileArgs: [
+            "--ro-bind", "/", "/",
+            "--bind", policy.writableRoot, policy.writableRoot,
+            "--bind", "/tmp", "/tmp",
+            "--dev", "/dev",
+            // Layered last so a denied path wins over every writable bind above.
+            // A denied path need not exist yet, so one inside a writable region
+            // is materialized first; `-try` remains for the paths that are
+            // read-only regardless and for the ones that could not be created,
+            // which are paths the confined process cannot create either.
+            ...denyBinds,
+            "--",
+            args.execPath, ...args.execArgs,
+        ],
+    };
+}
+
+function linuxSandboxBackend(seams: SandboxSeams): SandboxBackend | undefined {
+    const bwrap = (seams.lookupExecutable ?? executableFromPath)("bwrap");
+    if (!bwrap) return undefined;
+    return {
+        id: "linux-bubblewrap",
+        executable: bwrap,
+        buildCommand: (args, buildSeams) => buildLinuxSandboxCommand(bwrap, args, buildSeams),
+    };
+}
+
+function selectedSandboxBackend(seams: SandboxSeams): SandboxBackend | undefined {
+    const platform = currentPlatform(seams);
+    if (platform === "darwin") return macOSSandboxBackend;
+    if (platform === "linux") return linuxSandboxBackend(seams);
+    return undefined;
+}
+
+/**
+ * Why no backend applies here. The requirement only: what a caller can do
+ * instead is a property of that caller's surface, not of the platform, and is
+ * supplied through `SandboxRequest.remedy`.
+ */
+function unavailableMessage(platform: string): string {
+    if (platform === "linux") {
+        return "Linux sandbox requires executable bubblewrap (bwrap) on PATH. Install bubblewrap to enable it.";
+    }
+    if (platform === "darwin") {
+        return "macOS sandbox requires /usr/bin/sandbox-exec, which is missing here.";
+    }
+    return `sandbox is unsupported on ${platform}.`;
+}
+
+/** Report which backend this platform would select, and why it would not. */
+export function describeSandboxSupport(seams: SandboxSeams = {}): SandboxSupport {
+    const platform = currentPlatform(seams);
+    const backend = selectedSandboxBackend(seams);
+    if (!backend) {
+        return {
+            supported: false,
+            platform,
+            backend: undefined,
+            executable: undefined,
+            reason: unavailableMessage(platform),
+        };
+    }
+    return { supported: true, platform, backend: backend.id, executable: backend.executable };
+}
+
+/** The message explaining why no backend is available on this platform. */
+export function sandboxUnavailableMessage(seams: SandboxSeams = {}): string {
+    return unavailableMessage(currentPlatform(seams));
+}
+
+/** True when an OS write-sandbox backend can be applied on this platform. */
+export function sandboxSupported(seams: SandboxSeams = {}): boolean {
+    return selectedSandboxBackend(seams) !== undefined;
+}
+
+/**
+ * Resolve the caller's default-on, explicit-request, and opt-out policy before
+ * spawning. A selected backend always returns its wrapper; callers never retry
+ * the child directly when that wrapper exits or cannot initialize.
+ */
+export function maybeBuildSandboxCommand(
+    args: SandboxCommandArgs,
+    request: SandboxRequest,
+    seams: SandboxSeams = {},
+): SandboxCommand | undefined {
+    if (!request.sandboxEnabled) return undefined;
+
+    const backend = selectedSandboxBackend(seams);
+    if (!backend) {
+        if (request.explicitSandbox) {
+            const reason = sandboxUnavailableMessage(seams);
+            throw new Error(request.remedy ? `${reason} ${request.remedy}` : reason);
+        }
+        return undefined;
+    }
+    return backend.buildCommand(args, seams);
+}
+
+/**
+ * Return the selected backend's executable and ordered argv wrapper around the
+ * target. The fallback preserves the pre-existing direct-call result for callers
+ * that bypass the request-policy helper above.
+ */
+export function buildSandboxCommand(
+    args: SandboxCommandArgs,
+    seams: SandboxSeams = {},
+): SandboxCommand {
+    return (selectedSandboxBackend(seams) ?? macOSSandboxBackend).buildCommand(args, seams);
+}