pi-better-harness 0.1.25 → 0.1.26

package/README.md

@@ -1,11 +1,12 @@
 # pi-better-harness
 
-`pi-better-harness` is a Pi meta package that installs the core Pi Better Harness extensions for delegated subagents, durable background tasks, and goal tracking.
+`pi-better-harness` is a Pi meta package that installs the core Pi Better Harness extensions: a default-on write sandbox, delegated subagents, durable background tasks, and goal tracking.
 
 ## Quick Answer
 
-Use `pi-better-harness` when you want the full background-work set for Pi. It manages:
+Use `pi-better-harness` when you want the full working set for Pi. It manages:
 
+- `pi-better-sandbox` for a default-on write sandbox around Pi's foreground tools.
 - `pi-better-subagents` for detached, sandboxed subagent runs.
 - `pi-better-background-tasks` for durable shell tasks and watchers.
 - `pi-better-goal` for objective tracking that is aware of background work.
@@ -18,7 +19,7 @@ Use `pi-better-harness` when you want the full background-work set for Pi. It ma
 
 ## Install
 
-Install the three extensions as standalone Pi packages, so Pi displays and manages each by its own package name:
+Install the extensions as standalone Pi packages, so Pi displays and manages each by its own package name:
 
 ```sh
 npx pi-better-harness install
@@ -36,9 +37,25 @@ The bundled installation remains available for compatibility:
 pi install npm:pi-better-harness
 ```
 
+## Ordinary Startup
+
+You keep launching Pi the way you always have:
+
+```sh
+pi
+```
+
+The write sandbox arms itself at every session start — startup, new session, resume, fork, and reload. There is no launcher and no settings file to create.
+
+While it is on, Pi's built-in `bash`, `write`, and `edit` tools, your own `!` / `!!` commands, local background tasks, and subagents can write only under the directory you launched Pi from, minus the packaged deny paths (`.git/hooks`, `.env`, `.env.local`).
+
+**Reads and network access are unrestricted** — this sandbox limits writes only. Writes are confined for those integrated first-party execution paths; Pi's own process, arbitrary `pi.exec` calls, and unrelated third-party extension code are **not** confined. Confinement is also **per surface**: each integrated surface denies its own control plane, not every other surface's, so with several first-party surfaces installed a confined process on one can still write another's control plane.
+
+Sandbox state is human-only: `/sandbox`, `/sandbox on`, `/sandbox off`, `/sandbox deny ...`, and `/sandbox rules` are slash commands with no tool equivalent, so the model cannot turn off its own confinement. `/sandbox off` needs an interactive confirmation and never persists past the session. Full policy: [pi-better-sandbox](https://github.com/1aboveio/pi-better-harness/tree/main/packages/pi-better-sandbox#readme).
+
 ## When To Use
 
-Use the installer when you want all three core extensions with standalone package identities. Install an individual package instead when you only need subagents, shell task supervision, or goal tracking.
+Use the installer when you want every core extension with standalone package identities. Install an individual package instead when you only need the sandbox, subagents, shell task supervision, or goal tracking.
 
 ## Compatibility
 
@@ -46,11 +63,13 @@ Use the installer when you want all three core extensions with standalone packag
 |-------------|---------|
 | Pi | Required |
 | Recommended install | `npx pi-better-harness install` |
+| Write sandbox on macOS | Seatbelt (`sandbox-exec`), ships with the OS |
+| Write sandbox on Linux | Bubblewrap — install `bubblewrap` |
 | Development runtime | Node.js 22+ |
 
 ## Update Or Remove
 
-Remove all three standalone packages:
+Remove every standalone package:
 
 ```sh
 npx pi-better-harness uninstall

package/extensions/sandbox/index.ts

@@ -0,0 +1 @@
+export { default } from "../../node_modules/pi-better-sandbox/index.ts";

package/lib/cli.mjs

@@ -7,6 +7,9 @@ const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const { version } = JSON.parse(readFileSync(resolve(packageRoot, "package.json"), "utf8"));
 
 export const componentPackages = [
+  // The sandbox is configured first so a fresh install has write protection in
+  // place before the extensions whose work it confines.
+  "pi-better-sandbox",
   "pi-better-subagents",
   "pi-better-background-tasks",
   "pi-better-goal",

package/node_modules/pi-better-background-tasks/README.md

@@ -17,9 +17,43 @@ Use `pi-better-background-tasks` when a command should keep running while the fo
 - Keep task metadata and logs available across reloads.
 - Show active work in Pi's background-work navigator.
 - Flag running tasks with no observable output or completed poll as stalled.
+- Confine local task writes to the project directory when `pi-better-sandbox` is enabled.
+
+## Write Sandbox
+
+When [`pi-better-sandbox`](https://github.com/1aboveio/pi-better-harness/tree/main/packages/pi-better-sandbox#readme)
+is installed and enabled, every **local** task captures
+the effective foreground policy at launch and runs under the platform's write
+sandbox: reads and network stay unrestricted, writes are confined to the
+canonical project directory, and denied paths stay denied.
+
+The policy is captured once, when the task starts. A later `/sandbox on`,
+`/sandbox off`, or deny-rule change reaches tasks launched after it; a task
+already running — including a watcher resumed in a later Pi session — keeps the
+policy it started with.
+
+If the foreground sandbox reports `unavailable` or `failed`, a local launch is
+refused with an explanation instead of running unconfined. `/sandbox off` is the
+deliberate way to run local tasks unsandboxed.
+
+Structured remote SSH tasks are unaffected: the foreground sandbox describes this
+machine, and remote work keeps its existing remote semantics. Without
+`pi-better-sandbox` installed, local tasks behave exactly as they always have.
+
+Reads and network access are never restricted; only writes are. Pi's own
+process, `pi.exec` calls, and unrelated third-party extension code stay outside
+the guarantee, and confinement is per surface: a confined process on another
+first-party surface can still write this one's task registry. Installing
+[`pi-better-harness`](https://github.com/1aboveio/pi-better-harness/tree/main/packages/pi-better-harness#readme)
+brings the sandbox in by default, so an ordinary `pi` session confines its
+foreground tools and its local background tasks under one project policy.
 
 ## Remote SSH
 
+For short synchronous remote commands that should return output in the current
+turn, install `pi-better-ssh` and use `remote_bash`. Use background tasks for
+long-running or durable remote jobs and asynchronous health watches.
+
 Prefer structured `ssh` fields over hand-written `ssh` command lines. A remote
 spawn uses a durable tmux session by default, while a remote watch opens one
 direct SSH poll per interval and does not require tmux. The package keeps the
@@ -59,7 +93,7 @@ pi -e npm:pi-better-background-tasks
 
 Use this package for shell commands that need logs, status, cancellation, or completion notifications across a Pi turn.
 
-Do not use it for short commands where the foreground session should wait for the result directly.
+Do not use it for short commands where the foreground session should wait for the result directly; use `remote_bash` from `pi-better-ssh` instead.
 
 ## Compatibility
 

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

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-background-tasks",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "description": "Pi extension for durable background shell tasks, watchers, logs, and status inspection.",
   "license": "MIT",
   "type": "module",
@@ -30,20 +30,23 @@
     "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-ssh-core.mjs && node ../../scripts/sync-shared-sandbox-core.mjs",
+    "prepack": "node ../../scripts/sync-shared-log-utils.mjs && node ../../scripts/sync-shared-ssh-core.mjs && node ../../scripts/sync-shared-sandbox-core.mjs",
+    "pretypecheck": "node ../../scripts/sync-shared-sandbox-core.mjs",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:unit": "vitest run src/conditions.test.ts src/runtime.test.ts",
     "test:e2e": "vitest run src/e2e.test.ts",
     "test:cross-session": "vitest run src/e2e.test.ts -t \"different session\"",
     "test:golden": "vitest run src/golden-path.test.ts",
-    "test:integration": "npm run test:e2e && npm run test:golden"
+    "test:integration": "npm run test:e2e && npm run test:golden",
+    "test:sandbox": "vitest run src/sandbox.test.ts src/sandbox-kernel.test.ts"
   },
   "files": [
     "src/**/*.ts",
     "!src/**/*.test.ts",
     "!src/test-support/**",
+    "!src/shared-ssh-core/test-support/**",
     "README.md"
   ],
   "peerDependencies": {

package/node_modules/pi-better-background-tasks/src/index.ts

@@ -2,11 +2,15 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { disposeBackgroundWorkNavigator } from "./shared-navigator.ts";
 import { registerBackgroundTasksGoalProvider } from "./goal-provider.js";
 import { clearBackgroundTasksNavigatorSession, ensureBackgroundTasksNavigator, ensureBackgroundTasksNavigatorProvider } from "./navigator-provider.js";
+import { observeForegroundSandboxPolicy } from "./sandbox.js";
 import { registerTools } from "./tools.js";
 
 export default function backgroundTasksExtension(pi: ExtensionAPI): void {
   registerBackgroundTasksGoalProvider(pi);
   ensureBackgroundTasksNavigatorProvider(pi);
+  // Subscribed at load so a sandbox extension that publishes later is heard, and
+  // asked for a snapshot in case one published before this extension existed.
+  observeForegroundSandboxPolicy(pi);
   pi.on("session_start", async (_event, ctx) => {
     registerBackgroundTasksGoalProvider(pi);
     ensureBackgroundTasksNavigator(ctx);

package/node_modules/pi-better-background-tasks/src/process.ts

@@ -6,6 +6,9 @@ import type { CommandResult, CommandSpec } from "./types.js";
 
 const DEFAULT_SHELL = process.env.PI_BETTER_BACKGROUND_TASKS_SHELL || "/bin/bash";
 
+/** How long a timed-out process group has to exit on SIGTERM before SIGKILL. */
+const TERMINATION_GRACE_MS = 2_000;
+
 export interface SpawnedProcess {
   child: ChildProcess;
   pgid?: number;
@@ -36,6 +39,22 @@ export function spawnCommand(spec: CommandSpec, logPath: string, detached: boole
   return { child, pgid: detached && child.pid ? child.pid : undefined };
 }
 
+/**
+ * Run one command to completion and collect its output.
+ *
+ * A timeout has to reach the whole process tree, not just the process spawned
+ * here. Two things make that necessary rather than tidy:
+ *
+ * - The command may not be what runs. Under the Linux write sandbox the spawned
+ *   process is `bwrap`, which forks the real command instead of exec'ing it, so
+ *   a signal to the spawned pid never reaches the command at all. (macOS
+ *   `sandbox-exec` execs its target, which is why the same signal works there.)
+ * - `close` fires when the output pipes close, not when the child exits. A
+ *   surviving grandchild keeps holding them, so signalling only the direct child
+ *   leaves this promise pending indefinitely and the caller's deadline unenforced.
+ *
+ * So the child leads its own process group, and a timeout signals that group.
+ */
 export function runCommandOnce(
   spec: CommandSpec,
   maxBufferBytes = 1024 * 1024,
@@ -43,7 +62,7 @@ export function runCommandOnce(
 ): Promise<CommandResult> {
   validateCommandSpec(spec);
   const startedAt = Date.now();
-  const child = spawnArgs(spec, false, ["ignore", "pipe", "pipe"]);
+  const child = spawnArgs(spec, true, ["ignore", "pipe", "pipe"]);
   let stdout = "";
   let stderr = "";
   let timedOut = false;
@@ -54,17 +73,38 @@ export function runCommandOnce(
     if (Buffer.byteLength(stderr) < maxBufferBytes) stderr += chunk.toString("utf8");
   });
   return new Promise((resolve, reject) => {
+    // The group outlives the leader as long as any member is alive, so the
+    // kernel keeps the id reserved and this stays addressable after the spawned
+    // process itself has been reaped.
+    const signalGroup = (signal: NodeJS.Signals): void => {
+      if (child.pid === undefined) return;
+      try {
+        stopProcessGroup(child.pid, undefined, signal);
+      } catch {
+        // Nothing left in the group: the tree is already gone.
+      }
+    };
+    let escalation: NodeJS.Timeout | undefined;
     const timeout = timeoutMs === undefined ? undefined : setTimeout(() => {
       timedOut = true;
-      child.kill("SIGTERM");
+      signalGroup("SIGTERM");
+      // SIGTERM is a request. Whatever still holds the output pipes after the
+      // grace period is exactly what would keep this promise pending, so the
+      // group is killed outright rather than waited on.
+      escalation = setTimeout(() => signalGroup("SIGKILL"), TERMINATION_GRACE_MS);
+      escalation.unref();
     }, Math.max(1, timeoutMs));
     timeout?.unref();
-    child.on("error", (error) => {
+    const settle = (): void => {
       if (timeout) clearTimeout(timeout);
+      if (escalation) clearTimeout(escalation);
+    };
+    child.on("error", (error) => {
+      settle();
       reject(error);
     });
     child.on("close", (exitCode, signal) => {
-      if (timeout) clearTimeout(timeout);
+      settle();
       resolve({
         exitCode,
         signal,
@@ -78,13 +118,17 @@ export function runCommandOnce(
   });
 }
 
-export function stopProcessGroup(pid: number, pgid?: number): void {
+export function stopProcessGroup(
+  pid: number,
+  pgid?: number,
+  signal: NodeJS.Signals = "SIGTERM",
+): void {
   const target = pgid ?? pid;
   try {
-    process.kill(-target, "SIGTERM");
+    process.kill(-target, signal);
     return;
   } catch {
-    process.kill(pid, "SIGTERM");
+    process.kill(pid, signal);
   }
 }
 
@@ -97,22 +141,29 @@ export function processExists(pid: number): boolean {
   }
 }
 
+/**
+ * The executable and argument vector a spec runs as.
+ *
+ * Shell specs become an explicit `bash -lc` invocation rather than a shell
+ * string, so every caller — spawning directly, or wrapping the same launch in an
+ * OS sandbox — starts from one definition of what actually executes.
+ */
+export function commandExecution(spec: CommandSpec): { execPath: string; execArgs: string[] } {
+  if (spec.shell === false) {
+    const [command, ...args] = spec.argv!;
+    return { execPath: command!, execArgs: args };
+  }
+  return { execPath: DEFAULT_SHELL, execArgs: ["-lc", spec.command!] };
+}
+
 function spawnArgs(
   spec: CommandSpec,
   detached: boolean,
   stdio: ["ignore", "pipe" | number, "pipe" | number],
 ): ChildProcess {
   const env = { ...process.env, ...spec.env };
-  if (spec.shell === false) {
-    const [command, ...args] = spec.argv!;
-    return spawn(command!, args, {
-      cwd: spec.cwd,
-      env,
-      detached,
-      stdio,
-    });
-  }
-  return spawn(DEFAULT_SHELL, ["-lc", spec.command!], {
+  const { execPath, execArgs } = commandExecution(spec);
+  return spawn(execPath, execArgs, {
     cwd: spec.cwd,
     env,
     detached,

package/node_modules/pi-better-background-tasks/src/registry.ts

@@ -32,6 +32,17 @@ export function logPathFor(id: string): string {
   return join(taskDir(id), "output.log");
 }
 
+/**
+ * Where a task keeps the generated sandbox profile it launched under.
+ *
+ * It lives beside the task's own log and metadata so it survives exactly as long
+ * as the task does: a watch resumed in a later Pi session re-reads the profile it
+ * started with instead of a profile some other session has since rewritten.
+ */
+export function sandboxProfilePathFor(id: string): string {
+  return join(taskDir(id), "sandbox.sb");
+}
+
 export function nextTaskId(): string {
   seq += 1;
   return `bg_${process.pid.toString(36)}_${Date.now().toString(36)}_${seq}`;