@bitkyc08/opencodex 2.58.0 → 2.59.0

package/src/lib/spend-reservation-ledger.ts

@@ -60,6 +60,9 @@ import { dirname, join } from "node:path";
 // Definition-site import, not the ../config barrel -- same reasoning as
 // src/quota/reset-seen-store.ts: the barrel pulls ~154 modules into a hot path.
 import { getConfigDir } from "../config/paths";
+// Type-only, so it is erased before this module has a runtime import graph at all. The
+// config SHAPE is what this file needs; the config loader is what the note above keeps out.
+import type { OcxSpendConfig, OcxSpendScopeConfig } from "../types/config";
 import { assertNotRealHomeUnderTest } from "./test-home-guard";
 // Windows chmod does not remove inherited ACEs; this is the repository's icacls path.
 import { hardenSecretPath } from "./windows-secret-acl";
@@ -147,6 +150,24 @@ export interface SpendReservationRequest {
   /** Enforceable output ceiling -- max_output_tokens or the model's documented cap. */
   readonly outputCeilingTokens: number;
   readonly at?: number;
+  /**
+   * This send has ALREADY left for upstream and is being recorded rather than admitted.
+   *
+   * Some transports report their physical sends after the fact -- the passthrough ladder
+   * reports through `onSendsConsumed`, and an adapter's inner retries are counted when they
+   * finish. For those, a ceiling cannot refuse anything: the tokens are spent. Refusing to
+   * BOOK them is the worse answer, and it is not hypothetical -- it is a fixpoint. The send
+   * that would cross the ceiling gets dropped from the total, the total stays just under the
+   * limit forever, the scope never reads as exhausted, and the ceiling never fires again for
+   * any request. So a recorded send skips the limit check and takes the scope over its
+   * ceiling, which is what makes the NEXT request refusable.
+   *
+   * It skips the durability refusal for the same reason: a journal that could not be written
+   * is a reason to report degradation, never a reason to forget spend that really happened.
+   * Identity, capacity and journal-integrity denials still apply -- those say the ledger
+   * cannot account for the send at all, which no flag here can change.
+   */
+  readonly alreadySent?: boolean;
 }
 
 /**
@@ -468,6 +489,20 @@ export interface SpendReservationLedger {
   prune(now?: number): void;
   /** Whether this send id is already known, and therefore refused. */
   knows(sendId: string): boolean;
+  /**
+   * Replace the live policy.
+   *
+   * Every figure already accounted survives: raising, lowering or clearing a ceiling changes
+   * what is REFUSED from here on and never what was spent. Rebuilding the ledger instead
+   * would replay the journal into a second set of maps while the first still holds this
+   * process's open reservations, and the two would then disagree about what is in flight.
+   */
+  reconfigure(next: SpendReservationPolicy): void;
+  /**
+   * The policy in force. A live read, not a copy: a caller that formats a refusal has to name
+   * the ceiling this ledger would enforce on the NEXT request, not the one it was built with.
+   */
+  readonly policy: SpendReservationPolicy;
   /** Journal writes that failed; a nonzero count means durability is degraded. */
   readonly persistFailures: number;
   /**
@@ -495,13 +530,17 @@ export function createSpendReservationLedger(options: {
    */
   readonly salt?: string;
 } = {}): SpendReservationLedger {
-  const policy = options.policy ?? DEFAULT_SPEND_RESERVATION_POLICY;
+  // Mutable because the ceilings are operator configuration, and configuration is reloadable.
+  // The three bounds below are read through functions for the same reason: a value captured
+  // at construction would answer for the policy this ledger was BUILT with, and an operator
+  // who raised a bound would keep the old one until the process restarted.
+  let policy = options.policy ?? DEFAULT_SPEND_RESERVATION_POLICY;
   const journal = options.journal;
   const now = options.now ?? (() => Date.now());
   const salt = options.salt ?? "";
-  const maxTrackedScopes = policy.maxTrackedScopes ?? DEFAULT_MAX_TRACKED_SCOPES;
-  const maxTrackedSends = policy.maxTrackedSends ?? DEFAULT_MAX_TRACKED_SENDS;
-  const compactAfterRecords = policy.compactAfterRecords ?? DEFAULT_COMPACT_AFTER_RECORDS;
+  const maxTrackedScopes = (): number => policy.maxTrackedScopes ?? DEFAULT_MAX_TRACKED_SCOPES;
+  const maxTrackedSends = (): number => policy.maxTrackedSends ?? DEFAULT_MAX_TRACKED_SENDS;
+  const compactAfterRecords = (): number => policy.compactAfterRecords ?? DEFAULT_COMPACT_AFTER_RECORDS;
   const scopes = new Map<string, ScopeState>();
   const reservations = new Map<string, Reservation>();
   let persistFailures = 0;
@@ -753,7 +792,7 @@ export function createSpendReservationLedger(options: {
    */
   const compact = (at: number): void => {
     const rewrite = journal?.rewrite;
-    if (!journal || !rewrite || recordsOnDisk < compactAfterRecords) return;
+    if (!journal || !rewrite || recordsOnDisk < compactAfterRecords()) return;
     const checkpoint: JournalRecord = {
       v: 1,
       kind: "checkpoint",
@@ -791,12 +830,12 @@ export function createSpendReservationLedger(options: {
   const makeRoom = (refs: readonly ScopeRef[], at: number): SpendDenial | undefined => {
     evictSends(at, false);
     evictScopes(at, false);
-    while (reservations.size >= maxTrackedSends) {
+    while (reservations.size >= maxTrackedSends()) {
       if (evictSends(at, true) === 0) return { reason: "tracking-capacity-exhausted" };
     }
     let fresh = 0;
     for (const ref of refs) if (!scopes.has(scopeKey(ref.scope, ref.alias))) fresh += 1;
-    while (scopes.size + fresh > maxTrackedScopes) {
+    while (scopes.size + fresh > maxTrackedScopes()) {
       if (evictScopes(at, true) === 0) {
         return { reason: "tracking-capacity-exhausted", scope: refs[0]?.scope };
       }
@@ -808,6 +847,7 @@ export function createSpendReservationLedger(options: {
     get persistFailures() { return persistFailures; },
     get corruptRecords() { return corruptRecords; },
     get degraded() { return persistFailures > 0 || corruptRecords > 0; },
+    get policy() { return policy; },
 
     reserve(request: SpendReservationRequest): SpendReservationDecision {
       const tokens = sanitizeTokens(request.inputTokens) + sanitizeTokens(request.outputCeilingTokens);
@@ -834,7 +874,9 @@ export function createSpendReservationLedger(options: {
       // reservation booked on the scopes that would have passed. Reading state without
       // creating it matters here -- a denied request must not leave a tracked scope behind.
       for (const ref of refs) {
-        const limit = limitFor(ref.scope);
+        // A recorded send has no limit to fail: it already happened, and the point of booking
+        // it is to let the total go OVER the ceiling so the next request can be refused.
+        const limit = request.alreadySent === true ? undefined : limitFor(ref.scope);
         if (limit === undefined) continue;
         const state = scopes.get(scopeKey(ref.scope, ref.alias));
         const projected = (state ? state.settled + state.reserved + state.unresolved : 0) + tokens;
@@ -853,7 +895,7 @@ export function createSpendReservationLedger(options: {
       // limit a failed write refuses the request rather than admitting one that a restart
       // would forget -- which is exactly the disk-full and permission case durability is for.
       const durable = append({ v: 1, kind: "reserve", send, targets: refs, tokens, at });
-      if (!durable && enforced) {
+      if (!durable && enforced && request.alreadySent !== true) {
         return { reserved: false, denial: { reason: "reserve-not-durable", sendId: request.sendId } };
       }
       applyReserve(send, refs, tokens, at);
@@ -931,10 +973,72 @@ export function createSpendReservationLedger(options: {
       evictSends(at, false);
       evictScopes(at, false);
     },
+
+    reconfigure(next: SpendReservationPolicy): void {
+      policy = next;
+    },
   };
 }
 
 let sharedLedger: SpendReservationLedger | undefined;
+/**
+ * The operator policy in effect. Held beside the ledger rather than inside it because the
+ * ledger is built lazily: a configured ceiling has to be remembered from startup until the
+ * first request that actually reserves, and an install that configures nothing must still
+ * open no journal.
+ */
+let sharedPolicy: SpendReservationPolicy = DEFAULT_SPEND_RESERVATION_POLICY;
+
+/** Whether any scope carries a ceiling -- that is, whether anything at all can be refused. */
+export function spendCeilingsConfigured(policy: SpendReservationPolicy = sharedPolicy): boolean {
+  return policy.root.maxTokens !== undefined
+    || policy.identity.maxTokens !== undefined
+    || policy.pool.maxTokens !== undefined;
+}
+
+/** The policy the process-wide ledger enforces right now. */
+export function sharedSpendPolicy(): SpendReservationPolicy {
+  return sharedPolicy;
+}
+
+const spendScopeLimitFromConfig = (scope: OcxSpendScopeConfig | undefined): SpendScopeLimit =>
+  scope?.maxTokens !== undefined && Number.isFinite(scope.maxTokens) && scope.maxTokens > 0
+    ? { maxTokens: Math.trunc(scope.maxTokens) }
+    : {};
+
+/**
+ * The ledger policy an operator's `spend` section asks for.
+ *
+ * An absent section, an empty one, and one whose every ceiling is absent all produce the
+ * unconfigured default: observe-only accounting that refuses nothing. That equivalence is the
+ * load-bearing part. This ledger is on and journaling by default, so shipping a default
+ * ceiling would start refusing real traffic on the first upgrade that ran this code, against
+ * a number nobody chose. There is deliberately no default figure here at all.
+ */
+export function spendPolicyFromConfig(spend: OcxSpendConfig | undefined): SpendReservationPolicy {
+  const retentionDays = spend?.retentionDays;
+  return {
+    root: spendScopeLimitFromConfig(spend?.root),
+    identity: spendScopeLimitFromConfig(spend?.identity),
+    pool: spendScopeLimitFromConfig(spend?.pool),
+    retentionMs: retentionDays !== undefined && Number.isFinite(retentionDays) && retentionDays > 0
+      ? Math.trunc(retentionDays) * 24 * 60 * 60_000
+      : DEFAULT_SPEND_RESERVATION_POLICY.retentionMs,
+  };
+}
+
+/**
+ * Apply an operator policy to the process-wide ledger.
+ *
+ * Startup calls this with the loaded config, and a reload may call it again: the ledger keeps
+ * every figure it has already accounted, so changing a ceiling changes what is refused from
+ * here on and never what was spent. It does not CREATE the ledger -- an install that
+ * configures no ceiling must not open a journal merely because the server started.
+ */
+export function configureSharedSpendLedger(policy: SpendReservationPolicy): void {
+  sharedPolicy = policy;
+  sharedLedger?.reconfigure(policy);
+}
 
 /**
  * Process-wide ledger backed by the journal under OPENCODEX_HOME. Created lazily so
@@ -947,6 +1051,7 @@ export function sharedSpendLedger(): SpendReservationLedger {
     sharedLedger = createSpendReservationLedger({
       journal: createFileSpendJournal(join(home, SPEND_LEDGER_JOURNAL_FILENAME)),
       salt: loadOrCreateSpendLedgerSalt(join(home, SPEND_LEDGER_SALT_FILENAME)),
+      policy: sharedPolicy,
     });
   }
   return sharedLedger;
@@ -955,4 +1060,5 @@ export function sharedSpendLedger(): SpendReservationLedger {
 /** Test seam. Production never discards the ledger: that would reset a spent budget. */
 export function resetSharedSpendLedgerForTest(): void {
   sharedLedger = undefined;
+  sharedPolicy = DEFAULT_SPEND_RESERVATION_POLICY;
 }

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));
 }
 /**