@gaunt-sloth/core 2.0.0-beta.2 → 2.0.0-beta.4

package/dist/core/GthAgentRunner.js

@@ -7,6 +7,8 @@ import { classifyCommand } from '#src/core/shell/arity.js';
 import { describeAbstention } from '#src/core/shell/abstention.js';
 import { normalizeCommand } from '#src/core/shell/normalize.js';
 import { ApprovalStopError, AttackHaltError, NonInteractiveEscalationError, } from '#src/core/shell/approvalStop.js';
+import { attachTerminationReason, classifyThrownTermination, terminationReason, terminationReasonOf, } from '#src/core/terminationReason.js';
+import { terminationLogLine } from '#src/core/terminationNotice.js';
 import { applyDestructiveFloor, effectivePreflightFloorFinding, isBelowDestructiveFloor, isNegotiableCall, isRaterTimeout, mapAllowMatchedVerdictToAction, mapVerdictToAction, openWorldToolFloorReason, preflightFloorFinding, RATER_DEFAULT_TIMEOUT_MS, rateShellCommand, } from '#src/core/shell/rater.js';
 import { RaterHealth } from '#src/core/shell/raterHealth.js';
 import { alignmentApprovalNotice, isAlignmentFailClosed, runAlignmentCheck, } from '#src/core/shell/alignment.js';
@@ -207,10 +209,29 @@ export class GthAgentRunner {
      * {@link getRunStats} before cleanup. Defaults to an empty tally.
      */
     lastRunStats = { tools: [] };
+    /**
+     * [[EXT-159]] — why the current turn ended, as classified by the sites the RUNNER owns (the two
+     * exception wrappers, the approvals re-throws, the empty-response throws, the ordinary end of a
+     * turn). The agent owns the sites inside it and its answer outranks this one; see
+     * {@link getTerminationReason}.
+     */
+    terminationReason = null;
+    /**
+     * [[EXT-159]] — snapshot of the agent's own termination reason, for the same reason
+     * {@link lastRunStats} exists: {@link cleanup} nulls the agent, and the single-shot path reads
+     * the reason afterwards.
+     */
+    agentTerminationReason = null;
+    /**
+     * [[EXT-159]] — snapshot of the agent's per-message `finish_reason` observations, kept for the
+     * same reason {@link agentTerminationReason} is: `/debug-dump` and the non-interactive verbs ask
+     * after {@link cleanup} has already dropped the agent.
+     */
+    agentFinishReasons = [];
     /**
      * CFG-27 — the runtime, session-scoped approvals posture, seeded at {@link init} from
      * {@link resolveApprovals} and thereafter switchable for the session by `/approvals <rung>`.
-     * **This field, not the interrupt wiring, is where the rung lives.** The backends wire the
+     * **This field, not the interrupt wiring, is where the rung lives.** The agent wires the
      * interrupt rung-independently, so every tool any rung could gate arrives at the top of
      * {@link decideToolApproval} and is judged against the rung recorded here — which is what makes
      * `/approvals manual` take effect mid-session, and what keeps a config that pre-selects
@@ -813,6 +834,8 @@ export class GthAgentRunner {
         }
         // GS2-16: start this turn's analytics tally from zero (the runner is reused across turns).
         this.resetRunStats();
+        // [[EXT-159]] — the previous turn's termination reason goes with the previous turn's tally.
+        this.resetTerminationReason();
         // GS2-48 — record this turn's transcript tail for the crash handler.
         updateCrashContext({ transcriptTail: messages.slice(-CRASH_TRANSCRIPT_TAIL_MESSAGES) });
         // [[EXT-29]] §5 — a new user turn is the human being reached, so it ends any negotiation still
@@ -845,11 +868,17 @@ export class GthAgentRunner {
                     // CFG-27 — an approvals STOP is not a stream failure: it is the gate deliberately
                     // ending the run, and its message IS the explanation the spec requires it to carry.
                     // Re-thrown unchanged (the outer catch does the same) so nothing buries it.
-                    if (streamError instanceof ApprovalStopError)
+                    if (streamError instanceof ApprovalStopError) {
+                        this.noteApprovalStop('runner.stream-approval-stop', streamError);
                         throw streamError;
+                    }
                     // Handle streaming-specific errors
                     debugLogError('Stream processing', streamError);
-                    throw new Error(`Stream processing failed: ${streamError instanceof Error ? streamError.message : String(streamError)}`);
+                    // [[EXT-159]] — classify the ORIGINAL error, not the wrapper built from it: the wrapper's
+                    // message is where the diagnosis was being thrown away. The one reason is attached to the
+                    // wrapper as well, so a catcher that only ever sees the re-thrown error still reads it.
+                    const reason = this.classifyThrownAt('runner.stream-error', streamError);
+                    throw attachTerminationReason(new Error(`Stream processing failed: ${streamError instanceof Error ? streamError.message : String(streamError)}`), reason);
                 }
                 debugLog(`Stream completed. Total response length: ${result.length}`);
                 // EXT-37: a content-policy refusal (OpenAI content_filter / Anthropic stop_reason=refusal /
@@ -877,10 +906,16 @@ export class GthAgentRunner {
                     const fallback = await this.agent.invoke(messages, this.runConfig);
                     debugLog(`Fallback non-stream response length: ${fallback.length}`);
                     if (fallback.trim().length === 0) {
-                        throw new Error('Model returned an empty response after tool execution. Try again or switch to a more stable model.');
+                        // [[EXT-159]] — the retry has already been spent here, so this is the terminal empty
+                        // turn rather than the first one.
+                        const reason = terminationReason('runner.empty-after-fallback', 'control', 'empty_response');
+                        this.noteTermination(reason);
+                        throw attachTerminationReason(new Error('Model returned an empty response after tool execution. Try again or switch to a more stable model.'), reason);
                     }
+                    this.noteCompleted('runner.completed');
                     return fallback;
                 }
+                this.noteCompleted('runner.completed');
                 return result;
             }
             else {
@@ -897,8 +932,13 @@ export class GthAgentRunner {
                 result += await this.resolveToolInterrupts();
                 debugLog(`Non-stream response length: ${result.length}`);
                 if (result.trim().length === 0) {
-                    throw new Error('Model returned an empty response. Try again or switch to a more stable model.');
+                    // [[EXT-159]] — the non-streaming path has no retry to spend, so an empty turn is
+                    // terminal here at once.
+                    const reason = terminationReason('runner.empty-invoke', 'control', 'empty_response');
+                    this.noteTermination(reason);
+                    throw attachTerminationReason(new Error('Model returned an empty response. Try again or switch to a more stable model.'), reason);
                 }
+                this.noteCompleted('runner.completed');
                 return result;
             }
         }
@@ -907,13 +947,20 @@ export class GthAgentRunner {
             // its own words: the command, the rating and its reason are the whole point of it. Wrapping
             // it as "Agent processing failed: …" would bury the explanation the spec requires it to
             // carry, so it is re-thrown unchanged.
-            if (error instanceof ApprovalStopError)
+            if (error instanceof ApprovalStopError) {
+                this.noteApprovalStop('runner.turn-approval-stop', error);
                 throw error;
+            }
             // Handle agent invocation errors
             debugLogError('Agent processing', error);
+            // [[EXT-159]] — the OUTER of two nested wrappers. On the streaming path the inner one has
+            // already classified this same failure and re-thrown, so `noteTermination`'s first-write-wins
+            // keeps the inner, truer site; on the non-streaming path this is the only classification
+            // there is. Both are reachable, so both classify.
+            const reason = this.classifyThrownAt('runner.turn-error', error);
             const originalMessage = error instanceof Error ? error.message : String(error);
             const enhancedMessage = enhanceVertexUnauthorizedMessage(originalMessage, this.config?.llm);
-            throw new Error(`Agent processing failed: ${enhancedMessage}`, error instanceof Error ? { cause: error } : undefined);
+            throw attachTerminationReason(new Error(`Agent processing failed: ${enhancedMessage}`, error instanceof Error ? { cause: error } : undefined), reason);
         }
         finally {
             // [[TUI-C69]] §5.4 — the turn is over, so the argument is over. The reasoning is the same as
@@ -946,10 +993,10 @@ export class GthAgentRunner {
      * streamed across all resume turns (empty when nothing was resumed).
      *
      * No-ops (returns '') when the agent does not support interrupts (`getPendingToolInterrupts`/
-     * `streamResume` absent) — that is the only exemption. As of EXT-52 BOTH backends gate
-     * `run_shell_command` and expose the interrupt surface, so the lean (default) agent is now
-     * exactly the agent this loop serves; only an agent implementation without those methods
-     * (e.g. a test double) skips it.
+     * `streamResume` absent) — that is the only exemption. As of EXT-52 the shipped agent gates
+     * `run_shell_command` and exposes the interrupt surface, so the lean agent is exactly the agent
+     * this loop serves; only an agent implementation without those methods (e.g. a test double)
+     * skips it.
      */
     async resolveToolInterrupts() {
         const agent = this.agent;
@@ -959,11 +1006,17 @@ export class GthAgentRunner {
         if (!agent.getPendingToolInterrupts || !agent.streamResume)
             return '';
         let resumedText = '';
+        // [[EXT-159]] — which way the loop left decides what ended the turn, and only the loop knows.
+        // Falling out of the bound and draining cleanly are different endings; a caller sees the same
+        // returned string either way, so a caller cannot tell them apart.
+        let drained = false;
         // Bound the loop defensively so a misbehaving graph that re-suspends forever cannot spin.
         for (let guard = 0; guard < 100; guard++) {
             const pending = await agent.getPendingToolInterrupts(runConfig);
-            if (pending.length === 0)
+            if (pending.length === 0) {
+                drained = true;
                 break;
+            }
             const decisions = [];
             for (const tool of pending) {
                 decisions.push(await this.decideToolApproval(tool));
@@ -971,6 +1024,14 @@ export class GthAgentRunner {
             const stream = await agent.streamResume({ decisions }, runConfig);
             resumedText += await this.drainTextStream(stream);
         }
+        // [[EXT-159]] — the runtime gave up, and the turn ends here because of that. It still returns
+        // into `processMessages`, which then reports an ordinary completion (or an empty turn) at its
+        // own site — so routing to an enumerated site is no defence: that site would state a category
+        // that is affirmatively false. Noting it HERE, before those sites run, is what makes
+        // first-write-wins keep the one fact they cannot see.
+        if (!drained) {
+            this.noteTermination(terminationReason('runner.interrupt-guard-exhausted', 'control', 'interrupt_drain_guard'));
+        }
         return resumedText;
     }
     /**
@@ -1085,7 +1146,7 @@ export class GthAgentRunner {
      * (defense in depth in `GthDevToolkit.executeCommand`), so an allow-listed `rm -rf /` still
      * cannot run.
      *
-     * **Step 0 is the rung.** The backends wire the interrupt over every tool ANY rung could gate,
+     * **Step 0 is the rung.** The agent wires the interrupt over every tool ANY rung could gate,
      * because the graph is built once and `/approvals <rung>` moves the rung under it for the rest of
      * the session. So a call arriving here has not yet been judged against the rung in force: this is
      * where that happens, on `sessionApprovals.rung`, which a mid-session switch has already updated.
@@ -1321,7 +1382,7 @@ export class GthAgentRunner {
         const command = typeof tool.args?.command === 'string' ? tool.args.command : null;
         const isShellCommand = tool.name === SHELL_TOOL_NAME && command !== null;
         const approvals = this.sessionApprovals;
-        // (0) Does the rung IN FORCE gate this tool at all? Same shared predicate the backends built the
+        // (0) Does the rung IN FORCE gate this tool at all? Same shared predicate the agent built the
         // interrupt from, asked about this one call, so the wiring and the decision cannot disagree.
         // Scope `once`, so nothing is written to any allow-list: this is not a grant, it is the absence
         // of a gate.
@@ -2224,7 +2285,7 @@ export class GthAgentRunner {
         if (registered.length === 0)
             return [];
         // The LIVE gated set, from the SAME shared policy `decideToolApproval` decides on and the
-        // backends derive their interrupt from, so "granted" here means exactly what it means at
+        // agent derives its interrupt from, so "granted" here means exactly what it means at
         // tool-registration time (§4.5) and at the gate.
         //
         // EXT-80 makes this non-drift property load-bearing rather than incidental. At `manual` the
@@ -2629,6 +2690,8 @@ export class GthAgentRunner {
         }
         // GS2-16: start this turn's analytics tally from zero (the runner is reused across turns).
         this.resetRunStats();
+        // [[EXT-159]] — the previous turn's termination reason goes with the previous turn's tally.
+        this.resetTerminationReason();
         // GS2-48 — record this turn's transcript tail for the crash handler.
         updateCrashContext({ transcriptTail: messages.slice(-CRASH_TRANSCRIPT_TAIL_MESSAGES) });
         // [[EXT-29]] §5 — a new user turn is the human being reached, so it ends any negotiation still
@@ -2644,8 +2707,102 @@ export class GthAgentRunner {
         debugLog('Processing messages (event stream)...');
         debugLogObject('Input Messages', messages);
         try {
-            yield* this.agent.streamWithEvents(messages, this.runConfig, signal);
-            yield* this.resolveToolInterruptsWithEvents(signal);
+            // [[TUI-C100]] — **a tool call that never produced a result is closed here, and nowhere
+            // earlier.** `processEventStream` ends a call when its own result arrives and otherwise
+            // leaves it open, because from inside a stream a call suspended at the approval gate looks
+            // exactly like a terminal one: the graph interrupts, the stream returns, and the calls it
+            // announced are still outstanding either way. The two only part company at THIS level — the
+            // prompt is opened by `resolveToolInterruptsWithEvents` below, after the first stream has
+            // finished — so closing anything before that point would tell the surface a call had
+            // finished while the human was still being asked whether it may run at all.
+            //
+            // **Membership in this set at the drain IS "produced no result".** A call is forgotten on its
+            // own `tool_end` or its own `tool_result`, and a call that actually ran always yields the
+            // latter from its `ToolMessage` — so nothing that survives to the loop below has a result,
+            // whatever the reason. The reasons are several and the surface cannot tell most of them
+            // apart: the turn was abandoned; a refusal made the middleware jump back to the model and the
+            // whole round's tool node was skipped; the call was terminal. They do not differ in the one
+            // thing a row reports, so they are closed alike — as a call with no result, which is what an
+            // error result says, and never with the tick and the word `done`, which no arm of this loop
+            // could make true.
+            const unendedToolCalls = new Set();
+            // [[EXT-159]] — did this turn produce an ANSWER? Grammar member (2), "the model produced
+            // nothing", had two sites on the string path and none here, so an empty typed-event turn —
+            // the node's own motivating symptom, on the surface users actually watch — reported
+            // `completed`, i.e. a legitimate hand-back.
+            //
+            // `text` is the exact analogue of the string path's `result.trim().length === 0`: that path
+            // enqueues only `answerTextOf(chunk.content)`, which drops reasoning segments, and this path
+            // splits the same segments into `text` (answer) and `reasoning_delta` (not the answer). So a
+            // reasoning-only turn is empty on BOTH surfaces, and they cannot disagree about one turn.
+            // Testing each delta rather than the concatenation is equivalent: if every delta is blank
+            // their join is blank, and one non-blank delta makes the join non-blank.
+            //
+            // This is CLASSIFICATION only. The string path's empty-stream retry / `invoke` fallback is
+            // still deliberately not duplicated here (see this method's docblock) — naming what happened
+            // is not fixing it.
+            let sawAnswerText = false;
+            const tracking = async function* (source) {
+                for await (const event of source) {
+                    if (event.type === 'tool_start')
+                        unendedToolCalls.add(event.id);
+                    else if (event.type === 'tool_end' || event.type === 'tool_result')
+                        unendedToolCalls.delete(event.id);
+                    else if (event.type === 'text' && event.delta.trim().length > 0)
+                        sawAnswerText = true;
+                    yield event;
+                }
+            };
+            yield* tracking(this.agent.streamWithEvents(messages, this.runConfig, signal));
+            yield* tracking(this.resolveToolInterruptsWithEvents(signal));
+            // The abort is the one case that IS distinguishable here, and it buys the wording rather than
+            // a different outcome: a turn stopped part-way may have had a call in flight, so this says
+            // what is certain — no result arrived — without claiming the command never started.
+            const noResult = signal?.aborted
+                ? 'Cancelled before this call produced a result.'
+                : 'This call did not run.';
+            // Deliberately at the end of the `try` rather than in the `finally`. Esc does NOT break out
+            // of the consumer's loop — it aborts the signal, `streamWithEvents` catches the `AbortError`
+            // and returns cleanly, and `resolveToolInterruptsWithEvents` returns at its own aborted
+            // guard, so an abandoned turn reaches this line like any other and its rows are closed here
+            // too. The case the placement is actually for is a consumer that stops consuming: breaking
+            // out of a `for await`, or calling `return()` on this generator, closes it, and yielding
+            // during that forced return suspends the generator again instead of finishing it — which
+            // would leave `clearNegotiationDisplay()` below unreached. Rows abandoned that way keep
+            // whatever they last said, which is the price of the `finally` still running.
+            //
+            // A close is not cosmetic either way: an unclosed row on the TUI sits at `running` for the
+            // rest of the session, and a client is owed a terminal state for every call it was shown.
+            for (const id of unendedToolCalls) {
+                yield { type: 'tool_result', id, content: noResult, isError: true };
+            }
+            // [[EXT-159]] — the typed-event turn reached its own end. `signal?.aborted` is read again
+            // rather than reused from `noResult` above because a turn can be cancelled with no tool call
+            // outstanding, and that turn owes a reason just as much. First-write-wins keeps whatever the
+            // agent's own sites already said (a refusal, a suspend, an earlier abort).
+            if (signal?.aborted) {
+                this.noteTermination(terminationReason('runner.events-cancelled', 'control', {
+                    category: 'cancelled',
+                    detail: 'signal',
+                }));
+            }
+            else if (!sawAnswerText) {
+                // A turn that ended having said nothing did NOT complete, and saying it did is worse than
+                // saying nothing: this design defines an ABSENT reason as "a site we missed", and a
+                // present-but-false one silences that detector at the one case it was built for.
+                this.noteTermination(terminationReason('runner.events-empty', 'control', 'empty_response'));
+            }
+            else {
+                this.noteCompleted('runner.events-completed');
+            }
+        }
+        catch (error) {
+            // [[EXT-159]] — the typed-event path had NO catch at all, so a provider fault on the surface
+            // most users are looking at was the one termination nothing classified. Re-thrown UNCHANGED:
+            // this site adds a reason and takes nothing away, and the consumer's own error rendering is
+            // not this node's business.
+            this.classifyThrownAt('runner.events-error', error);
+            throw error;
         }
         finally {
             // [[TUI-C69]] §5.4 — **the turn is over, so the argument is over.** Until this existed the
@@ -2660,6 +2817,12 @@ export class GthAgentRunner {
             // In `finally` because an abort and a thrown stream end the turn just as much as a return
             // does, and those are the paths where rows left standing are least likely to be noticed.
             this.clearNegotiationDisplay();
+            // [[EXT-159]] — the one ending that reaches NEITHER the end of the try NOR the catch: a
+            // consumer that stops consuming (breaking out of its `for await`, or calling `return()` on
+            // this generator). Nothing was wrong with the run and nothing failed, so no other site can
+            // speak for it, and without this the turn would end with no reason at all — the state that
+            // must mean "a site we missed".
+            this.noteTermination(terminationReason('runner.events-abandoned', 'control', 'abandoned'));
         }
     }
     /**
@@ -2675,9 +2838,9 @@ export class GthAgentRunner {
      *
      * No-ops (yields nothing) when the agent does not support interrupts
      * (`getPendingToolInterrupts`/`streamWithEventsResume` absent) — that is the only exemption.
-     * As of EXT-52 BOTH backends gate `run_shell_command` and expose the interrupt surface, so the
-     * lean (default) agent is now exactly the agent this loop serves; only an agent implementation
-     * without those methods (e.g. a test double) skips it. Aborts (`signal`) propagate through the
+     * As of EXT-52 the shipped agent gates `run_shell_command` and exposes the interrupt surface, so
+     * the lean agent is exactly the agent this loop serves; only an agent implementation without
+     * those methods (e.g. a test double) skips it. Aborts (`signal`) propagate through the
      * resumed stream.
      */
     async *resolveToolInterruptsWithEvents(signal) {
@@ -2687,19 +2850,29 @@ export class GthAgentRunner {
             return;
         if (!agent.getPendingToolInterrupts || !agent.streamWithEventsResume)
             return;
+        // [[EXT-159]] — see {@link resolveToolInterrupts}: which way the loop left is the fact that
+        // distinguishes this ending, and it is discarded unless the loop itself records it. An abort
+        // `return`s below and never reaches the note, which is right — a cancelled turn was stopped by
+        // the user, not by this bound.
+        let drained = false;
         // Bound the loop defensively so a misbehaving graph that re-suspends forever cannot spin.
         for (let guard = 0; guard < 100; guard++) {
             if (signal?.aborted)
                 return;
             const pending = await agent.getPendingToolInterrupts(runConfig);
-            if (pending.length === 0)
+            if (pending.length === 0) {
+                drained = true;
                 break;
+            }
             const decisions = [];
             for (const tool of pending) {
                 decisions.push(await this.decideToolApproval(tool));
             }
             yield* agent.streamWithEventsResume({ decisions }, runConfig, [], signal);
         }
+        if (!drained) {
+            this.noteTermination(terminationReason('runner.events-interrupt-guard-exhausted', 'control', 'interrupt_drain_guard'));
+        }
     }
     // noinspection JSUnusedGlobalSymbols
     getAgent() {
@@ -2719,6 +2892,133 @@ export class GthAgentRunner {
             /* fail-soft: analytics must never affect a run */
         }
     }
+    /**
+     * [[EXT-159]] — forget the previous turn's termination reason, on both this runner and the live
+     * agent, so a new turn starts with none. Called at the top of each `processMessages` /
+     * `processMessagesWithEvents`, alongside {@link resetRunStats}. Fail-soft.
+     */
+    resetTerminationReason() {
+        this.terminationReason = null;
+        this.agentTerminationReason = null;
+        this.agentFinishReasons = [];
+        try {
+            this.agent?.resetTerminationReason?.();
+        }
+        catch {
+            /* fail-soft: classification must never affect a run */
+        }
+    }
+    /**
+     * [[EXT-159]] — record why the turn ended, **first-write-wins**.
+     *
+     * The runner's two exception wrappers are NESTED, not alternatives: a stream fault is classified
+     * at the inner one, re-thrown, and caught again by the outer one. Under last-write-wins the outer
+     * site would overwrite the inner classification on every streamed failure — the funnel this
+     * taxonomy replaces, rebuilt one level up.
+     */
+    noteTermination(reason) {
+        try {
+            if (this.terminationReason)
+                return;
+            this.terminationReason = reason;
+            // [[EXT-159]] — the debug log carried the wrapped error string and never the classification.
+            // Written at the decision so it survives a session whose surface never got to ask, and so a
+            // dump taken after a kill still holds it (the ring buffer behind `debugLog` is always on).
+            debugLog(terminationLogLine(reason));
+        }
+        catch {
+            /* fail-soft */
+        }
+    }
+    /**
+     * [[EXT-159]] — classify a thrown value at a runner site: record it here AND attach it to the
+     * error, then hand the error back so the throw reads as one expression.
+     *
+     * Both carriers matter. The runner's own field serves a caller holding the runner; the attached
+     * value serves every layer above that only ever sees the error — and neither is the message, so
+     * no user-facing string is the only carrier of the classification.
+     */
+    classifyThrownAt(site, error) {
+        // A reason already on the error was attached by an INNER site that saw the failure first, and
+        // that one is the truer classification — so it is inherited rather than replaced, and the two
+        // carriers cannot end up disagreeing about the same failure.
+        const existing = terminationReasonOf(error);
+        const reason = existing ?? terminationReason(site, 'exception', classifyThrownTermination(error));
+        this.noteTermination(reason);
+        if (!existing)
+            attachTerminationReason(error, reason);
+        return reason;
+    }
+    /**
+     * [[EXT-159]] — classify an approvals stop, which the generic classifier cannot see.
+     *
+     * The gate's errors are typed by their own subclass names, and their prose is the explanation
+     * rather than a diagnosis, so nothing in the exception classifier's grammar recognises one. It
+     * does not need to: this site reaches an `instanceof ApprovalStopError` branch, so it *knows*
+     * what ended the run, and stating the category is more honest than pattern-matching for it.
+     */
+    noteApprovalStop(site, error) {
+        const reason = terminationReason(site, 'control', {
+            category: 'approval_stop',
+            detail: error instanceof Error ? error.name : undefined,
+        });
+        this.noteTermination(reason);
+        attachTerminationReason(error, reason);
+    }
+    /**
+     * [[EXT-159]] — record that the turn ended because the model finished.
+     *
+     * An ordinary completion is a termination too, and recording it is what makes "no reason" mean
+     * *a site nobody classified* rather than *nothing went wrong*. First-write-wins keeps a deeper
+     * site's answer — a refusal or a truncation is what really ended a turn that also returned text.
+     */
+    noteCompleted(site) {
+        this.noteTermination(terminationReason(site, 'control', 'completed'));
+    }
+    /**
+     * [[EXT-159]] — why the just-finished turn ended, or `null` when nothing classified it.
+     *
+     * The agent's answer wins when it has one: its sites (the metadata reader, the cancellation and
+     * suspend paths, the run-ending middlewares) sit INSIDE the runner's catches, so the innermost
+     * classification is the true one. Never throws.
+     */
+    getTerminationReason() {
+        return this.captureAgentTerminationReason() ?? this.terminationReason;
+    }
+    /** [[EXT-159]] — read the live agent's reason into the snapshot (fail-soft). */
+    captureAgentTerminationReason() {
+        try {
+            const reason = this.agent?.getTerminationReason?.();
+            if (reason)
+                this.agentTerminationReason = reason;
+        }
+        catch {
+            /* fail-soft */
+        }
+        return this.agentTerminationReason;
+    }
+    /**
+     * [[EXT-159]] — what the provider said about why each model message stopped, this turn.
+     *
+     * Reads live from the agent while one is present and falls back to the {@link cleanup} snapshot
+     * afterwards, the same way {@link getRunStats} does — `/debug-dump` on the readline surface and
+     * the non-interactive verbs both ask once the agent has been dropped.
+     */
+    getFinishReasonObservations() {
+        return this.captureFinishReasonObservations();
+    }
+    /** [[EXT-159]] — read the live agent's finish-reason observations into the snapshot (fail-soft). */
+    captureFinishReasonObservations() {
+        try {
+            const observed = this.agent?.getFinishReasonObservations?.();
+            if (observed)
+                this.agentFinishReasons = observed;
+        }
+        catch {
+            /* fail-soft */
+        }
+        return this.agentFinishReasons;
+    }
     /** GS2-16 — read the live agent's run stats (fail-soft; empty tally if unavailable). */
     captureRunStats() {
         try {
@@ -2770,6 +3070,12 @@ export class GthAgentRunner {
         // GS2-16: snapshot the agent's run stats BEFORE nulling it, so a post-cleanup reader
         // (runSingleShot records history after calling cleanup) still gets this turn's analytics.
         this.lastRunStats = this.captureRunStats();
+        // [[EXT-159]] — and the agent's termination reason with it, for the same reason: the
+        // single-shot path asks why the run ended after the agent has already been nulled.
+        this.captureAgentTerminationReason();
+        // [[EXT-159]] — likewise the provider's per-message finish reasons, which `/debug-dump` and the
+        // non-interactive verbs read post-cleanup.
+        this.captureFinishReasonObservations();
         if (this.agent && 'cleanup' in this.agent && typeof this.agent.cleanup === 'function') {
             await this.agent.cleanup();
         }