agent-nuvira 3.3.0 → 3.3.3

package/dist/tools/tool-loop.js

@@ -16,14 +16,59 @@
  *   blocks after its response text (contract in TOOL_CONTRACT_JSON).
  */
 import { getTool, toolJsonSchemas } from './registry.js';
-import { detectPermissionSeeking, replyAsksTheReader, requestAuthorizesWrites, stripTrailingPermissionSeek, } from '../learning/autonomy-policy.js';
+import { detectPermissionSeeking, isAffirmativeReply, replyAsksTheReader, requestAuthorizesWrites, stripTrailingPermissionSeek, } from '../learning/autonomy-policy.js';
+import { envelopeFromPlan, envelopeFromRequest, getEnvelope, grantEnvelope, isEnvelopeKey, } from '../learning/intent-envelope.js';
+import { detectProcessComplaint, isTraceKey, repeatNudge, runTraceFor, RunTrace, } from '../learning/run-trace.js';
 import { wantsAuthoredArtifact } from '../learning/deliverable-class.js';
 import { normalizeFollowups } from './followup-utils.js';
-import { assessEditActivity, detectUnverifiedEditClaim, isVerificationTool, VERIFICATION_NUDGE, AUTHORIZED_WORK_NUDGE, deliverableNudge, } from './edit-verification.js';
+import { assessEditActivity, detectUnverifiedEditClaim, isVerificationTool, verificationNudgeFor, THINK_ONLY_ESCALATION, AUTHORIZED_WORK_NUDGE, deliverableNudge, } from './edit-verification.js';
 import { effectiveToolJsonSchemas, coreToolJsonSchemas, isToolEnabled, toolsetForTool } from './toolsets.js';
+import { deliverablesNamedIn, recordStepHandoff } from '../agents/step-handoff.js';
+/**
+ * Tools that MUTATE the workspace. A refusal of one of these is the only
+ * refusal that leaves work undone — a declined `read_file` costs a step, a
+ * declined `write_file` means the deliverable was never produced.
+ */
+const MUTATING_TOOL_NAMES = new Set([
+    'write_file',
+    'edit_file',
+    'propose_change',
+    'run_terminal',
+    'run_cli',
+]);
+/** The path a mutating call was aimed at, when it named one. */
+function mutatedPathOf(args) {
+    const a = args;
+    const p = a?.path ?? a?.file_path ?? a?.file;
+    return typeof p === 'string' && p.trim() ? p.trim() : undefined;
+}
+/**
+ * The ask this turn is answering — the text a hand-off is keyed against.
+ * `authorizationRequest` is the loop's own record of the last user message;
+ * the thread scan is the fallback for callers that do not set it (tests, direct
+ * invocations). Injected blocks (`[Project context]`, the route feed) are
+ * skipped: they are the loop's own additions, not the user's words.
+ */
+function currentAsk(opts) {
+    const recorded = opts.context?.authorizationRequest?.trim();
+    if (recorded)
+        return recorded.slice(0, 600);
+    const messages = opts.messages ?? [];
+    for (let i = messages.length - 1; i >= 0; i -= 1) {
+        const m = messages[i];
+        if (m.role !== 'user')
+            continue;
+        const text = (m.content ?? '').trim();
+        if (!text || text.startsWith('['))
+            continue;
+        return text.slice(0, 600);
+    }
+    return '';
+}
 import { appendToolArtifact } from './artifact-append.js';
+import { ROUTE_FEED_MARKER, isUnresolvedModel, routeFeedFingerprint, routeFeedText } from './loop-route-feed.js';
 import { logger } from '../utils/logger.js';
-import { toUserFacingGenerationError } from '../inference/tool-call-utils.js';
+import { toUserFacingGenerationError, TEXTUAL_TOOL_CALL_HINT, isTextualFollowupsPayload, followupEntriesFromPayload, stripTrailingFollowupsHeader, } from '../inference/tool-call-utils.js';
 // ─── P3c — tool-fallback hints (switch tools when one fails) ────────────────
 // The ask: *"if one tool fails you switch to another and explore parallel
 // ways"* (round-2 row 25). Today the raw `Error: …` text is fed back and a
@@ -116,7 +161,8 @@ export function isThinkOnlyResponse(content) {
 }
 /**
  * Extract JSON fallback tool calls from model text:
- * `{"tool":"name","arguments":{...}}` blocks, possibly fenced or multiple.
+ * `{"tool":"name","arguments":{...}}` blocks, possibly fenced or multiple —
+ * plus the name-keyed `{"suggest_followups":[…]}` shape models actually write.
  * Uses brace-matching (string-aware) so nested argument objects parse
  * correctly. Returns the cleaned content (blocks stripped) + parsed calls.
  */
@@ -161,11 +207,59 @@ export function extractFallbackToolCalls(content) {
             // Unparseable block — dropped from the answer, no tool call.
         }
     }
+    // ── Pass 2: our tool's ARGUMENTS keyed by our own tool NAME ─────────────
+    //   {"suggest_followups":[{"label":"…","prompt":"…"}, …]}
+    // This is the shape models ACTUALLY hand-write: across 116 stored assistant
+    // turns the canonical `{"tool":"…"}` form appeared ZERO times and this one
+    // 14. Pass 1 could not see it at all, so the block was delivered verbatim to
+    // the reader AND the suggestions were thrown away (no chips, no menu).
+    //
+    // The block is consumed in exactly two cases: it parses to OUR payload (the
+    // shared predicate — the same one the strip uses, so the two can never
+    // disagree), or it does not parse at all (truncated scaffolding is never
+    // prose). A value that parses cleanly to something demonstrably NOT the
+    // contract — `{"suggest_followups": "a note"}` — is left untouched, so a
+    // user's own JSON still survives.
+    const namedAt = /\(?\s*\{\s*"suggest_followups"\s*:/g;
+    let named;
+    while ((named = namedAt.exec(cleaned)) !== null) {
+        const end = findMatchingBrace(cleaned, named.index);
+        if (end === -1) {
+            // Cut off mid-call: everything from the marker on is scaffolding.
+            cleaned = cleaned.slice(0, named.index);
+            strippedAny = true;
+            break;
+        }
+        const block = cleaned.slice(named.index, end + 1);
+        let parsed = null;
+        let unparseable = false;
+        try {
+            parsed = JSON.parse(block);
+        }
+        catch {
+            unparseable = true;
+        }
+        if (!unparseable && !isTextualFollowupsPayload(parsed))
+            continue;
+        cleaned = cleaned.slice(0, named.index) + cleaned.slice(end + 1);
+        namedAt.lastIndex = named.index;
+        strippedAny = true;
+        const entries = followupEntriesFromPayload(parsed);
+        if (entries) {
+            calls.push({
+                id: `call_${calls.length + 1}`,
+                name: 'suggest_followups',
+                arguments: { followups: entries },
+            });
+        }
+    }
     if (!strippedAny)
         return { text: content, calls };
     // Remove empty fenced blocks left behind when a fenced JSON block's BODY was
-    // the tool call (e.g. "```json\n\n```").
-    const text = cleaned.replace(/\n?```[a-z]*\s*\n?\s*```\s*/gi, '\n').trim();
+    // the tool call (e.g. "```json\n\n```"), plus any caption/separator the model
+    // put in FRONT of the block. Without the second step the delivered answer
+    // ends on a dangling `---` — the visible half of the leak this recovers from.
+    const text = stripTrailingFollowupsHeader(cleaned.replace(/\n?```[a-z]*\s*\n?\s*```\s*/gi, '\n')).trim();
     return { text, calls };
 }
 /**
@@ -257,6 +351,16 @@ const MAX_PARALLEL_READS = 4;
 // half-done and resumable in-context. These defaults resume the SAME turn a
 // bounded number of times — the model keeps its thread, completed tool calls
 // are never re-run, and the loop can never spin forever.
+/**
+ * Consecutive REASONING-ONLY steps the loop tolerates before it escalates, and
+ * then one more before it ends the turn.
+ *
+ * Small on purpose. A `<think>`-then-answer model needs a step or two, so the
+ * limit cannot be zero — but unbounded, this path is a spin: two live eval runs
+ * produced 31 reasoning-only steps, one tool call, and a 0% score on a task they
+ * were well able to do (see `THINK_ONLY_ESCALATION`).
+ */
+export const MAX_THINK_CONTINUES = 3;
 /** Default continuations granted per turn when the option is omitted. */
 export const DEFAULT_MAX_CONTINUATIONS = 2;
 /** Default extra steps granted per continuation. */
@@ -296,6 +400,14 @@ async function runToolLoopInner(opts, progress) {
     // G13 — bounded "the request already authorized this" nudges (see
     // detectPermissionSeeking).
     let permissionNudges = 0;
+    // Stage 2 — the repetition nudge's own bound (see the block after the
+    // permission nudge). Separate from `permissionNudges` on purpose: that one
+    // asks the model to PROCEED, this one asks it to stop REPEATING, and the two
+    // fire on independent evidence.
+    let repeatNudges = 0;
+    // Bounded think-only continuation (see THINK_ONLY_ESCALATION). Counts the
+    // consecutive reasoning-only steps so the loop cannot spin on them.
+    let thinkContinues = 0;
     // G13b — bounded "the request asked for a file and none was written" nudges
     // (see wantsAuthoredArtifact).
     let deliverableNudges = 0;
@@ -342,6 +454,45 @@ async function runToolLoopInner(opts, progress) {
     // gate exactly as it was.
     const requestText = lastUserText(opts.messages);
     const authorization = requestAuthorizesWrites(requestText);
+    // ── INTENT ENVELOPE (the durable grant) ──────────────────────────────────
+    // `writesAuthorized` above answers "does the LAST message ask for files?" —
+    // once per turn, and forgotten at the turn boundary. That is why permission
+    // was re-asked for every operation and why an approval given minutes ago was
+    // worth nothing on the next turn. The envelope is the same verdict as a
+    // DURABLE, SCOPED object, keyed to the conversation (the dashboard console
+    // keeps one plan store per session and re-injects it every turn; the CLI keeps
+    // one per ChatCommand), so an approval outlives the turn that granted it.
+    //
+    // Grant order is deliberate: an APPROVED PLAN is the high-trust path (the user
+    // saw the plan and said yes), then a fresh directive request, then whatever is
+    // still live for this conversation.
+    const envelopeKey = isEnvelopeKey(context.planStore) ? context.planStore : undefined;
+    let envelope = getEnvelope(envelopeKey);
+    if (envelopeKey) {
+        const plan = context.planStore?.snapshot?.() ?? null;
+        if (plan && isAffirmativeReply(requestText)) {
+            envelope = envelopeFromPlan(plan.goal);
+            grantEnvelope(envelopeKey, envelope);
+            deps.onEvent?.('   ✅ Plan approved — running it under one grant; no per-step permission.');
+        }
+        else {
+            const fresh = envelopeFromRequest(requestText);
+            if (fresh) {
+                envelope = fresh;
+                grantEnvelope(envelopeKey, fresh);
+            }
+        }
+    }
+    // ── RUN TRACE (the loop's representation of its own behaviour) ────────────
+    // The envelope above answers "what may I do"; the trace answers "what have I
+    // been DOING" — the question nothing in the architecture could answer, which
+    // is why it could not notice its own loop and could not respond to a user
+    // asking about one. Keyed to the conversation like the envelope, with a
+    // per-turn fallback when there is no session handle so repetition WITHIN a
+    // single turn is still caught.
+    const traceKey = isTraceKey(context.planStore) ? context.planStore : undefined;
+    const runTrace = traceKey ? runTraceFor(traceKey) : new RunTrace();
+    progress.runTrace = runTrace;
     const ctx = {
         ...context,
         followups: context.followups || sink,
@@ -351,6 +502,11 @@ async function runToolLoopInner(opts, progress) {
         // ask for a commit? resolve to this CLI command?), and a single boolean
         // computed for a different question cannot answer any of them.
         authorizationRequest: requestText,
+        // The durable grant every gate consults FIRST (see learning/intent-envelope.ts).
+        envelope,
+        // The run's own behaviour, so a gate can refuse to RE-ASK a question the
+        // user already answered (see learning/run-trace.ts).
+        runTrace,
     };
     // Resolve the tool set — stable JSON schemas for every native step
     // (derived from the registry's zod schemas, single source of truth).
@@ -406,6 +562,30 @@ async function runToolLoopInner(opts, progress) {
         return added;
     };
     const thread = [...messages];
+    /** Serving pairs the loop has already told the model about, oldest first. */
+    const routeFeedState = { pairs: [] };
+    // ── Stage 2: answer a question ABOUT the run from the run ────────────────
+    // The live audit's worst moment was the user asking "why are you asking me
+    // this again and again?" and the turn replying with an edit plan — not through
+    // indifference, but because nothing held the fact that it had asked four
+    // times. Handing the trace in makes the honest answer possible; the framing
+    // line keeps it from being mistaken for a plan.
+    if (detectProcessComplaint(requestText)) {
+        deps.onEvent?.('   🪞 The user asked about your own behaviour — answering from the run trace.');
+        traceEvent({
+            kind: 'gate',
+            gate: 'repeat',
+            summary: `the user asked about the agent's own behaviour — trace provided (${runTrace.countAsks()} ask(s), ${runTrace.repeatedAskCount()} repeated)`,
+        });
+        thread.push({
+            role: 'system',
+            content: `${runTrace.selfReport()}\n\n` +
+                'The user is asking about THIS behaviour, not about the code. Answer them directly: ' +
+                'state what you did (how many questions you asked, which one you repeated, and what they ' +
+                'answered), acknowledge the repetition plainly if there was one, and say what you will do ' +
+                'instead. Do not answer a question about your own process with a plan for the work.',
+        });
+    }
     const budgetChars = opts.threadBudgetChars ?? DEFAULT_THREAD_BUDGET_CHARS;
     // P3d — per-turn parallel suggester: after 2+ successful independent gather
     // steps, one advisory delegate suggestion fires (bounded, deterministic).
@@ -449,6 +629,12 @@ async function runToolLoopInner(opts, progress) {
                 deps.onEvent?.(`   ✂️ ${trimmedResult.trimmed} old tool result(s) trimmed to fit the ${Math.round(budgetChars / 1000)}K-char context budget.`);
             }
         }
+        // ── The route feed, re-synced before every call ────────────────────────
+        // Placed here rather than at thread construction because THIS is the last
+        // point before the call: a failover during step N must be visible at step
+        // N+1, and a single up-front line would have the model answering about a
+        // model that has since stopped serving it.
+        syncRouteFeed(thread, opts.servedRoute, routeFeedState);
         let response;
         try {
             response = await deps.callModel(thread, schemas, opts.onToken, opts.signal);
@@ -542,7 +728,7 @@ async function runToolLoopInner(opts, progress) {
         // console, gateway) recovers the calls, and strip the block from the
         // visible answer either way: a raw `{"tool":…}` block must never be the
         // answer. Idempotent with the JSON transport (which already strips it).
-        if (response.toolCalls.length === 0 && response.content.includes('"tool"')) {
+        if (response.toolCalls.length === 0 && TEXTUAL_TOOL_CALL_HINT.test(response.content)) {
             const extracted = extractFallbackToolCalls(response.content);
             if (extracted.text !== response.content) {
                 response.content = extracted.text;
@@ -574,12 +760,63 @@ async function runToolLoopInner(opts, progress) {
             if (deps.isThinkOnly ? deps.isThinkOnly(response.content) : isThinkOnlyResponse(response.content)) {
                 // Feed an empty assistant step so the model continues in-context.
                 thread.push({ role: 'assistant', content: response.content });
-                deps.onEvent?.('   🧠 model reasoning… (continuing)');
+                thinkContinues += 1;
+                // AN EMPTY RESPONSE IS A FAILURE, NOT REASONING. `isThinkOnlyResponse('')`
+                // returns true, so a provider returning nothing (the loop arm falls over
+                // to `local/gpt-oss:120b-cloud`, which reliably returns length 0) was
+                // reported as "model reasoning… (continuing)" — the system's own evidence
+                // saying the agent was thinking when it was being handed nothing. That
+                // is the exact class of defect this work exists to remove, so the two
+                // cases are named apart even though they are bounded together.
+                const emptyResponse = response.content.trim().length === 0;
+                // BOUNDED (see THINK_ONLY_ESCALATION). Continuing on reasoning is right
+                // for a `<think>`-then-answer model and catastrophic without a limit:
+                // two live eval runs produced 31 reasoning-only steps, one tool call and
+                // a 0% score, printing "model reasoning… (continuing)" the whole way.
+                if (thinkContinues <= MAX_THINK_CONTINUES) {
+                    deps.onEvent?.(emptyResponse
+                        ? `   ⚠️ the provider returned an EMPTY response (${thinkContinues}/${MAX_THINK_CONTINUES}) — retrying the step.`
+                        : `   🧠 model reasoning… (continuing ${thinkContinues}/${MAX_THINK_CONTINUES})`);
+                    traceEvent({
+                        kind: 'decision',
+                        summary: emptyResponse
+                            ? 'the provider returned an empty response — no answer text and no tool call; the step was retried'
+                            : 'the model replied with its own reasoning instead of an answer — the step continued',
+                    });
+                    continue;
+                }
+                if (thinkContinues === MAX_THINK_CONTINUES + 1) {
+                    // One escalation: it has no answer yet, so tell it to act or answer.
+                    stepLimit += 1;
+                    deps.onEvent?.(emptyResponse
+                        ? '   ⚠️ The provider keeps returning empty responses — asking for one real step.'
+                        : '   🧠 Reasoning only, repeatedly — telling the model to act or answer now.');
+                    traceEvent({
+                        kind: 'gate',
+                        gate: 'repeat',
+                        summary: emptyResponse
+                            ? `the provider returned an empty response ${thinkContinues} times — one bounded escalation for a real step`
+                            : `the model produced reasoning-only output ${thinkContinues} times with no tool call and no answer — ` +
+                                'one bounded escalation to act or answer',
+                    });
+                    thread.push({ role: 'user', content: THINK_ONLY_ESCALATION });
+                    continue;
+                }
+                // Still spinning after the escalation: END the turn rather than burn the
+                // rest of the budget. `bounded` is set so every surface reads this as
+                // "stopped before finishing", never as a completed answer.
+                bounded = true;
+                deps.onEvent?.(emptyResponse
+                    ? '   ⚠️ Empty responses kept coming — ending the turn instead of spinning. This is a PROVIDER failure, not the agent thinking.'
+                    : '   🧠 Reasoning-only output kept repeating — ending the turn instead of spinning.');
                 traceEvent({
-                    kind: 'decision',
-                    summary: 'the model replied with its own reasoning instead of an answer — the step continued',
+                    kind: 'gate',
+                    gate: 'repeat',
+                    summary: emptyResponse
+                        ? `the provider returned ${thinkContinues} consecutive empty responses — the turn ended; this is a transport failure, not agent stuckness`
+                        : `reasoning-only output repeated ${thinkContinues} times after an escalation — the turn ended to avoid an unbounded spin`,
                 });
-                continue;
+                break;
             }
             // ── Dangling-promise nudge (bounded, once) ──────────────────────────
             // The model closed the turn announcing what it is ABOUT to do ("I will
@@ -654,6 +891,39 @@ async function runToolLoopInner(opts, progress) {
                 thread.push({ role: 'user', content: AUTHORIZED_WORK_NUDGE });
                 continue;
             }
+            // ── Stage 2 — REPETITION nudge (bounded, once) ───────────────────────
+            // The permission nudge above fires only when the request AUTHORIZED the
+            // work, and it asks the model to PROCEED. A repeated question is a defect
+            // on its own terms: the user already answered it, whatever their latest
+            // message authorized — which is precisely the case a live turn fell
+            // through, because the complaint about repeated questions was itself the
+            // message that failed to authorize. This nudge therefore does NOT depend
+            // on authorization, and deliberately does NOT say "proceed" (unsafe when
+            // the answer was no) — it says the answer is in hand, so act on it or say
+            // what blocks you. The evidence is the RUN TRACE, not the current text.
+            if (repeatNudges < 1 &&
+                schemas.length > 0 &&
+                detectPermissionSeeking(response.content.length >= lastContent.length ? response.content : lastContent) &&
+                runTrace.priorAskMatches(response.content.length >= lastContent.length ? response.content : lastContent).length > 0) {
+                const closing = response.content.length >= lastContent.length ? response.content : lastContent;
+                repeatNudges += 1;
+                stepLimit += 1;
+                deps.onEvent?.('   🔁 The turn asked a question the user has already answered — telling the model to act on the answer.');
+                traceEvent({
+                    kind: 'gate',
+                    gate: 'repeat',
+                    summary: 'the turn repeated a question already asked and answered in this conversation — one bounded nudge to use the answer',
+                });
+                if (progress.successfulToolCalls.length === 0) {
+                    lastContent = '';
+                }
+                else {
+                    lastContent = stripTrailingPermissionSeek(closing);
+                }
+                thread.push({ role: 'assistant', content: response.content });
+                thread.push({ role: 'user', content: repeatNudge(closing, runTrace.priorAnswer(closing)) });
+                continue;
+            }
             // S1 (both exits): the MOST SUBSTANTIVE content seen wins here too —
             // a short closing step ("Sent it to her! ✅") with no tool calls must
             // not clobber the deliverable (poem/essay) the model composed in an
@@ -700,7 +970,14 @@ async function runToolLoopInner(opts, progress) {
                     summary: 'the turn mutated the workspace and nothing observed the result — one bounded nudge to verify',
                 });
                 thread.push({ role: 'assistant', content: response.content });
-                thread.push({ role: 'user', content: VERIFICATION_NUDGE });
+                // Stage 3 — name THIS project's strongest check instead of describing a
+                // preference order. A live turn reached for `node -c` because the nudge
+                // left the choice to the model; `verificationNudgeFor` reads the
+                // workspace and asks for the real command, so there is nothing to guess.
+                thread.push({
+                    role: 'user',
+                    content: verificationNudgeFor(ctx.cwd ?? process.cwd(), progress.mutatedPaths),
+                });
                 continue;
             }
             return {
@@ -902,13 +1179,59 @@ async function runToolLoopInner(opts, progress) {
                 if (call.name === 'edit_file' || call.name === 'write_file') {
                     const a = call.arguments;
                     const p = a?.path ?? a?.file_path ?? a?.file;
-                    if (typeof p === 'string' && p)
+                    if (typeof p === 'string' && p) {
                         progress.mutatedPaths.push(p);
+                        // Stage 2 — the run's own record of what it CHANGED, so a self-report
+                        // can answer "what have you been doing" from data rather than from a
+                        // re-read of the transcript.
+                        runTrace.recordMutation(call.name, p);
+                    }
                 }
                 else if (isVerificationTool(call.name)) {
                     progress.verificationEvidence.push({ tool: call.name, args: call.arguments, result: rawResult });
                 }
             }
+            else if (refusal !== null || rawResult.startsWith('Error:')) {
+                // Stage 2 — the other half of noticing a loop: the SAME refusal, twice.
+                // The run records it with its reason, so a later step (or a self-report)
+                // can see "blocked twice, identically" instead of rediscovering it — and
+                // so the repetition gate has a refusal signal as well as an ask signal.
+                runTrace.recordRefusal(call.name, refusal?.gate ?? 'error', rawResult);
+                // ── DURABLE HAND-OFF ────────────────────────────────────────────────
+                // A refused MUTATION is the one failure that must outlive the turn.
+                // The live NVDA-addon failure is exactly this: `write_file` was refused
+                // on every attempt because the target was outside the workspace, and
+                // each of the 18 following attempts rediscovered it from zero — same
+                // plan, same refusal, same empty package. Recording it here means the
+                // next candidate, the next turn and the next RUN are told which path
+                // could not be written and WHY, so they change approach instead of
+                // repeating the identical call (see step-handoff.ts).
+                //
+                // Best-effort: a hand-off write must never break the loop.
+                if (refusal !== null && MUTATING_TOOL_NAMES.has(call.name)) {
+                    try {
+                        const ask = currentAsk(opts);
+                        const aimedAt = mutatedPathOf(call.arguments);
+                        // Key on the deliverable the ASK names when there is one, so the
+                        // same work asked for in different words resumes the same hand-off.
+                        const named = deliverablesNamedIn(ask);
+                        recordStepHandoff({
+                            projectPath: opts.context?.cwd || process.cwd(),
+                            goal: ask,
+                            stepDescription: aimedAt
+                                ? `${call.name} → ${aimedAt} (refused: ${refusal.gate ?? 'gate'})`
+                                : `${call.name} (refused: ${refusal.gate ?? 'gate'})`,
+                            declared: named.length > 0 ? named : aimedAt ? [aimedAt] : [],
+                            route: 'loop',
+                            kind: 'refused',
+                            reason: `${refusal.summary}${aimedAt ? ` — path: ${aimedAt}` : ''}`,
+                        });
+                    }
+                    catch {
+                        // Best-effort — a hand-off write must never break the loop.
+                    }
+                }
+            }
             let resultText = executed[i];
             // P3c — on error/denial, append the deterministic fallback hint for
             // this tool (advisory — the model still decides; never on success).
@@ -1019,7 +1342,14 @@ async function runToolLoopInner(opts, progress) {
                     summary: 'the turn mutated the workspace and nothing observed the result — one bounded nudge to verify',
                 });
                 thread.push({ role: 'assistant', content: response.content });
-                thread.push({ role: 'user', content: VERIFICATION_NUDGE });
+                // Stage 3 — name THIS project's strongest check instead of describing a
+                // preference order. A live turn reached for `node -c` because the nudge
+                // left the choice to the model; `verificationNudgeFor` reads the
+                // workspace and asks for the real command, so there is nothing to guess.
+                thread.push({
+                    role: 'user',
+                    content: verificationNudgeFor(ctx.cwd ?? process.cwd(), progress.mutatedPaths),
+                });
                 continue;
             }
             // G13b — DELIVERABLE GATE (concluding path). AFTER the verification gate
@@ -1199,6 +1529,69 @@ export function detectUnfulfilledIntentPromise(content) {
  * honest-answer flags so every surface (CLI, dashboard, gateway, trace) can
  * distinguish "generated a reply" from "actually performed the action".
  */
+/**
+ * Keep ONE route frame in the thread, current with what is serving the turn.
+ *
+ * Insert/replace is deliberate: appending a frame per step would pile up stale
+ * route claims the model can quote back ("I am gemini-2.5-flash" — from step 1,
+ * after a failover), and rewriting unconditionally would churn the thread (and
+ * the thread budget) on every step for no change in content.
+ *
+ * A caller with no route supplies nothing; a caller whose route resolves to the
+ * same fact as last step gets no write.
+ */
+function syncRouteFeed(thread, read, observed) {
+    if (!read)
+        return;
+    let route = null;
+    try {
+        route = read();
+    }
+    catch {
+        // A route read must never break the turn; an unknown route is a fact too.
+        return;
+    }
+    if (!route)
+        return;
+    // The loop OWNS the failover history, because the loop is the only thing that
+    // sees the sequence of routes it told the model about. Requiring each caller
+    // to track it means every future caller can silently forget, and a model told
+    // only the current pair describes the whole turn as having been run by it —
+    // the same fabricated answer, one layer down.
+    const currentPair = isUnresolvedModel(route.model) ? '' : `${route.providerType}/${route.model}`;
+    const previous = [...(route.previous ?? [])];
+    for (const pair of observed.pairs) {
+        if (pair !== currentPair && !previous.includes(pair))
+            previous.push(pair);
+    }
+    const rendered = previous.length > 0 ? { ...route, previous } : route;
+    const fingerprint = routeFeedFingerprint(rendered);
+    const index = thread.findIndex((m) => m.role === 'system' && typeof m.content === 'string' && m.content.startsWith(ROUTE_FEED_MARKER));
+    if (currentPair && !observed.pairs.includes(currentPair))
+        observed.pairs.push(currentPair);
+    if (index === -1) {
+        const frame = { role: 'system', content: routeFeedText(rendered) };
+        // Immediately after the leading system prompt when there is one — the route
+        // belongs with the run's own framing, not buried under tool output.
+        const insertAt = thread.length > 0 && thread[0].role === 'system' ? 1 : 0;
+        thread.splice(insertAt, 0, frame);
+        routeFeedFingerprints.set(frame, fingerprint);
+        return;
+    }
+    const existing = thread[index];
+    if (routeFeedFingerprints.get(existing) === fingerprint)
+        return;
+    const updated = { role: 'system', content: routeFeedText(rendered) };
+    thread[index] = updated;
+    routeFeedFingerprints.delete(existing);
+    routeFeedFingerprints.set(updated, fingerprint);
+}
+/**
+ * Fingerprint per frame object, so a thread that was trimmed and re-built does
+ * not re-write identical content. A WeakMap: a frame the loop drops is garbage
+ * the moment nothing references it.
+ */
+const routeFeedFingerprints = new WeakMap();
 export async function runToolLoop(opts) {
     const progress = {
         successfulToolCalls: [],
@@ -1210,6 +1603,8 @@ export async function runToolLoop(opts) {
     if (!result.cancelled && !result.generationFailed) {
         result.successfulToolCalls = [...progress.successfulToolCalls];
         result.deliveryConfirmed = progress.deliveryConfirmed;
+        // Stage 2 — the turn's own behaviour, as counts (see learning/run-trace.ts).
+        result.runTrace = progress.runTrace?.snapshot();
         // Judge the "I have sent it" claim against what actually DELIVERED, not
         // against the attempted tool list — a failed gateway_send must not silence
         // the honesty correction.