@fitchmultz/pi-subagents 0.44.7 → 0.46.0

package/dist/runs/shared/child-attempt.js

@@ -1,693 +1,340 @@
 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 { getSubagentDepthEnv, } from "../../shared/types.js";
 import { attachChildProcessLifecycle } from "../../shared/post-exit-stdio-guard.js";
-import { applyIntercomBridgeToAgent, resolveIntercomBridge } from "../../intercom/intercom-bridge.js";
-import { providerQualifiedModelId } from "../../shared/model-info.js";
-import { getSubagentDepthEnv } from "../../shared/types.js";
-import { extractTextFromContent, extractToolArgsPreview, formatResourceLimitExceeded, getFinalOutput, findLatestSessionFile } from "../../shared/utils.js";
-import { readFinalizationReport, resolveExecutionOutcome } from "./acceptance.js";
-import { readStructuredOutput } from "./structured-output.js";
-import { appendClaudeCodeMessage, buildClaudeCodeInvocation, claudeCodeMessageFromResult, isClaudeCodeModel, writeClaudeCodeSessionMetadata, } from "./claude-code.js";
-import { createMutationCompletionTracker, resolveCurrentPath } from "./mutating-tool-guard.js";
-import { applyThinkingSuffix, buildPiArgs } from "./pi-args.js";
-import { FINALIZATION_EVENT, nativeFinalizationLaunch } from "./native-finalization.js";
-import { addUsage, nativeUsageCollector, readNativeUsage, snapshotNativeBaseline, validateNativeUsage } from "./native-usage.js";
-import { sumAttemptUsage } from "./model-fallback.js";
+import { findLatestSessionFile, formatResourceLimitExceeded } from "../../shared/utils.js";
+import { resolveExecutionOutcome } from "./acceptance.js";
+import { snapshotNativeBaseline } from "./native-usage.js";
 import { getPiSpawnCommand } from "./pi-spawn.js";
-import { createRepeatedSubagentCallGuardState, recordToolEndForSubagentLoopGuard, recordToolStartForSubagentLoopGuard } from "./subagent-tool-loop-guard.js";
-import { JournalFrames, NativeJournal, nativeProjection, scanJournal } from "../../shared/journal-reader.js";
-import { compactObservedMessage, createMessageReferenceIndex, ExitCodeObservation } from "./child-observations.js";
-const liveProjection = (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) => path[0] === "args" || path[0] === "structured_output" || path.includes("arguments") ? Infinity : 4096;
-export function buildChildInvocation(input) {
-    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 };
-}
-/** One owned process group and finalized JSON event stream for either native backend. */
-export function runChildAttempt(options) {
-    const result = {
-        stderr: "", exitCode: 0, messages: [], model: options.model,
+import { ChildObservationSpool } from "./child-observation-spool.js";
+import { ChildStreamObserver } from "./child-stream-observer.js";
+import { ChildEventObserver } from "./child-event-observer.js";
+import { accountNativeChild } from "./child-native-accounting.js";
+import { childExecutionOutcome } from "./child-execution-outcome.js";
+import { errorMessage as errorText } from "../../shared/unknown.js";
+import { nonempty } from "./child-presence.js";
+export { buildChildInvocation } from "./child-invocation.js";
+function initialResult(model) {
+    return {
+        stderr: "",
+        exitCode: 0,
+        messages: [],
+        model,
         usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 },
-        finalOutput: "", observedCompletedMutation: false, durationMs: 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);
+}
+function nativeSessionFile(options) {
+    if (options.claudeCodeInvocation) {
+        return;
     }
-    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;
-    let baselineSnapshot;
-    try {
-        baselineSnapshot = snapshotNativeBaseline(nativeSessionFile());
-        baseline = baselineSnapshot.ids;
+    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));
+}
+/** One process-group owner; event accounting, observation retention and native review are separate. */
+class ChildAttemptRunner {
+    options;
+    completion = Promise.withResolvers();
+    startedAt = Date.now();
+    spool;
+    events;
+    stream;
+    lifecycle;
+    resourceTimer;
+    abortListener;
+    interruptListener;
+    receiverFailed = false;
+    settled = false;
+    pid;
+    constructor(options, baseline, spool) {
+        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) => this.receive(bytes));
+        child.stderr.setEncoding("utf8");
+        child.stderr.on("data", (text) => this.receiveStderr(text));
+        child.on("close", (code, signal) => this.finish(code, signal));
+        child.on("error", (error) => this.finish(1, undefined, error));
     }
-    catch (error) {
-        return Promise.resolve({ ...result, exitCode: 1, terminalFailure: true, error: `Cannot capture native usage baseline: ${error instanceof Error ? error.message : String(error)}` });
+    completed() {
+        return this.completion.promise;
     }
-    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+");
+    start() {
+        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);
     }
-    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)}` });
+    stop(outcome) {
+        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();
     }
-    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,
+    resourceLimit(kind, limit, observed) {
+        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,
         });
-        const lifecycle = attachChildProcessLifecycle(child);
-        const mutations = createMutationCompletionTracker();
-        const toolLoop = createRepeatedSubagentCallGuardState();
-        const wirePath = path.join(wireDirectory, "stdout");
-        let textOffset = 0;
-        const observations = [];
-        const references = createMessageReferenceIndex();
-        const referenceMessage = (entry) => baseline.has(entry.id) ? undefined : references.reference(entry);
-        let rawOutput = "", lastOutput = "", boundariesCursor = 0;
-        let receiverFailed = false;
-        const acceptedEntries = new Map();
-        let nativeMessageCount = 0;
-        const pendingBoundary = Symbol("pending boundary");
-        let textWritten = false, exitObservation = new ExitCodeObservation(), firstTextPath;
-        let outputTextPath, pendingSurrogate = "";
-        let reproject = false, replayOutput = false;
-        result.attemptBaseline = [...baseline];
-        let assistantError;
-        let cleanAssistantStop = false;
-        let settled = false;
-        let resourceTimer;
-        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) => {
-            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, limit, observed) => {
-            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 });
+        result.resourceLimitExceeded = {
+            kind,
+            limit,
+            ...(observed !== undefined ? { observed } : {}),
+            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;
-                    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 = { 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"])
-                            attemptUsage[key] += usage[key];
-                        attemptStartedAt = marker.at;
-                        resetResourceTimer();
-                    }
-                    options.onEvent?.(marker, result);
-                    boundariesCursor = end;
-                }, { policy: "live", start: boundariesCursor });
-            }
-            catch (error) {
-                if (error !== pendingBoundary && error.code !== "ENOENT")
-                    throw error;
-            }
-        };
-        const processEvent = (input) => {
-            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;
-                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;
-                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;
-                // 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;
-            let loopFailure;
-            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, start, end, consume) => {
-            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) => {
-            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, text, root) => {
-            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);
+        this.stop({ error: message });
+    }
+    resetResourceTimer() {
+        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);
             }
-            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;
+            else {
+                this.resetResourceTimer();
             }
-            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 }) } : {}) });
+        }, Math.max(0, limit - (Date.now() - this.events.boundaries.startedAt)));
+        this.resourceTimer.unref();
+    }
+    listenForCancellation() {
+        const { signal, interruptSignal } = this.options;
+        if (signal) {
+            this.abortListener = addAbortListener(signal, () => {
+                const reason = 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;
                 }
-            }
-            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);
-            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);
+                this.stop({ interrupted: true, error: undefined });
             });
-            const tail = decoder.end();
-            if (tail)
-                options.onOutput?.(tail);
-            resetRecord();
-        }, consumeMessageText, liveKeyLimit);
-        child.stderr.setEncoding("utf8");
-        child.stdout.on("data", (bytes) => {
-            try {
-                writeFileSync(wireFd, bytes);
-                if (!receiverFailed)
-                    stdout.write(bytes);
-            }
-            catch (error) {
-                receiverFailed = true;
-                result.terminalFailure = true;
-                stop({ error: `Cannot receive child events: ${String(error)}` });
+        }
+    }
+    receive(bytes) {
+        try {
+            if (this.receiverFailed) {
+                this.stream.saveUnparsed(bytes);
             }
-        });
-        child.stderr.on("data", (text) => {
-            try {
-                writeFileSync(stderrFd, text);
-                result.stderr = (result.stderr + text).slice(-16384);
-                options.onStderr?.(text);
+            else {
+                this.stream.write(bytes);
             }
-            catch (error) {
-                result.terminalFailure = true;
-                stop({ error: `Cannot save child diagnostics: ${String(error)}` });
+        }
+        catch (error) {
+            this.receiverFailed = true;
+            this.events.result.terminalFailure = true;
+            this.stop({ error: `Cannot receive child events: ${errorText(error)}` });
+        }
+    }
+    receiveStderr(text) {
+        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)}` });
+        }
+    }
+    drainObservations() {
+        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;
+        }
+    }
+    finish(code, signal, spawnError) {
+        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);
+    }
+    finalizeAccounting() {
+        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(),
         });
-        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, signal, spawnError) => {
-            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"])
-                        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;
-                }
+        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 publishedIds = new Set();
-            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 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 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);
+        }
+        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 async function runChildAttempt(options) {
+    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;
+    try {
+        baseline = snapshotNativeBaseline(nativeSessionFile(options));
+    }
+    catch (error) {
+        return {
+            ...result,
+            exitCode: 1,
+            terminalFailure: true,
+            error: `Cannot capture native usage baseline: ${errorText(error)}`,
         };
-        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);
-    });
+    }
+    let spool;
+    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();
 }