@pify/shell-background 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pifydev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,65 @@
+# @pify/shell-background
+
+[![CI](https://github.com/pifydev/shell-background/actions/workflows/ci.yml/badge.svg)](https://github.com/pifydev/shell-background/actions/workflows/ci.yml) [![npm version](https://img.shields.io/npm/v/@pify/shell-background)](https://www.npmjs.com/package/@pify/shell-background) [![npm downloads](https://img.shields.io/npm/dm/@pify/shell-background)](https://www.npmjs.com/package/@pify/shell-background)
+
+Long-running bash goes async in [pi](https://github.com/earendil-works/pi). Pass `background: true` to launch a command detached and get its id back immediately — and any foreground command still running after 30 seconds is **automatically moved to the background**, so a build, a test run, or a dev server never eats the agent's turn while it waits.
+
+Part of the [Pify suite](https://github.com/pifydev). Install with [`pify install shell-background`](https://github.com/pifydev/cli) or `pi install npm:@pify/shell-background`.
+
+## Why
+
+pi's bash tool waits for the command to finish. That is right for `ls` and wrong for `npm run build`: the agent sits blocked for a minute with nothing to do, and a `npm run dev` that never exits blocks it forever. The fix is to let a long command keep running in the background while the agent gets on with something else, and to hand back the result when it lands.
+
+## What it does
+
+It re-registers the `bash` tool with the same shell, working directory and environment — nothing about how a command runs changes — but a different lifecycle:
+
+| Situation | What happens |
+|---|---|
+| Command finishes quickly | Returns normally, exactly like before. |
+| Command still running after 30s | Moved to the background: the tool returns `moved to background, id=bg-1`, and the result is delivered into the conversation when the command finishes. |
+| `background: true` | Launched detached from the start; returns the id immediately. |
+| `timeout: N` | Killed (whole process tree) if it runs past N seconds. |
+
+```
+bash { command: "npm run build" }        # returns when done, or auto-backgrounds at 30s
+bash { command: "npm run dev", background: true }   # → "bg-2 started in the background"
+shell_status { id: "bg-2" }              # status + output so far
+shell_status                             # list every background command this session
+shell_kill { id: "bg-2" }                # stop it and its whole process tree
+```
+
+`/shell-bg` lists the jobs; `/shell-bg kill bg-2` stops one.
+
+## Delivery, and the headless caveat
+
+When a backgrounded command finishes in an **interactive** session, its result is pushed into the conversation as the next turn — you do not have to poll. Under headless `pi -p` there is nothing to deliver into (the session tears down when the prompt resolves), so **auto-background is disabled there** and only explicit `background: true` applies; collect it with `shell_status` inside the same turn. This is the same delivery rule the rest of the suite lives by.
+
+## How it works
+
+Each command is spawned with its stdout and stderr piped into a single log file, drained on every chunk so nothing is lost no matter how much it prints, and finalized only after the pipes end (with a short grace so a daemonized grandchild that holds a handle open cannot truncate the tail). The process is spawned detached (POSIX) and `unref`'d so a running job never holds the host open, and killed as a whole process tree — `taskkill /T` on Windows, a process-group signal on POSIX — on timeout, abort, `shell_kill`, or session shutdown.
+
+Shell resolution reuses pi's own `getShellConfig` (Git Bash on Windows, `/bin/bash` then `sh` on Unix), so a backgrounded command behaves identically to a foreground one. Jobs are tracked in memory and mirrored to a per-session sidecar under the temp dir, so `shell_status` still answers after a `/reload` and a job whose process has died is reconciled rather than shown as forever-running.
+
+There are **no runtime dependencies**, and it works on Linux, macOS and Windows.
+
+## Settings
+
+Put these in `.pi/shell-background.json` (project) or `<agentDir>/shell-background.json` (global):
+
+```json
+{
+  "autoBackgroundMs": 30000,
+  "tailBytes": 65536
+}
+```
+
+`autoBackgroundMs` is how long a foreground command may run before it auto-backgrounds; set it to `0` to disable auto-background (explicit `background: true` still works). `PIFY_SHELL_BG_MS` overrides it for one run or in CI. `tailBytes` bounds how much of a job's log a status result shows. Bad values fall back to the defaults with a warning rather than taking the tool down.
+
+## Coexistence
+
+This package owns the `bash` tool's execution. If you also run another extension that re-registers `bash` (a renderer like `@pify/pretty`, say), whichever loads last wins — install order decides. `@pify/pretty` only changes rendering and leaves execution alone, so the usual advice is to let this package load after it.
+
+## License
+
+MIT © [Pify maintainers](https://github.com/pifydev)

package/extensions/shell-background.ts

@@ -0,0 +1,380 @@
+/**
+ * @pify/shell-background — long-running bash goes async.
+ *
+ * Re-registers pi's `bash` tool with the same shell, cwd and env, but a
+ * different lifecycle:
+ *
+ *   - a command's stdout+stderr are written straight to a log file via
+ *     inherited file descriptors (no pipes, so no drain deadlock and no lost
+ *     output at any volume), the process is spawned detached and unref'd so it
+ *     survives the tool returning;
+ *   - a foreground command that is still running after the auto-background
+ *     threshold (default 30s, interactive sessions only) is moved to the
+ *     background: the tool returns "moved to background, id=…" and the result is
+ *     delivered into the conversation when the command finishes;
+ *   - `background: true` launches detached from the start and returns the id
+ *     immediately.
+ *
+ * `shell_status` polls or collects a job (and lists them all); `shell_kill`
+ * terminates one and its whole process tree. Delivery reuses the suite's
+ * pending pattern and its one hard rule: it only works in a session that
+ * outlives the run, so auto-background is off under headless `pi -p` (explicit
+ * background still works, collected with shell_status inside the turn).
+ *
+ * pi has no native background bash — every command is awaited to completion —
+ * so the spawn is our own, reusing pi's shell resolution (getShellConfig) for
+ * byte-identical shell behaviour. Zero runtime dependencies.
+ */
+import {
+  createBashToolDefinition,
+  getAgentDir,
+  getShellConfig,
+  type ExtensionAPI,
+  type ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+
+import { JobRegistry } from "../src/registry.ts";
+import { spawnToFile } from "../src/spawn.ts";
+import { killTree } from "../src/kill.ts";
+import { readTail } from "../src/tail.ts";
+import { DEFAULT_SETTINGS, resolveSettings, type ShellBgSettings } from "../src/config.ts";
+import { backgroundedResult, deliveryMessage, DELIVERY_TYPE } from "../src/pending.ts";
+import { formatResult, formatList, header } from "../src/format.ts";
+import { buildWidgetLines } from "../src/widget.ts";
+import type { Job } from "../src/types.ts";
+
+type UiContext = ExtensionContext;
+type AnyTool = { name: string; execute: (...a: never[]) => unknown; [k: string]: unknown };
+type ToolResult = { content: Array<{ type: "text"; text: string }>; details: Record<string, unknown>; isError?: boolean };
+
+const WIDGET = "shell-bg";
+
+export default function shellBackground(pi: ExtensionAPI) {
+  let settings: ShellBgSettings = DEFAULT_SETTINGS;
+  let registry: JobRegistry | null = null;
+  let lastUiCtx: UiContext | null = null;
+
+  // ── setup ──────────────────────────────────────────────────────────
+
+  function sessionKey(cwd: string): string {
+    const id = process.env.PI_SESSION_ID;
+    if (id) return id.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 40);
+    return createHash("sha256").update(cwd).digest("hex").slice(0, 16);
+  }
+
+  function loadSettings(cwd: string): string[] {
+    for (const file of [join(cwd, ".pi", "shell-background.json"), join(getAgentDir(), "shell-background.json")]) {
+      let raw: string;
+      try {
+        raw = readFileSync(file, "utf8");
+      } catch {
+        continue;
+      }
+      try {
+        const parsed = resolveSettings(JSON.parse(raw));
+        settings = parsed.settings;
+        return parsed.warnings;
+      } catch (err) {
+        settings = DEFAULT_SETTINGS;
+        return [`${file}: ${err instanceof Error ? err.message : String(err)}`];
+      }
+    }
+    const parsed = resolveSettings(undefined);
+    settings = parsed.settings;
+    return parsed.warnings;
+  }
+
+  /** Shell + args, reusing pi's resolution; command rides in argv (not stdin). */
+  function shellArgv(): { shell: string; args: string[] } {
+    const cfg = getShellConfig();
+    // Our stdio has stdin ignored, so a stdin command transport (legacy WSL)
+    // cannot receive the command — fall back to -c, which every bash accepts.
+    const args = cfg.commandTransport === "stdin" ? ["-c"] : [...cfg.args];
+    return { shell: cfg.shell, args };
+  }
+
+  function renderWidget(ctx: UiContext | null = lastUiCtx): void {
+    if (!ctx || !ctx.hasUI || !registry) return;
+    lastUiCtx = ctx;
+    const now = Date.now();
+    const lines = buildWidgetLines(registry.all(), ctx.ui.theme as never, now);
+    if (lines.length === 0) {
+      ctx.ui.setWidget(WIDGET, undefined);
+      return;
+    }
+    ctx.ui.setWidget(WIDGET, (_tui: unknown) => new Text(lines.join("\n"), 0, 0), { placement: "aboveEditor" });
+  }
+
+  // ── run ────────────────────────────────────────────────────────────
+
+  function snapshot(job: Job): ToolResult {
+    const tail = readTail(job.logPath, settings.tailBytes);
+    return {
+      content: [{ type: "text", text: `${header(job)}\n${tail.text.replace(/\n+$/, "") || "(no output yet)"}` }],
+      details: { id: job.id, status: job.status },
+    };
+  }
+
+  function finished(job: Job): ToolResult {
+    return {
+      content: [{ type: "text", text: formatResult(job, settings.tailBytes) }],
+      details: { id: job.id, status: job.status, exitCode: job.exitCode, signal: job.signal, background: false },
+      isError: job.status === "failed",
+    };
+  }
+
+  /** Deliver a finished background job into the conversation, once. */
+  function scheduleDelivery(job: Job, exit: Promise<unknown>): void {
+    exit
+      .then(() => {
+        if (job.delivered) return;
+        job.delivered = true;
+        registry?.persist(job);
+        renderWidget();
+        pi.sendMessage(
+          {
+            customType: DELIVERY_TYPE,
+            content: deliveryMessage(job.id, formatResult(job, settings.tailBytes)),
+            display: true,
+            details: { id: job.id, status: job.status, exitCode: job.exitCode },
+          },
+          { deliverAs: "followUp", triggerTurn: true },
+        );
+      })
+      .catch(() => {
+        // A /reload can make captured handles throw; delivery is a convenience,
+        // shell_status still collects the result.
+      });
+  }
+
+  async function runBash(
+    params: { command: string; timeout?: number; background?: boolean },
+    signal: AbortSignal | undefined,
+    onUpdate: ((r: ToolResult) => void) | undefined,
+    ctx: UiContext,
+  ): Promise<ToolResult> {
+    lastUiCtx = ctx;
+    if (!registry) throw new Error("shell-background not initialized");
+    const command = String(params.command ?? "").trim();
+    if (!command) return { content: [{ type: "text", text: "Empty command." }], details: {}, isError: true };
+
+    const job = registry.create(command, ctx.cwd);
+    const { shell, args } = shellArgv();
+
+    let spawned;
+    try {
+      spawned = spawnToFile(shell, args, command, ctx.cwd, process.env, job.logPath);
+    } catch (err) {
+      job.status = "failed";
+      job.endedAt = Date.now();
+      registry.persist(job);
+      return { content: [{ type: "text", text: `Failed to start: ${err instanceof Error ? err.message : String(err)}` }], details: {}, isError: true };
+    }
+    job.pid = spawned.pid;
+    registry.persist(job);
+    renderWidget(ctx);
+
+    // Settle the job record the moment the process ends, whatever else happens.
+    const settle = spawned.exit.then(({ code, signal: sig }) => {
+      if (job.status === "running") {
+        job.status = job.killedByUs ? "killed" : sig ? "killed" : code === 0 ? "done" : "failed";
+      }
+      job.exitCode = code;
+      job.signal = sig;
+      job.endedAt = Date.now();
+      registry?.persist(job);
+      renderWidget();
+    });
+
+    if (params.background) {
+      scheduleDelivery(job, settle);
+      const r = backgroundedResult({
+        id: job.id,
+        command,
+        elapsedMs: 0,
+        auto: false,
+        interactive: ctx.hasUI,
+        collectWith: "shell_status",
+      });
+      return { content: [{ type: "text", text: r.text }], details: r.details };
+    }
+
+    // Foreground: race the process against the auto-background threshold, an
+    // optional timeout, and the turn's abort signal — streaming the tail.
+    const autoMs = ctx.hasUI ? settings.autoBackgroundMs : 0;
+    const timers: NodeJS.Timeout[] = [];
+    const after = (ms: number, val: string) =>
+      new Promise<string>((res) => {
+        const t = setTimeout(() => res(val), ms);
+        t.unref?.();
+        timers.push(t);
+      });
+    const tick = setInterval(() => onUpdate?.(snapshot(job)), 1000);
+    tick.unref?.();
+
+    const abort = new Promise<string>((res) => {
+      if (!signal) return;
+      if (signal.aborted) res("abort");
+      else signal.addEventListener("abort", () => res("abort"), { once: true });
+    });
+
+    try {
+      const race: Array<Promise<string>> = [settle.then(() => "exit")];
+      if (autoMs > 0) race.push(after(autoMs, "auto"));
+      if (params.timeout && params.timeout > 0) race.push(after(params.timeout * 1000, "timeout"));
+      if (signal) race.push(abort);
+
+      const outcome = await Promise.race(race);
+
+      if (outcome === "exit") return finished(job);
+
+      if (outcome === "auto") {
+        scheduleDelivery(job, settle);
+        const r = backgroundedResult({
+          id: job.id,
+          command,
+          elapsedMs: Date.now() - job.startedAt,
+          auto: true,
+          interactive: ctx.hasUI,
+          collectWith: "shell_status",
+        });
+        return { content: [{ type: "text", text: r.text }], details: r.details };
+      }
+
+      // timeout or abort: stop the tree, let the record settle, report partial.
+      job.killedByUs = true;
+      killTree(job.pid);
+      await Promise.race([settle, after(500, "gave-up")]);
+      const note =
+        outcome === "timeout"
+          ? `\n\n[killed: exceeded the ${params.timeout}s timeout]`
+          : `\n\n[killed: the turn was aborted]`;
+      return {
+        content: [{ type: "text", text: formatResult(job, settings.tailBytes) + note }],
+        details: { id: job.id, status: job.status },
+        isError: true,
+      };
+    } finally {
+      timers.forEach(clearTimeout);
+      clearInterval(tick);
+    }
+  }
+
+  // ── tools & lifecycle ────────────────────────────────────────────────
+
+  function registerBash(cwd: string): void {
+    const original = createBashToolDefinition(cwd) as unknown as AnyTool;
+    const guidelines = [
+      ...(Array.isArray((original as { promptGuidelines?: unknown }).promptGuidelines)
+        ? ((original as { promptGuidelines?: string[] }).promptGuidelines as string[])
+        : []),
+      `A command still running after ${Math.round(settings.autoBackgroundMs / 1000)}s is moved to the background and its result is delivered when it finishes; pass background:true to background a long task (a server, build, or watcher) immediately. Collect or check with shell_status.`,
+    ];
+    pi.registerTool({
+      ...original,
+      parameters: Type.Object({
+        command: Type.String({ description: "Shell command to execute" }),
+        timeout: Type.Optional(
+          Type.Number({ description: "Timeout in seconds; a command that hits it is killed with its whole process tree." }),
+        ),
+        background: Type.Optional(
+          Type.Boolean({ description: "Launch detached and return an id immediately instead of waiting for the command to finish." }),
+        ),
+      }),
+      promptGuidelines: guidelines,
+      // Let pi render the result with its default text renderer; keep the call
+      // renderer (it only needs the command) if the original had one.
+      renderResult: undefined,
+      execute: async (_id: string, params: never, sig: never, upd: never, ctx: never) =>
+        runBash(params, sig as AbortSignal | undefined, upd as never, ctx as UiContext),
+    } as never);
+  }
+
+  pi.registerTool({
+    name: "shell_status",
+    label: "Background shell status",
+    promptSnippet: "Check or collect a backgrounded command",
+    description:
+      "Report a background command by id (its status and output tail), or list all this session's background commands when given no id. Finished results survive until the session ends.",
+    parameters: Type.Object({
+      id: Type.Optional(Type.String({ description: "Job id, e.g. bg-1. Omit to list all." })),
+    }),
+    async execute(_id: string, params: { id?: string }): Promise<ToolResult> {
+      if (!registry) return { content: [{ type: "text", text: "shell-background not initialized" }], details: {}, isError: true };
+      const id = params.id?.trim();
+      if (!id) return { content: [{ type: "text", text: formatList(registry.all()) }], details: {} };
+      const job = registry.get(id);
+      if (!job) {
+        const known = registry.all().map((j) => j.id).join(", ") || "(none)";
+        return { content: [{ type: "text", text: `No job "${id}". Known: ${known}` }], details: {}, isError: true };
+      }
+      // Reading marks it collected so it will not also be delivered unasked.
+      job.delivered = true;
+      return {
+        content: [{ type: "text", text: formatResult(job, settings.tailBytes) }],
+        details: { id: job.id, status: job.status, exitCode: job.exitCode },
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "shell_kill",
+    label: "Kill background shell",
+    promptSnippet: "Stop a backgrounded command",
+    description: "Terminate a background command and its whole process tree by id.",
+    parameters: Type.Object({ id: Type.String({ description: "Job id, e.g. bg-1" }) }),
+    async execute(_id: string, params: { id: string }): Promise<ToolResult> {
+      if (!registry) return { content: [{ type: "text", text: "shell-background not initialized" }], details: {}, isError: true };
+      const job = registry.get(params.id?.trim());
+      if (!job) return { content: [{ type: "text", text: `No job "${params.id}".` }], details: {}, isError: true };
+      if (job.status !== "running") {
+        return { content: [{ type: "text", text: `${job.id} already ${job.status}.` }], details: { id: job.id, status: job.status } };
+      }
+      job.killedByUs = true;
+      killTree(job.pid);
+      return { content: [{ type: "text", text: `Killing ${job.id} (pid ${job.pid ?? "?"}) and its process tree.` }], details: { id: job.id } };
+    },
+  });
+
+  pi.registerCommand("shell-bg", {
+    description: "Background shell jobs: /shell-bg [kill <id>]",
+    handler: async (args, ctx: UiContext) => {
+      if (!ctx.hasUI || !registry) return;
+      const [verb, id] = (args ?? "").trim().split(/\s+/);
+      if (verb === "kill" && id) {
+        const job = registry.get(id);
+        if (job && job.status === "running") {
+          job.killedByUs = true;
+          killTree(job.pid);
+          ctx.ui.notify(`Killing ${job.id}.`, "info");
+        } else {
+          ctx.ui.notify(job ? `${id} already ${job.status}.` : `No job "${id}".`, "warning");
+        }
+        return;
+      }
+      ctx.ui.notify(formatList(registry.all()), "info");
+    },
+  });
+
+  pi.on("session_start", async (_event, ctx) => {
+    const warnings = loadSettings(ctx.cwd);
+    registry = new JobRegistry(join(tmpdir(), "pify-shell-bg", sessionKey(ctx.cwd)));
+    registry.load();
+    registerBash(ctx.cwd);
+    renderWidget(ctx);
+    if (warnings.length > 0 && ctx.hasUI) ctx.ui.notify(`shell-background settings: ${warnings.join("; ")}`, "warning");
+  });
+
+  pi.on("session_shutdown", async (_event, ctx) => {
+    // Background jobs are tied to the session; do not leave orphans running
+    // after pi exits.
+    if (registry) for (const job of registry.running()) killTree(job.pid);
+    if (ctx.hasUI) ctx.ui.setWidget(WIDGET, undefined);
+  });
+}

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@pify/shell-background",
+  "version": "0.1.0",
+  "description": "Long-running bash goes async: background: true launches detached, and any command still running after 30s auto-backgrounds and delivers its result when it finishes",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "pify",
+    "bash",
+    "background",
+    "async",
+    "shell"
+  ],
+  "homepage": "https://github.com/pifydev/shell-background#readme",
+  "bugs": {
+    "url": "https://github.com/pifydev/shell-background/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pifydev/shell-background.git"
+  },
+  "license": "MIT",
+  "author": "Pify maintainers",
+  "type": "module",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "files": [
+    "extensions",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions/shell-background.ts"
+    ]
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "prepublishOnly": "npm run typecheck && npm test"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "^0.85.1",
+    "@earendil-works/pi-coding-agent": "^0.85.1",
+    "@earendil-works/pi-tui": "^0.85.1",
+    "@types/node": "^22.10.2",
+    "typebox": "^1.1.38",
+    "typescript": "^5.7.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/config.ts

@@ -0,0 +1,72 @@
+/**
+ * Settings for @pify/shell-background.
+ *
+ * The one number that is genuinely a matter of taste is the auto-background
+ * threshold: how long a foreground command may run before it is moved to the
+ * background so the agent gets its turn back. Read from `.pi/shell-background.json`
+ * (project) or `<agentDir>/shell-background.json` (global), with a PIFY_SHELL_BG_MS
+ * env override for one-off runs and CI. Bad values fall back to the default with
+ * a warning rather than taking the extension down.
+ */
+
+export interface ShellBgSettings {
+  /** Foreground ms before a command auto-backgrounds. 0 disables auto-background. */
+  autoBackgroundMs: number;
+  /** Bytes of the log tail shown in a status/collect result. */
+  tailBytes: number;
+}
+
+export const DEFAULT_SETTINGS: ShellBgSettings = {
+  autoBackgroundMs: 30_000,
+  tailBytes: 64 * 1024,
+};
+
+const LIMITS: Record<keyof ShellBgSettings, { min: number; max: number }> = {
+  // 0 is allowed (disable); otherwise at least 1s so a typo of "30" (=30ms)
+  // does not make every command look long-running.
+  autoBackgroundMs: { min: 0, max: 3_600_000 },
+  tailBytes: { min: 1024, max: 4 * 1024 * 1024 },
+};
+
+export function resolveSettings(
+  raw: unknown,
+  env: NodeJS.ProcessEnv = process.env,
+): { settings: ShellBgSettings; warnings: string[] } {
+  const settings: ShellBgSettings = { ...DEFAULT_SETTINGS };
+  const warnings: string[] = [];
+
+  if (raw !== undefined && raw !== null) {
+    if (typeof raw !== "object" || Array.isArray(raw)) {
+      warnings.push("settings file is not an object — ignored");
+    } else {
+      for (const [key, value] of Object.entries(raw as Record<string, unknown>)) {
+        if (!(key in DEFAULT_SETTINGS)) {
+          warnings.push(`unknown setting "${key}"`);
+          continue;
+        }
+        const name = key as keyof ShellBgSettings;
+        if (typeof value !== "number" || !Number.isFinite(value)) {
+          warnings.push(`"${key}" must be a number — using ${DEFAULT_SETTINGS[name]}`);
+          continue;
+        }
+        settings[name] = clamp(name, value, warnings);
+      }
+    }
+  }
+
+  const envMs = env.PIFY_SHELL_BG_MS;
+  if (envMs !== undefined && envMs !== "") {
+    const n = Number(envMs);
+    if (Number.isFinite(n)) settings.autoBackgroundMs = clamp("autoBackgroundMs", n, warnings);
+    else warnings.push(`PIFY_SHELL_BG_MS="${envMs}" is not a number — ignored`);
+  }
+
+  return { settings, warnings };
+}
+
+function clamp(name: keyof ShellBgSettings, value: number, warnings: string[]): number {
+  const { min, max } = LIMITS[name];
+  const c = Math.round(Math.min(max, Math.max(min, value)));
+  if (c !== value) warnings.push(`"${name}" clamped to ${c} (allowed ${min}–${max})`);
+  return c;
+}

package/src/format.ts

@@ -0,0 +1,63 @@
+/**
+ * Turning a job (and its log tail) into the text a tool returns. Pure: given a
+ * job and a tail, produce the string — the extension supplies both.
+ */
+import type { Job } from "./types.ts";
+import { readTail, countLines } from "./tail.ts";
+
+function secs(ms: number): string {
+  if (ms < 1000) return `${ms}ms`;
+  const s = ms / 1000;
+  return s < 60 ? `${s.toFixed(1)}s` : `${Math.floor(s / 60)}m ${Math.round(s % 60)}s`;
+}
+
+function duration(job: Job): string {
+  const end = job.endedAt ?? Date.now();
+  return secs(Math.max(0, end - job.startedAt));
+}
+
+/** `[bg-1 · done · exit 0 · 4.2s]` — the one-line header every result carries. */
+export function header(job: Job): string {
+  const verdict =
+    job.status === "running"
+      ? "running"
+      : job.signal
+        ? `signal ${job.signal}`
+        : job.status === "killed"
+          ? "killed"
+          : `exit ${job.exitCode ?? "?"}`;
+  return `[${job.id} · ${job.status} · ${verdict} · ${duration(job)}]`;
+}
+
+/**
+ * The full result of a finished (or polled) job: the header, then the tail of
+ * its output, with an honest note when output was truncated and where the whole
+ * log lives.
+ */
+export function formatResult(job: Job, tailBytes: number): string {
+  const tail = readTail(job.logPath, tailBytes);
+  const lines = [header(job)];
+  if (tail.text.trim() === "") {
+    lines.push(job.status === "running" ? "(no output yet)" : "(no output)");
+  } else {
+    if (tail.truncated) {
+      lines.push(`… showing the last ${countLines(tail.text)} lines — full log: ${job.logPath}`);
+    }
+    lines.push(tail.text.replace(/\n+$/, ""));
+  }
+  return lines.join("\n");
+}
+
+/** A roster of jobs for `shell_status` with no id. */
+export function formatList(jobs: Job[]): string {
+  if (jobs.length === 0) return "No background commands this session.";
+  const rows = jobs
+    .slice()
+    .sort((a, b) => b.startedAt - a.startedAt)
+    .map((j) => {
+      const cmd = j.command.replace(/\s+/g, " ").trim();
+      const short = cmd.length <= 48 ? cmd : `${cmd.slice(0, 47)}…`;
+      return `${header(j)}  ${short}`;
+    });
+  return [`${jobs.filter((j) => j.status === "running").length} running, ${jobs.length} total:`, ...rows].join("\n");
+}

package/src/kill.ts

@@ -0,0 +1,56 @@
+/**
+ * Kill a shell command and everything it spawned, on every platform.
+ *
+ * A `bash -c "…"` is a tree: the shell, and whatever it launched. Killing only
+ * the shell's own pid orphans the grandchildren, which keep running and keep
+ * writing to the log. So we kill the whole tree.
+ *
+ *  - POSIX: the command is spawned `detached`, which makes its pid a process
+ *    group leader, so a signal to the negative pid reaches the group. Send
+ *    SIGTERM, then escalate to SIGKILL after a grace period for anything that
+ *    ignored the polite signal. Fall back to the bare pid if the group send
+ *    fails (e.g. the group already gone).
+ *  - Windows: no process groups; `taskkill /T` walks and kills the tree. Use
+ *    the absolute System32 path so it works regardless of PATH, spawned with an
+ *    error handler so a missing binary can never throw into the caller.
+ *
+ * Zero dependencies — node:child_process only.
+ */
+import { spawn } from "node:child_process";
+
+const GRACE_MS = 3000;
+
+export function killTree(pid: number | null | undefined): void {
+  if (!pid || pid <= 0) return;
+
+  if (process.platform === "win32") {
+    const taskkill = `${process.env.SystemRoot ?? "C:\\Windows"}\\System32\\taskkill.exe`;
+    try {
+      spawn(taskkill, ["/PID", String(pid), "/T", "/F"], { windowsHide: true, stdio: "ignore" }).on(
+        "error",
+        () => {},
+      );
+    } catch {
+      // A machine without taskkill is not one we can do better on.
+    }
+    return;
+  }
+
+  const signalGroup = (sig: NodeJS.Signals) => {
+    try {
+      process.kill(-pid, sig);
+      return true;
+    } catch {
+      try {
+        process.kill(pid, sig);
+        return true;
+      } catch {
+        return false;
+      }
+    }
+  };
+
+  if (!signalGroup("SIGTERM")) return;
+  const timer = setTimeout(() => signalGroup("SIGKILL"), GRACE_MS);
+  timer.unref?.();
+}

package/src/pending.ts

@@ -0,0 +1,95 @@
+/**
+ * The messages a backgrounded command produces — when it is sent to the
+ * background, and when it comes back.
+ *
+ * Two audiences, one hard constraint. Delivery — pushing the finished result
+ * into the conversation unasked — only works if the session outlives the run.
+ * An interactive session does; a headless `pi -p` run tears down the moment the
+ * prompt resolves, so there is nothing left to deliver into. So the not-ready
+ * message tells the truth for the mode it is in: interactive can wait, headless
+ * must collect within the turn.
+ *
+ * Pure strings; the extension owns the clock, the processes and the host.
+ */
+
+export interface BackgroundedInput {
+  id: string;
+  command: string;
+  elapsedMs: number;
+  /** True on the auto-30s path, false when the caller asked for background. */
+  auto: boolean;
+  /** Whether a UI/interactive session is present to deliver into. */
+  interactive: boolean;
+  /** The tool to collect with, e.g. "shell_status". */
+  collectWith: string;
+}
+
+function elapsed(ms: number): string {
+  if (ms < 1000) return "just now";
+  const s = Math.round(ms / 1000);
+  if (s < 60) return `${s}s`;
+  return `${Math.floor(s / 60)}m ${s % 60}s`;
+}
+
+function clip(command: string, max = 60): string {
+  const one = command.replace(/\s+/g, " ").trim();
+  return one.length <= max ? one : `${one.slice(0, max - 1)}…`;
+}
+
+export interface BackgroundedResult {
+  text: string;
+  details: {
+    id: string;
+    status: "running";
+    background: true;
+    auto: boolean;
+    retryable: true;
+    pollRequired: boolean;
+    elapsedMs: number;
+  };
+}
+
+export function backgroundedResult(input: BackgroundedInput): BackgroundedResult {
+  const head = input.auto
+    ? `${input.id} is still running after ${elapsed(input.elapsedMs)} — moved to the background.`
+    : `${input.id} started in the background.`;
+  const line = `  $ ${clip(input.command)}`;
+  const tail = input.interactive
+    ? [
+        "Its result is delivered here automatically when it finishes, so carry on with other",
+        `work. ${input.collectWith} with id "${input.id}" is only if you want it early, and ${input.collectWith}`,
+        "with no id lists everything still running.",
+      ]
+    : [
+        "This is a headless run: nothing is delivered after your turn ends. Call",
+        `${input.collectWith} with id "${input.id}" again in this same turn until it reports finished —`,
+        "do not end your turn expecting the result to arrive on its own.",
+      ];
+  return {
+    text: [head, line, "", ...tail].join("\n"),
+    details: {
+      id: input.id,
+      status: "running",
+      background: true,
+      auto: input.auto,
+      retryable: true,
+      pollRequired: !input.interactive,
+      elapsedMs: input.elapsedMs,
+    },
+  };
+}
+
+/** How a finished background job introduces itself when it arrives unasked. */
+export function deliveryMessage(id: string, body: string): string {
+  return [
+    `<shell_background_result id="${id}">`,
+    body.trim(),
+    `</shell_background_result>`,
+    "",
+    `This is ${id}, a command you sent to the background; it has just finished and this is its result.`,
+    "Fold it into what you are doing. If you had already moved on, say what it changes — or that it changes nothing.",
+  ].join("\n");
+}
+
+/** The custom-message type a delivered result travels under. */
+export const DELIVERY_TYPE = "pify-shell-background-result";

package/src/registry.ts

@@ -0,0 +1,123 @@
+/**
+ * The set of background jobs, in memory and mirrored to disk.
+ *
+ * The live Map is the source of truth while the session runs. Each job is also
+ * written to a small JSON sidecar (atomically, temp + rename) so the status
+ * tool still answers after a `/reload` re-instantiates the extension, and so a
+ * job that outran the session can be reconciled: on load, a job still marked
+ * running whose pid is no longer alive is settled as finished rather than shown
+ * as forever-running.
+ *
+ * Scoped to one session via the base directory the caller supplies, so two pi
+ * sessions never reconcile each other's jobs. Zero dependencies — node:fs/path.
+ */
+import { mkdirSync, writeFileSync, renameSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { Job } from "./types.ts";
+import { isRecord } from "./types.ts";
+
+function isAlive(pid: number | null): boolean {
+  if (!pid || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    // EPERM means the process exists but we may not signal it — still alive.
+    return (err as { code?: string }).code === "EPERM";
+  }
+}
+
+function isJob(v: unknown): v is Job {
+  return (
+    isRecord(v) &&
+    typeof v.id === "string" &&
+    typeof v.command === "string" &&
+    typeof v.logPath === "string" &&
+    typeof v.status === "string"
+  );
+}
+
+export class JobRegistry {
+  private readonly jobs = new Map<string, Job>();
+  private counter = 0;
+  private readonly baseDir: string;
+
+  constructor(baseDir: string) {
+    this.baseDir = baseDir;
+    mkdirSync(join(baseDir, "logs"), { recursive: true });
+  }
+
+  logPathFor(id: string): string {
+    return join(this.baseDir, "logs", `${id}.log`);
+  }
+
+  create(command: string, cwd: string): Job {
+    const id = `bg-${++this.counter}`;
+    const job: Job = {
+      id,
+      command,
+      cwd,
+      pid: null,
+      status: "running",
+      exitCode: null,
+      signal: null,
+      logPath: this.logPathFor(id),
+      startedAt: Date.now(),
+      endedAt: null,
+      auto: false,
+      delivered: false,
+    };
+    this.jobs.set(id, job);
+    return job;
+  }
+
+  get(id: string): Job | undefined {
+    return this.jobs.get(id);
+  }
+
+  all(): Job[] {
+    return [...this.jobs.values()];
+  }
+
+  running(): Job[] {
+    return this.all().filter((j) => j.status === "running");
+  }
+
+  persist(job: Job): void {
+    try {
+      const file = join(this.baseDir, `${job.id}.json`);
+      const tmp = `${file}.${process.pid}.tmp`;
+      writeFileSync(tmp, JSON.stringify(job));
+      renameSync(tmp, file);
+    } catch {
+      // A registry we cannot persist still works for the live session.
+    }
+  }
+
+  /** Load persisted jobs and settle any whose process has since died. */
+  load(): void {
+    let files: string[];
+    try {
+      files = readdirSync(this.baseDir);
+    } catch {
+      return;
+    }
+    for (const f of files) {
+      if (!f.endsWith(".json")) continue;
+      try {
+        const raw = JSON.parse(readFileSync(join(this.baseDir, f), "utf8"));
+        if (!isJob(raw)) continue;
+        const job = raw;
+        if (job.status === "running" && !isAlive(job.pid)) {
+          job.status = "done";
+          job.endedAt = job.endedAt ?? Date.now();
+        }
+        this.jobs.set(job.id, job);
+        const n = Number(job.id.replace(/^bg-/, ""));
+        if (Number.isFinite(n)) this.counter = Math.max(this.counter, n);
+      } catch {
+        // Skip a corrupt sidecar rather than fail the whole load.
+      }
+    }
+  }
+}

package/src/spawn.ts

@@ -0,0 +1,121 @@
+/**
+ * Spawn a shell command whose output streams to a log file, cross-platform.
+ *
+ * The obvious trick — hand the child the file's own descriptor as stdout/stderr
+ * so the kernel writes it with zero JS in the path — is POSIX-only. On Windows
+ * a numeric fd in `stdio` does not inherit the way it does on Unix (measured:
+ * the command exits 1 and the file stays empty), which is why the background-
+ * bash extensions that use it have no Windows story. This suite supports
+ * Windows, so we take the portable path: pipe stdout and stderr and write them
+ * into one log file ourselves.
+ *
+ * Losslessness then depends on draining the pipes, which we do on every chunk,
+ * and on not finalizing before the tail arrives: after the process exits we
+ * wait for both pipes to end, with a short grace timer so a quiet inherited
+ * handle (a Windows daemonized grandchild that never closes it) still releases.
+ *
+ * `detached` (POSIX) makes the child a process-group leader so its whole tree
+ * can be signalled (see kill.ts); `unref` keeps a running job from holding the
+ * host's event loop open. The job lives as long as the session does — it is
+ * killed on shutdown, not orphaned — so pipes owned by the parent are the right
+ * model. Zero dependencies: node:child_process + node:fs.
+ */
+import { spawn } from "node:child_process";
+import { createWriteStream } from "node:fs";
+
+export interface Spawned {
+  pid: number | null;
+  /** Resolves once, when the process exits (after its output has drained) or fails to start. */
+  exit: Promise<{ code: number | null; signal: NodeJS.Signals | null }>;
+}
+
+const DRAIN_GRACE_MS = 150;
+
+export function spawnToFile(
+  shell: string,
+  shellArgs: readonly string[],
+  command: string,
+  cwd: string,
+  env: NodeJS.ProcessEnv,
+  logPath: string,
+): Spawned {
+  // Append so a re-attach or racing read never clips output already written.
+  const out = createWriteStream(logPath, { flags: "a" });
+
+  let child;
+  try {
+    child = spawn(shell, [...shellArgs, command], {
+      cwd,
+      env,
+      detached: process.platform !== "win32",
+      stdio: ["ignore", "pipe", "pipe"],
+      windowsHide: true,
+    });
+  } catch {
+    out.end();
+    return { pid: null, exit: Promise.resolve({ code: null, signal: null }) };
+  }
+
+  const pump = (s: NodeJS.ReadableStream | null) => {
+    s?.on("data", (chunk) => {
+      try {
+        out.write(chunk);
+      } catch {
+        // A closed sink must not crash the reader.
+      }
+    });
+  };
+  pump(child.stdout);
+  pump(child.stderr);
+
+  const exit = new Promise<{ code: number | null; signal: NodeJS.Signals | null }>((resolve) => {
+    let settled = false;
+    let info: { code: number | null; signal: NodeJS.Signals | null } | null = null;
+    let stdoutEnded = child.stdout === null;
+    let stderrEnded = child.stderr === null;
+
+    const finish = () => {
+      if (settled || !info) return;
+      settled = true;
+      try {
+        out.end();
+      } catch {
+        // already closed
+      }
+      resolve(info);
+    };
+    const maybeFinish = () => {
+      if (info && stdoutEnded && stderrEnded) finish();
+    };
+
+    child.stdout?.on("end", () => {
+      stdoutEnded = true;
+      maybeFinish();
+    });
+    child.stderr?.on("end", () => {
+      stderrEnded = true;
+      maybeFinish();
+    });
+    child.on("exit", (code, signal) => {
+      info = { code, signal };
+      maybeFinish();
+      // The pipes usually end right after exit; if one is held open by a
+      // detached grandchild, finalize anyway after a short grace.
+      const grace = setTimeout(() => {
+        stdoutEnded = true;
+        stderrEnded = true;
+        finish();
+      }, DRAIN_GRACE_MS);
+      grace.unref?.();
+    });
+    child.on("error", () => {
+      info = info ?? { code: null, signal: null };
+      stdoutEnded = true;
+      stderrEnded = true;
+      finish();
+    });
+  });
+
+  child.unref();
+  return { pid: child.pid ?? null, exit };
+}

package/src/tail.ts

@@ -0,0 +1,65 @@
+/**
+ * Read the tail of a growing log without loading the whole file.
+ *
+ * A background command writes its stdout and stderr straight into a file (see
+ * spawn.ts), so the status tool must read it back cheaply — a chatty job can
+ * produce megabytes, and `readFileSync` on that just to show the last screen is
+ * how a poll turns into an OOM. So seek to the end and read a bounded window.
+ *
+ * The window can begin mid-character: a multibyte UTF-8 sequence split at the
+ * cut would decode to a replacement char, so when we did not start at byte 0 we
+ * drop the leading continuation bytes (0b10xxxxxx) until a real character
+ * boundary. Zero dependencies — node:fs only.
+ */
+import { openSync, fstatSync, readSync, closeSync } from "node:fs";
+
+export interface Tail {
+  /** The decoded trailing text. */
+  text: string;
+  /** True if bytes before the window were dropped. */
+  truncated: boolean;
+  /** Total size of the file in bytes. */
+  bytes: number;
+}
+
+export const DEFAULT_TAIL_BYTES = 64 * 1024;
+
+export function readTail(path: string, maxBytes: number = DEFAULT_TAIL_BYTES): Tail {
+  let fd: number;
+  try {
+    fd = openSync(path, "r");
+  } catch {
+    return { text: "", truncated: false, bytes: 0 };
+  }
+  try {
+    const size = fstatSync(fd).size;
+    if (size === 0) return { text: "", truncated: false, bytes: 0 };
+    const start = size > maxBytes ? size - maxBytes : 0;
+    const len = size - start;
+    const buf = Buffer.allocUnsafe(len);
+    let read = 0;
+    while (read < len) {
+      const n = readSync(fd, buf, read, len - read, start + read);
+      if (n <= 0) break;
+      read += n;
+    }
+    let slice = buf.subarray(0, read);
+    if (start > 0) {
+      // Drop a leading partial UTF-8 char left by cutting mid-sequence.
+      let i = 0;
+      while (i < slice.length && (slice[i]! & 0xc0) === 0x80) i++;
+      slice = slice.subarray(i);
+    }
+    return { text: slice.toString("utf8"), truncated: start > 0, bytes: size };
+  } catch {
+    return { text: "", truncated: false, bytes: 0 };
+  } finally {
+    closeSync(fd);
+  }
+}
+
+/** Non-empty line count of a chunk of text. */
+export function countLines(text: string): number {
+  if (!text) return 0;
+  return text.split("\n").filter((l) => l.trim() !== "").length;
+}

package/src/types.ts

@@ -0,0 +1,40 @@
+/**
+ * Shared shapes for @pify/shell-background.
+ * No imports from pi packages: src/ typechecks and unit-tests standalone.
+ */
+
+export type JobStatus = "running" | "done" | "failed" | "killed";
+
+export interface Job {
+  /** Short session-monotonic id, e.g. "bg-1". */
+  id: string;
+  command: string;
+  cwd: string;
+  /** OS pid of the shell process; null before spawn or if spawn failed. */
+  pid: number | null;
+  status: JobStatus;
+  /** Process exit code, once finished. */
+  exitCode: number | null;
+  /** Terminating signal name, if the process was signalled. */
+  signal: string | null;
+  /** Absolute path of the merged stdout+stderr log file. */
+  logPath: string;
+  startedAt: number;
+  endedAt: number | null;
+  /** True if it reached the background because it outran the auto-threshold, */
+  /** false if the caller asked for background up front. */
+  auto: boolean;
+  /** Whether the finished result has been delivered back to the conversation. */
+  delivered: boolean;
+  /** Set when we killed it (timeout/abort/shell_kill), so exit reads as killed. */
+  killedByUs?: boolean;
+}
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** A finished job is anything past running. */
+export function isFinished(job: Job): boolean {
+  return job.status !== "running";
+}

package/src/widget.ts

@@ -0,0 +1,77 @@
+/**
+ * The aboveEditor box listing background jobs — running ones, and any that
+ * finished in the last 15s so a completion is visible before it disappears.
+ * Pure string builder; the extension wraps it in a pi-tui Text.
+ */
+import type { Job } from "./types.ts";
+
+const WIDTH = 54;
+const MAX_ROWS = 8;
+
+export interface WidgetTheme {
+  fg(color: string, text: string): string;
+  bold(text: string): string;
+}
+
+function icon(job: Job): string {
+  switch (job.status) {
+    case "running":
+      return "⟳";
+    case "done":
+      return "✓";
+    case "failed":
+      return "✗";
+    default:
+      return "◼";
+  }
+}
+
+function color(job: Job): string {
+  switch (job.status) {
+    case "running":
+      return "warning";
+    case "done":
+      return "success";
+    case "failed":
+      return "error";
+    default:
+      return "dim";
+  }
+}
+
+function elapsed(job: Job, now: number): string {
+  const end = job.endedAt ?? now;
+  const s = Math.max(0, Math.round((end - job.startedAt) / 1000));
+  return s < 60 ? `${s}s` : `${Math.floor(s / 60)}m ${s % 60}s`;
+}
+
+function clip(text: string, max: number): string {
+  const one = text.replace(/\s+/g, " ").trim();
+  return one.length <= max ? one : `${one.slice(0, max - 1)}…`;
+}
+
+export function buildWidgetLines(jobs: Job[], theme: WidgetTheme, now: number): string[] {
+  const dim = (s: string) => theme.fg("dim", s);
+  const visible = jobs
+    .filter((j) => j.status === "running" || (j.endedAt ?? 0) > now - 15_000)
+    .sort((a, b) => a.startedAt - b.startedAt);
+  if (visible.length === 0) return [];
+
+  const running = visible.filter((j) => j.status === "running").length;
+  const title = ` ⚙ shell-bg · ${running} running `;
+  const hint = " /shell-bg ";
+  const pad = Math.max(1, WIDTH - title.length - hint.length);
+  const lines = [dim(`╭${title}${"─".repeat(pad)}${hint}╮`)];
+
+  const shown = visible.slice(-MAX_ROWS);
+  const hidden = visible.length - shown.length;
+  for (const j of shown) {
+    const c = color(j);
+    lines.push(
+      `${theme.fg(c, icon(j))} ${theme.fg(c, j.id)} ${dim(`· ${elapsed(j, now)}`)} ${dim(clip(j.command, 28))}`,
+    );
+  }
+  if (hidden > 0) lines.push(dim(`│ … +${hidden} more`));
+  lines.push(dim(`╰${"─".repeat(WIDTH)}╯`));
+  return lines;
+}