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 you have named backups in your `backups/` directory and no active accounts, 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.
+
 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

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,
@@ -4176,6 +4178,8 @@ async function runBackupRestoreManager(
 
 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) {
@@ -4302,6 +4306,7 @@ async function runAuthLogin(): Promise<number> {
 					continue;
 				}
 				if (menuResult.mode === "fresh" && menuResult.deleteAll) {
+					suppressRecoveryPrompt = true;
 					await runActionPanel(
 						DESTRUCTIVE_ACTION_COPY.deleteSavedAccounts.label,
 						DESTRUCTIVE_ACTION_COPY.deleteSavedAccounts.stage,
@@ -4316,6 +4321,7 @@ async function runAuthLogin(): Promise<number> {
 					continue;
 				}
 				if (menuResult.mode === "reset") {
+					suppressRecoveryPrompt = true;
 					await runActionPanel(
 						DESTRUCTIVE_ACTION_COPY.resetLocalState.label,
 						DESTRUCTIVE_ACTION_COPY.resetLocalState.stage,
@@ -4360,6 +4366,37 @@ 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;
+			const recoveryState = await getActionableNamedBackupRestores({
+				currentStorage: refreshedStorage,
+			});
+			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"
+					} (${backupLabel}) in ${backupDir}. Restore now?`,
+				);
+				if (restoreNow) {
+					await runBackupRestoreManager(displaySettings);
+					continue;
+				}
+			}
+		}
 		let forceNewLogin = existingCount > 0;
 		while (true) {
 			const tokenResult = await runOAuthFlow(forceNewLogin);

lib/storage.ts

@@ -518,6 +518,11 @@ export interface BackupRestoreAssessment {
 	error?: string;
 }
 
+export interface ActionableNamedBackupRecoveries {
+	assessments: Awaited<ReturnType<typeof assessNamedBackupRestore>>[];
+	totalBackups: number;
+}
+
 export function getLastAccountsSaveTimestamp(): number {
 	return lastAccountsSaveTimestamp;
 }
@@ -1312,6 +1317,38 @@ export function getNamedBackupsDirectoryPath(): string {
 	return getNamedBackupsDirectory();
 }
 
+export async function getActionableNamedBackupRestores(
+	options: {
+		currentStorage?: AccountStorageV3 | null;
+		backups?: NamedBackupMetadata[];
+		assess?: typeof assessNamedBackupRestore;
+	} = {},
+): Promise<ActionableNamedBackupRecoveries> {
+	const backups = options.backups ?? (await listNamedBackups());
+	if (backups.length === 0) {
+		return { assessments: [], totalBackups: 0 };
+	}
+
+	const currentStorage =
+		options.currentStorage === undefined
+			? await loadAccounts()
+			: options.currentStorage;
+	const assess = options.assess ?? assessNamedBackupRestore;
+	const assessments = await Promise.all(
+		backups.map((backup) => assess(backup.name, { currentStorage })),
+	);
+
+	const actionable = assessments.filter(
+		(assessment) =>
+			assessment.valid &&
+			!assessment.wouldExceedLimit &&
+			assessment.imported !== null &&
+			assessment.imported > 0,
+	);
+
+	return { assessments: actionable, totalBackups: backups.length };
+}
+
 export async function createNamedBackup(
 	name: string,
 	options: { force?: boolean } = {},