@bitkyc08/opencodex 2.76.0 → 2.77.0

package/src/codex/main-account.ts

@@ -1,11 +1,15 @@
+import { classifyChatgptRefreshFailure, noteChatgptRefreshFailure } from "./chatgpt-refresh-failure";
+import { readBoundedResponseBody } from "../lib/bounded-body";
 import { createHash } from "node:crypto";
 import { readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { readCodexTokens } from "./auth-collision";
 import {
+  CHATGPT_CLIENT_ID,
+  CHATGPT_TOKEN_URL,
+  credsFromToken,
   decodeJwtPayload,
   extractAccountId,
-  refreshChatGPTToken,
 } from "../oauth/chatgpt";
 import type { OAuthCredentials } from "../oauth/types";
 import { extractChatgptPlanType } from "./plan";
@@ -17,7 +21,12 @@ import {
 import { atomicWriteFile, resolveWriteTarget } from "../config/atomic-write";
 import { resolveCodexHomeDir } from "./home";
 import { assertNotRealCodexHomeUnderTest } from "../lib/test-home-guard";
-import { clearAccountNeedsReauth } from "./account-runtime-state";
+import {
+  clearAccountNeedsReauth,
+  isMainRefreshGrantRejected,
+  markMainRefreshGrantRejected,
+  clearMainRefreshGrantRejection,
+} from "./account-runtime-state";
 import { advanceCodexCredentialMutationEpoch } from "./credential-mutation-epoch";
 import { withNativeMainExclusiveClaim } from "./native-main-claim";
 import { resolveNativeProfileContext } from "./native-profile-store";
@@ -78,6 +87,68 @@ export class MainAccountTokenRefreshError extends Error {
   }
 }
 
+/**
+ * The native-main refresh, posted here rather than through `refreshChatGPTToken` so the token
+ * endpoint's structured `error` code survives to {@link classifyChatgptRefreshFailure}.
+ *
+ * `refreshChatGPTToken` collapses the refusal into one display string, and classifying a grant
+ * from that string is what let `refresh_token_reused` pass as transient -- the grant never
+ * retired, every request re-earning its own 401 -- while a 5xx whose description merely read
+ * "session expired" passed as proof and would have retired a live grant.
+ *
+ * Same endpoint, client id and grant type as every other ChatGPT refresh, and the success path
+ * is `credsFromToken` itself, so only the failure branch differs: it classifies by code, exactly
+ * as the stored-pool refresh does.
+ */
+async function refreshNativeMainGrant(
+  refreshToken: string,
+  options: { signal: AbortSignal },
+): Promise<OAuthCredentials> {
+  const resp = await fetch(CHATGPT_TOKEN_URL, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      grant_type: "refresh_token",
+      client_id: CHATGPT_CLIENT_ID,
+      refresh_token: refreshToken,
+    }).toString(),
+    signal: options.signal,
+  });
+  if (!resp.ok) {
+    const body = await readBoundedResponseBody(resp, { signal: options.signal, maxBytes: 16_384, fatalUtf8: true })
+      .catch(() => undefined);
+    const failure = classifyChatgptRefreshFailure(resp.status, body?.displaySafe ? body.text : "");
+    noteChatgptRefreshFailure("native main", resp.status, failure);
+    throw new MainAccountTokenRefreshError(failure.reason === "unknown" ? "transient" : "reauth");
+  }
+  let credentials: OAuthCredentials;
+  try {
+    credentials = credsFromToken((await resp.json()) as Record<string, unknown>);
+  } catch {
+    if (options.signal.aborted) throw options.signal.reason;
+    noteNativeMainRefresh("transient", resp.status);
+    // Parsing errors may include provider body text; retain only the fixed verdict.
+    throw new MainAccountTokenRefreshError("transient");
+  }
+  noteNativeMainRefresh("ok", resp.status);
+  return credentials;
+}
+
+/**
+ * One line per native-main refresh verdict, so a dead grant is diagnosable from service.log.
+ *
+ * A revoked session is invisible from the outside: the grant is refused, nothing is written, and
+ * the request fails with a status that looks like every other 401. Carries the token endpoint's
+ * HTTP status and its structured `error` code and nothing else -- never a token, never a body.
+ */
+function noteNativeMainRefresh(outcome: string, status?: number, code?: string): void {
+  console.warn(
+    `[codex] native main refresh: ${outcome}`
+      + (status === undefined ? "" : ` status=${status}`)
+      + ` code=${code && /^[A-Za-z0-9._-]{1,64}$/.test(code) ? code : "none"}`,
+  );
+}
+
 function nonEmptyString(value: unknown): string | undefined {
   return typeof value === "string" && value.trim() ? value : undefined;
 }
@@ -147,13 +218,45 @@ function mainAccessTokenFresh(accessToken: string | undefined, now: number, skew
 }
 
 /** A refresh grant makes native main routeable even when the current access token is expired. */
-export function isMainAccountCredentialUsable(now = Date.now()): boolean {
+function mainRefreshGrantKey(current: MainAuthJsonCredential): string | undefined {
+  return current.refreshToken
+    ? `${current.path}:${refreshGrantFingerprintForToken(current.refreshToken)}` : undefined;
+}
+
+function credentialRefreshGrantRejected(current: MainAuthJsonCredential | null): boolean {
+  const key = current && mainRefreshGrantKey(current);
+  return !!key && isMainRefreshGrantRejected(key);
+}
+
+export interface MainAccountCredentialStatus {
+  refreshGrantRejected: boolean;
+  hasRefreshGrant: boolean;
+  usable: boolean;
+}
+
+/** One owned physical observation; no credential material escapes this view. */
+export function getMainAccountCredentialStatus(now = Date.now()): MainAccountCredentialStatus {
   const current = readMainAuthJsonCredential();
-  return !!current?.refreshToken || mainAccessTokenFresh(current?.accessToken, now, 0);
+  const refreshGrantRejected = credentialRefreshGrantRejected(current);
+  const hasRefreshGrant = !!current?.refreshToken && !refreshGrantRejected;
+  return {
+    refreshGrantRejected,
+    hasRefreshGrant,
+    usable: !refreshGrantRejected && (hasRefreshGrant || mainAccessTokenFresh(current?.accessToken, now, 0)),
+  };
+}
+
+/** Current owned profile only; callers must hold the native read/selection permission. */
+export function isMainAccountRefreshGrantRejected(): boolean {
+  return getMainAccountCredentialStatus().refreshGrantRejected;
+}
+
+export function isMainAccountCredentialUsable(now = Date.now()): boolean {
+  return getMainAccountCredentialStatus(now).usable;
 }
 
 export function hasMainAccountRefreshGrant(): boolean {
-  return !!readMainAuthJsonCredential()?.refreshToken;
+  return getMainAccountCredentialStatus().hasRefreshGrant;
 }
 
 function assertMainAuthJsonSnapshotUnchanged(expected: MainAuthJsonCredential): void {
@@ -342,14 +445,26 @@ async function resolveMainAccountToken(
   dependencies: NativeMainRefreshDependencies = {},
   rejectedAccessToken?: string,
 ): Promise<{ accessToken: string; chatgptAccountId: string } | null> {
+  if (dependencies.signal?.aborted) throw dependencies.signal.reason;
   const initial = readMainAuthJsonCredential();
-  if (!initial) return null;
+  // Every skip below ends a forced refresh WITHOUT asking the token endpoint anything, which from
+  // the outside is indistinguishable from a refusal: same failed request, no write, no verdict.
+  // A forced refresh is the only caller that passes `rejectedAccessToken`, so only it reports.
+  if (!initial) {
+    if (rejectedAccessToken !== undefined) noteNativeMainRefresh("skipped-no-credential");
+    return null;
+  }
+  if (credentialRefreshGrantRejected(initial)) throw new MainAccountTokenRefreshError("reauth");
   const now = Date.now();
   if (initial.accessToken !== rejectedAccessToken
     && mainAccessTokenFresh(initial.accessToken, now, MAIN_TOKEN_REFRESH_SKEW_MS)) {
+    // The stored credential is no longer the one upstream rejected: somebody else replaced it
+    // while this request was in flight, so there is nothing here to refresh or to retire.
+    if (rejectedAccessToken !== undefined) noteNativeMainRefresh("skipped-credential-replaced");
     return { accessToken: initial.accessToken!, chatgptAccountId: initial.chatgptAccountId };
   }
   if (!initial.refreshToken) {
+    if (rejectedAccessToken !== undefined) noteNativeMainRefresh("skipped-no-refresh-grant");
     return initial.accessToken !== rejectedAccessToken
       && mainAccessTokenFresh(initial.accessToken, now, 0)
       ? { accessToken: initial.accessToken!, chatgptAccountId: initial.chatgptAccountId }
@@ -380,6 +495,7 @@ async function resolveMainAccountToken(
       () => withCodexRefreshFileLock(lockKey, signal, async () => {
         const locked = readMainAuthJsonCredential();
         if (!locked) throw new MainAuthJsonChangedDuringRefreshError();
+        if (credentialRefreshGrantRejected(locked)) throw new MainAccountTokenRefreshError("reauth");
         if (!locked.refreshToken
           || refreshGrantFingerprintForToken(locked.refreshToken) !== lockKey) {
           if (locked.accessToken !== rejectedAccessToken
@@ -392,16 +508,31 @@ async function resolveMainAccountToken(
           && mainAccessTokenFresh(locked.accessToken, Date.now(), MAIN_TOKEN_REFRESH_SKEW_MS)) {
           return { accessToken: locked.accessToken!, chatgptAccountId: locked.chatgptAccountId };
         }
-        const refresh = dependencies.refreshToken
-          ?? ((refreshToken: string, options: { signal: AbortSignal }) => refreshChatGPTToken(refreshToken, options));
+        const refresh = dependencies.refreshToken ?? refreshNativeMainGrant;
         let refreshed: OAuthCredentials;
         try {
           refreshed = await refresh(locked.refreshToken, { signal });
         } catch (cause) {
+          // A refusal already classified at the endpoint keeps that verdict. An injected refresh
+          // threw an ordinary Error and has only its message, so prose still decides there --
+          // and only there, where there is no structured code to read.
           const message = cause instanceof Error ? cause.message.toLowerCase() : "";
-          const reason = /invalid_grant|invalidated|revoked|expired/.test(message)
-            ? "reauth" as const
-            : "transient" as const;
+          const reason = cause instanceof MainAccountTokenRefreshError
+            ? cause.reason
+            : dependencies.refreshToken && /invalid_grant|invalidated|revoked|expired/.test(message)
+              ? "reauth" as const
+              : "transient" as const;
+          // The shared point every request path reaches a terminal native-main verdict through:
+          // the forced refresh after an upstream 401, the pre-send refresh of an expired bearer,
+          // and the compact twin all land here. Recording the quarantine at the callers instead
+          // left the native main slot alone unrecorded -- `refreshNativeMainForwardAuth` has no
+          // `quarantine` flag for its caller to act on the way the stored-pool twin does -- so a
+          // revoked session stayed `needsReauth: false` and every request re-earned its own 401.
+          if (signal.aborted) throw signal.reason;
+          if (reason === "reauth") {
+            assertMainAuthJsonSnapshotUnchanged(locked);
+            markMainRefreshGrantRejected(mainRefreshGrantKey(locked)!);
+          }
           throw new MainAccountTokenRefreshError(reason, { cause });
         }
         // The refresh may resolve after the caller went away (an implementation that does
@@ -411,6 +542,8 @@ async function resolveMainAccountToken(
         // before its own commit above.
         if (dependencies.signal?.aborted) throw dependencies.signal.reason;
         const result = persistRefreshedMainAuthJson(locked, refreshed);
+        // A permitted in-flight success speaks only for its own profile and grant.
+        clearMainRefreshGrantRejection(mainRefreshGrantKey(locked)!);
         if (dependencies.preserveReauth !== true) clearAccountNeedsReauth(MAIN_CODEX_ACCOUNT_ID);
         return result;
       }),

package/src/codex/quota-refresh-outcome.ts

@@ -1,8 +1,22 @@
 /** Diagnostic only: never use this outcome as quota, entitlement, or admission evidence. */
 export type CodexQuotaRefreshOutcome =
-  | { status: "http_error"; httpStatus: number }
+  /** `code` is set only for a provider code that requires a new sign-in (fixed vocabulary). */
+  | { status: "http_error"; httpStatus: number; code?: CodexTerminalAuthCode }
   | { status: "ok" | "not_reported" | "timeout" | "network_error" | "invalid_response" | "internal_error" };
 
+/** Provider auth codes that only a new sign-in can recover. */
+export const CODEX_TERMINAL_AUTH_CODES = [
+  "invalid_workspace_selected",
+  "invalid_refresh_token",
+  // ChatGPT revokes every session of an account whose plan changes (for example Pro to Free),
+  // while the access token's `exp` still lies in the future.
+  "token_invalidated",
+] as const;
+export type CodexTerminalAuthCode = typeof CODEX_TERMINAL_AUTH_CODES[number];
+export function isCodexTerminalAuthCode(code: unknown): code is CodexTerminalAuthCode {
+  return (CODEX_TERMINAL_AUTH_CODES as readonly unknown[]).includes(code);
+}
+
 /** The management response is untrusted at the CLI boundary; copy only the fixed vocabulary. */
 export function projectCodexQuotaRefreshOutcome(value: unknown): CodexQuotaRefreshOutcome | undefined {
   if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
@@ -10,7 +24,8 @@ export function projectCodexQuotaRefreshOutcome(value: unknown): CodexQuotaRefre
   if (row.status === "http_error") {
     return typeof row.httpStatus === "number" && Number.isInteger(row.httpStatus)
       && row.httpStatus >= 100 && row.httpStatus <= 599
-      ? { status: "http_error", httpStatus: row.httpStatus }
+      ? { status: "http_error", httpStatus: row.httpStatus,
+        ...(isCodexTerminalAuthCode(row.code) ? { code: row.code } : {}) }
       : undefined;
   }
   switch (row.status) {

package/src/codex/quota-types.ts

@@ -22,6 +22,31 @@ export const TERMINAL_SHORT_WINDOW_FRESHNESS_MS = 5 * 60_000;
  */
 export const CODEX_EXHAUSTED_USAGE_PERCENT = 100;
 
+/** Credits have a separate clock: ordinary usage headers do not re-observe the balance. */
+export const CODEX_CREDITS_FRESHNESS_MS = 5 * 60_000;
+
+export interface CodexSpendableCredits {
+  hasCredits?: boolean;
+  unlimited?: boolean;
+  balance?: number;
+  overageLimitReached?: boolean;
+  allowed?: boolean;
+  observedAt: number;
+}
+
+export function hasSpendableCodexCredits(
+  quota: Pick<StoredAccountQuota, "credits"> | null,
+  now = Date.now(),
+): boolean {
+  const credits = quota?.credits;
+  if (!credits || !Number.isFinite(credits.observedAt)) return false;
+  const age = now - credits.observedAt;
+  if (age < 0 || age > CODEX_CREDITS_FRESHNESS_MS
+    || credits.allowed === false || credits.overageLimitReached === true || credits.hasCredits === false) return false;
+  return credits.unlimited === true || (credits.hasCredits === true
+    && typeof credits.balance === "number" && Number.isFinite(credits.balance) && credits.balance > 0);
+}
+
 /**
  * Above this a value is already milliseconds; at or below it, it is Unix seconds.
  *
@@ -80,6 +105,8 @@ export type StoredAccountQuota = {
   shortWindowSeconds?: number;
   customWindows?: Array<{ label: string; percent: number; resetAt?: number }>;
   resetCredits?: number;
+  /** Spendable usage credits; resetCredits are separate, manually redeemed reset tickets. */
+  credits?: CodexSpendableCredits | null;
   /** Monthly usage came from an explicitly monthly PRIMARY, not supplementary tertiary, window. */
   monthlyIsPrimaryWindow?: boolean;
   updatedAt: number;
@@ -114,7 +141,12 @@ export type WhamUsageResponse = {
     secondary_window?: WhamUsageWindow | null;
     tertiary_window?: WhamUsageWindow | null;
   };
-  credits?: unknown;
+  credits?: {
+    has_credits?: unknown;
+    unlimited?: unknown;
+    balance?: unknown;
+    overage_limit_reached?: unknown;
+  } | null;
   rate_limit_reset_credits?: { available_count: number } | null;
   additional_rate_limits?: WhamAdditionalRateLimit[] | null;
 };

package/src/codex/quota.ts

@@ -1,3 +1,4 @@
+import { parseCodexCredits } from "./credits";
 import { forgetMainAccountUsage, observeMainAccountUsage, type FreshWindow } from "./main-account-external-usage";
 import { closeSync, constants as fsConstants, existsSync, fstatSync, openSync, readSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
@@ -11,7 +12,7 @@ import { getObservedMainQuotaIdentityKey, isMainQuotaWriterLive, type MainQuotaW
 
 import { CodexQuotaHistory, QUOTA_HISTORY_LIMITS, type QuotaHistoryWindow } from "./quota-history";
 import { isPoolQuotaWriterLive, poolQuotaHistoryIdentity } from "./account-store";
-import { CODEX_EXHAUSTED_USAGE_PERCENT, MAIN_ACCOUNT_HARD_LOCK_MIN_PERCENT, resetAtToMs } from "./quota-types";
+import { CODEX_EXHAUSTED_USAGE_PERCENT, MAIN_ACCOUNT_HARD_LOCK_MIN_PERCENT, hasSpendableCodexCredits, resetAtToMs } from "./quota-types";
 import type { PoolQuotaWriter, StoredAccountQuota, WhamUsageResponse, WhamUsageWindow } from "./quota-types";
 
 export type { StoredAccountQuota, WhamUsageResponse } from "./quota-types";
@@ -83,10 +84,12 @@ function mayCommitAccountQuota(accountId: string, writerGeneration: number): boo
 // actually exhausted account is still eligible for threshold rotation.
 export const CODEX_UNKNOWN_USAGE_SCORE = 101;
 export function isCodexQuotaExhausted(
-  quota: Pick<StoredAccountQuota, "weeklyPercent" | "monthlyPercent" | "shortPercent"> | null,
+  quota: Pick<StoredAccountQuota, "weeklyPercent" | "monthlyPercent" | "shortPercent" | "credits"> | null,
   plan?: unknown,
+  allowCredits = false,
 ): boolean {
   if (!quota) return false;
+  if (allowCredits && hasSpendableCodexCredits(quota)) return false;
   // The burst window counts on EVERY plan. It is upstream-enforced independently, so an
   // account at 100% there is blocked regardless of which longer window governs its plan;
   // omitting it would route traffic straight into a 429 (#1791).
@@ -118,10 +121,11 @@ export function codexQuotaWindowForPlan(plan?: unknown): "monthly" | "weekly" {
 }
 
 export function isCompleteCodexQuotaRecoverySnapshot(
-  quota: Pick<StoredAccountQuota, "weeklyPercent" | "monthlyPercent" | "monthlyIsPrimaryWindow" | "shortPercent"> | null,
+  quota: Pick<StoredAccountQuota, "weeklyPercent" | "monthlyPercent" | "monthlyIsPrimaryWindow" | "shortPercent" | "credits"> | null,
   plan?: unknown,
+  allowCredits = false,
 ): boolean {
-  if (!quota || isCodexQuotaExhausted(quota, plan)) return false;
+  if (!quota || isCodexQuotaExhausted(quota, plan, allowCredits)) return false;
   // Recovery still fails closed on MISSING EVIDENCE — a credits-only or windowless payload
   // carries no usage reading at all and must never clear a cooldown. What it does not do is
   // fail closed on an unfamiliar plan NAME, which only ever meant "cooled forever".
@@ -277,6 +281,10 @@ function snapshotHasCustom(quota: Omit<StoredAccountQuota, "updatedAt">): boolea
 function snapshotHasUsage(quota: Omit<StoredAccountQuota, "updatedAt">): boolean {
   return snapshotHasWeekly(quota) || snapshotHasMonthly(quota) || snapshotHasShort(quota) || snapshotHasCustom(quota);
 }
+
+function snapshotHasCredits(quota: Omit<StoredAccountQuota, "updatedAt">): boolean {
+  return quota.resetCredits !== undefined || quota.credits !== undefined;
+}
 /**
  * Publish parsed display quota and separately validated policy evidence after writer checks.
  * A null policy observation retains only the matching main identity's previous evidence;
@@ -296,7 +304,7 @@ export function setAccountQuotaFromParsed(
 ): void {
   quota = withoutRetiredCodexQuota(quota);
   policyQuota = withoutRetiredCodexQuota(policyQuota);
-  if (!quota || (!snapshotHasUsage(quota) && quota.resetCredits === undefined)) return;
+  if (!quota || (!snapshotHasUsage(quota) && !snapshotHasCredits(quota))) return;
   if (!mayCommitAccountQuota(accountId, writerGeneration)) return;
   const isMain = accountId === MAIN_CODEX_ACCOUNT_ID;
   if (isMain && mainWriter && !isMainQuotaWriterLive(mainWriter)) return;
@@ -343,7 +351,7 @@ export function setAccountQuotaFromParsed(
   }
   schedulePersistAccountQuotas();
   // Credits carry the previous usage tuple; they must not refresh its observation clock.
-  if (!(quota.resetCredits !== undefined && !snapshotHasUsage(quota))) {
+  if (!(snapshotHasCredits(quota) && !snapshotHasUsage(quota))) {
     if (!isMain && policyQuota && livePoolEvidence) observeCodexLowQuota(accountId, policyQuota);
     notifyCodexQuotaSnapshot(accountId, next);
   }
@@ -363,7 +371,11 @@ function mergeAccountQuota(
   quota = withoutRetiredCodexQuota(quota) ?? {};
   existing = withoutRetiredCodexQuota(existing ?? null) ?? undefined;
   const next: StoredAccountQuota = { updatedAt };
-  const creditsOnly = quota.resetCredits !== undefined && !snapshotHasUsage(quota);
+  const creditsOnly = snapshotHasCredits(quota) && !snapshotHasUsage(quota);
+  // An explicit empty/invalid credits summary retracts the old balance. Partial headers
+  // retain the original observation clock instead of extending its spending authority.
+  if (quota.credits !== undefined) next.credits = quota.credits;
+  else if (existing?.credits !== undefined) next.credits = existing.credits;
 
   if (creditsOnly) {
     if (existing?.weeklyPercent !== undefined) next.weeklyPercent = existing.weeklyPercent;
@@ -373,7 +385,8 @@ function mergeAccountQuota(
     if (existing?.monthlyIsPrimaryWindow === true) next.monthlyIsPrimaryWindow = true;
     assignCarriedShort(next, existing, updatedAt, policyEvidence);
     if (existing?.customWindows !== undefined) next.customWindows = existing.customWindows;
-    next.resetCredits = quota.resetCredits;
+    if (quota.resetCredits !== undefined) next.resetCredits = quota.resetCredits;
+    else if (existing?.resetCredits !== undefined) next.resetCredits = existing.resetCredits;
     return stampCodexQuotaUsageObservation(next, quota, existing);
   }
 
@@ -525,7 +538,7 @@ export function withoutRetiredCodexQuota<T extends Omit<StoredAccountQuota, "upd
   const next = { ...quota };
   if (kept.length > 0) next.customWindows = kept;
   else delete next.customWindows;
-  return snapshotHasUsage(next) || next.resetCredits !== undefined ? next as T : null;
+  return snapshotHasUsage(next) || snapshotHasCredits(next) ? next as T : null;
 }
 
 export function parseUpstreamQuotaHeaders(headers: Headers, options?: { modelId?: string }): Omit<StoredAccountQuota, "updatedAt"> | null {
@@ -644,6 +657,7 @@ export function updateAccountQuota(
     ...(existing?.monthlyResetAt !== undefined ? { monthlyResetAt: existing.monthlyResetAt } : {}),
     ...(existing?.customWindows !== undefined ? { customWindows: existing.customWindows } : {}),
     ...(existing?.resetCredits !== undefined ? { resetCredits: existing.resetCredits } : {}),
+    ...(existing?.credits !== undefined ? { credits: existing.credits } : {}),
     updatedAt: Date.now(),
   };
   assignCarriedShort(quota, existing, quota.updatedAt);
@@ -702,6 +716,20 @@ function readMainPolicyQuota(value: unknown): MainPolicyQuota | null {
     if (typeof number === "number" && Number.isFinite(number) && number >= 0) quota[field] = number;
   }
   if (quota.monthlyPercent !== undefined && raw.monthlyIsPrimaryWindow === true) quota.monthlyIsPrimaryWindow = true;
+  // Retain the independent credit timestamp on restart; it still expires at its original deadline.
+  if (raw.credits === null) quota.credits = null;
+  else if (raw.credits && typeof raw.credits === "object" && !Array.isArray(raw.credits)) {
+    const stored = raw.credits as Record<string, unknown>;
+    if (typeof stored.observedAt === "number" && Number.isFinite(stored.observedAt) && stored.observedAt >= 0) {
+      quota.credits = { observedAt: stored.observedAt };
+      for (const key of ["hasCredits", "unlimited", "overageLimitReached", "allowed"] as const) {
+        if (typeof stored[key] === "boolean") quota.credits[key] = stored[key];
+      }
+      if (typeof stored.balance === "number" && Number.isFinite(stored.balance) && stored.balance >= 0) {
+        quota.credits.balance = stored.balance;
+      }
+    }
+  }
   return { identityKey: entry.identityKey, quota };
 }
 
@@ -845,7 +873,7 @@ function filterMainPolicyMonthlyQuota(
   delete filtered.monthlyResetAt;
   delete filtered.monthlyIsPrimaryWindow;
   // Null retains the matching prior observation; an empty object would merge away evidence.
-  return hasKnownQuotaValue(filtered) || filtered.resetCredits !== undefined ? filtered : null;
+  return hasKnownQuotaValue(filtered) || snapshotHasCredits(filtered) ? filtered : null;
 }
 
 /**
@@ -886,11 +914,24 @@ export function parseUsageQuota(data: WhamUsageResponse): Omit<StoredAccountQuot
     ? data.rate_limit_reset_credits.available_count
     : undefined;
 
-  if (!data.rate_limit) {
-    return resetCredits !== undefined ? { resetCredits } : null;
-  }
-
   const quota: Omit<StoredAccountQuota, "updatedAt"> = {};
+  if (resetCredits !== undefined) quota.resetCredits = resetCredits;
+  if (data.credits !== undefined) {
+    quota.credits = null;
+    const parsed = parseCodexCredits(data.credits);
+    if (parsed) {
+      const balance = parsed.balance === undefined ? undefined : Number(parsed.balance);
+      quota.credits = {
+        observedAt: Date.now(),
+        ...(parsed.hasCredits !== undefined ? { hasCredits: parsed.hasCredits } : {}),
+        ...(parsed.unlimited !== undefined ? { unlimited: parsed.unlimited } : {}),
+        ...(parsed.overageLimitReached !== undefined ? { overageLimitReached: parsed.overageLimitReached } : {}),
+        ...(typeof data.rate_limit?.allowed === "boolean" ? { allowed: data.rate_limit.allowed } : {}),
+        ...(balance !== undefined && Number.isFinite(balance) ? { balance } : {}),
+      };
+    }
+  } else if (data.rate_limit?.allowed === false) quota.credits = null;
+  if (!data.rate_limit) return snapshotHasCredits(quota) ? quota : null;
   const thirtyDayOnly = codexQuotaWindowForPlan(data.plan_type) === "monthly";
   const primaryWindow = data.rate_limit.primary_window;
   const secondaryWindow = data.rate_limit.secondary_window;
@@ -951,7 +992,7 @@ export function parseUsageQuota(data: WhamUsageResponse): Omit<StoredAccountQuot
 
   if (resetCredits !== undefined) quota.resetCredits = resetCredits;
 
-  return hasKnownQuotaValue(quota) || resetCredits !== undefined ? quota : null;
+  return hasKnownQuotaValue(quota) || snapshotHasCredits(quota) ? quota : null;
 }
 
 

package/src/codex/routing/cooldown-math.ts

@@ -3,7 +3,7 @@ import {
   CODEX_UNKNOWN_USAGE_SCORE,
 } from "../quota";
 import { isThirtyDayOnlyCodexPlan } from "../plan";
-import { isTerminalShortWindow } from "../quota-types";
+import { hasSpendableCodexCredits, isTerminalShortWindow, type CodexSpendableCredits } from "../quota-types";
 import type { CodexQuotaScope } from "./health-store";
 import type { TransientProbeGrant } from "./thread-affinity";
 
@@ -107,7 +107,8 @@ export function computeCodexUsageScore(quota: {
   shortPercent?: number;
   shortResetAt?: number;
   shortObservedAt?: number;
-} | null, plan?: unknown, now: number = Date.now()): number {
+  credits?: CodexSpendableCredits | null;
+} | null, plan?: unknown, now: number = Date.now(), allowCredits = false): number {
   if (!quota) return CODEX_UNKNOWN_USAGE_SCORE;
   const finite = (value: unknown): value is number => typeof value === "number" && Number.isFinite(value);
   const longWindows = isThirtyDayOnlyCodexPlan(plan)
@@ -126,10 +127,15 @@ export function computeCodexUsageScore(quota: {
   // correct for uncertainty and wrong for a measured refusal: the account stays selected,
   // `applyQuotaAutoSwitch` never fires, and the pool wedges on an exhausted credential.
   if (knownLong.length === 0) {
-    return isTerminalShortWindow(quota, now) ? CODEX_EXHAUSTED_USAGE_PERCENT : CODEX_UNKNOWN_USAGE_SCORE;
+    return isTerminalShortWindow(quota, now)
+      ? (allowCredits && hasSpendableCodexCredits(quota, now)) ? CODEX_EXHAUSTED_USAGE_PERCENT - 1 : CODEX_EXHAUSTED_USAGE_PERCENT
+      : CODEX_UNKNOWN_USAGE_SCORE;
   }
   const values = finite(quota.shortPercent) ? [...knownLong, quota.shortPercent] : knownLong;
-  return Math.max(...values);
+  const score = Math.max(...values);
+  // Keep included-capacity accounts ahead of a paid overage account, but do not
+  // classify the latter as exhausted solely from its subscription percentages.
+  return (allowCredits && hasSpendableCodexCredits(quota, now)) ? Math.min(score, CODEX_EXHAUSTED_USAGE_PERCENT - 1) : score;
 }
 
 // `isTerminalShortWindow` moved to ../quota-types, the leaf the dashboard can import. Routing

package/src/codex/routing/selection.ts

@@ -1,5 +1,5 @@
 import { getEffectiveCodexAutoSwitchThreshold } from "../account-auto-switch";
-import { isCodexAccountHeldForCredits } from "../account-credit-use";
+import { codexAccountUsesCreditsAfterLimit, isCodexAccountHeldForCredits } from "../account-credit-use";
 import { isCodexAccountPaused } from "../account-pause";
 import { codexAccountPriorityLookup, pinnedCodexAccountId } from "../account-priority";
 import { isSelectableCodexPoolAccount } from "../account-id";
@@ -16,7 +16,7 @@ import {
 } from "../pool-rotation";
 import { CODEX_UNKNOWN_USAGE_SCORE, getAccountQuota, resetAtToMs } from "../quota";
 import { codexPlanKey } from "../plan";
-import { MAIN_CODEX_ACCOUNT_ID, getMainAccountPlan, hasMainAccountRefreshGrant } from "../main-account";
+import { MAIN_CODEX_ACCOUNT_ID, getMainAccountPlan } from "../main-account";
 import type { OcxConfig } from "../../types";
 import { CODEX_FAILURE_WINDOW_MS, computeCodexUsageScore } from "./cooldown-math";
 import {
@@ -220,7 +220,6 @@ export function getEligiblePoolAccounts(
   if (
     excludeId !== MAIN_CODEX_ACCOUNT_ID
     && !isCodexAccountPaused(config, MAIN_CODEX_ACCOUNT_ID)
-    && (!isAccountNeedsReauth(MAIN_CODEX_ACCOUNT_ID) || hasMainAccountRefreshGrant())
     && getCodexQuotaHealthSnapshot(MAIN_CODEX_ACCOUNT_ID, quotaScope, now) === null
     && !isCodexAccountSoftAvoided(MAIN_CODEX_ACCOUNT_ID, now)
     // The main login is not in `config.codexAccounts`, so it never passes through the
@@ -293,6 +292,7 @@ export function hasCodexQuotaHeadroom(
     getAccountQuota(accountId),
     getPoolAccountPlanForSelection(config, accountId, selectionOptions),
     now,
+    codexAccountUsesCreditsAfterLimit(config, accountId),
   );
   if (isUnknownUsage(usage)) return true;
   return usage < threshold;
@@ -344,6 +344,7 @@ export function hasCodexSharedStateQuotaHeadroom(
     getAccountQuota(accountId),
     getPoolAccountPlanForSelection(config, accountId, selectionOptions),
     now,
+    codexAccountUsesCreditsAfterLimit(config, accountId),
   );
   return isUnknownUsage(usage) || usage < 100;
 }
@@ -537,7 +538,7 @@ export function sharedStateSelectionOptions(
   selectionOptions?: CodexAccountUsabilityOptions,
 ): Pick<
   CodexAccountUsabilityOptions,
-  "nativeMainSelectionOnly" | "isMainAccountTokenLive"
+  "nativeMainSelectionOnly" | "isMainAccountTokenLive" | "requestOwnedMainCredential"
 > | undefined {
   if (!selectionOptions) return undefined;
   return {
@@ -547,6 +548,9 @@ export function sharedStateSelectionOptions(
     ...(selectionOptions.isMainAccountTokenLive
       ? { isMainAccountTokenLive: selectionOptions.isMainAccountTokenLive }
       : {}),
+    ...(selectionOptions.requestOwnedMainCredential !== undefined
+      ? { requestOwnedMainCredential: selectionOptions.requestOwnedMainCredential }
+      : {}),
   };
 }
 
@@ -585,6 +589,7 @@ export function pickLowerUsageAccount(
       getAccountQuota(id),
       getPoolAccountPlanForSelection(config, id, selectionOptions),
       now,
+      codexAccountUsesCreditsAfterLimit(config, id),
     );
     if (usage < bestUsage) {
       best = id;
@@ -608,6 +613,7 @@ export function pickLowestUsageAmong(
       getAccountQuota(id),
       getPoolAccountPlanForSelection(config, id, selectionOptions),
       now,
+      codexAccountUsesCreditsAfterLimit(config, id),
     );
     if (usage < bestUsage) {
       best = id;
@@ -785,6 +791,7 @@ export function applyQuotaAutoSwitch(
     quota,
     getPoolAccountPlanForSelection(config, active, selectionOptions),
     now,
+    codexAccountUsesCreditsAfterLimit(config, active),
   );
   // Unknown usage is not evidence that a user's explicit selection crossed the
   // threshold. Wait for quota priming instead of rotating among guesses.