pi-background-tasks 1.0.6 → 1.0.7

package/README.md

@@ -26,7 +26,7 @@
 | Fact | Value |
 | --- | --- |
 | Package | `pi-background-tasks` |
-| Version | `1.0.6` |
+| Version | `1.0.7` |
 | Node engine | `>=22.19.0` |
 | Pi entrypoint | `./extensions/background-tasks.ts` |
 | Package image | [logo.png](https://raw.githubusercontent.com/ismailsaleekh/pi-background-tasks/main/logo.png) |

package/docs/manifest.json

@@ -89,7 +89,7 @@
       "state": "pass"
     },
     {
-      "authored_body_sha256": "sha256:77a2a9bfeb73a4cda9c65b2559a06e141096ff496d732e1e3d9c4eb1a0ba8616",
+      "authored_body_sha256": "sha256:2cea3292dac7fcb890bb05eb0c0783310671e11c1953c981251ec433b1099cb9",
       "covers_sources": [
         "extensions/fusion-child.ts",
         "src/core/fusion/artifacts.ts",
@@ -788,7 +788,7 @@
     "image": "https://raw.githubusercontent.com/ismailsaleekh/pi-background-tasks/main/logo.png",
     "name": "pi-background-tasks",
     "type": "module",
-    "version": "1.0.6"
+    "version": "1.0.7"
   },
   "public_surface_ids": [
     "command:bg",

package/docs/reference/runtime-contracts.md

@@ -49,10 +49,10 @@ This generated registry lists production environment-variable references, runtim
 | `PI_BG_SHELL` | read | `src/core/common.ts:679` |
 | `PI_BG_SHELL_PATH` | read | `src/core/common.ts:680` |
 | `PI_CACHE_RETENTION` | read | `src/core/fusion/claude-cache.ts:56` |
-| `PI_FUSION_RESEARCH_ENABLED` | read, remove, write | `src/core/fusion/pi-child.ts:1807`<br>`src/core/fusion/pi-child.ts:92`<br>`src/fusion-child-extension.ts:673` |
-| `PI_FUSION_SOURCE_POLICY_PATH` | read, remove, write | `src/core/fusion/pi-child.ts:1808`<br>`src/core/fusion/pi-child.ts:92`<br>`src/fusion-child-extension.ts:629` |
-| `PI_FUSION_SOURCE_POLICY_SHA256` | read, remove, write | `src/core/fusion/pi-child.ts:1809`<br>`src/core/fusion/pi-child.ts:92`<br>`src/fusion-child-extension.ts:630` |
-| `PI_FUSION_TOOL_CALL_LOG_PATH` | read, remove, write | `src/core/fusion/pi-child.ts:1796`<br>`src/core/fusion/pi-child.ts:92`<br>`src/fusion-child-extension.ts:672` |
+| `PI_FUSION_RESEARCH_ENABLED` | read, remove, write | `src/core/fusion/pi-child.ts:1811`<br>`src/core/fusion/pi-child.ts:92`<br>`src/fusion-child-extension.ts:673` |
+| `PI_FUSION_SOURCE_POLICY_PATH` | read, remove, write | `src/core/fusion/pi-child.ts:1812`<br>`src/core/fusion/pi-child.ts:92`<br>`src/fusion-child-extension.ts:629` |
+| `PI_FUSION_SOURCE_POLICY_SHA256` | read, remove, write | `src/core/fusion/pi-child.ts:1813`<br>`src/core/fusion/pi-child.ts:92`<br>`src/fusion-child-extension.ts:630` |
+| `PI_FUSION_TOOL_CALL_LOG_PATH` | read, remove, write | `src/core/fusion/pi-child.ts:1800`<br>`src/core/fusion/pi-child.ts:92`<br>`src/fusion-child-extension.ts:672` |
 | `PI_MODEL` | remove | `src/core/delegate/launch.ts:301`<br>`src/core/fusion/pi-child.ts:92` |
 | `PI_OFFLINE` | read | `src/extension.ts:445` |
 | `PI_PROVIDER` | remove | `src/core/delegate/launch.ts:301`<br>`src/core/fusion/pi-child.ts:92` |
@@ -81,26 +81,26 @@ This generated registry lists production environment-variable references, runtim
 | delegate-artifact | `seed.json` | `src/core/delegate/artifacts.ts:40` |
 | delegate-artifact | `spill/<receipt-named-file>` | `src/core/delegate/artifacts.ts:53` |
 | directory | `.pi/delegate/<session-id>-<pid>/<task-id>/` | `src/core/delegate/artifacts.ts:157` |
-| directory | `.pi/fusion/<session-id>-<pid>/<run-id>/` | `src/core/fusion/artifacts.ts:251` |
+| directory | `.pi/fusion/<session-id>-<pid>/<run-id>/` | `src/core/fusion/artifacts.ts:277` |
 | directory | `.pi/tasks/<session-id>-<pid>/` | `src/core/registry.ts:780` |
-| fusion-artifact | `<attempt-prefix> = candidate-<slot>.attempt-<n> \| evaluation.attempt-<n> \| merge.attempt-<n>` | `src/core/fusion/artifacts.ts:193` |
-| fusion-artifact | `<attempt-prefix>.calibration-violation.json` | `src/core/fusion/artifacts.ts:208` |
-| fusion-artifact | `<attempt-prefix>.events.jsonl` | `src/core/fusion/artifacts.ts:402` |
-| fusion-artifact | `<attempt-prefix>.prompt.txt` | `src/core/fusion/artifacts.ts:401` |
-| fusion-artifact | `<attempt-prefix>.stderr.txt` | `src/core/fusion/artifacts.ts:403` |
-| fusion-artifact | `blind-candidates.json` | `src/core/fusion/artifacts.ts:373` |
-| fusion-artifact | `budget-plan.json` | `src/core/fusion/artifacts.ts:369` |
-| fusion-artifact | `candidate-<slot>.attempt-<n>.response.md \| candidate-<slot>.attempt-<n>.response.partial.md` | `src/core/fusion/artifacts.ts:203` |
-| fusion-artifact | `candidate-<slot>.attempt-<n>.tool-calls.jsonl` | `src/core/fusion/artifacts.ts:301` |
+| fusion-artifact | `<attempt-prefix> = candidate-<slot>.attempt-<n> \| evaluation.attempt-<n> \| merge.attempt-<n>` | `src/core/fusion/artifacts.ts:219` |
+| fusion-artifact | `<attempt-prefix>.calibration-violation.json` | `src/core/fusion/artifacts.ts:234` |
+| fusion-artifact | `<attempt-prefix>.events.jsonl` | `src/core/fusion/artifacts.ts:429` |
+| fusion-artifact | `<attempt-prefix>.prompt.txt` | `src/core/fusion/artifacts.ts:428` |
+| fusion-artifact | `<attempt-prefix>.stderr.txt` | `src/core/fusion/artifacts.ts:430` |
+| fusion-artifact | `blind-candidates.json` | `src/core/fusion/artifacts.ts:399` |
+| fusion-artifact | `budget-plan.json` | `src/core/fusion/artifacts.ts:395` |
+| fusion-artifact | `candidate-<slot>.attempt-<n>.response.md \| candidate-<slot>.attempt-<n>.response.partial.md` | `src/core/fusion/artifacts.ts:229` |
+| fusion-artifact | `candidate-<slot>.attempt-<n>.tool-calls.jsonl` | `src/core/fusion/artifacts.ts:327` |
 | fusion-artifact | `candidate-<slot>.attempt-<n>.tool-calls.jsonl.seal.json` | `src/core/fusion/child-protocol.ts:17` |
-| fusion-artifact | `canonical-input.json` | `src/core/fusion/artifacts.ts:339` |
-| fusion-artifact | `context-omission-ledger.json` | `src/core/fusion/artifacts.ts:348` |
-| fusion-artifact | `error.json` | `src/core/fusion/artifacts.ts:385` |
-| fusion-artifact | `evaluation.attempt-<n>.response.txt \| evaluation.attempt-<n>.response.partial.txt` | `src/core/fusion/artifacts.ts:203` |
-| fusion-artifact | `evaluation.json` | `src/core/fusion/artifacts.ts:377` |
-| fusion-artifact | `merge.attempt-<n>.response.md \| merge.attempt-<n>.response.partial.md` | `src/core/fusion/artifacts.ts:203` |
-| fusion-artifact | `merged.md` | `src/core/fusion/artifacts.ts:316` |
-| fusion-artifact | `source-policy.private.json` | `src/core/fusion/artifacts.ts:355` |
+| fusion-artifact | `canonical-input.json` | `src/core/fusion/artifacts.ts:365` |
+| fusion-artifact | `context-omission-ledger.json` | `src/core/fusion/artifacts.ts:374` |
+| fusion-artifact | `error.json` | `src/core/fusion/artifacts.ts:411` |
+| fusion-artifact | `evaluation.attempt-<n>.response.txt \| evaluation.attempt-<n>.response.partial.txt` | `src/core/fusion/artifacts.ts:229` |
+| fusion-artifact | `evaluation.json` | `src/core/fusion/artifacts.ts:403` |
+| fusion-artifact | `merge.attempt-<n>.response.md \| merge.attempt-<n>.response.partial.md` | `src/core/fusion/artifacts.ts:229` |
+| fusion-artifact | `merged.md` | `src/core/fusion/artifacts.ts:342` |
+| fusion-artifact | `source-policy.private.json` | `src/core/fusion/artifacts.ts:381` |
 | task-file | `.pi/tasks/<session-id>-<pid>/<task-id>.attestation.json` | `src/core/attested-pi-run.ts:583` |
 | task-file | `.pi/tasks/<session-id>-<pid>/<task-id>.json` | `src/core/registry.ts:808` |
 | task-file | `.pi/tasks/<session-id>-<pid>/<task-id>.output` | `src/core/registry.ts:807` |
@@ -127,20 +127,20 @@ This generated registry lists production environment-variable references, runtim
 | `pi-background-tasks.extension-request.v1` | `src/core/extension-api.ts:15` |
 | `pi-background-tasks.extension-response.v1` | `src/core/extension-api.ts:16` |
 | `pi-background-tasks.extension-terminal.v1` | `src/core/extension-api.ts:17` |
-| `pi-background-tasks.fusion-blind-candidates.v1` | `src/core/fusion/prompts.ts:299` |
+| `pi-background-tasks.fusion-blind-candidates.v1` | `src/core/fusion/prompts.ts:300` |
 | `pi-background-tasks.fusion-budget-plan.v4` | `src/core/fusion/types.ts:25` |
-| `pi-background-tasks.fusion-calibration-violation.v1` | `src/core/fusion/types.ts:27` |
+| `pi-background-tasks.fusion-calibration-violation.v2` | `src/core/fusion/types.ts:27` |
 | `pi-background-tasks.fusion-child-result.v3` | `src/core/fusion/child-protocol.ts:6` |
 | `pi-background-tasks.fusion-child-settlement.v2` | `src/core/fusion/child-protocol.ts:9` |
 | `pi-background-tasks.fusion-claude-cache-observation.v1` | `src/core/fusion/claude-cache.ts:4` |
 | `pi-background-tasks.fusion-context-ledger.v2` | `src/core/fusion/types.ts:23` |
-| `pi-background-tasks.fusion-evaluation-repair-input.v1` | `src/core/fusion/prompts.ts:279` |
+| `pi-background-tasks.fusion-evaluation-repair-input.v1` | `src/core/fusion/prompts.ts:280` |
 | `pi-background-tasks.fusion-evaluation.v1` | `src/core/fusion/types.ts:16` |
 | `pi-background-tasks.fusion-input.v4` | `src/core/fusion/types.ts:14` |
 | `pi-background-tasks.fusion-input.v5` | `src/core/fusion/types.ts:15` |
 | `pi-background-tasks.fusion-manifest.v3` | `src/core/fusion/types.ts:21` |
 | `pi-background-tasks.fusion-manifest.v4` | `src/core/fusion/types.ts:22` |
-| `pi-background-tasks.fusion-merge-input.v1` | `src/core/fusion/prompts.ts:325` |
+| `pi-background-tasks.fusion-merge-input.v1` | `src/core/fusion/prompts.ts:326` |
 | `pi-background-tasks.fusion-models.v1` | `src/core/fusion/types.ts:13` |
 | `pi-background-tasks.fusion-progress.v1` | `src/fusion-extension.ts:57` |
 | `pi-background-tasks.fusion-request.v1` | `src/fusion-extension.ts:58` |
@@ -149,7 +149,8 @@ This generated registry lists production environment-variable references, runtim
 | `pi-background-tasks.fusion-runtime-guard.v1` | `src/core/fusion/child-protocol.ts:19` |
 | `pi-background-tasks.fusion-source-policy.v1` | `src/core/fusion/types.ts:24` |
 | `pi-background-tasks.fusion-tool-call-seal.v1` | `src/core/fusion/child-protocol.ts:16` |
-| `pi-background-tasks.fusion-tool-call.v1` | `src/core/fusion/types.ts:28` |
+| `pi-background-tasks.fusion-tool-call.v1` | `src/core/fusion/types.ts:30` |
+| `pi-background-tasks.fusion-validation-candidate-contract-event.v1` | `src/core/fusion/types.ts:29` |
 | `pi-background-tasks.fusion-validation-candidate.v1` | `src/core/fusion/types.ts:18` |
 | `pi-background-tasks.input-token-calibration.v1` | `src/core/context/token-budget.ts:18` |
 

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

@@ -12,12 +12,12 @@ 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: `1.0.6`
+- Canonical package version: `1.0.7`
 - Governed markdown docs: 40
 - Public surfaces extracted: 30
 - Governed production sources: 45
 - Tool contracts extracted: 11
-- Schema IDs extracted: 40
+- Schema IDs extracted: 41
 - Environment variable references extracted: 47
 - Behavioral attestation receipts not passing: 1
 - Receipt store: `docs/attestations.json`

package/docs/subsystems/fusion.md

@@ -72,7 +72,7 @@ Evaluator, evaluator-repair, and merger always use capability `reason` and empty
 
 ## 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
 
@@ -96,7 +96,7 @@ Fusion child environments strip session/model/provider variables plus metered cr
 
 ## 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` 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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-background-tasks",
-  "version": "1.0.6",
+  "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",

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

@@ -1122,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,
@@ -1137,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/evaluation.ts

@@ -525,6 +525,67 @@ export interface ParsedFusionValidationCandidateReport {
   limitations: readonly string[];
 }
 
+export type FusionValidationCandidateNormalization =
+  | 'markdown_json_fence'
+  | 'prose_then_markdown_json_fence';
+
+export interface RecoveredFusionValidationCandidateReport {
+  report: ParsedFusionValidationCandidateReport;
+  /** Bare JSON forwarded to the evaluator after explicit, audited recovery. */
+  response: string;
+  normalization: FusionValidationCandidateNormalization;
+}
+
+/**
+ * Recognize exactly one complete Markdown JSON fence, optionally preceded by a
+ * short prose preamble. This is deliberately narrower than generic substring
+ * extraction: trailing prose, nested fences, unlabelled fences, and oversized
+ * preambles remain contract failures.
+ */
+function fencedValidationCandidateJson(text: string): {
+  payload: string;
+  normalization: FusionValidationCandidateNormalization;
+} | undefined {
+  const trimmed = text.trim();
+  const openingPattern = /```json[ \t]*\r?\n/giu;
+  const openings = [...trimmed.matchAll(openingPattern)];
+  if (openings.length !== 1) return undefined;
+  const opening = openings[0];
+  if (opening === undefined) return undefined;
+  const headerEnd = opening.index + opening[0].length;
+  const closing = trimmed.indexOf('```', headerEnd);
+  if (closing < 0 || trimmed.slice(closing + 3).includes('```')) return undefined;
+  if (trimmed.slice(closing + 3).trim().length > 0) return undefined;
+  const preamble = trimmed.slice(0, opening.index).trim();
+  if (Buffer.byteLength(preamble, 'utf8') > 2_000 || preamble.includes('```')) return undefined;
+  const payload = trimmed.slice(headerEnd, closing).trim();
+  if (payload.length === 0 || payload.includes('```')) return undefined;
+  return {
+    payload,
+    normalization: preamble.length === 0
+      ? 'markdown_json_fence'
+      : 'prose_then_markdown_json_fence',
+  };
+}
+
+/**
+ * Defensive recovery for the one observed contract violation shape. Callers
+ * must persist/surface the returned normalization; this function intentionally
+ * does not make the strict parser permissive.
+ */
+export function recoverFencedFusionValidationCandidateReport(
+  text: string,
+  candidateId: FusionCandidateId,
+): RecoveredFusionValidationCandidateReport | undefined {
+  const recovered = fencedValidationCandidateJson(text);
+  if (recovered === undefined) return undefined;
+  return {
+    report: parseFusionValidationCandidateReport(recovered.payload, candidateId),
+    response: recovered.payload,
+    normalization: recovered.normalization,
+  };
+}
+
 export function parseFusionValidationCandidateReport(text: string, candidateId: FusionCandidateId): ParsedFusionValidationCandidateReport {
   let parsed: unknown;
   try {

package/src/core/fusion/orchestrator.ts

@@ -1,4 +1,4 @@
-import { randomBytes as nodeRandomBytes } from 'node:crypto';
+import { createHash, randomBytes as nodeRandomBytes } from 'node:crypto';
 import { canonicalJson } from '../attested-pi-run.js';
 import { parseJsonText } from '../common.js';
 import { FUSION_BUDGET_POLICY, FusionBudget, assertChildOutputWithinContract } from './budget.js';
@@ -11,6 +11,7 @@ import {
   boundedEvaluationErrors,
   formatEvaluationErrors,
   parseFusionValidationCandidateReport,
+  recoverFencedFusionValidationCandidateReport,
   renderValidatedFusionValidationReport,
   validateFusionEvaluation,
   validateFusionFindingAccounting,
@@ -35,6 +36,7 @@ import {
   FUSION_INPUT_SCHEMA_VERSION,
   FUSION_NO_TOOLS_CAPABILITY,
   FUSION_RESULT_SCHEMA_VERSION,
+  FUSION_VALIDATE_CANDIDATE_SCHEMA_VERSION,
   FusionError,
   addFusionUsage,
   createEmptyFusionUsage,
@@ -169,6 +171,7 @@ function recordFailureInput(
   stage: FusionStage,
   slot: CandidateSlot | undefined,
   attempt: number,
+  systemPrompt: string,
   prompt: string,
   responseKind: 'md' | 'txt',
 ): RecordFusionFailedAttemptInput {
@@ -176,6 +179,7 @@ function recordFailureInput(
     const base: RecordFusionFailedAttemptInput = {
       stage,
       attempt,
+      systemPrompt,
       prompt,
       events: error.events,
       partialResponse: error.response,
@@ -194,6 +198,7 @@ function recordFailureInput(
   const base: RecordFusionFailedAttemptInput = {
     stage,
     attempt,
+    systemPrompt,
     prompt,
     events: Buffer.alloc(0),
     partialResponse: Buffer.alloc(0),
@@ -371,22 +376,123 @@ function anonymousCandidates(
 }
 
 interface ValidationSourceData {
+  candidates: readonly [AnonymousFusionCandidate, AnonymousFusionCandidate, AnonymousFusionCandidate];
   findings: readonly FusionValidationFindingRecord[];
   verified: readonly string[];
   limitations: readonly string[];
 }
 
-function validationSourceData(candidates: readonly [AnonymousFusionCandidate, AnonymousFusionCandidate, AnonymousFusionCandidate]): ValidationSourceData {
+function sha256Text(value: string): string {
+  return createHash('sha256').update(value, 'utf8').digest('hex');
+}
+
+function boundedContractError(error: unknown): string {
+  const value = errorText(error);
+  return value.length <= 1_000 ? value : `${value.slice(0, 999)}…`;
+}
+
+/**
+ * Enforce the validation-candidate contract without making the shared JSON
+ * parser permissive. A single, tightly recognized fenced response is recovered
+ * with a durable warning. One irrecoverable minority report is represented as
+ * an explicit limitation; two or more still fail the workflow loudly.
+ */
+async function prepareValidationSourceData(
+  candidates: readonly [AnonymousFusionCandidate, AnonymousFusionCandidate, AnonymousFusionCandidate],
+  anonymousMap: Record<FusionCandidateId, CandidateSlot>,
+  store: FusionArtifactStore,
+): Promise<ValidationSourceData> {
+  const prepared = candidates.map((candidate) => ({ ...candidate })) as [
+    AnonymousFusionCandidate,
+    AnonymousFusionCandidate,
+    AnonymousFusionCandidate,
+  ];
   const findings: FusionValidationFindingRecord[] = [];
   const verified: string[] = [];
   const limitations: string[] = [];
-  for (const candidate of candidates) {
-    const report = parseFusionValidationCandidateReport(candidate.response, candidate.candidate_id);
-    findings.push(...report.findings);
-    verified.push(...report.verified);
+  let normalizationCount = 0;
+  const failures: Array<{ candidate: AnonymousFusionCandidate; error: string }> = [];
+
+  for (const candidate of prepared) {
+    try {
+      const report = parseFusionValidationCandidateReport(candidate.response, candidate.candidate_id);
+      findings.push(...report.findings);
+      verified.push(...report.verified);
+      limitations.push(...report.limitations);
+      continue;
+    } catch (strictError) {
+      try {
+        const recovered = recoverFencedFusionValidationCandidateReport(
+          candidate.response,
+          candidate.candidate_id,
+        );
+        if (recovered === undefined) throw strictError;
+        await store.recordValidationCandidateContractEvent({
+          candidateId: candidate.candidate_id,
+          slot: anonymousMap[candidate.candidate_id],
+          status: 'normalized',
+          detail: {
+            normalization: recovered.normalization,
+            original_sha256: sha256Text(candidate.response),
+            forwarded_sha256: sha256Text(recovered.response),
+            warning: 'Candidate output violated the bare-JSON contract; a single complete JSON fence was removed and recorded.',
+          },
+        });
+        candidate.response = recovered.response;
+        findings.push(...recovered.report.findings);
+        verified.push(...recovered.report.verified);
+        limitations.push(...recovered.report.limitations);
+        normalizationCount += 1;
+        continue;
+      } catch (recoveryError) {
+        failures.push({
+          candidate,
+          error: boundedContractError(recoveryError === strictError ? strictError : recoveryError),
+        });
+      }
+    }
+  }
+
+  if (normalizationCount > 0) {
+    limitations.push(
+      `${String(normalizationCount)} validation report${normalizationCount === 1 ? '' : 's'} required audited removal of a Markdown JSON wrapper; JSON content was unchanged.`,
+    );
+  }
+
+  for (const failure of failures) {
+    await store.recordValidationCandidateContractEvent({
+      candidateId: failure.candidate.candidate_id,
+      slot: anonymousMap[failure.candidate.candidate_id],
+      status: 'dropped',
+      detail: {
+        response_sha256: sha256Text(failure.candidate.response),
+        error: failure.error,
+        warning: 'Candidate output could not be parsed under the strict or fenced-JSON contract.',
+      },
+    });
+  }
+  if (failures.length > 1) {
+    throw new FusionError(
+      `fusion_validate cannot continue: ${String(failures.length)} of 3 candidate reports violated the structured-output contract`,
+      { code: 'evaluation_invalid', stage: 'candidate' },
+    );
+  }
+  const failure = failures[0];
+  if (failure !== undefined) {
+    const synthetic = canonicalJson({
+      schema_version: FUSION_VALIDATE_CANDIDATE_SCHEMA_VERSION,
+      findings: [],
+      verified: [],
+      limitations: [
+        'This validation report could not be parsed after strict contract checks; no findings or verification claims from it were included.',
+      ],
+    });
+    failure.candidate.response = synthetic;
+    const report = parseFusionValidationCandidateReport(synthetic, failure.candidate.candidate_id);
     limitations.push(...report.limitations);
   }
-  return { findings, verified, limitations };
+
+  return { candidates: prepared, findings, verified, limitations };
 }
 
 function validateEvaluationAccountsForSourceFindings(
@@ -558,11 +664,16 @@ export class FusionOrchestrator {
       input.onProgress?.({ type: 'state', state: 'candidates_complete' });
 
       const shuffled = anonymousCandidates(candidateResults, shuffledSlots(this.randomBytes));
-      const validationData = profile.id === 'validate' ? validationSourceData(shuffled.candidates) : undefined;
+      // Persist the blind mapping before workflow-specific contract parsing
+      // so a failed validation remains attributable to its durable slot artifact.
       await store.setAnonymousMap(shuffled.map);
+      const validationData = profile.id === 'validate'
+        ? await prepareValidationSourceData(shuffled.candidates, shuffled.map, store)
+        : undefined;
+      const evaluationCandidates = validationData?.candidates ?? shuffled.candidates;
       const blindInput = buildBlindEvaluationInput(
         input.canonicalInput,
-        shuffled.candidates,
+        evaluationCandidates,
         validationData?.findings,
       );
       await store.writeBlindCandidates(buildEvaluationPrompt(blindInput));
@@ -585,7 +696,7 @@ export class FusionOrchestrator {
 
       await store.transition('merging');
       input.onProgress?.({ type: 'state', state: 'merging' });
-      const mergeInput = buildMergeInput(input.canonicalInput, shuffled.candidates, evaluation);
+      const mergeInput = buildMergeInput(input.canonicalInput, evaluationCandidates, evaluation);
       const mergePrompt = buildMergePrompt(mergeInput);
       budget.assertStagePrompt('merge', profile.mergerSystemPrompt, mergePrompt);
       input.onProgress?.({ type: 'merge_started' });
@@ -604,7 +715,7 @@ export class FusionOrchestrator {
         'md',
       );
       addFusionUsage(usage, merged.usage);
-      await store.recordChildAttempt({ result: merged, prompt: mergePrompt, responseKind: 'md' });
+      await store.recordChildAttempt({ result: merged, systemPrompt: profile.mergerSystemPrompt, prompt: mergePrompt, responseKind: 'md' });
       await this.recordCalibrationObservation(
         input,
         store,
@@ -729,9 +840,9 @@ export class FusionOrchestrator {
           controller.signal,
           candidateCapability,
           slot,
-          'md',
+          profile.id === 'validate' ? 'txt' : 'md',
         ).then(async (result) => {
-          await store.recordChildAttempt({ result, prompt, responseKind: 'md' });
+          await store.recordChildAttempt({ result, systemPrompt, prompt, responseKind: profile.id === 'validate' ? 'txt' : 'md' });
           await this.recordCalibrationObservation(
             input,
             store,
@@ -866,7 +977,7 @@ export class FusionOrchestrator {
       attempt,
     );
     addFusionUsage(usage, result.usage);
-    await store.recordChildAttempt({ result, prompt, responseKind: 'txt' });
+    await store.recordChildAttempt({ result, systemPrompt, prompt, responseKind: 'txt' });
     await this.recordCalibrationObservation(
       input,
       store,
@@ -966,7 +1077,7 @@ export class FusionOrchestrator {
         if (!signal.aborted && retryableSpawn(error, launchTry) && launchTry === 1) continue;
         addFailedChildUsage(usage, error);
         await store.recordFailedAttempt(
-          recordFailureInput(error, stage, slot, logicalAttempt, userPrompt, responseKind),
+          recordFailureInput(error, stage, slot, logicalAttempt, systemPrompt, userPrompt, responseKind),
         );
         await store.setUsage(usage);
         throw error;

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

@@ -1440,6 +1440,8 @@ export class FusionPiCompactResultParser {
   ): {
     text: string;
     usage: FusionUsage;
+    firstRequestUsage: FusionUsage;
+    providerRequestCount: number;
     provider: string;
     model: string;
     qualifiedId: string;
@@ -1474,6 +1476,8 @@ export class FusionPiCompactResultParser {
     return {
       text: reconstructFinalText(response, final),
       usage: observed.usage,
+      firstRequestUsage: cloneFusionUsage(parsed.records[0]?.usage ?? createEmptyFusionUsage()),
+      providerRequestCount: parsed.records.length,
       provider: final.provider,
       model: final.model,
       qualifiedId: `${final.provider}/${final.model}`,
@@ -2119,6 +2123,8 @@ export async function runPiChild(options: RunPiChildOptions): Promise<FusionChil
       qualifiedId: parsed.qualifiedId,
       text: parsed.text,
       usage: parsed.usage,
+      firstRequestUsage: parsed.firstRequestUsage,
+      providerRequestCount: parsed.providerRequestCount,
       events: parsed.events,
       stderr: parsed.diagnostics,
       exitCode: close.code,

package/src/core/fusion/prompts.ts

@@ -190,6 +190,7 @@ Return only JSON matching this exact closed schema:
   "limitations": ["non-blank statement of what you could not cover"]
 }
 Use an empty findings array when no issues were found; do not omit verified or limitations.
+Do not wrap the JSON in Markdown fences or prose. Emit exactly one bare JSON object.
 
 Do not inflate severity and do not invent issues to appear thorough. If the work is correct, say so plainly in verified/limitations. A report with no findings that names the evidence behind that conclusion is a valid and valuable result; a padded report is not.
 

package/src/core/fusion/types.ts

@@ -24,7 +24,9 @@ export const FUSION_CONTEXT_LEDGER_SCHEMA_VERSION = 'pi-background-tasks.fusion-
 export const FUSION_SOURCE_POLICY_SCHEMA_VERSION = 'pi-background-tasks.fusion-source-policy.v1';
 export const FUSION_BUDGET_PLAN_SCHEMA_VERSION = 'pi-background-tasks.fusion-budget-plan.v4';
 export const FUSION_CALIBRATION_VIOLATION_SCHEMA_VERSION =
-  'pi-background-tasks.fusion-calibration-violation.v1';
+  'pi-background-tasks.fusion-calibration-violation.v2';
+export const FUSION_VALIDATE_CANDIDATE_CONTRACT_EVENT_SCHEMA_VERSION =
+  'pi-background-tasks.fusion-validation-candidate-contract-event.v1';
 export const FUSION_TOOL_CALL_LOG_SCHEMA_VERSION = 'pi-background-tasks.fusion-tool-call.v1';
 
 /**
@@ -769,7 +771,12 @@ export interface FusionChildRunResult {
   model: string;
   qualifiedId: string;
   text: string;
+  /** Aggregate usage across the complete child agent loop. */
   usage: FusionUsage;
+  /** First provider request, used for like-for-like prompt forecast calibration. */
+  firstRequestUsage?: FusionUsage;
+  /** Number of provider requests represented by aggregate usage. */
+  providerRequestCount?: number;
   events: Buffer;
   stderr: Buffer;
   exitCode: number;
@@ -962,6 +969,8 @@ export interface FusionCalibrationViolation {
   rate_source: TokenBudgetRateSource;
   prompt_utf8_bytes: number;
   prompt_sha256: string;
+  observation_scope: 'first_provider_request';
+  provider_request_count: number;
   forecast_input_tokens: number;
   billed_input_tokens: number;
   billed_input_breakdown: {