pi-background-tasks 2.1.4 → 2.4.0

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/getting-started.md

@@ -82,6 +82,7 @@ Use `bg_delegate` when the worker needs the current conversation as background b
   "name": "Config audit",
   "prompt": "Inspect package configuration and report where background-task output limits are defined. Include file paths and concise evidence.",
   "capability": "inspect",
+  "extensionMode": "isolated",
   "autoDeliver": "never"
 }
 ```
@@ -90,6 +91,8 @@ The child receives a frozen visible-conversation projection, its own session id/
 
 After the completion notification, retrieve the committed answer:
 
+`extensionMode:"isolated"` is the default and disables ambient extension discovery. If the pinned provider is registered only by a user/project extension, use `extensionMode:"ambient"` explicitly. Ambient mode executes arbitrary discovered extension code; the inspect tool allowlist does not sandbox it, so process isolation is weakened. No caller-supplied extension path or route fallback is supported.
+
 ```json
 {
   "taskId": "<task id from bg_delegate>",

package/docs/manifest.json

@@ -13,30 +13,40 @@
       "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:4d3d0ba1534c8ea5368e201fbf8fc7d52f2fbb353262d4af1ead263548547356",
+      "authored_body_sha256": "sha256:72c53dcc104f9b5efa57e38bcb21a4c3c620d5caf1571af82348f94dcafbe941",
+      "covers_sources": [
+        "extensions/anthropic-attribution.ts",
+        "src/core/anthropic-attribution-path.ts",
+        "src/core/anthropic-attribution.ts"
+      ],
+      "doc_id": "subsystems/anthropic-attribution",
+      "rel": "docs/subsystems/anthropic-attribution.md",
+      "required": true,
+      "state": "missing"
+    },
+    {
+      "authored_body_sha256": "sha256:0840d793b8c18869f9a3bb8a72beeb602824ed1a580161f3456126af8af9b459",
       "covers_sources": [
         "src/core/attested-pi-run.ts"
       ],
       "doc_id": "subsystems/attested-pi-runs",
-      "notes": "Reviewed attested Pi event parsing, last-reported stopReason semantics, OAuth route observation, argv/environment safeguards, git authority, hashes, failure handling, and atomic sidecar durability.",
       "rel": "docs/subsystems/attested-pi-runs.md",
       "required": true,
       "reviewer": "gpt-5.5-final-attested-safety-reviewer",
-      "state": "pass"
+      "state": "stale-authored-prose"
     },
     {
       "authored_body_sha256": "sha256:253948c8b1f4dd339b0c1eeabd6e8addf584fe208a0f71c3a7f094921ff4547f",
@@ -52,20 +62,19 @@
       "state": "stale-authored-prose"
     },
     {
-      "authored_body_sha256": "sha256:d5a27cd6a1f78820fe6a39996f8c64c5924efaf2dba99ea44415c1e770dc45bb",
+      "authored_body_sha256": "sha256:40ee5dac92b9e873d6a9f71a59c03ff1ccd44d6717a13d3be18f74b19e68326e",
       "covers_sources": [
         "src/core/durable-fs.ts",
         "src/core/pi-launch.ts"
       ],
       "doc_id": "subsystems/child-launch-durability-and-safety",
-      "notes": "Reviewed durable file replacement and child launch sources, including file fsync, POSIX directory sync, Windows limitation, ordinary versus attested output wording, and loud launch/durability failures.",
       "rel": "docs/subsystems/child-launch-durability-and-safety.md",
       "required": true,
       "reviewer": "gpt-5.5-final-attested-safety-reviewer",
-      "state": "pass"
+      "state": "stale-authored-prose"
     },
     {
-      "authored_body_sha256": "sha256:60b6235d33b9c7df1b1494c0c071862aee059074ce58058c103f9a71d5d9e7d8",
+      "authored_body_sha256": "sha256:67fbb232e66bf0b9f4c1a81b54ec5476c0aae929ed0f0777d57601afcac8e08b",
       "covers_sources": [
         "extensions/delegate-child.ts",
         "src/core/delegate/artifacts.ts",
@@ -87,10 +96,9 @@
       "state": "stale-authored-prose"
     },
     {
-      "authored_body_sha256": "sha256:e7cbe5b10fd56a28e6d23511db5500ee05b000be507fd50ac035d9757e0e2083",
+      "authored_body_sha256": "sha256:b6238bacecf46139dab1d6a8622783db76d913f0ce727205151b65b7cb210481",
       "covers_sources": [
         "extensions/fusion-child.ts",
-        "src/core/fusion/anthropic-attribution.ts",
         "src/core/fusion/artifacts.ts",
         "src/core/fusion/budget.ts",
         "src/core/fusion/child-protocol.ts",
@@ -198,6 +206,17 @@
       "review_policy": "contract",
       "stability": "stable"
     },
+    "commands/claude-cache": {
+      "audience": "user",
+      "covers_sources": [],
+      "covers_surfaces": [
+        "command:claude-cache"
+      ],
+      "mode": "mixed",
+      "rel": "docs/commands/claude-cache.md",
+      "review_policy": "contract",
+      "stability": "evolving"
+    },
     "commands/fusion": {
       "audience": "user",
       "covers_sources": [],
@@ -364,6 +383,19 @@
       "review_policy": "contract",
       "stability": "stable"
     },
+    "subsystems/anthropic-attribution": {
+      "audience": "maintainer",
+      "covers_sources": [
+        "extensions/anthropic-attribution.ts",
+        "src/core/anthropic-attribution-path.ts",
+        "src/core/anthropic-attribution.ts"
+      ],
+      "covers_surfaces": [],
+      "mode": "authored",
+      "rel": "docs/subsystems/anthropic-attribution.md",
+      "review_policy": "behavioral",
+      "stability": "evolving"
+    },
     "subsystems/attested-pi-runs": {
       "audience": "maintainer",
       "covers_sources": [
@@ -435,7 +467,6 @@
       "audience": "maintainer",
       "covers_sources": [
         "extensions/fusion-child.ts",
-        "src/core/fusion/anthropic-attribution.ts",
         "src/core/fusion/artifacts.ts",
         "src/core/fusion/budget.ts",
         "src/core/fusion/child-protocol.ts",
@@ -624,6 +655,12 @@
       "name": "command-contract-bg-update",
       "rel": "docs/commands/bg-update.md"
     },
+    {
+      "doc_id": "commands/claude-cache",
+      "generator": "scripts/docs/generate.mjs",
+      "name": "command-contract-claude-cache",
+      "rel": "docs/commands/claude-cache.md"
+    },
     {
       "doc_id": "commands/fusion",
       "generator": "scripts/docs/generate.mjs",
@@ -775,7 +812,10 @@
     "engines": {
       "node": ">=22.19.0"
     },
-    "entrypoint": "./extensions/background-tasks.ts",
+    "entrypoints": [
+      "./extensions/anthropic-attribution.ts",
+      "./extensions/background-tasks.ts"
+    ],
     "files": [
       "BACKGROUND-TASKS-INSTRUCTIONS.md",
       "LICENSE",
@@ -783,6 +823,7 @@
       "README.md",
       "TESTING.md",
       "TEST_PLAN.md",
+      "THIRD_PARTY_NOTICES.md",
       "docs/",
       "extensions/",
       "logo.png",
@@ -791,13 +832,14 @@
     "image": "https://raw.githubusercontent.com/ismailsaleekh/pi-background-tasks/main/logo.png",
     "name": "pi-background-tasks",
     "type": "module",
-    "version": "2.1.4"
+    "version": "2.4.0"
   },
   "public_surface_ids": [
     "command:bg",
     "command:bg-clear",
     "command:bg-tasks",
     "command:bg-update",
+    "command:claude-cache",
     "command:fusion",
     "command:fusion-models",
     "command:jobs",
@@ -855,6 +897,13 @@
         "name": "bg-update",
         "source": "src/extension.ts:567"
       },
+      {
+        "description": "Show or set Claude cache retention for this session (short, long, default)",
+        "id": "command:claude-cache",
+        "kind": "command",
+        "name": "claude-cache",
+        "source": "src/core/anthropic-attribution.ts:1928"
+      },
       {
         "description": "Start fixed-purpose Fusion reason in the background and return immediately.",
         "id": "command:fusion",
@@ -950,7 +999,7 @@
     ],
     "tool": [
       {
-        "description": "Launch one background Pi agent seeded with a frozen projection of the current conversation, then return a launch receipt immediately. The child has its own session, a route pinned at launch that is never substituted, and read-only tools. Retrieve its verified answer with bg_result.",
+        "description": "Launch one background Pi agent seeded with a frozen projection of the current conversation, then return a launch receipt immediately. The child has its own session, a route pinned at launch that is never substituted, and read-only tools. Extension discovery is isolated by default; ambient mode supports extension-registered providers but executes arbitrary discovered extension code. Retrieve its verified answer with bg_result.",
         "id": "tool:bg_delegate",
         "kind": "tool",
         "label": "Background Delegate",
@@ -958,7 +1007,9 @@
         "promptGuidelines": [
           "Use bg_delegate when work should continue in the background and the worker needs what you already know: it is seeded with a projection of this conversation.",
           "The prompt is authoritative. State exactly what you want investigated and what the answer should contain.",
-          "The delegate is inspect-only: it can read, search, and list files, but cannot run shell commands, edit or write files, use the network, or delegate further.",
+          "The delegate is inspect-only at the model-visible tool boundary: it can read, search, and list files, but cannot run shell commands, edit or write files, use the network, or delegate further.",
+          "Extension discovery is isolated by default. Use extensionMode:\"ambient\" only when the pinned provider is registered by an ambient user/project extension.",
+          "Ambient mode executes arbitrary discovered extension code in the child process. Tool allowlists do not sandbox extension code, so ambient mode weakens inspect-only process isolation.",
           "Facts that exist only inside omitted tool output are not available to the delegate. Restate such findings in the prompt.",
           "bg_delegate returns immediately. Do not poll; retrieve the answer with bg_result after the terminal notification arrives."
         ],
@@ -974,6 +1025,10 @@
               "description": "Capability profile. Only \"inspect\" (read/search/list, no shell, no writes, no network, no recursion) is supported.",
               "type": "string"
             },
+            "extensionMode": {
+              "description": "Extension discovery: isolated | ambient. Default isolated. Ambient is for extension-registered providers and executes arbitrary discovered extension code, weakening process isolation.",
+              "type": "string"
+            },
             "maxToolCalls": {
               "description": "Maximum tool calls. Default 120.",
               "type": "number"
@@ -1028,7 +1083,7 @@
           ],
           "type": "object"
         },
-        "source": "src/delegate-extension.ts:307"
+        "source": "src/delegate-extension.ts:340"
       },
       {
         "description": "Stop a running background task by ID. Fails loudly if the task is unknown or already finished.",
@@ -1116,7 +1171,7 @@
           ],
           "type": "object"
         },
-        "source": "src/delegate-extension.ts:468"
+        "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.",
@@ -1608,6 +1663,9 @@
   },
   "schema_version": "pi-background-tasks.docs-manifest.v2",
   "source_to_docs": {
+    "extensions/anthropic-attribution.ts": [
+      "subsystems/anthropic-attribution"
+    ],
     "extensions/background-tasks.ts": [
       "subsystems/host-ui-and-telemetry"
     ],
@@ -1617,6 +1675,12 @@
     "extensions/fusion-child.ts": [
       "subsystems/fusion"
     ],
+    "src/core/anthropic-attribution-path.ts": [
+      "subsystems/anthropic-attribution"
+    ],
+    "src/core/anthropic-attribution.ts": [
+      "subsystems/anthropic-attribution"
+    ],
     "src/core/attested-pi-run.ts": [
       "subsystems/attested-pi-runs"
     ],
@@ -1665,9 +1729,6 @@
     "src/core/extension-api.ts": [
       "api/eventbus-v1"
     ],
-    "src/core/fusion/anthropic-attribution.ts": [
-      "subsystems/fusion"
-    ],
     "src/core/fusion/artifacts.ts": [
       "subsystems/fusion"
     ],
@@ -1766,6 +1827,9 @@
     "command:bg-update": [
       "commands/bg-update"
     ],
+    "command:claude-cache": [
+      "commands/claude-cache"
+    ],
     "command:fusion": [
       "commands/fusion"
     ],

package/docs/operations/configuration.md

@@ -59,6 +59,20 @@ Bounded logs are for context safety; they point to the full local output file wh
 
 Telemetry wrapping is best-effort and task-owned. Missing telemetry is reported as unavailable, never as zero. Under Windows `cmd`, safe interception is unavailable and the command is left unchanged.
 
+## Global Anthropic attribution and caching
+
+Normal package installation loads the package-owned Anthropic attribution/sanitization extension before the background-task extension. Non-Anthropic sessions are unchanged. Anthropic sessions require Pi's subscription OAuth route; the provider refuses metered Anthropic credentials and reads `userID` plus `oauthAccount.accountUuid` from `~/.claude.json` without writing it.
+
+| Variable/command | Effect |
+|---|---|
+| `PI_CACHE_RETENTION=long` | Default to one-hour Anthropic cache breakpoints where the model supports them. This is the package default when unset. |
+| `PI_CACHE_RETENTION=short` | Default to ordinary ephemeral cache breakpoints without a one-hour TTL. |
+| `PI_CACHE_RETENTION=none` | Do not add default cache breakpoints. Explicit call-level policy remains authoritative. |
+| `/claude-cache status` | Show the effective cache-retention policy for the current session. |
+| `/claude-cache short\|long\|default` | Store or clear a branch-local session override. |
+
+Invalid retention values and malformed persisted overrides fail loudly. The extension also removes only the three reviewed exact-match Pi system-prompt lines rejected by Anthropic; it has no external sanitizer dependency. See [Anthropic attribution](../subsystems/anthropic-attribution.md) and [`/claude-cache`](../commands/claude-cache.md).
+
 ## Fusion model configuration
 
 Fusion model slots are stored globally under the Pi agent directory as:
@@ -77,7 +91,7 @@ Use `/fusion-models` in TUI mode to configure five slots:
 
 Missing config means all five slots are `$current`. Config entries are qualified `provider/model` selections or `$current`; malformed config, stale explicit models, unavailable current models, and concurrent selector conflicts fail loudly before child inference.
 
-Fusion accepts frontier-model routes only through Pi Anthropic or Codex subscription OAuth where `ModelRegistry.isUsingOAuth` confirms the route. Metered frontier API-key/base-URL paths are rejected before child creation, and relevant metered environment variables are stripped from Fusion children. Anthropic children additionally use the package-owned Claude Code attribution provider shared with the repo-local `spawn-anthropic-attribution` entrypoint. It reads `userID` and `oauthAccount.accountUuid` from `~/.claude.json` read-only; missing or malformed attribution data fails loudly before Anthropic transport. Its subscription request policy is 200K, so Fusion clamps Anthropic budget capacity to 200K even when Pi's model catalog advertises a larger context.
+Fusion accepts frontier-model routes only through Pi Anthropic or Codex subscription OAuth where `ModelRegistry.isUsingOAuth` confirms the route. Metered frontier API-key/base-URL paths are rejected before child creation, and relevant metered environment variables are stripped from Fusion children. Anthropic children explicitly load the same package-owned global attribution/sanitization extension because Fusion disables ambient extension discovery. Missing or malformed attribution data fails loudly before Anthropic transport. Its subscription request policy is 200K, so Fusion clamps Anthropic budget capacity to 200K even when Pi's model catalog advertises a larger context.
 
 ## Fusion Claude prompt caching
 

package/docs/operations/releasing.md

@@ -34,6 +34,8 @@ npm run test:hook-contract
 npm run smoke
 npm run smoke:large-context
 npm run pack:dry-run
+# With pnpm 11.18.0 on PATH:
+npm run test:pnpm-pack
 npm run docs:verify
 npm run payload:check
 # On a tag ref only: GITHUB_REF_TYPE=tag GITHUB_REF_NAME=v$VERSION npm run release:check-version
@@ -49,11 +51,12 @@ Live evidence (`npx tsx scripts/delegate-live-run.ts`) is release-time and perfo
 
 Use `npm pack --dry-run --json` output as the payload source of truth. Verify at minimum:
 
-- `extensions/background-tasks.ts` is included as the Pi entrypoint;
-- runtime `src/` files needed by the entrypoint are included;
-- `docs/`, `README.md`, `TESTING.md`, `TEST_PLAN.md`, `PUBLISHING.md`, `BACKGROUND-TASKS-INSTRUCTIONS.md`, root `logo.png`, and `LICENSE` are included per current `package.json.files`;
+- `extensions/anthropic-attribution.ts` and `extensions/background-tasks.ts` are included as the ordered Pi entrypoints;
+- runtime `src/` files needed by both entrypoints are included;
+- `docs/`, `README.md`, `TESTING.md`, `TEST_PLAN.md`, `PUBLISHING.md`, `BACKGROUND-TASKS-INSTRUCTIONS.md`, `THIRD_PARTY_NOTICES.md`, root `logo.png`, and `LICENSE` are included per current `package.json.files`;
 - tests, scripts, node_modules, local `.pi/` artifacts, generated evidence not meant for runtime, and nested tarballs are excluded;
 - TypeBox remains a Pi-provided peer and no private/nested runtime TypeBox copy is bundled;
+- production dependencies use registry versions only; no exotic URL/git/file subdependency is shipped;
 - docs/assets/gateway/logo inclusion matches `package.json.files` exactly.
 
 ## Tag certification vs npm publishing

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/read-before-edit.md

@@ -15,9 +15,12 @@ Every production file under `src/**` and `extensions/**` has exactly one primary
 
 | Source | Primary behavioral owner |
 | --- | --- |
+| `extensions/anthropic-attribution.ts` | [subsystems/anthropic-attribution](./subsystems/anthropic-attribution.md) |
 | `extensions/background-tasks.ts` | [subsystems/host-ui-and-telemetry](./subsystems/host-ui-and-telemetry.md) |
 | `extensions/delegate-child.ts` | [subsystems/delegation](./subsystems/delegation.md) |
 | `extensions/fusion-child.ts` | [subsystems/fusion](./subsystems/fusion.md) |
+| `src/core/anthropic-attribution-path.ts` | [subsystems/anthropic-attribution](./subsystems/anthropic-attribution.md) |
+| `src/core/anthropic-attribution.ts` | [subsystems/anthropic-attribution](./subsystems/anthropic-attribution.md) |
 | `src/core/attested-pi-run.ts` | [subsystems/attested-pi-runs](./subsystems/attested-pi-runs.md) |
 | `src/core/common.ts` | [subsystems/background-task-runtime](./subsystems/background-task-runtime.md) |
 | `src/core/context/parent-snapshot.ts` | [concepts/context-projection-and-budgeting](./concepts/context-projection-and-budgeting.md) |
@@ -34,7 +37,6 @@ Every production file under `src/**` and `extensions/**` has exactly one primary
 | `src/core/delegate/types.ts` | [subsystems/delegation](./subsystems/delegation.md) |
 | `src/core/durable-fs.ts` | [subsystems/child-launch-durability-and-safety](./subsystems/child-launch-durability-and-safety.md) |
 | `src/core/extension-api.ts` | [api/eventbus-v1](./api/eventbus-v1.md) |
-| `src/core/fusion/anthropic-attribution.ts` | [subsystems/fusion](./subsystems/fusion.md) |
 | `src/core/fusion/artifacts.ts` | [subsystems/fusion](./subsystems/fusion.md) |
 | `src/core/fusion/budget.ts` | [subsystems/fusion](./subsystems/fusion.md) |
 | `src/core/fusion/child-protocol.ts` | [subsystems/fusion](./subsystems/fusion.md) |
@@ -70,6 +72,7 @@ Every production file under `src/**` and `extensions/**` has exactly one primary
 - `command:bg-clear`
 - `command:bg-tasks`
 - `command:bg-update`
+- `command:claude-cache`
 - `command:fusion`
 - `command:fusion-models`
 - `command:jobs`

package/docs/reference/runtime-contracts.md

@@ -26,43 +26,43 @@ This generated registry lists production environment-variable references, runtim
 | `AZURE_OPENAI_DEPLOYMENT_NAME_MAP` | remove | `src/core/fusion/pi-child.ts:98` |
 | `AZURE_OPENAI_ENDPOINT` | remove | `src/core/fusion/pi-child.ts:98` |
 | `AZURE_OPENAI_RESOURCE_NAME` | remove | `src/core/fusion/pi-child.ts:98` |
-| `ComSpec` | read | `src/core/common.ts:725`<br>`src/core/common.ts:736` |
+| `ComSpec` | read | `src/core/common.ts:726`<br>`src/core/common.ts:737` |
 | `OPENAI_API_KEY` | remove | `src/core/attested-pi-run.ts:135`<br>`src/core/fusion/pi-child.ts:98` |
 | `OPENAI_BASE_URL` | remove | `src/core/attested-pi-run.ts:135`<br>`src/core/fusion/pi-child.ts:98` |
 | `OPENROUTER_API_KEY` | remove | `src/core/attested-pi-run.ts:135`<br>`src/core/fusion/pi-child.ts:98` |
 | `OPENROUTER_BASE_URL` | remove | `src/core/attested-pi-run.ts:135`<br>`src/core/fusion/pi-child.ts:98` |
-| `path` | read | `src/core/common.ts:680` |
-| `Path` | read | `src/core/common.ts:680` |
-| `PATH` | read | `src/core/common.ts:680` |
+| `path` | read | `src/core/common.ts:681` |
+| `Path` | read | `src/core/common.ts:681` |
+| `PATH` | read | `src/core/common.ts:681` |
 | `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:324`<br>`src/delegate-child-extension.ts:276` |
-| `PI_BG_DELEGATE_LAUNCH_NONCE` | read, write | `src/core/delegate/launch.ts:328`<br>`src/delegate-child-extension.ts:280` |
-| `PI_BG_DELEGATE_SEED_PATH` | read, write | `src/core/delegate/launch.ts:325`<br>`src/delegate-child-extension.ts:277` |
-| `PI_BG_DELEGATE_SEED_SHA256` | read, write | `src/core/delegate/launch.ts:326`<br>`src/delegate-child-extension.ts:278` |
-| `PI_BG_DELEGATE_TASK_ID` | read, write | `src/core/delegate/launch.ts:327`<br>`src/delegate-child-extension.ts:279` |
-| `PI_BG_DISABLE_PI_TELEMETRY` | read | `src/core/registry.ts:194` |
+| `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:68` |
+| `PI_BG_MAX_OUTPUT_BYTES` | read | `src/core/registry.ts:69` |
 | `PI_BG_REGISTRY_URL` | read | `src/extension.ts:464` |
-| `PI_BG_SHELL` | read | `src/core/common.ts:721` |
-| `PI_BG_SHELL_PATH` | read | `src/core/common.ts:722` |
-| `PI_CACHE_RETENTION` | read, write | `src/core/fusion/anthropic-attribution.ts:577`<br>`src/core/fusion/claude-cache.ts:57`<br>`src/core/fusion/pi-child.ts:271`<br>`src/core/fusion/pi-child.ts:272` |
-| `PI_FUSION_CANDIDATE_OUTPUT_RECOVERY_PATH` | read, remove, write | `src/core/fusion/pi-child.ts:1989`<br>`src/core/fusion/pi-child.ts:98`<br>`src/fusion-child-extension.ts:599` |
-| `PI_FUSION_RESEARCH_ENABLED` | read, remove, write | `src/core/fusion/pi-child.ts:2012`<br>`src/core/fusion/pi-child.ts:98`<br>`src/fusion-child-extension.ts:608` |
-| `PI_FUSION_SOURCE_POLICY_PATH` | read, remove, write | `src/core/fusion/pi-child.ts:2013`<br>`src/core/fusion/pi-child.ts:98`<br>`src/fusion-child-extension.ts:555` |
-| `PI_FUSION_SOURCE_POLICY_SHA256` | read, remove, write | `src/core/fusion/pi-child.ts:2014`<br>`src/core/fusion/pi-child.ts:98`<br>`src/fusion-child-extension.ts:556` |
-| `PI_FUSION_TOOL_CALL_LOG_PATH` | read, remove, write | `src/core/fusion/pi-child.ts:2001`<br>`src/core/fusion/pi-child.ts:98`<br>`src/fusion-child-extension.ts:598` |
-| `PI_MODEL` | remove | `src/core/delegate/launch.ts:301`<br>`src/core/fusion/pi-child.ts:98` |
+| `PI_BG_SHELL` | read | `src/core/common.ts:722` |
+| `PI_BG_SHELL_PATH` | read | `src/core/common.ts:723` |
+| `PI_CACHE_RETENTION` | read, write | `src/core/anthropic-attribution.ts:587`<br>`src/core/fusion/claude-cache.ts:57`<br>`src/core/fusion/pi-child.ts:271`<br>`src/core/fusion/pi-child.ts:272` |
+| `PI_FUSION_CANDIDATE_OUTPUT_RECOVERY_PATH` | read, remove, write | `src/core/fusion/pi-child.ts:1872`<br>`src/core/fusion/pi-child.ts:98`<br>`src/fusion-child-extension.ts:599` |
+| `PI_FUSION_RESEARCH_ENABLED` | read, remove, write | `src/core/fusion/pi-child.ts:1895`<br>`src/core/fusion/pi-child.ts:98`<br>`src/fusion-child-extension.ts:608` |
+| `PI_FUSION_SOURCE_POLICY_PATH` | read, remove, write | `src/core/fusion/pi-child.ts:1896`<br>`src/core/fusion/pi-child.ts:98`<br>`src/fusion-child-extension.ts:555` |
+| `PI_FUSION_SOURCE_POLICY_SHA256` | read, remove, write | `src/core/fusion/pi-child.ts:1897`<br>`src/core/fusion/pi-child.ts:98`<br>`src/fusion-child-extension.ts:556` |
+| `PI_FUSION_TOOL_CALL_LOG_PATH` | read, remove, write | `src/core/fusion/pi-child.ts:1884`<br>`src/core/fusion/pi-child.ts:98`<br>`src/fusion-child-extension.ts:598` |
+| `PI_MODEL` | remove | `src/core/delegate/launch.ts:330`<br>`src/core/fusion/pi-child.ts:98` |
 | `PI_OFFLINE` | read | `src/extension.ts:456` |
-| `PI_PROVIDER` | remove | `src/core/delegate/launch.ts:301`<br>`src/core/fusion/pi-child.ts:98` |
-| `PI_REASONING_LEVEL` | remove | `src/core/delegate/launch.ts:301`<br>`src/core/fusion/pi-child.ts:98` |
-| `PI_SESSION_FILE` | remove | `src/core/delegate/launch.ts:301`<br>`src/core/fusion/pi-child.ts:98` |
-| `PI_SESSION_ID` | remove | `src/core/delegate/launch.ts:301`<br>`src/core/fusion/pi-child.ts:98` |
-| `PI_SKIP_VERSION_CHECK` | write | `src/core/delegate/launch.ts:323`<br>`src/core/fusion/pi-child.ts:270` |
-| `PIPELINE_ANTHROPIC_ATTRIBUTION_AUDIT_PATH` | read | `src/core/fusion/anthropic-attribution.ts:1003` |
-| `SHELL` | read | `src/core/common.ts:717` |
+| `PI_PROVIDER` | remove | `src/core/delegate/launch.ts:330`<br>`src/core/fusion/pi-child.ts:98` |
+| `PI_REASONING_LEVEL` | remove | `src/core/delegate/launch.ts:330`<br>`src/core/fusion/pi-child.ts:98` |
+| `PI_SESSION_FILE` | remove | `src/core/delegate/launch.ts:330`<br>`src/core/fusion/pi-child.ts:98` |
+| `PI_SESSION_ID` | remove | `src/core/delegate/launch.ts:330`<br>`src/core/fusion/pi-child.ts:98` |
+| `PI_SKIP_VERSION_CHECK` | write | `src/core/delegate/launch.ts:352`<br>`src/core/fusion/pi-child.ts:270` |
+| `PIPELINE_ANTHROPIC_ATTRIBUTION_AUDIT_PATH` | read | `src/core/anthropic-attribution.ts:1013` |
+| `SHELL` | read | `src/core/common.ts:718` |
 | `SystemRoot` | read | `src/core/windows-taskkill.ts:96` |
 | `WINDIR` | read | `src/core/windows-taskkill.ts:101` |
 
@@ -71,20 +71,18 @@ 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:42` |
-| delegate-artifact | `child-prompt.txt` | `src/core/delegate/artifacts.ts:46` |
-| delegate-artifact | `child.stderr.txt` | `src/core/delegate/artifacts.ts:47` |
-| delegate-artifact | `child.stdout.txt` | `src/core/delegate/artifacts.ts:48` |
-| delegate-artifact | `context-omission-ledger.json` | `src/core/delegate/artifacts.ts:41` |
-| delegate-artifact | `error.json` | `src/core/delegate/artifacts.ts:49` |
-| delegate-artifact | `manifest.json` | `src/core/delegate/artifacts.ts:43` |
-| delegate-artifact | `outcome.json` | `src/core/delegate/artifacts.ts:44` |
+| delegate-artifact | `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: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:40` |
-| delegate-artifact | `spill/<receipt-named-file>` | `src/core/delegate/artifacts.ts:53` |
-| directory | `.pi/delegate/<session-id>-<pid>/<task-id>/` | `src/core/delegate/artifacts.ts:157` |
+| 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` |
-| directory | `.pi/tasks/<session-id>-<pid>/` | `src/core/registry.ts:783` |
+| directory | `.pi/tasks/<session-id>-<pid>/` | `src/core/registry.ts:784` |
 | fusion-artifact | `<attempt-prefix> = candidate-<slot>.attempt-<n> \| evaluation.attempt-<n> \| merge.attempt-<n>` | `src/core/fusion/artifacts.ts:248` |
 | fusion-artifact | `<attempt-prefix>.calibration-violation.json` | `src/core/fusion/artifacts.ts:263` |
 | fusion-artifact | `<attempt-prefix>.events.jsonl` | `src/core/fusion/artifacts.ts:804` |
@@ -104,29 +102,31 @@ This generated registry lists production environment-variable references, runtim
 | fusion-artifact | `merged.md` | `src/core/fusion/artifacts.ts:387` |
 | fusion-artifact | `result.json` | `src/core/fusion/artifacts.ts:647` |
 | fusion-artifact | `source-policy.private.json` | `src/core/fusion/artifacts.ts:690` |
-| task-file | `.pi/tasks/<session-id>-<pid>/<task-id>.attestation.json` | `src/core/attested-pi-run.ts:583` |
-| task-file | `.pi/tasks/<session-id>-<pid>/<task-id>.json` | `src/core/registry.ts:811` |
-| task-file | `.pi/tasks/<session-id>-<pid>/<task-id>.output` | `src/core/registry.ts:810` |
-| task-file | `.pi/tasks/<session-id>-<pid>/<task-id>.pi-events.jsonl` | `src/core/attested-pi-run.ts:580` |
-| task-file | `.pi/tasks/<session-id>-<pid>/<task-id>.pi-telemetry-wrapper.cjs` | `src/core/attested-pi-run.ts:582` |
-| task-file | `.pi/tasks/<session-id>-<pid>/<task-id>.stderr` | `src/core/attested-pi-run.ts:581` |
+| task-file | `.pi/tasks/<session-id>-<pid>/<task-id>.attestation.json` | `src/core/attested-pi-run.ts:592` |
+| task-file | `.pi/tasks/<session-id>-<pid>/<task-id>.json` | `src/core/registry.ts:812` |
+| task-file | `.pi/tasks/<session-id>-<pid>/<task-id>.output` | `src/core/registry.ts:811` |
+| task-file | `.pi/tasks/<session-id>-<pid>/<task-id>.pi-events.jsonl` | `src/core/attested-pi-run.ts:589` |
+| task-file | `.pi/tasks/<session-id>-<pid>/<task-id>.pi-telemetry-wrapper.cjs` | `src/core/attested-pi-run.ts:591` |
+| task-file | `.pi/tasks/<session-id>-<pid>/<task-id>.stderr` | `src/core/attested-pi-run.ts:590` |
 
 ### Schema identifiers
 
 | Schema | Provenance |
 | --- | --- |
 | `phase2.pi_task_attestation.v1` | `src/core/attested-pi-run.ts:20` |
-| `pi-background-tasks.delegate-budget-plan.v2` | `src/core/delegate/types.ts:21` |
-| `pi-background-tasks.delegate-child-terminal.v1` | `src/delegate-child-extension.ts:380` |
+| `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:413` |
+| `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.v1` | `src/core/delegate/types.ts:22` |
-| `pi-background-tasks.delegate-outcome.v1` | `src/core/delegate/runner.ts:200` |
+| `pi-background-tasks.delegate-manifest.v2` | `src/core/delegate/types.ts:22` |
+| `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:683` |
+| `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-seed.v1` | `src/core/delegate/types.ts:15` |
+| `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:723` |
+| `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` |