@timo972/cc-router 0.10.1 → 0.11.0-rc.0

package/dist/proxy/openai-ingress.js

@@ -6,6 +6,7 @@ import { stats, boundModelId, createLocalRoutingErrorLog } from "./stats.js";
 import { logError } from "./logger.js";
 import { EmptyPoolError, NoEligibleAccountError } from "./account-pool.js";
 import { acquireRequestRoute, routeReasonDetails, routeFailureDetails } from "./lease-lifecycle.js";
+import { MAX_UPSTREAM_ATTEMPTS, RETRY_REFRESH_TIMEOUT_MS, SAME_ACCOUNT_RETRY_DELAY_MS, boundedWait, isRetryableUpstreamStatus, retryDelay, } from "./upstream-retry.js";
 /**
  * Mirrors `anthropic-routing.ts`'s `requestTerminated` check. This ingress
  * path never threads the raw `Request` through (only `Response`), so it
@@ -158,46 +159,64 @@ export async function runOpenAIIngress(opts) {
         res.status(500).json(envelope.wrap("proxy_error", "Unexpected routing error"));
         return;
     }
-    const account = selected.route.account;
     const startedAt = now();
-    const needed = needsOpenAIRefresh(account);
-    let ready;
-    try {
-        ready = await prepareOpenAIAccount(account);
-    }
-    catch (error) {
-        // A throwing refresh must behave exactly like a `false` return, never
-        // crash the request (or the daemon).
-        const message = error instanceof Error ? error.message : String(error);
-        logError(account.id, 401, `openai token refresh threw: ${message}`);
-        ready = false;
-    }
-    if (!ready) {
-        selected.release();
-        account.errorCount++;
-        stats.totalErrors++;
-        // Intentionally does not touch `account.healthy`: a single failed
-        // refresh fails only this request. Disabling the account here would
-        // hard-block it from every future request until a manual recovery, even
-        // though the very next request naturally retries the refresh.
-        //
-        // It must, however, break session affinity and cool the account down.
-        // A sticky binding survives this failure, so without both the session
-        // would re-acquire the same broken account on every retry and never fail
-        // over — 401ing forever while healthy accounts sit idle.
-        if (selected.route.sessionId !== undefined && selected.route.bindingGeneration !== undefined) {
-            openAIRouter.invalidate(selected.route.sessionId, account.id, selected.route.bindingGeneration);
+    const maxAttempts = Math.max(1, opts.maxAttempts ?? MAX_UPSTREAM_ATTEMPTS);
+    const sameAccountDelayMs = opts.sameAccountRetryDelayMs ?? SAME_ACCOUNT_RETRY_DELAY_MS;
+    const retryRefreshTimeoutMs = opts.retryRefreshTimeoutMs ?? RETRY_REFRESH_TIMEOUT_MS;
+    /**
+     * Refresh a routed account's token if needed. On failure this applies the
+     * shared refresh-failure bookkeeping and returns false; what the caller
+     * sends instead is its own decision — the first attempt answers a local
+     * 401, a retry attempt relays the upstream failure it already holds.
+     */
+    const prepareRoute = async (routed) => {
+        const account = routed.route.account;
+        const needed = needsOpenAIRefresh(account);
+        let ready;
+        try {
+            ready = await prepareOpenAIAccount(account);
         }
-        openAIPool.setGlobalCooldownForAccount(account, REFRESH_FAILURE_COOLDOWN_MS, "unavailable");
-        recordActivity({
-            ts: now(),
-            accountId: account.id,
-            model: requestedModel,
-            type: "error",
-            statusCode: 401,
-            path,
-            details: "openai token refresh failed",
-        });
+        catch (error) {
+            // A throwing refresh must behave exactly like a `false` return, never
+            // crash the request (or the daemon).
+            const message = error instanceof Error ? error.message : String(error);
+            logError(account.id, 401, `openai token refresh threw: ${message}`);
+            ready = false;
+        }
+        if (!ready) {
+            routed.release();
+            account.errorCount++;
+            stats.totalErrors++;
+            // Intentionally does not touch `account.healthy`: a single failed
+            // refresh fails only this request. Disabling the account here would
+            // hard-block it from every future request until a manual recovery, even
+            // though the very next request naturally retries the refresh.
+            //
+            // It must, however, break session affinity and cool the account down.
+            // A sticky binding survives this failure, so without both the session
+            // would re-acquire the same broken account on every retry and never fail
+            // over — 401ing forever while healthy accounts sit idle.
+            if (routed.route.sessionId !== undefined && routed.route.bindingGeneration !== undefined) {
+                openAIRouter.invalidate(routed.route.sessionId, account.id, routed.route.bindingGeneration);
+            }
+            openAIPool.setGlobalCooldownForAccount(account, REFRESH_FAILURE_COOLDOWN_MS, "unavailable");
+            recordActivity({
+                ts: now(),
+                accountId: account.id,
+                model: requestedModel,
+                type: "error",
+                statusCode: 401,
+                path,
+                details: "openai token refresh failed",
+            });
+            return false;
+        }
+        account.healthy = true;
+        if (needed)
+            account.lastRefresh = now();
+        return true;
+    };
+    if (!(await prepareRoute(selected))) {
         res.status(401).json(envelope.wrap("authentication_error", "OpenAI subscription token refresh failed"));
         return;
     }
@@ -210,88 +229,168 @@ export async function runOpenAIIngress(opts) {
         selected.release();
         return;
     }
-    account.healthy = true;
-    if (needed)
-        account.lastRefresh = now();
     let upstream;
-    try {
-        upstream = await forwardOpenAI({
-            account,
-            body: forwardBody,
-            stream: forwardBody.stream === true,
-            signal: clientGone.signal,
-        });
-    }
-    catch (error) {
-        // A client that hung up mid-forward rejects this call through the abort
-        // above. That is a cancellation, not an upstream failure: the account did
-        // nothing wrong, so counting it would push a healthy account toward the
-        // unhealthy threshold and a cooldown for nothing more than a user pressing
-        // Ctrl-C, and there is no client left to receive a 502 or to whom an
-        // "upstream_error:network" entry would mean anything. Mirrors the
-        // pre-forward disconnect branch above, which also just releases and stops.
-        if (clientGone.signal.aborted || responseTerminated(res)) {
-            selected.release();
+    let upstreamFailed;
+    let details;
+    let accountFailureCounted;
+    for (let attempt = 1;; attempt++) {
+        const account = selected.route.account;
+        const attemptStartedAt = now();
+        try {
+            upstream = await forwardOpenAI({
+                account,
+                body: forwardBody,
+                stream: forwardBody.stream === true,
+                signal: clientGone.signal,
+            });
+        }
+        catch (error) {
+            // A client that hung up mid-forward rejects this call through the abort
+            // above. That is a cancellation, not an upstream failure: the account did
+            // nothing wrong, so counting it would push a healthy account toward the
+            // unhealthy threshold and a cooldown for nothing more than a user pressing
+            // Ctrl-C, and there is no client left to receive a 502 or to whom an
+            // "upstream_error:network" entry would mean anything. Mirrors the
+            // pre-forward disconnect branch above, which also just releases and stops.
+            if (clientGone.signal.aborted || responseTerminated(res)) {
+                selected.release();
+                return;
+            }
+            // A rejected forward call (network failure) must produce a local 502,
+            // never an unhandled rejection. The lease releases via the response's
+            // own finish/close lifecycle once this response is sent.
+            account.errorCount++;
+            stats.totalErrors++;
+            const message = error instanceof Error ? error.message : String(error);
+            logError(account.id, 502, `openai request failed: ${message}`);
+            recordActivity({
+                ts: startedAt,
+                accountId: account.id,
+                model: requestedModel,
+                type: "error",
+                statusCode: 502,
+                path,
+                details: "upstream_error:network",
+                durationMs: now() - startedAt,
+            });
+            res.status(502).json(envelope.wrap("upstream_error", `OpenAI request failed: ${message}`));
             return;
         }
-        // A rejected forward call (network failure) must produce a local 502,
-        // never an unhandled rejection. The lease releases via the response's
-        // own finish/close lifecycle once this response is sent.
-        account.errorCount++;
+        // Cooldown/eligibility react to the raw upstream signal — this must not
+        // change based on how the relay later renders the response to the client.
+        upstreamFailed = upstream.status === 401 || upstream.status === 429 || upstream.status >= 500;
+        details = routeReasonDetails(selected.route);
+        // Tracks whether `account.errorCount`/`consecutiveErrors` were already
+        // incremented for this request by the upstream-classification branch below,
+        // so a relay-synthesized failure (e.g. a byte-transparent stream that
+        // observed an upstream `response.failed`/`error` event on an otherwise-200
+        // response) can still increment them once further down without double
+        // counting an upstream 401/429/5xx that already did.
+        accountFailureCounted = false;
+        try {
+            // Header/rate-limit parsing and cooldown bookkeeping run on live upstream
+            // data between the two request-level try/catches above — a throw here
+            // (e.g. an unreadable header) must degrade to "skip this bookkeeping",
+            // never crash the daemon or leave the relay below un-reached.
+            const headerRecord = headersToRecord(upstream.headers);
+            applyCodexRateLimits(account, parseCodexRateLimits(headerRecord, now()), now());
+            if (upstreamFailed) {
+                account.errorCount++;
+                account.consecutiveErrors++;
+                accountFailureCounted = true;
+                const applied = applyCodexFailureRouting(upstream.status, headerRecord, selected.route, requestedModel, openAIRouter, openAIPool, now);
+                details = routeFailureDetails(selected.route, upstream.status === 401 ? "token-invalid"
+                    : upstream.status === 429 ? "rate-limited"
+                        // Only 503/529 are treated as upstream overload for cooldown
+                        // purposes; labelling an isolated 500/502/504 "service-overloaded"
+                        // would contradict the routing decision actually taken.
+                        : upstream.status === 503 || upstream.status === 529 ? "service-overloaded"
+                            : "upstream-error", applied.limitingScope);
+                if (upstream.status === 401)
+                    onUpstreamAuthFailure?.(account);
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            logError(account.id, upstream.status, `openai response classification failed: ${message}`);
+        }
+        // Retryable statuses (429 || >= 500) are a strict subset of
+        // `upstreamFailed`, so this predicate alone decides the loop.
+        if (!isRetryableUpstreamStatus(upstream.status)
+            || attempt >= maxAttempts || clientGone.signal.aborted) {
+            break;
+        }
+        // Router-side failover/retry. The failure bookkeeping above already ran
+        // (cooldown, affinity break, error counters), and not a single response
+        // byte has been relayed, so the request can move to whichever account the
+        // pool would hand a brand-new request: a different one after a 429 or
+        // 503/529 cooldown, the same one after a plain 5xx. Everything is decided
+        // BEFORE the held failure response is abandoned — any dead end below
+        // still relays the original upstream failure unchanged.
+        let next;
+        try {
+            next = acquireRequestRoute(sessionKey, res, openAIRouter, { requestedModel });
+        }
+        catch (error) {
+            // Nothing eligible to fail over to — pass the failure through. Only
+            // routing-level rejections are expected here; anything else is a bug
+            // worth a log line, though pass-through stays the safe outcome.
+            if (!(error instanceof NoEligibleAccountError) && !(error instanceof EmptyPoolError)) {
+                const message = error instanceof Error ? error.message : String(error);
+                logError("proxy", 500, `unexpected routing failure during retry: ${message}`);
+            }
+            break;
+        }
+        if (upstream.status === 429 && next.route.account.id === account.id) {
+            // Re-sending a 429 to the account that produced it would only
+            // reproduce the rate limit. The cooldown normally guarantees a
+            // different account here; if it ever does not, pass through instead.
+            next.release();
+            break;
+        }
+        // Same bound as the Anthropic route: the held failure is ready to relay
+        // and the refresh fetch has no deadline of its own, so an unbounded wait
+        // here could withhold it for minutes. The refresh is not cancelled — a
+        // late outcome still runs prepareRoute's own bookkeeping in the
+        // background and readies (or cools down) the account for later requests.
+        const prepared = await boundedWait(prepareRoute(next), retryRefreshTimeoutMs, "still-pending", clientGone.signal);
+        if (prepared === "still-pending") {
+            if (!clientGone.signal.aborted) {
+                logError(next.route.account.id, 0, `failover token refresh still pending after ${retryRefreshTimeoutMs}ms — relaying held upstream failure`);
+            }
+            next.release();
+            break;
+        }
+        if (!prepared)
+            break;
+        // Committed: record the failed attempt and abandon its response.
         stats.totalErrors++;
-        const message = error instanceof Error ? error.message : String(error);
-        logError(account.id, 502, `openai request failed: ${message}`);
         recordActivity({
-            ts: startedAt,
+            ts: attemptStartedAt,
             accountId: account.id,
             model: requestedModel,
             type: "error",
-            statusCode: 502,
+            statusCode: upstream.status,
             path,
-            details: "upstream_error:network",
-            durationMs: now() - startedAt,
+            ...(opts.method !== undefined ? { method: opts.method } : {}),
+            ...(opts.source !== undefined ? { source: opts.source } : {}),
+            details: `${details}:will-retry`,
+            durationMs: now() - attemptStartedAt,
         });
-        res.status(502).json(envelope.wrap("upstream_error", `OpenAI request failed: ${message}`));
-        return;
-    }
-    // Cooldown/eligibility react to the raw upstream signal — this must not
-    // change based on how the relay later renders the response to the client.
-    const upstreamFailed = upstream.status === 401 || upstream.status === 429 || upstream.status >= 500;
-    let details = routeReasonDetails(selected.route);
-    // Tracks whether `account.errorCount`/`consecutiveErrors` were already
-    // incremented for this request by the upstream-classification branch below,
-    // so a relay-synthesized failure (e.g. a byte-transparent stream that
-    // observed an upstream `response.failed`/`error` event on an otherwise-200
-    // response) can still increment them once further down without double
-    // counting an upstream 401/429/5xx that already did.
-    let accountFailureCounted = false;
-    try {
-        // Header/rate-limit parsing and cooldown bookkeeping run on live upstream
-        // data between the two request-level try/catches above — a throw here
-        // (e.g. an unreadable header) must degrade to "skip this bookkeeping",
-        // never crash the daemon or leave the relay below un-reached.
-        const headerRecord = headersToRecord(upstream.headers);
-        applyCodexRateLimits(account, parseCodexRateLimits(headerRecord, now()), now());
-        if (upstreamFailed) {
-            account.errorCount++;
-            account.consecutiveErrors++;
-            accountFailureCounted = true;
-            const applied = applyCodexFailureRouting(upstream.status, headerRecord, selected.route, requestedModel, openAIRouter, openAIPool, now);
-            details = routeFailureDetails(selected.route, upstream.status === 401 ? "token-invalid"
-                : upstream.status === 429 ? "rate-limited"
-                    // Only 503/529 are treated as upstream overload for cooldown
-                    // purposes; labelling an isolated 500/502/504 "service-overloaded"
-                    // would contradict the routing decision actually taken.
-                    : upstream.status === 503 || upstream.status === 529 ? "service-overloaded"
-                        : "upstream-error", applied.limitingScope);
-            if (upstream.status === 401)
-                onUpstreamAuthFailure?.(account);
+        void upstream.body?.cancel().catch(() => { });
+        selected.release();
+        const sameAccount = next.route.account.id === account.id;
+        selected = next;
+        // An immediate same-account replay would hit whatever transient condition
+        // produced the 5xx still in progress; a failover needs no pause.
+        if (sameAccount)
+            await retryDelay(sameAccountDelayMs, clientGone.signal);
+        if (clientGone.signal.aborted || responseTerminated(res)) {
+            selected.release();
+            return;
         }
     }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        logError(account.id, upstream.status, `openai response classification failed: ${message}`);
-    }
+    const account = selected.route.account;
     const entry = {
         ts: startedAt,
         accountId: account.id,

package/dist/proxy/responses-server.js

@@ -136,6 +136,13 @@ export function mountResponsesRoutes(app, opts) {
             now,
             envelope: RESPONSES_ENVELOPE,
             onUpstreamAuthFailure: opts.onUpstreamAuthFailure,
+            ...(opts.maxAttempts !== undefined ? { maxAttempts: opts.maxAttempts } : {}),
+            ...(opts.sameAccountRetryDelayMs !== undefined
+                ? { sameAccountRetryDelayMs: opts.sameAccountRetryDelayMs }
+                : {}),
+            ...(opts.retryRefreshTimeoutMs !== undefined
+                ? { retryRefreshTimeoutMs: opts.retryRefreshTimeoutMs }
+                : {}),
             relay: async (upstream, res, entry, report) => {
                 if (body.stream === true) {
                     const observer = createCodexUsageObserver();

package/dist/proxy/server.js

@@ -4,12 +4,14 @@ import { ServerResponse } from "http";
 import { timingSafeEqual } from "crypto";
 import { TokenPool } from "./token-pool.js";
 import { needsRefresh, refreshAccountIfCurrent, saveAccounts, startRefreshLoop } from "./token-refresher.js";
-import { loadAccounts, loadOpenAIAccounts, saveOpenAIAccountsToPath, accountsFileExists, readAccountsFromPath, readConfig, writeConfig, getProxyRequestTimeoutMs, migrateLegacyAccountProviders, setProviderAccountsEnabled } from "../config/manager.js";
+import { loadAccounts, loadOpenAIAccounts, saveOpenAIAccountsToPath, accountsFileExists, readAccountsFromPath, readConfig, writeConfig, getAutoFailoverEnabled, getProxyRequestTimeoutMs, migrateLegacyAccountProviders, setProviderAccountsEnabled } from "../config/manager.js";
 import { checkForUpdate, performUpdate, restartSelf, printUpdateBanner, getCurrentVersion } from "../utils/self-update.js";
 import { trackEvent, startHeartbeat } from "../utils/telemetry.js";
 import { loadTelemetryState } from "../config/telemetry.js";
 import { logRoute, logError, logStartup } from "./logger.js";
 import { createLocalRoutingErrorLog, stats } from "./stats.js";
+import { applyRateLimitHeaders } from "../providers/anthropic/rate-limit-headers.js";
+import { mountAnthropicMessagesRoute, withOAuthBeta } from "./anthropic-messages-route.js";
 import { PROXY_PORT, LITELLM_URL, ACCOUNTS_PATH } from "../config/paths.js";
 import { writePid, removePid, managesPidFile } from "../daemon/pid.js";
 import { applyOpenAIAccountPatch, validateAccountPatchBody } from "./account-patch.js";
@@ -26,14 +28,13 @@ import { SessionRouter } from "./session-router.js";
 import { createAnthropicProxy } from "./anthropic-proxy.js";
 import { AnthropicUsageRefresher } from "../providers/anthropic/usage-refresher.js";
 import { OpenAIUsageRefresher } from "../providers/openai/usage-fetch.js";
-import { createAnthropicUsageCapture } from "./usage-capture.js";
+import { attachAnthropicResponseCapture } from "./anthropic-response-capture.js";
 import { canUseExtraUsage } from "../providers/anthropic/usage.js";
 import { applyUpstreamFailureRoutingDetailed, reconcileAmbiguousRateLimitCooldown, routeFailureDetails, routeReasonDetails, } from "./lease-lifecycle.js";
 import { persistProviderEnabledState } from "./provider-routing.js";
 import { accountDeletionStatusCode, deleteAnthropicAccountTransaction, deleteOpenAIAccountTransaction, } from "./account-deletion.js";
 import { addOpenAIAccountTransaction } from "./account-add.js";
 import { createAnthropicRefreshMiddleware, createAnthropicRoutingMiddleware, } from "./anthropic-routing.js";
-import { createStreamLifecycleTracker } from "./stream-lifecycle.js";
 const zeroRoutingMetrics = () => ({
     inFlightRequests: 0,
     activeSessions: 0,
@@ -139,6 +140,8 @@ function publicUsageSnapshot(usage) {
         fetchStatus: usage.fetchStatus,
     };
 }
+// An unreported utilization surfaces as 0 here, which is what the dashboard
+// has always shown for it; only release decisions need the distinction.
 function publicWindow(window) {
     return { utilization: publicUtilization(window.utilization), resetAt: publicTimestamp(window.resetAt) };
 }
@@ -277,57 +280,9 @@ function providerStatus(accounts) {
         enabled: accounts.filter(a => a.enabled !== false).length,
     };
 }
-// Mutates entry and updates aggregate counters with token usage from Anthropic's
-// response. Called asynchronously after the log entry is already stored,
-// so the dashboard picks up the values on the next poll.
-function applyInputUsage(entry, usage) {
-    entry.cacheReadTokens = usage["cache_read_input_tokens"] ?? 0;
-    entry.cacheCreationTokens = usage["cache_creation_input_tokens"] ?? 0;
-    entry.inputTokens = usage["input_tokens"] ?? 0;
-    stats.totalCacheReadTokens += entry.cacheReadTokens;
-    stats.totalCacheCreationTokens += entry.cacheCreationTokens;
-    stats.totalInputTokens += entry.inputTokens;
-}
-function applyOutputUsage(entry, usage) {
-    entry.outputTokens = usage["output_tokens"] ?? 0;
-    stats.totalOutputTokens += entry.outputTokens;
-}
-// ─── Rate limit header extraction ──────────────────────────────────────────
-function inferPlan(requestsLimit) {
-    if (requestsLimit <= 0)
-        return "";
-    if (requestsLimit <= 100)
-        return "Pro";
-    if (requestsLimit <= 500)
-        return "Max 5x";
-    return "Max 20x";
-}
-function extractRateLimits(headers) {
-    const h = (name) => String(headers[name] ?? "");
-    const status = h("anthropic-ratelimit-unified-status");
-    if (!status)
-        return null; // No unified headers in this response
-    const requestsLimit = parseInt(h("anthropic-ratelimit-requests-limit"), 10) || 0;
-    return {
-        status: status === "rate_limited" ? "rate_limited" : "allowed",
-        fiveHourUtil: parseFloat(h("anthropic-ratelimit-unified-5h-utilization")) || 0,
-        fiveHourReset: parseInt(h("anthropic-ratelimit-unified-5h-reset"), 10) || 0,
-        sevenDayUtil: parseFloat(h("anthropic-ratelimit-unified-7d-utilization")) || 0,
-        sevenDayReset: parseInt(h("anthropic-ratelimit-unified-7d-reset"), 10) || 0,
-        claim: h("anthropic-ratelimit-unified-representative-claim"),
-        plan: inferPlan(requestsLimit),
-        requestsLimit,
-        lastUpdated: Date.now(),
-    };
-}
-/** Apply upstream rate-limit headers without discarding the usage snapshot. */
-export function applyRateLimitHeaders(account, headers) {
-    const rateLimits = extractRateLimits(headers);
-    if (!rateLimits)
-        return false;
-    account.rateLimits = { ...account.rateLimits, ...rateLimits };
-    return true;
-}
+// Re-exported so existing importers keep working; the implementation moved to
+// providers/anthropic so both Anthropic transports share it.
+export { applyRateLimitHeaders } from "../providers/anthropic/rate-limit-headers.js";
 /**
  * Build the single function through which this server writes OpenAI accounts.
  *
@@ -442,6 +397,13 @@ export async function startServer(opts = {}) {
     openAIUsageRefresher.start();
     const app = express();
     const proxyRequestTimeoutMs = getProxyRequestTimeoutMs();
+    // Router-side 429 failover / 5xx retry is on by default; `"autoFailover":
+    // false` in config.json opts out for anyone who cannot work with the
+    // trade-off (a committed retry abandons the original failure response).
+    // A single-attempt budget IS the off switch: both transports then relay
+    // every upstream failure unchanged, exactly as before the feature existed.
+    const autoFailover = getAutoFailoverEnabled();
+    const upstreamAttempts = autoFailover ? {} : { maxAttempts: 1 };
     // ─── Proxy auth middleware ─────────────────────────────────────────────────
     // If a proxySecret is configured, all requests must present it as EITHER
     //   "Authorization: Bearer <secret>" (Claude Code CLI, HTTP clients)
@@ -923,6 +885,7 @@ export async function startServer(opts = {}) {
         prepareOpenAIAccount: (account) => prepareOpenAIAccountForRequest(account, openAIAccounts, persistOpenAIAccounts),
         modelRouting,
         onUpstreamAuthFailure: onOpenAIUpstreamAuthFailure,
+        ...upstreamAttempts,
     });
     mountMessagesCrossProviderRoute(app, {
         openAIRouter,
@@ -930,6 +893,58 @@ export async function startServer(opts = {}) {
         prepareOpenAIAccount: (account) => prepareOpenAIAccountForRequest(account, openAIAccounts, persistOpenAIAccounts),
         modelRouting,
         onUpstreamAuthFailure: onOpenAIUpstreamAuthFailure,
+        ...upstreamAttempts,
+    });
+    // Shared between the retrying /v1/messages route and the generic /v1 chain
+    // so a locally rejected request is reported identically on both.
+    const onAnthropicEmptyPool = (err, _req, res) => {
+        stats.totalErrors++;
+        logError("proxy", 503, err.message);
+        res.status(503).json({
+            type: "error",
+            error: { type: "no_accounts", message: err.message },
+        });
+    };
+    const onAnthropicNoEligibleAccount = (err, req) => {
+        stats.totalErrors++;
+        const entry = createLocalRoutingErrorLog(err.reason, req._ccRouteContext?.modelFamily);
+        stats.addLog(entry);
+        logError(entry.accountId, entry.statusCode ?? 0, entry.details ?? "no-eligible");
+    };
+    const onAnthropicRefreshFailure = (account) => {
+        stats.totalErrors++;
+        logError(account.id, 401, "Token refresh failed");
+    };
+    // Claude-bound POST /v1/messages goes through its own transport with
+    // router-side 429 failover and 5xx retry; every other /v1 endpoint stays on
+    // the generic byte-transparent proxy below.
+    mountAnthropicMessagesRoute(app, {
+        target,
+        timeoutMs: proxyRequestTimeoutMs,
+        pool,
+        sessionRouter,
+        ...upstreamAttempts,
+        needsRefresh,
+        refresh: account => refreshAccountIfCurrent(account, pool),
+        onRefreshFailure: onAnthropicRefreshFailure,
+        onEmptyPool: onAnthropicEmptyPool,
+        onNoEligibleAccount: onAnthropicNoEligibleAccount,
+        // A relayed 401 means the token is stale — refresh in the background so
+        // the next request succeeds without making this client wait on it.
+        onUpstream401: account => {
+            void refreshAccountIfCurrent(account, pool).catch(console.error);
+        },
+        // Refresh in the background to narrow only ambiguity-owned global state
+        // when fresh usage proves a requested-model exhaustion.
+        onRateLimited: (route, ambiguousCooldownToken) => {
+            queueMicrotask(() => {
+                void usageRefresher.refreshAfterCurrent(route.account).then(result => {
+                    if (result.ok) {
+                        reconcileAmbiguousRateLimitCooldown(route, pool, ambiguousCooldownToken);
+                    }
+                });
+            });
+        },
     });
     // ─── Proxy middleware ──────────────────────────────────────────────────────
     // IMPORTANT: selfHandleResponse must be false (default) for SSE streaming to
@@ -952,15 +967,9 @@ export async function startServer(opts = {}) {
                 // CRITICAL: api.anthropic.com requires the "oauth-2025-04-20" beta flag to
                 // accept OAuth tokens (sk-ant-oat01-*). Without it the request is rejected
                 // with "OAuth authentication is currently not supported."
-                // APPEND — do NOT replace — so existing betas (tools, computer-use, etc.) are preserved.
-                const existingBeta = proxyReq.getHeader("anthropic-beta");
-                const betas = existingBeta
-                    ? String(existingBeta).split(",").map(b => b.trim()).filter(Boolean)
-                    : [];
-                if (!betas.includes("oauth-2025-04-20")) {
-                    betas.push("oauth-2025-04-20");
-                    proxyReq.setHeader("anthropic-beta", betas.join(","));
-                }
+                // APPEND — do NOT replace — so existing betas (tools, computer-use, etc.)
+                // are preserved. Shared with the retrying /v1/messages transport.
+                proxyReq.setHeader("anthropic-beta", withOAuthBeta(proxyReq.getHeader("anthropic-beta")));
                 // All other headers are forwarded automatically by http-proxy-middleware:
                 //   anthropic-version         — required by Anthropic API
                 //   X-Claude-Code-Session-Id  — session aggregation header sent by Claude Code
@@ -1061,34 +1070,9 @@ export async function startServer(opts = {}) {
                 const entry = pendingLog;
                 stats.addLog(entry);
                 // ── Capture token usage from Anthropic response body ─────────────────
-                // SSE streams carry usage across two events:
-                //   message_start  → input_tokens, cache_read/creation_input_tokens
-                //   message_delta   → output_tokens
-                // Non-streaming JSON carries all fields in a single usage object.
-                // The proxy is byte-transparent and the client's accept-encoding makes
-                // upstream compress, so the capture decompresses its own copy of the
-                // stream (see usage-capture.ts) — previously compressed responses were
-                // skipped, which in practice was EVERY response: no cache rate or
-                // token counts ever appeared on Anthropic activity rows.
-                const contentType = String(proxyRes.headers["content-type"] ?? "");
-                const encoding = String(proxyRes.headers["content-encoding"] ?? "");
-                const isCompressed = /gzip|br|deflate/.test(encoding);
-                const streamTracker = createStreamLifecycleTracker(req._startTime ?? Date.now(), !isCompressed && contentType.includes("text/event-stream"));
-                entry.streamLifecycle = streamTracker.state;
-                streamTracker.attach(proxyRes, response);
-                proxyRes.on("data", (chunk) => streamTracker.observeChunk(chunk));
-                const usageCapture = createAnthropicUsageCapture({
-                    contentType,
-                    contentEncoding: encoding,
-                    // Mutates the already-logged entry in place; the dashboard picks the
-                    // values up on its next poll.
-                    onInputUsage: (usage) => applyInputUsage(entry, usage),
-                    onOutputUsage: (usage) => applyOutputUsage(entry, usage),
-                });
-                if (usageCapture) {
-                    proxyRes.on("data", (chunk) => usageCapture.write(chunk));
-                    proxyRes.on("end", () => usageCapture.end());
-                }
+                // Passive stream-lifecycle + token-usage taps, shared with the
+                // retrying /v1/messages transport (see anthropic-response-capture.ts).
+                attachAnthropicResponseCapture(proxyRes, response, entry, req._startTime ?? Date.now());
             },
             error: (err, _req, res) => {
                 const request = _req;
@@ -1125,27 +1109,12 @@ export async function startServer(opts = {}) {
     // and breaks SSE streaming passthrough.
     app.use("/v1", createAnthropicRoutingMiddleware({
         sessionRouter,
-        onEmptyPool: (err, _req, res) => {
-            stats.totalErrors++;
-            logError("proxy", 503, err.message);
-            res.status(503).json({
-                type: "error",
-                error: { type: "no_accounts", message: err.message },
-            });
-        },
-        onNoEligibleAccount: (err, req) => {
-            stats.totalErrors++;
-            const entry = createLocalRoutingErrorLog(err.reason, req._ccRouteContext?.modelFamily);
-            stats.addLog(entry);
-            logError(entry.accountId, entry.statusCode ?? 0, entry.details ?? "no-eligible");
-        },
+        onEmptyPool: onAnthropicEmptyPool,
+        onNoEligibleAccount: onAnthropicNoEligibleAccount,
     }), createAnthropicRefreshMiddleware({
         needsRefresh,
         refresh: account => refreshAccountIfCurrent(account, pool),
-        onRefreshFailure: (account) => {
-            stats.totalErrors++;
-            logError(account.id, 401, "Token refresh failed");
-        },
+        onRefreshFailure: onAnthropicRefreshFailure,
     }), (req, _res, next) => {
         const route = req._ccRoute;
         const account = route.account;
@@ -1258,6 +1227,9 @@ export async function startServer(opts = {}) {
         console.log(autoUpdate
             ? chalk.gray("  Auto-update: enabled (patch/minor)")
             : chalk.gray("  Auto-update: off (notify-only) — run 'cc-router update' to install"));
+        console.log(autoFailover
+            ? chalk.gray("  Auto-failover: on — 429/5xx retried across accounts before the first relayed byte")
+            : chalk.gray("  Auto-failover: off — upstream failures pass through; clients own retries"));
         // Anonymous telemetry — fire-and-forget, never blocks proxy startup.
         try {
             const telemetryState = loadTelemetryState();