specpi 0.18.1 → 0.19.1

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.19.1 - 2026-09-08
+
+- Allow Pi's exact public Copilot catalog identification headers during delegation, fixing Copilot → Anthropic → Copilot switches that were incorrectly rejected as runtime provider overrides. Reconstruct headers independently in the child; retain runtime-auth, extension-provider and other header restrictions. Restart Pi after updating the harness.
+
+## 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,7 +49,7 @@ 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.1`.
 
 Delegation is enabled at startup. Use `/delegate off` to turn it off.
 
@@ -62,7 +63,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.1 fixes delegation when switching GitHub Copilot models in the same chat, including Luna → Opus → Luna. Update the harness and use **Restart Pi** to load the fix; this patch does not require a Chat 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, 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.
+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, unsupported model-specific headers, startup proxy configuration and mismatched safe model descriptors because those routes cannot be faithfully reconstructed. The sole model-header exception is the exact public Copilot catalog set: `User-Agent: GitHubCopilotChat/0.35.0`, `Editor-Version: vscode/1.107.0`, `Editor-Plugin-Version: copilot-chat/0.35.0`, and `Copilot-Integration-Id: vscode-chat`. Both parent and independently reconstructed child must have that entire set, with no extra keys, inherited headers or accessors; header presence must also match. No parent header object is copied or serialized. Changed catalog values require review before admission. 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.

package/docs/delegation/README.md

@@ -74,6 +74,6 @@ Cancellation revokes access and requests SDK abort. Slots remain held until SDK-
 
 Activation checks required public SDK capabilities, not an exact version allowlist. The installer retains its separate Pi 0.84.4 bootstrap pin. Restart after updating the runtime.
 
-Children use fresh Pi `ModelRuntime` instances with standard authentication/environment/models resolution and global transport/thinking settings. Project settings are not loaded. Parent model/thinking are explicit and checked through Pi's public APIs. Runtime-only authentication, selected extension-provider overrides, model headers, startup proxy configuration and mismatched model descriptors are rejected rather than silently approximated.
+Children use fresh Pi `ModelRuntime` instances with standard authentication/environment/models resolution and global transport/thinking settings. Project settings are not loaded. Parent model/thinking are explicit and checked through Pi's public APIs. Runtime-only authentication, selected extension-provider overrides, unsupported model headers, startup proxy configuration and mismatched model descriptors are rejected rather than silently approximated. Pi's exact public Copilot client-identification headers are supported when independently reconstructed in the child; all other model headers remain unsupported. The reviewed values and matching rules are listed in [the security model](../../SECURITY_MODEL.md).
 
 Parent hooks, ephemeral settings and session affinity are **not inherited**. Keep delegation off if they are required on every request. Stable provider identity cannot certify an unchanged remote service. Trusted extensions still share Pi's privileged process; this is a trusted-local-filesystem contract, not an OS sandbox. See [SECURITY_MODEL.md](../../SECURITY_MODEL.md) for the authoritative boundaries and [THIRD_PARTY.md](../../THIRD_PARTY.md) for dependency compatibility.

package/docs/delegation/protocol.md

@@ -17,8 +17,10 @@ fresh Pi `ModelRuntime`. The parent model and thinking level are passed explicit
 subject to Pi's clamping. Standard Pi authentication, environment and `models.json`
 resolution apply. Child transport/thinking budgets come from configured global settings;
 project settings are not loaded. Runtime-only authentication, selected extension-provider
-overrides, model-specific headers, startup proxy configuration and safe model-descriptor
-mismatches fail preflight. Parent request hooks,
+overrides, unsupported model-specific headers, startup proxy configuration and safe model-descriptor
+mismatches fail preflight. The exact public Copilot client-identification header set is
+permitted only when independently reconstructed in the child, as specified in the
+[security model](../../SECURITY_MODEL.md). Parent request hooks,
 ephemeral runtime settings, session affinity and ambient resources are not inherited.
 
 Command Guard is optional. Absent and Off states permit activation; an installed

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 = 10;
+const revision = 11;
 
 export async function withPiCompatibility(sdk, loadCompatibility) {
     if (typeof sdk.clampThinkingLevel === "function") {

package/extensions/delegation/provider.mjs

@@ -5,6 +5,14 @@ const MAX_CONTEXT_BYTES = 256 * 1024;
 const MAX_RUN_CONTEXT_BYTES = budgetLimits(MAX_BUDGET_MULTIPLIER).contextBytes;
 const MAX_RETAINED_RESPONSE_BYTES = budgetLimits(MAX_BUDGET_MULTIPLIER).retainedResponseBytes;
 const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
+// Public client identification from https://pi.dev/api/models/providers/github-copilot.
+// Keep this exception exact: other headers may contain credentials or routing overrides.
+const COPILOT_CATALOG_HEADERS = Object.freeze({
+    "User-Agent": "GitHubCopilotChat/0.35.0",
+    "Editor-Version": "vscode/1.107.0",
+    "Editor-Plugin-Version": "copilot-chat/0.35.0",
+    "Copilot-Integration-Id": "vscode-chat",
+});
 const MODEL_FIELDS = [
     "id",
     "provider",
@@ -62,7 +70,41 @@ function closed(value, keys) {
 
 function descriptor(model) {
     // Only public model behavior fields; never serialize a provider, headers, or credentials.
-    return JSON.parse(bounded(Object.fromEntries(MODEL_FIELDS.map((key) => [key, model[key]])), 16 * 1024));
+    return JSON.parse(
+        bounded(
+            {
+                ...Object.fromEntries(MODEL_FIELDS.map((key) => [key, model[key]])),
+                hasModelHeaders: model.headers !== undefined,
+            },
+            16 * 1024,
+        ),
+    );
+}
+
+function supportedModelHeaders(model) {
+    const headers = model.headers;
+    if (headers === undefined) {
+        return true;
+    }
+
+    if (model.provider !== "github-copilot" || !headers || typeof headers !== "object") {
+        return false;
+    }
+
+    try {
+        // Check names before touching values; never evaluate header getters or
+        // inspect arbitrary authentication headers. Retain no parent header data.
+        const keys = Reflect.ownKeys(headers);
+
+        return (
+            Object.getPrototypeOf(headers) === Object.prototype &&
+            keys.length === Object.keys(COPILOT_CATALOG_HEADERS).length &&
+            keys.every((key) => Object.hasOwn(COPILOT_CATALOG_HEADERS, key)) &&
+            keys.every((key) => Object.getOwnPropertyDescriptor(headers, key)?.value === COPILOT_CATALOG_HEADERS[key])
+        );
+    } catch {
+        return false;
+    }
 }
 
 function sameValue(left, right) {
@@ -314,7 +356,7 @@ export function createNativePiHost(ctx, { id, isCurrent, sdk, thinkingLevel } =
             !streaming &&
             (registry.getProviderAuthStatus(model.provider)?.source === "runtime" ||
                 registry.getRegisteredProviderIds().includes(model.provider) ||
-                model.headers !== undefined)
+                !supportedModelHeaders(model))
         ) {
             throw new DelegationError("Delegation cannot inherit this parent runtime provider override");
         }
@@ -351,6 +393,7 @@ export function createNativePiHost(ctx, { id, isCurrent, sdk, thinkingLevel } =
                 runtime.getError() ||
                 !runtime.getProvider(model.provider) ||
                 !childModel ||
+                !supportedModelHeaders(childModel) ||
                 !sameValue(descriptor(childModel), selected)
             ) {
                 throw new DelegationError(

package/package.json

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