codex-multi-auth 0.1.9 → 1.1.11

package/dist/lib/codex-manager.js

@@ -6,7 +6,7 @@ import { createAuthorizationFlow, exchangeAuthorizationCode, parseAuthorizationI
 import { startLocalOAuthServer } from "./auth/server.js";
 import { copyTextToClipboard, openBrowserUrl } from "./auth/browser.js";
 import { promptAddAnotherAccount, promptLoginMode } from "./cli.js";
-import { extractAccountEmail, extractAccountId, formatAccountLabel, formatCooldown, formatWaitTime, getAccountIdCandidates, resolveRequestAccountId, sanitizeEmail, selectBestAccountCandidate, } from "./accounts.js";
+import { extractAccountEmail, extractAccountId, formatAccountLabel, formatCooldown, formatWaitTime, getAccountIdCandidates, resolveRequestAccountId, sanitizeEmail, selectBestAccountCandidate, shouldUpdateAccountIdFromToken, } from "./accounts.js";
 import { ACCOUNT_LIMITS } from "./constants.js";
 import { loadDashboardDisplaySettings, DEFAULT_DASHBOARD_DISPLAY_SETTINGS, } from "./dashboard-settings.js";
 import { evaluateForecastAccounts, isHardRefreshFailure, recommendForecastAccount, summarizeForecast, } from "./forecast.js";
@@ -219,6 +219,7 @@ function printUsage() {
         "  codex auth list",
         "  codex auth status",
         "  codex auth switch <index>",
+        "  codex auth best [--live] [--json] [--model <model>]",
         "  codex auth check",
         "  codex auth features",
         "  codex auth verify-flagged [--dry-run] [--json] [--no-restore]",
@@ -273,6 +274,7 @@ const IMPLEMENTED_FEATURES = [
     { id: 38, name: "Dashboard display customization" },
     { id: 39, name: "Unified color/theme runtime (v2 UI)" },
     { id: 40, name: "OAuth browser-first flow with manual callback fallback" },
+    { id: 41, name: "Auto-switch to best account command" },
 ];
 function runFeaturesReport() {
     console.log(`Implemented features (${IMPLEMENTED_FEATURES.length})`);
@@ -342,6 +344,46 @@ function hasUniqueQuotaAccountId(accounts, account) {
     }
     return matchCount === 1;
 }
+function buildQuotaEmailFallbackState(accounts) {
+    const stateByEmail = new Map();
+    for (const account of accounts) {
+        const email = normalizeQuotaEmail(account.email);
+        if (!email)
+            continue;
+        const existing = stateByEmail.get(email);
+        if (existing) {
+            existing.matchingCount += 1;
+            const accountId = normalizeQuotaAccountId(account.accountId);
+            if (accountId) {
+                existing.distinctAccountIds.add(accountId);
+            }
+            continue;
+        }
+        const distinctAccountIds = new Set();
+        const accountId = normalizeQuotaAccountId(account.accountId);
+        if (accountId) {
+            distinctAccountIds.add(accountId);
+        }
+        stateByEmail.set(email, {
+            matchingCount: 1,
+            distinctAccountIds,
+        });
+    }
+    return stateByEmail;
+}
+function hasSafeQuotaEmailFallback(emailFallbackState, account) {
+    const email = normalizeQuotaEmail(account.email);
+    if (!email)
+        return false;
+    const state = emailFallbackState.get(email);
+    if (!state)
+        return false;
+    // size > 1 only matters when multiple accounts share the same email but
+    // disagree on accountId; a single matching account already implies size <= 1.
+    if (state.distinctAccountIds.size > 1)
+        return false;
+    return state.matchingCount === 1;
+}
 function quotaCacheEntryToSnapshot(entry) {
     return {
         status: entry.status,
@@ -409,20 +451,22 @@ function formatAccountQuotaSummary(entry) {
     }
     return formatQuotaSnapshotLine(quotaCacheEntryToSnapshot(entry));
 }
-function getQuotaCacheEntryForAccount(cache, account, accounts) {
-    const email = normalizeQuotaEmail(account.email);
-    if (email && cache.byEmail[email]) {
-        return cache.byEmail[email] ?? null;
-    }
+function getQuotaCacheEntryForAccount(cache, account, accounts, emailFallbackState = buildQuotaEmailFallbackState(accounts)) {
     const accountId = normalizeQuotaAccountId(account.accountId);
     if (accountId &&
         hasUniqueQuotaAccountId(accounts, account) &&
         cache.byAccountId[accountId]) {
         return cache.byAccountId[accountId] ?? null;
     }
+    const email = normalizeQuotaEmail(account.email);
+    if (email &&
+        hasSafeQuotaEmailFallback(emailFallbackState, account) &&
+        cache.byEmail[email]) {
+        return cache.byEmail[email] ?? null;
+    }
     return null;
 }
-function updateQuotaCacheForAccount(cache, account, snapshot, accounts) {
+function updateQuotaCacheForAccount(cache, account, snapshot, accounts, emailFallbackState = buildQuotaEmailFallbackState(accounts)) {
     const nextEntry = {
         updatedAt: Date.now(),
         status: snapshot.status,
@@ -440,33 +484,67 @@ function updateQuotaCacheForAccount(cache, account, snapshot, accounts) {
         },
     };
     let changed = false;
+    const accountId = normalizeQuotaAccountId(account.accountId);
+    const hasUniqueAccountId = accountId !== null && hasUniqueQuotaAccountId(accounts, account);
+    if (hasUniqueAccountId) {
+        cache.byAccountId[accountId] = nextEntry;
+        changed = true;
+    }
     const email = normalizeQuotaEmail(account.email);
-    if (email) {
+    if (email &&
+        hasSafeQuotaEmailFallback(emailFallbackState, account) &&
+        !hasUniqueAccountId) {
         cache.byEmail[email] = nextEntry;
         changed = true;
-        return changed;
     }
-    const accountId = normalizeQuotaAccountId(account.accountId);
-    if (accountId && hasUniqueQuotaAccountId(accounts, account)) {
-        cache.byAccountId[accountId] = nextEntry;
+    else if (email && cache.byEmail[email]) {
+        delete cache.byEmail[email];
         changed = true;
     }
     return changed;
 }
+function cloneQuotaCacheData(cache) {
+    // Shallow spreading is safe because quota cache entries are always replaced,
+    // never mutated in-place.
+    return {
+        byAccountId: { ...cache.byAccountId },
+        byEmail: { ...cache.byEmail },
+    };
+}
+function pruneUnsafeQuotaEmailCacheEntry(cache, email, accounts, emailFallbackState = buildQuotaEmailFallbackState(accounts)) {
+    const normalizedEmail = normalizeQuotaEmail(email);
+    if (!normalizedEmail || !cache.byEmail[normalizedEmail]) {
+        return false;
+    }
+    const hasSafeFallbackAccount = accounts.some((account) => normalizeQuotaEmail(account.email) === normalizedEmail &&
+        hasSafeQuotaEmailFallback(emailFallbackState, account));
+    if (hasSafeFallbackAccount) {
+        return false;
+    }
+    delete cache.byEmail[normalizedEmail];
+    return true;
+}
 const DEFAULT_MENU_QUOTA_REFRESH_TTL_MS = 5 * 60_000;
 const MENU_QUOTA_REFRESH_MODEL = "gpt-5-codex";
-function resolveMenuQuotaProbeInput(account, cache, maxAgeMs, now, accounts) {
+function resolveMenuQuotaProbeInput(account, cache, maxAgeMs, now, accounts, emailFallbackState = buildQuotaEmailFallbackState(accounts)) {
     if (account.enabled === false)
         return null;
     if (!hasUsableAccessToken(account, now))
         return null;
-    const existing = getQuotaCacheEntryForAccount(cache, account, accounts);
+    const existing = getQuotaCacheEntryForAccount(cache, account, accounts, emailFallbackState);
     if (existing &&
         typeof existing.updatedAt === "number" &&
         Number.isFinite(existing.updatedAt) &&
         now - existing.updatedAt < maxAgeMs) {
         return null;
     }
+    // Menu auto-refresh is cache-backed, so only probe when the result can be
+    // written behind a safe lookup key for later reuse.
+    const canStore = (normalizeQuotaAccountId(account.accountId) !== null &&
+        hasUniqueQuotaAccountId(accounts, account)) ||
+        hasSafeQuotaEmailFallback(emailFallbackState, account);
+    if (!canStore)
+        return null;
     const accessToken = account.accessToken;
     const accountId = accessToken
         ? (account.accountId ?? extractAccountId(accessToken))
@@ -475,10 +553,10 @@ function resolveMenuQuotaProbeInput(account, cache, maxAgeMs, now, accounts) {
         return null;
     return { accountId, accessToken };
 }
-function collectMenuQuotaRefreshTargets(storage, cache, maxAgeMs, now = Date.now()) {
+function collectMenuQuotaRefreshTargets(storage, cache, maxAgeMs, now = Date.now(), emailFallbackState = buildQuotaEmailFallbackState(storage.accounts)) {
     const targets = [];
     for (const account of storage.accounts) {
-        const probeInput = resolveMenuQuotaProbeInput(account, cache, maxAgeMs, now, storage.accounts);
+        const probeInput = resolveMenuQuotaProbeInput(account, cache, maxAgeMs, now, storage.accounts, emailFallbackState);
         if (!probeInput)
             continue;
         targets.push({
@@ -490,9 +568,10 @@ function collectMenuQuotaRefreshTargets(storage, cache, maxAgeMs, now = Date.now
     return targets;
 }
 function countMenuQuotaRefreshTargets(storage, cache, maxAgeMs, now = Date.now()) {
+    const emailFallbackState = buildQuotaEmailFallbackState(storage.accounts);
     let count = 0;
     for (const account of storage.accounts) {
-        if (resolveMenuQuotaProbeInput(account, cache, maxAgeMs, now, storage.accounts)) {
+        if (resolveMenuQuotaProbeInput(account, cache, maxAgeMs, now, storage.accounts, emailFallbackState)) {
             count += 1;
         }
     }
@@ -502,8 +581,10 @@ async function refreshQuotaCacheForMenu(storage, cache, maxAgeMs, onProgress) {
     if (storage.accounts.length === 0) {
         return cache;
     }
+    const emailFallbackState = buildQuotaEmailFallbackState(storage.accounts);
+    const nextCache = cloneQuotaCacheData(cache);
     const now = Date.now();
-    const targets = collectMenuQuotaRefreshTargets(storage, cache, maxAgeMs, now);
+    const targets = collectMenuQuotaRefreshTargets(storage, nextCache, maxAgeMs, now, emailFallbackState);
     const total = targets.length;
     let processed = 0;
     onProgress?.(processed, total);
@@ -518,17 +599,16 @@ async function refreshQuotaCacheForMenu(storage, cache, maxAgeMs, onProgress) {
                 model: MENU_QUOTA_REFRESH_MODEL,
             });
             changed =
-                updateQuotaCacheForAccount(cache, target.account, snapshot, storage.accounts) ||
-                    changed;
+                updateQuotaCacheForAccount(nextCache, target.account, snapshot, storage.accounts, emailFallbackState) || changed;
         }
         catch {
             // Keep existing cached values if probing fails.
         }
     }
     if (changed) {
-        await saveQuotaCache(cache);
+        await saveQuotaCache(nextCache);
     }
-    return cache;
+    return nextCache;
 }
 const ACCESS_TOKEN_FRESH_WINDOW_MS = 5 * 60 * 1000;
 function hasUsableAccessToken(account, now) {
@@ -641,9 +721,10 @@ function toExistingAccountInfo(storage, quotaCache, displaySettings) {
     const now = Date.now();
     const activeIndex = resolveActiveIndex(storage, "codex");
     const layoutMode = resolveMenuLayoutMode(displaySettings);
+    const emailFallbackState = buildQuotaEmailFallbackState(storage.accounts);
     const baseAccounts = storage.accounts.map((account, index) => {
         const entry = quotaCache
-            ? getQuotaCacheEntryForAccount(quotaCache, account, storage.accounts)
+            ? getQuotaCacheEntryForAccount(quotaCache, account, storage.accounts, emailFallbackState)
             : null;
         return {
             index,
@@ -719,6 +800,35 @@ function resolveAccountSelection(tokens) {
         accountLabel: best.label,
     };
 }
+function resolveStoredAccountIdentity(storedAccountId, storedAccountIdSource, tokenAccountId) {
+    const accountId = resolveRequestAccountId(storedAccountId, storedAccountIdSource, tokenAccountId);
+    if (!accountId) {
+        return {};
+    }
+    if (!shouldUpdateAccountIdFromToken(storedAccountIdSource, storedAccountId)) {
+        return {
+            accountId,
+            accountIdSource: storedAccountIdSource,
+        };
+    }
+    return {
+        accountId,
+        accountIdSource: accountId === tokenAccountId ? "token" : storedAccountIdSource,
+    };
+}
+function applyTokenAccountIdentity(account, tokenAccountId) {
+    const nextIdentity = resolveStoredAccountIdentity(account.accountId, account.accountIdSource, tokenAccountId);
+    if (!nextIdentity.accountId) {
+        return false;
+    }
+    if (nextIdentity.accountId === account.accountId
+        && nextIdentity.accountIdSource === account.accountIdSource) {
+        return false;
+    }
+    account.accountId = nextIdentity.accountId;
+    account.accountIdSource = nextIdentity.accountIdSource;
+    return true;
+}
 async function promptManualCallback(state) {
     if (!input.isTTY || !output.isTTY) {
         return null;
@@ -1222,6 +1332,7 @@ async function runHealthCheck(options = {}) {
     const probeModel = options.model?.trim() || "gpt-5-codex";
     const display = options.display ?? DEFAULT_DASHBOARD_DISPLAY_SETTINGS;
     const quotaCache = liveProbe ? await loadQuotaCache() : null;
+    const workingQuotaCache = quotaCache ? cloneQuotaCacheData(quotaCache) : null;
     let quotaCacheChanged = false;
     setStoragePath(null);
     const storage = await loadAccounts();
@@ -1229,6 +1340,9 @@ async function runHealthCheck(options = {}) {
         console.log("No accounts configured.");
         return;
     }
+    let quotaEmailFallbackState = liveProbe && quotaCache
+        ? buildQuotaEmailFallbackState(storage.accounts)
+        : null;
     let changed = false;
     let ok = 0;
     let failed = 0;
@@ -1271,9 +1385,9 @@ async function runHealthCheck(options = {}) {
                             accessToken: currentAccessToken,
                             model: probeModel,
                         });
-                        if (quotaCache) {
+                        if (workingQuotaCache) {
                             quotaCacheChanged =
-                                updateQuotaCacheForAccount(quotaCache, account, snapshot, storage.accounts) || quotaCacheChanged;
+                                updateQuotaCacheForAccount(workingQuotaCache, account, snapshot, storage.accounts, quotaEmailFallbackState ?? undefined) || quotaCacheChanged;
                         }
                         healthDetail = formatQuotaSnapshotForDashboard(snapshot, display);
                     }
@@ -1297,6 +1411,8 @@ async function runHealthCheck(options = {}) {
         if (result.type === "success") {
             const tokenAccountId = extractAccountId(result.access);
             const nextEmail = sanitizeEmail(extractAccountEmail(result.access, result.idToken));
+            const previousEmail = account.email;
+            let accountIdentityChanged = false;
             if (account.refreshToken !== result.refresh) {
                 account.refreshToken = result.refresh;
                 changed = true;
@@ -1312,16 +1428,21 @@ async function runHealthCheck(options = {}) {
             if (nextEmail && nextEmail !== account.email) {
                 account.email = nextEmail;
                 changed = true;
+                accountIdentityChanged = true;
             }
-            if (tokenAccountId && tokenAccountId !== account.accountId) {
-                account.accountId = tokenAccountId;
-                account.accountIdSource = "token";
+            if (applyTokenAccountIdentity(account, tokenAccountId)) {
                 changed = true;
+                accountIdentityChanged = true;
             }
             if (account.enabled === false) {
                 account.enabled = true;
                 changed = true;
             }
+            if (accountIdentityChanged && liveProbe && workingQuotaCache) {
+                quotaEmailFallbackState = buildQuotaEmailFallbackState(storage.accounts);
+                quotaCacheChanged =
+                    pruneUnsafeQuotaEmailCacheEntry(workingQuotaCache, previousEmail, storage.accounts, quotaEmailFallbackState) || quotaCacheChanged;
+            }
             account.lastUsed = Date.now();
             if (i === activeIndex) {
                 activeAccountRefreshed = true;
@@ -1341,9 +1462,9 @@ async function runHealthCheck(options = {}) {
                             accessToken: result.access,
                             model: probeModel,
                         });
-                        if (quotaCache) {
+                        if (workingQuotaCache) {
                             quotaCacheChanged =
-                                updateQuotaCacheForAccount(quotaCache, account, snapshot, storage.accounts) || quotaCacheChanged;
+                                updateQuotaCacheForAccount(workingQuotaCache, account, snapshot, storage.accounts, quotaEmailFallbackState ?? undefined) || quotaCacheChanged;
                         }
                         healthyMessage = formatQuotaSnapshotForDashboard(snapshot, display);
                     }
@@ -1377,8 +1498,8 @@ async function runHealthCheck(options = {}) {
     if (!display.showPerAccountRows) {
         console.log(stylePromptText("Per-account lines are hidden in dashboard settings.", "muted"));
     }
-    if (quotaCache && quotaCacheChanged) {
-        await saveQuotaCache(quotaCache);
+    if (workingQuotaCache && quotaCacheChanged) {
+        await saveQuotaCache(workingQuotaCache);
     }
     if (changed) {
         await saveAccounts(storage);
@@ -1413,6 +1534,21 @@ function printForecastUsage() {
         "  --model, -m        Probe model for live mode (default: gpt-5-codex)",
     ].join("\n"));
 }
+function printBestUsage() {
+    console.log([
+        "Usage:",
+        "  codex auth best [--live] [--json] [--model <model>]",
+        "",
+        "Options:",
+        "  --live, -l         Probe live quota headers via Codex backend before switching",
+        "  --json, -j         Print machine-readable JSON output",
+        "  --model, -m        Probe model for live mode (default: gpt-5-codex)",
+        "",
+        "Behavior:",
+        "  - Chooses the healthiest account using forecast scoring",
+        "  - Switches to the recommended account when it is not already active",
+    ].join("\n"));
+}
 function printFixUsage() {
     console.log([
         "Usage:",
@@ -1486,6 +1622,48 @@ function parseForecastArgs(args) {
     }
     return { ok: true, options };
 }
+function parseBestArgs(args) {
+    const options = {
+        live: false,
+        json: false,
+        model: "gpt-5-codex",
+        modelProvided: false,
+    };
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (!arg)
+            continue;
+        if (arg === "--live" || arg === "-l") {
+            options.live = true;
+            continue;
+        }
+        if (arg === "--json" || arg === "-j") {
+            options.json = true;
+            continue;
+        }
+        if (arg === "--model" || arg === "-m") {
+            const value = args[i + 1];
+            if (!value) {
+                return { ok: false, message: "Missing value for --model" };
+            }
+            options.model = value;
+            options.modelProvided = true;
+            i += 1;
+            continue;
+        }
+        if (arg.startsWith("--model=")) {
+            const value = arg.slice("--model=".length).trim();
+            if (!value) {
+                return { ok: false, message: "Missing value for --model" };
+            }
+            options.model = value;
+            options.modelProvided = true;
+            continue;
+        }
+        return { ok: false, message: `Unknown option: ${arg}` };
+    }
+    return { ok: true, options };
+}
 function parseFixArgs(args) {
     const options = {
         dryRun: false,
@@ -1698,6 +1876,7 @@ async function runForecast(args) {
     const options = parsedArgs.options;
     const display = DEFAULT_DASHBOARD_DISPLAY_SETTINGS;
     const quotaCache = options.live ? await loadQuotaCache() : null;
+    const workingQuotaCache = quotaCache ? cloneQuotaCacheData(quotaCache) : null;
     let quotaCacheChanged = false;
     setStoragePath(null);
     const storage = await loadAccounts();
@@ -1705,6 +1884,9 @@ async function runForecast(args) {
         console.log("No accounts configured.");
         return 0;
     }
+    const quotaEmailFallbackState = options.live && quotaCache
+        ? buildQuotaEmailFallbackState(storage.accounts)
+        : null;
     const now = Date.now();
     const activeIndex = resolveActiveIndex(storage, "codex");
     const refreshFailures = new Map();
@@ -1741,11 +1923,11 @@ async function runForecast(args) {
                 model: options.model,
             });
             liveQuotaByIndex.set(i, liveQuota);
-            if (quotaCache) {
+            if (workingQuotaCache) {
                 const account = storage.accounts[i];
                 if (account) {
                     quotaCacheChanged =
-                        updateQuotaCacheForAccount(quotaCache, account, liveQuota, storage.accounts) || quotaCacheChanged;
+                        updateQuotaCacheForAccount(workingQuotaCache, account, liveQuota, storage.accounts, quotaEmailFallbackState ?? undefined) || quotaCacheChanged;
                 }
             }
         }
@@ -1766,8 +1948,8 @@ async function runForecast(args) {
     const summary = summarizeForecast(forecastResults);
     const recommendation = recommendForecastAccount(forecastResults);
     if (options.json) {
-        if (quotaCache && quotaCacheChanged) {
-            await saveQuotaCache(quotaCache);
+        if (workingQuotaCache && quotaCacheChanged) {
+            await saveQuotaCache(workingQuotaCache);
         }
         console.log(JSON.stringify({
             command: "forecast",
@@ -1837,8 +2019,8 @@ async function runForecast(args) {
             console.log(`  ${stylePromptText("-", "warning")} ${stylePromptText(error, "muted")}`);
         }
     }
-    if (quotaCache && quotaCacheChanged) {
-        await saveQuotaCache(quotaCache);
+    if (workingQuotaCache && quotaCacheChanged) {
+        await saveQuotaCache(workingQuotaCache);
     }
     return 0;
 }
@@ -2022,7 +2204,8 @@ function findExistingAccountIndexForFlagged(storage, flagged, nextRefreshToken,
 }
 function upsertRecoveredFlaggedAccount(storage, flagged, refreshResult, now) {
     const nextEmail = sanitizeEmail(extractAccountEmail(refreshResult.access, refreshResult.idToken)) ?? flagged.email;
-    const nextAccountId = extractAccountId(refreshResult.access) ?? flagged.accountId;
+    const tokenAccountId = extractAccountId(refreshResult.access);
+    const { accountId: nextAccountId, accountIdSource: nextAccountIdSource } = resolveStoredAccountIdentity(flagged.accountId, flagged.accountIdSource, tokenAccountId);
     const existingIndex = findExistingAccountIndexForFlagged(storage, flagged, refreshResult.refresh, nextAccountId, nextEmail);
     if (existingIndex >= 0) {
         const existing = storage.accounts[existingIndex];
@@ -2046,9 +2229,11 @@ function upsertRecoveredFlaggedAccount(storage, flagged, refreshResult, now) {
             existing.email = nextEmail;
             changed = true;
         }
-        if (nextAccountId && nextAccountId !== existing.accountId) {
+        if (nextAccountId !== undefined &&
+            ((nextAccountId !== existing.accountId)
+                || (nextAccountIdSource !== existing.accountIdSource))) {
             existing.accountId = nextAccountId;
-            existing.accountIdSource = "token";
+            existing.accountIdSource = nextAccountIdSource;
             changed = true;
         }
         if (existing.enabled === false) {
@@ -2078,7 +2263,7 @@ function upsertRecoveredFlaggedAccount(storage, flagged, refreshResult, now) {
         accessToken: refreshResult.access,
         expiresAt: refreshResult.expires,
         accountId: nextAccountId,
-        accountIdSource: nextAccountId ? "token" : flagged.accountIdSource,
+        accountIdSource: nextAccountIdSource,
         accountLabel: flagged.accountLabel,
         email: nextEmail,
         addedAt: flagged.addedAt ?? now,
@@ -2146,13 +2331,15 @@ async function runVerifyFlagged(args) {
             const { index: i, flagged, label, result } = check;
             if (result.type === "success") {
                 if (!options.restore) {
+                    const tokenAccountId = extractAccountId(result.access);
+                    const nextIdentity = resolveStoredAccountIdentity(flagged.accountId, flagged.accountIdSource, tokenAccountId);
                     const nextFlagged = {
                         ...flagged,
                         refreshToken: result.refresh,
                         accessToken: result.access,
                         expiresAt: result.expires,
-                        accountId: extractAccountId(result.access) ?? flagged.accountId,
-                        accountIdSource: extractAccountId(result.access) ? "token" : flagged.accountIdSource,
+                        accountId: nextIdentity.accountId,
+                        accountIdSource: nextIdentity.accountIdSource,
                         email: sanitizeEmail(extractAccountEmail(result.access, result.idToken)) ?? flagged.email,
                         lastUsed: now,
                         lastError: undefined,
@@ -2181,13 +2368,15 @@ async function runVerifyFlagged(args) {
                     });
                     continue;
                 }
+                const tokenAccountId = extractAccountId(result.access);
+                const nextIdentity = resolveStoredAccountIdentity(flagged.accountId, flagged.accountIdSource, tokenAccountId);
                 const updatedFlagged = {
                     ...flagged,
                     refreshToken: result.refresh,
                     accessToken: result.access,
                     expiresAt: result.expires,
-                    accountId: extractAccountId(result.access) ?? flagged.accountId,
-                    accountIdSource: extractAccountId(result.access) ? "token" : flagged.accountIdSource,
+                    accountId: nextIdentity.accountId,
+                    accountIdSource: nextIdentity.accountIdSource,
                     email: sanitizeEmail(extractAccountEmail(result.access, result.idToken)) ?? flagged.email,
                     lastUsed: now,
                     lastError: upsertResult.message,
@@ -2317,6 +2506,7 @@ async function runFix(args) {
     const options = parsedArgs.options;
     const display = DEFAULT_DASHBOARD_DISPLAY_SETTINGS;
     const quotaCache = options.live ? await loadQuotaCache() : null;
+    const workingQuotaCache = quotaCache ? cloneQuotaCacheData(quotaCache) : null;
     let quotaCacheChanged = false;
     setStoragePath(null);
     const storage = await loadAccounts();
@@ -2324,6 +2514,9 @@ async function runFix(args) {
         console.log("No accounts configured.");
         return 0;
     }
+    let quotaEmailFallbackState = options.live && quotaCache
+        ? buildQuotaEmailFallbackState(storage.accounts)
+        : null;
     const now = Date.now();
     const activeIndex = resolveActiveIndex(storage, "codex");
     let changed = false;
@@ -2357,9 +2550,9 @@ async function runFix(args) {
                             accessToken: currentAccessToken,
                             model: options.model,
                         });
-                        if (quotaCache) {
+                        if (workingQuotaCache) {
                             quotaCacheChanged =
-                                updateQuotaCacheForAccount(quotaCache, account, snapshot, storage.accounts) || quotaCacheChanged;
+                                updateQuotaCacheForAccount(workingQuotaCache, account, snapshot, storage.accounts, quotaEmailFallbackState ?? undefined) || quotaCacheChanged;
                         }
                         reports.push({
                             index: i,
@@ -2397,7 +2590,9 @@ async function runFix(args) {
         if (refreshResult.type === "success") {
             const nextEmail = sanitizeEmail(extractAccountEmail(refreshResult.access, refreshResult.idToken));
             const nextAccountId = extractAccountId(refreshResult.access);
+            const previousEmail = account.email;
             let accountChanged = false;
+            let accountIdentityChanged = false;
             if (account.refreshToken !== refreshResult.refresh) {
                 account.refreshToken = refreshResult.refresh;
                 accountChanged = true;
@@ -2413,14 +2608,19 @@ async function runFix(args) {
             if (nextEmail && nextEmail !== account.email) {
                 account.email = nextEmail;
                 accountChanged = true;
+                accountIdentityChanged = true;
             }
-            if (!account.accountId && nextAccountId) {
-                account.accountId = nextAccountId;
-                account.accountIdSource = "token";
+            if (applyTokenAccountIdentity(account, nextAccountId)) {
                 accountChanged = true;
+                accountIdentityChanged = true;
             }
             if (accountChanged)
                 changed = true;
+            if (accountIdentityChanged && options.live && workingQuotaCache) {
+                quotaEmailFallbackState = buildQuotaEmailFallbackState(storage.accounts);
+                quotaCacheChanged =
+                    pruneUnsafeQuotaEmailCacheEntry(workingQuotaCache, previousEmail, storage.accounts, quotaEmailFallbackState) || quotaCacheChanged;
+            }
             if (options.live) {
                 const probeAccountId = account.accountId ?? nextAccountId;
                 if (probeAccountId) {
@@ -2430,9 +2630,9 @@ async function runFix(args) {
                             accessToken: refreshResult.access,
                             model: options.model,
                         });
-                        if (quotaCache) {
+                        if (workingQuotaCache) {
                             quotaCacheChanged =
-                                updateQuotaCacheForAccount(quotaCache, account, snapshot, storage.accounts) || quotaCacheChanged;
+                                updateQuotaCacheForAccount(workingQuotaCache, account, snapshot, storage.accounts, quotaEmailFallbackState ?? undefined) || quotaCacheChanged;
                         }
                         reports.push({
                             index: i,
@@ -2521,8 +2721,8 @@ async function runFix(args) {
         await saveAccounts(storage);
     }
     if (options.json) {
-        if (quotaCache && quotaCacheChanged) {
-            await saveQuotaCache(quotaCache);
+        if (workingQuotaCache && quotaCacheChanged) {
+            await saveQuotaCache(workingQuotaCache);
         }
         console.log(JSON.stringify({
             command: "fix",
@@ -2588,8 +2788,8 @@ async function runFix(args) {
             console.log(`${stylePromptText("Note:", "accent")} ${stylePromptText(recommendation.reason, "muted")}`);
         }
     }
-    if (quotaCache && quotaCacheChanged) {
-        await saveQuotaCache(quotaCache);
+    if (workingQuotaCache && quotaCacheChanged) {
+        await saveQuotaCache(workingQuotaCache);
     }
     if (changed && options.dryRun) {
         console.log(`\n${stylePromptText("Preview only: no changes were saved.", "warning")}`);
@@ -3027,10 +3227,7 @@ async function runDoctor(args) {
                             activeAccount.expiresAt = refreshResult.expires;
                             if (refreshedEmail)
                                 activeAccount.email = refreshedEmail;
-                            if (refreshedAccountId) {
-                                activeAccount.accountId = refreshedAccountId;
-                                activeAccount.accountIdSource = "token";
-                            }
+                            applyTokenAccountIdentity(activeAccount, refreshedAccountId);
                             syncAccessToken = refreshResult.access;
                             syncRefreshToken = refreshResult.refresh;
                             syncExpiresAt = refreshResult.expires;
@@ -3349,6 +3546,23 @@ async function runSwitch(args) {
         console.error(`Account ${parsed} not found.`);
         return 1;
     }
+    const { synced, wasDisabled } = await persistAndSyncSelectedAccount({
+        storage,
+        targetIndex,
+        parsed,
+        switchReason: "rotation",
+    });
+    if (!synced) {
+        console.warn(`Switched account ${parsed} locally, but Codex auth sync did not complete. Multi-auth routing will still use this account.`);
+    }
+    console.log(`Switched to account ${parsed}: ${formatAccountLabel(account, targetIndex)}${wasDisabled ? " (re-enabled)" : ""}`);
+    return 0;
+}
+async function persistAndSyncSelectedAccount({ storage, targetIndex, parsed, switchReason, initialSyncIdToken, }) {
+    const account = storage.accounts[targetIndex];
+    if (!account) {
+        throw new Error(`Account ${parsed} not found.`);
+    }
     storage.activeIndex = targetIndex;
     storage.activeIndexByFamily = storage.activeIndexByFamily ?? {};
     for (const family of MODEL_FAMILIES) {
@@ -3362,7 +3576,7 @@ async function runSwitch(args) {
     let syncAccessToken = account.accessToken;
     let syncRefreshToken = account.refreshToken;
     let syncExpiresAt = account.expiresAt;
-    let syncIdToken;
+    let syncIdToken = initialSyncIdToken;
     if (!hasUsableAccessToken(account, switchNow)) {
         const refreshResult = await queuedRefresh(account.refreshToken);
         if (refreshResult.type === "success") {
@@ -3380,10 +3594,7 @@ async function runSwitch(args) {
             if (nextEmail && nextEmail !== account.email) {
                 account.email = nextEmail;
             }
-            if (tokenAccountId && tokenAccountId !== account.accountId) {
-                account.accountId = tokenAccountId;
-                account.accountIdSource = "token";
-            }
+            applyTokenAccountIdentity(account, tokenAccountId);
             syncAccessToken = refreshResult.access;
             syncRefreshToken = refreshResult.refresh;
             syncExpiresAt = refreshResult.expires;
@@ -3394,7 +3605,7 @@ async function runSwitch(args) {
         }
     }
     account.lastUsed = switchNow;
-    account.lastSwitchReason = "rotation";
+    account.lastSwitchReason = switchReason;
     await saveAccounts(storage);
     const synced = await setCodexCliActiveSelection({
         accountId: account.accountId,
@@ -3404,10 +3615,224 @@ async function runSwitch(args) {
         expiresAt: syncExpiresAt,
         ...(syncIdToken ? { idToken: syncIdToken } : {}),
     });
-    if (!synced) {
-        console.warn(`Switched account ${parsed} locally, but Codex auth sync did not complete. Multi-auth routing will still use this account.`);
+    return { synced, wasDisabled };
+}
+async function runBest(args) {
+    if (args.includes("--help") || args.includes("-h")) {
+        printBestUsage();
+        return 0;
+    }
+    const parsedArgs = parseBestArgs(args);
+    if (!parsedArgs.ok) {
+        console.error(parsedArgs.message);
+        printBestUsage();
+        return 1;
+    }
+    const options = parsedArgs.options;
+    if (options.modelProvided && !options.live) {
+        console.error("--model requires --live for codex auth best");
+        printBestUsage();
+        return 1;
+    }
+    setStoragePath(null);
+    const storage = await loadAccounts();
+    if (!storage || storage.accounts.length === 0) {
+        if (options.json) {
+            console.log(JSON.stringify({ error: "No accounts configured." }, null, 2));
+        }
+        else {
+            console.log("No accounts configured.");
+        }
+        return 1;
+    }
+    const now = Date.now();
+    const refreshFailures = new Map();
+    const liveQuotaByIndex = new Map();
+    const probeIdTokenByIndex = new Map();
+    const probeRefreshedIndices = new Set();
+    const probeErrors = [];
+    let changed = false;
+    const printProbeNotes = () => {
+        if (probeErrors.length === 0)
+            return;
+        console.log(`Live check notes (${probeErrors.length}):`);
+        for (const error of probeErrors) {
+            console.log(`  - ${error}`);
+        }
+    };
+    const persistProbeChangesIfNeeded = async () => {
+        if (!changed)
+            return;
+        await saveAccounts(storage);
+        changed = false;
+    };
+    for (let i = 0; i < storage.accounts.length; i += 1) {
+        const account = storage.accounts[i];
+        if (!account || !options.live)
+            continue;
+        if (account.enabled === false)
+            continue;
+        let probeAccessToken = account.accessToken;
+        let probeAccountId = account.accountId ?? extractAccountId(account.accessToken);
+        if (!hasUsableAccessToken(account, now)) {
+            const refreshResult = await queuedRefresh(account.refreshToken);
+            if (refreshResult.type !== "success") {
+                refreshFailures.set(i, {
+                    ...refreshResult,
+                    message: normalizeFailureDetail(refreshResult.message, refreshResult.reason),
+                });
+                continue;
+            }
+            const refreshedEmail = sanitizeEmail(extractAccountEmail(refreshResult.access, refreshResult.idToken));
+            const refreshedAccountId = extractAccountId(refreshResult.access);
+            if (account.refreshToken !== refreshResult.refresh) {
+                account.refreshToken = refreshResult.refresh;
+                changed = true;
+            }
+            if (account.accessToken !== refreshResult.access) {
+                account.accessToken = refreshResult.access;
+                changed = true;
+            }
+            if (account.expiresAt !== refreshResult.expires) {
+                account.expiresAt = refreshResult.expires;
+                changed = true;
+            }
+            if (refreshedEmail && refreshedEmail !== account.email) {
+                account.email = refreshedEmail;
+                changed = true;
+            }
+            if (refreshedAccountId && refreshedAccountId !== account.accountId) {
+                account.accountId = refreshedAccountId;
+                account.accountIdSource = "token";
+                changed = true;
+            }
+            if (refreshResult.idToken) {
+                probeIdTokenByIndex.set(i, refreshResult.idToken);
+            }
+            probeRefreshedIndices.add(i);
+            probeAccessToken = account.accessToken;
+            probeAccountId = account.accountId ?? refreshedAccountId;
+        }
+        if (!probeAccessToken || !probeAccountId) {
+            probeErrors.push(`${formatAccountLabel(account, i)}: missing accountId for live probe`);
+            continue;
+        }
+        try {
+            const liveQuota = await fetchCodexQuotaSnapshot({
+                accountId: probeAccountId,
+                accessToken: probeAccessToken,
+                model: options.model,
+            });
+            liveQuotaByIndex.set(i, liveQuota);
+        }
+        catch (error) {
+            const message = normalizeFailureDetail(error instanceof Error ? error.message : String(error), undefined);
+            probeErrors.push(`${formatAccountLabel(account, i)}: ${message}`);
+        }
+    }
+    const forecastInputs = storage.accounts.map((account, index) => ({
+        index,
+        account,
+        isCurrent: index === resolveActiveIndex(storage, "codex"),
+        now,
+        refreshFailure: refreshFailures.get(index),
+        liveQuota: liveQuotaByIndex.get(index),
+    }));
+    const forecastResults = evaluateForecastAccounts(forecastInputs);
+    const recommendation = recommendForecastAccount(forecastResults);
+    if (recommendation.recommendedIndex === null) {
+        await persistProbeChangesIfNeeded();
+        if (options.json) {
+            console.log(JSON.stringify({
+                error: recommendation.reason,
+                ...(probeErrors.length > 0 ? { probeErrors } : {}),
+            }, null, 2));
+        }
+        else {
+            console.log(`No best account available: ${recommendation.reason}`);
+            printProbeNotes();
+        }
+        return 1;
+    }
+    const bestIndex = recommendation.recommendedIndex;
+    const bestAccount = storage.accounts[bestIndex];
+    if (!bestAccount) {
+        await persistProbeChangesIfNeeded();
+        if (options.json) {
+            console.log(JSON.stringify({ error: "Best account not found." }, null, 2));
+        }
+        else {
+            console.log("Best account not found.");
+        }
+        return 1;
+    }
+    // Check if already on best account
+    const currentIndex = resolveActiveIndex(storage, "codex");
+    if (currentIndex === bestIndex) {
+        const shouldSyncCurrentBest = probeRefreshedIndices.has(bestIndex) || probeIdTokenByIndex.has(bestIndex);
+        let alreadyBestSynced;
+        if (changed) {
+            bestAccount.lastUsed = now;
+            await persistProbeChangesIfNeeded();
+        }
+        if (shouldSyncCurrentBest) {
+            alreadyBestSynced = await setCodexCliActiveSelection({
+                accountId: bestAccount.accountId,
+                email: bestAccount.email,
+                accessToken: bestAccount.accessToken,
+                refreshToken: bestAccount.refreshToken,
+                expiresAt: bestAccount.expiresAt,
+                ...(probeIdTokenByIndex.has(bestIndex)
+                    ? { idToken: probeIdTokenByIndex.get(bestIndex) }
+                    : {}),
+            });
+            if (!alreadyBestSynced && !options.json) {
+                console.warn("Codex auth sync did not complete. Multi-auth routing will still use this account.");
+            }
+        }
+        if (options.json) {
+            console.log(JSON.stringify({
+                message: `Already on best account: ${formatAccountLabel(bestAccount, bestIndex)}`,
+                accountIndex: bestIndex + 1,
+                reason: recommendation.reason,
+                ...(alreadyBestSynced !== undefined ? { synced: alreadyBestSynced } : {}),
+                ...(probeErrors.length > 0 ? { probeErrors } : {}),
+            }, null, 2));
+        }
+        else {
+            console.log(`Already on best account ${bestIndex + 1}: ${formatAccountLabel(bestAccount, bestIndex)}`);
+            console.log(`Reason: ${recommendation.reason}`);
+            printProbeNotes();
+        }
+        return 0;
+    }
+    const targetIndex = bestIndex;
+    const parsed = targetIndex + 1;
+    const { synced, wasDisabled } = await persistAndSyncSelectedAccount({
+        storage,
+        targetIndex,
+        parsed,
+        switchReason: "best",
+        initialSyncIdToken: probeIdTokenByIndex.get(bestIndex),
+    });
+    if (options.json) {
+        console.log(JSON.stringify({
+            message: `Switched to best account: ${formatAccountLabel(bestAccount, targetIndex)}`,
+            accountIndex: parsed,
+            reason: recommendation.reason,
+            synced,
+            wasDisabled,
+            ...(probeErrors.length > 0 ? { probeErrors } : {}),
+        }, null, 2));
+    }
+    else {
+        console.log(`Switched to best account ${parsed}: ${formatAccountLabel(bestAccount, targetIndex)}${wasDisabled ? " (re-enabled)" : ""}`);
+        console.log(`Reason: ${recommendation.reason}`);
+        printProbeNotes();
+        if (!synced) {
+            console.warn("Codex auth sync did not complete. Multi-auth routing will still use this account.");
+        }
     }
-    console.log(`Switched to account ${parsed}: ${formatAccountLabel(account, targetIndex)}${wasDisabled ? " (re-enabled)" : ""}`);
     return 0;
 }
 export async function autoSyncActiveAccountToCodex() {
@@ -3451,9 +3876,7 @@ export async function autoSyncActiveAccountToCodex() {
                 account.email = nextEmail;
                 changed = true;
             }
-            if (tokenAccountId && tokenAccountId !== account.accountId) {
-                account.accountId = tokenAccountId;
-                account.accountIdSource = "token";
+            if (applyTokenAccountIdentity(account, tokenAccountId)) {
                 changed = true;
             }
             syncAccessToken = refreshResult.access;
@@ -3519,6 +3942,9 @@ export async function runCodexMultiAuthCli(rawArgs) {
     if (command === "forecast") {
         return runForecast(rest);
     }
+    if (command === "best") {
+        return runBest(rest);
+    }
     if (command === "report") {
         return runReport(rest);
     }