@juspay/neurolink 10.12.7 → 10.12.8

package/dist/lib/server/routes/claudeProxyRoutes.js

@@ -18,6 +18,8 @@ import { clearAccountCooldown, loadAccountCooldowns, saveAccountCooldown, } from
 import { anthropicAccountKeysEqual, ENV_ANTHROPIC_ACCOUNT_KEY, isAccountAllowed, LEGACY_ANTHROPIC_ACCOUNT_KEY, shouldLoadFallbackCredential, } from "../../proxy/accountSelection.js";
 import { getUnifiedRateLimitStatus, isQuotaOverageAvailable, loadAccountQuotas, parseQuotaHeaders, saveAccountQuota, } from "../../proxy/accountQuota.js";
 import { fetchAccountUsage, listAnthropicAccountsForUsage, usageToQuota, } from "../../proxy/accountUsage.js";
+import { AccountQuotaRefreshCoordinator } from "../../proxy/accountQuotaRefreshCoordinator.js";
+import { ProviderTransportCoordinator } from "../../proxy/providerTransportCoordinator.js";
 import { buildProxyLimitHeaders, summarizePoolHeadroom, } from "../../proxy/quotaHeaders.js";
 import { buildClaudeError, ClaudeStreamSerializer, generateToolUseId, parseClaudeRequest, serializeClaudeResponse, } from "../../proxy/claudeFormat.js";
 import { buildAnthropicModelsListResponse, buildTranslationOptions, extractText, extractToolArgs, extractUsageFromStreamResult, handleTranslatedJsonRequest, handleTranslatedStreamRequest, hasTranslatedOutput, } from "../../proxy/proxyTranslationEngine.js";
@@ -111,8 +113,11 @@ function fetchAnthropicUpstream(url, init) {
     });
 }
 const accountRuntimeState = new Map();
-/** Persisted quota is advisory after a restart. Older snapshots cannot reject
- * an account or create a new cooldown because the provider may have reset it. */
+const accountQuotaRefreshCoordinator = new AccountQuotaRefreshCoordinator();
+const providerTransportCoordinator = new ProviderTransportCoordinator();
+/** Snapshot age is diagnostic and controls lightweight refresh eligibility. It
+ * must never discard known healthy routing evidence or trigger a user request
+ * on another account solely to rediscover quota. */
 const QUOTA_SNAPSHOT_FRESHNESS_MS = 15 * 60 * 1000;
 /** 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. */
@@ -646,6 +651,65 @@ const MIN_USAGE_REFETCH_INTERVAL_MS = 15_000;
 const lastUsageFetchAt = new Map();
 let limitsRefreshInFlight = null;
 const USAGE_REFRESH_CONCURRENCY = 4;
+async function applyAccountUsageResult(account, fetchResult, observedAt, prior) {
+    if (fetchResult.ok === false) {
+        return null;
+    }
+    const state = getOrCreateRuntimeState(account.key);
+    const quota = usageToQuota(fetchResult.usage, {
+        now: observedAt,
+        prior: state.quota ?? prior ?? null,
+    });
+    if (!quota) {
+        return null;
+    }
+    // The usage payload cannot be newer than the request that fetched it. A
+    // passive response captured after that request started wins, including its
+    // cooldown decision and persisted snapshot.
+    if (quota.lastUpdated < (state.quota?.lastUpdated ?? 0)) {
+        return state.quota ?? null;
+    }
+    state.quota = quota;
+    const cooldownUpdate = reconcileCooldownFromQuota(state, quota, Date.now());
+    if (cooldownUpdate?.kind === "cooled") {
+        await saveAccountCooldown(account.key, cooldownUpdate.coolingUntil, cooldownUpdate.coolingReason).catch(() => {
+            // Non-fatal: the cooldown is already active in memory.
+        });
+    }
+    else if (cooldownUpdate?.kind === "cleared") {
+        await clearAccountCooldown(account.key, cooldownUpdate.coolingUntil).catch(() => {
+            // Non-fatal: the next successful response will reconcile again.
+        });
+    }
+    await saveAccountQuota(account.label, quota).catch(() => {
+        // Non-fatal: quota persistence is best-effort.
+    });
+    return quota;
+}
+async function fetchValidatedAccountUsage(account) {
+    const result = await fetchAccountUsage(account);
+    if (result.ok === false) {
+        return result;
+    }
+    const recognizable = usageToQuota(result.usage, {
+        now: Date.now(),
+        prior: accountRuntimeState.get(account.key)?.quota ?? null,
+    });
+    return recognizable
+        ? result
+        : {
+            ok: false,
+            reason: "parse",
+            error: "usage payload had no recognizable limit windows",
+        };
+}
+async function refreshAccountQuotaInBackground(account, trigger) {
+    const refresh = await accountQuotaRefreshCoordinator.run(account, trigger, fetchValidatedAccountUsage);
+    if (refresh.kind !== "completed" || refresh.result.ok === false) {
+        return;
+    }
+    await applyAccountUsageResult(account, refresh.result, refresh.startedAt);
+}
 /**
  * Fetch fresh limits from Anthropic's usage endpoint for every eligible OAuth
  * account and write them through the exact same chain the passive header
@@ -686,6 +750,7 @@ async function refreshAccountLimits(options = {}) {
             fetchedAt,
             snapshot: true,
             results: accounts.map((account) => buildResult(account, "snapshot", null)),
+            refreshMetrics: accountQuotaRefreshCoordinator.getMetrics(),
         };
     }
     const results = new Array(accounts.length);
@@ -710,7 +775,12 @@ async function refreshAccountLimits(options = {}) {
             // Isolate failures per account: an unexpected rejection must not abort
             // the Promise.all sweep and turn the whole /limits response into a 502.
             try {
-                const fetchResult = await fetchAccountUsage(account);
+                const refresh = await accountQuotaRefreshCoordinator.run(account, `manual:${account.key}`, fetchValidatedAccountUsage, { force: true });
+                if (refresh.kind !== "completed") {
+                    results[index] = buildResult(account, "throttled", null);
+                    continue;
+                }
+                const fetchResult = refresh.result;
                 // `=== false` (not `!ok`) — the react-hooks sub-build compiles this
                 // file without strictNullChecks, where negated boolean-discriminant
                 // narrowing does not apply.
@@ -718,35 +788,11 @@ async function refreshAccountLimits(options = {}) {
                     results[index] = buildResult(account, "error", null, fetchResult.error);
                     continue;
                 }
-                const state = getOrCreateRuntimeState(account.key);
-                const capturedAt = Date.now();
-                const quota = usageToQuota(fetchResult.usage, {
-                    now: capturedAt,
-                    prior: state.quota ?? persisted[account.label] ?? null,
-                });
+                const quota = await applyAccountUsageResult(account, fetchResult, refresh.startedAt, persisted[account.label] ?? null);
                 if (!quota) {
                     results[index] = buildResult(account, "error", null, "usage payload had no recognizable limit windows");
                     continue;
                 }
-                // Guard against a passive header capture that landed mid-fetch: never
-                // replace a fresher runtime snapshot with an older reading.
-                if (quota.lastUpdated >= (state.quota?.lastUpdated ?? 0)) {
-                    state.quota = quota;
-                }
-                const cooldownUpdate = reconcileCooldownFromQuota(state, quota, capturedAt);
-                if (cooldownUpdate?.kind === "cooled") {
-                    await saveAccountCooldown(account.key, cooldownUpdate.coolingUntil, cooldownUpdate.coolingReason).catch(() => {
-                        // Non-fatal: cooldown is already active in memory.
-                    });
-                }
-                else if (cooldownUpdate?.kind === "cleared") {
-                    await clearAccountCooldown(account.key, cooldownUpdate.coolingUntil).catch(() => {
-                        // Non-fatal: the next successful response will reconcile again.
-                    });
-                }
-                await saveAccountQuota(account.label, quota).catch(() => {
-                    // Non-fatal: quota persistence is best-effort
-                });
                 results[index] = buildResult(account, "refreshed", quota);
             }
             catch (err) {
@@ -755,7 +801,12 @@ async function refreshAccountLimits(options = {}) {
         }
     };
     await Promise.all(Array.from({ length: Math.min(USAGE_REFRESH_CONCURRENCY, accounts.length || 1) }, () => worker()));
-    return { fetchedAt, snapshot: false, results };
+    return {
+        fetchedAt,
+        snapshot: false,
+        results,
+        refreshMetrics: accountQuotaRefreshCoordinator.getMetrics(),
+    };
 }
 /** Quota-aware selection is on by default; disable with
  *  NEUROLINK_PROXY_QUOTA_ROUTING=off|false|0. Only affects the fill-first
@@ -800,8 +851,30 @@ function accountSortMetrics(accountKey, now, sessionSoftLimit, sessionResetToler
     const q = st?.quota;
     const quotaLastUpdated = q && Number.isFinite(q.lastUpdated) ? q.lastUpdated : null;
     const quotaAgeMs = quotaLastUpdated === null ? null : Math.max(0, now - quotaLastUpdated);
+    const refreshState = accountQuotaRefreshCoordinator.getState(accountKey);
     const quotaStale = quotaAgeMs !== null && quotaAgeMs > QUOTA_SNAPSHOT_FRESHNESS_MS;
-    const routingQuota = quotaStale ? undefined : q;
+    const normalizeStatus = (status) => status.trim().toLowerCase();
+    const rawOverageEligible = isQuotaOverageAvailable(q);
+    const observedStatuses = [
+        q?.unifiedStatus,
+        q?.sessionStatus,
+        q?.weeklyStatus,
+    ].filter((status) => !!status?.trim());
+    const staleHardOrAmbiguous = quotaStale &&
+        !!q &&
+        !rawOverageEligible &&
+        observedStatuses.some((status) => normalizeStatus(status) !== "allowed");
+    const quotaFreshness = !q
+        ? "unknown"
+        : !quotaStale
+            ? "fresh"
+            : staleHardOrAmbiguous
+                ? "refresh_due"
+                : "stale_known";
+    // A stale rejection is advisory after restart and cannot quarantine an
+    // account. Keep it as evidence, rank it behind known-healthy accounts, and
+    // refresh it through the usage endpoint before relying on the old status.
+    const routingQuota = staleHardOrAmbiguous ? undefined : q;
     const coolingActive = !!st?.coolingUntil && now < st.coolingUntil;
     // resetEpochToMs returns undefined for absent OR passed resets, so a
     // ticking window is exactly "reset !== undefined".
@@ -830,17 +903,46 @@ function accountSortMetrics(accountKey, now, sessionSoftLimit, sessionResetToler
             : "allowed"
         : null;
     const overageEligible = isQuotaOverageAvailable(routingQuota);
-    const saturated = sessionStatus === "throttled" ||
-        (sessionTicking && (sessionUsed ?? 0) >= sessionSoftLimit);
+    const hardSaturated = !overageEligible &&
+        (sessionStatus === "rejected" ||
+            sessionStatus === "throttled" ||
+            weeklyStatus === "rejected" ||
+            weeklyStatus === "throttled" ||
+            routingQuota?.unifiedStatus?.trim().toLowerCase() === "rejected" ||
+            (sessionTicking && (sessionUsed ?? 0) >= 1) ||
+            (weeklyTicking && (weeklyUsed ?? 0) >= 1));
+    const softSaturated = !hardSaturated &&
+        !overageEligible &&
+        sessionTicking &&
+        (sessionUsed ?? 0) >= sessionSoftLimit;
+    const saturated = hardSaturated || softSaturated;
     return {
-        usable: !coolingActive &&
-            weeklyStatus !== "rejected" &&
-            (sessionStatus !== "rejected" || overageEligible) &&
-            (routingQuota?.unifiedStatus?.trim().toLowerCase() !== "rejected" ||
-                overageEligible),
-        saturated: !quotaStale && saturated,
-        hasQuota: !!routingQuota,
+        usable: !coolingActive && !hardSaturated,
+        saturated,
+        hasQuota: !!q,
+        quotaEvidenceRank: quotaFreshness === "fresh" || quotaFreshness === "stale_known"
+            ? 0
+            : quotaFreshness === "refresh_due"
+                ? 1
+                : 2,
         quotaStale,
+        quotaFreshness,
+        refreshNeeded: quotaFreshness === "unknown" || quotaFreshness === "refresh_due",
+        refreshReason: quotaFreshness === "unknown"
+            ? "startup_unknown"
+            : quotaFreshness === "refresh_due"
+                ? "ambiguous_snapshot"
+                : null,
+        refreshInFlight: refreshState.inFlight,
+        lastRefreshAttemptAt: refreshState.lastAttemptAt ?? null,
+        lastRefreshSuccessAt: refreshState.lastSuccessAt ?? null,
+        nextRefreshEligibleAt: refreshState.nextEligibleAt ?? null,
+        saturationKind: hardSaturated ? "hard" : softSaturated ? "soft" : "none",
+        softLimitOverrideReason: overageEligible &&
+            sessionTicking &&
+            (sessionUsed ?? 0) >= sessionSoftLimit
+            ? "overage"
+            : null,
         quotaLastUpdated,
         quotaAgeMs,
         coolingActive,
@@ -880,8 +982,8 @@ function compareAccountRoutingFactors(a, b, metricsByKey, primaryKey) {
             au === bu ? "insertion_order" : "cooldown_recovery",
         ];
     }
-    if (ma.hasQuota !== mb.hasQuota) {
-        return [ma.hasQuota ? 1 : -1, "quota_probe"];
+    if (ma.quotaEvidenceRank !== mb.quotaEvidenceRank) {
+        return [ma.quotaEvidenceRank - mb.quotaEvidenceRank, "quota_evidence"];
     }
     if (ma.saturated !== mb.saturated) {
         return [ma.saturated ? 1 : -1, "session_headroom"];
@@ -928,9 +1030,8 @@ function orderAccountsByQuotaWithMetrics(accounts, now, primaryKey, sessionSoftL
  * temporarily demoted until that session 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.)
+ *   1. known healthy quota before unknown or ambiguous stale evidence. Quota
+ *      discovery is handled by a lightweight usage GET, never a user request.
  *   2. session headroom before session-saturated (>= soft limit or
  *      "throttled") — do not re-hammer an urgent weekly account while its 5h
  *      capacity is temporarily unavailable.
@@ -948,6 +1049,62 @@ function orderAccountsByQuotaWithMetrics(accounts, now, primaryKey, sessionSoftL
 function orderAccountsByQuota(accounts, now, primaryKey, sessionSoftLimit = getSessionSoftLimit(), sessionResetToleranceMs = getSessionResetToleranceMs()) {
     return orderAccountsByQuotaWithMetrics(accounts, now, primaryKey, sessionSoftLimit, sessionResetToleranceMs).orderedAccounts;
 }
+function scheduleAdaptiveQuotaRefreshes(accounts, orderedAccounts, sessionSoftLimit, routingMetrics) {
+    for (const account of accounts) {
+        if (account.type !== "oauth") {
+            continue;
+        }
+        const metrics = routingMetrics?.get(account.key) ??
+            accountSortMetrics(account.key, Date.now(), sessionSoftLimit, getSessionResetToleranceMs());
+        if (metrics.quotaFreshness === "unknown") {
+            void refreshAccountQuotaInBackground(account, `startup-unknown:${account.key}`).catch((error) => {
+                logger.debug(`[proxy] background quota discovery failed account=${account.label}: ${describeTransportError(error)}`);
+            });
+        }
+        else if (metrics.quotaFreshness === "refresh_due") {
+            void refreshAccountQuotaInBackground(account, `ambiguous:${metrics.quotaLastUpdated ?? 0}`).catch((error) => {
+                logger.debug(`[proxy] ambiguous quota refresh failed account=${account.label}: ${describeTransportError(error)}`);
+            });
+        }
+    }
+    const active = orderedAccounts[0];
+    const candidate = orderedAccounts[1];
+    if (!active || !candidate || candidate.type !== "oauth") {
+        return;
+    }
+    const activeQuota = accountRuntimeState.get(active.key)?.quota;
+    if (!activeQuota) {
+        return;
+    }
+    const sessionPrewarmAt = Math.max(0, sessionSoftLimit - 0.05);
+    const needsPrewarm = (activeQuota.sessionUsed ?? 0) >= sessionPrewarmAt ||
+        (activeQuota.weeklyUsed ?? 0) >= 0.9;
+    if (!needsPrewarm) {
+        return;
+    }
+    const trigger = [
+        "handoff",
+        active.key,
+        activeQuota.sessionResetAt ?? 0,
+        activeQuota.weeklyResetAt ?? 0,
+        candidate.key,
+    ].join(":");
+    void refreshAccountQuotaInBackground(candidate, trigger).catch((error) => {
+        logger.debug(`[proxy] quota handoff prewarm failed account=${candidate.label}: ${describeTransportError(error)}`);
+    });
+}
+function scheduleHandoffQuotaRefresh(current, candidate, handoffEpoch, sessionSoftLimit) {
+    if (!candidate || candidate.type !== "oauth") {
+        return;
+    }
+    const metrics = accountSortMetrics(candidate.key, Date.now(), sessionSoftLimit, getSessionResetToleranceMs());
+    if (metrics.quotaFreshness === "fresh") {
+        return;
+    }
+    void refreshAccountQuotaInBackground(candidate, `hard-handoff:${current.key}:${handoffEpoch}:${candidate.key}`).catch((error) => {
+        logger.debug(`[proxy] hard-handoff quota refresh failed account=${candidate.label}: ${describeTransportError(error)}`);
+    });
+}
 function buildRoutingDecision(args) {
     const { accounts, orderedAccounts, metricsByKey, evaluatedAt, strategy, primaryKey, quotaRoutingEnabled, quotaOrdered, sessionSoftLimit, sessionResetToleranceMs, rotationOffset, } = args;
     const sourceIndexes = new Map(accounts.map((account, index) => [account.key, index]));
@@ -969,6 +1126,15 @@ function buildRoutingDecision(args) {
             saturated: metrics.saturated,
             quotaObserved: metrics.hasQuota,
             quotaStale: metrics.quotaStale,
+            quotaFreshness: metrics.quotaFreshness,
+            refreshNeeded: metrics.refreshNeeded,
+            refreshReason: metrics.refreshReason,
+            refreshInFlight: metrics.refreshInFlight,
+            lastRefreshAttemptAt: metrics.lastRefreshAttemptAt,
+            lastRefreshSuccessAt: metrics.lastRefreshSuccessAt,
+            nextRefreshEligibleAt: metrics.nextRefreshEligibleAt,
+            saturationKind: metrics.saturationKind,
+            softLimitOverrideReason: metrics.softLimitOverrideReason,
             quotaLastUpdated: metrics.quotaLastUpdated,
             quotaAgeMs: metrics.quotaAgeMs,
             coolingActive: metrics.coolingActive,
@@ -1096,7 +1262,7 @@ function selectClaudeProxyAccountOrder(args) {
     if (routingDecision) {
         setRoutingDecision(routingDecision);
     }
-    return orderedAccounts;
+    return { orderedAccounts, metricsByKey };
 }
 // ---------------------------------------------------------------------------
 // OAuth polyfill helpers (extracted to reduce block nesting)
@@ -2207,7 +2373,7 @@ async function loadClaudeProxyAccounts(args) {
         tracer?.end(401, Date.now() - requestStartTime);
         return { response: buildLoggedClaudeError(401, reauthMsg) };
     }
-    const orderedAccounts = selectClaudeProxyAccountOrder({
+    const { orderedAccounts, metricsByKey } = selectClaudeProxyAccountOrder({
         enabledAccounts,
         accountStrategy,
         primaryAccountKey,
@@ -2216,6 +2382,11 @@ async function loadClaudeProxyAccounts(args) {
         sessionResetToleranceMs,
         setRoutingDecision,
     });
+    if (accountStrategy === "fill-first" &&
+        quotaRoutingEnabled &&
+        enabledAccounts.length > 1) {
+        scheduleAdaptiveQuotaRefreshes(enabledAccounts, orderedAccounts, sessionSoftLimit, metricsByKey);
+    }
     const normalizedAnthropicBody = normalizeClaudeRequestForAnthropic(body);
     const bodyStr = JSON.stringify(normalizedAnthropicBody);
     const requestStart = Date.now();
@@ -2560,7 +2731,7 @@ async function tryAutoClaudeFallback(args) {
     }
 }
 function buildClaudeAnthropicFailureResponse(args) {
-    const { tracer, requestStartTime, authFailureMessage, authCooldownMessage, invalidRequestFailure, sawNetworkError, sawTransientFailure, sawRateLimit, lastError, fallbackFailureMessage, orderedAccounts, buildLoggedClaudeError, logProxyBody, logFinalRequest, } = args;
+    const { tracer, requestStartTime, authFailureMessage, authCooldownMessage, invalidRequestFailure, sawNetworkError, sawTransientFailure, sawRateLimit, lastError, lastTransportErrorCode, lastTransportScope, fallbackFailureMessage, orderedAccounts, buildLoggedClaudeError, logProxyBody, logFinalRequest, } = args;
     if (authFailureMessage && !sawRateLimit) {
         tracer?.setError("authentication_error", authFailureMessage);
         tracer?.end(401, Date.now() - requestStartTime);
@@ -2598,12 +2769,22 @@ function buildClaudeAnthropicFailureResponse(args) {
         const fallbackSuffix = fallbackFailureMessage
             ? ` Fallback also failed: ${fallbackFailureMessage}`
             : "";
-        const msg = `All Anthropic accounts failed due to transient upstream/network errors. Last error: ${lastError instanceof Error
+        const transportDescription = lastTransportScope === "shared_provider_transport"
+            ? "shared Anthropic network"
+            : lastTransportScope === "connection_transport"
+                ? "Anthropic connection"
+                : null;
+        const msg = `${transportDescription ? `${transportDescription} failure prevented safe cross-account rotation` : "All Anthropic accounts failed due to transient upstream/network errors"}. Last error${lastTransportErrorCode ? ` (${lastTransportErrorCode})` : ""}: ${lastError instanceof Error
             ? lastError.message
             : String(lastError ?? "unknown")}.${fallbackSuffix}`;
         tracer?.setError("transient_error", msg.slice(0, 500));
         tracer?.end(502, Date.now() - requestStartTime);
-        return buildLoggedClaudeError(502, msg, fallbackFailureMessage ? "fallback_exhausted" : "transient_error");
+        return buildLoggedClaudeError(502, msg, fallbackFailureMessage ? "fallback_exhausted" : "transient_error", {
+            ...(lastTransportErrorCode
+                ? { errorCode: lastTransportErrorCode }
+                : {}),
+            ...(lastTransportScope ? { transportScope: lastTransportScope } : {}),
+        });
     }
     if (!sawRateLimit) {
         const fallbackSuffix = fallbackFailureMessage
@@ -4063,6 +4244,7 @@ function createClaudeRequestRuntimeContext(args) {
                         ? "stream_error"
                         : "handler_error",
                 message: errorMessage,
+                errorCode: extra?.errorCode,
             });
         }
         else {
@@ -4083,6 +4265,10 @@ function createClaudeRequestRuntimeContext(args) {
             responseTimeMs: Date.now() - requestStartTime,
             ...(errorType ? { errorType } : {}),
             ...(errorMessage ? { errorMessage } : {}),
+            ...(extra?.errorCode ? { errorCode: extra.errorCode } : {}),
+            ...(extra?.transportScope
+                ? { transportScope: extra.transportScope }
+                : {}),
             ...(extra?.inputTokens !== undefined
                 ? { inputTokens: extra.inputTokens }
                 : {}),
@@ -4104,7 +4290,7 @@ function createClaudeRequestRuntimeContext(args) {
     const buildLoggedClaudeError = (status, message, errorType, extra) => {
         const errorBody = buildClaudeError(status, message, errorType);
         const errorBodyText = JSON.stringify(errorBody);
-        logFinalRequest(status, extra?.account ?? "", extra?.accountType ?? "final", errorType, message);
+        logFinalRequest(status, extra?.account ?? "", extra?.accountType ?? "final", errorType, message, extra);
         logProxyBody({
             phase: "client_response",
             headers: { "content-type": "application/json" },
@@ -4156,6 +4342,9 @@ function createAnthropicAttemptLogger(args) {
             ...(errorType ? { errorType } : {}),
             ...(errorMessage ? { errorMessage } : {}),
             ...(extra?.errorCode ? { errorCode: extra.errorCode } : {}),
+            ...(extra?.transportScope
+                ? { transportScope: extra.transportScope }
+                : {}),
             ...(extra?.inputTokens !== undefined
                 ? { inputTokens: extra.inputTokens }
                 : {}),
@@ -4372,6 +4561,7 @@ async function fetchAnthropicAccountResponse(args) {
     }
     catch (fetchErr) {
         const retryable = isRetryableNetworkError(fetchErr);
+        const transportScope = classifyNetworkTransportScope(fetchErr);
         // Every dispatched upstream request is an attempt, including terminal
         // transport failures. Record it once before preserving the throw behavior.
         sawNetworkError = true;
@@ -4383,6 +4573,7 @@ async function fetchAnthropicAccountResponse(args) {
         logAttempt(502, "network_error", errorMessage, {
             retryable,
             errorCode,
+            transportScope,
         });
         tracer?.setError("network_error", errorMessage);
         if (retryable) {
@@ -4395,6 +4586,8 @@ async function fetchAnthropicAccountResponse(args) {
         return {
             continueLoop: true,
             retrySameAccount: true,
+            transportScope,
+            errorCode,
             lastError,
             sawRateLimit,
             sawNetworkError,
@@ -4572,6 +4765,15 @@ async function handleAnthropicRoutedClaudeRequest(args) {
         let transientSameAccountRetries = 0;
         let rateLimitSameAccountRetries = 0;
         while (true) {
+            const transportPermit = await providerTransportCoordinator.acquire(ctx.abortSignal);
+            if (transportPermit.allowed === false) {
+                loopState.sawNetworkError = true;
+                loopState.lastTransportErrorCode =
+                    transportPermit.errorCode ?? undefined;
+                loopState.lastTransportScope = transportPermit.transportScope;
+                loopState.lastError = `Anthropic transport recovery probe failed (${transportPermit.errorCode ?? "unknown"})`;
+                break accountLoop;
+            }
             loopState.attemptNumber += 1;
             if (tracer && loopState.attemptNumber === 1 && acctSelectionSpan) {
                 tracer.setAccountSelection({
@@ -4613,6 +4815,9 @@ async function handleAnthropicRoutedClaudeRequest(args) {
                 !preparedAttempt.buildUpstreamBody ||
                 !preparedAttempt.finalBodyStr ||
                 preparedAttempt.fetchStartMs === undefined) {
+                if (transportPermit.probe) {
+                    providerTransportCoordinator.reportProbeAbandoned(transportPermit);
+                }
                 continue accountLoop;
             }
             let admissionLease;
@@ -4632,31 +4837,53 @@ async function handleAnthropicRoutedClaudeRequest(args) {
             if (!admissionLease) {
                 // A later account may be immediately available. Preserve the routing
                 // order but do not leave a request queued behind a busy first choice.
+                if (transportPermit.probe) {
+                    providerTransportCoordinator.reportProbeAbandoned(transportPermit);
+                }
                 continue accountLoop;
             }
             let admissionTransferredToStream = false;
             try {
-                const fetchResult = await fetchAnthropicAccountResponse({
-                    url,
-                    headers: preparedAttempt.headers,
-                    finalBodyStr: preparedAttempt.finalBodyStr,
-                    account,
-                    accountState,
-                    enabledAccounts,
-                    orderedAccounts,
-                    tracer,
-                    logAttempt,
-                    logProxyBody,
-                    fetchStartMs: preparedAttempt.fetchStartMs,
-                    attemptNumber: loopState.attemptNumber,
-                    currentLastError: loopState.lastError,
-                    currentSawRateLimit: loopState.sawRateLimit,
-                    currentSawNetworkError: loopState.sawNetworkError,
-                    upstreamSpan: preparedAttempt.upstreamSpan,
-                });
+                let fetchResult;
+                try {
+                    fetchResult = await fetchAnthropicAccountResponse({
+                        url,
+                        headers: preparedAttempt.headers,
+                        finalBodyStr: preparedAttempt.finalBodyStr,
+                        account,
+                        accountState,
+                        enabledAccounts,
+                        orderedAccounts,
+                        tracer,
+                        logAttempt,
+                        logProxyBody,
+                        fetchStartMs: preparedAttempt.fetchStartMs,
+                        attemptNumber: loopState.attemptNumber,
+                        currentLastError: loopState.lastError,
+                        currentSawRateLimit: loopState.sawRateLimit,
+                        currentSawNetworkError: loopState.sawNetworkError,
+                        upstreamSpan: preparedAttempt.upstreamSpan,
+                    });
+                }
+                catch (error) {
+                    if (transportPermit.probe) {
+                        providerTransportCoordinator.reportProbeAbandoned(transportPermit);
+                    }
+                    throw error;
+                }
+                if (fetchResult.transportScope) {
+                    providerTransportCoordinator.reportTransportFailure(fetchResult.errorCode, fetchResult.transportScope, transportPermit);
+                }
+                else {
+                    providerTransportCoordinator.reportSuccess(transportPermit);
+                }
                 loopState.lastError = fetchResult.lastError;
                 loopState.sawRateLimit = fetchResult.sawRateLimit;
                 loopState.sawNetworkError = fetchResult.sawNetworkError;
+                if (fetchResult.transportScope) {
+                    loopState.lastTransportScope = fetchResult.transportScope;
+                    loopState.lastTransportErrorCode = fetchResult.errorCode;
+                }
                 if (fetchResult.terminalError) {
                     return finalizeAnthropicTerminalFetchError({
                         terminalError: fetchResult.terminalError,
@@ -4717,6 +4944,9 @@ async function handleAnthropicRoutedClaudeRequest(args) {
                         // 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`);
+                        if (plan.rotateImmediately) {
+                            scheduleHandoffQuotaRefresh(account, effectiveAccounts[accountIndex + 1], plan.coolingUntil, sessionSoftLimit);
+                        }
                         continue accountLoop;
                     }
                     // Transient error retry (network errors, 529 overloaded)
@@ -4728,9 +4958,13 @@ async function handleAnthropicRoutedClaudeRequest(args) {
                         await sleep(delayMs);
                         continue;
                     }
-                    if (fetchResult.retrySameAccount) {
+                    if (fetchResult.retrySameAccount && !fetchResult.transportScope) {
                         logger.always(`[proxy] exhausted transient same-account retries for account=${account.label}; rotating`);
                     }
+                    if (fetchResult.transportScope) {
+                        logger.always(`[proxy] Anthropic ${fetchResult.transportScope} failure code=${fetchResult.errorCode ?? "unknown"}; suppressing cross-account rotation after ${transientSameAccountRetries + 1} attempts`);
+                        break accountLoop;
+                    }
                     continue accountLoop;
                 }
                 let upstreamSpan = fetchResult.upstreamSpan;
@@ -4955,6 +5189,8 @@ async function handleAnthropicRoutedClaudeRequest(args) {
         sawTransientFailure: loopState.sawTransientFailure,
         sawRateLimit: loopState.sawRateLimit,
         lastError: loopState.lastError,
+        lastTransportErrorCode: loopState.lastTransportErrorCode,
+        lastTransportScope: loopState.lastTransportScope,
         fallbackFailureMessage: loopState.fallbackFailureMessage,
         orderedAccounts,
         buildLoggedClaudeError,
@@ -5406,11 +5642,18 @@ function isRetryableNetworkError(error) {
             // The Anthropic host is fixed, so ENOTFOUND can be a transient resolver
             // outage. Keep it inside the existing bounded same-account retry budget.
             "ENOTFOUND",
+            "EAI_AGAIN",
             "EHOSTUNREACH",
             "UND_ERR_CONNECT_TIMEOUT",
             "UND_ERR_CONNECT",
         ].includes(code));
 }
+function classifyNetworkTransportScope(error) {
+    const code = getErrorCode(error);
+    return code === "ENOTFOUND" || code === "EAI_AGAIN"
+        ? "shared_provider_transport"
+        : "connection_transport";
+}
 const TRANSIENT_HTTP_STATUSES = new Set([
     408, 500, 502, 503, 504, 520, 521, 522, 523, 524, 525, 526, 529,
 ]);
@@ -5540,15 +5783,20 @@ export const __testHooks = {
     planCooldownFor429,
     reconcileCooldownFromQuota,
     refreshAccountLimits,
+    applyAccountUsageResult,
     clearLimitsRefreshStateForTests: () => {
         lastUsageFetchAt.clear();
         limitsRefreshInFlight = null;
+        accountQuotaRefreshCoordinator.clear();
     },
     isRetryableNetworkError,
     isPermanentRefreshFailure,
     getStreamFailureDetails,
     trackUpstreamReadableStream,
     orderAccountsByQuota,
+    scheduleAdaptiveQuotaRefreshes,
+    scheduleHandoffQuotaRefresh,
+    getQuotaRefreshState: (key) => accountQuotaRefreshCoordinator.getState(key),
     buildQuotaRoutingDecision: (accounts, now, primaryKey, sessionSoftLimit = getSessionSoftLimit(), sessionResetToleranceMs = getSessionResetToleranceMs()) => {
         const order = orderAccountsByQuotaWithMetrics(accounts, now, primaryKey, sessionSoftLimit, sessionResetToleranceMs);
         return buildRoutingDecision({
@@ -5587,6 +5835,8 @@ export const __testHooks = {
         transientRateLimitRetryBudgets.clear();
         transientCooldownAdmissionSchedules.clear();
         accountAdmissionStates.clear();
+        accountQuotaRefreshCoordinator.clear();
+        providerTransportCoordinator.clear();
         primaryAccountIndex = 0;
         lastKnownAccountCount = 0;
     },