@juspay/neurolink 9.87.2 → 9.87.4

package/dist/server/routes/claudeProxyRoutes.js

@@ -23,7 +23,7 @@ import { withSpan } from "../../telemetry/withSpan.js";
 import { ProxyTracer, recordFallbackAttempt } from "../../proxy/proxyTracer.js";
 import { createRawStreamCapture } from "../../proxy/rawStreamCapture.js";
 import { relocateClientSystemIntoMessages } from "../../proxy/systemRelocation.js";
-import { logBodyCapture, logRequest, logRequestAttempt, logStreamError, } from "../../proxy/requestLogger.js";
+import { logBodyCapture, logRequest, logRequestAttempt, } from "../../proxy/requestLogger.js";
 import { createSSEInterceptor } from "../../proxy/sseInterceptor.js";
 import { createStreamTerminalOutcomeTracker, mergeStreamTerminalOutcome, } from "../../proxy/streamOutcome.js";
 import { isPermanentRefreshFailure, needsRefresh, persistTokens, refreshToken, } from "../../proxy/tokenRefresh.js";
@@ -31,6 +31,7 @@ import { buildProxyTranslationPlan, parseRetryAfterMs, } from "../../proxy/routi
 import { writeJsonSnapshotAtomically } from "../../proxy/snapshotPersistence.js";
 import { recordAttempt, recordAttemptError, recordFinalError, recordFinalSuccess, } from "../../proxy/usageStats.js";
 import { logger } from "../../utils/logger.js";
+import { withTimeout } from "../../utils/async/withTimeout.js";
 import { ProviderHealthChecker } from "../../utils/providerHealth.js";
 // ---------------------------------------------------------------------------
 // Helpers
@@ -61,6 +62,8 @@ let configuredAccountAllowlist;
 const MAX_AUTH_RETRIES = 5;
 const MAX_TRANSIENT_SAME_ACCOUNT_RETRIES = 2;
 const TRANSIENT_SAME_ACCOUNT_RETRY_DELAYS_MS = [250, 1_000];
+const MAX_FALLBACK_NETWORK_RETRIES = 1;
+const FALLBACK_STREAM_IDLE_TIMEOUT_MS = 2 * 60 * 1000;
 /** Maximum upstream 429 attempts per account before rotating — for a TRANSIENT
  *  burst 429 only (window still "allowed", short retry-after). An exhaustion 429
  *  (5h/7d window "rejected") rotates immediately with zero same-account retries,
@@ -91,12 +94,23 @@ const AUTH_REFRESH_MAX_COOLDOWN_MS = 5 * 60 * 1000;
  *  thinking from Opus models (which can exceed 5 minutes for large contexts). */
 const UPSTREAM_FETCH_TIMEOUT_MS = 15 * 60 * 1000; // 15 minutes
 const accountRuntimeState = new Map();
+/** Shared across requests so a concurrent burst gets at most two retries for
+ *  the account/window, rather than every request starting its own retry chain. */
+const transientRateLimitRetryBudgets = new Map();
+/** Pace requests that arrive while the last usable account has a short
+ * transient cooldown. This converts a local 429/retry storm into a bounded
+ * queue and avoids releasing every waiting request at the same millisecond. */
+const transientCooldownAdmissionSchedules = new Map();
 /** Track whether we've run the one-time startup prune. */
 let startupPruneDone = false;
 /** Default cooling period when retries are exhausted and upstream didn't
  *  provide a retry-after header. Short enough to recover quickly, long
  *  enough to avoid immediately hammering the same account. */
 const DEFAULT_COOLING_PERIOD_MS = 60_000;
+const MAX_TRANSIENT_QUEUE_WAIT_MS = 90_000;
+const MAX_TRANSIENT_TOTAL_QUEUE_WAIT_MS = 120_000;
+const TRANSIENT_ADMISSION_SPACING_MS = 250;
+const MAX_TRANSIENT_ADMISSION_SPREAD_MS = 15_000;
 /** Advance the primary account index when the current primary is exhausted
  *  (429 retries exhausted or auth failure). This is what makes fill-first work:
  *  we stick to one account until it's unusable. Only advances when the exhausted
@@ -159,6 +173,74 @@ function isAccountCooling(accountKey) {
     const state = accountRuntimeState.get(accountKey);
     return !!state?.coolingUntil && Date.now() < state.coolingUntil;
 }
+function claimTransientRateLimitRetry(accountKey, coolingUntil, now = Date.now()) {
+    let budget = transientRateLimitRetryBudgets.get(accountKey);
+    if (!budget || now >= budget.coolingUntil) {
+        budget = { coolingUntil, retriesClaimed: 0 };
+        transientRateLimitRetryBudgets.set(accountKey, budget);
+    }
+    else if (coolingUntil > budget.coolingUntil) {
+        budget.coolingUntil = coolingUntil;
+    }
+    if (budget.retriesClaimed >= MAX_RATE_LIMIT_SAME_ACCOUNT_RETRIES) {
+        return undefined;
+    }
+    budget.retriesClaimed += 1;
+    return budget.retriesClaimed;
+}
+function claimTransientCooldownAdmission(accountKey, coolingUntil, now = Date.now()) {
+    if (coolingUntil <= now) {
+        return 0;
+    }
+    if (coolingUntil - now > MAX_TRANSIENT_QUEUE_WAIT_MS) {
+        return undefined;
+    }
+    let schedule = transientCooldownAdmissionSchedules.get(accountKey);
+    if (!schedule || now >= schedule.coolingUntil) {
+        schedule = { coolingUntil, nextAdmissionAt: coolingUntil };
+        transientCooldownAdmissionSchedules.set(accountKey, schedule);
+    }
+    else if (coolingUntil > schedule.coolingUntil) {
+        schedule.coolingUntil = coolingUntil;
+        schedule.nextAdmissionAt = Math.max(schedule.nextAdmissionAt, coolingUntil);
+    }
+    const admissionAt = Math.max(now, schedule.coolingUntil, schedule.nextAdmissionAt);
+    if (admissionAt - schedule.coolingUntil > MAX_TRANSIENT_ADMISSION_SPREAD_MS) {
+        return undefined;
+    }
+    schedule.nextAdmissionAt = admissionAt + TRANSIENT_ADMISSION_SPACING_MS;
+    return admissionAt - now;
+}
+async function waitForTransientAccountAvailability(orderedAccounts) {
+    const deadline = Date.now() + MAX_TRANSIENT_TOTAL_QUEUE_WAIT_MS;
+    while (Date.now() < deadline) {
+        const available = orderedAccounts.filter((account) => !isAccountCooling(account.key));
+        if (available.length > 0) {
+            return available;
+        }
+        const now = Date.now();
+        const transientCandidate = orderedAccounts
+            .map((account) => ({
+            account,
+            state: getOrCreateRuntimeState(account.key),
+        }))
+            .filter(({ state }) => state.coolingReason === "transient" &&
+            state.coolingUntil !== undefined &&
+            state.coolingUntil > now)
+            .sort((a, b) => (a.state.coolingUntil ?? Number.POSITIVE_INFINITY) -
+            (b.state.coolingUntil ?? Number.POSITIVE_INFINITY))[0];
+        if (!transientCandidate?.state.coolingUntil) {
+            return [];
+        }
+        const waitMs = claimTransientCooldownAdmission(transientCandidate.account.key, transientCandidate.state.coolingUntil, now);
+        if (waitMs === undefined || now + waitMs > deadline) {
+            return [];
+        }
+        logger.always(`[proxy] all usable accounts are transiently cooling; queueing request for account=${transientCandidate.account.label} in ${waitMs}ms`);
+        await sleep(waitMs);
+    }
+    return [];
+}
 // ---------------------------------------------------------------------------
 // Quota-aware cooldown helpers
 // ---------------------------------------------------------------------------
@@ -315,45 +397,105 @@ function isQuotaRoutingEnabled() {
     const v = (process.env.NEUROLINK_PROXY_QUOTA_ROUTING ?? "").toLowerCase();
     return v !== "off" && v !== "false" && v !== "0";
 }
-/** Derive the ordering signals for an account from its latest runtime quota. */
-function accountSortMetrics(accountKey, now) {
+/** Session-utilization soft limit above which an account is demoted below
+ *  accounts with headroom (never made unusable). The utilization snapshot is
+ *  always at least one response stale and requests land in concurrent bursts,
+ *  so a small buffer under 100% turns the window-exhaustion handoff proactive
+ *  (scheduled between requests) instead of reactive (a burst of 429s).
+ *  Override with NEUROLINK_PROXY_SESSION_SOFT_LIMIT (0 < x <= 1; 1 disables). */
+function getSessionSoftLimit() {
+    // Number() rejects partially numeric values ("0.5oops") that parseFloat
+    // would silently truncate.
+    const raw = Number(process.env.NEUROLINK_PROXY_SESSION_SOFT_LIMIT ?? "");
+    return Number.isFinite(raw) && raw > 0 && raw <= 1 ? raw : 0.97;
+}
+/** Width of the bucket within which two session resets count as "the same
+ *  time", letting the weekly reset decide. Exact epoch equality never occurs,
+ *  and bucketing (unlike pairwise closeness) keeps the comparator transitive.
+ *  Override with NEUROLINK_PROXY_SESSION_RESET_TOLERANCE_MS. */
+function getSessionResetToleranceMs() {
+    // Number() + isInteger rejects partially numeric values ("900000oops")
+    // that parseInt would silently truncate.
+    const raw = Number(process.env.NEUROLINK_PROXY_SESSION_RESET_TOLERANCE_MS ?? "");
+    return Number.isInteger(raw) && raw > 0 ? raw : 15 * 60 * 1000;
+}
+/**
+ * Derive the ordering signals for an account from its latest runtime quota.
+ *
+ * Reset freshening: a window whose reset epoch has already passed is treated
+ * as FRESH (0 used, "allowed", reset unknown) at read time — stale snapshot
+ * numbers from before the reset can never saturate or reject an account whose
+ * window Anthropic has since renewed. The snapshot itself is refreshed from
+ * live response headers the next time the account serves a request.
+ */
+function accountSortMetrics(accountKey, now, sessionSoftLimit, sessionResetToleranceMs) {
     const st = accountRuntimeState.get(accountKey);
     const q = st?.quota;
     const coolingActive = !!st?.coolingUntil && now < st.coolingUntil;
+    // resetEpochToMs returns undefined for absent OR passed resets, so a
+    // ticking window is exactly "reset !== undefined".
     const weeklyReset = resetEpochToMs(q?.weeklyResetAt, now);
     const sessionReset = resetEpochToMs(q?.sessionResetAt, now);
-    const weeklyRejected = q?.weeklyStatus === "rejected" && weeklyReset !== undefined;
-    const sessionRejected = q?.sessionStatus === "rejected" && sessionReset !== undefined;
+    const sessionTicking = sessionReset !== undefined;
+    const weeklyTicking = weeklyReset !== undefined;
+    const sessionUsed = sessionTicking ? (q?.sessionUsed ?? 0) : 0;
+    const weeklyUsed = weeklyTicking ? (q?.weeklyUsed ?? -1) : q ? 0 : -1;
+    const sessionStatus = sessionTicking
+        ? (q?.sessionStatus ?? "unknown")
+        : "allowed";
+    const weeklyStatus = weeklyTicking
+        ? (q?.weeklyStatus ?? "unknown")
+        : "allowed";
+    const saturated = sessionStatus === "throttled" ||
+        (sessionTicking && sessionUsed >= sessionSoftLimit);
     return {
-        usable: !coolingActive && !weeklyRejected && !sessionRejected,
+        usable: !coolingActive &&
+            weeklyStatus !== "rejected" &&
+            sessionStatus !== "rejected",
+        saturated,
         hasQuota: !!q,
         coolingUntil: st?.coolingUntil ?? 0,
-        weeklyReset: weeklyReset ?? Number.POSITIVE_INFINITY,
+        sessionResetBucket: sessionTicking
+            ? Math.floor(sessionReset / sessionResetToleranceMs)
+            : Number.POSITIVE_INFINITY,
         sessionReset: sessionReset ?? Number.POSITIVE_INFINITY,
-        weeklyUsed: q?.weeklyUsed ?? -1,
+        weeklyReset: weeklyReset ?? Number.POSITIVE_INFINITY,
+        weeklyUsed,
     };
 }
 /**
  * Order accounts to MAXIMIZE quota utilization (fill-first, smart order):
- * spend the account whose window refreshes SOONEST first, so its about-to-reset
+ * spend the window that expires SOONEST first, so its about-to-reset
  * allowance isn't wasted, then move to accounts with longer-dated resets.
  *
  * Priority among usable accounts:
  *   1. no quota data yet — probe first: one request reveals its windows and
  *      self-corrects the ordering. (Ranking unknowns last would starve them
  *      forever: never picked → never observed → never comparable.)
- *   2. soonest WEEKLY (7d) reset  — the scarce, use-it-or-lose-it ceiling
- *   3. soonest SESSION (5h) reset
- *   4. highest weekly utilization — finish off the one closest to done
- *   5. configured primary account, then insertion order
+ *   2. session headroom before session-saturated (>= soft limit or
+ *      "throttled") — saturated accounts then follow the same bucketed
+ *      session ordering below: soonest back in service first, weekly
+ *      deciding same-bucket ties.
+ *   3. soonest SESSION (5h) reset — the capacity expiring soonest; compared
+ *      in tolerance buckets so near-simultaneous resets count as equal.
+ *   4. soonest WEEKLY (7d) reset — decides between same-bucket sessions.
+ *   5. highest weekly utilization — finish off the one closest to done
+ *   6. configured primary account, then insertion order
+ * An account with NO ticking session window (fresh, not yet started) has
+ * nothing expiring and sorts after ticking windows in step 3.
  * Cooling/rejected accounts sort last, soonest-back-to-service first, as
  * last resort.
  */
 function orderAccountsByQuota(accounts, now) {
     const primaryKey = configuredPrimaryAccountKey;
+    // Read the env-tunable thresholds once per sort: cheaper than per-compare,
+    // and a mid-sort env change can never make the comparator intransitive.
+    const sessionSoftLimit = getSessionSoftLimit();
+    const sessionResetToleranceMs = getSessionResetToleranceMs();
+    const metrics = (key) => accountSortMetrics(key, now, sessionSoftLimit, sessionResetToleranceMs);
     return [...accounts].sort((a, b) => {
-        const ma = accountSortMetrics(a.key, now);
-        const mb = accountSortMetrics(b.key, now);
+        const ma = metrics(a.key);
+        const mb = metrics(b.key);
         if (ma.usable !== mb.usable) {
             return ma.usable ? -1 : 1;
         }
@@ -365,12 +507,18 @@ function orderAccountsByQuota(accounts, now) {
         if (ma.hasQuota !== mb.hasQuota) {
             return ma.hasQuota ? 1 : -1;
         }
+        if (ma.saturated !== mb.saturated) {
+            return ma.saturated ? 1 : -1;
+        }
+        // Saturated pairs fall through to the same bucketed session ordering:
+        // soonest-back-in-service at bucket granularity, weekly deciding ties —
+        // honoring the configured tolerance instead of exact-epoch comparison.
+        if (ma.sessionResetBucket !== mb.sessionResetBucket) {
+            return ma.sessionResetBucket - mb.sessionResetBucket;
+        }
         if (ma.weeklyReset !== mb.weeklyReset) {
             return ma.weeklyReset - mb.weeklyReset;
         }
-        if (ma.sessionReset !== mb.sessionReset) {
-            return ma.sessionReset - mb.sessionReset;
-        }
         if (ma.weeklyUsed !== mb.weeklyUsed) {
             return mb.weeklyUsed - ma.weeklyUsed;
         }
@@ -645,13 +793,11 @@ function responseInfoFromStream(data) {
  * into the body.  Non-CC clients (Curator, custom apps) don't send these —
  * Anthropic rejects without them.
  */
-function polyfillOAuthBody(bodyStr, accountToken, snapshot, preferredSessionId) {
+function polyfillOAuthBody(bodyStr, accountToken, snapshot, isClaudeClientRequest, preferredSessionId) {
     try {
         const parsed = JSON.parse(bodyStr);
-        // Billing header block (required by Anthropic for OAuth)
-        // NOTE: This block MUST be deterministic (no random values) to preserve
-        // Anthropic's prompt caching prefix chain. We keep the real Claude Code
-        // version/entrypoint shape when present, but stabilize the volatile cch.
+        // Billing header block synthesized for clients that do not already provide
+        // the genuine Claude Code identity shape.
         const agentBlock = {
             type: "text",
             text: snapshot?.body?.agentBlock ||
@@ -661,11 +807,11 @@ function polyfillOAuthBody(bodyStr, accountToken, snapshot, preferredSessionId)
         //
         // The subscription/OAuth path only accepts a `system` it recognises as the
         // genuine Claude Code prompt. A real CC client sends its own billing + agent
-        // identity blocks alongside the canonical prompt — we keep those in place and
-        // just stabilise the volatile billing `cch`. A custom client (Curator) sends
-        // its own arbitrary system prompt with NO agent block; left in `system` it is
-        // rejected as `rate_limit_error: "Error"`, so we relocate it into the message
-        // stream and send only the recognised billing + agent blocks as `system`.
+        // identity blocks alongside the canonical prompt, which must pass through
+        // unchanged. A custom client (Curator) sends its own arbitrary system prompt
+        // with NO agent block; left in `system` it is rejected as
+        // `rate_limit_error: "Error"`, so we relocate it into the message stream and
+        // send only the recognised billing + agent blocks as `system`.
         if (parsed.system) {
             if (typeof parsed.system === "string") {
                 parsed.system = [{ type: "text", text: parsed.system }];
@@ -679,28 +825,28 @@ function polyfillOAuthBody(bodyStr, accountToken, snapshot, preferredSessionId)
                     type: "text",
                     text: buildStableClaudeCodeBillingHeader(parsed.system[billingIdx]?.text ?? snapshot?.body?.billingHeader),
                 };
-                // A genuine Claude Code client supplies its own agent-identity block;
-                // a custom client (Curator) does not.
-                const isClaudeCodeClient = agentIdx >= 0;
-                // Strip billing/agent from their positions (reverse order so indices
-                // stay valid). What remains is the client's "extra" system content.
-                const indicesToRemove = [billingIdx, agentIdx]
-                    .filter((i) => i >= 0)
-                    .sort((a, b) => b - a);
-                for (const idx of indicesToRemove) {
-                    parsed.system.splice(idx, 1);
-                }
-                if (!isClaudeCodeClient && parsed.system.length > 0) {
-                    // Non-CC client: relocate its system into the message stream so the
-                    // subscription/OAuth path accepts the request, then send only the
-                    // recognised billing + agent blocks as `system`.
-                    relocateClientSystemIntoMessages(parsed, parsed.system);
-                    parsed.system = [billingBlock, agentBlock];
+                const hasClaudeCodeSystemIdentity = isClaudeClientRequest && agentIdx >= 0;
+                if (hasClaudeCodeSystemIdentity) {
+                    // Claude Code's subagent billing marker, block order, and cache
+                    // controls are part of the accepted request shape. Preserve every
+                    // supplied block exactly; only synthesize a billing block if absent.
+                    if (billingIdx < 0) {
+                        parsed.system.unshift(billingBlock);
+                    }
                 }
                 else {
-                    // Genuine Claude Code (or no extra blocks): keep the recognised system
-                    // and append the deterministic billing + agent blocks at the end.
-                    parsed.system = [...parsed.system, billingBlock, agentBlock];
+                    // Strip generated identity blocks before relocating a custom
+                    // client's actual system instructions into the message stream.
+                    const indicesToRemove = [billingIdx, agentIdx]
+                        .filter((i) => i >= 0)
+                        .sort((a, b) => b - a);
+                    for (const idx of indicesToRemove) {
+                        parsed.system.splice(idx, 1);
+                    }
+                    if (parsed.system.length > 0) {
+                        relocateClientSystemIntoMessages(parsed, parsed.system);
+                    }
+                    parsed.system = [billingBlock, agentBlock];
                 }
             }
         }
@@ -1633,25 +1779,55 @@ async function loadClaudeProxyAccounts(args) {
 }
 async function executeClaudeFallbackTranslation(args) {
     const { ctx, body, tracer, requestStartTime, logProxyBody, logFinalRequest, options, providerLabel, } = args;
+    const fallbackAbortController = new AbortController();
+    let streamResult;
+    try {
+        streamResult = await withTimeout(ctx.neurolink.stream({
+            ...options,
+            abortSignal: fallbackAbortController.signal,
+        }), FALLBACK_STREAM_IDLE_TIMEOUT_MS, `Fallback ${providerLabel} initialization timed out after ${FALLBACK_STREAM_IDLE_TIMEOUT_MS}ms`);
+    }
+    catch (error) {
+        fallbackAbortController.abort(error);
+        throw error;
+    }
+    const consumeFallbackStream = async (onText) => {
+        const iterator = streamResult.stream[Symbol.asyncIterator]();
+        let collectedText = "";
+        try {
+            while (true) {
+                const { value: chunk, done } = await withTimeout(iterator.next(), FALLBACK_STREAM_IDLE_TIMEOUT_MS, `Fallback ${providerLabel} stream timed out after ${FALLBACK_STREAM_IDLE_TIMEOUT_MS}ms of inactivity`);
+                if (done) {
+                    return collectedText;
+                }
+                const text = extractText(chunk);
+                if (text) {
+                    collectedText += text;
+                    onText?.(text);
+                }
+            }
+        }
+        catch (error) {
+            fallbackAbortController.abort(error);
+            void iterator.return?.().catch(() => {
+                // Timeout/error already determines the request outcome.
+            });
+            throw error;
+        }
+    };
     if (body.stream) {
-        const streamResult = await ctx.neurolink.stream(options);
         const serializer = new ClaudeStreamSerializer(body.model, 0);
         // Eagerly consume stream so errors fire synchronously and the
         // fallback loop in tryConfiguredClaudeFallbackChain can catch them.
         const frames = [];
-        let collectedText = "";
         for (const frame of serializer.start()) {
             frames.push(frame);
         }
-        for await (const chunk of streamResult.stream) {
-            const text = extractText(chunk);
-            if (text) {
-                collectedText += text;
-                for (const frame of serializer.pushDelta(text)) {
-                    frames.push(frame);
-                }
+        const collectedText = await consumeFallbackStream((text) => {
+            for (const frame of serializer.pushDelta(text)) {
+                frames.push(frame);
             }
-        }
+        });
         const toolCalls = streamResult.toolCalls ?? [];
         if (!hasTranslatedOutput(collectedText, toolCalls)) {
             throw new Error(`Translated provider ${providerLabel} returned no content or tool calls`);
@@ -1696,14 +1872,7 @@ async function executeClaudeFallbackTranslation(args) {
         }
         return sseGenerator();
     }
-    const streamResult = await ctx.neurolink.stream(options);
-    let collectedText = "";
-    for await (const chunk of streamResult.stream) {
-        const text = extractText(chunk);
-        if (text) {
-            collectedText += text;
-        }
-    }
+    const collectedText = await consumeFallbackStream();
     if (!hasTranslatedOutput(collectedText, streamResult.toolCalls)) {
         throw new Error(`Translated provider ${providerLabel} returned no content or tool calls`);
     }
@@ -1736,6 +1905,25 @@ async function executeClaudeFallbackTranslation(args) {
     });
     return clientResponse;
 }
+async function executeClaudeFallbackWithRetry(args) {
+    let lastError;
+    for (let retry = 0; retry <= MAX_FALLBACK_NETWORK_RETRIES; retry += 1) {
+        try {
+            return await executeClaudeFallbackTranslation(args);
+        }
+        catch (error) {
+            lastError = error;
+            if (!isRetryableNetworkError(error) ||
+                retry === MAX_FALLBACK_NETWORK_RETRIES) {
+                throw error;
+            }
+            const delayMs = TRANSIENT_SAME_ACCOUNT_RETRY_DELAYS_MS[retry] ?? 250;
+            logger.always(`[proxy] retrying fallback=${args.providerLabel} after transient network error (${retry + 1}/${MAX_FALLBACK_NETWORK_RETRIES}) in ${delayMs}ms: ${describeTransportError(error)}`);
+            await sleep(delayMs);
+        }
+    }
+    throw lastError;
+}
 async function tryConfiguredClaudeFallbackChain(args) {
     const { ctx, body, parsedFallbackRequest, modelRouter, tracer, requestStartTime, logProxyBody, logFinalRequest, } = args;
     const chain = modelRouter?.getFallbackChain() ?? [];
@@ -1753,6 +1941,7 @@ async function tryConfiguredClaudeFallbackChain(args) {
         attemptCount: fallbackPlan.attempts.slice(1).length,
         reason: "all_anthropic_accounts_exhausted",
     });
+    let lastFallbackError;
     for (const fallback of fallbackPlan.attempts.slice(1)) {
         if (!fallback.provider || !fallback.model) {
             continue;
@@ -1768,7 +1957,7 @@ async function tryConfiguredClaudeFallbackChain(args) {
                 provider: fallback.provider,
                 model: fallback.model,
             });
-            const response = await executeClaudeFallbackTranslation({
+            const response = await executeClaudeFallbackWithRetry({
                 ctx,
                 body,
                 tracer,
@@ -1818,7 +2007,7 @@ async function tryConfiguredClaudeFallbackChain(args) {
             else if (errMsg.includes("Resource exhausted")) {
                 errorClass = "provider_quota";
             }
-            logger.always(`[proxy] fallback ${fallback.provider}/${fallback.model} failed [${errorClass}]: ${errMsg}`);
+            logger.always(`[proxy] fallback ${fallback.provider}/${fallback.model} failed [${errorClass}]: ${describeTransportError(fallbackErr)}`);
             recordFallbackAttempt({
                 provider: fallback.provider,
                 model: fallback.model,
@@ -1826,23 +2015,25 @@ async function tryConfiguredClaudeFallbackChain(args) {
                 errorMessage: `[${errorClass}] ${errMsg}`,
                 durationMs: Date.now() - fallbackStart,
             });
+            lastFallbackError = `[${fallback.provider}/${fallback.model}] ${describeTransportError(fallbackErr)}`;
         }
     }
-    return { response: null };
+    return { response: null, lastErrorMessage: lastFallbackError };
 }
 async function tryAutoClaudeFallback(args) {
     const { ctx, body, tracer, requestStartTime, logProxyBody, logFinalRequest } = args;
+    const fallbackStart = Date.now();
     try {
         const parsed = parseClaudeRequest(body);
         const plan = buildProxyTranslationPlan({ provider: "anthropic", model: body.model }, [], body.model, parsed);
         logProxyRoutingPlan(logProxyBody, "auto_fallback", plan);
         const autoAttempt = plan.attempts.find((attempt) => attempt.label === "auto-provider");
         if (!autoAttempt) {
-            return null;
+            return { response: null };
         }
         logger.always("[proxy] fallback → auto-provider");
         const options = buildProxyFallbackOptions(parsed);
-        return await executeClaudeFallbackTranslation({
+        const response = await executeClaudeFallbackWithRetry({
             ctx,
             body,
             tracer,
@@ -1852,14 +2043,43 @@ async function tryAutoClaudeFallback(args) {
             options: options,
             providerLabel: "auto-provider",
         });
+        recordFallbackAttempt({
+            provider: "auto-provider",
+            model: body.model,
+            status: "success",
+            durationMs: Date.now() - fallbackStart,
+        });
+        tracer?.setFallbackInfo({
+            triggered: true,
+            provider: "auto-provider",
+            model: body.model,
+            attemptCount: 1,
+            reason: "fallback_success",
+        });
+        return { response };
     }
     catch (fallbackErr) {
-        logger.debug(`[proxy] fallback auto-provider failed: ${fallbackErr instanceof Error ? fallbackErr.message : String(fallbackErr)}`);
-        return null;
+        const errorMessage = describeTransportError(fallbackErr);
+        logger.always(`[proxy] fallback auto-provider failed: ${errorMessage}`);
+        recordFallbackAttempt({
+            provider: "auto-provider",
+            model: body.model,
+            status: "failure",
+            errorMessage,
+            durationMs: Date.now() - fallbackStart,
+        });
+        tracer?.setFallbackInfo({
+            triggered: true,
+            provider: "auto-provider",
+            model: body.model,
+            attemptCount: 1,
+            reason: "fallback_failure",
+        });
+        return { response: null, lastErrorMessage: errorMessage };
     }
 }
 function buildClaudeAnthropicFailureResponse(args) {
-    const { tracer, requestStartTime, authFailureMessage, authCooldownMessage, invalidRequestFailure, sawNetworkError, sawTransientFailure, sawRateLimit, lastError, orderedAccounts, buildLoggedClaudeError, logProxyBody, logFinalRequest, } = args;
+    const { tracer, requestStartTime, authFailureMessage, authCooldownMessage, invalidRequestFailure, sawNetworkError, sawTransientFailure, sawRateLimit, lastError, fallbackFailureMessage, orderedAccounts, buildLoggedClaudeError, logProxyBody, logFinalRequest, } = args;
     if (authFailureMessage && !sawRateLimit) {
         tracer?.setError("authentication_error", authFailureMessage);
         tracer?.end(401, Date.now() - requestStartTime);
@@ -1895,20 +2115,26 @@ function buildClaudeAnthropicFailureResponse(args) {
         }
     }
     if ((sawNetworkError || sawTransientFailure) && !sawRateLimit) {
+        const fallbackSuffix = fallbackFailureMessage
+            ? ` Fallback also failed: ${fallbackFailureMessage}`
+            : "";
         const msg = `All Anthropic accounts failed due to transient upstream/network errors. Last error: ${lastError instanceof Error
             ? lastError.message
-            : String(lastError ?? "unknown")}`;
+            : String(lastError ?? "unknown")}.${fallbackSuffix}`;
         tracer?.setError("transient_error", msg.slice(0, 500));
         tracer?.end(502, Date.now() - requestStartTime);
-        return buildLoggedClaudeError(502, msg);
+        return buildLoggedClaudeError(502, msg, fallbackFailureMessage ? "fallback_exhausted" : "transient_error");
     }
     if (!sawRateLimit) {
+        const fallbackSuffix = fallbackFailureMessage
+            ? ` Fallback also failed: ${fallbackFailureMessage}`
+            : "";
         const msg = `All Anthropic accounts failed. Last error: ${lastError instanceof Error
             ? lastError.message
-            : String(lastError ?? "unknown")}`;
+            : String(lastError ?? "unknown")}.${fallbackSuffix}`;
         tracer?.setError("all_accounts_failed", msg.slice(0, 500));
         tracer?.end(502, Date.now() - requestStartTime);
-        return buildLoggedClaudeError(502, msg);
+        return buildLoggedClaudeError(502, msg, fallbackFailureMessage ? "fallback_exhausted" : "all_accounts_failed");
     }
     const now = Date.now();
     const activeRateLimitCooldowns = orderedAccounts
@@ -2012,7 +2238,7 @@ async function handleAnthropicSuccessfulResponse(args) {
     });
 }
 async function handleAnthropicStreamingSuccessResponse(args) {
-    const { ctx, body, account, accountState: _accountState, response, responseHeaders, tracer, requestStartTime, fetchStartMs, attemptNumber, finalBodyStr, upstreamSpan, logProxyBody, logFinalRequest, } = args;
+    const { account, accountState: _accountState, response, responseHeaders, tracer, requestStartTime, fetchStartMs, attemptNumber, finalBodyStr, upstreamSpan, logProxyBody, logFinalRequest, } = args;
     if (!response.body) {
         upstreamSpan?.end();
         tracer?.setError("stream_error", "No response body from upstream");
@@ -2093,17 +2319,9 @@ async function handleAnthropicStreamingSuccessResponse(args) {
                 controller.enqueue(value);
             }
             catch (streamErr) {
-                const errMsg = streamErr instanceof Error ? streamErr.message : String(streamErr);
+                const errMsg = describeTransportError(streamErr);
                 logger.always(`[proxy] mid-stream error account=${account.label}: ${errMsg}`);
                 streamOutcomeTracker.fail(errMsg);
-                logStreamError({
-                    timestamp: new Date().toISOString(),
-                    requestId: ctx.requestId,
-                    account: account.label,
-                    model: body.model,
-                    errorMessage: errMsg,
-                    durationMs: Date.now() - fetchStartMs,
-                });
                 if (!mainStreamClosed) {
                     mainStreamClosed = true;
                     const errorEvent = `event: error\ndata: ${JSON.stringify({ type: "error", error: { type: "api_error", message: `Upstream stream interrupted: ${errMsg}` } })}\n\n`;
@@ -2469,7 +2687,7 @@ async function handleAnthropicJsonSuccessResponse(args) {
     return { response: responseJson };
 }
 async function handleAnthropicSuccessfulRetryResponse(args) {
-    const { ctx, body, account, accountState, retryResp, tracer, requestStartTime, fetchStartMs, attemptNumber, finalBodyStr, upstreamSpan, logProxyBody, logFinalRequest, } = args;
+    const { body, account, accountState, retryResp, tracer, requestStartTime, fetchStartMs, attemptNumber, finalBodyStr, upstreamSpan, logProxyBody, logFinalRequest, } = args;
     const retryQuota = parseQuotaHeaders(retryResp.headers);
     if (retryQuota) {
         // Keep the auth-retry success path in parity with the main success path:
@@ -2514,17 +2732,9 @@ async function handleAnthropicSuccessfulRetryResponse(args) {
                     controller.enqueue(value);
                 }
                 catch (streamErr) {
-                    const errMsg = streamErr instanceof Error ? streamErr.message : String(streamErr);
+                    const errMsg = describeTransportError(streamErr);
                     logger.always(`[proxy] mid-stream error (auth-retry) account=${account.label}: ${errMsg}`);
                     streamOutcomeTracker.fail(errMsg);
-                    logStreamError({
-                        timestamp: new Date().toISOString(),
-                        requestId: ctx.requestId,
-                        account: account.label,
-                        model: body.model,
-                        errorMessage: errMsg,
-                        durationMs: Date.now() - fetchStartMs,
-                    });
                     if (!retryStreamClosed) {
                         retryStreamClosed = true;
                         const errorEvent = `event: error\ndata: ${JSON.stringify({ type: "error", error: { type: "api_error", message: `Upstream stream interrupted: ${errMsg}` } })}\n\n`;
@@ -2716,15 +2926,36 @@ async function handleAnthropicAuthRetry(args) {
             authRetryError = `retry ${authRetry + 1}/${MAX_AUTH_RETRIES} failed with status ${retryStatus}`;
             currentLastError = retryBody;
             logger.debug(`[proxy] retry ${authRetry + 1} failed: ${retryStatus} ${retryBody.substring(0, 120)}`);
-            recordAttemptError(account.label, account.type, retryStatus);
-            // A real rate-limit 429 rotates accounts. But an anti-abuse / construction
-            // 429 (no rate-limit headers, body "Error") is NOT a real rate limit:
-            // advancing the primary or rotating cannot help and only burns quota. Skip
-            // the rotate path for it so it falls through to the terminal error return
-            // below, surfacing the truthful upstream error — mirroring the initial
-            // fetch path's fast-fail (isAntiAbuseConstruction429).
             if (retryStatus === 429 &&
-                !isAntiAbuseConstruction429(retryRespHeaders, retryBody)) {
+                isAntiAbuseConstruction429(retryRespHeaders, retryBody)) {
+                logger.always(`[proxy] ← 429 account=${account.label} anti-abuse/construction rejection after OAuth refresh — returning non-retryable request error`);
+                logAttempt(429, "construction_rejection", retryBody);
+                tracer?.setError("construction_rejection", retryBody.slice(0, 500));
+                currentUpstreamSpan?.end();
+                return {
+                    response: finalizeAnthropicTerminalFetchError({
+                        terminalError: buildAnthropicConstructionRejectionTerminalError(),
+                        account,
+                        tracer,
+                        requestStartTime,
+                        attemptNumber,
+                        logProxyBody,
+                        logFinalRequest,
+                    }),
+                    continueLoop: false,
+                    lastError: retryBody,
+                    authFailureMessage: currentAuthFailureMessage,
+                    sawRateLimit: currentSawRateLimit,
+                    sawTransientFailure: currentSawTransientFailure,
+                    sawNetworkError: currentSawNetworkError,
+                    upstreamSpan: undefined,
+                };
+            }
+            recordAttemptError(account.label, account.type, retryStatus);
+            // Construction rejections return through the terminal 400 path above.
+            // Every 429 reaching this branch is a genuine rate limit and must cool
+            // the account according to its reset window before rotating.
+            if (retryStatus === 429) {
                 currentSawRateLimit = true;
                 // Cool the account per its real reset window before rotating, so a
                 // session/weekly-exhausted account isn't re-selected next request.
@@ -2862,6 +3093,22 @@ function buildAnthropicTerminalErrorResponse(args) {
         return clientError;
     }
 }
+function finalizeAnthropicTerminalFetchError(args) {
+    const { terminalError, account, tracer, requestStartTime, attemptNumber, logProxyBody, logFinalRequest, } = args;
+    recordFinalError(terminalError.status, account.label, account.type);
+    tracer?.end(terminalError.status, Date.now() - requestStartTime);
+    return buildAnthropicTerminalErrorResponse({
+        responseStatus: terminalError.status,
+        account,
+        errBody: terminalError.body,
+        errRespHeaders: terminalError.headers,
+        requestStartTime,
+        attemptNumber,
+        logProxyBody,
+        logFinalRequest,
+        errorType: terminalError.errorType,
+    });
+}
 async function handleAnthropicNonOkResponse(args) {
     const { response, account, accountState, enabledAccounts, orderedAccounts, tracer, requestStartTime, fetchStartMs, attemptNumber, logAttempt, logProxyBody, logFinalRequest, lastError, authFailureMessage, sawTransientFailure, invalidRequestFailure, } = args;
     let currentLastError = lastError;
@@ -3271,7 +3518,7 @@ async function prepareAnthropicAccountAttempt(args) {
         }
     }
     const buildUpstreamBody = (token) => isOAuth
-        ? polyfillOAuthBody(bodyStr, token, snapshot, headers["x-claude-code-session-id"])
+        ? polyfillOAuthBody(bodyStr, token, snapshot, isClaudeClientRequest, headers["x-claude-code-session-id"])
         : { bodyStr };
     const polyfilledBody = buildUpstreamBody(account.token);
     if (isOAuth &&
@@ -3325,7 +3572,7 @@ async function prepareAnthropicAccountAttempt(args) {
  * "Error" and which carries NONE of the real rate-limit headers (no retry-after,
  * no anthropic-ratelimit-*). This is NOT a capacity limit — retrying or rotating
  * accounts cannot fix it and only burns quota, so the caller must fail fast and
- * surface the truthful upstream error instead of "all accounts rate-limited".
+ * return a non-retryable request error instead of "all accounts rate-limited".
  */
 function isAntiAbuseConstruction429(headers, body) {
     const hasRetryAfter = !!headers["retry-after"];
@@ -3335,6 +3582,14 @@ function isAntiAbuseConstruction429(headers, body) {
     }
     return (body.includes("rate_limit_error") && /"message"\s*:\s*"Error"/.test(body));
 }
+function buildAnthropicConstructionRejectionTerminalError() {
+    return {
+        status: 400,
+        body: JSON.stringify(buildClaudeError(400, "Anthropic rejected the OAuth request shape. This is not an account rate limit.", "invalid_request_error")),
+        headers: { "content-type": "application/json" },
+        errorType: "construction_rejection",
+    };
+}
 async function fetchAnthropicAccountResponse(args) {
     const { url, headers, finalBodyStr, account, accountState: _accountState2, enabledAccounts: _enabledAccounts, orderedAccounts: _orderedAccounts, tracer, logAttempt, logProxyBody, fetchStartMs, attemptNumber, currentLastError, currentSawRateLimit, currentSawNetworkError, upstreamSpan, } = args;
     let lastError = currentLastError;
@@ -3374,9 +3629,7 @@ async function fetchAnthropicAccountResponse(args) {
         };
     }
     if (response.status === 429) {
-        sawRateLimit = true;
         const retryAfterMs = parseRetryAfterMs(response.headers.get("retry-after"));
-        recordAttemptError(account.label, account.type, 429);
         // Capture full response headers and body for diagnostics (parity with
         // handleAnthropicNonOkResponse which does this for all other error statuses).
         const errRespHeaders = {};
@@ -3407,28 +3660,24 @@ async function fetchAnthropicAccountResponse(args) {
         });
         // Anti-abuse / request-construction 429 (no rate-limit headers, body
         // "Error"): rotating accounts cannot help and only burns quota. Fail fast
-        // and surface the truthful upstream error instead of the misleading
-        // "all accounts rate-limited" after 44 wasted attempts.
+        // and return a non-retryable request error instead of prompting the client
+        // to repeat the same malformed request as a genuine rate limit.
         if (isAntiAbuseConstruction429(errRespHeaders, String(lastError))) {
-            logger.always(`[proxy] ← 429 account=${account.label} anti-abuse/construction rejection (no ratelimit headers, body="Error") — NOT a real rate limit; returning upstream error without rotating`);
+            logger.always(`[proxy] ← 429 account=${account.label} anti-abuse/construction rejection (no ratelimit headers, body="Error") — NOT a real rate limit; returning non-retryable request error`);
             logAttempt(429, "construction_rejection", String(lastError));
             tracer?.setError("construction_rejection", String(lastError).slice(0, 500));
             currentUpstreamSpan?.end();
-            const passthrough = new Response(String(lastError), {
-                status: 429,
-                headers: {
-                    "content-type": errRespHeaders["content-type"] ?? "application/json",
-                },
-            });
             return {
                 continueLoop: false,
-                response: passthrough,
+                terminalError: buildAnthropicConstructionRejectionTerminalError(),
                 lastError,
                 sawRateLimit,
                 sawNetworkError,
                 upstreamSpan: undefined,
             };
         }
+        sawRateLimit = true;
+        recordAttemptError(account.label, account.type, 429);
         // Parse the unified-window quota headers (present on real rate-limit 429s)
         // and derive a reset-aware cooldown plan. This is the fix for "kept
         // hammering the 5h/7d-exhausted account instead of switching": on an
@@ -3468,6 +3717,9 @@ async function fetchAnthropicAccountResponse(args) {
         upstreamSpan: currentUpstreamSpan,
     };
 }
+function shouldAttemptClaudeFallback(loopState) {
+    return loopState.invalidRequestFailure === null;
+}
 async function handleAnthropicRoutedClaudeRequest(args) {
     const { ctx, body, modelRouter, tracer, requestStartTime, accountStrategy, buildLoggedClaudeError, logProxyBody, logFinalRequest, } = args;
     const parsedRequest = parseClaudeRequest(body);
@@ -3507,7 +3759,16 @@ async function handleAnthropicRoutedClaudeRequest(args) {
     // is cooling, report the earliest persisted retry time without an upstream
     // call; restarting the proxy must not erase or bypass this quarantine.
     const nonCoolingAccounts = orderedAccounts.filter((a) => !isAccountCooling(a.key));
-    const effectiveAccounts = nonCoolingAccounts;
+    let effectiveAccounts = nonCoolingAccounts;
+    // If every usable account is cooling and the soonest recovery is a short
+    // transient burst cooldown, hold this request and pace its admission instead
+    // of returning a proxy-local 429 that makes the client retry in a herd. The
+    // helper rechecks because an in-flight retry can extend the cooldown while
+    // this request is waiting.
+    if (effectiveAccounts.length === 0) {
+        effectiveAccounts =
+            await waitForTransientAccountAvailability(orderedAccounts);
+    }
     if (effectiveAccounts.length === 0 && orderedAccounts.length > 0) {
         const coolingStates = orderedAccounts.map((account) => getOrCreateRuntimeState(account.key));
         const hasRateLimitCooldown = coolingStates.some((state) => state.coolingReason !== "auth");
@@ -3590,6 +3851,17 @@ async function handleAnthropicRoutedClaudeRequest(args) {
             loopState.lastError = fetchResult.lastError;
             loopState.sawRateLimit = fetchResult.sawRateLimit;
             loopState.sawNetworkError = fetchResult.sawNetworkError;
+            if (fetchResult.terminalError) {
+                return finalizeAnthropicTerminalFetchError({
+                    terminalError: fetchResult.terminalError,
+                    account,
+                    tracer,
+                    requestStartTime,
+                    attemptNumber: loopState.attemptNumber,
+                    logProxyBody,
+                    logFinalRequest,
+                });
+            }
             if (fetchResult.continueLoop || !fetchResult.response) {
                 // Genuine 429 (carries a cooldown plan derived from quota headers).
                 if (fetchResult.cooldownPlan) {
@@ -3601,32 +3873,41 @@ async function handleAnthropicRoutedClaudeRequest(args) {
                             // Non-fatal: routing already has the in-memory snapshot.
                         });
                     }
-                    // Transient burst (window still allowed): a couple of jittered
-                    // same-account retries before giving up. Exhaustion plans set
-                    // rotateImmediately, so retrySameAccount is false and we skip this.
+                    // Publish the cooldown before retrying so requests arriving behind
+                    // this one skip the throttled account instead of joining the burst.
+                    let cooldownExtended = false;
+                    if (!accountState.coolingUntil ||
+                        plan.coolingUntil > accountState.coolingUntil) {
+                        accountState.coolingUntil = plan.coolingUntil;
+                        accountState.coolingReason = plan.reason;
+                        cooldownExtended = true;
+                    }
+                    if (cooldownExtended) {
+                        await saveAccountCooldown(account.key, accountState.coolingUntil, accountState.coolingReason ?? plan.reason).catch(() => {
+                            // Non-fatal: routing already has the in-memory cooldown.
+                        });
+                    }
+                    // Transient retries are budgeted across all concurrent requests for
+                    // this account/window. Exhaustion plans rotate immediately and never
+                    // claim this budget.
+                    const sharedRetrySlot = fetchResult.retrySameAccount
+                        ? claimTransientRateLimitRetry(account.key, plan.coolingUntil)
+                        : undefined;
                     if (fetchResult.retrySameAccount &&
                         fetchResult.retryAfterMs !== undefined &&
-                        rateLimitSameAccountRetries < MAX_RATE_LIMIT_SAME_ACCOUNT_RETRIES) {
+                        rateLimitSameAccountRetries < MAX_RATE_LIMIT_SAME_ACCOUNT_RETRIES &&
+                        sharedRetrySlot !== undefined) {
                         rateLimitSameAccountRetries += 1;
                         const base = Math.min(fetchResult.retryAfterMs || 1_000, MAX_RATE_LIMIT_RETRY_DELAY_MS);
-                        // Cap AFTER jitter so the final sleep never exceeds the cap.
-                        const delayMs = Math.min(MAX_RATE_LIMIT_RETRY_DELAY_MS, jitteredDelay(base));
-                        logger.always(`[proxy] retrying same account=${account.label} after transient 429 (${rateLimitSameAccountRetries}/${MAX_RATE_LIMIT_SAME_ACCOUNT_RETRIES}) in ${delayMs}ms`);
+                        // Stagger the two shared slots, then cap after jitter so the final
+                        // sleep never exceeds the configured maximum.
+                        const delayMs = Math.min(MAX_RATE_LIMIT_RETRY_DELAY_MS, jitteredDelay(base * sharedRetrySlot));
+                        logger.always(`[proxy] retrying same account=${account.label} after transient 429 (shared slot ${sharedRetrySlot}/${MAX_RATE_LIMIT_SAME_ACCOUNT_RETRIES}) in ${delayMs}ms`);
                         await sleep(delayMs);
                         continue;
                     }
-                    // Exhaustion, or transient retries used up: park the account until
-                    // its ACTUAL reset (5h/7d) — no 60s hardcap — and rotate. Extend-only
-                    // so a concurrent short transient plan can't shorten a longer weekly
-                    // cooldown already set by another in-flight request.
-                    if (!accountState.coolingUntil ||
-                        plan.coolingUntil > accountState.coolingUntil) {
-                        accountState.coolingUntil = plan.coolingUntil;
-                        accountState.coolingReason = plan.reason;
-                    }
-                    await saveAccountCooldown(account.key, accountState.coolingUntil ?? plan.coolingUntil, accountState.coolingReason ?? plan.reason).catch(() => {
-                        // Non-fatal: routing already has the in-memory cooldown.
-                    });
+                    // Exhaustion, or the shared transient retry budget being used up:
+                    // rotate while the already-published cooldown remains active.
                     advancePrimaryIfCurrent(account.key, enabledAccounts.length, orderedAccounts[0]?.key);
                     logger.always(`[proxy] account=${account.label} rate-limited (${plan.reason}); cooling ~${minutesUntil(plan.coolingUntil, Date.now())}m until ${new Date(plan.coolingUntil).toISOString()}, rotating`);
                     continue accountLoop;
@@ -3768,33 +4049,43 @@ async function handleAnthropicRoutedClaudeRequest(args) {
     if (loopState.attemptNumber === 0) {
         acctSelectionSpan?.end();
     }
-    const configuredFallbackResult = await tryConfiguredClaudeFallbackChain({
-        ctx,
-        body,
-        parsedFallbackRequest: parsedRequest,
-        modelRouter,
-        tracer,
-        requestStartTime,
-        logProxyBody,
-        logFinalRequest,
-    });
-    if (configuredFallbackResult.response) {
-        return configuredFallbackResult.response;
-    }
-    // Try auto-provider fallback when the configured chain didn't produce a
-    // response (either no chain configured, or all entries failed/deduped).
-    if (!loopState.sawRateLimit) {
-        const autoFallbackResponse = await tryAutoClaudeFallback({
+    // Deterministic invalid requests (for example, prompt-too-long) cannot be
+    // repaired by changing providers. Preserve the authoritative Anthropic 400
+    // rather than delaying it or returning unrelated fallback output.
+    if (shouldAttemptClaudeFallback(loopState)) {
+        let fallbackFailureMessage;
+        const configuredFallbackResult = await tryConfiguredClaudeFallbackChain({
             ctx,
             body,
+            parsedFallbackRequest: parsedRequest,
+            modelRouter,
             tracer,
             requestStartTime,
             logProxyBody,
             logFinalRequest,
         });
-        if (autoFallbackResponse) {
-            return autoFallbackResponse;
+        if (configuredFallbackResult.response) {
+            return configuredFallbackResult.response;
         }
+        fallbackFailureMessage = configuredFallbackResult.lastErrorMessage;
+        // Try auto-provider fallback when the configured chain didn't produce a
+        // response (either no chain configured, or all entries failed/deduped).
+        if (!loopState.sawRateLimit) {
+            const autoFallbackResult = await tryAutoClaudeFallback({
+                ctx,
+                body,
+                tracer,
+                requestStartTime,
+                logProxyBody,
+                logFinalRequest,
+            });
+            if (autoFallbackResult.response) {
+                return autoFallbackResult.response;
+            }
+            fallbackFailureMessage =
+                autoFallbackResult.lastErrorMessage ?? fallbackFailureMessage;
+        }
+        loopState.fallbackFailureMessage = fallbackFailureMessage;
     }
     return buildClaudeAnthropicFailureResponse({
         tracer,
@@ -3806,6 +4097,7 @@ async function handleAnthropicRoutedClaudeRequest(args) {
         sawTransientFailure: loopState.sawTransientFailure,
         sawRateLimit: loopState.sawRateLimit,
         lastError: loopState.lastError,
+        fallbackFailureMessage: loopState.fallbackFailureMessage,
         orderedAccounts,
         buildLoggedClaudeError,
         logProxyBody,
@@ -4077,6 +4369,26 @@ function getErrorCode(error) {
     const causeCode = cause.code;
     return typeof causeCode === "string" ? causeCode : undefined;
 }
+function describeTransportError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (!error || typeof error !== "object") {
+        return message;
+    }
+    const cause = error.cause;
+    const causeMessage = cause instanceof Error
+        ? cause.message
+        : cause && typeof cause === "object"
+            ? String(cause.message ?? "")
+            : "";
+    const code = getErrorCode(error);
+    const detail = [
+        code,
+        causeMessage && causeMessage !== message && causeMessage,
+    ]
+        .filter(Boolean)
+        .join(": ");
+    return detail ? `${message} (${detail})` : message;
+}
 /**
  * Determine whether a thrown fetch error is a transient connectivity issue.
  */
@@ -4111,6 +4423,7 @@ function isRetryableNetworkError(error) {
     return (normalized.includes("econnrefused") ||
         normalized.includes("econnreset") ||
         normalized.includes("etimedout") ||
+        normalized.includes("timed out") ||
         normalized.includes("connection error") ||
         normalized.includes("connect error") ||
         normalized.includes("fetch failed") ||
@@ -4236,9 +4549,24 @@ export const __testHooks = {
     },
     resetAllRuntimeState: () => {
         accountRuntimeState.clear();
+        transientRateLimitRetryBudgets.clear();
+        transientCooldownAdmissionSchedules.clear();
         primaryAccountIndex = 0;
         lastKnownAccountCount = 0;
         configuredPrimaryAccountKey = undefined;
         configuredAccountAllowlist = undefined;
     },
+    polyfillOAuthBody: (bodyStr, isClaudeClientRequest) => polyfillOAuthBody(bodyStr, "test-account-token", null, isClaudeClientRequest),
+    isAntiAbuseConstruction429,
+    fetchAnthropicAccountResponse,
+    finalizeAnthropicTerminalFetchError,
+    handleAnthropicAuthRetry,
+    handleAnthropicStreamingSuccessResponse,
+    claimTransientRateLimitRetry,
+    claimTransientCooldownAdmission,
+    waitForTransientAccountAvailability,
+    describeTransportError,
+    shouldAttemptClaudeFallback,
+    executeClaudeFallbackWithRetry,
+    buildClaudeAnthropicFailureResponse,
 };