@juspay/neurolink 11.1.1 → 11.2.1

package/dist/lib/proxy/accountQuota.js

@@ -33,6 +33,82 @@ function getHeader(headers, name) {
     }
     return undefined;
 }
+/** Enumerate header names, working for both `Headers` and a plain record. */
+function forEachHeaderName(headers, visit) {
+    if (typeof headers.forEach === "function") {
+        headers.forEach((_value, name) => visit(name));
+        return;
+    }
+    for (const name of Object.keys(headers)) {
+        visit(name);
+    }
+}
+/**
+ * Collapse a wire model id to its family by dropping the snapshot date, so
+ * `claude-fable-5-20260115` and `claude-fable-5-20260320` both tag the same
+ * scoped window. Without this a window would stop matching the day Anthropic
+ * ships a new snapshot.
+ */
+export function modelFamilyToken(model) {
+    return model
+        .trim()
+        .replace(/[-_](latest)$/i, "")
+        .replace(/-\d{6,8}$/, "");
+}
+/** Unified header window tokens that map to the flat session/weekly fields. */
+const FLAT_UNIFIED_WINDOW_TOKENS = new Set(["5h", "7d"]);
+const UNIFIED_UTILIZATION_HEADER = /^anthropic-ratelimit-unified-([a-z0-9_]+)-utilization$/;
+/**
+ * Discover model-scoped rate-limit windows from response headers.
+ *
+ * Anthropic reports a per-model weekly cap as its own header family — today
+ * `anthropic-ratelimit-unified-7d_oi-*`, sent only on responses for the model
+ * that cap applies to. The token is matched generically rather than hardcoded
+ * so a future `7d_xx` is captured without a code change, mirroring how
+ * `mapUsageLimit` preserves the provider's vocabulary verbatim.
+ *
+ * Requires the request's model: the header states a limit but never says which
+ * model it scopes, and an untagged window cannot be matched to a later request.
+ */
+function parseScopedQuotaWindows(headers, model, now) {
+    if (!model) {
+        return [];
+    }
+    const scopeModel = modelFamilyToken(model);
+    if (!scopeModel) {
+        return [];
+    }
+    const tokens = [];
+    forEachHeaderName(headers, (name) => {
+        const match = UNIFIED_UTILIZATION_HEADER.exec(name.toLowerCase());
+        if (match?.[1] && !FLAT_UNIFIED_WINDOW_TOKENS.has(match[1])) {
+            tokens.push(match[1]);
+        }
+    });
+    const windows = [];
+    for (const token of tokens) {
+        const P = `anthropic-ratelimit-unified-${token}-`;
+        const used = parseFloat(getHeader(headers, `${P}utilization`) ?? "");
+        if (Number.isNaN(used)) {
+            continue;
+        }
+        const resetRaw = getHeader(headers, `${P}reset`);
+        const status = getHeader(headers, `${P}status`)?.trim().toLowerCase();
+        windows.push({
+            kind: token.startsWith("7d") ? "weekly_scoped" : "session_scoped",
+            group: token.startsWith("7d") ? "weekly" : "session",
+            used,
+            status: status ?? "unknown",
+            resetsAt: resetRaw ? parseInt(resetRaw, 10) || 0 : 0,
+            scopeModel,
+            scopeModelId: model,
+            headerWindow: token,
+            source: "headers",
+            updatedAt: now,
+        });
+    }
+    return windows;
+}
 /** Read and normalize Anthropic's authoritative top-level unified status. */
 export function getUnifiedRateLimitStatus(headers) {
     const value = getHeader(headers, "anthropic-ratelimit-unified-status");
@@ -48,7 +124,25 @@ export function getUnifiedRateLimitStatus(headers) {
  * equivalent provider state.
  */
 export function isQuotaOverageAvailable(quota) {
-    if (quota?.overageStatus?.trim().toLowerCase() !== "allowed") {
+    // `extra_usage.is_enabled` from the usage API is the account's own setting and
+    // is reported even for an account that has never served a request, which the
+    // header signals below cannot cover. Positive only: it is refreshed far less
+    // often than headers are, so a stale `false` must not veto live evidence that
+    // overage is actually serving.
+    //
+    // It is also sticky — the merge carries it forward whenever a payload omits
+    // `extra_usage` — so a live header saying overage is switched off must be
+    // able to veto it. Without that veto an org disabling extra usage would leave
+    // the flag true forever, suppressing every cooldown and sending request after
+    // request that is certain to 429.
+    const overageStatus = quota?.overageStatus?.trim().toLowerCase();
+    const providerDisabledOverage = overageStatus === "rejected" || quota?.overageDisabledReason !== undefined;
+    if (quota?.overageEnabled === true && !providerDisabledOverage) {
+        return true;
+    }
+    // Explicit null check: overageStatus is now read before this point, so the
+    // optional-chain no longer narrows `quota` for the accesses below.
+    if (!quota || overageStatus !== "allowed") {
         return false;
     }
     if (quota.overageInUse === true) {
@@ -69,7 +163,7 @@ export function isQuotaOverageAvailable(quota) {
  * Returns `null` when key headers are absent.
  * Pure computation — no I/O, no blocking.
  */
-export function parseQuotaHeaders(headers) {
+export function parseQuotaHeaders(headers, opts) {
     // Anthropic prefixes all quota headers with "anthropic-ratelimit-"
     const P = "anthropic-ratelimit-";
     const sessionUtilRaw = getHeader(headers, `${P}unified-5h-utilization`);
@@ -85,6 +179,10 @@ export function parseQuotaHeaders(headers) {
     const sessionResetRaw = getHeader(headers, `${P}unified-5h-reset`);
     const weeklyResetRaw = getHeader(headers, `${P}unified-7d-reset`);
     const fallbackRaw = getHeader(headers, `${P}unified-fallback-percentage`);
+    const now = opts?.now ?? Date.now();
+    const scopedWindows = parseScopedQuotaWindows(headers, opts?.model, now);
+    const overageDisabledReason = getHeader(headers, `${P}unified-overage-disabled-reason`);
+    const representativeClaim = getHeader(headers, `${P}unified-representative-claim`);
     return {
         unifiedStatus: getUnifiedRateLimitStatus(headers),
         sessionUsed,
@@ -94,15 +192,114 @@ 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,
+        // Anthropic does not send `unified-fallback` on the current wire, so this is
+        // always "unknown" in practice, which keeps the legacy back-compat branch of
+        // isQuotaOverageAvailable inert. Left as-is deliberately: making that branch
+        // reachable would stop cooling accounts that today park correctly, and the
+        // authoritative extra-usage signal now comes from `overageEnabled` instead.
         fallbackStatus: getHeader(headers, `${P}unified-fallback`) ?? "unknown",
         upgradePaths: getHeader(headers, `${P}unified-upgrade-paths`),
         overageStatus: getHeader(headers, `${P}unified-overage-status`) ?? "unknown",
         overageInUse: getHeader(headers, `${P}unified-overage-in-use`)?.trim().toLowerCase() ===
             "true",
-        lastUpdated: Date.now(),
+        ...(overageDisabledReason ? { overageDisabledReason } : {}),
+        ...(representativeClaim ? { representativeClaim } : {}),
+        lastUpdated: now,
         source: "headers",
+        ...(scopedWindows.length > 0 ? { windows: scopedWindows } : {}),
     };
 }
+/**
+ * Identity of a window across refreshes.
+ *
+ * Scope identity uses `scopeModel` — the model *family* on header-derived
+ * windows — ahead of the dated wire id, so a new model snapshot updates the
+ * existing window instead of appending a second one for the same cap and
+ * growing the array on every release. `source` keeps the two providers' views
+ * of the same cap distinct, since they name it differently and are reconciled
+ * by freshness rather than merged.
+ */
+function quotaWindowKey(window) {
+    return [
+        window.kind,
+        window.source ?? "usage-api",
+        window.headerWindow ?? "",
+        window.scopeModel ?? window.scopeModelId ?? "",
+        window.scopeSurface ?? "",
+    ].join("|");
+}
+/**
+ * Merge dynamic limit windows across snapshots from different sources.
+ *
+ * The two sources see different things and neither is a superset: the usage API
+ * reports every plan bucket but only when explicitly refreshed, while response
+ * headers report only the window(s) touched by the request just served — but do
+ * so continuously. A plain overwrite in either direction loses real data, which
+ * is why a header capture used to erase the model-scoped windows a `/limits`
+ * refresh had just fetched.
+ */
+export function mergeQuotaWindows(existing, incoming) {
+    if (!incoming?.length) {
+        return existing;
+    }
+    if (!existing?.length) {
+        return incoming;
+    }
+    const merged = new Map();
+    const incomingFromUsageApi = incoming.some((window) => (window.source ?? "usage-api") === "usage-api");
+    for (const window of existing) {
+        // A usage-API sweep is authoritative for every bucket it reports, but it
+        // never reports the header-only scoped windows — so those are carried over.
+        if (incomingFromUsageApi && (window.source ?? "usage-api") !== "headers") {
+            continue;
+        }
+        merged.set(quotaWindowKey(window), window);
+    }
+    for (const window of incoming) {
+        merged.set(quotaWindowKey(window), window);
+    }
+    return [...merged.values()];
+}
+/**
+ * Fold a freshly observed snapshot onto the previous one for the same account,
+ * preserving dynamic windows the new snapshot does not carry.
+ */
+export function mergeQuotaSnapshot(previous, incoming) {
+    if (!previous) {
+        return incoming;
+    }
+    const windows = mergeQuotaWindows(previous.windows, incoming.windows);
+    const next = { ...incoming };
+    if (windows !== undefined) {
+        next.windows = windows;
+    }
+    // Account configuration, not per-response state: each source reports only
+    // some of these, so a plain overwrite makes the value flicker in and out
+    // depending on which source wrote last. `overageEnabled` comes only from the
+    // usage API and `overageDisabledReason` only from response headers, so
+    // whichever wrote last would otherwise erase the other's field.
+    if (next.overageEnabled === undefined &&
+        previous.overageEnabled !== undefined) {
+        next.overageEnabled = previous.overageEnabled;
+    }
+    if (next.overageDisabledReason === undefined &&
+        previous.overageDisabledReason !== undefined) {
+        next.overageDisabledReason = previous.overageDisabledReason;
+    }
+    if (next.representativeClaim === undefined &&
+        previous.representativeClaim !== undefined) {
+        next.representativeClaim = previous.representativeClaim;
+    }
+    // windowsUpdatedAt tracks the last full usage-API sweep; a header capture
+    // adds one window and must not claim to have refreshed all of them.
+    const windowsUpdatedAt = incoming.source === "usage-api"
+        ? incoming.windowsUpdatedAt
+        : (incoming.windowsUpdatedAt ?? previous.windowsUpdatedAt);
+    if (windowsUpdatedAt !== undefined) {
+        next.windowsUpdatedAt = windowsUpdatedAt;
+    }
+    return next;
+}
 // ---------------------------------------------------------------------------
 // In-memory cache + debounced async persistence
 // ---------------------------------------------------------------------------
@@ -236,15 +433,9 @@ export async function loadAccountQuota(accountKey) {
 export async function saveAccountQuota(accountKey, quota) {
     await stateMutex.runExclusive(async () => {
         await ensureAccountQuotasLoaded();
-        const next = { ...quota };
-        // Header-sourced saves carry no dynamic windows; a passive capture right
-        // after a usage-API refresh must not erase the refreshed buckets.
-        const existing = memoryCache[accountKey];
-        if (next.windows === undefined && existing?.windows !== undefined) {
-            next.windows = existing.windows;
-            next.windowsUpdatedAt = existing.windowsUpdatedAt;
-        }
-        memoryCache[accountKey] = next;
+        // A header capture reports only the windows the served request touched, so
+        // it must fold onto the existing snapshot rather than replace it.
+        memoryCache[accountKey] = mergeQuotaSnapshot(memoryCache[accountKey], quota);
         dirty = true;
         cacheVersion += 1;
     });

package/dist/lib/proxy/accountUsage.js

@@ -199,12 +199,14 @@ function toFraction(percent) {
         ? percent / 100
         : undefined;
 }
-function mapUsageLimit(entry) {
+function mapUsageLimit(entry, now) {
     const window = {
         kind: entry.kind ?? "unknown",
         used: toFraction(entry.percent) ?? 0,
         status: deriveWindowStatus(entry.percent, entry.severity),
         resetsAt: isoToEpochSeconds(entry.resets_at),
+        source: "usage-api",
+        updatedAt: now,
     };
     if (entry.group !== undefined) {
         window.group = entry.group;
@@ -219,6 +221,13 @@ function mapUsageLimit(entry) {
     if (scopeModel) {
         window.scopeModel = scopeModel;
     }
+    // The wire id matches a request's `model` exactly, so keeping it lets routing
+    // skip the fuzzy display-name match ("Fable" vs "claude-fable-5-20260115").
+    // Often null in practice, which is why the display-name path still exists.
+    const scopeModelId = entry.scope?.model?.id;
+    if (scopeModelId) {
+        window.scopeModelId = scopeModelId;
+    }
     const scopeSurface = entry.scope?.surface;
     if (scopeSurface) {
         window.scopeSurface = scopeSurface;
@@ -242,7 +251,7 @@ export function usageToQuota(usage, opts) {
         return null;
     }
     const { now, prior } = opts;
-    const windows = limits.map(mapUsageLimit);
+    const windows = limits.map((entry) => mapUsageLimit(entry, now));
     const sessionLimit = limits.find((entry) => entry.kind === "session");
     const weeklyLimit = limits.find((entry) => entry.kind === "weekly_all");
     const sessionPct = usage.five_hour?.utilization ?? sessionLimit?.percent ?? undefined;
@@ -273,6 +282,10 @@ export function usageToQuota(usage, opts) {
         weeklyResetAt,
         fallbackPercentage: prior?.fallbackPercentage ?? 0,
         overageStatus,
+        // Authoritative: the header trio the legacy overage checks rely on is only
+        // ever sent on a served response, so an account refreshed but not yet used
+        // would otherwise look overage-ineligible even with extra usage switched on.
+        ...(typeof overageEnabled === "boolean" ? { overageEnabled } : {}),
         lastUpdated: now,
         windows,
         windowsUpdatedAt: now,

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

@@ -0,0 +1,26 @@
+/**
+ * Codex account enumeration + usage/quota normalisation.
+ *
+ * Mirrors `accountUsage.ts` (Anthropic) for the Codex pool. Codex reports two
+ * rate-limit windows — `primary` (short) and `secondary` (weekly) — which we
+ * map onto the shared AccountQuota session/weekly fields so the same routing,
+ * cooldown, and display code works for both providers.
+ */
+import type { AccountQuota, CodexRateLimits, CodexUsageFetchResult, ProxyPassthroughAccount } from "../types/index.js";
+export declare const CODEX_ACCOUNT_PREFIX = "codex:";
+/** Enumerate Codex OAuth accounts from the token store for usage refresh. */
+export declare function listCodexAccountsForUsage(): Promise<ProxyPassthroughAccount[]>;
+/** Normalise a Codex rate-limit block into the shared AccountQuota shape. */
+export declare function codexRateLimitsToQuota(rateLimits: CodexRateLimits | null | undefined, now?: number): AccountQuota;
+/**
+ * Parse Codex rate-limit information from response headers. The ChatGPT backend
+ * returns a JSON rate-limit blob in `x-codex-ratelimit` / `x-codex-active-limit`
+ * on some responses; parse defensively and return null when absent.
+ */
+export declare function parseCodexRateLimitHeaders(headers: Headers, now?: number): AccountQuota | null;
+/** Fetch the usage/limits window for one Codex account. */
+export declare function fetchCodexAccountUsage(account: ProxyPassthroughAccount, options?: {
+    timeoutMs?: number;
+}): Promise<CodexUsageFetchResult>;
+/** Decode plan type from an account's access token (display convenience). */
+export declare function codexAccountPlanType(account: ProxyPassthroughAccount): string | undefined;

package/dist/lib/proxy/codexAccountUsage.js

@@ -0,0 +1,174 @@
+/**
+ * Codex account enumeration + usage/quota normalisation.
+ *
+ * Mirrors `accountUsage.ts` (Anthropic) for the Codex pool. Codex reports two
+ * rate-limit windows — `primary` (short) and `secondary` (weekly) — which we
+ * map onto the shared AccountQuota session/weekly fields so the same routing,
+ * cooldown, and display code works for both providers.
+ */
+import { tokenStore } from "../auth/tokenStore.js";
+import { CODEX_ORIGINATOR, CODEX_USAGE_URL, CODEX_USER_AGENT, decodeCodexAccessToken, resolveCodexAccountId, } from "../auth/codexOAuth.js";
+import { logger } from "../utils/logger.js";
+export const CODEX_ACCOUNT_PREFIX = "codex:";
+/** Enumerate Codex OAuth accounts from the token store for usage refresh. */
+export async function listCodexAccountsForUsage() {
+    const keys = await tokenStore.listByPrefix(CODEX_ACCOUNT_PREFIX);
+    const accounts = [];
+    for (const key of keys) {
+        if (await tokenStore.isDisabled(key)) {
+            continue;
+        }
+        const tokens = await tokenStore.loadTokens(key);
+        if (!tokens) {
+            continue;
+        }
+        const label = key.slice(CODEX_ACCOUNT_PREFIX.length) || key;
+        accounts.push({
+            key,
+            label,
+            token: tokens.accessToken,
+            refreshToken: tokens.refreshToken,
+            expiresAt: tokens.expiresAt,
+            type: tokens.tokenType === "Bearer" ? "oauth" : "api_key",
+        });
+    }
+    return accounts;
+}
+function toFraction(percent) {
+    if (typeof percent !== "number" || !Number.isFinite(percent)) {
+        return 0;
+    }
+    // Codex reports 0-100; clamp and normalise to 0-1.
+    return Math.min(1, Math.max(0, percent / 100));
+}
+function windowResetEpochSeconds(window, nowSeconds) {
+    if (!window) {
+        return 0;
+    }
+    if (typeof window.resets_at === "number" &&
+        Number.isFinite(window.resets_at) &&
+        window.resets_at > 0) {
+        // Tolerate ms epochs (~year 2100 ceiling in seconds).
+        return window.resets_at > 4_102_444_800
+            ? Math.floor(window.resets_at / 1000)
+            : window.resets_at;
+    }
+    const relative = typeof window.resets_in_seconds === "number"
+        ? window.resets_in_seconds
+        : window.reset_after;
+    if (typeof relative === "number" &&
+        Number.isFinite(relative) &&
+        relative > 0) {
+        return nowSeconds + Math.floor(relative);
+    }
+    return 0;
+}
+function deriveWindowStatus(usedFraction) {
+    return usedFraction >= 1 ? "rejected" : "allowed";
+}
+function toQuotaWindow(kind, group, window, nowSeconds) {
+    if (!window) {
+        return null;
+    }
+    const used = toFraction(window.used_percent);
+    return {
+        kind,
+        group,
+        used,
+        status: deriveWindowStatus(used),
+        resetsAt: windowResetEpochSeconds(window, nowSeconds),
+        isActive: true,
+    };
+}
+/** Normalise a Codex rate-limit block into the shared AccountQuota shape. */
+export function codexRateLimitsToQuota(rateLimits, now = Date.now()) {
+    const nowSeconds = Math.floor(now / 1000);
+    const primary = rateLimits?.primary ?? null;
+    const secondary = rateLimits?.secondary ?? null;
+    const sessionUsed = toFraction(primary?.used_percent);
+    const weeklyUsed = toFraction(secondary?.used_percent);
+    const windows = [];
+    const primaryWindow = toQuotaWindow("session", "session", primary, nowSeconds);
+    const secondaryWindow = toQuotaWindow("weekly_all", "weekly", secondary, nowSeconds);
+    if (primaryWindow) {
+        windows.push(primaryWindow);
+    }
+    if (secondaryWindow) {
+        windows.push(secondaryWindow);
+    }
+    return {
+        sessionUsed,
+        sessionStatus: deriveWindowStatus(sessionUsed),
+        sessionResetAt: windowResetEpochSeconds(primary, nowSeconds),
+        weeklyUsed,
+        weeklyStatus: deriveWindowStatus(weeklyUsed),
+        weeklyResetAt: windowResetEpochSeconds(secondary, nowSeconds),
+        // Codex has no overage/fallback concept; keep neutral defaults.
+        fallbackPercentage: 0,
+        overageStatus: "rejected",
+        lastUpdated: now,
+        windows: windows.length > 0 ? windows : undefined,
+        windowsUpdatedAt: windows.length > 0 ? now : undefined,
+        source: "usage-api",
+    };
+}
+/**
+ * Parse Codex rate-limit information from response headers. The ChatGPT backend
+ * returns a JSON rate-limit blob in `x-codex-ratelimit` / `x-codex-active-limit`
+ * on some responses; parse defensively and return null when absent.
+ */
+export function parseCodexRateLimitHeaders(headers, now = Date.now()) {
+    const raw = headers.get("x-codex-ratelimit") ??
+        headers.get("x-codex-active-limit") ??
+        null;
+    if (!raw) {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        const rateLimits = "rate_limits" in parsed && parsed.rate_limits
+            ? parsed.rate_limits
+            : parsed;
+        return codexRateLimitsToQuota(rateLimits, now);
+    }
+    catch {
+        return null;
+    }
+}
+/** Fetch the usage/limits window for one Codex account. */
+export async function fetchCodexAccountUsage(account, options = {}) {
+    if (account.type !== "oauth") {
+        return { ok: false, reason: "not_oauth" };
+    }
+    const accountId = resolveCodexAccountId(account.token);
+    try {
+        const response = await fetch(CODEX_USAGE_URL, {
+            method: "GET",
+            headers: {
+                Authorization: `Bearer ${account.token}`,
+                ...(accountId ? { "chatgpt-account-id": accountId } : {}),
+                originator: CODEX_ORIGINATOR,
+                "User-Agent": CODEX_USER_AGENT,
+                Accept: "application/json",
+            },
+            signal: AbortSignal.timeout(options.timeoutMs ?? 10_000),
+        });
+        if (response.status === 401 || response.status === 403) {
+            return { ok: false, reason: "auth" };
+        }
+        if (!response.ok) {
+            return { ok: false, reason: "http" };
+        }
+        const usage = (await response.json());
+        return { ok: true, quota: codexRateLimitsToQuota(usage.rate_limits) };
+    }
+    catch (error) {
+        logger.debug(`Codex usage fetch failed for ${account.label}: ${error instanceof Error ? error.message : String(error)}`);
+        return { ok: false, reason: "network" };
+    }
+}
+/** Decode plan type from an account's access token (display convenience). */
+export function codexAccountPlanType(account) {
+    return decodeCodexAccessToken(account.token).planType;
+}
+//# sourceMappingURL=codexAccountUsage.js.map

package/dist/lib/proxy/proxyAnalysis.js

@@ -100,7 +100,13 @@ function routingCandidateValue(value) {
         "sessionStatus",
         "weeklyStatus",
     ];
-    const optionalNullableStringFields = ["fallbackStatus", "upgradePaths"];
+    const optionalNullableStringFields = [
+        "fallbackStatus",
+        "upgradePaths",
+        "scopedModel",
+        "scopedStatus",
+    ];
+    const optionalNullableNumberFields = ["scopedUsed", "scopedResetAt"];
     if (!stringValue(candidate.account) ||
         typeof candidate.accountType !== "string" ||
         !ROUTING_ACCOUNT_TYPES.has(candidate.accountType) ||
@@ -139,6 +145,7 @@ function routingCandidateValue(value) {
             "lastRefreshAttemptAt",
             "lastRefreshSuccessAt",
             "nextRefreshEligibleAt",
+            ...optionalNullableNumberFields,
         ].some((field) => field in candidate &&
             candidate[field] !== undefined &&
             !isNullableFiniteNumber(candidate[field])) ||
@@ -192,6 +199,10 @@ function routingCandidateValue(value) {
         weeklyStatus: candidate.weeklyStatus,
         weeklyUsed: candidate.weeklyUsed,
         weeklyResetAt: candidate.weeklyResetAt,
+        scopedModel: candidate.scopedModel,
+        scopedStatus: candidate.scopedStatus,
+        scopedUsed: candidate.scopedUsed,
+        scopedResetAt: candidate.scopedResetAt,
     };
 }
 function routingDecisionValue(value) {

package/dist/lib/proxy/proxyConfig.js

@@ -238,6 +238,16 @@ export function validateProxyConfig(config) {
             normalizedQuotaRouting !== "false") {
             errors.push("routing.quota-routing must be a boolean");
         }
+        // Without this a typo (`use-overage: nevr`) loads cleanly and silently
+        // falls back to "auto" — the operator asked to block paid extra usage and
+        // gets provider-driven overage instead.
+        const rawUseOverage = routing["use-overage"] ?? routing.useOverage;
+        if (rawUseOverage !== undefined &&
+            !["auto", "always", "never"].includes(typeof rawUseOverage === "string"
+                ? rawUseOverage.trim().toLowerCase()
+                : "")) {
+            errors.push("routing.use-overage must be auto, always, or never");
+        }
         const rawAutoFallback = routing["auto-fallback"] ?? routing.autoFallback;
         const normalizedAutoFallback = typeof rawAutoFallback === "string"
             ? rawAutoFallback.trim().toLowerCase()
@@ -417,6 +427,20 @@ function parseRoutingConfig(raw) {
             logger.warn(`[proxy-config] Ignoring routing.quotaRouting: expected boolean, got ${typeof rawQuotaRouting}`);
         }
     }
+    const rawUseOverage = raw["use-overage"] ?? raw.useOverage;
+    if (rawUseOverage !== undefined) {
+        const normalized = typeof rawUseOverage === "string"
+            ? rawUseOverage.trim().toLowerCase()
+            : "";
+        if (normalized === "auto" ||
+            normalized === "always" ||
+            normalized === "never") {
+            result.useOverage = normalized;
+        }
+        else {
+            logger.warn(`[proxy-config] Ignoring routing.useOverage: expected auto|always|never, got ${String(rawUseOverage)}`);
+        }
+    }
     const rawAutoFallback = raw["auto-fallback"] ?? raw.autoFallback;
     if (rawAutoFallback !== undefined) {
         if (typeof rawAutoFallback === "boolean") {

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

@@ -1,6 +1,17 @@
 /** Schema-v1 routing evidence values shared by emitters and offline readers. */
 export declare const PROXY_ACCOUNT_ROUTING_STRATEGIES: readonly ["round-robin", "fill-first"];
 export declare const PROXY_ACCOUNT_ROUTING_MODES: readonly ["quota", "primary", "round_robin", "single_account"];
-export declare const PROXY_ACCOUNT_ROUTING_REASONS: readonly ["single_account", "round_robin", "configured_primary", "insertion_order", "availability", "cooldown_recovery", "quota_evidence", "quota_probe", "session_headroom", "session_reset", "weekly_reset", "weekly_utilization"];
+export declare const PROXY_ACCOUNT_ROUTING_REASONS: readonly ["single_account", "round_robin", "configured_primary", "insertion_order", "availability", "cooldown_recovery", "quota_evidence", "quota_probe", "session_headroom", "scoped_headroom", "session_reset", "weekly_reset", "weekly_utilization", "scoped_utilization"];
 export declare const PROXY_ACCOUNT_TYPES: readonly ["oauth", "api_key"];
 export declare const ACCOUNT_COOLING_REASONS: readonly ["weekly", "session", "unified", "transient", "auth"];
+/**
+ * Longest a cooldown may last for each reason, measured from when it was set.
+ *
+ * A reason names a specific provider window, so it also bounds the wait: a
+ * "session" cooldown describes a 5-hour window and can never legitimately run
+ * for days. Without a per-reason ceiling a single bogus reset timestamp parks an
+ * account for as long as the global 8-day clamp allows — observed in the wild as
+ * a 206-hour "session" cooldown. Values carry slack so a genuine window that
+ * resets slightly late is not cut short.
+ */
+export declare const MAX_COOLDOWN_MS_BY_REASON: Record<string, number>;

package/dist/lib/proxy/routingEvidence.js

@@ -21,9 +21,11 @@ export const PROXY_ACCOUNT_ROUTING_REASONS = [
     // decisions must never select a production request for quota discovery.
     "quota_probe",
     "session_headroom",
+    "scoped_headroom",
     "session_reset",
     "weekly_reset",
     "weekly_utilization",
+    "scoped_utilization",
 ];
 export const PROXY_ACCOUNT_TYPES = ["oauth", "api_key"];
 export const ACCOUNT_COOLING_REASONS = [
@@ -33,4 +35,25 @@ export const ACCOUNT_COOLING_REASONS = [
     "transient",
     "auth",
 ];
+/**
+ * Longest a cooldown may last for each reason, measured from when it was set.
+ *
+ * A reason names a specific provider window, so it also bounds the wait: a
+ * "session" cooldown describes a 5-hour window and can never legitimately run
+ * for days. Without a per-reason ceiling a single bogus reset timestamp parks an
+ * account for as long as the global 8-day clamp allows — observed in the wild as
+ * a 206-hour "session" cooldown. Values carry slack so a genuine window that
+ * resets slightly late is not cut short.
+ */
+export const MAX_COOLDOWN_MS_BY_REASON = {
+    session: 5 * 60 * 60 * 1000 + 15 * 60 * 1000,
+    weekly: 7 * 24 * 60 * 60 * 1000 + 12 * 60 * 60 * 1000,
+    // No named window bounds this one: it fires when the 5h/7d statuses still read
+    // "allowed" and the provider's own Retry-After is the only signal. Generous on
+    // purpose — truncating a provider-directed wait just re-hammers the account on
+    // a shorter cycle — while still refusing an absurd multi-day park.
+    unified: 12 * 60 * 60 * 1000,
+    transient: 15 * 60 * 1000,
+    auth: 5 * 60 * 1000,
+};
 //# sourceMappingURL=routingEvidence.js.map

package/dist/lib/proxy/runtimeConfig.js

@@ -228,6 +228,7 @@ async function buildCandidate(options, generation, allowMissingConfig, allowMiss
         : "[missing]")
         .digest("hex")
         .slice(0, 16);
+    const useOverage = routing?.useOverage ?? "auto";
     const fingerprintSource = JSON.stringify({
         strategy,
         passthrough: options.passthrough,
@@ -237,6 +238,7 @@ async function buildCandidate(options, generation, allowMissingConfig, allowMiss
         quotaRoutingEnabled,
         sessionSoftLimit,
         sessionResetToleranceMs,
+        useOverage,
     });
     const configHash = createHash("sha256")
         .update(fingerprintSource)
@@ -256,6 +258,7 @@ async function buildCandidate(options, generation, allowMissingConfig, allowMiss
             quotaRoutingEnabled,
             sessionSoftLimit,
             sessionResetToleranceMs,
+            useOverage,
         }),
         configFilePresent,
         envFilePresent,