@fitchmultz/pi-subagents 0.0.0-stage → 0.44.5

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

@@ -0,0 +1,693 @@
+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 { 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 { 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,
+        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;
+    let baselineSnapshot;
+    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 = [];
+        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 });
+        };
+        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);
+            }
+            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);
+            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) => {
+            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) => {
+            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, 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;
+                }
+            }
+            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 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);
+    });
+}