opencode-auth-load-balancer 0.9.0 → 0.10.0

package/README.md

@@ -16,6 +16,7 @@ Selection is **not** round-robin. It is weighted primarily by **weekly** usage,
 - **Self-updating Claude Code version** — Anthropic gates new models on the client version the request claims, so a pinned version stops working the day a model ships (`Claude Code 2.1.87 does not support this model; version 2.1.251 or newer is required`). The plugin discovers the current version from npm instead, caches it for a day, and never regresses below a version known to work. See [Claude Code version](#claude-code-version).
 - **Session affinity** — a conversation stays pinned to one account so you keep its prompt cache and don't re-send context on every turn.
 - **Proactive migration** — leaves an account at a configurable soft threshold (~95%) instead of waiting for a hard 100% wall (which can break in-flight subagents).
+- **Codex credits** — a Codex account whose plan usage is exhausted keeps serving on its ChatGPT credits, as the Codex CLI and desktop app do. Credits cost money, so plan quota on any account is spent first, and a session running on credits moves back as soon as an account has plan headroom again. The dashboards show what is left beside the exhausted state.
 - **Single-use refresh-token safety** — per-account singleflight refresh; rotated tokens are persisted immediately.
 - **Visibility** — toasts for account switches, model fallback, pending/recovery, and restart restoration; an on-demand `auth_lb_status` tool; and a `bun run status` CLI dashboard.
 - **Gist sync of credentials and OAuth logins** — machines share their Claude tokens, Kimi API keys and (unless switched off) their Claude / Codex / Kimi OAuth logins, encrypted, through a secret GitHub gist, both ways: every machine that follows the link downloads, and one with a GitHub token also uploads its own. See [Sync credentials and OAuth logins between machines](#sync-credentials-and-oauth-logins-between-machines-github-gist).
@@ -287,6 +288,16 @@ Pending turns
 
 `▶` marks the in-use account; `#` is the rank the scheduler would pick next.
 
+An exhausted Codex account that still has ChatGPT credits stays selectable, ranked after every account with plan headroom, and its state shows the balance: `ready · credits 42.5` here, `full · credits 42.5` in the TUI sidebar. `credits unlimited` and `credits available` (no amount reported) are usable too; `no credits` means the account waits for its plan to reset. Balances come from the `/wham/usage` endpoint and from the `x-codex-credits-*` headers of every Codex response. A turn waiting for quota rechecks at least every five minutes, so credits that appear meanwhile (reported for the first time, or bought) resume it without waiting for the plan reset.
+
+While OpenCode is running, stale usage is checked every five minutes even without inference traffic or a status-tool call. Periodic checks share a machine-wide lock and a next-attempt timestamp in `auth-load-balancer.json.usage-poll.json`, so multiple windows do not multiply periodic requests, including failed attempts. The file contains scheduling metadata only, never credentials.
+
+A fresh usage measurement during re-login or a periodic check clears an obsolete, long quota cooldown when both usage windows have headroom. A successful re-login alone is not enough: exhausted or malformed usage, authentication/transient backoffs, and a newer rejection received during a usage check retain their cooldowns. Provider-side resets are picked up on the next successful check; a failed endpoint request never assumes recovery.
+
+If a usage endpoint rejects an OAuth access token with HTTP 401, the poll uses the same refresh lock and rejected-token recovery as inference, then retries the usage lookup once, even when the advertised access expiry is still in the future. A concurrently refreshed credential is adopted instead of spending its predecessor again. Static API keys are never sent to OAuth refresh, and 403/429 failures do not trigger authentication retries.
+
+A 403 caused by a missing `user:profile` scope requires a fresh OAuth login with browser approval. Restarting OpenCode or refreshing the same grant cannot restore that missing permission; an authoritative usage result is still required before clearing the old quota cooldown.
+
 ### Persistent bottom status bar (TUI)
 
 A SolidJS TUI plugin renders a persistent bottom status bar (opencode's always-visible `app_bottom` slot) showing both the in-use account(s) per provider (polled from the pool, e.g. `Claude anthropic-1 58% · 5h 12%`) **and** the current session usage — tokens, % of the model context window, and `$` cost — computed the same way opencode's own footer does. It is **four files**:
@@ -335,7 +346,7 @@ All knobs are environment variables with sane defaults.
 | `OPENCODE_AUTH_LB_HOURLY_INFLUENCE` | `0.5` | How much 5h headroom modulates the weekly-urgency score (0–1). |
 | `OPENCODE_AUTH_LB_MIN_RESET_MS` | `300000` | Floor on time-to-reset (caps urgency near a reset). |
 | `OPENCODE_AUTH_LB_WEEK_WINDOW_MS` | `604800000` | Baseline horizon used when a weekly reset time is unknown. |
-| `OPENCODE_AUTH_LB_EXHAUSTED_AT` | `0.999` | Hard exhaustion: at/above this utilization an account is excluded. |
+| `OPENCODE_AUTH_LB_EXHAUSTED_AT` | `0.999` | Hard exhaustion: at/above this utilization an account is excluded, unless Codex credits keep it serving. |
 | `OPENCODE_AUTH_LB_MIGRATE_AT` | `0.95` | Soft threshold to proactively leave a pinned account (before 100%). |
 | `OPENCODE_AUTH_LB_WEEKLY_DRAIN_TARGET` | `0.98` | Soft threshold for the WEEKLY window: scoring treats weekly quota as "fully drained" past this utilization, and a pinned session proactively migrates once its weekly util crosses it. The 5h window uses `MIGRATE_AT` (~0.95); the weekly window uses this (~0.98). Must be in (`MIGRATE_AT`, `EXHAUSTED_AT`]. |
 | `OPENCODE_AUTH_LB_CHEAP_SWITCH_MAX_BYTES` | `65536` | For non-forced (proactive/drain) switches, only switch when the request body ≤ this many bytes, so a grown conversation isn't re-sent onto a fresh (uncached) account — a full per-account prompt-cache write. `0` disables the gate (always switch). A proactive switch bypasses this gate when the pinned account is within ~1% of hard exhaustion (a forced switch is imminent anyway and the context only grows); forced switches always ignore it. |

package/dist/index.js

@@ -13054,6 +13054,18 @@ function normalizeWindow(w) {
     win.resetAt = 0;
   return win;
 }
+function normalizeCredits(c) {
+  if (!isPlainObject2(c))
+    return;
+  const credits = c;
+  if (typeof credits.hasCredits !== "boolean" || typeof credits.unlimited !== "boolean")
+    return;
+  if (!isFiniteNumber(credits.balance))
+    delete credits.balance;
+  if (credits.limitReached !== true)
+    delete credits.limitReached;
+  return credits;
+}
 function normalizeAccounts(rows) {
   let accounts = null;
   for (let i = 0;i < rows.length; i++) {
@@ -13073,7 +13085,13 @@ function normalizeAccounts(rows) {
         row.usage.capturedAt = 0;
       row.usage.hourly = normalizeWindow(row.usage.hourly);
       row.usage.weekly = normalizeWindow(row.usage.weekly);
+      delete row.usage.credits;
     }
+    const credits = normalizeCredits(row.credits);
+    if (credits)
+      row.credits = credits;
+    else
+      delete row.credits;
     if (!Number.isFinite(row.cooldownUntil))
       row.cooldownUntil = 0;
     if (row.cooldownKind !== undefined && row.cooldownKind !== "quota" && row.cooldownKind !== "auth" && row.cooldownKind !== "transient")
@@ -13326,14 +13344,19 @@ function maxUtil(account, now) {
 function isExhausted(account, cfg, now) {
   return maxUtil(account, now) >= cfg.exhaustedAt;
 }
+function hasCreditHeadroom(account) {
+  const credits = account.credits;
+  return !!credits && !credits.limitReached && (credits.unlimited || credits.hasCredits);
+}
+function hasHeadroom(account, cfg, now) {
+  return !isExhausted(account, cfg, now) || hasCreditHeadroom(account);
+}
 function isAvailable(account, cfg, now) {
   if (account.disabledReason)
     return false;
   if (account.cooldownUntil > now)
     return false;
-  if (isExhausted(account, cfg, now))
-    return false;
-  return true;
+  return hasHeadroom(account, cfg, now);
 }
 function weeklyUrgency(account, cfg, now) {
   const weekly = account.usage.weekly;
@@ -13364,9 +13387,11 @@ function scoreAccount(account, cfg, now) {
 function compareRanked(x, y) {
   if (x.available !== y.available)
     return x.available ? -1 : 1;
-  if (x.available)
-    return y.score - x.score;
-  return x.weeklyUtil - y.weeklyUtil;
+  if (!x.available)
+    return x.weeklyUtil - y.weeklyUtil;
+  if (x.onCredits !== y.onCredits)
+    return x.onCredits ? 1 : -1;
+  return y.score - x.score;
 }
 var DAY_MS, WEEK_MS2, HOUR_MS, HOURLY_WINDOW_MS, RESET_CUSHION_DAYS = 0.25, SCORE_DEFAULTS;
 var init_score_core = __esm(() => {
@@ -13385,6 +13410,14 @@ var init_score_core = __esm(() => {
 });
 
 // src/usage-merge.ts
+function reconcileQuotaCooldown(account, cfg, now) {
+  if (account.cooldownKind === "auth" || account.cooldownKind === "transient")
+    return;
+  if (account.cooldownUntil > now + MAX_TRANSIENT_COOLDOWN_MS && hasHeadroom(account, cfg, now)) {
+    account.cooldownUntil = 0;
+    delete account.cooldownKind;
+  }
+}
 function rollWeeklyAnchorForward(anchor, now) {
   if (!Number.isFinite(anchor) || anchor <= 0)
     return 0;
@@ -13401,8 +13434,10 @@ function preserveWeeklyAnchor(incoming, stored, now) {
     return incoming;
   return { utilization: incoming.utilization, resetAt: anchor };
 }
+var MAX_TRANSIENT_COOLDOWN_MS;
 var init_usage_merge = __esm(() => {
   init_score_core();
+  MAX_TRANSIENT_COOLDOWN_MS = 5 * 60 * 1000;
 });
 
 // src/accounts.ts
@@ -13449,11 +13484,15 @@ function clearLostLogin(row, login) {
 function mergeLoginUsage(row, usage) {
   if (!usage)
     return;
+  if (usage.credits)
+    row.credits = usage.credits;
   row.usage = {
     hourly: usage.hourly ?? row.usage.hourly,
     weekly: usage.weekly ? preserveWeeklyAnchor(usage.weekly, row.usage.weekly, usage.capturedAt) : row.usage.weekly,
     capturedAt: usage.weekly ? usage.capturedAt : row.usage.capturedAt
   };
+  if (usage.weekly)
+    reconcileQuotaCooldown(row, loadScoreConfig(), usage.capturedAt);
 }
 function applyTokens(row, tokens) {
   if (tokens.refresh) {
@@ -13547,6 +13586,7 @@ async function bootstrapFromOpencodeAuth(providerID, getAuth, tokensFromApiKey)
 var init_accounts = __esm(() => {
   init_pairing();
   init_store();
+  init_score_core();
   init_types();
   init_usage_merge();
 });
@@ -13571,7 +13611,8 @@ function classifyProviderRecovery(accounts, providerID, cfg, now, pollMs) {
       continue;
     const windows = exhaustedWindows(account, cfg, now);
     const cooldownActive = account.cooldownUntil > now;
-    if (!cooldownActive && windows.length === 0)
+    const blocking = hasCreditHeadroom(account) ? [] : windows;
+    if (!cooldownActive && blocking.length === 0)
       return { state: "available" };
     if (cooldownActive && (account.cooldownKind === "auth" || account.cooldownKind === "transient"))
       continue;
@@ -13580,7 +13621,7 @@ function classifyProviderRecovery(accounts, providerID, cfg, now, pollMs) {
     hasQuotaCandidate = true;
     const constraints = [];
     let accountHasUnknownReset = false;
-    for (const window of windows) {
+    for (const window of blocking) {
       if (window.resetAt > now)
         constraints.push(window.resetAt);
       else
@@ -13893,22 +13934,27 @@ function weeklyUtil(account) {
 function selectAccount(accounts, providerID, now, cfg = DEFAULT_CONFIG, exclude = NO_EXCLUSIONS, incumbentId = null) {
   let bestAvail = null;
   let bestAvailScore = Number.NEGATIVE_INFINITY;
+  let bestAvailOnCredits = true;
   let bestFallback = null;
   let lowestWeeklyUtil = Number.POSITIVE_INFINITY;
   let incumbentAccount = null;
   let incumbentScore = Number.NEGATIVE_INFINITY;
+  let incumbentOnCredits = false;
   for (const account of accounts) {
     if (account.providerID !== providerID || account.disabledReason || exclude.has(account.id))
       continue;
     if (isAvailable(account, cfg, now)) {
       const score = scoreAccount(account, cfg, now);
-      if (score > bestAvailScore) {
+      const onCredits = isExhausted(account, cfg, now);
+      if (onCredits === bestAvailOnCredits ? score > bestAvailScore : bestAvailOnCredits) {
         bestAvailScore = score;
         bestAvail = account;
+        bestAvailOnCredits = onCredits;
       }
       if (account.id === incumbentId) {
         incumbentAccount = account;
         incumbentScore = score;
+        incumbentOnCredits = onCredits;
       }
     } else {
       const util = weeklyUtil(account);
@@ -13919,7 +13965,7 @@ function selectAccount(accounts, providerID, now, cfg = DEFAULT_CONFIG, exclude
     }
   }
   if (bestAvail) {
-    if (incumbentAccount && incumbentScore >= bestAvailScore * (1 - INCUMBENT_HYSTERESIS))
+    if (incumbentAccount && incumbentOnCredits === bestAvailOnCredits && incumbentScore >= bestAvailScore * (1 - INCUMBENT_HYSTERESIS))
       return { account: incumbentAccount, degraded: false, sticky: false };
     return { account: bestAvail, degraded: false, sticky: false };
   }
@@ -13958,7 +14004,7 @@ function selectForSession(pool, providerID, sessionKey, now, cfg = DEFAULT_CONFI
     const cheap = (!pinnedImminent || cfg.drainMigrate) && isCheapMoment(typeof requestBytes === "function" ? requestBytes() : requestBytes, cfg);
     if (pinnedOverSoft && (pinnedImminent || cheap) || cfg.drainMigrate && cheap) {
       const alt = selectAccount(pool.accounts, providerID, now, cfg, withExcluded(exclude, pinned.id), null);
-      if (alt && !alt.degraded) {
+      if (alt && !alt.degraded && !isExhausted(alt.account, cfg, now)) {
         if (pinnedOverSoft) {
           const altUtil = maxUtil(alt.account, now);
           const proactiveBetter = pinnedImminent ? altUtil < pinnedUtil : pinnedUtil - altUtil >= PROACTIVE_MIGRATE_MIN_DELTA && weeklyUrgency(alt.account, cfg, now) >= weeklyUrgency(pinned, cfg, now);
@@ -14488,24 +14534,46 @@ var init_usage_headers = __esm(() => {
 });
 
 // src/providers/usage-http.ts
-async function fetchJson(url, headers, timeoutMs) {
-  let response;
+async function request(url, headers, timeoutMs) {
   try {
-    response = await fetch(url, {
+    return await fetch(url, {
       headers,
       signal: AbortSignal.timeout(timeoutMs)
     });
   } catch {
     return null;
   }
+}
+async function readJson(response) {
+  if (!response)
+    return null;
   if (!response.ok) {
     await response.body?.cancel().catch(ignore);
     return null;
   }
   return await response.json().catch(() => null);
 }
+async function fetchJson(url, headers, timeoutMs) {
+  return readJson(await request(url, headers, timeoutMs));
+}
+async function fetchUsageJson(url, headers, timeoutMs) {
+  const response = await request(url, headers, timeoutMs);
+  if (response?.status === 401) {
+    await response.body?.cancel().catch(ignore);
+    throw new UsageAuthenticationError;
+  }
+  return readJson(response);
+}
+var UsageAuthenticationError;
 var init_usage_http = __esm(() => {
   init_util2();
+  UsageAuthenticationError = class UsageAuthenticationError extends Error {
+    status = 401;
+    constructor() {
+      super("Usage endpoint rejected the access token (401)");
+      this.name = "UsageAuthenticationError";
+    }
+  };
 });
 
 // src/providers/anthropic/version.ts
@@ -14945,7 +15013,7 @@ async function probeUsage(access, now) {
 async function fetchUsage(account, now) {
   if (!account.refresh)
     return probeUsage(account.access, now);
-  const json = await fetchJson(USAGE_URL, {
+  const json = await fetchUsageJson(USAGE_URL, {
     authorization: `Bearer ${account.access}`,
     "anthropic-beta": "oauth-2025-04-20",
     "user-agent": usageUserAgent(),
@@ -15277,7 +15345,7 @@ function parseUsages(json, now) {
   return hourly || weekly ? { hourly, weekly, capturedAt: now } : null;
 }
 function getUsages(baseUrl, key) {
-  return fetchJson(`${baseUrl}/usages`, { authorization: `Bearer ${key}`, accept: "application/json" }, USAGE_HTTP_TIMEOUT_MS);
+  return fetchUsageJson(`${baseUrl}/usages`, { authorization: `Bearer ${key}`, accept: "application/json" }, USAGE_HTTP_TIMEOUT_MS);
 }
 function usageFetcher(baseUrl) {
   return async (account, now) => parseUsages(await getUsages(baseUrl, account.access), now);
@@ -15534,10 +15602,31 @@ var init_transform2 = __esm(() => {
 function isWeeklyMinutes(minutes) {
   return minutes >= WEEK_MINUTES * 0.95 && minutes <= WEEK_MINUTES * 1.05;
 }
+function creditsFrom(hasCredits, unlimited, balance, limitReached) {
+  if (typeof hasCredits !== "boolean" || typeof unlimited !== "boolean")
+    return;
+  const amount = typeof balance === "string" && balance.trim() !== "" ? Number(balance) : Number.NaN;
+  return {
+    hasCredits,
+    unlimited,
+    ...Number.isFinite(amount) ? { balance: amount } : {},
+    ...limitReached === true ? { limitReached } : {}
+  };
+}
+function headerBool(raw) {
+  const value = raw?.toLowerCase();
+  if (value === "true" || value === "1")
+    return true;
+  if (value === "false" || value === "0")
+    return false;
+  return;
+}
 function parseUsageHeaders2(headers) {
   const primaryWindowMinutes = Number(headers.get(PRIMARY_WINDOW_MINUTES_HEADER));
   const spec = isWeeklyMinutes(primaryWindowMinutes) ? WEEKLY_PRIMARY_HEADER_SPEC : HEADER_SPEC2;
-  return parseWindowPairHeaders(headers, spec);
+  const windows = parseWindowPairHeaders(headers, spec);
+  const credits = creditsFrom(headerBool(headers.get("x-codex-credits-has-credits")), headerBool(headers.get("x-codex-credits-unlimited")), headers.get("x-codex-credits-balance"));
+  return credits ? { ...windows, credits } : windows;
 }
 function endpointWindow2(w) {
   return endpointWindowFrom(w, (win) => win.used_percent, 100, (win) => secondsToMs(Number(win.reset_at ?? 0)));
@@ -15551,16 +15640,19 @@ async function fetchUsage2(account, now) {
   const accountId = resolveAccountId(account);
   if (accountId)
     headers["chatgpt-account-id"] = accountId;
-  const json = await fetchJson(USAGE_URL2, headers, USAGE_HTTP_TIMEOUT_MS);
+  const json = await fetchUsageJson(USAGE_URL2, headers, USAGE_HTTP_TIMEOUT_MS);
   const rateLimit = json?.rate_limit;
   if (!isPlainObject2(rateLimit))
     return null;
   const { primary_window: primary, secondary_window: secondary } = rateLimit;
   const primaryIsWeekly = isWeeklyMinutes(Math.ceil(Number(primary?.limit_window_seconds) / 60));
+  const reported = json?.credits;
+  const credits = isPlainObject2(reported) ? creditsFrom(reported.has_credits, reported.unlimited, reported.balance, reported.overage_limit_reached) : undefined;
   return {
     hourly: endpointWindow2(primaryIsWeekly ? secondary : primary),
     weekly: endpointWindow2(primaryIsWeekly ? primary : secondary),
-    capturedAt: now
+    capturedAt: now,
+    ...credits ? { credits } : {}
   };
 }
 var WEEK_MINUTES, PRIMARY_WINDOW_MINUTES_HEADER = "x-codex-primary-window-minutes", HEADER_SPEC2, WEEKLY_PRIMARY_HEADER_SPEC;
@@ -15607,6 +15699,7 @@ var init_adapter3 = __esm(() => {
     },
     parseUsageHeaders: parseUsageHeaders2,
     fetchUsage: fetchUsage2,
+    reportsCredits: true,
     classifyError: classifyHttpStatus
   };
 });
@@ -15640,11 +15733,14 @@ async function refreshUsage(adapters, now, poolSnapshot) {
     aliveIds?.add(account.id);
     if (account.disabledReason && account.disabledReason !== MANUAL_DISABLED_REASON)
       continue;
-    if (account.usage.capturedAt !== 0 && now - account.usage.capturedAt <= USAGE_REFRESH_TTL_MS)
+    const fresh = account.usage.capturedAt !== 0 && now - account.usage.capturedAt < USAGE_REFRESH_TTL_MS;
+    if (fresh && account.credits)
       continue;
     const adapter = adapterFor(adapters, account.providerID);
     if (!adapter)
       continue;
+    if (fresh && !adapter.reportsCredits)
+      continue;
     if ((lastPoll.get(account.id) ?? 0) > now - USAGE_REFRESH_TTL_MS)
       continue;
     lastPoll.set(account.id, now);
@@ -15662,20 +15758,29 @@ async function refreshUsage(adapters, now, poolSnapshot) {
   await Promise.all(stale.map(async ({ adapter, account }) => {
     try {
       await ensureAccessToken(adapter, account, now);
-      const snapshot = await adapter.fetchUsage(account, now);
+      const rejectedAccess = account.access;
+      let snapshot;
+      try {
+        snapshot = await adapter.fetchUsage(account, now);
+      } catch (error) {
+        if (!(error instanceof UsageAuthenticationError) || !account.refresh)
+          throw error;
+        await ensureAccessToken(adapter, account, now, rejectedAccess);
+        snapshot = await adapter.fetchUsage(account, now);
+      }
       if (snapshot) {
         await mutatePool((p) => {
           const stored = findAccount(p, account.id);
           if (stored) {
+            if (snapshot.credits)
+              stored.credits = snapshot.credits;
             stored.usage = {
               hourly: snapshot.hourly ?? stored.usage.hourly,
               weekly: snapshot.weekly === null ? stored.usage.weekly : preserveWeeklyAnchor(snapshot.weekly, stored.usage.weekly, now),
               capturedAt: snapshot.weekly === null ? stored.usage.capturedAt : now
             };
-            if (snapshot.weekly !== null && stored.cooldownUntil > now + MAX_TRANSIENT_COOLDOWN_MS && !isExhausted(stored, scoreCfg, now)) {
-              stored.cooldownUntil = 0;
-              delete stored.cooldownKind;
-            }
+            if (snapshot.weekly !== null && stored.cooldownUntil === account.cooldownUntil && stored.cooldownKind === account.cooldownKind)
+              reconcileQuotaCooldown(stored, scoreCfg, now);
           }
         });
       }
@@ -15688,16 +15793,17 @@ function refreshUsageInBackground(adapter, now, poolSnapshot) {
 function refreshAllUsageInBackground(now, poolSnapshot) {
   return refreshUsage(ADAPTERS, now, poolSnapshot);
 }
-var USAGE_REFRESH_TTL_MS, MAX_TRANSIENT_COOLDOWN_MS, lastPoll;
+var USAGE_REFRESH_TTL_MS, lastPoll;
 var init_usage_refresh = __esm(() => {
   init_store();
   init_registry();
+  init_usage_http();
   init_refresh();
   init_score_core();
   init_types();
   init_usage_merge();
+  init_usage_merge();
   USAGE_REFRESH_TTL_MS = 5 * 60 * 1000;
-  MAX_TRANSIENT_COOLDOWN_MS = 5 * 60 * 1000;
   lastPoll = new Map;
 });
 
@@ -15720,6 +15826,8 @@ async function bestEffort(what, op) {
 function applyUsagePartial(account, partial, now) {
   if (partial.hourly !== undefined)
     account.usage.hourly = partial.hourly;
+  if (partial.credits !== undefined)
+    account.credits = partial.credits;
   if (partial.weekly !== undefined) {
     account.usage.weekly = preserveWeeklyAnchor(partial.weekly, account.usage.weekly, now);
     account.usage.capturedAt = now;
@@ -15788,7 +15896,7 @@ async function recordSuccess(adapter, accountId, partial, sessionKey, now, cfg,
     if (account) {
       if (partial)
         applyUsagePartial(account, partial, now);
-      if (partial && account.cooldownUntil > now + ACCOUNT_COOLDOWN_MS && !isExhausted(account, cfg, now)) {
+      if (partial && account.cooldownUntil > now + ACCOUNT_COOLDOWN_MS && hasHeadroom(account, cfg, now)) {
         account.cooldownUntil = 0;
         delete account.cooldownKind;
       }
@@ -16132,7 +16240,18 @@ function byProviderId(a, b) {
 function isExpired(window, now) {
   return !!window && window.resetAt > 0 && window.resetAt <= now;
 }
-function toStatus(account, now, current, available, rank) {
+function creditsText(credits) {
+  if (!credits)
+    return "";
+  if (credits.limitReached)
+    return "credit limit reached";
+  if (credits.unlimited)
+    return "credits unlimited";
+  if (!credits.hasCredits)
+    return "no credits";
+  return credits.balance === undefined ? "credits available" : `credits ${Math.round(credits.balance * 100) / 100}`;
+}
+function toStatus(account, now, current, available, exhausted, rank) {
   const weekly = account.usage.weekly;
   const weeklyExpired = isExpired(weekly, now);
   return {
@@ -16148,6 +16267,7 @@ function toStatus(account, now, current, available, rank) {
     login: credentialTag(account),
     warnings: loginWarnings(account, now),
     lostNotes: lostLoginNotes(account, now),
+    credits: exhausted ? creditsText(account.credits) : "",
     current,
     rank
   };
@@ -16166,14 +16286,17 @@ function buildStatus(pool, now, cfg = DEFAULT_CONFIG) {
     const currentAccountId = pool.lastSelected[providerID] ?? null;
     const ranked = providerAccounts.map((a) => {
       const available = isAvailable(a, cfg, now);
+      const exhausted = isExhausted(a, cfg, now);
       return {
         a,
         available,
+        exhausted,
+        onCredits: available && exhausted,
         score: available ? scoreAccount(a, cfg, now) : Number.NEGATIVE_INFINITY,
         weeklyUtil: a.usage.weekly?.utilization ?? 0
       };
     }).sort(compareRanked);
-    const accounts = ranked.map(({ a, available }, i) => toStatus(a, now, a.id === currentAccountId, available, i + 1));
+    const accounts = ranked.map(({ a, available, exhausted }, i) => toStatus(a, now, a.id === currentAccountId, available, exhausted, i + 1));
     return { providerID, accounts };
   });
 }
@@ -16213,12 +16336,10 @@ function stateOf(a, now) {
   if (a.cooldownUntil > now)
     return `cooldown ${relTime(a.cooldownUntil, now)}`;
   if (!a.available)
-    return "exhausted";
+    return a.credits ? `exhausted · ${a.credits}` : "exhausted";
   const base = a.current ? "in use" : "ready";
   const tiers = Object.entries(a.modelCooldownsUntil).filter(([, until]) => until > now).sort(([x], [y]) => compareAscii(x, y)).map(([tier, until]) => `${tier} ${relTime(until, now)}`);
-  if (tiers.length > 0)
-    return `${base} · ${tiers.join(" · ")}`;
-  return base;
+  return [base, a.credits, ...tiers].filter(Boolean).join(" · ");
 }
 function providerName(providerID) {
   return PROVIDER_NAMES[providerID] ?? providerID;
@@ -16694,7 +16815,7 @@ class PendingCoordinator {
     await this.notifyPending(ref, recovery);
     try {
       for (;; ) {
-        await this.dependencies.sleep(Math.max(0, recovery.nextCheckAt - this.dependencies.now()), controller.signal);
+        await this.dependencies.sleep(Math.max(0, Math.min(recovery.nextCheckAt - this.dependencies.now(), USAGE_REFRESH_TTL_MS)), controller.signal);
         const now = this.dependencies.now();
         await this.dependencies.refreshUsage(now).catch(ignore);
         let next;
@@ -17329,7 +17450,7 @@ function backoffFrom(res, now) {
 function isRateLimited(res) {
   return res.status === 429 || res.status === 403 && (res.headers.get("x-ratelimit-remaining") === "0" || res.headers.has("retry-after"));
 }
-async function request(url, init, now) {
+async function request2(url, init, now) {
   let res;
   try {
     res = await globalThis.fetch(url, {
@@ -17381,7 +17502,7 @@ async function boundedText(res) {
   }
   return Buffer.concat(chunks).toString("utf8");
 }
-async function readJson(res) {
+async function readJson2(res) {
   if (!res.ok)
     throw new SyncError("http");
   const text = await boundedText(res);
@@ -17396,7 +17517,7 @@ async function readJson(res) {
   return json;
 }
 async function createGist(token, content, now = Date.now()) {
-  const res = await request(API, {
+  const res = await request2(API, {
     method: "POST",
     headers: { ...headers(token), "content-type": "application/json" },
     body: JSON.stringify({
@@ -17405,7 +17526,7 @@ async function createGist(token, content, now = Date.now()) {
       files: { [GIST_FILE]: { content } }
     })
   }, now);
-  const json = await readJson(res);
+  const json = await readJson2(res);
   const owner = isPlainObject2(json.owner) ? json.owner.login : undefined;
   if (typeof json.id !== "string" || !GIST_ID_RE.test(json.id))
     throw new SyncError("http");
@@ -17417,7 +17538,7 @@ async function createGist(token, content, now = Date.now()) {
 async function updateGist(token, id, content, now = Date.now()) {
   let res;
   try {
-    res = await request(`${API}/${id}`, {
+    res = await request2(`${API}/${id}`, {
       method: "PATCH",
       headers: { ...headers(token), "content-type": "application/json" },
       body: JSON.stringify({ files: { [GIST_FILE]: { content } } })
@@ -17429,10 +17550,10 @@ async function updateGist(token, id, content, now = Date.now()) {
   }
   if (res.status === 401 || res.status === 403)
     throw new SyncError("write-denied");
-  await readJson(res);
+  await readJson2(res);
 }
 async function readGist(id, etag, now = Date.now(), token) {
-  const ask = (auth) => request(`${API}/${id}`, {
+  const ask = (auth) => request2(`${API}/${id}`, {
     headers: {
       ...headers(auth),
       ...etag ? { "if-none-match": etag } : {}
@@ -17443,7 +17564,7 @@ async function readGist(id, etag, now = Date.now(), token) {
     res = await ask();
   if (res.status === 304)
     return { changed: false };
-  const json = await readJson(res);
+  const json = await readJson2(res);
   const file = isPlainObject2(json.files) ? json.files[GIST_FILE] : undefined;
   if (!isPlainObject2(file) || typeof file.content !== "string")
     throw new SyncError("bad-blob");
@@ -18585,6 +18706,71 @@ var init_start = __esm(() => {
   init_state();
 });
 
+// src/usage-poll.ts
+import { readFile as readFile8 } from "node:fs/promises";
+async function nextPollAt(path) {
+  try {
+    const value = JSON.parse(await readFile8(path, "utf8"));
+    return isPlainObject2(value) && isFiniteNumber(value.nextPollAt) ? value.nextPollAt : 0;
+  } catch (error) {
+    if (error instanceof SyntaxError || error instanceof Error && "code" in error && error.code === "ENOENT")
+      return 0;
+    throw error;
+  }
+}
+function startUsagePoll(deps = {}) {
+  const now = deps.now ?? Date.now;
+  const refresh = deps.refresh ?? refreshAllUsageInBackground;
+  const timers = deps.timers ?? realTimers;
+  let disposed = false;
+  let inflight;
+  async function poll() {
+    const path = `${poolFilePath()}.usage-poll.json`;
+    try {
+      await withLock(`${path}.lock`, {
+        staleMs: 120000,
+        timeoutMs: 0,
+        retryMs: 25,
+        heartbeatMs: 5000
+      }, async () => {
+        const at = now();
+        if (at < await nextPollAt(path))
+          return;
+        await writeJsonAtomic(path, JSON.stringify({ nextPollAt: at + USAGE_REFRESH_TTL_MS }));
+        await refresh(at);
+      });
+    } catch (error) {
+      if (!(error instanceof LockTimeoutError))
+        throw error;
+    }
+  }
+  function tick() {
+    if (disposed)
+      return Promise.resolve();
+    inflight ??= poll().finally(() => {
+      inflight = undefined;
+    });
+    return inflight;
+  }
+  const timer = timers.set(() => void tick().catch(ignore), USAGE_REFRESH_TTL_MS);
+  return {
+    tick,
+    async dispose() {
+      disposed = true;
+      timers.clear(timer);
+      await inflight;
+    }
+  };
+}
+var init_usage_poll = __esm(() => {
+  init_lock();
+  init_paths();
+  init_store();
+  init_loop();
+  init_usage_refresh();
+  init_util2();
+});
+
 // src/legacy.ts
 function zeroOutCost(provider) {
   for (const model of Object.values(provider.models)) {
@@ -18739,8 +18925,12 @@ function createProviderPlugin(adapter) {
 }
 var PROVIDER_LABELS, AnthropicLoadBalancerPlugin, OpenAILoadBalancerPlugin, KimiCodeLoadBalancerPlugin, KimiCodeGlobalLoadBalancerPlugin, lbResult = (output) => ({ title: "Auth Load Balancer", output }), AuthLoadBalancerStatusPlugin = async (input) => {
   const sync = startSync();
+  const usage = startUsagePoll();
   return {
-    dispose: async () => sync?.dispose(),
+    dispose: async () => {
+      await usage.dispose();
+      await sync?.dispose();
+    },
     tool: {
       auth_lb_status: tool({
         description: "Show the auth load-balancer pool: the in-use account per provider, each account's weekly and 5h usage, cooldowns, and the ranked next-candidate accounts. Refreshes stale usage from the provider usage endpoints (throttled) before rendering.",
@@ -18829,6 +19019,7 @@ var init_legacy = __esm(() => {
   init_start();
   init_token_mint();
   init_types();
+  init_usage_poll();
   init_usage_refresh();
   init_util2();
   PROVIDER_LABELS = {

package/dist/providers/anthropic/usage.d.ts

@@ -17,8 +17,8 @@ export declare function sendUsageProbe(access: string): Promise<Response>;
 export declare function probeSnapshot(headers: Headers, now: number): UsageSnapshot | null;
 /**
  * Poll the dedicated usage endpoint for authoritative 5h + 7d utilization without
- * consuming inference quota. Returns null on any failure — including a 200 whose
- * body is not the usage shape — so the caller keeps the last-known snapshot.
+ * consuming inference quota. A 401 is surfaced for bounded OAuth recovery;
+ * other failures, including an invalid 200 body, keep the last-known snapshot.
  *
  * A row without a refresh token is a `claude setup-token` bearer, scoped to
  * `user:inference` alone; the endpoint demands `user:profile` and answers it