test(auth): cover remaining onboarding restore gaps

Author: ndycode

docs/getting-started.md

@@ -44,15 +44,17 @@ codex auth login
 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.
+See upgrade note: [onboarding restore behavior](upgrade.md#onboarding-restore-note).
 
 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` by default, or under `%CODEX_MULTI_AUTH_DIR%\backups` if you override the storage root with `CODEX_MULTI_AUTH_DIR`
+   - `Recover saved accounts` when the current pool is empty and at least one valid 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
+   Empty, unreadable, or non-JSON backup sidecar files are skipped, so the menu entry appears only when at least one backup parses successfully and contains at least one account.
 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.

docs/upgrade.md

@@ -64,6 +64,16 @@ For maintainer/debug flows, see advanced/internal controls in [development/CONFI
 
 ---
 
+## Onboarding Restore Note
+
+`codex auth login` now opens directly into the sign-in menu when the active pool is empty, instead of opening the account dashboard first.
+
+- `Recover saved accounts` appears only when at least one valid named backup exists.
+- No new CLI flags or npm scripts were added for this flow.
+- The backup root remains `~/.codex/multi-auth/backups` by default, or `%CODEX_MULTI_AUTH_DIR%\\backups` when `CODEX_MULTI_AUTH_DIR` is set.
+
+---
+
 ## Legacy Compatibility
 
 Legacy files may still be discovered during migration-only compatibility checks.

lib/codex-manager.ts

@@ -1141,7 +1141,7 @@ async function promptManualCallback(state: string): Promise<string | null> {
 type OAuthSignInMode = "browser" | "manual" | "restore-backup" | "cancel";
 type BackupRestoreMode = "latest" | "manual" | "back";
 
-function formatBackupSavedAt(mtimeMs: number): string {
+export function formatBackupSavedAt(mtimeMs: number): string {
 	return new Date(mtimeMs).toLocaleString(undefined, {
 		month: "short",
 		day: "numeric",

lib/storage.ts

@@ -166,7 +166,11 @@ async function collectNamedBackups(storagePath: string): Promise<NamedBackupSumm
 		}
 	}
 
-	candidates.sort((left, right) => right.mtimeMs - left.mtimeMs);
+	candidates.sort((left, right) => {
+		const mtimeDelta = right.mtimeMs - left.mtimeMs;
+		if (mtimeDelta !== 0) return mtimeDelta;
+		return left.fileName.localeCompare(right.fileName);
+	});
 	return candidates;
 }
 
@@ -898,8 +902,9 @@ export async function restoreAccountsFromBackup(
 	}
 	const relativePath = relative(resolvedBackupRoot, resolvedBackupPath);
 	const isInsideBackupRoot =
-		relativePath === "" ||
-		(!relativePath.startsWith("..") && !isAbsolute(relativePath));
+		relativePath.length > 0 &&
+		!relativePath.startsWith("..") &&
+		!isAbsolute(relativePath);
 	if (!isInsideBackupRoot) {
 		throw new Error(`Backup path must stay inside ${resolvedBackupRoot}: ${path}`);
 	}

test/codex-manager-cli.test.ts

@@ -539,6 +539,26 @@ describe("codex manager cli commands", () => {
 		vi.restoreAllMocks();
 	});
 
+	it("formats backup saved-at timestamps with the runtime locale options", async () => {
+		const localeSpy = vi
+			.spyOn(Date.prototype, "toLocaleString")
+			.mockReturnValue("Localized Saved Time");
+		const { formatBackupSavedAt } = await import("../lib/codex-manager.js");
+
+		try {
+			expect(formatBackupSavedAt(1_710_000_000_000)).toBe("Localized Saved Time");
+			expect(localeSpy).toHaveBeenCalledWith(undefined, {
+				month: "short",
+				day: "numeric",
+				year: "numeric",
+				hour: "numeric",
+				minute: "2-digit",
+			});
+		} finally {
+			localeSpy.mockRestore();
+		}
+	});
+
 	it("runs forecast in json mode", async () => {
 		const now = Date.now();
 		loadAccountsMock.mockResolvedValueOnce({
@@ -3281,6 +3301,7 @@ describe("codex manager cli commands", () => {
 			.mockResolvedValueOnce("restore-backup")
 			.mockResolvedValueOnce("latest");
 		promptLoginModeMock.mockResolvedValueOnce({ mode: "cancel" });
+		const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
 		const { runCodexMultiAuthCli } = await import("../lib/codex-manager.js");
 
 		const exitCode = await runCodexMultiAuthCli(["auth", "login"]);
@@ -3297,6 +3318,9 @@ describe("codex manager cli commands", () => {
 				email: "warn@example.com",
 			}),
 		);
+		expect(logSpy).toHaveBeenCalledWith(
+			expect.stringContaining("Codex auth sync did not complete"),
+		);
 		expect(promptLoginModeMock).toHaveBeenCalledTimes(1);
 		expect(selectMock).toHaveBeenCalledTimes(2);
 	});
@@ -3330,6 +3354,9 @@ describe("codex manager cli commands", () => {
 			"C:/mock/backups/locked.json",
 			{ persist: false },
 		);
+		expect(saveAccountsMock).not.toHaveBeenCalled();
+		expect(promptLoginModeMock).not.toHaveBeenCalled();
+		expect(selectMock).toHaveBeenCalledTimes(3);
 		expect(errorSpy).toHaveBeenCalledWith("Backup restore failed: File is busy");
 	});
 
@@ -3609,6 +3636,7 @@ describe("codex manager cli commands", () => {
 		const exitCode = await runCodexMultiAuthCli(["auth", "login"]);
 
 		expect(exitCode).toBe(0);
+		expect(getNamedBackupsMock).toHaveBeenCalledTimes(1);
 		expect(restoreAccountsFromBackupMock).toHaveBeenCalledWith(
 			"/mock/backups/manual-choice.json",
 			{ persist: false },

test/storage-last-backup.test.ts

@@ -115,6 +115,60 @@ describe("storage last backup restore", () => {
 		]);
 	});
 
+	it("breaks backup mtime ties with a deterministic file-name order", async () => {
+		const alphaBackupPath = buildNamedBackupPath("backup-alpha");
+		const betaBackupPath = buildNamedBackupPath("backup-beta");
+		await fs.mkdir(dirname(alphaBackupPath), { recursive: true });
+		for (const backupPath of [betaBackupPath, alphaBackupPath]) {
+			await fs.writeFile(
+				backupPath,
+				JSON.stringify({
+					version: 3,
+					activeIndex: 0,
+					activeIndexByFamily: { codex: 0 },
+					accounts: [{ refreshToken: `${backupPath}-refresh`, addedAt: 1, lastUsed: 1 }],
+				}),
+				"utf-8",
+			);
+			await fs.utimes(
+				backupPath,
+				new Date("2026-03-04T00:00:00.000Z"),
+				new Date("2026-03-04T00:00:00.000Z"),
+			);
+		}
+
+		const backups = await getNamedBackups();
+
+		expect(backups.map((backup) => backup.fileName)).toEqual([
+			"backup-alpha.json",
+			"backup-beta.json",
+		]);
+	});
+
+	it("ignores non-json files and subdirectories in the backup root", async () => {
+		const backupPath = buildNamedBackupPath("real-backup");
+		const backupRoot = dirname(backupPath);
+		await fs.mkdir(backupRoot, { recursive: true });
+		await fs.writeFile(
+			backupPath,
+			JSON.stringify({
+				version: 3,
+				activeIndex: 0,
+				activeIndexByFamily: { codex: 0 },
+				accounts: [{ refreshToken: "real-refresh", addedAt: 1, lastUsed: 1 }],
+			}),
+			"utf-8",
+		);
+		await fs.writeFile(join(backupRoot, "sidecar.tmp"), "lock", "utf-8");
+		await fs.writeFile(join(backupRoot, "notes.bak"), "ignored", "utf-8");
+		await fs.mkdir(join(backupRoot, "subdir"), { recursive: true });
+
+		const backups = await getNamedBackups();
+
+		expect(backups).toHaveLength(1);
+		expect(backups[0]?.fileName).toBe("real-backup.json");
+	});
+
 	it("skips a backup that disappears before stat and falls back to the next valid backup", async () => {
 		const flakyBackupPath = buildNamedBackupPath("backup-flaky");
 		const stableBackupPath = buildNamedBackupPath("backup-stable");
@@ -198,8 +252,14 @@ describe("storage last backup restore", () => {
 
 		expect(restored.accounts).toHaveLength(2);
 		expect(restored.activeIndex).toBe(1);
+		expect(restored.activeIndexByFamily).toEqual(
+			expect.objectContaining({ codex: 1 }),
+		);
 		expect(loaded?.accounts).toHaveLength(2);
 		expect(loaded?.activeIndex).toBe(1);
+		expect(loaded?.activeIndexByFamily).toEqual(
+			expect.objectContaining({ codex: 1 }),
+		);
 		expect(loaded?.accounts[1]?.refreshToken).toBe("refresh-2");
 	});
 
@@ -231,9 +291,15 @@ describe("storage last backup restore", () => {
 
 		expect(restored.accounts).toHaveLength(2);
 		expect(restored.activeIndex).toBe(1);
+		expect(restored.activeIndexByFamily).toEqual(
+			expect.objectContaining({ codex: 1 }),
+		);
 		expect(loaded?.accounts).toHaveLength(1);
 		expect(loaded?.accounts[0]?.refreshToken).toBe("current-refresh");
 		expect(loaded?.activeIndex).toBe(0);
+		expect(loaded?.activeIndexByFamily).toEqual(
+			expect.objectContaining({ codex: 0 }),
+		);
 	});
 
 	it("throws when the named backup has no accounts", async () => {
@@ -314,6 +380,55 @@ describe("storage last backup restore", () => {
 		);
 	});
 
+	it("rejects the backup root directory itself as a restore target", async () => {
+		const backupPath = buildNamedBackupPath("backup-root-guard");
+		const backupRoot = dirname(backupPath);
+		await fs.mkdir(backupRoot, { recursive: true });
+
+		await expect(restoreAccountsFromBackup(backupRoot)).rejects.toThrow(
+			"Backup path must stay inside",
+		);
+	});
+
+	it("rejects a path inside the backup tree when realpath escapes outside the root", async () => {
+		const linkedBackupPath = buildNamedBackupPath("backup-link");
+		const backupRoot = dirname(linkedBackupPath);
+		const escapedBackupPath = join(testRoot, "backup-outside-root.json");
+		await fs.mkdir(backupRoot, { recursive: true });
+		await fs.writeFile(
+			escapedBackupPath,
+			JSON.stringify({
+				version: 3,
+				activeIndex: 0,
+				activeIndexByFamily: { codex: 0 },
+				accounts: [{ refreshToken: "outside-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) === linkedBackupPath) {
+				return originalRealpath(
+					escapedBackupPath as Parameters<typeof originalRealpath>[0],
+					options as Parameters<typeof originalRealpath>[1],
+				);
+			}
+			return originalRealpath(
+				path as Parameters<typeof originalRealpath>[0],
+				options as Parameters<typeof originalRealpath>[1],
+			);
+		});
+
+		try {
+			await expect(restoreAccountsFromBackup(linkedBackupPath)).rejects.toThrow(
+				"Backup path must stay inside",
+			);
+		} finally {
+			realpathSpy.mockRestore();
+		}
+	});
+
 	it("throws a clear error when the backup root has never been created", async () => {
 		const escapedBackupPath = join(testRoot, "backup-outside-root.json");
 		await fs.writeFile(