pi-background-tasks 2.1.3 → 2.3.0

package/src/core/delegate/launch.ts

@@ -17,6 +17,7 @@ import {
   DELEGATE_TOOL_NAME,
   DelegateError,
   type DelegateCapability,
+  type DelegateExtensionMode,
   type DelegateLimits,
   type DelegatePinnedRoute,
   type DelegateRoute,
@@ -87,7 +88,7 @@ export function resolveDelegateRoute(input: DelegateRouteResolutionInput): Deleg
           childCreated: false,
           remediation: [
             'Name a provider/model pair that appears in the current model registry.',
-            'Omit the route argument to use the parent session\'s current model.',
+            "Omit the route argument to use the parent session's current model.",
           ],
         },
       );
@@ -239,12 +240,23 @@ export function delegateToolsFor(capability: DelegateCapability): readonly strin
   });
 }
 
+function assertDelegateExtensionMode(mode: DelegateExtensionMode): void {
+  if (mode === 'isolated' || mode === 'ambient') return;
+  throw new DelegateError(`bg_delegate extension mode ${String(mode)} is not supported`, {
+    code: 'invalid_arguments',
+    childCreated: false,
+    remediation: ['Use extensionMode "isolated" or "ambient".'],
+  });
+}
+
 export interface DelegateChildArgvInput {
   route: DelegatePinnedRoute;
   capability: DelegateCapability;
+  extensionMode: DelegateExtensionMode;
   childSessionId: string;
   childSessionDir: string;
   childExtensionPath: string;
+  attributionExtensionPath?: string | undefined;
   systemPrompt: string;
 }
 
@@ -252,11 +264,15 @@ export interface DelegateChildArgvInput {
  * Build the child argv.
  *
  * The child gets its own `--session-id` and a task-owned `--session-dir`, so it
- * is structurally incapable of opening or mutating the parent session. Discovery
- * of ambient extensions, skills, prompt templates, themes, and context files is
- * disabled; only the package's own guard extension is loaded explicitly.
+ * is structurally incapable of opening or mutating the parent session. Skills,
+ * prompt templates, themes, and context files are always disabled. Extension
+ * discovery is disabled in isolated mode and deliberately enabled in ambient
+ * mode; ambient extensions execute arbitrary code and are not sandboxed by the
+ * model-visible tool allowlist. The package guard is always explicit; Anthropic
+ * routes first load the package attribution/sanitization extension.
  */
 export function buildDelegateChildArgv(input: DelegateChildArgvInput): string[] {
+  assertDelegateExtensionMode(input.extensionMode);
   const tools = delegateToolsFor(input.capability);
   for (const forbidden of DELEGATE_FORBIDDEN_TOOLS) {
     if (tools.includes(forbidden)) {
@@ -266,6 +282,20 @@ export function buildDelegateChildArgv(input: DelegateChildArgvInput): string[]
       );
     }
   }
+  const extensionPaths =
+    input.route.provider === 'anthropic'
+      ? [
+          input.attributionExtensionPath ??
+            (() => {
+              throw new DelegateError(
+                'Anthropic delegate launch requires the package attribution extension',
+                { code: 'delegate_isolation_unsupported', childCreated: false },
+              );
+            })(),
+          input.childExtensionPath,
+        ]
+      : [input.childExtensionPath];
+
   return [
     '--mode',
     'text',
@@ -279,13 +309,12 @@ export function buildDelegateChildArgv(input: DelegateChildArgvInput): string[]
     tools.join(','),
     '--exclude-tools',
     DELEGATE_FORBIDDEN_TOOLS.join(','),
-    '--no-extensions',
+    ...(input.extensionMode === 'isolated' ? ['--no-extensions'] : []),
     '--no-skills',
     '--no-prompt-templates',
     '--no-themes',
     '--no-context-files',
-    '--extension',
-    input.childExtensionPath,
+    ...extensionPaths.flatMap((path) => ['--extension', path]),
     '--provider',
     input.route.provider,
     '--model',
@@ -362,6 +391,7 @@ export interface DelegatePreflightInput {
   toolCallId: string | undefined;
   prompt: string;
   capability: DelegateCapability;
+  extensionMode: DelegateExtensionMode;
   route: DelegatePinnedRoute;
   limitOverrides: DelegateLimitOverrides;
   hookEvidence: DelegateHookContractEvidence;
@@ -411,10 +441,9 @@ export function buildDelegateChildPrompt(seedSerialized: string, directive: stri
  * one of these can refuse, and none of them has created a process, a session, or
  * an artifact by the time it does.
  */
-export function preflightDelegateLaunch(
-  input: DelegatePreflightInput,
-): DelegatePreflightResult {
+export function preflightDelegateLaunch(input: DelegatePreflightInput): DelegatePreflightResult {
   assertDelegateHookContract(input.hookEvidence);
+  assertDelegateExtensionMode(input.extensionMode);
   // Validates the capability and proves the tool set contains nothing forbidden.
   delegateToolsFor(input.capability);
   const limits = resolveDelegateLimits(input.route, input.limitOverrides);
@@ -427,10 +456,13 @@ export function preflightDelegateLaunch(
     toolCallId: input.toolCallId,
     directive: input.prompt,
     capability: input.capability,
+    extensionMode: input.extensionMode,
     route: input.route,
     limits,
   });
-  const childSystemPrompt = buildDelegateChildSystemPrompt('the task seed in your first user message');
+  const childSystemPrompt = buildDelegateChildSystemPrompt(
+    'the task seed in your first user message',
+  );
   const childPrompt = buildDelegateChildPrompt(seed.serialized, seed.seed.directive.text);
   const plan = planDelegateAdmission({
     route: input.route,
@@ -454,9 +486,7 @@ export function preflightDelegateLaunch(
 }
 
 /** Task-owned child session directory. Never the parent's session directory. */
-export async function ensureDelegateChildSessionDir(
-  artifactDirAbs: string,
-): Promise<string> {
+export async function ensureDelegateChildSessionDir(artifactDirAbs: string): Promise<string> {
   const dir = join(artifactDirAbs, 'child-session');
   await mkdir(dir, { recursive: true, mode: 0o700 });
   return dir;

package/src/core/delegate/runner.ts

@@ -2,6 +2,7 @@ import { existsSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { canonicalJson } from '../attested-pi-run.js';
 import { replaceFileDurable } from '../durable-fs.js';
+import { resolveAnthropicAttributionExtensionPath } from '../anthropic-attribution-path.js';
 import { join } from 'node:path';
 import { DelegateArtifactStore, discardDelegateArtifactRoot } from './artifacts.js';
 import {
@@ -20,6 +21,7 @@ import { verifyDelegateResultPackage, type VerifiedDelegateResult } from './resu
 import {
   DelegateError,
   type DelegateAutoDeliverMode,
+  type DelegateExtensionMode,
   type DelegateResultPackageV1,
 } from './types.js';
 import type { DelegateTaskFacts, DelegateTaskOutcome } from '../common.js';
@@ -48,7 +50,9 @@ export interface PrepareDelegateLaunchInput extends DelegatePreflightInput {
   cwd: string;
   sessionId: string | undefined;
   autoDeliver: DelegateAutoDeliverMode;
+  extensionMode: DelegateExtensionMode;
   childExtensionPath?: string | undefined;
+  attributionExtensionPath?: string | undefined;
   env?: NodeJS.ProcessEnv | undefined;
   now?: (() => Date) | undefined;
 }
@@ -68,6 +72,22 @@ export async function prepareDelegateLaunch(
   // its child guard must refuse rather than spawn an unguarded child.
   const childExtensionPath =
     input.childExtensionPath ?? resolveDelegateChildExtensionPath();
+  let attributionExtensionPath: string | undefined;
+  if (input.route.provider === 'anthropic') {
+    try {
+      attributionExtensionPath =
+        input.attributionExtensionPath ?? resolveAnthropicAttributionExtensionPath();
+    } catch (error) {
+      throw new DelegateError(
+        `Anthropic delegate attribution extension could not be resolved: ${error instanceof Error ? error.message : String(error)}`,
+        {
+          code: 'delegate_isolation_unsupported',
+          childCreated: false,
+          remediation: ['Reinstall the package; Anthropic delegates require attribution.'],
+        },
+      );
+    }
+  }
 
   const preflight = preflightDelegateLaunch(input);
 
@@ -78,6 +98,7 @@ export async function prepareDelegateLaunch(
     sessionId: input.sessionId,
     childSessionId: preflight.childSessionId,
     childSessionDir: '',
+    extensionMode: input.extensionMode,
     route: input.route,
     limits: preflight.limits,
     seedSha256: preflight.seed.sha256,
@@ -107,9 +128,11 @@ export async function prepareDelegateLaunch(
     const argv = buildDelegateChildArgv({
       route: input.route,
       capability: input.capability,
+      extensionMode: input.extensionMode,
       childSessionId: preflight.childSessionId,
       childSessionDir: childSessionDirAbs,
       childExtensionPath,
+      attributionExtensionPath,
       systemPrompt: preflight.childSystemPrompt,
     });
     const env = delegateChildEnv(
@@ -138,6 +161,7 @@ export async function prepareDelegateLaunch(
         family: preflight.plan.route.family,
         rate_source: preflight.plan.route.rate_source,
       },
+      extensionMode: input.extensionMode,
       autoDeliver: input.autoDeliver,
     };
     const stdinBytes = Buffer.from(preflight.childPrompt, 'utf8');

package/src/core/delegate/seed.ts

@@ -22,6 +22,7 @@ import {
   type DelegateContextPolicyDescriptor,
   type DelegateConversationProjection,
   type DelegateLedgerV1,
+  type DelegateExtensionMode,
   type DelegateLimits,
   type DelegatePinnedRoute,
   type DelegateSeedV1,
@@ -34,6 +35,7 @@ export interface BuildDelegateSeedOptions {
   toolCallId: string | undefined;
   directive: string;
   capability: DelegateCapability;
+  extensionMode: DelegateExtensionMode;
   route: DelegatePinnedRoute;
   limits: DelegateLimits;
 }
@@ -167,6 +169,7 @@ export function buildDelegateSeed(
     launch_nonce: options.launchNonce,
     cwd: ctx.cwd,
     capability: options.capability,
+    extension_mode: options.extensionMode,
     route: options.route,
     parent_system_prompt: ctx.getSystemPrompt(),
     parent_leaf_id: snapshot.leafId,
@@ -296,6 +299,14 @@ function rebuildSeed(record: Record<PropertyKey, unknown>, taskId: string): Dele
       taskId,
     });
   }
+  const extensionMode = requireString(record, 'extension_mode', taskId);
+  if (extensionMode !== 'isolated' && extensionMode !== 'ambient') {
+    throw new DelegateError(`delegate seed extension mode ${extensionMode} is not recognised`, {
+      code: 'seed_hash_mismatch',
+      childCreated: true,
+      taskId,
+    });
+  }
   const routeRecord = requireRecord(record, 'route', taskId);
   const routeOrigin = requireString(routeRecord, 'origin', taskId);
   if (routeOrigin !== 'parent_current' && routeOrigin !== 'explicit') {
@@ -378,6 +389,7 @@ function rebuildSeed(record: Record<PropertyKey, unknown>, taskId: string): Dele
     launch_nonce: requireString(record, 'launch_nonce', taskId),
     cwd: requireString(record, 'cwd', taskId),
     capability,
+    extension_mode: extensionMode,
     route,
     parent_system_prompt: requireString(record, 'parent_system_prompt', taskId),
     parent_leaf_id: parentLeafId,

package/src/core/delegate/types.ts

@@ -12,14 +12,14 @@ import type {
   ProjectionEntry,
 } from '../context/visible-conversation-v2.js';
 
-export const DELEGATE_SEED_SCHEMA_VERSION = 'pi-background-tasks.delegate-seed.v1' as const;
+export const DELEGATE_SEED_SCHEMA_VERSION = 'pi-background-tasks.delegate-seed.v2' as const;
 export const DELEGATE_LEDGER_SCHEMA_VERSION = 'pi-background-tasks.delegate-ledger.v1' as const;
 export const DELEGATE_RESULT_PACKAGE_SCHEMA_VERSION =
   'pi-background-tasks.delegate-result.v1' as const;
 export const DELEGATE_RECEIPT_SCHEMA_VERSION = 'pi-background-tasks.delegate-receipt.v1' as const;
 export const DELEGATE_BUDGET_PLAN_SCHEMA_VERSION =
   'pi-background-tasks.delegate-budget-plan.v2' as const;
-export const DELEGATE_MANIFEST_SCHEMA_VERSION = 'pi-background-tasks.delegate-manifest.v1' as const;
+export const DELEGATE_MANIFEST_SCHEMA_VERSION = 'pi-background-tasks.delegate-manifest.v2' as const;
 
 /**
  * Delegate's own context policy id. It shares the frozen
@@ -35,6 +35,13 @@ export const DELEGATE_RESULT_TOOL_NAME = 'bg_result';
 export const DELEGATE_CAPABILITIES = ['inspect'] as const;
 export type DelegateCapability = (typeof DELEGATE_CAPABILITIES)[number];
 
+/**
+ * Controls only Pi's ambient extension discovery for delegate children.
+ * Tool and project-resource restrictions remain independently enforced.
+ */
+export const DELEGATE_EXTENSION_MODES = ['isolated', 'ambient'] as const;
+export type DelegateExtensionMode = (typeof DELEGATE_EXTENSION_MODES)[number];
+
 export const DELEGATE_AUTO_DELIVER_MODES = ['never', 'when_small', 'always'] as const;
 export type DelegateAutoDeliverMode = (typeof DELEGATE_AUTO_DELIVER_MODES)[number];
 
@@ -110,6 +117,7 @@ export interface DelegateSeedV1 {
   launch_nonce: string;
   cwd: string;
   capability: DelegateCapability;
+  extension_mode: DelegateExtensionMode;
   route: DelegatePinnedRoute;
   parent_system_prompt: string;
   parent_leaf_id: string | null;

package/src/core/fusion/artifacts.ts

@@ -7,12 +7,18 @@ import { replaceFileDurable } from '../durable-fs.js';
 import {
   EMPTY_FUSION_USAGE,
   FUSION_COMMITTED_RESULT_SCHEMA_VERSION,
+  FUSION_FAILURE_SUMMARY_SCHEMA_VERSION,
   FUSION_MANIFEST_SCHEMA_VERSION,
   FUSION_VALIDATE_CANDIDATE_CONTRACT_EVENT_SCHEMA_VERSION,
   FusionError,
   cloneFusionUsage,
   type FusionArtifactManifest,
   type FusionArtifactRef,
+  type FusionFailureArtifactClassification,
+  type FusionFailureAttemptMetadata,
+  type FusionFailureEvidenceArtifact,
+  type FusionFailureSummaryV1,
+  type FusionRunProgress,
   type FusionAttemptArtifactRecord,
   type FusionBudgetPlanV1,
   type FusionCalibrationViolation,
@@ -318,6 +324,210 @@ function artifactRefSha256Hex(value: string): string {
   return hex;
 }
 
+/** A manifest artifact reference is always one safe basename below its run directory. */
+export function assertFusionArtifactBasename(name: string): string {
+  if (
+    name.length === 0 ||
+    name !== basename(name) ||
+    name.includes('/') ||
+    name.includes('\\') ||
+    name === '.' ||
+    name === '..' ||
+    Buffer.byteLength(name, 'utf8') > 255
+  ) {
+    throw errorForArtifact(`invalid fusion artifact name: ${name}`);
+  }
+  return name;
+}
+
+export const FUSION_FAILURE_SUMMARY_INLINE_MESSAGE_BYTES = 1024;
+export const FUSION_FAILURE_SUMMARY_ATTEMPT_CAP = 12;
+export const FUSION_FAILURE_SUMMARY_EVIDENCE_CAP = 24;
+export const FUSION_FAILURE_SUMMARY_MAX_BYTES = 32 * 1024;
+
+function compareArtifactText(left: string, right: string): number {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+interface FusionProgressManifest {
+  state: FusionState;
+  artifacts: Readonly<Record<string, FusionArtifactRef>>;
+  attempts: readonly {
+    stage: FusionStage;
+    slot?: 1 | 2 | 3 | undefined;
+    status: 'completed' | 'failed' | 'cancelled';
+    child_created: boolean;
+  }[];
+  usage: FusionUsage;
+}
+
+function failureStageProgress(
+  manifest: FusionProgressManifest,
+  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;
+}
+
+/** Derive terminal progress solely from the durable manifest. */
+export function buildFusionRunProgress(manifest: FusionProgressManifest): FusionRunProgress {
+  return {
+    manifest_state: manifest.state,
+    candidates: failureStageProgress(manifest, 'candidate'),
+    evaluation: failureStageProgress(manifest, 'evaluation'),
+    merge: failureStageProgress(manifest, 'merge'),
+    usage_so_far: cloneFusionUsage(manifest.usage),
+  };
+}
+
+function terminalMessageMetadata(message: string): FusionFailureSummaryV1['failure']['message'] {
+  const bytes = Buffer.from(message, 'utf8');
+  return {
+    byte_length: bytes.length,
+    sha256: sha256Buffer(bytes),
+    ...(bytes.length <= FUSION_FAILURE_SUMMARY_INLINE_MESSAGE_BYTES
+      ? { inline_message: message }
+      : { omission_reason: 'exceeds_inline_message_bytes_cap' as const }),
+  };
+}
+
+function failureArtifactClassification(
+  name: string,
+  ref: FusionArtifactRef,
+  manifest: FusionArtifactManifest,
+): FusionFailureArtifactClassification {
+  for (const attempt of manifest.attempts) {
+    if (attempt.response_path === name) {
+      return ref.byte_length === 0 && attempt.status !== 'completed'
+        ? 'empty_rejected_output'
+        : 'complete_stage_output';
+    }
+    if (attempt.partial_response_path === name) return 'partial_stage_output';
+    if (attempt.output_recovery?.original_response_path === name) return 'oversized_original';
+  }
+  return 'evidence_only';
+}
+
+function failureAttemptMetadata(manifest: FusionArtifactManifest): readonly FusionFailureAttemptMetadata[] {
+  return manifest.attempts
+    .map((attempt) => ({
+      stage: attempt.stage,
+      ...(attempt.slot === undefined ? {} : { slot: attempt.slot }),
+      attempt: attempt.attempt,
+      status: attempt.status,
+      child_created: attempt.child_created,
+    }))
+    .sort((left, right) =>
+      compareArtifactText(left.stage, right.stage) ||
+      (left.slot ?? 0) - (right.slot ?? 0) ||
+      left.attempt - right.attempt,
+    );
+}
+
+export function buildFusionFailureSummary(input: {
+  manifest: FusionArtifactManifest;
+  terminalError: FusionError;
+  progress: FusionRunProgress;
+  terminalState: Exclude<FusionTerminalState, 'completed'>;
+  createdAt: string;
+}): FusionFailureSummaryV1 {
+  if (
+    (input.terminalState !== 'failed' && input.terminalState !== 'cancelled') ||
+    input.manifest.state !== input.terminalState
+  ) {
+    throw errorForArtifact('failure summary requires a matching failed/cancelled terminal manifest');
+  }
+  if (input.manifest.error !== input.terminalError.message) {
+    throw errorForArtifact('failure summary terminal error does not match the durable manifest');
+  }
+  if (canonicalJson(input.progress) !== canonicalJson(buildFusionRunProgress(input.manifest))) {
+    throw errorForArtifact('failure summary progress does not match the durable terminal manifest');
+  }
+  if (input.manifest.artifacts['failure-summary.json'] !== undefined) {
+    throw errorForArtifact('failure summary already exists in the terminal manifest');
+  }
+  const attempts = failureAttemptMetadata(input.manifest);
+  const evidence: FusionFailureEvidenceArtifact[] = Object.entries(input.manifest.artifacts)
+    .map(([name, ref]) => ({
+      name: assertFusionArtifactBasename(name),
+      classification: failureArtifactClassification(name, ref, input.manifest),
+      ref: { ...ref },
+    }))
+    .sort((left, right) => compareArtifactText(left.name, right.name));
+  return {
+    schema_version: FUSION_FAILURE_SUMMARY_SCHEMA_VERSION,
+    run_id: input.manifest.run_id,
+    workflow: input.manifest.workflow,
+    source: input.manifest.source,
+    terminal_state: input.terminalState,
+    created_at: input.createdAt,
+    answer: { present: false, reason: 'run_did_not_commit' },
+    failure: {
+      code: input.terminalError.code,
+      ...(input.terminalError.stage === undefined ? {} : { stage: input.terminalError.stage }),
+      ...(input.terminalError.slot === undefined ? {} : { slot: input.terminalError.slot }),
+      ...(input.terminalError.attempt === undefined
+        ? {}
+        : { attempt: input.terminalError.attempt }),
+      child_created: input.terminalError.childCreated,
+      message: terminalMessageMetadata(input.terminalError.message),
+    },
+    progress: input.progress,
+    usage_so_far: cloneFusionUsage(input.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((_artifact, 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',
+      'split_or_reduce_work',
+      'retry_same_route_after_operator_review',
+    ],
+  };
+}
+
 export class FusionArtifactStore {
   private readonly runDirAbs: string;
   private readonly runDirDisplay: string;
@@ -534,6 +744,59 @@ export class FusionArtifactStore {
     });
   }
 
+  /**
+   * Writes the terminal evidence summary exactly once after writeError has made
+   * the manifest terminal. The summary deliberately contains refs only, never
+   * stage-output bodies.
+   */
+  async writeFailureSummary(summary: FusionFailureSummaryV1): Promise<FusionArtifactRef> {
+    if (
+      this.manifest.state !== 'failed' &&
+      this.manifest.state !== 'cancelled'
+    ) {
+      throw errorForArtifact('failure summary requires a failed/cancelled terminal manifest');
+    }
+    if (summary.terminal_state !== this.manifest.state) {
+      throw errorForArtifact('failure summary terminal state does not match the manifest');
+    }
+    if (
+      summary.run_id !== this.manifest.run_id ||
+      summary.workflow !== this.manifest.workflow ||
+      summary.source !== this.manifest.source
+    ) {
+      throw errorForArtifact('failure summary identity does not match the terminal manifest');
+    }
+    if (
+      summary.answer?.present !== false ||
+      summary.answer.reason !== 'run_did_not_commit'
+    ) {
+      throw errorForArtifact('failure summary must assert that no answer was committed');
+    }
+    if (this.manifest.error === undefined || this.manifest.artifacts['error.json'] === undefined) {
+      throw errorForArtifact('failure summary requires durable terminal error evidence');
+    }
+    if (
+      canonicalJson(summary.failure.message) !==
+      canonicalJson(terminalMessageMetadata(this.manifest.error))
+    ) {
+      throw errorForArtifact('failure summary terminal error metadata does not match the manifest');
+    }
+    if (canonicalJson(summary.progress) !== canonicalJson(buildFusionRunProgress(this.snapshot()))) {
+      throw errorForArtifact('failure summary progress does not match the terminal manifest');
+    }
+    if (canonicalJson(summary.usage_so_far) !== canonicalJson(this.manifest.usage)) {
+      throw errorForArtifact('failure summary usage does not match the terminal manifest');
+    }
+    if (this.manifest.artifacts['failure-summary.json'] !== undefined) {
+      throw errorForArtifact('failure summary is already bound in the manifest');
+    }
+    const bytes = Buffer.from(`${canonicalJson(summary)}\n`, 'utf8');
+    if (bytes.length > FUSION_FAILURE_SUMMARY_MAX_BYTES) {
+      throw errorForArtifact('failure summary exceeds its bounded diagnostics artifact limit');
+    }
+    return this.writeArtifact('failure-summary.json', bytes);
+  }
+
   async recordChildAttempt(input: RecordFusionChildAttemptInput): Promise<void> {
     const prefix = attemptPrefix(input.result.stage, input.result.slot, input.result.attempt);
     await this.writeArtifact(`${prefix}.system-prompt.txt`, input.systemPrompt);
@@ -664,6 +927,7 @@ export class FusionArtifactStore {
     });
   }
 
+  /** Writes a durable artifact then binds its exact bytes in the manifest. */
   private async writeArtifact(name: string, data: Buffer | string): Promise<FusionArtifactRef> {
     const absPath = this.artifactPath(name);
     const ref = await writePrivateFile(absPath, data);
@@ -674,9 +938,7 @@ export class FusionArtifactStore {
   }
 
   private artifactPath(name: string): string {
-    if (name.length === 0 || name.includes('/') || name.includes('\\')) {
-      throw errorForArtifact(`invalid fusion artifact name: ${name}`);
-    }
+    assertFusionArtifactBasename(name);
     const absPath = join(this.runDirAbs, name);
     if (!pathInside(this.runDirAbs, absPath)) {
       throw errorForArtifact(`fusion artifact path escapes run directory: ${name}`);

package/src/core/fusion/config.ts

@@ -5,7 +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 { CLAUDE_CODE_200K_SUBSCRIPTION_CONTEXT_WINDOW } from '../anthropic-attribution.js';
 import {
   FUSION_MODEL_CONFIG_SCHEMA_VERSION,
   FusionError,