@bitkyc08/opencodex 2.58.0 → 2.60.0

package/src/lib/workflow-budget.ts

@@ -21,11 +21,47 @@
 
 import {
   sharedSpendLedger,
+  spendCeilingsConfigured,
   type SpendReservationLedger,
   type SpendScope,
   type SpendUsage,
 } from "./spend-reservation-ledger";
 
+/**
+ * What a token-ceiling refusal has to be able to say.
+ *
+ * "Budget exhausted" on its own is the failure this repository keeps re-learning: a policy
+ * rejection wearing another error's clothing sends an operator to look at the provider. The
+ * scope says WHICH ceiling fired -- one task, one account, or the whole pool -- and the limit
+ * is the number they would otherwise have to read the journal to recover. The scope ID is
+ * deliberately not here: root ids are client thread headers and identity ids are credentials,
+ * and the ledger's rule is that neither is written down in the clear.
+ */
+export interface WorkflowSpendDenialDetail {
+  readonly scope: SpendScope;
+  readonly limit: number;
+  /** Tokens the refused reservation would have taken the scope to, where that is known. */
+  readonly projected?: number;
+}
+
+/** Operator-facing name for each scope. What an operator calls it, not what the type calls it. */
+const SPEND_SCOPE_LABEL: Record<SpendScope, string> = {
+  root: "task",
+  identity: "account",
+  pool: "provider pool",
+};
+
+/**
+ * Thousands separators, done here rather than by `toLocaleString`.
+ *
+ * A ceiling is an eight- or nine-digit number and an unseparated one is genuinely hard to read
+ * against the figure beside it. `toLocaleString` would do this too, but its output depends on
+ * the ICU data the runtime happens to carry, and a message a test pins must not differ between
+ * a developer's machine and a CI image.
+ */
+const formatTokenCount = (tokens: number): string =>
+  Math.trunc(tokens).toString().replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+
 export interface WorkflowBudgetPolicy {
   /** Children admitted concurrently under one root. */
   readonly maxConcurrentChildren: number;
@@ -172,7 +208,10 @@ export type WorkflowDenial =
  * therefore says which ceiling fired AND that no provider was contacted, because that is the
  * first thing an operator needs and the only place left to put it.
  */
-export function workflowDenialSummary(reason: WorkflowDenial): { code: string; message: string } {
+export function workflowDenialSummary(
+  reason: WorkflowDenial,
+  spend?: WorkflowSpendDenialDetail,
+): { code: string; message: string } {
   switch (reason) {
     case "workflow-sends-exhausted":
       return {
@@ -197,8 +236,21 @@ export function workflowDenialSummary(reason: WorkflowDenial): { code: string; m
     case "workflow-spend-exhausted":
       return {
         code: "workflow_spend_exhausted",
-        message: "This proxy refused the request locally: the task reached a configured token"
-          + " ceiling, so no provider was contacted.",
+        // With the denial in hand the sentence names the ceiling that fired and its number,
+        // because the alternative is an operator who can see that something refused and has
+        // no way to find out what. Without one -- a caller that knows only the reason -- the
+        // original sentence is kept unchanged.
+        message: spend
+          ? "This proxy refused the request locally: the configured " + SPEND_SCOPE_LABEL[spend.scope]
+            + " token ceiling of " + formatTokenCount(spend.limit) + " is spent"
+            + (spend.projected !== undefined
+              ? " (this send would have taken it to " + formatTokenCount(spend.projected) + ")"
+              : "")
+            + ", so no provider was contacted. Spend is durable, so it does not roll forward"
+            + " with the send window: raise or remove spend." + spend.scope
+            + ".maxTokens in config.json to grant more."
+          : "This proxy refused the request locally: the task reached a configured token"
+            + " ceiling, so no provider was contacted.",
       };
     case "workflow-tracking-exhausted":
       return {
@@ -241,6 +293,10 @@ export interface WorkflowBudgetEvent {
   readonly rootId: string;
   /** The ceiling that fired. Present for `refused`, absent for `cleared`. */
   readonly reason?: WorkflowDenial;
+  /** Which token scope refused, on a spend denial. Absent on every count denial. */
+  readonly spendScope?: SpendScope;
+  /** That scope's ceiling, so the event is readable without the config open beside it. */
+  readonly spendLimit?: number;
   /** Windowed sends at the moment of the event. */
   readonly sends: number;
   /** Windowed distinct children at the moment of the event. */
@@ -289,6 +345,7 @@ export function recordWorkflowRefusalEvent(
   rootId: string | undefined,
   reason: WorkflowDenial,
   now: number = Date.now(),
+  spend?: WorkflowSpendDenialDetail,
 ): void {
   if (!rootId) return;
   const state = roots.get(rootId);
@@ -297,6 +354,7 @@ export function recordWorkflowRefusalEvent(
     kind: "refused",
     rootId,
     reason,
+    ...(spend ? { spendScope: spend.scope, spendLimit: spend.limit } : {}),
     sends: state ? windowedSends(state, now) : 0,
     children: state ? windowedChildren(state, now) : 0,
   });
@@ -323,6 +381,10 @@ export type WorkflowDecision =
       rootId: string;
       /** Which spend scope refused, when the denial came from the token ledger. */
       spendScope?: SpendScope;
+      /** That scope's configured ceiling, so a caller can say what it was. */
+      spendLimit?: number;
+      /** Tokens the refused reservation would have taken the scope to, where known. */
+      spendProjected?: number;
     };
 
 /**
@@ -424,24 +486,40 @@ export function admitWorkflowTurn(
 ): WorkflowDecision | undefined {
   if (!rootId) return undefined;
   // An explicit ledger is consulted even without a spend request, so root eviction can
-  // still see spend-exhausted entries. With neither, no token tracking is in play.
-  const ledger = spendLedger ?? (spend ? sharedSpendLedger() : undefined);
+  // still see spend-exhausted entries. The shared one is resolved whenever a ceiling is
+  // CONFIGURED, which is what lets admission refuse an already-spent scope before a body is
+  // parsed. An install that configured nothing resolves no ledger, opens no journal, and runs
+  // this function exactly as it did before -- the unconfigured path has to stay byte-identical
+  // because the ledger is on and journalling by default.
+  const ledger = spendLedger ?? (spend || spendCeilingsConfigured() ? sharedSpendLedger() : undefined);
   let state = roots.get(rootId);
   // Every refusal below goes on the record through this one seam. Recording at each return
   // site instead of at the HTTP caller is what makes the record complete: the spend denials
   // are decided inside the ledger branch and never surface as a distinct reason to the caller
   // that formats the response.
-  const refuse = (reason: WorkflowDenial, spendScope?: SpendScope): WorkflowDecision => {
+  const refuse = (reason: WorkflowDenial, denial?: WorkflowSpendDenialDetail): WorkflowDecision => {
     const current = roots.get(rootId);
     recordBudgetEvent({
       at: now,
       kind: "refused",
       rootId,
       reason,
+      ...(denial ? { spendScope: denial.scope, spendLimit: denial.limit } : {}),
       sends: current ? windowedSends(current, now) : 0,
       children: current ? windowedChildren(current, now) : 0,
     });
-    return { admitted: false, reason, rootId, ...(spendScope ? { spendScope } : {}) };
+    return {
+      admitted: false,
+      reason,
+      rootId,
+      ...(denial
+        ? {
+          spendScope: denial.scope,
+          spendLimit: denial.limit,
+          ...(denial.projected !== undefined ? { spendProjected: denial.projected } : {}),
+        }
+        : {}),
+    };
   };
   if (!state) {
     if (roots.size >= policy.maxTrackedRoots && !evictOneRoot(policy, ledger, now)) {
@@ -469,6 +547,26 @@ export function admitWorkflowTurn(
     return refuse("workflow-concurrency-exhausted");
   }
 
+  // The counts are checked first and the token ceiling second, and the order is deliberate
+  // rather than emergent. A count check reads two integers this process already holds; a token
+  // check may have to build the ledger and replay its journal. Checking the cheap bound first
+  // means the expensive one is never reached for a request the cheap one already refused.
+  //
+  // The two therefore CAN disagree, and the intersection is what is enforced: a request passes
+  // only when every count cap and every token ceiling admits it. A token denial happens before
+  // any count is charged, and a count denial happens before any reservation is booked, so
+  // neither leaves the other's accounting to unwind. Whichever refuses first is reported as
+  // itself -- one refusal is never relabelled as the other, because "sends exhausted" and
+  // "spend exhausted" send an operator to two different remedies.
+  //
+  // A scope whose ceiling is ALREADY spent is refused here rather than at the reservation. The
+  // reservation needs a token count, which is not known until the body is parsed and a route
+  // resolved; an exhausted scope needs neither and is the cheapest refusal available.
+  if (!spend && ledger) {
+    const reached = spentRootCeiling(rootId, ledger);
+    if (reached) return refuse("workflow-spend-exhausted", reached);
+  }
+
   if (spend && ledger) {
     const decision = ledger.reserve({
       sendId: spend.sendId,
@@ -491,7 +589,9 @@ export function admitWorkflowTurn(
             : "workflow-spend-exhausted";
       return refuse(
         reason,
-        denial.reason === "spend-limit-exceeded" ? denial.scope : undefined,
+        denial.reason === "spend-limit-exceeded"
+          ? { scope: denial.scope, limit: denial.limit, projected: denial.projected }
+          : undefined,
       );
     }
   }
@@ -600,6 +700,43 @@ export function workflowSendCeilingReached(
   return state !== undefined && windowedSends(state, now) >= policy.maxPhysicalSends;
 }
 
+/**
+ * The root scope's ceiling when that scope is already spent, or undefined.
+ *
+ * Root only: identity and pool are not known until routing has picked an account, so those two
+ * refuse at the reservation itself. `exhausted` sums settled spend, open reservations and
+ * unresolved spend, which is the same total the reservation compares, so this answers the same
+ * question the reservation would -- just without needing the request's token count.
+ */
+function spentRootCeiling(
+  rootId: string,
+  ledger: SpendReservationLedger,
+): WorkflowSpendDenialDetail | undefined {
+  const limit = ledger.policy.root.maxTokens;
+  if (limit === undefined) return undefined;
+  return ledger.exhausted("root", rootId) ? { scope: "root", limit } : undefined;
+}
+
+/**
+ * The token ceiling a root has already spent, or undefined when it has room or has none.
+ *
+ * The count-side twin of {@link workflowSendCeilingReached}, and the responses path calls both
+ * at the same seam for the same reason: a refusal decided before dispatch can be reported as
+ * ITSELF -- a named ceiling, a synthetic log row, a machine-readable header -- instead of
+ * surfacing later as a generic send-budget error from whichever leg happened to run out first.
+ *
+ * Returns undefined when no ceiling is configured, without resolving a ledger, so an install
+ * that never opted in neither pays for this check nor opens a journal because of it.
+ */
+export function workflowSpendCeilingReached(
+  rootId: string | undefined,
+  spendLedger?: SpendReservationLedger,
+): WorkflowSpendDenialDetail | undefined {
+  if (!rootId) return undefined;
+  const ledger = spendLedger ?? (spendCeilingsConfigured() ? sharedSpendLedger() : undefined);
+  return ledger ? spentRootCeiling(rootId, ledger) : undefined;
+}
+
 export interface WorkflowBudgetSnapshot {
   active: number;
   /** Sends inside the window. This is the number the ceiling compares. */

package/src/oauth/account-quota-rank.ts

@@ -13,6 +13,38 @@
 import { getCachedProviderAccountQuota, hasPassiveAccountQuota } from "../providers/quota";
 import { getKiroAccountExhaustion } from "../providers/kiro-usage";
 
+/** Antigravity hosts Gemini and Claude windows on one account; ranking must not mix them. */
+export type QuotaModelFamily = "gem" | "cla";
+
+export function classifyModelFamilyForQuota(
+  provider: string,
+  modelId?: string | null,
+): QuotaModelFamily | undefined {
+  if (provider !== "google-antigravity" || typeof modelId !== "string" || !modelId.trim()) {
+    return undefined;
+  }
+  const id = modelId.toLowerCase();
+  // Gemma is not Gemini: a substring/prefix match would poison Gemini ranking.
+  if (/(?:^|[^a-z])gemma(?:[^a-z]|$)/.test(id)) return undefined;
+  // Catalog ids are gemini-*, never a bare gem- token. Window labels still match Gem via
+  // windowMatchesFamily; this classifier is only for request model ids.
+  if (/(?:^|[^a-z])gemini(?:[^a-z]|$)/.test(id)) return "gem";
+  if (
+    /(?:^|[^a-z])claude(?:[^a-z]|$)/.test(id)
+    || /(?:^|[^a-z])opus(?:[^a-z]|$)/.test(id)
+    || /(?:^|[^a-z])sonnet(?:[^a-z]|$)/.test(id)
+    || /(?:^|[^a-z])haiku(?:[^a-z]|$)/.test(id)
+    || /(?:^|[^a-z])gpt[-_]oss(?:[^a-z]|$)/.test(id)
+  ) return "cla";
+  return undefined;
+}
+
+function windowMatchesFamily(label: string, family: QuotaModelFamily): boolean {
+  const token = label.trim().split(/[\s(/]+/)[0] ?? "";
+  if (family === "gem") return /^gem(?:ini)?$/i.test(token);
+  return /^cla(?:ude)?$/i.test(token);
+}
+
 /** Lower sorts earlier. Unknown sits between measured-healthy and measured-empty. */
 const RANK_HEALTHY = 0;
 const RANK_UNKNOWN = 1;
@@ -48,15 +80,24 @@ const PASSIVE_HEADROOM_MAX_AGE_MS = 60 * 60_000;
 /**
  * Remaining headroom across every window the provider reports.
  *
- * The minimum wins: an account at 5% of its five-hour window is unusable right now even if
- * its monthly allowance is barely touched.
- */
-function headroomOf(provider: string, accountId: string): number | null {
+* The minimum wins: an account at 5% of its five-hour window is unusable right now even if
+* its monthly allowance is barely touched.
+*/
+function headroomOf(provider: string, accountId: string, requestedModelId?: string | null): number | null {
   const quota = getCachedProviderAccountQuota(provider, accountId);
   if (!quota) return null;
   // Null, not a low rank: this must reproduce "no evidence" so a stale roster degrades to
   // the unranked ring rather than to a differently wrong answer.
   if (hasPassiveAccountQuota(provider) && Date.now() - quota.updatedAt > PASSIVE_HEADROOM_MAX_AGE_MS) return null;
+  const family = classifyModelFamilyForQuota(provider, requestedModelId);
+  if (family) {
+    const percents = (quota.customWindows ?? [])
+      .filter(window => windowMatchesFamily(window.label, family))
+      .map(window => window.percent)
+      .filter((value): value is number => typeof value === "number");
+    if (percents.length === 0) return null;
+    return 100 - Math.max(...percents);
+  }
   const percents = [
     quota.fiveHourPercent,
     quota.weeklyPercent,
@@ -74,15 +115,23 @@ function headroomOf(provider: string, accountId: string): number | null {
  * than an ordering. Null stays null all the way out: a caller must decide what "unmeasured"
  * means for its own rule instead of being handed a fabricated 0 or 100.
  */
-export function accountHeadroomPercent(provider: string, accountId: string): number | null {
-  return headroomOf(provider, accountId);
+export function accountHeadroomPercent(
+  provider: string,
+  accountId: string,
+  requestedModelId?: string | null,
+): number | null {
+  return headroomOf(provider, accountId, requestedModelId);
 }
 
 /** Unknown usage is not exhaustion; Kiro's explicit overage verdict is authoritative. */
-export function isAccountQuotaExhausted(provider: string, accountId: string): boolean {
+export function isAccountQuotaExhausted(
+  provider: string,
+  accountId: string,
+  requestedModelId?: string | null,
+): boolean {
   const exhaustion = provider === "kiro" ? getKiroAccountExhaustion(`${provider}\u0000${accountId}`) : null;
   if (exhaustion !== null) return exhaustion.exhausted;
-  const headroom = headroomOf(provider, accountId);
+  const headroom = headroomOf(provider, accountId, requestedModelId);
   return headroom !== null && headroom <= 0;
 }
 
@@ -92,24 +141,28 @@ export function isAccountQuotaExhausted(provider: string, accountId: string): bo
  * Returns the input untouched when no candidate has quota evidence, which keeps every
  * provider without per-account quota on exactly the behaviour it has today.
  */
-export function rankAccountsByHeadroom(provider: string, ring: readonly string[]): string[] {
+export function rankAccountsByHeadroom(
+  provider: string,
+  ring: readonly string[],
+  requestedModelId?: string | null,
+): string[] {
   if (ring.length < 2) return [...ring];
 
   let sawEvidence = false;
   // Same rule as hasHeadroomEvidence: a passive provider's partial roster must not rank
   // at all. The failover path calls this directly (selectFailoverAccount), so the guard
   // cannot live only in the pre-dispatch predicate.
-  if (hasPassiveAccountQuota(provider) && !ring.every(id => headroomOf(provider, id) !== null)) {
+  if (hasPassiveAccountQuota(provider) && !ring.every(id => headroomOf(provider, id, requestedModelId) !== null)) {
     return [...ring];
   }
   const ranked: Ranked[] = ring.map((id, index) => {
     // A provider-declared exhaustion verdict outranks the percentage: an account may sit at
     // 100% and still be servable when overage is enabled, and the verdict knows that.
     const exhaustion = provider === "kiro" ? getKiroAccountExhaustion(`${provider}\u0000${id}`) : null;
-    const headroom = headroomOf(provider, id);
+    const headroom = headroomOf(provider, id, requestedModelId);
     if (exhaustion !== null || headroom !== null) sawEvidence = true;
 
-    if (isAccountQuotaExhausted(provider, id)) return { id, bucket: RANK_EXHAUSTED, headroom: 0, index };
+    if (isAccountQuotaExhausted(provider, id, requestedModelId)) return { id, bucket: RANK_EXHAUSTED, headroom: 0, index };
     if (headroom === null) return { id, bucket: RANK_UNKNOWN, headroom: 0, index };
     return { id, bucket: RANK_HEALTHY, headroom, index };
   });
@@ -129,7 +182,11 @@ export function rankAccountsByHeadroom(provider: string, ring: readonly string[]
  * told "ranked" when nothing was measured. Pre-dispatch selection asks this first so it
  * can decline to act on a roster it knows nothing about.
  */
-export function hasHeadroomEvidence(provider: string, ids: readonly string[]): boolean {
+export function hasHeadroomEvidence(
+  provider: string,
+  ids: readonly string[],
+  requestedModelId?: string | null,
+): boolean {
   // A PASSIVE provider needs evidence for EVERY candidate, not any one of them.
   //
   // A probe fills the whole roster in one pass (fetchProviderAccountQuotas), so "any"
@@ -140,10 +197,10 @@ export function hasHeadroomEvidence(provider: string, ids: readonly string[]): b
   // AWAY from an unmeasured account and TOWARD the one account known to be spent, which
   // is the exact inversion of what ranking is for.
   if (hasPassiveAccountQuota(provider)) {
-    return ids.length > 0 && ids.every(id => headroomOf(provider, id) !== null);
+    return ids.length > 0 && ids.every(id => headroomOf(provider, id, requestedModelId) !== null);
   }
   return ids.some(id =>
-    headroomOf(provider, id) !== null
+    headroomOf(provider, id, requestedModelId) !== null
     || (provider === "kiro" && getKiroAccountExhaustion(`${provider}\u0000${id}`) !== null));
 }
 /**

package/src/oauth/callback-server.ts

@@ -252,9 +252,10 @@ export abstract class OAuthCallbackFlow {
                 if (!parsed.code) return null;
                 // Kind-aware state enforcement: url/query-shaped input is an authorization
                 // RESPONSE and must carry a matching state — missing state is rejected, not
-                // downgraded to raw. Only a syntactically raw code (same PKCE session) is
-                // exempt, so the CLI/GUI paste fallback still works.
-                if (parsed.kind !== "raw" && expectedState && parsed.state !== expectedState) return null;
+                // downgraded to raw. A raw paste with an explicit code#state suffix is
+                // state-bearing too. Only a syntactically raw code WITHOUT a state suffix
+                // (same PKCE session) is exempt, so the CLI/GUI paste fallback still works.
+                if ((parsed.kind !== "raw" || parsed.state !== undefined) && expectedState && parsed.state !== expectedState) return null;
                 return { code: parsed.code, state: parsed.state ?? expectedState };
               })
               .catch((): CallbackResult | null => null),

package/src/oauth/generic-account-failover.ts

@@ -22,6 +22,8 @@ import {
   hasHeadroomEvidence,
   isAccountQuotaExhausted,
   rankAccountsByHeadroom,
+  classifyModelFamilyForQuota,
+  type QuotaModelFamily,
 } from "./account-quota-rank";
 import {
   genericPoolKey,
@@ -81,13 +83,14 @@ const health = new Map<string, AccountHealth>();
 /** Provider -> recent eligible-account count. TTL-bounded; never holds credential material. */
 const presence = new Map<string, PresenceEntry>();
 
-const healthKey = (provider: string, accountId: string) => `${provider}\u0000${accountId}`;
+const healthKey = (provider: string, accountId: string, family?: QuotaModelFamily) =>
+  family ? `${provider}\u0000${accountId}\u0000${family}` : `${provider}\u0000${accountId}`;
 
-function isCooled(provider: string, accountId: string, now: number): boolean {
-  const entry = health.get(healthKey(provider, accountId));
+function isCooled(provider: string, accountId: string, now: number, family?: QuotaModelFamily): boolean {
+  const entry = health.get(healthKey(provider, accountId, family));
   if (!entry) return false;
   if (entry.cooldownUntil <= now) {
-    health.delete(healthKey(provider, accountId));
+    health.delete(healthKey(provider, accountId, family));
     return false;
   }
   return true;
@@ -175,11 +178,11 @@ function isProactivePreferenceEnabled(config: OcxConfig, providerName: string, n
 }
 
 /** Accounts that may serve traffic right now: not cooled, not flagged for reauth. */
-export function eligibleFailoverAccounts(providerName: string, now = Date.now()): string[] {
+export function eligibleFailoverAccounts(providerName: string, now = Date.now(), family?: QuotaModelFamily): string[] {
   const set = getAccountSet(providerName);
   if (!set) return [];
   return set.accounts
-    .filter(account => account.needsReauth !== true && !isCooled(providerName, account.id, now))
+    .filter(account => account.needsReauth !== true && !isCooled(providerName, account.id, now, family))
     .map(account => account.id);
 }
 
@@ -230,8 +233,9 @@ function stableGenericRoster(providerName: string): string[] {
  * statement about observed usage, and treating "no observation" as "spent" would evacuate every
  * quota-less provider off its active account on the very first request.
  */
-function isOverAutoSwitchThreshold(providerName: string, accountId: string, threshold: number): boolean {
-  const headroom = accountHeadroomPercent(providerName, accountId);
+function isOverAutoSwitchThreshold(providerName: string, accountId: string, threshold: number, requestedModelId?: string | null): boolean {
+  if (threshold <= 0) return false;
+  const headroom = accountHeadroomPercent(providerName, accountId, requestedModelId);
   if (headroom === null) return false;
   return 100 - headroom >= threshold;
 }
@@ -245,15 +249,17 @@ function pickFillFirstGenericAccount(
   providerName: string,
   activeId: string | undefined,
   now: number,
+  requestedModelId?: string | null,
 ): string | null {
   const stableAll = stableGenericRoster(providerName);
   if (stableAll.length < 2) return null;
-  const eligible = new Set(eligibleFailoverAccounts(providerName, now));
+  const family = classifyModelFamilyForQuota(providerName, requestedModelId);
+  const eligible = new Set(eligibleFailoverAccounts(providerName, now, family));
   const stored = config.providers?.[providerName]?.oauthAccountFailover?.autoSwitchThreshold;
   const threshold = typeof stored === "number" && Number.isInteger(stored) && stored >= 0 && stored <= 100
     ? stored
     : DEFAULT_GENERIC_AUTO_SWITCH_THRESHOLD;
-  if (activeId && eligible.has(activeId) && !isOverAutoSwitchThreshold(providerName, activeId, threshold)) {
+  if (activeId && eligible.has(activeId) && !isOverAutoSwitchThreshold(providerName, activeId, threshold, requestedModelId)) {
     return null;
   }
   const start = activeId ? stableAll.indexOf(activeId) : -1;
@@ -277,11 +283,17 @@ function pickFillFirstGenericAccount(
  * advance and round-robin would propose the same account forever. This is the same shape
  * `commitAnthropicSelectionRouting` already commits with.
  */
-export function noteGenericPoolSelection(config: OcxConfig, providerName: string, accountId: string): void {
+export function noteGenericPoolSelection(
+  config: OcxConfig,
+  providerName: string,
+  accountId: string,
+  requestedModelId?: string | null,
+): void {
   if (activeGenericStrategy(config, providerName) !== "round-robin") return;
   const poolKey = genericPoolKey(providerName);
   const limit = genericStickyLimit(config, providerName);
-  const picked = pickRoundRobinAccount(poolKey, eligibleFailoverAccounts(providerName), limit);
+  const family = classifyModelFamilyForQuota(providerName, requestedModelId);
+  const picked = pickRoundRobinAccount(poolKey, eligibleFailoverAccounts(providerName, Date.now(), family), limit);
   // The resolver may have admitted a different account than the ring proposed: a removal, a
   // reauth verdict or a manual selection can land during credential resolution. Realign the
   // cursor onto what actually served rather than leaving it on a road not taken.
@@ -302,6 +314,7 @@ export function rotateGenericOAuthAccountOn429(
   failedAccountId: string,
   retryAfterHeader: string | null | undefined,
   now = Date.now(),
+  requestedModelId?: string | null,
 ): string | null {
   if (!isGenericOAuthFailoverEnabled(config, providerName)) return null;
   const set = getAccountSet(providerName);
@@ -314,13 +327,14 @@ export function rotateGenericOAuthAccountOn429(
   // A Retry-After from upstream still wins — it is the server's own instruction.
   const exhausted = parsed === undefined ? exhaustedCooldownMs(providerName, failedAccountId, now) : null;
   const cooldownMs = exhausted ?? Math.min(parsed ?? DEFAULT_COOLDOWN_MS, MAX_COOLDOWN_MS);
-  health.set(healthKey(providerName, failedAccountId), {
+  const family = classifyModelFamilyForQuota(providerName, requestedModelId);
+  health.set(healthKey(providerName, failedAccountId, family), {
     cooldownUntil: now + cooldownMs,
     cooldownSource: parsed ? "retry-after" : "default",
   });
   sweepExpiredOnWrite(now);
 
-  const eligible = eligibleFailoverAccounts(providerName, now).filter(id => id !== failedAccountId);
+  const eligible = eligibleFailoverAccounts(providerName, now, family).filter(id => id !== failedAccountId);
   if (eligible.length === 0) return null;
   // A rotation means the roster in use just changed; do not answer the next activation question
   // from a count read before the failure.
@@ -359,7 +373,7 @@ export function rotateGenericOAuthAccountOn429(
   }
   // With no quota evidence this returns the ring untouched, so providers without
   // per-account quota keep exactly the traversal they have today.
-  return rankAccountsByHeadroom(providerName, candidates)[0] ?? null;
+  return rankAccountsByHeadroom(providerName, candidates, requestedModelId)[0] ?? null;
 }
 
 /**
@@ -392,6 +406,7 @@ export function preferredInitialAccount(
   config: OcxConfig,
   providerName: string,
   now = Date.now(),
+  requestedModelId?: string | null,
 ): string | null {
   // The PROACTIVE predicate, not the reactive one: this steers a request upstream has not
   // refused, so `oauthAccountFailover.enabled: false` must still be able to refuse it.
@@ -411,7 +426,8 @@ export function preferredInitialAccount(
   // would never reach its own test. Cooldowns and reauth are still honoured inside each pick.
   const strategy = activeGenericStrategy(config, providerName);
   if (strategy === "round-robin") {
-    const eligibleNow = eligibleFailoverAccounts(providerName, now);
+    const family = classifyModelFamilyForQuota(providerName, requestedModelId);
+    const eligibleNow = eligibleFailoverAccounts(providerName, now, family);
     if (eligibleNow.length === 0) return null;
     // PEEK, not pick: this proposal is discardable, and advancing the ring for an account the
     // resolver then rejects would skip a turn for nothing. noteGenericPoolSelection commits.
@@ -423,26 +439,26 @@ export function preferredInitialAccount(
     return picked && picked !== active ? picked : null;
   }
   if (strategy === "fill-first") {
-    const picked = pickFillFirstGenericAccount(config, providerName, active, now);
+    const picked = pickFillFirstGenericAccount(config, providerName, active, now, requestedModelId);
     return picked && picked !== active ? picked : null;
   }
 
   const activeRow = selected.accounts.find(account => account.id === active);
   if (activeRow && activeRow.needsReauth !== true
-    && !isCooled(providerName, activeRow.id, now)
-    && !isAccountQuotaExhausted(providerName, activeRow.id)) return null;
+    && !isCooled(providerName, activeRow.id, now, classifyModelFamilyForQuota(providerName, requestedModelId))
+    && !isAccountQuotaExhausted(providerName, activeRow.id, requestedModelId)) return null;
 
   // Evidence is required BEFORE eligibility narrows the field. Without this, a provider
   // with no quota data at all could still be redirected: cool the active account with a
   // 429 and the eligible list collapses to one candidate, which any ranking returns
   // unchanged — an answer that looks ranked but was never measured. The no-op guarantee
   // for quota-less providers has to be checked on the full roster.
-  if (!hasHeadroomEvidence(providerName, order)) return null;
+  if (!hasHeadroomEvidence(providerName, order, requestedModelId)) return null;
 
   // Cooldowns are respected here, unlike in the presence count: this picks the account to
   // send to right now, and one inside its 429 window is the single candidate we hold
   // positive evidence against.
-  const eligible = order.filter(id => !isCooled(providerName, id, now));
+  const eligible = order.filter(id => !isCooled(providerName, id, now, classifyModelFamilyForQuota(providerName, requestedModelId)));
   if (eligible.length === 0) return null;
 
   // Start the ring at the active account so an unranked outcome reproduces today's choice.
@@ -451,7 +467,7 @@ export function preferredInitialAccount(
   const candidates = ring.filter(id => eligible.includes(id));
   if (candidates.length === 0) return null;
 
-  const best = rankAccountsByHeadroom(providerName, candidates)[0] ?? null;
+  const best = rankAccountsByHeadroom(providerName, candidates, requestedModelId)[0] ?? null;
   // Nothing to do when the ranking agrees with the account we would have used anyway.
   //
   // A proposal still needs guarded selection commit after credential resolution: a
@@ -461,12 +477,10 @@ export function preferredInitialAccount(
 
 /** Earliest remaining cooldown, for a client-facing Retry-After when every account is cooled. */
 export function genericFailoverRetryAfterSeconds(providerName: string, now = Date.now()): number | null {
-  const set = getAccountSet(providerName);
-  if (!set) return null;
+  const prefix = `${providerName}\u0000`;
   let earliest: number | null = null;
-  for (const account of set.accounts) {
-    const entry = health.get(healthKey(providerName, account.id));
-    if (!entry || entry.cooldownUntil <= now) continue;
+  for (const [key, entry] of health) {
+    if (!key.startsWith(prefix) || entry.cooldownUntil <= now) continue;
     if (earliest === null || entry.cooldownUntil < earliest) earliest = entry.cooldownUntil;
   }
   return earliest === null ? null : Math.max(1, Math.ceil((earliest - now) / 1000));

package/src/oauth/health.ts

@@ -202,6 +202,7 @@ export function projectStoredOAuthAccountHealth(
 export function projectCodexAccountHealth(input: {
   accountId: string;
   needsReauth: boolean;
+  reauthReason?: "unauthorized" | "forbidden" | "refresh_failed";
   now?: number;
 }): OAuthAccountHealth {
   // One read serves every verdict below. Each lookup re-reads and re-hardens the whole store
@@ -230,6 +231,16 @@ export function projectCodexAccountHealth(input: {
 
   const needsReauth = input.needsReauth || validationAuthFailed || terminalGrantFailure;
 
+  // A stored verification failure carries its own cause. When the caller did not name a
+  // reason, surface the persisted one instead of flattening every verdict into
+  // `refresh_failed`.
+  const storedVerificationFailed = validationAuthFailed || terminalGrantFailure;
+  const storedFailureReason: "unauthorized" | "forbidden" | undefined = !storedVerificationFailed
+    ? undefined
+    : record?.lastCodexValidationError === "http_status:403" ? "forbidden"
+      : record?.lastCodexValidationError === "http_status:401" ? "unauthorized"
+      : undefined;
+
   // Deferred validation is only worth reporting while the credential itself is still viable. A
   // revoked grant needs a re-login, not a "Refresh quotas" click, so reauth is resolved first.
   if (!needsReauth && record?.codexValidationPending) {
@@ -239,7 +250,7 @@ export function projectCodexAccountHealth(input: {
   const snap = getCodexAccountHealthSnapshot(input.accountId, now);
   return projectOAuthAccountHealth({
     needsReauth,
-    reauthReason: needsReauth ? "refresh_failed" : undefined,
+    reauthReason: needsReauth ? (input.reauthReason ?? storedFailureReason ?? "refresh_failed") : undefined,
     cooldownUntilMs: snap?.cooldownUntil,
     cooldownReason: cooldownReasonFromSource(snap?.cooldownSource),
     now,