Skip to content

feat(settings): productize stable and advanced controls #108

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ndycode wants to merge 26 commits into
base: dev
Choose a base branch
from
Open

feat(settings): productize stable and advanced controls #108

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
26 commits
Select commit Hold shift + click to select a range
af7f137
fix(auth): define reset and delete safety flows
ndycode Mar 15, 2026
f48ee06
feat(auth): add backup restore manager
ndycode Mar 15, 2026
12074e2
feat(auth): prompt for recovery on startup
ndycode Mar 15, 2026
8212831
test(storage): isolate empty export path
ndycode Mar 15, 2026
eeecf6e
feat(sync): add sync center and status surface
ndycode Mar 15, 2026
ccb06f6
fix(auth): clean startup recovery prompt branch
ndycode Mar 16, 2026
d0a80b5
feat(settings): productize stable and advanced controls
ndycode Mar 15, 2026
310325d
fix(auth): drop recovery fallback from settings slice
ndycode Mar 16, 2026
2ee71fb
fix(sync): harden sync center preview and apply
ndycode Mar 16, 2026
1eeec0b
Block non-interactive backup restore mode
ndycode Mar 16, 2026
9ec55db
Fix backup import accounting regressions
ndycode Mar 16, 2026
326d5f1
fix(auth): harden restore backup fallback and file reads
ndycode Mar 16, 2026
11c503c
fix(sync): close backup restore review gaps
ndycode Mar 16, 2026
e0e7680
fix(sync): preserve sync run timestamps
ndycode Mar 16, 2026
19b50d3
fix(sync): resolve review blockers
ndycode Mar 17, 2026
922c5de
fix(sync): close remaining review blockers
ndycode Mar 17, 2026
ce4fbf3
test(sync): cover retryable timestamp and scan errors
ndycode Mar 17, 2026
8ba80e7
Retry sync timestamp reads on EIO
ndycode Mar 17, 2026
dbe3c1c
Harden recovery backup reads
ndycode Mar 17, 2026
1a7ae95
test(sync): cover ENXIO and UNC sync-center paths
ndycode Mar 17, 2026
ea74af4
fix(restore): reuse pre-assessed backup restore
ndycode Mar 17, 2026
ef68e86
fix(sync): ignore storage-noise watch artifacts
ndycode Mar 17, 2026
f811d3d
Redact sync center filesystem errors
ndycode Mar 17, 2026
5e174c8
Redact stored sync run errors
ndycode Mar 17, 2026
c31c9ed
Merge remote-tracking branch 'origin/fresh/04-sync-center' into fresh…
ndycode Mar 17, 2026
f2f8427
fix(settings): tighten docs and sync-center coverage
ndycode Mar 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 6 additions & 3 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,7 @@ Codex CLI-first multi-account OAuth manager for the official `@openai/codex` CLI
### Option A: Standard install

```bash
npm i -g @openai/codex
npm i -g codex-multi-auth
```

Expand All @@ -74,16 +75,18 @@ codex auth status

### Step-by-step

1. Install global package:
1. Install global packages:
- `npm i -g @openai/codex`
- `npm i -g codex-multi-auth`
2. Run first login flow with `codex auth login`
3. Validate state with `codex auth status` and `codex auth check`
3. Validate state with `codex auth list` and `codex auth check`
4. Confirm routing with `codex auth forecast --live`

### Verification

```bash
codex auth status
codex auth list
codex auth check
```

Expand All @@ -95,7 +98,7 @@ codex auth check

```bash
codex auth login
codex auth status
codex auth list
codex auth check
codex auth forecast --live
```
Expand Down
2 changes: 2 additions & 0 deletions docs/getting-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 2 additions & 0 deletions docs/reference/commands.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 |

---

Expand Down Expand Up @@ -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
Expand Down
6 changes: 6 additions & 0 deletions docs/reference/public-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
46 changes: 35 additions & 11 deletions docs/reference/settings.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Settings Reference

Reference for dashboard and backend settings available from `codex auth login` -> `Settings`.
Reference for the settings surface available from `codex auth login` -> `Settings`.

---

Expand All @@ -19,7 +19,11 @@ When `CODEX_MULTI_AUTH_DIR` is set, this root moves accordingly.

---

## Account List View
## Everyday Settings

The top-level settings flow separates everyday dashboard preferences from advanced operator controls.

### List Appearance

Controls account-row display and sorting behavior:

Expand All @@ -37,7 +41,7 @@ Controls account-row display and sorting behavior:
- `menuSortQuickSwitchVisibleRow`
- `menuLayoutMode`

## Summary Line
### Details Line

Controls detail-line fields and order:

Expand All @@ -46,7 +50,7 @@ Controls detail-line fields and order:
- `limits`
- `status`

## Menu Behavior
### Results & Refresh

Controls result-screen and fetch behavior:

Expand All @@ -56,7 +60,7 @@ Controls result-screen and fetch behavior:
- `menuShowFetchStatus`
- `menuQuotaTtlMs`

## Color Theme
### Colors

Controls display style:

Expand All @@ -66,7 +70,23 @@ Controls display style:

---

## Experimental
## Advanced and Operator Controls

### Codex CLI Sync

The advanced section includes a preview-first sync center for Codex CLI account sync.
See [upgrade notes](../upgrade.md) for sync workflow changes.
Comment on lines +73 to 78
Copy link
Contributor

@coderabbitai coderabbitai bot Mar 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

align advanced section wording with shipped ui copy.

line 73 and line 77 in docs/reference/settings.md still use legacy wording ("advanced and operator controls", "sync center"), while the menu ships "advanced & operator" and "codex cli sync" in lib/ui/copy.ts:69-79 and renders them in lib/codex-manager/settings-hub.ts:3335-3356.

as per coding guidelines "UI text consistency: ensure synonyms and titles match the updated copy (e.g., Details Line for Summary Line, Colors for Color Theme, Codex CLI Sync for Sync Center)."

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@docs/reference/settings.md` around lines 73 - 78, Update the docs wording in
the settings page to exactly match the shipped UI copy: replace the header text
"Advanced and Operator Controls" with "advanced & operator" and change the
phrase "sync center" (or "sync center for Codex CLI account sync") to "codex cli
sync" so the docs mirror the strings used by the UI; search for those legacy
phrases in the settings documentation and update them to the exact UI strings
("advanced & operator" and "codex cli sync") used by the UI copy and settings
renderer.


Before applying sync, it shows:

- target path
- current source path when available
- last sync result for this session
- preview summary (adds, updates, destination-only preserved accounts)
- destination-only preservation behavior
- backup and rollback context (`.bak`, `.bak.1`, `.bak.2`, `.wal`)

### Experimental

Experimental currently hosts:

Expand All @@ -88,9 +108,13 @@ Named backup behavior:
- rejects separators, traversal (`..`), `.rotate.`, `.tmp`, and `.wal` suffixes
- fails safely on collisions instead of overwriting by default

## Backend Controls
### Advanced Backend Controls

Expert backend controls stay available without changing the saved settings schema. They are grouped into categories so the default path can stay simpler for day-to-day use.

Backend categories include:

### Session & Sync
#### Session & Sync

Examples:

Expand All @@ -102,7 +126,7 @@ Examples:
- `sessionAffinityMaxEntries`
- `perProjectAccounts`

### Rotation & Quota
#### Rotation & Quota

Examples:

Expand All @@ -114,7 +138,7 @@ Examples:
- `retryAllAccountsMaxWaitMs`
- `retryAllAccountsMaxRetries`

### Refresh & Recovery
#### Refresh & Recovery

Examples:

Expand All @@ -124,7 +148,7 @@ Examples:
- `sessionRecovery`
- `autoResume`

### Performance & Timeouts
#### Performance & Timeouts

Examples:

Expand Down
14 changes: 14 additions & 0 deletions docs/reference/storage-paths.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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` |
Expand Down Expand Up @@ -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:

Expand Down Expand Up @@ -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
Expand All @@ -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
```
Expand Down
46 changes: 38 additions & 8 deletions docs/troubleshooting.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 recoverable named backups are present, you will be prompted to restore before OAuth. This prompt only appears in interactive terminals and is skipped after same-session fresh/reset flows.

---

## Verify Install And Routing
Expand Down Expand Up @@ -89,24 +91,52 @@ codex auth doctor --json

---

## Soft Reset
## Reset Options

- Delete a single saved account: `codex auth login` → pick account → **Delete Account**
- Delete saved accounts: `codex auth login` → Danger Zone → **Delete Saved Accounts**
- Reset local state: `codex auth login` → Danger Zone → **Reset Local State**

Exact effects:

| Action | Saved accounts | Flagged/problem accounts | Settings | Codex CLI sync state | Quota cache |
| --- | --- | --- | --- | --- | --- |
| Delete Account | Delete the selected saved account | Delete the matching flagged/problem entry for that refresh token | Keep | Keep | Keep |
| Delete Saved Accounts | Delete all saved accounts | Keep | Keep | Keep | Keep |
| Reset Local State | Delete all saved accounts | Delete all flagged/problem accounts | Keep | Keep | Clear |

To perform the same actions manually:

PowerShell:
Delete saved accounts only:

```powershell
Remove-Item "$HOME\.codex\multi-auth\openai-codex-accounts.json" -Force -ErrorAction SilentlyContinue
Remove-Item "$HOME\.codex\multi-auth\openai-codex-flagged-accounts.json" -Force -ErrorAction SilentlyContinue
Remove-Item "$HOME\.codex\multi-auth\settings.json" -Force -ErrorAction SilentlyContinue
codex auth login
Remove-Item "$HOME\.codex\multi-auth\openai-codex-accounts.json.wal" -Force -ErrorAction SilentlyContinue
Remove-Item "$HOME\.codex\multi-auth\openai-codex-accounts.json.bak*" -Force -ErrorAction SilentlyContinue
```

Bash:
```bash
rm -f ~/.codex/multi-auth/openai-codex-accounts.json
rm -f ~/.codex/multi-auth/openai-codex-accounts.json.wal
rm -f ~/.codex/multi-auth/openai-codex-accounts.json.bak*
```

Reset local state (also clears flagged/problem accounts and quota cache; preserves settings and Codex CLI sync state):

```powershell
Remove-Item "$HOME\.codex\multi-auth\openai-codex-accounts.json" -Force -ErrorAction SilentlyContinue
Remove-Item "$HOME\.codex\multi-auth\openai-codex-accounts.json.wal" -Force -ErrorAction SilentlyContinue
Remove-Item "$HOME\.codex\multi-auth\openai-codex-accounts.json.bak*" -Force -ErrorAction SilentlyContinue
Remove-Item "$HOME\.codex\multi-auth\openai-codex-flagged-accounts.json" -Force -ErrorAction SilentlyContinue
Remove-Item "$HOME\.codex\multi-auth\quota-cache.json" -Force -ErrorAction SilentlyContinue
```

```bash
rm -f ~/.codex/multi-auth/openai-codex-accounts.json
rm -f ~/.codex/multi-auth/openai-codex-accounts.json.wal
rm -f ~/.codex/multi-auth/openai-codex-accounts.json.bak*
rm -f ~/.codex/multi-auth/openai-codex-flagged-accounts.json
rm -f ~/.codex/multi-auth/settings.json
codex auth login
rm -f ~/.codex/multi-auth/quota-cache.json
```

---
Expand Down
14 changes: 14 additions & 0 deletions docs/upgrade.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,20 @@ 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.

### Sync Center

The settings hub now includes a preview-first Sync Center for Codex CLI reconciliation.

- preview shows source and target paths, last session sync status, and whether destination-only accounts are preserved
- apply is blocked until the preview status is ready
- rollback context surfaces backup paths such as `.bak`, `.bak.1`, `.bak.2`, and `.wal`

---

## Legacy Compatibility
Expand Down
Loading