@juspay/neurolink 10.8.9 → 10.8.11

package/dist/lib/proxy/accountQuota.d.ts

@@ -12,6 +12,14 @@
 import type { AccountQuota } from "../types/index.js";
 /** Read and normalize Anthropic's authoritative top-level unified status. */
 export declare function getUnifiedRateLimitStatus(headers: Headers | Record<string, string>): string | undefined;
+/**
+ * Whether Anthropic explicitly permits a request to use overage after a
+ * subscription window is exhausted. Fresh responses require all three
+ * provider signals. Older persisted snapshots predate the raw fallback and
+ * upgrade-path fields, but retain a positive fallback percentage together with
+ * an allowed overage status, which is the equivalent provider state.
+ */
+export declare function isQuotaOverageAvailable(quota: Pick<AccountQuota, "fallbackPercentage" | "fallbackStatus" | "overageStatus" | "upgradePaths"> | null | undefined): boolean;
 /**
  * Parse Anthropic rate-limit / quota headers into an `AccountQuota`.
  * Returns `null` when key headers are absent.

package/dist/lib/proxy/accountQuota.js

@@ -39,6 +39,27 @@ export function getUnifiedRateLimitStatus(headers) {
     const normalized = value?.trim().toLowerCase();
     return normalized || undefined;
 }
+/**
+ * Whether Anthropic explicitly permits a request to use overage after a
+ * subscription window is exhausted. Fresh responses require all three
+ * provider signals. Older persisted snapshots predate the raw fallback and
+ * upgrade-path fields, but retain a positive fallback percentage together with
+ * an allowed overage status, which is the equivalent provider state.
+ */
+export function isQuotaOverageAvailable(quota) {
+    if (quota?.overageStatus?.trim().toLowerCase() !== "allowed") {
+        return false;
+    }
+    const explicitFallback = quota.fallbackStatus?.trim().toLowerCase();
+    const hasExplicitOveragePath = (quota.upgradePaths ?? "")
+        .split(",")
+        .map((path) => path.trim().toLowerCase())
+        .includes("overage");
+    if (explicitFallback === "available" && hasExplicitOveragePath) {
+        return true;
+    }
+    return explicitFallback === undefined && (quota.fallbackPercentage ?? 0) > 0;
+}
 /**
  * Parse Anthropic rate-limit / quota headers into an `AccountQuota`.
  * Returns `null` when key headers are absent.
@@ -69,6 +90,8 @@ export function parseQuotaHeaders(headers) {
         weeklyStatus: getHeader(headers, `${P}unified-7d-status`) ?? "unknown",
         weeklyResetAt: weeklyResetRaw ? parseInt(weeklyResetRaw, 10) || 0 : 0,
         fallbackPercentage: fallbackRaw ? parseFloat(fallbackRaw) || 0 : 0,
+        fallbackStatus: getHeader(headers, `${P}unified-fallback`) ?? "unknown",
+        upgradePaths: getHeader(headers, `${P}unified-upgrade-paths`),
         overageStatus: getHeader(headers, `${P}unified-overage-status`) ?? "unknown",
         lastUpdated: Date.now(),
     };

package/dist/lib/proxy/proxyAnalysis.js

@@ -87,6 +87,7 @@ function routingCandidateValue(value) {
         "sessionStatus",
         "weeklyStatus",
     ];
+    const optionalNullableStringFields = ["fallbackStatus", "upgradePaths"];
     if (!stringValue(candidate.account) ||
         typeof candidate.accountType !== "string" ||
         !ROUTING_ACCOUNT_TYPES.has(candidate.accountType) ||
@@ -97,6 +98,12 @@ function routingCandidateValue(value) {
         requiredBooleanFields.some((field) => typeof candidate[field] !== "boolean") ||
         requiredNullableNumberFields.some((field) => !isNullableFiniteNumber(candidate[field])) ||
         requiredNullableStringFields.some((field) => !isNullableString(candidate[field])) ||
+        optionalNullableStringFields.some((field) => field in candidate &&
+            candidate[field] !== undefined &&
+            !isNullableString(candidate[field])) ||
+        ("overageEligible" in candidate &&
+            candidate.overageEligible !== undefined &&
+            typeof candidate.overageEligible !== "boolean") ||
         !(candidate.coolingReason === null ||
             (typeof candidate.coolingReason === "string" &&
                 COOLING_REASONS.has(candidate.coolingReason)))) {
@@ -117,6 +124,9 @@ function routingCandidateValue(value) {
         coolingReason: candidate.coolingReason,
         coolingUntil: candidate.coolingUntil,
         unifiedStatus: candidate.unifiedStatus,
+        fallbackStatus: candidate.fallbackStatus,
+        upgradePaths: candidate.upgradePaths,
+        overageEligible: candidate.overageEligible,
         overageStatus: candidate.overageStatus,
         sessionStatus: candidate.sessionStatus,
         sessionUsed: candidate.sessionUsed,

package/dist/lib/server/routes/claudeProxyRoutes.d.ts

@@ -12,7 +12,7 @@
 import { buildTranslationOptions } from "../../proxy/proxyTranslationEngine.js";
 import { ProxyTracer } from "../../proxy/proxyTracer.js";
 import { isPermanentRefreshFailure } from "../../proxy/tokenRefresh.js";
-import type { AccountAllowlist, AccountAdmissionLease, AccountCooldownPlan, AccountQuota, AnthropicAttemptLogger, AnthropicAuthRetryResult, AnthropicLoopState, AnthropicNonOkResult, AnthropicSuccessResult, AnthropicUpstreamFetchResult, ClaudeFinalRequestLogger, ClaudeLoggedErrorBuilder, ClaudeRequest, ClaudeProxyRouteRuntimeOptions, ModelRouterInterface, ParsedClaudeError, ProxyAccountRoutingDecision, ProxyAccountSortMetrics, ProxyBodyCaptureLogger, ProxyPassthroughAccount, RouteGroup, RuntimeAccountState, ServerContext, StreamTerminalOutcome } from "../../types/index.js";
+import type { AccountAllowlist, AccountAdmissionLease, AccountCooldownPlan, AccountQuota, AnthropicAttemptLogger, AnthropicAuthRetryResult, AnthropicLoopState, AnthropicNonOkResult, AnthropicSuccessResult, AnthropicUpstreamFetchResult, ClaudeFinalRequestLogger, ClaudeLoggedErrorBuilder, ClaudeRequest, ClaudeProxyRouteRuntimeOptions, ModelRouterInterface, ParsedClaudeError, ProxyAccountRoutingDecision, ProxyAccountSortMetrics, ProxyBodyCaptureLogger, ProxyQuotaCooldownUpdate, ProxyPassthroughAccount, RouteGroup, RuntimeAccountState, ServerContext, StreamTerminalOutcome } from "../../types/index.js";
 declare function tryAcquireAccountAdmission(accountKey: string, capacity: number): AccountAdmissionLease | undefined;
 declare function acquireAccountAdmission(accountKey: string, capacity: number, abortSignal?: AbortSignal, timeoutMs?: number): Promise<AccountAdmissionLease | undefined>;
 declare function acquireFirstAvailableAccountAdmission(accountKeys: string[], capacity: number, abortSignal?: AbortSignal, timeoutMs?: number): Promise<{
@@ -45,15 +45,23 @@ declare function resetEpochToMs(resetEpoch: number | undefined, now: number): nu
  * The unified subscription limits expose per-window status + reset:
  *   - weekly (7d) "rejected"  → hard cap for the week; cool until the 7d reset.
  *   - session (5h) "rejected" → paced out for this session; cool until the 5h reset.
- * Both mean "retrying this account is futile until its window resets" → rotate
- * immediately (no same-account retries) and park the account until the ACTUAL
- * reset — never the legacy 60s hardcap that let us re-hammer a spent account.
+ * Both mean "retrying this account is futile until its window resets" unless
+ * the provider explicitly enables overage. In that case, the subscription
+ * window is exhausted but the account remains usable for paid fallback.
  *
  * Anything else (window still "allowed" but momentarily 429'd — a per-minute
  * burst / acceleration limit) is transient: honor retry-after as a floor,
  * allow a couple of jittered same-account retries, then a short cooldown.
  */
 declare function planCooldownFor429(quota: AccountQuota | null, retryAfterMs: number, now: number, unifiedStatus?: string | undefined): AccountCooldownPlan;
+/**
+ * Proactively cool an account when a SUCCESS response reveals a window has just
+ * flipped to "rejected" (the boundary request that spends the last of the quota
+ * still returns 200 but reports rejected/next-reset). Parks the account until
+ * its reset so the next request skips it instead of discovering the limit via a
+ * 429, except when the provider explicitly enables paid overage.
+ */
+declare function reconcileCooldownFromQuota(state: RuntimeAccountState, quota: AccountQuota, now: number): ProxyQuotaCooldownUpdate;
 /**
  * Seed each account's runtime quota from the persisted snapshots in
  * ~/.neurolink/account-quotas.json (keyed by label). Runtime state is
@@ -289,6 +297,12 @@ export declare function createClaudeProxyRoutes(modelRouter?: ModelRouterInterfa
 declare function reconcileEligibleAccountRuntimeState(account: ProxyPassthroughAccount): void;
 export declare function getTransientSameAccountRetryDelayMs(retryNumber: number): number;
 declare function describeTransportError(error: unknown): string;
+/**
+ * Determine whether a POST can be retried without risking duplicate provider
+ * work. Only failures that prove connection establishment did not complete are
+ * safe; a reset, socket error, or response timeout can happen after dispatch.
+ */
+declare function isRetryableNetworkError(error: unknown): boolean;
 /**
  * Parse a Claude error payload when available.
  */
@@ -329,6 +343,8 @@ export declare const __testHooks: {
     resolveHomeIndex: typeof resolveHomeIndex;
     maybeResetPrimaryToHome: typeof maybeResetPrimaryToHome;
     planCooldownFor429: typeof planCooldownFor429;
+    reconcileCooldownFromQuota: typeof reconcileCooldownFromQuota;
+    isRetryableNetworkError: typeof isRetryableNetworkError;
     isPermanentRefreshFailure: typeof isPermanentRefreshFailure;
     getStreamFailureDetails: typeof getStreamFailureDetails;
     trackUpstreamReadableStream: typeof trackUpstreamReadableStream;

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

@@ -12,10 +12,11 @@
 import { access, readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { Agent } from "undici";
 import { buildStableClaudeCodeBillingHeader, CLAUDE_CLI_USER_AGENT, CLAUDE_CODE_OAUTH_BETAS, getOrCreateClaudeCodeIdentity, parseClaudeCodeUserId, } from "../../auth/anthropicOAuth.js";
 import { clearAccountCooldown, loadAccountCooldowns, saveAccountCooldown, } from "../../proxy/accountCooldown.js";
 import { anthropicAccountKeysEqual, ENV_ANTHROPIC_ACCOUNT_KEY, isAccountAllowed, LEGACY_ANTHROPIC_ACCOUNT_KEY, shouldLoadFallbackCredential, } from "../../proxy/accountSelection.js";
-import { getUnifiedRateLimitStatus, loadAccountQuotas, parseQuotaHeaders, saveAccountQuota, } from "../../proxy/accountQuota.js";
+import { getUnifiedRateLimitStatus, isQuotaOverageAvailable, loadAccountQuotas, parseQuotaHeaders, saveAccountQuota, } from "../../proxy/accountQuota.js";
 import { buildClaudeError, ClaudeStreamSerializer, generateToolUseId, parseClaudeRequest, serializeClaudeResponse, } from "../../proxy/claudeFormat.js";
 import { buildAnthropicModelsListResponse, buildTranslationOptions, extractText, extractToolArgs, extractUsageFromStreamResult, handleTranslatedJsonRequest, handleTranslatedStreamRequest, hasTranslatedOutput, } from "../../proxy/proxyTranslationEngine.js";
 import { tracers } from "../../telemetry/tracers.js";
@@ -91,6 +92,21 @@ const AUTH_REFRESH_MAX_COOLDOWN_MS = 5 * 60 * 1000;
  *  to cover the full lifecycle of streaming responses, including extended
  *  thinking from Opus models (which can exceed 5 minutes for large contexts). */
 const UPSTREAM_FETCH_TIMEOUT_MS = 15 * 60 * 1000; // 15 minutes
+let anthropicUpstreamDispatcher;
+function fetchAnthropicUpstream(url, init) {
+    // Node's global fetch applies Undici's 300s default headers timeout before
+    // the route's 15-minute abort signal. Keep both transport deadlines aligned
+    // with the proxy contract and instantiate lazily so importing routes has no
+    // open transport handles.
+    anthropicUpstreamDispatcher ??= new Agent({
+        headersTimeout: UPSTREAM_FETCH_TIMEOUT_MS,
+        bodyTimeout: UPSTREAM_FETCH_TIMEOUT_MS,
+    });
+    return fetch(url, {
+        ...init,
+        dispatcher: anthropicUpstreamDispatcher,
+    });
+}
 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. */
@@ -411,9 +427,9 @@ function clampCooldownUntil(untilMs, now) {
  * The unified subscription limits expose per-window status + reset:
  *   - weekly (7d) "rejected"  → hard cap for the week; cool until the 7d reset.
  *   - session (5h) "rejected" → paced out for this session; cool until the 5h reset.
- * Both mean "retrying this account is futile until its window resets" → rotate
- * immediately (no same-account retries) and park the account until the ACTUAL
- * reset — never the legacy 60s hardcap that let us re-hammer a spent account.
+ * Both mean "retrying this account is futile until its window resets" unless
+ * the provider explicitly enables overage. In that case, the subscription
+ * window is exhausted but the account remains usable for paid fallback.
  *
  * Anything else (window still "allowed" but momentarily 429'd — a per-minute
  * burst / acceleration limit) is transient: honor retry-after as a floor,
@@ -430,7 +446,8 @@ function planCooldownFor429(quota, retryAfterMs, now, unifiedStatus = quota?.uni
             rotateImmediately: true,
         };
     }
-    if (quota && quota.sessionStatus === "rejected") {
+    const overageAvailable = isQuotaOverageAvailable(quota);
+    if (quota && quota.sessionStatus === "rejected" && !overageAvailable) {
         const reset = resetEpochToMs(quota.sessionResetAt, now) ??
             (retryAfterMs > 0 ? now + retryAfterMs : now + DEFAULT_COOLING_PERIOD_MS);
         return {
@@ -442,7 +459,7 @@ function planCooldownFor429(quota, retryAfterMs, now, unifiedStatus = quota?.uni
     // Anthropic may reject the authoritative top-level unified limit while both
     // 5h and 7d sub-window statuses still say "allowed". Treating this as a
     // transient burst retries a known-exhausted account and delays failover.
-    if (unifiedStatus?.trim().toLowerCase() === "rejected") {
+    if (unifiedStatus?.trim().toLowerCase() === "rejected" && !overageAvailable) {
         const reset = retryAfterMs > 0 ? now + retryAfterMs : now + DEFAULT_HARD_COOLDOWN_MS;
         return {
             reason: "unified",
@@ -470,34 +487,53 @@ function minutesUntil(untilMs, now) {
  * flipped to "rejected" (the boundary request that spends the last of the quota
  * still returns 200 but reports rejected/next-reset). Parks the account until
  * its reset so the next request skips it instead of discovering the limit via a
- * 429. Never shortens an existing, longer cooldown.
+ * 429, except when the provider explicitly enables paid overage.
  */
-function maybeCoolFromQuota(state, quota, now) {
+function reconcileCooldownFromQuota(state, quota, now) {
+    const overageAvailable = isQuotaOverageAvailable(quota);
     let until;
     let reason;
     if (quota.weeklyStatus === "rejected") {
         until = resetEpochToMs(quota.weeklyResetAt, now);
         reason = "weekly";
     }
-    else if (quota.sessionStatus === "rejected") {
+    if (until === undefined &&
+        overageAvailable &&
+        state.coolingUntil &&
+        (state.coolingReason === "session" || state.coolingReason === "unified")) {
+        const previousCoolingUntil = state.coolingUntil;
+        state.coolingUntil = undefined;
+        state.coolingReason = undefined;
+        logger.always("[proxy] clearing subscription cooldown because Anthropic explicitly permits overage");
+        return { kind: "cleared", coolingUntil: previousCoolingUntil };
+    }
+    if (until === undefined &&
+        quota.sessionStatus === "rejected" &&
+        !overageAvailable) {
         until = resetEpochToMs(quota.sessionResetAt, now);
         reason = "session";
     }
-    else if (quota.unifiedStatus === "rejected") {
+    else if (until === undefined &&
+        quota.unifiedStatus === "rejected" &&
+        !overageAvailable) {
         until = now + DEFAULT_HARD_COOLDOWN_MS;
         reason = "unified";
     }
     if (until === undefined) {
-        return false;
+        return null;
     }
     const clamped = clampCooldownUntil(until, now);
     if (!state.coolingUntil || clamped > state.coolingUntil) {
         state.coolingUntil = clamped;
         state.coolingReason = reason;
         logger.always(`[proxy] proactively cooling account (${reason}) ~${minutesUntil(clamped, now)}m from success-response quota (status rejected)`);
-        return true;
+        return {
+            kind: "cooled",
+            coolingUntil: clamped,
+            coolingReason: reason ?? "unified",
+        };
     }
-    return false;
+    return null;
 }
 /**
  * Seed each account's runtime quota from the persisted snapshots in
@@ -528,6 +564,15 @@ async function seedRuntimeQuotasFromDisk(accounts) {
                 state.coolingUntil = persistedCooldown.coolingUntil;
                 state.coolingReason = persistedCooldown.reason;
             }
+            if (state.quota) {
+                const cooldownUpdate = reconcileCooldownFromQuota(state, state.quota, now);
+                if (cooldownUpdate?.kind === "cooled") {
+                    await saveAccountCooldown(account.key, cooldownUpdate.coolingUntil, cooldownUpdate.coolingReason);
+                }
+                else if (cooldownUpdate?.kind === "cleared") {
+                    await clearAccountCooldown(account.key, cooldownUpdate.coolingUntil);
+                }
+            }
         }
     }
     catch {
@@ -594,13 +639,16 @@ function accountSortMetrics(accountKey, now, sessionSoftLimit, sessionResetToler
             ? (q.weeklyStatus ?? "unknown")
             : "allowed"
         : null;
+    const overageEligible = isQuotaOverageAvailable(q);
     const saturated = sessionStatus === "throttled" ||
         (sessionTicking && (sessionUsed ?? 0) >= sessionSoftLimit);
     const quotaLastUpdated = q && Number.isFinite(q.lastUpdated) ? q.lastUpdated : null;
     return {
         usable: !coolingActive &&
             weeklyStatus !== "rejected" &&
-            sessionStatus !== "rejected",
+            (sessionStatus !== "rejected" || overageEligible) &&
+            (q?.unifiedStatus?.trim().toLowerCase() !== "rejected" ||
+                overageEligible),
         saturated,
         hasQuota: !!q,
         quotaLastUpdated,
@@ -609,6 +657,9 @@ function accountSortMetrics(accountKey, now, sessionSoftLimit, sessionResetToler
         coolingReason: st?.coolingReason ?? null,
         coolingUntil: st?.coolingUntil ?? 0,
         unifiedStatus: q?.unifiedStatus ?? null,
+        fallbackStatus: q?.fallbackStatus ?? null,
+        upgradePaths: q?.upgradePaths ?? null,
+        overageEligible,
         overageStatus: q?.overageStatus ?? null,
         sessionStatus,
         sessionUsed,
@@ -735,6 +786,9 @@ function buildRoutingDecision(args) {
                 ? metrics.coolingUntil
                 : null,
             unifiedStatus: metrics.unifiedStatus,
+            fallbackStatus: metrics.fallbackStatus,
+            upgradePaths: metrics.upgradePaths,
+            overageEligible: metrics.overageEligible,
             overageStatus: metrics.overageStatus,
             sessionStatus: metrics.sessionStatus,
             sessionUsed: metrics.sessionUsed,
@@ -1368,7 +1422,7 @@ async function handleClaudePassthroughRequest(args) {
     recordAttempt("passthrough", "passthrough");
     let response;
     try {
-        response = await fetch("https://api.anthropic.com/v1/messages?beta=true", {
+        response = await fetchAnthropicUpstream("https://api.anthropic.com/v1/messages?beta=true", {
             method: "POST",
             headers: upstreamHeaders,
             body: bodyStr,
@@ -2385,15 +2439,18 @@ async function handleAnthropicSuccessfulResponse(args) {
     if (quota) {
         // Stash the latest quota on runtime state so the next request can pick the
         // account whose window resets soonest (max-utilization) and proactively
-        // skip any whose window is already rejected — without eating a 429 first.
+        // skip rejected windows unless Anthropic explicitly permits overage.
         accountState.quota = quota;
-        if (maybeCoolFromQuota(accountState, quota, Date.now())) {
-            const { coolingUntil, coolingReason } = accountState;
-            if (coolingUntil !== undefined && coolingReason !== undefined) {
-                saveAccountCooldown(account.key, coolingUntil, coolingReason).catch(() => {
-                    // Non-fatal: cooldown is already active in memory.
-                });
-            }
+        const cooldownUpdate = reconcileCooldownFromQuota(accountState, quota, Date.now());
+        if (cooldownUpdate?.kind === "cooled") {
+            saveAccountCooldown(account.key, cooldownUpdate.coolingUntil, cooldownUpdate.coolingReason).catch(() => {
+                // Non-fatal: cooldown is already active in memory.
+            });
+        }
+        else if (cooldownUpdate?.kind === "cleared") {
+            clearAccountCooldown(account.key, cooldownUpdate.coolingUntil).catch(() => {
+                // Non-fatal: the next successful response will reconcile again.
+            });
         }
         saveAccountQuota(account.label, quota).catch(() => {
             // Non-fatal: quota persistence is best-effort
@@ -2469,10 +2526,11 @@ async function handleAnthropicStreamingSuccessResponse(args) {
     if (preflight.kind === "transport_error") {
         const message = describeTransportError(preflight.error);
         const partialBody = Buffer.concat(preflight.chunks.map((chunk) => Buffer.from(chunk))).toString("utf8");
-        logger.always(`[proxy] stream failed before first chunk account=${account.label}: ${message}; trying next account`);
+        // The POST has already returned a response. The upstream may have started
+        // processing it, so replaying it on another account could duplicate work.
+        logger.always(`[proxy] stream failed before first chunk account=${account.label}: ${message}; returning terminal error to avoid replaying an ambiguous request`);
         recordAttemptError(account.label, account.type, 502);
-        logAttempt(502, "stream_error", message, { retryable: true });
-        tracer?.recordRetry(account.label, "stream_before_first_chunk");
+        logAttempt(502, "stream_error", message, { retryable: false });
         upstreamSpan?.end();
         logProxyBody({
             phase: "upstream_response",
@@ -2488,8 +2546,16 @@ async function handleAnthropicStreamingSuccessResponse(args) {
             metadata: { logicalStatus: 502, transportError: message },
         });
         return {
-            retryNextAccount: true,
-            failure: { message, rateLimit: false },
+            response: finalizeAnthropicTerminalTransportError({
+                account,
+                tracer,
+                requestStartTime,
+                attemptNumber,
+                logProxyBody,
+                logFinalRequest,
+                errorType: "stream_error",
+                message,
+            }),
         };
     }
     if (preflight.kind === "empty") {
@@ -2995,16 +3061,18 @@ async function handleAnthropicSuccessfulNonStreamRetryResponse(args) {
     const retryQuota = parseQuotaHeaders(retryResp.headers);
     if (retryQuota) {
         // Keep the auth-retry success path in parity with the main success path:
-        // stash quota for proactive selection and proactively cool if this
-        // response reveals the window flipped to "rejected".
+        // stash quota for proactive selection and reconcile a rejected window.
         accountState.quota = retryQuota;
-        if (maybeCoolFromQuota(accountState, retryQuota, Date.now())) {
-            const { coolingUntil, coolingReason } = accountState;
-            if (coolingUntil !== undefined && coolingReason !== undefined) {
-                saveAccountCooldown(account.key, coolingUntil, coolingReason).catch(() => {
-                    // Non-fatal: cooldown is already active in memory.
-                });
-            }
+        const cooldownUpdate = reconcileCooldownFromQuota(accountState, retryQuota, Date.now());
+        if (cooldownUpdate?.kind === "cooled") {
+            saveAccountCooldown(account.key, cooldownUpdate.coolingUntil, cooldownUpdate.coolingReason).catch(() => {
+                // Non-fatal: cooldown is already active in memory.
+            });
+        }
+        else if (cooldownUpdate?.kind === "cleared") {
+            clearAccountCooldown(account.key, cooldownUpdate.coolingUntil).catch(() => {
+                // Non-fatal: the next successful response will reconcile again.
+            });
         }
         saveAccountQuota(account.label, retryQuota).catch((error) => {
             logger.debug("[proxy] Failed to persist account quota after auth retry", {
@@ -3133,7 +3201,7 @@ async function handleAnthropicAuthRetry(args) {
             metadata: { upstreamMethod: "POST", upstreamUrl: url },
         });
         try {
-            const retryResp = await fetch(url, {
+            const retryResp = await fetchAnthropicUpstream(url, {
                 method: "POST",
                 headers,
                 body: retryBodyStr,
@@ -3344,11 +3412,37 @@ async function handleAnthropicAuthRetry(args) {
                 : String(retryFetchErr);
             authRetryError = `network error on retry ${authRetry + 1}: ${message}`;
             currentLastError = authRetryError;
+            const retryable = isRetryableNetworkError(retryFetchErr);
             retryLogAttempt(502, "network_error", message, {
-                retryable: isRetryableNetworkError(retryFetchErr),
+                retryable,
                 errorCode: getErrorCode(retryFetchErr) ?? "unknown",
             });
             logger.debug(`[proxy] ${authRetryError}`);
+            if (!retryable) {
+                // Once a POST has left this process, a reset/timeout or unknown fetch
+                // failure is ambiguous: retrying it on another account can duplicate
+                // the request. Only connection-establishment failures are replay-safe.
+                currentUpstreamSpan?.end();
+                return {
+                    response: finalizeAnthropicTerminalTransportError({
+                        account,
+                        tracer,
+                        requestStartTime,
+                        attemptNumber: retryAttemptNumber,
+                        logProxyBody,
+                        logFinalRequest,
+                        errorType: "network_error",
+                        message,
+                    }),
+                    continueLoop: false,
+                    lastError: currentLastError,
+                    authFailureMessage: currentAuthFailureMessage,
+                    sawRateLimit: currentSawRateLimit,
+                    sawTransientFailure: currentSawTransientFailure,
+                    sawNetworkError: currentSawNetworkError,
+                    upstreamSpan: undefined,
+                };
+            }
             break;
         }
     }
@@ -3427,6 +3521,27 @@ function finalizeAnthropicTerminalFetchError(args) {
         errorType: terminalError.errorType,
     });
 }
+function finalizeAnthropicTerminalTransportError(args) {
+    const { account, tracer, requestStartTime, attemptNumber, logProxyBody, logFinalRequest, errorType, message, } = args;
+    tracer?.setError(errorType, message);
+    tracer?.end(502, Date.now() - requestStartTime);
+    logFinalRequest(502, account.label, account.type, errorType, message);
+    const clientError = buildClaudeError(502, message);
+    const clientErrorBody = JSON.stringify(clientError);
+    logProxyBody({
+        phase: "client_response",
+        headers: { "content-type": "application/json" },
+        body: clientErrorBody,
+        bodySize: Buffer.byteLength(clientErrorBody, "utf8"),
+        contentType: "application/json",
+        account: account.label,
+        accountType: account.type,
+        attempt: attemptNumber,
+        responseStatus: 502,
+        durationMs: Date.now() - requestStartTime,
+    });
+    return clientError;
+}
 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;
@@ -4000,7 +4115,7 @@ async function fetchAnthropicAccountResponse(args) {
     const currentUpstreamSpan = upstreamSpan;
     let response;
     try {
-        response = await fetch(url, {
+        response = await fetchAnthropicUpstream(url, {
             method: "POST",
             headers,
             body: finalBodyStr,
@@ -4461,8 +4576,8 @@ async function handleAnthropicRoutedClaudeRequest(args) {
                 // Clear cooling on success — but only if the stored cooldown has already
                 // expired, so an older in-flight success can't wipe an active exhaustion
                 // cooldown just set by a concurrent 429. The success handler re-applies a
-                // cooldown via maybeCoolFromQuota if the fresh quota headers report the
-                // window flipped to "rejected" on this very request.
+                // cooldown via reconcileCooldownFromQuota when fresh quota headers
+                // report a rejected window without explicit overage availability.
                 if (accountState.coolingUntil &&
                     Date.now() >= accountState.coolingUntil) {
                     const expiredCooldown = accountState.coolingUntil;
@@ -4955,37 +5070,23 @@ function describeTransportError(error) {
     return detail ? `${message} (${detail})` : message;
 }
 /**
- * Determine whether a thrown fetch error is a transient connectivity issue.
+ * Determine whether a POST can be retried without risking duplicate provider
+ * work. Only failures that prove connection establishment did not complete are
+ * safe; a reset, socket error, or response timeout can happen after dispatch.
  */
 function isRetryableNetworkError(error) {
     const code = getErrorCode(error);
-    if (code &&
+    return (code !== undefined &&
         [
             "ECONNREFUSED",
-            "ECONNRESET",
+            "EADDRNOTAVAIL",
             // The Anthropic host is fixed, so ENOTFOUND can be a transient resolver
             // outage. Keep it inside the existing bounded same-account retry budget.
             "ENOTFOUND",
-            "ETIMEDOUT",
             "EHOSTUNREACH",
             "UND_ERR_CONNECT_TIMEOUT",
             "UND_ERR_CONNECT",
-            "UND_ERR_SOCKET",
-            "UND_ERR_HEADERS_TIMEOUT",
-        ].includes(code)) {
-        return true;
-    }
-    const message = error instanceof Error ? error.message : String(error);
-    const normalized = message.toLowerCase();
-    return (normalized.includes("econnrefused") ||
-        normalized.includes("econnreset") ||
-        normalized.includes("enotfound") ||
-        normalized.includes("etimedout") ||
-        normalized.includes("timed out") ||
-        normalized.includes("connection error") ||
-        normalized.includes("connect error") ||
-        normalized.includes("fetch failed") ||
-        normalized.includes("socket hang up"));
+        ].includes(code));
 }
 const TRANSIENT_HTTP_STATUSES = new Set([
     408, 500, 502, 503, 504, 520, 521, 522, 523, 524, 525, 526, 529,
@@ -5114,6 +5215,8 @@ export const __testHooks = {
     resolveHomeIndex,
     maybeResetPrimaryToHome,
     planCooldownFor429,
+    reconcileCooldownFromQuota,
+    isRetryableNetworkError,
     isPermanentRefreshFailure,
     getStreamFailureDetails,
     trackUpstreamReadableStream,

package/dist/lib/types/proxy.d.ts

@@ -445,6 +445,9 @@ export type ProxyAccountRoutingCandidate = {
     coolingReason: AccountCoolingReason | null;
     coolingUntil: number | null;
     unifiedStatus: string | null;
+    fallbackStatus?: string | null;
+    upgradePaths?: string | null;
+    overageEligible?: boolean;
     overageStatus: string | null;
     sessionStatus: string | null;
     sessionUsed: number | null;
@@ -480,6 +483,9 @@ export type ProxyAccountSortMetrics = {
     coolingReason: AccountCoolingReason | null;
     coolingUntil: number;
     unifiedStatus: string | null;
+    fallbackStatus?: string | null;
+    upgradePaths?: string | null;
+    overageEligible?: boolean;
     overageStatus: string | null;
     sessionStatus: string | null;
     sessionUsed: number | null;
@@ -737,6 +743,14 @@ export type AccountCooldownPlan = {
      *  burst), a small number of jittered same-account retries is allowed first. */
     rotateImmediately: boolean;
 };
+export type ProxyQuotaCooldownUpdate = {
+    kind: "cooled";
+    coolingUntil: number;
+    coolingReason: AccountCoolingReason;
+} | {
+    kind: "cleared";
+    coolingUntil: number;
+} | null;
 export type TransientRateLimitRetryBudget = {
     coolingUntil: number;
     retriesClaimed: number;
@@ -921,6 +935,10 @@ export type AccountQuota = {
     weeklyResetAt: number;
     /** 0.0-1.0  (from fallback-percentage) */
     fallbackPercentage: number;
+    /** Provider fallback availability, for example "available". */
+    fallbackStatus?: string;
+    /** Comma-separated provider upgrade paths, for example "overage". */
+    upgradePaths?: string;
     /** "allowed" | "rejected" */
     overageStatus: string;
     /** Epoch ms when we last captured this data */

package/dist/proxy/accountQuota.d.ts

@@ -12,6 +12,14 @@
 import type { AccountQuota } from "../types/index.js";
 /** Read and normalize Anthropic's authoritative top-level unified status. */
 export declare function getUnifiedRateLimitStatus(headers: Headers | Record<string, string>): string | undefined;
+/**
+ * Whether Anthropic explicitly permits a request to use overage after a
+ * subscription window is exhausted. Fresh responses require all three
+ * provider signals. Older persisted snapshots predate the raw fallback and
+ * upgrade-path fields, but retain a positive fallback percentage together with
+ * an allowed overage status, which is the equivalent provider state.
+ */
+export declare function isQuotaOverageAvailable(quota: Pick<AccountQuota, "fallbackPercentage" | "fallbackStatus" | "overageStatus" | "upgradePaths"> | null | undefined): boolean;
 /**
  * Parse Anthropic rate-limit / quota headers into an `AccountQuota`.
  * Returns `null` when key headers are absent.