codex-multi-auth 1.1.10 → 1.2.0

package/dist/lib/codex-manager.js

@@ -4,25 +4,28 @@ import { promises as fs, existsSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { createAuthorizationFlow, exchangeAuthorizationCode, parseAuthorizationInput, REDIRECT_URI, } from "./auth/auth.js";
 import { startLocalOAuthServer } from "./auth/server.js";
-import { copyTextToClipboard, openBrowserUrl } from "./auth/browser.js";
+import { copyTextToClipboard, isBrowserLaunchSuppressed, openBrowserUrl } from "./auth/browser.js";
 import { promptAddAnotherAccount, promptLoginMode } from "./cli.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";
+import { createLogger } from "./logger.js";
 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, findMatchingAccountIndex, getStoragePath, loadFlaggedAccounts, loadAccounts, saveFlaggedAccounts, saveAccounts, setStoragePath, withAccountAndFlaggedStorageTransaction, withAccountStorageTransaction, } from "./storage.js";
+import { clearAccounts, findMatchingAccountIndex, formatStorageErrorHint, getNamedBackups, getStoragePath, loadFlaggedAccounts, loadAccounts, StorageError, restoreAccountsFromBackup, 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";
 import { UI_COPY } from "./ui/copy.js";
+import { confirm } from "./ui/confirm.js";
 import { paintUiText, quotaToneFromLeftPercent } from "./ui/format.js";
 import { getUiRuntimeOptions } from "./ui/runtime.js";
 import { select } from "./ui/select.js";
 import { applyUiThemeFromDashboardSettings, configureUnifiedSettings, resolveMenuLayoutMode } from "./codex-manager/settings-hub.js";
+const log = createLogger("codex-manager");
 function stylePromptText(text, tone) {
     if (!output.isTTY)
         return text;
@@ -215,7 +218,7 @@ function printUsage() {
         "Codex Multi-Auth CLI",
         "",
         "Usage:",
-        "  codex auth login",
+        "  codex auth login [--manual|--no-browser]",
         "  codex auth list",
         "  codex auth status",
         "  codex auth switch <index>",
@@ -233,6 +236,26 @@ function printUsage() {
         "  - Syncs active account into Codex CLI auth state",
     ].join("\n"));
 }
+function parseAuthLoginArgs(args) {
+    const options = {
+        manual: false,
+    };
+    for (const arg of args) {
+        if (arg === "--manual" || arg === "--no-browser") {
+            options.manual = true;
+            continue;
+        }
+        if (arg === "--help" || arg === "-h") {
+            printUsage();
+            return { ok: false, message: "" };
+        }
+        return {
+            ok: false,
+            message: `Unknown login option: ${arg}`,
+        };
+    }
+    return { ok: true, options };
+}
 const IMPLEMENTED_FEATURES = [
     { id: 1, name: "Multi-account OAuth login dashboard" },
     { id: 2, name: "Account add/update dedupe by token/id/email" },
@@ -344,6 +367,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,
@@ -411,20 +474,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,
@@ -442,33 +507,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))
@@ -477,10 +576,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({
@@ -492,9 +591,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;
         }
     }
@@ -504,8 +604,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);
@@ -520,17 +622,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) {
@@ -643,9 +744,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,
@@ -750,15 +852,64 @@ function applyTokenAccountIdentity(account, tokenAccountId) {
     account.accountIdSource = nextIdentity.accountIdSource;
     return true;
 }
-async function promptManualCallback(state) {
-    if (!input.isTTY || !output.isTTY) {
+async function promptManualCallback(state, options = {}) {
+    const useInteractivePrompt = input.isTTY && output.isTTY;
+    if (!useInteractivePrompt && !options.allowNonTty) {
         return null;
     }
     const rl = createInterface({ input, output });
     try {
-        console.log("");
-        console.log(stylePromptText(UI_COPY.oauth.pastePrompt, "accent"));
-        const answer = await rl.question("◆  ");
+        if (useInteractivePrompt) {
+            console.log("");
+            console.log(stylePromptText(UI_COPY.oauth.pastePrompt, "accent"));
+        }
+        const answer = useInteractivePrompt
+            ? await rl.question("◆  ")
+            : await new Promise((resolve, reject) => {
+                if (input.readableEnded || input.destroyed) {
+                    resolve(null);
+                    return;
+                }
+                let settled = false;
+                const handleInputClosed = () => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    input.off("end", handleInputClosed);
+                    input.off("close", handleInputClosed);
+                    resolve(null);
+                };
+                const finish = (value) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    input.off("end", handleInputClosed);
+                    input.off("close", handleInputClosed);
+                    resolve(value);
+                };
+                const fail = (error) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    input.off("end", handleInputClosed);
+                    input.off("close", handleInputClosed);
+                    reject(error);
+                };
+                rl.question("")
+                    .then((value) => finish(value))
+                    .catch((error) => {
+                    if (isAbortError(error) || isReadlineClosedError(error)) {
+                        handleInputClosed();
+                        return;
+                    }
+                    fail(error);
+                });
+                input.once("end", handleInputClosed);
+                input.once("close", handleInputClosed);
+            });
+        if (answer === null) {
+            return null;
+        }
         if (answer.includes("\u001b")) {
             return null;
         }
@@ -778,7 +929,7 @@ async function promptManualCallback(state) {
         return parsed.code;
     }
     catch (error) {
-        if (isAbortError(error)) {
+        if (isAbortError(error) || isReadlineClosedError(error)) {
             return null;
         }
         throw error;
@@ -787,20 +938,56 @@ async function promptManualCallback(state) {
         rl.close();
     }
 }
-async function promptOAuthSignInMode() {
+function isReadlineClosedError(error) {
+    if (!(error instanceof Error)) {
+        return false;
+    }
+    const errorCode = typeof error === "object" && error !== null && "code" in error
+        ? String(error.code)
+        : "";
+    return errorCode === "ERR_USE_AFTER_CLOSE" || /readline was closed/i.test(error.message);
+}
+export function formatBackupSavedAt(mtimeMs) {
+    return new Date(mtimeMs).toLocaleString(undefined, {
+        month: "short",
+        day: "numeric",
+        year: "numeric",
+        hour: "numeric",
+        minute: "2-digit",
+    });
+}
+async function promptOAuthSignInMode(backupOption, backupDiscoveryWarning = null) {
     if (!input.isTTY || !output.isTTY) {
         return "browser";
     }
     const ui = getUiRuntimeOptions();
     const items = [
+        { label: UI_COPY.oauth.signInHeading, value: "cancel", kind: "heading" },
         { label: UI_COPY.oauth.openBrowser, value: "browser", color: "green" },
         { label: UI_COPY.oauth.manualMode, value: "manual", color: "yellow" },
+        ...(backupOption
+            ? [
+                { separator: true, label: "", value: "cancel" },
+                { label: UI_COPY.oauth.restoreHeading, value: "cancel", kind: "heading" },
+                {
+                    label: UI_COPY.oauth.restoreSavedBackup,
+                    value: "restore-backup",
+                    hint: UI_COPY.oauth.loadLastBackupHint(backupOption.fileName, backupOption.accountCount, formatBackupSavedAt(backupOption.mtimeMs)),
+                    color: "cyan",
+                },
+            ]
+            : []),
+        { separator: true, label: "", value: "cancel" },
         { label: UI_COPY.oauth.back, value: "cancel", color: "red" },
     ];
     const selected = await select(items, {
         message: UI_COPY.oauth.chooseModeTitle,
-        subtitle: UI_COPY.oauth.chooseModeSubtitle,
-        help: UI_COPY.oauth.chooseModeHelp,
+        subtitle: backupDiscoveryWarning
+            ? `${UI_COPY.oauth.chooseModeSubtitle} ${backupDiscoveryWarning}`
+            : UI_COPY.oauth.chooseModeSubtitle,
+        help: backupOption
+            ? UI_COPY.oauth.chooseModeHelpWithBackup
+            : UI_COPY.oauth.chooseModeHelp,
         clearScreen: true,
         theme: ui.theme,
         selectedEmphasis: "minimal",
@@ -813,11 +1000,81 @@ async function promptOAuthSignInMode() {
                 return "browser";
             if (lower === "2")
                 return "manual";
+            if (lower === "3" && backupOption)
+                return "restore-backup";
             return undefined;
         },
     });
     return selected ?? "cancel";
 }
+async function promptBackupRestoreMode(latestBackup) {
+    if (!input.isTTY || !output.isTTY) {
+        return "latest";
+    }
+    const ui = getUiRuntimeOptions();
+    const items = [
+        {
+            label: UI_COPY.oauth.loadLastBackup,
+            value: "latest",
+            hint: `${UI_COPY.oauth.restoreBackupLatestHint}\n${UI_COPY.oauth.manualBackupHint(latestBackup.accountCount, formatBackupSavedAt(latestBackup.mtimeMs))}`,
+            color: "cyan",
+        },
+        {
+            label: UI_COPY.oauth.chooseBackupManually,
+            value: "manual",
+            color: "yellow",
+        },
+        { label: UI_COPY.oauth.back, value: "back", color: "red" },
+    ];
+    const selected = await select(items, {
+        message: UI_COPY.oauth.restoreBackupTitle,
+        subtitle: UI_COPY.oauth.restoreBackupSubtitle,
+        help: UI_COPY.oauth.restoreBackupHelp,
+        clearScreen: true,
+        theme: ui.theme,
+        selectedEmphasis: "minimal",
+        allowEscape: false,
+        onInput: (raw) => {
+            const lower = raw.toLowerCase();
+            if (lower === "q")
+                return "back";
+            if (lower === "1")
+                return "latest";
+            if (lower === "2")
+                return "manual";
+            return undefined;
+        },
+    });
+    return selected ?? "back";
+}
+async function promptManualBackupSelection(backups) {
+    if (!input.isTTY || !output.isTTY) {
+        return backups[0] ?? null;
+    }
+    const ui = getUiRuntimeOptions();
+    const items = backups.map((backup) => ({
+        label: backup.fileName,
+        value: backup,
+        hint: UI_COPY.oauth.manualBackupHint(backup.accountCount, formatBackupSavedAt(backup.mtimeMs)),
+        color: "cyan",
+    }));
+    items.push({ label: UI_COPY.oauth.back, value: null, color: "red" });
+    const selected = await select(items, {
+        message: UI_COPY.oauth.manualBackupTitle,
+        subtitle: UI_COPY.oauth.manualBackupSubtitle,
+        help: UI_COPY.oauth.manualBackupHelp,
+        clearScreen: true,
+        theme: ui.theme,
+        selectedEmphasis: "minimal",
+        allowEscape: false,
+        onInput: (raw) => {
+            if (raw.toLowerCase() === "q")
+                return null;
+            return undefined;
+        },
+    });
+    return selected;
+}
 async function waitForMenuReturn(options = {}) {
     if (!input.isTTY || !output.isTTY) {
         return;
@@ -1063,18 +1320,29 @@ async function runActionPanel(title, stage, action, settings) {
         throw failed;
     }
 }
-async function runOAuthFlow(forceNewLogin) {
+async function runOAuthFlow(forceNewLogin, signInMode) {
     const { pkce, state, url } = await createAuthorizationFlow({ forceNewLogin });
-    const oauthServer = await startLocalOAuthServer({ state });
     let code = null;
+    let oauthServer = null;
     try {
-        const signInMode = await promptOAuthSignInMode();
-        if (signInMode === "cancel") {
-            return {
-                type: "failed",
-                reason: "unknown",
-                message: UI_COPY.oauth.cancelled,
-            };
+        if (signInMode === "browser") {
+            try {
+                oauthServer = await startLocalOAuthServer({ state });
+            }
+            catch (serverError) {
+                log.warn("Local OAuth callback server unavailable; falling back to manual callback entry.", serverError instanceof Error
+                    ? {
+                        message: serverError.message,
+                        stack: serverError.stack,
+                        code: typeof serverError === "object" &&
+                            serverError !== null &&
+                            "code" in serverError
+                            ? String(serverError.code)
+                            : undefined,
+                    }
+                    : { error: String(serverError) });
+                oauthServer = null;
+            }
         }
         if (signInMode === "browser") {
             const opened = openBrowserUrl(url);
@@ -1093,18 +1361,23 @@ async function runOAuthFlow(forceNewLogin) {
             const copied = copyTextToClipboard(url);
             console.log(stylePromptText(copied ? UI_COPY.oauth.copyOk : UI_COPY.oauth.copyFail, copied ? "success" : "warning"));
         }
-        if (oauthServer.ready) {
+        const waitingForCallback = signInMode === "browser" && oauthServer?.ready === true;
+        if (waitingForCallback && oauthServer) {
             console.log(stylePromptText(UI_COPY.oauth.waitingCallback, "muted"));
             const callbackResult = await oauthServer.waitForCode(state);
             code = callbackResult?.code ?? null;
         }
         if (!code) {
-            console.log(stylePromptText(UI_COPY.oauth.callbackMissed, "warning"));
-            code = await promptManualCallback(state);
+            console.log(stylePromptText(waitingForCallback
+                ? UI_COPY.oauth.callbackMissed
+                : signInMode === "manual"
+                    ? UI_COPY.oauth.callbackBypassed
+                    : UI_COPY.oauth.callbackUnavailable, "warning"));
+            code = await promptManualCallback(state, { allowNonTty: signInMode === "manual" });
         }
     }
     finally {
-        oauthServer.close();
+        oauthServer?.close();
     }
     if (!code) {
         return {
@@ -1253,6 +1526,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();
@@ -1260,6 +1534,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;
@@ -1302,9 +1579,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);
                     }
@@ -1328,6 +1605,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;
@@ -1343,14 +1622,21 @@ async function runHealthCheck(options = {}) {
             if (nextEmail && nextEmail !== account.email) {
                 account.email = nextEmail;
                 changed = true;
+                accountIdentityChanged = true;
             }
             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;
@@ -1370,9 +1656,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);
                     }
@@ -1406,8 +1692,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);
@@ -1784,6 +2070,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();
@@ -1791,6 +2078,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();
@@ -1827,11 +2117,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;
                 }
             }
         }
@@ -1852,8 +2142,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",
@@ -1923,8 +2213,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;
 }
@@ -2410,6 +2700,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();
@@ -2417,6 +2708,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;
@@ -2450,9 +2744,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,
@@ -2490,7 +2784,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;
@@ -2506,14 +2802,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) {
@@ -2523,9 +2824,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,
@@ -2614,8 +2915,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",
@@ -2681,8 +2982,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")}`);
@@ -3262,7 +3563,15 @@ async function handleManageAction(storage, menuResult) {
         const existing = storage.accounts[idx];
         if (!existing)
             return;
-        const tokenResult = await runOAuthFlow(true);
+        const signInMode = await promptOAuthSignInMode(null);
+        if (signInMode === "cancel") {
+            console.log(stylePromptText(UI_COPY.oauth.cancelledBackToMenu, "muted"));
+            return;
+        }
+        if (signInMode !== "browser" && signInMode !== "manual") {
+            return;
+        }
+        const tokenResult = await runOAuthFlow(true, signInMode);
         if (tokenResult.type !== "success") {
             console.error(`Refresh failed: ${tokenResult.message ?? tokenResult.reason ?? "unknown error"}`);
             return;
@@ -3273,7 +3582,17 @@ async function handleManageAction(storage, menuResult) {
         console.log(`Refreshed account ${idx + 1}.`);
     }
 }
-async function runAuthLogin() {
+async function runAuthLogin(args) {
+    const parsedArgs = parseAuthLoginArgs(args);
+    if (!parsedArgs.ok) {
+        if (parsedArgs.message) {
+            console.error(parsedArgs.message);
+            printUsage();
+            return 1;
+        }
+        return 0;
+    }
+    const loginOptions = parsedArgs.options;
     setStoragePath(null);
     let pendingMenuQuotaRefresh = null;
     let menuQuotaRefreshStatus;
@@ -3378,10 +3697,113 @@ async function runAuthLogin() {
             }
         }
         const refreshedStorage = await loadAccounts();
-        const existingCount = refreshedStorage?.accounts.length ?? 0;
+        let existingCount = refreshedStorage?.accounts.length ?? 0;
         let forceNewLogin = existingCount > 0;
+        let onboardingBackupDiscoveryWarning = null;
+        const loadNamedBackupsForOnboarding = async () => {
+            if (existingCount > 0) {
+                onboardingBackupDiscoveryWarning = null;
+                return [];
+            }
+            try {
+                onboardingBackupDiscoveryWarning = null;
+                return await getNamedBackups();
+            }
+            catch (error) {
+                const code = error.code;
+                log.debug("getNamedBackups failed, skipping restore option", {
+                    code,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+                if (code && code !== "ENOENT") {
+                    onboardingBackupDiscoveryWarning =
+                        "Named backup discovery failed. Continuing with browser or manual sign-in only.";
+                    console.warn(onboardingBackupDiscoveryWarning);
+                }
+                else {
+                    onboardingBackupDiscoveryWarning = null;
+                }
+                return [];
+            }
+        };
+        let namedBackups = await loadNamedBackupsForOnboarding();
         while (true) {
-            const tokenResult = await runOAuthFlow(forceNewLogin);
+            const latestNamedBackup = namedBackups[0] ?? null;
+            const preferManualMode = loginOptions.manual || isBrowserLaunchSuppressed();
+            const signInMode = preferManualMode
+                ? "manual"
+                : await promptOAuthSignInMode(latestNamedBackup, onboardingBackupDiscoveryWarning);
+            if (signInMode === "cancel") {
+                if (existingCount > 0) {
+                    console.log(stylePromptText(UI_COPY.oauth.cancelledBackToMenu, "muted"));
+                    continue loginFlow;
+                }
+                console.log("Cancelled.");
+                return 0;
+            }
+            if (signInMode === "restore-backup") {
+                const latestAvailableBackup = namedBackups[0] ?? null;
+                if (!latestAvailableBackup) {
+                    namedBackups = await loadNamedBackupsForOnboarding();
+                    continue;
+                }
+                const restoreMode = await promptBackupRestoreMode(latestAvailableBackup);
+                if (restoreMode === "back") {
+                    namedBackups = await loadNamedBackupsForOnboarding();
+                    continue;
+                }
+                const selectedBackup = restoreMode === "manual"
+                    ? await promptManualBackupSelection(namedBackups)
+                    : latestAvailableBackup;
+                if (!selectedBackup) {
+                    namedBackups = await loadNamedBackupsForOnboarding();
+                    continue;
+                }
+                const confirmed = await confirm(UI_COPY.oauth.restoreBackupConfirm(selectedBackup.fileName, selectedBackup.accountCount));
+                if (!confirmed) {
+                    namedBackups = await loadNamedBackupsForOnboarding();
+                    continue;
+                }
+                const displaySettings = await loadDashboardDisplaySettings();
+                applyUiThemeFromDashboardSettings(displaySettings);
+                try {
+                    await runActionPanel("Load Backup", `Loading ${selectedBackup.fileName}`, async () => {
+                        const restoredStorage = await restoreAccountsFromBackup(selectedBackup.path, { persist: false });
+                        const targetIndex = resolveActiveIndex(restoredStorage);
+                        const { synced } = await persistAndSyncSelectedAccount({
+                            storage: restoredStorage,
+                            targetIndex,
+                            parsed: targetIndex + 1,
+                            switchReason: "restore",
+                            preserveActiveIndexByFamily: true,
+                        });
+                        console.log(UI_COPY.oauth.restoreBackupLoaded(selectedBackup.fileName, restoredStorage.accounts.length));
+                        if (!synced) {
+                            console.warn(UI_COPY.oauth.restoreBackupSyncWarning);
+                        }
+                    }, displaySettings);
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    if (error instanceof StorageError) {
+                        console.error(formatStorageErrorHint(error, selectedBackup.path));
+                    }
+                    else {
+                        console.error(`Backup restore failed: ${message}`);
+                    }
+                    const storageAfterRestoreAttempt = await loadAccounts().catch(() => null);
+                    if ((storageAfterRestoreAttempt?.accounts.length ?? 0) > 0) {
+                        continue loginFlow;
+                    }
+                    namedBackups = await loadNamedBackupsForOnboarding();
+                    continue;
+                }
+                continue loginFlow;
+            }
+            if (signInMode !== "browser" && signInMode !== "manual") {
+                continue;
+            }
+            const tokenResult = await runOAuthFlow(forceNewLogin, signInMode);
             if (tokenResult.type !== "success") {
                 if (isUserCancelledOAuth(tokenResult)) {
                     if (existingCount > 0) {
@@ -3399,6 +3821,9 @@ async function runAuthLogin() {
             await syncSelectionToCodex(resolved);
             const latestStorage = await loadAccounts();
             const count = latestStorage?.accounts.length ?? 1;
+            existingCount = count;
+            namedBackups = [];
+            onboardingBackupDiscoveryWarning = null;
             console.log(`Added account. Total: ${count}`);
             if (count >= ACCOUNT_LIMITS.MAX_ACCOUNTS) {
                 console.log(`Reached maximum account limit (${ACCOUNT_LIMITS.MAX_ACCOUNTS}).`);
@@ -3451,15 +3876,29 @@ async function runSwitch(args) {
     console.log(`Switched to account ${parsed}: ${formatAccountLabel(account, targetIndex)}${wasDisabled ? " (re-enabled)" : ""}`);
     return 0;
 }
-async function persistAndSyncSelectedAccount({ storage, targetIndex, parsed, switchReason, initialSyncIdToken, }) {
+async function persistAndSyncSelectedAccount({ storage, targetIndex, parsed, switchReason, initialSyncIdToken, preserveActiveIndexByFamily = false, }) {
     const account = storage.accounts[targetIndex];
     if (!account) {
         throw new Error(`Account ${parsed} not found.`);
     }
+    const shouldPreserveActiveIndexByFamily = preserveActiveIndexByFamily &&
+        !!storage.activeIndexByFamily &&
+        targetIndex === storage.activeIndex;
     storage.activeIndex = targetIndex;
     storage.activeIndexByFamily = storage.activeIndexByFamily ?? {};
-    for (const family of MODEL_FAMILIES) {
-        storage.activeIndexByFamily[family] = targetIndex;
+    if (shouldPreserveActiveIndexByFamily) {
+        const maxIndex = Math.max(0, storage.accounts.length - 1);
+        for (const family of MODEL_FAMILIES) {
+            const raw = storage.activeIndexByFamily[family];
+            const candidate = typeof raw === "number" && Number.isFinite(raw) ? raw : targetIndex;
+            storage.activeIndexByFamily[family] = Math.max(0, Math.min(candidate, maxIndex));
+        }
+    }
+    else {
+        storage.activeIndexByFamily = storage.activeIndexByFamily ?? {};
+        for (const family of MODEL_FAMILIES) {
+            storage.activeIndexByFamily[family] = targetIndex;
+        }
     }
     const wasDisabled = account.enabled === false;
     if (wasDisabled) {
@@ -3813,7 +4252,7 @@ export async function runCodexMultiAuthCli(rawArgs) {
         return 0;
     }
     if (command === "login") {
-        return runAuthLogin();
+        return runAuthLogin(rest);
     }
     if (command === "list" || command === "status") {
         await showAccountStatus();