@bitkyc08/opencodex 2.76.0 → 2.78.0-preview.20261005

package/src/codex/account-credit-use.ts

@@ -4,6 +4,7 @@ import { isThirtyDayOnlyCodexPlan } from "./plan";
 import {
   CODEX_EXHAUSTED_USAGE_PERCENT,
   isTerminalShortWindow,
+  hasSpendableCodexCredits,
   resetAtToMs,
   type StoredAccountQuota,
 } from "./quota-types";
@@ -14,7 +15,7 @@ import {
  * Upstream does not refuse an account that holds ChatGPT credits at 100%: it serves the request
  * and draws the balance. Selection only takes an account off on quota after a refusal, so an
  * account with credits was never moved off. Spending is opt-in: only the ids in
- * `creditCodexAccountIds` may keep serving from credits, and every other account leaves rotation
+ * `creditCodexAccountIds` may keep serving from fresh spendable credits, and every other account leaves rotation
  * at 100% and comes back after its reset. Pool accounts and the `__main__` login both carry the
  * switch; the main login is also checked where the main-account hard lock is.
  */
@@ -95,5 +96,6 @@ export function isCodexAccountHeldForCredits(
   plan: unknown,
   now: number,
 ): boolean {
-  return !codexAccountUsesCreditsAfterLimit(config, accountId) && isCodexUsageLimitReached(quota, plan, now);
+  return !(codexAccountUsesCreditsAfterLimit(config, accountId) && hasSpendableCodexCredits(quota, now))
+    && isCodexUsageLimitReached(quota, plan, now);
 }

package/src/codex/account-runtime-state.ts

@@ -18,6 +18,27 @@ const reauthAccounts = new Map<string, number | undefined>();
 let lastReconciledGeneration = 0;
 let liveAccountIds = new Set<string>();
 
+// Refusal evidence is independent of the ordinary quarantine flag. Profile switches make a key
+// inapplicable, not forgotten; the oldest of at most 64 records is evicted to bound process state.
+const refusedMainRefreshGrants = new Set<string>();
+const MAX_REFUSED_MAIN_REFRESH_GRANTS = 64;
+
+export function markMainRefreshGrantRejected(key: string): void {
+  refusedMainRefreshGrants.add(key);
+  if (refusedMainRefreshGrants.size > MAX_REFUSED_MAIN_REFRESH_GRANTS) {
+    refusedMainRefreshGrants.delete(refusedMainRefreshGrants.values().next().value!);
+  }
+}
+
+export function isMainRefreshGrantRejected(key: string): boolean {
+  return refusedMainRefreshGrants.has(key);
+}
+
+export function clearMainRefreshGrantRejection(key: string): void {
+  refusedMainRefreshGrants.delete(key);
+}
+
+
 export function markAccountNeedsReauth(
   id: string,
   writerGeneration = captureConfigGeneration(),

package/src/codex/account-store.ts

@@ -1,3 +1,6 @@
+import { classifyChatgptRefreshFailure, noteChatgptRefreshFailure, type ChatgptRefreshDiagnosticCode } from "./chatgpt-refresh-failure";
+import { readBoundedResponseBody } from "../lib/bounded-body";
+export { classifyChatgptRefreshFailure } from "./chatgpt-refresh-failure";
 import { readOrcaAuthSource } from "./orca-auth-source";
 import { createHash } from "node:crypto";
 import { closeSync, existsSync, fstatSync, readFileSync, mkdirSync, openSync, statSync, unlinkSync, writeFileSync } from "node:fs";
@@ -526,7 +529,8 @@ const CHATGPT_CLIENT_ID = "app_EMoamEEZ73f0CkXaXp7hrann";
 
 export class TokenRefreshError extends Error {
   reason: "expired" | "revoked" | "unknown";
-  constructor(reason: "expired" | "revoked" | "unknown", message: string) {
+  constructor(reason: "expired" | "revoked" | "unknown", message: string,
+    readonly status?: number, readonly code?: ChatgptRefreshDiagnosticCode) {
     super(message);
     this.name = "TokenRefreshError";
     this.reason = reason;
@@ -1322,52 +1326,12 @@ async function resolveCodexToken(
       signal,
     });
     if (!res.ok) {
-      const errText = await res.text().catch(() => "");
-      let errDesc: string;
-      let errCodeExact: string | undefined;
-      try {
-        const parsed = JSON.parse(errText) as {
-          error?: string | { code?: string; message?: string };
-          error_description?: string;
-        };
-        if (typeof parsed.error === "string") {
-          errCodeExact = parsed.error.trim();
-          errDesc = [parsed.error, parsed.error_description].filter(Boolean).join(": ");
-        } else if (parsed.error && typeof parsed.error === "object") {
-          errCodeExact = typeof parsed.error.code === "string" ? parsed.error.code.trim() : undefined;
-          errDesc = [parsed.error.code, parsed.error.message, parsed.error_description].filter(Boolean).join(": ");
-        } else {
-          errDesc = parsed.error_description || `HTTP ${res.status}`;
-        }
-        if (!errDesc) errDesc = `HTTP ${res.status}`;
-      } catch { errDesc = `HTTP ${res.status}`; }
-      // `invalid_grant` is the standard OAuth code for a refresh token that is no longer
-      // usable, and upstream sends it bare with no description. Without it here the dead
-      // grant is classified "unknown", which callers treat as transient — so the account
-      // is never retired and every request repeats the same doomed refresh (#2887).
-      //
-      // Matched on the exact `error` CODE, not anywhere in the combined text: a transient
-      // `server_error` whose description happens to mention invalid_grant would otherwise
-      // retire a healthy account, which is the failure this whole change exists to remove.
-      //
-      // That rule binds the DESCRIPTION words too. "invalidated", "revoked" and "expired" read
-      // as terminal prose, but upstream puts arbitrary text there: a `server_error` whose
-      // description says "token was revoked" or "session expired" is still a 5xx blip, and
-      // retiring the account on it is exactly the false quarantine #2887 exists to prevent.
-      // So a body that carries a structured code is classified by that code ALONE. The
-      // substring fallback survives only where there is no structured code to read at all --
-      // a description-only body, or one this parser could not decode -- because there the
-      // prose is the only signal upstream gave us.
-      const structuredCode = errCodeExact ? errCodeExact : undefined;
-      const proseIsOnlySignal = structuredCode === undefined;
-      const reason = structuredCode === "invalid_grant"
-          || structuredCode === "refresh_token_invalidated"
-          || (proseIsOnlySignal
-            && (errDesc.includes("invalidated") || errDesc.includes("revoked"))) ? "revoked" as const
-        : structuredCode === "refresh_token_expired"
-          || (proseIsOnlySignal && errDesc.includes("expired")) ? "expired" as const
-        : "unknown" as const;
-      throw new TokenRefreshError(reason, `Codex token refresh failed (${reason}); reauthenticate the account.`);
+      const body = await readBoundedResponseBody(res, { signal, maxBytes: 16_384, fatalUtf8: true })
+        .catch(() => undefined);
+      const failure = classifyChatgptRefreshFailure(res.status, body?.displaySafe ? body.text : "");
+      const { reason } = failure;
+      noteChatgptRefreshFailure("pool", res.status, failure);
+      throw new TokenRefreshError(reason, `Codex token refresh failed (${reason}); reauthenticate the account.`, res.status, failure.code);
     }
     const data = (await res.json()) as { access_token: string; refresh_token?: string; expires_in: number };
     // Guard against a missing/non-finite/negative expires_in (malformed upstream

package/src/codex/account-usability.ts

@@ -2,8 +2,7 @@ import { readCodexAccountRecord } from "./account-store";
 import { isAccountNeedsReauth } from "./account-runtime-state";
 import {
   MAIN_CODEX_ACCOUNT_ID,
-  hasMainAccountRefreshGrant,
-  isMainAccountCredentialUsable,
+  getMainAccountCredentialStatus,
   isMainAccountTokenLive,
 } from "./main-account";
 import { hasLegacyMainCodexPoolAccount, isSelectableCodexPoolAccount } from "./account-id";
@@ -14,7 +13,7 @@ import { isMainAccountHardLocked } from "./main-account-hard-lock";
 export interface CodexAccountUsabilityOptions {
   /** Route using cached runtime state only; the caller must reject selected main before auth. */
   nativeMainSelectionOnly?: boolean;
-  /** Test seam for proving whether routing attempted a physical native-token read. */
+  /** Liveness override; ownership/read fences independently control physical credential reads. */
   isMainAccountTokenLive?: typeof isMainAccountTokenLive;
   /** Confirmed account ids for an account-gated model; omitted for ordinary native models. */
   modelEligibleAccountIds?: ReadonlySet<string>;
@@ -88,15 +87,19 @@ export function codexAccountUnusableReason(
     // A legacy pool row with the sentinel makes an active `__main__` ambiguous.
     // Fail closed until the authenticated compatibility-delete path removes it.
     if (hasLegacyMainCodexPoolAccount(config.codexAccounts)) return "legacy_pool_sentinel";
-    if (isAccountNeedsReauth(accountId) && !hasMainAccountRefreshGrant()) return "needs_reauth";
-    // A selection-only caller owns the recovery/drain fence and will reject main
-    // before reservation or token materialization. Treat cached main as a routing
-    // candidate without touching the credential file so affinity is not rebound.
+    // These scopes cannot consume physical stored-main state, even indirectly through an
+    // ordinary quarantine plus hasMainAccountRefreshGrant(). Caller liveness is request-owned.
     if (options.nativeMainSelectionOnly) return undefined;
+    if (options.requestOwnedMainCredential) {
+      return options.isMainAccountTokenLive?.() === false ? "main_credential_unavailable" : undefined;
+    }
+    const credential = getMainAccountCredentialStatus();
+    if (credential.refreshGrantRejected) return "needs_reauth";
+    if (isAccountNeedsReauth(accountId) && !credential.hasRefreshGrant) return "needs_reauth";
     // Main account: a refresh grant is enough to route; materialization refreshes before I/O.
     const mainLive = options.isMainAccountTokenLive
       ? options.isMainAccountTokenLive()
-      : isMainAccountCredentialUsable();
+      : credential.usable;
     return mainLive ? undefined : "main_credential_unavailable";
   }
   const exists = (config.codexAccounts ?? [])

package/src/codex/auth-api/account-list.ts

@@ -15,7 +15,7 @@ import { getCodexAccountAutoSwitchThresholdOverride } from "../account-auto-swit
 import { clearThreadAccountMapForAccount, isCodexAccountPlanExcluded, reconcileCodexActiveAfterExclusion } from "../routing";
 import { codexPlanValue, isThirtyDayOnlyCodexPlan } from "../plan";
 import { isAccountNeedsReauth, markAccountNeedsReauth } from "../account-runtime-state";
-import { getValidMainAccountToken, MainAccountTokenRefreshError, MAIN_CODEX_ACCOUNT_ID } from "../main-account";
+import { getValidMainAccountToken, isMainAccountRefreshGrantRejected, MAIN_CODEX_ACCOUNT_ID } from "../main-account";
 import { captureConfigGeneration } from "../../lib/state-store-sweeper";
 import { captureMainAccountIdentityGeneration, getMainAccountCredentialPresence, getMainAccountInfoCache, getObservedMainQuotaIdentityKey, isMainAccountIdentityGenerationLive } from "../main-account-cache";
 import type { CodexQuotaRefreshOutcome } from "../quota-refresh-outcome";
@@ -342,60 +342,76 @@ export async function listCodexAuthAccountsSnapshot(
       maskEmails,
     )];
   });
-  const fetchedMainGeneration = mainResult.identityGeneration ?? captureMainAccountIdentityGeneration();
-  const mainSnapshotLive = isMainAccountIdentityGenerationLive(fetchedMainGeneration);
-  // An ordinary same-account return can be parsed after its credential was replaced.
-  // The card and hard-lock status must describe the same published quota snapshot.
-  const mainInfo = mainSnapshotLive
-    ? mainResult.infoUnpublished ? getMainAccountInfoCache() ?? EMPTY_MAIN_ACCOUNT_INFO : mainResult.info
-    : EMPTY_MAIN_ACCOUNT_INFO;
-  const hasMainCredential = mainSnapshotLive && mainResult.credentialChecked
-    ? mainResult.hasCredential
-    : getMainAccountCredentialPresence() ?? false;
-  const mainMissingCredential = mainSnapshotLive && mainResult.credentialChecked && !hasMainCredential;
-  const mainNeedsReauth = mainMissingCredential || isAccountNeedsReauth(MAIN_CODEX_ACCOUNT_ID);
-  const mainHealth = projectCodexAccountHealth({
-    accountId: MAIN_CODEX_ACCOUNT_ID,
-    needsReauth: mainNeedsReauth,
-  });
-  // The main row carries the same attribution as a pool row. Reaching this point without
-  // `mainMissingCredential` means the runtime reauth flag is what set `mainNeedsReauth`, so the
-  // cause is a refresh that did not complete.
-  const mainReauthReason: CodexAccountReauthReason | undefined = mainMissingCredential
-    ? "missing_credential"
-    : mainNeedsReauth
-      ? "refresh_failed"
-      : mainHealth.status === "reauth_required" ? mainHealth.reason : undefined;
-  const main: CodexAuthAccountDto = {
-    id: MAIN_CODEX_ACCOUNT_ID,
-    email: projectEmail(mainInfo.email, maskEmails) ?? "Codex App login",
-    plan: mainInfo.plan,
-    ...(mainSnapshotLive && mainResult.quotaRefresh && mainResult.quotaRefreshGeneration !== undefined
+  const projectSnapshot = (mainRefreshRefused = false): CodexAuthAccountsSnapshot => {
+    const fetchedMainGeneration = mainResult.identityGeneration ?? captureMainAccountIdentityGeneration();
+    const mainSnapshotLive = isMainAccountIdentityGenerationLive(fetchedMainGeneration);
+    // An ordinary same-account return can be parsed after its credential was replaced.
+    // The card and hard-lock status must describe the same published quota snapshot.
+    const mainInfo = mainSnapshotLive
+      ? mainResult.infoUnpublished ? getMainAccountInfoCache() ?? EMPTY_MAIN_ACCOUNT_INFO : mainResult.info
+      : EMPTY_MAIN_ACCOUNT_INFO;
+    const hasMainCredential = mainSnapshotLive && mainResult.credentialChecked
+      ? mainResult.hasCredential
+      : getMainAccountCredentialPresence() ?? false;
+    const mainMissingCredential = mainSnapshotLive && mainResult.credentialChecked && !hasMainCredential;
+    const liveQuotaRefresh = mainSnapshotLive && mainResult.quotaRefreshGeneration !== undefined
       && isMainAccountIdentityGenerationLive(mainResult.quotaRefreshGeneration)
-      ? { quotaRefresh: mainResult.quotaRefresh } : {}),
-    logLabel: "main",
-    isMain: true,
-    paused: isCodexAccountPaused(runtimeConfig, MAIN_CODEX_ACCOUNT_ID),
-    mainAccountHardLock: { ...getMainAccountHardLockStatus(runtimeConfig),
-      externalUsage: getMainAccountExternalUsageWarning(getObservedMainQuotaIdentityKey()) },
-    priority: getCodexAccountPriority(runtimeConfig, MAIN_CODEX_ACCOUNT_ID),
-    autoSwitchThresholdOverride: getCodexAccountAutoSwitchThresholdOverride(runtimeConfig, MAIN_CODEX_ACCOUNT_ID),
-    creditsAfterLimit: codexAccountUsesCreditsAfterLimit(runtimeConfig, MAIN_CODEX_ACCOUNT_ID),
-    hasCredential: hasMainCredential,
-    needsReauth: mainNeedsReauth,
-    ...(mainReauthReason !== undefined ? { reauthReason: mainReauthReason } : {}),
-    quota: mainInfo.quota
-      ? quotaForPlan(mainQuotaWithCarriedResetCredits(mainInfo.quota), mainInfo.plan)
-      : null,
-    ...codexCreditsDtoField(runtimeConfig, MAIN_CODEX_ACCOUNT_ID, getMainChatgptAccountId()),
-    ...oauthAccountHealthFields("codex", MAIN_CODEX_ACCOUNT_ID, mainHealth),
-  };
-  return {
-    accounts: [main, ...withQuota],
-    mainIdentityGeneration: mainSnapshotLive
-      ? fetchedMainGeneration
-      : captureMainAccountIdentityGeneration(),
+      ? mainResult.quotaRefresh : undefined;
+    const mainNeedsReauth = mainMissingCredential || mainRefreshRefused || isAccountNeedsReauth(MAIN_CODEX_ACCOUNT_ID);
+    const mainHealth = projectCodexAccountHealth({
+      accountId: MAIN_CODEX_ACCOUNT_ID,
+      needsReauth: mainNeedsReauth,
+    });
+    // The main row carries the same attribution as a pool row. Reaching this point without
+    // Only a current terminal usage probe can attribute the reauth cause. A transient status
+    // never replaces a refresh failure, including a separately recorded refused grant.
+    const mainReauthReason: CodexAccountReauthReason | undefined = mainMissingCredential
+      ? "missing_credential"
+      : mainNeedsReauth
+        ? mainResult.terminalAuthFailure === true && liveQuotaRefresh?.status === "http_error"
+          ? "unauthorized" : "refresh_failed"
+        : mainHealth.status === "reauth_required" ? mainHealth.reason : undefined;
+    const main: CodexAuthAccountDto = {
+      id: MAIN_CODEX_ACCOUNT_ID,
+      email: projectEmail(mainInfo.email, maskEmails) ?? "Codex App login",
+      plan: mainInfo.plan,
+      ...(liveQuotaRefresh ? { quotaRefresh: liveQuotaRefresh } : {}),
+      logLabel: "main",
+      isMain: true,
+      paused: isCodexAccountPaused(runtimeConfig, MAIN_CODEX_ACCOUNT_ID),
+      mainAccountHardLock: { ...getMainAccountHardLockStatus(runtimeConfig),
+        externalUsage: getMainAccountExternalUsageWarning(getObservedMainQuotaIdentityKey()) },
+      priority: getCodexAccountPriority(runtimeConfig, MAIN_CODEX_ACCOUNT_ID),
+      autoSwitchThresholdOverride: getCodexAccountAutoSwitchThresholdOverride(runtimeConfig, MAIN_CODEX_ACCOUNT_ID),
+      creditsAfterLimit: codexAccountUsesCreditsAfterLimit(runtimeConfig, MAIN_CODEX_ACCOUNT_ID),
+      hasCredential: hasMainCredential,
+      needsReauth: mainNeedsReauth,
+      ...(mainReauthReason !== undefined ? { reauthReason: mainReauthReason } : {}),
+      quota: mainInfo.quota
+        ? quotaForPlan(mainQuotaWithCarriedResetCredits(mainInfo.quota), mainInfo.plan)
+        : null,
+      ...codexCreditsDtoField(runtimeConfig, MAIN_CODEX_ACCOUNT_ID, getMainChatgptAccountId()),
+      ...oauthAccountHealthFields("codex", MAIN_CODEX_ACCOUNT_ID, mainHealth),
+    };
+    return {
+      accounts: [main, ...withQuota],
+      mainIdentityGeneration: mainSnapshotLive
+        ? fetchedMainGeneration
+        : captureMainAccountIdentityGeneration(),
+    };
   };
+  // Project the refusal and DTO in the same owned synchronous observation. A same-account grant
+  // replacement during earlier pool probes must not inherit the previous grant's refusal.
+  const projectionLease = tryAcquireNativeMainProfileClaim();
+  if (!projectionLease) return projectSnapshot();
+  try {
+    return await withNativeMainCredentialClaim(async () => projectSnapshot(isMainAccountRefreshGrantRejected()));
+  } catch (error) {
+    if (isNativeMainClaimUnavailable(error)) return projectSnapshot();
+    throw error;
+  } finally {
+    projectionLease.release();
+  }
 }
 
 /** One opted-in account's metadata; reuse the bounded WHAM 401 recovery and generation fence. */
@@ -406,16 +422,10 @@ export async function refreshCodexQuotaForActivation(config: OcxConfig, accountI
     try {
       reconcileMainCodexAccountRuntimeState();
       if (isAccountNeedsReauth(accountId)) return;
-      const identityGeneration = captureMainAccountIdentityGeneration();
-      const writerGeneration = captureConfigGeneration();
       try {
-        // Refresh may need an exclusive claim; prepare before WHAM takes its shared claim.
+        // Refresh owns credential-scoped refusal evidence; do not recreate a global quarantine.
         if (!await getValidMainAccountToken({ preserveReauth: true })) return;
-      } catch (error) {
-        if (error instanceof MainAccountTokenRefreshError && error.reason === "reauth"
-          && isMainAccountIdentityGenerationLive(identityGeneration)) {
-          markAccountNeedsReauth(accountId, writerGeneration);
-        }
+      } catch {
         return;
       }
       if (isAccountNeedsReauth(accountId)) return;
@@ -476,7 +486,7 @@ export async function pauseExhaustedCodexAccounts(
         }
         return {
           shouldPause: !isCodexAccountPaused(config, MAIN_CODEX_ACCOUNT_ID)
-            && isCodexQuotaExhausted(mainResult.freshQuota, mainResult.info.plan),
+            && isCodexQuotaExhausted(mainResult.freshQuota, mainResult.info.plan, codexAccountUsesCreditsAfterLimit(config, MAIN_CODEX_ACCOUNT_ID)),
           checkedAccountCount: 1,
           failedAccountCount: 0,
         };
@@ -511,7 +521,7 @@ export async function pauseExhaustedCodexAccounts(
           continue;
         }
         checkedAccountCount += 1;
-        if (!isCodexAccountPaused(config, account.id) && isCodexQuotaExhausted(quotaResult.freshQuota, plan)) {
+        if (!isCodexAccountPaused(config, account.id) && isCodexQuotaExhausted(quotaResult.freshQuota, plan, codexAccountUsesCreditsAfterLimit(config, account.id))) {
           exhaustedIds.push(account.id);
         }
       }

package/src/codex/auth-api/main-account-probe.ts

@@ -16,14 +16,15 @@ import { getMainAccountPlan, isMainAccountTokenVerifiablyLive, MAIN_CODEX_ACCOUN
 import { captureConfigGeneration } from "../../lib/state-store-sweeper";
 import { captureMainAccountIdentityGeneration, clearMainAccountInfoCache, getMainAccountInfoCache, getMainQuotaCredentialGeneration, isMainAccountIdentityGenerationLive, isMainQuotaWriterLive, matchesMainQuotaCredential, observeMainQuotaCredential, setMainAccountCredentialPresence, setMainAccountInfoCache } from "../main-account-cache";
 import type { MainQuotaWriter, MainAccountInfo } from "../main-account-cache";
-import type { CodexQuotaRefreshOutcome } from "../quota-refresh-outcome";
+import { isCodexTerminalAuthCode } from "../quota-refresh-outcome";
+import type { CodexQuotaRefreshOutcome, CodexTerminalAuthCode } from "../quota-refresh-outcome";
 import { observeMainReserveRevocation } from "../reserve-availability";
 import type { AdmissionLease } from "../../lib/admission";
 import { nonEmptyPlan } from "./runtime-config";
 import { tryAcquireNativeMainProfileClaim } from "../native-main-admission";
 import { WHAM_REQUEST_TIMEOUT_MS } from "../quota-recovery-timing";
 import { withNativeMainCredentialClaim, isNativeMainClaimUnavailable } from "./http";
-import { MAIN_TERMINAL_AUTH_CODES, readMainAuthErrorCode, currentQuotaDispatchSequence, nextQuotaDispatchSequence, isQuotaDispatchCurrent, publishQuotaDispatch } from "./pool-quota-probe";
+import { readMainAuthErrorCode, currentQuotaDispatchSequence, nextQuotaDispatchSequence, isQuotaDispatchCurrent, publishQuotaDispatch } from "./pool-quota-probe";
 
 /**
  * Last reset-credit count this process parsed for the main account, tagged with the
@@ -79,14 +80,18 @@ function sharedMainQuotaPacingEnabled(config: OcxConfig): boolean {
  * itself would make a real 401 permanently transient.
  */
 export async function isTerminalMainAuthResponse(resp: Response, accessTokenLive: boolean): Promise<boolean> {
-  if (resp.status === 401) {
-    if (!accessTokenLive) return true;
-    const code = await readMainAuthErrorCode(resp);
-    return typeof code === "string" && MAIN_TERMINAL_AUTH_CODES.has(code);
-  }
-  if (resp.status !== 403) return false;
+  return (await classifyMainAuthResponse(resp, accessTokenLive)).terminal;
+}
+
+/** As `isTerminalMainAuthResponse`, also naming the provider code that made it terminal. */
+async function classifyMainAuthResponse(
+  resp: Response,
+  accessTokenLive: boolean,
+): Promise<{ terminal: boolean; code?: CodexTerminalAuthCode }> {
+  if (resp.status !== 401 && resp.status !== 403) return { terminal: false };
   const code = await readMainAuthErrorCode(resp);
-  return typeof code === "string" && MAIN_TERMINAL_AUTH_CODES.has(code);
+  if (isCodexTerminalAuthCode(code)) return { terminal: true, code };
+  return { terminal: resp.status === 401 && !accessTokenLive };
 }
 
 export interface MainResetQuotaProof {
@@ -103,6 +108,8 @@ export interface MainAccountInfoFetchResult {
   quotaRefresh?: CodexQuotaRefreshOutcome;
   /** Internal dispatch fence for diagnostics only; never copied into a public DTO or cache. */
   quotaRefreshGeneration?: number;
+  /** This current-credential usage response supplied terminal auth evidence; never public. */
+  terminalAuthFailure?: true;
   /** Whether this attempt safely inspected the physical native-main credential. */
   credentialChecked: boolean;
   /** Meaningful only when credentialChecked is true. */
@@ -288,7 +295,8 @@ export async function fetchMainAccountInfoWhileOwned(
       const resp = admission.response;
       quotaPhase = "publish";
       if (!resp.ok) {
-        const terminalAuthFailure = await isTerminalMainAuthResponse(resp, isMainAccountTokenVerifiablyLive());
+        const authFailure = await classifyMainAuthResponse(resp, isMainAccountTokenVerifiablyLive());
+        const terminalAuthFailure = authFailure.terminal;
         const retried = await retryMainAccountInfoIfIdentityChanged(requestAccountId, retriesRemaining, nativeMainLease, explicitRefresh, paced);
         if (retried) return retried;
         if (!isQuotaDispatchCurrent(dispatchSequence) || !credentialIsCurrent()) {
@@ -302,10 +310,15 @@ export async function fetchMainAccountInfoWhileOwned(
           if (diagnosticStillLive) quotaRefreshGeneration = captureMainAccountIdentityGeneration();
           markAccountNeedsReauth(MAIN_CODEX_ACCOUNT_ID, writerGeneration);
         }
+        // Keep the last-known plan visible: after a plan change revokes the session, the plan the
+        // account HAD is what tells the operator why it stopped working.
         return {
-          info: EMPTY_MAIN_ACCOUNT_INFO, credentialChecked: true, hasCredential: true,
-          quotaRefresh: { status: "http_error", httpStatus: resp.status },
+          info: { ...EMPTY_MAIN_ACCOUNT_INFO, plan: nonEmptyPlan(cached?.plan) ?? nonEmptyPlan(getMainAccountPlan()) },
+          credentialChecked: true, hasCredential: true,
+          quotaRefresh: { status: "http_error", httpStatus: resp.status,
+            ...(authFailure.code ? { code: authFailure.code } : {}) },
           quotaRefreshGeneration,
+          ...(terminalAuthFailure ? { terminalAuthFailure: true as const } : {}),
         };
       }
       quotaPhase = "body";

package/src/codex/auth-api/pool-mode-gate.ts

@@ -1,3 +1,4 @@
+import { codexAccountUsesCreditsAfterLimit } from "../account-credit-use";
 import { nextCodexUsageQueryAt, nextQuotaQueryDelay, pruneRemovedCodexPoolUsageAccounts } from "../quota-query-backoff";
 import { CODEX_PRIORITY_FAILBACK_REFRESH_MS } from "../account-priority";
 import { codexQuotaHasFreshUsage } from "../quota-observation-freshness";
@@ -6,8 +7,8 @@ import { getAccountQuota, isCompleteCodexQuotaRecoverySnapshot } from "../quota"
 import { reconcileMainCodexAccountRuntimeState } from "../account-lifecycle";
 import { claimDueCodexQuotaRecoveryProbes, settleCodexQuotaRecoveryProbe } from "../routing";
 import { readCodexTokens } from "../auth-collision";
-import { isAccountNeedsReauth, markAccountNeedsReauth } from "../account-runtime-state";
-import { getValidMainAccountToken, MainAccountTokenRefreshError, MAIN_CODEX_ACCOUNT_ID, getMainAccountPlan } from "../main-account";
+import { isAccountNeedsReauth } from "../account-runtime-state";
+import { getValidMainAccountToken, MAIN_CODEX_ACCOUNT_ID, getMainAccountPlan } from "../main-account";
 import { captureConfigGeneration, registerStateSweepAfterTick } from "../../lib/state-store-sweeper";
 import { observeMainQuotaCredential, getMainQuotaCredentialGeneration, captureMainAccountIdentityGeneration, isMainAccountIdentityGenerationLive } from "../main-account-cache";
 import { getMainAccountHardLockStatus } from "../main-account-hard-lock";
@@ -58,7 +59,7 @@ export async function runCodexCooldownRecoveryProbes(config: OcxConfig, now = Da
         // Defence in depth: independent scopes are already excluded at the claim site.
         // Generic WHAM must never clear Reserve even if claim selection changes.
         const recovered = (claim.scope === undefined || claim.scope === "shared")
-          && isCompleteCodexQuotaRecoverySnapshot(result.freshQuota ?? null, result.freshPlan ?? account.plan);
+          && isCompleteCodexQuotaRecoverySnapshot(result.freshQuota ?? null, result.freshPlan ?? account.plan, codexAccountUsesCreditsAfterLimit(config, claim.accountId));
         settleCodexQuotaRecoveryProbe(claim, recovered, {
           credentialGeneration: result.freshCredentialGeneration,
         }, now);
@@ -100,18 +101,14 @@ export async function runMainAccountHardLockRecovery(config: OcxConfig): Promise
     if (getMainAccountHardLockStatus(config).state !== "blocked"
       || isAccountNeedsReauth(MAIN_CODEX_ACCOUNT_ID)) return;
     const identityGeneration = captureMainAccountIdentityGeneration();
-    const writerGeneration = captureConfigGeneration();
     try {
       // Refresh can require an exclusive credential claim: never hold WHAM's shared
       // claim while obtaining a valid token. The runtime lease spans both operations.
       const prepared = await getValidMainAccountToken({ preserveReauth: true });
       if (!prepared) return;
       observeMainQuotaCredential(prepared.accessToken, prepared.chatgptAccountId);
-    } catch (error) {
-      if (error instanceof MainAccountTokenRefreshError && error.reason === "reauth"
-        && isMainAccountIdentityGenerationLive(identityGeneration)) {
-        markAccountNeedsReauth(MAIN_CODEX_ACCOUNT_ID, writerGeneration);
-      }
+    } catch {
+      // Native refresh retains its own grant-scoped refusal; global quarantine would outlive it.
       return;
     }
     if (isAccountNeedsReauth(MAIN_CODEX_ACCOUNT_ID)) return;

package/src/codex/auth-api/pool-quota-probe.ts

@@ -15,14 +15,12 @@ import { WHAM_REQUEST_TIMEOUT_MS } from "../quota-recovery-timing";
 import { claimQuotaRecovery, fencePropagatedQuotaRecovery, quotaRecoveryTerminalFor, releaseQuotaRecovery, settleQuotaRecovery, settleQuotaRecoveryTerminal } from "../quota-401-recovery";
 import { seedLoginRowsForTests } from "./login-state";
 import { nonEmptyPlan } from "./runtime-config";
+import { CODEX_TERMINAL_AUTH_CODES } from "../quota-refresh-outcome";
 
 export const POOL_CACHE_TTL = 5 * 60_000;
 export const POOL_QUOTA_REFRESH_CONCURRENCY = 4;
 
-export const MAIN_TERMINAL_AUTH_CODES = new Set([
-  "invalid_workspace_selected",
-  "invalid_refresh_token",
-]);
+export const MAIN_TERMINAL_AUTH_CODES: ReadonlySet<string> = new Set(CODEX_TERMINAL_AUTH_CODES);
 
 export async function readMainAuthErrorCode(resp: Response): Promise<unknown> {
   try {

package/src/codex/auth-api/reset-credit-service.ts

@@ -1,3 +1,4 @@
+import { codexAccountUsesCreditsAfterLimit } from "../account-credit-use";
 import { getValidCodexToken, isCodexAccountGenerationLive, readCodexAccountRecord, CodexCredentialGenerationConflictError } from "../account-store";
 import { isCompleteCodexQuotaRecoverySnapshot } from "../quota";
 import { reconcileMainCodexAccountRuntimeState } from "../account-lifecycle";
@@ -233,7 +234,7 @@ async function refreshAfterManualReset(
         && proof.credentialGeneration === auth.mainProof.credentialGeneration
         && proof.writer.identityKey === auth.mainProof.writer.identityKey
         && proof.writer.identityGeneration === auth.mainProof.writer.identityGeneration
-        && isCompleteCodexQuotaRecoverySnapshot(result.freshQuota ?? null, result.info.plan);
+        && isCompleteCodexQuotaRecoverySnapshot(result.freshQuota ?? null, result.info.plan, codexAccountUsesCreditsAfterLimit(getRuntimeConfig(config), accountId));
       for (const claim of claims) settleManualResetCooldown(getRuntimeConfig(config), claim, recovered);
       return manualResetAuthStillLive(accountId, auth) ? result.freshResetCredits : undefined;
     }
@@ -255,7 +256,7 @@ async function refreshAfterManualReset(
     const record = readCodexAccountRecord(accountId);
     const recovered = didReset && record?.credential?.chatgptAccountId === auth.chatgptAccountId
       && (result.quotaProbeAttempted?.dispatchSequence ?? 0) > afterDispatchSequence
-      && isCompleteCodexQuotaRecoverySnapshot(result.freshQuota ?? null, result.freshPlan ?? account.plan);
+      && isCompleteCodexQuotaRecoverySnapshot(result.freshQuota ?? null, result.freshPlan ?? account.plan, codexAccountUsesCreditsAfterLimit(getRuntimeConfig(config), accountId));
     for (const claim of claims) settleManualResetCooldown(getRuntimeConfig(config), claim, recovered, {
       credentialGeneration: result.freshCredentialGeneration,
       refreshLineage: result.resetRefreshLineage,

package/src/codex/auth-context.ts

@@ -1,3 +1,4 @@
+import { hasSpendableCodexCredits } from "./quota-types";
 import { noteMainAccountActivity } from "./main-account-external-usage";
 import { codexAccountPriorityFailbackEnabled } from "./account-priority";
 import type { PoolQuotaWriter } from "./quota-types";
@@ -16,7 +17,7 @@ import {
 import { isAccountNeedsReauth, markAccountNeedsReauth } from "./account-runtime-state";
 import { ConfigMutationLockError } from "../config";
 import { NativeProfileError } from "./native-profile-types";
-import { isCodexAccountUsable } from "./account-usability";
+import { codexAccountUnusableReason, isCodexAccountUsable } from "./account-usability";
 import { reconcileMainCodexAccountRuntimeState } from "./account-lifecycle";
 import {
   MAIN_CODEX_ACCOUNT_ID,
@@ -102,7 +103,7 @@ import { getEffectiveCodexAutoSwitchThreshold } from "./account-auto-switch";
 function requestOwnedMainPinHasQuotaHeadroom(config: OcxConfig): boolean {
   const threshold = getEffectiveCodexAutoSwitchThreshold(config, MAIN_CODEX_ACCOUNT_ID);
   if (threshold <= 0) return true;
-  const usage = computeCodexUsageScore(getAccountQuota(MAIN_CODEX_ACCOUNT_ID));
+  const usage = computeCodexUsageScore(getAccountQuota(MAIN_CODEX_ACCOUNT_ID), undefined, Date.now(), codexAccountUsesCreditsAfterLimit(config, MAIN_CODEX_ACCOUNT_ID));
   return usage >= CODEX_UNKNOWN_USAGE_SCORE || usage < threshold;
 }
 
@@ -378,9 +379,11 @@ export class CodexAuthContextError extends Error {
 }
 
 export class CodexPoolAuthenticationError extends Error {
-  constructor(message = "OpenAI account pool has no usable account credential") {
+  readonly quarantinedMain: boolean;
+  constructor(message = "OpenAI account pool has no usable account credential", options?: { quarantinedMain?: boolean }) {
     super(message);
     this.name = "CodexPoolAuthenticationError";
+    this.quarantinedMain = options?.quarantinedMain === true;
   }
 }
 
@@ -530,7 +533,7 @@ export class CodexMainAccountCreditsOffError extends CodexAccountCooldownError {
     super(MAIN_CODEX_ACCOUNT_ID, resetAt ?? 0);
     this.name = "CodexMainAccountCreditsOffError";
     this.resetAt = resetAt;
-    this.message = "Codex main account reached its usage limit, and spending ChatGPT credits is off for it."
+    this.message = "Codex main account reached its usage limit, and spending ChatGPT credits is off or no fresh spendable balance is available."
       + " Choose another account, wait for the limit to reset, or allow the main account under \"Use credits\" in Codex Auth.";
   }
 }
@@ -723,7 +726,8 @@ export function unwrapUpstreamRetryEvidenceError(error: unknown): unknown {
  * file, which several callers are forbidden to open, so every long window counts instead.
  */
 function mainCreditsHoldResetAt(config: Pick<OcxConfig, "creditCodexAccountIds">): number | undefined {
-  if (codexAccountUsesCreditsAfterLimit(config, MAIN_CODEX_ACCOUNT_ID)) return undefined;
+  if (codexAccountUsesCreditsAfterLimit(config, MAIN_CODEX_ACCOUNT_ID)
+    && hasSpendableCodexCredits(getMainPolicyQuota())) return undefined;
   return codexUsageLimitResetAt(getMainPolicyQuota(), undefined, Date.now());
 }
 
@@ -920,7 +924,7 @@ export function shouldMarkAccountNeedsReauthForCodexAuthFailure(cause: unknown):
     && !(cause instanceof CodexCredentialRefreshBusyError)
     && !(cause instanceof CodexCredentialRefreshStaleError)
     && !(cause instanceof MainAuthJsonChangedDuringRefreshError)
-    && !(cause instanceof MainAccountTokenRefreshError && cause.reason === "transient")
+    && !(cause instanceof MainAccountTokenRefreshError)
     && !(cause instanceof NativeProfileError && cause.retryable)
     && !(cause instanceof DOMException && cause.name === "AbortError")
     && !(cause instanceof ConfigMutationLockError);
@@ -1314,7 +1318,12 @@ export async function resolveCodexAuthContext(
             "Selected Codex account does not support this model",
           );
         }
-        throw new CodexPoolAuthenticationError("Selected Codex account is unavailable");
+        const mainReason = fixedAccountId === MAIN_CODEX_ACCOUNT_ID && !nativeMainReadsForbidden
+          && !policy.pausedCodexAccountIds?.includes(fixedAccountId)
+          ? codexAccountUnusableReason(config, fixedAccountId, selectionOptions) : undefined;
+        throw new CodexPoolAuthenticationError("Selected Codex account is unavailable", {
+          quarantinedMain: mainReason === "needs_reauth",
+        });
       }
       // Recovery or a turn drain deliberately makes physical main unobservable.
       // If no healthy pool route is available, report the temporary fence rather
@@ -1339,7 +1348,12 @@ export async function resolveCodexAuthContext(
             : "Codex accounts that support this model are currently unavailable",
         );
       }
-      throw new CodexPoolAuthenticationError();
+      throw new CodexPoolAuthenticationError(undefined, {
+        quarantinedMain: !nativeMainReadsForbidden
+          && options.excludeAccountId !== MAIN_CODEX_ACCOUNT_ID
+          && !policy.pausedCodexAccountIds?.includes(MAIN_CODEX_ACCOUNT_ID)
+          && codexAccountUnusableReason(config, MAIN_CODEX_ACCOUNT_ID, selectionOptions) === "needs_reauth",
+      });
     }
     accountId = selected;
     if (accountId === MAIN_CODEX_ACCOUNT_ID) assertMainAccountPolicy(policy);
@@ -1370,10 +1384,15 @@ export async function resolveCodexAuthContext(
         throw new CodexPoolAuthenticationError("Selected Codex account is unavailable");
       }
       if (isAccountNeedsReauth(accountId)) {
-        throw new CodexPoolAuthenticationError("Selected Codex account needs reauthentication");
+        throw new CodexPoolAuthenticationError("Selected Codex account needs reauthentication", {
+          quarantinedMain: accountId === MAIN_CODEX_ACCOUNT_ID && !nativeMainReadsForbidden,
+        });
       }
-      if (!isCodexAccountUsable(config, accountId, selectionOptions)) {
-        throw new CodexPoolAuthenticationError("Selected Codex account is unavailable");
+      const unusableReason = codexAccountUnusableReason(config, accountId, selectionOptions);
+      if (unusableReason !== undefined) {
+        throw new CodexPoolAuthenticationError("Selected Codex account is unavailable", {
+          quarantinedMain: accountId === MAIN_CODEX_ACCOUNT_ID && unusableReason === "needs_reauth",
+        });
       }
     }
   } catch (cause) {