pi-better-background-tasks 0.2.5 → 0.2.6

package/src/runtime.ts

@@ -5,7 +5,8 @@ import { evaluateCondition } from "./conditions.js";
 import { processExists, runCommandOnce, spawnCommand, stopProcessGroup } from "./process.js";
 import { DEFAULT_TMUX_BOOTSTRAP_TIMEOUT_MS, expandSshRemoteTaskPreset } from "./remote-task-preset.js";
 import type { RemoteRunner, ResolvedSshRemoteTask } from "./remote-task-preset.js";
-import { ensureTaskDir, logPathFor, nextTaskId, readMeta, writeMeta } from "./registry.js";
+import { ensureTaskDir, logPathFor, nextTaskId, readMeta, sandboxProfilePathFor, writeMeta } from "./registry.js";
+import { confineCommandSpec, resolveForegroundSandboxPlan } from "./sandbox.js";
 import { getCallbackBatcher } from "./shared-callback-batcher.js";
 import type {
   BackgroundTaskCallbackOrigin,
@@ -32,6 +33,9 @@ const REMOTE_SESSION_POLL_MS = 100;
 
 export const DEFAULT_WATCH_TIMEOUT_SECONDS = 15 * 60;
 
+/** Remote SSH launches never consult the local foreground sandbox policy. */
+const UNCONFINED_LAUNCH = { confined: false } as const;
+
 export type ActiveSessionProvider = () => BackgroundTaskCallbackOrigin | undefined;
 
 export interface SpawnTaskParams extends CommandSpec {
@@ -69,6 +73,10 @@ export function spawnTask(
   getActiveSession?: ActiveSessionProvider,
   dependencies: TaskRuntimeDependencies = {},
 ): BackgroundTaskMeta {
+  // Resolved before any task directory, log, or metadata exists so a blocked
+  // launch leaves nothing behind. Remote SSH work is not a local execution path
+  // and keeps its existing remote semantics untouched.
+  const sandboxPlan = params.ssh ? UNCONFINED_LAUNCH : resolveForegroundSandboxPlan(pi);
   const id = nextTaskId();
   const cwd = params.cwd ?? defaultCwd;
   const logPath = logPathFor(id);
@@ -85,12 +93,15 @@ export function spawnTask(
     }, dependencies.remoteRunner)
     : undefined;
   const commandSpec: CommandSpec = remoteTask?.commandSpec ?? { ...params, cwd, shell: params.shell ?? true };
+  const launchSpec = remoteTask
+    ? commandSpec
+    : confineCommandSpec(commandSpec, sandboxPlan, sandboxProfilePathFor(id));
   const tmuxBacked = remoteTask?.metadata.remote.session === "tmux";
   const spawned = tmuxBacked
     ? undefined
     : remoteTask
       ? remoteTask.spawn(logPath, true)
-      : spawnCommand(commandSpec, logPath, true);
+      : spawnCommand(launchSpec, logPath, true);
   const now = Date.now();
   const meta: BackgroundTaskMeta = {
     id,
@@ -108,6 +119,7 @@ export function spawnTask(
     shell: commandSpec.shell,
     cwd,
     env: params.env,
+    launchArgv: launchArgvOf(commandSpec, launchSpec),
     maxLogBytes: resolveMaxLogBytes(params.max_log_bytes),
     pid: spawned?.child.pid,
     pgid: spawned?.pgid,
@@ -296,6 +308,7 @@ export function startWatchTask(
   getActiveSession?: ActiveSessionProvider,
   dependencies: TaskRuntimeDependencies = {},
 ): BackgroundTaskMeta {
+  const sandboxPlan = params.ssh ? UNCONFINED_LAUNCH : resolveForegroundSandboxPlan(pi);
   const id = nextTaskId();
   const cwd = params.cwd ?? defaultCwd;
   const now = Date.now();
@@ -311,6 +324,9 @@ export function startWatchTask(
     }, dependencies.remoteRunner)
     : undefined;
   const commandSpec: CommandSpec = remoteTask?.commandSpec ?? { ...params, cwd, shell: params.shell ?? true };
+  const launchSpec = remoteTask
+    ? commandSpec
+    : confineCommandSpec(commandSpec, sandboxPlan, sandboxProfilePathFor(id));
   const meta: BackgroundTaskMeta = {
     id,
     name: params.name,
@@ -328,6 +344,7 @@ export function startWatchTask(
     shell: commandSpec.shell,
     cwd,
     env: params.env,
+    launchArgv: launchArgvOf(commandSpec, launchSpec),
     maxLogBytes: resolveMaxLogBytes(params.max_log_bytes),
     spawnPid: process.pid,
     successWhen: params.success_when,
@@ -796,6 +813,17 @@ function getCallbackSuppressionReason(
 }
 
 function commandSpecFromMeta(meta: BackgroundTaskMeta): CommandSpec {
+  // A task that launched under a sandbox re-runs the wrapper it captured then,
+  // not whatever the foreground policy says now — including after a resume in a
+  // later Pi session.
+  if (meta.launchArgv?.length) {
+    return {
+      argv: meta.launchArgv,
+      shell: false,
+      cwd: meta.cwd,
+      env: meta.env,
+    };
+  }
   return {
     command: meta.command,
     argv: meta.argv,
@@ -805,6 +833,11 @@ function commandSpecFromMeta(meta: BackgroundTaskMeta): CommandSpec {
   };
 }
 
+/** Record a launch vector only when confinement actually rewrote the spec. */
+function launchArgvOf(commandSpec: CommandSpec, launchSpec: CommandSpec): string[] | undefined {
+  return launchSpec === commandSpec ? undefined : launchSpec.argv;
+}
+
 function scheduleLogRetention(id: string): void {
   stopLogRetention(id);
   const timer = setInterval(() => {

package/src/sandbox.ts

@@ -0,0 +1,285 @@
+/**
+ * Foreground write-sandbox policy for locally launched background tasks.
+ *
+ * `pi-better-sandbox` owns the foreground policy and publishes an immutable
+ * snapshot of it on `pi.events`. This module is the consumer side of that wire
+ * contract: it mirrors the latest snapshot, and turns it into a confined
+ * command at the moment a local task launches.
+ *
+ * Two rules make the behaviour predictable:
+ *
+ * 1. **Snapshot at launch, never a live reference.** The wrapped executable and
+ *    argv are resolved once, when the task starts, and are what the task keeps
+ *    running. A later `/sandbox off` or deny-rule change therefore reaches only
+ *    tasks launched after it.
+ * 2. **Fail closed.** Once the foreground state says a sandbox should apply, a
+ *    missing or unusable backend blocks the launch. The local command is never
+ *    retried unconfined behind the operator's back. The single exception is an
+ *    explicitly `disabled` state, which is a human's deliberate decision.
+ *
+ * The contract is duplicated here rather than imported: `pi-better-sandbox` is
+ * an optional peer that this package must keep working without. Two channel
+ * names and a payload shape are the entire coupling, and both packages own
+ * tests that pin them.
+ */
+
+import { mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname } from "node:path";
+
+import { commandExecution } from "./process.js";
+import { baseDir } from "./registry.js";
+import { maybeBuildSandboxCommand, type SandboxSeams } from "./shared-sandbox-core.js";
+import type { CommandSpec } from "./types.js";
+
+/**
+ * What an operator can do about a missing backend here.
+ *
+ * A background task inherits the session's foreground policy, so its remedy is
+ * the session's: the slash command. `sandbox:false` is the subagent tool's
+ * opt-out and means nothing on this surface. The text is duplicated rather than
+ * imported for the same reason the rest of this contract is — `pi-better-sandbox`
+ * is an optional peer.
+ */
+export const FOREGROUND_SANDBOX_REMEDY =
+  "Run unconfined on purpose with /sandbox off, or work in a session that has a backend.";
+
+/** Channel `pi-better-sandbox` publishes every effective-policy change on. */
+export const FOREGROUND_SANDBOX_POLICY_CHANNEL = "pi-better-sandbox:policy";
+
+/** Channel a consumer emits on to ask for the current policy. */
+export const FOREGROUND_SANDBOX_POLICY_REQUEST_CHANNEL = "pi-better-sandbox:policy-request";
+
+/**
+ * What the foreground sandbox is doing right now.
+ *
+ * - `enabled`     - confine locally launched tasks.
+ * - `disabled`    - a human switched protection off; launch tasks as before.
+ * - `unavailable` - no backend on this platform; block protected launches.
+ * - `failed`      - protection cannot be applied here; block protected launches.
+ */
+export type ForegroundSandboxState = "enabled" | "disabled" | "unavailable" | "failed";
+
+/** The published snapshot, narrowed to the fields a task launch needs. */
+export interface ForegroundSandboxPolicy {
+  readonly state: ForegroundSandboxState;
+  /** The only writable subtree while `state` is `enabled`. */
+  readonly writableRoot?: string | undefined;
+  /** Canonical paths that stay non-writable inside the writable root. */
+  readonly denyWrite: readonly string[];
+  /** Human-readable evidence for why `state` is what it is. */
+  readonly reason: string;
+}
+
+/** The minimum `pi.events` surface this module uses. */
+export interface PolicyEventBus {
+  emit(channel: string, data: unknown): void;
+  on(channel: string, handler: (data: unknown) => void): unknown;
+}
+
+/** Thrown instead of launching a local task the foreground policy forbids. */
+export class ForegroundSandboxBlockedError extends Error {
+  readonly policy: ForegroundSandboxPolicy;
+
+  constructor(policy: ForegroundSandboxPolicy, detail?: string) {
+    super(
+      `Foreground sandbox is ${policy.state}; this local background task was blocked rather than launched unconfined. ${detail ?? policy.reason}`,
+    );
+    this.name = "ForegroundSandboxBlockedError";
+    this.policy = policy;
+  }
+}
+
+/** How one local launch should be confined. Resolved before any task state exists. */
+export type ForegroundSandboxPlan =
+  | { readonly confined: false }
+  | {
+      readonly confined: true;
+      readonly writableRoot: string;
+      readonly denyWrite: readonly string[];
+    };
+
+const UNCONFINED: ForegroundSandboxPlan = { confined: false };
+
+const VALID_STATES = new Set<string>(["enabled", "disabled", "unavailable", "failed"]);
+
+/**
+ * The latest snapshot per event bus.
+ *
+ * Keyed by the bus rather than kept in one module variable so that separate Pi
+ * sessions inside one process (and separate tests) cannot read each other's
+ * policy.
+ */
+const mirrors = new WeakMap<PolicyEventBus, { policy: ForegroundSandboxPolicy | undefined }>();
+
+function eventBusOf(pi: unknown): PolicyEventBus | undefined {
+  const events = (pi as { events?: unknown } | undefined)?.events;
+  if (!events || typeof events !== "object") return undefined;
+  const candidate = events as Partial<PolicyEventBus>;
+  if (typeof candidate.on !== "function" || typeof candidate.emit !== "function") return undefined;
+  return candidate as PolicyEventBus;
+}
+
+/**
+ * Accept a published payload only when it carries a state this module
+ * understands, so an unrelated extension emitting on the channel cannot clear a
+ * real policy or invent one.
+ */
+function readPolicy(data: unknown): ForegroundSandboxPolicy | undefined {
+  if (!data || typeof data !== "object") return undefined;
+  const value = data as Record<string, unknown>;
+  if (typeof value.state !== "string" || !VALID_STATES.has(value.state)) return undefined;
+  const writableRoot = typeof value.writableRoot === "string" ? value.writableRoot : undefined;
+  const denyWrite = Array.isArray(value.denyWrite)
+    ? value.denyWrite.filter((entry): entry is string => typeof entry === "string")
+    : [];
+  return {
+    state: value.state as ForegroundSandboxState,
+    writableRoot,
+    denyWrite: Object.freeze([...denyWrite]),
+    reason: typeof value.reason === "string" ? value.reason : "No reason was published.",
+  };
+}
+
+/**
+ * Start mirroring foreground policy on this session's event bus.
+ *
+ * Idempotent, and safe in either extension load order. If `pi-better-sandbox`
+ * loaded first, its last publication is already gone (the bus has no replay), so
+ * we ask for a fresh one on the request channel. If it loads later, its own
+ * session-start publication reaches the subscription registered here.
+ */
+export function observeForegroundSandboxPolicy(pi: unknown): void {
+  const events = eventBusOf(pi);
+  if (!events || mirrors.has(events)) return;
+
+  const mirror: { policy: ForegroundSandboxPolicy | undefined } = { policy: undefined };
+  mirrors.set(events, mirror);
+  events.on(FOREGROUND_SANDBOX_POLICY_CHANNEL, (data) => {
+    const policy = readPolicy(data);
+    if (policy) mirror.policy = policy;
+  });
+  events.emit(FOREGROUND_SANDBOX_POLICY_REQUEST_CHANNEL, undefined);
+}
+
+/**
+ * The foreground policy as of right now, or `undefined` when no sandbox
+ * extension is publishing one.
+ *
+ * Asks for a re-publication first. Pi's event bus dispatches synchronously, so
+ * the answer to that request has already been mirrored by the time this
+ * returns; if a future bus were to defer, the last published snapshot is still
+ * returned rather than nothing.
+ */
+export function currentForegroundSandboxPolicy(pi: unknown): ForegroundSandboxPolicy | undefined {
+  observeForegroundSandboxPolicy(pi);
+  const events = eventBusOf(pi);
+  if (!events) return undefined;
+  events.emit(FOREGROUND_SANDBOX_POLICY_REQUEST_CHANNEL, undefined);
+  return mirrors.get(events)?.policy;
+}
+
+/**
+ * Decide how a local launch must be confined, before the task has an id, a
+ * directory, or a log.
+ *
+ * Throws for every state that is neither confinable nor a human's explicit
+ * opt-out, which is what keeps a blocked launch from leaving task state behind.
+ */
+export function resolveForegroundSandboxPlan(pi: unknown): ForegroundSandboxPlan {
+  return planFor(currentForegroundSandboxPolicy(pi));
+}
+
+/** The plan for one already-read policy. Exposed for tests and reuse. */
+export function planFor(policy: ForegroundSandboxPolicy | undefined): ForegroundSandboxPlan {
+  // No sandbox extension is publishing: this package is installed on its own and
+  // keeps its historical unsandboxed behaviour.
+  if (!policy) return UNCONFINED;
+  if (policy.state === "disabled") return UNCONFINED;
+  if (policy.state !== "enabled" || !policy.writableRoot) {
+    throw new ForegroundSandboxBlockedError(policy);
+  }
+  return { confined: true, writableRoot: policy.writableRoot, denyWrite: policy.denyWrite };
+}
+
+/**
+ * Wrap a local command in the platform's write sandbox.
+ *
+ * The result is an ordinary `CommandSpec` whose argv is the backend wrapper
+ * around the exact executable and arguments the unconfined spec would have run,
+ * so spawning, streaming, timeouts, process-group termination, and env handling
+ * all stay on their existing code paths. The generated macOS profile is written
+ * to `profilePath`, which callers put inside the task's own directory so a
+ * resumed watch re-reads the policy it launched with.
+ *
+ * `seams` defaults to the real platform and PATH. It exists so a caller — in
+ * practice a test — can prove the argv this produces for a backend other than
+ * the one the host happens to have.
+ */
+export function confineCommandSpec(
+  spec: CommandSpec,
+  plan: ForegroundSandboxPlan,
+  profilePath: string,
+  seams: SandboxSeams = {},
+): CommandSpec {
+  if (!plan.confined) return spec;
+
+  const { execPath, execArgs } = commandExecution(spec);
+  // The generated profile is written here, so its directory must exist before
+  // the backend builds the command.
+  mkdirSync(dirname(profilePath), { recursive: true });
+  // Task state is this package's control plane: `meta.json` carries the launch
+  // vector a resumed watch re-runs verbatim, and `sandbox.sb` is the profile the
+  // launch is confined by. It lives under the system temp directory, which both
+  // backends leave writable by design, so a confined task could otherwise
+  // rewrite what its own next poll executes and choose its own confinement.
+  //
+  // Denying the whole registry closes that without moving any state, and without
+  // costing the task anything it actually needs: pi writes the registry from
+  // outside the sandbox, and the task's log reaches it through a descriptor
+  // opened before the launch, which no later mount or profile can revoke.
+  //
+  // Created here rather than assumed, because the Linux backend materializes an
+  // absent denied path as an empty *file* and this one has to be a directory.
+  const controlPlane = baseDir();
+  mkdirSync(controlPlane, { recursive: true });
+  const denyWrite = [...plan.denyWrite, controlPlane];
+  let command;
+  try {
+    command = maybeBuildSandboxCommand(
+      {
+        profilePath,
+        policy: {
+          writableRoot: plan.writableRoot,
+          denyWrite,
+          home: homedir(),
+        },
+        execPath,
+        execArgs,
+      },
+      // `explicitSandbox` because the foreground state already said a sandbox
+      // applies: an absent or unusable backend must throw here rather than hand
+      // back an unwrapped command. The remedy is the foreground one: this policy
+      // came from the session, and the session is where it is switched off.
+      { sandboxEnabled: true, explicitSandbox: true, remedy: FOREGROUND_SANDBOX_REMEDY },
+      seams,
+    );
+  } catch (error) {
+    throw blocked(plan, error instanceof Error ? error.message : String(error));
+  }
+  if (!command) throw blocked(plan, "no sandbox backend was applied");
+
+  return { ...spec, argv: [command.file, ...command.fileArgs], shell: false };
+}
+
+function blocked(plan: ForegroundSandboxPlan & { confined: true }, detail: string): Error {
+  return new ForegroundSandboxBlockedError(
+    {
+      state: "failed",
+      writableRoot: plan.writableRoot,
+      denyWrite: plan.denyWrite,
+      reason: detail,
+    },
+    detail,
+  );
+}