aiden-runtime 4.1.5 → 4.6.0

package/dist/core/v4/aidenAgent.js

@@ -40,8 +40,73 @@
  * `urlProvenance.ts`, `intentPreArm.ts`. Those modules predate this rewrite
  * and stay as-is.
  */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AidenAgent = void 0;
+// v4.1.6 spike — Task Completion Engine (TCE) per-turn loop detector
+// + recovery controller. Default ON as of v4.2 Phase 6 — set
+// AIDEN_TCE=0 to disable. Zero
+// behavioral change when unset. See core/v4/turnState.ts.
+const turnState_1 = require("./turnState");
+// v4.2 Phase 1 — per-tool result verifier. Same TCE gate as
+// TurnState (default ON, opt-out via AIDEN_TCE=0); classification
+// feeds the recovery controller.
+const verifier_1 = require("./verifier");
+// v4.2 Phase 2 — tool-failure WHY-classifier. Runs after the verifier
+// when verification.ok === false. Records-only; Phase 3 will act.
+const failureClassifier_1 = require("./failureClassifier");
+// v4.2 Phase 3 — structured RecoveryReport. Built ONLY when the
+// recovery controller's surface stage fires (tool_loop); enriches the
+// existing surface card with summary + category breakdown + dominant
+// guidance. Implicitly gated by TCE being enabled (surface only
+// reachable when TurnState is enabled — default ON as of Phase 6).
+const recoveryReport_1 = require("./recoveryReport");
+// v4.6 Phase 3b — self-improvement loop. Durable cross-session
+// failure ledger + recovery report writes. Loaded lazily inside the
+// per-call branch so a missing singleton (test agents without a
+// daemon DB) never blocks the agent loop.
+const signatureBuilder_1 = require("./selfimprovement/signatureBuilder");
+const recoveryStore_1 = require("./selfimprovement/recoveryStore");
+// v4.2 Phase 4 — checkpoint / restore. Lets the recovery controller
+// roll conversation messages + TurnState internals back to before a
+// looping tool started failing, so the model retries from a clean
+// baseline. Hard-blocked on iterations containing mutating tools
+// (never claim to undo executed side effects). All-no-op when
+// TCE is opted out via AIDEN_TCE=0 — capture / mark / find /
+// restore all short-circuit.
+const checkpoint_1 = require("./checkpoint");
 const skillEnforcement_1 = require("./agent/skillEnforcement");
 const urlProvenance_1 = require("./agent/urlProvenance");
 const intentPreArm_1 = require("./agent/intentPreArm");
@@ -58,6 +123,14 @@ class AidenAgent {
     constructor(opts) {
         this.skillMinerTurnIdx = 0;
         // ── Cross-call state ─────────────────────────────────────────────────
+        /**
+         * v4.6 Phase 1 — current per-turn AbortSignal, exposed to tools that need
+         * to construct child signal chains (specifically `spawn_sub_agent`). Set
+         * at the top of `runTurnLoop` from `runOptions.signal`, cleared before
+         * the loop returns. Read via `getCurrentSignal()`. Per-agent-instance —
+         * not shared across agents; a child agent has its own `_currentSignal`.
+         */
+        this._currentSignal = undefined;
         /** Cached system prompt — invalidated by setPersonalityOverlay/markMemoryDirty/explicit. */
         this.cachedSystemPrompt = null;
         this.compressionEvents = 0;
@@ -92,6 +165,7 @@ class AidenAgent {
         this.onSkillCandidate = opts.onSkillCandidate;
         this.resolveVerifiedFlag = opts.resolveVerifiedFlag;
         this.resolveToolset = opts.resolveToolset;
+        this.resolveMutates = opts.resolveMutates;
         this.promptBuilder = opts.promptBuilder;
         this.promptBuilderOptions = opts.promptBuilderOptions;
         this.contextCompressor = opts.contextCompressor;
@@ -108,6 +182,15 @@ class AidenAgent {
         this.onPromptBuilt = opts.onPromptBuilt;
         this.onProviderRequestStart = opts.onProviderRequestStart;
         this.lookupSkillRequiredTools = opts.lookupSkillRequiredTools;
+        // v4.5 Phase 7 — explicit sessionId. Existing access path
+        // `(this as { sessionId?: string }).sessionId` at line 751–752
+        // already reads from `this.sessionId`; setting it here keys
+        // docker / browser / TurnState per session for daemon-mode
+        // turns. Interactive REPL callers don't pass this and continue
+        // hitting the 'session' fallback.
+        if (typeof opts.sessionId === 'string' && opts.sessionId.length > 0) {
+            this.sessionId = opts.sessionId;
+        }
         // Phase v4.1.2-slice3: optional health registry (constructor-
         // injected per the slice3 decision tree — no singleton). When
         // wired, the caller already plumbed trackers into each subsystem
@@ -227,6 +310,17 @@ class AidenAgent {
     getEmptyResponseMetrics() {
         return { ...this.emptyResponseMetrics };
     }
+    /**
+     * v4.6 Phase 1 — return the AbortSignal currently associated with this
+     * agent's active `runTurnLoop`, or `undefined` if the agent is between
+     * turns. Used by the `spawn_sub_agent` tool to construct a child signal
+     * chain that cascades parent aborts to the child (Flag 1 pattern: tool
+     * captures the parent agent reference at construction time and reads
+     * the current signal from the instance at dispatch time).
+     */
+    getCurrentSignal() {
+        return this._currentSignal;
+    }
     // ── Main entry: runConversation ──────────────────────────────────────
     async runConversation(history, options = {}) {
         // 1. Refresh memory snapshot if the dirty bit was set since last turn.
@@ -304,7 +398,21 @@ class AidenAgent {
             }
         }
         // 10. SkillTeacher post-loop observation + proposal.
+        //
+        // v4.1.6 Polish 2 — `handleProposal` previously ran INLINE here,
+        // awaiting `callbacks.promptUser` (an inquirer modal) before
+        // `runConversation` returned. That made the modal fire BEFORE
+        // chatSession rendered the agent's reply on screen, so users
+        // saw "Save this as a reusable skill?" pop up mid-turn — feels
+        // like an interruption.
+        //
+        // New flow: agent ONLY observes here. When a proposal needs user
+        // confirmation (tier_3_propose with a promptUser callback), the
+        // proposal is surfaced in `AidenAgentResult.skillProposal` and
+        // chatSession handles the prompt + create dance AFTER rendering
+        // the reply. Tier_4_auto still runs inline (no prompt needed).
         let skillCreated;
+        let skillProposal;
         if (this.skillTeacher) {
             try {
                 const traceForTeacher = loopResult.toolCallTrace.map((entry, i) => ({
@@ -316,9 +424,20 @@ class AidenAgent {
                 }));
                 const proposal = await this.skillTeacher.observeTurn(history, traceForTeacher, loopResult.finishReason !== 'stop');
                 if (proposal) {
-                    const result = await this.skillTeacher.handleProposal(proposal, this.skillTeacherCallbacks);
-                    if (result.created && result.skillName) {
-                        skillCreated = result.skillName;
+                    // Defer to chatSession only when there's a prompt callback
+                    // wired (tier_3_propose path). Otherwise run inline to
+                    // preserve tier_4_auto and tier_off behaviour.
+                    const hasPromptCallback = typeof this.skillTeacherCallbacks?.promptUser === 'function';
+                    if (hasPromptCallback) {
+                        // Surface the proposal back to chatSession; do NOT call
+                        // handleProposal here.
+                        skillProposal = proposal;
+                    }
+                    else {
+                        const result = await this.skillTeacher.handleProposal(proposal, this.skillTeacherCallbacks);
+                        if (result.created && result.skillName) {
+                            skillCreated = result.skillName;
+                        }
                     }
                 }
             }
@@ -369,11 +488,20 @@ class AidenAgent {
             toolCallTrace: loopResult.toolCallTrace,
             honestyFindings,
             skillCreated,
+            // v4.1.6 Polish 2 — deferred to chatSession's post-render
+            // handler when the SkillTeacher proposal needs user
+            // confirmation. Undefined when no proposal, when tier auto-
+            // handled inline, or when the teacher's observation faulted.
+            skillProposal,
             compressionEvents: this.compressionEvents,
             auxiliaryUsage: this.auxiliaryClient?.getUsage() ?? {},
             skillEnforcement: { ...this.skillEnforcementMetrics },
             urlProvenance: { ...this.urlProvenanceMetrics },
             emptyResponse: { ...this.emptyResponseMetrics },
+            // v4.1.6 spike (TCE) — surfaced when TurnState hit the surface
+            // threshold mid-turn. chatSession reads this to render the
+            // structured-failure card; undefined on all other finishReasons.
+            toolLoopCard: loopResult.toolLoopCard,
         };
     }
     // ── Private helpers ──────────────────────────────────────────────────
@@ -442,6 +570,23 @@ class AidenAgent {
     async narrowTools(userMsg, history) {
         if (!this.plannerGuard)
             return this.tools;
+        // v4.6 Phase 2M — runtime toggle gates the keyword-based narrower.
+        // Default OFF: smart models (GPT-5.5, Claude Sonnet 4.5+, Opus)
+        // pick tools fine from the full catalog every turn, matching the
+        // reference multi-agent system's pattern. Opt in via env
+        // (AIDEN_PLANNER_GUARD=1) or `/planner-guard on` for small local
+        // models that need help. The toggle is read on each call so a
+        // mid-conversation flip takes effect on the next turn without
+        // restarting the agent.
+        //
+        // Lazy `require` to avoid a hard import dependency in the agent
+        // core — pure unit tests of AidenAgent that don't initialise the
+        // runtime toggles singleton keep working (the lazy getter returns
+        // an env-only fallback resolver per runtimeToggles.ts:213).
+        const { getRuntimeToggles } = await Promise.resolve().then(() => __importStar(require('./runtimeToggles')));
+        if (!getRuntimeToggles().isEnabled('planner_guard')) {
+            return this.tools;
+        }
         const decision = await this.plannerGuard.decide(userMsg, history);
         this.onPlannerGuardDecision?.(decision);
         const allowed = new Set(decision.selectedTools);
@@ -458,13 +603,33 @@ class AidenAgent {
      * `runConversation` enriches with post-loop scan output.
      */
     async runTurnLoop(initialMessages, tools, trackers, runOptions) {
+        // v4.6 Phase 1 — expose the per-turn signal to tools via
+        // `getCurrentSignal()`. Set at loop entry; cleared before the return
+        // below. Tools that need the parent's signal (e.g. `spawn_sub_agent`
+        // building a child cancellation chain) capture the agent reference at
+        // construction time and read this field at dispatch time. If the loop
+        // throws, the stale value persists until the next call's set —
+        // acceptable because the only consumer is in-flight tool dispatch,
+        // which can only run while the loop is mid-execution.
+        this._currentSignal = runOptions.signal;
         const messages = [...initialMessages];
         const toolCallTrace = [];
+        // v4.6 Phase 3b — per-turn signature tracker for failure → success
+        // transitions. Each entry records the signatureId + failure count
+        // observed so far for a given signature THIS turn. When a verifier
+        // later reports `ok` for a tool call whose signature has prior
+        // failures, we record a recovery report. Keyed by signature string
+        // (the canonical `tool:category[:hash]` form).
+        const turnFailureTracker = new Map();
         // Internal trace mirror that retains tool-call arguments — Honesty's
         // shape doesn't include args, but SkillTeacher needs them. Both live
         // off the same entry index.
         const fullTrace = [];
         const totalUsage = { inputTokens: 0, outputTokens: 0 };
+        // v4.2 Phase 3 — turn start timestamp for RecoveryReport duration.
+        // Captured here so any code path (early-return / error / surface)
+        // can compute wallclock duration consistently.
+        const turnStartedAt = Date.now();
         let turnCount = 0;
         let toolCallCount = 0;
         let fallbackActivated = false;
@@ -473,7 +638,37 @@ class AidenAgent {
         let emptyRetriesUsed = 0;
         let finishReason = 'stop';
         let finalContent = '';
+        // v4.1.6 spike (TCE) — per-turn loop detection + recovery state.
+        // Default ON as of v4.2 Phase 6 — set AIDEN_TCE=0 to disable.
+        // When disabled, TurnState.recordToolCall short-circuits with
+        // `{kind: 'allow'}` and the entire v4.2 recovery surface stays
+        // dormant (zero behavioural change vs v4.1.6).
+        const turnState = new turnState_1.TurnState();
+        // v4.2 Phase 1 — per-tool verifier registry. Constructed
+        // unconditionally (cheap, no side effects) but only used to
+        // classify tool outcomes when TCE is enabled; verification args
+        // are passed to TurnState only inside the gated branch below.
+        const verifierRegistry = (0, verifier_1.buildDefaultRegistry)();
+        // v4.2 Phase 2 — per-tool failure classifier. Same gating as
+        // the verifier; only runs when verification.ok === false. Phase 2
+        // records-only — Phase 3 wires recovery actions off the category.
+        const failureClassifier = (0, failureClassifier_1.buildDefaultClassifier)();
+        let toolLoopCard = undefined;
         while (true) {
+            // v4.6 prep — between-iteration cooperative-cancellation check.
+            // When the caller passed an AbortSignal that has aborted, exit
+            // immediately with `finishReason: 'interrupted'`. Delta accumulation
+            // on abort is deferred — finalContent stays '' in this prep dispatch
+            // (see docs/v4.6/phase-1-design.md §11.0).
+            if (runOptions.signal?.aborted) {
+                finishReason = 'interrupted';
+                finalContent = '';
+                break;
+            }
+            // v4.1.6 spike — decrement cooldown counters once per iteration
+            // so cooled-down tools eventually return to the schemas. No-op
+            // when TCE is disabled.
+            turnState.advanceIteration();
             if (turnCount >= this.maxTurns) {
                 finishReason = 'budget_exhausted';
                 break;
@@ -491,12 +686,36 @@ class AidenAgent {
                 this.onBudgetWarning?.('warning', turnCount, this.maxTurns);
             }
             // ── Provider call (stream or non-stream) ──────────────────────────
+            //
+            // v4.1.6 spike (TCE) — filter cooled-down tools out of the
+            // schemas we send to the provider. The model literally cannot
+            // see (and therefore cannot request) a cooled-down tool until
+            // its cooldown counter decrements to zero via
+            // `turnState.advanceIteration()`. No-op when TCE disabled
+            // (`getCooledDownTools()` returns []).
+            let effectiveTools = tools;
+            const cooledDown = turnState.getCooledDownTools();
+            if (cooledDown.length > 0) {
+                const cdSet = new Set(cooledDown);
+                effectiveTools = tools.filter((t) => !cdSet.has(t.name));
+            }
             let output;
             try {
-                output = await this.callProvider(messages, tools, runOptions);
+                output = await this.callProvider(messages, effectiveTools, runOptions);
             }
             catch (err) {
                 const error = err instanceof Error ? err : new Error(String(err));
+                // v4.6 prep — external abort takes priority over fallback. An
+                // AbortError surfaced from the adapter when input.signal aborted
+                // is NOT a transient transport failure; surface it immediately
+                // as `finishReason: 'interrupted'` so the calling spawn primitive
+                // can route correctly. Detect via either the live signal flag or
+                // the error name (covers both pre-fetch and mid-flight aborts).
+                if (runOptions.signal?.aborted || error.name === 'AbortError') {
+                    finishReason = 'interrupted';
+                    finalContent = '';
+                    break;
+                }
                 if (this.fallback && !fallbackActivated) {
                     const next = await this.fallback.activate(error, turnCount);
                     if (next) {
@@ -511,6 +730,25 @@ class AidenAgent {
             }
             totalUsage.inputTokens += output.usage?.inputTokens ?? 0;
             totalUsage.outputTokens += output.usage?.outputTokens ?? 0;
+            // v4.2 Phase 4 — capture the state going INTO this iteration's
+            // tool dispatch. MUST run BEFORE `messages.push(assistantMsg)`
+            // so the checkpoint represents "the conversation before the
+            // model decided to call this iteration's tools". If rollback
+            // fires later, truncating `messages.length` to
+            // `checkpoint.messages.length` drops the assistant tool_call
+            // message together with its tool result messages — preserving
+            // tool_call/tool_result pairing in the rolled-back state.
+            //
+            // Capturing AFTER the assistant push (the prior placement) was
+            // a real bug: rollback would leave the assistant tool_call in
+            // history without its tool results, producing strict-provider
+            // 400 errors of the form "No tool output found for function
+            // call <id>". Tests in tests/v4/core/checkpoint-integration
+            // assert the post-rollback messages array contains zero orphan
+            // assistant tool_calls — this position is part of the contract.
+            //
+            // No-op when TCE is disabled (AIDEN_TCE=0) or checkpointDepth=0.
+            turnState.captureCheckpoint(messages, turnCount);
             // ── Append assistant message ──────────────────────────────────────
             const assistantMsg = output.toolCalls.length > 0
                 ? { role: 'assistant', content: output.content ?? '', toolCalls: output.toolCalls }
@@ -585,8 +823,40 @@ class AidenAgent {
             }
             // ── Dispatch tools sequentially ──────────────────────────────────
             const turnToolMessages = [];
+            // v4.1.6 spike (TCE) — set when TurnState surfaces a tool_loop
+            // mid-batch. The agent stops dispatching remaining calls in the
+            // batch and breaks out of the outer iteration loop cleanly.
+            let surfaceDecision = null;
+            // v4.2 Phase 4 — set when TurnState's recovery controller asks
+            // for a rollback. The agent loop truncates messages + restores
+            // TurnState internals + pushes a corrective system message,
+            // then continues the outer iteration loop from a clean baseline.
+            let rollbackDecision = null;
             for (const call of output.toolCalls) {
+                // v4.6 prep — pre-tool-call cooperative-cancellation check.
+                // If the caller aborted between the model emitting tool calls
+                // and us dispatching them, skip the remaining calls in this
+                // batch. We set finishReason here; the outer-while break is
+                // handled after the for-of exits.
+                if (runOptions.signal?.aborted) {
+                    finishReason = 'interrupted';
+                    finalContent = '';
+                    break;
+                }
                 this.onToolCall?.(call, 'before');
+                // v4.2 Phase 4 — mark any active checkpoints as containing a
+                // mutating call BEFORE dispatch. Done pre-dispatch (not post)
+                // so that even if the tool throws / errors / produces a
+                // partial side effect, the mutation flag is set — rollback
+                // safety errs on the side of "this iteration mutated state".
+                // The mutability resolver is wired from the CLI's tool
+                // registry (`resolveMutates`); unknown tools return undefined,
+                // which we treat as non-mutating (leave the flag alone).
+                // Plugin authors should declare `mutates` honestly on their
+                // tool handlers — this is the structural enforcement point.
+                if (turnState.isEnabled() && this.resolveMutates?.(call.name) === true) {
+                    turnState.markMutationOnLiveCheckpoint(call.name);
+                }
                 let result;
                 try {
                     result = await this.toolExecutor(call);
@@ -600,11 +870,114 @@ class AidenAgent {
                     };
                 }
                 toolCallCount += 1;
+                // v4.2 Phase 1 — verifier classification. Runs only when TCE
+                // is enabled; the registry resolves a per-tool verifier or
+                // falls back to the heuristic default. Synchronous + pure;
+                // no network, no side effects.
+                let verification;
+                let classification = null;
+                if (turnState.isEnabled()) {
+                    try {
+                        verification = verifierRegistry.resolve(call.name)(call.name, call.arguments, result);
+                    }
+                    catch {
+                        // Defensive — a buggy verifier never breaks the agent loop.
+                        verification = undefined;
+                    }
+                    // v4.2 Phase 2 — classify WHY when the verifier said !ok.
+                    // classify(...) returns null for ok results, so happy-path
+                    // calls incur zero classifier work.
+                    if (verification && !verification.ok) {
+                        try {
+                            classification = failureClassifier.classify(verification, call.name, call.arguments, result);
+                        }
+                        catch {
+                            // Defensive — a buggy classifier never breaks the loop.
+                            classification = null;
+                        }
+                        // v4.6 Phase 3b — write-through to the durable failure
+                        // ledger. Best-effort: a null/missing store (test agents
+                        // without a daemon DB wired) silently no-ops. The
+                        // signature builder is pure + cheap.
+                        if (classification) {
+                            try {
+                                const store = (0, recoveryStore_1.getRecoveryStore)();
+                                if (store) {
+                                    const sig = (0, signatureBuilder_1.buildFailureSignature)({
+                                        toolName: call.name,
+                                        category: classification.category,
+                                        args: call.arguments,
+                                    });
+                                    const signatureId = store.recordFailureOccurrence({
+                                        signature: sig.signature,
+                                        toolName: call.name,
+                                        category: classification.category,
+                                        argsHash: sig.argsHash,
+                                    });
+                                    if (signatureId > 0) {
+                                        const existing = turnFailureTracker.get(sig.signature);
+                                        turnFailureTracker.set(sig.signature, {
+                                            signatureId,
+                                            failedAttempts: (existing?.failedAttempts ?? 0) + 1,
+                                        });
+                                    }
+                                }
+                            }
+                            catch {
+                                // Defensive — persistence failure must never break the loop.
+                            }
+                        }
+                    }
+                    else if (verification && verification.ok) {
+                        // v4.6 Phase 3b — failure → success transition detection.
+                        // We don't know the failure CATEGORY for this successful
+                        // call (the verifier said ok, so classify() wasn't run),
+                        // but the per-turn tracker remembers every signature seen
+                        // failing this turn. Walk the tracker; if any entry's
+                        // signature starts with `<call.name>:`, this tool now
+                        // succeeded — record a recovery and drop the entry so
+                        // subsequent successes don't double-count.
+                        try {
+                            const store = (0, recoveryStore_1.getRecoveryStore)();
+                            if (store) {
+                                const matching = [];
+                                for (const sig of turnFailureTracker.keys()) {
+                                    if (sig.startsWith(`${call.name}:`))
+                                        matching.push(sig);
+                                }
+                                for (const sig of matching) {
+                                    const entry = turnFailureTracker.get(sig);
+                                    if (!entry)
+                                        continue;
+                                    store.recordRecovery({
+                                        signatureId: entry.signatureId,
+                                        sessionId: this.sessionId,
+                                        failedAttempts: entry.failedAttempts,
+                                        successfulStrategy: 'in_turn_retry',
+                                        notes: `${call.name} succeeded after ${entry.failedAttempts} prior failure(s) this turn`,
+                                    });
+                                    turnFailureTracker.delete(sig);
+                                }
+                            }
+                        }
+                        catch {
+                            // Defensive — recovery persistence failure must never break the loop.
+                        }
+                    }
+                }
                 toolCallTrace.push({
                     name: call.name,
                     result: result.result,
                     error: result.error,
                     verified: this.resolveVerifiedFlag?.(result),
+                    // v4.2 Phase 1 — verification surfaces alongside the trace
+                    // entry for downstream callers (chatSession, loopTrace,
+                    // future RecoveryReport). Undefined when TCE is off.
+                    verification,
+                    // v4.2 Phase 2 — classification surfaces alongside verification.
+                    // Undefined for verifier-ok calls (classifier skips them) and
+                    // when TCE is off.
+                    classification: classification ?? undefined,
                 });
                 fullTrace.push({ name: call.name, args: call.arguments });
                 // URL ledger ingest — extracts ids from result body for next turn.
@@ -623,6 +996,134 @@ class AidenAgent {
                         ? `[error] ${result.error}`
                         : stringifyToolResult(result.result),
                 });
+                // v4.1.6 spike (TCE) — after the tool result lands in the
+                // message history, consult the recovery controller. Returns
+                // `allow` immediately when TCE disabled (zero overhead).
+                // v4.2 Phase 1 — pass the verifier outcome so TurnState's
+                // consecFailed counter can fast-fail on demonstrably failing
+                // tool calls before the slower signature/name counters fire.
+                // v4.2 Phase 2 — also pass the classification so TurnState
+                // records the WHY for Phase 3's RecoveryReport.
+                const recovery = turnState.recordToolCall(call.name, call.arguments, verification, classification);
+                if (recovery.kind === 'hint' && recovery.hintMessage) {
+                    // Stage 1: append a corrective system message so the model
+                    // sees it on the next provider call. Same pattern as the
+                    // existing skill-enforcement + URL-provenance correctives.
+                    turnToolMessages.push({
+                        role: 'system',
+                        content: recovery.hintMessage,
+                    });
+                }
+                else if (recovery.kind === 'cooldown_with_rollback' && recovery.rollback) {
+                    // v4.2 Phase 4 — controller asks us to roll back. Capture
+                    // the decision; we apply it AFTER the inner dispatch loop
+                    // exits so we don't leave partial turnToolMessages in a
+                    // half-state. Break out of dispatch immediately — no point
+                    // running more tools whose results we're about to drop.
+                    rollbackDecision = recovery;
+                    break;
+                }
+                else if (recovery.kind === 'cooldown' && recovery.cooldownMessage) {
+                    // Stage 2: cooldown has already been recorded internally
+                    // (next iteration's schema-filter step excludes this tool).
+                    // Inject a system message announcing the cooldown so the
+                    // model knows why the tool just disappeared from its menu.
+                    turnToolMessages.push({
+                        role: 'system',
+                        content: recovery.cooldownMessage,
+                    });
+                }
+                else if (recovery.kind === 'surface' && recovery.surfaceCard) {
+                    // Stage 3: structured failure. Stop dispatching the rest of
+                    // the batch — anything else is throwing good budget after
+                    // bad. The outer loop reads `surfaceDecision` below and
+                    // exits cleanly.
+                    surfaceDecision = recovery;
+                    break;
+                }
+            }
+            // v4.6 prep — if the per-tool-call abort check fired inside the
+            // for-of above, finishReason is now 'interrupted'. Break the outer
+            // while immediately so we don't run another provider call. Done
+            // here (post-for-of) rather than inside the for-of because the
+            // inner `break` only exits the inner loop.
+            if (finishReason === 'interrupted') {
+                break;
+            }
+            // v4.2 Phase 4 — apply rollback if the controller asked for it.
+            // Truncate messages to the captured snapshot length, restore
+            // TurnState internals, then push a corrective system message
+            // and continue the OUTER iteration loop. We deliberately drop
+            // any partial `turnToolMessages` collected before the rollback
+            // trigger — those are the noise we're trying to undo.
+            //
+            // Hard-block invariant: TurnState only emits
+            // `cooldown_with_rollback` when the target checkpoint has
+            // `containedMutations === false`, so we never get here for an
+            // iteration that ran a mutating tool. The optional
+            // `rollback.blockedBy` is empty in Phase 4 (kept on the type
+            // for a Phase 5+ soft-rollback variant).
+            if (rollbackDecision && rollbackDecision.rollback) {
+                const { checkpoint, blockedBy } = rollbackDecision.rollback;
+                // Truncate messages array to the captured length. The captured
+                // items are immutable Message references; we keep them as-is
+                // and just shorten the live array.
+                messages.length = checkpoint.messages.length;
+                // Restore TurnState mutable internals (stage / streaks /
+                // cooledDownTools / arrays). The cooled-down tools map is
+                // preserved as it was at checkpoint time — but the controller
+                // already added the looping tool to `cooledDownTools` before
+                // emitting the decision, so we need to RE-apply that cooldown
+                // after restore to honour the cooldown intent.
+                turnState.restoreInternalsFrom(checkpoint);
+                // Re-cool the tool that triggered the rollback so the next
+                // provider call sees the constrained schema.
+                if (rollbackDecision.toolName) {
+                    turnState.reapplyCooldown(rollbackDecision.toolName);
+                }
+                // Inject corrective system message so the model sees what
+                // happened and why the tool just disappeared from its menu.
+                messages.push({
+                    role: 'system',
+                    content: (0, checkpoint_1.buildRollbackMessage)({
+                        iteration: checkpoint.iteration,
+                        toolName: rollbackDecision.toolName,
+                        blockedBy,
+                    }),
+                });
+                // Continue the outer iteration loop from the restored
+                // baseline. The next provider call gets the filtered tool
+                // schema (cooldown applied) and the corrective message.
+                continue;
+            }
+            // v4.1.6 spike (TCE) — terminal surface handling.
+            if (surfaceDecision && surfaceDecision.kind === 'surface') {
+                finishReason = 'tool_loop';
+                // v4.2 Phase 3 — enrich the base surface card with a
+                // structured RecoveryReport. Pure synthesis from TurnState's
+                // diagnostic snapshot + first-user-message goal + duration.
+                // Implicit gating: this branch is only reachable when
+                // TurnState is enabled, so AIDEN_TCE=0 (opt-out) never
+                // builds a report.
+                if (surfaceDecision.surfaceCard) {
+                    const report = (0, recoveryReport_1.buildRecoveryReport)({
+                        snapshot: turnState.getDiagnosticSnapshot(),
+                        goal: (0, recoveryReport_1.extractGoal)(messages),
+                        exitReason: 'tool_loop',
+                        durationMs: Date.now() - turnStartedAt,
+                    });
+                    toolLoopCard = (0, recoveryReport_1.enrichCardWithReport)(surfaceDecision.surfaceCard, report);
+                }
+                else {
+                    toolLoopCard = surfaceDecision.surfaceCard;
+                }
+                // Push the partial tool messages we collected so honesty +
+                // history downstream see the full sequence including the
+                // loop-trigger call. No final assistant message — the
+                // tool_loop card IS the user-facing surface.
+                messages.push(...turnToolMessages);
+                finalContent = '';
+                break;
             }
             // ── Iteration-budget injection on the LAST tool message ──────────
             if (this.iterationBudgetInjection && turnToolMessages.length > 0) {
@@ -635,6 +1136,11 @@ class AidenAgent {
             messages.push(...turnToolMessages);
             // Loop continues — provider gets the tool results next iteration.
         }
+        // v4.6 Phase 1 — clear the per-turn signal exposure before returning.
+        // No-throw guarantee: if any prior code in this loop threw, the next
+        // call's `this._currentSignal = runOptions.signal` at the top will
+        // overwrite the stale value before any tool can read it.
+        this._currentSignal = undefined;
         return {
             finalContent,
             messages,
@@ -645,6 +1151,7 @@ class AidenAgent {
             totalUsage,
             toolCallTrace,
             fullTrace,
+            toolLoopCard,
         };
     }
     /**
@@ -669,7 +1176,9 @@ class AidenAgent {
         }
         catch { /* defensive */ }
         if (!wantStream) {
-            return this.provider.call({ messages, tools });
+            // v4.6 prep — forward the abort signal into the provider call so
+            // an in-flight HTTP request can be cancelled mid-flight.
+            return this.provider.call({ messages, tools, signal: runOptions.signal });
         }
         let firstDeltaFired = false;
         let finalOutput = null;
@@ -677,6 +1186,9 @@ class AidenAgent {
             messages,
             tools,
             stream: true,
+            // v4.6 prep — also forward to streaming adapters; mid-stream
+            // aborts cancel the underlying SSE read via the same signal.
+            signal: runOptions.signal,
         });
         for await (const evt of stream) {
             if (evt.type === 'delta') {
@@ -703,6 +1215,16 @@ class AidenAgent {
             }
         }
         if (!finalOutput) {
+            // v4.6 prep — if the stream consumer exited without a `done`
+            // event because the signal was aborted mid-stream, surface a
+            // synthetic AbortError so the outer catch routes it as
+            // 'interrupted' rather than the misleading "closed without done"
+            // generic error.
+            if (runOptions.signal?.aborted) {
+                const abortErr = new Error('Streaming provider aborted before done event');
+                abortErr.name = 'AbortError';
+                throw abortErr;
+            }
             throw new Error('Streaming provider closed without a done event');
         }
         return finalOutput;