pi-background-tasks 0.7.4 → 0.7.7

package/src/core/fusion/types.ts

@@ -1,14 +1,24 @@
 import type { Usage } from '@earendil-works/pi-ai';
+import type {
+  EstimateInputTokensResult,
+  TokenBudgetByteClassBreakdown,
+  TokenBudgetDominantByteClass,
+  TokenBudgetFamily,
+  TokenBudgetFamilyCalibration,
+  TokenBudgetRateSource,
+} from '../context/token-budget.js';
 
 export type FusionThinkingLevel = 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
 
 export const FUSION_MODEL_CONFIG_SCHEMA_VERSION = 'pi-background-tasks.fusion-models.v1';
-export const FUSION_INPUT_SCHEMA_VERSION = 'pi-background-tasks.fusion-input.v2';
+export const FUSION_INPUT_SCHEMA_VERSION = 'pi-background-tasks.fusion-input.v4';
 export const FUSION_EVALUATION_SCHEMA_VERSION = 'pi-background-tasks.fusion-evaluation.v1';
-export const FUSION_RESULT_SCHEMA_VERSION = 'pi-background-tasks.fusion-result.v2';
+export const FUSION_RESULT_SCHEMA_VERSION = 'pi-background-tasks.fusion-result.v3';
 export const FUSION_MANIFEST_SCHEMA_VERSION = 'pi-background-tasks.fusion-manifest.v2';
-export const FUSION_CONTEXT_LEDGER_SCHEMA_VERSION = 'pi-background-tasks.fusion-context-ledger.v1';
-export const FUSION_BUDGET_PLAN_SCHEMA_VERSION = 'pi-background-tasks.fusion-budget-plan.v1';
+export const FUSION_CONTEXT_LEDGER_SCHEMA_VERSION = 'pi-background-tasks.fusion-context-ledger.v2';
+export const FUSION_BUDGET_PLAN_SCHEMA_VERSION = 'pi-background-tasks.fusion-budget-plan.v3';
+export const FUSION_CALIBRATION_VIOLATION_SCHEMA_VERSION =
+  'pi-background-tasks.fusion-calibration-violation.v1';
 
 /**
  * Conversation-projection transform shared by every Fusion entry point.
@@ -18,12 +28,12 @@ export const FUSION_BUDGET_PLAN_SCHEMA_VERSION = 'pi-background-tasks.fusion-bud
  * hash-accounted omission receipts. It never truncates retained text and never
  * forwards raw image bytes.
  */
-export const FUSION_CONTEXT_TRANSFORM_ID = 'visible-conversation-ledger-v1';
+export const FUSION_CONTEXT_TRANSFORM_ID = 'visible-conversation-ledger-v2';
 export const FUSION_BRANCH_FILTER_ID = 'exclude-active-fusion-subtree-v1';
 
 /** Entry-point specific context policies. Both use the same payload-exclusion transform. */
-export const FUSION_TOOL_CONTEXT_POLICY_ID = 'fusion-tool-explicit-v1';
-export const FUSION_COMMAND_CONTEXT_POLICY_ID = 'fusion-command-conversation-v1';
+export const FUSION_TOOL_CONTEXT_POLICY_ID = 'fusion-tool-explicit-v2';
+export const FUSION_COMMAND_CONTEXT_POLICY_ID = 'fusion-command-conversation-v2';
 
 export const FUSION_IMAGE_OMISSION_PREFIX = '[Image omitted from fusion text transcript: ';
 
@@ -112,7 +122,7 @@ export interface ResolvedFusionModels {
 
 export type FusionRequestAuthority = 'explicit_text' | 'directive_over_projected_conversation';
 
-export interface FusionCanonicalRequestV2 {
+export interface FusionCanonicalRequestV3 {
   /** Entry point that produced this request. */
   source: FusionSource;
   /** How children must weigh `text` against the projected conversation. */
@@ -144,59 +154,60 @@ export interface FusionOmittedEventRecord {
   mime_type?: string;
 }
 
-export interface FusionContextOmissionLedgerV1 {
+export interface FusionOmittedActivityProjectionMapEntry {
+  canonical_entry_index: number;
+  entry_kind: 'omitted_activity';
+  ledger_index_first: number;
+  ledger_index_last: number;
+}
+
+export interface FusionLedgerOnlyImageProjectionMapEntry {
+  entry_kind: 'ledger_only_tool_result_image';
+  ledger_index_first: number;
+  ledger_index_last: number;
+}
+
+export type FusionContextProjectionMapEntry =
+  | FusionOmittedActivityProjectionMapEntry
+  | FusionLedgerOnlyImageProjectionMapEntry;
+
+export interface FusionContextOmissionLedgerV2 {
   schema_version: typeof FUSION_CONTEXT_LEDGER_SCHEMA_VERSION;
   policy_id: string;
   transform: typeof FUSION_CONTEXT_TRANSFORM_ID;
   entries: readonly FusionOmittedEventRecord[];
+  projection_map: readonly FusionContextProjectionMapEntry[];
   root_sha256: string;
 }
 
-export interface FusionProjectionTextEntry {
-  kind: 'text';
-  source_ordinal: number;
-  block_ordinal: number;
-  role: 'user' | 'assistant';
-  text: string;
-}
-
-/**
- * Per-kind counts for one omitted run. Zero-valued kinds are omitted from the
- * serialized receipt by a fixed policy rule so receipt size does not scale with
- * the number of tracked kinds; absent means exactly zero.
- */
-export interface FusionOmittedRunCounts {
-  assistant_thinking?: number;
-  tool_calls?: number;
-  tool_result_texts?: number;
-  tool_result_images?: number;
-}
+export type FusionProjectionTextEntry = [
+  tag: 't',
+  role: 'u' | 'a',
+  sourceOrdinal: number,
+  blockOrdinal: number,
+  text: string,
+];
 
-/** Byte totals for one omitted run, using the same omit-when-zero rule. */
-export interface FusionOmittedRunBytes {
-  assistant_thinking?: number;
-  tool_call_arguments?: number;
-  tool_result_text?: number;
-  tool_result_image?: number;
-}
+export type FusionProjectionOmissionCounts = [
+  assistantThinking: number,
+  toolCalls: number,
+  toolResults: number,
+];
 
-export interface FusionProjectionOmissionEntry {
-  kind: 'omitted_activity';
-  source_ordinal_first: number;
-  source_ordinal_last: number;
-  ledger_index_first: number;
-  ledger_index_last: number;
-  counts: FusionOmittedRunCounts;
-  payload_bytes: FusionOmittedRunBytes;
-  ledger_run_sha256: string;
-}
+export type FusionProjectionOmissionEntry = [
+  tag: 'o',
+  sourceOrdinalSpan: [first: number, last: number],
+  bytes: number,
+  counts: FusionProjectionOmissionCounts,
+];
 
 export type FusionProjectionEntry = FusionProjectionTextEntry | FusionProjectionOmissionEntry;
 
 export interface FusionContextPolicyDescriptor {
   id: string;
   transform: typeof FUSION_CONTEXT_TRANSFORM_ID;
-  version: 1;
+  version: 2;
+  receipt_format: 'omitted_activity.v2';
   user_text: 'verbatim';
   assistant_text: 'verbatim';
   assistant_thinking: 'ledger_only';
@@ -238,23 +249,28 @@ export interface FusionProjectionAccounting {
   tool_call_names: readonly FusionToolCallNameCount[];
   ledger_entry_count: number;
   ledger_root_sha256: string;
+  omission_receipt_utf8_bytes: number;
 }
 
-export interface FusionConversationProjectionV2 {
+export interface FusionConversationProjectionV4 {
   policy: FusionContextPolicyDescriptor;
   branch_filter: FusionBranchFilterDescriptor;
   entries: readonly FusionProjectionEntry[];
   accounting: FusionProjectionAccounting;
 }
 
-export interface FusionCanonicalInputV2 {
+export type FusionConversationProjectionV3 = FusionConversationProjectionV4;
+
+export interface FusionCanonicalInputV4 {
   schema_version: typeof FUSION_INPUT_SCHEMA_VERSION;
   cwd: string;
   system_prompt: string;
-  request: FusionCanonicalRequestV2;
-  conversation_projection: FusionConversationProjectionV2;
+  request: FusionCanonicalRequestV3;
+  conversation_projection: FusionConversationProjectionV4;
 }
 
+export type FusionCanonicalInputV3 = FusionCanonicalInputV4;
+
 export interface CandidateAssessment {
   candidate_id: FusionCandidateId;
   summary: string;
@@ -348,6 +364,15 @@ export function addFusionUsage(target: FusionUsage, delta: FusionUsage): void {
   target.cost.total += delta.cost.total;
 }
 
+export interface FusionResultBudgetDetails {
+  policy_id: string;
+  calibration_version: string;
+  route_table: readonly FusionRouteCapacity[];
+  rate_sources: readonly TokenBudgetRateSource[];
+  unknown_provider_warnings: readonly string[];
+  calibration_warnings: readonly FusionCalibrationViolation[];
+}
+
 export interface FusionResultDetails {
   schema_version: typeof FUSION_RESULT_SCHEMA_VERSION;
   run_id: string;
@@ -362,6 +387,7 @@ export interface FusionResultDetails {
   };
   evaluator_attempts: number;
   usage: FusionUsage;
+  budget: FusionResultBudgetDetails;
 }
 
 export type FusionProgressEvent =
@@ -370,6 +396,8 @@ export type FusionProgressEvent =
   | { type: 'candidate_completed'; slot: 1 | 2 | 3; completed: number; total: 3 }
   | { type: 'evaluation_started'; attempt: 1 | 2; repair: boolean }
   | { type: 'evaluation_retry'; errors: readonly string[] }
+  | { type: 'budget_warning'; warnings: readonly FusionBudgetWarning[]; error: string }
+  | { type: 'calibration_warning'; warning: FusionCalibrationViolation; artifact: string }
   | { type: 'merge_started' }
   | { type: 'completed'; runId: string; artifactDir: string }
   | { type: 'failed'; runId: string; artifactDir: string; error: string }
@@ -381,7 +409,8 @@ export type FusionErrorCode =
   | 'model_unavailable'
   | 'context_capture_failed'
   | 'context_policy_unsupported_block'
-  | 'prompt_budget_exceeded'
+  | 'prompt_budget_exceeded_forecast'
+  | 'prompt_budget_exceeded_measured'
   | 'model_capacity_unknown'
   | 'child_spawn_failed'
   | 'child_stdin_failed'
@@ -395,14 +424,53 @@ export type FusionErrorCode =
   | 'state_transition_invalid'
   | 'orchestration_failed';
 
-/**
- * Structured detail attached to a `prompt_budget_exceeded` failure so the caller
- * can see exactly which stage, which measured size, which allowed size, and
- * which configured model was the limiting participant.
- */
+export type FusionBudgetCheckKind = 'input_only_preflight' | 'rendered_prompt';
+
+export interface FusionBudgetComponentBreakdown {
+  visible_text: { bytes: number; tokens: number };
+  omission_receipts: { bytes: number; tokens: number };
+  projection_metadata: { bytes: number; tokens: number };
+  request: { bytes: number; tokens: number };
+  static_stage_framing: { bytes: number; tokens: number };
+  upstream_output_contracts: { bytes: number; tokens: number };
+}
+
+export interface FusionBudgetDenseRegion {
+  offset: number;
+  len: number;
+  detector: 'not_implemented_step_6';
+}
+
+export interface FusionBudgetRouteTableEntry {
+  role: FusionRouteCapacity['role'];
+  qualified_id: string;
+  allowed_input_tokens: number;
+  family: TokenBudgetFamily;
+  effective_rate_bytes_per_token_x100: number;
+  byte_capacity_utf8_bytes: number;
+  backed: boolean;
+}
+
+export interface FusionBudgetCounterfactuals {
+  empty_request: FusionBudgetEmptyRequestVerdict;
+  without_reservation: {
+    forecast_input_tokens_upper_bound: number;
+    signed_headroom_tokens: number;
+    fits: boolean;
+  };
+  at_median_rate: {
+    forecast_input_tokens_upper_bound: number | null;
+    signed_headroom_tokens: number | null;
+    fits: boolean | null;
+  };
+}
+
+/** Structured detail attached to a split prompt-budget failure. */
 export interface FusionBudgetErrorDetail {
   budget_stage: FusionBudgetStage;
-  measurement_kind: 'worst_case_envelope' | 'rendered_prompt';
+  slot?: 1 | 2 | 3;
+  measurement_kind: 'stage_forecast' | 'rendered_prompt';
+  check_kind: FusionBudgetCheckKind;
   measured_utf8_bytes: number;
   measured_input_tokens_upper_bound: number;
   allowed_input_tokens: number;
@@ -412,8 +480,24 @@ export interface FusionBudgetErrorDetail {
     qualified_id: string;
     context_window_tokens: number;
   };
+  rate_source: TokenBudgetRateSource;
+  backed: boolean;
+  dominant_byte_class: TokenBudgetDominantByteClass;
+  component_breakdown: FusionBudgetComponentBreakdown;
+  byte_class_breakdown: TokenBudgetByteClassBreakdown;
+  dense_regions: readonly FusionBudgetDenseRegion[];
+  bytes_over: number;
+  tokens_over: number;
+  required_allowed_tokens: number;
+  route_table: readonly FusionBudgetRouteTableEntry[];
+  counterfactuals: FusionBudgetCounterfactuals;
+  stage_upstream_actuals: readonly { stage: FusionStage; bytes: number }[];
+  policy_id: string;
+  calibration_version: string;
   context_policy_id: string;
   remediation: readonly string[];
+  blockers: readonly FusionBudgetBlocker[];
+  artifact_dir: string;
 }
 
 export interface FusionErrorDetails {
@@ -533,50 +617,110 @@ export interface FusionRouteCapacity {
   framing_reserve_tokens: number;
   safety_reserve_tokens: number;
   allowed_input_tokens: number;
+  family: TokenBudgetFamily;
+  rate_source: TokenBudgetRateSource;
+  byte_capacity_utf8_bytes: number;
+}
+
+export interface FusionBudgetStageComposition {
+  visible_text_bytes: number;
+  omission_receipt_bytes: number;
+  projection_metadata_bytes: number;
+  request_bytes: number;
+  static_stage_framing_bytes: number;
+  upstream_output_contract_bytes: number;
 }
 
 export interface FusionStageBudgetPlanEntry {
   budget_stage: FusionBudgetStage;
-  measurement_kind: 'worst_case_envelope';
-  measured_utf8_bytes: number;
-  measured_input_tokens_upper_bound: number;
+  slot?: 1 | 2 | 3;
+  route: FusionRouteCapacity;
+  conditional: boolean;
+  check_kind: 'input_only_preflight';
+  input_utf8_bytes: number;
+  upstream_output_contract_bytes: number;
+  forecast_utf8_bytes: number;
+  input_only_input_tokens_upper_bound: number;
+  forecast_input_tokens_upper_bound: number;
   allowed_input_tokens: number;
-  limiting_qualified_id: string;
-  slack_tokens: number;
+  input_only_signed_headroom_tokens: number;
+  signed_headroom_tokens: number;
+  input_only_utilization_basis_points: number;
+  utilization_basis_points: number;
+  input_only_estimate: EstimateInputTokensResult;
+  reservation_estimate: EstimateInputTokensResult;
+  fits: boolean;
+  reservation_fits: boolean;
+}
+
+export interface FusionBudgetBlocker extends FusionStageBudgetPlanEntry {
+  overage_tokens: number;
+  bytes_over: number;
+}
+
+export interface FusionBudgetWarning extends FusionStageBudgetPlanEntry {
+  warning_kind: 'input_utilization' | 'worst_case_reservation';
+  threshold_basis_points: number;
+}
+
+export interface FusionBudgetEmptyRequestVerdict {
+  request_utf8_bytes: number;
+  still_fails_with_empty_request: boolean;
+  shortening_request_can_help: boolean;
+  minimum_request_byte_reduction: number;
+  maximum_safe_request_utf8_bytes: number;
+  blockers_with_empty_request: readonly FusionBudgetBlocker[];
 }
 
 export interface FusionBudgetPlanV1 {
   schema_version: typeof FUSION_BUDGET_PLAN_SCHEMA_VERSION;
   policy: FusionBudgetPolicyDescriptor;
   routes: readonly FusionRouteCapacity[];
-  limiting_qualified_id: string;
-  /** Base-context feasibility check performed before the first candidate spawns. */
-  base_context: FusionStageBudgetPlanEntry;
+  stages: readonly FusionStageBudgetPlanEntry[];
+  blockers: readonly FusionBudgetBlocker[];
+  primary_blocker?: FusionBudgetBlocker;
+  primary_blocker_composition?: FusionBudgetStageComposition;
+  empty_request: FusionBudgetEmptyRequestVerdict;
+  warnings: readonly FusionBudgetWarning[];
 }
 
-/**
- * Documented, versioned budget policy.
- *
- * `bytes_per_token_divisor` is a conservative lower bound on UTF-8 bytes per
- * token: token upper bound = ceil(utf8Bytes / divisor). It is deliberately far
- * below the smallest ratio measured across real Fusion prompts so dense
- * non-ASCII input cannot silently exceed a route's window.
- *
- * `downstream_reserve_bytes` is withheld from the canonical input so the
- * evaluator, evaluation-repair, and merger prompts provably have room for the
- * child outputs they embed. It is derived from the enforced per-stage output
- * byte contracts, so it is a guarantee rather than an estimate: a response over
- * its contract fails loudly instead of being embedded. `downstream_reserve_tokens`
- * converts it with the same `bytes_per_token_divisor` used to measure prompts,
- * because reserving output tokens directly would understate the cost of
- * re-embedding those bytes. Neither value is adjusted to fit a particular input.
- */
+/** Documented, versioned budget policy. */
 export interface FusionBudgetPolicyDescriptor {
-  id: 'fusion-budget-policy-v1';
-  bytes_per_token_divisor: number;
+  id: 'fusion-budget-policy-v3';
+  calibration_version: string;
+  calibration_table: Readonly<Record<TokenBudgetFamily, TokenBudgetFamilyCalibration>>;
   reserved_output_tokens: number;
   framing_reserve_tokens: number;
   safety_reserve_tokens: number;
-  downstream_reserve_bytes: number;
-  downstream_reserve_tokens: number;
+  candidate_output_contract_bytes: number;
+  evaluation_output_contract_bytes: number;
+  merge_output_contract_bytes: number;
+  diagnostics_contract_bytes: number;
+  utilization_warning_threshold_basis_points: 8000;
+}
+
+export interface FusionCalibrationViolation {
+  schema_version: typeof FUSION_CALIBRATION_VIOLATION_SCHEMA_VERSION;
+  stage: FusionStage;
+  slot?: 1 | 2 | 3;
+  attempt: number;
+  route: {
+    provider: string;
+    model: string;
+    qualified_id: string;
+  };
+  family: TokenBudgetFamily;
+  rate_source: TokenBudgetRateSource;
+  prompt_utf8_bytes: number;
+  prompt_sha256: string;
+  forecast_input_tokens: number;
+  billed_input_tokens: number;
+  billed_input_breakdown: {
+    input: number;
+    cache_read: number;
+    cache_write: number;
+  };
+  under_forecast_tokens: number;
+  byte_class_breakdown: TokenBudgetByteClassBreakdown;
+  dominant_byte_class: TokenBudgetDominantByteClass;
 }

package/src/core/registry.ts

@@ -27,6 +27,7 @@ import {
   type JsonObject,
   type KillKind,
   type StartAttestedPiTaskOptions,
+  type StartDelegateTaskOptions,
   type StartTaskOptions,
   type TaskContextUsage,
   type TaskStatus,
@@ -52,6 +53,7 @@ import {
 } from './attested-pi-run.js';
 import {
   assertWindowsCommandLineWithinLimit,
+  piLaunchArgv,
   resolvePiLaunch,
   type PiLaunchSpec,
 } from './pi-launch.js';
@@ -87,8 +89,15 @@ interface OutputEventSource {
   on(event: 'data', listener: (data: Buffer | string) => void): unknown;
 }
 
+interface ChildStdin {
+  write(data: Buffer, callback: (error?: Error | null) => void): boolean;
+  end(callback?: () => void): unknown;
+  once(event: 'error', listener: (error: Error) => void): unknown;
+}
+
 export interface BackgroundTaskChildProcess {
   pid?: number | undefined;
+  stdin?: ChildStdin | null | undefined;
   stdout?: OutputEventSource | null | undefined;
   stderr?: OutputEventSource | null | undefined;
   kill(signal?: NodeJS.Signals): boolean;
@@ -678,6 +687,32 @@ function noopOnChange(): void {
   return undefined;
 }
 
+/**
+ * Deliver the delegate prompt bytes over stdin.
+ *
+ * A failure to deliver the seed is loud: the caller terminates the task rather
+ * than letting a child run without the context it was supposed to receive.
+ */
+function writeDelegateStdin(
+  child: BackgroundTaskChildProcess,
+  bytes: Buffer,
+  onError: (error: Error) => void,
+): void {
+  const stdin = child.stdin;
+  if (stdin === undefined || stdin === null) {
+    onError(new Error('delegate child stdin pipe is unavailable'));
+    return;
+  }
+  stdin.once('error', onError);
+  stdin.write(bytes, (error?: Error | null) => {
+    if (error !== undefined && error !== null) {
+      onError(error);
+      return;
+    }
+    stdin.end();
+  });
+}
+
 export class BackgroundTaskRegistry {
   private readonly tasks = new Map<string, BgTask>();
   private runtimeDir: RuntimeDir | undefined;
@@ -927,6 +962,145 @@ export class BackgroundTaskRegistry {
     }
   }
 
+  /**
+   * Start a prepared delegate child.
+   *
+   * The caller has already completed preflight, so by the time this runs the
+   * seed, budget plan, and artifact directory exist and the argv is fixed. The
+   * child is launched directly, never through a shell, and its terminal state
+   * flows through the same durable notification path as `bg_run`.
+   */
+  async startDelegateTask(
+    ctx: BackgroundTaskContext,
+    request: StartDelegateTaskOptions,
+  ): Promise<BgTask> {
+    if (this.shuttingDown)
+      throw new Error('Cannot start a delegate task while Pi is shutting down');
+
+    const launch = resolvePiLaunch({ platform: this.platform });
+    assertWindowsCommandLineWithinLimit(launch, request.argv, this.platform, 'bg-delegate');
+
+    const dir = await this.ensureRuntimeDir(ctx);
+    const id = request.facts.taskId;
+    const outputAbsPath = join(dir.abs, `${id}.output`);
+    const metadataAbsPath = join(dir.abs, `${id}.json`);
+    const outputPath = join(dir.display, `${id}.output`);
+
+    const task: BgTask = {
+      id,
+      name: normalizeTaskName(request.name) ?? 'Delegate task',
+      command: ['pi', ...request.argv].map(shellQuote).join(' '),
+      status: 'running',
+      outputPath,
+      outputAbsPath,
+      metadataAbsPath,
+      cwd: ctx.cwd,
+      startTime: this.now(),
+      exitCode: undefined,
+      pid: undefined,
+      bytesWritten: 0,
+      isAgent: true,
+      notified: false,
+      notifyOnCompletion: request.notifyOnCompletion,
+      triggerOnCompletion: request.triggerOnCompletion,
+      timeoutSeconds: request.timeoutSeconds,
+      model: request.facts.route.qualifiedId,
+      delegate: request.facts,
+      waiters: [],
+    };
+    this.tasks.set(id, task);
+
+    const stream = createWriteStream(outputAbsPath, { flags: 'a', encoding: 'utf8' });
+    task.stream = stream;
+    stream.on('error', (error) => {
+      task.error = `Output file write failed: ${error.message}`;
+    });
+
+    try {
+      const child = this.spawn(launch.executable, piLaunchArgv(launch, [...request.argv]), {
+        cwd: ctx.cwd,
+        detached: this.platform !== 'win32',
+        shell: false,
+        // The seed travels over stdin, never as a shell or positional argument,
+        // so the bytes the child reads are exactly the bytes that were persisted
+        // and hashed, with no quoting or command-line length limit in the path.
+        stdio: ['pipe', 'pipe', 'pipe'],
+        env: request.env,
+        windowsHide: true,
+      });
+      task.child = child;
+      task.pid = child.pid;
+      writeDelegateStdin(child, request.stdinBytes, (error) => {
+        this.writeNotice(task, `\n[delegate stdin write failed: ${error.message}]\n`);
+        if (task.status === 'running') {
+          task.killKind = 'user';
+          task.error = `Delegate seed could not be delivered: ${error.message}`;
+          try {
+            this.requestKill(task, 'SIGTERM');
+          } catch {
+            void this.finalizeTask(task, 'failed', null, undefined, task.error);
+          }
+        }
+      });
+
+      child.stdout?.on('data', (data) => {
+        this.appendChildOutput(task, data, 'stdout');
+      });
+      child.stderr?.on('data', (data) => {
+        this.appendChildOutput(task, data, 'stderr');
+      });
+      child.on('error', (error) => {
+        this.writeNotice(task, `\n[delegate spawn error: ${error.message}]\n`);
+        void this.finalizeTask(task, 'failed', null, undefined, error.message);
+      });
+      child.on('close', (code, signalName) => {
+        let status: TaskStatus;
+        let error: string | undefined;
+        if (task.killKind === 'user' || task.killKind === 'shutdown') {
+          status = 'killed';
+        } else if (task.killKind === 'timeout') {
+          status = 'failed';
+          error = task.error ?? `Timed out after ${String(request.timeoutSeconds ?? 0)}s`;
+        } else if ((code ?? 0) === 0) {
+          status = 'completed';
+        } else {
+          status = 'failed';
+          error = `Exited with code ${code === null ? 'null' : String(code)}${signalName ? ` (${signalName})` : ''}`;
+        }
+        void this.finalizeTask(task, status, code, signalName, error);
+      });
+
+      if (request.timeoutSeconds !== undefined) {
+        task.timeoutHandle = setTimeout(() => {
+          if (task.status !== 'running') return;
+          task.killKind = 'timeout';
+          task.error = `Timed out after ${String(request.timeoutSeconds)}s`;
+          this.writeNotice(task, `\n[delegate timeout: ${task.error}]\n`);
+          try {
+            this.requestKill(task, 'SIGTERM');
+          } catch (error) {
+            void this.finalizeTask(
+              task,
+              'failed',
+              null,
+              undefined,
+              `${task.error}; kill failed: ${error instanceof Error ? error.message : String(error)}`,
+            );
+          }
+        }, request.timeoutSeconds * 1000);
+      }
+
+      await this.writeMetadata(task);
+      this.onChange();
+      return task;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      this.writeNotice(task, `\n[delegate spawn exception: ${message}]\n`);
+      await this.finalizeTask(task, 'failed', null, undefined, message);
+      throw new Error(`Failed to start delegate task: ${message}`);
+    }
+  }
+
   async startAttestedPiTask(
     ctx: BackgroundTaskContext,
     request: StartAttestedPiTaskOptions,