pi-background-tasks 1.0.7 → 2.1.1

package/src/core/fusion/config.ts

@@ -5,6 +5,7 @@ import { getAgentDir } from '@earendil-works/pi-coding-agent';
 import type { Api, Model } from '@earendil-works/pi-ai';
 import { isJsonObject, parseJsonText, type JsonObject } from '../common.js';
 import { replaceFileDurable } from '../durable-fs.js';
+import { CLAUDE_CODE_200K_SUBSCRIPTION_CONTEXT_WINDOW } from './anthropic-attribution.js';
 import {
   FUSION_MODEL_CONFIG_SCHEMA_VERSION,
   FusionError,
@@ -158,6 +159,13 @@ function requireContextWindow(model: Model<Api>, label: string): number {
   return Math.floor(value);
 }
 
+function transportContextWindow(model: Model<Api>, label: string): number {
+  const advertised = requireContextWindow(model, label);
+  return model.provider === 'anthropic'
+    ? Math.min(advertised, CLAUDE_CODE_200K_SUBSCRIPTION_CONTEXT_WINDOW)
+    : advertised;
+}
+
 function requireMaxOutputTokens(model: Model<Api>, label: string): number {
   const value = model.maxTokens;
   if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
@@ -315,7 +323,7 @@ function resolveSelection(
       model: available.id,
       qualifiedId,
       thinkingLevel,
-      contextWindow: requireContextWindow(available, slotLabel),
+      contextWindow: transportContextWindow(available, slotLabel),
       maxOutputTokens: requireMaxOutputTokens(available, slotLabel),
     };
   }
@@ -334,7 +342,7 @@ function resolveSelection(
     model: model.id,
     qualifiedId: selection,
     thinkingLevel,
-    contextWindow: requireContextWindow(model, slotLabel),
+    contextWindow: transportContextWindow(model, slotLabel),
     maxOutputTokens: requireMaxOutputTokens(model, slotLabel),
   };
 }

package/src/core/fusion/orchestrator.ts

@@ -1,7 +1,8 @@
 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';
+import { FUSION_BUDGET_POLICY, FusionBudget } from './budget.js';
+import { assertChildOutputWithinContract } from './output-contract.js';
 import {
   FusionArtifactStore,
   type CreateFusionArtifactStoreOptions,
@@ -39,7 +40,9 @@ import {
   FUSION_VALIDATE_CANDIDATE_SCHEMA_VERSION,
   FusionError,
   addFusionUsage,
+  cloneFusionUsage,
   createEmptyFusionUsage,
+  type FusionArtifactManifest,
   type FusionCalibrationViolation,
   type FusionCapability,
   type FusionCanonicalInputV3,
@@ -50,6 +53,7 @@ import {
   type FusionEvaluationV1,
   type FusionModelConfigV1,
   type FusionProgressEvent,
+  type FusionRunProgress,
   type FusionRunResult,
   type FusionSource,
   type FusionStage,
@@ -63,6 +67,12 @@ export type FusionChildRunner = (options: RunPiChildOptions) => Promise<FusionCh
 export type FusionProgressSink = (event: FusionProgressEvent) => void;
 export type FusionRandomBytes = (size: number) => Buffer;
 
+export interface FusionRunReady {
+  runId: string;
+  artifactDir: string;
+  artifactDirAbs: string;
+}
+
 type CandidateSlot = 1 | 2 | 3;
 
 export interface FusionWorkflowInput {
@@ -79,6 +89,12 @@ export interface FusionWorkflowInput {
   profile?: FusionWorkflowProfile | undefined;
   signal?: AbortSignal | undefined;
   onProgress?: FusionProgressSink | undefined;
+  /**
+   * Optional no-child-yet handoff. The orchestrator pauses here after durable
+   * preflight and budget admission, allowing a background registry receipt to
+   * become durable before candidate launch.
+   */
+  onReady?: ((ready: FusionRunReady) => Promise<void>) | undefined;
 }
 
 export interface FusionOrchestratorOptions {
@@ -120,7 +136,8 @@ function hasOnlyKeys(value: Record<string, unknown>, allowed: readonly string[])
 
 function isStrictCleanCanonicalInput(value: unknown): boolean {
   if (!isRecord(value)) return false;
-  if (!hasOnlyKeys(value, ['schema_version', 'workflow', 'cwd', 'request', 'context'])) return false;
+  if (!hasOnlyKeys(value, ['schema_version', 'workflow', 'cwd', 'request', 'context']))
+    return false;
   const request = value['request'];
   if (!isRecord(request)) return false;
   if (!hasOnlyKeys(request, ['source', 'authority', 'text', 'sha256'])) return false;
@@ -131,7 +148,8 @@ function isStrictCleanCanonicalInput(value: unknown): boolean {
   const declaredSources = context['declared_sources'];
   if (!Array.isArray(declaredSources)) return false;
   for (const source of declaredSources) {
-    if (!isRecord(source) || !hasOnlyKeys(source, ['url', 'canonical_url', 'purpose', 'sha256'])) return false;
+    if (!isRecord(source) || !hasOnlyKeys(source, ['url', 'canonical_url', 'purpose', 'sha256']))
+      return false;
   }
   return true;
 }
@@ -148,6 +166,7 @@ function asFusionError(error: unknown, artifactDir: string, messageOverride?: st
     if (error.slot !== undefined) details.slot = error.slot;
     if (error.attempt !== undefined) details.attempt = error.attempt;
     if (error.budget !== undefined) details.budget = error.budget;
+    if (error.runProgress !== undefined) details.runProgress = error.runProgress;
     return new FusionError(messageOverride ?? error.message, details);
   }
   return new FusionError(messageOverride ?? errorText(error), {
@@ -157,6 +176,103 @@ function asFusionError(error: unknown, artifactDir: string, messageOverride?: st
   });
 }
 
+function fusionStageProgress(
+  manifest: FusionArtifactManifest,
+  stage: FusionStage,
+): FusionRunProgress['candidates'] {
+  const attempts = manifest.attempts.filter((attempt) => attempt.stage === stage);
+  const created = attempts.filter((attempt) => attempt.child_created).length;
+  const completed = attempts.filter(
+    (attempt) => attempt.child_created && attempt.status === 'completed',
+  ).length;
+  const failed = attempts.filter(
+    (attempt) => attempt.child_created && attempt.status === 'failed',
+  ).length;
+  const cancelled = attempts.filter(
+    (attempt) => attempt.child_created && attempt.status === 'cancelled',
+  ).length;
+  const completedByState =
+    stage === 'candidate'
+      ? completed >= 3
+      : stage === 'evaluation'
+        ? manifest.artifacts['evaluation.json'] !== undefined ||
+          manifest.state === 'evaluation_complete' ||
+          manifest.state === 'merging' ||
+          manifest.state === 'completed'
+        : manifest.artifacts['merged.md'] !== undefined || manifest.state === 'completed';
+  const progress: FusionRunProgress['candidates'] = {
+    status: completedByState ? 'completed' : created === 0 ? 'not_started' : 'incomplete',
+    attempts_recorded: attempts.length,
+    children_created: created,
+    children_completed: completed,
+    children_failed: failed,
+    children_cancelled: cancelled,
+  };
+  if (stage === 'candidate') {
+    const createdSlots = new Set(
+      attempts.flatMap((attempt) =>
+        attempt.child_created && attempt.slot !== undefined ? [attempt.slot] : [],
+      ),
+    );
+    progress.not_started_slots = 3 - createdSlots.size;
+  }
+  return progress;
+}
+
+export function buildFusionRunProgress(manifest: FusionArtifactManifest): FusionRunProgress {
+  return {
+    manifest_state: manifest.state,
+    candidates: fusionStageProgress(manifest, 'candidate'),
+    evaluation: fusionStageProgress(manifest, 'evaluation'),
+    merge: fusionStageProgress(manifest, 'merge'),
+    usage_so_far: cloneFusionUsage(manifest.usage),
+  };
+}
+
+function formatFusionRunStage(name: string, stage: FusionRunProgress['candidates']): string {
+  const notStarted =
+    stage.not_started_slots === undefined
+      ? ''
+      : `, ${String(stage.not_started_slots)} slot(s) not started`;
+  return `${name}=${stage.status} (${String(stage.children_created)} created, ${String(stage.children_completed)} completed, ${String(stage.children_failed)} failed, ${String(stage.children_cancelled)} cancelled${notStarted})`;
+}
+
+export function formatFusionRunProgress(progress: FusionRunProgress): string {
+  const usage = progress.usage_so_far;
+  const optionalUsage = [
+    usage.cacheWrite1h === undefined ? undefined : `cacheWrite1h=${String(usage.cacheWrite1h)}`,
+    usage.reasoning === undefined ? undefined : `reasoning=${String(usage.reasoning)}`,
+  ].filter((value): value is string => value !== undefined);
+  const optionalText = optionalUsage.length === 0 ? '' : `, ${optionalUsage.join(', ')}`;
+  return (
+    `Run progress from durable attempts: ${formatFusionRunStage('candidates', progress.candidates)}; ` +
+    `${formatFusionRunStage('evaluation', progress.evaluation)}; ` +
+    `${formatFusionRunStage('merge', progress.merge)}. ` +
+    `Usage so far: input=${String(usage.input)}, output=${String(usage.output)}, cacheRead=${String(usage.cacheRead)}, cacheWrite=${String(usage.cacheWrite)}${optionalText}, totalTokens=${String(usage.totalTokens)}, ` +
+    `cost.input=${String(usage.cost.input)}, cost.output=${String(usage.cost.output)}, cost.cacheRead=${String(usage.cost.cacheRead)}, cost.cacheWrite=${String(usage.cost.cacheWrite)}, cost.total=${String(usage.cost.total)}.`
+  );
+}
+
+function withRunProgress(
+  error: unknown,
+  artifactDir: string,
+  progress: FusionRunProgress,
+): FusionError {
+  const base = asFusionError(error, artifactDir);
+  const details: FusionErrorDetails = {
+    code: base.code,
+    artifactDir,
+    transient: base.transient,
+    childCreated: base.childCreated,
+    runProgress: progress,
+  };
+  if (base.stage !== undefined) details.stage = base.stage;
+  if (base.slot !== undefined) details.slot = base.slot;
+  if (base.attempt !== undefined) details.attempt = base.attempt;
+  if (base.budget !== undefined) details.budget = base.budget;
+  return new FusionError(`${base.message}\n${formatFusionRunProgress(progress)}`, details);
+}
+
 function withTerminalArtifactFailure(
   error: unknown,
   artifactDir: string,
@@ -187,7 +303,9 @@ function recordFailureInput(
       error: error.message,
       status: error.code === 'child_cancelled' ? 'cancelled' : 'failed',
       responseKind,
+      childCreated: error.childCreated,
       usage: error.usage,
+      ...(error.outputRecovery === undefined ? {} : { outputRecovery: error.outputRecovery }),
     };
     if (slot !== undefined) base.slot = slot;
     if (error.provider !== undefined) base.provider = error.provider;
@@ -207,6 +325,7 @@ function recordFailureInput(
     status:
       error instanceof FusionError && error.code === 'child_cancelled' ? 'cancelled' : 'failed',
     responseKind,
+    childCreated: error instanceof FusionError ? error.childCreated : false,
   };
   if (slot !== undefined) base.slot = slot;
   return base;
@@ -231,6 +350,7 @@ function childOptions(
   slot?: CandidateSlot,
   toolCallLogPath?: string,
   sourcePolicy?: { path: string; sha256: string },
+  candidateOutputRecoveryPath?: string,
 ): RunPiChildOptions {
   const out: RunPiChildOptions = {
     stage,
@@ -245,6 +365,8 @@ function childOptions(
   if (slot !== undefined) out.slot = slot;
   if (toolCallLogPath !== undefined) out.toolCallLogPath = toolCallLogPath;
   if (sourcePolicy !== undefined) out.sourcePolicy = sourcePolicy;
+  if (candidateOutputRecoveryPath !== undefined)
+    out.candidateOutputRecoveryPath = candidateOutputRecoveryPath;
   return out;
 }
 
@@ -276,7 +398,10 @@ function parseEvaluationAttempt(
     };
   }
   if (expectedValidationFindings !== undefined) {
-    const accountingErrors = validateEvaluationAccountsForSourceFindings(result.value, expectedValidationFindings);
+    const accountingErrors = validateEvaluationAccountsForSourceFindings(
+      result.value,
+      expectedValidationFindings,
+    );
     if (accountingErrors.length > 0) return { evaluation: undefined, errors: accountingErrors };
   }
   return { evaluation: result.value, errors: [] };
@@ -376,7 +501,11 @@ function anonymousCandidates(
 }
 
 interface ValidationSourceData {
-  candidates: readonly [AnonymousFusionCandidate, AnonymousFusionCandidate, AnonymousFusionCandidate];
+  candidates: readonly [
+    AnonymousFusionCandidate,
+    AnonymousFusionCandidate,
+    AnonymousFusionCandidate,
+  ];
   findings: readonly FusionValidationFindingRecord[];
   verified: readonly string[];
   limitations: readonly string[];
@@ -398,7 +527,11 @@ function boundedContractError(error: unknown): string {
  * an explicit limitation; two or more still fail the workflow loudly.
  */
 async function prepareValidationSourceData(
-  candidates: readonly [AnonymousFusionCandidate, AnonymousFusionCandidate, AnonymousFusionCandidate],
+  candidates: readonly [
+    AnonymousFusionCandidate,
+    AnonymousFusionCandidate,
+    AnonymousFusionCandidate,
+  ],
   anonymousMap: Record<FusionCandidateId, CandidateSlot>,
   store: FusionArtifactStore,
 ): Promise<ValidationSourceData> {
@@ -415,7 +548,10 @@ async function prepareValidationSourceData(
 
   for (const candidate of prepared) {
     try {
-      const report = parseFusionValidationCandidateReport(candidate.response, candidate.candidate_id);
+      const report = parseFusionValidationCandidateReport(
+        candidate.response,
+        candidate.candidate_id,
+      );
       findings.push(...report.findings);
       verified.push(...report.verified);
       limitations.push(...report.limitations);
@@ -435,7 +571,8 @@ async function prepareValidationSourceData(
             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.',
+            warning:
+              'Candidate output violated the bare-JSON contract; a single complete JSON fence was removed and recorded.',
           },
         });
         candidate.response = recovered.response;
@@ -506,14 +643,18 @@ function validateEvaluationAccountsForSourceFindings(
   }
   const expected = sourceFindings.map((finding) => canonicalJson(finding)).sort();
   const actual = accounting.findings.map((finding) => canonicalJson(finding)).sort();
-  if (expected.length !== actual.length || expected.some((value, index) => value !== actual[index])) {
-    errors.push('validation evaluator validation_accounting.findings must exactly equal host-assigned source findings');
+  if (
+    expected.length !== actual.length ||
+    expected.some((value, index) => value !== actual[index])
+  ) {
+    errors.push(
+      'validation evaluator validation_accounting.findings must exactly equal host-assigned source findings',
+    );
   }
   errors.push(...validateFusionFindingAccounting(accounting));
   return errors;
 }
 
-
 function resolveRunProfile(input: FusionWorkflowInput): FusionWorkflowProfile {
   if (input.profile !== undefined) return fusionWorkflowProfile(input.profile.id);
   const workflow = input.canonicalInput.workflow;
@@ -564,11 +705,17 @@ export class FusionOrchestrator {
         { code: 'orchestration_failed', childCreated: false },
       );
     }
-    if (profile.contextKind === 'clean_task' && !isStrictCleanCanonicalInput(input.canonicalInput)) {
-      throw new FusionError('clean-task fusion input must not carry parent context fields and must match the strict clean canonical shape', {
-        code: 'orchestration_failed',
-        childCreated: false,
-      });
+    if (
+      profile.contextKind === 'clean_task' &&
+      !isStrictCleanCanonicalInput(input.canonicalInput)
+    ) {
+      throw new FusionError(
+        'clean-task fusion input must not carry parent context fields and must match the strict clean canonical shape',
+        {
+          code: 'orchestration_failed',
+          childCreated: false,
+        },
+      );
     }
     const candidateCapability = assertWorkflowCapability(profile, input.candidateCapability);
     const storeOptions: CreateFusionArtifactStoreOptions = {
@@ -589,16 +736,22 @@ export class FusionOrchestrator {
     try {
       serializedParsed = parseJsonText(input.canonicalInputSerialized);
     } catch (error) {
-      throw new FusionError(`fusion canonical input artifact is not valid JSON: ${errorText(error)}`, {
-        code: 'orchestration_failed',
-        childCreated: false,
-      });
+      throw new FusionError(
+        `fusion canonical input artifact is not valid JSON: ${errorText(error)}`,
+        {
+          code: 'orchestration_failed',
+          childCreated: false,
+        },
+      );
     }
     if (canonicalJson(serializedParsed) !== canonicalJson(input.canonicalInput)) {
-      throw new FusionError('fusion canonical input serialized bytes do not match canonical input object', {
-        code: 'orchestration_failed',
-        childCreated: false,
-      });
+      throw new FusionError(
+        'fusion canonical input serialized bytes do not match canonical input object',
+        {
+          code: 'orchestration_failed',
+          childCreated: false,
+        },
+      );
     }
     const store = await this.createArtifactStore(storeOptions);
     input.onProgress?.({ type: 'state', state: 'initializing' });
@@ -608,10 +761,13 @@ export class FusionOrchestrator {
       await store.writeCanonicalInput(input.canonicalInputSerialized);
       if (inputContextKind === 'session_projection') {
         if (input.contextLedger === undefined) {
-          throw new FusionError('session-projection fusion input requires an omission ledger artifact', {
-            code: 'orchestration_failed',
-            childCreated: false,
-          });
+          throw new FusionError(
+            'session-projection fusion input requires an omission ledger artifact',
+            {
+              code: 'orchestration_failed',
+              childCreated: false,
+            },
+          );
         }
         await store.writeContextLedger(input.contextLedger);
       } else if (input.contextLedger !== undefined) {
@@ -649,6 +805,17 @@ export class FusionOrchestrator {
           error: 'fusion budget utilization warning',
         });
       }
+      await input.onReady?.({
+        runId: store.runId,
+        artifactDir: store.artifactDir,
+        artifactDirAbs: store.artifactDirAbs,
+      });
+      if (input.signal?.aborted === true) {
+        throw new FusionError('fusion run cancelled before launch', {
+          code: 'child_cancelled',
+          childCreated: false,
+        });
+      }
       await store.transition('candidates_running');
       input.onProgress?.({ type: 'state', state: 'candidates_running' });
       const candidateResults = await this.runCandidates(
@@ -667,9 +834,10 @@ export class FusionOrchestrator {
       // 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 validationData =
+        profile.id === 'validate'
+          ? await prepareValidationSourceData(shuffled.candidates, shuffled.map, store)
+          : undefined;
       const evaluationCandidates = validationData?.candidates ?? shuffled.candidates;
       const blindInput = buildBlindEvaluationInput(
         input.canonicalInput,
@@ -715,7 +883,12 @@ export class FusionOrchestrator {
         'md',
       );
       addFusionUsage(usage, merged.usage);
-      await store.recordChildAttempt({ result: merged, systemPrompt: profile.mergerSystemPrompt, prompt: mergePrompt, responseKind: 'md' });
+      await store.recordChildAttempt({
+        result: merged,
+        systemPrompt: profile.mergerSystemPrompt,
+        prompt: mergePrompt,
+        responseKind: 'md',
+      });
       await this.recordCalibrationObservation(
         input,
         store,
@@ -731,52 +904,67 @@ export class FusionOrchestrator {
       if (profile.id === 'validate') {
         const accounting = evaluation.validation_accounting;
         if (accounting === undefined) {
-          throw new FusionError('fusion_validate evaluation completed without validation accounting', {
-            code: 'evaluation_invalid',
-            stage: 'merge',
-          });
+          throw new FusionError(
+            'fusion_validate evaluation completed without validation accounting',
+            {
+              code: 'evaluation_invalid',
+              stage: 'merge',
+            },
+          );
         }
         finalMergedText = renderValidatedFusionValidationReport(accounting, validationData);
       }
-      if (finalMergedText !== merged.text) assertChildOutputWithinContract('merge', finalMergedText);
-      await store.writeMerged(finalMergedText);
+      if (finalMergedText !== merged.text)
+        assertChildOutputWithinContract('merge', finalMergedText);
+      const mergedRef = await store.writeMerged(finalMergedText);
       await store.setUsage(usage);
-      await store.transition('completed');
-      input.onProgress?.({ type: 'completed', runId: store.runId, artifactDir: store.artifactDir });
-      return {
-        mergedText: finalMergedText,
-        details: {
-          schema_version: FUSION_RESULT_SCHEMA_VERSION,
-          run_id: store.runId,
-          workflow: profile.id,
-          source: input.source,
-          status: 'completed',
-          artifact_dir: store.artifactDir,
-          context: { kind: inputContextKind, policy_id: input.canonicalInput.context?.policy_id ?? 'fusion-session-projection-v1' },
-          tool_policy: { candidate_tools: profile.candidateTools, evaluation_tools: [], merge_tools: [] },
-          models: store.snapshot().models,
-          evaluator_attempts: store
-            .snapshot()
-            .attempts.filter((attempt) => attempt.stage === 'evaluation').length,
-          usage,
-          budget: {
-            policy_id: FUSION_BUDGET_POLICY.id,
-            calibration_version: budgetPlan.policy.calibration_version,
-            route_table: budget.routes,
-            rate_sources: budget.resultRateSources,
-            unknown_provider_warnings: budget.unknownProviderWarnings,
-            calibration_warnings: calibrationWarnings,
-          },
+      const details: FusionRunResult['details'] = {
+        schema_version: FUSION_RESULT_SCHEMA_VERSION,
+        run_id: store.runId,
+        workflow: profile.id,
+        source: input.source,
+        status: 'completed',
+        artifact_dir: store.artifactDir,
+        context: {
+          kind: inputContextKind,
+          policy_id: input.canonicalInput.context?.policy_id ?? 'fusion-session-projection-v1',
+        },
+        tool_policy: {
+          candidate_tools: profile.candidateTools,
+          evaluation_tools: [],
+          merge_tools: [],
+        },
+        models: store.snapshot().models,
+        evaluator_attempts: store
+          .snapshot()
+          .attempts.filter((attempt) => attempt.stage === 'evaluation').length,
+        usage,
+        budget: {
+          policy_id: FUSION_BUDGET_POLICY.id,
+          calibration_version: budgetPlan.policy.calibration_version,
+          route_table: budget.routes,
+          rate_sources: budget.resultRateSources,
+          unknown_provider_warnings: budget.unknownProviderWarnings,
+          calibration_warnings: calibrationWarnings,
         },
       };
+      await store.writeCommittedResult(mergedRef, details);
+      await store.transition('completed');
+      input.onProgress?.({ type: 'completed', runId: store.runId, artifactDir: store.artifactDir });
+      return { mergedText: finalMergedText, details };
     } catch (error) {
       const cancelled =
         input.signal?.aborted === true ||
         (error instanceof FusionError && error.code === 'child_cancelled');
-      const message = errorText(error);
+      let terminalError: FusionError;
       try {
         await store.setUsage(usage);
-        await store.writeError(cancelled ? 'cancelled' : 'failed', message);
+        terminalError = withRunProgress(
+          error,
+          store.artifactDir,
+          buildFusionRunProgress(store.snapshot()),
+        );
+        await store.writeError(cancelled ? 'cancelled' : 'failed', terminalError.message);
       } catch (artifactError) {
         throw withTerminalArtifactFailure(error, store.artifactDir, artifactError);
       }
@@ -785,17 +973,17 @@ export class FusionOrchestrator {
           type: 'cancelled',
           runId: store.runId,
           artifactDir: store.artifactDir,
-          reason: message,
+          reason: terminalError.message,
         });
       } else {
         input.onProgress?.({
           type: 'failed',
           runId: store.runId,
           artifactDir: store.artifactDir,
-          error: message,
+          error: terminalError.message,
         });
       }
-      throw asFusionError(error, store.artifactDir);
+      throw terminalError;
     }
   }
 
@@ -842,7 +1030,12 @@ export class FusionOrchestrator {
           slot,
           profile.id === 'validate' ? 'txt' : 'md',
         ).then(async (result) => {
-          await store.recordChildAttempt({ result, systemPrompt, prompt, responseKind: profile.id === 'validate' ? 'txt' : 'md' });
+          await store.recordChildAttempt({
+            result,
+            systemPrompt,
+            prompt,
+            responseKind: profile.id === 'validate' ? 'txt' : 'md',
+          });
           await this.recordCalibrationObservation(
             input,
             store,
@@ -854,12 +1047,12 @@ export class FusionOrchestrator {
             result,
             slot,
           );
-          // The response is durable before the contract check, so an oversized
-          // answer is preserved as evidence rather than lost.
-          assertChildOutputWithinContract('candidate', result.text);
-          completed += 1;
+          // The response and its consumed usage are durable before the contract
+          // check, so an oversized answer is preserved and accounted rather than lost.
           addFusionUsage(usage, result.usage);
           await store.setUsage(usage);
+          assertChildOutputWithinContract('candidate', result.text);
+          completed += 1;
           input.onProgress?.({ type: 'candidate_completed', slot, completed, total: 3 });
           return { slot, result };
         });
@@ -1054,8 +1247,10 @@ export class FusionOrchestrator {
           ? store.childToolCallLogPath(stage, slot, logicalAttempt)
           : undefined;
       const sourcePolicy =
-        capability === 'research'
-          ? store.sourcePolicyLaunchReference()
+        capability === 'research' ? store.sourcePolicyLaunchReference() : undefined;
+      const candidateOutputRecoveryPath =
+        stage === 'candidate' && slot !== undefined
+          ? store.childOutputRecoveryPath(slot, logicalAttempt, responseKind)
           : undefined;
       try {
         return await this.childRunner(
@@ -1071,13 +1266,22 @@ export class FusionOrchestrator {
             slot,
             toolCallLogPath,
             sourcePolicy,
+            candidateOutputRecoveryPath,
           ),
         );
       } catch (error) {
         if (!signal.aborted && retryableSpawn(error, launchTry) && launchTry === 1) continue;
         addFailedChildUsage(usage, error);
         await store.recordFailedAttempt(
-          recordFailureInput(error, stage, slot, logicalAttempt, systemPrompt, userPrompt, responseKind),
+          recordFailureInput(
+            error,
+            stage,
+            slot,
+            logicalAttempt,
+            systemPrompt,
+            userPrompt,
+            responseKind,
+          ),
         );
         await store.setUsage(usage);
         throw error;

package/src/core/fusion/output-contract.ts

@@ -0,0 +1,34 @@
+import { FusionError, type FusionStage } from './types.js';
+
+/** Hard output contracts are measured over the JSON rendering embedded downstream. */
+export const FUSION_CANDIDATE_MAX_OUTPUT_BYTES = 48 * 1024;
+export const FUSION_EVALUATION_MAX_OUTPUT_BYTES = 64 * 1024;
+export const FUSION_MERGE_MAX_OUTPUT_BYTES = 64 * 1024;
+export const FUSION_DIAGNOSTICS_MAX_BYTES = 8 * 1024;
+
+const FUSION_CANDIDATE_MAX_OUTPUT_BYTES_DISPLAY =
+  FUSION_CANDIDATE_MAX_OUTPUT_BYTES.toLocaleString('en-US');
+
+export const FUSION_CANDIDATE_OUTPUT_CONTRACT_INSTRUCTION = `Your complete response must be at most ${FUSION_CANDIDATE_MAX_OUTPUT_BYTES_DISPLAY} JSON-rendered UTF-8 bytes. If the requested scope cannot fit, prioritize the most important findings and explicitly state limitations.`;
+
+export const FUSION_CANDIDATE_OUTPUT_COMPRESSION_PROMPT = `Compress and restructure only your immediately previous answer so the complete replacement is at most ${FUSION_CANDIDATE_MAX_OUTPUT_BYTES_DISPLAY} JSON-rendered UTF-8 bytes. Do not investigate again, do not use tools, and do not add new evidence. Preserve the most important findings and evidence already present, state material limitations, obey the original output format, and output only the replacement answer.`;
+
+export function fusionJsonRenderedTextBytes(text: string): number {
+  return Buffer.byteLength(JSON.stringify(text), 'utf8');
+}
+
+export function fusionOutputContractBytes(stage: FusionStage): number {
+  if (stage === 'candidate') return FUSION_CANDIDATE_MAX_OUTPUT_BYTES;
+  if (stage === 'evaluation') return FUSION_EVALUATION_MAX_OUTPUT_BYTES;
+  return FUSION_MERGE_MAX_OUTPUT_BYTES;
+}
+
+export function assertChildOutputWithinContract(stage: FusionStage, text: string): void {
+  const bytes = fusionJsonRenderedTextBytes(text);
+  const allowed = fusionOutputContractBytes(stage);
+  if (bytes <= allowed) return;
+  throw new FusionError(
+    `fusion ${stage} response is ${String(bytes)} JSON-rendered bytes, exceeding the ${String(allowed)}-byte output contract for that stage; the response is preserved in the run artifacts and is not forwarded or truncated`,
+    { code: 'child_output_cap', stage, childCreated: true },
+  );
+}