specpi 0.18.0 → 0.19.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # 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.
+
+- SpecPi Chat 0.4.1 replaces the persistent Delegates panel with a compact live-only activity strip and opens workspace image links in the validated image viewer instead of the text editor. Chat is packaged separately; update the harness for the model-switch fix and Chat for the UI fixes.
+
 ## 0.18.0 - 2026-09-07
 
 - Start Command Guard off in RPC sessions, including new SpecPi Chat conversations. Explicit `/guard guard` and `/guard strict` still enable protection for the current session; the terminal startup chooser is unchanged.

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.0`.
+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.0 adds live delegate progress and worker Stop controls, plus compact tags for attached files. With SpecPi 0.18.0, new Chat sessions start with Guard off; use `/guard guard` or `/guard strict` to enable it. Update the harness and use **Restart Pi** to load these changes.
+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

@@ -35,7 +35,7 @@ not a new provider-disclosure boundary.
 
 Delegation is a native extension discovered through the ordinary Pi package and SpecPi lifecycle. Start `pi` normally; delegation is enabled by default at the first session start of each Pi process, including TUI, RPC, print and JSON modes, after settings, host and Guard checks. Startup launches no workers or model inference, but Pi-owned authentication/OAuth preparation may occur. The model-facing schema is present only while dispatch is enabled. It adds no launcher, separate host process, service or trust override. Parent Pi retains normal resource discovery, trust decisions and proxy policy. Delegation checks required public SDK capabilities, not exact version identifiers. Missing session/runtime/settings/thinking APIs prevent activation; session construction and every request still enforce the tool, model and resource policy. API presence is not proof of every future SDK behavior or a passing integration receipt. Normal installation's minimum Pi version and 0.84.4 bootstrap pin are separate contracts.
 
-Each worker is an SDK `createAgentSession` instance with in-memory session storage. Pi owns its model/tool loop. A fresh Pi `ModelRuntime` uses standard authentication, environment and `models.json` resolution. Child transport and thinking budgets come from configured global settings; project settings are not loaded. Parent model/thinking are explicit with Pi's supported-level clamping. SpecPi does not extract credentials, copy authentication state or inspect private runtime fields. Preflight rejects runtime-only authentication, selected extension-registered provider overrides, model-specific headers, startup proxy configuration and mismatched safe model descriptors because those routes cannot be faithfully reconstructed. These rejections leave parent configuration unchanged.
+Each worker is an SDK `createAgentSession` instance with in-memory session storage. Pi owns its model/tool loop. A fresh Pi `ModelRuntime` uses standard authentication, environment and `models.json` resolution, restoring Pi's persisted model catalogs with catalog network refresh disabled. Child transport and thinking budgets come from configured global settings; project settings are not loaded. Parent model/thinking are explicit with Pi's supported-level clamping. SpecPi does not extract credentials, copy authentication state or inspect private runtime fields. Preflight rejects runtime-only authentication, selected extension-registered provider overrides, model-specific headers, startup proxy configuration and mismatched safe model descriptors because those routes cannot be faithfully reconstructed. These rejections leave parent configuration unchanged.
 
 This is not full parent inference parity: parent request hooks, ephemeral runtime settings and session affinity are not automatically inherited. Keep delegation disabled if those inherited controls are required for every request. Children load no ambient extensions, skills, AGENTS files or parent transcript. Their only tools are selected-source list/read/literal-search; shell, write, arbitrary plugin, live-web and nested delegation tools are absent. Trusted parent extensions remain privileged in the same process. This is an application boundary, not an OS sandbox against malicious extensions.
 
@@ -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.
@@ -195,7 +209,7 @@ The sidebar uses Pi's documented JSONL RPC protocol. Pi owns provider authentica
 
 Chat allows up to 90 seconds for an initial read-only RPC readiness probe before sending normal requests. This accommodates the 30-second startup fallback in older installed Guard versions without extending later request deadlines. Dialogs arriving before readiness receive cancellation only, never an approval or mode selection; the sidebar explains the limitation and retains a notice after connection. An extension with an unbounded startup dialog can still prevent readiness. Chat times out with recovery guidance instead of bypassing that extension or changing the user's installed harness.
 
-The webview loads only packaged scripts/styles under a strict content security policy, forbids network resources, and renders model/tool/file text without interpreting embedded HTML. Images use validated data URLs under `img-src data:`; remote image URLs are never fetched by the webview. HTTP(S) links, including external image links, require a human click and pass through VS Code's external-link API. Clicked code references use a separate host action: paths are parsed, checked against the selected workspace, canonicalized, and restricted to regular non-sensitive files before VS Code opens the file and reveals a clamped line/range. Clicked workspace Markdown image references use the same path boundary and the image validator before a preview is returned. Arbitrary command and URI handlers are not executed. Raw paths preserve literal percent signs; Markdown link destinations and explicit local file URLs are decoded once before filesystem validation.
+The webview loads only packaged scripts/styles under a strict content security policy, forbids network resources, and renders model/tool/file text without interpreting embedded HTML. Images use validated data URLs under `img-src data:`; remote image URLs are never fetched by the webview. HTTP(S) links, including external image links, require a human click and pass through VS Code's external-link API. Clicked code references use a separate host action: paths are parsed, checked against the selected workspace, canonicalized, and restricted to regular non-sensitive files before VS Code opens the file and reveals a clamped line/range. Clicked workspace Markdown image references, and ordinary file links or inline references ending in PNG, JPEG, GIF or WebP extensions, use the same path boundary and the image validator before a preview is returned. The extension suffix chooses the viewer, not whether the file is safe or valid. Arbitrary command and URI handlers are not executed. Raw paths preserve literal percent signs; Markdown link destinations and explicit local file URLs are decoded once before filesystem validation.
 
 Text/code context requires an explicit file/selection action, is size-bounded, rejects binary and known sensitive paths, and checks canonical workspace containment. Workspace file suggestions enumerate a bounded set of names; choosing a suggestion invokes the same attachment validation before reading contents. Dropped workspace URIs are validated independently of their browser representation. Native image selection, clipboard images, and dropped image files are explicit attachment actions and may supply images from outside the selected workspace; filesystem image sources still require ordinary files and pass sensitive-path checks. Pi-state names such as `auth`, `trust`, `sessions`, `missions`, and `history` are reserved inside `.pi`, Chat-owned storage, and the configured Pi agent directory (including its canonical target), not arbitrary source directories. Global credential/key patterns remain blocked, including `auth.json`. Relative `PI_CODING_AGENT_DIR` overrides retain conservative name blocking because they resolve in the child workspace; use an absolute path or `~/…` to obtain directory-scoped filtering. These filename checks and format validators are not content-based secret detectors. Manually typed messages, ordinary files, and images may contain sensitive content, and the extension does not promise image metadata removal. Prompts and attachments are sent to the provider selected in Pi when the user sends them.
 
@@ -209,7 +223,7 @@ Pi persists chats, including sent image blocks, in a workspace-specific director
 
 Conversation edits select entries from the active Pi tree, revalidate the selection before mutation, and fork before the chosen user prompt. Exact original text and validated image blocks are captured before forking because Pi's fork response returns text only. The original conversation is retained, restored drafts require another send action, and conversation forks/clones do not restore or checkpoint workspace files. Actions are scoped to the active workspace, connection, and session revision. Export opens an unsaved Markdown document and Copy Conversation writes the visible Markdown to the OS clipboard only on explicit request. Both omit image bytes and represent images as placeholders; they do not reconstruct truncated or hidden history. Usage displays report Pi measurements, preserving unavailable values rather than inventing totals. The separate provider Limits row projects bounded strings from the known Codex Usage and pi-usage status keys, strips terminal/control sequences, and inserts text only. It does not parse numeric quotas, combine budgets with conversation cost, read provider credentials or usage-cache files, or add provider requests. Reports stay with their live connection and are cleared on disconnect, exit, and reconnect; refreshing and cache age remain upstream plugin responsibilities. Opening the details has no RPC or provider side effect. Existing `/usage` notifications and exact confirmation dialogs continue through the normal UI protocol; no automatic reset consumption or terminal-footer emulation is added.
 
-The Delegates panel consumes the known `specpi-delegation-v1` RPC widget key, with one versioned JSON record of at most 32 KiB and eight projected worker rows. Public identities, shortened task labels, states, elapsed times, call counts and code-owned diagnostics are text-only; snapshots, full prompts, raw provider errors and child transcripts are not sent through the live widget. A single extension-side timer samples existing counters while slots are occupied; it makes no provider or source requests and is disposed on shutdown/rebinding. Invalidated-generation jobs contribute only to occupied-slot counts, not cross-session task labels; replaced same-generation stopping jobs remain visible until settlement. Chat clears live state on disconnect, exit and runtime session replacement and keeps at most 32 connection-local completion summaries for refresh; it adds no child journal or webview persistence. Existing delegate tool receipts are projected into readable advisory reports without changing their model/session content. Stop actions require a trusted workspace, foreground conversation, matching context and an observed running/queued batch/job/attempt. Pi rechecks that exact attempt before its human command cancels it. Worker Stop does not submit draft text/images, clear parent queues, approve tools, change quotas or claim remote termination. The widget is an integration contract with trusted installed extensions, not protection against a malicious extension in Pi's process.
+The delegate activity strip consumes the known `specpi-delegation-v1` RPC widget key, with one versioned JSON record of at most 32 KiB and eight projected worker rows. It appears only while workers run or retain unsettled requests, starts collapsed, and excludes settled results; reports remain in the conversation. Queued jobs are shown only alongside live work. Unsettled requests without current-generation job metadata show only a stopping count, never prior task labels. Public identities, shortened task labels, states, elapsed times, call counts and code-owned diagnostics are text-only; snapshots, full prompts, raw provider errors and child transcripts are not sent through the live widget. A single extension-side timer samples existing counters while slots are occupied; it makes no provider or source requests and is disposed on shutdown/rebinding. Invalidated-generation jobs contribute only to occupied-slot counts, not cross-session task labels; replaced same-generation stopping jobs remain visible until settlement. Chat clears live state on disconnect, exit and runtime session replacement and keeps at most 32 connection-local completion summaries for refresh; it adds no child journal or webview persistence. Existing delegate tool receipts are projected into readable advisory reports without changing their model/session content. Stop actions require a trusted workspace, foreground conversation, matching context and an observed running/queued batch/job/attempt. Pi rechecks that exact attempt before its human command cancels it. Worker Stop does not submit draft text/images, clear parent queues, approve tools, change quotas or claim remote termination. The widget is an integration contract with trusted installed extensions, not protection against a malicious extension in Pi's process.
 
 Native change review reads VS Code's Git API, validates selected workspace paths, and opens the corresponding working-tree or staged view through the built-in diff/editor actions. It does not execute a shell command, stage, commit, discard, or restore files. Git integration availability and the filesystem race boundary still apply. The sidebar coordinator keeps independent Pi connections for explicitly opened conversations. Switching conversations or folders only changes the selected view. Stop and Disconnect target the selected process; extension-host shutdown stops all owned processes. User-initiated parallel conversations share their workspace files and are not isolated worktrees. Branching uses Pi's pre-runtime `--fork` to copy into a new owned session before extensions can write, then performs any active-branch or prompt selection there; the original process and session remain unchanged.
 

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/extensions/delegation/native.mjs

@@ -7,7 +7,7 @@ import { DelegationError } from "./errors.mjs";
 import { createTimeoutStore } from "./settings.mjs";
 
 const stateKey = Symbol.for("specpi.delegation.native.v1");
-const revision = 9;
+const revision = 10;
 
 export async function withPiCompatibility(sdk, loadCompatibility) {
     if (typeof sdk.clampThinkingLevel === "function") {

package/extensions/delegation/provider.mjs

@@ -325,7 +325,8 @@ export function createNativePiHost(ctx, { id, isCurrent, sdk, thinkingLevel } =
         check();
         initialization ??= (async () => {
             // Pi owns normal configuration and credential access. No credential object is
-            // requested, copied, or exposed. Static catalogs avoid refresh I/O.
+            // requested, copied, or exposed. Restore Pi's persisted catalogs without
+            // network refresh; skipping initialization also skips cached model overlays.
             const configured = sdk.SettingsManager.create(ctx.cwd, undefined, { projectTrusted: false });
             if (
                 configured.getGlobalSettings().httpProxy ||
@@ -343,7 +344,7 @@ export function createNativePiHost(ctx, { id, isCurrent, sdk, thinkingLevel } =
                 compaction: { enabled: false },
                 retry: { enabled: false, maxRetries: 0, provider: { maxRetries: 0 } },
             };
-            const runtime = await sdk.ModelRuntime.create({ allowModelNetwork: false, refreshOnCreate: false });
+            const runtime = await sdk.ModelRuntime.create({ allowModelNetwork: false });
             check();
             const childModel = runtime.getModel(model.provider, model.id);
             if (

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specpi",
-  "version": "0.18.0",
+  "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) {