@juspay/neurolink 11.2.0 → 11.2.2

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

@@ -481,6 +481,13 @@ export type ProxyAccountRoutingCandidate = {
     weeklyStatus: string | null;
     weeklyUsed: number | null;
     weeklyResetAt: number | null;
+    /** Display name of the model-scoped window that matched the requested model
+     *  (e.g. "Fable"), or null when the account reports no scoped cap for it.
+     *  Optional so schema-v1 readers of older records stay valid. */
+    scopedModel?: string | null;
+    scopedStatus?: string | null;
+    scopedUsed?: number | null;
+    scopedResetAt?: number | null;
 };
 export type ProxyAccountRoutingDecision = {
     schemaVersion: 1;
@@ -531,6 +538,15 @@ export type ProxyAccountSortMetrics = {
     weeklyReset: number;
     weeklyUsed: number | null;
     weeklyUsedForSort: number;
+    /** Model-scoped weekly window matching the requested model. All null/false
+     *  when the account reports no scoped cap for it (the common case), which
+     *  makes every scoped comparator rung a no-op for unscoped traffic. */
+    scopedModel: string | null;
+    scopedStatus: string | null;
+    scopedUsed: number | null;
+    scopedReset: number;
+    scopedUsedForSort: number;
+    scopedSaturated: boolean;
 };
 export type RequestLogEntry = {
     timestamp: string;
@@ -665,6 +681,8 @@ export type AnthropicLoopState = {
     } | null;
     authFailureMessage: string | null;
     authCooldownMessage: string | null;
+    entitlementFailure: AnthropicEntitlementFailure | null;
+    scopedExhaustion: AnthropicScopedExhaustion | null;
     fallbackFailureMessage?: string;
     attemptNumber: number;
     lastTransportErrorCode?: string;
@@ -752,6 +770,7 @@ export type AnthropicAuthRetryResult = {
     retryDelayMs?: number;
     lastError: unknown;
     authFailureMessage: string | null;
+    entitlementFailure: AnthropicEntitlementFailure | null;
     sawRateLimit: boolean;
     sawTransientFailure: boolean;
     sawNetworkError: boolean;
@@ -771,6 +790,7 @@ export type AnthropicNonOkResult = {
         body: string;
         contentType?: string;
     } | null;
+    entitlementFailure: AnthropicEntitlementFailure | null;
     upstreamSpan?: Span;
 };
 export type PreparedAnthropicAccountAttempt = {
@@ -997,6 +1017,17 @@ export type AccountQuota = {
     overageStatus: string;
     /** Whether Anthropic reports that paid overage is actively serving traffic. */
     overageInUse?: boolean;
+    /** Why overage is unavailable, verbatim from
+     *  anthropic-ratelimit-unified-overage-disabled-reason (e.g.
+     *  "org_level_disabled"). Present only when the provider states one. */
+    overageDisabledReason?: string;
+    /** Authoritative extra-usage switch from the usage API's
+     *  `extra_usage.is_enabled`. Unlike the header trio this is reported even for
+     *  an account that has never served a request. */
+    overageEnabled?: boolean;
+    /** Which window Anthropic considers binding right now, verbatim from
+     *  anthropic-ratelimit-unified-representative-claim (e.g. "five_hour"). */
+    representativeClaim?: string;
     /** Epoch ms when we last captured this data */
     lastUpdated: number;
     /** Dynamic per-plan limit buckets from the usage API `limits[]` array
@@ -1033,8 +1064,21 @@ export type AccountQuotaWindow = {
     isActive?: boolean;
     /** Model display name for model-scoped windows (e.g. "Fable"). */
     scopeModel?: string;
+    /** Wire model id for the scope when the provider reports one
+     *  (`scope.model.id`), which matches a request's `model` exactly and so beats
+     *  display-name matching. Often null in practice. */
+    scopeModelId?: string;
     /** Surface scope when the provider reports one. */
     scopeSurface?: string;
+    /** Epoch ms this individual window was observed. Lets a header-derived window
+     *  and a usage-API window on the same account age independently — the flat
+     *  `lastUpdated` refreshes on every response and would otherwise make a
+     *  days-old scoped window look current. */
+    updatedAt?: number;
+    /** Provenance of this window, mirroring AccountQuotaSource. */
+    source?: AccountQuotaSource;
+    /** Raw unified header token for header-derived windows, e.g. "7d_oi". */
+    headerWindow?: string;
 };
 /** One utilization window from the OAuth usage endpoint (wire shape, loose). */
 export type AnthropicUsageWindow = {
@@ -2316,6 +2360,40 @@ export type ClaudeSnapshot = {
 export type ParsedClaudeError = {
     errorType?: string;
     message?: string;
+    /** `error.details.error_code`, e.g. "oauth_not_allowed_for_organization".
+     *  Absent on payloads that carry no details object. */
+    errorCode?: string;
+};
+/**
+ * Accounts rejected by an organization/plan entitlement policy during a single
+ * request. Anthropic answers such an account with a `permission_error` that no
+ * amount of retrying or token refreshing can fix, but which a *different*
+ * account may not hit at all — so it drives rotation, and is reported to the
+ * client only once every account has been tried.
+ */
+export type AnthropicEntitlementFailure = {
+    status: number;
+    /** Labels of every account that rejected this request on entitlement. */
+    accounts: string[];
+    /** Upstream message from the first such rejection. */
+    message: string;
+    errorCode?: string;
+};
+/**
+ * Every account's model-scoped window for the requested model is spent. Unlike
+ * a cooldown this is per-model: the same accounts stay healthy for every other
+ * model, so the client is told to switch model rather than to back off.
+ */
+export type AnthropicScopedExhaustion = {
+    /** Wire model id from the request. */
+    model: string;
+    /** Display name of the exhausted window, e.g. "Fable". */
+    scopeModel: string;
+    /** Epoch ms of the soonest reset across the exhausted accounts. */
+    earliestResetMs: number;
+    accounts: string[];
+    /** Provider reason overage is unavailable, e.g. "org_level_disabled". */
+    overageDisabledReason?: string;
 };
 /** ora spinner instance held by proxy CLI commands, nullable when --quiet. */
 export type ProxySpinner = Ora | null;
@@ -2340,7 +2418,12 @@ export type ProxyRequestRoutingSnapshot = {
     quotaRoutingEnabled: boolean;
     sessionSoftLimit: number;
     sessionResetToleranceMs: number;
+    /** Operator policy on spending paid extra usage once a subscription window is
+     *  spent. Only "never" can override the provider's own signal. */
+    useOverage: ProxyOveragePolicy;
 };
+/** Operator policy for paid extra usage. */
+export type ProxyOveragePolicy = "auto" | "always" | "never";
 /** Immutable last-known-good proxy configuration published at runtime. */
 export type ProxyRuntimeConfigSnapshot = ProxyRequestRoutingSnapshot & {
     loadedAt: string;

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

@@ -998,6 +998,19 @@ export type ProxyRoutingConfig = {
     passthroughModels?: string[];
     /** Enable quota-aware fill-first account ordering. Defaults to true. */
     quotaRouting?: boolean;
+    /**
+     * Whether an account may keep serving on paid extra usage once its
+     * subscription window is spent.
+     *
+     * - `auto` (default): follow whatever Anthropic reports for the account.
+     * - `never`: park the account at the subscription limit even when extra usage
+     *   is enabled, so the pool can never spend credits.
+     * - `always`: keep serving whenever the provider permits extra usage.
+     *
+     * Only `never` can override the provider — nothing here can enable extra usage
+     * that Anthropic has disabled (e.g. `org_level_disabled`).
+     */
+    useOverage?: "auto" | "always" | "never";
     /** Session utilization threshold used to proactively demote an account. */
     sessionSoftLimit?: number;
     /** Reset-time bucket width used when ordering quota windows. */

package/dist/providers/openaiChatCompletionsBase.js

@@ -464,15 +464,22 @@ export class OpenAIChatCompletionsProvider extends BaseProvider {
                         const apiErr = await buildAPIError(url, body, res);
                         // One-shot 400 retry. The overflow corrector runs FIRST (it can
                         // re-fit max_tokens from the provider's own numbers and also
-                        // self-heals the runtime window registry); otherwise a subclass
-                        // may strip a rejected field and return a modified body (e.g.
-                        // NIM's chat_template / reasoning_budget). The retry runs under
-                        // the SAME timeout controller as the first attempt, so the
-                        // configured timeout caps the overall call — matching the
-                        // streaming path, which reuses its composed signal for the retry.
+                        // self-heals the runtime window registry); its output then feeds
+                        // a subclass hook that may strip a rejected field (e.g. NIM's
+                        // chat_template / reasoning_budget), so a body that needs BOTH
+                        // fixes gets both — a plain `??` between the two would let
+                        // whichever ran first silently win and drop the other's fix. The
+                        // retry runs under the SAME timeout controller as the first
+                        // attempt, so the configured timeout caps the overall call —
+                        // matching the streaming path, which reuses its composed signal
+                        // for the retry.
                         const retryBody = res.status === 400
-                            ? (correctBodyAfterContextOverflow(body, apiErr) ??
-                                adjustBodyAfter400(body, apiErr))
+                            ? (() => {
+                                const typedErr = apiErr;
+                                const overflowCorrected = correctBodyAfterContextOverflow(body, typedErr);
+                                return (adjustBodyAfter400(overflowCorrected ?? body, typedErr) ??
+                                    overflowCorrected);
+                            })()
                             : undefined;
                         if (!retryBody) {
                             throw apiErr;
@@ -967,13 +974,18 @@ export class OpenAIChatCompletionsProvider extends BaseProvider {
             // consumed inside doFetch's closure, either returned on success or
             // discarded after buildAPIError read its body on failure.
             const apiErr = err;
-            // Overflow corrector first (re-fits max_tokens from the provider's
-            // own numbers + self-heals the window registry), then the subclass
-            // hook (e.g. NIM strips chat_template / reasoning_budget when a model
-            // rejects them).
+            // Overflow corrector first (re-fits max_tokens from the provider's own
+            // numbers + self-heals the window registry); its output then feeds the
+            // subclass hook (e.g. NIM strips chat_template / reasoning_budget when
+            // a model rejects them), so a body needing BOTH fixes gets both — a
+            // plain `??` between the two would let whichever ran first silently
+            // win and drop the other's fix.
             const retryBody = apiErr.statusCode === 400
-                ? (this.correctBodyAfterContextOverflow(body, apiErr) ??
-                    this.adjustBodyAfter400(body, apiErr))
+                ? (() => {
+                    const overflowCorrected = this.correctBodyAfterContextOverflow(body, apiErr);
+                    return (this.adjustBodyAfter400(overflowCorrected ?? body, apiErr) ??
+                        overflowCorrected);
+                })()
                 : undefined;
             if (!retryBody) {
                 throw apiErr;

package/dist/proxy/accountCooldown.js

@@ -2,7 +2,8 @@ import { readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { AsyncMutex } from "../utils/asyncMutex.js";
-import { ACCOUNT_COOLING_REASONS } from "./routingEvidence.js";
+import { logger } from "../utils/logger.js";
+import { ACCOUNT_COOLING_REASONS, MAX_COOLDOWN_MS_BY_REASON, } from "./routingEvidence.js";
 import { writeJsonSnapshotAtomically } from "./snapshotPersistence.js";
 const COOLDOWN_FILE = "account-cooldowns.json";
 const VALID_REASONS = new Set(ACCOUNT_COOLING_REASONS);
@@ -32,13 +33,45 @@ function isPersistedCooldown(value) {
         typeof candidate.reason === "string" &&
         VALID_REASONS.has(candidate.reason));
 }
+/**
+ * Cap a persisted cooldown at what its reason can plausibly mean, measured from
+ * when it was written.
+ *
+ * Entries written before per-reason ceilings existed can hold a wildly
+ * out-of-range wait — a "session" cooldown running for days, from a single stale
+ * reset timestamp. Clamping on load heals those without operator action.
+ * Clamping rather than dropping keeps a legitimate long weekly cooldown intact.
+ */
+function sanitizePersistedCooldown(accountKey, entry) {
+    const ceiling = MAX_COOLDOWN_MS_BY_REASON[entry.reason];
+    if (ceiling === undefined) {
+        return entry;
+    }
+    const latest = entry.updatedAt + ceiling;
+    if (entry.coolingUntil <= latest) {
+        return entry;
+    }
+    // Announce it: an account silently parked far beyond what its reason can mean
+    // is exactly the condition that is hard to diagnose from the outside, and this
+    // runs once per process so it cannot become noise.
+    const hours = (ms) => (ms / 3_600_000).toFixed(1);
+    logger.always(`[proxy] cooldown clamp: ${accountKey} ${entry.reason} entry healed from ` +
+        `${hours(entry.coolingUntil - entry.updatedAt)}h to ` +
+        `${hours(ceiling)}h — the stored wait exceeded what "${entry.reason}" can mean`);
+    return { ...entry, coolingUntil: latest };
+}
 async function ensureAccountCooldownsLoaded() {
     if (!cacheLoaded) {
         if (!cacheLoadPromise) {
             cacheLoadPromise = (async () => {
                 try {
                     const parsed = JSON.parse(await readFile(getCooldownFilePath(), "utf8"));
-                    memoryCache = Object.fromEntries(Object.entries(parsed).filter((entry) => isPersistedCooldown(entry[1])));
+                    memoryCache = Object.fromEntries(Object.entries(parsed)
+                        .filter((entry) => isPersistedCooldown(entry[1]))
+                        .map(([key, entry]) => [
+                        key,
+                        sanitizePersistedCooldown(key, entry),
+                    ]));
                 }
                 catch {
                     memoryCache = {};

package/dist/proxy/accountQuota.d.ts

@@ -9,7 +9,14 @@
  * updates an in-memory cache and debounces disk writes so the request/response
  * path is never blocked by file I/O.
  */
-import type { AccountQuota } from "../types/index.js";
+import type { AccountQuota, AccountQuotaWindow } from "../types/index.js";
+/**
+ * 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 declare function modelFamilyToken(model: string): string;
 /** Read and normalize Anthropic's authoritative top-level unified status. */
 export declare function getUnifiedRateLimitStatus(headers: Headers | Record<string, string>): string | undefined;
 /**
@@ -20,13 +27,32 @@ export declare function getUnifiedRateLimitStatus(headers: Headers | Record<stri
  * fallback percentage together with an allowed overage status, which is the
  * equivalent provider state.
  */
-export declare function isQuotaOverageAvailable(quota: Pick<AccountQuota, "fallbackPercentage" | "fallbackStatus" | "overageStatus" | "overageInUse" | "upgradePaths"> | null | undefined): boolean;
+export declare function isQuotaOverageAvailable(quota: Pick<AccountQuota, "fallbackPercentage" | "fallbackStatus" | "overageStatus" | "overageInUse" | "overageEnabled" | "overageDisabledReason" | "upgradePaths"> | null | undefined): boolean;
 /**
  * Parse Anthropic rate-limit / quota headers into an `AccountQuota`.
  * Returns `null` when key headers are absent.
  * Pure computation — no I/O, no blocking.
  */
-export declare function parseQuotaHeaders(headers: Headers | Record<string, string>): AccountQuota | null;
+export declare function parseQuotaHeaders(headers: Headers | Record<string, string>, opts?: {
+    model?: string;
+    now?: number;
+}): AccountQuota | null;
+/**
+ * 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 declare function mergeQuotaWindows(existing: AccountQuotaWindow[] | undefined, incoming: AccountQuotaWindow[] | undefined): AccountQuotaWindow[] | undefined;
+/**
+ * Fold a freshly observed snapshot onto the previous one for the same account,
+ * preserving dynamic windows the new snapshot does not carry.
+ */
+export declare function mergeQuotaSnapshot(previous: AccountQuota | undefined, incoming: AccountQuota): AccountQuota;
 /**
  * Initialise the quota module with a custom file path.
  * When set, all reads/writes go to this path instead of the default

package/dist/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/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,