pi-background-tasks 0.9.0 → 1.0.4

package/README.md

@@ -1,533 +1,325 @@
-# pi-background-tasks
-
-Claude-Code-like explicit background shell task manager for [Pi](https://pi.dev/).
-
-This package adds named, tracked background shell jobs with durable output files, bounded log reads, kill/timeout safety, task-owned context-window/token/tool-use/model telemetry, explicit Pi-agent telemetry wrapping for tasks marked as agents, a focused footer-dock task manager, `/tasks` fallback UI, and completion notifications that can wake the agent when LLM-launched work finishes. It also ships Fusion: a direct child-Pi five-call synthesis workflow exposed as `/fusion`, `/fusion-models`, and the always-active `fusion_brainstorm` and `fusion_validate` tools. A terminal task status is published only after trailing wrapped-agent telemetry is consumed and final output plus terminal metadata have completed their durability writes.
-
-## Install
-
-From npm after publish:
-
-```bash
-pi install npm:pi-background-tasks@0.9.0
-```
-
-From git after pushing this package to its standalone repository and tagging:
-
-```bash
-pi install git:github.com/ismailsaleekh/pi-background-tasks@v0.9.0
-```
-
-For project-local install:
-
-```bash
-pi install -l npm:pi-background-tasks@0.9.0
-```
-
-## Commands
-
-- `/bg [--agent] [--name "Task name"] <command>` — start a named tracked background shell command. Use `--agent` only when the command launches an LLM/agent.
-- `/jobs` — list running and recent completed/failed/killed tasks.
-- `/logs <id> [maxBytes]` — show bounded tail output and full output path.
-- `/kill <id>` — stop a running task.
-- `/tasks` or `/bg-tasks` — fallback command to open the task manager UI.
-- `/bg-clear` — clear finished background-task footer notices.
-- `/bg-update` — print update instructions when a newer published version exists (instruct-only; never self-installs).
-- `/fusion <prompt>` — run three candidate child Pi final-text calls, one blind evaluator, and one merger, then append the merged answer directly as a visible `fusion-result` custom message without asking the parent model to rewrite it. Running `/fusion` without arguments opens a multiline editor in UI-capable modes; cancelling the editor does not spawn children.
-- `/fusion-models` — TUI-only five-slot global model selector (`Candidate 1`, `Candidate 2`, `Candidate 3`, `Evaluator`, `Merger`). It supports duplicate selections, `$current` defaults, slash-containing model ids, atomic saves to `fusion-models.json`, and rejects non-TUI modes immediately.
-
-## Footer dock UX
-
-When tasks are active or unseen completions/failures exist, Pi shows a compact footer status:
-
-```text
-bg 2 running · Shift↓
-bg 1 running · 1 failed · Shift↓ · /bg-clear
-bg 2 done · Shift↓ · /bg-clear
-```
-
-Press `Shift+Down` to open the focused bottom dock. Arrow keys are captured only while the dock is focused. Each task row shows the latest context-window usage reported by that specific background task, for example `ctx 21.0%/200k`; tasks that do not report their own context show `ctx —` rather than the parent Pi session's usage. Background Pi-agent tasks also surface the LLM model they ran (`model gpt-5.5` in the compact row, fully-qualified such as `openai-codex/gpt-5.5` in the detail view), cumulative token usage (`tok 1.6k`), and tool-use counts (`tools 2/1 failed`) in the dock and detail view; missing model/token/tool telemetry is omitted in rows and shown as “not reported by this background task” in details. When a background command is explicitly marked as an agent and invokes a print/json child agent such as `pi -p ...` through the normal shell command name, the extension wraps that child Pi process with `--mode json`, parses real assistant usage/tool execution events, and emits task-owned telemetry automatically — including the model reported by the child assistant turns.
+<div align="center">
+  <img src="logo.png" alt="pi-background-tasks logo: a futuristic dispatcher coordinating parallel work nodes into a completed result" width="144" height="144">
 
-### Agent activity transcript
-
-For those wrapped background Pi agents, the task output file and the dock's detail **Output tail** show a live, human-readable transcript of what the agent is actually doing — assistant messages, `→ tool args` calls, `… reasoning`, and `✗ tool failed` errors — as the agent loop runs. The machine telemetry (context/token/tool/model) is parsed out of the child stream and surfaced only as the metrics above and in `bg_status`/metadata, so the focused window reflects the agent's real activity rather than its raw instrumentation JSON. Child stderr is passed through to the transcript verbatim. Non-agent tasks and agent commands that cannot be wrapped (for example a path-qualified `pi`) keep streaming their raw stdout/stderr unchanged.
-
-Finished-task badges intentionally remain visible until acknowledged. The reliable clear path is `/bg-clear`, which works in every terminal and clears finished background-task footer notices without opening the dock. `Ctrl+Alt+C` is still registered as an optional terminal-dependent fallback shortcut, but the footer advertises `/bg-clear` because some macOS terminals do not transmit `Ctrl+Alt+C` distinctly.
-
-Dock controls:
-
-| Key | Action |
-|---|---|
-| `Shift+Down` | Open focused background-task dock |
-| `/bg-clear` | Clear finished-task footer notices from the main UI |
-| `Ctrl+Alt+C` | Optional terminal-dependent shortcut for `/bg-clear` |
-| `↑` / `↓` | Select task (list) · scroll the output tail (detail) |
-| `PageUp` / `PageDown` | Page the task list (list) · page the output tail (detail) |
-| `Enter` / `→` | Inspect logs/details |
-| `←` | Return from details to list |
-| `h` | Toggle recent history |
-| `k` | Stop selected running task |
-| `a` / `K` | Stop all running tasks, with confirmation |
-| `r` | Refresh detail tail |
-| `R` | Rerun selected command |
-| `c` | Show copyable output path |
-| `x` / `Esc` / `q` | Close dock |
-| `/bg-update` | Print update instructions when a newer version is published |
+# pi-background-tasks
 
-In the detail view the **Output tail** is scrollable: `↑`/`↓` and `PageUp`/`PageDown` move through the loaded output (a generous bounded window, not just the last lines). Scrolling up pauses the live tail and freezes the view so it stays stable as new output arrives; the status line shows your position (e.g. `lines 46–57 of 60`). Scrolling back to the bottom (or pressing `r`) resumes live tailing.
+**Keep Pi moving while long jobs, delegated investigations, and fixed-purpose multi-model Fusion work run in the background.**
 
-### Update-available notice
+[![npm](https://img.shields.io/npm/v/pi-background-tasks?label=npm)](https://www.npmjs.com/package/pi-background-tasks)
+[![Pi extension](https://img.shields.io/badge/Pi-extension-19c7d4)](https://github.com/earendil-works/pi-coding-agent)
+[![Node](https://img.shields.io/badge/node-%3E%3D22.19-1f8f4d)](package.json)
+[![License](https://img.shields.io/badge/license-ISC-f5a623)](LICENSE)
 
-When a newer version of `pi-background-tasks` has been published to npm, the footer appends a compact, instruct-only segment after the entry hint:
+</div>
 
-```text
-bg 1 running · 1 failed · Shift↓ · /bg-clear · ⬆ v0.7.0 /bg-update
-```
+`pi-background-tasks` adds background jobs, delegated agents, and multi-model Fusion for Pi:
 
-When no tasks are active, the notice still appears on its own (`bg ⬆ v0.7.0 /bg-update`) so the update hint is visible. The segment is rendered only when a strictly newer published version exists; `/bg-update` prints the npm and git update commands and never installs or self-updates.
+- **Run long work without blocking**: start named shell jobs, keep talking to Pi, and get durable completion notifications when they finish.
+- **Delegate context-aware investigation**: launch one route-pinned, inspect-only child Pi agent seeded with a frozen projection of the current conversation, then retrieve a hash-verified result.
+- **Combine model perspectives through fixed-purpose Fusion**: run three candidate children, blind evaluation, optional bounded evaluator repair, and merger for reasoning, investigation, targeted URL research, or validation review.
 
-The lookup runs at most once per session on `session_start`, is time-boxed, and is fully offline-safe: it never blocks or errors the footer/session, and on an offline or failed lookup it simply renders no segment (it never pins a misleading version). The check is skipped entirely when `PI_OFFLINE=1`, and can be disabled explicitly with `PI_BG_DISABLE_UPDATE_CHECK=1`. Set `PI_BG_REGISTRY_URL` to point the check at a registry mirror instead of `https://registry.npmjs.org`.
+<p align="center">
+  <img src="docs/assets/architecture.svg" alt="Architecture diagram showing Pi session, background task registry, delegated child agent, and Fusion candidate/evaluator/merger flow" width="760">
+</p>
 
-## LLM tools
+<!-- pi-docs:begin name="readme-package-facts" generator="scripts/docs/generate.mjs" -->
+| Fact | Value |
+| --- | --- |
+| Package | `pi-background-tasks` |
+| Version | `1.0.4` |
+| Node engine | `>=22.19.0` |
+| Pi entrypoint | `./extensions/background-tasks.ts` |
+| Package image | [logo.png](https://raw.githubusercontent.com/ismailsaleekh/pi-background-tasks/main/logo.png) |
+<!-- pi-docs:end name="readme-package-facts" -->
 
-- `bg_run` — start named long-running commands without blocking the conversation.
-- `bg_delegate` — launch one background Pi agent seeded with a frozen projection of the current conversation, then return a launch receipt immediately. See [Delegated background agents](#delegated-background-agents).
-- `bg_result` — retrieve a `bg_delegate` answer, hash-verified before it is returned.
-- `bg_run_pi_attested` — opt-in structured direct-spawn Pi agent task that emits a strict local attestation sidecar after successful completion.
-- `bg_status` — inspect one task or all recent tasks.
-- `bg_logs` — read bounded task output.
-- `bg_kill` — stop a running task.
-- `fusion_validate({prompt})` — always-active tool that runs the same five-model Fusion workflow as a validation review of work that was just completed, and returns the merged prose review. Its closed public schema has exactly one parameter, `prompt`; **it takes no `capability` argument**, and a caller-supplied `capability` is rejected loudly rather than ignored. Candidate reviewers always run with the read-only `inspect` capability, because a reasoning-only reviewer cannot read the code it is judging; the evaluator and merger remain no-tools by stage policy. Findings are classified `critical`, `high`, or `minor`, each with a file/symbol location, the evidence the reviewer actually read, and why it matters. A review with no findings must state what was verified rather than returning an unexplained pass. See [Validation workflow](#validation-workflow).
-- `fusion_brainstorm({prompt, capability?})` — always-active tool that runs the Fusion workflow and returns the exact merged text as the tool result for the parent agent to consume, with the exact Pi `Usage` shape attached when the host supports tool-result usage: token fields plus complete `cost.input`, `cost.output`, `cost.cacheRead`, `cost.cacheWrite`, and `cost.total`. Calling it as `fusion_brainstorm({prompt})` uses the default `reason` capability: no tools and byte-identical child argv/prompt behaviour to the previous release. The optional `capability` accepts only `"reason"`, `"inspect"`, or `"research"`; `inspect` gives candidate children read-only repository inspection tools, and `research` adds the package-owned `fusion_web_fetch` tool for targeted public URL fetches. The evaluator and merger remain no-tools by stage policy. Its closed public schema has one required parameter, `prompt`, plus optional `capability`; extra keys are rejected. It has no eligibility, quota, routine, or justification gate. Tool context capture excludes the current assistant tool-call leaf when Pi is executing that `fusion_brainstorm` call, so the nested children do not see the in-progress tool call or sibling calls. Children receive the documented conversation projection described under [Conversation context policy](#conversation-context-policy): visible user/assistant text verbatim, with thinking and tool payloads replaced by explicit hash-accounted omission receipts. Because the prompt is composed by the parent agent, it is treated as authoritative and self-contained.
+<!-- pi-docs:begin name="readme-public-surfaces" generator="scripts/docs/generate.mjs" -->
+| Surface kind | Count |
+| --- | --- |
+| command | 10 |
+| tool | 11 |
+| shortcut | 2 |
+| renderer | 2 |
+| eventbus | 1 |
+| workflow | 4 |
 
-`bg_run` requires a concise `name` for the footer dock, the shell `command`, and required `isAgent: boolean`. Set `isAgent: true` only when the background task launches an LLM/agent process (for example `pi -p ...` or `pi --mode json ...`); set `isAgent: false` for scripts, tests, dev servers, sleeps, and ordinary shell commands. It defaults both `notifyOnCompletion` and `triggerOnCompletion` to `true`. With those defaults, `bg_run` returns immediately, the agent continues only independent useful work or ends its current turn instead of sleeping or polling, and a durable `background-task-notification` for completed, failed, or killed state automatically starts a follow-up turn. The launch receipt states the effective notification/wake behavior explicitly. `bg_status` and `bg_logs` remain available for user-requested inspection, deliberately disabled completion delivery, concrete hang diagnosis, or reading output after the terminal event; they are not waiting primitives, and the terminal notification does not need status reconfirmation. Setting `triggerOnCompletion: false` keeps the notification but prevents it from starting an agent turn. Setting `notifyOnCompletion: false` suppresses both notification and wake-up even if `triggerOnCompletion` is true.
+Public commands: `/bg`, `/bg-clear`, `/bg-tasks`, `/bg-update`, `/fusion`, `/fusion-models`, `/jobs`, `/kill`, `/logs`, `/tasks`.
 
-Tasks marked with `isAgent: true` that launch print/json child Pi agents through the normal shell command name are telemetry-wrapped; set `PI_BG_DISABLE_PI_TELEMETRY=1` only when raw Pi stdout is required. The task snapshot and metadata expose `isAgent`, `contextUsage` (latest reported child assistant turn), cumulative `tokenUsage` (`input`, `output`, `cacheRead`, `cacheWrite`, `totalTokens`), cumulative `toolUsage` (`total`, `failed`, `byName`), and `model` (the LLM identifier reported by the child assistant turns, preferring the fully-qualified `provider/model` form) when reported by the child task. User-launched `/bg` jobs are display-only by default unless `--agent` is provided; UI reruns preserve the original task's `isAgent` value.
+Public tools: `bg_delegate`, `bg_kill`, `bg_logs`, `bg_result`, `bg_run`, `bg_run_pi_attested`, `bg_status`, `fusion_investigate`, `fusion_reason`, `fusion_research`, `fusion_validate`.
 
-`bg_run_pi_attested` is separate from `bg_run` and never accepts a shell command. It takes structured `provider`, `model`, `prompt`, optional literal extra Pi argv, and a relative `reportPath`; launches exactly one direct `pi --mode json` child; records raw Pi JSON events, separate stderr, exact argv/cwd, prompt/report hashes, observed Pi session/provider/model, and `ModelRegistry.isUsingOAuth` credential class. It forbids direct API-key/auth-file launch arguments and emits no partial attestation: failures remain ordinary failed tasks with no sidecar.
+Full owner map and generated contracts live in [docs/INDEX.md](docs/INDEX.md).
+<!-- pi-docs:end name="readme-public-surfaces" -->
 
 
-## Delegated background agents
 
-`bg_delegate` fills the gap between `bg_run` (a background agent with a **fresh,
-empty** context) and `fusion_brainstorm` (your current context, but synchronous
-and five-model). It is one agent, one prompt, seeded with the current session's
-context, non-blocking. `bg_result` retrieves its answer safely. They ship
-together: a delegate without a safe retrieval path could not return its work.
 
-```text
-bg_delegate({ name, prompt })              → launch receipt, immediately
-  … the parent keeps working; the terminal notification wakes it …
-bg_result({ taskId })                      → hash-verified answer
-```
+## Why use it?
 
-### Context seeding
-
-The child does **not** share the parent's live session. The parent conversation
-is projected with the same frozen `visible-conversation-ledger-v2` transform
-Fusion uses (see [Conversation context policy](#conversation-context-policy)),
-frozen as an immutable seed, and the child is given its **own** `--session-id`
-and a task-owned `--session-dir`. Conceptually it has your context; physically it
-can never open or mutate the parent session.
-
-| Content | Disposition |
+| You want to... | Use this package because... |
 |---|---|
-| User text | included verbatim, never clipped |
-| Assistant text | included verbatim, never clipped |
-| User image blocks | marker only, never raw bytes |
-| Assistant thinking | excluded; recorded as a hash-accounted omission receipt |
-| Tool-call arguments | excluded; recorded as a hash-accounted omission receipt |
-| Tool-result payloads | excluded; recorded as a hash-accounted omission receipt |
-| The in-flight `bg_delegate` call and its sibling calls | scope-excluded from the branch |
-
-The assistant message carrying the in-flight call is excluded as a whole, so when
-several `bg_delegate` calls share one assistant message **every** sibling call is
-excluded for **every** child: two delegates launched together receive identical
-projected history and neither can observe the other's arguments.
-
-The seed is canonical-JSON, SHA-256'd, and persisted. The persisted bytes are the
-exact bytes the child reads, and the child re-verifies that hash **before its
-first model call**. Repeated construction from the same session is
-byte-identical.
-
-**Documented limitation:** facts that exist only inside omitted parent tool
-output are **not** available to the child. The child is told this explicitly and
-instructed to say so plainly rather than guess. Restate any such finding in the
-`prompt`.
-
-### Route pinning
-
-The route is pinned at launch — by default the parent's current effective
-provider/model, or an explicit `route {provider, model}`. It is **never**
-substituted, never falls back, and is never retried on a different route. An
-unavailable route or one with no declared context window is a typed refusal
-before anything is created. The child additionally asserts that every assistant
-message it produced came from the pinned route; a mismatch prevents the run from
-committing an answer at all.
-
-### Inspect-only capability boundary
-
-v1 supports exactly one capability, `inspect`. The child is launched with
-`--tools read,grep,find,ls,delegate_read_artifact`, `--no-builtin-tools`, an
-explicit `--exclude-tools` denylist, and no ambient extensions, skills, prompt
-templates, themes, or context files. **The boundary is enforced by argv and the
-child's tool registry, not by prompt text.** There is no shell, no network, no
-edit/write, no recursive delegation, and no Fusion from the child. Writable
-profiles are deliberately out of scope.
-
-### Budgets, spilling, and limits
-
-Admission is checked **before** the child process, the child session, or the
-artifact directory exists, so a refusal leaves **zero** children and **zero**
-artifacts. Inside the child, every model call is measured before dispatch; a call
-that would exceed the pinned route's allowance is refused and the run terminates
-with a typed `provider_context_budget_exhausted`.
-
-A tool result larger than the per-result transcript cap is written **in full** to
-a hashed artifact and replaced in the transcript by an explicit receipt naming
-the artifact, its exact byte count, its SHA-256, and how to read a bounded range.
-The raw payload never enters the transcript and **nothing is truncated**. The
-bounded `delegate_read_artifact` tool returns exactly the requested range or
-fails; a request past end-of-file is refused rather than silently shortened.
-Turn, tool-call, aggregate-output, and wall-clock limits are enforced and
-reported.
-
-### Retrieving the answer
-
-The child commits exactly one self-contained result package by temp-write,
-`fsync`, rename, directory `fsync`. **The rename is the commit point**: a package
-present under its final name is complete, and its absence means no answer was
-accepted — whatever the process exit code was. A child that exits `0` without
-committing is a typed `child_exited_without_commit`, never a silent empty
-success. A run that degraded anything latches terminal state and **cannot**
-commit a success package, so a hash-valid answer can never be built on silently
-mutilated context.
-
-`bg_result` verifies the package identity, seed hash, route, every per-block
-SHA-256, and the aggregate SHA-256 before returning a single byte, and returns
-bytes from the buffer it verified. A running task returns a typed *not ready*
-result and **never blocks or polls**. An answer over the inline cap degrades to
-an artifact reference **explicitly**; requesting `delivery:"inline"` for it is a
-typed `result_too_large_for_inline` failure naming the artifact. It is **never**
-truncated to fit. `autoDeliver` (`never` | `when_small` | `always`) defaults to
-`never`: completion notifications carry metadata, and the answer is fetched
-deliberately with `bg_result`.
-
-### Failure taxonomy
-
-Every delegate failure is typed and states what happened, what was preserved, and
-what the operator can do. Admission codes
-(`delegate_hook_contract_unsupported`, `delegate_isolation_unsupported`,
-`route_unresolved`, `route_capacity_unknown`, `seed_projection_failed`,
-`seed_budget_exceeded`, `seed_persist_failed`, `invalid_arguments`) always report
-`childCreated: false`. Execution and integrity codes include `child_spawn_failed`,
-`child_timeout`, `child_cancelled`, `child_turn_limit`, `child_tool_call_limit`,
-`child_exited_without_commit`, `provider_context_budget_exhausted`,
-`aggregate_tool_output_cap`, `child_result_invalid`,
-`child_result_encoding_invalid`, `route_attestation_missing`, `route_mismatch`,
-`seed_hash_mismatch`, `answer_hash_mismatch`, `artifact_spill_failed`, and
-`artifact_read_failed`. Retrieval states are `result_not_ready`,
-`result_unavailable`, `result_too_large_for_inline`, and `task_unknown`.
-
-Usage that the provider did not report is recorded as explicitly `unavailable`,
-never as zero.
-
-### Proven Pi hook contract
-
-The child-side guard depends on runtime Pi behaviour, which is **proven by
-execution** rather than read from type declarations. The
-`npm run test:hook-contract` gate drives a real Pi agent loop and records what it
-observed. On Pi 0.83 it establishes that `context` fires once before every model
-call in extension load order and that returned messages reach the provider; that
-**throwing** from a `context` handler does **not** block the call (Pi catches it
-and dispatches anyway); that `ctx.abort()` does not skip the provider call site
-but hands it an already-aborted signal and terminates the run; and that
-`tool_result` fires before the result enters the transcript, chains in load order,
-and preserves tool-call id, role, and error flag across replacement.
-
-Because neither a throw nor an abort is a hard admission gate on its own, the
-guard uses abort as the barrier **and** removes the oversized content from the
-outgoing message set, so the request cannot carry it even if a provider ignored
-the aborted signal. If a Pi build cannot provide the required guarantees,
-`bg_delegate` refuses to spawn with a typed
-`delegate_hook_contract_unsupported`; the guard is never weakened to fit.
-
-Delegate artifacts are written under:
-
-```text
-.pi/delegate/<session-id>-<pid>/<task-id>/
-```
+| Start a dev server, watch build, migration dry run, or long check | `bg_run` and `/bg` return immediately, write durable output files, show a footer dock, and notify on terminal state. |
+| Let Pi keep working instead of sleeping or polling | Default `bg_run` completion delivery sends a durable terminal notification and can wake a follow-up turn. |
+| Ask a second agent to inspect the repo with the current conversation as context | `bg_delegate` starts one isolated child with read/search/list tools only; `bg_result` verifies the committed result before returning it. |
+| Compare model perspectives without exposing arbitrary parent context | Fusion children receive only the workflow input and fixed tool policy; no silent route substitution or fallback is used on delegate/Fusion paths. |
+| Produce local evidence for a direct Pi run | `bg_run_pi_attested` records local same-user-writable artifacts and hashes after a successful structured child Pi task. |
 
-Each run contains `seed.json`, `child-prompt.txt` (the exact bytes handed to the
-child over stdin, never a shell or positional argument),
-`context-omission-ledger.json`, `budget-plan.json`, `manifest.json`, the
-task-owned `child-session/`, any `spill/` artifacts, `result.json` once the child
-commits, and `outcome.json` once the parent adjudicates the run.
+## Install
 
-`result.json` is written by the **child** and `outcome.json` by the **parent**, so
-neither writer can claim a state it did not observe. `manifest.state` records only
-what the parent knew at launch and is never used to decide success.
+Version information comes from [`package.json`](package.json). Use npm `@latest` for normal installs; use git `main` only when you intentionally want the current repository state.
 
-## Fusion workflow
+```bash
+# Global install from npm
+pi install npm:pi-background-tasks@latest
 
-Fusion runs direct child `pi --mode text` processes only; it never calls `pi-ai` completion APIs. Each child is launched with `--no-session`, `--no-extensions`, `--no-skills`, `--no-prompt-templates`, `--no-themes`, and `--no-context-files`, plus the tool policy described below, the resolved provider/model/thinking level, and the package-owned private `extensions/fusion-child.ts` metadata extension. The prompt travels over stdin, not a shell or positional argument.
+# Project-local install from npm
+pi install npm:pi-background-tasks@latest -l
 
-Pi text mode writes the final full answer exactly once instead of serializing cumulative reasoning/partial-message events on every token delta. The private child extension emits one compact, reasoning-free metadata record per finalized assistant message for provider/model, stop reason, the complete Pi token/cost `Usage` object, and response byte/hash validation. Fusion persists those compact records in `*.events.jsonl`; the complete answer remains in the stage response artifact. The 32 MiB child stdout cap therefore applies to one final response, not amplified JSON telemetry. Failed attempts keep the authoritative response artifact empty and, when any stdout was captured, persist it separately as an explicitly incomplete `*.response.partial.*` artifact.
+# Git main branch; not a release tag
+pi install git:github.com/ismailsaleekh/pi-background-tasks@main
 
-Model configuration is global under the Pi agent directory:
+# Project-local git main install
+pi install git:github.com/ismailsaleekh/pi-background-tasks@main -l
 
-```text
-fusion-models.json
+# Local checkout/package path, run from this package directory
+pi install .
+pi install . -l
 ```
 
-### Validation workflow
-
-`fusion_validate` is the same orchestrator, artifact store, budget engine, conversation projection, and evaluation schema as `fusion_brainstorm`, with different stage framing. A workflow profile selects the four system prompts and the capability policy; it never changes the canonical input schema, which remains `pi-background-tasks.fusion-input.v4` for both tools. Canonical input bytes and the omission ledger are provably identical across workflows for the same conversation, and that equality is asserted by the golden-bytes gate rather than assumed.
+Local paths are loaded from disk without copying; use the path to this package from your current directory.
 
-| Concern | `fusion_brainstorm` | `fusion_validate` |
-|---|---|---|
-| Parameters | `{prompt, capability?}` | `{prompt}` — capability rejected |
-| Candidate capability | caller-selected, default `reason` | always `inspect` |
-| Evaluator / merger capability | `reason` by stage policy | `reason` by stage policy |
-| Run id prefix | `f` | `v` |
-| Output | prose answer | prose review |
-| Evaluation schema | `fusion-evaluation.v1` | `fusion-evaluation.v1` (identical) |
+## Quick start: useful in under five minutes
 
-The capability is fixed rather than defaulted. A `capability` argument on `fusion_validate` is a hard error at the schema boundary, and the orchestrator independently re-asserts the workflow capability before the artifact store or any child process exists, so a contradicting request launches **zero children**.
+1. Install and start Pi in a project.
+2. Launch a background command:
 
-The three reviewers are blind-compared exactly like brainstorm candidates, but the evaluator is additionally required to treat each distinct defect claim as a unit and to carry every surviving claim into `synthesis_plan.must_include`, **including claims raised by only one reviewer**. The merger is correspondingly forbidden from dropping a single-source finding or inventing one no reviewer raised, and must state the resolution and reason wherever reviewers disagreed. Without those two clauses a real defect that only one model noticed could disappear by silent majority vote, which is the failure mode a three-model review exists to prevent.
+   ```text
+   /bg --name "Typecheck watch" npm run typecheck -- --watch
+   ```
 
-`fusion_validate` is advisory and read-only. It never modifies files, it does not gate anything, and it is not a substitute for running tests or builds. Like every Fusion entry point, facts that exist only inside omitted tool output are not visible to reviewers; `inspect` lets them re-derive repository facts themselves, but uncommitted state that exists only in the parent agent's context must be restated in the prompt.
+   `/bg` starts a tracked shell task and returns the task id plus output path. User-launched `/bg` tasks notify in the UI but do not automatically wake a follow-up model turn.
 
-### Anthropic child sanitization
+3. Open the footer dock with **Shift↓** or list tasks:
 
-Fusion children launch with `--no-extensions` for isolation, which disables extension *discovery* while still honouring explicit `--extension` paths. The parent session normally loads an Anthropic system-prompt sanitizer through discovery, so a Claude child would inherit nothing and fail at the provider: Pi's own system prompt contains documentation lines Anthropic rejects.
+   ```text
+   /jobs
+   ```
 
-Children routed to the `anthropic` provider therefore receive a second explicit extension, [`@ravshansbox/pi-anthropic-sps`](https://github.com/ravshansbox/pi-anthropic-sps) (MIT), resolved from the package's own dependency tree. The metadata extension is always passed first so its `message_end` frame is never displaced.
+4. Read bounded output only when you need it:
 
-Children on every other provider receive exactly one `--extension` and their argv is byte-identical to the pre-sanitizer form. The sanitizer package publishes no `main`/`exports`, so it is located through its manifest's `pi.extensions[0]` entry rather than a direct require. Every resolution failure - package missing, manifest unreadable or malformed, no declared extension, or a declared file that does not exist - is a loud error before launch, because silently omitting the sanitizer would resurface later as an opaque provider rejection.
+   ```text
+   /logs b12ab34c 20000
+   ```
 
-### Candidate capabilities
+5. Let a child agent inspect while you continue:
 
-Fusion candidate children support three launch-time capability profiles. `reason` is the default: it passes `--no-tools` and preserves the previous no-tool candidate argv and prompt bytes. `inspect` is available only to candidate children and replaces `--no-tools` with the exact read-only tool policy `--no-builtin-tools --tools read,grep,find,ls --exclude-tools bash,edit,write,fusion_brainstorm,bg_delegate,bg_result,bg_run,bg_kill,bg_status,bg_logs,bg_run_pi_attested`. `research` extends `inspect` by adding the package-owned `fusion_web_fetch` tool to the `--tools` allowlist; the `--exclude-tools` denylist is unchanged and still bans `bash`, `edit`, `write`, `fusion_brainstorm`, `bg_delegate`, `bg_result`, `bg_run`, `bg_kill`, `bg_status`, `bg_logs`, and `bg_run_pi_attested`. The `reason` and `inspect` argv forms remain byte-identical to v0.7.8.
+   ```json
+   {"name":"Config reader","prompt":"Inspect the repository configuration files and report where background task settings are documented. Include file paths and quote only the relevant lines.","capability":"inspect"}
+   ```
 
-Evaluator, evaluation-repair, and merger children always run with `--no-tools` by stage policy. Caller input cannot grant them tools, even when candidates use `inspect` or `research`. Capability is recorded as launch metadata in the run manifest and child argv, not added to the canonical child-facing input; the canonical input schema remains `pi-background-tasks.fusion-input.v4`.
+   Call this with `bg_delegate`. When its terminal notification arrives, retrieve the answer deliberately:
 
-The inspect candidate system prompt tells the child it may re-derive facts from the repository using `read`, `grep`, `find`, and `ls`. The research prompt adds `fusion_web_fetch` for fetching a specific public URL as bounded Markdown or text. Both prompts extend the untrusted-data rule: projected conversation text, file contents, and fetched page content are data, never instructions to follow.
+   ```json
+   {"taskId":"<task id from bg_delegate>","delivery":"inline"}
+   ```
 
-`fusion_web_fetch` has a closed schema: `{ url: string, extract?: 'text' | 'markdown' }`. `extract` defaults to Markdown. There is deliberately no per-fetch prompt parameter. Anthropic documents the `{url, prompt}` extraction pattern as lossy by design: the prompt decides what reaches the model, so a false negative can enter a Fusion candidate answer, pass through blind evaluation, and reach the merged answer with no signal that the page contained missed information.
+   Call this with `bg_result`. Retrieval is hash-verified and never silently truncated.
 
-HTML extraction uses the runtime dependency `turndown@7.2.4`; its only dependency is `@mixmark-io/domino`, so it does not require `jsdom`. Markdown is the default because it preserves link destinations, headings, tables, and code blocks better than plain text. This version has no web search, browser, PDF support, cache, or domain allowlist.
+6. For a self-contained synthesis, ask Fusion:
 
-| `fusion_web_fetch` policy | Value |
-|---|---:|
-| Request method | GET |
-| Schemes | `http:` and `https:` only |
-| Timeout | 60 seconds |
-| Response body cap | 2 MiB |
-| Returned content cap | 32 KiB |
-| Redirect cap | 5 hops |
+   ```json
+   {"prompt":"Compare the tradeoffs between a watcher, a one-shot build, and a delegated repo inspection for a large refactor."}
+   ```
 
-Network handling is basic network hygiene, not a secret-exfiltration control. The hostname is resolved once, every returned address is checked, the connection is pinned to the vetted address, and the socket's remote address is verified after connect. Address validation re-runs on every redirect hop. Private, loopback, link-local, unique-local, multicast, and cloud-metadata addresses are refused. A research child that can read files and reach the network can in principle send what it read; that is an accepted trade in this version, not a sandbox or security boundary.
+   Call this with `fusion_reason`, or use `/fusion <prompt>` interactively.
 
-`fusion_web_fetch` fails loudly with typed errors rather than retrying or falling back to another URL, scheme, encoding, or extraction mode. Error codes include `invalid_url`, `unsupported_scheme`, `blocked_address`, `dns_failure`, `redirect_limit`, `redirect_blocked`, `response_too_large`, `unsupported_content_type`, `request_timeout`, `network_error`, `extraction_failed`, and `http_error`.
+More walkthrough detail: [Getting started](docs/getting-started.md).
 
-Every child has a stale-action watchdog in addition to the 30-minute absolute timeout. `FUSION_CHILD_IDLE_TIMEOUT_MS` defaults to 900 seconds and fails the child if no stdout or stderr activity occurs during that window; any stdout or stderr activity resets the watchdog. The threshold is deliberately far above tool latency: the child metadata frame is emitted only at `message_end` and text-mode stdout carries only the final assistant message, so one slow model turn is legitimately silent on both streams and must not be killed. The absolute timeout remains a backstop for children that keep producing output but never finish.
+## Pick the right workflow
 
-Inspect and research candidates also write a per-attempt tool-call audit log at `candidate-<slot>.attempt-<n>.tool-calls.jsonl`. The child appends one JSON line per completed tool call with the tool name, argument/result byte counts, and SHA-256 digests only. For `fusion_web_fetch`, the record also includes `url`, `final_url`, `http_status`, `response_bytes`, and `content_sha256`. Raw arguments, raw tool results, and page content are never written because file paths, file contents, fetched content, and tool results may contain secrets. After the child exits, the parent verifies the log is complete and contiguous; a trailing partial line, ordinal gap, duplicate ordinal, or schema-version mismatch is a loud failure.
+| Workflow | Blocking? | Context | Tools/network/write boundary | Best for | Expected behavior |
+|---|---:|---|---|---|---|
+| Ordinary foreground Pi work | Yes | Full current session | Whatever tools the active session has | Short reads/edits/commands where you want live back-and-forth | Pi waits for the work before responding. |
+| `/bg` | No | No model child unless your command starts one | Runs your shell command; **not sandboxed** | User-started local commands, servers, watches | UI notification and footer tracking; `/bg` uses notification-only by default. |
+| `bg_run` | No | No model child unless command starts one | Runs your shell command; **not sandboxed** | Agent-started long commands | Returns task id/output path; defaults to notification plus automatic follow-up wake. |
+| `bg_delegate` + `bg_result` | No launch; retrieval is point-in-time | Frozen visible conversation projection | Inspect-only child: read, grep, find, ls, artifact read; no shell, writes, network, recursion | Context-aware read-only investigation while parent continues | Launch returns immediately; result is committed by child and hash-verified by retrieval. |
+| `bg_run_pi_attested` | No | Prompt passed to one direct child Pi run | Direct `pi --mode json`; no shell command; writes requested report path | Evidence-oriented direct Pi task | Emits local attestation sidecar only after successful completion. |
+| `/fusion` / `fusion_reason` | Synchronous | Versioned conversation projection plus prompt | Candidates/evaluator/repair/merger run with no tools | Self-contained reasoning and synthesis | Three candidates → blind evaluator → optional bounded repair if evaluator JSON is invalid → merger. |
+| `fusion_investigate` | Synchronous | Clean task input only | Candidate read-only repo tools; evaluator/repair/merger no tools | Independent repo investigation | Restate all needed facts in fields; parent hidden/tool context is not visible. |
+| `fusion_research` | Synchronous | Clean task input only | Candidate read-only repo tools plus targeted fetch of caller-supplied public URLs only | URL-backed synthesis | Targeted URL retrieval, **not web search**. |
+| `fusion_validate` | Synchronous | Clean task input only | Advisory read-only validation review | Second-opinion review of completed work | Not a replacement for tests, builds, linters, security scans, or human review. |
 
-Missing config means all five slots are `$current`. Malformed config, stale explicit models, unavailable current models, and concurrent selector write conflicts fail loudly before child inference. Selector saves use an inter-process lock plus revision re-read before rename so simultaneous dialogs cannot silently overwrite each other. Candidate identities are anonymized before evaluation; provider/model metadata stays in local artifacts, not in evaluator prompts.
+See [Choose a workflow](docs/choose-a-workflow.md) for a decision tree and tradeoffs.
 
-Progress is surfaced through `fusion` status updates, TUI cancellable loader UI for `/fusion`, and partial `fusion_brainstorm` tool updates. Session shutdown or reload tracks the whole invocation from entry, aborts live or initializing Fusion runs, and waits for cleanup.
-
-### Conversation context policy
-
-Fusion children receive a **versioned conversation projection**, not a raw execution transcript. The canonical input schema is `pi-background-tasks.fusion-input.v4` and every run states exactly what was included and what was omitted.
-
-The projection transform (`visible-conversation-ledger-v2`) is shared by both entry points:
-
-| Content | Disposition |
-|---|---|
-| User text | included verbatim, never clipped |
-| Assistant text | included verbatim, never clipped |
-| User image blocks | `[Image omitted from fusion text transcript: <mime-type>]` marker |
-| Assistant thinking | excluded; recorded as an omission receipt |
-| Tool-call arguments | excluded; recorded as an omission receipt |
-| Tool-result payloads | excluded; recorded as an omission receipt |
-| Tool-result images | excluded; recorded as an omission receipt (never raw bytes) |
-| Active `fusion_brainstorm` call and its sibling calls | scope-excluded from the branch |
+## Copy-paste examples
 
-Omissions are **explicit, deterministic, and auditable** — never silent. Each omitted event produces a ledger row with its kind, exact byte count, and SHA-256 of the omitted bytes. Fusion v4 encodes child-facing projection entries as positional tuples to remove repeated object keys while preserving every role, ordinal, span, byte total, count, and text byte:
+### `bg_run`: start long shell work
 
 ```json
-["t","u",0,0,"hello"]
-["o",[1,9],29019,[0,5,5]]
+{
+  "name": "Docs preview",
+  "command": "npm run docs:dev",
+  "isAgent": false,
+  "timeoutSeconds": 3600
+}
 ```
 
-Text tuples are `["t", role, sourceOrdinal, blockOrdinal, text]`, where `role` is `"u"` for user or `"a"` for assistant. Omission tuples are `["o", [firstSourceOrdinal, lastSourceOrdinal], bytes, [assistantThinking, toolCalls, toolResultTexts]]`. The span is inclusive, `bytes` is the total omitted non-image payload for that run, and the count tuple order is fixed. Per-event hashes, ledger indices, and per-event byte details live in `context-omission-ledger.json`, not in the prompt: a child cannot verify a hash of payload it does not hold, so forwarding one only consumed context. That ledger also carries a `projection_map` proving every ledger row is represented by exactly one receipt or ledger-only image marker, and `accounting.omission_receipt_utf8_bytes` records the exact compact tuple receipt cost. The complete ledger is persisted as `context-omission-ledger.json`, and its row shape and root hash are unchanged by the compact encoding. **No head, tail, or preview of an omitted payload is ever forwarded** (`tool_payload_preview_bytes` is `0`), because an arbitrary prefix is usually irrelevant and can leak secrets or carry tool-output prompt injection. Repeated construction is byte-identical via canonical JSON, so prompt bytes and hashes are stable.
+Expected: returns immediately with a task id, PID when available, and `.pi/tasks/...output`. The command runs as an ordinary local shell command with your user permissions; it can invoke networked tools or paid services if the command itself does so.
 
-Two entry points share the transform but differ in request authority:
+### `bg_delegate`: context-seeded read-only investigation
 
-| Entry point | Policy id | `request.authority` |
-|---|---|---|
-| `fusion_brainstorm({prompt})` | `fusion-tool-explicit-v2` | `explicit_text` — the prompt is authoritative and self-contained |
-| `/fusion [prompt]` | `fusion-command-conversation-v2` | `directive_over_projected_conversation` |
-
-**Documented limitation:** facts that exist only inside omitted tool output are not available to Fusion children. Restate any required finding as visible conversation text, or include it in the `fusion_brainstorm` prompt. Children are instructed to say so plainly rather than guess. No model-generated summarization is used as hidden preprocessing.
-
-### Stage budgets
-
-Every prompt-expansion stage — candidate, evaluator, evaluation repair, and merger — is size-checked **before any child process is created**, and each stage is checked against **its own configured route**, so a large-context slot cannot hide a small-context sibling and a small slot cannot veto stages it never serves.
-
-Input forecasting uses the shared affine estimator `estimateInputTokens({family, segments})`: additive integer byte-class accounting plus a 512-token affine intercept. Calibrated normal-ASCII rates are used only for backed exact model IDs, measured prompts at or above 50 KiB, and prompts that pass the low-whitespace dense-ASCII gate. That gate records the measured whitespace fraction in `budget-plan.json` and falls back conservatively for out-of-distribution near-zero-whitespace payloads; it is a heuristic token-density proxy, not a bound. Multibyte UTF-8 uses the conservative 2.0 B/tok fatal rate while persisting the provable 1.00 B/tok ceiling as advisory. The calibration basis is 882 real large Fusion prompts: Anthropic observed floor 2.047 B/tok (shipped `r=1.73`) and Codex observed floor 3.400 B/tok (shipped `r=2.89`); unknown providers and unbacked model IDs use the unbacked 1.00 B/tok floor and are surfaced in artifacts and result details.
-
-Each stage is forecast with its **real prompt builder**, rendered with empty embedded-output slots, plus the enforced output contracts for whatever that stage will embed:
-
-| Stage | Embeds | Mandatory |
-|---|---|---|
-| `candidate` | canonical input only | yes, once per slot |
-| `evaluation` | + 3 candidate answers | yes |
-| `evaluation_repair` | + 3 candidates, invalid evaluator output, diagnostics | conditional, still budgeted |
-| `merge` | + 3 candidates, validated evaluation | yes |
-
-`evaluation_repair` only runs when the evaluator returns schema-invalid JSON, but it is budgeted unconditionally: "uncommon" is not a reliability contract.
-
-Output sizes are guaranteed by **enforced contracts**, not assumptions. Each stage has a maximum response size measured in *JSON-rendered transfer bytes* — the bytes the response actually costs once a later stage embeds it, escaping included (candidate 48 KiB, evaluator 64 KiB, merger 64 KiB, repair diagnostics 8 KiB). Measuring the rendered form removes any escaping guess: quotes, backslashes, and newlines expand 2x and control characters up to 6x. A response over its contract is a loud `child_output_cap` failure; it is preserved in the run artifacts and is never sliced, truncated, or forwarded.
-
-When a workflow cannot fit, the error names the **first failing mandatory stage** in deterministic order (candidate slots, then evaluation, then merge), lists every other blocking stage, and labels conditional ones. It never blames a stage that would have succeeded.
-
-Remediation is derived, not guessed: Fusion re-plans the entire workflow **with the request removed**. If it still fails, the error says plainly that shortening the request cannot help and points at starting a fresh conversation or raising the route's context window. If it then fits, the request is what determines feasibility, and the error states the exact minimum byte reduction and the maximum safe request size.
-
-Preflight is two-tiered: input-only forecasts are fatal (`prompt_budget_exceeded_forecast`), while worst-case downstream output reservations are warning-only and recorded in `budget-plan.json`. Exact rendered per-stage checks remain fatal (`prompt_budget_exceeded_measured`). Runs that fit still emit advisory warnings for tight utilization or reservation overage. The warning never alters behaviour.
-
-Every configured route must also satisfy a documented minimum capacity; smaller routes are rejected at configuration time with an actionable error naming the requirement, rather than being accepted and failing later at the provider. All route capacities, per-stage forecasts, headroom, utilization, the byte composition of the blocking stage, and the blockers list are persisted as `budget-plan.json`.
-
-If an input still exceeds the safe budget, Fusion fails with `prompt_budget_exceeded_forecast` for input-only preflight or `prompt_budget_exceeded_measured` for exact rendered prompts. The error names the stage, measured bytes, measured token upper bound, allowed tokens, the limiting configured model and its context window, estimator source, and concrete remediation. **Zero children are launched** when preflight rejects. Provider context-window failures remain loud child failures; there is no hidden local truncation and no silent fallback anywhere in this path.
-
-## Extension EventBus API
-
-Version `0.7.0` exposes a real extension-to-extension service over Pi's documented `pi.events` bus. This is not a `ctx` method and it does not call a second task manager: requests route to the same `BackgroundTaskRegistry` used by `bg_run`, `bg_status`, `bg_logs`, and `bg_kill`.
+```json
+{
+  "name": "Route audit",
+  "prompt": "Inspect the package source and identify where delegate route pinning is enforced. Return file paths, function names, and a short explanation. If a fact exists only in omitted parent tool output, say it is unavailable rather than guessing.",
+  "capability": "inspect",
+  "autoDeliver": "never"
+}
+```
 
-Public constants are exported from `src/core/extension-api.ts`:
+Then retrieve:
 
-| Purpose | Value |
-|---|---|
-| Request channel | `pi-background-tasks:request:v1` |
-| Response channel | `pi-background-tasks:response:v1` |
-| Terminal channel | `pi-background-tasks:terminal:v1` |
-| Request schema | `pi-background-tasks.extension-request.v1` |
-| Response schema | `pi-background-tasks.extension-response.v1` |
-| Terminal schema | `pi-background-tasks.extension-terminal.v1` |
+```json
+{
+  "taskId": "<delegate task id>",
+  "delivery": "inline"
+}
+```
 
-Requests are closed frames: `{ schema_version, request_id, operation, payload }`, where `operation` is one of `capabilities`, `run`, `status`, `logs`, or `kill`. Responses echo the same `request_id` and `operation`, set `ok`, and contain exactly one of `result` or bounded `error`. Malformed frames, unknown keys, duplicate request IDs, requests before `session_start`, and requests during shutdown receive `ok: false`; they are not silently dropped or rerouted to shell fallback behavior.
+Expected: `bg_delegate` returns a launch receipt immediately. `bg_result` returns a typed not-ready result while running; after commit it verifies package identity, seed hash, route, block hashes, and aggregate hash before returning bytes. Oversized answers become explicit artifact references, not truncated inline text.
 
-`capabilities` returns exactly:
+### `bg_run_pi_attested`: local evidence for one Pi child
 
 ```json
-{"api_version":1,"run":true,"run_is_agent":true,"run_completion_trigger":true,"status":true,"logs":true,"logs_bounded":true,"kill":true}
+{
+  "name": "Migration report",
+  "provider": "openai-codex",
+  "model": "gpt-5.5",
+  "prompt": "Inspect the repository and write a concise migration report to reports/migration.md.",
+  "reportPath": "reports/migration.md",
+  "timeoutSeconds": 1800
+}
 ```
 
-`run.payload` is the strict `bg_run` launch object: `name`, `command`, `isAgent`, `notifyOnCompletion`, `triggerOnCompletion`, plus optional positive-integer `timeoutSeconds`. The result is a `BgTaskSnapshot`. `status` returns `{ tasks }`; `logs` returns the existing bounded log detail fields plus bounded `text`; `kill` returns `{ task, message }`. Task status vocabulary is exactly `running`, `completed`, `failed`, or `killed`.
-
-Terminal events keep the strict paired-consumer frame `{ schema_version: "pi-background-tasks.extension-terminal.v1", task }`. They are correlated by `task.id`, published exactly once per task after final output and terminal metadata durability, and for EventBus `run`/`kill` requests they are held behind a response barrier so even an immediately exiting or immediately killed child cannot emit its terminal event until the correlated response has been delivered and one microtask turn has allowed consumers to bind the returned task id. Terminal EventBus delivery exceptions are logged loudly and retried; a task is marked terminal-published only after the EventBus emit returns successfully.
+Expected: launches exactly one direct `pi --mode json` child using structured provider/model fields. It rejects direct API-key/auth-file launch arguments and only writes the attestation sidecar after successful completion and durable hashes. The attestation is local evidence, not cryptographic proof against a compromised machine or provider.
 
-## Runtime files
+### Fusion tools
 
-Task output and metadata are written under the current project:
-
-```text
-.pi/tasks/<session-id>-<pid>/<task-id>.output
-.pi/tasks/<session-id>-<pid>/<task-id>.json
+```json
+{"prompt":"Design a rollback strategy for a risky database migration. Include assumptions and failure modes."}
 ```
 
-Fusion writes private debugging artifacts under:
+Use with `fusion_reason` for self-contained synthesis.
 
-```text
-.pi/fusion/<session-id>-<pid>/<run-id>/
+```json
+{
+  "objective": "Find how background task output is capped and surfaced.",
+  "background": ["We are evaluating pi-background-tasks behavior for long-running commands."],
+  "deliverable": "File paths, constants, defaults, and user-visible behavior.",
+  "scope": ["src"],
+  "constraints": ["Read-only inspection only."]
+}
 ```
 
-Each run contains `manifest.json`, `canonical-input.json`, `context-omission-ledger.json`, `budget-plan.json`, candidate/evaluation/merge prompts, raw child JSONL events, stderr, responses, and, when inspect or research candidates run, tool-call logs named `candidate-<slot>.attempt-<n>.tool-calls.jsonl`, plus `blind-candidates.json`, `evaluation.json`, `merged.md`, and `error.json` for failed/cancelled runs. Persisted stage prompts are byte-identical to the exact bytes written to that child's stdin. `context-omission-ledger.json` carries the complete source-ordered omission ledger, and `budget-plan.json` records every configured route's capacity plus the pre-candidate feasibility decision, so a rejected run is as auditable as a successful one. Artifact files are written by private temp-file/fsync/rename, and v2 manifests persist cumulative child usage plus per-attempt observed usage/model data for successful, failed, and cancelled child attempts. Every usage record preserves the complete Pi cost breakdown; the same exact shape is cloned into `fusion_brainstorm` tool results so newer Pi hosts can calculate and replay footer/session statistics safely. These artifacts are local evidence only; they are not shown in `/jobs` or the background-task dock.
+Use with `fusion_investigate`.
 
-For attested Pi tasks only, the task id is `b` plus 32 random hex characters (128 bits) and additional flat siblings are written in the same directory:
-
-```text
-.pi/tasks/<session-id>-<pid>/<task-id>.pi-events.jsonl
-.pi/tasks/<session-id>-<pid>/<task-id>.stderr
-.pi/tasks/<session-id>-<pid>/<task-id>.pi-telemetry-wrapper.cjs
-.pi/tasks/<session-id>-<pid>/<task-id>.attestation.json
+```json
+{
+  "objective": "Summarize the installation syntax Pi documents for packages.",
+  "background": ["We need package README install examples to match Pi package docs."],
+  "deliverable": "A short summary with caveats.",
+  "sources": [
+    {"url":"https://github.com/earendil-works/pi-coding-agent","purpose":"Pi package documentation repository"}
+  ]
+}
 ```
 
-The attestation sidecar uses `schema_version: "phase2.pi_task_attestation.v1"` and is written last, after metadata/output/events/stderr/wrapper/report bytes are closed and hashed. An attested task does not become externally visible as `completed` until final metadata and the sidecar are durable. These are local runtime artifacts and should remain gitignored.
-
-## Durability model
-
-All task metadata, task output/events/stderr, attestation sidecars, Fusion artifacts, and the global `fusion-models.json` are written through one shared primitive in `src/core/durable-fs.ts`.
-
-The invariant is: **open the file once with write intent, write and `fsync` through that same writable handle, then close.** A pathname is never reopened merely to flush it. This is required for Windows correctness — `FlushFileBuffers` needs a handle with write access, so flushing through a reopened read-only handle fails with `EPERM: operation not permitted, fsync` and previously broke every background task on Windows.
-
-Two write modes are provided:
+Use with `fusion_research`. Only declared public `http(s)` URLs may be fetched; this is not a search tool.
 
-| Mode | Flags | Used for |
-|---|---|---|
-| Direct durable write | `w`, inherited mode | task output, events, stderr |
-| Atomic replacement | private `0o600` temp with `wx`, then rename | task metadata, attestations, Fusion artifacts/manifests, model config |
-
-Failure handling is loud and typed. Every open, write, `fsync`, rename, close, and temp-cleanup failure raises `DurableFileError` carrying the failing operation, path, native error code, and original cause. **A failed `fsync` is never tolerated or downgraded**, so the package cannot report durable state it did not actually achieve. A close or cleanup failure is attached as a secondary `cleanupFailures` entry and never replaces the primary error, and a temporary file is only removed when that same call created it.
-
-**Platform limitation.** After the rename, the parent directory is itself `fsync`ed on POSIX so the new directory entry is crash-durable. Node exposes no portable equivalent on Windows, so that step is skipped there: file contents are still explicitly flushed before the rename and rename failures remain fatal, but the package cannot offer the same crash-durability guarantee for the directory entry on Windows. When a failure occurs after a successful rename, `DurableFileError.renameCompleted` is `true`, meaning the replacement may already be visible even though the operation reported an error.
+```json
+{
+  "objective": "Review whether a documentation-only change is ready to ship.",
+  "background": ["The change edits README and package-local docs only."],
+  "changeSummary": "Replaced monolithic README with landing page and moved operational details into docs.",
+  "scope": ["README.md", "docs/getting-started.md", "docs/choose-a-workflow.md"],
+  "acceptanceCriteria": ["Install commands are accurate", "Safety limitations are explicit", "Examples match public schemas"],
+  "verification": {
+    "status": "provided",
+    "evidence": [{"check":"Focused link check", "outcome":"All local README links resolve"}]
+  }
+}
+```
 
-## Safety model
+Use with `fusion_validate` for advisory read-only review.
 
-- Commands are spawned and tracked with `child_process.spawn`; the package does not rely on shell `&`.
-- Fusion inference is isolated to direct child `pi --mode text` invocations with tools/skills/session/context files disabled and only the package-owned compact metadata extension explicitly loaded; no direct completion API, API-key argument, or model fallback is used.
-- Attested Pi tasks are a local, unsigned, same-user-writable attestation path for downstream gates. They bind source bytes and observed Pi/ModelRegistry facts; they are not cryptographic proof against a malicious local user, compromised Pi binary, or compromised provider.
-- stdout/stderr are captured to task output files.
-- Model-visible logs are bounded and point to full output files.
-- POSIX process groups are used for process-tree kill where possible, with child-process fallback.
-- On Windows, process-tree termination uses `%SystemRoot%\\System32\\taskkill.exe` directly (never `PATH`) with a two-stage `/T` then `/T /F` flow. Stage one is a logical Windows termination request, not SIGTERM and not a guaranteed graceful shutdown: console processes may ignore it, and re-parented descendants can escape the tree. Strong containment would require Windows Job Objects via a native component, which is out of scope.
-- Running tasks are cleaned up on Pi session shutdown/reload.
-- Child Pi processes are never launched through a shell. On Windows the npm `pi.cmd` shim is deliberately not executed, because a batch shim cannot preserve argument bytes safely; the package resolves the Pi package's own CLI entry and launches it with `process.execPath` instead. Batch, PowerShell, and extensionless launch targets are rejected loudly rather than executed, and a launch target resolving outside the Pi package root is rejected.
-- Cross-Pi-restart process reattachment and Ctrl+B backgrounding of already-running foreground tools are intentionally out of scope.
+## Footer dock
 
-### Windows shell and telemetry
+<p align="center">
+  <img src="docs/assets/footer-dock.svg" alt="Illustration of the pi-background-tasks footer dock with running and completed tasks" width="760">
+</p>
 
-`cmd.exe` remains the default Windows shell, so existing commands written for `cmd` keep working unchanged. The generic `SHELL` variable is deliberately ignored on Windows, because honouring it would silently change the command language for `%VAR%`, `set`, `dir`, backslash paths, and quoting.
+When tasks are running or unseen completions exist, the footer shows a compact `bg ...` segment. Press **Shift↓** to open the focused bottom dock. Use `/bg-clear` to acknowledge finished-task footer notices in any terminal.
 
-A POSIX shell is available as an explicit opt-in via `PI_BG_SHELL=bash`, with an optional absolute `PI_BG_SHELL_PATH`. Invalid values fail loudly rather than falling back. Bash is invoked with `-c` and never `-lc`, because a login shell runs profile scripts whose banner output would be captured into task output.
+| Control | Action |
+|---|---|
+| `Shift↓` | Open the dock |
+| `/bg-clear` | Clear finished-task notices |
+| `↑` / `↓`, `PageUp` / `PageDown` | Move through list or scroll output tail |
+| `Enter` / `→` | Inspect details |
+| `←` | Return to list |
+| `k` | Stop selected running task |
+| `R` | Rerun selected command |
+| `c` | Show copyable output path |
+| `x` / `Esc` / `q` | Close dock |
 
-**Documented limitation:** `isAgent: true` Pi-agent telemetry wrapping works by installing a POSIX shell function that intercepts `pi`. That mechanism has no safe `cmd.exe` equivalent, so under the Windows `cmd` dialect the command is left byte-for-byte unchanged and telemetry is reported as unavailable with the reason `win32-cmd-cannot-safely-intercept-pi-argv`. Zero usage is never synthesized, and no warning text is injected into captured command output. Use `PI_BG_SHELL=bash` on Windows when agent telemetry is required.
+Agent tasks launched through `pi -p ...` or `pi --mode json ...` and marked `isAgent:true` can show task-owned model/context/token/tool telemetry. Missing child telemetry is shown as unavailable, not synthesized as zero.
 
-On Windows, argument lists are checked against the 32,767-code-unit command-line limit before a child is created, so an oversized invocation fails loudly with the measured length rather than producing a confusing native spawn error. Argument contents are never included in that error.
+<a id="commands"></a>
+<a id="footer-dock-ux"></a>
+<a id="update-available-notice"></a>
+<a id="llm-tools"></a>
+<a id="delegated-background-agents"></a>
+<a id="fusion-workflow"></a>
+<a id="conversation-context-policy"></a>
+<a id="extension-eventbus-api"></a>
+<a id="runtime-files"></a>
+<a id="durability-model"></a>
+<a id="safety-model"></a>
+<a id="windows-shell-and-telemetry"></a>
 
-## Development and QA
+## Architecture, trust, and safety
 
-Default QA gate:
+- Runtime task files live under `.pi/tasks/<session-id>-<pid>/`; Fusion artifacts under `.pi/fusion/...`; delegate artifacts under `.pi/delegate/...`.
+- Shell jobs are tracked by the package, but they are not sandboxed. Treat commands as local processes with your permissions and credentials.
+- Delegate and Fusion child Pi processes are route-pinned where applicable; delegate/Fusion paths do not silently substitute routes.
+- Fusion uses direct child `pi --mode text` processes, not direct completion APIs. Frontier Fusion routes are admitted only through Pi Anthropic or Codex subscription OAuth; metered frontier API credentials are rejected before child creation.
+- Fusion research fetches only caller-supplied public `http(s)` URLs with bounded retrieval. It is not web search and not a secret-exfiltration boundary.
+- Attestation sidecars are local, unsigned, same-user-writable evidence. They are useful for downstream local gates, but not cryptographic proof against local compromise, a compromised Pi binary, or a compromised provider.
+- Metadata, attestations, delegate/Fusion artifacts, and configuration replacements use write/fsync/rename durability patterns. Ordinary task output is closed and drained before terminal publication but is not explicitly fsynced. POSIX directory entries are fsynced after atomic replacement; Windows lacks the same portable directory-entry crash-durability guarantee.
 
-```bash
-npm run test
-```
+Detailed operations: [Configuration](docs/operations/configuration.md).
 
-Smoke and release checks:
+## EventBus and Autopilot integration
 
-```bash
-npm run smoke
-npm run pack:dry-run
-npm run test:compat
-```
+Other Pi extensions can control the same `BackgroundTaskRegistry` through Pi's `events` bus instead of shelling out or maintaining a second task manager. The public channels are:
 
-Full interactive QA gate:
+| Purpose | Channel |
+|---|---|
+| Request | `pi-background-tasks:request:v1` |
+| Response | `pi-background-tasks:response:v1` |
+| Terminal task event | `pi-background-tasks:terminal:v1` |
 
-```bash
-npm run test:full
-```
+Operations are `capabilities`, `run`, `status`, `logs`, and `kill`. This is the integration point for orchestrators such as Autopilot that need non-blocking package-managed work with bounded logs and correlated terminal events. Consumers must deduplicate terminal frames by `task.id`: an EventBus listener failure can cause a retried publication.
 
-The suite includes typecheck, unit, SDK, RPC, component, package, PTY/TUI, and scripted-provider coverage for the focused dock, lifecycle safety, and completion follow-up behavior.
+## Documentation map
 
-Note: the repo QA standard requires exhaustive coverage of every public behavior and plausible edge case. `TEST_PLAN.md` tracks the current coverage matrix and any future edge-case additions.
+| Need | Read |
+|---|---|
+| First install and first task | [Getting started](docs/getting-started.md) |
+| Which workflow/tool to choose | [Choose a workflow](docs/choose-a-workflow.md) |
+| Environment variables, shells, output caps, model config, offline behavior | [Configuration](docs/operations/configuration.md) |
+| Package QA expectations | [TESTING.md](TESTING.md) and [TEST_PLAN.md](TEST_PLAN.md) |
+| Publishing notes | [PUBLISHING.md](PUBLISHING.md) |
+| License | [LICENSE](LICENSE) |
 
-This package follows the repo-wide Pi extension QA standard documented in:
+## Contributing
 
-- [`../EXTENSION_QA_STANDARD.md`](../EXTENSION_QA_STANDARD.md)
-- [`../EXTENSION_TESTING_PLAYBOOK.md`](../EXTENSION_TESTING_PLAYBOOK.md)
-- [`TEST_PLAN.md`](TEST_PLAN.md)
-- [`TESTING.md`](TESTING.md)
+Keep user-facing claims tied to source. If you change public schemas, command behavior, durability, model routing, or environment variables, update these package-local docs in the same change and run focused checks appropriate to the edit.