@juspay/neurolink 10.8.8 → 10.8.10

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

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

package/dist/lib/proxy/accountQuota.js

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

package/dist/lib/proxy/proxyAnalysis.js

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

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

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

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

@@ -15,7 +15,7 @@ import { join } from "node:path";
 import { buildStableClaudeCodeBillingHeader, CLAUDE_CLI_USER_AGENT, CLAUDE_CODE_OAUTH_BETAS, getOrCreateClaudeCodeIdentity, parseClaudeCodeUserId, } from "../../auth/anthropicOAuth.js";
 import { clearAccountCooldown, loadAccountCooldowns, saveAccountCooldown, } from "../../proxy/accountCooldown.js";
 import { anthropicAccountKeysEqual, ENV_ANTHROPIC_ACCOUNT_KEY, isAccountAllowed, LEGACY_ANTHROPIC_ACCOUNT_KEY, shouldLoadFallbackCredential, } from "../../proxy/accountSelection.js";
-import { getUnifiedRateLimitStatus, loadAccountQuotas, parseQuotaHeaders, saveAccountQuota, } from "../../proxy/accountQuota.js";
+import { getUnifiedRateLimitStatus, isQuotaOverageAvailable, loadAccountQuotas, parseQuotaHeaders, saveAccountQuota, } from "../../proxy/accountQuota.js";
 import { buildClaudeError, ClaudeStreamSerializer, generateToolUseId, parseClaudeRequest, serializeClaudeResponse, } from "../../proxy/claudeFormat.js";
 import { buildAnthropicModelsListResponse, buildTranslationOptions, extractText, extractToolArgs, extractUsageFromStreamResult, handleTranslatedJsonRequest, handleTranslatedStreamRequest, hasTranslatedOutput, } from "../../proxy/proxyTranslationEngine.js";
 import { tracers } from "../../telemetry/tracers.js";
@@ -411,9 +411,9 @@ function clampCooldownUntil(untilMs, now) {
  * The unified subscription limits expose per-window status + reset:
  *   - weekly (7d) "rejected"  → hard cap for the week; cool until the 7d reset.
  *   - session (5h) "rejected" → paced out for this session; cool until the 5h reset.
- * Both mean "retrying this account is futile until its window resets" → rotate
- * immediately (no same-account retries) and park the account until the ACTUAL
- * reset — never the legacy 60s hardcap that let us re-hammer a spent account.
+ * Both mean "retrying this account is futile until its window resets" unless
+ * the provider explicitly enables overage. In that case, the subscription
+ * window is exhausted but the account remains usable for paid fallback.
  *
  * Anything else (window still "allowed" but momentarily 429'd — a per-minute
  * burst / acceleration limit) is transient: honor retry-after as a floor,
@@ -430,7 +430,8 @@ function planCooldownFor429(quota, retryAfterMs, now, unifiedStatus = quota?.uni
             rotateImmediately: true,
         };
     }
-    if (quota && quota.sessionStatus === "rejected") {
+    const overageAvailable = isQuotaOverageAvailable(quota);
+    if (quota && quota.sessionStatus === "rejected" && !overageAvailable) {
         const reset = resetEpochToMs(quota.sessionResetAt, now) ??
             (retryAfterMs > 0 ? now + retryAfterMs : now + DEFAULT_COOLING_PERIOD_MS);
         return {
@@ -442,7 +443,7 @@ function planCooldownFor429(quota, retryAfterMs, now, unifiedStatus = quota?.uni
     // Anthropic may reject the authoritative top-level unified limit while both
     // 5h and 7d sub-window statuses still say "allowed". Treating this as a
     // transient burst retries a known-exhausted account and delays failover.
-    if (unifiedStatus?.trim().toLowerCase() === "rejected") {
+    if (unifiedStatus?.trim().toLowerCase() === "rejected" && !overageAvailable) {
         const reset = retryAfterMs > 0 ? now + retryAfterMs : now + DEFAULT_HARD_COOLDOWN_MS;
         return {
             reason: "unified",
@@ -470,34 +471,53 @@ function minutesUntil(untilMs, now) {
  * flipped to "rejected" (the boundary request that spends the last of the quota
  * still returns 200 but reports rejected/next-reset). Parks the account until
  * its reset so the next request skips it instead of discovering the limit via a
- * 429. Never shortens an existing, longer cooldown.
+ * 429, except when the provider explicitly enables paid overage.
  */
-function maybeCoolFromQuota(state, quota, now) {
+function reconcileCooldownFromQuota(state, quota, now) {
+    const overageAvailable = isQuotaOverageAvailable(quota);
     let until;
     let reason;
     if (quota.weeklyStatus === "rejected") {
         until = resetEpochToMs(quota.weeklyResetAt, now);
         reason = "weekly";
     }
-    else if (quota.sessionStatus === "rejected") {
+    if (until === undefined &&
+        overageAvailable &&
+        state.coolingUntil &&
+        (state.coolingReason === "session" || state.coolingReason === "unified")) {
+        const previousCoolingUntil = state.coolingUntil;
+        state.coolingUntil = undefined;
+        state.coolingReason = undefined;
+        logger.always("[proxy] clearing subscription cooldown because Anthropic explicitly permits overage");
+        return { kind: "cleared", coolingUntil: previousCoolingUntil };
+    }
+    if (until === undefined &&
+        quota.sessionStatus === "rejected" &&
+        !overageAvailable) {
         until = resetEpochToMs(quota.sessionResetAt, now);
         reason = "session";
     }
-    else if (quota.unifiedStatus === "rejected") {
+    else if (until === undefined &&
+        quota.unifiedStatus === "rejected" &&
+        !overageAvailable) {
         until = now + DEFAULT_HARD_COOLDOWN_MS;
         reason = "unified";
     }
     if (until === undefined) {
-        return false;
+        return null;
     }
     const clamped = clampCooldownUntil(until, now);
     if (!state.coolingUntil || clamped > state.coolingUntil) {
         state.coolingUntil = clamped;
         state.coolingReason = reason;
         logger.always(`[proxy] proactively cooling account (${reason}) ~${minutesUntil(clamped, now)}m from success-response quota (status rejected)`);
-        return true;
+        return {
+            kind: "cooled",
+            coolingUntil: clamped,
+            coolingReason: reason ?? "unified",
+        };
     }
-    return false;
+    return null;
 }
 /**
  * Seed each account's runtime quota from the persisted snapshots in
@@ -528,6 +548,15 @@ async function seedRuntimeQuotasFromDisk(accounts) {
                 state.coolingUntil = persistedCooldown.coolingUntil;
                 state.coolingReason = persistedCooldown.reason;
             }
+            if (state.quota) {
+                const cooldownUpdate = reconcileCooldownFromQuota(state, state.quota, now);
+                if (cooldownUpdate?.kind === "cooled") {
+                    await saveAccountCooldown(account.key, cooldownUpdate.coolingUntil, cooldownUpdate.coolingReason);
+                }
+                else if (cooldownUpdate?.kind === "cleared") {
+                    await clearAccountCooldown(account.key, cooldownUpdate.coolingUntil);
+                }
+            }
         }
     }
     catch {
@@ -594,13 +623,16 @@ function accountSortMetrics(accountKey, now, sessionSoftLimit, sessionResetToler
             ? (q.weeklyStatus ?? "unknown")
             : "allowed"
         : null;
+    const overageEligible = isQuotaOverageAvailable(q);
     const saturated = sessionStatus === "throttled" ||
         (sessionTicking && (sessionUsed ?? 0) >= sessionSoftLimit);
     const quotaLastUpdated = q && Number.isFinite(q.lastUpdated) ? q.lastUpdated : null;
     return {
         usable: !coolingActive &&
             weeklyStatus !== "rejected" &&
-            sessionStatus !== "rejected",
+            (sessionStatus !== "rejected" || overageEligible) &&
+            (q?.unifiedStatus?.trim().toLowerCase() !== "rejected" ||
+                overageEligible),
         saturated,
         hasQuota: !!q,
         quotaLastUpdated,
@@ -609,6 +641,9 @@ function accountSortMetrics(accountKey, now, sessionSoftLimit, sessionResetToler
         coolingReason: st?.coolingReason ?? null,
         coolingUntil: st?.coolingUntil ?? 0,
         unifiedStatus: q?.unifiedStatus ?? null,
+        fallbackStatus: q?.fallbackStatus ?? null,
+        upgradePaths: q?.upgradePaths ?? null,
+        overageEligible,
         overageStatus: q?.overageStatus ?? null,
         sessionStatus,
         sessionUsed,
@@ -735,6 +770,9 @@ function buildRoutingDecision(args) {
                 ? metrics.coolingUntil
                 : null,
             unifiedStatus: metrics.unifiedStatus,
+            fallbackStatus: metrics.fallbackStatus,
+            upgradePaths: metrics.upgradePaths,
+            overageEligible: metrics.overageEligible,
             overageStatus: metrics.overageStatus,
             sessionStatus: metrics.sessionStatus,
             sessionUsed: metrics.sessionUsed,
@@ -2385,15 +2423,18 @@ async function handleAnthropicSuccessfulResponse(args) {
     if (quota) {
         // Stash the latest quota on runtime state so the next request can pick the
         // account whose window resets soonest (max-utilization) and proactively
-        // skip any whose window is already rejected — without eating a 429 first.
+        // skip rejected windows unless Anthropic explicitly permits overage.
         accountState.quota = quota;
-        if (maybeCoolFromQuota(accountState, quota, Date.now())) {
-            const { coolingUntil, coolingReason } = accountState;
-            if (coolingUntil !== undefined && coolingReason !== undefined) {
-                saveAccountCooldown(account.key, coolingUntil, coolingReason).catch(() => {
-                    // Non-fatal: cooldown is already active in memory.
-                });
-            }
+        const cooldownUpdate = reconcileCooldownFromQuota(accountState, quota, Date.now());
+        if (cooldownUpdate?.kind === "cooled") {
+            saveAccountCooldown(account.key, cooldownUpdate.coolingUntil, cooldownUpdate.coolingReason).catch(() => {
+                // Non-fatal: cooldown is already active in memory.
+            });
+        }
+        else if (cooldownUpdate?.kind === "cleared") {
+            clearAccountCooldown(account.key, cooldownUpdate.coolingUntil).catch(() => {
+                // Non-fatal: the next successful response will reconcile again.
+            });
         }
         saveAccountQuota(account.label, quota).catch(() => {
             // Non-fatal: quota persistence is best-effort
@@ -2995,16 +3036,18 @@ async function handleAnthropicSuccessfulNonStreamRetryResponse(args) {
     const retryQuota = parseQuotaHeaders(retryResp.headers);
     if (retryQuota) {
         // Keep the auth-retry success path in parity with the main success path:
-        // stash quota for proactive selection and proactively cool if this
-        // response reveals the window flipped to "rejected".
+        // stash quota for proactive selection and reconcile a rejected window.
         accountState.quota = retryQuota;
-        if (maybeCoolFromQuota(accountState, retryQuota, Date.now())) {
-            const { coolingUntil, coolingReason } = accountState;
-            if (coolingUntil !== undefined && coolingReason !== undefined) {
-                saveAccountCooldown(account.key, coolingUntil, coolingReason).catch(() => {
-                    // Non-fatal: cooldown is already active in memory.
-                });
-            }
+        const cooldownUpdate = reconcileCooldownFromQuota(accountState, retryQuota, Date.now());
+        if (cooldownUpdate?.kind === "cooled") {
+            saveAccountCooldown(account.key, cooldownUpdate.coolingUntil, cooldownUpdate.coolingReason).catch(() => {
+                // Non-fatal: cooldown is already active in memory.
+            });
+        }
+        else if (cooldownUpdate?.kind === "cleared") {
+            clearAccountCooldown(account.key, cooldownUpdate.coolingUntil).catch(() => {
+                // Non-fatal: the next successful response will reconcile again.
+            });
         }
         saveAccountQuota(account.label, retryQuota).catch((error) => {
             logger.debug("[proxy] Failed to persist account quota after auth retry", {
@@ -4461,8 +4504,8 @@ async function handleAnthropicRoutedClaudeRequest(args) {
                 // Clear cooling on success — but only if the stored cooldown has already
                 // expired, so an older in-flight success can't wipe an active exhaustion
                 // cooldown just set by a concurrent 429. The success handler re-applies a
-                // cooldown via maybeCoolFromQuota if the fresh quota headers report the
-                // window flipped to "rejected" on this very request.
+                // cooldown via reconcileCooldownFromQuota when fresh quota headers
+                // report a rejected window without explicit overage availability.
                 if (accountState.coolingUntil &&
                     Date.now() >= accountState.coolingUntil) {
                     const expiredCooldown = accountState.coolingUntil;
@@ -5114,6 +5157,7 @@ export const __testHooks = {
     resolveHomeIndex,
     maybeResetPrimaryToHome,
     planCooldownFor429,
+    reconcileCooldownFromQuota,
     isPermanentRefreshFailure,
     getStreamFailureDetails,
     trackUpstreamReadableStream,

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

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

package/dist/proxy/accountQuota.d.ts

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

package/dist/proxy/accountQuota.js

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

package/dist/proxy/proxyAnalysis.js

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

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

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