pi-better-background-tasks 0.2.5 → 0.2.7

package/README.md

@@ -17,9 +17,45 @@ 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. The foreground sandbox is
+inactive by default, so local tasks ordinarily launch unconfined. A later
+`/sandbox on`, `/sandbox off`, `/sandbox default on|off`, or a 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)
+installs the sandbox extension, but leaves foreground tools and local background
+tasks inactive until a human opts in.
 
 ## 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 +95,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-background-tasks",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "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/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/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/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}`;