pi-background-tasks 1.0.3 → 1.0.6

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

@@ -6,17 +6,39 @@ import { createRequire } from 'node:module';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import {
+  FUSION_CHILD_MAX_PROVIDER_REQUESTS,
+  FUSION_CHILD_MAX_TOOL_CALLS,
+  FUSION_CHILD_MIN_OUTPUT_RESERVE_TOKENS,
   FUSION_CHILD_RESULT_PREFIX,
   FUSION_CHILD_RESULT_SCHEMA_VERSION,
+  FUSION_CHILD_SAFETY_RESERVE_TOKENS,
+  FUSION_CHILD_SETTLEMENT_PREFIX,
+  FUSION_CHILD_SETTLEMENT_SCHEMA_VERSION,
   FUSION_RESEARCH_ENABLED_ENV,
+  FUSION_RUNTIME_GUARD_PREFIX,
+  FUSION_RUNTIME_GUARD_SCHEMA_VERSION,
   FUSION_SOURCE_POLICY_PATH_ENV,
   FUSION_SOURCE_POLICY_SHA256_ENV,
   FUSION_TOOL_CALL_LOG_PATH_ENV,
   FUSION_TOOL_CALL_SEAL_SCHEMA_VERSION,
   FUSION_TOOL_CALL_SEAL_SUFFIX,
   FUSION_CHILD_MAX_TOTAL_TOOL_RESULT_BYTES,
+  buildFusionChildSettlement,
+  isRecoverableFusionChildErrorRecord,
+  serializeFusionChildResultRecords,
   type FusionChildResultMetadata,
+  type FusionChildSettlementFailureReason,
+  type FusionChildSettlementRecord,
+  type FusionRuntimeGuardCode,
+  type FusionRuntimeGuardRecord,
 } from './child-protocol.js';
+import {
+  FUSION_CLAUDE_CACHE_BREAKPOINT_LIMIT,
+  FUSION_CLAUDE_CACHE_OBSERVATION_SCHEMA_VERSION,
+  FUSION_CLAUDE_CACHE_RETENTION_ENV,
+  type FusionClaudeCacheObservation,
+  type FusionClaudeCacheRetention,
+} from './claude-cache.js';
 import {
   FUSION_FORBIDDEN_TOOLS,
   FUSION_NO_TOOLS_CAPABILITY,
@@ -64,7 +86,8 @@ export const FUSION_CHILD_TIMEOUT_MS = 30 * 60 * 1000;
 export const FUSION_CHILD_IDLE_TIMEOUT_MS = 20 * 60 * 1000;
 export const FUSION_CHILD_KILL_GRACE_MS = 3000;
 export const FUSION_CHILD_SIGKILL_WAIT_MS = 5000;
-const FUSION_PI_CHILD_O_NOFOLLOW = typeof constants.O_NOFOLLOW === 'number' ? constants.O_NOFOLLOW : 0;
+const FUSION_PI_CHILD_O_NOFOLLOW =
+  typeof constants.O_NOFOLLOW === 'number' ? constants.O_NOFOLLOW : 0;
 
 export const FUSION_CHILD_REMOVED_ENV_KEYS = [
   'PI_SESSION_ID',
@@ -404,8 +427,9 @@ function fusionToolArgv(capability: FusionCapability): string[] {
  *
  * `--no-extensions` disables discovery but still honours explicit `--extension`
  * paths, so this list is the complete set a child receives. The metadata
- * extension is always present; the Anthropic sanitizer is appended only for
- * Claude routes, keeping non-Anthropic child argv byte-identical to before.
+ * extension is always present. For Claude routes the sanitizer loads first so
+ * the private runtime governor observes the final post-sanitizer payload; non-
+ * Anthropic child argv remains unchanged.
  */
 export function fusionChildExtensionPaths(
   model: ResolvedFusionModel,
@@ -413,7 +437,7 @@ export function fusionChildExtensionPaths(
   resolveSanitizer: () => string = resolveAnthropicSanitizerExtensionPath,
 ): readonly string[] {
   if (model.provider !== FUSION_SANITIZED_PROVIDER) return [childExtensionPath];
-  return [childExtensionPath, resolveSanitizer()];
+  return [resolveSanitizer(), childExtensionPath];
 }
 
 export function buildFusionPiChildArgv(
@@ -452,6 +476,9 @@ export function buildFusionPiChildArgv(
 
 const SHA256_HEX_PATTERN = /^[0-9a-f]{64}$/;
 const FUSION_CHILD_RESULT_PREFIX_BYTES = Buffer.from(FUSION_CHILD_RESULT_PREFIX, 'utf8');
+const FUSION_CHILD_SETTLEMENT_PREFIX_BYTES = Buffer.from(FUSION_CHILD_SETTLEMENT_PREFIX, 'utf8');
+const FUSION_RUNTIME_GUARD_PREFIX_BYTES = Buffer.from(FUSION_RUNTIME_GUARD_PREFIX, 'utf8');
+const PI_EXTENSION_ERROR_PREFIX_BYTES = Buffer.from('Extension error (', 'utf8');
 
 interface ParsedFusionChildStderr {
   records: FusionChildResultMetadata[];
@@ -525,6 +552,16 @@ function requireUsageInteger(
   return value;
 }
 
+function requirePositiveSafeInteger(
+  record: Record<PropertyKey, unknown>,
+  key: string,
+  label: string,
+): number {
+  const value = requireUsageInteger(record, key, label);
+  if (value === 0) throw new Error(`${label}.${key} must be a positive safe integer`);
+  return value;
+}
+
 function requireCostNumber(
   record: Record<PropertyKey, unknown>,
   key: string,
@@ -563,10 +600,124 @@ function parseCompactUsage(value: unknown): FusionUsage {
   };
 }
 
+const FUSION_CLAUDE_CACHE_RETENTIONS = new Set<FusionClaudeCacheRetention>([
+  'none',
+  'short',
+  'long',
+]);
+
+function parseFusionClaudeCacheObservation(
+  value: unknown,
+  provider: string,
+): FusionClaudeCacheObservation {
+  const record = assertClosedRecord(
+    value,
+    [
+      'schema_version',
+      'applicability',
+      'source',
+      'requested_retention',
+      'effective_retention',
+      'breakpoint_count',
+      'request_ordinal',
+    ],
+    'fusion child cache observation',
+  );
+  if (record['schema_version'] !== FUSION_CLAUDE_CACHE_OBSERVATION_SCHEMA_VERSION) {
+    throw new Error('fusion child cache observation schema_version mismatch');
+  }
+  const applicability = record['applicability'];
+  const source = record['source'];
+  const requested = record['requested_retention'];
+  const effective = record['effective_retention'];
+  const breakpointCount = requireUsageInteger(
+    record,
+    'breakpoint_count',
+    'fusion child cache observation',
+  );
+  const requestOrdinal = requirePositiveSafeInteger(
+    record,
+    'request_ordinal',
+    'fusion child cache observation',
+  );
+  if (requestOrdinal > FUSION_CHILD_MAX_PROVIDER_REQUESTS) {
+    throw new Error('fusion child cache observation exceeds the provider request limit');
+  }
+  if (breakpointCount > FUSION_CLAUDE_CACHE_BREAKPOINT_LIMIT) {
+    throw new Error('fusion child cache observation exceeds the Anthropic breakpoint limit');
+  }
+  if (provider !== 'anthropic') {
+    if (
+      applicability !== 'not_applicable' ||
+      source !== 'not_applicable' ||
+      requested !== null ||
+      effective !== null ||
+      breakpointCount !== 0
+    ) {
+      throw new Error('non-Anthropic fusion child has contradictory cache observation');
+    }
+    return {
+      schema_version: FUSION_CLAUDE_CACHE_OBSERVATION_SCHEMA_VERSION,
+      applicability: 'not_applicable',
+      source: 'not_applicable',
+      requested_retention: null,
+      effective_retention: null,
+      breakpoint_count: 0,
+      request_ordinal: requestOrdinal,
+    };
+  }
+  if (applicability !== 'anthropic') {
+    throw new Error('Anthropic fusion child cache observation is not applicable');
+  }
+  if (source !== 'default' && source !== FUSION_CLAUDE_CACHE_RETENTION_ENV) {
+    throw new Error('Anthropic fusion child cache observation source is invalid');
+  }
+  if (
+    typeof requested !== 'string' ||
+    !FUSION_CLAUDE_CACHE_RETENTIONS.has(requested as FusionClaudeCacheRetention) ||
+    typeof effective !== 'string' ||
+    !FUSION_CLAUDE_CACHE_RETENTIONS.has(effective as FusionClaudeCacheRetention)
+  ) {
+    throw new Error('Anthropic fusion child cache retention is invalid');
+  }
+  const requestedRetention = requested as FusionClaudeCacheRetention;
+  const effectiveRetention = effective as FusionClaudeCacheRetention;
+  if (source === 'default' && requestedRetention !== 'long') {
+    throw new Error('default Anthropic cache policy did not request long retention');
+  }
+  if ((effectiveRetention === 'none') !== (breakpointCount === 0)) {
+    throw new Error('Anthropic fusion child cache retention/breakpoint evidence mismatch');
+  }
+  if (requestedRetention === 'none' && effectiveRetention !== 'none') {
+    throw new Error('disabled Anthropic cache policy reported active breakpoints');
+  }
+  if (effectiveRetention === 'long' && requestedRetention !== 'long') {
+    throw new Error('Anthropic long cache retention was not requested');
+  }
+  return {
+    schema_version: FUSION_CLAUDE_CACHE_OBSERVATION_SCHEMA_VERSION,
+    applicability: 'anthropic',
+    source,
+    requested_retention: requestedRetention,
+    effective_retention: effectiveRetention,
+    breakpoint_count: breakpointCount,
+    request_ordinal: requestOrdinal,
+  };
+}
+
 function parseChildResultMetadata(value: unknown): FusionChildResultMetadata {
   const record = assertClosedRecord(
     value,
-    ['schema_version', 'provider', 'model', 'stop_reason', 'text_blocks', 'text_sha256', 'usage'],
+    [
+      'schema_version',
+      'provider',
+      'model',
+      'stop_reason',
+      'text_blocks',
+      'text_sha256',
+      'usage',
+      'cache_observation',
+    ],
     'fusion child result',
   );
   if (record['schema_version'] !== FUSION_CHILD_RESULT_SCHEMA_VERSION)
@@ -583,18 +734,346 @@ function parseChildResultMetadata(value: unknown): FusionChildResultMetadata {
     };
   });
   const usage = parseCompactUsage(record['usage']);
+  const provider = requireNonBlankString(record, 'provider', 'fusion child result');
   return {
     schema_version: FUSION_CHILD_RESULT_SCHEMA_VERSION,
-    provider: requireNonBlankString(record, 'provider', 'fusion child result'),
+    provider,
     model: requireNonBlankString(record, 'model', 'fusion child result'),
     stop_reason: requireNonBlankString(record, 'stop_reason', 'fusion child result'),
     text_blocks: textBlocks,
     text_sha256: requireSha256(record, 'text_sha256', 'fusion child result'),
     usage,
+    cache_observation: parseFusionClaudeCacheObservation(record['cache_observation'], provider),
   };
 }
 
+const FUSION_RUNTIME_GUARD_CODES = new Set<FusionRuntimeGuardCode>([
+  'provider_request_limit',
+  'provider_request_budget',
+  'provider_payload_invalid',
+  'claude_cache_policy',
+  'tool_call_limit',
+]);
+
+export function parseFusionRuntimeGuard(stderr: Buffer): FusionRuntimeGuardRecord | undefined {
+  const frames: FusionRuntimeGuardRecord[] = [];
+  let cursor = 0;
+  for (;;) {
+    const frameStart = stderr.indexOf(FUSION_RUNTIME_GUARD_PREFIX_BYTES, cursor);
+    if (frameStart < 0) break;
+    const payloadStart = frameStart + FUSION_RUNTIME_GUARD_PREFIX_BYTES.length;
+    const newline = stderr.indexOf(10, payloadStart);
+    if (newline < 0) throw new Error('fusion runtime guard frame is not newline-terminated');
+    const bytes = stderr.subarray(payloadStart, newline);
+    const text = bytes.toString('utf8');
+    if (!Buffer.from(text, 'utf8').equals(bytes)) {
+      throw new Error('fusion runtime guard frame is not valid UTF-8');
+    }
+    const record = assertClosedRecord(
+      parseJsonText(text),
+      [
+        'schema_version',
+        'code',
+        'provider',
+        'model',
+        'request_ordinal',
+        'tool_call_count',
+        'payload_bytes',
+        'payload_sha256',
+        'estimated_input_tokens',
+        'context_window_tokens',
+        'reserved_output_tokens',
+        'safety_reserve_tokens',
+        'allowed_input_tokens',
+        'message',
+      ],
+      'fusion runtime guard',
+    );
+    if (record['schema_version'] !== FUSION_RUNTIME_GUARD_SCHEMA_VERSION) {
+      throw new Error('fusion runtime guard schema_version mismatch');
+    }
+    const code = requireNonBlankString(record, 'code', 'fusion runtime guard');
+    if (!FUSION_RUNTIME_GUARD_CODES.has(code as FusionRuntimeGuardCode)) {
+      throw new Error(`fusion runtime guard code is unsupported: ${code}`);
+    }
+    const frame: FusionRuntimeGuardRecord = {
+      schema_version: FUSION_RUNTIME_GUARD_SCHEMA_VERSION,
+      code: code as FusionRuntimeGuardCode,
+      provider: requireNonBlankString(record, 'provider', 'fusion runtime guard'),
+      model: requireNonBlankString(record, 'model', 'fusion runtime guard'),
+      request_ordinal: requirePositiveSafeInteger(
+        record,
+        'request_ordinal',
+        'fusion runtime guard',
+      ),
+      tool_call_count: requireUsageInteger(record, 'tool_call_count', 'fusion runtime guard'),
+      payload_bytes: requireUsageInteger(record, 'payload_bytes', 'fusion runtime guard'),
+      payload_sha256: requireSha256(record, 'payload_sha256', 'fusion runtime guard'),
+      estimated_input_tokens: requireUsageInteger(
+        record,
+        'estimated_input_tokens',
+        'fusion runtime guard',
+      ),
+      context_window_tokens: requireUsageInteger(
+        record,
+        'context_window_tokens',
+        'fusion runtime guard',
+      ),
+      reserved_output_tokens: requirePositiveSafeInteger(
+        record,
+        'reserved_output_tokens',
+        'fusion runtime guard',
+      ),
+      safety_reserve_tokens: requirePositiveSafeInteger(
+        record,
+        'safety_reserve_tokens',
+        'fusion runtime guard',
+      ),
+      allowed_input_tokens: requireUsageInteger(
+        record,
+        'allowed_input_tokens',
+        'fusion runtime guard',
+      ),
+      message: requireNonBlankString(record, 'message', 'fusion runtime guard'),
+    };
+    if (frame.code !== 'provider_payload_invalid') {
+      if (frame.context_window_tokens === 0) {
+        throw new Error('fusion runtime guard.context_window_tokens must be positive');
+      }
+      const expectedAllowed =
+        frame.context_window_tokens - frame.reserved_output_tokens - frame.safety_reserve_tokens;
+      if (expectedAllowed < 0 || frame.allowed_input_tokens !== expectedAllowed) {
+        throw new Error('fusion runtime guard allowed-input arithmetic mismatch');
+      }
+    }
+    if (frame.code === 'claude_cache_policy') {
+      if (
+        frame.payload_bytes !== 0 ||
+        frame.payload_sha256 !== createHash('sha256').update(Buffer.alloc(0)).digest('hex') ||
+        frame.estimated_input_tokens !== 0
+      ) {
+        throw new Error('fusion runtime guard Claude cache policy payload evidence mismatch');
+      }
+    }
+    if (
+      frame.code === 'provider_request_budget' &&
+      frame.estimated_input_tokens <= frame.allowed_input_tokens
+    ) {
+      throw new Error('fusion runtime guard provider budget code has no token overage');
+    }
+    if (
+      frame.code === 'provider_request_limit' &&
+      frame.request_ordinal <= FUSION_CHILD_MAX_PROVIDER_REQUESTS
+    ) {
+      throw new Error('fusion runtime guard provider request limit was not exceeded');
+    }
+    if (frame.code === 'tool_call_limit') {
+      if (frame.tool_call_count <= FUSION_CHILD_MAX_TOOL_CALLS) {
+        throw new Error('fusion runtime guard tool call limit was not exceeded');
+      }
+      if (
+        frame.payload_bytes !== 0 ||
+        frame.payload_sha256 !== createHash('sha256').update(Buffer.alloc(0)).digest('hex') ||
+        frame.estimated_input_tokens !== 0
+      ) {
+        throw new Error('fusion runtime guard tool call limit payload evidence mismatch');
+      }
+    }
+    frames.push(frame);
+    cursor = newline + 1;
+  }
+  if (frames.length > 1) throw new Error('fusion child emitted multiple runtime guard frames');
+  return frames[0];
+}
+
+const FUSION_CHILD_SETTLEMENT_FAILURE_REASONS = new Set<FusionChildSettlementFailureReason>([
+  'no_records',
+  'final_not_stop',
+  'invalid_non_final',
+  'runtime_guard',
+  'cache_observation',
+]);
+
+export function parseFusionChildSettlement(
+  stderr: Buffer,
+): FusionChildSettlementRecord | undefined {
+  const frames: FusionChildSettlementRecord[] = [];
+  let cursor = 0;
+  for (;;) {
+    const frameStart = stderr.indexOf(FUSION_CHILD_SETTLEMENT_PREFIX_BYTES, cursor);
+    if (frameStart < 0) break;
+    const payloadStart = frameStart + FUSION_CHILD_SETTLEMENT_PREFIX_BYTES.length;
+    const newline = stderr.indexOf(10, payloadStart);
+    if (newline < 0) throw new Error('fusion child settlement frame is not newline-terminated');
+    const bytes = stderr.subarray(payloadStart, newline);
+    const text = bytes.toString('utf8');
+    if (!Buffer.from(text, 'utf8').equals(bytes)) {
+      throw new Error('fusion child settlement frame is not valid UTF-8');
+    }
+    const record = assertClosedRecord(
+      parseJsonText(text),
+      [
+        'schema_version',
+        'status',
+        'record_count',
+        'records_sha256',
+        'final_record_index',
+        'final_text_sha256',
+        'recovered_error_ordinals',
+        'failure_reason',
+      ],
+      'fusion child settlement',
+    );
+    if (record['schema_version'] !== FUSION_CHILD_SETTLEMENT_SCHEMA_VERSION) {
+      throw new Error('fusion child settlement schema_version mismatch');
+    }
+    const status = record['status'];
+    if (status !== 'complete' && status !== 'failed') {
+      throw new Error('fusion child settlement.status is invalid');
+    }
+    const recordCount = requireUsageInteger(record, 'record_count', 'fusion child settlement');
+    const finalIndexValue = record['final_record_index'];
+    const finalRecordIndex =
+      finalIndexValue === null
+        ? null
+        : requireUsageInteger(record, 'final_record_index', 'fusion child settlement');
+    const finalHashValue = record['final_text_sha256'];
+    const finalTextSha256 =
+      finalHashValue === null
+        ? null
+        : requireSha256(record, 'final_text_sha256', 'fusion child settlement');
+    const recoveredValue = record['recovered_error_ordinals'];
+    if (!Array.isArray(recoveredValue)) {
+      throw new Error('fusion child settlement.recovered_error_ordinals must be an array');
+    }
+    const recoveredErrorOrdinals = recoveredValue.map((value, index) => {
+      if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0) {
+        throw new Error(
+          `fusion child settlement.recovered_error_ordinals[${String(index)}] must be a non-negative safe integer`,
+        );
+      }
+      return value;
+    });
+    for (let index = 0; index < recoveredErrorOrdinals.length; index += 1) {
+      const ordinal = recoveredErrorOrdinals[index];
+      if (
+        ordinal === undefined ||
+        ordinal >= recordCount - 1 ||
+        (index > 0 && ordinal <= (recoveredErrorOrdinals[index - 1] ?? -1))
+      ) {
+        throw new Error('fusion child settlement recovered-error ordinals are not canonical');
+      }
+    }
+    const failureValue = record['failure_reason'];
+    let failureReason: FusionChildSettlementFailureReason | null;
+    if (failureValue === null) failureReason = null;
+    else if (
+      typeof failureValue === 'string' &&
+      FUSION_CHILD_SETTLEMENT_FAILURE_REASONS.has(
+        failureValue as FusionChildSettlementFailureReason,
+      )
+    ) {
+      failureReason = failureValue as FusionChildSettlementFailureReason;
+    } else {
+      throw new Error('fusion child settlement.failure_reason is invalid');
+    }
+    if ((status === 'complete') !== (failureReason === null)) {
+      throw new Error('fusion child settlement status/failure_reason mismatch');
+    }
+    if (recordCount === 0) {
+      if (finalRecordIndex !== null || finalTextSha256 !== null) {
+        throw new Error('fusion child settlement empty stream has final-record evidence');
+      }
+    } else if (finalRecordIndex !== recordCount - 1 || finalTextSha256 === null) {
+      throw new Error('fusion child settlement final-record evidence mismatch');
+    }
+    frames.push({
+      schema_version: FUSION_CHILD_SETTLEMENT_SCHEMA_VERSION,
+      status,
+      record_count: recordCount,
+      records_sha256: requireSha256(record, 'records_sha256', 'fusion child settlement'),
+      final_record_index: finalRecordIndex,
+      final_text_sha256: finalTextSha256,
+      recovered_error_ordinals: recoveredErrorOrdinals,
+      failure_reason: failureReason,
+    });
+    cursor = newline + 1;
+  }
+  if (frames.length > 1) throw new Error('fusion child emitted multiple settlement frames');
+  return frames[0];
+}
+
+function assertFusionChildSettlementOrdering(stderr: Buffer): void {
+  const settlementStart = stderr.indexOf(FUSION_CHILD_SETTLEMENT_PREFIX_BYTES);
+  if (settlementStart < 0) return;
+  if (stderr.indexOf(FUSION_CHILD_RESULT_PREFIX_BYTES, settlementStart) >= 0) {
+    throw new Error('fusion child emitted result metadata after terminal settlement');
+  }
+}
+
+function stripChildControlFrames(stderr: Buffer): Buffer {
+  const prefixes = [FUSION_CHILD_SETTLEMENT_PREFIX_BYTES, FUSION_RUNTIME_GUARD_PREFIX_BYTES];
+  const diagnostics: Buffer[] = [];
+  let cursor = 0;
+  for (;;) {
+    let next = -1;
+    let prefix: Buffer | undefined;
+    for (const candidate of prefixes) {
+      const found = stderr.indexOf(candidate, cursor);
+      if (found >= 0 && (next < 0 || found < next)) {
+        next = found;
+        prefix = candidate;
+      }
+    }
+    if (next < 0 || prefix === undefined) {
+      if (cursor < stderr.length) diagnostics.push(stderr.subarray(cursor));
+      break;
+    }
+    if (next > cursor) diagnostics.push(stderr.subarray(cursor, next));
+    const newline = stderr.indexOf(10, next + prefix.length);
+    if (newline < 0) throw new Error('fusion child control frame is not newline-terminated');
+    cursor = newline + 1;
+  }
+  return Buffer.concat(diagnostics);
+}
+
+export function assertFusionRuntimeGuardMatchesModel(
+  guard: FusionRuntimeGuardRecord,
+  model: ResolvedFusionModel,
+): void {
+  const routeUnknown = guard.provider === 'unknown' && guard.model === 'unknown';
+  if (!routeUnknown && (guard.provider !== model.provider || guard.model !== model.model)) {
+    throw new Error(
+      `fusion runtime guard route mismatch: expected ${model.qualifiedId}, observed ${guard.provider}/${guard.model}`,
+    );
+  }
+  if (routeUnknown && guard.code !== 'provider_payload_invalid') {
+    throw new Error('fusion runtime guard omitted the route for a capacity-backed refusal');
+  }
+  if (guard.code === 'provider_payload_invalid') return;
+  const expectedReservedOutput = Math.max(
+    FUSION_CHILD_MIN_OUTPUT_RESERVE_TOKENS,
+    model.maxOutputTokens,
+  );
+  const expectedAllowedInput =
+    model.contextWindow - expectedReservedOutput - FUSION_CHILD_SAFETY_RESERVE_TOKENS;
+  if (
+    guard.context_window_tokens !== model.contextWindow ||
+    guard.reserved_output_tokens !== expectedReservedOutput ||
+    guard.safety_reserve_tokens !== FUSION_CHILD_SAFETY_RESERVE_TOKENS ||
+    guard.allowed_input_tokens !== expectedAllowedInput
+  ) {
+    throw new Error('fusion runtime guard capacity evidence does not match the resolved route');
+  }
+}
+
 export function parseFusionChildStderr(stderr: Buffer): ParsedFusionChildStderr {
+  // Validate every package-owned side frame even though result metadata is parsed
+  // independently below. Malformed refusal/settlement evidence must never degrade
+  // into opaque diagnostics.
+  parseFusionRuntimeGuard(stderr);
+  const settlement = parseFusionChildSettlement(stderr);
+  assertFusionChildSettlementOrdering(stderr);
   const records: FusionChildResultMetadata[] = [];
   const diagnostics: Buffer[] = [];
   let cursor = 0;
@@ -623,11 +1102,16 @@ export function parseFusionChildStderr(stderr: Buffer): ParsedFusionChildStderr
     records.push(parseChildResultMetadata(parsed));
     cursor = newline + 1;
   }
-  const events = Buffer.from(
-    records.length === 0 ? '' : `${records.map((record) => JSON.stringify(record)).join('\n')}\n`,
-    'utf8',
-  );
-  return { records, events, diagnostics: Buffer.concat(diagnostics) };
+  const resultEvents = serializeFusionChildResultRecords(records);
+  const events =
+    settlement === undefined
+      ? resultEvents
+      : Buffer.concat([resultEvents, Buffer.from(`${JSON.stringify(settlement)}\n`, 'utf8')]);
+  return {
+    records,
+    events,
+    diagnostics: stripChildControlFrames(Buffer.concat(diagnostics)),
+  };
 }
 
 function parseToolCallLogRecord(value: unknown, label: string): FusionToolCallLogRecord {
@@ -728,36 +1212,53 @@ export function parseFusionToolCallLog(bytes: Buffer): FusionToolCallTrace {
   };
 }
 
-
 async function assertCompletedToolPolicy(
   trace: FusionToolCallTrace,
   capability: FusionCapability,
   sourcePolicy: { path: string; sha256: string } | undefined,
 ): Promise<void> {
-  const allowed = capability === 'inspect' ? FUSION_INSPECT_TOOLS : capability === 'research' ? FUSION_RESEARCH_TOOLS : [];
+  const allowed =
+    capability === 'inspect'
+      ? FUSION_INSPECT_TOOLS
+      : capability === 'research'
+        ? FUSION_RESEARCH_TOOLS
+        : [];
   const allowedSet = new Set<string>(allowed);
   const declared =
     capability === 'research' && sourcePolicy !== undefined
-      ? new Set((await readFusionSourcePolicyFile(sourcePolicy.path, sourcePolicy.sha256)).sources.map((source) => source.canonical_url))
+      ? new Set(
+          (await readFusionSourcePolicyFile(sourcePolicy.path, sourcePolicy.sha256)).sources.map(
+            (source) => source.canonical_url,
+          ),
+        )
       : undefined;
   for (const record of trace.records) {
     if (!allowedSet.has(record.tool_name)) {
       throw new Error(`fusion child used non-allowlisted tool ${record.tool_name}`);
     }
     if (capability === 'research' && record.tool_name === FUSION_WEB_FETCH_TOOL_NAME) {
-      if (sourcePolicy === undefined || declared === undefined) throw new Error('fusion research source policy missing during audit');
+      if (sourcePolicy === undefined || declared === undefined)
+        throw new Error('fusion research source policy missing during audit');
       if (record.status === 'ok') {
         if (record.url === undefined) throw new Error('fusion research fetch audit is missing url');
         const canonicalUrl = canonicalizeFusionPublicUrl(record.url);
-        if (record.url !== canonicalUrl) throw new Error('fusion research fetch audit URL was not canonical');
-        if (!declared.has(canonicalUrl)) throw new Error('fusion research fetch audit URL was not declared');
+        if (record.url !== canonicalUrl)
+          throw new Error('fusion research fetch audit URL was not canonical');
+        if (!declared.has(canonicalUrl))
+          throw new Error('fusion research fetch audit URL was not declared');
         if (record.rejected_url_sha256 !== undefined) {
-          throw new Error('fusion research successful fetch audit must not include rejected_url_sha256');
+          throw new Error(
+            'fusion research successful fetch audit must not include rejected_url_sha256',
+          );
         }
-        if (record.final_url === undefined) throw new Error('fusion research fetch audit is missing final_url');
-        if (record.http_status === undefined) throw new Error('fusion research fetch audit is missing http_status');
-        if (record.response_bytes === undefined) throw new Error('fusion research fetch audit is missing response_bytes');
-        if (record.content_sha256 === undefined) throw new Error('fusion research fetch audit is missing content_sha256');
+        if (record.final_url === undefined)
+          throw new Error('fusion research fetch audit is missing final_url');
+        if (record.http_status === undefined)
+          throw new Error('fusion research fetch audit is missing http_status');
+        if (record.response_bytes === undefined)
+          throw new Error('fusion research fetch audit is missing response_bytes');
+        if (record.content_sha256 === undefined)
+          throw new Error('fusion research fetch audit is missing content_sha256');
       } else {
         if (record.url !== undefined || record.final_url !== undefined) {
           throw new Error('fusion research rejected fetch audit must not persist raw URL');
@@ -828,7 +1329,8 @@ async function assertFusionToolCallLogSeal(
   }
   try {
     const stats = await handle.stat();
-    if (!stats.isFile()) throw new Error('fusion tool-call audit completion seal is not a regular file');
+    if (!stats.isFile())
+      throw new Error('fusion tool-call audit completion seal is not a regular file');
     if (stats.size > 4096) throw new Error('fusion tool-call audit completion seal is oversized');
     const bytes = await handle.readFile();
     if (bytes.at(-1) !== 10) throw new Error('fusion tool-call audit completion seal is partial');
@@ -841,7 +1343,13 @@ async function assertFusionToolCallLogSeal(
       throw new Error('fusion tool-call audit completion seal must be an object');
     }
     const keys = Object.keys(parsed).sort();
-    const expected = ['log_sha256', 'record_count', 'schema_version', 'status', 'total_result_bytes'];
+    const expected = [
+      'log_sha256',
+      'record_count',
+      'schema_version',
+      'status',
+      'total_result_bytes',
+    ];
     if (keys.join('\0') !== expected.join('\0')) {
       throw new Error('fusion tool-call audit completion seal keys mismatch');
     }
@@ -939,10 +1447,29 @@ export class FusionPiCompactResultParser {
     diagnostics: Buffer;
   } {
     const parsed = parseFusionChildStderr(stderr);
+    const runtimeGuard = parseFusionRuntimeGuard(stderr);
+    if (runtimeGuard !== undefined) {
+      throw new Error(`Pi child runtime guard refused the run: ${runtimeGuard.message}`);
+    }
+    const settlement = parseFusionChildSettlement(stderr);
+    if (settlement === undefined) throw new Error('Pi child emitted no terminal result settlement');
+    const expectedSettlement = buildFusionChildSettlement(parsed.records);
+    if (JSON.stringify(settlement) !== JSON.stringify(expectedSettlement)) {
+      throw new Error('Pi child terminal result settlement does not match the metadata stream');
+    }
+    if (parsed.diagnostics.includes(PI_EXTENSION_ERROR_PREFIX_BYTES)) {
+      throw new Error('Pi child reported an extension error diagnostic');
+    }
     const final = parsed.records.at(-1);
     if (final === undefined) throw new Error('Pi child emitted no compact result metadata');
     for (const record of parsed.records) this.assertModel(record);
+    this.assertCacheObservationOrdinals(parsed.records);
     this.assertTranscriptStopReasons(parsed.records);
+    if (settlement.status !== 'complete') {
+      throw new Error(
+        `Pi child terminal result settlement failed: ${settlement.failure_reason ?? 'unknown'}`,
+      );
+    }
     const observed = this.observedFromRecords(parsed.records);
     return {
       text: reconstructFinalText(response, final),
@@ -963,6 +1490,19 @@ export class FusionPiCompactResultParser {
     }
   }
 
+  private assertCacheObservationOrdinals(records: readonly FusionChildResultMetadata[]): void {
+    let priorOrdinal = 0;
+    for (const [index, record] of records.entries()) {
+      const ordinal = record.cache_observation.request_ordinal;
+      if (ordinal <= priorOrdinal) {
+        throw new Error(
+          `Pi child cache observation ordinal is not increasing at result ${String(index)}: previous ${String(priorOrdinal)}, observed ${String(ordinal)}`,
+        );
+      }
+      priorOrdinal = ordinal;
+    }
+  }
+
   private assertTranscriptStopReasons(records: readonly FusionChildResultMetadata[]): void {
     for (const [index, record] of records.entries()) {
       const isFinal = index === records.length - 1;
@@ -970,9 +1510,14 @@ export class FusionPiCompactResultParser {
         if (record.stop_reason !== 'stop') {
           throw new Error(this.stopReasonError('final', 'stop', record.stop_reason, true));
         }
-      } else if (record.stop_reason !== 'toolUse') {
+      } else if (record.stop_reason !== 'toolUse' && !isRecoverableFusionChildErrorRecord(record)) {
         throw new Error(
-          this.stopReasonError(`non-final record ${index}`, 'toolUse', record.stop_reason, true),
+          this.stopReasonError(
+            `non-final record ${index}`,
+            'toolUse or a settled zero-usage retry marker',
+            record.stop_reason,
+            true,
+          ),
         );
       }
     }
@@ -1251,7 +1796,13 @@ export async function runPiChild(options: RunPiChildOptions): Promise<FusionChil
     env[FUSION_TOOL_CALL_LOG_PATH_ENV] = options.toolCallLogPath;
     if (capability === 'research') {
       if (options.sourcePolicy === undefined) {
-        throw childError('fusion research child requires a source-policy path and hash', 'orchestration_failed', options, false, false);
+        throw childError(
+          'fusion research child requires a source-policy path and hash',
+          'orchestration_failed',
+          options,
+          false,
+          false,
+        );
       }
       env[FUSION_RESEARCH_ENABLED_ENV] = '1';
       env[FUSION_SOURCE_POLICY_PATH_ENV] = options.sourcePolicy.path;
@@ -1335,7 +1886,15 @@ export async function runPiChild(options: RunPiChildOptions): Promise<FusionChil
             options,
           );
         }
-        terminateChild(child, state, platform, killProcess, killGraceMs, sigkillWaitMs, settleClose);
+        terminateChild(
+          child,
+          state,
+          platform,
+          killProcess,
+          killGraceMs,
+          sigkillWaitMs,
+          settleClose,
+        );
       }, idleTimeoutMs),
     );
   };
@@ -1452,11 +2011,39 @@ export async function runPiChild(options: RunPiChildOptions): Promise<FusionChil
         observed,
       );
     if (close.code !== 0 || close.signal !== null) {
+      let runtimeGuard: FusionRuntimeGuardRecord | undefined;
+      try {
+        runtimeGuard = parseFusionRuntimeGuard(rawStderr);
+        if (runtimeGuard !== undefined) {
+          assertFusionRuntimeGuardMatchesModel(runtimeGuard, options.model);
+        }
+      } catch (error) {
+        throw new FusionChildRunError(
+          withCleanupErrors(
+            childError(
+              `Pi child runtime guard evidence invalid: ${error instanceof Error ? error.message : String(error)}`,
+              'child_event_invalid',
+              options,
+            ),
+            state.cleanupErrors,
+          ),
+          compactEvents,
+          response,
+          diagnostics,
+          close,
+          observed,
+        );
+      }
       throw new FusionChildRunError(
         withCleanupErrors(
           childError(
-            `Pi child exited with code ${close.code === null ? 'null' : String(close.code)}${close.signal === null ? '' : ` (${close.signal})`}`,
-            'child_exit_failed',
+            runtimeGuard?.message ??
+              `Pi child exited with code ${close.code === null ? 'null' : String(close.code)}${close.signal === null ? '' : ` (${close.signal})`}`,
+            runtimeGuard === undefined
+              ? 'child_exit_failed'
+              : runtimeGuard.code === 'claude_cache_policy'
+                ? 'child_cache_policy_invalid'
+                : 'child_runtime_budget_exceeded',
             options,
           ),
           state.cleanupErrors,