opencode-auth-load-balancer 0.9.1 → 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,8 @@ 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.
@@ -343,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(() => {
@@ -13388,7 +13413,7 @@ var init_score_core = __esm(() => {
 function reconcileQuotaCooldown(account, cfg, now) {
   if (account.cooldownKind === "auth" || account.cooldownKind === "transient")
     return;
-  if (account.cooldownUntil > now + MAX_TRANSIENT_COOLDOWN_MS && !isExhausted(account, cfg, now)) {
+  if (account.cooldownUntil > now + MAX_TRANSIENT_COOLDOWN_MS && hasHeadroom(account, cfg, now)) {
     account.cooldownUntil = 0;
     delete account.cooldownKind;
   }
@@ -13459,6 +13484,8 @@ 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,
@@ -13584,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;
@@ -13593,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
@@ -13906,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);
@@ -13932,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 };
   }
@@ -13971,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);
@@ -15569,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)));
@@ -15592,10 +15646,13 @@ async function fetchUsage2(account, now) {
     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;
@@ -15642,6 +15699,7 @@ var init_adapter3 = __esm(() => {
     },
     parseUsageHeaders: parseUsageHeaders2,
     fetchUsage: fetchUsage2,
+    reportsCredits: true,
     classifyError: classifyHttpStatus
   };
 });
@@ -15675,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);
@@ -15711,6 +15772,8 @@ async function refreshUsage(adapters, now, poolSnapshot) {
         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),
@@ -15763,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;
@@ -15831,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;
       }
@@ -16175,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 {
@@ -16191,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
   };
@@ -16209,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 };
   });
 }
@@ -16256,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;
@@ -16737,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;

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

@@ -8,11 +8,13 @@ import type { PoolAccount, UsageSnapshot } from '../../types';
  * NaN, and every comparison against NaN is false. The parse itself (null-short-circuit,
  * "no capturedAt", "`{}` collapses to null") lives in the shared
  * `parseWindowPairHeaders` — only the header names, the percent scale, and
- * this role detection are Codex-specific.
+ * this role detection are Codex-specific. The credits headers
+ * (x-codex-credits-*) ride along, even on a response without windows.
  */
 export declare function parseUsageHeaders(headers: Headers): Partial<UsageSnapshot> | null;
 /**
- * Poll GET /wham/usage for authoritative 5h + weekly utilization without
+ * Poll GET /wham/usage for authoritative 5h + weekly utilization (and the
+ * credits spent past them) without
  * consuming inference quota, assigning each returned window to its role BY
  * DURATION (see `isWeeklyMinutes`) rather than by position. A 401 is surfaced
  * for bounded OAuth recovery; other failures return null.

package/dist/providers/types.d.ts

@@ -151,6 +151,11 @@ export interface ProviderAdapter {
     parseUsageHeaders(headers: Headers): Partial<UsageSnapshot> | null;
     /** Poll a dedicated usage endpoint for authoritative quota, if one exists. */
     fetchUsage(account: PoolAccount, now: number): Promise<UsageSnapshot | null>;
+    /**
+     * The usage endpoint reports credits (Codex): a row whose credits are still
+     * unknown is polled even when its windows are fresh.
+     */
+    reportsCredits?: boolean;
     /** Classify an HTTP status for rotation decisions. */
     classifyError(status: number): ErrorClass;
     /**

package/dist/scheduler/score-core.d.ts

@@ -45,6 +45,13 @@ export interface ScoreWindow {
     utilization: number;
     resetAt: number;
 }
+/** Codex credits, which keep an account serving once its plan windows are exhausted. */
+export interface ScoreCredits {
+    hasCredits: boolean;
+    unlimited: boolean;
+    /** The credit spending cap is hit: the balance cannot be spent. */
+    limitReached?: boolean;
+}
 /**
  * The slice of an account the scoring reads. The server's full `PoolAccount` and the
  * TUI's parsed-pool account both satisfy this (the TUI normalizes its looser JSON into
@@ -55,6 +62,7 @@ export interface ScoreAccount {
         hourly: ScoreWindow | null;
         weekly: ScoreWindow | null;
     };
+    credits?: ScoreCredits;
     cooldownUntil: number;
     disabledReason: string | null;
 }
@@ -97,7 +105,15 @@ export declare function displayUtil(window: ScoreWindow | null, now: number): nu
 export declare function maxUtil(account: ScoreAccount, now: number): number;
 /** An account is exhausted when ANY still-live window is at/over the exhaustion threshold. */
 export declare function isExhausted(account: ScoreAccount, cfg: ScoreConfig, now: number): boolean;
-/** Available = not disabled, not in cooldown, and not exhausted. */
+/**
+ * Whether credits keep the account serving past exhausted plan windows. Same test as
+ * Codex itself (`unlimited || has_credits`, the backend then bills the credits), unless
+ * the account's credit spending cap is hit.
+ */
+export declare function hasCreditHeadroom(account: ScoreAccount): boolean;
+/** Plan headroom, or credits to spend once the plan is exhausted. */
+export declare function hasHeadroom(account: ScoreAccount, cfg: ScoreConfig, now: number): boolean;
+/** Available = not disabled, not in cooldown, and with plan or credit headroom. */
 export declare function isAvailable(account: ScoreAccount, cfg: ScoreConfig, now: number): boolean;
 /**
  * Weekly "urgency" — how perishable an account's remaining weekly quota is. It favors
@@ -150,18 +166,21 @@ export declare function scoreAccount(account: ScoreAccount, cfg: ScoreConfig, no
  * Sort comparator shared by `src/status.ts` and the TUI sidebar ranking pipeline, so the
  * dashboard's *ordering* rule can never silently drift from what the server displays —
  * the same single-source guarantee `scoreAccount` provides for the *formula*. Both
- * pipelines map each account into `{ available, score, weeklyUtil }` (the per-pipeline
- * `weeklyUtil` field is computed locally — `src/status.ts` uses the raw stored value to
- * keep tie-breaking deterministic for cooling-down accounts, the TUI uses `utilOf` to
- * discard a window that already reset) and pass that shape here:
+ * pipelines map each account into `{ available, onCredits, score, weeklyUtil }` (the
+ * per-pipeline `weeklyUtil` field is computed locally — `src/status.ts` uses the raw
+ * stored value to keep tie-breaking deterministic for cooling-down accounts, the TUI uses
+ * `utilOf` to discard a window that already reset) and pass that shape here:
  *
  *   - available accounts come first (they're the only ones the scheduler will pick);
- *   - among available accounts, higher `score` wins (matches `selectAccount`'s pick);
+ *   - among available accounts, plan headroom comes before serving on credits alone
+ *     (`onCredits`: credits cost money), then higher `score` wins (matches
+ *     `selectAccount`'s pick);
  *   - among unavailable accounts, lower `weeklyUtil` wins — the "least bad cooling-down
  *     account" surfaces first so a forced fall-through stays predictable.
  */
 export declare function compareRanked<T extends {
     available: boolean;
+    onCredits: boolean;
     score: number;
     weeklyUtil: number;
 }>(x: T, y: T): number;

package/dist/scheduler/select.d.ts

@@ -13,10 +13,13 @@ export interface Selection {
  * 1. Restrict to the provider's non-disabled accounts, minus `exclude` (already
  *    tried this request).
  * 2. Prefer the subset that is currently available (not exhausted / cooling down).
- * 3. Among those, pick the highest urgency score — but KEEP the incumbent
- *    (`incumbentId`, the provider's current in-use account) when its score is
- *    within `INCUMBENT_HYSTERESIS` of the best, so near-equal scores don't churn
- *    the account and waste prompt cache.
+ * 3. Among those, prefer plan headroom over serving on credits alone (an
+ *    exhausted Codex account whose credits keep it usable — credits cost money,
+ *    plan quota is already paid for), then pick the highest urgency score — but
+ *    KEEP the incumbent (`incumbentId`, the provider's current in-use account)
+ *    when it is in that same group and its score is within
+ *    `INCUMBENT_HYSTERESIS` of the best, so near-equal scores don't churn the
+ *    account and waste prompt cache.
  * 4. If none are available, fall back to the least-bad account (lowest weekly
  *    utilization) and flag the selection as `degraded`.
  *

package/dist/status.d.ts

@@ -18,6 +18,8 @@ interface AccountStatus {
     warnings: string[];
     /** Why each lost login stopped working, printed under the table. */
     lostNotes: string[];
+    /** What credits leave once the plan is exhausted (`creditsText`); '' otherwise. */
+    credits: string;
     /** The account that most recently served a request for this provider. */
     current: boolean;
     /** 1 = next candidate the scheduler would pick. */

package/dist/types.d.ts

@@ -9,6 +9,18 @@ export interface UsageWindow {
     utilization: number;
     resetAt: number;
 }
+/**
+ * Codex credits: what a ChatGPT account spends once its plan's usage windows
+ * are exhausted. `balance` is the amount left, when the backend reports it;
+ * `limitReached` (`overage_limit_reached`) means the account's credit
+ * spending cap is hit, so the balance cannot be spent.
+ */
+export interface UsageCredits {
+    hasCredits: boolean;
+    unlimited: boolean;
+    balance?: number;
+    limitReached?: boolean;
+}
 /** Normalized usage snapshot for one account. */
 export interface UsageSnapshot {
     /** Short rolling window (~5h for both Anthropic and Codex). */
@@ -23,6 +35,11 @@ export interface UsageSnapshot {
      * snapshot fresh, or an out-of-band weekly reset is never picked up.
      */
     capturedAt: number;
+    /**
+     * Codex credits as just measured. Stored on the row (`PoolAccount.credits`),
+     * not here: versions before credits rebuild `usage` and would drop them.
+     */
+    credits?: UsageCredits;
 }
 export declare function emptyUsage(): UsageSnapshot;
 /** Result of an OAuth authorization-code exchange or refresh. */
@@ -142,6 +159,8 @@ export interface PoolAccount {
      */
     orgId?: string;
     usage: UsageSnapshot;
+    /** Codex credits, absent until the provider reports them. */
+    credits?: UsageCredits;
     /** epoch ms; the account is skipped until this time. 0 = no cooldown. */
     cooldownUntil: number;
     /** Why the active account-wide cooldown was written. Absent on legacy rows. */