pi-background-tasks 2.1.3 → 2.1.4

package/src/core/fusion/result-package.ts

@@ -1,17 +1,35 @@
-import { readFile } from 'node:fs/promises';
+import { lstat, readFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { sha256Buffer } from '../attested-pi-run.js';
+import { canonicalJson, sha256Buffer } from '../attested-pi-run.js';
 import { parseJsonText, type JsonObject } from '../common.js';
+import {
+  FUSION_FAILURE_SUMMARY_ATTEMPT_CAP,
+  FUSION_FAILURE_SUMMARY_EVIDENCE_CAP,
+  FUSION_FAILURE_SUMMARY_INLINE_MESSAGE_BYTES,
+  FUSION_FAILURE_SUMMARY_MAX_BYTES,
+  assertFusionArtifactBasename,
+  buildFusionRunProgress,
+} from './artifacts.js';
 import {
   FUSION_COMMITTED_RESULT_SCHEMA_VERSION,
+  FUSION_FAILURE_SUMMARY_SCHEMA_VERSION,
+  FUSION_LEGACY_MANIFEST_SCHEMA_VERSION,
   FUSION_MANIFEST_SCHEMA_VERSION,
   FUSION_RESULT_SCHEMA_VERSION,
   FusionError,
   type FusionArtifactRef,
+  type FusionFailureAttemptMetadata,
+  type FusionFailureEvidenceArtifact,
+  type FusionFailureList,
+  type FusionFailureResultView,
+  type FusionFailureSummaryV1,
   type FusionResultDetails,
   type FusionRunResult,
   type FusionUsage,
   type FusionWorkflowId,
+  type FusionRunProgress,
+  type FusionSource,
+  type FusionStage,
 } from './types.js';
 
 const SHA256_PATTERN = /^sha256:[0-9a-f]{64}$/u;
@@ -45,7 +63,10 @@ function artifactRef(value: unknown, label: string, artifactDir: string): Fusion
   const path = value['path'];
   const byteLength = value['byte_length'];
   const sha256 = value['sha256'];
-  if (typeof path !== 'string' || path.length === 0 || path.includes('/') || path.includes('\\')) {
+  if (typeof path !== 'string') fail(`${label}.path is invalid`, artifactDir);
+  try {
+    assertFusionArtifactBasename(path);
+  } catch {
     fail(`${label}.path is invalid`, artifactDir);
   }
   if (!Number.isSafeInteger(byteLength) || Number(byteLength) < 0) {
@@ -308,6 +329,31 @@ async function readUtf8(
   return { bytes, text };
 }
 
+/** Failure retrieval has an additional bounded, no-symlink evidence-file policy. */
+async function readFailureUtf8(
+  path: string,
+  label: string,
+  artifactDir: string,
+  maxBytes: number,
+): Promise<{ bytes: Buffer; text: string }> {
+  try {
+    const metadata = await lstat(path);
+    if (!metadata.isFile() || metadata.isSymbolicLink()) {
+      fail(`${label} is not a regular artifact file`, artifactDir);
+    }
+    if (metadata.size > maxBytes) fail(`${label} exceeds its bounded artifact size`, artifactDir);
+  } catch (error) {
+    if (error instanceof FusionError) throw error;
+    fail(
+      `${label} is unreadable: ${error instanceof Error ? error.message : String(error)}`,
+      artifactDir,
+    );
+  }
+  const file = await readUtf8(path, label, artifactDir);
+  if (file.bytes.length > maxBytes) fail(`${label} exceeds its bounded artifact size`, artifactDir);
+  return file;
+}
+
 export interface ReadFusionCommittedResultOptions {
   artifactDirAbs: string;
   artifactDir: string;
@@ -410,3 +456,504 @@ export async function readFusionCommittedResult(
   }
   return { mergedText: mergedFile.text, details };
 }
+
+// The public tool adds a small task envelope and text receipt around this view.
+// Keep the verified details below 8 KiB even after that model-visible envelope.
+const FAILURE_VIEW_MAX_BYTES = 6 * 1024;
+const FAILURE_CODES = new Set([
+  'config_invalid', 'config_conflict', 'model_unavailable', 'context_capture_failed',
+  'context_policy_unsupported_block', 'prompt_budget_exceeded_forecast',
+  'prompt_budget_exceeded_measured', 'model_capacity_unknown', 'child_spawn_failed',
+  'child_stdin_failed', 'child_event_invalid', 'child_exit_failed',
+  'child_runtime_limit_exceeded', 'child_runtime_payload_invalid',
+  'child_cache_policy_invalid', 'child_timeout', 'child_output_cap', 'child_cancelled',
+  'evaluation_invalid', 'artifact_error', 'state_transition_invalid', 'orchestration_failed',
+]);
+const FAILURE_REMEDIATION_IDS = new Set([
+  'inspect_manifest_bound_evidence', 'inspect_terminal_error', 'split_or_reduce_work',
+  'retry_same_route_after_operator_review',
+]);
+const FAILURE_CLASSIFICATIONS = new Set([
+  'complete_stage_output', 'partial_stage_output', 'oversized_original',
+  'empty_rejected_output', 'evidence_only',
+]);
+
+interface TrustedFailureManifest {
+  schemaVersion: string;
+  source: FusionSource;
+  state: 'failed' | 'cancelled';
+  usage: FusionUsage;
+  artifacts: Readonly<Record<string, FusionArtifactRef>>;
+  attempts: readonly FusionFailureAttemptMetadata[];
+  classifications: Readonly<Record<string, FusionFailureEvidenceArtifact['classification']>>;
+  error?: string | undefined;
+}
+
+function failureUnavailable(
+  state: 'failed' | 'cancelled',
+  status: 'unavailable' | 'integrity_failed',
+): FusionFailureResultView {
+  return {
+    schema_version: FUSION_FAILURE_SUMMARY_SCHEMA_VERSION,
+    summary_status: status,
+    terminal_state: state,
+    answer: { present: false, reason: 'run_did_not_commit' },
+    summary_unavailable_reason: status === 'unavailable' ? 'manifest_untrusted' : 'summary_integrity_failed',
+  };
+}
+
+function failureString(value: unknown, label: string): string {
+  if (typeof value !== 'string') throw new Error(`${label} must be a string`);
+  return value;
+}
+
+function failureInteger(value: unknown, label: string): number {
+  if (!Number.isSafeInteger(value) || Number(value) < 0)
+    throw new Error(`${label} must be a nonnegative integer`);
+  return Number(value);
+}
+
+function compareFailureText(left: string, right: string): number {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+function failureStage(value: unknown, label: string): FusionStage {
+  if (value === 'candidate' || value === 'evaluation' || value === 'merge') return value;
+  throw new Error(`${label} is invalid`);
+}
+
+function failureUsage(value: unknown, artifactDir: string): FusionUsage {
+  return usage(value, artifactDir);
+}
+
+function failureRef(value: unknown, label: string, artifactDir: string): FusionArtifactRef {
+  return artifactRef(value, label, artifactDir);
+}
+
+function sameFailureRef(left: FusionArtifactRef, right: FusionArtifactRef): boolean {
+  return left.path === right.path && left.byte_length === right.byte_length && left.sha256 === right.sha256;
+}
+
+function trustedFailureManifest(
+  value: unknown,
+  options: ReadFusionCommittedResultOptions,
+): TrustedFailureManifest {
+  if (!isRecord(value)) throw new Error('manifest must be an object');
+  const schemaVersion = value['schema_version'];
+  if (schemaVersion !== FUSION_MANIFEST_SCHEMA_VERSION && schemaVersion !== FUSION_LEGACY_MANIFEST_SCHEMA_VERSION)
+    throw new Error('manifest schema version mismatch');
+  if (value['run_id'] !== options.runId || value['workflow'] !== options.workflow)
+    throw new Error('manifest identity mismatch');
+  const state = value['state'];
+  if (state !== 'failed' && state !== 'cancelled') throw new Error('manifest is not failed or cancelled');
+  const source = value['source'];
+  if (source !== 'command' && source !== 'tool') throw new Error('manifest source is invalid');
+  const artifactsValue = value['artifacts'];
+  if (!isRecord(artifactsValue)) throw new Error('manifest artifacts are invalid');
+  const artifacts: Record<string, FusionArtifactRef> = {};
+  for (const [name, ref] of Object.entries(artifactsValue)) {
+    assertFusionArtifactBasename(name);
+    const checked = failureRef(ref, `manifest artifact ${name}`, options.artifactDir);
+    if (checked.path !== name) throw new Error('manifest artifact key/ref divergence');
+    artifacts[name] = checked;
+  }
+  const attemptsValue = value['attempts'];
+  if (!Array.isArray(attemptsValue)) throw new Error('manifest attempts are invalid');
+  const attempts: FusionFailureAttemptMetadata[] = [];
+  const classifications: Record<string, FusionFailureEvidenceArtifact['classification']> = {};
+  const attemptArtifact = (entry: unknown, label: string): string | undefined => {
+    if (entry === undefined) return undefined;
+    const name = failureString(entry, label);
+    assertFusionArtifactBasename(name);
+    if (artifacts[name] === undefined) throw new Error(`${label} is not manifest-bound`);
+    return name;
+  };
+  for (const attemptValue of attemptsValue) {
+    if (!isRecord(attemptValue)) throw new Error('manifest attempt is invalid');
+    const metadata = failureAttempt({
+      stage: attemptValue['stage'], slot: attemptValue['slot'], attempt: attemptValue['attempt'],
+      status: attemptValue['status'], child_created: attemptValue['child_created'],
+    });
+    attempts.push(metadata);
+    const response = attemptArtifact(attemptValue['response_path'], 'manifest response_path');
+    if (response !== undefined) {
+      const responseRef = artifacts[response];
+      if (responseRef === undefined) throw new Error('manifest response_path is not manifest-bound');
+      classifications[response] =
+        responseRef.byte_length === 0 && metadata.status !== 'completed'
+          ? 'empty_rejected_output'
+          : 'complete_stage_output';
+    }
+    const partial = attemptArtifact(
+      attemptValue['partial_response_path'],
+      'manifest partial_response_path',
+    );
+    if (partial !== undefined) classifications[partial] = 'partial_stage_output';
+    const recovery = attemptValue['output_recovery'];
+    if (recovery !== undefined) {
+      if (!isRecord(recovery)) throw new Error('manifest output_recovery is invalid');
+      const original = attemptArtifact(
+        recovery['original_response_path'],
+        'manifest output_recovery.original_response_path',
+      );
+      if (original === undefined) throw new Error('manifest output recovery has no original response');
+      classifications[original] = 'oversized_original';
+    }
+  }
+  attempts.sort((left, right) =>
+    compareFailureText(left.stage, right.stage) ||
+    (left.slot ?? 0) - (right.slot ?? 0) ||
+    left.attempt - right.attempt,
+  );
+  const manifestUsage = failureUsage(value['usage'], options.artifactDir);
+  const error = value['error'];
+  if (error !== undefined && typeof error !== 'string') throw new Error('manifest error is invalid');
+  return { schemaVersion, source, state, usage: manifestUsage, artifacts, attempts, classifications, ...(error === undefined ? {} : { error }) };
+}
+
+function failureMessage(value: unknown): FusionFailureSummaryV1['failure']['message'] {
+  if (!isRecord(value)) throw new Error('failure message is invalid');
+  assertOnlyKeys(value, ['byte_length', 'sha256', 'inline_message', 'omission_reason'], 'failure message', 'failure-summary.json');
+  const byteLength = failureInteger(value['byte_length'], 'failure message byte_length');
+  const sha256 = failureString(value['sha256'], 'failure message sha256');
+  if (!SHA256_PATTERN.test(sha256)) throw new Error('failure message sha256 is invalid');
+  const inline = value['inline_message'];
+  const omission = value['omission_reason'];
+  if ((inline === undefined) === (omission === undefined)) throw new Error('failure message must have exactly one representation');
+  if (inline !== undefined) {
+    if (
+      typeof inline !== 'string' ||
+      byteLength > FUSION_FAILURE_SUMMARY_INLINE_MESSAGE_BYTES ||
+      Buffer.byteLength(inline, 'utf8') !== byteLength ||
+      sha256Buffer(Buffer.from(inline, 'utf8')) !== sha256
+    ) {
+      throw new Error('failure inline message does not match its metadata');
+    }
+    return { byte_length: byteLength, sha256, inline_message: inline };
+  }
+  if (omission !== 'exceeds_inline_message_bytes_cap')
+    throw new Error('failure message omission reason is invalid');
+  return { byte_length: byteLength, sha256, omission_reason: omission };
+}
+
+function failureList<T>(
+  value: unknown,
+  label: string,
+  cap: number,
+  parseEntry: (entry: unknown) => T,
+): FusionFailureList<T> {
+  if (!isRecord(value)) throw new Error(`${label} is invalid`);
+  assertOnlyKeys(value, ['listed', 'omitted_count'], label, 'failure-summary.json');
+  if (!Array.isArray(value['listed']) || value['listed'].length > cap)
+    throw new Error(`${label}.listed is invalid`);
+  return {
+    listed: value['listed'].map(parseEntry),
+    omitted_count: failureInteger(value['omitted_count'], `${label}.omitted_count`),
+  };
+}
+
+function failureAttempt(value: unknown): FusionFailureAttemptMetadata {
+  if (!isRecord(value)) throw new Error('failure attempt is invalid');
+  assertOnlyKeys(value, ['stage', 'slot', 'attempt', 'status', 'child_created'], 'failure attempt', 'failure-summary.json');
+  const stage = failureStage(value['stage'], 'failure attempt stage');
+  const slot = value['slot'];
+  if (slot !== undefined && slot !== 1 && slot !== 2 && slot !== 3)
+    throw new Error('failure attempt slot is invalid');
+  if ((stage === 'candidate') !== (slot !== undefined))
+    throw new Error('failure attempt stage/slot is inconsistent');
+  const status = value['status'];
+  if (status !== 'completed' && status !== 'failed' && status !== 'cancelled') throw new Error('failure attempt status is invalid');
+  if (typeof value['child_created'] !== 'boolean') throw new Error('failure attempt child_created is invalid');
+  const attempt = failureInteger(value['attempt'], 'failure attempt number');
+  if (attempt === 0) throw new Error('failure attempt number must be positive');
+  return { stage, ...(slot === undefined ? {} : { slot }), attempt, status, child_created: value['child_created'] };
+}
+
+function failureEvidence(
+  value: unknown,
+  manifest: TrustedFailureManifest,
+  artifactDir: string,
+): FusionFailureEvidenceArtifact {
+  if (!isRecord(value)) throw new Error('failure evidence row is invalid');
+  assertOnlyKeys(value, ['name', 'classification', 'ref'], 'failure evidence row', artifactDir);
+  const name = failureString(value['name'], 'failure evidence name');
+  assertFusionArtifactBasename(name);
+  const classification = value['classification'];
+  if (typeof classification !== 'string' || !FAILURE_CLASSIFICATIONS.has(classification))
+    throw new Error('failure evidence classification is invalid');
+  const ref = failureRef(value['ref'], 'failure evidence ref', artifactDir);
+  const manifestRef = manifest.artifacts[name];
+  if (manifestRef === undefined || !sameFailureRef(ref, manifestRef))
+    throw new Error('failure evidence ref diverges from manifest');
+  const expectedClassification = manifest.classifications[name] ?? 'evidence_only';
+  if (classification !== expectedClassification) throw new Error('failure evidence classification diverges from manifest');
+  return { name, classification: expectedClassification, ref };
+}
+
+function failureProgress(value: unknown, manifest: TrustedFailureManifest, artifactDir: string): FusionRunProgress {
+  if (!isRecord(value)) throw new Error('failure progress is invalid');
+  assertOnlyKeys(value, ['manifest_state', 'candidates', 'evaluation', 'merge', 'usage_so_far'], 'failure progress', artifactDir);
+  if (value['manifest_state'] !== manifest.state) throw new Error('failure progress state diverges from manifest');
+  const stage = (entry: unknown, label: string, candidates: boolean): FusionRunProgress['candidates'] => {
+    if (!isRecord(entry)) throw new Error(`${label} is invalid`);
+    assertOnlyKeys(entry, ['status', 'attempts_recorded', 'children_created', 'children_completed', 'children_failed', 'children_cancelled', 'not_started_slots'], label, artifactDir);
+    const status = entry['status'];
+    if (status !== 'not_started' && status !== 'incomplete' && status !== 'completed') throw new Error(`${label}.status is invalid`);
+    const notStarted = entry['not_started_slots'];
+    if (candidates ? !Number.isSafeInteger(notStarted) || Number(notStarted) < 0 || Number(notStarted) > 3 : notStarted !== undefined)
+      throw new Error(`${label}.not_started_slots is invalid`);
+    return {
+      status,
+      attempts_recorded: failureInteger(entry['attempts_recorded'], `${label}.attempts_recorded`),
+      children_created: failureInteger(entry['children_created'], `${label}.children_created`),
+      children_completed: failureInteger(entry['children_completed'], `${label}.children_completed`),
+      children_failed: failureInteger(entry['children_failed'], `${label}.children_failed`),
+      children_cancelled: failureInteger(entry['children_cancelled'], `${label}.children_cancelled`),
+      ...(candidates ? { not_started_slots: Number(notStarted) } : {}),
+    };
+  };
+  const usageSoFar = failureUsage(value['usage_so_far'], artifactDir);
+  if (canonicalJson(usageSoFar) !== canonicalJson(manifest.usage)) throw new Error('failure progress usage diverges from manifest');
+  return { manifest_state: manifest.state, candidates: stage(value['candidates'], 'failure candidates', true), evaluation: stage(value['evaluation'], 'failure evaluation', false), merge: stage(value['merge'], 'failure merge', false), usage_so_far: usageSoFar };
+}
+
+function parseFailureSummary(
+  value: unknown,
+  manifest: TrustedFailureManifest,
+  options: ReadFusionCommittedResultOptions,
+): FusionFailureSummaryV1 {
+  if (!isRecord(value)) throw new Error('failure summary must be an object');
+  assertOnlyKeys(value, ['schema_version', 'run_id', 'workflow', 'source', 'terminal_state', 'created_at', 'answer', 'failure', 'progress', 'usage_so_far', 'attempts', 'evidence_artifacts', 'remediation_ids'], 'failure summary', options.artifactDir);
+  if (value['schema_version'] !== FUSION_FAILURE_SUMMARY_SCHEMA_VERSION || value['run_id'] !== options.runId || value['workflow'] !== options.workflow || value['source'] !== manifest.source || value['terminal_state'] !== manifest.state || typeof value['created_at'] !== 'string')
+    throw new Error('failure summary identity is invalid');
+  const answer = value['answer'];
+  if (!isRecord(answer) || answer['present'] !== false || answer['reason'] !== 'run_did_not_commit') throw new Error('failure summary answer assertion is invalid');
+  const failure = value['failure'];
+  if (!isRecord(failure)) throw new Error('failure summary failure metadata is invalid');
+  assertOnlyKeys(failure, ['code', 'stage', 'slot', 'attempt', 'child_created', 'message'], 'failure metadata', options.artifactDir);
+  const code = failure['code'];
+  if (code !== null && (typeof code !== 'string' || !FAILURE_CODES.has(code))) throw new Error('failure code is invalid');
+  const stageValue = failure['stage'];
+  const stage = stageValue === undefined ? undefined : failureStage(stageValue, 'failure stage');
+  const slot = failure['slot'];
+  if (slot !== undefined && slot !== 1 && slot !== 2 && slot !== 3) throw new Error('failure slot is invalid');
+  if (failure['attempt'] !== undefined) failureInteger(failure['attempt'], 'failure attempt');
+  if (typeof failure['child_created'] !== 'boolean') throw new Error('failure child_created is invalid');
+  const progress = failureProgress(value['progress'], manifest, options.artifactDir);
+  const expectedProgress = buildFusionRunProgress(manifest);
+  if (canonicalJson(progress) !== canonicalJson(expectedProgress))
+    throw new Error('failure progress diverges from durable attempts');
+  const usageSoFar = failureUsage(value['usage_so_far'], options.artifactDir);
+  if (canonicalJson(usageSoFar) !== canonicalJson(manifest.usage))
+    throw new Error('summary usage diverges from manifest');
+  const attempts = failureList(
+    value['attempts'],
+    'failure attempts',
+    FUSION_FAILURE_SUMMARY_ATTEMPT_CAP,
+    failureAttempt,
+  );
+  const expectedAttempts = manifest.attempts;
+  const expectedAttemptListedCount = Math.min(
+    expectedAttempts.length,
+    FUSION_FAILURE_SUMMARY_ATTEMPT_CAP,
+  );
+  if (
+    attempts.listed.length !== expectedAttemptListedCount ||
+    attempts.omitted_count !== expectedAttempts.length - expectedAttemptListedCount ||
+    canonicalJson(attempts.listed) !==
+      canonicalJson(
+        expectedAttempts.filter((_attempt, index) => index < expectedAttemptListedCount),
+      )
+  ) {
+    throw new Error('failure attempt metadata diverges from manifest');
+  }
+  const evidence = failureList(
+    value['evidence_artifacts'],
+    'failure evidence artifacts',
+    FUSION_FAILURE_SUMMARY_EVIDENCE_CAP,
+    (entry) => failureEvidence(entry, manifest, options.artifactDir),
+  );
+  const expectedEvidence = Object.entries(manifest.artifacts)
+    .filter(([name]) => name !== 'failure-summary.json')
+    .map(([name, ref]) => ({ name, classification: manifest.classifications[name] ?? 'evidence_only', ref }))
+    .sort((left, right) => compareFailureText(left.name, right.name));
+  const expectedEvidenceListedCount = Math.min(
+    expectedEvidence.length,
+    FUSION_FAILURE_SUMMARY_EVIDENCE_CAP,
+  );
+  if (
+    evidence.listed.length !== expectedEvidenceListedCount ||
+    evidence.omitted_count !== expectedEvidence.length - expectedEvidenceListedCount ||
+    canonicalJson(evidence.listed) !==
+      canonicalJson(
+        expectedEvidence.filter((_evidence, index) => index < expectedEvidenceListedCount),
+      )
+  ) {
+    throw new Error('failure evidence metadata diverges from manifest');
+  }
+  const remediationIds = value['remediation_ids'];
+  const expectedRemediationIds = [
+    'inspect_manifest_bound_evidence',
+    'inspect_terminal_error',
+    'split_or_reduce_work',
+    'retry_same_route_after_operator_review',
+  ];
+  if (
+    !Array.isArray(remediationIds) ||
+    !remediationIds.every((id) => typeof id === 'string' && FAILURE_REMEDIATION_IDS.has(id)) ||
+    canonicalJson(remediationIds) !== canonicalJson(expectedRemediationIds)
+  ) {
+    throw new Error('failure remediation ids are invalid');
+  }
+  const terminalMessage = failureMessage(failure['message']);
+  if (manifest.error === undefined) throw new Error('manifest terminal error is unavailable');
+  const manifestErrorBytes = Buffer.from(manifest.error, 'utf8');
+  const expectedMessage = {
+    byte_length: manifestErrorBytes.length,
+    sha256: sha256Buffer(manifestErrorBytes),
+    ...(manifestErrorBytes.length <= FUSION_FAILURE_SUMMARY_INLINE_MESSAGE_BYTES
+      ? { inline_message: manifest.error }
+      : { omission_reason: 'exceeds_inline_message_bytes_cap' as const }),
+  };
+  if (canonicalJson(terminalMessage) !== canonicalJson(expectedMessage))
+    throw new Error('failure message diverges from manifest terminal error');
+  return {
+    schema_version: FUSION_FAILURE_SUMMARY_SCHEMA_VERSION, run_id: options.runId, workflow: options.workflow,
+    source: manifest.source, terminal_state: manifest.state, created_at: value['created_at'],
+    answer: { present: false, reason: 'run_did_not_commit' },
+    failure: { code: code as FusionFailureSummaryV1['failure']['code'], ...(stage === undefined ? {} : { stage }), ...(slot === undefined ? {} : { slot }), ...(failure['attempt'] === undefined ? {} : { attempt: Number(failure['attempt']) }), child_created: failure['child_created'], message: terminalMessage },
+    progress, usage_so_far: usageSoFar, attempts, evidence_artifacts: evidence,
+    remediation_ids: [...remediationIds] as FusionFailureSummaryV1['remediation_ids'],
+  };
+}
+
+interface FailureViewSource {
+  terminal_state: Exclude<FusionFailureResultView['terminal_state'], 'completed'>;
+  failure?: FusionFailureResultView['failure'] | undefined;
+  progress: FusionRunProgress;
+  usage_so_far: FusionUsage;
+  attempts: FusionFailureList<FusionFailureAttemptMetadata>;
+  evidence_artifacts: FusionFailureList<FusionFailureEvidenceArtifact>;
+  remediation_ids: FusionFailureSummaryV1['remediation_ids'];
+}
+
+function boundedFailureView(
+  source: FailureViewSource,
+  status: FusionFailureResultView['summary_status'],
+  summaryRef?: FusionArtifactRef,
+): FusionFailureResultView {
+  const attempts = { listed: [...source.attempts.listed], omitted_count: source.attempts.omitted_count };
+  const evidence = { listed: [...source.evidence_artifacts.listed], omitted_count: source.evidence_artifacts.omitted_count };
+  const failure = source.failure;
+  const view: FusionFailureResultView = {
+    schema_version: FUSION_FAILURE_SUMMARY_SCHEMA_VERSION,
+    summary_status: status,
+    terminal_state: source.terminal_state,
+    answer: { present: false, reason: 'run_did_not_commit' },
+    ...(failure === undefined
+      ? {}
+      : { failure: { ...failure, message: { ...failure.message } } }),
+    progress: source.progress,
+    usage_so_far: source.usage_so_far,
+    attempts,
+    evidence_artifacts: evidence,
+    remediation_ids: source.remediation_ids,
+    ...(summaryRef === undefined ? {} : { failure_summary_ref: summaryRef }),
+  };
+  const fits = (): boolean => Buffer.byteLength(canonicalJson(view), 'utf8') <= FAILURE_VIEW_MAX_BYTES;
+  if (!fits() && view.failure?.message.inline_message !== undefined) {
+    const message = view.failure.message;
+    view.failure = {
+      ...view.failure,
+      message: {
+        byte_length: message.byte_length,
+        sha256: message.sha256,
+        omission_reason: 'result_view_byte_budget',
+      },
+    };
+  }
+  while (!fits() && evidence.listed.length > 0) { evidence.listed.pop(); evidence.omitted_count += 1; }
+  while (!fits() && attempts.listed.length > 0) { attempts.listed.pop(); attempts.omitted_count += 1; }
+  if (!fits()) throw new Error('failure result view exceeds its byte budget without a safe whole-section omission');
+  return view;
+}
+
+function legacyFailureSource(
+  manifest: TrustedFailureManifest,
+): FailureViewSource {
+  const message =
+    manifest.error === undefined
+      ? undefined
+      : (() => {
+          const bytes = Buffer.from(manifest.error, 'utf8');
+          return bytes.length <= FUSION_FAILURE_SUMMARY_INLINE_MESSAGE_BYTES
+            ? {
+                byte_length: bytes.length,
+                sha256: sha256Buffer(bytes),
+                inline_message: manifest.error,
+              }
+            : {
+                byte_length: bytes.length,
+                sha256: sha256Buffer(bytes),
+                omission_reason: 'exceeds_inline_message_bytes_cap' as const,
+              };
+        })();
+  const evidence = Object.entries(manifest.artifacts)
+    .map(([name, ref]) => ({
+      name,
+      classification: manifest.classifications[name] ?? 'evidence_only',
+      ref: { ...ref },
+    }))
+    .sort((left, right) => compareFailureText(left.name, right.name));
+  const attempts = manifest.attempts;
+  return {
+    terminal_state: manifest.state,
+    ...(message === undefined ? {} : { failure: { message } }),
+    progress: buildFusionRunProgress(manifest),
+    usage_so_far: manifest.usage,
+    attempts: {
+      listed: attempts.filter((_attempt, index) => index < FUSION_FAILURE_SUMMARY_ATTEMPT_CAP),
+      omitted_count: attempts.length - Math.min(attempts.length, FUSION_FAILURE_SUMMARY_ATTEMPT_CAP),
+    },
+    evidence_artifacts: {
+      listed: evidence.filter((_evidence, index) => index < FUSION_FAILURE_SUMMARY_EVIDENCE_CAP),
+      omitted_count: evidence.length - Math.min(evidence.length, FUSION_FAILURE_SUMMARY_EVIDENCE_CAP),
+    },
+    remediation_ids: ['inspect_manifest_bound_evidence', 'inspect_terminal_error'],
+  };
+}
+
+/** Read only terminal failure metadata; it never reads stage-output bodies. */
+export async function readFusionFailureResult(
+  options: ReadFusionCommittedResultOptions,
+): Promise<FusionFailureResultView> {
+  let manifest: TrustedFailureManifest;
+  try {
+    const file = await readUtf8(join(options.artifactDirAbs, 'manifest.json'), 'manifest.json', options.artifactDir);
+    manifest = trustedFailureManifest(parseJsonText(file.text), options);
+  } catch {
+    return failureUnavailable('failed', 'unavailable');
+  }
+  const summaryRef = manifest.artifacts['failure-summary.json'];
+  if (summaryRef === undefined) {
+    return boundedFailureView(legacyFailureSource(manifest), 'legacy_manifest_only');
+  }
+  if (manifest.schemaVersion !== FUSION_MANIFEST_SCHEMA_VERSION || summaryRef.path !== 'failure-summary.json')
+    return failureUnavailable(manifest.state, 'integrity_failed');
+  try {
+    if (summaryRef.byte_length > FUSION_FAILURE_SUMMARY_MAX_BYTES)
+      throw new Error('failure summary exceeds its bounded artifact size');
+    const file = await readFailureUtf8(
+      join(options.artifactDirAbs, summaryRef.path),
+      'failure-summary.json',
+      options.artifactDir,
+      FUSION_FAILURE_SUMMARY_MAX_BYTES,
+    );
+    if (file.bytes.length !== summaryRef.byte_length || sha256Buffer(file.bytes) !== summaryRef.sha256)
+      throw new Error('failure summary hash/length mismatch');
+    const summary = parseFailureSummary(parseJsonText(file.text), manifest, options);
+    return boundedFailureView(summary, 'verified', summaryRef);
+  } catch {
+    return failureUnavailable(manifest.state, 'integrity_failed');
+  }
+}