@bitkyc08/opencodex 2.7.40 → 2.7.41

package/src/cli/status-oauth.ts

@@ -0,0 +1,68 @@
+import { maskAccountId } from "../lib/privacy";
+import {
+  CODEX_HEALTH_UNAVAILABLE_NOTE,
+  MASKED_ACCOUNT_FALLBACK,
+  type OAuthAccountHealth,
+  type OAuthCliHealthReport,
+  type OAuthHealthEntry,
+} from "../oauth/health";
+
+function describeHealth(health: OAuthAccountHealth): string {
+  switch (health.status) {
+    case "healthy":
+      return "healthy";
+    case "reauth_required":
+      return "reauthentication required";
+    case "cooldown":
+      return health.reason === "rate_limit"
+        ? `rate limited until ${health.until}`
+        : `quota limited until ${health.until}`;
+    case "warning":
+      switch (health.reason) {
+        case "refresh_conflict":
+          return "refresh conflict";
+        case "metadata_mismatch":
+          return "metadata mismatch";
+        case "stale_credentials":
+          return "stale credentials";
+        default:
+          return "warning";
+      }
+    default:
+      return "unknown";
+  }
+}
+
+function formatEntryBlock(entries: OAuthHealthEntry[]): string {
+  if (entries.length === 0) return "";
+
+  const notable = entries.filter((entry) => entry.health.status !== "healthy");
+  if (notable.length === 0) return "OAuth health: ok";
+
+  const lines = ["OAuth health: warning"];
+  for (const entry of notable) {
+    const masked = maskAccountId(entry.accountId) ?? MASKED_ACCOUNT_FALLBACK;
+    lines.push(`  ${entry.provider}  ${masked}  ${describeHealth(entry.health)}`);
+    if (entry.action) {
+      lines.push(`    Action: ${entry.action}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+/** Human-readable OAuth health block for `ocx status` (redacted account ids, no tokens). */
+export function formatOAuthHealthForStatus(
+  input: OAuthHealthEntry[] | OAuthCliHealthReport,
+): string {
+  const report: OAuthCliHealthReport = Array.isArray(input)
+    ? { entries: input, codexHealthSource: "management-api" }
+    : input;
+
+  const parts: string[] = [];
+  if (report.codexHealthSource === "unavailable") {
+    parts.push(CODEX_HEALTH_UNAVAILABLE_NOTE);
+  }
+  const oauthBlock = formatEntryBlock(report.entries);
+  if (oauthBlock) parts.push(oauthBlock);
+  return parts.join("\n");
+}

package/src/cli/status.ts

@@ -9,6 +9,7 @@ import { getCodexRoutingKind } from "../codex/inject";
 import { diagnoseCodexShim } from "../codex/shim";
 import { displayCodexRuntimePath, effortClampAppliesToRuntime, loadLastEffortClamp, resolveCodexRuntime } from "../codex/runtime";
 import { redactSecretString, redactUserPath } from "../lib/redact";
+import { collectOrcaCodexHomeDiagnostic, type OrcaCodexHomeDiagnostic } from "../codex/home";
 
 type HealthCheck = {
   ok: boolean;
@@ -65,6 +66,7 @@ export type CliStatusJson = {
       runtimeVersion: string | null;
     };
   };
+  codexHome: OrcaCodexHomeDiagnostic;
 };
 
 export type CliStatusView = {
@@ -163,6 +165,7 @@ export async function collectStatus(): Promise<CliStatusView> {
   })();
   const lastClamp = loadLastEffortClamp();
   const clampActive = effortClampAppliesToRuntime(lastClamp, resolvedRuntime.runtime);
+  const codexHome = collectOrcaCodexHomeDiagnostic();
   const warningParts: string[] = [];
   if (
     resolvedRuntime.replacedConfigured
@@ -256,6 +259,7 @@ export async function collectStatus(): Promise<CliStatusView> {
       codexShim: { summary: codexShimSummary },
       codexPlugins,
       codexRuntime,
+      codexHome,
     },
   };
 }

package/src/codex/account-lifecycle.ts

@@ -1,15 +1,46 @@
 import { removeCodexAccountCredential } from "./account-store";
 import { clearAccountNeedsReauth } from "./account-runtime-state";
+import { getMainChatgptAccountId } from "./auth-collision";
+import { MAIN_CODEX_ACCOUNT_ID, setMainAccountPlan } from "./main-account";
 import { clearAccountQuota } from "./quota";
 import { clearCodexUpstreamHealthForAccount, clearThreadAccountMapForAccount } from "./routing";
 import { invalidateCodexWebSocketsForAccount } from "./websocket-registry";
+import { clearMainAccountInfoCache } from "./main-account-cache";
 import type { OcxConfig } from "../types";
 
+let observedMainChatgptAccountId: string | undefined;
+
 export function purgeCodexAccountRuntimeState(accountId: string): void {
   clearAccountNeedsReauth(accountId);
   clearAccountQuota(accountId);
   clearThreadAccountMapForAccount(accountId);
   clearCodexUpstreamHealthForAccount(accountId);
+  if (accountId === MAIN_CODEX_ACCOUNT_ID) clearMainAccountInfoCache();
+}
+
+/**
+ * The main Codex login is stored under the stable `__main__` alias, while
+ * `~/.codex/auth.json` can be replaced with credentials for another physical
+ * ChatGPT account. Drop alias-keyed runtime state when that identity changes so
+ * cooldown, quota, reauth, and thread affinity do not leak across accounts.
+ */
+export function reconcileMainCodexAccountRuntimeState(): boolean {
+  const currentAccountId = getMainChatgptAccountId();
+  // A missing/malformed auth.json is an unknown identity, not a confirmed account switch. Keep the
+  // prior observation and its safety state until a real account id can be read again.
+  if (currentAccountId === null) return false;
+  const previousAccountId = observedMainChatgptAccountId;
+  observedMainChatgptAccountId = currentAccountId;
+  if (previousAccountId === undefined || previousAccountId === currentAccountId) return false;
+
+  purgeCodexAccountRuntimeState(MAIN_CODEX_ACCOUNT_ID);
+  setMainAccountPlan(null);
+  invalidateCodexWebSocketsForAccount(MAIN_CODEX_ACCOUNT_ID);
+  return true;
+}
+
+export function resetMainCodexAccountIdentityTrackingForTests(): void {
+  observedMainChatgptAccountId = undefined;
 }
 
 export function deleteCodexAccount(runtimeConfig: OcxConfig, accountId: string): void {

package/src/codex/auth-api.ts

@@ -1,4 +1,4 @@
-import { loadConfig, saveConfig } from "../config";
+import { loadConfig, saveConfigPreservingClaudeCode } from "../config";
 import { withCodexAccountLogLabel } from "./account-label";
 import {
   getCodexAccountCredential,
@@ -9,8 +9,9 @@ import {
   CodexCredentialRefreshLockTimeoutError,
   TokenRefreshError,
 } from "./account-store";
-import { deleteCodexAccount } from "./account-lifecycle";
-import { checkAccountIdCollision, readCodexTokens } from "./auth-collision";
+import { deleteCodexAccount, reconcileMainCodexAccountRuntimeState } from "./account-lifecycle";
+import { clearCodexAccountCooldown } from "./routing";
+import { checkAccountIdCollision, getMainChatgptAccountId, readCodexTokens, readCodexTokensResult } from "./auth-collision";
 export { checkAccountIdCollision, getMainChatgptAccountId } from "./auth-collision";
 export { clearAccountNeedsReauth, isAccountNeedsReauth, markAccountNeedsReauth } from "./account-runtime-state";
 import { clearAccountNeedsReauth, isAccountNeedsReauth, markAccountNeedsReauth } from "./account-runtime-state";
@@ -34,6 +35,13 @@ export {
 } from "./quota";
 import { extractAccountId, decodeJwtPayload } from "../oauth/chatgpt";
 import { MAIN_CODEX_ACCOUNT_ID, setMainAccountPlan } from "./main-account";
+import {
+  clearMainAccountInfoCache,
+  getMainAccountInfoCache,
+  setMainAccountInfoCache,
+  type MainAccountInfo,
+} from "./main-account-cache";
+export { clearMainAccountInfoCache } from "./main-account-cache";
 import { maskEmail } from "../lib/privacy";
 import { CodexWarmupError, codexWarmupFailureReason, warmCodexAccount } from "./warmup";
 export { maskEmail } from "../lib/privacy";
@@ -41,6 +49,12 @@ import type { CodexAccount, OcxConfig } from "../types";
 import { isCanonicalOpenAiForwardProvider, OPENAI_CODEX_PROVIDER_ID } from "../providers/openai-tiers";
 import { providerCodexAccountMode } from "../providers/registry";
 import { readBoundedResponseBody } from "../lib/bounded-body";
+import {
+  oauthAccountHealthFields,
+  projectCodexAccountHealth,
+  type OAuthAccountHealth,
+  type OAuthHealthLabel,
+} from "../oauth/health";
 
 function jsonResponse(data: unknown, status = 200): Response {
   return new Response(JSON.stringify(data), {
@@ -83,6 +97,8 @@ function poolAccountDto(
   hasCredential: boolean,
 ): CodexAuthAccountDto {
   const quota = quotaForPlan(quotaResult.quota, account.plan);
+  const needsReauth = !hasCredential || quotaResult.needsReauth || isAccountNeedsReauth(account.id);
+  const health = projectCodexAccountHealth({ accountId: account.id, needsReauth });
   return {
     id: account.id,
     email: maskEmail(account.email) ?? account.email,
@@ -91,8 +107,9 @@ function poolAccountDto(
     ...(account.logLabel !== undefined ? { logLabel: account.logLabel } : {}),
     isMain: false,
     quota: quota ? { ...quota } : null,
-    needsReauth: !hasCredential || quotaResult.needsReauth || isAccountNeedsReauth(account.id),
+    needsReauth,
     hasCredential,
+    ...oauthAccountHealthFields("codex", account.id, health),
   };
 }
 
@@ -187,7 +204,6 @@ function expireCodexAuthFlow(flowId: string | null, error = "Login cancelled"):
   }
 }
 
-let mainAccountCache: { email: string | null; plan: string | null; quota: Omit<StoredAccountQuota, "updatedAt"> | null; ts: number } | null = null;
 const MAIN_CACHE_TTL = 5 * 60_000;
 const POOL_CACHE_TTL = 5 * 60_000;
 const POOL_QUOTA_REFRESH_CONCURRENCY = 4;
@@ -201,7 +217,7 @@ function getRuntimeConfig(config: OcxConfig): OcxConfig {
 }
 
 function saveRuntimeConfig(sourceConfig: OcxConfig, nextConfig: OcxConfig): void {
-  saveConfig(nextConfig);
+  saveConfigPreservingClaudeCode(nextConfig);
   if (sourceConfig === nextConfig || !isRuntimeConfig(sourceConfig)) return;
   for (const key of Object.keys(sourceConfig) as Array<keyof OcxConfig>) {
     delete sourceConfig[key];
@@ -253,15 +269,49 @@ async function isTerminalMainAuthResponse(resp: Response): Promise<boolean> {
   }
 }
 
-export async function fetchMainAccountInfo(forceRefresh = false): Promise<{ email: string | null; plan: string | null; quota: Omit<StoredAccountQuota, "updatedAt"> | null }> {
-  const tokens = readCodexTokens();
-  if (!tokens) {
-    mainAccountCache = null;
-    markAccountNeedsReauth(MAIN_CODEX_ACCOUNT_ID);
-    return { email: null, plan: null, quota: null };
+interface MainAccountInfoFetchResult {
+  info: MainAccountInfo;
+  /** Present only when this call's WHAM response included `rate_limit_reset_credits.available_count`. */
+  freshResetCredits?: number;
+}
+
+export async function fetchMainAccountInfo(forceRefresh = false): Promise<MainAccountInfo> {
+  const { info } = await fetchMainAccountInfoAttempt(forceRefresh, 1);
+  return info;
+}
+
+const EMPTY_MAIN_ACCOUNT_INFO: MainAccountInfo = { email: null, plan: null, quota: null };
+
+async function retryMainAccountInfoIfIdentityChanged(
+  requestAccountId: string | null,
+  retriesRemaining: number,
+): Promise<MainAccountInfoFetchResult | null> {
+  const currentAccountId = getMainChatgptAccountId();
+  if (currentAccountId === null || currentAccountId === requestAccountId) return null;
+  reconcileMainCodexAccountRuntimeState();
+  return retriesRemaining > 0
+    ? fetchMainAccountInfoAttempt(true, retriesRemaining - 1)
+    : { info: EMPTY_MAIN_ACCOUNT_INFO };
+}
+
+async function fetchMainAccountInfoAttempt(forceRefresh: boolean, retriesRemaining: number): Promise<MainAccountInfoFetchResult> {
+  reconcileMainCodexAccountRuntimeState();
+  const tokenRead = readCodexTokensResult();
+  if (tokenRead.status !== "ok") {
+    // A local read failure is NOT proof of sign-out: a missing file can be a non-atomic rewrite
+    // gap, and malformed JSON can be a half-written file. Clearing the cache and marking the
+    // account for reauth here destroyed healthy email/plan/quota state and pinned a working
+    // account as unusable. Preserve what we already know and let the caller retry; request
+    // routing stays fail-closed because getMainAccountToken() re-reads the file itself, and the
+    // account DTO still reports hasCredential=false while the file is unreadable.
+    const preserved = getMainAccountInfoCache();
+    return { info: preserved ?? EMPTY_MAIN_ACCOUNT_INFO };
   }
-  if (!forceRefresh && mainAccountCache && Date.now() - mainAccountCache.ts < MAIN_CACHE_TTL) {
-    return mainAccountCache;
+  const tokens = tokenRead.tokens;
+  const requestAccountId = extractAccountId(tokens.id_token, tokens.access_token) ?? (tokens.account_id || null);
+  const cached = getMainAccountInfoCache();
+  if (!forceRefresh && cached && Date.now() - cached.ts < MAIN_CACHE_TTL) {
+    return { info: cached };
   }
   try {
     const resp = await fetch("https://chatgpt.com/backend-api/wham/usage", {
@@ -269,20 +319,27 @@ export async function fetchMainAccountInfo(forceRefresh = false): Promise<{ emai
       signal: AbortSignal.timeout(8000),
     });
     if (!resp.ok) {
-      if (await isTerminalMainAuthResponse(resp)) {
-        mainAccountCache = null;
+      const terminalAuthFailure = await isTerminalMainAuthResponse(resp);
+      const retried = await retryMainAccountInfoIfIdentityChanged(requestAccountId, retriesRemaining);
+      if (retried) return retried;
+      if (terminalAuthFailure) {
+        clearMainAccountInfoCache();
         markAccountNeedsReauth(MAIN_CODEX_ACCOUNT_ID);
       }
-      return { email: null, plan: null, quota: null };
+      return { info: EMPTY_MAIN_ACCOUNT_INFO };
     }
     const data = (await resp.json()) as WhamUsageResponse;
+    const retried = await retryMainAccountInfoIfIdentityChanged(requestAccountId, retriesRemaining);
+    if (retried) return retried;
+    const quota = parseUsageQuota(data);
+    const freshResetCredits = quota?.resetCredits;
     const result = {
       email: data.email ?? null,
       plan: data.plan_type ?? null,
-      quota: parseUsageQuota(data),
+      quota,
       ts: Date.now(),
     };
-    mainAccountCache = result;
+    setMainAccountInfoCache(result);
     clearAccountNeedsReauth(MAIN_CODEX_ACCOUNT_ID);
     // Mirror main quota + plan into the shared stores so the rotation engine can
     // score and auto-switch the main account exactly like a pool account (Option A).
@@ -290,15 +347,21 @@ export async function fetchMainAccountInfo(forceRefresh = false): Promise<{ emai
     if (result.quota) {
       setAccountQuotaFromParsed(MAIN_CODEX_ACCOUNT_ID, result.quota);
     }
-    return result;
+    return {
+      info: result,
+      ...(freshResetCredits !== undefined ? { freshResetCredits } : {}),
+    };
   } catch {
-    return { email: null, plan: null, quota: null };
+    const retried = await retryMainAccountInfoIfIdentityChanged(requestAccountId, retriesRemaining);
+    return retried ?? { info: EMPTY_MAIN_ACCOUNT_INFO };
   }
 }
 
 interface PoolQuotaResult {
   quota: StoredAccountQuota | null;
   needsReauth: boolean;
+  /** Present only when this call's WHAM response included `rate_limit_reset_credits.available_count`. */
+  freshResetCredits?: number;
 }
 
 export interface CodexAuthAccountDto {
@@ -311,6 +374,10 @@ export interface CodexAuthAccountDto {
   quota: (StoredAccountQuota | (Omit<StoredAccountQuota, "updatedAt"> & { updatedAt: number })) | null;
   needsReauth?: boolean;
   hasCredential: boolean;
+  health: OAuthAccountHealth;
+  healthLabel: OAuthHealthLabel;
+  healthSummary: string;
+  healthAction?: string;
 }
 
 async function fetchPoolAccountQuota(accountId: string, forceRefresh = false, configuredPlan?: string): Promise<PoolQuotaResult> {
@@ -327,9 +394,14 @@ async function fetchPoolAccountQuota(accountId: string, forceRefresh = false, co
     if (!resp.ok) return { quota: existing ?? null, needsReauth: resp.status === 401 };
     const data = (await resp.json()) as WhamUsageResponse;
     const quota = parseUsageQuota({ ...data, plan_type: data.plan_type ?? configuredPlan });
+    const freshResetCredits = quota?.resetCredits;
     if (!quota) return { quota: existing ?? null, needsReauth: false };
     setAccountQuotaFromParsed(accountId, quota);
-    return { quota: getAccountQuota(accountId), needsReauth: false };
+    return {
+      quota: getAccountQuota(accountId),
+      needsReauth: false,
+      ...(freshResetCredits !== undefined ? { freshResetCredits } : {}),
+    };
   } catch (e) {
     if (e instanceof CodexCredentialGenerationConflictError || e instanceof CodexCredentialRefreshLockTimeoutError) return { quota: existing ?? null, needsReauth: false };
     if (e instanceof TokenRefreshError) return { quota: existing ?? null, needsReauth: true };
@@ -363,6 +435,10 @@ export async function primeCodexPoolQuotas(config: OcxConfig, reason: string): P
     || providerCodexAccountMode(OPENAI_CODEX_PROVIDER_ID, openai) !== "pool"
   ) return;
   if (primeInFlight) return primeInFlight;
+  // Seed the observed physical main identity before startup/lazy priming can populate quota or
+  // plan state. Otherwise the first post-startup account switch sees no previous identity and
+  // skips the purge that protects the stable __main__ alias.
+  reconcileMainCodexAccountRuntimeState();
   primeInFlight = (async () => {
     const runtimeConfig = getRuntimeConfig(config);
     const pool = (runtimeConfig.codexAccounts ?? []).filter(a => !a.isMain);
@@ -407,14 +483,20 @@ export async function listCodexAuthAccounts(config: OcxConfig, forceRefresh = fa
     return poolAccountDto(a, quotaResult, !!cred);
   });
   const hasMainCredential = readCodexTokens() !== null;
+  const mainNeedsReauth = !hasMainCredential || isAccountNeedsReauth(MAIN_CODEX_ACCOUNT_ID);
+  const mainHealth = projectCodexAccountHealth({
+    accountId: MAIN_CODEX_ACCOUNT_ID,
+    needsReauth: mainNeedsReauth,
+  });
   const main: CodexAuthAccountDto = {
     id: MAIN_CODEX_ACCOUNT_ID,
     email: maskEmail(mainInfo.email) ?? "Codex App login",
     plan: mainInfo.plan,
     isMain: true,
     hasCredential: hasMainCredential,
-    needsReauth: !hasMainCredential || isAccountNeedsReauth(MAIN_CODEX_ACCOUNT_ID),
+    needsReauth: mainNeedsReauth,
     quota: mainInfo.quota ? { ...quotaForPlan({ ...mainInfo.quota, updatedAt: Date.now() }, mainInfo.plan) } : null,
+    ...oauthAccountHealthFields("codex", MAIN_CODEX_ACCOUNT_ID, mainHealth),
   };
   return [main, ...withQuota];
 }
@@ -501,6 +583,21 @@ export async function handleCodexAuthAPI(
     return jsonResponse({ ok: true, id, alias: alias || null });
   }
 
+  // Manual escape from a quota cooldown. Injected Codex routing makes this proxy the only
+  // model path for Codex Desktop, so a cooldown that outlives the real upstream limit
+  // otherwise leaves editing config.toml as the user's only recovery.
+  //
+  // Existence is deliberately NOT disclosed: an unknown id returns 200 with cleared:false
+  // exactly like an account that simply had no live cooldown, so this route cannot be used
+  // to enumerate configured accounts. Cooldown state is runtime-only and independent of the
+  // account list, so 404 would carry no useful meaning anyway.
+  if (url.pathname === "/api/codex-auth/accounts/clear-cooldown" && req.method === "POST") {
+    const body = await req.json().catch(() => ({})) as { id?: unknown };
+    const id = typeof body.id === "string" ? body.id.trim() : "";
+    if (!id || !ACCOUNT_ID_RE.test(id)) return jsonResponse({ error: "Invalid account id format" }, 400);
+    return jsonResponse({ ok: true, id, cleared: clearCodexAccountCooldown(id) });
+  }
+
   if (url.pathname === "/api/codex-auth/active" && req.method === "PUT") {
     let body: { accountId: string | null };
     try { body = (await req.json()) as typeof body; } catch { return jsonResponse({ error: "Invalid JSON" }, 400); }
@@ -608,13 +705,23 @@ export async function handleCodexAuthAPI(
         return jsonResponse({ error: `Upstream error ${resp.status}` }, resp.status);
       }
       const result = safeResetCreditConsumeDto(await resp.json());
-      if (result.code === "reset") {
+      // After a successful redeem (or an idempotent already_redeemed), refresh WHAM usage
+      // and return remaining only when that refresh freshly parsed available_count.
+      // Do not fall back to a preserved cached resetCredits (failed/omitted refresh).
+      if (result.code === "reset" || result.code === "already_redeemed") {
+        let freshResetCredits: number | undefined;
         if (auth.isMain) {
-          await fetchMainAccountInfo(true);
+          ({ freshResetCredits } = await fetchMainAccountInfoAttempt(true, 1));
         } else {
           const account = configuredPoolAccount(getRuntimeConfig(config), body.accountId);
-          await fetchPoolAccountQuota(body.accountId, true, account?.plan);
+          ({ freshResetCredits } = await fetchPoolAccountQuota(body.accountId, true, account?.plan));
         }
+        return jsonResponse({
+          code: result.code,
+          ...(typeof freshResetCredits === "number" && Number.isFinite(freshResetCredits)
+            ? { remaining: freshResetCredits }
+            : {}),
+        });
       }
       return jsonResponse(result);
     } catch (e) {

package/src/codex/auth-collision.ts

@@ -1,25 +1,69 @@
-import { existsSync, readFileSync } from "node:fs";
+import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { getCodexAccountCredential } from "./account-store";
 import { loadConfig } from "../config";
 import { resolveCodexHomeDir } from "./home";
 import { extractAccountId } from "../oauth/chatgpt";
 
-export function readCodexTokens(): { access_token: string; account_id: string; id_token?: string } | null {
+export interface CodexTokens {
+  access_token: string;
+  account_id: string;
+  id_token?: string;
+}
+
+/**
+ * Why a read *outcome* and not just `Tokens | null`: callers need to tell a real sign-out apart
+ * from a transient read failure. A single null collapsed "file absent", "malformed JSON", and
+ * "read error" into one answer, so a half-written `auth.json` looked exactly like a logout and
+ * callers destroyed healthy cached account state because of it.
+ */
+export type CodexTokenReadResult =
+  | { status: "ok"; tokens: CodexTokens }
+  | { status: "missing" | "invalid" | "unreadable" };
+
+function hasErrnoCode(error: unknown, code: string): boolean {
+  return typeof error === "object" && error !== null && "code" in error
+    && (error as { code?: unknown }).code === code;
+}
+
+/**
+ * Reads the Codex CLI credential file and classifies the outcome. Reads once instead of doing an
+ * `existsSync` pre-check, so a file replaced between check and read cannot be misread as absent.
+ * Never returns or logs the raw error or any token material.
+ */
+export function readCodexTokensResult(): CodexTokenReadResult {
+  let raw: string;
   try {
-    const codexHome = resolveCodexHomeDir();
-    const authPath = join(codexHome, "auth.json");
-    if (!existsSync(authPath)) return null;
-    const j = JSON.parse(readFileSync(authPath, "utf-8")) as {
+    raw = readFileSync(join(resolveCodexHomeDir(), "auth.json"), "utf-8");
+  } catch (error) {
+    return { status: hasErrnoCode(error, "ENOENT") ? "missing" : "unreadable" };
+  }
+  try {
+    const j = JSON.parse(raw) as {
       tokens?: { access_token?: string; account_id?: string; id_token?: string };
     };
-    if (!j?.tokens?.access_token) return null;
+    if (!j?.tokens?.access_token) return { status: "invalid" };
     return {
-      access_token: j.tokens.access_token,
-      account_id: j.tokens.account_id ?? "",
-      id_token: j.tokens.id_token,
+      status: "ok",
+      tokens: {
+        access_token: j.tokens.access_token,
+        account_id: j.tokens.account_id ?? "",
+        id_token: j.tokens.id_token,
+      },
     };
-  } catch { return null; }
+  } catch {
+    return { status: "invalid" };
+  }
+}
+
+/**
+ * Compatibility wrapper: any usable-token check keeps the original null contract, which keeps
+ * request routing fail-closed. Only callers that must distinguish the failure reason should use
+ * `readCodexTokensResult()`.
+ */
+export function readCodexTokens(): CodexTokens | null {
+  const result = readCodexTokensResult();
+  return result.status === "ok" ? result.tokens : null;
 }
 
 export function getMainChatgptAccountId(): string | null {

package/src/codex/auth-context.ts

@@ -6,14 +6,18 @@ import {
 } from "./account-store";
 import { markAccountNeedsReauth } from "./account-runtime-state";
 import { isCodexAccountUsable } from "./account-usability";
+import { reconcileMainCodexAccountRuntimeState } from "./account-lifecycle";
 import { MAIN_CODEX_ACCOUNT_ID, getMainAccountToken } from "./main-account";
 import {
-  getCodexAccountCooldownUntil,
+  getCodexAccountHealthSnapshot,
   releaseCodexQuotaProbeLease,
   tryAcquireCodexQuotaProbeLease,
   pickLowestUsageCodexAccount,
   resolveCodexAccountForThreadDetailed,
 } from "./routing";
+import type { CodexCooldownSource } from "./routing";
+import { maskAccountId } from "../lib/privacy";
+import { formatErrorResponse } from "../bridge";
 import { getAccountQuota } from "./quota";
 import type { CodexAccountMode, OcxConfig, OcxProviderConfig } from "../types";
 import { FORWARD_HEADERS } from "../adapters/openai-responses";
@@ -94,15 +98,49 @@ export function hasCallerCodexBearer(headers: Headers): boolean {
 export class CodexAccountCooldownError extends Error {
   accountId: string;
   cooldownUntil: number;
+  cooldownSource?: CodexCooldownSource;
 
-  constructor(accountId: string, cooldownUntil: number) {
+  constructor(accountId: string, cooldownUntil: number, cooldownSource?: CodexCooldownSource) {
     super("Selected Codex account is cooling down");
     this.name = "CodexAccountCooldownError";
     this.accountId = accountId;
     this.cooldownUntil = cooldownUntil;
+    this.cooldownSource = cooldownSource;
   }
 }
 
+/**
+ * Human-readable account label for a client-visible error. NEVER the raw id: the proxy
+ * supports non-loopback binds (auth-cors.ts `isApiAuthRequired` requires a token there
+ * rather than refusing), so data-plane bodies can reach remote authenticated clients.
+ * The main login has no secret id, so it renders as the literal alias users type.
+ */
+export function cooldownAccountLabel(accountId: string): string {
+  return accountId === MAIN_CODEX_ACCOUNT_ID ? "main" : maskAccountId(accountId) ?? "account-…????";
+}
+
+/**
+ * Actionable message for a cooled-down account: until when, why, and how to escape.
+ * Shared by every transport so the WebSocket surface (Codex Desktop) says the same thing
+ * as HTTP. The bare "cooling down" string left users with no route but commenting out the
+ * injected `openai_base_url` in config.toml.
+ */
+export function cooldownErrorMessage(err: CodexAccountCooldownError): string {
+  const until = new Date(err.cooldownUntil).toISOString();
+  return `Selected Codex account (${cooldownAccountLabel(err.accountId)}) is cooling down until ${until}`
+    + ` (source: ${err.cooldownSource ?? "default"}).`
+    + ` Run 'ocx account list openai' to find the id, then`
+    + ` 'ocx account clear-cooldown openai <id>' to lift it, or switch accounts with 'ocx account use openai <id>'.`;
+}
+
+/** HTTP form of {@link cooldownErrorMessage}, carrying Retry-After for well-behaved clients. */
+export function cooldownErrorResponse(err: CodexAccountCooldownError, now = Date.now()): Response {
+  const res = formatErrorResponse(429, "rate_limit_error", cooldownErrorMessage(err));
+  const headers = new Headers(res.headers);
+  headers.set("Retry-After", String(Math.max(1, Math.ceil((err.cooldownUntil - now) / 1000))));
+  return new Response(res.body, { status: res.status, headers });
+}
+
 export class CodexThreadAffinityExpiredError extends Error {
   accountId: string;
 
@@ -131,6 +169,7 @@ export async function resolveCodexAuthContext(
     if (!hasCallerCodexBearer(headers)) throw new CodexDirectAuthenticationError();
     return { kind: "main", accountId: null };
   }
+  reconcileMainCodexAccountRuntimeState();
   const threadId = headers.get("x-codex-parent-thread-id");
   const resolution = options.excludeAccountId
     ? (() => {
@@ -153,14 +192,17 @@ export async function resolveCodexAuthContext(
       .then(({ primeCodexPoolQuotas }) => primeCodexPoolQuotas(config, "pre-route"))
       .catch(() => {});
   }
-  const cooldownUntil = getCodexAccountCooldownUntil(accountId);
+  // Snapshot (not just the deadline) so a refused request can report WHY it is cooled:
+  // a literal Retry-After reads very differently to a user than a reset-derived guess.
+  const cooldown = getCodexAccountHealthSnapshot(accountId);
+  const cooldownUntil = cooldown?.cooldownUntil;
   // A cooled-down account never sends traffic, so upstream recovery can never be
   // observed and the cooldown outlives the real limit. Admit one probe per
   // interval; its outcome decides whether the cooldown ends (#433).
   let probeLeaseId: string | undefined;
   if (cooldownUntil) {
     probeLeaseId = tryAcquireCodexQuotaProbeLease(accountId) ?? undefined;
-    if (!probeLeaseId) throw new CodexAccountCooldownError(accountId, cooldownUntil);
+    if (!probeLeaseId) throw new CodexAccountCooldownError(accountId, cooldownUntil, cooldown?.cooldownSource);
   }
 
   if (accountId === MAIN_CODEX_ACCOUNT_ID) {
@@ -203,8 +245,10 @@ export function assertCodexAuthContextNotCooled(ctx: CodexAuthContext | undefine
   if (ctx?.kind !== "pool" && ctx?.kind !== "main-pool") return;
   // A context holding the probe lease was deliberately admitted through the cooldown.
   if (ctx.probeLeaseId) return;
-  const cooldownUntil = getCodexAccountCooldownUntil(ctx.accountId);
-  if (cooldownUntil) throw new CodexAccountCooldownError(ctx.accountId, cooldownUntil);
+  const cooldown = getCodexAccountHealthSnapshot(ctx.accountId);
+  if (cooldown?.cooldownUntil) {
+    throw new CodexAccountCooldownError(ctx.accountId, cooldown.cooldownUntil, cooldown.cooldownSource);
+  }
 }
 
 export function applyCodexAuthContextToProvider(

package/src/codex/catalog/provider-fetch.ts

@@ -267,7 +267,8 @@ export async function fetchProviderModels(name: string, prov: OcxProviderConfig,
     if (liveResult.ok) {
       const available = filterCursorConfiguredModelsByLiveDiscovery(configured, liveResult.models);
       const result = available.length > 0 ? available : configured;
-      markProviderDiscoveryOk(name);
+      // Count what discovery actually returned, not the configured rows we fall back to.
+      markProviderDiscoveryOk(name, liveResult.models.length);
       setCached(name, result);
       return result;
     }
@@ -384,6 +385,9 @@ export async function fetchProviderModels(name: string, prov: OcxProviderConfig,
       ...catalogHintsFromModelsApiItem(name, m),
     }, contextCap))
       .filter(m => shouldExposeProviderModel(name, m.id));
+    // Capture the count BEFORE the alias/configured augmentation below pushes extra rows into
+    // `live`; otherwise configured entries would be reported as discovered ones.
+    const liveModelCount = live.length;
     const liveIds = new Set(live.map(m => m.id));
     // Dated-release aliases (Anthropic pattern): older models may appear in the live catalog
     // ONLY under their dated id (claude-haiku-4-5-20251001) while the config names the
@@ -412,7 +416,7 @@ export async function fetchProviderModels(name: string, prov: OcxProviderConfig,
       && !QUIET_AUTHORITATIVE_CATALOG_PROVIDERS.has(name)) {
       warnDroppedConfiguredIdsOnce(name, droppedConfiguredIds);
     }
-    markProviderDiscoveryOk(name);
+    markProviderDiscoveryOk(name, liveModelCount);
     setCached(name, live);
     return live;
   } catch (error) {