taskflow-core 0.1.8 → 0.2.1

package/dist/runner-core.js

@@ -11,10 +11,11 @@
  * failure semantics, retry heuristics, and usage folding are identical across
  * hosts.
  */
-import { spawn } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
+import { StringDecoder } from "node:string_decoder";
 import { emptyUsage } from "./usage.js";
 export function isFailed(r) {
-    return r.exitCode !== 0 || r.stopReason === "error" || r.stopReason === "aborted";
+    return r.exitCode !== 0 || Boolean(r.errorMessage) || r.stopReason === "error" || r.stopReason === "aborted";
 }
 /**
  * Heuristic: did this failure look like a transient/retryable provider error
@@ -35,6 +36,26 @@ export function isTransientError(r) {
     const hay = `${r.errorMessage ?? ""} ${r.stderr ?? ""} ${r.output ?? ""}`;
     return TRANSIENT_ERROR_RE.test(hay);
 }
+/** Wait for a retry backoff, but release immediately when the run is aborted.
+ * Resolves (rather than rejects) on abort so callers can leave their retry loop
+ * through the normal `signal.aborted` branch and preserve paused semantics. */
+export function abortableDelay(ms, signal) {
+    if (ms <= 0 || signal?.aborted)
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        let settled = false;
+        const finish = () => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", finish);
+            resolve();
+        };
+        const timer = setTimeout(finish, ms);
+        signal?.addEventListener("abort", finish, { once: true });
+    });
+}
 /** Placeholder written to a failed phase's `output` so downstream interpolation
  *  can detect "upstream failed" without being polluted by raw HTML/JSON. */
 export const TRANSPORT_ERROR_PLACEHOLDER = "(upstream error: subagent failed; see error)";
@@ -102,7 +123,7 @@ export function getFinalOutput(messages) {
     return "";
 }
 export function newAccumulator(model) {
-    return { messages: [], usage: emptyUsage(), model, lastActivity: "" };
+    return { messages: [], usage: emptyUsage(), model, finalText: "", lastActivity: "" };
 }
 /**
  * Fold one NDJSON line into the accumulator. Returns a LiveUpdate when an
@@ -149,8 +170,13 @@ export function foldEventLine(acc, line) {
         acc.model = msg.model;
     if (msg.stopReason)
         acc.stopReason = msg.stopReason;
-    if (msg.errorMessage)
+    if (msg.errorMessage) {
         acc.errorMessage = msg.errorMessage;
+        acc.fatalError = msg.errorMessage;
+    }
+    const finalText = getFinalOutput([msg]);
+    if (finalText.trim())
+        acc.finalText = finalText;
     const activity = describeActivity(msg);
     if (activity)
         acc.lastActivity = activity;
@@ -240,17 +266,123 @@ export function num(v) {
  *  Module-global (not per-host): a single exit handler must reach every host's
  *  children, so all host runners register here. */
 const activeChildren = new Set();
-const killAllChildren = () => {
-    for (const pid of activeChildren) {
+/** Register a detached process group with the host-wide supervisor. Script
+ * phases and agent runners share this registry so external host termination
+ * cannot leave either kind of child mutating the workspace. */
+export function registerProcessTree(pid) {
+    activeChildren.add(pid);
+}
+/** Remove a process group after its stdio has closed and all descendants have
+ * been synchronously reaped. */
+export function unregisterProcessTree(pid) {
+    activeChildren.delete(pid);
+}
+/** Signal the whole process tree rooted at a spawned subagent. POSIX children
+ * are process-group leaders (`detached:true` at spawn), so a negative pid
+ * reaches every descendant in the group. Windows has no equivalent signal;
+ * taskkill /T /F is the platform-supported tree termination primitive. */
+export function killProcessTree(pid, signal, direct) {
+    if (process.platform === "win32") {
+        try {
+            // Wait for taskkill: returning while /T is still enumerating descendants
+            // violates the phase boundary and is especially racy after root exit.
+            const killed = spawnSync("taskkill", ["/PID", String(pid), "/T", "/F"], {
+                shell: false,
+                stdio: "ignore",
+                windowsHide: true,
+            });
+            if (killed.error || killed.status !== 0) {
+                try {
+                    direct?.kill();
+                }
+                catch { /* already dead */ }
+            }
+        }
+        catch {
+            try {
+                direct?.kill();
+            }
+            catch { /* already dead */ }
+        }
+        return;
+    }
+    try {
+        process.kill(-pid, signal);
+    }
+    catch {
+        // A process can exit between the liveness check and group signal. Falling
+        // back to the direct handle also covers platforms that reject group kills.
         try {
-            process.kill(pid, "SIGKILL");
+            direct?.kill(signal);
         }
         catch { /* already dead */ }
     }
+}
+/** Synchronous variant for the host's `exit` event, where asynchronous taskkill
+ * cannot be awaited and would never get a chance to run. */
+function killProcessTreeSync(pid) {
+    if (process.platform === "win32") {
+        try {
+            spawnSync("taskkill", ["/PID", String(pid), "/T", "/F"], {
+                shell: false,
+                stdio: "ignore",
+                windowsHide: true,
+            });
+        }
+        catch { /* already dead / taskkill unavailable */ }
+        return;
+    }
+    try {
+        process.kill(-pid, "SIGKILL");
+    }
+    catch { /* already dead */ }
+}
+const killAllChildren = () => {
+    for (const pid of activeChildren) {
+        killProcessTreeSync(pid);
+    }
 };
 process.on("exit", killAllChildren);
+// Installing a signal listener disables Node's default signal termination.
+// Reap every registered process group synchronously, then restore the default
+// disposition and re-deliver the same signal so callers still observe a real
+// signal exit (rather than an arbitrary numeric process.exit code).
+const EXTERNAL_SIGNALS = ["SIGTERM", "SIGINT", "SIGHUP"];
+const SIGNAL_EXIT_CODES = {
+    SIGTERM: 143,
+    SIGINT: 130,
+    SIGHUP: 129,
+};
+let handlingExternalSignal = false;
+for (const signal of EXTERNAL_SIGNALS) {
+    process.on(signal, () => {
+        if (handlingExternalSignal)
+            return;
+        handlingExternalSignal = true;
+        killAllChildren();
+        // Existing listeners have already been snapshotted for this EventEmitter
+        // dispatch. Removing them here only ensures the re-delivered signal takes
+        // the OS default path instead of recursively entering user handlers.
+        process.removeAllListeners(signal);
+        try {
+            process.kill(process.pid, signal);
+        }
+        catch {
+            process.exit(SIGNAL_EXIT_CODES[signal]);
+        }
+    });
+}
 /** Same idle window every host runner uses: a child silent this long is wedged. */
 export const DEFAULT_IDLE_TIMEOUT_MS = 5 * 60_000;
+/** After a phase timeout aborts its runner, allow process-backed hosts enough
+ * time to execute their SIGTERM to SIGKILL escalation. A custom runner that
+ * ignores AbortSignal entirely is still bounded by this grace window. */
+export const PHASE_TIMEOUT_ABORT_GRACE_MS = 5500;
+/** Maximum NDJSON line size retained while waiting for a newline. A hostile or
+ * broken host can otherwise stream an unterminated line until the orchestrator
+ * runs out of memory. Host events are expected to be compact; 1 MiB still
+ * leaves ample room for a large final answer while providing a hard bound. */
+export const MAX_STDOUT_LINE_BYTES = 1024 * 1024;
 /** Standard "unknown agent" RunResult — identical across every host runner. */
 export function unknownAgentResult(agentName, task, agents) {
     const available = agents.map((a) => `"${a.name}"`).join(", ") || "none";
@@ -284,7 +416,21 @@ export async function runSubagentProcess(opts) {
     let wasAborted = false;
     let idleTimedOut = false;
     let killedBySignal;
+    let protocolError;
+    let policyFatal;
+    let terminalCommitted = false;
+    let reapedAfterTerminal = false;
+    let completionNotified = false;
+    let killReason;
     const idleMs = opts.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS;
+    const terminationGraceMs = opts.terminationGraceMs ?? 5000;
+    const completionPolicy = opts.completionPolicy;
+    if (completionPolicy && (!Number.isFinite(completionPolicy.terminalGraceMs) || completionPolicy.terminalGraceMs < 0)) {
+        throw new Error("terminalGraceMs must be a non-negative finite number");
+    }
+    if (!Number.isFinite(terminationGraceMs) || terminationGraceMs < 0) {
+        throw new Error("terminationGraceMs must be a non-negative finite number");
+    }
     // Structured run-log header, opt-in via PI_TASKFLOW_RUN_LOG. Written to the
     // HOST process's stderr (the MCP stdio log channel; pi's subagent diagnostic
     // stream) — never to stdout (stdout is JSON-RPC for MCP). One line per spawn
@@ -298,25 +444,89 @@ export async function runSubagentProcess(opts) {
         }
     }
     const exitCode = await new Promise((resolve) => {
-        const proc = spawn(bin, args, { cwd, shell: false, stdio: ["ignore", "pipe", "pipe"], env });
+        const proc = spawn(bin, args, {
+            cwd,
+            shell: false,
+            stdio: ["ignore", "pipe", "pipe"],
+            env,
+            // On POSIX this makes the subagent a process-group leader while retaining
+            // piped stdout/stderr. Cancellation can then signal `-pid` and cannot
+            // strand grandchildren that outlive the direct CLI process.
+            detached: process.platform !== "win32",
+            windowsHide: true,
+        });
         if (proc.pid)
-            activeChildren.add(proc.pid);
+            registerProcessTree(proc.pid);
         let buffer = "";
+        const stdoutDecoder = new StringDecoder("utf8");
+        const stderrDecoder = new StringDecoder("utf8");
         let idleTimer;
+        let terminalTimer;
         let forceTimer;
+        let candidateEpoch = 0;
+        let terminalCandidate = false;
+        let settled = false;
+        let removeAbortListener = () => { };
         const clearTimers = () => {
-            if (idleTimer)
+            if (idleTimer) {
                 clearTimeout(idleTimer);
+                idleTimer = undefined;
+            }
+            if (terminalTimer) {
+                clearTimeout(terminalTimer);
+                terminalTimer = undefined;
+            }
+            if (forceTimer) {
+                clearTimeout(forceTimer);
+                forceTimer = undefined;
+            }
+        };
+        const signalTree = (signal) => {
+            if (proc.pid)
+                killProcessTree(proc.pid, signal, proc);
+            else {
+                try {
+                    proc.kill(signal);
+                }
+                catch { /* spawn failed / already dead */ }
+            }
+        };
+        const setKillReason = (reason) => {
+            if (killReason)
+                return killReason === reason;
+            killReason = reason;
+            return true;
+        };
+        const scheduleForceKill = () => {
+            if (settled)
+                return;
             if (forceTimer)
                 clearTimeout(forceTimer);
+            forceTimer = setTimeout(() => {
+                if (!settled)
+                    signalTree("SIGKILL");
+            }, terminationGraceMs);
+            forceTimer.unref();
+        };
+        const clearTerminalCandidate = () => {
+            terminalCandidate = false;
+            candidateEpoch++;
+            if (terminalTimer) {
+                clearTimeout(terminalTimer);
+                terminalTimer = undefined;
+            }
         };
         const hardKill = () => {
+            if (settled || terminalCommitted || !setKillReason("idle-timeout"))
+                return;
             idleTimedOut = true;
-            proc.kill("SIGTERM");
-            forceTimer = setTimeout(() => proc.kill("SIGKILL"), 5000);
-            forceTimer.unref();
+            clearTerminalCandidate();
+            signalTree("SIGTERM");
+            scheduleForceKill();
         };
         const armIdle = () => {
+            if (terminalCandidate || terminalCommitted || settled)
+                return;
             if (idleTimer)
                 clearTimeout(idleTimer);
             if (idleMs <= 0)
@@ -325,102 +535,360 @@ export async function runSubagentProcess(opts) {
             idleTimer.unref();
         };
         armIdle();
+        const failProtocol = (message) => {
+            if (protocolError)
+                return;
+            // An earlier abort/idle/fatal stop can itself truncate the last record.
+            // First-writer wins; only a terminal reap remains revocable by a bad tail.
+            if (killReason && killReason !== "terminal-reap" && killReason !== "protocol-error")
+                return;
+            protocolError = message;
+            if (!killReason && !setKillReason("protocol-error"))
+                return;
+            clearTerminalCandidate();
+            if (idleTimer) {
+                clearTimeout(idleTimer);
+                idleTimer = undefined;
+            }
+            signalTree("SIGTERM");
+            scheduleForceKill();
+        };
+        const notifyCompletionCommit = () => {
+            if (completionNotified)
+                return;
+            completionNotified = true;
+            try {
+                opts.onTerminalCommit?.();
+            }
+            catch { /* internal observer is fail-open */ }
+        };
+        const canCommitTerminal = () => {
+            if (!completionPolicy)
+                return false;
+            try {
+                return completionPolicy.canCommitTerminal(acc);
+            }
+            catch (error) {
+                failProtocol(`Completion policy failed: ${error instanceof Error ? error.message : String(error)}`);
+                return false;
+            }
+        };
+        const commitTerminal = (epoch) => {
+            // A cleared timer may already be queued. The epoch is the CAS token that
+            // prevents it from committing a revoked candidate.
+            if (settled || terminalCommitted || !terminalCandidate || epoch !== candidateEpoch ||
+                wasAborted || protocolError || policyFatal || killReason)
+                return;
+            if (buffer.trim()) {
+                failProtocol("Subagent emitted malformed or truncated JSON after its terminal event");
+                return;
+            }
+            if (!canCommitTerminal()) {
+                clearTerminalCandidate();
+                armIdle();
+                return;
+            }
+            terminalCommitted = true;
+            terminalCandidate = false;
+            setKillReason("terminal-reap");
+            reapedAfterTerminal = true;
+            notifyCompletionCommit();
+            const diagnostic = `[taskflow] Child produced terminal output but did not exit after ${completionPolicy?.terminalGraceMs ?? 0}ms; ` +
+                "reaped process tree and accepted the completed result.";
+            result.stderr += `${result.stderr && !result.stderr.endsWith("\n") ? "\n" : ""}${diagnostic}\n`;
+            signalTree("SIGTERM");
+            scheduleForceKill();
+        };
+        const beginTerminalCandidate = () => {
+            if (!completionPolicy || terminalCommitted || settled || killReason)
+                return;
+            if (!canCommitTerminal()) {
+                clearTerminalCandidate();
+                armIdle();
+                return;
+            }
+            terminalCandidate = true;
+            const epoch = ++candidateEpoch;
+            if (idleTimer) {
+                clearTimeout(idleTimer);
+                idleTimer = undefined;
+            }
+            if (terminalTimer)
+                clearTimeout(terminalTimer);
+            terminalTimer = setTimeout(() => {
+                terminalTimer = undefined;
+                // Let already-readable stdout callbacks run before the linearization
+                // point so lifecycle activity cannot lose to a same-tick timer.
+                setImmediate(() => commitTerminal(epoch));
+            }, completionPolicy.terminalGraceMs);
+            terminalTimer.unref();
+        };
         const processLine = (line) => {
-            // A throwing foldLine (malformed/hostile stream line) or a throwing onLive
-            // callback must NEVER crash the run — this is the fail-open backstop that
-            // turns a bad line into a skipped line. It also honours the AGENTS.md
-            // invariant that user callbacks are wrapped in try/catch.
+            if (!line.trim() || protocolError)
+                return;
+            // Every supported host advertises a JSON/NDJSON stream. Treat malformed
+            // records as a protocol failure: silently dropping them can turn a
+            // truncated provider error into a successful phase with empty output.
+            let event;
             try {
-                const live = foldLine(acc, line);
-                if (live && opts.onLive)
-                    opts.onLive(live);
+                event = JSON.parse(line);
             }
             catch {
-                /* malformed stream line / throwing callback — skip, never crash */
+                failProtocol("Subagent emitted malformed or truncated JSON output");
+                return;
+            }
+            let live;
+            try {
+                live = foldLine(acc, line);
+            }
+            catch (error) {
+                failProtocol(`Subagent output parser failed: ${error instanceof Error ? error.message : String(error)}`);
+                return;
+            }
+            // onLive is a user callback and remains fail-open; parser failures above
+            // are part of the transport contract and therefore fail closed.
+            if (live && opts.onLive) {
+                try {
+                    opts.onLive(live);
+                }
+                catch { /* user callback must not sink run */ }
+            }
+            if (!completionPolicy || terminalCommitted) {
+                armIdle();
+                return;
+            }
+            let classification;
+            try {
+                classification = completionPolicy.classifyEvent(acc, event);
+            }
+            catch (error) {
+                failProtocol(`Completion policy failed: ${error instanceof Error ? error.message : String(error)}`);
+                return;
+            }
+            switch (classification) {
+                case "terminal-candidate":
+                    beginTerminalCandidate();
+                    break;
+                case "fatal":
+                    if (setKillReason("fatal-error")) {
+                        policyFatal = acc.fatalError ?? "Subagent emitted a fatal terminal event";
+                        if (idleTimer) {
+                            clearTimeout(idleTimer);
+                            idleTimer = undefined;
+                        }
+                        signalTree("SIGTERM");
+                        scheduleForceKill();
+                    }
+                    clearTerminalCandidate();
+                    break;
+                case "activity":
+                    clearTerminalCandidate();
+                    armIdle();
+                    break;
+                case "ignore":
+                    break;
             }
         };
         proc.stdout.on("data", (data) => {
-            armIdle();
-            buffer += data.toString();
+            // StringDecoder preserves multi-byte UTF-8 characters split across
+            // arbitrary pipe chunks. Candidate revocation is event-semantic below:
+            // metadata/heartbeat records classified as `ignore` must not disable both
+            // terminal grace and the ordinary idle watchdog.
+            buffer += stdoutDecoder.write(data);
+            if (Buffer.byteLength(buffer) > MAX_STDOUT_LINE_BYTES && !buffer.includes("\n")) {
+                // Drop the retained bytes before terminating so the bound remains true
+                // even while a non-cooperative child takes time to die.
+                buffer = "";
+                failProtocol(`Subagent emitted an unterminated stdout record larger than ${MAX_STDOUT_LINE_BYTES} bytes`);
+                return;
+            }
             const lines = buffer.split("\n");
             buffer = lines.pop() || "";
-            for (const line of lines)
+            for (const line of lines) {
+                if (Buffer.byteLength(line) > MAX_STDOUT_LINE_BYTES) {
+                    failProtocol(`Subagent emitted a stdout record larger than ${MAX_STDOUT_LINE_BYTES} bytes`);
+                    break;
+                }
                 processLine(line);
+            }
+            if (!completionPolicy)
+                armIdle();
         });
-        const STDERR_MAX_LEN = 64 * 1024;
+        const STDERR_MAX_BYTES = 64 * 1024;
+        let stderrBytes = 0;
         let stderrCapped = false;
         proc.stderr.on("data", (data) => {
+            // Diagnostics are real child activity too. A CLI that is actively
+            // reporting provider retries on stderr must not be killed as idle.
+            // stderr is activity while running, but after a terminal candidate it
+            // neither revokes nor prolongs the bounded grace window.
+            if (!terminalCandidate && !terminalCommitted)
+                armIdle();
             if (!stderrCapped) {
-                result.stderr += data.toString();
-                if (result.stderr.length >= STDERR_MAX_LEN) {
-                    result.stderr = result.stderr.slice(0, STDERR_MAX_LEN) + "\n[...stderr truncated at 64KB]";
+                const remaining = STDERR_MAX_BYTES - stderrBytes;
+                const retained = data.subarray(0, Math.max(0, remaining));
+                if (retained.length > 0) {
+                    result.stderr += stderrDecoder.write(retained);
+                    stderrBytes += retained.length;
+                }
+                if (data.length > retained.length) {
+                    result.stderr += "\n[...stderr truncated at 64KB]";
                     stderrCapped = true;
                 }
             }
         });
-        proc.on("close", (code, signal) => {
+        // `close` waits for inherited stdio handles. A direct CLI can exit while a
+        // background descendant still owns stdout/stderr, so reap the group at the
+        // earlier `exit` boundary; `close` remains the point where buffered output
+        // is folded and the result is settled.
+        proc.once("exit", () => {
             if (proc.pid)
-                activeChildren.delete(proc.pid);
-            clearTimers();
-            if (buffer.trim())
+                killProcessTree(proc.pid, "SIGKILL", proc);
+        });
+        const finish = (code, signal) => {
+            if (settled)
+                return;
+            // Flush decoders and classify the final unterminated record before
+            // settling. Any force-kill timer created by a malformed tail is cleared
+            // below, so no signal can fire after this Promise resolves.
+            buffer += stdoutDecoder.end();
+            if (!stderrCapped)
+                result.stderr += stderrDecoder.end();
+            if (buffer.trim() && killReason !== "abort" && killReason !== "idle-timeout" && killReason !== "fatal-error") {
                 processLine(buffer);
-            if (code === null && signal)
+            }
+            settled = true;
+            // The direct CLI may intentionally or accidentally leave background
+            // descendants behind. A phase boundary is also a process-tree boundary:
+            // always reap the group before returning, not only on abort/idle timeout.
+            // Otherwise detached grandchildren can keep mutating the workspace after
+            // the phase has been persisted as complete.
+            if (proc.pid)
+                killProcessTree(proc.pid, "SIGKILL", proc);
+            if (proc.pid)
+                unregisterProcessTree(proc.pid);
+            clearTimers();
+            removeAbortListener();
+            if (signal)
                 killedBySignal = signal;
-            resolve(code ?? 0);
+            let terminalValid = !completionPolicy;
+            if (completionPolicy) {
+                try {
+                    terminalValid = completionPolicy.canCommitTerminal(acc);
+                }
+                catch (error) {
+                    protocolError ??= `Completion policy failed: ${error instanceof Error ? error.message : String(error)}`;
+                }
+            }
+            if (code === 0 && !signal && !protocolError && !policyFatal && !acc.fatalError &&
+                !wasAborted && !idleTimedOut &&
+                terminalValid)
+                notifyCompletionCommit();
+            resolve(code);
+        };
+        proc.on("close", (code, signal) => {
+            finish(code ?? 0, code === null ? signal : undefined);
         });
         proc.on("error", (err) => {
-            clearTimers();
-            if (proc.pid)
-                activeChildren.delete(proc.pid); // defensive: close usually fires after error, but don't rely on it
             if (!result.stderr)
                 result.stderr = err.message;
             if (!result.errorMessage)
                 result.errorMessage = err.message;
-            resolve(1);
+            finish(1);
         });
         if (opts.signal) {
             const kill = () => {
+                // Terminal commit is the completion linearization point. A later outer
+                // timeout/user abort cannot retroactively change a completed task.
+                if (terminalCommitted || settled)
+                    return;
+                if (!setKillReason("abort"))
+                    return;
                 wasAborted = true;
                 // Disarm the idle watchdog first: otherwise, if the idle timer fires
                 // between this SIGTERM and the close event, `idleTimedOut` would be
                 // set and the post-exit classify chain (which checks idle BEFORE
                 // abort) would misreport a user abort as an idle stall.
                 clearTimers();
-                proc.kill("SIGTERM");
-                const forceKill = setTimeout(() => proc.kill("SIGKILL"), 5000);
-                forceKill.unref();
+                signalTree("SIGTERM");
+                scheduleForceKill();
             };
             if (opts.signal.aborted)
                 kill();
-            else
+            else {
                 opts.signal.addEventListener("abort", kill, { once: true });
+                removeAbortListener = () => {
+                    opts.signal?.removeEventListener("abort", kill);
+                    removeAbortListener = () => { };
+                };
+            }
         }
     });
     result.exitCode = exitCode;
     result.usage = acc.usage;
     result.model = acc.model;
     result.output = acc.finalText;
-    if (acc.fatalError) {
+    if (protocolError) {
+        result.exitCode = result.exitCode || 1;
+        result.stopReason = "error";
+        result.errorMessage = protocolError;
+    }
+    else if (wasAborted) {
+        result.stopReason = "aborted";
+        result.errorMessage = "Subagent was aborted";
+    }
+    else if (idleTimedOut) {
+        result.stopReason = "error";
+        result.idleTimeout = true;
+        result.errorMessage = `Subagent stalled: no output for ${Math.round(idleMs / 1000)}s (idle timeout) — killed`;
+    }
+    else if (acc.fatalError || policyFatal) {
         result.exitCode = result.exitCode || 1;
         result.stopReason = "error";
-        result.errorMessage = acc.fatalError;
+        result.errorMessage = acc.fatalError ?? policyFatal;
+    }
+    else if (terminalCommitted) {
+        // A signal caused by our own terminal reap is a successful controlled
+        // shutdown, regardless of the OS exit code/signal encoding.
+        result.exitCode = 0;
+        result.stopReason = "end";
     }
     else {
-        result.stopReason = exitCode === 0 ? "end" : "error";
+        result.stopReason = acc.stopReason ?? (exitCode === 0 ? "end" : "error");
     }
-    if (exitCode === 0 && killedBySignal && !idleTimedOut && !wasAborted) {
+    if (!isFailed(result) && opts.requireTerminalEvent && !acc.terminalSeen) {
         result.exitCode = 1;
         result.stopReason = "error";
-        result.errorMessage = `Subagent killed by signal ${killedBySignal}`;
+        result.errorMessage = `Subagent stream ended before ${opts.terminalEventLabel ?? "the terminal event"}`;
     }
-    if (idleTimedOut) {
+    if (exitCode === 0 && killedBySignal && !idleTimedOut && !wasAborted && !protocolError &&
+        !terminalCommitted && killReason !== "fatal-error") {
+        result.exitCode = 1;
         result.stopReason = "error";
-        result.idleTimeout = true;
-        result.errorMessage = `Subagent stalled: no output for ${Math.round(idleMs / 1000)}s (idle timeout) — killed`;
+        result.errorMessage = `Subagent killed by signal ${killedBySignal}`;
     }
-    else if (wasAborted) {
-        result.stopReason = "aborted";
-        result.errorMessage = "Subagent was aborted";
+    result.completionSource = protocolError
+        ? "protocol-error"
+        : idleTimedOut
+            ? "idle-timeout"
+            : wasAborted
+                ? "abort"
+                : terminalCommitted
+                    ? "terminal-reap"
+                    : killedBySignal && killReason !== "fatal-error"
+                        ? "external-signal"
+                        : "process-exit";
+    if (terminalCommitted) {
+        result.reapedAfterTerminal = reapedAfterTerminal;
+        result.terminalGraceMs = completionPolicy?.terminalGraceMs;
+    }
+    // A zero exit with no answer is not evidence of successful agent work. It is
+    // the characteristic outcome of a truncated/unknown host stream whose lines
+    // were syntactically valid but never contained a terminal answer.
+    if (!isFailed(result) && !result.output.trim()) {
+        result.exitCode = 1;
+        result.stopReason = "error";
+        result.errorMessage = "Subagent exited successfully without a final output";
     }
     if (isFailed(result)) {
         if (!result.output) {