@fitchmultz/pi-subagents 0.44.7 → 0.46.0

package/src/runs/shared/child-attempt.ts

@@ -1,623 +1,387 @@
 import { spawn } from "node:child_process";
-import { randomUUID } from "node:crypto";
 import { addAbortListener } from "node:events";
-import { mkdirSync, writeFileSync, mkdtempSync, openSync, readSync, writeSync, closeSync, rmSync, fstatSync, ftruncateSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { StringDecoder } from "node:string_decoder";
-import * as path from "node:path";
-import type { Message } from "@earendil-works/pi-ai";
-import { attachChildProcessLifecycle } from "../../shared/post-exit-stdio-guard.ts";
-import { applyIntercomBridgeToAgent, resolveIntercomBridge } from "../../intercom/intercom-bridge.ts";
-import { providerQualifiedModelId } from "../../shared/model-info.ts";
-import { getSubagentDepthEnv, type AgentProcessExit, type ResourceLimitExceeded, type Usage } from "../../shared/types.ts";
-import { extractTextFromContent, extractToolArgsPreview, formatResourceLimitExceeded, getFinalOutput, findLatestSessionFile } from "../../shared/utils.ts";
-import { readFinalizationReport, resolveExecutionOutcome } from "./acceptance.ts";
-import { readStructuredOutput } from "./structured-output.ts";
 import {
-	appendClaudeCodeMessage, buildClaudeCodeInvocation, claudeCodeMessageFromResult, isClaudeCodeModel, writeClaudeCodeSessionMetadata,
-	type ClaudeCodeInvocation, type ClaudeCodeResultEvent,
-} from "./claude-code.ts";
-import { createMutationCompletionTracker, resolveCurrentPath, type MutationToolResult } from "./mutating-tool-guard.ts";
-import { applyThinkingSuffix, buildPiArgs } from "./pi-args.ts";
-import { FINALIZATION_EVENT, nativeFinalizationLaunch, type NativeFinalizationConfig, type NativeFinalizationEvent } from "./native-finalization.ts";
-import { addUsage, nativeUsageCollector, readNativeUsage, snapshotNativeBaseline, validateNativeUsage, type NativeUsageMetadata } from "./native-usage.ts";
-import { sumAttemptUsage } from "./model-fallback.ts";
+  getSubagentDepthEnv,
+  type ReadonlyInput,
+  type ResourceLimitExceeded,
+} from "../../shared/types.ts";
+import { attachChildProcessLifecycle } from "../../shared/post-exit-stdio-guard.ts";
+import { findLatestSessionFile, formatResourceLimitExceeded } from "../../shared/utils.ts";
+import { resolveExecutionOutcome } from "./acceptance.ts";
+import { snapshotNativeBaseline, type NativeBaseline } from "./native-usage.ts";
 import { getPiSpawnCommand } from "./pi-spawn.ts";
-import type { StructuredOutputRuntime } from "./structured-output.ts";
-import type { updateStreamingText } from "./streaming-text.ts";
-import { createRepeatedSubagentCallGuardState, recordToolEndForSubagentLoopGuard, recordToolStartForSubagentLoopGuard } from "./subagent-tool-loop-guard.ts";
-import { JournalFrames, NativeJournal, nativeProjection, scanJournal, type Projection } from "../../shared/journal-reader.ts";
-import { compactObservedMessage, createMessageReferenceIndex, ExitCodeObservation } from "./child-observations.ts";
-
-const liveProjection: Projection = (path, root) => {
-	if (!path.length) return true;
-	if (["messages", "toolResults"].includes(String(path[0]))) return false;
-	if (path[0] === "entry") return path.length === 1 || ["id", "type", "parentId", "timestamp", "customType", "usage", "provider", "model"].includes(String(path[1])) ? 4096 : false;
-	if (path[0] === "assistantMessageEvent") return path.length === 1 || ["type", "delta", "contentIndex"].includes(String(path[1])) ? 8192 : false;
-	if (path[0] === "result" && root?.type !== "result") return false;
-	if (path[0] === "message") {
-		if (path.length > 1 && !["role", "timestamp", "provider", "model", "responseModel", "usage", "stopReason", "errorMessage", "toolCallId", "toolName", "isError", "content", "details"].includes(String(path[1]))) return false;
-		if (path[1] === "content" && root?.type !== "message_end") return false;
-		if (path[1] === "content" && path.length === 2) return 4096;
-		if (path[1] === "details") return path.length === 2 || ["preview", "modifiedFiles"].includes(String(path[2])) ? 4096 : false;
-		if (path[1] === "content" && path.length > 3) {
-			if (path[3] === "thinking" || path[3] === "data") return false;
-			if (path[3] === "text") return root?.message?.role === "assistant" ? true : 4096;
-			if (path[3] === "arguments") return root?.message?.content?.[Number(path[2])]?.name === "structured_output" ? true : nativeProjection(path, root);
-		}
-	}
-	// ponytail: explicitly consumed tool arguments and structured reports must
-	// fit their guard/schema consumer's heap; lifecycle aggregates are skipped.
-	return true;
-};
-const liveKeyLimit = (path: readonly (string | number)[]) => path[0] === "args" || path[0] === "structured_output" || path.includes("arguments") ? Infinity : 4096;
+import { ChildObservationSpool } from "./child-observation-spool.ts";
+import { ChildStreamObserver } from "./child-stream-observer.ts";
+import { ChildEventObserver } from "./child-event-observer.ts";
+import { accountNativeChild } from "./child-native-accounting.ts";
+import { childExecutionOutcome } from "./child-execution-outcome.ts";
+import { errorMessage as errorText } from "../../shared/unknown.ts";
+import { nonempty } from "./child-presence.ts";
+import type { ChildAttemptOptions, ChildAttemptResult } from "./child-attempt-types.ts";
+export { buildChildInvocation } from "./child-invocation.ts";
+export type {
+  ChildEvent,
+  ChildAttemptResult,
+  ChildAttemptControl,
+  NativeAttemptSegment,
+} from "./child-attempt-types.ts";
 
-export function buildChildInvocation(input: Omit<Parameters<typeof buildPiArgs>[0], "baseArgs"> & { nativeFinalization?: NativeFinalizationConfig }): {
-	args: string[];
-	env: Record<string, string | undefined>;
-	tempDir?: string;
-	claudeCodeInvocation?: ClaudeCodeInvocation;
-} {
-	const model = applyThinkingSuffix(input.model, input.thinking);
-	if (!model || !isClaudeCodeModel(model)) {
-		if (input.orchestratorIntercomTarget) {
-			const bridged = applyIntercomBridgeToAgent({ systemPrompt: input.systemPrompt ?? "",
-				tools: input.tools, extensions: input.extensions }, resolveIntercomBridge(input.orchestratorIntercomTarget));
-			input = { ...input, systemPrompt: bridged.systemPrompt, tools: bridged.tools, extensions: bridged.extensions };
-		}
-		const built = buildPiArgs({ ...input, structuredOutput: input.nativeFinalization ? undefined : input.structuredOutput, baseArgs: ["--mode", "json", "-p"] });
-		if (input.nativeFinalization) {
-			const runtime = nativeFinalizationLaunch(input.nativeFinalization);
-			built.args.push("--extension", runtime.extension);
-			Object.assign(built.env, runtime.env);
-			const tools = built.args.indexOf("--tools");
-			if (tools >= 0 && !built.args[tools + 1]!.split(",").includes("structured_output")) built.args[tools + 1] += ",structured_output";
-		}
-		return built;
-	}
-	const claudeCodeInvocation = buildClaudeCodeInvocation({ ...input, model, systemPrompt: input.systemPrompt ?? undefined,
-		sessionName: input.intercomSessionName, outputSchema: input.structuredOutput?.schema });
-	return { args: claudeCodeInvocation.args, env: claudeCodeInvocation.env, claudeCodeInvocation };
+type StopOutcome = Pick<ChildAttemptResult, "error" | "timedOut" | "interrupted">;
+function initialResult(model?: string): ChildAttemptResult {
+  return {
+    stderr: "",
+    exitCode: 0,
+    messages: [],
+    model,
+    usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 },
+    finalOutput: "",
+    observedCompletedMutation: false,
+    durationMs: 0,
+  };
 }
-
-export interface ChildEvent {
-	type?: string;
-	assistantMessageEvent?: Parameters<typeof updateStreamingText>[1]["assistantMessageEvent"];
-	message?: Message;
-	toolCallId?: string;
-	toolName?: string;
-	args?: Record<string, unknown>;
-	isError?: boolean;
+function nativeSessionFile(options: ReadonlyInput<ChildAttemptOptions>): string | undefined {
+  if (options.claudeCodeInvocation) {
+    return;
+  }
+  const index = options.args.indexOf("--session-dir");
+  const directory = index >= 0 ? options.args.at(index + 1) : undefined;
+  return (
+    options.sessionFile ??
+    (nonempty(directory) ? (findLatestSessionFile(directory) ?? undefined) : undefined)
+  );
 }
 
-export interface NativeAttemptSegment {
-	event: NativeFinalizationEvent;
-	messages: Message[];
-	usage: Usage;
-	durationMs: number;
-	execution?: Pick<ChildAttemptResult, "exitCode" | "error" | "interrupted" | "timedOut" | "resourceLimitExceeded" | "terminalFailure">;
-}
+/** One process-group owner; event accounting, observation retention and native review are separate. */
+class ChildAttemptRunner {
+  private readonly options: ReadonlyInput<ChildAttemptOptions>;
+  private readonly completion = Promise.withResolvers<ChildAttemptResult>();
+  private readonly startedAt = Date.now();
+  private readonly spool: ReadonlyInput<Pick<ChildObservationSpool, keyof ChildObservationSpool>>;
+  private readonly events: ChildEventObserver;
+  private readonly stream: ChildStreamObserver;
+  private readonly lifecycle: ReturnType<typeof attachChildProcessLifecycle>;
+  private resourceTimer?: NodeJS.Timeout;
+  private abortListener?: Disposable;
+  private interruptListener?: Disposable;
+  private receiverFailed = false;
+  private settled = false;
+  private readonly pid?: number;
 
-export interface ChildAttemptResult {
-	accounting?: { state: "complete" | "incomplete"; error?: string };
-	nativeSessionId?: string;
-	terminalLeafId?: string | null;
-	terminalEntryId?: string;
-	effectiveConfiguration?: { model?: string; thinking?: string; modelRecordedAt?: number };
-	attemptBaseline?: string[];
-	auditPath?: string;
-	auditSaveError?: string;
-	auditRecords?: Array<{ kind: string; messageNumber?: number; offset: number; length: number }>;
-	nativeReferences?: Array<{ messageNumber?: number; entryId: string }>;
-	messageCount?: number;
-	finalization?: NativeAttemptSegment[];
-	stderr: string;
-	agentProcessExit?: AgentProcessExit;
-	exitCode: number;
-	messages: Message[];
-	usage: Usage;
-	model?: string;
-	error?: string;
-	finalOutput: string;
-	interrupted?: boolean;
-	timedOut?: boolean;
-	terminalFailure?: boolean;
-	observedCompletedMutation: boolean;
-	resourceLimitExceeded?: ResourceLimitExceeded;
-	durationMs: number;
-}
+  constructor(
+    options: ReadonlyInput<ChildAttemptOptions>,
+    baseline: NativeBaseline,
+    spool: ReadonlyInput<Pick<ChildObservationSpool, keyof ChildObservationSpool>>,
+  ) {
+    this.options = options;
+    this.spool = spool;
+    const command = options.claudeCodeInvocation ?? getPiSpawnCommand(options.args);
+    const child = spawn(command.command, [...command.args], {
+      cwd: options.cwd,
+      env: {
+        ...process.env,
+        ...options.env,
+        ...getSubagentDepthEnv(options.maxSubagentDepth),
+        PI_SUBAGENT_NATIVE_BASELINE_COUNT: baseline.legacy ? String(baseline.entryCount) : "",
+      },
+      stdio: ["ignore", "pipe", "pipe"],
+      detached: true,
+    });
+    this.pid = child.pid;
+    this.lifecycle = attachChildProcessLifecycle(child);
+    this.events = new ChildEventObserver(
+      options,
+      baseline,
+      {
+        observeLifecycle: (type) => this.lifecycle.observeEvent(type),
+        stopping: () => this.lifecycle.stopping,
+        stop: (outcome) => this.stop(outcome),
+        resourceLimit: (kind, limit, observed) => this.resourceLimit(kind, limit, observed),
+        resetTimer: () => this.resetResourceTimer(),
+        reference: (entry) => this.stream.reference(entry),
+      },
+      this.startedAt,
+    );
+    this.stream = new ChildStreamObserver(this.spool, {
+      claude: options.claudeCodeInvocation !== undefined,
+      sessionFile: options.sessionFile,
+      consume: (value, textWritten) => this.events.process(value, textWritten),
+      output: options.onOutput,
+      rawLine: options.onRawLine,
+    });
+    child.stdout.on("data", (bytes: Buffer) => this.receive(bytes));
+    child.stderr.setEncoding("utf8");
+    child.stderr.on("data", (text: string) => this.receiveStderr(text));
+    child.on("close", (code, signal) => this.finish(code, signal));
+    child.on("error", (error) => this.finish(1, undefined, error));
+  }
+  completed(): Promise<ChildAttemptResult> {
+    return this.completion.promise;
+  }
 
-export interface ChildAttemptControl {
-	pid?: number;
-	readonly stopping: boolean;
-	stop(outcome: Pick<ChildAttemptResult, "error" | "timedOut" | "interrupted">): void;
-}
+  start(): void {
+    this.listenForCancellation();
+    this.resetResourceTimer();
+    const lifecycle = this.lifecycle;
+    this.options.onStart?.(
+      {
+        pid: this.pid,
+        get stopping() {
+          return lifecycle.stopping;
+        },
+        stop: (outcome) => this.stop(outcome),
+      },
+      this.events.result,
+    );
+  }
 
-interface ChildAttemptOptions {
-	args: string[];
-	cwd: string;
-	env?: Record<string, string | undefined>;
-	agent: string;
-	model?: string;
-	maxSubagentDepth?: number;
-	maxExecutionTimeMs?: number;
-	maxTokens?: number;
-	claudeCodeInvocation?: ClaudeCodeInvocation;
-	sessionFile?: string;
-	auditPath?: string;
-	structuredOutput?: StructuredOutputRuntime;
-	reportRuntime?: StructuredOutputRuntime;
-	nativeFinalization?: NativeFinalizationConfig;
-	signal?: AbortSignal;
-	interruptSignal?: AbortSignal;
-	onStart?: (control: ChildAttemptControl, result: ChildAttemptResult) => void;
-	onEvent?: (event: ChildEvent, result: ChildAttemptResult, mutation?: MutationToolResult) => void;
-	onFailure?: (result: ChildAttemptResult) => void;
-	onOutput?: (text: string) => void;
-	onRawLine?: (stream: "stdout" | "stderr", line: string) => void;
-	onStderr?: (text: string) => void;
+  private stop(outcome: StopOutcome): void {
+    if (this.settled) {
+      return;
+    }
+    Object.assign(this.events.result, outcome);
+    this.events.result.durationMs = Date.now() - this.startedAt;
+    if (nonempty(outcome.error)) {
+      this.options.onOutput?.(`${outcome.error}\n`);
+    }
+    this.options.onFailure?.(this.events.result);
+    this.lifecycle.terminate();
+  }
+  private resourceLimit(
+    kind: ResourceLimitExceeded["kind"],
+    limit: number,
+    observed?: number,
+  ): void {
+    const result = this.events.result;
+    if (
+      this.settled ||
+      result.resourceLimitExceeded ||
+      result.timedOut === true ||
+      this.lifecycle.stopping
+    ) {
+      return;
+    }
+    const message = formatResourceLimitExceeded({
+      agent: this.options.agent,
+      kind,
+      limit,
+      observed,
+    });
+    result.resourceLimitExceeded = {
+      kind,
+      limit,
+      ...(observed !== undefined ? { observed } : {}),
+      message,
+    };
+    this.stop({ error: message });
+  }
+  private resetResourceTimer(): void {
+    clearTimeout(this.resourceTimer);
+    const limit = this.options.maxExecutionTimeMs;
+    if (limit === undefined) {
+      return;
+    }
+    this.resourceTimer = setTimeout(
+      () => {
+        this.events.sync();
+        if (Date.now() - this.events.boundaries.startedAt >= limit) {
+          this.resourceLimit("maxExecutionTimeMs", limit);
+        } else {
+          this.resetResourceTimer();
+        }
+      },
+      Math.max(0, limit - (Date.now() - this.events.boundaries.startedAt)),
+    );
+    this.resourceTimer.unref();
+  }
+  private listenForCancellation(): void {
+    const { signal, interruptSignal } = this.options;
+    if (signal) {
+      this.abortListener = addAbortListener(signal, () => {
+        const reason: unknown = signal.reason;
+        const timedOut = reason instanceof Error && reason.name === "TimeoutError";
+        this.stop({
+          error: timedOut ? reason.message : "Subagent cancelled.",
+          timedOut: timedOut || undefined,
+          interrupted: false,
+        });
+      });
+    }
+    if (interruptSignal) {
+      this.interruptListener = addAbortListener(interruptSignal, () => {
+        if (
+          signal?.aborted === true ||
+          this.events.result.resourceLimitExceeded ||
+          this.events.result.timedOut === true
+        ) {
+          return;
+        }
+        this.stop({ interrupted: true, error: undefined });
+      });
+    }
+  }
+  private receive(bytes: Buffer): void {
+    try {
+      if (this.receiverFailed) {
+        this.stream.saveUnparsed(bytes);
+      } else {
+        this.stream.write(bytes);
+      }
+    } catch (error) {
+      this.receiverFailed = true;
+      this.events.result.terminalFailure = true;
+      this.stop({ error: `Cannot receive child events: ${errorText(error)}` });
+    }
+  }
+  private receiveStderr(text: string): void {
+    try {
+      this.spool.writeStderr(text);
+      this.events.result.stderr = (this.events.result.stderr + text).slice(-16384);
+      this.options.onStderr?.(text);
+    } catch (error) {
+      this.events.result.terminalFailure = true;
+      this.stop({ error: `Cannot save child diagnostics: ${errorText(error)}` });
+    }
+  }
+  private drainObservations(): void {
+    try {
+      if (!this.receiverFailed) {
+        this.stream.finish();
+      }
+    } catch (error) {
+      this.receiverFailed = true;
+      this.events.result.error ??= errorText(error);
+      this.events.result.terminalFailure = true;
+    }
+    try {
+      this.events.sync();
+    } catch (error) {
+      this.events.result.error ??= `Cannot read finalization boundary: ${errorText(error)}`;
+      this.events.result.terminalFailure = true;
+    }
+  }
+  private finish(
+    code: number | null,
+    signal?: NodeJS.Signals | null,
+    spawnError?: Readonly<Error>,
+  ): void {
+    if (this.settled) {
+      return;
+    }
+    this.drainObservations();
+    this.settled = true;
+    clearTimeout(this.resourceTimer);
+    this.abortListener?.[Symbol.dispose]();
+    this.interruptListener?.[Symbol.dispose]();
+    const result = this.events.result;
+    result.agentProcessExit = this.lifecycle.agentProcessExit;
+    result.durationMs = Date.now() - this.startedAt;
+    Object.assign(
+      result,
+      childExecutionOutcome({
+        result,
+        options: this.options,
+        code,
+        signal,
+        spawnError,
+        stopping: this.lifecycle.stopping,
+        settledCleanup: this.lifecycle.settledCleanup,
+        cleanAssistantStop: this.events.cleanAssistantStop,
+        assistantError: this.events.assistantError,
+      }),
+    );
+    result.finalOutput =
+      result.resourceLimitExceeded?.message ??
+      (this.events.lastOutput.length > 0 ? this.events.lastOutput : this.stream.rawOutput.trim());
+    const boundary = this.events.boundaries.finish(result);
+    result.finalization = boundary.finalization;
+    if (boundary.missing) {
+      result.error = "Native self-review boundary did not return a result.";
+      result.exitCode = 1;
+      result.terminalFailure = true;
+    }
+    this.finalizeAccounting();
+    this.completion.resolve(result);
+  }
+  private finalizeAccounting(): void {
+    const result = this.events.result;
+    const native = accountNativeChild({
+      file: nativeSessionFile(this.options),
+      result,
+      baseline: this.events.baseline,
+      acceptedEntries: this.events.acceptedEntries,
+      reference: (entry) => this.stream.reference(entry),
+      observations: () => this.stream.observed(),
+    });
+    result.accounting = native.accounting;
+    result.nativeSessionId = native.nativeSessionId;
+    result.terminalEntryId = native.terminalEntryId;
+    result.terminalLeafId = native.terminalLeafId;
+    result.effectiveConfiguration = native.effectiveConfiguration;
+    if (native.usage) {
+      result.usage = native.usage;
+    }
+    for (const [index, segment] of (result.finalization ?? []).entries()) {
+      const usage = native.segmentUsage?.at(index);
+      if (usage) {
+        segment.usage = usage;
+      }
+    }
+    const retained = this.stream.published(native.publishedIds);
+    for (const item of retained) {
+      if (nonempty(item.nativeEntryId)) {
+        (result.nativeReferences ??= []).push({
+          messageNumber: item.number,
+          entryId: item.nativeEntryId,
+        });
+      }
+    }
+    const audit = this.spool.retain(retained, this.receiverFailed);
+    result.auditPath = audit.auditPath;
+    result.auditSaveError = audit.auditSaveError;
+    result.auditRecords = audit.auditRecords?.slice();
+  }
 }
 
 /** One owned process group and finalized JSON event stream for either native backend. */
-export function runChildAttempt(options: ChildAttemptOptions): Promise<ChildAttemptResult> {
-	const result: ChildAttemptResult = {
-		stderr: "", exitCode: 0, messages: [], model: options.model,
-		usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 },
-		finalOutput: "", observedCompletedMutation: false, durationMs: 0,
-	};
-	if (options.signal?.aborted || options.interruptSignal?.aborted) {
-		Object.assign(result, resolveExecutionOutcome({ result, signal: options.signal, interruptSignal: options.interruptSignal }));
-		result.finalOutput = result.error ?? "Interrupted. Waiting for explicit next action.";
-		return Promise.resolve(result);
-	}
-	const sessionDirectoryArg = options.args.indexOf("--session-dir");
-	const sessionDirectory = sessionDirectoryArg >= 0 ? options.args[sessionDirectoryArg + 1] : undefined;
-	const nativeSessionFile = () => options.claudeCodeInvocation ? undefined : options.sessionFile ?? (sessionDirectory ? findLatestSessionFile(sessionDirectory) ?? undefined : undefined);
-	let baseline: Set<string>;
-	let baselineSnapshot: ReturnType<typeof snapshotNativeBaseline>;
-	try { baselineSnapshot = snapshotNativeBaseline(nativeSessionFile()); baseline = baselineSnapshot.ids; } catch (error) {
-		return Promise.resolve({ ...result, exitCode: 1, terminalFailure: true, error: `Cannot capture native usage baseline: ${error instanceof Error ? error.message : String(error)}` });
-	}
-	const streamId = randomUUID();
-	let wireDirectory = "", wireFd = -1, textFd = -1, stderrFd = -1;
-	try {
-		const parent = options.auditPath ? path.dirname(options.auditPath) : tmpdir();
-		mkdirSync(parent, { recursive: true });
-		wireDirectory = mkdtempSync(path.join(parent, ".pi-subagents-wire-"));
-		wireFd = openSync(path.join(wireDirectory, "stdout"), "wx+");
-		textFd = openSync(path.join(wireDirectory, "text"), "wx+");
-		stderrFd = openSync(path.join(wireDirectory, "stderr"), "wx+");
-	} catch (error) {
-		if (wireFd >= 0) closeSync(wireFd);
-		if (textFd >= 0) closeSync(textFd);
-		if (stderrFd >= 0) closeSync(stderrFd);
-		if (wireDirectory) rmSync(wireDirectory, { recursive: true, force: true });
-		return Promise.resolve({ ...result, exitCode: 1, terminalFailure: true, error: `Cannot prepare child observations: ${String(error)}` });
-	}
-	return new Promise((resolve) => {
-		const startedAt = Date.now();
-		const invocation = options.claudeCodeInvocation;
-		const command = invocation ?? getPiSpawnCommand(options.args);
-		const child = spawn(command.command, command.args, {
-			cwd: options.cwd,
-			env: { ...process.env, ...options.env, ...getSubagentDepthEnv(options.maxSubagentDepth), PI_SUBAGENT_NATIVE_BASELINE_COUNT: baselineSnapshot.legacy ? String(baselineSnapshot.entryCount) : "" },
-			stdio: ["ignore", "pipe", "pipe"],
-			detached: true,
-		});
-		const lifecycle = attachChildProcessLifecycle(child);
-		const mutations = createMutationCompletionTracker();
-		const toolLoop = createRepeatedSubagentCallGuardState();
-		const wirePath = path.join(wireDirectory, "stdout");
-		let textOffset = 0;
-		const observations: Array<{ start: number; end: number; kind: string; number?: number; message?: Message; nativeEntryId?: string }> = [];
-		const references = createMessageReferenceIndex<(typeof observations)[number]>();
-		const referenceMessage = (entry: NativeUsageMetadata) => baseline.has(entry.id) ? undefined : references.reference(entry);
-		let rawOutput = "", lastOutput = "", boundariesCursor = 0;
-		let receiverFailed = false;
-		const acceptedEntries = new Map<string, NativeUsageMetadata>();
-		let nativeMessageCount = 0;
-		const pendingBoundary = Symbol("pending boundary");
-		let textWritten = false, exitObservation = new ExitCodeObservation(), firstTextPath: string | undefined;
-		let outputTextPath: string | undefined, pendingSurrogate = "";
-		let reproject = false, replayOutput = false;
-		result.attemptBaseline = [...baseline];
-		let assistantError: string | undefined;
-		let cleanAssistantStop = false;
-		let settled = false;
-		let resourceTimer: NodeJS.Timeout | undefined;
-		let attemptStartedAt = startedAt;
-		let messageOffset = 0;
-		// maxTokens bounds this assistant; billing also includes nested tools and summaries.
-		let assistantTokens = 0;
-		let attemptAssistantTokens = 0;
-		const attemptUsage = { ...result.usage };
-		const resetResourceTimer = () => {
-			clearTimeout(resourceTimer);
-			if (options.maxExecutionTimeMs !== undefined) {
-				const limit = options.maxExecutionTimeMs;
-				resourceTimer = setTimeout(() => {
-					syncFinalization();
-					if (Date.now() - attemptStartedAt >= limit) resourceLimit("maxExecutionTimeMs", limit);
-					else resetResourceTimer();
-				}, Math.max(0, limit - (Date.now() - attemptStartedAt)));
-				resourceTimer.unref();
-			}
-		};
-
-		const stop = (outcome: Pick<ChildAttemptResult, "error" | "timedOut" | "interrupted">) => {
-			if (settled) return;
-			Object.assign(result, outcome);
-			result.durationMs = Date.now() - startedAt;
-			if (outcome.error) options.onOutput?.(`${outcome.error}\n`);
-			options.onFailure?.(result);
-			lifecycle.terminate();
-		};
-		const resourceLimit = (kind: ResourceLimitExceeded["kind"], limit: number, observed?: number) => {
-			if (settled || result.resourceLimitExceeded || result.timedOut || lifecycle.stopping) return;
-			const message = formatResourceLimitExceeded({ agent: options.agent, kind, limit, observed });
-			result.resourceLimitExceeded = { kind, limit, ...(observed !== undefined ? { observed } : {}), message };
-			stop({ error: message });
-		};
-		const syncFinalization = () => {
-			if (!options.nativeFinalization) return;
-			const file = path.join(path.dirname(options.nativeFinalization.reportRuntime.schemaPath), "boundaries.jsonl");
-			try { scanJournal(file, () => true, ({ value, end }) => {
-				const marker = value as NativeFinalizationEvent;
-				if (marker.nonce !== options.nativeFinalization!.nonce) throw new Error("Unexpected finalization nonce");
-				if (marker.messageCount > nativeMessageCount) throw pendingBoundary;
-				const messages = result.messages.filter((message) => ["assistant", "user", "toolResult"].includes(message.role));
-				const segmentMessages = messages.slice(messageOffset, marker.messageCount);
-				const usage: Usage = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 };
-				let segmentAssistantTokens = 0;
-				for (const message of segmentMessages) {
-					if (message.role === "assistant") {
-						usage.turns++;
-						segmentAssistantTokens += (message.usage?.input ?? 0) + (message.usage?.output ?? 0);
-					}
-					if ((message.role === "assistant" || message.role === "toolResult") && message.usage) addUsage(usage, message.usage);
-				}
-				(result.finalization ??= []).push({ event: marker, messages: segmentMessages, usage, durationMs: marker.at - attemptStartedAt });
-				if (options.maxTokens !== undefined && segmentAssistantTokens >= options.maxTokens) resourceLimit("maxTokens", options.maxTokens, segmentAssistantTokens);
-				if (options.maxExecutionTimeMs !== undefined && marker.at - attemptStartedAt >= options.maxExecutionTimeMs) resourceLimit("maxExecutionTimeMs", options.maxExecutionTimeMs);
-				if (marker.nextPrompt) {
-					messageOffset = marker.messageCount;
-					attemptAssistantTokens += segmentAssistantTokens;
-					for (const key of ["input", "output", "cacheRead", "cacheWrite", "cost", "turns"] as const) attemptUsage[key] += usage[key];
-					attemptStartedAt = marker.at;
-					resetResourceTimer();
-				}
-				options.onEvent?.(marker, result);
-				boundariesCursor = end;
-			}, { policy: "live", start: boundariesCursor }); } catch (error) { if (error !== pendingBoundary && (error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
-		};
-		const processEvent = (input: ChildEvent) => {
-			let event = input;
-			if (!event || typeof event !== "object") return;
-			if (event.type === "message_end" && !event.message) throw new Error("Child message_end event is missing its message");
-			if (event.type !== "message_update") syncFinalization();
-			if (event.type === "subagent.native_baseline") {
-				const value = event as ChildEvent & { sessionId: string; entryIds: string[] };
-				if (!baselineSnapshot.legacy || value.sessionId !== baselineSnapshot.sessionId || !Array.isArray(value.entryIds)
-					|| new Set(value.entryIds).size !== baselineSnapshot.entryCount || value.entryIds.some((id) => typeof id !== "string" || !id)) throw new Error("Cannot reconcile native legacy baseline");
-				baseline.clear(); baseline.add(value.sessionId); for (const id of value.entryIds) baseline.add(id);
-				result.attemptBaseline = [...baseline];
-			}
-			if (event.type === "subagent.native") {
-				const native = event as ChildEvent & { sessionId: string; leafId: string | null; persisted?: boolean; configuration: ChildAttemptResult["effectiveConfiguration"]; entries: Array<NativeUsageMetadata & { message?: { role: string; timestamp: number; toolCallId?: string } }> };
-				result.nativeSessionId = native.sessionId;
-				result.terminalLeafId = native.leafId;
-				result.terminalEntryId = native.entries.at(-1)?.id ?? result.terminalEntryId;
-				result.effectiveConfiguration = native.configuration;
-				if (!native.persisted) for (const entry of native.entries) acceptedEntries.set(entry.id, entry);
-				const nativeReferences = [];
-				if (native.persisted) for (const entry of native.entries) if (entry.message) {
-					const observation = referenceMessage(entry);
-					if (observation) {
-						nativeReferences.push({ messageNumber: observation.number, entryId: entry.id });
-					}
-				}
-				Object.assign(event, { nativeReferences, referenceState: "observed" });
-			}
-			lifecycle.observeEvent(invocation && event.type === "result" ? "agent_settled" : event.type);
-			if (invocation && event.type === "result") {
-				const nativeResult = event as ClaudeCodeResultEvent;
-				// Claude reports totals, not a native per-category cost receipt. Keep
-				// that observation rather than inventing zero-valued category costs.
-				result.accounting = { state: "incomplete", error: "Claude Code did not provide the complete native usage/cost receipt. Reported totals and its audit were retained." };
-				if (options.structuredOutput && nativeResult.structured_output !== undefined) {
-					mkdirSync(path.dirname(options.structuredOutput.outputPath), { recursive: true });
-					writeFileSync(options.structuredOutput.outputPath, `${JSON.stringify(nativeResult.structured_output)}\n`, "utf8");
-				}
-				const message = claudeCodeMessageFromResult(nativeResult, invocation.model.inputModel);
-				if (options.sessionFile) {
-					writeClaudeCodeSessionMetadata(options.sessionFile, {
-						sessionId: nativeResult.session_id || invocation.sessionId,
-						model: invocation.model.inputModel, cliModel: invocation.model.cliModel,
-						family: invocation.model.family, context: invocation.model.context, updatedAt: Date.now(),
-					});
-					const { result: _result, structured_output: _structured, ...observation } = nativeResult;
-					appendClaudeCodeMessage(options.sessionFile, message, observation);
-				}
-				event = { type: "message_end", message };
-			}
-			let mutation: MutationToolResult | undefined;
-			let loopFailure: string | undefined;
-			if (event.type === "tool_execution_start") {
-				loopFailure = recordToolStartForSubagentLoopGuard({ state: toolLoop, ...event, toolName: event.toolName, args: event.args });
-				mutations.recordToolStart({ id: event.toolCallId, toolName: event.toolName, args: event.args,
-					path: resolveCurrentPath(event.toolName, event.args), startedAt: Date.now() });
-				const args = extractToolArgsPreview(event.args ?? {});
-				if (event.toolName) options.onOutput?.(`${event.toolName}${args ? `: ${args}` : ""}\n`);
-			} else if (event.type === "tool_execution_end") {
-				loopFailure = recordToolEndForSubagentLoopGuard({ state: toolLoop, ...event, toolName: event.toolName, isError: event.isError });
-			} else if (event.type === "message_end" && event.message) {
-				const message = event.message;
-				if (message.role === "assistant" && !message.usage) result.accounting = { state: "incomplete", error: "Required assistant usage is unavailable; execution was not repeated." };
-				const final = getFinalOutput([message]);
-				if (final) lastOutput = final;
-				result.messages.push(compactObservedMessage(message));
-				if (["assistant", "user", "toolResult"].includes(message.role)) nativeMessageCount++;
-				result.messageCount = nativeMessageCount;
-				const text = extractTextFromContent(message.content);
-				if (textWritten) options.onOutput?.("\n");
-				else if (invocation && text) options.onOutput?.(`${text}\n`);
-				if ((message.role === "assistant" || message.role === "toolResult") && message.usage) {
-					try { addUsage(result.usage, message.usage, { id: `stream:${streamId}:${result.messages.length}`,
-						provider: message.role === "assistant" ? message.provider : undefined,
-						model: message.role === "assistant" ? message.responseModel ?? message.model : undefined });
-						validateNativeUsage(message.usage);
-					} catch (error) { result.accounting = { state: "incomplete", error: String(error) }; }
-				}
-				if (message.role === "toolResult") {
-					mutation = mutations.recordToolResult(message);
-					if (mutation?.completedMutation) result.observedCompletedMutation = true;
-				} else if (message.role === "assistant") {
-					result.model ??= providerQualifiedModelId(message.provider, message.model);
-					result.usage.turns++;
-					assistantTokens += (message.usage?.input ?? 0) + (message.usage?.output ?? 0);
-					if (message.errorMessage) assistantError = message.errorMessage;
-					cleanAssistantStop = message.stopReason === "stop" && !message.errorMessage
-						&& !message.content.some((part) => part.type === "toolCall");
-					if (cleanAssistantStop && text.trim()) assistantError = undefined;
-				}
-			}
-			result.durationMs = Date.now() - startedAt;
-			options.onEvent?.(event, result, mutation);
-			if (loopFailure && !lifecycle.stopping) {
-				result.terminalFailure = true;
-				stop({ error: loopFailure });
-			}
-			if (event.type === "message_end") syncFinalization();
-			const tokens = assistantTokens - attemptAssistantTokens;
-			if (options.maxTokens !== undefined && tokens >= options.maxTokens) resourceLimit("maxTokens", options.maxTokens, tokens);
-		};
-
-		const copyBytes = (fd: number, start: number, end: number, consume: (bytes: Buffer) => void) => {
-			const buffer = Buffer.allocUnsafe(64 * 1024);
-			for (let position = start; position < end;) {
-				const count = readSync(fd, buffer, 0, Math.min(buffer.length, end - position), position);
-				if (!count) throw new Error("Missing child audit bytes");
-				consume(buffer.subarray(0, count)); position += count;
-			}
-		};
-		const appendText = (text: string) => {
-			const bytes = Buffer.from(text);
-			for (let offset = 0; offset < bytes.length;) {
-				const count = writeSync(textFd, bytes, offset, bytes.length - offset, textOffset + offset);
-				if (!count) throw new Error("Cannot write child output spool");
-				offset += count;
-			}
-			textOffset += bytes.length;
-		};
-		const resetRecord = () => {
-			textWritten = false; exitObservation = new ExitCodeObservation(); firstTextPath = undefined;
-			pendingSurrogate = ""; outputTextPath = undefined; reproject = false; replayOutput = false;
-			textOffset = 0; ftruncateSync(textFd, 0);
-		};
-		const consumeMessageText = (path: readonly (string | number)[], text: string, root?: Record<string, any>) => {
-			if (root?.type !== "message_end" || path[0] !== "message" || path[1] !== "content" || path.at(-1) !== "text" && path.length !== 2) return;
-			const key = path.join(".");
-			if (outputTextPath !== key) {
-				if (pendingSurrogate) { textWritten = true; appendText(pendingSurrogate); }
-				pendingSurrogate = "";
-				if (textWritten && text) appendText("\n");
-				outputTextPath = key;
-			}
-			// Unpacked JSON escape tokens can split a surrogate pair. Join that one
-			// code unit before handing text to an output writer.
-			const joined = pendingSurrogate + text;
-			pendingSurrogate = /[\uD800-\uDBFF]/.test(joined.at(-1) ?? "") ? joined.at(-1)! : "";
-			const output = pendingSurrogate ? joined.slice(0, -1) : joined;
-			if (output) { textWritten = true; appendText(output); }
-			if (path.length !== 4) return;
-			firstTextPath ??= key;
-			if (firstTextPath === key) exitObservation.write(text);
-		};
-		const stdout = new JournalFrames((path, root) => {
-			if (invocation) return !path.length || ["type", "subtype", "is_error", "api_error_status", "result", "stop_reason", "session_id", "total_cost_usd", "usage", "modelUsage", "structured_output"].includes(String(path[0]));
-			if (path[0] === "message" && path[1] === "content" && !root?.type) replayOutput = true;
-			if (path[0] === "message" && path[1] === "content" && (!root?.type || path.at(-1) === "text" && !root.message?.role
-				|| path.includes("arguments") && !root.message?.content?.[Number(path[2])]?.name)) reproject = true;
-			return liveProjection(path, root);
-		}, ({ value: projected, start, end }) => {
-			if (!projected || typeof projected !== "object" || Array.isArray(projected)) { resetRecord(); return; }
-			let value = projected;
-			if (reproject && value.type === "message_end") {
-				// JSON member order is not semantic. Revisit only this selected value
-				// when attribution/call names appeared after their payloads.
-				for (let pass = 0; pass < 2; pass++) {
-					const known = value;
-					scanJournal(wirePath, (path, root) => liveProjection(path, { ...root, type: known.type,
-						message: { ...root?.message, role: known.message?.role, content: known.message?.content ?? root?.message?.content } }),
-					(record) => { value = record.value; }, { start, end, policy: "strict", keys: liveKeyLimit,
-						...(pass === 0 && replayOutput ? { stringChunk: (path, text, root) => consumeMessageText(path, text, { ...root, type: known.type }) } : {}) });
-				}
-			}
-			reproject = false; replayOutput = false;
-			if (pendingSurrogate) { textWritten = true; appendText(pendingSurrogate); }
-			pendingSurrogate = ""; outputTextPath = undefined;
-			const decoder = new StringDecoder("utf8");
-			copyBytes(textFd, 0, textOffset, (bytes) => options.onOutput?.(decoder.write(bytes)));
-			const tail = decoder.end(); if (tail) options.onOutput?.(tail);
-			if (exitObservation.value !== undefined && value.type === "message_end" && value.message?.role === "toolResult") value.message.observedExitCode = exitObservation.value;
-			processEvent(value as ChildEvent);
-			if (["message_end", "tool_execution_end"].includes(value.type) || invocation && (value.type !== "result" || !options.sessionFile)) {
-				const observation = { start, end, kind: value.type,
-					...(value.type === "message_end" ? { number: nativeMessageCount, message: result.messages.at(-1) } : {}) };
-				observations.push(observation);
-				references.add(observation);
-			}
-			resetRecord();
-		}, "inspect", 0, (start, end) => {
-			observations.push({ start, end, kind: "diagnostic" });
-			const decoder = new StringDecoder("utf8");
-			copyBytes(wireFd, start, end, (bytes) => {
-				const text = decoder.write(bytes);
-				rawOutput = (rawOutput + text).slice(-16384);
-				options.onOutput?.(text); options.onRawLine?.("stdout", text);
-			});
-			const tail = decoder.end(); if (tail) options.onOutput?.(tail);
-			resetRecord();
-		}, consumeMessageText, liveKeyLimit);
-		child.stderr.setEncoding("utf8");
-		child.stdout.on("data", (bytes: Buffer) => {
-			try { writeFileSync(wireFd, bytes); if (!receiverFailed) stdout.write(bytes); } catch (error) {
-				receiverFailed = true;
-				result.terminalFailure = true; stop({ error: `Cannot receive child events: ${String(error)}` });
-			}
-		});
-		child.stderr.on("data", (text: string) => {
-			try {
-				writeFileSync(stderrFd, text);
-				result.stderr = (result.stderr + text).slice(-16384);
-				options.onStderr?.(text);
-			} catch (error) {
-				result.terminalFailure = true; stop({ error: `Cannot save child diagnostics: ${String(error)}` });
-			}
-		});
-		const abortListener = options.signal && addAbortListener(options.signal, () => {
-			const reason = options.signal?.reason;
-			stop({ error: reason instanceof Error && reason.name === "TimeoutError" ? reason.message : "Subagent cancelled.",
-				timedOut: reason instanceof Error && reason.name === "TimeoutError" || undefined, interrupted: false });
-		});
-		const interruptListener = options.interruptSignal && addAbortListener(options.interruptSignal, () => {
-			if (options.signal?.aborted || result.resourceLimitExceeded || result.timedOut) return;
-			stop({ interrupted: true, error: undefined });
-		});
-		const finish = (code: number | null, signal?: NodeJS.Signals | null, spawnError?: Error) => {
-			if (settled) return;
-			// Sealed stdout may retain an EOF observation; native publication is verified separately.
-			try { if (!receiverFailed) stdout.finish(); } catch (error) { receiverFailed = true; result.error ??= String(error); result.terminalFailure = true; }
-			try { syncFinalization(); } catch (error) { result.error ??= `Cannot read finalization boundary: ${String(error)}`; result.terminalFailure = true; }
-			settled = true;
-			clearTimeout(resourceTimer);
-			abortListener?.[Symbol.dispose]();
-			interruptListener?.[Symbol.dispose]();
-			result.agentProcessExit = lifecycle.agentProcessExit;
-			result.durationMs = Date.now() - startedAt;
-			const reportRuntime = options.nativeFinalization?.reportRuntime ?? options.reportRuntime;
-			const report = reportRuntime && readFinalizationReport(result.messages, reportRuntime).output;
-			const structured = options.structuredOutput && readStructuredOutput(options.structuredOutput);
-			const completedOutput = cleanAssistantStop || report || structured && !structured.error;
-			if (report) assistantError = undefined;
-			result.error ??= assistantError ?? spawnError?.message;
-			const drainedSuccess = lifecycle.settledCleanup && (cleanAssistantStop || report) && !result.error;
-			if (code !== 0 && !result.error && !drainedSuccess && !result.interrupted) result.error = result.stderr.trim() || undefined;
-			result.exitCode = result.timedOut ? 124 : result.resourceLimitExceeded || result.terminalFailure ? 1
-				: result.interrupted || drainedSuccess ? 0 : lifecycle.stopping || signal ? code ?? 1 : code ?? 0;
-			if (result.interrupted) result.error = undefined;
-			if (result.exitCode === 0 && !result.interrupted && !result.error && !completedOutput) {
-				result.error = options.nativeFinalization ? "Native self-review boundary did not return a result." : "Child exit was observed, but no completed assistant result was returned.";
-				result.exitCode = 1; result.terminalFailure = true;
-			}
-			result.finalOutput = result.resourceLimitExceeded?.message ?? (lastOutput || rawOutput.trim());
-			if (options.nativeFinalization) {
-				const previous = result.finalization?.at(-1);
-				if (previous?.event.nextPrompt) {
-					const usage = { ...result.usage, contributions: result.usage.contributions?.slice(attemptUsage.contributions?.length ?? 0) };
-					for (const key of ["input", "output", "cacheRead", "cacheWrite", "cost", "turns"] as const) usage[key] -= attemptUsage[key];
-					result.finalization!.push({ event: { type: FINALIZATION_EVENT, nonce: options.nativeFinalization.nonce,
-						turn: previous.event.turn + 1, messageCount: result.messages.length, at: Date.now(), submission: { output: "" }, resolvedOutput: previous.event.resolvedOutput },
-						messages: result.messages.slice(messageOffset), usage, durationMs: Date.now() - attemptStartedAt });
-				}
-				const final = result.finalization?.at(-1);
-				if (final) {
-					if (final.event.turn > 0) final.event.submission = { ...readFinalizationReport(result.messages, options.nativeFinalization.reportRuntime, { messageOffset }), error: final.event.submission.error };
-					final.execution = { exitCode: result.exitCode, error: result.error, interrupted: result.interrupted,
-						timedOut: result.timedOut, resourceLimitExceeded: result.resourceLimitExceeded, terminalFailure: result.terminalFailure };
-				} else if (result.exitCode === 0 && !result.error && !result.interrupted) {
-					result.error = "Native self-review boundary did not return a result.";
-					result.exitCode = 1;
-					result.terminalFailure = true;
-				}
-			}
-			const publishedIds = new Set<string>();
-			try {
-				const native = readNativeUsage(nativeSessionFile(), baseline, result.finalization?.map((segment) => segment.event.lastEntryId), {
-					onEntry: (entry) => { if (entry.type === "message") { publishedIds.add(entry.id); referenceMessage(entry); } },
-					onBoundary: ({ sessionId, lastEntryId }) => { result.nativeSessionId = sessionId; result.terminalEntryId = lastEntryId; },
-				});
-				const accepted = !native && result.nativeSessionId && acceptedEntries.size
-					? nativeUsageCollector(result.nativeSessionId, baseline, result.finalization?.map((segment) => segment.event.lastEntryId)) : undefined;
-				if (accepted) for (const entry of acceptedEntries.values()) accepted.append(entry);
-				const totals = native ?? accepted?.totals;
-				if (totals) {
-					if (native && observations.some((item) => item.message && (item.message.role === "assistant" || item.message.role === "toolResult" && item.message.usage)
-						&& (!item.nativeEntryId || !publishedIds.has(item.nativeEntryId)))) throw new Error("Finalized message usage has no verified native commit; its reported usage and audit remain available.");
-					result.accounting = { state: "complete" };
-					result.usage = sumAttemptUsage(totals.map((usage) => ({ model: result.model ?? "default", success: true, usage })));
-					result.finalization?.forEach((segment, index) => { segment.usage = totals[index]!; });
-				}
-			} catch (error) {
-				result.accounting = { state: "incomplete", error: `Cannot read finalized native usage: ${error instanceof Error ? error.message : String(error)}` };
-			}
-			for (const item of observations) if (item.nativeEntryId) {
-				if (publishedIds.has(item.nativeEntryId)) (result.nativeReferences ??= []).push({ messageNumber: item.number, entryId: item.nativeEntryId });
-				else item.nativeEntryId = undefined;
-			}
-			result.accounting ??= { state: "complete" };
-			const file = nativeSessionFile();
-			if (!result.effectiveConfiguration && file) try {
-				const journal = new NativeJournal(file, "inspect", true);
-				const terminal = journal.records.findLast((record) => record.value.type !== "session");
-				result.terminalEntryId ??= terminal?.value.id;
-				result.terminalLeafId ??= result.terminalEntryId;
-				result.effectiveConfiguration = journal.configuration(undefined, result.terminalLeafId);
-			} catch (error) { result.accounting = { state: "incomplete", error: result.accounting.error ?? `Cannot capture terminal native selection: ${String(error)}` }; }
-			const retained = receiverFailed ? [{ start: 0, end: fstatSync(wireFd).size, kind: "receiver_failure", number: undefined }] : observations.filter((item) => !item.nativeEntryId);
-			const auditPath = options.auditPath ?? path.join(wireDirectory, "observations.log");
-			const stderrLength = fstatSync(stderrFd).size;
-			let retainedWire = false;
-			try { if (retained.length || stderrLength) {
-				const audit = openSync(auditPath, "a", 0o600);
-				try {
-					let offset = fstatSync(audit).size;
-					for (const item of retained) {
-						copyBytes(wireFd, item.start, item.end, (bytes) => writeFileSync(audit, bytes));
-						(result.auditRecords ??= []).push({ kind: item.kind, messageNumber: item.number, offset, length: item.end - item.start });
-						offset += item.end - item.start;
-					}
-					if (stderrLength) {
-						copyBytes(stderrFd, 0, stderrLength, (bytes) => writeFileSync(audit, bytes));
-						(result.auditRecords ??= []).push({ kind: "stderr", offset, length: stderrLength });
-					}
-					result.auditPath = auditPath;
-				} finally { closeSync(audit); }
-			}
-			} catch (error) { retainedWire = true; result.auditSaveError = String(error); result.auditPath = wireDirectory; }
-			finally {
-				closeSync(wireFd); closeSync(textFd); closeSync(stderrFd);
-				if (!retainedWire) {
-					if (result.auditPath?.startsWith(`${wireDirectory}${path.sep}`)) {
-						rmSync(wirePath); rmSync(path.join(wireDirectory, "text")); rmSync(path.join(wireDirectory, "stderr"));
-					} else rmSync(wireDirectory, { recursive: true, force: true });
-				}
-			}
-			resolve(result);
-		};
-		child.on("close", (code, signal) => finish(code, signal));
-		child.on("error", (error) => finish(1, undefined, error));
-		resetResourceTimer();
-		options.onStart?.({ pid: child.pid, get stopping() { return lifecycle.stopping; }, stop }, result);
-	});
+export async function runChildAttempt(
+  options: ReadonlyInput<ChildAttemptOptions>,
+): Promise<ChildAttemptResult> {
+  const result = initialResult(options.model);
+  if (options.signal?.aborted === true || options.interruptSignal?.aborted === true) {
+    Object.assign(
+      result,
+      resolveExecutionOutcome({
+        result,
+        signal: options.signal,
+        interruptSignal: options.interruptSignal,
+      }),
+    );
+    result.finalOutput = result.error ?? "Interrupted. Waiting for explicit next action.";
+    return result;
+  }
+  let baseline: NativeBaseline;
+  try {
+    baseline = snapshotNativeBaseline(nativeSessionFile(options));
+  } catch (error) {
+    return {
+      ...result,
+      exitCode: 1,
+      terminalFailure: true,
+      error: `Cannot capture native usage baseline: ${errorText(error)}`,
+    };
+  }
+  let spool: ChildObservationSpool;
+  try {
+    spool = new ChildObservationSpool(options.auditPath);
+  } catch (error) {
+    return {
+      ...result,
+      exitCode: 1,
+      terminalFailure: true,
+      error: `Cannot prepare child observations: ${errorText(error)}`,
+    };
+  }
+  const runner = new ChildAttemptRunner(options, baseline, spool);
+  runner.start();
+  return runner.completed();
 }