feat(auth): add backup restore manager

docs/reference/commands.md

@@ -26,6 +26,7 @@ Compatibility aliases are supported:
 | `codex auth switch <index>` | Set active account by index |
 | `codex auth check` | Run quick account health check |
 | `codex auth features` | Print implemented feature summary |
+| `codex auth restore-backup` | Open the backup restore picker directly |
 
 ---
 
@@ -111,6 +112,7 @@ codex auth report --live --json
 Repair and recovery:
 
 ```bash
+codex auth restore-backup
 codex auth fix --dry-run
 codex auth fix --live --model gpt-5-codex
 codex auth doctor --fix

docs/reference/public-api.md

@@ -37,6 +37,12 @@ Compatibility policy for Tier B:
 - Existing exported symbols must not be removed in this release line.
 - Deprecated usage may be documented, but hard removals require a major version transition plan.
 
+Current additive compatibility note:
+
+- `importAccounts()` now returns `{ imported, total, skipped, changed }` at runtime.
+- The exported `ImportAccountsResult` type keeps `changed` optional so older callers modeling the legacy shape remain source-compatible.
+- New callers should read `changed` to distinguish duplicate-only no-ops from metadata-refresh writes.
+
 ### Tier C: Internal APIs
 
 Internal APIs are any non-exported internals and implementation details not covered by Tier A or Tier B.

docs/reference/storage-paths.md

@@ -22,6 +22,7 @@ Override root:
 | --- | --- |
 | Unified settings | `~/.codex/multi-auth/settings.json` |
 | Accounts | `~/.codex/multi-auth/openai-codex-accounts.json` |
+| Named backups | `~/.codex/multi-auth/backups/<name>.json` |
 | Accounts backup | `~/.codex/multi-auth/openai-codex-accounts.json.bak` |
 | Accounts WAL | `~/.codex/multi-auth/openai-codex-accounts.json.wal` |
 | Flagged accounts | `~/.codex/multi-auth/openai-codex-flagged-accounts.json` |
@@ -56,6 +57,7 @@ Backup metadata:
 When project-scoped behavior is enabled:
 
 - `~/.codex/multi-auth/projects/<project-key>/openai-codex-accounts.json`
+- `~/.codex/multi-auth/projects/<project-key>/backups/<name>.json`
 
 `<project-key>` is derived as:
 
@@ -100,6 +102,17 @@ Rules:
 - `.rotate.`, `.tmp`, and `.wal` names are rejected
 - existing files are not overwritten unless a lower-level force path is used explicitly
 
+Restore workflow:
+
+1. Run `codex auth login`.
+2. Open the `Recovery` section.
+3. Choose `Restore From Backup`.
+4. Pick a backup and confirm the merge summary before import.
+
+Direct entrypoint:
+
+- Run `codex auth restore-backup` to open the same picker without entering the full login dashboard first.
+
 ---
 
 ## oc-chatgpt Target Paths
@@ -115,6 +128,7 @@ Experimental sync targets the companion `oc-chatgpt-multi-auth` storage layout:
 ## Verification Commands
 
 ```bash
+codex auth login
 codex auth status
 codex auth list
 ```

lib/cli.ts

@@ -57,6 +57,7 @@ export type LoginMode =
 	| "check"
 	| "deep-check"
 	| "verify-flagged"
+	| "restore-backup"
 	| "cancel";
 
 export interface ExistingAccountInfo {
@@ -233,6 +234,14 @@ async function promptLoginModeFallback(
 			) {
 				return { mode: "verify-flagged" };
 			}
+			if (
+				normalized === "u" ||
+				normalized === "backup" ||
+				normalized === "restore" ||
+				normalized === "restore-backup"
+			) {
+				return { mode: "restore-backup" };
+			}
 			if (normalized === "q" || normalized === "quit")
 				return { mode: "cancel" };
 			console.log(UI_COPY.fallback.invalidModePrompt);
@@ -287,6 +296,8 @@ export async function promptLoginMode(
 				return { mode: "deep-check" };
 			case "verify-flagged":
 				return { mode: "verify-flagged" };
+			case "restore-backup":
+				return { mode: "restore-backup" };
 			case "select-account": {
 				const accountAction = await showAccountDetails(action.account);
 				if (accountAction === "delete") {