@juspay/neurolink 11.2.0 → 11.2.2

package/dist/server/routes/claudeProxyRoutes.js

@@ -16,10 +16,11 @@ import { Agent } from "undici";
 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, isQuotaOverageAvailable, loadAccountQuotas, parseQuotaHeaders, saveAccountQuota, } from "../../proxy/accountQuota.js";
+import { getUnifiedRateLimitStatus, isQuotaOverageAvailable, loadAccountQuotas, mergeQuotaSnapshot, modelFamilyToken, parseQuotaHeaders, saveAccountQuota, } from "../../proxy/accountQuota.js";
 import { fetchAccountUsage, listAnthropicAccountsForUsage, usageToQuota, } from "../../proxy/accountUsage.js";
 import { AccountQuotaRefreshCoordinator } from "../../proxy/accountQuotaRefreshCoordinator.js";
 import { ProviderTransportCoordinator } from "../../proxy/providerTransportCoordinator.js";
+import { MAX_COOLDOWN_MS_BY_REASON } from "../../proxy/routingEvidence.js";
 import { buildProxyLimitHeaders, summarizePoolHeadroom, } from "../../proxy/quotaHeaders.js";
 import { buildClaudeError, ClaudeStreamSerializer, generateToolUseId, parseClaudeRequest, serializeClaudeResponse, } from "../../proxy/claudeFormat.js";
 import { buildAnthropicModelsListResponse, buildTranslationOptions, extractText, extractToolArgs, extractUsageFromStreamResult, handleTranslatedJsonRequest, handleTranslatedStreamRequest, hasTranslatedOutput, } from "../../proxy/proxyTranslationEngine.js";
@@ -487,9 +488,15 @@ function publishLimitHeaders(ctx, args) {
         logger.debug(`[proxy] failed to publish limit headers: ${error instanceof Error ? error.message : String(error)}`);
     }
 }
-/** Clamp a cooldown target epoch-ms into [now+MIN, now+MAX]. */
-function clampCooldownUntil(untilMs, now) {
-    return Math.min(Math.max(untilMs, now + MIN_COOLDOWN_MS), now + MAX_COOLDOWN_MS);
+/**
+ * Clamp a cooldown target epoch-ms into [now+MIN, now+MAX], additionally capped
+ * by what the reason can plausibly mean — a "session" cooldown describes a
+ * 5-hour window, so a stale or malformed reset must not be able to park the
+ * account for days under that label.
+ */
+function clampCooldownUntil(untilMs, now, reason) {
+    const ceiling = Math.min(MAX_COOLDOWN_MS, (reason && MAX_COOLDOWN_MS_BY_REASON[reason]) ?? MAX_COOLDOWN_MS);
+    return Math.min(Math.max(untilMs, now + MIN_COOLDOWN_MS), now + ceiling);
 }
 /**
  * Decide how to cool an account after a genuine (non-anti-abuse) 429.
@@ -505,24 +512,24 @@ function clampCooldownUntil(untilMs, now) {
  * burst / acceleration limit) is transient: honor retry-after as a floor,
  * allow a couple of jittered same-account retries, then a short cooldown.
  */
-function planCooldownFor429(quota, retryAfterMs, now, unifiedStatus = quota?.unifiedStatus) {
+function planCooldownFor429(quota, retryAfterMs, now, unifiedStatus = quota?.unifiedStatus, policy = overagePolicy) {
     // Weekly exhaustion takes precedence — it's the longest, hardest ceiling.
     if (quota && quota.weeklyStatus === "rejected") {
         const reset = resetEpochToMs(quota.weeklyResetAt, now) ??
             (retryAfterMs > 0 ? now + retryAfterMs : now + DEFAULT_COOLING_PERIOD_MS);
         return {
             reason: "weekly",
-            coolingUntil: clampCooldownUntil(reset, now),
+            coolingUntil: clampCooldownUntil(reset, now, "weekly"),
             rotateImmediately: true,
         };
     }
-    const overageAvailable = isQuotaOverageAvailable(quota);
+    const overageAvailable = isOverageUsable(quota, policy);
     if (quota && quota.sessionStatus === "rejected" && !overageAvailable) {
         const reset = resetEpochToMs(quota.sessionResetAt, now) ??
             (retryAfterMs > 0 ? now + retryAfterMs : now + DEFAULT_COOLING_PERIOD_MS);
         return {
             reason: "session",
-            coolingUntil: clampCooldownUntil(reset, now),
+            coolingUntil: clampCooldownUntil(reset, now, "session"),
             rotateImmediately: true,
         };
     }
@@ -533,7 +540,7 @@ function planCooldownFor429(quota, retryAfterMs, now, unifiedStatus = quota?.uni
         const reset = retryAfterMs > 0 ? now + retryAfterMs : now + DEFAULT_HARD_COOLDOWN_MS;
         return {
             reason: "unified",
-            coolingUntil: clampCooldownUntil(reset, now),
+            coolingUntil: clampCooldownUntil(reset, now, "unified"),
             rotateImmediately: true,
         };
     }
@@ -559,8 +566,8 @@ function minutesUntil(untilMs, now) {
  * its reset so the next request skips it instead of discovering the limit via a
  * 429, except when the provider explicitly enables paid overage.
  */
-function reconcileCooldownFromQuota(state, quota, now) {
-    const overageAvailable = isQuotaOverageAvailable(quota);
+function reconcileCooldownFromQuota(state, quota, now, policy = overagePolicy) {
+    const overageAvailable = isOverageUsable(quota, policy);
     let until;
     let reason;
     if (quota.weeklyStatus === "rejected") {
@@ -592,7 +599,7 @@ function reconcileCooldownFromQuota(state, quota, now) {
     if (until === undefined) {
         return null;
     }
-    const clamped = clampCooldownUntil(until, now);
+    const clamped = clampCooldownUntil(until, now, reason);
     if (!state.coolingUntil || clamped > state.coolingUntil) {
         state.coolingUntil = clamped;
         state.coolingReason = reason;
@@ -669,7 +676,7 @@ async function applyAccountUsageResult(account, fetchResult, observedAt, prior)
     if (quota.lastUpdated < (state.quota?.lastUpdated ?? 0)) {
         return state.quota ?? null;
     }
-    state.quota = quota;
+    state.quota = mergeQuotaSnapshot(state.quota, quota);
     const cooldownUpdate = reconcileCooldownFromQuota(state, quota, Date.now());
     if (cooldownUpdate?.kind === "cooled") {
         await saveAccountCooldown(account.key, cooldownUpdate.coolingUntil, cooldownUpdate.coolingReason).catch(() => {
@@ -837,6 +844,46 @@ function getSessionResetToleranceMs() {
     const raw = Number(process.env.NEUROLINK_PROXY_SESSION_RESET_TOLERANCE_MS ?? "");
     return Number.isInteger(raw) && raw > 0 ? raw : 15 * 60 * 1000;
 }
+/**
+ * Operator policy on spending paid extra usage, refreshed from the runtime
+ * config snapshot on every request so a config edit applies mid-flight.
+ *
+ * Module-level rather than threaded through because every routing and cooldown
+ * decision consults it, and the value is uniform for a given proxy generation.
+ */
+let overagePolicy = "auto";
+/**
+ * Publish the operator's extra-usage policy for paths that cannot receive it
+ * explicitly. Callers that make a routing or cooldown decision take it as a
+ * parameter instead — see {@link isOverageUsable} — so a concurrent request or
+ * a hot config reload cannot change the answer mid-flight.
+ *
+ * `undefined` means "no runtime config on this path", which is not a request to
+ * clear an operator's setting, so the current value is kept.
+ */
+function setOveragePolicy(policy) {
+    if (policy !== undefined) {
+        overagePolicy = policy;
+    }
+}
+/** The policy in force for a request that did not capture one explicitly. */
+function currentOveragePolicy() {
+    return overagePolicy;
+}
+/**
+ * Whether this account may keep serving on paid extra usage.
+ *
+ * The provider decides what is possible; the operator decides what is
+ * permitted. `never` therefore vetoes an enabled account, while `always` can
+ * only confirm a signal Anthropic already gives — nothing here can switch on
+ * extra usage the organization has disabled.
+ */
+function isOverageUsable(quota, policy = overagePolicy) {
+    if (policy === "never") {
+        return false;
+    }
+    return isQuotaOverageAvailable(quota);
+}
 /**
  * Derive the ordering signals for an account from its latest runtime quota.
  *
@@ -846,7 +893,152 @@ function getSessionResetToleranceMs() {
  * window Anthropic has since renewed. The snapshot itself is refreshed from
  * live response headers the next time the account serves a request.
  */
-function accountSortMetrics(accountKey, now, sessionSoftLimit, sessionResetToleranceMs) {
+/** Shortest scope token we will match on, so a degenerately broad scope name
+ *  (e.g. "Claude") cannot silently apply a per-model cap to every model. */
+const MIN_SCOPE_TOKEN_LENGTH = 4;
+function normalizeModelToken(value) {
+    return value.toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+/**
+ * The distinguishing part of a scope display name. The shared vendor prefix is
+ * dropped so a window scoped to plain "Claude" collapses to "" and is rejected
+ * by the length guard rather than matching every Claude model.
+ */
+function scopeMatchToken(scopeModel) {
+    const normalized = normalizeModelToken(scopeModel);
+    return normalized.startsWith("claude") ? normalized.slice(6) : normalized;
+}
+/**
+ * How well a window's scope identifies the requested model, or null when it does
+ * not apply. Higher wins; an exact wire-id agreement is unambiguous and so
+ * outranks every display-name match.
+ */
+function scopeMatchScore(window, normalizedModel, requestedFamily) {
+    if (window.scopeModelId &&
+        normalizeModelToken(modelFamilyToken(window.scopeModelId)) ===
+            requestedFamily) {
+        return Number.MAX_SAFE_INTEGER;
+    }
+    if (!window.scopeModel) {
+        return null;
+    }
+    const scopeToken = scopeMatchToken(window.scopeModel);
+    if (scopeToken.length < MIN_SCOPE_TOKEN_LENGTH ||
+        !normalizedModel.includes(scopeToken)) {
+        return null;
+    }
+    return scopeToken.length;
+}
+/**
+ * When a scoped window was last observed. Falls back through the usage-API
+ * sweep timestamp to the flat snapshot time.
+ *
+ * Needed because the flat fields refresh on every response while `windows` only
+ * changes when the served model has a scoped cap — so a days-old scoped window
+ * rides along on a `lastUpdated` from seconds ago and looks current.
+ */
+function scopedWindowObservedAt(quota, window) {
+    return window.updatedAt ?? quota.windowsUpdatedAt ?? quota.lastUpdated;
+}
+/**
+ * Find the model-scoped quota window that applies to the requested model.
+ *
+ * Two sources describe the same cap differently: response headers carry the wire
+ * id of the model just served, while the usage API reports a DISPLAY name
+ * ("Fable", "Claude Opus 4.6"). So an exact wire-id match is tried first and
+ * display-name containment over alphanumeric-normalized forms is the fallback.
+ * Among equally specific matches the freshest observation wins, which favours
+ * the continuously-updated header window over a manually-refreshed one.
+ *
+ * Returns null whenever the account reports no applicable, still-fresh scoped
+ * cap — the common case.
+ */
+function matchScopedQuotaWindow(quota, requestedModel, now = Date.now()) {
+    if (!quota?.windows?.length || !requestedModel) {
+        return null;
+    }
+    const normalizedModel = normalizeModelToken(requestedModel);
+    if (!normalizedModel) {
+        return null;
+    }
+    const requestedFamily = normalizeModelToken(modelFamilyToken(requestedModel));
+    let best = null;
+    let bestScore = -1;
+    let bestObservedAt = -1;
+    for (const window of quota.windows) {
+        // `isActive` marks which window the provider considers binding right now,
+        // not whether the cap applies — a scoped cap reads as inactive until it is
+        // the tightest constraint, which is far too late to route around it.
+        if (now - scopedWindowObservedAt(quota, window) >
+            QUOTA_SNAPSHOT_FRESHNESS_MS) {
+            continue;
+        }
+        const score = scopeMatchScore(window, normalizedModel, requestedFamily);
+        if (score === null) {
+            continue;
+        }
+        const observedAt = scopedWindowObservedAt(quota, window);
+        if (score > bestScore ||
+            (score === bestScore && observedAt > bestObservedAt)) {
+            best = window;
+            bestScore = score;
+            bestObservedAt = observedAt;
+        }
+    }
+    return best;
+}
+/**
+ * Split a candidate set by whether each account can still serve the requested
+ * model under its model-scoped cap.
+ *
+ * An account is scoped out only on evidence strong enough to act on: a fresh
+ * window, a reset that is actually ticking, a rejected/spent reading, and no
+ * paid extra usage to absorb the overflow. Anything weaker leaves the account
+ * eligible — a stale or mis-parsed window must never be able to empty the pool.
+ *
+ * `exhaustion` is populated only when every candidate is scoped out AND the
+ * evidence is trustworthy, which is what lets the caller report "switch model"
+ * instead of a generic rate limit.
+ */
+function evaluateScopedExhaustion(accounts, requestedModel, now = Date.now(), policy = overagePolicy) {
+    if (!requestedModel || accounts.length === 0) {
+        return { eligible: accounts, exhaustion: null };
+    }
+    const eligible = [];
+    const exhausted = [];
+    let overageDisabledReason;
+    for (const account of accounts) {
+        const quota = accountRuntimeState.get(account.key)?.quota;
+        const window = matchScopedQuotaWindow(quota, requestedModel, now);
+        const reset = window ? resetEpochToMs(window.resetsAt, now) : undefined;
+        const spent = window !== null &&
+            reset !== undefined &&
+            ((window.status ?? "").trim().toLowerCase() === "rejected" ||
+                (window.used ?? 0) >= 1) &&
+            !isOverageUsable(quota, policy);
+        if (!spent || !window) {
+            eligible.push(account);
+            continue;
+        }
+        exhausted.push({ label: account.label, window });
+        overageDisabledReason ??= quota?.overageDisabledReason;
+    }
+    if (eligible.length > 0 || exhausted.length === 0) {
+        return { eligible, exhaustion: null };
+    }
+    const earliestResetMs = Math.min(...exhausted.map((entry) => resetEpochToMs(entry.window.resetsAt, now) ?? Number.POSITIVE_INFINITY));
+    return {
+        eligible,
+        exhaustion: {
+            model: requestedModel,
+            scopeModel: exhausted[0]?.window.scopeModel ?? modelFamilyToken(requestedModel),
+            earliestResetMs,
+            accounts: exhausted.map((entry) => entry.label),
+            ...(overageDisabledReason ? { overageDisabledReason } : {}),
+        },
+    };
+}
+function accountSortMetrics(accountKey, now, sessionSoftLimit, sessionResetToleranceMs, requestedModel, policy = overagePolicy) {
     const st = accountRuntimeState.get(accountKey);
     const q = st?.quota;
     const quotaLastUpdated = q && Number.isFinite(q.lastUpdated) ? q.lastUpdated : null;
@@ -902,7 +1094,9 @@ function accountSortMetrics(accountKey, now, sessionSoftLimit, sessionResetToler
             ? (routingQuota.weeklyStatus ?? "unknown")
             : "allowed"
         : null;
-    const overageEligible = isQuotaOverageAvailable(routingQuota);
+    // isOverageUsable layers the operator's routing.use-overage policy over the
+    // provider signal isQuotaOverageAvailable reads.
+    const overageEligible = isOverageUsable(routingQuota, policy);
     const hardSaturated = !overageEligible &&
         (sessionStatus === "rejected" ||
             sessionStatus === "throttled" ||
@@ -916,9 +1110,41 @@ function accountSortMetrics(accountKey, now, sessionSoftLimit, sessionResetToler
         sessionTicking &&
         (sessionUsed ?? 0) >= sessionSoftLimit;
     const saturated = hardSaturated || softSaturated;
+    // Model-scoped weekly cap for the model this request actually asks for.
+    // Reset-freshened exactly like session/weekly: a window whose reset has
+    // passed reads as renewed, never as spent.
+    const scopedWindow = matchScopedQuotaWindow(routingQuota, requestedModel, now);
+    const scopedReset = scopedWindow
+        ? resetEpochToMs(scopedWindow.resetsAt, now)
+        : undefined;
+    const scopedTicking = scopedReset !== undefined;
+    const scopedUsed = scopedWindow
+        ? scopedTicking
+            ? scopedWindow.used
+            : 0
+        : null;
+    const scopedStatus = scopedWindow
+        ? scopedTicking
+            ? (scopedWindow.status ?? "unknown")
+            : "allowed"
+        : null;
+    const scopedSaturated = !quotaStale && scopedTicking && (scopedUsed ?? 0) >= sessionSoftLimit;
     return {
-        usable: !coolingActive && !hardSaturated,
+        // A rejected model-scoped window means this account cannot serve THIS
+        // model, even though it may be perfectly healthy for others. Excluding it
+        // here only affects ordering — the real gate is evaluateScopedExhaustion,
+        // and neither cools the account, which would wrongly withhold it from
+        // every other model.
+        usable: !coolingActive &&
+            !hardSaturated &&
+            (scopedStatus !== "rejected" || overageEligible),
         saturated,
+        scopedModel: scopedWindow?.scopeModel ?? null,
+        scopedStatus,
+        scopedUsed,
+        scopedReset: scopedReset ?? Number.POSITIVE_INFINITY,
+        scopedUsedForSort: scopedUsed ?? -1,
+        scopedSaturated,
         hasQuota: !!q,
         quotaEvidenceRank: quotaFreshness === "fresh" || quotaFreshness === "stale_known"
             ? 0
@@ -988,6 +1214,12 @@ function compareAccountRoutingFactors(a, b, metricsByKey, primaryKey) {
     if (ma.saturated !== mb.saturated) {
         return [ma.saturated ? 1 : -1, "session_headroom"];
     }
+    // Per-model headroom, after overall session capacity: an account whose cap
+    // for THIS model is nearly spent is demoted even when its 5h/7d are healthy.
+    // No-op when neither account reports a scoped window for the model.
+    if (ma.scopedSaturated !== mb.scopedSaturated) {
+        return [ma.scopedSaturated ? 1 : -1, "scoped_headroom"];
+    }
     if (ma.saturated && mb.saturated) {
         if (ma.sessionResetBucket !== mb.sessionResetBucket) {
             return [ma.sessionResetBucket - mb.sessionResetBucket, "session_reset"];
@@ -1004,6 +1236,19 @@ function compareAccountRoutingFactors(a, b, metricsByKey, primaryKey) {
             return [ma.sessionResetBucket - mb.sessionResetBucket, "session_reset"];
         }
     }
+    // Fill-first within the per-model allowance: finish off the account closest
+    // to spending its cap for this model before opening a fresher one. Ranked
+    // above overall weekly utilization because it is the tighter constraint.
+    // Both sides must actually report a scoped window. Comparing a real
+    // utilization against the "absent" sentinel would rank the account that has a
+    // window above one that does not — and since only the account serving a model
+    // gets that model's window, it would funnel all of a model's traffic onto
+    // whichever account happened to serve it first.
+    if (ma.scopedUsed !== null &&
+        mb.scopedUsed !== null &&
+        ma.scopedUsedForSort !== mb.scopedUsedForSort) {
+        return [mb.scopedUsedForSort - ma.scopedUsedForSort, "scoped_utilization"];
+    }
     if (ma.weeklyUsedForSort !== mb.weeklyUsedForSort) {
         return [mb.weeklyUsedForSort - ma.weeklyUsedForSort, "weekly_utilization"];
     }
@@ -1012,10 +1257,10 @@ function compareAccountRoutingFactors(a, b, metricsByKey, primaryKey) {
     }
     return [0, "insertion_order"];
 }
-function orderAccountsByQuotaWithMetrics(accounts, now, primaryKey, sessionSoftLimit, sessionResetToleranceMs) {
+function orderAccountsByQuotaWithMetrics(accounts, now, primaryKey, sessionSoftLimit, sessionResetToleranceMs, requestedModel) {
     const metricsByKey = new Map(accounts.map((account) => [
         account.key,
-        accountSortMetrics(account.key, now, sessionSoftLimit, sessionResetToleranceMs),
+        accountSortMetrics(account.key, now, sessionSoftLimit, sessionResetToleranceMs, requestedModel),
     ]));
     return {
         orderedAccounts: [...accounts].sort((a, b) => compareAccountRoutingFactors(a, b, metricsByKey, primaryKey)[0]),
@@ -1046,8 +1291,8 @@ function orderAccountsByQuotaWithMetrics(accounts, now, primaryKey, sessionSoftL
  * Cooling/rejected accounts sort last, soonest-back-to-service first, as
  * last resort.
  */
-function orderAccountsByQuota(accounts, now, primaryKey, sessionSoftLimit = getSessionSoftLimit(), sessionResetToleranceMs = getSessionResetToleranceMs()) {
-    return orderAccountsByQuotaWithMetrics(accounts, now, primaryKey, sessionSoftLimit, sessionResetToleranceMs).orderedAccounts;
+function orderAccountsByQuota(accounts, now, primaryKey, sessionSoftLimit = getSessionSoftLimit(), sessionResetToleranceMs = getSessionResetToleranceMs(), requestedModel) {
+    return orderAccountsByQuotaWithMetrics(accounts, now, primaryKey, sessionSoftLimit, sessionResetToleranceMs, requestedModel).orderedAccounts;
 }
 function scheduleAdaptiveQuotaRefreshes(accounts, orderedAccounts, sessionSoftLimit, routingMetrics) {
     for (const account of accounts) {
@@ -1160,6 +1405,12 @@ function buildRoutingDecision(args) {
             weeklyResetAt: Number.isFinite(metrics.weeklyReset)
                 ? metrics.weeklyReset
                 : null,
+            scopedModel: metrics.scopedModel,
+            scopedStatus: metrics.scopedStatus,
+            scopedUsed: metrics.scopedUsed,
+            scopedResetAt: Number.isFinite(metrics.scopedReset)
+                ? metrics.scopedReset
+                : null,
         });
     }
     const initialAccount = orderedAccounts[0];
@@ -1202,7 +1453,7 @@ function buildRoutingDecision(args) {
     };
 }
 function selectClaudeProxyAccountOrder(args) {
-    const { enabledAccounts, accountStrategy, primaryAccountKey, quotaRoutingEnabled, sessionSoftLimit, sessionResetToleranceMs, setRoutingDecision, } = args;
+    const { enabledAccounts, accountStrategy, primaryAccountKey, quotaRoutingEnabled, sessionSoftLimit, sessionResetToleranceMs, requestedModel, setRoutingDecision, } = args;
     let orderedAccounts = [...enabledAccounts];
     const evaluatedAt = Date.now();
     let metricsByKey;
@@ -1215,7 +1466,7 @@ function selectClaudeProxyAccountOrder(args) {
         maybeResetPrimaryToHome(enabledAccounts, primaryAccountKey);
     }
     if (quotaOrdered) {
-        const quotaOrder = orderAccountsByQuotaWithMetrics(enabledAccounts, evaluatedAt, primaryAccountKey, sessionSoftLimit, sessionResetToleranceMs);
+        const quotaOrder = orderAccountsByQuotaWithMetrics(enabledAccounts, evaluatedAt, primaryAccountKey, sessionSoftLimit, sessionResetToleranceMs, requestedModel);
         orderedAccounts = quotaOrder.orderedAccounts;
         metricsByKey = quotaOrder.metricsByKey;
         if (logger.shouldLog("debug")) {
@@ -1243,7 +1494,7 @@ function selectClaudeProxyAccountOrder(args) {
         }
         metricsByKey = new Map(enabledAccounts.map((account) => [
             account.key,
-            accountSortMetrics(account.key, evaluatedAt, sessionSoftLimit, sessionResetToleranceMs),
+            accountSortMetrics(account.key, evaluatedAt, sessionSoftLimit, sessionResetToleranceMs, requestedModel),
         ]));
     }
     const routingDecision = buildRoutingDecision({
@@ -1818,7 +2069,9 @@ async function handleClaudePassthroughRequest(args) {
     // to report — but the upstream quota headers are still the caller's real
     // limits. Published before the ok/non-ok split so a 429 carries them too.
     {
-        const passthroughQuota = parseQuotaHeaders(response.headers);
+        const passthroughQuota = parseQuotaHeaders(response.headers, {
+            model: body.model,
+        });
         publishLimitHeaders(ctx, {
             upstreamHeaders: response.headers,
             quota: passthroughQuota,
@@ -2216,6 +2469,11 @@ async function loadClaudeProxyAccounts(args) {
         startupPruneDone = true;
     }
     const compoundKeys = await tokenStore.listByPrefix("anthropic:");
+    // Tracked so an empty pool can name the real cause: "every account is
+    // entitlement-blocked" is a different problem from "no credentials".
+    const entitlementBlockedLabels = [];
+    let skippedDisabledCount = 0;
+    let skippedForOtherReasons = 0;
     for (const key of compoundKeys) {
         if (!isAccountAllowed(key, accountAllowlist)) {
             logger.debug(`[proxy] skipping account=${key} (not in account allowlist)`);
@@ -2237,11 +2495,16 @@ async function loadClaudeProxyAccounts(args) {
             else {
                 logger.debug(`[proxy] skipping disabled account=${key.split(":")[1] ?? key}`);
                 existingState.permanentlyDisabled = true;
+                if (disabledReason === "entitlement_blocked") {
+                    entitlementBlockedLabels.push(key.split(":")[1] ?? key);
+                }
+                skippedDisabledCount += 1;
                 continue;
             }
         }
         const tokens = await tokenStore.loadTokens(key);
         if (!tokens) {
+            skippedForOtherReasons += 1;
             continue;
         }
         let accessToken = tokens.accessToken;
@@ -2349,6 +2612,24 @@ async function loadClaudeProxyAccounts(args) {
         });
     }
     if (accounts.length === 0) {
+        // Once every account has been disabled on entitlement the loop never runs,
+        // so this is the only place the client can learn why. A flat 401 here would
+        // send the user to re-authenticate, which cannot fix an org policy.
+        if (entitlementBlockedLabels.length > 0 &&
+            entitlementBlockedLabels.length === skippedDisabledCount &&
+            skippedForOtherReasons === 0) {
+            const entitlementMessage = buildEntitlementErrorMessage({
+                status: 403,
+                accounts: entitlementBlockedLabels,
+                message: "OAuth authentication is not allowed for this organization.",
+                errorCode: "oauth_not_allowed_for_organization",
+            });
+            tracer?.setError("permission_error", entitlementMessage);
+            tracer?.end(403, Date.now() - requestStartTime);
+            return {
+                response: buildLoggedClaudeError(403, entitlementMessage, "permission_error"),
+            };
+        }
         const noCredentialsMessage = accountAllowlist
             ? "No allowed Anthropic credentials are currently available"
             : compoundKeys.length > 0
@@ -2380,6 +2661,7 @@ async function loadClaudeProxyAccounts(args) {
         quotaRoutingEnabled,
         sessionSoftLimit,
         sessionResetToleranceMs,
+        requestedModel: typeof body.model === "string" ? body.model : undefined,
         setRoutingDecision,
     });
     if (accountStrategy === "fill-first" &&
@@ -2730,8 +3012,100 @@ async function tryAutoClaudeFallback(args) {
         return { response: null, lastErrorMessage: errorMessage };
     }
 }
+/** Human-readable list that stays short when the pool is large. */
+function joinAccountLabels(labels, max = 5) {
+    const unique = [...new Set(labels)];
+    if (unique.length <= max) {
+        return unique.join(", ");
+    }
+    return `${unique.slice(0, max).join(", ")} and ${unique.length - max} more`;
+}
+/**
+ * The client-facing text for "every account is blocked by an organization
+ * entitlement policy". Names the accounts and the remedy, because the upstream
+ * message alone ("OAuth authentication is currently not allowed…") gives no
+ * indication that a pool was involved or which credential to fix.
+ */
+function buildEntitlementErrorMessage(failure) {
+    const count = new Set(failure.accounts).size;
+    const code = failure.errorCode ? ` (${failure.errorCode})` : "";
+    return (`All ${count} Anthropic account${count === 1 ? "" : "s"} are blocked by an ` +
+        `organization entitlement policy${code}. Accounts: ${joinAccountLabels(failure.accounts)}. Upstream: "${failure.message}". Ask an organization admin to re-enable ` +
+        `Claude Code OAuth access, then run: neurolink auth enable anthropic:<account>.`);
+}
+/** Name the subscription window a set of cooldowns is waiting on. */
+function describeCoolingWindow(states) {
+    const reasons = new Set(states.map((state) => state.coolingReason));
+    if (reasons.size === 1) {
+        switch ([...reasons][0]) {
+            case "session":
+                return "5-hour subscription window";
+            case "weekly":
+                return "7-day subscription window";
+            case "unified":
+                return "subscription limit";
+            case "transient":
+                return "upstream burst limit";
+            default:
+                break;
+        }
+    }
+    return "upstream rate limits";
+}
+/**
+ * The provider's stated reason that paid extra usage is unavailable, taken from
+ * the first account that reports one. Anthropic sends this on every response
+ * (e.g. "org_level_disabled"); without it an exhausted pool looks like a proxy
+ * failure rather than a billing policy.
+ */
+function findOverageDisabledReason(accounts) {
+    for (const account of accounts) {
+        const quota = accountRuntimeState.get(account.key)?.quota;
+        if (quota?.overageDisabledReason &&
+            quota.overageStatus?.trim().toLowerCase() !== "allowed") {
+            return quota.overageDisabledReason;
+        }
+    }
+    return undefined;
+}
+/** Suffix explaining why paid overage cannot absorb an exhausted window. */
+function buildOverageUnavailableSuffix(reason) {
+    if (!reason) {
+        return "";
+    }
+    return (` Paid extra usage is unavailable for this organization (${reason}), so ` +
+        `there is no additional capacity before the window resets.`);
+}
+/**
+ * The client-facing text for "every account has spent its model-scoped cap".
+ * Distinct from a normal rate limit: the same accounts remain healthy for every
+ * other model, so switching model is a real remedy and backing off is not.
+ */
+function buildScopedExhaustionMessage(exhaustion) {
+    const count = new Set(exhaustion.accounts).size;
+    return (`All ${count} Anthropic account${count === 1 ? "" : "s"} have exhausted the ` +
+        `model-scoped limit for ${exhaustion.model} (window "${exhaustion.scopeModel}"). ` +
+        `Other models remain available on this pool — switch model, or add an account ` +
+        `with remaining ${exhaustion.scopeModel} capacity. Earliest reset at ` +
+        `${new Date(exhaustion.earliestResetMs).toISOString()}.` +
+        buildOverageUnavailableSuffix(exhaustion.overageDisabledReason));
+}
 function buildClaudeAnthropicFailureResponse(args) {
-    const { tracer, requestStartTime, authFailureMessage, authCooldownMessage, invalidRequestFailure, sawNetworkError, sawTransientFailure, sawRateLimit, lastError, lastTransportErrorCode, lastTransportScope, fallbackFailureMessage, orderedAccounts, buildLoggedClaudeError, logProxyBody, logFinalRequest, } = args;
+    const { tracer, requestStartTime, authFailureMessage, authCooldownMessage, invalidRequestFailure, entitlementFailure, scopedExhaustion, sawNetworkError, sawTransientFailure, sawRateLimit, lastError, lastTransportErrorCode, lastTransportScope, fallbackFailureMessage, orderedAccounts, buildLoggedClaudeError, logProxyBody, logFinalRequest, } = args;
+    // Ranked above the auth rung on purpose: an organization policy block is a
+    // more specific diagnosis than "authentication failed". But only when the
+    // policy explains the *whole* pool — otherwise a single blocked account would
+    // mask four genuine 5xx failures behind a 403, telling the client not to retry
+    // when retrying is exactly right. No retry-after: waiting cannot fix a policy.
+    const entitlementExplainsPool = entitlementFailure !== null &&
+        orderedAccounts.length > 0 &&
+        new Set(entitlementFailure.accounts).size >= orderedAccounts.length;
+    if (entitlementExplainsPool && entitlementFailure && !sawRateLimit) {
+        const message = buildEntitlementErrorMessage(entitlementFailure);
+        tracer?.setError("permission_error", message);
+        tracer?.end(403, Date.now() - requestStartTime);
+        return buildLoggedClaudeError(403, message, "permission_error");
+    }
     if (authFailureMessage && !sawRateLimit) {
         tracer?.setError("authentication_error", authFailureMessage);
         tracer?.end(401, Date.now() - requestStartTime);
@@ -2786,6 +3160,37 @@ function buildClaudeAnthropicFailureResponse(args) {
             ...(lastTransportScope ? { transportScope: lastTransportScope } : {}),
         });
     }
+    /** Emit the 429 the client sees, with an honest retry-after. */
+    const respondRateLimited = (message, retryAfterSec) => {
+        const errorBody = buildClaudeError(429, message, "overloaded_error");
+        tracer?.setError("rate_limit_error", message);
+        tracer?.end(429, Date.now() - requestStartTime);
+        logFinalRequest(429, "", "final", "rate_limit_error", message);
+        const errorBodyText = JSON.stringify(errorBody);
+        const headers = {
+            "content-type": "application/json",
+            "retry-after": String(retryAfterSec),
+        };
+        logProxyBody({
+            phase: "client_response",
+            headers,
+            body: errorBodyText,
+            bodySize: Buffer.byteLength(errorBodyText, "utf8"),
+            contentType: "application/json",
+            responseStatus: 429,
+            durationMs: Date.now() - requestStartTime,
+        });
+        return new Response(errorBodyText, { status: 429, headers });
+    };
+    // A model-scoped cap is spent on every account. No upstream call was made, so
+    // sawRateLimit is false and this must be caught before the generic
+    // "all accounts failed" 502 below, which would report the wrong cause and
+    // invite an immediate, guaranteed-to-fail retry.
+    if (scopedExhaustion) {
+        const message = buildScopedExhaustionMessage(scopedExhaustion);
+        logger.always(`[proxy] model-scoped limit exhausted for ${scopedExhaustion.model} on all accounts`);
+        return respondRateLimited(message, Math.max(1, Math.ceil((scopedExhaustion.earliestResetMs - Date.now()) / 1000)));
+    }
     if (!sawRateLimit) {
         const fallbackSuffix = fallbackFailureMessage
             ? ` Fallback also failed: ${fallbackFailureMessage}`
@@ -2809,45 +3214,27 @@ function buildClaudeAnthropicFailureResponse(args) {
     const retryAfterSec = allAccountsCooling
         ? Math.max(1, Math.ceil((earliestRetryAt - now) / 1000))
         : 1;
+    // Name the window that actually ran out. "rate limits" alone cannot be acted
+    // on: a 5-hour session window and a 7-day weekly window call for very
+    // different responses from the caller.
+    const windowLabel = describeCoolingWindow(activeRateLimitCooldowns);
+    const overageSuffix = buildOverageUnavailableSuffix(findOverageDisabledReason(orderedAccounts));
     const errorMessage = allAccountsCooling
-        ? `All ${orderedAccounts.length} Anthropic accounts are cooling after upstream rate limits. Earliest retry at ${new Date(earliestRetryAt).toISOString()}.`
-        : `All ${orderedAccounts.length} accounts rate-limited after per-account retries.`;
+        ? `All ${orderedAccounts.length} Anthropic accounts are cooling after the ${windowLabel} was exhausted. Earliest retry at ${new Date(earliestRetryAt).toISOString()}.${overageSuffix}`
+        : `All ${orderedAccounts.length} accounts rate-limited after per-account retries.${overageSuffix}`;
     logger.always(`[proxy] all accounts rate-limited, retry in ${retryAfterSec}s`);
-    const errorBody = buildClaudeError(429, errorMessage, "overloaded_error");
-    tracer?.setError("rate_limit_error", errorMessage);
-    tracer?.end(429, Date.now() - requestStartTime);
-    logFinalRequest(429, "", "final", "rate_limit_error", errorMessage);
-    const errorBodyText = JSON.stringify(errorBody);
-    logProxyBody({
-        phase: "client_response",
-        headers: {
-            "content-type": "application/json",
-            "retry-after": String(retryAfterSec),
-        },
-        body: errorBodyText,
-        bodySize: Buffer.byteLength(errorBodyText, "utf8"),
-        contentType: "application/json",
-        responseStatus: 429,
-        durationMs: Date.now() - requestStartTime,
-    });
-    return new Response(errorBodyText, {
-        status: 429,
-        headers: {
-            "content-type": "application/json",
-            "retry-after": String(retryAfterSec),
-        },
-    });
+    return respondRateLimited(errorMessage, retryAfterSec);
 }
 async function handleAnthropicSuccessfulResponse(args) {
     const { ctx, body, account, accountState, response, tracer, requestStartTime, fetchStartMs, attemptNumber, finalBodyStr, upstreamSpan, logAttempt, logProxyBody, onStreamTerminal, poolAccounts, logFinalRequest, } = args;
     accountState.consecutiveRefreshFailures = 0;
     logger.always(`[proxy] ← ${response.status} account=${account.label}`);
-    const quota = parseQuotaHeaders(response.headers);
+    const quota = parseQuotaHeaders(response.headers, { model: body.model });
     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 rejected windows unless Anthropic explicitly permits overage.
-        accountState.quota = quota;
+        accountState.quota = mergeQuotaSnapshot(accountState.quota, quota);
         const cooldownUpdate = reconcileCooldownFromQuota(accountState, quota, Date.now());
         if (cooldownUpdate?.kind === "cooled") {
             saveAccountCooldown(account.key, cooldownUpdate.coolingUntil, cooldownUpdate.coolingReason).catch(() => {
@@ -2918,7 +3305,7 @@ async function handleAnthropicSuccessfulResponse(args) {
     });
 }
 async function handleAnthropicStreamingSuccessResponse(args) {
-    const { ctx, account, accountState, response, responseHeaders, tracer, requestStartTime, fetchStartMs, attemptNumber, finalBodyStr, upstreamSpan, logAttempt, logProxyBody, onStreamTerminal, logFinalRequest, } = args;
+    const { ctx, body, account, accountState, response, responseHeaders, tracer, requestStartTime, fetchStartMs, attemptNumber, finalBodyStr, upstreamSpan, logAttempt, logProxyBody, onStreamTerminal, logFinalRequest, } = args;
     if (!response.body) {
         recordAttemptError(account.label, account.type, 502);
         logAttempt(502, "stream_error", "No response body from upstream");
@@ -3015,11 +3402,13 @@ async function handleAnthropicStreamingSuccessResponse(args) {
         const bodyText = Buffer.concat(preflight.chunks.map((chunk) => Buffer.from(chunk))).toString("utf8");
         const isRateLimit = preflight.errorType === "rate_limit_error";
         const logicalStatus = isRateLimit ? 429 : 502;
-        const quota = parseQuotaHeaders(responseHeaders);
+        const quota = parseQuotaHeaders(responseHeaders, { model: body.model });
         const now = Date.now();
         if (isRateLimit) {
             const cooldownPlan = planCooldownFor429(quota, parseRetryAfterMs(responseHeaders["retry-after"] ?? null), now, getUnifiedRateLimitStatus(responseHeaders));
-            accountState.quota = quota ?? accountState.quota;
+            accountState.quota = quota
+                ? mergeQuotaSnapshot(accountState.quota, quota)
+                : accountState.quota;
             const rateLimitKind = cooldownPlan.reason === "transient" ? "transient" : "quota";
             if (!accountState.coolingUntil ||
                 cooldownPlan.coolingUntil > accountState.coolingUntil) {
@@ -3480,12 +3869,14 @@ async function handleAnthropicJsonSuccessResponse(args) {
     return { response: responseJson };
 }
 async function handleAnthropicSuccessfulNonStreamRetryResponse(args) {
-    const { account, accountState, retryResp, tracer, requestStartTime, fetchStartMs, attemptNumber, finalBodyStr, upstreamSpan, logAttempt, logProxyBody, logFinalRequest, } = args;
-    const retryQuota = parseQuotaHeaders(retryResp.headers);
+    const { account, accountState, requestedModel, retryResp, tracer, requestStartTime, fetchStartMs, attemptNumber, finalBodyStr, upstreamSpan, logAttempt, logProxyBody, logFinalRequest, } = args;
+    const retryQuota = parseQuotaHeaders(retryResp.headers, {
+        model: requestedModel,
+    });
     if (retryQuota) {
         // Keep the auth-retry success path in parity with the main success path:
         // stash quota for proactive selection and reconcile a rejected window.
-        accountState.quota = retryQuota;
+        accountState.quota = mergeQuotaSnapshot(accountState.quota, retryQuota);
         const cooldownUpdate = reconcileCooldownFromQuota(accountState, retryQuota, Date.now());
         if (cooldownUpdate?.kind === "cooled") {
             saveAccountCooldown(account.key, cooldownUpdate.coolingUntil, cooldownUpdate.coolingReason).catch(() => {
@@ -3566,13 +3957,14 @@ async function handleAnthropicSuccessfulNonStreamRetryResponse(args) {
     return retryJson;
 }
 async function handleAnthropicAuthRetry(args) {
-    const { ctx, body, account, accountState, headers, buildUpstreamBody, url, enabledAccounts, orderedAccounts, tracer, requestStartTime, allocateAttemptNumber, upstreamSpan, logAttempt, logProxyBody, onStreamTerminal, logFinalRequest, lastError, authFailureMessage, sawRateLimit, sawTransientFailure, sawNetworkError, } = args;
+    const { ctx, body, account, accountState, headers, buildUpstreamBody, url, enabledAccounts, orderedAccounts, tracer, requestStartTime, allocateAttemptNumber, upstreamSpan, logAttempt, logProxyBody, onStreamTerminal, logFinalRequest, lastError, authFailureMessage, entitlementFailure, sawRateLimit, sawTransientFailure, sawNetworkError, } = args;
     recordAttemptError(account.label, account.type, 401);
     logAttempt(401, "authentication_error", "received 401 from Anthropic", {
         retryable: true,
     });
     let currentLastError = lastError;
     let currentAuthFailureMessage = authFailureMessage;
+    let currentEntitlementFailure = entitlementFailure;
     let currentSawRateLimit = sawRateLimit;
     let currentSawTransientFailure = sawTransientFailure;
     let currentSawNetworkError = sawNetworkError;
@@ -3656,6 +4048,7 @@ async function handleAnthropicAuthRetry(args) {
                         response: await handleAnthropicSuccessfulNonStreamRetryResponse({
                             account,
                             accountState,
+                            requestedModel: body.model,
                             retryResp,
                             tracer,
                             requestStartTime,
@@ -3677,6 +4070,7 @@ async function handleAnthropicAuthRetry(args) {
                             : {}),
                         lastError: failure?.message ?? currentLastError,
                         authFailureMessage: currentAuthFailureMessage,
+                        entitlementFailure: currentEntitlementFailure,
                         sawRateLimit: currentSawRateLimit || Boolean(failure?.rateLimit),
                         sawTransientFailure: currentSawTransientFailure ||
                             Boolean(failure && !failure.rateLimit),
@@ -3690,6 +4084,7 @@ async function handleAnthropicAuthRetry(args) {
                     continueLoop: false,
                     lastError: currentLastError,
                     authFailureMessage: currentAuthFailureMessage,
+                    entitlementFailure: currentEntitlementFailure,
                     sawRateLimit: currentSawRateLimit,
                     sawTransientFailure: currentSawTransientFailure,
                     sawNetworkError: currentSawNetworkError,
@@ -3746,6 +4141,7 @@ async function handleAnthropicAuthRetry(args) {
                     continueLoop: false,
                     lastError: retryBody,
                     authFailureMessage: currentAuthFailureMessage,
+                    entitlementFailure: currentEntitlementFailure,
                     sawRateLimit: currentSawRateLimit,
                     sawTransientFailure: currentSawTransientFailure,
                     sawNetworkError: currentSawNetworkError,
@@ -3760,9 +4156,11 @@ async function handleAnthropicAuthRetry(args) {
                 // Cool the account per its real reset window before rotating, so a
                 // session/weekly-exhausted account isn't re-selected next request.
                 const nowRetry = Date.now();
-                const retryQuota429 = parseQuotaHeaders(retryRespHeaders);
+                const retryQuota429 = parseQuotaHeaders(retryRespHeaders, {
+                    model: body.model,
+                });
                 if (retryQuota429) {
-                    accountState.quota = retryQuota429;
+                    accountState.quota = mergeQuotaSnapshot(accountState.quota, retryQuota429);
                 }
                 const retryPlan = planCooldownFor429(retryQuota429, parseRetryAfterMs(retryRespHeaders["retry-after"] ?? null), nowRetry, getUnifiedRateLimitStatus(retryRespHeaders));
                 const rateLimitKind = retryPlan.reason === "transient" ? "transient" : "quota";
@@ -3789,6 +4187,36 @@ async function handleAnthropicAuthRetry(args) {
                 break;
             }
             if (retryStatus === 401 || retryStatus === 402 || retryStatus === 403) {
+                // An organization/plan entitlement refusal is not an authentication
+                // problem: the token just minted is valid and refreshing again cannot
+                // change the verdict. Rotate now instead of burning the remaining
+                // refresh cycles and their one-second waits on a certain failure.
+                if (isAccountEntitlementError(retryStatus, retryBody)) {
+                    const parsedRetry = parseClaudeErrorBody(retryBody);
+                    recordAttemptError(account.label, account.type, retryStatus);
+                    retryLogAttempt(retryStatus, "permission_error", summarizeErrorMessage(retryBody));
+                    currentEntitlementFailure = {
+                        status: retryStatus,
+                        accounts: [
+                            ...(currentEntitlementFailure?.accounts ?? []),
+                            account.label,
+                        ],
+                        message: currentEntitlementFailure?.message ??
+                            parsedRetry.message ??
+                            summarizeErrorMessage(retryBody),
+                        ...(parsedRetry.errorCode
+                            ? { errorCode: parsedRetry.errorCode }
+                            : {}),
+                    };
+                    if (account.type === "oauth" &&
+                        isDurableEntitlementBlock(retryStatus, retryBody)) {
+                        await disableAccountUntilReauth(account, accountState, "entitlement_blocked");
+                    }
+                    authRetryError = `entitlement blocked for account=${account.label}`;
+                    currentLastError = authRetryError;
+                    logger.always(`[proxy] ← ${retryStatus} account=${account.label} entitlement blocked after refresh; advancing to next account`);
+                    break;
+                }
                 recordAttemptError(account.label, account.type, retryStatus);
                 retryLogAttempt(retryStatus, "authentication_error", summarizeErrorMessage(retryBody), { retryable: true });
                 if (authRetry < MAX_AUTH_RETRIES - 1) {
@@ -3810,6 +4238,7 @@ async function handleAnthropicAuthRetry(args) {
                     continueLoop: false,
                     lastError: currentLastError,
                     authFailureMessage: currentAuthFailureMessage,
+                    entitlementFailure: currentEntitlementFailure,
                     sawRateLimit: currentSawRateLimit,
                     sawTransientFailure: currentSawTransientFailure,
                     sawNetworkError: currentSawNetworkError,
@@ -3823,6 +4252,7 @@ async function handleAnthropicAuthRetry(args) {
                     continueLoop: false,
                     lastError: currentLastError,
                     authFailureMessage: currentAuthFailureMessage,
+                    entitlementFailure: currentEntitlementFailure,
                     sawRateLimit: currentSawRateLimit,
                     sawTransientFailure: currentSawTransientFailure,
                     sawNetworkError: currentSawNetworkError,
@@ -3863,6 +4293,7 @@ async function handleAnthropicAuthRetry(args) {
                     continueLoop: false,
                     lastError: currentLastError,
                     authFailureMessage: currentAuthFailureMessage,
+                    entitlementFailure: currentEntitlementFailure,
                     sawRateLimit: currentSawRateLimit,
                     sawTransientFailure: currentSawTransientFailure,
                     sawNetworkError: currentSawNetworkError,
@@ -3886,6 +4317,7 @@ async function handleAnthropicAuthRetry(args) {
         continueLoop: true,
         lastError: currentLastError,
         authFailureMessage: currentAuthFailureMessage,
+        entitlementFailure: currentEntitlementFailure,
         sawRateLimit: currentSawRateLimit,
         sawTransientFailure: currentSawTransientFailure,
         sawNetworkError: currentSawNetworkError,
@@ -3969,11 +4401,12 @@ function finalizeAnthropicTerminalTransportError(args) {
     return clientError;
 }
 async function handleAnthropicNonOkResponse(args) {
-    const { response, account, accountState, enabledAccounts, orderedAccounts, tracer, requestStartTime, fetchStartMs, attemptNumber, logAttempt, logProxyBody, logFinalRequest, lastError, authFailureMessage, sawTransientFailure, invalidRequestFailure, } = args;
+    const { response, account, accountState, enabledAccounts, orderedAccounts, tracer, requestStartTime, fetchStartMs, attemptNumber, logAttempt, logProxyBody, logFinalRequest, lastError, authFailureMessage, sawTransientFailure, invalidRequestFailure, entitlementFailure, } = args;
     let currentLastError = lastError;
     let currentAuthFailureMessage = authFailureMessage;
     let currentSawTransientFailure = sawTransientFailure;
     let currentInvalidRequestFailure = invalidRequestFailure;
+    let currentEntitlementFailure = entitlementFailure;
     const errBody = await response.text();
     const errRespHeaders = {};
     response.headers.forEach((value, key) => {
@@ -4023,6 +4456,7 @@ async function handleAnthropicNonOkResponse(args) {
                 authFailureMessage: currentAuthFailureMessage,
                 sawTransientFailure: currentSawTransientFailure,
                 invalidRequestFailure: currentInvalidRequestFailure,
+                entitlementFailure: currentEntitlementFailure,
                 upstreamSpan: undefined,
             };
         }
@@ -4041,6 +4475,53 @@ async function handleAnthropicNonOkResponse(args) {
             authFailureMessage: currentAuthFailureMessage,
             sawTransientFailure: currentSawTransientFailure,
             invalidRequestFailure: currentInvalidRequestFailure,
+            entitlementFailure: currentEntitlementFailure,
+            upstreamSpan: undefined,
+        };
+    }
+    if (account.type === "oauth" &&
+        isAccountEntitlementError(response.status, errBody)) {
+        // Anthropic refuses this credential on organization/plan policy, e.g.
+        // "OAuth authentication is currently not allowed for this organization."
+        // Neither a retry nor a token refresh can fix it, but another account may
+        // not be subject to the same policy — so rotate rather than fail the client.
+        //
+        // Must precede the no-refresh-token branch below: that branch matches the
+        // same 401/402/403 statuses and would disable the account as
+        // `missing_refresh_token`, telling the user to re-login — which cannot help
+        // and burns a working credential.
+        //
+        // Like the beta-rejection branch above, deliberately sets neither
+        // `currentInvalidRequestFailure` (would suppress provider fallback and
+        // outrank a later account's real 429) nor `currentAuthFailureMessage`
+        // (would surface a misleading "re-authenticate" 401).
+        const parsed = parseClaudeErrorBody(errBody);
+        recordAttemptError(account.label, account.type, response.status);
+        currentEntitlementFailure = {
+            status: response.status,
+            accounts: [...(currentEntitlementFailure?.accounts ?? []), account.label],
+            message: currentEntitlementFailure?.message ??
+                parsed.message ??
+                summarizeErrorMessage(errBody),
+            ...(parsed.errorCode ? { errorCode: parsed.errorCode } : {}),
+        };
+        logger.always(`[proxy] ← ${response.status} account=${account.label} entitlement blocked${parsed.errorCode ? ` (${parsed.errorCode})` : ""}; advancing to next account`);
+        logAttempt(response.status, "permission_error", summarizeErrorMessage(errBody));
+        tracer?.setError("permission_error", summarizeErrorMessage(errBody));
+        tracer?.recordRetry(account.label, "entitlement_blocked");
+        if (account.type === "oauth" &&
+            isDurableEntitlementBlock(response.status, errBody)) {
+            await disableAccountUntilReauth(account, accountState, "entitlement_blocked");
+        }
+        advancePrimaryIfCurrent(account.key, enabledAccounts.length, orderedAccounts[0]?.key);
+        currentLastError = summarizeErrorMessage(errBody);
+        return {
+            continueLoop: true,
+            lastError: currentLastError,
+            authFailureMessage: currentAuthFailureMessage,
+            sawTransientFailure: currentSawTransientFailure,
+            invalidRequestFailure: currentInvalidRequestFailure,
+            entitlementFailure: currentEntitlementFailure,
             upstreamSpan: undefined,
         };
     }
@@ -4064,6 +4545,7 @@ async function handleAnthropicNonOkResponse(args) {
             authFailureMessage: currentAuthFailureMessage,
             sawTransientFailure: currentSawTransientFailure,
             invalidRequestFailure: currentInvalidRequestFailure,
+            entitlementFailure: currentEntitlementFailure,
             upstreamSpan: undefined,
         };
     }
@@ -4086,6 +4568,7 @@ async function handleAnthropicNonOkResponse(args) {
             authFailureMessage: currentAuthFailureMessage,
             sawTransientFailure: currentSawTransientFailure,
             invalidRequestFailure: currentInvalidRequestFailure,
+            entitlementFailure: currentEntitlementFailure,
             upstreamSpan: undefined,
         };
     }
@@ -4111,6 +4594,7 @@ async function handleAnthropicNonOkResponse(args) {
             authFailureMessage: currentAuthFailureMessage,
             sawTransientFailure: currentSawTransientFailure,
             invalidRequestFailure: currentInvalidRequestFailure,
+            entitlementFailure: currentEntitlementFailure,
             upstreamSpan: undefined,
         };
     }
@@ -4139,6 +4623,7 @@ async function handleAnthropicNonOkResponse(args) {
             authFailureMessage: currentAuthFailureMessage,
             sawTransientFailure: currentSawTransientFailure,
             invalidRequestFailure: currentInvalidRequestFailure,
+            entitlementFailure: currentEntitlementFailure,
             upstreamSpan: undefined,
         };
     }
@@ -4164,6 +4649,7 @@ async function handleAnthropicNonOkResponse(args) {
         authFailureMessage: currentAuthFailureMessage,
         sawTransientFailure: currentSawTransientFailure,
         invalidRequestFailure: currentInvalidRequestFailure,
+        entitlementFailure: currentEntitlementFailure,
         upstreamSpan: undefined,
     };
 }
@@ -4545,7 +5031,7 @@ function buildAnthropicConstructionRejectionTerminalError() {
     };
 }
 async function fetchAnthropicAccountResponse(args) {
-    const { url, headers, finalBodyStr, account, accountState: _accountState2, enabledAccounts: _enabledAccounts, orderedAccounts: _orderedAccounts, tracer, logAttempt, logProxyBody, fetchStartMs, attemptNumber, currentLastError, currentSawRateLimit, currentSawNetworkError, upstreamSpan, } = args;
+    const { url, headers, finalBodyStr, requestedModel, account, accountState: _accountState2, enabledAccounts: _enabledAccounts, orderedAccounts: _orderedAccounts, tracer, logAttempt, logProxyBody, fetchStartMs, attemptNumber, currentLastError, currentSawRateLimit, currentSawNetworkError, upstreamSpan, } = args;
     let lastError = currentLastError;
     let sawRateLimit = currentSawRateLimit;
     let sawNetworkError = currentSawNetworkError;
@@ -4649,7 +5135,7 @@ async function fetchAnthropicAccountResponse(args) {
         // exhaustion 429 we rotate immediately and park the account until its
         // ACTUAL reset, not a 60s hardcap.
         const now = Date.now();
-        const quota = parseQuotaHeaders(errRespHeaders);
+        const quota = parseQuotaHeaders(errRespHeaders, { model: requestedModel });
         const unifiedStatus = getUnifiedRateLimitStatus(errRespHeaders);
         const cooldownPlan = planCooldownFor429(quota, retryAfterMs, now, unifiedStatus);
         const rateLimitKind = cooldownPlan.reason === "transient" ? "transient" : "quota";
@@ -4712,6 +5198,10 @@ async function handleAnthropicRoutedClaudeRequest(args) {
         return loadedAccounts.response;
     }
     const { accounts, enabledAccounts, orderedAccounts, bodyStr, requestStart, toolCount, url, clientHeaders, isClaudeClientRequest, } = loadedAccounts;
+    // Snapshot the operator policy once. Reading the module value later would let
+    // a concurrent /limits call or a hot config reload change this request's
+    // answer partway through its own account loop.
+    const requestOveragePolicy = currentOveragePolicy();
     const loopState = {
         lastError: undefined,
         sawRateLimit: false,
@@ -4720,6 +5210,8 @@ async function handleAnthropicRoutedClaudeRequest(args) {
         invalidRequestFailure: null,
         authFailureMessage: null,
         authCooldownMessage: null,
+        entitlementFailure: null,
+        scopedExhaustion: null,
         attemptNumber: 0,
     };
     const acctSelectionSpan = tracer?.startAccountSelection();
@@ -4750,6 +5242,25 @@ async function handleAnthropicRoutedClaudeRequest(args) {
             loopState.authCooldownMessage = `All ${orderedAccounts.length} Anthropic accounts are temporarily unavailable while OAuth refresh is cooling. Earliest retry at ${new Date(earliestRetryAt).toISOString()}.`;
         }
     }
+    // Second eligibility gate, alongside cooldowns: an account whose model-scoped
+    // cap for THIS model is spent will 429 with certainty. Unlike a cooldown the
+    // condition is per-model, so it must not park the account — it stays fully
+    // available for every other model.
+    const scopedExhaustion = evaluateScopedExhaustion(effectiveAccounts, typeof body.model === "string" ? body.model : undefined, Date.now(), requestOveragePolicy);
+    if (scopedExhaustion.eligible.length > 0) {
+        effectiveAccounts = scopedExhaustion.eligible;
+    }
+    else if (scopedExhaustion.exhaustion) {
+        // Every account is scoped out on evidence we trust. Record it and let the
+        // loop fall through to the post-loop path, so a configured fallback chain
+        // still runs and only the terminal message changes. Returning here instead
+        // would silently drop that fallback.
+        loopState.scopedExhaustion = scopedExhaustion.exhaustion;
+        loopState.lastError = `Model-scoped limit exhausted for ${scopedExhaustion.exhaustion.model}`;
+        effectiveAccounts = [];
+    }
+    // Otherwise the scoped evidence was stale or absent: attempt the request
+    // anyway rather than let a mis-parsed window take the pool down.
     const accountAdmissionCapacity = modelRouter?.getMaxInflightPerAccount?.();
     // When every eligible account is busy, reserve the first account that frees
     // instead of arbitrarily waiting behind the last configured account.
@@ -4850,6 +5361,7 @@ async function handleAnthropicRoutedClaudeRequest(args) {
                         url,
                         headers: preparedAttempt.headers,
                         finalBodyStr: preparedAttempt.finalBodyStr,
+                        requestedModel: body.model,
                         account,
                         accountState,
                         enabledAccounts,
@@ -4901,7 +5413,7 @@ async function handleAnthropicRoutedClaudeRequest(args) {
                         const plan = fetchResult.cooldownPlan;
                         // Refresh the account's quota snapshot for proactive selection.
                         if (fetchResult.quota) {
-                            accountState.quota = fetchResult.quota;
+                            accountState.quota = mergeQuotaSnapshot(accountState.quota, fetchResult.quota);
                             saveAccountQuota(account.label, fetchResult.quota).catch(() => {
                                 // Non-fatal: routing already has the in-memory snapshot.
                             });
@@ -4995,12 +5507,14 @@ async function handleAnthropicRoutedClaudeRequest(args) {
                         onStreamTerminal: admissionLease.release,
                         lastError: loopState.lastError,
                         authFailureMessage: loopState.authFailureMessage,
+                        entitlementFailure: loopState.entitlementFailure,
                         sawRateLimit: loopState.sawRateLimit,
                         sawTransientFailure: loopState.sawTransientFailure,
                         sawNetworkError: loopState.sawNetworkError,
                     });
                     loopState.lastError = authRetryResult.lastError;
                     loopState.authFailureMessage = authRetryResult.authFailureMessage;
+                    loopState.entitlementFailure = authRetryResult.entitlementFailure;
                     loopState.sawRateLimit = authRetryResult.sawRateLimit;
                     loopState.sawTransientFailure = authRetryResult.sawTransientFailure;
                     loopState.sawNetworkError = authRetryResult.sawNetworkError;
@@ -5036,11 +5550,13 @@ async function handleAnthropicRoutedClaudeRequest(args) {
                         authFailureMessage: loopState.authFailureMessage,
                         sawTransientFailure: loopState.sawTransientFailure,
                         invalidRequestFailure: loopState.invalidRequestFailure,
+                        entitlementFailure: loopState.entitlementFailure,
                     });
                     loopState.lastError = nonOkResult.lastError;
                     loopState.authFailureMessage = nonOkResult.authFailureMessage;
                     loopState.sawTransientFailure = nonOkResult.sawTransientFailure;
                     loopState.invalidRequestFailure = nonOkResult.invalidRequestFailure;
+                    loopState.entitlementFailure = nonOkResult.entitlementFailure;
                     if (nonOkResult.response !== undefined) {
                         return nonOkResult.response;
                     }
@@ -5185,6 +5701,8 @@ async function handleAnthropicRoutedClaudeRequest(args) {
         authFailureMessage: loopState.authFailureMessage,
         authCooldownMessage: loopState.authCooldownMessage,
         invalidRequestFailure: loopState.invalidRequestFailure,
+        entitlementFailure: loopState.entitlementFailure,
+        scopedExhaustion: loopState.scopedExhaustion,
         sawNetworkError: loopState.sawNetworkError,
         sawTransientFailure: loopState.sawTransientFailure,
         sawRateLimit: loopState.sawRateLimit,
@@ -5268,7 +5786,9 @@ export function createClaudeProxyRoutes(modelRouter, basePath = "", accountStrat
                         quotaRoutingEnabled: isQuotaRoutingEnabled(),
                         sessionSoftLimit: getSessionSoftLimit(),
                         sessionResetToleranceMs: getSessionResetToleranceMs(),
+                        useOverage: "auto",
                     };
+                    setOveragePolicy(requestRouting.useOverage);
                     const requestModelRouter = requestRouting.modelRouter;
                     const body = ctx.body;
                     // 1. Validate
@@ -5436,9 +5956,12 @@ export function createClaudeProxyRoutes(modelRouter, basePath = "", accountStrat
                 method: "GET",
                 path: `${basePath}/limits`,
                 handler: async (ctx) => {
-                    const effectiveAllowlist = runtimeConfigProvider
-                        ? runtimeConfigProvider().accountAllowlist
-                        : accountAllowlist;
+                    const limitsRouting = runtimeConfigProvider?.();
+                    const effectiveAllowlist = limitsRouting?.accountAllowlist ?? accountAllowlist;
+                    // A refresh reconciles cooldowns from the fetched quota, so it makes
+                    // the same overage judgement the request path does and needs the same
+                    // operator policy in scope.
+                    setOveragePolicy(limitsRouting?.useOverage);
                     const snapshotOnly = ctx.query?.snapshot === "true" || ctx.query?.snapshot === "1";
                     const accountFilter = ctx.query?.account;
                     return withSpan({
@@ -5529,7 +6052,9 @@ async function disableAccountUntilReauth(account, state, reason) {
         logger.debug(`[proxy] failed to persist disabled state for ${account.label}: ${e instanceof Error ? e.message : String(e)}`);
     }
     state.permanentlyDisabled = true;
-    logger.always(`[proxy] account=${account.label} disabled until re-authentication. Run: neurolink auth login anthropic --method oauth`);
+    logger.always(reason === "entitlement_blocked"
+        ? `[proxy] account=${account.label} disabled: the organization blocks Claude Code OAuth. Ask an admin to re-enable it, then run: neurolink auth enable ${account.key}`
+        : `[proxy] account=${account.label} disabled until re-authentication. Run: neurolink auth login anthropic --method oauth`);
     return true;
 }
 async function coolAccountAfterTransientRefreshFailure(account, state) {
@@ -5667,11 +6192,13 @@ export function parseClaudeErrorBody(errBody) {
             parsed.type === "error" &&
             parsed.error &&
             typeof parsed.error === "object") {
+            const errorCode = parsed.error.details?.error_code;
             return {
                 errorType: typeof parsed.error.type === "string" ? parsed.error.type : undefined,
                 message: typeof parsed.error.message === "string"
                     ? parsed.error.message
                     : undefined,
+                ...(typeof errorCode === "string" ? { errorCode } : {}),
             };
         }
     }
@@ -5714,6 +6241,55 @@ export function isSubscriptionBetaRejection(status, errBody) {
         message.includes("subscription") &&
         message.includes("available"));
 }
+/**
+ * Organization/plan entitlement codes Anthropic reports in `error.details`.
+ * Membership here is what promotes a rejection from "rotate" to "remember".
+ */
+const ENTITLEMENT_ERROR_CODES = new Set([
+    "oauth_not_allowed_for_organization",
+    "oauth_not_allowed",
+    "organization_disabled",
+]);
+/**
+ * An entitlement rejection: Anthropic refuses THIS credential on organization
+ * or plan policy, e.g. `403 permission_error` /
+ * "OAuth authentication is currently not allowed for this organization."
+ *
+ * The taxonomy makes this safe to rotate on: `permission_error` is reserved for
+ * credential/organization permission, distinct from `invalid_request_error`
+ * (request shape) and `not_found_error`, both already terminal above. No
+ * `permission_error` is caused by the request body, so the identical request
+ * can succeed on a different account.
+ *
+ * Deliberately broad — rotation is cheap and reversible. Persisting the block
+ * is gated on the narrower {@link isDurableEntitlementBlock}.
+ */
+export function isAccountEntitlementError(status, errBody) {
+    if (status !== 401 && status !== 402 && status !== 403) {
+        return false;
+    }
+    const parsed = parseClaudeErrorBody(errBody);
+    if (parsed.errorType === "permission_error") {
+        return true;
+    }
+    return (parsed.errorCode !== undefined &&
+        ENTITLEMENT_ERROR_CODES.has(parsed.errorCode));
+}
+/**
+ * Whether an entitlement rejection is specific enough to disable the account
+ * until someone re-enables it. Narrower than {@link isAccountEntitlementError}
+ * because disabling is sticky and user-visible: an unrecognised
+ * `permission_error` should rotate through the pool and surface a 403, never
+ * durably remove a credential on a guess.
+ */
+export function isDurableEntitlementBlock(status, errBody) {
+    if (!isAccountEntitlementError(status, errBody)) {
+        return false;
+    }
+    const parsed = parseClaudeErrorBody(errBody);
+    return (parsed.errorCode !== undefined &&
+        ENTITLEMENT_ERROR_CODES.has(parsed.errorCode));
+}
 function normalizeClaudeRequestForAnthropic(body) {
     return {
         ...body,
@@ -5797,8 +6373,8 @@ export const __testHooks = {
     scheduleAdaptiveQuotaRefreshes,
     scheduleHandoffQuotaRefresh,
     getQuotaRefreshState: (key) => accountQuotaRefreshCoordinator.getState(key),
-    buildQuotaRoutingDecision: (accounts, now, primaryKey, sessionSoftLimit = getSessionSoftLimit(), sessionResetToleranceMs = getSessionResetToleranceMs()) => {
-        const order = orderAccountsByQuotaWithMetrics(accounts, now, primaryKey, sessionSoftLimit, sessionResetToleranceMs);
+    buildQuotaRoutingDecision: (accounts, now, primaryKey, sessionSoftLimit = getSessionSoftLimit(), sessionResetToleranceMs = getSessionResetToleranceMs(), requestedModel) => {
+        const order = orderAccountsByQuotaWithMetrics(accounts, now, primaryKey, sessionSoftLimit, sessionResetToleranceMs, requestedModel);
         return buildRoutingDecision({
             accounts,
             orderedAccounts: order.orderedAccounts,
@@ -5870,4 +6446,9 @@ export const __testHooks = {
     shouldAttemptClaudeFallback,
     executeClaudeFallbackWithRetry,
     buildClaudeAnthropicFailureResponse,
+    isAccountEntitlementError,
+    isDurableEntitlementBlock,
+    evaluateScopedExhaustion,
+    matchScopedQuotaWindow,
+    setOveragePolicy,
 };