pi-better-harness 0.4.0 → 0.5.0

package/node_modules/pi-better-background-tasks/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-background-tasks",
-  "version": "0.2.17",
+  "version": "0.2.18",
   "description": "Pi extension for durable background shell tasks, watchers, logs, and status inspection.",
   "license": "MIT",
   "type": "module",

package/node_modules/pi-better-background-tasks/src/shared-sandbox-core.ts

@@ -79,6 +79,8 @@ export type SandboxCommandArgs = SandboxTarget & {
     /** Where the macOS backend writes its generated SBPL profile. */
     profilePath: string;
     policy: SandboxWritePolicy;
+    /** Fixed internal helper only: expose its executable in a hidden Linux root. */
+    internalHelperExecutable?: boolean;
 };
 
 /** The wrapper command to spawn: the backend executable and its full argv. */
@@ -410,7 +412,21 @@ const macOSSandboxBackend: SandboxBackend = {
     buildCommand: buildMacOSSandboxCommand,
 };
 
-/** Resolve an executable from PATH without starting it or probing namespaces. */
+/** Resolve only a root-owned system executable; never inspect task PATH. */
+function systemSandboxExecutable(name: string): string | undefined {
+    // Never resolve the host-side confinement launcher through task-influenced PATH.
+    for (const directory of ["/usr/bin", "/bin"]) {
+        const candidate = join(directory, name);
+        try {
+            const info = statSync(candidate);
+            if (!info.isFile() || info.uid !== 0 || (info.mode & 0o022) !== 0) continue;
+            accessSync(candidate, constants.X_OK);
+            return candidate;
+        } catch { /* Try the next system location. */ }
+    }
+    return undefined;
+}
+
 export function executableFromPath(name: string): string | undefined {
     const path = process.env.PATH;
     if (!path) return undefined;
@@ -592,6 +608,12 @@ function buildLinuxPermissionCommand(
             if (existsSync(root)) mounts.push("--ro-bind", root, root);
         }
         mounts.push("--tmpfs", "/tmp");
+        if (args.internalHelperExecutable) {
+            const executable = canonicalizePath(args.execPath, seams);
+            if (!RUNTIME_ROOTS.some((root) => contains(canonicalizePath(root, seams), executable))) {
+                mounts.push("--ro-bind", executable, executable);
+            }
+        }
     } else {
         mounts.push(permissions.outsideProject === "read" ? "--ro-bind" : "--bind", "/tmp", "/tmp");
     }
@@ -605,17 +627,18 @@ function buildLinuxPermissionCommand(
         }
     }
     for (const path of policy.runtimeWrite ?? []) {
-        if ([...credentials, ...policy.denyWrite].some((protectedPath) => contains(path, protectedPath) || contains(protectedPath, path))) {
+        if (credentials.some((protectedPath) => contains(path, protectedPath) || contains(protectedPath, path)) ||
+            policy.denyWrite.some((protectedPath) => contains(protectedPath, path))) {
             throw new Error("Runtime directory overlaps protected credentials or control paths.");
         }
         mounts.push("--bind", path, path);
     }
     const protectedPaths = [...policy.denyWrite,
         ...(permissions.storedCredentials !== "read-write" ? overlappingCredentials : [])];
-    if (writableProject) {
+    for (const writableRoot of [...(writableProject ? [project] : []), ...(policy.runtimeWrite ?? [])]) {
         const materialize = seams.materializeDenyPath ?? materializeDenyPath;
-        const leaves = protectedPaths.filter((path) => contains(project, path) && materialize(path));
-        for (const parent of protectedAncestors(leaves).filter((path) => contains(project, path) && path !== project)) {
+        const leaves = protectedPaths.filter((path) => contains(writableRoot, path) && materialize(path));
+        for (const parent of protectedAncestors(leaves).filter((path) => contains(writableRoot, path) && path !== writableRoot)) {
             mounts.push("--bind", parent, parent);
         }
         for (const path of leaves) mounts.push("--ro-bind", path, path);
@@ -628,7 +651,7 @@ function buildLinuxPermissionCommand(
 }
 
 function linuxSandboxBackend(seams: SandboxSeams): SandboxBackend | undefined {
-    const bwrap = (seams.lookupExecutable ?? executableFromPath)("bwrap");
+    const bwrap = (seams.lookupExecutable ?? systemSandboxExecutable)("bwrap");
     if (!bwrap) return undefined;
     return {
         id: "linux-bubblewrap",
@@ -651,7 +674,7 @@ function selectedSandboxBackend(seams: SandboxSeams): SandboxBackend | undefined
  */
 function unavailableMessage(platform: string): string {
     if (platform === "linux") {
-        return "Linux sandbox requires executable bubblewrap (bwrap) on PATH. Install bubblewrap to enable it.";
+        return "Linux sandbox requires executable bubblewrap (bwrap) in /usr/bin or /bin. Install bubblewrap to enable it.";
     }
     if (platform === "darwin") {
         return "macOS sandbox requires /usr/bin/sandbox-exec, which is missing here.";

package/node_modules/pi-better-sandbox/README.md

@@ -41,52 +41,47 @@ OS vault services such as Keychain and Secret Service, and tokens inherited in
 environment variables, are excluded. Read / write may be needed by a CLI that
 refreshes a token or updates its credential database.
 
-For shell commands the denial is done by the kernel, not by inspecting command
-text: macOS uses Seatbelt (`sandbox-exec`) and Linux uses Bubblewrap (`bwrap`).
-A crafted command cannot talk its way past it, because the write syscall itself
-is refused.
-
-`write` and `edit` never start a child process — they change files inside Pi's
-own process — so there is no child to wrap. They are confined by a containment
-check on the canonical target instead, run inside Pi's own file-mutation queue,
-immediately before the filesystem call it guards. A refused mutation leaves
-nothing behind on disk.
+File and shell operations use the kernel: macOS uses Seatbelt (`sandbox-exec`)
+and Linux uses Bubblewrap (`bwrap`). `read`, `write`, and `edit` keep Pi's normal
+tool behavior and mutation queues, while a fixed worker performs filesystem
+syscalls under the selected policy. Canonical checks explain denials; kernel
+enforcement also protects against a symlink changing between checking and use.
+The confined file worker rejects files over 8 MiB instead of silently truncating
+them; larger-file processing can use a confined command when commands are On.
 
 ## What is confined, and what is not
 
-Selected file and network rules apply to confined commands. Main's model
-connection remains outside the tool sandbox. A detached subagent's OS sandbox
-surrounds its whole runtime: until provider networking is isolated, launching a
-subagent with Network access Off is refused with an explanation. Run commands &
-applications Off prevents new shell, application, background-task, and subagent
-launches; in-process file tools can still operate according to their file rules.
-
-Permissions cover the integrated first-party execution paths:
-
-- Pi's built-in `bash` tool.
-- User-entered `!` and `!!` commands.
-- Pi's built-in `read`, `write`, and `edit` tools.
-- Local [`pi-better-background-tasks`](https://github.com/1aboveio/pi-better-harness/tree/main/packages/pi-better-background-tasks#readme)
-  spawns and watches, which capture this policy at launch.
-- [`pi-better-subagents`](https://github.com/1aboveio/pi-better-harness/tree/main/packages/pi-better-subagents#readme)
-  children, through the same shared mechanism.
-
-**Not** confined:
-
-- Pi's own process.
-- `pi.exec` calls made by extensions.
-- Unrelated third-party extension code.
-- Remote filesystem operations: local permissions cannot constrain the remote
-  host. With Main sandbox enabled, the dedicated `remote_bash` and structured
-  SSH background launchers are blocked because their local SSH client does not
-  yet use the confinement wrapper. Run `ssh` through confined `bash` to apply
-  local file, credential, and network permissions to the SSH client.
-- Another first-party surface's control plane. Each surface denies its own —
-  the files naming what it will run next — but not every other surface's, so
-  confinement is per surface rather than global.
-
-This is a tool-execution sandbox. It limits accidental damage from commands the
-model or you run through Pi's shell; it is not a boundary around Pi itself.
+Pi is the trusted runtime. It can lock configuration/authentication files,
+connect to its provider, and persist sessions. Main and Subagents permissions
+apply to task operations. Subagents can start with task Network access or Run
+commands & applications Off. The fixed file worker remains available according
+to the file permissions even when task commands are Off.
+
+The task executor provides a private scratch directory through `TMPDIR`, `TMP`,
+and `TEMP`. Only that directory is writable in addition to the selected project
+and explicit file grants; a protected anchor prevents replacing its root with a
+symlink. It is separate from Pi's runtime control files.
+
+The currently admitted model-tool implementations are `read`, `write`, `edit`,
+and `bash`. User-entered `!` and `!!` commands use the same shell policy. Other
+model-callable tools require a verified execution adapter and are refused while
+that actor's sandbox is enabled; enabling network alone does not admit them.
+Subagent launch output identifies requested tools that are unavailable. Main
+remains Off by default, so its ordinary orchestration tools remain available
+unless the user enables Main confinement.
+
+Pi and installed runtime extensions remain trusted code, including their
+initialization, provider hooks, and internal `pi.exec` calls. The tool gate is
+not a sandbox around malicious runtime extensions. Loaded runtime code,
+configuration, and policy/control files are protected from task writes, even
+under broader file grants. Task access to `~/.pi` does not receive a blanket
+write allowance or lock-file exception.
+
+Local confinement cannot govern a remote host's filesystem. Dedicated SSH,
+MCP, scripting, background, and nested-agent tools currently lack admission
+adapters and fail closed under an enabled actor profile. SSH through confined
+`bash` receives local file, credential, and network restrictions; remote effects
+remain outside the local filesystem policy.
 
 Overriding `write` and `edit` changes nothing you can see: the parameter
 schemas, prompt guidance, call rendering, write previews, edit diffs, result

package/node_modules/pi-better-sandbox/index.ts

@@ -7,19 +7,15 @@
  * with one writable root — the canonical directory Pi was launched from — and
  * the packaged write-denied paths carved back out of it. Selected file,
  * credential-file, command, and network permissions apply to protected tools.
- * In-process file tools use the same canonical policy as spawned commands.
+ * File-tool syscalls and shell commands run under the same kernel policy.
  *
  * This is a tool-execution sandbox. Pi's own process, `pi.exec` calls, and
  * unrelated third-party extension code are not confined by it.
  */
 
-import { homedir } from "node:os";
-import { resolve } from "node:path";
+import { dirname, isAbsolute, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import {
-    createBashToolDefinition,
-    createReadToolDefinition,
-    createEditToolDefinition,
-    createWriteToolDefinition,
     SettingsManager,
     type ExtensionAPI,
     type ExtensionContext,
@@ -36,16 +32,12 @@ import {
     FOREGROUND_SANDBOX_POLICY_REQUEST_CHANNEL,
     publishForegroundSandboxPolicy,
 } from "./events.ts";
-import {
-    createSandboxedEditOperations,
-    createSandboxedWriteOperations,
-    createForegroundReadGuard,
-} from "./files.ts";
+import { installTaskTools, runtimeCodeRoot } from "./shared-task-sandbox.ts";
 import { writeSandboxDefault } from "./preferences.ts";
 import { readPermissionSettings, writePermissionSettings } from "./permission-settings.ts";
 import { defaultSandboxPermissions } from "./permissions.ts";
 import { openPermissionsPage } from "./permissions-page.ts";
-import { createSandboxedBashOperations } from "./shell.ts";
+
 import { footerTone, formatFooterStatus } from "./status.ts";
 import { ForegroundSandboxController, type ForegroundSandboxStatus } from "./state.ts";
 
@@ -57,47 +49,12 @@ export default function piBetterSandbox(pi: ExtensionAPI): void {
     // Pi's shell setting is only readable once a session directory is known, so
     // it is resolved lazily and re-read on every session start.
     let shellPath: string | undefined;
-    const operations = createSandboxedBashOperations(controller, { shellPath: () => shellPath });
-
-    // Overriding the built-in bash tool by name. Only `operations` changes:
-    // Pi's own definition still owns the schema, streaming, timeout,
-    // cancellation, truncation, session environment, result details, and both
-    // renderers, so every bash contract stays the built-in one.
-    pi.registerTool(createBashToolDefinition(process.cwd(), { operations }));
-
-    // The same backend for user-entered ! and !! commands.
-    pi.on("user_bash", () => ({ operations }));
-
-    // Overriding the built-in write and edit tools the same way: only their
-    // file operations change, so Pi's own definitions keep the parameter
-    // schemas, prompt guidance, call rendering, write previews, edit diffs,
-    // result details, file-mutation queue, and cancellation checks. The guarded
-    // operations run inside that queue, which is where the enforcement belongs.
-    const writeOperations = createSandboxedWriteOperations(controller);
-    const editOperations = createSandboxedEditOperations(controller);
-    const assertReadable = createForegroundReadGuard(controller);
-
-    // `cwd` is what these tools resolve a relative `path` against, so it has to
-    // be the directory Pi itself resolves against. Registration is re-run when
-    // a session reports a different cwd (`pi --cwd ...`), which Pi supports and
-    // refreshes in the same session.
-    let fileToolCwd: string | undefined;
-    const registerFileTools = (cwd: string): void => {
-        if (fileToolCwd === cwd) return;
-        fileToolCwd = cwd;
-        pi.registerTool(createWriteToolDefinition(cwd, { operations: writeOperations }));
-        pi.registerTool(createEditToolDefinition(cwd, { operations: editOperations }));
-        const read = createReadToolDefinition(cwd);
-        pi.registerTool({
-            ...read,
-            execute: (id, params, signal, update, ctx) => {
-                const path = params.path.replace(/^@/, "");
-                const expanded = path === "~" ? homedir() : path.startsWith("~/") ? resolve(homedir(), path.slice(2)) : resolve(cwd, path);
-                return read.execute(id, { ...params, path: assertReadable(expanded) }, signal, update, ctx);
-            },
-        });
-    };
-    registerFileTools(process.cwd());
+    const ownEntry = fileURLToPath(import.meta.url);
+    const boundary = installTaskTools(pi, { controller, cwd: process.cwd(), shellPath: () => shellPath,
+        trustedSources: [ownEntry,
+            join(dirname(ownEntry), "../../extensions/sandbox/index.ts"),
+            join(dirname(ownEntry), "../pi-better-harness/extensions/sandbox/index.ts")],
+    });
 
     pi.on("tool_call", (event) => {
         const status = controller.status();
@@ -142,7 +99,7 @@ export default function piBetterSandbox(pi: ExtensionAPI): void {
 
     pi.on("session_start", (_event, ctx: ExtensionContext) => {
         shellPath = resolveShellPath(ctx.cwd);
-        registerFileTools(ctx.cwd);
+        boundary.register(ctx.cwd);
         paintFooter = (status) => {
             ctx.ui.setStatus(
                 FOOTER_KEY,
@@ -167,6 +124,9 @@ export default function piBetterSandbox(pi: ExtensionAPI): void {
             return;
         }
         controller.beginSession(ctx.cwd, settings.main.enabled);
+        controller.protectRuntimePaths((pi.getAllTools?.() ?? [])
+            .map((tool) => tool.sourceInfo?.path).filter((path): path is string => typeof path === "string" && isAbsolute(path))
+            .map(runtimeCodeRoot));
         controller.setPermissionSettings(settings);
         controller.applyDefault(settings.main.enabled);
 

package/node_modules/pi-better-sandbox/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-sandbox",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Pi extension with independent Main and Subagents permission profiles, file guards, and OS sandbox enforcement.",
   "license": "MIT",
   "type": "module",
@@ -31,9 +31,9 @@
     "access": "public"
   },
   "scripts": {
-    "pretypecheck": "node ../../scripts/sync-shared-sandbox-core.mjs",
-    "pretest": "node ../../scripts/sync-shared-sandbox-core.mjs",
-    "prepack": "node ../../scripts/sync-shared-sandbox-core.mjs",
+    "pretypecheck": "node ../../scripts/sync-shared-sandbox-core.mjs && node ../../scripts/sync-task-sandbox.mjs",
+    "pretest": "node ../../scripts/sync-shared-sandbox-core.mjs && node ../../scripts/sync-task-sandbox.mjs",
+    "prepack": "node ../../scripts/sync-shared-sandbox-core.mjs && node ../../scripts/sync-task-sandbox.mjs",
     "typecheck": "tsc --noEmit",
     "test": "node --import tsx --test test/*.test.ts",
     "verify": "npm run typecheck && npm test"
@@ -44,7 +44,7 @@
     "LICENSE"
   ],
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-coding-agent": ">=0.82.1",
     "@earendil-works/pi-tui": "*",
     "typebox": "*"
   },

package/node_modules/pi-better-sandbox/shared-sandbox-core.ts

@@ -79,6 +79,8 @@ export type SandboxCommandArgs = SandboxTarget & {
     /** Where the macOS backend writes its generated SBPL profile. */
     profilePath: string;
     policy: SandboxWritePolicy;
+    /** Fixed internal helper only: expose its executable in a hidden Linux root. */
+    internalHelperExecutable?: boolean;
 };
 
 /** The wrapper command to spawn: the backend executable and its full argv. */
@@ -410,7 +412,21 @@ const macOSSandboxBackend: SandboxBackend = {
     buildCommand: buildMacOSSandboxCommand,
 };
 
-/** Resolve an executable from PATH without starting it or probing namespaces. */
+/** Resolve only a root-owned system executable; never inspect task PATH. */
+function systemSandboxExecutable(name: string): string | undefined {
+    // Never resolve the host-side confinement launcher through task-influenced PATH.
+    for (const directory of ["/usr/bin", "/bin"]) {
+        const candidate = join(directory, name);
+        try {
+            const info = statSync(candidate);
+            if (!info.isFile() || info.uid !== 0 || (info.mode & 0o022) !== 0) continue;
+            accessSync(candidate, constants.X_OK);
+            return candidate;
+        } catch { /* Try the next system location. */ }
+    }
+    return undefined;
+}
+
 export function executableFromPath(name: string): string | undefined {
     const path = process.env.PATH;
     if (!path) return undefined;
@@ -592,6 +608,12 @@ function buildLinuxPermissionCommand(
             if (existsSync(root)) mounts.push("--ro-bind", root, root);
         }
         mounts.push("--tmpfs", "/tmp");
+        if (args.internalHelperExecutable) {
+            const executable = canonicalizePath(args.execPath, seams);
+            if (!RUNTIME_ROOTS.some((root) => contains(canonicalizePath(root, seams), executable))) {
+                mounts.push("--ro-bind", executable, executable);
+            }
+        }
     } else {
         mounts.push(permissions.outsideProject === "read" ? "--ro-bind" : "--bind", "/tmp", "/tmp");
     }
@@ -605,17 +627,18 @@ function buildLinuxPermissionCommand(
         }
     }
     for (const path of policy.runtimeWrite ?? []) {
-        if ([...credentials, ...policy.denyWrite].some((protectedPath) => contains(path, protectedPath) || contains(protectedPath, path))) {
+        if (credentials.some((protectedPath) => contains(path, protectedPath) || contains(protectedPath, path)) ||
+            policy.denyWrite.some((protectedPath) => contains(protectedPath, path))) {
             throw new Error("Runtime directory overlaps protected credentials or control paths.");
         }
         mounts.push("--bind", path, path);
     }
     const protectedPaths = [...policy.denyWrite,
         ...(permissions.storedCredentials !== "read-write" ? overlappingCredentials : [])];
-    if (writableProject) {
+    for (const writableRoot of [...(writableProject ? [project] : []), ...(policy.runtimeWrite ?? [])]) {
         const materialize = seams.materializeDenyPath ?? materializeDenyPath;
-        const leaves = protectedPaths.filter((path) => contains(project, path) && materialize(path));
-        for (const parent of protectedAncestors(leaves).filter((path) => contains(project, path) && path !== project)) {
+        const leaves = protectedPaths.filter((path) => contains(writableRoot, path) && materialize(path));
+        for (const parent of protectedAncestors(leaves).filter((path) => contains(writableRoot, path) && path !== writableRoot)) {
             mounts.push("--bind", parent, parent);
         }
         for (const path of leaves) mounts.push("--ro-bind", path, path);
@@ -628,7 +651,7 @@ function buildLinuxPermissionCommand(
 }
 
 function linuxSandboxBackend(seams: SandboxSeams): SandboxBackend | undefined {
-    const bwrap = (seams.lookupExecutable ?? executableFromPath)("bwrap");
+    const bwrap = (seams.lookupExecutable ?? systemSandboxExecutable)("bwrap");
     if (!bwrap) return undefined;
     return {
         id: "linux-bubblewrap",
@@ -651,7 +674,7 @@ function selectedSandboxBackend(seams: SandboxSeams): SandboxBackend | undefined
  */
 function unavailableMessage(platform: string): string {
     if (platform === "linux") {
-        return "Linux sandbox requires executable bubblewrap (bwrap) on PATH. Install bubblewrap to enable it.";
+        return "Linux sandbox requires executable bubblewrap (bwrap) in /usr/bin or /bin. Install bubblewrap to enable it.";
     }
     if (platform === "darwin") {
         return "macOS sandbox requires /usr/bin/sandbox-exec, which is missing here.";