pi-background-tasks 0.9.0 → 1.0.4

package/docs/operations/configuration.md

@@ -0,0 +1,110 @@
+---
+doc_id: operations/configuration
+audience: maintainer
+mode: authored
+review_policy: contract
+stability: stable
+covers_surfaces: []
+covers_sources: []
+---
+# Configuration
+
+This page lists operator-facing configuration found in source. It intentionally does not invent undocumented environment variables.
+
+## Update check
+
+At `session_start`, the extension performs a one-shot, time-boxed npm latest-version lookup. Failures are offline-safe: the footer simply shows no update segment.
+
+| Variable | Effect |
+|---|---|
+| `PI_BG_DISABLE_UPDATE_CHECK=1` | Skip the update check. |
+| `PI_OFFLINE=1` | Skip the update check. |
+| `PI_BG_REGISTRY_URL=<url>` | Use a registry mirror instead of `https://registry.npmjs.org`. |
+
+`/bg-update` only prints update commands; it does not install or self-update.
+
+## Shell selection
+
+### POSIX
+
+For ordinary `bg_run` and `/bg` shell commands, non-Windows platforms use `SHELL` when it is set, otherwise `/bin/sh`.
+
+### Windows
+
+Windows defaults to `cmd.exe`/`ComSpec`. The generic `SHELL` variable is ignored on Windows so existing `cmd` syntax does not silently change language.
+
+| Variable | Effect |
+|---|---|
+| `PI_BG_SHELL=cmd` | Use Windows `cmd` dialect. |
+| `PI_BG_SHELL=bash` | Use POSIX-style `bash -c` on Windows. |
+| `PI_BG_SHELL_PATH=<absolute .exe/.com>` | Explicit shell path; requires `PI_BG_SHELL`. |
+
+Invalid Windows shell settings fail loudly instead of falling back. `bash` is invoked with `-c`, not `-lc`.
+
+## Output and log caps
+
+| Setting/surface | Value/behavior |
+|---|---|
+| `PI_BG_MAX_OUTPUT_BYTES` | Optional environment override for task output cap. Default is 20 MiB. Exceeding it fails/kills the task rather than claiming success. |
+| `bg_logs.maxBytes` / `/logs <id> [maxBytes]` | Bounded model-visible read. The package cap is 50 KiB. |
+| Full output | Written under `.pi/tasks/<session-id>-<pid>/<task-id>.output`. |
+
+Bounded logs are for context safety; they point to the full local output file when more bytes exist.
+
+## Pi-agent telemetry opt-out
+
+| Variable | Effect |
+|---|---|
+| `PI_BG_DISABLE_PI_TELEMETRY=1` | Do not wrap shell commands that appear to launch `pi -p ...` or `pi --mode json ...` when `isAgent:true`. Raw stdout is preserved. |
+
+Telemetry wrapping is best-effort and task-owned. Missing telemetry is reported as unavailable, never as zero. Under Windows `cmd`, safe interception is unavailable and the command is left unchanged.
+
+## Fusion model configuration
+
+Fusion model slots are stored globally under the Pi agent directory as:
+
+```text
+fusion-models.json
+```
+
+Use `/fusion-models` in TUI mode to configure five slots:
+
+- Candidate 1
+- Candidate 2
+- Candidate 3
+- Evaluator
+- Merger
+
+Missing config means all five slots are `$current`. Config entries are qualified `provider/model` selections or `$current`; malformed config, stale explicit models, unavailable current models, and concurrent selector conflicts fail loudly before child inference.
+
+Fusion accepts frontier-model routes only through Pi Anthropic or Codex subscription OAuth where `ModelRegistry.isUsingOAuth` confirms the route. Metered frontier API-key/base-URL paths are rejected before child creation, and relevant metered environment variables are stripped from Fusion children.
+
+## Fusion runtime limits
+
+These are source constants, not documented operator env knobs:
+
+| Limit | Value |
+|---|---:|
+| Child absolute timeout | 30 minutes |
+| Child stale-output watchdog | 20 minutes |
+| Child stdout cap | 32 MiB |
+| Child stderr cap | 4 MiB |
+| Candidate output contract | 48 KiB JSON-rendered bytes |
+| Evaluator output contract | 64 KiB JSON-rendered bytes |
+| Merger output contract | 64 KiB JSON-rendered bytes |
+| `fusion_web_fetch` timeout | 60 seconds |
+| `fusion_web_fetch` response body cap | 2 MiB |
+| `fusion_web_fetch` returned content cap | 32 KiB |
+| `fusion_web_fetch` redirect cap | 5 hops |
+
+Oversized Fusion outputs fail loudly and are preserved in local artifacts where applicable. They are not forwarded or silently truncated.
+
+## Offline behavior
+
+- Update checks skip when `PI_OFFLINE=1` and degrade to no footer update segment on any lookup failure.
+- Background shell commands may still do whatever the command does; the package does not block their network access.
+- Fusion child model calls require configured Pi model routes. `fusion_research` additionally requires network access to the caller-supplied public URLs it fetches.
+
+## Durability and platform note
+
+Task metadata, delegate/Fusion artifacts, attestation sidecars, and `fusion-models.json` use durable write helpers. Ordinary task `.output` streams are ended and drained before terminal publication but are not explicitly fsynced. POSIX performs directory `fsync` after atomic replacement. Windows still flushes replaced file contents before rename and treats rename failures as fatal, but it does not get the same portable directory-entry crash-durability guarantee.

package/docs/operations/releasing.md

@@ -0,0 +1,67 @@
+---
+doc_id: operations/releasing
+audience: maintainer
+mode: authored
+review_policy: contract
+stability: evolving
+covers_surfaces: []
+covers_sources: []
+---
+# Releasing operations
+
+Package maintenance entrypoint: `PUBLISHING.md`. Source version is always `package.json`; never hard-code a release version in commands.
+
+```bash
+VERSION=$(node -p "require('./package.json').version")
+printf 'pi-background-tasks@%s\n' "$VERSION"
+```
+
+Current observed standalone git tags stop at `v0.6.0`. Do not advertise or certify a `v1.x` git install tag until that tag exists in the standalone package repository.
+
+## Ordinary release checks
+
+Run from the `pi-background-tasks` package root in an isolated environment. These are release-candidate checks, not tag certification:
+
+```bash
+npm run typecheck
+npm run test:type-safety
+npm run test:unit
+npm run test:sdk
+npm run test:rpc
+npm run test:component
+npm run test:package
+npm run test:hook-contract
+npm run smoke
+npm run smoke:large-context
+npm run pack:dry-run
+npm run docs:verify
+npm run payload:check
+# On a tag ref only: GITHUB_REF_TYPE=tag GITHUB_REF_NAME=v$VERSION npm run release:check-version
+npm run test:compat
+npm view pi-background-tasks name version --json
+```
+
+`npm run test:full` additionally runs PTY and scripted-provider agent-loop gates. Treat it as a full interactive gate; do not run it for routine docs edits.
+
+Live evidence (`npx tsx scripts/delegate-live-run.ts`) is release-time and performs real subscription-OAuth inference. It must never use API-key/metered frontier channels.
+
+## Payload verification
+
+Use `npm pack --dry-run --json` output as the payload source of truth. Verify at minimum:
+
+- `extensions/background-tasks.ts` is included as the Pi entrypoint;
+- runtime `src/` files needed by the entrypoint are included;
+- `docs/`, `README.md`, `TESTING.md`, `TEST_PLAN.md`, `PUBLISHING.md`, `BACKGROUND-TASKS-INSTRUCTIONS.md`, root `logo.png`, and `LICENSE` are included per current `package.json.files`;
+- tests, scripts, node_modules, local `.pi/` artifacts, generated evidence not meant for runtime, and nested tarballs are excluded;
+- TypeBox remains a Pi-provided peer and no private/nested runtime TypeBox copy is bundled;
+- docs/assets/gateway/logo inclusion matches `package.json.files` exactly.
+
+## Tag certification vs npm publishing
+
+Separate these activities:
+
+1. **npm release candidate:** version comes from `package.json`; run ordinary release checks; inspect pack payload; publish only on operator approval.
+2. **git tag certification:** verify the standalone repo is at the exact release commit, clean, and already has or is about to receive tag `v$VERSION`. `npm run release:check-version` requires an explicit tag ref (`GITHUB_REF_TYPE=tag`, `GITHUB_REF_NAME=v$VERSION`) and never publishes. Tags currently observed stop at `v0.6.0`, so `v$VERSION` is not certified merely because npm has that version.
+3. **post-publish install smoke:** install by `npm:pi-background-tasks@$VERSION` in an isolated Pi agent dir. Use git install smoke only after the corresponding standalone tag exists.
+
+No auto-publish. No automated push/tag from repair runs unless the operator explicitly asks.

package/docs/operations/testing.md

@@ -0,0 +1,101 @@
+---
+doc_id: operations/testing
+audience: maintainer
+mode: authored
+review_policy: contract
+stability: evolving
+covers_surfaces: []
+covers_sources: []
+---
+# Testing operations
+
+Package entry docs: `TESTING.md` and `TEST_PLAN.md`. This page explains how to choose gates without losing the detailed coverage matrix.
+
+## Isolation defaults
+
+Automated package tests should use isolated temp project/agent/session directories and these defaults unless a test intentionally overrides them:
+
+```bash
+PI_OFFLINE=1
+PI_SKIP_VERSION_CHECK=1
+PI_TELEMETRY=0
+CI=1
+```
+
+Never point tests at the user's real `~/.pi/agent`.
+
+## Current package scripts
+
+From current `package.json`:
+
+| Lane | Script | Meaning |
+|---|---|---|
+| Typecheck | `npm run typecheck` | `tsc --noEmit`. |
+| Type safety package tests | `npm run test:type-safety` | Package/type-safety tests. |
+| Unit | `npm run test:unit` | Pure/unit coverage, including durable fs, budgets, projection, Fusion/delegate core. |
+| SDK | `npm run test:sdk` | Real package entrypoint through SDK-style harnesses. |
+| RPC | `npm run test:rpc` | RPC command/tool surface. |
+| Component | `npm run test:component` | TUI component rendering/key behavior. |
+| Package | `npm run test:package` | Manifest/payload/mutation/package guards. |
+| Hook contract | `npm run test:hook-contract` | Real Pi hook characterization evidence comparison. |
+| Default | `npm run test` | Typecheck + type-safety + unit + SDK + RPC + component + package + hook-contract. |
+| PTY | `npm run test:pty` | Real expect/TUI scenarios; full gate only. |
+| Agent loop | `npm run test:agent-loop` | Scripted-provider real agent-loop behavior; full gate only. |
+| Full | `npm run test:full` | Default + PTY + agent-loop. |
+| Smoke | `npm run smoke` | Isolated load-only `/jobs`. |
+| Large context smoke | `npm run smoke:large-context` | Offline Fusion context/budget reproduction; no inference/child spawn. |
+| Compatibility | `npm run test:compat` | Release-only exact Pi version install/compat plus current-host witness. |
+| Pack | `npm run pack:dry-run` | Release payload preview. |
+| Docs generate | `npm run docs:generate` | Regenerates generated docs regions/index/manifest. |
+| Docs verify | `npm run docs:verify` | Offline, read-only deterministic docs freshness verification; renders generated files twice in memory and compares committed bytes. |
+| Docs attestation | `npm run docs:attest/record -- <doc_id> --reviewer <identity-after-semantic-review> --verdict PASS --notes <review-notes>` | Computes hashes and records an explicit semantic PASS receipt after review; `npm run docs:attest` is an alias and still needs args. |
+| Docs unit/package gate | `npm run test:docs` | Docs-gate unit/package tests. |
+| Payload check | `npm run payload:check` | Package payload policy check. |
+| Release version check | `npm run release:check-version` | Tag-only version sanity; requires explicit `GITHUB_REF_TYPE=tag`/`GITHUB_REF_NAME=v$VERSION` and never publishes. |
+
+Do not run full/default/root suites for documentation-only edits unless the operator explicitly asks. If the operator restricts verification to focused checks, report that `docs:verify`/attestation were not run.
+
+## Evidence that must be preserved
+
+`TESTING.md` and `TEST_PLAN.md` intentionally carry exhaustive QA knowledge. Do not replace them with generic summaries.
+
+Preserve especially:
+
+- Pi hook contract evidence and byte-identical shipped copy behavior;
+- Fusion golden-byte and independent oracle coverage;
+- delegate seed/budget/artifact/result/guard/mutation coverage;
+- scripted-provider no-poll/no-sleep follow-up behavior;
+- PTY keyboard-protocol negotiation notes;
+- compatibility TypeBox peer/payload checks;
+- live subscription evidence caveat: it is release-time, real inference, and subscription OAuth only.
+
+## Focused docs checks
+
+When a change is constrained to focused docs checks, use targeted checks such as:
+
+```bash
+python3 - <<'PY'
+from pathlib import Path
+for p in [*Path('docs').rglob('*.md'), Path('TESTING.md'), Path('TEST_PLAN.md'), Path('PUBLISHING.md')]:
+    if p.exists(): print(p)
+PY
+```
+
+Recommended focused checks for docs changes:
+
+1. frontmatter schema on `docs/**/*.md`;
+2. package-local markdown links resolve;
+3. no standalone links to removed parent `../EXTENSION_*` standards;
+4. docs workflow wording matches current `package.json` scripts;
+5. version/tag references derive from `package.json` or observed git tags.
+
+These checks are not substitutes for code gates when source behavior changes.
+
+## Gate selection
+
+- **Doc-only navigation/release wording:** focused link/frontmatter/version checks.
+- **EventBus docs vs API changes:** EventBus unit/SDK targeted tests if code changed; otherwise focused docs checks.
+- **Context projection/budget changes:** unit tests for projection/budget/golden/oracle; do not update goldens casually.
+- **Durability/launch changes:** durable-fs, pi-launch, Windows argv targeted units.
+- **Delegate guard changes:** hook contract, delegate unit/SDK/scripted-provider targeted gates.
+- **Release candidate:** ordinary release checks in `docs/operations/releasing.md`; live subscription evidence only when explicitly certifying release behavior.

package/docs/operations/troubleshooting.md

@@ -0,0 +1,38 @@
+---
+doc_id: operations/troubleshooting
+audience: maintainer
+mode: authored
+review_policy: contract
+stability: evolving
+covers_surfaces: []
+covers_sources: []
+---
+# Troubleshooting
+
+Start from the symptom, verify the source-owned doc, then apply the remediation. Do not tier-bump models, switch routes, or add fallbacks to make a failure disappear.
+
+| Symptom/error | Likely cause | Remediation |
+|---|---|---|
+| EventBus response says `request frame must be an object`, `unknown key`, `schema_version mismatch`, or duplicate `request_id` | Request frame violates the closed EventBus v1 schema | Fix caller frame to match `docs/api/eventbus-v1.md`; never relax closed-frame validation. |
+| EventBus says service unavailable before `session_start` | Extension API is installed but no session context exists | Start/await Pi session startup; do not fabricate a context. |
+| Terminal event arrives unexpectedly early in a consumer | Consumer is not waiting for the `run` response before correlating task id, or an older implementation lacks the gate | Bind response first; current API gates terminal publication for `run`/`kill`. See `docs/api/eventbus-v1.md`. |
+| `bg_run` starts but logs are bounded/truncated | `bg_logs` is model-visible and capped by design | Read the full output file path from the notice only when operator-approved; do not increase model-visible logs casually. |
+| Output cap terminates a task | `PI_BG_MAX_OUTPUT_BYTES` cap reached | Inspect full command behavior; raise cap only deliberately for that run environment. The task failure is intentional safety. |
+| `PI_BG_SHELL` or `PI_BG_SHELL_PATH` error on Windows | Windows shell selection is closed and path-validated | Use `PI_BG_SHELL=cmd` or `bash`; if setting `PI_BG_SHELL_PATH`, provide an absolute `.exe`/`.com`. See `docs/subsystems/child-launch-durability-and-safety.md`. |
+| `pi_executable_resolution_failed` | Windows Pi package bin cannot be resolved/validated | Reinstall/repair Pi package; do not fall back to shell PATH shims. |
+| `pi_command_line_too_long` | Rendered Windows command line exceeds 32,767 UTF-16 units | Move large payload to stdin/artifact path; do not truncate argv. |
+| Terminal metadata/output durability failure | Fsync/close/metadata write failed | Treat terminal state as failed; inspect `DurableFileError` operation/path/cause. See `docs/subsystems/child-launch-durability-and-safety.md`. |
+| Delegate refuses with `delegate_hook_contract_unsupported` | Current Pi hook behavior does not match committed evidence | Re-run the hook characterization gate during release work and re-review the guard; do not weaken the guard. See `docs/operations/testing.md`. |
+| Delegate refuses with `route_unresolved` or `route_capacity_unknown` | Requested/default route unavailable or lacks usable context window | Pin an available provider/model with declared context window; no substitute route is selected. |
+| Delegate refuses with `seed_budget_exceeded` | Frozen seed plus child prompt/system prompt exceeds allowed input tokens | Use a larger-context subscription route, delegate earlier, or reduce visible parent text. Nothing was clipped. |
+| `bg_result` says not ready | Child has not committed `result.json` yet | Wait for terminal notification or inspect later; do not poll tightly. |
+| Delegate result corruption/hash/identity mismatch | Result package does not match task/seed/route/hash contract | Treat as invalid; inspect artifact bytes. Do not synthesize an answer. |
+| Fusion model unavailable or metered route refusal | Frontier route is not admitted as a Pi subscription/OAuth route, or configured model is stale | Fix `/fusion-models` config to available subscription routes. Never route GPT/Claude-class work through metered APIs. |
+| Fusion prompt budget exceeded | Stage forecast or measured prompt exceeds limiting route capacity | Use larger configured routes or reduce explicit request/context. Do not route-substitute after planning. |
+| Fusion child timeout vs idle timeout | Absolute timeout is 30 minutes; idle watchdog is 20 minutes of no stdout/stderr activity | Preserve distinction in errors. `FUSION_CHILD_IDLE_TIMEOUT_MS` is a source constant, not documented as env-configurable. |
+| Fusion research URL rejected | Source URL is not declared/public http(s), has credentials, resolves to blocked address class, or redirects unsafely | Provide declared public source URLs with purpose; targeted fetch is not search. |
+| `/fusion-models` rejects in non-TUI mode | Selector requires interactive UI | Use an interactive Pi TUI session to edit config; headless path should fail loudly. |
+| `/bg-update` shows no update | Offline/opt-out/current-version/registry failure path | Check `PI_OFFLINE`, `PI_BG_DISABLE_UPDATE_CHECK`, `PI_BG_REGISTRY_URL`; update check is one-shot and non-blocking. |
+| TypeBox/compat failure | Installed package resolved a private/nested TypeBox or used removed APIs | Keep TypeBox as Pi-provided peer and verify installed payload. See `docs/operations/releasing.md`. |
+
+Detailed references: EventBus API (`docs/api/eventbus-v1.md`), context budgeting (`docs/concepts/context-projection-and-budgeting.md`), launch/durability (`docs/subsystems/child-launch-durability-and-safety.md`), runtime registry (`docs/reference/runtime-contracts.md`), testing (`docs/operations/testing.md`), releasing (`docs/operations/releasing.md`).

package/docs/read-before-edit.md

@@ -0,0 +1,94 @@
+---
+doc_id: read-before-edit
+audience: agent
+mode: generated
+review_policy: contract
+stability: stable
+covers_surfaces: []
+covers_sources: []
+---
+# Read before editing production sources
+
+Every production file under `src/**` and `extensions/**` has exactly one primary behavioral documentation owner. This file is generated from authored ownership frontmatter and owns no production source itself.
+
+## Source ownership
+
+| Source | Primary behavioral owner |
+| --- | --- |
+| `extensions/background-tasks.ts` | [subsystems/host-ui-and-telemetry](./subsystems/host-ui-and-telemetry.md) |
+| `extensions/delegate-child.ts` | [subsystems/delegation](./subsystems/delegation.md) |
+| `extensions/fusion-child.ts` | [subsystems/fusion](./subsystems/fusion.md) |
+| `src/core/attested-pi-run.ts` | [subsystems/attested-pi-runs](./subsystems/attested-pi-runs.md) |
+| `src/core/common.ts` | [subsystems/background-task-runtime](./subsystems/background-task-runtime.md) |
+| `src/core/context/parent-snapshot.ts` | [concepts/context-projection-and-budgeting](./concepts/context-projection-and-budgeting.md) |
+| `src/core/context/token-budget.ts` | [concepts/context-projection-and-budgeting](./concepts/context-projection-and-budgeting.md) |
+| `src/core/context/visible-conversation-v2.ts` | [concepts/context-projection-and-budgeting](./concepts/context-projection-and-budgeting.md) |
+| `src/core/delegate/artifacts.ts` | [subsystems/delegation](./subsystems/delegation.md) |
+| `src/core/delegate/budget.ts` | [subsystems/delegation](./subsystems/delegation.md) |
+| `src/core/delegate/hook-contract-evidence.json` | [subsystems/delegation](./subsystems/delegation.md) |
+| `src/core/delegate/hook-contract.ts` | [subsystems/delegation](./subsystems/delegation.md) |
+| `src/core/delegate/launch.ts` | [subsystems/delegation](./subsystems/delegation.md) |
+| `src/core/delegate/result-package.ts` | [subsystems/delegation](./subsystems/delegation.md) |
+| `src/core/delegate/runner.ts` | [subsystems/delegation](./subsystems/delegation.md) |
+| `src/core/delegate/seed.ts` | [subsystems/delegation](./subsystems/delegation.md) |
+| `src/core/delegate/types.ts` | [subsystems/delegation](./subsystems/delegation.md) |
+| `src/core/durable-fs.ts` | [subsystems/child-launch-durability-and-safety](./subsystems/child-launch-durability-and-safety.md) |
+| `src/core/extension-api.ts` | [api/eventbus-v1](./api/eventbus-v1.md) |
+| `src/core/fusion/artifacts.ts` | [subsystems/fusion](./subsystems/fusion.md) |
+| `src/core/fusion/budget.ts` | [subsystems/fusion](./subsystems/fusion.md) |
+| `src/core/fusion/child-protocol.ts` | [subsystems/fusion](./subsystems/fusion.md) |
+| `src/core/fusion/clean-context.ts` | [subsystems/fusion](./subsystems/fusion.md) |
+| `src/core/fusion/config.ts` | [subsystems/fusion](./subsystems/fusion.md) |
+| `src/core/fusion/context.ts` | [subsystems/fusion](./subsystems/fusion.md) |
+| `src/core/fusion/evaluation.ts` | [subsystems/fusion](./subsystems/fusion.md) |
+| `src/core/fusion/orchestrator.ts` | [subsystems/fusion](./subsystems/fusion.md) |
+| `src/core/fusion/pi-child.ts` | [subsystems/fusion](./subsystems/fusion.md) |
+| `src/core/fusion/prompts.ts` | [subsystems/fusion](./subsystems/fusion.md) |
+| `src/core/fusion/source-policy.ts` | [subsystems/fusion](./subsystems/fusion.md) |
+| `src/core/fusion/types.ts` | [subsystems/fusion](./subsystems/fusion.md) |
+| `src/core/fusion/web-fetch.ts` | [subsystems/fusion](./subsystems/fusion.md) |
+| `src/core/fusion/workflows.ts` | [subsystems/fusion](./subsystems/fusion.md) |
+| `src/core/pi-launch.ts` | [subsystems/child-launch-durability-and-safety](./subsystems/child-launch-durability-and-safety.md) |
+| `src/core/registry.ts` | [subsystems/background-task-runtime](./subsystems/background-task-runtime.md) |
+| `src/core/update-check.ts` | [subsystems/host-ui-and-telemetry](./subsystems/host-ui-and-telemetry.md) |
+| `src/core/windows-taskkill.ts` | [subsystems/background-task-runtime](./subsystems/background-task-runtime.md) |
+| `src/delegate-child-extension.ts` | [subsystems/delegation](./subsystems/delegation.md) |
+| `src/delegate-extension.ts` | [subsystems/delegation](./subsystems/delegation.md) |
+| `src/extension.ts` | [subsystems/host-ui-and-telemetry](./subsystems/host-ui-and-telemetry.md) |
+| `src/fusion-child-extension.ts` | [subsystems/fusion](./subsystems/fusion.md) |
+| `src/fusion-extension.ts` | [subsystems/fusion](./subsystems/fusion.md) |
+| `src/ui/background-tasks-manager.ts` | [subsystems/host-ui-and-telemetry](./subsystems/host-ui-and-telemetry.md) |
+| `src/ui/fusion-model-selector.ts` | [subsystems/fusion](./subsystems/fusion.md) |
+
+## Public surfaces
+
+- `command:bg`
+- `command:bg-clear`
+- `command:bg-tasks`
+- `command:bg-update`
+- `command:fusion`
+- `command:fusion-models`
+- `command:jobs`
+- `command:kill`
+- `command:logs`
+- `command:tasks`
+- `eventbus:background-task-v1`
+- `renderer:background-task-notification`
+- `renderer:fusion-result`
+- `shortcut:ctrl+alt+c`
+- `shortcut:shift+down`
+- `tool:bg_delegate`
+- `tool:bg_kill`
+- `tool:bg_logs`
+- `tool:bg_result`
+- `tool:bg_run`
+- `tool:bg_run_pi_attested`
+- `tool:bg_status`
+- `tool:fusion_investigate`
+- `tool:fusion_reason`
+- `tool:fusion_research`
+- `tool:fusion_validate`
+- `workflow:investigate`
+- `workflow:reason`
+- `workflow:research`
+- `workflow:validate`

package/docs/reference/runtime-contracts.md

@@ -0,0 +1,213 @@
+---
+doc_id: reference/runtime-contracts
+audience: maintainer
+mode: mixed
+review_policy: contract
+stability: evolving
+covers_surfaces: []
+covers_sources: []
+---
+# Runtime contracts reference
+
+This generated registry lists production environment-variable references, runtime paths/artifacts, schema identifiers, and status vocabularies extracted from package source. It intentionally excludes incidental source-code literals such as package metadata import paths.
+
+<!-- pi-docs:begin name="runtime-contracts" generator="scripts/docs/generate.mjs" -->
+### Environment variable references
+
+| Name | Access | Provenance |
+| --- | --- | --- |
+| `ANTHROPIC_API_KEY` | remove | `src/core/attested-pi-run.ts:135`<br>`src/core/fusion/pi-child.ts:70` |
+| `ANTHROPIC_AUTH_TOKEN` | remove | `src/core/fusion/pi-child.ts:70` |
+| `ANTHROPIC_BASE_URL` | remove | `src/core/attested-pi-run.ts:135`<br>`src/core/fusion/pi-child.ts:70` |
+| `AZURE_OPENAI_AD_TOKEN` | remove | `src/core/fusion/pi-child.ts:70` |
+| `AZURE_OPENAI_API_KEY` | remove | `src/core/fusion/pi-child.ts:70` |
+| `AZURE_OPENAI_API_VERSION` | remove | `src/core/fusion/pi-child.ts:70` |
+| `AZURE_OPENAI_BASE_URL` | remove | `src/core/fusion/pi-child.ts:70` |
+| `AZURE_OPENAI_DEPLOYMENT_NAME_MAP` | remove | `src/core/fusion/pi-child.ts:70` |
+| `AZURE_OPENAI_ENDPOINT` | remove | `src/core/fusion/pi-child.ts:70` |
+| `AZURE_OPENAI_RESOURCE_NAME` | remove | `src/core/fusion/pi-child.ts:70` |
+| `ComSpec` | read | `src/core/common.ts:683`<br>`src/core/common.ts:692` |
+| `OPENAI_API_KEY` | remove | `src/core/attested-pi-run.ts:135`<br>`src/core/fusion/pi-child.ts:70` |
+| `OPENAI_BASE_URL` | remove | `src/core/attested-pi-run.ts:135`<br>`src/core/fusion/pi-child.ts:70` |
+| `OPENROUTER_API_KEY` | remove | `src/core/attested-pi-run.ts:135`<br>`src/core/fusion/pi-child.ts:70` |
+| `OPENROUTER_BASE_URL` | remove | `src/core/attested-pi-run.ts:135`<br>`src/core/fusion/pi-child.ts:70` |
+| `path` | read | `src/core/common.ts:638` |
+| `Path` | read | `src/core/common.ts:638` |
+| `PATH` | read | `src/core/common.ts:638` |
+| `PI_API_BASE_URL` | remove | `src/core/attested-pi-run.ts:135`<br>`src/core/fusion/pi-child.ts:70` |
+| `PI_API_KEY` | remove | `src/core/attested-pi-run.ts:135`<br>`src/core/fusion/pi-child.ts:70` |
+| `PI_AUTH_FILE` | remove | `src/core/attested-pi-run.ts:135`<br>`src/core/fusion/pi-child.ts:70` |
+| `PI_BG_DELEGATE_ARTIFACT_DIR` | read, write | `src/core/delegate/launch.ts:324`<br>`src/delegate-child-extension.ts:277` |
+| `PI_BG_DELEGATE_LAUNCH_NONCE` | read, write | `src/core/delegate/launch.ts:328`<br>`src/delegate-child-extension.ts:281` |
+| `PI_BG_DELEGATE_SEED_PATH` | read, write | `src/core/delegate/launch.ts:325`<br>`src/delegate-child-extension.ts:278` |
+| `PI_BG_DELEGATE_SEED_SHA256` | read, write | `src/core/delegate/launch.ts:326`<br>`src/delegate-child-extension.ts:279` |
+| `PI_BG_DELEGATE_TASK_ID` | read, write | `src/core/delegate/launch.ts:327`<br>`src/delegate-child-extension.ts:280` |
+| `PI_BG_DISABLE_PI_TELEMETRY` | read | `src/core/registry.ts:193` |
+| `PI_BG_DISABLE_UPDATE_CHECK` | read | `src/extension.ts:444` |
+| `PI_BG_MAX_OUTPUT_BYTES` | read | `src/core/registry.ts:67` |
+| `PI_BG_REGISTRY_URL` | read | `src/extension.ts:453` |
+| `PI_BG_SHELL` | read | `src/core/common.ts:679` |
+| `PI_BG_SHELL_PATH` | read | `src/core/common.ts:680` |
+| `PI_FUSION_RESEARCH_ENABLED` | read, remove, write | `src/core/fusion/pi-child.ts:1291`<br>`src/core/fusion/pi-child.ts:70`<br>`src/fusion-child-extension.ts:393` |
+| `PI_FUSION_SOURCE_POLICY_PATH` | read, remove, write | `src/core/fusion/pi-child.ts:1292`<br>`src/core/fusion/pi-child.ts:70`<br>`src/fusion-child-extension.ts:349` |
+| `PI_FUSION_SOURCE_POLICY_SHA256` | read, remove, write | `src/core/fusion/pi-child.ts:1293`<br>`src/core/fusion/pi-child.ts:70`<br>`src/fusion-child-extension.ts:350` |
+| `PI_FUSION_TOOL_CALL_LOG_PATH` | read, remove, write | `src/core/fusion/pi-child.ts:1280`<br>`src/core/fusion/pi-child.ts:70`<br>`src/fusion-child-extension.ts:392` |
+| `PI_MODEL` | remove | `src/core/delegate/launch.ts:301`<br>`src/core/fusion/pi-child.ts:70` |
+| `PI_OFFLINE` | read | `src/extension.ts:445` |
+| `PI_PROVIDER` | remove | `src/core/delegate/launch.ts:301`<br>`src/core/fusion/pi-child.ts:70` |
+| `PI_REASONING_LEVEL` | remove | `src/core/delegate/launch.ts:301`<br>`src/core/fusion/pi-child.ts:70` |
+| `PI_SESSION_FILE` | remove | `src/core/delegate/launch.ts:301`<br>`src/core/fusion/pi-child.ts:70` |
+| `PI_SESSION_ID` | remove | `src/core/delegate/launch.ts:301`<br>`src/core/fusion/pi-child.ts:70` |
+| `PI_SKIP_VERSION_CHECK` | write | `src/core/delegate/launch.ts:323`<br>`src/core/fusion/pi-child.ts:234` |
+| `SHELL` | read | `src/core/common.ts:675` |
+| `SystemRoot` | read | `src/core/windows-taskkill.ts:96` |
+| `WINDIR` | read | `src/core/windows-taskkill.ts:101` |
+
+### Runtime paths and artifacts
+
+| Kind | Path/artifact | Provenance |
+| --- | --- | --- |
+| config | `fusion-models.json` | `src/core/fusion/config.ts:20` |
+| delegate-artifact | `budget-plan.json` | `src/core/delegate/artifacts.ts:42` |
+| delegate-artifact | `child-prompt.txt` | `src/core/delegate/artifacts.ts:46` |
+| delegate-artifact | `child.stderr.txt` | `src/core/delegate/artifacts.ts:47` |
+| delegate-artifact | `child.stdout.txt` | `src/core/delegate/artifacts.ts:48` |
+| delegate-artifact | `context-omission-ledger.json` | `src/core/delegate/artifacts.ts:41` |
+| delegate-artifact | `error.json` | `src/core/delegate/artifacts.ts:49` |
+| delegate-artifact | `manifest.json` | `src/core/delegate/artifacts.ts:43` |
+| delegate-artifact | `outcome.json` | `src/core/delegate/artifacts.ts:44` |
+| delegate-artifact | `result.json` | `src/core/delegate/result-package.ts:28` |
+| delegate-artifact | `seed.json` | `src/core/delegate/artifacts.ts:40` |
+| delegate-artifact | `spill/<receipt-named-file>` | `src/core/delegate/artifacts.ts:53` |
+| directory | `.pi/delegate/<session-id>-<pid>/<task-id>/` | `src/core/delegate/artifacts.ts:157` |
+| directory | `.pi/fusion/<session-id>-<pid>/<run-id>/` | `src/core/fusion/artifacts.ts:251` |
+| directory | `.pi/tasks/<session-id>-<pid>/` | `src/core/registry.ts:780` |
+| fusion-artifact | `<attempt-prefix> = candidate-<slot>.attempt-<n> \| evaluation.attempt-<n> \| merge.attempt-<n>` | `src/core/fusion/artifacts.ts:193` |
+| fusion-artifact | `<attempt-prefix>.calibration-violation.json` | `src/core/fusion/artifacts.ts:208` |
+| fusion-artifact | `<attempt-prefix>.events.jsonl` | `src/core/fusion/artifacts.ts:402` |
+| fusion-artifact | `<attempt-prefix>.prompt.txt` | `src/core/fusion/artifacts.ts:401` |
+| fusion-artifact | `<attempt-prefix>.stderr.txt` | `src/core/fusion/artifacts.ts:403` |
+| fusion-artifact | `blind-candidates.json` | `src/core/fusion/artifacts.ts:373` |
+| fusion-artifact | `budget-plan.json` | `src/core/fusion/artifacts.ts:369` |
+| fusion-artifact | `candidate-<slot>.attempt-<n>.response.md \| candidate-<slot>.attempt-<n>.response.partial.md` | `src/core/fusion/artifacts.ts:203` |
+| fusion-artifact | `candidate-<slot>.attempt-<n>.tool-calls.jsonl` | `src/core/fusion/artifacts.ts:301` |
+| fusion-artifact | `candidate-<slot>.attempt-<n>.tool-calls.jsonl.seal.json` | `src/core/fusion/child-protocol.ts:13` |
+| fusion-artifact | `canonical-input.json` | `src/core/fusion/artifacts.ts:339` |
+| fusion-artifact | `context-omission-ledger.json` | `src/core/fusion/artifacts.ts:348` |
+| fusion-artifact | `error.json` | `src/core/fusion/artifacts.ts:385` |
+| fusion-artifact | `evaluation.attempt-<n>.response.txt \| evaluation.attempt-<n>.response.partial.txt` | `src/core/fusion/artifacts.ts:203` |
+| fusion-artifact | `evaluation.json` | `src/core/fusion/artifacts.ts:377` |
+| fusion-artifact | `merge.attempt-<n>.response.md \| merge.attempt-<n>.response.partial.md` | `src/core/fusion/artifacts.ts:203` |
+| fusion-artifact | `merged.md` | `src/core/fusion/artifacts.ts:316` |
+| fusion-artifact | `source-policy.private.json` | `src/core/fusion/artifacts.ts:355` |
+| task-file | `.pi/tasks/<session-id>-<pid>/<task-id>.attestation.json` | `src/core/attested-pi-run.ts:583` |
+| task-file | `.pi/tasks/<session-id>-<pid>/<task-id>.json` | `src/core/registry.ts:808` |
+| task-file | `.pi/tasks/<session-id>-<pid>/<task-id>.output` | `src/core/registry.ts:807` |
+| task-file | `.pi/tasks/<session-id>-<pid>/<task-id>.pi-events.jsonl` | `src/core/attested-pi-run.ts:580` |
+| task-file | `.pi/tasks/<session-id>-<pid>/<task-id>.pi-telemetry-wrapper.cjs` | `src/core/attested-pi-run.ts:582` |
+| task-file | `.pi/tasks/<session-id>-<pid>/<task-id>.stderr` | `src/core/attested-pi-run.ts:581` |
+
+### Schema identifiers
+
+| Schema | Provenance |
+| --- | --- |
+| `phase2.pi_task_attestation.v1` | `src/core/attested-pi-run.ts:20` |
+| `pi-background-tasks.delegate-budget-plan.v2` | `src/core/delegate/types.ts:21` |
+| `pi-background-tasks.delegate-child-terminal.v1` | `src/delegate-child-extension.ts:381` |
+| `pi-background-tasks.delegate-hook-contract.v1` | `src/core/delegate/hook-contract.ts:15` |
+| `pi-background-tasks.delegate-launch.v1` | `src/delegate-extension.ts:373` |
+| `pi-background-tasks.delegate-ledger.v1` | `src/core/delegate/types.ts:16` |
+| `pi-background-tasks.delegate-manifest.v1` | `src/core/delegate/types.ts:22` |
+| `pi-background-tasks.delegate-outcome.v1` | `src/core/delegate/runner.ts:200` |
+| `pi-background-tasks.delegate-receipt.v1` | `src/core/delegate/types.ts:19` |
+| `pi-background-tasks.delegate-result-view.v1` | `src/delegate-extension.ts:528` |
+| `pi-background-tasks.delegate-result.v1` | `src/core/delegate/types.ts:18` |
+| `pi-background-tasks.delegate-seed.v1` | `src/core/delegate/types.ts:15` |
+| `pi-background-tasks.extension-request.v1` | `src/core/extension-api.ts:15` |
+| `pi-background-tasks.extension-response.v1` | `src/core/extension-api.ts:16` |
+| `pi-background-tasks.extension-terminal.v1` | `src/core/extension-api.ts:17` |
+| `pi-background-tasks.fusion-blind-candidates.v1` | `src/core/fusion/prompts.ts:299` |
+| `pi-background-tasks.fusion-budget-plan.v3` | `src/core/fusion/types.ts:24` |
+| `pi-background-tasks.fusion-calibration-violation.v1` | `src/core/fusion/types.ts:26` |
+| `pi-background-tasks.fusion-child-result.v2` | `src/core/fusion/child-protocol.ts:5` |
+| `pi-background-tasks.fusion-context-ledger.v2` | `src/core/fusion/types.ts:22` |
+| `pi-background-tasks.fusion-evaluation-repair-input.v1` | `src/core/fusion/prompts.ts:279` |
+| `pi-background-tasks.fusion-evaluation.v1` | `src/core/fusion/types.ts:16` |
+| `pi-background-tasks.fusion-input.v4` | `src/core/fusion/types.ts:14` |
+| `pi-background-tasks.fusion-input.v5` | `src/core/fusion/types.ts:15` |
+| `pi-background-tasks.fusion-manifest.v3` | `src/core/fusion/types.ts:20` |
+| `pi-background-tasks.fusion-manifest.v4` | `src/core/fusion/types.ts:21` |
+| `pi-background-tasks.fusion-merge-input.v1` | `src/core/fusion/prompts.ts:325` |
+| `pi-background-tasks.fusion-models.v1` | `src/core/fusion/types.ts:13` |
+| `pi-background-tasks.fusion-progress.v1` | `src/fusion-extension.ts:57` |
+| `pi-background-tasks.fusion-request.v1` | `src/fusion-extension.ts:58` |
+| `pi-background-tasks.fusion-result.v4` | `src/core/fusion/types.ts:18` |
+| `pi-background-tasks.fusion-result.v5` | `src/core/fusion/types.ts:19` |
+| `pi-background-tasks.fusion-source-policy.v1` | `src/core/fusion/types.ts:23` |
+| `pi-background-tasks.fusion-tool-call-seal.v1` | `src/core/fusion/child-protocol.ts:12` |
+| `pi-background-tasks.fusion-tool-call.v1` | `src/core/fusion/types.ts:27` |
+| `pi-background-tasks.fusion-validation-candidate.v1` | `src/core/fusion/types.ts:17` |
+| `pi-background-tasks.input-token-calibration.v1` | `src/core/context/token-budget.ts:18` |
+
+### Status vocabularies
+
+
+```json
+{
+  "DELEGATE_MANIFEST_STATES": [
+    "launched",
+    "running",
+    "committed",
+    "failed",
+    "cancelled"
+  ],
+  "FUSION_BUDGET_STAGE_VALUES": [
+    "candidate",
+    "evaluation",
+    "evaluation_repair",
+    "merge"
+  ],
+  "FUSION_CAPABILITY_VALUES": [
+    "reason",
+    "inspect",
+    "research"
+  ],
+  "FUSION_STAGE_VALUES": [
+    "candidate",
+    "evaluation",
+    "merge"
+  ],
+  "FUSION_STATE_VALUES": [
+    "initializing",
+    "candidates_running",
+    "candidates_complete",
+    "evaluating",
+    "evaluation_complete",
+    "merging",
+    "completed",
+    "failed",
+    "cancelled"
+  ],
+  "FUSION_TERMINAL_STATE_VALUES": [
+    "completed",
+    "failed",
+    "cancelled"
+  ],
+  "TASK_STATUS_VALUES": [
+    "running",
+    "completed",
+    "failed",
+    "killed"
+  ],
+  "TERMINAL_TASK_STATUS_VALUES": [
+    "completed",
+    "failed",
+    "killed"
+  ]
+}
+```
+<!-- pi-docs:end name="runtime-contracts" -->
+
+## Maintenance rule
+
+If a runtime fact changes in source, update the owning subsystem/API doc and run `npm run docs:generate`. Do not hand-edit generated tables.