pi-background-tasks 2.3.0 → 2.4.0

package/README.md

@@ -27,7 +27,7 @@
 | Fact | Value |
 | --- | --- |
 | Package | `pi-background-tasks` |
-| Version | `2.3.0` |
+| Version | `2.4.0` |
 | Node engine | `>=22.19.0` |
 | Pi entrypoints | `./extensions/anthropic-attribution.ts`, `./extensions/background-tasks.ts` |
 | Package image | [logo.png](https://raw.githubusercontent.com/ismailsaleekh/pi-background-tasks/main/logo.png) |
@@ -295,6 +295,7 @@ Agent tasks launched through `pi -p ...` or `pi --mode json ...` and marked `isA
 ## Architecture, trust, and safety
 
 - Runtime task files live under `.pi/tasks/<session-id>-<pid>/`; Fusion artifacts under `.pi/fusion/...`; delegate artifacts under `.pi/delegate/...`.
+- Delegate launch budgeting uses backed route-family calibration for eligible large prompts and records a provable conservative counter-forecast across every byte class. During investigation, text and image-bearing tool output spill losslessly when retaining them would consume protected final-answer runway—even below the normal 64 KiB per-result threshold. Exact artifact ranges return as base64, final capture excludes intermediate tool-use narration, and near the runway boundary tools are disabled for graceful finalization. Runtime token estimates are advisory; Pi/provider own live context admission, avoiding Fusion BUG-185-style false refusals.
 - Shell jobs are tracked by the package, but they are not sandboxed. Treat commands as local processes with your permissions and credentials.
 - Delegate and Fusion child Pi processes are route-pinned where applicable; delegate/Fusion paths do not silently substitute routes.
 - Fusion uses direct child `pi --mode text` processes, not direct completion APIs. Frontier Fusion routes are admitted only through Pi Anthropic or Codex subscription OAuth; metered frontier API credentials are rejected before child creation.

package/TESTING.md

@@ -114,8 +114,7 @@ Two unit gates protect Fusion's persisted artifact bytes, which are a frozen for
 - `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-budget.test.ts` — reserve arithmetic, backed-family versus conservative launch policy, incident byte-class fixture replay, provable multibyte counter-forecast, retained-growth runway, boundary accept/reject, and advisory runtime measurement.
 - `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.
@@ -132,8 +131,13 @@ Two unit gates protect Fusion's persisted artifact bytes, which are a frozen for
   resolves the exact pinned provider, retains the package guard, and commits.
 - `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.
+  kept out of the transcript, structured preservation of image-bearing results,
+  repeated sub-64-KiB results spilling against protected route runway, BUG-185
+  regression coverage proving advisory estimates do not abort a valid live request,
+  graceful no-tool finalization, byte-exact base64 range reads including a split UTF-8
+  sequence, malformed-Unicode spill refusal, exclusion of intermediate tool-use
+  narration from the committed answer, multi-turn usage accumulation, route-drift
+  refusal, answer capture, 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, default isolated argv, explicit ambient argv/warning/metadata,

package/TEST_PLAN.md

@@ -91,9 +91,9 @@ SDK/RPC/scripted-provider/package/compatibility coverage asserts exactly four to
 | 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 real Pi agent loops and records, rather than assumes: Fusion `before_provider_request` transformations chain in extension load order through the Codex transport adapter and abort before local HTTP transport; Delegate `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()` either skips provider invocation (Pi 0.84) or delivers an already-aborted signal (older supported lines), blocks transport, 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.v2`, `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, hash-bound `extension_mode`, 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, an unknown extension mode, 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, 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 budget and guard | `budget-plan.json` v3, `runtime-budget.json`, typed `seed_budget_exceeded` | yes | yes |  |  |  | mutation guard | yes | Unit covers reserve subtraction, exact-boundary accept and one-byte-past reject, backed large-prompt family calibration with a provable every-byte-class counter-forecast, the 173,740-byte compacted-session incident byte-class fixture, protected retained-growth/finalization runway, child system prompt input, multi-byte UTF-8, and conservative fallback for small/unbacked routes. Preflight refusal creates **zero** children and **zero** artifacts. Scripted-provider coverage pins Fusion BUG-185, image-bearing structured spill fidelity, base64 range fidelity across split UTF-8, final-answer-only capture, and truthful diagnostics. An advisory overage does not self-report provider exhaustion or abort valid transport; it disables tools for graceful finalization. Runtime evidence records retained/spilled bytes, context estimates, first-request usage, and calibration underforecast. |
+| 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 escape, and non-positive lengths are refused. Scripted-provider coverage additionally proves repeated 32 KiB results—each below the fixed 64 KiB cap—spill proactively when retaining them would consume protected final-answer runway, while the child still commits a complete answer. |
+| 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. Unit covers round-trip verification, exact encoding, corruption/identity/route rejection, explicitly unavailable usage, answer capture enforcement, zero-exit/no-commit, child-recorded failure, and cancellation. SDK covers not-ready, completed, corrupted, route-drift, unknown-task, and no-truncation delivery. Terminal diagnostics dynamically advertise only paths that exist: the merged `.pi/tasks/...output` path is reported when available, while absent delegate-local `child.stdout.txt`/`child.stderr.txt` files are never claimed. |
 | Delegate extension/isolation boundary | `extensionMode`, child argv, `--session-id`, `--session-dir`, `--tools` | yes | yes |  |  |  | mutation guard | yes | Unit proves default/explicit isolated mode sets `--no-extensions`; ambient mode omits only that flag; both modes retain separate task-owned session identity, inspect-only model tools, the explicit denylist, disabled skills/prompt templates/themes/context files, and the package guard; Anthropic keeps attribution-before-guard in both modes. Public schema/preparation rejects unknown modes, arbitrary `extensions`/`extensionPaths`, and route substitution. Seed/task facts/launch details/manifest bind the selected mode, and ambient receipt text warns that arbitrary extension code executes outside the tool sandbox. SDK verifies argv, warning, and metadata. A fresh-process scripted-provider regression installs a provider only in a temp global extension directory: isolated mode fails unknown-provider with no result, while ambient mode resolves that exact pinned provider and commits under the guard. |
 | 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. |

package/docs/INDEX.md

@@ -142,7 +142,7 @@ Generated navigation for every package-local documentation page. This index inte
 | tool | `bg_delegate` | `tool:bg_delegate` | `src/delegate-extension.ts:340` |
 | tool | `bg_kill` | `tool:bg_kill` | `src/extension.ts:908` |
 | tool | `bg_logs` | `tool:bg_logs` | `src/extension.ts:863` |
-| tool | `bg_result` | `tool:bg_result` | `src/delegate-extension.ts:515` |
+| tool | `bg_result` | `tool:bg_result` | `src/delegate-extension.ts:516` |
 | tool | `bg_run` | `tool:bg_run` | `src/extension.ts:682` |
 | tool | `bg_run_pi_attested` | `tool:bg_run_pi_attested` | `src/extension.ts:767` |
 | tool | `bg_status` | `tool:bg_status` | `src/extension.ts:832` |

package/docs/concepts/context-projection-and-budgeting.md

@@ -62,7 +62,8 @@ Calibration facts in code:
 - observed large Fusion prompt corpus: 882 prompts, dated 2026-08-02;
 - Anthropic configured rate: 1.73 B/token after haircut;
 - OpenAI Codex configured rate: 2.89 B/token after haircut;
-- conservative/floor rates are used for delegate scope, small prompts, unbacked models, unknown providers, capacity guards, and dense-ASCII out-of-domain cases.
+- delegate launch uses backed family calibration only for large prompts on routes that can hold the calibration domain; small prompts/routes, unbacked models, unknown providers, and dense-ASCII out-of-domain cases use conservative/floor rates;
+- delegate runtime context estimates are advisory, while a separate provable `1.00 B/token` retained-growth budget drives explicit spilling and no-tool finalization.
 
 The dense-ASCII gate is explicitly a low-whitespace heuristic proxy, not a tokenizer guarantee. Calibration applies only when the input is in the measured domain and the route capacity can hold that domain.
 
@@ -70,9 +71,10 @@ The dense-ASCII gate is explicitly a low-whitespace heuristic proxy, not a token
 
 - `allowedInputTokens()` returns a signed number and never clamps unusable routes to zero.
 - Callers must reject unusable or too-small context windows before spawning children.
-- Multibyte bytes cannot bypass accounting.
+- Multibyte bytes cannot bypass accounting; delegate's published provable counter-forecast charges them at the same `1.00 B/token` ceiling as every other byte class.
 - Unknown output contracts are charged separately; future output cannot be assumed to be cheap.
 - Rate-source warnings are part of the contract and should be surfaced in refusal details.
+- A package-local estimate must not reject a live provider payload by subtracting hypothetical output; Fusion BUG-185 established this as a false-refusal shape. Use conservative estimates for lossless spill decisions, where a false positive preserves bytes rather than failing work.
 
 ## No silent truncation
 

package/docs/manifest.json

@@ -13,18 +13,17 @@
       "state": "pass"
     },
     {
-      "authored_body_sha256": "sha256:36942d62aa217dad07813c7900291adbc39b1ac859b18d94f606db0ce2e13a9f",
+      "authored_body_sha256": "sha256:810591c82ced086e1622be9b037db88c8a667856580895dc90cd5af54c6e2107",
       "covers_sources": [
         "src/core/context/parent-snapshot.ts",
         "src/core/context/token-budget.ts",
         "src/core/context/visible-conversation-v2.ts"
       ],
       "doc_id": "concepts/context-projection-and-budgeting",
-      "notes": "Reviewed visible conversation transform identity, active-branch snapshotting, omission receipts and hashes, text/tool/thinking/image dispositions, token estimators, calibration, reserves, warnings, and fail-loud no-truncation behavior.",
       "rel": "docs/concepts/context-projection-and-budgeting.md",
       "required": true,
       "reviewer": "gpt-5.5-final-context-projection-reviewer",
-      "state": "pass"
+      "state": "stale-authored-prose"
     },
     {
       "authored_body_sha256": "sha256:72c53dcc104f9b5efa57e38bcb21a4c3c620d5caf1571af82348f94dcafbe941",
@@ -75,7 +74,7 @@
       "state": "stale-authored-prose"
     },
     {
-      "authored_body_sha256": "sha256:bc319ce7e62d2592c71476f950947c8ff011fb74e7f2093b0169f77d59980f18",
+      "authored_body_sha256": "sha256:67fbb232e66bf0b9f4c1a81b54ec5476c0aae929ed0f0777d57601afcac8e08b",
       "covers_sources": [
         "extensions/delegate-child.ts",
         "src/core/delegate/artifacts.ts",
@@ -833,7 +832,7 @@
     "image": "https://raw.githubusercontent.com/ismailsaleekh/pi-background-tasks/main/logo.png",
     "name": "pi-background-tasks",
     "type": "module",
-    "version": "2.3.0"
+    "version": "2.4.0"
   },
   "public_surface_ids": [
     "command:bg",
@@ -1172,7 +1171,7 @@
           ],
           "type": "object"
         },
-        "source": "src/delegate-extension.ts:515"
+        "source": "src/delegate-extension.ts:516"
       },
       {
         "description": "Start a named long-running shell command in the background and return immediately with a task ID and output path. By default, completed, failed, or killed terminal state is delivered automatically as <background-task-notification> and starts a follow-up agent turn; do not sleep or poll merely to wait. Output is written to .pi/tasks and model-visible logs are bounded to 50.0KB.",

package/docs/operations/troubleshooting.md

@@ -24,7 +24,9 @@ Start from the symptom, verify the source-owned doc, then apply the remediation.
 | 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. |
+| Delegate refuses with `seed_budget_exceeded` | Exact child prompt plus system prompt exceeds allowed input under the backed route-family policy or conservative fallback | Use a larger-context subscription route, delegate earlier, or reduce visible parent text. Nothing was clipped. |
+| Delegate spills many individually small tool results | Retaining them would consume protected final-answer runway | This is expected lossless pressure control. The full bytes are in `spill/`; inspect `runtime-budget.json`. Narrow the investigation only if receipt-driven range reads become excessive. |
+| Delegate enters finalization runway | Advisory context/runway pressure disabled tools so the child can answer from gathered evidence | Let the child finish. Do not re-enable tools or treat the advisory estimate as a provider context rejection. |
 | `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. |

package/docs/reference/runtime-contracts.md

@@ -37,11 +37,11 @@ This generated registry lists production environment-variable references, runtim
 | `PI_API_BASE_URL` | remove | `src/core/attested-pi-run.ts:135`<br>`src/core/fusion/pi-child.ts:98` |
 | `PI_API_KEY` | remove | `src/core/attested-pi-run.ts:135`<br>`src/core/fusion/pi-child.ts:98` |
 | `PI_AUTH_FILE` | remove | `src/core/attested-pi-run.ts:135`<br>`src/core/fusion/pi-child.ts:98` |
-| `PI_BG_DELEGATE_ARTIFACT_DIR` | read, write | `src/core/delegate/launch.ts:353`<br>`src/delegate-child-extension.ts:279` |
-| `PI_BG_DELEGATE_LAUNCH_NONCE` | read, write | `src/core/delegate/launch.ts:357`<br>`src/delegate-child-extension.ts:283` |
-| `PI_BG_DELEGATE_SEED_PATH` | read, write | `src/core/delegate/launch.ts:354`<br>`src/delegate-child-extension.ts:280` |
-| `PI_BG_DELEGATE_SEED_SHA256` | read, write | `src/core/delegate/launch.ts:355`<br>`src/delegate-child-extension.ts:281` |
-| `PI_BG_DELEGATE_TASK_ID` | read, write | `src/core/delegate/launch.ts:356`<br>`src/delegate-child-extension.ts:282` |
+| `PI_BG_DELEGATE_ARTIFACT_DIR` | read, write | `src/core/delegate/launch.ts:353`<br>`src/delegate-child-extension.ts:384` |
+| `PI_BG_DELEGATE_LAUNCH_NONCE` | read, write | `src/core/delegate/launch.ts:357`<br>`src/delegate-child-extension.ts:388` |
+| `PI_BG_DELEGATE_SEED_PATH` | read, write | `src/core/delegate/launch.ts:354`<br>`src/delegate-child-extension.ts:385` |
+| `PI_BG_DELEGATE_SEED_SHA256` | read, write | `src/core/delegate/launch.ts:355`<br>`src/delegate-child-extension.ts:386` |
+| `PI_BG_DELEGATE_TASK_ID` | read, write | `src/core/delegate/launch.ts:356`<br>`src/delegate-child-extension.ts:387` |
 | `PI_BG_DISABLE_PI_TELEMETRY` | read | `src/core/registry.ts:195` |
 | `PI_BG_DISABLE_UPDATE_CHECK` | read | `src/extension.ts:455` |
 | `PI_BG_MAX_OUTPUT_BYTES` | read | `src/core/registry.ts:69` |
@@ -71,16 +71,14 @@ This generated registry lists production environment-variable references, runtim
 | Kind | Path/artifact | Provenance |
 | --- | --- | --- |
 | config | `fusion-models.json` | `src/core/fusion/config.ts:21` |
-| delegate-artifact | `budget-plan.json` | `src/core/delegate/artifacts.ts:43` |
-| delegate-artifact | `child-prompt.txt` | `src/core/delegate/artifacts.ts:47` |
-| delegate-artifact | `child.stderr.txt` | `src/core/delegate/artifacts.ts:48` |
-| delegate-artifact | `child.stdout.txt` | `src/core/delegate/artifacts.ts:49` |
-| delegate-artifact | `context-omission-ledger.json` | `src/core/delegate/artifacts.ts:42` |
+| delegate-artifact | `budget-plan.json` | `src/core/delegate/artifacts.ts:44` |
+| delegate-artifact | `child-prompt.txt` | `src/core/delegate/artifacts.ts:48` |
+| delegate-artifact | `context-omission-ledger.json` | `src/core/delegate/artifacts.ts:43` |
 | delegate-artifact | `error.json` | `src/core/delegate/artifacts.ts:50` |
-| delegate-artifact | `manifest.json` | `src/core/delegate/artifacts.ts:44` |
-| delegate-artifact | `outcome.json` | `src/core/delegate/artifacts.ts:45` |
+| delegate-artifact | `manifest.json` | `src/core/delegate/artifacts.ts:45` |
+| delegate-artifact | `outcome.json` | `src/core/delegate/artifacts.ts:46` |
 | delegate-artifact | `result.json` | `src/core/delegate/result-package.ts:28` |
-| delegate-artifact | `seed.json` | `src/core/delegate/artifacts.ts:41` |
+| delegate-artifact | `seed.json` | `src/core/delegate/artifacts.ts:42` |
 | delegate-artifact | `spill/<receipt-named-file>` | `src/core/delegate/artifacts.ts:54` |
 | directory | `.pi/delegate/<session-id>-<pid>/<task-id>/` | `src/core/delegate/artifacts.ts:160` |
 | directory | `.pi/fusion/<session-id>-<pid>/<run-id>/` | `src/core/fusion/artifacts.ts:563` |
@@ -116,17 +114,19 @@ This generated registry lists production environment-variable references, runtim
 | 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:387` |
+| `pi-background-tasks.delegate-budget-plan.v3` | `src/core/delegate/types.ts:21` |
+| `pi-background-tasks.delegate-child-terminal.v1` | `src/delegate-child-extension.ts:584` |
 | `pi-background-tasks.delegate-hook-contract.v1` | `src/core/delegate/hook-contract.ts:15` |
 | `pi-background-tasks.delegate-launch.v1` | `src/delegate-extension.ts:458` |
 | `pi-background-tasks.delegate-ledger.v1` | `src/core/delegate/types.ts:16` |
 | `pi-background-tasks.delegate-manifest.v2` | `src/core/delegate/types.ts:22` |
-| `pi-background-tasks.delegate-outcome.v1` | `src/core/delegate/runner.ts:224` |
+| `pi-background-tasks.delegate-outcome.v1` | `src/core/delegate/runner.ts:228` |
 | `pi-background-tasks.delegate-receipt.v1` | `src/core/delegate/types.ts:19` |
-| `pi-background-tasks.delegate-result-view.v1` | `src/delegate-extension.ts:731` |
+| `pi-background-tasks.delegate-result-view.v1` | `src/delegate-extension.ts:734` |
 | `pi-background-tasks.delegate-result.v1` | `src/core/delegate/types.ts:18` |
+| `pi-background-tasks.delegate-runtime-budget.v1` | `src/delegate-child-extension.ts:489` |
 | `pi-background-tasks.delegate-seed.v2` | `src/core/delegate/types.ts:15` |
+| `pi-background-tasks.delegate-tool-result-content.v1` | `src/delegate-child-extension.ts:190` |
 | `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` |
@@ -149,7 +149,7 @@ This generated registry lists production environment-variable references, runtim
 | `pi-background-tasks.fusion-merge-input.v1` | `src/core/fusion/prompts.ts:336` |
 | `pi-background-tasks.fusion-models.v1` | `src/core/fusion/types.ts:13` |
 | `pi-background-tasks.fusion-progress.v1` | `src/fusion-extension.ts:59` |
-| `pi-background-tasks.fusion-result-view.v1` | `src/delegate-extension.ts:772` |
+| `pi-background-tasks.fusion-result-view.v1` | `src/delegate-extension.ts:775` |
 | `pi-background-tasks.fusion-result.v4` | `src/core/fusion/types.ts:19` |
 | `pi-background-tasks.fusion-result.v5` | `src/core/fusion/types.ts:20` |
 | `pi-background-tasks.fusion-runtime-guard.v2` | `src/core/fusion/child-protocol.ts:24` |

package/docs/subsystems/delegation.md

@@ -82,43 +82,52 @@ Routes are pinned once:
 - unavailable/unknown-capacity routes fail;
 - no substitution, fallback, or retry on a different route.
 
-Budgets use a delegate-specific conservative estimator. Constants currently documented by source/tests:
+Budgeting separates admission from package-owned runtime growth. Constants currently documented by source/tests:
 
 - reserved output: `16,384` tokens;
 - framing reserve: `8,192` tokens;
 - safety reserve: `4,096` tokens;
 - minimum usable input: `8,192` tokens;
+- protected finalization input runway: `32,768` tokens;
+- finalization trigger inside retained-growth runway: `8,192` tokens;
 - default turns/tools/timeout: `24` / `120` / `1200s`;
 - per-result transcript cap: `64 KiB`;
-- aggregate tool-output cap: `64 MiB`;
-- answer capture cap value carried in the seed: `4 MiB`; current child code does not separately enforce this before packaging;
+- aggregate raw tool-output cap: `64 MiB`;
+- answer capture cap: `4 MiB`, enforced before result packaging;
 - inline answer cap: `48 KiB`.
 
-Launch admission measures the child system prompt plus the actual child prompt carrying the seed. Runtime guard measures retained input before every model call. An over-budget runtime call latches `provider_context_budget_exhausted`, aborts the run, and suppresses outgoing content.
+Launch admission measures the child system prompt plus the exact child prompt carrying the seed. Backed large prompts use the shared family calibration; prompts or routes below the calibration domain and unknown/unbacked routes use the provable `1.00 B/token` profile. `budget-plan.json` v3 also records the provable conservative counter-forecast, protected finalization reserve, and retained-growth budget.
+
+After launch, token measurements are advisory. Fusion BUG-185 proved that a package-local estimate must not reject a live provider payload after subtracting hypothetical output. Delegate therefore does not self-report provider exhaustion from that estimate. Pi and the provider own live context handling; a genuine provider context error remains loud. Package-owned growth is controlled before transcript entry: a tool result spills whenever it exceeds the per-result cap **or** retaining it would consume protected final-answer runway. Conservative false positives therefore create explicit hash receipts rather than failed tasks. Near the end of the runway the child disables tools and injects one finalization instruction so it can answer from evidence already gathered.
 
 ## Child guard and commit discipline
 
 The child verifies seed hash, task id, and launch nonce at extension load before the first model call. It then enforces:
 
-- context budget before every provider call;
-- per-result spill receipts before tool output enters the transcript;
-- aggregate tool-output cap;
+- advisory retained-context measurement before every provider call, without a BUG-185-style token abort;
+- route-runway-aware and per-result spill receipts before tool output enters the transcript, including structured preservation of image-bearing results;
+- bounded artifact range reads returned as lossless base64 against remaining inline runway;
+- aggregate raw tool-output cap;
+- protected no-tool finalization when retained-growth runway becomes low;
 - turn and tool-call limits;
 - route attestation for assistant messages;
-- complete usage records only (missing/partial usage is `unavailable`, never zero);
+- per-turn usage accumulation across the full agent loop; if any turn is missing/partial, aggregate usage is `unavailable` rather than understated or replaced by a later record;
 - accepted final stop reason `stop` only, so provider `length` stops become `child_model_output_limit` rather than partial success;
+- answer capture from only the final clean-stop assistant message, never intermediate tool-use narration;
 - non-empty, non-whitespace answer text;
-- well-formed UTF-8 answer blocks.
+- the declared answer capture cap, with no partial result on overflow;
+- well-formed UTF-8 answer blocks;
+- durable `runtime-budget.json` evidence containing context measurements, retained/spilled bytes, finalization state, first-request observed usage, and calibration-underforecast evidence.
 
 A terminal latch prevents later success commit after any degraded/refused condition. This avoids a hash-valid result built on silently modified context.
 
 `result.json` is the single answer data plane. It is child-written by temp file, file fsync, and rename; POSIX then fsyncs the parent directory, while Windows skips directory fsync because Node does not provide the same portable guarantee there. Final-name presence is the child commit point. No final `result.json` means no accepted answer, regardless of process exit code. `child-terminal.json` records child-side terminal failures when no success package is committed.
 
-After adjudication, the parent makes a best-effort durable write of `outcome.json`. This is separate from `result.json` so child and parent cannot race over one state field. An `outcome.json` write failure is currently ignored and does not change the returned adjudication, so the artifact may be absent even though evaluation completed. Child stdout/stderr are currently captured in the background task output file; although delegate artifact constants name `child.stdout.txt` and `child.stderr.txt`, current registry finalization does not populate those files in the delegate artifact directory.
+After adjudication, the parent makes a best-effort durable write of `outcome.json`. This is separate from `result.json` so child and parent cannot race over one state field. An `outcome.json` write failure is currently ignored and does not change the returned adjudication, so the artifact may be absent even though evaluation completed. Child stdout/stderr are captured in the background task output file. Delegate-local `child.stdout.txt` and `child.stderr.txt` are not currently populated, and terminal reporting now lists only diagnostic paths that actually exist.
 
 ## Spill artifacts and `delegate_read_artifact`
 
-Oversized tool results are durably written in full under `spill/` and replaced with receipts. A failed spill withholds the original payload and latches a terminal failure; no uncommitted artifact is claimed by receipt.
+Oversized tool results are durably written in full under `spill/` and replaced with receipts. A single text block is stored as exact UTF-8; malformed lone-surrogate text is rejected rather than silently converted to U+FFFD. Multi-block or image-bearing content is stored in a closed JSON envelope that preserves block boundaries, MIME types, text, and complete base64 image data. New receipts record `content_format`; historical v1 receipts without that optional field remain readable. A failed spill withholds the original payload and latches a terminal failure; no uncommitted artifact is claimed by receipt.
 
 `delegate_read_artifact` requires:
 
@@ -126,7 +135,7 @@ Oversized tool results are durably written in full under `spill/` and replaced w
 - `offset: non-negative safe integer`;
 - `length: positive safe integer`.
 
-It reads the whole artifact file, verifies the requested range is in bounds, and returns exactly that UTF-8-decoded range. Path escape and short reads fail loudly.
+It reads the whole artifact file, verifies the requested range is in bounds, and returns the exact bytes as base64 plus offset/length metadata. Arbitrary ranges are never decoded as UTF-8, so a range that splits a multibyte sequence remains byte-exact rather than becoming U+FFFD. Path escape and short reads fail loudly.
 
 ## Retrieval contract
 
@@ -163,7 +172,7 @@ Launch / execution:
 
 Budget / limits:
 
-- `provider_context_budget_exhausted`
+- `provider_context_budget_exhausted` (legacy terminal records only; current children do not infer provider exhaustion from an advisory estimate)
 - `aggregate_tool_output_cap`
 - `child_model_output_limit`
 - `child_capture_limit`

package/docs/subsystems/docs-freshness-gate.md

@@ -12,14 +12,14 @@ covers_sources: []
 This authored section defines the boundary: documentation facts are extracted from package metadata and TypeScript ASTs, then generated into docs and the manifest. Unsupported syntax fails the gate rather than falling back to regex or stale hand-maintained inventories. Public registrations must remain unconditional top-level direct calls or use the one validated local tool-wrapper shape; host/method aliases, computed access, nested or conditional registration, wrapper chaining/passing, constructor helpers, ambiguous public metadata, destructured Pi parameters, and repeated imported registrars are rejected.
 
 <!-- pi-docs:begin name="docs-freshness-gate" generator="scripts/docs/generate.mjs" -->
-- Canonical package version: `2.3.0`
+- Canonical package version: `2.4.0`
 - Governed markdown docs: 42
 - Public surfaces extracted: 31
 - Governed production sources: 50
 - Tool contracts extracted: 11
-- Schema IDs extracted: 44
+- Schema IDs extracted: 46
 - Environment variable references extracted: 49
-- Behavioral attestation receipts not passing: 7
+- Behavioral attestation receipts not passing: 8
 - Receipt store: `docs/attestations.json`
 
 `npm run docs:verify` is read-only: it renders generated files twice in memory and compares them with committed bytes. `npm run docs:generate` is the only docs writer.

package/docs/tools/bg_delegate.md

@@ -186,19 +186,24 @@ Budgets and limits:
 - route capacity is the declared context window minus reserves: `16,384` output, `8,192` framing, `4,096` safety tokens;
 - minimum usable input is `8,192` tokens;
 - launch admission measures the child system prompt plus the exact child prompt bytes that carry the seed;
-- runtime context is measured before each model call;
-- per-tool-result transcript cap: `64 KiB`;
-- aggregate tool-output cap: `64 MiB`;
-- answer capture cap value in the seed: `4 MiB`; current child code carries this limit but does not separately enforce it before packaging;
+- backed large prompts use route-family calibration; the plan also records a provable `1.00 B/token` counter-forecast for every byte class, including multibyte input;
+- `32,768` input tokens are protected for finalization, with an `8,192`-token low-runway trigger;
+- runtime context estimates are advisory and never masquerade as provider context truth;
+- tool results spill above `64 KiB` or earlier when retaining them would consume protected runway;
+- artifact range reads are bounded by remaining inline runway;
+- aggregate raw tool-output cap: `64 MiB`;
+- answer capture cap: `4 MiB`, enforced without committing a prefix;
 - timeout defaults to `1200s`.
 
-Artifacts are under `.pi/delegate/<session-id>-<pid>/<task-id>/` and include `seed.json`, `child-prompt.txt`, `context-omission-ledger.json`, `budget-plan.json`, `manifest.json`, `child-session/`, `spill/`, and later `result.json` / `outcome.json` when produced. Child stdout/stderr are captured through the background task output path; the delegate artifact constants include child stream filenames, but current launch/finalize code does not mirror streams into those delegate files.
+When protected runway becomes low, the child disables tools and is instructed to answer immediately from evidence already gathered. Pi and the provider—not the package estimator—own final live context admission. A genuine provider context rejection remains a loud failure and is never retried on another route.
+
+Artifacts are under `.pi/delegate/<session-id>-<pid>/<task-id>/` and include `seed.json`, `child-prompt.txt`, `context-omission-ledger.json`, `budget-plan.json`, `manifest.json`, `child-session/`, `spill/`, `runtime-budget.json`, and later `result.json` / `outcome.json` when produced. Child stdout/stderr are captured through the background task output path; terminal failures report that real merged output path when it exists and do not claim absent delegate-local stream files.
 
 ## Spilled tool output
 
-Oversized child tool results are written in full to `spill/...` artifacts and replaced in the transcript by receipts carrying path, byte length, SHA-256, tool name, call id, turn sequence, and source call index. The raw oversized payload is not forwarded as a fallback and is not truncated.
+Oversized child tool results are written in full to `spill/...` artifacts and replaced in the transcript by receipts carrying path, byte length, SHA-256, content format, tool name, call id, turn sequence, and source call index. Single text blocks retain their exact UTF-8 bytes; malformed lone-surrogate text fails loudly instead of being substituted. Multi-block and image-bearing results use a structured JSON envelope preserving text, block boundaries, MIME type, and complete base64 image data. The raw oversized payload is not forwarded as a fallback and is not truncated.
 
-Inside the child, `delegate_read_artifact({artifact, offset, length})` reads an exact byte range. It refuses path escape, negative/non-integer offsets, non-positive lengths, and reads past EOF rather than returning a short/clamped range.
+Inside the child, `delegate_read_artifact({artifact, offset, length})` reads an exact byte range and returns those bytes as base64. It refuses path escape, negative/non-integer offsets, non-positive lengths, and reads past EOF rather than returning a short/clamped range. Base64 prevents a range that splits a UTF-8 sequence from being silently changed to replacement characters.
 
 ## Completion
 

package/docs/tools/bg_result.md

@@ -11,7 +11,7 @@ covers_sources: []
 
 <!-- pi-docs:begin name="tool-contract-bg_result" generator="scripts/docs/generate.mjs" -->
 - Label: **Background Result**
-- Source: `src/delegate-extension.ts:515`
+- Source: `src/delegate-extension.ts:516`
 - Description: Retrieve a hash-verified result from a bg_delegate or background Fusion task. Never blocks: a running task returns a typed not-ready result. Oversized answers are never truncated.
 - Root schema: `object`; additionalProperties: `false`
 
@@ -124,7 +124,7 @@ Common delegate retrieval outcomes:
 - `result_too_large_for_inline` — explicit inline request exceeded the inline cap.
 - Fusion `summary_status:"integrity_failed"` — a terminal summary or its manifest binding failed verification; no summary metadata is trusted.
 
-Delegate errors include whether a child process was created, preserved artifact hints when known, and remediation text. Usage missing from the provider is reported as `unavailable`, not synthesized as zero. Fusion retrieval additionally fails on non-completed manifests, identity/schema drift, malformed usage/details, invalid UTF-8, or any manifest/result/merged hash or byte-length mismatch; failed/cancelled runs return their preserved terminal error rather than partial output.
+Delegate errors include whether a child process was created, preserved artifact hints that are checked for existence, the real merged task output path when available, and remediation text. Usage missing from the provider is reported as `unavailable`, not synthesized as zero. Fusion retrieval additionally fails on non-completed manifests, identity/schema drift, malformed usage/details, invalid UTF-8, or any manifest/result/merged hash or byte-length mismatch; failed/cancelled runs return their preserved terminal error rather than partial output.
 
 ## Parent outcome separation
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-background-tasks",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "Pi extension for durable background shell tasks, read-only delegated agents, local attested Pi runs, and fixed-purpose Fusion workflows through child Pi processes.",
   "type": "module",
   "license": "ISC",

package/src/core/context/token-budget.ts

@@ -45,7 +45,11 @@ export const TOKEN_BUDGET_SEGMENT_KINDS = [
 ] as const;
 export type TokenBudgetSegmentKind = (typeof TOKEN_BUDGET_SEGMENT_KINDS)[number];
 
-export type TokenBudgetEstimatorScope = 'fusion' | 'delegate' | 'conservative';
+export type TokenBudgetEstimatorScope =
+  | 'fusion'
+  | 'delegate_launch'
+  | 'delegate'
+  | 'conservative';
 export type TokenBudgetDominantByteClass =
   | 'normal'
   | 'dense_ascii'
@@ -526,7 +530,7 @@ function rateSourceWarning(input: {
     return `model is not in the exact calibration backing set for family ${input.family}; using the provable 1.00 B/tok floor`;
   }
   if (input.source === 'delegate_conservative') {
-    return 'delegate scope withholds calibrated rates and uses the provable 1.00 B/tok profile for launch/runtime headroom';
+    return 'delegate launch/runtime uses the provable 1.00 B/tok profile when the prompt or route is below the backed large-prompt calibration domain';
   }
   if (input.source === 'explicit_conservative') {
     return 'explicit conservative scope uses the provable 1.00 B/tok profile';
@@ -569,7 +573,16 @@ function effectiveRateSource(input: {
       ? 'unbacked_model_floor'
       : 'unknown_provider_floor';
     effective = TOKEN_BUDGET_PROVABLE_RATE_X100;
-  } else if (input.scope === 'delegate') {
+  } else if (
+    input.scope === 'delegate' ||
+    (input.scope === 'delegate_launch' &&
+      (input.profile.concrete_known_bytes < TOKEN_BUDGET_LARGE_PROMPT_MIN_BYTES ||
+        (input.allowedInputTokens !== undefined &&
+          Math.floor(
+            (input.allowedInputTokens * TOKEN_BUDGET_DELEGATE_CONSERVATIVE_RATE_X100) /
+              TOKEN_BUDGET_RATE_SCALE,
+          ) < TOKEN_BUDGET_LARGE_PROMPT_MIN_BYTES)))
+  ) {
     source = 'delegate_conservative';
     effective = Math.min(configured, TOKEN_BUDGET_DELEGATE_CONSERVATIVE_RATE_X100);
   } else if (input.scope === 'conservative') {

package/src/core/delegate/artifacts.ts

@@ -1,4 +1,5 @@
 import { createHash } from 'node:crypto';
+import { existsSync } from 'node:fs';
 import { chmod, mkdir, open, readFile, rename, rm } from 'node:fs/promises';
 import { basename, isAbsolute, join, relative, sep } from 'node:path';
 import { canonicalJson } from '../attested-pi-run.js';
@@ -45,8 +46,7 @@ export const DELEGATE_ARTIFACT_NAMES = {
   outcome: 'outcome.json',
   result: DELEGATE_RESULT_PACKAGE_FILENAME,
   childPrompt: 'child-prompt.txt',
-  childStderr: 'child.stderr.txt',
-  childStdout: 'child.stdout.txt',
+  runtimeBudget: 'runtime-budget.json',
   error: 'error.json',
 } as const;
 
@@ -232,11 +232,6 @@ export class DelegateArtifactStore {
     return this.write(DELEGATE_ARTIFACT_NAMES.budgetPlan, `${canonicalJson(plan)}\n`);
   }
 
-  async writeChildStreams(stdout: Buffer, stderr: Buffer): Promise<void> {
-    await this.write(DELEGATE_ARTIFACT_NAMES.childStdout, stdout);
-    await this.write(DELEGATE_ARTIFACT_NAMES.childStderr, stderr);
-  }
-
   /** Commit the run. The rename performed here is the single success point. */
   async commitResult(pkg: DelegateResultPackageV1): Promise<DelegateArtifactRef> {
     const ref = await this.write(
@@ -251,17 +246,23 @@ export class DelegateArtifactStore {
     try {
       return await readFile(this.resultPathAbs, 'utf8');
     } catch (error) {
+      const diagnosticNames = [
+        DELEGATE_ARTIFACT_NAMES.error,
+        DELEGATE_ARTIFACT_NAMES.outcome,
+        DELEGATE_ARTIFACT_NAMES.runtimeBudget,
+        DELEGATE_ARTIFACT_NAMES.manifest,
+      ].filter((name) => existsSync(join(this.rootAbs, name)));
       throw new DelegateError(
-        `delegate result package is not present at ${join(this.rootDisplay, DELEGATE_ARTIFACT_NAMES.result)}; the child produced no committed answer`,
+        `delegate result package could not be read at ${join(this.rootDisplay, DELEGATE_ARTIFACT_NAMES.result)}; no committed answer is available (${error instanceof Error ? error.message : String(error)})`,
         {
           code: 'result_unavailable',
           childCreated: true,
           taskId: this.manifest.task_id,
           artifactDir: this.rootDisplay,
-          preserved: [this.rootDisplay],
-          remediation: [
-            'Inspect child.stderr.txt and error.json in the artifact directory for the recorded failure.',
-          ],
+          preserved: diagnosticNames,
+          remediation: diagnosticNames.length === 0
+            ? ['No diagnostic control artifact exists; inspect the background task merged output if one was created.']
+            : [`Inspect the existing delegate control artifacts: ${diagnosticNames.join(', ')}.`],
         },
       );
     }
@@ -353,6 +354,7 @@ export class DelegateArtifactStore {
       source_call_index: input.sourceCallIndex,
       byte_length: input.payload.length,
       sha256: sha256Bytes(input.payload),
+      content_format: 'opaque_bytes',
     };
   }