fix(auth): close onboarding restore review gaps

Author: ndycode

docs/getting-started.md

@@ -45,16 +45,17 @@ Expected flow:
 
 Backup restore appears under the `Recover saved accounts` heading in the onboarding menu. This flow does not add any new CLI flags or npm scripts.
 
-1. The dashboard opens in the terminal.
-2. Choose `Add New Account`.
-3. Choose one of the sign-in options:
+1. If no accounts are saved yet, the terminal opens directly to the sign-in menu.
+2. Choose one of the sign-in options:
    - `Open Browser (Easy)` for the normal OAuth flow
    - `Manual / Incognito` when you need to paste the callback yourself
-   - `Recover saved accounts` when the current pool is empty and a named backup exists under `~/.codex/multi-auth/backups`
-4. If you choose the backup restore flow under `Recover saved accounts`, a second menu lets you either load the newest valid backup automatically or pick a backup manually from a newest-first list.
-5. If you use browser or manual sign-in, complete the official OAuth flow and return to the terminal.
-6. If you load a backup, the selected named backup is restored and its active account is synced back into Codex CLI auth.
-7. Confirm the account appears in the saved account list.
+   - `Recover saved accounts` when the current pool is empty and a named backup exists under `~/.codex/multi-auth/backups` by default, or under `%CODEX_MULTI_AUTH_DIR%\backups` if you override the storage root with `CODEX_MULTI_AUTH_DIR`
+3. If you choose `Recover saved accounts`, the next menu lets you either:
+   - load the newest valid backup automatically
+   - pick a specific backup from a newest-first list
+4. If you use browser or manual sign-in, complete the official OAuth flow and return to the terminal.
+5. If you load a backup, the selected backup is restored, its active account is synced back into Codex CLI auth, and the login flow continues with that restored pool.
+6. Confirm the restored or newly signed-in account appears in the saved account list.
 
 Verify the new account:
 

lib/codex-manager.ts

@@ -4381,9 +4381,7 @@ async function runAuthLogin(): Promise<number> {
 				}
 
 				const selectedBackup = restoreMode === "manual"
-					? await promptManualBackupSelection(
-						await getNamedBackups().catch(() => []),
-					)
+					? await promptManualBackupSelection(namedBackups)
 					: latestNamedBackup;
 				if (!selectedBackup) {
 					continue;

lib/storage.ts

@@ -886,7 +886,16 @@ export async function restoreAccountsFromBackup(
 		}
 		throw error;
 	}
-	const resolvedBackupPath = await fs.realpath(path);
+	let resolvedBackupPath: string;
+	try {
+		resolvedBackupPath = await fs.realpath(path);
+	} catch (error) {
+		const code = (error as NodeJS.ErrnoException).code;
+		if (code === "ENOENT") {
+			throw new Error(`Backup file no longer exists: ${path}`);
+		}
+		throw error;
+	}
 	const relativePath = relative(resolvedBackupRoot, resolvedBackupPath);
 	const isInsideBackupRoot =
 		relativePath === "" ||

test/codex-manager-cli.test.ts

@@ -3035,44 +3035,89 @@ describe("codex manager cli commands", () => {
 			.mockResolvedValueOnce("latest");
 		promptLoginModeMock.mockResolvedValueOnce({ mode: "cancel" });
 		const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+		const localeSpy = vi
+			.spyOn(Date.prototype, "toLocaleString")
+			.mockReturnValue("Localized Saved Time");
+		const { runCodexMultiAuthCli } = await import("../lib/codex-manager.js");
+
+		try {
+			const exitCode = await runCodexMultiAuthCli(["auth", "login"]);
+
+			expect(exitCode).toBe(0);
+			expect(getNamedBackupsMock).toHaveBeenCalled();
+			const signInItems = selectMock.mock.calls[0]?.[0] as Array<{
+				label: string;
+				kind?: string;
+				hint?: string;
+			}>;
+			expect(signInItems.map((item) => item.label)).toContain(
+				"Recover saved accounts",
+			);
+			expect(signInItems.find((item) => item.label === "Recover saved accounts")?.kind).toBe(
+				"heading",
+			);
+			expect(
+				signInItems.find((item) => item.label === "Restore Saved Backup")?.hint,
+			).toBe("last-good.json | 2 accounts | saved Localized Saved Time");
+			expect(localeSpy).toHaveBeenCalledWith(undefined, {
+				month: "short",
+				day: "numeric",
+				year: "numeric",
+				hour: "numeric",
+				minute: "2-digit",
+			});
+			expect(restoreAccountsFromBackupMock).toHaveBeenCalledWith(
+				"/mock/backups/last-good.json",
+				{ persist: false },
+			);
+			expect(confirmMock).toHaveBeenCalledWith("Load last-good.json (2 accounts)?");
+			expect(saveAccountsMock).toHaveBeenCalledTimes(1);
+			expect(saveAccountsMock.mock.calls[0]?.[0]).toEqual(
+				expect.objectContaining({
+					activeIndex: 1,
+					activeIndexByFamily: { codex: 1 },
+				}),
+			);
+			expect(setCodexCliActiveSelectionMock).toHaveBeenCalledWith(
+				expect.objectContaining({
+					accountId: "acc_restored",
+					email: "restored@example.com",
+				}),
+			);
+			expect(logSpy).toHaveBeenCalledWith(
+				"Loaded last-good.json (2 accounts).",
+			);
+			expect(promptLoginModeMock).toHaveBeenCalledTimes(1);
+		} finally {
+			localeSpy.mockRestore();
+		}
+	});
+
+	it("returns to onboarding when restore mode is back", async () => {
+		const now = Date.now();
+		setInteractiveTTY(true);
+		loadAccountsMock.mockResolvedValue(null);
+		getNamedBackupsMock.mockResolvedValue([
+			{
+				path: "/mock/backups/latest.json",
+				fileName: "latest.json",
+				accountCount: 1,
+				mtimeMs: now,
+			},
+		]);
+		selectMock
+			.mockResolvedValueOnce("restore-backup")
+			.mockResolvedValueOnce("back")
+			.mockResolvedValueOnce("cancel");
 		const { runCodexMultiAuthCli } = await import("../lib/codex-manager.js");
 
 		const exitCode = await runCodexMultiAuthCli(["auth", "login"]);
 
 		expect(exitCode).toBe(0);
-		expect(getNamedBackupsMock).toHaveBeenCalled();
-		const signInItems = selectMock.mock.calls[0]?.[0] as Array<{
-			label: string;
-			kind?: string;
-		}>;
-		expect(signInItems.map((item) => item.label)).toContain(
-			"Recover saved accounts",
-		);
-		expect(signInItems.find((item) => item.label === "Recover saved accounts")?.kind).toBe(
-			"heading",
-		);
-		expect(restoreAccountsFromBackupMock).toHaveBeenCalledWith(
-			"/mock/backups/last-good.json",
-			{ persist: false },
-		);
-		expect(confirmMock).toHaveBeenCalledWith("Load last-good.json (2 accounts)?");
-		expect(saveAccountsMock).toHaveBeenCalledTimes(1);
-		expect(saveAccountsMock.mock.calls[0]?.[0]).toEqual(
-			expect.objectContaining({
-				activeIndex: 1,
-				activeIndexByFamily: { codex: 1 },
-			}),
-		);
-		expect(setCodexCliActiveSelectionMock).toHaveBeenCalledWith(
-			expect.objectContaining({
-				accountId: "acc_restored",
-				email: "restored@example.com",
-			}),
-		);
-		expect(logSpy).toHaveBeenCalledWith(
-			"Loaded last-good.json (2 accounts).",
-		);
-		expect(promptLoginModeMock).toHaveBeenCalledTimes(1);
+		expect(restoreAccountsFromBackupMock).not.toHaveBeenCalled();
+		expect(confirmMock).not.toHaveBeenCalled();
+		expect(saveAccountsMock).not.toHaveBeenCalled();
+		expect(promptLoginModeMock).not.toHaveBeenCalled();
 	});
 
 	it("returns to the onboarding menu when the manual backup picker is backed out", async () => {
@@ -3111,6 +3156,7 @@ describe("codex manager cli commands", () => {
 
 	it("does not offer backup restore on onboarding when accounts already exist", async () => {
 		const now = Date.now();
+		setInteractiveTTY(true);
 		loadAccountsMock
 			.mockResolvedValueOnce({
 				version: 3,
@@ -3152,6 +3198,7 @@ describe("codex manager cli commands", () => {
 		const exitCode = await runCodexMultiAuthCli(["auth", "login"]);
 
 		expect(exitCode).toBe(0);
+		expect(promptLoginModeMock).toHaveBeenCalledTimes(1);
 		expect(getNamedBackupsMock).not.toHaveBeenCalled();
 	});
 

test/storage-last-backup.test.ts

@@ -255,6 +255,45 @@ describe("storage last backup restore", () => {
 		);
 	});
 
+	it("throws a clear error when a backup disappears before restore realpath", async () => {
+		const backupPath = buildNamedBackupPath("backup-disappeared-before-restore");
+		await fs.mkdir(dirname(backupPath), { recursive: true });
+		await fs.writeFile(
+			backupPath,
+			JSON.stringify({
+				version: 3,
+				activeIndex: 0,
+				activeIndexByFamily: { codex: 0 },
+				accounts: [{ refreshToken: "gone-refresh", addedAt: 1, lastUsed: 1 }],
+			}),
+			"utf-8",
+		);
+
+		const originalRealpath = fs.realpath.bind(fs);
+		const realpathSpy = vi.spyOn(fs, "realpath").mockImplementation(async (path, options) => {
+			if (String(path) === backupPath) {
+				await fs.rm(backupPath, { force: true });
+				const error = new Error(
+					`ENOENT: no such file or directory, realpath '${backupPath}'`,
+				) as NodeJS.ErrnoException;
+				error.code = "ENOENT";
+				throw error;
+			}
+			return originalRealpath(
+				path as Parameters<typeof originalRealpath>[0],
+				options as Parameters<typeof originalRealpath>[1],
+			);
+		});
+
+		try {
+			await expect(restoreAccountsFromBackup(backupPath)).rejects.toThrow(
+				`Backup file no longer exists: ${backupPath}`,
+			);
+		} finally {
+			realpathSpy.mockRestore();
+		}
+	});
+
 	it("rejects restore paths outside the managed named-backup root", async () => {
 		const backupPath = buildNamedBackupPath("backup-inside-root");
 		const escapedBackupPath = join(testRoot, "backup-outside-root.json");