pi-background-tasks 0.7.6 → 0.9.0

package/PUBLISHING.md

@@ -1,6 +1,6 @@
 # Publishing pi-background-tasks
 
-Release checklist for npm publishing and standalone git publishing. The current release candidate is 0.7.6; version 0.7.0 introduced the Fusion public surfaces (`/fusion`, `/fusion-models`, `fusion_brainstorm`) in addition to the background-task surfaces. Do not advertise the GitHub install target until the standalone repository has the exact release commit and tag.
+Release checklist for npm publishing and standalone git publishing. The current release candidate is 0.9.0, which adds the `fusion_validate` validation workflow and Anthropic child sanitization; 0.7.0 introduced the Fusion public surfaces (`/fusion`, `/fusion-models`, `fusion_brainstorm`) in addition to the background-task surfaces. Do not advertise the GitHub install target until the standalone repository has the exact release commit and tag.
 
 ## Preconditions
 
@@ -37,8 +37,8 @@ npm publish --access public
 Pi install smoke after publish:
 
 ```bash
-PI_CODING_AGENT_DIR=$(mktemp -d) pi -e npm:pi-background-tasks@0.7.6 --offline --no-tools --no-session -p "/jobs"
-pi install npm:pi-background-tasks@0.7.6
+PI_CODING_AGENT_DIR=$(mktemp -d) pi -e npm:pi-background-tasks@0.9.0 --offline --no-tools --no-session -p "/jobs"
+pi install npm:pi-background-tasks@0.9.0
 ```
 
 ## Publish to git
@@ -51,15 +51,15 @@ git status --short --branch
 git log --oneline -3
 git remote -v
 git push origin main
-git tag v0.7.6
-git push origin v0.7.6
+git tag v0.9.0
+git push origin v0.9.0
 ```
 
 Pi install smoke after git tag, using an isolated Pi agent directory so no local checkout or user `~/.pi` state is involved:
 
 ```bash
-PI_CODING_AGENT_DIR=$(mktemp -d) pi -e git:github.com/ismailsaleekh/pi-background-tasks@v0.7.6 --offline --no-tools --no-session -p "/jobs"
-pi install git:github.com/ismailsaleekh/pi-background-tasks@v0.7.6
+PI_CODING_AGENT_DIR=$(mktemp -d) pi -e git:github.com/ismailsaleekh/pi-background-tasks@v0.9.0 --offline --no-tools --no-session -p "/jobs"
+pi install git:github.com/ismailsaleekh/pi-background-tasks@v0.9.0
 ```
 
 ## pi.dev/packages

package/README.md

@@ -2,26 +2,26 @@
 
 Claude-Code-like explicit background shell task manager for [Pi](https://pi.dev/).
 
-This package adds named, tracked background shell jobs with durable output files, bounded log reads, kill/timeout safety, task-owned context-window/token/tool-use/model telemetry, explicit Pi-agent telemetry wrapping for tasks marked as agents, a focused footer-dock task manager, `/tasks` fallback UI, and completion notifications that can wake the agent when LLM-launched work finishes. It also ships Fusion: a direct child-Pi five-call synthesis workflow exposed as `/fusion`, `/fusion-models`, and the always-active `fusion_brainstorm` tool. A terminal task status is published only after trailing wrapped-agent telemetry is consumed and final output plus terminal metadata have completed their durability writes.
+This package adds named, tracked background shell jobs with durable output files, bounded log reads, kill/timeout safety, task-owned context-window/token/tool-use/model telemetry, explicit Pi-agent telemetry wrapping for tasks marked as agents, a focused footer-dock task manager, `/tasks` fallback UI, and completion notifications that can wake the agent when LLM-launched work finishes. It also ships Fusion: a direct child-Pi five-call synthesis workflow exposed as `/fusion`, `/fusion-models`, and the always-active `fusion_brainstorm` and `fusion_validate` tools. A terminal task status is published only after trailing wrapped-agent telemetry is consumed and final output plus terminal metadata have completed their durability writes.
 
 ## Install
 
 From npm after publish:
 
 ```bash
-pi install npm:pi-background-tasks@0.7.6
+pi install npm:pi-background-tasks@0.9.0
 ```
 
 From git after pushing this package to its standalone repository and tagging:
 
 ```bash
-pi install git:github.com/ismailsaleekh/pi-background-tasks@v0.7.6
+pi install git:github.com/ismailsaleekh/pi-background-tasks@v0.9.0
 ```
 
 For project-local install:
 
 ```bash
-pi install -l npm:pi-background-tasks@0.7.6
+pi install -l npm:pi-background-tasks@0.9.0
 ```
 
 ## Commands
@@ -91,11 +91,14 @@ The lookup runs at most once per session on `session_start`, is time-boxed, and
 ## LLM tools
 
 - `bg_run` — start named long-running commands without blocking the conversation.
+- `bg_delegate` — launch one background Pi agent seeded with a frozen projection of the current conversation, then return a launch receipt immediately. See [Delegated background agents](#delegated-background-agents).
+- `bg_result` — retrieve a `bg_delegate` answer, hash-verified before it is returned.
 - `bg_run_pi_attested` — opt-in structured direct-spawn Pi agent task that emits a strict local attestation sidecar after successful completion.
 - `bg_status` — inspect one task or all recent tasks.
 - `bg_logs` — read bounded task output.
 - `bg_kill` — stop a running task.
-- `fusion_brainstorm({prompt})` — always-active tool that runs the Fusion workflow and returns the exact merged text as the tool result for the parent agent to consume, with the exact Pi `Usage` shape attached when the host supports tool-result usage: token fields plus complete `cost.input`, `cost.output`, `cost.cacheRead`, `cost.cacheWrite`, and `cost.total`. Its closed public schema has exactly one required parameter, `prompt`; extra keys are rejected. It has no eligibility, quota, routine, or justification gate. Tool context capture excludes the current assistant tool-call leaf when Pi is executing that `fusion_brainstorm` call, so the nested children do not see the in-progress tool call or sibling calls. Children receive the documented conversation projection described under [Conversation context policy](#conversation-context-policy): visible user/assistant text verbatim, with thinking and tool payloads replaced by explicit hash-accounted omission receipts. Because the prompt is composed by the parent agent, it is treated as authoritative and self-contained.
+- `fusion_validate({prompt})` — always-active tool that runs the same five-model Fusion workflow as a validation review of work that was just completed, and returns the merged prose review. Its closed public schema has exactly one parameter, `prompt`; **it takes no `capability` argument**, and a caller-supplied `capability` is rejected loudly rather than ignored. Candidate reviewers always run with the read-only `inspect` capability, because a reasoning-only reviewer cannot read the code it is judging; the evaluator and merger remain no-tools by stage policy. Findings are classified `critical`, `high`, or `minor`, each with a file/symbol location, the evidence the reviewer actually read, and why it matters. A review with no findings must state what was verified rather than returning an unexplained pass. See [Validation workflow](#validation-workflow).
+- `fusion_brainstorm({prompt, capability?})` — always-active tool that runs the Fusion workflow and returns the exact merged text as the tool result for the parent agent to consume, with the exact Pi `Usage` shape attached when the host supports tool-result usage: token fields plus complete `cost.input`, `cost.output`, `cost.cacheRead`, `cost.cacheWrite`, and `cost.total`. Calling it as `fusion_brainstorm({prompt})` uses the default `reason` capability: no tools and byte-identical child argv/prompt behaviour to the previous release. The optional `capability` accepts only `"reason"`, `"inspect"`, or `"research"`; `inspect` gives candidate children read-only repository inspection tools, and `research` adds the package-owned `fusion_web_fetch` tool for targeted public URL fetches. The evaluator and merger remain no-tools by stage policy. Its closed public schema has one required parameter, `prompt`, plus optional `capability`; extra keys are rejected. It has no eligibility, quota, routine, or justification gate. Tool context capture excludes the current assistant tool-call leaf when Pi is executing that `fusion_brainstorm` call, so the nested children do not see the in-progress tool call or sibling calls. Children receive the documented conversation projection described under [Conversation context policy](#conversation-context-policy): visible user/assistant text verbatim, with thinking and tool payloads replaced by explicit hash-accounted omission receipts. Because the prompt is composed by the parent agent, it is treated as authoritative and self-contained.
 
 `bg_run` requires a concise `name` for the footer dock, the shell `command`, and required `isAgent: boolean`. Set `isAgent: true` only when the background task launches an LLM/agent process (for example `pi -p ...` or `pi --mode json ...`); set `isAgent: false` for scripts, tests, dev servers, sleeps, and ordinary shell commands. It defaults both `notifyOnCompletion` and `triggerOnCompletion` to `true`. With those defaults, `bg_run` returns immediately, the agent continues only independent useful work or ends its current turn instead of sleeping or polling, and a durable `background-task-notification` for completed, failed, or killed state automatically starts a follow-up turn. The launch receipt states the effective notification/wake behavior explicitly. `bg_status` and `bg_logs` remain available for user-requested inspection, deliberately disabled completion delivery, concrete hang diagnosis, or reading output after the terminal event; they are not waiting primitives, and the terminal notification does not need status reconfirmation. Setting `triggerOnCompletion: false` keeps the notification but prevents it from starting an agent turn. Setting `notifyOnCompletion: false` suppresses both notification and wake-up even if `triggerOnCompletion` is true.
 
@@ -104,9 +107,170 @@ Tasks marked with `isAgent: true` that launch print/json child Pi agents through
 `bg_run_pi_attested` is separate from `bg_run` and never accepts a shell command. It takes structured `provider`, `model`, `prompt`, optional literal extra Pi argv, and a relative `reportPath`; launches exactly one direct `pi --mode json` child; records raw Pi JSON events, separate stderr, exact argv/cwd, prompt/report hashes, observed Pi session/provider/model, and `ModelRegistry.isUsingOAuth` credential class. It forbids direct API-key/auth-file launch arguments and emits no partial attestation: failures remain ordinary failed tasks with no sidecar.
 
 
+## Delegated background agents
+
+`bg_delegate` fills the gap between `bg_run` (a background agent with a **fresh,
+empty** context) and `fusion_brainstorm` (your current context, but synchronous
+and five-model). It is one agent, one prompt, seeded with the current session's
+context, non-blocking. `bg_result` retrieves its answer safely. They ship
+together: a delegate without a safe retrieval path could not return its work.
+
+```text
+bg_delegate({ name, prompt })              → launch receipt, immediately
+  … the parent keeps working; the terminal notification wakes it …
+bg_result({ taskId })                      → hash-verified answer
+```
+
+### Context seeding
+
+The child does **not** share the parent's live session. The parent conversation
+is projected with the same frozen `visible-conversation-ledger-v2` transform
+Fusion uses (see [Conversation context policy](#conversation-context-policy)),
+frozen as an immutable seed, and the child is given its **own** `--session-id`
+and a task-owned `--session-dir`. Conceptually it has your context; physically it
+can never open or mutate the parent session.
+
+| Content | Disposition |
+|---|---|
+| User text | included verbatim, never clipped |
+| Assistant text | included verbatim, never clipped |
+| User image blocks | marker only, never raw bytes |
+| Assistant thinking | excluded; recorded as a hash-accounted omission receipt |
+| Tool-call arguments | excluded; recorded as a hash-accounted omission receipt |
+| Tool-result payloads | excluded; recorded as a hash-accounted omission receipt |
+| The in-flight `bg_delegate` call and its sibling calls | scope-excluded from the branch |
+
+The assistant message carrying the in-flight call is excluded as a whole, so when
+several `bg_delegate` calls share one assistant message **every** sibling call is
+excluded for **every** child: two delegates launched together receive identical
+projected history and neither can observe the other's arguments.
+
+The seed is canonical-JSON, SHA-256'd, and persisted. The persisted bytes are the
+exact bytes the child reads, and the child re-verifies that hash **before its
+first model call**. Repeated construction from the same session is
+byte-identical.
+
+**Documented limitation:** facts that exist only inside omitted parent tool
+output are **not** available to the child. The child is told this explicitly and
+instructed to say so plainly rather than guess. Restate any such finding in the
+`prompt`.
+
+### Route pinning
+
+The route is pinned at launch — by default the parent's current effective
+provider/model, or an explicit `route {provider, model}`. It is **never**
+substituted, never falls back, and is never retried on a different route. An
+unavailable route or one with no declared context window is a typed refusal
+before anything is created. The child additionally asserts that every assistant
+message it produced came from the pinned route; a mismatch prevents the run from
+committing an answer at all.
+
+### Inspect-only capability boundary
+
+v1 supports exactly one capability, `inspect`. The child is launched with
+`--tools read,grep,find,ls,delegate_read_artifact`, `--no-builtin-tools`, an
+explicit `--exclude-tools` denylist, and no ambient extensions, skills, prompt
+templates, themes, or context files. **The boundary is enforced by argv and the
+child's tool registry, not by prompt text.** There is no shell, no network, no
+edit/write, no recursive delegation, and no Fusion from the child. Writable
+profiles are deliberately out of scope.
+
+### Budgets, spilling, and limits
+
+Admission is checked **before** the child process, the child session, or the
+artifact directory exists, so a refusal leaves **zero** children and **zero**
+artifacts. Inside the child, every model call is measured before dispatch; a call
+that would exceed the pinned route's allowance is refused and the run terminates
+with a typed `provider_context_budget_exhausted`.
+
+A tool result larger than the per-result transcript cap is written **in full** to
+a hashed artifact and replaced in the transcript by an explicit receipt naming
+the artifact, its exact byte count, its SHA-256, and how to read a bounded range.
+The raw payload never enters the transcript and **nothing is truncated**. The
+bounded `delegate_read_artifact` tool returns exactly the requested range or
+fails; a request past end-of-file is refused rather than silently shortened.
+Turn, tool-call, aggregate-output, and wall-clock limits are enforced and
+reported.
+
+### Retrieving the answer
+
+The child commits exactly one self-contained result package by temp-write,
+`fsync`, rename, directory `fsync`. **The rename is the commit point**: a package
+present under its final name is complete, and its absence means no answer was
+accepted — whatever the process exit code was. A child that exits `0` without
+committing is a typed `child_exited_without_commit`, never a silent empty
+success. A run that degraded anything latches terminal state and **cannot**
+commit a success package, so a hash-valid answer can never be built on silently
+mutilated context.
+
+`bg_result` verifies the package identity, seed hash, route, every per-block
+SHA-256, and the aggregate SHA-256 before returning a single byte, and returns
+bytes from the buffer it verified. A running task returns a typed *not ready*
+result and **never blocks or polls**. An answer over the inline cap degrades to
+an artifact reference **explicitly**; requesting `delivery:"inline"` for it is a
+typed `result_too_large_for_inline` failure naming the artifact. It is **never**
+truncated to fit. `autoDeliver` (`never` | `when_small` | `always`) defaults to
+`never`: completion notifications carry metadata, and the answer is fetched
+deliberately with `bg_result`.
+
+### Failure taxonomy
+
+Every delegate failure is typed and states what happened, what was preserved, and
+what the operator can do. Admission codes
+(`delegate_hook_contract_unsupported`, `delegate_isolation_unsupported`,
+`route_unresolved`, `route_capacity_unknown`, `seed_projection_failed`,
+`seed_budget_exceeded`, `seed_persist_failed`, `invalid_arguments`) always report
+`childCreated: false`. Execution and integrity codes include `child_spawn_failed`,
+`child_timeout`, `child_cancelled`, `child_turn_limit`, `child_tool_call_limit`,
+`child_exited_without_commit`, `provider_context_budget_exhausted`,
+`aggregate_tool_output_cap`, `child_result_invalid`,
+`child_result_encoding_invalid`, `route_attestation_missing`, `route_mismatch`,
+`seed_hash_mismatch`, `answer_hash_mismatch`, `artifact_spill_failed`, and
+`artifact_read_failed`. Retrieval states are `result_not_ready`,
+`result_unavailable`, `result_too_large_for_inline`, and `task_unknown`.
+
+Usage that the provider did not report is recorded as explicitly `unavailable`,
+never as zero.
+
+### Proven Pi hook contract
+
+The child-side guard depends on runtime Pi behaviour, which is **proven by
+execution** rather than read from type declarations. The
+`npm run test:hook-contract` gate drives a real Pi agent loop and records what it
+observed. On Pi 0.83 it establishes that `context` fires once before every model
+call in extension load order and that returned messages reach the provider; that
+**throwing** from a `context` handler does **not** block the call (Pi catches it
+and dispatches anyway); that `ctx.abort()` does not skip the provider call site
+but hands it an already-aborted signal and terminates the run; and that
+`tool_result` fires before the result enters the transcript, chains in load order,
+and preserves tool-call id, role, and error flag across replacement.
+
+Because neither a throw nor an abort is a hard admission gate on its own, the
+guard uses abort as the barrier **and** removes the oversized content from the
+outgoing message set, so the request cannot carry it even if a provider ignored
+the aborted signal. If a Pi build cannot provide the required guarantees,
+`bg_delegate` refuses to spawn with a typed
+`delegate_hook_contract_unsupported`; the guard is never weakened to fit.
+
+Delegate artifacts are written under:
+
+```text
+.pi/delegate/<session-id>-<pid>/<task-id>/
+```
+
+Each run contains `seed.json`, `child-prompt.txt` (the exact bytes handed to the
+child over stdin, never a shell or positional argument),
+`context-omission-ledger.json`, `budget-plan.json`, `manifest.json`, the
+task-owned `child-session/`, any `spill/` artifacts, `result.json` once the child
+commits, and `outcome.json` once the parent adjudicates the run.
+
+`result.json` is written by the **child** and `outcome.json` by the **parent**, so
+neither writer can claim a state it did not observe. `manifest.state` records only
+what the parent knew at launch and is never used to decide success.
+
 ## Fusion workflow
 
-Fusion runs direct child `pi --mode text` processes only; it never calls `pi-ai` completion APIs. Each child is launched with `--no-session`, `--no-tools`, `--no-extensions`, `--no-skills`, `--no-prompt-templates`, `--no-themes`, and `--no-context-files`, plus the resolved provider/model/thinking level and the package-owned private `extensions/fusion-child.ts` metadata extension. The prompt travels over stdin, not a shell or positional argument.
+Fusion runs direct child `pi --mode text` processes only; it never calls `pi-ai` completion APIs. Each child is launched with `--no-session`, `--no-extensions`, `--no-skills`, `--no-prompt-templates`, `--no-themes`, and `--no-context-files`, plus the tool policy described below, the resolved provider/model/thinking level, and the package-owned private `extensions/fusion-child.ts` metadata extension. The prompt travels over stdin, not a shell or positional argument.
 
 Pi text mode writes the final full answer exactly once instead of serializing cumulative reasoning/partial-message events on every token delta. The private child extension emits one compact, reasoning-free metadata record per finalized assistant message for provider/model, stop reason, the complete Pi token/cost `Usage` object, and response byte/hash validation. Fusion persists those compact records in `*.events.jsonl`; the complete answer remains in the stage response artifact. The 32 MiB child stdout cap therefore applies to one final response, not amplified JSON telemetry. Failed attempts keep the authoritative response artifact empty and, when any stdout was captured, persist it separately as an explicitly incomplete `*.response.partial.*` artifact.
 
@@ -116,15 +280,71 @@ Model configuration is global under the Pi agent directory:
 fusion-models.json
 ```
 
+### Validation workflow
+
+`fusion_validate` is the same orchestrator, artifact store, budget engine, conversation projection, and evaluation schema as `fusion_brainstorm`, with different stage framing. A workflow profile selects the four system prompts and the capability policy; it never changes the canonical input schema, which remains `pi-background-tasks.fusion-input.v4` for both tools. Canonical input bytes and the omission ledger are provably identical across workflows for the same conversation, and that equality is asserted by the golden-bytes gate rather than assumed.
+
+| Concern | `fusion_brainstorm` | `fusion_validate` |
+|---|---|---|
+| Parameters | `{prompt, capability?}` | `{prompt}` — capability rejected |
+| Candidate capability | caller-selected, default `reason` | always `inspect` |
+| Evaluator / merger capability | `reason` by stage policy | `reason` by stage policy |
+| Run id prefix | `f` | `v` |
+| Output | prose answer | prose review |
+| Evaluation schema | `fusion-evaluation.v1` | `fusion-evaluation.v1` (identical) |
+
+The capability is fixed rather than defaulted. A `capability` argument on `fusion_validate` is a hard error at the schema boundary, and the orchestrator independently re-asserts the workflow capability before the artifact store or any child process exists, so a contradicting request launches **zero children**.
+
+The three reviewers are blind-compared exactly like brainstorm candidates, but the evaluator is additionally required to treat each distinct defect claim as a unit and to carry every surviving claim into `synthesis_plan.must_include`, **including claims raised by only one reviewer**. The merger is correspondingly forbidden from dropping a single-source finding or inventing one no reviewer raised, and must state the resolution and reason wherever reviewers disagreed. Without those two clauses a real defect that only one model noticed could disappear by silent majority vote, which is the failure mode a three-model review exists to prevent.
+
+`fusion_validate` is advisory and read-only. It never modifies files, it does not gate anything, and it is not a substitute for running tests or builds. Like every Fusion entry point, facts that exist only inside omitted tool output are not visible to reviewers; `inspect` lets them re-derive repository facts themselves, but uncommitted state that exists only in the parent agent's context must be restated in the prompt.
+
+### Anthropic child sanitization
+
+Fusion children launch with `--no-extensions` for isolation, which disables extension *discovery* while still honouring explicit `--extension` paths. The parent session normally loads an Anthropic system-prompt sanitizer through discovery, so a Claude child would inherit nothing and fail at the provider: Pi's own system prompt contains documentation lines Anthropic rejects.
+
+Children routed to the `anthropic` provider therefore receive a second explicit extension, [`@ravshansbox/pi-anthropic-sps`](https://github.com/ravshansbox/pi-anthropic-sps) (MIT), resolved from the package's own dependency tree. The metadata extension is always passed first so its `message_end` frame is never displaced.
+
+Children on every other provider receive exactly one `--extension` and their argv is byte-identical to the pre-sanitizer form. The sanitizer package publishes no `main`/`exports`, so it is located through its manifest's `pi.extensions[0]` entry rather than a direct require. Every resolution failure - package missing, manifest unreadable or malformed, no declared extension, or a declared file that does not exist - is a loud error before launch, because silently omitting the sanitizer would resurface later as an opaque provider rejection.
+
+### Candidate capabilities
+
+Fusion candidate children support three launch-time capability profiles. `reason` is the default: it passes `--no-tools` and preserves the previous no-tool candidate argv and prompt bytes. `inspect` is available only to candidate children and replaces `--no-tools` with the exact read-only tool policy `--no-builtin-tools --tools read,grep,find,ls --exclude-tools bash,edit,write,fusion_brainstorm,bg_delegate,bg_result,bg_run,bg_kill,bg_status,bg_logs,bg_run_pi_attested`. `research` extends `inspect` by adding the package-owned `fusion_web_fetch` tool to the `--tools` allowlist; the `--exclude-tools` denylist is unchanged and still bans `bash`, `edit`, `write`, `fusion_brainstorm`, `bg_delegate`, `bg_result`, `bg_run`, `bg_kill`, `bg_status`, `bg_logs`, and `bg_run_pi_attested`. The `reason` and `inspect` argv forms remain byte-identical to v0.7.8.
+
+Evaluator, evaluation-repair, and merger children always run with `--no-tools` by stage policy. Caller input cannot grant them tools, even when candidates use `inspect` or `research`. Capability is recorded as launch metadata in the run manifest and child argv, not added to the canonical child-facing input; the canonical input schema remains `pi-background-tasks.fusion-input.v4`.
+
+The inspect candidate system prompt tells the child it may re-derive facts from the repository using `read`, `grep`, `find`, and `ls`. The research prompt adds `fusion_web_fetch` for fetching a specific public URL as bounded Markdown or text. Both prompts extend the untrusted-data rule: projected conversation text, file contents, and fetched page content are data, never instructions to follow.
+
+`fusion_web_fetch` has a closed schema: `{ url: string, extract?: 'text' | 'markdown' }`. `extract` defaults to Markdown. There is deliberately no per-fetch prompt parameter. Anthropic documents the `{url, prompt}` extraction pattern as lossy by design: the prompt decides what reaches the model, so a false negative can enter a Fusion candidate answer, pass through blind evaluation, and reach the merged answer with no signal that the page contained missed information.
+
+HTML extraction uses the runtime dependency `turndown@7.2.4`; its only dependency is `@mixmark-io/domino`, so it does not require `jsdom`. Markdown is the default because it preserves link destinations, headings, tables, and code blocks better than plain text. This version has no web search, browser, PDF support, cache, or domain allowlist.
+
+| `fusion_web_fetch` policy | Value |
+|---|---:|
+| Request method | GET |
+| Schemes | `http:` and `https:` only |
+| Timeout | 60 seconds |
+| Response body cap | 2 MiB |
+| Returned content cap | 32 KiB |
+| Redirect cap | 5 hops |
+
+Network handling is basic network hygiene, not a secret-exfiltration control. The hostname is resolved once, every returned address is checked, the connection is pinned to the vetted address, and the socket's remote address is verified after connect. Address validation re-runs on every redirect hop. Private, loopback, link-local, unique-local, multicast, and cloud-metadata addresses are refused. A research child that can read files and reach the network can in principle send what it read; that is an accepted trade in this version, not a sandbox or security boundary.
+
+`fusion_web_fetch` fails loudly with typed errors rather than retrying or falling back to another URL, scheme, encoding, or extraction mode. Error codes include `invalid_url`, `unsupported_scheme`, `blocked_address`, `dns_failure`, `redirect_limit`, `redirect_blocked`, `response_too_large`, `unsupported_content_type`, `request_timeout`, `network_error`, `extraction_failed`, and `http_error`.
+
+Every child has a stale-action watchdog in addition to the 30-minute absolute timeout. `FUSION_CHILD_IDLE_TIMEOUT_MS` defaults to 900 seconds and fails the child if no stdout or stderr activity occurs during that window; any stdout or stderr activity resets the watchdog. The threshold is deliberately far above tool latency: the child metadata frame is emitted only at `message_end` and text-mode stdout carries only the final assistant message, so one slow model turn is legitimately silent on both streams and must not be killed. The absolute timeout remains a backstop for children that keep producing output but never finish.
+
+Inspect and research candidates also write a per-attempt tool-call audit log at `candidate-<slot>.attempt-<n>.tool-calls.jsonl`. The child appends one JSON line per completed tool call with the tool name, argument/result byte counts, and SHA-256 digests only. For `fusion_web_fetch`, the record also includes `url`, `final_url`, `http_status`, `response_bytes`, and `content_sha256`. Raw arguments, raw tool results, and page content are never written because file paths, file contents, fetched content, and tool results may contain secrets. After the child exits, the parent verifies the log is complete and contiguous; a trailing partial line, ordinal gap, duplicate ordinal, or schema-version mismatch is a loud failure.
+
 Missing config means all five slots are `$current`. Malformed config, stale explicit models, unavailable current models, and concurrent selector write conflicts fail loudly before child inference. Selector saves use an inter-process lock plus revision re-read before rename so simultaneous dialogs cannot silently overwrite each other. Candidate identities are anonymized before evaluation; provider/model metadata stays in local artifacts, not in evaluator prompts.
 
 Progress is surfaced through `fusion` status updates, TUI cancellable loader UI for `/fusion`, and partial `fusion_brainstorm` tool updates. Session shutdown or reload tracks the whole invocation from entry, aborts live or initializing Fusion runs, and waits for cleanup.
 
 ### Conversation context policy
 
-Fusion children receive a **versioned conversation projection**, not a raw execution transcript. The canonical input schema is `pi-background-tasks.fusion-input.v3` and every run states exactly what was included and what was omitted.
+Fusion children receive a **versioned conversation projection**, not a raw execution transcript. The canonical input schema is `pi-background-tasks.fusion-input.v4` and every run states exactly what was included and what was omitted.
 
-The projection transform (`visible-conversation-ledger-v1`) is shared by both entry points:
+The projection transform (`visible-conversation-ledger-v2`) is shared by both entry points:
 
 | Content | Disposition |
 |---|---|
@@ -137,20 +357,21 @@ The projection transform (`visible-conversation-ledger-v1`) is shared by both en
 | Tool-result images | excluded; recorded as an omission receipt (never raw bytes) |
 | Active `fusion_brainstorm` call and its sibling calls | scope-excluded from the branch |
 
-Omissions are **explicit, deterministic, and auditable** — never silent. Each omitted event produces a ledger row with its kind, exact byte count, and SHA-256 of the omitted bytes. Contiguous omissions collapse into source-ordered `omitted_activity` receipts. Each receipt is deliberately compact, carrying only what a reading model can act on:
+Omissions are **explicit, deterministic, and auditable** — never silent. Each omitted event produces a ledger row with its kind, exact byte count, and SHA-256 of the omitted bytes. Fusion v4 encodes child-facing projection entries as positional tuples to remove repeated object keys while preserving every role, ordinal, span, byte total, count, and text byte:
 
 ```json
-{"at":[1,9],"bytes":29019,"counts":{"tool_calls":5,"tool_result_texts":5},"kind":"omitted_activity"}
+["t","u",0,0,"hello"]
+["o",[1,9],29019,[0,5,5]]
 ```
 
-`at` is the inclusive source-ordinal span, `bytes` is the total omitted non-image payload for that run, and a zero-valued count is absent rather than serialized. Per-event hashes, ledger indices, and the per-kind byte map live in `context-omission-ledger.json`, not in the prompt: a child cannot verify a hash of payload it does not hold, so forwarding one only consumed context. That ledger also carries a `projection_map` proving every ledger row is represented by exactly one receipt or image marker, and `accounting.omission_receipt_utf8_bytes` records the exact receipt cost. The complete ledger is persisted as `context-omission-ledger.json`. **No head, tail, or preview of an omitted payload is ever forwarded** (`tool_payload_preview_bytes` is `0`), because an arbitrary prefix is usually irrelevant and can leak secrets or carry tool-output prompt injection. Repeated construction is byte-identical, so hashes are stable.
+Text tuples are `["t", role, sourceOrdinal, blockOrdinal, text]`, where `role` is `"u"` for user or `"a"` for assistant. Omission tuples are `["o", [firstSourceOrdinal, lastSourceOrdinal], bytes, [assistantThinking, toolCalls, toolResultTexts]]`. The span is inclusive, `bytes` is the total omitted non-image payload for that run, and the count tuple order is fixed. Per-event hashes, ledger indices, and per-event byte details live in `context-omission-ledger.json`, not in the prompt: a child cannot verify a hash of payload it does not hold, so forwarding one only consumed context. That ledger also carries a `projection_map` proving every ledger row is represented by exactly one receipt or ledger-only image marker, and `accounting.omission_receipt_utf8_bytes` records the exact compact tuple receipt cost. The complete ledger is persisted as `context-omission-ledger.json`, and its row shape and root hash are unchanged by the compact encoding. **No head, tail, or preview of an omitted payload is ever forwarded** (`tool_payload_preview_bytes` is `0`), because an arbitrary prefix is usually irrelevant and can leak secrets or carry tool-output prompt injection. Repeated construction is byte-identical via canonical JSON, so prompt bytes and hashes are stable.
 
 Two entry points share the transform but differ in request authority:
 
 | Entry point | Policy id | `request.authority` |
 |---|---|---|
-| `fusion_brainstorm({prompt})` | `fusion-tool-explicit-v1` | `explicit_text` — the prompt is authoritative and self-contained |
-| `/fusion [prompt]` | `fusion-command-conversation-v1` | `directive_over_projected_conversation` |
+| `fusion_brainstorm({prompt})` | `fusion-tool-explicit-v2` | `explicit_text` — the prompt is authoritative and self-contained |
+| `/fusion [prompt]` | `fusion-command-conversation-v2` | `directive_over_projected_conversation` |
 
 **Documented limitation:** facts that exist only inside omitted tool output are not available to Fusion children. Restate any required finding as visible conversation text, or include it in the `fusion_brainstorm` prompt. Children are instructed to say so plainly rather than guess. No model-generated summarization is used as hidden preprocessing.
 
@@ -158,7 +379,7 @@ Two entry points share the transform but differ in request authority:
 
 Every prompt-expansion stage — candidate, evaluator, evaluation repair, and merger — is size-checked **before any child process is created**, and each stage is checked against **its own configured route**, so a large-context slot cannot hide a small-context sibling and a small slot cannot veto stages it never serves.
 
-The input token bound is `ceil(utf8Bytes / 2)`. This is a ceiling, not an estimate: across 159 real large Fusion prompts the densest observed ratio was 3.552 bytes per input token, so the divisor keeps roughly a 1.7x margin and also bounds dense non-ASCII input.
+Input forecasting uses the shared affine estimator `estimateInputTokens({family, segments})`: additive integer byte-class accounting plus a 512-token affine intercept. Calibrated normal-ASCII rates are used only for backed exact model IDs, measured prompts at or above 50 KiB, and prompts that pass the low-whitespace dense-ASCII gate. That gate records the measured whitespace fraction in `budget-plan.json` and falls back conservatively for out-of-distribution near-zero-whitespace payloads; it is a heuristic token-density proxy, not a bound. Multibyte UTF-8 uses the conservative 2.0 B/tok fatal rate while persisting the provable 1.00 B/tok ceiling as advisory. The calibration basis is 882 real large Fusion prompts: Anthropic observed floor 2.047 B/tok (shipped `r=1.73`) and Codex observed floor 3.400 B/tok (shipped `r=2.89`); unknown providers and unbacked model IDs use the unbacked 1.00 B/tok floor and are surfaced in artifacts and result details.
 
 Each stage is forecast with its **real prompt builder**, rendered with empty embedded-output slots, plus the enforced output contracts for whatever that stage will embed:
 
@@ -177,11 +398,11 @@ When a workflow cannot fit, the error names the **first failing mandatory stage*
 
 Remediation is derived, not guessed: Fusion re-plans the entire workflow **with the request removed**. If it still fails, the error says plainly that shortening the request cannot help and points at starting a fresh conversation or raising the route's context window. If it then fits, the request is what determines feasibility, and the error states the exact minimum byte reduction and the maximum safe request size.
 
-Runs that do fit still emit an advisory utilization warning for any stage at or above 80% of its allowance, recorded in `budget-plan.json` and as a progress event, so a session approaching the ceiling is visible before it hard-fails. The warning never alters behaviour.
+Preflight is two-tiered: input-only forecasts are fatal (`prompt_budget_exceeded_forecast`), while worst-case downstream output reservations are warning-only and recorded in `budget-plan.json`. Exact rendered per-stage checks remain fatal (`prompt_budget_exceeded_measured`). Runs that fit still emit advisory warnings for tight utilization or reservation overage. The warning never alters behaviour.
 
 Every configured route must also satisfy a documented minimum capacity; smaller routes are rejected at configuration time with an actionable error naming the requirement, rather than being accepted and failing later at the provider. All route capacities, per-stage forecasts, headroom, utilization, the byte composition of the blocking stage, and the blockers list are persisted as `budget-plan.json`.
 
-If an input still exceeds the safe budget, Fusion fails with a typed `prompt_budget_exceeded` error naming the stage, measured bytes, measured token upper bound, allowed tokens, the limiting configured model and its context window, and concrete remediation. **Zero children are launched** when preflight rejects. Provider context-window failures remain loud child failures; there is no hidden local truncation and no silent fallback anywhere in this path.
+If an input still exceeds the safe budget, Fusion fails with `prompt_budget_exceeded_forecast` for input-only preflight or `prompt_budget_exceeded_measured` for exact rendered prompts. The error names the stage, measured bytes, measured token upper bound, allowed tokens, the limiting configured model and its context window, estimator source, and concrete remediation. **Zero children are launched** when preflight rejects. Provider context-window failures remain loud child failures; there is no hidden local truncation and no silent fallback anywhere in this path.
 
 ## Extension EventBus API
 
@@ -225,7 +446,7 @@ Fusion writes private debugging artifacts under:
 .pi/fusion/<session-id>-<pid>/<run-id>/
 ```
 
-Each run contains `manifest.json`, `canonical-input.json`, `context-omission-ledger.json`, `budget-plan.json`, candidate/evaluation/merge prompts, raw child JSONL events, stderr, responses, `blind-candidates.json`, `evaluation.json`, `merged.md`, and `error.json` for failed/cancelled runs. Persisted stage prompts are byte-identical to the exact bytes written to that child's stdin. `context-omission-ledger.json` carries the complete source-ordered omission ledger, and `budget-plan.json` records every configured route's capacity plus the pre-candidate feasibility decision, so a rejected run is as auditable as a successful one. Artifact files are written by private temp-file/fsync/rename, and v2 manifests persist cumulative child usage plus per-attempt observed usage/model data for successful, failed, and cancelled child attempts. Every usage record preserves the complete Pi cost breakdown; the same exact shape is cloned into `fusion_brainstorm` tool results so newer Pi hosts can calculate and replay footer/session statistics safely. These artifacts are local evidence only; they are not shown in `/jobs` or the background-task dock.
+Each run contains `manifest.json`, `canonical-input.json`, `context-omission-ledger.json`, `budget-plan.json`, candidate/evaluation/merge prompts, raw child JSONL events, stderr, responses, and, when inspect or research candidates run, tool-call logs named `candidate-<slot>.attempt-<n>.tool-calls.jsonl`, plus `blind-candidates.json`, `evaluation.json`, `merged.md`, and `error.json` for failed/cancelled runs. Persisted stage prompts are byte-identical to the exact bytes written to that child's stdin. `context-omission-ledger.json` carries the complete source-ordered omission ledger, and `budget-plan.json` records every configured route's capacity plus the pre-candidate feasibility decision, so a rejected run is as auditable as a successful one. Artifact files are written by private temp-file/fsync/rename, and v2 manifests persist cumulative child usage plus per-attempt observed usage/model data for successful, failed, and cancelled child attempts. Every usage record preserves the complete Pi cost breakdown; the same exact shape is cloned into `fusion_brainstorm` tool results so newer Pi hosts can calculate and replay footer/session statistics safely. These artifacts are local evidence only; they are not shown in `/jobs` or the background-task dock.
 
 For attested Pi tasks only, the task id is `b` plus 32 random hex characters (128 bits) and additional flat siblings are written in the same directory:
 

package/TESTING.md

@@ -24,8 +24,39 @@ npm run test:sdk
 npm run test:rpc
 npm run test:component
 npm run test:package
+npm run test:hook-contract
 ```
 
+`npm run test:hook-contract` is the **Pi hook characterisation gate**. It drives a
+real Pi agent loop against a deterministic scripted provider and records what Pi's
+`context` and `tool_result` hooks actually do, because the `bg_delegate` child-side
+guard depends on that behaviour and it must be proven by execution rather than read
+from type declarations.
+
+The observed guarantees are written to
+`tests/scripted-provider/pi-hook-contract-evidence.json` and shipped as
+`src/core/delegate/hook-contract-evidence.json`. A package test asserts the two are
+byte-identical, so the runtime gate and the gate that proved it cannot drift apart.
+If the evidence file already exists, the gate **compares** against it rather than
+rewriting it: a change in Pi's hook behaviour fails loudly and forces a deliberate
+re-review of the child guard instead of silently regenerating.
+
+On Pi 0.83 the gate establishes, by execution:
+
+| Question | Observed |
+|---|---|
+| Does `context` fire before every model call? | yes, once per call, in extension load order |
+| Do messages returned from `context` reach the provider? | yes |
+| Does **throwing** in `context` prevent the provider call? | **no** — Pi catches it and dispatches anyway |
+| Does `ctx.abort()` prevent it? | it does not skip the call site, but the call receives an already-aborted signal and the run terminates |
+| Does `tool_result` fire before the transcript entry, and can a handler replace it? | yes, chained in load order; the replacement reaches the provider and the original does not |
+| Do tool-call id, role, and `isError` survive replacement? | yes |
+
+Because neither a throw nor an abort is a hard admission gate on its own, the child
+guard uses abort as the barrier **and** removes the oversized content from the
+outgoing message set. A Pi build that cannot provide the required guarantees causes
+`bg_delegate` to refuse to spawn with a typed `delegate_hook_contract_unsupported`.
+
 Full interactive gate:
 
 ```bash
@@ -58,6 +89,69 @@ Current smoke is `tsx scripts/smoke.ts`. It creates a temporary Pi agent/session
 
 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.
 
+### Fusion byte-immutability gates
+
+Two unit gates protect Fusion's persisted artifact bytes, which are a frozen format:
+
+- `tests/unit/fusion-golden-bytes.test.ts` renders an exhaustive 28-case differential
+  corpus (empty conversations, run-boundary and image-coalescing branches, unknown
+  blocks, tool-name ordering, `compactCounts` combinations, UTF-8 and lone-surrogate
+  content, every budget stage across three route sets) and compares the raw bytes
+  against `tests/fixtures/fusion-golden-bytes.json`. The golden file is never
+  auto-updated once it exists.
+- `tests/unit/fusion-extraction-equivalence.test.ts` compares the current
+  implementation against `tests/oracle/fusion-context-pre-extraction.ts`, a verbatim
+  copy of the projection engine as it existed before the shared transform was
+  extracted. This is an **independent oracle**, so equivalence is proven rather than
+  merely self-consistent, including `Object.is` comparison of budget floats and exact
+  error-message parity.
+
+### Delegate gates
+
+- `tests/unit/delegate-seed.test.ts` — verbatim visible text, thinking/tool-payload
+  exclusion, marker-only images, sibling-batch exclusion, byte-identical construction
+  across repeated builds and separate processes, and receive-side seed verification.
+- `tests/unit/delegate-budget.test.ts` — reserve arithmetic, boundary accept/reject,
+  and the total runtime governor.
+- `tests/unit/delegate-result-package.test.ts` — hash verification, strict base64,
+  encoding refusal for lone surrogates, route-mismatch and missing-attestation
+  detection, and explicitly unavailable usage.
+- `tests/unit/delegate-artifacts.test.ts` — spill/receipt coordinates under
+  out-of-order completion, aggregate caps, exact bounded range reads, and terminal
+  evaluation including a zero-exit child that never committed.
+- `tests/unit/delegate-launch.test.ts` — route pinning without substitution, argv-level
+  isolation, the hook-contract gate, and the property that a refused launch creates
+  **zero** children and **zero** artifacts.
+- `tests/scripted-provider/delegate-child-guard.test.ts` — the child guard inside a
+  real Pi agent loop: a 2 MB tool result spilled to a hashed artifact with the payload
+  kept out of the transcript, a blocked over-budget model call, exact bounded range
+  reads, route-drift refusal, and turn-limit enforcement.
+- `tests/sdk/delegate-sdk.test.ts` — the full public loop through the shipped
+  entrypoint with a fake child `pi`: launch receipt, projected context actually
+  reaching the child, child session isolation, not-ready retrieval, corruption
+  detection, and oversized answers degrading to an artifact reference without
+  truncation.
+- `tests/package/delegate-mutation-guard.test.ts` — fails if silent truncation, a
+  silent fallback, a route substitution, an unbounded inline answer, a dropped
+  preflight, a synthesized zero usage, a fail-open guard hook, or an undelivered
+  seed is reintroduced. Verified by actually mutating the source: disabling the
+  spill makes two behavioural tests fail.
+
+### Live subscription evidence run
+
+`npx tsx scripts/delegate-live-run.ts` is a release-time evidence harness. It
+builds a genuinely large parent session (43 visible text entries plus 120 omitted
+tool events withholding ~162 KB of tool-result payload), launches **one** real
+child `pi` on the parent's current **subscription OAuth** route with no API-key
+argument, and asserts that the child produced a hash-verified answer that used
+**both** its read-only file tools and the projected conversation. It also asserts
+the omitted payload never appears in the seed or the child prompt.
+
+It is not part of the default gate because it performs real inference. It caught
+two defects that no offline gate did: a child that verified its seed file but was
+never handed a prompt, and a budget that measured the seed instead of the prompt
+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.
 
 ## Required isolated environment