pi-background-tasks 1.0.4 → 1.0.7

package/docs/subsystems/fusion.md

@@ -5,8 +5,9 @@ mode: mixed
 review_policy: behavioral
 stability: stable
 covers_surfaces: [renderer:fusion-result, workflow:investigate, workflow:reason, workflow:research, workflow:validate]
-covers_sources: [extensions/fusion-child.ts, src/core/fusion/artifacts.ts, src/core/fusion/budget.ts, src/core/fusion/child-protocol.ts, src/core/fusion/clean-context.ts, src/core/fusion/config.ts, src/core/fusion/context.ts, src/core/fusion/evaluation.ts, src/core/fusion/orchestrator.ts, src/core/fusion/pi-child.ts, src/core/fusion/prompts.ts, src/core/fusion/source-policy.ts, src/core/fusion/types.ts, src/core/fusion/web-fetch.ts, src/core/fusion/workflows.ts, src/fusion-child-extension.ts, src/fusion-extension.ts, src/ui/fusion-model-selector.ts]
+covers_sources: [extensions/fusion-child.ts, src/core/fusion/artifacts.ts, src/core/fusion/budget.ts, src/core/fusion/child-protocol.ts, src/core/fusion/claude-cache.ts, src/core/fusion/clean-context.ts, src/core/fusion/config.ts, src/core/fusion/context.ts, src/core/fusion/evaluation.ts, src/core/fusion/orchestrator.ts, src/core/fusion/pi-child.ts, src/core/fusion/prompts.ts, src/core/fusion/source-policy.ts, src/core/fusion/types.ts, src/core/fusion/web-fetch.ts, src/core/fusion/workflows.ts, src/fusion-child-extension.ts, src/fusion-extension.ts, src/ui/fusion-model-selector.ts]
 ---
+
 # Fusion subsystem
 
 <!-- pi-docs:begin name="fusion-workflows" generator="scripts/docs/generate.mjs" -->
@@ -60,18 +61,18 @@ Do not describe Fusion as unconditionally exactly five model calls. A completed
 
 Candidate tool policies are fixed by workflow:
 
-| Workflow | Candidate capability | Candidate tools |
-|---|---:|---|
-| reason | `reason` | none (`--no-tools`) |
-| investigate | `inspect` | `read`, `grep`, `find`, `ls` |
-| research | `research` | `read`, `grep`, `find`, `ls`, `fusion_web_fetch` |
-| validate | `inspect` | `read`, `grep`, `find`, `ls` |
+| Workflow    | Candidate capability | Candidate tools                                  |
+| ----------- | -------------------: | ------------------------------------------------ |
+| reason      |             `reason` | none (`--no-tools`)                              |
+| investigate |            `inspect` | `read`, `grep`, `find`, `ls`                     |
+| research    |           `research` | `read`, `grep`, `find`, `ls`, `fusion_web_fetch` |
+| validate    |            `inspect` | `read`, `grep`, `find`, `ls`                     |
 
 Evaluator, evaluator-repair, and merger always use capability `reason` and empty tool lists. Tool-enabled children run with built-in tools disabled and an explicit allowlist plus a denylist that includes shell/write/edit, Fusion recursion, and background/delegate tools.
 
 ## Validation specifics
 
-`fusion_validate` enforces a strict public verification contract: `provided` requires non-empty evidence and no reason; `not_run` requires a reason and empty/omitted evidence. Reviewers return closed candidate-report JSON. The host assigns stable finding ids after anonymization, the evaluator must account for every source finding exactly once, and the host renders the final report from validated accounting after the merger. Validation is advisory and read-only: it never edits files, runs tests, gates a release, or replaces builds, linters, scanners, or human review.
+`fusion_validate` enforces a strict public verification contract: `provided` requires non-empty evidence and no reason; `not_run` requires a reason and empty/omitted evidence. Reviewers return exactly one bare, closed candidate-report JSON object. The host keeps its shared JSON parser strict; a single complete `json` fence can be removed only by the validation-specific audited recovery path, which writes a contract-event artifact and surfaces a limitation. One irrecoverable minority report is also recorded and surfaced as a limitation, while two invalid reports fail the workflow. The host assigns stable finding ids after anonymization, the evaluator must account for every source finding exactly once, and the host renders the final report from validated accounting after the merger. Validation is advisory and read-only: it never edits files, runs tests, gates a release, or replaces builds, linters, scanners, or human review.
 
 ## Research specifics
 
@@ -81,21 +82,23 @@ Research is targeted fetch, not search. The public caller declares exact non-dup
 
 Research intentionally combines read-only file tools and network fetch in one child. This supports source-backed synthesis but is security-sensitive: operators must not supply secret-bearing URLs or ask children to put private data in URL strings. The package blocks common SSRF targets and credential URLs, but its deny rules are not an exhaustive network sandbox; fetched content remains untrusted and caller-declared public URLs can still disclose access through remote logs/timing.
 
-Inspect/research candidates write sealed tool-call audit logs. The log contains schema version, ordinal, tool name, argument/result byte counts and SHA-256 digests, status, duration, and fetch provenance. Raw arguments, raw results, page content, and rejected raw URLs are not persisted. The parent requires the log and seal, verifies hashes/counts/ordinals/status, enforces the 8 MiB aggregate result-byte cap, and rejects non-allowlisted tools.
+Inspect/research candidates write sealed tool-call audit logs. The log contains schema version, ordinal, tool name, argument/result byte counts and SHA-256 digests, status, duration, and fetch provenance. Raw arguments, raw results, page content, and rejected raw URLs are not persisted. The parent requires the log and seal, verifies hashes/counts/ordinals/status, enforces the 8 MiB aggregate result-byte cap, and rejects non-allowlisted tools. A child may attempt at most 192 tool calls; crossing that limit aborts the run, emits structured refusal evidence, and prevents a complete audit seal.
 
 ## Child process isolation
 
-Fusion never calls direct completion APIs. It launches direct child `pi --mode text` processes and writes the prompt over stdin. Child argv includes `--no-session`, `--no-extensions`, `--no-skills`, `--no-prompt-templates`, `--no-themes`, and `--no-context-files`; explicit extensions still load, so the package-owned compact metadata extension is always supplied. Anthropic children additionally receive the `@ravshansbox/pi-anthropic-sps` sanitizer extension because discovery is disabled and Claude routes need Pi system-prompt sanitization.
+Fusion never calls direct completion APIs. It launches direct child `pi --mode text` processes and writes the prompt over stdin. Child argv includes `--no-session`, `--no-extensions`, `--no-skills`, `--no-prompt-templates`, `--no-themes`, and `--no-context-files`; explicit extensions still load, so the package-owned compact metadata extension is always supplied. Anthropic children additionally receive the `@ravshansbox/pi-anthropic-sps` sanitizer extension because discovery is disabled and Claude routes need Pi system-prompt sanitization. That dependency only sanitizes rejected system-prompt lines and preserves existing cache fields; it does not choose Fusion's cache policy.
+
+Child text mode writes the final full answer to stdout. The private child extension emits compact reasoning-free metadata frames to stderr for finalized assistant messages: provider/model, stop reason, text block byte counts and hashes, aggregate text hash, the complete Pi `Usage` object, and a closed cache-policy observation. It also governs every final `before_provider_request` payload after earlier extensions have transformed it. Claude's sanitizer therefore loads before the package governor. For Anthropic routes, the package normalizes only cache breakpoints already selected by Pi's adapter: default retention is `long` (`ttl: "1h"`), while inherited `PI_CACHE_RETENTION=short|none|long` explicitly selects the policy. Long retention falls back to short when model compatibility rejects it. Existing no-marker payloads remain unmarked so Pi's call-level `cacheRetention="none"` compaction requests are never overridden. Malformed controls, invalid policy values, or more than four breakpoints abort before transport. Non-Anthropic payloads remain byte-equivalent apart from the governor's existing JSON normalization.
 
-Child text mode writes the final full answer to stdout. The private child extension emits compact reasoning-free metadata frames to stderr for finalized assistant messages: provider/model, stop reason, text block byte counts and hashes, aggregate text hash, and the complete Pi `Usage` object. The parent reconstructs and validates stdout against the final metadata, requires final stop reason `stop` and non-final stop reason `toolUse`, verifies model identity, and preserves usage/cost exactly.
+After cache normalization, the governor serializes and hashes the exact payload, applies the shared conservative estimator, reserves the model's declared maximum output plus 4,096 safety tokens, and aborts before transport if the payload cannot fit or if the child exceeds 128 provider requests. Pi's provider-hook behavior is characterized through the same `openai-codex-responses` transport adapter used by subscription Codex routes in a real local HTTP agent loop: transforms chain in extension load order and `ctx.abort()` prevents network transport. Cache observations use `pi-background-tasks.fusion-claude-cache-observation.v1`, state requested/effective retention, source, breakpoint count, and provider-request ordinal, and are hash-bound inside `pi-background-tasks.fusion-child-result.v3` attempt event artifacts. At terminal `agent_settled`, the extension emits exactly one `pi-background-tasks.fusion-child-settlement.v2` frame binding the complete ordered metadata stream by count and SHA-256, the final record/hash, and any recovered retry-marker ordinals. The parent validates closed cache evidence and increasing request ordinals, reconstructs stdout against the final metadata, requires final stop reason `stop`, verifies model identity, and preserves usage/cost exactly. Non-final `toolUse` records remain normal. A non-final `error` is accepted only when it is a zero-content, empty-hash, zero-usage retry marker, a later final `stop` exists, and the terminal settlement hash/accounts for that exact ordinal. `length`, `aborted`, `pending`, final `error`, error records carrying text or usage, missing/duplicate/tampered settlement, and settlement before terminal idleness all fail loudly.
 
 Fusion child environments strip session/model/provider variables plus metered credential/base-url variables for OpenRouter, OpenAI, Anthropic, Azure OpenAI, and generic Pi API credentials before launch. Frontier model routes are admitted only when the registry reports subscription OAuth for trusted `anthropic` or `openai-codex` endpoints. There is no fallback, model substitution, endpoint override, or metered API-key route.
 
 ## Budgets and output contracts
 
-Budget planning is per route and per stage. Every configured candidate, evaluator, and merger route must have a usable context window. The affine estimator from the shared token-budget layer accounts for byte classes plus a 512-token intercept; backed model-family calibrations are used only where applicable, unknown/unbacked providers are reported in artifacts/result details, and multibyte/dense ASCII diagnostics are preserved.
+Budget planning is per route and per stage. Every configured candidate, evaluator, and merger route must have a usable context window. The affine estimator from the shared token-budget layer accounts for byte classes plus a 512-token intercept; backed model-family calibrations are used only where applicable, unknown/unbacked providers are reported in artifacts/result details, and multibyte/dense ASCII diagnostics are preserved. Post-run calibration compares that one-request forecast only with the first provider request; cumulative agent-loop and cache usage is retained as total usage but is never misclassified as a prompt under-forecast.
 
-`budget-plan.json` records route capacities, stage forecasts for candidate/evaluation/evaluation-repair/merge, conditional repair reservation, warnings, blockers, empty-request counterfactuals, and remediation. Fatal preflight blockers launch zero children. High utilization or worst-case reservation pressure is a warning when input still fits. Exact rendered prompt checks happen again immediately before candidate, evaluation, repair, and merge launches.
+`budget-plan.json` uses `pi-background-tasks.fusion-budget-plan.v4` and records route capacities, stage forecasts for candidate/evaluation/evaluation-repair/merge, conditional repair reservation, warnings, blockers, empty-request counterfactuals, and remediation. Each route reserves the larger of Fusion's 32,768-token output contract reserve and the resolved model's declared maximum output; a model advertising a 128,000-token maximum therefore receives the full 128,000-token reserve. Fatal preflight blockers launch zero children. High utilization or worst-case reservation pressure is a warning when input still fits. Exact rendered prompt checks happen again immediately before candidate, evaluation, repair, and merge launches.
 
 Output contracts are checked after durable attempt recording: candidate responses up to 48 KiB JSON-rendered bytes, evaluator up to 64 KiB, merger/final report up to 64 KiB, diagnostics contract 8 KiB, child stdout cap 32 MiB, child stderr cap 4 MiB. Oversized child output fails loudly and preserves evidence; Fusion never clips or silently forwards truncated content.
 
@@ -105,7 +108,7 @@ Run artifacts are private local evidence under `.pi/fusion/<session-id>-<pid>/<r
 
 Artifact writes use durable private temp-file/fsync/rename. Manifests enforce legal state transitions and record config, resolved models, fixed capabilities, context policy, tool policy, anonymous map, attempts, artifact refs, cumulative usage, and errors. Successful, failed, and cancelled observed attempts preserve complete Pi usage/cost components; public tool results clone the same `Usage` shape.
 
-For tool-enabled children, the private audit journal remains open across every low-level `agent_end`, because Pi may still retry, compact and retry, or process a queued continuation. Only terminal `agent_settled` can exclusively publish the complete hash/count/byte seal. Tool activity after finalization, duplicate settlement, pre-settlement shutdown, extension diagnostics, and missing/failed/stale seals are fatal. This lifecycle requires Pi 0.81.1 or newer; older Pi lines do not expose the required terminal event and are not claimed as compatible.
+For tool-enabled children, the private audit journal remains open across every low-level `agent_end`, because Pi may still retry, compact and retry, or process a queued continuation. Only terminal `agent_settled` can exclusively publish the complete hash/count/byte seal. Runtime-guard refusal latches process failure, makes that seal incomplete, and forces the result settlement to failed. The child emits one closed `pi-background-tasks.fusion-runtime-guard.v1` stderr frame containing the refusal code, route capacities, request/tool ordinals, exact payload byte count and SHA-256, conservative token estimate, and a bounded message; it never emits the payload itself. The parent validates this frame and reports typed `child_runtime_budget_exceeded` for runtime capacity/loop refusals or `child_cache_policy_invalid` for Claude cache-policy refusal, instead of accepting a later clean-looking result or reducing it to an unexplained exit code. Tool activity after finalization, duplicate settlement, pre-settlement shutdown, extension diagnostics, malformed/duplicate runtime-guard frames, and missing/failed/stale seals are fatal. This lifecycle requires Pi 0.81.1 or newer; older Pi lines do not expose the required terminal event and are not claimed as compatible.
 
 Cancellation and shutdown are loud and durable when a run store exists. The extension tracks active runs, links external abort signals, aborts on session shutdown/reload, and waits for settlement. Child processes have a 30 minute wall timeout, 20 minute idle watchdog, SIGTERM grace, SIGKILL wait, process-group kill on POSIX, bounded stdout/stderr, and cleanup-error propagation.
 
@@ -116,6 +119,8 @@ Cancellation and shutdown are loud and durable when a run store exists. The exte
 - Frontier/API route rejected: use Pi Anthropic or Codex subscription OAuth, not OpenAI/OpenRouter/Azure/API-key routes.
 - `prompt_budget_exceeded_forecast`: inspect `budget-plan.json`; the error says whether shortening the request can help or whether session history/scope/model context window is the blocker.
 - `prompt_budget_exceeded_measured`: an exact rendered prompt exceeded capacity after upstream output was known; split the workflow or choose a larger-context subscription route.
+- `child_runtime_budget_exceeded`: a later provider payload, provider-request loop, or tool-call loop crossed a child runtime guard after launch. Inspect the attempt stderr guard frame and failed tool seal; narrow the task or select a subscription route with more safe input headroom. Do not ignore intermediate provider errors or weaken the guard.
+- `child_cache_policy_invalid`: `PI_CACHE_RETENTION` or Claude cache-control evidence was malformed. Use exactly `none`, `short`, or `long`; do not remove the final-payload guard.
 - `evaluation schema repair failed`: both evaluator attempts failed the closed JSON contract; inspect `evaluation.attempt-*.response.txt` and errors.
 - `tool-call log invalid`: inspect the candidate `*.tool-calls.jsonl` and `*.seal.json`; missing/partial/unsealed logs, non-allowlisted tools, hash/count mismatches, and over-budget tool output fail by design.
 - Research fetch failures are typed and do not retry via other URLs or extraction modes; verify the declared URL is public, reachable, supported content, and within caps.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-background-tasks",
-  "version": "1.0.4",
+  "version": "1.0.7",
   "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",
@@ -68,6 +68,7 @@
     "test:hook-contract": "tsx --test --test-concurrency=1 tests/scripted-provider/pi-hook-contract.test.ts",
     "docs:generate": "node scripts/docs/generate.mjs",
     "docs:verify": "node scripts/docs/verify.mjs",
+    "docs:verify:attestations": "node scripts/docs/verify.mjs --require-attestations",
     "docs:attest/record": "node scripts/docs/attest.mjs",
     "docs:attest": "npm run docs:attest/record",
     "test:docs": "tsx --test tests/unit/docs-gate.test.ts tests/package/docs-contract.test.ts",

package/src/core/fusion/artifacts.ts

@@ -7,6 +7,7 @@ import { replaceFileDurable } from '../durable-fs.js';
 import {
   EMPTY_FUSION_USAGE,
   FUSION_MANIFEST_SCHEMA_VERSION,
+  FUSION_VALIDATE_CANDIDATE_CONTRACT_EVENT_SCHEMA_VERSION,
   FusionError,
   cloneFusionUsage,
   type FusionArtifactManifest,
@@ -83,14 +84,39 @@ export interface CreateFusionArtifactStoreOptions {
 
 export interface RecordFusionChildAttemptInput {
   result: FusionChildRunResult;
+  systemPrompt: string;
   prompt: string;
   responseKind: 'md' | 'txt';
 }
 
+export type RecordValidationCandidateContractEventInput =
+  | {
+      candidateId: FusionCandidateId;
+      slot: 1 | 2 | 3;
+      status: 'normalized';
+      detail: {
+        normalization: 'markdown_json_fence' | 'prose_then_markdown_json_fence';
+        original_sha256: string;
+        forwarded_sha256: string;
+        warning: string;
+      };
+    }
+  | {
+      candidateId: FusionCandidateId;
+      slot: 1 | 2 | 3;
+      status: 'dropped';
+      detail: {
+        response_sha256: string;
+        error: string;
+        warning: string;
+      };
+    };
+
 export interface RecordFusionFailedAttemptInput {
   stage: FusionStage;
   slot?: 1 | 2 | 3;
   attempt: number;
+  systemPrompt: string;
   prompt: string;
   events: Buffer;
   partialResponse: Buffer;
@@ -398,6 +424,7 @@ export class FusionArtifactStore {
 
   async recordChildAttempt(input: RecordFusionChildAttemptInput): Promise<void> {
     const prefix = attemptPrefix(input.result.stage, input.result.slot, input.result.attempt);
+    await this.writeArtifact(`${prefix}.system-prompt.txt`, input.systemPrompt);
     const promptRef = await this.writeArtifact(`${prefix}.prompt.txt`, input.prompt);
     const eventsRef = await this.writeArtifact(`${prefix}.events.jsonl`, input.result.events);
     const stderrRef = await this.writeArtifact(`${prefix}.stderr.txt`, input.result.stderr);
@@ -442,8 +469,22 @@ export class FusionArtifactStore {
     return this.writeArtifact(calibrationViolationName(prefix), `${canonicalJson(input.violation)}\n`);
   }
 
+  async recordValidationCandidateContractEvent(
+    input: RecordValidationCandidateContractEventInput,
+  ): Promise<FusionArtifactRef> {
+    const name = `candidate-${String(input.slot)}.output-contract-${input.status}.json`;
+    return this.writeArtifact(name, `${canonicalJson({
+      schema_version: FUSION_VALIDATE_CANDIDATE_CONTRACT_EVENT_SCHEMA_VERSION,
+      ...input.detail,
+      candidate_id: input.candidateId,
+      slot: input.slot,
+      status: input.status,
+    })}\n`);
+  }
+
   async recordFailedAttempt(input: RecordFusionFailedAttemptInput): Promise<void> {
     const prefix = attemptPrefix(input.stage, input.slot, input.attempt);
+    await this.writeArtifact(`${prefix}.system-prompt.txt`, input.systemPrompt);
     const promptRef = await this.writeArtifact(`${prefix}.prompt.txt`, input.prompt);
     const eventsRef = await this.writeArtifact(`${prefix}.events.jsonl`, input.events);
     const stderrRef = await this.writeArtifact(`${prefix}.stderr.txt`, input.stderr);

package/src/core/fusion/budget.ts

@@ -88,7 +88,8 @@ export const FUSION_MIN_CONTEXT_WINDOW_TOKENS =
   FUSION_SAFETY_RESERVE_TOKENS;
 
 export const FUSION_BUDGET_POLICY: FusionBudgetPolicyDescriptor = {
-  id: 'fusion-budget-policy-v3',
+  id: 'fusion-budget-policy-v4',
+  route_output_reserve_strategy: 'max_fusion_contract_or_model_max',
   calibration_version: TOKEN_BUDGET_CALIBRATION_VERSION,
   calibration_table: FUSION_CALIBRATED_BYTES_PER_TOKEN,
   reserved_output_tokens: FUSION_RESERVED_OUTPUT_TOKENS,
@@ -288,14 +289,20 @@ function routeCapacity(
   role: FusionRouteCapacity['role'],
 ): FusionRouteCapacity {
   const contextWindow = requirePositiveContextWindow(model, role);
+  const reservedOutputTokens = Math.max(FUSION_RESERVED_OUTPUT_TOKENS, model.maxOutputTokens);
   const allowed = allowedInputTokens(contextWindow, {
-    reservedOutputTokens: FUSION_RESERVED_OUTPUT_TOKENS,
+    reservedOutputTokens,
     framingReserveTokens: FUSION_FRAMING_RESERVE_TOKENS,
     safetyReserveTokens: FUSION_SAFETY_RESERVE_TOKENS,
   });
   if (allowed < FUSION_MIN_CANONICAL_INPUT_TOKENS) {
+    const minimumContextWindow =
+      reservedOutputTokens +
+      FUSION_FRAMING_RESERVE_TOKENS +
+      FUSION_SAFETY_RESERVE_TOKENS +
+      FUSION_MIN_CANONICAL_INPUT_TOKENS;
     throw new FusionError(
-      `fusion ${role} route ${model.qualifiedId} has a ${String(contextWindow)}-token context window, but Fusion requires at least ${String(FUSION_MIN_CONTEXT_WINDOW_TOKENS)} tokens per configured route: ${String(FUSION_RESERVED_OUTPUT_TOKENS)} output + ${String(FUSION_FRAMING_RESERVE_TOKENS)} framing + ${String(FUSION_SAFETY_RESERVE_TOKENS)} safety + ${String(FUSION_MIN_CANONICAL_INPUT_TOKENS)} usable input. Choose a larger-context model for this slot with /fusion-models.`,
+      `fusion ${role} route ${model.qualifiedId} has a ${String(contextWindow)}-token context window, but Fusion requires at least ${String(minimumContextWindow)} tokens: ${String(reservedOutputTokens)} reserved for the route's configured maximum output + ${String(FUSION_FRAMING_RESERVE_TOKENS)} framing + ${String(FUSION_SAFETY_RESERVE_TOKENS)} safety + ${String(FUSION_MIN_CANONICAL_INPUT_TOKENS)} usable input. Choose a larger-context or lower-max-output subscription model for this slot with /fusion-models.`,
       { code: 'model_capacity_unknown', childCreated: false },
     );
   }
@@ -322,7 +329,7 @@ function routeCapacity(
     model: model.model,
     qualified_id: model.qualifiedId,
     context_window_tokens: contextWindow,
-    reserved_output_tokens: FUSION_RESERVED_OUTPUT_TOKENS,
+    reserved_output_tokens: reservedOutputTokens,
     framing_reserve_tokens: FUSION_FRAMING_RESERVE_TOKENS,
     safety_reserve_tokens: FUSION_SAFETY_RESERVE_TOKENS,
     allowed_input_tokens: allowed,
@@ -1115,7 +1122,13 @@ export class FusionBudget {
     const inputSegments = [knownTextSegment(systemPrompt), knownTextSegment(userPrompt)];
     const promptUtf8Bytes = inputSegments.reduce((sum, segment) => sum + segment.bytes, 0);
     const estimate = estimateRouteInput(route, inputSegments);
-    const billedInput = result.usage.input + result.usage.cacheRead + result.usage.cacheWrite;
+    // The forecast is a one-request admission estimate. Compare it only with
+    // the first provider request, never with aggregate agent-loop/cache usage.
+    // Custom child runners predating this observation field remain compatible,
+    // but cannot produce a calibration verdict without like-for-like evidence.
+    const observedUsage = result.firstRequestUsage;
+    if (observedUsage === undefined) return undefined;
+    const billedInput = observedUsage.input + observedUsage.cacheRead + observedUsage.cacheWrite;
     if (billedInput <= estimate.tokens) return undefined;
     const violation: FusionCalibrationViolation = {
       schema_version: FUSION_CALIBRATION_VIOLATION_SCHEMA_VERSION,
@@ -1130,12 +1143,14 @@ export class FusionBudget {
       rate_source: estimate.rateSource,
       prompt_utf8_bytes: promptUtf8Bytes,
       prompt_sha256: sha256Hex(`${systemPrompt}\u0000${userPrompt}`),
+      observation_scope: 'first_provider_request',
+      provider_request_count: result.providerRequestCount ?? 1,
       forecast_input_tokens: estimate.tokens,
       billed_input_tokens: billedInput,
       billed_input_breakdown: {
-        input: result.usage.input,
-        cache_read: result.usage.cacheRead,
-        cache_write: result.usage.cacheWrite,
+        input: observedUsage.input,
+        cache_read: observedUsage.cacheRead,
+        cache_write: observedUsage.cacheWrite,
       },
       under_forecast_tokens: billedInput - estimate.tokens,
       byte_class_breakdown: estimate.byte_class_breakdown,

package/src/core/fusion/child-protocol.ts

@@ -1,9 +1,13 @@
 import { createHash } from 'node:crypto';
 import type { Usage } from '@earendil-works/pi-ai';
+import type { FusionClaudeCacheObservation } from './claude-cache.js';
 
 export const FUSION_CHILD_RESULT_SCHEMA_VERSION =
-  'pi-background-tasks.fusion-child-result.v2' as const;
+  'pi-background-tasks.fusion-child-result.v3' as const;
 export const FUSION_CHILD_RESULT_PREFIX = '\u001ePI_FUSION_CHILD_RESULT ';
+export const FUSION_CHILD_SETTLEMENT_SCHEMA_VERSION =
+  'pi-background-tasks.fusion-child-settlement.v2' as const;
+export const FUSION_CHILD_SETTLEMENT_PREFIX = '\u001ePI_FUSION_CHILD_SETTLEMENT ';
 export const FUSION_TOOL_CALL_LOG_PATH_ENV = 'PI_FUSION_TOOL_CALL_LOG_PATH';
 export const FUSION_RESEARCH_ENABLED_ENV = 'PI_FUSION_RESEARCH_ENABLED';
 export const FUSION_SOURCE_POLICY_PATH_ENV = 'PI_FUSION_SOURCE_POLICY_PATH';
@@ -11,17 +15,47 @@ export const FUSION_SOURCE_POLICY_SHA256_ENV = 'PI_FUSION_SOURCE_POLICY_SHA256';
 export const FUSION_TOOL_CALL_SEAL_SCHEMA_VERSION =
   'pi-background-tasks.fusion-tool-call-seal.v1' as const;
 export const FUSION_TOOL_CALL_SEAL_SUFFIX = '.seal.json';
+export const FUSION_RUNTIME_GUARD_SCHEMA_VERSION =
+  'pi-background-tasks.fusion-runtime-guard.v1' as const;
+export const FUSION_RUNTIME_GUARD_PREFIX = '\u001ePI_FUSION_RUNTIME_GUARD ';
+export const FUSION_CHILD_MAX_PROVIDER_REQUESTS = 128;
+export const FUSION_CHILD_MAX_TOOL_CALLS = 192;
+export const FUSION_CHILD_MIN_OUTPUT_RESERVE_TOKENS = 32_768;
+export const FUSION_CHILD_SAFETY_RESERVE_TOKENS = 4_096;
 
 /**
  * Aggregate ceiling on tool-result bytes a single candidate child may accumulate.
  *
- * v1 deliberately has no tool-call-count cap, so this byte budget is the only bound on
- * how much a read-only candidate can pull into its context. 8 MiB is generous for
- * targeted grep/read investigation while still preventing an unbounded read loop from
- * degrading into an opaque provider-side context failure.
+ * The byte ceiling complements the runtime provider-payload governor and tool/request
+ * count limits. It remains an independent bound on total tool material even when Pi
+ * compaction keeps each individual provider request within the route context window.
  */
 export const FUSION_CHILD_MAX_TOTAL_TOOL_RESULT_BYTES = 8 * 1024 * 1024;
 
+export type FusionRuntimeGuardCode =
+  | 'provider_request_limit'
+  | 'provider_request_budget'
+  | 'provider_payload_invalid'
+  | 'claude_cache_policy'
+  | 'tool_call_limit';
+
+export interface FusionRuntimeGuardRecord {
+  schema_version: typeof FUSION_RUNTIME_GUARD_SCHEMA_VERSION;
+  code: FusionRuntimeGuardCode;
+  provider: string;
+  model: string;
+  request_ordinal: number;
+  tool_call_count: number;
+  payload_bytes: number;
+  payload_sha256: string;
+  estimated_input_tokens: number;
+  context_window_tokens: number;
+  reserved_output_tokens: number;
+  safety_reserve_tokens: number;
+  allowed_input_tokens: number;
+  message: string;
+}
+
 export interface FusionChildTextBlockMetadata {
   utf8_bytes: number;
   sha256: string;
@@ -37,19 +71,109 @@ export interface FusionChildResultMetadata {
   text_blocks: FusionChildTextBlockMetadata[];
   text_sha256: string;
   usage: FusionChildResultUsageMetadata;
+  cache_observation: FusionClaudeCacheObservation;
+}
+
+export type FusionChildSettlementFailureReason =
+  | 'no_records'
+  | 'final_not_stop'
+  | 'invalid_non_final'
+  | 'runtime_guard'
+  | 'cache_observation';
+
+export interface FusionChildSettlementRecord {
+  schema_version: typeof FUSION_CHILD_SETTLEMENT_SCHEMA_VERSION;
+  status: 'complete' | 'failed';
+  record_count: number;
+  records_sha256: string;
+  final_record_index: number | null;
+  final_text_sha256: string | null;
+  recovered_error_ordinals: number[];
+  failure_reason: FusionChildSettlementFailureReason | null;
 }
 
 function protocolSha256(value: string | Buffer): string {
   return createHash('sha256').update(value).digest('hex');
 }
 
-export function buildFusionChildResultMetadata(message: {
-  provider: string;
-  model: string;
-  stopReason: string;
-  content: ReadonlyArray<{ type: string; text?: string }>;
-  usage: Usage;
-}): FusionChildResultMetadata {
+export function serializeFusionChildResultRecords(
+  records: readonly FusionChildResultMetadata[],
+): Buffer {
+  return Buffer.from(
+    records.length === 0 ? '' : `${records.map((record) => JSON.stringify(record)).join('\n')}\n`,
+    'utf8',
+  );
+}
+
+function hasZeroUsage(record: FusionChildResultMetadata): boolean {
+  const usage = record.usage;
+  return (
+    usage.input === 0 &&
+    usage.output === 0 &&
+    usage.cacheRead === 0 &&
+    usage.cacheWrite === 0 &&
+    usage.totalTokens === 0 &&
+    usage.cost.input === 0 &&
+    usage.cost.output === 0 &&
+    usage.cost.cacheRead === 0 &&
+    usage.cost.cacheWrite === 0 &&
+    usage.cost.total === 0
+  );
+}
+
+export function isRecoverableFusionChildErrorRecord(record: FusionChildResultMetadata): boolean {
+  return (
+    record.stop_reason === 'error' &&
+    record.text_blocks.length === 0 &&
+    record.text_sha256 === protocolSha256(Buffer.alloc(0)) &&
+    hasZeroUsage(record)
+  );
+}
+
+export function buildFusionChildSettlement(
+  records: readonly FusionChildResultMetadata[],
+  runtimeGuardFailed = false,
+  cacheObservationFailed = false,
+): FusionChildSettlementRecord {
+  const finalRecordIndex = records.length === 0 ? null : records.length - 1;
+  const final = records.at(-1);
+  const recoveredErrorOrdinals = records.flatMap((record, ordinal) =>
+    ordinal < records.length - 1 && isRecoverableFusionChildErrorRecord(record) ? [ordinal] : [],
+  );
+  const invalidNonFinal = records.some(
+    (record, ordinal) =>
+      ordinal < records.length - 1 &&
+      record.stop_reason !== 'toolUse' &&
+      !isRecoverableFusionChildErrorRecord(record),
+  );
+  let failureReason: FusionChildSettlementFailureReason | null = null;
+  if (runtimeGuardFailed) failureReason = 'runtime_guard';
+  else if (cacheObservationFailed) failureReason = 'cache_observation';
+  else if (final === undefined) failureReason = 'no_records';
+  else if (final.stop_reason !== 'stop') failureReason = 'final_not_stop';
+  else if (invalidNonFinal) failureReason = 'invalid_non_final';
+  return {
+    schema_version: FUSION_CHILD_SETTLEMENT_SCHEMA_VERSION,
+    status: failureReason === null ? 'complete' : 'failed',
+    record_count: records.length,
+    records_sha256: protocolSha256(serializeFusionChildResultRecords(records)),
+    final_record_index: finalRecordIndex,
+    final_text_sha256: final?.text_sha256 ?? null,
+    recovered_error_ordinals: recoveredErrorOrdinals,
+    failure_reason: failureReason,
+  };
+}
+
+export function buildFusionChildResultMetadata(
+  message: {
+    provider: string;
+    model: string;
+    stopReason: string;
+    content: ReadonlyArray<{ type: string; text?: string }>;
+    usage: Usage;
+  },
+  cacheObservation: FusionClaudeCacheObservation,
+): FusionChildResultMetadata {
   const textBlocks = message.content.flatMap((part) =>
     part.type === 'text' && typeof part.text === 'string' ? [part.text] : [],
   );
@@ -78,5 +202,6 @@ export function buildFusionChildResultMetadata(message: {
     })),
     text_sha256: protocolSha256(textBlocks.join('')),
     usage,
+    cache_observation: cacheObservation,
   };
 }

package/src/core/fusion/claude-cache.ts

@@ -0,0 +1,186 @@
+import type { JsonObject } from '../common.js';
+
+export const FUSION_CLAUDE_CACHE_OBSERVATION_SCHEMA_VERSION =
+  'pi-background-tasks.fusion-claude-cache-observation.v1' as const;
+export const FUSION_CLAUDE_CACHE_RETENTION_ENV = 'PI_CACHE_RETENTION';
+export const FUSION_CLAUDE_CACHE_DEFAULT_RETENTION = 'long' as const;
+export const FUSION_CLAUDE_CACHE_BREAKPOINT_LIMIT = 4;
+
+export type FusionClaudeCacheRetention = 'none' | 'short' | 'long';
+export type FusionClaudeCachePolicySource =
+  | 'default'
+  | typeof FUSION_CLAUDE_CACHE_RETENTION_ENV
+  | 'not_applicable';
+
+export interface FusionClaudeCacheObservation {
+  schema_version: typeof FUSION_CLAUDE_CACHE_OBSERVATION_SCHEMA_VERSION;
+  applicability: 'anthropic' | 'not_applicable';
+  source: FusionClaudeCachePolicySource;
+  requested_retention: FusionClaudeCacheRetention | null;
+  effective_retention: FusionClaudeCacheRetention | null;
+  breakpoint_count: number;
+  request_ordinal: number;
+}
+
+export interface FusionClaudeCacheNormalization {
+  payload: JsonObject;
+  observation: FusionClaudeCacheObservation;
+}
+
+function isRecord(value: unknown): value is JsonObject {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function unknownArray(value: unknown): unknown[] | undefined {
+  return Array.isArray(value) ? (value as unknown[]) : undefined;
+}
+
+function requireRequestOrdinal(value: number): number {
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw new Error('Fusion Claude cache request ordinal must be a positive safe integer');
+  }
+  return value;
+}
+
+function parseRetention(value: string): FusionClaudeCacheRetention {
+  if (value === 'none' || value === 'short' || value === 'long') return value;
+  throw new Error(
+    `${FUSION_CLAUDE_CACHE_RETENTION_ENV} must be one of none, short, or long; got ${JSON.stringify(value)}`,
+  );
+}
+
+export function resolveFusionClaudeCachePolicy(env: Readonly<NodeJS.ProcessEnv> = process.env): {
+  retention: FusionClaudeCacheRetention;
+  source: FusionClaudeCachePolicySource;
+} {
+  const configured = env[FUSION_CLAUDE_CACHE_RETENTION_ENV];
+  if (configured === undefined) {
+    return { retention: FUSION_CLAUDE_CACHE_DEFAULT_RETENTION, source: 'default' };
+  }
+  return {
+    retention: parseRetention(configured),
+    source: FUSION_CLAUDE_CACHE_RETENTION_ENV,
+  };
+}
+
+function validateCacheControl(value: unknown): JsonObject {
+  if (!isRecord(value)) {
+    throw new Error('Fusion Claude cache_control must be an object');
+  }
+  if (value['type'] !== 'ephemeral') {
+    throw new Error('Fusion Claude cache_control.type must be "ephemeral"');
+  }
+  const ttl = value['ttl'];
+  if (ttl !== undefined && ttl !== '1h' && ttl !== '5m') {
+    throw new Error('Fusion Claude cache_control.ttl must be "1h" or "5m" when present');
+  }
+  return value;
+}
+
+/**
+ * Normalize only cache breakpoints already selected by Pi's Anthropic adapter.
+ *
+ * Not creating new breakpoints is deliberate: an empty marker set may represent
+ * Pi's explicit cacheRetention="none" compaction request or a model compatibility
+ * restriction. The package may strengthen or disable native markers, but it must
+ * not override an upstream call-level opt-out that is no longer visible in the
+ * final provider payload.
+ */
+export function normalizeFusionClaudeCachePayload(input: {
+  payload: unknown;
+  requestOrdinal: number;
+  env?: Readonly<NodeJS.ProcessEnv>;
+  supportsLongCacheRetention?: boolean | undefined;
+}): FusionClaudeCacheNormalization {
+  if (!isRecord(input.payload)) {
+    throw new Error('Fusion Claude provider payload must be an object');
+  }
+  const requestOrdinal = requireRequestOrdinal(input.requestOrdinal);
+  const policy = resolveFusionClaudeCachePolicy(input.env ?? process.env);
+  const normalizedRetention: FusionClaudeCacheRetention =
+    policy.retention === 'long' && input.supportsLongCacheRetention === false
+      ? 'short'
+      : policy.retention;
+  let incomingBreakpoints = 0;
+  let outputBreakpoints = 0;
+
+  const normalizeBlock = (value: unknown): unknown => {
+    if (!isRecord(value) || !Object.hasOwn(value, 'cache_control')) return value;
+    const existing = value['cache_control'];
+    if (existing === undefined) {
+      const next = { ...value };
+      Reflect.deleteProperty(next, 'cache_control');
+      return next;
+    }
+    incomingBreakpoints += 1;
+    if (incomingBreakpoints > FUSION_CLAUDE_CACHE_BREAKPOINT_LIMIT) {
+      throw new Error(
+        `Fusion Claude payload has ${String(incomingBreakpoints)} cache_control breakpoints; Anthropic supports at most ${String(FUSION_CLAUDE_CACHE_BREAKPOINT_LIMIT)}`,
+      );
+    }
+    const control = validateCacheControl(existing);
+    const next = { ...value };
+    if (normalizedRetention === 'none') {
+      Reflect.deleteProperty(next, 'cache_control');
+      return next;
+    }
+    const normalizedControl = { ...control, type: 'ephemeral' };
+    Reflect.deleteProperty(normalizedControl, 'ttl');
+    if (normalizedRetention === 'long') Object.assign(normalizedControl, { ttl: '1h' });
+    next['cache_control'] = normalizedControl;
+    outputBreakpoints += 1;
+    return next;
+  };
+
+  const system = unknownArray(input.payload['system']);
+  const tools = unknownArray(input.payload['tools']);
+  const messages = unknownArray(input.payload['messages']);
+  const payload = {
+    ...input.payload,
+    ...(system === undefined ? {} : { system: system.map(normalizeBlock) }),
+    ...(tools === undefined ? {} : { tools: tools.map(normalizeBlock) }),
+    ...(messages === undefined
+      ? {}
+      : {
+          messages: messages.map((message) => {
+            if (!isRecord(message)) return message;
+            const content = unknownArray(message['content']);
+            return content === undefined
+              ? message
+              : { ...message, content: content.map(normalizeBlock) };
+          }),
+        }),
+  };
+  if (outputBreakpoints > FUSION_CLAUDE_CACHE_BREAKPOINT_LIMIT) {
+    throw new Error(
+      `Fusion Claude payload produced ${String(outputBreakpoints)} cache_control breakpoints; Anthropic supports at most ${String(FUSION_CLAUDE_CACHE_BREAKPOINT_LIMIT)}`,
+    );
+  }
+
+  return {
+    payload,
+    observation: {
+      schema_version: FUSION_CLAUDE_CACHE_OBSERVATION_SCHEMA_VERSION,
+      applicability: 'anthropic',
+      source: policy.source,
+      requested_retention: policy.retention,
+      effective_retention: outputBreakpoints === 0 ? 'none' : normalizedRetention,
+      breakpoint_count: outputBreakpoints,
+      request_ordinal: requestOrdinal,
+    },
+  };
+}
+
+export function nonAnthropicFusionCacheObservation(
+  requestOrdinal: number,
+): FusionClaudeCacheObservation {
+  return {
+    schema_version: FUSION_CLAUDE_CACHE_OBSERVATION_SCHEMA_VERSION,
+    applicability: 'not_applicable',
+    source: 'not_applicable',
+    requested_retention: null,
+    effective_retention: null,
+    breakpoint_count: 0,
+    request_ordinal: requireRequestOrdinal(requestOrdinal),
+  };
+}