pi-background-tasks 2.5.0 → 2.6.0

package/src/core/config.ts

@@ -0,0 +1,121 @@
+export const PI_BG_FEATURE_VALUES = Object.freeze([
+  'process',
+  'delegate',
+  'fusion',
+  'attested',
+  'attribution',
+] as const);
+export type PiBackgroundFeature = (typeof PI_BG_FEATURE_VALUES)[number];
+
+export const PI_BG_DEFAULT_FEATURES = PI_BG_FEATURE_VALUES;
+
+export const PI_BG_DOCK_SHORTCUT_VALUES = Object.freeze([
+  'shift+down',
+  'ctrl+alt+b',
+  'off',
+] as const);
+export type PiBackgroundDockShortcut = (typeof PI_BG_DOCK_SHORTCUT_VALUES)[number];
+
+export const PI_BG_DEFAULT_DOCK_SHORTCUT: PiBackgroundDockShortcut = 'shift+down';
+
+export interface PiBackgroundFeatureSelection {
+  readonly process: true;
+  readonly delegate: boolean;
+  readonly fusion: boolean;
+  readonly attested: boolean;
+  readonly attribution: boolean;
+}
+
+export interface PiBackgroundConfig {
+  readonly features: PiBackgroundFeatureSelection;
+  readonly dockShortcut: PiBackgroundDockShortcut;
+}
+
+const CONFIG_VALUE_EXCERPT_CHARS = 96;
+
+function boundedConfigValue(value: string): string {
+  if (value.length <= CONFIG_VALUE_EXCERPT_CHARS) return JSON.stringify(value);
+  return `${JSON.stringify(value.slice(0, CONFIG_VALUE_EXCERPT_CHARS))}… (${String(value.length)} chars)`;
+}
+
+function invalidConfig(variable: string, reason: string, value: string): never {
+  throw new Error(
+    `pi_bg_config_invalid: ${variable} ${reason}; received ${boundedConfigValue(value)}`,
+  );
+}
+
+function parseFeatures(rawValue: string | undefined): PiBackgroundFeatureSelection {
+  const raw = rawValue ?? PI_BG_DEFAULT_FEATURES.join(',');
+  const accepted = PI_BG_FEATURE_VALUES.join(',');
+  if (raw.length === 0) {
+    invalidConfig('PI_BG_FEATURES', `must not be empty; accepted tokens: ${accepted}`, raw);
+  }
+  if (/\s/u.test(raw)) {
+    invalidConfig(
+      'PI_BG_FEATURES',
+      `must contain no whitespace; accepted tokens: ${accepted}`,
+      raw,
+    );
+  }
+  const tokens = raw.split(',');
+  if (tokens.some((token) => token.length === 0)) {
+    invalidConfig(
+      'PI_BG_FEATURES',
+      `contains a blank comma token; accepted tokens: ${accepted}`,
+      raw,
+    );
+  }
+
+  const selected = new Set<PiBackgroundFeature>();
+  for (const token of tokens) {
+    if (!(PI_BG_FEATURE_VALUES as readonly string[]).includes(token)) {
+      invalidConfig(
+        'PI_BG_FEATURES',
+        `contains unknown token ${boundedConfigValue(token)}; accepted tokens: ${accepted}; bg_result is derived from delegate or fusion`,
+        raw,
+      );
+    }
+    const feature = token as PiBackgroundFeature;
+    if (selected.has(feature)) {
+      invalidConfig('PI_BG_FEATURES', `contains duplicate token ${feature}`, raw);
+    }
+    selected.add(feature);
+  }
+  if (!selected.has('process')) {
+    invalidConfig('PI_BG_FEATURES', 'must include mandatory token process', raw);
+  }
+
+  return Object.freeze({
+    process: true,
+    delegate: selected.has('delegate'),
+    fusion: selected.has('fusion'),
+    attested: selected.has('attested'),
+    attribution: selected.has('attribution'),
+  });
+}
+
+function parseDockShortcut(rawValue: string | undefined): PiBackgroundDockShortcut {
+  const raw = rawValue ?? PI_BG_DEFAULT_DOCK_SHORTCUT;
+  if (!(PI_BG_DOCK_SHORTCUT_VALUES as readonly string[]).includes(raw)) {
+    invalidConfig(
+      'PI_BG_DOCK_SHORTCUT',
+      `accepted values are exactly ${PI_BG_DOCK_SHORTCUT_VALUES.join(',')}`,
+      raw,
+    );
+  }
+  return raw as PiBackgroundDockShortcut;
+}
+
+export function parseBackgroundTasksConfig(
+  env: Readonly<Record<string, string | undefined>> = process.env,
+): PiBackgroundConfig {
+  const features = parseFeatures(env['PI_BG_FEATURES']);
+  const dockShortcut = parseDockShortcut(env['PI_BG_DOCK_SHORTCUT']);
+  return Object.freeze({ features, dockShortcut });
+}
+
+export function dockShortcutFooterHint(shortcut: PiBackgroundDockShortcut): string {
+  if (shortcut === 'shift+down') return 'Shift↓';
+  if (shortcut === 'ctrl+alt+b') return 'CtrlAltB';
+  return '/tasks';
+}

package/src/core/context/visible-conversation-v2.ts

@@ -1,6 +1,6 @@
 import { createHash } from 'node:crypto';
 import type { Message } from '@earendil-works/pi-ai';
-import { canonicalJson } from '../attested-pi-run.js';
+import { canonicalJson } from '../canonical-json.js';
 
 /**
  * Frozen `visible-conversation-ledger-v2` transform.
@@ -22,8 +22,7 @@ import { canonicalJson } from '../attested-pi-run.js';
  */
 export const VISIBLE_CONVERSATION_TRANSFORM_ID = 'visible-conversation-ledger-v2';
 
-export const CONVERSATION_IMAGE_OMISSION_PREFIX =
-  '[Image omitted from fusion text transcript: ';
+export const CONVERSATION_IMAGE_OMISSION_PREFIX = '[Image omitted from fusion text transcript: ';
 
 export const OMITTED_EVENT_KINDS = [
   'assistant_thinking',
@@ -141,9 +140,7 @@ export class UnsupportedConversationBlockError extends Error {
   readonly label: string;
 
   constructor(label: string) {
-    super(
-      `fusion context projection encountered an unsupported conversation block: ${label}`,
-    );
+    super(`fusion context projection encountered an unsupported conversation block: ${label}`);
     this.name = 'UnsupportedConversationBlockError';
     this.label = label;
   }

package/src/core/delegate/artifacts.ts

@@ -2,7 +2,7 @@ import { createHash } from 'node:crypto';
 import { existsSync } from 'node:fs';
 import { chmod, mkdir, open, readFile, rename, rm } from 'node:fs/promises';
 import { basename, isAbsolute, join, relative, sep } from 'node:path';
-import { canonicalJson } from '../attested-pi-run.js';
+import { canonicalJson } from '../canonical-json.js';
 import { sanitizePathSegment } from '../common.js';
 import { replaceFileDurable, writeFileDurable } from '../durable-fs.js';
 import {
@@ -92,11 +92,14 @@ function sha256Bytes(bytes: Buffer): string {
 
 function pathInside(parent: string, child: string): boolean {
   const rel = relative(parent, child);
-  return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel) && !rel.split(sep).includes('..'));
+  return (
+    rel === '' || (!rel.startsWith('..') && !isAbsolute(rel) && !rel.split(sep).includes('..'))
+  );
 }
 
 function artifactError(message: string, cause?: unknown): DelegateError {
-  const suffix = cause === undefined ? '' : `: ${cause instanceof Error ? cause.message : String(cause)}`;
+  const suffix =
+    cause === undefined ? '' : `: ${cause instanceof Error ? cause.message : String(cause)}`;
   return new DelegateError(`${message}${suffix}`, {
     code: 'artifact_error',
     childCreated: true,
@@ -150,9 +153,7 @@ export class DelegateArtifactStore {
    * directory is created with `recursive: false` so a pre-existing directory is
    * a loud failure rather than a silent reuse.
    */
-  static async create(
-    options: CreateDelegateArtifactStoreOptions,
-  ): Promise<DelegateArtifactStore> {
+  static async create(options: CreateDelegateArtifactStoreOptions): Promise<DelegateArtifactStore> {
     const sessionSegment = sanitizePathSegment(
       options.sessionId ?? `session-${String(process.pid)}`,
     );
@@ -260,9 +261,12 @@ export class DelegateArtifactStore {
           taskId: this.manifest.task_id,
           artifactDir: this.rootDisplay,
           preserved: diagnosticNames,
-          remediation: diagnosticNames.length === 0
-            ? ['No diagnostic control artifact exists; inspect the background task merged output if one was created.']
-            : [`Inspect the existing delegate control artifacts: ${diagnosticNames.join(', ')}.`],
+          remediation:
+            diagnosticNames.length === 0
+              ? [
+                  'No diagnostic control artifact exists; inspect the background task merged output if one was created.',
+                ]
+              : [`Inspect the existing delegate control artifacts: ${diagnosticNames.join(', ')}.`],
         },
       );
     }

package/src/core/delegate/budget.ts

@@ -14,6 +14,12 @@ import {
   type TokenBudgetFamilyCalibration,
   type TokenBudgetRateSource,
 } from '../context/token-budget.js';
+import {
+  DELEGATE_DEFAULT_MAX_TOOL_CALLS,
+  DELEGATE_DEFAULT_MAX_TURNS,
+  DELEGATE_DEFAULT_TIMEOUT_SECONDS,
+  DELEGATE_INLINE_ANSWER_BYTES,
+} from './facade-contract.js';
 import {
   DELEGATE_BUDGET_PLAN_SCHEMA_VERSION,
   DelegateError,
@@ -21,6 +27,13 @@ import {
   type DelegatePinnedRoute,
 } from './types.js';
 
+export {
+  DELEGATE_DEFAULT_MAX_TOOL_CALLS,
+  DELEGATE_DEFAULT_MAX_TURNS,
+  DELEGATE_DEFAULT_TIMEOUT_SECONDS,
+  DELEGATE_INLINE_ANSWER_BYTES,
+} from './facade-contract.js';
+
 /**
  * Delegate budgeting.
  *
@@ -51,9 +64,6 @@ export const DELEGATE_MIN_CONTEXT_WINDOW_TOKENS =
   DELEGATE_FRAMING_RESERVE_TOKENS +
   DELEGATE_SAFETY_RESERVE_TOKENS;
 
-export const DELEGATE_DEFAULT_MAX_TURNS = 24;
-export const DELEGATE_DEFAULT_MAX_TOOL_CALLS = 120;
-export const DELEGATE_DEFAULT_TIMEOUT_SECONDS = 1200;
 export const DELEGATE_MAX_TOOL_RESULT_BYTES = 64 * 1024;
 export const DELEGATE_MAX_TOTAL_TOOL_OUTPUT_BYTES = 64 * 1024 * 1024;
 export const DELEGATE_MAX_ANSWER_BYTES = 4 * 1024 * 1024;
@@ -61,9 +71,6 @@ export const DELEGATE_MAX_ANSWER_BYTES = 4 * 1024 * 1024;
 export const DELEGATE_FINALIZATION_INPUT_RESERVE_TOKENS = 32 * 1024;
 /** Remaining retained-growth runway at which the child disables tools. */
 export const DELEGATE_FINALIZATION_TRIGGER_TOKENS = 8 * 1024;
-/** Answers at or under this serialize inline; larger ones degrade explicitly. */
-export const DELEGATE_INLINE_ANSWER_BYTES = 48 * 1024;
-
 export const DELEGATE_BUDGET_POLICY_ID = 'delegate-budget-policy-v3';
 
 export interface DelegateBudgetPolicyDescriptor {

package/src/core/delegate/facade-contract.ts

@@ -0,0 +1,6 @@
+/** Light registration constants shared by the delegate facade and budget engine. */
+export const DELEGATE_DEFAULT_MAX_TURNS = 24;
+export const DELEGATE_DEFAULT_MAX_TOOL_CALLS = 120;
+export const DELEGATE_DEFAULT_TIMEOUT_SECONDS = 1200;
+/** Answers at or under this serialize inline; larger ones degrade explicitly. */
+export const DELEGATE_INLINE_ANSWER_BYTES = 48 * 1024;

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

@@ -1,5 +1,5 @@
 import { createHash } from 'node:crypto';
-import { canonicalJson } from '../attested-pi-run.js';
+import { canonicalJson } from '../canonical-json.js';
 import {
   DELEGATE_RECEIPT_SCHEMA_VERSION,
   DELEGATE_RESULT_PACKAGE_SCHEMA_VERSION,
@@ -87,9 +87,7 @@ export function buildDelegateResultPackage(
       data_base64: bytes.toString('base64'),
     };
   });
-  const aggregate = Buffer.concat(
-    blocks.map((block) => Buffer.from(block.data_base64, 'base64')),
-  );
+  const aggregate = Buffer.concat(blocks.map((block) => Buffer.from(block.data_base64, 'base64')));
   return {
     schema_version: DELEGATE_RESULT_PACKAGE_SCHEMA_VERSION,
     task_id: input.taskId,
@@ -183,7 +181,11 @@ function parseUsage(value: unknown, taskId: string): DelegateUsageReport {
     );
   const usage = value['usage'];
   if (!isRecord(usage))
-    fail('delegate result package observed usage must be an object', 'child_result_invalid', taskId);
+    fail(
+      'delegate result package observed usage must be an object',
+      'child_result_invalid',
+      taskId,
+    );
   const cost = usage['cost'];
   if (!isRecord(cost))
     fail(
@@ -220,10 +222,7 @@ function parseUsage(value: unknown, taskId: string): DelegateUsageReport {
   };
 }
 
-function parseAttestations(
-  value: unknown,
-  taskId: string,
-): readonly DelegateRouteAttestation[] {
+function parseAttestations(value: unknown, taskId: string): readonly DelegateRouteAttestation[] {
   if (!Array.isArray(value))
     fail(
       'delegate result package route_attestations must be an array',
@@ -264,7 +263,11 @@ function parseSpillContentFormat(
 
 function parseSpillReceipts(value: unknown, taskId: string): readonly DelegateSpillReceipt[] {
   if (!Array.isArray(value))
-    fail('delegate result package spilled_artifacts must be an array', 'child_result_invalid', taskId);
+    fail(
+      'delegate result package spilled_artifacts must be an array',
+      'child_result_invalid',
+      taskId,
+    );
   return value.map((entry) => {
     if (!isRecord(entry))
       fail('delegate spill receipt must be an object', 'child_result_invalid', taskId);
@@ -332,7 +335,11 @@ export function verifyDelegateResultPackage(
 
   const routeRecord = parsed['route'];
   if (!isRecord(routeRecord))
-    fail('delegate result package route must be an object', 'child_result_invalid', expected.taskId);
+    fail(
+      'delegate result package route must be an object',
+      'child_result_invalid',
+      expected.taskId,
+    );
   const provider = requireString(routeRecord, 'provider', expected.taskId);
   const model = requireString(routeRecord, 'model', expected.taskId);
   if (provider !== expected.route.provider || model !== expected.route.model)
@@ -343,7 +350,10 @@ export function verifyDelegateResultPackage(
     );
   const attestations = parseAttestations(parsed['route_attestations'], expected.taskId);
   for (const attestation of attestations) {
-    if (attestation.provider !== expected.route.provider || attestation.model !== expected.route.model)
+    if (
+      attestation.provider !== expected.route.provider ||
+      attestation.model !== expected.route.model
+    )
       fail(
         `delegate child produced an assistant message on ${attestation.provider}/${attestation.model}, but the pinned route is ${expected.route.provider}/${expected.route.model}`,
         'route_mismatch',
@@ -353,7 +363,11 @@ export function verifyDelegateResultPackage(
 
   const answerRecord = parsed['answer'];
   if (!isRecord(answerRecord))
-    fail('delegate result package answer must be an object', 'child_result_invalid', expected.taskId);
+    fail(
+      'delegate result package answer must be an object',
+      'child_result_invalid',
+      expected.taskId,
+    );
   if (answerRecord['encoding'] !== 'utf-8')
     fail(
       'delegate result package answer encoding must be utf-8',
@@ -364,7 +378,11 @@ export function verifyDelegateResultPackage(
   const declaredSha = requireSha256(answerRecord, 'sha256', expected.taskId);
   const blocksValue = answerRecord['blocks'];
   if (!Array.isArray(blocksValue))
-    fail('delegate result package answer blocks must be an array', 'child_result_invalid', expected.taskId);
+    fail(
+      'delegate result package answer blocks must be an array',
+      'child_result_invalid',
+      expected.taskId,
+    );
 
   const blocks: DelegateAnswerBlock[] = [];
   const buffers: Buffer[] = [];

package/src/core/delegate/runner.ts

@@ -1,9 +1,9 @@
 import { existsSync } from 'node:fs';
-import { readFile } from 'node:fs/promises';
-import { canonicalJson } from '../attested-pi-run.js';
+import { readFile, rmdir } from 'node:fs/promises';
+import { canonicalJson } from '../canonical-json.js';
 import { replaceFileDurable } from '../durable-fs.js';
 import { resolveAnthropicAttributionExtensionPath } from '../anthropic-attribution-path.js';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
 import { DelegateArtifactStore, discardDelegateArtifactRoot } from './artifacts.js';
 import {
   buildDelegateChildArgv,
@@ -14,9 +14,7 @@ import {
   type DelegatePreflightInput,
   type DelegatePreflightResult,
 } from './launch.js';
-import {
-  DELEGATE_INLINE_ANSWER_BYTES,
-} from './budget.js';
+import { DELEGATE_INLINE_ANSWER_BYTES } from './budget.js';
 import { verifyDelegateResultPackage, type VerifiedDelegateResult } from './result-package.js';
 import {
   DelegateError,
@@ -44,6 +42,8 @@ export interface PreparedDelegateLaunch {
   seedPathAbs: string;
   /** Exact prompt bytes delivered to the child over stdin. */
   stdinBytes: Buffer;
+  /** Remove this complete preparation while it is still unowned by a task. */
+  rollback: () => Promise<void>;
 }
 
 export interface PrepareDelegateLaunchInput extends DelegatePreflightInput {
@@ -55,6 +55,57 @@ export interface PrepareDelegateLaunchInput extends DelegatePreflightInput {
   attributionExtensionPath?: string | undefined;
   env?: NodeJS.ProcessEnv | undefined;
   now?: (() => Date) | undefined;
+  /** Activation closure cancels preparation before task ownership transfers. */
+  signal?: AbortSignal | undefined;
+}
+
+const PREPARATION_CLEANUP_ERROR_MAX_CHARS = 320;
+
+function boundedPreparationError(error: unknown): string {
+  const text = (error instanceof Error ? error.message : String(error))
+    .replace(/\s+/gu, ' ')
+    .trim();
+  if (text.length <= PREPARATION_CLEANUP_ERROR_MAX_CHARS) return text;
+  return `${text.slice(0, PREPARATION_CLEANUP_ERROR_MAX_CHARS)}…`;
+}
+
+function filesystemErrorCode(error: unknown): string | undefined {
+  if (typeof error !== 'object' || error === null) return undefined;
+  const code: unknown = Reflect.get(error, 'code');
+  return typeof code === 'string' ? code : undefined;
+}
+
+async function removeEmptyDirectory(path: string): Promise<boolean> {
+  try {
+    await rmdir(path);
+    return true;
+  } catch (error) {
+    const code = filesystemErrorCode(error);
+    if (code === 'ENOENT') return true;
+    if (code === 'ENOTEMPTY' || code === 'EEXIST') return false;
+    throw error;
+  }
+}
+
+async function discardUnownedDelegatePreparation(rootAbs: string): Promise<void> {
+  await discardDelegateArtifactRoot(rootAbs);
+  const runParent = dirname(rootAbs);
+  if (!(await removeEmptyDirectory(runParent))) return;
+  await removeEmptyDirectory(dirname(runParent));
+}
+
+function throwIfPreparationAborted(signal: AbortSignal | undefined): void {
+  if (signal?.aborted !== true) return;
+  const reason: unknown = signal.reason;
+  if (reason instanceof Error) throw reason;
+  throw new Error('delegate launch preparation was cancelled before task registration');
+}
+
+function preparationCleanupFailure(original: unknown, cleanup: unknown): AggregateError {
+  return new AggregateError(
+    [original, cleanup],
+    `delegate launch preparation failed and rollback also failed: ${boundedPreparationError(cleanup)}`,
+  );
 }
 
 /**
@@ -62,16 +113,16 @@ export interface PrepareDelegateLaunchInput extends DelegatePreflightInput {
  *
  * Preflight runs first and completes entirely before the artifact directory is
  * created, so every admission refusal leaves zero children AND zero artifacts.
- * When a step after directory creation fails, the partially created directory
- * is removed, so a refused launch never leaves a half-formed run behind.
+ * When a step after directory creation fails or activation cancellation is
+ * observed, the producer removes the unowned directory before rejecting.
  */
 export async function prepareDelegateLaunch(
   input: PrepareDelegateLaunchInput,
 ): Promise<PreparedDelegateLaunch> {
+  throwIfPreparationAborted(input.signal);
   // Resolve the guard extension before anything is created: a package missing
   // its child guard must refuse rather than spawn an unguarded child.
-  const childExtensionPath =
-    input.childExtensionPath ?? resolveDelegateChildExtensionPath();
+  const childExtensionPath = input.childExtensionPath ?? resolveDelegateChildExtensionPath();
   let attributionExtensionPath: string | undefined;
   if (input.route.provider === 'anthropic') {
     try {
@@ -89,41 +140,46 @@ export async function prepareDelegateLaunch(
     }
   }
 
+  throwIfPreparationAborted(input.signal);
   const preflight = preflightDelegateLaunch(input);
+  throwIfPreparationAborted(input.signal);
 
-  const store = await DelegateArtifactStore.create({
-    cwd: input.cwd,
-    taskId: preflight.taskId,
-    launchNonce: preflight.launchNonce,
-    sessionId: input.sessionId,
-    childSessionId: preflight.childSessionId,
-    childSessionDir: '',
-    extensionMode: input.extensionMode,
-    route: input.route,
-    limits: preflight.limits,
-    seedSha256: preflight.seed.sha256,
-    ...(input.now === undefined ? {} : { now: input.now }),
-  });
-
+  let store: DelegateArtifactStore | undefined;
   try {
+    store = await DelegateArtifactStore.create({
+      cwd: input.cwd,
+      taskId: preflight.taskId,
+      launchNonce: preflight.launchNonce,
+      sessionId: input.sessionId,
+      childSessionId: preflight.childSessionId,
+      childSessionDir: '',
+      extensionMode: input.extensionMode,
+      route: input.route,
+      limits: preflight.limits,
+      seedSha256: preflight.seed.sha256,
+      ...(input.now === undefined ? {} : { now: input.now }),
+    });
+    throwIfPreparationAborted(input.signal);
+
     const seedRef = await store.writeSeed(preflight.seed.serialized);
+    throwIfPreparationAborted(input.signal);
     // The persisted seed bytes are the bytes the child reads. Nothing
     // re-serializes them between here and the child, and the child verifies the
     // hash before its first model call.
     if (seedRef.sha256 !== preflight.seed.sha256) {
-      throw new DelegateError(
-        'delegate seed hash changed between construction and persistence',
-        {
-          code: 'seed_persist_failed',
-          childCreated: false,
-          taskId: preflight.taskId,
-          artifactDir: store.artifactDir,
-        },
-      );
+      throw new DelegateError('delegate seed hash changed between construction and persistence', {
+        code: 'seed_persist_failed',
+        childCreated: false,
+        taskId: preflight.taskId,
+        artifactDir: store.artifactDir,
+      });
     }
     await store.writeLedger(preflight.seed.ledger);
+    throwIfPreparationAborted(input.signal);
     await store.writeBudgetPlan(preflight.plan);
+    throwIfPreparationAborted(input.signal);
     const childSessionDirAbs = await ensureDelegateChildSessionDir(store.artifactDirAbs);
+    throwIfPreparationAborted(input.signal);
     const seedPathAbs = join(store.artifactDirAbs, 'seed.json');
     const argv = buildDelegateChildArgv({
       route: input.route,
@@ -169,6 +225,13 @@ export async function prepareDelegateLaunch(
     // The persisted prompt bytes must equal the bytes sent to the child, so the
     // artifact is evidence of what the child actually received.
     await store.writeChildPrompt(stdinBytes);
+    throwIfPreparationAborted(input.signal);
+    const artifactDirAbs = store.artifactDirAbs;
+    let rollbackPromise: Promise<void> | undefined;
+    const rollback = (): Promise<void> => {
+      rollbackPromise ??= discardUnownedDelegatePreparation(artifactDirAbs);
+      return rollbackPromise;
+    };
     return {
       preflight,
       store,
@@ -178,10 +241,15 @@ export async function prepareDelegateLaunch(
       childSessionDirAbs,
       seedPathAbs,
       stdinBytes,
+      rollback,
     };
   } catch (error) {
-    // A failure after directory creation must not leave a half-formed run.
-    await discardDelegateArtifactRoot(store.artifactDirAbs);
+    if (store === undefined) throw error;
+    try {
+      await discardUnownedDelegatePreparation(store.artifactDirAbs);
+    } catch (cleanupError) {
+      throw preparationCleanupFailure(error, cleanupError);
+    }
     throw error;
   }
 }
@@ -246,17 +314,19 @@ async function adjudicateDelegateTerminal(
   const resultPath = join(input.artifactDirAbs, 'result.json');
   const terminalPath = join(input.artifactDirAbs, 'child-terminal.json');
   if (!existsSync(resultPath)) {
-    const recorded = existsSync(terminalPath)
-      ? await readChildTerminal(terminalPath)
-      : undefined;
+    const recorded = existsSync(terminalPath) ? await readChildTerminal(terminalPath) : undefined;
     const cancelled = input.taskStatus === 'killed';
     const code = recorded?.code ?? (cancelled ? 'child_cancelled' : 'child_exited_without_commit');
     const detail =
       recorded?.message ??
       input.taskError ??
       'the delegate child exited without committing a result package';
-    const preserved = ['seed.json', 'budget-plan.json', 'child-terminal.json', 'runtime-budget.json']
-      .filter((name) => existsSync(join(input.artifactDirAbs, name)));
+    const preserved = [
+      'seed.json',
+      'budget-plan.json',
+      'child-terminal.json',
+      'runtime-budget.json',
+    ].filter((name) => existsSync(join(input.artifactDirAbs, name)));
     if (
       input.taskOutputPath !== undefined &&
       input.taskOutputAbsPath !== undefined &&
@@ -265,25 +335,26 @@ async function adjudicateDelegateTerminal(
       preserved.push(input.taskOutputPath);
     }
     const diagnosticTargets = preserved.filter(
-      (name) => name === 'child-terminal.json' || name === 'runtime-budget.json' || name === input.taskOutputPath,
-    );
-    const diagnostic = diagnosticTargets.length === 0
-      ? 'No child terminal record or merged task output exists; inspect the preserved launch artifacts listed above.'
-      : `Inspect the preserved diagnostic evidence: ${diagnosticTargets.join(', ')}.`;
-    const error = new DelegateError(
-      `bg_delegate produced no committed answer: ${detail}`,
-      {
-        code: isDelegateErrorCode(code) ? code : 'child_exited_without_commit',
-        childCreated: true,
-        taskId: input.taskId,
-        artifactDir: input.artifactDirAbs,
-        preserved,
-        remediation: [
-          diagnostic,
-          'No partial answer is returned; nothing was truncated to look like success.',
-        ],
-      },
+      (name) =>
+        name === 'child-terminal.json' ||
+        name === 'runtime-budget.json' ||
+        name === input.taskOutputPath,
     );
+    const diagnostic =
+      diagnosticTargets.length === 0
+        ? 'No child terminal record or merged task output exists; inspect the preserved launch artifacts listed above.'
+        : `Inspect the preserved diagnostic evidence: ${diagnosticTargets.join(', ')}.`;
+    const error = new DelegateError(`bg_delegate produced no committed answer: ${detail}`, {
+      code: isDelegateErrorCode(code) ? code : 'child_exited_without_commit',
+      childCreated: true,
+      taskId: input.taskId,
+      artifactDir: input.artifactDirAbs,
+      preserved,
+      remediation: [
+        diagnostic,
+        'No partial answer is returned; nothing was truncated to look like success.',
+      ],
+    });
     const outcome: DelegateTaskOutcome = {
       status: cancelled ? 'cancelled' : 'failed',
       errorCode: error.code,

package/src/core/delegate/seed.ts

@@ -1,5 +1,5 @@
 import { createHash } from 'node:crypto';
-import { canonicalJson } from '../attested-pi-run.js';
+import { canonicalJson } from '../canonical-json.js';
 import {
   UnsupportedConversationBlockError,
   projectVisibleConversationV2,
@@ -241,11 +241,7 @@ export function verifyDelegateSeedBytes(
   return rebuildSeed(parsed, expected.taskId);
 }
 
-function requireString(
-  record: Record<PropertyKey, unknown>,
-  key: string,
-  taskId: string,
-): string {
+function requireString(record: Record<PropertyKey, unknown>, key: string, taskId: string): string {
   const value = record[key];
   if (typeof value !== 'string') {
     throw new DelegateError(`delegate seed field ${key} must be a string`, {
@@ -404,7 +400,9 @@ function rebuildSeed(record: Record<PropertyKey, unknown>, taskId: string): Dele
  * so it is carried through without re-deriving values that would only duplicate
  * the parent's computation.
  */
-function readDelegateProjection(record: Record<PropertyKey, unknown>): DelegateConversationProjection {
+function readDelegateProjection(
+  record: Record<PropertyKey, unknown>,
+): DelegateConversationProjection {
   const projection: unknown = record;
   if (!isDelegateProjection(projection)) {
     throw new DelegateError('delegate seed conversation_projection is malformed', {