agent-nuvira 3.4.0 → 3.5.1

package/dist/cli/chat.js

@@ -24,7 +24,7 @@ import { beginIsolation, endIsolation, resolveIsolationRequest, worktreeNotice,
 import { closeResume, openResume, resolveResumeRequest, } from '../learning/step-checkpoint.js';
 import { applyActiveModel } from './model.js';
 import { capabilityReasoningEffort, isMaxCapability } from '../config/capability-mode.js';
-import { getProviderFallback, classifyFallbackError, isRetryableError, isTransientForRetry, recordRegistrySuccess, recordRegistryFailure } from '../learning/provider-fallback.js';
+import { getProviderFallback, classifyFallbackError, isRetryableError, isTransientForRetry, isHarnessFault, recordRegistrySuccess, recordRegistryFailure } from '../learning/provider-fallback.js';
 import { recordActionFailure, } from '../learning/failure-bookkeeping.js';
 import { getRouterBandit } from '../learning/router-bandit.js';
 import { UnusableModelResponseError } from '../learning/response-usability.js';
@@ -62,7 +62,9 @@ import { assertAgenticRoute, setWeakModelConsent, resolveWeakModelPolicy, weakRo
 import { resolvePromptBudget, measurePromptBudget, formatPromptBudgetBreakdown } from '../learning/prompt-budget.js';
 import { buildTurnReport, formatTurnReport } from '../learning/turn-report.js';
 import { turnOutcomeObservation } from '../learning/outcome-observation.js';
-import { resolveAdapterDefault, hasCredentials } from '../learning/model-selection.js';
+import { resolveAdapterDefault, hasCredentials, preferredModelsFor, rankAvailableProviders } from '../learning/model-selection.js';
+import { sameClassFallback, capabilityClassOf } from '../learning/model-capability.js';
+import { planBlipPatience, EMPTY_PATIENCE_MS, TRANSIENT_BLIP_DELAYS_MS, } from '../learning/retry-patience.js';
 import { buildLoopProjectContext } from '../tools/loop-project-context.js';
 import { sweepTransientFailures, collectionRevivalStore } from '../learning/provider-revival.js';
 import { analyzeComplexity } from '../learning/hybrid-router.js';
@@ -260,12 +262,261 @@ export async function runDeveloperMode(goal, configManager, options) {
  * caller, never to skip the loop).
  */
 /**
- * Backoff schedule for a SAME-provider retry on a transient failure. Two extra
- * attempts, deliberately short: a capacity spike at a shared endpoint clears in
- * seconds, and the user is waiting in the foreground. Long/looping retries belong
- * to the background runners, not the interactive turn.
+ * Backoff schedule for a SAME-provider retry on a TRANSIENT failure
+ * (server/network/timeout): dense early, sparse late — attempts at ≈1s, 3s, 7s,
+ * 15s, 30s, 60s.
+ *
+ * WHY THE SHAPE CHANGED (it was `[5s, 10s, 20s, 30s]`, front-loaded). A fixed
+ * front-loaded schedule is wrong in BOTH directions at once:
+ *
+ *   - A TWO-SECOND BLINK WAS NOT CAUGHT. A cloud endpoint routinely returns 200,
+ *     then a couple of empty/5xx answers for a handful of seconds, then serves
+ *     normally again (measured repeatedly on `deepseek`). The first retry sat at
+ *     t=5s, so the wait outlived the blink AND, because exhausting this schedule
+ *     is what starts the failover walk, a healthy strong model was declared dead
+ *     and the turn folded onto a weaker one. A retry at t≈1s catches the blink
+ *     outright.
+ *   - THE TOTAL STILL HAS TO RIDE OUT A REAL SPIKE. A capacity spike, an
+ *     upstream batch job or a rolling restart lasts tens of seconds, so the late
+ *     delays stay sparse and the total stays ~60s. Nothing that used to be
+ *     ridden out is given up on; the wait is just spent where the evidence is.
+ *
+ * THIS IS THE NO-EVIDENCE DEFAULT, NOT THE WHOLE POLICY. The schedule used per
+ * call comes from {@link planBlipPatience} — which also decides whether walking
+ * away is a remedy at all, from the pair's alternatives, its track record, and
+ * whether it already failed an earlier step of this turn. This constant is what
+ * every caller with no evidence gets, and it is what the `models`/parity
+ * harnesses see.
+ *
+ * Every sleep is CANCELLABLE (see `abortableSleep`), so an Esc during a 30s wait
+ * stops the turn immediately instead of after it.
+ */
+export const TRANSIENT_RETRY_DELAYS_MS = TRANSIENT_BLIP_DELAYS_MS;
+/**
+ * Resolve the backoff schedule actually used (env override → default).
+ *
+ * `NUVIRA_TRANSIENT_RETRY_DELAYS_MS` takes a comma-separated list of ms
+ * (`"5000,10000"`), so how long a foreground turn waits on a flapping provider
+ * is a CONFIGURATION decision rather than a property of the build — the same
+ * rule the warmup sweep's bounds follow. A headless gateway, a CI contract
+ * test or a user on a metered connection can dial it down (or to `0`) without a
+ * source edit and a rebuild; nonsense is ignored and the default stands.
+ *
+ * Read PER CALL, not captured at import, so a test observes the value in force
+ * at that moment.
+ */
+export function transientRetryDelaysMs(env = process.env) {
+    const raw = env.NUVIRA_TRANSIENT_RETRY_DELAYS_MS;
+    if (raw === undefined || raw.trim() === '')
+        return TRANSIENT_RETRY_DELAYS_MS;
+    const parsed = raw
+        .split(',')
+        .map((part) => Number(part.trim()))
+        .filter((n) => Number.isFinite(n) && n >= 0);
+    return parsed.length > 0 ? parsed : TRANSIENT_RETRY_DELAYS_MS;
+}
+/**
+ * Is the transient schedule overridden by the environment right now?
+ *
+ * The dial is authoritative when set (it is an explicit configuration decision,
+ * and it is what makes attempt COUNTS deterministic in the parity/E2E
+ * contracts), so callers ask this BEFORE substituting an evidence-derived
+ * schedule — otherwise a test would silently get the learned schedule and its
+ * exact call-count assertions would be about a different policy than the one it
+ * dialed.
+ *
+ * A set-but-nonsense value does NOT count as an override: `transientRetryDelaysMs`
+ * ignores it and falls back to the shipped schedule, so the evidence-derived
+ * schedule would be overridden by nothing.
+ */
+export function transientRetryScheduleOverridden(env = process.env) {
+    const raw = env.NUVIRA_TRANSIENT_RETRY_DELAYS_MS;
+    if (raw === undefined || raw.trim() === '')
+        return false;
+    return raw.split(',').some((part) => {
+        const n = Number(part.trim());
+        return Number.isFinite(n) && n >= 0;
+    });
+}
+/**
+ * Bounded extra same-model patience for an `empty-response` — the "final verse"
+ * case, granted ONLY to a pair that has already delivered real work this turn.
+ *
+ * THE TWO CASES LOOK IDENTICAL TO THE CLASSIFIER AND MUST NOT BE TREATED ALIKE:
+ *
+ *   - a BROKEN pair answers nothing, forever. The codebase already measured the
+ *     cost of re-asking it: "5 empty responses on one model" in one turn, no
+ *     failover, which is why `empty-response` was removed from
+ *     `TRANSIENT_RETRY_TYPES` and why the handoff/walk is what remedies it.
+ *   - a pair that just finished four GOOD steps and then returns nothing is
+ *     having a blip at the END of real work — the expensive case, because the
+ *     turn already paid for the context, the tool results and the edits, and a
+ *     single empty reply would otherwise discard all of it.
+ *
+ * The discriminator is EVIDENCE, not a heuristic on the reply. Two halves, both
+ * required to be absent before we give up on a pair: a completed tool call in
+ * THIS turn (`threadHasDeliveredWork`), and the registry's own record for the
+ * pair — verified by TELEMETRY or a spot-check, with a low error rate
+ * (`hasProvenTrackRecord` in `retry-patience.ts`, which is where the rule now
+ * lives so it cannot drift). So a pair that answers nothing from the start with
+ * no track record still fails over immediately, a proven pair's FIRST empty
+ * reply gets these two short waits, and a proven pair whose only alternatives
+ * would DE-ESCALATE gets the longer
+ * `EMPTY_PATIENCE_WAIT_BEATS_FOLDING_MS` schedule rather than folding down a
+ * capability band. Bounded by design, and always finite.
+ *
+ * The value is re-exported from `retry-patience.ts`: ONE table for the whole
+ * blip policy, so the CLI and any other caller cannot drift apart.
+ */
+export const EMPTY_RESPONSE_PATIENCE_MS = EMPTY_PATIENCE_MS;
+/**
+ * Sleep that a CANCELLED turn interrupts.
+ *
+ * The old retry slept with a bare `setTimeout`, so an Esc during a backoff was
+ * only honored when the timer happened to fire — with a 30s step in the
+ * schedule that is a 30s delay before the turn admits it was cancelled. This
+ * resolves the moment the signal aborts, so the caller's abort checks see the
+ * cancellation immediately.
+ */
+function abortableSleep(ms, signal) {
+    if (!signal)
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    if (signal.aborted)
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        const finish = () => {
+            clearTimeout(timer);
+            signal.removeEventListener('abort', finish);
+            resolve();
+        };
+        const timer = setTimeout(finish, ms);
+        signal.addEventListener('abort', finish, { once: true });
+    });
+}
+/**
+ * Has this turn already produced real, OBSERVED work on this thread?
+ *
+ * Structural, not a counter: an assistant step that ASKED for a tool and the
+ * tool result that came back for it. That is the cheapest honest evidence that
+ * the pair under us has already served this turn — a pair that has not is given
+ * no `empty-response` patience at all, so the "ask a broken model five times"
+ * loop stays impossible.
+ */
+export function threadHasDeliveredWork(thread) {
+    const asked = thread.some((m) => m.role === 'assistant' && (m.toolCalls?.length ?? 0) > 0);
+    const answered = thread.some((m) => m.role === 'tool');
+    return asked && answered;
+}
+/**
+ * The pairs this surface could actually switch to right now, best-first, for
+ * {@link planBlipPatience}.
+ *
+ * DELIBERATELY NARROW. Only providers with at least one registry-VERIFIED model
+ * count, and the model offered is the one that provider would actually lead
+ * with (`preferredModelsFor`'s health order). A provider we cannot name a model
+ * for is not evidence of a same-band alternative — treating a cold-start or
+ * unverified provider as one would SHORTEN patience on the strength of a guess,
+ * and the whole point of the policy is that waiting is better than an
+ * unproven downgrade. Unknown therefore reads as "no known alternative", the
+ * conservative direction.
+ *
+ * Pure read, best-effort: any failure to rank means the same thing (no known
+ * alternative), never a thrown turn.
  */
-export const TRANSIENT_RETRY_DELAYS_MS = [1_000, 3_000];
+function failoverAlternatives(configManager, excludeProvider) {
+    const out = [];
+    try {
+        for (const ranked of rankAvailableProviders(configManager)) {
+            if (ranked.provider === excludeProvider)
+                continue;
+            const model = ranked.verifiedModels[0];
+            if (!model)
+                continue;
+            out.push({ provider: ranked.provider, model });
+        }
+    }
+    catch {
+        // Best-effort — see the note above: unknown is the conservative reading.
+    }
+    return out;
+}
+/**
+ * Registry evidence for one pair, shaped for {@link planBlipPatience}.
+ * `undefined` when nothing is recorded — an untracked pair earns no patience.
+ *
+ * The `default` sentinel is not a model id, so it has no evidence by definition
+ * (the same reasoning that keeps it out of `preferredModelsFor`).
+ */
+function registryPatienceEvidence(provider, model) {
+    if (!model || model === 'default')
+        return undefined;
+    try {
+        const entry = getModelRegistry().getEntry(provider, model);
+        if (!entry)
+            return undefined;
+        return {
+            verified: entry.status === 'verified',
+            source: entry.source,
+            errorRate: entry.errorRate,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * How long a PINNED + STRICT pair is given to answer before the user is asked
+ * what to do next (ms).
+ *
+ * WHY A WAIT AT ALL, and why two minutes. A pinned+strict turn is an explicit
+ * quality contract: the user would rather wait than be answered by a model they
+ * did not choose. A provider having a slow moment (or an upstream batch job) is
+ * exactly the case that contract covers, so the SAME pair is retried inside this
+ * window before anything else can happen. Two minutes is the bar the user set: it
+ * rides out a bad minute at a shared endpoint, while a genuinely dead provider no
+ * longer holds the turn for the ~5 minutes that prompted the complaint. NOTHING
+ * is routed to another model inside this window.
+ */
+export const PINNED_SAME_PAIR_GRACE_MS = 120_000;
+/**
+ * Backoff between retries of the SAME pinned pair. Summed with the call time,
+ * these reach the {@link PINNED_SAME_PAIR_GRACE_MS} budget.
+ */
+export const PINNED_GRACE_BACKOFF_MS = [5_000, 15_000, 30_000, 45_000];
+/**
+ * Failure kinds a WAIT can plausibly fix.
+ *
+ * A rejected credential, a model the provider does not serve, an over-long prompt
+ * or a request-encoding fault are DEFINITIVE: retrying them for two minutes only
+ * makes the user wait longer for the same answer. A pinned+strict turn refuses
+ * those immediately (the honest strict stop) instead of presenting them as a
+ * delay.
+ */
+const PINNED_WAITABLE_KINDS = new Set(['server', 'network', 'timeout', 'rate-limit', 'unknown']);
+/**
+ * How long the user has to answer the pinned-failure question before the turn
+ * stops honestly (ms).
+ *
+ * Without a bound the turn waits on the question FOREVER: the console's
+ * `askQuestion` promise is deliberately never rejected (worst case the model
+ * proceeds on best judgment), so a client that renders the card and is then
+ * closed — or a headless caller that never answers — would hold the turn (and its
+ * `busy` slot) open indefinitely. Measured live while probing the endpoint: the
+ * HTTP request sat open until it was cancelled by hand. Five minutes is generous
+ * for a person reading the options, and the answer is a choice, not a dependency:
+ * stopping with the pin's own error is the honest outcome once nobody answers.
+ */
+export const PINNED_ANSWER_TIMEOUT_MS = 300_000;
+/**
+ * Message shapes that name a DEFINITIVE model problem — the pair does not exist,
+ * or the request shape is wrong. A wait cannot fix either (see
+ * `pinnedFailureIsWaitable`).
+ *
+ * Deliberately NOT blanket-applied: it is consulted only for a failure the
+ * classifier could not place (`unknown`), so a DNS/network blip whose text happens
+ * to say "not found" still gets its grace window.
+ */
+const PINNED_DEFINITIVE_ERROR_RE = /(?:does not exist|not found|no such model|invalid model|unknown model|unsupported model|but you passed|model_not_found)/i;
 /**
  * Run one provider attempt, retrying transient failures against the SAME
  * provider before giving up.
@@ -279,18 +530,48 @@ export const TRANSIENT_RETRY_DELAYS_MS = [1_000, 3_000];
  *
  * Never retries: non-transient classes (auth, rate-limit, model/harness faults),
  * a cancelled turn, or once the schedule is exhausted.
+ *
+ * `emptyResponseDelaysMs` is the ONE narrowly-scoped exception, and it exists in
+ * this helper rather than in `TRANSIENT_RETRY_TYPES` because retryability here
+ * depends on the TURN, not only on the error class: pass it only when the pair
+ * has a track record this turn (see {@link threadHasDeliveredWork}). Omitted →
+ * an empty response is not retried at all, byte for byte the old behaviour.
+ *
+ * `transientDelaysMs` is the caller's EVIDENCE-DERIVED schedule
+ * ({@link planBlipPatience}) for server/network/timeout failures. Omitted → the
+ * shipped default / env dial (`transientRetryDelaysMs`), which is what a caller
+ * with no evidence (a test, a headless path) gets.
  */
-export async function generateWithTransientRetry(attempt, signal, onRetry) {
-    for (let i = 0;; i += 1) {
+export async function generateWithTransientRetry(attempt, signal, onRetry, opts = {}) {
+    let transientRetries = 0;
+    let emptyRetries = 0;
+    const emptySchedule = opts.emptyResponseDelaysMs ?? [];
+    const transientSchedule = opts.transientDelaysMs ?? transientRetryDelaysMs();
+    for (;;) {
         try {
             return await attempt();
         }
         catch (err) {
-            const canRetry = i < TRANSIENT_RETRY_DELAYS_MS.length && isTransientForRetry(err);
-            if (!canRetry || signal?.aborted)
+            if (signal?.aborted)
+                throw err;
+            // The attempt number a human sees: 1-based, counting every retry so far.
+            const attemptNumber = transientRetries + emptyRetries + 1;
+            let delay;
+            if (isTransientForRetry(err)) {
+                delay = transientRetries < transientSchedule.length
+                    ? transientSchedule[transientRetries++]
+                    : undefined;
+            }
+            else if (classifyFallbackError(err) === 'empty-response' && emptyRetries < emptySchedule.length) {
+                delay = emptySchedule[emptyRetries++];
+            }
+            if (delay === undefined)
+                throw err;
+            onRetry?.(attemptNumber, err);
+            await abortableSleep(delay, signal);
+            // A cancelled turn must not pay for another attempt.
+            if (signal?.aborted)
                 throw err;
-            onRetry?.(i + 1, err);
-            await new Promise((resolve) => setTimeout(resolve, TRANSIENT_RETRY_DELAYS_MS[i]));
         }
     }
 }
@@ -1907,7 +2188,10 @@ export class ChatCommand extends BaseCommand {
                 },
             },
         };
-        const callModel = this.buildToolCallModel(message, session, options, mode, ctxOverrides?.onToken, ctxOverrides?.signal, continuationSoftwareText(message, history) ?? undefined);
+        const callModel = this.buildToolCallModel(message, session, options, mode, ctxOverrides?.onToken, ctxOverrides?.signal, continuationSoftwareText(message, history) ?? undefined, 
+        // PINNED + STRICT: the escalation asks the USER when a pinned model will not
+        // answer (keep trying / switch to a same-class model / name one / go auto).
+        ctxOverrides?.askUser);
         let result;
         // v1.8x audit — CHAT TRACE CAPTURE: every LLM call in a chat turn is now
         // recorded to ~/.nuvira/memory/reasoning-traces.json (source 'chat'), so
@@ -2188,6 +2472,16 @@ export class ChatCommand extends BaseCommand {
             try {
                 const chain = getProviderFallback(this.configManager, this.configManager.getAll().fallback)
                     .getFallbackChain(session.type);
+                /**
+                 * PINNED + AUTO-FALLBACK stays in the PIN'S CAPABILITY CLASS.
+                 *
+                 * A user who pins a strong model and leaves auto-fallback on has said
+                 * "keep me in this class" — they have not agreed to a small/fast model
+                 * because it happens to have the best health score. `sameClassFallback`
+                 * chooses within the class first and reports when it must step down, so
+                 * the handoff can SAY so instead of arriving as a silent downgrade.
+                 */
+                const pinModel = session.model;
                 for (const fbType of chain) {
                     if (fbType === session.type)
                         continue;
@@ -2197,7 +2491,16 @@ export class ChatCommand extends BaseCommand {
                         continue;
                     try {
                         const resolved = resolveProvider(this.configManager, fbType);
-                        const model = getAutoRouter().resolveModel(fbType, 'chat', this.configManager);
+                        const base = getAutoRouter().resolveModel(fbType, 'chat', this.configManager);
+                        const pick = sameClassFallback(pinModel, [
+                            ...(base ? [base] : []),
+                            ...preferredModelsFor(resolved.type),
+                        ]);
+                        const model = pick?.model ?? base;
+                        if (pick?.crossClass) {
+                            logger.warn(`   ⚠️ ${pinModel ?? 'the pinned model'} is not available anywhere; handing over to ` +
+                                `${resolved.type}/${model} (${capabilityClassOf(model)} class — no same-class model was available).`);
+                        }
                         if (install({ type: resolved.type, provider: resolved.provider, model }))
                             return true;
                     }
@@ -2395,6 +2698,10 @@ export class ChatCommand extends BaseCommand {
                         ...(typeof breadth.poolSize === 'number' ? { poolSize: breadth.poolSize } : {}),
                         ...(typeof breadth.poolProviders === 'number' ? { poolProviders: breadth.poolProviders } : {}),
                         task: message,
+                        // The user's PIN, when there was one — so the report's own advice
+                        // respects the quality bar they set instead of inviting a downgrade
+                        // (see ExhaustionInput.pinnedModel).
+                        ...(session.model && session.model !== 'default' ? { pinnedModel: session.model } : {}),
                         // The underlying line is kept as the REASON, so a specific,
                         // actionable cause is never buried by the report.
                         ...(result.generationFailed && result.content.trim() ? { cause: result.content } : {}),
@@ -2758,6 +3065,281 @@ export class ChatCommand extends BaseCommand {
             traceId: chatTraceId,
         });
     }
+    /**
+     * Providers that could TAKE OVER from a pin, split by capability class.
+     *
+     * Only providers with credentials are considered, and each contributes the
+     * model `sameClassFallback` would choose for it — so the "switch to …" offer
+     * is a pair the router would actually serve, never a name invented here.
+     */
+    pinAlternatives(pinModel, excludeProvider) {
+        const sameClass = [];
+        const crossClass = [];
+        let types = [];
+        try {
+            const all = this.configManager.getAll();
+            types = Object.keys(all.providers ?? {});
+        }
+        catch {
+            return { sameClass, crossClass };
+        }
+        for (const providerType of types) {
+            if (providerType === excludeProvider)
+                continue;
+            try {
+                if (!hasCredentials(this.configManager, providerType))
+                    continue;
+                const resolved = resolveProvider(this.configManager, providerType);
+                const base = resolveAdapterDefault(resolved.type, undefined);
+                const pick = sameClassFallback(pinModel, [
+                    ...(base ? [base] : []),
+                    ...preferredModelsFor(resolved.type),
+                ]);
+                if (!pick)
+                    continue;
+                (pick.crossClass ? crossClass : sameClass).push({ provider: resolved.type, model: pick.model });
+            }
+            catch {
+                // Next provider.
+            }
+        }
+        return { sameClass, crossClass };
+    }
+    /**
+     * Read a user-typed choice as `provider/model` (or a bare model id).
+     *
+     * A bare id keeps the PINNED provider — that is what "another model" means when
+     * the user was asked about a pinned turn. A prefixed value is only accepted as a
+     * provider when it RESOLVES to one, so a model id that merely contains a slash
+     * (`openai/gpt-oss-120b`) is not mistaken for a provider name.
+     */
+    parsePinChoice(text, pinnedProvider) {
+        const trimmed = text.trim();
+        if (!trimmed)
+            return null;
+        const sep = trimmed.includes('/') ? '/' : trimmed.includes(':') ? ':' : null;
+        if (sep) {
+            const [head, ...rest] = trimmed.split(sep);
+            const tail = rest.join(sep);
+            if (head && tail) {
+                try {
+                    const resolved = resolveProvider(this.configManager, head);
+                    return { provider: resolved.type, model: tail };
+                }
+                catch {
+                    // Not a provider name — treat the whole value as a model id below.
+                }
+            }
+        }
+        return { provider: pinnedProvider, model: trimmed };
+    }
+    /**
+     * Serve ONE step on a pair the USER named, validated AS A PAIR.
+     *
+     * `resolveRoute` is asked in strict mode, so a pair the provider cannot serve is
+     * REFUSED rather than silently substituted — the same guarantee every other
+     * pinned call gets (issue #9: a model id sent to the wrong provider is the bug
+     * class this covers). Returns null when the pair cannot be used or the call
+     * fails, leaving the honest stop in place rather than switching anyway.
+     */
+    async serveChosenPair(input, providerType, model) {
+        try {
+            const resolved = resolveProvider(this.configManager, providerType);
+            // Validated as a PAIR via `resolveRoute` in strict mode (see above).
+            const route = await resolveRoute({
+                providerType: resolved.type,
+                provider: resolved.provider,
+                model,
+                source: 'chat',
+                strict: true,
+            });
+            const resp = await input.tryGenerate(resolved.provider, resolved.type, route.model);
+            input.session.type = resolved.type;
+            input.session.provider = resolved.provider;
+            input.session.model = route.model;
+            logger.warn(`   ✅ continuing on ${resolved.provider.name} / ${route.model} (your choice).`);
+            return resp;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * PINNED + STRICT and the pin did not answer: wait on the SAME model, then let
+     * the USER decide — never a silent substitution.
+     *
+     * WHY THIS EXISTS. The user pinned a model AND turned strict mode on. That is a
+     * quality contract, and the old behaviour broke it in the one direction they
+     * explicitly forbade: rather than wait, or say what was happening, a failed pin
+     * either dead-ended in "the language model was unavailable" or (non-strict) was
+     * handed to whatever the health ranking liked — including `local/qwen2.5:0.5b`, a
+     * model that cannot call tools at all, so its "answer" was fabricated rather
+     * than merely weaker. Sending that work to a weak model is not a degraded answer;
+     * for an agentic turn it is a wrong one.
+     *
+     * So: the SAME pair is retried inside {@link PINNED_SAME_PAIR_GRACE_MS} first
+     * (nothing is routed anywhere in that window), and if it still does not answer
+     * the user is asked — keep trying, switch to the closest SAME-CLASS model the
+     * agent can find and name, type another model/provider, or release the pin to
+     * auto. The question says outright that nothing has been routed elsewhere.
+     *
+     * Returns a served response when the user's choice works; `null` when the turn
+     * must fail honestly — headless (no one to ask: the strict refusal stands, as
+     * it must, because silently choosing FOR the user is the original defect), or
+     * when the chosen pair could not serve.
+     */
+    async pinnedStrictEscalation(input) {
+        const { session } = input;
+        const pin = `${session.type}/${session.model ?? 'default'}`;
+        const kind = classifyFallbackError(input.err);
+        // A DEFINITIVE failure is not a delay (see PINNED_WAITABLE_KINDS) — and a model
+        // the provider does not serve, or a request-shape fault, is definitive even
+        // though the classifier can only call it `unknown` (measured: a pin to a
+        // nonexistent id spent the whole 2-minute grace window on a 400 that could
+        // never change).
+        if (!PINNED_WAITABLE_KINDS.has(kind))
+            return null;
+        if (kind === 'unknown') {
+            const message = input.err instanceof Error ? input.err.message : String(input.err);
+            if (isHarnessFault(input.err) || PINNED_DEFINITIVE_ERROR_RE.test(message))
+                return null;
+        }
+        const attemptPin = async () => {
+            try {
+                return await input.tryGenerate(session.provider, session.type, session.model);
+            }
+            catch (err) {
+                const k = classifyFallbackError(err);
+                this.recordTurnAttempt({
+                    provider: this.lastAttempt?.provider ?? session.type,
+                    model: this.lastAttempt?.model ?? session.model ?? 'default',
+                    kind: k,
+                    reason: describeFailureKind(k),
+                });
+                return null;
+            }
+        };
+        // ── 1. The SAME pair gets its grace window. Nothing is routed anywhere. ──
+        let served = await attemptPin();
+        if (served)
+            return served;
+        const startedAt = Date.now();
+        for (const backoff of PINNED_GRACE_BACKOFF_MS) {
+            if (input.signal?.aborted)
+                return null;
+            if (Date.now() - startedAt + backoff > PINNED_SAME_PAIR_GRACE_MS)
+                break;
+            // Visible on BOTH surfaces: the CLI reads it on the console, the dashboard
+            // renders the same line as a progress step.
+            logger.warn(`   ⏳ your pinned ${pin} has not answered (${describeFailureKind(kind)}) — retrying it in ` +
+                `${Math.round(backoff / 1000)}s (${Math.round((Date.now() - startedAt) / 1000)}s of ` +
+                `${Math.round(PINNED_SAME_PAIR_GRACE_MS / 1000)}s). Nothing has been sent to another model.`);
+            await new Promise((resolve) => setTimeout(resolve, backoff));
+            served = await attemptPin();
+            if (served)
+                return served;
+        }
+        // ── 2. ASK. The pin is the user's contract; only they may release it. ────
+        const alternatives = this.pinAlternatives(session.model, session.type);
+        const switchTarget = alternatives.sameClass[0];
+        // Headless (a pipeline, a cron, a queue worker) has no one to ask: the strict
+        // refusal stands. Choosing silently FOR the user is the defect this fixes.
+        if (!input.askUser && !process.stdin.isTTY)
+            return null;
+        const ask = input.askUser ?? (await import('../tools/ask-user.js')).renderAskUser;
+        const choices = [
+            {
+                label: `Keep trying with ${pin}`,
+                description: 'Stay on your pinned model — nothing is routed to another model.',
+            },
+        ];
+        if (switchTarget) {
+            choices.push({
+                label: `Switch to ${switchTarget.provider}/${switchTarget.model}`,
+                description: `The closest same-class model available (${capabilityClassOf(switchTarget.model)}).`,
+            });
+        }
+        choices.push({
+            label: 'Type another model or provider…',
+            description: 'Name any model id, or provider/model, and it is used exactly as given.',
+        });
+        const keepIdx = 0;
+        const switchIdx = switchTarget ? 1 : -1;
+        const otherIdx = switchTarget ? 2 : 1;
+        // NOTE — there is deliberately NO "go to auto" option. It was considered and
+        // removed: it is the one choice that serves a model the user never named, and
+        // a strict pin exists precisely to rule that out. A user who wants routing to
+        // decide turns strict mode off, which is a decision they own and can see.
+        // Nothing in this method can therefore serve a pair the user did not pick.
+        const question = `I have NOT sent this to another model — you pinned ${pin} and strict mode is on, so that choice is yours.\n` +
+            `${pin} did not answer within ${Math.round(PINNED_SAME_PAIR_GRACE_MS / 1000)}s (${describeFailureKind(kind)}).\n` +
+            (switchTarget
+                ? `If you would rather switch, ${switchTarget.provider}/${switchTarget.model} is the closest same-class model available.`
+                : 'No same-class model is available to switch to right now.');
+        let answer = {};
+        /** The bounded-answer timer — cleared or unref'd as soon as it is not needed. */
+        let answerTimer;
+        try {
+            // BOUNDED: an unanswered question must not hold the turn open forever
+            // (see PINNED_ANSWER_TIMEOUT_MS). A late answer is simply ignored — the
+            // honest stop already happened.
+            const raced = await Promise.race([
+                ask(question, choices, false).then((a) => ({ answered: true, a })),
+                new Promise((resolve) => {
+                    answerTimer = setTimeout(() => resolve({ answered: false }), PINNED_ANSWER_TIMEOUT_MS);
+                    // Never hold the process open for an answer that already arrived: an
+                    // un-unref'd 5-minute timer kept the CLI alive long after the turn was
+                    // finished (the `chat` command would appear to hang on exit).
+                    answerTimer.unref?.();
+                }),
+            ]);
+            if (answerTimer)
+                clearTimeout(answerTimer);
+            if (!raced.answered) {
+                logger.warn(`   ⌛ no answer to the pinned-model question after ${Math.round(PINNED_ANSWER_TIMEOUT_MS / 60_000)} minutes — ` +
+                    `stopping on ${pin} rather than choosing for you.`);
+                return null;
+            }
+            answer = raced.a;
+        }
+        catch {
+            return null;
+        }
+        const chosen = typeof answer.index === 'number' ? answer.index : -1;
+        if (chosen === keepIdx) {
+            // One more full window on the SAME pair, then the honest stop. Bounded on
+            // purpose: "keep trying" must not become an unbounded loop the user cannot
+            // interrupt — they can ask again, and the dashboard's retry offer queues it.
+            const retryStart = Date.now();
+            for (;;) {
+                if (input.signal?.aborted)
+                    return null;
+                const again = await attemptPin();
+                if (again)
+                    return again;
+                if (Date.now() - retryStart >= PINNED_SAME_PAIR_GRACE_MS)
+                    break;
+                await new Promise((resolve) => setTimeout(resolve, 15_000));
+            }
+            return null;
+        }
+        if (switchIdx >= 0 && chosen === switchIdx && switchTarget) {
+            return await this.serveChosenPair(input, switchTarget.provider, switchTarget.model);
+        }
+        if (chosen === otherIdx) {
+            const custom = (answer.custom ?? '').trim();
+            if (custom) {
+                const pair = this.parsePinChoice(custom, session.type);
+                if (pair) {
+                    const servedCustom = await this.serveChosenPair(input, pair.provider, pair.model);
+                    if (servedCustom)
+                        return servedCustom;
+                }
+                logger.warn(`   ⚠️ could not use "${custom}" — check that the model is served by that provider.`);
+            }
+        }
+        return null;
+    }
     /**
      * E3b — the model-call step for the tool loop:
      * native generateTools when the provider supports it, JSON fallback
@@ -2797,7 +3379,14 @@ export class ChatCommand extends BaseCommand {
      * too, or a continuation whose first cloud provider dies re-routes on the
      * signal-free message and can land on a tiny local model.
      */
-    routingText) {
+    routingText, 
+    /**
+     * PINNED + STRICT escalation needs to ASK the user (see
+     * `pinnedStrictEscalation`). The dashboard console injects a real question
+     * card; a TTY falls back to the CLI prompt; headless has neither, and there
+     * the strict refusal stands rather than anything being chosen for the user.
+     */
+    askUser) {
         return async (messages, schemas, stepOnToken, stepSignal) => {
             // The effective token sink: the caller's stream wins; when a step-level
             // sink is also given (loop passthrough) they are the same channel.
@@ -2907,12 +3496,23 @@ export class ChatCommand extends BaseCommand {
                 // One resolution per attempt — the request, the trace, the telemetry
                 // and the cache key all read the same value (see above).
                 const effectiveModel = resolveEffectiveModel(typ, mdl);
-                // Record the ATTEMPTED model immediately so a failed step's trace and
-                // telemetry name the model that failed, instead of "unknown".
-                if (effectiveModel)
-                    session.model = effectiveModel;
-                // G5 — and name the attempt itself, so the trace recorder reports the
-                // real provider/model (post-failover) rather than the session default.
+                // Name the ATTEMPT itself — the trace recorder and the failure report
+                // read `lastAttempt` — but NEVER install its model on the session
+                // before the call succeeds.
+                //
+                // MEASURED (trace-1791732980335-omkv62, 2026-10-11). This used to assign
+                // `session.model = effectiveModel` here, BEFORE the request. A pinned
+                // `deepseek` turn whose step failed walked the fallback chain, and the
+                // walk's last candidate — which also FAILED — left its own model on the
+                // session. The loop's NEXT step then called the pinned provider with
+                // that foreign id (`deepseek` + `wire-stub-model`), which the API
+                // rejected outright: "The supported API model names are deepseek-flash,
+                // deepseek-v4-pro, but you passed wire-stub-model". The turn burned its
+                // whole failover walk (25 attempts) and ended in a model-shortage report
+                // while healthy models sat in the pool. A failed attempt must never
+                // become the model of the next request; the success paths
+                // (`answered()`, and the walks that install what they served) are the
+                // ones that own `session.model`.
                 this.lastAttempt = { provider: typ, model: effectiveModel };
                 const nativeKey = `${typ}|${effectiveModel ?? ''}`;
                 // Answer-quality resilience: a CONFUSED reply — the model talking about
@@ -3025,32 +3625,91 @@ export class ChatCommand extends BaseCommand {
                 // R2 — this IS the fallback transport, so say so: the same fact the
                 // subagent child announces, and what makes a chat turn comparable with it.
                 return answered({ content: text, toolCalls: calls, transport: 'json' });
+            }; // ── HOW PATIENT TO BE, AND WHY ────────────────────────────────────────
+            // A fixed schedule cannot tell a 2-second blink from a dead endpoint, so
+            // the schedule is chosen per pair from evidence the caller ALREADY HAS:
+            // is a same-or-better-band candidate reachable, does this pair have a
+            // track record, and has it already failed an EARLIER step of this turn.
+            // Both ways of getting this wrong are expensive — fail fast and a
+            // blinking strong model is silently replaced by a weaker one nobody
+            // chose; wait blindly and every user of a dead provider pays the full
+            // backoff. The plan's `reason` goes to the debug log, because "why was
+            // that turn slow / why did it change model" is asked after the fact.
+            const patiencePair = {
+                provider: session.type,
+                model: this.lastAttempt?.model ?? session.model ?? 'default',
             };
+            const patience = planBlipPatience({
+                current: patiencePair,
+                alternatives: failoverAlternatives(this.configManager, patiencePair.provider),
+                evidence: registryPatienceEvidence(patiencePair.provider, patiencePair.model),
+                // An entry here means an EARLIER step of this same turn already failed
+                // on this pair — the same pair failing twice is a pattern, not a blip,
+                // and patience collapses there whatever the alternatives look like.
+                failedEarlierStep: this.turnAttempts.some((a) => a.provider === patiencePair.provider && a.model === patiencePair.model),
+                deliveredWorkThisTurn: threadHasDeliveredWork(messages),
+            });
             try {
-                // Same-provider transient retry FIRST (see the helper's contract): a
-                // 503 spike at a shared endpoint must not become a dead run. Failover
-                // only helps if a DIFFERENT provider exists — and it also hides the real
-                // failure from the user while parking a healthy provider for 120s.
-                return await generateWithTransientRetry(() => tryGenerate(session.provider, session.type, session.model), abort, (attempt, err) => logger.warn(`   ⏳ ${session.provider.name} transient failure (attempt ${attempt}) — retrying shortly: ${err instanceof Error ? err.message.split('\n')[0] : String(err)}`));
+                logger.debug(`[patience] ${patience.reason}`);
+            }
+            catch {
+                // Logging must never break a turn.
+            }
+            try {
+                return await generateWithTransientRetry(() => tryGenerate(session.provider, session.type, session.model), abort, (attempt, err) => logger.warn(`   ⏳ ${session.provider.name} transient failure (attempt ${attempt}) — retrying shortly: ${err instanceof Error ? err.message.split('\n')[0] : String(err)}`), 
+                // Empty-response patience from the plan: granted for a proven pair
+                // (registry track record or real work this turn), LONGER when every
+                // alternative would de-escalate a capability band. A pair with neither
+                // gets none — the measured "5 empty responses on one model" loop stays
+                // impossible — while a pair that just finished real steps never has
+                // them thrown away by a single empty reply.
+                {
+                    // The env dial stays authoritative when set (tests, headless
+                    // gateways, metered connections) — it is an explicit configuration
+                    // decision, and the attempt COUNTS in the parity/E2E contracts are
+                    // derived from it.
+                    transientDelaysMs: transientRetryScheduleOverridden()
+                        ? undefined
+                        : patience.transientDelaysMs,
+                    emptyResponseDelaysMs: patience.emptyResponseDelaysMs,
+                });
             }
             catch (err) {
                 // P4 — the model this turn STARTED on failed. Recorded with a human
                 // phrase (never the raw provider text, which is how a JSON quota dump
                 // once reached a user verbatim) so the exhaustion report can name it.
                 const primaryKind = classifyFallbackError(err);
+                // The pair that FAILED is the one the attempt named — `session.model`
+                // still holds the pair the turn RAN on (see `tryGenerate`).
                 this.recordTurnAttempt({
-                    provider: session.type,
-                    model: session.model ?? 'default',
+                    provider: this.lastAttempt?.provider ?? session.type,
+                    model: this.lastAttempt?.model ?? session.model ?? 'default',
                     kind: primaryKind,
                     reason: describeFailureKind(primaryKind),
                 });
+                // ── LEARN the failure, don't just survive it ───────────────────────────
+                // A failed attempt was recorded in an in-memory per-turn list only, so
+                // the registry's health score, the quota timeline and the shared
+                // breaker all stayed untouched: the model kept its `verified` badge and
+                // was re-picked on the next turn, and a degraded turn left no on-disk
+                // evidence of WHICH candidate failed or WHY. `recordAutoProviderFailure`
+                // runs the full shared composition (model-scoped session exclusion,
+                // registry write-through, quota-timeline event, shared breaker) exactly
+                // as the empty-response handoff already does.
+                try {
+                    this.recordAutoProviderFailure(this.lastAttempt?.provider ?? session.type, err, this.lastAttempt?.model ?? session.model);
+                }
+                catch {
+                    // Best-effort — bookkeeping must never break the turn.
+                }
                 // Auto mode: fail over across the ranked candidates (never stuck).
                 if (mode.auto) {
                     const firstType = session.type;
                     // Observable telemetry, identical to the shared single-shot runner
                     // (the E2E repair-failover contract): one warn per walk, one
-                    // success log per landed candidate.
-                    logger.warn(`   ⚠️ ${session.provider.name} failed — trying the next auto candidate...`);
+                    // success log per landed candidate — and now the failure KIND in the
+                    // line, so the console says what went wrong instead of only that it did.
+                    logger.warn(`   ⚠️ ${session.provider.name} failed (${describeFailureKind(primaryKind)}) — trying the next auto candidate...`);
                     const failed = new Set([session.type]);
                     // Intent-aware escalation for the FAILOVER walk (the live junk path):
                     // a mid-turn failure used to re-route on the bare message alone, so a
@@ -3128,6 +3787,21 @@ export class ChatCommand extends BaseCommand {
                                 kind: nextKind,
                                 reason: describeFailureKind(nextKind),
                             });
+                            // ── DIAGNOSABILITY: every failed candidate gets a reason LINE and
+                            // a REGISTRY write, not only an in-memory entry. A live turn
+                            // walked gemini → openrouter → groq → local and left NO on-disk
+                            // record of why the first three died — the walk was undebuggable
+                            // and those candidates never lost health, so the router kept
+                            // offering them. `recordAutoProviderFailure` writes the pair's
+                            // own row (and, for a rate-limit, parks it for the real reset
+                            // window) while leaving a healthy provider's siblings routable.
+                            try {
+                                this.recordAutoProviderFailure(next.type, nextErr, next.model);
+                            }
+                            catch {
+                                // Best-effort — bookkeeping must never break the turn.
+                            }
+                            logger.warn(`   ⚠️ ${next.type}/${next.model ?? 'default'} failed (${describeFailureKind(nextKind)}) — trying the next auto candidate...`);
                             // Next candidate.
                         }
                     }
@@ -3169,7 +3843,47 @@ export class ChatCommand extends BaseCommand {
                         // the walk now installs what it serves (see below), and the warning
                         // must still name the provider that actually failed.
                         const pinnedType = session.type;
-                        for (const fbType of ordered) {
+                        /**
+                         * The model the USER pinned — for the same-class rule below.
+                         */
+                        const pinnedModel = this.lastAttempt?.model ?? session.model;
+                        /**
+                         * PINNED + AUTO-FALLBACK: providers that can hold the PIN'S
+                         * CAPABILITY CLASS are tried FIRST, and only then the ones that can
+                         * only step down.
+                         *
+                         * WHY (the user's own rule): "if a strong model is selected then only
+                         * strong should be the priority". The chain order was health/registry
+                         * order, so a provider whose only usable model was a small local one
+                         * could be reached while a provider with a same-class strong model sat
+                         * later in the chain — the exact silent downgrade this ordering
+                         * prevents. `crossClass` is what keeps it honest: when nothing in the
+                         * pin's class can serve, the step-down still happens, but it is named
+                         * in the log AND in the answer (see `routingNotice`).
+                         */
+                        const sameClassFirst = [];
+                        const crossClass = [];
+                        for (const t of ordered) {
+                            if (t === session.type)
+                                continue;
+                            let stepsDown = true;
+                            try {
+                                const r = resolveProvider(this.configManager, t);
+                                const base = resolveEffectiveModel(r.type, undefined);
+                                const pick = sameClassFallback(pinnedModel, [
+                                    ...(base ? [base] : []),
+                                    ...preferredModelsFor(r.type),
+                                ]);
+                                stepsDown = pick?.crossClass ?? true;
+                            }
+                            catch {
+                                // A provider we cannot describe cannot be promised a same-class
+                                // model — it waits for the second pass rather than being dropped.
+                                stepsDown = true;
+                            }
+                            (stepsDown ? crossClass : sameClassFirst).push(t);
+                        }
+                        for (const fbType of [...sameClassFirst, ...crossClass]) {
                             if (fbType === session.type)
                                 continue;
                             // ADMIN POLICY: never fall back to a provider the policy rules
@@ -3193,6 +3907,10 @@ export class ChatCommand extends BaseCommand {
                             // gate `loop-executor`'s pinned pool applies.
                             if (!hasCredentials(this.configManager, fbType))
                                 continue;
+                            // The model THIS candidate actually used — hoisted so the failure
+                            // handler below can name the pair without relying on block-scoped
+                            // bindings from the `try` body.
+                            let fbAttemptedModel;
                             try {
                                 const resolved = resolveProvider(this.configManager, fbType);
                                 // The fallback provider gets ITS OWN model, not the primary's
@@ -3206,7 +3924,25 @@ export class ChatCommand extends BaseCommand {
                                 // the dashboard console and the gateway chat engine - looked
                                 // dead.) Undefined = that provider's configured/adapter
                                 // default, which tryGenerate resolves per attempt.
-                                const fallbackModel = resolveEffectiveModel(resolved.type, undefined);
+                                /**
+                                 * The fallback provider gets a model from the PIN'S CLASS when
+                                 * it has one — never merely its healthiest adapter default, which
+                                 * is how a strong pin could be answered by a weak one (see
+                                 * `sameClassFallback`). A class step-down is LOGGED, so a
+                                 * reduced-quality handoff is never silent.
+                                 */
+                                const baseModel = resolveEffectiveModel(resolved.type, undefined);
+                                const pick = sameClassFallback(pinnedModel, [
+                                    ...(baseModel ? [baseModel] : []),
+                                    ...preferredModelsFor(resolved.type),
+                                ]);
+                                if (pick?.crossClass) {
+                                    logger.warn(`   ⚠️ no ${capabilityClassOf(pinnedModel)}-class model available to take over — ` +
+                                        `${resolved.type}/${pick.model} (${capabilityClassOf(pick.model)} class) is standing in for ` +
+                                        `${pinnedType}/${pinnedModel ?? 'default'}.`);
+                                }
+                                const fallbackModel = pick?.model ?? baseModel;
+                                fbAttemptedModel = fallbackModel;
                                 const resp = await tryGenerate(resolved.provider, resolved.type, fallbackModel);
                                 // ── The pair that ANSWERED is the pair the turn ran on ───────
                                 // This walk used to serve the fallback and leave `session` still
@@ -3241,7 +3977,27 @@ export class ChatCommand extends BaseCommand {
                                 logger.warn(`   🔀 ${pinnedType} was unavailable — answered from ${resolved.provider.name} (${fallbackModel ?? 'default'})`);
                                 return resp;
                             }
-                            catch {
+                            catch (fbErr) {
+                                // DIAGNOSABILITY (pinned walk): name and LEARN each failed
+                                // fallback candidate instead of swallowing it. The silent catch
+                                // meant a pinned turn that stepped through three dead providers
+                                // reported only the primary error, and none of those providers
+                                // lost health — the same undebuggable-walk defect the auto walk
+                                // had.
+                                const fbKind = classifyFallbackError(fbErr);
+                                this.recordTurnAttempt({
+                                    provider: fbType,
+                                    model: fbAttemptedModel ?? 'default',
+                                    kind: fbKind,
+                                    reason: describeFailureKind(fbKind),
+                                });
+                                try {
+                                    this.recordAutoProviderFailure(fbType, fbErr, fbAttemptedModel);
+                                }
+                                catch {
+                                    // Best-effort — bookkeeping must never break the turn.
+                                }
+                                logger.warn(`   ⚠️ ${fbType}/${fbAttemptedModel ?? 'default'} failed (${describeFailureKind(fbKind)}) — trying the next fallback...`);
                                 // Next fallback candidate.
                             }
                         }
@@ -3262,6 +4018,21 @@ export class ChatCommand extends BaseCommand {
                             .join('; ')}`);
                     }
                 }
+                else if (strictModelMode()) {
+                    /**
+                     * PINNED + STRICT — wait on the SAME model, then ASK. Never substitute:
+                     * that is the whole meaning of the pin. See `pinnedStrictEscalation`.
+                     */
+                    const decided = await this.pinnedStrictEscalation({
+                        session,
+                        err,
+                        tryGenerate,
+                        ...(askUser ? { askUser } : {}),
+                        signal: abort,
+                    });
+                    if (decided)
+                        return decided;
+                }
                 // Answer-quality resilience: every candidate failed (or none was
                 // tried) and the error carries the model's raw confused reply —
                 // deliver THAT instead of failing the whole turn. A confusing answer