pi-better-background-tasks 0.1.0

package/README.md

@@ -0,0 +1,65 @@
+# pi-better-background-tasks
+
+Generic durable background tasks for [pi](https://pi.dev). The extension lets an
+agent start long-running commands or command-based watchers without blocking the
+foreground turn. Task metadata and logs are stored under the OS temp directory,
+so status and logs remain available across `/reload` and ordinary session use.
+
+The core is deliberately domain-neutral. GitHub, Mergify, Cloud Build, Vercel,
+and similar integrations should be thin presets on top of the generic watcher,
+not special cases in the runtime.
+
+## Tools
+
+| Tool | Purpose |
+| ---- | ------- |
+| `bg_task_spawn` | Start a long-running process and return immediately. |
+| `bg_task_watch` | Poll a command until success/failure/timeout. |
+| `bg_task_list` | List known tasks. |
+| `bg_task_status` | Inspect one task. Compact by default; pass `verbose:true` for full metadata JSON. |
+| `bg_task_log` | Read a bounded task log tail by default, or a full log on request. |
+| `bg_task_stop` | Cancel a watcher or terminate a process task. |
+| `bg_task` | Action-based wrapper for `spawn`, `watch`, `list`, `status`, `log`, `stop`, `clear`. |
+| `bg_status` | Small action wrapper for `list`, `status`, `log`, `stop`, `clear`. |
+
+`clear` dismisses terminal tasks for the active cwd/session so they no longer
+count as foreground attention. It keeps metadata and logs on disk for explicit
+inspection.
+
+Callbacks are terminal-only by default. When `callback` is not false, a task that
+reaches a terminal state queues one follow-up message telling the foreground
+agent which task finished and which tool to call for details.
+
+Callbacks point to `bg_task_status` first. The default status response is a
+compact model-facing summary that omits large command bodies; use
+`verbose:true` only when full metadata is required. `bg_task_log` defaults to a
+20-line tail, and `tail_lines: 0` requests the full log explicitly.
+
+Command watchers default to a 15 minute timeout when `timeout_seconds` is
+omitted. Pass `timeout_seconds: 0` to disable the watcher timeout explicitly.
+Spawned processes do not get a default timeout.
+
+## Examples
+
+```json
+{
+  "name": "dev server",
+  "command": "npm run dev",
+  "cwd": "/path/to/app"
+}
+```
+
+```json
+{
+  "name": "wait for success",
+  "command": "node ./scripts/check-status.js --json",
+  "interval_seconds": 15,
+  "timeout_seconds": 600,
+  "success_when": { "type": "json_path_equals", "path": "$.status", "value": "done" },
+  "failure_when": { "type": "json_path_equals", "path": "$.status", "value": "failed" }
+}
+```
+
+Commands run through `/bin/bash -lc` by default so shell-mode watchers behave
+consistently across sessions. Set `PI_BETTER_BACKGROUND_TASKS_SHELL` to override
+that shell, or pass `argv` and `shell:false` to avoid shell parsing.

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "pi-better-background-tasks",
+  "version": "0.1.0",
+  "description": "Generic durable background task and watcher tools for pi.",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "background-tasks"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/1aboveio/pi-better-harness.git",
+    "directory": "packages/pi-better-background-tasks"
+  },
+  "bugs": {
+    "url": "https://github.com/1aboveio/pi-better-harness/issues"
+  },
+  "homepage": "https://github.com/1aboveio/pi-better-harness/tree/main/packages/pi-better-background-tasks#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "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"
+  },
+  "files": [
+    "src/**/*.ts",
+    "!src/**/*.test.ts",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0",
+    "typebox": "^1.1.38"
+  }
+}

package/src/conditions.ts

@@ -0,0 +1,92 @@
+import type { CommandResult, Condition } from "./types.js";
+
+export interface ConditionMatch {
+  matched: boolean;
+  value?: unknown;
+  error?: string;
+}
+
+export function evaluateCondition(condition: Condition, result: CommandResult): ConditionMatch {
+  switch (condition.type) {
+    case "exit_code":
+      return { matched: result.exitCode === condition.equals, value: result.exitCode };
+    case "stdout_contains":
+      return { matched: result.stdout.includes(condition.value) };
+    case "stderr_contains":
+      return { matched: result.stderr.includes(condition.value) };
+    case "json_path_equals": {
+      const resolved = resolveJsonPath(result.stdout, condition.path);
+      if (!resolved.ok) return { matched: false, error: resolved.error };
+      return { matched: deepEqual(resolved.value, condition.value), value: resolved.value };
+    }
+    case "json_path_exists": {
+      const resolved = resolveJsonPath(result.stdout, condition.path);
+      return resolved.ok ? { matched: true, value: resolved.value } : { matched: false, error: resolved.error };
+    }
+  }
+}
+
+export function resolveJsonPath(jsonText: string, path: string): { ok: true; value: unknown } | { ok: false; error: string } {
+  let current: unknown;
+  try {
+    current = JSON.parse(jsonText);
+  } catch (error) {
+    return { ok: false, error: `stdout is not valid JSON: ${error instanceof Error ? error.message : String(error)}` };
+  }
+
+  const tokens = parseJsonPath(path);
+  if (!tokens) return { ok: false, error: `unsupported JSON path: ${path}` };
+
+  for (const token of tokens) {
+    if (typeof token === "number") {
+      if (!Array.isArray(current) || token < 0 || token >= current.length) {
+        return { ok: false, error: `JSON path not found: ${path}` };
+      }
+      current = current[token];
+      continue;
+    }
+    if (current === null || typeof current !== "object" || !(token in current)) {
+      return { ok: false, error: `JSON path not found: ${path}` };
+    }
+    current = (current as Record<string, unknown>)[token];
+  }
+
+  return { ok: true, value: current };
+}
+
+function parseJsonPath(path: string): Array<string | number> | undefined {
+  if (!path.startsWith("$")) return undefined;
+  const tokens: Array<string | number> = [];
+  let i = 1;
+  while (i < path.length) {
+    if (path[i] === ".") {
+      i += 1;
+      const start = i;
+      while (i < path.length && /[A-Za-z0-9_$-]/.test(path[i]!)) i += 1;
+      if (i === start) return undefined;
+      tokens.push(path.slice(start, i));
+      continue;
+    }
+    if (path[i] === "[") {
+      const end = path.indexOf("]", i);
+      if (end === -1) return undefined;
+      const raw = path.slice(i + 1, end).trim();
+      const quoted = raw.match(/^['\"](.+)['\"]$/);
+      if (quoted) {
+        tokens.push(quoted[1]!);
+      } else if (/^\d+$/.test(raw)) {
+        tokens.push(Number(raw));
+      } else {
+        return undefined;
+      }
+      i = end + 1;
+      continue;
+    }
+    return undefined;
+  }
+  return tokens;
+}
+
+function deepEqual(a: unknown, b: unknown): boolean {
+  return JSON.stringify(a) === JSON.stringify(b);
+}

package/src/goal-provider.ts

@@ -0,0 +1,116 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { listMetas } from "./registry.js";
+import type { BackgroundTaskMeta } from "./types.js";
+import { isTerminalStatus } from "./types.js";
+
+const GOAL_READY_EVENT = "pi-better-goal:ready";
+const GOAL_REGISTER_PROVIDER_EVENT = "pi-better-goal:register-provider";
+const readySubscriptions = new WeakSet<ExtensionAPI>();
+
+export interface GoalBackgroundWorkItem {
+  id: string;
+  label?: string;
+  status: string;
+  active: boolean;
+  unhealthy?: boolean;
+  terminal?: boolean;
+  attention?: boolean;
+  startedAt?: number;
+  endedAt?: number;
+  details?: Record<string, unknown>;
+}
+
+export interface GoalBackgroundProviderSnapshot {
+  providerId: string;
+  label?: string;
+  items: GoalBackgroundWorkItem[];
+}
+
+export function collectBackgroundTaskGoalActivity(
+  metas: BackgroundTaskMeta[] = listMetas(),
+  ctx?: ExtensionContext,
+  now = Date.now(),
+): GoalBackgroundProviderSnapshot {
+  return {
+    providerId: "background-tasks",
+    label: "Background Tasks",
+    items: metas
+      .filter((meta) => isVisibleGoalActivity(meta, ctx, now))
+      .map(backgroundTaskToGoalItem),
+  };
+}
+
+export function registerBackgroundTasksGoalProvider(pi: ExtensionAPI): void {
+  const emitProvider = (): void => {
+    pi.events?.emit(GOAL_REGISTER_PROVIDER_EVENT, {
+      id: "background-tasks",
+      label: "Background Tasks",
+      getActivity: (ctx: ExtensionContext) => collectBackgroundTaskGoalActivity(listMetas(), ctx),
+    });
+  };
+
+  if (!readySubscriptions.has(pi)) {
+    pi.events?.on?.(GOAL_READY_EVENT, emitProvider);
+    readySubscriptions.add(pi);
+  }
+  emitProvider();
+}
+
+const TERMINAL_GOAL_ACTIVITY_RETENTION_MS = 30_000;
+
+function isVisibleGoalActivity(meta: BackgroundTaskMeta, ctx: ExtensionContext | undefined, now: number): boolean {
+  if (meta.dismissedAt !== undefined) return false;
+  if (ctx && !belongsToGoalActivitySession(meta, ctx)) return false;
+  if (meta.status === "running") return true;
+  if (!ctx) return true;
+  if (typeof meta.endedAt !== "number") return true;
+  return now - meta.endedAt < TERMINAL_GOAL_ACTIVITY_RETENTION_MS;
+}
+
+function belongsToGoalActivitySession(meta: BackgroundTaskMeta, ctx: ExtensionContext): boolean {
+  const active = getGoalActivityOrigin(ctx);
+  const origin = meta.callbackOrigin;
+  if (origin) {
+    if (origin.cwd !== active.cwd) return false;
+    if (origin.sessionId || active.sessionId) return origin.sessionId === active.sessionId;
+    return true;
+  }
+  if (active.sessionId) return false;
+  return meta.cwd === active.cwd;
+}
+
+function getGoalActivityOrigin(ctx: ExtensionContext) {
+  let sessionId: string | undefined;
+  try {
+    sessionId = ctx.sessionManager?.getSessionId();
+  } catch {
+    sessionId = undefined;
+  }
+  return { cwd: ctx.cwd, sessionId };
+}
+
+function backgroundTaskToGoalItem(meta: BackgroundTaskMeta): GoalBackgroundWorkItem {
+  const active = meta.status === "running";
+  const terminal = isTerminalStatus(meta.status);
+  const attention = terminal && meta.status !== "succeeded";
+  const item: GoalBackgroundWorkItem = {
+    id: meta.id,
+    status: meta.status,
+    active,
+    terminal,
+    attention,
+    startedAt: meta.startedAt,
+    details: {
+      kind: meta.kind,
+      callback: meta.callback !== false,
+      cwd: meta.cwd,
+      command: meta.command,
+      argv: meta.argv,
+      logPath: meta.logPath,
+      spawnPid: meta.spawnPid,
+    },
+  };
+  if (meta.name !== undefined) item.label = meta.name;
+  if (meta.endedAt !== undefined) item.endedAt = meta.endedAt;
+  return item;
+}

package/src/index.ts

@@ -0,0 +1,23 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { disposeBackgroundWorkNavigator } from "../../navigator/index.ts";
+import { registerBackgroundTasksGoalProvider } from "./goal-provider.js";
+import { clearBackgroundTasksNavigatorSession, ensureBackgroundTasksNavigator, ensureBackgroundTasksNavigatorProvider } from "./navigator-provider.js";
+import { registerTools } from "./tools.js";
+
+export default function backgroundTasksExtension(pi: ExtensionAPI): void {
+  registerBackgroundTasksGoalProvider(pi);
+  ensureBackgroundTasksNavigatorProvider(pi);
+  pi.on("session_start", async (_event, ctx) => {
+    registerBackgroundTasksGoalProvider(pi);
+    ensureBackgroundTasksNavigator(ctx);
+  });
+  pi.on("session_before_switch", async () => {
+    clearBackgroundTasksNavigatorSession();
+    disposeBackgroundWorkNavigator();
+  });
+  pi.on("session_shutdown", async (_event, ctx) => {
+    clearBackgroundTasksNavigatorSession();
+    disposeBackgroundWorkNavigator(ctx);
+  });
+  registerTools(pi);
+}

package/src/logs.ts

@@ -0,0 +1,30 @@
+import { appendFileSync, readFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { mkdirSync } from "node:fs";
+import type { CommandResult } from "./types.js";
+
+export function appendWatchResult(logPath: string, result: CommandResult): void {
+  mkdirSync(dirname(logPath), { recursive: true });
+  const header = `\n--- check ${new Date(result.startedAt).toISOString()} exit=${result.exitCode ?? "null"} signal=${result.signal ?? "null"} duration_ms=${result.endedAt - result.startedAt} ---\n`;
+  appendFileSync(logPath, header);
+  if (result.stdout) appendFileSync(logPath, result.stdout.endsWith("\n") ? result.stdout : `${result.stdout}\n`);
+  if (result.stderr) appendFileSync(logPath, `[stderr]\n${result.stderr.endsWith("\n") ? result.stderr : `${result.stderr}\n`}`);
+}
+
+export function appendLine(logPath: string, line: string): void {
+  mkdirSync(dirname(logPath), { recursive: true });
+  appendFileSync(logPath, `${line}\n`);
+}
+
+export function readLog(logPath: string, tailLines?: number): { text: string; truncated: boolean } {
+  let text: string;
+  try {
+    text = readFileSync(logPath, "utf8");
+  } catch {
+    return { text: "", truncated: false };
+  }
+  if (!tailLines || tailLines <= 0) return { text, truncated: false };
+  const lines = text.split(/\r?\n/);
+  if (lines.length <= tailLines) return { text, truncated: false };
+  return { text: lines.slice(-tailLines).join("\n"), truncated: true };
+}

package/src/navigator-provider.ts

@@ -0,0 +1,212 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+  ensureBackgroundWorkNavigator,
+  refreshBackgroundWorkNavigator,
+  registerBackgroundWorkProvider,
+  type BackgroundWorkDetail,
+  type BackgroundWorkProvider,
+  type BackgroundWorkRow,
+} from "../../navigator/index.ts";
+import { CustomEditor } from "@earendil-works/pi-coding-agent";
+import { Key, matchesKey, truncateToWidth } from "@earendil-works/pi-tui";
+import { readLog } from "./logs.js";
+import { listMetas, readMeta, writeMeta } from "./registry.js";
+import { stopTask } from "./runtime.js";
+import type { BackgroundTaskCallbackOrigin, BackgroundTaskMeta, BackgroundTaskStatus } from "./types.js";
+
+let unregister: (() => void) | undefined;
+let piRef: ExtensionAPI | undefined;
+let activeNavigatorOrigin: BackgroundTaskCallbackOrigin | undefined;
+const TERMINAL_NAVIGATOR_RETENTION_MS = 30_000;
+
+export function ensureBackgroundTasksNavigatorProvider(pi: ExtensionAPI): void {
+  piRef = pi;
+  if (unregister) return;
+  unregister = registerBackgroundWorkProvider(provider);
+}
+
+export function ensureBackgroundTasksNavigator(ctx: ExtensionContext): void {
+  activeNavigatorOrigin = getNavigatorOrigin(ctx);
+  ensureBackgroundWorkNavigator(ctx, {
+    createDefaultEditor: (tui, theme, keybindings) => new CustomEditor(tui as never, theme as never, keybindings as never),
+    isOpenTrigger: (data) => matchesKey(data, Key.left),
+    matchKey: (data, keyId) => matchesKey(data, keyId as Parameters<typeof matchesKey>[1]),
+    truncate: truncateToWidth,
+  });
+}
+
+export function clearBackgroundTasksNavigatorSession(): void {
+  activeNavigatorOrigin = undefined;
+}
+
+export function refreshBackgroundTasksNavigator(ctx?: ExtensionContext): void {
+  refreshBackgroundWorkNavigator(ctx);
+}
+
+const provider: BackgroundWorkProvider = {
+  id: "background-tasks",
+  label: "Background Tasks",
+  priority: 20,
+  visibleCount: () => visibleMetas(Date.now()).filter((meta) => meta.status === "running").length,
+  listRows: (now) => visibleMetas(now).map((meta) => rowFromMeta(meta, now)),
+  detail: (id, now, options) => detailFromMeta(readMeta(id), now, options),
+  armCloseLabel: (row) => row.status === "running" ? "x again to stop" : "x again to dismiss",
+  close: (id) => {
+    const meta = readMeta(id);
+    if (!meta) return { action: "missing", providerId: "background-tasks", id };
+    if (meta.status === "running") {
+      const stopped = stopTask(piRef as ExtensionAPI, id);
+      return { action: "stopped", providerId: "background-tasks", id, status: stopped?.status };
+    }
+    meta.dismissedAt = Date.now();
+    writeMeta(meta);
+    return { action: "dismissed", providerId: "background-tasks", id, status: meta.status };
+  },
+};
+
+function visibleMetas(now = Date.now()): BackgroundTaskMeta[] {
+  return listMetas().filter((meta) => meta.dismissedAt === undefined && belongsToActiveNavigatorSession(meta) && !isExpiredTerminalNavigatorRow(meta, now));
+}
+
+function getNavigatorOrigin(ctx: ExtensionContext): BackgroundTaskCallbackOrigin {
+  let sessionId: string | undefined;
+  try {
+    sessionId = ctx.sessionManager?.getSessionId();
+  } catch {
+    sessionId = undefined;
+  }
+  return { cwd: ctx.cwd, sessionId };
+}
+
+function belongsToActiveNavigatorSession(meta: BackgroundTaskMeta): boolean {
+  const active = activeNavigatorOrigin;
+  if (!active) return false;
+  const origin = meta.callbackOrigin;
+  if (origin) {
+    if (origin.cwd !== active.cwd) return false;
+    if (origin.sessionId || active.sessionId) return origin.sessionId === active.sessionId;
+    return true;
+  }
+  if (active.sessionId) return false;
+  return meta.cwd === active.cwd;
+}
+
+function isExpiredTerminalNavigatorRow(meta: BackgroundTaskMeta, now: number): boolean {
+  if (meta.status === "running") return false;
+  const endedAt = meta.endedAt;
+  return typeof endedAt === "number" && now - endedAt >= TERMINAL_NAVIGATOR_RETENTION_MS;
+}
+
+function rowFromMeta(meta: BackgroundTaskMeta, now: number): BackgroundWorkRow {
+  const elapsed = formatDuration((meta.endedAt ?? now) - meta.startedAt);
+  return {
+    providerId: "background-tasks",
+    id: meta.id,
+    name: meta.name,
+    status: meta.status,
+    statusTone: toneForStatus(meta.status),
+    kind: meta.kind === "command_watch" ? "watch" : "process",
+    elapsed,
+    primary: compactCommandLabel(meta),
+    command: commandLabel(meta),
+    tool: compactCommandLabel(meta),
+    secondary: secondaryLabel(meta),
+    facts: factsForMeta(meta, now),
+    sortStartedAt: meta.startedAt,
+  };
+}
+
+function detailFromMeta(meta: BackgroundTaskMeta | undefined, now: number, options?: { logTailLines?: number }): BackgroundWorkDetail | null {
+  if (!meta) return null;
+  const log = readLog(meta.logPath, options?.logTailLines ?? 10);
+  const command = commandLabel(meta);
+  const metadata = [
+    { label: "provider", value: "Background Tasks" },
+    { label: "kind", value: meta.kind === "command_watch" ? "watch" : "process" },
+    { label: "elapsed", value: formatDuration((meta.endedAt ?? now) - meta.startedAt) },
+    { label: "cwd", value: meta.cwd },
+    { label: "pid", value: meta.pid != null ? String(meta.pid) : "-" },
+    { label: "pgid", value: meta.pgid != null ? String(meta.pgid) : "-" },
+    { label: "log", value: meta.logPath },
+  ];
+  if (meta.deadlineAt) metadata.push({ label: "deadline", value: formatDuration(meta.deadlineAt - now) });
+  if (meta.lastCheckedAt) metadata.push({ label: "checked", value: `${formatDuration(now - meta.lastCheckedAt)} ago` });
+  if (meta.lastExitCode !== undefined) metadata.push({ label: "exit", value: String(meta.lastExitCode) });
+  if (meta.error) metadata.push({ label: "error", value: meta.error });
+  return {
+    providerId: "background-tasks",
+    id: meta.id,
+    title: meta.name || meta.id,
+    status: meta.status,
+    statusTone: toneForStatus(meta.status),
+    subtitle: compactCommandLabel(meta),
+    metadata,
+    foldedSections: [{
+      id: "command",
+      label: "command",
+      text: command,
+      collapsedText: compactCommandLabel(meta),
+    }],
+    evidence: {
+      label: log.truncated ? "log tail" : "log",
+      text: log.text || "(log is empty)",
+    },
+    footerActions: [meta.status === "running" ? "x stop" : "x dismiss"],
+  };
+}
+
+function toneForStatus(status: BackgroundTaskStatus): BackgroundWorkRow["statusTone"] {
+  switch (status) {
+    case "running": return "running";
+    case "succeeded": return "success";
+    case "failed":
+    case "timed_out": return "failed";
+    case "cancelled": return "warning";
+    default: return "muted";
+  }
+}
+
+function commandLabel(meta: BackgroundTaskMeta): string {
+  if (meta.command) return meta.command;
+  if (meta.argv?.length) return meta.argv.join(" ");
+  return "(no command recorded)";
+}
+
+function compactCommandLabel(meta: BackgroundTaskMeta): string {
+  const value = commandLabel(meta).trim();
+  const parts = value.split(/\s+/).filter(Boolean);
+  if (parts.length <= 3) return value;
+  return parts.slice(0, 3).join(" ");
+}
+
+function secondaryLabel(meta: BackgroundTaskMeta): string | undefined {
+  const parts = [];
+  if (meta.cwd) parts.push(meta.cwd);
+  if (meta.pid != null) parts.push(`pid ${meta.pid}`);
+  if (meta.lastExitCode !== undefined) parts.push(`exit ${meta.lastExitCode}`);
+  return parts.length ? parts.join(" · ") : undefined;
+}
+
+function factsForMeta(meta: BackgroundTaskMeta, now: number): string[] {
+  const facts: string[] = [];
+  if (meta.kind === "command_watch" && meta.intervalMs) facts.push(`every ${formatDuration(meta.intervalMs)}`);
+  if (meta.deadlineAt && meta.status === "running") facts.push(`${formatDuration(meta.deadlineAt - now)} left`);
+  if (meta.result && meta.status !== "running") {
+    const reason = typeof meta.result === "object" && meta.result && "reason" in meta.result
+      ? String((meta.result as { reason?: unknown }).reason)
+      : "result";
+    facts.push(reason);
+  }
+  return facts.slice(0, 2);
+}
+
+function formatDuration(ms: number): string {
+  const seconds = Math.max(0, Math.round(ms / 1000));
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.floor(seconds / 60);
+  const rest = seconds % 60;
+  if (minutes < 60) return `${minutes}m ${rest.toString().padStart(2, "0")}s`;
+  const hours = Math.floor(minutes / 60);
+  const min = minutes % 60;
+  return `${hours}h ${min.toString().padStart(2, "0")}m`;
+}

package/src/process.ts

@@ -0,0 +1,99 @@
+import { spawn } from "node:child_process";
+import { appendFileSync, closeSync, mkdirSync, openSync, writeSync } from "node:fs";
+import { dirname } 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";
+
+export interface SpawnedProcess {
+  child: ChildProcess;
+  pgid?: number;
+}
+
+export function validateCommandSpec(spec: CommandSpec): void {
+  if (spec.shell === false) {
+    if (!spec.argv || spec.argv.length === 0 || !spec.argv[0]) {
+      throw new Error("argv with at least one element is required when shell:false");
+    }
+    return;
+  }
+  if (!spec.command || spec.command.trim().length === 0) {
+    throw new Error("command is required unless shell:false with argv is provided");
+  }
+}
+
+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);
+  child.on("close", (code, signal) => {
+    appendFileSync(logPath, `\n--- exit ${new Date().toISOString()} code=${code ?? "null"} signal=${signal ?? "null"} ---\n`);
+  });
+  return { child, pgid: detached && child.pid ? child.pid : undefined };
+}
+
+export function runCommandOnce(spec: CommandSpec, maxBufferBytes = 1024 * 1024): Promise<CommandResult> {
+  validateCommandSpec(spec);
+  const startedAt = Date.now();
+  const child = spawnArgs(spec, false, ["ignore", "pipe", "pipe"]);
+  let stdout = "";
+  let stderr = "";
+  child.stdout?.on("data", (chunk: Buffer) => {
+    if (Buffer.byteLength(stdout) < maxBufferBytes) stdout += chunk.toString("utf8");
+  });
+  child.stderr?.on("data", (chunk: Buffer) => {
+    if (Buffer.byteLength(stderr) < maxBufferBytes) stderr += chunk.toString("utf8");
+  });
+  return new Promise((resolve, reject) => {
+    child.on("error", reject);
+    child.on("close", (exitCode, signal) => {
+      resolve({ exitCode, signal, stdout, stderr, startedAt, endedAt: Date.now() });
+    });
+  });
+}
+
+export function stopProcessGroup(pid: number, pgid?: number): void {
+  const target = pgid ?? pid;
+  try {
+    process.kill(-target, "SIGTERM");
+    return;
+  } catch {
+    process.kill(pid, "SIGTERM");
+  }
+}
+
+export function processExists(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+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!], {
+    cwd: spec.cwd,
+    env,
+    detached,
+    stdio,
+  });
+}