pi-background-tasks 0.9.0 → 1.0.4

package/TESTING.md

@@ -1,10 +1,12 @@
 # pi-background-tasks Testing
 
-This package follows the repo-wide Pi extension QA standard:
+This package follows the package-local QA navigation docs:
 
-- [`../EXTENSION_QA_STANDARD.md`](../EXTENSION_QA_STANDARD.md)
-- [`../EXTENSION_TESTING_PLAYBOOK.md`](../EXTENSION_TESTING_PLAYBOOK.md)
-- [`TEST_PLAN.md`](TEST_PLAN.md)
+- `BACKGROUND-TASKS-INSTRUCTIONS.md` — required agent gateway/read order
+- [`docs/operations/testing.md`](docs/operations/testing.md) — gate selection and isolation
+- [`TEST_PLAN.md`](TEST_PLAN.md) — exhaustive feature coverage matrix and acceptance truth
+
+The historical monorepo extension standards are contextual background only; do not leave standalone package links to parent `../EXTENSION_*` files in this package's published docs.
 
 ## Current commands
 
@@ -85,7 +87,7 @@ Current smoke is `tsx scripts/smoke.ts`. It creates a temporary Pi agent/session
 
 - the pre-fix full-transcript canonical input and the fact that it is rejected against the panel's smallest route;
 - the post-fix projected canonical input with full omission accounting and a byte-identical rebuild check;
-- the measured candidate, evaluator, evaluation-repair, and merger prompt sizes against the allowed input budget, using the largest real candidate answer (45,434 B) and evaluator output (54,829 B) observed in `.pi/fusion`.
+- the measured candidate, evaluator, evaluation-repair, and merger prompt sizes against the allowed input budget, using the enforced contract maxima: 48 KiB (49,152 B) for each candidate output and 64 KiB (65,536 B) for evaluator output.
 
 It performs no inference and spawns no child, so it is safe to run offline and costs nothing. It exits non-zero if any stage would exceed the budget.
 
@@ -154,6 +156,10 @@ actually sent. Both are now pinned by unit and mutation-guard tests.
 
 Smoke proves loadability only; completion requires `npm run test`, `npm run test:full`, `npm run pack:dry-run`, and the release-only compatibility gate when preparing a release.
 
+### Docs/gateway focused checks
+
+Current package docs gates are `npm run docs:generate`, `npm run docs:verify`, and `npm run docs:attest/record -- <doc_id> --reviewer <identity-after-semantic-review> --verdict PASS --notes <review-notes>`. For docs-only changes under constrained operator instructions, run only the requested focused subset (for example frontmatter, package-local links, absence of standalone parent `../EXTENSION_*` links, and version/tag wording derived from `package.json`/observed git tags) and report when full docs verification/attestation was not run.
+
 ## Required isolated environment
 
 Automated tests run with isolated temp project/agent/session directories and should use:
@@ -180,23 +186,23 @@ npm run test:rpc
 npm run test:agent-loop
 ```
 
-The Fusion SDK/RPC/scripted-provider tests install a deterministic fake child `pi` in a temp `PATH` from `tests/helpers/fusion-fake-pi.ts`. Parent Pi remains the real SDK/RPC runtime; only direct child `pi --mode text` calls with the package-owned private compact metadata extension are intercepted. `PI_CODING_AGENT_DIR` is pointed at the temp agent directory so `fusion-models.json` is never read from the user's real global Pi directory. Fusion context coverage is conversation-projection coverage. `tests/unit/fusion-context-prompts.test.ts` verifies that a synthetic session carrying more than 1 MB of tool arguments/results still yields a small canonical input, that user and assistant text survive verbatim, that thinking and tool payloads never appear (including no head/tail/preview sentinel), that omission counts, byte totals, and hashes are exact and stable, that repeated construction is byte-identical, that the active `fusion_brainstorm` leaf and sibling calls stay scope-excluded, that images remain marker-only or ledger-only with no raw base64 in child prompts, and that every retained source block receives exactly one disposition. `tests/unit/fusion-high-cardinality.test.ts` covers the receipt-cardinality regression: a session of many short interleaved tool events (rather than a few enormous results) pins per-receipt cost, proves the compact `omitted_activity` fields are the only model-facing ones, reconciles every receipt against the ledger through `projection_map`, and proves the whole workflow fits a real route budget. `tests/unit/fusion-budget.test.ts` covers stage budgets: the limiting model is the smallest configured route (including when it is the evaluator rather than a candidate), unknown or too-small capacities fail before spawn, boundary prompts pass at exactly the limit and fail one byte past it, the child system prompt counts as input, dense multi-byte UTF-8 cannot bypass byte accounting, and candidate, evaluator, evaluation-repair, and merger expansions are each rejected before their child is spawned with zero partial launches. `tests/package/typebox-compat.test.ts` pins the TypeBox posture and compiles nullable-array schemas. The release-only `npm run test:compat` packs the package, installs exact supported Pi versions, runs `/jobs`, runs `/fusion` through the installed package entrypoint with the fake child Pi, verifies five child invocations, verifies `/fusion-models` rejects non-TUI mode, asserts the resolved `typebox` is Pi's bundled peer rather than a private or nested copy, and scans the installed package bytes for TypeBox APIs removed in the 1.3.x line. It then drives the current host Pi through a real RPC `fusion_brainstorm` parent-agent loop, checks the persisted tool result carries the complete Pi `Usage.cost` object, invokes `get_session_stats` (the same aggregation boundary used by the TUI footer), reopens the durable session, and verifies identical token/cost totals. All parent and child inference remains deterministic and local.
+The Fusion SDK/RPC/scripted-provider tests install a deterministic fake child `pi` in a temp `PATH` from `tests/helpers/fusion-fake-pi.ts`. Parent Pi remains the real SDK/RPC runtime; only direct child `pi --mode text` calls with the package-owned private compact metadata extension are intercepted. `PI_CODING_AGENT_DIR` is pointed at the temp agent directory so `fusion-models.json` is never read from the user's real global Pi directory. Fusion v1 public-surface coverage asserts exactly four tools (`fusion_reason`, `fusion_investigate`, `fusion_research`, `fusion_validate`), no public capability argument, retired-tool active-tool removal, `/fusion` mapping to reason/no-tool candidates, closed schemas with Google-compatible enum status, targeted URL fetch not search, URL exfiltration warnings, strict validation verification rules, historical v4 rendering without old-tool activation, and actionable migration errors for `fusion_validate({prompt})`. Fusion context coverage covers both reason conversation projection and clean-task non-interference invariants, including parent-sentinel absence from every clean downstream prompt/artifact and byte-identical clean inputs across unrelated parent sessions. `tests/unit/fusion-context-prompts.test.ts` verifies that a synthetic session carrying more than 1 MB of tool arguments/results still yields a small canonical input, that user and assistant text survive verbatim, that thinking and tool payloads never appear (including no head/tail/preview sentinel), that omission counts, byte totals, and hashes are exact and stable, that repeated construction is byte-identical, that the active Fusion tool leaf and sibling calls stay scope-excluded, that images remain marker-only or ledger-only with no raw base64 in child prompts, and that every retained source block receives exactly one disposition. `tests/unit/fusion-high-cardinality.test.ts` covers the receipt-cardinality regression: a session of many short interleaved tool events (rather than a few enormous results) pins per-receipt cost, proves the compact `omitted_activity` fields are the only model-facing ones, reconciles every receipt against the ledger through `projection_map`, and proves the whole workflow fits a real route budget. `tests/unit/fusion-budget.test.ts` covers stage budgets: the limiting model is the smallest configured route (including when it is the evaluator rather than a candidate), unknown or too-small capacities fail before spawn, boundary prompts pass at exactly the limit and fail one byte past it, the child system prompt counts as input, dense multi-byte UTF-8 cannot bypass byte accounting, and candidate, evaluator, evaluation-repair, and merger expansions are each rejected before their child is spawned with zero partial launches. `tests/package/typebox-compat.test.ts` pins the TypeBox posture and compiles nullable-array schemas. The release-only `npm run test:compat` packs the package, installs exact supported Pi versions, runs `/jobs`, runs `/fusion` through the installed package entrypoint with the fake child Pi, verifies five child invocations, verifies `/fusion-models` rejects non-TUI mode, requires each supported Pi line to declare terminal `agent_settled`, asserts the resolved `typebox` is Pi's bundled peer rather than a private or nested copy, and scans the installed package bytes for TypeBox APIs removed in the 1.3.x line. Pi 0.75.5 is intentionally unsupported because it lacks the terminal event required to seal a Fusion audit after retries and compaction. It then drives the current host Pi through a real RPC `fusion_reason` parent-agent loop, checks the persisted tool result carries the complete Pi `Usage.cost` object, invokes `get_session_stats` (the same aggregation boundary used by the TUI footer), reopens the durable session, and verifies identical token/cost totals. All parent and child inference remains deterministic and local.
 
 ## Coverage summary
 
 Implemented coverage includes:
 
-- tools: `bg_run`, `bg_run_pi_attested`, `bg_status`, `bg_logs`, `bg_kill`, `fusion_brainstorm`, including required `isAgent` schema/runtime validation, the event-driven no-sleep/no-poll system-prompt contract, truthful launch receipts for all four notification/wake combinations, non-terminating `bg_run` compatibility, point-in-time status/log guidance, durable terminal-notification authority, attested direct Pi spawn validation, Fusion exact merged tool result delivery/progress/details/context exclusion, versioned conversation projection with explicit hash-accounted tool/thinking omissions, pre-spawn stage budget rejection for all four expansion stages, image omission markers with raw image data excluded from child prompts, unknown/ambiguous IDs, completed-kill failure, legacy no-name preparation, head/tail truncation, and notification on/off behavior
+- tools: `bg_run`, `bg_run_pi_attested`, `bg_status`, `bg_logs`, `bg_kill`, `fusion_reason`, `fusion_investigate`, `fusion_research`, `fusion_validate`, including required `isAgent` schema/runtime validation, the event-driven no-sleep/no-poll system-prompt contract, truthful launch receipts for all four notification/wake combinations, non-terminating `bg_run` compatibility, point-in-time status/log guidance, durable terminal-notification authority, attested direct Pi spawn validation, Fusion exact merged tool result delivery/progress/details/context exclusion, reason versioned conversation projection with explicit hash-accounted tool/thinking omissions, clean-task context isolation, pre-spawn stage budget rejection for all four expansion stages, image omission markers with raw image data excluded from child prompts, unknown/ambiguous IDs, completed-kill failure, legacy no-name preparation, head/tail truncation, and notification on/off behavior
 - commands: `/bg`, `/jobs`, `/logs`, `/kill`, `/tasks`, `/bg-tasks`, `/bg-clear`, `/bg-update`, `/fusion`, `/fusion-models` discovery, happy paths, `/fusion` direct custom-message delivery, `/fusion` editor/cancel flow, `/fusion-models` TUI save and non-TUI rejection, `/bg --agent` parsing, finished-notice clearing, malformed `/bg`, unknown/ambiguous IDs, completed-task `/kill`, byte-limit normalization, and RPC no-hang fallback behavior
 - update-available notice: semver parse/compare/precedence, `formatUpdateSegment`, npm/`package.json` payload narrowing, and injected-fetch success/404/throw/timeout (unit); localhost-registry footer segment (idle + appended to an active footer), `/bg-update` non-installing instructions, and opt-out/offline/already-current/registry-failure no-segment-and-no-throw paths (SDK); `/bg-update` discovery and offline instructions (RPC). The check is one-shot on `session_start`, time-boxed, offline-safe, gated by `PI_OFFLINE`/`PI_BG_DISABLE_UPDATE_CHECK`, and `PI_BG_REGISTRY_URL` overrides the registry endpoint
 - shortcut/UI: component coverage for focused dock list/detail/key handling, detail output-tail scrolling (arrow/page scroll, follow-pause-on-scroll, `lines X–Y of N` position indicator, resume-follow-at-bottom, and no-scroll when output fits), empty/history/unread states, paging, close aliases, stop/stop-all/rerun/path actions, missing output files; SDK coverage for explicit `/bg-clear` finished-notice clearing, `/bg-clear` footer hinting, optional `Ctrl+Alt+C` fallback shortcut registration, and mixed failed/stopped/done/focused footer status; RPC coverage that `/bg-clear` works as a terminal-independent clear path; and PTY coverage for `/tasks`, `/bg-tasks`, real `Shift+Down`, arrows, page keys, detail/back/history/stop/stop-all/rerun/path/close, failed unread badges, and running/completed/failed/killed rerun paths
 - runtime files: output and metadata files under `.pi/tasks/`, Fusion private `.pi/fusion/<session-id>-<pid>/<run-id>/` artifacts plus global `fusion-models.json`, persisted `isAgent` classification, task-owned context-window telemetry snapshots, cumulative background Pi-agent token usage, tool-use counts, agent model identifier (preferring the fully-qualified `provider/model` form), explicit `isAgent:true` telemetry wrapping for background `pi` agents, `isAgent:false` non-wrapping for scripts, attested Pi flat siblings (`.pi-events.jsonl`, `.stderr`, `.pi-telemetry-wrapper.cjs`, `.attestation.json`), real child `pi --mode json` tool-event parsing for background-agent telemetry, split/large telemetry ingestion, metadata after completion/failure, Fusion v2 compact final-only metadata and explicitly marked partial-response artifacts, and Fusion manifest token plus complete cost-component aggregates equal to the sum of successful and observed failed/cancelled attempts
-- extension EventBus API: unit coverage for `pi-background-tasks:request:v1`/`response:v1` closed-frame validation, exact capability handshake, malformed payload rejection, unknown keys, unknown operations, duplicate request IDs, missing `session_start`, shutdown refusal, unsubscribe, strict terminal frame shape, and response-barrier ordering; registry coverage for exactly-one terminal publication after durable metadata plus loud/retriable terminal delivery failure; SDK coverage with a shared real `createEventBus()` loading the actual extension, starting `printf api-ok`, reading bounded logs, observing exactly one terminal event after the run response, and killing a real sleep task without model/provider calls
+- extension EventBus API: unit coverage for `pi-background-tasks:request:v1`/`response:v1` closed-frame validation, exact capability handshake, malformed payload rejection, unknown keys, unknown operations, duplicate request IDs, missing `session_start`, shutdown refusal, unsubscribe, strict terminal frame shape, and response-barrier ordering; registry coverage for one terminal publication after durable metadata when emit succeeds plus loud/retriable delivery failure. A retry after a listener throws can redeliver to an earlier listener, so consumers deduplicate by task id. SDK coverage uses a shared real `createEventBus()`, starts `printf api-ok`, reads bounded logs, observes one terminal event after the run response, and kills a real sleep task without model/provider calls
 - attested Pi producer: unit/SDK coverage for 128-bit attested task ids, exact direct argv/cwd, ModelRegistry OAuth observation without secrets, raw Pi session/message events, separate stderr, prompt/report/source hashes, authority start/finish commit/tree/clean checks, atomic metadata serialization, completion visibility only after the sidecar is durable, malformed event rejection, and no attestation sidecar for ordinary tasks
 - agent activity transcript: pure `parseAgentActivity`/`formatAgentActivityLine` coverage (assistant text, reasoning, tool start with arg summary, silent successful tool end, `✗ tool failed` errors, truncation, invalid/non-activity narrowing); registry-unit coverage that wrapped-agent stdout is reconstructed across split chunks into the human-readable transcript while telemetry/activity control JSON is stripped from the output file (telemetry fields still updated), stderr passes through, and the trailing partial line is flushed on finalize; SDK coverage that fake and real child `pi --mode json` runs surface `→ tool`/`✗ tool failed`/assistant text in `bg_logs` with no control JSON leaking into the visible output
-- durability: `tests/unit/durable-fs.test.ts` covers the shared `src/core/durable-fs.ts` primitive through an injectable operations seam plus real-filesystem integration — single-open write/sync/close ordering, exclusive `wx` temp creation at `0o600`, direct `w` writes with inherited mode, the rule that a pathname is never reopened to flush it, temp ownership (a colliding temp created by another writer is never deleted), primary-versus-cleanup error precedence for write/sync/close/rename/remove failures, `renameCompleted` after a post-rename directory failure, the Windows directory-sync skip, atomic concurrent replacement, and fatal (never tolerated) `fsync` failures. `tests/package/package.test.ts` adds a mutation guard that fails if a read/read-write handle is used for `.sync()`, a path-based `fsyncFile` helper returns, or a sync failure is silently swallowed
+- durability: `tests/unit/durable-fs.test.ts` covers the shared `src/core/durable-fs.ts` primitive used for metadata, event/stderr buffers, attestations, delegate/Fusion artifacts, and configuration — single-open write/sync/close ordering, exclusive `wx` temp creation at `0o600`, direct `w` writes with inherited mode, never reopening a pathname merely to flush it, temp ownership, primary-versus-cleanup error precedence, `renameCompleted` after a post-rename directory failure, the Windows directory-sync skip, atomic replacement, and fatal `fsync` failures. Ordinary task `.output` is a streaming file ended/drained before terminal metadata and is not explicitly fsynced. `tests/package/package.test.ts` mutation guards pin the durable-helper invariants
 - safety: kill, already-finished kill failure, timeout failure, spawn failure, low output-cap failure, multi-task shutdown cleanup, POSIX process-group kill fallback, Windows `taskkill /T` then `/T /F` tree termination with shared soft attempts, soft-abort-on-force, exit-128 race tolerance, loud force failures, no root-only fallback, SIGKILL escalation that terminates instead of re-arming (a SIGKILL never schedules a further escalation, and concurrent stop requests share exactly one escalation timer that is cleared on finalize), duplicate finalization/notification races, metadata/notification failure handling, and pruning
-- agent loop: deterministic scripted-provider coverage against `extensions/background-tasks.ts` for actual event-driven `bg_run` behavior. The provider observes the effective system prompt, public tool descriptions, and real launch receipt and deliberately emits the pre-fix `bg_status` poll if any contract layer is absent; the passing path proves one launch, no sleep/status/log polling, one durable terminal notification, and exactly one follow-up turn. It also covers notification-only `triggerOnCompletion:false`, `/bg` display-only behavior, `notifyOnCompletion:false`, failed-task notification error fields, and parent-model `fusion_brainstorm` tool use followed by normal parent response
+- agent loop: deterministic scripted-provider coverage against `extensions/background-tasks.ts` for actual event-driven `bg_run` behavior. The provider observes the effective system prompt, public tool descriptions, and real launch receipt and deliberately emits the pre-fix `bg_status` poll if any contract layer is absent; the passing path proves one launch, no sleep/status/log polling, one durable terminal notification, and exactly one follow-up turn. It also covers notification-only `triggerOnCompletion:false`, `/bg` display-only behavior, `notifyOnCompletion:false`, failed-task notification error fields, and parent-model `fusion_reason` tool use followed by normal parent response
 - package: manifest, docs, `pi.extensions`, exported `src/core/extension-api.ts`, peer dependency/import parity, packed runtime files, tarball-install smoke, direct-completion import bans, test/helper/script/artifact exclusion, isolated offline npm installation, exact-version compatibility, and current-host persisted/replayed tool-usage safety
 
 ## PTY notes

package/TEST_PLAN.md

@@ -1,10 +1,12 @@
 # pi-background-tasks Test Plan
 
-This package follows:
+This package follows the package-local maintainer navigation:
 
-- [`../EXTENSION_PACKAGE_STANDARD.md`](../EXTENSION_PACKAGE_STANDARD.md)
-- [`../EXTENSION_QA_STANDARD.md`](../EXTENSION_QA_STANDARD.md)
-- [`../EXTENSION_TESTING_PLAYBOOK.md`](../EXTENSION_TESTING_PLAYBOOK.md)
+- `BACKGROUND-TASKS-INSTRUCTIONS.md` — required agent gateway/read order
+- [`docs/operations/testing.md`](docs/operations/testing.md) — gate selection and isolation
+- [`docs/operations/releasing.md`](docs/operations/releasing.md) — release/payload maintenance
+
+The table below remains the exhaustive acceptance source. Do not replace it with a generic summary.
 
 ## Package
 
@@ -13,12 +15,13 @@ This package follows:
 | Package | `pi-background-tasks` |
 | Extension entrypoint | `extensions/background-tasks.ts` |
 | Public commands | `/bg`, `/jobs`, `/logs`, `/kill`, `/tasks`, `/bg-tasks`, `/bg-clear`, `/bg-update`, `/fusion`, `/fusion-models` |
-| Public tools | `bg_run`, `bg_delegate`, `bg_result`, `bg_run_pi_attested`, `bg_status`, `bg_logs`, `bg_kill`, `fusion_brainstorm`, `fusion_validate` |
+| Public tools | `bg_run`, `bg_delegate`, `bg_result`, `bg_run_pi_attested`, `bg_status`, `bg_logs`, `bg_kill`, `fusion_reason`, `fusion_investigate`, `fusion_research`, `fusion_validate` |
 | Extension EventBus API | `pi-background-tasks:request:v1`, `pi-background-tasks:response:v1`, `pi-background-tasks:terminal:v1`; schemas exported from `src/core/extension-api.ts` |
 | Shortcuts | `Shift+Down`; optional fallback `Ctrl+Alt+C` |
 | Custom UI | footer status + focused bottom dock overlay |
 | Custom provider | no |
 | Runtime files/state | `.pi/tasks/<session-id>-<pid>/<task-id>.output`, `.pi/tasks/<session-id>-<pid>/<task-id>.json`; attested Pi opt-in adds `.pi-events.jsonl`, `.stderr`, `.pi-telemetry-wrapper.cjs`, `.attestation.json`; Fusion adds private `.pi/fusion/<session-id>-<pid>/<run-id>/` manifests/prompts/events/stderr/responses/evaluation/merged/error artifacts plus `context-omission-ledger.json` and `budget-plan.json` plus global `fusion-models.json` |
+| Maintainer docs/gateway | `BACKGROUND-TASKS-INSTRUCTIONS.md`, `docs/api/eventbus-v1.md`, `docs/concepts/context-projection-and-budgeting.md`, `docs/subsystems/child-launch-durability-and-safety.md`, `docs/reference/runtime-contracts.md`, `docs/operations/{troubleshooting,testing,releasing}.md`, `TESTING.md`, `TEST_PLAN.md`, `PUBLISHING.md` |
 
 ## Required gates
 
@@ -37,7 +40,25 @@ This package follows:
 | Smoke | `npm run smoke` | no | implemented; isolated load-only |
 | Large-context smoke | `npm run smoke:large-context` | release gate | implemented; rebuilds the production failure byte composition, proves the pre-fix input is rejected and the post-fix projection fits all four stages against the smallest configured route, with no inference and no child spawn |
 | Live subscription evidence | `npx tsx scripts/delegate-live-run.ts` | release gate | implemented; one real subscription-OAuth child on the parent's current route, large seeded session, hash-verified answer, and explicit leak checks. Caught two defects no offline gate did (undelivered prompt, seed-not-prompt budgeting), both now pinned by unit and mutation tests |
-| Compatibility | `npm run test:compat` | release gate | implemented; exact Pi `0.75.5`, `0.81.1`, `0.82.1`, `0.83.0` pack/install plus `/jobs`, `/fusion`, and `/fusion-models` surfaces, per-version bundled-TypeBox peer verification, removed-TypeBox-API scan of installed package bytes, followed by a current-host real `fusion_brainstorm` session-stat and replay witness |
+| Compatibility | `npm run test:compat` | release gate | implemented; exact Pi `0.81.1`, `0.82.1`, `0.83.0` pack/install plus `/jobs`, `/fusion`, and `/fusion-models` surfaces, per-version `agent_settled` event declaration and bundled-TypeBox peer verification, removed-TypeBox-API scan of installed package bytes, followed by a current-host real `fusion_reason` session-stat and replay witness |
+| Docs verification | `npm run docs:verify` | prepack/release gate | implemented; offline docs freshness, generated region/index/manifest/link/reachability/coverage/attestation checks |
+| Docs tests | `npm run test:docs` | targeted docs gate | implemented; docs-gate unit/package tests |
+| Payload policy | `npm run payload:check` | prepack/release gate | implemented; package payload/docs/assets exclusions and inclusions |
+| Release version sanity | `npm run release:check-version` | release gate | implemented; package version/tag sanity without advertising nonexistent tags |
+| Docs/gateway focused checks | frontmatter/link/version checks plus package docs gate when allowed | docs-only gate | implemented operationally; verifies `docs/**/*.md` frontmatter shape, package-local links, no standalone parent `../EXTENSION_*` links, package version wording from `package.json`, observed git tags, and documents current `docs:generate`/`docs:verify`/attestation workflow |
+
+## Fusion v1 public surface coverage
+
+Fusion v1 is a breaking public API release. Public tools are exactly `fusion_reason`, `fusion_investigate`, `fusion_research`, and `fusion_validate`; `fusion_brainstorm` is retired, removed from active tools on `session_start`, and not reactivated in resumed sessions. `/fusion` remains and maps to `fusion_reason` with no-tool candidates. `/fusion-models` remains shared.
+
+| Public surface | Contract |
+|---|---|
+| `fusion_reason({prompt})` | closed schema, visible-session projection with no candidate tools, no `capability` |
+| `fusion_investigate({objective, background, deliverable, scope?, constraints?})` | closed schema, optional arrays normalize to `[]`, clean-context read-only investigation |
+| `fusion_research({... sources:[{url,purpose}]})` | non-empty public `http(s)` sources, no credentials, canonical duplicate rejection; targeted URL fetch, not search, with URL exfiltration warning |
+| `fusion_validate({objective, background, changeSummary, scope, acceptanceCriteria, verification, knownLimitations?, exclusions?})` | `scope` and `acceptanceCriteria` non-empty; `verification.status:'provided'` requires evidence and no reason; `not_run` requires reason and no evidence; advisory/read-only, not a build/test substitute |
+
+SDK/RPC/scripted-provider/package/compatibility coverage asserts exactly four tools in discovery and active-tool repair, no public capability mode, direct `/fusion` result behavior, usage propagation, cancellation/shutdown, legacy v4 rendering, packed files, TypeBox enum schemas, and actionable legacy `fusion_validate({prompt})` migration errors.
 
 ## Feature coverage matrix
 
@@ -54,29 +75,29 @@ This package follows:
 | Read task logs | `bg_logs` | yes | yes |  |  |  |  | yes | SDK verifies bounded content and the model-facing no-wait-loop contract. Scripted-provider ordinary waiting makes zero log calls. |
 | Stop task from LLM tool | `bg_kill` |  | yes |  |  |  |  |  | Covers running kill and already-finished loud failure. |
 | Fusion command direct result | `/fusion`, `fusion-result` custom message | yes | yes | yes |  | yes | yes |  | Core unit covers deterministic v2 conversation-projection construction, explicit image omission markers without raw image data, direct final-text child argv/stdin/compact-metadata parsing, exact multi-block answer reconstruction, artifacts, pre-abort handling, and orchestration. SDK runs real `/fusion` against a fake child `pi`, verifies exactly five child text-mode invocations, hidden prompt persistence, visible exact merged custom message, no parent assistant rewrite, renderer output, progress/status behavior, no-argument editor flow, editor cancellation, and malformed config causing zero children. RPC verifies command discovery, `/fusion <prompt>` with U+2028/U+2029 content, custom-message result emission, no parent `agent_start`, no-argument editor protocol, malformed config/child failure visibility, and child isolation flags. PTY verifies `/fusion` renders the exact merged answer directly in a real TUI. Compatibility smoke runs `/fusion` through every supported Pi version with the installed package entrypoint. |
-| Fusion tool result | `fusion_brainstorm({prompt})` | yes | yes |  |  | current-host stats/replay | yes | yes | Tool is registered at load and re-added on `session_start`; no eligibility/quota/routine/justification gates are implemented. BUG-182 unit/SDK coverage pins the exact host `Usage` contract, complete cost-component aggregation, rejection of legacy `costTotal`, v2 child/result/manifest schemas, exact merged text, progress, context exclusion, and final details. The release compatibility gate drives a real current-host RPC agent through the tool, verifies persisted tool usage, invokes the same session-stat path used by the footer, then reopens the durable session and verifies identical stats. Scripted-provider coverage proves normal parent consumption and evaluator schema repair. |
+| Fusion v1 tool result | `fusion_reason`, `fusion_investigate`, `fusion_research`, `fusion_validate` | yes | yes |  |  | current-host stats/replay | yes | yes | Exactly four tools are registered/activated; `fusion_brainstorm` is removed from active tools. No public `capability` exists. BUG-182 coverage pins the exact host `Usage` contract, complete cost-component aggregation, v4 result rendering, exact merged text, progress, context exclusion, and final details. The compatibility gate drives a real current-host RPC agent through `fusion_reason`, verifies persisted tool usage, invokes the same session-stat path used by the footer, then reopens the durable session and verifies identical stats. |
 | Fusion Anthropic child sanitization | `@ravshansbox/pi-anthropic-sps` dependency, child `--extension` argv | yes |  |  |  |  | yes |  | Unit proves a Claude route receives exactly two `--extension` paths with the metadata extension first and the sanitizer second, that every non-Anthropic provider still receives exactly one and never resolves the sanitizer at all, and that the real installed package resolves to an existing file through its manifest `pi.extensions[0]`. Resolution failures are each pinned as loud errors: package unresolvable, manifest unreadable, manifest not JSON, missing `pi` section, empty `pi.extensions`, blank entry, and a declared file that does not exist. Package guards require the sanitizer to be a declared dependency and require the provider gate so non-Anthropic child argv cannot drift. |
-| Fusion validation workflow | `fusion_validate({prompt})`, workflow profiles, `fusion-manifest.v3`, `fusion-result.v4` | yes |  |  |  |  | yes |  | Unit pins the brainstorm profile to the exact pre-extraction prompt constants so the workflow seam is proven byte-neutral, binds the validate profile to its own four system prompts, and asserts the two workflows share one evaluation schema contract and one repair framing. Validate orchestration covers five children with validate framing, candidates always `inspect` while evaluator and merger stay `reason`, tool-call log paths assigned only to candidates, `workflow` plus a `v`-prefixed run id persisted in the manifest and result details, and prompt artifacts byte-identical to the bytes handed to each child. A caller capability contradicting the fixed workflow policy is rejected before the artifact store exists and launches **zero** children; the same capability stated explicitly is accepted. Golden bytes pin a separate committed validate corpus, prove canonical input and omission ledger are identical across workflows for every case, and prove budget plans move for every case so the profile provably reaches the budget engine. Package guards reject `capability` and extra keys on `fusion_validate`, pin `FUSION_VALIDATE_CAPABILITY` to `inspect`, require `fusion_validate` in both the Fusion and delegate denylists, and pin the workflow-invariant comments at exactly one occurrence per launch site. |
-| Fusion conversation projection | canonical input `fusion-input.v4`, `context-omission-ledger.json` | yes | yes | yes |  |  | yes |  | Unit covers a >1 MB synthetic tool-heavy session staying within budget, verbatim user/assistant text, thinking exclusion, zero tool-payload preview bytes (head/tail sentinels absent), exact and stable omission counts/byte totals/hashes, tuple round-trip preservation of roles/source ordinals/block ordinals/exact text, byte-identical repeated construction and separate-process determinism, hash change on omitted-payload mutation without exposing the payload, ledger root hash unchanged by compact encoding, contiguous omission-run collapsing into compact `["o", span, bytes, [thinking, toolCalls, toolResults]]` tuples, material canonical-input byte reduction versus the verbose object encoding, receipt-to-ledger reconciliation through `projection_map`, active-tool-call-leaf and sibling-call exclusion, marker-only user images plus ledger-only tool-result images with no base64, per-entry-point policy ids and request authority, and the exactly-one-disposition property for every retained block. SDK verifies the exact child stdin carries `conversation_projection` and never `conversation_transcript`. RPC verifies the versioned request object. A dedicated high-cardinality fixture (340 receipt runs over 1,360 omitted events with incident-matching visible-text volume) pins per-receipt cost and proves the pre-fix verbose format would overflow the merge stage while the compact tuple format fits. Package tests assert the ledger artifact ships in the documented artifact set. |
+| Fusion validation workflow | structured `fusion_validate`, workflow profiles, `fusion-manifest.v4`, `fusion-result.v5` | yes | yes |  |  |  | yes |  | Public validation rejects legacy `{prompt}` with a migration error, enforces non-empty `scope`/`acceptanceCriteria`, and loudly validates `verification` cross-fields (`provided` ↔ evidence, `not_run` ↔ reason). Core validate orchestration is clean/read-only/advisory, enforces source-finding accounting including singleton, duplicate, exclusion, and merger add/drop cases, and remains no build/test substitute claim. |
+| Fusion context boundaries | canonical input `fusion-input.v5`, reason `context-omission-ledger.json`, clean-task inputs | yes | yes | yes |  |  | yes |  | Unit covers reason/session projection for a >1 MB synthetic tool-heavy session, verbatim user/assistant text, thinking exclusion, zero tool-payload preview bytes, exact and stable omission counts/byte totals/hashes, compact tuple round-trip, receipt-to-ledger reconciliation, active-tool-call-leaf and sibling-call exclusion, and byte-identical repeated construction. Clean-task tests assert investigate/research/validate inputs omit parent system prompt, conversation projection, and omission ledger, stay byte-identical across unrelated parent sessions, and keep parent sentinels out of every clean downstream prompt and artifact. SDK/RPC verify clean validate stdin has no `conversation_projection` or transcript while `/fusion`/reason preserve the projected-conversation path. |
 | Fusion stage budgets | `budget-plan.json` (v3 per-stage forecasts), typed `prompt_budget_exceeded_forecast` / `prompt_budget_exceeded_measured` | yes |  |  |  |  |  |  | Unit covers the per-family affine estimator, additive segment accounting, multibyte 1.0-token/byte charging, unknown-provider floor visibility, byte-capacity route selection, scope guards for small windows, input-only fatal preflight versus warning-only reservations, rejection of unknown/zero/negative/too-small context windows, boundary accept at exactly the limit and reject one byte past, the child system prompt counted as input, per-stage forecasts built from the real prompt builders against each stage's own route, reservation warnings, breach-detector artifacts, safe prompts completing all five calls, persisted route/plan snapshots including negative slack on fatal rejection, and the reproduced 1 MB failure shape now fitting the smallest configured budget. Errors carry stage, measured size, allowed size, limiting model, estimator source, and remediation in both structured detail and message text. |
-| Fusion candidate capability profiles | `fusion_brainstorm({prompt, capability?})`, candidate child argv | yes | yes |  |  |  | yes |  | Unit covers `reason` defaulting; reason and inspect argv remain byte-identical; `inspect` argv is exactly `--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` argv is the inspect allowlist plus `fusion_web_fetch`, with the same denylist. Unit also proves capability-specific prompts, research env only for research children, candidate tool-call log paths assigned only to candidates, and evaluator plus merger calls staying `reason`/`--no-tools` under caller-selected inspect or research. SDK and package guards validate only `reason`/`inspect`/`research`, reject extra keys, pin the allow/deny lists and `fusion_web_fetch` tool name, and assert evaluator/merger launch sites cannot read the caller-selected capability. |
-| Fusion research web fetch | `fusion_web_fetch({ url, extract? })`, `candidate-<slot>.attempt-<n>.tool-calls.jsonl` | yes |  |  |  |  | yes | live child | Unit covers the closed schema surface through the child extension, registration only when research mode is enabled, unsupported schemes and URL credentials failing before network access, blocked DNS classes, a mixed public-plus-blocked DNS answer failing loudly, a redirect to a blocked address failing loudly, redirect-loop limit failure, Content-Length and streamed-body response caps, unsupported content types, Markdown extraction preserving links/headings/tables/code blocks, script/style stripping, text/plain passthrough with hash and byte count, UTF-8-safe output truncation, and typed timeout. Unit also proves the resolver is consulted once and the connection is pinned to that vetted address, and that audit metadata records `url`, `final_url`, `http_status`, `response_bytes`, and `content_sha256` without raw page content. Package guards require `fusion_web_fetch` registration behind the research env flag. Live verification fetched `https://example.com/`, reported the page H1, read a repository constant, and refused instruction-like text from both a repo file and the fetched page. |
+| Fusion fixed-purpose profiles | `/fusion`, `fusion_reason`, `fusion_investigate`, `fusion_research`, `fusion_validate`, candidate child argv | yes | yes | yes |  |  | yes |  | Public surface has no caller-selected capability. SDK/RPC pin `/fusion` to reason/no-tool candidates; investigate is read-only, research is targeted URL fetch with public http(s) source validation, and evaluator/merger remain no-tools by stage policy. Package guards reject extra keys and verify schemas are closed. |
+| Fusion research web fetch | `fusion_web_fetch({ url, extract? })`, `candidate-<slot>.attempt-<n>.tool-calls.jsonl` | yes |  |  |  |  | yes | live child | Unit covers the closed schema surface through the child extension, registration only when research mode is enabled, unsupported schemes and URL credentials failing before network access, blocked DNS classes, a mixed public-plus-blocked DNS answer failing loudly, a redirect to a blocked address failing loudly, redirect-loop limit failure, Content-Length and streamed-body response caps, unsupported content types, Markdown extraction preserving links/headings/tables/code blocks, script/style stripping, text/plain passthrough with hash and byte count, UTF-8-safe output truncation, and typed timeout. Unit also proves the resolver is consulted once and the connection is pinned to that vetted address, undeclared research URLs are rejected before fetch with only the attempted URL hash audited, and that audit metadata records `url`, `final_url`, `http_status`, `response_bytes`, and `content_sha256` without raw page content. Package guards require `fusion_web_fetch` registration behind the research env flag. Live verification fetched `https://example.com/`, reported the page H1, read a repository constant, and refused instruction-like text from both a repo file and the fetched page. |
 | Fusion multi-message transcript validation | `*.events.jsonl`, stop reasons `toolUse`/`stop` | yes |  |  |  |  |  |  | Unit accepts a multi-message tool loop, reconstructs stdout from the final assistant message only, and sums usage across all compact metadata records. Non-final records must be `toolUse`, the final record must be `stop`, and `length`, `error`, `aborted`, and `pending` fail loudly instead of being skipped. |
 | Fusion stale-action watchdog | `FUSION_CHILD_IDLE_TIMEOUT_MS`, child process lifecycle | yes |  |  |  |  |  |  | Unit proves a child with no stdout or stderr activity fails as `child_timeout` with the stalled-child message and is terminated; stderr activity resets the watchdog and allows success; the 30-minute absolute timeout path remains distinct and is not reported as a stalled child. |
-| Fusion candidate tool-call audit log | `candidate-<slot>.attempt-<n>.tool-calls.jsonl`, `pi-background-tasks.fusion-tool-call.v1` | yes |  |  |  |  |  |  | Unit proves completed tool calls are logged with tool name, byte counts, and hashes while raw arguments/results containing a secret never appear; a complete 3-call log summarizes count and result bytes; zero completed calls is a complete trace; a trailing partial line, ordinal gap, duplicate ordinal, wrong schema version, and inspect-child partial log all fail loudly. Artifact coverage verifies successful attempts persist the JSONL and manifest summary, while no-log attempts do not invent one. |
+| Fusion candidate tool-call audit log | `candidate-<slot>.attempt-<n>.tool-calls.jsonl`, `*.seal.json`, `pi-background-tasks.fusion-tool-call.v1` | yes |  |  |  |  |  |  | Unit proves completed tool calls are logged with tool name, byte counts, and hashes while raw arguments/results containing a secret never appear. Repeated low-level `agent_end` boundaries publish no seal; terminal `agent_settled` exclusively seals the complete log after all retry/compaction/follow-up work. The 46-call incident regression proves a 22-call prefix is never sealed and duplicate settlement fails without replacement. Shutdown before settlement writes failed evidence and latches process failure. The parent rejects extension diagnostics and missing/failed/mismatched seals and independently rejects aggregate result bytes above 8 MiB. A trailing partial line, ordinal gap, duplicate ordinal, wrong schema version, and inspect-child partial log all fail loudly. |
 | Pi/TypeBox compatibility | `peerDependencies`, packed bytes | yes |  |  |  |  | yes |  | Unit pins typebox as a `"*"` peer that is neither a runtime nor bundled dependency, requires the resolved TypeBox to be Pi 0.83's 1.3.x line, requires all four supported Pi/TUI lines in the peer range, scans all package TypeScript for the seven removed TypeBox APIs, and compiles the shipped tool schema plus nullable-array/nullable-string and optional-field shapes under TypeBox 1.3. The release compat gate repeats the removed-API scan against installed package bytes per Pi version. |
 | Pi hook contract | `npm run test:hook-contract`, `tests/scripted-provider/pi-hook-contract-evidence.json`, `src/core/delegate/hook-contract-evidence.json` |  |  |  |  |  | evidence parity | yes | Executes a real Pi agent loop and records, rather than assumes: `context` fires once before every model call in load order; returned messages reach the provider; **throwing** in `context` does NOT block dispatch (Pi catches and continues); `ctx.abort()` does not skip the call site but delivers an already-aborted signal and terminates the run; `tool_result` fires before the transcript entry, chains in load order, replacement reaches the provider while the original does not, and toolCallId/role/`isError` survive. Handler ordering across two separate probe extensions is pinned. The evidence file is compared, never silently regenerated, and a package test asserts the shipped copy is byte-identical. |
 | Delegate context seeding | `bg_delegate` seed `pi-background-tasks.delegate-seed.v1`, `seed.json`, `context-omission-ledger.json` | yes | yes |  |  |  | mutation guard | yes | Unit covers verbatim visible user/assistant text, complete exclusion of thinking/tool-call arguments/tool-result payloads, marker-only images with no raw bytes anywhere in the seed, exclusion of the in-flight `bg_delegate` call **and every sibling call in the same assistant message** (two delegates launched together get byte-identical projected history), the prompt preserved exactly and marked `explicit_text` authority, zero payload-preview bytes, byte-identical construction across repeated builds and across separate processes via a fixed-leaf fixture, and refusal of a blank prompt. Receive-side verification rejects a single mutated byte, a foreign task identity, a structurally malformed seed whose hash matches, a directive whose hash disagrees with its text, and an unsupported capability. SDK proves the projected parent text actually reaches the child. |
 | Delegate route pinning | `bg_delegate` `route`, `route_attestations` | yes | yes |  |  |  | mutation guard | yes | Unit covers defaulting to the parent current model, explicit pinning, refusal of an unavailable route with `route_unresolved` and no substitution, refusal of a route with no declared context window with `route_capacity_unknown` rather than assuming one, and refusal when neither is available. The result package rejects a mismatched route, a mismatched attestation, and a package carrying no attestation at all. The scripted-provider gate proves an observed route drift prevents a success commit entirely. The mutation guard fails if a fallback list or first-available selection appears. |
 | Delegate budget and guard | `budget-plan.json`, typed `seed_budget_exceeded` / `provider_context_budget_exhausted` | yes | yes |  |  |  | mutation guard | yes | Unit covers reserve subtraction, exact-boundary accept and one-byte-past reject, the child system prompt counted as input, multi-byte UTF-8 measured by bytes, refusal of unusable windows without defaulting, and a total runtime governor that cannot throw from inside a hook. Preflight rejection is proven to create **zero** children and **zero** artifacts for hook-contract, budget, and blank-prompt refusals, with the artifact directory verified absent. The scripted-provider gate proves an over-budget model call is blocked in a real agent loop and produces a typed terminal record with no committed result. |
 | Delegate tool-result spilling | `spill/` artifacts, `pi-background-tasks.delegate-receipt.v1`, `delegate_read_artifact` | yes | yes |  |  |  | mutation guard | yes | Unit proves a 2 MB payload is written in full, hashed, and represented by a receipt carrying `(turn_sequence, source_call_index, tool_call_id)` assigned before execution, so parallel spills completing out of order cannot be mis-associated; an aggregate-cap refusal writes nothing and emits no receipt; bounded range reads return exactly the requested bytes; a range past end-of-file, a path escaping the artifact directory, and non-positive lengths are refused rather than shortened. The scripted-provider gate proves in a real agent loop that the raw payload never enters the transcript, the transcript instead carries a receipt naming the hash and stating nothing was truncated, and an over-long range read fails loudly. |
-| Delegate result commit and `bg_result` | `result.json` (`pi-background-tasks.delegate-result.v1`), `bg_result` | yes | yes |  |  |  | mutation guard | yes | The single atomically-committed package is the sole answer data plane: temp-write, fsync, rename, directory fsync, with the rename as the commit point. Unit covers round-trip verification, multi-block concatenation, exact preservation of U+2028/U+2029/emoji/unnormalized sequences, refusal of lone surrogates rather than U+FFFD substitution, detection of block-hash, aggregate-hash, declared-length, and non-strict-base64 corruption, foreign identity/seed rejection, and explicitly unavailable usage that is never reported as zero. Terminal evaluation treats a zero-exit child with no committed package as typed `child_exited_without_commit`, reports the child-recorded reason when present, and classifies a killed task as cancelled. SDK covers not-ready (non-blocking), completed, corrupted, route-drift, and unknown-task paths, and proves an oversized answer degrades to an artifact reference while an explicit inline request fails with `result_too_large_for_inline` and is never truncated. |
-| Delegate isolation boundary | child argv, `--session-id`, `--session-dir`, `--tools` | yes | yes |  |  |  | mutation guard | yes | Unit proves the child receives its own session id and a task-owned session directory, no `--continue`/`--resume`/`--session`/`--fork`, only the inspect tool set, an explicit denylist covering `bash`/`edit`/`write`/`bg_delegate`/`fusion_brainstorm`, disabled discovery of extensions/skills/prompt templates/themes/context files, exactly one explicitly loaded package guard extension, explicit provider/model with no `--api-key`, and parent session identity stripped from the child environment. SDK verifies the same facts from the argv and environment the child actually observed. |
+| Delegate result commit and `bg_result` | `result.json` (`pi-background-tasks.delegate-result.v1`), `bg_result` | yes | yes |  |  |  | mutation guard | yes | The single atomically-committed package is the sole answer data plane: temp-write, file fsync, and rename, with the rename as the commit point; POSIX additionally fsyncs the parent directory while Windows explicitly lacks that portable directory-entry guarantee. Unit covers round-trip verification, multi-block concatenation, exact preservation of U+2028/U+2029/emoji/unnormalized sequences, refusal of lone surrogates rather than U+FFFD substitution, detection of block-hash, aggregate-hash, declared-length, and non-strict-base64 corruption, foreign identity/seed rejection, and explicitly unavailable usage that is never reported as zero. Terminal evaluation treats a zero-exit child with no committed package as typed `child_exited_without_commit`, reports the child-recorded reason when present, and classifies a killed task as cancelled. SDK covers not-ready (non-blocking), completed, corrupted, route-drift, and unknown-task paths, and proves an oversized answer degrades to an artifact reference while an explicit inline request fails with `result_too_large_for_inline` and is never truncated. |
+| Delegate isolation boundary | child argv, `--session-id`, `--session-dir`, `--tools` | yes | yes |  |  |  | mutation guard | yes | Unit proves the child receives its own session id and a task-owned session directory, no `--continue`/`--resume`/`--session`/`--fork`, only the inspect tool set, an explicit denylist covering `bash`/`edit`/`write`/`bg_delegate` and all current/retired Fusion tools, disabled discovery of extensions/skills/prompt templates/themes/context files, exactly one explicitly loaded package guard extension, explicit provider/model with no `--api-key`, and parent session identity stripped from the child environment. SDK verifies the same facts from the argv and environment the child actually observed. |
 | Fusion artifact byte immutability | `canonical-input.json`, `context-omission-ledger.json`, `budget-plan.json` | yes |  |  |  |  | shared-source guard |  | A 28-case differential corpus is rendered to raw bytes and compared against a committed golden file that is never auto-updated once present, and separately against `tests/oracle/fusion-context-pre-extraction.ts`, a verbatim pre-extraction copy of the projection engine used as an **independent oracle**. Equivalence covers canonical input, ledger, and budget-plan bytes, `Object.is` comparison of budget floats including `utilization`, field-for-field accounting parity, ledger root hashes, and identical error type and message for unknown blocks and blank requests. The package guard now scans the shared `context/` modules, not only the Fusion facade, and pins both the shared divisor definition and Fusion's binding to it. |
 | Fusion model selector | `/fusion-models`, `fusion-models.json`, `FusionModelSelector` | yes | yes | yes | yes | yes | yes |  | Unit covers strict config parsing, duplicates, slash-containing model IDs, stale model failures, `$current`, atomic save, inter-process lock/revision compare-and-swap, and deterministic concurrent-save conflict. Component covers all five slots, duplicate selection, searchable model list, stale display, reset/save/cancel, persistence errors, and width safety. SDK drives the real command in a synthetic TUI context without `ctx.mode` to cover old Pi compatibility and verifies duplicate `$current`/explicit model persistence; SDK also verifies headless no-UI rejection. RPC verifies non-TUI notification without hanging, PTY verifies the real selector opens in a TUI, and compatibility smoke verifies print-mode rejection for every supported Pi version. |
 | Fusion child isolation/lifecycle | child `pi --mode text`, private compact metadata extension, shutdown cleanup, `.pi/fusion` artifacts | yes | yes | yes |  | current-host stats/replay | yes |  | BUG-180 coverage proves final-text transport, reasoning exclusion, strict response reconstruction, unchanged caps, isolation, process cleanup, failure artifacts, and lifecycle semantics. BUG-182 upgrades the private compact metadata and artifact manifest to v2, preserves all token and cost components, centralizes clone/add/empty operations, rejects missing/legacy/unknown/non-finite cost shapes, and proves successful plus failed/cancelled attempt costs aggregate exactly once. SDK/RPC verify public child isolation; session shutdown tracks initializing and live runs. |
 | Extension request/response service | `pi-background-tasks:request:v1` → `pi-background-tasks:response:v1` | yes | yes |  |  |  | yes |  | Unit covers closed-frame validation, capability handshake, unknown keys, unknown operation, duplicate request IDs, missing `session_start`, shutdown refusal, strict `run.payload`, strict malformed frames, and unsubscribe. SDK loads the real extension with a shared `createEventBus()`, starts `printf api-ok`, reads bounded logs, lists status, starts and kills a real sleep task, and checks malformed/unknown/duplicate controls without model/provider calls. Package tests assert `src/core/extension-api.ts` ships. |
-| Terminal EventBus publication | `pi-background-tasks:terminal:v1` | yes | yes |  |  |  | yes |  | Registry unit proves exactly-one terminal snapshot after durable metadata and loud/retriable EventBus delivery failure; extension API unit proves one strict terminal frame correlated by task id after the run response for immediate, normal, failed, timeout, and killed tasks; SDK observes one terminal event for a completed task and one for a killed task through the real extension service. |
+| Terminal EventBus publication | `pi-background-tasks:terminal:v1` | yes | yes |  |  |  | yes |  | Registry unit proves one terminal snapshot after durable metadata when EventBus emit succeeds and loud/retriable delivery failure. Because retry after a listener throws may redeliver to an earlier listener, consumers must deduplicate by task id. Extension API unit proves one strict terminal frame correlated by task id after the run response for immediate, normal, failed, timeout, and killed tasks; SDK observes one terminal event for a completed task and one for a killed task through the real extension service. |
 | Completion notification | custom message `background-task-notification` | yes | yes |  | renderer via typecheck |  |  | yes | BUG-181 unit/SDK coverage pins the durable-terminal guidance and truthful effective delivery receipts. Scripted provider loads the shipped extension, conditionally attempts the old `bg_status` poll when the real system prompt/descriptions/receipt are incomplete, and proves the fixed contract instead yields with exactly one `bg_run`, one terminal notification, and one default follow-up. Notification-only, notification-disabled, failed-task, and display-only `/bg` paths remain covered. |
 | Footer status | `ctx.ui.setStatus` |  | load path + clear command/shortcut + mixed states/focused label |  | render semantics | yes |  |  | SDK verifies `/bg-clear` hint, failed/stopped/done combinations, running combinations, and focused label; PTY verifies Shift+Down dock path after footer-visible task. |
 | Explicit agent classification | required `bg_run.isAgent`, `/bg --agent`, task metadata | yes | yes |  |  |  |  | yes | `isAgent:true` is required only for LLM/agent tasks and enables Pi-agent telemetry wrapping when the command invokes plain `pi`; `isAgent:false` is required for scripts/non-agents and prevents wrapping even if the command text looks like `pi -p ...`. |
@@ -92,9 +113,9 @@ This package follows:
 | Dock rerun | `R` |  |  |  | yes | yes |  |  | Component plus PTY running/completed/failed/killed rerun paths. |
 | Dock close | `x`/`Esc`/`q` |  |  |  | yes | yes |  |  | Component + PTY. |
 | Shortcut opens dock | `Shift+Down` |  | registration |  |  | yes |  |  | PTY sends xterm `ESC [ 1 ; 2 B`. |
-| Clear finished notices | `/bg-clear`, optional `Ctrl+Alt+C` fallback |  | yes | yes |  |  |  |  | `/bg-clear` is the canonical terminal-independent path and is advertised in the footer. SDK invokes the slash-command handler and verifies fallback shortcut registration; RPC verifies `/bg-clear` clears finished notices; finished notices remain until explicit clear. |
+| Clear finished notices | `/bg-clear`, optional `Ctrl+Alt+C` fallback |  | yes | yes |  |  |  |  | `/bg-clear` is the canonical terminal-independent path and is advertised while unseen finished tasks exist and the dock is closed. SDK invokes the slash-command handler and verifies fallback shortcut registration; RPC verifies `/bg-clear` clears finished notices. Opening a finished task's detail marks that task seen; merely opening the list or closing the dock does not clear other badges. |
 | Update-available footer notice | `⬆ v<latest> /bg-update` footer segment + `/bg-update` command | yes | yes | yes |  |  |  |  | Unit covers semver parse/compare/precedence, `isNewerVersion`, `formatUpdateSegment`, npm/`package.json` payload narrowing, injected-fetch success/404/throw/timeout, and `package.json` read/degrade. SDK uses a localhost registry to verify the idle and append-to-active footer segment, `/bg-update` non-installing instructions, and that opt-out (`PI_BG_DISABLE_UPDATE_CHECK=1`), offline (`PI_OFFLINE=1`), already-current, and registry-failure paths render no segment and never throw. RPC verifies `/bg-update` discovery and offline non-installing instructions. The check is one-shot per `session_start`, time-boxed, offline-safe, and never runs on the status tick. |
-| Durable file writes | `src/core/durable-fs.ts` (task metadata, output/events/stderr, attestations, Fusion artifacts, `fusion-models.json`) | yes |  |  |  |  | mutation guard |  | Unit covers single-open write/sync/close ordering, exclusive `wx` temp at `0o600`, direct `w` writes with inherited mode, never reopening a pathname to flush it, temp ownership (never deleting another writer's colliding temp), primary-versus-cleanup error precedence across write/sync/close/rename/remove, `renameCompleted` after post-rename directory failure, the Windows directory-sync skip, real-filesystem overwrite/atomic-replace/concurrency, and fatal `fsync` failures. Package mutation guard fails if a read/read-write handle is used for `.sync()`, a path-based `fsyncFile` returns, or a sync failure is silently swallowed. Fixes the Windows `EPERM: operation not permitted, fsync` reported in PR #1. |
+| Durable file writes | `src/core/durable-fs.ts` (metadata, event/stderr buffers, attestations, delegate/Fusion artifacts, `fusion-models.json`) | yes |  |  |  |  | mutation guard |  | Unit covers single-open write/sync/close ordering, exclusive `wx` temp at `0o600`, direct `w` writes with inherited mode, never reopening a pathname to flush it, temp ownership (never deleting another writer's colliding temp), primary-versus-cleanup error precedence across write/sync/close/rename/remove, `renameCompleted` after post-rename directory failure, the Windows directory-sync skip, real-filesystem overwrite/atomic-replace/concurrency, and fatal `fsync` failures. Ordinary task `.output` uses a streaming writer that is ended/drained before terminal metadata but is not explicitly fsynced; the durable-fs claim does not extend to that stream. Package mutation guards pin the durable helper invariants. Fixes the Windows `EPERM: operation not permitted, fsync` reported in PR #1. |
 | Runtime output files | `.pi/tasks/...output` | yes | yes |  |  |  |  |  | SDK asserts existence. |
 | Runtime metadata files | `.pi/tasks/...json` | yes | yes |  |  |  |  |  | SDK asserts shape/status/name/context usage; registry unit tests cover metadata failure/update ordering. |
 | Timeout kills task | `timeoutSeconds` |  | yes |  |  |  |  |  | SDK. |
@@ -103,6 +124,9 @@ This package follows:
 | Process lifecycle/races | registry core | yes | yes | yes |  | yes |  | yes | Unit tests cover POSIX process-group fallback, Windows `taskkill /T` then `/T /F` tree termination, SIGKILL escalation, duplicate finalization/notification races, notification/metadata failures, pruning, malformed telemetry, split telemetry chunks, large telemetry records above the old 16KiB buffer, and wrapped-agent transcript/telemetry separation with split-chunk and trailing-partial flush; SDK/RPC cover runtime spawn/timeout/output-cap/shutdown; scripted provider covers wakeup integration. |
 | Package manifest | `package.json` |  |  |  |  |  | yes |  | Keywords, `pi.extensions`, files, local smoke/compat scripts, and direct-completion import bans. |
 | Pack contents | `npm pack --dry-run` |  |  |  |  |  | yes |  | Runtime files included; tests, fake child helpers, release-only scripts, artifacts, nested tarballs, and `node_modules` excluded. Default tarball install test uses isolated HOME/XDG/npm cache and offline peer-ignore install from the local tarball. |
+| Maintainer docs gateway | `BACKGROUND-TASKS-INSTRUCTIONS.md` | docs focused |  |  |  |  |  |  | Gateway requires INDEX → read-before-edit → owning-doc navigation, records current docs generate/verify/attestation workflow, preserves subscription-only frontier routing, parent/child tool separation, durability/integrity, and no self-certification. Logo reference is package-local (`docs/assets/logo.svg`) when the asset-owner file is present. |
+| Shared architecture/API/runtime/operations docs | `docs/api`, `docs/concepts`, `docs/subsystems`, `docs/reference`, `docs/operations` | docs focused |  |  |  |  |  |  | The active docs engine validates frontmatter, package-local links/reference links, INDEX reachability, exact behavioral source ownership, generated runtime contracts, deterministic generated regions, manifest freshness, and semantic receipts. Unsupported extraction and legacy placeholders fail closed. |
+| Package maintenance version/tag wording | `PUBLISHING.md`, `docs/operations/releasing.md` | docs focused |  |  |  |  |  |  | Release commands derive `VERSION` from `package.json`; observed git tags stop at `v0.6.0`, so git install/tag certification is separate from npm publishing and no nonexistent v1 tag is advertised. |
 
 ## Residual hardening coverage
 
@@ -136,3 +160,5 @@ Lane A residual hardening is now covered by automated tests. No remaining harden
 - [x] No real LLM/API/network dependency in default tests.
 - [x] No dependency on user/global `~/.pi/agent` for SDK/RPC/PTY tests.
 - [x] Volatile output is normalized in snapshot-style assertions where applicable.
+- [x] Docs/gateway freshness has a focused package-local check path and documents the current package `docs:*` workflow for unconstrained runs.
+- [x] Release wording derives from `package.json` version and does not advertise nonexistent git tags.

package/docs/INDEX.md

@@ -0,0 +1,157 @@
+---
+doc_id: INDEX
+audience: user
+mode: generated
+review_policy: contract
+stability: stable
+covers_surfaces: []
+covers_sources: []
+---
+# Documentation index
+
+Generated navigation for every package-local documentation page. This index intentionally owns no public surface and no production source; ownership is explicit in each primary doc's frontmatter.
+
+## Start here
+
+- [Getting started](./getting-started.md)
+- [Choose a workflow](./choose-a-workflow.md)
+- [Read before editing production sources](./read-before-edit.md)
+- [Runtime contracts](./reference/runtime-contracts.md)
+
+## Docs by audience
+
+### agent
+
+| Doc | Mode | Review | Stability |
+| --- | --- | --- | --- |
+| [concepts/completion-delivery](./concepts/completion-delivery.md) | authored | contract | stable |
+| [concepts/context-projection-and-budgeting](./concepts/context-projection-and-budgeting.md) | authored | behavioral | evolving |
+| [read-before-edit](./read-before-edit.md) | generated | contract | stable |
+| [tools/bg_delegate](./tools/bg_delegate.md) | mixed | contract | stable |
+| [tools/bg_kill](./tools/bg_kill.md) | mixed | contract | stable |
+| [tools/bg_logs](./tools/bg_logs.md) | mixed | contract | stable |
+| [tools/bg_result](./tools/bg_result.md) | mixed | contract | stable |
+| [tools/bg_run](./tools/bg_run.md) | mixed | contract | stable |
+| [tools/bg_run_pi_attested](./tools/bg_run_pi_attested.md) | mixed | contract | stable |
+| [tools/bg_status](./tools/bg_status.md) | mixed | contract | stable |
+| [tools/fusion_investigate](./tools/fusion_investigate.md) | mixed | contract | stable |
+| [tools/fusion_reason](./tools/fusion_reason.md) | mixed | contract | stable |
+| [tools/fusion_research](./tools/fusion_research.md) | mixed | contract | stable |
+| [tools/fusion_validate](./tools/fusion_validate.md) | mixed | contract | stable |
+
+### maintainer
+
+| Doc | Mode | Review | Stability |
+| --- | --- | --- | --- |
+| [api/eventbus-v1](./api/eventbus-v1.md) | mixed | behavioral | evolving |
+| [operations/configuration](./operations/configuration.md) | authored | contract | stable |
+| [operations/releasing](./operations/releasing.md) | authored | contract | evolving |
+| [operations/testing](./operations/testing.md) | authored | contract | evolving |
+| [operations/troubleshooting](./operations/troubleshooting.md) | authored | contract | evolving |
+| [reference/runtime-contracts](./reference/runtime-contracts.md) | mixed | contract | evolving |
+| [subsystems/attested-pi-runs](./subsystems/attested-pi-runs.md) | authored | behavioral | evolving |
+| [subsystems/background-task-runtime](./subsystems/background-task-runtime.md) | authored | behavioral | stable |
+| [subsystems/child-launch-durability-and-safety](./subsystems/child-launch-durability-and-safety.md) | authored | behavioral | evolving |
+| [subsystems/delegation](./subsystems/delegation.md) | authored | behavioral | evolving |
+| [subsystems/docs-freshness-gate](./subsystems/docs-freshness-gate.md) | mixed | contract | stable |
+| [subsystems/fusion](./subsystems/fusion.md) | mixed | behavioral | stable |
+| [subsystems/host-ui-and-telemetry](./subsystems/host-ui-and-telemetry.md) | authored | behavioral | stable |
+
+### user
+
+| Doc | Mode | Review | Stability |
+| --- | --- | --- | --- |
+| [choose-a-workflow](./choose-a-workflow.md) | authored | contract | stable |
+| [commands/bg](./commands/bg.md) | mixed | contract | stable |
+| [commands/bg-clear](./commands/bg-clear.md) | mixed | contract | stable |
+| [commands/bg-update](./commands/bg-update.md) | mixed | contract | stable |
+| [commands/fusion](./commands/fusion.md) | mixed | contract | stable |
+| [commands/fusion-models](./commands/fusion-models.md) | mixed | contract | stable |
+| [commands/jobs](./commands/jobs.md) | mixed | contract | stable |
+| [commands/kill](./commands/kill.md) | mixed | contract | stable |
+| [commands/logs](./commands/logs.md) | mixed | contract | stable |
+| [commands/task-manager](./commands/task-manager.md) | mixed | contract | stable |
+| [getting-started](./getting-started.md) | authored | contract | stable |
+| [INDEX](./INDEX.md) | generated | contract | stable |
+| [reference/shortcuts-and-dock](./reference/shortcuts-and-dock.md) | mixed | contract | stable |
+
+## Docs by category
+
+- **api**: [api/eventbus-v1](./api/eventbus-v1.md)
+- **commands**: [commands/bg](./commands/bg.md), [commands/bg-clear](./commands/bg-clear.md), [commands/bg-update](./commands/bg-update.md), [commands/fusion](./commands/fusion.md), [commands/fusion-models](./commands/fusion-models.md), [commands/jobs](./commands/jobs.md), [commands/kill](./commands/kill.md), [commands/logs](./commands/logs.md), [commands/task-manager](./commands/task-manager.md)
+- **concepts**: [concepts/completion-delivery](./concepts/completion-delivery.md), [concepts/context-projection-and-budgeting](./concepts/context-projection-and-budgeting.md)
+- **operations**: [operations/configuration](./operations/configuration.md), [operations/releasing](./operations/releasing.md), [operations/testing](./operations/testing.md), [operations/troubleshooting](./operations/troubleshooting.md)
+- **reference**: [reference/runtime-contracts](./reference/runtime-contracts.md), [reference/shortcuts-and-dock](./reference/shortcuts-and-dock.md)
+- **root**: [choose-a-workflow](./choose-a-workflow.md), [getting-started](./getting-started.md), [INDEX](./INDEX.md), [read-before-edit](./read-before-edit.md)
+- **subsystems**: [subsystems/attested-pi-runs](./subsystems/attested-pi-runs.md), [subsystems/background-task-runtime](./subsystems/background-task-runtime.md), [subsystems/child-launch-durability-and-safety](./subsystems/child-launch-durability-and-safety.md), [subsystems/delegation](./subsystems/delegation.md), [subsystems/docs-freshness-gate](./subsystems/docs-freshness-gate.md), [subsystems/fusion](./subsystems/fusion.md), [subsystems/host-ui-and-telemetry](./subsystems/host-ui-and-telemetry.md)
+- **tools**: [tools/bg_delegate](./tools/bg_delegate.md), [tools/bg_kill](./tools/bg_kill.md), [tools/bg_logs](./tools/bg_logs.md), [tools/bg_result](./tools/bg_result.md), [tools/bg_run](./tools/bg_run.md), [tools/bg_run_pi_attested](./tools/bg_run_pi_attested.md), [tools/bg_status](./tools/bg_status.md), [tools/fusion_investigate](./tools/fusion_investigate.md), [tools/fusion_reason](./tools/fusion_reason.md), [tools/fusion_research](./tools/fusion_research.md), [tools/fusion_validate](./tools/fusion_validate.md)
+
+## Public surface owners
+
+| Surface | Primary doc |
+| --- | --- |
+| `command:bg` | [commands/bg](./commands/bg.md) |
+| `command:bg-clear` | [commands/bg-clear](./commands/bg-clear.md) |
+| `command:bg-tasks` | [commands/task-manager](./commands/task-manager.md) |
+| `command:bg-update` | [commands/bg-update](./commands/bg-update.md) |
+| `command:fusion` | [commands/fusion](./commands/fusion.md) |
+| `command:fusion-models` | [commands/fusion-models](./commands/fusion-models.md) |
+| `command:jobs` | [commands/jobs](./commands/jobs.md) |
+| `command:kill` | [commands/kill](./commands/kill.md) |
+| `command:logs` | [commands/logs](./commands/logs.md) |
+| `command:tasks` | [commands/task-manager](./commands/task-manager.md) |
+| `eventbus:background-task-v1` | [api/eventbus-v1](./api/eventbus-v1.md) |
+| `renderer:background-task-notification` | [concepts/completion-delivery](./concepts/completion-delivery.md) |
+| `renderer:fusion-result` | [subsystems/fusion](./subsystems/fusion.md) |
+| `shortcut:ctrl+alt+c` | [reference/shortcuts-and-dock](./reference/shortcuts-and-dock.md) |
+| `shortcut:shift+down` | [reference/shortcuts-and-dock](./reference/shortcuts-and-dock.md) |
+| `tool:bg_delegate` | [tools/bg_delegate](./tools/bg_delegate.md) |
+| `tool:bg_kill` | [tools/bg_kill](./tools/bg_kill.md) |
+| `tool:bg_logs` | [tools/bg_logs](./tools/bg_logs.md) |
+| `tool:bg_result` | [tools/bg_result](./tools/bg_result.md) |
+| `tool:bg_run` | [tools/bg_run](./tools/bg_run.md) |
+| `tool:bg_run_pi_attested` | [tools/bg_run_pi_attested](./tools/bg_run_pi_attested.md) |
+| `tool:bg_status` | [tools/bg_status](./tools/bg_status.md) |
+| `tool:fusion_investigate` | [tools/fusion_investigate](./tools/fusion_investigate.md) |
+| `tool:fusion_reason` | [tools/fusion_reason](./tools/fusion_reason.md) |
+| `tool:fusion_research` | [tools/fusion_research](./tools/fusion_research.md) |
+| `tool:fusion_validate` | [tools/fusion_validate](./tools/fusion_validate.md) |
+| `workflow:investigate` | [subsystems/fusion](./subsystems/fusion.md) |
+| `workflow:reason` | [subsystems/fusion](./subsystems/fusion.md) |
+| `workflow:research` | [subsystems/fusion](./subsystems/fusion.md) |
+| `workflow:validate` | [subsystems/fusion](./subsystems/fusion.md) |
+
+## Public surface inventory
+
+| Kind | Name | ID | Provenance |
+| --- | --- | --- | --- |
+| command | `bg` | `command:bg` | `src/extension.ts:506` |
+| command | `bg-clear` | `command:bg-clear` | `src/extension.ts:548` |
+| command | `bg-tasks` | `command:bg-tasks` | `src/extension.ts:540` |
+| command | `bg-update` | `command:bg-update` | `src/extension.ts:556` |
+| command | `fusion` | `command:fusion` | `src/fusion-extension.ts:891` |
+| command | `fusion-models` | `command:fusion-models` | `src/fusion-extension.ts:914` |
+| command | `jobs` | `command:jobs` | `src/extension.ts:594` |
+| command | `kill` | `command:kill` | `src/extension.ts:638` |
+| command | `logs` | `command:logs` | `src/extension.ts:607` |
+| command | `tasks` | `command:tasks` | `src/extension.ts:532` |
+| tool | `bg_delegate` | `tool:bg_delegate` | `src/delegate-extension.ts:265` |
+| tool | `bg_kill` | `tool:bg_kill` | `src/extension.ts:897` |
+| tool | `bg_logs` | `tool:bg_logs` | `src/extension.ts:852` |
+| tool | `bg_result` | `tool:bg_result` | `src/delegate-extension.ts:428` |
+| tool | `bg_run` | `tool:bg_run` | `src/extension.ts:671` |
+| tool | `bg_run_pi_attested` | `tool:bg_run_pi_attested` | `src/extension.ts:756` |
+| tool | `bg_status` | `tool:bg_status` | `src/extension.ts:821` |
+| tool | `fusion_investigate` | `tool:fusion_investigate` | `src/fusion-extension.ts:1049` |
+| tool | `fusion_reason` | `tool:fusion_reason` | `src/fusion-extension.ts:1032` |
+| tool | `fusion_research` | `tool:fusion_research` | `src/fusion-extension.ts:1066` |
+| tool | `fusion_validate` | `tool:fusion_validate` | `src/fusion-extension.ts:1084` |
+| shortcut | `ctrl+alt+c` | `shortcut:ctrl+alt+c` | `src/extension.ts:586` |
+| shortcut | `shift+down` | `shortcut:shift+down` | `src/extension.ts:579` |
+| renderer | `background-task-notification` | `renderer:background-task-notification` | `src/extension.ts:415` |
+| renderer | `fusion-result` | `renderer:fusion-result` | `src/fusion-extension.ts:875` |
+| eventbus | `background-task-v1` | `eventbus:background-task-v1` | `src/core/extension-api.ts` |
+| workflow | `investigate` | `workflow:investigate` | `src/core/fusion/workflows.ts:80` |
+| workflow | `reason` | `workflow:reason` | `src/core/fusion/workflows.ts:61` |
+| workflow | `research` | `workflow:research` | `src/core/fusion/workflows.ts:99` |
+| workflow | `validate` | `workflow:validate` | `src/core/fusion/workflows.ts:118` |