specpi 0.18.1 → 0.19.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.19.0 - 2026-09-07
+
+- Add session-owned background commands with exact interactive approvals, shared Command Guard admission, bounded logs, and best-effort process cleanup.
+- Install and verify the background tools with an offline doctor smoke; document shell, environment, output-retention, and process-tree limits.
+- Clarify repository guidance for concise commits, pull requests, and necessary risk-focused validation.
+
 ## 0.18.1 - 2026-09-07
 
 - Restore Pi's cached model catalogs during delegation setup so switching to catalog-added or updated models resumes workers without a manual toggle or restart. Catalog network refresh stays disabled; exact-model checks, safety revocations and spent quotas remain enforced.

package/README.md

@@ -30,6 +30,7 @@ SpecPi extends Pi with chat, review tools, and focused delegation. Its principle
 ## What it adds
 
 - **Focused delegation.** One agent makes changes. Up to two read-only subagents help investigate and review. [Research and design](https://tannermidd.github.io/SpecPi/single-agent/)
+- **Background tasks.** Start an approved dev server, test suite, or watch build, inspect bounded output, and stop it without blocking other work.
 - **Review as you work.** Track changed files, inspect diffs, check pages in a browser, and review risky commands.
 - **Improvements you choose.** Record recurring problems, select one with `/harness-improvement`, and test the change before calling it done.
 
@@ -48,12 +49,20 @@ specpi doctor
 
 Preview the changes, confirm the install, then check the setup. Restart Pi when finished.
 
-To pin this release, use `npm install --global specpi@0.18.1`.
+To pin this release, use `npm install --global specpi@0.19.0`.
 
 Delegation is enabled at startup. Use `/delegate off` to turn it off.
 
 [Setup, updates & removal](https://tannermidd.github.io/SpecPi/wiki/#getting-started) · [Delegation settings](docs/delegation/README.md)
 
+## Background tasks
+
+Ask Pi to start a long-running command with `background_start`, then use `background_list`, `background_logs`, and `background_stop` to observe and clean up tasks. `background_start` accepts `command`, optional `cwd`/`label`, and `timeoutSeconds` (1–28,800; default 1,800). It requires interactive approval even with Guard off; Guard denials and locks still apply. Headless starts are denied.
+
+Commands use `/bin/sh` on POSIX or system `cmd.exe` on Windows, not Pi's configured Bash. They inherit the process environment except `NODE_OPTIONS` and `NODE_PATH`, which are cleared to keep the supervisor's startup predictable. No PTY or interactive stdin is provided. Four active tasks are allowed; output is capped at 256 KiB per task, reads at 64 KiB, and completed records at 32. Log offsets are absolute bytes in the UTF-8 stream including stdout/stderr markers, before terminal-control escaping; responses report the next cursor and lost bytes.
+
+Stop tasks when finished. Session replacement, reload, tree navigation, and shutdown attempt bounded cleanup. `cleanup: confirmed` means the owned root/group termination was observed, not that escaped descendants are contained; unconfirmed cleanup retains its slot and may need manual process inspection. Spawn success is not service readiness. Output is memory-only in the extension, but returned text may enter Pi conversation/provider retention. See the [security boundary](SECURITY_MODEL.md#background-task-execution).
+
 ## SpecPi Chat for VS Code
 
 Chat beside your code, attach files, and switch conversations.
@@ -62,7 +71,7 @@ Chat beside your code, attach files, and switch conversations.
 
 In VS Code, find **SpecPi Chat** by **tannermidd** in Extensions and install it. Open **SpecPi** in the Activity Bar, then **Connect Pi**.
 
-Chat 0.4.1 shows a compact delegation strip only while workers run or settle, and opens workspace image links in the image viewer. SpecPi 0.18.1 fixes delegation after switching models in the same chat. Update both packages, reload VS Code for the Chat update, and use **Restart Pi** to load the harness update. Later model switches do not require a restart. New Chat sessions start with Guard off; use `/guard guard` or `/guard strict` to enable it.
+Chat 0.4.1 shows a compact delegation strip only while workers run or settle, and opens workspace image links in the image viewer. SpecPi 0.19.0 includes the delegation fix for switching models in the same chat. Update both packages, reload VS Code for the Chat update, and use **Restart Pi** to load the harness update. Later model switches do not require a restart. New Chat sessions start with Guard off; use `/guard guard` or `/guard strict` to enable it.
 
 ## Go further
 

package/SECURITY_MODEL.md

@@ -111,7 +111,7 @@ Global package installations, upstream package-manager effects, downloaded cache
 
 ## Command Guard
 
-Command Guard is a pre-execution policy layer for model-initiated Pi tool calls. It covers Pi's documented `bash`, `powershell`, `read`, `write`, and `edit` tools. Other extensions, custom or MCP tools, direct user `!command` and `!!command` escapes, approved scripts, and process execution outside these seams are not contained.
+Command Guard is a pre-execution policy layer for model-initiated Pi tool calls. It covers Pi's documented `bash`, `powershell`, `read`, `write`, and `edit` tools. Other extensions, custom or MCP tools, direct user `!command` and `!!command` escapes, approved scripts, and process execution outside these seams are not contained. SpecPi's background tools are an explicit reviewed integration: starts request Guard's shared admission policy again inside execution, while observation and owned-task cleanup remain available under locks.
 
 Interactive top-level sessions choose one session-only mode:
 
@@ -129,6 +129,20 @@ The guard keeps mode, lock, counters, parser cache, and approval hashes only in
 
 Static analysis cannot resolve every alias, generated command, script body, plugin, encoding, runtime expansion, symlink race, or interpreter behavior. Recognized private-path reads receive narrow protection, but arbitrary scripts or shell syntax can still read credentials. An allowed or approved command runs with the user's full permissions. `specpi doctor` verifies installed checksums and deterministic policy smoke behavior, not universal command safety.
 
+## Background task execution
+
+`background_start` executes an approved noninteractive command under the user's permissions, using `/bin/sh` on POSIX or system `cmd.exe /d /s /c` on Windows. It does not inherit Pi's Bash configuration or spawn hooks. POSIX commands are classified by Guard's Bash parser but executed by `/bin/sh` (often dash); the dialect mismatch can change parsing or runtime behavior. Classification is defense in depth, not proof of shell equivalence. The process environment is inherited except `NODE_OPTIONS` and `NODE_PATH`, cleared to prevent ambient Node startup hooks in the bundled supervisor. No provider authentication resolution, private Pi store inspection, or session-environment injection is performed. Approved processes can still access ambient secrets and same-user files; this is not credential isolation.
+
+Starts require an active session and interactive UI, even for cached approvals and when Guard is Off. A synchronous event requests Guard's current mode, generation, and command decision. Guard/Strict critical denials and locks cannot be approved away; uncertainty is shown in the feature's approval prompt. An absent Guard falls back to the shared Guard-mode command policy. Unready, old, or ambiguous Guard responders fail closed. Trusted extensions and the shared event bus remain privileged, not an adversarial isolation boundary. Guard exempts the four background tools from its outer tool-call gate only when Pi's current tool-registration metadata identifies the sibling `background-tasks/index.ts` entry point. Missing, replaced, or foreign registrations retain ordinary Strict and locked checks; matching a name alone is insufficient. Genuine starts recheck admission inside execution, while observation/stop validate their own inputs and only address the extension's opaque task IDs. Registration provenance is not containment of a malicious trusted extension or a modified installed entry point.
+
+Background approval is deliberately binary and session-scoped: v1 offers no allow-once option, unlike Guard's general approval menu. The confirmation explicitly grants the exact execution for the session. Approvals bind exact command, canonical cwd, shell policy, timeout, label, session generation, and Guard decision/generation. Inputs and policy are checked again immediately before launch, including cached approvals. Lifecycle and Guard changes invalidate pending prompts and approval state. Commands and approvals are not persisted by the extension. Directory replacement, changed scripts/executables, inherited environment changes, and filesystem races cannot be fully resolved by an exact command fingerprint; approval grants arbitrary execution, not an immutable executable snapshot.
+
+The runner reserves at most four active/unconfirmed tasks before spawning. Command/cwd/label input limits are 16 KiB/4 KiB/128 UTF-8 bytes, approvals are capped at 128, and completed records at 32. Combined stdout/stderr retention is capped at 256 KiB per task with 64 KiB raw-output reads. Stream markers count toward absolute UTF-8 byte cursors; terminal controls are escaped after slicing, so serialized responses can be larger (bounded below 512 KiB). Lost bytes and truncation are explicit. Output and previews are untrusted; preview redaction is best effort, not a secrecy guarantee. There is no extension-owned command/output journal. Tool results can enter normal Pi conversation storage and model-provider retention, and executed programs can write files themselves. These caps do not bound child CPU, memory, disk, or network usage.
+
+A bundled Node supervisor keeps the owned root alive after shell exit until cleanup. Deadlines (30 minutes by default, at most eight hours) initiate termination, not a guarantee of stopped work. POSIX uses a dedicated process group with a five-second SIGTERM grace then SIGKILL for running commands. If the command's exit or spawn failure was already observed when cleanup began, it skips that grace and cleans up the remaining group immediately; the supervisor still holds the root identity until escalation. Windows uses fixed-argv system `taskkill /T /F`. Cleanup observes the root exit and, on POSIX, process-group disappearance. It does not signal an observed-dead root again, reducing PID-reuse risk without eliminating OS races. Windows tree discovery can miss descendants after intermediate parent exit; detached/escaped descendants, orphaned zombies, crashes, denied signals, and forced host termination remain limitations. A confirmed cleanup covers only this supported root/group evidence, not universal descendant death. Failed/unconfirmed cleanup retains its slot and record while the extension instance lives.
+
+Start cancellation attempts cleanup and returns its task outcome; cancelling log reads does not stop registered work. Shutdown (including reload/new/resume/fork) and tree navigation revoke approvals and attempt bounded cleanup. The UI reports uncertainty with blocking task IDs and recovery steps: starts stay disabled in that runtime, so retry `background_stop` for those IDs, then `/reload` after cleanup confirms. Old-instance memory and IDs do not survive replacement or a crash; inspect any remaining processes manually if the runtime has already changed. Stop remains available under policy locks and is idempotent. No automatic restart, persistence, or follow-up model turn is provided. Doctor checks installed checksums before running the bundled offline smoke; fixture success proves supported behavior, not OS containment.
+
 ## Local improvement state
 
 Capability-gap collection is disabled until the user makes an explicit local on/off choice. When enabled, SpecPi stores bounded sanitized summaries and salted hashes used to measure distinct tasks, sessions, and projects. It does not read prompts, source files, sessions, history, credentials, provider authentication, or trust decisions to construct reports, and it never uploads wishlist state.

package/extensions/background-tasks/core.d.mts

@@ -0,0 +1,90 @@
+import type { ChildProcess, spawn } from "node:child_process";
+
+export type StartSpec = Readonly<{
+    command: string;
+    cwd: string;
+    label: string;
+    timeoutSeconds: number;
+    shell: string;
+    dialect: "bash" | "cmd";
+}>;
+export type TaskSummary = {
+    id: string;
+    label: string;
+    command: string;
+    status: "starting" | "running" | "stopping" | "cleanup-unconfirmed" | "failed" | "exited" | "killed";
+    elapsedMs: number;
+    exitCode: number | null;
+    exitSignal: string | null;
+    reason: string | null;
+    cleanup: "pending" | "confirmed" | "unconfirmed";
+    generation: number;
+};
+export type OwnedRoot = {
+    child?: Pick<ChildProcess, "pid">;
+    rootExited: boolean;
+    exitCode?: number | null;
+};
+export type Task = OwnedRoot & {
+    id: string;
+    spec: StartSpec;
+    generation: number;
+    startedAt: number;
+    endedAt?: number;
+    status: TaskSummary["status"];
+    cleanup: TaskSummary["cleanup"];
+    ring: OutputRing;
+    child?: ChildProcess;
+    exitSignal?: string | null;
+    reason?: string;
+    failed?: boolean;
+    stopping?: Promise<TaskSummary>;
+    timer?: ReturnType<typeof setTimeout>;
+};
+export declare const LIMITS: Readonly<
+    Record<"command" | "cwd" | "label" | "active" | "completed" | "approvals" | "buffer" | "read" | "timeout", number>
+>;
+export declare function safeText(value: unknown): string;
+export declare function preview(value: unknown, limit?: number): string;
+export declare function record(value: unknown, keys: string[]): void;
+export declare function shellSpec(platform?: NodeJS.Platform): Pick<StartSpec, "shell" | "dialect">;
+export declare function normalizeStart(input: unknown, cwd: string): StartSpec;
+export declare class OutputRing {
+    constructor(capacity?: number);
+    capacity: number;
+    bytes: Buffer;
+    end: number;
+    append(stream: "stdout" | "stderr", chunk: Buffer, final?: boolean): void;
+    append(stream: "stdout" | "stderr", chunk: undefined, final: true): void;
+    read(offset?: number): {
+        output: string;
+        offset: number;
+        nextOffset: number;
+        endOffset: number;
+        lostBytes: number;
+        truncated: boolean;
+    };
+}
+export declare function terminateOwned(
+    task: OwnedRoot,
+    options?: { graceMs?: number; observeMs?: number },
+): Promise<boolean>;
+export declare class TaskRunner {
+    constructor(options?: {
+        spawnProcess?: typeof spawn;
+        terminate?: (task: Task) => Promise<boolean>;
+        startupMs?: number;
+    });
+    tasks: Map<string, Task>;
+    closed: boolean;
+    spawnProcess: typeof spawn;
+    terminate: (task: Task) => Promise<boolean>;
+    startupMs: number;
+    get(id: string): Task;
+    summary(task: Task): TaskSummary;
+    list(): TaskSummary[];
+    evict(): void;
+    start(spec: StartSpec, generation: number, signal?: AbortSignal): Promise<TaskSummary>;
+    stop(id: string, reason?: string): Promise<TaskSummary>;
+    shutdown(): Promise<TaskSummary[]>;
+}

package/extensions/background-tasks/core.mjs

@@ -0,0 +1,413 @@
+import fs from "node:fs";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { spawn, execFile } from "node:child_process";
+import { StringDecoder } from "node:string_decoder";
+import { fileURLToPath } from "node:url";
+import { redactCommand } from "../command-guard/redact.mjs";
+
+export const LIMITS = Object.freeze({
+    command: 16384,
+    cwd: 4096,
+    label: 128,
+    active: 4,
+    completed: 32,
+    approvals: 128,
+    buffer: 262144,
+    read: 65536,
+    timeout: 28800,
+});
+const supervisor = fileURLToPath(new URL("./supervisor.mjs", import.meta.url));
+const terminal = /[\u0000-\u0008\u000b-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/gu;
+export function safeText(value) {
+    return String(value).replace(
+        terminal,
+        (character) => `\\u${character.charCodeAt(0).toString(16).padStart(4, "0")}`,
+    );
+}
+
+export function preview(value, limit = 320) {
+    return safeText(redactCommand(value, limit));
+}
+
+export function record(value, keys) {
+    if (
+        !value ||
+        typeof value !== "object" ||
+        Array.isArray(value) ||
+        Object.keys(value).some((key) => !keys.includes(key))
+    ) {
+        throw new Error("Invalid background task input.");
+    }
+}
+
+function text(value, limit, name) {
+    if (typeof value !== "string" || !value.trim() || value.includes("\0") || Buffer.byteLength(value) > limit) {
+        throw new Error(`Invalid or oversized ${name}.`);
+    }
+
+    return value;
+}
+
+export function shellSpec(platform = process.platform) {
+    if (platform === "win32") {
+        return { shell: path.join(process.env.SystemRoot || "C:\\Windows", "System32", "cmd.exe"), dialect: "cmd" };
+    }
+
+    return { shell: "/bin/sh", dialect: "bash" };
+}
+
+export function normalizeStart(input, cwd) {
+    record(input, ["command", "cwd", "label", "timeoutSeconds"]);
+    const command = text(input.command, LIMITS.command, "command");
+    const requestedCwd = text(input.cwd ?? cwd, LIMITS.cwd, "cwd");
+    let resolved;
+    try {
+        resolved = fs.realpathSync(path.resolve(cwd, requestedCwd));
+        if (!fs.statSync(resolved).isDirectory()) {
+            throw new Error();
+        }
+    } catch {
+        throw new Error("Background cwd must be an existing directory.");
+    }
+
+    text(resolved, LIMITS.cwd, "resolved cwd");
+    const label = input.label === undefined ? "" : text(input.label, LIMITS.label, "label");
+    const timeoutSeconds = input.timeoutSeconds ?? 1800;
+    if (!Number.isInteger(timeoutSeconds) || timeoutSeconds < 1 || timeoutSeconds > LIMITS.timeout) {
+        throw new Error("timeoutSeconds must be an integer from 1 to 28800.");
+    }
+
+    return Object.freeze({ command, cwd: resolved, label, timeoutSeconds, ...shellSpec() });
+}
+
+export class OutputRing {
+    constructor(capacity = LIMITS.buffer) {
+        this.capacity = capacity;
+        this.bytes = Buffer.alloc(0);
+        this.end = 0;
+        this.decoders = { stdout: new StringDecoder("utf8"), stderr: new StringDecoder("utf8") };
+    }
+    append(stream, chunk, final = false) {
+        const decoded = final ? this.decoders[stream].end() : this.decoders[stream].write(chunk);
+        if (!decoded) {
+            return;
+        }
+
+        const next = Buffer.from(`[${stream}] ${decoded}`);
+        this.end += next.length;
+        if (next.length >= this.capacity) {
+            this.bytes = Buffer.from(next.subarray(next.length - this.capacity));
+        } else {
+            this.bytes = Buffer.concat([
+                this.bytes.subarray(Math.max(0, this.bytes.length + next.length - this.capacity)),
+                next,
+            ]);
+        }
+
+        let skip = 0;
+        while (skip < this.bytes.length && (this.bytes[skip] & 0xc0) === 0x80) {
+            skip += 1;
+        }
+
+        this.bytes = this.bytes.subarray(skip);
+    }
+    read(offset = 0) {
+        if (!Number.isSafeInteger(offset) || offset < 0 || offset > this.end) {
+            throw new Error("Invalid or future output cursor.");
+        }
+
+        const oldest = this.end - this.bytes.length;
+        let start = Math.max(offset, oldest) - oldest;
+        while (start < this.bytes.length && (this.bytes[start] & 0xc0) === 0x80) {
+            start += 1;
+        }
+
+        let end = Math.min(this.bytes.length, start + LIMITS.read);
+        while (end < this.bytes.length && end > start && (this.bytes[end] & 0xc0) === 0x80) {
+            end -= 1;
+        }
+
+        return {
+            output: safeText(this.bytes.subarray(start, end).toString("utf8")),
+            offset: oldest + start,
+            nextOffset: oldest + end,
+            endOffset: this.end,
+            lostBytes: oldest + start - offset,
+            truncated: oldest + start > offset || end < this.bytes.length,
+        };
+    }
+}
+
+function delay(milliseconds) {
+    return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+
+function groupAlive(pid) {
+    try {
+        process.kill(-pid, 0);
+
+        return true;
+    } catch (error) {
+        return error.code !== "ESRCH";
+    }
+}
+
+export async function terminateOwned(task, { graceMs = 5000, observeMs = 1000 } = {}) {
+    if (!task.child?.pid) {
+        return true;
+    }
+
+    const pid = task.child.pid;
+    if (process.platform === "win32") {
+        // Never taskkill a PID after observing that the owned supervisor exited.
+        if (task.rootExited) {
+            return false;
+        }
+
+        const helper = path.join(process.env.SystemRoot || "C:\\Windows", "System32", "taskkill.exe");
+        const ok = await new Promise((resolve) => {
+            execFile(
+                helper,
+                ["/PID", String(pid), "/T", "/F"],
+                { windowsHide: true, timeout: 5000, maxBuffer: 16384 },
+                (error) => resolve(!error),
+            );
+        });
+        const end = Date.now() + observeMs;
+        while (!task.rootExited && Date.now() < end) {
+            await delay(20);
+        }
+
+        return ok && task.rootExited;
+    }
+
+    // Preserve grace for a running command/tree. An observed command exit (including
+    // a null exit code for a signal/failure) needs only the remaining group cleanup.
+    // Keep the supervisor alive until escalation; never signal an observed-dead root.
+    const commandExited = task.exitCode !== undefined;
+    if (!task.rootExited) {
+        try {
+            process.kill(-pid, "SIGTERM");
+        } catch (error) {
+            if (error.code !== "ESRCH") {
+                return false;
+            }
+        }
+
+        if (!commandExited) {
+            await delay(graceMs);
+        }
+
+        if (!task.rootExited) {
+            try {
+                process.kill(-pid, "SIGKILL");
+            } catch (error) {
+                if (error.code !== "ESRCH") {
+                    return false;
+                }
+            }
+        }
+    }
+
+    const end = Date.now() + observeMs;
+    while ((!task.rootExited || groupAlive(pid)) && Date.now() < end) {
+        await delay(20);
+    }
+
+    return task.rootExited && !groupAlive(pid);
+}
+
+export class TaskRunner {
+    constructor({ spawnProcess = spawn, terminate = terminateOwned, startupMs = 10000 } = {}) {
+        this.tasks = new Map();
+        this.spawnProcess = spawnProcess;
+        this.terminate = terminate;
+        this.startupMs = startupMs;
+        this.closed = false;
+    }
+    get(id) {
+        if (typeof id !== "string" || !this.tasks.has(id)) {
+            throw new Error("Unknown background task ID.");
+        }
+
+        return this.tasks.get(id);
+    }
+    summary(task) {
+        return {
+            id: task.id,
+            label: preview(task.spec.label, LIMITS.label),
+            command: preview(task.spec.command),
+            status: task.status,
+            elapsedMs: (task.endedAt ?? Date.now()) - task.startedAt,
+            exitCode: task.exitCode ?? null,
+            exitSignal: task.exitSignal ?? null,
+            reason: task.reason ?? null,
+            cleanup: task.cleanup,
+            generation: task.generation,
+        };
+    }
+    list() {
+        return [...this.tasks.values()].map((task) => this.summary(task));
+    }
+    evict() {
+        const completed = [...this.tasks.values()].filter((task) => task.cleanup === "confirmed");
+        while (completed.length > LIMITS.completed) {
+            this.tasks.delete(completed.shift().id);
+        }
+    }
+    async start(spec, generation, signal) {
+        signal?.throwIfAborted();
+        if (
+            this.closed ||
+            [...this.tasks.values()].filter((task) => task.cleanup !== "confirmed").length >= LIMITS.active
+        ) {
+            throw new Error("Background admission closed or four active/unconfirmed tasks already exist.");
+        }
+
+        const task = {
+            id: randomUUID(),
+            spec,
+            generation,
+            startedAt: Date.now(),
+            status: "starting",
+            cleanup: "pending",
+            ring: new OutputRing(),
+            rootExited: false,
+        };
+        // Reserve synchronously before any await, including supervisor startup.
+        this.tasks.set(task.id, task);
+        let settle;
+        const started = new Promise((resolve) => {
+            settle = resolve;
+        });
+        const abort = () => {
+            void this.stop(task.id, "start cancelled");
+            settle(false);
+        };
+
+        signal?.addEventListener("abort", abort, { once: true });
+        try {
+            task.child = this.spawnProcess(process.execPath, [supervisor], {
+                cwd: spec.cwd,
+                env: { ...process.env, NODE_OPTIONS: "", NODE_PATH: "" },
+                stdio: ["ignore", "pipe", "pipe", "ipc"],
+                detached: process.platform !== "win32",
+                windowsHide: true,
+            });
+            for (const stream of ["stdout", "stderr"]) {
+                task.child[stream].on("data", (chunk) => task.ring.append(stream, chunk));
+                task.child[stream].once("end", () => task.ring.append(stream, undefined, true));
+                task.child[stream].on("error", () => {});
+            }
+
+            task.child.once("error", () => {
+                task.failed = true;
+                task.rootExited = true;
+                settle(false);
+                void this.stop(task.id, "spawn failed");
+            });
+            task.child.once("exit", () => {
+                task.rootExited = true;
+                settle(false);
+                if (!task.stopping) {
+                    void this.stop(task.id, "supervisor exited unexpectedly");
+                }
+            });
+            task.child.on("message", (message) => {
+                if (message?.event === "ready" && task.status === "starting") {
+                    const args =
+                        process.platform === "win32" ? ["/d", "/s", "/c", `"${spec.command}"`] : ["-c", spec.command];
+                    task.child.send({ operation: "start", shell: spec.shell, args, cwd: spec.cwd }, (error) => {
+                        if (error) {
+                            settle(false);
+                            void this.stop(task.id, "startup failed");
+                        }
+                    });
+                } else if (message?.event === "started") {
+                    if (task.status === "starting") {
+                        task.status = "running";
+                    }
+
+                    settle(true);
+                } else if (message?.event === "exited" || message?.event === "failed") {
+                    task.exitCode = Number.isInteger(message.code) ? message.code : null;
+                    task.exitSignal = typeof message.signal === "string" ? message.signal.slice(0, 32) : null;
+                    task.failed = message.event === "failed";
+                    settle(!task.failed);
+                    void this.stop(task.id, task.failed ? "command spawn failed" : "command exited");
+                }
+            });
+            task.timer = setTimeout(() => {
+                void this.stop(task.id, "timeout");
+            }, spec.timeoutSeconds * 1000);
+            const startupTimer = setTimeout(() => settle(false), this.startupMs);
+            const success = await started;
+            clearTimeout(startupTimer);
+            if (!success || signal?.aborted || this.closed) {
+                await this.stop(task.id, signal?.aborted ? "start cancelled" : "startup failed");
+            }
+
+            return this.summary(task);
+        } catch {
+            task.failed = true;
+            await this.stop(task.id, "spawn failed");
+
+            return this.summary(task);
+        } finally {
+            signal?.removeEventListener("abort", abort);
+        }
+    }
+    async stop(id, reason = "stop requested") {
+        const task = this.get(id);
+        if (task.cleanup === "confirmed") {
+            return this.summary(task);
+        }
+
+        if (task.stopping) {
+            return task.stopping;
+        }
+
+        task.status = "stopping";
+        task.reason ??= reason;
+        clearTimeout(task.timer);
+        task.stopping = (async () => {
+            let confirmed = false;
+            try {
+                confirmed = await this.terminate(task);
+            } catch {
+                // Failure is evidence of uncertainty, never evidence of death.
+            }
+
+            task.cleanup = confirmed ? "confirmed" : "unconfirmed";
+            task.status = !confirmed
+                ? "cleanup-unconfirmed"
+                : task.failed
+                  ? "failed"
+                  : task.reason === "command exited"
+                    ? "exited"
+                    : "killed";
+            if (confirmed) {
+                task.endedAt = Date.now();
+                task.child?.stdout?.destroy();
+                task.child?.stderr?.destroy();
+                if (task.child?.connected) {
+                    task.child.disconnect();
+                }
+            }
+
+            this.evict();
+
+            return this.summary(task);
+        })();
+        const result = await task.stopping;
+        task.stopping = undefined;
+
+        return result;
+    }
+    async shutdown() {
+        this.closed = true;
+
+        return Promise.all([...this.tasks.keys()].map((id) => this.stop(id, "session cleanup")));
+    }
+}

package/extensions/background-tasks/index.ts

@@ -0,0 +1,262 @@
+import { createHash } from "node:crypto";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { decideCommand } from "../command-guard/core.mjs";
+import { LIMITS, TaskRunner, normalizeStart, preview, record } from "./core.mjs";
+
+function fingerprint(value: unknown): string {
+    return createHash("sha256").update(JSON.stringify(value)).digest("hex");
+}
+
+function result(value: unknown) {
+    return { content: [{ type: "text" as const, text: JSON.stringify(value) }], details: {} };
+}
+
+export default function registerBackgroundTasks(
+    pi: ExtensionAPI,
+    dependencies: {
+        runner?: Pick<TaskRunner, "closed" | "list" | "shutdown" | "start" | "get" | "stop">;
+        approvalMs?: number;
+    } = {},
+) {
+    let runner = dependencies.runner ?? new TaskRunner();
+    let generation = 0;
+    let active = false;
+    let pending = 0;
+    const approvals = new Set<string>();
+    let lifecycle = new AbortController();
+    const invalidate = () => {
+        generation += 1;
+        approvals.clear();
+        lifecycle.abort();
+        lifecycle = new AbortController();
+    };
+
+    let unsubscribe: (() => void) | undefined;
+    const subscribe = () => {
+        unsubscribe ??= pi.events.on("specpi:guard-policy-changed", invalidate);
+    };
+
+    subscribe();
+    const admission = (spec: any, hasUI: boolean) => {
+        let stateReplies = 0;
+        pi.events.emit("specpi:guard-state", {
+            reply() {
+                stateReplies += 1;
+            },
+        });
+        const replies: any[] = [];
+        pi.events.emit("specpi:background-admission", {
+            input: { command: spec.command },
+            cwd: spec.cwd,
+            shell: spec.dialect,
+            hasUI,
+            reply(value: unknown) {
+                replies.push(value);
+            },
+        });
+        if (stateReplies === 0 && replies.length === 0) {
+            const decision = decideCommand(spec.command, {
+                mode: "guard",
+                shell: spec.dialect,
+                cwd: spec.cwd,
+                platform: process.platform,
+                hasUI,
+                cache: false,
+            });
+
+            return { mode: "absent-guard-policy", generation: 0, action: decision.action, reason: decision.reason };
+        }
+
+        const policy = replies[0];
+        if (
+            stateReplies !== 1 ||
+            replies.length !== 1 ||
+            !["guard", "strict", "off", "locked"].includes(policy?.mode) ||
+            !Number.isSafeInteger(policy?.generation) ||
+            !["allow", "ask", "deny"].includes(policy?.action)
+        ) {
+            throw new Error("Background Guard policy is unavailable or ambiguous; start denied.");
+        }
+
+        return policy;
+    };
+
+    const cleanup = async (_event: unknown, ctx: any) => {
+        active = false;
+        invalidate();
+        const outcomes = await runner.shutdown();
+        const unconfirmed = outcomes.filter((task: any) => task.cleanup !== "confirmed");
+        if (unconfirmed.length) {
+            ctx.ui.notify(
+                `Background cleanup unconfirmed for ${unconfirmed.map((task: any) => task.id).join(", ")}. Processes may still be running. background_start is disabled in this runtime: retry background_stop for these IDs, then /reload after cleanup confirms. IDs do not survive runtime replacement; inspect any remaining processes manually.`,
+                "warning",
+            );
+        }
+    };
+
+    pi.on("session_shutdown", async (event, ctx) => {
+        await cleanup(event, ctx);
+        unsubscribe?.();
+        unsubscribe = undefined;
+    });
+    pi.on("session_start", async (event, ctx) => {
+        subscribe();
+        if (runner.list().length) {
+            await cleanup(event, ctx);
+        }
+
+        if (runner.list().some((task: any) => task.cleanup !== "confirmed")) {
+            return;
+        }
+
+        if (runner.closed) {
+            runner = dependencies.runner ?? new TaskRunner();
+        }
+
+        invalidate();
+        active = true;
+    });
+    pi.on("session_tree", async (event, ctx) => {
+        await cleanup(event, ctx);
+        if (!runner.list().some((task: any) => task.cleanup !== "confirmed")) {
+            runner = dependencies.runner ?? new TaskRunner();
+            active = true;
+        }
+    });
+
+    pi.registerTool({
+        name: "background_start",
+        label: "Start background task",
+        description:
+            "Start a session-owned noninteractive command after explicit approval. Uses /bin/sh on POSIX and system cmd.exe on Windows, not Pi Bash configuration. Four active tasks; 30 minute default timeout, eight hour maximum. Inherits the process environment. Not a sandbox or proof of service readiness.",
+        promptSnippet: "Start an approved long-running command while other work continues",
+        promptGuidelines: [
+            "Never use background_start to reroute a denied command. Use background_logs to observe progress and background_stop when a task is no longer needed. Spawn success is not readiness or completion evidence.",
+        ],
+        parameters: Type.Object(
+            {
+                command: Type.String({ minLength: 1, maxLength: LIMITS.command }),
+                cwd: Type.Optional(Type.String({ minLength: 1, maxLength: LIMITS.cwd })),
+                label: Type.Optional(Type.String({ minLength: 1, maxLength: LIMITS.label })),
+                timeoutSeconds: Type.Optional(Type.Integer({ minimum: 1, maximum: LIMITS.timeout })),
+            },
+            { additionalProperties: false },
+        ),
+        async execute(_id, input, signal, _update, ctx) {
+            if (!active || !ctx.hasUI || pending >= LIMITS.active) {
+                throw new Error(
+                    "Background starts require an active session, approval UI, and an available admission slot.",
+                );
+            }
+
+            pending += 1;
+            try {
+                const spec = normalizeStart(input, ctx.cwd);
+                const policy = admission(spec, ctx.hasUI);
+                if (policy.action === "deny") {
+                    throw new Error(preview(policy.reason));
+                }
+
+                const epoch = generation;
+                const key = fingerprint({ spec, policy, generation: epoch });
+                const abort = AbortSignal.any([lifecycle.signal, ...(signal ? [signal] : [])]);
+                abort.throwIfAborted();
+                if (!approvals.has(key)) {
+                    const controller = new AbortController();
+                    const promptSignal = AbortSignal.any([abort, controller.signal]);
+                    const timer = setTimeout(() => controller.abort(), dependencies.approvalMs ?? 600000);
+                    let cancel: () => void = () => {};
+
+                    try {
+                        const cancelled = new Promise<boolean>((resolve) => {
+                            cancel = () => resolve(false);
+                            promptSignal.addEventListener("abort", cancel, { once: true });
+                        });
+                        const confirmed = await Promise.race([
+                            ctx.ui.confirm(
+                                "Start background command for this session?",
+                                `Shell: ${preview(spec.shell)}\nCwd: ${preview(spec.cwd, LIMITS.cwd)}\nCommand: ${preview(spec.command, LIMITS.command)}\nTimeout: ${spec.timeoutSeconds}s\nGuard: ${preview(policy.mode)} — ${preview(policy.reason)}\nRuns with your permissions and inherited environment. Not a sandbox. Approves this exact execution for this session; output may enter conversation/provider retention.`,
+                                { signal: promptSignal },
+                            ),
+                            cancelled,
+                        ]);
+                        if (!confirmed || promptSignal.aborted) {
+                            throw new Error("Background command was not approved.");
+                        }
+                    } finally {
+                        clearTimeout(timer);
+                        promptSignal.removeEventListener("abort", cancel);
+                    }
+                }
+
+                abort.throwIfAborted();
+                const current = normalizeStart(input, ctx.cwd);
+                const currentPolicy = admission(current, ctx.hasUI);
+                if (
+                    !active ||
+                    !ctx.hasUI ||
+                    epoch !== generation ||
+                    currentPolicy.action === "deny" ||
+                    fingerprint({ spec: current, policy: currentPolicy, generation }) !== key
+                ) {
+                    throw new Error("Background input or policy changed during approval; start denied.");
+                }
+
+                while (approvals.size >= LIMITS.approvals && !approvals.has(key)) {
+                    approvals.delete(approvals.values().next().value!);
+                }
+
+                approvals.add(key);
+
+                return result(await runner.start(current, generation, abort));
+            } finally {
+                pending -= 1;
+            }
+        },
+    });
+    pi.registerTool({
+        name: "background_list",
+        label: "List background tasks",
+        description:
+            "List at most four active and 32 completed session tasks with bounded redacted previews and cleanup outcomes.",
+        parameters: Type.Object({}, { additionalProperties: false }),
+        async execute(_id, input) {
+            record(input, []);
+
+            return result(runner.list());
+        },
+    });
+    pi.registerTool({
+        name: "background_logs",
+        label: "Read background output",
+        description:
+            "Read untrusted memory-only task output after an absolute byte offset. At most 64 KiB raw output per read from a 256 KiB ring; stream markers count toward offsets. Terminal controls are escaped; truncation and lost bytes are explicit. Returned text may enter conversation/provider retention.",
+        parameters: Type.Object(
+            {
+                id: Type.String({ minLength: 1, maxLength: 36 }),
+                offset: Type.Optional(Type.Integer({ minimum: 0, maximum: Number.MAX_SAFE_INTEGER })),
+            },
+            { additionalProperties: false },
+        ),
+        async execute(_id, input, signal) {
+            record(input, ["id", "offset"]);
+            signal?.throwIfAborted();
+            const task = runner.get(input.id);
+
+            return result({ id: task.id, status: task.status, ...task.ring.read(input.offset) });
+        },
+    });
+    pi.registerTool({
+        name: "background_stop",
+        label: "Stop background task",
+        description:
+            "Idempotently request bounded termination of an owned task. Available under Guard locks. Reports confirmed or unconfirmed cleanup; escaped descendants are not contained.",
+        parameters: Type.Object({ id: Type.String({ minLength: 1, maxLength: 36 }) }, { additionalProperties: false }),
+        async execute(_id, input) {
+            record(input, ["id"]);
+
+            return result(await runner.stop(input.id));
+        },
+    });
+}

package/extensions/background-tasks/smoke.mjs

@@ -0,0 +1,33 @@
+import assert from "node:assert/strict";
+import { TaskRunner, OutputRing, normalizeStart, terminateOwned } from "./core.mjs";
+
+const ring = new OutputRing(32);
+ring.append("stdout", Buffer.from("x".repeat(100)));
+assert.equal(ring.read().lostBytes > 0, true);
+const runner = new TaskRunner({ terminate: (task) => terminateOwned(task, { graceMs: 20, observeMs: 2000 }) });
+try {
+    const spec = normalizeStart(
+        { command: `"${process.execPath}" -e "process.stdout.write('background-smoke');setInterval(()=>{},1000)"` },
+        process.cwd(),
+    );
+    const started = await runner.start(spec, 1);
+    assert.equal(started.status, "running");
+    const task = runner.get(started.id);
+    await new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            clearInterval(poll);
+            reject(new Error("Smoke output deadline exceeded"));
+        }, 10000);
+        const poll = setInterval(() => {
+            if (task.ring.read().output.includes("background-smoke")) {
+                clearInterval(poll);
+                clearTimeout(timer);
+                resolve();
+            }
+        }, 20);
+    });
+    assert.equal((await runner.stop(started.id)).cleanup, "confirmed");
+    console.log("BACKGROUND_TASKS_SMOKE=passed");
+} finally {
+    await runner.shutdown();
+}

package/extensions/background-tasks/supervisor.mjs

@@ -0,0 +1,33 @@
+// An owned root stays alive until the parent completes bounded tree cleanup.
+// Never load project modules or configuration here. Commands arrive once over IPC.
+import { spawn } from "node:child_process";
+
+let started = false;
+process.on("message", (message) => {
+    if (started || message?.operation !== "start") {
+        return;
+    }
+
+    started = true;
+    try {
+        const child = spawn(message.shell, message.args, {
+            cwd: message.cwd,
+            env: process.env,
+            stdio: ["ignore", "inherit", "inherit"],
+            windowsHide: true,
+            windowsVerbatimArguments: process.platform === "win32",
+        });
+        child.once("spawn", () => process.send?.({ event: "started" }));
+        child.once("error", () => process.send?.({ event: "failed" }));
+        child.once("exit", (code, signal) => process.send?.({ event: "exited", code, signal }));
+    } catch {
+        process.send?.({ event: "failed" });
+    }
+});
+// Keep the root alive during POSIX group grace so its identity cannot be reused.
+process.on("SIGTERM", () => {});
+process.on("disconnect", () => {
+    // A crashed parent cannot provide reliable tree cleanup. Do not persist a daemon.
+    process.exit(1);
+});
+process.send?.({ event: "ready" });

package/extensions/command-guard/core.d.mts

@@ -0,0 +1,12 @@
+// Narrow surface used by the background extension's scoped type gate, not the full Guard API.
+export declare function decideCommand(
+    command: unknown,
+    options?: {
+        mode?: "guard" | "strict" | "off" | "locked";
+        shell?: "bash" | "cmd" | "powershell";
+        cwd?: string;
+        platform?: NodeJS.Platform;
+        hasUI?: boolean;
+        cache?: boolean;
+    },
+): { action: "allow" | "ask" | "deny"; reason: string };

package/extensions/command-guard/index.ts

@@ -1,5 +1,6 @@
 import crypto from "node:crypto";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { clearAnalysisCache, decideCommand, decidePath } from "./core.mjs";
 import { boundedReason } from "./redact.mjs";
@@ -182,8 +183,54 @@ export default function registerCommandGuard(
         rules: {},
     };
     state.onModeChanged = () => pi.events?.emit("specpi:guard-policy-changed", { reason: "guard policy changed" });
+    let backgroundSubscription: (() => void) | undefined;
     let guardStateSubscription: (() => void) | undefined;
     const subscribeGuardState = () => {
+        if (!backgroundSubscription) {
+            backgroundSubscription = pi.events?.on?.("specpi:background-admission", (request: any) => {
+                if (typeof request?.reply !== "function") {
+                    return;
+                }
+
+                const unavailable = !state.ready || state.startupFailed || state.mode === "locked";
+                if (
+                    unavailable ||
+                    !validCommandInput(request.input) ||
+                    typeof request.cwd !== "string" ||
+                    !["bash", "cmd"].includes(request.shell)
+                ) {
+                    request.reply({
+                        mode: state.mode,
+                        generation: state.generation,
+                        action: "deny",
+                        reason: "Command guard is locked, unavailable, or received invalid background input.",
+                    });
+
+                    return;
+                }
+
+                const decision = decideCommand(request.input.command, {
+                    mode: state.mode,
+                    shell: request.shell,
+                    cwd: request.cwd,
+                    platform: process.platform,
+                    hasUI: request.hasUI === true,
+                    cache: false,
+                });
+                recordDecision(state, decision);
+                if (decision.action === "deny") {
+                    deny(state, decision.reason, decision.lockSession === true);
+                }
+
+                request.reply({
+                    mode: state.mode,
+                    generation: state.generation,
+                    action: decision.action,
+                    reason: decision.reason,
+                });
+            });
+        }
+
         if (!guardStateSubscription) {
             guardStateSubscription = pi.events?.on?.("specpi:guard-state", (request: any) => {
                 request.reply({ mode: state.ready && !state.startupFailed ? state.mode : undefined });
@@ -192,6 +239,24 @@ export default function registerCommandGuard(
     };
 
     subscribeGuardState();
+    const backgroundSource = fileURLToPath(new URL("../background-tasks/index.ts", import.meta.url));
+    const ownsBackgroundTool = (name: string): boolean => {
+        if (!["background_start", "background_list", "background_logs", "background_stop"].includes(name)) {
+            return false;
+        }
+
+        const matches = pi.getAllTools?.().filter((tool) => tool.name === name) ?? [];
+        const source = matches.length === 1 ? matches[0].sourceInfo?.path : undefined;
+        if (typeof source !== "string" || !path.isAbsolute(source)) {
+            return false;
+        }
+
+        const actual = path.resolve(source);
+        const expected = path.resolve(backgroundSource);
+
+        return process.platform === "win32" ? actual.toLowerCase() === expected.toLowerCase() : actual === expected;
+    };
+
     const delegationPolicy = (input: unknown): { fingerprint: string; summary: string } | undefined => {
         let replies = 0;
         let policy: any;
@@ -285,6 +350,8 @@ export default function registerCommandGuard(
     });
     pi.on("session_shutdown", (_event, ctx) => {
         reset();
+        backgroundSubscription?.();
+        backgroundSubscription = undefined;
         if (typeof guardStateSubscription === "function") {
             guardStateSubscription();
             guardStateSubscription = undefined;
@@ -443,6 +510,13 @@ export default function registerCommandGuard(
                 return deny(state, "Malformed tool call.");
             }
 
+            // Check Pi's current registration provenance, not a tool name or cached handshake.
+            // Genuine background tools validate again in execute; cleanup remains usable under a lock.
+            // A missing or replaced registration retains normal Strict/locked enforcement.
+            if (ownsBackgroundTool(name)) {
+                return;
+            }
+
             if (!state.ready || state.startupFailed) {
                 return deny(state, "Command guard is not initialized; protected tool calls are denied.");
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specpi",
-  "version": "0.18.1",
+  "version": "0.19.0",
   "description": "An explicit, privacy-conscious, self-improving harness for the Pi coding agent",
   "author": "Tanner Middleton",
   "repository": {

package/scripts/specpi.mjs

@@ -46,6 +46,8 @@ const browserRuntimeSourceDir = path.join(repoRoot, "browser-runtime");
 const browserRuntimeDir = path.join(stateDir, "browser-runtime");
 const browserRuntimeMarker = path.join(browserRuntimeDir, "specpi-runtime.json");
 const browserSmokePath = path.join(agentDir, "extensions", "browser", "smoke.mjs");
+const backgroundFiles = ["index.ts", "core.mjs", "supervisor.mjs", "smoke.mjs"];
+const backgroundRoot = path.join(agentDir, "extensions", "background-tasks");
 const capabilityRegistryPath = path.join(agentDir, "extensions", "tool-wishlist", "capabilities.json");
 const managedToolsDir = path.join(stateDir, "optional-tools");
 const managedBinDir = path.join(stateDir, "bin");
@@ -752,6 +754,11 @@ function desiredSettingsOperations() {
 
 function managedFiles(includeShell) {
     const files = [
+        ...backgroundFiles.map((name) => [
+            path.join(repoRoot, "extensions", "background-tasks", name),
+            path.join(backgroundRoot, name),
+            0o644,
+        ]),
         [path.join(repoRoot, "extensions", "spec.ts"), path.join(agentDir, "extensions", "spec.ts"), 0o644],
         [
             path.join(repoRoot, "extensions", "spec", "core.mjs"),
@@ -1134,6 +1141,7 @@ async function confirm(message, yes) {
 
 function assertSources() {
     const required = [
+        ...backgroundFiles.map((name) => `extensions/background-tasks/${name}`),
         "extensions/spec.ts",
         "extensions/spec/core.mjs",
         "extensions/ui-refresh/index.ts",
@@ -1937,6 +1945,29 @@ async function doctor() {
         }
     }
 
+    const backgroundIntegrity = backgroundFiles.every((name) => {
+        const target = path.join(backgroundRoot, name);
+        const record = manifest.files?.[target];
+
+        return record && fs.existsSync(target) && sha256(fs.readFileSync(target)) === record.installedHash;
+    });
+    if (!backgroundIntegrity || !commandGuardIntegrity) {
+        errors.push("Background task smoke skipped: installed background/Guard checksum integrity failed.");
+    } else {
+        const smoke = spawnSync(process.execPath, [path.join(backgroundRoot, "smoke.mjs")], {
+            cwd: agentDir,
+            encoding: "utf8",
+            timeout: 30000,
+            maxBuffer: 32768,
+            env: { ...process.env, NODE_OPTIONS: "", NODE_PATH: "" },
+        });
+        if (smoke.status === 0 && smoke.stdout.includes("BACKGROUND_TASKS_SMOKE=passed")) {
+            console.log("BACKGROUND_TASKS_SMOKE=passed");
+        } else {
+            errors.push("Installed background task smoke failed or timed out.");
+        }
+    }
+
     const runtimeStatus = browserRuntimeStatus();
     let browserSmoke;
     if (!runtimeStatus.installed) {