@erichll/pi-sandbox 0.22.0 → 0.23.0

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # Changelog
 
+## 0.23.0 - 2026-10-02
+
+- Add opt-in `network.strictAllowlist` (default `false`) to deny unmatched
+  destinations without model or human approval. Forward the setting to Sandbox
+  Runtime for Bash and built-in workers, including persistent follow-up and
+  nested handoff.
+- Merge global/project strict mode with logical OR while retaining domain-list
+  unions. Both files remain trusted policy sources: projects can add endpoints
+  but cannot disable globally required strict enforcement.
+- Reject strict mode combined with Host-IPC `ask` after configuration merging
+  and embedding overrides. Keep non-strict approval and host forwarding behavior.
+- Require `@erichll/pi-auto-review` `^0.23.0` for current-session review models
+  and full-command execution-context validation.
+- Cover real Linux broker network enforcement, persistent worker lifecycle and
+  startup failures with synthetic endpoints; isolate configuration tests from
+  the developer's working directory.
+
+## 0.22.1 - 2026-10-01
+
+- Fix sandboxed Bash on Bun-compiled Pi: launching the Sandbox Runtime broker
+  could instead start another unsandboxed Pi session with the broker path as
+  its prompt, leaving the requested command unexecuted
+  ([#7](https://github.com/erichll/pi-packages/issues/7)). The broker now runs
+  through a separate Node executable and communicates over JSON IPC.
+- **Bun-compiled Pi requires Node.js >=22.19.0 on PATH**, with its directory
+  listed as an absolute path. If Node cannot be found, commands fail explicitly
+  before execution. Aliases back to the Pi executable are rejected.
+- Fix built-in subagent startup for standalone Pi and resolve the host CLI
+  symlink for Node-based Pi. Derive filesystem permissions from the actual
+  runtime so a binary such as `/tmp/pi-bun` does not grant root reads or deny
+  writes to the entire host temp directory.
+- Fix protected `pi-subagents` loading on Bun when `pi-tui` and `typebox` are
+  provided by Pi. Reuse the host modules in the internal loader so compiled
+  Pi does not need separate copies beside the extension.
+- Clean up command temp directories when broker startup fails. Add isolated
+  Node, plain Bun, and compiled Bun regression tests for broker startup,
+  capability-ceiling registration, and rejection of enabled schedules.
+- Require `@erichll/pi-auto-review` `^0.22.1` to include the Bun SQLite audit fix.
+
 ## 0.22.0 - 2026-09-30
 
 - Raise the `@earendil-works/pi-coding-agent` peer floor to `^0.99.1` and the

package/README.md

@@ -69,6 +69,12 @@ configure an AppArmor profile for bubblewrap or disable
 
 macOS uses built-in Seatbelt support but still requires `ripgrep`.
 
+For Bun-compiled standalone Pi, install **Node.js >=22.19.0** and include its
+`bin` directory as an absolute entry on `PATH`. The sandbox broker runs in that
+separate Node process; built-in subagents launch the Pi executable directly.
+If no usable `node` is found, the command fails before execution. Node-based Pi
+and ordinary `bun cli.js` launches use their existing JavaScript runtime.
+
 ## Subagent provider
 
 The provider is selected from the configuration (`~/.pi/agent/extensions/pi-sandbox/config.json` globally or `.pi/extensions/pi-sandbox/config.json` project-locally):
@@ -94,10 +100,11 @@ Supported modes:
 This provider supports the `pi-subagents >=0.66.0` line (validated through
 0.72.1) and fails closed if its public ceiling API, module layout, or internal
 discovery layout drifts. The peer dependency is a floor with no upper pin; the
-loader's explicit export and layout checks are the real gate. The loader also
-aliases `@earendil-works/pi-tui`, a host peer that the `pi-subagents` internals
-import but do not ship, to the copy inside the running Pi package, so installs
-where it is not hoisted next to the extension still load.
+loader's explicit export and layout checks are the real gate. On Node, the
+loader aliases the `@earendil-works/pi-tui` host peer to the running Pi package.
+On Bun, including compiled Pi, it passes Pi's `pi-tui` and `typebox` module
+objects into its internal loader, so those peers can be embedded in Pi instead
+of installed beside `pi-subagents`.
 Configure both the protection mode and a non-empty canonical whitelist:
 
 ```json
@@ -150,6 +157,7 @@ Domain authorization can be configured globally at
 ```json
 {
   "network": {
+    "strictAllowlist": false,
     "allowedDomains": [
       "github.com",
       "*.github.com",
@@ -172,14 +180,50 @@ The precedence is deterministic:
 
 1. A matching `deniedDomains` entry rejects the connection.
 2. Otherwise, a matching `allowedDomains` entry permits it without review.
-3. Otherwise, the canonical public hostname and port enter the existing
+3. Otherwise, if `strictAllowlist` is `true`, the connection is denied without
+   invoking the Runtime ask callback, model review, or human approval.
+4. Otherwise, the canonical public hostname and port enter the existing
    one-shot auto-review or human approval flow.
 
-Both arrays default to empty. That preserves the prior behavior: no persistent
-network authorization, with every eligible public connection reviewed once.
-The same trusted arrays govern main-agent Bash, built-in subagents, and the
+Both arrays default to empty and `strictAllowlist` defaults to `false`, preserving
+the existing per-connection approval behavior. The setting accepts only a boolean.
+With strict mode and an empty allowlist, all proxied destinations are denied.
+`deniedDomains: ["*"]` also blocks allowed entries because deny rules take priority.
+The same network policy governs main-agent Bash, user Bash, built-in subagents, and the
 sandboxed Bash tool loaded by protected native `pi-subagents` children.
 
+For a worker restricted to explicitly approved inference endpoints:
+
+```json
+{
+  "subagents": { "provider": "builtin" },
+  "network": {
+    "strictAllowlist": true,
+    "allowedDomains": ["inference.example.com:443"],
+    "deniedDomains": []
+  },
+  "hostIPC": { "mode": "off" }
+}
+```
+
+Replace the example hostname with your approved endpoint. Global and project
+`strictAllowlist` values merge with logical OR: a project cannot disable strict
+mode required globally. Domain lists still form unions, so a project **can add
+allowed destinations**. Both files are trusted policy inputs; the global allowlist
+is not an administrative upper bound on project permissions.
+
+Strict mode cannot be combined with `hostIPC.mode: "ask"`, since host execution
+would escape the network sandbox. The effective configuration is rejected before
+tools or workers are created; set Host-IPC mode to `off`. This is checked after
+global/project merging, and again after an embedding's Host-IPC override.
+
+Configuration is loaded when the extension is registered. Existing persistent
+workers keep their policy through follow-up, and handoff workers receive the same
+configured policy. Reload the extension and create new workers to apply file
+changes; there is no configuration hot reload. Broker startup failure never retries
+the worker outside the sandbox, and unavailable approval services cannot relax a
+strict network denial.
+
 Domain allowlists are not a complete data-loss-prevention boundary. A
 multi-tenant or user-uploadable destination such as `github.com` can itself be
 an exfiltration channel; grant only the narrow domains and ports you intend.
@@ -222,7 +266,7 @@ approval warns that the first attempt may already have had partial side
 effects. Successful, timed-out, or aborted commands are never retried.
 
 Host forwarding is intentionally unavailable inside built-in subagents in
-this version.
+this version. It is also incompatible with `network.strictAllowlist: true`.
 
 ## Additional trusted read paths
 
@@ -262,8 +306,12 @@ In addition to user-level configuration at `~/.pi/agent/extensions/pi-sandbox/co
 ```
 
 When present, project configuration is merged with global configuration:
+
 - Array policies (`additionalAllowRead`, `allowedDomains`, `deniedDomains`, `preflightCommandPrefixes`) form a deduplicated union.
 - Scalar settings (`provider`, `mode`, `retryOnUnixSocketError`) allow project-level overrides.
+- `network.strictAllowlist` uses logical OR: `true` in either file enables it.
+  Both configuration files are trusted; project allowlist additions remain effective.
+- The merged configuration must not enable both strict allowlist and Host-IPC `ask`.
 
 **Read-only Security Guarantee**:
 Project-level configuration is explicitly protected in the sandbox policy (`denyWrite`),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@erichll/pi-sandbox",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "Linux (bubblewrap) and macOS (Seatbelt) process sandbox for Pi backed by Anthropic's @anthropic-ai/sandbox-runtime. Fail-closed static filesystem policy plus per-connection network approval from pi-auto-review; sandboxes main-agent Bash and built-in subagent process trees.",
   "type": "module",
   "license": "Apache-2.0",
@@ -51,7 +51,7 @@
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "^0.0.77",
-    "@erichll/pi-auto-review": "^0.22.0",
+    "@erichll/pi-auto-review": "^0.23.0",
     "jiti": "2.7.0"
   },
   "peerDependencies": {

package/src/config.ts

@@ -23,6 +23,8 @@ export type HostIPCConfig = {
 export type NetworkConfig = {
   readonly allowedDomains: readonly string[];
   readonly deniedDomains: readonly string[];
+  /** Deny unmatched destinations without review. Defaults to false. */
+  readonly strictAllowlist?: boolean;
 };
 
 export type PiSandboxConfig = {
@@ -34,7 +36,7 @@ export type PiSandboxConfig = {
   filesystem: {
     additionalAllowRead: readonly string[];
   };
-  network: NetworkConfig;
+  network: NetworkConfig & { readonly strictAllowlist: boolean };
   hostIPC: HostIPCConfig;
 };
 
@@ -57,6 +59,7 @@ export const DEFAULT_PI_SANDBOX_CONFIG: Readonly<PiSandboxConfig> = Object.freez
     network: Object.freeze({
       allowedDomains: Object.freeze([]),
       deniedDomains: Object.freeze([]),
+      strictAllowlist: false,
     }),
     hostIPC: Object.freeze({
       mode: "off",
@@ -263,9 +266,15 @@ export function parsePiSandboxConfigRaw(value: unknown): PartialPiSandboxConfig
     }
     rejectUnknownKeys(
       value.network,
-      ["allowedDomains", "deniedDomains"],
+      ["allowedDomains", "deniedDomains", "strictAllowlist"],
       "network",
     );
+    const strictAllowlist = value.network.strictAllowlist;
+    if (strictAllowlist !== undefined && typeof strictAllowlist !== "boolean") {
+      throw new Error(
+        "invalid pi-sandbox configuration: network.strictAllowlist must be a boolean",
+      );
+    }
     const normalizeDomainList = (
       key: "allowedDomains" | "deniedDomains",
     ): string[] | undefined => {
@@ -310,6 +319,7 @@ export function parsePiSandboxConfigRaw(value: unknown): PartialPiSandboxConfig
     parsedNetwork = {
       ...(allowed !== undefined ? { allowedDomains: allowed } : {}),
       ...(denied !== undefined ? { deniedDomains: denied } : {}),
+      ...(strictAllowlist !== undefined ? { strictAllowlist } : {}),
     };
   }
 
@@ -376,7 +386,24 @@ export function parsePiSandboxConfigRaw(value: unknown): PartialPiSandboxConfig
 }
 
 export function parsePiSandboxConfig(value: unknown): PiSandboxConfig {
-  const raw = parsePiSandboxConfigRaw(value);
+  const config = resolvePiSandboxConfig(parsePiSandboxConfigRaw(value));
+  validatePiSandboxConfig(config);
+  return config;
+}
+
+/** Validate the effective policy, after merging configuration layers. */
+export function validatePiSandboxConfig(
+  config: { network: NetworkConfig; hostIPC: HostIPCConfig },
+): void {
+  if (config.network.strictAllowlist && config.hostIPC.mode === "ask") {
+    throw new Error(
+      'invalid pi-sandbox configuration: network.strictAllowlist=true cannot be combined with hostIPC.mode="ask"; set hostIPC.mode="off" to keep execution sandboxed',
+    );
+  }
+}
+
+/** Apply defaults without validating conflicts in an intermediate layer. */
+function resolvePiSandboxConfig(raw: PartialPiSandboxConfig): PiSandboxConfig {
   const provider =
     raw.subagents?.provider ?? DEFAULT_PI_SANDBOX_CONFIG.subagents.provider;
   const isPiSubagents = provider === "pi-subagents";
@@ -400,6 +427,7 @@ export function parsePiSandboxConfig(value: unknown): PiSandboxConfig {
       ],
     },
     network: {
+      strictAllowlist: raw.network?.strictAllowlist ?? false,
       allowedDomains: [
         ...(raw.network?.allowedDomains ??
           DEFAULT_PI_SANDBOX_CONFIG.network.allowedDomains),
@@ -435,6 +463,7 @@ function defaultPiSandboxConfig(): PiSandboxConfig {
     network: {
       allowedDomains: [...DEFAULT_PI_SANDBOX_CONFIG.network.allowedDomains],
       deniedDomains: [...DEFAULT_PI_SANDBOX_CONFIG.network.deniedDomains],
+      strictAllowlist: DEFAULT_PI_SANDBOX_CONFIG.network.strictAllowlist,
     },
     hostIPC: {
       mode: DEFAULT_PI_SANDBOX_CONFIG.hostIPC.mode,
@@ -507,7 +536,7 @@ export function mergePiSandboxConfigs(
     allowedNativeAgents = [...new Set([...trustedAgents, ...projectAgents])];
   }
 
-  return {
+  const merged: PiSandboxConfig = {
     subagents: {
       provider,
       ...(isPiSubagents
@@ -526,6 +555,10 @@ export function mergePiSandboxConfigs(
       ],
     },
     network: {
+      // Both configuration files are trusted policy inputs. Projects may add
+      // destinations, but cannot turn off strict enforcement required globally.
+      strictAllowlist:
+        trusted.network.strictAllowlist || (project.network?.strictAllowlist ?? false),
       allowedDomains: [
         ...new Set([
           ...trusted.network.allowedDomains,
@@ -552,6 +585,8 @@ export function mergePiSandboxConfigs(
         trusted.hostIPC.retryOnUnixSocketError,
     },
   };
+  validatePiSandboxConfig(merged);
+  return merged;
 }
 
 export function loadPiSandboxConfig(
@@ -572,9 +607,8 @@ export function loadPiSandboxConfig(
   const globalPath = getPiSandboxConfigPath(options.home);
   let globalConfig: PiSandboxConfig | undefined;
   try {
-    globalConfig = parsePiSandboxConfigFile(
-      globalPath,
-      readPiSandboxConfigFile(globalPath),
+    globalConfig = resolvePiSandboxConfig(
+      parsePiSandboxConfigFileRaw(globalPath, readPiSandboxConfigFile(globalPath)),
     );
   } catch (error) {
     if (!isNotFoundError(error)) {
@@ -599,5 +633,6 @@ export function loadPiSandboxConfig(
   if (projectRaw) {
     return mergePiSandboxConfigs(base, projectRaw);
   }
+  validatePiSandboxConfig(base);
   return base;
 }

package/src/index.ts

@@ -17,6 +17,7 @@ import {
 } from "./approval.ts";
 import {
   loadPiSandboxConfig,
+  validatePiSandboxConfig,
   type HostIPCConfig,
   type NetworkConfig,
   type SubagentProvider,
@@ -220,6 +221,8 @@ async function performRegistration(
   let currentTurn = 0;
   const cwd = process.cwd();
   const config = loadPiSandboxConfig({ cwd });
+  const hostIPC = options.hostIPC ?? config.hostIPC;
+  validatePiSandboxConfig({ network: config.network, hostIPC });
   const subagentProvider =
     options.subagentProvider ?? config.subagents.provider;
   const isNativeSubagentChild = process.env.PI_SUBAGENT_CHILD === "1";
@@ -237,7 +240,6 @@ async function performRegistration(
     : undefined;
   const additionalAllowRead = config.filesystem.additionalAllowRead;
   const network = config.network;
-  const hostIPC = options.hostIPC ?? config.hostIPC;
   const subagents =
     subagentProvider === "builtin"
       ? (options.subagentManager ??
@@ -625,10 +627,13 @@ async function performRegistration(
       return;
     }
     if (ctx.hasUI) {
+      const networkMode = network.strictAllowlist
+        ? "strict network allowlist (unmatched destinations denied without review)"
+        : "per-connection network review";
       ctx.ui.notify(
         process.platform === "darwin"
-          ? `${EXTENSION_NAME} enabled: macOS Sandbox Runtime with static filesystem/domain policy and per-connection network review`
-          : `${EXTENSION_NAME} enabled: Linux Sandbox Runtime with static filesystem/domain policy and per-connection network review`,
+          ? `${EXTENSION_NAME} enabled: macOS Sandbox Runtime with static filesystem/domain policy and ${networkMode}`
+          : `${EXTENSION_NAME} enabled: Linux Sandbox Runtime with static filesystem/domain policy and ${networkMode}`,
         "info",
       );
     }

package/src/pi-subagents-native.ts

@@ -3,6 +3,8 @@ import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { createJiti } from "jiti";
+import * as hostPiTui from "@earendil-works/pi-tui";
+import * as hostTypebox from "typebox";
 
 /**
  * Compatible pi-subagents line: 0.66.0 and above (no upper pin). Any new minor
@@ -254,10 +256,23 @@ export async function loadPiSubagentsNativeRuntime(
   }
   const extension = resolvePiSubagentsModuleExtension(packageJson.exports);
 
+  // Pi's outer extension loader supplies these host modules, including embedded
+  // copies in compiled Bun builds. Static imports above keep host resolution in
+  // that outer loader even under plain `bun cli.js`. Filesystem aliases cannot
+  // locate modules that only exist inside Pi.
+  const resolutionOptions = process.versions.bun
+    ? {
+        tryNative: false,
+        virtualModules: {
+          [HOST_PI_TUI_PACKAGE]: hostPiTui,
+          typebox: hostTypebox,
+        },
+      }
+    : { alias: await resolvePiSubagentsHostAliases() };
   const jiti = createJiti(import.meta.url, {
     interopDefault: false,
     fsCache: false,
-    alias: await resolvePiSubagentsHostAliases(),
+    ...resolutionOptions,
   });
   const internal = (relative: string): string =>
     pathToFileURL(join(root, piSubagentsInternalModulePath(relative, extension))).href;

package/src/policy.ts

@@ -10,13 +10,13 @@ import {
 } from "node:path";
 import { fileURLToPath } from "node:url";
 import type { SandboxRuntimeConfig } from "@anthropic-ai/sandbox-runtime";
+import { runtimeFilesystemPaths } from "./runtime.ts";
 import {
   PROJECT_PI_SANDBOX_CONFIG_PATH,
   type NetworkConfig,
 } from "./config.ts";
 
 const PACKAGE_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
-const NODE_INSTALL_ROOT = dirname(dirname(process.execPath));
 const SANDBOX_RUNTIME_ROOT = dirname(
   dirname(
     fileURLToPath(import.meta.resolve("@anthropic-ai/sandbox-runtime")),
@@ -115,6 +115,7 @@ export type SandboxPolicy = {
   network: {
     allowedDomains: string[];
     deniedDomains: string[];
+    strictAllowlist?: boolean;
     allowLocalBinding: boolean;
     allowAllUnixSockets: boolean;
     allowUnixSockets: string[];
@@ -231,6 +232,7 @@ export function createDefaultPolicy(
 ): SandboxPolicy {
   const workspace = resolve(cwd);
   const home = resolve(homedir());
+  const runtimePaths = runtimeFilesystemPaths();
   const denyRead = home === parse(home).root ? [] : [home];
   const packageRelative = relative(workspace, PACKAGE_ROOT);
   const packageIsInWorkspace =
@@ -241,7 +243,7 @@ export function createDefaultPolicy(
       denyRead,
       allowRead: [
         workspace,
-        NODE_INSTALL_ROOT,
+        ...runtimePaths.allowRead,
         SANDBOX_RUNTIME_ROOT,
         join(home, ".gitconfig"),
         join(home, ".config", "git", "config"),
@@ -265,13 +267,14 @@ export function createDefaultPolicy(
           "config.json",
         ),
         ...(packageIsInWorkspace ? [] : [PACKAGE_ROOT]),
-        dirname(process.execPath),
+        ...runtimePaths.denyWrite,
         ...createWorkspaceSecretDenyWritePaths(workspace),
       ],
     },
     network: {
       allowedDomains: [...(options.network?.allowedDomains ?? [])],
       deniedDomains: [...(options.network?.deniedDomains ?? [])],
+      strictAllowlist: options.network?.strictAllowlist ?? false,
       allowLocalBinding: false,
       allowAllUnixSockets: false,
       allowUnixSockets: [],
@@ -295,6 +298,7 @@ export function toSandboxRuntimeConfig(
     network: {
       allowedDomains: [...policy.network.allowedDomains],
       deniedDomains: [...policy.network.deniedDomains],
+      strictAllowlist: policy.network.strictAllowlist ?? false,
       allowLocalBinding: policy.network.allowLocalBinding,
       allowAllUnixSockets: policy.network.allowAllUnixSockets,
       allowUnixSockets: [...policy.network.allowUnixSockets],

package/src/runner.ts

@@ -11,6 +11,7 @@ import type { Writable } from "node:stream";
 import { getShellConfig } from "@earendil-works/pi-coding-agent";
 import type { SandboxRuntimeConfig } from "@anthropic-ai/sandbox-runtime";
 import type { NetworkEndpoint } from "./approval.ts";
+import { resolveBrokerExecPath } from "./runtime.ts";
 import {
   createDefaultPolicy,
   toSandboxRuntimeConfig,
@@ -173,7 +174,10 @@ function spawnBroker(
     cwd: options.cwd,
     detached: true,
     env,
+    execPath: resolveBrokerExecPath(env),
     execArgv: broker.execArgv ?? [],
+    // Bun's default IPC serialization is incompatible with a Node child.
+    serialization: "json",
     stdio: ["pipe", "pipe", "pipe", "ipc"],
   };
   return fork(broker.modulePath, [], forkOptions);
@@ -206,12 +210,14 @@ export async function runSandboxedCommand(
       [SANDBOX_RUNTIME_TMPDIR_ENV]: tempDir,
     };
   }
-  const broker = spawnBroker(options, brokerEnv);
+  let broker: ChildProcess | undefined;
   let timeoutHandle: NodeJS.Timeout | undefined;
   let timedOut = false;
   let onAbort: (() => void) | undefined;
 
   try {
+    broker = spawnBroker(options, brokerEnv);
+    const child = broker;
     broker.stdout?.on("data", (data: Buffer) => {
       options.onData(data);
       options.onStdout?.(data);
@@ -222,7 +228,7 @@ export async function runSandboxedCommand(
     });
     broker.on("message", (message: unknown) => {
       if (!isNetworkRequest(message)) return;
-      void answerNetworkRequest(broker, message, options);
+      void answerNetworkRequest(child, message, options);
     });
 
     const init: BrokerInitMessage = {
@@ -242,18 +248,18 @@ export async function runSandboxedCommand(
       broker.stdin?.end();
     }
 
-    onAbort = () => killProcessTree(broker);
+    onAbort = () => killProcessTree(child);
     options.signal?.addEventListener("abort", onAbort, { once: true });
     if (options.timeout !== undefined && options.timeout > 0) {
       timeoutHandle = setTimeout(() => {
         timedOut = true;
-        killProcessTree(broker);
+        killProcessTree(child);
       }, options.timeout * 1_000);
     }
 
     const exitCode = await new Promise<number | null>((resolve, reject) => {
-      broker.once("error", reject);
-      broker.once("exit", resolve);
+      child.once("error", reject);
+      child.once("exit", resolve);
     });
     if (options.signal?.aborted) throw new Error("aborted");
     if (timedOut) throw new Error(`timeout:${options.timeout}`);
@@ -261,7 +267,7 @@ export async function runSandboxedCommand(
   } finally {
     if (timeoutHandle) clearTimeout(timeoutHandle);
     if (onAbort) options.signal?.removeEventListener("abort", onAbort);
-    if (broker.exitCode === null && broker.signalCode === null) {
+    if (broker && broker.exitCode === null && broker.signalCode === null) {
       killProcessTree(broker);
     }
     if (tempDir) {

package/src/runtime.ts

@@ -0,0 +1,79 @@
+import { accessSync, constants, realpathSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, delimiter, dirname, isAbsolute, join, parse } from "node:path";
+
+export type RuntimeProcess = {
+  execPath: string;
+  argv: readonly string[];
+  versions: Readonly<Record<string, string | undefined>>;
+  features?: { sea?: boolean; inspector?: boolean };
+};
+
+/** The extension's own import.meta.url is on disk even inside compiled Pi. */
+export function isStandaloneExecutable(host: RuntimeProcess = process): boolean {
+  return host.features?.sea === true || (
+    !!host.versions.bun &&
+    /(?:\$bunfs|~BUN|%7EBUN)/i.test(host.argv[1] ?? "")
+  );
+}
+
+/** fork() must execute a JS runtime, never a compiled Pi application image. */
+export function resolveBrokerExecPath(
+  env: NodeJS.ProcessEnv = process.env,
+  host: RuntimeProcess = process,
+): string {
+  if (!isStandaloneExecutable(host)) return host.execPath;
+
+  for (const directory of (env.PATH ?? "").split(delimiter)) {
+    // Do not discover executable code in the command's working directory.
+    if (!isAbsolute(directory)) continue;
+    try {
+      const candidate = realpathSync(join(directory, "node"));
+      accessSync(candidate, constants.X_OK);
+      const candidateStat = statSync(candidate);
+      const hostStat = statSync(host.execPath);
+      if (!candidateStat.isFile()) continue;
+      // Also reject symlinks/hard links from `node` back to the Pi binary.
+      if (candidateStat.dev === hostStat.dev && candidateStat.ino === hostStat.ino) continue;
+      return candidate;
+    } catch {
+      // Try the next absolute PATH entry.
+    }
+  }
+  throw new Error(
+    "pi-sandbox: standalone Pi requires Node.js >=22.19.0 on PATH to run the Sandbox Runtime broker; no usable node executable was found",
+  );
+}
+
+function runtimeReadPath(execPath: string): string {
+  const bin = dirname(execPath);
+  const root = dirname(bin);
+  // Node installations under nvm/Nix need their libraries as well as bin/node.
+  // Arbitrarily placed executables must not grant a whole home directory or /.
+  return basename(bin) === "bin" && root !== parse(root).root && root !== homedir()
+    ? root
+    : execPath;
+}
+
+function runtimeWritePath(execPath: string): string {
+  const directory = dirname(execPath);
+  return basename(directory) === "bin" ? directory : execPath;
+}
+
+export function runtimeFilesystemPaths(
+  env: NodeJS.ProcessEnv = process.env,
+  host: RuntimeProcess = process,
+): { allowRead: string[]; denyWrite: string[] } {
+  const brokerExecPath = resolveBrokerExecPath(env, host);
+  const standalone = isStandaloneExecutable(host);
+  return {
+    allowRead: [...new Set([
+      standalone ? host.execPath : runtimeReadPath(host.execPath),
+      runtimeReadPath(brokerExecPath),
+    ])],
+    denyWrite: [...new Set([
+      standalone ? host.execPath : runtimeWritePath(host.execPath),
+      runtimeWritePath(brokerExecPath),
+    ])],
+  };
+}

package/src/subagent.ts

@@ -1,8 +1,10 @@
 import { randomUUID } from "node:crypto";
+import { realpathSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import type { Writable } from "node:stream";
 import type { NetworkEndpoint } from "./approval.ts";
+import { isStandaloneExecutable, type RuntimeProcess } from "./runtime.ts";
 import {
   runSandboxedCommand,
   type SandboxCommandOptions,
@@ -201,19 +203,30 @@ export function validateSubagentModel(
   };
 }
 
-export function resolvePiInvocation(): ProcessInvocation {
-  const currentEntry = process.argv[1];
+export function resolvePiInvocation(host: RuntimeProcess = process): ProcessInvocation {
+  if (isStandaloneExecutable(host)) {
+    return { command: host.execPath, args: [] };
+  }
+  let currentEntry = host.argv[1];
+  if (currentEntry) {
+    try {
+      // npm's `pi` executable is usually a symlink to the host's cli.js.
+      currentEntry = realpathSync(currentEntry);
+    } catch {
+      // Preserve source/virtual entries that cannot be canonicalized.
+    }
+  }
   if (
     currentEntry &&
     /(?:^|[/\\])cli\.(?:js|mjs|cjs|ts)$/.test(currentEntry)
   ) {
-    return { command: process.execPath, args: [currentEntry] };
+    return { command: host.execPath, args: [currentEntry] };
   }
   const packageEntry = fileURLToPath(
     import.meta.resolve("@earendil-works/pi-coding-agent"),
   );
   return {
-    command: process.execPath,
+    command: host.execPath,
     args: [join(dirname(packageEntry), "cli.js")],
   };
 }