@juspay/neurolink 9.86.3 → 9.86.5

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

@@ -13,7 +13,9 @@ import { access, readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { buildStableClaudeCodeBillingHeader, CLAUDE_CLI_USER_AGENT, CLAUDE_CODE_OAUTH_BETAS, getOrCreateClaudeCodeIdentity, parseClaudeCodeUserId, } from "../../auth/anthropicOAuth.js";
-import { loadAccountQuotas, parseQuotaHeaders, saveAccountQuota, } from "../../proxy/accountQuota.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 { 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";
@@ -23,7 +25,8 @@ import { createRawStreamCapture } from "../../proxy/rawStreamCapture.js";
 import { relocateClientSystemIntoMessages } from "../../proxy/systemRelocation.js";
 import { logBodyCapture, logRequest, logRequestAttempt, logStreamError, } from "../../proxy/requestLogger.js";
 import { createSSEInterceptor } from "../../proxy/sseInterceptor.js";
-import { needsRefresh, persistTokens, refreshToken, } from "../../proxy/tokenRefresh.js";
+import { createStreamTerminalOutcomeTracker, mergeStreamTerminalOutcome, } from "../../proxy/streamOutcome.js";
+import { isPermanentRefreshFailure, needsRefresh, persistTokens, refreshToken, } from "../../proxy/tokenRefresh.js";
 import { buildProxyTranslationPlan, parseRetryAfterMs, } from "../../proxy/routingPolicy.js";
 import { writeJsonSnapshotAtomically } from "../../proxy/snapshotPersistence.js";
 import { recordAttempt, recordAttemptError, recordFinalError, recordFinalSuccess, } from "../../proxy/usageStats.js";
@@ -54,8 +57,8 @@ let lastKnownAccountCount = 0;
  *  When undefined, home semantics fall back to enabledAccounts[0] (insertion
  *  order) — preserves pre-existing behavior. */
 let configuredPrimaryAccountKey;
+let configuredAccountAllowlist;
 const MAX_AUTH_RETRIES = 5;
-const MAX_CONSECUTIVE_REFRESH_FAILURES = 15;
 const MAX_TRANSIENT_SAME_ACCOUNT_RETRIES = 2;
 const TRANSIENT_SAME_ACCOUNT_RETRY_DELAYS_MS = [250, 1_000];
 /** Maximum upstream 429 attempts per account before rotating — for a TRANSIENT
@@ -78,6 +81,11 @@ const MIN_COOLDOWN_MS = 5_000;
  *  we should return to the account soon rather than parking it for the full
  *  reset window. */
 const TRANSIENT_MAX_COOLDOWN_MS = 15 * 60 * 1000; // 15 minutes
+/** Fallback for authoritative rejected states that do not provide a usable
+ * reset or retry-after. These are not transient burst limits. */
+const DEFAULT_HARD_COOLDOWN_MS = 15 * 60 * 1000; // 15 minutes
+const AUTH_REFRESH_BASE_COOLDOWN_MS = 30_000;
+const AUTH_REFRESH_MAX_COOLDOWN_MS = 5 * 60 * 1000;
 /** Timeout for upstream requests to Anthropic. Must be generous enough
  *  to cover the full lifecycle of streaming responses, including extended
  *  thinking from Opus models (which can exceed 5 minutes for large contexts). */
@@ -109,10 +117,11 @@ function advancePrimaryIfCurrent(accountKey, enabledCount, primaryAccountKey) {
  *  removed). The resolution is per-request because enabledAccounts membership
  *  can shift between requests. */
 function resolveHomeIndex(enabledAccounts) {
-    if (!configuredPrimaryAccountKey) {
+    const primaryAccountKey = configuredPrimaryAccountKey;
+    if (!primaryAccountKey) {
         return 0;
     }
-    const idx = enabledAccounts.findIndex((a) => a.key === configuredPrimaryAccountKey);
+    const idx = enabledAccounts.findIndex((a) => anthropicAccountKeysEqual(a.key, primaryAccountKey));
     return idx >= 0 ? idx : 0;
 }
 /** If the configured home primary is no longer cooling, reset
@@ -135,7 +144,12 @@ function maybeResetPrimaryToHome(enabledAccounts) {
         // Home account is no longer cooling — reset to it
         primaryAccountIndex = homeIndex;
         if (homeState?.coolingUntil) {
+            const expiredCooldown = homeState.coolingUntil;
             homeState.coolingUntil = undefined;
+            homeState.coolingReason = undefined;
+            clearAccountCooldown(homeAccount.key, expiredCooldown).catch(() => {
+                // Best-effort cleanup; an expired entry is ignored on the next boot.
+            });
             logger.always(`[proxy] home primary account=${homeAccount.label} cooling expired, resetting primaryAccountIndex to ${homeIndex}`);
         }
     }
@@ -179,7 +193,7 @@ function clampCooldownUntil(untilMs, now) {
  * burst / acceleration limit) is transient: honor retry-after as a floor,
  * allow a couple of jittered same-account retries, then a short cooldown.
  */
-function planCooldownFor429(quota, retryAfterMs, now) {
+function planCooldownFor429(quota, retryAfterMs, now, unifiedStatus = quota?.unifiedStatus) {
     // Weekly exhaustion takes precedence — it's the longest, hardest ceiling.
     if (quota && quota.weeklyStatus === "rejected") {
         const reset = resetEpochToMs(quota.weeklyResetAt, now) ??
@@ -199,6 +213,17 @@ function planCooldownFor429(quota, retryAfterMs, now) {
             rotateImmediately: true,
         };
     }
+    // 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") {
+        const reset = retryAfterMs > 0 ? now + retryAfterMs : now + DEFAULT_HARD_COOLDOWN_MS;
+        return {
+            reason: "unified",
+            coolingUntil: clampCooldownUntil(reset, now),
+            rotateImmediately: true,
+        };
+    }
     // Transient burst: cool only for retry-after, floored at MIN_COOLDOWN_MS so a
     // tiny retry-after can't make the account eligible almost immediately, and
     // capped so it recovers quickly.
@@ -232,15 +257,21 @@ function maybeCoolFromQuota(state, quota, now) {
         until = resetEpochToMs(quota.sessionResetAt, now);
         reason = "session";
     }
+    else if (quota.unifiedStatus === "rejected") {
+        until = now + DEFAULT_HARD_COOLDOWN_MS;
+        reason = "unified";
+    }
     if (until === undefined) {
-        return;
+        return false;
     }
     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 false;
 }
 /**
  * Seed each account's runtime quota from the persisted snapshots in
@@ -254,11 +285,22 @@ function maybeCoolFromQuota(state, quota, now) {
  */
 async function seedRuntimeQuotasFromDisk(accounts) {
     try {
-        const persisted = await loadAccountQuotas();
+        const [persistedQuotas, persistedCooldowns] = await Promise.all([
+            loadAccountQuotas(),
+            loadAccountCooldowns(),
+        ]);
+        const now = Date.now();
         for (const account of accounts) {
             const state = getOrCreateRuntimeState(account.key);
-            if (!state.quota && persisted[account.label]) {
-                state.quota = persisted[account.label];
+            if (!state.quota && persistedQuotas[account.label]) {
+                state.quota = persistedQuotas[account.label];
+            }
+            const persistedCooldown = persistedCooldowns[account.key];
+            if (persistedCooldown?.coolingUntil > now &&
+                (!state.coolingUntil ||
+                    persistedCooldown.coolingUntil > state.coolingUntil)) {
+                state.coolingUntil = persistedCooldown.coolingUntil;
+                state.coolingReason = persistedCooldown.reason;
             }
         }
     }
@@ -695,47 +737,63 @@ async function tryLoadLegacyAccount(creds, legacyCredPath) {
     let legacyToken = creds.oauth.accessToken;
     let legacyRefresh = creds.oauth.refreshToken;
     let legacyExpiry = creds.oauth.expiresAt;
+    const legacyLabel = creds.email?.trim() || "legacy-default";
     const legacyExpired = legacyExpiry ? legacyExpiry < Date.now() : false;
+    const legacyAccount = () => ({
+        key: LEGACY_ANTHROPIC_ACCOUNT_KEY,
+        label: legacyLabel,
+        token: legacyToken,
+        refreshToken: legacyRefresh,
+        expiresAt: legacyExpiry,
+        type: "oauth",
+        persistTarget: { credPath: legacyCredPath },
+    });
     if (!legacyExpired) {
-        return {
-            key: "anthropic:legacy-default",
-            label: "default",
-            token: legacyToken,
-            refreshToken: legacyRefresh,
-            expiresAt: legacyExpiry,
-            type: "oauth",
-            persistTarget: { credPath: legacyCredPath },
-        };
+        return legacyAccount();
+    }
+    const state = getOrCreateRuntimeState(LEGACY_ANTHROPIC_ACCOUNT_KEY);
+    if (state.permanentlyDisabled) {
+        return undefined;
+    }
+    const persistedCooldown = (await loadAccountCooldowns())[LEGACY_ANTHROPIC_ACCOUNT_KEY];
+    if (persistedCooldown?.coolingUntil > Date.now() &&
+        (!state.coolingUntil || persistedCooldown.coolingUntil > state.coolingUntil)) {
+        state.coolingUntil = persistedCooldown.coolingUntil;
+        state.coolingReason = persistedCooldown.reason;
+    }
+    if (state.coolingReason === "auth" &&
+        state.coolingUntil &&
+        state.coolingUntil > Date.now()) {
+        return legacyAccount();
     }
     if (!legacyRefresh) {
         logger.always("[proxy] skipping legacy account (expired, no refresh token)");
+        await disableAccountUntilReauth(legacyAccount(), state, "missing_refresh_token");
         return undefined;
     }
     const tmp = {
         token: legacyToken,
         refreshToken: legacyRefresh,
         expiresAt: legacyExpiry,
-        label: "default",
+        label: legacyLabel,
     };
     const ok = await refreshToken(tmp);
     if (!ok.success) {
-        logger.always(`[proxy] skipping legacy account (expired, refresh failed: ${ok.error?.slice(0, 200) ?? "unknown"})`);
-        return undefined;
+        if (isPermanentRefreshFailure(ok)) {
+            await disableAccountUntilReauth(legacyAccount(), state, "refresh_invalid");
+            return undefined;
+        }
+        const coolingUntil = await coolAccountAfterTransientRefreshFailure(legacyAccount(), state);
+        logger.always(`[proxy] legacy refresh temporarily unavailable (${ok.status ?? "network"}); cooling until ${new Date(coolingUntil).toISOString()}`);
+        return legacyAccount();
     }
     legacyToken = tmp.token;
     legacyRefresh = tmp.refreshToken;
     legacyExpiry = tmp.expiresAt;
     await persistTokens(legacyCredPath, tmp);
+    await clearAuthCooldownAfterRefresh(legacyAccount(), state);
     logger.always("[proxy] refreshed legacy account at startup");
-    return {
-        key: "anthropic:legacy-default",
-        label: "default",
-        token: legacyToken,
-        refreshToken: legacyRefresh,
-        expiresAt: legacyExpiry,
-        type: "oauth",
-        persistTarget: { credPath: legacyCredPath },
-    };
+    return legacyAccount();
 }
 async function handleTranslatedClaudeRequest(args) {
     const { ctx, body, route, modelRouter, tracer, requestStartTime, logProxyBody, } = args;
@@ -925,6 +983,43 @@ async function handleClaudePassthroughRequest(args) {
         logProxyBody,
     });
 }
+function trackUpstreamReadableStream(source) {
+    const reader = source.getReader();
+    const tracker = createStreamTerminalOutcomeTracker();
+    let closed = false;
+    const stream = new ReadableStream({
+        async pull(controller) {
+            if (closed) {
+                return;
+            }
+            try {
+                const { done, value } = await reader.read();
+                if (closed) {
+                    return;
+                }
+                if (done) {
+                    closed = true;
+                    tracker.complete();
+                    controller.close();
+                    return;
+                }
+                controller.enqueue(value);
+            }
+            catch (error) {
+                closed = true;
+                const message = error instanceof Error ? error.message : String(error);
+                tracker.fail(message);
+                controller.error(error);
+            }
+        },
+        cancel(reason) {
+            closed = true;
+            tracker.cancel();
+            return reader.cancel(reason);
+        },
+    });
+    return { stream, outcome: tracker.outcome };
+}
 async function handleClaudePassthroughStreamResponse(args) {
     const { ctx, body, bodyStr, response, tracer, requestStartTime, toolCount, upstreamSpan, upstreamResponseHeaders, logProxyBody, } = args;
     const responseHeaders = { ...upstreamResponseHeaders };
@@ -933,7 +1028,8 @@ async function handleClaudePassthroughStreamResponse(args) {
     if (!responseBody) {
         throw new Error("Expected passthrough stream response body");
     }
-    let streamSource = responseBody;
+    const trackedStream = trackUpstreamReadableStream(responseBody);
+    let streamSource = trackedStream.stream;
     if (tracer) {
         try {
             const { stream: interceptor, telemetry } = createSSEInterceptor({
@@ -944,8 +1040,10 @@ async function handleClaudePassthroughStreamResponse(args) {
             const capturedUpstreamSpan = upstreamSpan;
             const capturedResponse = response;
             const capturedRequestBytes = bodyStr.length;
-            Promise.all([telemetry, clientCapture])
-                .then(([data, clientBody]) => {
+            Promise.all([telemetry, clientCapture, trackedStream.outcome])
+                .then(([data, clientBody, rawOutcome]) => {
+                const terminalOutcome = mergeStreamTerminalOutcome(rawOutcome, data.streamErrorMessage);
+                const failure = getStreamFailureDetails(terminalOutcome);
                 capturedTracer.setUsage({
                     inputTokens: data.usage.inputTokens,
                     outputTokens: data.usage.outputTokens,
@@ -975,7 +1073,10 @@ async function handleClaudePassthroughStreamResponse(args) {
                 capturedTracer.recordMetrics();
                 capturedTracer.recordBodySizes(capturedRequestBytes, data.totalBytesReceived);
                 capturedUpstreamSpan?.end();
-                capturedTracer.end(200, Date.now() - requestStartTime);
+                if (failure) {
+                    capturedTracer.setError(failure.errorType, failure.message);
+                }
+                capturedTracer.end(failure?.status ?? response.status, Date.now() - requestStartTime);
                 const traceCtx = capturedTracer.getTraceContext();
                 logRequest({
                     timestamp: new Date().toISOString(),
@@ -987,7 +1088,7 @@ async function handleClaudePassthroughStreamResponse(args) {
                     toolCount,
                     account: "passthrough",
                     accountType: "passthrough",
-                    responseStatus: 200,
+                    responseStatus: failure?.status ?? response.status,
                     responseTimeMs: Date.now() - requestStartTime,
                     inputTokens: data.usage.inputTokens,
                     outputTokens: data.usage.outputTokens,
@@ -995,6 +1096,12 @@ async function handleClaudePassthroughStreamResponse(args) {
                     cacheReadTokens: data.usage.cacheReadInputTokens,
                     traceId: traceCtx.traceId,
                     spanId: traceCtx.spanId,
+                    ...(failure
+                        ? {
+                            errorType: failure.errorType,
+                            errorMessage: failure.message,
+                        }
+                        : {}),
                 });
                 logProxyBody({
                     phase: "upstream_response",
@@ -1046,40 +1153,140 @@ async function handleClaudePassthroughStreamResponse(args) {
             });
         }
         catch {
-            // Streaming capture is best-effort.
+            trackedStream.outcome.then((outcome) => {
+                const failure = getStreamFailureDetails(outcome);
+                upstreamSpan?.end();
+                if (failure) {
+                    tracer.setError(failure.errorType, failure.message);
+                }
+                tracer.end(failure?.status ?? response.status, Date.now() - requestStartTime);
+                const traceCtx = tracer.getTraceContext();
+                logRequest({
+                    timestamp: new Date().toISOString(),
+                    requestId: ctx.requestId,
+                    method: ctx.method,
+                    path: ctx.path,
+                    model: body.model,
+                    stream: true,
+                    toolCount,
+                    account: "passthrough",
+                    accountType: "passthrough",
+                    responseStatus: failure?.status ?? response.status,
+                    responseTimeMs: Date.now() - requestStartTime,
+                    traceId: traceCtx.traceId,
+                    spanId: traceCtx.spanId,
+                    ...(failure
+                        ? {
+                            errorType: failure.errorType,
+                            errorMessage: failure.message,
+                        }
+                        : {}),
+                });
+            });
         }
     }
     else {
-        clientCapture
-            .then((clientBody) => {
-            logProxyBody({
-                phase: "upstream_response",
-                headers: responseHeaders,
-                body: clientBody.text,
-                bodySize: clientBody.totalBytes,
-                contentType: responseHeaders["content-type"] ?? "text/event-stream",
-                account: "passthrough",
-                accountType: "passthrough",
-                attempt: 1,
-                responseStatus: 200,
-                durationMs: Date.now() - requestStartTime,
+        try {
+            const { stream: interceptor, telemetry } = createSSEInterceptor({
+                captureRawText: true,
             });
-            logProxyBody({
-                phase: "client_response",
-                headers: responseHeaders,
-                body: clientBody.text,
-                bodySize: clientBody.totalBytes,
-                contentType: responseHeaders["content-type"] ?? "text/event-stream",
-                account: "passthrough",
-                accountType: "passthrough",
-                attempt: 1,
-                responseStatus: 200,
-                durationMs: Date.now() - requestStartTime,
+            streamSource = streamSource.pipeThrough(interceptor);
+            Promise.all([telemetry, clientCapture, trackedStream.outcome])
+                .then(([data, clientBody, rawOutcome]) => {
+                const terminalOutcome = mergeStreamTerminalOutcome(rawOutcome, data.streamErrorMessage);
+                const failure = getStreamFailureDetails(terminalOutcome);
+                logRequest({
+                    timestamp: new Date().toISOString(),
+                    requestId: ctx.requestId,
+                    method: ctx.method,
+                    path: ctx.path,
+                    model: body.model,
+                    stream: true,
+                    toolCount,
+                    account: "passthrough",
+                    accountType: "passthrough",
+                    responseStatus: failure?.status ?? response.status,
+                    responseTimeMs: Date.now() - requestStartTime,
+                    inputTokens: data.usage.inputTokens,
+                    outputTokens: data.usage.outputTokens,
+                    cacheCreationTokens: data.usage.cacheCreationInputTokens,
+                    cacheReadTokens: data.usage.cacheReadInputTokens,
+                    ...(failure
+                        ? {
+                            errorType: failure.errorType,
+                            errorMessage: failure.message,
+                        }
+                        : {}),
+                });
+                logProxyBody({
+                    phase: "upstream_response",
+                    headers: responseHeaders,
+                    body: data.rawText ?? "",
+                    bodySize: data.totalBytesReceived,
+                    contentType: responseHeaders["content-type"] ?? "text/event-stream",
+                    account: "passthrough",
+                    accountType: "passthrough",
+                    attempt: 1,
+                    responseStatus: response.status,
+                    durationMs: Date.now() - requestStartTime,
+                });
+                logProxyBody({
+                    phase: "client_response",
+                    headers: responseHeaders,
+                    body: clientBody.text,
+                    bodySize: clientBody.totalBytes,
+                    contentType: responseHeaders["content-type"] ?? "text/event-stream",
+                    account: "passthrough",
+                    accountType: "passthrough",
+                    attempt: 1,
+                    responseStatus: response.status,
+                    durationMs: Date.now() - requestStartTime,
+                });
+            })
+                .catch((error) => {
+                logRequest({
+                    timestamp: new Date().toISOString(),
+                    requestId: ctx.requestId,
+                    method: ctx.method,
+                    path: ctx.path,
+                    model: body.model,
+                    stream: true,
+                    toolCount,
+                    account: "passthrough",
+                    accountType: "passthrough",
+                    responseStatus: 500,
+                    responseTimeMs: Date.now() - requestStartTime,
+                    errorType: "stream_telemetry_error",
+                    errorMessage: error instanceof Error ? error.message : String(error),
+                });
             });
-        })
-            .catch(() => {
-            // Non-fatal
-        });
+        }
+        catch {
+            // Streaming capture is best-effort; the tracked source still propagates
+            // the transport failure to the client.
+            trackedStream.outcome.then((outcome) => {
+                const failure = getStreamFailureDetails(outcome);
+                logRequest({
+                    timestamp: new Date().toISOString(),
+                    requestId: ctx.requestId,
+                    method: ctx.method,
+                    path: ctx.path,
+                    model: body.model,
+                    stream: true,
+                    toolCount,
+                    account: "passthrough",
+                    accountType: "passthrough",
+                    responseStatus: failure?.status ?? response.status,
+                    responseTimeMs: Date.now() - requestStartTime,
+                    ...(failure
+                        ? {
+                            errorType: failure.errorType,
+                            errorMessage: failure.message,
+                        }
+                        : {}),
+                });
+            });
+        }
     }
     const clientStream = streamSource.pipeThrough(clientCaptureStream);
     return new Response(clientStream, {
@@ -1198,23 +1405,27 @@ async function loadClaudeProxyAccounts(args) {
     const accounts = [];
     const legacyCredPath = `${os.homedir()}/.neurolink/anthropic-credentials.json`;
     const { tokenStore } = await import("../../auth/tokenStore.js");
+    const persistedCooldowns = await loadAccountCooldowns();
     if (!startupPruneDone) {
         await tokenStore.pruneExpired();
         startupPruneDone = true;
     }
     const compoundKeys = await tokenStore.listByPrefix("anthropic:");
     for (const key of compoundKeys) {
+        if (!isAccountAllowed(key, configuredAccountAllowlist)) {
+            logger.debug(`[proxy] skipping account=${key} (not in account allowlist)`);
+            continue;
+        }
         if (await tokenStore.isDisabled(key)) {
             const existingState = getOrCreateRuntimeState(key);
-            const tokens = await tokenStore.loadTokens(key);
-            const hasTrackedTokens = existingState.lastToken !== undefined && existingState.lastToken !== "";
-            const tokenChanged = tokens &&
-                hasTrackedTokens &&
-                (existingState.lastToken !== tokens.accessToken ||
-                    existingState.lastRefreshToken !== tokens.refreshToken);
-            if (tokenChanged) {
+            const disabledReason = await tokenStore.getDisabledReason(key);
+            // Older releases permanently disabled accounts after any refresh error,
+            // including timeouts, 429s and 5xx responses. Re-evaluate those legacy
+            // entries once under the terminal/transient classifier below.
+            const legacyTransientDisable = disabledReason === "refresh_failed";
+            if (legacyTransientDisable) {
                 await tokenStore.markEnabled(key);
-                logger.always(`[proxy] account=${key.split(":")[1] ?? key} re-enabled (credentials changed)`);
+                logger.always(`[proxy] account=${key.split(":")[1] ?? key} re-enabled for legacy refresh failure recheck`);
                 existingState.permanentlyDisabled = false;
                 existingState.consecutiveRefreshFailures = 0;
             }
@@ -1231,16 +1442,41 @@ async function loadClaudeProxyAccounts(args) {
         let accessToken = tokens.accessToken;
         let refreshTok = tokens.refreshToken;
         let expiresAt = tokens.expiresAt;
+        const label = key.split(":")[1] ?? key;
+        const accountType = tokens.tokenType === "Bearer" ? "oauth" : "api_key";
+        const existingState = getOrCreateRuntimeState(key);
+        const persistedCooldown = persistedCooldowns[key];
+        if (persistedCooldown?.coolingUntil > Date.now() &&
+            (!existingState.coolingUntil ||
+                persistedCooldown.coolingUntil > existingState.coolingUntil)) {
+            existingState.coolingUntil = persistedCooldown.coolingUntil;
+            existingState.coolingReason = persistedCooldown.reason;
+        }
+        const addAccount = () => {
+            accounts.push({
+                key,
+                label,
+                token: accessToken,
+                refreshToken: refreshTok,
+                expiresAt,
+                type: accountType,
+                persistTarget: { providerKey: key },
+            });
+        };
         const isExpired = expiresAt ? expiresAt < Date.now() : false;
         if (isExpired) {
-            const label = key.split(":")[1] ?? key;
-            const existingState = getOrCreateRuntimeState(key);
             if (existingState.permanentlyDisabled) {
                 continue;
             }
+            if (existingState.coolingReason === "auth" &&
+                existingState.coolingUntil &&
+                existingState.coolingUntil > Date.now()) {
+                addAccount();
+                continue;
+            }
             if (!refreshTok) {
                 logger.always(`[proxy] skipping account=${label} (expired, no refresh token)`);
-                await disableAccountUntilReauth({ key, label, token: accessToken, type: "oauth" }, existingState);
+                await disableAccountUntilReauth({ key, label, token: accessToken, type: "oauth" }, existingState, "missing_refresh_token");
                 continue;
             }
             const tempAccount = {
@@ -1251,8 +1487,21 @@ async function loadClaudeProxyAccounts(args) {
             };
             const refreshed = await refreshToken(tempAccount);
             if (!refreshed.success) {
-                logger.always(`[proxy] skipping account=${label} (expired, refresh failed: ${refreshed.error?.slice(0, 200) ?? "unknown"})`);
-                await disableAccountUntilReauth({ key, label, token: accessToken, type: "oauth" }, existingState);
+                const account = {
+                    key,
+                    label,
+                    token: accessToken,
+                    type: "oauth",
+                };
+                if (isPermanentRefreshFailure(refreshed)) {
+                    logger.always(`[proxy] skipping account=${label} (refresh token rejected: ${refreshed.error?.slice(0, 200) ?? "unknown"})`);
+                    await disableAccountUntilReauth(account, existingState, "refresh_invalid");
+                }
+                else {
+                    const coolingUntil = await coolAccountAfterTransientRefreshFailure(account, existingState);
+                    logger.always(`[proxy] account=${label} refresh temporarily unavailable (${refreshed.status ?? "network"}); cooling until ${new Date(coolingUntil).toISOString()} and rotating`);
+                    addAccount();
+                }
                 continue;
             }
             accessToken = tempAccount.token;
@@ -1265,19 +1514,12 @@ async function loadClaudeProxyAccounts(args) {
                 tokenType: "Bearer",
             });
             logger.always(`[proxy] refreshed expired account=${key.split(":")[1] ?? key} at startup`);
+            await clearAuthCooldownAfterRefresh({ key }, existingState);
         }
-        const accountType = tokens.tokenType === "Bearer" ? "oauth" : "api_key";
-        accounts.push({
-            key,
-            label: key.split(":")[1] ?? key,
-            token: accessToken,
-            refreshToken: refreshTok,
-            expiresAt,
-            type: accountType,
-            persistTarget: { providerKey: key },
-        });
+        addAccount();
     }
-    if (accounts.length === 0) {
+    if (accounts.length === 0 &&
+        shouldLoadFallbackCredential(compoundKeys.length, LEGACY_ANTHROPIC_ACCOUNT_KEY, configuredAccountAllowlist)) {
         try {
             const creds = JSON.parse(fs.readFileSync(legacyCredPath, "utf8"));
             const legacyAccount = await tryLoadLegacyAccount(creds, legacyCredPath);
@@ -1289,19 +1531,26 @@ async function loadClaudeProxyAccounts(args) {
             // file absent or invalid
         }
     }
-    if (process.env.ANTHROPIC_API_KEY && accounts.length === 0) {
+    if (process.env.ANTHROPIC_API_KEY &&
+        accounts.length === 0 &&
+        shouldLoadFallbackCredential(compoundKeys.length, ENV_ANTHROPIC_ACCOUNT_KEY, configuredAccountAllowlist)) {
         accounts.push({
-            key: "anthropic:env",
+            key: ENV_ANTHROPIC_ACCOUNT_KEY,
             label: "env",
             token: process.env.ANTHROPIC_API_KEY,
             type: "api_key",
         });
     }
     if (accounts.length === 0) {
-        tracer?.setError("authentication_error", "No Anthropic credentials found");
+        const noCredentialsMessage = configuredAccountAllowlist
+            ? "No allowed Anthropic credentials are currently available"
+            : compoundKeys.length > 0
+                ? "Configured Anthropic accounts are disabled or unavailable"
+                : "No Anthropic credentials found";
+        tracer?.setError("authentication_error", noCredentialsMessage);
         tracer?.end(401, Date.now() - requestStartTime);
         return {
-            response: buildLoggedClaudeError(401, "No Anthropic credentials found"),
+            response: buildLoggedClaudeError(401, noCredentialsMessage),
         };
     }
     for (const account of accounts) {
@@ -1310,8 +1559,10 @@ async function loadClaudeProxyAccounts(args) {
             state.lastRefreshToken !== account.refreshToken;
         if (tokenChanged) {
             if (state.permanentlyDisabled) {
-                logger.always(`[proxy] account=${account.label} credentials changed, re-enabling`);
+                logger.always(`[proxy] account=${account.label} eligible credentials reloaded; clearing stale runtime auth-disable state`);
             }
+            // Eligibility was already resolved while loading accounts. This only
+            // clears stale in-process auth state after an explicit credential reload.
             state.consecutiveRefreshFailures = 0;
             state.permanentlyDisabled = false;
         }
@@ -1608,12 +1859,17 @@ async function tryAutoClaudeFallback(args) {
     }
 }
 function buildClaudeAnthropicFailureResponse(args) {
-    const { tracer, requestStartTime, authFailureMessage, invalidRequestFailure, sawNetworkError, sawTransientFailure, sawRateLimit, lastError, orderedAccounts, buildLoggedClaudeError, logProxyBody, logFinalRequest, } = args;
+    const { tracer, requestStartTime, authFailureMessage, authCooldownMessage, invalidRequestFailure, sawNetworkError, sawTransientFailure, sawRateLimit, lastError, orderedAccounts, buildLoggedClaudeError, logProxyBody, logFinalRequest, } = args;
     if (authFailureMessage && !sawRateLimit) {
         tracer?.setError("authentication_error", authFailureMessage);
         tracer?.end(401, Date.now() - requestStartTime);
         return buildLoggedClaudeError(401, authFailureMessage);
     }
+    if (authCooldownMessage && !sawRateLimit) {
+        tracer?.setError("token_refresh_unavailable", authCooldownMessage);
+        tracer?.end(503, Date.now() - requestStartTime);
+        return buildLoggedClaudeError(503, authCooldownMessage, "token_refresh_unavailable");
+    }
     if (invalidRequestFailure) {
         tracer?.setError("invalid_request_error", summarizeErrorMessage(invalidRequestFailure.body));
         tracer?.end(invalidRequestFailure.status, Date.now() - requestStartTime);
@@ -1654,10 +1910,21 @@ function buildClaudeAnthropicFailureResponse(args) {
         tracer?.end(502, Date.now() - requestStartTime);
         return buildLoggedClaudeError(502, msg);
     }
-    // All accounts returned 429 after exhausting per-account retries.
-    // Return 1s retry-after — the proxy already waited for each upstream retry-after inline.
-    const retryAfterSec = 1;
-    const errorMessage = `All ${orderedAccounts.length} accounts rate-limited after ${MAX_RATE_LIMIT_SAME_ACCOUNT_RETRIES + 1} attempts each (1 initial + ${MAX_RATE_LIMIT_SAME_ACCOUNT_RETRIES} retries).`;
+    const now = Date.now();
+    const activeRateLimitCooldowns = orderedAccounts
+        .map((account) => getOrCreateRuntimeState(account.key))
+        .filter((state) => state.coolingUntil &&
+        state.coolingUntil > now &&
+        state.coolingReason !== "auth");
+    const earliestRetryAt = Math.min(...activeRateLimitCooldowns.map((state) => state.coolingUntil ?? Number.POSITIVE_INFINITY));
+    const allAccountsCooling = orderedAccounts.length > 0 &&
+        activeRateLimitCooldowns.length === orderedAccounts.length;
+    const retryAfterSec = allAccountsCooling
+        ? Math.max(1, Math.ceil((earliestRetryAt - now) / 1000))
+        : 1;
+    const errorMessage = allAccountsCooling
+        ? `All ${orderedAccounts.length} Anthropic accounts are cooling after upstream rate limits. Earliest retry at ${new Date(earliestRetryAt).toISOString()}.`
+        : `All ${orderedAccounts.length} accounts rate-limited after per-account retries.`;
     logger.always(`[proxy] all accounts rate-limited, retry in ${retryAfterSec}s`);
     const errorBody = buildClaudeError(429, errorMessage, "overloaded_error");
     tracer?.setError("rate_limit_error", errorMessage);
@@ -1695,7 +1962,14 @@ async function handleAnthropicSuccessfulResponse(args) {
         // account whose window resets soonest (max-utilization) and proactively
         // skip any whose window is already rejected — without eating a 429 first.
         accountState.quota = quota;
-        maybeCoolFromQuota(accountState, quota, Date.now());
+        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.
+                });
+            }
+        }
         saveAccountQuota(account.label, quota).catch(() => {
             // Non-fatal: quota persistence is best-effort
         });
@@ -1762,14 +2036,40 @@ async function handleAnthropicStreamingSuccessResponse(args) {
         return { response: clientError };
     }
     const reader = response.body.getReader();
-    const firstChunk = await reader.read();
+    let firstChunk;
+    try {
+        firstChunk = await reader.read();
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        logger.always(`[proxy] stream failed before first chunk account=${account.label}: ${message}; trying next account`);
+        recordAttemptError(account.label, account.type, 502);
+        tracer?.recordRetry(account.label, "stream_before_first_chunk");
+        upstreamSpan?.end();
+        logProxyBody({
+            phase: "upstream_response",
+            headers: responseHeaders,
+            body: message,
+            bodySize: Buffer.byteLength(message, "utf8"),
+            contentType: responseHeaders["content-type"] ?? "text/event-stream",
+            account: account.label,
+            accountType: account.type,
+            attempt: attemptNumber,
+            responseStatus: 502,
+            durationMs: Date.now() - fetchStartMs,
+        });
+        return { retryNextAccount: true };
+    }
     if (firstChunk.done || !firstChunk.value || firstChunk.value.length === 0) {
-        reader.cancel();
+        await reader.cancel().catch(() => {
+            // Best-effort release before rotating to another account.
+        });
         logger.always(`[proxy] ← empty stream from account=${account.label}, trying next`);
         tracer?.recordRetry(account.label, "empty_stream");
         upstreamSpan?.end();
         return { retryNextAccount: true };
     }
+    const streamOutcomeTracker = createStreamTerminalOutcomeTracker();
     let mainStreamClosed = false;
     const remainingStream = new ReadableStream({
         start(controller) {
@@ -1786,6 +2086,7 @@ async function handleAnthropicStreamingSuccessResponse(args) {
                 }
                 if (done) {
                     mainStreamClosed = true;
+                    streamOutcomeTracker.complete();
                     controller.close();
                     return;
                 }
@@ -1794,6 +2095,7 @@ async function handleAnthropicStreamingSuccessResponse(args) {
             catch (streamErr) {
                 const errMsg = streamErr instanceof Error ? streamErr.message : String(streamErr);
                 logger.always(`[proxy] mid-stream error account=${account.label}: ${errMsg}`);
+                streamOutcomeTracker.fail(errMsg);
                 logStreamError({
                     timestamp: new Date().toISOString(),
                     requestId: ctx.requestId,
@@ -1812,7 +2114,8 @@ async function handleAnthropicStreamingSuccessResponse(args) {
         },
         cancel() {
             mainStreamClosed = true;
-            reader.cancel();
+            streamOutcomeTracker.cancel();
+            return reader.cancel();
         },
     });
     const result = attachAnthropicSuccessStreamTelemetry({
@@ -1820,6 +2123,7 @@ async function handleAnthropicStreamingSuccessResponse(args) {
         response,
         responseHeaders,
         remainingStream,
+        streamOutcome: streamOutcomeTracker.outcome,
         tracer,
         requestStartTime,
         attemptNumber,
@@ -1830,8 +2134,25 @@ async function handleAnthropicStreamingSuccessResponse(args) {
     });
     return { response: result };
 }
+function getStreamFailureDetails(outcome) {
+    if (outcome.kind === "upstream_error") {
+        return {
+            status: 502,
+            errorType: "stream_error",
+            message: outcome.message,
+        };
+    }
+    if (outcome.kind === "client_cancelled") {
+        return {
+            status: 499,
+            errorType: "client_cancelled",
+            message: "Client cancelled the streaming response",
+        };
+    }
+    return undefined;
+}
 function attachAnthropicSuccessStreamTelemetry(args) {
-    const { account, response, responseHeaders, remainingStream, tracer, requestStartTime, attemptNumber, finalBodyStr, upstreamSpan, logProxyBody, logFinalRequest, } = args;
+    const { account, response, responseHeaders, remainingStream, streamOutcome, tracer, requestStartTime, attemptNumber, finalBodyStr, upstreamSpan, logProxyBody, logFinalRequest, } = args;
     const { stream: clientCaptureStream, capture: clientCapture } = createRawStreamCapture();
     let streamSource = remainingStream;
     if (tracer) {
@@ -1845,8 +2166,9 @@ function attachAnthropicSuccessStreamTelemetry(args) {
             const capturedResponse = response;
             const capturedRequestBytes = finalBodyStr.length;
             const capturedAccountLabel = account.label;
-            Promise.all([telemetry, clientCapture])
-                .then(([data, clientBody]) => {
+            Promise.all([telemetry, clientCapture, streamOutcome])
+                .then(([data, clientBody, rawOutcome]) => {
+                const terminalOutcome = mergeStreamTerminalOutcome(rawOutcome, data.streamErrorMessage);
                 capturedTracer.setUsage({
                     inputTokens: data.usage.inputTokens,
                     outputTokens: data.usage.outputTokens,
@@ -1876,14 +2198,24 @@ function attachAnthropicSuccessStreamTelemetry(args) {
                 capturedTracer.recordMetrics();
                 capturedTracer.recordBodySizes(capturedRequestBytes, data.totalBytesReceived);
                 capturedUpstreamSpan?.end();
-                capturedTracer.end(200, Date.now() - requestStartTime);
-                recordFinalSuccess(capturedAccountLabel, account.type);
-                logFinalRequest(200, capturedAccountLabel, account.type, undefined, undefined, {
+                const failure = getStreamFailureDetails(terminalOutcome);
+                const usage = {
                     inputTokens: data.usage.inputTokens,
                     outputTokens: data.usage.outputTokens,
                     cacheCreationTokens: data.usage.cacheCreationInputTokens,
                     cacheReadTokens: data.usage.cacheReadInputTokens,
-                });
+                };
+                if (failure) {
+                    capturedTracer.setError(failure.errorType, failure.message);
+                    capturedTracer.end(failure.status, Date.now() - requestStartTime);
+                    recordFinalError(failure.status, capturedAccountLabel, account.type);
+                    logFinalRequest(failure.status, capturedAccountLabel, account.type, failure.errorType, failure.message, usage);
+                }
+                else {
+                    capturedTracer.end(200, Date.now() - requestStartTime);
+                    recordFinalSuccess(capturedAccountLabel, account.type);
+                    logFinalRequest(200, capturedAccountLabel, account.type, undefined, undefined, usage);
+                }
                 logProxyBody({
                     phase: "upstream_response",
                     headers: responseHeaders,
@@ -1918,7 +2250,23 @@ function attachAnthropicSuccessStreamTelemetry(args) {
             });
         }
         catch {
-            // Interceptor attachment failed after stream setup; response handling continues.
+            // Interceptor attachment failed after stream setup. Preserve delivery but
+            // still settle the request from the actual stream terminal outcome.
+            streamOutcome.then((outcome) => {
+                const failure = getStreamFailureDetails(outcome);
+                upstreamSpan?.end();
+                if (failure) {
+                    tracer.setError(failure.errorType, failure.message);
+                    tracer.end(failure.status, Date.now() - requestStartTime);
+                    recordFinalError(failure.status, account.label, account.type);
+                    logFinalRequest(failure.status, account.label, account.type, failure.errorType, failure.message);
+                }
+                else {
+                    tracer.end(response.status, Date.now() - requestStartTime);
+                    recordFinalSuccess(account.label, account.type);
+                    logFinalRequest(response.status, account.label, account.type);
+                }
+            });
         }
     }
     else {
@@ -1929,15 +2277,24 @@ function attachAnthropicSuccessStreamTelemetry(args) {
             });
             streamSource = streamSource.pipeThrough(noTracerInterceptor);
             const capturedAccountLabel = account.label;
-            Promise.all([noTracerTelemetry, clientCapture])
-                .then(([data, clientBody]) => {
-                recordFinalSuccess(capturedAccountLabel, account.type);
-                logFinalRequest(200, capturedAccountLabel, account.type, undefined, undefined, {
+            Promise.all([noTracerTelemetry, clientCapture, streamOutcome])
+                .then(([data, clientBody, rawOutcome]) => {
+                const terminalOutcome = mergeStreamTerminalOutcome(rawOutcome, data.streamErrorMessage);
+                const failure = getStreamFailureDetails(terminalOutcome);
+                const usage = {
                     inputTokens: data.usage.inputTokens,
                     outputTokens: data.usage.outputTokens,
                     cacheCreationTokens: data.usage.cacheCreationInputTokens,
                     cacheReadTokens: data.usage.cacheReadInputTokens,
-                });
+                };
+                if (failure) {
+                    recordFinalError(failure.status, capturedAccountLabel, account.type);
+                    logFinalRequest(failure.status, capturedAccountLabel, account.type, failure.errorType, failure.message, usage);
+                }
+                else {
+                    recordFinalSuccess(capturedAccountLabel, account.type);
+                    logFinalRequest(200, capturedAccountLabel, account.type, undefined, undefined, usage);
+                }
                 logProxyBody({
                     phase: "upstream_response",
                     headers: responseHeaders,
@@ -1963,9 +2320,10 @@ function attachAnthropicSuccessStreamTelemetry(args) {
                     durationMs: Date.now() - requestStartTime,
                 });
             })
-                .catch(() => {
-                recordFinalSuccess(account.label, account.type);
-                logFinalRequest(response.status, account.label, account.type);
+                .catch((error) => {
+                const message = error instanceof Error ? error.message : String(error);
+                recordFinalError(500, account.label, account.type);
+                logFinalRequest(500, account.label, account.type, "stream_telemetry_error", message);
             });
         }
         catch {
@@ -1987,8 +2345,17 @@ function attachAnthropicSuccessStreamTelemetry(args) {
                 .catch(() => {
                 // Non-fatal
             });
-            recordFinalSuccess(account.label, account.type);
-            logFinalRequest(response.status, account.label, account.type);
+            streamOutcome.then((outcome) => {
+                const failure = getStreamFailureDetails(outcome);
+                if (failure) {
+                    recordFinalError(failure.status, account.label, account.type);
+                    logFinalRequest(failure.status, account.label, account.type, failure.errorType, failure.message);
+                }
+                else {
+                    recordFinalSuccess(account.label, account.type);
+                    logFinalRequest(response.status, account.label, account.type);
+                }
+            });
         }
     }
     const clientStream = streamSource.pipeThrough(clientCaptureStream);
@@ -2109,7 +2476,14 @@ async function handleAnthropicSuccessfulRetryResponse(args) {
         // stash quota for proactive selection and proactively cool if this
         // response reveals the window flipped to "rejected".
         accountState.quota = retryQuota;
-        maybeCoolFromQuota(accountState, retryQuota, Date.now());
+        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.
+                });
+            }
+        }
         saveAccountQuota(account.label, retryQuota).catch((error) => {
             logger.debug("[proxy] Failed to persist account quota after auth retry", {
                 account: account.label,
@@ -2119,6 +2493,7 @@ async function handleAnthropicSuccessfulRetryResponse(args) {
     }
     if (body.stream && retryResp.body) {
         const retryReader = retryResp.body.getReader();
+        const streamOutcomeTracker = createStreamTerminalOutcomeTracker();
         let retryStreamClosed = false;
         const retryStream = new ReadableStream({
             async pull(controller) {
@@ -2132,6 +2507,7 @@ async function handleAnthropicSuccessfulRetryResponse(args) {
                     }
                     if (done) {
                         retryStreamClosed = true;
+                        streamOutcomeTracker.complete();
                         controller.close();
                         return;
                     }
@@ -2140,6 +2516,7 @@ async function handleAnthropicSuccessfulRetryResponse(args) {
                 catch (streamErr) {
                     const errMsg = streamErr instanceof Error ? streamErr.message : String(streamErr);
                     logger.always(`[proxy] mid-stream error (auth-retry) account=${account.label}: ${errMsg}`);
+                    streamOutcomeTracker.fail(errMsg);
                     logStreamError({
                         timestamp: new Date().toISOString(),
                         requestId: ctx.requestId,
@@ -2158,74 +2535,23 @@ async function handleAnthropicSuccessfulRetryResponse(args) {
             },
             cancel() {
                 retryStreamClosed = true;
-                retryReader.cancel();
+                streamOutcomeTracker.cancel();
+                return retryReader.cancel();
             },
         });
-        let retryClientStream = retryStream;
-        if (tracer) {
-            try {
-                const { stream: retryInterceptor, telemetry: retryTelemetry } = createSSEInterceptor();
-                retryClientStream = retryStream.pipeThrough(retryInterceptor);
-                const capturedTracer = tracer;
-                const capturedUpstreamSpan = upstreamSpan;
-                const capturedRetryResp = retryResp;
-                const capturedRetryRequestBytes = finalBodyStr.length;
-                const capturedAccountLabel = account.label;
-                retryTelemetry
-                    .then((data) => {
-                    capturedTracer.setUsage({
-                        inputTokens: data.usage.inputTokens,
-                        outputTokens: data.usage.outputTokens,
-                        cacheCreationTokens: data.usage.cacheCreationInputTokens,
-                        cacheReadTokens: data.usage.cacheReadInputTokens,
-                    });
-                    capturedTracer.logStreamEvents(data.events);
-                    capturedTracer.setResponseInfo(responseInfoFromStream(data));
-                    capturedTracer.logUpstreamResponseHeaders(Object.fromEntries([...capturedRetryResp.headers.entries()]));
-                    capturedTracer.recordMetrics();
-                    capturedTracer.recordBodySizes(capturedRetryRequestBytes, data.totalBytesReceived);
-                    capturedUpstreamSpan?.end();
-                    capturedTracer.end(200, Date.now() - requestStartTime);
-                    recordFinalSuccess(capturedAccountLabel, account.type);
-                    logFinalRequest(200, capturedAccountLabel, account.type, undefined, undefined, {
-                        inputTokens: data.usage.inputTokens,
-                        outputTokens: data.usage.outputTokens,
-                        cacheCreationTokens: data.usage.cacheCreationInputTokens,
-                        cacheReadTokens: data.usage.cacheReadInputTokens,
-                    });
-                })
-                    .catch((error) => {
-                    capturedTracer.setError("stream_error", error instanceof Error ? error.message : String(error));
-                    capturedUpstreamSpan?.end();
-                    capturedTracer.end(500, Date.now() - requestStartTime);
-                    recordFinalError(500, capturedAccountLabel, account.type);
-                    logFinalRequest(500, capturedAccountLabel, account.type, "stream_error", error instanceof Error ? error.message : String(error));
-                });
-            }
-            catch {
-                retryClientStream = retryStream;
-            }
-        }
-        const responseHeaders = {
-            "content-type": "text/event-stream",
-            "cache-control": "no-cache",
-            connection: "keep-alive",
-        };
-        for (const headerName of [
-            "retry-after",
-            "anthropic-ratelimit-requests-remaining",
-            "anthropic-ratelimit-requests-limit",
-            "anthropic-ratelimit-tokens-remaining",
-            "anthropic-ratelimit-tokens-limit",
-        ]) {
-            const value = retryResp.headers.get(headerName);
-            if (value) {
-                responseHeaders[headerName] = value;
-            }
-        }
-        return new Response(retryClientStream, {
-            status: retryResp.status,
-            headers: responseHeaders,
+        return attachAnthropicSuccessStreamTelemetry({
+            account,
+            response: retryResp,
+            responseHeaders: Object.fromEntries([...retryResp.headers.entries()]),
+            remainingStream: retryStream,
+            streamOutcome: streamOutcomeTracker.outcome,
+            tracer,
+            requestStartTime,
+            attemptNumber,
+            finalBodyStr,
+            upstreamSpan,
+            logProxyBody,
+            logFinalRequest,
         });
     }
     const retryRespHeaders = Object.fromEntries([...retryResp.headers.entries()]);
@@ -2303,24 +2629,24 @@ async function handleAnthropicAuthRetry(args) {
         logger.always(`[proxy] ← 401 account=${account.label} refreshing (attempt ${authRetry + 1}/${MAX_AUTH_RETRIES})`);
         const refreshSucceeded = await refreshToken(account);
         if (!refreshSucceeded.success) {
-            accountState.consecutiveRefreshFailures += 1;
             authRetryError = `refresh failed for account=${account.label} attempt ${authRetry + 1}/${MAX_AUTH_RETRIES}: ${refreshSucceeded.error?.slice(0, 200) ?? "unknown"}`;
             currentLastError = authRetryError;
-            logger.always(`[proxy] ⚠ account=${account.label} refresh failed on attempt ${authRetry + 1}`);
-            if (accountState.consecutiveRefreshFailures >=
-                MAX_CONSECUTIVE_REFRESH_FAILURES) {
-                await disableAccountUntilReauth(account, accountState);
+            if (isPermanentRefreshFailure(refreshSucceeded)) {
+                await disableAccountUntilReauth(account, accountState, "refresh_invalid");
                 currentAuthFailureMessage = formatReauthMessage(account.label);
-                break;
+                logger.always(`[proxy] account=${account.label} refresh token rejected; disabled until re-authentication`);
             }
-            if (authRetry < MAX_AUTH_RETRIES - 1) {
-                await sleep(2000);
+            else {
+                const coolingUntil = await coolAccountAfterTransientRefreshFailure(account, accountState);
+                currentSawTransientFailure = true;
+                logger.always(`[proxy] account=${account.label} refresh temporarily unavailable (${refreshSucceeded.status ?? "network"}); cooling until ${new Date(coolingUntil).toISOString()} and rotating`);
             }
-            continue;
+            break;
         }
         if (account.persistTarget) {
             await persistTokens(account.persistTarget, account);
         }
+        await clearAuthCooldownAfterRefresh(account, accountState);
         headers.authorization = `Bearer ${account.token}`;
         try {
             const retryResp = await fetch("https://api.anthropic.com/v1/messages?beta=true", {
@@ -2407,12 +2733,20 @@ async function handleAnthropicAuthRetry(args) {
                 if (retryQuota429) {
                     accountState.quota = retryQuota429;
                 }
-                const retryPlan = planCooldownFor429(retryQuota429, parseRetryAfterMs(retryRespHeaders["retry-after"] ?? null), nowRetry);
+                const retryPlan = planCooldownFor429(retryQuota429, parseRetryAfterMs(retryRespHeaders["retry-after"] ?? null), nowRetry, getUnifiedRateLimitStatus(retryRespHeaders));
                 if (!accountState.coolingUntil ||
                     retryPlan.coolingUntil > accountState.coolingUntil) {
                     accountState.coolingUntil = retryPlan.coolingUntil;
                     accountState.coolingReason = retryPlan.reason;
                 }
+                if (retryQuota429) {
+                    saveAccountQuota(account.label, retryQuota429).catch(() => {
+                        // Non-fatal: routing already has the in-memory snapshot.
+                    });
+                }
+                await saveAccountCooldown(account.key, accountState.coolingUntil ?? retryPlan.coolingUntil, accountState.coolingReason ?? retryPlan.reason).catch(() => {
+                    // Non-fatal: routing already has the in-memory cooldown.
+                });
                 advancePrimaryIfCurrent(account.key, enabledAccounts.length, orderedAccounts[0]?.key);
                 break;
             }
@@ -2529,7 +2863,7 @@ function buildAnthropicTerminalErrorResponse(args) {
     }
 }
 async function handleAnthropicNonOkResponse(args) {
-    const { response, account, accountState, enabledAccounts, orderedAccounts, tracer, requestStartTime, fetchStartMs, attemptNumber, logAttempt, logProxyBody, logFinalRequest, lastError, authFailureMessage, sawTransientFailure, invalidRequestFailure, maxConsecutiveRefreshFailures, } = args;
+    const { response, account, accountState, enabledAccounts, orderedAccounts, tracer, requestStartTime, fetchStartMs, attemptNumber, logAttempt, logProxyBody, logFinalRequest, lastError, authFailureMessage, sawTransientFailure, invalidRequestFailure, } = args;
     let currentLastError = lastError;
     let currentAuthFailureMessage = authFailureMessage;
     let currentSawTransientFailure = sawTransientFailure;
@@ -2578,10 +2912,7 @@ async function handleAnthropicNonOkResponse(args) {
         account.type === "oauth" &&
         !account.refreshToken) {
         recordAttemptError(account.label, account.type, response.status);
-        accountState.consecutiveRefreshFailures += 1;
-        if (accountState.consecutiveRefreshFailures >= maxConsecutiveRefreshFailures) {
-            await disableAccountUntilReauth(account, accountState);
-        }
+        await disableAccountUntilReauth(account, accountState, "missing_refresh_token");
         currentAuthFailureMessage = formatReauthMessage(account.label);
         logger.always(`[proxy] ← ${response.status} account=${account.label} (auth failure, no refresh token)`);
         currentLastError = errBody;
@@ -2847,23 +3178,25 @@ async function prepareAnthropicAccountAttempt(args) {
             if (account.persistTarget) {
                 await persistTokens(account.persistTarget, account);
             }
-            accountState.consecutiveRefreshFailures = 0;
+            await clearAuthCooldownAfterRefresh(account, accountState);
         }
         else {
-            accountState.consecutiveRefreshFailures += 1;
             lastError = `token refresh failed for account=${account.label}: ${refreshed.error?.slice(0, 200) ?? "unknown"}`;
-            logger.debug(`[proxy] preflight refresh failed account=${account.label} failures=${accountState.consecutiveRefreshFailures}`);
-            if (accountState.consecutiveRefreshFailures >=
-                MAX_CONSECUTIVE_REFRESH_FAILURES) {
-                await disableAccountUntilReauth(account, accountState);
+            if (isPermanentRefreshFailure(refreshed)) {
+                await disableAccountUntilReauth(account, accountState, "refresh_invalid");
                 authFailureMessage = formatReauthMessage(account.label);
-                logAttempt(401, "authentication_error", String(lastError));
-                return {
-                    continueLoop: true,
-                    lastError,
-                    authFailureMessage,
-                };
             }
+            else {
+                await coolAccountAfterTransientRefreshFailure(account, accountState);
+            }
+            logAttempt(isPermanentRefreshFailure(refreshed) ? 401 : 503, isPermanentRefreshFailure(refreshed)
+                ? "authentication_error"
+                : "token_refresh_unavailable", String(lastError));
+            return {
+                continueLoop: true,
+                lastError,
+                authFailureMessage,
+            };
         }
     }
     const isOAuth = account.type === "oauth";
@@ -3103,10 +3436,12 @@ async function fetchAnthropicAccountResponse(args) {
         // ACTUAL reset, not a 60s hardcap.
         const now = Date.now();
         const quota = parseQuotaHeaders(errRespHeaders);
-        const cooldownPlan = planCooldownFor429(quota, retryAfterMs, now);
+        const unifiedStatus = getUnifiedRateLimitStatus(errRespHeaders);
+        const cooldownPlan = planCooldownFor429(quota, retryAfterMs, now, unifiedStatus);
         logger.always(`[proxy] ← 429 account=${account.label} reason=${cooldownPlan.reason} ` +
             `retry-after=${retryAfterMs}ms 5h-status=${errRespHeaders["anthropic-ratelimit-unified-5h-status"] ?? "unknown"} ` +
             `7d-status=${errRespHeaders["anthropic-ratelimit-unified-7d-status"] ?? "unknown"} ` +
+            `unified-status=${unifiedStatus ?? "unknown"} ` +
             `→ ${cooldownPlan.rotateImmediately ? `rotate now, cool ${minutesUntil(cooldownPlan.coolingUntil, now)}m` : "retry same account (transient)"}`);
         logAttempt(429, "rate_limit_error", String(lastError));
         tracer?.setError("rate_limit_error", String(lastError).slice(0, 500));
@@ -3155,6 +3490,7 @@ async function handleAnthropicRoutedClaudeRequest(args) {
         sawTransientFailure: false,
         invalidRequestFailure: null,
         authFailureMessage: null,
+        authCooldownMessage: null,
         attemptNumber: 0,
     };
     const acctSelectionSpan = tracer?.startAccountSelection();
@@ -3167,10 +3503,24 @@ async function handleAnthropicRoutedClaudeRequest(args) {
     if (!usingQuotaOrder) {
         maybeResetPrimaryToHome(enabledAccounts);
     }
-    // Skip accounts that are still cooling from a recent 429-exhaustion,
-    // but keep them as last-resort if ALL accounts are cooling.
+    // Never re-hammer accounts with a known active cooldown. When every account
+    // 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.length > 0 ? nonCoolingAccounts : orderedAccounts;
+    const effectiveAccounts = nonCoolingAccounts;
+    if (effectiveAccounts.length === 0 && orderedAccounts.length > 0) {
+        const coolingStates = orderedAccounts.map((account) => getOrCreateRuntimeState(account.key));
+        const hasRateLimitCooldown = coolingStates.some((state) => state.coolingReason !== "auth");
+        loopState.sawRateLimit = hasRateLimitCooldown;
+        loopState.sawTransientFailure = !hasRateLimitCooldown;
+        loopState.lastError = hasRateLimitCooldown
+            ? "All Anthropic accounts have active rate-limit cooldowns"
+            : "All Anthropic accounts have active authentication cooldowns";
+        if (!hasRateLimitCooldown) {
+            const earliestRetryAt = Math.min(...coolingStates.map((state) => state.coolingUntil ?? Number.POSITIVE_INFINITY));
+            loopState.authCooldownMessage = `All ${orderedAccounts.length} Anthropic accounts are temporarily unavailable while OAuth refresh is cooling. Earliest retry at ${new Date(earliestRetryAt).toISOString()}.`;
+        }
+    }
     accountLoop: for (const account of effectiveAccounts) {
         const accountState = getOrCreateRuntimeState(account.key);
         let transientSameAccountRetries = 0;
@@ -3247,6 +3597,9 @@ async function handleAnthropicRoutedClaudeRequest(args) {
                     // Refresh the account's quota snapshot for proactive selection.
                     if (fetchResult.quota) {
                         accountState.quota = fetchResult.quota;
+                        saveAccountQuota(account.label, fetchResult.quota).catch(() => {
+                            // 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
@@ -3271,6 +3624,9 @@ async function handleAnthropicRoutedClaudeRequest(args) {
                         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.
+                    });
                     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;
@@ -3350,7 +3706,6 @@ async function handleAnthropicRoutedClaudeRequest(args) {
                     authFailureMessage: loopState.authFailureMessage,
                     sawTransientFailure: loopState.sawTransientFailure,
                     invalidRequestFailure: loopState.invalidRequestFailure,
-                    maxConsecutiveRefreshFailures: MAX_CONSECUTIVE_REFRESH_FAILURES,
                 });
                 loopState.lastError = nonOkResult.lastError;
                 loopState.authFailureMessage = nonOkResult.authFailureMessage;
@@ -3382,8 +3737,12 @@ async function handleAnthropicRoutedClaudeRequest(args) {
             // window flipped to "rejected" on this very request.
             if (accountState.coolingUntil &&
                 Date.now() >= accountState.coolingUntil) {
+                const expiredCooldown = accountState.coolingUntil;
                 accountState.coolingUntil = undefined;
                 accountState.coolingReason = undefined;
+                clearAccountCooldown(account.key, expiredCooldown).catch(() => {
+                    // Best-effort cleanup; expired entries are ignored during seeding.
+                });
             }
             const successResult = await handleAnthropicSuccessfulResponse({
                 ctx,
@@ -3441,6 +3800,7 @@ async function handleAnthropicRoutedClaudeRequest(args) {
         tracer,
         requestStartTime,
         authFailureMessage: loopState.authFailureMessage,
+        authCooldownMessage: loopState.authCooldownMessage,
         invalidRequestFailure: loopState.invalidRequestFailure,
         sawNetworkError: loopState.sawNetworkError,
         sawTransientFailure: loopState.sawTransientFailure,
@@ -3465,8 +3825,11 @@ async function handleAnthropicRoutedClaudeRequest(args) {
  * @param basePath    - Base path prefix (default: "" since Claude API uses /v1/...).
  * @returns RouteGroup with Claude-compatible endpoints.
  */
-export function createClaudeProxyRoutes(modelRouter, basePath = "", accountStrategy = "fill-first", passthroughMode = false, primaryAccountKey) {
+export function createClaudeProxyRoutes(modelRouter, basePath = "", accountStrategy = "fill-first", passthroughMode = false, primaryAccountKey, accountAllowlist) {
     configuredPrimaryAccountKey = primaryAccountKey;
+    configuredAccountAllowlist = accountAllowlist
+        ? new Set(accountAllowlist)
+        : undefined;
     return {
         prefix: `${basePath}/v1`,
         routes: [
@@ -3630,18 +3993,48 @@ function getOrCreateRuntimeState(accountKey) {
     accountRuntimeState.set(accountKey, initial);
     return initial;
 }
-async function disableAccountUntilReauth(account, state) {
+async function disableAccountUntilReauth(account, state, reason) {
     state.permanentlyDisabled = true;
     // Decision 7 (usage): Persist disabled state to disk so it survives restarts
     try {
         const { tokenStore } = await import("../../auth/tokenStore.js");
-        await tokenStore.markDisabled(account.key, "refresh_failed");
+        await tokenStore.markDisabled(account.key, reason);
     }
     catch (e) {
         logger.debug(`[proxy] failed to persist disabled state for ${account.label}: ${e instanceof Error ? e.message : String(e)}`);
     }
     logger.always(`[proxy] account=${account.label} disabled until re-authentication. Run: neurolink auth login anthropic --method oauth`);
 }
+async function coolAccountAfterTransientRefreshFailure(account, state) {
+    state.consecutiveRefreshFailures += 1;
+    const exponent = Math.min(state.consecutiveRefreshFailures - 1, 4);
+    const delayMs = Math.min(AUTH_REFRESH_MAX_COOLDOWN_MS, AUTH_REFRESH_BASE_COOLDOWN_MS * 2 ** exponent);
+    const coolingUntil = Date.now() + delayMs;
+    if (!state.coolingUntil || coolingUntil > state.coolingUntil) {
+        state.coolingUntil = coolingUntil;
+        state.coolingReason = "auth";
+    }
+    const effectiveCoolingUntil = state.coolingUntil ?? coolingUntil;
+    const effectiveReason = state.coolingReason ?? "auth";
+    state.coolingUntil = effectiveCoolingUntil;
+    state.coolingReason = effectiveReason;
+    await saveAccountCooldown(account.key, effectiveCoolingUntil, effectiveReason).catch(() => {
+        // Non-fatal: the in-memory cooldown still prevents immediate re-hammering.
+    });
+    return effectiveCoolingUntil;
+}
+async function clearAuthCooldownAfterRefresh(account, state) {
+    state.consecutiveRefreshFailures = 0;
+    if (state.coolingReason !== "auth" || !state.coolingUntil) {
+        return;
+    }
+    const previousCoolingUntil = state.coolingUntil;
+    state.coolingUntil = undefined;
+    state.coolingReason = undefined;
+    await clearAccountCooldown(account.key, previousCoolingUntil).catch(() => {
+        // Best-effort cleanup; an expired auth cooldown is harmless on next boot.
+    });
+}
 function formatReauthMessage(labels) {
     const value = Array.isArray(labels) ? labels.join(", ") : labels;
     return `Account(s) require re-authentication: ${value}. Run: neurolink auth login anthropic --method oauth`;
@@ -3814,6 +4207,9 @@ export const __testHooks = {
     resolveHomeIndex,
     maybeResetPrimaryToHome,
     planCooldownFor429,
+    isPermanentRefreshFailure,
+    getStreamFailureDetails,
+    trackUpstreamReadableStream,
     orderAccountsByQuota,
     resetEpochToMs,
     seedRuntimeQuotasFromDisk,
@@ -3825,6 +4221,10 @@ export const __testHooks = {
         configuredPrimaryAccountKey = key;
     },
     getConfiguredPrimaryAccountKey: () => configuredPrimaryAccountKey,
+    setConfiguredAccountAllowlist: (allowlist) => {
+        configuredAccountAllowlist = allowlist ? new Set(allowlist) : undefined;
+    },
+    getConfiguredAccountAllowlist: () => configuredAccountAllowlist ? [...configuredAccountAllowlist] : undefined,
     setPrimaryAccountIndex: (index) => {
         primaryAccountIndex = index;
     },
@@ -3839,6 +4239,7 @@ export const __testHooks = {
         primaryAccountIndex = 0;
         lastKnownAccountCount = 0;
         configuredPrimaryAccountKey = undefined;
+        configuredAccountAllowlist = undefined;
     },
 };
 //# sourceMappingURL=claudeProxyRoutes.js.map