codex-multi-auth 0.1.8 → 1.1.10

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";
@@ -14,7 +14,7 @@ import { MODEL_FAMILIES } from "./prompts/codex.js";
 import { fetchCodexQuotaSnapshot, formatQuotaSnapshotLine, } from "./quota-probe.js";
 import { queuedRefresh } from "./refresh-queue.js";
 import { loadQuotaCache, saveQuotaCache, } from "./quota-cache.js";
-import { clearAccounts, getStoragePath, loadFlaggedAccounts, loadAccounts, saveFlaggedAccounts, saveAccounts, setStoragePath, } from "./storage.js";
+import { clearAccounts, findMatchingAccountIndex, getStoragePath, loadFlaggedAccounts, loadAccounts, saveFlaggedAccounts, saveAccounts, setStoragePath, withAccountAndFlaggedStorageTransaction, withAccountStorageTransaction, } from "./storage.js";
 import { getCodexCliAuthPath, getCodexCliConfigPath, loadCodexCliState, } from "./codex-cli/state.js";
 import { setCodexCliActiveSelection } from "./codex-cli/writer.js";
 import { ANSI } from "./ui/ansi.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})`);
@@ -322,6 +324,26 @@ function normalizeQuotaEmail(email) {
     const normalized = sanitizeEmail(email);
     return normalized && normalized.length > 0 ? normalized : null;
 }
+function normalizeQuotaAccountId(accountId) {
+    if (typeof accountId !== "string")
+        return null;
+    const trimmed = accountId.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+function hasUniqueQuotaAccountId(accounts, account) {
+    const accountId = normalizeQuotaAccountId(account.accountId);
+    if (!accountId)
+        return false;
+    let matchCount = 0;
+    for (const candidate of accounts) {
+        if (normalizeQuotaAccountId(candidate.accountId) !== accountId)
+            continue;
+        matchCount += 1;
+        if (matchCount > 1)
+            return false;
+    }
+    return matchCount === 1;
+}
 function quotaCacheEntryToSnapshot(entry) {
     return {
         status: entry.status,
@@ -389,17 +411,20 @@ function formatAccountQuotaSummary(entry) {
     }
     return formatQuotaSnapshotLine(quotaCacheEntryToSnapshot(entry));
 }
-function getQuotaCacheEntryForAccount(cache, account) {
-    if (account.accountId && cache.byAccountId[account.accountId]) {
-        return cache.byAccountId[account.accountId] ?? null;
-    }
+function getQuotaCacheEntryForAccount(cache, account, accounts) {
     const email = normalizeQuotaEmail(account.email);
     if (email && cache.byEmail[email]) {
         return cache.byEmail[email] ?? null;
     }
+    const accountId = normalizeQuotaAccountId(account.accountId);
+    if (accountId &&
+        hasUniqueQuotaAccountId(accounts, account) &&
+        cache.byAccountId[accountId]) {
+        return cache.byAccountId[accountId] ?? null;
+    }
     return null;
 }
-function updateQuotaCacheForAccount(cache, account, snapshot) {
+function updateQuotaCacheForAccount(cache, account, snapshot, accounts) {
     const nextEntry = {
         updatedAt: Date.now(),
         status: snapshot.status,
@@ -417,25 +442,27 @@ function updateQuotaCacheForAccount(cache, account, snapshot) {
         },
     };
     let changed = false;
-    if (account.accountId) {
-        cache.byAccountId[account.accountId] = nextEntry;
-        changed = true;
-    }
     const email = normalizeQuotaEmail(account.email);
     if (email) {
         cache.byEmail[email] = nextEntry;
         changed = true;
+        return changed;
+    }
+    const accountId = normalizeQuotaAccountId(account.accountId);
+    if (accountId && hasUniqueQuotaAccountId(accounts, account)) {
+        cache.byAccountId[accountId] = nextEntry;
+        changed = true;
     }
     return changed;
 }
 const DEFAULT_MENU_QUOTA_REFRESH_TTL_MS = 5 * 60_000;
 const MENU_QUOTA_REFRESH_MODEL = "gpt-5-codex";
-function resolveMenuQuotaProbeInput(account, cache, maxAgeMs, now) {
+function resolveMenuQuotaProbeInput(account, cache, maxAgeMs, now, accounts) {
     if (account.enabled === false)
         return null;
     if (!hasUsableAccessToken(account, now))
         return null;
-    const existing = getQuotaCacheEntryForAccount(cache, account);
+    const existing = getQuotaCacheEntryForAccount(cache, account, accounts);
     if (existing &&
         typeof existing.updatedAt === "number" &&
         Number.isFinite(existing.updatedAt) &&
@@ -453,7 +480,7 @@ function resolveMenuQuotaProbeInput(account, cache, maxAgeMs, now) {
 function collectMenuQuotaRefreshTargets(storage, cache, maxAgeMs, now = Date.now()) {
     const targets = [];
     for (const account of storage.accounts) {
-        const probeInput = resolveMenuQuotaProbeInput(account, cache, maxAgeMs, now);
+        const probeInput = resolveMenuQuotaProbeInput(account, cache, maxAgeMs, now, storage.accounts);
         if (!probeInput)
             continue;
         targets.push({
@@ -467,7 +494,7 @@ function collectMenuQuotaRefreshTargets(storage, cache, maxAgeMs, now = Date.now
 function countMenuQuotaRefreshTargets(storage, cache, maxAgeMs, now = Date.now()) {
     let count = 0;
     for (const account of storage.accounts) {
-        if (resolveMenuQuotaProbeInput(account, cache, maxAgeMs, now)) {
+        if (resolveMenuQuotaProbeInput(account, cache, maxAgeMs, now, storage.accounts)) {
             count += 1;
         }
     }
@@ -492,7 +519,9 @@ async function refreshQuotaCacheForMenu(storage, cache, maxAgeMs, onProgress) {
                 accessToken: target.accessToken,
                 model: MENU_QUOTA_REFRESH_MODEL,
             });
-            changed = updateQuotaCacheForAccount(cache, target.account, snapshot) || changed;
+            changed =
+                updateQuotaCacheForAccount(cache, target.account, snapshot, storage.accounts) ||
+                    changed;
         }
         catch {
             // Keep existing cached values if probing fails.
@@ -615,7 +644,9 @@ function toExistingAccountInfo(storage, quotaCache, displaySettings) {
     const activeIndex = resolveActiveIndex(storage, "codex");
     const layoutMode = resolveMenuLayoutMode(displaySettings);
     const baseAccounts = storage.accounts.map((account, index) => {
-        const entry = quotaCache ? getQuotaCacheEntryForAccount(quotaCache, account) : null;
+        const entry = quotaCache
+            ? getQuotaCacheEntryForAccount(quotaCache, account, storage.accounts)
+            : null;
         return {
             index,
             sourceIndex: index,
@@ -690,6 +721,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;
@@ -1058,118 +1118,83 @@ async function runOAuthFlow(forceNewLogin) {
 async function persistAccountPool(results, replaceAll) {
     if (results.length === 0)
         return;
-    const loadedStorage = replaceAll
-        ? null
-        : await loadAccounts();
-    const now = Date.now();
-    const accounts = loadedStorage?.accounts ? [...loadedStorage.accounts] : [];
-    const indexByRefreshToken = new Map();
-    const indexByAccountId = new Map();
-    const indexByEmail = new Map();
-    let selectedAccountIndex = null;
-    for (let i = 0; i < accounts.length; i += 1) {
-        const account = accounts[i];
-        if (!account)
-            continue;
-        if (account.refreshToken)
-            indexByRefreshToken.set(account.refreshToken, i);
-        if (account.accountId)
-            indexByAccountId.set(account.accountId, i);
-        if (account.email)
-            indexByEmail.set(account.email, i);
-    }
-    for (const result of results) {
-        const tokenAccountId = extractAccountId(result.access);
-        const accountId = resolveRequestAccountId(result.accountIdOverride, result.accountIdSource, tokenAccountId);
-        const accountIdSource = accountId
-            ? (result.accountIdSource ?? (result.accountIdOverride ? "manual" : "token"))
-            : undefined;
-        const accountLabel = result.accountLabel;
-        const accountEmail = sanitizeEmail(extractAccountEmail(result.access, result.idToken));
-        const existingByEmail = accountEmail && indexByEmail.has(accountEmail)
-            ? indexByEmail.get(accountEmail)
-            : undefined;
-        const existingById = accountId && indexByAccountId.has(accountId)
-            ? indexByAccountId.get(accountId)
-            : undefined;
-        const existingByToken = indexByRefreshToken.get(result.refresh);
-        const existingIndex = existingById ?? existingByEmail ?? existingByToken;
-        if (existingIndex === undefined) {
-            const newIndex = accounts.length;
-            accounts.push({
+    await withAccountStorageTransaction(async (loadedStorage, persist) => {
+        const stored = replaceAll ? null : loadedStorage;
+        const now = Date.now();
+        const accounts = stored?.accounts ? [...stored.accounts] : [];
+        let selectedAccountIndex = null;
+        for (const result of results) {
+            const tokenAccountId = extractAccountId(result.access);
+            const accountId = resolveRequestAccountId(result.accountIdOverride, result.accountIdSource, tokenAccountId);
+            const accountIdSource = accountId
+                ? (result.accountIdSource ?? (result.accountIdOverride ? "manual" : "token"))
+                : undefined;
+            const accountLabel = result.accountLabel;
+            const accountEmail = sanitizeEmail(extractAccountEmail(result.access, result.idToken));
+            const existingIndex = findMatchingAccountIndex(accounts, {
                 accountId,
-                accountIdSource,
-                accountLabel,
                 email: accountEmail,
                 refreshToken: result.refresh,
+            }, {
+                allowUniqueAccountIdFallbackWithoutEmail: true,
+            });
+            if (existingIndex === undefined) {
+                const newIndex = accounts.length;
+                accounts.push({
+                    accountId,
+                    accountIdSource,
+                    accountLabel,
+                    email: accountEmail,
+                    refreshToken: result.refresh,
+                    accessToken: result.access,
+                    expiresAt: result.expires,
+                    enabled: true,
+                    addedAt: now,
+                    lastUsed: now,
+                });
+                selectedAccountIndex = newIndex;
+                continue;
+            }
+            const existing = accounts[existingIndex];
+            if (!existing)
+                continue;
+            const nextEmail = accountEmail ?? existing.email;
+            const nextAccountId = accountId ?? existing.accountId;
+            const nextAccountIdSource = accountId
+                ? (accountIdSource ?? existing.accountIdSource)
+                : existing.accountIdSource;
+            accounts[existingIndex] = {
+                ...existing,
+                accountId: nextAccountId,
+                accountIdSource: nextAccountIdSource,
+                accountLabel: accountLabel ?? existing.accountLabel,
+                email: nextEmail,
+                refreshToken: result.refresh,
                 accessToken: result.access,
                 expiresAt: result.expires,
                 enabled: true,
-                addedAt: now,
                 lastUsed: now,
-            });
-            indexByRefreshToken.set(result.refresh, newIndex);
-            if (accountId)
-                indexByAccountId.set(accountId, newIndex);
-            if (accountEmail)
-                indexByEmail.set(accountEmail, newIndex);
-            selectedAccountIndex = newIndex;
-            continue;
-        }
-        const existing = accounts[existingIndex];
-        if (!existing)
-            continue;
-        const oldToken = existing.refreshToken;
-        const oldEmail = existing.email;
-        const nextEmail = accountEmail ?? existing.email;
-        const nextAccountId = accountId ?? existing.accountId;
-        const nextAccountIdSource = accountId
-            ? (accountIdSource ?? existing.accountIdSource)
-            : existing.accountIdSource;
-        accounts[existingIndex] = {
-            ...existing,
-            accountId: nextAccountId,
-            accountIdSource: nextAccountIdSource,
-            accountLabel: accountLabel ?? existing.accountLabel,
-            email: nextEmail,
-            refreshToken: result.refresh,
-            accessToken: result.access,
-            expiresAt: result.expires,
-            enabled: true,
-            lastUsed: now,
-        };
-        if (oldToken !== result.refresh) {
-            indexByRefreshToken.delete(oldToken);
-            indexByRefreshToken.set(result.refresh, existingIndex);
-        }
-        if (nextAccountId) {
-            indexByAccountId.set(nextAccountId, existingIndex);
-        }
-        if (oldEmail && oldEmail !== nextEmail) {
-            indexByEmail.delete(oldEmail);
-        }
-        if (nextEmail) {
-            indexByEmail.set(nextEmail, existingIndex);
-        }
-        selectedAccountIndex = existingIndex;
-    }
-    const fallbackActiveIndex = accounts.length === 0
-        ? 0
-        : Math.max(0, Math.min(loadedStorage?.activeIndex ?? 0, accounts.length - 1));
-    const nextActiveIndex = accounts.length === 0
-        ? 0
-        : selectedAccountIndex === null
-            ? fallbackActiveIndex
-            : Math.max(0, Math.min(selectedAccountIndex, accounts.length - 1));
-    const activeIndexByFamily = {};
-    for (const family of MODEL_FAMILIES) {
-        activeIndexByFamily[family] = nextActiveIndex;
-    }
-    await saveAccounts({
-        version: 3,
-        accounts,
-        activeIndex: nextActiveIndex,
-        activeIndexByFamily,
+            };
+            selectedAccountIndex = existingIndex;
+        }
+        const fallbackActiveIndex = accounts.length === 0
+            ? 0
+            : Math.max(0, Math.min(stored?.activeIndex ?? 0, accounts.length - 1));
+        const nextActiveIndex = accounts.length === 0
+            ? 0
+            : selectedAccountIndex === null
+                ? fallbackActiveIndex
+                : Math.max(0, Math.min(selectedAccountIndex, accounts.length - 1));
+        const activeIndexByFamily = {};
+        for (const family of MODEL_FAMILIES) {
+            activeIndexByFamily[family] = nextActiveIndex;
+        }
+        await persist({
+            version: 3,
+            accounts,
+            activeIndex: nextActiveIndex,
+            activeIndexByFamily,
+        });
     });
 }
 async function syncSelectionToCodex(tokens) {
@@ -1279,7 +1304,7 @@ async function runHealthCheck(options = {}) {
                         });
                         if (quotaCache) {
                             quotaCacheChanged =
-                                updateQuotaCacheForAccount(quotaCache, account, snapshot) || quotaCacheChanged;
+                                updateQuotaCacheForAccount(quotaCache, account, snapshot, storage.accounts) || quotaCacheChanged;
                         }
                         healthDetail = formatQuotaSnapshotForDashboard(snapshot, display);
                     }
@@ -1319,9 +1344,7 @@ async function runHealthCheck(options = {}) {
                 account.email = nextEmail;
                 changed = true;
             }
-            if (tokenAccountId && tokenAccountId !== account.accountId) {
-                account.accountId = tokenAccountId;
-                account.accountIdSource = "token";
+            if (applyTokenAccountIdentity(account, tokenAccountId)) {
                 changed = true;
             }
             if (account.enabled === false) {
@@ -1349,7 +1372,7 @@ async function runHealthCheck(options = {}) {
                         });
                         if (quotaCache) {
                             quotaCacheChanged =
-                                updateQuotaCacheForAccount(quotaCache, account, snapshot) || quotaCacheChanged;
+                                updateQuotaCacheForAccount(quotaCache, account, snapshot, storage.accounts) || quotaCacheChanged;
                         }
                         healthyMessage = formatQuotaSnapshotForDashboard(snapshot, display);
                     }
@@ -1419,6 +1442,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:",
@@ -1492,6 +1530,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,
@@ -1751,7 +1831,7 @@ async function runForecast(args) {
                 const account = storage.accounts[i];
                 if (account) {
                     quotaCacheChanged =
-                        updateQuotaCacheForAccount(quotaCache, account, liveQuota) || quotaCacheChanged;
+                        updateQuotaCacheForAccount(quotaCache, account, liveQuota, storage.accounts) || quotaCacheChanged;
                 }
             }
         }
@@ -2007,28 +2087,29 @@ function findExistingAccountIndexForFlagged(storage, flagged, nextRefreshToken,
     const flaggedEmail = sanitizeEmail(flagged.email);
     const candidateAccountId = nextAccountId ?? flagged.accountId;
     const candidateEmail = sanitizeEmail(nextEmail) ?? flaggedEmail;
-    for (let i = 0; i < storage.accounts.length; i += 1) {
-        const account = storage.accounts[i];
-        if (!account)
-            continue;
-        if (account.refreshToken === flagged.refreshToken || account.refreshToken === nextRefreshToken) {
-            return i;
-        }
-        if (candidateAccountId &&
-            typeof account.accountId === "string" &&
-            account.accountId === candidateAccountId) {
-            return i;
-        }
-        const existingEmail = sanitizeEmail(account.email);
-        if (candidateEmail && existingEmail && existingEmail === candidateEmail) {
-            return i;
-        }
-    }
-    return -1;
+    const nextMatchIndex = findMatchingAccountIndex(storage.accounts, {
+        accountId: candidateAccountId,
+        email: candidateEmail,
+        refreshToken: nextRefreshToken,
+    }, {
+        allowUniqueAccountIdFallbackWithoutEmail: true,
+    });
+    if (nextMatchIndex !== undefined) {
+        return nextMatchIndex;
+    }
+    const flaggedMatchIndex = findMatchingAccountIndex(storage.accounts, {
+        accountId: candidateAccountId,
+        email: candidateEmail,
+        refreshToken: flagged.refreshToken,
+    }, {
+        allowUniqueAccountIdFallbackWithoutEmail: true,
+    });
+    return flaggedMatchIndex ?? -1;
 }
 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];
@@ -2052,9 +2133,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) {
@@ -2084,7 +2167,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,
@@ -2129,113 +2212,142 @@ async function runVerifyFlagged(args) {
         console.log("No flagged accounts to check.");
         return 0;
     }
-    let storage = await loadAccounts();
-    if (!storage) {
-        storage = createEmptyAccountStorage();
-    }
     let storageChanged = false;
     let flaggedChanged = false;
     const reports = [];
     const nextFlaggedAccounts = [];
     const now = Date.now();
+    const refreshChecks = [];
     for (let i = 0; i < flaggedStorage.accounts.length; i += 1) {
         const flagged = flaggedStorage.accounts[i];
         if (!flagged)
             continue;
         const label = formatAccountLabel(flagged, i);
-        const result = await queuedRefresh(flagged.refreshToken);
-        if (result.type === "success") {
-            if (!options.restore) {
-                const nextFlagged = {
+        refreshChecks.push({
+            index: i,
+            flagged,
+            label,
+            result: await queuedRefresh(flagged.refreshToken),
+        });
+    }
+    const applyRefreshChecks = (storage) => {
+        for (const check of refreshChecks) {
+            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: nextIdentity.accountId,
+                        accountIdSource: nextIdentity.accountIdSource,
+                        email: sanitizeEmail(extractAccountEmail(result.access, result.idToken)) ?? flagged.email,
+                        lastUsed: now,
+                        lastError: undefined,
+                    };
+                    nextFlaggedAccounts.push(nextFlagged);
+                    if (JSON.stringify(nextFlagged) !== JSON.stringify(flagged)) {
+                        flaggedChanged = true;
+                    }
+                    reports.push({
+                        index: i,
+                        label,
+                        outcome: "healthy-flagged",
+                        message: "session is healthy (left in flagged list due to --no-restore)",
+                    });
+                    continue;
+                }
+                const upsertResult = upsertRecoveredFlaggedAccount(storage, flagged, result, now);
+                if (upsertResult.restored) {
+                    storageChanged = storageChanged || upsertResult.changed;
+                    flaggedChanged = true;
+                    reports.push({
+                        index: i,
+                        label,
+                        outcome: "restored",
+                        message: upsertResult.message,
+                    });
+                    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: undefined,
+                    lastError: upsertResult.message,
                 };
-                nextFlaggedAccounts.push(nextFlagged);
-                if (JSON.stringify(nextFlagged) !== JSON.stringify(flagged)) {
+                nextFlaggedAccounts.push(updatedFlagged);
+                if (JSON.stringify(updatedFlagged) !== JSON.stringify(flagged)) {
                     flaggedChanged = true;
                 }
                 reports.push({
                     index: i,
                     label,
-                    outcome: "healthy-flagged",
-                    message: "session is healthy (left in flagged list due to --no-restore)",
-                });
-                continue;
-            }
-            const upsertResult = upsertRecoveredFlaggedAccount(storage, flagged, result, now);
-            if (upsertResult.restored) {
-                storageChanged = storageChanged || upsertResult.changed;
-                flaggedChanged = true;
-                reports.push({
-                    index: i,
-                    label,
-                    outcome: "restored",
+                    outcome: "restore-skipped",
                     message: upsertResult.message,
                 });
                 continue;
             }
-            const updatedFlagged = {
+            const detail = normalizeFailureDetail(result.message, result.reason);
+            const failedFlagged = {
                 ...flagged,
-                refreshToken: result.refresh,
-                accessToken: result.access,
-                expiresAt: result.expires,
-                accountId: extractAccountId(result.access) ?? flagged.accountId,
-                accountIdSource: extractAccountId(result.access) ? "token" : flagged.accountIdSource,
-                email: sanitizeEmail(extractAccountEmail(result.access, result.idToken)) ?? flagged.email,
-                lastUsed: now,
-                lastError: upsertResult.message,
+                lastError: detail,
             };
-            nextFlaggedAccounts.push(updatedFlagged);
-            if (JSON.stringify(updatedFlagged) !== JSON.stringify(flagged)) {
+            nextFlaggedAccounts.push(failedFlagged);
+            if ((flagged.lastError ?? "") !== detail) {
                 flaggedChanged = true;
             }
             reports.push({
                 index: i,
                 label,
-                outcome: "restore-skipped",
-                message: upsertResult.message,
+                outcome: "still-flagged",
+                message: detail,
             });
-            continue;
         }
-        const detail = normalizeFailureDetail(result.message, result.reason);
-        const failedFlagged = {
-            ...flagged,
-            lastError: detail,
-        };
-        nextFlaggedAccounts.push(failedFlagged);
-        if ((flagged.lastError ?? "") !== detail) {
-            flaggedChanged = true;
+    };
+    if (options.restore) {
+        if (options.dryRun) {
+            applyRefreshChecks((await loadAccounts()) ?? createEmptyAccountStorage());
         }
-        reports.push({
-            index: i,
-            label,
-            outcome: "still-flagged",
-            message: detail,
-        });
+        else {
+            await withAccountAndFlaggedStorageTransaction(async (loadedStorage, persist) => {
+                const nextStorage = loadedStorage
+                    ? structuredClone(loadedStorage)
+                    : createEmptyAccountStorage();
+                applyRefreshChecks(nextStorage);
+                if (!storageChanged) {
+                    return;
+                }
+                normalizeDoctorIndexes(nextStorage);
+                await persist(nextStorage, {
+                    version: 1,
+                    accounts: nextFlaggedAccounts,
+                });
+            });
+        }
+    }
+    else {
+        applyRefreshChecks(createEmptyAccountStorage());
     }
     const remainingFlagged = nextFlaggedAccounts.length;
     const restored = reports.filter((report) => report.outcome === "restored").length;
     const healthyFlagged = reports.filter((report) => report.outcome === "healthy-flagged").length;
     const stillFlagged = reports.filter((report) => report.outcome === "still-flagged").length;
     const changed = storageChanged || flaggedChanged;
-    if (!options.dryRun) {
-        if (storageChanged) {
-            normalizeDoctorIndexes(storage);
-            await saveAccounts(storage);
-        }
-        if (flaggedChanged) {
-            await saveFlaggedAccounts({
-                version: 1,
-                accounts: nextFlaggedAccounts,
-            });
-        }
+    if (!options.dryRun && flaggedChanged && (!options.restore || !storageChanged)) {
+        await saveFlaggedAccounts({
+            version: 1,
+            accounts: nextFlaggedAccounts,
+        });
     }
     if (options.json) {
         console.log(JSON.stringify({
@@ -2340,7 +2452,7 @@ async function runFix(args) {
                         });
                         if (quotaCache) {
                             quotaCacheChanged =
-                                updateQuotaCacheForAccount(quotaCache, account, snapshot) || quotaCacheChanged;
+                                updateQuotaCacheForAccount(quotaCache, account, snapshot, storage.accounts) || quotaCacheChanged;
                         }
                         reports.push({
                             index: i,
@@ -2413,7 +2525,7 @@ async function runFix(args) {
                         });
                         if (quotaCache) {
                             quotaCacheChanged =
-                                updateQuotaCacheForAccount(quotaCache, account, snapshot) || quotaCacheChanged;
+                                updateQuotaCacheForAccount(quotaCache, account, snapshot, storage.accounts) || quotaCacheChanged;
                         }
                         reports.push({
                             index: i,
@@ -2615,6 +2727,12 @@ function normalizeDoctorIndexes(storage) {
     }
     return changed;
 }
+function getDoctorRefreshTokenKey(refreshToken) {
+    if (typeof refreshToken !== "string")
+        return undefined;
+    const trimmed = refreshToken.trim();
+    return trimmed || undefined;
+}
 function applyDoctorFixes(storage) {
     let changed = false;
     const actions = [];
@@ -2630,7 +2748,9 @@ function applyDoctorFixes(storage) {
         const account = storage.accounts[i];
         if (!account)
             continue;
-        const refreshToken = account.refreshToken.trim();
+        const refreshToken = getDoctorRefreshTokenKey(account.refreshToken);
+        if (!refreshToken)
+            continue;
         const existingTokenIndex = seenRefreshTokens.get(refreshToken);
         if (typeof existingTokenIndex === "number") {
             if (account.enabled !== false) {
@@ -2879,7 +2999,9 @@ async function runDoctor(args) {
         const seenRefreshTokens = new Set();
         let duplicateTokenCount = 0;
         for (const account of storage.accounts) {
-            const token = account.refreshToken.trim();
+            const token = getDoctorRefreshTokenKey(account.refreshToken);
+            if (!token)
+                continue;
             if (seenRefreshTokens.has(token)) {
                 duplicateTokenCount += 1;
             }
@@ -2998,10 +3120,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;
@@ -3320,6 +3439,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) {
@@ -3333,7 +3469,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") {
@@ -3351,10 +3487,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;
@@ -3365,7 +3498,7 @@ async function runSwitch(args) {
         }
     }
     account.lastUsed = switchNow;
-    account.lastSwitchReason = "rotation";
+    account.lastSwitchReason = switchReason;
     await saveAccounts(storage);
     const synced = await setCodexCliActiveSelection({
         accountId: account.accountId,
@@ -3375,10 +3508,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() {
@@ -3422,9 +3769,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;
@@ -3490,6 +3835,9 @@ export async function runCodexMultiAuthCli(rawArgs) {
     if (command === "forecast") {
         return runForecast(rest);
     }
+    if (command === "best") {
+        return runBest(rest);
+    }
     if (command === "report") {
         return runReport(rest);
     }