@bitkyc08/opencodex 2.80.0 → 2.82.0

package/src/providers/quota/anthropic-cooldown-recovery.ts

@@ -1,48 +1,15 @@
 import { mergeAnthropicFamilyWindows, hasAnthropicFamilyEnumeration } from "./anthropic-family-headers";
-import { getCachedProviderAccountQuota } from "./account-cache";
-import { observeAnthropicFamilyQuota, anthropicFamilyQuotaGeneration } from "../../oauth/anthropic-model-quota";
-import { credentialGeneration, getAccountCredential, getAccountCredentialWithStatus } from "../../oauth/store";
+import { getCachedProviderAccountQuota, captureProviderAccountQuotaEpoch } from "./account-cache";
+import { anthropicModelQuotaFor } from "../../oauth/anthropic-model-quota";
+import type { AnthropicInstanceId } from "../anthropic-instance-id";
+import type { GenerationContext } from "../../lib/state-store-sweeper";
+import { credentialGeneration, getAccountCredential, getAccountCredentialWithStatus, getAccountSet } from "../../oauth/store";
 import type { ProviderQuota } from "../quota-types";
 
 export class AnthropicQuotaProbeOwnershipError extends Error {}
 
-/** Check live pause and bearer ownership at the last synchronous step before usage dispatch. */
-export function assertAnthropicQuotaSendAllowed(accountId: string, token: string): void {
-  const row = getAccountCredentialWithStatus("anthropic", accountId);
-  if (!row || row.paused || row.needsReauth || row.credential.access !== token) {
-    throw new AnthropicQuotaProbeOwnershipError("anthropic quota account is no longer eligible");
-  }
-}
-
-const cooldownGenerationByAccount = new Map<string, number>();
-let nextCooldownGeneration = 1;
-let afterSettlementForTests: (() => void) | undefined;
-
-export function setAnthropicQuotaAfterSettlementForTests(hook: (() => void) | undefined): void {
-  afterSettlementForTests = hook;
-}
-
-/** Monotonic per-account fence shared by routing mutations and quota publication. */
-export function anthropicCooldownGeneration(accountId: string): number {
-  return cooldownGenerationByAccount.get(accountId) ?? 0;
-}
-
-/** Keep same-state quota calls joinable while moving post-429 calls to a fresh flight. */
-export function anthropicCooldownFlightKey(baseKey: string, accountId: string): string {
-  return `${baseKey}\0anthropic-cooldown:${anthropicCooldownGeneration(accountId)}`;
-}
-
-export function noteAnthropicCooldownMutation(accountId: string): number {
-  const generation = nextCooldownGeneration++;
-  cooldownGenerationByAccount.set(accountId, generation);
-  return generation;
-}
-
-export function clearAnthropicCooldownGenerations(): void {
-  cooldownGenerationByAccount.clear();
-}
-
 export type AnthropicCooldownRecoveryProbe = Readonly<{
+  instance: AnthropicInstanceId;
   requiresFreshDispatch: boolean;
   isCurrentCredential(): boolean;
   isCurrentFamily(): boolean;
@@ -51,86 +18,230 @@ export type AnthropicCooldownRecoveryProbe = Readonly<{
 }>;
 
 export type AnthropicQuotaRecoveryResult = Readonly<{
+  instance: AnthropicInstanceId;
   quota: ProviderQuota;
   /** Must be checked synchronously at each publication boundary. */
   isCurrent(): boolean;
 }>;
 
-/**
- * Bind a quota probe to both the credential and cooldown generations it observed before
- * dispatch. A successful response may otherwise arrive after either credential replacement
- * or a newer 429 and incorrectly make unrelated state eligible.
- */
-export async function captureAnthropicCooldownRecoveryProbe(
-  accountId: string,
-  accessToken: string,
-): Promise<AnthropicCooldownRecoveryProbe | null> {
-  const credential = getAccountCredential("anthropic", accountId);
-  if (!credential || credential.access !== accessToken) return null;
-  const generation = credentialGeneration(credential);
-  // Lazy because anthropic-routing reads the quota cache on normal request routing.
-  const routing = await import("../../oauth/anthropic-routing");
-  const cooldownGeneration = anthropicCooldownGeneration(accountId);
-  const familyGeneration = anthropicFamilyQuotaGeneration(accountId);
-  const claim = routing.captureAnthropicCooldownRecovery(accountId);
-  const isCurrentCredential = () => {
-    const current = getAccountCredential("anthropic", accountId);
-    return !!current && credentialGeneration(current) === generation;
-  };
-  return {
-    requiresFreshDispatch: claim !== null,
-    isCurrentCredential,
-    isCurrentFamily: () => anthropicFamilyQuotaGeneration(accountId) === familyGeneration,
-    isCurrent: () => isCurrentCredential()
-      && anthropicCooldownGeneration(accountId) === cooldownGeneration,
-    settle: quota => claim === null ? "retained"
-      : routing.settleAnthropicCooldownRecovery(claim, quota),
-  };
-}
+function createAnthropicCooldownRecovery(instance: AnthropicInstanceId) {
+  const familyGeneration = (accountId: string) => anthropicModelQuotaFor(instance).anthropicFamilyQuotaGeneration(accountId);
 
-/** Run one authoritative usage read and publish its recovery effect only while still owned. */
-export async function probeAnthropicQuotaWithRecovery(
-  accountId: string,
-  accessToken: string,
-  read: (requireFreshDispatch: boolean) => Promise<ProviderQuota | null>,
-  mayPublish: () => boolean,
-): Promise<AnthropicQuotaRecoveryResult | null> {
-  const probe = await captureAnthropicCooldownRecoveryProbe(accountId, accessToken);
-  if (!probe) throw new AnthropicQuotaProbeOwnershipError("anthropic quota probe lost credential ownership");
-  let quota: ProviderQuota | null;
-  try { quota = await read(probe.requiresFreshDispatch); }
-  catch (error) {
-    if (!probe.isCurrent() || !mayPublish()) throw new AnthropicQuotaProbeOwnershipError("anthropic quota probe failure is stale");
-    throw error;
+  /** Check live pause and bearer ownership at the last synchronous step before usage dispatch. */
+  function assertAnthropicQuotaSendAllowed(accountId: string, token: string): void {
+    const row = getAccountCredentialWithStatus(instance, accountId);
+    if (!row || row.paused || row.needsReauth || row.credential.access !== token) {
+      throw new AnthropicQuotaProbeOwnershipError(`${instance} quota account is no longer eligible`);
+    }
+  }
+
+  let cooldownGenerationByAccount: Map<string, number> | undefined;
+  let emptyGeneration = 0;
+  let nextCooldownGeneration = 1;
+  // Account lifetime is distinct from refusal/probe mutations; a valid refusal must not revoke itself.
+  let accountIncarnations: Map<string, number> | undefined;
+  let emptyAccountIncarnation = 0;
+  let nextAccountIncarnation = 1;
+  let afterSettlementForTests: (() => void) | undefined;
+
+  function setAnthropicQuotaAfterSettlementForTests(hook: (() => void) | undefined): void {
+    afterSettlementForTests = hook;
+  }
+
+  /** Monotonic per-account fence shared by routing mutations and quota publication. */
+  function anthropicCooldownGeneration(accountId: string): number {
+    return cooldownGenerationByAccount?.get(accountId) ?? emptyGeneration;
+  }
+
+  /** Keep same-state quota calls joinable while moving post-429 calls to a fresh flight. */
+  function anthropicCooldownFlightKey(baseKey: string, accountId: string): string {
+    // Flight reservation establishes an incarnation even without prior refusal evidence.
+    const generation = reserveCooldownGeneration(accountId);
+    return `${baseKey}\0${instance}-cooldown:${generation}`;
+  }
+
+  /** Active usage readers bind this key after token refresh; renewal keeps the legacy flight valid. */
+  function anthropicCredentialQuotaFlightKey(baseKey: string, accountId: string): string {
+    const row = getAccountSet(instance)?.accounts.find(row => row.id === accountId);
+    return `${anthropicCooldownFlightKey(baseKey, accountId)}\0${row ? JSON.stringify([credentialGeneration(row.credential), row.loginId, row.addedAt]) : "missing"}`;
   }
-  if (!probe.isCurrent() || !mayPublish()) {
-    throw new AnthropicQuotaProbeOwnershipError("anthropic quota probe result is stale");
+
+  function reserveCooldownGeneration(accountId: string): number {
+    return cooldownGenerationByAccount?.get(accountId) ?? noteAnthropicCooldownMutation(accountId);
+  }
+
+  function noteAnthropicCooldownMutation(accountId: string): number {
+    const generation = nextCooldownGeneration++;
+    (cooldownGenerationByAccount ??= new Map()).set(accountId, generation);
+    return generation;
+  }
+
+  function anthropicAccountIncarnation(accountId: string): number {
+    return accountIncarnations?.get(accountId) ?? emptyAccountIncarnation;
+  }
+
+  function reserveAnthropicAccountIncarnation(accountId: string): number {
+    const existing = accountIncarnations?.get(accountId);
+    if (existing !== undefined) return existing;
+    const incarnation = nextAccountIncarnation++;
+    (accountIncarnations ??= new Map()).set(accountId, incarnation);
+    return incarnation;
+  }
+
+  function clearAnthropicCooldownGenerations(): void {
+    emptyGeneration = nextCooldownGeneration++;
+    cooldownGenerationByAccount = undefined;
+    emptyAccountIncarnation = nextAccountIncarnation++;
+    accountIncarnations = undefined;
+  }
+
+  /**
+   * Bind a quota probe to both the credential and cooldown generations it observed before
+   * dispatch. A successful response may otherwise arrive after either credential replacement
+   * or a newer 429 and incorrectly make unrelated state eligible.
+   */
+  async function captureAnthropicCooldownRecoveryProbe(
+    accountId: string,
+    accessToken: string,
+  ): Promise<AnthropicCooldownRecoveryProbe | null> {
+    const credential = getAccountCredential(instance, accountId);
+    if (!credential || credential.access !== accessToken) return null;
+    const generation = credentialGeneration(credential);
+    const incarnation = reserveAnthropicAccountIncarnation(accountId);
+    const quotaEpoch = captureProviderAccountQuotaEpoch(instance);
+    const initialRow = getAccountSet(instance)?.accounts.find(row => row.id === accountId);
+    if (!initialRow || initialRow.paused || initialRow.needsReauth || credentialGeneration(initialRow.credential) !== generation) return null;
+    // Lazy because anthropic-routing reads the quota cache on normal request routing.
+    const { anthropicRoutingFor } = await import("../../oauth/anthropic-routing");
+    const routing = anthropicRoutingFor(instance);
+    const live = getAccountCredential(instance, accountId);
+    if (!live || credentialGeneration(live) !== generation) return null;
+    const cooldownGeneration = reserveCooldownGeneration(accountId);
+    const capturedFamilyGeneration = anthropicModelQuotaFor(instance).captureAnthropicFamilyQuotaGeneration(accountId);
+    const claim = routing.captureAnthropicCooldownRecovery(accountId);
+    const isCurrentCredential = () => {
+      const currentRow = getAccountSet(instance)?.accounts.find(row => row.id === accountId);
+      const current = currentRow?.credential;
+      return quotaEpoch === captureProviderAccountQuotaEpoch(instance)
+        && anthropicAccountIncarnation(accountId) === incarnation
+        && currentRow?.loginId === initialRow?.loginId && currentRow?.addedAt === initialRow?.addedAt
+        && !!current && credentialGeneration(current) === generation;
+    };
+    return {
+      instance,
+      requiresFreshDispatch: claim !== null,
+      isCurrentCredential,
+      isCurrentFamily: () => familyGeneration(accountId) === capturedFamilyGeneration,
+      isCurrent: () => isCurrentCredential()
+        && anthropicCooldownGeneration(accountId) === cooldownGeneration,
+      settle: quota => !isCurrentCredential() || anthropicCooldownGeneration(accountId) !== cooldownGeneration ? "superseded"
+        : claim === null ? "retained" : routing.settleAnthropicCooldownRecovery(claim, quota),
+    };
   }
-  if (!quota) return null;
-  const settlement = probe.settle(quota);
-  if (settlement === "superseded") {
-    throw new AnthropicQuotaProbeOwnershipError("anthropic quota probe lost cooldown ownership");
+
+  /** Run one authoritative usage read and publish its recovery effect only while still owned. */
+  async function probeAnthropicQuotaWithRecovery(
+    accountId: string,
+    accessToken: string,
+    read: (requireFreshDispatch: boolean) => Promise<ProviderQuota | null>,
+    mayPublish: () => boolean,
+  ): Promise<AnthropicQuotaRecoveryResult | null> {
+    const probe = await captureAnthropicCooldownRecoveryProbe(accountId, accessToken);
+    if (!probe) throw new AnthropicQuotaProbeOwnershipError(`${instance} quota probe lost credential ownership`);
+    if (!probe.isCurrent() || !mayPublish()) throw new AnthropicQuotaProbeOwnershipError(`${instance} quota probe lost dispatch ownership`);
+    let quota: ProviderQuota | null;
+    try { quota = await read(probe.requiresFreshDispatch); }
+    catch (error) {
+      if (!probe.isCurrent() || !mayPublish()) throw new AnthropicQuotaProbeOwnershipError(`${instance} quota probe failure is stale`);
+      throw error;
+    }
+    if (!probe.isCurrent() || !mayPublish()) {
+      throw new AnthropicQuotaProbeOwnershipError(`${instance} quota probe result is stale`);
+    }
+    if (!quota) return null;
+    const settlement = probe.settle(quota);
+    if (settlement === "superseded") {
+      throw new AnthropicQuotaProbeOwnershipError(`${instance} quota probe lost cooldown ownership`);
+    }
+    // Clearing the claimed cooldown intentionally advances the fence. Adopt that exact new
+    // generation; any later observation/429 then invalidates publication before a cache write.
+    const ownsFamily = probe.isCurrentFamily();
+    const authoritative = ownsFamily && hasAnthropicFamilyEnumeration(quota);
+    if (ownsFamily) anthropicModelQuotaFor(instance).observeAnthropicFamilyQuota(accountId, quota.customWindows ?? [], quota.updatedAt, authoritative);
+    if (!authoritative) {
+      const cached = getCachedProviderAccountQuota(instance, accountId)?.customWindows;
+      const windows = ownsFamily ? mergeAnthropicFamilyWindows(cached, quota.customWindows)
+        : cached ?? [];
+      // A superseded family enumeration has no authority, including over absent families.
+      if (!ownsFamily || windows.length) quota = { ...quota, customWindows: windows };
+    }
+    const publicationGeneration = anthropicCooldownGeneration(accountId);
+    const publicationFamilyGeneration = familyGeneration(accountId);
+    afterSettlementForTests?.();
+    return {
+      instance,
+      quota,
+      isCurrent: () => probe.isCurrentCredential()
+        && anthropicCooldownGeneration(accountId) === publicationGeneration
+        && familyGeneration(accountId) === publicationFamilyGeneration
+        && mayPublish(),
+    };
   }
-  // Clearing the claimed cooldown intentionally advances the fence. Adopt that exact new
-  // generation; any later observation/429 then invalidates publication before a cache write.
-  const ownsFamily = probe.isCurrentFamily();
-  const authoritative = ownsFamily && hasAnthropicFamilyEnumeration(quota);
-  if (ownsFamily) observeAnthropicFamilyQuota(accountId, quota.customWindows ?? [], quota.updatedAt, authoritative);
-  if (!authoritative) {
-    const cached = getCachedProviderAccountQuota("anthropic", accountId)?.customWindows;
-    const windows = ownsFamily ? mergeAnthropicFamilyWindows(cached, quota.customWindows)
-      : cached ?? [];
-    // A superseded family enumeration has no authority, including over absent families.
-    if (!ownsFamily || windows.length) quota = { ...quota, customWindows: windows };
+
+  function reconcileAnthropicCooldownGenerations(context: GenerationContext): number {
+    // Probe reservations include accounts with no cooldown, so every claim retires here.
+    for (const id of cooldownGenerationByAccount?.keys() ?? []) {
+      if (!context.oauthAccountKeys.has(`${instance}\0${id}`)) noteAnthropicCooldownMutation(id);
+    }
+    for (const id of accountIncarnations?.keys() ?? []) {
+      if (!context.oauthAccountKeys.has(`${instance}\0${id}`)) accountIncarnations!.set(id, nextAccountIncarnation++);
+    }
+    return 0; // Tombstones are retained, never reclaimed into an older generation.
   }
-  const publicationGeneration = anthropicCooldownGeneration(accountId);
-  const publicationFamilyGeneration = anthropicFamilyQuotaGeneration(accountId);
-  afterSettlementForTests?.();
-  return {
-    quota,
-    isCurrent: () => probe.isCurrentCredential()
-      && anthropicCooldownGeneration(accountId) === publicationGeneration
-      && anthropicFamilyQuotaGeneration(accountId) === publicationFamilyGeneration
-      && mayPublish(),
-  };
+  return Object.freeze({ instance, assertAnthropicQuotaSendAllowed, setAnthropicQuotaAfterSettlementForTests,
+    anthropicCooldownGeneration, anthropicCooldownFlightKey, anthropicCredentialQuotaFlightKey, noteAnthropicCooldownMutation,
+    anthropicAccountIncarnation, reserveAnthropicAccountIncarnation,
+    clearAnthropicCooldownGenerations, captureAnthropicCooldownRecoveryProbe,
+    probeAnthropicQuotaWithRecovery, reconcileAnthropicCooldownGenerations });
+}
+export type AnthropicCooldownRecovery = ReturnType<typeof createAnthropicCooldownRecovery>;
+const instances = new Map<AnthropicInstanceId, AnthropicCooldownRecovery>();
+export function anthropicCooldownRecoveryFor(instance: AnthropicInstanceId): AnthropicCooldownRecovery {
+  let facade = instances.get(instance);
+  if (!facade) { facade = createAnthropicCooldownRecovery(instance); instances.set(instance, facade); }
+  return facade;
+}
+export function reconcileAllAnthropicCooldownGenerations(context: GenerationContext): number {
+  for (const facade of instances.values()) facade.reconcileAnthropicCooldownGenerations(context);
+  return 0;
+}
+export function clearAllAnthropicCooldownGenerations(): void {
+  for (const facade of instances.values()) facade.clearAnthropicCooldownGenerations();
+}
+export function assertAnthropicQuotaSendAllowed(accountId: string, token: string): void {
+  anthropicCooldownRecoveryFor("anthropic").assertAnthropicQuotaSendAllowed(accountId, token);
+}
+export function setAnthropicQuotaAfterSettlementForTests(hook: (() => void) | undefined): void {
+  anthropicCooldownRecoveryFor("anthropic").setAnthropicQuotaAfterSettlementForTests(hook);
+}
+export function anthropicCooldownGeneration(accountId: string): number {
+  return anthropicCooldownRecoveryFor("anthropic").anthropicCooldownGeneration(accountId);
+}
+export function anthropicCooldownFlightKey(baseKey: string, accountId: string): string {
+  return anthropicCooldownRecoveryFor("anthropic").anthropicCooldownFlightKey(baseKey, accountId);
+}
+export function noteAnthropicCooldownMutation(accountId: string): number {
+  return anthropicCooldownRecoveryFor("anthropic").noteAnthropicCooldownMutation(accountId);
+}
+export function clearAnthropicCooldownGenerations(): void {
+  anthropicCooldownRecoveryFor("anthropic").clearAnthropicCooldownGenerations();
+}
+export function captureAnthropicCooldownRecoveryProbe(accountId: string, accessToken: string): Promise<AnthropicCooldownRecoveryProbe | null> {
+  return anthropicCooldownRecoveryFor("anthropic").captureAnthropicCooldownRecoveryProbe(accountId, accessToken);
+}
+export function probeAnthropicQuotaWithRecovery(
+  accountId: string, accessToken: string,
+  read: (requireFreshDispatch: boolean) => Promise<ProviderQuota | null>, mayPublish: () => boolean,
+): Promise<AnthropicQuotaRecoveryResult | null> {
+  return anthropicCooldownRecoveryFor("anthropic").probeAnthropicQuotaWithRecovery(accountId, accessToken, read, mayPublish);
 }

package/src/providers/quota/report-cache.ts

@@ -8,7 +8,7 @@ import { apiKeyPoolEntryId } from "../api-keys";
 import { getProviderRegistryEntry, providerCodexAccountMode } from "../registry";
 import { isCanonicalOpenAiForwardProvider, OPENAI_CODEX_PROVIDER_ID } from "../openai-tiers";
 import { CODEX_CAPACITY_MAX_QUOTA_AGE_MS, type CodexCapacityAggregation, type CodexCapacityQuota } from "../codex-capacity";
-import { clearCachedProviderQuotas, providerQuotaRoutingBinding, type ProviderQuotaRoutingEvidence } from "../quota-routing-cache";
+import { clearCachedProviderQuotas, providerQuotaRoutingBinding, replaceCachedProviderQuotas, type ProviderQuotaRoutingEvidence } from "../quota-routing-cache";
 import { clearProviderApiKeyQuotaCache } from "../quota-key-accounts";
 import { QUOTA_JSON_READ_FAILURE, readQuotaJson } from "../quota-wire";
 import type { OcxConfig, OcxProviderConfig } from "../../types";
@@ -101,6 +101,29 @@ export function clearProviderQuotaCache(): void {
   invalidationEpoch += 1;
 }
 
+const providerReportEpochs = new Map<string, number>();
+
+export function captureProviderReportEpochs(): ReadonlyMap<string, number> {
+  return new Map(providerReportEpochs);
+}
+
+export function providerReportEpochChanged(captured: ReadonlyMap<string, number>, provider: string): boolean {
+  return (providerReportEpochs.get(provider) ?? 0) !== (captured.get(provider) ?? 0);
+}
+
+/**
+ * Provider-scoped invalidation: drop one provider's report and routing row. The global epoch
+ * is untouched, so another provider's cached row and in-flight commit authority survive; an
+ * aggregate already in flight drops only this provider's row when it publishes.
+ */
+export function clearProviderQuotaCacheFor(provider: string): void {
+  providerReportEpochs.set(provider, (providerReportEpochs.get(provider) ?? 0) + 1);
+  if (!cache) return;
+  const reports = cache.response.reports.filter(report => report.provider !== provider);
+  cache = { ...cache, response: { ...cache.response, reports } };
+  replaceCachedProviderQuotas(reports, routingEvidence);
+}
+
 function cacheKey(config: OcxConfig): string {
   const providers = Object.entries(config.providers)
     .map(([name, provider]) => {

package/src/providers/quota/vendor-probes-key.ts

@@ -38,6 +38,7 @@ const DEEPSEEK_BASE_URL = "https://api.deepseek.com";
 const CLINE_BASE_URL = "https://api.cline.bot";
 const OLLAMA_CLOUD_BASE_URL = "https://ollama.com";
 const OLLAMA_CLOUD_USAGE_URL = `${OLLAMA_CLOUD_BASE_URL}/api/usage`;
+const OLLAMA_CLOUD_BALANCE_URL = `${OLLAMA_CLOUD_BASE_URL}/api/balance`;
 const ZAI_BASE_URL = "https://api.z.ai";
 const ZAI_CN_BASE_URL = "https://open.bigmodel.cn";
 const MINIMAX_REMAINS_PATH = "/v1/api/openplatform/coding_plan/remains";
@@ -439,11 +440,80 @@ async function fetchClineQuota(provider: string, config: OcxProviderConfig): Pro
 }
 
 /**
- * Ollama Cloud `GET https://ollama.com/api/usage` — returns account usage.
- * Legacy plans report rolling 5-hour `limits.session.usage` and 7-day
- * `limits.weekly.usage`. Migrated monthly-credit plans report
- * `limits.monthly.usage`. `usage` values are normalized fractions (0..1).
+ * Ollama Cloud quota. `GET https://ollama.com/api/balance` is the live source: it
+ * returns the included (plan) balance plus purchased credits. Legacy plans report
+ * rolling 5-hour `included.session.remaining_percent` and 7-day
+ * `included.weekly.remaining_percent` (remaining shares, so used = 100 - remaining);
+ * credit plans report `included.balance_usd`/`included.allowance_usd` over a
+ * `period`.
+ *
+ * `GET https://ollama.com/api/usage` used to carry `limits.{session,weekly,monthly}.usage`
+ * as normalized fractions but now returns only a request-count timeseries, so it is
+ * kept as a fallback for older deployments.
  */
+function parseOllamaUsedPercent(row: Record<string, unknown>): number | undefined {
+  if (row.remaining_percent !== undefined) {
+    const remaining = toFiniteNumber(row.remaining_percent);
+    if (remaining === undefined) return undefined;
+    return normalizePercent(Math.round((100 - remaining) * 100) / 100);
+  }
+  return parseOllamaPercent(row.usage);
+}
+
+export function parseOllamaCloudBalance(body: Record<string, unknown> | null): ProviderQuota | null {
+  if (!body) return null;
+  const included = asRecord(body.included);
+  if (!included) return null;
+
+  const quota: ProviderQuota = { updatedAt: Date.now() };
+  let windows = 0;
+
+  const rows: Array<[string, "fiveHour" | "weekly" | "monthly"]> = [
+    ["session", "fiveHour"],
+    ["weekly", "weekly"],
+    ["monthly", "monthly"],
+  ];
+  for (const [key, window] of rows) {
+    const row = asRecord(included[key]);
+    if (!row) continue;
+    const percent = parseOllamaUsedPercent(row);
+    if (percent === undefined) continue;
+    const resetAt = normalizeResetAt(row.resets_at);
+    if (window === "fiveHour") {
+      quota.fiveHourPercent = percent;
+      if (resetAt !== undefined) quota.fiveHourResetAt = resetAt;
+    } else if (window === "weekly") {
+      quota.weeklyPercent = percent;
+      if (resetAt !== undefined) quota.weeklyResetAt = resetAt;
+    } else {
+      quota.monthlyPercent = percent;
+      if (resetAt !== undefined) quota.monthlyResetAt = resetAt;
+    }
+    windows += 1;
+  }
+
+  const allowance = toFiniteNumber(included.allowance_usd);
+  const balance = toFiniteNumber(included.balance_usd);
+  if (allowance !== undefined && allowance > 0 && balance !== undefined) {
+    const used = Math.max(0, allowance - balance);
+    const percent = normalizePercent(Math.round((used / allowance) * 10000) / 100);
+    if (percent !== undefined) {
+      const expiresAt = normalizeResetAt(asRecord(included.period)?.until);
+      // creditsUsd is the included allowance only; purchased credits are ignored.
+      quota.creditsUsd = {
+        used,
+        limit: allowance,
+        remaining: balance,
+        percent,
+        ...(expiresAt !== undefined ? { expiresAt } : {}),
+      };
+      windows += 1;
+    }
+  }
+
+  return windows > 0 ? quota : null;
+}
+
 function parseOllamaPercent(usageValue: unknown): number | undefined {
   const usage = toFiniteNumber(usageValue);
   if (usage === undefined || usage < 0) return undefined;
@@ -489,25 +559,65 @@ export function parseOllamaCloudQuota(body: Record<string, unknown> | null): Pro
   return windows > 0 ? quota : null;
 }
 
+/**
+ * Routing projection for an `/api/balance` report. `creditsUsd` covers the included
+ * allowance only, so it may veto routing only when purchased credit is known to be empty;
+ * otherwise an exhausted allowance would block an account that still has paid balance.
+ */
+function ollamaBalanceInferenceQuota(quota: ProviderQuota, body: Record<string, unknown> | null): ProviderQuota {
+  if (!quota.creditsUsd) return quota;
+  const purchased = toFiniteNumber(asRecord(body?.purchased)?.balance_usd);
+  if (purchased !== undefined && purchased <= 0) return quota;
+  const { creditsUsd: _includedOnly, ...inference } = quota;
+  return inference;
+}
+
 async function fetchOllamaCloudQuota(provider: string, config: OcxProviderConfig): Promise<ProviderQuotaProbeResult> {
   const effectiveBaseUrl = config.baseUrl ?? getProviderRegistryEntry(provider)?.baseUrl ?? "";
   if (!isCanonicalOllamaCloudBaseUrl(effectiveBaseUrl)) return null;
   const apiKey = resolveProviderApiKey(config.apiKey)?.trim();
   if (!apiKey) return null;
-  const response = await quotaFetch(provider, config, OLLAMA_CLOUD_USAGE_URL, {
-    headers: { Accept: "application/json", Authorization: `Bearer ${apiKey}` },
-    redirect: "error",
-    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
-  });
-  if (!response.ok) {
-    if (response.status === 404) return null;
-    return response.status >= 400 && response.status < 500 && response.status !== 408 && response.status !== 429
-      ? TERMINAL_QUOTA_FAILURE
-      : null;
+  const attempts: Array<{
+    url: string;
+    source: string;
+    parse: (body: Record<string, unknown> | null) => ProviderQuota | null;
+  }> = [
+    { url: OLLAMA_CLOUD_BALANCE_URL, source: "ollama-cloud:balance", parse: parseOllamaCloudBalance },
+    { url: OLLAMA_CLOUD_USAGE_URL, source: "ollama-cloud:usage", parse: parseOllamaCloudQuota },
+  ];
+  let terminalFailure = false;
+  for (const attempt of attempts) {
+    let response: Response;
+    try {
+      response = await quotaFetch(provider, config, attempt.url, {
+        headers: { Accept: "application/json", Authorization: `Bearer ${apiKey}` },
+        redirect: "error",
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+      });
+    } catch {
+      continue;
+    }
+    if (!response.ok) {
+      if (response.status !== 404 && response.status >= 400 && response.status < 500 && response.status !== 408 && response.status !== 429) {
+        terminalFailure = true;
+      }
+      try {
+        void response.body?.cancel().catch(() => undefined);
+      } catch {
+        // Best-effort cancellation only.
+      }
+      continue;
+    }
+    const raw = await readQuotaJson(response);
+    if (raw === QUOTA_JSON_READ_FAILURE) return terminalFailure ? TERMINAL_QUOTA_FAILURE : null;
+    const body = asRecord(raw);
+    const quota = attempt.parse(body);
+    if (quota) {
+      const inference = attempt.url === OLLAMA_CLOUD_BALANCE_URL ? ollamaBalanceInferenceQuota(quota, body) : quota;
+      return keyReport(provider, attempt.source, quota, config, apiKey, inference);
+    }
   }
-  const body = asRecord(await readQuotaJson(response));
-  const quota = parseOllamaCloudQuota(body);
-  return quota ? keyReport(provider, "ollama-cloud:usage", quota, config, apiKey, quota) : null;
+  return terminalFailure ? TERMINAL_QUOTA_FAILURE : null;
 }
 
 /**