pi-better-background-tasks 0.2.6 → 0.2.8

package/README.md

@@ -27,8 +27,10 @@ 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
+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.
 
@@ -45,8 +47,8 @@ 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.
+installs the sandbox extension, but leaves foreground tools and local background
+tasks inactive until a human opts in.
 
 ## Remote SSH
 

package/package.json

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

package/src/process.ts

@@ -1,10 +1,47 @@
-import { spawn } from "node:child_process";
-import { appendFileSync, closeSync, mkdirSync, openSync, writeSync } from "node:fs";
-import { dirname } from "node:path";
+import { spawn, spawnSync } from "node:child_process";
+import { appendFileSync, closeSync, existsSync, mkdirSync, openSync, writeSync } from "node:fs";
+import { dirname, join } from "node:path";
 import type { ChildProcess } from "node:child_process";
 import type { CommandResult, CommandSpec } from "./types.js";
 
-const DEFAULT_SHELL = process.env.PI_BETTER_BACKGROUND_TASKS_SHELL || "/bin/bash";
+/** Known Git for Windows locations; `bash -lc` needs a real bash, not the WSL shim. */
+const WINDOWS_BASH_CANDIDATES = [
+  "C:\\Program Files\\Git\\bin\\bash.exe",
+  "C:\\Program Files (x86)\\Git\\bin\\bash.exe",
+  "C:\\Program Files\\Git\\usr\\bin\\bash.exe",
+];
+
+/**
+ * Resolve the shell used for `command` specs.
+ *
+ * POSIX keeps `/bin/bash`. Windows has no `/bin/bash`, and the `bash.exe` found
+ * on PATH is usually the WSL launcher in System32 or the WindowsApps alias,
+ * either of which would run the command inside WSL instead of Windows. Prefer
+ * an explicit override, then Git for Windows, then a non-WSL `bash.exe` on PATH.
+ *
+ * Resolved lazily at spawn time, not module load: env-injection extensions
+ * (e.g. pi-env) may apply settings.json `env` values after this module is
+ * evaluated, and those overrides must still take effect.
+ *
+ * Exposed for tests and reuse.
+ */
+export function resolveDefaultShell(): string {
+  const fromEnv = process.env.PI_BETTER_BACKGROUND_TASKS_SHELL;
+  if (fromEnv) return fromEnv;
+  if (process.platform !== "win32") return "/bin/bash";
+  for (const candidate of WINDOWS_BASH_CANDIDATES) {
+    if (existsSync(candidate)) return candidate;
+  }
+  for (const dir of (process.env.PATH ?? "").split(";")) {
+    const trimmed = dir.trim();
+    if (!trimmed || /(^|[\\/])(system32|windowsapps)([\\/]|$)/i.test(trimmed)) continue;
+    const candidate = join(trimmed, "bash.exe");
+    if (existsSync(candidate)) return candidate;
+  }
+  // Nothing usable found: keep the POSIX default so the failure surfaces as a
+  // logged spawn error for the task instead of crashing the whole host process.
+  return "/bin/bash";
+}
 
 /** How long a timed-out process group has to exit on SIGTERM before SIGKILL. */
 const TERMINATION_GRACE_MS = 2_000;
@@ -26,15 +63,98 @@ export function validateCommandSpec(spec: CommandSpec): void {
   }
 }
 
+/** Convert a Windows path to the `/c/...` form MSYS bash resolves in redirections. Exposed for tests and reuse. */
+export function toMsysPath(path: string): string {
+  const forward = path.replace(/\\/g, "/");
+  const drive = /^([A-Za-z]):(\/.+)$/.exec(forward);
+  return drive ? `/${drive[1].toLowerCase()}${drive[2]}` : forward;
+}
+
+/** Single-quote a value for safe literal use in a bash script line. Exposed for tests and reuse. */
+export function bashSingleQuote(value: string): string {
+  return `'${value.replace(/'/g, "'\\''")}'`;
+}
+
+/**
+ * On Windows, numeric fds above 2 are unusable as child stdio: Node spawns the
+ * process, but its output handles end up broken, every write fails, and shell
+ * tasks exit 1 having produced nothing. (POSIX inherits the fd normally.)
+ *
+ * Instead of handing the child a log fd, the shell opens and redirects into the
+ * log itself. Output stays durable — written by the detached task directly, so
+ * logging continues after pi exits — and the child runs with no inherited
+ * stdio. Raw argv specs get a bash trampoline (`exec`) that performs the same
+ * redirect before replacing itself with the target program.
+ *
+ * Exposed for tests and reuse.
+ */
+export function withWindowsLogRedirect(spec: CommandSpec, logPath: string): CommandSpec {
+  const redirectLine = `exec >> ${bashSingleQuote(toMsysPath(logPath))} 2>&1`;
+  if (spec.shell === false) {
+    const argvText = spec.argv!.map((arg) => bashSingleQuote(String(arg))).join(" ");
+    return {
+      ...spec,
+      shell: true,
+      // The MSYS2 runtime rewrites POSIX-looking argv (e.g. `/c`, `/opt/x.sh`)
+      // when exec'ing native Windows binaries. Node spawn passed argv verbatim,
+      // so conversion is disabled to keep raw-argv semantics unchanged. The
+      // redirect target is unaffected: bash resolves it itself, already in
+      // `/c/...` form.
+      command: `${redirectLine}\nexport MSYS2_ARG_CONV_EXCL='*'\nexec ${argvText}`,
+    };
+  }
+  return { ...spec, command: `${redirectLine}\n${spec.command}` };
+}
+
 export function spawnCommand(spec: CommandSpec, logPath: string, detached: boolean): SpawnedProcess {
   validateCommandSpec(spec);
   mkdirSync(dirname(logPath), { recursive: true });
-  const fd = openSync(logPath, "a");
-  const child = spawnArgs(spec, detached, ["ignore", fd, fd]);
-  writeSync(fd, `\n--- spawn ${new Date().toISOString()} pid=${child.pid ?? "unknown"} ---\n`);
-  closeSync(fd);
+  const windows = process.platform === "win32";
+  const launchSpec = windows ? withWindowsLogRedirect(spec, logPath) : spec;
+  let fd: number | undefined;
+  let stdio: SpawnStdio;
+  if (windows) {
+    stdio = ["ignore", "ignore", "ignore"];
+  } else {
+    fd = openSync(logPath, "a");
+    stdio = ["ignore", fd, fd];
+  }
+  const child = spawnArgs(launchSpec, detached, stdio);
+  const marker = `\n--- spawn ${new Date().toISOString()} pid=${child.pid ?? "unknown"} ---\n`;
+  try {
+    if (fd !== undefined) {
+      writeSync(fd, marker);
+    } else {
+      // The detached child is already running; a throw here would orphan it
+      // with no task metadata, so the marker write is best effort.
+      appendFileSync(logPath, marker);
+    }
+  } catch {
+    // Log unavailable; the runtime close handler still records the failure.
+  } finally {
+    if (fd !== undefined) {
+      try { closeSync(fd); } catch { /* best effort */ }
+    }
+  }
+  // Spawn failures (ENOENT, bad cwd, permission denied) surface as an 'error'
+  // event. With no listener Node turns it into an uncaughtException that takes
+  // down the whole host process; log it here and let the runtime's 'close'
+  // handler finalize the task as failed.
+  child.on("error", (error) => {
+    try {
+      const code = (error as NodeJS.ErrnoException).code ?? "unknown";
+      appendFileSync(logPath, `\n--- spawn error ${new Date().toISOString()} code=${code} message=${error.message} ---\n`);
+    } catch {
+      // Log unavailable; the runtime close handler still records the failure.
+    }
+  });
   child.on("close", (code, signal) => {
-    appendFileSync(logPath, `\n--- exit ${new Date().toISOString()} code=${code ?? "null"} signal=${signal ?? "null"} ---\n`);
+    try {
+      appendFileSync(logPath, `\n--- exit ${new Date().toISOString()} code=${code ?? "null"} signal=${signal ?? "null"} ---\n`);
+    } catch {
+      // Log unavailable (swept tmp dir, ACL change): a throw here would crash
+      // the host; the runtime already finalized the task from meta.
+    }
   });
   return { child, pgid: detached && child.pid ? child.pid : undefined };
 }
@@ -80,18 +200,32 @@ export function runCommandOnce(
       if (child.pid === undefined) return;
       try {
         stopProcessGroup(child.pid, undefined, signal);
-      } catch {
+      } catch (error) {
+        if (process.platform === "win32") throw error;
         // Nothing left in the group: the tree is already gone.
       }
     };
     let escalation: NodeJS.Timeout | undefined;
     const timeout = timeoutMs === undefined ? undefined : setTimeout(() => {
       timedOut = true;
-      signalGroup("SIGTERM");
+      try {
+        signalGroup("SIGTERM");
+      } catch (error) {
+        settle();
+        reject(error);
+        return;
+      }
       // 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 = setTimeout(() => {
+        try {
+          signalGroup("SIGKILL");
+        } catch (error) {
+          settle();
+          reject(error);
+        }
+      }, TERMINATION_GRACE_MS);
       escalation.unref();
     }, Math.max(1, timeoutMs));
     timeout?.unref();
@@ -118,11 +252,41 @@ export function runCommandOnce(
   });
 }
 
+/**
+ * Stop a task's process tree.
+ *
+ * POSIX signals the process group (`-target`), falling back to the direct pid
+ * when the group is already gone. Windows has no process groups in libuv, and
+ * `process.kill(pid)` would only terminate the spawned `bash.exe` while real
+ * work survives in grandchildren — so the tree is terminated with
+ * `taskkill /T /F` instead. Windows has no graceful signal delivery, so the
+ * requested signal is informational there.
+ */
 export function stopProcessGroup(
   pid: number,
   pgid?: number,
   signal: NodeJS.Signals = "SIGTERM",
 ): void {
+  if (process.platform === "win32") {
+    const result = spawnSync("taskkill", ["/T", "/F", "/PID", String(pid)], {
+      encoding: "utf8",
+      windowsHide: true,
+    });
+    if (result.error) {
+      const code = (result.error as NodeJS.ErrnoException).code;
+      throw new Error(`taskkill could not start for PID ${pid}${code ? ` (${code})` : ""}: ${result.error.message}`, {
+        cause: result.error,
+      });
+    }
+    if (result.status === 0) return;
+    // A child can exit between the caller's liveness check and taskkill. That
+    // race is success; any still-live PID means the tree was not terminated.
+    if (!processExists(pid)) return;
+    const detail = String(result.stderr ?? result.stdout ?? "").replace(/\s+/g, " ").trim();
+    throw new Error(
+      `taskkill failed with exit ${result.status ?? "unknown"} for PID ${pid}${detail ? `: ${detail}` : ""}`,
+    );
+  }
   const target = pgid ?? pid;
   try {
     process.kill(-target, signal);
@@ -153,13 +317,16 @@ export function commandExecution(spec: CommandSpec): { execPath: string; execArg
     const [command, ...args] = spec.argv!;
     return { execPath: command!, execArgs: args };
   }
-  return { execPath: DEFAULT_SHELL, execArgs: ["-lc", spec.command!] };
+  return { execPath: resolveDefaultShell(), execArgs: ["-lc", spec.command!] };
 }
 
+/** Stdio for a spawned task: stdin is always ignored; stdout/stderr are piped (collected) or ignored (redirected into the log by the child itself). */
+type SpawnStdio = ["ignore", "pipe" | "ignore" | number, "pipe" | "ignore" | number];
+
 function spawnArgs(
   spec: CommandSpec,
   detached: boolean,
-  stdio: ["ignore", "pipe" | number, "pipe" | number],
+  stdio: SpawnStdio,
 ): ChildProcess {
   const env = { ...process.env, ...spec.env };
   const { execPath, execArgs } = commandExecution(spec);
@@ -168,5 +335,8 @@ function spawnArgs(
     env,
     detached,
     stdio,
+    // A detached Windows child gets its own console window unless hidden; these
+    // tasks write to log files and must not flash terminals.
+    windowsHide: process.platform === "win32",
   });
-}
+}

package/src/runtime.ts

@@ -490,7 +490,13 @@ export async function stopTask(
     try {
       stopProcessGroup(meta.pid, meta.pgid);
     } catch (error) {
+      meta.stopRequestedAt = undefined;
       meta.error = error instanceof Error ? error.message : String(error);
+      writeMeta(meta);
+      if (meta.deadlineAt && meta.deadlineAt > Date.now()) {
+        scheduleProcessTimeout(pi, id, meta.deadlineAt, getActiveSession);
+      }
+      return meta;
     }
   }
 
@@ -726,7 +732,14 @@ async function finalizeProcessTimeout(
     }
   } else {
     if (meta.pid) {
-      try { stopProcessGroup(meta.pid, meta.pgid); } catch { /* best effort */ }
+      try {
+        stopProcessGroup(meta.pid, meta.pgid);
+      } catch (error) {
+        reason = `timeout; could not terminate local process tree: ${readableError(error)}`;
+        meta.error = reason;
+        writeMeta(meta);
+        return;
+      }
     }
     if (meta.remote?.session === "direct") {
       reason = "timeout; terminated local SSH client, but the remote process may still be running";

package/src/sandbox.ts

@@ -12,10 +12,10 @@
  *    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.
+ * 2. **Opt-in, then fail closed.** `inactive` and explicitly `disabled` states
+ *    launch unconfined. Once foreground policy says confinement applies, a
+ *    missing or unusable backend blocks the launch and is never retried
+ *    unconfined behind the operator's back.
  *
  * The contract is duplicated here rather than imported: `pi-better-sandbox` is
  * an optional peer that this package must keep working without. Two channel
@@ -53,12 +53,13 @@ export const FOREGROUND_SANDBOX_POLICY_REQUEST_CHANNEL = "pi-better-sandbox:poli
 /**
  * What the foreground sandbox is doing right now.
  *
+ * - `inactive`    - default-off foreground policy; launch tasks as before.
  * - `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";
+export type ForegroundSandboxState = "inactive" | "enabled" | "disabled" | "unavailable" | "failed";
 
 /** The published snapshot, narrowed to the fields a task launch needs. */
 export interface ForegroundSandboxPolicy {
@@ -101,7 +102,7 @@ export type ForegroundSandboxPlan =
 
 const UNCONFINED: ForegroundSandboxPlan = { confined: false };
 
-const VALID_STATES = new Set<string>(["enabled", "disabled", "unavailable", "failed"]);
+const VALID_STATES = new Set<string>(["inactive", "enabled", "disabled", "unavailable", "failed"]);
 
 /**
  * The latest snapshot per event bus.
@@ -183,8 +184,8 @@ export function currentForegroundSandboxPolicy(pi: unknown): ForegroundSandboxPo
  * 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.
+ * Throws for every state that is neither confinable nor intentionally
+ * unconfined, which keeps a blocked launch from leaving task state behind.
  */
 export function resolveForegroundSandboxPlan(pi: unknown): ForegroundSandboxPlan {
   return planFor(currentForegroundSandboxPolicy(pi));
@@ -195,7 +196,7 @@ export function planFor(policy: ForegroundSandboxPolicy | undefined): Foreground
   // 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 === "inactive" || policy.state === "disabled") return UNCONFINED;
   if (policy.state !== "enabled" || !policy.writableRoot) {
     throw new ForegroundSandboxBlockedError(policy);
   }

package/src/shared-navigator.ts

@@ -152,7 +152,12 @@ export function unregisterBackgroundWorkProvider(id: string): void {
 }
 
 export function isNavigatorUiAvailable(ctx: ExtensionContext | undefined): boolean {
-  return Boolean(ctx && ctx.mode === "tui" && ctx.hasUI === true && ctx.ui);
+  if (!ctx) return false;
+  try {
+    return Boolean(ctx.mode === "tui" && ctx.hasUI === true && ctx.ui);
+  } catch {
+    return false;
+  }
 }
 
 export function navigatorFooterHint(count: number): string | null {
@@ -191,8 +196,10 @@ export function disposeBackgroundWorkNavigator(ctx?: ExtensionContext): void {
   try { s.dispose?.(); } catch { /* ignore */ }
   s.dispose = undefined;
   stopMainListWidget();
-  const ui = (ctx ?? s.uiCtx)?.ui;
-  if (ui && isNavigatorUiAvailable(ctx ?? s.uiCtx)) {
+  const activeCtx = ctx ?? s.uiCtx;
+  s.uiCtx = undefined;
+  if (activeCtx && isNavigatorUiAvailable(activeCtx)) {
+    const ui = activeCtx.ui;
     try { applyNavigatorFooter(ui as any, 0); } catch { /* ignore */ }
     try { applyCloseConfirmFooter(ui as any, null); } catch { /* ignore */ }
     try { (ui as any).setWidget?.(MAIN_LIST_WIDGET_KEY, undefined); } catch { /* ignore */ }
@@ -207,7 +214,6 @@ export function disposeBackgroundWorkNavigator(ctx?: ExtensionContext): void {
   s.detailOverlayRows = undefined;
   s.mainListSelectedId = undefined;
   s.mainListFocused = false;
-  if (ctx && s.uiCtx === ctx) s.uiCtx = undefined;
 }
 
 export function refreshBackgroundWorkNavigator(ctx?: ExtensionContext): void {