feat(auth): prompt for recovery on startup

docs/getting-started.md

@@ -49,6 +49,8 @@ Expected flow:
 4. Return to the terminal when the browser step completes.
 5. Confirm the account appears in the saved account list.
 
+If interactive `codex auth login` starts with zero saved accounts and recoverable named backups in your `backups/` directory, the login flow will prompt you to restore before opening OAuth. Confirm to launch the existing restore manager; skip to proceed with a fresh login. The prompt is suppressed in non-interactive/fallback flows and after same-session `fresh` or `reset` actions.
+
 Verify the new account:
 
 ```bash

docs/troubleshooting.md

@@ -18,6 +18,8 @@ If the account pool is still not usable:
 codex auth login
 ```
 
+If `codex auth login` starts with no saved accounts and named backups are present, you will be prompted to restore before OAuth. This prompt only appears in interactive terminals and is skipped after intentional reset flows.
+
 ---
 
 ## Verify Install And Routing

docs/upgrade.md

@@ -62,6 +62,12 @@ After source selection, environment variables still override individual setting
 For day-to-day operator use, prefer stable overrides documented in [configuration.md](configuration.md).
 For maintainer/debug flows, see advanced/internal controls in [development/CONFIG_FIELDS.md](development/CONFIG_FIELDS.md).
 
+### Startup Recovery Prompt
+
+Interactive `codex auth login` now offers named-backup recovery before OAuth only when the session starts with zero saved accounts and at least one recoverable named backup.
+
+The prompt is intentionally skipped in fallback/non-interactive login paths and after same-session `fresh` or `reset` actions so an intentional wipe does not immediately re-offer restore state.
+
 ---
 
 ## Legacy Compatibility

lib/cli.ts

@@ -26,6 +26,10 @@ export function isNonInteractiveMode(): boolean {
 	return false;
 }
 
+export function isInteractiveLoginMenuAvailable(): boolean {
+	return !isNonInteractiveMode() && isTTY();
+}
+
 export async function promptAddAnotherAccount(
 	currentCount: number,
 ): Promise<boolean> {
@@ -243,7 +247,7 @@ export async function promptLoginMode(
 		return { mode: "add" };
 	}
 
-	if (!isTTY()) {
+	if (!isInteractiveLoginMenuAvailable()) {
 		return promptLoginModeFallback(existingAccounts);
 	}
 

lib/codex-manager.ts

@@ -23,6 +23,7 @@ import { copyTextToClipboard, openBrowserUrl } from "./auth/browser.js";
 import { startLocalOAuthServer } from "./auth/server.js";
 import {
 	type ExistingAccountInfo,
+	isInteractiveLoginMenuAvailable,
 	promptAddAnotherAccount,
 	promptLoginMode,
 } from "./cli.js";
@@ -76,6 +77,7 @@ import {
 	assessNamedBackupRestore,
 	type FlaggedAccountMetadataV1,
 	type FlaggedAccountStorageV1,
+	getActionableNamedBackupRestores,
 	getNamedBackupsDirectoryPath,
 	getStoragePath,
 	listNamedBackups,
@@ -4092,22 +4094,42 @@ type BackupMenuAction =
 	  }
 	| { type: "back" };
 
+type BackupRestoreManagerResult = "restored" | "dismissed";
+
 async function runBackupRestoreManager(
 	displaySettings: DashboardDisplaySettings,
-): Promise<void> {
+): Promise<BackupRestoreManagerResult> {
 	const backupDir = getNamedBackupsDirectoryPath();
 	const backups = await listNamedBackups();
 	if (backups.length === 0) {
 		console.log(`No named backups found. Place backup files in ${backupDir}.`);
-		return;
+		return "dismissed";
 	}
 
 	const currentStorage = await loadAccounts();
-	const assessments = await Promise.all(
-		backups.map((backup) =>
-			assessNamedBackupRestore(backup.name, { currentStorage }),
-		),
-	);
+	const assessments: Awaited<ReturnType<typeof assessNamedBackupRestore>>[] = [];
+	for (const backup of backups) {
+		try {
+			assessments.push(
+				await assessNamedBackupRestore(backup.name, { currentStorage }),
+			);
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			console.warn(
+				`Failed to assess backup "${backup.name}" in restore manager: ${message}`,
+			);
+			assessments.push({
+				backup,
+				currentAccountCount: currentStorage?.accounts.length ?? 0,
+				mergedAccountCount: null,
+				imported: null,
+				skipped: null,
+				wouldExceedLimit: false,
+				valid: false,
+				error: message,
+			});
+		}
+	}
 
 	const items: MenuItem<BackupMenuAction>[] = assessments.map((assessment) => {
 		const status =
@@ -4155,27 +4177,30 @@ async function runBackupRestoreManager(
 	});
 
 	if (!selection || selection.type === "back") {
-		return;
+		return "dismissed";
 	}
 
 	const assessment = selection.assessment;
 	if (!assessment.valid || assessment.wouldExceedLimit) {
 		console.log(assessment.error ?? "Backup is not eligible for restore.");
-		return;
+		return "dismissed";
 	}
 
 	const confirmMessage = `Restore backup "${assessment.backup.name}"? This will merge ${assessment.backup.accountCount ?? 0} account(s) into ${assessment.currentAccountCount} current (${assessment.mergedAccountCount ?? assessment.currentAccountCount} after dedupe).`;
 	const confirmed = await confirm(confirmMessage);
-	if (!confirmed) return;
+	if (!confirmed) return "dismissed";
 
 	const result = await restoreNamedBackup(assessment.backup.name);
 	console.log(
 		`Restored backup "${assessment.backup.name}". Imported ${result.imported}, skipped ${result.skipped}, total ${result.total}.`,
 	);
+	return "restored";
 }
 
 async function runAuthLogin(): Promise<number> {
 	setStoragePath(null);
+	let suppressRecoveryPrompt = false;
+	let recoveryPromptAttempted = false;
 	let pendingMenuQuotaRefresh: Promise<void> | null = null;
 	let menuQuotaRefreshStatus: string | undefined;
 	loginFlow: while (true) {
@@ -4313,6 +4338,7 @@ async function runAuthLogin(): Promise<number> {
 						},
 						displaySettings,
 					);
+					suppressRecoveryPrompt = true;
 					continue;
 				}
 				if (menuResult.mode === "reset") {
@@ -4325,6 +4351,7 @@ async function runAuthLogin(): Promise<number> {
 						},
 						displaySettings,
 					);
+					suppressRecoveryPrompt = true;
 					continue;
 				}
 				if (menuResult.mode === "manage") {
@@ -4360,6 +4387,52 @@ async function runAuthLogin(): Promise<number> {
 
 		const refreshedStorage = await loadAccounts();
 		const existingCount = refreshedStorage?.accounts.length ?? 0;
+		const canPromptForRecovery =
+			!suppressRecoveryPrompt &&
+			!recoveryPromptAttempted &&
+			existingCount === 0 &&
+			isInteractiveLoginMenuAvailable();
+		if (canPromptForRecovery) {
+			recoveryPromptAttempted = true;
+			let recoveryState: Awaited<
+				ReturnType<typeof getActionableNamedBackupRestores>
+			>;
+			try {
+				recoveryState = await getActionableNamedBackupRestores({
+					currentStorage: refreshedStorage,
+				});
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				console.warn(
+					`Startup recovery scan failed: ${message}. Continuing with OAuth.`,
+				);
+				recoveryState = { assessments: [], totalBackups: 0 };
+			}
+			if (recoveryState.assessments.length > 0) {
+				const displaySettings = await loadDashboardDisplaySettings();
+				applyUiThemeFromDashboardSettings(displaySettings);
+				const backupDir = getNamedBackupsDirectoryPath();
+				const sample = recoveryState.assessments[0];
+				const backupLabel =
+					sample?.backup.name ??
+					`${recoveryState.assessments.length} backup${
+						recoveryState.assessments.length === 1 ? "" : "s"
+					}`;
+				const restoreNow = await confirm(
+					`Found ${recoveryState.assessments.length} recoverable backup${
+						recoveryState.assessments.length === 1 ? "" : "s"
+					} out of ${recoveryState.totalBackups} total (${backupLabel}) in ${backupDir}. Restore now?`,
+				);
+				if (restoreNow) {
+					const restoreResult =
+						await runBackupRestoreManager(displaySettings);
+					if (restoreResult !== "restored") {
+						recoveryPromptAttempted = false;
+					}
+					continue;
+				}
+			}
+		}
 		let forceNewLogin = existingCount > 0;
 		while (true) {
 			const tokenResult = await runOAuthFlow(forceNewLogin);