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

package/dist/core/GthAgentRunner.js

@@ -7,7 +7,7 @@ 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 { attachTerminationReason, classifyThrownTermination, replaceTerminationReason, terminationPosture, 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';
@@ -33,6 +33,7 @@ import { getNewRunnableConfig } from '#src/utils/llmUtils.js';
 import { initDebugLogging, debugLog, debugLogError, debugLogObject, } from '#src/utils/debugUtils.js';
 import { updateCrashContext } from '#src/utils/crashHandler.js';
 import { setToolDisplayConfig } from '#src/core/toolDisplay.js';
+import { compactMessages, conversationSize, createModelSummarizer, DEFAULT_KEEP_RECENT, } from '#src/core/compaction.js';
 /**
  * GS2-48 — how many trailing messages of the in-flight turn to hand the crash handler as the
  * transcript tail. A crash file is triage, not the full session, so only the last few messages are
@@ -228,6 +229,12 @@ export class GthAgentRunner {
      * after {@link cleanup} has already dropped the agent.
      */
     agentFinishReasons = [];
+    /**
+     * GS2-23 — how many turns are being driven right now, through either driver. Read by
+     * {@link compactConversation}, which refuses to rewrite the thread underneath a running turn:
+     * the graph would be writing checkpoints for the turn while the compaction wrote a competing one.
+     */
+    turnsInFlight = 0;
     /**
      * CFG-27 — the runtime, session-scoped approvals posture, seeded at {@link init} from
      * {@link resolveApprovals} and thereafter switchable for the session by `/approvals <rung>`.
@@ -284,6 +291,15 @@ export class GthAgentRunner {
      * both are handed to the same matcher, so a runtime refusal and a declared one are one list.
      */
     denyGrants = new ApprovalGrantStore();
+    /**
+     * GS2-20 — told whenever the session-scoped contents of {@link sessionGrants} or
+     * {@link denyGrants} change, so the session can write them against its conversation and a resume
+     * can restore them. Set via {@link setSessionGrantsListener}; `null` means nobody records them,
+     * which is where every surface without a conversation row (ACP, AG-UI, a single-shot run) stays.
+     * Deliberately NOT fired by {@link resumeConversation}: what it installs was read from the store
+     * a moment ago, and writing it straight back would be a no-op with a disk write in it.
+     */
+    sessionGrantsListener = null;
     /**
      * The persisted (`always`) grant store, loaded lazily on first use from
      * `.gsloth/.gsloth-settings/shell-allowlist.json`. Null until a gated call actually needs it, and
@@ -560,6 +576,9 @@ export class GthAgentRunner {
         const removedFromFile = target.origin === 'persisted'
             ? (this.getPersistedDenials()?.remove(target.entry) ?? false)
             : false;
+        // GS2-20 — a lifted session refusal must leave the conversation's record too, or a resume
+        // would put back the very refusal the person just removed.
+        this.notifySessionGrantsChanged();
         const key = renderApprovalEntryObject(target.entry);
         return {
             outcome: 'lifted',
@@ -612,6 +631,106 @@ export class GthAgentRunner {
         }
         return grants;
     }
+    /**
+     * GS2-20 — **the grants that belong to the conversation**: every `session`-scoped entry in the
+     * two runtime stores, deep-copied on the way out for the reason {@link getGrants} gives.
+     *
+     * `always` entries are deliberately left out. They mirror the project's allow-list / deny-list
+     * files, which every run reads for itself; recording them against the conversation as well would
+     * make one decision two records that can disagree, and a resume that restored a lifted one would
+     * resurrect a refusal the person had already removed. What is here is exactly what a fresh
+     * process would otherwise have lost.
+     */
+    getSessionScopedGrants() {
+        const copy = (grant) => ({
+            ...grant,
+            entry: copyApprovalEntry(grant.entry),
+            ...(grant.annotations ? { annotations: { ...grant.annotations } } : {}),
+        });
+        return {
+            allow: this.sessionGrants
+                .list()
+                .filter((grant) => grant.scope === 'session')
+                .map(copy),
+            deny: this.denyGrants
+                .list()
+                .filter((grant) => grant.scope === 'session')
+                .map(copy),
+        };
+    }
+    /**
+     * GS2-20 — hear about every change to the conversation's grants ({@link getSessionScopedGrants}),
+     * after it has landed. The session records them against its conversation row, which is how a
+     * grant outlives the process and reaches a resume. Pass `null` to stop listening.
+     */
+    setSessionGrantsListener(listener) {
+        this.sessionGrantsListener = listener;
+    }
+    /** Fire the listener; a listener that throws must not turn a recorded grant into a failed turn. */
+    notifySessionGrantsChanged() {
+        try {
+            this.sessionGrantsListener?.();
+        }
+        catch {
+            /* fail-soft: recording a grant is a side benefit, never the critical path of the gate */
+        }
+    }
+    /**
+     * GS2-20 — **re-enter a stored conversation: its thread, and its grants.** The ONE seam both
+     * `--resume <id>` (at boot, after {@link init}) and `/resume <id>` (mid-session) go through, so
+     * the two spellings cannot come to mean different things.
+     *
+     * The thread half is {@link resetThread}'s rotation pointed at a stored id instead of a fresh
+     * one: the durable checkpointer is one database serving any thread, so re-entering a conversation
+     * needs no new saver, only `configurable.thread_id` naming the thread whose checkpoint holds its
+     * state. The negotiation window and the rater's noted clarifications go with the old thread for
+     * the reason {@link resetThread} gives — they are context of the conversation being LEFT.
+     *
+     * The grants half replaces the session-scoped grants with the conversation's own. Replaces, not
+     * adds: a grant's lifetime is the conversation, so what the session granted while it was in
+     * another conversation does not follow it here — that stays recorded against the conversation it
+     * was made in. The `always` mirrors stay, because the project files they mirror are still in
+     * force. Every restored grant is stamped `session` whatever the document said, since that is the
+     * only scope this seam is handed and the only one the stores should hold for it.
+     *
+     * The listener is NOT fired: what was installed is what the store already holds.
+     *
+     * **Refuses while a turn is running, and refuses a graph suspended on a pending tool approval**
+     * — the same two refusals as {@link compactConversation}, for the same reason: the runnable
+     * config is what the in-flight work resumes through. Measured without the guard: a mid-turn
+     * call returned normally, the turn's approval `Command({ resume })` then went to the OTHER
+     * thread, the gated tool never ran, the turn died as "Model returned an empty response after
+     * tool execution" — a failure blamed on the model — and the thread being resumed INTO received
+     * a checkpoint from the turn being left. Neither shipped surface can reach this (`/resume` is
+     * idle-only on both), so this is the seam refusing on its own behalf, for its next caller.
+     */
+    async resumeConversation(target) {
+        if (!this.agent || !this.config || !this.runConfig) {
+            throw new Error('AgentRunner not initialized. Call init() first.');
+        }
+        if (this.turnsInFlight > 0) {
+            throw new Error('A turn is still running; wait for it to finish before resuming another conversation.');
+        }
+        const pendingApprovals = (await this.agent.getPendingToolInterrupts?.(this.runConfig)) ?? [];
+        if (pendingApprovals.length > 0) {
+            throw new Error('A tool approval is still pending; answer it before resuming another conversation.');
+        }
+        this.rotateThread(target.threadId);
+        for (const grant of this.sessionGrants.list()) {
+            if (grant.scope === 'session')
+                this.sessionGrants.remove(grant.entry);
+        }
+        for (const grant of this.denyGrants.list()) {
+            if (grant.scope === 'session')
+                this.denyGrants.remove(grant.entry);
+        }
+        for (const grant of target.grants.allow) {
+            this.sessionGrants.add({ ...grant, scope: 'session' });
+        }
+        for (const grant of target.grants.deny) {
+            this.denyGrants.add({ ...grant, scope: 'session' });
+        }
+    }
     /**
      * §4.7.1 — **which of each server's annotation hints this session believes**, for display.
      *
@@ -792,6 +911,16 @@ export class GthAgentRunner {
         initDebugLogging(configIn.debugLog ?? false);
         debugLog(`Initializing GthAgentRunner with command: ${command || 'default'}`);
         this.runConfig = getNewRunnableConfig();
+        // GS2-20 — drive a caller-supplied thread when there is one, so the durable checkpointer writes
+        // under the id the session has already recorded against its conversation (and, on a resume,
+        // reads back the state stored there). Overlaid on the minted config rather than replacing it, so
+        // the recursion limit and anything else `getNewRunnableConfig` sets survive.
+        if (options?.threadId) {
+            this.runConfig = {
+                ...this.runConfig,
+                configurable: { ...this.runConfig.configurable, thread_id: options.threadId },
+            };
+        }
         debugLogObject('Runnable Config', this.runConfig);
         this.warnIfSubagentsCannotBeHonored(configIn, command ?? options?.owningCommand);
         this.agent = this.agentFactory(this.statusUpdate, this.resolvers);
@@ -850,6 +979,25 @@ export class GthAgentRunner {
         this.negotiation.noteUserMessages(humanMessageTexts(messages));
         debugLog('Processing messages...');
         debugLogObject('Input Messages', messages);
+        return this.runTurn(messages, 0);
+    }
+    /**
+     * The turn itself, separated from the per-turn bookkeeping above so [[EXT-160]] can run it twice.
+     *
+     * `attempt` is 0 for the turn the user asked for and 1 for the single retry that follows a
+     * compaction; nothing else calls this. The retry passes an EMPTY message list, because the user's
+     * message is already in the graph's state — the input step commits before the model step throws
+     * (measured), so re-sending it would append a second copy of the same turn.
+     *
+     * The preamble is deliberately NOT repeated on the retry: resetting the analytics tally, ending
+     * the negotiation and re-recording the crash transcript are things a NEW user turn does, and a
+     * retry is the same turn being attempted again.
+     */
+    async runTurn(messages, attempt) {
+        if (!this.agent || !this.config || !this.runConfig) {
+            throw new Error('AgentRunner not initialized. Call init() first.');
+        }
+        this.turnsInFlight++;
         try {
             // Decision: Use streaming or non-streaming based on config
             if (this.config.streamOutput) {
@@ -951,6 +1099,18 @@ export class GthAgentRunner {
                 this.noteApprovalStop('runner.turn-approval-stop', error);
                 throw error;
             }
+            // [[EXT-160]] — **the reactive seam: catch, classify, compact, retry once.**
+            //
+            // Here rather than in the streaming branch's inner `catch` because BOTH paths reach this one
+            // and only one of them has an inner catch — and because the streaming path does not always
+            // use it: an overflow raised while the stream is being CREATED (`await this.agent.stream(…)`,
+            // above the inner `try`) lands here too, which is exactly what the local measurement showed.
+            // One seam, both paths, once each.
+            const retryAfterCompaction = await this.handleContextOverflow(error, attempt);
+            if (retryAfterCompaction) {
+                const answer = await this.runTurn([], attempt + 1);
+                return answer;
+            }
             // Handle agent invocation errors
             debugLogError('Agent processing', error);
             // [[EXT-159]] — the OUTER of two nested wrappers. On the streaming path the inner one has
@@ -969,6 +1129,7 @@ export class GthAgentRunner {
             // the one place the panel outlives its turn. Display-only, and a no-op on today's readline
             // surface, which appends to scrollback and implements no `end`.
             this.clearNegotiationDisplay();
+            this.turnsInFlight--;
         }
     }
     /**
@@ -2566,6 +2727,8 @@ export class GthAgentRunner {
         // refusal in force for this run even when the file cannot be written, and the display
         // de-duplicates by entry identity.
         this.denyGrants.add({ entry, grantedAt, scope: landed });
+        // GS2-20 — after the record, never before it: the listener reads the stores.
+        this.notifySessionGrantsChanged();
         return landed;
     }
     /**
@@ -2602,6 +2765,8 @@ export class GthAgentRunner {
         const saved = persisted?.add({ ...grant, grantedAt, scope: 'always' }) ?? false;
         const grantScope = saved ? 'always' : 'session';
         this.sessionGrants.add({ ...grant, grantedAt, scope: grantScope });
+        // GS2-20 — after the record, never before it: the listener reads the stores.
+        this.notifySessionGrantsChanged();
         return grantScope;
     }
     /**
@@ -2660,6 +2825,9 @@ export class GthAgentRunner {
             // place would silently swallow the human's re-approval of the same tool.
             this.sessionGrants.remove(entry);
             persisted?.remove(entry);
+            // GS2-20 — and out of the conversation's record, so a resume cannot bring back a grant the
+            // tool has since weakened out from under.
+            this.notifySessionGrantsChanged();
             this.statusUpdate(StatusLevel.WARNING, describeWeakenedGrant(entry, weakened, held.annotations, effective));
         }
     }
@@ -2706,6 +2874,7 @@ export class GthAgentRunner {
         this.negotiation.noteUserMessages(humanMessageTexts(messages));
         debugLog('Processing messages (event stream)...');
         debugLogObject('Input Messages', messages);
+        this.turnsInFlight++;
         try {
             // [[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
@@ -2823,6 +2992,7 @@ export class GthAgentRunner {
             // 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'));
+            this.turnsInFlight--;
         }
     }
     /**
@@ -3033,7 +3203,7 @@ export class GthAgentRunner {
     }
     /**
      * GS2-16 — the analytics harvested from the just-finished turn (token usage + invoked tools),
-     * to thread into the opt-in history recorder. Reads live from the agent when one is present,
+     * to thread into the local history recorder. Reads live from the agent when one is present,
      * otherwise the snapshot captured at {@link cleanup} (the single-shot path reads post-cleanup).
      * Never throws.
      */
@@ -3053,6 +3223,13 @@ export class GthAgentRunner {
      * of any checkpointer-specific delete API, mirroring how `init()` mints the initial config.
      */
     resetThread() {
+        this.rotateThread();
+    }
+    /**
+     * Move the runner onto another thread: a fresh one (`/clear`) or a stored one (a resume — see
+     * {@link resumeConversation}). Everything that is context of the thread being left goes with it.
+     */
+    rotateThread(threadId) {
         // [[EXT-29]] §5.1 — the negotiation goes with the thread, user messages included. The rater's
         // last-5 window is conversation context; leaving it behind a `/clear` would quote the user's
         // previous conversation into a rating made after they asked for it to be forgotten.
@@ -3062,9 +3239,253 @@ export class GthAgentRunner {
         // sentence above is the whole argument for dropping them: they would decide how rows are drawn
         // in a conversation the user has just asked to start fresh.
         this.clearRaterClarifications();
-        this.runConfig = getNewRunnableConfig();
+        const minted = getNewRunnableConfig();
+        // GS2-20 — overlaid on the minted config exactly as `init` overlays a caller's thread, so the
+        // recursion limit and anything else `getNewRunnableConfig` sets survive the switch.
+        this.runConfig = threadId
+            ? { ...minted, configurable: { ...minted.configurable, thread_id: threadId } }
+            : minted;
         debugLogObject('Reset Runnable Config', this.runConfig);
     }
+    /**
+     * GS2-23 — **fold the older conversation into a summary, in the live graph.** The idle,
+     * user-invoked seam: what `/compact` calls between turns.
+     *
+     * It is not the seam for the involuntary paths. EXT-160's compact-and-retry runs inside the
+     * driver's `try`, where a turn is in flight and this method refuses; that path composes
+     * `compactMessages` with `replaceGraphMessages` (or the agent's `replaceConversationMessages`)
+     * from inside the turn, or adds a guard-free internal when it needs one, rather than calling this.
+     *
+     * Reads the thread's messages from the graph, runs the shared `compactMessages` with the
+     * summariser bound to the session model, and writes the replacement back through the graph's own
+     * state update — so the compacted history is checkpointed and a later resume loads it compacted.
+     * `after` is read back from the graph rather than computed, so the report describes what the
+     * graph actually holds.
+     *
+     * Refuses while a turn is running (the two drivers count themselves in and out). Refuses a graph
+     * suspended on a pending tool approval — idle, but not between turns: the state write lands on
+     * such a graph and erases the interrupt payload (measured: one pending interrupt becomes none,
+     * `next` preserved), so the approval could never be answered. A graph a THROWN turn left behind
+     * is not refused: its checkpoint ends on the pending human turn with no interrupt, the write
+     * lands, and the next turn runs from the compacted state. Invariant (c) is relative there — the
+     * mechanism never creates a trailing assistant turn and the pending human stays last; having the
+     * next human turn present before the model is invoked again is the caller's job. Does nothing on
+     * a conversation no longer than the kept tail: `changed: false`, nothing written.
+     */
+    /**
+     * EXT-161 — the preventive compaction threshold in force, with its provenance, or `undefined`
+     * when this session has no resolved model to derive one from.
+     *
+     * Read by `/status` and by the bare `/autocompact`. Asynchronous because resolving a context
+     * window can reach the models.dev cache (and, on a cold cache, the network) — memoised behind
+     * the agent's one window resolution, so calling it per command costs nothing after the first.
+     *
+     * **Never throws.** A status line that could take a session down would be worse than a missing
+     * one, and every source under it already degrades to "unknown" rather than failing.
+     */
+    async getAutocompactStatus() {
+        try {
+            return await this.agent?.autocompact?.status();
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * EXT-161 — move the preventive compaction threshold for the rest of this session.
+     *
+     * Returns the status that LANDED, so the surface's notice describes what is actually in force
+     * rather than what was asked for — the same discipline `/approvals` and `/compact` follow.
+     * `undefined` when there is no resolved model, in which case nothing was changed.
+     *
+     * Takes an already-parsed budget: the grammar is the shared parser's, and a second entry point
+     * accepting text would be a second place it could drift.
+     */
+    async setAutocompactThreshold(budget) {
+        const controller = this.agent?.autocompact;
+        if (!controller)
+            return undefined;
+        controller.setSessionBudget(budget);
+        return this.getAutocompactStatus();
+    }
+    async compactConversation(options = {}) {
+        if (!this.agent || !this.config || !this.runConfig) {
+            throw new Error('AgentRunner not initialized. Call init() first.');
+        }
+        if (this.turnsInFlight > 0) {
+            throw new Error('A turn is still running; wait for it to finish before compacting.');
+        }
+        const agent = this.agent;
+        if (!agent.getConversationMessages || !agent.replaceConversationMessages) {
+            throw new Error('This agent does not expose its conversation state, so it cannot be compacted.');
+        }
+        const runConfig = this.runConfig;
+        const pendingApprovals = (await agent.getPendingToolInterrupts?.(runConfig)) ?? [];
+        if (pendingApprovals.length > 0) {
+            throw new Error('A tool approval is still pending; answer it before compacting.');
+        }
+        return this.applyCompaction(options);
+    }
+    /**
+     * [[EXT-160]] — the read-compact-write itself, with **no turn-state guards**: the shared internal
+     * behind both the idle `/compact` above and the involuntary compact-and-retry inside a turn.
+     *
+     * It exists because {@link compactConversation}'s guards are exactly wrong for the involuntary
+     * case. That method refuses while `turnsInFlight > 0`, and the overflow seam runs inside the
+     * driver's `catch`, where the turn it is recovering is still counted in — so calling the public
+     * method from there throws every time. The alternative was for the seam to compose
+     * `compactMessages` with `replaceConversationMessages` itself, which is the same six steps written
+     * twice: two places to keep the summariser, the keep-recent default, the read-back and the
+     * `changed: false` shape in agreement. One implementation with the guards on the caller that needs
+     * them is the version that cannot drift.
+     *
+     * **The pending-approval guard is dropped here too, and that is deliberate rather than an
+     * oversight.** `/compact` refuses under a pending approval because the user is mid-decision about
+     * a tool call, and folding the conversation under them would rewrite the history that decision is
+     * being made against. The involuntary path cannot be in that position: it runs from the `catch`
+     * of a model call that threw, and a model call that threw produced no tool call, so there is no
+     * new interrupt to answer. An approval raised EARLIER in the same turn has already been resolved
+     * — the driver resolves interrupts in a loop before the model is asked again — so by the time an
+     * overflow can be caught, there is nothing pending for the guard to protect.
+     */
+    async applyCompaction(options = {}) {
+        if (!this.agent || !this.config || !this.runConfig) {
+            throw new Error('AgentRunner not initialized. Call init() first.');
+        }
+        const agent = this.agent;
+        if (!agent.getConversationMessages || !agent.replaceConversationMessages) {
+            throw new Error('This agent does not expose its conversation state, so it cannot be compacted.');
+        }
+        const runConfig = this.runConfig;
+        const keepRecent = options.keepRecent ?? DEFAULT_KEEP_RECENT;
+        const messages = await agent.getConversationMessages(runConfig);
+        const before = conversationSize(messages);
+        const result = await compactMessages({
+            messages,
+            summarize: createModelSummarizer(this.config.llm),
+            keepRecent,
+            ...(options.focus !== undefined ? { focus: options.focus } : {}),
+        });
+        if (!result.changed) {
+            return {
+                changed: false,
+                removedCount: 0,
+                keptCount: messages.length,
+                keepRecent,
+                summaryText: '',
+                before,
+                after: before,
+            };
+        }
+        await agent.replaceConversationMessages(runConfig, result.messages);
+        const after = conversationSize(await agent.getConversationMessages(runConfig));
+        debugLog(`Compacted the conversation: ${result.removedCount} folded, ${result.keptCount} kept, ` +
+            `${before.messages}→${after.messages} messages, ${before.characters}→${after.characters} chars`);
+        return {
+            changed: true,
+            removedCount: result.removedCount,
+            keptCount: result.keptCount,
+            keepRecent,
+            summaryText: result.summaryText,
+            before,
+            after,
+        };
+    }
+    /**
+     * [[EXT-160]] — **decide what a thrown turn's context overflow means, and act on it once.**
+     *
+     * Returns `true` when the conversation was made smaller and the turn is worth attempting again;
+     * `false` for everything else, including every failure that is not an overflow at all, in which
+     * case the caller's existing error path runs untouched.
+     *
+     * **The predicate is the taxonomy's, never a private one.** The category comes from the reason an
+     * inner site already attached, or failing that from `classifyThrownTermination`, and the decision
+     * is `remedy === 'reduce-context'` read out of the one POSTURE table. That is what makes this the
+     * same fact [[EXT-159]] surfaces rather than a second opinion about it — and it is why an
+     * `output_truncated` turn is not compacted here: the answer was cut off against the output cap,
+     * its remedy is `change-request`, and folding the history would not add a single token of room to
+     * the part that ran out. `context_overflow` is also the one category whose posture separates the
+     * two facts this method depends on: retrying the SAME prompt is hopeless (`retryableAsIs: false`,
+     * which is what `ContextOverflowError.getRetryable()` says too) while retrying a SMALLER one is
+     * the whole move (`retryableAfterRemedy: true`).
+     *
+     * **One retry, and the reasons a compaction can decline.** A second overflow after the history has
+     * already been folded is not worth a second fold — the tail it just kept is what the next
+     * compaction would have to eat — so `attempt > 0` terminates at its own site. So does a compaction
+     * that had nothing to fold, could not get a summary, or found an agent with no conversation state:
+     * each is "the automatic remedy was tried and had nothing to give", which is a different fact from
+     * "the model said no" and deserves to be said in its own words.
+     *
+     * The original overflow error is what surfaces in every declining branch. A compaction that throws
+     * has its own failure logged and dropped rather than re-thrown, because replacing a diagnosis the
+     * whole node exists to preserve with a summariser's stack trace buries the one useful thing the
+     * turn produced.
+     */
+    async handleContextOverflow(error, attempt) {
+        const category = terminationReasonOf(error)?.category ?? classifyThrownTermination(error).category;
+        if (terminationPosture(category).remedy !== 'reduce-context')
+            return false;
+        if (attempt > 0) {
+            this.overrideTerminationReason(error, terminationReason('runner.overflow-compact-exhausted', 'exception', {
+                category: 'context_overflow',
+                detail: 'overflowed again after compaction',
+            }));
+            this.statusUpdate(StatusLevel.WARNING, 'The context overflowed again after compacting, so this turn was ended. Start a new ' +
+                'conversation, or narrow what this turn is asking for.');
+            return false;
+        }
+        // An agent that exposes no conversation state cannot be compacted at ALL, which is a different
+        // fact from a compaction that ran and had nothing to give — and only the second is something
+        // this seam knows. So nothing is overridden here: the wrapper's own classification is the
+        // truest thing anyone has, and claiming the remedy was tried would be false.
+        const agent = this.agent;
+        if (!agent?.getConversationMessages || !agent?.replaceConversationMessages) {
+            debugLog('Context overflow: this agent exposes no conversation state, so it cannot be compacted.');
+            return false;
+        }
+        let compaction;
+        try {
+            compaction = await this.applyCompaction();
+        }
+        catch (compactionError) {
+            debugLogError('Compacting after a context overflow', compactionError);
+            compaction = { changed: false };
+        }
+        if (!compaction.changed) {
+            this.overrideTerminationReason(error, terminationReason('runner.overflow-compact', 'exception', {
+                category: 'context_overflow',
+                detail: 'nothing left to compact',
+            }));
+            this.statusUpdate(StatusLevel.WARNING, 'The context overflowed and there was nothing left to compact, so this turn was ended. ' +
+                'Start a new conversation, or narrow what this turn is asking for.');
+            return false;
+        }
+        this.statusUpdate(StatusLevel.INFO, `The context overflowed, so ${compaction.removedCount} earlier messages were folded into a ` +
+            `summary (${compaction.before.messages}→${compaction.after.messages} messages). Retrying.`);
+        // The retry is a fresh attempt and owes its own reason: the FULL reset, so the failed attempt's
+        // provider finish reasons go with it rather than being read later as the retry's.
+        this.resetTerminationReason();
+        return true;
+    }
+    /**
+     * [[EXT-160]] — record a reason that OVERRIDES what an inner site already said, on both carriers.
+     *
+     * {@link noteTermination} is first-write-wins and {@link classifyThrownAt} inherits, which is
+     * right for the nested wrappers they serve: the inner site saw the failure first. The overflow
+     * seam is the one site that legitimately knows better — it has watched the same turn overflow
+     * twice, or watched the remedy come back empty, and the wrapper that classified the throw saw
+     * neither. Both carriers move together so the runner's field and the error can never disagree.
+     */
+    overrideTerminationReason(error, reason) {
+        try {
+            this.terminationReason = reason;
+            replaceTerminationReason(error, reason);
+            debugLog(terminationLogLine(reason));
+        }
+        catch {
+            /* fail-soft: classification must never affect a run */
+        }
+    }
     async cleanup() {
         debugLog('Cleaning up GthAgentRunner...');
         // GS2-16: snapshot the agent's run stats BEFORE nulling it, so a post-cleanup reader