diff --git a/.env.example b/.env.example
new file mode 100644
index 00000000..2d6a9a59
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,19 @@
+# Optional overrides
+
+# Path to an explicit plugin config file (absolute preferred; relative is resolved from cwd).
+CODEX_MULTI_AUTH_CONFIG_PATH=
+
+# Directory used for multi-auth state (absolute preferred; relative is resolved from cwd).
+CODEX_MULTI_AUTH_DIR=
+
+# Enable console mirror logging (`1` to enable).
+CODEX_CONSOLE_LOG=
+
+# Override Codex home root used by Codex CLI integrations.
+CODEX_HOME=
+
+# Logging flags for plugin diagnostics.
+CODEX_PLUGIN_LOG_BODIES=
+CODEX_PLUGIN_LOG_LEVEL=
+DEBUG_CODEX_PLUGIN=
+ENABLE_PLUGIN_REQUEST_LOGGING=
diff --git a/.gitignore b/.gitignore
index aa48be20..018396a6 100644
--- a/.gitignore
+++ b/.gitignore
@@ -26,3 +26,7 @@ winston/
 task_plan.md
 findings.md
 progress.md
+
+# local env files
+.env
+.env.local
diff --git a/README.md b/README.md
index 07e36506..aa304835 100644
--- a/README.md
+++ b/README.md
@@ -3,326 +3,159 @@
 [![npm version](https://img.shields.io/npm/v/codex-multi-auth.svg)](https://www.npmjs.com/package/codex-multi-auth)
 [![npm downloads](https://img.shields.io/npm/dw/codex-multi-auth.svg)](https://www.npmjs.com/package/codex-multi-auth)
 
-OpenCode plugin that routes OpenAI SDK traffic through the ChatGPT Codex backend using OAuth, with multi-account rotation and Codex CLI state sync.
+Codex CLI-first multi-account OAuth manager for the official Codex CLI.
 
-> [!NOTE]
-> Renamed from `opencode-openai-codex-auth-multi`.
-> If you used the old package name, switch to `codex-multi-auth`.
+* * *
 
 ## Quick Start
 
-### 1. Install
+Install from source (current project workflow):
 
 ```bash
-npx -y codex-multi-auth@latest
-```
-
-### 2. Authenticate
-
-```bash
-opencode auth login
+npm install -g @openai/codex
+git clone https://github.com/ndycode/codex-multi-auth.git
+cd codex-multi-auth
+npm install
+npm run build
+npm link
 ```
 
-Run `opencode auth login` again to add more accounts (up to 20).
-
-### 3. Use a model
+Add and verify accounts:
 
 ```bash
-opencode run "Hello" --model=openai/gpt-5.2 --variant=medium
+codex auth login
+codex auth list
+codex auth check
 ```
 
-### 4. Verify tools
-
-```text
-codex-list
-codex-status
-```
-
-## Why this plugin
-
-- Use ChatGPT Plus/Pro OAuth instead of API-key billing for OpenCode usage.
-- Multi-account failover with health-aware rotation.
-- Codex CLI source-of-truth sync (`~/.codex/accounts.json`) by default.
-- Built-in account management tools (`codex-*`).
-- Strict request shaping for compatibility with the ChatGPT Codex backend.
-
-## Usage Notice
-
-> [!CAUTION]
-> Personal development tool.
->
-> Not for:
-> - commercial API resale
-> - multi-tenant production services
->
-> You are responsible for compliance with OpenAI Terms of Use.
->
-> Official production path: [OpenAI Platform API](https://platform.openai.com/)
+If browser opens during `codex auth login`, that is expected. Complete OAuth and return to the same terminal.
 
-## Navigation
+* * *
 
-- [Installation Options](#installation-options)
-- [Model Setup](#model-setup)
-- [Account Rotation](#account-rotation)
-- [Tool Reference](#tool-reference)
-- [Configuration](#configuration)
-- [Troubleshooting](#troubleshooting)
-- [Repository and Docs Map](#repository-and-docs-map)
-- [Development](#development)
-- [Compatibility](#compatibility)
+## What You Get
 
-## Installation Options
+- `codex auth ...` commands for multi-account management.
+- Interactive beginner-friendly dashboard with hotkeys.
+- Health checks, forecasting, safe auto-fix, and diagnostics.
+- Live account sync and Codex CLI active-account state sync.
 
-### Option A: one-command installer (recommended)
+* * *
 
-```bash
-npx -y codex-multi-auth@latest
-```
-
-This installer:
-- updates `~/.config/opencode/opencode.json`
-- backs up existing config
-- clears plugin cache
+## Most-Used Commands
 
-Use `--legacy` for older OpenCode versions (`<= v1.0.209`).
+| Command | Use it for |
+| --- | --- |
+| `codex auth login` | Add/manage accounts in the dashboard |
+| `codex auth list` | See saved accounts and current account |
+| `codex auth switch <index>` | Switch current account |
+| `codex auth check` | Quick health + live session checks |
+| `codex auth forecast --live` | Choose the best next account |
+| `codex auth fix --dry-run` | Preview safe fixes |
+| `codex auth fix` | Apply safe fixes |
+| `codex auth doctor --fix` | Diagnose and auto-repair common issues |
+| `codex auth report --live --json` | Full machine-readable report |
+| `codex auth features` | Print all implemented feature areas |
 
-### Option B: manual setup
+Complete command reference: [docs/reference/commands.md](docs/reference/commands.md)
 
-Add plugin in `~/.config/opencode/opencode.json`:
+* * *
 
-```json
-{
-  "plugin": ["codex-multi-auth@latest"]
-}
-```
-
-Then authenticate:
+## Dashboard Hotkeys
 
-```bash
-opencode auth login
-```
+Main dashboard:
 
-### Option C: copy-paste prompt for another agent
+- `Up` / `Down`: move
+- `Enter`: select
+- `1-9`: quick switch account
+- `/`: search
+- `?` or `H`: help
+- `Q`: back
 
-```text
-Install the codex-multi-auth plugin and configure OpenCode using:
-https://raw.githubusercontent.com/ndycode/codex-multi-auth/main/README.md
-```
+Account detail menu:
 
-## Model Setup
+- `S`: set current
+- `R`: refresh login
+- `E`: enable/disable
+- `D`: delete account
 
-### Supported model families
+* * *
 
-| Model | Variants | Notes |
-|---|---|---|
-| `gpt-5.2` | none, low, medium, high, xhigh | Main general model |
-| `gpt-5-codex` | low, medium, high | Main coding model |
-| `gpt-5.1-codex-max` | low, medium, high, xhigh | Max-context coding |
-| `gpt-5.1-codex` | low, medium, high | Standard coding |
-| `gpt-5.1-codex-mini` | medium, high | Smaller coding model |
-| `gpt-5.1` | none, low, medium, high | General model |
-| `gpt-5.3-codex-spark` | low, medium, high, xhigh | Optional, entitlement-gated |
+## Settings and Advanced Backend
 
-### Variant usage
+Open:
 
 ```bash
-# modern OpenCode (v1.0.210+)
-opencode run "Hello" --model=openai/gpt-5.2 --variant=high
-
-# legacy OpenCode (v1.0.209 and below)
-opencode run "Hello" --model=openai/gpt-5.2-high
+codex auth login
+# Settings
 ```
 
-### Config templates
+Settings are persisted in:
 
-Use these ready files:
+- `~/.codex/multi-auth/settings.json`
+- or `CODEX_MULTI_AUTH_DIR/settings.json` when custom root is set
 
-- `config/opencode-modern.json` (modern variant format)
-- `config/opencode-legacy.json` (legacy model-name format)
-- `config/minimal-opencode.json` (minimal baseline)
+Reference:
 
-Details: [config/README.md](config/README.md)
+- [docs/reference/settings.md](docs/reference/settings.md)
 
-## Account Rotation
+* * *
 
-- Rotation is health-aware and quota-aware.
-- Token bucket prevents repeatedly hitting exhausted accounts.
-- All-accounts-limited flow can wait/retry with countdown.
-- Failed auth can degrade/remove unhealthy accounts.
-- Active account writes back to Codex CLI on:
-  - explicit selection (`codex-switch`)
-  - successful routed requests
+## Documentation Map
 
-Canonical state paths:
+Start here:
 
-- Codex CLI source of truth: `~/.codex/accounts.json`
-- Plugin runtime metadata mirror: `~/.opencode/openai-codex-accounts.json`
-- Plugin config: `~/.opencode/codex-multi-auth-config.json`
+- Docs portal: [docs/README.md](docs/README.md)
+- Beginner setup: [docs/getting-started.md](docs/getting-started.md)
+- Full feature matrix: [docs/features.md](docs/features.md)
+- Configuration: [docs/configuration.md](docs/configuration.md)
+- Troubleshooting: [docs/troubleshooting.md](docs/troubleshooting.md)
+- Storage/path reference: [docs/reference/storage-paths.md](docs/reference/storage-paths.md)
+- Upgrade guide: [docs/upgrade.md](docs/upgrade.md)
+- Privacy/data handling: [docs/privacy.md](docs/privacy.md)
 
-## Tool Reference
+Maintainer docs:
 
-### Default tools
+- Architecture: [docs/development/ARCHITECTURE.md](docs/development/ARCHITECTURE.md)
+- Config fields: [docs/development/CONFIG_FIELDS.md](docs/development/CONFIG_FIELDS.md)
+- Config flow: [docs/development/CONFIG_FLOW.md](docs/development/CONFIG_FLOW.md)
+- Testing: [docs/development/TESTING.md](docs/development/TESTING.md)
+- TUI parity checklist: [docs/development/TUI_PARITY_CHECKLIST.md](docs/development/TUI_PARITY_CHECKLIST.md)
 
-| Tool | Purpose | Example |
-|---|---|---|
-| `codex-list` | list configured accounts | `codex-list` |
-| `codex-switch` | switch active account | `codex-switch index=2` |
-| `codex-status` | show health/limits/reset timing | `codex-status` |
-| `codex-health` | validate token health (read-only) | `codex-health` |
-| `hashline_read` | read hashline refs for deterministic edits | `hashline_read path="src/file.ts"` |
-| `edit` | hashline-capable edit tool (also supports legacy `oldString/newString`) | `edit path="src/file.ts" lineRef="L42#..." operation="replace" content="..."` |
+* * *
 
-### Advanced tools (opt-in)
-
-Enable advanced tools:
+## Quick Troubleshooting
 
 ```bash
-CODEX_MULTI_AUTH_EXPOSE_ADMIN_TOOLS=1 opencode
-```
-
-| Tool | Purpose | Example |
-|---|---|---|
-| `codex-metrics` | show process runtime metrics | `codex-metrics` |
-| `codex-refresh` | refresh and persist account tokens | `codex-refresh` |
-| `codex-remove` | remove account by index | `codex-remove index=3` |
-| `codex-export` | export accounts to JSON | `codex-export path="~/backup/accounts.json"` |
-| `codex-import` | import/merge accounts from JSON | `codex-import path="~/backup/accounts.json"` |
-
-### Hashline flow (plain OpenCode)
-
-```text
-hashline_read path="src/file.ts"
-edit path="src/file.ts" lineRef="L42#deadbeef" operation="replace" content="new code"
-edit path="src/file.ts" lineRef="L42#deadbeef" endLineRef="L44#feedcafe" operation="replace" content="replacement block"
-# legacy fallback remains supported:
-edit path="src/file.ts" oldString="from" newString="to"
+codex auth doctor --fix
+codex auth list
+codex auth forecast --live
 ```
 
-## Configuration
-
-Create optional file:
-
-`~/.opencode/codex-multi-auth-config.json`
-
-### Important options
-
-| Option | Default | Effect |
-|---|---|---|
-| `codexMode` | `true` | use Codex bridge prompt |
-| `codexTuiV2` | `true` | codex-style terminal UI |
-| `fastSession` | `false` | lower-latency tuning |
-| `fastSessionStrategy` | `hybrid` | `hybrid` or `always` |
-| `retryAllAccountsRateLimited` | `true` | wait/retry when all accounts are limited |
-| `unsupportedCodexPolicy` | `strict` | strict or fallback for unsupported model responses |
-| `unsupportedCodexFallbackChain` | `{}` | model-specific fallback sequence override |
-| `fetchTimeoutMs` | `60000` | upstream request timeout |
-| `streamStallTimeoutMs` | `45000` | stall timeout for non-stream parsing |
-
-### Common environment variables
+If command routing is broken:
 
 ```bash
-DEBUG_CODEX_PLUGIN=1 opencode
-ENABLE_PLUGIN_REQUEST_LOGGING=1 opencode
-CODEX_PLUGIN_LOG_BODIES=1 opencode
-CODEX_PLUGIN_LOG_LEVEL=debug opencode
-
-CODEX_MODE=0 opencode
-CODEX_TUI_V2=0 opencode
-CODEX_TUI_COLOR_PROFILE=ansi16 opencode
-CODEX_TUI_GLYPHS=unicode opencode
-
-CODEX_AUTH_FAST_SESSION=1 opencode
-CODEX_AUTH_FAST_SESSION_STRATEGY=always opencode
-CODEX_AUTH_FAST_SESSION_MAX_INPUT_ITEMS=24 opencode
-
-CODEX_AUTH_UNSUPPORTED_MODEL_POLICY=fallback opencode
-CODEX_MULTI_AUTH_SYNC_CODEX_CLI=0 opencode
-CODEX_MULTI_AUTH_EXPOSE_ADMIN_TOOLS=1 opencode
-CODEX_AUTH_FETCH_TIMEOUT_MS=120000 opencode
-CODEX_AUTH_STREAM_STALL_TIMEOUT_MS=60000 opencode
+where codex
+codex --version
+codex auth status
+codex multi auth status
 ```
 
-Full config details: [docs/configuration.md](docs/configuration.md)
-
-## Troubleshooting
-
-Quick reset path:
-
-1. delete `~/.opencode/auth/openai.json`
-2. run `opencode auth login`
-3. run `codex-status`
-
-### Key file paths (all platforms)
-
-| File | Path |
-|---|---|
-| OpenCode config | `~/.config/opencode/opencode.json` |
-| Auth tokens | `~/.opencode/auth/openai.json` |
-| Codex CLI accounts | `~/.codex/accounts.json` |
-| Plugin account mirror | `~/.opencode/openai-codex-accounts.json` |
-| Plugin config | `~/.opencode/codex-multi-auth-config.json` |
-| Plugin logs | `~/.opencode/logs/codex-plugin/` |
-
-More diagnostics: [docs/troubleshooting.md](docs/troubleshooting.md)
-
-## Repository and Docs Map
-
-### Repository ownership
-
-| Path | Responsibility |
-|---|---|
-| `index.ts` | plugin entrypoint and routing |
-| `lib/auth/` | OAuth + token lifecycle |
-| `lib/request/` | request transform + fetch + SSE handling |
-| `lib/prompts/` | prompt bridge and prompt sync logic |
-| `lib/storage/` | paths and migrations |
-| `lib/codex-cli/` | Codex CLI state sync |
-| `test/` | unit/integration/property tests |
-| `scripts/` | build/install helpers |
-| `config/` | user config templates |
-| `docs/` | user + developer docs |
-| `dist/` | generated output |
-
-### AGENTS hierarchy
-
-- `AGENTS.md` applies repo-wide.
-- `lib/AGENTS.md` applies to `lib/**`.
-- `test/AGENTS.md` applies to `test/**`.
-
-### Docs entry points
-
-- [docs/README.md](docs/README.md)
-- [docs/development/REPOSITORY_SCOPE.md](docs/development/REPOSITORY_SCOPE.md)
-- [docs/development/ARCHITECTURE.md](docs/development/ARCHITECTURE.md)
-- [docs/development/TESTING.md](docs/development/TESTING.md)
-- [docs/DOCUMENTATION.md](docs/DOCUMENTATION.md)
+* * *
 
 ## Development
 
 ```bash
-npm run build
 npm run typecheck
 npm run lint
 npm test
+npm run build
 ```
 
-## Compatibility
+* * *
 
-- Works with `oh-my-opencode`.
-- With `@tarquinen/opencode-dcp`, list `codex-multi-auth` first in plugin order.
-- You do not need `openai-codex-auth` alongside this plugin.
+## Security and Usage Notice
 
-## Security and Legal
+This project is for personal development workflows. You are responsible for compliance with OpenAI policies.
 
 - Security policy: [SECURITY.md](SECURITY.md)
-- This project is independent and not affiliated with OpenAI.
-- "ChatGPT", "GPT-5", "Codex", and "OpenAI" are trademarks of OpenAI, L.L.C.
-
-## Credits
-
-- [numman-ali/opencode-openai-codex-auth](https://github.com/numman-ali/opencode-openai-codex-auth) by [numman-ali](https://github.com/numman-ali)
-- [ndycode](https://github.com/ndycode)
-
-## License
-
-MIT. See [LICENSE](LICENSE).
\ No newline at end of file
+- License: [LICENSE](LICENSE)
diff --git a/SECURITY.md b/SECURITY.md
index 01bc995d..be648f22 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -16,17 +16,17 @@ We provide security updates for the latest version of the plugin.
 This plugin handles sensitive OAuth tokens. To protect your security:
 
 ✅ **What we do:**
-- Store tokens securely via opencode's credential management
+- Store tokens in local account storage files with restricted file permissions
 - Use PKCE-secured OAuth 2.0 flows
 - Never transmit tokens to third parties
 - Implement automatic token refresh
 - Use industry-standard authentication practices
 
 ⚠️ **What you should do:**
-- Never share your `~/.opencode/` directory
+- Never share your `~/.codex/` directory
 - Do not commit OAuth tokens to version control
 - Regularly review authorized apps at [ChatGPT Settings](https://chatgpt.com/settings/apps)
-- Use `opencode auth logout` when done on shared systems
+- Remove local plugin auth files when done on shared systems (default: `~/.codex/multi-auth/openai-codex-*.json`; use `CODEX_MULTI_AUTH_DIR` if overridden)
 - Enable debug logging (`ENABLE_PLUGIN_REQUEST_LOGGING=1`) only when troubleshooting
 
 ### Reporting a Vulnerability
@@ -72,9 +72,10 @@ The following are **not** security vulnerabilities:
 ### Third-Party Dependencies
 
 This plugin minimizes dependencies for security:
-- **Only dependency:** `@openauthjs/openauth` (for OAuth handling)
+- Runtime dependencies include: `@openauthjs/openauth`, `@opencode-ai/plugin`, `hono`, and `zod`
 - Regular dependency updates for security patches
 - No telemetry or analytics dependencies
+- CI/local guardrail: run `npm run audit:ci` before release or after dependency updates
 
 ## Questions?
 
diff --git a/docs/DOCUMENTATION.md b/docs/DOCUMENTATION.md
index 5aa5c919..f4a6a3b8 100644
--- a/docs/DOCUMENTATION.md
+++ b/docs/DOCUMENTATION.md
@@ -1,47 +1,105 @@
-# Documentation Structure
-
-This file describes how docs are organized in this repository.
-
-## Repository-level docs
-
-- `README.md` - Main entry point for users
-- `CHANGELOG.md` - Release history
-- `CONTRIBUTING.md` - Contribution workflow
-- `SECURITY.md` - Security reporting policy
-- `AGENTS.md` - AI agent instructions for this codebase
-
-## docs/ (site + user/developer guides)
-
-```text
-docs/
-  index.md                     # documentation landing page
-  README.md                    # docs portal / navigation
-  getting-started.md           # install + first-run guide
-  configuration.md             # full config reference
-  troubleshooting.md           # operational debugging guide
-  privacy.md                   # data handling notes
-  development/
-    REPOSITORY_SCOPE.md        # canonical path ownership + extension points
-    ARCHITECTURE.md            # technical design
-    CONFIG_FLOW.md             # config resolution internals
-    CONFIG_FIELDS.md           # config field semantics
-    TESTING.md                 # testing strategy and commands
-    TUI_PARITY_CHECKLIST.md    # auth dashboard UI parity checks
-```
-
-## config/ (copy-paste templates)
-
-- `config/opencode-modern.json` - OpenCode v1.0.210+ variant-based template
-- `config/opencode-legacy.json` - OpenCode v1.0.209 and below template
-- `config/minimal-opencode.json` - minimal debug template
-- `config/README.md` - template-selection guide
-
-## Notes
-
-- AGENTS hierarchy for source edits:
-  - `AGENTS.md` applies repository-wide.
-  - `lib/AGENTS.md` applies to `lib/**`.
-  - `test/AGENTS.md` applies to `test/**`.
-- `dist/` is build output and not a documentation source of truth.
-- `tmp*` files are release scratch artifacts and not part of user docs.
-- For user-facing guidance, start with `README.md` or `docs/getting-started.md`.
+# Documentation Architecture
+
+This file defines the canonical documentation system for `codex-multi-auth`.
+
+* * *
+
+## Documentation Layers
+
+| Layer | Audience | Goal |
+| --- | --- | --- |
+| Product entry | New users | Install quickly and run first successful login/check |
+| User operations | Users/operators | Configure, operate, troubleshoot safely |
+| Reference | Power users/maintainers | Exact command/setting/path lookup |
+| Development | Maintainers/contributors | Internal architecture, flow, tests, ownership |
+
+* * *
+
+## Master Chart
+
+| Scope | File |
+| --- | --- |
+| Project entry | `README.md` |
+| Docs portal | `docs/README.md` |
+| Docs landing | `docs/index.md` |
+| Beginner setup | `docs/getting-started.md` |
+| Feature matrix | `docs/features.md` |
+| Configuration guide | `docs/configuration.md` |
+| Troubleshooting guide | `docs/troubleshooting.md` |
+| Privacy/data handling | `docs/privacy.md` |
+| Upgrade/migration | `docs/upgrade.md` |
+| Command reference | `docs/reference/commands.md` |
+| Settings reference | `docs/reference/settings.md` |
+| Storage path reference | `docs/reference/storage-paths.md` |
+| Documentation style rules | `docs/STYLE_GUIDE.md` |
+| Docs governance (this file) | `docs/DOCUMENTATION.md` |
+| Architecture internals | `docs/development/ARCHITECTURE.md` |
+| Config fields internals | `docs/development/CONFIG_FIELDS.md` |
+| Config flow internals | `docs/development/CONFIG_FLOW.md` |
+| Repository ownership map | `docs/development/REPOSITORY_SCOPE.md` |
+| Testing guide | `docs/development/TESTING.md` |
+| TUI parity checklist | `docs/development/TUI_PARITY_CHECKLIST.md` |
+| Benchmarks | `docs/benchmarks/code-edit-format-benchmark.md` |
+
+* * *
+
+## Tone and Formatting Contract
+
+All user-facing docs must follow `docs/STYLE_GUIDE.md`:
+
+1. Beginner-first language.
+2. Short lead sentence.
+3. Quick path before deep details.
+4. Command-first examples.
+5. Clear next steps/related links.
+
+Codex CLI-first style is the baseline:
+
+- concise sections
+- operational clarity
+- progressive disclosure
+
+* * *
+
+## Canonical Command and Path Policy
+
+1. Canonical account workflow command family: `codex auth ...`.
+2. Canonical runtime storage root: `~/.codex/multi-auth`.
+3. Legacy paths/flows are documented only in migration/compat sections.
+4. Do not present legacy flows as the default workflow.
+
+* * *
+
+## Update Rules
+
+When runtime behavior changes:
+
+1. Update `README.md` and `docs/getting-started.md` first.
+2. Update `docs/features.md` for feature coverage changes.
+3. Update command/settings/path references if any CLI/config/storage behavior changed.
+4. Update `docs/troubleshooting.md` with new failure signatures.
+5. Update development docs when architecture/config flow changed.
+6. Update `docs/upgrade.md` when migration steps, command routing, or paths changed.
+7. Keep `SECURITY.md` aligned with current storage paths and credential handling.
+8. Update npm script references whenever build/install workflow changes.
+
+* * *
+
+## Documentation QA Checklist
+
+Before merge:
+
+1. Every documented command executes as written.
+2. Paths match runtime code (`lib/runtime-paths.ts`, `lib/storage.ts`, `lib/config.ts`).
+3. Feature matrix covers all implemented features.
+4. Internal links are valid.
+5. Cross-platform examples are present for OS-sensitive flows.
+6. No conflicting duplicate guidance across pages.
+
+* * *
+
+## Related
+
+- [Project README.md](../README.md)
+- [Docs README.md](README.md)
+- [STYLE_GUIDE.md](STYLE_GUIDE.md)
diff --git a/docs/OPENCODE_PR_PROPOSAL.md b/docs/OPENCODE_PR_PROPOSAL.md
deleted file mode 100644
index a49fcfe7..00000000
--- a/docs/OPENCODE_PR_PROPOSAL.md
+++ /dev/null
@@ -1,96 +0,0 @@
-# OpenCode PR: Merge Auth Methods from Multiple Plugins
-
-## Problem
-
-When multiple plugins register for the same provider (e.g., `openai`), only the first plugin's auth methods are shown. This is because `auth.ts:310` uses `.find()` which returns the first match:
-
-```typescript
-const plugin = await Plugin.list().then((x) => x.find((x) => x.auth?.provider === provider))
-```
-
-Since internal plugins (like `CodexAuthPlugin`) load before external plugins, external plugins can never add auth methods to providers that have internal plugins.
-
-## Use Case
-
-Multi-account authentication plugins need to add their auth methods alongside built-in options. For example:
-- Built-in: "ChatGPT Pro/Plus" 
-- External: "ChatGPT Pro/Plus (Multi-Account)"
-
-Users should see both options when selecting OpenAI provider.
-
-## Proposed Solution
-
-Change `auth.ts` to collect and merge auth methods from ALL plugins that register for the same provider:
-
-### Current Code (auth.ts lines 310-314)
-
-```typescript
-const plugin = await Plugin.list().then((x) => x.find((x) => x.auth?.provider === provider))
-if (plugin && plugin.auth) {
-  const handled = await handlePluginAuth({ auth: plugin.auth }, provider)
-  if (handled) return
-}
-```
-
-### Proposed Code
-
-```typescript
-// Collect auth methods from ALL plugins that register for this provider
-const matchingPlugins = await Plugin.list().then((x) => 
-  x.filter((x) => x.auth?.provider === provider)
-)
-
-if (matchingPlugins.length > 0) {
-  // Merge methods from all matching plugins
-  const mergedMethods = matchingPlugins.flatMap((p) => p.auth?.methods ?? [])
-  
-  // Use the first plugin's loader (internal plugins take precedence)
-  const primaryPlugin = matchingPlugins[0]
-  
-  const handled = await handlePluginAuth(
-    { 
-      auth: {
-        ...primaryPlugin.auth!,
-        methods: mergedMethods,
-      }
-    }, 
-    provider
-  )
-  if (handled) return
-}
-```
-
-### Also update lines 326-330 (custom provider handling)
-
-```typescript
-// Same pattern for custom providers
-const customPlugins = await Plugin.list().then((x) => 
-  x.filter((x) => x.auth?.provider === provider)
-)
-if (customPlugins.length > 0) {
-  const mergedMethods = customPlugins.flatMap((p) => p.auth?.methods ?? [])
-  const primaryPlugin = customPlugins[0]
-  const handled = await handlePluginAuth(
-    { auth: { ...primaryPlugin.auth!, methods: mergedMethods } }, 
-    provider
-  )
-  if (handled) return
-}
-```
-
-## Benefits
-
-1. **Backward Compatible**: Existing behavior unchanged for providers with single plugin
-2. **Extensible**: External plugins can add auth methods to any provider
-3. **Priority Preserved**: Internal plugins' loaders still take precedence
-4. **Minimal Change**: ~10 lines changed, no new dependencies
-
-## Testing
-
-1. Install an external plugin that registers for `openai` provider
-2. Run `opencode auth login` → select "OpenAI"
-3. Verify both internal and external auth methods appear in the list
-
-## Alternative Considered
-
-Have external plugins use different provider IDs (e.g., `openai-multi`), but this requires users to manually type the provider ID via "Other", which is poor UX.
diff --git a/docs/README.md b/docs/README.md
index 7b1923f8..1bc6a503 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,43 +1,59 @@
-# Documentation
+# Documentation Portal
 
-Welcome to the OpenCode OpenAI Codex Auth Plugin documentation!
+Use this portal to navigate user docs, references, and maintainer docs.
 
-## For Users
+* * *
 
-- **[Getting Started](getting-started.md)** - Installation, configuration, and quick start
-- **[Configuration Guide](configuration.md)** - Complete config reference
-- **[Troubleshooting](troubleshooting.md)** - Common issues and debugging
-- **[Changelog](../CHANGELOG.md)** - Version history and release notes
+## Start Here
 
-## For Developers
+1. [Getting Started](getting-started.md)
+2. [Features](features.md)
+3. [Configuration](configuration.md)
+4. [Troubleshooting](troubleshooting.md)
 
-Explore the engineering depth behind this plugin:
+* * *
 
-- **[Repository Scope Map](development/REPOSITORY_SCOPE.md)** - Canonical path ownership and extension points
-- **[Architecture](development/ARCHITECTURE.md)** - Technical design, request pipeline, AI SDK compatibility
-- **[Configuration System](development/CONFIG_FLOW.md)** - How config loading and merging works
-- **[Config Fields Guide](development/CONFIG_FIELDS.md)** - Understanding config keys, `id`, and `name`
-- **[Testing Guide](development/TESTING.md)** - Test scenarios, verification procedures, integration testing
-- **[TUI Parity Checklist](development/TUI_PARITY_CHECKLIST.md)** - Auth dashboard/UI parity requirements for future changes
+## User Guides
 
-## Documentation Meta
+| Page | What it answers |
+| --- | --- |
+| [index.md](index.md) | Fast docs landing page |
+| [getting-started.md](getting-started.md) | How to install, login, add accounts, and run first checks |
+| [features.md](features.md) | What all implemented features do |
+| [configuration.md](configuration.md) | How to configure behavior and reliability settings |
+| [troubleshooting.md](troubleshooting.md) | What to do when login/switch/limits fail |
+| [privacy.md](privacy.md) | Where data is stored and what is sent over network |
+| [upgrade.md](upgrade.md) | How to migrate from older flows and legacy paths |
 
-- **[Documentation Structure](DOCUMENTATION.md)** - How docs are organized in this repository
+* * *
 
-## Key Architectural Decisions
+## Reference
 
-This plugin bridges two different systems with careful engineering:
+| Page | What it answers |
+| --- | --- |
+| [reference/commands.md](reference/commands.md) | Full command and hotkey reference |
+| [reference/settings.md](reference/settings.md) | Dashboard/backend settings reference |
+| [reference/storage-paths.md](reference/storage-paths.md) | Current and legacy file path matrix |
+| [STYLE_GUIDE.md](STYLE_GUIDE.md) | Documentation tone and formatting rules |
 
-1. **AI SDK Compatibility** - Filters `item_reference` (AI SDK construct) for Codex API compatibility
-2. **Stateless Operation** - ChatGPT backend requires `store: false`, verified via testing
-3. **Full Context Preservation** - Sends complete message history (IDs stripped) for LLM context (with optional fast-session trimming)
-4. **Stale-While-Revalidate Caching** - Keeps prompt/instruction fetches fast while avoiding GitHub rate limits; optional startup prewarm for first-turn latency
-5. **Per-Model Configuration** - Enables quality presets with quick switching
-6. **Fast Session Mode** - Optional low-latency tuning (clamps reasoning/verbosity on trivial turns) without changing defaults
-7. **Entitlement-Aware Fallback Flow** - Unsupported models try remaining accounts/workspaces first, then optional fallback chain if enabled
+* * *
 
-**Testing**: large Vitest suite with enforced 80% coverage threshold plus integration coverage
+## Maintainer Docs
 
----
+| Page | What it answers |
+| --- | --- |
+| [DOCUMENTATION.md](DOCUMENTATION.md) | How docs are structured and maintained |
+| [development/ARCHITECTURE.md](development/ARCHITECTURE.md) | Runtime architecture and request/account flow |
+| [development/CONFIG_FIELDS.md](development/CONFIG_FIELDS.md) | Full config field inventory |
+| [development/CONFIG_FLOW.md](development/CONFIG_FLOW.md) | Resolution and precedence flow |
+| [development/REPOSITORY_SCOPE.md](development/REPOSITORY_SCOPE.md) | Ownership map for repo paths |
+| [development/TESTING.md](development/TESTING.md) | Test matrix and release gate |
+| [development/TUI_PARITY_CHECKLIST.md](development/TUI_PARITY_CHECKLIST.md) | TUI quality checklist |
+| [benchmarks/code-edit-format-benchmark.md](benchmarks/code-edit-format-benchmark.md) | Benchmark guide |
 
-**Quick Links**: [GitHub](https://github.com/ndycode/codex-multi-auth) | [npm](https://www.npmjs.com/package/codex-multi-auth) | [Issues](https://github.com/ndycode/codex-multi-auth/issues)
+* * *
+
+## Related
+
+- Project README: [../README.md](../README.md)
+- Security policy: [../SECURITY.md](../SECURITY.md)
diff --git a/docs/STYLE_GUIDE.md b/docs/STYLE_GUIDE.md
new file mode 100644
index 00000000..c2856ea9
--- /dev/null
+++ b/docs/STYLE_GUIDE.md
@@ -0,0 +1,93 @@
+# Documentation Style Guide
+
+Use this style guide for every docs page in this repository.
+
+* * *
+
+## Goals
+
+1. Beginner-first clarity.
+2. Fast path first, deep details second.
+3. Consistent wording and section structure.
+4. Codex CLI-first tone: concise, practical, command-driven.
+
+* * *
+
+## Page Template
+
+User-facing pages should follow this order:
+
+1. Title.
+2. One-line lead.
+3. Quick path section.
+4. Common tasks section.
+5. Deeper details/reference section.
+6. Troubleshooting/gotchas section (if relevant).
+7. Related links.
+
+Use `* * *` separators between major blocks for scanability.
+
+* * *
+
+## Writing Rules
+
+1. Prefer short sentences and direct verbs.
+2. Prefer action phrasing:
+   - "Run ..."
+   - "Check ..."
+   - "If this fails, do ..."
+3. Avoid long abstract paragraphs before commands.
+4. Explain expected result after critical commands.
+5. Define acronyms/jargon once in plain language.
+
+* * *
+
+## Command Example Rules
+
+1. Use runnable commands.
+2. Include platform-specific blocks for OS-sensitive operations.
+3. Use canonical command family: `codex auth ...`.
+4. Keep command blocks small and task-specific.
+
+* * *
+
+## Path and Terminology Rules
+
+1. Canonical runtime root is `~/.codex/multi-auth`.
+2. Legacy paths belong in migration/compat sections only.
+3. Keep command/path naming consistent across all docs.
+4. Do not mix old/new command families in beginner quick paths.
+
+* * *
+
+## Tables and Lists
+
+1. Use compact tables for key-value or comparison data.
+2. Keep table columns minimal and meaningful.
+3. Use flat bullet lists (no nested bullets in docs where possible).
+4. Keep long references in dedicated `docs/reference/*` pages.
+
+* * *
+
+## Maintainer Rules
+
+1. Any runtime change that affects users must update:
+   - `README.md`
+   - `docs/getting-started.md`
+   - `docs/features.md`
+   - relevant reference pages
+2. Any new setting/flag/path must be reflected in reference docs.
+3. Keep `docs/upgrade.md` updated for command/path migration changes.
+4. Keep `SECURITY.md` path guidance aligned with runtime paths.
+5. Validate commands before merging documentation changes.
+
+* * *
+
+## Anti-Patterns
+
+Avoid:
+
+- command examples that are not executable
+- conflicting path guidance across pages
+- legacy-first wording in primary guides
+- giant walls of text before actionable steps
diff --git a/docs/_config.yml b/docs/_config.yml
index 2ae29a25..85582ce9 100644
--- a/docs/_config.yml
+++ b/docs/_config.yml
@@ -1,4 +1,4 @@
 theme: jekyll-theme-hacker
-title: OpenCode Codex Auth Plugin
-description: Access GPT-5 Codex through your ChatGPT Plus/Pro subscription
-show_downloads: true
+title: codex-multi-auth docs
+description: Codex CLI multi-account OAuth documentation
+show_downloads: false
diff --git a/docs/benchmarks/code-edit-format-benchmark.md b/docs/benchmarks/code-edit-format-benchmark.md
index 01d4177b..feace425 100644
--- a/docs/benchmarks/code-edit-format-benchmark.md
+++ b/docs/benchmarks/code-edit-format-benchmark.md
@@ -1,70 +1,82 @@
 # Code Edit Format Benchmark
 
-This benchmark compares code edit formats across Codex models using the same task corpus and validators.
+Benchmark guide for comparing edit format performance and render behavior.
 
-Formats:
-- `patch`
-- `replace`
-- `hashline`
-- `hashline_v2` (benchmark-only experimental mode based on the PinEdit-style workflow)
+* * *
 
-Default model preset:
-- `codex-core` (stable named `openai/*codex*` models discovered from local `opencode models`)
+## Purpose
 
-## Outputs
+Use this benchmark to compare edit-format throughput and output quality for Codex-focused editing workloads.
 
-Each run writes artifacts under `.tmp-bench/<label>/`:
-- `results/summary.json`
-- `results/report.md`
-- `results/dashboard.html`
-- `logs/*.ndjson` (measured runs and failures by default)
-- `workspaces/*` (per-run temp workspaces)
+* * *
 
-This keeps benchmark artifacts easy to delete later.
-
-## Quick start
-
-Smoke run (few tasks, 1 measured run, no warmup):
+## Quick Start
 
 ```bash
-node scripts/benchmark-edit-formats.mjs --smoke --models=openai/gpt-5-codex
+npm run bench:edit-formats
 ```
 
-Fuller run on Codex core preset:
+Smoke run:
 
 ```bash
-node scripts/benchmark-edit-formats.mjs --preset=codex-core --warmup-runs=1 --measured-runs=5
+npm run bench:edit-formats:smoke
 ```
 
-Use your existing provider config/home when required:
+Render dashboard output:
 
 ```bash
-node scripts/benchmark-edit-formats.mjs --home="C:\\Users\\Administrator"
+npm run bench:edit-formats:render
 ```
 
-## Re-render dashboard from summary
+* * *
 
-```bash
-node scripts/benchmark-render-dashboard.mjs --input=.tmp-bench/<label>/results/summary.json
-```
+## Output Files
+
+| Output | Location |
+| --- | --- |
+| Benchmark report JSON | `.tmp/edit-format-benchmark-*.json` |
+| Render preview artifacts | `.tmp/edit-format-benchmark-render-*.txt` |
+
+(Temporary benchmark artifacts are not source files.)
+
+* * *
 
-## Notes on mode behavior
+## Common Presets
 
-- `patch` mode expects filesystem patch/edit tools (for example `filesystem_edit_file`). If the model uses another tool family, the run is marked unsupported for patch-mode scoring.
-- `replace` mode expects plugin edit payloads with `oldString/newString`.
-- `hashline` mode expects `hashline_read` followed by a hash-anchored edit (`lineRef`).
-- `hashline_v2` expects no tools and a single JSON edit call response in the benchmark-only PinEdit-style schema.
+| Preset | Goal |
+| --- | --- |
+| `codex-core` | Baseline Codex-oriented evaluation |
+| `smoke` | Fast sanity check for CI/local validation |
+
+* * *
+
+## Interpretation Checklist
+
+1. Compare latency per format.
+2. Measure token/size overhead.
+3. Review success/error rates.
+4. Validate output consistency.
+5. Confirm no regressions in editing fidelity.
+
+* * *
 
 ## Cleanup
 
-Delete all benchmark artifacts:
+Bash:
 
 ```bash
-rm -rf .tmp-bench
+rm -rf .tmp
 ```
 
 PowerShell:
 
 ```powershell
-Remove-Item -Recurse -Force .tmp-bench
+Remove-Item ".tmp" -Recurse -Force -ErrorAction SilentlyContinue
 ```
+
+* * *
+
+## Related
+
+- [../development/TESTING.md](../development/TESTING.md)
+- [../development/ARCHITECTURE.md](../development/ARCHITECTURE.md)
diff --git a/docs/configuration.md b/docs/configuration.md
index eb466f62..d24c365d 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -1,395 +1,183 @@
-# configuration
+# Configuration
 
-complete reference for configuring the plugin. most of this is optional - defaults work fine for most people.
+Configure behavior from one settings root and optional environment overrides.
 
----
+* * *
 
-## quick start
+## Config Files
 
-```json
-{
-  "$schema": "https://opencode.ai/config.json",
-  "plugin": ["codex-multi-auth@latest"],
-  "provider": {
-    "openai": {
-      "options": {
-        "reasoningEffort": "medium",
-        "reasoningSummary": "auto",
-        "textVerbosity": "medium",
-        "include": ["reasoning.encrypted_content"],
-        "store": false
-      }
-    }
-  }
-}
-```
-
----
-
-## model options
-
-### reasoningEffort
-
-controls how much thinking the model does.
-
-| model | supported values |
-|-------|------------------|
-| `gpt-5.2` | none, low, medium, high, xhigh |
-| `gpt-5-codex` | low, medium, high (default: high) |
-| `gpt-5.3-codex` | low, medium, high, xhigh (legacy alias to `gpt-5-codex`) |
-| `gpt-5.3-codex-spark` | low, medium, high, xhigh (entitlement-gated legacy alias; add manually) |
-| `gpt-5.2-codex` | low, medium, high, xhigh (legacy alias to `gpt-5-codex`) |
-| `gpt-5.1-codex-max` | low, medium, high, xhigh |
-| `gpt-5.1-codex` | low, medium, high |
-| `gpt-5.1-codex-mini` | medium, high |
-| `gpt-5.1` | none, low, medium, high |
-
-the shipped config templates include:
-- modern template (variants): 27 presets
-- legacy template (explicit model ids): 22 presets
-
-Spark is not added by default. add `gpt-5.3-codex-spark` manually only for entitled workspaces.
-
-what they mean:
-- `none` - no reasoning phase (base models only, auto-converts to `low` for codex)
-- `low` - light reasoning, fastest
-- `medium` - balanced (default)
-- `high` - deep reasoning
-- `xhigh` - max depth for complex tasks (default for legacy `gpt-5.3-codex` / `gpt-5.2-codex` aliases and `gpt-5.1-codex-max`)
-
-### reasoningSummary
-
-| value | what it does |
-|-------|--------------|
-| `auto` | adapts automatically (default) |
-| `concise` | short summaries |
-| `detailed` | verbose summaries |
-
-legacy `off`/`on` values are accepted from old configs but normalized to `auto` at request time.
+| Layer | Path | Purpose |
+| --- | --- | --- |
+| Unified settings | `~/.codex/multi-auth/settings.json` | Dashboard display + backend `pluginConfig` |
+| Optional config override file | `CODEX_MULTI_AUTH_CONFIG_PATH=<path>` | External config input compatibility |
 
-### textVerbosity
+If `CODEX_MULTI_AUTH_DIR` is set, replace `~/.codex/multi-auth` with that custom root.
 
-| value | what it does |
-|-------|--------------|
-| `low` | concise responses |
-| `medium` | balanced (default) |
-| `high` | verbose responses |
+* * *
 
-### include
+## Unified Settings Structure
 
-array of extra response fields.
-
-| value | why you need it |
-|-------|-----------------|
-| `reasoning.encrypted_content` | required for multi-turn with `store: false` |
-
-### store
-
-| value | what it does |
-|-------|--------------|
-| `false` | stateless mode (required for this plugin) |
-| `true` | not supported by codex api |
-
----
-
-## plugin config
-
-advanced settings go in `~/.opencode/codex-multi-auth-config.json`:
+`settings.json` stores two top-level blocks:
 
 ```json
 {
-  "codexMode": true,
-  "codexTuiV2": true,
-  "codexTuiColorProfile": "truecolor",
-  "codexTuiGlyphMode": "ascii",
-  "fastSession": false,
-  "fastSessionStrategy": "hybrid",
-  "fastSessionMaxInputItems": 30,
-  "perProjectAccounts": true,
-  "toastDurationMs": 5000,
-  "retryAllAccountsRateLimited": true,
-  "retryAllAccountsMaxWaitMs": 0,
-  "unsupportedCodexPolicy": "strict",
-  "fallbackOnUnsupportedCodexModel": false,
-  "fallbackToGpt52OnUnsupportedGpt53": true,
-  "unsupportedCodexFallbackChain": {
-    "gpt-5-codex": ["gpt-5.2-codex"]
+  "version": 1,
+  "dashboardDisplaySettings": {
+    "menuAutoFetchLimits": true,
+    "menuSortEnabled": true,
+    "menuSortMode": "ready-first",
+    "menuShowQuotaSummary": true,
+    "menuShowQuotaCooldown": true,
+    "menuLayoutMode": "compact-details"
+  },
+  "pluginConfig": {
+    "codexMode": true,
+    "liveAccountSync": true,
+    "sessionAffinity": true,
+    "proactiveRefreshGuardian": true,
+    "preemptiveQuotaEnabled": true,
+    "fetchTimeoutMs": 60000,
+    "streamStallTimeoutMs": 45000
   }
 }
 ```
 
-### options
-
-| option | default | what it does |
-|--------|---------|--------------|
-| `codexMode` | `true` | uses codex-opencode bridge prompt (synced with codex cli) |
-| `codexTuiV2` | `true` | enables codex-style terminal ui output (set `false` to keep legacy output) |
-| `codexTuiColorProfile` | `truecolor` | terminal color profile for codex ui (`truecolor`, `ansi256`, `ansi16`) |
-| `codexTuiGlyphMode` | `ascii` | glyph set for codex ui (`ascii`, `unicode`, `auto`) |
-| `fastSession` | `false` | forces low-latency settings per request (`reasoningEffort=none/low`, `reasoningSummary=auto`, `textVerbosity=low`) |
-| `fastSessionStrategy` | `hybrid` | `hybrid` speeds simple turns and keeps full-depth for complex prompts; `always` forces fast mode every turn |
-| `fastSessionMaxInputItems` | `30` | max input items kept when fast mode is applied |
-| `perProjectAccounts` | `true` | each project gets its own account storage |
-| `toastDurationMs` | `5000` | how long toast notifications stay visible (ms) |
-| `retryAllAccountsRateLimited` | `true` | wait and retry when all accounts hit rate limits |
-| `retryAllAccountsMaxWaitMs` | `0` | max wait time in ms (0 = unlimited) |
-| `retryAllAccountsMaxRetries` | `Infinity` | max retry attempts (omit this key for unlimited retries) |
-| `unsupportedCodexPolicy` | `strict` | unsupported-model behavior: `strict` (return entitlement error) or `fallback` (retry with configured fallback chain) |
-| `fallbackOnUnsupportedCodexModel` | `false` | legacy fallback toggle mapped to `unsupportedCodexPolicy` (prefer using `unsupportedCodexPolicy`) |
-| `fallbackToGpt52OnUnsupportedGpt53` | `true` | legacy compatibility toggle for the `gpt-5.3-codex -> gpt-5.2-codex` edge when generic fallback is enabled |
-| `unsupportedCodexFallbackChain` | `{}` | optional per-model fallback-chain override (map of `model -> [fallback1, fallback2, ...]`) |
-| `sessionRecovery` | `true` | auto-recover from common api errors |
-| `autoResume` | `true` | auto-resume after thinking block recovery |
-| `tokenRefreshSkewMs` | `60000` | refresh tokens this many ms before expiry |
-| `rateLimitToastDebounceMs` | `60000` | debounce rate limit toasts |
-| `fetchTimeoutMs` | `60000` | upstream fetch timeout in ms |
-| `streamStallTimeoutMs` | `45000` | max time to wait for next SSE chunk before aborting |
-
-### hashline tools (plain opencode)
-
-No extra config is required. The plugin now:
-- overrides `edit` with a hashline-capable engine
-- adds `hashline_read` for `L<line>#<hash>` references
-
-recommended flow:
-
-```txt
-hashline_read path="src/file.ts"
-edit path="src/file.ts" lineRef="L42#deadbeef" operation="replace" content="new code"
-```
-
-legacy `edit oldString/newString` remains available as fallback.
+* * *
 
-### unsupported-model behavior + fallback chain
-
-by default the plugin is strict (`unsupportedCodexPolicy: "strict"`). it returns entitlement errors directly for unsupported models.
-
-Spark exception: `gpt-5.3-codex-spark` entitlement failures auto-fallback to the default chain even in strict mode, because Spark access is commonly limited to Pro/Business workspaces. This avoids long account-rotation stalls for non-entitled users.
-
-set `unsupportedCodexPolicy: "fallback"` to enable model fallback after account/workspace attempts are exhausted.
-
-defaults when fallback policy is enabled and `unsupportedCodexFallbackChain` is empty:
-- `gpt-5.3-codex -> gpt-5-codex -> gpt-5.2-codex`
-- `gpt-5.3-codex-spark -> gpt-5-codex -> gpt-5.3-codex -> gpt-5.2-codex` (applies if you manually select Spark model IDs)
-- `gpt-5.2-codex -> gpt-5-codex`
-- `gpt-5.1-codex -> gpt-5-codex`
-
-note: the TUI can continue showing your originally selected model while fallback is applied internally. use request logs to verify the effective upstream model (`request-*-after-transform.json`). set `CODEX_PLUGIN_LOG_BODIES=1` when you need to inspect raw `.body.*` fields.
-
-custom chain example:
-```json
-{
-  "unsupportedCodexPolicy": "fallback",
-  "fallbackOnUnsupportedCodexModel": true,
-  "unsupportedCodexFallbackChain": {
-    "gpt-5-codex": ["gpt-5.2-codex"],
-    "gpt-5.3-codex": ["gpt-5-codex", "gpt-5.2-codex"],
-    "gpt-5.3-codex-spark": ["gpt-5-codex", "gpt-5.3-codex", "gpt-5.2-codex"]
-  }
-}
-```
+## Recommended Presets
 
-legacy toggle compatibility:
-- `CODEX_AUTH_FALLBACK_UNSUPPORTED_MODEL=1` maps to fallback mode
-- `CODEX_AUTH_FALLBACK_UNSUPPORTED_MODEL=0` maps to strict mode
-
-### environment variables
-
-override any config with env vars:
-
-| variable | what it does |
-|----------|--------------|
-| `DEBUG_CODEX_PLUGIN=1` | enable debug logging |
-| `ENABLE_PLUGIN_REQUEST_LOGGING=1` | log request metadata (no raw prompt/response bodies) |
-| `CODEX_PLUGIN_LOG_BODIES=1` | include raw request/response bodies in log files (sensitive) |
-| `CODEX_PLUGIN_LOG_LEVEL=debug` | set log level (debug/info/warn/error) |
-| `CODEX_MODE=0` | disable bridge prompt |
-| `CODEX_TUI_V2=0` | disable codex-style ui (use legacy output) |
-| `CODEX_TUI_COLOR_PROFILE=ansi16` | force color profile for codex ui |
-| `CODEX_TUI_GLYPHS=unicode` | override glyph mode (`ascii`, `unicode`, `auto`) |
-| `CODEX_AUTH_PREWARM=0` | disable startup prewarm (prompt/instruction cache warmup) |
-| `CODEX_AUTH_FAST_SESSION=1` | enable fast-session defaults |
-| `CODEX_AUTH_FAST_SESSION_STRATEGY=always` | force fast mode on every prompt |
-| `CODEX_AUTH_FAST_SESSION_MAX_INPUT_ITEMS=24` | tune max retained input items in fast mode |
-| `CODEX_AUTH_PER_PROJECT_ACCOUNTS=0` | disable per-project accounts |
-| `CODEX_AUTH_TOAST_DURATION_MS=8000` | set toast duration |
-| `CODEX_AUTH_RETRY_ALL_RATE_LIMITED=0` | disable wait-and-retry |
-| `CODEX_AUTH_RETRY_ALL_MAX_WAIT_MS=30000` | set max wait time |
-| `CODEX_AUTH_RETRY_ALL_MAX_RETRIES=1` | set max retries |
-| `CODEX_AUTH_UNSUPPORTED_MODEL_POLICY=fallback` | enable generic unsupported-model fallback policy |
-| `CODEX_AUTH_FALLBACK_UNSUPPORTED_MODEL=1` | legacy fallback toggle (prefer policy variable above) |
-| `CODEX_AUTH_FALLBACK_GPT53_TO_GPT52=0` | disable only the legacy `gpt-5.3-codex -> gpt-5.2-codex` edge |
-| `CODEX_AUTH_ACCOUNT_ID=acc_xxx` | force specific workspace id |
-| `CODEX_AUTH_FETCH_TIMEOUT_MS=120000` | override fetch timeout |
-| `CODEX_AUTH_STREAM_STALL_TIMEOUT_MS=60000` | override SSE stall timeout |
-
----
-
-## config patterns
-
-### global options
-
-same settings for all models:
+### Stable Default
 
 ```json
 {
-  "plugin": ["codex-multi-auth@latest"],
-  "provider": {
-    "openai": {
-      "options": {
-        "reasoningEffort": "high",
-        "textVerbosity": "high",
-        "store": false
-      }
-    }
+  "pluginConfig": {
+    "liveAccountSync": true,
+    "sessionAffinity": true,
+    "proactiveRefreshGuardian": true,
+    "preemptiveQuotaEnabled": true,
+    "preemptiveQuotaRemainingPercent5h": 5,
+    "preemptiveQuotaRemainingPercent7d": 5,
+    "preemptiveQuotaMaxDeferralMs": 7200000,
+    "fetchTimeoutMs": 60000,
+    "streamStallTimeoutMs": 45000,
+    "networkErrorCooldownMs": 6000,
+    "serverErrorCooldownMs": 4000
   }
 }
 ```
 
-### per-model options
-
-different settings for different models:
+### More Conservative
 
 ```json
 {
-  "provider": {
-    "openai": {
-      "options": {
-        "reasoningEffort": "medium",
-        "store": false
-      },
-      "models": {
-        "gpt-5.2-fast": {
-          "name": "fast gpt-5.2",
-          "options": { "reasoningEffort": "low" }
-        },
-        "gpt-5.2-smart": {
-          "name": "smart gpt-5.2",
-          "options": { "reasoningEffort": "high" }
-        }
-      }
-    }
+  "pluginConfig": {
+    "preemptiveQuotaRemainingPercent5h": 10,
+    "preemptiveQuotaRemainingPercent7d": 10,
+    "fetchTimeoutMs": 90000,
+    "streamStallTimeoutMs": 60000,
+    "networkErrorCooldownMs": 8000,
+    "serverErrorCooldownMs": 6000
   }
 }
 ```
 
-model options override global options.
-
-### project-specific
+### More Aggressive
 
-global (`~/.config/opencode/opencode.json`):
 ```json
 {
-  "plugin": ["codex-multi-auth@latest"],
-  "provider": {
-    "openai": {
-      "options": { "reasoningEffort": "medium" }
-    }
+  "pluginConfig": {
+    "sessionAffinity": false,
+    "preemptiveQuotaRemainingPercent5h": 3,
+    "preemptiveQuotaRemainingPercent7d": 3,
+    "preemptiveQuotaMaxDeferralMs": 1800000,
+    "fetchTimeoutMs": 45000,
+    "streamStallTimeoutMs": 25000,
+    "networkErrorCooldownMs": 3000,
+    "serverErrorCooldownMs": 2000
   }
 }
 ```
 
-project (`my-project/.opencode.json`):
-```json
-{
-  "provider": {
-    "openai": {
-      "options": { "reasoningEffort": "high" }
-    }
-  }
-}
-```
+* * *
 
-result: project uses `high`, other projects use `medium`.
+## High-Impact Keys
 
----
+| Key | Default | Why it matters |
+| --- | --- | --- |
+| `menuAutoFetchLimits` | `true` | Refreshes quota limits in menu automatically |
+| `menuSortEnabled` | `true` | Enables readiness-based account ordering |
+| `menuSortMode` | `ready-first` | Puts more available accounts higher |
+| `liveAccountSync` | `true` | Picks up account file updates without restart |
+| `sessionAffinity` | `true` | Keeps same conversation on same account when healthy |
+| `proactiveRefreshGuardian` | `true` | Refreshes expiring tokens in background |
+| `preemptiveQuotaEnabled` | `true` | Defers before quota hard exhaustion |
+| `parallelProbing` | `false` | Enables parallel health probes |
+| `fetchTimeoutMs` | `60000` | Total request timeout |
+| `streamStallTimeoutMs` | `45000` | Stream inactivity failover trigger |
 
-## file locations
+* * *
 
-| file | what it's for |
-|------|---------------|
-| `~/.config/opencode/opencode.json` | global opencode config |
-| `<project>/.opencode.json` | project-specific config |
-| `~/.opencode/codex-multi-auth-config.json` | plugin config |
-| `~/.opencode/auth/openai.json` | oauth tokens |
-| `~/.opencode/openai-codex-accounts.json` | global account storage |
-| `~/.opencode/projects/<project-key>/openai-codex-accounts.json` | per-project account storage |
-| `~/.opencode/logs/codex-plugin/` | debug logs |
+## Environment Variable Overrides
 
----
+| Variable | Effect |
+| --- | --- |
+| `CODEX_MULTI_AUTH_DIR` | Override settings/accounts root directory |
+| `CODEX_MULTI_AUTH_CONFIG_PATH` | Read config from alternate file |
+| `CODEX_MODE=0/1` | Disable/enable Codex mode |
+| `CODEX_TUI_V2=0/1` | Disable/enable TUI v2 |
+| `CODEX_TUI_COLOR_PROFILE=truecolor\|ansi256\|ansi16` | TUI color profile |
+| `CODEX_TUI_GLYPHS=ascii\|unicode\|auto` | TUI glyph style |
+| `CODEX_AUTH_FETCH_TIMEOUT_MS=<ms>` | Override request timeout |
+| `CODEX_AUTH_STREAM_STALL_TIMEOUT_MS=<ms>` | Override stream stall timeout |
+| `DEBUG_CODEX_PLUGIN=1` | Enable debug logging |
+| `ENABLE_PLUGIN_REQUEST_LOGGING=1` | Enable request metadata logs |
+| `CODEX_PLUGIN_LOG_BODIES=1` | Log raw payload bodies (sensitive) |
 
-## debugging
+* * *
 
-### check config is valid
+## Validate Current Configuration
 
 ```bash
-opencode
-# shows errors if config is invalid
+codex auth status
+codex auth list
+codex auth report --json
 ```
 
-### verify model resolution
+* * *
 
-```bash
-DEBUG_CODEX_PLUGIN=1 opencode run "test" --model=openai/gpt-5.2
-```
+## Build and Upgrade References
 
-look for:
-```
-[openai-codex-plugin] Model config lookup: "gpt-5.2" → normalized to "gpt-5.2" for API {
-  hasModelSpecificConfig: true,
-  resolvedConfig: { ... }
-}
-```
-
-### test per-model options
+If settings or runtime behavior changed locally:
 
 ```bash
-# modern opencode (variants)
-ENABLE_PLUGIN_REQUEST_LOGGING=1 opencode run "test" --model=openai/gpt-5.2 --variant=low
-ENABLE_PLUGIN_REQUEST_LOGGING=1 opencode run "test" --model=openai/gpt-5.2 --variant=high
-
-# legacy presets (model names include the effort)
-ENABLE_PLUGIN_REQUEST_LOGGING=1 opencode run "test" --model=openai/gpt-5.2-low
-ENABLE_PLUGIN_REQUEST_LOGGING=1 opencode run "test" --model=openai/gpt-5.2-high
-
-# compare reasoning.effort in logs
-cat ~/.opencode/logs/codex-plugin/request-*-after-transform.json | jq '.reasoning.effort'
+npm run lint
+npm run typecheck
+npm test
 ```
 
----
+Migration quick checklist:
 
-## troubleshooting
+1. Keep canonical commands on `codex auth ...` (do not use legacy command paths in new docs/workflows).
+2. Ensure `settings.json` contains both `dashboardDisplaySettings` and `pluginConfig`.
+3. If you use external config input, verify `CODEX_MULTI_AUTH_CONFIG_PATH` points to the intended file.
+4. Re-run `codex auth check` after upgrading so quota/session snapshots refresh against current runtime behavior.
 
-### model not found
+Relevant npm scripts for this settings/runtime model:
 
-**error**: `Model 'openai/my-model' not found`
+- `npm run build`
+- `npm run test`
+- `npm run test:coverage`
+- `npm run audit:ci`
 
-**fix**: make sure config key matches exactly:
-```json
-{ "models": { "my-model": { ... } } }
-```
-```bash
-opencode run "test" --model=openai/my-model
-```
+For migration between older command/path layouts, follow:
 
-### per-model options not applied
+- [upgrade.md](upgrade.md)
 
-```bash
-DEBUG_CODEX_PLUGIN=1 opencode run "test" --model=openai/your-model
-```
-
-look for `hasModelSpecificConfig: true`. if it's false, config lookup failed - check for typos.
-
-### per-project accounts not working
-
-make sure you're in a project directory (has `.git`, `package.json`, etc). the plugin auto-detects the project root and uses a namespaced file under `~/.opencode/projects/`. if no project root is found, it falls back to global storage.
-
-check which storage is being used:
-```bash
-DEBUG_CODEX_PLUGIN=1 opencode
-# look for storage path in logs
-```
+* * *
 
----
+## Related
 
-**next**: [troubleshooting](troubleshooting.md) | [back to docs](index.md)
+- [reference/settings.md](reference/settings.md)
+- [reference/storage-paths.md](reference/storage-paths.md)
+- [development/CONFIG_FIELDS.md](development/CONFIG_FIELDS.md)
+- [development/CONFIG_FLOW.md](development/CONFIG_FLOW.md)
diff --git a/docs/development/ARCHITECTURE.md b/docs/development/ARCHITECTURE.md
index 24e3da7c..80fa941c 100644
--- a/docs/development/ARCHITECTURE.md
+++ b/docs/development/ARCHITECTURE.md
@@ -1,547 +1,118 @@
-# Plugin Architecture & Technical Decisions
+# Architecture
+
+Runtime architecture for Codex CLI-first multi-account OAuth with optional plugin-host integration.
+
+* * *
 
-This document explains the technical design decisions, architecture, and implementation details of the OpenAI Codex OAuth plugin for OpenCode.
+## Design Goals
+
+1. Keep account management simple for end users (`codex auth ...`).
+2. Preserve resilient request routing across multiple accounts.
+3. Support plugin-host request flow without patching host core.
+4. Keep stateless backend request compatibility (`store: false`).
 
-## Table of Contents
-- [Repository Scope Map](./REPOSITORY_SCOPE.md)
-- [Architecture Overview](#architecture-overview)
-- [Stateless vs Stateful Mode](#stateless-vs-stateful-mode)
-- [Message ID Handling](#message-id-handling)
-- [Reasoning Content Flow](#reasoning-content-flow)
-- [Request Pipeline](#request-pipeline)
-- [Comparison with Codex CLI](#comparison-with-codex-cli)
-- [Design Rationale](#design-rationale)
-- [TUI Parity Checklist](./TUI_PARITY_CHECKLIST.md)
+* * *
 
----
+## System Diagram
 
-## Architecture Overview
+```text
+Terminal user
+  |
+  | codex auth ...
+  v
+scripts/codex.js
+  |- handles auth subcommands locally (codex-manager)
+  |- forwards all other codex commands to @openai/codex
+  v
+lib/codex-manager.ts
+  |- oauth login flow + dashboard + check/forecast/fix/doctor/report
+  |- reads/writes ~/.codex/multi-auth/*
+  |- syncs active account to Codex CLI state files
 
+Plugin-host runtime (optional)
+  |
+  v
+index.ts (plugin entry)
+  |- account loading + live sync + session affinity + proactive refresh
+  |- request transformation + retry + rotation + failover
+  v
+OpenAI OAuth + Codex/ChatGPT backend
 ```
-┌─────────────┐
-│  OpenCode   │  TUI/Desktop client
-└──────┬──────┘
-       │
-       │ streamText() with AI SDK
-       │
-       ▼
-┌──────────────────────────────┐
-│  OpenCode Provider System    │
-│  - Loads plugin               │
-│  - Calls plugin.auth.loader() │
-│  - Passes provider config     │
-└──────┬───────────────────────┘
-       │
-       │ Custom fetch()
-       │
-       ▼
-┌──────────────────────────────┐
-│  This Plugin                 │
-│  - OAuth authentication      │
-│  - Request transformation    │
-│  - store:false handling      │
-│  - Codex bridge prompts      │
-└──────┬───────────────────────┘
-       │
-       │ HTTP POST with OAuth
-       │
-       ▼
-┌──────────────────────────────┐
-│  OpenAI Codex API            │
-│  (ChatGPT Backend)           │
-│  - Requires OAuth            │
-│  - Supports store:false      │
-│  - Returns SSE stream        │
-└──────────────────────────────┘
-```
-
----
-
-## Stateless vs Stateful Mode
-
-### Why store:false?
-
-The plugin uses **`store: false`** (stateless mode) because:
-
-1. **ChatGPT Backend Requirement** (confirmed via testing):
-   ```json
-   // Attempt with store:true → 400 Bad Request
-   {"detail":"Store must be set to false"}
-   ```
-
-2. **Codex CLI Behavior** (`tmp/codex/codex-rs/core/src/client.rs:215-232`):
-   ```rust
-   // Codex CLI uses store:false for ChatGPT OAuth
-   let azure_workaround = self.provider.is_azure_responses_endpoint();
-   store: azure_workaround,  // false for ChatGPT, true for Azure
-   ```
-
-**Key Points**:
-1. ✅ **ChatGPT backend REQUIRES store:false** (not optional)
-2. ✅ **Codex CLI uses store:false for ChatGPT**
-3. ✅ **Azure requires store:true** (different endpoint, not supported by this plugin)
-4. ✅ **Stateless mode = no server-side conversation storage**
-
-### How Context Works with store:false
-
-**Question**: If there's no server storage, how does the LLM remember previous turns?
-
-**Answer**: Full message history is sent in every request:
-
-```typescript
-// Turn 3 request contains ALL previous messages:
-input: [
-  { role: "developer", content: "..." },      // System prompts
-  { role: "user", content: "write test.txt" },     // Turn 1 user
-  { type: "function_call", name: "write", ... },   // Turn 1 tool call
-  { type: "function_call_output", ... },           // Turn 1 tool result
-  { role: "assistant", content: "Done!" },         // Turn 1 response
-  { role: "user", content: "read it" },            // Turn 2 user
-  { type: "function_call", name: "read", ... },    // Turn 2 tool call
-  { type: "function_call_output", ... },           // Turn 2 tool result
-  { role: "assistant", content: "Contents..." },   // Turn 2 response
-  { role: "user", content: "what did you write?" } // Turn 3 user (current)
-]
-// All IDs stripped, item_reference filtered out
-```
-
-**Context is maintained through**:
-- ✅ Full message history (LLM sees all previous messages)
-- ✅ Full tool call history (LLM sees what it did)
-- ✅ `reasoning.encrypted_content` (preserves reasoning between turns)
-
-**Source**: Verified via `ENABLE_PLUGIN_REQUEST_LOGGING=1 CODEX_PLUGIN_LOG_BODIES=1` logs
-
-### Store Comparison
-
-| Aspect | store:false (This Plugin) | store:true (Azure Only) |
-|--------|---------------------------|-------------------------|
-| **ChatGPT Support** | ✅ Required | ❌ Rejected by API |
-| **Message History** | ✅ Sent in each request (no IDs) | Stored on server |
-| **Message IDs** | ❌ Must strip all | ✅ Required |
-| **AI SDK Compat** | ❌ Must filter `item_reference` | ✅ Works natively |
-| **Context** | Full history + encrypted reasoning | Server-stored conversation |
-| **Codex CLI Parity** | ✅ Perfect match | ❌ Different mode |
-
-**Decision**: Use **`store:false`** (only option for ChatGPT backend).
-
----
-
-## Message ID Handling & AI SDK Compatibility
-
-### The Problem
-
-**OpenCode/AI SDK sends two incompatible constructs**:
-```typescript
-// Multi-turn request from OpenCode
-const body = {
-  input: [
-    { type: "message", role: "developer", content: [...] },
-    { type: "message", role: "user", content: [...], id: "msg_abc" },
-    { type: "item_reference", id: "rs_xyz" },  // ← AI SDK construct
-    { type: "function_call", id: "fc_123" }
-  ]
-};
-```
-
-**Two issues**:
-1. `item_reference` - AI SDK construct for server state lookup (not in Codex API spec)
-2. Message IDs - Cause "item not found" with `store: false`
-
-**ChatGPT Backend Requirement** (confirmed via testing):
-```json
-{"detail":"Store must be set to false"}
-```
-
-**Errors that occurred**:
-```
-❌ "Item with id 'msg_abc' not found. Items are not persisted when `store` is set to false."
-❌ "Missing required parameter: 'input[3].id'" (when item_reference has no ID)
-```
-
-### The Solution
-
-**Filter AI SDK Constructs + Strip IDs** (`lib/request/request-transformer.ts:114-135`):
-```typescript
-export function filterInput(input: InputItem[]): InputItem[] {
-  return input
-    .filter((item) => {
-      // Remove AI SDK constructs not supported by Codex API
-      if (item.type === "item_reference") {
-        return false;  // AI SDK only - references server state
-      }
-      return true;  // Keep all other items
-    })
-    .map((item) => {
-      // Strip IDs from all items (stateless mode)
-      if (item.id) {
-        const { id, ...itemWithoutId } = item;
-        return itemWithoutId as InputItem;
-      }
-      return item;
-    });
-}
-```
-
-**Why this approach?**
-1. ✅ **Filter `item_reference`** - Not in Codex API, AI SDK-only construct
-2. ✅ **Keep all messages** - LLM needs full conversation history for context
-3. ✅ **Strip ALL IDs** - Matches Codex CLI stateless behavior
-4. ✅ **Future-proof** - No ID pattern matching, handles any ID format
-
-### Debug Logging
-
-The plugin logs ID filtering for debugging:
-
-```typescript
-// Before filtering
-console.log(`[openai-codex-plugin] Filtering ${originalIds.length} message IDs from input:`, originalIds);
-
-// After filtering
-console.log(`[openai-codex-plugin] Successfully removed all ${originalIds.length} message IDs`);
-
-// Or warning if IDs remain
-console.warn(`[openai-codex-plugin] WARNING: ${remainingIds.length} IDs still present after filtering:`, remainingIds);
-```
-
-**Source**: `lib/request/request-transformer.ts:287-301`
-
----
-
-## Reasoning Content Flow
-
-### Context Preservation Without Storage
-
-**Challenge**: How to maintain context across turns when `store:false` means no server-side storage?
-
-**Solution**: Use `reasoning.encrypted_content`
-
-```typescript
-body.include = modelConfig.include || ["reasoning.encrypted_content"];
-```
-
-**How it works**:
-1. **Turn 1**: Model generates reasoning, encrypted content returned
-2. **Client**: Stores encrypted content locally
-3. **Turn 2**: Client sends encrypted content back in request
-4. **Server**: Decrypts content to restore reasoning context
-5. **Model**: Has full context without server-side storage
-
-**Flow Diagram**:
-```
-Turn 1:
-Client → [Request without IDs] → Server
-         Server → [Response + encrypted reasoning] → Client
-         Client stores encrypted content locally
-
-Turn 2:
-Client → [Request with encrypted content, no IDs] → Server
-         Server decrypts reasoning context
-         Server → [Response + new encrypted reasoning] → Client
-```
-
-**Codex CLI equivalent** (`tmp/codex/codex-rs/core/src/client.rs:190-194`):
-```rust
-let include: Vec<String> = if reasoning.is_some() {
-    vec!["reasoning.encrypted_content".to_string()]
-} else {
-    vec![]
-};
-```
-
-**Source**: `lib/request/request-transformer.ts:303`
-
----
-
-## Request Pipeline
-
-### Transformation Steps
-
-```
-1. Original OpenCode Request
-   ├─ model: "gpt-5-codex"
-   ├─ input: [{ id: "msg_123", ... }, { id: "rs_456", ... }]
-   └─ tools: [...]
-
-2. Model Normalization
-   ├─ Detect codex/gpt-5/codex-mini variants
-   └─ Normalize to "gpt-5", "gpt-5-codex", or "codex-mini-latest"
-
-3. Config Merging
-   ├─ Global options (provider.openai.options)
-   ├─ Model-specific options (provider.openai.models[name].options)
-   └─ Result: merged config for this model
-
-4. Message ID Filtering
-   ├─ Remove ALL IDs from input array
-   ├─ Log original IDs for debugging
-   └─ Verify no IDs remain
-
-5. System Prompt Handling (CODEX_MODE)
-   ├─ Filter out OpenCode system prompts
-   ├─ Preserve OpenCode env + AGENTS instructions when concatenated
-   └─ Add Codex-OpenCode bridge prompt
-
-6. Fast Session Tuning (optional)
-   ├─ Clamp reasoning + verbosity for low-latency turns
-   ├─ Trim long stateless histories to a small window
-   └─ For trivial turns: may omit tool definitions + compact instructions
-
-7. Orphan Tool Output Handling
-   ├─ Match function_call_output to function_call OR local_shell_call
-   ├─ Match custom_tool_call_output to custom_tool_call
-   └─ Convert unmatched outputs to assistant messages (preserve context)
-
-8. Reasoning Configuration
-   ├─ Set reasoningEffort (none/minimal/low/medium/high/xhigh)
-   ├─ Set reasoningSummary (auto/detailed)
-   └─ Based on model variant
-
-9. Prompt Caching & Session Headers
-   ├─ Preserve host-supplied prompt_cache_key (OpenCode session id)
-   ├─ Add conversation + account headers for Codex debugging when cache key exists
-   └─ Leave headers unset if host does not provide a cache key
-
-10. Final Body
-   ├─ store: false
-   ├─ stream: true
-   ├─ instructions: Codex system prompt
-   ├─ input: Filtered messages (no IDs)
-   ├─ reasoning: { effort, summary }
-   ├─ text: { verbosity }
-   ├─ include: ["reasoning.encrypted_content"]
-   └─ prompt_cache_key: preserved when provided by host (OpenCode session id)
-```
-
-**Source**: `lib/request/request-transformer.ts:265-329`
-
----
-
-## Comparison with Codex CLI
-
-### What We Match
-
-| Feature | Codex CLI | This Plugin | Match? |
-|---------|-----------|-------------|--------|
-| **OAuth Flow** | ✅ PKCE + ChatGPT login | ✅ Same | ✅ |
-| **store Parameter** | `false` (ChatGPT) | `false` | ✅ |
-| **Message IDs** | Stripped in stateless | Stripped | ✅ |
-| **reasoning.encrypted_content** | ✅ Included | ✅ Included | ✅ |
-| **Model Normalization** | "gpt-5" / "gpt-5-codex" / "codex-mini-latest" | Same | ✅ |
-| **Reasoning Effort** | medium (default) | opinionated defaults by model family (for example GPT-5.3/5.2 Codex prefer `xhigh`) | ⚠️ (intentional) |
-| **Text Verbosity** | model-dependent defaults | config-driven (default: medium) | ✅ |
-
-### What We Add
-
-| Feature | Codex CLI | This Plugin | Why? |
-|---------|-----------|-------------|------|
-| **Codex-OpenCode Bridge** | N/A (native) | ✅ Custom prompt | OpenCode → Codex translation |
-| **OpenCode Prompt Filtering** | N/A | ✅ Filter & replace | Remove OpenCode prompts, keep env/AGENTS |
-| **Orphan Tool Output Handling** | ✅ Drop orphans | ✅ Convert to messages | Preserve context + avoid 400s |
-| **Usage-limit messaging** | CLI prints status | ✅ Friendly error summary | Surface 5h/weekly windows in OpenCode |
-| **Per-Model Options** | CLI flags | ✅ Config file | Better UX in OpenCode |
-| **Custom Model Names** | No | ✅ Display names | UI convenience |
-
----
-
-## Design Rationale
-
-### Why Not store:true?
-
-**Pros of store:true**:
-- ✅ No ID filtering needed
-- ✅ Server manages conversation
-- ✅ Potentially more robust
-
-**Cons of store:true**:
-- ❌ Diverges from Codex CLI behavior
-- ❌ Requires conversation ID management
-- ❌ More complex error handling
-- ❌ Unknown server-side storage limits
-
-**Decision**: Use `store:false` for Codex parity and simplicity.
-
-### Why Complete ID Removal?
-
-**Alternative**: Filter specific ID patterns (`rs_*`, `msg_*`, etc.)
-
-**Problem**:
-- ID patterns may change
-- New ID types could be added
-- Partial filtering is brittle
-
-**Solution**: Remove **ALL** IDs
-
-**Rationale**:
-- Matches Codex CLI behavior exactly
-- Future-proof against ID format changes
-- Simpler implementation (no pattern matching)
-- Clearer semantics (stateless = no IDs)
-
-### Why Codex-OpenCode Bridge?
-
-**Problem**: OpenCode's system prompts are optimized for OpenCode's tool set and behavior patterns.
-
-**Solution**: Replace OpenCode prompts with Codex-specific instructions.
-
-**Benefits**:
-- ✅ Explains tool name differences (apply_patch intent → patch/edit)
-- ✅ Documents available tools
-- ✅ Maintains OpenCode working style
-- ✅ Preserves Codex best practices
-- ✅ 90% reduction in prompt tokens
-
-**Source**: `lib/prompts/codex-opencode-bridge.ts`
-
-### Why Per-Model Config Options?
-
-**Alternative**: Single global config
-
-**Problem**:
-- `gpt-5-codex` optimal settings differ from `gpt-5-nano`
-- Users want quick switching between quality levels
-- No way to save "presets"
-
-**Solution**: Per-model options in config
-
-**Benefits**:
-- ✅ Save multiple configurations
-- ✅ Quick switching (no CLI args)
-- ✅ Descriptive names ("Fast", "Balanced", "Max Quality")
-- ✅ Persistent across sessions
-
-**Source**: `config/opencode-legacy.json` (legacy) or `config/opencode-modern.json` (variants)
-
----
-
-## Error Handling
-
-### Common Errors
-
-#### 1. "Item with id 'X' not found"
-**Cause**: Message ID leaked through filtering
-**Fix**: Improved `filterInput()` removes ALL IDs
-**Prevention**: Debug logging catches remaining IDs
-
-#### 2. Token Expiration
-**Cause**: OAuth access token expired
-**Fix**: `shouldRefreshToken()` checks expiration
-**Prevention**: Auto-refresh before requests
-
-#### 3. "store: false" Validation Error (Azure)
-**Cause**: Azure doesn't support stateless mode
-**Workaround**: Codex CLI uses `store: true` for Azure only
-**This Plugin**: Only supports ChatGPT OAuth (no Azure)
-
----
-
-## Multi-Account Rotation (v4.4.0+)
-
-### Health-Based Account Selection
-
-The plugin tracks account health and uses intelligent rotation:
-
-```
-Account Selection Flow:
-1. Score = (health × 2) + (tokens × 5) + (freshness × 0.1)
-2. Select account with highest score
-3. Consume token from bucket
-4. On success: health +1
-5. On rate limit: health -10, mark rate-limited
-6. On failure: health -20
-7. Passive recovery: +2 health/hour
-```
-
-### Token Bucket Rate Limiting
-
-Client-side rate limiting prevents hitting API limits:
-
-| Parameter | Value |
-|-----------|-------|
-| Max tokens | 50 |
-| Regeneration | 6 tokens/min |
-| Consume per request | 1 token |
-
-### Reason-Aware Backoff
-
-Different rate limit reasons use different backoff multipliers:
-
-| Reason | Multiplier | Description |
-|--------|------------|-------------|
-| `quota` | 3.0× | Daily quota exhausted |
-| `tokens` | 1.5× | Token limit hit |
-| `concurrent` | 0.5× | Concurrent request limit |
-| `unknown` | 1.0× | Default |
-
-### RefreshQueue (v4.5.0+)
-
-Prevents race conditions when multiple concurrent requests try to refresh the same token:
-
-```typescript
-// Without RefreshQueue: N concurrent requests = N refresh attempts
-// With RefreshQueue: N concurrent requests = 1 refresh, N-1 await
-
-const queue = getRefreshQueue();
-const tokens = await queue.queuedRefresh(refreshToken, async () => {
-  return await actualRefresh(refreshToken);
-});
-```
-
-**Source**: `lib/refresh-queue.ts`, `lib/rotation.ts`
-
----
-
-## Performance Considerations
-
-### Token Usage
-
-**Codex Bridge Prompt**: ~550 tokens (~90% reduction vs full OpenCode prompt)
-**Benefit**: Faster inference, lower costs
 
-### Request Optimization
+* * *
 
-**Prompt Caching**: Uses `promptCacheKey` for session-based caching
-**Result**: Reduced token usage on subsequent turns
+## Core Subsystems
 
-**Source**: `tmp/opencode/packages/opencode/src/provider/transform.ts:90-92`
+| Subsystem | Key files | Responsibility |
+| --- | --- | --- |
+| CLI wrapper | `scripts/codex.js`, `scripts/codex-multi-auth.js` | Command routing and alias normalization |
+| Auth flow | `lib/auth/auth.ts`, `lib/auth/server.ts`, `lib/auth/browser.ts` | PKCE OAuth flow, callback handling, browser/manual auth path |
+| Account manager | `lib/codex-manager.ts`, `lib/accounts.ts` | Dashboard actions, account selection, health operations |
+| Storage/runtime paths | `lib/storage.ts`, `lib/storage/paths.ts`, `lib/runtime-paths.ts` | Account/settings persistence, migration, path resolution |
+| Unified settings | `lib/unified-settings.ts`, `lib/dashboard-settings.ts`, `lib/config.ts` | Shared settings persistence + runtime config defaults/overrides |
+| Forecast + quota | `lib/forecast.ts`, `lib/quota-probe.ts`, `lib/quota-cache.ts` | Readiness scoring, live quota probe, cached quota view |
+| Resilience runtime | `lib/live-account-sync.ts`, `lib/session-affinity.ts`, `lib/refresh-guardian.ts`, `lib/refresh-lease.ts` | No-restart sync, sticky sessions, proactive refresh, cross-process refresh dedupe |
+| Failure handling | `lib/request/failure-policy.ts`, `lib/request/stream-failover.ts`, `lib/request/rate-limit-backoff.ts` | Controlled retry, stream failover, cooldown/backoff |
+| Capability/entitlement | `lib/capability-policy.ts`, `lib/entitlement-cache.ts`, `lib/preemptive-quota-scheduler.ts` | Unsupported-model suppression, policy scoring, quota deferral |
+| Plugin-host request bridge | `index.ts`, `lib/request/fetch-helpers.ts`, `lib/request/request-transformer.ts` | Request shaping, headers, response handling, retry/rotation |
 
----
+* * *
 
-## Future Improvements
+## Request Pipeline (Plugin Host)
 
-### Potential Enhancements
+High-level flow:
 
-1. **Azure Support**: Add `store: true` mode with ID management
-2. **Version Detection**: Adapt to OpenCode/AI SDK version changes
-3. **Config Validation**: Warn about unsupported options
-4. **Test Coverage**: Unit tests for all transformation functions
-5. **Performance Metrics**: Log token usage and latency
+1. Load runtime config and account manager.
+2. Normalize incoming model/provider request shape.
+3. Enforce Codex backend invariants:
+   - `stream: true`
+   - `store: false`
+   - include `reasoning.encrypted_content`
+4. Strip unsupported payload forms for stateless behavior.
+5. Select candidate account with health + quota + affinity logic.
+6. Execute request with timeout/retry/failover policy.
+7. Update cooldown/rate-limit/session-affinity state.
+8. Persist updated account/cache state.
 
-## Terminal UI Runtime (Codex TUI v2)
+* * *
 
-The plugin now supports a Codex-style terminal presentation layer for both interactive menus and text tool outputs.
+## Storage Model
 
-- Default: enabled (`codexTuiV2: true`)
-- Opt-out: `codexTuiV2: false` or `CODEX_TUI_V2=0`
-- Color profile selection:
-  - `codexTuiColorProfile: "truecolor" | "ansi256" | "ansi16"`
-  - `CODEX_TUI_COLOR_PROFILE`
-- Glyph mode selection:
-  - `codexTuiGlyphMode: "ascii" | "unicode" | "auto"`
-  - `CODEX_TUI_GLYPHS`
+Canonical root: `~/.codex/multi-auth`.
 
-Legacy output remains unchanged when V2 is disabled.
+| File | Purpose |
+| --- | --- |
+| `settings.json` | Unified dashboard + plugin config |
+| `openai-codex-accounts.json` | Main account pool |
+| `openai-codex-accounts.json.bak` / `.wal` | Backup and recovery journal |
+| `openai-codex-flagged-accounts.json` | Flagged account pool |
+| `quota-cache.json` | Cached quota snapshots |
+| `logs/` | Plugin logs when logging enabled |
+| `cache/` | Prompt/cache artifacts |
 
-### Breaking Changes to Watch
+* * *
 
-1. **AI SDK Updates**: Changes to `.responses()` method
-2. **OpenCode Changes**: New message ID formats
-3. **Codex API Changes**: New request parameters
+## TUI Runtime Notes
 
----
+- TUI v2 is default.
+- Palette and accent are configurable.
+- Account rows support compact + details views.
+- Hotkeys support quick-switch/search/help and per-account actions.
 
-## See Also
-- [CONFIG_FLOW.md](./CONFIG_FLOW.md) - Configuration system guide
-- [TUI_PARITY_CHECKLIST.md](./TUI_PARITY_CHECKLIST.md) - Auth dashboard and interaction parity checklist
-- [Codex CLI Source](https://github.com/openai/codex) - Official implementation
-- [OpenCode Source](https://github.com/sst/opencode) - OpenCode implementation
+* * *
+
+## Invariants
+
+1. OAuth callback port remains `1455`.
+2. Dist folder is generated output only.
+3. Non-auth `codex` commands are always forwarded to official Codex CLI.
+4. Canonical account-management commands remain `codex auth ...`.
+
+* * *
+
+## Related
+
+- [CONFIG_FIELDS.md](CONFIG_FIELDS.md)
+- [CONFIG_FLOW.md](CONFIG_FLOW.md)
+- [TESTING.md](TESTING.md)
+- [../features.md](../features.md)
diff --git a/docs/development/CONFIG_FIELDS.md b/docs/development/CONFIG_FIELDS.md
index c1862878..9a3ee4cf 100644
--- a/docs/development/CONFIG_FIELDS.md
+++ b/docs/development/CONFIG_FIELDS.md
@@ -1,679 +1,217 @@
-# Config Fields: Complete Guide
+# Config Fields Reference
 
-Understanding the difference between config key, `id`, and `name` fields in OpenCode model configuration.
+Complete field inventory for runtime configuration and display settings.
 
-## The Three Fields
+* * *
 
-```json
-{
-  "provider": {
-    "openai": {
-      "models": {
-        "THIS-IS-THE-CONFIG-KEY": {
-          "id": "this-is-the-id-field",
-          "name": "This is the name field"
-        }
-      }
-    }
-  }
-}
-```
-
----
-
-## What Each Field Controls
-
-### Config Key (Property Name)
-
-**Example:** `"gpt-5-codex-low"`
-
-**Used For:**
-- ✅ CLI `--model` flag: `--model=openai/gpt-5-codex-low`
-- ✅ OpenCode internal lookups: `provider.info.models["gpt-5-codex-low"]`
-- ✅ TUI persistence: Saved to `~/.opencode/tui` as `model_id = "gpt-5-codex-low"`
-- ✅ Custom command frontmatter: `model: openai/gpt-5-codex-low`
-- ✅ Agent configuration: `"model": "openai/gpt-5-codex-low"`
-- ✅ **Plugin config lookup**: `userConfig.models["gpt-5-codex-low"]`
-- ✅ Passed to custom loaders: `getModel(sdk, "gpt-5-codex-low")`
-
-**This is the PRIMARY identifier throughout OpenCode!**
-
----
-
-### `id` Field (Optional - NOT NEEDED for OpenAI)
-
-**Example:** `"gpt-5-codex"`
-
-**What it's used for:**
-- ⚠️ **Other providers**: Some providers use this for `sdk.languageModel(id)`
-- ⚠️ **Sorting**: Used for model priority sorting in OpenCode
-- ⚠️ **Documentation**: Indicates the "canonical" model ID
-
-**What it's NOT used for with OpenAI:**
-- ❌ **NOT sent to AI SDK** (config key is sent instead)
-- ❌ **NOT used by plugin** (plugin receives config key)
-- ❌ **NOT required** (OpenCode defaults it to config key)
-
-**Code Reference:** (`tmp/opencode/packages/opencode/src/provider/provider.ts:252`)
-```typescript
-const parsedModel: ModelsDev.Model = {
-  id: model.id ?? modelID,  // ← Defaults to config key if omitted
-  ...
-}
-```
-
-**OpenAI Custom Loader:** (`tmp/opencode/packages/opencode/src/provider/provider.ts:58-65`)
-```typescript
-openai: async () => {
-  return {
-    async getModel(sdk: any, modelID: string) {
-      return sdk.responses(modelID)  // ← Receives CONFIG KEY, not id field!
-    }
-  }
-}
-```
-
-**Our plugin receives:** `body.model = "gpt-5-codex-low"` (config key, NOT id field)
-
-**Recommendation:** **Omit the `id` field** for OpenAI provider - it's redundant and creates confusion. OpenCode will auto-set it to the config key.
-
----
-
-### `name` Field (Optional)
-
-**Example:** `"GPT 5 Codex Low (OAuth)"`
-
-**Used For:**
-- ✅ **TUI Model Picker**: Display name shown in the model selection UI
-- ℹ️ **Documentation**: Human-friendly description
-
-**Code Reference:** (`tmp/opencode/packages/opencode/src/provider/provider.ts:253`)
-```typescript
-const parsedModel: ModelsDev.Model = {
-  name: model.name ?? existing?.name ?? modelID,  // Defaults to config key
-  ...
-}
-```
-
-**If omitted:** Falls back to config key for display
-
----
-
-## Complete Flow Diagram
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                    What Users See & Use                         │
-├─────────────────────────────────────────────────────────────────┤
-│                                                                 │
-│  CLI Usage:                                                     │
-│  $ opencode run --model=openai/gpt-5-codex-low                 │
-│                                 └──────┬──────┘                 │
-│                                   CONFIG KEY                    │
-│                                                                 │
-│  TUI Display:                                                   │
-│  ┌──────────────────────────────────┐                          │
-│  │ Select Model:                    │                          │
-│  │                                  │                          │
-│  │ ○ GPT 5 Codex Low (OAuth) ←──────┼── name field            │
-│  │ ○ GPT 5 Codex Medium (OAuth)     │                          │
-│  │ ○ GPT 5 Codex High (OAuth)       │                          │
-│  └──────────────────────────────────┘                          │
-│                                                                 │
-│  Config Lookup (Plugin):                                       │
-│  userConfig.models["gpt-5-codex-low"].options                  │
-│                     └──────┬──────┘                             │
-│                       CONFIG KEY                                │
-│                                                                 │
-└─────────────────────────────────────────────────────────────────┘
-
-┌─────────────────────────────────────────────────────────────────┐
-│                    Internal Flow                                │
-├─────────────────────────────────────────────────────────────────┤
-│                                                                 │
-│  1. User Selection                                              │
-│     opencode run --model=openai/gpt-5-codex-low                │
-│     OpenCode parses: providerID="openai"                        │
-│                      modelID="gpt-5-codex-low" ← CONFIG KEY    │
-│                                                                 │
-│  2. OpenCode Provider Lookup                                    │
-│     provider.info.models["gpt-5-codex-low"]                     │
-│                          └──────┬──────┘                        │
-│                            CONFIG KEY                           │
-│                                                                 │
-│  3. Custom Loader Call (OpenAI)                                 │
-│     getModel(sdk, "gpt-5-codex-low")                            │
-│                   └──────┬──────┘                               │
-│                     CONFIG KEY                                  │
-│                                                                 │
-│  4. AI SDK Request Creation                                     │
-│     { model: "gpt-5-codex-low", ... }                           │
-│              └──────┬──────┘                                    │
-│                CONFIG KEY                                       │
-│                                                                 │
-│  5. Custom fetch() (Our Plugin)                                 │
-│     body.model = "gpt-5-codex-low"                              │
-│                  └──────┬──────┘                                │
-│                    CONFIG KEY                                   │
-│                                                                 │
-│  6. Plugin Config Lookup                                        │
-│     userConfig.models["gpt-5-codex-low"].options                │
-│                       └──────┬──────┘                           │
-│                         CONFIG KEY                              │
-│     Result: { reasoningEffort: "low", ... } ✅ FOUND           │
-│                                                                 │
-│  7. Plugin Normalization                                        │
-│     normalizeModel("gpt-5-codex-low")                           │
-│     Returns: "gpt-5-codex" ← SENT TO CODEX API                 │
-│                                                                 │
-│  8. TUI Persistence                                             │
-│     ~/.opencode/tui:                                            │
-│       provider_id = "openai"                                    │
-│       model_id = "gpt-5-codex-low" ← CONFIG KEY persisted      │
-│                                                                 │
-└─────────────────────────────────────────────────────────────────┘
-```
-
----
-
-## Field Purpose Summary
-
-### Config Key: The Real Identifier
-
-```json
-"gpt-5-codex-low": { ... }
- └──────┬──────┘
-   CONFIG KEY
-```
-
-**Purpose:**
-- 🎯 **PRIMARY identifier** - used everywhere in OpenCode
-- 🎯 **Plugin receives this** - what our plugin sees in `body.model`
-- 🎯 **Config lookup key** - how plugin finds per-model options
-- 🎯 **Persisted value** - saved in TUI state
-
-**Best Practice:** Use Codex CLI preset names (`gpt-5-codex-low`, `gpt-5-high`, etc.)
-
----
-
-### `id` Field: Documentation/Metadata
-
-```json
-"id": "gpt-5-codex"
-       └─────┬─────┘
-         ID FIELD
-```
-
-**Purpose:**
-- 📝 **Documents** what base model this variant uses
-- 📝 **Helps sorting** in model lists
-- 📝 **Clarity** - shows relationship between variants
-
-**Best Practice:** Set to the base API model name (`gpt-5-codex`, `gpt-5`, etc.)
-
-**Note:** For OpenAI provider, this is NOT sent to the API! The plugin normalizes the config key instead.
-
----
-
-### `name` Field: UI Display
-
-```json
-"name": "GPT 5 Codex Low (OAuth)"
-         └──────────┬──────────┘
-              NAME FIELD
-```
-
-**Purpose:**
-- 🎨 **TUI display** - what users see in model picker
-- 🎨 **User-friendly** - can be descriptive
-- 🎨 **Differentiation** - helps distinguish from API key models
-
-**Best Practice:** Human-friendly name with context (OAuth, API, subscription type, etc.)
-
----
-
-## Real-World Examples
-
-### Example 1: Our Current Config ✅
-
-```json
-{
-  "gpt-5-codex-low": {
-    "id": "gpt-5-codex",
-    "name": "GPT 5 Codex Low (OAuth)",
-    "options": { "reasoningEffort": "low" }
-  }
-}
-```
-
-**When user selects `openai/gpt-5-codex-low`:**
-- CLI: Uses `"gpt-5-codex-low"` (config key)
-- TUI: Shows `"GPT 5 Codex Low (OAuth)"` (name field)
-- Plugin receives: `body.model = "gpt-5-codex-low"` (config key)
-- Plugin looks up: `models["gpt-5-codex-low"]` ✅ Found
-- Plugin sends to API: `"gpt-5-codex"` (normalized)
-
-**Result:** ✅ Everything works perfectly!
-
----
-
-### Example 2: Multiple Variants of Same Model ✅
-
-```json
-{
-  "gpt-5-codex-low": {
-    "id": "gpt-5-codex",
-    "name": "GPT 5 Codex Low (OAuth)"
-  },
-  "gpt-5-codex-high": {
-    "id": "gpt-5-codex",
-    "name": "GPT 5 Codex High (OAuth)"
-  }
-}
-```
-
-**Why this works:**
-- Config keys are different: `"gpt-5-codex-low"` vs `"gpt-5-codex-high"` ✅
-- Same `id` is fine - it's just metadata
-- Different `name` values help distinguish in TUI
-
-**Result:** ✅ Two variants of same base model, different settings
-
----
-
-### Example 3: If We Made Config Key = ID ❌
-
-```json
-{
-  "gpt-5-codex": {
-    "id": "gpt-5-codex",
-    "name": "GPT 5 Codex Low (OAuth)",
-    "options": { "reasoningEffort": "low" }
-  },
-  "gpt-5-codex": {  // ❌ DUPLICATE KEY ERROR!
-    "id": "gpt-5-codex",
-    "name": "GPT 5 Codex High (OAuth)",
-    "options": { "reasoningEffort": "high" }
-  }
-}
-```
-
-**Problem:** JavaScript objects can't have duplicate keys!
-
-**Result:** ❌ Can't have multiple variants
-
----
-
-## Why We Need Different Config Keys
-
-**Problem:** Need multiple configurations for the same API model
-
-**Solution:** Different config keys → same `id`
-
-```json
-{
-  "gpt-5-codex-low": {          // ← Unique config key #1
-    "id": "gpt-5-codex",         // ← Same base model
-    "options": { "reasoningEffort": "low" }
-  },
-  "gpt-5-codex-medium": {       // ← Unique config key #2
-    "id": "gpt-5-codex",         // ← Same base model
-    "options": { "reasoningEffort": "medium" }
-  },
-  "gpt-5-codex-high": {         // ← Unique config key #3
-    "id": "gpt-5-codex",         // ← Same base model
-    "options": { "reasoningEffort": "high" }
-  }
-}
-```
-
-**Result:**
-- 3 selectable variants in TUI ✅
-- Same API model (`gpt-5-codex`) ✅
-- Different reasoning settings ✅
-- Plugin correctly applies per-variant options ✅
-
----
-
-## Backwards Compatibility
-
-### Config Changes are Safe ✅
+## Canonical Settings File
 
-**Old Plugin + Old Config:**
-```json
-"GPT 5 Codex Low (ChatGPT Subscription)": {
-  "id": "gpt-5-codex",
-  "options": { "reasoningEffort": "low" }
-}
-```
-**Result:** ❌ Per-model options broken (existing bug in old plugin)
-
-**New Plugin + Old Config:**
-```json
-"GPT 5 Codex Low (ChatGPT Subscription)": {
-  "id": "gpt-5-codex",
-  "options": { "reasoningEffort": "low" }
-}
-```
-**Result:** ✅ Per-model options work! (bug fixed)
-
-**New Plugin + New Config:**
-```json
-"gpt-5-codex-low": {
-  "id": "gpt-5-codex",
-  "name": "GPT 5 Codex Low (OAuth)",
-  "options": { "reasoningEffort": "low" }
-}
-```
-**Result:** ✅ Per-model options work! (bug fixed + cleaner naming)
-
-**Conclusion:**
-- ✅ Existing configs continue to work
-- ✅ New configs work better
-- ✅ Users can migrate at their own pace
-
----
-
-## Required Configuration Fields
-
-### `store` Field: Critical for AI SDK 2.0.50+
-
-**⚠️ Required as of AI SDK 2.0.50 (released Oct 12, 2025)**
-
-```json
-{
-  "provider": {
-    "openai": {
-      "options": {
-        "store": false
-      }
-    }
-  }
-}
-```
-
-**What it does:**
-- `false` (required): Prevents AI SDK from using `item_reference` for conversation history
-- `true` (default): Uses server-side storage with references (incompatible with Codex API)
-
-**Why required:**
-AI SDK 2.0.50 introduced automatic use of `item_reference` items to reduce payload size when `store: true`. However:
-- Codex API requires `store: false` (stateless mode)
-- `item_reference` items cannot be resolved without server-side storage
-- Without this setting, multi-turn conversations fail with: `"Item with id 'fc_xxx' not found"`
-
-**Where to set:**
-```json
-{
-  "provider": {
-    "openai": {
-      "options": {
-        "store": false  // ← Global: applies to all models
-      },
-      "models": {
-        "gpt-5-codex-low": {
-          "options": {
-            "store": false  // ← Per-model: redundant but explicit
-          }
-        }
-      }
-    }
-  }
-}
-```
-
-**Recommendation:** Set in global `options` since it's required for all models using this plugin.
-
-**Note:** The plugin also includes a `chat.params` hook that automatically injects `store: false`, but explicit configuration is recommended for clarity and forward compatibility.
-
----
-
-## Recommended Structure
-
-### Recommended: Config Key + Name ✅
-
-```json
-{
-  "gpt-5-codex-low": {
-    "name": "GPT 5 Codex Low (OAuth)",
-    "options": { "reasoningEffort": "low" }
-  }
-}
-```
-
-**Benefits:**
-- ✅ Clean config key: `gpt-5-codex-low` (matches Codex CLI presets)
-- ✅ Friendly display: `"GPT 5 Codex Low (OAuth)"` (UX)
-- ✅ No redundant fields
-- ✅ OpenCode auto-sets `id` to config key
-
-**Why no `id` field?**
-- For OpenAI provider, the `id` field is NOT used (custom loader receives config key)
-- OpenCode defaults `id` to config key if omitted
-- Including it is redundant and creates confusion
-
----
-
-### Minimal Structure (Works but less friendly)
-
-```json
-{
-  "gpt-5-codex-low": {
-    "options": { "reasoningEffort": "low" }
-  }
-}
-```
-
-**What happens:**
-- `id` defaults to: `"gpt-5-codex-low"` (config key)
-- `name` defaults to: `"gpt-5-codex-low"` (config key)
-- TUI shows: `"gpt-5-codex-low"` (less friendly)
-- Plugin normalizes: `"gpt-5-codex-low"` → `"gpt-5-codex"` for API
-- **Works perfectly, just less user-friendly**
-
----
-
-### With id Field (Redundant but Harmless)
+Primary settings file:
 
-```json
-{
-  "gpt-5-codex-low": {
-    "id": "gpt-5-codex",
-    "name": "GPT 5 Codex Low (OAuth)",
-    "options": { "reasoningEffort": "low" }
-  }
-}
-```
-
-**What happens:**
-- `id` field is stored but NOT used by OpenAI custom loader
-- Adds documentation value but is technically redundant
-- Works fine, just verbose
-
----
-
-## Summary Table
-
-| Use Case | Which Field? | Example Value |
-|----------|-------------|---------------|
-| **CLI `--model` flag** | Config Key | `openai/gpt-5-codex-low` |
-| **Custom commands** | Config Key | `model: openai/gpt-5-codex-low` |
-| **Agent config** | Config Key | `"model": "openai/gpt-5-codex-low"` |
-| **TUI display** | `name` field | `"GPT 5 Codex Low (OAuth)"` |
-| **Plugin config lookup** | Config Key | `models["gpt-5-codex-low"]` |
-| **AI SDK receives** | Config Key | `body.model = "gpt-5-codex-low"` |
-| **Plugin normalizes** | Transformed | `"gpt-5-codex"` (sent to API) |
-| **TUI persistence** | Config Key | `model_id = "gpt-5-codex-low"` |
-| **Documentation** | `id` field | `"gpt-5-codex"` (base model) |
-| **Model sorting** | `id` field | Used for priority ranking |
-
----
-
-## Key Insight for OpenAI Provider
-
-```
-CONFIG KEY is the real identifier! 👑
-  ├─ Used for selection (CLI, TUI, commands)
-  ├─ Used for persistence (saved to ~/.opencode/tui)
-  ├─ Passed to custom loader (getModel receives this)
-  ├─ Sent to AI SDK (body.model = this)
-  └─ Received by plugin (our plugin sees this)
-
-id field is metadata 📝
-  ├─ Documents base model
-  ├─ Used for sorting
-  └─ NOT sent to AI SDK (custom loader uses config key)
-
-name field is UI sugar 🎨
-  └─ Makes TUI model picker user-friendly
-```
-
----
-
-## Why The Bug Happened
-
-**Old Plugin Logic (Broken):**
-```typescript
-const normalizedModel = normalizeModel(body.model);  // "gpt-5-codex-low" → "gpt-5-codex"
-const modelConfig = getModelConfig(normalizedModel, userConfig);  // Lookup "gpt-5-codex"
-```
-
-**Problem:**
-- Plugin received: `"gpt-5-codex-low"` (config key)
-- Plugin normalized first: `"gpt-5-codex"`
-- Plugin looked up config: `models["gpt-5-codex"]` ❌ NOT FOUND
-- Config key was: `models["gpt-5-codex-low"]`
-- **Result:** Per-model options ignored!
-
-**New Plugin Logic (Fixed):**
-```typescript
-const originalModel = body.model;  // "gpt-5-codex-low" (config key)
-const normalizedModel = normalizeModel(body.model);  // "gpt-5-codex" (for API)
-const modelConfig = getModelConfig(originalModel, userConfig);  // Lookup "gpt-5-codex-low" ✅
-```
-
-**Fix:**
-- Use original value (config key) for config lookup ✅
-- Normalize separately for API call ✅
-- **Result:** Per-model options applied correctly!
-
----
-
-## Testing the Understanding
-
-### Test Case 1: Which model does plugin send to API?
-
-**Config:**
-```json
-{
-  "my-custom-name": {
-    "id": "gpt-5-codex",
-    "name": "My Custom Display Name",
-    "options": { "reasoningEffort": "high" }
-  }
-}
-```
-
-**User runs:** `--model=openai/my-custom-name`
-
-**Question:** What model does plugin send to Codex API?
-
-**Answer:**
-1. Plugin receives: `body.model = "my-custom-name"`
-2. Plugin normalizes: `"my-custom-name"` → `"gpt-5-codex"` (contains "codex")
-3. Plugin sends to API: `"gpt-5-codex"` ✅
-
-**The `id` field is NOT used for this!**
+- `~/.codex/multi-auth/settings.json`
 
----
+Top-level shape:
 
-### Test Case 2: How does TUI know what to display?
-
-**Config:**
 ```json
 {
-  "ugly-key-123": {
-    "id": "gpt-5",
-    "name": "Beautiful Display Name"
-  }
+  "version": 1,
+  "dashboardDisplaySettings": { "...": "..." },
+  "pluginConfig": { "...": "..." }
 }
 ```
 
-**Question:** What does TUI model picker show?
+* * *
 
-**Answer:** `"Beautiful Display Name"` (from `name` field)
+## Plugin-Host Provider Options (`provider.openai.options`)
 
-**If `name` was omitted:** Would show `"ugly-key-123"` (config key)
+Used only for host plugin mode through the host runtime config file.
 
----
+| Key | Type | Common values | Effect |
+| --- | --- | --- | --- |
+| `reasoningEffort` | string | `none\|minimal\|low\|medium\|high\|xhigh` | Reasoning effort hint |
+| `reasoningSummary` | string | `auto\|concise\|detailed` | Summary detail hint |
+| `textVerbosity` | string | `low\|medium\|high` | Text verbosity target |
+| `include` | string[] | `reasoning.encrypted_content` | Extra payload include |
+| `store` | boolean | `false` | Required for stateless backend mode |
 
-### Test Case 3: How does plugin find config?
+* * *
 
-**Config:**
-```json
-{
-  "gpt-5-codex-low": {
-    "id": "gpt-5-codex",
-    "options": { "reasoningEffort": "low" }
-  }
-}
-```
+## `pluginConfig` Fields
 
-**User selects:** `openai/gpt-5-codex-low`
+### Core UX
 
-**Question:** How does plugin find the options?
+| Key | Default |
+| --- | --- |
+| `codexMode` | `true` |
+| `codexTuiV2` | `true` |
+| `codexTuiColorProfile` | `truecolor` |
+| `codexTuiGlyphMode` | `ascii` |
 
-**Answer:**
-1. Plugin receives: `body.model = "gpt-5-codex-low"`
-2. Plugin looks up: `userConfig.models["gpt-5-codex-low"]` ✅
-3. Plugin finds: `{ reasoningEffort: "low" }` ✅
+### Fast Session
 
-**The lookup uses config key, NOT the `id` field!**
+| Key | Default |
+| --- | --- |
+| `fastSession` | `false` |
+| `fastSessionStrategy` | `hybrid` |
+| `fastSessionMaxInputItems` | `30` |
 
----
+### Retry / Fallback / Rotation
 
-## Common Mistakes
+| Key | Default |
+| --- | --- |
+| `retryAllAccountsRateLimited` | `true` |
+| `retryAllAccountsMaxWaitMs` | `0` |
+| `retryAllAccountsMaxRetries` | `Infinity` |
+| `unsupportedCodexPolicy` | `strict` |
+| `fallbackOnUnsupportedCodexModel` | `false` |
+| `fallbackToGpt52OnUnsupportedGpt53` | `true` |
+| `unsupportedCodexFallbackChain` | `{}` |
 
-### ❌ Using id as Config Key
+### Token / Recovery
 
-```json
-{
-  "gpt-5-codex": {  // ❌ Can't have multiple variants
-    "id": "gpt-5-codex"
-  }
-}
-```
+| Key | Default |
+| --- | --- |
+| `tokenRefreshSkewMs` | `60000` |
+| `sessionRecovery` | `true` |
+| `autoResume` | `true` |
+| `proactiveRefreshGuardian` | `true` |
+| `proactiveRefreshIntervalMs` | `60000` |
+| `proactiveRefreshBufferMs` | `300000` |
 
-### ❌ Thinking id Controls Plugin Lookup
-
-```json
-{
-  "my-model": {
-    "id": "gpt-5-codex-low",  // ❌ Plugin won't look up by this!
-    "options": { ... }
-  }
-}
-```
+### Storage / Sync
 
-**Plugin looks up by:** `"my-model"` (config key), not `"gpt-5-codex-low"` (id)
+| Key | Default |
+| --- | --- |
+| `perProjectAccounts` | `true` |
+| `storageBackupEnabled` | `true` |
+| `liveAccountSync` | `true` |
+| `liveAccountSyncDebounceMs` | `250` |
+| `liveAccountSyncPollMs` | `2000` |
 
-### ❌ Forgetting name Field
+### Session Affinity
 
-```json
-{
-  "gpt-5-codex-low": {
-    "id": "gpt-5-codex"
-    // Missing: "name" field
-  }
-}
-```
+| Key | Default |
+| --- | --- |
+| `sessionAffinity` | `true` |
+| `sessionAffinityTtlMs` | `1200000` |
+| `sessionAffinityMaxEntries` | `512` |
 
-**Result:** TUI shows `"gpt-5-codex-low"` (works but less friendly)
+### Reliability / Timeout / Probe
 
----
+| Key | Default |
+| --- | --- |
+| `parallelProbing` | `false` |
+| `parallelProbingMaxConcurrency` | `2` |
+| `emptyResponseMaxRetries` | `2` |
+| `emptyResponseRetryDelayMs` | `1000` |
+| `pidOffsetEnabled` | `false` |
+| `fetchTimeoutMs` | `60000` |
+| `streamStallTimeoutMs` | `45000` |
+| `networkErrorCooldownMs` | `6000` |
+| `serverErrorCooldownMs` | `4000` |
 
-## See Also
+### Quota Deferral
 
-- [CONFIG_FLOW.md](./CONFIG_FLOW.md) - Complete config system guide
-- [ARCHITECTURE.md](./ARCHITECTURE.md) - Technical architecture
-- [TESTING.md](./TESTING.md) - Testing strategy and verification guidance
+| Key | Default |
+| --- | --- |
+| `preemptiveQuotaEnabled` | `true` |
+| `preemptiveQuotaRemainingPercent5h` | `5` |
+| `preemptiveQuotaRemainingPercent7d` | `5` |
+| `preemptiveQuotaMaxDeferralMs` | `7200000` |
+
+### Notifications
+
+| Key | Default |
+| --- | --- |
+| `rateLimitToastDebounceMs` | `60000` |
+| `toastDurationMs` | `5000` |
+
+* * *
+
+## `dashboardDisplaySettings` Fields
+
+### General Display
+
+| Key | Default |
+| --- | --- |
+| `showPerAccountRows` | `true` |
+| `showQuotaDetails` | `true` |
+| `showForecastReasons` | `true` |
+| `showRecommendations` | `true` |
+| `showLiveProbeNotes` | `true` |
+
+### Result Screen Behavior
+
+| Key | Default |
+| --- | --- |
+| `actionAutoReturnMs` | `2000` |
+| `actionPauseOnKey` | `true` |
+
+### Dashboard Fetch and Sort
+
+| Key | Default |
+| --- | --- |
+| `menuAutoFetchLimits` | `true` |
+| `menuQuotaTtlMs` | `300000` |
+| `menuSortEnabled` | `true` |
+| `menuSortMode` | `ready-first` |
+| `menuSortPinCurrent` | `false` |
+| `menuSortQuickSwitchVisibleRow` | `true` |
+
+### Account Row Content
+
+| Key | Default |
+| --- | --- |
+| `menuShowStatusBadge` | `true` |
+| `menuShowCurrentBadge` | `true` |
+| `menuShowLastUsed` | `true` |
+| `menuShowQuotaSummary` | `true` |
+| `menuShowQuotaCooldown` | `true` |
+| `menuShowFetchStatus` | `true` |
+| `menuShowDetailsForUnselectedRows` | `false` |
+| `menuStatuslineFields` | `last-used, limits, status` |
+
+### Visual Style
+
+| Key | Default |
+| --- | --- |
+| `uiThemePreset` | `green` |
+| `uiAccentColor` | `green` |
+| `menuLayoutMode` | `compact-details` |
+| `menuFocusStyle` | `row-invert` |
+| `menuHighlightCurrentRow` | `true` |
+
+* * *
+
+## Environment Overrides
+
+| Variable | Purpose |
+| --- | --- |
+| `CODEX_MULTI_AUTH_DIR` | Custom root for settings/accounts/cache/logs |
+| `CODEX_MULTI_AUTH_CONFIG_PATH` | Alternate config file input |
+| `CODEX_MODE` | Toggle Codex mode |
+| `CODEX_TUI_V2` | Toggle TUI v2 |
+| `CODEX_TUI_COLOR_PROFILE` | TUI color profile |
+| `CODEX_TUI_GLYPHS` | TUI glyph mode |
+| `CODEX_AUTH_FETCH_TIMEOUT_MS` | Request timeout override |
+| `CODEX_AUTH_STREAM_STALL_TIMEOUT_MS` | Stream stall timeout override |
+| `CODEX_MULTI_AUTH_SYNC_CODEX_CLI` | Toggle Codex CLI state sync |
+| `CODEX_MULTI_AUTH_REAL_CODEX_BIN` | Force official Codex binary path |
+| `CODEX_MULTI_AUTH_BYPASS` | Bypass local auth handling |
+
+* * *
+
+## Concurrency and Windows Notes
+
+- Storage writes use temp-file + rename semantics; Windows may surface transient `EPERM`/`EBUSY` during rename.
+- Cross-process refresh coordination relies on lease/state files; avoid manually editing those files while the CLI is running.
+- Live account sync combines `fs.watch` with polling fallback to handle Windows watcher edge cases.
+- Backup/WAL artifacts may exist briefly during writes and recovery; they are part of normal safety behavior.
+
+* * *
+
+## Related
+
+- [CONFIG_FLOW.md](CONFIG_FLOW.md)
+- [ARCHITECTURE.md](ARCHITECTURE.md)
+- [../reference/settings.md](../reference/settings.md)
diff --git a/docs/development/CONFIG_FLOW.md b/docs/development/CONFIG_FLOW.md
index 7e40eef7..524942ef 100644
--- a/docs/development/CONFIG_FLOW.md
+++ b/docs/development/CONFIG_FLOW.md
@@ -1,410 +1,114 @@
-# OpenCode Config Flow: Complete Guide
+# Configuration Flow
 
-This document explains how OpenCode configuration flows from user files through the plugin system to the Codex API.
+How configuration is resolved at runtime from files, env, and defaults.
 
-## Table of Contents
-- [Config Loading Order](#config-loading-order)
-- [Provider Options Flow](#provider-options-flow)
-- [Model Selection & Persistence](#model-selection--persistence)
-- [Plugin Configuration](#plugin-configuration)
-- [Examples](#examples)
-- [Best Practices](#best-practices)
+* * *
 
----
+## 1) Root Directory Resolution
 
-## Config Loading Order
+Runtime root priority:
 
-OpenCode loads and merges configuration from multiple sources in this order (**last wins**):
+1. `CODEX_MULTI_AUTH_DIR`
+2. `CODEX_HOME/multi-auth`
+3. Detected fallback roots with existing storage signals
+4. Legacy path fallback only when signals exist
 
-### 1. Global Config
-```
-~/.opencode/config.json
-~/.opencode/opencode.json
-~/.opencode/opencode.jsonc
-```
-
-### 2. Project Configs (traversed upward from cwd)
-```
-<project>/.opencode/opencode.json
-<parent>/.opencode/opencode.json
-... (up to worktree root)
-```
-
-### 3. Custom Config (via flags)
-```bash
-OPENCODE_CONFIG=/path/to/config.json opencode
-# or
-OPENCODE_CONFIG_CONTENT='{"model":"openai/gpt-5"}' opencode
-```
-
-### 4. Auth Configs
-```
-# From .well-known/opencode endpoints (for OAuth providers)
-https://auth.example.com/.well-known/opencode
-```
-
-**Source**: `tmp/opencode/packages/opencode/src/config/config.ts:26-51`
-
----
-
-## Provider Options Flow
-
-Options are merged at multiple stages before reaching the plugin:
-
-### Stage 1: Database Defaults
-Models.dev provides baseline capabilities for each provider/model.
-
-### Stage 2: Environment Variables
-```bash
-export OPENAI_API_KEY="sk-..."
-```
+Canonical target is `~/.codex/multi-auth` when no override is set.
 
-### Stage 3: Custom Loaders
-Plugins can inject options via the `loader()` function.
-
-### Stage 4: User Config (HIGHEST PRIORITY)
-```json
-{
-  "provider": {
-    "openai": {
-      "options": {
-        "reasoningEffort": "medium",
-        "textVerbosity": "low"
-      }
-    }
-  }
-}
-```
+* * *
 
-**Result**: User config overrides everything else.
-
-**Source**: `tmp/opencode/packages/opencode/src/provider/provider.ts:236-339`
-
----
-
-## Model Selection & Persistence
-
-### Display Names vs Internal IDs
-
-**Your Config** (`config/opencode-legacy.json`):
-```json
-{
-  "provider": {
-    "openai": {
-      "models": {
-        "gpt-5-codex-medium": {
-          "name": "GPT 5 Codex Medium (OAuth)",
-          "limit": {
-            "context": 272000,
-            "output": 128000
-          },
-          "options": {
-            "reasoningEffort": "medium",
-            "reasoningSummary": "auto",
-            "textVerbosity": "medium",
-            "include": [
-              "reasoning.encrypted_content"
-            ],
-            "store": false
-          }
-        }
-      }
-    }
-  }
-}
-```
+## 2) Unified Settings Resolution
 
-**What OpenCode Uses**:
-- **UI Display**: "GPT 5 Codex Medium (OAuth)" ✅
-- **Persistence**: `provider_id: "openai"` + `model_id: "gpt-5-codex-medium"` ✅
-- **Plugin lookup**: `models["gpt-5-codex-medium"]` → used to build Codex request ✅
+`settings.json` is read for:
 
-### TUI Persistence
+- `dashboardDisplaySettings`
+- `pluginConfig`
 
-The TUI stores recently used models in `~/.opencode/tui`:
+If legacy config exists, compatibility load and migration path still apply.
 
-```toml
-[[recently_used_models]]
-provider_id = "openai"
-model_id = "gpt-5-codex"
-last_used = 2025-10-12T10:30:00Z
-```
+* * *
 
-**Key Point**: Custom display names are **UI-only**. The underlying `id` field is what gets persisted and sent to APIs.
+## 3) Runtime Value Precedence
 
-**Source**: `tmp/opencode/packages/tui/internal/app/state.go:54-79`
+For plugin runtime values:
 
----
+1. Environment override
+2. `CODEX_MULTI_AUTH_CONFIG_PATH` (when set)
+3. Unified/compat config value
+4. Hardcoded default in `DEFAULT_PLUGIN_CONFIG`
 
-## Plugin Configuration
+For dashboard display values:
 
-### How This Plugin Receives Config
+1. Persisted `dashboardDisplaySettings`
+2. Normalization + fallback defaults
 
-**Plugin Entry Point** (`index.ts:64-86`):
-```typescript
-async loader(getAuth: () => Promise<Auth>, provider: unknown) {
-  const providerConfig = provider as {
-    options?: Record<string, unknown>;
-    models?: UserConfig["models"]
-  };
+* * *
 
-  const userConfig: UserConfig = {
-    global: providerConfig?.options || {},  // Global options
-    models: providerConfig?.models || {},   // Per-model options
-  };
+## 4) Account Storage Path Flow
 
-  // ... use userConfig in custom fetch()
-}
-```
+1. Resolve root directory.
+2. Use global accounts file by default.
+3. If project-scoped mode is active, use project namespaced path under root.
+4. Attempt legacy project-file migration when applicable.
 
-### Config Structure
-
-```typescript
-type UserConfig = {
-  global: {
-    // Applied to ALL models
-    reasoningEffort?: "minimal" | "low" | "medium" | "high";
-    textVerbosity?: "low" | "medium" | "high";
-    include?: string[];
-  };
-  models: {
-    [modelName: string]: {
-      options?: {
-        // Override global for specific model
-        reasoningEffort?: "minimal" | "low" | "medium" | "high";
-        textVerbosity?: "low" | "medium" | "high";
-      };
-    };
-  };
-};
-```
+* * *
 
-### Option Precedence
+## 5) Command Routing Flow
 
-For a given model, options are merged:
-1. **Global options** (`provider.openai.options`)
-2. **Model-specific options** (`provider.openai.models[modelName].options`) ← WINS
+1. Wrapper receives `codex`, `codex-multi-auth`, or `codex-multi-auth-opencode-install`.
+2. Normalize alias args (`multi auth`, `multi-auth`, `multiauth`).
+3. If command belongs to auth manager scope, run local manager.
+4. Otherwise forward invocation to official Codex CLI binary.
+5. Direct `codex-multi-auth ...` and install wrapper invocations route through the same routing entrypoint.
 
-**Implementation**: `lib/request/request-transformer.ts:getModelConfig()`
+* * *
 
----
+## 6) Request Handling Flow (Plugin)
 
-## Examples
+1. Transform request for Codex backend compatibility.
+2. Resolve account candidate set (health, cooldown, quota, affinity).
+3. Execute request with timeout/retry policy.
+4. Apply failover/rotation/cooldown decisions.
+5. Persist account/cache/session updates.
 
-### Example 1: Global Options Only
-```json
-{
-  "plugin": ["codex-multi-auth"],
-  "provider": {
-    "openai": {
-      "options": {
-        "reasoningEffort": "medium",
-        "textVerbosity": "medium",
-        "include": ["reasoning.encrypted_content"]
-      }
-    }
-  }
-}
-```
+* * *
 
-**Result**: All OpenAI models use these options.
-
-### Example 2: Per-Model Override
-```json
-{
-  "plugin": ["codex-multi-auth"],
-  "provider": {
-    "openai": {
-      "options": {
-        "reasoningEffort": "medium",
-        "textVerbosity": "medium"
-      },
-      "models": {
-        "gpt-5-codex-high": {
-          "name": "GPT 5 Codex High (OAuth)",
-          "options": {
-            "reasoningEffort": "high",
-            "reasoningSummary": "detailed"
-          }
-        },
-        "gpt-5-nano": {
-          "name": "GPT 5 Nano (OAuth)",
-          "options": {
-            "reasoningEffort": "minimal",
-            "textVerbosity": "low"
-          }
-        }
-      }
-    }
-  }
-}
-```
+## 7) Unsupported Model / Entitlement Flow
 
-**Result**:
-- `gpt-5-codex-high` uses `reasoningEffort: "high"` (overridden) + `textVerbosity: "medium"` (from global)
-- `gpt-5-nano` uses `reasoningEffort: "minimal"` + `textVerbosity: "low"` (both overridden)
-
-### Example 3: Full Configuration
-```json
-{
-  "$schema": "https://opencode.ai/config.json",
-  "plugin": ["codex-multi-auth"],
-  "model": "openai/gpt-5-codex-medium",
-  "provider": {
-    "openai": {
-      "options": {
-        "reasoningEffort": "medium",
-        "reasoningSummary": "auto",
-        "textVerbosity": "medium",
-        "include": ["reasoning.encrypted_content"]
-      },
-      "models": {
-        "gpt-5-codex-low": {
-          "name": "GPT 5 Codex Low (OAuth)",
-          "options": {
-            "reasoningEffort": "low"
-          }
-        },
-        "gpt-5-codex-high": {
-          "name": "GPT 5 Codex High (OAuth)",
-          "options": {
-            "reasoningEffort": "high",
-            "reasoningSummary": "detailed"
-          }
-        }
-      }
-    }
-  }
-}
-```
+1. Detect unsupported model or entitlement failures.
+2. Record in entitlement cache.
+3. Apply capability penalties for account/model pair.
+4. Use fallback model policy if enabled.
+5. Re-evaluate account scoring and retry path.
 
----
-
-## Best Practices
-
-### 1. Use Per-Model Options for Variants
-Instead of duplicating global options, override only what's different:
-
-❌ **Bad**:
-```json
-{
-  "models": {
-    "gpt-5-low": {
-      "id": "gpt-5",
-      "options": {
-        "reasoningEffort": "low",
-        "textVerbosity": "low",
-        "include": ["reasoning.encrypted_content"]
-      }
-    },
-    "gpt-5-high": {
-      "id": "gpt-5",
-      "options": {
-        "reasoningEffort": "high",
-        "textVerbosity": "high",
-        "include": ["reasoning.encrypted_content"]
-      }
-    }
-  }
-}
-```
+* * *
 
-✅ **Good**:
-```json
-{
-  "options": {
-    "include": ["reasoning.encrypted_content"]
-  },
-  "models": {
-    "gpt-5-low": {
-      "id": "gpt-5",
-      "options": {
-        "reasoningEffort": "low",
-        "textVerbosity": "low"
-      }
-    },
-    "gpt-5-high": {
-      "id": "gpt-5",
-      "options": {
-        "reasoningEffort": "high",
-        "textVerbosity": "high"
-      }
-    }
-  }
-}
-```
+## 8) Live Runtime Sync Flow
 
-### 2. Keep Display Names Meaningful
-Custom model names help you remember what each variant does:
-
-```json
-{
-  "models": {
-    "GPT 5 Codex - Fast & Cheap": {
-      "id": "gpt-5-codex",
-      "options": { "reasoningEffort": "low" }
-    },
-    "GPT 5 Codex - Balanced": {
-      "id": "gpt-5-codex",
-      "options": { "reasoningEffort": "medium" }
-    },
-    "GPT 5 Codex - Max Quality": {
-      "id": "gpt-5-codex",
-      "options": { "reasoningEffort": "high" }
-    }
-  }
-}
-```
+1. File watcher detects account-file updates.
+2. Debounce and reload in-memory account manager.
+3. Session affinity and guardian processes continue with updated state.
 
-### 3. Set Defaults at Global Level
-Most common settings should be global:
-
-```json
-{
-  "options": {
-    "reasoningEffort": "medium",
-    "reasoningSummary": "auto",
-    "textVerbosity": "medium",
-    "include": ["reasoning.encrypted_content"]
-  }
-}
-```
+* * *
 
-### 4. Use Config Files, Not Environment Variables
-While you can set `CODEX_MODE=0` to disable the bridge prompt, it's better to document such settings in config files:
+## 9) Debugging Effective Config
 
-❌ **Bad**: `CODEX_MODE=0 opencode`
+Use:
 
-✅ **Good**: Create `~/.opencode/codex-multi-auth-config.json`:
-```json
-{
-  "codexMode": false
-}
+```bash
+codex auth status
+codex auth report --json
 ```
 
----
-
-## Troubleshooting
-
-### Config Not Being Applied
-1. Check config file syntax with `jq . < config.json`
-2. Verify config file location (use absolute paths)
-3. Check OpenCode logs for config load errors
-4. Use `OPENCODE_CONFIG_CONTENT` to test minimal configs
+Check files:
 
-### Model Not Persisting
-1. TUI remembers the `id` field, not the display name
-2. Check `~/.opencode/tui` for recently used models
-3. Verify your config has the correct `id` field
+- `~/.codex/multi-auth/settings.json`
+- `~/.codex/multi-auth/openai-codex-accounts.json`
 
-### Options Not Taking Effect
-1. Model-specific options override global options
-2. Plugin receives merged config from OpenCode
-3. Add debug logging to verify what plugin receives
+* * *
 
----
+## Related
 
-## See Also
-- [ARCHITECTURE.md](./ARCHITECTURE.md) - Plugin architecture and design decisions
-- [OpenCode Config Schema](https://opencode.ai/config.json) - Official schema
-- [Models.dev](https://models.dev) - Model capability database
+- [CONFIG_FIELDS.md](CONFIG_FIELDS.md)
+- [ARCHITECTURE.md](ARCHITECTURE.md)
+- [../configuration.md](../configuration.md)
diff --git a/docs/development/REPOSITORY_SCOPE.md b/docs/development/REPOSITORY_SCOPE.md
index f0fff027..74dba997 100644
--- a/docs/development/REPOSITORY_SCOPE.md
+++ b/docs/development/REPOSITORY_SCOPE.md
@@ -1,71 +1,80 @@
 # Repository Scope Map
 
-This document is the canonical map of repository scope, file ownership, and extension points.
-
-## Top-Level Scope
-
-| Path | Purpose | Source of Truth |
-| --- | --- | --- |
-| `.github/` | CI workflows, issue templates, automation policy | Yes |
-| `.husky/` | Local git hook entrypoints | Yes |
-| `index.ts` | Plugin entrypoint, provider hook wiring, fetch orchestration, tool registration | Yes |
-| `lib/` | Core runtime logic (auth, rotation, request/response transforms, storage, UI, prompts) | Yes |
-| `test/` | Vitest unit/integration/property coverage | Yes |
-| `scripts/` | Build/install/helper scripts | Yes |
-| `config/` | Copy-paste OpenCode config templates | Yes |
-| `docs/` | User + developer documentation | Yes |
-| `assets/` | Static project assets | Yes |
-| `bench/` | Benchmark fixtures and benchmark tooling | Yes |
-| `package.json` | Runtime metadata, scripts, dependency contracts | Yes |
-| `eslint.config.js`, `tsconfig.json`, `vitest.config.ts`, `biome.jsonc` | Lint/type/test/toolchain behavior | Yes |
-| `CHANGELOG.md`, `CONTRIBUTING.md`, `SECURITY.md` | Governance, contribution, release and security policy | Yes |
-| `dist/` | Build output generated by `npm run build` | No (generated) |
-
-## Core Module Ownership
-
-| Area | Main Path(s) | Responsibility |
-| --- | --- | --- |
-| Plugin orchestration | `index.ts` | Request pipeline, routing, retries, tool surface |
-| OAuth + token lifecycle | `lib/auth/auth.ts`, `lib/auth/server.ts`, `lib/refresh-queue.ts` | Login flow, callback handling, refresh control |
-| Multi-account rotation | `lib/accounts.ts`, `lib/rotation.ts`, `lib/health.ts`, `lib/circuit-breaker.ts` | Account selection, health scoring, failover |
-| Rate limits and retries | `lib/accounts/rate-limits.ts`, `lib/request/rate-limit-backoff.ts` | Quota awareness, wait/retry logic |
-| Request transformation | `lib/request/request-transformer.ts`, `lib/request/helpers/model-map.ts` | OpenCode request normalization to Codex backend format |
-| Fetch + error mapping | `lib/request/fetch-helpers.ts` | Headers, timeout handling, backend error normalization |
-| Stream/SSE handling | `lib/request/response-handler.ts` | Streaming parsing and terminal response assembly |
-| Prompt bridge | `lib/prompts/codex.ts`, `lib/prompts/codex-opencode-bridge.ts`, `lib/prompts/opencode-codex.ts` | Prompt templates, codex bridge instructions, sync/cache |
-| Config loading | `lib/config.ts`, `lib/schemas.ts`, `config/*.json` | Plugin options, schema validation, templates |
-| Storage and migrations | `lib/storage.ts`, `lib/storage/paths.ts`, `lib/storage/migrations.ts` | Account persistence, path resolution, schema upgrades |
-| Recovery/session state | `lib/recovery/` | Conversation recovery state and persistence |
-| Codex CLI sync | `lib/codex-cli/` | Codex CLI account/state synchronization |
-| Tooling | `lib/tools/hashline-tools.ts`, `lib/table-formatter.ts` | User-facing plugin tools and CLI display |
+Ownership map for source paths and documentation paths.
 
-## AGENTS Scope Hierarchy
+* * *
+
+## Top-Level Map
+
+| Path | Purpose |
+| --- | --- |
+| `index.ts` | Plugin-host runtime entry |
+| `lib/` | Core runtime, auth, storage, UI, policies |
+| `scripts/` | CLI wrappers and helper scripts |
+| `docs/` | User docs + references + maintainer docs |
+| `test/` | Unit/integration/property tests |
+| `config/` | Plugin-host config examples |
+| `assets/` | Static project assets |
+| `dist/` | Generated build output (do not edit directly) |
+
+* * *
 
-AGENTS files apply hierarchically. Deeper AGENTS files override parent rules for their subtree.
+## Core Runtime Ownership
 
-| AGENTS file | Scope |
+| Area | Primary files |
 | --- | --- |
-| `AGENTS.md` | Entire repository |
-| `lib/AGENTS.md` | `lib/**` |
-| `test/AGENTS.md` | `test/**` |
+| CLI auth manager | `lib/codex-manager.ts` |
+| OAuth flow/server | `lib/auth/*` |
+| Storage and paths | `lib/storage.ts`, `lib/storage/paths.ts`, `lib/runtime-paths.ts` |
+| Unified settings | `lib/unified-settings.ts`, `lib/dashboard-settings.ts`, `lib/config.ts` |
+| Account runtime | `lib/accounts.ts`, `lib/rotation.ts`, `lib/forecast.ts` |
+| Quota runtime | `lib/quota-probe.ts`, `lib/quota-cache.ts`, `lib/preemptive-quota-scheduler.ts` |
+| Resilience | `lib/live-account-sync.ts`, `lib/session-affinity.ts`, `lib/refresh-guardian.ts`, `lib/refresh-lease.ts` |
+| Request pipeline | `lib/request/*`, `index.ts` |
+| UI system | `lib/ui/*` |
 
-## Generated/Local Artifacts (Out of Scope for Source Edits)
+* * *
 
-| Path Pattern | Notes |
+## Documentation Ownership
+
+| Area | Files |
 | --- | --- |
-| `dist/**` | Generated build output, do not edit by hand |
-| `.tmp*`, `tmp*` | Local scratch/release artifacts |
-| `.omx/**`, `.sisyphus/**` | Local agent/runtime state |
-| `coverage/**` | Generated test coverage output |
-| `node_modules/**` | Installed dependencies |
-
-## Extension Points for New Work
-
-Use this checklist when adding a new feature (for example a Codex CLI-focused config/plugin extension).
-
-1. Update plugin behavior and registration in `index.ts`.
-2. Add/adjust option parsing in `lib/config.ts` and validation in `lib/schemas.ts`.
-3. Update request transform and model mapping in `lib/request/request-transformer.ts` and `lib/request/helpers/model-map.ts`.
-4. Add prompt behavior in `lib/prompts/` when bridge instructions change.
-5. Add tests in `test/` for success path, edge cases, and regressions.
-6. Update user docs (`README.md`, `docs/configuration.md`, `docs/getting-started.md`) and developer docs (`docs/development/*.md`).
+| User docs | `docs/getting-started.md`, `docs/configuration.md`, `docs/troubleshooting.md`, `docs/features.md`, `docs/upgrade.md`, `docs/privacy.md` |
+| Reference docs | `docs/reference/*` |
+| Maintainer docs | `docs/development/*`, `docs/DOCUMENTATION.md` |
+| Style and consistency | `docs/STYLE_GUIDE.md` |
+
+* * *
+
+## AGENTS Scope Hierarchy
+
+Within this repo:
+
+1. `AGENTS.md` (root scope)
+2. `lib/AGENTS.md` for `lib/**`
+3. `test/AGENTS.md` for `test/**`
+
+Deeper AGENTS files override higher-level guidance for their subtree.
+
+* * *
+
+## Generated or Local Artifacts (Not Source)
+
+- `dist/`
+- `.tmp*` directories
+- local caches/logs under runtime roots
+
+Do not treat these as primary implementation sources.
+
+* * *
+
+## Feature Placement Checklist
+
+When adding a new feature:
+
+1. Implement runtime/module code in `lib/`.
+2. Add/extend tests in `test/`.
+3. Update user docs (`docs/features.md` + relevant guides).
+4. Update references if command/setting/path changed.
+5. Update architecture/config flow docs for cross-cutting behavior.
+6. Update `docs/upgrade.md` and any npm-script references when command flow/build steps changed.
diff --git a/docs/development/TESTING.md b/docs/development/TESTING.md
index e445316e..9292b906 100644
--- a/docs/development/TESTING.md
+++ b/docs/development/TESTING.md
@@ -1,763 +1,112 @@
-# Complete Test Scenarios
+# Testing Guide
 
-Comprehensive testing matrix for all config scenarios and backwards compatibility.
+Testing strategy and release gate for runtime, CLI, and docs consistency.
 
-## Test Scenarios Matrix
+* * *
 
-### Scenario 1: Default OpenCode Models (No Custom Config)
+## Test Stack
 
-**Config:**
-```json
-{
-  "plugin": ["codex-multi-auth"]
-}
-```
-
-**Available Models:** (from OpenCode's models.dev database)
-- `gpt-5`
-- `gpt-5-codex`
-- `gpt-5-mini`
-- `gpt-5-nano`
-
-**Test Cases:**
-
-| User Selects | Plugin Receives | Normalizes To | Config Lookup | API Receives | Result |
-|--------------|-----------------|---------------|---------------|--------------|--------|
-| `openai/gpt-5` | `"gpt-5"` | `"gpt-5"` | `models["gpt-5"]` → undefined | `"gpt-5"` | ✅ Uses global options |
-| `openai/gpt-5-codex` | `"gpt-5-codex"` | `"gpt-5-codex"` | `models["gpt-5-codex"]` → undefined | `"gpt-5-codex"` | ✅ Uses global options |
-| `openai/gpt-5-mini` | `"gpt-5-mini"` | `"gpt-5"` | `models["gpt-5-mini"]` → undefined | `"gpt-5"` | ✅ Uses global options |
-| `openai/gpt-5-nano` | `"gpt-5-nano"` | `"gpt-5"` | `models["gpt-5-nano"]` → undefined | `"gpt-5"` | ✅ Uses global options |
-
-**Expected Behavior:**
-- ✅ All models work with global options
-- ✅ Normalized correctly for API
-- ✅ No errors
-
----
-
-### Scenario 2: Custom Config with Preset Names (New Style)
-
-**Config:**
-```json
-{
-  "plugin": ["codex-multi-auth"],
-  "provider": {
-    "openai": {
-      "options": {
-        "reasoningEffort": "medium"
-      },
-      "models": {
-        "gpt-5-codex-low": {
-          "name": "GPT 5 Codex Low (OAuth)",
-          "options": { "reasoningEffort": "low" }
-        },
-        "gpt-5-codex-high": {
-          "name": "GPT 5 Codex High (OAuth)",
-          "options": { "reasoningEffort": "high" }
-        }
-      }
-    }
-  }
-}
-```
-
-**Test Cases:**
-
-| User Selects | Plugin Receives | Config Lookup | Resolved Options | API Receives | Result |
-|--------------|-----------------|---------------|------------------|--------------|--------|
-| `openai/gpt-5-codex-low` | `"gpt-5-codex-low"` | Found ✅ | `{ reasoningEffort: "low" }` | `"gpt-5-codex"` | ✅ Per-model |
-| `openai/gpt-5-codex-high` | `"gpt-5-codex-high"` | Found ✅ | `{ reasoningEffort: "high" }` | `"gpt-5-codex"` | ✅ Per-model |
-| `openai/gpt-5-codex` | `"gpt-5-codex"` | Not found | `{ reasoningEffort: "medium" }` | `"gpt-5-codex"` | ✅ Global |
-
-**Expected Behavior:**
-- ✅ Custom variants use per-model options
-- ✅ Default `gpt-5-codex` uses global options
-- ✅ Both normalize to `"gpt-5-codex"` for API
-
----
-
-### Scenario 3: Old Config (Backwards Compatibility)
-
-**Config:**
-```json
-{
-  "plugin": ["codex-multi-auth"],
-  "provider": {
-    "openai": {
-      "options": {
-        "reasoningEffort": "medium"
-      },
-      "models": {
-        "GPT 5 Codex Low (ChatGPT Subscription)": {
-          "id": "gpt-5-codex",
-          "options": { "reasoningEffort": "low" }
-        }
-      }
-    }
-  }
-}
-```
-
-**Test Cases:**
-
-| User Selects | Plugin Receives | Config Lookup | Resolved Options | API Receives | Result |
-|--------------|-----------------|---------------|------------------|--------------|--------|
-| `openai/GPT 5 Codex Low (ChatGPT Subscription)` | `"GPT 5 Codex Low (ChatGPT Subscription)"` | Found ✅ | `{ reasoningEffort: "low" }` | `"gpt-5-codex"` | ✅ Per-model |
-
-**Expected Behavior:**
-- ✅ Old config keys still work
-- ✅ Per-model options applied correctly
-- ✅ Normalizes correctly for API
-
----
-
-### Scenario 4: Mixed Config (Default + Custom)
-
-**Config:**
-```json
-{
-  "plugin": ["codex-multi-auth"],
-  "provider": {
-    "openai": {
-      "models": {
-        "gpt-5-codex-low": {
-          "name": "GPT 5 Codex Low (OAuth)",
-          "options": { "reasoningEffort": "low" }
-        }
-      }
-    }
-  }
-}
-```
-
-**Available Models:**
-- `gpt-5-codex-low` (custom)
-- `gpt-5-codex` (default from models.dev)
-- `gpt-5` (default from models.dev)
-
-**Test Cases:**
-
-| User Selects | Config Lookup | Uses Options | Result |
-|--------------|---------------|--------------|--------|
-| `openai/gpt-5-codex-low` | Found ✅ | Per-model | ✅ Custom config |
-| `openai/gpt-5-codex` | Not found | Global | ✅ Default model |
-| `openai/gpt-5` | Not found | Global | ✅ Default model |
-
-**Expected Behavior:**
-- ✅ Custom variants use per-model options
-- ✅ Default models use global options
-- ✅ Both types coexist peacefully
-
----
-
-### Scenario 5: Edge Cases
-
-#### 5a: Model Name with Uppercase
-
-**Config:**
-```json
-{
-  "models": {
-    "GPT-5-CODEX-HIGH": {
-      "options": { "reasoningEffort": "high" }
-    }
-  }
-}
-```
-
-**Test:**
-```
-User selects: openai/GPT-5-CODEX-HIGH
-Plugin receives: "GPT-5-CODEX-HIGH"
-normalizeModel: "GPT-5-CODEX-HIGH" → "gpt-5-codex" ✅ (includes "codex")
-Config lookup: models["GPT-5-CODEX-HIGH"] → Found ✅
-API receives: "gpt-5-codex" ✅
-```
-
-**Result:** ✅ Works (case-insensitive includes())
-
----
-
-#### 5b: Model Name with Special Characters
-
-**Config:**
-```json
-{
-  "models": {
-    "my-gpt5-codex-variant": {
-      "options": { "reasoningEffort": "high" }
-    }
-  }
-}
-```
-
-**Test:**
-```
-User selects: openai/my-gpt5-codex-variant
-Plugin receives: "my-gpt5-codex-variant"
-normalizeModel: "my-gpt5-codex-variant" → "gpt-5-codex" ✅ (includes "codex")
-Config lookup: models["my-gpt5-codex-variant"] → Found ✅
-API receives: "gpt-5-codex" ✅
-```
-
-**Result:** ✅ Works (normalization handles it)
-
----
-
-#### 5c: No Config, No Model Specified
-
-**Config:**
-```json
-{
-  "plugin": ["codex-multi-auth"]
-}
-```
-
-**Test:**
-```
-User selects: (none - uses OpenCode default)
-Plugin receives: undefined or default from OpenCode
-normalizeModel: undefined → "gpt-5" ✅ (fallback)
-Config lookup: models[undefined] → undefined
-API receives: "gpt-5" ✅
-```
-
-**Result:** ✅ Works (safe fallback)
-
----
-
-#### 5d: Only `gpt-5` in Name (No `codex`)
-
-**Config:**
-```json
-{
-  "models": {
-    "my-gpt-5-variant": {
-      "options": { "reasoningEffort": "high" }
-    }
-  }
-}
-```
-
-**Test:**
-```
-User selects: openai/my-gpt-5-variant
-Plugin receives: "my-gpt-5-variant"
-normalizeModel: "my-gpt-5-variant" → "gpt-5" ✅ (includes "gpt-5", not "codex")
-Config lookup: models["my-gpt-5-variant"] → Found ✅
-API receives: "gpt-5" ✅
-```
-
-**Result:** ✅ Works (correct model selected)
-
----
-
-### Scenario 6: Multi-Turn Conversation (store:false Test)
-
-**Config:** Any
-
-**Test Sequence:**
-```
-Turn 1: > write hello to test.txt
-Turn 2: > read the file
-Turn 3: > what did you write?
-Turn 4: > now delete it
-```
-
-**What Plugin Should Do:**
-
-| Turn | Input Has IDs? | Filter Result | Encrypted Content | Result |
-|------|---------------|---------------|-------------------|--------|
-| 1 | No | No filtering needed | Received in response | ✅ Works |
-| 2 | Yes (from Turn 1) | ALL removed ✅ | Sent back in request | ✅ Works |
-| 3 | Yes (from Turn 1-2) | ALL removed ✅ | Sent back in request | ✅ Works |
-| 4 | Yes (from Turn 1-3) | ALL removed ✅ | Sent back in request | ✅ Works |
-
-**Expected Behavior:**
-- ✅ No "item not found" errors on any turn
-- ✅ Context preserved via encrypted reasoning
-- ✅ Debug log shows: "Successfully removed all X message IDs"
-
----
-
-## Backwards Compatibility Testing
-
-### Test Matrix
-
-| Plugin Version | Config Format | Expected Result |
-|----------------|--------------|-----------------|
-| **Old (<2.1.2)** | Long names + id | ❌ Per-model options broken, ID errors |
-| **Old (<2.1.2)** | Short names | ❌ Per-model options broken, ID errors |
-| **New (2.1.2+)** | Long names + id | ✅ **ALL FIXED** |
-| **New (2.1.2+)** | Short names | ✅ **ALL FIXED** |
-| **New (2.1.2+)** | Short names (no id) | ✅ **OPTIMAL** |
-
-### Backwards Compatibility Tests
-
-#### Test 1: Old Plugin User Upgrades
-
-**Before (Plugin v2.1.1):**
-```json
-{
-  "models": {
-    "GPT 5 Codex Low (ChatGPT Subscription)": {
-      "id": "gpt-5-codex",
-      "options": { "reasoningEffort": "low" }
-    }
-  }
-}
-```
-
-**After (Plugin v2.1.2):**
-- Keep same config
-- Plugin now finds per-model options ✅
-- No "item not found" errors ✅
-
-**Result:** ✅ **Works without config changes**
-
----
-
-#### Test 2: New User with Recommended Config
-
-**Config:**
-```json
-{
-  "models": {
-    "gpt-5-codex-low": {
-      "name": "GPT 5 Codex Low (OAuth)",
-      "options": { "reasoningEffort": "low" }
-    }
-  }
-}
-```
-
-**Expected:**
-- CLI: `--model=openai/gpt-5-codex-low` ✅
-- TUI: Shows "GPT 5 Codex Low (OAuth)" ✅
-- Plugin: Finds and applies per-model options ✅
-- API: Receives `"gpt-5-codex"` ✅
-
-**Result:** ✅ **Optimal experience**
-
----
-
-#### Test 3: Minimal Config (No Custom Models)
-
-**Config:**
-```json
-{
-  "plugin": ["codex-multi-auth"],
-  "model": "openai/gpt-5-codex"
-}
-```
+| Layer | Tooling |
+| --- | --- |
+| Unit/integration tests | Vitest (`test/**/*.test.ts`) |
+| Type checks | TypeScript (`tsc --noEmit`) |
+| Linting | ESLint |
+| Coverage | Vitest V8 coverage |
 
-**Expected:**
-- Uses default OpenCode model: `gpt-5-codex`
-- Plugin applies: Global options + Codex defaults
-- No errors ✅
+Coverage thresholds in `vitest.config.ts`: statements/branches/functions/lines >= `80`.
 
-**Result:** ✅ **Works out of the box**
+* * *
 
----
-
-## Debug Logging Test Cases
-
-### Enable Debug Mode
-
-```bash
-DEBUG_CODEX_PLUGIN=1 opencode run "test" --model=openai/gpt-5-codex-low
-```
-
-### Expected Debug Output
-
-#### Case 1: Custom Model with Config
-
-```
-[openai-codex-plugin] Debug logging ENABLED
-[openai-codex-plugin] Model config lookup: "gpt-5-codex-low" → normalized to "gpt-5-codex" for API {
-  hasModelSpecificConfig: true,
-  resolvedConfig: {
-    reasoningEffort: 'low',
-    textVerbosity: 'medium',
-    reasoningSummary: 'auto',
-    include: ['reasoning.encrypted_content']
-  }
-}
-[openai-codex-plugin] Filtering 0 message IDs from input: []
-```
-
-✅ **Verify:** `hasModelSpecificConfig: true` confirms per-model options found
-
----
-
-#### Case 2: Default Model (No Custom Config)
-
-```bash
-DEBUG_CODEX_PLUGIN=1 opencode run "test" --model=openai/gpt-5-codex
-```
-
-```
-[openai-codex-plugin] Debug logging ENABLED
-[openai-codex-plugin] Model config lookup: "gpt-5-codex" → normalized to "gpt-5-codex" for API {
-  hasModelSpecificConfig: false,
-  resolvedConfig: {
-    reasoningEffort: 'medium',
-    textVerbosity: 'medium',
-    reasoningSummary: 'auto',
-    include: ['reasoning.encrypted_content']
-  }
-}
-[openai-codex-plugin] Filtering 0 message IDs from input: []
-```
-
-✅ **Verify:** `hasModelSpecificConfig: false` confirms using global options
-
----
-
-#### Case 3: Multi-Turn with ID Filtering
-
-```
-[openai-codex-plugin] Filtering 3 message IDs from input: ['msg_abc123', 'rs_xyz789', 'msg_def456']
-[openai-codex-plugin] Successfully removed all 3 message IDs
-```
-
-✅ **Verify:** All IDs removed, no warnings
-
----
-
-#### Case 4: Warning if IDs Leak (Should Never Happen)
-
-```
-[openai-codex-plugin] WARNING: 1 IDs still present after filtering: ['msg_abc123']
-```
-
-❌ **This would indicate a bug** - should never appear
-
----
-
-## Integration Test Plan
-
-### Manual Testing Procedure
-
-#### Step 1: Fresh Install Test
-
-```bash
-# 1. Clear cache
-(cd ~ && rm -rf .cache/opencode/node_modules/codex-multi-auth)
-
-# 2. Use minimal config
-cat > ~/.config/opencode/opencode.json <<'EOF'
-{
-  "plugin": ["codex-multi-auth"],
-  "model": "openai/gpt-5-codex"
-}
-EOF
-
-# 3. Test default model
-DEBUG_CODEX_PLUGIN=1 opencode run "write hello world to test.txt"
-```
-
-**Verify:**
-- ✅ Plugin installs automatically
-- ✅ Auth works
-- ✅ Debug log shows: `hasModelSpecificConfig: false`
-- ✅ Model normalizes to `"gpt-5-codex"`
-- ✅ No errors
-
----
-
-#### Step 2: Custom Config Test
+## Core Commands
 
 ```bash
-# Update config with custom models
-cat > ~/.config/opencode/opencode.json <<'EOF'
-{
-  "plugin": ["codex-multi-auth"],
-  "provider": {
-    "openai": {
-      "models": {
-        "gpt-5-codex-low": {
-          "name": "GPT 5 Codex Low (OAuth)",
-          "options": { "reasoningEffort": "low" }
-        },
-        "gpt-5-codex-high": {
-          "name": "GPT 5 Codex High (OAuth)",
-          "options": { "reasoningEffort": "high" }
-        }
-      }
-    }
-  }
-}
-EOF
-
-# Test per-model options
-DEBUG_CODEX_PLUGIN=1 opencode run "test low" --model=openai/gpt-5-codex-low
-DEBUG_CODEX_PLUGIN=1 opencode run "test high" --model=openai/gpt-5-codex-high
-```
-
-**Verify:**
-- ✅ Debug log shows: `hasModelSpecificConfig: true` for both
-- ✅ Different `reasoningEffort` values in logs
-- ✅ TUI shows friendly names
-
----
-
-#### Step 3: Multi-Turn Test (Critical for store:false)
-
-```bash
-DEBUG_CODEX_PLUGIN=1 opencode --model=openai/gpt-5-codex-medium
-```
-
-```
-> write "test content" to file1.txt
-> read file1.txt
-> what did you just write?
-> create file2.txt with different content
-> compare the two files
-```
-
-**Verify:**
-- ✅ No "item not found" errors on ANY turn
-- ✅ Debug shows IDs removed on turns 2+
-- ✅ Context is maintained across turns
-- ✅ All tool calls work correctly
-
----
-
-#### Step 4: Model Switching Test
-
-```bash
-DEBUG_CODEX_PLUGIN=1 opencode
+npm run typecheck
+npm run lint
+npm test
+npm run build
 ```
 
-```
-> /model openai/gpt-5-codex-low
-> write hello to test.txt
-> /model openai/gpt-5-codex-high
-> write goodbye to test2.txt
-```
-
-**Verify:**
-- ✅ Different reasoning efforts logged for each model
-- ✅ Per-model options applied correctly
-- ✅ No errors when switching
-
----
-
-#### Step 5: TUI Persistence Test
+Optional:
 
 ```bash
-# 1. Start opencode
-opencode --model=openai/gpt-5-codex-high
-
-# 2. Run a command
-> write test
-
-# 3. Exit (ctrl+c)
-
-# 4. Restart
-opencode
-
-# 5. Check which model is selected
-> /model
+npm run test:watch
+npm run test:coverage
+npm run test:model-matrix:smoke
+npm run bench:edit-formats:smoke
 ```
 
-**Verify:**
-- ✅ Last used model is `gpt-5-codex-high`
-- ✅ Model is auto-selected on restart
-- ✅ TUI shows correct model highlighted
+* * *
 
----
+## Recommended Local Gate Before PR
 
-## Normalization Edge Cases
+1. `npm run typecheck`
+2. `npm run lint`
+3. `npm test`
+4. `npm run build`
+5. run docs command checks for newly documented command paths
 
-### Test: normalizeModel() Coverage
+* * *
 
-```typescript
-normalizeModel("gpt-5.2-codex")         // → "gpt-5.2-codex" ✅
-normalizeModel("gpt-5.2-codex-high")    // → "gpt-5.2-codex" ✅
-normalizeModel("gpt-5.2-xhigh")         // → "gpt-5.2" ✅
-normalizeModel("gpt-5.1-codex-max-xhigh")// → "gpt-5.1-codex-max" ✅
-normalizeModel("gpt-5.1-codex-mini-high")// → "gpt-5.1-codex-mini" ✅
-normalizeModel("codex-mini-latest")     // → "gpt-5.1-codex-mini" ✅
-normalizeModel("gpt-5.1-codex")         // → "gpt-5.1-codex" ✅
-normalizeModel("gpt-5.1")               // → "gpt-5.1" ✅
-normalizeModel("my-codex-model")        // → "gpt-5.1-codex" ✅
-normalizeModel("gpt-5")                 // → "gpt-5.1" ✅
-normalizeModel("gpt-5-mini")            // → "gpt-5.1" ✅
-normalizeModel("gpt-5-nano")            // → "gpt-5.1" ✅
-normalizeModel("GPT 5 High")            // → "gpt-5.1" ✅
-normalizeModel(undefined)               // → "gpt-5.1" ✅
-normalizeModel("random-model")          // → "gpt-5.1" ✅ (fallback)
-```
-
-**Implementation:**
-```typescript
-export function normalizeModel(model: string | undefined): string {
-  if (!model) return "gpt-5.1";
-  const modelId = model.includes("/") ? model.split("/").pop()! : model;
-  const mappedModel = MODEL_MAP[modelId];
-  if (mappedModel) return mappedModel;
+## Auth/Account Change Test Matrix
 
-  const normalized = modelId.toLowerCase();
+| Area | Minimum checks |
+| --- | --- |
+| Login flow | `codex auth login` completes and stores real account data |
+| Switching flow | `codex auth switch <index>` updates active account behavior |
+| Health operations | `check`, `forecast`, `fix`, `doctor`, `report` produce sane output |
+| Storage durability | backup/WAL recovery remains valid |
+| CLI state sync | active account sync with Codex CLI files |
+| Live updates | account changes picked up without restart |
+| Concurrency race safety | refresh/write races covered by deterministic tests |
+| Windows transient FS handling | retry behavior for `EBUSY`/`EPERM` paths |
 
-  if (normalized.includes("gpt-5.2-codex") || normalized.includes("gpt 5.2 codex")) {
-    return "gpt-5.2-codex";
-  }
-  if (normalized.includes("gpt-5.2") || normalized.includes("gpt 5.2")) {
-    return "gpt-5.2";
-  }
-  if (normalized.includes("gpt-5.1-codex-max") || normalized.includes("gpt 5.1 codex max")) {
-    return "gpt-5.1-codex-max";
-  }
-  if (normalized.includes("gpt-5.1-codex-mini") || normalized.includes("gpt 5.1 codex mini")) {
-    return "gpt-5.1-codex-mini";
-  }
-  if (
-    normalized.includes("codex-mini-latest") ||
-    normalized.includes("gpt-5-codex-mini") ||
-    normalized.includes("gpt 5 codex mini")
-  ) {
-    return "codex-mini-latest";
-  }
-  if (normalized.includes("gpt-5.1-codex") || normalized.includes("gpt 5.1 codex")) {
-    return "gpt-5.1-codex";
-  }
-  if (normalized.includes("gpt-5.1") || normalized.includes("gpt 5.1")) {
-    return "gpt-5.1";
-  }
-  if (normalized.includes("codex")) {
-    return "gpt-5.1-codex";
-  }
-  if (normalized.includes("gpt-5") || normalized.includes("gpt 5")) {
-    return "gpt-5.1";
-  }
-  return "gpt-5.1";
-}
-```
+* * *
 
-**Why this works:**
-- ✅ Case-insensitive (`.toLowerCase()` + `.includes()`)
-- ✅ Pattern-based (works with any naming)
-- ✅ Safe fallback (unknown models → `gpt-5.1`)
-- ✅ Codex priority with explicit Codex Mini support (`codex-mini*` → `codex-mini-latest`)
-
----
-
-## Expected Failures (These Should Error)
-
-### Invalid Model Selection
+## Manual Smoke Pack
 
 ```bash
-opencode run "test" --model=openai/claude-3.5
+codex auth login
+codex auth list
+codex auth check
+codex auth forecast --live
+codex auth fix --dry-run
+codex auth doctor --fix --dry-run
+codex auth report --live --json
 ```
 
-**Expected:** ❌ Error before plugin (OpenCode rejects unknown model)
-
-### Missing Authentication
+Optional plugin-host smoke:
 
 ```bash
-# Without running: opencode auth login
-opencode run "test" --model=openai/gpt-5-codex
+<run-your-host-runtime-smoke-command>
 ```
 
-**Expected:** ❌ 401 Unauthorized error
-
----
+* * *
 
-## Success Criteria
+## Failure-Mode Scenarios
 
-### All Tests Must Pass
+| Scenario | Expected behavior |
+| --- | --- |
+| OAuth callback port conflict | clean error and retry path |
+| Invalid/expired refresh token | account flagged/disabled by policy tools |
+| All accounts rate-limited | forecast/report show wait and recommendation |
+| Storage write error | `StorageError` has actionable hint |
+| Unsupported model | policy fallback or strict failure as configured |
+| Stream stalls | stream failover logic engages by policy |
 
-- [ ] Default models work without custom config
-- [ ] Custom config variants use per-model options
-- [ ] Old config format still works (backwards compat)
-- [ ] Mixed default + custom models work
-- [ ] Multi-turn conversations have no ID errors
-- [ ] Model switching works correctly
-- [ ] TUI persistence remembers last used model
-- [ ] Debug logging shows correct information
-- [ ] All normalization edge cases work
+* * *
 
-### No Errors
+## Docs QA (when docs change)
 
-- [ ] No "item not found" errors
-- [ ] No TypeScript errors
-- [ ] No authentication errors (after login)
-- [ ] No config validation errors
-
----
-
-## Automated Test Suggestions
-
-### Unit Tests (Future)
-
-```typescript
-describe('normalizeModel', () => {
-  test('handles all default models', () => {
-    expect(normalizeModel('gpt-5')).toBe('gpt-5')
-    expect(normalizeModel('gpt-5-codex')).toBe('gpt-5-codex')
-    expect(normalizeModel('gpt-5-codex-mini')).toBe('codex-mini-latest')
-    expect(normalizeModel('gpt-5-mini')).toBe('gpt-5')
-    expect(normalizeModel('gpt-5-nano')).toBe('gpt-5')
-  })
-
-  test('handles custom preset names', () => {
-    expect(normalizeModel('gpt-5-codex-low')).toBe('gpt-5-codex')
-    expect(normalizeModel('openai/gpt-5-codex-mini-high')).toBe('codex-mini-latest')
-    expect(normalizeModel('gpt-5-high')).toBe('gpt-5')
-  })
-
-  test('handles legacy names', () => {
-    expect(normalizeModel('GPT 5 Codex Low (ChatGPT Subscription)')).toBe('gpt-5-codex')
-  })
-
-  test('handles edge cases', () => {
-    expect(normalizeModel(undefined)).toBe('gpt-5')
-    expect(normalizeModel('codex-mini-latest')).toBe('codex-mini-latest')
-    expect(normalizeModel('random')).toBe('gpt-5')
-  })
-})
-
-describe('getModelConfig', () => {
-  test('returns per-model options when found', () => {
-    const config = getModelConfig('gpt-5-codex-low', {
-      global: { reasoningEffort: 'medium' },
-      models: {
-        'gpt-5-codex-low': {
-          options: { reasoningEffort: 'low' }
-        }
-      }
-    })
-    expect(config.reasoningEffort).toBe('low')
-  })
-
-  test('returns global options when model not in config', () => {
-    const config = getModelConfig('gpt-5-codex', {
-      global: { reasoningEffort: 'medium' },
-      models: {}
-    })
-    expect(config.reasoningEffort).toBe('medium')
-  })
-})
-
-describe('filterInput', () => {
-  test('removes all message IDs', () => {
-    const input = [
-      { id: 'msg_123', role: 'user', content: [] },
-      { id: 'rs_456', role: 'assistant', content: [] },
-      { role: 'user', content: [] }  // No ID
-    ]
-    const result = filterInput(input)
-    expect(result.every(item => !item.id)).toBe(true)
-  })
-})
-```
+1. Verify every command snippet is runnable.
+2. Cross-check path references against runtime modules.
+3. Confirm cross-links are valid.
+4. Keep feature matrix in sync with implemented features.
 
----
+* * *
 
-## See Also
+## Related
 
-- [ARCHITECTURE.md](./ARCHITECTURE.md) - Complete architecture and request pipeline summary
-- [CONFIG_FIELDS.md](./CONFIG_FIELDS.md) - Field usage guide
-- [CONFIG_FLOW.md](./CONFIG_FLOW.md) - Configuration loading and merge flow
+- [ARCHITECTURE.md](ARCHITECTURE.md)
+- [CONFIG_FIELDS.md](CONFIG_FIELDS.md)
+- [../DOCUMENTATION.md](../DOCUMENTATION.md)
+- [../benchmarks/code-edit-format-benchmark.md](../benchmarks/code-edit-format-benchmark.md)
diff --git a/docs/development/TUI_PARITY_CHECKLIST.md b/docs/development/TUI_PARITY_CHECKLIST.md
index c0e48455..bf03c231 100644
--- a/docs/development/TUI_PARITY_CHECKLIST.md
+++ b/docs/development/TUI_PARITY_CHECKLIST.md
@@ -1,104 +1,122 @@
-# TUI Parity Checklist (Codex Multi-Auth)
-
-Use this checklist to keep `codex-multi-auth` aligned with the Antigravity-style auth TUI pattern, while preserving Codex-specific logic and storage behavior.
-
-## Scope
-
-- Match interaction shape and operator experience.
-- Do not copy provider-specific business logic from Antigravity.
-- Keep Codex storage/auth semantics as source of truth.
-
-## Menu Structure Parity
-
-- `opencode auth login` -> provider -> login method -> account dashboard.
-- Dashboard sections exist in this order:
-  - `Actions`
-  - `Accounts`
-  - `Danger zone`
-- Core actions visible:
-  - `Add account`
-  - `Check quotas`
-  - `Deep probe accounts`
-  - `Verify flagged accounts`
-  - `Start fresh`
-  - `Delete all accounts`
-- Account row format includes:
-  - numeric index
-  - account label/email
-  - state badges (`[current]`, `[active]`, `[ok]`, `[rate-limited]`, `[disabled]`, `[flagged]`)
-  - usage hint (`used today`, `used yesterday`, etc.)
-
-## Keyboard and Navigation Parity
-
-- `Up/Down` moves selection.
-- `Enter` confirms selected item.
-- `Esc` returns/back/cancel.
-- Ctrl+C exits gracefully without corrupting terminal state.
-- Cursor visibility restored on exit from menu.
-
-## Account Detail Menu Parity
-
-- Selecting an account opens account detail actions:
-  - `Enable/Disable account`
-  - `Refresh account` (re-auth that account)
-  - `Delete this account`
-  - `Back`
-- Destructive actions require confirmation.
-- `Delete all accounts` requires explicit typed confirmation (`DELETE`).
-
-## Health/Quota Check Parity
-
-- `Check quotas` scans all active accounts and prints per-account results.
-- `Deep probe` performs stricter validation and surfaces richer diagnostic output.
-- Output includes index progress (`[i/N]`) and per-account status (`OK`, `ERROR`, `DISABLED`).
-- Summary line always shown at end (`ok/error/disabled` counts).
-
-## Flagged/Disabled State Parity
-
-- Invalid-refresh accounts are moved to flagged storage.
-- `Verify flagged accounts` can restore accounts that refresh successfully.
-- Disabled accounts remain visible but are skipped from active rotation and health execution paths.
-- Account manager never selects disabled accounts as current/next candidate.
-
-## Persistence and Cache Behavior
-
-- Storage writes occur after:
-  - account add/update/delete
-  - enable/disable toggle
-  - flagged pool migration/restore
-- In-memory account manager caches are invalidated after any account pool mutation.
-- Import flow invalidates both cached manager object and pending manager promise.
-
-## V2 Rollout Controls
-
-- Default behavior: Codex-style TUI is enabled.
-- Opt-out is supported through config/env:
-  - `codexTuiV2: false`
-  - `CODEX_TUI_V2=0`
-- Visual controls:
-  - `codexTuiColorProfile`: `truecolor` / `ansi256` / `ansi16`
-  - `codexTuiGlyphMode`: `ascii` / `unicode` / `auto`
-
-## Tooling Parity
-
-- `codex-list` reflects account states and active selection.
-- `codex-status` shows per-family active index and account-level state details.
-- `codex-import` and `codex-export` remain compatible with multi-account storage.
-
-## Verification Checklist (Before Release)
-
-- `npm run -s typecheck` passes.
-- `npm test` passes.
-- Manual smoke run:
-  - login -> dashboard appears
-  - add account works
-  - check quotas runs and summarizes
-  - disable account prevents rotation to it
-  - verify flagged restores a recoverable account
-  - delete-all requires typed confirmation and clears active + flagged pools
+# TUI Parity Checklist
+
+Checklist for keeping the auth dashboard consistent, beginner-friendly, and predictable.
+
+* * *
+
+## UX Target
+
+1. New users can complete add/check/switch without docs.
+2. Focus and key behavior are stable across all menus.
+3. Action feedback is clear and non-duplicative.
+4. Colors and labels are consistent across screens.
+
+* * *
+
+## Main Dashboard Structure
+
+Required sections:
+
+1. Quick Actions
+2. Advanced Checks
+3. Saved Accounts
+4. Danger Zone
+
+Required action set:
+
+- Add New Account
+- Run Health Check
+- Pick Best Account
+- Auto-Repair Issues
+- Settings
+- Refresh/Verify problem accounts
+
+* * *
+
+## Account Row Behavior
+
+Each row should support:
+
+- account identity (email/name)
+- optional status/current badges
+- last-used summary
+- quota summary bars (5h/7d)
+- optional cooldown text
+- clear selected-row highlight
+
+No duplicate focus indicators should be rendered.
+
+* * *
+
+## Keyboard Behavior
+
+Main menu minimum:
+
+- `Up/Down`
+- `Enter`
+- `Q`
+- `/` search
+- `?` help
+- `1-9` quick switch
+
+Account detail minimum:
+
+- `S` set current
+- `R` refresh login
+- `E` enable/disable
+- `D` delete
+- `Q` back
+
+Settings screens:
+
+- stable focus after toggle
+- no cursor reset on simple update
+- save/back behavior deterministic
+
+* * *
+
+## Auth Flow Parity
+
+Add-account flow must support:
+
+1. Browser-first OAuth.
+2. Manual/incognito callback paste flow.
+3. Safe cancel path returning to menu.
+4. No unhandled abort/CTRL+C stack traces in normal cancel behavior.
+
+* * *
+
+## Result Screen Quality
+
+1. No duplicated "Press Enter" lines.
+2. No stale text remnants after transitions.
+3. Auto-return messaging should not block user control.
+4. Errors should be normalized and readable.
+
+* * *
+
+## Data/Runtime Parity
+
+1. Displayed account state matches storage and active selection.
+2. Smart sort matches configured mode.
+3. Quick-switch follows configured row-index policy.
+4. Auto-fetch status is visible when running.
+
+* * *
+
+## Release Checklist
+
+Before release:
+
+1. Walk all menu paths manually.
+2. Validate hotkeys in terminal variants.
+3. Check color/focus consistency across all result screens.
+4. Ensure settings persist and reload correctly.
+5. Confirm command aliases still route correctly.
+
+* * *
 
 ## Non-Goals
 
-- Replicating Antigravity Google token semantics.
-- Sharing storage files with unrelated plugins.
-- Editing Antigravity repo files as part of Codex plugin maintenance.
+- Perfect clone of official Codex UI internals.
+- Terminal feature parity beyond supported input/color modes.
diff --git a/docs/features.md b/docs/features.md
new file mode 100644
index 00000000..105f27f9
--- /dev/null
+++ b/docs/features.md
@@ -0,0 +1,96 @@
+# Features
+
+Complete feature matrix for `codex-multi-auth`.
+
+This page is the authoritative index of implemented feature areas.
+
+* * *
+
+## Account and Auth Core
+
+| ID | Feature | What it gives you | Entry point |
+| --- | --- | --- | --- |
+| 1 | Multi-account OAuth login dashboard | Add/manage multiple accounts in one UI | `codex auth login` |
+| 2 | Account add/update dedupe by token/id/email | Prevent duplicate account records | Login flow |
+| 3 | Set current account command | Explicit active-account control | `codex auth switch <index>` |
+| 4 | Per-family active index handling | Model-family aware active account mapping | Runtime selection |
+| 5 | Quick health check command | Fast account session check | `codex auth check` |
+| 6 | Full refresh check command | Deeper refresh-based validation | Dashboard advanced check |
+| 7 | Flagged account verification command | Re-test flagged account health | `codex auth verify-flagged` |
+| 8 | Flagged account restore flow | Move healthy flagged accounts back to active pool | `codex auth verify-flagged` |
+
+* * *
+
+## Forecast, Fix, and Diagnostics
+
+| ID | Feature | What it gives you | Entry point |
+| --- | --- | --- | --- |
+| 9 | Best account forecast engine | Picks best account by risk/readiness | `codex auth forecast` |
+| 10 | Forecast live quota probing | Uses live quota headers for forecast quality | `codex auth forecast --live` |
+| 11 | Auto-fix command (safe mode) | Applies safe repairs to account state | `codex auth fix` |
+| 12 | Doctor diagnostics command | Structured diagnostics + optional repair | `codex auth doctor` |
+| 13 | JSON outputs for machine automation | Stable machine-readable command outputs | `--json` flags |
+| 14 | Report generation command | Full health summary for tooling/support | `codex auth report` |
+
+* * *
+
+## Storage and Data Safety
+
+| ID | Feature | What it gives you | Entry point |
+| --- | --- | --- | --- |
+| 15 | Storage v3 normalization and migration | Normalized account format + migration handling | Storage loader |
+| 16 | Storage backup and recovery journal | Backup/WAL durability protections | Storage writer |
+| 17 | Project-scoped and global storage paths | Per-project isolation option | `pluginConfig.perProjectAccounts` |
+| 18 | Quota cache storage | Cached quota summaries for dashboard/forecast | `quota-cache.json` |
+
+* * *
+
+## Runtime Reliability and Sync
+
+| ID | Feature | What it gives you | Entry point |
+| --- | --- | --- | --- |
+| 19 | Live account sync watcher | Reload account state without restart | `pluginConfig.liveAccountSync` |
+| 20 | Session affinity store | Keep session on stable account | `pluginConfig.sessionAffinity` |
+| 21 | Refresh queue dedupe (in-process) | Avoid duplicate refresh calls in one process | Refresh queue |
+| 22 | Refresh lease dedupe (cross-process) | Avoid duplicate refresh calls across processes | Refresh lease |
+| 23 | Token rotation mapping in refresh queue | Handles rotating token pairs safely | Refresh flow |
+| 24 | Refresh guardian (proactive refresh) | Refresh near-expiry accounts in background | `pluginConfig.proactiveRefreshGuardian` |
+| 25 | Preemptive quota scheduler | Delay before hard quota exhaustion | `pluginConfig.preemptiveQuotaEnabled` |
+| 26 | Entitlement cache for unsupported models | Temporarily suppress unsupported account/model paths | Automatic during forecast/check/probe |
+| 27 | Capability policy scoring store | Boost/penalty memory per account+model | Automatic scoring in runtime selection |
+| 28 | Failure policy evaluation module | Centralized retry/rotate/cooldown decisions | Failure policy |
+| 29 | Streaming failover pipeline | Recover from stream stalls via fallback | Stream failover |
+| 30 | Rate-limit backoff and cooldown handling | Controlled wait/rotation under rate limit | Backoff runtime |
+
+* * *
+
+## Request and Prompt Integration
+
+| ID | Feature | What it gives you | Entry point |
+| --- | --- | --- | --- |
+| 31 | Plugin-host request transformer bridge | Converts incoming requests to Codex-safe shape | Plugin request pipeline |
+| 32 | Prompt template sync with cache | Cached prompt templates with sync/ETag strategy | Prompt subsystem |
+| 33 | Codex CLI active-account state sync | Aligns active account with official Codex state | Codex writer/sync |
+
+* * *
+
+## TUI and UX
+
+| ID | Feature | What it gives you | Entry point |
+| --- | --- | --- | --- |
+| 34 | TUI quick-switch hotkeys (1-9) | Immediate account switch from dashboard | Auth dashboard |
+| 35 | TUI search and help toggles | Fast filtering and keyboard help | `/`, `?` |
+| 36 | TUI account detail hotkeys (S/R/E/D) | Fast per-account actions | Account detail menu |
+| 37 | TUI settings hub (list/summary/behavior/theme) | In-dashboard customization | Settings menu |
+| 38 | Dashboard display customization | Toggle/sort/layout/field options | Dashboard settings |
+| 39 | Unified color/theme runtime (v2 UI) | Consistent colors/focus styles across menus | UI runtime/theme |
+| 40 | OAuth browser-first flow with manual callback fallback | Works with default browser or manual/incognito flow | Add account flow |
+
+* * *
+
+## Related
+
+- [reference/commands.md](reference/commands.md)
+- [reference/settings.md](reference/settings.md)
+- [troubleshooting.md](troubleshooting.md)
+- [development/ARCHITECTURE.md](development/ARCHITECTURE.md)
diff --git a/docs/getting-started.md b/docs/getting-started.md
index 83b27c75..e17a2110 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -1,260 +1,140 @@
 # Getting Started
 
-Complete installation and setup guide for the OpenCode OpenAI Codex Auth Plugin.
+Install, sign in, and run your first healthy multi-account setup.
 
----
-
-<details open>
-<summary><b>Before You Begin</b></summary>
-
-> [!CAUTION]
-> **This plugin is for personal development use only.** It uses OpenAI's official OAuth authentication for individual coding assistance with your ChatGPT Plus/Pro subscription.
->
-> **Not intended for:** Commercial services, API resale, multi-user applications, or any use that violates [OpenAI's Terms of Use](https://openai.com/policies/terms-of-use/).
->
-> For production applications, use the [OpenAI Platform API](https://platform.openai.com/).
-
-</details>
-
----
+* * *
 
 ## Prerequisites
 
-| Requirement | Notes |
-|-------------|-------|
-| **OpenCode** | [Installation guide](https://opencode.ai) |
-| **ChatGPT Plus or Pro** | Required for Codex access |
-| **Node.js 20+** | For OpenCode runtime |
-
----
-
-## Installation
-
-<details open>
-<summary><b>Option A: One-Command Install (Recommended)</b></summary>
+- Node.js `18+`
+- Official Codex CLI package: `@openai/codex`
+- This repository cloned locally
 
-Works on **Windows, macOS, and Linux**:
-
-```bash
-npx -y codex-multi-auth@latest
-```
-
-This:
-- Writes config to `~/.config/opencode/opencode.json`
-- Backs up existing config
-- Clears OpenCode plugin cache
-
-**Legacy OpenCode (v1.0.209 and below)?**
-```bash
-npx -y codex-multi-auth@latest --legacy
-```
+* * *
 
-</details>
+## Install (Source Workflow)
 
-<details>
-<summary><b>Option B: Install from Source</b></summary>
+Bash:
 
 ```bash
+npm install -g @openai/codex
 git clone https://github.com/ndycode/codex-multi-auth.git
 cd codex-multi-auth
-npm ci
+npm install
 npm run build
+npm link
 ```
 
-Point OpenCode at the local build output:
+PowerShell:
 
-```json
-{
-  "plugin": ["file:///absolute/path/to/codex-multi-auth/dist"]
-}
+```powershell
+npm install -g @openai/codex
+git clone https://github.com/ndycode/codex-multi-auth.git
+Set-Location codex-multi-auth
+npm install
+npm run build
+npm link
 ```
 
-> **Note**: Must point to `dist/` folder (built output), not root.
-
-</details>
-
----
-
-## Setup Steps
-
-### Step 1: Add Plugin to Config
-
-Edit `~/.config/opencode/opencode.json`:
+Verify command wiring:
 
-```json
-{
-  "$schema": "https://opencode.ai/config.json",
-  "plugin": ["codex-multi-auth@latest"]
-}
+```bash
+codex --version
+codex auth status
 ```
 
-> If you installed from source, use the `file://` path instead.
+* * *
 
-### Step 2: Authenticate
+## Add Your First Account
 
 ```bash
-opencode auth login
+codex auth login
 ```
 
-1. Select **"OpenAI"**
-2. Choose **"ChatGPT Plus/Pro (Codex Subscription)"**
-3. Browser opens automatically for OAuth flow
-4. Log in with your ChatGPT account
-5. Done! Token saved to `~/.opencode/auth/openai.json`
-
-<details>
-<summary><b>OAuth Not Working?</b></summary>
-
-**Port conflict:**
-- Stop Codex CLI if running (both use port 1455)
-- Check: `lsof -i :1455` (macOS/Linux) or `netstat -ano | findstr :1455` (Windows)
-
-**SSH/WSL/Remote:**
-- Select **"ChatGPT Plus/Pro (Manual URL Paste)"**
-- Paste the full redirect URL after login
-
-</details>
-
-### Step 3: Add Model Configuration
-
-Use one of the provided config files:
+Expected flow:
 
-| OpenCode Version | Config File |
-|------------------|-------------|
-| v1.0.210+ (modern) | `config/opencode-modern.json` |
-| v1.0.209 and below | `config/opencode-legacy.json` |
+1. Dashboard opens.
+2. Choose **Add New Account**.
+3. OAuth page opens in browser.
+4. After approval, return to terminal.
+5. Your real email appears in the account list.
 
-Copy the relevant config to your `~/.config/opencode/opencode.json`.
-
-The shipped templates include 27 presets in modern mode and 22 presets in legacy mode, and intentionally omit Spark IDs. Add `gpt-5.3-codex-spark` manually only when your workspace is entitled.
-
-<details>
-<summary><b>Why use the full config?</b></summary>
-
-- GPT-5 models need proper configuration to work reliably
-- Full configs include `limit` metadata for OpenCode UI features
-- Minimal configs are for debugging only
-
-</details>
-
-### Step 4: Test It
+Check result:
 
 ```bash
-# Modern OpenCode (v1.0.210+)
-opencode run "write hello world to test.txt" --model=openai/gpt-5.2 --variant=medium
-opencode run "write hello world to test.txt" --model=openai/gpt-5-codex --variant=medium
-
-# Legacy OpenCode (v1.0.209 and below)
-opencode run "write hello world to test.txt" --model=openai/gpt-5.2-medium
-
-# Or start interactive session
-opencode
+codex auth list
 ```
 
-You'll see all 27 GPT-5.x variants in the model selector!
-
-If `gpt-5-codex` or `gpt-5.3-codex-spark` returns an unsupported-model entitlement error, re-auth with `opencode auth login` or add another entitled account/workspace first. The plugin tries remaining accounts/workspaces before model fallback. See [Configuration](configuration.md) for strict vs fallback policy controls.
-
-If you manually add Spark IDs and want to confirm effective upstream routing, run with `ENABLE_PLUGIN_REQUEST_LOGGING=1 CODEX_PLUGIN_LOG_BODIES=1` and inspect `~/.opencode/logs/codex-plugin/request-*-after-transform.json`.
-
----
-
-## Available Models
-
-| Model | Variants | Notes |
-|-------|----------|-------|
-| `gpt-5.2` | none, low, medium, high, xhigh | Latest GPT-5.2 |
-| `gpt-5-codex` | low, medium, high | Canonical Codex for code generation |
-| `gpt-5.3-codex-spark` | low, medium, high, xhigh | Optional manual model; entitlement-gated by account/workspace |
-| `gpt-5.1-codex-max` | low, medium, high, xhigh | Maximum context |
-| `gpt-5.1-codex` | low, medium, high | Standard Codex |
-| `gpt-5.1-codex-mini` | medium, high | Lightweight |
-| `gpt-5.1` | none, low, medium, high | Base model |
-
-**Total: 27 template presets** with 272k context / 128k output (+ optional Spark IDs when entitled).
-
----
+* * *
 
-## Configuration Locations
+## Add More Accounts
 
-OpenCode checks multiple config files in order:
+Run login again and add another account from the same dashboard.
 
-| Priority | Location | Use Case |
-|----------|----------|----------|
-| 1 | `./.opencode.json` | Project-specific |
-| 2 | Parent directories | Monorepo |
-| 3 | `~/.config/opencode/opencode.json` | Global defaults |
-
-**Recommendation**: Plugin in global config, model/agent overrides in project config.
-
----
-
-## Updating the Plugin
-
-<details>
-<summary><b>From npm</b></summary>
+```bash
+codex auth login
+```
 
-OpenCode caches plugins. Re-run the installer:
+After adding, run:
 
 ```bash
-npx -y codex-multi-auth@latest
+codex auth check
+codex auth forecast --live
 ```
 
-</details>
+This confirms session health and shows the best next account.
+
+* * *
 
-<details>
-<summary><b>From source</b></summary>
+## Day-1 Command Pack
 
 ```bash
-cd codex-multi-auth
-git pull
-npm ci
-npm run build
+codex auth list
+codex auth switch 2
+codex auth check
+codex auth forecast --live
+codex auth fix --dry-run
+codex auth doctor --fix
+codex auth report --live --json
 ```
 
-</details>
+* * *
 
-**When to update:**
-- New features released
-- Bug fixes available
-- Security updates
+## Optional: Plugin-Host Integration
 
-**Check for updates**: [Releases Page](https://github.com/ndycode/codex-multi-auth/releases)
+`codex auth ...` works without any extra host config.
 
----
+If you also run this project as a plugin-host integration, see the optional host config section in [configuration.md](configuration.md).
 
-## Verifying Installation
+* * *
 
-### Check Plugin is Loaded
+## Common First-Run Issues
+
+If you see placeholder/demo email rows:
 
 ```bash
-opencode --version
-# Should not show any plugin errors
+codex auth doctor --fix
+codex auth list
 ```
 
-### Check Authentication
+If `codex auth` is not recognized:
 
 ```bash
-cat ~/.opencode/auth/openai.json
-# Should show OAuth credentials
+where codex
+codex multi auth status
 ```
 
-### Test API Access
+If OAuth callback fails on port `1455`:
 
-```bash
-# Enable logging to verify requests
-ENABLE_PLUGIN_REQUEST_LOGGING=1 opencode run "test" --model=openai/gpt-5.2
+- Close other process using that port.
+- Retry `codex auth login`.
 
-# Check logs
-ls ~/.opencode/logs/codex-plugin/
-```
-
----
+* * *
 
 ## Next Steps
 
-- [Configuration Guide](configuration.md) — Advanced config options
-- [Troubleshooting](troubleshooting.md) — Common issues and solutions
-- [Architecture](development/ARCHITECTURE.md) — Technical deep dive
-
-**Back to**: [Documentation Home](index.md) | [Main README](../README.md)
+- [features.md](features.md)
+- [configuration.md](configuration.md)
+- [troubleshooting.md](troubleshooting.md)
+- [reference/commands.md](reference/commands.md)
+- [upgrade.md](upgrade.md)
diff --git a/docs/index.md b/docs/index.md
index 40cf7d12..79829822 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,140 +1,49 @@
-# OpenCode OpenAI Codex Auth Plugin
+# codex-multi-auth Docs
 
-[![npm version](https://img.shields.io/npm/v/codex-multi-auth.svg)](https://www.npmjs.com/package/codex-multi-auth)
-[![Tests](https://github.com/ndycode/codex-multi-auth/actions/workflows/ci.yml/badge.svg)](https://github.com/ndycode/codex-multi-auth/actions)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](../LICENSE)
+Codex CLI-first multi-account OAuth docs in one place.
 
-> Access GPT-5 Codex through your ChatGPT Plus/Pro subscription in OpenCode
-
----
-
-<details open>
-<summary><b>Usage Notice</b></summary>
-
-> [!CAUTION]
-> **This plugin is for personal development use only.** It uses OpenAI's official OAuth authentication (the same method as OpenAI's official Codex CLI) for individual coding assistance with your ChatGPT Plus/Pro subscription.
->
-> **Not for:** Commercial services, API resale, or multi-user applications. For production use, see [OpenAI Platform API](https://platform.openai.com/).
->
-> Users are responsible for compliance with [OpenAI's Terms of Use](https://openai.com/policies/terms-of-use/).
-
-</details>
-
----
-
-## Quick Links
-
-### For Users
-
-| Guide | Description |
-|-------|-------------|
-| [Getting Started](getting-started.md) | Complete installation and setup |
-| [Configuration](configuration.md) | Advanced config options and patterns |
-| [Troubleshooting](troubleshooting.md) | Debug techniques and common issues |
-| [Privacy & Data](privacy.md) | How your data is handled |
-| [Release Notes](https://github.com/ndycode/codex-multi-auth/releases) | Version history |
-
-### For Developers
-
-| Guide | Description |
-|-------|-------------|
-| [Repository Scope Map](development/REPOSITORY_SCOPE.md) | Canonical ownership map for paths and extension points |
-| [Architecture](development/ARCHITECTURE.md) | Technical design, AI SDK compatibility |
-| [Config System](development/CONFIG_FLOW.md) | Configuration loading and merging |
-| [Config Fields](development/CONFIG_FIELDS.md) | Understanding config keys and fields |
-| [Testing Guide](development/TESTING.md) | Test scenarios and verification |
-| [TUI Parity Checklist](development/TUI_PARITY_CHECKLIST.md) | Auth dashboard/UI parity requirements |
-
----
+* * *
 
 ## Quick Start
 
 ```bash
-# 1. Install
-npx -y codex-multi-auth@latest
-
-# 2. Authenticate
-opencode auth login
-
-# 3. Use it
-opencode run "Hello" --model=openai/gpt-5.2 --variant=medium
+codex auth login
+codex auth list
+codex auth check
 ```
 
-For detailed setup, see [Getting Started](getting-started.md).
-
----
+Then continue with:
 
-## Features
+- [Getting Started](getting-started.md)
+- [Configuration](configuration.md)
+- [Troubleshooting](troubleshooting.md)
 
-| Feature | Description |
-|---------|-------------|
-| **OAuth Authentication** | Secure ChatGPT Plus/Pro login |
-| **27 Template Presets** | GPT-5.2, 5.3-Codex, 5.1-Codex-Max, 5.1-Codex, 5.1-Codex-Mini, 5.1 (plus optional manual Spark IDs) |
-| **Variant System** | Works with OpenCode v1.0.210+ variants and legacy presets |
-| **Multi-Account** | Auto-rotation when rate-limited |
-| **Per-Model Config** | Different reasoning effort per model |
-| **Multi-Turn** | Full conversation history with stateless backend |
-| **Fast Session Mode** | Optional low-latency tuning for quick interactive turns |
-| **Comprehensive Tests** | 1500+ tests (80% coverage threshold) + integration tests |
+* * *
 
----
+## Quick Commands
 
-## Why This Plugin?
-
-**Use your ChatGPT subscription instead of OpenAI API credits**
-
-| Benefit | Description |
-|---------|-------------|
-| No separate API key | Uses ChatGPT OAuth |
-| Access Codex models | Through ChatGPT Plus/Pro |
-| Same auth as Codex CLI | Official OAuth flow |
-| Full feature parity | With Codex CLI |
-
----
-
-## How It Works
-
-The plugin intercepts OpenCode's OpenAI SDK requests and transforms them for the ChatGPT backend API:
-
-```
-OpenCode SDK Request
-        ↓
-    OAuth Token Management (auto-refresh)
-        ↓
-    Request Transformation (SDK → Codex API)
-        ↓
-    AI SDK Compatibility (filter constructs)
-        ↓
-    Stateless Operation (store: false)
-        ↓
-ChatGPT Codex Backend
+```bash
+codex auth forecast --live
+codex auth fix --dry-run
+codex auth doctor --fix
+codex auth report --live --json
 ```
 
-See [Architecture](development/ARCHITECTURE.md) and [TUI Parity Checklist](development/TUI_PARITY_CHECKLIST.md) for technical details and UI parity criteria.
-
----
-
-## Support
-
-| Resource | Link |
-|----------|------|
-| Issues | [GitHub Issues](https://github.com/ndycode/codex-multi-auth/issues) |
-| Releases | [Release Notes](https://github.com/ndycode/codex-multi-auth/releases) |
-| Repository | [GitHub](https://github.com/ndycode/codex-multi-auth) |
-
----
-
-## Credits
+* * *
 
-| Contributor | Role |
-|-------------|------|
-| [numman-ali](https://github.com/numman-ali) | Original plugin author |
-| [ndycode](https://github.com/ndycode) | Multi-account support and maintenance |
+## Documentation Sections
 
----
+- User guides: [README.md](README.md)
+- Full features list: [features.md](features.md)
+- Command reference: [reference/commands.md](reference/commands.md)
+- Settings reference: [reference/settings.md](reference/settings.md)
+- Storage paths: [reference/storage-paths.md](reference/storage-paths.md)
+- Development internals: [development/](development/)
 
-## License
+* * *
 
-MIT License with Usage Disclaimer — See [LICENSE](../LICENSE) for details.
+## Notes
 
-**Trademark Notice:** Not affiliated with OpenAI. ChatGPT, GPT-5, Codex, and OpenAI are trademarks of OpenAI, L.L.C.
+- `codex auth ...` is the canonical account-management flow.
+- Legacy path/command notes live in [upgrade.md](upgrade.md).
+- Non-auth `codex` commands are forwarded to the official `@openai/codex` CLI by the wrapper.
diff --git a/docs/privacy.md b/docs/privacy.md
index f5a4bb1d..dd1f6af4 100644
--- a/docs/privacy.md
+++ b/docs/privacy.md
@@ -1,203 +1,93 @@
-# Privacy & Data Handling
+# Privacy and Data Handling
 
-This page explains how the OpenCode OpenAI Codex Auth Plugin handles your data and protects your privacy.
+`codex-multi-auth` is local-first: account/session data is stored on your machine.
 
-## Overview
+* * *
 
-This plugin prioritizes user privacy and data security. We believe in transparency about data handling and giving you full control over your information.
+## Telemetry
 
----
+- No custom-hosted analytics pipeline in this project.
+- No project-owned remote database.
+- Network calls only go to required OAuth/backend/update endpoints.
 
-## What We Collect
+* * *
 
-**Nothing.** This plugin does not collect, store, or transmit usage data to third parties.
+## Local Files (Current Canonical)
 
-- ❌ No telemetry
-- ❌ No analytics
-- ❌ No usage tracking
-- ❌ No personal information collection
+| Data | Path | Why it exists |
+| --- | --- | --- |
+| Unified settings | `~/.codex/multi-auth/settings.json` | Dashboard + backend behavior settings |
+| Accounts | `~/.codex/multi-auth/openai-codex-accounts.json` | Saved account pool |
+| Flagged accounts | `~/.codex/multi-auth/openai-codex-flagged-accounts.json` | Accounts with hard auth failures |
+| Quota cache | `~/.codex/multi-auth/quota-cache.json` | Cached 5h/7d limit snapshots |
+| Logs | `~/.codex/multi-auth/logs/codex-plugin/` | Optional diagnostic logs |
+| Prompt/cache files | `~/.codex/multi-auth/cache/` | Cached prompt/template metadata |
+| Codex CLI auth state | `~/.codex/accounts.json`, `~/.codex/auth.json` | Official Codex CLI account/auth files |
 
----
+Legacy compatibility files from older versions may still be read during migration-only compatibility checks.
+If `CODEX_MULTI_AUTH_DIR` or `CODEX_MULTI_AUTH_CONFIG_PATH` is set, these locations move to the configured override path.
 
-## Data Storage
+* * *
 
-All data is stored **locally on your machine**:
+## Network Destinations
 
-### OAuth Tokens
-- **Location:** `~/.opencode/auth/openai.json`
-- **Contents:** Access tokens, refresh tokens, expiration timestamps
-- **Managed by:** OpenCode's credential management system
-- **Security:** File permissions restrict access to your user account
+This project communicates with:
 
-### Cache Files
-- **Location:** `~/.opencode/cache/`
-- **Contents:**
-  - `codex-instructions.txt` - Codex system instructions (fetched from GitHub)
-  - `codex-instructions-meta.json` - ETag and timestamp metadata
-- **Purpose:** Reduce GitHub API calls and improve performance
-- **TTL:** 15 minutes (automatically refreshes when stale)
+- OpenAI OAuth endpoints (`auth.openai.com`)
+- OpenAI Codex/ChatGPT backend endpoints
+- GitHub raw/releases endpoints for prompt-template sync cache
 
-### Debug Logs
-- **Location:** `~/.opencode/logs/codex-plugin/`
-- **Contents:** Request/response metadata logs (only when `ENABLE_PLUGIN_REQUEST_LOGGING=1` is set)
-- **Includes:**
-  - Request metadata (model, flags, response status, timing)
-  - Raw request/response payloads only when `CODEX_PLUGIN_LOG_BODIES=1` is also set
-  - Timestamps
-  - Configuration used
-- **⚠️ Warning:** Logs may contain your prompts and model responses - handle with care
+* * *
 
----
+## Sensitive Logging Warning
 
-## Data Transmission
+If you enable raw body logging:
 
-### Direct to OpenAI
-All API requests go **directly from your machine to OpenAI's servers**:
-- ✅ No intermediary proxies
-- ✅ No third-party data collection
-- ✅ HTTPS encrypted communication
-- ✅ OAuth-secured authentication
-
-### What Gets Sent to OpenAI
-When you use the plugin, the following is transmitted to OpenAI:
-- Your prompts and conversation history
-- OAuth access token (for authentication)
-- ChatGPT account ID (from token JWT)
-- Configuration options (reasoning effort, verbosity, etc.)
-- Model selection
-
-**Note:** This is identical to what the official OpenAI Codex CLI sends.
-
-### What Does NOT Get Sent
-- ❌ Your filesystem contents (unless explicitly requested via tools)
-- ❌ Personal information beyond what's in your prompts
-- ❌ Usage statistics or analytics
-- ❌ Plugin version or system information
-
----
-
-## Third-Party Services
-
-### GitHub API
-The plugin fetches Codex instructions from GitHub:
-- **URL:** `https://api.github.com/repos/openai/codex/releases/latest`
-- **Purpose:** Get latest Codex system instructions
-- **Frequency:** Once per 15 minutes (cached with ETag)
-- **Data sent:** HTTP GET request (no personal data)
-- **Rate limiting:** 60 requests/hour (unauthenticated)
-
-### OpenAI Services
-All interactions with OpenAI go through:
-- **OAuth:** `https://chatgpt.com/oauth`
-- **API:** `https://chatgpt.com/backend-api/conversation`
+```bash
+CODEX_PLUGIN_LOG_BODIES=1
+```
 
-See [OpenAI Privacy Policy](https://openai.com/policies/privacy-policy/) for how OpenAI handles data.
+prompt/response payload text can be written to local logs. Treat those logs as sensitive.
 
----
+* * *
 
-## Your Data Rights
+## Data Cleanup
 
-You have complete control over your data:
+Bash:
 
-### Delete OAuth Tokens
 ```bash
-opencode auth logout
-# Or manually:
-rm ~/.opencode/auth/openai.json
+rm -f ~/.codex/multi-auth/settings.json
+rm -f ~/.codex/multi-auth/openai-codex-accounts.json
+rm -f ~/.codex/multi-auth/openai-codex-flagged-accounts.json
+rm -f ~/.codex/multi-auth/quota-cache.json
+rm -rf ~/.codex/multi-auth/logs/codex-plugin
+rm -rf ~/.codex/multi-auth/cache
 ```
 
-### Delete Cache Files
-```bash
-rm -rf ~/.opencode/cache/
-```
+PowerShell:
 
-### Delete Logs
-```bash
-rm -rf ~/.opencode/logs/codex-plugin/
+```powershell
+Remove-Item "$HOME\.codex\multi-auth\settings.json" -Force -ErrorAction SilentlyContinue
+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\quota-cache.json" -Force -ErrorAction SilentlyContinue
+Remove-Item "$HOME\.codex\multi-auth\logs\codex-plugin" -Recurse -Force -ErrorAction SilentlyContinue
+Remove-Item "$HOME\.codex\multi-auth\cache" -Recurse -Force -ErrorAction SilentlyContinue
 ```
 
-### Revoke OAuth Access
-1. Visit [ChatGPT Settings → Authorized Apps](https://chatgpt.com/settings/apps)
-2. Find "OpenCode" or "Codex CLI"
-3. Click "Revoke"
-
-This immediately invalidates all access tokens.
-
----
-
-## Security Measures
-
-### Token Protection
-- **Local storage only:** Tokens never leave your machine except when sent to OpenAI for authentication
-- **File permissions:** Auth files are readable only by your user account
-- **No logging:** OAuth tokens are never written to debug logs
-- **Automatic refresh:** Expired tokens are refreshed automatically
-
-### PKCE Flow
-The plugin uses **PKCE (Proof Key for Code Exchange)** for OAuth:
-- Prevents authorization code interception attacks
-- Industry-standard security for OAuth 2.0
-- Same method used by OpenAI's official Codex CLI
-
-### HTTPS Encryption
-All network communication uses HTTPS:
-- OAuth authorization: Encrypted
-- API requests: Encrypted
-- Token refresh: Encrypted
-
----
-
-## Compliance
-
-### OpenAI's Privacy Policy
-When using this plugin, you are subject to:
-- [OpenAI Privacy Policy](https://openai.com/policies/privacy-policy/)
-- [OpenAI Terms of Use](https://openai.com/policies/terms-of-use/)
-
-**Your responsibility:** Ensure your usage complies with OpenAI's policies.
-
-### GDPR Considerations
-This plugin:
-- ✅ Does not collect personal data
-- ✅ Does not process data on behalf of third parties
-- ✅ Stores data locally under your control
-- ✅ Provides clear data deletion mechanisms
-
-However, data sent to OpenAI is subject to OpenAI's privacy practices.
-
----
-
-## Transparency
-
-### Open Source
-The entire plugin source code is available at:
-- **GitHub:** [https://github.com/ndycode/codex-multi-auth](https://github.com/ndycode/codex-multi-auth)
-
-
-You can:
-- Review all code
-- Audit data handling
-- Verify no hidden telemetry
-- Inspect network requests
-
-### No Hidden Behavior
-- No obfuscated code
-- No minified dependencies
-- All network requests are documented
-- Debug logging shows exactly what's sent to APIs
-
----
+* * *
 
-## Questions?
+## Policy Responsibility
 
-For privacy-related questions:
-- **Plugin-specific:** [GitHub Issues](https://github.com/ndycode/codex-multi-auth/issues)
+Usage must comply with OpenAI policy documents:
 
-- **OpenAI data handling:** [OpenAI Support](https://help.openai.com/)
-- **Security concerns:** See [SECURITY.md](../SECURITY.md)
+- https://openai.com/policies/terms-of-use/
+- https://openai.com/policies/privacy-policy/
 
----
+* * *
 
-**Last Updated:** 2025-10-12
+## Related
 
-**Back to:** [Documentation Home](index.md) | [Getting Started](getting-started.md)
+- [configuration.md](configuration.md)
+- [troubleshooting.md](troubleshooting.md)
+- [reference/storage-paths.md](reference/storage-paths.md)
diff --git a/docs/reference/commands.md b/docs/reference/commands.md
new file mode 100644
index 00000000..adee6a1b
--- /dev/null
+++ b/docs/reference/commands.md
@@ -0,0 +1,135 @@
+# Command Reference
+
+Complete CLI and hotkey reference for `codex-multi-auth`.
+
+* * *
+
+## Canonical Command Family
+
+Use `codex auth ...` for account operations.
+
+Supported aliases:
+
+- `codex multi auth ...`
+- `codex multi-auth ...`
+- `codex multiauth ...`
+
+* * *
+
+## Primary Commands
+
+| Command | Description |
+| --- | --- |
+| `codex auth login` | Open interactive auth dashboard |
+| `codex auth list` | List saved accounts and active account |
+| `codex auth status` | Short status summary |
+| `codex auth switch <index>` | Set active account by index |
+| `codex auth check` | Run quick account health check |
+| `codex auth features` | Print implemented feature list |
+
+* * *
+
+## Advanced Commands
+
+| Command | Description |
+| --- | --- |
+| `codex auth verify-flagged` | Verify flagged accounts and optionally restore healthy ones |
+| `codex auth forecast` | Forecast best account by readiness/risk |
+| `codex auth report` | Generate full health report |
+| `codex auth fix` | Apply safe account storage fixes |
+| `codex auth doctor` | Run diagnostics and optional fixes |
+
+Common flags:
+
+| Flag | Applies to | Meaning |
+| --- | --- | --- |
+| `--json` | verify-flagged/forecast/report/fix/doctor | machine-readable output |
+| `--live` | forecast/report | use live quota/session probes |
+| `--dry-run` | verify-flagged/fix/doctor | preview without mutation |
+| `--fix` | doctor | apply repairs |
+| `--model <model>` | forecast/report | choose forecast model |
+| `--out <path>` | report | write report file |
+| `--no-restore` | verify-flagged | verify only, do not restore |
+
+* * *
+
+## Dashboard Hotkeys
+
+### Main Dashboard
+
+| Key | Action |
+| --- | --- |
+| `Up` / `Down` | Move selection |
+| `Enter` | Select/open |
+| `1-9` | Quick switch visible/source account |
+| `/` | Search accounts |
+| `?` | Toggle help |
+| `Q` | Back/cancel |
+
+### Account Detail Menu
+
+| Key | Action |
+| --- | --- |
+| `S` | Set current account |
+| `R` | Refresh/re-login this account |
+| `E` | Enable/disable |
+| `D` | Delete account |
+| `Q` | Back |
+
+### Settings Screens
+
+| Key | Action |
+| --- | --- |
+| `Enter` | Toggle/select/open |
+| `1-9` | Quick toggle for numbered options |
+| `S` | Save |
+| `R` | Reset (where applicable) |
+| `Q` | Back or Save+Back (context dependent) |
+| `[` / `]` | Reorder fields in summary settings |
+| `+` / `-` | Adjust focused numeric backend setting |
+
+* * *
+
+## Useful Workflows
+
+Health workflow:
+
+```bash
+codex auth check
+codex auth forecast --live
+codex auth report --live --json
+```
+
+Repair workflow:
+
+```bash
+codex auth fix --dry-run
+codex auth fix
+codex auth doctor --fix
+```
+
+Flagged account workflow:
+
+```bash
+codex auth verify-flagged --json
+```
+
+* * *
+
+## Troubleshooting Commands
+
+```bash
+where codex
+which codex
+codex --version
+codex auth status
+codex multi auth status
+```
+
+* * *
+
+## Related
+
+- [../features.md](../features.md)
+- [settings.md](settings.md)
+- [../troubleshooting.md](../troubleshooting.md)
diff --git a/docs/reference/settings.md b/docs/reference/settings.md
new file mode 100644
index 00000000..6a74c72a
--- /dev/null
+++ b/docs/reference/settings.md
@@ -0,0 +1,162 @@
+# Settings Reference
+
+Reference for dashboard and backend settings available from `codex auth login` -> `Settings`.
+
+* * *
+
+## Where Settings Are Saved
+
+- `~/.codex/multi-auth/settings.json`
+- under:
+  - `dashboardDisplaySettings`
+  - `pluginConfig`
+
+If `CODEX_MULTI_AUTH_DIR` is set, this root changes accordingly.
+
+* * *
+
+## Dashboard Settings (User-Facing)
+
+### Account List View
+
+Controls account-row content and layout:
+
+- status badge visibility
+- current badge visibility
+- last-used visibility
+- limit bars visibility
+- cooldown visibility
+- fetch-status visibility
+- current-row highlighting
+- smart sort enable/mode
+- compact vs expanded layout
+
+### Summary Fields
+
+Controls detail-line fields and order:
+
+- last-used
+- limits
+- status
+
+### Behavior
+
+Controls result-screen return and menu refresh behavior:
+
+- auto-return delay
+- pause-on-key behavior
+- auto-fetch limits
+- limit fetch TTL
+
+### Theme
+
+Controls color scheme:
+
+- base theme preset
+- accent color
+- focus style
+
+* * *
+
+## Advanced Backend Categories
+
+### 1) Session & Sync
+
+Typical controls:
+
+- `liveAccountSync`
+- `liveAccountSyncDebounceMs`
+- `liveAccountSyncPollMs`
+- `sessionAffinity`
+- `sessionAffinityTtlMs`
+- `sessionAffinityMaxEntries`
+- `perProjectAccounts`
+
+### 2) Rotation & Quota
+
+Typical controls:
+
+- `preemptiveQuotaEnabled`
+- `preemptiveQuotaRemainingPercent5h`
+- `preemptiveQuotaRemainingPercent7d`
+- `preemptiveQuotaMaxDeferralMs`
+- `retryAllAccountsRateLimited`
+- `retryAllAccountsMaxWaitMs`
+- `retryAllAccountsMaxRetries`
+
+### 3) Refresh & Recovery
+
+Typical controls:
+
+- `tokenRefreshSkewMs`
+- `proactiveRefreshGuardian`
+- `proactiveRefreshIntervalMs`
+- `proactiveRefreshBufferMs`
+- `sessionRecovery`
+- `autoResume`
+
+### 4) Performance & Timeouts
+
+Typical controls:
+
+- `parallelProbing`
+- `parallelProbingMaxConcurrency`
+- `fastSession`
+- `fastSessionStrategy`
+- `fastSessionMaxInputItems`
+- `emptyResponseMaxRetries`
+- `emptyResponseRetryDelayMs`
+- `fetchTimeoutMs`
+- `streamStallTimeoutMs`
+- `networkErrorCooldownMs`
+- `serverErrorCooldownMs`
+
+* * *
+
+## Recommended Defaults
+
+For most users, keep:
+
+- smart sort enabled
+- auto-fetch limits enabled
+- live sync enabled
+- session affinity enabled
+- preemptive quota deferral enabled
+- proactive refresh guardian enabled
+
+* * *
+
+## Environment Overrides
+
+Important env overrides that can supersede file settings:
+
+- `CODEX_MULTI_AUTH_DIR`
+- `CODEX_MULTI_AUTH_CONFIG_PATH`
+- `CODEX_MODE`
+- `CODEX_TUI_V2`
+- `CODEX_AUTH_FETCH_TIMEOUT_MS`
+- `CODEX_AUTH_STREAM_STALL_TIMEOUT_MS`
+
+Full field inventory:
+
+- [../development/CONFIG_FIELDS.md](../development/CONFIG_FIELDS.md)
+
+* * *
+
+## Validation
+
+After changing settings:
+
+```bash
+codex auth status
+codex auth check
+codex auth forecast --live
+```
+
+* * *
+
+## Related
+
+- [commands.md](commands.md)
+- [storage-paths.md](storage-paths.md)
+- [../configuration.md](../configuration.md)
diff --git a/docs/reference/storage-paths.md b/docs/reference/storage-paths.md
new file mode 100644
index 00000000..e0db27f0
--- /dev/null
+++ b/docs/reference/storage-paths.md
@@ -0,0 +1,80 @@
+# Storage Paths Reference
+
+Canonical and legacy file paths for account/settings/runtime data.
+
+* * *
+
+## Canonical Root
+
+Default root:
+
+- `~/.codex/multi-auth`
+
+Override root:
+
+- `CODEX_MULTI_AUTH_DIR=<path>`
+
+* * *
+
+## Canonical Files
+
+| File | Default path |
+| --- | --- |
+| Unified settings | `~/.codex/multi-auth/settings.json` |
+| Accounts | `~/.codex/multi-auth/openai-codex-accounts.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` |
+| Quota cache | `~/.codex/multi-auth/quota-cache.json` |
+| Logs | `~/.codex/multi-auth/logs/codex-plugin/` |
+| Cache | `~/.codex/multi-auth/cache/` |
+| Codex CLI accounts | `~/.codex/accounts.json` |
+| Codex CLI auth | `~/.codex/auth.json` |
+
+Notes:
+
+- `~/.codex/multi-auth/*` is owned by this project.
+- `~/.codex/auth.json` and `~/.codex/accounts.json` are owned by official Codex CLI and may be synced by this project.
+
+* * *
+
+## Project-Scoped Account Paths
+
+When project-scoped behavior is enabled, account files are namespaced under:
+
+- `~/.codex/multi-auth/projects/<project-key>/openai-codex-accounts.json`
+
+`<project-key>` is derived from normalized project path + short hash.
+
+* * *
+
+## Legacy Compatibility Paths
+
+Legacy compatibility paths may still be detected/read during migration.
+Exact legacy path values are internal compatibility details and are not part of the canonical user workflow.
+
+Example legacy roots that might be discovered in older installs:
+
+- `~/.opencode/`
+- `~/DevTools/config/codex/`
+
+Canonical behavior should be documented against `~/.codex/multi-auth`.
+
+* * *
+
+## Verify Paths in Your Environment
+
+```bash
+codex auth status
+codex auth list
+```
+
+Inspect files manually if needed.
+
+* * *
+
+## Related
+
+- [../configuration.md](../configuration.md)
+- [../upgrade.md](../upgrade.md)
+- [../privacy.md](../privacy.md)
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index 7b610535..c1671752 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -1,642 +1,139 @@
-# Troubleshooting Guide
+# Troubleshooting
 
-Common issues and debugging techniques for the OpenCode OpenAI Codex Auth Plugin.
+Use this page when login, switching, quota checks, or command routing fails.
 
----
+* * *
 
-> **Quick Reset**: Most issues can be resolved by deleting `~/.opencode/auth/openai.json` and running `opencode auth login` again.
+## 60-Second Recovery Flow
 
----
-
-## Known Limitations
-
-<details>
-<summary><b>✅ RESOLVED: OpenCode plugin blocking (v4.9.0+)</b></summary>
-
-**Status:** Fixed in v4.9.0 by renaming the package.
-
-**What was happening:**
-
-OpenCode's plugin loader explicitly skips plugins with `opencode-openai-codex-auth` in the name:
-
-```typescript
-if (plugin.includes("opencode-openai-codex-auth") || plugin.includes("opencode-copilot-auth")) continue
-```
-
-**Resolution:**
-
-The package was renamed from `opencode-openai-codex-auth-multi` to `codex-multi-auth`, which bypasses this check.
-
-**If you were using the old package:**
-
-Update your `~/.config/opencode/opencode.json`:
-```json
-{
-  "plugin": ["codex-multi-auth@latest"]
-}
-```
-
-**Tracking:** [Issue #11](https://github.com/ndycode/codex-multi-auth/issues/11)
-
-</details>
-
----
-
-## Installation & Loading Issues
-
-<details open>
-<summary><b>Plugin not downloading / no logs</b></summary>
-
-**Symptoms:**
-- Plugin folder missing under `~/.cache/opencode/node_modules/`
-- No files in `~/.opencode/logs/codex-plugin/` even with logging enabled
-
-**Checks:**
-1. **Verify config path and plugin list**:
-   - Global: `~/.config/opencode/opencode.json`
-   - Project: `./.opencode.json`
-   - Entry should include: `"plugin": ["codex-multi-auth@latest"]`
-2. **Confirm plugin cache location** (npm plugins are cached, not stored in `~/.opencode/plugins/`):
-   ```bash
-   ls ~/.cache/opencode/node_modules/codex-multi-auth
-   ```
-3. **Remember: request logs only appear after the first OpenAI request**:
-   ```bash
-   ENABLE_PLUGIN_REQUEST_LOGGING=1 opencode run "test" --model=openai/gpt-5.2
-   ```
-4. **Check registry access**:
-   ```bash
-   npm view codex-multi-auth version
-   ```
-5. **If the plugin is present but still won’t load**, upgrade to v4.8.1+ (fixes Node ESM load issues with `@opencode-ai/plugin`).
-
-</details>
-
----
-
-## Performance & Latency
-
-<details open>
-<summary><b>Slow first response / startup latency</b></summary>
-
-**What’s normal:**
-- The first request may fetch **Codex instructions** and/or the **OpenCode codex prompt** from GitHub.
-- v4.14.1+ uses **stale-while-revalidate caching** and a **startup prewarm** to reduce first-turn latency.
-
-**Tuning knobs:**
-1. Disable prewarm (if you prefer zero background fetches at startup):
-   ```bash
-   CODEX_AUTH_PREWARM=0 opencode
-   ```
-2. Enable fast-session mode (recommended: `hybrid`) to speed up trivial/interactive turns without changing defaults for complex prompts:
-   ```json
-   // ~/.opencode/codex-multi-auth-config.json
-   {
-     "fastSession": true,
-     "fastSessionStrategy": "hybrid",
-     "fastSessionMaxInputItems": 24
-   }
-   ```
-   Or via env:
-   ```bash
-   CODEX_AUTH_FAST_SESSION=1 opencode
-   ```
-
-**Note:** `fastSessionStrategy: "always"` forces fast tuning even on complex prompts and can reduce depth. Use `hybrid` unless you explicitly want maximum speed.
-
-</details>
-
----
-
-## Authentication Issues
-
-<details open>
-<summary><b>401 Unauthorized Error</b></summary>
-
-**Symptoms:**
-```
-Error: 401 Unauthorized
-Failed to access Codex API
-```
-
-**Causes:**
-1. Token expired
-2. Not authenticated yet
-3. Invalid credentials
-
-**Solutions:**
-
-1. **Re-authenticate:**
-   ```bash
-   opencode auth login
-   ```
-
-2. **Check auth file exists:**
-   ```bash
-   cat ~/.opencode/auth/openai.json
-   # Should show OAuth credentials
-   ```
-
-3. **Check token expiration:**
-   ```bash
-   cat ~/.opencode/auth/openai.json | jq '.expires'
-   date +%s000  # Compare to current timestamp
-   ```
-
-4. **Collect diagnostics from the error payload:**
-   - Newer versions include `diagnostics` on 401 responses (for example `requestId` and `cfRay`).
-   - Share those IDs when filing an issue so upstream auth failures are easier to trace.
-
-</details>
-
-<details>
-<summary><b>Browser Doesn't Open for OAuth</b></summary>
-
-**Symptoms:**
-- `opencode auth login` succeeds but no browser window
-- OAuth callback times out
-
-**Solutions:**
-
-1. **Manual URL paste:**
-   - Re-run `opencode auth login`
-   - Select **"ChatGPT Plus/Pro (Manual URL Paste)"**
-   - Paste the full redirect URL after login
-
-2. **Check port 1455 availability:**
-   ```bash
-   # macOS/Linux
-   lsof -i :1455
-   
-   # Windows
-   netstat -ano | findstr :1455
-   ```
-
-3. **Stop Codex CLI if running** — both use port 1455
-
-</details>
-
-<details>
-<summary><b>Authorization Session Expired</b></summary>
-
-**Symptoms:**
-- Browser shows: `Your authorization session was not initialized or has expired`
-
-**Solutions:**
-- Re-run `opencode auth login` to generate a fresh URL
-- Open the URL directly in browser (don't use a stale link)
-- For SSH/WSL/remote, use **"Manual URL Paste"** option
-
-</details>
-
-<details>
-<summary><b>403 Forbidden Error</b></summary>
-
-**Cause:** ChatGPT subscription issue
-
-**Check:**
-1. Active ChatGPT Plus or Pro subscription
-2. Subscription not expired
-3. Billing is current
-
-**Solution:** Visit [ChatGPT](https://chatgpt.com) and verify subscription status
-
-</details>
-
-<details>
-<summary><b>"Usage not included in your plan"</b></summary>
-
-**Symptoms:**
-- Requests fail with: `Usage not included in your plan`
-- Often reported on Business/Team workspaces
-
-**Cause:** The plugin is using the wrong workspace/account id (personal vs business).
-
-**Solutions:**
-1. Upgrade to `codex-multi-auth@5.1.0` or newer (workspace routing logic was hardened for Business + Personal dual accounts).
-2. Re-run `opencode auth login` and select the correct workspace when prompted.
-3. If running non-interactively, set `CODEX_AUTH_ACCOUNT_ID` to the workspace account id and re-login.
-4. Verify the workspace has Codex access in the ChatGPT UI.
-
-</details>
-
-<details>
-<summary><b>"All N account(s) failed (server errors or auth issues)"</b></summary>
-
-**Symptoms:**
-- Request loop ends with `All 14 account(s) failed ...` (count varies)
-- Frequent retries, then hard failure
-
-**Common causes:**
-1. Most accounts in the pool have expired/invalid refresh tokens
-2. Account pool contains duplicate stale accounts
-3. Temporary upstream/server failures across all available accounts
-
-**Solutions:**
-1. Re-auth at least one known-good account first:
-   ```bash
-   opencode auth login
-   ```
-2. Check account storage health (global and project-scoped):
-   - `~/.opencode/openai-codex-accounts.json`
-   - `~/.opencode/projects/<project-key>/openai-codex-accounts.json`
-   - `~/.opencode/openai-codex-flagged-accounts.json`
-3. Remove obviously stale/duplicate entries and keep only verified accounts.
-4. Re-run with logging and inspect per-account failures:
-   ```bash
-   DEBUG_CODEX_PLUGIN=1 ENABLE_PLUGIN_REQUEST_LOGGING=1 opencode run "ping" --model=openai/gpt-5-codex
-   ```
-5. If you only need personal Plus/Pro usage, ensure login selected the intended personal workspace/account id.
-
-</details>
-
----
-
-## Model Issues
-
-<details open>
-<summary><b>Model Not Found</b></summary>
-
-**Error:** `Model 'openai/gpt-5-codex-low' not found`
-
-**Cause 1: Config key mismatch**
-
-Check your config:
-```json
-{
-  "models": {
-    "gpt-5-codex-low": { ... }  // ← This is the key
-  }
-}
-```
-
-CLI must match exactly:
 ```bash
-opencode run "test" --model=openai/gpt-5-codex-low  # Must match config key
-```
-
-**Cause 2: Missing provider prefix**
-
-| Wrong | Correct |
-|-------|---------|
-| `--model=gpt-5-codex-low` | `--model=openai/gpt-5-codex-low` |
-
-</details>
-
-<details>
-<summary><b>Per-Model Options Not Applied</b></summary>
-
-**Symptom:** All models behave the same despite different `reasoningEffort`
-
-**Debug:**
-```bash
-DEBUG_CODEX_PLUGIN=1 opencode run "test" --model=openai/your-model
-```
-
-**Look for:**
-```
-hasModelSpecificConfig: true  ← Should be true
-resolvedConfig: { reasoningEffort: 'low', ... }  ← Should show your options
+codex auth doctor --fix
+codex auth check
+codex auth forecast --live
 ```
 
-**Common causes:**
-1. Model name in CLI doesn't match config key
-2. Typo in config file
-3. Wrong config file location
-
-</details>
-
-<details>
-<summary><b>"Model is not supported when using Codex with a ChatGPT account"</b></summary>
-
-**Symptoms:**
-- Request fails with an entitlement-style 400/403 mentioning model support for ChatGPT Codex OAuth
-- Common after switching workspaces or selecting a model your workspace is not currently entitled to
-
-**Cause:** The selected model is currently not entitled for the active ChatGPT account/workspace.
-
-**Solutions:**
-1. Re-auth/login to refresh workspace selection:
-   ```bash
-   opencode auth login
-   ```
-2. Add another entitled account/workspace. The plugin tries remaining accounts/workspaces before model fallback.
-3. Enable fallback policy only if you want automatic model downgrades:
-   ```bash
-   CODEX_AUTH_UNSUPPORTED_MODEL_POLICY=fallback opencode
-   ```
-4. Default fallback chain (when policy is `fallback` and not overridden):
-   - `gpt-5.3-codex -> gpt-5-codex -> gpt-5.2-codex`
-   - `gpt-5.3-codex-spark -> gpt-5-codex -> gpt-5.3-codex -> gpt-5.2-codex` (if Spark IDs are selected manually)
-   - `gpt-5.2-codex -> gpt-5-codex`
-   - `gpt-5.1-codex -> gpt-5-codex`
-   - Spark entitlement failures trigger fallback immediately (no full account/workspace traversal), even when policy is `strict`
-5. Configure a custom fallback chain in `~/.opencode/codex-multi-auth-config.json`:
-   ```json
-   {
-     "unsupportedCodexPolicy": "fallback",
-     "fallbackOnUnsupportedCodexModel": true,
-     "unsupportedCodexFallbackChain": {
-       "gpt-5-codex": ["gpt-5.2-codex"],
-       "gpt-5.3-codex": ["gpt-5-codex", "gpt-5.2-codex"],
-       "gpt-5.3-codex-spark": ["gpt-5-codex", "gpt-5.3-codex", "gpt-5.2-codex"]
-     }
-   }
-   ```
-6. Use strict mode (no model fallback) for explicit entitlement failures:
-   ```bash
-   CODEX_AUTH_UNSUPPORTED_MODEL_POLICY=strict opencode
-   ```
-7. Legacy compatibility toggle (only controls `gpt-5.3-codex -> gpt-5.2-codex`):
-   ```bash
-   CODEX_AUTH_FALLBACK_GPT53_TO_GPT52=0 opencode
-   ```
-8. Legacy generic fallback toggle compatibility:
-   ```bash
-   CODEX_AUTH_FALLBACK_UNSUPPORTED_MODEL=1 opencode
-   ```
-9. Verify effective upstream model when debugging Spark/fallback behavior:
-   ```bash
-   ENABLE_PLUGIN_REQUEST_LOGGING=1 CODEX_PLUGIN_LOG_BODIES=1 opencode run "ping" --model=openai/gpt-5.3-codex-spark
-   ```
-   Then inspect `~/.opencode/logs/codex-plugin/request-*-after-transform.json` (`.body.model`). The TUI can keep showing the selected label while fallback is applied internally.
-
-</details>
-
----
-
-## Multi-Turn Issues
-
-<details open>
-<summary><b>Item Not Found Errors</b></summary>
-
-**Error:**
-```
-AI_APICallError: Item with id 'msg_abc123' not found.
-Items are not persisted when `store` is set to false.
-```
-
-**Cause:** Old plugin version (fixed in v2.1.2+)
+If still broken:
 
-**Solution:**
 ```bash
-npx -y codex-multi-auth@latest
-opencode
+codex auth login
 ```
 
-**Verify fix:**
-```bash
-DEBUG_CODEX_PLUGIN=1 opencode
-> write test.txt
-> read test.txt
-> what did you write?
-```
+* * *
 
-Should see: `Successfully removed all X message IDs`
+## Symptom -> Action
 
-</details>
+| Symptom | Likely cause | Action |
+| --- | --- | --- |
+| Browser opens during login | Expected OAuth behavior | Complete auth in browser and return to same terminal |
+| `codex auth` unrecognized | Wrapper command path conflict | Run `where codex`, then `codex multi auth status` |
+| Account switch says success but wrong account in Codex | Stale Codex auth state sync | Run `codex auth switch <index>`, then restart `codex` session |
+| `missing field id_token` | Old/stale auth state payload | Re-login account with `codex auth login` |
+| `refresh_token_reused` | Refresh token already rotated by newer token pair | Re-login that account |
+| `token_expired` | Token no longer valid | Re-login that account |
+| All accounts unhealthy | Entire pool stale/invalid | `codex auth doctor --fix`, then add one fresh account |
+| Menu feels stale or delayed | Limits not refreshed yet | Wait for auto-fetch or run `codex auth check` |
+| OAuth callback port `1455` busy | Another process is using callback port | Stop conflicting process and retry |
 
-<details>
-<summary><b>Context Not Preserved</b></summary>
+* * *
 
-**Symptom:** Model doesn't remember previous turns
+## Useful Diagnostics
 
-**Check logs:**
 ```bash
-ENABLE_PLUGIN_REQUEST_LOGGING=1 CODEX_PLUGIN_LOG_BODIES=1 opencode
-> first message
-> second message
+codex auth list
+codex auth status
+codex auth check
+codex auth verify-flagged --json
+codex auth forecast --live
+codex auth fix --dry-run
+codex auth report --live --json
+codex auth doctor --json
 ```
 
-**Verify:**
-```bash
-cat ~/.opencode/logs/codex-plugin/request-*-after-transform.json | jq '.body.input | length'
-# Should show increasing count (3, 5, 7, 9, ...)
-```
-
-**What to check:**
-1. Full message history present (not just current turn)
-2. No `item_reference` items (filtered out)
-3. All IDs stripped
-
-</details>
+* * *
 
----
+## Verify Command Routing
 
-## Request Errors
-
-<details open>
-<summary><b>400 Bad Request</b></summary>
-
-**Debug:**
 ```bash
-ENABLE_PLUGIN_REQUEST_LOGGING=1 opencode run "test"
-cat ~/.opencode/logs/codex-plugin/request-*-error-response.json
-```
-
-**Common causes:**
-1. Invalid options for model (e.g., `minimal` for gpt-5-codex)
-2. Malformed request body
-3. Unsupported parameter
-
-</details>
-
-<details>
-<summary><b>Rate Limit Exceeded</b></summary>
-
-**Error:**
-```
-Rate limit reached for gpt-5-codex
+where codex
+codex --version
+codex auth status
+codex multi auth status
 ```
 
-**Solutions:**
+Expected:
 
-1. **Wait for reset:**
-   ```bash
-   cat ~/.opencode/logs/codex-plugin/request-*-response.json | jq '.headers["x-codex-primary-reset-after-seconds"]'
-   ```
+- `codex auth ...` works.
+- `codex multi auth ...` alias works.
+- Non-auth `codex` commands open official Codex CLI.
 
-2. **Add more accounts:**
-   ```bash
-   opencode auth login  # Add another account
-   ```
+* * *
 
-3. **Switch model family:**
-   ```bash
-   opencode run "task" --model=openai/gpt-5.1
-   ```
+## Logging
 
-</details>
+Use this only for plugin-host request debugging (not required for normal `codex auth ...` dashboard usage).
 
-<details>
-<summary><b>Context Window Exceeded</b></summary>
+Bash:
 
-**Error:**
-```
-Your input exceeds the context window
-```
-
-**Solutions:**
-1. Exit and restart OpenCode (clears history)
-2. Use compact mode (if OpenCode supports it)
-3. Switch to model with larger context
-
-</details>
-
----
-
-## OAuth Callback Issues
-
-<details>
-<summary><b>Safari OAuth Callback Fails (macOS)</b></summary>
-
-**Symptoms:**
-- "fail to authorize" after successful login
-- Safari shows "Safari can't open the page"
-
-**Cause:** Safari's "HTTPS-Only Mode" blocks `http://localhost` callback.
-
-**Solutions:**
-
-1. **Use Chrome or Firefox** (easiest)
-
-2. **Disable HTTPS-Only Mode temporarily:**
-   - Safari > Settings (⌘,) > Privacy
-   - Uncheck "Enable HTTPS-Only Mode"
-   - Run `opencode auth login`
-   - Re-enable after authentication
-
-</details>
-
-<details>
-<summary><b>Port Conflict (Address Already in Use)</b></summary>
-
-**macOS / Linux:**
 ```bash
-lsof -i :1455
-kill -9 <PID>
-opencode auth login
+DEBUG_CODEX_PLUGIN=1 ENABLE_PLUGIN_REQUEST_LOGGING=1 CODEX_PLUGIN_LOG_BODIES=1 <run-your-host-request-command>
 ```
 
-**Windows (PowerShell):**
+PowerShell:
+
 ```powershell
-netstat -ano | findstr :1455
-taskkill /PID <PID> /F
-opencode auth login
+$env:DEBUG_CODEX_PLUGIN='1'
+$env:ENABLE_PLUGIN_REQUEST_LOGGING='1'
+$env:CODEX_PLUGIN_LOG_BODIES='1'
+<run-your-host-request-command>
 ```
 
-</details>
-
-<details>
-<summary><b>Docker / WSL2 / Remote Development</b></summary>
+cmd.exe:
 
-OAuth callback requires browser to reach `localhost` on the machine running OpenCode.
-
-**WSL2:**
-- Use VS Code's port forwarding, or
-- Configure Windows → WSL port forwarding
-
-**SSH / Remote:**
-```bash
-ssh -L 1455:localhost:1455 user@remote
+```bat
+set DEBUG_CODEX_PLUGIN=1
+set ENABLE_PLUGIN_REQUEST_LOGGING=1
+set CODEX_PLUGIN_LOG_BODIES=1
+<run-your-host-request-command>
 ```
 
-**Docker / Containers:**
-- OAuth with localhost redirect doesn't work in containers
-- Use SSH port forwarding or manual URL flow
-
-</details>
-
----
+Default log location:
 
-## Debug Techniques
-
-<details open>
-<summary><b>Enable Full Logging</b></summary>
-
-```bash
-DEBUG_CODEX_PLUGIN=1 ENABLE_PLUGIN_REQUEST_LOGGING=1 CODEX_PLUGIN_LOG_BODIES=1 opencode run "test"
-```
+- `~/.codex/multi-auth/logs/codex-plugin/`
 
-**What you get:**
-- Console: Debug messages showing config resolution
-- Files: Request/response metadata logs
-- Files: Raw payloads included because `CODEX_PLUGIN_LOG_BODIES=1` is set (sensitive)
+* * *
 
-**Log locations:**
-- `~/.opencode/logs/codex-plugin/request-*-before-transform.json`
-- `~/.opencode/logs/codex-plugin/request-*-after-transform.json`
-- `~/.opencode/logs/codex-plugin/request-*-response.json`
+## Soft Reset
 
-</details>
+1. Backup account and settings files.
+2. Remove stale local state.
+3. Re-login one known-good account first.
 
-<details>
-<summary><b>Inspect Actual API Requests</b></summary>
+Bash:
 
 ```bash
-ENABLE_PLUGIN_REQUEST_LOGGING=1 CODEX_PLUGIN_LOG_BODIES=1 opencode run "test" --model=openai/gpt-5.2-low
-
-cat ~/.opencode/logs/codex-plugin/request-*-after-transform.json | jq '{
-  model: .body.model,
-  reasoning: .body.reasoning,
-  text: .body.text,
-  store: .body.store,
-  include: .body.include
-}'
+rm -f ~/.codex/multi-auth/openai-codex-accounts.json
+rm -f ~/.codex/multi-auth/openai-codex-flagged-accounts.json
+rm -f ~/.codex/multi-auth/settings.json
+codex auth login
 ```
 
-**Verify:**
-- `model`: Normalized correctly?
-- `reasoning.effort`: Matches your config?
-- `store`: Should be `false`
-- `include`: Should have `reasoning.encrypted_content`
+PowerShell:
 
-</details>
-
----
-
-## Getting Help
-
-### Before Opening an Issue
-
-1. **Enable logging:**
-   ```bash
-   DEBUG_CODEX_PLUGIN=1 ENABLE_PLUGIN_REQUEST_LOGGING=1 opencode run "your command"
-   ```
-
-2. **Collect info:**
-   - OpenCode version: `opencode --version`
-   - Plugin version: Check `package.json` or npm
-   - Error logs from `~/.opencode/logs/codex-plugin/`
-   - Config file (redact sensitive info)
+```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
+```
 
-3. **Check existing issues:**
-   [GitHub Issues](https://github.com/ndycode/codex-multi-auth/issues)
+* * *
 
-### Reporting Bugs
+## Before Opening an Issue
 
 Include:
-- Error message
-- Steps to reproduce
-- Config file (redacted)
-- Log files
-- OpenCode version
-- Plugin version
-
-### Account or Subscription Issues
-
-| Issue | Solution |
-|-------|----------|
-| Auth problems | Verify subscription at [ChatGPT Settings](https://chatgpt.com/settings) |
-| Free tier | Not supported — requires Plus or Pro |
-| Usage limits | Check subscription limits |
-| Account flagged | Contact OpenAI support |
-
-**To revoke and re-authorize:**
-1. Revoke: [ChatGPT Settings → Authorized Apps](https://chatgpt.com/settings/apps)
-2. Remove tokens: `opencode auth logout`
-3. Re-authenticate: `opencode auth login`
-
----
-
-**Next**: [Configuration Guide](configuration.md) | [Architecture](development/ARCHITECTURE.md) | [Back to Home](index.md)
+
+- `codex auth report --json`
+- `codex auth doctor --json`
+- `codex --version`
+- `npm ls -g codex-multi-auth`
+- failing command and full output
diff --git a/docs/upgrade.md b/docs/upgrade.md
new file mode 100644
index 00000000..f264f9ae
--- /dev/null
+++ b/docs/upgrade.md
@@ -0,0 +1,103 @@
+# Upgrade Guide
+
+Migrate safely from older command/path layouts to the current Codex-first workflow.
+
+* * *
+
+## What Changed
+
+| Area | Older flow | Current flow |
+| --- | --- | --- |
+| Primary auth command | mixed legacy command forms | `codex auth ...` |
+| Main account menu | mixed command/UI paths | `codex auth login` dashboard |
+| Settings location | split config files | unified `~/.codex/multi-auth/settings.json` |
+| Canonical accounts path | mixed legacy storage | `~/.codex/multi-auth/openai-codex-accounts.json` |
+
+Compatibility note:
+
+- Legacy files are still read when discovered for migration compatibility.
+
+* * *
+
+## Current Canonical Paths
+
+- `~/.codex/multi-auth/settings.json`
+- `~/.codex/multi-auth/openai-codex-accounts.json`
+- `~/.codex/multi-auth/openai-codex-flagged-accounts.json`
+- `~/.codex/multi-auth/quota-cache.json`
+
+Legacy compatibility paths may still appear in older environments and are migrated automatically.
+
+* * *
+
+## Recommended Migration Sequence
+
+1. Refresh Codex CLI and this project:
+
+```bash
+npm install -g @openai/codex
+npm install
+npm run build
+npm link
+```
+
+1. Confirm command routing:
+
+```bash
+codex --version
+codex auth status
+```
+
+1. Re-login and rebuild account pool:
+
+```bash
+codex auth login
+codex auth check
+```
+
+1. Validate active behavior:
+
+```bash
+codex auth list
+codex auth forecast --live
+```
+
+1. (Optional) refresh plugin-host config:
+
+```bash
+codex-multi-auth --modern
+```
+
+* * *
+
+## Post-Upgrade Verification
+
+```bash
+codex auth report --live --json
+codex auth doctor --fix --dry-run
+```
+
+Optional plugin-host smoke test (only if you use host mode):
+
+```bash
+<run your plugin-host smoke command in your host environment>
+```
+
+* * *
+
+## Common Upgrade Problems
+
+| Problem | Action |
+| --- | --- |
+| `codex auth` not found | `where codex` (Windows) or `which codex` (macOS/Linux), ensure wrapper path is active |
+| Old command habits | Use `codex auth ...` as canonical workflow |
+| Accounts look stale | `codex auth doctor --fix` then re-login impacted accounts |
+| Mixed path confusion | Check [reference/storage-paths.md](reference/storage-paths.md) |
+
+* * *
+
+## Related
+
+- [getting-started.md](getting-started.md)
+- [troubleshooting.md](troubleshooting.md)
+- [reference/storage-paths.md](reference/storage-paths.md)
diff --git a/index.ts b/index.ts
index 7e2b056f..758f8657 100644
--- a/index.ts
+++ b/index.ts
@@ -30,6 +30,7 @@ import {
         createAuthorizationFlow,
         exchangeAuthorizationCode,
         parseAuthorizationInput,
+        redactOAuthUrlForLog,
         REDIRECT_URI,
 } from "./lib/auth/auth.js";
 import { queuedRefresh } from "./lib/refresh-queue.js";
@@ -61,6 +62,22 @@ import {
 	getCodexTuiV2,
 	getCodexTuiColorProfile,
 	getCodexTuiGlyphMode,
+	getLiveAccountSync,
+	getLiveAccountSyncDebounceMs,
+	getLiveAccountSyncPollMs,
+	getSessionAffinity,
+	getSessionAffinityTtlMs,
+	getSessionAffinityMaxEntries,
+	getProactiveRefreshGuardian,
+	getProactiveRefreshIntervalMs,
+	getProactiveRefreshBufferMs,
+	getNetworkErrorCooldownMs,
+	getServerErrorCooldownMs,
+	getStorageBackupEnabled,
+	getPreemptiveQuotaEnabled,
+	getPreemptiveQuotaRemainingPercent5h,
+	getPreemptiveQuotaRemainingPercent7d,
+	getPreemptiveQuotaMaxDeferralMs,
 	loadPluginConfig,
 } from "./lib/config.js";
 import {
@@ -114,6 +131,7 @@ import {
 	clearFlaggedAccounts,
 	StorageError,
 	formatStorageErrorHint,
+	setStorageBackupEnabled,
 	type AccountStorageV3,
 	type FlaggedAccountMetadataV1,
 } from "./lib/storage.js";
@@ -137,6 +155,23 @@ import {
 } from "./lib/request/rate-limit-backoff.js";
 import { isEmptyResponse } from "./lib/request/response-handler.js";
 import { addJitter } from "./lib/rotation.js";
+import { SessionAffinityStore } from "./lib/session-affinity.js";
+import { LiveAccountSync } from "./lib/live-account-sync.js";
+import { RefreshGuardian } from "./lib/refresh-guardian.js";
+import {
+	evaluateFailurePolicy,
+	type FailoverMode,
+} from "./lib/request/failure-policy.js";
+import {
+	EntitlementCache,
+	resolveEntitlementAccountKey,
+} from "./lib/entitlement-cache.js";
+import {
+	PreemptiveQuotaScheduler,
+	readQuotaSchedulerSnapshot,
+} from "./lib/preemptive-quota-scheduler.js";
+import { CapabilityPolicyStore } from "./lib/capability-policy.js";
+import { withStreamingFailover } from "./lib/request/stream-failover.js";
 import { buildTableHeader, buildTableRow, type TableOptions } from "./lib/table-formatter.js";
 import { setUiRuntimeOptions, type UiRuntimeOptions } from "./lib/ui/runtime.js";
 import { paintUiText, formatUiBadge, formatUiHeader, formatUiItem, formatUiKeyValue, formatUiSection } from "./lib/ui/format.js";
@@ -165,6 +200,7 @@ import {
 	createHashlineEditTool,
 	createHashlineReadTool,
 } from "./lib/tools/hashline-tools.js";
+import { registerCleanup } from "./lib/shutdown.js";
 
 /**
  * OpenAI Codex OAuth authentication plugin for opencode
@@ -191,9 +227,70 @@ export const OpenAIOAuthPlugin: Plugin = async ({ client }: PluginInput) => {
 	let startupPrewarmTriggered = false;
 	let lastCodexCliActiveSyncIndex: number | null = null;
 	let perProjectStorageWarningShown = false;
+	let liveAccountSync: LiveAccountSync | null = null;
+	let liveAccountSyncPath: string | null = null;
+	let refreshGuardian: RefreshGuardian | null = null;
+	let refreshGuardianConfigKey: string | null = null;
+	let sessionAffinityStore: SessionAffinityStore | null = new SessionAffinityStore();
+	let sessionAffinityConfigKey: string | null = null;
+	const entitlementCache = new EntitlementCache();
+	const preemptiveQuotaScheduler = new PreemptiveQuotaScheduler();
+	const capabilityPolicyStore = new CapabilityPolicyStore();
+	let accountReloadInFlight: Promise<AccountManager> | null = null;
 	const exposeAdvancedCodexTools =
 		(process.env.CODEX_MULTI_AUTH_EXPOSE_ADMIN_TOOLS ?? "").trim() === "1";
 	const MIN_BACKOFF_MS = 100;
+	const STREAM_FAILOVER_MAX_BY_MODE: Record<FailoverMode, number> = {
+		aggressive: 1,
+		balanced: 2,
+		conservative: 2,
+	};
+	const STREAM_FAILOVER_SOFT_TIMEOUT_BY_MODE: Record<FailoverMode, number> = {
+		aggressive: 10_000,
+		balanced: 15_000,
+		conservative: 20_000,
+	};
+
+	const parseFailoverMode = (value: string | undefined): FailoverMode => {
+		const normalized = (value ?? "").trim().toLowerCase();
+		if (normalized === "aggressive") return "aggressive";
+		if (normalized === "conservative") return "conservative";
+		return "balanced";
+	};
+
+	const parseEnvInt = (value: string | undefined): number | undefined => {
+		if (value === undefined) return undefined;
+		const parsed = Number.parseInt(value, 10);
+		return Number.isFinite(parsed) ? parsed : undefined;
+	};
+
+	const sanitizeResponseHeadersForLog = (headers: Headers): Record<string, string> => {
+		const allowed = new Set([
+			"content-type",
+			"x-request-id",
+			"x-openai-request-id",
+			"x-codex-plan-type",
+			"x-codex-active-limit",
+			"x-codex-primary-used-percent",
+			"x-codex-primary-window-minutes",
+			"x-codex-primary-reset-at",
+			"x-codex-primary-reset-after-seconds",
+			"x-codex-secondary-used-percent",
+			"x-codex-secondary-window-minutes",
+			"x-codex-secondary-reset-at",
+			"x-codex-secondary-reset-after-seconds",
+			"retry-after",
+			"x-ratelimit-reset",
+			"x-ratelimit-reset-requests",
+		]);
+		const sanitized: Record<string, string> = {};
+		for (const [rawName, rawValue] of headers.entries()) {
+			const name = rawName.toLowerCase();
+			if (!allowed.has(name)) continue;
+			sanitized[name] = rawValue;
+		}
+		return sanitized;
+	};
 
 	type RuntimeMetrics = {
 		startedAt: number;
@@ -203,9 +300,14 @@ export const OpenAIOAuthPlugin: Plugin = async ({ client }: PluginInput) => {
 		rateLimitedResponses: number;
 		serverErrors: number;
 		networkErrors: number;
+		userAborts: number;
 		authRefreshFailures: number;
 		emptyResponseRetries: number;
 		accountRotations: number;
+		sameAccountRetries: number;
+		streamFailoverAttempts: number;
+		streamFailoverRecoveries: number;
+		streamFailoverCrossAccountRecoveries: number;
 		cumulativeLatencyMs: number;
 		lastRequestAt: number | null;
 		lastError: string | null;
@@ -219,9 +321,14 @@ export const OpenAIOAuthPlugin: Plugin = async ({ client }: PluginInput) => {
 		rateLimitedResponses: 0,
 		serverErrors: 0,
 		networkErrors: 0,
+		userAborts: 0,
 		authRefreshFailures: 0,
 		emptyResponseRetries: 0,
 		accountRotations: 0,
+		sameAccountRetries: 0,
+		streamFailoverAttempts: 0,
+		streamFailoverRecoveries: 0,
+		streamFailoverCrossAccountRecoveries: 0,
 		cumulativeLatencyMs: 0,
 		lastRequestAt: null,
 		lastError: null,
@@ -339,7 +446,7 @@ export const OpenAIOAuthPlugin: Plugin = async ({ client }: PluginInput) => {
 		forceNewLogin: boolean = false,
 	): Promise<TokenResult> => {
 		const { pkce, state, url } = await createAuthorizationFlow({ forceNewLogin });
-		logInfo(`OAuth URL: ${url}`);
+		logInfo(`OAuth URL: ${redactOAuthUrlForLog(url)}`);
 
                 let serverInfo: Awaited<ReturnType<typeof startLocalOAuthServer>> | null = null;
                 try {
@@ -676,8 +783,28 @@ export const OpenAIOAuthPlugin: Plugin = async ({ client }: PluginInput) => {
 			accountManagerPromise = null;
 		};
 
+		const reloadAccountManagerFromDisk = async (
+			authFallback?: OAuthAuthDetails,
+		): Promise<AccountManager> => {
+			if (accountReloadInFlight) {
+				return accountReloadInFlight;
+			}
+			accountReloadInFlight = (async () => {
+				const reloaded = await AccountManager.loadFromDisk(authFallback);
+				cachedAccountManager = reloaded;
+				accountManagerPromise = Promise.resolve(reloaded);
+				return reloaded;
+			})();
+			try {
+				return await accountReloadInFlight;
+			} finally {
+				accountReloadInFlight = null;
+			}
+		};
+
 		const applyAccountStorageScope = (pluginConfig: ReturnType<typeof loadPluginConfig>): void => {
 			const perProjectAccounts = getPerProjectAccounts(pluginConfig);
+			setStorageBackupEnabled(getStorageBackupEnabled(pluginConfig));
 			if (isCodexCliSyncEnabled()) {
 				if (perProjectAccounts && !perProjectStorageWarningShown) {
 					perProjectStorageWarningShown = true;
@@ -692,6 +819,118 @@ export const OpenAIOAuthPlugin: Plugin = async ({ client }: PluginInput) => {
 			setStoragePath(perProjectAccounts ? process.cwd() : null);
 		};
 
+		const ensureLiveAccountSync = async (
+			pluginConfig: ReturnType<typeof loadPluginConfig>,
+			authFallback?: OAuthAuthDetails,
+		): Promise<void> => {
+			if (!getLiveAccountSync(pluginConfig)) {
+				if (liveAccountSync) {
+					liveAccountSync.stop();
+					liveAccountSync = null;
+					liveAccountSyncPath = null;
+				}
+				return;
+			}
+
+			const targetPath = getStoragePath();
+			if (!liveAccountSync) {
+				liveAccountSync = new LiveAccountSync(
+					async () => {
+						await reloadAccountManagerFromDisk(authFallback);
+					},
+					{
+						debounceMs: getLiveAccountSyncDebounceMs(pluginConfig),
+						pollIntervalMs: getLiveAccountSyncPollMs(pluginConfig),
+					},
+				);
+				registerCleanup(() => {
+					liveAccountSync?.stop();
+				});
+			}
+
+		if (liveAccountSyncPath !== targetPath) {
+			let switched = false;
+			for (let attempt = 0; attempt < 3; attempt += 1) {
+				try {
+					await liveAccountSync.syncToPath(targetPath);
+					liveAccountSyncPath = targetPath;
+					switched = true;
+					break;
+				} catch (error) {
+					const code = (error as NodeJS.ErrnoException | undefined)?.code;
+					if (code !== "EBUSY" && code !== "EPERM") {
+						throw error;
+					}
+					await new Promise((resolve) => setTimeout(resolve, 25 * 2 ** attempt));
+				}
+			}
+			if (!switched) {
+				logWarn(
+					`[${PLUGIN_NAME}] Live account sync path switch failed due to transient filesystem locks; keeping previous watcher.`,
+				);
+			}
+		}
+	};
+
+		const ensureRefreshGuardian = (
+			pluginConfig: ReturnType<typeof loadPluginConfig>,
+		): void => {
+			if (!getProactiveRefreshGuardian(pluginConfig)) {
+				if (refreshGuardian) {
+					refreshGuardian.stop();
+					refreshGuardian = null;
+					refreshGuardianConfigKey = null;
+				}
+				return;
+			}
+
+			const intervalMs = getProactiveRefreshIntervalMs(pluginConfig);
+			const bufferMs = getProactiveRefreshBufferMs(pluginConfig);
+			const configKey = `${intervalMs}:${bufferMs}`;
+			if (refreshGuardian && refreshGuardianConfigKey === configKey) return;
+
+			if (refreshGuardian) {
+				refreshGuardian.stop();
+			}
+			refreshGuardian = new RefreshGuardian(
+				() => cachedAccountManager,
+				{ intervalMs, bufferMs },
+			);
+			refreshGuardianConfigKey = configKey;
+			refreshGuardian.start();
+			registerCleanup(() => {
+				refreshGuardian?.stop();
+			});
+		};
+
+		const ensureSessionAffinity = (
+			pluginConfig: ReturnType<typeof loadPluginConfig>,
+		): void => {
+			if (!getSessionAffinity(pluginConfig)) {
+				sessionAffinityStore = null;
+				sessionAffinityConfigKey = null;
+				return;
+			}
+
+			const ttlMs = getSessionAffinityTtlMs(pluginConfig);
+			const maxEntries = getSessionAffinityMaxEntries(pluginConfig);
+			const configKey = `${ttlMs}:${maxEntries}`;
+			if (sessionAffinityStore && sessionAffinityConfigKey === configKey) return;
+			sessionAffinityStore = new SessionAffinityStore({ ttlMs, maxEntries });
+			sessionAffinityConfigKey = configKey;
+		};
+
+		const applyPreemptiveQuotaSettings = (
+			pluginConfig: ReturnType<typeof loadPluginConfig>,
+		): void => {
+			preemptiveQuotaScheduler.configure({
+				enabled: getPreemptiveQuotaEnabled(pluginConfig),
+				remainingPercentThresholdPrimary: getPreemptiveQuotaRemainingPercent5h(pluginConfig),
+				remainingPercentThresholdSecondary: getPreemptiveQuotaRemainingPercent7d(pluginConfig),
+				maxDeferralMs: getPreemptiveQuotaMaxDeferralMs(pluginConfig),
+			});
+		};
+
         // Event handler for session recovery and account selection
         const eventHandler = async (input: { event: { type: string; properties?: unknown } }) => {
           try {
@@ -733,13 +972,11 @@ export const OpenAIOAuthPlugin: Plugin = async ({ client }: PluginInput) => {
 				}
 				lastCodexCliActiveSyncIndex = index;
 
-                                // Reload manager from disk so we don't overwrite newer rotated
-                                // refresh tokens with stale in-memory state.
-                                if (cachedAccountManager) {
-                                        const reloadedManager = await AccountManager.loadFromDisk();
-                                        cachedAccountManager = reloadedManager;
-                                        accountManagerPromise = Promise.resolve(reloadedManager);
-                                }
+				// Reload manager from disk so we don't overwrite newer rotated
+				// refresh tokens with stale in-memory state.
+				if (cachedAccountManager) {
+					await reloadAccountManagerFromDisk();
+				}
 
                                 await showToast(`Switched to account ${index + 1}`, "info");
                         }
@@ -775,6 +1012,9 @@ export const OpenAIOAuthPlugin: Plugin = async ({ client }: PluginInput) => {
 			const pluginConfig = loadPluginConfig();
 			applyUiRuntimeFromConfig(pluginConfig);
 			applyAccountStorageScope(pluginConfig);
+			ensureSessionAffinity(pluginConfig);
+			ensureRefreshGuardian(pluginConfig);
+			applyPreemptiveQuotaSettings(pluginConfig);
 
 			// Only handle OAuth auth type, skip API key auth
 			if (auth.type !== "oauth") {
@@ -790,7 +1030,6 @@ export const OpenAIOAuthPlugin: Plugin = async ({ client }: PluginInput) => {
 					`[${PLUGIN_NAME}] Auth is missing multiAccount marker; continuing with single-account compatibility mode`,
 				);
 			}
-
 				// Acquire mutex for thread-safe initialization
 				// Use while loop to handle multiple concurrent waiters correctly
 				while (loaderMutex) {
@@ -802,12 +1041,14 @@ export const OpenAIOAuthPlugin: Plugin = async ({ client }: PluginInput) => {
 					resolveMutex = resolve;
 				});
 				try {
+					await ensureLiveAccountSync(pluginConfig, auth);
 					if (!accountManagerPromise) {
-						accountManagerPromise = AccountManager.loadFromDisk(
-							auth as OAuthAuthDetails,
-						);
+						await reloadAccountManagerFromDisk(auth as OAuthAuthDetails);
 					}
-					let accountManager = await accountManagerPromise;
+					const managerPromise =
+						accountManagerPromise ??
+						reloadAccountManagerFromDisk(auth as OAuthAuthDetails);
+					let accountManager = await managerPromise;
 					cachedAccountManager = accountManager;
 					const refreshToken =
 						auth.type === "oauth" ? auth.refresh : "";
@@ -820,7 +1061,7 @@ export const OpenAIOAuthPlugin: Plugin = async ({ client }: PluginInput) => {
 
 					if (accountManager.getAccountCount() === 0) {
 						logDebug(
-							`[${PLUGIN_NAME}] No OAuth accounts available (run opencode auth login)`,
+							`[${PLUGIN_NAME}] No OAuth accounts available (run codex login)`,
 						);
 						return {};
 					}
@@ -853,6 +1094,26 @@ export const OpenAIOAuthPlugin: Plugin = async ({ client }: PluginInput) => {
 				const toastDurationMs = getToastDurationMs(pluginConfig);
 				const fetchTimeoutMs = getFetchTimeoutMs(pluginConfig);
 				const streamStallTimeoutMs = getStreamStallTimeoutMs(pluginConfig);
+				const networkErrorCooldownMs = getNetworkErrorCooldownMs(pluginConfig);
+				const serverErrorCooldownMs = getServerErrorCooldownMs(pluginConfig);
+				const failoverMode = parseFailoverMode(process.env.CODEX_AUTH_FAILOVER_MODE);
+				const streamFailoverMax = Math.max(
+					0,
+					parseEnvInt(process.env.CODEX_AUTH_STREAM_FAILOVER_MAX) ??
+						STREAM_FAILOVER_MAX_BY_MODE[failoverMode],
+				);
+				const streamFailoverSoftTimeoutMs = Math.max(
+					1_000,
+					parseEnvInt(process.env.CODEX_AUTH_STREAM_STALL_SOFT_TIMEOUT_MS) ??
+						STREAM_FAILOVER_SOFT_TIMEOUT_BY_MODE[failoverMode],
+				);
+				const streamFailoverHardTimeoutMs = Math.max(
+					streamFailoverSoftTimeoutMs,
+					parseEnvInt(process.env.CODEX_AUTH_STREAM_STALL_HARD_TIMEOUT_MS) ??
+						streamStallTimeoutMs,
+				);
+				const maxSameAccountRetries =
+					failoverMode === "conservative" ? 2 : failoverMode === "balanced" ? 1 : 0;
 
 				const sessionRecoveryEnabled = getSessionRecovery(pluginConfig);
 				const autoResumeEnabled = getAutoResume(pluginConfig);
@@ -1028,6 +1289,13 @@ export const OpenAIOAuthPlugin: Plugin = async ({ client }: PluginInput) => {
 							(process.env.CODEX_THREAD_ID ?? promptCacheKey ?? "")
 								.toString()
 								.trim() || undefined;
+						const sessionAffinityKey = threadIdCandidate ?? promptCacheKey ?? null;
+						const effectivePromptCacheKey =
+							(sessionAffinityKey ?? promptCacheKey ?? "").toString().trim() || undefined;
+						const preferredSessionAccountIndex = sessionAffinityStore?.getPreferredAccountIndex(
+							sessionAffinityKey,
+						);
+						sessionAffinityStore?.prune();
 							const requestCorrelationId = setCorrelationId(
 								threadIdCandidate ? `${threadIdCandidate}:${Date.now()}` : undefined,
 							);
@@ -1100,9 +1368,76 @@ export const OpenAIOAuthPlugin: Plugin = async ({ client }: PluginInput) => {
 										const accountCount = accountManager.getAccountCount();
 										const attempted = new Set<number>();
 										let restartAccountTraversalWithFallback = false;
+										let usedPreferredSessionAccount = false;
+										const capabilityBoostByAccount: Record<number, number> = {};
+										type AccountSnapshotCandidate = {
+											index: number;
+											accountId?: string;
+											email?: string;
+										};
+										const accountSnapshotSource = accountManager as {
+											getAccountsSnapshot?: () => AccountSnapshotCandidate[];
+											getAccountByIndex?: (index: number) => AccountSnapshotCandidate | null;
+										};
+										const accountSnapshotList =
+											typeof accountSnapshotSource.getAccountsSnapshot === "function"
+												? accountSnapshotSource.getAccountsSnapshot() ?? []
+												: [];
+										if (
+											accountSnapshotList.length === 0 &&
+											typeof accountSnapshotSource.getAccountByIndex === "function"
+										) {
+											for (
+												let accountSnapshotIndex = 0;
+												accountSnapshotIndex < accountCount;
+												accountSnapshotIndex += 1
+											) {
+												const candidate = accountSnapshotSource.getAccountByIndex(
+													accountSnapshotIndex,
+												);
+												if (candidate) {
+													accountSnapshotList.push(candidate);
+												}
+											}
+										}
+										for (const candidate of accountSnapshotList) {
+											const accountKey = resolveEntitlementAccountKey(candidate);
+											capabilityBoostByAccount[candidate.index] = capabilityPolicyStore.getBoost(
+												accountKey,
+												model ?? modelFamily,
+											);
+										}
 
 while (attempted.size < Math.max(1, accountCount)) {
-				const account = accountManager.getCurrentOrNextForFamilyHybrid(modelFamily, model, { pidOffsetEnabled });
+				let account = null;
+				if (
+					!usedPreferredSessionAccount &&
+					typeof preferredSessionAccountIndex === "number"
+				) {
+					usedPreferredSessionAccount = true;
+					if (
+						accountManager.isAccountAvailableForFamily(
+							preferredSessionAccountIndex,
+							modelFamily,
+							model,
+						)
+					) {
+						account = accountManager.getAccountByIndex(preferredSessionAccountIndex);
+						if (account) {
+							account.lastUsed = Date.now();
+							accountManager.markSwitched(account, "rotation", modelFamily);
+						}
+					} else {
+						sessionAffinityStore?.forgetSession(sessionAffinityKey);
+					}
+				}
+
+				if (!account) {
+					account = accountManager.getCurrentOrNextForFamilyHybrid(modelFamily, model, {
+						pidOffsetEnabled,
+						scoreBoostByAccount: capabilityBoostByAccount,
+					});
+				}
 				if (!account || attempted.has(account.index)) {
 					break;
 				}
@@ -1131,25 +1466,39 @@ while (attempted.size < Math.max(1, accountCount)) {
 				runtimeMetrics.lastError = (err as Error)?.message ?? String(err);
 				const failures = accountManager.incrementAuthFailures(account);
 				const accountLabel = formatAccountLabel(account, account.index);
-				
-				if (failures >= ACCOUNT_LIMITS.MAX_AUTH_FAILURES_BEFORE_REMOVAL) {
+
+				const authFailurePolicy = evaluateFailurePolicy({
+					kind: "auth-refresh",
+					consecutiveAuthFailures: failures,
+				});
+				sessionAffinityStore?.forgetSession(sessionAffinityKey);
+
+				if (authFailurePolicy.removeAccount) {
+					const removedIndex = account.index;
+					sessionAffinityStore?.forgetAccount(removedIndex);
 					accountManager.removeAccount(account);
+					sessionAffinityStore?.reindexAfterRemoval(removedIndex);
 					accountManager.saveToDiskDebounced();
 					await showToast(
-						`Removed ${accountLabel} after ${failures} consecutive auth failures. Run 'opencode auth login' to re-add.`,
+						`Removed ${accountLabel} after ${failures} consecutive auth failures. Run 'codex login' to re-add.`,
 						"error",
 						{ duration: toastDurationMs * 2 },
 					);
 					continue;
 				}
-				
-				accountManager.markAccountCoolingDown(
-								account,
-								ACCOUNT_LIMITS.AUTH_FAILURE_COOLDOWN_MS,
-								"auth-failure",
-							);
-						accountManager.saveToDiskDebounced();
-						continue;
+
+				if (
+					typeof authFailurePolicy.cooldownMs === "number" &&
+					authFailurePolicy.cooldownReason
+				) {
+					accountManager.markAccountCoolingDown(
+						account,
+						authFailurePolicy.cooldownMs,
+						authFailurePolicy.cooldownReason,
+					);
+				}
+				accountManager.saveToDiskDebounced();
+				continue;
 					}
 
 				const hadAccountId = !!account.accountId;
@@ -1159,6 +1508,11 @@ while (attempted.size < Math.max(1, accountCount)) {
 						account.accountIdSource,
 						tokenAccountId,
 					);
+					const entitlementAccountKey = resolveEntitlementAccountKey({
+						accountId: hadAccountId ? account.accountId : undefined,
+						email: account.email,
+						index: account.index,
+					});
 						if (!accountId) {
 							accountManager.markAccountCoolingDown(
 								account,
@@ -1174,6 +1528,18 @@ while (attempted.size < Math.max(1, accountCount)) {
 											}
 											account.email =
 												extractAccountEmail(accountAuth.access) ?? account.email;
+											const entitlementBlock = entitlementCache.isBlocked(
+												entitlementAccountKey,
+												model ?? modelFamily,
+											);
+											if (entitlementBlock.blocked) {
+												runtimeMetrics.accountRotations++;
+												runtimeMetrics.lastError = `Entitlement cached block for account ${account.index + 1}`;
+												logWarn(
+													`Skipping account ${account.index + 1} due to cached entitlement block (${formatWaitTime(entitlementBlock.waitMs)} remaining).`,
+												);
+												continue;
+											}
 
 											if (
 												accountCount > 1 &&
@@ -1196,12 +1562,29 @@ while (attempted.size < Math.max(1, accountCount)) {
 									accountAuth.access,
 									{
 										model,
-										promptCacheKey,
+										promptCacheKey: effectivePromptCacheKey,
 									},
 								);
+								const quotaScheduleKey = `${entitlementAccountKey}:${model ?? modelFamily}`;
+								const capabilityModelKey = model ?? modelFamily;
+								const quotaDeferral = preemptiveQuotaScheduler.getDeferral(quotaScheduleKey);
+								if (quotaDeferral.defer && quotaDeferral.waitMs > 0) {
+									accountManager.markRateLimitedWithReason(
+										account,
+										quotaDeferral.waitMs,
+										modelFamily,
+										"quota",
+										model,
+									);
+									accountManager.recordRateLimit(account, modelFamily, model);
+									runtimeMetrics.accountRotations++;
+									runtimeMetrics.lastError = `Preemptive quota deferral for account ${account.index + 1}`;
+									accountManager.saveToDiskDebounced();
+									continue;
+								}
 
-								// Consume a token before making the request for proactive rate limiting
-								const tokenConsumed = accountManager.consumeToken(account, modelFamily, model);
+							// Consume a token before making the request for proactive rate limiting
+					const tokenConsumed = accountManager.consumeToken(account, modelFamily, model);
 								if (!tokenConsumed) {
 									accountManager.recordRateLimit(account, modelFamily, model);
 									runtimeMetrics.accountRotations++;
@@ -1213,6 +1596,8 @@ while (attempted.size < Math.max(1, accountCount)) {
 									break;
 								}
 
+							let sameAccountRetryCount = 0;
+							let successAccountForResponse = account;
 							while (true) {
 								let response: Response;
 								const fetchStart = performance.now();
@@ -1236,7 +1621,7 @@ while (attempted.size < Math.max(1, accountCount)) {
 									abortSignal.addEventListener("abort", onUserAbort, { once: true });
 								}
 
-								try {
+							try {
 								runtimeMetrics.totalRequests++;
 								response = await fetch(url, {
 									...requestInit,
@@ -1244,14 +1629,61 @@ while (attempted.size < Math.max(1, accountCount)) {
 									signal: fetchController.signal,
 								});
 				} catch (networkError) {
+								const isUserAbort =
+									abortSignal?.aborted ||
+									(networkError instanceof Error &&
+										(networkError.name === "AbortError" || /abort/i.test(networkError.message)));
+								if (isUserAbort) {
+									runtimeMetrics.userAborts++;
+									runtimeMetrics.lastError = "request aborted by user";
+									sessionAffinityStore?.forgetSession(sessionAffinityKey);
+									break;
+								}
 								const errorMsg = networkError instanceof Error ? networkError.message : String(networkError);
 								logWarn(`Network error for account ${account.index + 1}: ${errorMsg}`);
 								runtimeMetrics.failedRequests++;
 								runtimeMetrics.networkErrors++;
 								runtimeMetrics.accountRotations++;
 								runtimeMetrics.lastError = errorMsg;
-								accountManager.refundToken(account, modelFamily, model);
-								accountManager.recordFailure(account, modelFamily, model);
+								const policy = evaluateFailurePolicy(
+									{ kind: "network", failoverMode },
+									{ networkCooldownMs: networkErrorCooldownMs },
+								);
+								if (policy.refundToken) {
+									accountManager.refundToken(account, modelFamily, model);
+								}
+								if (policy.recordFailure) {
+									accountManager.recordFailure(account, modelFamily, model);
+									capabilityPolicyStore.recordFailure(
+										entitlementAccountKey,
+										capabilityModelKey,
+									);
+								}
+								if (
+									policy.retrySameAccount &&
+									sameAccountRetryCount < maxSameAccountRetries
+								) {
+									sameAccountRetryCount += 1;
+									runtimeMetrics.sameAccountRetries += 1;
+									const retryDelayMs = Math.max(
+										MIN_BACKOFF_MS,
+										Math.floor(policy.retryDelayMs ?? 250),
+									);
+									await sleep(addJitter(retryDelayMs, 0.2));
+									continue;
+								}
+								if (
+									typeof policy.cooldownMs === "number" &&
+									policy.cooldownReason
+								) {
+									accountManager.markAccountCoolingDown(
+										account,
+										policy.cooldownMs,
+										policy.cooldownReason,
+									);
+									accountManager.saveToDiskDebounced();
+								}
+								sessionAffinityStore?.forgetSession(sessionAffinityKey);
 								break;
 								} finally {
 									clearTimeout(fetchTimeoutId);
@@ -1261,15 +1693,22 @@ while (attempted.size < Math.max(1, accountCount)) {
 								}
 											const fetchLatencyMs = Math.round(performance.now() - fetchStart);
 
-											logRequest(LOG_STAGES.RESPONSE, {
-												status: response.status,
-												ok: response.ok,
-												statusText: response.statusText,
-												latencyMs: fetchLatencyMs,
-												headers: Object.fromEntries(response.headers.entries()),
-											});
+												logRequest(LOG_STAGES.RESPONSE, {
+													status: response.status,
+													ok: response.ok,
+													statusText: response.statusText,
+													latencyMs: fetchLatencyMs,
+													headers: sanitizeResponseHeadersForLog(response.headers),
+												});
+												const quotaSnapshot = readQuotaSchedulerSnapshot(
+													response.headers,
+													response.status,
+												);
+												if (quotaSnapshot) {
+													preemptiveQuotaScheduler.update(quotaScheduleKey, quotaSnapshot);
+												}
 
-								if (!response.ok) {
+									if (!response.ok) {
 									const contextOverflowResult = await handleContextOverflow(response, model);
 									if (contextOverflowResult.handled) {
 										return contextOverflowResult.response;
@@ -1297,13 +1736,27 @@ while (attempted.size < Math.max(1, accountCount)) {
 			// accounts before degrading the model via fallback.
 			// Spark entitlement is commonly unavailable on non-Pro/Business workspaces;
 			// force direct fallback instead of traversing every account/workspace first.
-			if (
-				unsupportedModelInfo.isUnsupported &&
-				hasRemainingAccounts &&
-				!shouldForceSparkFallback
-			) {
-				accountManager.refundToken(account, modelFamily, model);
-				accountManager.recordFailure(account, modelFamily, model);
+				if (
+					unsupportedModelInfo.isUnsupported &&
+					hasRemainingAccounts &&
+					!shouldForceSparkFallback
+				) {
+					entitlementCache.markBlocked(
+						entitlementAccountKey,
+						blockedModel,
+						"unsupported-model",
+					);
+					capabilityPolicyStore.recordUnsupported(
+						entitlementAccountKey,
+						blockedModel,
+					);
+										accountManager.refundToken(account, modelFamily, model);
+										accountManager.recordFailure(account, modelFamily, model);
+										capabilityPolicyStore.recordFailure(
+											entitlementAccountKey,
+											capabilityModelKey,
+										);
+										sessionAffinityStore?.forgetSession(sessionAffinityKey);
 				account.lastSwitchReason = "rotation";
 				runtimeMetrics.lastError = `Unsupported model on account ${account.index + 1}: ${blockedModel}`;
 				logWarn(
@@ -1328,12 +1781,21 @@ while (attempted.size < Math.max(1, accountCount)) {
 				customChain: unsupportedCodexFallbackChain,
 			});
 
-			if (fallbackModel) {
-				const previousModel = model ?? "gpt-5-codex";
-				const previousModelFamily = modelFamily;
-				attemptedUnsupportedFallbackModels.add(previousModel);
-				attemptedUnsupportedFallbackModels.add(fallbackModel);
-				accountManager.refundToken(account, previousModelFamily, previousModel);
+				if (fallbackModel) {
+					const previousModel = model ?? "gpt-5-codex";
+					const previousModelFamily = modelFamily;
+					attemptedUnsupportedFallbackModels.add(previousModel);
+					attemptedUnsupportedFallbackModels.add(fallbackModel);
+					entitlementCache.markBlocked(
+						entitlementAccountKey,
+						previousModel,
+						"unsupported-model",
+					);
+					capabilityPolicyStore.recordUnsupported(
+						entitlementAccountKey,
+						previousModel,
+					);
+					accountManager.refundToken(account, previousModelFamily, previousModel);
 
 				model = fallbackModel;
 				modelFamily = getModelFamily(model);
@@ -1379,6 +1841,15 @@ while (attempted.size < Math.max(1, accountCount)) {
 			}
 
 			if (unsupportedModelInfo.isUnsupported && !allowUnsupportedFallback) {
+				entitlementCache.markBlocked(
+					entitlementAccountKey,
+					blockedModel,
+					"unsupported-model",
+				);
+				capabilityPolicyStore.recordUnsupported(
+					entitlementAccountKey,
+					blockedModel,
+				);
 				runtimeMetrics.lastError = `Unsupported model (strict): ${blockedModel}`;
 				logWarn(
 					`Model ${blockedModel} is unsupported for this ChatGPT account. Strict policy blocks automatic fallback.`,
@@ -1396,6 +1867,33 @@ while (attempted.size < Math.max(1, accountCount)) {
 					{ duration: toastDurationMs },
 				);
 			}
+			if (
+				unsupportedModelInfo.isUnsupported &&
+				allowUnsupportedFallback &&
+				!hasRemainingAccounts &&
+				!fallbackModel
+			) {
+				entitlementCache.markBlocked(
+					entitlementAccountKey,
+					blockedModel,
+					"unsupported-model",
+				);
+				capabilityPolicyStore.recordUnsupported(
+					entitlementAccountKey,
+					blockedModel,
+				);
+			}
+			if (errorResponse.status === 403 && !unsupportedModelInfo.isUnsupported) {
+				entitlementCache.markBlocked(
+					entitlementAccountKey,
+					model ?? modelFamily,
+					"plan-entitlement",
+				);
+				capabilityPolicyStore.recordFailure(
+					entitlementAccountKey,
+					capabilityModelKey,
+				);
+			}
 
 			if (recoveryHook && errorBody && isRecoverableError(errorBody)) {
 					const errorType = detectErrorType(errorBody);
@@ -1415,19 +1913,60 @@ while (attempted.size < Math.max(1, accountCount)) {
 						runtimeMetrics.serverErrors++;
 						runtimeMetrics.accountRotations++;
 						runtimeMetrics.lastError = `HTTP ${response.status}`;
-						accountManager.refundToken(account, modelFamily, model);
-						accountManager.recordFailure(account, modelFamily, model);
+						const policy = evaluateFailurePolicy(
+							{ kind: "server", failoverMode },
+							{ serverCooldownMs: serverErrorCooldownMs },
+						);
+						if (policy.refundToken) {
+							accountManager.refundToken(account, modelFamily, model);
+						}
+							if (policy.recordFailure) {
+								accountManager.recordFailure(account, modelFamily, model);
+								capabilityPolicyStore.recordFailure(
+									entitlementAccountKey,
+									capabilityModelKey,
+								);
+							}
+						if (
+							policy.retrySameAccount &&
+							sameAccountRetryCount < maxSameAccountRetries
+						) {
+							sameAccountRetryCount += 1;
+							runtimeMetrics.sameAccountRetries += 1;
+							const retryDelayMs = Math.max(
+								MIN_BACKOFF_MS,
+								Math.floor(policy.retryDelayMs ?? 500),
+							);
+							await sleep(addJitter(retryDelayMs, 0.2));
+							continue;
+						}
+						if (
+							typeof policy.cooldownMs === "number" &&
+							policy.cooldownReason
+						) {
+							accountManager.markAccountCoolingDown(
+								account,
+								policy.cooldownMs,
+								policy.cooldownReason,
+							);
+							accountManager.saveToDiskDebounced();
+						}
+						sessionAffinityStore?.forgetSession(sessionAffinityKey);
 						break;
 					}
 
 					if (rateLimit) {
 																														runtimeMetrics.rateLimitedResponses++;
-																														const { attempt, delayMs } = getRateLimitBackoff(
-																															account.index,
-																															quotaKey,
-																															rateLimit.retryAfterMs,
-																														);
-																														const waitLabel = formatWaitTime(delayMs);
+																															const { attempt, delayMs } = getRateLimitBackoff(
+																																account.index,
+																																quotaKey,
+																																rateLimit.retryAfterMs,
+																															);
+																															preemptiveQuotaScheduler.markRateLimited(
+																																quotaScheduleKey,
+																																delayMs,
+																															);
+																															const waitLabel = formatWaitTime(delayMs);
 
 																														if (delayMs <= RATE_LIMIT_SHORT_RETRY_THRESHOLD_MS) {
 																																if (
@@ -1457,6 +1996,7 @@ while (attempted.size < Math.max(1, accountCount)) {
 				);
 				accountManager.recordRateLimit(account, modelFamily, model);
 				account.lastSwitchReason = "rate-limit";
+				sessionAffinityStore?.forgetSession(sessionAffinityKey);
 				runtimeMetrics.accountRotations++;
 				accountManager.saveToDiskDebounced();
 						logWarn(
@@ -1477,18 +2017,228 @@ while (attempted.size < Math.max(1, accountCount)) {
 																									);
 																																	accountManager.markToastShown(account.index);
 																																}
-																														break;
-																													}
-																													runtimeMetrics.failedRequests++;
-																													runtimeMetrics.lastError = `HTTP ${response.status}`;
-																													return errorResponse;
+																															break;
+																														}
+																														if (
+																															!rateLimit &&
+																															!unsupportedModelInfo.isUnsupported &&
+																															errorResponse.status !== 403
+																														) {
+																															capabilityPolicyStore.recordFailure(
+																																entitlementAccountKey,
+																																capabilityModelKey,
+																															);
+																														}
+																														runtimeMetrics.failedRequests++;
+																														runtimeMetrics.lastError = `HTTP ${response.status}`;
+																														return errorResponse;
 																											}
 
-					resetRateLimitBackoff(account.index, quotaKey);
-					runtimeMetrics.cumulativeLatencyMs += fetchLatencyMs;
-					const successResponse = await handleSuccessResponse(response, isStreaming, {
-						streamStallTimeoutMs,
-					});
+						resetRateLimitBackoff(account.index, quotaKey);
+						runtimeMetrics.cumulativeLatencyMs += fetchLatencyMs;
+						let responseForSuccess = response;
+						if (isStreaming) {
+							const streamFallbackCandidateOrder = [
+								account.index,
+								...accountManager
+									.getAccountsSnapshot()
+									.map((candidate) => candidate.index)
+									.filter((index) => index !== account.index),
+							];
+							responseForSuccess = withStreamingFailover(
+								response,
+								async (failoverAttempt, emittedBytes) => {
+									if (abortSignal?.aborted) {
+										return null;
+									}
+									runtimeMetrics.streamFailoverAttempts += 1;
+
+									for (const candidateIndex of streamFallbackCandidateOrder) {
+										if (abortSignal?.aborted) {
+											return null;
+										}
+										if (
+											!accountManager.isAccountAvailableForFamily(
+												candidateIndex,
+												modelFamily,
+												model,
+											)
+										) {
+											continue;
+										}
+
+										const fallbackAccount = accountManager.getAccountByIndex(candidateIndex);
+										if (!fallbackAccount) continue;
+
+										let fallbackAuth = accountManager.toAuthDetails(fallbackAccount) as OAuthAuthDetails;
+										try {
+											if (shouldRefreshToken(fallbackAuth, tokenRefreshSkewMs)) {
+												fallbackAuth = (await refreshAndUpdateToken(
+													fallbackAuth,
+													client,
+												)) as OAuthAuthDetails;
+												accountManager.updateFromAuth(fallbackAccount, fallbackAuth);
+												accountManager.clearAuthFailures(fallbackAccount);
+												accountManager.saveToDiskDebounced();
+											}
+										} catch (refreshError) {
+											logWarn(
+												`Stream failover refresh failed for account ${fallbackAccount.index + 1}.`,
+												{
+													error:
+														refreshError instanceof Error
+															? refreshError.message
+															: String(refreshError),
+												},
+											);
+											continue;
+										}
+
+										const fallbackTokenAccountId = extractAccountId(fallbackAuth.access);
+										const fallbackAccountId = resolveRequestAccountId(
+											fallbackAccount.accountId,
+											fallbackAccount.accountIdSource,
+											fallbackTokenAccountId,
+										);
+										if (!fallbackAccountId) {
+											continue;
+										}
+
+										if (!accountManager.consumeToken(fallbackAccount, modelFamily, model)) {
+											continue;
+										}
+
+										const fallbackHeaders = createCodexHeaders(
+											requestInit,
+											fallbackAccountId,
+											fallbackAuth.access,
+											{
+												model,
+												promptCacheKey: effectivePromptCacheKey,
+											},
+										);
+
+										const fallbackController = new AbortController();
+										const fallbackTimeoutId = setTimeout(
+											() => fallbackController.abort(new Error("Request timeout")),
+											fetchTimeoutMs,
+										);
+										const onFallbackAbort = abortSignal
+											? () =>
+													fallbackController.abort(
+														abortSignal.reason ?? new Error("Aborted by user"),
+													)
+											: null;
+										if (abortSignal && onFallbackAbort) {
+											abortSignal.addEventListener("abort", onFallbackAbort, {
+												once: true,
+											});
+										}
+
+										try {
+											runtimeMetrics.totalRequests++;
+											const fallbackResponse = await fetch(url, {
+												...requestInit,
+												headers: fallbackHeaders,
+												signal: fallbackController.signal,
+											});
+											const fallbackSnapshot = readQuotaSchedulerSnapshot(
+												fallbackResponse.headers,
+												fallbackResponse.status,
+											);
+											if (fallbackSnapshot) {
+												preemptiveQuotaScheduler.update(
+													`${resolveEntitlementAccountKey(fallbackAccount)}:${model ?? modelFamily}`,
+													fallbackSnapshot,
+												);
+											}
+											if (!fallbackResponse.ok) {
+												try {
+													await fallbackResponse.body?.cancel();
+												} catch {
+													// Best effort cleanup before trying next fallback account.
+												}
+												if (fallbackResponse.status === 429) {
+													const retryAfterRaw = fallbackResponse.headers
+														.get("retry-after")
+														?.trim();
+													const retryAfterMs =
+														retryAfterRaw && /^\d+$/.test(retryAfterRaw)
+															? Number.parseInt(retryAfterRaw, 10) * 1000
+															: 60_000;
+													accountManager.markRateLimitedWithReason(
+														fallbackAccount,
+														retryAfterMs,
+														modelFamily,
+														"quota",
+														model,
+													);
+													accountManager.recordRateLimit(fallbackAccount, modelFamily, model);
+												} else {
+													accountManager.recordFailure(fallbackAccount, modelFamily, model);
+												}
+												capabilityPolicyStore.recordFailure(
+													resolveEntitlementAccountKey(fallbackAccount),
+													capabilityModelKey,
+												);
+												continue;
+											}
+
+											successAccountForResponse = fallbackAccount;
+											runtimeMetrics.streamFailoverRecoveries += 1;
+											if (fallbackAccount.index !== account.index) {
+												runtimeMetrics.streamFailoverCrossAccountRecoveries += 1;
+												runtimeMetrics.accountRotations += 1;
+												sessionAffinityStore?.remember(
+													sessionAffinityKey,
+													fallbackAccount.index,
+												);
+											}
+
+											logInfo(
+												`Recovered stream via failover attempt ${failoverAttempt} using account ${fallbackAccount.index + 1}.`,
+												{ emittedBytes },
+											);
+											return fallbackResponse;
+										} catch (streamFailoverError) {
+											accountManager.refundToken(fallbackAccount, modelFamily, model);
+											accountManager.recordFailure(fallbackAccount, modelFamily, model);
+											capabilityPolicyStore.recordFailure(
+												resolveEntitlementAccountKey(fallbackAccount),
+												capabilityModelKey,
+											);
+											logWarn(
+												`Stream failover attempt ${failoverAttempt} failed for account ${fallbackAccount.index + 1}.`,
+												{
+													emittedBytes,
+													error:
+														streamFailoverError instanceof Error
+															? streamFailoverError.message
+															: String(streamFailoverError),
+												},
+											);
+											continue;
+										} finally {
+											clearTimeout(fallbackTimeoutId);
+											if (abortSignal && onFallbackAbort) {
+												abortSignal.removeEventListener("abort", onFallbackAbort);
+											}
+										}
+									}
+
+									return null;
+								},
+								{
+									maxFailovers: streamFailoverMax,
+									softTimeoutMs: streamFailoverSoftTimeoutMs,
+									hardTimeoutMs: streamFailoverHardTimeoutMs,
+									requestInstanceId: requestCorrelationId ?? undefined,
+								},
+							);
+						}
+						const successResponse = await handleSuccessResponse(responseForSuccess, isStreaming, {
+							streamStallTimeoutMs,
+						});
 
 					if (!isStreaming && emptyResponseMaxRetries > 0) {
 						const clonedResponse = successResponse.clone();
@@ -1507,6 +2257,30 @@ while (attempted.size < Math.max(1, accountCount)) {
 									);
 									accountManager.refundToken(account, modelFamily, model);
 									accountManager.recordFailure(account, modelFamily, model);
+									capabilityPolicyStore.recordFailure(
+										entitlementAccountKey,
+										capabilityModelKey,
+									);
+									const emptyPolicy = evaluateFailurePolicy({
+										kind: "empty-response",
+										failoverMode,
+									});
+									if (
+										emptyPolicy.retrySameAccount &&
+										sameAccountRetryCount < maxSameAccountRetries
+									) {
+										sameAccountRetryCount += 1;
+										runtimeMetrics.sameAccountRetries += 1;
+										const retryDelayMs = Math.max(
+											0,
+											Math.floor(emptyPolicy.retryDelayMs ?? emptyResponseRetryDelayMs),
+										);
+										if (retryDelayMs > 0) {
+											await sleep(addJitter(retryDelayMs, 0.2));
+										}
+										continue;
+									}
+									sessionAffinityStore?.forgetSession(sessionAffinityKey);
 									await sleep(addJitter(emptyResponseRetryDelayMs, 0.2));
 									break;
 								}
@@ -1517,12 +2291,25 @@ while (attempted.size < Math.max(1, accountCount)) {
 						}
 					}
 
-					accountManager.recordSuccess(account, modelFamily, model);
+						if (successAccountForResponse.index !== account.index) {
+							accountManager.markSwitched(successAccountForResponse, "rotation", modelFamily);
+						}
+						const successAccountKey = resolveEntitlementAccountKey(successAccountForResponse);
+						accountManager.recordSuccess(successAccountForResponse, modelFamily, model);
+						capabilityPolicyStore.recordSuccess(
+							successAccountKey,
+							capabilityModelKey,
+						);
+						entitlementCache.clear(successAccountKey, capabilityModelKey);
+						sessionAffinityStore?.remember(
+							sessionAffinityKey,
+							successAccountForResponse.index,
+						);
 					runtimeMetrics.successfulRequests++;
 					runtimeMetrics.lastError = null;
-					if (lastCodexCliActiveSyncIndex !== account.index) {
-						void accountManager.syncCodexCliActiveSelectionForIndex(account.index);
-						lastCodexCliActiveSyncIndex = account.index;
+					if (lastCodexCliActiveSyncIndex !== successAccountForResponse.index) {
+						void accountManager.syncCodexCliActiveSelectionForIndex(successAccountForResponse.index);
+						lastCodexCliActiveSyncIndex = successAccountForResponse.index;
 					}
 						return successResponse;
 																								}
@@ -1555,9 +2342,9 @@ while (attempted.size < Math.max(1, accountCount)) {
 								const waitLabel = waitMs > 0 ? formatWaitTime(waitMs) : "a bit";
 								const message =
 									count === 0
-										? "No Codex accounts configured. Run `opencode auth login`."
+										? "No Codex accounts configured. Run `codex login`."
 										: waitMs > 0
-											? `All ${count} account(s) are rate-limited. Try again in ${waitLabel} or add another account with \`opencode auth login\`.`
+											? `All ${count} account(s) are rate-limited. Try again in ${waitLabel} or add another account with \`codex login\`.`
 											: `All ${count} account(s) failed (server errors or auth issues). Check account health with \`codex-health\`.`;
 								runtimeMetrics.failedRequests++;
 								runtimeMetrics.lastError = message;
@@ -2586,7 +3373,7 @@ while (attempted.size < Math.max(1, accountCount)) {
 								...formatUiHeader(ui, "Codex accounts"),
 								"",
 								formatUiItem(ui, "No accounts configured.", "warning"),
-								formatUiItem(ui, "Run: opencode auth login", "accent"),
+								formatUiItem(ui, "Run: codex login", "accent"),
 								formatUiKeyValue(ui, "Storage", storePath, "muted"),
 							].join("\n");
 						}
@@ -2594,7 +3381,7 @@ while (attempted.size < Math.max(1, accountCount)) {
                                                         "No Codex accounts configured.",
                                                         "",
                                                         "Add accounts:",
-                                                        "  opencode auth login",
+                                                        "  codex login",
                                                         "",
                                                         `Storage: ${storePath}`,
                                                 ].join("\n");
@@ -2636,7 +3423,7 @@ while (attempted.size < Math.max(1, accountCount)) {
 
 						lines.push("");
 						lines.push(...formatUiSection(ui, "Commands"));
-						lines.push(formatUiItem(ui, "Add account: opencode auth login", "accent"));
+						lines.push(formatUiItem(ui, "Add account: codex login", "accent"));
 						lines.push(formatUiItem(ui, "Switch account: codex-switch <index>"));
 						lines.push(formatUiItem(ui, "Detailed status: codex-status"));
 						lines.push(formatUiItem(ui, "Health check: codex-health"));
@@ -2681,7 +3468,7 @@ while (attempted.size < Math.max(1, accountCount)) {
                                         lines.push(`Storage: ${storePath}`);
                                         lines.push("");
                                         lines.push("Commands:");
-                                        lines.push("  - Add account: opencode auth login");
+                                        lines.push("  - Add account: codex login");
                                         lines.push("  - Switch account: codex-switch");
                                         lines.push("  - Status details: codex-status");
                                         lines.push("  - Health check: codex-health");
@@ -2705,10 +3492,10 @@ while (attempted.size < Math.max(1, accountCount)) {
 								...formatUiHeader(ui, "Switch account"),
 								"",
 								formatUiItem(ui, "No accounts configured.", "warning"),
-								formatUiItem(ui, "Run: opencode auth login", "accent"),
+								formatUiItem(ui, "Run: codex login", "accent"),
 							].join("\n");
 						}
-                                                return "No Codex accounts configured. Run: opencode auth login";
+                                                return "No Codex accounts configured. Run: codex login";
                                         }
 
                                         const targetIndex = Math.floor((index ?? 0) - 1);
@@ -2755,11 +3542,9 @@ while (attempted.size < Math.max(1, accountCount)) {
 						return `Switched to ${formatAccountLabel(account, targetIndex)} but failed to persist. Changes may be lost on restart.`;
 					}
 
-                                        if (cachedAccountManager) {
-						const reloadedManager = await AccountManager.loadFromDisk();
-						cachedAccountManager = reloadedManager;
-						accountManagerPromise = Promise.resolve(reloadedManager);
-                                        }
+					if (cachedAccountManager) {
+						await reloadAccountManagerFromDisk();
+					}
 
                                         const label = formatAccountLabel(account, targetIndex);
 					if (ui.v2Enabled) {
@@ -2784,10 +3569,10 @@ while (attempted.size < Math.max(1, accountCount)) {
 								...formatUiHeader(ui, "Account status"),
 								"",
 								formatUiItem(ui, "No accounts configured.", "warning"),
-								formatUiItem(ui, "Run: opencode auth login", "accent"),
+								formatUiItem(ui, "Run: codex login", "accent"),
 							].join("\n");
 						}
-						return "No Codex accounts configured. Run: opencode auth login";
+						return "No Codex accounts configured. Run: codex login";
 					}
 
 				const now = Date.now();
@@ -2907,6 +3692,9 @@ while (attempted.size < Math.max(1, accountCount)) {
 						successful > 0
 							? Math.round(runtimeMetrics.cumulativeLatencyMs / successful)
 							: 0;
+					const liveSyncSnapshot = liveAccountSync?.getSnapshot();
+					const guardianStats = refreshGuardian?.getStats();
+					const sessionAffinityEntries = sessionAffinityStore?.size() ?? 0;
 					const lastRequest =
 						runtimeMetrics.lastRequestAt !== null
 							? `${formatWaitTime(now - runtimeMetrics.lastRequestAt)} ago`
@@ -2924,9 +3712,17 @@ while (attempted.size < Math.max(1, accountCount)) {
 						`Rate-limited responses: ${runtimeMetrics.rateLimitedResponses}`,
 						`Server errors (5xx): ${runtimeMetrics.serverErrors}`,
 						`Network errors: ${runtimeMetrics.networkErrors}`,
+						`User aborts: ${runtimeMetrics.userAborts}`,
 						`Auth refresh failures: ${runtimeMetrics.authRefreshFailures}`,
 						`Account rotations: ${runtimeMetrics.accountRotations}`,
+						`Same-account retries: ${runtimeMetrics.sameAccountRetries}`,
+						`Stream failover attempts: ${runtimeMetrics.streamFailoverAttempts}`,
+						`Stream failover recoveries: ${runtimeMetrics.streamFailoverRecoveries}`,
+						`Stream failover cross-account recoveries: ${runtimeMetrics.streamFailoverCrossAccountRecoveries}`,
 						`Empty-response retries: ${runtimeMetrics.emptyResponseRetries}`,
+						`Session affinity entries: ${sessionAffinityEntries}`,
+						`Live sync: ${liveSyncSnapshot?.running ? "on" : "off"} (${liveSyncSnapshot?.reloadCount ?? 0} reloads)`,
+						`Refresh guardian: ${guardianStats ? "on" : "off"} (${guardianStats?.refreshed ?? 0} refreshed, ${guardianStats?.failed ?? 0} failed)`,
 						`Last upstream request: ${lastRequest}`,
 					];
 
@@ -2946,9 +3742,34 @@ while (attempted.size < Math.max(1, accountCount)) {
 							formatUiKeyValue(ui, "Rate-limited responses", String(runtimeMetrics.rateLimitedResponses), "warning"),
 							formatUiKeyValue(ui, "Server errors (5xx)", String(runtimeMetrics.serverErrors), "danger"),
 							formatUiKeyValue(ui, "Network errors", String(runtimeMetrics.networkErrors), "danger"),
+							formatUiKeyValue(ui, "User aborts", String(runtimeMetrics.userAborts), "muted"),
 							formatUiKeyValue(ui, "Auth refresh failures", String(runtimeMetrics.authRefreshFailures), "warning"),
 							formatUiKeyValue(ui, "Account rotations", String(runtimeMetrics.accountRotations), "accent"),
+							formatUiKeyValue(ui, "Same-account retries", String(runtimeMetrics.sameAccountRetries), "warning"),
+							formatUiKeyValue(ui, "Stream failover attempts", String(runtimeMetrics.streamFailoverAttempts), "muted"),
+							formatUiKeyValue(ui, "Stream failover recoveries", String(runtimeMetrics.streamFailoverRecoveries), "success"),
+							formatUiKeyValue(
+								ui,
+								"Stream failover cross-account recoveries",
+								String(runtimeMetrics.streamFailoverCrossAccountRecoveries),
+								"accent",
+							),
 							formatUiKeyValue(ui, "Empty-response retries", String(runtimeMetrics.emptyResponseRetries), "warning"),
+							formatUiKeyValue(ui, "Session affinity entries", String(sessionAffinityEntries), "muted"),
+							formatUiKeyValue(
+								ui,
+								"Live sync",
+								`${liveSyncSnapshot?.running ? "on" : "off"} (${liveSyncSnapshot?.reloadCount ?? 0} reloads)`,
+								liveSyncSnapshot?.running ? "success" : "muted",
+							),
+							formatUiKeyValue(
+								ui,
+								"Refresh guardian",
+								guardianStats
+									? `on (${guardianStats.refreshed} refreshed, ${guardianStats.failed} failed)`
+									: "off",
+								guardianStats ? "success" : "muted",
+							),
 							formatUiKeyValue(ui, "Last upstream request", lastRequest, "muted"),
 						];
 						if (runtimeMetrics.lastError) {
@@ -2973,10 +3794,10 @@ while (attempted.size < Math.max(1, accountCount)) {
 								...formatUiHeader(ui, "Health check"),
 								"",
 								formatUiItem(ui, "No accounts configured.", "warning"),
-								formatUiItem(ui, "Run: opencode auth login", "accent"),
+								formatUiItem(ui, "Run: codex login", "accent"),
 							].join("\n");
 						}
-						return "No Codex accounts configured. Run: opencode auth login";
+						return "No Codex accounts configured. Run: codex login";
 					}
 
 					const results: string[] = ui.v2Enabled
@@ -3110,9 +3931,7 @@ while (attempted.size < Math.max(1, accountCount)) {
 				}
 
 					if (cachedAccountManager) {
-						const reloadedManager = await AccountManager.loadFromDisk();
-						cachedAccountManager = reloadedManager;
-						accountManagerPromise = Promise.resolve(reloadedManager);
+						await reloadAccountManagerFromDisk();
 					}
 
 					const remaining = storage.accounts.length;
@@ -3123,7 +3942,7 @@ while (attempted.size < Math.max(1, accountCount)) {
 							formatUiItem(ui, `${getStatusMarker(ui, "ok")} Removed: ${label}`, "success"),
 							remaining > 0
 								? formatUiKeyValue(ui, "Remaining accounts", String(remaining))
-								: formatUiItem(ui, "No accounts remaining. Run: opencode auth login", "warning"),
+								: formatUiItem(ui, "No accounts remaining. Run: codex login", "warning"),
 						].join("\n");
 					}
 					return [
@@ -3131,7 +3950,7 @@ while (attempted.size < Math.max(1, accountCount)) {
 						"",
 						remaining > 0
 							? `Remaining accounts: ${remaining}`
-							: "No accounts remaining. Run: opencode auth login",
+							: "No accounts remaining. Run: codex login",
 					].join("\n");
 				},
 			}),
@@ -3148,10 +3967,10 @@ while (attempted.size < Math.max(1, accountCount)) {
 								...formatUiHeader(ui, "Refresh accounts"),
 								"",
 								formatUiItem(ui, "No accounts configured.", "warning"),
-								formatUiItem(ui, "Run: opencode auth login", "accent"),
+								formatUiItem(ui, "Run: codex login", "accent"),
 							].join("\n");
 						}
-						return "No Codex accounts configured. Run: opencode auth login";
+						return "No Codex accounts configured. Run: codex login";
 					}
 
 					const results: string[] = ui.v2Enabled
@@ -3187,9 +4006,7 @@ while (attempted.size < Math.max(1, accountCount)) {
 
 				await saveAccounts(storage);
 				if (cachedAccountManager) {
-					const reloadedManager = await AccountManager.loadFromDisk();
-					cachedAccountManager = reloadedManager;
-					accountManagerPromise = Promise.resolve(reloadedManager);
+					await reloadAccountManagerFromDisk();
 				}
 				results.push("");
 				results.push(`Summary: ${refreshedCount} refreshed, ${failedCount} failed`);
diff --git a/lib/accounts.ts b/lib/accounts.ts
index e154737f..d4fa6a12 100644
--- a/lib/accounts.ts
+++ b/lib/accounts.ts
@@ -323,6 +323,21 @@ export class AccountManager {
 		}));
 	}
 
+	getAccountByIndex(index: number): ManagedAccount | null {
+		if (!Number.isFinite(index)) return null;
+		if (index < 0 || index >= this.accounts.length) return null;
+		const account = this.accounts[index];
+		return account ?? null;
+	}
+
+	isAccountAvailableForFamily(index: number, family: ModelFamily, model?: string | null): boolean {
+		const account = this.getAccountByIndex(index);
+		if (!account) return false;
+		if (account.enabled === false) return false;
+		clearExpiredRateLimits(account);
+		return !isRateLimitedForFamily(account, family, model) && !this.isAccountCoolingDown(account);
+	}
+
 	setActiveIndex(index: number): ManagedAccount | null {
 		if (!Number.isFinite(index)) return null;
 		if (index < 0 || index >= this.accounts.length) return null;
@@ -349,6 +364,9 @@ export class AccountManager {
 		await setCodexCliActiveSelection({
 			accountId: account.accountId,
 			email: account.email,
+			accessToken: account.access,
+			refreshToken: account.refreshToken,
+			expiresAt: account.expires,
 		});
 	}
 
diff --git a/lib/audit.ts b/lib/audit.ts
index 36d3fdcd..93764022 100644
--- a/lib/audit.ts
+++ b/lib/audit.ts
@@ -1,7 +1,7 @@
 import { writeFileSync, mkdirSync, existsSync, statSync, renameSync, readdirSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
-import { homedir } from "node:os";
 import { getCorrelationId, maskEmail } from "./logger.js";
+import { getCodexLogDir } from "./runtime-paths.js";
 
 export enum AuditAction {
 	ACCOUNT_ADD = "account.add",
@@ -48,7 +48,7 @@ export interface AuditConfig {
 
 const DEFAULT_CONFIG: AuditConfig = {
 	enabled: true,
-	logDir: join(homedir(), ".opencode", "logs"),
+	logDir: getCodexLogDir(),
 	maxFileSizeBytes: 10 * 1024 * 1024,
 	maxFiles: 5,
 };
diff --git a/lib/auth/auth.ts b/lib/auth/auth.ts
index 545d6365..4c3a59b6 100644
--- a/lib/auth/auth.ts
+++ b/lib/auth/auth.ts
@@ -11,6 +11,31 @@ export const TOKEN_URL = "https://auth.openai.com/oauth/token";
 export const REDIRECT_URI = "http://localhost:1455/auth/callback";
 export const SCOPE = "openid profile email offline_access";
 
+const OAUTH_SENSITIVE_QUERY_PARAMS = [
+	"state",
+	"code",
+	"code_challenge",
+	"code_verifier",
+] as const;
+
+/**
+ * Redacts sensitive OAuth query parameters for safe logging.
+ * Returns the original string when parsing fails.
+ */
+export function redactOAuthUrlForLog(rawUrl: string): string {
+	try {
+		const parsed = new URL(rawUrl);
+		for (const key of OAUTH_SENSITIVE_QUERY_PARAMS) {
+			if (parsed.searchParams.has(key)) {
+				parsed.searchParams.set(key, "<redacted>");
+			}
+		}
+		return parsed.toString();
+	} catch {
+		return rawUrl;
+	}
+}
+
 /**
  * Generate a random state value for OAuth flow
  * @returns Random hex string
diff --git a/lib/auth/browser.ts b/lib/auth/browser.ts
index 04c94170..65fde943 100644
--- a/lib/auth/browser.ts
+++ b/lib/auth/browser.ts
@@ -19,6 +19,16 @@ export function getBrowserOpener(): string {
 	return PLATFORM_OPENERS.linux;
 }
 
+/**
+ * Determines whether a given command name exists on the system PATH.
+ *
+ * @param command - The command name to check.
+ * @returns `true` if a matching executable is found on PATH (on Windows this includes PATHEXT extensions or the literal `"start"`), `false` otherwise.
+ *
+ * Concurrency: result reflects the current filesystem state and may change after return; no atomicity guarantees.
+ * Windows filesystem behavior: resolves executable candidates using PATHEXT extensions.
+ * Token handling: the `command` string is used verbatim for lookup and is not redacted or modified.
+ */
 function commandExists(command: string): boolean {
 	if (!command) return false;
 
@@ -37,7 +47,13 @@ function commandExists(command: string): boolean {
 		const pathext = (process.env.PATHEXT || ".EXE;.CMD;.BAT;.COM")
 			.split(";")
 			.filter(Boolean);
+		const hasExtension = /\.[^\\/]+$/.test(command);
 		for (const entry of entries) {
+			if (hasExtension) {
+				const directCandidate = path.join(entry, command);
+				if (fs.existsSync(directCandidate)) return true;
+				continue;
+			}
 			for (const ext of pathext) {
 				const candidate = path.join(entry, `${command}${ext}`);
 				if (fs.existsSync(candidate)) return true;
@@ -49,21 +65,38 @@ function commandExists(command: string): boolean {
 
 	for (const entry of entries) {
 		const candidate = path.join(entry, command);
-		if (fs.existsSync(candidate)) return true;
+		try {
+			const stats = fs.statSync(candidate);
+			if (!stats.isFile()) continue;
+			// On POSIX, ensure at least one executable bit is set.
+			if ((stats.mode & 0o111) === 0) continue;
+			return true;
+		} catch {
+			continue;
+		}
 	}
 	return false;
 }
 
 /**
- * Opens a URL in the default browser
- * Silently fails if browser cannot be opened (user can copy URL manually)
- * @param url - URL to open
- * @returns True if a browser launch was attempted
+ * Launches the user's default browser to open the provided URL using a platform-appropriate command.
+ *
+ * This is a best-effort, fire-and-forget launcher: it attempts a platform-specific spawn and ignores
+ * child-process errors. On Windows it uses PowerShell `Start-Process` with PowerShell meta-character
+ * escaping to reduce shell/filesystem quirks. Callers must redact any sensitive tokens (for example,
+ * OAuth codes) from `url` before calling. Invocations are not atomic—concurrent calls may race but are
+ * safe to perform.
+ *
+ * @param url - The URL to open; redact sensitive tokens (e.g., OAuth codes) before passing.
+ * @returns `true` if a browser launch was attempted, `false` if no suitable opener was available or an exception occurred.
  */
 export function openBrowserUrl(url: string): boolean {
 	try {
 		// Windows: use PowerShell Start-Process to avoid cmd/start quirks with URLs containing '&' or ':'
 		if (process.platform === "win32") {
+			if (!commandExists("powershell.exe")) {
+				return false;
+			}
 			// Escape PowerShell special characters: backticks, double quotes, and $ (sub-expression injection)
 			const psUrl = url
 				.replace(/`/g, "``")
@@ -95,3 +128,65 @@ export function openBrowserUrl(url: string): boolean {
 	}
 }
 
+/**
+ * Copy text into the system clipboard using a best-effort, platform-specific command.
+ *
+ * On Windows the text is escaped for PowerShell to avoid interpretation of special characters.
+ * This function makes no guarantees of atomicity across processes; concurrent invocations may interleave.
+ * Clipboard contents are not redacted or logged — callers must mask or remove sensitive tokens before calling.
+ *
+ * @param text - The text to copy; falsy or empty values produce no action
+ * @returns `true` if a clipboard command was launched, `false` otherwise
+ */
+export function copyTextToClipboard(text: string): boolean {
+	try {
+		if (!text) return false;
+
+		if (process.platform === "win32") {
+			if (!commandExists("powershell.exe")) {
+				return false;
+			}
+			const psText = text
+				.replace(/`/g, "``")
+				.replace(/\$/g, "`$")
+				.replace(/"/g, '""');
+			const child = spawn(
+				"powershell.exe",
+				["-NoLogo", "-NoProfile", "-Command", `Set-Clipboard -Value "${psText}"`],
+				{ stdio: "ignore" },
+			);
+			child.on("error", () => {});
+			return true;
+		}
+
+		if (process.platform === "darwin") {
+			if (!commandExists("pbcopy")) return false;
+			const child = spawn("pbcopy", [], {
+				stdio: ["pipe", "ignore", "ignore"],
+				shell: false,
+			});
+			child.on("error", () => {});
+			child.stdin?.end(text);
+			return true;
+		}
+
+		const linuxClipboardCommands: Array<{ command: string; args: string[] }> = [
+			{ command: "wl-copy", args: [] },
+			{ command: "xclip", args: ["-selection", "clipboard"] },
+			{ command: "xsel", args: ["--clipboard", "--input"] },
+		];
+		for (const { command, args } of linuxClipboardCommands) {
+			if (!commandExists(command)) continue;
+			const child = spawn(command, args, {
+				stdio: ["pipe", "ignore", "ignore"],
+				shell: false,
+			});
+			child.on("error", () => {});
+			child.stdin?.end(text);
+			return true;
+		}
+		return false;
+	} catch {
+		return false;
+	}
+}
diff --git a/lib/auth/server.ts b/lib/auth/server.ts
index 1f83a105..79861021 100644
--- a/lib/auth/server.ts
+++ b/lib/auth/server.ts
@@ -10,9 +10,23 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const successHtml = fs.readFileSync(path.join(__dirname, "..", "oauth-success.html"), "utf-8");
 
 /**
- * Start a small local HTTP server that waits for /auth/callback and returns the code
- * @param options - OAuth state for validation
- * @returns Promise that resolves to server info
+ * Start a local HTTP server that captures an OAuth authorization code sent to /auth/callback.
+ *
+ * The server validates the `state` query parameter, serves a static success page for valid callbacks,
+ * and retains a single authorization code on the server instance until consumed via `waitForCode`.
+ * Only one code is stored at a time; call `close` to abort polling and shut down the server.
+ *
+ * On platforms such as Windows, binding to 127.0.0.1:1455 may fail if another process holds the port
+ * or if firewall/antivirus restrictions prevent local binding; in that case the returned `ready`
+ * flag is `false` to allow a manual paste fallback.
+ *
+ * Captured authorization codes are secrets and must be treated accordingly; callers should redact
+ * them from logs and error messages.
+ *
+ * @param options - Object with a `state` string used to validate the OAuth redirect
+ * @returns An OAuthServerInfo describing the server: `port` (1455), `ready` (boolean), a `close`
+ *          function to abort polling and close the server, and `waitForCode` which returns
+ *          `{ code: string }` when a code becomes available or `null` on timeout/abort.
  */
 export function startLocalOAuthServer({ state }: { state: string }): Promise<OAuthServerInfo> {
 	let pollAborted = false;
@@ -39,14 +53,22 @@ export function startLocalOAuthServer({ state }: { state: string }): Promise<OAu
 			res.setHeader("Content-Type", "text/html; charset=utf-8");
 			res.setHeader("X-Frame-Options", "DENY");
 			res.setHeader("X-Content-Type-Options", "nosniff");
-			res.setHeader("Content-Security-Policy", "default-src 'self'; script-src 'none'");
+			res.setHeader(
+				"Content-Security-Policy",
+				"default-src 'none'; style-src 'unsafe-inline'; img-src 'self' data:; font-src 'self' data:; script-src 'none'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'",
+			);
 			res.end(successHtml);
-			(server as http.Server & { _lastCode?: string })._lastCode = code;
-	} catch (err) {
-		logError(`Request handler error: ${(err as Error)?.message ?? String(err)}`);
-		res.statusCode = 500;
-		res.end("Internal error");
-	}
+			const trackedServer = server as http.Server & { _lastCode?: string };
+			if (trackedServer._lastCode) {
+				logWarn("Duplicate OAuth callback received; preserving first authorization code");
+				return;
+			}
+			trackedServer._lastCode = code;
+		} catch (err) {
+			logError(`Request handler error: ${(err as Error)?.message ?? String(err)}`);
+			res.statusCode = 500;
+			res.end("Internal error");
+		}
 	});
 
 	server.unref();
@@ -61,20 +83,20 @@ export function startLocalOAuthServer({ state }: { state: string }): Promise<OAu
 						pollAborted = true;
 						server.close();
 					},
-				waitForCode: async () => {
-					const POLL_INTERVAL_MS = 100;
-					const TIMEOUT_MS = 5 * 60 * 1000;
-					const maxIterations = Math.floor(TIMEOUT_MS / POLL_INTERVAL_MS);
-					const poll = () => new Promise<void>((r) => setTimeout(r, POLL_INTERVAL_MS));
-					for (let i = 0; i < maxIterations; i++) {
-						if (pollAborted) return null;
-						const lastCode = (server as http.Server & { _lastCode?: string })._lastCode;
-						if (lastCode) return { code: lastCode };
-						await poll();
-					}
-					logWarn("OAuth poll timeout after 5 minutes");
-					return null;
-				},
+					waitForCode: async () => {
+						const POLL_INTERVAL_MS = 100;
+						const TIMEOUT_MS = 5 * 60 * 1000;
+						const maxIterations = Math.floor(TIMEOUT_MS / POLL_INTERVAL_MS);
+						const poll = () => new Promise<void>((r) => setTimeout(r, POLL_INTERVAL_MS));
+						for (let i = 0; i < maxIterations; i++) {
+							if (pollAborted) return null;
+							const lastCode = (server as http.Server & { _lastCode?: string })._lastCode;
+							if (lastCode) return { code: lastCode };
+							await poll();
+						}
+						logWarn("OAuth poll timeout after 5 minutes");
+						return null;
+					},
 				});
 			})
 			.on("error", (err: NodeJS.ErrnoException) => {
@@ -84,14 +106,16 @@ export function startLocalOAuthServer({ state }: { state: string }): Promise<OAu
 				resolve({
 					port: 1455,
 					ready: false,
-				close: () => {
-					pollAborted = true;
-					try {
-						server.close();
-					} catch (err) {
-					logError(`Failed to close OAuth server: ${(err as Error)?.message ?? String(err)}`);
-					}
-				},
+					close: () => {
+						pollAborted = true;
+						try {
+							server.close();
+						} catch (closeErr) {
+							logError(
+								`Failed to close OAuth server: ${(closeErr as Error)?.message ?? String(closeErr)}`,
+							);
+						}
+					},
 					waitForCode: () => Promise.resolve(null),
 				});
 			});
diff --git a/lib/auto-update-checker.ts b/lib/auto-update-checker.ts
index f56df7d9..a948c60e 100644
--- a/lib/auto-update-checker.ts
+++ b/lib/auto-update-checker.ts
@@ -1,13 +1,13 @@
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
-import { homedir } from "node:os";
 import { createLogger } from "./logger.js";
+import { getCodexCacheDir } from "./runtime-paths.js";
 
 const log = createLogger("update-checker");
 
 const PACKAGE_NAME = "codex-multi-auth";
 const NPM_REGISTRY_URL = `https://registry.npmjs.org/${PACKAGE_NAME}/latest`;
-const CACHE_DIR = join(homedir(), ".opencode", "cache");
+const CACHE_DIR = getCodexCacheDir();
 const CACHE_FILE = join(CACHE_DIR, "update-check-cache.json");
 const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
 
@@ -22,6 +22,20 @@ interface NpmPackageInfo {
   name: string;
 }
 
+interface ParsedSemver {
+  core: [number, number, number];
+  prerelease: string[];
+}
+
+const RETRYABLE_WRITE_ERRORS = new Set(["EBUSY", "EPERM"]);
+
+function sleepSync(ms: number): void {
+  const delay = Math.max(0, Math.floor(ms));
+  if (delay === 0) return;
+  const lock = new Int32Array(new SharedArrayBuffer(4));
+  Atomics.wait(lock, 0, 0, delay);
+}
+
 function getCurrentVersion(): string {
   try {
     const packageJsonPath = join(import.meta.dirname ?? __dirname, "..", "package.json");
@@ -47,25 +61,107 @@ function saveCache(cache: UpdateCheckCache): void {
     if (!existsSync(CACHE_DIR)) {
       mkdirSync(CACHE_DIR, { recursive: true });
     }
-    writeFileSync(CACHE_FILE, JSON.stringify(cache, null, 2), "utf8");
+    const serialized = JSON.stringify(cache, null, 2);
+    let lastError: Error | null = null;
+    for (let attempt = 0; attempt < 4; attempt++) {
+      try {
+        writeFileSync(CACHE_FILE, serialized, "utf8");
+        return;
+      } catch (error) {
+        const code = (error as NodeJS.ErrnoException).code ?? "";
+        lastError = error as Error;
+        if (!RETRYABLE_WRITE_ERRORS.has(code) || attempt >= 3) {
+          throw error;
+        }
+        sleepSync(15 * (2 ** attempt));
+      }
+    }
+    if (lastError) throw lastError;
   } catch (error) {
     log.warn("Failed to save update cache", { error: (error as Error).message });
   }
 }
 
-function compareVersions(current: string, latest: string): number {
-  const currentParts = current.split(".").map((p) => parseInt(p, 10) || 0);
-  const latestParts = latest.split(".").map((p) => parseInt(p, 10) || 0);
-
-  for (let i = 0; i < Math.max(currentParts.length, latestParts.length); i++) {
-    const c = currentParts[i] ?? 0;
-    const l = latestParts[i] ?? 0;
-    if (l > c) return 1;
-    if (l < c) return -1;
+function parseSemver(version: string): ParsedSemver {
+  const normalized = version.trim().replace(/^v/i, "");
+  const [withoutBuild] = normalized.split("+");
+  const [corePart = "0.0.0", prereleasePart] = (withoutBuild ?? "0.0.0").split("-", 2);
+  const [majorRaw = "0", minorRaw = "0", patchRaw = "0"] = corePart.split(".");
+
+  const toSafeInt = (value: string): number => {
+    if (!/^\d+$/.test(value)) return 0;
+    const parsed = Number.parseInt(value, 10);
+    return Number.isFinite(parsed) ? parsed : 0;
+  };
+
+  return {
+    core: [toSafeInt(majorRaw), toSafeInt(minorRaw), toSafeInt(patchRaw)],
+    prerelease:
+      prereleasePart && prereleasePart.trim().length > 0
+        ? prereleasePart.split(".").filter((segment) => segment.length > 0)
+        : [],
+  };
+}
+
+function comparePrerelease(current: string[], latest: string[]): number {
+  const maxLen = Math.max(current.length, latest.length);
+
+  for (let i = 0; i < maxLen; i++) {
+    const currentPart = current[i];
+    const latestPart = latest[i];
+
+    if (currentPart === undefined && latestPart === undefined) return 0;
+    if (currentPart === undefined) return 1;
+    if (latestPart === undefined) return -1;
+
+    if (currentPart === latestPart) continue;
+
+    const currentIsNumeric = /^\d+$/.test(currentPart);
+    const latestIsNumeric = /^\d+$/.test(latestPart);
+
+    if (currentIsNumeric && latestIsNumeric) {
+      const currentNum = Number.parseInt(currentPart, 10);
+      const latestNum = Number.parseInt(latestPart, 10);
+      if (latestNum > currentNum) return 1;
+      if (latestNum < currentNum) return -1;
+      continue;
+    }
+
+    if (currentIsNumeric && !latestIsNumeric) return 1;
+    if (!currentIsNumeric && latestIsNumeric) return -1;
+
+    const lexical = latestPart.localeCompare(currentPart, "en", { sensitivity: "case" });
+    if (lexical > 0) return 1;
+    if (lexical < 0) return -1;
   }
+
   return 0;
 }
 
+function compareVersions(current: string, latest: string): number {
+  const parsedCurrent = parseSemver(current);
+  const parsedLatest = parseSemver(latest);
+
+  for (let i = 0; i < parsedCurrent.core.length; i++) {
+    const currentPart = parsedCurrent.core[i] ?? 0;
+    const latestPart = parsedLatest.core[i] ?? 0;
+    if (latestPart > currentPart) return 1;
+    if (latestPart < currentPart) return -1;
+  }
+
+  const currentHasPrerelease = parsedCurrent.prerelease.length > 0;
+  const latestHasPrerelease = parsedLatest.prerelease.length > 0;
+
+  if (!currentHasPrerelease && latestHasPrerelease) {
+    return -1;
+  }
+  if (currentHasPrerelease && !latestHasPrerelease) {
+    return 1;
+  }
+
+  return comparePrerelease(parsedCurrent.prerelease, parsedLatest.prerelease);
+}
+
 async function fetchLatestVersion(): Promise<string | null> {
   try {
     const controller = new AbortController();
diff --git a/lib/capability-policy.ts b/lib/capability-policy.ts
new file mode 100644
index 00000000..eb9a7f92
--- /dev/null
+++ b/lib/capability-policy.ts
@@ -0,0 +1,160 @@
+import { getNormalizedModel } from "./request/helpers/model-map.js";
+
+export interface CapabilityPolicySnapshot {
+	successes: number;
+	failures: number;
+	unsupported: number;
+	lastSuccessAt?: number;
+	lastFailureAt?: number;
+}
+
+interface CapabilityEntry extends CapabilityPolicySnapshot {
+	updatedAt: number;
+}
+
+const MAX_ENTRIES = 2048;
+const PASSIVE_RECOVERY_PER_MIN = 0.5;
+
+/**
+ * Produce a compact canonical token from a model identifier for use in storage keys.
+ *
+ * The function is side-effect-free and safe for concurrent use. It treats only forward slashes ("/") as segment separators,
+ * removes common trailing qualifiers (`-none`, `-minimal`, `-low`, `-medium`, `-high`, `-xhigh`) from the final segment,
+ * and does not access the filesystem. It does not further redact secrets; the resulting token may require encoding before
+ * use as a Windows filename.
+ *
+ * @param model - Optional model string which may include path-like segments and trailing qualifiers
+ * @returns The normalized model token, or `null` if `model` is missing or empty after trimming
+ */
+function normalizeModel(model: string | undefined): string | null {
+	if (!model) return null;
+	const trimmedInput = model.trim();
+	if (!trimmedInput) return null;
+	const withoutProvider = trimmedInput.includes("/")
+		? (trimmedInput.split("/").pop() ?? trimmedInput)
+		: trimmedInput;
+	const mapped = getNormalizedModel(withoutProvider) ?? withoutProvider;
+	const trimmed = mapped.trim().toLowerCase();
+	if (!trimmed) return null;
+	return trimmed.replace(/-(none|minimal|low|medium|high|xhigh)$/i, "");
+}
+
+/**
+ * Compose a storage key from an account key and a normalized model identifier.
+ *
+ * The function is pure and safe to call concurrently. It does not perform any
+ * secret/token redaction — do not pass sensitive values in `accountKey` or `model`.
+ * Note: the returned key includes a colon separator (`accountKey:normalizedModel`)
+ * and may not be suitable as a Windows filename without further encoding.
+ *
+ * @param accountKey - The account identifier used as the key prefix
+ * @param model - The model string to normalize and append; may be undefined
+ * @returns The combined key string, or `null` if `accountKey` is falsy or `model` cannot be normalized
+ */
+function makeKey(accountKey: string, model: string | undefined): string | null {
+	const normalized = normalizeModel(model);
+	if (!accountKey || !normalized) return null;
+	return `${accountKey}:${normalized}`;
+}
+
+export class CapabilityPolicyStore {
+	private readonly entries = new Map<string, CapabilityEntry>();
+
+	recordSuccess(accountKey: string, model: string, now = Date.now()): void {
+		const key = makeKey(accountKey, model);
+		if (!key) return;
+		const existing = this.entries.get(key);
+		this.entries.set(key, {
+			successes: (existing?.successes ?? 0) + 1,
+			failures: Math.max(0, (existing?.failures ?? 0) - 1),
+			unsupported: Math.max(0, (existing?.unsupported ?? 0) - 1),
+			lastSuccessAt: now,
+			lastFailureAt: existing?.lastFailureAt,
+			updatedAt: now,
+		});
+		this.evictIfNeeded();
+	}
+
+	recordFailure(accountKey: string, model: string, now = Date.now()): void {
+		const key = makeKey(accountKey, model);
+		if (!key) return;
+		const existing = this.entries.get(key);
+		this.entries.set(key, {
+			successes: existing?.successes ?? 0,
+			failures: (existing?.failures ?? 0) + 1,
+			unsupported: existing?.unsupported ?? 0,
+			lastSuccessAt: existing?.lastSuccessAt,
+			lastFailureAt: now,
+			updatedAt: now,
+		});
+		this.evictIfNeeded();
+	}
+
+	recordUnsupported(accountKey: string, model: string, now = Date.now()): void {
+		const key = makeKey(accountKey, model);
+		if (!key) return;
+		const existing = this.entries.get(key);
+		this.entries.set(key, {
+			successes: existing?.successes ?? 0,
+			failures: (existing?.failures ?? 0) + 1,
+			unsupported: (existing?.unsupported ?? 0) + 1,
+			lastSuccessAt: existing?.lastSuccessAt,
+			lastFailureAt: now,
+			updatedAt: now,
+		});
+		this.evictIfNeeded();
+	}
+
+	getBoost(accountKey: string, model: string, now = Date.now()): number {
+		const key = makeKey(accountKey, model);
+		if (!key) return 0;
+		const entry = this.entries.get(key);
+		if (!entry) return 0;
+
+		const minutesSinceUpdate = Math.max(0, (now - entry.updatedAt) / 60_000);
+		const recoveredFailures = Math.max(0, entry.failures - minutesSinceUpdate * PASSIVE_RECOVERY_PER_MIN);
+		const recoveredUnsupported = Math.max(0, entry.unsupported - minutesSinceUpdate * PASSIVE_RECOVERY_PER_MIN);
+
+		const successScore = Math.min(12, entry.successes * 2);
+		const failurePenalty = Math.min(18, recoveredFailures * 3);
+		const unsupportedPenalty = Math.min(24, recoveredUnsupported * 6);
+		const net = successScore - failurePenalty - unsupportedPenalty;
+		return Math.max(-30, Math.min(20, net));
+	}
+
+	getSnapshot(accountKey: string, model: string): CapabilityPolicySnapshot | null {
+		const key = makeKey(accountKey, model);
+		if (!key) return null;
+		const entry = this.entries.get(key);
+		if (!entry) return null;
+		return {
+			successes: entry.successes,
+			failures: entry.failures,
+			unsupported: entry.unsupported,
+			lastSuccessAt: entry.lastSuccessAt,
+			lastFailureAt: entry.lastFailureAt,
+		};
+	}
+
+	clearAccount(accountKey: string): number {
+		if (!accountKey) return 0;
+		let removed = 0;
+		for (const key of this.entries.keys()) {
+			if (key.startsWith(`${accountKey}:`)) {
+				this.entries.delete(key);
+				removed += 1;
+			}
+		}
+		return removed;
+	}
+
+	private evictIfNeeded(): void {
+		if (this.entries.size <= MAX_ENTRIES) return;
+		const oldest = this.entries.entries().next().value;
+		if (!oldest) return;
+		const [key] = oldest;
+		if (typeof key === "string") {
+			this.entries.delete(key);
+		}
+	}
+}
diff --git a/lib/cli.ts b/lib/cli.ts
index 7d6e445d..6c4b0009 100644
--- a/lib/cli.ts
+++ b/lib/cli.ts
@@ -7,6 +7,7 @@ import {
 	isTTY,
 	type AccountStatus,
 } from "./ui/auth-menu.js";
+import { UI_COPY } from "./ui/copy.js";
 
 /**
  * Detect if running in OpenCode Desktop/TUI mode where readline prompts don't work.
@@ -30,8 +31,8 @@ export async function promptAddAnotherAccount(currentCount: number): Promise<boo
 
 	const rl = createInterface({ input, output });
 	try {
-		console.log("\nTIP: use private browsing or sign out before adding another account.\n");
-		const answer = await rl.question(`Add another account? (${currentCount} added) (y/n): `);
+		console.log(`\n${UI_COPY.fallback.addAnotherTip}\n`);
+		const answer = await rl.question(UI_COPY.fallback.addAnotherQuestion(currentCount));
 		const normalized = answer.trim().toLowerCase();
 		return normalized === "y" || normalized === "yes";
 	} finally {
@@ -41,6 +42,9 @@ export async function promptAddAnotherAccount(currentCount: number): Promise<boo
 
 export type LoginMode =
 	| "add"
+	| "forecast"
+	| "fix"
+	| "settings"
 	| "fresh"
 	| "manage"
 	| "check"
@@ -53,15 +57,32 @@ export interface ExistingAccountInfo {
 	accountLabel?: string;
 	email?: string;
 	index: number;
+	sourceIndex?: number;
+	quickSwitchNumber?: number;
 	addedAt?: number;
 	lastUsed?: number;
 	status?: AccountStatus;
+	quotaSummary?: string;
+	quota5hLeftPercent?: number;
+	quota5hResetAtMs?: number;
+	quota7dLeftPercent?: number;
+	quota7dResetAtMs?: number;
+	quotaRateLimited?: boolean;
 	isCurrentAccount?: boolean;
 	enabled?: boolean;
+	showStatusBadge?: boolean;
+	showCurrentBadge?: boolean;
+	showLastUsed?: boolean;
+	showQuotaCooldown?: boolean;
+	showHintsForUnselectedRows?: boolean;
+	highlightCurrentRow?: boolean;
+	focusStyle?: "row-invert" | "chip";
+	statuslineFields?: string[];
 }
 
 export interface LoginMenuOptions {
 	flaggedCount?: number;
+	statusMessage?: string | (() => string | undefined);
 }
 
 export interface LoginMenuResult {
@@ -69,6 +90,7 @@ export interface LoginMenuResult {
 	deleteAccountIndex?: number;
 	refreshAccountIndex?: number;
 	toggleAccountIndex?: number;
+	switchAccountIndex?: number;
 	deleteAll?: boolean;
 }
 
@@ -88,10 +110,27 @@ function formatAccountLabel(account: ExistingAccountInfo, index: number): string
 	return `${num}. Account`;
 }
 
+function resolveAccountSourceIndex(account: ExistingAccountInfo): number {
+	const sourceIndex =
+		typeof account.sourceIndex === "number" && Number.isFinite(account.sourceIndex)
+			? Math.max(0, Math.floor(account.sourceIndex))
+			: undefined;
+	if (typeof sourceIndex === "number") return sourceIndex;
+	if (typeof account.index === "number" && Number.isFinite(account.index)) {
+		return Math.max(0, Math.floor(account.index));
+	}
+	return -1;
+}
+
+function warnUnresolvableAccountSelection(account: ExistingAccountInfo): void {
+	const label = account.email?.trim() || account.accountId?.trim() || `index ${account.index + 1}`;
+	console.log(`Unable to resolve saved account for action: ${label}`);
+}
+
 async function promptDeleteAllTypedConfirm(): Promise<boolean> {
 	const rl = createInterface({ input, output });
 	try {
-		const answer = await rl.question("Type DELETE to confirm removing all accounts: ");
+		const answer = await rl.question("Type DELETE to remove all saved accounts: ");
 		return answer.trim() === "DELETE";
 	} finally {
 		rl.close();
@@ -110,15 +149,33 @@ async function promptLoginModeFallback(existingAccounts: ExistingAccountInfo[]):
 		}
 
 		while (true) {
-			const answer = await rl.question("(a)dd, (f)resh, (c)heck, (d)eep, (v)erify flagged, or (q)uit? [a/f/c/d/v/q]: ");
+			const answer = await rl.question(UI_COPY.fallback.selectModePrompt);
 			const normalized = answer.trim().toLowerCase();
 			if (normalized === "a" || normalized === "add") return { mode: "add" };
-			if (normalized === "f" || normalized === "fresh") return { mode: "fresh", deleteAll: true };
+			if (normalized === "b" || normalized === "p" || normalized === "forecast") {
+				return { mode: "forecast" };
+			}
+			if (normalized === "x" || normalized === "fix") return { mode: "fix" };
+			if (normalized === "s" || normalized === "settings" || normalized === "configure") {
+				return { mode: "settings" };
+			}
+			if (normalized === "f" || normalized === "fresh" || normalized === "clear") {
+				return { mode: "fresh", deleteAll: true };
+			}
 			if (normalized === "c" || normalized === "check") return { mode: "check" };
-			if (normalized === "d" || normalized === "deep") return { mode: "deep-check" };
-			if (normalized === "v" || normalized === "verify") return { mode: "verify-flagged" };
+			if (normalized === "d" || normalized === "deep") {
+				return { mode: "deep-check" };
+			}
+			if (
+				normalized === "g" ||
+				normalized === "flagged" ||
+				normalized === "verify-flagged" ||
+				normalized === "verify"
+			) {
+				return { mode: "verify-flagged" };
+			}
 			if (normalized === "q" || normalized === "quit") return { mode: "cancel" };
-			console.log("Please enter one of: a, f, c, d, v, q.");
+			console.log(UI_COPY.fallback.invalidModePrompt);
 		}
 	} finally {
 		rl.close();
@@ -140,14 +197,21 @@ export async function promptLoginMode(
 	while (true) {
 		const action = await showAuthMenu(existingAccounts, {
 			flaggedCount: options.flaggedCount ?? 0,
+			statusMessage: options.statusMessage,
 		});
 
 		switch (action.type) {
 			case "add":
 				return { mode: "add" };
+			case "forecast":
+				return { mode: "forecast" };
+			case "fix":
+				return { mode: "fix" };
+			case "settings":
+				return { mode: "settings" };
 			case "fresh":
 				if (!(await promptDeleteAllTypedConfirm())) {
-					console.log("\nDelete-all cancelled.\n");
+					console.log("\nDelete all cancelled.\n");
 					continue;
 				}
 				return { mode: "fresh", deleteAll: true };
@@ -160,19 +224,61 @@ export async function promptLoginMode(
 			case "select-account": {
 				const accountAction = await showAccountDetails(action.account);
 				if (accountAction === "delete") {
-					return { mode: "manage", deleteAccountIndex: action.account.index };
+					const index = resolveAccountSourceIndex(action.account);
+					if (index >= 0) return { mode: "manage", deleteAccountIndex: index };
+					warnUnresolvableAccountSelection(action.account);
+					continue;
+				}
+				if (accountAction === "set-current") {
+					const index = resolveAccountSourceIndex(action.account);
+					if (index >= 0) return { mode: "manage", switchAccountIndex: index };
+					warnUnresolvableAccountSelection(action.account);
+					continue;
 				}
 				if (accountAction === "refresh") {
-					return { mode: "manage", refreshAccountIndex: action.account.index };
+					const index = resolveAccountSourceIndex(action.account);
+					if (index >= 0) return { mode: "manage", refreshAccountIndex: index };
+					warnUnresolvableAccountSelection(action.account);
+					continue;
 				}
 				if (accountAction === "toggle") {
-					return { mode: "manage", toggleAccountIndex: action.account.index };
+					const index = resolveAccountSourceIndex(action.account);
+					if (index >= 0) return { mode: "manage", toggleAccountIndex: index };
+					warnUnresolvableAccountSelection(action.account);
+					continue;
 				}
 				continue;
 			}
+			case "set-current-account": {
+				const index = resolveAccountSourceIndex(action.account);
+				if (index >= 0) return { mode: "manage", switchAccountIndex: index };
+				warnUnresolvableAccountSelection(action.account);
+				continue;
+			}
+			case "refresh-account": {
+				const index = resolveAccountSourceIndex(action.account);
+				if (index >= 0) return { mode: "manage", refreshAccountIndex: index };
+				warnUnresolvableAccountSelection(action.account);
+				continue;
+			}
+			case "toggle-account": {
+				const index = resolveAccountSourceIndex(action.account);
+				if (index >= 0) return { mode: "manage", toggleAccountIndex: index };
+				warnUnresolvableAccountSelection(action.account);
+				continue;
+			}
+			case "delete-account": {
+				const index = resolveAccountSourceIndex(action.account);
+				if (index >= 0) return { mode: "manage", deleteAccountIndex: index };
+				warnUnresolvableAccountSelection(action.account);
+				continue;
+			}
+			case "search":
+				// Search is handled in showAuthMenu; keep the main loop active.
+				continue;
 			case "delete-all":
 				if (!(await promptDeleteAllTypedConfirm())) {
-					console.log("\nDelete-all cancelled.\n");
+					console.log("\nDelete all cancelled.\n");
 					continue;
 				}
 				return { mode: "fresh", deleteAll: true };
diff --git a/lib/codex-cli/state.ts b/lib/codex-cli/state.ts
index f605fc4b..1380574b 100644
--- a/lib/codex-cli/state.ts
+++ b/lib/codex-cli/state.ts
@@ -2,7 +2,9 @@ import { existsSync, promises as fs } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { decodeJWT } from "../auth/auth.js";
+import { extractAccountEmail, extractAccountId } from "../auth/token-utils.js";
 import { createLogger } from "../logger.js";
+import { sleep } from "../utils.js";
 import {
 	incrementCodexCliMetric,
 	makeAccountFingerprint,
@@ -10,6 +12,7 @@ import {
 
 const log = createLogger("codex-cli-state");
 const CACHE_TTL_MS = 5_000;
+const RETRYABLE_FS_CODES = new Set(["EBUSY", "EPERM"]);
 
 export interface CodexCliTokenCacheEntry {
 	accessToken: string;
@@ -28,12 +31,36 @@ export interface CodexCliState {
 	accounts: CodexCliAccountSnapshot[];
 	activeAccountId?: string;
 	activeEmail?: string;
+	syncVersion?: number;
+	sourceUpdatedAtMs?: number;
 }
 
 let cache: CodexCliState | null = null;
 let cacheLoadedAt = 0;
+let inFlightLoadPromise: Promise<CodexCliState | null> | null = null;
 const emittedWarnings = new Set<string>();
 
+function isRetryableFsError(error: unknown): boolean {
+	const code = (error as NodeJS.ErrnoException | undefined)?.code;
+	return typeof code === "string" && RETRYABLE_FS_CODES.has(code);
+}
+
+async function retryFsOperation<T>(task: () => Promise<T>, attempts = 4): Promise<T> {
+	let lastError: unknown;
+	for (let attempt = 0; attempt < attempts; attempt += 1) {
+		try {
+			return await task();
+		} catch (error) {
+			lastError = error;
+			if (!isRetryableFsError(error) || attempt >= attempts - 1) {
+				throw error;
+			}
+			await sleep(10 * 2 ** attempt);
+		}
+	}
+	throw lastError instanceof Error ? lastError : new Error("filesystem retry exhausted");
+}
+
 function isRecord(value: unknown): value is Record<string, unknown> {
 	return !!value && typeof value === "object" && !Array.isArray(value);
 }
@@ -135,6 +162,22 @@ function extractAccountSnapshot(raw: unknown): CodexCliAccountSnapshot | null {
 	};
 }
 
+/**
+ * Determines whether Codex CLI sync is enabled based on environment variables.
+ *
+ * Checks CODEX_MULTI_AUTH_SYNC_CODEX_CLI first (explicit "1" enables, "0" disables),
+ * then falls back to the legacy CODEX_AUTH_SYNC_CODEX_CLI (also "1"/"0"). If the
+ * legacy variable is used, a single warning is emitted and a metric is incremented.
+ *
+ * Concurrency: the function may perform a one-time side effect (emitting a legacy-use
+ * warning and incrementing a metric); that side effect is guarded to run at most once
+ * per process and is safe to call from concurrent contexts.
+ *
+ * Filesystem and tokens: this function does not access the filesystem and does not
+ * read or log any tokens (no token redaction is required here).
+ *
+ * @returns `true` if sync is enabled, `false` otherwise.
+ */
 export function isCodexCliSyncEnabled(): boolean {
 	const override = (process.env.CODEX_MULTI_AUTH_SYNC_CODEX_CLI ?? "").trim();
 	if (override === "0") return false;
@@ -153,13 +196,54 @@ export function isCodexCliSyncEnabled(): boolean {
 	return true;
 }
 
+/**
+ * Resolves the filesystem path to the Codex CLI accounts file.
+ *
+ * If the environment variable CODEX_CLI_ACCOUNTS_PATH is set to a non-empty value it will be returned; otherwise the default is "$HOME/.codex/accounts.json".
+ *
+ * Concurrency: callers should treat the returned path as a location that may be concurrently read or written by other processes.
+ * Windows: returns a path using the platform path separators (may contain backslashes on Windows).
+ * Token redaction: this function only returns the file path; it does not read or expose token contents and callers must redact sensitive fields when logging the file contents.
+ *
+ * @returns The resolved path to the accounts JSON file, either the overridden value from CODEX_CLI_ACCOUNTS_PATH or the platform-specific "$HOME/.codex/accounts.json".
+ */
 export function getCodexCliAccountsPath(): string {
 	const override = (process.env.CODEX_CLI_ACCOUNTS_PATH ?? "").trim();
 	if (override.length > 0) return override;
 	return join(homedir(), ".codex", "accounts.json");
 }
 
-function parseCodexCliState(path: string, parsed: unknown): CodexCliState | null {
+/**
+ * Resolve the filesystem path for the Codex CLI auth JSON file, allowing an environment override.
+ *
+ * If the environment variable `CODEX_CLI_AUTH_PATH` is set to a non-empty value (after trimming) that value is returned;
+ * otherwise the default path is homedir/.codex/auth.json. The returned path may reference a file containing authentication tokens—
+ * treat it as sensitive (avoid logging full paths or file contents without redaction). The function returns a platform-native path
+ * (path separators follow the current OS); callers should handle concurrent access to the file when reading or writing.
+ *
+ * @returns The resolved path to the Codex CLI `auth.json` file.
+ */
+export function getCodexCliAuthPath(): string {
+	const override = (process.env.CODEX_CLI_AUTH_PATH ?? "").trim();
+	if (override.length > 0) return override;
+	return join(homedir(), ".codex", "auth.json");
+}
+
+/**
+ * Convert a parsed Codex CLI accounts JSON payload into a CodexCliState snapshot.
+ *
+ * Parses the provided JSON object expected to contain an `accounts` array and optional metadata, producing a state object that includes accounts, active account/email if present, `syncVersion`, and the optional `sourceUpdatedAtMs`. The supplied `path` is recorded as-is and is not normalized (may be a Unix or Windows path). This function performs no synchronization or locking and may produce stale results relative to on-disk changes. Tokens are copied verbatim from the payload and are not redacted; callers must redact sensitive values before logging or exposing the returned state.
+ *
+ * @param path - Filesystem path of the source payload; path separators are preserved and not normalized.
+ * @param parsed - The already-parsed JSON value expected to contain an `accounts` array and optional metadata.
+ * @param sourceUpdatedAtMs - Optional source modification timestamp (milliseconds) to attach to the returned state.
+ * @returns A populated `CodexCliState` when `parsed` contains a valid `accounts` array, or `null` when the payload is not in the expected shape.
+ */
+function parseCodexCliState(
+	path: string,
+	parsed: unknown,
+	sourceUpdatedAtMs?: number,
+): CodexCliState | null {
 	if (!isRecord(parsed) || !Array.isArray(parsed.accounts)) {
 		return null;
 	}
@@ -188,9 +272,102 @@ function parseCodexCliState(path: string, parsed: unknown): CodexCliState | null
 		accounts,
 		activeAccountId,
 		activeEmail,
+		syncVersion: readNumber(parsed.codexMultiAuthSyncVersion),
+		sourceUpdatedAtMs,
 	};
 }
 
+/**
+ * Parse an auth-style Codex CLI payload into a CodexCliState snapshot.
+ *
+ * The returned state represents a point-in-time conversion of the provided payload and may include raw tokens
+ * and derived metadata (account id, email, expiration, sync version, and optional sourceUpdatedAtMs).
+ *
+ * Concurrency: the result reflects the payload at the time of parsing; callers should not assume it remains
+ * valid if the underlying file changes concurrently.
+ *
+ * Windows/filesystem note: filesystem-derived timestamps (sourceUpdatedAtMs) may be coarse or approximate on some
+ * platforms (notably Windows); treat them as best-effort indicators of source modification time.
+ *
+ * Token handling: the returned state includes raw access/refresh tokens. Callers must redact or avoid logging tokens
+ * or other sensitive fields when emitting logs, telemetry, or external diagnostics.
+ *
+ * @param path - Filesystem path that served as the source of `parsed`; stored verbatim on the returned state.
+ * @param parsed - The parsed JSON payload from an auth-style file; expected to contain a `tokens` object.
+ * @param sourceUpdatedAtMs - Optional best-effort source modification timestamp (milliseconds since epoch).
+ * @returns A CodexCliState built from the auth payload, or `null` if `parsed` is not a valid auth payload containing no tokens.
+ */
+function parseCodexCliAuthState(
+	path: string,
+	parsed: unknown,
+	sourceUpdatedAtMs?: number,
+): CodexCliState | null {
+	if (!isRecord(parsed)) return null;
+	const tokens = isRecord(parsed.tokens) ? parsed.tokens : null;
+	if (!tokens) return null;
+
+	const accessToken = extractTokenFromRecord(tokens, ["access_token", "accessToken"]);
+	const refreshToken = extractTokenFromRecord(tokens, ["refresh_token", "refreshToken"]);
+	if (!accessToken && !refreshToken) return null;
+
+	const idToken = extractTokenFromRecord(tokens, ["id_token", "idToken"]);
+	const accountId =
+		readTrimmedString(tokens.account_id) ??
+		readTrimmedString(tokens.accountId) ??
+		(accessToken ? extractAccountId(accessToken) : undefined);
+	const email =
+		(accessToken ? extractAccountEmail(accessToken, idToken) : undefined) ??
+		normalizeEmail(parsed.email);
+
+	let expiresAt: number | undefined = undefined;
+	if (accessToken) {
+		const decoded = decodeJWT(accessToken);
+		const exp = decoded?.exp;
+		if (typeof exp === "number" && Number.isFinite(exp)) {
+			expiresAt = exp * 1000;
+		}
+	}
+
+	const snapshot: CodexCliAccountSnapshot = {
+		accountId,
+		email,
+		accessToken: accessToken ?? "",
+		refreshToken,
+		expiresAt,
+		isActive: true,
+	};
+
+	return {
+		path,
+		accounts: [snapshot],
+		activeAccountId: accountId,
+		activeEmail: email,
+		syncVersion: readNumber(parsed.codexMultiAuthSyncVersion),
+		sourceUpdatedAtMs,
+	};
+}
+
+/**
+ * Loads Codex CLI authentication state from disk, with an in-memory TTL cache and optional force refresh.
+ *
+ * Reads either the accounts JSON or the legacy auth JSON (whichever is present) and returns a normalized
+ * CodexCliState including tokens, active account, optional sync version, and source file modification time.
+ * Uses an in-memory cache valid for CACHE_TTL_MS; if `forceRefresh` is true the cache is bypassed.
+ *
+ * Concurrency: callers may race to read/update the in-memory cache; this function performs best-effort caching
+ * and does not provide external synchronization primitives.
+ *
+ * Windows filesystem notes: file modification timestamps (sourceUpdatedAtMs) are derived from fs.stat().mtimeMs
+ * and may have coarser resolution on some Windows filesystems.
+ *
+ * Token redaction: returned state may contain token values (accessToken, refreshToken); consumers should treat
+ * these values as sensitive and redact or avoid logging them.
+ *
+ * @param options - Optional settings.
+ * @param options.forceRefresh - If true, bypass the in-memory TTL cache and re-read files from disk.
+ * @returns The parsed CodexCliState when a valid accounts/auth payload is found, or `null` if sync is disabled,
+ * no valid payload exists, or a read/parse error occurred.
+ */
 export async function loadCodexCliState(
 	options?: { forceRefresh?: boolean },
 ): Promise<CodexCliState | null> {
@@ -202,54 +379,132 @@ export async function loadCodexCliState(
 	if (!options?.forceRefresh && cache && now - cacheLoadedAt < CACHE_TTL_MS) {
 		return cache;
 	}
+	if (inFlightLoadPromise) {
+		return inFlightLoadPromise;
+	}
 
-	const path = getCodexCliAccountsPath();
-	incrementCodexCliMetric("readAttempts");
-	cacheLoadedAt = now;
+	const readTask = async (): Promise<CodexCliState | null> => {
+		const accountsPath = getCodexCliAccountsPath();
+		const authPath = getCodexCliAuthPath();
+		incrementCodexCliMetric("readAttempts");
 
-	if (!existsSync(path)) {
-		incrementCodexCliMetric("readMisses");
-		cache = null;
-		return null;
-	}
+		const hasAccountsPath = existsSync(accountsPath);
+		const hasAuthPath = existsSync(authPath);
+		if (!hasAccountsPath && !hasAuthPath) {
+			incrementCodexCliMetric("readMisses");
+			cache = null;
+			return null;
+		}
 
-	try {
-		const raw = await fs.readFile(path, "utf-8");
-		const parsed = JSON.parse(raw) as unknown;
-		const state = parseCodexCliState(path, parsed);
-		if (!state) {
+		try {
+			if (hasAccountsPath) {
+				try {
+					const raw = await retryFsOperation(() => fs.readFile(accountsPath, "utf-8"));
+					const parsed = JSON.parse(raw) as unknown;
+					let sourceUpdatedAtMs: number | undefined;
+					try {
+						sourceUpdatedAtMs = (await retryFsOperation(() => fs.stat(accountsPath))).mtimeMs;
+					} catch {
+						sourceUpdatedAtMs = undefined;
+					}
+					const state = parseCodexCliState(accountsPath, parsed, sourceUpdatedAtMs);
+					if (state) {
+						incrementCodexCliMetric("readSuccesses");
+						log.debug("Loaded Codex CLI state", {
+							operation: "read-state",
+							outcome: "success",
+							path: accountsPath,
+							accountCount: state.accounts.length,
+							activeAccountRef: makeAccountFingerprint({
+								accountId: state.activeAccountId,
+								email: state.activeEmail,
+							}),
+						});
+						cache = state;
+						return state;
+					}
+					log.warn("Codex CLI accounts payload is malformed", {
+						operation: "read-state",
+						outcome: "malformed",
+						path: accountsPath,
+					});
+				} catch (accountsError) {
+					log.warn("Failed to read Codex CLI accounts state", {
+						operation: "read-state",
+						outcome: "accounts-read-error",
+						path: accountsPath,
+						error: String(accountsError),
+					});
+				}
+			}
+
+			if (hasAuthPath) {
+				try {
+					const raw = await retryFsOperation(() => fs.readFile(authPath, "utf-8"));
+					const parsed = JSON.parse(raw) as unknown;
+					let sourceUpdatedAtMs: number | undefined;
+					try {
+						sourceUpdatedAtMs = (await retryFsOperation(() => fs.stat(authPath))).mtimeMs;
+					} catch {
+						sourceUpdatedAtMs = undefined;
+					}
+					const state = parseCodexCliAuthState(authPath, parsed, sourceUpdatedAtMs);
+					if (state) {
+						incrementCodexCliMetric("readSuccesses");
+						log.debug("Loaded Codex CLI auth state", {
+							operation: "read-state",
+							outcome: "success",
+							path: authPath,
+							accountCount: state.accounts.length,
+							activeAccountRef: makeAccountFingerprint({
+								accountId: state.activeAccountId,
+								email: state.activeEmail,
+							}),
+						});
+						cache = state;
+						return state;
+					}
+					log.warn("Codex CLI auth payload is malformed", {
+						operation: "read-state",
+						outcome: "malformed",
+						path: authPath,
+					});
+				} catch (authError) {
+					log.warn("Failed to read Codex CLI auth state", {
+						operation: "read-state",
+						outcome: "auth-read-error",
+						path: authPath,
+						error: String(authError),
+					});
+				}
+			}
+
+			incrementCodexCliMetric("readFailures");
+			cache = null;
+			return null;
+		} catch (error) {
 			incrementCodexCliMetric("readFailures");
-			log.warn("Codex CLI accounts payload is malformed", {
+			log.warn("Failed to read Codex CLI state", {
 				operation: "read-state",
-				outcome: "malformed",
-				path,
+				outcome: "error",
+				path: hasAccountsPath ? accountsPath : authPath,
+				error: String(error),
 			});
 			cache = null;
 			return null;
+		} finally {
+			cacheLoadedAt = Date.now();
+		}
+	};
+
+	const currentLoad = readTask();
+	inFlightLoadPromise = currentLoad;
+	try {
+		return await currentLoad;
+	} finally {
+		if (inFlightLoadPromise === currentLoad) {
+			inFlightLoadPromise = null;
 		}
-		incrementCodexCliMetric("readSuccesses");
-		log.debug("Loaded Codex CLI state", {
-			operation: "read-state",
-			outcome: "success",
-			path,
-			accountCount: state.accounts.length,
-			activeAccountRef: makeAccountFingerprint({
-				accountId: state.activeAccountId,
-				email: state.activeEmail,
-			}),
-		});
-		cache = state;
-		return state;
-	} catch (error) {
-		incrementCodexCliMetric("readFailures");
-		log.warn("Failed to read Codex CLI state", {
-			operation: "read-state",
-			outcome: "error",
-			path,
-			error: String(error),
-		});
-		cache = null;
-		return null;
 	}
 }
 
@@ -276,6 +531,7 @@ export async function lookupCodexCliTokensByEmail(
 export function clearCodexCliStateCache(): void {
 	cache = null;
 	cacheLoadedAt = 0;
+	inFlightLoadPromise = null;
 }
 
 export function __resetCodexCliWarningCacheForTests(): void {
diff --git a/lib/codex-cli/sync.ts b/lib/codex-cli/sync.ts
index edd22f52..38e66050 100644
--- a/lib/codex-cli/sync.ts
+++ b/lib/codex-cli/sync.ts
@@ -1,4 +1,8 @@
-import type { AccountMetadataV3, AccountStorageV3 } from "../storage.js";
+import {
+	getLastAccountsSaveTimestamp,
+	type AccountMetadataV3,
+	type AccountStorageV3,
+} from "../storage.js";
 import { MODEL_FAMILIES, type ModelFamily } from "../prompts/codex.js";
 import { createLogger } from "../logger.js";
 import { loadCodexCliState, type CodexCliAccountSnapshot } from "./state.js";
@@ -6,6 +10,7 @@ import {
 	incrementCodexCliMetric,
 	makeAccountFingerprint,
 } from "./observability.js";
+import { getLastCodexCliSelectionWriteTimestamp } from "./writer.js";
 
 const log = createLogger("codex-cli-sync");
 
@@ -164,6 +169,21 @@ function writeFamilyIndexes(
 	}
 }
 
+/**
+ * Normalize and clamp the global and per-family active account indexes to valid ranges.
+ *
+ * Mutates `storage` in-place: ensures `activeIndexByFamily` exists, clamps `activeIndex` to
+ * 0..(accounts.length - 1) (or 0 when there are no accounts), and resolves each family entry
+ * to a valid index within the same bounds.
+ *
+ * Concurrency: callers must synchronize externally when multiple threads/processes may write
+ * the same storage object. Filesystem notes: no platform-specific IO is performed here; when
+ * persisted to disk on Windows consumers should still ensure atomic writes. Token handling:
+ * this function does not read or modify authentication tokens and makes no attempt to redact
+ * sensitive fields.
+ *
+ * @param storage - The account storage object whose indexes will be normalized and clamped
+ */
 function normalizeStoredFamilyIndexes(storage: AccountStorageV3): void {
 	const count = storage.accounts.length;
 	const clamped = count === 0 ? 0 : Math.max(0, Math.min(storage.activeIndex, count - 1));
@@ -180,6 +200,16 @@ function normalizeStoredFamilyIndexes(storage: AccountStorageV3): void {
 	}
 }
 
+/**
+ * Return the `accountId` and `email` from the first snapshot marked active.
+ *
+ * @param snapshots - Array of Codex CLI account snapshots to search
+ * @returns The `accountId` and `email` from the first snapshot whose `isActive` is true; properties are omitted if no active snapshot is found
+ *
+ * Concurrency: pure and side-effect free; safe to call concurrently.
+ * Filesystem: behavior is independent of OS/filesystem semantics (including Windows).
+ * Security: only `accountId` and `email` are returned; other sensitive snapshot fields (for example tokens) are not exposed or returned by this function.
+ */
 function readActiveFromSnapshots(
 	snapshots: CodexCliAccountSnapshot[],
 ): { accountId?: string; email?: string } {
@@ -190,6 +220,55 @@ function readActiveFromSnapshots(
 	};
 }
 
+/**
+ * Determines whether the Codex CLI's active-account selection should override the local selection.
+ *
+ * Considers the state's numeric `syncVersion` or `sourceUpdatedAtMs` and compares the derived Codex timestamp
+ * against local timestamps from recent account saves and last Codex selection writes. Concurrent writes or
+ * clock skew can affect this decision; filesystem timestamp granularity on Windows may reduce timestamp precision.
+ * This function only examines timestamps and identifiers in `state` and does not read or expose token values.
+ *
+ * @param state - Persisted Codex CLI state (may be undefined); the function reads `syncVersion` and `sourceUpdatedAtMs` when present
+ * @returns `true` if the Codex CLI selection should be applied (i.e., Codex state is newer or timestamps are unknown), `false` otherwise
+ */
+function shouldApplyCodexCliSelection(state: Awaited<ReturnType<typeof loadCodexCliState>>): boolean {
+	if (!state) return false;
+	const hasSyncVersion =
+		typeof state.syncVersion === "number" && Number.isFinite(state.syncVersion);
+	const codexVersion = hasSyncVersion
+		? (state.syncVersion as number)
+		: typeof state.sourceUpdatedAtMs === "number" && Number.isFinite(state.sourceUpdatedAtMs)
+			? state.sourceUpdatedAtMs
+			: 0;
+	const localVersion = Math.max(
+		getLastAccountsSaveTimestamp(),
+		getLastCodexCliSelectionWriteTimestamp(),
+	);
+	if (codexVersion <= 0 || localVersion <= 0) return true;
+	// Keep local selection when plugin wrote more recently than Codex state.
+	const toleranceMs = hasSyncVersion ? 0 : 1_000;
+	return codexVersion >= localVersion - toleranceMs;
+}
+
+/**
+ * Reconciles the provided local account storage with the Codex CLI state and returns the resulting storage and whether it changed.
+ *
+ * This operation:
+ * - Merges accounts from the Codex CLI state into a clone of `current` (or into a new empty storage when `current` is null).
+ * - May update the active account selection and per-family active indexes when the Codex CLI selection is considered applicable.
+ * - Preserves secrets and sensitive fields; any tokens written to storage are subject to the project's token-redaction rules and are not exposed in logs or metrics.
+ *
+ * Concurrency assumptions:
+ * - Caller is responsible for serializing concurrent writes to persistent storage; this function only returns an in-memory storage object and does not perform atomic file-level coordination.
+ *
+ * Windows filesystem notes:
+ * - When the caller persists the returned storage to disk on Windows, standard Windows file-locking and path-length semantics apply; this function does not perform Windows-specific path normalization.
+ *
+ * @param current - The current local AccountStorageV3, or `null` to indicate none exists.
+ * @returns An object containing:
+ *   - `storage`: the reconciled AccountStorageV3 to persist (may be the original `current` when no changes were applied).
+ *   - `changed`: `true` if the reconciled storage differs from `current`, `false` otherwise.
+ */
 export async function syncAccountStorageFromCodexCli(
 	current: AccountStorageV3 | null,
 ): Promise<{ storage: AccountStorageV3 | null; changed: boolean }> {
@@ -223,21 +302,38 @@ export async function syncAccountStorageFromCodexCli(
 		}
 
 		const activeFromSnapshots = readActiveFromSnapshots(state.accounts);
-		const desiredIndex = resolveActiveIndex(
-			next.accounts,
-			state.activeAccountId ?? activeFromSnapshots.accountId,
-			state.activeEmail ?? activeFromSnapshots.email,
-		);
+		const applyActiveFromCodex = shouldApplyCodexCliSelection(state);
+		if (applyActiveFromCodex) {
+			const desiredIndex = resolveActiveIndex(
+				next.accounts,
+				state.activeAccountId ?? activeFromSnapshots.accountId,
+				state.activeEmail ?? activeFromSnapshots.email,
+			);
 
-		const previousActive = next.activeIndex;
-		const previousFamilies = JSON.stringify(next.activeIndexByFamily ?? {});
-		writeFamilyIndexes(next, desiredIndex);
-		normalizeStoredFamilyIndexes(next);
-		if (previousActive !== next.activeIndex) {
-			changed = true;
-		}
-		if (previousFamilies !== JSON.stringify(next.activeIndexByFamily ?? {})) {
-			changed = true;
+			const previousActive = next.activeIndex;
+			const previousFamilies = JSON.stringify(next.activeIndexByFamily ?? {});
+			writeFamilyIndexes(next, desiredIndex);
+			normalizeStoredFamilyIndexes(next);
+			if (previousActive !== next.activeIndex) {
+				changed = true;
+			}
+			if (previousFamilies !== JSON.stringify(next.activeIndexByFamily ?? {})) {
+				changed = true;
+			}
+		} else {
+			const previousActive = next.activeIndex;
+			const previousFamilies = JSON.stringify(next.activeIndexByFamily ?? {});
+			normalizeStoredFamilyIndexes(next);
+			if (previousActive !== next.activeIndex) {
+				changed = true;
+			}
+			if (previousFamilies !== JSON.stringify(next.activeIndexByFamily ?? {})) {
+				changed = true;
+			}
+			log.debug("Skipped Codex CLI active selection overwrite due to newer local state", {
+				operation: "reconcile-storage",
+				outcome: "local-newer",
+			});
 		}
 
 		incrementCodexCliMetric(changed ? "reconcileChanges" : "reconcileNoops");
diff --git a/lib/codex-cli/writer.ts b/lib/codex-cli/writer.ts
index 18a16820..1341962d 100644
--- a/lib/codex-cli/writer.ts
+++ b/lib/codex-cli/writer.ts
@@ -1,23 +1,60 @@
 import { existsSync, promises as fs } from "node:fs";
 import { dirname } from "node:path";
 import { createLogger } from "../logger.js";
-import { clearCodexCliStateCache, getCodexCliAccountsPath, isCodexCliSyncEnabled } from "./state.js";
+import {
+	clearCodexCliStateCache,
+	getCodexCliAccountsPath,
+	getCodexCliAuthPath,
+	isCodexCliSyncEnabled,
+} from "./state.js";
 import {
 	incrementCodexCliMetric,
 	makeAccountFingerprint,
 } from "./observability.js";
 
 const log = createLogger("codex-cli-writer");
+let lastCodexCliSelectionWriteAt = 0;
+let activeSelectionWriteQueue: Promise<void> = Promise.resolve();
 
 interface ActiveSelection {
 	accountId?: string;
 	email?: string;
+	accessToken?: string;
+	refreshToken?: string;
+	expiresAt?: number;
+	idToken?: string;
 }
 
 function isRecord(value: unknown): value is Record<string, unknown> {
 	return !!value && typeof value === "object" && !Array.isArray(value);
 }
 
+function readTrimmedString(value: unknown): string | undefined {
+	if (typeof value !== "string") return undefined;
+	const trimmed = value.trim();
+	return trimmed.length > 0 ? trimmed : undefined;
+}
+
+function readNumber(value: unknown): number | undefined {
+	if (typeof value === "number" && Number.isFinite(value)) return value;
+	if (typeof value === "string") {
+		const parsed = Number(value);
+		if (Number.isFinite(parsed)) return parsed;
+	}
+	return undefined;
+}
+
+function extractTokenFromRecord(
+	record: Record<string, unknown>,
+	keys: string[],
+): string | undefined {
+	for (const key of keys) {
+		const token = readTrimmedString(record[key]);
+		if (token) return token;
+	}
+	return undefined;
+}
+
 function normalizeEmail(value: unknown): string | undefined {
 	if (typeof value !== "string") return undefined;
 	const trimmed = value.trim().toLowerCase();
@@ -35,6 +72,41 @@ function readAccountId(record: Record<string, unknown>): string | undefined {
 	return undefined;
 }
 
+function extractSelectionFromAccountRecord(record: Record<string, unknown>): ActiveSelection {
+	const auth = isRecord(record.auth) ? record.auth : undefined;
+	const tokens = auth && isRecord(auth.tokens) ? auth.tokens : undefined;
+
+	const accessToken =
+		extractTokenFromRecord(record, ["accessToken", "access_token"]) ??
+		(tokens ? extractTokenFromRecord(tokens, ["access_token", "accessToken"]) : undefined);
+	const refreshToken =
+		extractTokenFromRecord(record, ["refreshToken", "refresh_token"]) ??
+		(tokens ? extractTokenFromRecord(tokens, ["refresh_token", "refreshToken"]) : undefined);
+	const accountId =
+		readAccountId(record) ??
+		(tokens ? readTrimmedString(tokens.account_id) ?? readTrimmedString(tokens.accountId) : undefined);
+	const idToken =
+		extractTokenFromRecord(record, ["idToken", "id_token"]) ??
+		(tokens ? extractTokenFromRecord(tokens, ["id_token", "idToken"]) : undefined);
+	const email =
+		normalizeEmail(record.email) ??
+		normalizeEmail(record.user_email) ??
+		normalizeEmail(record.username);
+	const expiresAt =
+		readNumber(record.expiresAt) ??
+		readNumber(record.expires_at) ??
+		(tokens ? readNumber(tokens.expires_at) : undefined);
+
+	return {
+		accountId,
+		email,
+		accessToken,
+		refreshToken,
+		expiresAt,
+		idToken,
+	};
+}
+
 function resolveMatchIndex(
 	accounts: unknown[],
 	selection: ActiveSelection,
@@ -61,107 +133,307 @@ function resolveMatchIndex(
 	return -1;
 }
 
-export async function setCodexCliActiveSelection(
+function toIsoTime(ms: number | undefined): string {
+	if (typeof ms === "number" && Number.isFinite(ms) && ms > 0) {
+		return new Date(ms).toISOString();
+	}
+	return new Date().toISOString();
+}
+
+async function atomicWriteJson(path: string, payload: Record<string, unknown>): Promise<void> {
+	const tempPath = `${path}.${Date.now()}.${Math.random().toString(36).slice(2, 8)}.tmp`;
+	await fs.mkdir(dirname(path), { recursive: true });
+	try {
+		await fs.writeFile(tempPath, JSON.stringify(payload, null, 2), {
+			encoding: "utf-8",
+			mode: 0o600,
+		});
+
+		let lastRenameError: NodeJS.ErrnoException | null = null;
+		for (let attempt = 0; attempt < 5; attempt += 1) {
+			try {
+				await fs.rename(tempPath, path);
+				return;
+			} catch (error) {
+				const code = (error as NodeJS.ErrnoException).code;
+				if (code === "EPERM" || code === "EBUSY") {
+					lastRenameError = error as NodeJS.ErrnoException;
+					await new Promise((resolve) => setTimeout(resolve, 10 * 2 ** attempt));
+					continue;
+				}
+				throw error;
+			}
+		}
+		if (lastRenameError) throw lastRenameError;
+	} finally {
+		try {
+			await fs.unlink(tempPath);
+		} catch {
+			// Best effort temp-file cleanup.
+		}
+	}
+}
+
+async function writeCodexAuthState(
+	path: string,
 	selection: ActiveSelection,
 ): Promise<boolean> {
-	if (!isCodexCliSyncEnabled()) return false;
+	const raw = existsSync(path) ? await fs.readFile(path, "utf-8") : "{}";
+	const parsed = JSON.parse(raw) as unknown;
+	if (!isRecord(parsed)) {
+		log.warn("Failed to persist Codex auth selection", {
+			operation: "write-active-selection",
+			outcome: "malformed-auth-state",
+			path,
+		});
+		return false;
+	}
+
+	const existingTokens = isRecord(parsed.tokens) ? parsed.tokens : {};
+	const next = { ...parsed } as Record<string, unknown>;
+	const nextTokens = { ...existingTokens } as Record<string, unknown>;
+
+	const syncVersion = Date.now();
+	const selectedAccessToken = readTrimmedString(selection.accessToken);
+	const selectedRefreshToken = readTrimmedString(selection.refreshToken);
+	const accessToken =
+		selectedAccessToken ??
+		(typeof existingTokens.access_token === "string" ? existingTokens.access_token : undefined);
+	const refreshToken =
+		selectedRefreshToken ??
+		(typeof existingTokens.refresh_token === "string" ? existingTokens.refresh_token : undefined);
+
+	if (!accessToken || !refreshToken) {
+		log.warn("Failed to persist Codex auth selection", {
+			operation: "write-active-selection",
+			outcome: "missing-token-payload",
+			path,
+			accountRef: makeAccountFingerprint({
+				accountId: selection.accountId,
+				email: selection.email,
+			}),
+		});
+		return false;
+	}
+
+	next.auth_mode = typeof parsed.auth_mode === "string" ? parsed.auth_mode : "chatgpt";
+	next.OPENAI_API_KEY = null;
+	const selectedEmail = normalizeEmail(selection.email);
+	if (selectedEmail) {
+		next.email = selectedEmail;
+	}
+	nextTokens.access_token = accessToken;
+	nextTokens.refresh_token = refreshToken;
+	const resolvedIdToken =
+		readTrimmedString(selection.idToken) ??
+		(typeof existingTokens.id_token === "string" ? existingTokens.id_token : undefined);
+	if (resolvedIdToken) {
+		nextTokens.id_token = resolvedIdToken;
+	}
+	if (selection.accountId?.trim()) {
+		nextTokens.account_id = selection.accountId.trim();
+	}
+	next.tokens = nextTokens;
+	next.last_refresh = toIsoTime(selection.expiresAt);
+	next.codexMultiAuthSyncVersion = syncVersion;
 
-	const path = getCodexCliAccountsPath();
-	if (!existsSync(path)) return false;
-	incrementCodexCliMetric("writeAttempts");
+	await atomicWriteJson(path, next);
+	lastCodexCliSelectionWriteAt = Math.max(lastCodexCliSelectionWriteAt, syncVersion);
+	return true;
+}
 
+async function enqueueActiveSelectionWrite<T>(task: () => Promise<T>): Promise<T> {
+	let releaseQueue!: () => void;
+	const queueTail = new Promise<void>((resolve) => {
+		releaseQueue = resolve;
+	});
+	const previous = activeSelectionWriteQueue;
+	activeSelectionWriteQueue = previous
+		.catch(() => {
+			// Keep queue alive even if a previous task failed.
+		})
+		.then(() => queueTail);
+	await previous.catch(() => {
+		// Ignore previous failure, current task still runs.
+	});
 	try {
-		const raw = await fs.readFile(path, "utf-8");
-		const parsed = JSON.parse(raw) as unknown;
-		if (!isRecord(parsed) || !Array.isArray(parsed.accounts)) {
+		return await task();
+	} finally {
+		releaseQueue();
+	}
+}
+
+export async function setCodexCliActiveSelection(
+	selection: ActiveSelection,
+): Promise<boolean> {
+	return enqueueActiveSelectionWrite(async () => {
+		if (!isCodexCliSyncEnabled()) return false;
+
+		incrementCodexCliMetric("writeAttempts");
+		const accountsPath = getCodexCliAccountsPath();
+		const authPath = getCodexCliAuthPath();
+		const hasAccountsPath = existsSync(accountsPath);
+		const hasAuthPath = existsSync(authPath);
+
+		if (!hasAccountsPath && !hasAuthPath) {
 			incrementCodexCliMetric("writeFailures");
-			log.warn("Failed to persist Codex CLI active selection", {
-				operation: "write-active-selection",
-				outcome: "malformed",
-				path,
-			});
 			return false;
 		}
 
-		const matchIndex = resolveMatchIndex(parsed.accounts, selection);
-		if (matchIndex < 0) {
+		try {
+			let resolvedSelection: ActiveSelection = { ...selection };
+			let wroteAccounts = false;
+			let wroteAuth = false;
+
+			if (hasAccountsPath) {
+				const raw = await fs.readFile(accountsPath, "utf-8");
+				const parsed = JSON.parse(raw) as unknown;
+				if (!isRecord(parsed) || !Array.isArray(parsed.accounts)) {
+					log.warn("Failed to persist Codex CLI active selection", {
+						operation: "write-active-selection",
+						outcome: "malformed",
+						path: accountsPath,
+					});
+				} else {
+					const matchIndex = resolveMatchIndex(parsed.accounts, selection);
+					if (matchIndex < 0) {
+						const hasSelectionTokens =
+							typeof selection.accessToken === "string" &&
+							selection.accessToken.trim().length > 0 &&
+							typeof selection.refreshToken === "string" &&
+							selection.refreshToken.trim().length > 0;
+						log.warn("Failed to persist Codex CLI active selection", {
+							operation: "write-active-selection",
+							outcome: "no-match",
+							path: accountsPath,
+							accountRef: makeAccountFingerprint({
+								accountId: selection.accountId,
+								email: selection.email,
+							}),
+						});
+						if (!hasAuthPath || !hasSelectionTokens) {
+							incrementCodexCliMetric("writeFailures");
+							return false;
+						}
+					} else {
+						const chosen = parsed.accounts[matchIndex];
+						if (!isRecord(chosen)) {
+							log.warn("Failed to persist Codex CLI active selection", {
+								operation: "write-active-selection",
+								outcome: "invalid-account-record",
+								path: accountsPath,
+							});
+							if (!hasAuthPath) {
+								incrementCodexCliMetric("writeFailures");
+								return false;
+							}
+						} else {
+							const chosenSelection = extractSelectionFromAccountRecord(chosen);
+							resolvedSelection = {
+								...resolvedSelection,
+								accountId: resolvedSelection.accountId ?? chosenSelection.accountId,
+								email: resolvedSelection.email ?? chosenSelection.email,
+								accessToken: resolvedSelection.accessToken ?? chosenSelection.accessToken,
+								refreshToken: resolvedSelection.refreshToken ?? chosenSelection.refreshToken,
+								expiresAt: resolvedSelection.expiresAt ?? chosenSelection.expiresAt,
+								idToken: resolvedSelection.idToken ?? chosenSelection.idToken,
+							};
+
+							const next = { ...parsed };
+							const syncVersion = Date.now();
+							const chosenAccountId = readAccountId(chosen) ?? selection.accountId?.trim();
+							const chosenEmail = normalizeEmail(chosen.email) ?? normalizeEmail(selection.email);
+
+							if (chosenAccountId) {
+								next.activeAccountId = chosenAccountId;
+								next.active_account_id = chosenAccountId;
+							}
+							if (chosenEmail) {
+								next.activeEmail = chosenEmail;
+								next.active_email = chosenEmail;
+							}
+
+							next.accounts = parsed.accounts.map((entry, index) => {
+								if (!isRecord(entry)) return entry;
+								const updated = { ...entry };
+								updated.active = index === matchIndex;
+								updated.isActive = index === matchIndex;
+								updated.is_active = index === matchIndex;
+								return updated;
+							});
+							next.codexMultiAuthSyncVersion = syncVersion;
+
+							await atomicWriteJson(accountsPath, next);
+							lastCodexCliSelectionWriteAt = Math.max(lastCodexCliSelectionWriteAt, syncVersion);
+							wroteAccounts = true;
+							log.debug("Persisted Codex CLI accounts selection", {
+								operation: "write-active-selection",
+								outcome: "success",
+								path: accountsPath,
+								accountRef: makeAccountFingerprint({
+									accountId: chosenAccountId,
+									email: chosenEmail,
+								}),
+							});
+						}
+					}
+				}
+			}
+
+			if (hasAuthPath) {
+				wroteAuth = await writeCodexAuthState(authPath, resolvedSelection);
+				if (!wroteAuth) {
+					if (!wroteAccounts) {
+						incrementCodexCliMetric("writeFailures");
+						return false;
+					}
+					log.warn("Codex auth state update skipped after accounts selection update", {
+						operation: "write-active-selection",
+						outcome: "accounts-updated-auth-failed",
+						path: authPath,
+						accountRef: makeAccountFingerprint({
+							accountId: resolvedSelection.accountId,
+							email: resolvedSelection.email,
+						}),
+					});
+				} else {
+					log.debug("Persisted Codex auth active selection", {
+						operation: "write-active-selection",
+						outcome: "success",
+						path: authPath,
+						accountRef: makeAccountFingerprint({
+							accountId: resolvedSelection.accountId,
+							email: resolvedSelection.email,
+						}),
+					});
+				}
+			}
+
+			if (wroteAccounts || wroteAuth) {
+				clearCodexCliStateCache();
+				incrementCodexCliMetric("writeSuccesses");
+				return true;
+			}
+
+			incrementCodexCliMetric("writeFailures");
+			return false;
+		} catch (error) {
 			incrementCodexCliMetric("writeFailures");
 			log.warn("Failed to persist Codex CLI active selection", {
 				operation: "write-active-selection",
-				outcome: "no-match",
-				path,
+				outcome: "error",
+				path: hasAccountsPath ? accountsPath : authPath,
 				accountRef: makeAccountFingerprint({
 					accountId: selection.accountId,
 					email: selection.email,
 				}),
+				error: String(error),
 			});
 			return false;
 		}
+	});
+}
 
-		const chosen = parsed.accounts[matchIndex];
-		if (!isRecord(chosen)) {
-			incrementCodexCliMetric("writeFailures");
-			log.warn("Failed to persist Codex CLI active selection", {
-				operation: "write-active-selection",
-				outcome: "invalid-account-record",
-				path,
-			});
-			return false;
-		}
-
-		const next = { ...parsed };
-		const chosenAccountId = readAccountId(chosen) ?? selection.accountId?.trim();
-		const chosenEmail = normalizeEmail(chosen.email) ?? normalizeEmail(selection.email);
-
-		if (chosenAccountId) {
-			next.activeAccountId = chosenAccountId;
-			next.active_account_id = chosenAccountId;
-		}
-		if (chosenEmail) {
-			next.activeEmail = chosenEmail;
-			next.active_email = chosenEmail;
-		}
-
-		next.accounts = parsed.accounts.map((entry, index) => {
-			if (!isRecord(entry)) return entry;
-			const updated = { ...entry };
-			updated.active = index === matchIndex;
-			updated.isActive = index === matchIndex;
-			updated.is_active = index === matchIndex;
-			return updated;
-		});
-
-		const tempPath = `${path}.${Date.now()}.${Math.random().toString(36).slice(2, 8)}.tmp`;
-		await fs.mkdir(dirname(path), { recursive: true });
-		await fs.writeFile(tempPath, JSON.stringify(next, null, 2), {
-			encoding: "utf-8",
-			mode: 0o600,
-		});
-		await fs.rename(tempPath, path);
-		clearCodexCliStateCache();
-		incrementCodexCliMetric("writeSuccesses");
-		log.debug("Persisted Codex CLI active selection", {
-			operation: "write-active-selection",
-			outcome: "success",
-			path,
-			accountRef: makeAccountFingerprint({
-				accountId: chosenAccountId,
-				email: chosenEmail,
-			}),
-		});
-		return true;
-	} catch (error) {
-		incrementCodexCliMetric("writeFailures");
-		log.warn("Failed to persist Codex CLI active selection", {
-			operation: "write-active-selection",
-			outcome: "error",
-			path,
-			accountRef: makeAccountFingerprint({
-				accountId: selection.accountId,
-				email: selection.email,
-			}),
-			error: String(error),
-		});
-		return false;
-	}
+export function getLastCodexCliSelectionWriteTimestamp(): number {
+	return lastCodexCliSelectionWriteAt;
 }
diff --git a/lib/codex-manager.ts b/lib/codex-manager.ts
new file mode 100644
index 00000000..5bda1cbe
--- /dev/null
+++ b/lib/codex-manager.ts
@@ -0,0 +1,5687 @@
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+import { promises as fs, existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import {
+	createAuthorizationFlow,
+	exchangeAuthorizationCode,
+	parseAuthorizationInput,
+	REDIRECT_URI,
+} from "./auth/auth.js";
+import { startLocalOAuthServer } from "./auth/server.js";
+import { copyTextToClipboard, openBrowserUrl } from "./auth/browser.js";
+import { promptAddAnotherAccount, promptLoginMode, type ExistingAccountInfo } from "./cli.js";
+import {
+	extractAccountEmail,
+	extractAccountId,
+	formatAccountLabel,
+	formatCooldown,
+	formatWaitTime,
+	getAccountIdCandidates,
+	resolveRequestAccountId,
+	sanitizeEmail,
+	selectBestAccountCandidate,
+} from "./accounts.js";
+import { ACCOUNT_LIMITS } from "./constants.js";
+import {
+	loadDashboardDisplaySettings,
+	saveDashboardDisplaySettings,
+	getDashboardSettingsPath,
+	DEFAULT_DASHBOARD_DISPLAY_SETTINGS,
+	type DashboardDisplaySettings,
+	type DashboardThemePreset,
+	type DashboardAccentColor,
+	type DashboardAccountSortMode,
+	type DashboardStatuslineField,
+} from "./dashboard-settings.js";
+import {
+	getDefaultPluginConfig,
+	loadPluginConfig,
+	savePluginConfig,
+} from "./config.js";
+import {
+	evaluateForecastAccounts,
+	isHardRefreshFailure,
+	recommendForecastAccount,
+	summarizeForecast,
+	type ForecastAccountResult,
+} from "./forecast.js";
+import { MODEL_FAMILIES, type ModelFamily } from "./prompts/codex.js";
+import {
+	fetchCodexQuotaSnapshot,
+	formatQuotaSnapshotLine,
+	type CodexQuotaSnapshot,
+} from "./quota-probe.js";
+import { queuedRefresh } from "./refresh-queue.js";
+import {
+	loadQuotaCache,
+	saveQuotaCache,
+	type QuotaCacheData,
+	type QuotaCacheEntry,
+} from "./quota-cache.js";
+import {
+	getStoragePath,
+	loadFlaggedAccounts,
+	loadAccounts,
+	saveFlaggedAccounts,
+	saveAccounts,
+	setStoragePath,
+	type AccountMetadataV3,
+	type AccountStorageV3,
+	type FlaggedAccountMetadataV1,
+} from "./storage.js";
+import type { AccountIdSource, PluginConfig, TokenFailure, TokenResult } from "./types.js";
+import { setCodexCliActiveSelection } from "./codex-cli/writer.js";
+import { ANSI } from "./ui/ansi.js";
+import { UI_COPY } from "./ui/copy.js";
+import { paintUiText, quotaToneFromLeftPercent } from "./ui/format.js";
+import { getUiRuntimeOptions, setUiRuntimeOptions } from "./ui/runtime.js";
+import { select, type MenuItem } from "./ui/select.js";
+
+type TokenSuccess = Extract<TokenResult, { type: "success" }>;
+type TokenSuccessWithAccount = TokenSuccess & {
+	accountIdOverride?: string;
+	accountIdSource?: AccountIdSource;
+	accountLabel?: string;
+};
+type PromptTone = "accent" | "success" | "warning" | "danger" | "muted";
+
+function stylePromptText(text: string, tone: PromptTone): string {
+	if (!output.isTTY) return text;
+	const ui = getUiRuntimeOptions();
+	if (ui.v2Enabled) {
+		if (tone === "muted") {
+			return `${ui.theme.colors.dim}${paintUiText(ui, text, "muted")}${ui.theme.colors.reset}`;
+		}
+		const mapped = tone === "accent" ? "primary" : tone;
+		return paintUiText(ui, text, mapped);
+	}
+	const legacyCode = tone === "accent"
+		? ANSI.green
+		: tone === "success"
+			? ANSI.green
+			: tone === "warning"
+				? ANSI.yellow
+				: tone === "danger"
+					? ANSI.red
+					: ANSI.dim;
+	return `${legacyCode}${text}${ANSI.reset}`;
+}
+
+function collapseWhitespace(value: string): string {
+	return value.replace(/\s+/g, " ").trim();
+}
+
+function formatReasonLabel(reason: string | undefined): string | undefined {
+	if (!reason) return undefined;
+	const normalized = collapseWhitespace(reason.replace(/_/g, " "));
+	return normalized.length > 0 ? normalized : undefined;
+}
+
+function extractErrorMessageFromPayload(payload: unknown): string | undefined {
+	if (!payload || typeof payload !== "object") return undefined;
+	const record = payload as Record<string, unknown>;
+
+	const directMessage = typeof record.message === "string"
+		? collapseWhitespace(record.message)
+		: "";
+	const directCode = typeof record.code === "string"
+		? collapseWhitespace(record.code)
+		: "";
+	if (directMessage) {
+		if (directCode && !directMessage.toLowerCase().includes(directCode.toLowerCase())) {
+			return `${directMessage} [${directCode}]`;
+		}
+		return directMessage;
+	}
+
+	const nested = record.error;
+	if (nested && typeof nested === "object") {
+		return extractErrorMessageFromPayload(nested);
+	}
+	return undefined;
+}
+
+function parseStructuredErrorMessage(raw: string): string | undefined {
+	const trimmed = raw.trim();
+	if (!trimmed) return undefined;
+	const candidates = new Set<string>([trimmed]);
+	const firstBrace = trimmed.indexOf("{");
+	const lastBrace = trimmed.lastIndexOf("}");
+	if (firstBrace >= 0 && lastBrace > firstBrace) {
+		candidates.add(trimmed.slice(firstBrace, lastBrace + 1));
+	}
+
+	for (const candidate of candidates) {
+		try {
+			const parsed = JSON.parse(candidate) as unknown;
+			const message = extractErrorMessageFromPayload(parsed);
+			if (message) return message;
+		} catch {
+			// ignore non-JSON candidates
+		}
+	}
+	return undefined;
+}
+
+function normalizeFailureDetail(
+	message: string | undefined,
+	reason: string | undefined,
+): string {
+	const reasonLabel = formatReasonLabel(reason);
+	const raw = message?.trim() || reasonLabel || "refresh failed";
+	const structured = parseStructuredErrorMessage(raw);
+	const normalized = collapseWhitespace(structured ?? raw);
+	const bounded = normalized.length > 260 ? `${normalized.slice(0, 257)}...` : normalized;
+	return bounded.length > 0 ? bounded : "refresh failed";
+}
+
+function joinStyledSegments(parts: string[]): string {
+	if (parts.length === 0) return "";
+	const separator = stylePromptText(" | ", "muted");
+	return parts.join(separator);
+}
+
+function formatResultSummary(
+	segments: ReadonlyArray<{ text: string; tone: PromptTone }>,
+): string {
+	const rendered = segments.map((segment) => stylePromptText(segment.text, segment.tone));
+	return `${stylePromptText("Result:", "accent")} ${joinStyledSegments(rendered)}`;
+}
+
+function styleQuotaSummary(summary: string): string {
+	const normalized = collapseWhitespace(summary);
+	if (!normalized) return stylePromptText(summary, "muted");
+	const segments = normalized.split("|").map((segment) => segment.trim()).filter(Boolean);
+	if (segments.length === 0) return stylePromptText(normalized, "muted");
+
+	const rendered = segments.map((segment) => {
+		if (/rate-limited/i.test(segment)) {
+			return stylePromptText(segment, "danger");
+		}
+		const match = segment.match(/^([0-9a-zA-Z]+)\s+(\d{1,3})%$/);
+		if (!match) {
+			return stylePromptText(segment, "muted");
+		}
+		const windowLabel = match[1] ?? "";
+		const leftPercent = Number.parseInt(match[2] ?? "", 10);
+		if (!Number.isFinite(leftPercent)) {
+			return stylePromptText(segment, "muted");
+		}
+		const tone = quotaToneFromLeftPercent(leftPercent);
+		return `${stylePromptText(windowLabel, "muted")} ${stylePromptText(`${leftPercent}%`, tone)}`;
+	});
+
+	return joinStyledSegments(rendered);
+}
+
+function styleAccountDetailText(detail: string, fallbackTone: PromptTone = "muted"): string {
+	const compact = collapseWhitespace(detail);
+	if (!compact) return stylePromptText("", fallbackTone);
+
+	const quotaMatch = compact.match(/^(.*?)\(([^()]*\d{1,3}%[^()]*)\)(.*)$/);
+	if (quotaMatch) {
+		const prefix = (quotaMatch[1] ?? "").trim();
+		const quota = (quotaMatch[2] ?? "").trim();
+		const suffix = (quotaMatch[3] ?? "").trim();
+
+		const prefixTone: PromptTone = /failed|error/i.test(prefix)
+			? "danger"
+			: /ok|working|succeeded|valid/i.test(prefix)
+				? "success"
+				: fallbackTone;
+		const suffixTone: PromptTone = /re-login|stale|warning|retry|fallback/i.test(suffix)
+			? "warning"
+			: /failed|error/i.test(suffix)
+				? "danger"
+				: "muted";
+
+		const chunks: string[] = [];
+		if (prefix) chunks.push(stylePromptText(prefix, prefixTone));
+		chunks.push(`(${styleQuotaSummary(quota)})`);
+		if (suffix) chunks.push(stylePromptText(suffix, suffixTone));
+		return chunks.join(" ");
+	}
+
+	if (/rate-limited/i.test(compact)) return stylePromptText(compact, "danger");
+	if (/re-login|stale|warning|fallback/i.test(compact)) return stylePromptText(compact, "warning");
+	if (/failed|error/i.test(compact)) return stylePromptText(compact, "danger");
+	if (/ok|working|succeeded|valid/i.test(compact)) return stylePromptText(compact, "success");
+	return stylePromptText(compact, fallbackTone);
+}
+
+function riskTone(level: ForecastAccountResult["riskLevel"]): "success" | "warning" | "danger" {
+	if (level === "low") return "success";
+	if (level === "medium") return "warning";
+	return "danger";
+}
+
+function availabilityTone(
+	availability: ForecastAccountResult["availability"],
+): "success" | "warning" | "danger" {
+	if (availability === "ready") return "success";
+	if (availability === "delayed") return "warning";
+	return "danger";
+}
+
+type DashboardDisplaySettingKey =
+	| "menuShowStatusBadge"
+	| "menuShowCurrentBadge"
+	| "menuShowLastUsed"
+	| "menuShowQuotaSummary"
+	| "menuShowQuotaCooldown"
+	| "menuShowDetailsForUnselectedRows"
+	| "menuShowFetchStatus"
+	| "menuHighlightCurrentRow"
+	| "menuSortEnabled"
+	| "menuSortPinCurrent"
+	| "menuSortQuickSwitchVisibleRow";
+
+interface DashboardDisplaySettingOption {
+	key: DashboardDisplaySettingKey;
+	label: string;
+	description: string;
+}
+
+const DASHBOARD_DISPLAY_OPTIONS: DashboardDisplaySettingOption[] = [
+	{
+		key: "menuShowStatusBadge",
+		label: "Show Status Badges",
+		description: "Show [ok], [active], and similar badges.",
+	},
+	{
+		key: "menuShowCurrentBadge",
+		label: "Show [current]",
+		description: "Mark the account active in Codex.",
+	},
+	{
+		key: "menuShowLastUsed",
+		label: "Show Last Used",
+		description: "Show relative usage like 'today'.",
+	},
+	{
+		key: "menuShowQuotaSummary",
+		label: "Show Limits (5h / 7d)",
+		description: "Show limit bars in each row.",
+	},
+	{
+		key: "menuShowQuotaCooldown",
+		label: "Show Limit Cooldowns",
+		description: "Show reset timers next to 5h/7d bars.",
+	},
+	{
+		key: "menuShowFetchStatus",
+		label: "Show Fetch Status",
+		description: "Show background limit refresh status in the menu subtitle.",
+	},
+	{
+		key: "menuHighlightCurrentRow",
+		label: "Highlight Current Row",
+		description: "Use stronger color on the current row.",
+	},
+	{
+		key: "menuSortEnabled",
+		label: "Enable Smart Sort",
+		description: "Sort accounts by readiness (view only).",
+	},
+	{
+		key: "menuSortPinCurrent",
+		label: "Pin [current] when tied",
+		description: "Keep current at top only when it is equally ready.",
+	},
+	{
+		key: "menuSortQuickSwitchVisibleRow",
+		label: "Quick Switch Uses Visible Rows",
+		description: "Number keys (1-9) follow what you see in the list.",
+	},
+];
+
+const DEFAULT_STATUSLINE_FIELDS: DashboardStatuslineField[] = ["last-used", "limits", "status"];
+const AUTO_RETURN_OPTIONS_MS = [1_000, 2_000, 4_000] as const;
+const MENU_QUOTA_TTL_OPTIONS_MS = [60_000, 5 * 60_000, 10 * 60_000] as const;
+const THEME_PRESET_OPTIONS: DashboardThemePreset[] = ["green", "blue"];
+const ACCENT_COLOR_OPTIONS: DashboardAccentColor[] = ["green", "cyan", "blue", "yellow"];
+const PREVIEW_ACCOUNT_EMAIL = "demo@example.com";
+const PREVIEW_LAST_USED = "today";
+const PREVIEW_STATUS = "active";
+const PREVIEW_LIMITS = "5h ██████▒▒▒▒ 62% | 7d █████▒▒▒▒▒ 49%";
+const PREVIEW_LIMIT_COOLDOWNS = "5h reset 1h 20m | 7d reset 2d 04h";
+type PreviewFocusKey =
+	| DashboardDisplaySettingKey
+	| DashboardStatuslineField
+	| "menuSortMode"
+	| "menuLayoutMode"
+	| null;
+
+type BackendToggleSettingKey =
+	| "liveAccountSync"
+	| "sessionAffinity"
+	| "proactiveRefreshGuardian"
+	| "retryAllAccountsRateLimited"
+	| "parallelProbing"
+	| "storageBackupEnabled"
+	| "preemptiveQuotaEnabled"
+	| "fastSession"
+	| "sessionRecovery"
+	| "autoResume"
+	| "perProjectAccounts";
+
+type BackendNumberSettingKey =
+	| "liveAccountSyncDebounceMs"
+	| "liveAccountSyncPollMs"
+	| "sessionAffinityTtlMs"
+	| "sessionAffinityMaxEntries"
+	| "proactiveRefreshIntervalMs"
+	| "proactiveRefreshBufferMs"
+	| "parallelProbingMaxConcurrency"
+	| "fastSessionMaxInputItems"
+	| "networkErrorCooldownMs"
+	| "serverErrorCooldownMs"
+	| "fetchTimeoutMs"
+	| "streamStallTimeoutMs"
+	| "tokenRefreshSkewMs"
+	| "preemptiveQuotaRemainingPercent5h"
+	| "preemptiveQuotaRemainingPercent7d"
+	| "preemptiveQuotaMaxDeferralMs";
+
+type BackendSettingFocusKey = BackendToggleSettingKey | BackendNumberSettingKey | null;
+
+interface BackendToggleSettingOption {
+	key: BackendToggleSettingKey;
+	label: string;
+	description: string;
+}
+
+interface BackendNumberSettingOption {
+	key: BackendNumberSettingKey;
+	label: string;
+	description: string;
+	min: number;
+	max: number;
+	step: number;
+	unit: "ms" | "percent" | "count";
+}
+
+type BackendCategoryKey =
+	| "session-sync"
+	| "rotation-quota"
+	| "refresh-recovery"
+	| "performance-timeouts";
+
+interface BackendCategoryOption {
+	key: BackendCategoryKey;
+	label: string;
+	description: string;
+	toggleKeys: BackendToggleSettingKey[];
+	numberKeys: BackendNumberSettingKey[];
+}
+
+const BACKEND_TOGGLE_OPTIONS: BackendToggleSettingOption[] = [
+	{
+		key: "liveAccountSync",
+		label: "Enable Live Sync",
+		description: "Keep accounts synced when files change in another window.",
+	},
+	{
+		key: "sessionAffinity",
+		label: "Enable Session Affinity",
+		description: "Try to keep each conversation on the same account.",
+	},
+	{
+		key: "proactiveRefreshGuardian",
+		label: "Enable Token Refresh Guard",
+		description: "Refresh tokens early in the background.",
+	},
+	{
+		key: "retryAllAccountsRateLimited",
+		label: "Retry When All Rate-Limited",
+		description: "If all accounts are limited, wait and try again.",
+	},
+	{
+		key: "parallelProbing",
+		label: "Enable Parallel Probing",
+		description: "Check multiple accounts at the same time.",
+	},
+	{
+		key: "storageBackupEnabled",
+		label: "Enable Storage Backups",
+		description: "Create a backup before account data changes.",
+	},
+	{
+		key: "preemptiveQuotaEnabled",
+		label: "Enable Quota Deferral",
+		description: "Delay requests before limits are fully exhausted.",
+	},
+	{
+		key: "fastSession",
+		label: "Enable Fast Session Mode",
+		description: "Use lighter request handling for faster responses.",
+	},
+	{
+		key: "sessionRecovery",
+		label: "Enable Session Recovery",
+		description: "Restore recoverable sessions after restart.",
+	},
+	{
+		key: "autoResume",
+		label: "Enable Auto Resume",
+		description: "Automatically continue sessions when possible.",
+	},
+	{
+		key: "perProjectAccounts",
+		label: "Enable Per-Project Accounts",
+		description: "Keep separate account lists for each project.",
+	},
+];
+
+const BACKEND_NUMBER_OPTIONS: BackendNumberSettingOption[] = [
+	{
+		key: "liveAccountSyncDebounceMs",
+		label: "Live Sync Debounce",
+		description: "Wait this long before applying sync file changes.",
+		min: 50,
+		max: 10_000,
+		step: 50,
+		unit: "ms",
+	},
+	{
+		key: "liveAccountSyncPollMs",
+		label: "Live Sync Poll",
+		description: "How often to check files for account updates.",
+		min: 500,
+		max: 60_000,
+		step: 500,
+		unit: "ms",
+	},
+	{
+		key: "sessionAffinityTtlMs",
+		label: "Session Affinity TTL",
+		description: "How long conversation-to-account mapping is kept.",
+		min: 1_000,
+		max: 24 * 60 * 60_000,
+		step: 60_000,
+		unit: "ms",
+	},
+	{
+		key: "sessionAffinityMaxEntries",
+		label: "Session Affinity Max Entries",
+		description: "Maximum stored conversation mappings.",
+		min: 8,
+		max: 4_096,
+		step: 32,
+		unit: "count",
+	},
+	{
+		key: "proactiveRefreshIntervalMs",
+		label: "Refresh Guard Interval",
+		description: "How often to scan for tokens near expiry.",
+		min: 5_000,
+		max: 10 * 60_000,
+		step: 5_000,
+		unit: "ms",
+	},
+	{
+		key: "proactiveRefreshBufferMs",
+		label: "Refresh Guard Buffer",
+		description: "How early to refresh before expiry.",
+		min: 30_000,
+		max: 10 * 60_000,
+		step: 30_000,
+		unit: "ms",
+	},
+	{
+		key: "parallelProbingMaxConcurrency",
+		label: "Parallel Probe Concurrency",
+		description: "Maximum checks running at once.",
+		min: 1,
+		max: 5,
+		step: 1,
+		unit: "count",
+	},
+	{
+		key: "fastSessionMaxInputItems",
+		label: "Fast Session Max Inputs",
+		description: "Max number of input items kept in fast mode.",
+		min: 8,
+		max: 200,
+		step: 2,
+		unit: "count",
+	},
+	{
+		key: "networkErrorCooldownMs",
+		label: "Network Error Cooldown",
+		description: "Wait time after network errors before retry.",
+		min: 0,
+		max: 120_000,
+		step: 500,
+		unit: "ms",
+	},
+	{
+		key: "serverErrorCooldownMs",
+		label: "Server Error Cooldown",
+		description: "Wait time after server errors before retry.",
+		min: 0,
+		max: 120_000,
+		step: 500,
+		unit: "ms",
+	},
+	{
+		key: "fetchTimeoutMs",
+		label: "Request Timeout",
+		description: "Max time to wait for a request.",
+		min: 1_000,
+		max: 10 * 60_000,
+		step: 5_000,
+		unit: "ms",
+	},
+	{
+		key: "streamStallTimeoutMs",
+		label: "Stream Stall Timeout",
+		description: "Max wait before a stuck stream is retried.",
+		min: 1_000,
+		max: 10 * 60_000,
+		step: 5_000,
+		unit: "ms",
+	},
+	{
+		key: "tokenRefreshSkewMs",
+		label: "Token Refresh Buffer",
+		description: "Refresh this long before token expiry.",
+		min: 0,
+		max: 10 * 60_000,
+		step: 10_000,
+		unit: "ms",
+	},
+	{
+		key: "preemptiveQuotaRemainingPercent5h",
+		label: "5h Remaining Threshold",
+		description: "Start delaying when 5h remaining reaches this percent.",
+		min: 0,
+		max: 100,
+		step: 1,
+		unit: "percent",
+	},
+	{
+		key: "preemptiveQuotaRemainingPercent7d",
+		label: "7d Remaining Threshold",
+		description: "Start delaying when weekly remaining reaches this percent.",
+		min: 0,
+		max: 100,
+		step: 1,
+		unit: "percent",
+	},
+	{
+		key: "preemptiveQuotaMaxDeferralMs",
+		label: "Max Preemptive Deferral",
+		description: "Maximum time allowed for quota-based delay.",
+		min: 1_000,
+		max: 24 * 60 * 60_000,
+		step: 60_000,
+		unit: "ms",
+	},
+];
+
+const BACKEND_DEFAULTS = getDefaultPluginConfig();
+const BACKEND_TOGGLE_OPTION_BY_KEY = new Map<BackendToggleSettingKey, BackendToggleSettingOption>(
+	BACKEND_TOGGLE_OPTIONS.map((option) => [option.key, option]),
+);
+const BACKEND_NUMBER_OPTION_BY_KEY = new Map<BackendNumberSettingKey, BackendNumberSettingOption>(
+	BACKEND_NUMBER_OPTIONS.map((option) => [option.key, option]),
+);
+const BACKEND_CATEGORY_OPTIONS: BackendCategoryOption[] = [
+	{
+		key: "session-sync",
+		label: "Session & Sync",
+		description: "Sync and session behavior.",
+		toggleKeys: [
+			"liveAccountSync",
+			"sessionAffinity",
+			"perProjectAccounts",
+			"sessionRecovery",
+			"autoResume",
+		],
+		numberKeys: [
+			"liveAccountSyncDebounceMs",
+			"liveAccountSyncPollMs",
+			"sessionAffinityTtlMs",
+			"sessionAffinityMaxEntries",
+		],
+	},
+	{
+		key: "rotation-quota",
+		label: "Rotation & Quota",
+		description: "Quota and retry behavior.",
+		toggleKeys: ["preemptiveQuotaEnabled", "retryAllAccountsRateLimited"],
+		numberKeys: [
+			"preemptiveQuotaRemainingPercent5h",
+			"preemptiveQuotaRemainingPercent7d",
+			"preemptiveQuotaMaxDeferralMs",
+		],
+	},
+	{
+		key: "refresh-recovery",
+		label: "Refresh & Recovery",
+		description: "Token refresh and recovery safety.",
+		toggleKeys: ["proactiveRefreshGuardian", "storageBackupEnabled"],
+		numberKeys: [
+			"proactiveRefreshIntervalMs",
+			"proactiveRefreshBufferMs",
+			"tokenRefreshSkewMs",
+		],
+	},
+	{
+		key: "performance-timeouts",
+		label: "Performance & Timeouts",
+		description: "Speed, probing, and timeout controls.",
+		toggleKeys: ["fastSession", "parallelProbing"],
+		numberKeys: [
+			"fastSessionMaxInputItems",
+			"parallelProbingMaxConcurrency",
+			"fetchTimeoutMs",
+			"streamStallTimeoutMs",
+			"networkErrorCooldownMs",
+			"serverErrorCooldownMs",
+		],
+	},
+];
+
+function normalizeStatuslineFields(
+	fields: DashboardStatuslineField[] | undefined,
+): DashboardStatuslineField[] {
+	const source = fields ?? DEFAULT_STATUSLINE_FIELDS;
+	const seen = new Set<DashboardStatuslineField>();
+	const normalized: DashboardStatuslineField[] = [];
+	for (const field of source) {
+		if (seen.has(field)) continue;
+		seen.add(field);
+		normalized.push(field);
+	}
+	if (normalized.length === 0) {
+		return [...DEFAULT_STATUSLINE_FIELDS];
+	}
+	return normalized;
+}
+
+function highlightPreviewToken(
+	text: string,
+	ui: ReturnType<typeof getUiRuntimeOptions>,
+): string {
+	if (!output.isTTY) return text;
+	if (ui.v2Enabled) {
+		return `${ui.theme.colors.accent}${ANSI.bold}${text}${ui.theme.colors.reset}`;
+	}
+	return `${ANSI.cyan}${ANSI.bold}${text}${ANSI.reset}`;
+}
+
+function isLastUsedPreviewFocus(focus: PreviewFocusKey): boolean {
+	return focus === "menuShowLastUsed" || focus === "last-used";
+}
+
+function isLimitsPreviewFocus(focus: PreviewFocusKey): boolean {
+	return focus === "menuShowQuotaSummary" || focus === "limits";
+}
+
+function isLimitsCooldownPreviewFocus(focus: PreviewFocusKey): boolean {
+	return focus === "menuShowQuotaCooldown";
+}
+
+function isStatusPreviewFocus(focus: PreviewFocusKey): boolean {
+	return focus === "menuShowStatusBadge" || focus === "status";
+}
+
+function isCurrentBadgePreviewFocus(focus: PreviewFocusKey): boolean {
+	return focus === "menuShowCurrentBadge";
+}
+
+function isCurrentRowPreviewFocus(focus: PreviewFocusKey): boolean {
+	return focus === "menuHighlightCurrentRow";
+}
+
+function isExpandedRowsPreviewFocus(focus: PreviewFocusKey): boolean {
+	return focus === "menuShowDetailsForUnselectedRows" || focus === "menuLayoutMode";
+}
+
+function buildSummaryPreviewText(
+	settings: DashboardDisplaySettings,
+	ui: ReturnType<typeof getUiRuntimeOptions>,
+	focus: PreviewFocusKey = null,
+): string {
+	const partsByField = new Map<DashboardStatuslineField, string>();
+	if (settings.menuShowLastUsed !== false) {
+		const part = `last used: ${PREVIEW_LAST_USED}`;
+		partsByField.set(
+			"last-used",
+			isLastUsedPreviewFocus(focus) ? highlightPreviewToken(part, ui) : part,
+		);
+	}
+	if (settings.menuShowQuotaSummary !== false) {
+		const limitsText = settings.menuShowQuotaCooldown === false
+			? PREVIEW_LIMITS
+			: `${PREVIEW_LIMITS} | ${PREVIEW_LIMIT_COOLDOWNS}`;
+		const part = `limits: ${limitsText}`;
+		partsByField.set(
+			"limits",
+			isLimitsPreviewFocus(focus) || isLimitsCooldownPreviewFocus(focus)
+				? highlightPreviewToken(part, ui)
+				: part,
+		);
+	}
+	if (settings.menuShowStatusBadge === false) {
+		const part = `status: ${PREVIEW_STATUS}`;
+		partsByField.set(
+			"status",
+			isStatusPreviewFocus(focus) ? highlightPreviewToken(part, ui) : part,
+		);
+	}
+
+	const orderedParts = normalizeStatuslineFields(settings.menuStatuslineFields)
+		.map((field) => partsByField.get(field))
+		.filter((part): part is string => typeof part === "string" && part.length > 0);
+	if (orderedParts.length > 0) {
+		return orderedParts.join(" | ");
+	}
+
+	const showsStatusField = normalizeStatuslineFields(settings.menuStatuslineFields).includes("status");
+	if (showsStatusField && settings.menuShowStatusBadge !== false) {
+		const note = "status text appears only when status badges are hidden";
+		return isStatusPreviewFocus(focus) ? highlightPreviewToken(note, ui) : note;
+	}
+	return "no summary text is visible with current account-list settings";
+}
+
+function buildAccountListPreview(
+	settings: DashboardDisplaySettings,
+	ui: ReturnType<typeof getUiRuntimeOptions>,
+	focus: PreviewFocusKey = null,
+): { label: string; hint: string } {
+	const badges: string[] = [];
+	if (settings.menuShowCurrentBadge !== false) {
+		const currentBadge = "[current]";
+		badges.push(
+			isCurrentBadgePreviewFocus(focus) ? highlightPreviewToken(currentBadge, ui) : currentBadge,
+		);
+	}
+	if (settings.menuShowStatusBadge !== false) {
+		const statusBadge = "[active]";
+		badges.push(
+			isStatusPreviewFocus(focus) ? highlightPreviewToken(statusBadge, ui) : statusBadge,
+		);
+	}
+	const badgeSuffix = badges.length > 0 ? ` ${badges.join(" ")}` : "";
+	const accountEmail = isCurrentRowPreviewFocus(focus)
+		? highlightPreviewToken(PREVIEW_ACCOUNT_EMAIL, ui)
+		: PREVIEW_ACCOUNT_EMAIL;
+	const rowDetailMode = resolveMenuLayoutMode(settings) === "expanded-rows"
+		? "details shown on all rows"
+		: "details shown on selected row only";
+	const detailModeText = isExpandedRowsPreviewFocus(focus)
+		? highlightPreviewToken(rowDetailMode, ui)
+		: rowDetailMode;
+	return {
+		label: `1. ${accountEmail}${badgeSuffix}`,
+		hint: `${buildSummaryPreviewText(settings, ui, focus)}\n${detailModeText}`,
+	};
+}
+
+function cloneDashboardSettings(settings: DashboardDisplaySettings): DashboardDisplaySettings {
+	const layoutMode = resolveMenuLayoutMode(settings);
+	return {
+		showPerAccountRows: settings.showPerAccountRows,
+		showQuotaDetails: settings.showQuotaDetails,
+		showForecastReasons: settings.showForecastReasons,
+		showRecommendations: settings.showRecommendations,
+		showLiveProbeNotes: settings.showLiveProbeNotes,
+		actionAutoReturnMs: settings.actionAutoReturnMs ?? 2_000,
+		actionPauseOnKey: settings.actionPauseOnKey ?? true,
+		menuAutoFetchLimits: settings.menuAutoFetchLimits ?? true,
+		menuSortEnabled:
+			settings.menuSortEnabled ?? (DEFAULT_DASHBOARD_DISPLAY_SETTINGS.menuSortEnabled ?? true),
+		menuSortMode:
+			settings.menuSortMode ?? (DEFAULT_DASHBOARD_DISPLAY_SETTINGS.menuSortMode ?? "ready-first"),
+		menuSortPinCurrent:
+			settings.menuSortPinCurrent ??
+			(DEFAULT_DASHBOARD_DISPLAY_SETTINGS.menuSortPinCurrent ?? false),
+		menuSortQuickSwitchVisibleRow: settings.menuSortQuickSwitchVisibleRow ?? true,
+		uiThemePreset: settings.uiThemePreset ?? "green",
+		uiAccentColor: settings.uiAccentColor ?? "green",
+		menuShowStatusBadge: settings.menuShowStatusBadge ?? true,
+		menuShowCurrentBadge: settings.menuShowCurrentBadge ?? true,
+		menuShowLastUsed: settings.menuShowLastUsed ?? true,
+		menuShowQuotaSummary: settings.menuShowQuotaSummary ?? true,
+		menuShowQuotaCooldown: settings.menuShowQuotaCooldown ?? true,
+		menuShowFetchStatus: settings.menuShowFetchStatus ?? true,
+		menuShowDetailsForUnselectedRows: layoutMode === "expanded-rows",
+		menuLayoutMode: layoutMode,
+		menuQuotaTtlMs: settings.menuQuotaTtlMs ?? 5 * 60_000,
+		menuFocusStyle: settings.menuFocusStyle ?? "row-invert",
+		menuHighlightCurrentRow: settings.menuHighlightCurrentRow ?? true,
+		menuStatuslineFields: [...normalizeStatuslineFields(settings.menuStatuslineFields)],
+	};
+}
+
+function dashboardSettingsEqual(
+	left: DashboardDisplaySettings,
+	right: DashboardDisplaySettings,
+): boolean {
+	return (
+		left.showPerAccountRows === right.showPerAccountRows &&
+		left.showQuotaDetails === right.showQuotaDetails &&
+		left.showForecastReasons === right.showForecastReasons &&
+		left.showRecommendations === right.showRecommendations &&
+		left.showLiveProbeNotes === right.showLiveProbeNotes &&
+		(left.actionAutoReturnMs ?? 2_000) === (right.actionAutoReturnMs ?? 2_000) &&
+		(left.actionPauseOnKey ?? true) === (right.actionPauseOnKey ?? true) &&
+		(left.menuAutoFetchLimits ?? true) === (right.menuAutoFetchLimits ?? true) &&
+		(left.menuSortEnabled ?? (DEFAULT_DASHBOARD_DISPLAY_SETTINGS.menuSortEnabled ?? true)) ===
+			(right.menuSortEnabled ?? (DEFAULT_DASHBOARD_DISPLAY_SETTINGS.menuSortEnabled ?? true)) &&
+		(left.menuSortMode ?? (DEFAULT_DASHBOARD_DISPLAY_SETTINGS.menuSortMode ?? "ready-first")) ===
+			(right.menuSortMode ?? (DEFAULT_DASHBOARD_DISPLAY_SETTINGS.menuSortMode ?? "ready-first")) &&
+		(left.menuSortPinCurrent ?? (DEFAULT_DASHBOARD_DISPLAY_SETTINGS.menuSortPinCurrent ?? false)) ===
+			(right.menuSortPinCurrent ?? (DEFAULT_DASHBOARD_DISPLAY_SETTINGS.menuSortPinCurrent ?? false)) &&
+		(left.menuSortQuickSwitchVisibleRow ?? true) ===
+			(right.menuSortQuickSwitchVisibleRow ?? true) &&
+		(left.uiThemePreset ?? "green") === (right.uiThemePreset ?? "green") &&
+		(left.uiAccentColor ?? "green") === (right.uiAccentColor ?? "green") &&
+		(left.menuShowStatusBadge ?? true) === (right.menuShowStatusBadge ?? true) &&
+		(left.menuShowCurrentBadge ?? true) === (right.menuShowCurrentBadge ?? true) &&
+		(left.menuShowLastUsed ?? true) === (right.menuShowLastUsed ?? true) &&
+		(left.menuShowQuotaSummary ?? true) === (right.menuShowQuotaSummary ?? true) &&
+		(left.menuShowQuotaCooldown ?? true) === (right.menuShowQuotaCooldown ?? true) &&
+		(left.menuShowFetchStatus ?? true) === (right.menuShowFetchStatus ?? true) &&
+		resolveMenuLayoutMode(left) === resolveMenuLayoutMode(right) &&
+		(left.menuQuotaTtlMs ?? 5 * 60_000) === (right.menuQuotaTtlMs ?? 5 * 60_000) &&
+		(left.menuFocusStyle ?? "row-invert") === (right.menuFocusStyle ?? "row-invert") &&
+		(left.menuHighlightCurrentRow ?? true) === (right.menuHighlightCurrentRow ?? true) &&
+		JSON.stringify(normalizeStatuslineFields(left.menuStatuslineFields)) ===
+			JSON.stringify(normalizeStatuslineFields(right.menuStatuslineFields))
+	);
+}
+
+function cloneBackendPluginConfig(config: PluginConfig): PluginConfig {
+	const fallbackChain = config.unsupportedCodexFallbackChain;
+	return {
+		...BACKEND_DEFAULTS,
+		...config,
+		unsupportedCodexFallbackChain: fallbackChain && typeof fallbackChain === "object"
+			? { ...fallbackChain }
+			: {},
+	};
+}
+
+function backendSettingsSnapshot(config: PluginConfig): Record<string, unknown> {
+	const snapshot: Record<string, unknown> = {};
+	for (const option of BACKEND_TOGGLE_OPTIONS) {
+		snapshot[option.key] = config[option.key] ?? BACKEND_DEFAULTS[option.key] ?? false;
+	}
+	for (const option of BACKEND_NUMBER_OPTIONS) {
+		snapshot[option.key] = config[option.key] ?? BACKEND_DEFAULTS[option.key] ?? option.min;
+	}
+	return snapshot;
+}
+
+function backendSettingsEqual(left: PluginConfig, right: PluginConfig): boolean {
+	return JSON.stringify(backendSettingsSnapshot(left)) === JSON.stringify(backendSettingsSnapshot(right));
+}
+
+function formatBackendNumberValue(option: BackendNumberSettingOption, value: number): string {
+	if (option.unit === "percent") return `${Math.round(value)}%`;
+	if (option.unit === "count") return `${Math.round(value)}`;
+	if (value >= 60_000 && value % 60_000 === 0) {
+		return `${Math.round(value / 60_000)}m`;
+	}
+	if (value >= 1_000 && value % 1_000 === 0) {
+		return `${Math.round(value / 1_000)}s`;
+	}
+	return `${Math.round(value)}ms`;
+}
+
+function clampBackendNumber(option: BackendNumberSettingOption, value: number): number {
+	return Math.max(option.min, Math.min(option.max, Math.round(value)));
+}
+
+function buildBackendSettingsPreview(
+	config: PluginConfig,
+	ui: ReturnType<typeof getUiRuntimeOptions>,
+	focus: BackendSettingFocusKey = null,
+): { label: string; hint: string } {
+	const liveSync = config.liveAccountSync ?? BACKEND_DEFAULTS.liveAccountSync ?? true;
+	const affinity = config.sessionAffinity ?? BACKEND_DEFAULTS.sessionAffinity ?? true;
+	const preemptive = config.preemptiveQuotaEnabled ?? BACKEND_DEFAULTS.preemptiveQuotaEnabled ?? true;
+	const threshold5h =
+		config.preemptiveQuotaRemainingPercent5h ??
+		BACKEND_DEFAULTS.preemptiveQuotaRemainingPercent5h ??
+		5;
+	const threshold7d =
+		config.preemptiveQuotaRemainingPercent7d ??
+		BACKEND_DEFAULTS.preemptiveQuotaRemainingPercent7d ??
+		5;
+	const fetchTimeout = config.fetchTimeoutMs ?? BACKEND_DEFAULTS.fetchTimeoutMs ?? 60_000;
+	const stallTimeout = config.streamStallTimeoutMs ?? BACKEND_DEFAULTS.streamStallTimeoutMs ?? 45_000;
+	const fetchTimeoutOption = BACKEND_NUMBER_OPTION_BY_KEY.get("fetchTimeoutMs");
+	const stallTimeoutOption = BACKEND_NUMBER_OPTION_BY_KEY.get("streamStallTimeoutMs");
+
+	const highlightIfFocused = (key: BackendSettingFocusKey, text: string): string => {
+		if (focus !== key) return text;
+		return highlightPreviewToken(text, ui);
+	};
+
+	const label = [
+		`live sync ${highlightIfFocused("liveAccountSync", liveSync ? "on" : "off")}`,
+		`affinity ${highlightIfFocused("sessionAffinity", affinity ? "on" : "off")}`,
+		`preemptive ${highlightIfFocused("preemptiveQuotaEnabled", preemptive ? "on" : "off")}`,
+	].join(" | ");
+
+	const hint = [
+		`thresholds 5h<=${highlightIfFocused("preemptiveQuotaRemainingPercent5h", `${threshold5h}%`)}`,
+		`7d<=${highlightIfFocused("preemptiveQuotaRemainingPercent7d", `${threshold7d}%`)}`,
+		`timeouts ${highlightIfFocused("fetchTimeoutMs", fetchTimeoutOption ? formatBackendNumberValue(fetchTimeoutOption, fetchTimeout) : `${fetchTimeout}ms`)}/${highlightIfFocused("streamStallTimeoutMs", stallTimeoutOption ? formatBackendNumberValue(stallTimeoutOption, stallTimeout) : `${stallTimeout}ms`)}`,
+	].join(" | ");
+
+	return { label, hint };
+}
+
+function buildBackendConfigPatch(config: PluginConfig): Partial<PluginConfig> {
+	const patch: Partial<PluginConfig> = {};
+	for (const option of BACKEND_TOGGLE_OPTIONS) {
+		const value = config[option.key];
+		if (typeof value === "boolean") {
+			patch[option.key] = value;
+		}
+	}
+	for (const option of BACKEND_NUMBER_OPTIONS) {
+		const value = config[option.key];
+		if (typeof value === "number" && Number.isFinite(value)) {
+			patch[option.key] = clampBackendNumber(option, value);
+		}
+	}
+	return patch;
+}
+
+function applyUiThemeFromDashboardSettings(settings: DashboardDisplaySettings): void {
+	const current = getUiRuntimeOptions();
+	setUiRuntimeOptions({
+		v2Enabled: current.v2Enabled,
+		colorProfile: current.colorProfile,
+		glyphMode: current.glyphMode,
+		palette: settings.uiThemePreset ?? "green",
+		accent: settings.uiAccentColor ?? "green",
+	});
+}
+
+function formatDashboardSettingState(value: boolean): string {
+	return value ? "[x]" : "[ ]";
+}
+
+function formatQuotaSnapshotForDashboard(
+	snapshot: Awaited<ReturnType<typeof fetchCodexQuotaSnapshot>>,
+	settings: DashboardDisplaySettings,
+): string {
+	if (!settings.showQuotaDetails) return "live session OK";
+	return `live session OK (${formatCompactQuotaSnapshot(snapshot)})`;
+}
+
+function isAbortError(error: unknown): boolean {
+	if (!(error instanceof Error)) return false;
+	const maybe = error as Error & { code?: string };
+	return maybe.name === "AbortError" || maybe.code === "ABORT_ERR";
+}
+
+function isUserCancelledOAuth(result: TokenResult): boolean {
+	if (result.type !== "failed") return false;
+	const message = (result.message ?? "").toLowerCase();
+	return message.includes("cancelled");
+}
+
+function printUsage(): void {
+	console.log(
+		[
+			"Codex Multi-Auth CLI",
+			"",
+			"Usage:",
+			"  codex-multi-auth auth login",
+			"  codex-multi-auth auth list",
+			"  codex-multi-auth auth status",
+			"  codex-multi-auth auth switch <index>",
+			"  codex-multi-auth auth check",
+			"  codex-multi-auth auth features",
+			"  codex-multi-auth auth verify-flagged [--dry-run] [--json] [--no-restore]",
+			"  codex-multi-auth auth forecast [--live] [--json] [--model <model>]",
+			"  codex-multi-auth auth report [--live] [--json] [--model <model>] [--out <path>]",
+			"  codex-multi-auth auth fix [--dry-run] [--json]",
+			"  codex-multi-auth auth doctor [--json] [--fix] [--dry-run]",
+			"",
+			"Notes:",
+			"  - Uses ~/.codex/multi-auth/openai-codex-accounts.json",
+			"  - Syncs active account into Codex CLI auth state",
+		].join("\n"),
+	);
+}
+
+interface ImplementedFeature {
+	id: number;
+	name: string;
+}
+
+const IMPLEMENTED_FEATURES: ImplementedFeature[] = [
+	{ id: 1, name: "Multi-account OAuth login dashboard" },
+	{ id: 2, name: "Account add/update dedupe by token/id/email" },
+	{ id: 3, name: "Set current account command" },
+	{ id: 4, name: "Per-family active index handling" },
+	{ id: 5, name: "Quick health check command" },
+	{ id: 6, name: "Full refresh check command" },
+	{ id: 7, name: "Flagged account verification command" },
+	{ id: 8, name: "Flagged account restore flow" },
+	{ id: 9, name: "Best account forecast engine" },
+	{ id: 10, name: "Forecast live quota probing" },
+	{ id: 11, name: "Auto-fix command (safe mode)" },
+	{ id: 12, name: "Doctor diagnostics command" },
+	{ id: 13, name: "JSON outputs for machine automation" },
+	{ id: 14, name: "Report generation command" },
+	{ id: 15, name: "Storage v3 normalization and migration" },
+	{ id: 16, name: "Storage backup and recovery journal" },
+	{ id: 17, name: "Project-scoped and global storage paths" },
+	{ id: 18, name: "Quota cache storage" },
+	{ id: 19, name: "Live account sync watcher" },
+	{ id: 20, name: "Session affinity store" },
+	{ id: 21, name: "Refresh queue dedupe (in-process)" },
+	{ id: 22, name: "Refresh lease dedupe (cross-process)" },
+	{ id: 23, name: "Token rotation mapping in refresh queue" },
+	{ id: 24, name: "Refresh guardian (proactive refresh)" },
+	{ id: 25, name: "Preemptive quota scheduler" },
+	{ id: 26, name: "Entitlement cache for unsupported models" },
+	{ id: 27, name: "Capability policy scoring store" },
+	{ id: 28, name: "Failure policy evaluation module" },
+	{ id: 29, name: "Streaming failover pipeline" },
+	{ id: 30, name: "Rate-limit backoff and cooldown handling" },
+	{ id: 31, name: "OpenCode request transformer bridge" },
+	{ id: 32, name: "Prompt template sync with cache" },
+	{ id: 33, name: "Codex CLI active-account state sync" },
+	{ id: 34, name: "TUI quick-switch hotkeys (1-9)" },
+	{ id: 35, name: "TUI search and help toggles" },
+	{ id: 36, name: "TUI account detail hotkeys (S/R/E/D)" },
+	{ id: 37, name: "TUI settings hub (list/summary/behavior/theme)" },
+	{ id: 38, name: "Dashboard display customization" },
+	{ id: 39, name: "Unified color/theme runtime (v2 UI)" },
+	{ id: 40, name: "OAuth browser-first flow with manual callback fallback" },
+];
+
+function runFeaturesReport(): number {
+	console.log(`Implemented features (${IMPLEMENTED_FEATURES.length})`);
+	console.log("");
+	for (const feature of IMPLEMENTED_FEATURES) {
+		console.log(`${feature.id}. ${feature.name}`);
+	}
+	return 0;
+}
+
+function resolveActiveIndex(
+	storage: AccountStorageV3,
+	family: ModelFamily = "codex",
+): number {
+	const total = storage.accounts.length;
+	if (total === 0) return 0;
+	const rawCandidate = storage.activeIndexByFamily?.[family] ?? storage.activeIndex;
+	const raw = Number.isFinite(rawCandidate) ? rawCandidate : 0;
+	return Math.max(0, Math.min(raw, total - 1));
+}
+
+function getRateLimitResetTimeForFamily(
+	account: { rateLimitResetTimes?: Record<string, number | undefined> },
+	now: number,
+	family: ModelFamily,
+): number | null {
+	const times = account.rateLimitResetTimes;
+	if (!times) return null;
+
+	let minReset: number | null = null;
+	const prefix = `${family}:`;
+	for (const [key, value] of Object.entries(times)) {
+		if (typeof value !== "number") continue;
+		if (value <= now) continue;
+		if (key !== family && !key.startsWith(prefix)) continue;
+		if (minReset === null || value < minReset) {
+			minReset = value;
+		}
+	}
+
+	return minReset;
+}
+
+function formatRateLimitEntry(
+	account: { rateLimitResetTimes?: Record<string, number | undefined> },
+	now: number,
+	family: ModelFamily = "codex",
+): string | null {
+	const resetAt = getRateLimitResetTimeForFamily(account, now, family);
+	if (typeof resetAt !== "number") return null;
+	const remaining = resetAt - now;
+	if (remaining <= 0) return null;
+	return `resets in ${formatWaitTime(remaining)}`;
+}
+
+function normalizeQuotaEmail(email: string | undefined): string | null {
+	const normalized = sanitizeEmail(email);
+	return normalized && normalized.length > 0 ? normalized : null;
+}
+
+function quotaCacheEntryToSnapshot(entry: QuotaCacheEntry): CodexQuotaSnapshot {
+	return {
+		status: entry.status,
+		planType: entry.planType,
+		model: entry.model,
+		primary: {
+			usedPercent: entry.primary.usedPercent,
+			windowMinutes: entry.primary.windowMinutes,
+			resetAtMs: entry.primary.resetAtMs,
+		},
+		secondary: {
+			usedPercent: entry.secondary.usedPercent,
+			windowMinutes: entry.secondary.windowMinutes,
+			resetAtMs: entry.secondary.resetAtMs,
+		},
+	};
+}
+
+function formatCompactQuotaWindowLabel(windowMinutes: number | undefined): string {
+	if (!windowMinutes || !Number.isFinite(windowMinutes) || windowMinutes <= 0) {
+		return "quota";
+	}
+	if (windowMinutes % 1440 === 0) return `${windowMinutes / 1440}d`;
+	if (windowMinutes % 60 === 0) return `${windowMinutes / 60}h`;
+	return `${windowMinutes}m`;
+}
+
+function formatCompactQuotaPart(windowMinutes: number | undefined, usedPercent: number | undefined): string | null {
+	const label = formatCompactQuotaWindowLabel(windowMinutes);
+	if (typeof usedPercent !== "number" || !Number.isFinite(usedPercent)) {
+		return null;
+	}
+	const left = quotaLeftPercentFromUsed(usedPercent);
+	return `${label} ${left}%`;
+}
+
+function quotaLeftPercentFromUsed(usedPercent: number | undefined): number | undefined {
+	if (typeof usedPercent !== "number" || !Number.isFinite(usedPercent)) {
+		return undefined;
+	}
+	return Math.max(0, Math.min(100, Math.round(100 - usedPercent)));
+}
+
+function formatCompactQuotaSnapshot(snapshot: CodexQuotaSnapshot): string {
+	const parts = [
+		formatCompactQuotaPart(snapshot.primary.windowMinutes, snapshot.primary.usedPercent),
+		formatCompactQuotaPart(snapshot.secondary.windowMinutes, snapshot.secondary.usedPercent),
+	].filter((value): value is string => typeof value === "string" && value.length > 0);
+	if (snapshot.status === 429) {
+		parts.push("rate-limited");
+	}
+	if (parts.length > 0) {
+		return parts.join(" | ");
+	}
+	return formatQuotaSnapshotLine(snapshot);
+}
+
+function formatAccountQuotaSummary(entry: QuotaCacheEntry): string {
+	const parts = [
+		formatCompactQuotaPart(entry.primary.windowMinutes, entry.primary.usedPercent),
+		formatCompactQuotaPart(entry.secondary.windowMinutes, entry.secondary.usedPercent),
+	].filter((value): value is string => typeof value === "string" && value.length > 0);
+	if (entry.status === 429) {
+		parts.push("rate-limited");
+	}
+	if (parts.length > 0) {
+		return parts.join(" | ");
+	}
+	return formatQuotaSnapshotLine(quotaCacheEntryToSnapshot(entry));
+}
+
+function getQuotaCacheEntryForAccount(
+	cache: QuotaCacheData,
+	account: Pick<AccountMetadataV3, "accountId" | "email">,
+): QuotaCacheEntry | null {
+	if (account.accountId && cache.byAccountId[account.accountId]) {
+		return cache.byAccountId[account.accountId] ?? null;
+	}
+	const email = normalizeQuotaEmail(account.email);
+	if (email && cache.byEmail[email]) {
+		return cache.byEmail[email] ?? null;
+	}
+	return null;
+}
+
+function updateQuotaCacheForAccount(
+	cache: QuotaCacheData,
+	account: Pick<AccountMetadataV3, "accountId" | "email">,
+	snapshot: CodexQuotaSnapshot,
+): boolean {
+	const nextEntry: QuotaCacheEntry = {
+		updatedAt: Date.now(),
+		status: snapshot.status,
+		model: snapshot.model,
+		planType: snapshot.planType,
+		primary: {
+			usedPercent: snapshot.primary.usedPercent,
+			windowMinutes: snapshot.primary.windowMinutes,
+			resetAtMs: snapshot.primary.resetAtMs,
+		},
+		secondary: {
+			usedPercent: snapshot.secondary.usedPercent,
+			windowMinutes: snapshot.secondary.windowMinutes,
+			resetAtMs: snapshot.secondary.resetAtMs,
+		},
+	};
+
+	let changed = false;
+	if (account.accountId) {
+		cache.byAccountId[account.accountId] = nextEntry;
+		changed = true;
+	}
+	const email = normalizeQuotaEmail(account.email);
+	if (email) {
+		cache.byEmail[email] = nextEntry;
+		changed = true;
+	}
+	return changed;
+}
+
+const DEFAULT_MENU_QUOTA_REFRESH_TTL_MS = 5 * 60_000;
+const MENU_QUOTA_REFRESH_MODEL = "gpt-5-codex";
+
+interface MenuQuotaProbeTarget {
+	account: AccountMetadataV3;
+	accountId: string;
+	accessToken: string;
+}
+
+function resolveMenuQuotaProbeInput(
+	account: AccountMetadataV3,
+	cache: QuotaCacheData,
+	maxAgeMs: number,
+	now: number,
+): { accountId: string; accessToken: string } | null {
+	if (account.enabled === false) return null;
+	if (!hasUsableAccessToken(account, now)) return null;
+
+	const existing = getQuotaCacheEntryForAccount(cache, account);
+	if (
+		existing &&
+		typeof existing.updatedAt === "number" &&
+		Number.isFinite(existing.updatedAt) &&
+		now - existing.updatedAt < maxAgeMs
+	) {
+		return null;
+	}
+
+	const accessToken = account.accessToken;
+	const accountId = accessToken
+		? (account.accountId ?? extractAccountId(accessToken))
+		: account.accountId;
+	if (!accountId || !accessToken) return null;
+	return { accountId, accessToken };
+}
+
+function collectMenuQuotaRefreshTargets(
+	storage: AccountStorageV3,
+	cache: QuotaCacheData,
+	maxAgeMs: number,
+	now = Date.now(),
+): MenuQuotaProbeTarget[] {
+	const targets: MenuQuotaProbeTarget[] = [];
+	for (const account of storage.accounts) {
+		const probeInput = resolveMenuQuotaProbeInput(account, cache, maxAgeMs, now);
+		if (!probeInput) continue;
+		targets.push({
+			account,
+			accountId: probeInput.accountId,
+			accessToken: probeInput.accessToken,
+		});
+	}
+	return targets;
+}
+
+function countMenuQuotaRefreshTargets(
+	storage: AccountStorageV3,
+	cache: QuotaCacheData,
+	maxAgeMs: number,
+	now = Date.now(),
+): number {
+	let count = 0;
+	for (const account of storage.accounts) {
+		if (resolveMenuQuotaProbeInput(account, cache, maxAgeMs, now)) {
+			count += 1;
+		}
+	}
+	return count;
+}
+
+async function refreshQuotaCacheForMenu(
+	storage: AccountStorageV3,
+	cache: QuotaCacheData,
+	maxAgeMs: number,
+	onProgress?: (current: number, total: number) => void,
+): Promise<QuotaCacheData> {
+	if (storage.accounts.length === 0) {
+		return cache;
+	}
+
+	const now = Date.now();
+	const targets = collectMenuQuotaRefreshTargets(storage, cache, maxAgeMs, now);
+	const total = targets.length;
+	let processed = 0;
+	onProgress?.(processed, total);
+	let changed = false;
+	for (const target of targets) {
+		processed += 1;
+		onProgress?.(processed, total);
+
+		try {
+			const snapshot = await fetchCodexQuotaSnapshot({
+				accountId: target.accountId,
+				accessToken: target.accessToken,
+				model: MENU_QUOTA_REFRESH_MODEL,
+			});
+			changed = updateQuotaCacheForAccount(cache, target.account, snapshot) || changed;
+		} catch {
+			// Keep existing cached values if probing fails.
+		}
+	}
+
+	if (changed) {
+		await saveQuotaCache(cache);
+	}
+
+	return cache;
+}
+
+const ACCESS_TOKEN_FRESH_WINDOW_MS = 5 * 60 * 1000;
+
+function hasUsableAccessToken(
+	account: Pick<AccountMetadataV3, "accessToken" | "expiresAt">,
+	now: number,
+): boolean {
+	if (!account.accessToken) return false;
+	if (typeof account.expiresAt !== "number" || !Number.isFinite(account.expiresAt)) return false;
+	return account.expiresAt - now > ACCESS_TOKEN_FRESH_WINDOW_MS;
+}
+
+function hasLikelyInvalidRefreshToken(refreshToken: string | undefined): boolean {
+	if (!refreshToken) return true;
+	const trimmed = refreshToken.trim();
+	if (trimmed.length < 20) return true;
+	return trimmed.startsWith("token-");
+}
+
+function mapAccountStatus(
+	account: AccountMetadataV3,
+	index: number,
+	activeIndex: number,
+	now: number,
+): ExistingAccountInfo["status"] {
+	if (account.enabled === false) return "disabled";
+	if (typeof account.coolingDownUntil === "number" && account.coolingDownUntil > now) {
+		return "cooldown";
+	}
+	const rateLimit = formatRateLimitEntry(account, now, "codex");
+	if (rateLimit) return "rate-limited";
+	if (index === activeIndex) return "active";
+	return "ok";
+}
+
+function parseLeftPercentFromQuotaSummary(
+	summary: string | undefined,
+	windowLabel: "5h" | "7d",
+): number {
+	if (!summary) return -1;
+	const match = summary.match(new RegExp(`(?:^|\\|)\\s*${windowLabel}\\s+(\\d{1,3})%`, "i"));
+	const value = Number.parseInt(match?.[1] ?? "", 10);
+	if (!Number.isFinite(value)) return -1;
+	return Math.max(0, Math.min(100, value));
+}
+
+function readQuotaLeftPercent(
+	account: ExistingAccountInfo,
+	windowLabel: "5h" | "7d",
+): number {
+	const direct = windowLabel === "5h" ? account.quota5hLeftPercent : account.quota7dLeftPercent;
+	if (typeof direct === "number" && Number.isFinite(direct)) {
+		return Math.max(0, Math.min(100, Math.round(direct)));
+	}
+	return parseLeftPercentFromQuotaSummary(account.quotaSummary, windowLabel);
+}
+
+function accountStatusSortBucket(status: ExistingAccountInfo["status"]): number {
+	switch (status) {
+		case "active":
+		case "ok":
+			return 0;
+		case "unknown":
+			return 1;
+		case "cooldown":
+		case "rate-limited":
+			return 2;
+		case "disabled":
+		case "error":
+		case "flagged":
+			return 3;
+		default:
+			return 1;
+	}
+}
+
+function compareReadyFirstAccounts(
+	left: ExistingAccountInfo,
+	right: ExistingAccountInfo,
+): number {
+	const left5h = readQuotaLeftPercent(left, "5h");
+	const right5h = readQuotaLeftPercent(right, "5h");
+	if (left5h !== right5h) return right5h - left5h;
+
+	const left7d = readQuotaLeftPercent(left, "7d");
+	const right7d = readQuotaLeftPercent(right, "7d");
+	if (left7d !== right7d) return right7d - left7d;
+
+	const bucketDelta = accountStatusSortBucket(left.status) - accountStatusSortBucket(right.status);
+	if (bucketDelta !== 0) return bucketDelta;
+
+	const leftLastUsed = left.lastUsed ?? 0;
+	const rightLastUsed = right.lastUsed ?? 0;
+	if (leftLastUsed !== rightLastUsed) return rightLastUsed - leftLastUsed;
+
+	const leftSource = left.sourceIndex ?? left.index;
+	const rightSource = right.sourceIndex ?? right.index;
+	return leftSource - rightSource;
+}
+
+function applyAccountMenuOrdering(
+	accounts: ExistingAccountInfo[],
+	displaySettings: DashboardDisplaySettings,
+): ExistingAccountInfo[] {
+	const sortEnabled =
+		displaySettings.menuSortEnabled ?? (DEFAULT_DASHBOARD_DISPLAY_SETTINGS.menuSortEnabled ?? true);
+	const sortMode: DashboardAccountSortMode =
+		displaySettings.menuSortMode ?? (DEFAULT_DASHBOARD_DISPLAY_SETTINGS.menuSortMode ?? "ready-first");
+	if (!sortEnabled || sortMode !== "ready-first") {
+		return [...accounts];
+	}
+
+	const sorted = [...accounts].sort(compareReadyFirstAccounts);
+	const pinCurrent = displaySettings.menuSortPinCurrent ??
+		(DEFAULT_DASHBOARD_DISPLAY_SETTINGS.menuSortPinCurrent ?? false);
+	if (pinCurrent) {
+		const currentIndex = sorted.findIndex((account) => account.isCurrentAccount);
+		if (currentIndex > 0) {
+			const current = sorted.splice(currentIndex, 1)[0];
+			const first = sorted[0];
+			if (current && first && compareReadyFirstAccounts(current, first) <= 0) {
+				sorted.unshift(current);
+			} else if (current) {
+				sorted.splice(currentIndex, 0, current);
+			}
+		}
+	}
+	return sorted;
+}
+
+function toExistingAccountInfo(
+	storage: AccountStorageV3,
+	quotaCache: QuotaCacheData | null,
+	displaySettings: DashboardDisplaySettings,
+): ExistingAccountInfo[] {
+	const now = Date.now();
+	const activeIndex = resolveActiveIndex(storage, "codex");
+	const layoutMode = resolveMenuLayoutMode(displaySettings);
+	const baseAccounts = storage.accounts.map((account, index) => {
+		const entry = quotaCache ? getQuotaCacheEntryForAccount(quotaCache, account) : null;
+		return {
+			index,
+			sourceIndex: index,
+			accountId: account.accountId,
+			accountLabel: account.accountLabel,
+			email: account.email,
+			addedAt: account.addedAt,
+			lastUsed: account.lastUsed,
+			status: mapAccountStatus(account, index, activeIndex, now),
+			quotaSummary: (displaySettings.menuShowQuotaSummary ?? true) && entry
+				? formatAccountQuotaSummary(entry)
+				: undefined,
+			quota5hLeftPercent: quotaLeftPercentFromUsed(entry?.primary.usedPercent),
+			quota5hResetAtMs: entry?.primary.resetAtMs,
+			quota7dLeftPercent: quotaLeftPercentFromUsed(entry?.secondary.usedPercent),
+			quota7dResetAtMs: entry?.secondary.resetAtMs,
+			quotaRateLimited: entry?.status === 429,
+			isCurrentAccount: index === activeIndex,
+			enabled: account.enabled !== false,
+			showStatusBadge: displaySettings.menuShowStatusBadge ?? true,
+			showCurrentBadge: displaySettings.menuShowCurrentBadge ?? true,
+			showLastUsed: displaySettings.menuShowLastUsed ?? true,
+			showQuotaCooldown: displaySettings.menuShowQuotaCooldown ?? true,
+			showHintsForUnselectedRows: layoutMode === "expanded-rows",
+			highlightCurrentRow: displaySettings.menuHighlightCurrentRow ?? true,
+			focusStyle: displaySettings.menuFocusStyle ?? "row-invert",
+			statuslineFields: displaySettings.menuStatuslineFields ?? ["last-used", "limits", "status"],
+		};
+	});
+	const orderedAccounts = applyAccountMenuOrdering(baseAccounts, displaySettings);
+	const quickSwitchUsesVisibleRows = displaySettings.menuSortQuickSwitchVisibleRow ?? true;
+	return orderedAccounts.map((account, displayIndex) => ({
+		...account,
+		index: displayIndex,
+		quickSwitchNumber: quickSwitchUsesVisibleRows
+			? displayIndex + 1
+			: (account.sourceIndex ?? displayIndex) + 1,
+	}));
+}
+
+function resolveAccountSelection(tokens: TokenSuccess): TokenSuccessWithAccount {
+	const override = (process.env.CODEX_AUTH_ACCOUNT_ID ?? "").trim();
+	if (override) {
+		return {
+			...tokens,
+			accountIdOverride: override,
+			accountIdSource: "manual",
+		};
+	}
+
+	const candidates = getAccountIdCandidates(tokens.access, tokens.idToken);
+	if (candidates.length === 0) {
+		return tokens;
+	}
+
+	if (candidates.length === 1) {
+		const [candidate] = candidates;
+		if (candidate) {
+			return {
+				...tokens,
+				accountIdOverride: candidate.accountId,
+				accountIdSource: candidate.source,
+				accountLabel: candidate.label,
+			};
+		}
+	}
+
+	const best = selectBestAccountCandidate(candidates);
+	if (!best) {
+		return tokens;
+	}
+
+	return {
+		...tokens,
+		accountIdOverride: best.accountId,
+		accountIdSource: best.source ?? "token",
+		accountLabel: best.label,
+	};
+}
+
+async function promptManualCallback(state: string): Promise<string | null> {
+	if (!input.isTTY || !output.isTTY) {
+		return null;
+	}
+
+	const rl = createInterface({ input, output });
+	try {
+		console.log("");
+		console.log(stylePromptText(UI_COPY.oauth.pastePrompt, "accent"));
+		const answer = await rl.question("◆  ");
+		if (answer.includes("\u001b")) {
+			return null;
+		}
+		const normalized = answer.trim().toLowerCase();
+		if (
+			normalized.length === 0 ||
+			normalized === "q" ||
+			normalized === "quit" ||
+			normalized === "cancel" ||
+			normalized === "back"
+		) {
+			return null;
+		}
+		const parsed = parseAuthorizationInput(answer);
+		if (!parsed.code) return null;
+		if (parsed.state && parsed.state !== state) return null;
+		return parsed.code;
+	} catch (error) {
+		if (isAbortError(error)) {
+			return null;
+		}
+		throw error;
+	} finally {
+		rl.close();
+	}
+}
+
+type OAuthSignInMode = "browser" | "manual" | "cancel";
+
+async function promptOAuthSignInMode(): Promise<OAuthSignInMode> {
+	if (!input.isTTY || !output.isTTY) {
+		return "browser";
+	}
+
+	const ui = getUiRuntimeOptions();
+	const items: MenuItem<OAuthSignInMode>[] = [
+		{ label: UI_COPY.oauth.openBrowser, value: "browser", color: "green" },
+		{ label: UI_COPY.oauth.manualMode, value: "manual", color: "yellow" },
+		{ label: UI_COPY.oauth.back, value: "cancel", color: "red" },
+	];
+
+	const selected = await select<OAuthSignInMode>(items, {
+		message: UI_COPY.oauth.chooseModeTitle,
+		subtitle: UI_COPY.oauth.chooseModeSubtitle,
+		help: UI_COPY.oauth.chooseModeHelp,
+		clearScreen: true,
+		theme: ui.theme,
+		selectedEmphasis: "minimal",
+		allowEscape: false,
+		onInput: (raw) => {
+			const lower = raw.toLowerCase();
+			if (lower === "q") return "cancel";
+			if (lower === "1") return "browser";
+			if (lower === "2") return "manual";
+			return undefined;
+		},
+	});
+
+	return selected ?? "cancel";
+}
+
+interface WaitForReturnOptions {
+	promptText?: string;
+	autoReturnMs?: number;
+	pauseOnAnyKey?: boolean;
+}
+
+async function waitForMenuReturn(options: WaitForReturnOptions = {}): Promise<void> {
+	if (!input.isTTY || !output.isTTY) {
+		return;
+	}
+
+	const promptText = options.promptText ?? UI_COPY.returnFlow.continuePrompt;
+	const autoReturnMs = options.autoReturnMs ?? 0;
+	const pauseOnAnyKey = options.pauseOnAnyKey ?? true;
+
+	try {
+		let chunk: Buffer | string | null;
+		do {
+			chunk = input.read();
+		} while (chunk !== null);
+	} catch {
+		// best effort buffer drain
+	}
+
+	const writeInlineStatus = (message: string): void => {
+		output.write(`\r${ANSI.clearLine}${stylePromptText(message, "muted")}`);
+	};
+
+	const clearInlineStatus = (): void => {
+		output.write(`\r${ANSI.clearLine}`);
+	};
+
+	if (autoReturnMs > 0) {
+		if (!pauseOnAnyKey) {
+			await new Promise<void>((resolve) => setTimeout(resolve, autoReturnMs));
+			return;
+		}
+		const wasRaw = input.isRaw ?? false;
+		const endAt = Date.now() + autoReturnMs;
+		let lastShownSeconds: number | null = null;
+		const renderCountdown = () => {
+			const remainingMs = Math.max(0, endAt - Date.now());
+			const remainingSeconds = Math.max(1, Math.ceil(remainingMs / 1000));
+			if (lastShownSeconds === remainingSeconds) return;
+			lastShownSeconds = remainingSeconds;
+			writeInlineStatus(
+				UI_COPY.returnFlow.autoReturn(remainingSeconds),
+			);
+		};
+		renderCountdown();
+		const pinned = await new Promise<boolean>((resolve) => {
+			let done = false;
+			const interval = setInterval(renderCountdown, 80);
+			let timeout: ReturnType<typeof setTimeout> | null = setTimeout(() => {
+				timeout = null;
+				if (!done) {
+					done = true;
+					cleanup();
+					resolve(false);
+				}
+			}, autoReturnMs);
+			const onData = () => {
+				if (done) return;
+				done = true;
+				cleanup();
+				resolve(true);
+			};
+			const cleanup = () => {
+				clearInterval(interval);
+				if (timeout) {
+					clearTimeout(timeout);
+					timeout = null;
+				}
+				input.removeListener("data", onData);
+				try {
+					input.setRawMode(wasRaw);
+				} catch {
+					// best effort restore
+				}
+			};
+			try {
+				input.setRawMode(true);
+			} catch {
+				// if raw mode fails, keep countdown behavior
+			}
+			input.on("data", onData);
+			input.resume();
+		});
+		clearInlineStatus();
+		if (!pinned) {
+			return;
+		}
+		const paused = stylePromptText(UI_COPY.returnFlow.paused, "muted");
+		writeInlineStatus(paused);
+		await new Promise<void>((resolve) => {
+			const wasRaw = input.isRaw ?? false;
+			const onData = () => {
+				cleanup();
+				resolve();
+			};
+			const cleanup = () => {
+				input.removeListener("data", onData);
+				try {
+					input.setRawMode(wasRaw);
+				} catch {
+					// best effort restore
+				}
+			};
+			try {
+				input.setRawMode(true);
+			} catch {
+				// best effort fallback
+			}
+			input.on("data", onData);
+			input.resume();
+		});
+		clearInlineStatus();
+		return;
+	}
+
+	const rl = createInterface({ input, output });
+	try {
+		const question = promptText.length > 0 ? `${stylePromptText(promptText, "muted")} ` : "";
+		output.write(`\r${ANSI.clearLine}`);
+		await rl.question(question);
+	} catch (error) {
+		if (!isAbortError(error)) {
+			throw error;
+		}
+	} finally {
+		rl.close();
+		clearInlineStatus();
+	}
+}
+
+function stringifyLogArgs(args: unknown[]): string {
+	return args
+		.map((value) => {
+			if (typeof value === "string") return value;
+			try {
+				return JSON.stringify(value);
+			} catch {
+				return String(value);
+			}
+		})
+		.join(" ");
+}
+
+async function runActionPanel(
+	title: string,
+	stage: string,
+	action: () => Promise<void> | void,
+	settings?: DashboardDisplaySettings,
+): Promise<void> {
+	if (!input.isTTY || !output.isTTY) {
+		await action();
+		return;
+	}
+
+	const spinnerFrames = ["-", "\\", "|", "/"];
+	let frame = 0;
+	let running = true;
+	let failed: unknown = null;
+	const captured: string[] = [];
+	const maxVisibleLines = Math.max(8, (output.rows ?? 24) - 8);
+	const previousLog = console.log;
+	const previousWarn = console.warn;
+	const previousError = console.error;
+
+	const capture = (prefix: string, args: unknown[]): void => {
+		const line = stringifyLogArgs(args).trim();
+		if (!line) return;
+		captured.push(prefix ? `${prefix}${line}` : line);
+		if (captured.length > 400) {
+			captured.splice(0, captured.length - 400);
+		}
+	};
+
+	const render = () => {
+		output.write(ANSI.clearScreen + ANSI.moveTo(1, 1));
+		const spinner = running
+			? `${spinnerFrames[frame % spinnerFrames.length] ?? "-"} `
+			: failed
+				? "x "
+				: "+ ";
+		const stageText = running
+			? `${spinner}${stage}`
+			: failed
+				? UI_COPY.returnFlow.failed
+				: UI_COPY.returnFlow.done;
+		previousLog(stylePromptText(title, "accent"));
+		previousLog(stylePromptText(stageText, failed ? "danger" : running ? "accent" : "success"));
+		previousLog("");
+
+		const lines = captured.slice(-maxVisibleLines);
+		for (const line of lines) {
+			previousLog(line);
+		}
+
+		const remainingLines = Math.max(0, maxVisibleLines - lines.length);
+		for (let i = 0; i < remainingLines; i += 1) {
+			previousLog("");
+		}
+		previousLog("");
+		if (running) previousLog(stylePromptText(UI_COPY.returnFlow.working, "muted"));
+		frame += 1;
+	};
+
+	console.log = (...args: unknown[]) => {
+		capture("", args);
+	};
+	console.warn = (...args: unknown[]) => {
+		capture("! ", args);
+	};
+	console.error = (...args: unknown[]) => {
+		capture("x ", args);
+	};
+
+	output.write(ANSI.altScreenOn + ANSI.hide);
+	let timer: ReturnType<typeof setInterval> | null = null;
+	try {
+		render();
+		timer = setInterval(() => {
+			if (!running) return;
+			render();
+		}, 120);
+
+		await action();
+	} catch (error) {
+		failed = error;
+		capture("x ", [error instanceof Error ? error.message : String(error)]);
+	} finally {
+		running = false;
+		if (timer) {
+			clearInterval(timer);
+			timer = null;
+		}
+		render();
+		console.log = previousLog;
+		console.warn = previousWarn;
+		console.error = previousError;
+	}
+
+	if (failed) {
+		await waitForMenuReturn({
+			promptText: UI_COPY.returnFlow.actionFailedPrompt,
+		});
+	} else {
+		await waitForMenuReturn({
+			autoReturnMs: settings?.actionAutoReturnMs ?? 2_000,
+			pauseOnAnyKey: settings?.actionPauseOnKey ?? true,
+		});
+	}
+	output.write(ANSI.altScreenOff + ANSI.show + ANSI.clearScreen + ANSI.moveTo(1, 1));
+	if (failed) {
+		throw failed;
+	}
+}
+
+type DashboardConfigAction =
+	| { type: "toggle"; key: DashboardDisplaySettingKey }
+	| { type: "cycle-sort-mode" }
+	| { type: "cycle-layout-mode" }
+	| { type: "reset" }
+	| { type: "save" }
+	| { type: "cancel" };
+
+type StatuslineConfigAction =
+	| { type: "toggle"; key: DashboardStatuslineField }
+	| { type: "move-up"; key: DashboardStatuslineField }
+	| { type: "move-down"; key: DashboardStatuslineField }
+	| { type: "reset" }
+	| { type: "save" }
+	| { type: "cancel" };
+
+type BehaviorConfigAction =
+	| { type: "set-delay"; delayMs: number }
+	| { type: "toggle-pause" }
+	| { type: "toggle-menu-limit-fetch" }
+	| { type: "toggle-menu-fetch-status" }
+	| { type: "set-menu-quota-ttl"; ttlMs: number }
+	| { type: "reset" }
+	| { type: "save" }
+	| { type: "cancel" };
+
+type ThemeConfigAction =
+	| { type: "set-palette"; palette: DashboardThemePreset }
+	| { type: "set-accent"; accent: DashboardAccentColor }
+	| { type: "reset" }
+	| { type: "save" }
+	| { type: "cancel" };
+
+type BackendCategoryConfigAction =
+	| { type: "toggle"; key: BackendToggleSettingKey }
+	| { type: "bump"; key: BackendNumberSettingKey; direction: -1 | 1 }
+	| { type: "reset-category" }
+	| { type: "back" };
+
+type BackendSettingsHubAction =
+	| { type: "open-category"; key: BackendCategoryKey }
+	| { type: "reset" }
+	| { type: "save" }
+	| { type: "cancel" };
+
+type SettingsHubAction =
+	| { type: "account-list" }
+	| { type: "summary-fields" }
+	| { type: "behavior" }
+	| { type: "theme" }
+	| { type: "backend" }
+	| { type: "back" };
+
+const STATUSLINE_FIELD_OPTIONS: Array<{
+	key: DashboardStatuslineField;
+	label: string;
+	description: string;
+}> = [
+	{
+		key: "last-used",
+		label: "Show Last Used",
+		description: "Example: 'today' or '2d ago'.",
+	},
+	{
+		key: "limits",
+		label: "Show Limits (5h / 7d)",
+		description: "Uses cached limit data from checks.",
+	},
+	{
+		key: "status",
+		label: "Show Status Text",
+		description: "Visible when badges are hidden.",
+	},
+];
+
+function formatMenuSortMode(mode: DashboardAccountSortMode): string {
+	return mode === "ready-first" ? "Ready-First" : "Manual";
+}
+
+function resolveMenuLayoutMode(
+	settings: DashboardDisplaySettings,
+): "compact-details" | "expanded-rows" {
+	if (settings.menuLayoutMode === "expanded-rows") {
+		return "expanded-rows";
+	}
+	if (settings.menuLayoutMode === "compact-details") {
+		return "compact-details";
+	}
+	return settings.menuShowDetailsForUnselectedRows === true ? "expanded-rows" : "compact-details";
+}
+
+function formatMenuLayoutMode(mode: "compact-details" | "expanded-rows"): string {
+	return mode === "expanded-rows" ? "Expanded Rows" : "Compact + Details Pane";
+}
+
+function formatMenuQuotaTtl(ttlMs: number): string {
+	if (ttlMs >= 60_000 && ttlMs % 60_000 === 0) {
+		return `${Math.round(ttlMs / 60_000)}m`;
+	}
+	if (ttlMs >= 1_000 && ttlMs % 1_000 === 0) {
+		return `${Math.round(ttlMs / 1_000)}s`;
+	}
+	return `${ttlMs}ms`;
+}
+
+async function promptDashboardDisplaySettings(
+	initial: DashboardDisplaySettings,
+): Promise<DashboardDisplaySettings | null> {
+	if (!input.isTTY || !output.isTTY) {
+		return null;
+	}
+
+	const ui = getUiRuntimeOptions();
+	let draft = cloneDashboardSettings(initial);
+	let focusKey: DashboardDisplaySettingKey | "menuSortMode" | "menuLayoutMode" =
+		DASHBOARD_DISPLAY_OPTIONS[0]?.key ?? "menuShowStatusBadge";
+	while (true) {
+		const preview = buildAccountListPreview(draft, ui, focusKey);
+		const optionItems: MenuItem<DashboardConfigAction>[] = DASHBOARD_DISPLAY_OPTIONS.map((option, index) => {
+			const enabled = draft[option.key] ?? true;
+			const label = `${formatDashboardSettingState(enabled)} ${index + 1}. ${option.label}`;
+			const color: MenuItem<DashboardConfigAction>["color"] = enabled ? "green" : "yellow";
+			return {
+				label,
+				hint: option.description,
+				value: { type: "toggle", key: option.key } as DashboardConfigAction,
+				color,
+			};
+		});
+		const sortMode = draft.menuSortMode ?? (DEFAULT_DASHBOARD_DISPLAY_SETTINGS.menuSortMode ?? "ready-first");
+		const sortModeItem: MenuItem<DashboardConfigAction> = {
+			label: `Sort mode: ${formatMenuSortMode(sortMode)}`,
+			hint: "Applies when smart sort is enabled.",
+			value: { type: "cycle-sort-mode" },
+			color: sortMode === "ready-first" ? "green" : "yellow",
+		};
+		const layoutMode = resolveMenuLayoutMode(draft);
+		const layoutModeItem: MenuItem<DashboardConfigAction> = {
+			label: `Layout: ${formatMenuLayoutMode(layoutMode)}`,
+			hint: "Compact shows one-line rows with a selected details pane.",
+			value: { type: "cycle-layout-mode" },
+			color: layoutMode === "compact-details" ? "green" : "yellow",
+		};
+		const items: MenuItem<DashboardConfigAction>[] = [
+			{ label: UI_COPY.settings.previewHeading, value: { type: "cancel" }, kind: "heading" },
+			{
+				label: preview.label,
+				hint: preview.hint,
+				value: { type: "cancel" },
+				color: "green",
+				disabled: true,
+				hideUnavailableSuffix: true,
+			},
+			{ label: "", value: { type: "cancel" }, separator: true },
+			{ label: UI_COPY.settings.displayHeading, value: { type: "cancel" }, kind: "heading" },
+			...optionItems,
+			sortModeItem,
+			layoutModeItem,
+			{ label: "", value: { type: "cancel" }, separator: true },
+			{ label: UI_COPY.settings.resetDefault, value: { type: "reset" }, color: "yellow" },
+			{ label: UI_COPY.settings.saveAndBack, value: { type: "save" }, color: "green" },
+			{ label: UI_COPY.settings.backNoSave, value: { type: "cancel" }, color: "red" },
+		];
+		const initialCursor = items.findIndex((item) =>
+			(item.value.type === "toggle" && item.value.key === focusKey) ||
+			(item.value.type === "cycle-sort-mode" && focusKey === "menuSortMode") ||
+			(item.value.type === "cycle-layout-mode" && focusKey === "menuLayoutMode")
+		);
+
+		const updateFocusedPreview = (cursor: number) => {
+			const focusedItem = items[cursor];
+			const focusedKey =
+				focusedItem?.value.type === "toggle"
+					? focusedItem.value.key
+					: focusedItem?.value.type === "cycle-sort-mode"
+						? "menuSortMode"
+						: focusedItem?.value.type === "cycle-layout-mode"
+							? "menuLayoutMode"
+						: focusKey;
+			const nextPreview = buildAccountListPreview(draft, ui, focusedKey);
+			const previewItem = items[1];
+			if (!previewItem) return;
+			previewItem.label = nextPreview.label;
+			previewItem.hint = nextPreview.hint;
+		};
+
+		const result = await select<DashboardConfigAction>(
+			items,
+			{
+				message: UI_COPY.settings.accountListTitle,
+				subtitle: UI_COPY.settings.accountListSubtitle,
+				help: UI_COPY.settings.accountListHelp,
+				clearScreen: true,
+				theme: ui.theme,
+				selectedEmphasis: "minimal",
+				initialCursor: initialCursor >= 0 ? initialCursor : undefined,
+				onCursorChange: ({ cursor }) => {
+					const focusedItem = items[cursor];
+					if (focusedItem?.value.type === "toggle") {
+						focusKey = focusedItem.value.key;
+					} else if (focusedItem?.value.type === "cycle-sort-mode") {
+						focusKey = "menuSortMode";
+					} else if (focusedItem?.value.type === "cycle-layout-mode") {
+						focusKey = "menuLayoutMode";
+					}
+					updateFocusedPreview(cursor);
+				},
+			onInput: (raw) => {
+				const lower = raw.toLowerCase();
+				if (lower === "q") return { type: "save" };
+				if (lower === "s") return { type: "save" };
+				if (lower === "r") return { type: "reset" };
+				if (lower === "m") return { type: "cycle-sort-mode" };
+				if (lower === "l") return { type: "cycle-layout-mode" };
+					const parsed = Number.parseInt(raw, 10);
+					if (Number.isFinite(parsed) && parsed >= 1 && parsed <= DASHBOARD_DISPLAY_OPTIONS.length) {
+						const target = DASHBOARD_DISPLAY_OPTIONS[parsed - 1];
+						if (target) {
+							return { type: "toggle", key: target.key };
+						}
+					}
+					if (parsed === DASHBOARD_DISPLAY_OPTIONS.length + 1) {
+						return { type: "cycle-sort-mode" };
+					}
+					if (parsed === DASHBOARD_DISPLAY_OPTIONS.length + 2) {
+						return { type: "cycle-layout-mode" };
+					}
+					return undefined;
+				},
+			},
+		);
+
+		if (!result || result.type === "cancel") {
+			return null;
+		}
+		if (result.type === "save") {
+			return draft;
+		}
+		if (result.type === "reset") {
+			draft = cloneDashboardSettings(DEFAULT_DASHBOARD_DISPLAY_SETTINGS);
+			focusKey = DASHBOARD_DISPLAY_OPTIONS[0]?.key ?? focusKey;
+			await saveDashboardDisplaySettings(draft);
+			continue;
+		}
+		if (result.type === "cycle-sort-mode") {
+			const currentMode = draft.menuSortMode ?? (DEFAULT_DASHBOARD_DISPLAY_SETTINGS.menuSortMode ?? "ready-first");
+			const nextMode: DashboardAccountSortMode = currentMode === "ready-first"
+				? "manual"
+				: "ready-first";
+			draft = {
+				...draft,
+				menuSortMode: nextMode,
+				menuSortEnabled: nextMode === "ready-first"
+					? true
+					: (draft.menuSortEnabled ?? (DEFAULT_DASHBOARD_DISPLAY_SETTINGS.menuSortEnabled ?? true)),
+			};
+			focusKey = "menuSortMode";
+			await saveDashboardDisplaySettings(draft);
+			continue;
+		}
+		if (result.type === "cycle-layout-mode") {
+			const currentLayout = resolveMenuLayoutMode(draft);
+			const nextLayout = currentLayout === "compact-details" ? "expanded-rows" : "compact-details";
+			draft = {
+				...draft,
+				menuLayoutMode: nextLayout,
+				menuShowDetailsForUnselectedRows: nextLayout === "expanded-rows",
+			};
+			focusKey = "menuLayoutMode";
+			await saveDashboardDisplaySettings(draft);
+			continue;
+		}
+		focusKey = result.key;
+		draft = {
+			...draft,
+			[result.key]: !draft[result.key],
+		};
+		await saveDashboardDisplaySettings(draft);
+	}
+}
+
+async function configureDashboardDisplaySettings(
+	currentSettings?: DashboardDisplaySettings,
+): Promise<DashboardDisplaySettings> {
+	const current = currentSettings ?? await loadDashboardDisplaySettings();
+	if (!input.isTTY || !output.isTTY) {
+		console.log("Settings require interactive mode.");
+		console.log(`Settings file: ${getDashboardSettingsPath()}`);
+		return current;
+	}
+
+	const selected = await promptDashboardDisplaySettings(current);
+	if (!selected) return current;
+	if (dashboardSettingsEqual(current, selected)) return current;
+
+	await saveDashboardDisplaySettings(selected);
+	applyUiThemeFromDashboardSettings(selected);
+	return selected;
+}
+
+function reorderField(
+	fields: DashboardStatuslineField[],
+	key: DashboardStatuslineField,
+	direction: -1 | 1,
+): DashboardStatuslineField[] {
+	const index = fields.indexOf(key);
+	if (index < 0) return fields;
+	const target = index + direction;
+	if (target < 0 || target >= fields.length) return fields;
+	const next = [...fields];
+	const current = next[index];
+	const swap = next[target];
+	if (!current || !swap) return fields;
+	next[index] = swap;
+	next[target] = current;
+	return next;
+}
+
+async function promptStatuslineSettings(
+	initial: DashboardDisplaySettings,
+): Promise<DashboardDisplaySettings | null> {
+	if (!input.isTTY || !output.isTTY) {
+		return null;
+	}
+
+	const ui = getUiRuntimeOptions();
+	let draft = cloneDashboardSettings(initial);
+	let focusKey: DashboardStatuslineField = draft.menuStatuslineFields?.[0] ?? "last-used";
+	while (true) {
+		const preview = buildAccountListPreview(draft, ui, focusKey);
+		const selectedSet = new Set(normalizeStatuslineFields(draft.menuStatuslineFields));
+		const ordered = normalizeStatuslineFields(draft.menuStatuslineFields);
+		const orderMap = new Map<DashboardStatuslineField, number>();
+		for (let index = 0; index < ordered.length; index += 1) {
+			const key = ordered[index];
+			if (key) orderMap.set(key, index + 1);
+		}
+
+		const optionItems: MenuItem<StatuslineConfigAction>[] = STATUSLINE_FIELD_OPTIONS.map((option, index) => {
+			const enabled = selectedSet.has(option.key);
+			const rank = orderMap.get(option.key);
+			const label = `${formatDashboardSettingState(enabled)} ${index + 1}. ${option.label}${rank ? ` (order ${rank})` : ""}`;
+			return {
+				label,
+				hint: option.description,
+				value: { type: "toggle", key: option.key },
+				color: enabled ? "green" : "yellow",
+			};
+		});
+
+		const items: MenuItem<StatuslineConfigAction>[] = [
+			{ label: UI_COPY.settings.previewHeading, value: { type: "cancel" }, kind: "heading" },
+			{
+				label: preview.label,
+				hint: preview.hint,
+				value: { type: "cancel" },
+				color: "green",
+				disabled: true,
+				hideUnavailableSuffix: true,
+			},
+			{ label: "", value: { type: "cancel" }, separator: true },
+			{ label: UI_COPY.settings.displayHeading, value: { type: "cancel" }, kind: "heading" },
+			...optionItems,
+			{ label: "", value: { type: "cancel" }, separator: true },
+			{ label: UI_COPY.settings.moveUp, value: { type: "move-up", key: focusKey }, color: "green" },
+			{ label: UI_COPY.settings.moveDown, value: { type: "move-down", key: focusKey }, color: "green" },
+			{ label: "", value: { type: "cancel" }, separator: true },
+			{ label: UI_COPY.settings.resetDefault, value: { type: "reset" }, color: "yellow" },
+			{ label: UI_COPY.settings.saveAndBack, value: { type: "save" }, color: "green" },
+			{ label: UI_COPY.settings.backNoSave, value: { type: "cancel" }, color: "red" },
+		];
+
+		const initialCursor = items.findIndex(
+			(item) => item.value.type === "toggle" && item.value.key === focusKey,
+		);
+
+		const updateFocusedPreview = (cursor: number) => {
+			const focusedItem = items[cursor];
+			const focusedKey =
+				focusedItem?.value.type === "toggle" ? focusedItem.value.key : focusKey;
+			const nextPreview = buildAccountListPreview(draft, ui, focusedKey);
+			const previewItem = items[1];
+			if (!previewItem) return;
+			previewItem.label = nextPreview.label;
+			previewItem.hint = nextPreview.hint;
+		};
+
+		const result = await select<StatuslineConfigAction>(items, {
+			message: UI_COPY.settings.summaryTitle,
+			subtitle: UI_COPY.settings.summarySubtitle,
+			help: UI_COPY.settings.summaryHelp,
+			clearScreen: true,
+			theme: ui.theme,
+			selectedEmphasis: "minimal",
+			initialCursor: initialCursor >= 0 ? initialCursor : undefined,
+			onCursorChange: ({ cursor }) => {
+				const focusedItem = items[cursor];
+				if (focusedItem?.value.type === "toggle") {
+					focusKey = focusedItem.value.key;
+				}
+				updateFocusedPreview(cursor);
+			},
+			onInput: (raw) => {
+				const lower = raw.toLowerCase();
+				if (lower === "q") return { type: "save" };
+				if (lower === "s") return { type: "save" };
+				if (lower === "r") return { type: "reset" };
+				if (lower === "[") return { type: "move-up", key: focusKey };
+				if (lower === "]") return { type: "move-down", key: focusKey };
+				const parsed = Number.parseInt(raw, 10);
+				if (Number.isFinite(parsed) && parsed >= 1 && parsed <= STATUSLINE_FIELD_OPTIONS.length) {
+					const target = STATUSLINE_FIELD_OPTIONS[parsed - 1];
+					if (target) {
+						return { type: "toggle", key: target.key };
+					}
+				}
+				return undefined;
+			},
+		});
+
+		if (!result || result.type === "cancel") {
+			return null;
+		}
+		if (result.type === "save") {
+			return draft;
+		}
+		if (result.type === "reset") {
+			draft = cloneDashboardSettings(DEFAULT_DASHBOARD_DISPLAY_SETTINGS);
+			focusKey = draft.menuStatuslineFields?.[0] ?? "last-used";
+			await saveDashboardDisplaySettings(draft);
+			continue;
+		}
+		if (result.type === "move-up") {
+			draft = {
+				...draft,
+				menuStatuslineFields: reorderField(
+					normalizeStatuslineFields(draft.menuStatuslineFields),
+					result.key,
+					-1,
+				),
+			};
+			focusKey = result.key;
+			await saveDashboardDisplaySettings(draft);
+			continue;
+		}
+		if (result.type === "move-down") {
+			draft = {
+				...draft,
+				menuStatuslineFields: reorderField(
+					normalizeStatuslineFields(draft.menuStatuslineFields),
+					result.key,
+					1,
+				),
+			};
+			focusKey = result.key;
+			await saveDashboardDisplaySettings(draft);
+			continue;
+		}
+
+		focusKey = result.key;
+		const fields = normalizeStatuslineFields(draft.menuStatuslineFields);
+		const isEnabled = fields.includes(result.key);
+		if (isEnabled) {
+			const next = fields.filter((field) => field !== result.key);
+			draft = {
+				...draft,
+				menuStatuslineFields: next.length > 0 ? next : [result.key],
+			};
+		} else {
+			draft = {
+				...draft,
+				menuStatuslineFields: [...fields, result.key],
+			};
+		}
+		await saveDashboardDisplaySettings(draft);
+	}
+}
+
+async function configureStatuslineSettings(
+	currentSettings?: DashboardDisplaySettings,
+): Promise<DashboardDisplaySettings> {
+	const current = currentSettings ?? await loadDashboardDisplaySettings();
+	if (!input.isTTY || !output.isTTY) {
+		console.log("Settings require interactive mode.");
+		console.log(`Settings file: ${getDashboardSettingsPath()}`);
+		return current;
+	}
+
+	const selected = await promptStatuslineSettings(current);
+	if (!selected) return current;
+	if (dashboardSettingsEqual(current, selected)) return current;
+
+	await saveDashboardDisplaySettings(selected);
+	applyUiThemeFromDashboardSettings(selected);
+	return selected;
+}
+
+function formatDelayLabel(delayMs: number): string {
+	return delayMs <= 0 ? "Instant return" : `${Math.round(delayMs / 1000)}s auto-return`;
+}
+
+async function promptBehaviorSettings(
+	initial: DashboardDisplaySettings,
+): Promise<DashboardDisplaySettings | null> {
+	if (!input.isTTY || !output.isTTY) return null;
+	const ui = getUiRuntimeOptions();
+	let draft = cloneDashboardSettings(initial);
+	let focus: BehaviorConfigAction = {
+		type: "set-delay",
+		delayMs: draft.actionAutoReturnMs ?? 2_000,
+	};
+
+	while (true) {
+		const currentDelay = draft.actionAutoReturnMs ?? 2_000;
+		const pauseOnKey = draft.actionPauseOnKey ?? true;
+		const autoFetchLimits = draft.menuAutoFetchLimits ?? true;
+		const fetchStatusVisible = draft.menuShowFetchStatus ?? true;
+		const menuQuotaTtlMs = draft.menuQuotaTtlMs ?? 5 * 60_000;
+		const delayItems: MenuItem<BehaviorConfigAction>[] = AUTO_RETURN_OPTIONS_MS.map((delayMs) => {
+			const color: MenuItem<BehaviorConfigAction>["color"] = currentDelay === delayMs ? "green" : "yellow";
+			return {
+				label: `${currentDelay === delayMs ? "[x]" : "[ ]"} ${formatDelayLabel(delayMs)}`,
+				hint:
+					delayMs === 1_000
+						? "Fastest loop for frequent actions."
+						: delayMs === 2_000
+							? "Balanced default for most users."
+							: "More time to read action output.",
+				value: { type: "set-delay", delayMs },
+				color,
+			};
+		});
+		const pauseColor: MenuItem<BehaviorConfigAction>["color"] = pauseOnKey ? "green" : "yellow";
+		const items: MenuItem<BehaviorConfigAction>[] = [
+			{ label: UI_COPY.settings.actionTiming, value: { type: "cancel" }, kind: "heading" },
+			...delayItems,
+			{ label: "", value: { type: "cancel" }, separator: true },
+			{
+				label: `${pauseOnKey ? "[x]" : "[ ]"} Pause on key press`,
+				hint: "Press any key to stop auto-return.",
+				value: { type: "toggle-pause" },
+				color: pauseColor,
+			},
+			{
+				label: `${autoFetchLimits ? "[x]" : "[ ]"} Auto-fetch limits on menu open (5m cache)`,
+				hint: "Refreshes account limits automatically when opening the menu.",
+				value: { type: "toggle-menu-limit-fetch" },
+				color: autoFetchLimits ? "green" : "yellow",
+			},
+			{
+				label: `${fetchStatusVisible ? "[x]" : "[ ]"} Show limit refresh status`,
+				hint: "Shows background fetch progress like [2/7] in menu subtitle.",
+				value: { type: "toggle-menu-fetch-status" },
+				color: fetchStatusVisible ? "green" : "yellow",
+			},
+			{
+				label: `Limit cache TTL: ${formatMenuQuotaTtl(menuQuotaTtlMs)}`,
+				hint: "How fresh cached quota data must be before refresh runs.",
+				value: { type: "set-menu-quota-ttl", ttlMs: menuQuotaTtlMs },
+				color: "yellow",
+			},
+			{ label: "", value: { type: "cancel" }, separator: true },
+			{ label: UI_COPY.settings.resetDefault, value: { type: "reset" }, color: "yellow" },
+			{ label: UI_COPY.settings.saveAndBack, value: { type: "save" }, color: "green" },
+			{ label: UI_COPY.settings.backNoSave, value: { type: "cancel" }, color: "red" },
+		];
+		const initialCursor = items.findIndex((item) => {
+			const value = item.value;
+			if (value.type !== focus.type) return false;
+			if (value.type === "set-delay" && focus.type === "set-delay") {
+				return value.delayMs === focus.delayMs;
+			}
+			return true;
+		});
+
+		const result = await select<BehaviorConfigAction>(items, {
+			message: UI_COPY.settings.behaviorTitle,
+			subtitle: UI_COPY.settings.behaviorSubtitle,
+			help: UI_COPY.settings.behaviorHelp,
+			clearScreen: true,
+			theme: ui.theme,
+			selectedEmphasis: "minimal",
+			initialCursor: initialCursor >= 0 ? initialCursor : undefined,
+			onCursorChange: ({ cursor }) => {
+				const item = items[cursor];
+				if (item && !item.separator && item.kind !== "heading") {
+					focus = item.value;
+				}
+			},
+			onInput: (raw) => {
+				const lower = raw.toLowerCase();
+				if (lower === "q") return { type: "save" };
+				if (lower === "s") return { type: "save" };
+				if (lower === "r") return { type: "reset" };
+				if (lower === "p") return { type: "toggle-pause" };
+				if (lower === "l") return { type: "toggle-menu-limit-fetch" };
+				if (lower === "f") return { type: "toggle-menu-fetch-status" };
+				if (lower === "t") return { type: "set-menu-quota-ttl", ttlMs: menuQuotaTtlMs };
+				const parsed = Number.parseInt(raw, 10);
+				if (Number.isFinite(parsed) && parsed >= 1 && parsed <= AUTO_RETURN_OPTIONS_MS.length) {
+					const delayMs = AUTO_RETURN_OPTIONS_MS[parsed - 1];
+					if (typeof delayMs === "number") return { type: "set-delay", delayMs };
+				}
+				return undefined;
+			},
+		});
+
+		if (!result || result.type === "cancel") return null;
+		if (result.type === "save") return draft;
+		if (result.type === "reset") {
+			draft = cloneDashboardSettings(DEFAULT_DASHBOARD_DISPLAY_SETTINGS);
+			focus = { type: "set-delay", delayMs: draft.actionAutoReturnMs ?? 2_000 };
+			await saveDashboardDisplaySettings(draft);
+			continue;
+		}
+		if (result.type === "toggle-pause") {
+			draft = {
+				...draft,
+				actionPauseOnKey: !(draft.actionPauseOnKey ?? true),
+			};
+			focus = result;
+			await saveDashboardDisplaySettings(draft);
+			continue;
+		}
+		if (result.type === "toggle-menu-limit-fetch") {
+			draft = {
+				...draft,
+				menuAutoFetchLimits: !(draft.menuAutoFetchLimits ?? true),
+			};
+			focus = result;
+			await saveDashboardDisplaySettings(draft);
+			continue;
+		}
+		if (result.type === "toggle-menu-fetch-status") {
+			draft = {
+				...draft,
+				menuShowFetchStatus: !(draft.menuShowFetchStatus ?? true),
+			};
+			focus = result;
+			await saveDashboardDisplaySettings(draft);
+			continue;
+		}
+		if (result.type === "set-menu-quota-ttl") {
+			const currentIndex = MENU_QUOTA_TTL_OPTIONS_MS.findIndex((value) => value === menuQuotaTtlMs);
+			const nextIndex = currentIndex < 0
+				? 0
+				: (currentIndex + 1) % MENU_QUOTA_TTL_OPTIONS_MS.length;
+			const nextTtl = MENU_QUOTA_TTL_OPTIONS_MS[nextIndex] ?? MENU_QUOTA_TTL_OPTIONS_MS[0] ?? menuQuotaTtlMs;
+			draft = {
+				...draft,
+				menuQuotaTtlMs: nextTtl,
+			};
+			focus = { type: "set-menu-quota-ttl", ttlMs: nextTtl };
+			await saveDashboardDisplaySettings(draft);
+			continue;
+		}
+		draft = {
+			...draft,
+			actionAutoReturnMs: result.delayMs,
+		};
+		focus = result;
+		await saveDashboardDisplaySettings(draft);
+	}
+}
+
+async function promptThemeSettings(
+	initial: DashboardDisplaySettings,
+): Promise<DashboardDisplaySettings | null> {
+	if (!input.isTTY || !output.isTTY) return null;
+	const ui = getUiRuntimeOptions();
+	let draft = cloneDashboardSettings(initial);
+	let focus: ThemeConfigAction = {
+		type: "set-palette",
+		palette: draft.uiThemePreset ?? "green",
+	};
+	while (true) {
+		const palette = draft.uiThemePreset ?? "green";
+		const accent = draft.uiAccentColor ?? "green";
+		const paletteItems: MenuItem<ThemeConfigAction>[] = THEME_PRESET_OPTIONS.map((candidate, index) => {
+			const color: MenuItem<ThemeConfigAction>["color"] = palette === candidate ? "green" : "yellow";
+			return {
+				label: `${palette === candidate ? "[x]" : "[ ]"} ${index + 1}. ${candidate === "green" ? "Green base" : "Blue base"}`,
+				hint: candidate === "green" ? "High-contrast default." : "Codex-style blue look.",
+				value: { type: "set-palette", palette: candidate },
+				color,
+			};
+		});
+		const accentItems: MenuItem<ThemeConfigAction>[] = ACCENT_COLOR_OPTIONS.map((candidate) => {
+			const color: MenuItem<ThemeConfigAction>["color"] = accent === candidate ? "green" : "yellow";
+			return {
+				label: `${accent === candidate ? "[x]" : "[ ]"} ${candidate}`,
+				value: { type: "set-accent", accent: candidate },
+				color,
+			};
+		});
+		const items: MenuItem<ThemeConfigAction>[] = [
+			{ label: UI_COPY.settings.baseTheme, value: { type: "cancel" }, kind: "heading" },
+			...paletteItems,
+			{ label: "", value: { type: "cancel" }, separator: true },
+			{ label: UI_COPY.settings.accentColor, value: { type: "cancel" }, kind: "heading" },
+			...accentItems,
+			{ label: "", value: { type: "cancel" }, separator: true },
+			{ label: UI_COPY.settings.resetDefault, value: { type: "reset" }, color: "yellow" },
+			{ label: UI_COPY.settings.saveAndBack, value: { type: "save" }, color: "green" },
+			{ label: UI_COPY.settings.backNoSave, value: { type: "cancel" }, color: "red" },
+		];
+		const initialCursor = items.findIndex((item) => {
+			const value = item.value;
+			if (value.type !== focus.type) return false;
+			if (value.type === "set-palette" && focus.type === "set-palette") {
+				return value.palette === focus.palette;
+			}
+			if (value.type === "set-accent" && focus.type === "set-accent") {
+				return value.accent === focus.accent;
+			}
+			return true;
+		});
+		const result = await select<ThemeConfigAction>(items, {
+			message: UI_COPY.settings.themeTitle,
+			subtitle: UI_COPY.settings.themeSubtitle,
+			help: UI_COPY.settings.themeHelp,
+			clearScreen: true,
+			theme: ui.theme,
+			selectedEmphasis: "minimal",
+			initialCursor: initialCursor >= 0 ? initialCursor : undefined,
+			onCursorChange: ({ cursor }) => {
+				const item = items[cursor];
+				if (item && !item.separator && item.kind !== "heading") {
+					focus = item.value;
+				}
+			},
+			onInput: (raw) => {
+				const lower = raw.toLowerCase();
+				if (lower === "q") return { type: "save" };
+				if (lower === "s") return { type: "save" };
+				if (lower === "r") return { type: "reset" };
+				if (raw === "1") return { type: "set-palette", palette: "green" };
+				if (raw === "2") return { type: "set-palette", palette: "blue" };
+				return undefined;
+			},
+		});
+		if (!result || result.type === "cancel") return null;
+		if (result.type === "save") return draft;
+		if (result.type === "reset") {
+			draft = cloneDashboardSettings(DEFAULT_DASHBOARD_DISPLAY_SETTINGS);
+			focus = { type: "set-palette", palette: draft.uiThemePreset ?? "green" };
+			await saveDashboardDisplaySettings(draft);
+			continue;
+		}
+		if (result.type === "set-palette") {
+			draft = { ...draft, uiThemePreset: result.palette };
+			focus = result;
+			applyUiThemeFromDashboardSettings(draft);
+			await saveDashboardDisplaySettings(draft);
+			continue;
+		}
+		draft = { ...draft, uiAccentColor: result.accent };
+		focus = result;
+		applyUiThemeFromDashboardSettings(draft);
+		await saveDashboardDisplaySettings(draft);
+	}
+}
+
+function resolveFocusedBackendNumberKey(
+	focus: BackendSettingFocusKey,
+	numberOptions: BackendNumberSettingOption[] = BACKEND_NUMBER_OPTIONS,
+): BackendNumberSettingKey {
+	const numberKeys = new Set<BackendNumberSettingKey>(numberOptions.map((option) => option.key));
+	if (focus && numberKeys.has(focus as BackendNumberSettingKey)) {
+		return focus as BackendNumberSettingKey;
+	}
+	return numberOptions[0]?.key ?? "fetchTimeoutMs";
+}
+
+function getBackendCategory(key: BackendCategoryKey): BackendCategoryOption | null {
+	return BACKEND_CATEGORY_OPTIONS.find((category) => category.key === key) ?? null;
+}
+
+function getBackendCategoryInitialFocus(category: BackendCategoryOption): BackendSettingFocusKey {
+	const firstToggle = category.toggleKeys[0];
+	if (firstToggle) return firstToggle;
+	return category.numberKeys[0] ?? null;
+}
+
+function applyBackendCategoryDefaults(
+	draft: PluginConfig,
+	category: BackendCategoryOption,
+): PluginConfig {
+	const next = { ...draft };
+	for (const key of category.toggleKeys) {
+		next[key] = BACKEND_DEFAULTS[key] ?? false;
+	}
+	for (const key of category.numberKeys) {
+		const option = BACKEND_NUMBER_OPTION_BY_KEY.get(key);
+		const fallback = option?.min ?? 0;
+		next[key] = BACKEND_DEFAULTS[key] ?? fallback;
+	}
+	return next;
+}
+
+async function promptBackendCategorySettings(
+	initial: PluginConfig,
+	category: BackendCategoryOption,
+	initialFocus: BackendSettingFocusKey,
+): Promise<{ draft: PluginConfig; focusKey: BackendSettingFocusKey }> {
+	const ui = getUiRuntimeOptions();
+	let draft = cloneBackendPluginConfig(initial);
+	let focusKey: BackendSettingFocusKey = initialFocus;
+	if (
+		!focusKey ||
+		(!category.toggleKeys.includes(focusKey as BackendToggleSettingKey) &&
+			!category.numberKeys.includes(focusKey as BackendNumberSettingKey))
+	) {
+		focusKey = getBackendCategoryInitialFocus(category);
+	}
+
+	const toggleOptions = category.toggleKeys
+		.map((key) => BACKEND_TOGGLE_OPTION_BY_KEY.get(key))
+		.filter((option): option is BackendToggleSettingOption => !!option);
+	const numberOptions = category.numberKeys
+		.map((key) => BACKEND_NUMBER_OPTION_BY_KEY.get(key))
+		.filter((option): option is BackendNumberSettingOption => !!option);
+
+	while (true) {
+		const preview = buildBackendSettingsPreview(draft, ui, focusKey);
+		const toggleItems: MenuItem<BackendCategoryConfigAction>[] = toggleOptions.map((option, index) => {
+			const enabled = draft[option.key] ?? BACKEND_DEFAULTS[option.key] ?? false;
+			return {
+				label: `${formatDashboardSettingState(enabled)} ${index + 1}. ${option.label}`,
+				hint: option.description,
+				value: { type: "toggle", key: option.key },
+				color: enabled ? "green" : "yellow",
+			};
+		});
+		const numberItems: MenuItem<BackendCategoryConfigAction>[] = numberOptions.map((option) => {
+			const rawValue = draft[option.key] ?? BACKEND_DEFAULTS[option.key] ?? option.min;
+			const numericValue = typeof rawValue === "number" && Number.isFinite(rawValue)
+				? rawValue
+				: option.min;
+			const clampedValue = clampBackendNumber(option, numericValue);
+			const valueLabel = formatBackendNumberValue(option, clampedValue);
+			return {
+				label: `${option.label}: ${valueLabel}`,
+				hint: `${option.description} Step ${formatBackendNumberValue(option, option.step)}.`,
+				value: { type: "bump", key: option.key, direction: 1 },
+				color: "yellow",
+			};
+		});
+
+		const focusedNumberKey = resolveFocusedBackendNumberKey(focusKey, numberOptions);
+		const items: MenuItem<BackendCategoryConfigAction>[] = [
+			{ label: UI_COPY.settings.previewHeading, value: { type: "back" }, kind: "heading" },
+			{
+				label: preview.label,
+				hint: preview.hint,
+				value: { type: "back" },
+				disabled: true,
+				color: "green",
+				hideUnavailableSuffix: true,
+			},
+			{ label: "", value: { type: "back" }, separator: true },
+			{ label: UI_COPY.settings.backendToggleHeading, value: { type: "back" }, kind: "heading" },
+			...toggleItems,
+			{ label: "", value: { type: "back" }, separator: true },
+			{ label: UI_COPY.settings.backendNumberHeading, value: { type: "back" }, kind: "heading" },
+			...numberItems,
+		];
+
+		if (numberOptions.length > 0) {
+			items.push({ label: "", value: { type: "back" }, separator: true });
+			items.push({
+				label: UI_COPY.settings.backendDecrease,
+				value: { type: "bump", key: focusedNumberKey, direction: -1 },
+				color: "yellow",
+			});
+			items.push({
+				label: UI_COPY.settings.backendIncrease,
+				value: { type: "bump", key: focusedNumberKey, direction: 1 },
+				color: "green",
+			});
+		}
+
+		items.push({ label: "", value: { type: "back" }, separator: true });
+		items.push({ label: UI_COPY.settings.backendResetCategory, value: { type: "reset-category" }, color: "yellow" });
+		items.push({ label: UI_COPY.settings.backendBackToCategories, value: { type: "back" }, color: "red" });
+
+		const initialCursor = items.findIndex((item) => {
+			if (item.separator || item.disabled || item.kind === "heading") return false;
+			if (item.value.type === "toggle" && focusKey === item.value.key) return true;
+			if (item.value.type === "bump" && focusKey === item.value.key) return true;
+			return false;
+		});
+
+		const result = await select<BackendCategoryConfigAction>(items, {
+			message: `${UI_COPY.settings.backendCategoryTitle}: ${category.label}`,
+			subtitle: category.description,
+			help: UI_COPY.settings.backendCategoryHelp,
+			clearScreen: true,
+			theme: ui.theme,
+			selectedEmphasis: "minimal",
+			initialCursor: initialCursor >= 0 ? initialCursor : undefined,
+			onCursorChange: ({ cursor }) => {
+				const focusedItem = items[cursor];
+				if (focusedItem?.value.type === "toggle" || focusedItem?.value.type === "bump") {
+					focusKey = focusedItem.value.key;
+				}
+			},
+			onInput: (raw) => {
+				const lower = raw.toLowerCase();
+				if (lower === "q") return { type: "back" };
+				if (lower === "r") return { type: "reset-category" };
+				if (numberOptions.length > 0 && (lower === "+" || lower === "=" || lower === "]" || lower === "d")) {
+					return { type: "bump", key: resolveFocusedBackendNumberKey(focusKey, numberOptions), direction: 1 };
+				}
+				if (numberOptions.length > 0 && (lower === "-" || lower === "[" || lower === "a")) {
+					return { type: "bump", key: resolveFocusedBackendNumberKey(focusKey, numberOptions), direction: -1 };
+				}
+				const parsed = Number.parseInt(raw, 10);
+				if (Number.isFinite(parsed) && parsed >= 1 && parsed <= toggleOptions.length) {
+					const target = toggleOptions[parsed - 1];
+					if (target) return { type: "toggle", key: target.key };
+				}
+				return undefined;
+			},
+		});
+
+		if (!result || result.type === "back") {
+			return { draft, focusKey };
+		}
+		if (result.type === "reset-category") {
+			draft = applyBackendCategoryDefaults(draft, category);
+			focusKey = getBackendCategoryInitialFocus(category);
+			continue;
+		}
+		if (result.type === "toggle") {
+			const currentValue = draft[result.key] ?? BACKEND_DEFAULTS[result.key] ?? false;
+			draft = { ...draft, [result.key]: !currentValue };
+			focusKey = result.key;
+			continue;
+		}
+
+		const option = BACKEND_NUMBER_OPTION_BY_KEY.get(result.key);
+		if (!option) continue;
+		const currentValue = draft[result.key] ?? BACKEND_DEFAULTS[result.key] ?? option.min;
+		const numericCurrent = typeof currentValue === "number" && Number.isFinite(currentValue)
+			? currentValue
+			: option.min;
+		draft = {
+			...draft,
+			[result.key]: clampBackendNumber(option, numericCurrent + option.step * result.direction),
+		};
+		focusKey = result.key;
+	}
+}
+
+async function promptBackendSettings(
+	initial: PluginConfig,
+): Promise<PluginConfig | null> {
+	if (!input.isTTY || !output.isTTY) return null;
+
+	const ui = getUiRuntimeOptions();
+	let draft = cloneBackendPluginConfig(initial);
+	let activeCategory = BACKEND_CATEGORY_OPTIONS[0]?.key ?? "session-sync";
+	const focusByCategory: Partial<Record<BackendCategoryKey, BackendSettingFocusKey>> = {};
+	for (const category of BACKEND_CATEGORY_OPTIONS) {
+		focusByCategory[category.key] = getBackendCategoryInitialFocus(category);
+	}
+
+	while (true) {
+		const previewFocus = focusByCategory[activeCategory] ?? null;
+		const preview = buildBackendSettingsPreview(draft, ui, previewFocus);
+		const categoryItems: MenuItem<BackendSettingsHubAction>[] = BACKEND_CATEGORY_OPTIONS.map((category, index) => {
+			return {
+				label: `${index + 1}. ${category.label}`,
+				hint: category.description,
+				value: { type: "open-category", key: category.key },
+				color: "green",
+			};
+		});
+
+		const items: MenuItem<BackendSettingsHubAction>[] = [
+			{ label: UI_COPY.settings.previewHeading, value: { type: "cancel" }, kind: "heading" },
+			{
+				label: preview.label,
+				hint: preview.hint,
+				value: { type: "cancel" },
+				disabled: true,
+				color: "green",
+				hideUnavailableSuffix: true,
+			},
+			{ label: "", value: { type: "cancel" }, separator: true },
+			{ label: UI_COPY.settings.backendCategoriesHeading, value: { type: "cancel" }, kind: "heading" },
+			...categoryItems,
+			{ label: "", value: { type: "cancel" }, separator: true },
+			{ label: UI_COPY.settings.resetDefault, value: { type: "reset" }, color: "yellow" },
+			{ label: UI_COPY.settings.saveAndBack, value: { type: "save" }, color: "green" },
+			{ label: UI_COPY.settings.backNoSave, value: { type: "cancel" }, color: "red" },
+		];
+
+		const initialCursor = items.findIndex((item) => {
+			if (item.separator || item.disabled || item.kind === "heading") return false;
+			return item.value.type === "open-category" && item.value.key === activeCategory;
+		});
+
+		const result = await select<BackendSettingsHubAction>(items, {
+			message: UI_COPY.settings.backendTitle,
+			subtitle: UI_COPY.settings.backendSubtitle,
+			help: UI_COPY.settings.backendHelp,
+			clearScreen: true,
+			theme: ui.theme,
+			selectedEmphasis: "minimal",
+			initialCursor: initialCursor >= 0 ? initialCursor : undefined,
+			onCursorChange: ({ cursor }) => {
+				const focusedItem = items[cursor];
+				if (focusedItem?.value.type === "open-category") {
+					activeCategory = focusedItem.value.key;
+				}
+			},
+			onInput: (raw) => {
+				const lower = raw.toLowerCase();
+				if (lower === "q") return { type: "save" };
+				if (lower === "s") return { type: "save" };
+				if (lower === "r") return { type: "reset" };
+				const parsed = Number.parseInt(raw, 10);
+				if (Number.isFinite(parsed) && parsed >= 1 && parsed <= BACKEND_CATEGORY_OPTIONS.length) {
+					const target = BACKEND_CATEGORY_OPTIONS[parsed - 1];
+					if (target) return { type: "open-category", key: target.key };
+				}
+				return undefined;
+			},
+		});
+
+		if (!result || result.type === "cancel") return null;
+		if (result.type === "save") return draft;
+		if (result.type === "reset") {
+			draft = cloneBackendPluginConfig(BACKEND_DEFAULTS);
+			for (const category of BACKEND_CATEGORY_OPTIONS) {
+				focusByCategory[category.key] = getBackendCategoryInitialFocus(category);
+			}
+			activeCategory = BACKEND_CATEGORY_OPTIONS[0]?.key ?? activeCategory;
+			continue;
+		}
+
+		const category = getBackendCategory(result.key);
+		if (!category) continue;
+		activeCategory = category.key;
+		const categoryResult = await promptBackendCategorySettings(
+			draft,
+			category,
+			focusByCategory[category.key] ?? getBackendCategoryInitialFocus(category),
+		);
+		draft = categoryResult.draft;
+		focusByCategory[category.key] = categoryResult.focusKey;
+	}
+}
+
+async function configureBackendSettings(
+	currentConfig?: PluginConfig,
+): Promise<PluginConfig> {
+	const current = cloneBackendPluginConfig(currentConfig ?? loadPluginConfig());
+	if (!input.isTTY || !output.isTTY) {
+		console.log("Settings require interactive mode.");
+		return current;
+	}
+
+	const selected = await promptBackendSettings(current);
+	if (!selected) return current;
+	if (backendSettingsEqual(current, selected)) return current;
+
+	await savePluginConfig(buildBackendConfigPatch(selected));
+	return selected;
+}
+
+async function promptSettingsHub(
+	initialFocus: SettingsHubAction["type"] = "account-list",
+): Promise<SettingsHubAction | null> {
+	if (!input.isTTY || !output.isTTY) return null;
+	const ui = getUiRuntimeOptions();
+	const items: MenuItem<SettingsHubAction>[] = [
+		{ label: UI_COPY.settings.sectionTitle, value: { type: "back" }, kind: "heading" },
+		{ label: UI_COPY.settings.accountList, value: { type: "account-list" }, color: "green" },
+		{ label: UI_COPY.settings.summaryFields, value: { type: "summary-fields" }, color: "green" },
+		{ label: UI_COPY.settings.behavior, value: { type: "behavior" }, color: "green" },
+		{ label: UI_COPY.settings.theme, value: { type: "theme" }, color: "green" },
+		{ label: "", value: { type: "back" }, separator: true },
+		{ label: UI_COPY.settings.advancedTitle, value: { type: "back" }, kind: "heading" },
+		{ label: UI_COPY.settings.backend, value: { type: "backend" }, color: "green" },
+		{ label: "", value: { type: "back" }, separator: true },
+		{ label: UI_COPY.settings.exitTitle, value: { type: "back" }, kind: "heading" },
+		{ label: UI_COPY.settings.back, value: { type: "back" }, color: "red" },
+	];
+	const initialCursor = items.findIndex((item) => {
+		if (item.separator || item.disabled || item.kind === "heading") return false;
+		return item.value.type === initialFocus;
+	});
+	return select<SettingsHubAction>(items, {
+		message: UI_COPY.settings.title,
+		subtitle: UI_COPY.settings.subtitle,
+		help: UI_COPY.settings.help,
+		clearScreen: true,
+		theme: ui.theme,
+		selectedEmphasis: "minimal",
+		initialCursor: initialCursor >= 0 ? initialCursor : undefined,
+		onInput: (raw) => {
+			const lower = raw.toLowerCase();
+			if (lower === "q") return { type: "back" };
+			return undefined;
+		},
+	});
+}
+
+async function configureUnifiedSettings(
+	initialSettings?: DashboardDisplaySettings,
+): Promise<DashboardDisplaySettings> {
+	let current = cloneDashboardSettings(initialSettings ?? await loadDashboardDisplaySettings());
+	let backendConfig = cloneBackendPluginConfig(loadPluginConfig());
+	applyUiThemeFromDashboardSettings(current);
+	let hubFocus: SettingsHubAction["type"] = "account-list";
+	while (true) {
+		const action = await promptSettingsHub(hubFocus);
+		if (!action || action.type === "back") {
+			return current;
+		}
+		hubFocus = action.type;
+		if (action.type === "account-list") {
+			current = await configureDashboardDisplaySettings(current);
+			continue;
+		}
+		if (action.type === "summary-fields") {
+			current = await configureStatuslineSettings(current);
+			continue;
+		}
+		if (action.type === "behavior") {
+			const selected = await promptBehaviorSettings(current);
+			if (selected && !dashboardSettingsEqual(current, selected)) {
+				current = selected;
+				await saveDashboardDisplaySettings(current);
+			}
+			continue;
+		}
+		if (action.type === "theme") {
+			const selected = await promptThemeSettings(current);
+			if (selected && !dashboardSettingsEqual(current, selected)) {
+				current = selected;
+				await saveDashboardDisplaySettings(current);
+				applyUiThemeFromDashboardSettings(current);
+			}
+			continue;
+		}
+		if (action.type === "backend") {
+			backendConfig = await configureBackendSettings(backendConfig);
+		}
+	}
+}
+
+async function runOAuthFlow(forceNewLogin: boolean): Promise<TokenResult> {
+	const { pkce, state, url } = await createAuthorizationFlow({ forceNewLogin });
+	const oauthServer = await startLocalOAuthServer({ state });
+	let code: string | null = null;
+	try {
+		const signInMode = await promptOAuthSignInMode();
+		if (signInMode === "cancel") {
+			return {
+				type: "failed",
+				reason: "unknown",
+				message: UI_COPY.oauth.cancelled,
+			};
+		}
+
+		if (signInMode === "browser") {
+			const opened = openBrowserUrl(url);
+			if (opened) {
+				console.log(stylePromptText(UI_COPY.oauth.browserOpened, "success"));
+			} else {
+				console.log(stylePromptText(UI_COPY.oauth.browserOpenFail, "warning"));
+				console.log(`${stylePromptText(UI_COPY.oauth.goTo, "accent")} ${url}`);
+				const copied = copyTextToClipboard(url);
+				console.log(
+					stylePromptText(
+						copied ? UI_COPY.oauth.copyOk : UI_COPY.oauth.copyFail,
+						copied ? "success" : "warning",
+					),
+				);
+			}
+		} else {
+			console.log(`${stylePromptText(UI_COPY.oauth.goTo, "accent")} ${url}`);
+			const copied = copyTextToClipboard(url);
+			console.log(
+				stylePromptText(
+					copied ? UI_COPY.oauth.copyOk : UI_COPY.oauth.copyFail,
+					copied ? "success" : "warning",
+				),
+			);
+		}
+
+		if (oauthServer.ready) {
+			console.log(stylePromptText(UI_COPY.oauth.waitingCallback, "muted"));
+			const callbackResult = await oauthServer.waitForCode(state);
+			code = callbackResult?.code ?? null;
+		}
+
+		if (!code) {
+			console.log(stylePromptText(UI_COPY.oauth.callbackMissed, "warning"));
+			code = await promptManualCallback(state);
+		}
+	} finally {
+		oauthServer.close();
+	}
+
+	if (!code) {
+		return {
+			type: "failed",
+			reason: "unknown",
+			message: UI_COPY.oauth.cancelled,
+		};
+	}
+	return exchangeAuthorizationCode(code, pkce.verifier, REDIRECT_URI);
+}
+
+async function persistAccountPool(
+	results: TokenSuccessWithAccount[],
+	replaceAll: boolean,
+): Promise<void> {
+	if (results.length === 0) return;
+
+	const loadedStorage = replaceAll
+		? null
+		: await loadAccounts();
+	const now = Date.now();
+	const accounts = loadedStorage?.accounts ? [...loadedStorage.accounts] : [];
+
+	const indexByRefreshToken = new Map<string, number>();
+	const indexByAccountId = new Map<string, number>();
+	const indexByEmail = new Map<string, number>();
+	let selectedAccountIndex: number | null = null;
+
+	for (let i = 0; i < accounts.length; i += 1) {
+		const account = accounts[i];
+		if (!account) continue;
+		if (account.refreshToken) indexByRefreshToken.set(account.refreshToken, i);
+		if (account.accountId) indexByAccountId.set(account.accountId, i);
+		if (account.email) indexByEmail.set(account.email, i);
+	}
+
+	for (const result of results) {
+		const tokenAccountId = extractAccountId(result.access);
+		const accountId = resolveRequestAccountId(
+			result.accountIdOverride,
+			result.accountIdSource,
+			tokenAccountId,
+		);
+		const accountIdSource = accountId
+			? (result.accountIdSource ?? (result.accountIdOverride ? "manual" : "token"))
+			: undefined;
+		const accountLabel = result.accountLabel;
+		const accountEmail = sanitizeEmail(extractAccountEmail(result.access, result.idToken));
+
+		const existingByEmail =
+			accountEmail && indexByEmail.has(accountEmail)
+				? indexByEmail.get(accountEmail)
+				: undefined;
+		const existingById =
+			accountId && indexByAccountId.has(accountId)
+				? indexByAccountId.get(accountId)
+				: undefined;
+		const existingByToken = indexByRefreshToken.get(result.refresh);
+		const existingIndex = existingById ?? existingByEmail ?? existingByToken;
+
+		if (existingIndex === undefined) {
+			const newIndex = accounts.length;
+			accounts.push({
+				accountId,
+				accountIdSource,
+				accountLabel,
+				email: accountEmail,
+				refreshToken: result.refresh,
+				accessToken: result.access,
+				expiresAt: result.expires,
+				enabled: true,
+				addedAt: now,
+				lastUsed: now,
+			});
+			indexByRefreshToken.set(result.refresh, newIndex);
+			if (accountId) indexByAccountId.set(accountId, newIndex);
+			if (accountEmail) indexByEmail.set(accountEmail, newIndex);
+			selectedAccountIndex = newIndex;
+			continue;
+		}
+
+		const existing = accounts[existingIndex];
+		if (!existing) continue;
+
+		const oldToken = existing.refreshToken;
+		const oldEmail = existing.email;
+		const nextEmail = accountEmail ?? existing.email;
+		const nextAccountId = accountId ?? existing.accountId;
+		const nextAccountIdSource = accountId
+			? (accountIdSource ?? existing.accountIdSource)
+			: existing.accountIdSource;
+
+		accounts[existingIndex] = {
+			...existing,
+			accountId: nextAccountId,
+			accountIdSource: nextAccountIdSource,
+			accountLabel: accountLabel ?? existing.accountLabel,
+			email: nextEmail,
+			refreshToken: result.refresh,
+			accessToken: result.access,
+			expiresAt: result.expires,
+			enabled: true,
+			lastUsed: now,
+		};
+
+		if (oldToken !== result.refresh) {
+			indexByRefreshToken.delete(oldToken);
+			indexByRefreshToken.set(result.refresh, existingIndex);
+		}
+		if (nextAccountId) {
+			indexByAccountId.set(nextAccountId, existingIndex);
+		}
+		if (oldEmail && oldEmail !== nextEmail) {
+			indexByEmail.delete(oldEmail);
+		}
+		if (nextEmail) {
+			indexByEmail.set(nextEmail, existingIndex);
+		}
+		selectedAccountIndex = existingIndex;
+	}
+
+	const fallbackActiveIndex = accounts.length === 0
+		? 0
+		: Math.max(0, Math.min(loadedStorage?.activeIndex ?? 0, accounts.length - 1));
+	const nextActiveIndex = accounts.length === 0
+		? 0
+		: selectedAccountIndex === null
+			? fallbackActiveIndex
+			: Math.max(0, Math.min(selectedAccountIndex, accounts.length - 1));
+	const activeIndexByFamily: Partial<Record<ModelFamily, number>> = {};
+	for (const family of MODEL_FAMILIES) {
+		activeIndexByFamily[family] = nextActiveIndex;
+	}
+
+	await saveAccounts({
+		version: 3,
+		accounts,
+		activeIndex: nextActiveIndex,
+		activeIndexByFamily,
+	});
+}
+
+async function syncSelectionToCodex(tokens: TokenSuccessWithAccount): Promise<void> {
+	const tokenAccountId = extractAccountId(tokens.access);
+	const accountId = resolveRequestAccountId(
+		tokens.accountIdOverride,
+		tokens.accountIdSource,
+		tokenAccountId,
+	);
+	const email = sanitizeEmail(extractAccountEmail(tokens.access, tokens.idToken));
+	await setCodexCliActiveSelection({
+		accountId,
+		email,
+		accessToken: tokens.access,
+		refreshToken: tokens.refresh,
+		expiresAt: tokens.expires,
+		idToken: tokens.idToken,
+	});
+}
+
+async function showAccountStatus(): Promise<void> {
+	setStoragePath(null);
+	const storage = await loadAccounts();
+	const path = getStoragePath();
+	if (!storage || storage.accounts.length === 0) {
+		console.log("No accounts configured.");
+		console.log(`Storage: ${path}`);
+		return;
+	}
+
+	const now = Date.now();
+	const activeIndex = resolveActiveIndex(storage, "codex");
+	console.log(`Accounts (${storage.accounts.length})`);
+	console.log(`Storage: ${path}`);
+	console.log("");
+	for (let i = 0; i < storage.accounts.length; i += 1) {
+		const account = storage.accounts[i];
+		if (!account) continue;
+		const label = formatAccountLabel(account, i);
+		const markers: string[] = [];
+		if (i === activeIndex) markers.push("current");
+		if (account.enabled === false) markers.push("disabled");
+		const rateLimit = formatRateLimitEntry(account, now, "codex");
+		if (rateLimit) markers.push("rate-limited");
+		const cooldown = formatCooldown(account, now);
+		if (cooldown) markers.push(`cooldown:${cooldown}`);
+		const markerLabel = markers.length > 0 ? ` [${markers.join(", ")}]` : "";
+		const lastUsed = typeof account.lastUsed === "number" && account.lastUsed > 0
+			? `used ${formatWaitTime(now - account.lastUsed)} ago`
+			: "never used";
+		console.log(`${i + 1}. ${label}${markerLabel} ${lastUsed}`);
+	}
+}
+
+interface HealthCheckOptions {
+	forceRefresh?: boolean;
+	liveProbe?: boolean;
+	model?: string;
+	display?: DashboardDisplaySettings;
+}
+
+async function runHealthCheck(options: HealthCheckOptions = {}): Promise<void> {
+	const forceRefresh = options.forceRefresh === true;
+	const liveProbe = options.liveProbe === true;
+	const probeModel = options.model?.trim() || "gpt-5-codex";
+	const display = options.display ?? DEFAULT_DASHBOARD_DISPLAY_SETTINGS;
+	const quotaCache = liveProbe ? await loadQuotaCache() : null;
+	let quotaCacheChanged = false;
+	setStoragePath(null);
+	const storage = await loadAccounts();
+	if (!storage || storage.accounts.length === 0) {
+		console.log("No accounts configured.");
+		return;
+	}
+
+	let changed = false;
+	let ok = 0;
+	let failed = 0;
+	let warnings = 0;
+	const activeIndex = resolveActiveIndex(storage, "codex");
+	let activeAccountRefreshed = false;
+	const now = Date.now();
+	console.log(stylePromptText(
+		forceRefresh
+			? `Checking ${storage.accounts.length} account(s) with full refresh test...`
+			: `Checking ${storage.accounts.length} account(s) with quick check${liveProbe ? " + live check" : ""}...`,
+		"accent",
+	));
+	for (let i = 0; i < storage.accounts.length; i += 1) {
+		const account = storage.accounts[i];
+		if (!account) continue;
+		const label = formatAccountLabel(account, i);
+		const labelText = stylePromptText(label, "accent");
+		const sessionLikelyValid = hasUsableAccessToken(account, now);
+		if (!forceRefresh && sessionLikelyValid) {
+			if (account.enabled === false) {
+				account.enabled = true;
+				changed = true;
+			}
+			if (i === activeIndex) {
+				activeAccountRefreshed = true;
+			}
+			let healthDetail = "signed in and working";
+			if (liveProbe) {
+				const currentAccessToken = account.accessToken;
+				const probeAccountId = currentAccessToken
+					? (account.accountId ?? extractAccountId(currentAccessToken))
+					: undefined;
+				if (!probeAccountId || !currentAccessToken) {
+					warnings += 1;
+					healthDetail = "signed in and working (live check skipped: missing account ID)";
+				} else {
+					try {
+						const snapshot = await fetchCodexQuotaSnapshot({
+							accountId: probeAccountId,
+							accessToken: currentAccessToken,
+							model: probeModel,
+						});
+						if (quotaCache) {
+							quotaCacheChanged =
+								updateQuotaCacheForAccount(quotaCache, account, snapshot) || quotaCacheChanged;
+						}
+						healthDetail = formatQuotaSnapshotForDashboard(snapshot, display);
+					} catch (error) {
+						const message = normalizeFailureDetail(
+							error instanceof Error ? error.message : String(error),
+							undefined,
+						);
+						warnings += 1;
+						healthDetail = `signed in and working (live check failed: ${message})`;
+					}
+				}
+			}
+			if (hasLikelyInvalidRefreshToken(account.refreshToken)) {
+				healthDetail += " (re-login suggested soon)";
+			}
+			ok += 1;
+			if (display.showPerAccountRows) {
+				console.log(
+					`  ${stylePromptText("✓", "success")} ${labelText} ${stylePromptText("|", "muted")} ${styleAccountDetailText(healthDetail)}`,
+				);
+			}
+			continue;
+		}
+		const result = await queuedRefresh(account.refreshToken);
+		if (result.type === "success") {
+			const tokenAccountId = extractAccountId(result.access);
+			const nextEmail = sanitizeEmail(extractAccountEmail(result.access, result.idToken));
+			if (account.refreshToken !== result.refresh) {
+				account.refreshToken = result.refresh;
+				changed = true;
+			}
+			if (account.accessToken !== result.access) {
+				account.accessToken = result.access;
+				changed = true;
+			}
+			if (account.expiresAt !== result.expires) {
+				account.expiresAt = result.expires;
+				changed = true;
+			}
+			if (nextEmail && nextEmail !== account.email) {
+				account.email = nextEmail;
+				changed = true;
+			}
+			if (tokenAccountId && tokenAccountId !== account.accountId) {
+				account.accountId = tokenAccountId;
+				account.accountIdSource = "token";
+				changed = true;
+			}
+			if (account.enabled === false) {
+				account.enabled = true;
+				changed = true;
+			}
+			account.lastUsed = Date.now();
+			if (i === activeIndex) {
+				activeAccountRefreshed = true;
+			}
+			ok += 1;
+			let healthyMessage = "working now";
+			if (liveProbe) {
+				const probeAccountId = account.accountId ?? tokenAccountId;
+				if (!probeAccountId) {
+					warnings += 1;
+					healthyMessage = "working now (live check skipped: missing account ID)";
+				} else {
+					try {
+						const snapshot = await fetchCodexQuotaSnapshot({
+							accountId: probeAccountId,
+							accessToken: result.access,
+							model: probeModel,
+						});
+						if (quotaCache) {
+							quotaCacheChanged =
+								updateQuotaCacheForAccount(quotaCache, account, snapshot) || quotaCacheChanged;
+						}
+						healthyMessage = formatQuotaSnapshotForDashboard(snapshot, display);
+					} catch (error) {
+						const message = normalizeFailureDetail(
+							error instanceof Error ? error.message : String(error),
+							undefined,
+						);
+						warnings += 1;
+						healthyMessage = `working now (live check failed: ${message})`;
+					}
+				}
+			}
+			if (display.showPerAccountRows) {
+				console.log(
+					`  ${stylePromptText("✓", "success")} ${labelText} ${stylePromptText("|", "muted")} ${styleAccountDetailText(healthyMessage)}`,
+				);
+			}
+		} else {
+			const detail = normalizeFailureDetail(result.message, result.reason);
+			if (sessionLikelyValid) {
+				warnings += 1;
+				if (display.showPerAccountRows) {
+					console.log(
+						`  ${stylePromptText("!", "warning")} ${labelText} ${stylePromptText("|", "muted")} ${stylePromptText(`refresh failed (${detail}) but this account still works right now`, "warning")}`,
+					);
+				}
+			} else {
+				failed += 1;
+				if (display.showPerAccountRows) {
+					console.log(
+						`  ${stylePromptText("✗", "danger")} ${labelText} ${stylePromptText("|", "muted")} ${stylePromptText(detail, "danger")}`,
+					);
+				}
+			}
+		}
+	}
+
+	if (!display.showPerAccountRows) {
+		console.log(stylePromptText("Per-account lines are hidden in dashboard settings.", "muted"));
+	}
+	if (quotaCache && quotaCacheChanged) {
+		await saveQuotaCache(quotaCache);
+	}
+
+	if (changed) {
+		await saveAccounts(storage);
+	}
+
+	if (activeAccountRefreshed && activeIndex >= 0 && activeIndex < storage.accounts.length) {
+		const activeAccount = storage.accounts[activeIndex];
+		if (activeAccount) {
+			await setCodexCliActiveSelection({
+				accountId: activeAccount.accountId,
+				email: activeAccount.email,
+				accessToken: activeAccount.accessToken,
+				refreshToken: activeAccount.refreshToken,
+				expiresAt: activeAccount.expiresAt,
+			});
+		}
+	}
+
+	console.log("");
+	console.log(formatResultSummary([
+		{ text: `${ok} working`, tone: "success" },
+		{ text: `${failed} need re-login`, tone: failed > 0 ? "danger" : "muted" },
+		{ text: `${warnings} warning${warnings === 1 ? "" : "s"}`, tone: warnings > 0 ? "warning" : "muted" },
+	]));
+}
+
+interface ForecastCliOptions {
+	live: boolean;
+	json: boolean;
+	model: string;
+}
+
+interface FixCliOptions {
+	dryRun: boolean;
+	json: boolean;
+	live: boolean;
+	model: string;
+}
+
+interface ReportCliOptions {
+	live: boolean;
+	json: boolean;
+	model: string;
+	outPath?: string;
+}
+
+interface VerifyFlaggedCliOptions {
+	dryRun: boolean;
+	json: boolean;
+	restore: boolean;
+}
+
+type ParsedArgsResult<T> = { ok: true; options: T } | { ok: false; message: string };
+
+function printForecastUsage(): void {
+	console.log(
+		[
+			"Usage:",
+			"  codex auth forecast [--live] [--json] [--model <model>]",
+			"",
+			"Options:",
+			"  --live, -l         Probe live quota headers via Codex backend",
+			"  --json, -j         Print machine-readable JSON output",
+			"  --model, -m        Probe model for live mode (default: gpt-5-codex)",
+		].join("\n"),
+	);
+}
+
+function printFixUsage(): void {
+	console.log(
+		[
+			"Usage:",
+			"  codex auth fix [--dry-run] [--json] [--live] [--model <model>]",
+			"",
+			"Options:",
+			"  --dry-run, -n      Preview changes without writing storage",
+			"  --json, -j         Print machine-readable JSON output",
+			"  --live, -l         Run live session probe before deciding health",
+			"  --model, -m        Probe model for live mode (default: gpt-5-codex)",
+			"",
+			"Behavior:",
+			"  - Refreshes tokens for enabled accounts",
+			"  - Disables hard-failed accounts (never deletes)",
+			"  - Recommends a better current account when needed",
+		].join("\n"),
+	);
+}
+
+function printVerifyFlaggedUsage(): void {
+	console.log(
+		[
+			"Usage:",
+			"  codex auth verify-flagged [--dry-run] [--json] [--no-restore]",
+			"",
+			"Options:",
+			"  --dry-run, -n      Preview changes without writing storage",
+			"  --json, -j         Print machine-readable JSON output",
+			"  --no-restore       Check flagged accounts without restoring healthy ones",
+			"",
+			"Behavior:",
+			"  - Refresh-checks accounts from flagged storage",
+			"  - Restores healthy accounts back to active storage by default",
+		].join("\n"),
+	);
+}
+
+function parseForecastArgs(args: string[]): ParsedArgsResult<ForecastCliOptions> {
+	const options: ForecastCliOptions = {
+		live: false,
+		json: false,
+		model: "gpt-5-codex",
+	};
+
+	for (let i = 0; i < args.length; i += 1) {
+		const arg = args[i];
+		if (!arg) continue;
+		if (!arg) continue;
+		if (arg === "--live" || arg === "-l") {
+			options.live = true;
+			continue;
+		}
+		if (arg === "--json" || arg === "-j") {
+			options.json = true;
+			continue;
+		}
+		if (arg === "--model" || arg === "-m") {
+			const value = args[i + 1];
+			if (!value) {
+				return { ok: false, message: "Missing value for --model" };
+			}
+			options.model = value;
+			i += 1;
+			continue;
+		}
+		if (arg.startsWith("--model=")) {
+			const value = arg.slice("--model=".length).trim();
+			if (!value) {
+				return { ok: false, message: "Missing value for --model" };
+			}
+			options.model = value;
+			continue;
+		}
+		return { ok: false, message: `Unknown option: ${arg}` };
+	}
+
+	return { ok: true, options };
+}
+
+function parseFixArgs(args: string[]): ParsedArgsResult<FixCliOptions> {
+	const options: FixCliOptions = {
+		dryRun: false,
+		json: false,
+		live: false,
+		model: "gpt-5-codex",
+	};
+
+	for (let i = 0; i < args.length; i += 1) {
+		const argValue = args[i];
+		if (typeof argValue !== "string") continue;
+		if (argValue === "--dry-run" || argValue === "-n") {
+			options.dryRun = true;
+			continue;
+		}
+		if (argValue === "--json" || argValue === "-j") {
+			options.json = true;
+			continue;
+		}
+		if (argValue === "--live" || argValue === "-l") {
+			options.live = true;
+			continue;
+		}
+		if (argValue === "--model" || argValue === "-m") {
+			const value = args[i + 1];
+			if (!value) {
+				return { ok: false, message: "Missing value for --model" };
+			}
+			options.model = value;
+			i += 1;
+			continue;
+		}
+		if (argValue.startsWith("--model=")) {
+			const value = argValue.slice("--model=".length).trim();
+			if (!value) {
+				return { ok: false, message: "Missing value for --model" };
+			}
+			options.model = value;
+			continue;
+		}
+		return { ok: false, message: `Unknown option: ${argValue}` };
+	}
+
+	return { ok: true, options };
+}
+
+function parseVerifyFlaggedArgs(args: string[]): ParsedArgsResult<VerifyFlaggedCliOptions> {
+	const options: VerifyFlaggedCliOptions = {
+		dryRun: false,
+		json: false,
+		restore: true,
+	};
+
+	for (const arg of args) {
+		if (arg === "--dry-run" || arg === "-n") {
+			options.dryRun = true;
+			continue;
+		}
+		if (arg === "--json" || arg === "-j") {
+			options.json = true;
+			continue;
+		}
+		if (arg === "--no-restore") {
+			options.restore = false;
+			continue;
+		}
+		return { ok: false, message: `Unknown option: ${arg}` };
+	}
+
+	return { ok: true, options };
+}
+
+interface DoctorCliOptions {
+	json: boolean;
+	fix: boolean;
+	dryRun: boolean;
+}
+
+function printDoctorUsage(): void {
+	console.log(
+		[
+			"Usage:",
+			"  codex auth doctor [--json] [--fix] [--dry-run]",
+			"",
+			"Options:",
+			"  --json, -j         Print machine-readable JSON diagnostics",
+			"  --fix              Apply safe auto-fixes to storage",
+			"  --dry-run, -n      Preview --fix changes without writing storage",
+			"",
+			"Behavior:",
+			"  - Validates account storage readability",
+			"  - Checks active index consistency and account duplication",
+			"  - Flags placeholder/demo accounts and disabled-all scenarios",
+		].join("\n"),
+	);
+}
+
+function parseDoctorArgs(args: string[]): ParsedArgsResult<DoctorCliOptions> {
+	const options: DoctorCliOptions = { json: false, fix: false, dryRun: false };
+	for (const arg of args) {
+		if (arg === "--json" || arg === "-j") {
+			options.json = true;
+			continue;
+		}
+		if (arg === "--fix") {
+			options.fix = true;
+			continue;
+		}
+		if (arg === "--dry-run" || arg === "-n") {
+			options.dryRun = true;
+			continue;
+		}
+		return { ok: false, message: `Unknown option: ${arg}` };
+	}
+	if (options.dryRun && !options.fix) {
+		return { ok: false, message: "--dry-run requires --fix" };
+	}
+	return { ok: true, options };
+}
+
+function printReportUsage(): void {
+	console.log(
+		[
+			"Usage:",
+			"  codex auth report [--live] [--json] [--model <model>] [--out <path>]",
+			"",
+			"Options:",
+			"  --live, -l         Probe live quota headers via Codex backend",
+			"  --json, -j         Print machine-readable JSON output",
+			"  --model, -m        Probe model for live mode (default: gpt-5-codex)",
+			"  --out              Write JSON report to a file path",
+		].join("\n"),
+	);
+}
+
+function parseReportArgs(args: string[]): ParsedArgsResult<ReportCliOptions> {
+	const options: ReportCliOptions = {
+		live: false,
+		json: false,
+		model: "gpt-5-codex",
+	};
+
+	for (let i = 0; i < args.length; i += 1) {
+		const arg = args[i];
+		if (!arg) continue;
+		if (arg === "--live" || arg === "-l") {
+			options.live = true;
+			continue;
+		}
+		if (arg === "--json" || arg === "-j") {
+			options.json = true;
+			continue;
+		}
+		if (arg === "--model" || arg === "-m") {
+			const value = args[i + 1];
+			if (!value) {
+				return { ok: false, message: "Missing value for --model" };
+			}
+			options.model = value;
+			i += 1;
+			continue;
+		}
+		if (arg.startsWith("--model=")) {
+			const value = arg.slice("--model=".length).trim();
+			if (!value) {
+				return { ok: false, message: "Missing value for --model" };
+			}
+			options.model = value;
+			continue;
+		}
+		if (arg === "--out") {
+			const value = args[i + 1];
+			if (!value) {
+				return { ok: false, message: "Missing value for --out" };
+			}
+			options.outPath = value;
+			i += 1;
+			continue;
+		}
+		if (arg.startsWith("--out=")) {
+			const value = arg.slice("--out=".length).trim();
+			if (!value) {
+				return { ok: false, message: "Missing value for --out" };
+			}
+			options.outPath = value;
+			continue;
+		}
+		return { ok: false, message: `Unknown option: ${arg}` };
+	}
+
+	return { ok: true, options };
+}
+
+function serializeForecastResults(
+	results: ForecastAccountResult[],
+	liveQuotaByIndex: Map<number, Awaited<ReturnType<typeof fetchCodexQuotaSnapshot>>>,
+	refreshFailures: Map<number, TokenFailure>,
+): Array<{
+	index: number;
+	label: string;
+	isCurrent: boolean;
+	availability: ForecastAccountResult["availability"];
+	riskScore: number;
+	riskLevel: ForecastAccountResult["riskLevel"];
+	waitMs: number;
+	reasons: string[];
+	liveQuota?: {
+		status: number;
+		planType?: string;
+		activeLimit?: number;
+		model: string;
+		summary: string;
+	};
+	refreshFailure?: TokenFailure;
+}> {
+	return results.map((result) => {
+		const liveQuota = liveQuotaByIndex.get(result.index);
+		return {
+			index: result.index,
+			label: result.label,
+			isCurrent: result.isCurrent,
+			availability: result.availability,
+			riskScore: result.riskScore,
+			riskLevel: result.riskLevel,
+			waitMs: result.waitMs,
+			reasons: result.reasons,
+			liveQuota: liveQuota
+				? {
+					status: liveQuota.status,
+					planType: liveQuota.planType,
+					activeLimit: liveQuota.activeLimit,
+					model: liveQuota.model,
+					summary: formatQuotaSnapshotLine(liveQuota),
+				}
+				: undefined,
+			refreshFailure: refreshFailures.get(result.index),
+		};
+	});
+}
+
+async function runForecast(args: string[]): Promise<number> {
+	if (args.includes("--help") || args.includes("-h")) {
+		printForecastUsage();
+		return 0;
+	}
+
+	const parsedArgs = parseForecastArgs(args);
+	if (!parsedArgs.ok) {
+		console.error(parsedArgs.message);
+		printForecastUsage();
+		return 1;
+	}
+	const options = parsedArgs.options;
+	const display = DEFAULT_DASHBOARD_DISPLAY_SETTINGS;
+	const quotaCache = options.live ? await loadQuotaCache() : null;
+	let quotaCacheChanged = false;
+
+	setStoragePath(null);
+	const storage = await loadAccounts();
+	if (!storage || storage.accounts.length === 0) {
+		console.log("No accounts configured.");
+		return 0;
+	}
+
+	const now = Date.now();
+	const activeIndex = resolveActiveIndex(storage, "codex");
+	const refreshFailures = new Map<number, TokenFailure>();
+	const liveQuotaByIndex = new Map<number, Awaited<ReturnType<typeof fetchCodexQuotaSnapshot>>>();
+	const probeErrors: string[] = [];
+
+	for (let i = 0; i < storage.accounts.length; i += 1) {
+		const account = storage.accounts[i];
+		if (!account || !options.live) continue;
+		if (account.enabled === false) continue;
+
+		let probeAccessToken = account.accessToken;
+		let probeAccountId = account.accountId ?? extractAccountId(account.accessToken);
+		if (!hasUsableAccessToken(account, now)) {
+			const refreshResult = await queuedRefresh(account.refreshToken);
+			if (refreshResult.type !== "success") {
+				refreshFailures.set(i, {
+					...refreshResult,
+					message: normalizeFailureDetail(refreshResult.message, refreshResult.reason),
+				});
+				continue;
+			}
+			probeAccessToken = refreshResult.access;
+			probeAccountId = account.accountId ?? extractAccountId(refreshResult.access);
+		}
+
+		if (!probeAccessToken || !probeAccountId) {
+			probeErrors.push(`${formatAccountLabel(account, i)}: missing accountId for live probe`);
+			continue;
+		}
+
+		try {
+			const liveQuota = await fetchCodexQuotaSnapshot({
+				accountId: probeAccountId,
+				accessToken: probeAccessToken,
+				model: options.model,
+			});
+			liveQuotaByIndex.set(i, liveQuota);
+			if (quotaCache) {
+				const account = storage.accounts[i];
+				if (account) {
+					quotaCacheChanged =
+						updateQuotaCacheForAccount(quotaCache, account, liveQuota) || quotaCacheChanged;
+				}
+			}
+		} catch (error) {
+			const message = normalizeFailureDetail(
+				error instanceof Error ? error.message : String(error),
+				undefined,
+			);
+			probeErrors.push(`${formatAccountLabel(account, i)}: ${message}`);
+		}
+	}
+
+	const forecastInputs = storage.accounts.map((account, index) => ({
+		index,
+		account,
+		isCurrent: index === activeIndex,
+		now,
+		refreshFailure: refreshFailures.get(index),
+		liveQuota: liveQuotaByIndex.get(index),
+	}));
+	const forecastResults = evaluateForecastAccounts(forecastInputs);
+	const summary = summarizeForecast(forecastResults);
+	const recommendation = recommendForecastAccount(forecastResults);
+
+	if (options.json) {
+		if (quotaCache && quotaCacheChanged) {
+			await saveQuotaCache(quotaCache);
+		}
+		console.log(
+			JSON.stringify(
+				{
+					command: "forecast",
+					model: options.model,
+					liveProbe: options.live,
+					summary,
+					recommendation,
+					probeErrors,
+					accounts: serializeForecastResults(forecastResults, liveQuotaByIndex, refreshFailures),
+				},
+				null,
+				2,
+			),
+		);
+		return 0;
+	}
+
+	console.log(
+		stylePromptText(
+			`Best-account preview (${storage.accounts.length} account(s), model ${options.model}, live check ${options.live ? "on" : "off"})`,
+			"accent",
+		),
+	);
+	console.log(
+		formatResultSummary([
+			{ text: `${summary.ready} ready now`, tone: "success" },
+			{ text: `${summary.delayed} waiting`, tone: "warning" },
+			{ text: `${summary.unavailable} unavailable`, tone: summary.unavailable > 0 ? "danger" : "muted" },
+			{ text: `${summary.highRisk} high risk`, tone: summary.highRisk > 0 ? "danger" : "muted" },
+		]),
+	);
+	console.log("");
+
+	for (const result of forecastResults) {
+		if (!display.showPerAccountRows) {
+			continue;
+		}
+		const currentTag = result.isCurrent ? " [current]" : "";
+		const waitLabel = result.waitMs > 0 ? stylePromptText(`wait ${formatWaitTime(result.waitMs)}`, "muted") : "";
+		const indexLabel = stylePromptText(`${result.index + 1}.`, "accent");
+		const accountLabel = stylePromptText(`${result.label}${currentTag}`, "accent");
+		const riskLabel = stylePromptText(`${result.riskLevel} risk (${result.riskScore})`, riskTone(result.riskLevel));
+		const availabilityLabel = stylePromptText(result.availability, availabilityTone(result.availability));
+		const rowParts = [availabilityLabel, riskLabel];
+		if (waitLabel) rowParts.push(waitLabel);
+		console.log(`${indexLabel} ${accountLabel} ${stylePromptText("|", "muted")} ${joinStyledSegments(rowParts)}`);
+		if (display.showForecastReasons && result.reasons.length > 0) {
+			console.log(`   ${stylePromptText(result.reasons.slice(0, 3).join("; "), "muted")}`);
+		}
+		const liveQuota = liveQuotaByIndex.get(result.index);
+		if (display.showQuotaDetails && liveQuota) {
+			console.log(`   ${stylePromptText("quota:", "accent")} ${styleQuotaSummary(formatCompactQuotaSnapshot(liveQuota))}`);
+		}
+	}
+
+	if (!display.showPerAccountRows) {
+		console.log(stylePromptText("Per-account lines are hidden in dashboard settings.", "muted"));
+	}
+
+	if (display.showRecommendations) {
+		console.log("");
+		if (recommendation.recommendedIndex !== null) {
+			const index = recommendation.recommendedIndex;
+			const account = forecastResults.find((result) => result.index === index);
+			if (account) {
+				console.log(
+					`${stylePromptText("Best next account:", "accent")} ${stylePromptText(`${index + 1} (${account.label})`, "success")}`,
+				);
+				console.log(`${stylePromptText("Why:", "accent")} ${stylePromptText(recommendation.reason, "muted")}`);
+				if (index !== activeIndex) {
+					console.log(`${stylePromptText("Switch now with:", "accent")} codex auth switch ${index + 1}`);
+				}
+			}
+		} else {
+			console.log(`${stylePromptText("Note:", "accent")} ${stylePromptText(recommendation.reason, "muted")}`);
+		}
+	}
+
+	if (display.showLiveProbeNotes && probeErrors.length > 0) {
+		console.log("");
+		console.log(stylePromptText(`Live check notes (${probeErrors.length}):`, "warning"));
+		for (const error of probeErrors) {
+			console.log(`  ${stylePromptText("-", "warning")} ${stylePromptText(error, "muted")}`);
+		}
+	}
+	if (quotaCache && quotaCacheChanged) {
+		await saveQuotaCache(quotaCache);
+	}
+
+	return 0;
+}
+
+async function runReport(args: string[]): Promise<number> {
+	if (args.includes("--help") || args.includes("-h")) {
+		printReportUsage();
+		return 0;
+	}
+
+	const parsedArgs = parseReportArgs(args);
+	if (!parsedArgs.ok) {
+		console.error(parsedArgs.message);
+		printReportUsage();
+		return 1;
+	}
+	const options = parsedArgs.options;
+
+	setStoragePath(null);
+	const storagePath = getStoragePath();
+	const storage = await loadAccounts();
+	const now = Date.now();
+	const accountCount = storage?.accounts.length ?? 0;
+	const activeIndex = storage ? resolveActiveIndex(storage, "codex") : 0;
+	const refreshFailures = new Map<number, TokenFailure>();
+	const liveQuotaByIndex = new Map<number, Awaited<ReturnType<typeof fetchCodexQuotaSnapshot>>>();
+	const probeErrors: string[] = [];
+
+	if (storage && options.live) {
+		for (let i = 0; i < storage.accounts.length; i += 1) {
+			const account = storage.accounts[i];
+			if (!account || account.enabled === false) continue;
+
+			const refreshResult = await queuedRefresh(account.refreshToken);
+			if (refreshResult.type !== "success") {
+				refreshFailures.set(i, {
+					...refreshResult,
+					message: normalizeFailureDetail(refreshResult.message, refreshResult.reason),
+				});
+				continue;
+			}
+
+			const accountId = account.accountId ?? extractAccountId(refreshResult.access);
+			if (!accountId) {
+				probeErrors.push(`${formatAccountLabel(account, i)}: missing accountId for live probe`);
+				continue;
+			}
+
+			try {
+				const liveQuota = await fetchCodexQuotaSnapshot({
+					accountId,
+					accessToken: refreshResult.access,
+					model: options.model,
+				});
+				liveQuotaByIndex.set(i, liveQuota);
+			} catch (error) {
+				const message = normalizeFailureDetail(
+					error instanceof Error ? error.message : String(error),
+					undefined,
+				);
+				probeErrors.push(`${formatAccountLabel(account, i)}: ${message}`);
+			}
+		}
+	}
+
+	const forecastResults = storage
+		? evaluateForecastAccounts(
+				storage.accounts.map((account, index) => ({
+					index,
+					account,
+					isCurrent: index === activeIndex,
+					now,
+					refreshFailure: refreshFailures.get(index),
+					liveQuota: liveQuotaByIndex.get(index),
+				})),
+			)
+		: [];
+	const forecastSummary = summarizeForecast(forecastResults);
+	const recommendation = recommendForecastAccount(forecastResults);
+	const enabledCount = storage
+		? storage.accounts.filter((account) => account.enabled !== false).length
+		: 0;
+	const disabledCount = Math.max(0, accountCount - enabledCount);
+	const coolingCount = storage
+		? storage.accounts.filter(
+				(account) =>
+					typeof account.coolingDownUntil === "number" && account.coolingDownUntil > now,
+			).length
+		: 0;
+	const rateLimitedCount = storage
+		? storage.accounts.filter((account) => !!formatRateLimitEntry(account, now, "codex")).length
+		: 0;
+
+	const report = {
+		command: "report",
+		generatedAt: new Date(now).toISOString(),
+		storagePath,
+		model: options.model,
+		liveProbe: options.live,
+		accounts: {
+			total: accountCount,
+			enabled: enabledCount,
+			disabled: disabledCount,
+			coolingDown: coolingCount,
+			rateLimited: rateLimitedCount,
+		},
+		activeIndex: accountCount > 0 ? activeIndex + 1 : null,
+		forecast: {
+			summary: forecastSummary,
+			recommendation,
+			probeErrors,
+			accounts: serializeForecastResults(forecastResults, liveQuotaByIndex, refreshFailures),
+		},
+	};
+
+	if (options.outPath) {
+		const outputPath = resolve(process.cwd(), options.outPath);
+		await fs.mkdir(dirname(outputPath), { recursive: true });
+		await fs.writeFile(outputPath, `${JSON.stringify(report, null, 2)}\n`, "utf-8");
+	}
+
+	if (options.json) {
+		console.log(JSON.stringify(report, null, 2));
+		return 0;
+	}
+
+	console.log(`Report generated at ${report.generatedAt}`);
+	console.log(`Storage: ${report.storagePath}`);
+	console.log(
+		`Accounts: ${report.accounts.total} total (${report.accounts.enabled} enabled, ${report.accounts.disabled} disabled, ${report.accounts.coolingDown} cooling, ${report.accounts.rateLimited} rate-limited)`,
+	);
+	if (report.activeIndex !== null) {
+		console.log(`Active account: ${report.activeIndex}`);
+	}
+	console.log(
+		`Forecast: ${report.forecast.summary.ready} ready, ${report.forecast.summary.delayed} delayed, ${report.forecast.summary.unavailable} unavailable`,
+	);
+	if (report.forecast.recommendation.recommendedIndex !== null) {
+		console.log(
+			`Recommendation: account ${report.forecast.recommendation.recommendedIndex + 1} (${report.forecast.recommendation.reason})`,
+		);
+	} else {
+		console.log(`Recommendation: ${report.forecast.recommendation.reason}`);
+	}
+	if (options.outPath) {
+		console.log(`Report written: ${resolve(process.cwd(), options.outPath)}`);
+	}
+	if (report.forecast.probeErrors.length > 0) {
+		console.log(`Probe notes: ${report.forecast.probeErrors.length}`);
+	}
+	return 0;
+}
+
+type FixOutcome =
+	| "healthy"
+	| "disabled-hard-failure"
+	| "warning-soft-failure"
+	| "already-disabled";
+
+interface FixAccountReport {
+	index: number;
+	label: string;
+	outcome: FixOutcome;
+	message: string;
+}
+
+function summarizeFixReports(
+	reports: FixAccountReport[],
+): {
+	healthy: number;
+	disabled: number;
+	warnings: number;
+	skipped: number;
+} {
+	let healthy = 0;
+	let disabled = 0;
+	let warnings = 0;
+	let skipped = 0;
+	for (const report of reports) {
+		if (report.outcome === "healthy") healthy += 1;
+		else if (report.outcome === "disabled-hard-failure") disabled += 1;
+		else if (report.outcome === "warning-soft-failure") warnings += 1;
+		else skipped += 1;
+	}
+	return { healthy, disabled, warnings, skipped };
+}
+
+interface VerifyFlaggedReport {
+	index: number;
+	label: string;
+	outcome: "restored" | "healthy-flagged" | "still-flagged" | "restore-skipped";
+	message: string;
+}
+
+function createEmptyAccountStorage(): AccountStorageV3 {
+	const activeIndexByFamily: Partial<Record<ModelFamily, number>> = {};
+	for (const family of MODEL_FAMILIES) {
+		activeIndexByFamily[family] = 0;
+	}
+	return {
+		version: 3,
+		accounts: [],
+		activeIndex: 0,
+		activeIndexByFamily,
+	};
+}
+
+function findExistingAccountIndexForFlagged(
+	storage: AccountStorageV3,
+	flagged: FlaggedAccountMetadataV1,
+	nextRefreshToken: string,
+	nextAccountId: string | undefined,
+	nextEmail: string | undefined,
+): number {
+	const flaggedEmail = sanitizeEmail(flagged.email);
+	const candidateAccountId = nextAccountId ?? flagged.accountId;
+	const candidateEmail = sanitizeEmail(nextEmail) ?? flaggedEmail;
+
+	for (let i = 0; i < storage.accounts.length; i += 1) {
+		const account = storage.accounts[i];
+		if (!account) continue;
+		if (account.refreshToken === flagged.refreshToken || account.refreshToken === nextRefreshToken) {
+			return i;
+		}
+		if (
+			candidateAccountId &&
+			typeof account.accountId === "string" &&
+			account.accountId === candidateAccountId
+		) {
+			return i;
+		}
+		const existingEmail = sanitizeEmail(account.email);
+		if (candidateEmail && existingEmail && existingEmail === candidateEmail) {
+			return i;
+		}
+	}
+
+	return -1;
+}
+
+function upsertRecoveredFlaggedAccount(
+	storage: AccountStorageV3,
+	flagged: FlaggedAccountMetadataV1,
+	refreshResult: TokenSuccess,
+	now: number,
+): { restored: boolean; changed: boolean; message: string } {
+	const nextEmail = sanitizeEmail(extractAccountEmail(refreshResult.access, refreshResult.idToken)) ?? flagged.email;
+	const nextAccountId = extractAccountId(refreshResult.access) ?? flagged.accountId;
+	const existingIndex = findExistingAccountIndexForFlagged(
+		storage,
+		flagged,
+		refreshResult.refresh,
+		nextAccountId,
+		nextEmail,
+	);
+
+	if (existingIndex >= 0) {
+		const existing = storage.accounts[existingIndex];
+		if (!existing) {
+			return { restored: false, changed: false, message: "existing account entry is missing" };
+		}
+		let changed = false;
+		if (existing.refreshToken !== refreshResult.refresh) {
+			existing.refreshToken = refreshResult.refresh;
+			changed = true;
+		}
+		if (existing.accessToken !== refreshResult.access) {
+			existing.accessToken = refreshResult.access;
+			changed = true;
+		}
+		if (existing.expiresAt !== refreshResult.expires) {
+			existing.expiresAt = refreshResult.expires;
+			changed = true;
+		}
+		if (nextEmail && nextEmail !== existing.email) {
+			existing.email = nextEmail;
+			changed = true;
+		}
+		if (nextAccountId && nextAccountId !== existing.accountId) {
+			existing.accountId = nextAccountId;
+			existing.accountIdSource = "token";
+			changed = true;
+		}
+		if (existing.enabled === false) {
+			existing.enabled = true;
+			changed = true;
+		}
+		if (existing.accountLabel !== flagged.accountLabel && flagged.accountLabel) {
+			existing.accountLabel = flagged.accountLabel;
+			changed = true;
+		}
+		existing.lastUsed = now;
+		return {
+			restored: true,
+			changed,
+			message: `restored into existing account ${existingIndex + 1}`,
+		};
+	}
+
+	if (storage.accounts.length >= ACCOUNT_LIMITS.MAX_ACCOUNTS) {
+		return {
+			restored: false,
+			changed: false,
+			message: `cannot restore (max ${ACCOUNT_LIMITS.MAX_ACCOUNTS} accounts reached)`,
+		};
+	}
+
+	storage.accounts.push({
+		refreshToken: refreshResult.refresh,
+		accessToken: refreshResult.access,
+		expiresAt: refreshResult.expires,
+		accountId: nextAccountId,
+		accountIdSource: nextAccountId ? "token" : flagged.accountIdSource,
+		accountLabel: flagged.accountLabel,
+		email: nextEmail,
+		addedAt: flagged.addedAt ?? now,
+		lastUsed: now,
+		enabled: true,
+	});
+	return {
+		restored: true,
+		changed: true,
+		message: `restored as account ${storage.accounts.length}`,
+	};
+}
+
+async function runVerifyFlagged(args: string[]): Promise<number> {
+	if (args.includes("--help") || args.includes("-h")) {
+		printVerifyFlaggedUsage();
+		return 0;
+	}
+
+	const parsedArgs = parseVerifyFlaggedArgs(args);
+	if (!parsedArgs.ok) {
+		console.error(parsedArgs.message);
+		printVerifyFlaggedUsage();
+		return 1;
+	}
+	const options = parsedArgs.options;
+
+	setStoragePath(null);
+	const flaggedStorage = await loadFlaggedAccounts();
+	if (flaggedStorage.accounts.length === 0) {
+		if (options.json) {
+			console.log(
+				JSON.stringify(
+					{
+						command: "verify-flagged",
+						total: 0,
+						restored: 0,
+						healthyFlagged: 0,
+						stillFlagged: 0,
+						changed: false,
+						dryRun: options.dryRun,
+						restore: options.restore,
+						reports: [] as VerifyFlaggedReport[],
+					},
+					null,
+					2,
+				),
+			);
+			return 0;
+		}
+		console.log("No flagged accounts to check.");
+		return 0;
+	}
+
+	let storage = await loadAccounts();
+	if (!storage) {
+		storage = createEmptyAccountStorage();
+	}
+	let storageChanged = false;
+	let flaggedChanged = false;
+	const reports: VerifyFlaggedReport[] = [];
+	const nextFlaggedAccounts: FlaggedAccountMetadataV1[] = [];
+	const now = Date.now();
+
+	for (let i = 0; i < flaggedStorage.accounts.length; i += 1) {
+		const flagged = flaggedStorage.accounts[i];
+		if (!flagged) continue;
+		const label = formatAccountLabel(flagged, i);
+		const result = await queuedRefresh(flagged.refreshToken);
+
+		if (result.type === "success") {
+			if (!options.restore) {
+				const nextFlagged: FlaggedAccountMetadataV1 = {
+					...flagged,
+					refreshToken: result.refresh,
+					accessToken: result.access,
+					expiresAt: result.expires,
+					accountId: extractAccountId(result.access) ?? flagged.accountId,
+					accountIdSource: extractAccountId(result.access) ? "token" : flagged.accountIdSource,
+					email: sanitizeEmail(extractAccountEmail(result.access, result.idToken)) ?? flagged.email,
+					lastUsed: now,
+					lastError: undefined,
+				};
+				nextFlaggedAccounts.push(nextFlagged);
+				if (JSON.stringify(nextFlagged) !== JSON.stringify(flagged)) {
+					flaggedChanged = true;
+				}
+				reports.push({
+					index: i,
+					label,
+					outcome: "healthy-flagged",
+					message: "session is healthy (left in flagged list due to --no-restore)",
+				});
+				continue;
+			}
+
+			const upsertResult = upsertRecoveredFlaggedAccount(storage, flagged, result, now);
+			if (upsertResult.restored) {
+				storageChanged = storageChanged || upsertResult.changed;
+				flaggedChanged = true;
+				reports.push({
+					index: i,
+					label,
+					outcome: "restored",
+					message: upsertResult.message,
+				});
+				continue;
+			}
+
+			const updatedFlagged: FlaggedAccountMetadataV1 = {
+				...flagged,
+				refreshToken: result.refresh,
+				accessToken: result.access,
+				expiresAt: result.expires,
+				accountId: extractAccountId(result.access) ?? flagged.accountId,
+				accountIdSource: extractAccountId(result.access) ? "token" : flagged.accountIdSource,
+				email: sanitizeEmail(extractAccountEmail(result.access, result.idToken)) ?? flagged.email,
+				lastUsed: now,
+				lastError: upsertResult.message,
+			};
+			nextFlaggedAccounts.push(updatedFlagged);
+			if (JSON.stringify(updatedFlagged) !== JSON.stringify(flagged)) {
+				flaggedChanged = true;
+			}
+			reports.push({
+				index: i,
+				label,
+				outcome: "restore-skipped",
+				message: upsertResult.message,
+			});
+			continue;
+		}
+
+		const detail = normalizeFailureDetail(result.message, result.reason);
+		const failedFlagged: FlaggedAccountMetadataV1 = {
+			...flagged,
+			lastError: detail,
+		};
+		nextFlaggedAccounts.push(failedFlagged);
+		if ((flagged.lastError ?? "") !== detail) {
+			flaggedChanged = true;
+		}
+		reports.push({
+			index: i,
+			label,
+			outcome: "still-flagged",
+			message: detail,
+		});
+	}
+
+	const remainingFlagged = nextFlaggedAccounts.length;
+	const restored = reports.filter((report) => report.outcome === "restored").length;
+	const healthyFlagged = reports.filter((report) => report.outcome === "healthy-flagged").length;
+	const stillFlagged = reports.filter((report) => report.outcome === "still-flagged").length;
+	const changed = storageChanged || flaggedChanged;
+
+	if (!options.dryRun) {
+		if (storageChanged) {
+			normalizeDoctorIndexes(storage);
+			await saveAccounts(storage);
+		}
+		if (flaggedChanged) {
+			await saveFlaggedAccounts({
+				version: 1,
+				accounts: nextFlaggedAccounts,
+			});
+		}
+	}
+
+	if (options.json) {
+		console.log(
+			JSON.stringify(
+				{
+					command: "verify-flagged",
+					total: flaggedStorage.accounts.length,
+					restored,
+					healthyFlagged,
+					stillFlagged,
+					remainingFlagged,
+					changed,
+					dryRun: options.dryRun,
+					restore: options.restore,
+					reports,
+				},
+				null,
+				2,
+			),
+		);
+		return 0;
+	}
+
+	console.log(
+		stylePromptText(
+			`Checking ${flaggedStorage.accounts.length} flagged account(s)...`,
+			"accent",
+		),
+	);
+	for (const report of reports) {
+		const tone = report.outcome === "restored"
+			? "success"
+			: report.outcome === "healthy-flagged"
+				? "warning"
+				: report.outcome === "restore-skipped"
+					? "warning"
+					: "danger";
+		const marker = report.outcome === "restored"
+			? "✓"
+			: report.outcome === "healthy-flagged"
+				? "!"
+				: report.outcome === "restore-skipped"
+					? "!"
+					: "✗";
+		console.log(
+			`${stylePromptText(marker, tone)} ${stylePromptText(`${report.index + 1}. ${report.label}`, "accent")} ${stylePromptText("|", "muted")} ${styleAccountDetailText(report.message, tone)}`,
+		);
+	}
+	console.log("");
+	console.log(formatResultSummary([
+		{ text: `${restored} restored`, tone: restored > 0 ? "success" : "muted" },
+		{ text: `${healthyFlagged} healthy (kept flagged)`, tone: healthyFlagged > 0 ? "warning" : "muted" },
+		{ text: `${stillFlagged} still flagged`, tone: stillFlagged > 0 ? "danger" : "muted" },
+	]));
+	if (options.dryRun) {
+		console.log(stylePromptText("Preview only: no changes were saved.", "warning"));
+	} else if (!changed) {
+		console.log(stylePromptText("No storage changes were needed.", "muted"));
+	}
+
+	return 0;
+}
+
+async function runFix(args: string[]): Promise<number> {
+	if (args.includes("--help") || args.includes("-h")) {
+		printFixUsage();
+		return 0;
+	}
+
+	const parsedArgs = parseFixArgs(args);
+	if (!parsedArgs.ok) {
+		console.error(parsedArgs.message);
+		printFixUsage();
+		return 1;
+	}
+	const options = parsedArgs.options;
+	const display = DEFAULT_DASHBOARD_DISPLAY_SETTINGS;
+	const quotaCache = options.live ? await loadQuotaCache() : null;
+	let quotaCacheChanged = false;
+
+	setStoragePath(null);
+	const storage = await loadAccounts();
+	if (!storage || storage.accounts.length === 0) {
+		console.log("No accounts configured.");
+		return 0;
+	}
+
+	const now = Date.now();
+	const activeIndex = resolveActiveIndex(storage, "codex");
+	let changed = false;
+	const reports: FixAccountReport[] = [];
+	const refreshFailures = new Map<number, TokenFailure>();
+	const hardDisabledIndexes: number[] = [];
+
+	for (let i = 0; i < storage.accounts.length; i += 1) {
+		const account = storage.accounts[i];
+		if (!account) continue;
+		const label = formatAccountLabel(account, i);
+
+		if (account.enabled === false) {
+			reports.push({
+				index: i,
+				label,
+				outcome: "already-disabled",
+				message: "already disabled",
+			});
+			continue;
+		}
+
+		if (hasUsableAccessToken(account, now)) {
+			if (options.live) {
+				const currentAccessToken = account.accessToken;
+				const probeAccountId = currentAccessToken
+					? (account.accountId ?? extractAccountId(currentAccessToken))
+					: undefined;
+				if (probeAccountId && currentAccessToken) {
+					try {
+						const snapshot = await fetchCodexQuotaSnapshot({
+							accountId: probeAccountId,
+							accessToken: currentAccessToken,
+							model: options.model,
+						});
+						if (quotaCache) {
+							quotaCacheChanged =
+								updateQuotaCacheForAccount(quotaCache, account, snapshot) || quotaCacheChanged;
+						}
+						reports.push({
+							index: i,
+							label,
+							outcome: "healthy",
+							message: display.showQuotaDetails
+								? `live session OK (${formatCompactQuotaSnapshot(snapshot)})`
+								: "live session OK",
+						});
+						continue;
+					} catch (error) {
+						const message = normalizeFailureDetail(
+							error instanceof Error ? error.message : String(error),
+							undefined,
+						);
+						reports.push({
+							index: i,
+							label,
+							outcome: "warning-soft-failure",
+							message: `live probe failed (${message}), trying refresh fallback`,
+						});
+					}
+				}
+			}
+
+			const refreshWarning = hasLikelyInvalidRefreshToken(account.refreshToken)
+				? " (refresh token looks stale; re-login recommended)"
+				: "";
+			reports.push({
+				index: i,
+				label,
+				outcome: "healthy",
+				message: `access token still valid${refreshWarning}`,
+			});
+			continue;
+		}
+
+		const refreshResult = await queuedRefresh(account.refreshToken);
+		if (refreshResult.type === "success") {
+			const nextEmail = sanitizeEmail(extractAccountEmail(refreshResult.access, refreshResult.idToken));
+			const nextAccountId = extractAccountId(refreshResult.access);
+			let accountChanged = false;
+
+			if (account.refreshToken !== refreshResult.refresh) {
+				account.refreshToken = refreshResult.refresh;
+				accountChanged = true;
+			}
+			if (account.accessToken !== refreshResult.access) {
+				account.accessToken = refreshResult.access;
+				accountChanged = true;
+			}
+			if (account.expiresAt !== refreshResult.expires) {
+				account.expiresAt = refreshResult.expires;
+				accountChanged = true;
+			}
+			if (nextEmail && nextEmail !== account.email) {
+				account.email = nextEmail;
+				accountChanged = true;
+			}
+			if (!account.accountId && nextAccountId) {
+				account.accountId = nextAccountId;
+				account.accountIdSource = "token";
+				accountChanged = true;
+			}
+
+			if (accountChanged) changed = true;
+			if (options.live) {
+				const probeAccountId = account.accountId ?? nextAccountId;
+				if (probeAccountId) {
+					try {
+						const snapshot = await fetchCodexQuotaSnapshot({
+							accountId: probeAccountId,
+							accessToken: refreshResult.access,
+							model: options.model,
+						});
+						if (quotaCache) {
+							quotaCacheChanged =
+								updateQuotaCacheForAccount(quotaCache, account, snapshot) || quotaCacheChanged;
+						}
+						reports.push({
+							index: i,
+							label,
+							outcome: "healthy",
+							message: display.showQuotaDetails
+								? `refresh + live probe succeeded (${formatCompactQuotaSnapshot(snapshot)})`
+								: "refresh + live probe succeeded",
+						});
+						continue;
+					} catch (error) {
+						const message = normalizeFailureDetail(
+							error instanceof Error ? error.message : String(error),
+							undefined,
+						);
+						reports.push({
+							index: i,
+							label,
+							outcome: "warning-soft-failure",
+							message: `refresh succeeded but live probe failed: ${message}`,
+						});
+						continue;
+					}
+				}
+			}
+			reports.push({
+				index: i,
+				label,
+				outcome: "healthy",
+				message: "refresh succeeded",
+			});
+			continue;
+		}
+
+		const detail = normalizeFailureDetail(refreshResult.message, refreshResult.reason);
+		refreshFailures.set(i, {
+			...refreshResult,
+			message: detail,
+		});
+		if (isHardRefreshFailure(refreshResult)) {
+			account.enabled = false;
+			changed = true;
+			hardDisabledIndexes.push(i);
+			reports.push({
+				index: i,
+				label,
+				outcome: "disabled-hard-failure",
+				message: detail,
+			});
+		} else {
+			reports.push({
+				index: i,
+				label,
+				outcome: "warning-soft-failure",
+				message: detail,
+			});
+		}
+	}
+
+	if (hardDisabledIndexes.length > 0) {
+		const enabledCount = storage.accounts.filter((account) => account.enabled !== false).length;
+		if (enabledCount === 0) {
+			const fallbackIndex =
+				hardDisabledIndexes.includes(activeIndex) ? activeIndex : hardDisabledIndexes[0];
+			const fallback = typeof fallbackIndex === "number"
+				? storage.accounts[fallbackIndex]
+				: undefined;
+			if (fallback && fallback.enabled === false) {
+				fallback.enabled = true;
+				changed = true;
+				const existingReport = reports.find(
+					(report) =>
+						report.index === fallbackIndex &&
+						report.outcome === "disabled-hard-failure",
+				);
+				if (existingReport) {
+					existingReport.outcome = "warning-soft-failure";
+					existingReport.message = `${existingReport.message} (kept enabled to avoid lockout; re-login required)`;
+				}
+			}
+		}
+	}
+
+	const forecastResults = evaluateForecastAccounts(
+		storage.accounts.map((account, index) => ({
+			index,
+			account,
+			isCurrent: index === activeIndex,
+			now,
+			refreshFailure: refreshFailures.get(index),
+		})),
+	);
+	const recommendation = recommendForecastAccount(forecastResults);
+	const reportSummary = summarizeFixReports(reports);
+
+	if (changed && !options.dryRun) {
+		await saveAccounts(storage);
+	}
+
+	if (options.json) {
+		if (quotaCache && quotaCacheChanged) {
+			await saveQuotaCache(quotaCache);
+		}
+		console.log(
+			JSON.stringify(
+				{
+					command: "fix",
+					dryRun: options.dryRun,
+					liveProbe: options.live,
+					model: options.model,
+					changed,
+					summary: reportSummary,
+					recommendation,
+					recommendedSwitchCommand:
+						recommendation.recommendedIndex !== null &&
+							recommendation.recommendedIndex !== activeIndex
+							? `codex auth switch ${recommendation.recommendedIndex + 1}`
+							: null,
+					reports,
+				},
+				null,
+				2,
+			),
+		);
+		return 0;
+	}
+
+	console.log(stylePromptText(`Auto-fix scan (${options.dryRun ? "preview" : "apply"})`, "accent"));
+	console.log(formatResultSummary([
+		{ text: `${reportSummary.healthy} working`, tone: "success" },
+		{ text: `${reportSummary.disabled} disabled`, tone: reportSummary.disabled > 0 ? "danger" : "muted" },
+		{
+			text: `${reportSummary.warnings} warning${reportSummary.warnings === 1 ? "" : "s"}`,
+			tone: reportSummary.warnings > 0 ? "warning" : "muted",
+		},
+		{ text: `${reportSummary.skipped} already disabled`, tone: "muted" },
+	]));
+	if (display.showPerAccountRows) {
+		console.log("");
+		for (const report of reports) {
+			const prefix =
+				report.outcome === "healthy"
+					? "✓"
+					: report.outcome === "disabled-hard-failure"
+						? "✗"
+						: report.outcome === "warning-soft-failure"
+							? "!"
+							: "-";
+			const tone = report.outcome === "healthy"
+				? "success"
+				: report.outcome === "disabled-hard-failure"
+					? "danger"
+					: report.outcome === "warning-soft-failure"
+						? "warning"
+						: "muted";
+			console.log(
+				`${stylePromptText(prefix, tone)} ${stylePromptText(`${report.index + 1}. ${report.label}`, "accent")} ${stylePromptText("|", "muted")} ${styleAccountDetailText(report.message, tone === "success" ? "muted" : tone)}`,
+			);
+		}
+	} else {
+		console.log("");
+		console.log(stylePromptText("Per-account lines are hidden in dashboard settings.", "muted"));
+	}
+
+	if (display.showRecommendations) {
+		console.log("");
+		if (recommendation.recommendedIndex !== null) {
+			const target = recommendation.recommendedIndex + 1;
+			console.log(`${stylePromptText("Best next account:", "accent")} ${stylePromptText(String(target), "success")}`);
+			console.log(`${stylePromptText("Why:", "accent")} ${stylePromptText(recommendation.reason, "muted")}`);
+			if (recommendation.recommendedIndex !== activeIndex) {
+				console.log(`${stylePromptText("Switch now with:", "accent")} codex auth switch ${target}`);
+			}
+		} else {
+			console.log(`${stylePromptText("Note:", "accent")} ${stylePromptText(recommendation.reason, "muted")}`);
+		}
+	}
+	if (quotaCache && quotaCacheChanged) {
+		await saveQuotaCache(quotaCache);
+	}
+
+	if (changed && options.dryRun) {
+		console.log(`\n${stylePromptText("Preview only: no changes were saved.", "warning")}`);
+	} else if (changed) {
+		console.log(`\n${stylePromptText("Saved updates.", "success")}`);
+	} else {
+		console.log(`\n${stylePromptText("No changes were needed.", "muted")}`);
+	}
+
+	return 0;
+}
+
+type DoctorSeverity = "ok" | "warn" | "error";
+
+interface DoctorCheck {
+	key: string;
+	severity: DoctorSeverity;
+	message: string;
+	details?: string;
+}
+
+interface DoctorFixAction {
+	key: string;
+	message: string;
+}
+
+function hasPlaceholderEmail(value: string | undefined): boolean {
+	if (!value) return false;
+	const email = value.trim().toLowerCase();
+	if (!email) return false;
+	return (
+		email.endsWith("@example.com") ||
+		email.includes("account1@example.com") ||
+		email.includes("account2@example.com") ||
+		email.includes("account3@example.com")
+	);
+}
+
+function normalizeDoctorIndexes(storage: AccountStorageV3): boolean {
+	const total = storage.accounts.length;
+	const nextActive = total === 0 ? 0 : Math.max(0, Math.min(storage.activeIndex, total - 1));
+	let changed = false;
+	if (storage.activeIndex !== nextActive) {
+		storage.activeIndex = nextActive;
+		changed = true;
+	}
+	storage.activeIndexByFamily = storage.activeIndexByFamily ?? {};
+	for (const family of MODEL_FAMILIES) {
+		const raw = storage.activeIndexByFamily[family];
+		const fallback = storage.activeIndex;
+		const candidate = typeof raw === "number" && Number.isFinite(raw) ? raw : fallback;
+		const clamped = total === 0 ? 0 : Math.max(0, Math.min(candidate, total - 1));
+		if (storage.activeIndexByFamily[family] !== clamped) {
+			storage.activeIndexByFamily[family] = clamped;
+			changed = true;
+		}
+	}
+	return changed;
+}
+
+function applyDoctorFixes(storage: AccountStorageV3): { changed: boolean; actions: DoctorFixAction[] } {
+	let changed = false;
+	const actions: DoctorFixAction[] = [];
+
+	if (normalizeDoctorIndexes(storage)) {
+		changed = true;
+		actions.push({
+			key: "active-index",
+			message: "Normalized active account indexes",
+		});
+	}
+
+	const seenRefreshTokens = new Map<string, number>();
+	for (let i = 0; i < storage.accounts.length; i += 1) {
+		const account = storage.accounts[i];
+		if (!account) continue;
+
+		const refreshToken = account.refreshToken.trim();
+		const existingTokenIndex = seenRefreshTokens.get(refreshToken);
+		if (typeof existingTokenIndex === "number") {
+			if (account.enabled !== false) {
+				account.enabled = false;
+				changed = true;
+				actions.push({
+					key: "duplicate-refresh-token",
+					message: `Disabled duplicate token entry on account ${i + 1} (kept account ${existingTokenIndex + 1})`,
+				});
+			}
+		} else {
+			seenRefreshTokens.set(refreshToken, i);
+		}
+
+		const tokenEmail = sanitizeEmail(extractAccountEmail(account.accessToken));
+		if (
+			tokenEmail &&
+			(!sanitizeEmail(account.email) || hasPlaceholderEmail(account.email))
+		) {
+			account.email = tokenEmail;
+			changed = true;
+			actions.push({
+				key: "email-from-token",
+				message: `Updated account ${i + 1} email from token claims`,
+			});
+		}
+
+		const tokenAccountId = extractAccountId(account.accessToken);
+		if (!account.accountId && tokenAccountId) {
+			account.accountId = tokenAccountId;
+			account.accountIdSource = "token";
+			changed = true;
+			actions.push({
+				key: "account-id-from-token",
+				message: `Filled missing accountId for account ${i + 1}`,
+			});
+		}
+	}
+
+	const enabledCount = storage.accounts.filter((account) => account.enabled !== false).length;
+	if (storage.accounts.length > 0 && enabledCount === 0) {
+		const index = resolveActiveIndex(storage, "codex");
+		const candidate = storage.accounts[index] ?? storage.accounts[0];
+		if (candidate) {
+			candidate.enabled = true;
+			changed = true;
+			actions.push({
+				key: "enabled-accounts",
+				message: `Re-enabled account ${index + 1} to avoid an all-disabled pool`,
+			});
+		}
+	}
+
+	if (normalizeDoctorIndexes(storage)) {
+		changed = true;
+	}
+
+	return { changed, actions };
+}
+
+async function runDoctor(args: string[]): Promise<number> {
+	if (args.includes("--help") || args.includes("-h")) {
+		printDoctorUsage();
+		return 0;
+	}
+
+	const parsedArgs = parseDoctorArgs(args);
+	if (!parsedArgs.ok) {
+		console.error(parsedArgs.message);
+		printDoctorUsage();
+		return 1;
+	}
+	const options = parsedArgs.options;
+
+	setStoragePath(null);
+	const storagePath = getStoragePath();
+	const checks: DoctorCheck[] = [];
+	const addCheck = (check: DoctorCheck): void => {
+		checks.push(check);
+	};
+
+	addCheck({
+		key: "storage-file",
+		severity: existsSync(storagePath) ? "ok" : "warn",
+		message: existsSync(storagePath)
+			? "Account storage file found"
+			: "Account storage file does not exist yet (first login pending)",
+		details: storagePath,
+	});
+
+	if (existsSync(storagePath)) {
+		try {
+			const stat = await fs.stat(storagePath);
+			addCheck({
+				key: "storage-readable",
+				severity: stat.size > 0 ? "ok" : "warn",
+				message: stat.size > 0 ? "Storage file is readable" : "Storage file is empty",
+				details: `${stat.size} bytes`,
+			});
+		} catch (error) {
+			addCheck({
+				key: "storage-readable",
+				severity: "error",
+				message: "Unable to read storage file metadata",
+				details: error instanceof Error ? error.message : String(error),
+			});
+		}
+	}
+
+	const storage = await loadAccounts();
+	let fixChanged = false;
+	let fixActions: DoctorFixAction[] = [];
+	if (options.fix && storage && storage.accounts.length > 0) {
+		const fixed = applyDoctorFixes(storage);
+		fixChanged = fixed.changed;
+		fixActions = fixed.actions;
+		if (fixChanged && !options.dryRun) {
+			await saveAccounts(storage);
+		}
+		addCheck({
+			key: "auto-fix",
+			severity: fixChanged ? "warn" : "ok",
+			message: fixChanged
+				? options.dryRun
+					? `Prepared ${fixActions.length} fix(es) (dry-run)`
+					: `Applied ${fixActions.length} fix(es)`
+				: "No safe auto-fixes needed",
+		});
+	}
+	if (!storage || storage.accounts.length === 0) {
+		addCheck({
+			key: "accounts",
+			severity: "warn",
+			message: "No accounts configured",
+		});
+	} else {
+		addCheck({
+			key: "accounts",
+			severity: "ok",
+			message: `Loaded ${storage.accounts.length} account(s)`,
+		});
+
+		const activeIndex = resolveActiveIndex(storage, "codex");
+		const activeExists = activeIndex >= 0 && activeIndex < storage.accounts.length;
+		addCheck({
+			key: "active-index",
+			severity: activeExists ? "ok" : "error",
+			message: activeExists
+				? `Active index is valid (${activeIndex + 1})`
+				: "Active index is out of range",
+		});
+
+		const disabledCount = storage.accounts.filter((a) => a.enabled === false).length;
+		addCheck({
+			key: "enabled-accounts",
+			severity: disabledCount >= storage.accounts.length ? "error" : "ok",
+			message:
+				disabledCount >= storage.accounts.length
+					? "All accounts are disabled"
+					: `${storage.accounts.length - disabledCount} enabled / ${disabledCount} disabled`,
+		});
+
+		const seenRefreshTokens = new Set<string>();
+		let duplicateTokenCount = 0;
+		for (const account of storage.accounts) {
+			const token = account.refreshToken.trim();
+			if (seenRefreshTokens.has(token)) {
+				duplicateTokenCount += 1;
+			} else {
+				seenRefreshTokens.add(token);
+			}
+		}
+		addCheck({
+			key: "duplicate-refresh-token",
+			severity: duplicateTokenCount > 0 ? "warn" : "ok",
+			message:
+				duplicateTokenCount > 0
+					? `Detected ${duplicateTokenCount} duplicate refresh token entr${duplicateTokenCount === 1 ? "y" : "ies"}`
+					: "No duplicate refresh tokens detected",
+		});
+
+		const seenEmails = new Set<string>();
+		let duplicateEmailCount = 0;
+		let placeholderEmailCount = 0;
+		let likelyInvalidRefreshTokenCount = 0;
+		for (const account of storage.accounts) {
+			const email = sanitizeEmail(account.email);
+			if (!email) continue;
+			if (seenEmails.has(email)) duplicateEmailCount += 1;
+			seenEmails.add(email);
+			if (hasPlaceholderEmail(email)) placeholderEmailCount += 1;
+			if (hasLikelyInvalidRefreshToken(account.refreshToken)) {
+				likelyInvalidRefreshTokenCount += 1;
+			}
+		}
+		addCheck({
+			key: "duplicate-email",
+			severity: duplicateEmailCount > 0 ? "warn" : "ok",
+			message:
+				duplicateEmailCount > 0
+					? `Detected ${duplicateEmailCount} duplicate email entr${duplicateEmailCount === 1 ? "y" : "ies"}`
+					: "No duplicate emails detected",
+		});
+		addCheck({
+			key: "placeholder-email",
+			severity: placeholderEmailCount > 0 ? "warn" : "ok",
+			message:
+				placeholderEmailCount > 0
+					? `${placeholderEmailCount} account(s) appear to be placeholder/demo entries`
+					: "No placeholder emails detected",
+		});
+		addCheck({
+			key: "refresh-token-shape",
+			severity: likelyInvalidRefreshTokenCount > 0 ? "warn" : "ok",
+			message:
+				likelyInvalidRefreshTokenCount > 0
+					? `${likelyInvalidRefreshTokenCount} account(s) have likely invalid refresh token format`
+					: "Refresh token format looks normal",
+		});
+
+		const now = Date.now();
+		const forecastResults = evaluateForecastAccounts(
+			storage.accounts.map((account, index) => ({
+				index,
+				account,
+				isCurrent: index === activeIndex,
+				now,
+			})),
+		);
+		const recommendation = recommendForecastAccount(forecastResults);
+		if (recommendation.recommendedIndex !== null && recommendation.recommendedIndex !== activeIndex) {
+			addCheck({
+				key: "recommended-switch",
+				severity: "warn",
+				message: `A healthier account is available: switch to ${recommendation.recommendedIndex + 1}`,
+				details: recommendation.reason,
+			});
+		} else {
+			addCheck({
+				key: "recommended-switch",
+				severity: "ok",
+				message: "Current account aligns with forecast recommendation",
+			});
+		}
+	}
+
+	const summary = checks.reduce(
+		(acc, check) => {
+			acc[check.severity] += 1;
+			return acc;
+		},
+		{ ok: 0, warn: 0, error: 0 },
+	);
+
+	if (options.json) {
+		console.log(
+			JSON.stringify(
+				{
+					command: "doctor",
+					storagePath,
+					summary,
+					checks,
+					fix: {
+						enabled: options.fix,
+						dryRun: options.dryRun,
+						changed: fixChanged,
+						actions: fixActions,
+					},
+				},
+				null,
+				2,
+			),
+		);
+		return summary.error > 0 ? 1 : 0;
+	}
+
+	console.log("Doctor diagnostics");
+	console.log(`Storage: ${storagePath}`);
+	console.log(`Summary: ${summary.ok} ok, ${summary.warn} warnings, ${summary.error} errors`);
+	console.log("");
+	for (const check of checks) {
+		const marker = check.severity === "ok" ? "✓" : check.severity === "warn" ? "!" : "✗";
+		console.log(`${marker} ${check.key}: ${check.message}`);
+		if (check.details) {
+			console.log(`  ${check.details}`);
+		}
+	}
+	if (options.fix) {
+		console.log("");
+		if (fixActions.length > 0) {
+			console.log(`Auto-fix actions (${options.dryRun ? "dry-run" : "applied"}):`);
+			for (const action of fixActions) {
+				console.log(`  - ${action.message}`);
+			}
+		} else {
+			console.log("Auto-fix actions: none");
+		}
+	}
+
+	return summary.error > 0 ? 1 : 0;
+}
+
+async function clearAccountsAndReset(): Promise<void> {
+	await saveAccounts({
+		version: 3,
+		accounts: [],
+		activeIndex: 0,
+		activeIndexByFamily: {},
+	});
+}
+
+async function handleManageAction(
+	storage: AccountStorageV3,
+	menuResult: Awaited<ReturnType<typeof promptLoginMode>>,
+): Promise<void> {
+	if (typeof menuResult.switchAccountIndex === "number") {
+		const index = menuResult.switchAccountIndex;
+		await runSwitch([String(index + 1)]);
+		return;
+	}
+
+	if (typeof menuResult.deleteAccountIndex === "number") {
+		const idx = menuResult.deleteAccountIndex;
+		if (idx >= 0 && idx < storage.accounts.length) {
+			storage.accounts.splice(idx, 1);
+			storage.activeIndex = 0;
+			storage.activeIndexByFamily = {};
+			for (const family of MODEL_FAMILIES) {
+				storage.activeIndexByFamily[family] = 0;
+			}
+			await saveAccounts(storage);
+			console.log(`Deleted account ${idx + 1}.`);
+		}
+		return;
+	}
+
+	if (typeof menuResult.toggleAccountIndex === "number") {
+		const idx = menuResult.toggleAccountIndex;
+		const account = storage.accounts[idx];
+		if (account) {
+			account.enabled = account.enabled === false;
+			await saveAccounts(storage);
+			console.log(
+				`${account.enabled === false ? "Disabled" : "Enabled"} account ${idx + 1}.`,
+			);
+		}
+		return;
+	}
+
+	if (typeof menuResult.refreshAccountIndex === "number") {
+		const idx = menuResult.refreshAccountIndex;
+		const existing = storage.accounts[idx];
+		if (!existing) return;
+
+		const tokenResult = await runOAuthFlow(true);
+		if (tokenResult.type !== "success") {
+			console.error(`Refresh failed: ${tokenResult.message ?? tokenResult.reason ?? "unknown error"}`);
+			return;
+		}
+
+		const resolved = resolveAccountSelection(tokenResult);
+		await persistAccountPool([resolved], false);
+		await syncSelectionToCodex(resolved);
+		console.log(`Refreshed account ${idx + 1}.`);
+	}
+}
+
+async function runAuthLogin(): Promise<number> {
+	setStoragePath(null);
+	let pendingMenuQuotaRefresh: Promise<void> | null = null;
+	let menuQuotaRefreshStatus: string | undefined;
+	loginFlow:
+	while (true) {
+		let existingStorage = await loadAccounts();
+		if (existingStorage && existingStorage.accounts.length > 0) {
+			while (true) {
+				existingStorage = await loadAccounts();
+				if (!existingStorage || existingStorage.accounts.length === 0) {
+					break;
+				}
+				const currentStorage = existingStorage;
+				const displaySettings = await loadDashboardDisplaySettings();
+				applyUiThemeFromDashboardSettings(displaySettings);
+				const quotaCache = await loadQuotaCache();
+				const shouldAutoFetchLimits = displaySettings.menuAutoFetchLimits ?? true;
+				const showFetchStatus = displaySettings.menuShowFetchStatus ?? true;
+				const quotaTtlMs = displaySettings.menuQuotaTtlMs ?? DEFAULT_MENU_QUOTA_REFRESH_TTL_MS;
+				if (shouldAutoFetchLimits && !pendingMenuQuotaRefresh) {
+					const staleCount = countMenuQuotaRefreshTargets(currentStorage, quotaCache, quotaTtlMs);
+					if (staleCount > 0) {
+						if (showFetchStatus) {
+							menuQuotaRefreshStatus = `${UI_COPY.mainMenu.loadingLimits} [0/${staleCount}]`;
+						}
+						pendingMenuQuotaRefresh = refreshQuotaCacheForMenu(
+							currentStorage,
+							quotaCache,
+							quotaTtlMs,
+							(current, total) => {
+								if (!showFetchStatus) return;
+								menuQuotaRefreshStatus = `${UI_COPY.mainMenu.loadingLimits} [${current}/${total}]`;
+							},
+						)
+							.then(() => undefined)
+							.catch(() => undefined)
+							.finally(() => {
+								menuQuotaRefreshStatus = undefined;
+								pendingMenuQuotaRefresh = null;
+							});
+					}
+				}
+				const flaggedStorage = await loadFlaggedAccounts();
+
+				const menuResult = await promptLoginMode(
+					toExistingAccountInfo(currentStorage, quotaCache, displaySettings),
+					{
+						flaggedCount: flaggedStorage.accounts.length,
+						statusMessage: showFetchStatus ? () => menuQuotaRefreshStatus : undefined,
+					},
+				);
+
+				if (menuResult.mode === "cancel") {
+					console.log("Cancelled.");
+					return 0;
+				}
+				if (menuResult.mode === "check") {
+					await runActionPanel("Quick Check", "Checking local session + live status", async () => {
+						await runHealthCheck({ forceRefresh: false, liveProbe: true });
+					}, displaySettings);
+					continue;
+				}
+				if (menuResult.mode === "deep-check") {
+					await runActionPanel("Deep Check", "Refreshing and testing all accounts", async () => {
+						await runHealthCheck({ forceRefresh: true, liveProbe: true });
+					}, displaySettings);
+					continue;
+				}
+				if (menuResult.mode === "forecast") {
+					await runActionPanel("Best Account", "Comparing accounts", async () => {
+						await runForecast(["--live"]);
+					}, displaySettings);
+					continue;
+				}
+				if (menuResult.mode === "fix") {
+					await runActionPanel("Auto-Fix", "Checking and fixing common issues", async () => {
+						await runFix(["--live"]);
+					}, displaySettings);
+					continue;
+				}
+				if (menuResult.mode === "settings") {
+					await configureUnifiedSettings(displaySettings);
+					continue;
+				}
+				if (menuResult.mode === "verify-flagged") {
+					await runActionPanel("Problem Account Check", "Checking problem accounts", async () => {
+						await runVerifyFlagged([]);
+					}, displaySettings);
+					continue;
+				}
+				if (menuResult.mode === "fresh" && menuResult.deleteAll) {
+					await runActionPanel("Reset Accounts", "Deleting all saved accounts", async () => {
+						await clearAccountsAndReset();
+						console.log("Deleted all accounts.");
+					}, displaySettings);
+					continue;
+				}
+				if (menuResult.mode === "manage") {
+					const requiresInteractiveOAuth = typeof menuResult.refreshAccountIndex === "number";
+					if (requiresInteractiveOAuth) {
+						await handleManageAction(currentStorage, menuResult);
+						continue;
+					}
+					await runActionPanel("Applying Change", "Updating selected account", async () => {
+						await handleManageAction(currentStorage, menuResult);
+					}, displaySettings);
+					continue;
+				}
+				if (menuResult.mode === "add") {
+					break;
+				}
+			}
+		}
+
+		const refreshedStorage = await loadAccounts();
+		const existingCount = refreshedStorage?.accounts.length ?? 0;
+		let forceNewLogin = existingCount > 0;
+		while (true) {
+			const tokenResult = await runOAuthFlow(forceNewLogin);
+			if (tokenResult.type !== "success") {
+				if (isUserCancelledOAuth(tokenResult)) {
+					if (existingCount > 0) {
+						console.log(stylePromptText(UI_COPY.oauth.cancelledBackToMenu, "muted"));
+						continue loginFlow;
+					}
+					console.log("Cancelled.");
+					return 0;
+				}
+				console.error(`Login failed: ${tokenResult.message ?? tokenResult.reason ?? "unknown error"}`);
+				return 1;
+			}
+
+			const resolved = resolveAccountSelection(tokenResult);
+			await persistAccountPool([resolved], false);
+			await syncSelectionToCodex(resolved);
+
+			const latestStorage = await loadAccounts();
+			const count = latestStorage?.accounts.length ?? 1;
+			console.log(`Added account. Total: ${count}`);
+			if (count >= ACCOUNT_LIMITS.MAX_ACCOUNTS) {
+				console.log(`Reached maximum account limit (${ACCOUNT_LIMITS.MAX_ACCOUNTS}).`);
+				break;
+			}
+
+			const addAnother = await promptAddAnotherAccount(count);
+			if (!addAnother) break;
+			forceNewLogin = true;
+		}
+		continue loginFlow;
+	}
+}
+
+async function runSwitch(args: string[]): Promise<number> {
+	setStoragePath(null);
+	const indexArg = args[0];
+	if (!indexArg) {
+		console.error("Missing index. Usage: codex-multi-auth auth switch <index>");
+		return 1;
+	}
+	const parsed = Number.parseInt(indexArg, 10);
+	if (!Number.isFinite(parsed) || parsed < 1) {
+		console.error(`Invalid index: ${indexArg}`);
+		return 1;
+	}
+	const targetIndex = parsed - 1;
+
+	const storage = await loadAccounts();
+	if (!storage || storage.accounts.length === 0) {
+		console.error("No accounts configured.");
+		return 1;
+	}
+	if (targetIndex < 0 || targetIndex >= storage.accounts.length) {
+		console.error(`Index out of range. Valid range: 1-${storage.accounts.length}`);
+		return 1;
+	}
+
+	const account = storage.accounts[targetIndex];
+	if (!account) {
+		console.error(`Account ${parsed} not found.`);
+		return 1;
+	}
+
+	storage.activeIndex = targetIndex;
+	storage.activeIndexByFamily = storage.activeIndexByFamily ?? {};
+	for (const family of MODEL_FAMILIES) {
+		storage.activeIndexByFamily[family] = targetIndex;
+	}
+	const wasDisabled = account.enabled === false;
+	if (wasDisabled) {
+		account.enabled = true;
+	}
+	account.lastUsed = Date.now();
+	account.lastSwitchReason = "rotation";
+	await saveAccounts(storage);
+
+	const synced = await setCodexCliActiveSelection({
+		accountId: account.accountId,
+		email: account.email,
+		accessToken: account.accessToken,
+		refreshToken: account.refreshToken,
+		expiresAt: account.expiresAt,
+	});
+	if (!synced) {
+		console.error(
+			`Switch failed: account ${parsed} was selected locally but Codex auth sync failed. Run \"Refresh login for this account\" and retry.`,
+		);
+		return 1;
+	}
+
+	console.log(
+		`Switched to account ${parsed}: ${formatAccountLabel(account, targetIndex)}${wasDisabled ? " (re-enabled)" : ""}`,
+	);
+	return 0;
+}
+
+export async function runCodexMultiAuthCli(rawArgs: string[]): Promise<number> {
+	const startupDisplaySettings = await loadDashboardDisplaySettings();
+	applyUiThemeFromDashboardSettings(startupDisplaySettings);
+
+	const args = [...rawArgs];
+	if (args.length === 0) {
+		printUsage();
+		return 0;
+	}
+	if (args[0] === "--help" || args[0] === "-h") {
+		printUsage();
+		return 0;
+	}
+
+	const [root, sub, ...rest] = args;
+	if (root !== "auth") {
+		printUsage();
+		return 1;
+	}
+
+	const command = sub ?? "login";
+	if (command === "--help" || command === "-h") {
+		printUsage();
+		return 0;
+	}
+	if (command === "login") {
+		return runAuthLogin();
+	}
+	if (command === "list" || command === "status") {
+		await showAccountStatus();
+		return 0;
+	}
+	if (command === "switch") {
+		return runSwitch(rest);
+	}
+	if (command === "check") {
+		await runHealthCheck({ liveProbe: true });
+		return 0;
+	}
+	if (command === "features") {
+		return runFeaturesReport();
+	}
+	if (command === "verify-flagged") {
+		return runVerifyFlagged(rest);
+	}
+	if (command === "forecast") {
+		return runForecast(rest);
+	}
+	if (command === "report") {
+		return runReport(rest);
+	}
+	if (command === "fix") {
+		return runFix(rest);
+	}
+	if (command === "doctor") {
+		return runDoctor(rest);
+	}
+
+	console.error(`Unknown command: ${command}`);
+	printUsage();
+	return 1;
+}
diff --git a/lib/config.ts b/lib/config.ts
index 3efadbec..c992f00b 100644
--- a/lib/config.ts
+++ b/lib/config.ts
@@ -1,17 +1,32 @@
-import { readFileSync, existsSync } from "node:fs";
-import { join } from "node:path";
-import { homedir } from "node:os";
+import { readFileSync, existsSync, promises as fs } from "node:fs";
+import { dirname, join } from "node:path";
 import type { PluginConfig } from "./types.js";
 import { logWarn } from "./logger.js";
 import { PluginConfigSchema, getValidationErrors } from "./schemas.js";
+import { getCodexHomeDir, getCodexMultiAuthDir, getLegacyOpenCodeDir } from "./runtime-paths.js";
+import {
+	getUnifiedSettingsPath,
+	loadUnifiedPluginConfigSync,
+	saveUnifiedPluginConfig,
+} from "./unified-settings.js";
 
-const CONFIG_DIR = join(homedir(), ".opencode");
-const CONFIG_PATH = join(CONFIG_DIR, "codex-multi-auth-config.json");
-const LEGACY_CONFIG_PATH = join(CONFIG_DIR, "openai-codex-auth-config.json");
+const CONFIG_DIR = getCodexMultiAuthDir();
+const CONFIG_PATH = join(CONFIG_DIR, "config.json");
+const LEGACY_CODEX_CONFIG_PATH = join(getCodexHomeDir(), "codex-multi-auth-config.json");
+const LEGACY_OPENCODE_CONFIG_PATH = join(
+	getLegacyOpenCodeDir(),
+	"codex-multi-auth-config.json",
+);
+const LEGACY_OPENCODE_AUTH_CONFIG_PATH = join(
+	getLegacyOpenCodeDir(),
+	"openai-codex-auth-config.json",
+);
 const TUI_COLOR_PROFILES = new Set(["truecolor", "ansi16", "ansi256"]);
 const TUI_GLYPH_MODES = new Set(["ascii", "unicode", "auto"]);
 const UNSUPPORTED_CODEX_POLICIES = new Set(["strict", "fallback"]);
 const emittedConfigWarnings = new Set<string>();
+const configSaveQueues = new Map<string, Promise<void>>();
+const RETRYABLE_FS_CODES = new Set(["EBUSY", "EPERM"]);
 
 export type UnsupportedCodexPolicy = "strict" | "fallback";
 
@@ -27,6 +42,22 @@ export function __resetConfigWarningCacheForTests(): void {
 	emittedConfigWarnings.clear();
 }
 
+/**
+ * Determines the filesystem path to the plugin configuration file, preferring an explicit environment override and falling back to current and legacy locations.
+ *
+ * The lookup order is:
+ * 1. `CODEX_MULTI_AUTH_CONFIG_PATH` environment variable (if set and non-empty)
+ * 2. current CONFIG_PATH
+ * 3. legacy Codex/OpenCode config locations (with a one-time migration warning)
+ *
+ * Concurrency: the function is synchronous and relies on the filesystem state at call time; callers should handle concurrent config writes externally.
+ *
+ * Windows: path existence checks use Node's filesystem semantics (case sensitivity and symlink behavior follow the host OS).
+ *
+ * Security: the returned path may reference files containing sensitive tokens; callers MUST redact or avoid logging full paths or file contents.
+ *
+ * @returns The resolved config file path as a string, or `null` if no config file was found.
+ */
 function resolvePluginConfigPath(): string | null {
 	const envPath = (process.env.CODEX_MULTI_AUTH_CONFIG_PATH ?? "").trim();
 	if (envPath.length > 0) {
@@ -37,12 +68,28 @@ function resolvePluginConfigPath(): string | null {
 		return CONFIG_PATH;
 	}
 
-	if (existsSync(LEGACY_CONFIG_PATH)) {
+	if (existsSync(LEGACY_CODEX_CONFIG_PATH)) {
+		logConfigWarnOnce(
+			`Using legacy config path ${LEGACY_CODEX_CONFIG_PATH}. ` +
+				`Please migrate to ${CONFIG_PATH}.`,
+		);
+		return LEGACY_CODEX_CONFIG_PATH;
+	}
+
+	if (existsSync(LEGACY_OPENCODE_CONFIG_PATH)) {
+		logConfigWarnOnce(
+			`Using legacy OpenCode config path ${LEGACY_OPENCODE_CONFIG_PATH}. ` +
+				`Please migrate to ${CONFIG_PATH}.`,
+		);
+		return LEGACY_OPENCODE_CONFIG_PATH;
+	}
+
+	if (existsSync(LEGACY_OPENCODE_AUTH_CONFIG_PATH)) {
 		logConfigWarnOnce(
-			`Using legacy config path ${LEGACY_CONFIG_PATH}. ` +
+			`Using legacy OpenCode config path ${LEGACY_OPENCODE_AUTH_CONFIG_PATH}. ` +
 				`Please migrate to ${CONFIG_PATH}.`,
 		);
-		return LEGACY_CONFIG_PATH;
+		return LEGACY_OPENCODE_AUTH_CONFIG_PATH;
 	}
 
 	return null;
@@ -52,7 +99,7 @@ function resolvePluginConfigPath(): string | null {
  * Default plugin configuration
  * CODEX_MODE is enabled by default for better Codex CLI parity
  */
-const DEFAULT_CONFIG: PluginConfig = {
+export const DEFAULT_PLUGIN_CONFIG: PluginConfig = {
 	codexMode: true,
 	codexTuiV2: true,
 	codexTuiColorProfile: "truecolor",
@@ -80,25 +127,63 @@ const DEFAULT_CONFIG: PluginConfig = {
 	pidOffsetEnabled: false,
 	fetchTimeoutMs: 60_000,
 	streamStallTimeoutMs: 45_000,
+	liveAccountSync: true,
+	liveAccountSyncDebounceMs: 250,
+	liveAccountSyncPollMs: 2_000,
+	sessionAffinity: true,
+	sessionAffinityTtlMs: 20 * 60_000,
+	sessionAffinityMaxEntries: 512,
+	proactiveRefreshGuardian: true,
+	proactiveRefreshIntervalMs: 60_000,
+	proactiveRefreshBufferMs: 5 * 60_000,
+	networkErrorCooldownMs: 6_000,
+	serverErrorCooldownMs: 4_000,
+	storageBackupEnabled: true,
+	preemptiveQuotaEnabled: true,
+	preemptiveQuotaRemainingPercent5h: 5,
+	preemptiveQuotaRemainingPercent7d: 5,
+	preemptiveQuotaMaxDeferralMs: 2 * 60 * 60_000,
 };
 
 /**
- * Load plugin configuration from ~/.opencode/codex-multi-auth-config.json
- * (with compatibility fallback to ~/.opencode/openai-codex-auth-config.json)
- * Falls back to defaults if file doesn't exist or is invalid
+ * Return a shallow copy of the default plugin configuration.
+ *
+ * Safe to call concurrently; performs no I/O and has no filesystem or Windows atomicity implications.
+ * The returned object may include placeholder fields for secrets or tokens — callers must redact sensitive values before logging or persisting.
+ *
+ * @returns A shallow copy of DEFAULT_PLUGIN_CONFIG
+ */
+export function getDefaultPluginConfig(): PluginConfig {
+	return { ...DEFAULT_PLUGIN_CONFIG };
+}
+
+/**
+ * Load the plugin configuration, merging validated user settings with defaults and applying legacy fallbacks.
+ *
+ * Attempts to read unified settings first; if absent, falls back to legacy per-user JSON files (UTF-8 BOM is stripped on Windows before parsing).
+ * Emits one-time warnings for validation or migration issues and avoids exposing sensitive tokens in logged messages.
+ * This function performs filesystem reads and may write a migrated unified config; callers should avoid concurrent writers to the same config paths.
  *
- * @returns Plugin configuration
+ * @returns The effective PluginConfig: a shallow merge of DEFAULT_PLUGIN_CONFIG with any validated user-provided settings
  */
 export function loadPluginConfig(): PluginConfig {
 	try {
-		const configPath = resolvePluginConfigPath();
-		if (!configPath) {
-			return DEFAULT_CONFIG;
+		const unifiedConfig = loadUnifiedPluginConfigSync();
+		let userConfig: unknown = unifiedConfig;
+		let sourceKind: "unified" | "file" = "unified";
+
+		if (!isRecord(userConfig)) {
+			const configPath = resolvePluginConfigPath();
+			if (!configPath) {
+				return { ...DEFAULT_PLUGIN_CONFIG };
+			}
+
+			const fileContent = readFileSync(configPath, "utf-8");
+			const normalizedFileContent = stripUtf8Bom(fileContent);
+			userConfig = JSON.parse(normalizedFileContent) as unknown;
+			sourceKind = "file";
 		}
 
-		const fileContent = readFileSync(configPath, "utf-8");
-		const normalizedFileContent = stripUtf8Bom(fileContent);
-		const userConfig = JSON.parse(normalizedFileContent) as unknown;
 		const hasFallbackEnvOverride =
 			process.env.CODEX_AUTH_FALLBACK_UNSUPPORTED_MODEL !== undefined ||
 			process.env.CODEX_AUTH_FALLBACK_GPT53_TO_GPT52 !== undefined;
@@ -123,8 +208,18 @@ export function loadPluginConfig(): PluginConfig {
 			);
 		}
 
+		if (
+			sourceKind === "file" &&
+			isRecord(userConfig) &&
+			(process.env.CODEX_MULTI_AUTH_CONFIG_PATH ?? "").trim().length === 0
+		) {
+			logConfigWarnOnce(
+				`Legacy config file is still in use; settings will migrate to ${getUnifiedSettingsPath()} on next save.`,
+			);
+		}
+
 		return {
-			...DEFAULT_CONFIG,
+			...DEFAULT_PLUGIN_CONFIG,
 			...(userConfig as Partial<PluginConfig>),
 		};
 	} catch (error) {
@@ -132,16 +227,174 @@ export function loadPluginConfig(): PluginConfig {
 		logConfigWarnOnce(
 			`Failed to load config from ${configPath}: ${(error as Error).message}`,
 		);
-		return DEFAULT_CONFIG;
+		return { ...DEFAULT_PLUGIN_CONFIG };
 	}
 }
 
+/**
+ * Remove a leading UTF‑8 byte order mark (BOM) from the given string if present.
+ *
+ * This is a pure, idempotent operation with no side effects. It is commonly used to normalize text read from files (including Windows-generated files) before JSON parsing or token redaction.
+ *
+ * @param content - The string to normalize
+ * @returns The input string without a leading UTF‑8 BOM; returns the original string if no BOM is present
+ */
 function stripUtf8Bom(content: string): string {
 	return content.charCodeAt(0) === 0xfeff ? content.slice(1) : content;
 }
 
+/**
+ * Determines whether a value is a non-null object that can be treated as a record.
+ *
+ * @param value - The value to test
+ * @returns `true` if `value` is a non-null object and can be treated as `Record<string, unknown>`, `false` otherwise.
+ */
 function isRecord(value: unknown): value is Record<string, unknown> {
-	return value !== null && typeof value === "object";
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function isRetryableFsError(error: unknown): boolean {
+	const code = (error as NodeJS.ErrnoException | undefined)?.code;
+	return typeof code === "string" && RETRYABLE_FS_CODES.has(code);
+}
+
+function sleep(ms: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function writeJsonFileAtomicWithRetry(
+	filePath: string,
+	payload: Record<string, unknown>,
+): Promise<void> {
+	const tempPath = `${filePath}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2, 8)}.tmp`;
+	await fs.mkdir(dirname(filePath), { recursive: true });
+	await fs.writeFile(tempPath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+	let renamed = false;
+	try {
+		for (let attempt = 0; attempt < 5; attempt += 1) {
+			try {
+				await fs.rename(tempPath, filePath);
+				renamed = true;
+				return;
+			} catch (error) {
+				if (!isRetryableFsError(error) || attempt >= 4) {
+					throw error;
+				}
+				await sleep(10 * 2 ** attempt);
+			}
+		}
+	} finally {
+		if (!renamed) {
+			try {
+				await fs.unlink(tempPath);
+			} catch {
+				// Best-effort temp cleanup.
+			}
+		}
+	}
+}
+
+async function withConfigSaveLock(path: string, task: () => Promise<void>): Promise<void> {
+	const previous = configSaveQueues.get(path) ?? Promise.resolve();
+	const queued = previous.catch(() => {}).then(task);
+	configSaveQueues.set(path, queued);
+	try {
+		await queued;
+	} finally {
+		if (configSaveQueues.get(path) === queued) {
+			configSaveQueues.delete(path);
+		}
+	}
+}
+
+/**
+ * Read and parse a JSON configuration file and return its top-level object when present and valid.
+ *
+ * This function tolerates transient read/parse failures caused by concurrent writers; callers should handle a `null` return as "unavailable". Log messages include the file path and error message — callers should avoid logging or displaying raw paths that may contain sensitive tokens without redaction. On Windows, path casing or exclusive file locks can make existing files temporarily unreadable.
+ *
+ * @param configPath - Filesystem path to the JSON config file. Concurrent writes may cause transient read/parse failures; callers should tolerate `null`. On Windows, path casing and exclusive locks can affect readability.
+ * @returns The parsed top-level JSON object as a Record<string, unknown> when the file exists and contains an object, or `null` if the file is missing, malformed, or could not be read.
+ */
+function readConfigRecordFromPath(configPath: string): Record<string, unknown> | null {
+	if (!existsSync(configPath)) return null;
+	try {
+		const fileContent = readFileSync(configPath, "utf-8");
+		const normalizedFileContent = stripUtf8Bom(fileContent);
+		const parsed = JSON.parse(normalizedFileContent) as unknown;
+		return isRecord(parsed) ? parsed : null;
+	} catch (error) {
+		logConfigWarnOnce(
+			`Failed to read config from ${configPath}: ${
+				error instanceof Error ? error.message : String(error)
+			}`,
+		);
+		return null;
+	}
+}
+
+/**
+ * Prepare a partial PluginConfig for persistence by removing undefined values,
+ * omitting non-finite numbers, and shallow-copying nested object records.
+ *
+ * @param config - Partial plugin configuration to sanitize before saving. Note: this function does not redact or mask secrets (tokens/credentials); callers must handle redaction before writing to disk.
+ * @returns A plain Record<string, unknown> suitable for JSON serialization: keys with `undefined` or non-finite numeric values are omitted and nested objects are shallow-copied.
+ *
+ * Concurrency: synchronous and side-effect free; callers are responsible for coordinating concurrent writes to the filesystem.
+ * Filesystem: no Windows-specific path normalization or filesystem I/O is performed by this function.
+ */
+function sanitizePluginConfigForSave(config: Partial<PluginConfig>): Record<string, unknown> {
+	const entries = Object.entries(config as Record<string, unknown>);
+	const sanitized: Record<string, unknown> = {};
+	for (const [key, value] of entries) {
+		if (value === undefined) continue;
+		if (typeof value === "number" && !Number.isFinite(value)) continue;
+		if (isRecord(value)) {
+			sanitized[key] = { ...value };
+			continue;
+		}
+		sanitized[key] = value;
+	}
+	return sanitized;
+}
+
+/**
+ * Persist a partial plugin configuration to disk, merging it with existing stored settings.
+ *
+ * This writes the sanitized patch either to the path specified by the CODEX_MULTI_AUTH_CONFIG_PATH
+ * environment variable (if set) or into the unified settings store. The function does not take
+ * internal locks; callers should avoid concurrent invocations that might overwrite each other.
+ * On Windows and other platforms the write behavior follows the Node.js filesystem semantics and may
+ * not be atomic across processes. Callers are responsible for redacting any sensitive values
+ * (tokens, secrets) before calling if redaction is required; this function writes merged values as-is.
+ *
+ * @param configPatch - Partial PluginConfig containing changes to persist; undefined fields are ignored.
+ * @returns void
+ */
+export async function savePluginConfig(configPatch: Partial<PluginConfig>): Promise<void> {
+	const sanitizedPatch = sanitizePluginConfigForSave(configPatch);
+	const envPath = (process.env.CODEX_MULTI_AUTH_CONFIG_PATH ?? "").trim();
+
+	if (envPath.length > 0) {
+		await withConfigSaveLock(envPath, async () => {
+			const merged = {
+				...(readConfigRecordFromPath(envPath) ?? {}),
+				...sanitizedPatch,
+			};
+			await writeJsonFileAtomicWithRetry(envPath, merged);
+		});
+		return;
+	}
+
+	const unifiedPath = getUnifiedSettingsPath();
+	await withConfigSaveLock(unifiedPath, async () => {
+		const unifiedConfig = loadUnifiedPluginConfigSync();
+		const legacyPath = unifiedConfig ? null : resolvePluginConfigPath();
+		const merged = {
+			...(unifiedConfig ?? (legacyPath ? readConfigRecordFromPath(legacyPath) : null) ?? {}),
+			...sanitizedPatch,
+		};
+		await saveUnifiedPluginConfig(merged);
+	});
 }
 
 /**
@@ -169,6 +422,19 @@ function parseStringEnv(value: string | undefined): string | undefined {
 	return trimmed.length > 0 ? trimmed : undefined;
 }
 
+/**
+ * Resolves a boolean configuration value, preferring an explicit environment variable.
+ *
+ * Checks the environment variable named by `envName` first (using the module's boolean parsing rules);
+ * if present, that value is returned. Otherwise returns `configValue` when defined, or `defaultValue`.
+ *
+ * This function is synchronous, has no filesystem interactions, and does not log or expose token values.
+ *
+ * @param envName - Name of the environment variable to check (e.g., "CODEX_FEATURE_FLAG")
+ * @param configValue - Value from the plugin configuration, used when the env var is not set
+ * @param defaultValue - Fallback value used when neither env nor config provide a value
+ * @returns `true` or `false` according to the resolution order: environment → config → default
+ */
 function resolveBooleanSetting(
 	envName: string,
 	configValue: boolean | undefined,
@@ -179,22 +445,41 @@ function resolveBooleanSetting(
 	return configValue ?? defaultValue;
 }
 
+/**
+ * Resolve a numeric setting using an environment override, then a config value, then a default, and clamp the result to optional bounds.
+ *
+ * This function prefers a numeric value from the environment variable named by `envName`, falls back to `configValue`, then to `defaultValue`, and enforces inclusive `options.min`/`options.max` when provided. It is safe to call concurrently (reads only from `process.env`), performs no filesystem I/O (including on Windows), and does not emit or log secrets or tokens; callers should handle any redaction of sensitive values before logging.
+ *
+ * @param envName - Environment variable name to check for an override
+ * @param configValue - Configuration-provided numeric value to use if the environment variable is absent
+ * @param defaultValue - Fallback numeric value used when neither env nor config provide one
+ * @param options - Optional inclusive `min` and `max` bounds to clamp the resolved value
+ * @returns The resolved number, clamped to `options.min`/`options.max` when specified
+ */
 function resolveNumberSetting(
 	envName: string,
 	configValue: number | undefined,
 	defaultValue: number,
-	options?: { min?: number },
+	options?: { min?: number; max?: number },
 ): number {
 	const envValue = parseNumberEnv(process.env[envName]);
 	const candidate = envValue ?? configValue ?? defaultValue;
-	const min = options?.min;
-	if (min !== undefined) {
-		return Math.max(min, candidate);
-	}
-	// istanbul ignore next -- dead code: all callers pass { min: ... }
-	return candidate;
+	const min = options?.min ?? Number.NEGATIVE_INFINITY;
+	const max = options?.max ?? Number.POSITIVE_INFINITY;
+	return Math.max(min, Math.min(max, candidate));
 }
 
+/**
+ * Choose the effective string value from an environment variable, a config value, or a default while enforcing a whitelist.
+ *
+ * This reads the environment variable named by `envName` once and prefers it if its trimmed/lowercased value is in `allowedValues`; otherwise it falls back to `configValue` if allowed, then to `defaultValue`. Concurrency: concurrent mutations to `process.env` may change the outcome. Filesystem: performs no filesystem I/O and has no platform-specific behavior (including Windows). Secrets: the function does not redact or log values; callers are responsible for handling sensitive values.
+ *
+ * @param envName - Name of the environment variable to consult first
+ * @param configValue - Configuration-provided value to use if the environment value is absent or not allowed
+ * @param defaultValue - Fallback value used when neither environment nor config provide an allowed value
+ * @param allowedValues - Set of permitted values; only values in this set will be accepted
+ * @returns The resolved value, guaranteed to be one of the values in `allowedValues`
+ */
 function resolveStringSetting<T extends string>(
 	envName: string,
 	configValue: T | undefined,
@@ -464,6 +749,14 @@ export function getPidOffsetEnabled(pluginConfig: PluginConfig): boolean {
 	);
 }
 
+/**
+ * Resolve the HTTP fetch timeout to use for account/token requests.
+ *
+ * Concurrency: value is read-only and safe to use concurrently; callers must enforce timeout usage in their request code. On Windows, filesystem-derived overrides (via env or config file) are subject to typical path encoding and newline semantics. Configuration values may contain sensitive tokens elsewhere; this function only returns a numeric timeout and does not expose or log secrets.
+ *
+ * @param pluginConfig - Plugin configuration object to read the `fetchTimeoutMs` fallback from
+ * @returns The resolved fetch timeout in milliseconds (at least 1000)
+ */
 export function getFetchTimeoutMs(pluginConfig: PluginConfig): number {
 	return resolveNumberSetting(
 		"CODEX_AUTH_FETCH_TIMEOUT_MS",
@@ -473,6 +766,14 @@ export function getFetchTimeoutMs(pluginConfig: PluginConfig): number {
 	);
 }
 
+/**
+ * Compute the effective stream stall timeout used to detect stalled streams.
+ *
+ * This value applies across concurrent operations and should be treated as a global per-process timeout; callers may use it from multiple async contexts without additional synchronization. The function performs no filesystem I/O and has no special Windows filesystem behavior. Returned values do not contain or reveal any tokens and no redaction is performed by this function.
+ *
+ * @param pluginConfig - Plugin configuration that may contain a `streamStallTimeoutMs` override
+ * @returns The effective stream stall timeout in milliseconds; at least 1000 ms, defaults to 45000 ms
+ */
 export function getStreamStallTimeoutMs(pluginConfig: PluginConfig): number {
 	return resolveNumberSetting(
 		"CODEX_AUTH_STREAM_STALL_TIMEOUT_MS",
@@ -481,3 +782,310 @@ export function getStreamStallTimeoutMs(pluginConfig: PluginConfig): number {
 		{ min: 1_000 },
 	);
 }
+
+/**
+ * Determine whether live account synchronization is enabled.
+ *
+ * Respects the environment override `CODEX_AUTH_LIVE_ACCOUNT_SYNC`, falls back to
+ * `pluginConfig.liveAccountSync` when present, and defaults to `true`. This accessor performs no
+ * filesystem operations (behaves the same on Windows paths) and does not mutate or log token or
+ * credential material; callers are responsible for concurrency and must redact tokens before
+ * logging or persisting them.
+ *
+ * @param pluginConfig - The plugin configuration object used as the non-environment fallback
+ * @returns `true` if live account synchronization is enabled, `false` otherwise
+ */
+export function getLiveAccountSync(pluginConfig: PluginConfig): boolean {
+	return resolveBooleanSetting(
+		"CODEX_AUTH_LIVE_ACCOUNT_SYNC",
+		pluginConfig.liveAccountSync,
+		true,
+	);
+}
+
+/**
+ * Get the debounce interval, in milliseconds, used when synchronizing live accounts.
+ *
+ * @param pluginConfig - Plugin configuration which may contain an override for the debounce value
+ * @returns The debounce interval in milliseconds; defaults to 250, and will be at least 50
+ *
+ * Concurrency: safe to call from multiple threads/tasks concurrently.
+ * Windows filesystem: value is independent of filesystem semantics.
+ * Token redaction: this value contains no secrets and is safe to log.
+ */
+export function getLiveAccountSyncDebounceMs(pluginConfig: PluginConfig): number {
+	return resolveNumberSetting(
+		"CODEX_AUTH_LIVE_ACCOUNT_SYNC_DEBOUNCE_MS",
+		pluginConfig.liveAccountSyncDebounceMs,
+		250,
+		{ min: 50 },
+	);
+}
+
+/**
+ * Determines the polling interval (in milliseconds) used by live account synchronization.
+ *
+ * @param pluginConfig - The plugin configuration to read the setting from.
+ * @returns The effective poll interval in milliseconds; guaranteed to be at least 500.
+ *
+ * Notes:
+ * - Concurrency: this value is used to debounce/drive polling and should be treated as a minimum per-worker interval when multiple workers run concurrently.
+ * - Platform: value is independent of Windows filesystem semantics.
+ * - Secrets: the returned value contains no sensitive tokens and is safe for logging (no redaction required).
+ */
+export function getLiveAccountSyncPollMs(pluginConfig: PluginConfig): number {
+	return resolveNumberSetting(
+		"CODEX_AUTH_LIVE_ACCOUNT_SYNC_POLL_MS",
+		pluginConfig.liveAccountSyncPollMs,
+		2_000,
+		{ min: 500 },
+	);
+}
+
+/**
+ * Indicates whether session affinity is enabled.
+ *
+ * Reads the `sessionAffinity` value from `pluginConfig` and allows an environment
+ * override via `CODEX_AUTH_SESSION_AFFINITY`. Safe for concurrent reads, unaffected
+ * by Windows filesystem semantics, and does not expose or log authentication tokens.
+ *
+ * @param pluginConfig - The plugin configuration to consult for the setting
+ * @returns `true` if session affinity is enabled, `false` otherwise
+ */
+export function getSessionAffinity(pluginConfig: PluginConfig): boolean {
+	return resolveBooleanSetting(
+		"CODEX_AUTH_SESSION_AFFINITY",
+		pluginConfig.sessionAffinity,
+		true,
+	);
+}
+
+/**
+ * Get the session-affinity time-to-live in milliseconds.
+ *
+ * Reads CODEX_AUTH_SESSION_AFFINITY_TTL_MS from the environment if present, otherwise uses
+ * `pluginConfig.sessionAffinityTtlMs`, falling back to 20 minutes. The returned value is
+ * clamped to a minimum of 1000 ms.
+ *
+ * This function performs no filesystem I/O, is safe for concurrent callers, and does not
+ * read or emit any token or secret material (suitable for logging without redaction).
+ * Because it does no file operations, there are no Windows filesystem semantics to consider.
+ *
+ * @param pluginConfig - The plugin configuration to read the setting from
+ * @returns The effective session-affinity TTL in milliseconds (minimum 1000)
+ */
+export function getSessionAffinityTtlMs(pluginConfig: PluginConfig): number {
+	return resolveNumberSetting(
+		"CODEX_AUTH_SESSION_AFFINITY_TTL_MS",
+		pluginConfig.sessionAffinityTtlMs,
+		20 * 60_000,
+		{ min: 1_000 },
+	);
+}
+
+/**
+ * Determine the configured maximum number of session-affinity entries.
+ *
+ * @param pluginConfig - The plugin configuration to read the `sessionAffinityMaxEntries` setting from.
+ * @returns The effective maximum number of affinity entries (minimum 8, default 512).
+ *
+ * Concurrency: value is used for in-memory sizing and should be safe for concurrent use by runtime components.
+ * Filesystem: value is runtime-only and unaffected by Windows filesystem semantics.
+ * Security: this setting contains no secrets and is safe to log; it does not include tokens or credentials.
+ */
+export function getSessionAffinityMaxEntries(pluginConfig: PluginConfig): number {
+	return resolveNumberSetting(
+		"CODEX_AUTH_SESSION_AFFINITY_MAX_ENTRIES",
+		pluginConfig.sessionAffinityMaxEntries,
+		512,
+		{ min: 8 },
+	);
+}
+
+/**
+ * Controls whether the proactive refresh guardian is enabled.
+ *
+ * When enabled, background refreshes may run concurrently; callers should assume safe concurrent access.
+ * Configuration respects cross-platform semantics (including Windows filesystem behavior) when persisting or migrating settings.
+ * Any tokens or sensitive values observed during refresh operations are redacted from logs and persisted records.
+ *
+ * @param pluginConfig - The plugin configuration object to read the setting from
+ * @returns `true` if the proactive refresh guardian is enabled, `false` otherwise.
+ */
+export function getProactiveRefreshGuardian(pluginConfig: PluginConfig): boolean {
+	return resolveBooleanSetting(
+		"CODEX_AUTH_PROACTIVE_GUARDIAN",
+		pluginConfig.proactiveRefreshGuardian,
+		true,
+	);
+}
+
+/**
+ * Determines the proactive refresh guardian interval in milliseconds.
+ *
+ * Uses the environment override `CODEX_AUTH_PROACTIVE_GUARDIAN_INTERVAL_MS` if present; otherwise uses
+ * the configured `pluginConfig.proactiveRefreshIntervalMs` or the default of 60000 ms. The resulting
+ * value is constrained to be at least 5000 ms.
+ *
+ * Concurrency assumption: callers may be invoked from multiple timers/workers concurrently.
+ * Windows filesystem and token-redaction concerns do not affect this getter.
+ *
+ * @param pluginConfig - Plugin configuration used as the fallback source for the interval value
+ * @returns The proactive refresh interval in milliseconds (>= 5000)
+ */
+export function getProactiveRefreshIntervalMs(pluginConfig: PluginConfig): number {
+	return resolveNumberSetting(
+		"CODEX_AUTH_PROACTIVE_GUARDIAN_INTERVAL_MS",
+		pluginConfig.proactiveRefreshIntervalMs,
+		60_000,
+		{ min: 5_000 },
+	);
+}
+
+/**
+ * Get the proactive refresh guardian buffer interval in milliseconds.
+ *
+ * @param pluginConfig - Plugin configuration object; `proactiveRefreshBufferMs` may override the default
+ * @returns The buffer interval in milliseconds: at least 30000, default 300000
+ *
+ * Concurrency: this value is shared across concurrent proactive-refresh workers and should be treated as a global timing setting.
+ * Windows filesystem: not related to filesystem behavior.
+ * Token redaction: environment values and config contents may be redacted in logs and diagnostics.
+ */
+export function getProactiveRefreshBufferMs(pluginConfig: PluginConfig): number {
+	return resolveNumberSetting(
+		"CODEX_AUTH_PROACTIVE_GUARDIAN_BUFFER_MS",
+		pluginConfig.proactiveRefreshBufferMs,
+		5 * 60_000,
+		{ min: 30_000 },
+	);
+}
+
+/**
+ * Get the network error cooldown interval used before retrying network operations.
+ *
+ * @param pluginConfig - Plugin configuration to read override values from
+ * @returns The cooldown interval in milliseconds (greater than or equal to 0)
+ *
+ * Concurrency: callers may read and cache this value; it is read-only at call time.
+ * Windows filesystem: no platform-specific filesystem behavior affects this setting.
+ * Token redaction: this function does not expose or log sensitive tokens.
+ */
+export function getNetworkErrorCooldownMs(pluginConfig: PluginConfig): number {
+	return resolveNumberSetting(
+		"CODEX_AUTH_NETWORK_ERROR_COOLDOWN_MS",
+		pluginConfig.networkErrorCooldownMs,
+		6_000,
+		{ min: 0 },
+	);
+}
+
+/**
+ * Get the cooldown duration in milliseconds to apply after a server error.
+ *
+ * Callers may invoke this concurrently; the returned value is read-only and safe for concurrent use.
+ * This function performs no filesystem access and is unaffected by Windows path semantics.
+ * It does not log or expose secrets — environment-derived values are treated as configuration, not token data.
+ *
+ * @param pluginConfig - Plugin configuration used to resolve the setting
+ * @returns The cooldown in milliseconds to use after a server error (minimum 0, default 4000)
+ */
+export function getServerErrorCooldownMs(pluginConfig: PluginConfig): number {
+	return resolveNumberSetting(
+		"CODEX_AUTH_SERVER_ERROR_COOLDOWN_MS",
+		pluginConfig.serverErrorCooldownMs,
+		4_000,
+		{ min: 0 },
+	);
+}
+
+/**
+ * Determines whether periodic storage backups are enabled.
+ *
+ * When enabled, background backup tasks may run concurrently; backups follow platform filesystem semantics (including Windows path behavior), and persisted backup data will have sensitive tokens redacted.
+ *
+ * @param pluginConfig - The plugin configuration to read the setting from
+ * @returns `true` if storage backup is enabled, `false` otherwise
+ */
+export function getStorageBackupEnabled(pluginConfig: PluginConfig): boolean {
+	return resolveBooleanSetting(
+		"CODEX_AUTH_STORAGE_BACKUP_ENABLED",
+		pluginConfig.storageBackupEnabled,
+		true,
+	);
+}
+
+/**
+ * Determines whether preemptive quota checks are enabled.
+ *
+ * Safe to call concurrently; this function does not access the filesystem (no Windows-specific behavior)
+ * and does not expose or log any authentication tokens.
+ *
+ * @param pluginConfig - Plugin configuration to read the preemptive quota setting from
+ * @returns `true` if preemptive quota is enabled, `false` otherwise
+ */
+export function getPreemptiveQuotaEnabled(pluginConfig: PluginConfig): boolean {
+	return resolveBooleanSetting(
+		"CODEX_AUTH_PREEMPTIVE_QUOTA_ENABLED",
+		pluginConfig.preemptiveQuotaEnabled,
+		true,
+	);
+}
+
+/**
+ * Get the configured preemptive-quota remaining percentage for 5-hour windows.
+ *
+ * @param pluginConfig - Plugin configuration to read the setting from. The value may be overridden by the CODEX_AUTH_PREEMPTIVE_QUOTA_5H_REMAINING_PCT environment variable; environment override semantics are the same on Windows. Safe to call concurrently. The returned value does not contain sensitive tokens and requires no redaction.
+ * @returns The percentage (0–100) used as the preemptive quota threshold for 5-hour intervals.
+ */
+export function getPreemptiveQuotaRemainingPercent5h(pluginConfig: PluginConfig): number {
+	return resolveNumberSetting(
+		"CODEX_AUTH_PREEMPTIVE_QUOTA_5H_REMAINING_PCT",
+		pluginConfig.preemptiveQuotaRemainingPercent5h,
+		5,
+		{ min: 0, max: 100 },
+	);
+}
+
+/**
+ * Determine the percentage of quota to reserve for the 7-day window.
+ *
+ * Resolves the effective value from the environment variable `CODEX_AUTH_PREEMPTIVE_QUOTA_7D_REMAINING_PCT`,
+ * then from `pluginConfig.preemptiveQuotaRemainingPercent7d`, falling back to `5` if unset, and clamps the result
+ * to the inclusive range `0`–`100`.
+ *
+ * Concurrent reads are safe. Behavior is independent of Windows filesystem semantics. No sensitive tokens are included
+ * or returned by this function.
+ *
+ * @param pluginConfig - Plugin configuration object used as a fallback when the environment variable is not set
+ * @returns The reserved quota percentage for the 7-day window, an integer between `0` and `100`
+ */
+export function getPreemptiveQuotaRemainingPercent7d(pluginConfig: PluginConfig): number {
+	return resolveNumberSetting(
+		"CODEX_AUTH_PREEMPTIVE_QUOTA_7D_REMAINING_PCT",
+		pluginConfig.preemptiveQuotaRemainingPercent7d,
+		5,
+		{ min: 0, max: 100 },
+	);
+}
+
+/**
+ * Get the configured maximum deferral time (in milliseconds) for preemptive quota checks.
+ *
+ * Reads an environment override or the plugin configuration and enforces a minimum of 1000 ms.
+ *
+ * @param pluginConfig - Plugin configuration object to read the setting from
+ * @returns The maximum deferral interval in milliseconds
+ *
+ * Concurrency: concurrent config writers may not be observed immediately by readers.
+ * Filesystem note: config persistence/visibility may differ on Windows vs POSIX filesystems.
+ * Security: the returned value contains no sensitive tokens and is safe to log.
+ */
+export function getPreemptiveQuotaMaxDeferralMs(pluginConfig: PluginConfig): number {
+	return resolveNumberSetting(
+		"CODEX_AUTH_PREEMPTIVE_QUOTA_MAX_DEFERRAL_MS",
+		pluginConfig.preemptiveQuotaMaxDeferralMs,
+		2 * 60 * 60_000,
+		{ min: 1_000 },
+	);
+}
diff --git a/lib/dashboard-settings.ts b/lib/dashboard-settings.ts
new file mode 100644
index 00000000..d4dbdb1a
--- /dev/null
+++ b/lib/dashboard-settings.ts
@@ -0,0 +1,461 @@
+import { existsSync, promises as fs } from "node:fs";
+import { join } from "node:path";
+import { getCodexMultiAuthDir } from "./runtime-paths.js";
+import { logWarn } from "./logger.js";
+import { sleep } from "./utils.js";
+import {
+	getUnifiedSettingsPath,
+	loadUnifiedDashboardSettings,
+	saveUnifiedDashboardSettings,
+} from "./unified-settings.js";
+
+export type DashboardThemePreset = "green" | "blue";
+export type DashboardAccentColor = "green" | "cyan" | "blue" | "yellow";
+export type DashboardAccountSortMode = "manual" | "ready-first";
+export type DashboardLayoutMode = "compact-details" | "expanded-rows";
+export type DashboardFocusStyle = "row-invert";
+
+export interface DashboardDisplaySettings {
+	showPerAccountRows: boolean;
+	showQuotaDetails: boolean;
+	showForecastReasons: boolean;
+	showRecommendations: boolean;
+	showLiveProbeNotes: boolean;
+	actionAutoReturnMs?: number;
+	actionPauseOnKey?: boolean;
+	menuAutoFetchLimits?: boolean;
+	menuSortEnabled?: boolean;
+	menuSortMode?: DashboardAccountSortMode;
+	menuSortPinCurrent?: boolean;
+	menuSortQuickSwitchVisibleRow?: boolean;
+	uiThemePreset?: DashboardThemePreset;
+	uiAccentColor?: DashboardAccentColor;
+	menuShowStatusBadge?: boolean;
+	menuShowCurrentBadge?: boolean;
+	menuShowLastUsed?: boolean;
+	menuShowQuotaSummary?: boolean;
+	menuShowQuotaCooldown?: boolean;
+	menuShowFetchStatus?: boolean;
+	menuShowDetailsForUnselectedRows?: boolean;
+	menuLayoutMode?: DashboardLayoutMode;
+	menuQuotaTtlMs?: number;
+	menuFocusStyle?: DashboardFocusStyle;
+	menuHighlightCurrentRow?: boolean;
+	menuStatuslineFields?: DashboardStatuslineField[];
+}
+
+export type DashboardStatuslineField = "last-used" | "limits" | "status";
+
+export const DASHBOARD_DISPLAY_SETTINGS_VERSION = 1 as const;
+
+export const DEFAULT_DASHBOARD_DISPLAY_SETTINGS: DashboardDisplaySettings = {
+	showPerAccountRows: true,
+	showQuotaDetails: true,
+	showForecastReasons: true,
+	showRecommendations: true,
+	showLiveProbeNotes: true,
+	actionAutoReturnMs: 2_000,
+	actionPauseOnKey: true,
+	menuAutoFetchLimits: true,
+	menuSortEnabled: true,
+	menuSortMode: "ready-first",
+	menuSortPinCurrent: false,
+	menuSortQuickSwitchVisibleRow: true,
+	uiThemePreset: "green",
+	uiAccentColor: "green",
+	menuShowStatusBadge: true,
+	menuShowCurrentBadge: true,
+	menuShowLastUsed: true,
+	menuShowQuotaSummary: true,
+	menuShowQuotaCooldown: true,
+	menuShowFetchStatus: true,
+	menuShowDetailsForUnselectedRows: false,
+	menuLayoutMode: "compact-details",
+	menuQuotaTtlMs: 5 * 60_000,
+	menuFocusStyle: "row-invert",
+	menuHighlightCurrentRow: true,
+	menuStatuslineFields: ["last-used", "limits", "status"],
+};
+
+const DASHBOARD_SETTINGS_PATH = join(getCodexMultiAuthDir(), "dashboard-settings.json");
+const RETRYABLE_READ_CODES = new Set(["EBUSY", "EPERM", "EAGAIN"]);
+const LEGACY_READ_MAX_ATTEMPTS = 4;
+const LEGACY_READ_BASE_DELAY_MS = 20;
+
+/**
+ * Checks whether a value is a non-null object that can be treated as a string-keyed record.
+ *
+ * @param value - Value to test
+ * @returns `true` if `value` is an object and not `null` (narrowed to `Record<string, unknown>`), `false` otherwise.
+ */
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function isRetryableReadError(error: unknown): boolean {
+	const code = (error as NodeJS.ErrnoException | undefined)?.code;
+	return typeof code === "string" && RETRYABLE_READ_CODES.has(code);
+}
+
+async function readLegacySettingsFile(path: string): Promise<string> {
+	let lastError: unknown;
+	for (let attempt = 0; attempt < LEGACY_READ_MAX_ATTEMPTS; attempt += 1) {
+		try {
+			return await fs.readFile(path, "utf8");
+		} catch (error) {
+			if (!isRetryableReadError(error) || attempt + 1 >= LEGACY_READ_MAX_ATTEMPTS) {
+				throw error;
+			}
+			lastError = error;
+			await sleep(LEGACY_READ_BASE_DELAY_MS * 2 ** attempt);
+		}
+	}
+	throw lastError instanceof Error ? lastError : new Error("Failed to read legacy dashboard settings");
+}
+
+/**
+ * Coerces a value to a boolean, using a provided fallback when the input is not a boolean.
+ *
+ * @param value - The input to evaluate; only `true` and `false` are accepted as boolean values
+ * @param fallback - The boolean to return when `value` is not a boolean
+ * @returns The boolean `value` if it is a boolean, otherwise `fallback`
+ */
+function normalizeBoolean(value: unknown, fallback: boolean): boolean {
+	return typeof value === "boolean" ? value : fallback;
+}
+
+/**
+ * Normalize an input value into a dashboard theme preset.
+ *
+ * @param value - Untrusted input to coerce to a theme preset
+ * @returns `"blue"` if `value` is exactly `"blue"`, `"green"` otherwise
+ */
+function normalizeThemePreset(value: unknown): DashboardThemePreset {
+	return value === "blue" ? "blue" : "green";
+}
+
+/**
+ * Normalize an input value into an allowed dashboard accent color, defaulting to green.
+ *
+ * @param value - Input value to coerce into an accent color
+ * @returns `'cyan'`, `'blue'`, or `'yellow'` if `value` matches one of those strings; otherwise `'green'`
+ */
+function normalizeAccentColor(value: unknown): DashboardAccentColor {
+	switch (value) {
+		case "cyan":
+			return "cyan";
+		case "blue":
+			return "blue";
+		case "yellow":
+			return "yellow";
+		default:
+			return "green";
+	}
+}
+
+/**
+ * Validate a dashboard layout mode, allowing only "expanded-rows".
+ *
+ * @param value - Candidate value to validate as a layout mode
+ * @param fallback - Value to return when `value` is not `"expanded-rows"`
+ * @returns `"expanded-rows"` if `value` strictly equals that string, otherwise `fallback`
+ */
+function normalizeLayoutMode(
+	value: unknown,
+	fallback: DashboardLayoutMode,
+): DashboardLayoutMode {
+	return value === "expanded-rows" ? "expanded-rows" : fallback;
+}
+
+/**
+ * Coerces an arbitrary value into the dashboard focus style.
+ *
+ * @param value - Value to coerce into a DashboardFocusStyle
+ * @returns The normalized focus style; always `'row-invert'`.
+ */
+function normalizeFocusStyle(value: unknown): DashboardFocusStyle {
+	return value === "row-invert" ? "row-invert" : "row-invert";
+}
+
+/**
+ * Normalize a numeric TTL (milliseconds) into a validated, rounded, bounded integer.
+ *
+ * @param value - The input value to normalize; if not a finite number, the function falls back.
+ * @param fallback - Value returned when `value` is not a finite number.
+ * @returns A rounded integer number of milliseconds between 60,000 and 1,800,000 (30 minutes), or `fallback` if `value` is invalid.
+ */
+function normalizeQuotaTtlMs(value: unknown, fallback: number): number {
+	if (typeof value !== "number" || !Number.isFinite(value)) return fallback;
+	const rounded = Math.round(value);
+	return Math.max(60_000, Math.min(30 * 60_000, rounded));
+}
+
+/**
+ * Normalize a candidate account sort mode to a known mode.
+ *
+ * @param value - The input value to validate as an account sort mode
+ * @param fallback - Mode to use if `value` is not a recognized sort mode
+ * @returns The validated `DashboardAccountSortMode`: `ready-first` or `manual` if `value` matches, otherwise `fallback`
+ */
+function normalizeAccountSortMode(value: unknown, fallback: DashboardAccountSortMode): DashboardAccountSortMode {
+	if (value === "ready-first" || value === "manual") {
+		return value;
+	}
+	return fallback;
+}
+
+/**
+ * Coerces an untrusted value to an integer millisecond timeout between 0 and 10000.
+ *
+ * This rounds and clamps numeric input; if the input is not a finite number the provided
+ * fallback is returned. Safe to call concurrently. Filesystem semantics, Windows atomicity,
+ * and unified-settings token redaction are not applicable to this operation.
+ *
+ * @param value - The untrusted input to normalize
+ * @param fallback - The numeric fallback to use when `value` is invalid
+ * @returns A millisecond timeout value between 0 and 10000 inclusive
+ */
+function normalizeAutoReturnMs(value: unknown, fallback: number): number {
+	if (typeof value !== "number" || !Number.isFinite(value)) return fallback;
+	const rounded = Math.round(value);
+	return Math.max(0, Math.min(10_000, rounded));
+}
+
+/**
+ * Coerces an arbitrary value into a deduplicated, order-preserving list of allowed statusline fields.
+ *
+ * @param value - The input to normalize; may be any value. Non-string entries, unknown fields, and duplicates are discarded.
+ * @returns An array of `DashboardStatuslineField` in their original order with duplicates removed. If the input is not an array or yields no valid fields, returns the default statusline fields.
+ */
+function normalizeStatuslineFields(value: unknown): DashboardStatuslineField[] {
+	const defaultFields = [...(DEFAULT_DASHBOARD_DISPLAY_SETTINGS.menuStatuslineFields ?? [])];
+	if (!Array.isArray(value)) return defaultFields;
+
+	const allowed = new Set<DashboardStatuslineField>(["last-used", "limits", "status"]);
+	const fields: DashboardStatuslineField[] = [];
+	for (const entry of value) {
+		if (typeof entry !== "string") continue;
+		if (!allowed.has(entry as DashboardStatuslineField)) continue;
+		const typed = entry as DashboardStatuslineField;
+		if (!fields.includes(typed)) {
+			fields.push(typed);
+		}
+	}
+
+	return fields.length > 0 ? fields : defaultFields;
+}
+
+/**
+ * Convert a DashboardDisplaySettings object into a plain record suitable for JSON serialization and persistence.
+ *
+ * @param value - The dashboard display settings to serialize
+ * @returns A shallow Record<string, unknown> containing the same keys and values as `value`, ready for JSON encoding
+ *
+ * Notes:
+ * - This function performs no I/O and is safe to call concurrently.
+ * - It does not perform any token redaction or platform-specific path normalization; behavior is identical across platforms (including Windows).
+ */
+function toJsonRecord(value: DashboardDisplaySettings): Record<string, unknown> {
+	const record: Record<string, unknown> = {};
+	for (const [key, fieldValue] of Object.entries(value)) {
+		record[key] = fieldValue;
+	}
+	return record;
+}
+
+/**
+ * Filesystem path to the unified dashboard settings file.
+ *
+ * This path is the canonical location used by the load/save helpers. Callers should assume the file may be concurrently modified by other processes and use atomic write strategies when persisting. On Windows the returned path may contain backslashes; redact any sensitive tokens before logging or external reporting.
+ *
+ * @returns The absolute path to the unified dashboard settings file.
+ */
+export function getDashboardSettingsPath(): string {
+	return getUnifiedSettingsPath();
+}
+
+/**
+ * Normalize an untrusted value into a complete, validated DashboardDisplaySettings object.
+ *
+ * Produces a settings object where missing or invalid fields are replaced with sensible defaults,
+ * layout-derived fields are resolved, numeric values are clamped to allowed ranges, and enumerations
+ * are coerced to allowed values.
+ *
+ * Concurrency: pure and deterministic; safe to call concurrently. This function performs no I/O,
+ * so Windows filesystem semantics do not apply. It does not perform token redaction or any
+ * sensitive-data filtering.
+ *
+ * @param value - The input to normalize (may be any type, typically parsed JSON or a partial settings record)
+ * @returns A DashboardDisplaySettings object with all fields validated and defaulted
+ */
+export function normalizeDashboardDisplaySettings(
+	value: unknown,
+): DashboardDisplaySettings {
+	if (!isRecord(value)) {
+		return { ...DEFAULT_DASHBOARD_DISPLAY_SETTINGS };
+	}
+	const derivedLayoutMode = normalizeLayoutMode(
+		value.menuLayoutMode,
+		value.menuShowDetailsForUnselectedRows === true ? "expanded-rows" : "compact-details",
+	);
+	return {
+		showPerAccountRows: normalizeBoolean(
+			value.showPerAccountRows,
+			DEFAULT_DASHBOARD_DISPLAY_SETTINGS.showPerAccountRows,
+		),
+		showQuotaDetails: normalizeBoolean(
+			value.showQuotaDetails,
+			DEFAULT_DASHBOARD_DISPLAY_SETTINGS.showQuotaDetails,
+		),
+		showForecastReasons: normalizeBoolean(
+			value.showForecastReasons,
+			DEFAULT_DASHBOARD_DISPLAY_SETTINGS.showForecastReasons,
+		),
+		showRecommendations: normalizeBoolean(
+			value.showRecommendations,
+			DEFAULT_DASHBOARD_DISPLAY_SETTINGS.showRecommendations,
+		),
+		showLiveProbeNotes: normalizeBoolean(
+			value.showLiveProbeNotes,
+			DEFAULT_DASHBOARD_DISPLAY_SETTINGS.showLiveProbeNotes,
+		),
+		actionAutoReturnMs: normalizeAutoReturnMs(
+			value.actionAutoReturnMs,
+			DEFAULT_DASHBOARD_DISPLAY_SETTINGS.actionAutoReturnMs ?? 2_000,
+		),
+		actionPauseOnKey: normalizeBoolean(
+			value.actionPauseOnKey,
+			DEFAULT_DASHBOARD_DISPLAY_SETTINGS.actionPauseOnKey ?? true,
+		),
+		menuAutoFetchLimits: normalizeBoolean(
+			value.menuAutoFetchLimits,
+			DEFAULT_DASHBOARD_DISPLAY_SETTINGS.menuAutoFetchLimits ?? true,
+		),
+		menuSortEnabled: normalizeBoolean(
+			value.menuSortEnabled,
+			DEFAULT_DASHBOARD_DISPLAY_SETTINGS.menuSortEnabled ?? false,
+		),
+		menuSortMode: normalizeAccountSortMode(
+			value.menuSortMode,
+			DEFAULT_DASHBOARD_DISPLAY_SETTINGS.menuSortMode ?? "ready-first",
+		),
+		menuSortPinCurrent: normalizeBoolean(
+			value.menuSortPinCurrent,
+			DEFAULT_DASHBOARD_DISPLAY_SETTINGS.menuSortPinCurrent ?? true,
+		),
+		menuSortQuickSwitchVisibleRow: normalizeBoolean(
+			value.menuSortQuickSwitchVisibleRow,
+			DEFAULT_DASHBOARD_DISPLAY_SETTINGS.menuSortQuickSwitchVisibleRow ?? true,
+		),
+		uiThemePreset: normalizeThemePreset(
+			value.uiThemePreset,
+		),
+		uiAccentColor: normalizeAccentColor(
+			value.uiAccentColor,
+		),
+		menuShowStatusBadge: normalizeBoolean(
+			value.menuShowStatusBadge,
+			DEFAULT_DASHBOARD_DISPLAY_SETTINGS.menuShowStatusBadge ?? true,
+		),
+		menuShowCurrentBadge: normalizeBoolean(
+			value.menuShowCurrentBadge,
+			DEFAULT_DASHBOARD_DISPLAY_SETTINGS.menuShowCurrentBadge ?? true,
+		),
+		menuShowLastUsed: normalizeBoolean(
+			value.menuShowLastUsed,
+			DEFAULT_DASHBOARD_DISPLAY_SETTINGS.menuShowLastUsed ?? true,
+		),
+		menuShowQuotaSummary: normalizeBoolean(
+			value.menuShowQuotaSummary,
+			DEFAULT_DASHBOARD_DISPLAY_SETTINGS.menuShowQuotaSummary ?? true,
+		),
+		menuShowQuotaCooldown: normalizeBoolean(
+			value.menuShowQuotaCooldown,
+			DEFAULT_DASHBOARD_DISPLAY_SETTINGS.menuShowQuotaCooldown ?? true,
+		),
+		menuShowFetchStatus: normalizeBoolean(
+			value.menuShowFetchStatus,
+			DEFAULT_DASHBOARD_DISPLAY_SETTINGS.menuShowFetchStatus ?? true,
+		),
+		menuShowDetailsForUnselectedRows: derivedLayoutMode === "expanded-rows",
+		menuLayoutMode: derivedLayoutMode,
+		menuQuotaTtlMs: normalizeQuotaTtlMs(
+			value.menuQuotaTtlMs,
+			DEFAULT_DASHBOARD_DISPLAY_SETTINGS.menuQuotaTtlMs ?? 5 * 60_000,
+		),
+		menuFocusStyle: normalizeFocusStyle(value.menuFocusStyle),
+		menuHighlightCurrentRow: normalizeBoolean(
+			value.menuHighlightCurrentRow,
+			DEFAULT_DASHBOARD_DISPLAY_SETTINGS.menuHighlightCurrentRow ?? true,
+		),
+		menuStatuslineFields: normalizeStatuslineFields(value.menuStatuslineFields),
+	};
+}
+
+/**
+ * Load and return the normalized dashboard display settings, migrating legacy settings when present.
+ *
+ * Attempts to read unified settings first; if absent, loads legacy dashboard-settings.json, normalizes
+ * its contents, and tries to migrate the normalized result to the unified settings store. On any read,
+ * parse, or validation error, or if no settings are found, returns the built-in defaults.
+ *
+ * @returns The normalized DashboardDisplaySettings to apply.
+ *
+ * @remarks
+ * - Concurrency: callers may race with other processes performing migration or writes; callers should
+ *   not assume exclusive access and should tolerate eventual consistency.
+ * - Filesystem (Windows): legacy-path checks use case-insensitive filesystem semantics implicitly; ensure
+ *   any external tooling accounts for that when placing or removing legacy files.
+ * - Token handling: persisted settings are stored as-is; remove or redact any sensitive tokens from
+ *   settings before calling this function if they must not be written unmodified to persistent stores.
+ */
+export async function loadDashboardDisplaySettings(): Promise<DashboardDisplaySettings> {
+	const unifiedSettings = await loadUnifiedDashboardSettings();
+	if (unifiedSettings) {
+		return normalizeDashboardDisplaySettings(unifiedSettings);
+	}
+
+	if (!existsSync(DASHBOARD_SETTINGS_PATH)) {
+		return { ...DEFAULT_DASHBOARD_DISPLAY_SETTINGS };
+	}
+
+	try {
+		const raw = await readLegacySettingsFile(DASHBOARD_SETTINGS_PATH);
+		const parsed = JSON.parse(raw) as unknown;
+		if (!isRecord(parsed)) {
+			return { ...DEFAULT_DASHBOARD_DISPLAY_SETTINGS };
+		}
+		const normalized = normalizeDashboardDisplaySettings(parsed.settings);
+		try {
+			await saveUnifiedDashboardSettings(toJsonRecord(normalized));
+		} catch {
+			// Keep legacy fallback behavior even if migration write fails.
+		}
+		return normalized;
+	} catch (error) {
+		logWarn(
+			`Failed to load dashboard settings from ${DASHBOARD_SETTINGS_PATH}: ${
+				error instanceof Error ? error.message : String(error)
+			}`,
+		);
+		return { ...DEFAULT_DASHBOARD_DISPLAY_SETTINGS };
+	}
+}
+
+/**
+ * Persist normalized dashboard display settings to the unified settings store.
+ *
+ * Normalizes `settings` and writes the resulting record via the unified settings API.
+ * Concurrent callers may race and overwrite each other; callers should serialize updates
+ * when strong write ordering is required. On Windows, underlying filesystem writes may
+ * not be atomic across processes. Any sensitive tokens or secrets present in settings
+ * are written as provided; callers must remove or redact sensitive values before saving.
+ *
+ * @param settings - The dashboard display settings to normalize and save
+ */
+export async function saveDashboardDisplaySettings(
+	settings: DashboardDisplaySettings,
+): Promise<void> {
+	const normalized = normalizeDashboardDisplaySettings(settings);
+	await saveUnifiedDashboardSettings(toJsonRecord(normalized));
+}
diff --git a/lib/entitlement-cache.ts b/lib/entitlement-cache.ts
new file mode 100644
index 00000000..b4464294
--- /dev/null
+++ b/lib/entitlement-cache.ts
@@ -0,0 +1,156 @@
+import { createLogger } from "./logger.js";
+
+const log = createLogger("entitlement-cache");
+
+export interface EntitlementBlock {
+	model: string;
+	blockedUntil: number;
+	reason: "unsupported-model" | "plan-entitlement";
+	updatedAt: number;
+}
+
+export interface EntitlementCacheSnapshot {
+	accounts: Record<string, EntitlementBlock[]>;
+}
+
+const DEFAULT_BLOCK_TTL_MS = 30 * 60_000;
+const MAX_ACCOUNT_BUCKETS = 512;
+
+export interface EntitlementAccountRef {
+	accountId?: string;
+	email?: string;
+	index?: number;
+}
+
+/**
+ * Produce a normalized model identifier suitable for cache keys and comparisons.
+ *
+ * Trims and lowercases the input, uses the final path segment if a slash is present,
+ * and removes common variant suffixes such as `-none`, `-minimal`, `-low`, `-medium`, `-high`, and `-xhigh`.
+ *
+ * @param model - The raw model string to normalize; may be undefined or empty.
+ * @returns The simplified model identifier, or `null` if `model` is missing or empty after trimming.
+ */
+function normalizeModel(model: string | undefined): string | null {
+	if (!model) return null;
+	const trimmed = model.trim().toLowerCase();
+	if (!trimmed) return null;
+	const stripped = trimmed.includes("/") ? (trimmed.split("/").pop() ?? trimmed) : trimmed;
+	return stripped.replace(/-(none|minimal|low|medium|high|xhigh)$/i, "");
+}
+
+/**
+ * Derives a stable cache key for an entitlement account reference.
+ *
+ * Produces one of three deterministic keys:
+ * - `id:<trimmed accountId>` when `accountId` is present,
+ * - `email:<lowercased trimmed email>` when `email` is present and no `accountId`,
+ * - `idx:<non-negative integer>` otherwise (index defaults to 0).
+ *
+ * This function is pure and concurrency-safe; it performs no I/O and is not affected by Windows filesystem semantics. It does not redact secrets or tokens — values are only trimmed and, for emails, lowercased.
+ *
+ * @param ref - Reference identifying an account (may include `accountId`, `email`, or `index`)
+ * @returns A deterministic string key prefixed with `id:`, `email:`, or `idx:` as described above
+ */
+export function resolveEntitlementAccountKey(ref: EntitlementAccountRef): string {
+	const accountId = typeof ref.accountId === "string" ? ref.accountId.trim() : "";
+	if (accountId) return `id:${accountId}`;
+	const email = typeof ref.email === "string" ? ref.email.trim().toLowerCase() : "";
+	if (email) return `email:${email}`;
+	const index = Number.isFinite(ref.index) ? Math.max(0, Math.floor(ref.index ?? 0)) : 0;
+	return `idx:${index}`;
+}
+
+export class EntitlementCache {
+	private readonly blocksByAccount = new Map<string, Map<string, EntitlementBlock>>();
+
+	markBlocked(
+		accountKey: string,
+		model: string,
+		reason: EntitlementBlock["reason"],
+		ttlMs = DEFAULT_BLOCK_TTL_MS,
+		now = Date.now(),
+	): void {
+		const normalizedModel = normalizeModel(model);
+		if (!accountKey || !normalizedModel) return;
+		const normalizedTtlMs =
+			typeof ttlMs === "number" && Number.isFinite(ttlMs)
+				? Math.max(1_000, Math.floor(ttlMs))
+				: DEFAULT_BLOCK_TTL_MS;
+		if (this.blocksByAccount.size >= MAX_ACCOUNT_BUCKETS && !this.blocksByAccount.has(accountKey)) {
+			const first = this.blocksByAccount.keys().next().value;
+			if (typeof first === "string") this.blocksByAccount.delete(first);
+		}
+		const existing = this.blocksByAccount.get(accountKey) ?? new Map<string, EntitlementBlock>();
+		existing.set(normalizedModel, {
+			model: normalizedModel,
+			blockedUntil: now + normalizedTtlMs,
+			reason,
+			updatedAt: now,
+		});
+		this.blocksByAccount.set(accountKey, existing);
+	}
+
+	clear(accountKey: string, model?: string): void {
+		if (!accountKey) return;
+		if (!model) {
+			this.blocksByAccount.delete(accountKey);
+			return;
+		}
+		const normalizedModel = normalizeModel(model);
+		if (!normalizedModel) return;
+		const accountBlocks = this.blocksByAccount.get(accountKey);
+		if (!accountBlocks) return;
+		accountBlocks.delete(normalizedModel);
+		if (accountBlocks.size === 0) this.blocksByAccount.delete(accountKey);
+	}
+
+	isBlocked(accountKey: string, model: string, now = Date.now()): { blocked: boolean; waitMs: number; reason?: EntitlementBlock["reason"] } {
+		const normalizedModel = normalizeModel(model);
+		if (!accountKey || !normalizedModel) return { blocked: false, waitMs: 0 };
+		const accountBlocks = this.blocksByAccount.get(accountKey);
+		if (!accountBlocks) return { blocked: false, waitMs: 0 };
+		const block = accountBlocks.get(normalizedModel);
+		if (!block) return { blocked: false, waitMs: 0 };
+		if (block.blockedUntil <= now) {
+			accountBlocks.delete(normalizedModel);
+			if (accountBlocks.size === 0) this.blocksByAccount.delete(accountKey);
+			return { blocked: false, waitMs: 0 };
+		}
+		return {
+			blocked: true,
+			waitMs: Math.max(0, block.blockedUntil - now),
+			reason: block.reason,
+		};
+	}
+
+	prune(now = Date.now()): number {
+		let removed = 0;
+		for (const [accountKey, blocks] of this.blocksByAccount.entries()) {
+			for (const [model, block] of blocks.entries()) {
+				if (block.blockedUntil <= now) {
+					blocks.delete(model);
+					removed += 1;
+				}
+			}
+			if (blocks.size === 0) {
+				this.blocksByAccount.delete(accountKey);
+			}
+		}
+		if (removed > 0) {
+			log.debug("Pruned entitlement cache", { removed });
+		}
+		return removed;
+	}
+
+	snapshot(now = Date.now()): EntitlementCacheSnapshot {
+		this.prune(now);
+		const accounts: Record<string, EntitlementBlock[]> = {};
+		for (const [accountKey, blocks] of this.blocksByAccount.entries()) {
+			accounts[accountKey] = Array.from(blocks.values())
+				.map((block) => ({ ...block }))
+				.sort((a, b) => a.model.localeCompare(b.model));
+		}
+		return { accounts };
+	}
+}
diff --git a/lib/forecast.ts b/lib/forecast.ts
new file mode 100644
index 00000000..30455746
--- /dev/null
+++ b/lib/forecast.ts
@@ -0,0 +1,317 @@
+import { formatAccountLabel, formatWaitTime } from "./accounts.js";
+import type { CodexQuotaSnapshot } from "./quota-probe.js";
+import type { AccountMetadataV3 } from "./storage.js";
+import type { TokenFailure } from "./types.js";
+
+export type ForecastAvailability = "ready" | "delayed" | "unavailable";
+export type ForecastRiskLevel = "low" | "medium" | "high";
+
+export interface ForecastAccountInput {
+	index: number;
+	account: AccountMetadataV3;
+	isCurrent: boolean;
+	now: number;
+	refreshFailure?: TokenFailure;
+	liveQuota?: CodexQuotaSnapshot;
+}
+
+export interface ForecastAccountResult {
+	index: number;
+	label: string;
+	isCurrent: boolean;
+	availability: ForecastAvailability;
+	riskScore: number;
+	riskLevel: ForecastRiskLevel;
+	waitMs: number;
+	reasons: string[];
+	hardFailure: boolean;
+	disabled: boolean;
+}
+
+export interface ForecastRecommendation {
+	recommendedIndex: number | null;
+	reason: string;
+}
+
+export interface ForecastSummary {
+	total: number;
+	ready: number;
+	delayed: number;
+	unavailable: number;
+	highRisk: number;
+}
+
+function clampRisk(score: number): number {
+	if (!Number.isFinite(score)) return 100;
+	return Math.max(0, Math.min(100, Math.round(score)));
+}
+
+function maskEmail(value: string): string {
+	const atIndex = value.indexOf("@");
+	if (atIndex <= 0) return "***@***";
+	const local = value.slice(0, atIndex);
+	const domain = value.slice(atIndex + 1);
+	const domainParts = domain.split(".");
+	const tld = domainParts.pop() ?? "";
+	const prefix = local.slice(0, Math.min(2, local.length));
+	return `${prefix}***@***.${tld || "***"}`;
+}
+
+function redactEmails(value: string): string {
+	return value.replace(
+		/[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g,
+		(match) => maskEmail(match),
+	);
+}
+
+function redactSensitiveReason(value: string): string {
+	return redactEmails(
+		value
+			.replace(/Bearer\s+\S+/gi, "Bearer ***")
+			.replace(/\b(sk-[A-Za-z0-9]{10,})\b/g, "***"),
+	);
+}
+
+function summarizeRefreshFailure(failure: TokenFailure): string {
+	const reasonCode = failure.reason?.trim();
+	if (reasonCode && reasonCode.length > 0) {
+		const statusCode = typeof failure.statusCode === "number" ? ` (${failure.statusCode})` : "";
+		return `${reasonCode}${statusCode}`;
+	}
+	const fallback = failure.message?.trim() || "refresh failed";
+	return redactSensitiveReason(fallback).slice(0, 160);
+}
+
+function getRiskLevel(score: number): ForecastRiskLevel {
+	if (score >= 75) return "high";
+	if (score >= 40) return "medium";
+	return "low";
+}
+
+function getRateLimitResetTimeForFamily(
+	account: AccountMetadataV3,
+	now: number,
+	family = "codex",
+): number | null {
+	const times = account.rateLimitResetTimes;
+	if (!times) return null;
+
+	let minReset: number | null = null;
+	const prefix = `${family}:`;
+	for (const [key, value] of Object.entries(times)) {
+		if (typeof value !== "number") continue;
+		if (value <= now) continue;
+		if (key !== family && !key.startsWith(prefix)) continue;
+		if (minReset === null || value < minReset) {
+			minReset = value;
+		}
+	}
+	return minReset;
+}
+
+function getLiveQuotaWaitMs(snapshot: CodexQuotaSnapshot, now: number): number {
+	const waits: number[] = [];
+	for (const resetAt of [snapshot.primary.resetAtMs, snapshot.secondary.resetAtMs]) {
+		if (typeof resetAt !== "number") continue;
+		if (!Number.isFinite(resetAt)) continue;
+		const remaining = resetAt - now;
+		if (remaining > 0) waits.push(remaining);
+	}
+	return waits.length > 0 ? Math.max(...waits) : 0;
+}
+
+function describeQuotaUsage(label: string, usedPercent: number | undefined): string | null {
+	if (typeof usedPercent !== "number" || !Number.isFinite(usedPercent)) return null;
+	const bounded = Math.max(0, Math.min(100, Math.round(usedPercent)));
+	return `${label} quota ${bounded}% used`;
+}
+
+export function isHardRefreshFailure(failure: TokenFailure): boolean {
+	if (failure.reason === "missing_refresh") return true;
+	if (failure.statusCode === 401) return true;
+	if (failure.statusCode !== 400) return false;
+	const message = (failure.message ?? "").toLowerCase();
+	return (
+		message.includes("invalid_grant") ||
+		message.includes("invalid refresh") ||
+		message.includes("token has been revoked")
+	);
+}
+
+function appendWaitReason(reasons: string[], prefix: string, waitMs: number): void {
+	if (waitMs <= 0) return;
+	reasons.push(`${prefix} ${formatWaitTime(waitMs)}`);
+}
+
+export function evaluateForecastAccount(input: ForecastAccountInput): ForecastAccountResult {
+	const { account, index, isCurrent, now } = input;
+	const reasons: string[] = [];
+	let availability: ForecastAvailability = "ready";
+	let riskScore = isCurrent ? -5 : 0;
+	let waitMs = 0;
+	let hardFailure = false;
+	const disabled = account.enabled === false;
+
+	if (disabled) {
+		availability = "unavailable";
+		riskScore += 95;
+		reasons.push("account is disabled");
+	}
+
+	if (input.refreshFailure) {
+		const hard = isHardRefreshFailure(input.refreshFailure);
+		hardFailure = hard;
+		const detail = summarizeRefreshFailure(input.refreshFailure);
+		if (hard) {
+			availability = "unavailable";
+			riskScore += 90;
+			reasons.push(`hard auth failure: ${detail}`);
+		} else {
+			riskScore += 25;
+			reasons.push(`refresh warning: ${detail}`);
+		}
+	}
+
+	if (typeof account.coolingDownUntil === "number" && account.coolingDownUntil > now) {
+		const remaining = account.coolingDownUntil - now;
+		waitMs = Math.max(waitMs, remaining);
+		if (availability === "ready") availability = "delayed";
+		riskScore += 45;
+		appendWaitReason(reasons, "cooldown remaining", remaining);
+	}
+
+	const rateLimitResetAt = getRateLimitResetTimeForFamily(account, now, "codex");
+	if (typeof rateLimitResetAt === "number") {
+		const remaining = Math.max(0, rateLimitResetAt - now);
+		waitMs = Math.max(waitMs, remaining);
+		if (availability === "ready") availability = "delayed";
+		riskScore += 35;
+		appendWaitReason(reasons, "rate limit resets in", remaining);
+	}
+
+	const quota = input.liveQuota;
+	if (quota) {
+		const primaryUsed = quota.primary.usedPercent ?? 0;
+		const secondaryUsed = quota.secondary.usedPercent ?? 0;
+		const quotaPressure = quota.status === 429 || primaryUsed >= 90 || secondaryUsed >= 90;
+
+		if (quota.status === 429) {
+			availability = availability === "unavailable" ? "unavailable" : "delayed";
+			riskScore += 35;
+			reasons.push("live probe returned 429");
+		}
+		const liveWait = quotaPressure ? getLiveQuotaWaitMs(quota, now) : 0;
+		waitMs = Math.max(waitMs, liveWait);
+		if (liveWait > 0 && availability === "ready") {
+			availability = "delayed";
+		}
+
+		const primaryUsage = describeQuotaUsage("primary", quota.primary.usedPercent);
+		if (primaryUsage) reasons.push(primaryUsage);
+		const secondaryUsage = describeQuotaUsage("secondary", quota.secondary.usedPercent);
+		if (secondaryUsage) reasons.push(secondaryUsage);
+
+		if (primaryUsed >= 98 || secondaryUsed >= 98) {
+			riskScore += 55;
+		} else if (primaryUsed >= 90 || secondaryUsed >= 90) {
+			riskScore += 35;
+		} else if (primaryUsed >= 80 || secondaryUsed >= 80) {
+			riskScore += 20;
+		} else if (primaryUsed >= 70 || secondaryUsed >= 70) {
+			riskScore += 10;
+		}
+	}
+
+	const hasLastUsed = typeof account.lastUsed === "number" && Number.isFinite(account.lastUsed) && account.lastUsed > 0;
+	const lastUsedAge = hasLastUsed ? now - account.lastUsed : null;
+	if (lastUsedAge !== null && (!Number.isFinite(lastUsedAge) || lastUsedAge < 0)) {
+		riskScore += 5;
+	} else if (lastUsedAge !== null && lastUsedAge > 7 * 24 * 60 * 60 * 1000) {
+		riskScore += 10;
+	}
+
+	const finalRisk = clampRisk(riskScore);
+	return {
+		index,
+		label: redactEmails(formatAccountLabel(account, index)),
+		isCurrent,
+		availability,
+		riskScore: finalRisk,
+		riskLevel: getRiskLevel(finalRisk),
+		waitMs: Math.max(0, Math.floor(waitMs)),
+		reasons,
+		hardFailure,
+		disabled,
+	};
+}
+
+export function evaluateForecastAccounts(inputs: ForecastAccountInput[]): ForecastAccountResult[] {
+	return inputs.map((input) => evaluateForecastAccount(input));
+}
+
+function compareForecastResults(a: ForecastAccountResult, b: ForecastAccountResult): number {
+	if (a.availability !== b.availability) {
+		const rank: Record<ForecastAvailability, number> = {
+			ready: 0,
+			delayed: 1,
+			unavailable: 2,
+		};
+		return rank[a.availability] - rank[b.availability];
+	}
+
+	if (a.availability === "delayed" && b.availability === "delayed" && a.waitMs !== b.waitMs) {
+		return a.waitMs - b.waitMs;
+	}
+
+	if (a.riskScore !== b.riskScore) {
+		return a.riskScore - b.riskScore;
+	}
+
+	if (a.isCurrent !== b.isCurrent) {
+		return a.isCurrent ? -1 : 1;
+	}
+
+	return a.index - b.index;
+}
+
+export function recommendForecastAccount(results: ForecastAccountResult[]): ForecastRecommendation {
+	const candidates = results.filter((result) => !result.disabled && !result.hardFailure);
+	if (candidates.length === 0) {
+		return {
+			recommendedIndex: null,
+			reason: "No healthy accounts are available. Run `codex auth login` to add a fresh account.",
+		};
+	}
+
+	const sorted = [...candidates].sort(compareForecastResults);
+	const best = sorted[0];
+	if (!best) {
+		return {
+			recommendedIndex: null,
+			reason: "No recommendation available.",
+		};
+	}
+
+	if (best.availability === "ready") {
+		return {
+			recommendedIndex: best.index,
+			reason: `Lowest risk ready account (${best.riskLevel}, score ${best.riskScore}).`,
+		};
+	}
+
+	return {
+		recommendedIndex: best.index,
+		reason: `No account is immediately ready; pick shortest wait (${formatWaitTime(best.waitMs)}).`,
+	};
+}
+
+export function summarizeForecast(results: ForecastAccountResult[]): ForecastSummary {
+	return {
+		total: results.length,
+		ready: results.filter((result) => result.availability === "ready").length,
+		delayed: results.filter((result) => result.availability === "delayed").length,
+		unavailable: results.filter((result) => result.availability === "unavailable").length,
+		highRisk: results.filter((result) => result.riskLevel === "high").length,
+	};
+}
+
diff --git a/lib/index.ts b/lib/index.ts
index cdd3530b..0e259846 100644
--- a/lib/index.ts
+++ b/lib/index.ts
@@ -15,6 +15,16 @@ export * from "./circuit-breaker.js";
 export * from "./health.js";
 export * from "./table-formatter.js";
 export * from "./parallel-probe.js";
+export * from "./session-affinity.js";
+export * from "./live-account-sync.js";
+export * from "./refresh-guardian.js";
+export * from "./refresh-lease.js";
+export * from "./request/failure-policy.js";
+export * from "./entitlement-cache.js";
+export * from "./preemptive-quota-scheduler.js";
+export * from "./unified-settings.js";
+export * from "./capability-policy.js";
+export * from "./request/stream-failover.js";
 export * from "./codex-cli/state.js";
 export * from "./codex-cli/sync.js";
 export * from "./codex-cli/writer.js";
diff --git a/lib/live-account-sync.ts b/lib/live-account-sync.ts
new file mode 100644
index 00000000..245be892
--- /dev/null
+++ b/lib/live-account-sync.ts
@@ -0,0 +1,214 @@
+import { promises as fs, watch as fsWatch, type FSWatcher } from "node:fs";
+import { basename, dirname } from "node:path";
+import { createLogger } from "./logger.js";
+
+const log = createLogger("live-account-sync");
+
+export interface LiveAccountSyncOptions {
+	debounceMs?: number;
+	pollIntervalMs?: number;
+}
+
+export interface LiveAccountSyncSnapshot {
+	path: string | null;
+	running: boolean;
+	lastKnownMtimeMs: number | null;
+	lastSyncAt: number | null;
+	reloadCount: number;
+	errorCount: number;
+}
+
+/**
+ * Convert an fs.watch filename value to a UTF-8 string or null.
+ *
+ * @param filename - The value supplied by fs.watch listeners; may be a `string`, `Buffer`, or `null`. Buffers are decoded as UTF-8.
+ * @returns `filename` as a UTF-8 string, or `null` when the input is `null`.
+ */
+function normalizeFsWatchFilename(filename: string | Buffer | null): string | null {
+	if (filename === null) return null;
+	if (typeof filename === "string") return filename;
+	return filename.toString("utf-8");
+}
+
+/**
+ * Read the file modification time (mtime) for a given filesystem path in milliseconds.
+ *
+ * This is a point-in-time snapshot — the value may change immediately due to concurrent writes and callers
+ * should not assume stability across subsequent operations. On some platforms (notably Windows) timestamp
+ * resolution can be coarse; callers should account for that when comparing mtime values.
+ *
+ * Treat `path` as sensitive when logging: redact any tokens or secrets before emitting it.
+ *
+ * @param path - Filesystem path to inspect
+ * @returns The file's mtime in milliseconds, or `null` if the path does not exist or the mtime is not finite
+ */
+async function readMtimeMs(path: string): Promise<number | null> {
+	try {
+		const stats = await fs.stat(path);
+		return Number.isFinite(stats.mtimeMs) ? stats.mtimeMs : null;
+	} catch (error) {
+		const code = (error as NodeJS.ErrnoException).code;
+		if (code === "ENOENT" || code === "EBUSY" || code === "EACCES") return null;
+		throw error;
+	}
+}
+
+function summarizeWatchPath(path: string | null): string {
+	if (!path) return "<unknown>";
+	return basename(path);
+}
+
+/**
+ * Watches account storage and triggers a reload callback when file content
+ * changes. Uses fs.watch + polling fallback for Windows reliability.
+ */
+export class LiveAccountSync {
+	private readonly reload: () => Promise<void>;
+	private readonly debounceMs: number;
+	private readonly pollIntervalMs: number;
+	private watcher: FSWatcher | null = null;
+	private pollTimer: ReturnType<typeof setInterval> | null = null;
+	private debounceTimer: ReturnType<typeof setTimeout> | null = null;
+	private currentPath: string | null = null;
+	private running = false;
+	private lastKnownMtimeMs: number | null = null;
+	private lastSyncAt: number | null = null;
+	private reloadCount = 0;
+	private errorCount = 0;
+	private reloadInFlight: Promise<void> | null = null;
+
+	constructor(reload: () => Promise<void>, options: LiveAccountSyncOptions = {}) {
+		this.reload = reload;
+		this.debounceMs = Math.max(50, Math.floor(options.debounceMs ?? 250));
+		this.pollIntervalMs = Math.max(500, Math.floor(options.pollIntervalMs ?? 2_000));
+	}
+
+	async syncToPath(path: string): Promise<void> {
+		if (!path) return;
+		if (this.currentPath === path && this.running) return;
+		this.stop();
+
+		this.currentPath = path;
+		this.lastKnownMtimeMs = await readMtimeMs(path);
+		const targetDir = dirname(path);
+		const targetName = basename(path);
+
+		try {
+			this.watcher = fsWatch(targetDir, { persistent: false }, (_eventType, filename) => {
+				const name = normalizeFsWatchFilename(filename);
+				if (!name) {
+					this.scheduleReload("watch");
+					return;
+				}
+
+				if (name === targetName || name.startsWith(`${targetName}.`)) {
+					this.scheduleReload("watch");
+				}
+			});
+		} catch (error) {
+			this.errorCount += 1;
+			log.warn("Failed to start fs.watch for account storage", {
+				path: summarizeWatchPath(path),
+				error: error instanceof Error ? error.message : String(error),
+			});
+		}
+
+		this.pollTimer = setInterval(() => {
+			void this.pollOnce();
+		}, this.pollIntervalMs);
+		if (typeof this.pollTimer === "object" && "unref" in this.pollTimer && typeof this.pollTimer.unref === "function") {
+			this.pollTimer.unref();
+		}
+
+		this.running = true;
+	}
+
+	stop(): void {
+		this.running = false;
+		if (this.watcher) {
+			this.watcher.close();
+			this.watcher = null;
+		}
+		if (this.pollTimer) {
+			clearInterval(this.pollTimer);
+			this.pollTimer = null;
+		}
+		if (this.debounceTimer) {
+			clearTimeout(this.debounceTimer);
+			this.debounceTimer = null;
+		}
+	}
+
+	getSnapshot(): LiveAccountSyncSnapshot {
+		return {
+			path: this.currentPath,
+			running: this.running,
+			lastKnownMtimeMs: this.lastKnownMtimeMs,
+			lastSyncAt: this.lastSyncAt,
+			reloadCount: this.reloadCount,
+			errorCount: this.errorCount,
+		};
+	}
+
+	private scheduleReload(reason: "watch" | "poll"): void {
+		if (!this.running) return;
+		if (this.debounceTimer) {
+			clearTimeout(this.debounceTimer);
+		}
+		this.debounceTimer = setTimeout(() => {
+			void this.runReload(reason);
+		}, this.debounceMs);
+	}
+
+	private async pollOnce(): Promise<void> {
+		if (!this.running || !this.currentPath) return;
+		try {
+			const currentMtime = await readMtimeMs(this.currentPath);
+			if (currentMtime !== this.lastKnownMtimeMs) {
+				this.lastKnownMtimeMs = currentMtime;
+				this.scheduleReload("poll");
+			}
+		} catch (error) {
+			this.errorCount += 1;
+			log.debug("Live account sync poll failed", {
+				path: summarizeWatchPath(this.currentPath),
+				error: error instanceof Error ? error.message : String(error),
+			});
+		}
+	}
+
+	private async runReload(reason: "watch" | "poll"): Promise<void> {
+		if (!this.running || !this.currentPath) return;
+		const targetPath = this.currentPath;
+		if (this.reloadInFlight) {
+			await this.reloadInFlight;
+			return;
+		}
+
+		this.reloadInFlight = (async () => {
+			try {
+				await this.reload();
+				this.lastSyncAt = Date.now();
+				this.reloadCount += 1;
+				this.lastKnownMtimeMs = await readMtimeMs(targetPath);
+				log.debug("Reloaded account manager from live storage update", {
+					reason,
+					path: summarizeWatchPath(targetPath),
+				});
+			} catch (error) {
+				this.errorCount += 1;
+				log.warn("Live account sync reload failed", {
+					reason,
+					path: summarizeWatchPath(targetPath),
+					error: error instanceof Error ? error.message : String(error),
+				});
+			}
+		})();
+
+		try {
+			await this.reloadInFlight;
+		} finally {
+			this.reloadInFlight = null;
+		}
+	}
+}
diff --git a/lib/logger.ts b/lib/logger.ts
index efa96b81..c0a933ee 100644
--- a/lib/logger.ts
+++ b/lib/logger.ts
@@ -1,8 +1,8 @@
 import { writeFileSync, mkdirSync, existsSync } from "node:fs";
 import { join } from "node:path";
-import { homedir } from "node:os";
 import { randomUUID } from "node:crypto";
 import { PLUGIN_NAME } from "./constants.js";
+import { getCodexLogDir } from "./runtime-paths.js";
 
 export type LogLevel = "debug" | "info" | "warn" | "error";
 
@@ -121,7 +121,10 @@ export const REQUEST_BODY_LOGGING_ENABLED = process.env.CODEX_PLUGIN_LOG_BODIES
 export const DEBUG_ENABLED = process.env.DEBUG_CODEX_PLUGIN === "1" || LOGGING_ENABLED;
 export const LOG_LEVEL = parseLogLevel(process.env.CODEX_PLUGIN_LOG_LEVEL);
 const CONSOLE_LOG_ENABLED = process.env.CODEX_CONSOLE_LOG === "1";
-const LOG_DIR = join(homedir(), ".opencode", "logs", "codex-plugin");
+const LOG_DIR = join(getCodexLogDir(), "codex-plugin");
+const LOG_DIR_RETRYABLE_ERRORS = new Set(["EBUSY", "EPERM"]);
+const LOG_DIR_MAX_ATTEMPTS = 3;
+const LOG_DIR_RETRY_BASE_DELAY_MS = 10;
 
 let client: LogClient | null = null;
 let currentCorrelationId: string | null = null;
@@ -251,11 +254,40 @@ function formatDuration(ms: number): string {
 	return `${minutes}m ${seconds}s`;
 }
 
+function ensureLogDir(path: string): boolean {
+	for (let attempt = 0; attempt < LOG_DIR_MAX_ATTEMPTS; attempt += 1) {
+		try {
+			if (!existsSync(path)) {
+				mkdirSync(path, { recursive: true, mode: 0o700 });
+			}
+			return true;
+		} catch (error) {
+			const code = (error as NodeJS.ErrnoException).code ?? "";
+			const canRetry = LOG_DIR_RETRYABLE_ERRORS.has(code);
+			if (canRetry && attempt + 1 < LOG_DIR_MAX_ATTEMPTS) {
+				Atomics.wait(
+					new Int32Array(new SharedArrayBuffer(4)),
+					0,
+					0,
+					LOG_DIR_RETRY_BASE_DELAY_MS * 2 ** attempt,
+				);
+				continue;
+			}
+			logToConsole("warn", `[${PLUGIN_NAME}] Failed to ensure log directory`, {
+				path,
+				error: error instanceof Error ? error.message : String(error),
+			});
+			return false;
+		}
+	}
+	return false;
+}
+
 export function logRequest(stage: string, data: Record<string, unknown>): void {
 	if (!LOGGING_ENABLED) return;
 
-	if (!existsSync(LOG_DIR)) {
-		mkdirSync(LOG_DIR, { recursive: true, mode: 0o700 });
+	if (!ensureLogDir(LOG_DIR)) {
+		return;
 	}
 
 	const timestamp = new Date().toISOString();
diff --git a/lib/oauth-success.html b/lib/oauth-success.html
index 385a28d8..4af91d9e 100644
--- a/lib/oauth-success.html
+++ b/lib/oauth-success.html
@@ -1,712 +1,338 @@
-<!DOCTYPE html>
+<!doctype html>
 <html lang="en">
 <head>
-    <meta charset="UTF-8">
-    <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <title>OpenCode - Authentication Successful</title>
-    <link rel="preconnect" href="https://fonts.googleapis.com">
-    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
-    <link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:ital,wght@0,100;0,200;0,300;0,400;0,500;0,600;0,700;1,100;1,200;1,300;1,400;1,500;1,600;1,700&display=swap" rel="stylesheet">
-    <style>
-        * {
-            margin: 0;
-            padding: 0;
-            box-sizing: border-box;
-        }
-
-        body {
-            font-family: "IBM Plex Mono", monospace;
-            font-weight: 400;
-            background: #0a0a0a;
-            color: #B7B1B1;
-            overflow: hidden;
-            height: 100vh;
-            display: flex;
-            align-items: center;
-            justify-content: center;
-            position: relative;
-        }
-
-        /* Matrix rain background */
-        .matrix {
-            position: fixed;
-            top: 0;
-            left: 0;
-            width: 100%;
-            height: 100%;
-            z-index: 1;
-            opacity: 0.35;
-        }
-
-        /* Scan lines effect */
-        .scanline {
-            position: fixed;
-            top: 0;
-            left: 0;
-            width: 100%;
-            height: 100%;
-            background: linear-gradient(
-                transparent 50%,
-                rgba(0, 0, 0, 0.1) 50%
-            );
-            background-size: 100% 4px;
-            z-index: 2;
-            pointer-events: none;
-            animation: scan 8s linear infinite;
-        }
-
-        @keyframes scan {
-            0% { transform: translateY(0); }
-            100% { transform: translateY(4px); }
-        }
-
-        /* Vignette effect */
-        .vignette {
-            position: fixed;
-            top: 0;
-            left: 0;
-            width: 100%;
-            height: 100%;
-            box-shadow: inset 0 0 200px rgba(0, 0, 0, 0.8);
-            z-index: 2;
-            pointer-events: none;
-        }
-
-        .container {
-            width: 90%;
-            max-width: 650px;
-            text-align: center;
-            z-index: 10;
-            position: relative;
-            animation: fadeIn 0.8s ease-out;
-        }
-
-        @keyframes fadeIn {
-            from {
-                opacity: 0;
-                transform: scale(0.95);
-            }
-            to {
-                opacity: 1;
-                transform: scale(1);
-            }
-        }
-
-        .logo {
-            margin-bottom: 60px;
-            opacity: 0;
-            animation: logoEntrance 1.2s cubic-bezier(0.34, 1.56, 0.64, 1) 0.3s forwards;
-            position: relative;
-        }
-
-        @keyframes logoEntrance {
-            0% {
-                opacity: 0;
-                transform: translateY(-50px) rotateX(90deg);
-            }
-            100% {
-                opacity: 1;
-                transform: translateY(0) rotateX(0);
-            }
-        }
-
-        .logo svg {
-            width: 300px;
-            height: auto;
-            filter: drop-shadow(0 0 30px rgba(241, 236, 236, 0.3));
-            animation: pulse 3s ease-in-out infinite;
-        }
-
-        @keyframes pulse {
-            0%, 100% {
-                filter: drop-shadow(0 0 30px rgba(241, 236, 236, 0.3));
-            }
-            50% {
-                filter: drop-shadow(0 0 50px rgba(241, 236, 236, 0.5));
-            }
-        }
-
-        /* Glowing orb behind logo */
-        .logo::before {
-            content: '';
-            position: absolute;
-            top: 50%;
-            left: 50%;
-            transform: translate(-50%, -50%);
-            width: 200px;
-            height: 200px;
-            background: radial-gradient(circle, rgba(241, 236, 236, 0.1) 0%, transparent 70%);
-            border-radius: 50%;
-            animation: orbPulse 4s ease-in-out infinite;
-            z-index: -1;
-        }
-
-        @keyframes orbPulse {
-            0%, 100% {
-                transform: translate(-50%, -50%) scale(1);
-                opacity: 0.3;
-            }
-            50% {
-                transform: translate(-50%, -50%) scale(1.2);
-                opacity: 0.6;
-            }
-        }
-
-        .terminal-window {
-            background: rgba(26, 26, 26, 0.95);
-            backdrop-filter: blur(10px);
-            -webkit-backdrop-filter: blur(10px);
-            border: 1px solid rgba(75, 70, 70, 0.3);
-            border-radius: 12px;
-            margin: 30px 0;
-            opacity: 0;
-            animation: boxEntrance 0.8s cubic-bezier(0.34, 1.56, 0.64, 1) 0.6s forwards;
-            position: relative;
-            overflow: hidden;
-            box-shadow:
-                0 0 60px rgba(0, 0, 0, 0.5),
-                inset 0 1px 0 rgba(255, 255, 255, 0.05);
-        }
-
-        .terminal-header {
-            background: rgba(15, 15, 15, 0.9);
-            padding: 14px 18px;
-            display: flex;
-            align-items: center;
-            gap: 8px;
-            border-bottom: 1px solid rgba(75, 70, 70, 0.3);
-            position: relative;
-        }
-
-        .terminal-button {
-            width: 12px;
-            height: 12px;
-            border-radius: 50%;
-            transition: transform 0.2s;
-        }
-
-        .terminal-button:hover {
-            transform: scale(1.2);
-        }
-
-        .terminal-button.red {
-            background: #ff5f56;
-            box-shadow: 0 0 10px rgba(255, 95, 86, 0.3);
-            animation: pulse 2s infinite;
-        }
-
-        .terminal-button.yellow {
-            background: #ffbd2e;
-            box-shadow: 0 0 10px rgba(255, 189, 46, 0.3);
-            animation: pulse 2s infinite 0.3s;
-        }
-
-        .terminal-button.green {
-            background: #27c93f;
-            box-shadow: 0 0 10px rgba(39, 201, 63, 0.3);
-            animation: pulse 2s infinite 0.6s;
-        }
-
-        @keyframes pulse {
-            0%, 100% { opacity: 1; }
-            50% { opacity: 0.6; }
-        }
-
-        .terminal-title {
-            flex: 1;
-            text-align: center;
-            font-size: 12px;
-            color: #6a6565;
-            opacity: 0.8;
-            letter-spacing: 0.5px;
-        }
-
-        .status-box {
-            padding: 50px 40px;
-            position: relative;
-        }
-
-        @keyframes boxEntrance {
-            from {
-                opacity: 0;
-                transform: translateY(30px);
-            }
-            to {
-                opacity: 1;
-                transform: translateY(0);
-            }
-        }
-
-        /* Animated border gradient */
-        .terminal-window::before {
-            content: '';
-            position: absolute;
-            top: -2px;
-            left: -2px;
-            right: -2px;
-            bottom: -2px;
-            background: linear-gradient(
-                45deg,
-                transparent,
-                rgba(241, 236, 236, 0.1),
-                transparent,
-                rgba(241, 236, 236, 0.1)
-            );
-            background-size: 400% 400%;
-            border-radius: 12px;
-            z-index: -1;
-            animation: gradientShift 8s ease infinite;
-        }
-
-        @keyframes gradientShift {
-            0%, 100% { background-position: 0% 50%; }
-            50% { background-position: 100% 50%; }
-        }
-
-        .checkmark-container {
-            width: 100px;
-            height: 100px;
-            margin: 0 auto 40px;
-            position: relative;
-        }
-
-        .checkmark-circle {
-            width: 100px;
-            height: 100px;
-            border-radius: 50%;
-            border: 4px solid transparent;
-            display: flex;
-            align-items: center;
-            justify-content: center;
-            position: relative;
-            animation: circleAppear 0.6s ease-out 1s both;
-        }
-
-        @keyframes circleAppear {
-            from {
-                transform: scale(0) rotate(-180deg);
-                border-color: transparent;
-            }
-            to {
-                transform: scale(1) rotate(0);
-                border-color: #4B4646;
-            }
-        }
-
-        /* Spinning rings around checkmark */
-        .checkmark-circle::before,
-        .checkmark-circle::after {
-            content: '';
-            position: absolute;
-            width: 120%;
-            height: 120%;
-            border: 2px solid transparent;
-            border-top-color: rgba(241, 236, 236, 0.2);
-            border-radius: 50%;
-            animation: rotate 3s linear infinite;
-        }
-
-        .checkmark-circle::after {
-            width: 140%;
-            height: 140%;
-            border-top-color: rgba(183, 177, 177, 0.1);
-            animation: rotate 4s linear infinite reverse;
-        }
-
-        @keyframes rotate {
-            to { transform: rotate(360deg); }
-        }
-
-        .checkmark {
-            width: 35px;
-            height: 18px;
-            border-left: 5px solid #F1ECEC;
-            border-bottom: 5px solid #F1ECEC;
-            transform: rotate(-45deg) scale(0);
-            animation: checkmarkDraw 0.5s cubic-bezier(0.65, 0, 0.45, 1) 1.3s forwards;
-            filter: drop-shadow(0 0 10px rgba(241, 236, 236, 0.5));
-        }
-
-        @keyframes checkmarkDraw {
-            0% {
-                transform: rotate(-45deg) scale(0);
-            }
-            50% {
-                transform: rotate(-45deg) scale(1.1);
-            }
-            100% {
-                transform: rotate(-45deg) scale(1);
-            }
-        }
-
-        .title {
-            font-size: 32px;
-            color: #00ff41;
-            margin-bottom: 20px;
-            font-weight: 500;
-            letter-spacing: 1px;
-            text-shadow: 0 0 20px rgba(0, 255, 65, 0.5);
-            opacity: 0;
-            animation: fadeInUp 0.6s ease-out 1.8s forwards;
-        }
-
-        @keyframes fadeInUp {
-            from {
-                opacity: 0;
-                transform: translateY(20px);
-            }
-            to {
-                opacity: 1;
-                transform: translateY(0);
-            }
-        }
-
-        .message {
-            font-size: 16px;
-            color: #9a9595;
-            line-height: 1.8;
-            margin-bottom: 30px;
-            opacity: 0;
-            animation: fadeInUp 0.6s ease-out 2s forwards;
-        }
-
-        .terminal-output {
-            background: rgba(10, 10, 10, 0.6);
-            border: 1px solid rgba(75, 70, 70, 0.2);
-            border-radius: 8px;
-            padding: 25px;
-            text-align: left;
-            font-size: 14px;
-            line-height: 2;
-            margin-top: 25px;
-            position: relative;
-            overflow: hidden;
-        }
-
-        /* Terminal typing effect */
-        .terminal-output::before {
-            content: '';
-            position: absolute;
-            top: 0;
-            left: 0;
-            width: 100%;
-            height: 2px;
-            background: linear-gradient(90deg, transparent, #4B4646, transparent);
-            animation: scanProgress 2s ease-out 2.2s forwards;
-        }
-
-        @keyframes scanProgress {
-            from {
-                transform: translateX(-100%);
-            }
-            to {
-                transform: translateX(100%);
-            }
-        }
-
-        .terminal-line {
-            opacity: 0;
-            transform: translateX(-20px);
-            animation: terminalType 0.4s ease-out forwards;
-            display: flex;
-            align-items: center;
-            gap: 12px;
-        }
-
-        .terminal-line:nth-child(1) { animation-delay: 2.2s; }
-        .terminal-line:nth-child(2) { animation-delay: 2.4s; }
-        .terminal-line:nth-child(3) { animation-delay: 2.6s; }
-        .terminal-line:nth-child(4) { animation-delay: 2.8s; }
-
-        @keyframes terminalType {
-            to {
-                opacity: 1;
-                transform: translateX(0);
-            }
-        }
-
-        .prompt {
-            color: #6a6565;
-            font-weight: 500;
-        }
-
-        .success {
-            color: #B7B1B1;
-        }
-
-        .terminal-line::after {
-            content: '';
-            flex: 1;
-            height: 1px;
-            background: linear-gradient(90deg, rgba(75, 70, 70, 0.3), transparent);
-        }
-
-        .footer {
-            margin-top: 40px;
-            font-size: 14px;
-            color: #6a6565;
-            opacity: 0;
-            animation: fadeInUp 0.6s ease-out 3.2s forwards;
-            text-shadow: 0 0 10px rgba(106, 101, 101, 0.5);
-        }
-
-        .cursor {
-            display: inline-block;
-            width: 2px;
-            height: 16px;
-            background: #8a8585;
-            margin-left: 6px;
-            animation: blink 1s infinite;
-            box-shadow: 0 0 8px #8a8585;
-        }
-
-        @keyframes blink {
-            0%, 49% { opacity: 1; }
-            50%, 100% { opacity: 0; }
-        }
-
-        /* Floating particles */
-        .particle {
-            position: fixed;
-            width: 2px;
-            height: 2px;
-            background: rgba(183, 177, 177, 0.3);
-            border-radius: 50%;
-            pointer-events: none;
-            z-index: 5;
-            animation: float 8s linear infinite;
-        }
-
-        @keyframes float {
-            0% {
-                transform: translateY(100vh) translateX(0) scale(0);
-                opacity: 0;
-            }
-            10% {
-                opacity: 1;
-                transform: translateY(90vh) translateX(10px) scale(1);
-            }
-            90% {
-                opacity: 1;
-            }
-            100% {
-                transform: translateY(-10vh) translateX(-10px) scale(0);
-                opacity: 0;
-            }
-        }
-
-        /* Success glow effect */
-        @keyframes successGlow {
-            0%, 100% {
-                box-shadow:
-                    0 0 60px rgba(0, 0, 0, 0.5),
-                    inset 0 1px 0 rgba(255, 255, 255, 0.05);
-            }
-            50% {
-                box-shadow:
-                    0 0 80px rgba(241, 236, 236, 0.1),
-                    inset 0 1px 0 rgba(255, 255, 255, 0.05);
-            }
-        }
-
-        .terminal-window {
-            animation:
-                boxEntrance 0.8s cubic-bezier(0.34, 1.56, 0.64, 1) 0.6s forwards,
-                successGlow 4s ease-in-out 2s infinite;
-        }
-    </style>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width,initial-scale=1" />
+  <title>OpenAI Codex Sign-in Complete</title>
+  <style>
+    :root {
+      --bg: #040608;
+      --bg2: #0a1210;
+      --card: #0a0f0d;
+      --line: #1f3a2f;
+      --line-soft: #13261f;
+      --text: #e6f6ee;
+      --muted: #9ac3b1;
+      --green: #35d28a;
+      --green-strong: #13b06e;
+      --warn: #f2cc60;
+    }
+
+    * { box-sizing: border-box; }
+
+    html, body {
+      margin: 0;
+      width: 100%;
+      height: 100%;
+      font-family: Consolas, "Cascadia Mono", "SFMono-Regular", Menlo, Monaco, monospace;
+      background: radial-gradient(1300px 700px at 20% -10%, #0f2b21 0%, transparent 55%),
+                  radial-gradient(1000px 560px at 100% 0%, #0a2019 0%, transparent 60%),
+                  linear-gradient(180deg, var(--bg), var(--bg2));
+      color: var(--text);
+      overflow-x: hidden;
+      overflow-y: auto;
+    }
+
+    .grid {
+      position: fixed;
+      inset: 0;
+      background-image:
+        linear-gradient(to right, rgba(53, 210, 138, 0.06) 1px, transparent 1px),
+        linear-gradient(to bottom, rgba(53, 210, 138, 0.05) 1px, transparent 1px);
+      background-size: 28px 28px;
+      mask-image: radial-gradient(circle at center, black 35%, transparent 90%);
+      pointer-events: none;
+      animation: drift 16s linear infinite;
+    }
+
+    .scanline {
+      position: fixed;
+      inset: 0;
+      pointer-events: none;
+      background: linear-gradient(180deg, transparent 0%, rgba(53, 210, 138, 0.07) 48%, transparent 52%, transparent 100%);
+      animation: sweep 5s linear infinite;
+      opacity: 0.45;
+    }
+
+    @keyframes sweep {
+      0% { transform: translateY(-100%); }
+      100% { transform: translateY(100%); }
+    }
+
+    @keyframes drift {
+      from { transform: translateY(0); }
+      to { transform: translateY(28px); }
+    }
+
+    .wrap {
+      position: relative;
+      width: min(860px, calc(100vw - 32px));
+      margin: 24px auto;
+      top: 50%;
+      transform: translateY(-50%);
+      border: 1px solid var(--line);
+      border-radius: 14px;
+      background: linear-gradient(180deg, rgba(10, 16, 13, 0.94), rgba(6, 11, 9, 0.94));
+      box-shadow: 0 28px 80px rgba(0,0,0,0.58), 0 0 0 1px rgba(53,210,138,0.08) inset;
+      overflow: hidden;
+      animation: pop 380ms ease-out;
+    }
+
+    @keyframes pop {
+      from { opacity: 0; transform: translateY(-48%) scale(0.985); }
+      to { opacity: 1; transform: translateY(-50%) scale(1); }
+    }
+
+    .titlebar {
+      display: flex;
+      align-items: center;
+      gap: 12px;
+      padding: 12px 16px;
+      border-bottom: 1px solid var(--line-soft);
+      background: rgba(6, 12, 10, 0.9);
+    }
+
+    .lights { display: flex; gap: 6px; }
+    .dot {
+      width: 10px;
+      height: 10px;
+      border-radius: 999px;
+      background: #375a4a;
+      border: 1px solid #2b463b;
+    }
+    .dot.ok {
+      background: var(--green);
+      border-color: #1a6f46;
+      box-shadow: 0 0 8px rgba(53,210,138,0.65);
+      animation: blink 1.6s ease-in-out infinite;
+    }
+
+    @keyframes blink {
+      0%, 100% { opacity: 1; }
+      50% { opacity: 0.55; }
+    }
+
+    .bar-title {
+      font-size: 13px;
+      letter-spacing: 0.02em;
+      color: var(--muted);
+      white-space: nowrap;
+      overflow: hidden;
+      text-overflow: ellipsis;
+    }
+
+    .content {
+      padding: 20px;
+      display: grid;
+      grid-template-columns: 1.15fr 0.85fr;
+      gap: 16px;
+    }
+
+    .left {
+      border: 1px solid var(--line-soft);
+      border-radius: 10px;
+      padding: 18px;
+      background: rgba(8, 14, 11, 0.62);
+    }
+
+    .right {
+      border: 1px solid var(--line-soft);
+      border-radius: 10px;
+      padding: 16px;
+      background: rgba(8, 14, 11, 0.62);
+    }
+
+    .kicker {
+      color: var(--green);
+      font-size: 12px;
+      text-transform: uppercase;
+      letter-spacing: 0.11em;
+      margin-bottom: 10px;
+    }
+
+    h1 {
+      margin: 0 0 10px;
+      font-size: clamp(22px, 3.2vw, 29px);
+      line-height: 1.2;
+      letter-spacing: -0.02em;
+    }
+
+    .subtitle {
+      margin: 0 0 14px;
+      color: var(--muted);
+      font-size: 14px;
+      line-height: 1.5;
+    }
+
+    .badge {
+      display: inline-flex;
+      align-items: center;
+      gap: 8px;
+      margin: 0 0 14px;
+      padding: 7px 10px;
+      border-radius: 999px;
+      border: 1px solid rgba(53,210,138,0.4);
+      background: rgba(53,210,138,0.12);
+      color: #d9f9e9;
+      font-size: 12px;
+      font-weight: 700;
+      letter-spacing: 0.05em;
+      text-transform: uppercase;
+    }
+
+    .badge .pulse {
+      width: 8px;
+      height: 8px;
+      border-radius: 999px;
+      background: var(--green);
+      box-shadow: 0 0 9px rgba(53,210,138,0.85);
+      animation: ping 1.2s ease-out infinite;
+    }
+
+    @keyframes ping {
+      0% { transform: scale(1); opacity: 1; }
+      100% { transform: scale(1.8); opacity: 0.1; }
+    }
+
+    .steps {
+      margin: 0;
+      padding: 0;
+      list-style: none;
+      display: grid;
+      gap: 8px;
+    }
+
+    .steps li {
+      border: 1px solid var(--line-soft);
+      background: rgba(7, 12, 10, 0.72);
+      border-radius: 8px;
+      padding: 9px 10px;
+      color: #cde6db;
+      font-size: 13px;
+      display: flex;
+      align-items: center;
+      gap: 8px;
+    }
+
+    .steps li::before {
+      content: ">";
+      color: var(--green);
+      font-weight: 700;
+    }
+
+    .steps li:last-child::before { content: "*"; }
+
+    .terminal {
+      border: 1px solid var(--line-soft);
+      border-radius: 8px;
+      padding: 12px;
+      background: #060b09;
+      min-height: 180px;
+    }
+
+    .prompt {
+      color: #cde6db;
+      margin: 0;
+      font-size: 12px;
+      line-height: 1.65;
+      white-space: pre-wrap;
+    }
+
+    .prompt .ok { color: var(--green); }
+    .prompt .muted { color: var(--muted); }
+    .prompt .warn { color: var(--warn); }
+
+    .progress {
+      margin-top: 10px;
+      height: 8px;
+      border-radius: 999px;
+      background: #0b1a14;
+      border: 1px solid var(--line-soft);
+      overflow: hidden;
+      position: relative;
+    }
+
+    .progress span {
+      display: block;
+      width: 72%;
+      height: 100%;
+      background: linear-gradient(90deg, var(--green-strong), var(--green));
+      animation: load 1.8s ease-in-out infinite;
+    }
+
+    @keyframes load {
+      0%, 100% { width: 62%; }
+      50% { width: 88%; }
+    }
+
+    .footer {
+      border-top: 1px solid var(--line-soft);
+      padding: 11px 16px;
+      color: var(--muted);
+      font-size: 12px;
+      display: flex;
+      justify-content: space-between;
+      gap: 8px;
+      flex-wrap: wrap;
+      background: rgba(6, 11, 9, 0.9);
+    }
+
+    .footer strong { color: var(--text); font-weight: 700; }
+
+    @media (max-width: 840px) {
+      .content {
+        grid-template-columns: 1fr;
+      }
+    }
+  </style>
 </head>
 <body>
-    <canvas class="matrix" id="matrix"></canvas>
-    <div class="scanline"></div>
-    <div class="vignette"></div>
-
-    <div class="container">
-        <div class="logo">
-            <svg width="300" height="54" viewBox="0 0 234 42" fill="none" xmlns="http://www.w3.org/2000/svg">
-                <path d="M18 30H6V18H18V30Z" fill="#4B4646"/>
-                <path d="M18 12H6V30H18V12ZM24 36H0V6H24V36Z" fill="#B7B1B1"/>
-                <path d="M48 30H36V18H48V30Z" fill="#4B4646"/>
-                <path d="M36 30H48V12H36V30ZM54 36H36V42H30V6H54V36Z" fill="#B7B1B1"/>
-                <path d="M84 24V30H66V24H84Z" fill="#4B4646"/>
-                <path d="M84 24H66V30H84V36H60V6H84V24ZM66 18H78V12H66V18Z" fill="#B7B1B1"/>
-                <path d="M108 36H96V18H108V36Z" fill="#4B4646"/>
-                <path d="M108 12H96V36H90V6H108V12ZM114 36H108V12H114V36Z" fill="#B7B1B1"/>
-                <path d="M144 30H126V18H144V30Z" fill="#4B4646"/>
-                <path d="M144 12H126V30H144V36H120V6H144V12Z" fill="#F1ECEC"/>
-                <path d="M168 30H156V18H168V30Z" fill="#4B4646"/>
-                <path d="M168 12H156V30H168V12ZM174 36H150V6H174V36Z" fill="#F1ECEC"/>
-                <path d="M198 30H186V18H198V30Z" fill="#4B4646"/>
-                <path d="M198 12H186V30H198V12ZM204 36H180V6H198V0H204V36Z" fill="#F1ECEC"/>
-                <path d="M234 24V30H216V24H234Z" fill="#4B4646"/>
-                <path d="M216 12V18H228V12H216ZM234 24H216V30H234V36H210V6H234V24Z" fill="#F1ECEC"/>
-            </svg>
+  <div class="grid" aria-hidden="true"></div>
+  <div class="scanline" aria-hidden="true"></div>
+
+  <main class="wrap" role="main" aria-label="OAuth callback success">
+    <header class="titlebar">
+      <div class="lights">
+        <span class="dot"></span>
+        <span class="dot"></span>
+        <span class="dot ok"></span>
+      </div>
+      <div class="bar-title">OpenAI Codex - Callback Received</div>
+    </header>
+
+    <section class="content">
+      <article class="left">
+        <p class="kicker">OpenAI Codex</p>
+        <h1>Sign-in Complete</h1>
+        <p class="subtitle">Account connected. Return to terminal.</p>
+
+        <div class="badge"><span class="pulse"></span> Connected</div>
+
+        <ul class="steps" aria-label="Completion steps">
+          <li>Authorization code received</li>
+          <li>Token exchange complete</li>
+          <li>Credentials saved to local Codex auth storage</li>
+          <li>Session ready</li>
+        </ul>
+      </article>
+
+      <aside class="right" aria-label="Terminal status">
+        <div class="terminal">
+          <pre class="prompt"><span class="ok">[ok]</span> callback received on localhost:1455
+<span class="ok">[ok]</span> secure token flow complete
+<span class="ok">[ok]</span> account saved
+
+<span class="muted">next:</span> return to terminal
+<span class="warn">tip:</span> close this tab</pre>
+          <div class="progress" aria-hidden="true"><span></span></div>
         </div>
-
-        <div class="terminal-window">
-            <div class="terminal-header">
-                <div class="terminal-button red"></div>
-                <div class="terminal-button yellow"></div>
-                <div class="terminal-button green"></div>
-                <div class="terminal-title">codex-multi-auth — OAuth Authentication</div>
-            </div>
-
-            <div class="status-box">
-                <div class="checkmark-container">
-                    <div class="checkmark-circle">
-                        <div class="checkmark"></div>
-                    </div>
-                </div>
-
-                <div class="title">ACCESS GRANTED</div>
-                <div class="message">
-                    OpenAI ChatGPT authentication successful<br>
-                    Your credentials have been securely stored
-                </div>
-
-                <div class="terminal-output">
-                    <div class="terminal-line">
-                        <span class="prompt">▸</span>
-                        <span class="success">Initializing OAuth handshake...</span>
-                    </div>
-                    <div class="terminal-line">
-                        <span class="prompt">▸</span>
-                        <span class="success">Token exchange verified</span>
-                    </div>
-                    <div class="terminal-line">
-                        <span class="prompt">▸</span>
-                        <span class="success">Credentials encrypted & stored</span>
-                    </div>
-                    <div class="terminal-line">
-                        <span class="prompt">✓</span>
-                        <span class="success">OpenCode ready for deployment</span>
-                    </div>
-                </div>
-            </div>
-        </div>
-
-        <div class="footer">
-            Return to your terminal to continue<span class="cursor"></span>
-        </div>
-    </div>
-
-    <script>
-        // Enhanced Matrix rain effect with mouse interaction
-        const canvas = document.getElementById('matrix');
-        const ctx = canvas.getContext('2d');
-
-        canvas.width = window.innerWidth;
-        canvas.height = window.innerHeight;
-
-        // Mix of characters including OpenCode themed ones
-        const chars = 'OPENCODE▸✓▹▸◂◃◄►◀▶←→↑↓⟨⟩∧∨∩∪⊂⊃⊆⊇∈∉∀∃∄∅∞≡≠≤≥±∓⊕⊗⊙01';
-        const fontSize = 16;
-        const columns = Math.floor(canvas.width / fontSize);
-
-        const drops = Array(columns).fill(1);
-        const speeds = Array(columns).fill(0).map(() => Math.random() * 0.5 + 0.5);
-
-        // Track mouse position
-        let mouseX = -1000;
-        let mouseY = -1000;
-
-        canvas.addEventListener('mousemove', (e) => {
-            mouseX = e.clientX;
-            mouseY = e.clientY;
-        });
-
-        canvas.addEventListener('mouseleave', () => {
-            mouseX = -1000;
-            mouseY = -1000;
-        });
-
-        function drawMatrix() {
-            ctx.fillStyle = 'rgba(10, 10, 10, 0.08)';
-            ctx.fillRect(0, 0, canvas.width, canvas.height);
-
-            ctx.font = fontSize + 'px "IBM Plex Mono"';
-
-            for (let i = 0; i < drops.length; i++) {
-                const text = chars[Math.floor(Math.random() * chars.length)];
-                const x = i * fontSize;
-                const y = drops[i] * fontSize;
-
-                // Check distance from mouse
-                const distanceFromMouse = Math.sqrt(
-                    Math.pow(x - mouseX, 2) + Math.pow(y - mouseY, 2)
-                );
-
-                const hoverRadius = 80;
-                const isNearMouse = distanceFromMouse < hoverRadius;
-
-                if (isNearMouse) {
-                    // Matrix green color when near mouse
-                    const intensity = 1 - (distanceFromMouse / hoverRadius);
-                    ctx.fillStyle = `rgba(0, 255, 65, ${intensity * 0.95})`;
-                    ctx.shadowBlur = 20 * intensity;
-                    ctx.shadowColor = '#00ff41';
-                } else {
-                    // Bright white gradient by default
-                    const gradient = ctx.createLinearGradient(0, y - fontSize * 10, 0, y);
-                    gradient.addColorStop(0, 'rgba(200, 200, 200, 0)');
-                    gradient.addColorStop(0.5, 'rgba(241, 236, 236, 0.8)');
-                    gradient.addColorStop(1, 'rgba(255, 255, 255, 1)');
-                    ctx.fillStyle = gradient;
-                    ctx.shadowBlur = 0;
-                }
-
-                ctx.fillText(text, x, y);
-
-                // Randomly reset drops
-                if (drops[i] * fontSize > canvas.height && Math.random() > 0.98) {
-                    drops[i] = 0;
-                    speeds[i] = Math.random() * 0.5 + 0.5;
-                }
-
-                drops[i] += speeds[i];
-            }
-
-            // Reset shadow for next frame
-            ctx.shadowBlur = 0;
-        }
-
-        setInterval(drawMatrix, 40);
-
-        // Create floating particles
-        function createParticle() {
-            const particle = document.createElement('div');
-            particle.className = 'particle';
-            particle.style.left = Math.random() * 100 + '%';
-            particle.style.animationDelay = Math.random() * 8 + 's';
-            particle.style.animationDuration = (Math.random() * 4 + 6) + 's';
-            document.body.appendChild(particle);
-
-            setTimeout(() => particle.remove(), 10000);
-        }
-
-        // Generate particles periodically
-        for (let i = 0; i < 20; i++) {
-            setTimeout(createParticle, i * 400);
-        }
-
-        setInterval(() => {
-            if (Math.random() > 0.7) createParticle();
-        }, 2000);
-
-        // Resize handler
-        window.addEventListener('resize', () => {
-            canvas.width = window.innerWidth;
-            canvas.height = window.innerHeight;
-        });
-
-        // Add subtle mouse parallax effect
-        document.addEventListener('mousemove', (e) => {
-            const moveX = (e.clientX - window.innerWidth / 2) / 50;
-            const moveY = (e.clientY - window.innerHeight / 2) / 50;
-
-            document.querySelector('.container').style.transform =
-                `translate(${moveX}px, ${moveY}px)`;
-        });
-    </script>
+      </aside>
+    </section>
+
+    <footer class="footer">
+      <span>Status: <strong>Connected</strong></span>
+      <span>Back to terminal to continue.</span>
+    </footer>
+  </main>
 </body>
 </html>
diff --git a/lib/preemptive-quota-scheduler.ts b/lib/preemptive-quota-scheduler.ts
new file mode 100644
index 00000000..e1bfe528
--- /dev/null
+++ b/lib/preemptive-quota-scheduler.ts
@@ -0,0 +1,278 @@
+export interface QuotaSchedulerWindow {
+	usedPercent?: number;
+	resetAtMs?: number;
+}
+
+export interface QuotaSchedulerSnapshot {
+	status: number;
+	primary: QuotaSchedulerWindow;
+	secondary: QuotaSchedulerWindow;
+	updatedAt: number;
+}
+
+export interface QuotaDeferralDecision {
+	defer: boolean;
+	waitMs: number;
+	reason?: "rate-limit" | "quota-near-exhaustion";
+}
+
+export interface QuotaSchedulerOptions {
+	enabled?: boolean;
+	remainingPercentThresholdPrimary?: number;
+	remainingPercentThresholdSecondary?: number;
+	usedPercentThreshold?: number;
+	maxDeferralMs?: number;
+}
+
+const DEFAULT_REMAINING_PERCENT_THRESHOLD = 5;
+const DEFAULT_MAX_DEFERRAL_MS = 2 * 60 * 60_000;
+
+/**
+ * Clamp a number to the inclusive integer range [min, max] after flooring.
+ *
+ * @param value - The input number to be floored and clamped
+ * @param min - The inclusive lower bound
+ * @param max - The inclusive upper bound
+ * @returns The integer result equal to `Math.floor(value)` constrained to the range between `min` and `max`
+ */
+function clampInt(value: number, min: number, max: number): number {
+	return Math.max(min, Math.min(max, Math.floor(value)));
+}
+
+/**
+ * Parses a header value as a finite number and returns it when valid.
+ *
+ * This function is pure: it has no concurrency or filesystem side effects, does not access the Windows filesystem, and does not perform any token redaction.
+ *
+ * @param headers - The Headers object to read the header from
+ * @param name - The name of the header to parse
+ * @returns The parsed finite number from the header, or `undefined` if the header is absent or not a finite number
+ */
+function parseFiniteNumberHeader(headers: Headers, name: string): number | undefined {
+	const raw = headers.get(name);
+	if (!raw) return undefined;
+	const parsed = Number(raw);
+	return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+/**
+ * Parse an HTTP header value as a base-10 integer.
+ *
+ * @param headers - The Headers object to read the value from.
+ * @param name - The header name to parse.
+ * @returns The parsed integer if the header exists and is a finite base-10 integer, `undefined` otherwise.
+ */
+function parseFiniteIntHeader(headers: Headers, name: string): number | undefined {
+	const raw = headers.get(name);
+	if (!raw) return undefined;
+	const parsed = Number.parseInt(raw, 10);
+	return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+/**
+ * Parse a reset timestamp header for the given prefix and normalize it to milliseconds since the epoch.
+ *
+ * Interprets `<prefix>-reset-after-seconds` as a relative seconds offset from now, and `<prefix>-reset-at` as
+ * either an absolute epoch seconds value or an HTTP-date; returns the corresponding millisecond timestamp or
+ * `undefined` when no valid value is present.
+ *
+ * Concurrency: callers should treat `headers` as an immutable snapshot. Behavior is independent of Windows
+ * filesystem semantics. Sensitive header values (tokens) are not logged or persisted by this function.
+ *
+ * @param headers - The Headers object to read values from.
+ * @param prefix - Header name prefix (for example `"x-rate-limit"` to read `"x-rate-limit-reset-at"` or `"x-rate-limit-reset-after-seconds"`).
+ * @returns The reset time in milliseconds since epoch, or `undefined` if no valid value is found.
+ */
+function parseResetAtMs(headers: Headers, prefix: string, now: number): number | undefined {
+	const resetAfterSeconds = parseFiniteIntHeader(headers, `${prefix}-reset-after-seconds`);
+	if (typeof resetAfterSeconds === "number" && resetAfterSeconds > 0) {
+		return now + resetAfterSeconds * 1000;
+	}
+	const resetAtRaw = headers.get(`${prefix}-reset-at`);
+	if (!resetAtRaw) return undefined;
+	const trimmed = resetAtRaw.trim();
+	if (/^\d+$/.test(trimmed)) {
+		const parsedNumber = Number.parseInt(trimmed, 10);
+		if (Number.isFinite(parsedNumber) && parsedNumber > 0) {
+			return parsedNumber < 10_000_000_000 ? parsedNumber * 1000 : parsedNumber;
+		}
+	}
+	const parsedDate = Date.parse(trimmed);
+	return Number.isFinite(parsedDate) ? parsedDate : undefined;
+}
+
+/**
+ * Create a quota snapshot from HTTP headers when quota signals are present.
+ *
+ * Parses primary and secondary used-percent and reset timestamps and produces a snapshot; returns `null` if no quota signals are present.
+ *
+ * Concurrency: pure and safe for concurrent calls.
+ * Filesystem: does not access the filesystem (no Windows-specific behavior).
+ * Token handling: does not log or persist header values; callers should redact sensitive headers before logging or storing.
+ *
+ * @param headers - HTTP headers to read quota signals from; may contain sensitive values
+ * @param status - HTTP status code associated with the snapshot
+ * @param now - Millisecond epoch used as the snapshot's `updatedAt` timestamp
+ * @returns A QuotaSchedulerSnapshot built from available header values, or `null` when no signals are present
+ */
+export function readQuotaSchedulerSnapshot(headers: Headers, status: number, now = Date.now()): QuotaSchedulerSnapshot | null {
+	const primaryPrefix = "x-codex-primary";
+	const secondaryPrefix = "x-codex-secondary";
+	const primaryUsed = parseFiniteNumberHeader(headers, `${primaryPrefix}-used-percent`);
+	const secondaryUsed = parseFiniteNumberHeader(headers, `${secondaryPrefix}-used-percent`);
+	const primaryResetAt = parseResetAtMs(headers, primaryPrefix, now);
+	const secondaryResetAt = parseResetAtMs(headers, secondaryPrefix, now);
+
+	const hasSignal =
+		typeof primaryUsed === "number" ||
+		typeof secondaryUsed === "number" ||
+		typeof primaryResetAt === "number" ||
+		typeof secondaryResetAt === "number";
+	if (!hasSignal) return null;
+
+	return {
+		status,
+		primary: { usedPercent: primaryUsed, resetAtMs: primaryResetAt },
+		secondary: { usedPercent: secondaryUsed, resetAtMs: secondaryResetAt },
+		updatedAt: now,
+	};
+}
+
+export class PreemptiveQuotaScheduler {
+	private readonly snapshots = new Map<string, QuotaSchedulerSnapshot>();
+	private enabled: boolean;
+	private primaryRemainingPercentThreshold: number;
+	private secondaryRemainingPercentThreshold: number;
+	private maxDeferralMs: number;
+	private lastPruneAt = 0;
+
+	constructor(options: QuotaSchedulerOptions = {}) {
+		this.enabled = true;
+		this.primaryRemainingPercentThreshold = DEFAULT_REMAINING_PERCENT_THRESHOLD;
+		this.secondaryRemainingPercentThreshold = DEFAULT_REMAINING_PERCENT_THRESHOLD;
+		this.maxDeferralMs = DEFAULT_MAX_DEFERRAL_MS;
+		this.configure(options);
+	}
+
+	configure(options: QuotaSchedulerOptions = {}): void {
+		if (typeof options.enabled === "boolean") {
+			this.enabled = options.enabled;
+		}
+
+		const legacyUsedPercentThreshold = options.usedPercentThreshold;
+		if (
+			typeof legacyUsedPercentThreshold === "number" &&
+			Number.isFinite(legacyUsedPercentThreshold)
+		) {
+			const clampedUsed = clampInt(legacyUsedPercentThreshold, 0, 100);
+			const derivedRemaining = clampInt(100 - clampedUsed, 0, 100);
+			this.primaryRemainingPercentThreshold = derivedRemaining;
+			this.secondaryRemainingPercentThreshold = derivedRemaining;
+		}
+
+		if (
+			typeof options.remainingPercentThresholdPrimary === "number" &&
+			Number.isFinite(options.remainingPercentThresholdPrimary)
+		) {
+			this.primaryRemainingPercentThreshold = clampInt(
+				options.remainingPercentThresholdPrimary,
+				0,
+				100,
+			);
+		}
+
+		if (
+			typeof options.remainingPercentThresholdSecondary === "number" &&
+			Number.isFinite(options.remainingPercentThresholdSecondary)
+		) {
+			this.secondaryRemainingPercentThreshold = clampInt(
+				options.remainingPercentThresholdSecondary,
+				0,
+				100,
+			);
+		}
+
+		if (typeof options.maxDeferralMs === "number" && Number.isFinite(options.maxDeferralMs)) {
+			this.maxDeferralMs = Math.max(1_000, Math.floor(options.maxDeferralMs));
+		}
+	}
+
+	private maybePrune(now = Date.now()): void {
+		if (now - this.lastPruneAt < 60_000) return;
+		this.prune(now);
+		this.lastPruneAt = now;
+	}
+
+	update(key: string, snapshot: QuotaSchedulerSnapshot): void {
+		if (!key) return;
+		this.maybePrune(snapshot.updatedAt || Date.now());
+		this.snapshots.set(key, snapshot);
+	}
+
+	markRateLimited(key: string, retryAfterMs: number, now = Date.now()): void {
+		if (!key) return;
+		const waitMs = Number.isFinite(retryAfterMs) ? Math.max(0, Math.floor(retryAfterMs)) : 0;
+		this.snapshots.set(key, {
+			status: 429,
+			primary: {
+				usedPercent: 100,
+				resetAtMs: now + waitMs,
+			},
+			secondary: {},
+			updatedAt: now,
+		});
+	}
+
+	getDeferral(key: string, now = Date.now()): QuotaDeferralDecision {
+		this.maybePrune(now);
+		if (!this.enabled) {
+			return { defer: false, waitMs: 0 };
+		}
+
+		const snapshot = this.snapshots.get(key);
+		if (!snapshot) return { defer: false, waitMs: 0 };
+
+		const waitCandidates = [snapshot.primary.resetAtMs, snapshot.secondary.resetAtMs]
+			.filter((value): value is number => typeof value === "number" && Number.isFinite(value) && value > now)
+			.map((value) => value - now)
+			.filter((value) => value > 0);
+		const nearestWait = waitCandidates.length > 0 ? Math.min(...waitCandidates) : 0;
+
+		if (snapshot.status === 429 && nearestWait > 0) {
+			const bounded = Math.min(nearestWait, this.maxDeferralMs);
+			if (bounded > 0) {
+				return { defer: true, waitMs: bounded, reason: "rate-limit" };
+			}
+		}
+
+		const primaryNearExhausted =
+			typeof snapshot.primary.usedPercent === "number" &&
+			Number.isFinite(snapshot.primary.usedPercent) &&
+			snapshot.primary.usedPercent >= 100 - this.primaryRemainingPercentThreshold;
+		const secondaryNearExhausted =
+			typeof snapshot.secondary.usedPercent === "number" &&
+			Number.isFinite(snapshot.secondary.usedPercent) &&
+			snapshot.secondary.usedPercent >= 100 - this.secondaryRemainingPercentThreshold;
+		const nearExhausted = primaryNearExhausted || secondaryNearExhausted;
+		if (nearExhausted && nearestWait > 0) {
+			const bounded = Math.min(nearestWait, this.maxDeferralMs);
+			if (bounded > 0) {
+				return { defer: true, waitMs: bounded, reason: "quota-near-exhaustion" };
+			}
+		}
+
+		return { defer: false, waitMs: 0 };
+	}
+
+	prune(now = Date.now()): number {
+		let removed = 0;
+		for (const [key, snapshot] of this.snapshots.entries()) {
+			const latestReset = Math.max(snapshot.primary.resetAtMs ?? 0, snapshot.secondary.resetAtMs ?? 0);
+			if (latestReset > 0 && latestReset <= now) {
+				this.snapshots.delete(key);
+				removed += 1;
+			}
+		}
+		return removed;
+	}
+}
diff --git a/lib/prompts/codex.ts b/lib/prompts/codex.ts
index 4012e998..eee314f4 100644
--- a/lib/prompts/codex.ts
+++ b/lib/prompts/codex.ts
@@ -1,15 +1,15 @@
 import { promises as fs } from "node:fs";
-import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import type { CacheMetadata, GitHubRelease } from "../types.js";
 import { logWarn, logError, logDebug } from "../logger.js";
+import { getCodexCacheDir } from "../runtime-paths.js";
 
 const GITHUB_API_RELEASES =
 	"https://api.github.com/repos/openai/codex/releases/latest";
 const GITHUB_HTML_RELEASES =
 	"https://github.com/openai/codex/releases/latest";
-const CACHE_DIR = join(homedir(), ".opencode", "cache");
+const CACHE_DIR = getCodexCacheDir();
 const CACHE_TTL_MS = 15 * 60 * 1000;
 
 const __filename = fileURLToPath(import.meta.url);
diff --git a/lib/prompts/opencode-codex.ts b/lib/prompts/opencode-codex.ts
index fa370bb3..03da0590 100644
--- a/lib/prompts/opencode-codex.ts
+++ b/lib/prompts/opencode-codex.ts
@@ -6,9 +6,10 @@
  */
 
 import { join } from "node:path";
-import { homedir } from "node:os";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { logDebug } from "../logger.js";
+import { getCodexCacheDir } from "../runtime-paths.js";
+import { sleep } from "../utils.js";
 
 const DEFAULT_OPENCODE_CODEX_URLS = [
 	"https://raw.githubusercontent.com/anomalyco/opencode/dev/packages/opencode/src/session/prompt/codex.txt",
@@ -20,17 +21,22 @@ const DEFAULT_OPENCODE_CODEX_URLS = [
 	"https://raw.githubusercontent.com/anomalyco/opencode/main/packages/opencode/src/session/prompt/codex.md",
 	"https://raw.githubusercontent.com/sst/opencode/main/packages/opencode/src/session/prompt/codex.md",
 ] as const;
-const OPENCODE_CODEX_URL_OVERRIDE_ENV = "OPENCODE_CODEX_PROMPT_URL";
-const CACHE_DIR = join(homedir(), ".opencode", "cache");
+const CODEX_PROMPT_URL_OVERRIDE_ENV = "CODEX_PROMPT_SOURCE_URL";
+const LEGACY_OPENCODE_CODEX_URL_OVERRIDE_ENV = "OPENCODE_CODEX_PROMPT_URL";
+const CACHE_DIR = getCodexCacheDir();
 const CACHE_FILE = join(CACHE_DIR, "opencode-codex.txt");
 const CACHE_META_FILE = join(CACHE_DIR, "opencode-codex-meta.json");
 const CACHE_TTL_MS = 15 * 60 * 1000;
+const RETRYABLE_FS_ERROR_CODES = new Set(["EBUSY", "EPERM"]);
+const WRITE_RETRY_ATTEMPTS = 5;
+const WRITE_RETRY_BASE_DELAY_MS = 10;
 
 interface CacheMeta {
 	etag: string;
 	lastFetch?: string; // Legacy field for backwards compatibility
 	lastChecked: number; // Timestamp for rate limit protection
-	sourceUrl?: string;
+	sourceKey?: string;
+	sourceUrl?: string; // Legacy field kept for compatibility reads.
 }
 
 interface CacheSnapshot {
@@ -45,6 +51,15 @@ function isFresh(lastChecked: number): boolean {
 	return Date.now() - lastChecked < CACHE_TTL_MS;
 }
 
+function redactSourceForLog(source: string): string {
+	try {
+		const parsed = new URL(source);
+		return `${parsed.origin}${parsed.pathname}`;
+	} catch {
+		return "<invalid-url>";
+	}
+}
+
 function parseSourceUrl(source: string | undefined): string | undefined {
 	if (!source) return undefined;
 	const trimmed = source.trim();
@@ -53,20 +68,51 @@ function parseSourceUrl(source: string | undefined): string | undefined {
 		const parsed = new URL(trimmed);
 		if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
 			logDebug("Ignoring OpenCode codex prompt source override due to protocol", {
-				source: trimmed,
+				source: redactSourceForLog(trimmed),
 			});
 			return undefined;
 		}
 		return trimmed;
 	} catch {
 		logDebug("Ignoring invalid OpenCode codex prompt source override", {
-			source: trimmed,
+			source: redactSourceForLog(trimmed),
 		});
 		return undefined;
 	}
 }
 
-function resolvePromptSources(cachedMeta: CacheMeta | null): string[] {
+function sourceCacheKey(source: string): string {
+	try {
+		const parsed = new URL(source);
+		return `${parsed.origin}${parsed.pathname}`;
+	} catch {
+		return source.trim();
+	}
+}
+
+function isRetryableFsError(error: unknown): boolean {
+	const code = (error as NodeJS.ErrnoException | undefined)?.code;
+	return typeof code === "string" && RETRYABLE_FS_ERROR_CODES.has(code);
+}
+
+async function writeFileWithRetry(filePath: string, content: string): Promise<void> {
+	let lastError: unknown;
+	for (let attempt = 0; attempt < WRITE_RETRY_ATTEMPTS; attempt += 1) {
+		try {
+			await writeFile(filePath, content, "utf-8");
+			return;
+		} catch (error) {
+			if (!isRetryableFsError(error) || attempt + 1 >= WRITE_RETRY_ATTEMPTS) {
+				throw error;
+			}
+			lastError = error;
+			await sleep(WRITE_RETRY_BASE_DELAY_MS * 2 ** attempt);
+		}
+	}
+	throw lastError instanceof Error ? lastError : new Error("Failed to write prompt cache file");
+}
+
+function resolvePromptSources(): string[] {
 	const sources: string[] = [];
 	const seen = new Set<string>();
 
@@ -77,8 +123,8 @@ function resolvePromptSources(cachedMeta: CacheMeta | null): string[] {
 		sources.push(parsed);
 	};
 
-	add(process.env[OPENCODE_CODEX_URL_OVERRIDE_ENV]);
-	add(cachedMeta?.sourceUrl);
+	add(process.env[CODEX_PROMPT_URL_OVERRIDE_ENV]);
+	add(process.env[LEGACY_OPENCODE_CODEX_URL_OVERRIDE_ENV]);
 	for (const source of DEFAULT_OPENCODE_CODEX_URLS) {
 		add(source);
 	}
@@ -111,11 +157,11 @@ async function saveDiskCache(
 		etag,
 		lastFetch: new Date().toISOString(),
 		lastChecked: Date.now(),
-		sourceUrl,
+		sourceKey: sourceCacheKey(sourceUrl),
 	};
 	await Promise.all([
-		writeFile(CACHE_FILE, content, "utf-8"),
-		writeFile(CACHE_META_FILE, JSON.stringify(meta, null, 2), "utf-8"),
+		writeFileWithRetry(CACHE_FILE, content),
+		writeFileWithRetry(CACHE_META_FILE, JSON.stringify(meta, null, 2)),
 	]);
 	return meta;
 }
@@ -124,14 +170,17 @@ async function refreshPrompt(
 	cachedMeta: CacheMeta | null,
 	cachedContent: string | null,
 ): Promise<string> {
-	const sources = resolvePromptSources(cachedMeta);
+	const sources = resolvePromptSources();
 	let lastFailure: string | null = null;
 
 	for (const sourceUrl of sources) {
 		const headers: Record<string, string> = {};
+		const currentSourceKey = sourceCacheKey(sourceUrl);
+		const cachedSourceKey = cachedMeta?.sourceKey ??
+			(cachedMeta?.sourceUrl ? sourceCacheKey(cachedMeta.sourceUrl) : undefined);
 		const canUseConditionalRequest =
 			!!cachedMeta?.etag &&
-			(!cachedMeta.sourceUrl || cachedMeta.sourceUrl === sourceUrl);
+			(!cachedSourceKey || cachedSourceKey === currentSourceKey);
 		if (canUseConditionalRequest) {
 			headers["If-None-Match"] = cachedMeta.etag;
 		}
@@ -140,9 +189,9 @@ async function refreshPrompt(
 		try {
 			response = await fetch(sourceUrl, { headers });
 		} catch (error) {
-			lastFailure = `${sourceUrl}: ${String(error)}`;
+			lastFailure = `${redactSourceForLog(sourceUrl)}: ${String(error)}`;
 			logDebug("OpenCode prompt source fetch failed", {
-				sourceUrl,
+				sourceUrl: redactSourceForLog(sourceUrl),
 				error: String(error),
 			});
 			continue;
@@ -153,22 +202,18 @@ async function refreshPrompt(
 				etag: cachedMeta?.etag ?? "",
 				lastFetch: cachedMeta?.lastFetch ?? new Date().toISOString(),
 				lastChecked: Date.now(),
-				sourceUrl,
+				sourceKey: currentSourceKey,
 			};
 			memoryCache = { content: cachedContent, meta: refreshedMeta };
 			await mkdir(CACHE_DIR, { recursive: true });
-			await writeFile(
-				CACHE_META_FILE,
-				JSON.stringify(refreshedMeta, null, 2),
-				"utf-8",
-			);
+			await writeFileWithRetry(CACHE_META_FILE, JSON.stringify(refreshedMeta, null, 2));
 			return cachedContent;
 		}
 
 		if (!response.ok) {
-			lastFailure = `${sourceUrl}: HTTP ${response.status}`;
+			lastFailure = `${redactSourceForLog(sourceUrl)}: HTTP ${response.status}`;
 			logDebug("OpenCode prompt source returned non-OK response", {
-				sourceUrl,
+				sourceUrl: redactSourceForLog(sourceUrl),
 				status: response.status,
 			});
 			continue;
diff --git a/lib/quota-cache.ts b/lib/quota-cache.ts
new file mode 100644
index 00000000..9870a2b6
--- /dev/null
+++ b/lib/quota-cache.ts
@@ -0,0 +1,261 @@
+import { existsSync, promises as fs } from "node:fs";
+import { basename, join } from "node:path";
+import { logWarn } from "./logger.js";
+import { getCodexMultiAuthDir } from "./runtime-paths.js";
+import { isRecord, sleep } from "./utils.js";
+
+export interface QuotaCacheWindow {
+	usedPercent?: number;
+	windowMinutes?: number;
+	resetAtMs?: number;
+}
+
+export interface QuotaCacheEntry {
+	updatedAt: number;
+	status: number;
+	model: string;
+	planType?: string;
+	primary: QuotaCacheWindow;
+	secondary: QuotaCacheWindow;
+}
+
+export interface QuotaCacheData {
+	byAccountId: Record<string, QuotaCacheEntry>;
+	byEmail: Record<string, QuotaCacheEntry>;
+}
+
+interface QuotaCacheFile {
+	version: 1;
+	byAccountId: Record<string, QuotaCacheEntry>;
+	byEmail: Record<string, QuotaCacheEntry>;
+}
+
+const QUOTA_CACHE_PATH = join(getCodexMultiAuthDir(), "quota-cache.json");
+const QUOTA_CACHE_LABEL = basename(QUOTA_CACHE_PATH);
+const RETRYABLE_FS_CODES = new Set(["EBUSY", "EPERM"]);
+
+function isRetryableFsError(error: unknown): boolean {
+	const code = (error as NodeJS.ErrnoException | undefined)?.code;
+	return typeof code === "string" && RETRYABLE_FS_CODES.has(code);
+}
+
+/**
+ * Normalizes an unknown value to a finite number.
+ *
+ * @param value - The value to normalize
+ * @returns The input as a finite number, or `undefined` if the value is not a finite number
+ */
+function normalizeNumber(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+/**
+ * Produce a normalized QuotaCacheWindow from an arbitrary value.
+ *
+ * @param value - The raw input to normalize; if not an object, an empty window is returned.
+ * @returns A QuotaCacheWindow whose `usedPercent`, `windowMinutes`, and `resetAtMs` are finite numbers or `undefined` when missing/invalid.
+ */
+function normalizeWindow(value: unknown): QuotaCacheWindow {
+	if (!isRecord(value)) return {};
+	return {
+		usedPercent: normalizeNumber(value.usedPercent),
+		windowMinutes: normalizeNumber(value.windowMinutes),
+		resetAtMs: normalizeNumber(value.resetAtMs),
+	};
+}
+
+/**
+ * Normalize and validate a raw parsed value into a quota cache entry.
+ *
+ * Produces a QuotaCacheEntry with a trimmed `model`, optional `planType`, and normalized
+ * `primary`/`secondary` windows when `updatedAt`, `status`, and `model` are present and valid;
+ * returns `null` for any invalid input. This helper is pure (no I/O), safe to call concurrently,
+ * and platform-agnostic (works with data read from files on Windows or POSIX). It does not perform
+ * token redaction — callers must redact sensitive fields before persisting or logging.
+ *
+ * @param value - The arbitrary input (typically parsed JSON) to validate and normalize
+ * @returns A normalized `QuotaCacheEntry` if validation succeeds, `null` otherwise
+ */
+function normalizeEntry(value: unknown): QuotaCacheEntry | null {
+	if (!isRecord(value)) return null;
+	const updatedAt = normalizeNumber(value.updatedAt);
+	const status = normalizeNumber(value.status);
+	const model = typeof value.model === "string" ? value.model : "";
+	if (
+		typeof updatedAt !== "number" ||
+		typeof status !== "number" ||
+		model.trim().length === 0
+	) {
+		return null;
+	}
+
+	return {
+		updatedAt,
+		status,
+		model: model.trim(),
+		planType: typeof value.planType === "string" ? value.planType : undefined,
+		primary: normalizeWindow(value.primary),
+		secondary: normalizeWindow(value.secondary),
+	};
+}
+
+/**
+ * Convert a raw parsed value into a map of validated quota cache entries.
+ *
+ * @param value - Parsed JSON value (typically an object) containing raw entries keyed by identifier; non-objects, empty keys, or invalid entries are ignored.
+ * @returns A record mapping valid string keys to normalized `QuotaCacheEntry` objects; malformed entries are omitted.
+ * 
+ * Note: This function is pure and performs no filesystem I/O. Callers are responsible for any filesystem concurrency or Windows-specific behavior when loading/saving the on-disk cache, and for redacting any sensitive tokens before logging or persisting.
+ */
+function normalizeEntryMap(value: unknown): Record<string, QuotaCacheEntry> {
+	if (!isRecord(value)) return {};
+	const entries: Record<string, QuotaCacheEntry> = {};
+	for (const [key, raw] of Object.entries(value)) {
+		if (typeof key !== "string" || key.trim().length === 0) continue;
+		const normalized = normalizeEntry(raw);
+		if (!normalized) continue;
+		entries[key] = normalized;
+	}
+	return entries;
+}
+
+async function readCacheFileWithRetry(path: string): Promise<string> {
+	let lastError: unknown;
+	for (let attempt = 0; attempt < 5; attempt += 1) {
+		try {
+			return await fs.readFile(path, "utf8");
+		} catch (error) {
+			lastError = error;
+			if (!isRetryableFsError(error) || attempt >= 4) {
+				throw error;
+			}
+			await sleep(10 * 2 ** attempt);
+		}
+	}
+	throw lastError instanceof Error ? lastError : new Error("quota cache read retry exhausted");
+}
+
+/**
+ * Get the absolute filesystem path to the quota-cache.json file.
+ *
+ * The resolved path points to quota-cache.json inside the Codex multi-auth directory.
+ * Callers must observe normal filesystem concurrency semantics (no internal locking is provided),
+ * and handle platform-specific path behavior (for example, on Windows the file may reside under %APPDATA%).
+ * The file can contain sensitive values; redact tokens or secrets before logging or exposing its contents.
+ *
+ * @returns The absolute path to the quota-cache.json file
+ */
+export function getQuotaCachePath(): string {
+	return QUOTA_CACHE_PATH;
+}
+
+/**
+ * Loads and returns the normalized quota cache from disk.
+ *
+ * Reads the JSON cache at the configured quota-cache path, validates and normalizes entries,
+ * and returns maps keyed by account ID and email. If the file is missing, invalid, or an I/O
+ * error occurs, returns empty maps and logs a warning.
+ *
+ * Notes:
+ * - Concurrency: callers should expect concurrent readers and writers; the function performs
+ *   a best-effort read and does not perform file locking.
+ * - Windows: uses standard UTF-8 file reads; caller should ensure the quota-cache path is
+ *   compatible with Windows path semantics when used on that platform.
+ * - Redaction: callers should avoid logging or exposing the file contents; any tokens or
+ *   sensitive identifiers contained in the cache should be redacted before external reporting.
+ *
+ * @returns The quota cache as `{ byAccountId, byEmail }` with normalized entries; each map
+ *          will be empty if the on-disk file is absent, malformed, or could not be read.
+ */
+export async function loadQuotaCache(): Promise<QuotaCacheData> {
+	if (!existsSync(QUOTA_CACHE_PATH)) {
+		return { byAccountId: {}, byEmail: {} };
+	}
+
+	try {
+		const content = await readCacheFileWithRetry(QUOTA_CACHE_PATH);
+		const parsed = JSON.parse(content) as unknown;
+		if (!isRecord(parsed)) {
+			return { byAccountId: {}, byEmail: {} };
+		}
+		if (parsed.version !== 1) {
+			logWarn(`Quota cache rejected due to version mismatch: ${String(parsed.version)}`);
+			return { byAccountId: {}, byEmail: {} };
+		}
+
+		return {
+			byAccountId: normalizeEntryMap(parsed.byAccountId),
+			byEmail: normalizeEntryMap(parsed.byEmail),
+		};
+	} catch (error) {
+		logWarn(
+			`Failed to load quota cache from ${QUOTA_CACHE_LABEL}: ${
+				error instanceof Error ? error.message : String(error)
+			}`,
+		);
+		return { byAccountId: {}, byEmail: {} };
+	}
+}
+
+/**
+ * Persist the quota cache to the on-disk JSON file used by the multi-auth runtime.
+ *
+ * Writes a versioned, pretty-printed JSON representation of `data` to the configured
+ * quota cache path. Failures are logged and do not throw, so callers should handle
+ * eventual consistency or retry as needed.
+ *
+ * Concurrency: concurrent writers may race and overwrite each other; callers should
+ * serialize writes if strong consistency is required.
+ *
+ * Filesystem notes: Windows path length, permissions, or antivirus locks may cause
+ * write failures; such errors are logged rather than thrown.
+ *
+ * Security: this function does not redact secrets or tokens — callers must ensure
+ * `data` contains no sensitive plaintext tokens before calling.
+ *
+ * @param data - The quota cache data (byAccountId and byEmail maps) to persist; callers
+ *               should pass normalized QuotaCacheData.
+ */
+export async function saveQuotaCache(data: QuotaCacheData): Promise<void> {
+	const payload: QuotaCacheFile = {
+		version: 1,
+		byAccountId: data.byAccountId,
+		byEmail: data.byEmail,
+	};
+
+	try {
+		await fs.mkdir(getCodexMultiAuthDir(), { recursive: true });
+		const tempPath = `${QUOTA_CACHE_PATH}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2, 8)}.tmp`;
+		await fs.writeFile(tempPath, `${JSON.stringify(payload, null, 2)}\n`, {
+			encoding: "utf8",
+			mode: 0o600,
+		});
+		let renamed = false;
+		try {
+			for (let attempt = 0; attempt < 5; attempt += 1) {
+				try {
+					await fs.rename(tempPath, QUOTA_CACHE_PATH);
+					renamed = true;
+					break;
+				} catch (error) {
+					if (!isRetryableFsError(error) || attempt >= 4) throw error;
+					await sleep(10 * 2 ** attempt);
+				}
+			}
+		} finally {
+			if (!renamed) {
+				try {
+					await fs.unlink(tempPath);
+				} catch {
+					// Best effort temp cleanup.
+				}
+			}
+		}
+	} catch (error) {
+		logWarn(
+			`Failed to save quota cache to ${QUOTA_CACHE_LABEL}: ${
+				error instanceof Error ? error.message : String(error)
+			}`,
+		);
+	}
+}
diff --git a/lib/quota-probe.ts b/lib/quota-probe.ts
new file mode 100644
index 00000000..9535b7f9
--- /dev/null
+++ b/lib/quota-probe.ts
@@ -0,0 +1,414 @@
+import { CODEX_BASE_URL } from "./constants.js";
+import { createCodexHeaders, getUnsupportedCodexModelInfo } from "./request/fetch-helpers.js";
+import { getCodexInstructions } from "./prompts/codex.js";
+import type { RequestBody } from "./types.js";
+import { isRecord } from "./utils.js";
+
+export interface CodexQuotaWindow {
+	usedPercent?: number;
+	windowMinutes?: number;
+	resetAtMs?: number;
+}
+
+export interface CodexQuotaSnapshot {
+	status: number;
+	planType?: string;
+	activeLimit?: number;
+	primary: CodexQuotaWindow;
+	secondary: CodexQuotaWindow;
+	model: string;
+}
+
+const DEFAULT_QUOTA_PROBE_MODELS = ["gpt-5-codex", "gpt-5.3-codex", "gpt-5.2-codex"] as const;
+
+/**
+ * Parse an HTTP header value and return it as a finite number.
+ *
+ * This is synchronous, has no filesystem side effects, and is safe for concurrent use.
+ * Callers are responsible for any sensitive header handling or token redaction.
+ *
+ * @param headers - The Headers object to read the header from.
+ * @param name - The header name to parse.
+ * @returns The header value parsed as a finite number, or `undefined` if the header is missing or not a finite number.
+ */
+function parseFiniteNumberHeader(headers: Headers, name: string): number | undefined {
+	const raw = headers.get(name);
+	if (!raw) return undefined;
+	const parsed = Number(raw);
+	return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+/**
+ * Parse a header value as a base-10 integer and return it if it is a finite number.
+ *
+ * This function is pure and side-effect-free, safe for concurrent use, and performs no filesystem I/O.
+ * It does not redact or log header contents; treat header values as potentially sensitive and avoid exposing them.
+ *
+ * @param headers - The Headers object to read from
+ * @param name - The header name to parse
+ * @returns The parsed integer value, or `undefined` if the header is missing or not a finite integer
+ */
+function parseFiniteIntHeader(headers: Headers, name: string): number | undefined {
+	const raw = headers.get(name);
+	if (!raw) return undefined;
+	const parsed = Number.parseInt(raw, 10);
+	return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+/**
+ * Compute the absolute millisecond timestamp when a quota window resets from Codex response headers.
+ *
+ * @param headers - Response Headers object containing reset information (e.g., `<prefix>-reset-after-seconds` or `<prefix>-reset-at`)
+ * @param prefix - Header name prefix (for example, `"primary"` or `"secondary"`)
+ * @returns The reset time as a Unix timestamp in milliseconds, or `undefined` if no valid reset information is present.
+ *
+ * Concurrency: pure and safe for concurrent use.
+ * Filesystem: performs no filesystem I/O and behaves identically on Windows.
+ * Security: does not emit or persist header values; callers must redact any sensitive tokens before storing or logging headers.
+ */
+function parseResetAtMs(headers: Headers, prefix: string): number | undefined {
+	const resetAfterSeconds = parseFiniteIntHeader(headers, `${prefix}-reset-after-seconds`);
+	if (typeof resetAfterSeconds === "number" && resetAfterSeconds > 0) {
+		return Date.now() + resetAfterSeconds * 1000;
+	}
+
+	const resetAtRaw = headers.get(`${prefix}-reset-at`);
+	if (!resetAtRaw) return undefined;
+
+	const trimmed = resetAtRaw.trim();
+	if (/^\d+$/.test(trimmed)) {
+		const parsedNumber = Number.parseInt(trimmed, 10);
+		if (Number.isFinite(parsedNumber) && parsedNumber > 0) {
+			return parsedNumber < 10_000_000_000 ? parsedNumber * 1000 : parsedNumber;
+		}
+	}
+
+	const parsedDate = Date.parse(trimmed);
+	return Number.isFinite(parsedDate) ? parsedDate : undefined;
+}
+
+/**
+ * Detects whether the provided HTTP headers include any Codex quota-related keys.
+ *
+ * Inspects only header presence (no header values are read, logged, or written to disk). Safe to call concurrently; does not interact with the filesystem. Callers must ensure any sensitive tokens in headers are redacted before external logging.
+ *
+ * @param headers - The Headers object to check for Codex quota headers
+ * @returns `true` if at least one Codex quota header is present, `false` otherwise
+ */
+function hasCodexQuotaHeaders(headers: Headers): boolean {
+	const keys = [
+		"x-codex-primary-used-percent",
+		"x-codex-primary-window-minutes",
+		"x-codex-primary-reset-at",
+		"x-codex-primary-reset-after-seconds",
+		"x-codex-secondary-used-percent",
+		"x-codex-secondary-window-minutes",
+		"x-codex-secondary-reset-at",
+		"x-codex-secondary-reset-after-seconds",
+	];
+	return keys.some((key) => headers.get(key) !== null);
+}
+
+/**
+ * Parse Codex quota-related HTTP headers into a quota snapshot (excluding the model).
+ *
+ * @param headers - HTTP response headers to read quota fields from; the function does not modify headers and performs no I/O.
+ * @param status - HTTP status code associated with the response; included verbatim in the returned snapshot when present.
+ * @returns An object with `status`, optional `planType`, optional `activeLimit`, and `primary`/`secondary` quota window objects when any Codex quota headers are present; `null` if no quota headers were found.
+ *
+ * Concurrency: safe to call concurrently from multiple tasks (pure header parsing with no shared state).
+ * Filesystem: performs no filesystem operations and is unaffected by platform path semantics (Windows or otherwise).
+ * Token redaction: this function does not redact or log header values; callers must ensure any sensitive tokens in `headers` are redacted before logging or persisting.
+ */
+function parseQuotaSnapshotBase(
+	headers: Headers,
+	status: number,
+): Omit<CodexQuotaSnapshot, "model"> | null {
+	if (!hasCodexQuotaHeaders(headers)) return null;
+
+	const primaryPrefix = "x-codex-primary";
+	const secondaryPrefix = "x-codex-secondary";
+	const primary: CodexQuotaWindow = {
+		usedPercent: parseFiniteNumberHeader(headers, `${primaryPrefix}-used-percent`),
+		windowMinutes: parseFiniteIntHeader(headers, `${primaryPrefix}-window-minutes`),
+		resetAtMs: parseResetAtMs(headers, primaryPrefix),
+	};
+	const secondary: CodexQuotaWindow = {
+		usedPercent: parseFiniteNumberHeader(headers, `${secondaryPrefix}-used-percent`),
+		windowMinutes: parseFiniteIntHeader(headers, `${secondaryPrefix}-window-minutes`),
+		resetAtMs: parseResetAtMs(headers, secondaryPrefix),
+	};
+
+	const planTypeRaw = headers.get("x-codex-plan-type");
+	const planType = planTypeRaw && planTypeRaw.trim() ? planTypeRaw.trim() : undefined;
+	const activeLimit = parseFiniteIntHeader(headers, "x-codex-active-limit");
+
+	return { status, planType, activeLimit, primary, secondary };
+}
+
+/**
+ * Build a deduplicated, trimmed list of candidate probe model names from a primary model and fallbacks.
+ *
+ * Produces a unique array where each entry is a non-empty, trimmed model string. Empty or whitespace-only
+ * inputs are ignored and duplicates are removed while preserving the first occurrence order.
+ *
+ * Concurrency assumptions: pure and side-effect-free — safe to call concurrently.
+ * Windows filesystem behavior: no filesystem interaction.
+ * Token redaction: does not log or retain authentication tokens; callers must redact tokens when logging model names if required.
+ *
+ * @param primaryModel - Optional preferred model name to try first
+ * @param fallbackModels - Optional array of fallback model names; if omitted, a built-in default list is used
+ * @returns An array of unique, trimmed model names to probe, in priority order
+ */
+function normalizeProbeModels(
+	primaryModel: string | undefined,
+	fallbackModels: readonly string[] | undefined,
+): string[] {
+	const base = primaryModel?.trim();
+	const merged = [
+		base,
+		...(fallbackModels ?? DEFAULT_QUOTA_PROBE_MODELS),
+	].filter((model): model is string => typeof model === "string" && model.trim().length > 0);
+	return Array.from(new Set(merged.map((model) => model.trim())));
+}
+
+/**
+ * Extracts the most informative error message from an HTTP response body.
+ *
+ * Safe for concurrent use and performs no filesystem access (including no Windows-specific file operations).
+ * This function does not redact tokens or other sensitive values from the returned message.
+ *
+ * @param bodyText - Raw response body text
+ * @param status - HTTP status code associated with the response
+ * @returns The best available message: `error.message` or `message` from parsed JSON if present, `HTTP <status>` when the body is empty, or the trimmed raw body text otherwise
+ */
+function extractErrorMessage(bodyText: string, status: number): string {
+	const trimmed = bodyText.trim();
+	if (!trimmed) return `HTTP ${status}`;
+	try {
+		const parsed = JSON.parse(trimmed) as unknown;
+		if (isRecord(parsed)) {
+			const maybeError = parsed.error;
+			if (isRecord(maybeError) && typeof maybeError.message === "string") {
+				return maybeError.message;
+			}
+			if (typeof parsed.message === "string") {
+				return parsed.message;
+			}
+		}
+	} catch {
+		// Fall through to raw body text.
+	}
+	return trimmed;
+}
+
+/**
+ * Produce a short human-friendly label for a quota window duration.
+ *
+ * @param windowMinutes - Duration of the quota window in minutes; if undefined, non-finite, or <= 0 a generic label is returned
+ * @returns A short label: `Nd` when `windowMinutes` is divisible by 1440 (days), `Nh` when divisible by 60 (hours), `Nm` otherwise; returns `"quota"` for unspecified or invalid input
+ *
+ * Notes: safe for concurrent use, performs no filesystem I/O, and returns no sensitive tokens (safe for logging/display).
+ */
+function formatQuotaWindowLabel(windowMinutes: number | undefined): string {
+	if (!windowMinutes || !Number.isFinite(windowMinutes) || windowMinutes <= 0) {
+		return "quota";
+	}
+	if (windowMinutes % 1440 === 0) return `${windowMinutes / 1440}d`;
+	if (windowMinutes % 60 === 0) return `${windowMinutes / 60}h`;
+	return `${windowMinutes}m`;
+}
+
+/**
+ * Format a millisecond epoch timestamp into a concise human-readable reset time.
+ *
+ * Returns a 24-hour time "HH:MM" when the timestamp is today, otherwise "HH:MM on Mon DD".
+ *
+ * This function has no side effects, is safe for concurrent use, does not access the filesystem,
+ * and produces no sensitive token data.
+ *
+ * @param resetAtMs - Timestamp in milliseconds since epoch; if `undefined`, non-finite, or <= 0, the function returns `undefined`.
+ * @returns The formatted reset time string, or `undefined` if `resetAtMs` is invalid or not provided.
+ */
+function formatResetAt(resetAtMs: number | undefined): string | undefined {
+	if (!resetAtMs || !Number.isFinite(resetAtMs) || resetAtMs <= 0) return undefined;
+	const date = new Date(resetAtMs);
+	if (!Number.isFinite(date.getTime())) return undefined;
+
+	const now = new Date();
+	const sameDay =
+		now.getFullYear() === date.getFullYear() &&
+		now.getMonth() === date.getMonth() &&
+		now.getDate() === date.getDate();
+
+	const time = date.toLocaleTimeString(undefined, {
+		hour: "2-digit",
+		minute: "2-digit",
+		hour12: false,
+	});
+
+	if (sameDay) return time;
+	const day = date.toLocaleDateString(undefined, { month: "short", day: "2-digit" });
+	return `${time} on ${day}`;
+}
+
+/**
+ * Create a short human-readable summary for a quota window.
+ *
+ * Safe for concurrent use; does not access the filesystem and never includes or exposes sensitive tokens.
+ *
+ * @param label - Human-friendly label for the window (e.g., "2h", "7d", "quota")
+ * @param window - Quota window fields used to populate the summary (e.g., `usedPercent`, `resetAtMs`)
+ * @returns A single-line summary combining the label, percent left (if available), and reset time (if available), e.g. "2h 40% left (resets 14:05)"
+ */
+function formatWindowSummary(label: string, window: CodexQuotaWindow): string {
+	const used = window.usedPercent;
+	const left =
+		typeof used === "number" && Number.isFinite(used)
+			? Math.max(0, Math.min(100, Math.round(100 - used)))
+			: undefined;
+	const reset = formatResetAt(window.resetAtMs);
+	let summary = label;
+	if (left !== undefined) summary = `${summary} ${left}% left`;
+	if (reset) summary = `${summary} (resets ${reset})`;
+	return summary;
+}
+
+/**
+ * Produce a single-line human-readable summary of a Codex quota snapshot.
+ *
+ * This pure, deterministic formatter is safe for concurrent use, performs no
+ * filesystem side effects (including on Windows), and never exposes secret
+ * tokens or other sensitive values.
+ *
+ * @param snapshot - The quota snapshot to format
+ * @returns A concise, comma-separated summary describing primary and secondary windows, optional plan and active limit, and `rate-limited` when the status is 429
+ */
+export function formatQuotaSnapshotLine(snapshot: CodexQuotaSnapshot): string {
+	const primaryLabel = formatQuotaWindowLabel(snapshot.primary.windowMinutes);
+	const secondaryLabel = formatQuotaWindowLabel(snapshot.secondary.windowMinutes);
+	const parts = [
+		formatWindowSummary(primaryLabel, snapshot.primary),
+		formatWindowSummary(secondaryLabel, snapshot.secondary),
+	];
+	if (snapshot.planType) parts.push(`plan:${snapshot.planType}`);
+	if (typeof snapshot.activeLimit === "number" && Number.isFinite(snapshot.activeLimit)) {
+		parts.push(`active:${snapshot.activeLimit}`);
+	}
+	if (snapshot.status === 429) parts.push("rate-limited");
+	return parts.join(", ");
+}
+
+export interface ProbeCodexQuotaOptions {
+	accountId: string;
+	accessToken: string;
+	model?: string;
+	fallbackModels?: readonly string[];
+	timeoutMs?: number;
+}
+
+/**
+ * Probe Codex models sequentially to obtain a quota snapshot for the specified account.
+ *
+ * Concurrency: models are probed one-at-a-time (no parallel requests).
+ * Filesystem: performs no filesystem access and makes no Windows filesystem calls.
+ * Security: `accessToken` is sent in request headers and is treated as sensitive; tokens are not persisted or written to disk.
+ *
+ * @param options - Probe options including:
+ *   - accountId: account identifier used for Codex requests
+ *   - accessToken: bearer token for authentication (sensitive)
+ *   - model: optional preferred model name to probe first
+ *   - fallbackModels: optional list of fallback model names to try
+ *   - timeoutMs: optional per-model timeout in milliseconds (bounded between 1000 and 60000; default 15000)
+ * @returns The first CodexQuotaSnapshot parsed from response quota headers, augmented with the model that produced it.
+ * @throws If no candidate model produces a quota snapshot, throws the last encountered error or a generic failure error.
+ */
+export async function fetchCodexQuotaSnapshot(
+	options: ProbeCodexQuotaOptions,
+): Promise<CodexQuotaSnapshot> {
+	const models = normalizeProbeModels(options.model, options.fallbackModels);
+	const timeoutMs = Math.max(1_000, Math.min(options.timeoutMs ?? 15_000, 60_000));
+	let lastError: Error | null = null;
+
+	for (const model of models) {
+		try {
+			const instructions = await getCodexInstructions(model);
+			const probeBody: RequestBody = {
+				model,
+				stream: true,
+				store: false,
+				include: ["reasoning.encrypted_content"],
+				instructions,
+				input: [
+					{
+						type: "message",
+						role: "user",
+						content: [{ type: "input_text", text: "quota ping" }],
+					},
+				],
+				reasoning: { effort: "none", summary: "auto" },
+				text: { verbosity: "low" },
+			};
+
+			const headers = createCodexHeaders(undefined, options.accountId, options.accessToken, {
+				model,
+			});
+			headers.set("content-type", "application/json");
+
+			const controller = new AbortController();
+			const timeout = setTimeout(() => controller.abort(), timeoutMs);
+			let response: Response;
+			try {
+				response = await fetch(`${CODEX_BASE_URL}/codex/responses`, {
+					method: "POST",
+					headers,
+					body: JSON.stringify(probeBody),
+					signal: controller.signal,
+				});
+			} finally {
+				clearTimeout(timeout);
+			}
+
+			const snapshotBase = parseQuotaSnapshotBase(response.headers, response.status);
+			if (snapshotBase) {
+				try {
+					await response.body?.cancel();
+				} catch {
+					// Best effort cancellation.
+				}
+				return { ...snapshotBase, model };
+			}
+
+			if (!response.ok) {
+				const bodyText = await response.text().catch(() => "");
+				let errorBody: unknown = undefined;
+				try {
+					errorBody = bodyText ? (JSON.parse(bodyText) as unknown) : undefined;
+				} catch {
+					errorBody = { error: { message: bodyText } };
+				}
+
+				const unsupportedInfo = getUnsupportedCodexModelInfo(errorBody);
+				if (unsupportedInfo.isUnsupported) {
+					lastError = new Error(
+						unsupportedInfo.message ?? `Model '${model}' unsupported for this account`,
+					);
+					continue;
+				}
+
+				throw new Error(extractErrorMessage(bodyText, response.status));
+			}
+
+			try {
+				await response.body?.cancel();
+			} catch {
+				// Best effort cancellation.
+			}
+			lastError = new Error("Codex response did not include quota headers");
+		} catch (error) {
+			lastError = error instanceof Error ? error : new Error(String(error));
+		}
+	}
+
+	throw lastError ?? new Error("Failed to fetch quotas");
+}
diff --git a/lib/recovery/constants.ts b/lib/recovery/constants.ts
index b7a44336..8adf26b2 100644
--- a/lib/recovery/constants.ts
+++ b/lib/recovery/constants.ts
@@ -1,15 +1,21 @@
 /**
  * Constants for session recovery storage paths.
  *
- * Based on opencode-antigravity-auth recovery module.
+ * Adapted from prior recovery module patterns.
  */
 
 import { join } from "node:path";
 import { homedir } from "node:os";
 
 /**
- * Get the XDG data directory for OpenCode storage.
- * Falls back to ~/.local/share on Linux/Mac, or APPDATA on Windows.
+ * Determine the base XDG-style data directory used for Codex storage.
+ *
+ * This function is pure and side-effect free; it is safe to call concurrently from multiple processes.
+ * On Windows it prefers the APPDATA environment variable and falls back to the user's AppData/Roaming directory.
+ * On other platforms it prefers XDG_DATA_HOME and falls back to ~/.local/share.
+ * Returned paths may include the user's home directory; callers should redact or avoid logging any sensitive tokens contained in file names or paths.
+ *
+ * @returns The filesystem path to use as the base data directory for Codex storage.
  */
 function getXdgData(): string {
   const platform = process.platform;
@@ -21,9 +27,9 @@ function getXdgData(): string {
   return process.env.XDG_DATA_HOME || join(homedir(), ".local", "share");
 }
 
-export const OPENCODE_STORAGE = join(getXdgData(), "opencode", "storage");
-export const MESSAGE_STORAGE = join(OPENCODE_STORAGE, "message");
-export const PART_STORAGE = join(OPENCODE_STORAGE, "part");
+export const CODEX_STORAGE = join(getXdgData(), "codex", "storage");
+export const MESSAGE_STORAGE = join(CODEX_STORAGE, "message");
+export const PART_STORAGE = join(CODEX_STORAGE, "part");
 
 export const THINKING_TYPES = new Set(["thinking", "redacted_thinking", "reasoning"]);
 export const META_TYPES = new Set(["step-start", "step-finish"]);
diff --git a/lib/refresh-guardian.ts b/lib/refresh-guardian.ts
new file mode 100644
index 00000000..b40bddd8
--- /dev/null
+++ b/lib/refresh-guardian.ts
@@ -0,0 +1,176 @@
+import { createLogger } from "./logger.js";
+import { applyRefreshResult, refreshExpiringAccounts } from "./proactive-refresh.js";
+import type { AccountManager } from "./accounts.js";
+import type { CooldownReason } from "./storage.js";
+import type { TokenResult } from "./types.js";
+
+const log = createLogger("refresh-guardian");
+
+export interface RefreshGuardianOptions {
+	intervalMs?: number;
+	bufferMs?: number;
+}
+
+export interface RefreshGuardianStats {
+	runs: number;
+	refreshed: number;
+	failed: number;
+	notNeeded: number;
+	noRefreshToken: number;
+	rateLimited: number;
+	networkFailed: number;
+	authFailed: number;
+	lastRunAt: number | null;
+}
+
+const DEFAULT_INTERVAL_MS = 60_000;
+
+export class RefreshGuardian {
+	private readonly getAccountManager: () => AccountManager | null;
+	private readonly intervalMs: number;
+	private readonly bufferMs: number;
+	private timer: ReturnType<typeof setInterval> | null = null;
+	private running = false;
+	private stats: RefreshGuardianStats = {
+		runs: 0,
+		refreshed: 0,
+		failed: 0,
+		notNeeded: 0,
+		noRefreshToken: 0,
+		rateLimited: 0,
+		networkFailed: 0,
+		authFailed: 0,
+		lastRunAt: null,
+	};
+
+	constructor(
+		getAccountManager: () => AccountManager | null,
+		options: RefreshGuardianOptions = {},
+	) {
+		this.getAccountManager = getAccountManager;
+		this.intervalMs = Math.max(5_000, Math.floor(options.intervalMs ?? DEFAULT_INTERVAL_MS));
+		this.bufferMs = Math.max(30_000, Math.floor(options.bufferMs ?? 5 * 60_000));
+	}
+
+	start(): void {
+		if (this.timer) return;
+		this.timer = setInterval(() => {
+			void this.tick();
+		}, this.intervalMs);
+		if (typeof this.timer === "object" && "unref" in this.timer && typeof this.timer.unref === "function") {
+			this.timer.unref();
+		}
+		log.debug("Refresh guardian started", {
+			intervalMs: this.intervalMs,
+			bufferMs: this.bufferMs,
+		});
+	}
+
+	stop(): void {
+		if (!this.timer) return;
+		clearInterval(this.timer);
+		this.timer = null;
+	}
+
+	getStats(): RefreshGuardianStats {
+		return { ...this.stats };
+	}
+
+	private classifyFailureReason(tokenResult: TokenResult | undefined): CooldownReason {
+		if (!tokenResult || tokenResult.type !== "failed") {
+			return "network-error";
+		}
+
+		const statusCode = tokenResult.statusCode;
+		if (statusCode === 429) return "rate-limit";
+		if (tokenResult.reason === "network_error") return "network-error";
+		if (tokenResult.reason === "missing_refresh") return "auth-failure";
+		if (tokenResult.reason === "invalid_response") return "auth-failure";
+		if (
+			tokenResult.reason === "http_error" &&
+			(statusCode === 400 || statusCode === 401 || statusCode === 403)
+		) {
+			return "auth-failure";
+		}
+		return "network-error";
+	}
+
+	async tick(): Promise<void> {
+		if (this.running) return;
+		const manager = this.getAccountManager();
+		if (!manager) return;
+		this.running = true;
+		try {
+			const snapshot = manager.getAccountsSnapshot().filter((account) => account.enabled !== false);
+			if (snapshot.length === 0) {
+				return;
+			}
+
+			const refreshResults = await refreshExpiringAccounts(snapshot, this.bufferMs);
+			if (refreshResults.size === 0) {
+				this.stats.runs += 1;
+				this.stats.lastRunAt = Date.now();
+				return;
+			}
+
+			const snapshotByIndex = new Map<number, (typeof snapshot)[number]>();
+			for (const candidate of snapshot) {
+				snapshotByIndex.set(candidate.index, candidate);
+			}
+
+			for (const [accountIndex, result] of refreshResults.entries()) {
+				const sourceAccount = snapshotByIndex.get(accountIndex);
+				if (!sourceAccount) continue;
+				const liveAccounts = manager.getAccountsSnapshot();
+				const resolvedIndex = liveAccounts.findIndex(
+					(candidate) => candidate.refreshToken === sourceAccount.refreshToken,
+				);
+				const account = resolvedIndex >= 0 ? manager.getAccountByIndex(resolvedIndex) : null;
+				if (!account) continue;
+
+				switch (result.reason) {
+					case "success":
+						if (result.tokenResult?.type === "success") {
+							applyRefreshResult(account, result.tokenResult);
+							manager.clearAuthFailures(account);
+							this.stats.refreshed += 1;
+						} else {
+							manager.markAccountCoolingDown(account, this.bufferMs, "network-error");
+							this.stats.failed += 1;
+							this.stats.networkFailed += 1;
+						}
+						break;
+					case "failed": {
+						const cooldownReason = this.classifyFailureReason(result.tokenResult);
+						manager.markAccountCoolingDown(account, this.bufferMs, cooldownReason);
+						this.stats.failed += 1;
+						if (cooldownReason === "rate-limit") this.stats.rateLimited += 1;
+						else if (cooldownReason === "auth-failure") this.stats.authFailed += 1;
+						else this.stats.networkFailed += 1;
+						break;
+					}
+					case "not_needed":
+						this.stats.notNeeded += 1;
+						break;
+					case "no_refresh_token":
+						manager.markAccountCoolingDown(account, this.bufferMs, "auth-failure");
+						manager.setAccountEnabled(account.index, false);
+						this.stats.noRefreshToken += 1;
+						this.stats.failed += 1;
+						this.stats.authFailed += 1;
+						break;
+				}
+			}
+
+			manager.saveToDiskDebounced();
+			this.stats.runs += 1;
+			this.stats.lastRunAt = Date.now();
+		} catch (error) {
+			log.warn("Refresh guardian tick failed", {
+				error: error instanceof Error ? error.message : String(error),
+			});
+		} finally {
+			this.running = false;
+		}
+	}
+}
diff --git a/lib/refresh-lease.ts b/lib/refresh-lease.ts
new file mode 100644
index 00000000..fe524a06
--- /dev/null
+++ b/lib/refresh-lease.ts
@@ -0,0 +1,403 @@
+import { createHash } from "node:crypto";
+import { existsSync, promises as fs } from "node:fs";
+import { join } from "node:path";
+import { createLogger } from "./logger.js";
+import { getCodexMultiAuthDir } from "./runtime-paths.js";
+import { safeParseTokenResult } from "./schemas.js";
+import type { TokenResult } from "./types.js";
+
+const log = createLogger("refresh-lease");
+
+const DEFAULT_LEASE_TTL_MS = 30_000;
+const DEFAULT_WAIT_TIMEOUT_MS = 35_000;
+const DEFAULT_POLL_INTERVAL_MS = 150;
+const DEFAULT_RESULT_TTL_MS = 20_000;
+const RETRYABLE_IO_ERRORS = new Set(["EBUSY", "EPERM", "EMFILE", "ENFILE"]);
+
+interface LeaseFilePayload {
+	tokenHash: string;
+	pid: number;
+	acquiredAt: number;
+	expiresAt: number;
+}
+
+interface ResultFilePayload {
+	tokenHash: string;
+	createdAt: number;
+	result: TokenResult;
+}
+
+type LeaseFsOps = Pick<
+	typeof fs,
+	"mkdir" | "open" | "writeFile" | "rename" | "unlink" | "readFile" | "stat" | "readdir"
+>;
+
+export interface RefreshLeaseCoordinatorOptions {
+	enabled?: boolean;
+	leaseDir?: string;
+	leaseTtlMs?: number;
+	waitTimeoutMs?: number;
+	pollIntervalMs?: number;
+	resultTtlMs?: number;
+	fsOps?: LeaseFsOps;
+}
+
+export interface RefreshLeaseHandle {
+	role: "owner" | "follower" | "bypass";
+	result?: TokenResult;
+	release: (result?: TokenResult) => Promise<void>;
+}
+
+function parseBooleanEnv(value: string | undefined): boolean | undefined {
+	if (value === undefined) return undefined;
+	const normalized = value.trim().toLowerCase();
+	if (normalized === "1" || normalized === "true" || normalized === "yes") return true;
+	if (normalized === "0" || normalized === "false" || normalized === "no") return false;
+	return undefined;
+}
+
+function parseEnvInt(value: string | undefined): number | undefined {
+	if (value === undefined) return undefined;
+	const parsed = Number.parseInt(value, 10);
+	return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+function sleep(delayMs: number): Promise<void> {
+	return new Promise((resolve) => {
+		setTimeout(resolve, delayMs);
+	});
+}
+
+function hashRefreshToken(refreshToken: string): string {
+	return createHash("sha256").update(refreshToken).digest("hex");
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === "object";
+}
+
+function parseLeasePayload(raw: unknown): LeaseFilePayload | null {
+	if (!isRecord(raw)) return null;
+	const tokenHash = typeof raw.tokenHash === "string" ? raw.tokenHash : "";
+	const pid = typeof raw.pid === "number" ? raw.pid : Number.NaN;
+	const acquiredAt = typeof raw.acquiredAt === "number" ? raw.acquiredAt : Number.NaN;
+	const expiresAt = typeof raw.expiresAt === "number" ? raw.expiresAt : Number.NaN;
+	if (
+		tokenHash.length === 0 ||
+		!Number.isFinite(pid) ||
+		!Number.isFinite(acquiredAt) ||
+		!Number.isFinite(expiresAt)
+	) {
+		return null;
+	}
+	return {
+		tokenHash,
+		pid: Math.floor(pid),
+		acquiredAt: Math.floor(acquiredAt),
+		expiresAt: Math.floor(expiresAt),
+	};
+}
+
+function parseResultPayload(raw: unknown): ResultFilePayload | null {
+	if (!isRecord(raw)) return null;
+	const tokenHash = typeof raw.tokenHash === "string" ? raw.tokenHash : "";
+	const createdAt = typeof raw.createdAt === "number" ? raw.createdAt : Number.NaN;
+	const result = safeParseTokenResult(raw.result);
+	if (tokenHash.length === 0 || !Number.isFinite(createdAt) || !result) return null;
+	return {
+		tokenHash,
+		createdAt: Math.floor(createdAt),
+		result,
+	};
+}
+
+async function readJson(path: string, fsOps: LeaseFsOps): Promise<unknown | null> {
+	try {
+		const content = await fsOps.readFile(path, "utf8");
+		return JSON.parse(content) as unknown;
+	} catch {
+		return null;
+	}
+}
+
+async function safeUnlink(
+	path: string,
+	options?: { attempts?: number; baseDelayMs?: number },
+	fsOps: LeaseFsOps = fs,
+): Promise<boolean> {
+	const attempts = Math.max(1, Math.floor(options?.attempts ?? 4));
+	const baseDelayMs = Math.max(5, Math.floor(options?.baseDelayMs ?? 15));
+	for (let attempt = 0; attempt < attempts; attempt++) {
+		try {
+			await fsOps.unlink(path);
+			return true;
+		} catch (error) {
+			const code = (error as NodeJS.ErrnoException).code;
+			if (code === "ENOENT") return true;
+			const canRetry = RETRYABLE_IO_ERRORS.has(code ?? "");
+			if (canRetry && attempt + 1 < attempts) {
+				await sleep(baseDelayMs * (2 ** attempt));
+				continue;
+			}
+			log.debug("Failed to remove lease artifact", {
+				path,
+				error: error instanceof Error ? error.message : String(error),
+				code,
+			});
+			return false;
+		}
+	}
+	return false;
+}
+
+type LockStalenessAssessment =
+	| { state: "stale"; reason: string }
+	| { state: "active"; reason: string }
+	| { state: "unknown"; reason: string };
+
+function isRetryableFsCode(code: string | undefined): boolean {
+	return RETRYABLE_IO_ERRORS.has(code ?? "");
+}
+
+export class RefreshLeaseCoordinator {
+	private readonly enabled: boolean;
+	private readonly leaseDir: string;
+	private readonly leaseTtlMs: number;
+	private readonly waitTimeoutMs: number;
+	private readonly pollIntervalMs: number;
+	private readonly resultTtlMs: number;
+	private readonly fsOps: LeaseFsOps;
+
+	constructor(options: RefreshLeaseCoordinatorOptions = {}) {
+		this.enabled = options.enabled ?? true;
+		this.leaseDir = options.leaseDir ?? join(getCodexMultiAuthDir(), "refresh-leases");
+		this.leaseTtlMs = Math.max(1_000, Math.floor(options.leaseTtlMs ?? DEFAULT_LEASE_TTL_MS));
+		this.waitTimeoutMs = Math.max(0, Math.floor(options.waitTimeoutMs ?? DEFAULT_WAIT_TIMEOUT_MS));
+		this.pollIntervalMs = Math.max(50, Math.floor(options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS));
+		this.resultTtlMs = Math.max(1_000, Math.floor(options.resultTtlMs ?? DEFAULT_RESULT_TTL_MS));
+		this.fsOps = options.fsOps ?? fs;
+	}
+
+	static fromEnvironment(): RefreshLeaseCoordinator {
+		const testMode = process.env.VITEST === "true" || process.env.NODE_ENV === "test";
+		const enabled =
+			parseBooleanEnv(process.env.CODEX_AUTH_REFRESH_LEASE) ??
+			(testMode ? false : true);
+		return new RefreshLeaseCoordinator({
+			enabled,
+			leaseDir:
+				(process.env.CODEX_AUTH_REFRESH_LEASE_DIR ?? "").trim() || undefined,
+			leaseTtlMs: parseEnvInt(process.env.CODEX_AUTH_REFRESH_LEASE_TTL_MS),
+			waitTimeoutMs: parseEnvInt(process.env.CODEX_AUTH_REFRESH_LEASE_WAIT_MS),
+			pollIntervalMs: parseEnvInt(process.env.CODEX_AUTH_REFRESH_LEASE_POLL_MS),
+			resultTtlMs: parseEnvInt(process.env.CODEX_AUTH_REFRESH_LEASE_RESULT_TTL_MS),
+		});
+	}
+
+	async acquire(refreshToken: string): Promise<RefreshLeaseHandle> {
+		if (!this.enabled) {
+			return this.createBypassHandle("disabled");
+		}
+		if (refreshToken.trim().length === 0) {
+			return this.createBypassHandle("empty-token");
+		}
+
+		const tokenHash = hashRefreshToken(refreshToken);
+		const lockPath = join(this.leaseDir, `${tokenHash}.lock`);
+		const resultPath = join(this.leaseDir, `${tokenHash}.result.json`);
+		await this.fsOps.mkdir(this.leaseDir, { recursive: true });
+		void this.pruneExpiredArtifacts();
+
+		const deadline = Date.now() + this.waitTimeoutMs;
+		while (true) {
+			const cachedResult = await this.readFreshResult(resultPath, tokenHash);
+			if (cachedResult) {
+				return {
+					role: "follower",
+					result: cachedResult,
+					release: async () => {
+						// Follower does not own lock.
+					},
+				};
+			}
+
+			try {
+				const handle = await this.fsOps.open(lockPath, "wx");
+				try {
+					const now = Date.now();
+					const payload: LeaseFilePayload = {
+						tokenHash,
+						pid: process.pid,
+						acquiredAt: now,
+						expiresAt: now + this.leaseTtlMs,
+					};
+					await handle.writeFile(`${JSON.stringify(payload)}\n`, "utf8");
+				} finally {
+					await handle.close();
+				}
+
+				return this.createOwnerHandle(tokenHash, lockPath, resultPath);
+			} catch (error) {
+				const code = (error as NodeJS.ErrnoException).code;
+				if (code !== "EEXIST") {
+					log.warn("Refresh lease acquisition failed; proceeding without lease", {
+						error: error instanceof Error ? error.message : String(error),
+					});
+					return this.createBypassHandle("acquire-error");
+				}
+
+				const stale = await this.assessLockStaleness(lockPath, tokenHash);
+				if (stale.state === "stale") {
+					const removed = await safeUnlink(lockPath, undefined, this.fsOps);
+					if (removed) continue;
+					if (Date.now() >= deadline) {
+						log.warn("Refresh lease wait timeout while stale lock could not be removed", {
+							waitTimeoutMs: this.waitTimeoutMs,
+						});
+						return this.createBypassHandle("wait-timeout");
+					}
+					await sleep(this.pollIntervalMs);
+					continue;
+				}
+
+				if (Date.now() >= deadline) {
+					log.warn("Refresh lease wait timeout; proceeding without lease", {
+						waitTimeoutMs: this.waitTimeoutMs,
+					});
+					return this.createBypassHandle("wait-timeout");
+				}
+				await sleep(this.pollIntervalMs);
+			}
+		}
+	}
+
+	private createBypassHandle(reason: string): RefreshLeaseHandle {
+		log.debug("Bypassing refresh lease", { reason });
+		return {
+			role: "bypass",
+			release: async () => {
+				// No-op
+			},
+		};
+	}
+
+	private createOwnerHandle(
+		tokenHash: string,
+		lockPath: string,
+		resultPath: string,
+	): RefreshLeaseHandle {
+		let released = false;
+		return {
+			role: "owner",
+			release: async (result?: TokenResult) => {
+				if (released) return;
+				released = true;
+				try {
+					if (result) {
+						await this.writeResult(resultPath, tokenHash, result);
+					}
+				} finally {
+					await safeUnlink(lockPath, undefined, this.fsOps);
+				}
+			},
+		};
+	}
+
+	private async writeResult(
+		resultPath: string,
+		tokenHash: string,
+		result: TokenResult,
+	): Promise<void> {
+		const payload: ResultFilePayload = {
+			tokenHash,
+			createdAt: Date.now(),
+			result,
+		};
+		const tempPath = `${resultPath}.${process.pid}.${Date.now()}.tmp`;
+		try {
+			await this.fsOps.writeFile(tempPath, `${JSON.stringify(payload)}\n`, "utf8");
+			await this.fsOps.rename(tempPath, resultPath);
+		} finally {
+			await safeUnlink(tempPath, undefined, this.fsOps);
+		}
+	}
+
+	private async readFreshResult(
+		resultPath: string,
+		tokenHash: string,
+	): Promise<TokenResult | null> {
+		if (!existsSync(resultPath)) return null;
+		const parsed = parseResultPayload(await readJson(resultPath, this.fsOps));
+		if (!parsed || parsed.tokenHash !== tokenHash) {
+			return null;
+		}
+		const ageMs = Date.now() - parsed.createdAt;
+		if (ageMs > this.resultTtlMs) {
+			await safeUnlink(resultPath, undefined, this.fsOps);
+			return null;
+		}
+		return parsed.result;
+	}
+
+	private async assessLockStaleness(
+		lockPath: string,
+		tokenHash: string,
+	): Promise<LockStalenessAssessment> {
+		const raw = await readJson(lockPath, this.fsOps);
+		if (raw === null) {
+			if (!existsSync(lockPath)) {
+				return { state: "stale", reason: "missing" };
+			}
+			return { state: "unknown", reason: "unreadable" };
+		}
+
+		const parsed = parseLeasePayload(raw);
+		if (!parsed) {
+			return { state: "unknown", reason: "invalid-payload" };
+		}
+		if (parsed.tokenHash !== tokenHash) {
+			return { state: "unknown", reason: "token-mismatch" };
+		}
+		if (parsed.expiresAt <= Date.now()) {
+			return { state: "stale", reason: "expired" };
+		}
+
+		try {
+			const stat = await this.fsOps.stat(lockPath);
+			if (Date.now() - stat.mtimeMs > this.leaseTtlMs) {
+				return { state: "stale", reason: "mtime-expired" };
+			}
+			return { state: "active", reason: "fresh" };
+		} catch (error) {
+			const code = (error as NodeJS.ErrnoException).code;
+			if (code === "ENOENT") return { state: "stale", reason: "missing" };
+			if (isRetryableFsCode(code) || code === "EACCES") {
+				return { state: "unknown", reason: `stat-${String(code).toLowerCase()}` };
+			}
+			return { state: "unknown", reason: "stat-error" };
+		}
+	}
+
+	private async pruneExpiredArtifacts(): Promise<void> {
+		try {
+			const entries = await this.fsOps.readdir(this.leaseDir, { withFileTypes: true });
+			const now = Date.now();
+			const maxAgeMs = Math.max(this.leaseTtlMs, this.resultTtlMs) * 2;
+			for (const entry of entries) {
+				if (!entry.isFile()) continue;
+				if (!entry.name.endsWith(".lock") && !entry.name.endsWith(".result.json")) continue;
+				const fullPath = join(this.leaseDir, entry.name);
+				try {
+					const stat = await this.fsOps.stat(fullPath);
+					if (now - stat.mtimeMs > maxAgeMs) {
+						await safeUnlink(fullPath, undefined, this.fsOps);
+					}
+				} catch {
+					// Best effort.
+				}
+			}
+		} catch {
+			// Best effort.
+		}
+	}
+}
diff --git a/lib/refresh-queue.ts b/lib/refresh-queue.ts
index fe610759..be81f1f3 100644
--- a/lib/refresh-queue.ts
+++ b/lib/refresh-queue.ts
@@ -11,6 +11,7 @@
 import { refreshAccessToken } from "./auth/auth.js";
 import type { TokenResult } from "./types.js";
 import { createLogger } from "./logger.js";
+import { RefreshLeaseCoordinator } from "./refresh-lease.js";
 
 const log = createLogger("refresh-queue");
 
@@ -55,6 +56,7 @@ interface RefreshEntry {
  */
 export class RefreshQueue {
   private pending: Map<string, RefreshEntry> = new Map();
+  private readonly leaseCoordinator: RefreshLeaseCoordinator;
   
   /**
    * Maps old refresh tokens to new tokens after rotation.
@@ -74,8 +76,12 @@ export class RefreshQueue {
    * Create a new RefreshQueue instance.
    * @param maxEntryAgeMs - Maximum age for pending entries before cleanup (default: 30s)
    */
-  constructor(maxEntryAgeMs: number = 30_000) {
+  constructor(
+    maxEntryAgeMs: number = 30_000,
+    leaseCoordinator: RefreshLeaseCoordinator = RefreshLeaseCoordinator.fromEnvironment(),
+  ) {
     this.maxEntryAgeMs = maxEntryAgeMs;
+    this.leaseCoordinator = leaseCoordinator;
   }
 
   /**
@@ -115,10 +121,49 @@ export class RefreshQueue {
       }
     }
 
-    // Start a new refresh
+    // Start a new refresh immediately so local state reflects "in-flight"
+    // without waiting on cross-process lease checks.
     const startedAt = Date.now();
-    const promise = this.executeRefreshWithRotationTracking(refreshToken);
+    const promise = (async (): Promise<TokenResult> => {
+      let lease: Awaited<ReturnType<RefreshLeaseCoordinator["acquire"]>>;
+      try {
+        lease = await this.leaseCoordinator.acquire(refreshToken);
+      } catch (error) {
+        log.warn("Refresh lease acquire failed; falling back to local refresh", {
+          tokenSuffix: refreshToken.slice(-6),
+          error: (error as Error)?.message ?? String(error),
+        });
+        return this.executeRefreshWithRotationTracking(refreshToken);
+      }
+      if (lease.role === "follower" && lease.result) {
+        log.info("Using refresh result from cross-process lease", {
+          tokenSuffix: refreshToken.slice(-6),
+        });
+        return lease.result;
+      }
 
+      try {
+        const result = await this.executeRefreshWithRotationTracking(refreshToken);
+        try {
+          await lease.release(result);
+        } catch (error) {
+          log.warn("Failed to publish lease refresh result", {
+            tokenSuffix: refreshToken.slice(-6),
+            error: (error as Error)?.message ?? String(error),
+          });
+        }
+        return result;
+      } finally {
+        try {
+          await lease.release();
+        } catch (error) {
+          log.warn("Failed to release refresh lease", {
+            tokenSuffix: refreshToken.slice(-6),
+            error: (error as Error)?.message ?? String(error),
+          });
+        }
+      }
+    })();
     this.pending.set(refreshToken, { promise, startedAt });
 
     try {
diff --git a/lib/request/failure-policy.ts b/lib/request/failure-policy.ts
new file mode 100644
index 00000000..28572345
--- /dev/null
+++ b/lib/request/failure-policy.ts
@@ -0,0 +1,181 @@
+import { ACCOUNT_LIMITS } from "../constants.js";
+import type { CooldownReason } from "../storage.js";
+
+export type FailureKind =
+	| "auth-refresh"
+	| "network"
+	| "server"
+	| "rate-limit"
+	| "empty-response";
+
+export type FailoverMode = "aggressive" | "balanced" | "conservative";
+
+export interface FailurePolicyInput {
+	kind: FailureKind;
+	consecutiveAuthFailures?: number;
+	maxAuthFailuresBeforeRemoval?: number;
+	serverRetryAfterMs?: number;
+	failoverMode?: FailoverMode;
+}
+
+export interface FailurePolicyDecision {
+	rotateAccount: boolean;
+	refundToken: boolean;
+	recordFailure: boolean;
+	markRateLimited: boolean;
+	removeAccount: boolean;
+	cooldownMs?: number;
+	cooldownReason?: CooldownReason;
+	retrySameAccount: boolean;
+	retryDelayMs?: number;
+	handoffStrategy: "soft" | "hard";
+}
+
+const DEFAULT_NETWORK_COOLDOWN_MS = 6_000;
+const DEFAULT_SERVER_COOLDOWN_MS = 4_000;
+const NETWORK_RETRY_DELAY_MS: Record<FailoverMode, number> = {
+	aggressive: 0,
+	balanced: 250,
+	conservative: 900,
+};
+const EMPTY_RESPONSE_RETRY_DELAY_MS: Record<FailoverMode, number> = {
+	aggressive: 0,
+	balanced: 200,
+	conservative: 600,
+};
+
+/**
+ * Selects the failover mode provided on the input or uses `aggressive` when not set.
+ *
+ * This is a pure, concurrency-safe helper with no filesystem side effects (including on Windows)
+ * and does not log or expose tokens from its input.
+ *
+ * @param input - Failure policy input that may contain an optional `failoverMode`
+ * @returns The chosen failover mode: `aggressive`, `balanced`, or `conservative` (defaults to `aggressive`)
+ */
+function getFailoverMode(input: FailurePolicyInput): FailoverMode {
+	return input.failoverMode ?? "aggressive";
+}
+
+/**
+ * Compute a FailurePolicyDecision that specifies how to handle a failure described by `input`.
+ *
+ * Evaluates the provided failure kind and related hints to decide whether to rotate or remove an account,
+ * refund a token, record or mark the failure, apply a cooldown, retry on the same account (and with what delay),
+ * and choose a handoff strategy.
+ *
+ * Concurrency assumptions: this function is pure and safe to call concurrently from multiple threads/processes.
+ * Filesystem notes: no filesystem access is performed (no Windows-specific behavior).
+ * Token redaction: decisions may set `refundToken` to true/false but this function does not log or expose token values.
+ *
+ * @param input - Configuration and hints for the failure policy (must include `kind`; may include `consecutiveAuthFailures`, `maxAuthFailuresBeforeRemoval`, `serverRetryAfterMs`, and `failoverMode`).
+ * @param overrides - Optional environment overrides: `networkCooldownMs` and `serverCooldownMs` adjust fallback cooldown values.
+ * @returns A FailurePolicyDecision object describing rotation, refund, recording, rate-limit marking, removal, cooldown and retry behavior, and the chosen handoff strategy.
+ */
+export function evaluateFailurePolicy(
+	input: FailurePolicyInput,
+	overrides?: {
+		networkCooldownMs?: number;
+		serverCooldownMs?: number;
+	},
+): FailurePolicyDecision {
+	switch (input.kind) {
+		case "auth-refresh": {
+			const failures = Math.max(0, Math.floor(input.consecutiveAuthFailures ?? 0));
+			const maxFailures = Math.max(
+				1,
+				Math.floor(input.maxAuthFailuresBeforeRemoval ?? ACCOUNT_LIMITS.MAX_AUTH_FAILURES_BEFORE_REMOVAL),
+			);
+			return {
+				rotateAccount: true,
+				refundToken: false,
+				recordFailure: false,
+				markRateLimited: false,
+				removeAccount: failures >= maxFailures,
+				cooldownMs: ACCOUNT_LIMITS.AUTH_FAILURE_COOLDOWN_MS,
+				cooldownReason: "auth-failure",
+				retrySameAccount: false,
+				handoffStrategy: "hard",
+			};
+		}
+		case "network": {
+			const mode = getFailoverMode(input);
+			const cooldownMs = Math.max(
+				0,
+				Math.floor(overrides?.networkCooldownMs ?? DEFAULT_NETWORK_COOLDOWN_MS),
+			);
+			const retryDelayMs = NETWORK_RETRY_DELAY_MS[mode];
+			const retrySameAccount = retryDelayMs > 0;
+			return {
+				rotateAccount: !retrySameAccount,
+				refundToken: true,
+				recordFailure: true,
+				markRateLimited: false,
+				removeAccount: false,
+				cooldownMs,
+				cooldownReason: cooldownMs > 0 ? "network-error" : undefined,
+				retrySameAccount,
+				retryDelayMs: retrySameAccount ? retryDelayMs : undefined,
+				handoffStrategy: "soft",
+			};
+		}
+		case "server": {
+			const mode = getFailoverMode(input);
+			const retryAfterMs = Math.max(0, Math.floor(input.serverRetryAfterMs ?? 0));
+			const fallbackCooldown = Math.max(
+				0,
+				Math.floor(overrides?.serverCooldownMs ?? DEFAULT_SERVER_COOLDOWN_MS),
+			);
+			const cooldownMs = retryAfterMs > 0 ? retryAfterMs : fallbackCooldown;
+			const retrySameAccount = mode === "conservative" && retryAfterMs <= 0;
+			return {
+				rotateAccount: !retrySameAccount,
+				refundToken: true,
+				recordFailure: true,
+				markRateLimited: false,
+				removeAccount: false,
+				cooldownMs,
+				cooldownReason: cooldownMs > 0 ? "network-error" : undefined,
+				retrySameAccount,
+				retryDelayMs: retrySameAccount ? 500 : undefined,
+				handoffStrategy: "hard",
+			};
+		}
+		case "rate-limit": {
+			return {
+				rotateAccount: true,
+				refundToken: false,
+				recordFailure: false,
+				markRateLimited: true,
+				removeAccount: false,
+				retrySameAccount: false,
+				handoffStrategy: "hard",
+			};
+		}
+		case "empty-response": {
+			const mode = getFailoverMode(input);
+			const retryDelayMs = EMPTY_RESPONSE_RETRY_DELAY_MS[mode];
+			const retrySameAccount = retryDelayMs > 0;
+			return {
+				rotateAccount: !retrySameAccount,
+				refundToken: true,
+				recordFailure: true,
+				markRateLimited: false,
+				removeAccount: false,
+				retrySameAccount,
+				retryDelayMs: retrySameAccount ? retryDelayMs : undefined,
+				handoffStrategy: "soft",
+			};
+		}
+		default:
+			return {
+				rotateAccount: true,
+				refundToken: true,
+				recordFailure: true,
+				markRateLimited: false,
+				removeAccount: false,
+				retrySameAccount: false,
+				handoffStrategy: "hard",
+			};
+	}
+}
diff --git a/lib/request/fetch-helpers.ts b/lib/request/fetch-helpers.ts
index 03c2b36e..c10209c7 100644
--- a/lib/request/fetch-helpers.ts
+++ b/lib/request/fetch-helpers.ts
@@ -222,11 +222,14 @@ export function shouldFallbackToGpt52OnUnsupportedGpt53(
 }
 
 /**
- * Checks if an error code indicates an entitlement/subscription issue
- * These errors should NOT be treated as rate limits because:
- * 1. They won't resolve by waiting
- * 2. They won't resolve by switching accounts (all accounts likely have same issue)
- * 3. User needs to upgrade their subscription
+ * Detects whether an error code or response body indicates an entitlement/subscription issue for Codex models.
+ *
+ * Entitlement errors signal that the requested feature is not included in the user's plan and should not be treated as rate limits.
+ * This function is pure and safe to call concurrently; it performs no filesystem access (including on Windows) and does not read or redact tokens — callers must avoid passing sensitive credentials in `code` or `bodyText`.
+ *
+ * @param code - The error code string returned by the service
+ * @param bodyText - The response body text to inspect for entitlement-related phrases
+ * @returns `true` if the combined `code` or `bodyText` indicates an entitlement/subscription issue, `false` otherwise
  */
 export function isEntitlementError(code: string, bodyText: string): boolean {
         const haystack = `${code} ${bodyText}`.toLowerCase();
@@ -236,13 +239,24 @@ export function isEntitlementError(code: string, bodyText: string): boolean {
 }
 
 /**
- * Creates a user-friendly entitlement error response
+ * Constructs a standardized 403 entitlement error Response indicating the user lacks access to Codex models.
+ *
+ * This function returns a JSON Response with an `error` payload containing a user-facing message, a
+ * `type` of `"entitlement_error"`, and a `code` of `"usage_not_included"`. The message suggests checking
+ * account/workspace access and re-authenticating with `codex login`.
+ *
+ * Concurrency: stateless and safe to call concurrently from multiple threads or requests.
+ * Windows filesystem behavior: none (function does not access the filesystem).
+ * Token redaction: any tokens are not included in the generated payload; do not pass sensitive tokens in `_bodyText`.
+ *
+ * @param _bodyText - Original response body text (accepted for compatibility; ignored when building the response)
+ * @returns A 403 Response with a JSON body describing the entitlement error and guidance for resolving it
  */
 export function createEntitlementErrorResponse(_bodyText: string): Response {
         const message = 
                 "This model is not included in your ChatGPT subscription. " +
                 "Please check that your account or workspace has access to Codex models (Plus/Pro/Business/Enterprise). " +
-                "If you recently subscribed or switched workspaces, try logging out and back in with `opencode auth login`.";
+                "If you recently subscribed or switched workspaces, try logging out and back in with `codex login`.";
         
         const payload = {
                 error: {
@@ -682,6 +696,22 @@ type ErrorPayload = {
         };
 };
 
+/**
+ * Build a normalized ErrorPayload from a raw response body, status, and diagnostics.
+ *
+ * Produces a structured error object by preferring explicit error fields in `errorBody`, falling back to `bodyText`, `statusText`, or a generic message; special-cases Codex ChatGPT unsupported-model entitlement errors and appends diagnostic info when provided.
+ *
+ * @param errorBody - Parsed response body, if available; may be any JSON-derived value.
+ * @param bodyText - Raw response text used as a fallback message when structured fields are absent.
+ * @param statusText - HTTP status text used as a final fallback for the error message.
+ * @param status - HTTP status code; when 401 adds a short hint to run `codex login`.
+ * @param diagnostics - Optional diagnostic metadata (request IDs, correlation/thread IDs); fields may be redacted for tokens and sensitive values.
+ * @returns The normalized ErrorPayload with an `error.message` and optional `type`, `code`, `unsupported_model`, and `diagnostics` fields.
+ *
+ * Concurrency: pure and safe to call concurrently from multiple threads/tasks.
+ * Filesystem: performs no filesystem I/O and has no Windows-specific behavior.
+ * Token redaction: callers should assume diagnostic fields may be redacted to avoid leaking credentials.
+ */
 function normalizeErrorPayload(
         errorBody: unknown,
         bodyText: string,
@@ -729,7 +759,7 @@ function normalizeErrorPayload(
                                 payload.error.diagnostics = diagnostics;
                         }
                         if (status === HTTP_STATUS.UNAUTHORIZED) {
-                                payload.error.message = `${payload.error.message} (run \`opencode auth login\` if this persists)`;
+                                payload.error.message = `${payload.error.message} (run \`codex login\` if this persists)`;
                         }
                         return payload;
                 }
@@ -740,7 +770,7 @@ function normalizeErrorPayload(
                                 payload.error.diagnostics = diagnostics;
                         }
                         if (status === HTTP_STATUS.UNAUTHORIZED) {
-                                payload.error.message = `${payload.error.message} (run \`opencode auth login\` if this persists)`;
+                                payload.error.message = `${payload.error.message} (run \`codex login\` if this persists)`;
                         }
                         return payload;
                 }
@@ -753,7 +783,7 @@ function normalizeErrorPayload(
                         payload.error.diagnostics = diagnostics;
                 }
                 if (status === HTTP_STATUS.UNAUTHORIZED) {
-                        payload.error.message = `${payload.error.message} (run \`opencode auth login\` if this persists)`;
+                        payload.error.message = `${payload.error.message} (run \`codex login\` if this persists)`;
                 }
                 return payload;
         }
@@ -764,7 +794,7 @@ function normalizeErrorPayload(
                         payload.error.diagnostics = diagnostics;
                 }
                 if (status === HTTP_STATUS.UNAUTHORIZED) {
-                        payload.error.message = `${payload.error.message} (run \`opencode auth login\` if this persists)`;
+                        payload.error.message = `${payload.error.message} (run \`codex login\` if this persists)`;
                 }
                 return payload;
         }
@@ -774,7 +804,7 @@ function normalizeErrorPayload(
                 payload.error.diagnostics = diagnostics;
         }
         if (status === HTTP_STATUS.UNAUTHORIZED) {
-                payload.error.message = `${payload.error.message} (run \`opencode auth login\` if this persists)`;
+                payload.error.message = `${payload.error.message} (run \`codex login\` if this persists)`;
         }
         return payload;
 }
diff --git a/lib/request/stream-failover.ts b/lib/request/stream-failover.ts
new file mode 100644
index 00000000..0dced4e1
--- /dev/null
+++ b/lib/request/stream-failover.ts
@@ -0,0 +1,234 @@
+import { ensureContentType } from "./response-handler.js";
+
+export interface StreamFailoverOptions {
+	maxFailovers?: number;
+	stallTimeoutMs?: number;
+	softTimeoutMs?: number;
+	hardTimeoutMs?: number;
+	requestInstanceId?: string;
+}
+
+const DEFAULT_MAX_FAILOVERS = 1;
+const DEFAULT_STALL_TIMEOUT_MS = 45_000;
+const DEFAULT_SOFT_TIMEOUT_MS = 15_000;
+const MAX_REQUEST_INSTANCE_ID_LENGTH = 64;
+
+class StallTimeoutError extends Error {
+	readonly isStallTimeout = true;
+
+	constructor(timeoutMs: number) {
+		super(`SSE stream stalled for ${timeoutMs}ms`);
+		this.name = "StallTimeoutError";
+	}
+}
+
+/**
+ * Read a single chunk from `reader`, rejecting if no chunk is produced within `timeoutMs`.
+ *
+ * Assumes the provided reader is not read concurrently by other callers. This function performs no filesystem I/O (behavior is unaffected by Windows filesystem semantics) and does not perform token redaction or logging of stream contents.
+ *
+ * @param reader - The ReadableStreamDefaultReader to read from.
+ * @param timeoutMs - Maximum time in milliseconds to wait for a chunk before rejecting.
+ * @returns The result of `reader.read()`: an object with `done` and `value` (`Uint8Array | undefined`).
+ */
+async function readChunkWithTimeout(
+	readPromise: Promise<Awaited<ReturnType<ReadableStreamDefaultReader<Uint8Array>["read"]>>>,
+	timeoutMs: number,
+): Promise<Awaited<ReturnType<ReadableStreamDefaultReader<Uint8Array>["read"]>>> {
+	let timeoutId: ReturnType<typeof setTimeout> | undefined;
+	try {
+		return await Promise.race([
+			readPromise,
+			new Promise<never>((_, reject) => {
+				timeoutId = setTimeout(() => {
+					reject(new StallTimeoutError(timeoutMs));
+				}, timeoutMs);
+			}),
+		]);
+	} finally {
+		if (timeoutId !== undefined) {
+			clearTimeout(timeoutId);
+		}
+	}
+}
+
+/**
+ * Determines whether an error indicates an SSE stream stall timeout.
+ *
+ * Concurrency: safe to call from multiple async contexts. Windows filesystem: not applicable. Token redaction: this function only inspects the error message and does not log or expose sensitive tokens.
+ *
+ * @param error - The value to inspect for a stall-timeout error
+ * @returns `true` if `error` is an `Error` whose message contains "SSE stream stalled for", `false` otherwise.
+ */
+function isStallTimeoutError(error: unknown): boolean {
+	if (error instanceof StallTimeoutError) return true;
+	if (!error || typeof error !== "object") return false;
+	const candidate = error as { isStallTimeout?: unknown };
+	if (candidate.isStallTimeout === true) return true;
+	return false;
+}
+
+/**
+ * Normalize a request instance identifier by trimming whitespace and enforcing a maximum length.
+ *
+ * This function is pure and safe for concurrent use; it performs no I/O or filesystem operations (behavior is OS-independent, including Windows). It truncates long identifiers to MAX_REQUEST_INSTANCE_ID_LENGTH but does not mask or redact content — callers should apply any token-redaction or masking required for logs or telemetry.
+ *
+ * @param value - The raw identifier value which may be undefined or contain surrounding whitespace
+ * @returns The trimmed identifier if non-empty and within the length limit, a truncated identifier if longer than the limit, or `null` if the input is undefined or empty after trimming
+ */
+function normalizeRequestInstanceId(value: string | undefined): string | null {
+	if (!value) return null;
+	const trimmed = value.trim();
+	if (!trimmed) return null;
+	if (trimmed.length <= MAX_REQUEST_INSTANCE_ID_LENGTH) return trimmed;
+	return trimmed.slice(0, MAX_REQUEST_INSTANCE_ID_LENGTH);
+}
+
+async function readChunkWithSoftHardTimeout(
+	reader: ReadableStreamDefaultReader<Uint8Array>,
+	softTimeoutMs: number,
+	hardTimeoutMs: number,
+): Promise<Awaited<ReturnType<ReadableStreamDefaultReader<Uint8Array>["read"]>>> {
+	const readPromise = reader.read();
+	try {
+		return await readChunkWithTimeout(readPromise, softTimeoutMs);
+	} catch (error) {
+		if (!isStallTimeoutError(error) || hardTimeoutMs <= softTimeoutMs) {
+			throw error;
+		}
+		return readChunkWithTimeout(readPromise, hardTimeoutMs - softTimeoutMs);
+	}
+}
+
+/**
+ * Wraps an SSE-like streaming Response so the stream can switch to fallback sources on stalls or errors to keep the client session alive.
+ *
+ * The returned Response streams bytes from the initialResponse body and, when the stream stalls or errors, will attempt up to `maxFailovers` failovers by calling `getFallbackResponse(attempt, emittedBytes)`. On each successful failover a textual marker is injected into the stream identifying the failover attempt (and `requestInstanceId` when provided). The function performs best-effort cleanup of underlying readers and enforces soft/hard read timeouts as configured via `options`.
+ *
+ * Concurrency assumptions: the implementation expects a single consumer reading the returned Response body; callers must not concurrently read the same stream body from multiple consumers. Filesystem/platform note: behavior is platform-agnostic; no filesystem access is performed (Windows-specific filesystem semantics do not apply). Token redaction: any request identifiers embedded in the injected marker are limited to the normalized `requestInstanceId` (trimmed and truncated to 64 chars) to avoid leaking long tokens.
+ *
+ * @param initialResponse - The original Response whose body will be streamed and monitored for stalls/errors.
+ * @param getFallbackResponse - Async function invoked for each failover attempt with the 1-based attempt number and total emitted bytes; should return a Response with a streaming body to switch to, or `null`/a Response without a body to indicate no fallback.
+ * @param options - Optional failover configuration (maxFailovers, stall/soft/hard timeout overrides, requestInstanceId). `requestInstanceId` will be normalized and truncated to 64 characters.
+ * @returns A new Response that streams data from the initial response but may switch to fallback responses on stall/error, preserving the original status, statusText, and content-type header.
+ */
+export function withStreamingFailover(
+	initialResponse: Response,
+	getFallbackResponse: (attempt: number, emittedBytes: number) => Promise<Response | null>,
+	options: StreamFailoverOptions = {},
+): Response {
+	const maxFailovers = Math.max(0, Math.floor(options.maxFailovers ?? DEFAULT_MAX_FAILOVERS));
+	const defaultHardTimeoutMs = options.stallTimeoutMs ?? DEFAULT_STALL_TIMEOUT_MS;
+	const softTimeoutMs = Math.max(
+		1_000,
+		Math.floor(options.softTimeoutMs ?? Math.min(defaultHardTimeoutMs, DEFAULT_SOFT_TIMEOUT_MS)),
+	);
+	const hardTimeoutMs = Math.max(
+		softTimeoutMs,
+		Math.floor(options.hardTimeoutMs ?? defaultHardTimeoutMs),
+	);
+	const requestInstanceId = normalizeRequestInstanceId(options.requestInstanceId);
+	const headers = ensureContentType(initialResponse.headers);
+
+	if (!initialResponse.body || maxFailovers <= 0) {
+		return initialResponse;
+	}
+
+	let closed = false;
+	let releaseCurrentReaderForCancel: (() => Promise<void>) | null = null;
+	const body = new ReadableStream<Uint8Array>({
+		start(controller) {
+			let currentReader = initialResponse.body?.getReader() ?? null;
+			let failoverAttempt = 0;
+			let emittedBytes = 0;
+
+			const releaseCurrentReader = async (): Promise<void> => {
+				if (!currentReader) return;
+				try {
+					await currentReader.cancel();
+				} catch {
+					// Best effort.
+				}
+				try {
+					currentReader.releaseLock();
+				} catch {
+					// Best effort.
+				}
+				currentReader = null;
+			};
+			releaseCurrentReaderForCancel = releaseCurrentReader;
+
+			const tryFailover = async (): Promise<boolean> => {
+				if (failoverAttempt >= maxFailovers) {
+					return false;
+				}
+				failoverAttempt += 1;
+				const fallback = await getFallbackResponse(failoverAttempt, emittedBytes);
+				if (!fallback?.body) {
+					return false;
+				}
+				await releaseCurrentReader();
+				const markerLabel = requestInstanceId
+					? `: codex-multi-auth failover ${failoverAttempt} req:${requestInstanceId}\n\n`
+					: `: codex-multi-auth failover ${failoverAttempt}\n\n`;
+				const marker = new TextEncoder().encode(markerLabel);
+				controller.enqueue(marker);
+				currentReader = fallback.body.getReader();
+				return true;
+			};
+
+			const pump = async (): Promise<void> => {
+				while (!closed && currentReader) {
+					try {
+						const result = await readChunkWithSoftHardTimeout(
+							currentReader,
+							softTimeoutMs,
+							hardTimeoutMs,
+						);
+						if (result.done) {
+							closed = true;
+							controller.close();
+							await releaseCurrentReader();
+							return;
+						}
+						if (result.value && result.value.byteLength > 0) {
+							emittedBytes += result.value.byteLength;
+							controller.enqueue(result.value);
+						}
+					} catch (error) {
+						let switched = false;
+						try {
+							switched = await tryFailover();
+						} catch (failoverError) {
+							closed = true;
+							await releaseCurrentReader();
+							controller.error(failoverError);
+							return;
+						}
+						if (switched) {
+							continue;
+						}
+						closed = true;
+						await releaseCurrentReader();
+						controller.error(error);
+						return;
+					}
+				}
+			};
+
+			void pump();
+		},
+		cancel() {
+			closed = true;
+			if (releaseCurrentReaderForCancel) {
+				void releaseCurrentReaderForCancel();
+			}
+		},
+	});
+
+	return new Response(body, {
+		status: initialResponse.status,
+		statusText: initialResponse.statusText,
+		headers,
+	});
+}
diff --git a/lib/rotation.ts b/lib/rotation.ts
index 9b171636..652a9173 100644
--- a/lib/rotation.ts
+++ b/lib/rotation.ts
@@ -297,8 +297,24 @@ export const DEFAULT_HYBRID_SELECTION_CONFIG: HybridSelectionConfig = {
  */
 export interface HybridSelectionOptions {
   pidOffsetEnabled?: boolean;
+  scoreBoostByAccount?: Record<number, number>;
 }
 
+/**
+ * Selects the best account from a set using a weighted hybrid score composed of health, token availability, and freshness.
+ *
+ * @param accounts - Candidate accounts with availability (`isAvailable`) and last-used timestamp (`lastUsed`); when none are available the least-recently-used account is returned.
+ * @param healthTracker - Tracker used to obtain per-account health scores (scoped by `quotaKey` when provided).
+ * @param tokenTracker - Tracker used to obtain per-account token counts (scoped by `quotaKey` when provided). Logged token values are rounded for telemetry and sensitive tokens are not emitted.
+ * @param quotaKey - Optional quota key to scope health and token lookups.
+ * @param config - Partial selection weights that override defaults (healthWeight, tokenWeight, freshnessWeight).
+ * @param options - Selection options. `pidOffsetEnabled` adds a small PID-based deterministic offset to distribute selection across processes. `scoreBoostByAccount` is an optional per-account numeric boost keyed by account index.
+ * @returns The chosen AccountWithMetrics for the next request, or `null` if no accounts exist.
+ *
+ * Concurrency & environment notes:
+ * - Selection is deterministic given the same inputs except when `pidOffsetEnabled` is used to bias selection per-process.
+ * - The function is purely in-memory and performs no filesystem operations (no Windows filesystem considerations).
+ */
 export function selectHybridAccount(
   accounts: AccountWithMetrics[],
   healthTracker: HealthScoreTracker,
@@ -338,10 +354,17 @@ export function selectHybridAccount(
     const tokens = tokenTracker.getTokens(account.index, quotaKey);
     const hoursSinceUsed = (now - account.lastUsed) / (1000 * 60 * 60);
 
+    const capabilityBoost =
+      typeof options.scoreBoostByAccount?.[account.index] === "number"
+        ? options.scoreBoostByAccount[account.index] ?? 0
+        : 0;
+    const safeCapabilityBoost = Number.isFinite(capabilityBoost) ? capabilityBoost : 0;
+
     let score =
       health * cfg.healthWeight +
       tokens * cfg.tokenWeight +
-      hoursSinceUsed * cfg.freshnessWeight;
+      hoursSinceUsed * cfg.freshnessWeight +
+      safeCapabilityBoost;
 
     // PID-based offset distributes selection across parallel agents
     if (options.pidOffsetEnabled) {
diff --git a/lib/runtime-paths.ts b/lib/runtime-paths.ts
new file mode 100644
index 00000000..2650ccad
--- /dev/null
+++ b/lib/runtime-paths.ts
@@ -0,0 +1,173 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { existsSync } from "node:fs";
+
+/**
+ * Resolve the Codex home directory path used by the CLI, honoring an environment override or a sensible default.
+ *
+ * This function is safe to call concurrently and returns a filesystem path string as-is; on Windows the underlying filesystem is case-insensitive so callers should avoid relying on case for equality. The returned path may contain sensitive identifiers; redact or avoid logging it in plaintext.
+ *
+ * @returns The resolved Codex home directory path: the value of `CODEX_HOME` when set and non-empty, otherwise the user's home directory joined with `.codex`.
+ */
+
+export function getCodexHomeDir(): string {
+	const fromEnv = (process.env.CODEX_HOME ?? "").trim();
+	return fromEnv.length > 0 ? fromEnv : join(homedir(), ".codex");
+}
+
+/**
+ * Returns a deduplicated list of path strings preserving the first occurrence order.
+ *
+ * Trims each input entry and ignores empty results; comparison for uniqueness is
+ * case-insensitive on Windows and case-sensitive on other platforms. This function
+ * performs no I/O and is safe to call concurrently.
+ *
+ * Note: entries are preserved as trimmed strings and are not modified for token
+ * redaction or normalization beyond trimming and optional lowercasing on Windows.
+ *
+ * @param paths - Array of path strings to deduplicate
+ * @returns An array of unique, trimmed path strings in their original first-seen order
+ */
+function deduplicatePaths(paths: string[]): string[] {
+	const seen = new Set<string>();
+	const result: string[] = [];
+	for (const candidate of paths) {
+		const trimmed = candidate.trim();
+		if (trimmed.length === 0) continue;
+		const key = process.platform === "win32" ? trimmed.toLowerCase() : trimmed;
+		if (seen.has(key)) continue;
+		seen.add(key);
+		result.push(trimmed);
+	}
+	return result;
+}
+
+/**
+ * Detects whether a directory contains known Codex storage indicators.
+ *
+ * Checks for the presence of known signal files (for example: openai-codex-accounts.json, settings.json, config.json, dashboard-settings.json)
+ * or a "projects" subdirectory to determine if the directory appears to hold Codex data.
+ *
+ * Notes:
+ * - The check only tests filesystem existence; it does not read file contents (no token or secret inspection/redaction is performed).
+ * - Results can change if other processes modify the filesystem concurrently; callers should tolerate races.
+ * - On Windows, filesystem case-insensitivity affects existence checks.
+ *
+ * @param dir - Filesystem path of the directory to probe
+ * @returns `true` if any known signal file or a "projects" subdirectory exists, `false` otherwise.
+ */
+function hasStorageSignals(dir: string): boolean {
+	const signals = [
+		"openai-codex-accounts.json",
+		"settings.json",
+		"config.json",
+		"dashboard-settings.json",
+	];
+	for (const signal of signals) {
+		if (existsSync(join(dir, signal))) {
+			return true;
+		}
+	}
+	return existsSync(join(dir, "projects"));
+}
+
+/**
+ * Builds a deduplicated list of fallback candidate directories that may contain Codex runtime data.
+ *
+ * The returned list preserves evaluation order (primary Codex home first, then DevTools config, then legacy ~/.codex).
+ * Comparison is normalized for case-insensitive filesystems (Windows) during deduplication. Callers should treat
+ * these paths as suggestions only; concurrent callers may observe different filesystem states and should handle
+ * races. Paths may contain sensitive tokens; callers must redact or avoid logging them.
+ *
+ * @returns An array of unique, trimmed directory paths to probe for Codex home data, in prioritized order.
+ */
+function getFallbackCodexHomeDirs(): string[] {
+	return deduplicatePaths([
+		getCodexHomeDir(),
+		join(homedir(), "DevTools", "config", "codex"),
+		join(homedir(), ".codex"),
+	]);
+}
+
+/**
+ * Determine the directory to use for Codex multi-auth data, preferring an explicit override
+ * or existing storage locations and falling back to the primary Codex location.
+ *
+ * @returns The resolved multi-auth directory path.
+ *
+ * @remarks
+ * Concurrency: safe to call concurrently; the function only inspects filesystem state and does not create or mutate directories.
+ *
+ * Windows: deduplication and existence checks treat paths case-insensitively on Windows; returned paths preserve platform-native casing.
+ *
+ * Security: returned paths may contain user-specific or sensitive data; callers should redact or avoid logging full paths. 
+ */
+export function getCodexMultiAuthDir(): string {
+	const fromEnv = (process.env.CODEX_MULTI_AUTH_DIR ?? "").trim();
+	if (fromEnv.length > 0) {
+		return fromEnv;
+	}
+
+	const primary = join(getCodexHomeDir(), "multi-auth");
+	if (hasStorageSignals(primary)) {
+		return primary;
+	}
+
+	const fallbackCandidates = deduplicatePaths([
+		...getFallbackCodexHomeDirs().map((dir) => join(dir, "multi-auth")),
+		getLegacyOpenCodeDir(),
+	]);
+
+	for (const candidate of fallbackCandidates) {
+		if (candidate === primary) continue;
+		if (hasStorageSignals(candidate)) {
+			return candidate;
+		}
+	}
+
+	return primary;
+}
+
+/**
+ * Resolves the Codex cache directory used for storing cached multi-auth artifacts.
+ *
+ * The returned path is derived from the resolved multi-auth directory. Callers should avoid concurrent
+ * mutations to the returned directory path (concurrent reads are safe). On Windows, path comparison
+ * is case-insensitive elsewhere in this module; the returned path itself preserves platform casing.
+ *
+ * Token or secret redaction is not performed on the path; do not log paths that may contain secrets.
+ *
+ * @returns The filesystem path to the Codex cache directory.
+ */
+export function getCodexCacheDir(): string {
+	return join(getCodexMultiAuthDir(), "cache");
+}
+
+/**
+ * Resolve the filesystem path for Codex log files.
+ *
+ * Returns the `logs` subdirectory within the resolved multi-auth directory.
+ * Concurrency: safe to call concurrently; this function performs no I/O or directory creation.
+ * Windows: path comparisons elsewhere are case-insensitive on Windows; this function returns a path using the platform separator.
+ * Security: the returned path may contain sensitive artifacts (tokens/credentials); redact before logging or diagnostics.
+ *
+ * @returns The path to the Codex `logs` directory (i.e., `<multi-auth-dir>/logs`)
+ */
+export function getCodexLogDir(): string {
+	return join(getCodexMultiAuthDir(), "logs");
+}
+
+/**
+ * Resolve the legacy OpenCode home directory path.
+ *
+ * The returned path points to the per-user legacy OpenCode folder (typically `<home>/.opencode`).
+ *
+ * Concurrency: no atomicity guarantees — callers must handle concurrent filesystem access.
+ * Windows: path comparisons may be case-insensitive on Windows filesystems.
+ * Security: do not embed or log secrets/tokens in this path; redact any tokens before logging or telemetry.
+ *
+ * @returns The filesystem path for the legacy OpenCode directory (e.g. `/home/alice/.opencode`).
+ */
+export function getLegacyOpenCodeDir(): string {
+	return join(homedir(), ".opencode");
+}
diff --git a/lib/schemas.ts b/lib/schemas.ts
index 2af03f03..55028b6e 100644
--- a/lib/schemas.ts
+++ b/lib/schemas.ts
@@ -41,6 +41,22 @@ export const PluginConfigSchema = z.object({
 	pidOffsetEnabled: z.boolean().optional(),
 	fetchTimeoutMs: z.number().min(1_000).optional(),
 	streamStallTimeoutMs: z.number().min(1_000).optional(),
+	liveAccountSync: z.boolean().optional(),
+	liveAccountSyncDebounceMs: z.number().min(50).optional(),
+	liveAccountSyncPollMs: z.number().min(500).optional(),
+	sessionAffinity: z.boolean().optional(),
+	sessionAffinityTtlMs: z.number().min(1_000).optional(),
+	sessionAffinityMaxEntries: z.number().min(8).optional(),
+	proactiveRefreshGuardian: z.boolean().optional(),
+	proactiveRefreshIntervalMs: z.number().min(5_000).optional(),
+	proactiveRefreshBufferMs: z.number().min(30_000).optional(),
+	networkErrorCooldownMs: z.number().min(0).optional(),
+	serverErrorCooldownMs: z.number().min(0).optional(),
+	storageBackupEnabled: z.boolean().optional(),
+	preemptiveQuotaEnabled: z.boolean().optional(),
+	preemptiveQuotaRemainingPercent5h: z.number().min(0).max(100).optional(),
+	preemptiveQuotaRemainingPercent7d: z.number().min(0).max(100).optional(),
+	preemptiveQuotaMaxDeferralMs: z.number().min(1_000).optional(),
 });
 
 export type PluginConfigFromSchema = z.infer<typeof PluginConfigSchema>;
@@ -59,7 +75,7 @@ export type AccountIdSourceFromSchema = z.infer<typeof AccountIdSourceSchema>;
 /**
  * Cooldown reason for temporary account suspension.
  */
-export const CooldownReasonSchema = z.enum(["auth-failure", "network-error"]);
+export const CooldownReasonSchema = z.enum(["auth-failure", "network-error", "rate-limit"]);
 
 export type CooldownReasonFromSchema = z.infer<typeof CooldownReasonSchema>;
 
diff --git a/lib/session-affinity.ts b/lib/session-affinity.ts
new file mode 100644
index 00000000..5cfcdafa
--- /dev/null
+++ b/lib/session-affinity.ts
@@ -0,0 +1,144 @@
+import { createLogger } from "./logger.js";
+
+const log = createLogger("session-affinity");
+
+export interface SessionAffinityOptions {
+	ttlMs?: number;
+	maxEntries?: number;
+}
+
+interface SessionAffinityEntry {
+	accountIndex: number;
+	expiresAt: number;
+	updatedAt: number;
+}
+
+const DEFAULT_TTL_MS = 20 * 60 * 1000;
+const DEFAULT_MAX_ENTRIES = 512;
+const MAX_SESSION_KEY_LENGTH = 256;
+
+/**
+ * Normalize a session key by trimming surrounding whitespace and enforcing the maximum allowed length.
+ *
+ * This function is pure and has no side effects; it makes no filesystem-specific assumptions (including Windows) and does not perform token redaction. Callers are responsible for any concurrency control.
+ *
+ * @param value - The raw session key (may be `null` or `undefined`)
+ * @returns The trimmed session key truncated to at most `MAX_SESSION_KEY_LENGTH` characters, or `null` if the input is missing or contains only whitespace
+ */
+function normalizeSessionKey(value: string | null | undefined): string | null {
+	if (!value) return null;
+	const trimmed = value.trim();
+	if (!trimmed) return null;
+	if (trimmed.length <= MAX_SESSION_KEY_LENGTH) return trimmed;
+	return trimmed.slice(0, MAX_SESSION_KEY_LENGTH);
+}
+
+/**
+ * Tracks preferred account index per session so follow-up turns stay on the
+ * same account until it becomes unhealthy or stale.
+ */
+export class SessionAffinityStore {
+	private readonly ttlMs: number;
+	private readonly maxEntries: number;
+	private readonly entries = new Map<string, SessionAffinityEntry>();
+
+	constructor(options: SessionAffinityOptions = {}) {
+		this.ttlMs = Math.max(1_000, Math.floor(options.ttlMs ?? DEFAULT_TTL_MS));
+		this.maxEntries = Math.max(1, Math.floor(options.maxEntries ?? DEFAULT_MAX_ENTRIES));
+	}
+
+	getPreferredAccountIndex(sessionKey: string | null | undefined, now = Date.now()): number | null {
+		const key = normalizeSessionKey(sessionKey);
+		if (!key) return null;
+
+		const entry = this.entries.get(key);
+		if (!entry) return null;
+		if (entry.expiresAt <= now) {
+			this.entries.delete(key);
+			return null;
+		}
+		return entry.accountIndex;
+	}
+
+	remember(sessionKey: string | null | undefined, accountIndex: number, now = Date.now()): void {
+		const key = normalizeSessionKey(sessionKey);
+		if (!key) return;
+		if (!Number.isFinite(accountIndex) || accountIndex < 0) return;
+
+		if (this.entries.size >= this.maxEntries && !this.entries.has(key)) {
+			const oldest = this.findOldestKey();
+			if (oldest) this.entries.delete(oldest);
+		}
+
+		this.entries.set(key, {
+			accountIndex,
+			expiresAt: now + this.ttlMs,
+			updatedAt: now,
+		});
+	}
+
+	forgetSession(sessionKey: string | null | undefined): void {
+		const key = normalizeSessionKey(sessionKey);
+		if (!key) return;
+		this.entries.delete(key);
+	}
+
+	forgetAccount(accountIndex: number): number {
+		if (!Number.isFinite(accountIndex) || accountIndex < 0) return 0;
+		let removed = 0;
+		for (const [key, entry] of this.entries.entries()) {
+			if (entry.accountIndex === accountIndex) {
+				this.entries.delete(key);
+				removed += 1;
+			}
+		}
+		if (removed > 0) {
+			log.debug("Cleared session affinity entries for account", {
+				accountIndex,
+				removed,
+			});
+		}
+		return removed;
+	}
+
+	reindexAfterRemoval(removedIndex: number): number {
+		if (!Number.isFinite(removedIndex) || removedIndex < 0) return 0;
+		let shifted = 0;
+		for (const [key, entry] of this.entries.entries()) {
+			if (entry.accountIndex > removedIndex) {
+				this.entries.set(key, { ...entry, accountIndex: entry.accountIndex - 1 });
+				shifted += 1;
+			}
+		}
+		return shifted;
+	}
+
+	prune(now = Date.now()): number {
+		let removed = 0;
+		for (const [key, entry] of this.entries.entries()) {
+			if (entry.expiresAt <= now) {
+				this.entries.delete(key);
+				removed += 1;
+			}
+		}
+		return removed;
+	}
+
+	size(): number {
+		return this.entries.size;
+	}
+
+	private findOldestKey(): string | null {
+		let oldestKey: string | null = null;
+		let oldestTimestamp = Number.POSITIVE_INFINITY;
+
+		for (const [key, entry] of this.entries.entries()) {
+			if (entry.updatedAt < oldestTimestamp) {
+				oldestTimestamp = entry.updatedAt;
+				oldestKey = key;
+			}
+		}
+
+		return oldestKey;
+	}
+}
diff --git a/lib/storage.ts b/lib/storage.ts
index accbabb8..e53034c1 100644
--- a/lib/storage.ts
+++ b/lib/storage.ts
@@ -1,5 +1,6 @@
 import { promises as fs, existsSync } from "node:fs";
 import { dirname, join } from "node:path";
+import { createHash } from "node:crypto";
 import { ACCOUNT_LIMITS } from "./constants.js";
 import { createLogger } from "./logger.js";
 import { MODEL_FAMILIES, type ModelFamily } from "./prompts/codex.js";
@@ -21,6 +22,13 @@ const log = createLogger("storage");
 const ACCOUNTS_FILE_NAME = "openai-codex-accounts.json";
 const FLAGGED_ACCOUNTS_FILE_NAME = "openai-codex-flagged-accounts.json";
 const LEGACY_FLAGGED_ACCOUNTS_FILE_NAME = "openai-codex-blocked-accounts.json";
+const ACCOUNTS_BACKUP_SUFFIX = ".bak";
+const ACCOUNTS_WAL_SUFFIX = ".wal";
+const BACKUP_COPY_MAX_ATTEMPTS = 5;
+const BACKUP_COPY_BASE_DELAY_MS = 10;
+
+let storageBackupEnabled = true;
+let lastAccountsSaveTimestamp = 0;
 
 export interface FlaggedAccountMetadataV1 extends AccountMetadataV3 {
 	flaggedAt: number;
@@ -63,7 +71,7 @@ export function formatStorageErrorHint(error: unknown, path: string): string {
     case "EPERM":
       return isWindows
         ? `Permission denied writing to ${path}. Check antivirus exclusions for this folder. Ensure you have write permissions.`
-        : `Permission denied writing to ${path}. Check folder permissions. Try: chmod 755 ~/.opencode`;
+        : `Permission denied writing to ${path}. Check folder permissions. Try: chmod 755 ~/.codex`;
     case "EBUSY":
       return `File is locked at ${path}. The file may be open in another program. Close any editors or processes accessing it.`;
     case "ENOSPC":
@@ -115,14 +123,14 @@ async function ensureGitignore(storagePath: string): Promise<void> {
     if (existsSync(gitignorePath)) {
       content = await fs.readFile(gitignorePath, "utf-8");
       const lines = content.split("\n").map((l) => l.trim());
-      if (lines.includes(".opencode") || lines.includes(".opencode/") || lines.includes("/.opencode") || lines.includes("/.opencode/")) {
+      if (lines.includes(".codex") || lines.includes(".codex/") || lines.includes("/.codex") || lines.includes("/.codex/")) {
         return;
       }
     }
 
     const newContent = content.endsWith("\n") || content === "" ? content : content + "\n";
-    await fs.writeFile(gitignorePath, newContent + ".opencode/\n", "utf-8");
-    log.debug("Added .opencode to .gitignore", { path: gitignorePath });
+    await fs.writeFile(gitignorePath, newContent + ".codex/\n", "utf-8");
+    log.debug("Added .codex to .gitignore", { path: gitignorePath });
   } catch (error) {
     log.warn("Failed to update .gitignore", { error: String(error) });
   }
@@ -132,6 +140,34 @@ let currentStoragePath: string | null = null;
 let currentLegacyProjectStoragePath: string | null = null;
 let currentProjectRoot: string | null = null;
 
+export function setStorageBackupEnabled(enabled: boolean): void {
+	storageBackupEnabled = enabled;
+}
+
+function getAccountsBackupPath(path: string): string {
+	return `${path}${ACCOUNTS_BACKUP_SUFFIX}`;
+}
+
+function getAccountsWalPath(path: string): string {
+	return `${path}${ACCOUNTS_WAL_SUFFIX}`;
+}
+
+function computeSha256(value: string): string {
+	return createHash("sha256").update(value).digest("hex");
+}
+
+type AccountsJournalEntry = {
+	version: 1;
+	createdAt: number;
+	path: string;
+	checksum: string;
+	content: string;
+};
+
+export function getLastAccountsSaveTimestamp(): number {
+	return lastAccountsSaveTimestamp;
+}
+
 export function setStoragePath(projectPath: string | null): void {
   if (!projectPath) {
     currentStoragePath = null;
@@ -485,22 +521,64 @@ export async function loadAccounts(): Promise<AccountStorageV3 | null> {
   return loadAccountsInternal(saveAccounts);
 }
 
+function parseAndNormalizeStorage(data: unknown): {
+	normalized: AccountStorageV3 | null;
+	storedVersion: unknown;
+	schemaErrors: string[];
+} {
+	const schemaErrors = getValidationErrors(AnyAccountStorageSchema, data);
+	const normalized = normalizeAccountStorage(data);
+	const storedVersion = isRecord(data) ? (data as { version?: unknown }).version : undefined;
+	return { normalized, storedVersion, schemaErrors };
+}
+
+async function loadAccountsFromPath(path: string): Promise<{
+	normalized: AccountStorageV3 | null;
+	storedVersion: unknown;
+	schemaErrors: string[];
+}> {
+	const content = await fs.readFile(path, "utf-8");
+	const data = JSON.parse(content) as unknown;
+	return parseAndNormalizeStorage(data);
+}
+
+async function loadAccountsFromJournal(path: string): Promise<AccountStorageV3 | null> {
+	const walPath = getAccountsWalPath(path);
+	try {
+		const raw = await fs.readFile(walPath, "utf-8");
+		const parsed = JSON.parse(raw) as unknown;
+		if (!isRecord(parsed)) return null;
+		const entry = parsed as Partial<AccountsJournalEntry>;
+		if (entry.version !== 1) return null;
+		if (typeof entry.content !== "string" || typeof entry.checksum !== "string") return null;
+		const computed = computeSha256(entry.content);
+		if (computed !== entry.checksum) {
+			log.warn("Account journal checksum mismatch", { path: walPath });
+			return null;
+		}
+		const data = JSON.parse(entry.content) as unknown;
+		const { normalized } = parseAndNormalizeStorage(data);
+		if (!normalized) return null;
+		log.warn("Recovered account storage from WAL journal", { path, walPath });
+		return normalized;
+	} catch (error) {
+		const code = (error as NodeJS.ErrnoException).code;
+		if (code !== "ENOENT") {
+			log.warn("Failed to load account WAL journal", { path: walPath, error: String(error) });
+		}
+		return null;
+	}
+}
+
 async function loadAccountsInternal(
   persistMigration: ((storage: AccountStorageV3) => Promise<void>) | null,
 ): Promise<AccountStorageV3 | null> {
   try {
     const path = getStoragePath();
-    const content = await fs.readFile(path, "utf-8");
-    const data = JSON.parse(content) as unknown;
-
-    const schemaErrors = getValidationErrors(AnyAccountStorageSchema, data);
+    const { normalized, storedVersion, schemaErrors } = await loadAccountsFromPath(path);
     if (schemaErrors.length > 0) {
       log.warn("Account storage schema validation warnings", { errors: schemaErrors.slice(0, 5) });
     }
-
-    const normalized = normalizeAccountStorage(data);
-
-    const storedVersion = isRecord(data) ? (data as { version?: unknown }).version : undefined;
     if (normalized && storedVersion !== normalized.version) {
       log.info("Migrating account storage to v3", { from: storedVersion, to: normalized.version });
       if (persistMigration) {
@@ -515,14 +593,65 @@ async function loadAccountsInternal(
     return normalized;
   } catch (error) {
     const code = (error as NodeJS.ErrnoException).code;
-    if (code === "ENOENT") {
-      const migrated = persistMigration
-        ? await migrateLegacyProjectStorageIfNeeded(persistMigration)
-        : null;
+	const path = getStoragePath();
+    if (code === "ENOENT" && persistMigration) {
+      const migrated = await migrateLegacyProjectStorageIfNeeded(persistMigration);
       if (migrated) return migrated;
-      return null;
     }
-    log.error("Failed to load account storage", { error: String(error) });
+
+	const recoveredFromWal = await loadAccountsFromJournal(path);
+	if (recoveredFromWal) {
+		if (persistMigration) {
+			try {
+				await persistMigration(recoveredFromWal);
+			} catch (persistError) {
+				log.warn("Failed to persist WAL-recovered storage", {
+					path,
+					error: String(persistError),
+				});
+			}
+		}
+		return recoveredFromWal;
+	}
+
+	if (storageBackupEnabled) {
+		const backupPath = getAccountsBackupPath(path);
+		try {
+			const backup = await loadAccountsFromPath(backupPath);
+			if (backup.schemaErrors.length > 0) {
+				log.warn("Backup account storage schema validation warnings", {
+					path: backupPath,
+					errors: backup.schemaErrors.slice(0, 5),
+				});
+			}
+			if (backup.normalized) {
+				log.warn("Recovered account storage from backup file", { path, backupPath });
+				if (persistMigration) {
+					try {
+						await persistMigration(backup.normalized);
+					} catch (persistError) {
+						log.warn("Failed to persist recovered backup storage", {
+							path,
+							error: String(persistError),
+						});
+					}
+				}
+				return backup.normalized;
+			}
+		} catch (backupError) {
+			const backupCode = (backupError as NodeJS.ErrnoException).code;
+			if (backupCode !== "ENOENT") {
+				log.warn("Failed to load backup account storage", {
+					path: backupPath,
+					error: String(backupError),
+				});
+			}
+		}
+	}
+
+    if (code !== "ENOENT") {
+      log.error("Failed to load account storage", { error: String(error) });
+    }
     return null;
   }
 }
@@ -531,12 +660,53 @@ async function saveAccountsUnlocked(storage: AccountStorageV3): Promise<void> {
   const path = getStoragePath();
   const uniqueSuffix = `${Date.now()}.${Math.random().toString(36).slice(2, 8)}`;
   const tempPath = `${path}.${uniqueSuffix}.tmp`;
+  const walPath = getAccountsWalPath(path);
 
   try {
     await fs.mkdir(dirname(path), { recursive: true });
     await ensureGitignore(path);
 
+	if (storageBackupEnabled && existsSync(path)) {
+		const backupPath = getAccountsBackupPath(path);
+		try {
+			for (let attempt = 0; attempt < BACKUP_COPY_MAX_ATTEMPTS; attempt += 1) {
+				try {
+					await fs.copyFile(path, backupPath);
+					break;
+				} catch (backupError) {
+					const code = (backupError as NodeJS.ErrnoException).code;
+					const canRetry = (code === "EPERM" || code === "EBUSY") &&
+						attempt + 1 < BACKUP_COPY_MAX_ATTEMPTS;
+					if (canRetry) {
+						await new Promise((resolve) =>
+							setTimeout(resolve, BACKUP_COPY_BASE_DELAY_MS * 2 ** attempt)
+						);
+						continue;
+					}
+					throw backupError;
+				}
+			}
+		} catch (backupError) {
+			log.warn("Failed to create account storage backup", {
+				path,
+				backupPath,
+				error: String(backupError),
+			});
+		}
+	}
+
     const content = JSON.stringify(storage, null, 2);
+	const journalEntry: AccountsJournalEntry = {
+		version: 1,
+		createdAt: Date.now(),
+		path,
+		checksum: computeSha256(content),
+		content,
+	};
+	await fs.writeFile(walPath, JSON.stringify(journalEntry), {
+		encoding: "utf-8",
+		mode: 0o600,
+	});
     await fs.writeFile(tempPath, content, { encoding: "utf-8", mode: 0o600 });
 
     const stats = await fs.stat(tempPath);
@@ -550,6 +720,12 @@ async function saveAccountsUnlocked(storage: AccountStorageV3): Promise<void> {
     for (let attempt = 0; attempt < 5; attempt++) {
       try {
         await fs.rename(tempPath, path);
+		lastAccountsSaveTimestamp = Date.now();
+		try {
+			await fs.unlink(walPath);
+		} catch {
+			// Best effort cleanup.
+		}
         return;
       } catch (renameError) {
         const code = (renameError as NodeJS.ErrnoException).code;
@@ -604,7 +780,7 @@ export async function withAccountStorageTransaction<T>(
 
 /**
  * Persists account storage to disk using atomic write (temp file + rename).
- * Creates the .opencode directory if it doesn't exist.
+ * Creates the Codex multi-auth storage directory if it doesn't exist.
  * Verifies file was written correctly and provides detailed error messages.
  * @param storage - Account storage data to save
  * @throws StorageError with platform-aware hints on failure
@@ -621,14 +797,27 @@ export async function saveAccounts(storage: AccountStorageV3): Promise<void> {
  */
 export async function clearAccounts(): Promise<void> {
   return withStorageLock(async () => {
-    try {
-      const path = getStoragePath();
-      await fs.unlink(path);
-    } catch (error) {
-      const code = (error as NodeJS.ErrnoException).code;
-      if (code !== "ENOENT") {
-        log.error("Failed to clear account storage", { error: String(error) });
+    const path = getStoragePath();
+    const walPath = getAccountsWalPath(path);
+    const backupPath = getAccountsBackupPath(path);
+    const clearPath = async (targetPath: string): Promise<void> => {
+      try {
+        await fs.unlink(targetPath);
+      } catch (error) {
+        const code = (error as NodeJS.ErrnoException).code;
+        if (code !== "ENOENT") {
+          log.error("Failed to clear account storage artifact", {
+            path: targetPath,
+            error: String(error),
+          });
+        }
       }
+    };
+
+    try {
+      await Promise.all([clearPath(path), clearPath(walPath), clearPath(backupPath)]);
+    } catch {
+      // Individual path cleanup is already best-effort with per-artifact logging.
     }
   });
 }
@@ -657,7 +846,7 @@ function normalizeFlaggedStorage(data: unknown): FlaggedAccountStorageV1 {
 		const isCooldownReason = (
 			value: unknown,
 		): value is AccountMetadataV3["cooldownReason"] =>
-			value === "auth-failure" || value === "network-error";
+			value === "auth-failure" || value === "network-error" || value === "rate-limit";
 
 		let rateLimitResetTimes: AccountMetadataV3["rateLimitResetTimes"] | undefined;
 		if (isRecord(rawAccount.rateLimitResetTimes)) {
diff --git a/lib/storage/migrations.ts b/lib/storage/migrations.ts
index ac3c5bf0..2339d1d1 100644
--- a/lib/storage/migrations.ts
+++ b/lib/storage/migrations.ts
@@ -6,7 +6,7 @@
 import { MODEL_FAMILIES, type ModelFamily } from "../prompts/codex.js";
 import type { AccountIdSource } from "../types.js";
 
-export type CooldownReason = "auth-failure" | "network-error";
+export type CooldownReason = "auth-failure" | "network-error" | "rate-limit";
 
 export interface RateLimitStateV3 {
 	[key: string]: number | undefined;
diff --git a/lib/storage/paths.ts b/lib/storage/paths.ts
index b3e9d5b9..2fab1788 100644
--- a/lib/storage/paths.ts
+++ b/lib/storage/paths.ts
@@ -7,19 +7,47 @@ import { existsSync } from "node:fs";
 import { createHash } from "node:crypto";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { homedir, tmpdir } from "node:os";
+import { getCodexMultiAuthDir } from "../runtime-paths.js";
 
-const PROJECT_MARKERS = [".git", "package.json", "Cargo.toml", "go.mod", "pyproject.toml", ".opencode"];
+const PROJECT_MARKERS = [".git", "package.json", "Cargo.toml", "go.mod", "pyproject.toml", ".codex"];
 const PROJECTS_DIR = "projects";
 const PROJECT_KEY_HASH_LENGTH = 12;
 
+/**
+ * Gets the path to the global Codex multi-auth configuration directory.
+ *
+ * The returned path is platform-specific (may use Windows separators and casing). The directory is intended for concurrent use by multiple processes; callers should treat its contents as sensitive (redact tokens/credentials when logging).
+ *
+ * @returns The absolute filesystem path to the Codex multi-auth configuration directory.
+ */
 export function getConfigDir(): string {
-	return join(homedir(), ".opencode");
+	return getCodexMultiAuthDir();
 }
 
+/**
+ * Get the per-project .codex directory path inside the given project path.
+ *
+ * This function is pure and safe for concurrent use. The returned path uses the platform's native separators; on Windows, casing and separators follow OS semantics and callers should normalize if needed. The returned value may contain sensitive segments derived from `projectPath`; callers should redact secrets before logging.
+ *
+ * @param projectPath - Project directory path (absolute or relative)
+ * @returns The path to the project's ".codex" configuration directory
+ */
 export function getProjectConfigDir(projectPath: string): string {
-	return join(projectPath, ".opencode");
+	return join(projectPath, ".codex");
 }
 
+/**
+ * Normalize a project filesystem path for consistent comparison and storage.
+ *
+ * Produces an absolute path with forward slashes; on Windows the path is also converted to lowercase
+ * to make comparisons case-insensitive. This function is pure and safe for concurrent use.
+ *
+ * Note: this function does not redact or remove sensitive tokens from the path — callers must
+ * perform any required redaction before logging or exposing paths.
+ *
+ * @param projectPath - The input path to normalize
+ * @returns The absolute, forward-slash-normalized path; on Windows the result is lowercased
+ */
 function normalizeProjectPath(projectPath: string): string {
 	const resolvedPath = resolve(projectPath);
 	const normalizedSeparators = resolvedPath.replace(/\\/g, "/");
@@ -28,12 +56,32 @@ function normalizeProjectPath(projectPath: string): string {
 		: normalizedSeparators;
 }
 
+/**
+ * Produce a filesystem-safe project name derived from a project path.
+ *
+ * The returned name contains only letters, digits, dots, underscores, and hyphens,
+ * has no leading or trailing hyphens, and is never empty (falls back to `"project"`).
+ * This function is pure and safe to call concurrently. It does not perform any
+ * secret/token redaction and does not depend on platform-specific case normalization;
+ * additional normalization for Windows filenames should be applied by the caller if needed.
+ *
+ * @param projectPath - Path to the project (used only to derive the basename)
+ * @returns A sanitized project name suitable for use in filenames and identifiers
+ */
 function sanitizeProjectName(projectPath: string): string {
 	const name = basename(projectPath);
 	const sanitized = name.replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
 	return sanitized || "project";
 }
 
+/**
+ * Create a deterministic, filesystem-safe storage key for a project path.
+ *
+ * The key is "<sanitized-name>-<truncated-hex>" where the sanitized name is derived from the project's basename (disallowed characters replaced, trimmed, and truncated to 40 characters) and the hex segment is the first 12 characters of a SHA-256 hash of the normalized path. On Windows the path is normalized to lowercase before hashing to ensure case-insensitive equivalence. The function is pure and safe for concurrent use; it produces the same output for equivalent paths and does not perform I/O. The key does not include the raw project path, so tokens or secrets embedded in the original path are not directly exposed.
+ *
+ * @param projectPath - Project path in any form; it will be normalized (expanded, resolved, and platform-normalized) before key generation
+ * @returns A filesystem-safe storage key string composed of a sanitized project name (up to 40 chars), a dash, and a 12-character hex hash
+ */
 export function getProjectStorageKey(projectPath: string): string {
 	const normalizedPath = normalizeProjectPath(projectPath);
 	const hash = createHash("sha256")
@@ -45,8 +93,20 @@ export function getProjectStorageKey(projectPath: string): string {
 }
 
 /**
- * Per-project storage is namespaced under ~/.opencode/projects
- * to avoid writing account files into user repositories.
+ * Compute the global per-project storage directory path under the Codex multi-auth projects directory.
+ *
+ * The returned path is grounded in the global Codex multi-auth config directory and is namespaced
+ * by a filesystem-friendly project storage key derived from `projectPath` (sanitized and hashed to
+ * avoid embedding sensitive tokens or raw paths).
+ *
+ * Concurrency: the resulting directory may be accessed by multiple processes; callers are responsible
+ * for any required concurrency-safe operations when creating or mutating files within it.
+ *
+ * Windows: storage key derivation normalizes path separators and casing to produce stable keys on
+ * Windows hosts.
+ *
+ * @param projectPath - The project filesystem path used to derive the per-project storage key.
+ * @returns The absolute path to the project's storage directory under the global Codex multi-auth projects directory.
  */
 export function getProjectGlobalConfigDir(projectPath: string): string {
 	return join(getConfigDir(), PROJECTS_DIR, getProjectStorageKey(projectPath));
diff --git a/lib/ui/ansi.ts b/lib/ui/ansi.ts
index 4d804c3c..d4eb9199 100644
--- a/lib/ui/ansi.ts
+++ b/lib/ui/ansi.ts
@@ -6,28 +6,70 @@ export const ANSI = {
 	// Cursor control
 	hide: "\x1b[?25l",
 	show: "\x1b[?25h",
+	altScreenOn: "\x1b[?1049h",
+	altScreenOff: "\x1b[?1049l",
 	up: (lines = 1) => `\x1b[${lines}A`,
 	clearLine: "\x1b[2K",
 	clearScreen: "\x1b[2J",
 	moveTo: (row: number, col: number) => `\x1b[${row};${col}H`,
 
 	// Styling
+	black: "\x1b[30m",
+	white: "\x1b[97m",
 	cyan: "\x1b[36m",
 	green: "\x1b[32m",
 	red: "\x1b[31m",
 	yellow: "\x1b[33m",
+	bgBlue: "\x1b[44m",
+	bgBrightBlue: "\x1b[104m",
+	bgGreen: "\x1b[42m",
+	bgYellow: "\x1b[43m",
+	bgRed: "\x1b[41m",
+	inverse: "\x1b[7m",
 	dim: "\x1b[2m",
 	bold: "\x1b[1m",
 	reset: "\x1b[0m",
 } as const;
 
-export type KeyAction = "up" | "down" | "enter" | "escape" | "escape-start" | null;
+export type KeyAction =
+	| "up"
+	| "down"
+	| "home"
+	| "end"
+	| "enter"
+	| "escape"
+	| "escape-start"
+	| null;
 
+/**
+ * Maps a raw stdin Buffer to a normalized keyboard action token.
+ *
+ * Interprets common ANSI/terminal key sequences; safe to call concurrently (stateless). On some Windows terminals sequences may differ from POSIX terminals. Returned tokens are suitable for logging or control flow; redact or avoid logging raw `data` buffers when handling sensitive input.
+ *
+ * @param data - Buffer containing the bytes read from stdin for a single key event
+ * @returns The corresponding `KeyAction` value: `up`, `down`, `home`, `end`, `enter`, `escape`, `escape-start`, or `null` if the input is not recognized
+ */
 export function parseKey(data: Buffer): KeyAction {
 	const input = data.toString();
 
 	if (input === "\x1b[A" || input === "\x1bOA") return "up";
 	if (input === "\x1b[B" || input === "\x1bOB") return "down";
+	if (
+		input === "\x1b[H" ||
+		input === "\x1bOH" ||
+		input === "\x1b[1~" ||
+		input === "\x1b[7~"
+	) {
+		return "home";
+	}
+	if (
+		input === "\x1b[F" ||
+		input === "\x1bOF" ||
+		input === "\x1b[4~" ||
+		input === "\x1b[8~"
+	) {
+		return "end";
+	}
 	if (input === "\r" || input === "\n") return "enter";
 	if (input === "\x03") return "escape";
 	if (input === "\x1b") return "escape-start";
diff --git a/lib/ui/auth-menu.ts b/lib/ui/auth-menu.ts
index bbfc44c1..dbd062ab 100644
--- a/lib/ui/auth-menu.ts
+++ b/lib/ui/auth-menu.ts
@@ -1,8 +1,11 @@
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
 import { ANSI, isTTY } from "./ansi.js";
 import { confirm } from "./confirm.js";
 import { getUiRuntimeOptions } from "./runtime.js";
 import { select, type MenuItem } from "./select.js";
-import { paintUiText, formatUiBadge } from "./format.js";
+import { paintUiText, formatUiBadge, quotaToneFromLeftPercent } from "./format.js";
+import { UI_COPY, formatCheckFlaggedLabel } from "./copy.js";
 
 export type AccountStatus =
 	| "active"
@@ -16,31 +19,64 @@ export type AccountStatus =
 
 export interface AccountInfo {
 	index: number;
+	sourceIndex?: number;
+	quickSwitchNumber?: number;
 	accountId?: string;
 	accountLabel?: string;
 	email?: string;
 	addedAt?: number;
 	lastUsed?: number;
 	status?: AccountStatus;
+	quotaSummary?: string;
+	quota5hLeftPercent?: number;
+	quota5hResetAtMs?: number;
+	quota7dLeftPercent?: number;
+	quota7dResetAtMs?: number;
+	quotaRateLimited?: boolean;
 	isCurrentAccount?: boolean;
 	enabled?: boolean;
+	showStatusBadge?: boolean;
+	showCurrentBadge?: boolean;
+	showLastUsed?: boolean;
+	showQuotaCooldown?: boolean;
+	showHintsForUnselectedRows?: boolean;
+	highlightCurrentRow?: boolean;
+	focusStyle?: "row-invert" | "chip";
+	statuslineFields?: string[];
 }
 
 export interface AuthMenuOptions {
 	flaggedCount?: number;
+	statusMessage?: string | (() => string | undefined);
 }
 
 export type AuthMenuAction =
 	| { type: "add" }
+	| { type: "forecast" }
+	| { type: "fix" }
+	| { type: "settings" }
 	| { type: "fresh" }
 	| { type: "check" }
 	| { type: "deep-check" }
 	| { type: "verify-flagged" }
 	| { type: "select-account"; account: AccountInfo }
+	| { type: "set-current-account"; account: AccountInfo }
+	| { type: "refresh-account"; account: AccountInfo }
+	| { type: "toggle-account"; account: AccountInfo }
+	| { type: "delete-account"; account: AccountInfo }
+	| { type: "search" }
 	| { type: "delete-all" }
 	| { type: "cancel" };
 
-export type AccountAction = "back" | "delete" | "refresh" | "toggle" | "cancel";
+export type AccountAction = "back" | "delete" | "refresh" | "toggle" | "set-current" | "cancel";
+
+function sanitizeTerminalText(value: string | undefined): string | undefined {
+	if (!value) return undefined;
+	return value
+		.replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, "")
+		.replace(/[\u0000-\u001f\u007f]/g, "")
+		.trim();
+}
 
 function formatRelativeTime(timestamp: number | undefined): string {
 	if (!timestamp) return "never";
@@ -59,112 +95,513 @@ function formatDate(timestamp: number | undefined): string {
 
 function statusBadge(status: AccountStatus | undefined): string {
 	const ui = getUiRuntimeOptions();
+	const withTone = (
+		label: string,
+		tone: "accent" | "success" | "warning" | "danger" | "muted",
+	): string => {
+		if (ui.v2Enabled) return formatUiBadge(ui, label, tone);
+		if (tone === "accent") return `${ANSI.bgGreen}${ANSI.black}[${label}]${ANSI.reset}`;
+		if (tone === "success") return `${ANSI.bgGreen}${ANSI.black}[${label}]${ANSI.reset}`;
+		if (tone === "warning") return `${ANSI.bgYellow}${ANSI.black}[${label}]${ANSI.reset}`;
+		if (tone === "danger") return `${ANSI.bgRed}${ANSI.white}[${label}]${ANSI.reset}`;
+		return `${ANSI.inverse}[${label}]${ANSI.reset}`;
+	};
+
 	if (ui.v2Enabled) {
 		switch (status) {
 			case "active":
-				return formatUiBadge(ui, "active", "success");
+				return withTone("active", "success");
 			case "ok":
-				return formatUiBadge(ui, "ok", "success");
+				return withTone("ok", "success");
 			case "rate-limited":
-				return formatUiBadge(ui, "rate-limited", "warning");
+				return withTone("rate-limited", "warning");
 			case "cooldown":
-				return formatUiBadge(ui, "cooldown", "warning");
+				return withTone("cooldown", "warning");
 			case "flagged":
-				return formatUiBadge(ui, "flagged", "danger");
+				return withTone("flagged", "danger");
 			case "disabled":
-				return formatUiBadge(ui, "disabled", "danger");
+				return withTone("disabled", "danger");
 			case "error":
-				return formatUiBadge(ui, "error", "danger");
+				return withTone("error", "danger");
 			default:
-				return "";
+				return withTone("unknown", "muted");
 		}
 	}
 
 	switch (status) {
 		case "active":
-			return `${ANSI.green}[active]${ANSI.reset}`;
+			return withTone("active", "success");
 		case "ok":
-			return `${ANSI.green}[ok]${ANSI.reset}`;
+			return withTone("ok", "success");
 		case "rate-limited":
-			return `${ANSI.yellow}[rate-limited]${ANSI.reset}`;
+			return withTone("rate-limited", "warning");
 		case "cooldown":
-			return `${ANSI.yellow}[cooldown]${ANSI.reset}`;
+			return withTone("cooldown", "warning");
 		case "flagged":
-			return `${ANSI.red}[flagged]${ANSI.reset}`;
+			return withTone("flagged", "danger");
 		case "disabled":
-			return `${ANSI.red}[disabled]${ANSI.reset}`;
+			return withTone("disabled", "danger");
 		case "error":
-			return `${ANSI.red}[error]${ANSI.reset}`;
+			return withTone("error", "danger");
 		default:
-			return "";
+			return withTone("unknown", "muted");
 	}
 }
 
 function accountTitle(account: AccountInfo): string {
+	const accountNumber = account.quickSwitchNumber ?? (account.index + 1);
 	const base =
-		account.email?.trim() ||
-		account.accountLabel?.trim() ||
-		account.accountId?.trim() ||
-		`Account ${account.index + 1}`;
-	return `${account.index + 1}. ${base}`;
+		sanitizeTerminalText(account.email) ||
+		sanitizeTerminalText(account.accountLabel) ||
+		sanitizeTerminalText(account.accountId) ||
+		`Account ${accountNumber}`;
+	return `${accountNumber}. ${base}`;
+}
+
+function accountSearchText(account: AccountInfo): string {
+	return [
+		sanitizeTerminalText(account.email),
+		sanitizeTerminalText(account.accountLabel),
+		sanitizeTerminalText(account.accountId),
+		String(account.quickSwitchNumber ?? (account.index + 1)),
+	]
+		.filter((value): value is string => typeof value === "string" && value.trim().length > 0)
+		.join(" ")
+		.toLowerCase();
+}
+
+function accountRowColor(account: AccountInfo): MenuItem<AuthMenuAction>["color"] {
+	if (account.isCurrentAccount && account.highlightCurrentRow !== false) return "green";
+	switch (account.status) {
+		case "active":
+		case "ok":
+			return "green";
+		case "rate-limited":
+		case "cooldown":
+			return "yellow";
+		case "disabled":
+		case "error":
+		case "flagged":
+			return "red";
+		default:
+			return "yellow";
+	}
+}
+
+function statusTone(status: AccountStatus | undefined): "success" | "warning" | "danger" | "muted" {
+	switch (status) {
+		case "active":
+		case "ok":
+			return "success";
+		case "rate-limited":
+		case "cooldown":
+			return "warning";
+		case "disabled":
+		case "error":
+		case "flagged":
+			return "danger";
+		default:
+			return "muted";
+	}
+}
+
+function statusText(status: AccountStatus | undefined): string {
+	return status ?? "unknown";
+}
+
+function normalizeQuotaPercent(value: number | undefined): number | null {
+	if (typeof value !== "number" || !Number.isFinite(value)) return null;
+	return Math.max(0, Math.min(100, Math.round(value)));
+}
+
+function parseLeftPercentFromSummary(summary: string, windowLabel: "5h" | "7d"): number | null {
+	const segments = summary.split("|");
+	for (const segment of segments) {
+		const trimmed = segment.trim().toLowerCase();
+		if (!trimmed.startsWith(`${windowLabel} `)) continue;
+		const percentToken = trimmed.slice(windowLabel.length).trim().split(/\s+/)[0] ?? "";
+		const parsed = Number.parseInt(percentToken.replace("%", ""), 10);
+		if (!Number.isFinite(parsed)) continue;
+		return Math.max(0, Math.min(100, parsed));
+	}
+	return null;
+}
+
+function formatDurationCompact(milliseconds: number): string {
+	const totalSeconds = Math.max(0, Math.ceil(milliseconds / 1_000));
+	if (totalSeconds < 60) return `${totalSeconds}s`;
+	const totalMinutes = Math.floor(totalSeconds / 60);
+	if (totalMinutes < 60) {
+		const seconds = totalSeconds % 60;
+		return seconds > 0 ? `${totalMinutes}m ${seconds}s` : `${totalMinutes}m`;
+	}
+	const totalHours = Math.floor(totalMinutes / 60);
+	if (totalHours < 24) {
+		const minutes = totalMinutes % 60;
+		return minutes > 0 ? `${totalHours}h ${minutes}m` : `${totalHours}h`;
+	}
+	const days = Math.floor(totalHours / 24);
+	const hours = totalHours % 24;
+	return hours > 0 ? `${days}d ${hours}h` : `${days}d`;
+}
+
+function formatLimitCooldown(resetAtMs: number | undefined): string | null {
+	if (typeof resetAtMs !== "number" || !Number.isFinite(resetAtMs)) return null;
+	const remaining = resetAtMs - Date.now();
+	if (remaining <= 0) return "reset ready";
+	return `reset ${formatDurationCompact(remaining)}`;
+}
+
+function formatQuotaBar(
+	leftPercent: number | null,
+	ui: ReturnType<typeof getUiRuntimeOptions>,
+): string {
+	const width = 10;
+	const ratio = leftPercent === null ? 0 : leftPercent / 100;
+	const filled = Math.max(0, Math.min(width, Math.round(ratio * width)));
+	const filledText = "█".repeat(filled);
+	const emptyText = "▒".repeat(width - filled);
+	if (ui.v2Enabled) {
+		const tone = leftPercent === null ? "muted" : quotaToneFromLeftPercent(leftPercent);
+		const filledSegment = filledText.length > 0 ? paintUiText(ui, filledText, tone) : "";
+		const emptySegment = emptyText.length > 0 ? paintUiText(ui, emptyText, "muted") : "";
+		return `${filledSegment}${emptySegment}`;
+	}
+	if (leftPercent === null) return `${ANSI.dim}${emptyText}${ANSI.reset}`;
+	const color = leftPercent <= 15 ? ANSI.red : leftPercent <= 35 ? ANSI.yellow : ANSI.green;
+	const filledSegment = filledText.length > 0 ? `${color}${filledText}${ANSI.reset}` : "";
+	const emptySegment = emptyText.length > 0 ? `${ANSI.dim}${emptyText}${ANSI.reset}` : "";
+	return `${filledSegment}${emptySegment}`;
+}
+
+function formatQuotaPercent(
+	leftPercent: number | null,
+	ui: ReturnType<typeof getUiRuntimeOptions>,
+): string | null {
+	if (leftPercent === null) return null;
+	const percentText = `${leftPercent}%`;
+	if (!ui.v2Enabled) {
+		const color = leftPercent <= 15 ? ANSI.red : leftPercent <= 35 ? ANSI.yellow : ANSI.green;
+		return `${color}${percentText}${ANSI.reset}`;
+	}
+	const tone = quotaToneFromLeftPercent(leftPercent);
+	return paintUiText(ui, percentText, tone);
+}
+
+function formatQuotaWindow(
+	label: "5h" | "7d",
+	leftPercent: number | null,
+	resetAtMs: number | undefined,
+	showCooldown: boolean,
+	ui: ReturnType<typeof getUiRuntimeOptions>,
+): string {
+	const labelText = ui.v2Enabled ? paintUiText(ui, label, "muted") : label;
+	const bar = formatQuotaBar(leftPercent, ui);
+	const percent = formatQuotaPercent(leftPercent, ui);
+	if (!showCooldown) {
+		return percent ? `${labelText} ${bar} ${percent}` : `${labelText} ${bar}`;
+	}
+	const cooldown = formatLimitCooldown(resetAtMs);
+	if (!cooldown) {
+		return percent ? `${labelText} ${bar} ${percent}` : `${labelText} ${bar}`;
+	}
+	const cooldownText = ui.v2Enabled ? paintUiText(ui, cooldown, "muted") : cooldown;
+	if (!percent) {
+		return `${labelText} ${bar} ${cooldownText}`;
+	}
+	return `${labelText} ${bar} ${percent} ${cooldownText}`;
+}
+
+function formatQuotaSummary(account: AccountInfo, ui: ReturnType<typeof getUiRuntimeOptions>): string {
+	const summary = account.quotaSummary ?? "";
+	const showCooldown = account.showQuotaCooldown !== false;
+	const left5h = normalizeQuotaPercent(account.quota5hLeftPercent) ?? parseLeftPercentFromSummary(summary, "5h");
+	const left7d = normalizeQuotaPercent(account.quota7dLeftPercent) ?? parseLeftPercentFromSummary(summary, "7d");
+	const segments: string[] = [];
+
+	if (left5h !== null || typeof account.quota5hResetAtMs === "number") {
+		segments.push(formatQuotaWindow("5h", left5h, account.quota5hResetAtMs, showCooldown, ui));
+	}
+	if (left7d !== null || typeof account.quota7dResetAtMs === "number") {
+		segments.push(formatQuotaWindow("7d", left7d, account.quota7dResetAtMs, showCooldown, ui));
+	}
+	if (account.quotaRateLimited || summary.toLowerCase().includes("rate-limited")) {
+		segments.push(ui.v2Enabled ? paintUiText(ui, "rate-limited", "danger") : `${ANSI.red}rate-limited${ANSI.reset}`);
+	}
+
+	if (segments.length === 0) {
+		if (!summary) return "";
+		return ui.v2Enabled ? paintUiText(ui, summary, "muted") : summary;
+	}
+
+	const separator = ui.v2Enabled ? ` ${paintUiText(ui, "|", "muted")} ` : " | ";
+	return segments.join(separator);
+}
+
+function formatAccountHint(account: AccountInfo, ui: ReturnType<typeof getUiRuntimeOptions>): string {
+	const withKey = (
+		key: string,
+		value: string,
+		tone: "heading" | "accent" | "muted" | "success" | "warning" | "danger",
+	) => {
+		if (!ui.v2Enabled) return `${key} ${value}`;
+		if (value.includes("\x1b[")) {
+			return `${paintUiText(ui, key, "muted")} ${value}`;
+		}
+		return `${paintUiText(ui, key, "muted")} ${paintUiText(ui, value, tone)}`;
+	};
+
+	const partsByKey = new Map<string, string>();
+	if (account.showStatusBadge === false) {
+		partsByKey.set("status", withKey("Status:", statusText(account.status), statusTone(account.status)));
+	}
+	if (account.showLastUsed !== false) {
+		partsByKey.set("last-used", withKey("Last used:", formatRelativeTime(account.lastUsed), "heading"));
+	}
+	const quotaSummaryText = formatQuotaSummary(account, ui);
+	if (quotaSummaryText) {
+		partsByKey.set("limits", withKey("Limits:", quotaSummaryText, "accent"));
+	}
+
+	const fields = account.statuslineFields && account.statuslineFields.length > 0
+		? account.statuslineFields
+		: ["last-used", "limits", "status"];
+	const orderedParts: string[] = [];
+	for (const field of fields) {
+		const part = partsByKey.get(field);
+		if (part) orderedParts.push(part);
+	}
+
+	if (orderedParts.length === 0) {
+		return "";
+	}
+
+	const separator = ui.v2Enabled ? ` ${paintUiText(ui, "|", "muted")} ` : " | ";
+	if (orderedParts.length === 1) {
+		return orderedParts[0] ?? "";
+	}
+
+	const firstLine = orderedParts.slice(0, 2).join(separator);
+	const secondLine = orderedParts.slice(2).join(separator);
+	return secondLine ? `${firstLine}${separator}${secondLine}` : firstLine;
+}
+
+async function promptSearchQuery(current: string): Promise<string> {
+	if (!input.isTTY || !output.isTTY) {
+		return current;
+	}
+
+	const rl = createInterface({ input, output });
+	try {
+		const suffix = current ? ` (${current})` : "";
+		const answer = await rl.question(`Search${suffix} (blank clears): `);
+		return answer.trim().toLowerCase();
+	} finally {
+		rl.close();
+	}
+}
+
+function authMenuFocusKey(action: AuthMenuAction): string {
+	switch (action.type) {
+		case "select-account":
+		case "set-current-account":
+		case "refresh-account":
+		case "toggle-account":
+		case "delete-account":
+			return `account:${action.account.sourceIndex ?? action.account.index}`;
+		case "add":
+		case "forecast":
+		case "fix":
+		case "settings":
+		case "fresh":
+		case "check":
+		case "deep-check":
+		case "verify-flagged":
+		case "search":
+		case "delete-all":
+		case "cancel":
+			return `action:${action.type}`;
+	}
 }
 
 export async function showAuthMenu(
 	accounts: AccountInfo[],
 	options: AuthMenuOptions = {},
 ): Promise<AuthMenuAction> {
-	const ui = getUiRuntimeOptions();
 	const flaggedCount = options.flaggedCount ?? 0;
-	const verifyLabel =
-		flaggedCount > 0
-			? `Verify flagged accounts (${flaggedCount})`
-			: "Verify flagged accounts";
-
-	const items: MenuItem<AuthMenuAction>[] = [
-		{ label: "Actions", value: { type: "cancel" }, kind: "heading" },
-		{ label: "Add account", value: { type: "add" }, color: "cyan" },
-		{ label: "Check quotas", value: { type: "check" }, color: "cyan" },
-		{ label: "Deep check accounts", value: { type: "deep-check" }, color: "cyan" },
-		{ label: verifyLabel, value: { type: "verify-flagged" }, color: "cyan" },
-		{ label: "Start fresh", value: { type: "fresh" }, color: "yellow" },
-		{ label: "", value: { type: "cancel" }, separator: true },
-		{ label: "Accounts", value: { type: "cancel" }, kind: "heading" },
-		...accounts.map((account) => {
-			const currentBadge = account.isCurrentAccount
-				? (ui.v2Enabled ? ` ${formatUiBadge(ui, "current", "accent")}` : ` ${ANSI.cyan}[current]${ANSI.reset}`)
-				: "";
-			const badge = statusBadge(account.status);
-			const disabledBadge =
-				account.enabled === false
-					? (ui.v2Enabled ? ` ${formatUiBadge(ui, "disabled", "danger")}` : ` ${ANSI.red}[disabled]${ANSI.reset}`)
-					: "";
-			const statusSuffix = badge ? ` ${badge}` : "";
-			const label = `${accountTitle(account)}${currentBadge}${statusSuffix}${disabledBadge}`;
-			return {
-				label: ui.v2Enabled ? paintUiText(ui, label, "heading") : label,
-				hint: `used ${formatRelativeTime(account.lastUsed)}`,
-				value: { type: "select-account" as const, account },
-			};
-		}),
-		{ label: "", value: { type: "cancel" }, separator: true },
-		{ label: "Danger zone", value: { type: "cancel" }, kind: "heading" },
-		{ label: "Delete all accounts", value: { type: "delete-all" }, color: "red" },
-	];
-
+	const verifyLabel = formatCheckFlaggedLabel(flaggedCount);
+	const ui = getUiRuntimeOptions();
+	let showDetailedHelp = false;
+	let searchQuery = "";
+	let focusKey = "action:add";
 	while (true) {
+		const normalizedSearch = searchQuery.trim().toLowerCase();
+		const visibleAccounts = normalizedSearch.length > 0
+			? accounts.filter((account) => accountSearchText(account).includes(normalizedSearch))
+			: accounts;
+		const visibleByNumber = new Map<number, AccountInfo>();
+		const duplicateQuickSwitchNumbers = new Set<number>();
+		for (const account of visibleAccounts) {
+			const quickSwitchNumber = account.quickSwitchNumber ?? (account.index + 1);
+			if (visibleByNumber.has(quickSwitchNumber)) {
+				duplicateQuickSwitchNumbers.add(quickSwitchNumber);
+				continue;
+			}
+			visibleByNumber.set(quickSwitchNumber, account);
+		}
+
+		const items: MenuItem<AuthMenuAction>[] = [
+			{ label: UI_COPY.mainMenu.quickStart, value: { type: "cancel" }, kind: "heading" },
+			{ label: UI_COPY.mainMenu.addAccount, value: { type: "add" }, color: "green" },
+			{ label: UI_COPY.mainMenu.checkAccounts, value: { type: "check" }, color: "green" },
+			{ label: UI_COPY.mainMenu.bestAccount, value: { type: "forecast" }, color: "green" },
+			{ label: UI_COPY.mainMenu.fixIssues, value: { type: "fix" }, color: "green" },
+			{ label: UI_COPY.mainMenu.settings, value: { type: "settings" }, color: "green" },
+			{ label: "", value: { type: "cancel" }, separator: true },
+			{ label: UI_COPY.mainMenu.moreChecks, value: { type: "cancel" }, kind: "heading" },
+			{ label: UI_COPY.mainMenu.refreshChecks, value: { type: "deep-check" }, color: "green" },
+			{ label: verifyLabel, value: { type: "verify-flagged" }, color: flaggedCount > 0 ? "red" : "yellow" },
+			{ label: "", value: { type: "cancel" }, separator: true },
+			{ label: UI_COPY.mainMenu.accounts, value: { type: "cancel" }, kind: "heading" },
+		];
+
+		if (visibleAccounts.length === 0) {
+			items.push({
+				label: UI_COPY.mainMenu.noSearchMatches,
+				value: { type: "cancel" },
+				disabled: true,
+			});
+		} else {
+			items.push(
+				...visibleAccounts.map((account) => {
+					const currentBadge = account.isCurrentAccount && account.showCurrentBadge !== false
+						? (ui.v2Enabled ? ` ${formatUiBadge(ui, "current", "accent")}` : ` ${ANSI.cyan}[current]${ANSI.reset}`)
+						: "";
+					const badge = account.showStatusBadge === false ? "" : statusBadge(account.status);
+					const statusSuffix = badge ? ` ${badge}` : "";
+					const title = ui.v2Enabled
+						? paintUiText(ui, accountTitle(account), account.isCurrentAccount ? "accent" : "heading")
+						: accountTitle(account);
+					const label = `${title}${currentBadge}${statusSuffix}`;
+					const hint = formatAccountHint(account, ui);
+					const hasHint = hint.length > 0;
+					const hintText = ui.v2Enabled
+						? (hasHint ? hint : undefined)
+						: (hasHint ? hint : undefined);
+					return {
+						label,
+						hint: hintText,
+						color: accountRowColor(account),
+						value: { type: "select-account" as const, account },
+					};
+				}),
+			);
+		}
+
+		items.push({ label: "", value: { type: "cancel" }, separator: true });
+		items.push({ label: UI_COPY.mainMenu.dangerZone, value: { type: "cancel" }, kind: "heading" });
+		items.push({ label: UI_COPY.mainMenu.removeAllAccounts, value: { type: "delete-all" }, color: "red" });
+
+		const compactHelp = UI_COPY.mainMenu.helpCompact;
+		const detailedHelp = UI_COPY.mainMenu.helpDetailed;
+		const showHintsForUnselectedRows = visibleAccounts[0]?.showHintsForUnselectedRows ??
+			accounts[0]?.showHintsForUnselectedRows ??
+			false;
+		const focusStyle = visibleAccounts[0]?.focusStyle ??
+			accounts[0]?.focusStyle ??
+			"row-invert";
+		const resolveStatusMessage = (): string | undefined => {
+			const raw = typeof options.statusMessage === "function"
+				? options.statusMessage()
+				: options.statusMessage;
+			return typeof raw === "string" && raw.trim().length > 0 ? raw.trim() : undefined;
+		};
+		const buildSubtitle = (): string | undefined => {
+			const parts: string[] = [];
+			if (normalizedSearch.length > 0) {
+				parts.push(`${UI_COPY.mainMenu.searchSubtitlePrefix} ${normalizedSearch}`);
+			}
+			const statusText = resolveStatusMessage();
+			if (statusText) {
+				parts.push(statusText);
+			}
+			if (parts.length === 0) return undefined;
+			return parts.join(" | ");
+		};
+		const initialCursor = items.findIndex((item) => {
+			if (item.separator || item.disabled || item.kind === "heading") return false;
+			return authMenuFocusKey(item.value) === focusKey;
+		});
+
 		const result = await select(items, {
-			message: ui.v2Enabled ? "OpenAI accounts (Codex)" : "Codex accounts",
-			subtitle: "Select action or account",
+			message: UI_COPY.mainMenu.title,
+			subtitle: buildSubtitle(),
+			dynamicSubtitle: buildSubtitle,
+			help: showDetailedHelp ? detailedHelp : compactHelp,
 			clearScreen: true,
-			variant: ui.v2Enabled ? "codex" : "legacy",
+			selectedEmphasis: "minimal",
+			focusStyle,
+			showHintsForUnselected: showHintsForUnselectedRows,
+			refreshIntervalMs: 200,
+			initialCursor: initialCursor >= 0 ? initialCursor : undefined,
 			theme: ui.theme,
+			onInput: (input, context) => {
+				const lower = input.toLowerCase();
+				if (lower === "?") {
+					showDetailedHelp = !showDetailedHelp;
+					context.requestRerender();
+					return undefined;
+				}
+				if (lower === "q") {
+					return { type: "cancel" as const };
+				}
+				if (lower === "/") {
+					return { type: "search" as const };
+				}
+				const parsed = Number.parseInt(input, 10);
+				if (Number.isFinite(parsed) && parsed >= 1 && parsed <= 9) {
+					if (duplicateQuickSwitchNumbers.has(parsed)) {
+						return undefined;
+					}
+					const direct = visibleByNumber.get(parsed);
+					if (direct) {
+						return { type: "set-current-account" as const, account: direct };
+					}
+				}
+
+				const selected = context.items[context.cursor];
+				if (!selected || selected.separator || selected.disabled || selected.kind === "heading") {
+					return undefined;
+				}
+				if (selected.value.type !== "select-account") return undefined;
+				return undefined;
+			},
+			onCursorChange: ({ cursor }) => {
+				const selected = items[cursor];
+				if (!selected || selected.separator || selected.disabled || selected.kind === "heading") return;
+				focusKey = authMenuFocusKey(selected.value);
+			},
 		});
 
 		if (!result) return { type: "cancel" };
+		if (result.type === "search") {
+			searchQuery = await promptSearchQuery(searchQuery);
+			focusKey = "action:search";
+			continue;
+		}
 		if (result.type === "delete-all") {
 			const confirmed = await confirm("Delete all accounts?");
 			if (!confirmed) continue;
 		}
+		if (result.type === "delete-account") {
+			const confirmed = await confirm(`Delete ${accountTitle(result.account)}?`);
+			if (!confirmed) continue;
+		}
+		if (result.type === "refresh-account") {
+			const confirmed = await confirm(`Re-authenticate ${accountTitle(result.account)}?`);
+			if (!confirmed) continue;
+		}
+		focusKey = authMenuFocusKey(result);
 		return result;
 	}
 }
@@ -178,30 +615,54 @@ export async function showAccountDetails(account: AccountInfo): Promise<AccountA
 				? ` ${formatUiBadge(ui, "disabled", "danger")}`
 				: ` ${ANSI.red}[disabled]${ANSI.reset}`)
 			: "");
-	const subtitle = `Added: ${formatDate(account.addedAt)} | Last used: ${formatRelativeTime(account.lastUsed)}`;
+	const statusLabel = account.status ?? "unknown";
+	const subtitle = `Added: ${formatDate(account.addedAt)} | Used: ${formatRelativeTime(account.lastUsed)} | Status: ${statusLabel}`;
+	let focusAction: AccountAction = "back";
 
 	while (true) {
-		const action = await select<AccountAction>(
-			[
-				{ label: "Back", value: "back" },
-				{
-					label: account.enabled === false ? "Enable account" : "Disable account",
-					value: "toggle",
-					color: account.enabled === false ? "green" : "yellow",
-				},
-				{ label: "Refresh account", value: "refresh", color: "cyan" },
-				{ label: "Delete this account", value: "delete", color: "red" },
-			],
+		const items: MenuItem<AccountAction>[] = [
+			{ label: UI_COPY.accountDetails.back, value: "back" },
+			{
+				label: account.enabled === false ? UI_COPY.accountDetails.enable : UI_COPY.accountDetails.disable,
+				value: "toggle",
+				color: account.enabled === false ? "green" : "yellow",
+			},
 			{
-				message: header,
-				subtitle,
-				clearScreen: true,
-				variant: ui.v2Enabled ? "codex" : "legacy",
-				theme: ui.theme,
+				label: UI_COPY.accountDetails.setCurrent,
+				value: "set-current",
+				color: "green",
 			},
-		);
+			{ label: UI_COPY.accountDetails.refresh, value: "refresh", color: "green" },
+			{ label: UI_COPY.accountDetails.remove, value: "delete", color: "red" },
+		];
+		const initialCursor = items.findIndex((item) => item.value === focusAction);
+		const action = await select<AccountAction>(items, {
+			message: header,
+			subtitle,
+			help: UI_COPY.accountDetails.help,
+			clearScreen: true,
+			selectedEmphasis: "minimal",
+			focusStyle: account.focusStyle ?? "row-invert",
+			initialCursor: initialCursor >= 0 ? initialCursor : undefined,
+			theme: ui.theme,
+			onInput: (input) => {
+				const lower = input.toLowerCase();
+				if (lower === "q") return "cancel";
+				if (lower === "s") return "set-current";
+				if (lower === "r") return "refresh";
+				if (lower === "t" || lower === "e" || lower === "x") return "toggle";
+				if (lower === "d") return "delete";
+				return undefined;
+			},
+			onCursorChange: ({ cursor }) => {
+				const selected = items[cursor];
+				if (!selected || selected.separator || selected.disabled || selected.kind === "heading") return;
+				focusAction = selected.value;
+			},
+		});
 
 		if (!action) return "cancel";
+		focusAction = action;
 		if (action === "delete") {
 			const confirmed = await confirm(`Delete ${accountTitle(account)}?`);
 			if (!confirmed) continue;
@@ -215,4 +676,3 @@ export async function showAccountDetails(account: AccountInfo): Promise<AccountA
 }
 
 export { isTTY };
-
diff --git a/lib/ui/confirm.ts b/lib/ui/confirm.ts
index ccf9199f..d6366cd2 100644
--- a/lib/ui/confirm.ts
+++ b/lib/ui/confirm.ts
@@ -1,6 +1,15 @@
 import { select } from "./select.js";
 import { getUiRuntimeOptions } from "./runtime.js";
 
+/**
+ * Prompt the user with a Yes/No choice.
+ *
+ * Assumes a single interactive UI context; concurrent prompts may interleave. Does not access the filesystem (no Windows-specific filesystem effects). Callers should redact sensitive tokens from `message` before passing it to this prompt.
+ *
+ * @param message - The prompt text shown to the user
+ * @param defaultYes - If true, "Yes" is presented first and treated as the default ordering
+ * @returns `true` if the user selects "Yes", `false` otherwise
+ */
 export async function confirm(message: string, defaultYes = false): Promise<boolean> {
 	const ui = getUiRuntimeOptions();
 	const items = defaultYes
@@ -15,7 +24,6 @@ export async function confirm(message: string, defaultYes = false): Promise<bool
 
 	const result = await select(items, {
 		message,
-		variant: ui.v2Enabled ? "codex" : "legacy",
 		theme: ui.theme,
 	});
 	return result ?? false;
diff --git a/lib/ui/copy.ts b/lib/ui/copy.ts
new file mode 100644
index 00000000..fd05aadf
--- /dev/null
+++ b/lib/ui/copy.ts
@@ -0,0 +1,128 @@
+export const UI_COPY = {
+	mainMenu: {
+		title: "Accounts Dashboard",
+		searchSubtitlePrefix: "Search:",
+		quickStart: "Quick Actions",
+		addAccount: "Add New Account",
+		checkAccounts: "Run Health Check",
+		bestAccount: "Pick Best Account",
+		fixIssues: "Auto-Repair Issues",
+		settings: "Settings",
+		moreChecks: "Advanced Checks",
+		refreshChecks: "Refresh All Accounts",
+		checkFlagged: "Check Problem Accounts",
+		accounts: "Saved Accounts",
+		loadingLimits: "Fetching account limits...",
+		noSearchMatches: "No accounts match your search",
+		dangerZone: "Danger Zone",
+		removeAllAccounts: "Delete All Accounts",
+		helpCompact: "↑↓ Move | Enter Select | / Search | 1-9 Switch | Q Back",
+		helpDetailed: "Arrow keys move, Enter selects, / searches, 1-9 switches account, Q goes back",
+	},
+	accountDetails: {
+		back: "Back",
+		enable: "Enable Account",
+		disable: "Disable Account",
+		setCurrent: "Set As Current",
+		refresh: "Re-Login",
+		remove: "Delete Account",
+		help: "↑↓ Move | Enter Select | S Use | R Sign In | D Delete | Q Back",
+	},
+	oauth: {
+		chooseModeTitle: "Sign-In Method",
+		chooseModeSubtitle: "How do you want to sign in?",
+		openBrowser: "Open Browser (Easy)",
+		manualMode: "Manual / Incognito",
+		back: "Back",
+		chooseModeHelp: "↑↓ Move | Enter Select | 1 Easy | 2 Manual | Q Back",
+		goTo: "Go to:",
+		copyOk: "Login link copied.",
+		copyFail: "Could not copy login link.",
+		pastePrompt: "Paste callback URL or code here (Q to cancel):",
+		browserOpened: "Browser opened.",
+		browserOpenFail: "Could not open browser. Use this link:",
+		waitingCallback: "Waiting for login callback on localhost:1455...",
+		callbackMissed: "No callback received. Paste manually.",
+		cancelled: "Sign-in cancelled.",
+		cancelledBackToMenu: "Sign-in cancelled. Going back to menu.",
+	},
+	returnFlow: {
+		continuePrompt: "Press Enter to go back.",
+		actionFailedPrompt: "Action failed. Press Enter to go back.",
+		autoReturn: (seconds: number) => `Returning in ${seconds}s... Press any key to pause.`,
+		paused: "Paused. Press any key to continue.",
+		working: "Running...",
+		done: "Done.",
+		failed: "Failed.",
+	},
+	settings: {
+		title: "Settings",
+		subtitle: "Customize menu, behavior, and backend",
+		help: "↑↓ Move | Enter Select | Q Back",
+		sectionTitle: "Basic",
+		advancedTitle: "Advanced",
+		exitTitle: "Back",
+		accountList: "Account List View",
+		summaryFields: "Summary Line",
+		behavior: "Menu Behavior",
+		theme: "Color Theme",
+		backend: "Backend Controls",
+		back: "Back",
+		previewHeading: "Live Preview",
+		displayHeading: "Options",
+		resetDefault: "Reset to Default",
+		saveAndBack: "Save and Back",
+		backNoSave: "Back Without Saving",
+		accountListTitle: "Account List View",
+		accountListSubtitle: "Choose row details and optional smart sorting",
+		accountListHelp: "Enter Toggle | Number Toggle | M Sort | L Layout | S Save | Q Save+Back",
+		summaryTitle: "Account Details Row",
+		summarySubtitle: "Choose and order detail fields",
+		summaryHelp: "Enter Toggle | 1-3 Toggle | [ ] Reorder | S Save | Q Save+Back",
+		behaviorTitle: "Return Behavior",
+		behaviorSubtitle: "Control how result screens return",
+		behaviorHelp: "Enter Select | 1-3 Delay | P Pause | L AutoFetch | F Status | T TTL | S Save | Q Save+Back",
+		themeTitle: "Color Theme",
+		themeSubtitle: "Pick base color and accent",
+		themeHelp: "Enter Select | 1-2 Base | S Save | Q Save+Back",
+		backendTitle: "Backend Controls",
+		backendSubtitle: "Tune sync, retry, and limit behavior",
+		backendHelp: "Enter Open | 1-4 Category | S Save | R Reset | Q Save+Back",
+		backendCategoriesHeading: "Categories",
+		backendCategoryTitle: "Backend Category",
+		backendCategoryHelp: "Enter Toggle/Adjust | +/- or [ ] Number | 1-9 Toggle | R Reset | Q Back",
+		backendToggleHeading: "Switches",
+		backendNumberHeading: "Numbers",
+		backendDecrease: "Decrease Focused Value",
+		backendIncrease: "Increase Focused Value",
+		backendResetCategory: "Reset Category",
+		backendBackToCategories: "Back to Categories",
+		baseTheme: "Base Color",
+		accentColor: "Accent Color",
+		actionTiming: "Auto Return Delay",
+		moveUp: "Move Focused Field Up",
+		moveDown: "Move Focused Field Down",
+	},
+	fallback: {
+		addAnotherTip: "Tip: Use private mode or sign out before adding another account.",
+		addAnotherQuestion: (count: number) => `Add another account? (${count} added) (y/n): `,
+		selectModePrompt:
+			"(a) add, (c) check, (b) best, fi(x), (s) settings, (d) deep, (g) problem, (f) fresh, (q) back [a/c/b/x/s/d/g/f/q]: ",
+		invalidModePrompt: "Use one of: a, c, b, x, s, d, g, f, q.",
+	},
+} as const;
+
+/**
+ * Builds the "Check Problem Accounts" label, appending the flagged count when greater than zero.
+ *
+ * This function is pure and has no side effects, is safe for concurrent use, performs no filesystem
+ * access (including Windows-specific behavior), and does not perform any token redaction.
+ *
+ * @param flaggedCount - The number of flagged accounts to show; if greater than zero the count is appended in parentheses.
+ * @returns The resulting label string: the base label when `flaggedCount` is 0 or less, otherwise the base label followed by ` (count)`.
+ */
+export function formatCheckFlaggedLabel(flaggedCount: number): string {
+	return flaggedCount > 0
+		? `${UI_COPY.mainMenu.checkFlagged} (${flaggedCount})`
+		: UI_COPY.mainMenu.checkFlagged;
+}
diff --git a/lib/ui/format.ts b/lib/ui/format.ts
index 5547a595..39169929 100644
--- a/lib/ui/format.ts
+++ b/lib/ui/format.ts
@@ -1,6 +1,7 @@
 import type { UiRuntimeOptions } from "./runtime.js";
 
 export type UiTextTone =
+	| "primary"
 	| "heading"
 	| "accent"
 	| "muted"
@@ -10,6 +11,7 @@ export type UiTextTone =
 	| "normal";
 
 const TONE_TO_COLOR: Record<UiTextTone, keyof UiRuntimeOptions["theme"]["colors"] | null> = {
+	primary: "primary",
 	heading: "heading",
 	accent: "accent",
 	muted: "muted",
@@ -19,6 +21,110 @@ const TONE_TO_COLOR: Record<UiTextTone, keyof UiRuntimeOptions["theme"]["colors"
 	normal: null,
 };
 
+/**
+ * Produce the ANSI/ANSI256/truecolor start and theme reset sequences for a badge given UI options and tone.
+ *
+ * @param ui - Runtime UI options used to select color profile, palette, accent, and the theme reset sequence
+ * @param tone - Badge tone: "primary", "accent", "success", "warning", "danger", or "muted"
+ * @returns The `start` escape sequence to begin badge styling and the `end` reset sequence from the theme
+ *
+ * Concurrency: pure and safe for concurrent use.
+ * Windows consoles: returned ANSI sequences may not be interpreted on older Windows terminals and can appear verbatim.
+ * Token redaction: returned strings contain raw ANSI codes and should be treated as presentation data (avoid leaking in sensitive logs).
+ */
+function badgeStyleForTone(
+	ui: UiRuntimeOptions,
+	tone: Exclude<UiTextTone, "normal" | "heading">,
+): { start: string; end: string } {
+	const end = ui.theme.colors.reset;
+	const isBlue = ui.palette === "blue";
+	const accent = ui.accent;
+	if (ui.colorProfile === "truecolor") {
+		const accentStart = (() => {
+			if (accent === "cyan") return "\x1b[48;2;8;89;106m\x1b[38;2;224;242;254m\x1b[1m";
+			if (accent === "blue") return "\x1b[48;2;30;64;175m\x1b[38;2;219;234;254m\x1b[1m";
+			if (accent === "yellow") return "\x1b[48;2;120;53;15m\x1b[38;2;255;247;237m\x1b[1m";
+			return "\x1b[48;2;20;83;45m\x1b[38;2;220;252;231m\x1b[1m";
+		})();
+		const successStart = isBlue
+			? "\x1b[48;2;30;64;175m\x1b[38;2;219;234;254m\x1b[1m"
+			: "\x1b[48;2;20;83;45m\x1b[38;2;220;252;231m\x1b[1m";
+		switch (tone) {
+			case "primary":
+			case "accent":
+				return { start: accentStart, end };
+			case "success":
+				return { start: successStart, end };
+			case "warning":
+				return { start: "\x1b[48;2;120;53;15m\x1b[38;2;255;247;237m\x1b[1m", end };
+			case "danger":
+				return { start: "\x1b[48;2;127;29;29m\x1b[38;2;254;226;226m\x1b[1m", end };
+			case "muted":
+				return { start: "\x1b[48;2;51;65;85m\x1b[38;2;226;232;240m\x1b[1m", end };
+		}
+	}
+
+	if (ui.colorProfile === "ansi256") {
+		const accentStart = (() => {
+			if (accent === "cyan") return "\x1b[48;5;23m\x1b[38;5;159m\x1b[1m";
+			if (accent === "blue") return "\x1b[48;5;19m\x1b[38;5;153m\x1b[1m";
+			if (accent === "yellow") return "\x1b[48;5;94m\x1b[38;5;230m\x1b[1m";
+			return "\x1b[48;5;22m\x1b[38;5;157m\x1b[1m";
+		})();
+		const successStart = isBlue
+			? "\x1b[48;5;19m\x1b[38;5;153m\x1b[1m"
+			: "\x1b[48;5;22m\x1b[38;5;157m\x1b[1m";
+		switch (tone) {
+			case "primary":
+			case "accent":
+				return { start: accentStart, end };
+			case "success":
+				return { start: successStart, end };
+			case "warning":
+				return { start: "\x1b[48;5;94m\x1b[38;5;230m\x1b[1m", end };
+			case "danger":
+				return { start: "\x1b[48;5;88m\x1b[38;5;224m\x1b[1m", end };
+			case "muted":
+				return { start: "\x1b[48;5;240m\x1b[38;5;255m\x1b[1m", end };
+		}
+	}
+
+	const accentStart = (() => {
+		if (accent === "cyan") return "\x1b[46m\x1b[30m\x1b[1m";
+		if (accent === "blue") return "\x1b[44m\x1b[97m\x1b[1m";
+		if (accent === "yellow") return "\x1b[43m\x1b[30m\x1b[1m";
+		return "\x1b[42m\x1b[30m\x1b[1m";
+	})();
+	const successStart = isBlue ? "\x1b[44m\x1b[97m\x1b[1m" : "\x1b[42m\x1b[30m\x1b[1m";
+	switch (tone) {
+		case "primary":
+		case "accent":
+			return { start: accentStart, end };
+		case "success":
+			return { start: successStart, end };
+		case "warning":
+			return { start: "\x1b[43m\x1b[30m\x1b[1m", end };
+		case "danger":
+			return { start: "\x1b[41m\x1b[97m\x1b[1m", end };
+		case "muted":
+			return { start: "\x1b[100m\x1b[97m\x1b[1m", end };
+	}
+}
+
+/**
+ * Colorize a text string according to the UI theme and tone.
+ *
+ * If `ui.v2Enabled` is false or the tone maps to no color, the original `text` is returned unchanged.
+ *
+ * Concurrency: pure and side-effect-free; safe to call concurrently.
+ * Filesystem: performs no I/O and behaves identically on Windows and other platforms.
+ * Token redaction: this function only wraps `text` with theme color tokens and does not redact or alter token contents.
+ *
+ * @param ui - Runtime UI options (used to determine theme colors and whether v2 styling is enabled)
+ * @param text - The text to colorize
+ * @param tone - The text tone to apply; when the tone maps to no color (e.g., "normal") the text is returned as-is
+ * @returns The input `text` wrapped with the theme color start token for `tone` and the theme reset token, or the original `text` if no color is applied
+ */
 export function paintUiText(ui: UiRuntimeOptions, text: string, tone: UiTextTone = "normal"): string {
 	if (!ui.v2Enabled) return text;
 	const colorKey = TONE_TO_COLOR[tone];
@@ -50,6 +156,20 @@ export function formatUiItem(
 	return `${bullet} ${paintUiText(ui, text, tone)}`;
 }
 
+/**
+ * Format a key/value pair for display, applying muted styling to the key and a configurable tone to the value when v2 UI is enabled.
+ *
+ * @param ui - Runtime UI options that control theming and v2 behavior
+ * @param key - The label for the value; a trailing colon is added when v2 is enabled
+ * @param value - The value text to display
+ * @param valueTone - Tone to apply to the value (e.g., "accent", "success"); "normal" leaves the value uncolored
+ *
+ * Concurrency: pure and safe to call concurrently.
+ * Windows: ANSI or truecolor sequences may not be interpreted on older Windows terminals.
+ * Redaction: this function does not redact sensitive tokens; callers must provide already-redacted values if needed.
+ *
+ * @returns The formatted key/value string, optionally wrapped with theme color sequences when v2 is enabled
+ */
 export function formatUiKeyValue(
 	ui: UiRuntimeOptions,
 	key: string,
@@ -62,12 +182,45 @@ export function formatUiKeyValue(
 	return `${keyText} ${valueText}`;
 }
 
+/**
+ * Format a badge label for the UI, applying tone-specific styling when v2 UI is enabled.
+ *
+ * @param ui - Runtime UI options that control styling, color profile, and v2 enablement
+ * @param label - Text to display inside the badge (will be wrapped in square brackets)
+ * @param tone - Visual tone for the badge; must not be `"normal"` or `"heading"`
+ * @returns The badge string; when v2 is disabled this is `"[label]"`, otherwise the label wrapped with start/end styling sequences
+ *
+ * @remarks
+ * Concurrency: safe to call concurrently; function is pure with respect to provided inputs.  
+ * Windows filesystem: output contains ANSI/ANSI256/truecolor escape sequences when v2 is enabled—terminal support may vary on Windows consoles.  
+ * Token redaction: this function does not perform any secret/token redaction; callers should redact sensitive values in `label` before calling if needed.
+ */
 export function formatUiBadge(
 	ui: UiRuntimeOptions,
 	label: string,
 	tone: Exclude<UiTextTone, "normal" | "heading"> = "accent",
 ): string {
 	const text = `[${label}]`;
-	return paintUiText(ui, text, tone);
+	if (!ui.v2Enabled) return text;
+	const style = badgeStyleForTone(ui, tone);
+	return `${style.start}${text}${style.end}`;
 }
 
+/**
+ * Selects a UI tone representing quota health based on remaining percentage.
+ *
+ * @param leftPercent - Percentage of quota remaining (typically 0–100)
+ * @returns `'success'` if `leftPercent` > 35, `'warning'` if `leftPercent` ≤ 35 and > 15, `'danger'` if `leftPercent` ≤ 15
+ *
+ * @remarks
+ * Concurrency: pure and side-effect-free; safe to call from concurrent contexts.
+ * Windows filesystem: no filesystem interaction.
+ * Token redaction: does not handle or emit sensitive tokens.
+ */
+export function quotaToneFromLeftPercent(
+	leftPercent: number,
+): Extract<UiTextTone, "success" | "warning" | "danger"> {
+	if (leftPercent <= 15) return "danger";
+	if (leftPercent <= 35) return "warning";
+	return "success";
+}
diff --git a/lib/ui/runtime.ts b/lib/ui/runtime.ts
index abaf6270..72a2b6e4 100644
--- a/lib/ui/runtime.ts
+++ b/lib/ui/runtime.ts
@@ -2,6 +2,8 @@ import {
 	createUiTheme,
 	type UiColorProfile,
 	type UiGlyphMode,
+	type UiPalette,
+	type UiAccent,
 	type UiTheme,
 } from "./theme.js";
 
@@ -9,6 +11,8 @@ export interface UiRuntimeOptions {
 	v2Enabled: boolean;
 	colorProfile: UiColorProfile;
 	glyphMode: UiGlyphMode;
+	palette: UiPalette;
+	accent: UiAccent;
 	theme: UiTheme;
 }
 
@@ -16,35 +20,72 @@ const DEFAULT_OPTIONS: UiRuntimeOptions = {
 	v2Enabled: true,
 	colorProfile: "truecolor",
 	glyphMode: "ascii",
+	palette: "green",
+	accent: "green",
 	theme: createUiTheme({
 		profile: "truecolor",
 		glyphMode: "ascii",
+		palette: "green",
+		accent: "green",
 	}),
 };
 
 let runtimeOptions: UiRuntimeOptions = { ...DEFAULT_OPTIONS };
 
+/**
+ * Update UI runtime options and recompute the derived theme.
+ *
+ * Unspecified fields in `options` retain their current values; the exported `runtimeOptions`
+ * object is replaced with a new object containing the resolved fields and a newly created
+ * `theme` based on `colorProfile`, `glyphMode`, `palette`, and `accent`.
+ *
+ * Concurrency: callers should synchronize externally if multiple callers may update options
+ * concurrently (updates are a single replacement and may race). Filesystem: this function
+ * performs no filesystem operations and is unaffected by Windows filesystem semantics.
+ * Token handling: this function does not perform token redaction or logging—sensitive
+ * values should be redacted by the caller before passing them in.
+ *
+ * @param options - Partial runtime options (omit `theme`); any omitted fields keep their current values
+ * @returns The resolved `UiRuntimeOptions` including the recomputed `theme`
+ */
 export function setUiRuntimeOptions(
 	options: Partial<Omit<UiRuntimeOptions, "theme">>,
 ): UiRuntimeOptions {
 	const v2Enabled = options.v2Enabled ?? runtimeOptions.v2Enabled;
 	const colorProfile = options.colorProfile ?? runtimeOptions.colorProfile;
 	const glyphMode = options.glyphMode ?? runtimeOptions.glyphMode;
+	const palette = options.palette ?? runtimeOptions.palette;
+	const accent = options.accent ?? runtimeOptions.accent;
 	runtimeOptions = {
 		v2Enabled,
 		colorProfile,
 		glyphMode,
-		theme: createUiTheme({ profile: colorProfile, glyphMode }),
+		palette,
+		accent,
+		theme: createUiTheme({ profile: colorProfile, glyphMode, palette, accent }),
 	};
 	return runtimeOptions;
 }
 
+/**
+ * Accesses the current UI runtime options.
+ *
+ * The returned object reflects the current in-memory runtime configuration; concurrent callers may observe updates made by others, so external synchronization is recommended when mutating options. This function performs no filesystem I/O (including on Windows) and the runtime options contain no sensitive tokens that require redaction.
+ *
+ * @returns The current UiRuntimeOptions object
+ */
 export function getUiRuntimeOptions(): UiRuntimeOptions {
 	return runtimeOptions;
 }
 
+/**
+ * Reset the UI runtime options to the default configuration.
+ *
+ * This replaces the global runtime options with a fresh shallow copy of DEFAULT_OPTIONS. Concurrent callers may observe the updated options immediately; callers that need isolation should clone the returned object. This operation performs no filesystem access (including on Windows). The runtime options contain only configuration fields and do not include sensitive tokens.
+ *
+ * @returns The new runtime options object set to the defaults
+ */
 export function resetUiRuntimeOptions(): UiRuntimeOptions {
 	runtimeOptions = { ...DEFAULT_OPTIONS };
 	return runtimeOptions;
 }
-
diff --git a/lib/ui/select.ts b/lib/ui/select.ts
index 3ba4a3c1..37724b7d 100644
--- a/lib/ui/select.ts
+++ b/lib/ui/select.ts
@@ -3,21 +3,44 @@ import type { UiTheme } from "./theme.js";
 
 export interface MenuItem<T = string> {
 	label: string;
+	selectedLabel?: string;
 	value: T;
 	hint?: string;
 	disabled?: boolean;
+	hideUnavailableSuffix?: boolean;
 	separator?: boolean;
 	kind?: "heading";
 	color?: "red" | "green" | "yellow" | "cyan";
 }
 
-export interface SelectOptions {
+export interface SelectOptions<T = string> {
 	message: string;
 	subtitle?: string;
+	dynamicSubtitle?: () => string | undefined;
 	help?: string;
 	clearScreen?: boolean;
-	variant?: "legacy" | "codex";
 	theme?: UiTheme;
+	selectedEmphasis?: "chip" | "minimal";
+	focusStyle?: "row-invert" | "chip";
+	showHintsForUnselected?: boolean;
+	refreshIntervalMs?: number;
+	initialCursor?: number;
+	allowEscape?: boolean;
+	onCursorChange?: (
+		context: {
+			cursor: number;
+			items: MenuItem<T>[];
+			requestRerender: () => void;
+		},
+	) => void;
+	onInput?: (
+		input: string,
+		context: {
+			cursor: number;
+			items: MenuItem<T>[];
+			requestRerender: () => void;
+		},
+	) => T | null | undefined;
 }
 
 const ESCAPE_TIMEOUT_MS = 50;
@@ -28,6 +51,19 @@ function stripAnsi(input: string): string {
 	return input.replace(ANSI_REGEX, "");
 }
 
+/**
+ * Truncates a string to at most a given number of visible characters while preserving ANSI SGR sequences.
+ *
+ * Preserves ANSI color/formatting codes in the returned string and appends "..." (or "." / shorter sequences)
+ * as a visible truncation suffix when the visible length exceeds `maxVisibleChars`.
+ *
+ * Concurrency: function is pure and safe for concurrent use. Filesystem: behavior is independent of OS (including Windows).
+ * Token handling: this function does not redact or interpret token semantics; it only preserves ANSI escape sequences.
+ *
+ * @param input - The input string which may contain ANSI SGR escape sequences.
+ * @param maxVisibleChars - Maximum number of visible (non-ANSI) characters to keep; values <= 0 yield an empty string.
+ * @returns The input string truncated so its visible character count does not exceed `maxVisibleChars`, with ANSI codes preserved and a truncation suffix appended when truncation occurred.
+ */
 function truncateAnsi(input: string, maxVisibleChars: number): string {
 	if (maxVisibleChars <= 0) return "";
 	const visible = stripAnsi(input);
@@ -56,6 +92,14 @@ function truncateAnsi(input: string, maxVisibleChars: number): string {
 	return output + suffix;
 }
 
+/**
+ * Map a MenuItem color to its ANSI SGR color code.
+ *
+ * No concurrency effects; does not access the filesystem on Windows or other platforms; performs no token redaction.
+ *
+ * @param color - The menu item color ("red", "green", "yellow", "cyan") or undefined/other for no color
+ * @returns The ANSI SGR code for `color`, or an empty string if no color is specified
+ */
 function colorCode(color: MenuItem["color"]): string {
 	switch (color) {
 		case "red":
@@ -71,22 +115,68 @@ function colorCode(color: MenuItem["color"]): string {
 	}
 }
 
-function codexColorCode(theme: UiTheme, color: MenuItem["color"]): string {
-	switch (color) {
-		case "red":
-			return theme.colors.danger;
-		case "green":
-			return theme.colors.success;
-		case "yellow":
-			return theme.colors.warning;
-		case "cyan":
-			return theme.colors.accent;
-		default:
-			return theme.colors.heading;
+/**
+ * Decode a raw stdin buffer into a single printable "hotkey" character or `null` when none is available.
+ *
+ * Recognizes common VT-style numpad/keypad escape sequences and otherwise yields the first printable ASCII character in the input. Safe to call concurrently; it performs no filesystem or external I/O and behaves the same on Windows. This function never returns control or non-printable bytes, reducing the risk of leaking raw control sequences or sensitive tokens.
+ *
+ * @param data - Raw input buffer from stdin (may contain escape sequences or control bytes)
+ * @returns The decoded single-character hotkey (for example, `"0"`, `"a"`, `"+"`) or `null` if no printable character is present
+ */
+function decodeHotkeyInput(data: Buffer): string | null {
+	const input = data.toString("utf8");
+	// Common VT-style numpad sequences in raw mode.
+	const keypadMap: Record<string, string> = {
+		"\x1bOp": "0",
+		"\x1bOq": "1",
+		"\x1bOr": "2",
+		"\x1bOs": "3",
+		"\x1bOt": "4",
+		"\x1bOu": "5",
+		"\x1bOv": "6",
+		"\x1bOw": "7",
+		"\x1bOx": "8",
+		"\x1bOy": "9",
+		"\x1bOk": "+",
+		"\x1bOm": "-",
+		"\x1bOj": "*",
+		"\x1bOo": "/",
+		"\x1bOn": ".",
+	};
+	const mapped = keypadMap[input];
+	if (mapped) return mapped;
+
+	// Fallback: strip control bytes and keep first printable ASCII char.
+	for (const ch of input) {
+		const code = ch.charCodeAt(0);
+		if (code >= 32 && code <= 126) return ch;
 	}
+	return null;
 }
 
-export async function select<T>(items: MenuItem<T>[], options: SelectOptions): Promise<T | null> {
+/**
+ * Present an interactive TTY menu, let the user navigate and choose an item.
+ *
+ * Mutates terminal state (raw mode, cursor visibility) and drives stdin/stdout until the
+ * prompt finishes. Emits ANSI control sequences; on Windows the result depends on the
+ * host terminal's ANSI support. Callers must not run this concurrently with other code
+ * that expects normal terminal stdin/stdout state and must redact any sensitive tokens
+ * in item labels/hints before calling.
+ *
+ * @param items - Menu items to display. Items with `disabled`, `separator`, or `kind === "heading"`
+ *                are non-selectable. If exactly one selectable item exists its `value` is returned
+ *                immediately.
+ * @param options - Configuration for the prompt (message, subtitle or `dynamicSubtitle`, theme,
+ *                  `focusStyle`, `initialCursor`, `allowEscape`, `onCursorChange`, `onInput`,
+ *                  `refreshIntervalMs`, `help`, `clearScreen`, and related display behavior).
+ *                  - `onInput` receives decoded hotkey input and may return a `T` to finish early
+ *                    or `undefined` to continue; it may call `requestRerender` via the provided context.
+ *                  - `onCursorChange` is invoked when the highlighted cursor changes and may request rerender.
+ * @returns The selected item's `value`, or `null` if the prompt was cancelled or could not be started.
+ *
+ * @throws If not running on a TTY, if `items` is empty, or if all menu items are non-selectable.
+ */
+export async function select<T>(items: MenuItem<T>[], options: SelectOptions<T>): Promise<T | null> {
 	if (!isTTY()) {
 		throw new Error("Interactive select requires a TTY terminal");
 	}
@@ -106,121 +196,83 @@ export async function select<T>(items: MenuItem<T>[], options: SelectOptions): P
 
 	const { stdin, stdout } = process;
 	let cursor = items.findIndex(isSelectable);
+	if (typeof options.initialCursor === "number" && Number.isFinite(options.initialCursor)) {
+		const bounded = Math.max(0, Math.min(items.length - 1, Math.trunc(options.initialCursor)));
+		cursor = bounded;
+	}
+	if (cursor < 0 || !isSelectable(items[cursor] as MenuItem<T>)) {
+		cursor = items.findIndex(isSelectable);
+	}
 	if (cursor < 0) cursor = 0;
 	let escapeTimeout: ReturnType<typeof setTimeout> | null = null;
 	let cleanedUp = false;
 	let renderedLines = 0;
+	let hasRendered = false;
+	let inputGuardUntil = 0;
+	const theme = options.theme;
+	let rerenderRequested = false;
 
-	const renderLegacy = () => {
-		const columns = stdout.columns ?? 80;
-		const rows = stdout.rows ?? 24;
-		const previousRenderedLines = renderedLines;
-
-		if (options.clearScreen) {
-			stdout.write(ANSI.clearScreen + ANSI.moveTo(1, 1));
-		} else if (previousRenderedLines > 0) {
-			stdout.write(ANSI.up(previousRenderedLines));
-		}
-
-		let linesWritten = 0;
-		const writeLine = (line: string) => {
-			stdout.write(`${ANSI.clearLine}${line}\n`);
-			linesWritten += 1;
-		};
+	const requestRerender = () => {
+		rerenderRequested = true;
+	};
 
-		const subtitleLines = options.subtitle ? 3 : 0;
-		const fixedLines = 1 + subtitleLines + 2;
-		const maxVisibleItems = Math.max(1, Math.min(items.length, rows - fixedLines - 1));
+	const notifyCursorChange = () => {
+		if (!options.onCursorChange) return;
+		rerenderRequested = false;
+		options.onCursorChange({
+			cursor,
+			items,
+			requestRerender,
+		});
+	};
 
-		let windowStart = 0;
-		let windowEnd = items.length;
-		if (items.length > maxVisibleItems) {
-			windowStart = cursor - Math.floor(maxVisibleItems / 2);
-			windowStart = Math.max(0, Math.min(windowStart, items.length - maxVisibleItems));
-			windowEnd = windowStart + maxVisibleItems;
+	const drainStdinBuffer = () => {
+		try {
+			let chunk: Buffer | string | null;
+			do {
+				chunk = stdin.read();
+			} while (chunk !== null);
+		} catch {
+			// best effort: ignore non-readable states
 		}
+	};
 
-		const visibleItems = items.slice(windowStart, windowEnd);
-		writeLine(`${ANSI.dim}+ ${ANSI.reset}${truncateAnsi(options.message, Math.max(1, columns - 4))}`);
-
-		if (options.subtitle) {
-			writeLine("|");
-			writeLine(`${ANSI.cyan}>${ANSI.reset} ${truncateAnsi(options.subtitle, Math.max(1, columns - 4))}`);
-			writeLine("");
+	const codexColorCode = (color: MenuItem["color"]): string => {
+		if (!theme) {
+			return colorCode(color);
 		}
-
-		for (let i = 0; i < visibleItems.length; i += 1) {
-			const itemIndex = windowStart + i;
-			const item = visibleItems[i];
-			if (!item) continue;
-
-			if (item.separator) {
-				writeLine("|");
-				continue;
-			}
-
-			if (item.kind === "heading") {
-				const heading = truncateAnsi(
-					`${ANSI.dim}${ANSI.bold}${item.label}${ANSI.reset}`,
-					Math.max(1, columns - 6),
-				);
-				writeLine(`${ANSI.cyan}|${ANSI.reset}  ${heading}`);
-				continue;
-			}
-
-			const selected = itemIndex === cursor;
-			let labelText: string;
-			if (item.disabled) {
-				labelText = `${ANSI.dim}${item.label} (unavailable)${ANSI.reset}`;
-			} else if (selected) {
-				const color = colorCode(item.color);
-				labelText = color ? `${color}${item.label}${ANSI.reset}` : item.label;
-				if (item.hint) {
-					labelText += ` ${ANSI.dim}${item.hint}${ANSI.reset}`;
-				}
-			} else {
-				const color = colorCode(item.color);
-				labelText = color
-					? `${ANSI.dim}${color}${item.label}${ANSI.reset}`
-					: `${ANSI.dim}${item.label}${ANSI.reset}`;
-				if (item.hint) {
-					labelText += ` ${ANSI.dim}${item.hint}${ANSI.reset}`;
-				}
-			}
-
-			labelText = truncateAnsi(labelText, Math.max(1, columns - 8));
-			if (selected) {
-				writeLine(`${ANSI.cyan}|${ANSI.reset}  ${ANSI.green}*${ANSI.reset} ${labelText}`);
-			} else {
-				writeLine(`${ANSI.cyan}|${ANSI.reset}  ${ANSI.dim}o${ANSI.reset} ${labelText}`);
-			}
+		switch (color) {
+			case "red":
+				return theme.colors.danger;
+			case "green":
+				return theme.colors.success;
+			case "yellow":
+				return theme.colors.warning;
+			case "cyan":
+				return theme.colors.accent;
+			default:
+				return theme.colors.heading;
 		}
+	};
 
-		const windowHint =
-			items.length > visibleItems.length ? ` (${windowStart + 1}-${windowEnd}/${items.length})` : "";
-		const helpText = options.help ?? `Up/Down select | Enter confirm | Esc back${windowHint}`;
-		writeLine(
-			`${ANSI.cyan}|${ANSI.reset}  ${ANSI.dim}${truncateAnsi(helpText, Math.max(1, columns - 6))}${ANSI.reset}`,
-		);
-		writeLine(`${ANSI.cyan}+${ANSI.reset}`);
-
-		if (!options.clearScreen && previousRenderedLines > linesWritten) {
-			const extra = previousRenderedLines - linesWritten;
-			for (let i = 0; i < extra; i += 1) {
-				writeLine("");
-			}
+	const selectedLabelStart = (): string => {
+		if (!theme) {
+			return `${ANSI.bgGreen}${ANSI.black}${ANSI.bold}`;
 		}
-
-		renderedLines = linesWritten;
+		return `${theme.colors.focusBg}${theme.colors.focusText}${ANSI.bold}`;
 	};
 
-	const renderCodex = (theme: UiTheme) => {
+	const render = () => {
 		const columns = stdout.columns ?? 80;
 		const rows = stdout.rows ?? 24;
 		const previousRenderedLines = renderedLines;
+		const subtitleText = options.dynamicSubtitle ? options.dynamicSubtitle() : options.subtitle;
+		const focusStyle = options.focusStyle ?? "row-invert";
+		let didFullClear = false;
 
-		if (options.clearScreen) {
+		if (options.clearScreen && !hasRendered) {
 			stdout.write(ANSI.clearScreen + ANSI.moveTo(1, 1));
+			didFullClear = true;
 		} else if (previousRenderedLines > 0) {
 			stdout.write(ANSI.up(previousRenderedLines));
 		}
@@ -231,7 +283,7 @@ export async function select<T>(items: MenuItem<T>[], options: SelectOptions): P
 			linesWritten += 1;
 		};
 
-		const subtitleLines = options.subtitle ? 2 : 0;
+		const subtitleLines = subtitleText ? 2 : 0;
 		const fixedLines = 2 + subtitleLines + 2;
 		const maxVisibleItems = Math.max(1, Math.min(items.length, rows - fixedLines - 1));
 
@@ -244,21 +296,20 @@ export async function select<T>(items: MenuItem<T>[], options: SelectOptions): P
 		}
 
 		const visibleItems = items.slice(windowStart, windowEnd);
-		const border = theme.colors.border;
-		const muted = theme.colors.muted;
-		const heading = theme.colors.heading;
-		const accent = theme.colors.accent;
-		const reset = theme.colors.reset;
-		const selectedGlyph = theme.glyphs.selected;
-		const unselectedGlyph = theme.glyphs.unselected;
+		const border = theme?.colors.border ?? ANSI.dim;
+		const muted = theme?.colors.muted ?? ANSI.dim;
+		const heading = theme?.colors.heading ?? ANSI.reset;
+		const reset = theme?.colors.reset ?? ANSI.reset;
+		const selectedGlyph = theme?.glyphs.selected ?? ">";
+		const unselectedGlyph = theme?.glyphs.unselected ?? "o";
+		const selectedGlyphColor = theme?.colors.success ?? ANSI.green;
+		const selectedChip = selectedLabelStart();
 
 		writeLine(`${border}+${reset} ${heading}${truncateAnsi(options.message, Math.max(1, columns - 4))}${reset}`);
-		if (options.subtitle) {
-			writeLine(
-				`${border}|${reset} ${muted}${truncateAnsi(options.subtitle, Math.max(1, columns - 4))}${reset}`,
-			);
+		if (subtitleText) {
+			writeLine(` ${muted}${truncateAnsi(subtitleText, Math.max(1, columns - 2))}${reset}`);
 		}
-		writeLine(`${border}|${reset}`);
+		writeLine("");
 
 		for (let i = 0; i < visibleItems.length; i += 1) {
 			const itemIndex = windowStart + i;
@@ -266,47 +317,75 @@ export async function select<T>(items: MenuItem<T>[], options: SelectOptions): P
 			if (!item) continue;
 
 			if (item.separator) {
-				writeLine(`${border}|${reset}`);
+				writeLine("");
 				continue;
 			}
 
 			if (item.kind === "heading") {
-				const headingText = truncateAnsi(
-					`${theme.colors.dim}${heading}${item.label}${reset}`,
-					Math.max(1, columns - 6),
+				const heading = truncateAnsi(
+					`${muted}${item.label}${reset}`,
+					Math.max(1, columns - 2),
 				);
-				writeLine(`${border}|${reset} ${headingText}`);
+				writeLine(` ${heading}`);
 				continue;
 			}
 
 			const selected = itemIndex === cursor;
-			const prefix = selected
-				? `${accent}${selectedGlyph}${reset}`
-				: `${muted}${unselectedGlyph}${reset}`;
-			const itemColor = codexColorCode(theme, item.color);
-			let labelText: string;
-			if (item.disabled) {
-				labelText = `${muted}${item.label} (unavailable)${reset}`;
-			} else if (selected) {
-				labelText = `${itemColor}${item.label}${reset}`;
+			if (selected) {
+				const selectedText = item.selectedLabel
+					? stripAnsi(item.selectedLabel)
+					: item.disabled
+						? item.hideUnavailableSuffix
+							? stripAnsi(item.label)
+							: `${stripAnsi(item.label)} (unavailable)`
+						: stripAnsi(item.label);
+				if (focusStyle === "row-invert") {
+					const rowText = `${selectedGlyph} ${selectedText}`;
+					const focusedRow = theme
+						? `${theme.colors.focusBg}${theme.colors.focusText}${ANSI.bold}${truncateAnsi(rowText, Math.max(1, columns - 2))}${reset}`
+						: `${ANSI.inverse}${truncateAnsi(rowText, Math.max(1, columns - 2))}${ANSI.reset}`;
+					writeLine(` ${focusedRow}`);
+				} else {
+					const selectedLabel = `${selectedChip}${selectedText}${reset}`;
+					writeLine(
+						` ${selectedGlyphColor}${selectedGlyph}${reset} ${truncateAnsi(selectedLabel, Math.max(1, columns - 4))}`,
+					);
+				}
+				if (item.hint) {
+					const detailLines = item.hint.split("\n").slice(0, 3);
+					for (const detailLine of detailLines) {
+						const detail = truncateAnsi(detailLine, Math.max(1, columns - 8));
+						writeLine(`   ${muted}${detail}${reset}`);
+					}
+				}
 			} else {
-				labelText = `${muted}${item.label}${reset}`;
-			}
-			if (item.hint) {
-				labelText += ` ${muted}${item.hint}${reset}`;
+				const itemColor = codexColorCode(item.color);
+				const labelText = item.disabled
+					? item.hideUnavailableSuffix
+						? `${muted}${item.label}${reset}`
+						: `${muted}${item.label} (unavailable)${reset}`
+					: `${itemColor}${item.label}${reset}`;
+				writeLine(
+					` ${muted}${unselectedGlyph}${reset} ${truncateAnsi(labelText, Math.max(1, columns - 4))}`,
+				);
+				if (item.hint && (options.showHintsForUnselected ?? true)) {
+					const detailLines = item.hint.split("\n").slice(0, 2);
+					for (const detailLine of detailLines) {
+						const detail = truncateAnsi(`${muted}${detailLine}${reset}`, Math.max(1, columns - 8));
+						writeLine(`   ${detail}`);
+					}
+				}
 			}
-
-			labelText = truncateAnsi(labelText, Math.max(1, columns - 8));
-			writeLine(`${border}|${reset} ${prefix} ${labelText}`);
 		}
 
 		const windowHint =
 			items.length > visibleItems.length ? ` (${windowStart + 1}-${windowEnd}/${items.length})` : "";
-		const helpText = options.help ?? `Up/Down select | Enter confirm | Esc back${windowHint}`;
-		writeLine(`${border}|${reset} ${muted}${truncateAnsi(helpText, Math.max(1, columns - 4))}${reset}`);
+		const backLabel = "Q Back";
+		const helpText = options.help ?? `↑↓ Move | Enter Select | ${backLabel}${windowHint}`;
+		writeLine(` ${muted}${truncateAnsi(helpText, Math.max(1, columns - 2))}${reset}`);
 		writeLine(`${border}+${reset}`);
 
-		if (!options.clearScreen && previousRenderedLines > linesWritten) {
+		if (!didFullClear && previousRenderedLines > linesWritten) {
 			const extra = previousRenderedLines - linesWritten;
 			for (let i = 0; i < extra; i += 1) {
 				writeLine("");
@@ -314,18 +393,12 @@ export async function select<T>(items: MenuItem<T>[], options: SelectOptions): P
 		}
 
 		renderedLines = linesWritten;
-	};
-
-	const render = () => {
-		if (options.variant === "codex" && options.theme) {
-			renderCodex(options.theme);
-			return;
-		}
-		renderLegacy();
+		hasRendered = true;
 	};
 
 	return new Promise((resolve) => {
 		const wasRaw = stdin.isRaw ?? false;
+		let refreshTimer: ReturnType<typeof setInterval> | null = null;
 
 		const cleanup = () => {
 			if (cleanedUp) return;
@@ -340,6 +413,10 @@ export async function select<T>(items: MenuItem<T>[], options: SelectOptions): P
 				stdin.removeListener("data", onKey);
 				stdin.setRawMode(wasRaw);
 				stdin.pause();
+				if (refreshTimer) {
+					clearInterval(refreshTimer);
+					refreshTimer = null;
+				}
 				stdout.write(ANSI.show);
 			} catch {
 				// best effort cleanup
@@ -371,26 +448,74 @@ export async function select<T>(items: MenuItem<T>[], options: SelectOptions): P
 				escapeTimeout = null;
 			}
 
+			if (Date.now() < inputGuardUntil) {
+				const action = parseKey(data);
+				if (action === "enter" || action === "escape" || action === "escape-start") {
+					return;
+				}
+			}
+
 			const action = parseKey(data);
 			switch (action) {
 				case "up":
 					cursor = findNextSelectable(cursor, -1);
+					notifyCursorChange();
 					render();
 					return;
 				case "down":
 					cursor = findNextSelectable(cursor, 1);
+					notifyCursorChange();
 					render();
 					return;
+				case "home":
+					cursor = items.findIndex(isSelectable);
+					notifyCursorChange();
+					render();
+					return;
+				case "end": {
+					for (let i = items.length - 1; i >= 0; i -= 1) {
+						const item = items[i];
+						if (item && isSelectable(item)) {
+							cursor = i;
+							break;
+						}
+					}
+					notifyCursorChange();
+					render();
+					return;
+				}
 				case "enter":
 					finish(items[cursor]?.value ?? null);
 					return;
 				case "escape":
-					finish(null);
+					if (options.allowEscape !== false) {
+						finish(null);
+					}
 					return;
 				case "escape-start":
-					escapeTimeout = setTimeout(() => finish(null), ESCAPE_TIMEOUT_MS);
+					if (options.allowEscape !== false) {
+						escapeTimeout = setTimeout(() => finish(null), ESCAPE_TIMEOUT_MS);
+					}
 					return;
 				default:
+					if (options.onInput) {
+						const hotkey = decodeHotkeyInput(data);
+						if (hotkey) {
+							rerenderRequested = false;
+							const result = options.onInput(hotkey, {
+								cursor,
+								items,
+								requestRerender,
+							});
+							if (result !== undefined) {
+								finish(result);
+								return;
+							}
+							if (rerenderRequested) {
+								render();
+							}
+						}
+					}
 					return;
 			}
 		};
@@ -407,9 +532,17 @@ export async function select<T>(items: MenuItem<T>[], options: SelectOptions): P
 		}
 
 		stdin.resume();
+		drainStdinBuffer();
+		inputGuardUntil = Date.now() + 120;
 		stdout.write(ANSI.hide);
+		notifyCursorChange();
 		render();
+		if (options.dynamicSubtitle && (options.refreshIntervalMs ?? 0) > 0) {
+			const intervalMs = Math.max(80, Math.round(options.refreshIntervalMs ?? 0));
+			refreshTimer = setInterval(() => {
+				render();
+			}, intervalMs);
+		}
 		stdin.on("data", onKey);
 	});
 }
-
diff --git a/lib/ui/theme.ts b/lib/ui/theme.ts
index 56ebecbd..da0fc2d1 100644
--- a/lib/ui/theme.ts
+++ b/lib/ui/theme.ts
@@ -4,6 +4,8 @@
 
 export type UiColorProfile = "ansi16" | "ansi256" | "truecolor";
 export type UiGlyphMode = "ascii" | "unicode" | "auto";
+export type UiPalette = "green" | "blue";
+export type UiAccent = "green" | "cyan" | "blue" | "yellow";
 
 export interface UiGlyphSet {
 	selected: string;
@@ -18,11 +20,14 @@ export interface UiThemeColors {
 	dim: string;
 	muted: string;
 	heading: string;
+	primary: string;
 	accent: string;
 	success: string;
 	warning: string;
 	danger: string;
 	border: string;
+	focusBg: string;
+	focusText: string;
 }
 
 export interface UiTheme {
@@ -35,7 +40,17 @@ export interface UiTheme {
 const ansi16 = (code: number): string => `\x1b[${code}m`;
 const ansi256 = (code: number): string => `\x1b[38;5;${code}m`;
 const truecolor = (r: number, g: number, b: number): string => `\x1b[38;2;${r};${g};${b}m`;
+const ansi256Bg = (code: number): string => `\x1b[48;5;${code}m`;
+const truecolorBg = (r: number, g: number, b: number): string => `\x1b[48;2;${r};${g};${b}m`;
 
+/**
+ * Resolve a glyph mode, interpreting `"auto"` to choose `"unicode"` or `"ascii"` based on the environment.
+ *
+ * Safe for concurrent use, performs no filesystem operations (including on Windows), and does not expose or log sensitive tokens.
+ *
+ * @param mode - The requested glyph mode ("ascii", "unicode", or "auto")
+ * @returns `"unicode"` when Unicode is likely safe, `"ascii"` otherwise; if `mode` is not `"auto"`, returns it unchanged
+ */
 function resolveGlyphMode(mode: UiGlyphMode): Exclude<UiGlyphMode, "auto"> {
 	if (mode !== "auto") return mode;
 	const isLikelyUnicodeSafe =
@@ -45,6 +60,14 @@ function resolveGlyphMode(mode: UiGlyphMode): Exclude<UiGlyphMode, "auto"> {
 	return isLikelyUnicodeSafe ? "unicode" : "ascii";
 }
 
+/**
+ * Selects a glyph set appropriate for the given glyph mode.
+ *
+ * This function has no concurrency implications, performs no filesystem I/O (including on Windows), and does not perform any token redaction.
+ *
+ * @param mode - The resolved glyph mode; `'unicode'` yields Unicode glyphs, otherwise ASCII glyphs
+ * @returns The `UiGlyphSet` matching the requested `mode`
+ */
 function getGlyphs(mode: Exclude<UiGlyphMode, "auto">): UiGlyphSet {
 	if (mode === "unicode") {
 		return {
@@ -64,31 +87,96 @@ function getGlyphs(mode: Exclude<UiGlyphMode, "auto">): UiGlyphSet {
 	};
 }
 
-function getColors(profile: UiColorProfile): UiThemeColors {
+/**
+ * Selects the ANSI escape sequence for the requested accent color according to the color profile.
+ *
+ * This function is pure and has no side effects: it is safe for concurrent use, performs no filesystem operations (including on Windows), and does not perform any token redaction.
+ *
+ * @param profile - The color profile to use (`"truecolor"`, `"ansi256"`, or `"ansi16"`)
+ * @param accent - The accent name to resolve (`"green"`, `"cyan"`, `"blue"`, or `"yellow"`)
+ * @returns The escape sequence for the accent color suitable for use as a foreground color
+ */
+function accentColorForProfile(profile: UiColorProfile, accent: UiAccent): string {
+	switch (profile) {
+		case "truecolor":
+			switch (accent) {
+				case "cyan":
+					return truecolor(34, 211, 238);
+				case "blue":
+					return truecolor(59, 130, 246);
+				case "yellow":
+					return truecolor(245, 158, 11);
+				default:
+					return truecolor(74, 222, 128);
+			}
+		case "ansi256":
+			switch (accent) {
+				case "cyan":
+					return ansi256(51);
+				case "blue":
+					return ansi256(75);
+				case "yellow":
+					return ansi256(214);
+				default:
+					return ansi256(83);
+			}
+		default:
+			switch (accent) {
+				case "cyan":
+					return ansi16(96);
+				case "blue":
+					return ansi16(94);
+				case "yellow":
+					return ansi16(93);
+				default:
+					return ansi16(92);
+			}
+	}
+}
+
+/**
+ * Produce a set of terminal color tokens and focus/background values appropriate for the given color profile, palette, and accent.
+ *
+ * This function is safe for concurrent use (no shared mutable state), performs no filesystem operations (including on Windows), and returns color tokens that may contain ANSI escape sequences — treat those sequences as sensitive when logging or emitting to external telemetry and redact them as needed.
+ *
+ * @param profile - The color capability profile to target (`"ansi16" | "ansi256" | "truecolor"`)
+ * @param palette - The UI palette selection that influences primary/success/border colors (`"green" | "blue"`)
+ * @param accent - The accent color choice used for the `accent` token (`"green" | "cyan" | "blue" | "yellow"`)
+ * @returns A UiThemeColors object containing resolved color tokens (e.g., `reset`, `dim`, `muted`, `heading`, `primary`, `accent`, `success`, `warning`, `danger`, `border`, `focusBg`, and `focusText`)
+ */
+function getColors(profile: UiColorProfile, palette: UiPalette, accent: UiAccent): UiThemeColors {
+	const accentColor = accentColorForProfile(profile, accent);
+	const isBluePalette = palette === "blue";
 	switch (profile) {
 		case "truecolor":
 			return {
 				reset: "\x1b[0m",
 				dim: "\x1b[2m",
 				muted: truecolor(148, 163, 184),
-				heading: truecolor(226, 232, 240),
-				accent: truecolor(56, 189, 248),
-				success: truecolor(74, 222, 128),
-				warning: truecolor(251, 191, 36),
-				danger: truecolor(248, 113, 113),
-				border: truecolor(100, 116, 139),
+				heading: truecolor(240, 253, 244),
+				primary: isBluePalette ? truecolor(96, 165, 250) : truecolor(74, 222, 128),
+				accent: accentColor,
+				success: isBluePalette ? truecolor(96, 165, 250) : truecolor(74, 222, 128),
+				warning: truecolor(245, 158, 11),
+				danger: truecolor(239, 68, 68),
+				border: isBluePalette ? truecolor(59, 130, 246) : truecolor(34, 197, 94),
+				focusBg: isBluePalette ? truecolorBg(37, 99, 235) : truecolorBg(22, 101, 52),
+				focusText: truecolor(248, 250, 252),
 			};
 		case "ansi256":
 			return {
 				reset: "\x1b[0m",
 				dim: "\x1b[2m",
-				muted: ansi256(109),
+				muted: ansi256(102),
 				heading: ansi256(255),
-				accent: ansi256(45),
-				success: ansi256(84),
-				warning: ansi256(220),
-				danger: ansi256(203),
-				border: ansi256(67),
+				primary: isBluePalette ? ansi256(75) : ansi256(83),
+				accent: accentColor,
+				success: isBluePalette ? ansi256(75) : ansi256(83),
+				warning: ansi256(214),
+				danger: ansi256(196),
+				border: isBluePalette ? ansi256(27) : ansi256(40),
+				focusBg: isBluePalette ? ansi256Bg(26) : ansi256Bg(28),
+				focusText: ansi256(231),
 			};
 		default:
 			return {
@@ -96,27 +184,48 @@ function getColors(profile: UiColorProfile): UiThemeColors {
 				dim: "\x1b[2m",
 				muted: ansi16(37),
 				heading: ansi16(97),
-				accent: ansi16(96),
-				success: ansi16(92),
+				primary: isBluePalette ? ansi16(94) : ansi16(92),
+				accent: accentColor,
+				success: isBluePalette ? ansi16(94) : ansi16(92),
 				warning: ansi16(93),
 				danger: ansi16(91),
-				border: ansi16(90),
+				border: isBluePalette ? ansi16(94) : ansi16(92),
+				focusBg: isBluePalette ? "\x1b[104m" : "\x1b[102m",
+				focusText: "\x1b[30m",
 			};
 	}
 }
 
+/**
+ * Create a UI theme object for terminal rendering.
+ *
+ * @param options - Optional configuration:
+ *   - profile: color profile to use; defaults to `"truecolor"`.
+ *   - glyphMode: glyph rendering mode; defaults to `"ascii"`.
+ *   - palette: overall palette variant; defaults to `"green"`.
+ *   - accent: accent color selection; defaults to `"green"`.
+ * @returns The constructed UiTheme object containing `profile`, `glyphMode`, `glyphs`, and `colors`.
+ *
+ * @remarks
+ * - Concurrency: creation is pure and side-effect free, safe to call concurrently.
+ * - Windows filesystem: theme creation does not access the filesystem and has no platform-specific file behavior.
+ * - Token redaction: this function does not handle or emit secrets or sensitive tokens.
+ */
 export function createUiTheme(options?: {
 	profile?: UiColorProfile;
 	glyphMode?: UiGlyphMode;
+	palette?: UiPalette;
+	accent?: UiAccent;
 }): UiTheme {
 	const profile = options?.profile ?? "truecolor";
 	const glyphMode = options?.glyphMode ?? "ascii";
+	const palette = options?.palette ?? "green";
+	const accent = options?.accent ?? "green";
 	const resolvedGlyphMode = resolveGlyphMode(glyphMode);
 	return {
 		profile,
 		glyphMode,
 		glyphs: getGlyphs(resolvedGlyphMode),
-		colors: getColors(profile),
+		colors: getColors(profile, palette, accent),
 	};
 }
-
diff --git a/lib/unified-settings.ts b/lib/unified-settings.ts
new file mode 100644
index 00000000..ff63d894
--- /dev/null
+++ b/lib/unified-settings.ts
@@ -0,0 +1,321 @@
+import {
+	existsSync,
+	mkdirSync,
+	renameSync,
+	readFileSync,
+	unlinkSync,
+	writeFileSync,
+	promises as fs,
+} from "node:fs";
+import { join } from "node:path";
+import { getCodexMultiAuthDir } from "./runtime-paths.js";
+import { sleep } from "./utils.js";
+
+type JsonRecord = Record<string, unknown>;
+
+export const UNIFIED_SETTINGS_VERSION = 1 as const;
+
+const UNIFIED_SETTINGS_PATH = join(getCodexMultiAuthDir(), "settings.json");
+const RETRYABLE_FS_CODES = new Set(["EBUSY", "EPERM"]);
+let settingsWriteQueue: Promise<void> = Promise.resolve();
+
+function isRetryableFsError(error: unknown): boolean {
+	const code = (error as NodeJS.ErrnoException | undefined)?.code;
+	return typeof code === "string" && RETRYABLE_FS_CODES.has(code);
+}
+
+/**
+ * Determines whether a value is a non-null object suitable for use as a JsonRecord.
+ *
+ * @param value - The value to test
+ * @returns `true` if `value` is an object and not `null`, `false` otherwise
+ */
+function isRecord(value: unknown): value is JsonRecord {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * Return a shallow clone of an object-style record, or `null` if the input is not a record.
+ *
+ * @param value - Value to clone; must be a non-null plain object (record)
+ * @returns A new object containing the same own enumerable properties as `value`, or `null` if `value` is not a record
+ */
+function cloneRecord(value: unknown): JsonRecord | null {
+	if (!isRecord(value)) return null;
+	return { ...value };
+}
+
+/**
+ * Reads and parses the unified settings JSON file from disk.
+ *
+ * @returns The parsed settings object as a `JsonRecord`, or `null` if the settings file does not exist or cannot be read/parsed.
+ *
+ * @remarks
+ * - Concurrency: concurrent writers may produce transient read failures or partial files; atomicity is not guaranteed and callers should tolerate `null` and retry if needed.
+ * - Windows: file locking on Windows may cause reads to fail; in those cases this function returns `null`.
+ * - Sensitive data: this function performs no token or secret redaction; any sensitive values present in the file are returned as-is and callers are responsible for redaction before logging or external exposure.
+ */
+function readSettingsRecordSync(): JsonRecord | null {
+	if (!existsSync(UNIFIED_SETTINGS_PATH)) {
+		return null;
+	}
+
+	const raw = readFileSync(UNIFIED_SETTINGS_PATH, "utf8");
+	const parsed = cloneRecord(JSON.parse(raw));
+	if (!parsed) {
+		throw new Error("Unified settings must contain a JSON object at the root.");
+	}
+	return parsed;
+}
+
+/**
+ * Reads and parses the unified settings JSON file if present.
+ *
+ * This attempts to read and parse the file at the unified settings path and returns a shallow-cloned object on success. Returns `null` if the file does not exist, cannot be read, or contains invalid JSON. Concurrent writers may cause this call to return `null` or stale/partial data; callers should tolerate missing or malformed results. On Windows, path and permission semantics follow the Node runtime and may affect visibility. Consumers must redact any sensitive tokens before logging or returning the record.
+ *
+ * @returns The parsed settings record as an object clone, or `null` if unavailable or invalid.
+ */
+async function readSettingsRecordAsync(): Promise<JsonRecord | null> {
+	if (!existsSync(UNIFIED_SETTINGS_PATH)) {
+		return null;
+	}
+
+	const raw = await fs.readFile(UNIFIED_SETTINGS_PATH, "utf8");
+	const parsed = cloneRecord(JSON.parse(raw));
+	if (!parsed) {
+		throw new Error("Unified settings must contain a JSON object at the root.");
+	}
+	return parsed;
+}
+
+/**
+ * Return a shallow-cloned settings record with the canonical unified settings `version` applied.
+ *
+ * This function is pure and only normalizes the payload for disk writes; it does not coordinate or serialize
+ * concurrent writers (callers must handle concurrency). No platform-specific behavior is applied for Windows —
+ * the `version` field is always set. Sensitive values (tokens, secrets) are not redacted or transformed;
+ * callers must remove or redact them before writing if required.
+ *
+ * @param record - The input settings object to normalize; keys are preserved.
+ * @returns The shallow clone of `record` with `version` set to `UNIFIED_SETTINGS_VERSION`.
+ */
+function normalizeForWrite(record: JsonRecord): JsonRecord {
+	return {
+		...record,
+		version: UNIFIED_SETTINGS_VERSION,
+	};
+}
+
+/**
+ * Persist a unified settings record to the unified settings file on disk.
+ *
+ * Ensures the target directory exists, writes a pretty-printed, version-normalized JSON payload
+ * with a trailing newline to the configured unified settings path. This function does not
+ * redact, encrypt, or otherwise transform sensitive values — callers must remove or redact
+ * secrets (tokens, credentials) before calling.
+ *
+ * Concurrency: concurrent invocations may race and overwrite each other; callers should
+ * serialize writes if atomicity is required. Filesystem behavior (including atomicity and
+ * file-lock semantics) is platform-dependent and may differ on Windows.
+ *
+ * @param record - The settings object to persist; it will be normalized to include the unified settings version.
+ */
+function writeSettingsRecordSync(record: JsonRecord): void {
+	mkdirSync(getCodexMultiAuthDir(), { recursive: true });
+	const payload = normalizeForWrite(record);
+	const data = `${JSON.stringify(payload, null, 2)}\n`;
+	const tempPath = `${UNIFIED_SETTINGS_PATH}.${process.pid}.${Date.now()}.tmp`;
+	writeFileSync(tempPath, data, "utf8");
+	let moved = false;
+	try {
+		for (let attempt = 0; attempt < 5; attempt += 1) {
+			try {
+				renameSync(tempPath, UNIFIED_SETTINGS_PATH);
+				moved = true;
+				return;
+			} catch (error) {
+				if (!isRetryableFsError(error) || attempt >= 4) {
+					throw error;
+				}
+				Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10 * 2 ** attempt);
+			}
+		}
+	} finally {
+		if (!moved) {
+			try {
+				unlinkSync(tempPath);
+			} catch {
+				// Best-effort temp cleanup.
+			}
+		}
+	}
+}
+
+/**
+ * Write a normalized unified settings record to the shared settings.json file.
+ *
+ * The function ensures the multi-auth settings directory exists, normalizes the
+ * provided record by embedding the canonical settings version, and writes a
+ * pretty-printed JSON file with a trailing newline to the resolved settings path.
+ *
+ * Concurrency: concurrent writers may race; the last successful write wins. Callers
+ * should coordinate writes if atomic read-modify-write semantics are required.
+ *
+ * Windows filesystem note: file locking and rename atomicity differ on Windows;
+ * callers should handle possible sharing or locking errors when multiple processes
+ * interact with the file.
+ *
+ * Security note: this function does not redact or sanitize sensitive values (e.g.,
+ * tokens or secrets). Ensure any secrets are removed or redacted from `record`
+ * before calling.
+ *
+ * @param record - The settings object to persist; it will be normalized (version set)
+ */
+async function writeSettingsRecordAsync(record: JsonRecord): Promise<void> {
+	await fs.mkdir(getCodexMultiAuthDir(), { recursive: true });
+	const payload = normalizeForWrite(record);
+	const data = `${JSON.stringify(payload, null, 2)}\n`;
+	const tempPath = `${UNIFIED_SETTINGS_PATH}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2, 8)}.tmp`;
+	await fs.writeFile(tempPath, data, "utf8");
+	let moved = false;
+	try {
+		for (let attempt = 0; attempt < 5; attempt += 1) {
+			try {
+				await fs.rename(tempPath, UNIFIED_SETTINGS_PATH);
+				moved = true;
+				return;
+			} catch (error) {
+				if (!isRetryableFsError(error) || attempt >= 4) {
+					throw error;
+				}
+				await sleep(10 * 2 ** attempt);
+			}
+		}
+	} finally {
+		if (!moved) {
+			try {
+				await fs.unlink(tempPath);
+			} catch {
+				// Best-effort temp cleanup.
+			}
+		}
+	}
+}
+
+async function enqueueSettingsWrite<T>(task: () => Promise<T>): Promise<T> {
+	const run = settingsWriteQueue.catch(() => {}).then(task);
+	settingsWriteQueue = run.then(
+		() => undefined,
+		() => undefined,
+	);
+	return run;
+}
+
+/**
+ * Get the absolute filesystem path to the unified settings JSON file used for multi-auth plugins.
+ *
+ * The path points to the settings.json inside the Codex multi-auth directory. Callers should treat access as subject to typical filesystem race conditions (concurrent readers/writers may conflict), and be aware that on Windows the path uses platform separators returned by Node's path utilities. The file may contain sensitive tokens; redact or avoid logging file contents.
+ *
+ * @returns The absolute path to the unified settings JSON file
+ */
+export function getUnifiedSettingsPath(): string {
+	return UNIFIED_SETTINGS_PATH;
+}
+
+/**
+ * Loads the unified plugin configuration from the versioned settings file.
+ *
+ * Returns a shallow clone of the `pluginConfig` section if present; returns `null` when the settings file or the section is absent or unreadable.
+ *
+ * Note: callers should expect possible race conditions if other processes write the settings file concurrently; atomicity is not guaranteed across filesystems (including some Windows setups). This function does not redact or modify sensitive tokens—do not log or expose values returned here without first applying appropriate redaction.
+ *
+ * @returns A shallow clone of the `pluginConfig` object from the settings file, or `null` if unavailable.
+ */
+export function loadUnifiedPluginConfigSync(): JsonRecord | null {
+	try {
+		const record = readSettingsRecordSync();
+		if (!record) return null;
+		return cloneRecord(record.pluginConfig);
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Persist the given plugin configuration into the unified settings file synchronously.
+ *
+ * The provided `pluginConfig` is stored as the `pluginConfig` section of the on-disk
+ * settings payload (shallow-cloned before write). Callers are responsible for redacting
+ * any sensitive tokens or secrets prior to calling; values are written verbatim.
+ *
+ * Concurrency: no cross-process locking is performed — concurrent writers may overwrite
+ * each other. On Windows, write semantics and atomicity may differ from POSIX filesystems.
+ *
+ * @param pluginConfig - Key/value map representing plugin configuration to persist
+ */
+export function saveUnifiedPluginConfigSync(pluginConfig: JsonRecord): void {
+	const record = readSettingsRecordSync() ?? {};
+	record.pluginConfig = { ...pluginConfig };
+	writeSettingsRecordSync(record);
+}
+
+/**
+ * Persist the provided plugin configuration to the unified settings file, replacing the `pluginConfig` section.
+ *
+ * Writes a shallow clone of `pluginConfig` into the on-disk settings payload. In-process calls are serialized
+ * through an async queue to reduce lost-update races, but there is still no cross-process locking. On Windows,
+ * filesystem atomicity and visibility semantics are platform-dependent; do not assume atomic merges across processes.
+ * The settings file is written as plain JSON; redact or remove any sensitive tokens or secrets before calling.
+ *
+ * @param pluginConfig - The plugin configuration object to store (will be shallow-cloned)
+ */
+export async function saveUnifiedPluginConfig(pluginConfig: JsonRecord): Promise<void> {
+	await enqueueSettingsWrite(async () => {
+		const record = await readSettingsRecordAsync() ?? {};
+		record.pluginConfig = { ...pluginConfig };
+		await writeSettingsRecordAsync(record);
+	});
+}
+
+/**
+ * Load the dashboard display settings section from the unified settings file.
+ *
+ * Concurrency: callers should avoid concurrent conflicting writes to the settings file; concurrent readers are allowed but may observe intermediate state if a writer is in progress.
+ * Windows: note that filesystem semantics on Windows may cause exclusive locks or delayed visibility during writes.
+ * Secrets: this API does not perform token or secret redaction; callers must remove or mask sensitive values before saving.
+ *
+ * @returns A cloned `JsonRecord` with the `dashboardDisplaySettings` section, or `null` if the settings file is missing or cannot be parsed.
+ */
+export async function loadUnifiedDashboardSettings(): Promise<JsonRecord | null> {
+	try {
+		const record = await readSettingsRecordAsync();
+		if (!record) return null;
+		return cloneRecord(record.dashboardDisplaySettings);
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Persist dashboard display settings into the unified settings file.
+ *
+ * Writes `dashboardDisplaySettings` into the shared settings.json (overwriting
+ * any existing dashboardDisplaySettings section) and ensures the payload is
+ * normalized with the file version. In-process async callers are serialized
+ * through an internal queue (last writer still wins), but no cross-process lock
+ * is provided. On Windows, path and directory creation follow Node's filesystem
+ * semantics (case-insensitive paths, ACLs apply). Sensitive tokens or secrets
+ * included in `dashboardDisplaySettings` are written verbatim — callers must
+ * redact or omit secrets before calling.
+ *
+ * @param dashboardDisplaySettings - A plain JSON record describing dashboard display preferences; the object is shallow-copied before persisting.
+ */
+export async function saveUnifiedDashboardSettings(
+	dashboardDisplaySettings: JsonRecord,
+): Promise<void> {
+	await enqueueSettingsWrite(async () => {
+		const record = await readSettingsRecordAsync() ?? {};
+		record.dashboardDisplaySettings = { ...dashboardDisplaySettings };
+		await writeSettingsRecordAsync(record);
+	});
+}
diff --git a/package.json b/package.json
index b1a7aee3..b00a570f 100644
--- a/package.json
+++ b/package.json
@@ -56,7 +56,9 @@
     "prepare": "husky"
   },
   "bin": {
-    "codex-multi-auth": "scripts/install-opencode-codex-auth.js"
+    "codex": "scripts/codex.js",
+    "codex-multi-auth": "scripts/codex-multi-auth.js",
+    "codex-multi-auth-opencode-install": "scripts/install-opencode-codex-auth.js"
   },
   "files": [
     "dist/",
diff --git a/scripts/codex-multi-auth.js b/scripts/codex-multi-auth.js
new file mode 100644
index 00000000..aacf87fc
--- /dev/null
+++ b/scripts/codex-multi-auth.js
@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+
+import { runCodexMultiAuthCli } from "../dist/lib/codex-manager.js";
+
+const exitCode = await runCodexMultiAuthCli(process.argv.slice(2));
+process.exit(exitCode);
diff --git a/scripts/codex-routing.js b/scripts/codex-routing.js
new file mode 100644
index 00000000..aaa90009
--- /dev/null
+++ b/scripts/codex-routing.js
@@ -0,0 +1,34 @@
+const AUTH_SUBCOMMANDS = new Set([
+	"login",
+	"list",
+	"status",
+	"switch",
+	"check",
+	"features",
+	"verify-flagged",
+	"forecast",
+	"report",
+	"fix",
+	"doctor",
+]);
+
+export function normalizeAuthAlias(args) {
+	if (args.length >= 2 && args[0] === "multi" && args[1] === "auth") {
+		return ["auth", ...args.slice(2)];
+	}
+	if (args.length >= 1 && (args[0] === "multi-auth" || args[0] === "multiauth")) {
+		return ["auth", ...args.slice(1)];
+	}
+	return args;
+}
+
+export function shouldHandleMultiAuthAuth(args) {
+	if (args[0] !== "auth") return false;
+	if (args.length === 1) return true;
+	const subcommand = args[1];
+	if (typeof subcommand !== "string") return false;
+	if (subcommand.startsWith("-")) return true;
+	return AUTH_SUBCOMMANDS.has(subcommand);
+}
+
+export { AUTH_SUBCOMMANDS };
diff --git a/scripts/codex.js b/scripts/codex.js
new file mode 100644
index 00000000..0e16e412
--- /dev/null
+++ b/scripts/codex.js
@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+import { runCodexMultiAuthCli } from "../dist/lib/codex-manager.js";
+import { normalizeAuthAlias, shouldHandleMultiAuthAuth } from "./codex-routing.js";
+
+function resolveRealCodexBin() {
+	const override = (process.env.CODEX_MULTI_AUTH_REAL_CODEX_BIN ?? "").trim();
+	if (override.length > 0) {
+		if (existsSync(override)) return override;
+		console.error(
+			`CODEX_MULTI_AUTH_REAL_CODEX_BIN is set but missing: ${override}`,
+		);
+		return null;
+	}
+
+	try {
+		const require = createRequire(import.meta.url);
+		const resolved = require.resolve("@openai/codex/bin/codex.js");
+		if (existsSync(resolved)) return resolved;
+	} catch {
+		// Fall through to sibling lookup.
+	}
+
+	const searchRoots = [];
+	const scriptDir = dirname(fileURLToPath(import.meta.url));
+	searchRoots.push(join(scriptDir, "..", ".."));
+
+	const invokedScript = process.argv[1];
+	if (typeof invokedScript === "string" && invokedScript.length > 0) {
+		searchRoots.push(join(dirname(invokedScript), "..", ".."));
+	}
+
+	const npmPrefix = (process.env.npm_config_prefix ?? process.env.PREFIX ?? "").trim();
+	if (npmPrefix.length > 0) {
+		searchRoots.push(join(npmPrefix, "node_modules"));
+		searchRoots.push(join(npmPrefix, "lib", "node_modules"));
+	}
+
+	for (const root of searchRoots) {
+		const candidate = join(root, "@openai", "codex", "bin", "codex.js");
+		if (existsSync(candidate)) return candidate;
+	}
+
+	const npmCmd = process.platform === "win32" ? "npm.cmd" : "npm";
+	try {
+		const rootResult = spawnSync(npmCmd, ["root", "-g"], {
+			encoding: "utf8",
+			stdio: ["ignore", "pipe", "ignore"],
+		});
+		if (rootResult.status === 0) {
+			const globalRoot = rootResult.stdout.trim();
+			if (globalRoot.length > 0) {
+				const globalBin = join(globalRoot, "@openai", "codex", "bin", "codex.js");
+				if (existsSync(globalBin)) return globalBin;
+			}
+		}
+	} catch {
+		// Ignore and fall through to null.
+	}
+
+	return null;
+}
+
+function forwardToRealCodex(codexBin, args) {
+	return new Promise((resolve) => {
+		const child = spawn(process.execPath, [codexBin, ...args], {
+			stdio: "inherit",
+			env: process.env,
+		});
+
+		child.once("error", (error) => {
+			console.error(`Failed to launch real Codex CLI: ${String(error)}`);
+			resolve(1);
+		});
+
+		child.once("exit", (code, signal) => {
+			if (signal) {
+				const signalNumber = signal === "SIGINT" ? 130 : 1;
+				resolve(signalNumber);
+				return;
+			}
+			resolve(typeof code === "number" ? code : 1);
+		});
+	});
+}
+
+const rawArgs = process.argv.slice(2);
+const normalizedArgs = normalizeAuthAlias(rawArgs);
+const bypass = (process.env.CODEX_MULTI_AUTH_BYPASS ?? "").trim() === "1";
+
+if (!bypass && shouldHandleMultiAuthAuth(normalizedArgs)) {
+	try {
+		const exitCode = await runCodexMultiAuthCli(normalizedArgs);
+		process.exit(exitCode);
+	} catch (error) {
+		console.error(
+			`codex-multi-auth runner failed: ${error instanceof Error ? error.message : String(error)}`,
+		);
+		process.exit(1);
+	}
+}
+
+const realCodexBin = resolveRealCodexBin();
+if (!realCodexBin) {
+	console.error(
+		[
+			"Could not locate the official Codex CLI binary (@openai/codex).",
+			"Install it globally: npm install -g @openai/codex",
+			"Or set CODEX_MULTI_AUTH_REAL_CODEX_BIN to a full bin/codex.js path.",
+		].join("\n"),
+	);
+	process.exit(1);
+}
+
+const forwardExitCode = await forwardToRealCodex(realCodexBin, rawArgs);
+process.exit(forwardExitCode);
diff --git a/test/accounts.test.ts b/test/accounts.test.ts
index 0fbf30ba..8328909a 100644
--- a/test/accounts.test.ts
+++ b/test/accounts.test.ts
@@ -203,6 +203,99 @@ describe("AccountManager", () => {
     expect(manager.getCurrentAccount()?.refreshToken).toBe("refresh-token");
   });
 
+  it("returns account by index and rejects invalid indexes", () => {
+    const now = Date.now();
+    const stored = {
+      version: 3 as const,
+      activeIndex: 0,
+      accounts: [
+        { refreshToken: "token-1", addedAt: now, lastUsed: now },
+        { refreshToken: "token-2", addedAt: now, lastUsed: now },
+      ],
+    };
+
+    const manager = new AccountManager(undefined, stored);
+    expect(manager.getAccountByIndex(0)?.refreshToken).toBe("token-1");
+    expect(manager.getAccountByIndex(1)?.refreshToken).toBe("token-2");
+    expect(manager.getAccountByIndex(-1)).toBeNull();
+    expect(manager.getAccountByIndex(9)).toBeNull();
+    expect(manager.getAccountByIndex(Number.NaN)).toBeNull();
+  });
+
+  it("checks account availability by enabled/rate-limit/cooldown state", () => {
+    const now = Date.now();
+    const stored = {
+      version: 3 as const,
+      activeIndex: 0,
+      accounts: [
+        {
+          refreshToken: "token-1",
+          addedAt: now,
+          lastUsed: now,
+          enabled: false,
+        },
+        {
+          refreshToken: "token-2",
+          addedAt: now,
+          lastUsed: now,
+          rateLimitResetTimes: { codex: now + 60_000 },
+        },
+        {
+          refreshToken: "token-3",
+          addedAt: now,
+          lastUsed: now,
+          coolingDownUntil: now + 60_000,
+          cooldownReason: "network-error" as const,
+        },
+        {
+          refreshToken: "token-4",
+          addedAt: now,
+          lastUsed: now,
+        },
+      ],
+    };
+
+    const manager = new AccountManager(undefined, stored);
+
+    expect(manager.isAccountAvailableForFamily(0, "codex")).toBe(false);
+    expect(manager.isAccountAvailableForFamily(1, "codex")).toBe(false);
+    expect(manager.isAccountAvailableForFamily(2, "codex")).toBe(false);
+    expect(manager.isAccountAvailableForFamily(3, "codex")).toBe(true);
+  });
+
+  it("returns false for invalid account index in availability checks", () => {
+    const now = Date.now();
+    const stored = {
+      version: 3 as const,
+      activeIndex: 0,
+      accounts: [{ refreshToken: "token-1", addedAt: now, lastUsed: now }],
+    };
+    const manager = new AccountManager(undefined, stored);
+    expect(manager.isAccountAvailableForFamily(-1, "codex")).toBe(false);
+    expect(manager.isAccountAvailableForFamily(99, "codex")).toBe(false);
+    expect(manager.isAccountAvailableForFamily(Number.NaN, "codex")).toBe(false);
+  });
+
+  it("clears expired rate-limit windows before availability check", () => {
+    const now = Date.now();
+    const stored = {
+      version: 3 as const,
+      activeIndex: 0,
+      accounts: [
+        {
+          refreshToken: "token-1",
+          addedAt: now,
+          lastUsed: now,
+          rateLimitResetTimes: { codex: now - 1_000 },
+        },
+      ],
+    };
+    const manager = new AccountManager(undefined, stored);
+    expect(manager.isAccountAvailableForFamily(0, "codex")).toBe(true);
+    const account = manager.getAccountByIndex(0);
+    expect(account?.rateLimitResetTimes?.codex).toBeUndefined();
+  });
+
   it("rotates when the active account is rate-limited", () => {
     const now = Date.now();
     const stored = {
diff --git a/test/ansi.test.ts b/test/ansi.test.ts
new file mode 100644
index 00000000..7bfbd475
--- /dev/null
+++ b/test/ansi.test.ts
@@ -0,0 +1,26 @@
+import { describe, expect, it } from "vitest";
+import { parseKey } from "../lib/ui/ansi.js";
+
+describe("ansi parseKey", () => {
+	it("parses home key variants", () => {
+		expect(parseKey(Buffer.from("\x1b[H"))).toBe("home");
+		expect(parseKey(Buffer.from("\x1bOH"))).toBe("home");
+		expect(parseKey(Buffer.from("\x1b[1~"))).toBe("home");
+		expect(parseKey(Buffer.from("\x1b[7~"))).toBe("home");
+	});
+
+	it("parses end key variants", () => {
+		expect(parseKey(Buffer.from("\x1b[F"))).toBe("end");
+		expect(parseKey(Buffer.from("\x1bOF"))).toBe("end");
+		expect(parseKey(Buffer.from("\x1b[4~"))).toBe("end");
+		expect(parseKey(Buffer.from("\x1b[8~"))).toBe("end");
+	});
+
+	it("preserves existing arrow and escape parsing", () => {
+		expect(parseKey(Buffer.from("\x1b[A"))).toBe("up");
+		expect(parseKey(Buffer.from("\x1b[B"))).toBe("down");
+		expect(parseKey(Buffer.from("\x1b"))).toBe("escape-start");
+		expect(parseKey(Buffer.from("\x03"))).toBe("escape");
+		expect(parseKey(Buffer.from("\r"))).toBe("enter");
+	});
+});
diff --git a/test/auth-menu-hotkeys.test.ts b/test/auth-menu-hotkeys.test.ts
new file mode 100644
index 00000000..682a04a2
--- /dev/null
+++ b/test/auth-menu-hotkeys.test.ts
@@ -0,0 +1,180 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { AccountInfo } from "../lib/ui/auth-menu.js";
+
+const selectMock = vi.fn();
+const confirmMock = vi.fn(async () => true);
+
+vi.mock("../lib/ui/select.js", () => ({
+	select: selectMock,
+}));
+
+vi.mock("../lib/ui/confirm.js", () => ({
+	confirm: confirmMock,
+}));
+
+function createAccounts(): AccountInfo[] {
+	const baseTime = 1_700_000_000_000;
+	return [
+		{ index: 0, email: "first@example.com", status: "ok", lastUsed: baseTime - 1_000 },
+		{ index: 1, email: "second@example.com", status: "ok", lastUsed: baseTime },
+	];
+}
+
+describe("auth-menu hotkeys", () => {
+	beforeEach(() => {
+		vi.resetModules();
+		selectMock.mockReset();
+		confirmMock.mockReset();
+		confirmMock.mockResolvedValue(true);
+		Object.defineProperty(process.stdin, "isTTY", { value: false, configurable: true });
+		Object.defineProperty(process.stdout, "isTTY", { value: false, configurable: true });
+	});
+
+	afterEach(() => {
+		vi.restoreAllMocks();
+	});
+
+	it("supports numeric quick-switch hotkey (1-9)", async () => {
+		selectMock.mockImplementationOnce(async (items: unknown[], options: { onInput?: (...args: unknown[]) => unknown }) => {
+			if (!options.onInput) return null;
+			return options.onInput("2", {
+				cursor: 0,
+				items,
+				requestRerender: () => undefined,
+			});
+		});
+
+		const { showAuthMenu } = await import("../lib/ui/auth-menu.js");
+		const result = await showAuthMenu(createAccounts());
+
+		expect(result.type).toBe("set-current-account");
+		if (result.type === "set-current-account") {
+			expect(result.account.index).toBe(1);
+		}
+	});
+
+	it("ignores out-of-range numeric hotkeys and handles q cancel", async () => {
+		selectMock.mockImplementationOnce(
+			async (items: unknown[], options: { onInput?: (...args: unknown[]) => unknown }) => {
+				if (!options.onInput) return null;
+				expect(
+					options.onInput("0", {
+						cursor: 0,
+						items,
+						requestRerender: () => undefined,
+					}),
+				).toBeUndefined();
+				expect(
+					options.onInput("10", {
+						cursor: 0,
+						items,
+						requestRerender: () => undefined,
+					}),
+				).toBeUndefined();
+				return options.onInput("q", {
+					cursor: 0,
+					items,
+					requestRerender: () => undefined,
+				});
+			},
+		);
+
+		const { showAuthMenu } = await import("../lib/ui/auth-menu.js");
+		const result = await showAuthMenu(createAccounts());
+
+		expect(result).toEqual({ type: "cancel" });
+	});
+
+	it("does not quick-switch when quick-switch numbers collide", async () => {
+		selectMock
+			.mockImplementationOnce(
+				async (items: unknown[], options: { onInput?: (...args: unknown[]) => unknown }) => {
+					if (!options.onInput) return null;
+					expect(
+						options.onInput("2", {
+							cursor: 0,
+							items,
+							requestRerender: () => undefined,
+						}),
+					).toBeUndefined();
+					return { type: "cancel" };
+				},
+			);
+
+		const { showAuthMenu } = await import("../lib/ui/auth-menu.js");
+		const result = await showAuthMenu([
+			{ ...createAccounts()[0], quickSwitchNumber: 2 },
+			{ ...createAccounts()[1], quickSwitchNumber: 2 },
+		]);
+
+		expect(result).toEqual({ type: "cancel" });
+	});
+
+	it("supports search hotkey (/)", async () => {
+		selectMock
+			.mockImplementationOnce(async (items: unknown[], options: { onInput?: (...args: unknown[]) => unknown }) => {
+				if (!options.onInput) return null;
+				return options.onInput("/", {
+					cursor: 0,
+					items,
+					requestRerender: () => undefined,
+				});
+			})
+			.mockResolvedValueOnce({ type: "cancel" });
+
+		const { showAuthMenu } = await import("../lib/ui/auth-menu.js");
+		const result = await showAuthMenu(createAccounts());
+
+		expect(result).toEqual({ type: "cancel" });
+		expect(selectMock).toHaveBeenCalledTimes(2);
+	});
+
+	it("supports help toggle hotkey (?) and requests rerender", async () => {
+		let rerenderCalls = 0;
+		selectMock.mockImplementationOnce(async (items: unknown[], options: { onInput?: (...args: unknown[]) => unknown }) => {
+			if (options.onInput) {
+				const outcome = options.onInput("?", {
+					cursor: 0,
+					items,
+					requestRerender: () => {
+						rerenderCalls += 1;
+					},
+				});
+				expect(outcome).toBeUndefined();
+			}
+			return { type: "cancel" };
+		});
+
+		const { showAuthMenu } = await import("../lib/ui/auth-menu.js");
+		const result = await showAuthMenu(createAccounts());
+
+		expect(result).toEqual({ type: "cancel" });
+		expect(rerenderCalls).toBe(1);
+	});
+
+	it("renders compact account list by showing hints only for selected row", async () => {
+		selectMock.mockResolvedValueOnce({ type: "cancel" });
+
+		const { showAuthMenu } = await import("../lib/ui/auth-menu.js");
+		const result = await showAuthMenu(createAccounts());
+
+		expect(result).toEqual({ type: "cancel" });
+		const options = selectMock.mock.calls[0]?.[1] as { showHintsForUnselected?: boolean };
+		expect(options?.showHintsForUnselected).toBe(false);
+	});
+
+	it("shows details for unselected rows when account-list setting enables expanded rows", async () => {
+		selectMock.mockResolvedValueOnce({ type: "cancel" });
+
+		const { showAuthMenu } = await import("../lib/ui/auth-menu.js");
+		const accounts = createAccounts().map((account) => ({
+			...account,
+			showHintsForUnselectedRows: true,
+		}));
+		const result = await showAuthMenu(accounts);
+
+		expect(result).toEqual({ type: "cancel" });
+		const options = selectMock.mock.calls[0]?.[1] as { showHintsForUnselected?: boolean };
+		expect(options?.showHintsForUnselected).toBe(true);
+	});
+});
diff --git a/test/auth.test.ts b/test/auth.test.ts
index 3f8b1005..dcfc2e8e 100644
--- a/test/auth.test.ts
+++ b/test/auth.test.ts
@@ -4,6 +4,7 @@ import {
 	parseAuthorizationInput,
 	decodeJWT,
 	createAuthorizationFlow,
+	redactOAuthUrlForLog,
 	refreshAccessToken,
 	exchangeAuthorizationCode,
 	CLIENT_ID,
@@ -224,6 +225,26 @@ describe('Auth Module', () => {
 		});
 	});
 
+	describe("redactOAuthUrlForLog", () => {
+		it("redacts sensitive oauth params in URLs", () => {
+			const raw =
+				"https://auth.openai.com/oauth/authorize?state=abc123&code=xyz&code_challenge=foo&response_type=code";
+			const redacted = redactOAuthUrlForLog(raw);
+			expect(redacted).not.toContain("abc123");
+			expect(redacted).not.toContain("xyz");
+			expect(redacted).not.toContain("foo");
+			expect(redacted).toContain("state=%3Credacted%3E");
+			expect(redacted).toContain("code=%3Credacted%3E");
+			expect(redacted).toContain("code_challenge=%3Credacted%3E");
+			expect(redacted).toContain("response_type=code");
+		});
+
+		it("returns original input when url parsing fails", () => {
+			const raw = "not-a-url";
+			expect(redactOAuthUrlForLog(raw)).toBe(raw);
+		});
+	});
+
 	describe('exchangeAuthorizationCode', () => {
 		it('returns success with tokens on valid response', async () => {
 			vi.spyOn(Date, 'now').mockReturnValue(1_000);
diff --git a/test/auto-update-checker.test.ts b/test/auto-update-checker.test.ts
index a7cb3e7b..61572330 100644
--- a/test/auto-update-checker.test.ts
+++ b/test/auto-update-checker.test.ts
@@ -19,6 +19,7 @@ describe("auto-update-checker", () => {
 		vi.resetModules();
 		vi.useFakeTimers();
 		vi.setSystemTime(new Date("2026-01-30T12:00:00Z"));
+		mockPackageJson.version = "4.12.0";
 
 		fs = await import("node:fs");
 		vi.mocked(fs.readFileSync).mockImplementation((path: unknown) => {
@@ -78,16 +79,150 @@ describe("auto-update-checker", () => {
 			expect(result.hasUpdate).toBe(false);
 		});
 
-		it("handles semver with different segment counts", async () => {
+		it("handles versions with v-prefix", async () => {
 			vi.mocked(globalThis.fetch).mockResolvedValue({
 				ok: true,
-				json: async () => ({ version: "4.12.0.1" }),
+				json: async () => ({ version: "v4.13.0" }),
 			} as Response);
 
 			const result = await checkForUpdates(true);
 
 			expect(result.hasUpdate).toBe(true);
 		});
+
+		it("treats stable releases as newer than prerelease", async () => {
+			mockPackageJson.version = "0.1.0-beta.0";
+			vi.mocked(globalThis.fetch).mockResolvedValue({
+				ok: true,
+				json: async () => ({ version: "0.1.0" }),
+			} as Response);
+
+			const result = await checkForUpdates(true);
+
+			expect(result.hasUpdate).toBe(true);
+		});
+
+		it("does not treat prerelease as newer than stable", async () => {
+			mockPackageJson.version = "0.1.0";
+			vi.mocked(globalThis.fetch).mockResolvedValue({
+				ok: true,
+				json: async () => ({ version: "0.1.0-beta.1" }),
+			} as Response);
+
+			const result = await checkForUpdates(true);
+
+			expect(result.hasUpdate).toBe(false);
+		});
+
+		it("treats prerelease with additional segment as newer", async () => {
+			mockPackageJson.version = "1.2.3-beta";
+			vi.mocked(globalThis.fetch).mockResolvedValue({
+				ok: true,
+				json: async () => ({ version: "1.2.3-beta.1" }),
+			} as Response);
+
+			const result = await checkForUpdates(true);
+			expect(result.hasUpdate).toBe(true);
+		});
+
+		it("treats shorter prerelease as older than longer current prerelease", async () => {
+			mockPackageJson.version = "1.2.3-beta.1";
+			vi.mocked(globalThis.fetch).mockResolvedValue({
+				ok: true,
+				json: async () => ({ version: "1.2.3-beta" }),
+			} as Response);
+
+			const result = await checkForUpdates(true);
+			expect(result.hasUpdate).toBe(false);
+		});
+
+		it("compares numeric prerelease segments", async () => {
+			mockPackageJson.version = "1.2.3-beta.2";
+			vi.mocked(globalThis.fetch).mockResolvedValue({
+				ok: true,
+				json: async () => ({ version: "1.2.3-beta.10" }),
+			} as Response);
+
+			const result = await checkForUpdates(true);
+			expect(result.hasUpdate).toBe(true);
+		});
+
+		it("does not treat lower numeric prerelease as newer", async () => {
+			mockPackageJson.version = "1.2.3-beta.10";
+			vi.mocked(globalThis.fetch).mockResolvedValue({
+				ok: true,
+				json: async () => ({ version: "1.2.3-beta.2" }),
+			} as Response);
+
+			const result = await checkForUpdates(true);
+			expect(result.hasUpdate).toBe(false);
+		});
+
+		it("continues prerelease comparison after equal numeric segments", async () => {
+			mockPackageJson.version = "1.2.3-beta.2.omega";
+			vi.mocked(globalThis.fetch).mockResolvedValue({
+				ok: true,
+				json: async () => ({ version: "1.2.3-beta.2.zeta" }),
+			} as Response);
+
+			const result = await checkForUpdates(true);
+			expect(result.hasUpdate).toBe(true);
+		});
+
+		it("handles numeric current vs lexical latest prerelease segment", async () => {
+			mockPackageJson.version = "1.2.3-beta.2";
+			vi.mocked(globalThis.fetch).mockResolvedValue({
+				ok: true,
+				json: async () => ({ version: "1.2.3-beta.alpha" }),
+			} as Response);
+
+			const result = await checkForUpdates(true);
+			expect(result.hasUpdate).toBe(true);
+		});
+
+		it("handles lexical current vs numeric latest prerelease segment", async () => {
+			mockPackageJson.version = "1.2.3-beta.alpha";
+			vi.mocked(globalThis.fetch).mockResolvedValue({
+				ok: true,
+				json: async () => ({ version: "1.2.3-beta.2" }),
+			} as Response);
+
+			const result = await checkForUpdates(true);
+			expect(result.hasUpdate).toBe(false);
+		});
+
+		it("compares lexical prerelease segments by locale order", async () => {
+			mockPackageJson.version = "1.2.3-beta.omega";
+			vi.mocked(globalThis.fetch).mockResolvedValue({
+				ok: true,
+				json: async () => ({ version: "1.2.3-beta.zeta" }),
+			} as Response);
+
+			const result = await checkForUpdates(true);
+			expect(result.hasUpdate).toBe(true);
+		});
+
+		it("does not treat lexically lower prerelease as newer", async () => {
+			mockPackageJson.version = "1.2.3-beta.zeta";
+			vi.mocked(globalThis.fetch).mockResolvedValue({
+				ok: true,
+				json: async () => ({ version: "1.2.3-beta.alpha" }),
+			} as Response);
+
+			const result = await checkForUpdates(true);
+			expect(result.hasUpdate).toBe(false);
+		});
+
+		it("handles invalid semver parts and build metadata safely", async () => {
+			mockPackageJson.version = "v1.x.0+build.1";
+			vi.mocked(globalThis.fetch).mockResolvedValue({
+				ok: true,
+				json: async () => ({ version: "1.0.1+build.2" }),
+			} as Response);
+
+			const result = await checkForUpdates(true);
+			expect(result.hasUpdate).toBe(true);
+		});
 	});
 
 	describe("checkForUpdates", () => {
@@ -115,6 +250,30 @@ describe("auto-update-checker", () => {
 			expect(result.latestVersion).toBe("5.0.0");
 		});
 
+		it("handles cached null latestVersion without update", async () => {
+			const cacheData = {
+				lastCheck: Date.now() - 1000 * 60 * 60,
+				latestVersion: null,
+				currentVersion: "4.12.0",
+			};
+			vi.mocked(fs.existsSync).mockReturnValue(true);
+			vi.mocked(fs.readFileSync).mockImplementation((path: unknown) => {
+				if (String(path).includes("package.json")) {
+					return JSON.stringify(mockPackageJson);
+				}
+				if (String(path).includes("update-check-cache.json")) {
+					return JSON.stringify(cacheData);
+				}
+				throw new Error("File not found");
+			});
+
+			const result = await checkForUpdates();
+
+			expect(globalThis.fetch).not.toHaveBeenCalled();
+			expect(result.hasUpdate).toBe(false);
+			expect(result.latestVersion).toBeNull();
+		});
+
 		it("fetches when cache is expired", async () => {
 			const oldCache = {
 				lastCheck: Date.now() - 1000 * 60 * 60 * 25,
@@ -220,6 +379,31 @@ describe("auto-update-checker", () => {
 			});
 		});
 
+		it.each(["EBUSY", "EPERM"] as const)(
+			"retries cache writes when filesystem is transiently locked (%s)",
+			async (code) => {
+			let attempts = 0;
+			vi.mocked(fs.writeFileSync).mockClear();
+			vi.mocked(fs.writeFileSync).mockImplementation(() => {
+				attempts += 1;
+				if (attempts < 3) {
+					const error = new Error("busy") as NodeJS.ErrnoException;
+					error.code = code;
+					throw error;
+				}
+				return undefined;
+			});
+			vi.mocked(globalThis.fetch).mockResolvedValue({
+				ok: true,
+				json: async () => ({ version: "5.0.0" }),
+			} as Response);
+
+			await checkForUpdates(true);
+
+			expect(fs.writeFileSync).toHaveBeenCalledTimes(3);
+			},
+		);
+
 		it("includes updateCommand in result", async () => {
 			vi.mocked(globalThis.fetch).mockResolvedValue({
 				ok: true,
@@ -276,6 +460,21 @@ describe("auto-update-checker", () => {
 			await expect(checkAndNotify(showToast)).resolves.toBeUndefined();
 			expect(showToast).not.toHaveBeenCalled();
 		});
+
+		it("catches toast callback errors", async () => {
+			vi.mocked(globalThis.fetch).mockResolvedValue({
+				ok: true,
+				json: async () => ({ version: "5.0.0" }),
+			} as Response);
+			const showToast = vi.fn().mockRejectedValue(new Error("toast failed"));
+
+			await expect(checkAndNotify(showToast)).resolves.toBeUndefined();
+			expect(showToast).toHaveBeenCalledTimes(1);
+			expect(showToast).toHaveBeenCalledWith(
+				expect.stringContaining("v5.0.0"),
+				"info",
+			);
+		});
 	});
 
 	describe("clearUpdateCache", () => {
diff --git a/test/browser.test.ts b/test/browser.test.ts
index 40b6dbd1..a2e08377 100644
--- a/test/browser.test.ts
+++ b/test/browser.test.ts
@@ -1,276 +1,274 @@
-import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import { spawn } from 'node:child_process';
-import fs from 'node:fs';
-import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import { getBrowserOpener, openBrowserUrl, copyTextToClipboard } from "../lib/auth/browser.js";
+import { PLATFORM_OPENERS } from "../lib/constants.js";
 
-vi.mock('node:child_process', () => ({
+vi.mock("node:child_process", () => ({
 	spawn: vi.fn(() => ({
 		on: vi.fn(),
+		stdin: { end: vi.fn() },
 	})),
 }));
 
-vi.mock('node:fs', () => ({
+vi.mock("node:fs", () => ({
 	default: {
 		existsSync: vi.fn(),
+		statSync: vi.fn(),
 	},
 	existsSync: vi.fn(),
+	statSync: vi.fn(),
 }));
 
-import { getBrowserOpener, openBrowserUrl } from '../lib/auth/browser.js';
-import { PLATFORM_OPENERS } from '../lib/constants.js';
-
 const mockedSpawn = vi.mocked(spawn);
 const mockedExistsSync = vi.mocked(fs.existsSync);
-
-describe('Browser Module', () => {
+const mockedStatSync = vi.mocked(fs.statSync);
+
+function expectLastSpawnStdinEndWith(text: string): void {
+	const spawnResult = mockedSpawn.mock.results.at(-1)?.value as
+		| { stdin?: { end?: (value?: string) => void } }
+		| undefined;
+	expect(spawnResult?.stdin?.end).toBeTypeOf("function");
+	const stdinEnd = spawnResult?.stdin?.end as ReturnType<typeof vi.fn>;
+	expect(stdinEnd).toHaveBeenCalledWith(text);
+}
+
+describe("auth browser utilities", () => {
 	const originalPlatform = process.platform;
 	const originalPath = process.env.PATH;
-	const originalPathext = process.env.PATHEXT;
+	const originalPathExt = process.env.PATHEXT;
 
 	beforeEach(() => {
 		vi.clearAllMocks();
+		mockedExistsSync.mockReturnValue(false);
+		mockedStatSync.mockReturnValue({
+			isFile: () => true,
+			mode: 0o755,
+		} as unknown as ReturnType<typeof fs.statSync>);
 	});
 
 	afterEach(() => {
-		Object.defineProperty(process, 'platform', { value: originalPlatform });
-		if (originalPath === undefined) {
-			delete process.env.PATH;
-		} else {
-			process.env.PATH = originalPath;
-		}
-		if (originalPathext === undefined) {
-			delete process.env.PATHEXT;
-		} else {
-			process.env.PATHEXT = originalPathext;
-		}
+		Object.defineProperty(process, "platform", { value: originalPlatform });
+		if (originalPath === undefined) delete process.env.PATH;
+		else process.env.PATH = originalPath;
+		if (originalPathExt === undefined) delete process.env.PATHEXT;
+		else process.env.PATHEXT = originalPathExt;
 	});
 
-	describe('getBrowserOpener', () => {
-		it('should return correct opener for darwin', () => {
-			Object.defineProperty(process, 'platform', { value: 'darwin' });
-			expect(getBrowserOpener()).toBe(PLATFORM_OPENERS.darwin);
-		});
-
-		it('should return correct opener for win32', () => {
-			Object.defineProperty(process, 'platform', { value: 'win32' });
-			expect(getBrowserOpener()).toBe(PLATFORM_OPENERS.win32);
-		});
+	it("returns platform opener command", () => {
+		Object.defineProperty(process, "platform", { value: "darwin" });
+		expect(getBrowserOpener()).toBe(PLATFORM_OPENERS.darwin);
+		Object.defineProperty(process, "platform", { value: "win32" });
+		expect(getBrowserOpener()).toBe(PLATFORM_OPENERS.win32);
+		Object.defineProperty(process, "platform", { value: "linux" });
+		expect(getBrowserOpener()).toBe(PLATFORM_OPENERS.linux);
+	});
 
-		it('should return linux opener for linux platform', () => {
-			Object.defineProperty(process, 'platform', { value: 'linux' });
-			expect(getBrowserOpener()).toBe(PLATFORM_OPENERS.linux);
-		});
+	describe("openBrowserUrl", () => {
+		it("returns false on win32 when powershell.exe is unavailable", () => {
+			Object.defineProperty(process, "platform", { value: "win32" });
+			process.env.PATH = "C:\\missing";
+			process.env.PATHEXT = ".EXE;.CMD";
+			mockedExistsSync.mockReturnValue(false);
 
-		it('should return linux opener for unknown platforms like freebsd', () => {
-			Object.defineProperty(process, 'platform', { value: 'freebsd' });
-			expect(getBrowserOpener()).toBe(PLATFORM_OPENERS.linux);
+			expect(openBrowserUrl("https://example.com")).toBe(false);
+			expect(mockedSpawn).not.toHaveBeenCalled();
 		});
 
-		it('should return linux opener for aix platform', () => {
-			Object.defineProperty(process, 'platform', { value: 'aix' });
-			expect(getBrowserOpener()).toBe(PLATFORM_OPENERS.linux);
+		it("uses powershell on win32 when available", () => {
+			Object.defineProperty(process, "platform", { value: "win32" });
+			process.env.PATH = "C:\\Windows\\System32";
+			process.env.PATHEXT = ".EXE;.CMD";
+			mockedExistsSync.mockImplementation(
+				(candidate) =>
+					typeof candidate === "string" &&
+					candidate.toLowerCase().includes("powershell.exe"),
+			);
+
+			expect(openBrowserUrl("https://example.com/$var")).toBe(true);
+			expect(mockedSpawn).toHaveBeenCalledWith(
+				"powershell.exe",
+				expect.arrayContaining([expect.stringContaining("Start-Process")]),
+				{ stdio: "ignore" },
+			);
+			const args = mockedSpawn.mock.calls.at(-1)?.[1] as string[] | undefined;
+			expect(args).toEqual(expect.arrayContaining(["-NoLogo", "-NoProfile", "-Command"]));
+			expect(args?.join(" ")).toContain('Start-Process "https://example.com/`$var"');
 		});
-	});
 
-	describe('openBrowserUrl', () => {
-		describe('Windows platform', () => {
-			beforeEach(() => {
-				Object.defineProperty(process, 'platform', { value: 'win32' });
-			});
+		it("returns false when opener binary is non-executable on linux", () => {
+			Object.defineProperty(process, "platform", { value: "linux" });
+			process.env.PATH = "/usr/bin";
+			mockedExistsSync.mockReturnValue(true);
+			mockedStatSync.mockReturnValue({
+				isFile: () => true,
+				mode: 0o644,
+			} as unknown as ReturnType<typeof fs.statSync>);
 
-			it('should use PowerShell on Windows', () => {
-				openBrowserUrl('https://example.com');
-				expect(mockedSpawn).toHaveBeenCalledWith(
-					'powershell.exe',
-					expect.arrayContaining(['-NoLogo', '-NoProfile', '-Command']),
-					{ stdio: 'ignore' }
-				);
-			});
-
-			it('should escape PowerShell special characters in URL', () => {
-				openBrowserUrl('https://example.com?foo=bar&baz=qux');
-				expect(mockedSpawn).toHaveBeenCalledWith(
-					'powershell.exe',
-					expect.arrayContaining([
-						expect.stringContaining('Start-Process')
-					]),
-					expect.anything()
-				);
-			});
-
-			it('should escape backticks in URL for PowerShell', () => {
-				openBrowserUrl('https://example.com/path`with`backticks');
-				const call = mockedSpawn.mock.calls[0];
-				const commandArg = call[1].find((arg: string) => arg.includes('Start-Process'));
-				expect(commandArg).toContain('``');
-			});
-
-			it('should escape dollar signs in URL for PowerShell', () => {
-				openBrowserUrl('https://example.com/$variable');
-				const call = mockedSpawn.mock.calls[0];
-				const commandArg = call[1].find((arg: string) => arg.includes('Start-Process'));
-				expect(commandArg).toContain('`$');
-			});
-
-			it('should return true on Windows', () => {
-				const result = openBrowserUrl('https://example.com');
-				expect(result).toBe(true);
-			});
+			expect(openBrowserUrl("https://example.com")).toBe(false);
 		});
 
-		describe('Non-Windows platforms', () => {
-			beforeEach(() => {
-				Object.defineProperty(process, 'platform', { value: 'linux' });
-			});
-
-			it('should return false when PATH is empty', () => {
-				process.env.PATH = '';
-				const result = openBrowserUrl('https://example.com');
-				expect(result).toBe(false);
-			});
-
-			it('should return false when opener command does not exist in PATH', () => {
-				process.env.PATH = '/usr/bin:/bin';
-				mockedExistsSync.mockReturnValue(false);
-				const result = openBrowserUrl('https://example.com');
-				expect(result).toBe(false);
+		it("returns false on darwin when open is unavailable", () => {
+			Object.defineProperty(process, "platform", { value: "darwin" });
+			process.env.PATH = "/usr/bin";
+			mockedStatSync.mockImplementation(() => {
+				throw new Error("missing");
 			});
 
-			it('should spawn opener when command exists', () => {
-				process.env.PATH = '/usr/bin';
-				mockedExistsSync.mockImplementation((p) => {
-					return typeof p === 'string' && p.includes('xdg-open');
-				});
-				openBrowserUrl('https://example.com');
-				expect(mockedSpawn).toHaveBeenCalledWith(
-					expect.any(String),
-					['https://example.com'],
-					{ stdio: 'ignore', shell: false }
-				);
-			});
-
-			it('should return true when opener exists and spawns successfully', () => {
-				process.env.PATH = '/usr/bin';
-				mockedExistsSync.mockReturnValue(true);
-				const result = openBrowserUrl('https://example.com');
-				expect(result).toBe(true);
-			});
+			expect(openBrowserUrl("https://example.com")).toBe(false);
+			expect(mockedSpawn).not.toHaveBeenCalled();
 		});
 
-		describe('macOS platform', () => {
-			beforeEach(() => {
-				Object.defineProperty(process, 'platform', { value: 'darwin' });
-				process.env.PATH = '/usr/bin';
-			});
+		it("uses open on darwin when available", () => {
+			Object.defineProperty(process, "platform", { value: "darwin" });
+			process.env.PATH = "/usr/bin";
+			mockedExistsSync.mockImplementation(
+				(candidate) => typeof candidate === "string" && candidate.endsWith("open"),
+			);
+			mockedStatSync.mockReturnValue({
+				isFile: () => true,
+				mode: 0o755,
+			} as unknown as ReturnType<typeof fs.statSync>);
+
+			expect(openBrowserUrl("https://example.com")).toBe(true);
+			expect(mockedSpawn).toHaveBeenCalledWith(
+				"open",
+				["https://example.com"],
+				{ stdio: "ignore", shell: false },
+			);
+		});
+	});
 
-			it('should use "open" command on macOS', () => {
-				mockedExistsSync.mockReturnValue(true);
-				openBrowserUrl('https://example.com');
-				expect(mockedSpawn).toHaveBeenCalledWith(
-					'open',
-					['https://example.com'],
-					expect.anything()
-				);
-			});
+	describe("copyTextToClipboard", () => {
+		it("returns false for empty text", () => {
+			expect(copyTextToClipboard("")).toBe(false);
 		});
 
-		describe('Error handling', () => {
-			it('should handle spawn errors silently and return true on Windows', () => {
-				Object.defineProperty(process, 'platform', { value: 'win32' });
-				mockedSpawn.mockImplementation(() => {
-					const mockChild = {
-						on: vi.fn((event, callback) => {
-							if (event === 'error') {
-								callback(new Error('spawn failed'));
-							}
-						}),
-					};
-					return mockChild as unknown as ReturnType<typeof spawn>;
-				});
-				const result = openBrowserUrl('https://example.com');
-				expect(result).toBe(true);
-			});
+		it("returns false on win32 when powershell.exe is unavailable", () => {
+			Object.defineProperty(process, "platform", { value: "win32" });
+			process.env.PATH = "C:\\missing";
+			process.env.PATHEXT = ".EXE;.CMD";
+			mockedExistsSync.mockReturnValue(false);
 
-			it('should catch and swallow errors in outer try-catch', () => {
-				Object.defineProperty(process, 'platform', { value: 'linux' });
-				process.env.PATH = '/usr/bin';
-				mockedExistsSync.mockImplementation(() => {
-					throw new Error('filesystem error');
-				});
-				const result = openBrowserUrl('https://example.com');
-				expect(result).toBe(false);
-			});
+			expect(copyTextToClipboard("hello")).toBe(false);
+			expect(mockedSpawn).not.toHaveBeenCalled();
 		});
 
-		describe('Windows commandExists for "start" builtin', () => {
-			it('should return true on Windows even without checking PATH for start', () => {
-				Object.defineProperty(process, 'platform', { value: 'win32' });
-				const result = openBrowserUrl('https://example.com');
-				expect(result).toBe(true);
-			});
+		it("uses powershell Set-Clipboard on win32 when available", () => {
+			Object.defineProperty(process, "platform", { value: "win32" });
+			process.env.PATH = "C:\\Windows\\System32";
+			process.env.PATHEXT = ".EXE;.CMD";
+			mockedExistsSync.mockImplementation(
+				(candidate) =>
+					typeof candidate === "string" &&
+					candidate.toLowerCase().includes("powershell.exe"),
+			);
+
+			expect(copyTextToClipboard("hello$world")).toBe(true);
+			expect(mockedSpawn).toHaveBeenCalledWith(
+				"powershell.exe",
+				expect.arrayContaining([expect.stringContaining("Set-Clipboard")]),
+				{ stdio: "ignore" },
+			);
+			const args = mockedSpawn.mock.calls.at(-1)?.[1] as string[] | undefined;
+			expect(args).toEqual(expect.arrayContaining(["-NoLogo", "-NoProfile", "-Command"]));
+			expect(args?.join(" ")).toContain('Set-Clipboard -Value "hello`$world"');
 		});
 
-		describe('PATHEXT handling on Windows', () => {
-			beforeEach(() => {
-				Object.defineProperty(process, 'platform', { value: 'win32' });
-			});
+		it("uses pbcopy on darwin", () => {
+			Object.defineProperty(process, "platform", { value: "darwin" });
+			process.env.PATH = "/usr/bin";
+			mockedExistsSync.mockImplementation(
+				(candidate) => typeof candidate === "string" && candidate.endsWith("pbcopy"),
+			);
+			mockedStatSync.mockReturnValue({
+				isFile: () => true,
+				mode: 0o755,
+			} as unknown as ReturnType<typeof fs.statSync>);
+
+			expect(copyTextToClipboard("hello")).toBe(true);
+			expect(mockedSpawn).toHaveBeenCalledWith(
+				"pbcopy",
+				[],
+				{ stdio: ["pipe", "ignore", "ignore"], shell: false },
+			);
+			expectLastSpawnStdinEndWith("hello");
+		});
 
-			it('should use PowerShell regardless of PATHEXT', () => {
-				process.env.PATHEXT = '.EXE;.CMD;.BAT';
-				process.env.PATH = 'C:\\Windows\\System32';
-				openBrowserUrl('https://example.com');
-				expect(mockedSpawn).toHaveBeenCalledWith(
-					'powershell.exe',
-					expect.anything(),
-					expect.anything()
-				);
+		it("uses wl-copy when available on linux", () => {
+			Object.defineProperty(process, "platform", { value: "linux" });
+			process.env.PATH = "/usr/bin:/bin";
+			mockedExistsSync.mockImplementation((candidate) => {
+				if (typeof candidate !== "string") return false;
+				return candidate.endsWith("wl-copy");
 			});
+			mockedStatSync.mockReturnValue({
+				isFile: () => true,
+				mode: 0o755,
+			} as unknown as ReturnType<typeof fs.statSync>);
+
+			expect(copyTextToClipboard("hello")).toBe(true);
+			expect(mockedSpawn).toHaveBeenCalledWith(
+				"wl-copy",
+				[],
+				{ stdio: ["pipe", "ignore", "ignore"], shell: false },
+			);
+			expectLastSpawnStdinEndWith("hello");
 		});
-	});
 
-	describe('commandExists internal behavior', () => {
-		beforeEach(() => {
-			vi.clearAllMocks();
-		});
+		it("falls back across linux clipboard commands", () => {
+			Object.defineProperty(process, "platform", { value: "linux" });
+			process.env.PATH = "/usr/bin:/bin";
+			mockedStatSync.mockImplementation((candidate) => {
+				if (typeof candidate !== "string") throw new Error("bad path");
+				if (candidate.endsWith("wl-copy")) throw new Error("missing");
+				if (candidate.endsWith("xclip")) {
+					return {
+						isFile: () => true,
+						mode: 0o755,
+					} as unknown as ReturnType<typeof fs.statSync>;
+				}
+				throw new Error("missing");
+			});
 
-		afterEach(() => {
-			Object.defineProperty(process, 'platform', { value: originalPlatform });
-			if (originalPath === undefined) {
-				delete process.env.PATH;
-			} else {
-				process.env.PATH = originalPath;
-			}
-			if (originalPathext === undefined) {
-				delete process.env.PATHEXT;
-			} else {
-				process.env.PATHEXT = originalPathext;
-			}
+			expect(copyTextToClipboard("hello")).toBe(true);
+			expect(mockedSpawn).toHaveBeenCalledWith(
+				"xclip",
+				["-selection", "clipboard"],
+				{ stdio: ["pipe", "ignore", "ignore"], shell: false },
+			);
+			expectLastSpawnStdinEndWith("hello");
 		});
 
-		const originalPlatform = process.platform;
-		const originalPath = process.env.PATH;
-		const originalPathext = process.env.PATHEXT;
-
-		it('should find command with .EXE extension on Windows when non-PowerShell opener used', () => {
-			Object.defineProperty(process, 'platform', { value: 'linux' });
-			process.env.PATH = '/usr/bin';
-			mockedExistsSync.mockImplementation((p) => {
-				if (typeof p === 'string' && p.endsWith('xdg-open')) return true;
-				return false;
+		it("falls back to xsel when only xsel is available on linux", () => {
+			Object.defineProperty(process, "platform", { value: "linux" });
+			process.env.PATH = "/usr/bin:/bin";
+			mockedStatSync.mockImplementation((candidate) => {
+				if (typeof candidate !== "string") throw new Error("bad path");
+				if (candidate.endsWith("xsel")) {
+					return {
+						isFile: () => true,
+						mode: 0o755,
+					} as unknown as ReturnType<typeof fs.statSync>;
+				}
+				throw new Error("missing");
 			});
 
-			const result = openBrowserUrl('https://example.com');
-			expect(result).toBe(true);
-			expect(mockedExistsSync).toHaveBeenCalled();
+			expect(copyTextToClipboard("hello")).toBe(true);
+			expect(mockedSpawn).toHaveBeenCalledWith(
+				"xsel",
+				["--clipboard", "--input"],
+				{ stdio: ["pipe", "ignore", "ignore"], shell: false },
+			);
+			expectLastSpawnStdinEndWith("hello");
 		});
 
-		it('should try multiple PATHEXT extensions when searching for command', () => {
-			Object.defineProperty(process, 'platform', { value: 'linux' });
-			process.env.PATH = '/opt/bin';
+		it("returns false on linux when PATH is unset or no command exists", () => {
+			Object.defineProperty(process, "platform", { value: "linux" });
+			delete process.env.PATH;
 			mockedExistsSync.mockReturnValue(false);
 
-			openBrowserUrl('https://example.com');
-			expect(mockedExistsSync).toHaveBeenCalled();
+			expect(copyTextToClipboard("hello")).toBe(false);
 		});
 	});
 });
diff --git a/test/capability-policy.test.ts b/test/capability-policy.test.ts
new file mode 100644
index 00000000..77a63a76
--- /dev/null
+++ b/test/capability-policy.test.ts
@@ -0,0 +1,47 @@
+import { describe, expect, it } from "vitest";
+import { CapabilityPolicyStore } from "../lib/capability-policy.js";
+
+describe("capability policy store", () => {
+	it("rewards repeated successes", () => {
+		const store = new CapabilityPolicyStore();
+		store.recordSuccess("id:acc_1", "gpt-5-codex", 1_000);
+		store.recordSuccess("id:acc_1", "gpt-5-codex", 2_000);
+
+		expect(store.getBoost("id:acc_1", "gpt-5-codex", 2_500)).toBeGreaterThan(0);
+	});
+
+	it("penalizes failures and unsupported errors", () => {
+		const store = new CapabilityPolicyStore();
+		store.recordFailure("id:acc_1", "gpt-5.3-codex", 1_000);
+		store.recordUnsupported("id:acc_1", "gpt-5.3-codex", 1_500);
+
+		const boost = store.getBoost("id:acc_1", "gpt-5.3-codex", 1_600);
+		expect(boost).toBeLessThan(0);
+	});
+
+	it("recovers passively over time", () => {
+		const store = new CapabilityPolicyStore();
+		store.recordFailure("id:acc_2", "gpt-5-codex", 1_000);
+		const early = store.getBoost("id:acc_2", "gpt-5-codex", 2_000);
+		const later = store.getBoost("id:acc_2", "gpt-5-codex", 122_000);
+
+		expect(later).toBeGreaterThanOrEqual(early);
+	});
+
+	it("clears account-specific entries", () => {
+		const store = new CapabilityPolicyStore();
+		store.recordSuccess("id:acc_a", "gpt-5-codex", 1_000);
+		store.recordFailure("id:acc_b", "gpt-5-codex", 1_000);
+
+		expect(store.clearAccount("id:acc_a")).toBeGreaterThan(0);
+		expect(store.getSnapshot("id:acc_a", "gpt-5-codex")).toBeNull();
+		expect(store.getSnapshot("id:acc_b", "gpt-5-codex")).not.toBeNull();
+	});
+
+	it("uses canonical model normalization across aliases", () => {
+		const store = new CapabilityPolicyStore();
+		store.recordSuccess("id:acc_alias", "gpt-5.3-codex", 1_000);
+		const boostFromCanonical = store.getBoost("id:acc_alias", "gpt-5-codex", 1_500);
+		expect(boostFromCanonical).toBeGreaterThan(0);
+	});
+});
diff --git a/test/cli-auth-menu.test.ts b/test/cli-auth-menu.test.ts
new file mode 100644
index 00000000..518417ce
--- /dev/null
+++ b/test/cli-auth-menu.test.ts
@@ -0,0 +1,192 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const showAuthMenu = vi.fn();
+const showAccountDetails = vi.fn();
+const isTTY = vi.fn();
+
+vi.mock("../lib/ui/auth-menu.js", () => ({
+	showAuthMenu,
+	showAccountDetails,
+	isTTY,
+}));
+
+describe("CLI auth menu shortcuts", () => {
+	beforeEach(() => {
+		vi.resetModules();
+		showAuthMenu.mockReset();
+		showAccountDetails.mockReset();
+		isTTY.mockReset();
+		isTTY.mockReturnValue(true);
+		process.env.FORCE_INTERACTIVE_MODE = "1";
+	});
+
+	afterEach(() => {
+		delete process.env.FORCE_INTERACTIVE_MODE;
+		vi.restoreAllMocks();
+	});
+
+	it("returns switch action when auth menu requests set current", async () => {
+		showAuthMenu.mockResolvedValueOnce({
+			type: "set-current-account",
+			account: { index: 1 },
+		});
+
+		const { promptLoginMode } = await import("../lib/cli.js");
+		const result = await promptLoginMode([{ index: 0 }, { index: 1 }]);
+
+		expect(result).toEqual({ mode: "manage", switchAccountIndex: 1 });
+	});
+
+	it("uses source index for set current when sorted view provides source mapping", async () => {
+		showAuthMenu.mockResolvedValueOnce({
+			type: "set-current-account",
+			account: { index: 0, sourceIndex: 4 },
+		});
+
+		const { promptLoginMode } = await import("../lib/cli.js");
+		const result = await promptLoginMode([{ index: 0, sourceIndex: 4 }]);
+
+		expect(result).toEqual({ mode: "manage", switchAccountIndex: 4 });
+	});
+
+	it("returns switch action when account details picks set current", async () => {
+		showAuthMenu.mockResolvedValueOnce({
+			type: "select-account",
+			account: { index: 2 },
+		});
+		showAccountDetails.mockResolvedValueOnce("set-current");
+
+		const { promptLoginMode } = await import("../lib/cli.js");
+		const result = await promptLoginMode([{ index: 0 }, { index: 1 }, { index: 2 }]);
+
+		expect(result).toEqual({ mode: "manage", switchAccountIndex: 2 });
+	});
+
+	it("returns refresh action when auth menu requests refresh", async () => {
+		showAuthMenu.mockResolvedValueOnce({
+			type: "refresh-account",
+			account: { index: 0 },
+		});
+
+		const { promptLoginMode } = await import("../lib/cli.js");
+		const result = await promptLoginMode([{ index: 0 }]);
+
+		expect(result).toEqual({ mode: "manage", refreshAccountIndex: 0 });
+	});
+
+	it("returns toggle action when auth menu requests toggle", async () => {
+		showAuthMenu.mockResolvedValueOnce({
+			type: "toggle-account",
+			account: { index: 1 },
+		});
+
+		const { promptLoginMode } = await import("../lib/cli.js");
+		const result = await promptLoginMode([{ index: 0 }, { index: 1 }]);
+
+		expect(result).toEqual({ mode: "manage", toggleAccountIndex: 1 });
+	});
+
+	it("uses source index for account-details actions when sorted view provides source mapping", async () => {
+		showAuthMenu.mockResolvedValueOnce({
+			type: "select-account",
+			account: { index: 0, sourceIndex: 3 },
+		});
+		showAccountDetails.mockResolvedValueOnce("refresh");
+
+		const { promptLoginMode } = await import("../lib/cli.js");
+		const result = await promptLoginMode([{ index: 0, sourceIndex: 3 }]);
+
+		expect(result).toEqual({ mode: "manage", refreshAccountIndex: 3 });
+	});
+
+	it("returns forecast mode when auth menu requests forecast", async () => {
+		showAuthMenu.mockResolvedValueOnce({
+			type: "forecast",
+		});
+
+		const { promptLoginMode } = await import("../lib/cli.js");
+		const result = await promptLoginMode([{ index: 0 }]);
+
+		expect(result).toEqual({ mode: "forecast" });
+	});
+
+	it("returns fix mode when auth menu requests fix", async () => {
+		showAuthMenu.mockResolvedValueOnce({
+			type: "fix",
+		});
+
+		const { promptLoginMode } = await import("../lib/cli.js");
+		const result = await promptLoginMode([{ index: 0 }]);
+
+		expect(result).toEqual({ mode: "fix" });
+	});
+
+	it("returns settings mode when auth menu requests settings", async () => {
+		showAuthMenu.mockResolvedValueOnce({
+			type: "settings",
+		});
+
+		const { promptLoginMode } = await import("../lib/cli.js");
+		const result = await promptLoginMode([{ index: 0 }]);
+
+		expect(result).toEqual({ mode: "settings" });
+	});
+
+	it("returns delete action when auth menu requests delete", async () => {
+		showAuthMenu.mockResolvedValueOnce({
+			type: "delete-account",
+			account: { index: 0 },
+		});
+
+		const { promptLoginMode } = await import("../lib/cli.js");
+		const result = await promptLoginMode([{ index: 0 }]);
+
+		expect(result).toEqual({ mode: "manage", deleteAccountIndex: 0 });
+	});
+
+	it("returns deep-check mode when auth menu requests deep-check", async () => {
+		showAuthMenu.mockResolvedValueOnce({ type: "deep-check" });
+
+		const { promptLoginMode } = await import("../lib/cli.js");
+		const result = await promptLoginMode([{ index: 0 }]);
+
+		expect(result).toEqual({ mode: "deep-check" });
+	});
+
+	it("returns verify-flagged mode when auth menu requests verify-flagged", async () => {
+		showAuthMenu.mockResolvedValueOnce({ type: "verify-flagged" });
+
+		const { promptLoginMode } = await import("../lib/cli.js");
+		const result = await promptLoginMode([{ index: 0 }]);
+
+		expect(result).toEqual({ mode: "verify-flagged" });
+	});
+
+	it("returns cancel mode when auth menu requests cancel", async () => {
+		showAuthMenu.mockResolvedValueOnce({ type: "cancel" });
+
+		const { promptLoginMode } = await import("../lib/cli.js");
+		const result = await promptLoginMode([{ index: 0 }]);
+
+		expect(result).toEqual({ mode: "cancel" });
+	});
+
+	it("shows feedback when account action cannot resolve a valid source index", async () => {
+		const consoleSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+		showAuthMenu
+			.mockResolvedValueOnce({
+				type: "set-current-account",
+				account: { index: Number.NaN, email: "broken@example.com" },
+			})
+			.mockResolvedValueOnce({ type: "cancel" });
+
+		const { promptLoginMode } = await import("../lib/cli.js");
+		const result = await promptLoginMode([{ index: 0 }]);
+
+		expect(result).toEqual({ mode: "cancel" });
+		expect(consoleSpy).toHaveBeenCalledWith(
+			expect.stringContaining("Unable to resolve saved account for action"),
+		);
+		consoleSpy.mockRestore();
+	});
+});
diff --git a/test/cli.test.ts b/test/cli.test.ts
index 5e670ba0..95b328b6 100644
--- a/test/cli.test.ts
+++ b/test/cli.test.ts
@@ -124,6 +124,33 @@ describe("CLI Module", () => {
       expect(result).toEqual({ mode: "add" });
     });
 
+    it("returns 'forecast' for 'p' input", async () => {
+      mockRl.question.mockResolvedValueOnce("p");
+
+      const { promptLoginMode } = await import("../lib/cli.js");
+      const result = await promptLoginMode([{ index: 0 }]);
+
+      expect(result).toEqual({ mode: "forecast" });
+    });
+
+    it("returns 'fix' for 'x' input", async () => {
+      mockRl.question.mockResolvedValueOnce("x");
+
+      const { promptLoginMode } = await import("../lib/cli.js");
+      const result = await promptLoginMode([{ index: 0 }]);
+
+      expect(result).toEqual({ mode: "fix" });
+    });
+
+    it("returns 'settings' for 's' input", async () => {
+      mockRl.question.mockResolvedValueOnce("s");
+
+      const { promptLoginMode } = await import("../lib/cli.js");
+      const result = await promptLoginMode([{ index: 0 }]);
+
+      expect(result).toEqual({ mode: "settings" });
+    });
+
     it("returns 'fresh' for 'f' input", async () => {
       mockRl.question.mockResolvedValueOnce("f");
       
@@ -142,6 +169,31 @@ describe("CLI Module", () => {
       expect(result).toEqual({ mode: "fresh", deleteAll: true });
     });
 
+    it("returns 'verify-flagged' for 'g' input", async () => {
+      mockRl.question.mockResolvedValueOnce("g");
+
+      const { promptLoginMode } = await import("../lib/cli.js");
+      const result = await promptLoginMode([{ index: 0 }]);
+
+      expect(result).toEqual({ mode: "verify-flagged" });
+    });
+
+    it("accepts uppercase quick shortcuts for advanced actions", async () => {
+      const { promptLoginMode } = await import("../lib/cli.js");
+
+      mockRl.question.mockResolvedValueOnce("P");
+      await expect(promptLoginMode([{ index: 0 }])).resolves.toEqual({ mode: "forecast" });
+
+      mockRl.question.mockResolvedValueOnce("X");
+      await expect(promptLoginMode([{ index: 0 }])).resolves.toEqual({ mode: "fix" });
+
+      mockRl.question.mockResolvedValueOnce("S");
+      await expect(promptLoginMode([{ index: 0 }])).resolves.toEqual({ mode: "settings" });
+
+      mockRl.question.mockResolvedValueOnce("G");
+      await expect(promptLoginMode([{ index: 0 }])).resolves.toEqual({ mode: "verify-flagged" });
+    });
+
     it("is case insensitive", async () => {
       mockRl.question.mockResolvedValueOnce("A");
       
@@ -154,7 +206,7 @@ describe("CLI Module", () => {
     it("re-prompts on invalid input then accepts valid", async () => {
       mockRl.question
         .mockResolvedValueOnce("invalid")
-        .mockResolvedValueOnce("x")
+        .mockResolvedValueOnce("zzz")
         .mockResolvedValueOnce("a");
       
       const { promptLoginMode } = await import("../lib/cli.js");
diff --git a/test/codex-cli-state.test.ts b/test/codex-cli-state.test.ts
index d3314c9e..ed18621a 100644
--- a/test/codex-cli-state.test.ts
+++ b/test/codex-cli-state.test.ts
@@ -1,7 +1,8 @@
 import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { promises as fsPromises } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import {
 	__resetCodexCliWarningCacheForTests,
 	clearCodexCliStateCache,
@@ -18,18 +19,23 @@ import { setCodexCliActiveSelection } from "../lib/codex-cli/writer.js";
 describe("codex-cli state", () => {
 	let tempDir: string;
 	let accountsPath: string;
+	let authPath: string;
 	let previousPath: string | undefined;
+	let previousAuthPath: string | undefined;
 	let previousSync: string | undefined;
 	let previousLegacySync: string | undefined;
 
 	beforeEach(async () => {
 		previousPath = process.env.CODEX_CLI_ACCOUNTS_PATH;
+		previousAuthPath = process.env.CODEX_CLI_AUTH_PATH;
 		previousSync = process.env.CODEX_MULTI_AUTH_SYNC_CODEX_CLI;
 		previousLegacySync = process.env.CODEX_AUTH_SYNC_CODEX_CLI;
 
 		tempDir = await mkdtemp(join(tmpdir(), "codex-multi-auth-state-"));
 		accountsPath = join(tempDir, "accounts.json");
+		authPath = join(tempDir, "auth.json");
 		process.env.CODEX_CLI_ACCOUNTS_PATH = accountsPath;
+		process.env.CODEX_CLI_AUTH_PATH = authPath;
 		process.env.CODEX_MULTI_AUTH_SYNC_CODEX_CLI = "1";
 		delete process.env.CODEX_AUTH_SYNC_CODEX_CLI;
 		clearCodexCliStateCache();
@@ -42,6 +48,8 @@ describe("codex-cli state", () => {
 		__resetCodexCliWarningCacheForTests();
 		if (previousPath === undefined) delete process.env.CODEX_CLI_ACCOUNTS_PATH;
 		else process.env.CODEX_CLI_ACCOUNTS_PATH = previousPath;
+		if (previousAuthPath === undefined) delete process.env.CODEX_CLI_AUTH_PATH;
+		else process.env.CODEX_CLI_AUTH_PATH = previousAuthPath;
 		if (previousSync === undefined) delete process.env.CODEX_MULTI_AUTH_SYNC_CODEX_CLI;
 		else process.env.CODEX_MULTI_AUTH_SYNC_CODEX_CLI = previousSync;
 		if (previousLegacySync === undefined) delete process.env.CODEX_AUTH_SYNC_CODEX_CLI;
@@ -55,6 +63,7 @@ describe("codex-cli state", () => {
 			accountsPath,
 			JSON.stringify(
 				{
+					codexMultiAuthSyncVersion: 123456,
 					activeAccountId: "acc_b",
 					accounts: [
 						{
@@ -89,12 +98,180 @@ describe("codex-cli state", () => {
 		const state = await loadCodexCliState({ forceRefresh: true });
 		expect(state?.activeAccountId).toBe("acc_b");
 		expect(state?.accounts.length).toBe(2);
+		expect(state?.syncVersion).toBe(123456);
+		expect(typeof state?.sourceUpdatedAtMs).toBe("number");
 
 		const lookup = await lookupCodexCliTokensByEmail("B@EXAMPLE.com");
 		expect(lookup?.refreshToken).toBe("refresh-b");
 		expect(lookup?.accountId).toBe("acc_b");
 	});
 
+	it("coalesces concurrent cache-miss loads into one file read", async () => {
+		await writeFile(
+			accountsPath,
+			JSON.stringify(
+				{
+					activeAccountId: "acc_a",
+					accounts: [
+						{
+							accountId: "acc_a",
+							email: "a@example.com",
+							auth: {
+								tokens: {
+									access_token: "a.b.c",
+									refresh_token: "refresh-a",
+								},
+							},
+						},
+					],
+				},
+				null,
+				2,
+			),
+			"utf-8",
+		);
+		clearCodexCliStateCache();
+		const readSpy = vi.spyOn(fsPromises, "readFile");
+
+		try {
+			const results = await Promise.all(
+				Array.from({ length: 8 }, () => loadCodexCliState()),
+			);
+			expect(results.every((state) => state?.activeAccountId === "acc_a")).toBe(true);
+			const accountReads = readSpy.mock.calls.filter(
+				(args) => String(args[0]) === accountsPath,
+			);
+			expect(accountReads.length).toBe(1);
+		} finally {
+			readSpy.mockRestore();
+		}
+	});
+
+	it("retries transient read/stat lock errors before failing", async () => {
+		await writeFile(
+			accountsPath,
+			JSON.stringify(
+				{
+					activeAccountId: "acc_a",
+					accounts: [
+						{
+							accountId: "acc_a",
+							email: "a@example.com",
+							auth: {
+								tokens: {
+									access_token: "a.b.c",
+									refresh_token: "refresh-a",
+								},
+							},
+						},
+					],
+				},
+				null,
+				2,
+			),
+			"utf-8",
+		);
+		clearCodexCliStateCache();
+
+		const realReadFile = fsPromises.readFile.bind(fsPromises);
+		const realStat = fsPromises.stat.bind(fsPromises);
+		let accountsReadAttempts = 0;
+		let accountsStatAttempts = 0;
+		const readSpy = vi.spyOn(fsPromises, "readFile");
+		const statSpy = vi.spyOn(fsPromises, "stat");
+		readSpy.mockImplementation(async (...args) => {
+			if (String(args[0]) === accountsPath) {
+				accountsReadAttempts += 1;
+				if (accountsReadAttempts === 1) {
+					const error = new Error("locked") as NodeJS.ErrnoException;
+					error.code = "EPERM";
+					throw error;
+				}
+			}
+			return realReadFile(...args);
+		});
+		statSpy.mockImplementation(async (...args) => {
+			if (String(args[0]) === accountsPath) {
+				accountsStatAttempts += 1;
+				if (accountsStatAttempts === 1) {
+					const error = new Error("busy") as NodeJS.ErrnoException;
+					error.code = "EBUSY";
+					throw error;
+				}
+			}
+			return realStat(...args);
+		});
+
+		try {
+			const state = await loadCodexCliState({ forceRefresh: true });
+			expect(state?.activeAccountId).toBe("acc_a");
+			expect(accountsReadAttempts).toBe(2);
+			expect(accountsStatAttempts).toBe(2);
+		} finally {
+			readSpy.mockRestore();
+			statSpy.mockRestore();
+		}
+	});
+
+	it("falls back to Codex auth.json when accounts.json is missing", async () => {
+		await writeFile(
+			authPath,
+			JSON.stringify(
+				{
+					auth_mode: "chatgpt",
+					OPENAI_API_KEY: null,
+					tokens: {
+						access_token:
+							"eyJhbGciOiJub25lIn0.eyJleHAiOjQxMDAwMDAwMDAsImh0dHBzOi8vYXBpLm9wZW5haS5jb20vYXV0aCI6eyJjaGF0Z3B0X2FjY291bnRfaWQiOiJhY2NfYXV0aCJ9LCJlbWFpbCI6ImF1dGhAZXhhbXBsZS5jb20ifQ.",
+						refresh_token: "refresh-auth",
+						account_id: "acc_auth",
+					},
+					last_refresh: "2026-02-25T21:36:07.864Z",
+				},
+				null,
+				2,
+			),
+			"utf-8",
+		);
+
+		const state = await loadCodexCliState({ forceRefresh: true });
+		expect(state?.path).toBe(authPath);
+		expect(state?.accounts.length).toBe(1);
+		expect(state?.activeAccountId).toBe("acc_auth");
+		expect(state?.activeEmail).toBe("auth@example.com");
+
+		const lookup = await lookupCodexCliTokensByEmail("AUTH@EXAMPLE.COM");
+		expect(lookup?.refreshToken).toBe("refresh-auth");
+		expect(lookup?.accountId).toBe("acc_auth");
+	});
+
+	it("falls back to auth.json when accounts.json is malformed", async () => {
+		await writeFile(accountsPath, "{ malformed json", "utf-8");
+		await writeFile(
+			authPath,
+			JSON.stringify(
+				{
+					auth_mode: "chatgpt",
+					OPENAI_API_KEY: null,
+					tokens: {
+						access_token:
+							"eyJhbGciOiJub25lIn0.eyJleHAiOjQxMDAwMDAwMDAsImh0dHBzOi8vYXBpLm9wZW5haS5jb20vYXV0aCI6eyJjaGF0Z3B0X2FjY291bnRfaWQiOiJhY2NfYXV0aCJ9LCJlbWFpbCI6ImF1dGhAZXhhbXBsZS5jb20ifQ.",
+						refresh_token: "refresh-auth",
+						account_id: "acc_auth",
+					},
+				},
+				null,
+				2,
+			),
+			"utf-8",
+		);
+
+		const state = await loadCodexCliState({ forceRefresh: true });
+		expect(state?.path).toBe(authPath);
+		expect(state?.activeAccountId).toBe("acc_auth");
+		expect(state?.accounts.length).toBe(1);
+	});
+
 	it("derives active selection from per-account active flag", async () => {
 		await writeFile(
 			accountsPath,
@@ -263,6 +440,142 @@ describe("codex-cli state", () => {
 		expect(written.accounts?.[1]?.active).toBe(true);
 	});
 
+	it("updates both accounts.json and auth.json when both files exist", async () => {
+		await writeFile(
+			accountsPath,
+			JSON.stringify(
+				{
+					accounts: [
+						{
+							accountId: "acc_a",
+							email: "a@example.com",
+							auth: {
+								tokens: {
+									access_token: "access-a",
+									id_token: "id-a",
+									refresh_token: "refresh-a",
+								},
+							},
+						},
+						{
+							accountId: "acc_b",
+							email: "b@example.com",
+							auth: {
+								tokens: {
+									access_token: "access-b",
+									id_token: "id-b",
+									refresh_token: "refresh-b",
+								},
+							},
+						},
+					],
+				},
+				null,
+				2,
+			),
+			"utf-8",
+		);
+		await writeFile(
+			authPath,
+			JSON.stringify(
+				{
+					auth_mode: "chatgpt",
+					OPENAI_API_KEY: null,
+					tokens: {
+						access_token: "old-access",
+						id_token: "old-id-token",
+						refresh_token: "old-refresh",
+						account_id: "old-account",
+					},
+				},
+				null,
+				2,
+			),
+			"utf-8",
+		);
+
+		const updated = await setCodexCliActiveSelection({ accountId: "acc_b" });
+		expect(updated).toBe(true);
+
+		const writtenAccounts = JSON.parse(await readFile(accountsPath, "utf-8")) as {
+			activeAccountId?: string;
+			accounts?: Array<{ active?: boolean }>;
+		};
+		expect(writtenAccounts.activeAccountId).toBe("acc_b");
+		expect(writtenAccounts.accounts?.[0]?.active).toBe(false);
+		expect(writtenAccounts.accounts?.[1]?.active).toBe(true);
+
+		const writtenAuth = JSON.parse(await readFile(authPath, "utf-8")) as {
+			tokens?: { access_token?: string; id_token?: string; refresh_token?: string; account_id?: string };
+		};
+		expect(writtenAuth.tokens?.access_token).toBe("access-b");
+		expect(writtenAuth.tokens?.id_token).toBe("id-b");
+		expect(writtenAuth.tokens?.refresh_token).toBe("refresh-b");
+		expect(writtenAuth.tokens?.account_id).toBe("acc_b");
+	});
+
+	it("prefers explicit selection tokens over stale accounts.json tokens", async () => {
+		await writeFile(
+			accountsPath,
+			JSON.stringify(
+				{
+					accounts: [
+						{
+							accountId: "acc_b",
+							email: "b@example.com",
+							auth: {
+								tokens: {
+									access_token: "stale-access",
+									id_token: "stale-id",
+									refresh_token: "stale-refresh",
+								},
+							},
+						},
+					],
+				},
+				null,
+				2,
+			),
+			"utf-8",
+		);
+		await writeFile(
+			authPath,
+			JSON.stringify(
+				{
+					auth_mode: "chatgpt",
+					OPENAI_API_KEY: null,
+					tokens: {
+						access_token: "old-access",
+						id_token: "old-id-token",
+						refresh_token: "old-refresh",
+						account_id: "old-account",
+					},
+				},
+				null,
+				2,
+			),
+			"utf-8",
+		);
+
+		const updated = await setCodexCliActiveSelection({
+			accountId: "acc_b",
+			email: "explicit@example.com",
+			accessToken: "fresh-access",
+			refreshToken: "fresh-refresh",
+			idToken: "fresh-id-token",
+		});
+		expect(updated).toBe(true);
+
+		const writtenAuth = JSON.parse(await readFile(authPath, "utf-8")) as {
+			email?: string;
+			tokens?: { access_token?: string; id_token?: string; refresh_token?: string };
+		};
+		expect(writtenAuth.email).toBe("explicit@example.com");
+		expect(writtenAuth.tokens?.access_token).toBe("fresh-access");
+		expect(writtenAuth.tokens?.id_token).toBe("fresh-id-token");
+		expect(writtenAuth.tokens?.refresh_token).toBe("fresh-refresh");
+	});
+
 	it("persists active selection by email match when accountId is omitted", async () => {
 		await writeFile(
 			accountsPath,
@@ -336,6 +649,118 @@ describe("codex-cli state", () => {
 		expect(updated).toBe(false);
 	});
 
+	it("still updates auth.json when accounts.json has no match", async () => {
+		await writeFile(
+			accountsPath,
+			JSON.stringify(
+				{
+					accounts: [
+						{
+							accountId: "acc_a",
+							email: "a@example.com",
+							auth: {
+								tokens: {
+									access_token: "access-a",
+									refresh_token: "refresh-a",
+								},
+							},
+						},
+					],
+				},
+				null,
+				2,
+			),
+			"utf-8",
+		);
+		await writeFile(
+			authPath,
+			JSON.stringify(
+				{
+					auth_mode: "chatgpt",
+					OPENAI_API_KEY: null,
+					tokens: {
+						access_token: "old-access",
+						id_token: "old-id-token",
+						refresh_token: "old-refresh",
+						account_id: "old-account",
+					},
+				},
+				null,
+				2,
+			),
+			"utf-8",
+		);
+
+		const updated = await setCodexCliActiveSelection({
+			accountId: "missing-account",
+			email: "b@example.com",
+			accessToken: "fresh-access",
+			refreshToken: "fresh-refresh",
+		});
+		expect(updated).toBe(true);
+
+		const writtenAuth = JSON.parse(await readFile(authPath, "utf-8")) as {
+			email?: string;
+			tokens?: { access_token?: string; id_token?: string; refresh_token?: string };
+		};
+		expect(writtenAuth.email).toBe("b@example.com");
+		expect(writtenAuth.tokens?.access_token).toBe("fresh-access");
+		expect(writtenAuth.tokens?.id_token).toBe("old-id-token");
+		expect(writtenAuth.tokens?.refresh_token).toBe("fresh-refresh");
+	});
+
+	it("does not update auth.json when no account match and selection lacks tokens", async () => {
+		await writeFile(
+			accountsPath,
+			JSON.stringify(
+				{
+					accounts: [
+						{
+							accountId: "acc_a",
+							email: "a@example.com",
+							auth: {
+								tokens: {
+									access_token: "access-a",
+									refresh_token: "refresh-a",
+								},
+							},
+						},
+					],
+				},
+				null,
+				2,
+			),
+			"utf-8",
+		);
+		await writeFile(
+			authPath,
+			JSON.stringify(
+				{
+					auth_mode: "chatgpt",
+					OPENAI_API_KEY: null,
+					tokens: {
+						access_token: "old-access",
+						id_token: "old-id-token",
+						refresh_token: "old-refresh",
+						account_id: "old-account",
+					},
+				},
+				null,
+				2,
+			),
+			"utf-8",
+		);
+
+		const before = await readFile(authPath, "utf-8");
+		const updated = await setCodexCliActiveSelection({
+			accountId: "missing-account",
+			email: "b@example.com",
+		});
+		expect(updated).toBe(false);
+		const after = await readFile(authPath, "utf-8");
+		expect(after).toBe(before);
+	});
+
 	it("returns false when writer sync is disabled", async () => {
 		process.env.CODEX_MULTI_AUTH_SYNC_CODEX_CLI = "0";
 		clearCodexCliStateCache();
@@ -385,4 +810,48 @@ describe("codex-cli state", () => {
 		const updated = await setCodexCliActiveSelection({ accountId: "acc_a" });
 		expect(updated).toBe(false);
 	});
+
+	it("writes selected tokens to Codex auth.json when accounts.json is absent", async () => {
+		await writeFile(
+			authPath,
+			JSON.stringify(
+				{
+					auth_mode: "chatgpt",
+					OPENAI_API_KEY: null,
+					tokens: {
+						access_token: "old.access.token",
+						id_token: "old.id.token",
+						refresh_token: "old-refresh",
+						account_id: "old-id",
+					},
+					last_refresh: "2026-01-01T00:00:00.000Z",
+				},
+				null,
+				2,
+			),
+			"utf-8",
+		);
+
+		const updated = await setCodexCliActiveSelection({
+			accountId: "acc_new",
+			email: "new@example.com",
+			accessToken: "new.access.token",
+			refreshToken: "new-refresh-token",
+			expiresAt: Date.parse("2026-03-01T00:00:00.000Z"),
+		});
+		expect(updated).toBe(true);
+
+		const written = JSON.parse(await readFile(authPath, "utf-8")) as {
+			tokens?: {
+				access_token?: string;
+				id_token?: string;
+				refresh_token?: string;
+				account_id?: string;
+			};
+		};
+		expect(written.tokens?.access_token).toBe("new.access.token");
+		expect(written.tokens?.id_token).toBe("old.id.token");
+		expect(written.tokens?.refresh_token).toBe("new-refresh-token");
+		expect(written.tokens?.account_id).toBe("acc_new");
+	});
 });
diff --git a/test/codex-cli-sync.test.ts b/test/codex-cli-sync.test.ts
index 58cbe271..80fd6f0a 100644
--- a/test/codex-cli-sync.test.ts
+++ b/test/codex-cli-sync.test.ts
@@ -1,23 +1,29 @@
-import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import type { AccountStorageV3 } from "../lib/storage.js";
 import { clearCodexCliStateCache } from "../lib/codex-cli/state.js";
 import { syncAccountStorageFromCodexCli } from "../lib/codex-cli/sync.js";
+import { setCodexCliActiveSelection } from "../lib/codex-cli/writer.js";
 
 describe("codex-cli sync", () => {
 	let tempDir: string;
 	let accountsPath: string;
+	let authPath: string;
 	let previousPath: string | undefined;
+	let previousAuthPath: string | undefined;
 	let previousSync: string | undefined;
 
 	beforeEach(async () => {
 		previousPath = process.env.CODEX_CLI_ACCOUNTS_PATH;
+		previousAuthPath = process.env.CODEX_CLI_AUTH_PATH;
 		previousSync = process.env.CODEX_MULTI_AUTH_SYNC_CODEX_CLI;
 		tempDir = await mkdtemp(join(tmpdir(), "codex-multi-auth-sync-"));
 		accountsPath = join(tempDir, "accounts.json");
+		authPath = join(tempDir, "auth.json");
 		process.env.CODEX_CLI_ACCOUNTS_PATH = accountsPath;
+		process.env.CODEX_CLI_AUTH_PATH = authPath;
 		process.env.CODEX_MULTI_AUTH_SYNC_CODEX_CLI = "1";
 		clearCodexCliStateCache();
 	});
@@ -26,6 +32,8 @@ describe("codex-cli sync", () => {
 		clearCodexCliStateCache();
 		if (previousPath === undefined) delete process.env.CODEX_CLI_ACCOUNTS_PATH;
 		else process.env.CODEX_CLI_ACCOUNTS_PATH = previousPath;
+		if (previousAuthPath === undefined) delete process.env.CODEX_CLI_AUTH_PATH;
+		else process.env.CODEX_CLI_AUTH_PATH = previousAuthPath;
 		if (previousSync === undefined) delete process.env.CODEX_MULTI_AUTH_SYNC_CODEX_CLI;
 		else process.env.CODEX_MULTI_AUTH_SYNC_CODEX_CLI = previousSync;
 		await rm(tempDir, { recursive: true, force: true });
@@ -205,4 +213,315 @@ describe("codex-cli sync", () => {
 		expect(result.changed).toBe(false);
 		expect(result.storage).toBe(current);
 	});
+
+	it("keeps local active selection when local write is newer than codex snapshot", async () => {
+		await writeFile(
+			authPath,
+			JSON.stringify(
+				{
+					auth_mode: "chatgpt",
+					OPENAI_API_KEY: null,
+					tokens: {
+						access_token: "local.access.token",
+						refresh_token: "local-refresh-token",
+						account_id: "acc_a",
+					},
+				},
+				null,
+				2,
+			),
+			"utf-8",
+		);
+		await setCodexCliActiveSelection({
+			accountId: "acc_a",
+			accessToken: "local.access.token",
+			refreshToken: "local-refresh-token",
+		});
+
+		await writeFile(
+			accountsPath,
+			JSON.stringify(
+				{
+					codexMultiAuthSyncVersion: Date.now() - 120_000,
+					activeAccountId: "acc_b",
+					accounts: [
+						{
+							accountId: "acc_a",
+							email: "a@example.com",
+							auth: { tokens: { access_token: "a.access", refresh_token: "refresh-a" } },
+						},
+						{
+							accountId: "acc_b",
+							email: "b@example.com",
+							auth: { tokens: { access_token: "b.access", refresh_token: "refresh-b" } },
+						},
+					],
+				},
+				null,
+				2,
+			),
+			"utf-8",
+		);
+		clearCodexCliStateCache();
+
+		const current: AccountStorageV3 = {
+			version: 3,
+			accounts: [
+				{
+					accountId: "acc_a",
+					email: "a@example.com",
+					refreshToken: "refresh-a",
+					addedAt: 1,
+					lastUsed: 1,
+				},
+				{
+					accountId: "acc_b",
+					email: "b@example.com",
+					refreshToken: "refresh-b",
+					addedAt: 1,
+					lastUsed: 1,
+				},
+			],
+			activeIndex: 0,
+			activeIndexByFamily: { codex: 0 },
+		};
+
+		const result = await syncAccountStorageFromCodexCli(current);
+		expect(result.storage?.activeIndex).toBe(0);
+	});
+
+	it("keeps local active selection when local state is newer by sub-second gap and syncVersion exists", async () => {
+		await writeFile(
+			authPath,
+			JSON.stringify(
+				{
+					auth_mode: "chatgpt",
+					OPENAI_API_KEY: null,
+					tokens: {
+						access_token: "local.access.token",
+						refresh_token: "local-refresh-token",
+						account_id: "acc_a",
+					},
+				},
+				null,
+				2,
+			),
+			"utf-8",
+		);
+		await setCodexCliActiveSelection({
+			accountId: "acc_a",
+			accessToken: "local.access.token",
+			refreshToken: "local-refresh-token",
+		});
+
+		const staleSyncVersion = Date.now() - 500;
+		await writeFile(
+			accountsPath,
+			JSON.stringify(
+				{
+					codexMultiAuthSyncVersion: staleSyncVersion,
+					activeAccountId: "acc_b",
+					accounts: [
+						{
+							accountId: "acc_a",
+							email: "a@example.com",
+							auth: { tokens: { access_token: "a.access", refresh_token: "refresh-a" } },
+						},
+						{
+							accountId: "acc_b",
+							email: "b@example.com",
+							auth: { tokens: { access_token: "b.access", refresh_token: "refresh-b" } },
+						},
+					],
+				},
+				null,
+				2,
+			),
+			"utf-8",
+		);
+		clearCodexCliStateCache();
+
+		const current: AccountStorageV3 = {
+			version: 3,
+			accounts: [
+				{
+					accountId: "acc_a",
+					email: "a@example.com",
+					refreshToken: "refresh-a",
+					addedAt: 1,
+					lastUsed: 1,
+				},
+				{
+					accountId: "acc_b",
+					email: "b@example.com",
+					refreshToken: "refresh-b",
+					addedAt: 1,
+					lastUsed: 1,
+				},
+			],
+			activeIndex: 0,
+			activeIndexByFamily: { codex: 0 },
+		};
+
+		const result = await syncAccountStorageFromCodexCli(current);
+		expect(result.storage?.activeIndex).toBe(0);
+	});
+
+	it("marks changed when local index normalization mutates storage while codex selection is skipped", async () => {
+		await writeFile(
+			authPath,
+			JSON.stringify(
+				{
+					auth_mode: "chatgpt",
+					OPENAI_API_KEY: null,
+					tokens: {
+						access_token: "local.access.token",
+						refresh_token: "local-refresh-token",
+						account_id: "acc_a",
+					},
+				},
+				null,
+				2,
+			),
+			"utf-8",
+		);
+		await setCodexCliActiveSelection({
+			accountId: "acc_a",
+			accessToken: "local.access.token",
+			refreshToken: "local-refresh-token",
+		});
+
+		await writeFile(
+			accountsPath,
+			JSON.stringify(
+				{
+					codexMultiAuthSyncVersion: Date.now() - 120_000,
+					activeAccountId: "acc_b",
+					accounts: [
+						{
+							accountId: "acc_a",
+							email: "a@example.com",
+							auth: { tokens: { access_token: "a.access", refresh_token: "refresh-a" } },
+						},
+						{
+							accountId: "acc_b",
+							email: "b@example.com",
+							auth: { tokens: { access_token: "b.access", refresh_token: "refresh-b" } },
+						},
+					],
+				},
+				null,
+				2,
+			),
+			"utf-8",
+		);
+		clearCodexCliStateCache();
+
+		const current: AccountStorageV3 = {
+			version: 3,
+			accounts: [
+				{
+					accountId: "acc_a",
+					email: "a@example.com",
+					refreshToken: "refresh-a",
+					addedAt: 1,
+					lastUsed: 1,
+				},
+				{
+					accountId: "acc_b",
+					email: "b@example.com",
+					refreshToken: "refresh-b",
+					addedAt: 1,
+					lastUsed: 1,
+				},
+			],
+			activeIndex: 99,
+			activeIndexByFamily: { codex: 99 },
+		};
+
+		const result = await syncAccountStorageFromCodexCli(current);
+		expect(result.changed).toBe(true);
+		expect(result.storage?.activeIndex).toBe(1);
+		expect(result.storage?.activeIndexByFamily?.codex).toBe(1);
+	});
+
+	it("serializes concurrent active-selection writes to keep accounts/auth aligned", async () => {
+		await writeFile(
+			accountsPath,
+			JSON.stringify(
+				{
+					accounts: [
+						{
+							accountId: "acc_a",
+							email: "a@example.com",
+							auth: {
+								tokens: {
+									access_token: "access-a",
+									id_token: "id-a",
+									refresh_token: "refresh-a",
+								},
+							},
+						},
+						{
+							accountId: "acc_b",
+							email: "b@example.com",
+							auth: {
+								tokens: {
+									access_token: "access-b",
+									id_token: "id-b",
+									refresh_token: "refresh-b",
+								},
+							},
+						},
+					],
+				},
+				null,
+				2,
+			),
+			"utf-8",
+		);
+		await writeFile(
+			authPath,
+			JSON.stringify(
+				{
+					auth_mode: "chatgpt",
+					OPENAI_API_KEY: null,
+					email: "a@example.com",
+					tokens: {
+						access_token: "access-a",
+						id_token: "id-a",
+						refresh_token: "refresh-a",
+						account_id: "acc_a",
+					},
+				},
+				null,
+				2,
+			),
+			"utf-8",
+		);
+
+		const [first, second] = await Promise.all([
+			setCodexCliActiveSelection({ accountId: "acc_a" }),
+			setCodexCliActiveSelection({ accountId: "acc_b" }),
+		]);
+		expect(first).toBe(true);
+		expect(second).toBe(true);
+
+		const writtenAccounts = JSON.parse(await readFile(accountsPath, "utf-8")) as {
+			activeAccountId?: string;
+			activeEmail?: string;
+			accounts?: Array<{ accountId?: string; active?: boolean }>;
+		};
+		const writtenAuth = JSON.parse(await readFile(authPath, "utf-8")) as {
+			email?: string;
+			tokens?: { account_id?: string };
+		};
+
+		expect(writtenAccounts.activeAccountId).toBe("acc_b");
+		expect(writtenAccounts.activeEmail).toBe("b@example.com");
+		expect(writtenAccounts.accounts?.[0]?.active).toBe(false);
+		expect(writtenAccounts.accounts?.[1]?.active).toBe(true);
+		expect(writtenAuth.tokens?.account_id).toBe("acc_b");
+		expect(writtenAuth.email).toBe("b@example.com");
+	});
 });
diff --git a/test/codex-manager-cli.test.ts b/test/codex-manager-cli.test.ts
new file mode 100644
index 00000000..ffdba307
--- /dev/null
+++ b/test/codex-manager-cli.test.ts
@@ -0,0 +1,1400 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const loadAccountsMock = vi.fn();
+const loadFlaggedAccountsMock = vi.fn();
+const saveAccountsMock = vi.fn();
+const saveFlaggedAccountsMock = vi.fn();
+const setStoragePathMock = vi.fn();
+const getStoragePathMock = vi.fn(() => "/mock/openai-codex-accounts.json");
+const queuedRefreshMock = vi.fn();
+const setCodexCliActiveSelectionMock = vi.fn();
+const promptAddAnotherAccountMock = vi.fn();
+const promptLoginModeMock = vi.fn();
+const fetchCodexQuotaSnapshotMock = vi.fn();
+const loadDashboardDisplaySettingsMock = vi.fn();
+const saveDashboardDisplaySettingsMock = vi.fn();
+const loadQuotaCacheMock = vi.fn();
+const saveQuotaCacheMock = vi.fn();
+const loadPluginConfigMock = vi.fn();
+const savePluginConfigMock = vi.fn();
+const selectMock = vi.fn();
+
+vi.mock("../lib/logger.js", () => ({
+	createLogger: vi.fn(() => ({
+		debug: vi.fn(),
+		info: vi.fn(),
+		warn: vi.fn(),
+		error: vi.fn(),
+	})),
+	logWarn: vi.fn(),
+}));
+
+vi.mock("../lib/auth/auth.js", () => ({
+	createAuthorizationFlow: vi.fn(),
+	exchangeAuthorizationCode: vi.fn(),
+	parseAuthorizationInput: vi.fn(),
+	REDIRECT_URI: "http://127.0.0.1:1455/auth/callback",
+}));
+
+vi.mock("../lib/auth/browser.js", () => ({
+	openBrowserUrl: vi.fn(),
+	copyTextToClipboard: vi.fn(() => true),
+}));
+
+vi.mock("../lib/auth/server.js", () => ({
+	startLocalOAuthServer: vi.fn(),
+}));
+
+vi.mock("../lib/cli.js", () => ({
+	promptAddAnotherAccount: promptAddAnotherAccountMock,
+	promptLoginMode: promptLoginModeMock,
+}));
+
+vi.mock("../lib/prompts/codex.js", () => ({
+	MODEL_FAMILIES: ["codex"] as const,
+}));
+
+vi.mock("../lib/accounts.js", () => ({
+	extractAccountEmail: vi.fn(() => undefined),
+	extractAccountId: vi.fn(() => "acc_test"),
+	formatAccountLabel: vi.fn((account: { email?: string }, index: number) =>
+		account.email ? `${index + 1}. ${account.email}` : `Account ${index + 1}`,
+	),
+	formatCooldown: vi.fn(() => null),
+	formatWaitTime: vi.fn((ms: number) => `${Math.max(1, Math.round(ms / 1000))}s`),
+	getAccountIdCandidates: vi.fn(() => []),
+	resolveRequestAccountId: vi.fn(
+		(_override: string | undefined, _source: string | undefined, tokenId: string | undefined) =>
+			tokenId,
+	),
+	sanitizeEmail: vi.fn((email: string | undefined) =>
+		typeof email === "string" ? email.toLowerCase() : undefined,
+	),
+	selectBestAccountCandidate: vi.fn(() => null),
+}));
+
+vi.mock("../lib/storage.js", () => ({
+	loadAccounts: loadAccountsMock,
+	loadFlaggedAccounts: loadFlaggedAccountsMock,
+	saveAccounts: saveAccountsMock,
+	saveFlaggedAccounts: saveFlaggedAccountsMock,
+	setStoragePath: setStoragePathMock,
+	getStoragePath: getStoragePathMock,
+}));
+
+vi.mock("../lib/refresh-queue.js", () => ({
+	queuedRefresh: queuedRefreshMock,
+}));
+
+vi.mock("../lib/codex-cli/writer.js", () => ({
+	setCodexCliActiveSelection: setCodexCliActiveSelectionMock,
+}));
+
+vi.mock("../lib/quota-probe.js", () => ({
+	fetchCodexQuotaSnapshot: fetchCodexQuotaSnapshotMock,
+	formatQuotaSnapshotLine: vi.fn(() => "probe-ok"),
+}));
+
+vi.mock("../lib/dashboard-settings.js", () => ({
+	DEFAULT_DASHBOARD_DISPLAY_SETTINGS: {
+		showPerAccountRows: true,
+		showQuotaDetails: true,
+		showForecastReasons: true,
+		showRecommendations: true,
+		showLiveProbeNotes: true,
+		menuAutoFetchLimits: true,
+		menuSortEnabled: true,
+		menuSortMode: "ready-first",
+		menuSortPinCurrent: true,
+		menuSortQuickSwitchVisibleRow: true,
+	},
+	getDashboardSettingsPath: vi.fn(() => "/mock/dashboard-settings.json"),
+	loadDashboardDisplaySettings: loadDashboardDisplaySettingsMock,
+	saveDashboardDisplaySettings: saveDashboardDisplaySettingsMock,
+}));
+
+vi.mock("../lib/config.js", async () => {
+	const actual = await vi.importActual("../lib/config.js");
+	return {
+		...(actual as Record<string, unknown>),
+		loadPluginConfig: loadPluginConfigMock,
+		savePluginConfig: savePluginConfigMock,
+	};
+});
+
+vi.mock("../lib/quota-cache.js", () => ({
+	loadQuotaCache: loadQuotaCacheMock,
+	saveQuotaCache: saveQuotaCacheMock,
+}));
+
+vi.mock("../lib/ui/select.js", () => ({
+	select: selectMock,
+}));
+
+const stdinIsTTYDescriptor = Object.getOwnPropertyDescriptor(process.stdin, "isTTY");
+const stdoutIsTTYDescriptor = Object.getOwnPropertyDescriptor(process.stdout, "isTTY");
+
+function setInteractiveTTY(enabled: boolean): void {
+	Object.defineProperty(process.stdin, "isTTY", {
+		value: enabled,
+		configurable: true,
+	});
+	Object.defineProperty(process.stdout, "isTTY", {
+		value: enabled,
+		configurable: true,
+	});
+}
+
+function restoreTTYDescriptors(): void {
+	if (stdinIsTTYDescriptor) {
+		Object.defineProperty(process.stdin, "isTTY", stdinIsTTYDescriptor);
+	} else {
+		delete (process.stdin as unknown as { isTTY?: boolean }).isTTY;
+	}
+	if (stdoutIsTTYDescriptor) {
+		Object.defineProperty(process.stdout, "isTTY", stdoutIsTTYDescriptor);
+	} else {
+		delete (process.stdout as unknown as { isTTY?: boolean }).isTTY;
+	}
+}
+
+describe("codex manager cli commands", () => {
+	beforeEach(() => {
+		vi.resetModules();
+		vi.clearAllMocks();
+		loadAccountsMock.mockReset();
+		loadFlaggedAccountsMock.mockReset();
+		saveAccountsMock.mockReset();
+		saveFlaggedAccountsMock.mockReset();
+		queuedRefreshMock.mockReset();
+		setCodexCliActiveSelectionMock.mockReset();
+		promptAddAnotherAccountMock.mockReset();
+		promptLoginModeMock.mockReset();
+		fetchCodexQuotaSnapshotMock.mockReset();
+		loadDashboardDisplaySettingsMock.mockReset();
+		saveDashboardDisplaySettingsMock.mockReset();
+		loadQuotaCacheMock.mockReset();
+		saveQuotaCacheMock.mockReset();
+		loadPluginConfigMock.mockReset();
+		savePluginConfigMock.mockReset();
+		selectMock.mockReset();
+		fetchCodexQuotaSnapshotMock.mockResolvedValue({
+			status: 200,
+			model: "gpt-5-codex",
+			primary: {},
+			secondary: {},
+		});
+		loadQuotaCacheMock.mockResolvedValue({
+			byAccountId: {},
+			byEmail: {},
+		});
+		loadFlaggedAccountsMock.mockResolvedValue({
+			version: 1,
+			accounts: [],
+		});
+		loadDashboardDisplaySettingsMock.mockResolvedValue({
+			showPerAccountRows: true,
+			showQuotaDetails: true,
+			showForecastReasons: true,
+			showRecommendations: true,
+			showLiveProbeNotes: true,
+			menuAutoFetchLimits: true,
+			menuSortEnabled: true,
+			menuSortMode: "ready-first",
+			menuSortPinCurrent: true,
+			menuSortQuickSwitchVisibleRow: true,
+		});
+		loadPluginConfigMock.mockReturnValue({});
+		savePluginConfigMock.mockResolvedValue(undefined);
+		selectMock.mockResolvedValue(undefined);
+		restoreTTYDescriptors();
+		setStoragePathMock.mockReset();
+		getStoragePathMock.mockReturnValue("/mock/openai-codex-accounts.json");
+	});
+
+	afterEach(() => {
+		restoreTTYDescriptors();
+		vi.restoreAllMocks();
+	});
+
+	it("runs forecast in json mode", async () => {
+		const now = Date.now();
+		loadAccountsMock.mockResolvedValueOnce({
+			version: 3,
+			activeIndex: 0,
+			activeIndexByFamily: { codex: 0 },
+			accounts: [
+				{
+					email: "a@example.com",
+					refreshToken: "refresh-a",
+					addedAt: now - 1_000,
+					lastUsed: now - 1_000,
+				},
+				{
+					email: "b@example.com",
+					refreshToken: "refresh-b",
+					addedAt: now - 1_000,
+					lastUsed: now - 1_000,
+					enabled: false,
+				},
+			],
+		});
+
+		const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+		const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+		const { runCodexMultiAuthCli } = await import("../lib/codex-manager.js");
+
+		const exitCode = await runCodexMultiAuthCli(["auth", "forecast", "--json"]);
+		expect(exitCode).toBe(0);
+		expect(errorSpy).not.toHaveBeenCalled();
+		expect(queuedRefreshMock).not.toHaveBeenCalled();
+
+		const payload = JSON.parse(String(logSpy.mock.calls[0]?.[0])) as {
+			command: string;
+			summary: { total: number };
+			recommendation: { recommendedIndex: number | null };
+		};
+		expect(payload.command).toBe("forecast");
+		expect(payload.summary.total).toBe(2);
+		expect(payload.recommendation.recommendedIndex).toBe(0);
+	});
+
+	it("prints implemented 40-feature matrix", async () => {
+		const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+		const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+		const { runCodexMultiAuthCli } = await import("../lib/codex-manager.js");
+
+		const exitCode = await runCodexMultiAuthCli(["auth", "features"]);
+		expect(exitCode).toBe(0);
+		expect(errorSpy).not.toHaveBeenCalled();
+		expect(logSpy.mock.calls[0]?.[0]).toBe("Implemented features (40)");
+		expect(
+			logSpy.mock.calls.some((call) =>
+				String(call[0]).includes("40. OAuth browser-first flow with manual callback fallback"),
+			),
+		).toBe(true);
+	});
+
+	it("prints auth help when subcommand is --help", async () => {
+		const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+		const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+		const { runCodexMultiAuthCli } = await import("../lib/codex-manager.js");
+
+		const exitCode = await runCodexMultiAuthCli(["auth", "--help"]);
+		expect(exitCode).toBe(0);
+		expect(errorSpy).not.toHaveBeenCalled();
+		expect(logSpy.mock.calls[0]?.[0]).toContain("Codex Multi-Auth CLI");
+	});
+
+	it("restores healthy flagged accounts into active storage", async () => {
+		const now = Date.now();
+		loadFlaggedAccountsMock.mockResolvedValueOnce({
+			version: 1,
+			accounts: [
+				{
+					refreshToken: "flagged-refresh",
+					accountId: "acc_flagged",
+					email: "flagged@example.com",
+					addedAt: now - 1_000,
+					lastUsed: now - 1_000,
+					flaggedAt: now - 5_000,
+				},
+			],
+		});
+		loadAccountsMock.mockResolvedValueOnce(null);
+		queuedRefreshMock.mockResolvedValueOnce({
+			type: "success",
+			access: "access-restored",
+			refresh: "refresh-restored",
+			expires: now + 3_600_000,
+		});
+		const { runCodexMultiAuthCli } = await import("../lib/codex-manager.js");
+
+		const exitCode = await runCodexMultiAuthCli(["auth", "verify-flagged", "--json"]);
+		expect(exitCode).toBe(0);
+		expect(saveAccountsMock).toHaveBeenCalledTimes(1);
+		expect(saveFlaggedAccountsMock).toHaveBeenCalledTimes(1);
+		expect(saveFlaggedAccountsMock).toHaveBeenCalledWith({
+			version: 1,
+			accounts: [],
+		});
+	});
+
+	it("keeps flagged account when verification still fails", async () => {
+		const now = Date.now();
+		loadFlaggedAccountsMock.mockResolvedValueOnce({
+			version: 1,
+			accounts: [
+				{
+					refreshToken: "flagged-refresh",
+					accountId: "acc_flagged",
+					email: "flagged@example.com",
+					addedAt: now - 1_000,
+					lastUsed: now - 1_000,
+					flaggedAt: now - 5_000,
+				},
+			],
+		});
+		loadAccountsMock.mockResolvedValueOnce({
+			version: 3,
+			activeIndex: 0,
+			activeIndexByFamily: { codex: 0 },
+			accounts: [],
+		});
+		queuedRefreshMock.mockResolvedValueOnce({
+			type: "failed",
+			reason: "http_error",
+			statusCode: 401,
+			message: "token expired",
+		});
+		const { runCodexMultiAuthCli } = await import("../lib/codex-manager.js");
+
+		const exitCode = await runCodexMultiAuthCli(["auth", "verify-flagged", "--json"]);
+		expect(exitCode).toBe(0);
+		expect(saveAccountsMock).not.toHaveBeenCalled();
+		expect(saveFlaggedAccountsMock).toHaveBeenCalledTimes(1);
+		expect(saveFlaggedAccountsMock).toHaveBeenCalledWith(
+			expect.objectContaining({
+				accounts: [
+					expect.objectContaining({
+						refreshToken: "flagged-refresh",
+						lastError: "token expired",
+					}),
+				],
+			}),
+		);
+	});
+
+	it("runs fix dry-run without persisting changes", async () => {
+		const now = Date.now();
+		loadAccountsMock.mockResolvedValueOnce({
+			version: 3,
+			activeIndex: 0,
+			activeIndexByFamily: { codex: 0 },
+			accounts: [
+				{
+					email: "a@example.com",
+					refreshToken: "refresh-a",
+					addedAt: now - 1_000,
+					lastUsed: now - 1_000,
+				},
+			],
+		});
+		queuedRefreshMock.mockResolvedValueOnce({
+			type: "failed",
+			reason: "missing_refresh",
+			message: "No refresh token in response or input",
+		});
+
+		const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+		const { runCodexMultiAuthCli } = await import("../lib/codex-manager.js");
+
+		const exitCode = await runCodexMultiAuthCli(["auth", "fix", "--dry-run", "--json"]);
+		expect(exitCode).toBe(0);
+		expect(saveAccountsMock).not.toHaveBeenCalled();
+
+		const payload = JSON.parse(String(logSpy.mock.calls[0]?.[0])) as {
+			command: string;
+			dryRun: boolean;
+			changed: boolean;
+			reports: Array<{ outcome: string }>;
+		};
+		expect(payload.command).toBe("fix");
+		expect(payload.dryRun).toBe(true);
+		expect(payload.changed).toBe(true);
+		expect(payload.reports[0]?.outcome).toBe("warning-soft-failure");
+	});
+
+	it("persists rotated tokens during auth check and syncs active codex selection", async () => {
+		const now = Date.now();
+		loadAccountsMock.mockResolvedValueOnce({
+			version: 3,
+			activeIndex: 0,
+			activeIndexByFamily: { codex: 0 },
+			accounts: [
+				{
+					accountId: "acc_old",
+					email: "a@example.com",
+					refreshToken: "refresh-a",
+					accessToken: "access-a",
+					expiresAt: now - 60_000,
+					addedAt: now - 1_000,
+					lastUsed: now - 1_000,
+					enabled: true,
+				},
+			],
+		});
+		queuedRefreshMock.mockResolvedValueOnce({
+			type: "success",
+			access: "access-a-next",
+			refresh: "refresh-a-next",
+			expires: now + 3_600_000,
+		});
+
+		const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+		const { runCodexMultiAuthCli } = await import("../lib/codex-manager.js");
+
+		const exitCode = await runCodexMultiAuthCli(["auth", "check"]);
+		expect(exitCode).toBe(0);
+		expect(logSpy).toHaveBeenCalled();
+		expect(saveAccountsMock).toHaveBeenCalledTimes(1);
+		expect(setCodexCliActiveSelectionMock).toHaveBeenCalledTimes(1);
+		expect(setCodexCliActiveSelectionMock).toHaveBeenCalledWith(
+			expect.objectContaining({
+				accessToken: "access-a-next",
+				refreshToken: "refresh-a-next",
+				expiresAt: now + 3_600_000,
+			}),
+		);
+	});
+
+	it("treats fresh access tokens as healthy without forcing refresh", async () => {
+		const now = Date.now();
+		loadAccountsMock.mockResolvedValueOnce({
+			version: 3,
+			activeIndex: 0,
+			activeIndexByFamily: { codex: 0 },
+			accounts: [
+				{
+					accountId: "acc_live",
+					email: "live@example.com",
+					refreshToken: "refresh-live",
+					accessToken: "access-live",
+					expiresAt: now + 60 * 60 * 1000,
+					addedAt: now - 1_000,
+					lastUsed: now - 1_000,
+					enabled: true,
+				},
+			],
+		});
+		const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+		const { runCodexMultiAuthCli } = await import("../lib/codex-manager.js");
+
+		const exitCode = await runCodexMultiAuthCli(["auth", "check"]);
+		expect(exitCode).toBe(0);
+		expect(queuedRefreshMock).not.toHaveBeenCalled();
+		expect(saveAccountsMock).not.toHaveBeenCalled();
+		expect(fetchCodexQuotaSnapshotMock).toHaveBeenCalledTimes(1);
+		expect(setCodexCliActiveSelectionMock).toHaveBeenCalledTimes(1);
+		expect(logSpy.mock.calls.some((call) => String(call[0]).includes("live session OK"))).toBe(true);
+	});
+
+	it("runs fix apply mode and returns a switch recommendation", async () => {
+		const now = Date.now();
+		loadAccountsMock.mockResolvedValueOnce({
+			version: 3,
+			activeIndex: 0,
+			activeIndexByFamily: { codex: 0 },
+			accounts: [
+				{
+					email: "a@example.com",
+					refreshToken: "refresh-a",
+					addedAt: now - 1_000,
+					lastUsed: now - 1_000,
+				},
+				{
+					email: "b@example.com",
+					refreshToken: "refresh-b",
+					addedAt: now - 1_000,
+					lastUsed: now - 1_000,
+				},
+			],
+		});
+
+		queuedRefreshMock
+			.mockResolvedValueOnce({
+				type: "failed",
+				reason: "http_error",
+				statusCode: 401,
+				message: "unauthorized",
+			})
+			.mockResolvedValueOnce({
+				type: "success",
+				access: "access-b",
+				refresh: "refresh-b-next",
+				expires: now + 3_600_000,
+			});
+
+		const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+		const { runCodexMultiAuthCli } = await import("../lib/codex-manager.js");
+
+		const exitCode = await runCodexMultiAuthCli(["auth", "fix", "--json"]);
+		expect(exitCode).toBe(0);
+		expect(saveAccountsMock).toHaveBeenCalledTimes(1);
+		expect(setCodexCliActiveSelectionMock).not.toHaveBeenCalled();
+
+		const payload = JSON.parse(String(logSpy.mock.calls[0]?.[0])) as {
+			changed: boolean;
+			recommendedSwitchCommand: string | null;
+		};
+		expect(payload.changed).toBe(true);
+		expect(payload.recommendedSwitchCommand).toBe("codex auth switch 2");
+	});
+
+	it("fails switch when Codex auth sync fails", async () => {
+		const now = Date.now();
+		loadAccountsMock.mockResolvedValueOnce({
+			version: 3,
+			activeIndex: 0,
+			activeIndexByFamily: { codex: 0 },
+			accounts: [
+				{
+					email: "a@example.com",
+					refreshToken: "refresh-a",
+					accessToken: "access-a",
+					expiresAt: now + 3_600_000,
+					addedAt: now - 1_000,
+					lastUsed: now - 1_000,
+					enabled: true,
+				},
+			],
+		});
+		setCodexCliActiveSelectionMock.mockResolvedValueOnce(false);
+		const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+		const { runCodexMultiAuthCli } = await import("../lib/codex-manager.js");
+
+		const exitCode = await runCodexMultiAuthCli(["auth", "switch", "1"]);
+		expect(exitCode).toBe(1);
+		expect(saveAccountsMock).toHaveBeenCalledTimes(1);
+		expect(errorSpy).toHaveBeenCalledWith(
+			expect.stringContaining("Codex auth sync failed"),
+		);
+	});
+
+	it("keeps auth login menu open after switch until user cancels", async () => {
+		const now = Date.now();
+		const storage = {
+			version: 3,
+			activeIndex: 0,
+			activeIndexByFamily: { codex: 0 },
+			accounts: [
+				{
+					email: "a@example.com",
+					accountId: "acc_a",
+					refreshToken: "refresh-a",
+					accessToken: "access-a",
+					expiresAt: now + 3_600_000,
+					addedAt: now - 1_000,
+					lastUsed: now - 1_000,
+					enabled: true,
+				},
+				{
+					email: "b@example.com",
+					accountId: "acc_b",
+					refreshToken: "refresh-b",
+					accessToken: "access-b",
+					expiresAt: now + 3_600_000,
+					addedAt: now - 1_000,
+					lastUsed: now - 1_000,
+					enabled: true,
+				},
+			],
+		};
+		loadAccountsMock.mockResolvedValue(storage);
+		setCodexCliActiveSelectionMock.mockResolvedValue(true);
+		promptLoginModeMock
+			.mockResolvedValueOnce({ mode: "manage", switchAccountIndex: 1 })
+			.mockResolvedValueOnce({ mode: "cancel" });
+		const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+		const { runCodexMultiAuthCli } = await import("../lib/codex-manager.js");
+
+		const exitCode = await runCodexMultiAuthCli(["auth", "login"]);
+		expect(exitCode).toBe(0);
+		expect(promptLoginModeMock).toHaveBeenCalledTimes(2);
+		expect(saveAccountsMock).toHaveBeenCalledTimes(1);
+		expect(logSpy).toHaveBeenCalledWith(
+			expect.stringContaining("Switched to account 2"),
+		);
+		expect(logSpy).toHaveBeenCalledWith("Cancelled.");
+	});
+
+	it("marks newly added login account active so smart sort reflects it immediately", async () => {
+		const now = Date.now();
+		let storageState: {
+			version: number;
+			activeIndex: number;
+			activeIndexByFamily: { codex: number };
+			accounts: Array<{
+				email: string;
+				accountId: string;
+				refreshToken: string;
+				accessToken: string;
+				expiresAt: number;
+				addedAt: number;
+				lastUsed: number;
+				enabled: boolean;
+			}>;
+		} = {
+			version: 3,
+			activeIndex: 0,
+			activeIndexByFamily: { codex: 0 },
+			accounts: [
+				{
+					email: "old@example.com",
+					accountId: "acc_old",
+					refreshToken: "refresh-old",
+					accessToken: "access-old",
+					expiresAt: now + 3_600_000,
+					addedAt: now - 5_000,
+					lastUsed: now - 5_000,
+					enabled: true,
+				},
+			],
+		};
+		loadAccountsMock.mockImplementation(async () => structuredClone(storageState));
+		saveAccountsMock.mockImplementation(async (nextStorage) => {
+			storageState = structuredClone(nextStorage);
+		});
+		promptLoginModeMock
+			.mockResolvedValueOnce({ mode: "add" })
+			.mockResolvedValueOnce({ mode: "cancel" });
+		promptAddAnotherAccountMock.mockResolvedValue(false);
+
+		const authModule = await import("../lib/auth/auth.js");
+		const createAuthorizationFlowMock = vi.mocked(authModule.createAuthorizationFlow);
+		const exchangeAuthorizationCodeMock = vi.mocked(authModule.exchangeAuthorizationCode);
+		const browserModule = await import("../lib/auth/browser.js");
+		const openBrowserUrlMock = vi.mocked(browserModule.openBrowserUrl);
+		const serverModule = await import("../lib/auth/server.js");
+		const startLocalOAuthServerMock = vi.mocked(serverModule.startLocalOAuthServer);
+
+		const flow: Awaited<ReturnType<typeof authModule.createAuthorizationFlow>> = {
+			pkce: { challenge: "pkce-challenge", verifier: "pkce-verifier" },
+			state: "oauth-state",
+			url: "https://auth.openai.com/mock",
+		};
+		createAuthorizationFlowMock.mockResolvedValue(flow);
+		const oauthResult: Awaited<ReturnType<typeof authModule.exchangeAuthorizationCode>> = {
+			type: "success",
+			access: "access-new",
+			refresh: "refresh-new",
+			expires: now + 7_200_000,
+			idToken: "id-token-new",
+			multiAccount: true,
+		};
+		exchangeAuthorizationCodeMock.mockResolvedValue(oauthResult);
+		openBrowserUrlMock.mockReturnValue(true);
+		const oauthServer: Awaited<ReturnType<typeof serverModule.startLocalOAuthServer>> = {
+			ready: true,
+			waitForCode: vi.fn(async () => ({ code: "oauth-code" })),
+			close: vi.fn(),
+		};
+		startLocalOAuthServerMock.mockResolvedValue(oauthServer);
+
+		const { runCodexMultiAuthCli } = await import("../lib/codex-manager.js");
+		const exitCode = await runCodexMultiAuthCli(["auth", "login"]);
+
+		expect(exitCode).toBe(0);
+		expect(storageState.accounts).toHaveLength(2);
+		expect(storageState.activeIndex).toBe(1);
+		expect(storageState.activeIndexByFamily.codex).toBe(1);
+		expect(setCodexCliActiveSelectionMock).toHaveBeenCalledTimes(1);
+	});
+
+	it("runs full refresh test from login menu deep-check mode", async () => {
+		const now = Date.now();
+		const storage = {
+			version: 3,
+			activeIndex: 0,
+			activeIndexByFamily: { codex: 0 },
+			accounts: [
+				{
+					email: "a@example.com",
+					accountId: "acc_a",
+					refreshToken: "refresh-a",
+					accessToken: "access-a",
+					expiresAt: now + 3_600_000,
+					addedAt: now - 1_000,
+					lastUsed: now - 1_000,
+					enabled: true,
+				},
+			],
+		};
+		loadAccountsMock.mockResolvedValue(storage);
+		promptLoginModeMock
+			.mockResolvedValueOnce({ mode: "deep-check" })
+			.mockResolvedValueOnce({ mode: "cancel" });
+		queuedRefreshMock.mockResolvedValueOnce({
+			type: "success",
+			access: "access-a-next",
+			refresh: "refresh-a-next",
+			expires: now + 7_200_000,
+		});
+		const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+		const { runCodexMultiAuthCli } = await import("../lib/codex-manager.js");
+
+		const exitCode = await runCodexMultiAuthCli(["auth", "login"]);
+		expect(exitCode).toBe(0);
+		expect(queuedRefreshMock).toHaveBeenCalledTimes(1);
+		expect(fetchCodexQuotaSnapshotMock).toHaveBeenCalledTimes(2);
+		expect(logSpy.mock.calls.some((call) => String(call[0]).includes("full refresh test"))).toBe(true);
+	});
+
+	it("runs quick check from login menu with live probe", async () => {
+		const now = Date.now();
+		const storage = {
+			version: 3,
+			activeIndex: 0,
+			activeIndexByFamily: { codex: 0 },
+			accounts: [
+				{
+					email: "a@example.com",
+					accountId: "acc_a",
+					refreshToken: "refresh-a",
+					accessToken: "access-a",
+					expiresAt: now + 3_600_000,
+					addedAt: now - 1_000,
+					lastUsed: now - 1_000,
+					enabled: true,
+				},
+			],
+		};
+		loadAccountsMock.mockResolvedValue(storage);
+		promptLoginModeMock
+			.mockResolvedValueOnce({ mode: "check" })
+			.mockResolvedValueOnce({ mode: "cancel" });
+		const { runCodexMultiAuthCli } = await import("../lib/codex-manager.js");
+
+		const exitCode = await runCodexMultiAuthCli(["auth", "login"]);
+		expect(exitCode).toBe(0);
+		expect(fetchCodexQuotaSnapshotMock).toHaveBeenCalledTimes(2);
+		expect(queuedRefreshMock).not.toHaveBeenCalled();
+	});
+
+	it("auto-refreshes cached limits on menu open", async () => {
+		const now = Date.now();
+		loadAccountsMock.mockResolvedValue({
+			version: 3,
+			activeIndex: 0,
+			activeIndexByFamily: { codex: 0 },
+			accounts: [
+				{
+					email: "a@example.com",
+					accountId: "acc_a",
+					refreshToken: "refresh-a",
+					accessToken: "access-a",
+					expiresAt: now + 60 * 60 * 1000,
+					addedAt: now - 1_000,
+					lastUsed: now - 1_000,
+					enabled: true,
+				},
+			],
+		});
+		loadDashboardDisplaySettingsMock.mockResolvedValue({
+			showPerAccountRows: true,
+			showQuotaDetails: true,
+			showForecastReasons: true,
+			showRecommendations: true,
+			showLiveProbeNotes: true,
+			menuAutoFetchLimits: true,
+			menuSortEnabled: false,
+			menuSortMode: "manual",
+			menuSortPinCurrent: true,
+			menuSortQuickSwitchVisibleRow: true,
+		});
+		promptLoginModeMock.mockResolvedValueOnce({ mode: "cancel" });
+
+		const { runCodexMultiAuthCli } = await import("../lib/codex-manager.js");
+		const exitCode = await runCodexMultiAuthCli(["auth", "login"]);
+
+		expect(exitCode).toBe(0);
+		expect(fetchCodexQuotaSnapshotMock).toHaveBeenCalledTimes(1);
+		expect(saveQuotaCacheMock).toHaveBeenCalledTimes(1);
+	});
+
+	it("keeps login loop running when settings action is selected", async () => {
+		const now = Date.now();
+		const storage = {
+			version: 3,
+			activeIndex: 0,
+			activeIndexByFamily: { codex: 0 },
+			accounts: [
+				{
+					email: "a@example.com",
+					accountId: "acc_a",
+					refreshToken: "refresh-a",
+					accessToken: "access-a",
+					expiresAt: now + 3_600_000,
+					addedAt: now - 1_000,
+					lastUsed: now - 1_000,
+					enabled: true,
+				},
+			],
+		};
+		loadAccountsMock.mockResolvedValue(storage);
+		promptLoginModeMock
+			.mockResolvedValueOnce({ mode: "settings" })
+			.mockResolvedValueOnce({ mode: "cancel" });
+		const { runCodexMultiAuthCli } = await import("../lib/codex-manager.js");
+
+		const exitCode = await runCodexMultiAuthCli(["auth", "login"]);
+		expect(exitCode).toBe(0);
+		expect(promptLoginModeMock).toHaveBeenCalledTimes(2);
+	});
+
+	it("passes smart-sorted accounts to auth menu while preserving source index mapping", async () => {
+		const now = Date.now();
+		const storage = {
+			version: 3,
+			activeIndex: 2,
+			activeIndexByFamily: { codex: 2 },
+			accounts: [
+				{
+					email: "a@example.com",
+					accountId: "acc_a",
+					refreshToken: "refresh-a",
+					accessToken: "access-a",
+					expiresAt: now + 3_600_000,
+					addedAt: now - 3_000,
+					lastUsed: now - 3_000,
+					enabled: true,
+				},
+				{
+					email: "b@example.com",
+					accountId: "acc_b",
+					refreshToken: "refresh-b",
+					accessToken: "access-b",
+					expiresAt: now + 3_600_000,
+					addedAt: now - 2_000,
+					lastUsed: now - 2_000,
+					enabled: true,
+				},
+				{
+					email: "c@example.com",
+					accountId: "acc_c",
+					refreshToken: "refresh-c",
+					accessToken: "access-c",
+					expiresAt: now + 3_600_000,
+					addedAt: now - 1_000,
+					lastUsed: now - 1_000,
+					enabled: true,
+				},
+			],
+		};
+		loadAccountsMock.mockResolvedValue(storage);
+		loadDashboardDisplaySettingsMock.mockResolvedValue({
+			showPerAccountRows: true,
+			showQuotaDetails: true,
+			showForecastReasons: true,
+			showRecommendations: true,
+			showLiveProbeNotes: true,
+			menuAutoFetchLimits: false,
+			menuSortEnabled: true,
+			menuSortMode: "ready-first",
+			menuSortPinCurrent: true,
+			menuSortQuickSwitchVisibleRow: true,
+		});
+		loadQuotaCacheMock.mockResolvedValue({
+			byAccountId: {},
+			byEmail: {
+				"a@example.com": {
+					updatedAt: now,
+					status: 200,
+					model: "gpt-5-codex",
+					primary: { usedPercent: 80, windowMinutes: 300, resetAtMs: now + 1_000 },
+					secondary: { usedPercent: 80, windowMinutes: 10080, resetAtMs: now + 2_000 },
+				},
+				"b@example.com": {
+					updatedAt: now,
+					status: 200,
+					model: "gpt-5-codex",
+					primary: { usedPercent: 0, windowMinutes: 300, resetAtMs: now + 1_000 },
+					secondary: { usedPercent: 0, windowMinutes: 10080, resetAtMs: now + 2_000 },
+				},
+				"c@example.com": {
+					updatedAt: now,
+					status: 200,
+					model: "gpt-5-codex",
+					primary: { usedPercent: 60, windowMinutes: 300, resetAtMs: now + 1_000 },
+					secondary: { usedPercent: 60, windowMinutes: 10080, resetAtMs: now + 2_000 },
+				},
+			},
+		});
+		promptLoginModeMock.mockResolvedValueOnce({ mode: "cancel" });
+
+		const { runCodexMultiAuthCli } = await import("../lib/codex-manager.js");
+		const exitCode = await runCodexMultiAuthCli(["auth", "login"]);
+
+		expect(exitCode).toBe(0);
+		const firstCallAccounts = promptLoginModeMock.mock.calls[0]?.[0] as Array<{
+			email?: string;
+			index: number;
+			sourceIndex?: number;
+			quickSwitchNumber?: number;
+			isCurrentAccount?: boolean;
+		}>;
+		expect(firstCallAccounts.map((account) => account.email)).toEqual([
+			"b@example.com",
+			"c@example.com",
+			"a@example.com",
+		]);
+		expect(firstCallAccounts.map((account) => account.index)).toEqual([0, 1, 2]);
+		expect(firstCallAccounts.map((account) => account.sourceIndex)).toEqual([1, 2, 0]);
+		expect(firstCallAccounts.map((account) => account.quickSwitchNumber)).toEqual([1, 2, 3]);
+		expect(firstCallAccounts[0]?.isCurrentAccount).toBe(false);
+		expect(firstCallAccounts[1]?.isCurrentAccount).toBe(true);
+	});
+
+	it("uses source-number quick switch mapping when visible-row quick switch is disabled", async () => {
+		const now = Date.now();
+		loadAccountsMock.mockResolvedValue({
+			version: 3,
+			activeIndex: 0,
+			activeIndexByFamily: { codex: 0 },
+			accounts: [
+				{
+					email: "a@example.com",
+					accountId: "acc_a",
+					refreshToken: "refresh-a",
+					accessToken: "access-a",
+					expiresAt: now + 3_600_000,
+					addedAt: now - 1_000,
+					lastUsed: now - 1_000,
+					enabled: true,
+				},
+				{
+					email: "b@example.com",
+					accountId: "acc_b",
+					refreshToken: "refresh-b",
+					accessToken: "access-b",
+					expiresAt: now + 3_600_000,
+					addedAt: now - 2_000,
+					lastUsed: now - 2_000,
+					enabled: true,
+				},
+			],
+		});
+		loadDashboardDisplaySettingsMock.mockResolvedValue({
+			showPerAccountRows: true,
+			showQuotaDetails: true,
+			showForecastReasons: true,
+			showRecommendations: true,
+			showLiveProbeNotes: true,
+			menuAutoFetchLimits: false,
+			menuSortEnabled: true,
+			menuSortMode: "ready-first",
+			menuSortPinCurrent: false,
+			menuSortQuickSwitchVisibleRow: false,
+		});
+		loadQuotaCacheMock.mockResolvedValue({
+			byAccountId: {},
+			byEmail: {
+				"a@example.com": {
+					updatedAt: now,
+					status: 200,
+					model: "gpt-5-codex",
+					primary: { usedPercent: 80, windowMinutes: 300, resetAtMs: now + 1_000 },
+					secondary: { usedPercent: 80, windowMinutes: 10080, resetAtMs: now + 2_000 },
+				},
+				"b@example.com": {
+					updatedAt: now,
+					status: 200,
+					model: "gpt-5-codex",
+					primary: { usedPercent: 0, windowMinutes: 300, resetAtMs: now + 1_000 },
+					secondary: { usedPercent: 0, windowMinutes: 10080, resetAtMs: now + 2_000 },
+				},
+			},
+		});
+		promptLoginModeMock.mockResolvedValueOnce({ mode: "cancel" });
+
+		const { runCodexMultiAuthCli } = await import("../lib/codex-manager.js");
+		const exitCode = await runCodexMultiAuthCli(["auth", "login"]);
+
+		expect(exitCode).toBe(0);
+		const firstCallAccounts = promptLoginModeMock.mock.calls[0]?.[0] as Array<{
+			email?: string;
+			quickSwitchNumber?: number;
+		}>;
+		expect(firstCallAccounts.map((account) => account.email)).toEqual([
+			"b@example.com",
+			"a@example.com",
+		]);
+		expect(firstCallAccounts.map((account) => account.quickSwitchNumber)).toEqual([2, 1]);
+	});
+
+	it("runs doctor command in json mode", async () => {
+		const now = Date.now();
+		loadAccountsMock.mockResolvedValueOnce({
+			version: 3,
+			activeIndex: 0,
+			activeIndexByFamily: { codex: 0 },
+			accounts: [
+				{
+					email: "real@example.net",
+					refreshToken: "refresh-a",
+					addedAt: now - 1_000,
+					lastUsed: now - 1_000,
+				},
+			],
+		});
+
+		const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+		const { runCodexMultiAuthCli } = await import("../lib/codex-manager.js");
+
+		const exitCode = await runCodexMultiAuthCli(["auth", "doctor", "--json"]);
+		expect(exitCode).toBe(0);
+
+		const payload = JSON.parse(String(logSpy.mock.calls[0]?.[0])) as {
+			command: string;
+			summary: { ok: number; warn: number; error: number };
+			checks: Array<{ key: string }>;
+		};
+		expect(payload.command).toBe("doctor");
+		expect(payload.summary.error).toBe(0);
+		expect(payload.checks.some((check) => check.key === "active-index")).toBe(true);
+	});
+
+	it("runs doctor --fix in dry-run mode", async () => {
+		const now = Date.now();
+		loadAccountsMock.mockResolvedValueOnce({
+			version: 3,
+			activeIndex: 4,
+			activeIndexByFamily: { codex: 4 },
+			accounts: [
+				{
+					email: "account1@example.com",
+					accessToken: "access-a",
+					refreshToken: "refresh-a",
+					addedAt: now - 1_000,
+					lastUsed: now - 1_000,
+					enabled: false,
+				},
+				{
+					email: "account2@example.com",
+					accessToken: "access-b",
+					refreshToken: "refresh-a",
+					addedAt: now - 1_000,
+					lastUsed: now - 1_000,
+					enabled: false,
+				},
+			],
+		});
+
+		const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+		const { runCodexMultiAuthCli } = await import("../lib/codex-manager.js");
+		const exitCode = await runCodexMultiAuthCli(["auth", "doctor", "--fix", "--dry-run", "--json"]);
+
+		expect(exitCode).toBe(0);
+		expect(saveAccountsMock).not.toHaveBeenCalled();
+		const payload = JSON.parse(String(logSpy.mock.calls[0]?.[0])) as {
+			fix: { enabled: boolean; dryRun: boolean; changed: boolean; actions: Array<{ key: string }> };
+		};
+		expect(payload.fix.enabled).toBe(true);
+		expect(payload.fix.dryRun).toBe(true);
+		expect(payload.fix.changed).toBe(true);
+		expect(payload.fix.actions.length).toBeGreaterThan(0);
+	});
+
+	it("runs report command in json mode", async () => {
+		const now = Date.now();
+		loadAccountsMock.mockResolvedValueOnce({
+			version: 3,
+			activeIndex: 0,
+			activeIndexByFamily: { codex: 0 },
+			accounts: [
+				{
+					email: "real@example.net",
+					refreshToken: "refresh-a",
+					addedAt: now - 1_000,
+					lastUsed: now - 1_000,
+					enabled: true,
+				},
+				{
+					email: "other@example.net",
+					refreshToken: "refresh-b",
+					addedAt: now - 1_000,
+					lastUsed: now - 1_000,
+					enabled: false,
+				},
+			],
+		});
+
+		const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+		const { runCodexMultiAuthCli } = await import("../lib/codex-manager.js");
+		const exitCode = await runCodexMultiAuthCli(["auth", "report", "--json"]);
+
+		expect(exitCode).toBe(0);
+		const payload = JSON.parse(String(logSpy.mock.calls[0]?.[0])) as {
+			command: string;
+			accounts: { total: number; enabled: number; disabled: number };
+		};
+		expect(payload.command).toBe("report");
+		expect(payload.accounts.total).toBe(2);
+		expect(payload.accounts.enabled).toBe(1);
+		expect(payload.accounts.disabled).toBe(1);
+	});
+
+	it("drives interactive settings hub across sections and persists dashboard/backend changes", async () => {
+		setInteractiveTTY(true);
+		const now = Date.now();
+		const storage = {
+			version: 3,
+			activeIndex: 0,
+			activeIndexByFamily: { codex: 0 },
+			accounts: [
+				{
+					email: "settings@example.com",
+					accountId: "acc_settings",
+					refreshToken: "refresh-settings",
+					accessToken: "access-settings",
+					expiresAt: now + 3_600_000,
+					addedAt: now - 1_000,
+					lastUsed: now - 1_000,
+					enabled: true,
+				},
+			],
+		};
+		loadAccountsMock.mockImplementation(async () => structuredClone(storage));
+		promptLoginModeMock
+			.mockResolvedValueOnce({ mode: "settings" })
+			.mockResolvedValueOnce({ mode: "cancel" });
+
+		const selectResults: Array<Record<string, unknown>> = [
+			{ type: "account-list" },
+			{ type: "toggle", key: "menuShowStatusBadge" },
+			{ type: "cycle-sort-mode" },
+			{ type: "cycle-layout-mode" },
+			{ type: "save" },
+			{ type: "summary-fields" },
+			{ type: "move-down", key: "last-used" },
+			{ type: "toggle", key: "status" },
+			{ type: "save" },
+			{ type: "behavior" },
+			{ type: "toggle-pause" },
+			{ type: "toggle-menu-limit-fetch" },
+			{ type: "set-menu-quota-ttl", ttlMs: 300_000 },
+			{ type: "set-delay", delayMs: 1_000 },
+			{ type: "save" },
+			{ type: "theme" },
+			{ type: "set-palette", palette: "blue" },
+			{ type: "set-accent", accent: "cyan" },
+			{ type: "save" },
+			{ type: "backend" },
+			{ type: "open-category", key: "rotation-quota" },
+			{ type: "toggle", key: "preemptiveQuotaEnabled" },
+			{ type: "bump", key: "preemptiveQuotaRemainingPercent5h", direction: 1 },
+			{ type: "back" },
+			{ type: "save" },
+			{ type: "back" },
+		];
+		selectMock.mockImplementation(async () => selectResults.shift() ?? { type: "back" });
+		const { runCodexMultiAuthCli } = await import("../lib/codex-manager.js");
+
+		const exitCode = await runCodexMultiAuthCli(["auth", "login"]);
+		expect(exitCode).toBe(0);
+		expect(selectResults).toHaveLength(0);
+		expect(saveDashboardDisplaySettingsMock).toHaveBeenCalled();
+		expect(savePluginConfigMock).toHaveBeenCalledTimes(1);
+		expect(savePluginConfigMock).toHaveBeenCalledWith(
+			expect.objectContaining({
+				preemptiveQuotaEnabled: expect.any(Boolean),
+				preemptiveQuotaRemainingPercent5h: expect.any(Number),
+			}),
+		);
+	});
+
+	it("keeps last account enabled during fix to avoid lockout", async () => {
+		const now = Date.now();
+		loadAccountsMock.mockResolvedValueOnce({
+			version: 3,
+			activeIndex: 0,
+			activeIndexByFamily: { codex: 0 },
+			accounts: [
+				{
+					email: "solo@example.com",
+					refreshToken: "refresh-solo",
+					addedAt: now - 1_000,
+					lastUsed: now - 1_000,
+					enabled: true,
+				},
+			],
+		});
+		queuedRefreshMock.mockResolvedValueOnce({
+			type: "failed",
+			reason: "http_error",
+			statusCode: 401,
+			message: "unauthorized",
+		});
+		const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+		const { runCodexMultiAuthCli } = await import("../lib/codex-manager.js");
+
+		const exitCode = await runCodexMultiAuthCli(["auth", "fix", "--json"]);
+		expect(exitCode).toBe(0);
+		expect(saveAccountsMock).toHaveBeenCalledTimes(1);
+		expect(saveAccountsMock.mock.calls[0]?.[0]?.accounts?.[0]?.enabled).toBe(true);
+
+		const payload = JSON.parse(String(logSpy.mock.calls[0]?.[0])) as {
+			reports: Array<{ outcome: string; message: string }>;
+		};
+		expect(payload.reports[0]?.outcome).toBe("warning-soft-failure");
+		expect(payload.reports[0]?.message).toContain("avoid lockout");
+	});
+
+	it("runs live fix path with probe success and probe fallback warning", async () => {
+		const now = Date.now();
+		loadAccountsMock.mockResolvedValueOnce({
+			version: 3,
+			activeIndex: 0,
+			activeIndexByFamily: { codex: 0 },
+			accounts: [
+				{
+					email: "live-ok@example.com",
+					accountId: "acc_live_ok",
+					refreshToken: "refresh-live-ok",
+					accessToken: "access-live-ok",
+					expiresAt: now + 3_600_000,
+					addedAt: now - 5_000,
+					lastUsed: now - 5_000,
+					enabled: true,
+				},
+				{
+					email: "live-warn@example.com",
+					accountId: "acc_live_warn",
+					refreshToken: "refresh-live-warn",
+					accessToken: "access-live-warn",
+					expiresAt: now - 5_000,
+					addedAt: now - 4_000,
+					lastUsed: now - 4_000,
+					enabled: true,
+				},
+			],
+		});
+		queuedRefreshMock.mockResolvedValueOnce({
+			type: "success",
+			access: "access-live-warn-next",
+			refresh: "refresh-live-warn-next",
+			expires: now + 7_200_000,
+		});
+		fetchCodexQuotaSnapshotMock
+			.mockResolvedValueOnce({
+				status: 200,
+				model: "gpt-5-codex",
+				primary: { usedPercent: 20, windowMinutes: 300, resetAtMs: now + 1_000 },
+				secondary: { usedPercent: 10, windowMinutes: 10080, resetAtMs: now + 2_000 },
+			})
+			.mockRejectedValueOnce(new Error("live probe temporary failure"));
+
+		const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+		const { runCodexMultiAuthCli } = await import("../lib/codex-manager.js");
+		const exitCode = await runCodexMultiAuthCli(["auth", "fix", "--live", "--json"]);
+
+		expect(exitCode).toBe(0);
+		expect(fetchCodexQuotaSnapshotMock).toHaveBeenCalledTimes(2);
+		expect(queuedRefreshMock).toHaveBeenCalledTimes(1);
+		expect(saveQuotaCacheMock).toHaveBeenCalledTimes(1);
+
+		const payload = JSON.parse(String(logSpy.mock.calls[0]?.[0])) as {
+			reports: Array<{ outcome: string; message: string }>;
+		};
+		expect(
+			payload.reports.some(
+				(report) =>
+					report.outcome === "healthy" &&
+					report.message.includes("live session OK"),
+			),
+		).toBe(true);
+		expect(
+			payload.reports.some(
+				(report) =>
+					report.outcome === "warning-soft-failure" &&
+					report.message.includes("refresh succeeded but live probe failed"),
+			),
+		).toBe(true);
+	});
+
+	it("deletes an account from manage mode and persists storage", async () => {
+		const now = Date.now();
+		loadAccountsMock.mockResolvedValue({
+			version: 3,
+			activeIndex: 0,
+			activeIndexByFamily: { codex: 0 },
+			accounts: [
+				{
+					email: "first@example.com",
+					refreshToken: "refresh-first",
+					addedAt: now - 2_000,
+					lastUsed: now - 2_000,
+					enabled: true,
+				},
+				{
+					email: "second@example.com",
+					refreshToken: "refresh-second",
+					addedAt: now - 1_000,
+					lastUsed: now - 1_000,
+					enabled: true,
+				},
+			],
+		});
+		promptLoginModeMock
+			.mockResolvedValueOnce({ mode: "manage", deleteAccountIndex: 1 })
+			.mockResolvedValueOnce({ mode: "cancel" });
+
+		const { runCodexMultiAuthCli } = await import("../lib/codex-manager.js");
+		const exitCode = await runCodexMultiAuthCli(["auth", "login"]);
+
+		expect(exitCode).toBe(0);
+		expect(saveAccountsMock).toHaveBeenCalledTimes(1);
+		expect(saveAccountsMock.mock.calls[0]?.[0]?.accounts).toHaveLength(1);
+		expect(saveAccountsMock.mock.calls[0]?.[0]?.accounts?.[0]?.email).toBe("first@example.com");
+	});
+
+	it("toggles account enabled state from manage mode", async () => {
+		const now = Date.now();
+		loadAccountsMock.mockResolvedValue({
+			version: 3,
+			activeIndex: 0,
+			activeIndexByFamily: { codex: 0 },
+			accounts: [
+				{
+					email: "toggle@example.com",
+					refreshToken: "refresh-toggle",
+					addedAt: now - 1_000,
+					lastUsed: now - 1_000,
+					enabled: true,
+				},
+			],
+		});
+		promptLoginModeMock
+			.mockResolvedValueOnce({ mode: "manage", toggleAccountIndex: 0 })
+			.mockResolvedValueOnce({ mode: "cancel" });
+
+		const { runCodexMultiAuthCli } = await import("../lib/codex-manager.js");
+		const exitCode = await runCodexMultiAuthCli(["auth", "login"]);
+
+		expect(exitCode).toBe(0);
+		expect(saveAccountsMock).toHaveBeenCalledTimes(1);
+		expect(saveAccountsMock.mock.calls[0]?.[0]?.accounts?.[0]?.enabled).toBe(false);
+	});
+
+	it("keeps settings unchanged in non-interactive mode and returns to menu", async () => {
+		const now = Date.now();
+		loadAccountsMock.mockResolvedValue({
+			version: 3,
+			activeIndex: 0,
+			activeIndexByFamily: { codex: 0 },
+			accounts: [
+				{
+					email: "non-tty@example.com",
+					accountId: "acc_non_tty",
+					refreshToken: "refresh-non-tty",
+					accessToken: "access-non-tty",
+					expiresAt: now + 3_600_000,
+					addedAt: now - 1_000,
+					lastUsed: now - 1_000,
+					enabled: true,
+				},
+			],
+		});
+		promptLoginModeMock
+			.mockResolvedValueOnce({ mode: "settings" })
+			.mockResolvedValueOnce({ mode: "cancel" });
+
+		const { runCodexMultiAuthCli } = await import("../lib/codex-manager.js");
+		const exitCode = await runCodexMultiAuthCli(["auth", "login"]);
+
+		expect(exitCode).toBe(0);
+		expect(selectMock).not.toHaveBeenCalled();
+		expect(saveDashboardDisplaySettingsMock).not.toHaveBeenCalled();
+		expect(savePluginConfigMock).not.toHaveBeenCalled();
+	});
+});
diff --git a/test/codex-prompts.test.ts b/test/codex-prompts.test.ts
index 6801eff7..17131b8f 100644
--- a/test/codex-prompts.test.ts
+++ b/test/codex-prompts.test.ts
@@ -3,6 +3,7 @@ import { promises as fs } from "node:fs";
 import path from "node:path";
 
 vi.mock("node:fs", () => ({
+	existsSync: vi.fn(() => false),
 	promises: {
 		readFile: vi.fn(),
 		writeFile: vi.fn(),
diff --git a/test/codex-routing.test.ts b/test/codex-routing.test.ts
new file mode 100644
index 00000000..079d0944
--- /dev/null
+++ b/test/codex-routing.test.ts
@@ -0,0 +1,19 @@
+import { describe, expect, it } from "vitest";
+import { normalizeAuthAlias, shouldHandleMultiAuthAuth } from "../scripts/codex-routing.js";
+
+describe("codex routing helpers", () => {
+	it("normalizes supported auth aliases", () => {
+		expect(normalizeAuthAlias(["multi", "auth", "status"])).toEqual(["auth", "status"]);
+		expect(normalizeAuthAlias(["multi-auth", "login"])).toEqual(["auth", "login"]);
+		expect(normalizeAuthAlias(["multiauth", "list"])).toEqual(["auth", "list"]);
+		expect(normalizeAuthAlias(["auth", "check"])).toEqual(["auth", "check"]);
+	});
+
+	it("routes only known auth subcommands to multi-auth runner", () => {
+		expect(shouldHandleMultiAuthAuth(["auth"])).toBe(true);
+		expect(shouldHandleMultiAuthAuth(["auth", "login"])).toBe(true);
+		expect(shouldHandleMultiAuthAuth(["auth", "--help"])).toBe(true);
+		expect(shouldHandleMultiAuthAuth(["auth", "unknown-subcommand"])).toBe(false);
+		expect(shouldHandleMultiAuthAuth(["status"])).toBe(false);
+	});
+});
diff --git a/test/dashboard-settings.test.ts b/test/dashboard-settings.test.ts
new file mode 100644
index 00000000..ce064224
--- /dev/null
+++ b/test/dashboard-settings.test.ts
@@ -0,0 +1,211 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { promises as fs } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+describe("dashboard settings", () => {
+	let tempDir: string;
+	let originalDir: string | undefined;
+
+	beforeEach(async () => {
+		originalDir = process.env.CODEX_MULTI_AUTH_DIR;
+		tempDir = await fs.mkdtemp(join(tmpdir(), "codex-multi-auth-dashboard-"));
+		process.env.CODEX_MULTI_AUTH_DIR = tempDir;
+		vi.resetModules();
+	});
+
+	afterEach(async () => {
+		if (originalDir === undefined) {
+			delete process.env.CODEX_MULTI_AUTH_DIR;
+		} else {
+			process.env.CODEX_MULTI_AUTH_DIR = originalDir;
+		}
+		await fs.rm(tempDir, { recursive: true, force: true });
+	});
+
+	it("loads defaults when settings file does not exist", async () => {
+		const { loadDashboardDisplaySettings, DEFAULT_DASHBOARD_DISPLAY_SETTINGS } = await import(
+			"../lib/dashboard-settings.js"
+		);
+
+		const settings = await loadDashboardDisplaySettings();
+		expect(settings).toEqual(DEFAULT_DASHBOARD_DISPLAY_SETTINGS);
+	});
+
+	it("saves and reloads settings", async () => {
+		const {
+			saveDashboardDisplaySettings,
+			loadDashboardDisplaySettings,
+			getDashboardSettingsPath,
+		} = await import("../lib/dashboard-settings.js");
+
+		await saveDashboardDisplaySettings({
+			showPerAccountRows: false,
+			showQuotaDetails: true,
+			showForecastReasons: false,
+			showRecommendations: true,
+			showLiveProbeNotes: false,
+			actionAutoReturnMs: 1_000,
+			actionPauseOnKey: false,
+			uiThemePreset: "blue",
+			uiAccentColor: "cyan",
+		});
+
+		const reloaded = await loadDashboardDisplaySettings();
+		expect(reloaded).toEqual({
+			showPerAccountRows: false,
+			showQuotaDetails: true,
+			showForecastReasons: false,
+			showRecommendations: true,
+			showLiveProbeNotes: false,
+			actionAutoReturnMs: 1_000,
+			actionPauseOnKey: false,
+			menuAutoFetchLimits: true,
+			menuSortEnabled: true,
+			menuSortMode: "ready-first",
+			menuSortPinCurrent: false,
+			menuSortQuickSwitchVisibleRow: true,
+			uiThemePreset: "blue",
+			uiAccentColor: "cyan",
+			menuShowStatusBadge: true,
+			menuShowCurrentBadge: true,
+			menuShowLastUsed: true,
+			menuShowQuotaSummary: true,
+			menuShowQuotaCooldown: true,
+			menuShowFetchStatus: true,
+			menuShowDetailsForUnselectedRows: false,
+			menuLayoutMode: "compact-details",
+			menuQuotaTtlMs: 300_000,
+			menuFocusStyle: "row-invert",
+			menuHighlightCurrentRow: true,
+			menuStatuslineFields: ["last-used", "limits", "status"],
+		});
+
+		const content = await fs.readFile(getDashboardSettingsPath(), "utf8");
+		expect(content).toContain("\"version\": 1");
+		expect(content).toContain("\"dashboardDisplaySettings\"");
+		expect(content).not.toContain("\"settings\":");
+	});
+
+	it("preserves plugin config section when saving dashboard settings", async () => {
+		const { saveUnifiedPluginConfig } = await import("../lib/unified-settings.js");
+		const {
+			saveDashboardDisplaySettings,
+			getDashboardSettingsPath,
+		} = await import("../lib/dashboard-settings.js");
+
+		await saveUnifiedPluginConfig({ codexMode: false });
+		await saveDashboardDisplaySettings({
+			showPerAccountRows: true,
+			showQuotaDetails: true,
+			showForecastReasons: true,
+			showRecommendations: true,
+			showLiveProbeNotes: true,
+		});
+
+		const content = await fs.readFile(getDashboardSettingsPath(), "utf8");
+		expect(content).toContain("\"pluginConfig\"");
+		expect(content).toContain("\"codexMode\": false");
+		expect(content).toContain("\"dashboardDisplaySettings\"");
+	});
+
+	it("migrates legacy dashboard-settings.json into unified settings", async () => {
+		const {
+			loadDashboardDisplaySettings,
+			getDashboardSettingsPath,
+		} = await import("../lib/dashboard-settings.js");
+
+		const legacyPath = join(tempDir, "dashboard-settings.json");
+		await fs.writeFile(
+			legacyPath,
+			JSON.stringify({
+				settings: {
+					showPerAccountRows: false,
+					showQuotaDetails: false,
+					menuShowQuotaSummary: false,
+					menuLayoutMode: "expanded-rows",
+				},
+			}),
+			"utf-8",
+		);
+
+		const migrated = await loadDashboardDisplaySettings();
+		expect(migrated.showPerAccountRows).toBe(false);
+		expect(migrated.showQuotaDetails).toBe(false);
+		expect(migrated.menuShowQuotaSummary).toBe(false);
+		expect(migrated.menuLayoutMode).toBe("expanded-rows");
+
+		const unifiedContent = await fs.readFile(getDashboardSettingsPath(), "utf8");
+		expect(unifiedContent).toContain("\"dashboardDisplaySettings\"");
+		expect(unifiedContent).toContain("\"showPerAccountRows\": false");
+	});
+
+	it("falls back to defaults when legacy file read fails", async () => {
+		const { loadDashboardDisplaySettings, DEFAULT_DASHBOARD_DISPLAY_SETTINGS } = await import(
+			"../lib/dashboard-settings.js"
+		);
+
+		const legacyPath = join(tempDir, "dashboard-settings.json");
+		await fs.writeFile(legacyPath, JSON.stringify({ settings: { showPerAccountRows: false } }), "utf8");
+
+		const error = Object.assign(new Error("permission denied"), { code: "EACCES" });
+		const readSpy = vi.spyOn(fs, "readFile").mockRejectedValueOnce(error);
+
+		const loaded = await loadDashboardDisplaySettings();
+		expect(loaded).toEqual(DEFAULT_DASHBOARD_DISPLAY_SETTINGS);
+		readSpy.mockRestore();
+	});
+
+	it("falls back to defaults when legacy file contains malformed JSON", async () => {
+		const { loadDashboardDisplaySettings, DEFAULT_DASHBOARD_DISPLAY_SETTINGS } = await import(
+			"../lib/dashboard-settings.js"
+		);
+		const legacyPath = join(tempDir, "dashboard-settings.json");
+		await fs.writeFile(legacyPath, "{ malformed", "utf8");
+
+		const loaded = await loadDashboardDisplaySettings();
+		expect(loaded).toEqual(DEFAULT_DASHBOARD_DISPLAY_SETTINGS);
+	});
+
+	it("retries transient EBUSY reads for legacy settings and succeeds", async () => {
+		const { loadDashboardDisplaySettings } = await import("../lib/dashboard-settings.js");
+		const legacyPath = join(tempDir, "dashboard-settings.json");
+		const payload = JSON.stringify({
+			settings: {
+				showPerAccountRows: false,
+				menuShowQuotaSummary: false,
+			},
+		});
+		await fs.writeFile(legacyPath, payload, "utf8");
+
+		const originalReadFile = fs.readFile.bind(fs);
+		const readSpy = vi.spyOn(fs, "readFile");
+		const busy = Object.assign(new Error("busy"), { code: "EBUSY" });
+		readSpy
+			.mockRejectedValueOnce(busy)
+			.mockImplementation(async (...args) => originalReadFile(...args));
+
+		const loaded = await loadDashboardDisplaySettings();
+		expect(loaded.showPerAccountRows).toBe(false);
+		expect(loaded.menuShowQuotaSummary).toBe(false);
+		expect(readSpy).toHaveBeenCalled();
+		readSpy.mockRestore();
+	});
+
+	it("falls back to defaults when retryable legacy reads keep failing", async () => {
+		const { loadDashboardDisplaySettings, DEFAULT_DASHBOARD_DISPLAY_SETTINGS } = await import(
+			"../lib/dashboard-settings.js"
+		);
+		const legacyPath = join(tempDir, "dashboard-settings.json");
+		await fs.writeFile(legacyPath, JSON.stringify({ settings: { showPerAccountRows: false } }), "utf8");
+
+		const readSpy = vi.spyOn(fs, "readFile");
+		const locked = Object.assign(new Error("locked"), { code: "EPERM" });
+		readSpy.mockRejectedValue(locked);
+
+		const loaded = await loadDashboardDisplaySettings();
+		expect(loaded).toEqual(DEFAULT_DASHBOARD_DISPLAY_SETTINGS);
+		expect(readSpy).toHaveBeenCalledTimes(4);
+		readSpy.mockRestore();
+	});
+});
diff --git a/test/entitlement-cache.test.ts b/test/entitlement-cache.test.ts
new file mode 100644
index 00000000..91bfacaf
--- /dev/null
+++ b/test/entitlement-cache.test.ts
@@ -0,0 +1,73 @@
+import { describe, expect, it } from "vitest";
+import { EntitlementCache, resolveEntitlementAccountKey } from "../lib/entitlement-cache.js";
+
+describe("entitlement cache", () => {
+	it("resolves account key priority", () => {
+		expect(
+			resolveEntitlementAccountKey({
+				accountId: "acc_123",
+				email: "user@example.com",
+				index: 2,
+			}),
+		).toBe("id:acc_123");
+		expect(resolveEntitlementAccountKey({ email: "User@Example.com", index: 5 })).toBe(
+			"email:user@example.com",
+		);
+		expect(resolveEntitlementAccountKey({ index: 7 })).toBe("idx:7");
+	});
+
+	it("marks model block and expires after ttl", () => {
+		const cache = new EntitlementCache();
+		const accountKey = "id:acc_1";
+		cache.markBlocked(accountKey, "gpt-5.3-codex", "unsupported-model", 500, 1_000);
+
+		const blockedNow = cache.isBlocked(accountKey, "gpt-5.3-codex", 1_100);
+		expect(blockedNow.blocked).toBe(true);
+		expect(blockedNow.reason).toBe("unsupported-model");
+		expect(blockedNow.waitMs).toBeGreaterThan(0);
+
+		const blockedLater = cache.isBlocked(accountKey, "gpt-5.3-codex", 2_200);
+		expect(blockedLater.blocked).toBe(false);
+		expect(blockedLater.waitMs).toBe(0);
+	});
+
+	it("clears model or full account block", () => {
+		const cache = new EntitlementCache();
+		const accountKey = "email:person@example.com";
+		cache.markBlocked(accountKey, "gpt-5-codex", "plan-entitlement", 5_000, 2_000);
+		cache.markBlocked(accountKey, "gpt-5.3-codex", "unsupported-model", 5_000, 2_000);
+
+		cache.clear(accountKey, "gpt-5-codex");
+		expect(cache.isBlocked(accountKey, "gpt-5-codex", 2_500).blocked).toBe(false);
+		expect(cache.isBlocked(accountKey, "gpt-5.3-codex", 2_500).blocked).toBe(true);
+
+		cache.clear(accountKey);
+		expect(cache.isBlocked(accountKey, "gpt-5.3-codex", 2_500).blocked).toBe(false);
+	});
+
+	it("normalizes invalid ttl values to default minimum behavior", () => {
+		const cache = new EntitlementCache();
+		const accountKey = "id:ttl-invalid";
+		cache.markBlocked(accountKey, "gpt-5-codex", "plan-entitlement", Number.NaN, 1_000);
+
+		const blocked = cache.isBlocked(accountKey, "gpt-5-codex", 2_000);
+		expect(blocked.blocked).toBe(true);
+		expect(blocked.waitMs).toBeGreaterThan(0);
+	});
+
+	it("returns immutable snapshot entries", () => {
+		const cache = new EntitlementCache();
+		const accountKey = "id:snapshot";
+		cache.markBlocked(accountKey, "gpt-5-codex", "plan-entitlement", 5_000, 1_000);
+
+		const snapshot = cache.snapshot(1_500);
+		expect(snapshot.accounts[accountKey]).toHaveLength(1);
+		if (!snapshot.accounts[accountKey]) {
+			throw new Error("missing snapshot account entry");
+		}
+
+		snapshot.accounts[accountKey][0].model = "tampered-model";
+		const fresh = cache.snapshot(1_500);
+		expect(fresh.accounts[accountKey]?.[0]?.model).toBe("gpt-5-codex");
+	});
+});
diff --git a/test/failure-policy.test.ts b/test/failure-policy.test.ts
new file mode 100644
index 00000000..bdcb404f
--- /dev/null
+++ b/test/failure-policy.test.ts
@@ -0,0 +1,196 @@
+import { describe, expect, it } from "vitest";
+import { evaluateFailurePolicy } from "../lib/request/failure-policy.js";
+
+describe("failure policy", () => {
+	it.each([
+		[0, false],
+		[2, false],
+		[3, true],
+	] as const)(
+		"handles auth-refresh removal boundary for failures=%s",
+		(consecutiveAuthFailures, removeAccount) => {
+			const decision = evaluateFailurePolicy({
+				kind: "auth-refresh",
+				consecutiveAuthFailures,
+				maxAuthFailuresBeforeRemoval: 3,
+			});
+			expect(decision.removeAccount).toBe(removeAccount);
+			expect(decision.rotateAccount).toBe(true);
+			expect(decision.handoffStrategy).toBe("hard");
+		},
+	);
+
+	it("removes account when auth refresh failures exceed threshold", () => {
+		const decision = evaluateFailurePolicy({
+			kind: "auth-refresh",
+			consecutiveAuthFailures: 3,
+			maxAuthFailuresBeforeRemoval: 3,
+		});
+
+		expect(decision.removeAccount).toBe(true);
+		expect(decision.cooldownReason).toBe("auth-failure");
+	});
+
+	it("applies configured network cooldown and rotates", () => {
+		const decision = evaluateFailurePolicy(
+			{ kind: "network" },
+			{ networkCooldownMs: 9_000 },
+		);
+
+		expect(decision.rotateAccount).toBe(true);
+		expect(decision.refundToken).toBe(true);
+		expect(decision.cooldownMs).toBe(9_000);
+		expect(decision.cooldownReason).toBe("network-error");
+	});
+
+	it("retries same account in balanced network mode", () => {
+		const decision = evaluateFailurePolicy(
+			{ kind: "network", failoverMode: "balanced" },
+			{ networkCooldownMs: 9_000 },
+		);
+
+		expect(decision.retrySameAccount).toBe(true);
+		expect(decision.retryDelayMs).toBe(250);
+		expect(decision.rotateAccount).toBe(false);
+		expect(decision.handoffStrategy).toBe("soft");
+	});
+
+	it("retries same account for conservative server failures without retry-after", () => {
+		const decision = evaluateFailurePolicy(
+			{ kind: "server", failoverMode: "conservative" },
+			{ serverCooldownMs: 4_000 },
+		);
+
+		expect(decision.retrySameAccount).toBe(true);
+		expect(decision.retryDelayMs).toBe(500);
+		expect(decision.rotateAccount).toBe(false);
+		expect(decision.handoffStrategy).toBe("hard");
+	});
+
+	it("marks rate limit without cooldown mutation", () => {
+		const decision = evaluateFailurePolicy({ kind: "rate-limit" });
+
+		expect(decision.markRateLimited).toBe(true);
+		expect(decision.refundToken).toBe(false);
+		expect(decision.cooldownMs).toBeUndefined();
+	});
+
+	it("rotates immediately in aggressive empty-response mode", () => {
+		const decision = evaluateFailurePolicy({
+			kind: "empty-response",
+			failoverMode: "aggressive",
+		});
+
+		expect(decision.retrySameAccount).toBe(false);
+		expect(decision.rotateAccount).toBe(true);
+		expect(decision.handoffStrategy).toBe("soft");
+	});
+
+	it.each([
+		["aggressive", false, undefined],
+		["balanced", true, 250],
+		["conservative", true, 900],
+	] as const)(
+		"applies network mode matrix for %s",
+		(mode, retrySameAccount, retryDelayMs) => {
+			const decision = evaluateFailurePolicy({
+				kind: "network",
+				failoverMode: mode,
+			});
+
+			expect(decision.retrySameAccount).toBe(retrySameAccount);
+			expect(decision.retryDelayMs).toBe(retryDelayMs);
+			expect(decision.rotateAccount).toBe(!retrySameAccount);
+			expect(decision.handoffStrategy).toBe("soft");
+		},
+	);
+
+	it.each([
+		["aggressive", false, undefined, true],
+		["balanced", false, undefined, true],
+		["conservative", true, 500, false],
+	] as const)(
+		"applies server mode matrix for %s",
+		(mode, retrySameAccount, retryDelayMs, rotateAccount) => {
+			const decision = evaluateFailurePolicy({
+				kind: "server",
+				failoverMode: mode,
+				serverRetryAfterMs: 0,
+			});
+			expect(decision.retrySameAccount).toBe(retrySameAccount);
+			expect(decision.retryDelayMs).toBe(retryDelayMs);
+			expect(decision.rotateAccount).toBe(rotateAccount);
+			expect(decision.handoffStrategy).toBe("hard");
+		},
+	);
+
+	it("retries same account for conservative server mode without retry-after", () => {
+		const decision = evaluateFailurePolicy({
+			kind: "server",
+			failoverMode: "conservative",
+			serverRetryAfterMs: 0,
+		});
+
+		expect(decision.retrySameAccount).toBe(true);
+		expect(decision.retryDelayMs).toBe(500);
+		expect(decision.rotateAccount).toBe(false);
+	});
+
+	it("rotates on server failures when retry-after is provided", () => {
+		const decision = evaluateFailurePolicy({
+			kind: "server",
+			failoverMode: "conservative",
+			serverRetryAfterMs: 3_000,
+		});
+
+		expect(decision.retrySameAccount).toBe(false);
+		expect(decision.rotateAccount).toBe(true);
+		expect(decision.cooldownMs).toBe(3_000);
+	});
+
+	it("uses override cooldowns for network and server kinds", () => {
+		const network = evaluateFailurePolicy(
+			{ kind: "network", failoverMode: "aggressive" },
+			{ networkCooldownMs: 0 },
+		);
+		const server = evaluateFailurePolicy(
+			{ kind: "server", failoverMode: "aggressive", serverRetryAfterMs: 0 },
+			{ serverCooldownMs: 0 },
+		);
+		expect(network.cooldownMs).toBe(0);
+		expect(network.cooldownReason).toBeUndefined();
+		expect(server.cooldownMs).toBe(0);
+		expect(server.cooldownReason).toBeUndefined();
+	});
+
+	it.each([
+		["aggressive", false, undefined],
+		["balanced", true, 200],
+		["conservative", true, 600],
+	] as const)(
+		"applies empty-response mode matrix for %s",
+		(mode, retrySameAccount, retryDelayMs) => {
+			const decision = evaluateFailurePolicy({
+				kind: "empty-response",
+				failoverMode: mode,
+			});
+
+			expect(decision.retrySameAccount).toBe(retrySameAccount);
+			expect(decision.retryDelayMs).toBe(retryDelayMs);
+			expect(decision.rotateAccount).toBe(!retrySameAccount);
+			expect(decision.handoffStrategy).toBe("soft");
+		},
+	);
+
+	it("falls back to default hard-handoff policy for unknown failure kind", () => {
+		const decision = evaluateFailurePolicy({ kind: "unknown" as never });
+		expect(decision).toMatchObject({
+			rotateAccount: true,
+			refundToken: true,
+			recordFailure: true,
+			removeAccount: false,
+			retrySameAccount: false,
+			handoffStrategy: "hard",
+		});
+	});
+});
diff --git a/test/fetch-helpers.test.ts b/test/fetch-helpers.test.ts
index a8ee5109..362285ce 100644
--- a/test/fetch-helpers.test.ts
+++ b/test/fetch-helpers.test.ts
@@ -546,7 +546,7 @@ describe('Fetch Helpers Module', () => {
 				};
 			};
 
-			expect(json.error.message).toContain('opencode auth login');
+			expect(json.error.message).toContain('codex login');
 			expect(json.error.diagnostics).toEqual(
 				expect.objectContaining({
 					cfRay: 'abc123-def',
diff --git a/test/forecast.test.ts b/test/forecast.test.ts
new file mode 100644
index 00000000..8a1dec9c
--- /dev/null
+++ b/test/forecast.test.ts
@@ -0,0 +1,439 @@
+import { describe, expect, it } from "vitest";
+import {
+	evaluateForecastAccount,
+	evaluateForecastAccounts,
+	isHardRefreshFailure,
+	recommendForecastAccount,
+	summarizeForecast,
+} from "../lib/forecast.js";
+
+describe("forecast helpers", () => {
+	it("marks disabled account as unavailable high risk", () => {
+		const now = 1_700_000_000_000;
+		const result = evaluateForecastAccount({
+			index: 0,
+			now,
+			isCurrent: false,
+			account: {
+				refreshToken: "refresh-1",
+				addedAt: now - 1_000,
+				lastUsed: now - 1_000,
+				enabled: false,
+			},
+		});
+
+		expect(result.availability).toBe("unavailable");
+		expect(result.riskLevel).toBe("high");
+		expect(result.disabled).toBe(true);
+	});
+
+	it("detects hard refresh failures", () => {
+		expect(
+			isHardRefreshFailure({
+				type: "failed",
+				reason: "missing_refresh",
+			}),
+		).toBe(true);
+
+		expect(
+			isHardRefreshFailure({
+				type: "failed",
+				reason: "http_error",
+				statusCode: 400,
+				message: "invalid_grant: token revoked",
+			}),
+		).toBe(true);
+
+		expect(
+			isHardRefreshFailure({
+				type: "failed",
+				reason: "network_error",
+				message: "timeout",
+			}),
+		).toBe(false);
+	});
+
+	it("raises risk when live quota usage is very high", () => {
+		const now = 1_700_000_000_000;
+		const result = evaluateForecastAccount({
+			index: 0,
+			now,
+			isCurrent: true,
+			account: {
+				refreshToken: "refresh-1",
+				addedAt: now - 10_000,
+				lastUsed: now - 10_000,
+			},
+			liveQuota: {
+				status: 200,
+				model: "gpt-5-codex",
+				primary: { usedPercent: 95, windowMinutes: 180 },
+				secondary: { usedPercent: 20, windowMinutes: 1440 },
+			},
+		});
+
+		expect(result.riskScore).toBeGreaterThanOrEqual(30);
+		expect(result.reasons.some((reason) => reason.includes("primary quota"))).toBe(true);
+	});
+
+	it("recommends the best ready account", () => {
+		const now = 1_700_000_000_000;
+		const results = evaluateForecastAccounts([
+			{
+				index: 0,
+				now,
+				isCurrent: true,
+				account: {
+					refreshToken: "refresh-1",
+					addedAt: now - 100_000,
+					lastUsed: now - 100_000,
+					coolingDownUntil: now + 60_000,
+				},
+			},
+			{
+				index: 1,
+				now,
+				isCurrent: false,
+				account: {
+					refreshToken: "refresh-2",
+					addedAt: now - 100_000,
+					lastUsed: now - 10_000,
+				},
+			},
+		]);
+
+		const recommendation = recommendForecastAccount(results);
+		expect(recommendation.recommendedIndex).toBe(1);
+		expect(recommendation.reason).toContain("Lowest risk ready account");
+
+		const summary = summarizeForecast(results);
+		expect(summary.total).toBe(2);
+		expect(summary.ready).toBe(1);
+		expect(summary.delayed).toBe(1);
+	});
+
+	it("redacts sensitive refresh warning details", () => {
+		const now = 1_700_000_000_000;
+		const result = evaluateForecastAccount({
+			index: 0,
+			now,
+			isCurrent: false,
+			account: {
+				refreshToken: "refresh-1",
+				addedAt: now - 1_000,
+				lastUsed: now - 1_000,
+			},
+			refreshFailure: {
+				type: "failed",
+				reason: "http_error",
+				statusCode: 400,
+				message:
+					"Bearer verysecrettoken12345 for user@example.com with key sk-1234567890abcdef",
+			},
+		});
+
+		expect(result.reasons.some((reason) => reason.includes("refresh warning:"))).toBe(true);
+		expect(result.reasons.join(" ")).not.toContain("user@example.com");
+		expect(result.reasons.join(" ")).not.toContain("verysecrettoken12345");
+		expect(result.reasons.join(" ")).not.toContain("sk-1234567890abcdef");
+		expect(result.riskLevel).toBe("low");
+	});
+
+	it("marks hard refresh failure as unavailable", () => {
+		const now = 1_700_000_000_000;
+		const result = evaluateForecastAccount({
+			index: 1,
+			now,
+			isCurrent: false,
+			account: {
+				refreshToken: "refresh-2",
+				addedAt: now - 1_000,
+				lastUsed: now - 1_000,
+			},
+			refreshFailure: {
+				type: "failed",
+				reason: "http_error",
+				statusCode: 401,
+				message: "invalid_grant",
+			},
+		});
+
+		expect(result.availability).toBe("unavailable");
+		expect(result.hardFailure).toBe(true);
+		expect(result.riskLevel).toBe("high");
+	});
+
+	it("uses max of cooldown and rate-limit wait for delayed availability", () => {
+		const now = 1_700_000_000_000;
+		const cooldownMs = 90_000;
+		const rateLimitMs = 120_000;
+		const result = evaluateForecastAccount({
+			index: 0,
+			now,
+			isCurrent: true,
+			account: {
+				refreshToken: "refresh-1",
+				addedAt: now - 10_000,
+				lastUsed: now - 10_000,
+				coolingDownUntil: now + cooldownMs,
+				rateLimitResetTimes: {
+					codex: now + rateLimitMs,
+					"other-family": now + 999_999,
+				},
+			},
+		});
+
+		expect(result.availability).toBe("delayed");
+		expect(result.waitMs).toBe(rateLimitMs);
+		expect(result.reasons.some((reason) => reason.includes("cooldown remaining"))).toBe(true);
+		expect(result.reasons.some((reason) => reason.includes("rate limit resets in"))).toBe(true);
+	});
+
+	it("marks delayed on live 429 and tracks quota reset wait", () => {
+		const now = 1_700_000_000_000;
+		const result = evaluateForecastAccount({
+			index: 2,
+			now,
+			isCurrent: false,
+			account: {
+				refreshToken: "refresh-3",
+				addedAt: now - 10_000,
+				lastUsed: now - 10_000,
+			},
+			liveQuota: {
+				status: 429,
+				model: "gpt-5-codex",
+				primary: {
+					usedPercent: 50,
+					windowMinutes: 300,
+					resetAtMs: now + 30_000,
+				},
+				secondary: {
+					usedPercent: 30,
+					windowMinutes: 10080,
+					resetAtMs: now + 120_000,
+				},
+			},
+		});
+
+		expect(result.availability).toBe("delayed");
+		expect(result.waitMs).toBe(120_000);
+		expect(result.reasons.some((reason) => reason.includes("live probe returned 429"))).toBe(true);
+	});
+
+	it("does not delay healthy accounts only because quota reset headers exist", () => {
+		const now = 1_700_000_000_000;
+		const result = evaluateForecastAccount({
+			index: 2,
+			now,
+			isCurrent: false,
+			account: {
+				refreshToken: "refresh-3",
+				addedAt: now - 10_000,
+				lastUsed: now - 10_000,
+			},
+			liveQuota: {
+				status: 200,
+				model: "gpt-5-codex",
+				primary: {
+					usedPercent: 20,
+					windowMinutes: 300,
+					resetAtMs: now + 120_000,
+				},
+				secondary: {
+					usedPercent: 10,
+					windowMinutes: 10080,
+					resetAtMs: now + 180_000,
+				},
+			},
+		});
+
+		expect(result.availability).toBe("ready");
+		expect(result.waitMs).toBe(0);
+	});
+
+	it("prefers refresh failure reason code over raw message text", () => {
+		const now = 1_700_000_000_000;
+		const result = evaluateForecastAccount({
+			index: 0,
+			now,
+			isCurrent: false,
+			account: {
+				refreshToken: "refresh-1",
+				addedAt: now - 1_000,
+				lastUsed: now - 1_000,
+			},
+			refreshFailure: {
+				type: "failed",
+				reason: "http_error",
+				statusCode: 400,
+				message: "invalid for user@example.com",
+			},
+		});
+
+		expect(result.reasons.join(" ")).toContain("http_error (400)");
+		expect(result.reasons.join(" ")).not.toContain("user@example.com");
+	});
+
+	it("applies higher risk at higher quota usage thresholds", () => {
+		const now = 1_700_000_000_000;
+		const scoreAt70 = evaluateForecastAccount({
+			index: 0,
+			now,
+			isCurrent: false,
+			account: { refreshToken: "r70", addedAt: now - 1_000, lastUsed: now - 1_000 },
+			liveQuota: {
+				status: 200,
+				model: "gpt-5-codex",
+				primary: { usedPercent: 70, windowMinutes: 300 },
+				secondary: { usedPercent: 0, windowMinutes: 10080 },
+			},
+		}).riskScore;
+		const scoreAt80 = evaluateForecastAccount({
+			index: 1,
+			now,
+			isCurrent: false,
+			account: { refreshToken: "r80", addedAt: now - 1_000, lastUsed: now - 1_000 },
+			liveQuota: {
+				status: 200,
+				model: "gpt-5-codex",
+				primary: { usedPercent: 80, windowMinutes: 300 },
+				secondary: { usedPercent: 0, windowMinutes: 10080 },
+			},
+		}).riskScore;
+		const scoreAt90 = evaluateForecastAccount({
+			index: 2,
+			now,
+			isCurrent: false,
+			account: { refreshToken: "r90", addedAt: now - 1_000, lastUsed: now - 1_000 },
+			liveQuota: {
+				status: 200,
+				model: "gpt-5-codex",
+				primary: { usedPercent: 90, windowMinutes: 300 },
+				secondary: { usedPercent: 0, windowMinutes: 10080 },
+			},
+		}).riskScore;
+		const scoreAt98 = evaluateForecastAccount({
+			index: 3,
+			now,
+			isCurrent: false,
+			account: { refreshToken: "r98", addedAt: now - 1_000, lastUsed: now - 1_000 },
+			liveQuota: {
+				status: 200,
+				model: "gpt-5-codex",
+				primary: { usedPercent: 98, windowMinutes: 300 },
+				secondary: { usedPercent: 0, windowMinutes: 10080 },
+			},
+		}).riskScore;
+
+		expect(scoreAt80).toBeGreaterThan(scoreAt70);
+		expect(scoreAt90).toBeGreaterThan(scoreAt80);
+		expect(scoreAt98).toBeGreaterThan(scoreAt90);
+	});
+
+	it("adds stale-age risk penalties for invalid and old usage timestamps", () => {
+		const now = 1_700_000_000_000;
+		const fresh = evaluateForecastAccount({
+			index: 0,
+			now,
+			isCurrent: false,
+			account: {
+				refreshToken: "fresh",
+				addedAt: now - 1_000,
+				lastUsed: now - 1_000,
+			},
+		});
+		const old = evaluateForecastAccount({
+			index: 1,
+			now,
+			isCurrent: false,
+			account: {
+				refreshToken: "old",
+				addedAt: now - 1_000,
+				lastUsed: now - 8 * 24 * 60 * 60 * 1000,
+			},
+		});
+		const future = evaluateForecastAccount({
+			index: 2,
+			now,
+			isCurrent: false,
+			account: {
+				refreshToken: "future",
+				addedAt: now - 1_000,
+				lastUsed: now + 60_000,
+			},
+		});
+
+		expect(old.riskScore).toBeGreaterThan(fresh.riskScore);
+		expect(future.riskScore).toBeGreaterThanOrEqual(fresh.riskScore + 5);
+	});
+
+	it("returns delayed recommendation when no account is immediately ready", () => {
+		const now = 1_700_000_000_000;
+		const results = evaluateForecastAccounts([
+			{
+				index: 0,
+				now,
+				isCurrent: false,
+				account: {
+					refreshToken: "a",
+					addedAt: now - 1_000,
+					lastUsed: now - 1_000,
+					coolingDownUntil: now + 90_000,
+				},
+			},
+			{
+				index: 1,
+				now,
+				isCurrent: true,
+				account: {
+					refreshToken: "b",
+					addedAt: now - 1_000,
+					lastUsed: now - 1_000,
+					rateLimitResetTimes: { codex: now + 30_000 },
+				},
+			},
+		]);
+
+		const recommendation = recommendForecastAccount(results);
+		expect(recommendation.recommendedIndex).not.toBeNull();
+		expect(recommendation.reason).toContain("No account is immediately ready");
+	});
+
+	it("returns null recommendation when all candidates are disabled or hard-failed", () => {
+		const now = 1_700_000_000_000;
+		const results = evaluateForecastAccounts([
+			{
+				index: 0,
+				now,
+				isCurrent: true,
+				account: {
+					refreshToken: "a",
+					addedAt: now - 1_000,
+					lastUsed: now - 1_000,
+					enabled: false,
+				},
+			},
+			{
+				index: 1,
+				now,
+				isCurrent: false,
+				account: {
+					refreshToken: "b",
+					addedAt: now - 1_000,
+					lastUsed: now - 1_000,
+				},
+				refreshFailure: {
+					type: "failed",
+					reason: "http_error",
+					statusCode: 401,
+					message: "invalid refresh token",
+				},
+			},
+		]);
+
+		const recommendation = recommendForecastAccount(results);
+		expect(recommendation.recommendedIndex).toBeNull();
+		expect(recommendation.reason).toContain("No healthy accounts are available");
+	});
+});
diff --git a/test/index-retry.test.ts b/test/index-retry.test.ts
index 47579837..d07bf796 100644
--- a/test/index-retry.test.ts
+++ b/test/index-retry.test.ts
@@ -130,6 +130,7 @@ vi.mock("../lib/storage.js", () => ({
 	loadAccounts: async () => null,
 	saveAccounts: async () => {},
 	setStoragePath: () => {},
+	setStorageBackupEnabled: () => {},
 	exportAccounts: async () => {},
 	importAccounts: async () => ({ imported: 0, total: 0 }),
 }));
diff --git a/test/index.test.ts b/test/index.test.ts
index 777f07f5..de91d2a9 100644
--- a/test/index.test.ts
+++ b/test/index.test.ts
@@ -39,6 +39,7 @@ vi.mock("../lib/auth/auth.js", () => ({
 			state: stateMatch?.[1],
 		};
 	}),
+	redactOAuthUrlForLog: vi.fn((url: string) => url.replace(/state=[^&]+/, "state=%3Credacted%3E")),
 	REDIRECT_URI: "http://127.0.0.1:1455/auth/callback",
 }));
 
@@ -91,12 +92,48 @@ vi.mock("../lib/config.js", () => ({
 	getPidOffsetEnabled: () => false,
 	getFetchTimeoutMs: () => 60000,
 	getStreamStallTimeoutMs: () => 45000,
+	getLiveAccountSync: vi.fn(() => false),
+	getLiveAccountSyncDebounceMs: () => 250,
+	getLiveAccountSyncPollMs: () => 2000,
+	getSessionAffinity: () => false,
+	getSessionAffinityTtlMs: () => 1_200_000,
+	getSessionAffinityMaxEntries: () => 512,
+	getProactiveRefreshGuardian: () => false,
+	getProactiveRefreshIntervalMs: () => 60000,
+	getProactiveRefreshBufferMs: () => 300000,
+	getNetworkErrorCooldownMs: () => 0,
+	getServerErrorCooldownMs: () => 0,
+	getStorageBackupEnabled: () => true,
+	getPreemptiveQuotaEnabled: () => true,
+	getPreemptiveQuotaRemainingPercent5h: () => 5,
+	getPreemptiveQuotaRemainingPercent7d: () => 5,
+	getPreemptiveQuotaMaxDeferralMs: () => 2 * 60 * 60_000,
 	getCodexTuiV2: () => false,
 	getCodexTuiColorProfile: () => "ansi16",
 	getCodexTuiGlyphMode: () => "ascii",
 	loadPluginConfig: () => ({}),
 }));
 
+const liveAccountSyncSyncToPathMock = vi.fn(async () => {});
+const liveAccountSyncStopMock = vi.fn();
+const liveAccountSyncCtorMock = vi.fn(
+	class MockLiveAccountSync {
+		syncToPath = liveAccountSyncSyncToPathMock;
+		stop = liveAccountSyncStopMock;
+
+		getSnapshot() {
+			return {
+				running: true,
+				reloadCount: 0,
+			};
+		}
+	},
+);
+
+vi.mock("../lib/live-account-sync.js", () => ({
+	LiveAccountSync: liveAccountSyncCtorMock,
+}));
+
 vi.mock("../lib/request/request-transformer.js", () => ({
 	applyFastSessionDefaults: <T>(config: T) => config,
 }));
@@ -203,6 +240,7 @@ vi.mock("../lib/storage.js", () => ({
 	saveAccounts: vi.fn(async () => {}),
 	clearAccounts: vi.fn(async () => {}),
 	setStoragePath: vi.fn(),
+	setStorageBackupEnabled: vi.fn(),
 	exportAccounts: vi.fn(async () => {}),
 	importAccounts: vi.fn(async () => ({ imported: 2, skipped: 1, total: 5 })),
 	loadFlaggedAccounts: vi.fn(async () => ({ version: 1, accounts: [] })),
@@ -466,6 +504,37 @@ describe("OpenAIOAuthPlugin", () => {
 			expect(result.reason).toBe("invalid_response");
 			expect(vi.mocked(authModule.exchangeAuthorizationCode)).not.toHaveBeenCalled();
 		});
+
+		it("redacts oauth state from logged oauth URL", async () => {
+			const authModule = await import("../lib/auth/auth.js");
+			const loggerModule = await import("../lib/logger.js");
+			const browserModule = await import("../lib/auth/browser.js");
+			const serverModule = await import("../lib/auth/server.js");
+			const flow: Awaited<ReturnType<typeof authModule.createAuthorizationFlow>> = {
+				pkce: { verifier: "v", challenge: "c" },
+				state: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+				url: "https://auth.openai.com/oauth/authorize?state=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&response_type=code&client_id=test",
+			};
+			vi.mocked(authModule.createAuthorizationFlow).mockResolvedValue(flow);
+			vi.mocked(browserModule.openBrowserUrl).mockReturnValue(true);
+			vi.mocked(serverModule.startLocalOAuthServer).mockResolvedValue({
+				ready: true,
+				close: vi.fn(),
+				waitForCode: vi.fn(async () => ({ code: "auth-code" })),
+			});
+
+			const autoMethod = plugin.auth.methods[0] as unknown as {
+				authorize: () => Promise<unknown>;
+			};
+			await autoMethod.authorize();
+
+			expect(vi.mocked(loggerModule.logInfo)).toHaveBeenCalledWith(
+				expect.stringContaining("state=%3Credacted%3E"),
+			);
+			expect(vi.mocked(loggerModule.logInfo)).not.toHaveBeenCalledWith(
+				expect.stringContaining("aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"),
+			);
+		});
 	});
 
 	describe("event handler", () => {
@@ -521,6 +590,34 @@ describe("OpenAIOAuthPlugin", () => {
 			expect(result.baseURL).toBeDefined();
 			expect(result.fetch).toBeDefined();
 		});
+
+		it("serializes live sync setup when loader is called concurrently", async () => {
+			const configModule = await import("../lib/config.js");
+			vi.mocked(configModule.getLiveAccountSync).mockReturnValue(true);
+			liveAccountSyncCtorMock.mockClear();
+			liveAccountSyncSyncToPathMock.mockClear();
+
+			const getAuth = async () => ({
+				type: "oauth" as const,
+				access: "a",
+				refresh: "r",
+				expires: Date.now() + 60_000,
+				multiAccount: true,
+			});
+
+			try {
+				await Promise.all([
+					plugin.auth.loader(getAuth, { options: {}, models: {} }),
+					plugin.auth.loader(getAuth, { options: {}, models: {} }),
+					plugin.auth.loader(getAuth, { options: {}, models: {} }),
+				]);
+
+				expect(liveAccountSyncCtorMock).toHaveBeenCalledTimes(1);
+				expect(liveAccountSyncSyncToPathMock).toHaveBeenCalledTimes(1);
+			} finally {
+				vi.mocked(configModule.getLiveAccountSync).mockReturnValue(false);
+			}
+		});
 	});
 
 	describe("codex-list tool", () => {
@@ -528,7 +625,7 @@ describe("OpenAIOAuthPlugin", () => {
 			mockStorage.accounts = [];
 			const result = await plugin.tool["codex-list"].execute();
 			expect(result).toContain("No Codex accounts configured");
-			expect(result).toContain("opencode auth login");
+			expect(result).toContain("codex login");
 		});
 
 		it("lists accounts with status", async () => {
@@ -970,6 +1067,32 @@ describe("OpenAIOAuthPlugin fetch handler", () => {
 		expect(syncCodexCliSelectionMock).not.toHaveBeenCalled();
 	});
 
+	it("does not penalize account health when fetch is aborted by user", async () => {
+		const { AccountManager } = await import("../lib/accounts.js");
+		const { CapabilityPolicyStore } = await import("../lib/capability-policy.js");
+		const recordFailureSpy = vi.spyOn(AccountManager.prototype, "recordFailure");
+		const markCooldownSpy = vi.spyOn(AccountManager.prototype, "markAccountCoolingDown");
+		const refundSpy = vi.spyOn(AccountManager.prototype, "refundToken");
+		const capabilityFailureSpy = vi.spyOn(CapabilityPolicyStore.prototype, "recordFailure");
+		const abortError = Object.assign(new Error("aborted by user"), { name: "AbortError" });
+		globalThis.fetch = vi.fn().mockRejectedValue(abortError);
+
+		const { sdk } = await setupPlugin();
+		const controller = new AbortController();
+		controller.abort(abortError);
+		const response = await sdk.fetch!("https://api.openai.com/v1/chat", {
+			method: "POST",
+			body: JSON.stringify({ model: "gpt-5.1" }),
+			signal: controller.signal,
+		});
+
+		expect(response.status).toBe(503);
+		expect(recordFailureSpy).not.toHaveBeenCalled();
+		expect(markCooldownSpy).not.toHaveBeenCalled();
+		expect(refundSpy).not.toHaveBeenCalled();
+		expect(capabilityFailureSpy).not.toHaveBeenCalled();
+	});
+
 	it("skips fetch when local token bucket is depleted", async () => {
 		const { AccountManager } = await import("../lib/accounts.js");
 		const consumeSpy = vi.spyOn(AccountManager.prototype, "consumeToken").mockReturnValue(false);
diff --git a/test/live-account-sync.test.ts b/test/live-account-sync.test.ts
new file mode 100644
index 00000000..0a26f083
--- /dev/null
+++ b/test/live-account-sync.test.ts
@@ -0,0 +1,78 @@
+import { describe, expect, it, beforeEach, afterEach, vi } from "vitest";
+import { promises as fs } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { LiveAccountSync } from "../lib/live-account-sync.js";
+
+describe("live-account-sync", () => {
+	let workDir = "";
+	let storagePath = "";
+
+	beforeEach(async () => {
+		vi.useFakeTimers();
+		vi.setSystemTime(new Date("2026-02-26T12:00:00.000Z"));
+		workDir = join(tmpdir(), `codex-live-sync-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+		storagePath = join(workDir, "openai-codex-accounts.json");
+		await fs.mkdir(workDir, { recursive: true });
+		await fs.writeFile(storagePath, JSON.stringify({ version: 3, activeIndex: 0, accounts: [] }), "utf-8");
+	});
+
+	afterEach(async () => {
+		vi.useRealTimers();
+		await fs.rm(workDir, { recursive: true, force: true });
+	});
+
+	it("reloads when file changes are detected by polling", async () => {
+		const reload = vi.fn(async () => undefined);
+		const sync = new LiveAccountSync(reload, { pollIntervalMs: 500, debounceMs: 50 });
+
+		await sync.syncToPath(storagePath);
+		await fs.writeFile(storagePath, JSON.stringify({ version: 3, activeIndex: 0, accounts: [{ refreshToken: "a" }] }), "utf-8");
+		const bumped = new Date(Date.now() + 1_000);
+		await fs.utimes(storagePath, bumped, bumped);
+
+		await vi.advanceTimersByTimeAsync(900);
+
+		expect(reload).toHaveBeenCalled();
+		const snapshot = sync.getSnapshot();
+		expect(snapshot.reloadCount).toBeGreaterThan(0);
+		expect(snapshot.lastSyncAt).not.toBeNull();
+		sync.stop();
+	});
+
+	it("records errors when reload fails", async () => {
+		const reload = vi.fn(async () => {
+			throw new Error("reload failed");
+		});
+		const sync = new LiveAccountSync(reload, { pollIntervalMs: 500, debounceMs: 50 });
+
+		await sync.syncToPath(storagePath);
+		await fs.writeFile(storagePath, JSON.stringify({ version: 3, activeIndex: 0, accounts: [{ refreshToken: "b" }] }), "utf-8");
+		const bumped = new Date(Date.now() + 2_000);
+		await fs.utimes(storagePath, bumped, bumped);
+
+		await vi.advanceTimersByTimeAsync(900);
+
+		const snapshot = sync.getSnapshot();
+		expect(snapshot.errorCount).toBeGreaterThan(0);
+		expect(snapshot.reloadCount).toBe(0);
+		sync.stop();
+	});
+
+	it("stops watching cleanly and prevents further reloads", async () => {
+		const reload = vi.fn(async () => undefined);
+		const sync = new LiveAccountSync(reload, { pollIntervalMs: 500, debounceMs: 50 });
+
+		await sync.syncToPath(storagePath);
+		sync.stop();
+		await fs.writeFile(storagePath, JSON.stringify({ version: 3, activeIndex: 0, accounts: [{ refreshToken: "c" }] }), "utf-8");
+		const bumped = new Date(Date.now() + 3_000);
+		await fs.utimes(storagePath, bumped, bumped);
+
+		await vi.advanceTimersByTimeAsync(1_200);
+
+		expect(reload).not.toHaveBeenCalled();
+		expect(sync.getSnapshot().running).toBe(false);
+	});
+});
+
diff --git a/test/logger.test.ts b/test/logger.test.ts
index 13781f5c..82ebabbf 100644
--- a/test/logger.test.ts
+++ b/test/logger.test.ts
@@ -800,6 +800,53 @@ describe('Logger Module', () => {
 				expect.stringContaining('Failed to write log'),
 			);
 		});
+
+		it("retries log directory creation for transient EBUSY/EPERM errors", async () => {
+			const transientBusy = Object.assign(new Error("busy"), { code: "EBUSY" });
+			const transientPerm = Object.assign(new Error("perm"), { code: "EPERM" });
+			mockExistsSync.mockReturnValue(false);
+			mockMkdirSync
+				.mockImplementationOnce(() => {
+					throw transientBusy;
+				})
+				.mockImplementationOnce(() => {
+					throw transientPerm;
+				})
+				.mockImplementationOnce(() => {});
+
+			const { logRequest: logRequestEnabled } = await loadLoggerModule({
+				ENABLE_PLUGIN_REQUEST_LOGGING: "1",
+				CODEX_CONSOLE_LOG: "1",
+			});
+
+			logRequestEnabled("retry-dir", { ok: true });
+
+			expect(mockMkdirSync).toHaveBeenCalledTimes(3);
+			expect(mockWriteFileSync).toHaveBeenCalledTimes(1);
+		});
+
+		it("skips write when directory creation fails with non-retryable error", async () => {
+			const consoleWarn = vi.spyOn(console, "warn").mockImplementation(() => {});
+			mockExistsSync.mockReturnValue(false);
+			mockMkdirSync.mockImplementation(() => {
+				throw Object.assign(new Error("denied"), { code: "EACCES" });
+			});
+
+			const { logRequest: logRequestEnabled } = await loadLoggerModule({
+				ENABLE_PLUGIN_REQUEST_LOGGING: "1",
+				CODEX_CONSOLE_LOG: "1",
+			});
+			consoleWarn.mockClear();
+
+			logRequestEnabled("mkdir-failed", { ok: false });
+
+			expect(mockMkdirSync).toHaveBeenCalledTimes(1);
+			expect(mockWriteFileSync).not.toHaveBeenCalled();
+			expect(consoleWarn).toHaveBeenCalledWith(
+				expect.stringContaining("Failed to ensure log directory"),
+				expect.objectContaining({ path: expect.any(String) }),
+			);
+		});
 	});
 
 	describe('scoped logger when debug is enabled', () => {
diff --git a/test/opencode-codex.test.ts b/test/opencode-codex.test.ts
index fb0c187e..3ec6c039 100644
--- a/test/opencode-codex.test.ts
+++ b/test/opencode-codex.test.ts
@@ -83,7 +83,7 @@ describe("opencode-codex", () => {
       );
     });
 
-    it("sends conditional request to cached source when sourceUrl is known", async () => {
+    it("does not trust cached sourceUrl for refetch ordering", async () => {
       const { getOpenCodeCodexPrompt } = await import("../lib/prompts/opencode-codex.js");
 
       vi.mocked(readFile)
@@ -103,12 +103,9 @@ describe("opencode-codex", () => {
       const result = await getOpenCodeCodexPrompt();
 
       expect(result).toBe("Cached content");
-      expect(mockFetch).toHaveBeenCalledWith(
-        "https://example.com/prompt.txt",
-        expect.objectContaining({
-          headers: { "If-None-Match": '"old-etag"' },
-        }),
-      );
+      expect(mockFetch).toHaveBeenCalledTimes(1);
+      expect(String(mockFetch.mock.calls[0]?.[0])).toContain("raw.githubusercontent.com");
+      expect(mockFetch.mock.calls[0]?.[1]).toEqual(expect.objectContaining({ headers: {} }));
     });
 
     it("falls back to next source when first source returns 404", async () => {
@@ -155,6 +152,32 @@ describe("opencode-codex", () => {
       expect(mockFetch.mock.calls[0]?.[0]).toBe("https://example.com/custom-codex.txt");
     });
 
+    it("does not persist raw override URL query parameters in cache metadata", async () => {
+      const { getOpenCodeCodexPrompt } = await import("../lib/prompts/opencode-codex.js");
+
+      vi.mocked(readFile).mockRejectedValue(new Error("ENOENT"));
+      vi.stubEnv(
+        "CODEX_PROMPT_SOURCE_URL",
+        "https://example.com/custom-codex.txt?token=secret123&state=abc",
+      );
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        text: () => Promise.resolve("Prompt from env override"),
+        headers: new Map([["etag", '"env-etag"']]),
+      });
+
+      await getOpenCodeCodexPrompt();
+
+      const metaCall = vi.mocked(writeFile).mock.calls.find((call) =>
+        typeof call[0] === "string" && call[0].includes("opencode-codex-meta.json")
+      );
+      const metaText = String(metaCall?.[1] ?? "");
+      expect(metaText).toContain("\"sourceKey\": \"https://example.com/custom-codex.txt\"");
+      expect(metaText).not.toContain("token=secret123");
+      expect(metaText).not.toContain("state=abc");
+    });
+
     it("serves stale content immediately and refreshes cache in background", async () => {
       const { getOpenCodeCodexPrompt } = await import("../lib/prompts/opencode-codex.js");
       
@@ -214,6 +237,26 @@ describe("opencode-codex", () => {
       expect(mockFetch.mock.calls.length).toBeGreaterThan(1);
     });
 
+    it("retries transient EBUSY cache write errors and succeeds", async () => {
+      const { getOpenCodeCodexPrompt } = await import("../lib/prompts/opencode-codex.js");
+
+      vi.mocked(readFile).mockRejectedValue(new Error("ENOENT"));
+      const busy = Object.assign(new Error("busy"), { code: "EBUSY" });
+      vi.mocked(writeFile)
+        .mockRejectedValueOnce(busy)
+        .mockResolvedValue(undefined);
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        text: () => Promise.resolve("Fresh prompt content"),
+        headers: new Map([["etag", '"abc123"']]),
+      });
+
+      const result = await getOpenCodeCodexPrompt();
+      expect(result).toBe("Fresh prompt content");
+      expect(writeFile).toHaveBeenCalled();
+    });
+
     it("falls back to cache on non-OK response", async () => {
       const { getOpenCodeCodexPrompt } = await import("../lib/prompts/opencode-codex.js");
       
diff --git a/test/package-bin.test.ts b/test/package-bin.test.ts
new file mode 100644
index 00000000..e35c36bf
--- /dev/null
+++ b/test/package-bin.test.ts
@@ -0,0 +1,16 @@
+import { describe, expect, it } from "vitest";
+import { readFileSync } from "node:fs";
+
+describe("package bin entries", () => {
+	it("exposes expected CLI bins", () => {
+		const pkg = JSON.parse(readFileSync("package.json", "utf8")) as {
+			bin?: Record<string, string>;
+		};
+		expect(pkg.bin).toBeDefined();
+		expect(pkg.bin?.codex).toBe("scripts/codex.js");
+		expect(pkg.bin?.["codex-multi-auth"]).toBe("scripts/codex-multi-auth.js");
+		expect(pkg.bin?.["codex-multi-auth-opencode-install"]).toBe(
+			"scripts/install-opencode-codex-auth.js",
+		);
+	});
+});
diff --git a/test/paths.test.ts b/test/paths.test.ts
index ca215ec8..8db7b7f8 100644
--- a/test/paths.test.ts
+++ b/test/paths.test.ts
@@ -20,32 +20,63 @@ import {
 const mockedExistsSync = vi.mocked(existsSync);
 
 describe("Storage Paths Module", () => {
+	const _origCODEX_HOME = process.env.CODEX_HOME;
+	const _origCODEX_MULTI_AUTH_DIR = process.env.CODEX_MULTI_AUTH_DIR;
+
 	beforeEach(() => {
+		delete process.env.CODEX_HOME;
+		delete process.env.CODEX_MULTI_AUTH_DIR;
 		vi.clearAllMocks();
 	});
 
 	afterEach(() => {
 		vi.resetAllMocks();
+		if (_origCODEX_HOME !== undefined) process.env.CODEX_HOME = _origCODEX_HOME; else delete process.env.CODEX_HOME;
+		if (_origCODEX_MULTI_AUTH_DIR !== undefined) process.env.CODEX_MULTI_AUTH_DIR = _origCODEX_MULTI_AUTH_DIR; else delete process.env.CODEX_MULTI_AUTH_DIR;
 	});
 
 	describe("getConfigDir", () => {
-		it("should return ~/.opencode", () => {
+		it("should return ~/.codex/multi-auth", () => {
+			const result = getConfigDir();
+			expect(result).toBe(path.join(homedir(), ".codex", "multi-auth"));
+		});
+
+		it("uses explicit CODEX_MULTI_AUTH_DIR when provided", () => {
+			process.env.CODEX_MULTI_AUTH_DIR = "/custom/multi-auth";
+			const result = getConfigDir();
+			expect(result).toBe("/custom/multi-auth");
+		});
+
+		it("falls back to legacy codex home dir with storage when primary has none", () => {
+			const primary = path.join(homedir(), ".codex", "multi-auth");
+			const fallback = path.join(homedir(), "DevTools", "config", "codex", "multi-auth");
+
+			mockedExistsSync.mockImplementation((candidate) => {
+				if (typeof candidate !== "string") return false;
+				if (candidate === path.join(primary, "openai-codex-accounts.json")) return false;
+				if (candidate === path.join(primary, "settings.json")) return false;
+				if (candidate === path.join(primary, "config.json")) return false;
+				if (candidate === path.join(primary, "dashboard-settings.json")) return false;
+				if (candidate === path.join(primary, "projects")) return false;
+				return candidate === path.join(fallback, "openai-codex-accounts.json");
+			});
+
 			const result = getConfigDir();
-			expect(result).toBe(path.join(homedir(), ".opencode"));
+			expect(result).toBe(fallback);
 		});
 	});
 
 	describe("getProjectConfigDir", () => {
-		it("should return project path with .opencode appended", () => {
+		it("should return project path with .codex appended", () => {
 			const projectPath = "/home/user/myproject";
 			const result = getProjectConfigDir(projectPath);
-			expect(result).toBe(path.join(projectPath, ".opencode"));
+			expect(result).toBe(path.join(projectPath, ".codex"));
 		});
 
 		it("should handle Windows-style paths", () => {
 			const projectPath = "C:\\Users\\test\\project";
 			const result = getProjectConfigDir(projectPath);
-			expect(result).toBe(path.join(projectPath, ".opencode"));
+			expect(result).toBe(path.join(projectPath, ".codex"));
 		});
 	});
 
@@ -60,16 +91,16 @@ describe("Storage Paths Module", () => {
 	});
 
 	describe("getProjectGlobalConfigDir", () => {
-		it("returns ~/.opencode/projects/<key>", () => {
+		it("returns ~/.codex/multi-auth/projects/<key>", () => {
 			const projectPath = "/home/user/myproject";
 			const result = getProjectGlobalConfigDir(projectPath);
-			expect(result).toContain(path.join(homedir(), ".opencode", "projects"));
+			expect(result).toContain(path.join(homedir(), ".codex", "multi-auth", "projects"));
 			expect(result).toContain("myproject-");
 		});
 	});
 
 	describe("isProjectDirectory", () => {
-		const markers = [".git", "package.json", "Cargo.toml", "go.mod", "pyproject.toml", ".opencode"];
+		const markers = [".git", "package.json", "Cargo.toml", "go.mod", "pyproject.toml", ".codex"];
 
 		it.each(markers)("should return true when %s exists", (marker) => {
 			mockedExistsSync.mockImplementation((p) => {
@@ -132,8 +163,8 @@ describe("Storage Paths Module", () => {
 
 	describe("resolvePath", () => {
 		it("should expand tilde to home directory", () => {
-			const result = resolvePath("~/.opencode/config.json");
-			expect(result).toBe(path.join(homedir(), ".opencode/config.json"));
+			const result = resolvePath("~/.codex/config.json");
+			expect(result).toBe(path.join(homedir(), ".codex/config.json"));
 		});
 
 		it("should resolve relative paths", () => {
diff --git a/test/plugin-config.test.ts b/test/plugin-config.test.ts
index ac78e7f8..6288127f 100644
--- a/test/plugin-config.test.ts
+++ b/test/plugin-config.test.ts
@@ -17,6 +17,10 @@ import {
 	getUnsupportedCodexFallbackChain,
 	getFetchTimeoutMs,
 	getStreamStallTimeoutMs,
+	getPreemptiveQuotaEnabled,
+	getPreemptiveQuotaRemainingPercent5h,
+	getPreemptiveQuotaRemainingPercent7d,
+	getPreemptiveQuotaMaxDeferralMs,
 } from '../lib/config.js';
 import type { PluginConfig } from '../lib/types.js';
 import * as fs from 'node:fs';
@@ -47,6 +51,8 @@ describe('Plugin Configuration', () => {
 	const mockExistsSync = vi.mocked(fs.existsSync);
 	const mockReadFileSync = vi.mocked(fs.readFileSync);
 	const envKeys = [
+		'CODEX_HOME',
+		'CODEX_MULTI_AUTH_DIR',
 		'CODEX_MODE',
 		'CODEX_TUI_V2',
 		'CODEX_TUI_COLOR_PROFILE',
@@ -57,6 +63,10 @@ describe('Plugin Configuration', () => {
 		'CODEX_AUTH_UNSUPPORTED_MODEL_POLICY',
 		'CODEX_AUTH_FALLBACK_UNSUPPORTED_MODEL',
 		'CODEX_AUTH_FALLBACK_GPT53_TO_GPT52',
+		'CODEX_AUTH_PREEMPTIVE_QUOTA_ENABLED',
+		'CODEX_AUTH_PREEMPTIVE_QUOTA_5H_REMAINING_PCT',
+		'CODEX_AUTH_PREEMPTIVE_QUOTA_7D_REMAINING_PCT',
+		'CODEX_AUTH_PREEMPTIVE_QUOTA_MAX_DEFERRAL_MS',
 	] as const;
 	const originalEnv: Partial<Record<(typeof envKeys)[number], string | undefined>> = {};
 
@@ -113,10 +123,28 @@ describe('Plugin Configuration', () => {
 				pidOffsetEnabled: false,
 				fetchTimeoutMs: 60_000,
 				streamStallTimeoutMs: 45_000,
+				liveAccountSync: true,
+				liveAccountSyncDebounceMs: 250,
+				liveAccountSyncPollMs: 2_000,
+				sessionAffinity: true,
+				sessionAffinityTtlMs: 20 * 60_000,
+				sessionAffinityMaxEntries: 512,
+				proactiveRefreshGuardian: true,
+				proactiveRefreshIntervalMs: 60_000,
+				proactiveRefreshBufferMs: 5 * 60_000,
+				networkErrorCooldownMs: 6_000,
+				serverErrorCooldownMs: 4_000,
+				storageBackupEnabled: true,
+				preemptiveQuotaEnabled: true,
+				preemptiveQuotaRemainingPercent5h: 5,
+				preemptiveQuotaRemainingPercent7d: 5,
+				preemptiveQuotaMaxDeferralMs: 2 * 60 * 60_000,
 			});
-			expect(mockExistsSync).toHaveBeenCalledWith(
-				path.join(os.homedir(), '.opencode', 'codex-multi-auth-config.json')
-			);
+			// existsSync is called with multiple candidate config paths (primary + legacy fallbacks)
+			expect(mockExistsSync).toHaveBeenCalled();
+			expect(mockExistsSync.mock.calls.some(([p]) =>
+				typeof p === 'string' && p.includes('config') && p.includes('codex')
+			)).toBe(true);
 		});
 
 		it('should load config from file when it exists', () => {
@@ -153,6 +181,22 @@ describe('Plugin Configuration', () => {
 				pidOffsetEnabled: false,
 				fetchTimeoutMs: 60_000,
 				streamStallTimeoutMs: 45_000,
+				liveAccountSync: true,
+				liveAccountSyncDebounceMs: 250,
+				liveAccountSyncPollMs: 2_000,
+				sessionAffinity: true,
+				sessionAffinityTtlMs: 20 * 60_000,
+				sessionAffinityMaxEntries: 512,
+				proactiveRefreshGuardian: true,
+				proactiveRefreshIntervalMs: 60_000,
+				proactiveRefreshBufferMs: 5 * 60_000,
+				networkErrorCooldownMs: 6_000,
+				serverErrorCooldownMs: 4_000,
+				storageBackupEnabled: true,
+				preemptiveQuotaEnabled: true,
+				preemptiveQuotaRemainingPercent5h: 5,
+				preemptiveQuotaRemainingPercent7d: 5,
+				preemptiveQuotaMaxDeferralMs: 2 * 60 * 60_000,
 			});
 		});
 
@@ -190,6 +234,22 @@ describe('Plugin Configuration', () => {
 				pidOffsetEnabled: false,
 				fetchTimeoutMs: 60_000,
 				streamStallTimeoutMs: 45_000,
+				liveAccountSync: true,
+				liveAccountSyncDebounceMs: 250,
+				liveAccountSyncPollMs: 2_000,
+				sessionAffinity: true,
+				sessionAffinityTtlMs: 20 * 60_000,
+				sessionAffinityMaxEntries: 512,
+				proactiveRefreshGuardian: true,
+				proactiveRefreshIntervalMs: 60_000,
+				proactiveRefreshBufferMs: 5 * 60_000,
+				networkErrorCooldownMs: 6_000,
+				serverErrorCooldownMs: 4_000,
+				storageBackupEnabled: true,
+				preemptiveQuotaEnabled: true,
+				preemptiveQuotaRemainingPercent5h: 5,
+				preemptiveQuotaRemainingPercent7d: 5,
+				preemptiveQuotaMaxDeferralMs: 2 * 60 * 60_000,
 			});
 		});
 
@@ -238,6 +298,22 @@ describe('Plugin Configuration', () => {
 		pidOffsetEnabled: false,
 		fetchTimeoutMs: 60_000,
 		streamStallTimeoutMs: 45_000,
+				liveAccountSync: true,
+				liveAccountSyncDebounceMs: 250,
+				liveAccountSyncPollMs: 2_000,
+				sessionAffinity: true,
+				sessionAffinityTtlMs: 20 * 60_000,
+				sessionAffinityMaxEntries: 512,
+				proactiveRefreshGuardian: true,
+				proactiveRefreshIntervalMs: 60_000,
+				proactiveRefreshBufferMs: 5 * 60_000,
+				networkErrorCooldownMs: 6_000,
+				serverErrorCooldownMs: 4_000,
+				storageBackupEnabled: true,
+				preemptiveQuotaEnabled: true,
+				preemptiveQuotaRemainingPercent5h: 5,
+				preemptiveQuotaRemainingPercent7d: 5,
+				preemptiveQuotaMaxDeferralMs: 2 * 60 * 60_000,
 	});
 		expect(mockLogWarn).toHaveBeenCalled();
 	});
@@ -280,6 +356,22 @@ describe('Plugin Configuration', () => {
 			pidOffsetEnabled: false,
 			fetchTimeoutMs: 60_000,
 			streamStallTimeoutMs: 45_000,
+				liveAccountSync: true,
+				liveAccountSyncDebounceMs: 250,
+				liveAccountSyncPollMs: 2_000,
+				sessionAffinity: true,
+				sessionAffinityTtlMs: 20 * 60_000,
+				sessionAffinityMaxEntries: 512,
+				proactiveRefreshGuardian: true,
+				proactiveRefreshIntervalMs: 60_000,
+				proactiveRefreshBufferMs: 5 * 60_000,
+				networkErrorCooldownMs: 6_000,
+				serverErrorCooldownMs: 4_000,
+				storageBackupEnabled: true,
+				preemptiveQuotaEnabled: true,
+				preemptiveQuotaRemainingPercent5h: 5,
+				preemptiveQuotaRemainingPercent7d: 5,
+				preemptiveQuotaMaxDeferralMs: 2 * 60 * 60_000,
 		});
 		expect(mockLogWarn).toHaveBeenCalled();
 	});
@@ -666,4 +758,25 @@ describe('Plugin Configuration', () => {
 			delete process.env.CODEX_AUTH_STREAM_STALL_TIMEOUT_MS;
 		});
 	});
+
+	describe('preemptive quota settings', () => {
+		it('should use default thresholds', () => {
+			expect(getPreemptiveQuotaEnabled({})).toBe(true);
+			expect(getPreemptiveQuotaRemainingPercent5h({})).toBe(5);
+			expect(getPreemptiveQuotaRemainingPercent7d({})).toBe(5);
+			expect(getPreemptiveQuotaMaxDeferralMs({})).toBe(2 * 60 * 60_000);
+		});
+
+		it('should prioritize environment overrides', () => {
+			process.env.CODEX_AUTH_PREEMPTIVE_QUOTA_ENABLED = '0';
+			process.env.CODEX_AUTH_PREEMPTIVE_QUOTA_5H_REMAINING_PCT = '9';
+			process.env.CODEX_AUTH_PREEMPTIVE_QUOTA_7D_REMAINING_PCT = '11';
+			process.env.CODEX_AUTH_PREEMPTIVE_QUOTA_MAX_DEFERRAL_MS = '123000';
+			expect(getPreemptiveQuotaEnabled({ preemptiveQuotaEnabled: true })).toBe(false);
+			expect(getPreemptiveQuotaRemainingPercent5h({ preemptiveQuotaRemainingPercent5h: 1 })).toBe(9);
+			expect(getPreemptiveQuotaRemainingPercent7d({ preemptiveQuotaRemainingPercent7d: 2 })).toBe(11);
+			expect(getPreemptiveQuotaMaxDeferralMs({ preemptiveQuotaMaxDeferralMs: 2_000 })).toBe(123000);
+		});
+	});
 });
+
diff --git a/test/preemptive-quota-scheduler.test.ts b/test/preemptive-quota-scheduler.test.ts
new file mode 100644
index 00000000..9bbbce0e
--- /dev/null
+++ b/test/preemptive-quota-scheduler.test.ts
@@ -0,0 +1,121 @@
+import { describe, expect, it } from "vitest";
+import {
+	PreemptiveQuotaScheduler,
+	readQuotaSchedulerSnapshot,
+} from "../lib/preemptive-quota-scheduler.js";
+
+describe("preemptive quota scheduler", () => {
+	it("reads quota snapshot from codex headers", () => {
+		const headers = new Headers({
+			"x-codex-primary-used-percent": "99",
+			"x-codex-primary-reset-after-seconds": "120",
+			"x-codex-secondary-used-percent": "10",
+		});
+
+		const snapshot = readQuotaSchedulerSnapshot(headers, 200, 1_000);
+		expect(snapshot).not.toBeNull();
+		expect(snapshot?.status).toBe(200);
+		expect(snapshot?.primary.usedPercent).toBe(99);
+		expect(snapshot?.primary.resetAtMs).toBeGreaterThan(1_000);
+	});
+
+	it("uses provided now when parsing reset-after seconds", () => {
+		const headers = new Headers({
+			"x-codex-primary-reset-after-seconds": "120",
+		});
+		const snapshot = readQuotaSchedulerSnapshot(headers, 200, 5_000);
+		expect(snapshot?.primary.resetAtMs).toBe(125_000);
+	});
+
+	it("defers requests for known 429 window", () => {
+		const scheduler = new PreemptiveQuotaScheduler();
+		scheduler.markRateLimited("acc:model", 30_000, 1_000);
+
+		const decision = scheduler.getDeferral("acc:model", 2_000);
+		expect(decision.defer).toBe(true);
+		expect(decision.reason).toBe("rate-limit");
+		expect(decision.waitMs).toBeGreaterThan(0);
+	});
+
+	it("sanitizes non-finite retry-after values", () => {
+		const scheduler = new PreemptiveQuotaScheduler();
+		scheduler.markRateLimited("acc:model", Number.NaN, 1_000);
+		const nanDecision = scheduler.getDeferral("acc:model", 1_000);
+		expect(nanDecision.defer).toBe(false);
+
+		scheduler.markRateLimited("acc:model", Number.POSITIVE_INFINITY, 2_000);
+		const infDecision = scheduler.getDeferral("acc:model", 2_000);
+		expect(infDecision.defer).toBe(false);
+
+		scheduler.markRateLimited("acc:model", -1234, 3_000);
+		const negativeDecision = scheduler.getDeferral("acc:model", 3_000);
+		expect(negativeDecision.defer).toBe(false);
+	});
+
+	it("defers when usage is near exhaustion and reset is pending", () => {
+		const scheduler = new PreemptiveQuotaScheduler({ usedPercentThreshold: 95 });
+		scheduler.update("acc:model", {
+			status: 200,
+			primary: {
+				usedPercent: 97,
+				resetAtMs: 70_000,
+			},
+			secondary: {},
+			updatedAt: 10_000,
+		});
+
+		const decision = scheduler.getDeferral("acc:model", 20_000);
+		expect(decision.defer).toBe(true);
+		expect(decision.reason).toBe("quota-near-exhaustion");
+	});
+
+	it("prunes expired snapshots", () => {
+		const scheduler = new PreemptiveQuotaScheduler();
+		scheduler.update("a", {
+			status: 200,
+			primary: { resetAtMs: 1_500 },
+			secondary: {},
+			updatedAt: 1_000,
+		});
+		scheduler.update("b", {
+			status: 200,
+			primary: { resetAtMs: 20_000 },
+			secondary: {},
+			updatedAt: 1_000,
+		});
+
+		const removed = scheduler.prune(2_000);
+		expect(removed).toBe(1);
+		expect(scheduler.getDeferral("a", 2_100).defer).toBe(false);
+		expect(scheduler.getDeferral("b", 2_100).defer).toBe(false);
+	});
+
+	it("uses separate 5h/7d remaining thresholds", () => {
+		const scheduler = new PreemptiveQuotaScheduler({
+			remainingPercentThresholdPrimary: 10,
+			remainingPercentThresholdSecondary: 2,
+		});
+		scheduler.update("acc:model", {
+			status: 200,
+			primary: { usedPercent: 91, resetAtMs: 65_000 },
+			secondary: { usedPercent: 97, resetAtMs: 66_000 },
+			updatedAt: 1_000,
+		});
+
+		const decision = scheduler.getDeferral("acc:model", 5_000);
+		expect(decision.defer).toBe(true);
+		expect(decision.reason).toBe("quota-near-exhaustion");
+	});
+
+	it("can disable preemptive deferral without clearing snapshots", () => {
+		const scheduler = new PreemptiveQuotaScheduler();
+		scheduler.markRateLimited("acc:model", 30_000, 1_000);
+		expect(scheduler.getDeferral("acc:model", 2_000).defer).toBe(true);
+
+		scheduler.configure({ enabled: false });
+		expect(scheduler.getDeferral("acc:model", 2_000).defer).toBe(false);
+
+		scheduler.configure({ enabled: true });
+		expect(scheduler.getDeferral("acc:model", 2_000).defer).toBe(true);
+	});
+});
diff --git a/test/quota-cache.test.ts b/test/quota-cache.test.ts
new file mode 100644
index 00000000..fdbabe04
--- /dev/null
+++ b/test/quota-cache.test.ts
@@ -0,0 +1,231 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { promises as fs } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+describe("quota cache", () => {
+	let tempDir: string;
+	let originalDir: string | undefined;
+
+	beforeEach(async () => {
+		originalDir = process.env.CODEX_MULTI_AUTH_DIR;
+		tempDir = await fs.mkdtemp(join(tmpdir(), "codex-multi-auth-quota-"));
+		process.env.CODEX_MULTI_AUTH_DIR = tempDir;
+		vi.resetModules();
+	});
+
+	afterEach(async () => {
+		if (originalDir === undefined) {
+			delete process.env.CODEX_MULTI_AUTH_DIR;
+		} else {
+			process.env.CODEX_MULTI_AUTH_DIR = originalDir;
+		}
+		await fs.rm(tempDir, { recursive: true, force: true });
+	});
+
+	it("returns empty cache by default", async () => {
+		const { loadQuotaCache } = await import("../lib/quota-cache.js");
+		const data = await loadQuotaCache();
+		expect(data).toEqual({ byAccountId: {}, byEmail: {} });
+	});
+
+	it("saves and reloads quota entries", async () => {
+		const { loadQuotaCache, saveQuotaCache, getQuotaCachePath } = await import(
+			"../lib/quota-cache.js"
+		);
+
+		await saveQuotaCache({
+			byAccountId: {
+				acc_1: {
+					updatedAt: Date.now(),
+					status: 200,
+					model: "gpt-5-codex",
+					planType: "plus",
+					primary: { usedPercent: 40, windowMinutes: 300 },
+					secondary: { usedPercent: 20, windowMinutes: 10080 },
+				},
+			},
+			byEmail: {},
+		});
+
+		const loaded = await loadQuotaCache();
+		expect(loaded.byAccountId.acc_1?.primary.usedPercent).toBe(40);
+
+		const fileContent = await fs.readFile(getQuotaCachePath(), "utf8");
+		expect(fileContent).toContain("\"version\": 1");
+	});
+
+	it("ignores cache files with unsupported version", async () => {
+		const { loadQuotaCache, getQuotaCachePath } = await import("../lib/quota-cache.js");
+		await fs.writeFile(
+			getQuotaCachePath(),
+			JSON.stringify({
+				version: 2,
+				byAccountId: {
+					acc_1: {
+						updatedAt: Date.now(),
+						status: 200,
+						model: "gpt-5-codex",
+						primary: { usedPercent: 10 },
+						secondary: { usedPercent: 5 },
+					},
+				},
+				byEmail: {},
+			}),
+			"utf8",
+		);
+
+		const loaded = await loadQuotaCache();
+		expect(loaded).toEqual({ byAccountId: {}, byEmail: {} });
+	});
+
+	it("retries transient EBUSY while loading cache", async () => {
+		const { loadQuotaCache, getQuotaCachePath } = await import("../lib/quota-cache.js");
+		await fs.writeFile(
+			getQuotaCachePath(),
+			JSON.stringify({
+				version: 1,
+				byAccountId: {
+					acc_1: {
+						updatedAt: Date.now(),
+						status: 200,
+						model: "gpt-5-codex",
+						primary: { usedPercent: 10 },
+						secondary: { usedPercent: 5 },
+					},
+				},
+				byEmail: {},
+			}),
+			"utf8",
+		);
+
+		const realRead = fs.readFile.bind(fs);
+		let attempts = 0;
+		const readSpy = vi.spyOn(fs, "readFile");
+		readSpy.mockImplementation(async (...args) => {
+			if (String(args[0]) === getQuotaCachePath()) {
+				attempts += 1;
+				if (attempts === 1) {
+					const error = new Error("busy") as NodeJS.ErrnoException;
+					error.code = "EBUSY";
+					throw error;
+				}
+			}
+			return realRead(...args);
+		});
+
+		try {
+			const loaded = await loadQuotaCache();
+			expect(loaded.byAccountId.acc_1?.model).toBe("gpt-5-codex");
+			expect(attempts).toBe(2);
+		} finally {
+			readSpy.mockRestore();
+		}
+	});
+
+	it.each(["EBUSY", "EPERM"] as const)(
+		"retries atomic rename on transient %s errors",
+		async (code) => {
+			const { saveQuotaCache, loadQuotaCache } = await import("../lib/quota-cache.js");
+			const realRename = fs.rename;
+			const renameSpy = vi.spyOn(fs, "rename");
+			let attempts = 0;
+			renameSpy.mockImplementation(async (...args) => {
+				attempts += 1;
+				if (attempts < 3) {
+					const error = new Error(`rename failed: ${code}`) as NodeJS.ErrnoException;
+					error.code = code;
+					throw error;
+				}
+				return realRename(...args);
+			});
+
+			try {
+				await saveQuotaCache({
+					byAccountId: {
+						acc_1: {
+							updatedAt: Date.now(),
+							status: 200,
+							model: "gpt-5-codex",
+							primary: { usedPercent: 40, windowMinutes: 300 },
+							secondary: { usedPercent: 20, windowMinutes: 10080 },
+						},
+					},
+					byEmail: {},
+				});
+				const loaded = await loadQuotaCache();
+				expect(loaded.byAccountId.acc_1?.model).toBe("gpt-5-codex");
+				expect(attempts).toBe(3);
+			} finally {
+				renameSpy.mockRestore();
+			}
+		},
+	);
+
+	it("cleans up temp files when rename keeps failing", async () => {
+		const { saveQuotaCache } = await import("../lib/quota-cache.js");
+		const renameSpy = vi.spyOn(fs, "rename");
+		const unlinkSpy = vi.spyOn(fs, "unlink");
+		renameSpy.mockImplementation(async () => {
+			const error = new Error("locked") as NodeJS.ErrnoException;
+			error.code = "EPERM";
+			throw error;
+		});
+
+		try {
+			await saveQuotaCache({
+				byAccountId: {
+					acc_1: {
+						updatedAt: Date.now(),
+						status: 200,
+						model: "gpt-5-codex",
+						primary: { usedPercent: 40, windowMinutes: 300 },
+						secondary: { usedPercent: 20, windowMinutes: 10080 },
+					},
+				},
+				byEmail: {},
+			});
+
+			expect(unlinkSpy).toHaveBeenCalledTimes(1);
+			const entries = await fs.readdir(tempDir);
+			expect(entries.some((entry) => entry.endsWith(".tmp"))).toBe(false);
+		} finally {
+			unlinkSpy.mockRestore();
+			renameSpy.mockRestore();
+		}
+	});
+
+	it("logs sanitized cache filename for load/save failures", async () => {
+		vi.resetModules();
+		const warnMock = vi.fn();
+		vi.doMock("../lib/logger.js", () => ({
+			logWarn: warnMock,
+		}));
+		try {
+			const { getQuotaCachePath, loadQuotaCache, saveQuotaCache } = await import(
+				"../lib/quota-cache.js"
+			);
+			await fs.writeFile(getQuotaCachePath(), "{}", "utf8");
+
+			const readSpy = vi.spyOn(fs, "readFile");
+			readSpy.mockRejectedValueOnce(new Error("read failed"));
+			await loadQuotaCache();
+			readSpy.mockRestore();
+
+			const renameSpy = vi.spyOn(fs, "rename");
+			renameSpy.mockImplementation(async () => {
+				const error = new Error("rename failed") as NodeJS.ErrnoException;
+				error.code = "EIO";
+				throw error;
+			});
+			await saveQuotaCache({ byAccountId: {}, byEmail: {} });
+			renameSpy.mockRestore();
+
+			const logMessages = warnMock.mock.calls.map((args) => String(args[0]));
+			expect(logMessages.some((message) => message.includes("quota-cache.json"))).toBe(true);
+			expect(logMessages.some((message) => message.includes(tempDir))).toBe(false);
+		} finally {
+			vi.doUnmock("../lib/logger.js");
+		}
+	});
+});
diff --git a/test/quota-probe.test.ts b/test/quota-probe.test.ts
new file mode 100644
index 00000000..efab28b7
--- /dev/null
+++ b/test/quota-probe.test.ts
@@ -0,0 +1,173 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const {
+	getCodexInstructionsMock,
+	createCodexHeadersMock,
+	getUnsupportedCodexModelInfoMock,
+} = vi.hoisted(() => ({
+	getCodexInstructionsMock: vi.fn(async (model: string) => `instructions:${model}`),
+	createCodexHeadersMock: vi.fn(() => new Headers()),
+	getUnsupportedCodexModelInfoMock: vi.fn(() => ({
+		isUnsupported: false,
+		unsupportedModel: undefined,
+		message: undefined,
+	})),
+}));
+
+vi.mock("../lib/prompts/codex.js", () => ({
+	getCodexInstructions: getCodexInstructionsMock,
+}));
+
+vi.mock("../lib/request/fetch-helpers.js", () => ({
+	createCodexHeaders: createCodexHeadersMock,
+	getUnsupportedCodexModelInfo: getUnsupportedCodexModelInfoMock,
+}));
+
+import { fetchCodexQuotaSnapshot, formatQuotaSnapshotLine } from "../lib/quota-probe.js";
+
+function makeQuotaHeaders(overrides: Record<string, string> = {}): Headers {
+	const headers = new Headers({
+		"x-codex-primary-used-percent": "32",
+		"x-codex-primary-window-minutes": "300",
+		"x-codex-primary-reset-after-seconds": "120",
+		"x-codex-secondary-used-percent": "64",
+		"x-codex-secondary-window-minutes": "10080",
+		"x-codex-secondary-reset-after-seconds": "600",
+		"x-codex-plan-type": "plus",
+		...overrides,
+	});
+	return headers;
+}
+
+describe("quota-probe", () => {
+	beforeEach(() => {
+		vi.restoreAllMocks();
+		vi.useRealTimers();
+		getCodexInstructionsMock.mockClear();
+		createCodexHeadersMock.mockClear();
+		getUnsupportedCodexModelInfoMock.mockReset();
+		getUnsupportedCodexModelInfoMock.mockReturnValue({
+			isUnsupported: false,
+			unsupportedModel: undefined,
+			message: undefined,
+		});
+	});
+
+	afterEach(() => {
+		vi.unstubAllGlobals();
+		vi.useRealTimers();
+	});
+
+	it("returns parsed quota snapshot from response headers", async () => {
+		const fetchMock = vi.fn(async () => new Response("", { status: 200, headers: makeQuotaHeaders() }));
+		vi.stubGlobal("fetch", fetchMock);
+
+		const snapshot = await fetchCodexQuotaSnapshot({
+			accountId: "acc-1",
+			accessToken: "token-1",
+			model: "gpt-5-codex",
+			fallbackModels: ["gpt-5.2-codex"],
+		});
+
+		expect(snapshot.model).toBe("gpt-5-codex");
+		expect(snapshot.status).toBe(200);
+		expect(snapshot.primary.usedPercent).toBe(32);
+		expect(snapshot.secondary.usedPercent).toBe(64);
+		expect(snapshot.planType).toBe("plus");
+		expect(formatQuotaSnapshotLine(snapshot)).toContain("5h");
+		expect(fetchMock).toHaveBeenCalledTimes(1);
+	});
+
+	it("falls back to next model when first model is unsupported", async () => {
+		const unsupported = new Response(
+			JSON.stringify({
+				error: { message: "Model gpt-5.3-codex unsupported", type: "invalid_request_error" },
+			}),
+			{ status: 400, headers: new Headers({ "content-type": "application/json" }) },
+		);
+		const ok = new Response("", {
+			status: 200,
+			headers: makeQuotaHeaders({ "x-codex-primary-used-percent": "11" }),
+		});
+		const fetchMock = vi.fn().mockResolvedValueOnce(unsupported).mockResolvedValueOnce(ok);
+		vi.stubGlobal("fetch", fetchMock);
+
+		getUnsupportedCodexModelInfoMock
+			.mockReturnValueOnce({
+				isUnsupported: true,
+				unsupportedModel: "gpt-5.3-codex",
+				message: "unsupported",
+			})
+			.mockReturnValue({
+				isUnsupported: false,
+				unsupportedModel: undefined,
+				message: undefined,
+			});
+
+		const snapshot = await fetchCodexQuotaSnapshot({
+			accountId: "acc-1",
+			accessToken: "token-1",
+			model: "gpt-5.3-codex",
+			fallbackModels: ["gpt-5.2-codex"],
+		});
+
+		expect(snapshot.model).toBe("gpt-5.2-codex");
+		expect(fetchMock).toHaveBeenCalledTimes(2);
+		expect(getCodexInstructionsMock).toHaveBeenNthCalledWith(1, "gpt-5.3-codex");
+		expect(getCodexInstructionsMock).toHaveBeenNthCalledWith(2, "gpt-5.2-codex");
+	});
+
+	it("accepts 429 responses when quota headers are present", async () => {
+		const fetchMock = vi.fn(async () =>
+			new Response("", {
+				status: 429,
+				headers: makeQuotaHeaders({ "x-codex-secondary-used-percent": "100" }),
+			}),
+		);
+		vi.stubGlobal("fetch", fetchMock);
+
+		const snapshot = await fetchCodexQuotaSnapshot({
+			accountId: "acc-1",
+			accessToken: "token-1",
+			model: "gpt-5-codex",
+			fallbackModels: ["gpt-5.2-codex"],
+		});
+
+		expect(snapshot.status).toBe(429);
+		expect(formatQuotaSnapshotLine(snapshot)).toContain("rate-limited");
+	});
+
+	it("times out a stalled probe and surfaces abort failure", async () => {
+		vi.useFakeTimers();
+		const fetchMock = vi.fn((_url: string, init?: RequestInit) => {
+			return new Promise<Response>((_resolve, reject) => {
+				const signal = init?.signal;
+				if (signal) {
+					signal.addEventListener(
+						"abort",
+						() => {
+							const error = new Error("aborted");
+							(error as Error & { name?: string }).name = "AbortError";
+							reject(error);
+						},
+						{ once: true },
+					);
+				}
+			});
+		});
+		vi.stubGlobal("fetch", fetchMock);
+
+		const pending = fetchCodexQuotaSnapshot({
+			accountId: "acc-timeout",
+			accessToken: "token-timeout",
+			model: "gpt-5-codex",
+			fallbackModels: [],
+			timeoutMs: 1_000,
+		});
+		const assertion = expect(pending).rejects.toThrow(/abort/i);
+
+		await vi.advanceTimersByTimeAsync(1_100);
+		await assertion;
+		expect(fetchMock).toHaveBeenCalledTimes(1);
+	});
+});
diff --git a/test/recovery-constants.test.ts b/test/recovery-constants.test.ts
index 42f0d6ae..f8caa21e 100644
--- a/test/recovery-constants.test.ts
+++ b/test/recovery-constants.test.ts
@@ -25,18 +25,18 @@ describe("recovery/constants.ts", () => {
       Object.defineProperty(process, "platform", { value: "linux" });
       process.env.XDG_DATA_HOME = "/custom/xdg/data";
 
-      const { OPENCODE_STORAGE } = await import("../lib/recovery/constants.js");
+      const { CODEX_STORAGE } = await import("../lib/recovery/constants.js");
 
-      expect(OPENCODE_STORAGE).toBe(join("/custom/xdg/data", "opencode", "storage"));
+      expect(CODEX_STORAGE).toBe(join("/custom/xdg/data", "codex", "storage"));
     });
 
     it("should fallback to ~/.local/share when XDG_DATA_HOME is not set", async () => {
       Object.defineProperty(process, "platform", { value: "linux" });
       delete process.env.XDG_DATA_HOME;
 
-      const { OPENCODE_STORAGE } = await import("../lib/recovery/constants.js");
+      const { CODEX_STORAGE } = await import("../lib/recovery/constants.js");
 
-      expect(OPENCODE_STORAGE).toBe(join(homedir(), ".local", "share", "opencode", "storage"));
+      expect(CODEX_STORAGE).toBe(join(homedir(), ".local", "share", "codex", "storage"));
     });
   });
 
@@ -45,18 +45,18 @@ describe("recovery/constants.ts", () => {
       Object.defineProperty(process, "platform", { value: "win32" });
       process.env.APPDATA = "C:\\Users\\Test\\AppData\\Roaming";
 
-      const { OPENCODE_STORAGE } = await import("../lib/recovery/constants.js");
+      const { CODEX_STORAGE } = await import("../lib/recovery/constants.js");
 
-      expect(OPENCODE_STORAGE).toBe(join("C:\\Users\\Test\\AppData\\Roaming", "opencode", "storage"));
+      expect(CODEX_STORAGE).toBe(join("C:\\Users\\Test\\AppData\\Roaming", "codex", "storage"));
     });
 
     it("should fallback to AppData/Roaming when APPDATA is not set", async () => {
       Object.defineProperty(process, "platform", { value: "win32" });
       delete process.env.APPDATA;
 
-      const { OPENCODE_STORAGE } = await import("../lib/recovery/constants.js");
+      const { CODEX_STORAGE } = await import("../lib/recovery/constants.js");
 
-      expect(OPENCODE_STORAGE).toBe(join(homedir(), "AppData", "Roaming", "opencode", "storage"));
+      expect(CODEX_STORAGE).toBe(join(homedir(), "AppData", "Roaming", "codex", "storage"));
     });
   });
 
diff --git a/test/refresh-guardian.test.ts b/test/refresh-guardian.test.ts
new file mode 100644
index 00000000..678a6ee3
--- /dev/null
+++ b/test/refresh-guardian.test.ts
@@ -0,0 +1,352 @@
+import { describe, expect, it, beforeEach, afterEach, vi } from "vitest";
+import type { AccountManager, ManagedAccount } from "../lib/accounts.js";
+
+const refreshExpiringAccountsMock = vi.fn();
+const applyRefreshResultMock = vi.fn();
+
+vi.mock("../lib/proactive-refresh.js", () => ({
+	refreshExpiringAccounts: refreshExpiringAccountsMock,
+	applyRefreshResult: applyRefreshResultMock,
+}));
+
+function createManagedAccount(index: number): ManagedAccount {
+	return {
+		index,
+		refreshToken: `refresh-${index}`,
+		addedAt: Date.now() - 10_000,
+		lastUsed: Date.now() - 5_000,
+		rateLimitResetTimes: {},
+		enabled: true,
+	};
+}
+
+function createManagerMock(accounts: ManagedAccount[]): AccountManager {
+	return {
+		getAccountsSnapshot: vi.fn(() => accounts),
+		getAccountByIndex: vi.fn((index: number) => accounts.find((account) => account.index === index) ?? null),
+		clearAuthFailures: vi.fn(),
+		markAccountCoolingDown: vi.fn(),
+		setAccountEnabled: vi.fn(),
+		saveToDiskDebounced: vi.fn(),
+	} as unknown as AccountManager;
+}
+
+describe("refresh-guardian", () => {
+	beforeEach(() => {
+		vi.useFakeTimers();
+		vi.setSystemTime(new Date("2026-02-26T00:00:00.000Z"));
+		refreshExpiringAccountsMock.mockReset();
+		applyRefreshResultMock.mockReset();
+	});
+
+	afterEach(() => {
+		vi.useRealTimers();
+		vi.restoreAllMocks();
+	});
+
+	it("applies refresh outcomes and updates stats", async () => {
+		const accountA = createManagedAccount(0);
+		const accountB = createManagedAccount(1);
+		const manager = createManagerMock([accountA, accountB]);
+		const { RefreshGuardian } = await import("../lib/refresh-guardian.js");
+		const guardian = new RefreshGuardian(() => manager, { bufferMs: 60_000, intervalMs: 5_000 });
+
+		refreshExpiringAccountsMock.mockResolvedValue(
+			new Map([
+				[
+					0,
+					{
+						refreshed: true,
+						reason: "success",
+						tokenResult: {
+							type: "success",
+							access: "access-0",
+							refresh: "refresh-0-new",
+							expires: Date.now() + 3_600_000,
+						},
+					},
+				],
+				[
+					1,
+					{
+						refreshed: true,
+						reason: "failed",
+						tokenResult: {
+							type: "failed",
+							reason: "invalid_response",
+							message: "invalid payload",
+						},
+					},
+				],
+			]),
+		);
+
+		await guardian.tick();
+
+		expect(refreshExpiringAccountsMock).toHaveBeenCalledTimes(1);
+		expect(applyRefreshResultMock).toHaveBeenCalledTimes(1);
+		expect(applyRefreshResultMock).toHaveBeenCalledWith(
+			accountA,
+			expect.objectContaining({ type: "success" }),
+		);
+		expect((manager.clearAuthFailures as ReturnType<typeof vi.fn>)).toHaveBeenCalledWith(accountA);
+		expect((manager.markAccountCoolingDown as ReturnType<typeof vi.fn>)).toHaveBeenCalledWith(
+			accountB,
+			60_000,
+			"auth-failure",
+		);
+		expect((manager.saveToDiskDebounced as ReturnType<typeof vi.fn>)).toHaveBeenCalledTimes(1);
+
+		const stats = guardian.getStats();
+		expect(stats.runs).toBe(1);
+		expect(stats.refreshed).toBe(1);
+		expect(stats.failed).toBe(1);
+		expect(stats.authFailed).toBe(1);
+		expect(stats.networkFailed).toBe(0);
+		expect(stats.rateLimited).toBe(0);
+		expect(stats.notNeeded).toBe(0);
+		expect(stats.noRefreshToken).toBe(0);
+		expect(stats.lastRunAt).not.toBeNull();
+	});
+
+	it("skips overlapping tick executions", async () => {
+		const accountA = createManagedAccount(0);
+		const manager = createManagerMock([accountA]);
+		const { RefreshGuardian } = await import("../lib/refresh-guardian.js");
+		const guardian = new RefreshGuardian(() => manager, { intervalMs: 5_000 });
+
+		let release: (() => void) | null = null;
+		const pending = new Promise<Map<number, unknown>>((resolve) => {
+			release = () => resolve(new Map());
+		});
+		refreshExpiringAccountsMock.mockReturnValue(pending);
+
+		const first = guardian.tick();
+		const second = guardian.tick();
+		expect(refreshExpiringAccountsMock).toHaveBeenCalledTimes(1);
+
+		release?.();
+		await first;
+		await second;
+	});
+
+	it("runs on interval start and stops cleanly", async () => {
+		const manager = createManagerMock([]);
+		const { RefreshGuardian } = await import("../lib/refresh-guardian.js");
+		const guardian = new RefreshGuardian(() => manager, { intervalMs: 5_000 });
+		const tickSpy = vi.spyOn(guardian, "tick").mockResolvedValue(undefined);
+
+		guardian.start();
+		await vi.advanceTimersByTimeAsync(5_000);
+		expect(tickSpy).toHaveBeenCalledTimes(1);
+
+		guardian.stop();
+		await vi.advanceTimersByTimeAsync(15_000);
+		expect(tickSpy).toHaveBeenCalledTimes(1);
+	});
+
+	it("resolves refreshed account using stable refresh token when indices shift", async () => {
+		const originalA = createManagedAccount(0);
+		const originalB = createManagedAccount(1);
+		const liveB = { ...originalB, index: 0 };
+		const liveA = { ...originalA, index: 1 };
+		const snapshots = [[originalA, originalB], [liveB, liveA]];
+		let readCount = 0;
+		const manager = {
+			getAccountsSnapshot: vi.fn(() => snapshots[Math.min(readCount++, snapshots.length - 1)]),
+			getAccountByIndex: vi.fn((index: number) => [liveB, liveA].find((account) => account.index === index) ?? null),
+			clearAuthFailures: vi.fn(),
+			markAccountCoolingDown: vi.fn(),
+			saveToDiskDebounced: vi.fn(),
+		} as unknown as AccountManager;
+		const { RefreshGuardian } = await import("../lib/refresh-guardian.js");
+		const guardian = new RefreshGuardian(() => manager, { bufferMs: 60_000, intervalMs: 5_000 });
+
+		refreshExpiringAccountsMock.mockResolvedValue(
+			new Map([
+				[
+					1,
+					{
+						refreshed: true,
+						reason: "success",
+						tokenResult: {
+							type: "success",
+							access: "access-shifted",
+							refresh: "refresh-shifted",
+							expires: Date.now() + 3_600_000,
+						},
+					},
+				],
+			]),
+		);
+
+		await guardian.tick();
+
+		expect(applyRefreshResultMock).toHaveBeenCalledTimes(1);
+		expect(applyRefreshResultMock).toHaveBeenCalledWith(
+			liveB,
+			expect.objectContaining({ type: "success" }),
+		);
+		expect((manager.clearAuthFailures as ReturnType<typeof vi.fn>)).toHaveBeenCalledWith(liveB);
+	});
+
+	it("classifies failure reasons and handles no-op branches", async () => {
+		const accountA = createManagedAccount(0);
+		const accountB = createManagedAccount(1);
+		const accountC = createManagedAccount(2);
+		const accountD = createManagedAccount(3);
+		const accountE = createManagedAccount(4);
+		const manager = createManagerMock([accountA, accountB, accountC, accountD, accountE]);
+		const { RefreshGuardian } = await import("../lib/refresh-guardian.js");
+		const guardian = new RefreshGuardian(() => manager, { bufferMs: 60_000, intervalMs: 5_000 });
+
+		refreshExpiringAccountsMock.mockResolvedValue(
+			new Map([
+				[0, { refreshed: false, reason: "not_needed" }],
+				[1, { refreshed: false, reason: "no_refresh_token" }],
+				[
+					2,
+					{
+						refreshed: true,
+						reason: "failed",
+						tokenResult: {
+							type: "failed",
+							reason: "http_error",
+							statusCode: 429,
+							message: "rate limited",
+						},
+					},
+				],
+				[
+					3,
+					{
+						refreshed: true,
+						reason: "failed",
+						tokenResult: {
+							type: "failed",
+							reason: "network_error",
+							message: "timeout",
+						},
+					},
+				],
+				[
+					4,
+					{
+						refreshed: true,
+						reason: "failed",
+						tokenResult: {
+							type: "failed",
+							reason: "http_error",
+							statusCode: 401,
+							message: "expired",
+						},
+					},
+				],
+			]),
+		);
+
+		await guardian.tick();
+
+		expect((manager.setAccountEnabled as ReturnType<typeof vi.fn>)).toHaveBeenCalledWith(1, false);
+		expect((manager.markAccountCoolingDown as ReturnType<typeof vi.fn>)).toHaveBeenNthCalledWith(
+			1,
+			accountB,
+			60_000,
+			"auth-failure",
+		);
+		expect((manager.markAccountCoolingDown as ReturnType<typeof vi.fn>)).toHaveBeenNthCalledWith(
+			2,
+			accountC,
+			60_000,
+			"rate-limit",
+		);
+		expect((manager.markAccountCoolingDown as ReturnType<typeof vi.fn>)).toHaveBeenNthCalledWith(
+			3,
+			accountD,
+			60_000,
+			"network-error",
+		);
+		expect((manager.markAccountCoolingDown as ReturnType<typeof vi.fn>)).toHaveBeenNthCalledWith(
+			4,
+			accountE,
+			60_000,
+			"auth-failure",
+		);
+
+		const stats = guardian.getStats();
+		expect(stats.runs).toBe(1);
+		expect(stats.refreshed).toBe(0);
+		expect(stats.failed).toBe(4);
+		expect(stats.notNeeded).toBe(1);
+		expect(stats.noRefreshToken).toBe(1);
+		expect(stats.rateLimited).toBe(1);
+		expect(stats.networkFailed).toBe(1);
+		expect(stats.authFailed).toBe(2);
+	});
+
+	it("handles account removal during tick without throwing", async () => {
+		const originalA = createManagedAccount(0);
+		const originalB = createManagedAccount(1);
+		const liveAfterRemoval = [{ ...originalB }];
+		let snapshotReads = 0;
+
+		const manager = {
+			getAccountsSnapshot: vi.fn(() => {
+				snapshotReads += 1;
+				if (snapshotReads === 1) return [originalA, originalB];
+				return liveAfterRemoval;
+			}),
+			getAccountByIndex: vi.fn((index: number) => liveAfterRemoval[index] ?? null),
+			clearAuthFailures: vi.fn(),
+			markAccountCoolingDown: vi.fn(),
+			setAccountEnabled: vi.fn(),
+			saveToDiskDebounced: vi.fn(),
+		} as unknown as AccountManager;
+
+		const { RefreshGuardian } = await import("../lib/refresh-guardian.js");
+		const guardian = new RefreshGuardian(() => manager, { bufferMs: 60_000, intervalMs: 5_000 });
+
+		refreshExpiringAccountsMock.mockResolvedValue(
+			new Map([
+				[
+					0,
+					{
+						refreshed: true,
+						reason: "success",
+						tokenResult: {
+							type: "success",
+							access: "removed-access",
+							refresh: "removed-refresh",
+							expires: Date.now() + 3_600_000,
+						},
+					},
+				],
+				[
+					1,
+					{
+						refreshed: true,
+						reason: "failed",
+						tokenResult: {
+							type: "failed",
+							reason: "http_error",
+							statusCode: 429,
+							message: "rate limit",
+						},
+					},
+				],
+			]),
+		);
+
+		await expect(guardian.tick()).resolves.toBeUndefined();
+		expect(applyRefreshResultMock).not.toHaveBeenCalledWith(
+			expect.objectContaining({ refreshToken: originalA.refreshToken }),
+			expect.anything(),
+		);
+		expect((manager.markAccountCoolingDown as ReturnType<typeof vi.fn>)).toHaveBeenCalledWith(
+			expect.objectContaining({ refreshToken: originalB.refreshToken }),
+			60_000,
+			"rate-limit",
+		);
+	});
+});
+
diff --git a/test/refresh-lease.test.ts b/test/refresh-lease.test.ts
new file mode 100644
index 00000000..b6b9d322
--- /dev/null
+++ b/test/refresh-lease.test.ts
@@ -0,0 +1,213 @@
+import * as fsPromises from "node:fs/promises";
+import { mkdtemp, mkdir, writeFile, readFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createHash } from "node:crypto";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { RefreshLeaseCoordinator } from "../lib/refresh-lease.js";
+
+const sampleSuccessResult = {
+	type: "success" as const,
+	access: "access-token",
+	refresh: "refresh-token-next",
+	expires: Date.now() + 60_000,
+};
+
+function hashToken(refreshToken: string): string {
+	return createHash("sha256").update(refreshToken).digest("hex");
+}
+
+describe("RefreshLeaseCoordinator", () => {
+	let leaseDir = "";
+
+	beforeEach(async () => {
+		leaseDir = await mkdtemp(join(tmpdir(), "codex-refresh-lease-"));
+	});
+
+	afterEach(() => {
+		leaseDir = "";
+		vi.restoreAllMocks();
+	});
+
+	it("returns owner then follower with shared result", async () => {
+		const coordinator = new RefreshLeaseCoordinator({
+			enabled: true,
+			leaseDir,
+			leaseTtlMs: 5_000,
+			waitTimeoutMs: 500,
+			pollIntervalMs: 25,
+			resultTtlMs: 2_000,
+		});
+
+		const owner = await coordinator.acquire("token-a");
+		expect(owner.role).toBe("owner");
+		await owner.release(sampleSuccessResult);
+
+		const follower = await coordinator.acquire("token-a");
+		expect(follower.role).toBe("follower");
+		expect(follower.result).toEqual(sampleSuccessResult);
+	});
+
+	it("recovers from stale lock payload", async () => {
+		const coordinator = new RefreshLeaseCoordinator({
+			enabled: true,
+			leaseDir,
+			leaseTtlMs: 2_000,
+			waitTimeoutMs: 300,
+			pollIntervalMs: 20,
+		});
+
+		const tokenHash = "7f4a7c15f6f8c0f98d95c58f18f6f31e4f55cc4c52f8f4de4fd4d95a88e4866c";
+		await mkdir(leaseDir, { recursive: true });
+		await writeFile(
+			join(leaseDir, `${tokenHash}.lock`),
+			JSON.stringify({
+				tokenHash,
+				pid: 9999,
+				acquiredAt: Date.now() - 10_000,
+				expiresAt: Date.now() - 1_000,
+			}),
+			"utf8",
+		);
+
+		const handle = await coordinator.acquire("token-stale");
+		expect(handle.role).toBe("owner");
+		await handle.release(sampleSuccessResult);
+	});
+
+	it("supports bypass mode", async () => {
+		const coordinator = new RefreshLeaseCoordinator({
+			enabled: false,
+			leaseDir,
+		});
+		const handle = await coordinator.acquire("token-b");
+		expect(handle.role).toBe("bypass");
+		await handle.release(sampleSuccessResult);
+	});
+
+	it("does not delete unreadable lock payloads", async () => {
+		const refreshToken = "token-partial";
+		const coordinator = new RefreshLeaseCoordinator({
+			enabled: true,
+			leaseDir,
+			leaseTtlMs: 10_000,
+			waitTimeoutMs: 120,
+			pollIntervalMs: 25,
+			resultTtlMs: 2_000,
+		});
+		await mkdir(leaseDir, { recursive: true });
+		const tokenHash = hashToken(refreshToken);
+		const lockPath = join(leaseDir, `${tokenHash}.lock`);
+		await writeFile(lockPath, "{", "utf8");
+
+		const handle = await coordinator.acquire(refreshToken);
+		expect(handle.role).toBe("bypass");
+		const lockContent = await readFile(lockPath, "utf8");
+		expect(lockContent).toBe("{");
+	});
+
+	it("retries stale lock cleanup when unlink is temporarily busy", async () => {
+		const refreshToken = "token-retry";
+		const tokenHash = hashToken(refreshToken);
+		let busyCount = 0;
+		const originalUnlink = fsPromises.unlink.bind(fsPromises);
+		const fsOps = {
+			mkdir: fsPromises.mkdir.bind(fsPromises),
+			open: fsPromises.open.bind(fsPromises),
+			writeFile: fsPromises.writeFile.bind(fsPromises),
+			rename: fsPromises.rename.bind(fsPromises),
+			unlink: vi.fn(async (path: Parameters<typeof fsPromises.unlink>[0]) => {
+				if (String(path).endsWith(".lock") && busyCount < 2) {
+					busyCount += 1;
+					const error = new Error("busy") as NodeJS.ErrnoException;
+					error.code = "EBUSY";
+					throw error;
+				}
+				return originalUnlink(path);
+			}),
+			readFile: fsPromises.readFile.bind(fsPromises),
+			stat: fsPromises.stat.bind(fsPromises),
+			readdir: fsPromises.readdir.bind(fsPromises),
+		};
+
+		const coordinator = new RefreshLeaseCoordinator({
+			enabled: true,
+			leaseDir,
+			leaseTtlMs: 2_000,
+			waitTimeoutMs: 400,
+			pollIntervalMs: 20,
+			resultTtlMs: 2_000,
+			fsOps,
+		});
+
+		await mkdir(leaseDir, { recursive: true });
+		const lockPath = join(leaseDir, `${tokenHash}.lock`);
+		await writeFile(
+			lockPath,
+			JSON.stringify({
+				tokenHash,
+				pid: 1111,
+				acquiredAt: Date.now() - 10_000,
+				expiresAt: Date.now() - 5_000,
+			}),
+			"utf8",
+		);
+
+		const handle = await coordinator.acquire(refreshToken);
+		expect(handle.role).toBe("owner");
+		expect(fsOps.unlink).toHaveBeenCalled();
+		expect(busyCount).toBe(2);
+		await handle.release(sampleSuccessResult);
+	});
+
+	it("times out to bypass when stale lock cannot be deleted", async () => {
+		const refreshToken = "token-timeout";
+		const tokenHash = hashToken(refreshToken);
+		const originalUnlink = fsPromises.unlink.bind(fsPromises);
+		const fsOps = {
+			mkdir: fsPromises.mkdir.bind(fsPromises),
+			open: fsPromises.open.bind(fsPromises),
+			writeFile: fsPromises.writeFile.bind(fsPromises),
+			rename: fsPromises.rename.bind(fsPromises),
+			unlink: vi.fn(async (path: Parameters<typeof fsPromises.unlink>[0]) => {
+				if (String(path).endsWith(".lock")) {
+					const error = new Error("busy") as NodeJS.ErrnoException;
+					error.code = "EBUSY";
+					throw error;
+				}
+				return originalUnlink(path);
+			}),
+			readFile: fsPromises.readFile.bind(fsPromises),
+			stat: fsPromises.stat.bind(fsPromises),
+			readdir: fsPromises.readdir.bind(fsPromises),
+		};
+
+		const coordinator = new RefreshLeaseCoordinator({
+			enabled: true,
+			leaseDir,
+			leaseTtlMs: 2_000,
+			waitTimeoutMs: 140,
+			pollIntervalMs: 25,
+			resultTtlMs: 2_000,
+			fsOps,
+		});
+
+		await mkdir(leaseDir, { recursive: true });
+		const lockPath = join(leaseDir, `${tokenHash}.lock`);
+		await writeFile(
+			lockPath,
+			JSON.stringify({
+				tokenHash,
+				pid: 2222,
+				acquiredAt: Date.now() - 10_000,
+				expiresAt: Date.now() - 5_000,
+			}),
+			"utf8",
+		);
+
+		const handle = await coordinator.acquire(refreshToken);
+		expect(handle.role).toBe("bypass");
+		expect(fsOps.unlink).toHaveBeenCalled();
+		await handle.release(sampleSuccessResult);
+	});
+});
diff --git a/test/refresh-queue.test.ts b/test/refresh-queue.test.ts
index 9d535f3d..620f04b8 100644
--- a/test/refresh-queue.test.ts
+++ b/test/refresh-queue.test.ts
@@ -1,6 +1,10 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { mkdtemp } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import { RefreshQueue, getRefreshQueue, resetRefreshQueue, queuedRefresh } from "../lib/refresh-queue.js";
 import * as authModule from "../lib/auth/auth.js";
+import { RefreshLeaseCoordinator } from "../lib/refresh-lease.js";
 
 vi.mock("../lib/auth/auth.js", () => ({
   refreshAccessToken: vi.fn(),
@@ -9,6 +13,7 @@ vi.mock("../lib/auth/auth.js", () => ({
 vi.mock("../lib/logger.js", () => ({
   createLogger: () => ({
     info: vi.fn(),
+    debug: vi.fn(),
     warn: vi.fn(),
     error: vi.fn(),
   }),
@@ -93,6 +98,7 @@ describe("RefreshQueue", () => {
       const promise1 = queue.refresh("same-token");
       const promise2 = queue.refresh("same-token");
       const promise3 = queue.refresh("same-token");
+      await Promise.resolve();
 
       expect(authModule.refreshAccessToken).toHaveBeenCalledTimes(1);
 
@@ -197,6 +203,7 @@ describe("RefreshQueue", () => {
       expect(queue.pendingCount).toBe(1);
       
       const p2 = queue.refresh("token-2");
+      await Promise.resolve();
       expect(queue.pendingCount).toBe(2);
       
       resolvers[0]!();
@@ -325,6 +332,7 @@ describe("RefreshQueue", () => {
 			
 			const promise1 = queue.refresh("old-token");
 			expect(queue.pendingCount).toBe(1);
+			await Promise.resolve();
 			expect(authModule.refreshAccessToken).toHaveBeenCalledTimes(1);
 
 			resolveRefresh!({
@@ -362,6 +370,7 @@ describe("RefreshQueue", () => {
 			
 			const promise1 = queue.refresh("old-token");
 			expect(queue.pendingCount).toBe(1);
+			await Promise.resolve();
 			
 			innerResolve!({
 				type: "success",
@@ -398,6 +407,7 @@ describe("RefreshQueue", () => {
 			
 			const promise1 = queue.refresh("old-token");
 			expect(queue.pendingCount).toBe(1);
+			await Promise.resolve();
 			
 			outerResolve!({
 				type: "success",
@@ -482,6 +492,7 @@ describe("RefreshQueue", () => {
 			queueInternal.tokenRotationMap.set("old-token", "new-rotated-token");
 			
 			const promise2 = queue.refresh("new-rotated-token");
+			await Promise.resolve();
 			
 			expect(authModule.refreshAccessToken).toHaveBeenCalledTimes(1);
 			
@@ -553,6 +564,7 @@ describe("RefreshQueue", () => {
 			queueInternal.tokenRotationMap.set("original-token", "rotated-token");
 			
 			const promise2 = queue.refresh("rotated-token");
+			await Promise.resolve();
 			
 			expect(authModule.refreshAccessToken).toHaveBeenCalledTimes(1);
 			expect(authModule.refreshAccessToken).toHaveBeenCalledWith("original-token");
@@ -568,4 +580,104 @@ describe("RefreshQueue", () => {
 			expect(result1).toBe(result2);
 		});
 	});
+
+  describe("cross-process lease dedupe", () => {
+		it("reuses refresh result across queue instances via lease files", async () => {
+			const leaseDir = await mkdtemp(join(tmpdir(), "codex-refresh-lease-int-"));
+			const leaseA = new RefreshLeaseCoordinator({
+				enabled: true,
+				leaseDir,
+				leaseTtlMs: 5_000,
+				waitTimeoutMs: 2_000,
+				pollIntervalMs: 25,
+				resultTtlMs: 5_000,
+			});
+			const leaseB = new RefreshLeaseCoordinator({
+				enabled: true,
+				leaseDir,
+				leaseTtlMs: 5_000,
+				waitTimeoutMs: 2_000,
+				pollIntervalMs: 25,
+				resultTtlMs: 5_000,
+			});
+			const queueA = new RefreshQueue(30_000, leaseA);
+			const queueB = new RefreshQueue(30_000, leaseB);
+
+			const delayedResult = {
+				type: "success" as const,
+				access: "shared-access",
+				refresh: "shared-refresh-next",
+				expires: Date.now() + 3600000,
+			};
+			let releaseRefresh: (() => void) | null = null;
+			vi.mocked(authModule.refreshAccessToken).mockImplementation(() => {
+				return new Promise((resolve) => {
+					releaseRefresh = () => resolve(delayedResult);
+				});
+			});
+
+			const ownerRefresh = queueA.refresh("same-cross-token");
+			await new Promise((resolve) => setTimeout(resolve, 50));
+			const followerRefresh = queueB.refresh("same-cross-token");
+
+			releaseRefresh?.();
+
+			const [ownerResult, followerResult] = await Promise.all([
+				ownerRefresh,
+				followerRefresh,
+			]);
+			expect(ownerResult).toEqual(delayedResult);
+			expect(followerResult).toEqual(delayedResult);
+      expect(authModule.refreshAccessToken).toHaveBeenCalledTimes(1);
+    });
+  });
+
+	describe("lease failure handling", () => {
+		it("falls back to local refresh when lease acquisition throws", async () => {
+			const mockResult = {
+				type: "success" as const,
+				access: "fallback-access",
+				refresh: "fallback-refresh",
+				expires: Date.now() + 3600000,
+			};
+			vi.mocked(authModule.refreshAccessToken).mockResolvedValue(mockResult);
+
+			const leaseCoordinator = {
+				acquire: vi.fn().mockRejectedValue(new Error("EBUSY lease dir")),
+			} as unknown as RefreshLeaseCoordinator;
+
+			const queue = new RefreshQueue(30_000, leaseCoordinator);
+			const result = await queue.refresh("token-with-acquire-error");
+
+			expect(result).toEqual(mockResult);
+			expect(authModule.refreshAccessToken).toHaveBeenCalledTimes(1);
+		});
+
+		it("swallows lease release errors and still returns token result", async () => {
+			const mockResult = {
+				type: "success" as const,
+				access: "release-safe-access",
+				refresh: "release-safe-refresh",
+				expires: Date.now() + 3600000,
+			};
+			vi.mocked(authModule.refreshAccessToken).mockResolvedValue(mockResult);
+
+			const release = vi
+				.fn()
+				.mockRejectedValueOnce(new Error("publish failed"))
+				.mockRejectedValueOnce(new Error("unlock failed"));
+			const leaseCoordinator = {
+				acquire: vi.fn().mockResolvedValue({
+					role: "owner" as const,
+					release,
+				}),
+			} as unknown as RefreshLeaseCoordinator;
+
+			const queue = new RefreshQueue(30_000, leaseCoordinator);
+			const result = await queue.refresh("token-with-release-error");
+
+			expect(result).toEqual(mockResult);
+			expect(release).toHaveBeenCalledTimes(2);
+		});
+	});
 });
diff --git a/test/request-transformer.test.ts b/test/request-transformer.test.ts
index a09679a9..01eb228a 100644
--- a/test/request-transformer.test.ts
+++ b/test/request-transformer.test.ts
@@ -1488,7 +1488,7 @@ describe('Request Transformer Module', () => {
 				expect(result.model).toBe('gpt-5-codex');
 				expect(result.reasoning?.effort).toBe('high');
 				expect(result.reasoning?.summary).toBe('detailed');
-			});
+			}, 10_000);
 
 		it('should downgrade xhigh to high for non-max codex', async () => {
 			const body: RequestBody = {
diff --git a/test/rotation-integration.test.ts b/test/rotation-integration.test.ts
index 5cd5384e..c6489057 100644
--- a/test/rotation-integration.test.ts
+++ b/test/rotation-integration.test.ts
@@ -1,8 +1,35 @@
-import { describe, it, expect, beforeEach } from "vitest";
+import { promises as fs } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, it, expect, beforeAll, beforeEach, afterAll } from "vitest";
 import { AccountManager } from "../lib/accounts.js";
-import { deduplicateAccounts, deduplicateAccountsByEmail, type AccountStorageV3 } from "../lib/storage.js";
+import {
+  deduplicateAccounts,
+  deduplicateAccountsByEmail,
+  setStoragePathDirect,
+  type AccountStorageV3,
+} from "../lib/storage.js";
 import type { ModelFamily } from "../lib/prompts/codex.js";
 
+let testStorageDir: string;
+let testStoragePath: string;
+
+beforeAll(async () => {
+  testStorageDir = await fs.mkdtemp(join(tmpdir(), "codex-multi-auth-rotation-"));
+  testStoragePath = join(testStorageDir, "openai-codex-accounts.json");
+  setStoragePathDirect(testStoragePath);
+});
+
+beforeEach(async () => {
+  setStoragePathDirect(testStoragePath);
+  await fs.rm(testStoragePath, { force: true });
+});
+
+afterAll(async () => {
+  setStoragePathDirect(null);
+  await fs.rm(testStorageDir, { recursive: true, force: true });
+});
+
 const TEST_ACCOUNTS = [
   { email: "account1@example.com", refresh_token: "fake_refresh_token_1_for_testing_only" },
   { email: "account2@example.com", refresh_token: "fake_refresh_token_2_for_testing_only" },
diff --git a/test/rotation.test.ts b/test/rotation.test.ts
index 29ead08f..d8bdb1fa 100644
--- a/test/rotation.test.ts
+++ b/test/rotation.test.ts
@@ -438,6 +438,79 @@ describe("selectHybridAccount", () => {
 
 		expect(selectedIndices.size).toBeGreaterThan(1);
 	});
+
+	it("applies scoreBoostByAccount to deterministically change winner", () => {
+		const now = Date.now();
+		const accounts: AccountWithMetrics[] = [
+			{ index: 0, isAvailable: true, lastUsed: now },
+			{ index: 1, isAvailable: true, lastUsed: now },
+		];
+
+		const baseline = selectHybridAccount(accounts, healthTracker, tokenTracker);
+		expect(baseline?.index).toBe(0);
+
+		const boosted = selectHybridAccount(
+			accounts,
+			healthTracker,
+			tokenTracker,
+			undefined,
+			undefined,
+			{
+				scoreBoostByAccount: { 1: 25 },
+			},
+		);
+		expect(boosted?.index).toBe(1);
+	});
+
+	it("ignores non-finite score boosts", () => {
+		const now = Date.now();
+		const accounts: AccountWithMetrics[] = [
+			{ index: 0, isAvailable: true, lastUsed: now },
+			{ index: 1, isAvailable: true, lastUsed: now },
+		];
+
+		const baseline = selectHybridAccount(accounts, healthTracker, tokenTracker);
+		const withNan = selectHybridAccount(
+			accounts,
+			healthTracker,
+			tokenTracker,
+			undefined,
+			undefined,
+			{ scoreBoostByAccount: { 1: Number.NaN } },
+		);
+		const withInf = selectHybridAccount(
+			accounts,
+			healthTracker,
+			tokenTracker,
+			undefined,
+			undefined,
+			{ scoreBoostByAccount: { 1: Number.POSITIVE_INFINITY } },
+		);
+
+		expect(withNan?.index).toBe(baseline?.index);
+		expect(withInf?.index).toBe(baseline?.index);
+	});
+
+	it("keeps boost behavior stable when pid offset is enabled", () => {
+		const now = Date.now();
+		const accounts: AccountWithMetrics[] = [
+			{ index: 0, isAvailable: true, lastUsed: now },
+			{ index: 1, isAvailable: true, lastUsed: now },
+		];
+
+		const result = selectHybridAccount(
+			accounts,
+			healthTracker,
+			tokenTracker,
+			undefined,
+			undefined,
+			{
+				pidOffsetEnabled: true,
+				scoreBoostByAccount: { 1: 100 },
+			},
+		);
+		expect(result?.index).toBe(1);
+	});
 });
 
 describe("utility functions", () => {
diff --git a/test/schemas.test.ts b/test/schemas.test.ts
index 43e56689..16cd2f97 100644
--- a/test/schemas.test.ts
+++ b/test/schemas.test.ts
@@ -44,11 +44,80 @@ describe("PluginConfigSchema", () => {
 			autoResume: false,
 			fetchTimeoutMs: 60000,
 			streamStallTimeoutMs: 45000,
+			liveAccountSync: true,
+			liveAccountSyncDebounceMs: 250,
+			liveAccountSyncPollMs: 2000,
+			sessionAffinity: true,
+			sessionAffinityTtlMs: 1_200_000,
+			sessionAffinityMaxEntries: 512,
+			proactiveRefreshGuardian: true,
+			proactiveRefreshIntervalMs: 60_000,
+			proactiveRefreshBufferMs: 300_000,
+			networkErrorCooldownMs: 6000,
+			serverErrorCooldownMs: 4000,
+			preemptiveQuotaEnabled: true,
+			preemptiveQuotaRemainingPercent5h: 5,
+			preemptiveQuotaRemainingPercent7d: 5,
+			preemptiveQuotaMaxDeferralMs: 120_000,
 		};
 		const result = PluginConfigSchema.safeParse(config);
 		expect(result.success).toBe(true);
 	});
 
+	it.each([
+		["liveAccountSyncDebounceMs", 49, 50],
+		["liveAccountSyncPollMs", 499, 500],
+		["sessionAffinityTtlMs", 999, 1000],
+		["sessionAffinityMaxEntries", 7, 8],
+		["proactiveRefreshIntervalMs", 4999, 5000],
+		["proactiveRefreshBufferMs", 29_999, 30_000],
+		["preemptiveQuotaMaxDeferralMs", 999, 1000],
+	] as const)("enforces minimum for %s", (key, invalidValue, validValue) => {
+		const invalidResult = PluginConfigSchema.safeParse({ [key]: invalidValue });
+		const validResult = PluginConfigSchema.safeParse({ [key]: validValue });
+		expect(invalidResult.success).toBe(false);
+		expect(validResult.success).toBe(true);
+	});
+
+	it.each([
+		["networkErrorCooldownMs", -1, 0],
+		["serverErrorCooldownMs", -1, 0],
+	] as const)("allows zero and rejects negatives for %s", (key, invalidValue, validValue) => {
+		const invalidResult = PluginConfigSchema.safeParse({ [key]: invalidValue });
+		const validResult = PluginConfigSchema.safeParse({ [key]: validValue });
+		expect(invalidResult.success).toBe(false);
+		expect(validResult.success).toBe(true);
+	});
+
+	it.each([
+		["preemptiveQuotaRemainingPercent5h", -1, 0, 100, 101],
+		["preemptiveQuotaRemainingPercent7d", -1, 0, 100, 101],
+	] as const)(
+		"enforces 0-100 range for %s",
+		(key, belowMin, min, max, aboveMax) => {
+			expect(PluginConfigSchema.safeParse({ [key]: belowMin }).success).toBe(false);
+			expect(PluginConfigSchema.safeParse({ [key]: min }).success).toBe(true);
+			expect(PluginConfigSchema.safeParse({ [key]: max }).success).toBe(true);
+			expect(PluginConfigSchema.safeParse({ [key]: aboveMax }).success).toBe(false);
+		},
+	);
+
+	it.each([
+		"liveAccountSyncDebounceMs",
+		"liveAccountSyncPollMs",
+		"sessionAffinityTtlMs",
+		"sessionAffinityMaxEntries",
+		"proactiveRefreshIntervalMs",
+		"proactiveRefreshBufferMs",
+		"networkErrorCooldownMs",
+		"serverErrorCooldownMs",
+		"preemptiveQuotaRemainingPercent5h",
+		"preemptiveQuotaRemainingPercent7d",
+		"preemptiveQuotaMaxDeferralMs",
+	] as const)("rejects string values for numeric key %s", (key) => {
+		expect(PluginConfigSchema.safeParse({ [key]: "123" }).success).toBe(false);
+	});
+
 	it("rejects toastDurationMs below 1000", () => {
 		const result = PluginConfigSchema.safeParse({ toastDurationMs: 500 });
 		expect(result.success).toBe(false);
diff --git a/test/select.test.ts b/test/select.test.ts
new file mode 100644
index 00000000..8605bc62
--- /dev/null
+++ b/test/select.test.ts
@@ -0,0 +1,101 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("../lib/ui/ansi.js", async () => {
+	const actual = await vi.importActual<typeof import("../lib/ui/ansi.js")>(
+		"../lib/ui/ansi.js",
+	);
+	return {
+		...actual,
+		isTTY: () => true,
+	};
+});
+
+describe("ui select", () => {
+	const stdin = process.stdin as NodeJS.ReadStream & {
+		setRawMode?: (mode: boolean) => void;
+	};
+	const stdout = process.stdout;
+	let rawModeSpy: ReturnType<typeof vi.spyOn> | null = null;
+	let resumeSpy: ReturnType<typeof vi.spyOn> | null = null;
+	let pauseSpy: ReturnType<typeof vi.spyOn> | null = null;
+	let writeSpy: ReturnType<typeof vi.spyOn> | null = null;
+	let readSpy: ReturnType<typeof vi.spyOn> | null = null;
+
+	beforeEach(() => {
+		vi.resetModules();
+		vi.useFakeTimers();
+		if (typeof stdin.setRawMode !== "function") {
+			Object.defineProperty(stdin, "setRawMode", {
+				value: (_mode: boolean) => undefined,
+				configurable: true,
+				writable: true,
+			});
+		}
+		rawModeSpy = vi.spyOn(stdin, "setRawMode").mockImplementation(() => undefined);
+		resumeSpy = vi.spyOn(stdin, "resume").mockImplementation(() => stdin);
+		pauseSpy = vi.spyOn(stdin, "pause").mockImplementation(() => stdin);
+		writeSpy = vi.spyOn(stdout, "write").mockImplementation(() => true);
+		readSpy = vi.spyOn(stdin, "read").mockImplementation(() => null);
+	});
+
+	afterEach(() => {
+		vi.useRealTimers();
+		rawModeSpy?.mockRestore();
+		resumeSpy?.mockRestore();
+		pauseSpy?.mockRestore();
+		writeSpy?.mockRestore();
+		readSpy?.mockRestore();
+		vi.restoreAllMocks();
+	});
+
+	it("suppresses initial enter during the input guard window", async () => {
+		const { select } = await import("../lib/ui/select.js");
+		const selectPromise = select(
+			[
+				{ label: "A", value: "a" },
+				{ label: "B", value: "b" },
+			],
+			{
+				message: "Pick",
+				onInput: (input) => {
+					if (input === "x") return "hotkey-picked";
+					return undefined;
+				},
+			},
+		);
+
+		stdin.emit("data", Buffer.from("\r", "utf8"));
+		stdin.emit("data", Buffer.from("x", "utf8"));
+
+		const result = await selectPromise;
+		expect(result).toBe("hotkey-picked");
+	});
+
+	it("cleans up refresh interval and signal listeners on cancel", async () => {
+		const initialSigintCount = process.listenerCount("SIGINT");
+		const clearIntervalSpy = vi.spyOn(globalThis, "clearInterval");
+		const { select } = await import("../lib/ui/select.js");
+
+		const selectPromise = select(
+			[
+				{ label: "A", value: "a" },
+				{ label: "B", value: "b" },
+			],
+			{
+				message: "Pick",
+				dynamicSubtitle: () => "live",
+				refreshIntervalMs: 200,
+			},
+		);
+
+		await vi.advanceTimersByTimeAsync(130);
+		stdin.emit("data", Buffer.from("\x1b", "utf8"));
+		await vi.advanceTimersByTimeAsync(80);
+
+		const result = await selectPromise;
+		expect(result).toBeNull();
+		expect(clearIntervalSpy).toHaveBeenCalled();
+		expect(process.listenerCount("SIGINT")).toBe(initialSigintCount);
+		clearIntervalSpy.mockRestore();
+	});
+});
diff --git a/test/server.unit.test.ts b/test/server.unit.test.ts
index ec6fb6a4..41de8257 100644
--- a/test/server.unit.test.ts
+++ b/test/server.unit.test.ts
@@ -178,7 +178,7 @@ describe('OAuth Server Unit Tests', () => {
 			expect(res.setHeader).toHaveBeenCalledWith('X-Content-Type-Options', 'nosniff');
 			expect(res.setHeader).toHaveBeenCalledWith(
 				'Content-Security-Policy',
-				"default-src 'self'; script-src 'none'"
+				"default-src 'none'; style-src 'unsafe-inline'; img-src 'self' data:; font-src 'self' data:; script-src 'none'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'"
 			);
 			expect(res.end).toHaveBeenCalledWith('<html>Success</html>');
 		});
@@ -192,6 +192,21 @@ describe('OAuth Server Unit Tests', () => {
 			expect(mockServer._lastCode).toBe('captured-code');
 		});
 
+		it('should keep the first code when duplicate callbacks arrive', () => {
+			const firstReq = createMockRequest('/auth/callback?code=first-code&state=test-state');
+			const secondReq = createMockRequest('/auth/callback?code=second-code&state=test-state');
+			const firstRes = createMockResponse();
+			const secondRes = createMockResponse();
+
+			requestHandler(firstReq, firstRes);
+			requestHandler(secondReq, secondRes);
+
+			expect(mockServer._lastCode).toBe('first-code');
+			expect(logWarn).toHaveBeenCalledWith(
+				expect.stringContaining('Duplicate OAuth callback received'),
+			);
+		});
+
 		it('should handle request handler errors gracefully', () => {
 			const req = createMockRequest('/auth/callback?code=test&state=test-state');
 			const res = createMockResponse();
diff --git a/test/session-affinity.test.ts b/test/session-affinity.test.ts
new file mode 100644
index 00000000..3e5b7788
--- /dev/null
+++ b/test/session-affinity.test.ts
@@ -0,0 +1,55 @@
+import { describe, expect, it } from "vitest";
+import { SessionAffinityStore } from "../lib/session-affinity.js";
+
+describe("SessionAffinityStore", () => {
+	it("returns remembered account while entry is fresh", () => {
+		const store = new SessionAffinityStore({ ttlMs: 10_000 });
+		store.remember("session-a", 2, 1_000);
+
+		expect(store.getPreferredAccountIndex("session-a", 5_000)).toBe(2);
+	});
+
+	it("expires entries after ttl", () => {
+		const store = new SessionAffinityStore({ ttlMs: 1_000 });
+		store.remember("session-a", 1, 1_000);
+
+		expect(store.getPreferredAccountIndex("session-a", 2_500)).toBeNull();
+		expect(store.size()).toBe(0);
+	});
+
+	it("evicts oldest entry when max size is reached", () => {
+		const store = new SessionAffinityStore({ ttlMs: 60_000, maxEntries: 2 });
+		store.remember("s1", 0, 1_000);
+		store.remember("s2", 1, 2_000);
+		store.remember("s3", 2, 3_000);
+
+		expect(store.getPreferredAccountIndex("s1", 3_100)).toBeNull();
+		expect(store.getPreferredAccountIndex("s2", 3_100)).toBe(1);
+		expect(store.getPreferredAccountIndex("s3", 3_100)).toBe(2);
+	});
+
+	it("forgets all sessions mapped to account", () => {
+		const store = new SessionAffinityStore({ ttlMs: 60_000, maxEntries: 10 });
+		store.remember("s1", 0);
+		store.remember("s2", 1);
+		store.remember("s3", 1);
+
+		const removed = store.forgetAccount(1);
+		expect(removed).toBe(2);
+		expect(store.getPreferredAccountIndex("s2")).toBeNull();
+		expect(store.getPreferredAccountIndex("s3")).toBeNull();
+		expect(store.getPreferredAccountIndex("s1")).toBe(0);
+	});
+
+	it("reindexes sessions after account removal", () => {
+		const store = new SessionAffinityStore({ ttlMs: 60_000, maxEntries: 10 });
+		store.remember("s1", 0);
+		store.remember("s2", 2);
+		store.remember("s3", 3);
+
+		const shifted = store.reindexAfterRemoval(1);
+		expect(shifted).toBe(2);
+		expect(store.getPreferredAccountIndex("s2")).toBe(1);
+		expect(store.getPreferredAccountIndex("s3")).toBe(2);
+	});
+});
diff --git a/test/storage-async.test.ts b/test/storage-async.test.ts
index 49ed85ad..57c03412 100644
--- a/test/storage-async.test.ts
+++ b/test/storage-async.test.ts
@@ -14,6 +14,18 @@ import {
 } from "../lib/storage.js";
 
 describe("Storage Module - Async Operations", () => {
+  const _origCODEX_HOME = process.env.CODEX_HOME;
+  const _origCODEX_MULTI_AUTH_DIR = process.env.CODEX_MULTI_AUTH_DIR;
+
+  beforeEach(() => {
+    delete process.env.CODEX_HOME;
+    delete process.env.CODEX_MULTI_AUTH_DIR;
+  });
+
+  afterEach(() => {
+    if (_origCODEX_HOME !== undefined) process.env.CODEX_HOME = _origCODEX_HOME; else delete process.env.CODEX_HOME;
+    if (_origCODEX_MULTI_AUTH_DIR !== undefined) process.env.CODEX_MULTI_AUTH_DIR = _origCODEX_MULTI_AUTH_DIR; else delete process.env.CODEX_MULTI_AUTH_DIR;
+  });
   let testDir: string;
   let originalGetStoragePath: typeof getStoragePath;
 
@@ -262,9 +274,9 @@ describe("Storage Module - Async Operations", () => {
       expect(path).toMatch(/openai-codex-accounts\.json$/);
     });
 
-    it("returns path containing .opencode directory", () => {
+    it("returns path containing .codex directory", () => {
       const path = getStoragePath();
-      expect(path).toContain(".opencode");
+      expect(path).toContain(".codex");
     });
   });
 
diff --git a/test/storage-recovery-paths.test.ts b/test/storage-recovery-paths.test.ts
new file mode 100644
index 00000000..f4f63f79
--- /dev/null
+++ b/test/storage-recovery-paths.test.ts
@@ -0,0 +1,113 @@
+import { describe, expect, it, beforeEach, afterEach } from "vitest";
+import { promises as fs } from "node:fs";
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import {
+	loadAccounts,
+	setStorageBackupEnabled,
+	setStoragePathDirect,
+} from "../lib/storage.js";
+
+function sha256(value: string): string {
+	return createHash("sha256").update(value).digest("hex");
+}
+
+describe("storage recovery paths", () => {
+	let workDir = "";
+	let storagePath = "";
+
+	beforeEach(async () => {
+		workDir = join(tmpdir(), `codex-storage-recovery-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+		storagePath = join(workDir, "openai-codex-accounts.json");
+		await fs.mkdir(workDir, { recursive: true });
+		setStoragePathDirect(storagePath);
+		setStorageBackupEnabled(true);
+	});
+
+	afterEach(async () => {
+		setStoragePathDirect(null);
+		setStorageBackupEnabled(true);
+		await fs.rm(workDir, { recursive: true, force: true });
+	});
+
+	it("recovers from WAL journal when primary storage is unreadable", async () => {
+		await fs.writeFile(storagePath, "{invalid-json", "utf-8");
+
+		const walPayload = {
+			version: 3,
+			activeIndex: 0,
+			accounts: [
+				{
+					refreshToken: "wal-refresh",
+					accountId: "from-wal",
+					addedAt: 1,
+					lastUsed: 1,
+				},
+			],
+		};
+		const walContent = JSON.stringify(walPayload);
+		const walEntry = {
+			version: 1,
+			createdAt: Date.now(),
+			path: storagePath,
+			checksum: sha256(walContent),
+			content: walContent,
+		};
+		await fs.writeFile(`${storagePath}.wal`, JSON.stringify(walEntry), "utf-8");
+
+		const recovered = await loadAccounts();
+		expect(recovered?.accounts).toHaveLength(1);
+		expect(recovered?.accounts[0]?.accountId).toBe("from-wal");
+
+		const persisted = JSON.parse(await fs.readFile(storagePath, "utf-8")) as {
+			accounts?: Array<{ accountId?: string }>;
+		};
+		expect(persisted.accounts?.[0]?.accountId).toBe("from-wal");
+	});
+
+	it("recovers from backup file when WAL is unavailable", async () => {
+		await fs.writeFile(storagePath, "{still-invalid", "utf-8");
+
+		const backupPayload = {
+			version: 3,
+			activeIndex: 0,
+			accounts: [
+				{
+					refreshToken: "backup-refresh",
+					accountId: "from-backup",
+					addedAt: 2,
+					lastUsed: 2,
+				},
+			],
+		};
+		await fs.writeFile(`${storagePath}.bak`, JSON.stringify(backupPayload), "utf-8");
+
+		const recovered = await loadAccounts();
+		expect(recovered?.accounts).toHaveLength(1);
+		expect(recovered?.accounts[0]?.accountId).toBe("from-backup");
+
+		const persisted = JSON.parse(await fs.readFile(storagePath, "utf-8")) as {
+			accounts?: Array<{ accountId?: string }>;
+		};
+		expect(persisted.accounts?.[0]?.accountId).toBe("from-backup");
+	});
+
+	it("does not use backup recovery when backups are disabled", async () => {
+		setStorageBackupEnabled(false);
+		await fs.writeFile(storagePath, "{broken-primary", "utf-8");
+		await fs.writeFile(
+			`${storagePath}.bak`,
+			JSON.stringify({
+				version: 3,
+				activeIndex: 0,
+				accounts: [{ refreshToken: "backup-refresh", accountId: "disabled-backup", addedAt: 3, lastUsed: 3 }],
+			}),
+			"utf-8",
+		);
+
+		const recovered = await loadAccounts();
+		expect(recovered).toBeNull();
+	});
+});
+
diff --git a/test/storage.test.ts b/test/storage.test.ts
index 69f48d41..ddf137ca 100644
--- a/test/storage.test.ts
+++ b/test/storage.test.ts
@@ -25,6 +25,18 @@ import {
 // But Task 0 says: "Tests should fail initially (RED phase)"
 
 describe("storage", () => {
+  const _origCODEX_HOME = process.env.CODEX_HOME;
+  const _origCODEX_MULTI_AUTH_DIR = process.env.CODEX_MULTI_AUTH_DIR;
+
+  beforeEach(() => {
+    delete process.env.CODEX_HOME;
+    delete process.env.CODEX_MULTI_AUTH_DIR;
+  });
+
+  afterEach(() => {
+    if (_origCODEX_HOME !== undefined) process.env.CODEX_HOME = _origCODEX_HOME; else delete process.env.CODEX_HOME;
+    if (_origCODEX_MULTI_AUTH_DIR !== undefined) process.env.CODEX_MULTI_AUTH_DIR = _origCODEX_MULTI_AUTH_DIR; else delete process.env.CODEX_MULTI_AUTH_DIR;
+  });
   describe("deduplication", () => {
     it("remaps activeIndex after deduplication using active account key", () => {
       const now = Date.now();
@@ -680,7 +692,7 @@ describe("storage", () => {
 
     beforeEach(async () => {
       await fs.mkdir(testWorkDir, { recursive: true });
-      testStoragePath = join(testWorkDir, ".opencode", "accounts.json");
+      testStoragePath = join(testWorkDir, ".codex", "accounts.json");
       setStoragePathDirect(testStoragePath);
     });
 
@@ -739,20 +751,20 @@ describe("storage", () => {
     it("sets path to null when projectPath is null", () => {
       setStoragePath(null);
       const path = getStoragePath();
-      expect(path).toContain(".opencode");
+      expect(path).toContain(".codex");
     });
 
     it("sets path to null when no project root found", () => {
       setStoragePath("/nonexistent/path/that/does/not/exist");
       const path = getStoragePath();
-      expect(path).toContain(".opencode");
+      expect(path).toContain(".codex");
     });
 
-    it("sets project-scoped path under global .opencode when project root found", () => {
+    it("sets project-scoped path under global .codex when project root found", () => {
       setStoragePath(process.cwd());
       const path = getStoragePath();
       expect(path).toContain("openai-codex-accounts.json");
-      expect(path).toContain(".opencode");
+      expect(path).toContain(".codex");
       expect(path).toContain("projects");
     });
   });
@@ -903,20 +915,20 @@ describe("storage", () => {
 
       expect(existsSync(gitignorePath)).toBe(true);
       const gitignoreContent = await fs.readFile(gitignorePath, "utf-8");
-      expect(gitignoreContent).toContain(".opencode/");
-      expect(getStoragePath()).toContain(join(fakeHome, ".opencode", "projects"));
+      expect(gitignoreContent).toContain(".codex/");
+      expect(getStoragePath()).toContain(join(fakeHome, ".codex", "multi-auth", "projects"));
     });
 
     it("creates .gitignore when it does not exist but .git dir exists (line 99-100 false branch)", async () => {
       const projectDir = join(testWorkDir, "project");
-      const openCodeDir = join(projectDir, ".opencode");
+      const codexDir = join(projectDir, ".codex");
       const gitDir = join(projectDir, ".git");
       const gitignorePath = join(projectDir, ".gitignore");
 
-      await fs.mkdir(openCodeDir, { recursive: true });
+      await fs.mkdir(codexDir, { recursive: true });
       await fs.mkdir(gitDir, { recursive: true });
 
-      testStoragePath = join(openCodeDir, "accounts.json");
+      testStoragePath = join(codexDir, "accounts.json");
       setStoragePathDirect(testStoragePath);
 
       const storage = {
@@ -929,20 +941,20 @@ describe("storage", () => {
 
       expect(existsSync(gitignorePath)).toBe(true);
       const gitignoreContent = await fs.readFile(gitignorePath, "utf-8");
-      expect(gitignoreContent).toContain(".opencode/");
+      expect(gitignoreContent).toContain(".codex/");
     });
 
     it("appends to existing .gitignore without trailing newline (line 107 coverage)", async () => {
       const projectDir = join(testWorkDir, "project2");
-      const openCodeDir = join(projectDir, ".opencode");
+      const codexDir = join(projectDir, ".codex");
       const gitDir = join(projectDir, ".git");
       const gitignorePath = join(projectDir, ".gitignore");
 
-      await fs.mkdir(openCodeDir, { recursive: true });
+      await fs.mkdir(codexDir, { recursive: true });
       await fs.mkdir(gitDir, { recursive: true });
       await fs.writeFile(gitignorePath, "node_modules", "utf-8");
 
-      testStoragePath = join(openCodeDir, "accounts.json");
+      testStoragePath = join(codexDir, "accounts.json");
       setStoragePathDirect(testStoragePath);
 
       const storage = {
@@ -954,7 +966,7 @@ describe("storage", () => {
       await saveAccounts(storage);
 
       const gitignoreContent = await fs.readFile(gitignorePath, "utf-8");
-      expect(gitignoreContent).toBe("node_modules\n.opencode/\n");
+      expect(gitignoreContent).toBe("node_modules\n.codex/\n");
     });
   });
 
@@ -974,7 +986,7 @@ describe("storage", () => {
       const fakeHome = join(testWorkDir, "home");
       const projectDir = join(testWorkDir, "project");
       const projectGitDir = join(projectDir, ".git");
-      const legacyProjectConfigDir = join(projectDir, ".opencode");
+      const legacyProjectConfigDir = join(projectDir, ".codex");
       const legacyStoragePath = join(legacyProjectConfigDir, "openai-codex-accounts.json");
 
       await fs.mkdir(fakeHome, { recursive: true });
@@ -1134,9 +1146,65 @@ describe("storage", () => {
 
       statSpy.mockRestore();
     });
+
+    it("retries backup copyFile on transient EBUSY and succeeds", async () => {
+      const now = Date.now();
+      const storage = {
+        version: 3 as const,
+        activeIndex: 0,
+        accounts: [{ refreshToken: "token", addedAt: now, lastUsed: now }],
+      };
+
+      // Seed a primary file so backup creation path runs on next save.
+      await saveAccounts(storage);
+
+      const originalCopy = fs.copyFile.bind(fs);
+      let copyAttempts = 0;
+      const copySpy = vi.spyOn(fs, "copyFile").mockImplementation(async (src, dest) => {
+        copyAttempts += 1;
+        if (copyAttempts === 1) {
+          const err = new Error("EBUSY copy") as NodeJS.ErrnoException;
+          err.code = "EBUSY";
+          throw err;
+        }
+        return originalCopy(src as string, dest as string);
+      });
+
+      await saveAccounts({
+        ...storage,
+        accounts: [{ refreshToken: "token-next", addedAt: now, lastUsed: now }],
+      });
+
+      expect(copyAttempts).toBe(2);
+      copySpy.mockRestore();
+    });
   });
 
   describe("clearAccounts edge cases", () => {
+    it("removes primary, backup, and wal artifacts", async () => {
+      const now = Date.now();
+      const storage = {
+        version: 3 as const,
+        activeIndex: 0,
+        accounts: [{ refreshToken: "token-1", addedAt: now, lastUsed: now }],
+      };
+
+      const storagePath = getStoragePath();
+      await saveAccounts(storage);
+      await fs.writeFile(`${storagePath}.bak`, JSON.stringify(storage), "utf-8");
+      await fs.writeFile(`${storagePath}.wal`, JSON.stringify(storage), "utf-8");
+
+      expect(existsSync(storagePath)).toBe(true);
+      expect(existsSync(`${storagePath}.bak`)).toBe(true);
+      expect(existsSync(`${storagePath}.wal`)).toBe(true);
+
+      await clearAccounts();
+
+      expect(existsSync(storagePath)).toBe(false);
+      expect(existsSync(`${storagePath}.bak`)).toBe(false);
+      expect(existsSync(`${storagePath}.wal`)).toBe(false);
+    });
+
     it("logs error for non-ENOENT errors during clear", async () => {
       const unlinkSpy = vi.spyOn(fs, "unlink").mockRejectedValue(
         Object.assign(new Error("EACCES error"), { code: "EACCES" })
diff --git a/test/stream-failover.test.ts b/test/stream-failover.test.ts
new file mode 100644
index 00000000..784a4148
--- /dev/null
+++ b/test/stream-failover.test.ts
@@ -0,0 +1,128 @@
+import { describe, expect, it, vi } from "vitest";
+import { withStreamingFailover } from "../lib/request/stream-failover.js";
+
+const encoder = new TextEncoder();
+
+function makeStallingResponse(): Response {
+	return new Response(
+		new ReadableStream<Uint8Array>({
+			start(controller) {
+				controller.enqueue(encoder.encode("data: first\n\n"));
+			},
+		}),
+		{
+			headers: {
+				"content-type": "text/event-stream",
+			},
+		},
+	);
+}
+
+function makeSseResponse(payload: string): Response {
+	return new Response(
+		new ReadableStream<Uint8Array>({
+			start(controller) {
+				controller.enqueue(encoder.encode(payload));
+				controller.close();
+			},
+		}),
+		{
+			headers: {
+				"content-type": "text/event-stream",
+			},
+		},
+	);
+}
+
+describe("stream failover", () => {
+	it("returns original response when max failovers disabled", async () => {
+		const response = withStreamingFailover(
+			makeSseResponse("data: ok\n\n"),
+			async () => makeSseResponse("data: fallback\n\n"),
+			{ maxFailovers: 0, stallTimeoutMs: 10 },
+		);
+
+		await expect(response.text()).resolves.toContain("data: ok");
+	});
+
+	it("switches to fallback stream when primary stalls", async () => {
+		const fallback = vi.fn(async () => makeSseResponse("data: second\n\n"));
+		const response = withStreamingFailover(makeStallingResponse(), fallback, {
+			maxFailovers: 1,
+			stallTimeoutMs: 10,
+		});
+
+		const text = await response.text();
+		expect(text).toContain("data: first");
+		expect(text).toContain("codex-multi-auth failover 1");
+		expect(text).toContain("data: second");
+		expect(fallback).toHaveBeenCalledTimes(1);
+	});
+
+	it("includes request id marker when provided", async () => {
+		const response = withStreamingFailover(
+			makeStallingResponse(),
+			async () => makeSseResponse("data: fallback\n\n"),
+			{
+				maxFailovers: 1,
+				stallTimeoutMs: 10,
+				requestInstanceId: "req-123",
+			},
+		);
+
+		const text = await response.text();
+		expect(text).toContain("codex-multi-auth failover 1 req:req-123");
+	});
+
+	it("errors when fallback is unavailable", async () => {
+		const response = withStreamingFailover(
+			makeStallingResponse(),
+			async () => null,
+			{ maxFailovers: 1, stallTimeoutMs: 10 },
+		);
+
+		await expect(response.text()).rejects.toThrow("SSE stream stalled");
+	});
+
+	it("propagates fallback provider exceptions deterministically", async () => {
+		const response = withStreamingFailover(
+			makeStallingResponse(),
+			async () => {
+				throw new Error("fallback exploded");
+			},
+			{ maxFailovers: 1, stallTimeoutMs: 10 },
+		);
+
+		await expect(response.text()).rejects.toThrow("fallback exploded");
+	});
+
+	it("releases underlying reader when wrapped stream is cancelled", async () => {
+		let sourceCancelled = 0;
+		const response = withStreamingFailover(
+			new Response(
+				new ReadableStream<Uint8Array>({
+					start(controller) {
+						controller.enqueue(encoder.encode("data: first\n\n"));
+					},
+					cancel() {
+						sourceCancelled += 1;
+					},
+				}),
+				{
+					headers: {
+						"content-type": "text/event-stream",
+					},
+				},
+			),
+			async () => null,
+			{ maxFailovers: 1, stallTimeoutMs: 10_000 },
+		);
+
+		const reader = response.body?.getReader();
+		expect(reader).toBeDefined();
+		await reader?.read();
+		await reader?.cancel();
+
+		expect(sourceCancelled).toBeGreaterThan(0);
+	});
+});
diff --git a/test/ui-format.test.ts b/test/ui-format.test.ts
index 4f037922..9f25723e 100644
--- a/test/ui-format.test.ts
+++ b/test/ui-format.test.ts
@@ -7,6 +7,7 @@ import {
 	formatUiKeyValue,
 	formatUiSection,
 	paintUiText,
+	quotaToneFromLeftPercent,
 } from "../lib/ui/format.js";
 import type { UiRuntimeOptions } from "../lib/ui/runtime.js";
 
@@ -14,6 +15,8 @@ const v2Ui: UiRuntimeOptions = {
 	v2Enabled: true,
 	colorProfile: "truecolor",
 	glyphMode: "ascii",
+	palette: "green",
+	accent: "green",
 	theme: createUiTheme({ profile: "truecolor", glyphMode: "ascii" }),
 };
 
@@ -21,6 +24,8 @@ const legacyUi: UiRuntimeOptions = {
 	v2Enabled: false,
 	colorProfile: "ansi16",
 	glyphMode: "ascii",
+	palette: "green",
+	accent: "green",
 	theme: createUiTheme({ profile: "ansi16", glyphMode: "ascii" }),
 };
 
@@ -54,5 +59,12 @@ describe("UI text formatter", () => {
 		expect(item).toContain("1. user@example.com");
 		expect(item).toContain(v2Ui.theme.glyphs.bullet);
 	});
-});
 
+	it("maps quota severity with traffic-light thresholds", () => {
+		expect(quotaToneFromLeftPercent(70)).toBe("success");
+		expect(quotaToneFromLeftPercent(35)).toBe("warning");
+		expect(quotaToneFromLeftPercent(16)).toBe("warning");
+		expect(quotaToneFromLeftPercent(15)).toBe("danger");
+		expect(quotaToneFromLeftPercent(0)).toBe("danger");
+	});
+});
diff --git a/test/ui-runtime.test.ts b/test/ui-runtime.test.ts
index cf41c965..e757c4d7 100644
--- a/test/ui-runtime.test.ts
+++ b/test/ui-runtime.test.ts
@@ -15,6 +15,8 @@ describe("UI runtime options", () => {
 		expect(ui.v2Enabled).toBe(true);
 		expect(ui.colorProfile).toBe("truecolor");
 		expect(ui.glyphMode).toBe("ascii");
+		expect(ui.palette).toBe("green");
+		expect(ui.accent).toBe("green");
 	});
 
 	it("updates runtime options and rebuilds theme", () => {
@@ -22,11 +24,15 @@ describe("UI runtime options", () => {
 			v2Enabled: false,
 			colorProfile: "ansi16",
 			glyphMode: "unicode",
+			palette: "blue",
+			accent: "cyan",
 		});
 
 		expect(updated.v2Enabled).toBe(false);
 		expect(updated.colorProfile).toBe("ansi16");
 		expect(updated.glyphMode).toBe("unicode");
+		expect(updated.palette).toBe("blue");
+		expect(updated.accent).toBe("cyan");
 		expect(updated.theme.profile).toBe("ansi16");
 		expect(updated.theme.glyphMode).toBe("unicode");
 	});
@@ -37,6 +43,7 @@ describe("UI runtime options", () => {
 		expect(ui.v2Enabled).toBe(false);
 		expect(ui.colorProfile).toBe("truecolor");
 		expect(ui.glyphMode).toBe("ascii");
+		expect(ui.palette).toBe("green");
+		expect(ui.accent).toBe("green");
 	});
 });
-
diff --git a/test/ui-theme.test.ts b/test/ui-theme.test.ts
index 9c33bfb4..cfe273cb 100644
--- a/test/ui-theme.test.ts
+++ b/test/ui-theme.test.ts
@@ -8,6 +8,9 @@ describe("UI theme", () => {
 		expect(theme.glyphMode).toBe("ascii");
 		expect(theme.glyphs.selected.length).toBeGreaterThan(0);
 		expect(theme.colors.reset).toBe("\x1b[0m");
+		expect(theme.colors.primary).toContain("\x1b[");
+		expect(theme.colors.focusBg).toContain("\x1b[");
+		expect(theme.colors.focusText).toContain("\x1b[");
 	});
 
 	it("uses ansi16 color profile when requested", () => {
@@ -22,6 +25,17 @@ describe("UI theme", () => {
 		expect(theme.colors.accent).toContain("38;5;");
 	});
 
+	it("supports blue palette and cyan accent overrides", () => {
+		const theme = createUiTheme({
+			profile: "truecolor",
+			palette: "blue",
+			accent: "cyan",
+		});
+		expect(theme.colors.primary).toContain("\x1b[");
+		expect(theme.colors.accent).toContain("\x1b[");
+		expect(theme.colors.focusBg).toContain("\x1b[");
+	});
+
 	it("uses unicode glyph set when explicitly requested", () => {
 		const theme = createUiTheme({ glyphMode: "unicode" });
 		expect(theme.glyphs.selected).not.toBe(">");
@@ -34,4 +48,3 @@ describe("UI theme", () => {
 		expect(theme.glyphs.check).toBe("+");
 	});
 });
-
diff --git a/test/unified-settings.test.ts b/test/unified-settings.test.ts
new file mode 100644
index 00000000..957b66e8
--- /dev/null
+++ b/test/unified-settings.test.ts
@@ -0,0 +1,144 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { promises as fs } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+describe("unified settings", () => {
+	let tempDir: string;
+	let originalDir: string | undefined;
+
+	beforeEach(async () => {
+		originalDir = process.env.CODEX_MULTI_AUTH_DIR;
+		tempDir = await fs.mkdtemp(join(tmpdir(), "codex-multi-auth-unified-"));
+		process.env.CODEX_MULTI_AUTH_DIR = tempDir;
+		vi.resetModules();
+	});
+
+	afterEach(async () => {
+		if (originalDir === undefined) {
+			delete process.env.CODEX_MULTI_AUTH_DIR;
+		} else {
+			process.env.CODEX_MULTI_AUTH_DIR = originalDir;
+		}
+		await fs.rm(tempDir, { recursive: true, force: true });
+	});
+
+	it("merges plugin and dashboard sections into one file", async () => {
+		const {
+			getUnifiedSettingsPath,
+			saveUnifiedPluginConfig,
+			saveUnifiedDashboardSettings,
+			loadUnifiedPluginConfigSync,
+			loadUnifiedDashboardSettings,
+		} = await import("../lib/unified-settings.js");
+
+		await saveUnifiedPluginConfig({ codexMode: true, fetchTimeoutMs: 90000 });
+		await saveUnifiedDashboardSettings({ menuShowLastUsed: false, uiThemePreset: "blue" });
+
+		const pluginConfig = loadUnifiedPluginConfigSync();
+		expect(pluginConfig).toEqual({
+			codexMode: true,
+			fetchTimeoutMs: 90000,
+		});
+
+		const dashboardSettings = await loadUnifiedDashboardSettings();
+		expect(dashboardSettings).toEqual({
+			menuShowLastUsed: false,
+			uiThemePreset: "blue",
+		});
+
+		const fileContent = await fs.readFile(getUnifiedSettingsPath(), "utf8");
+		expect(fileContent).toContain("\"version\": 1");
+		expect(fileContent).toContain("\"pluginConfig\"");
+		expect(fileContent).toContain("\"dashboardDisplaySettings\"");
+	});
+
+	it("returns null sections for invalid JSON", async () => {
+		const { getUnifiedSettingsPath, loadUnifiedPluginConfigSync, loadUnifiedDashboardSettings } = await import(
+			"../lib/unified-settings.js"
+		);
+
+		await fs.mkdir(tempDir, { recursive: true });
+		await fs.writeFile(getUnifiedSettingsPath(), "{ invalid json", "utf8");
+
+		expect(loadUnifiedPluginConfigSync()).toBeNull();
+		expect(await loadUnifiedDashboardSettings()).toBeNull();
+	});
+
+	it("serializes concurrent plugin config writes to avoid race corruption", async () => {
+		const {
+			saveUnifiedPluginConfig,
+			loadUnifiedPluginConfigSync,
+			getUnifiedSettingsPath,
+		} = await import("../lib/unified-settings.js");
+
+		await Promise.all([
+			saveUnifiedPluginConfig({ codexMode: false, requestTimeoutMs: 30_000 }),
+			saveUnifiedPluginConfig({ codexMode: true, requestTimeoutMs: 90_000, retries: 2 }),
+		]);
+
+		const pluginConfig = loadUnifiedPluginConfigSync();
+		expect(pluginConfig).toEqual({
+			codexMode: true,
+			requestTimeoutMs: 90_000,
+			retries: 2,
+		});
+
+		const raw = await fs.readFile(getUnifiedSettingsPath(), "utf8");
+		expect(() => JSON.parse(raw)).not.toThrow();
+	});
+
+	it("keeps both sections after concurrent plugin/dashboard writes", async () => {
+		const {
+			saveUnifiedPluginConfig,
+			saveUnifiedDashboardSettings,
+			loadUnifiedPluginConfigSync,
+			loadUnifiedDashboardSettings,
+		} = await import("../lib/unified-settings.js");
+
+		await Promise.all([
+			saveUnifiedPluginConfig({ codexMode: true, retries: 3 }),
+			saveUnifiedDashboardSettings({ menuShowLastUsed: false, uiThemePreset: "green" }),
+		]);
+
+		expect(loadUnifiedPluginConfigSync()).toEqual({ codexMode: true, retries: 3 });
+		expect(await loadUnifiedDashboardSettings()).toEqual({
+			menuShowLastUsed: false,
+			uiThemePreset: "green",
+		});
+	});
+
+	it("refuses overwriting settings sections when a read fails", async () => {
+		const {
+			saveUnifiedPluginConfig,
+			saveUnifiedDashboardSettings,
+			getUnifiedSettingsPath,
+		} = await import("../lib/unified-settings.js");
+
+		await saveUnifiedPluginConfig({ codexMode: true, fetchTimeoutMs: 70_000 });
+		await saveUnifiedDashboardSettings({ menuShowLastUsed: false, uiThemePreset: "blue" });
+
+		const readSpy = vi.spyOn(fs, "readFile");
+		readSpy.mockImplementationOnce(async () => {
+			const error = new Error("file locked") as NodeJS.ErrnoException;
+			error.code = "EBUSY";
+			throw error;
+		});
+
+		await expect(
+			saveUnifiedDashboardSettings({ menuShowLastUsed: true, uiThemePreset: "yellow" }),
+		).rejects.toThrow();
+		readSpy.mockRestore();
+
+		const raw = await fs.readFile(getUnifiedSettingsPath(), "utf8");
+		const parsed = JSON.parse(raw) as {
+			pluginConfig?: Record<string, unknown>;
+			dashboardDisplaySettings?: Record<string, unknown>;
+		};
+		expect(parsed.pluginConfig).toEqual({ codexMode: true, fetchTimeoutMs: 70_000 });
+		expect(parsed.dashboardDisplaySettings).toEqual({
+			menuShowLastUsed: false,
+			uiThemePreset: "blue",
+		});
+	});
+});
diff --git a/vitest.config.ts b/vitest.config.ts
index bd94bec5..96048a06 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -23,8 +23,10 @@ export default defineConfig({
         'dist/',
         'test/',
         'index.ts',
+        'lib/codex-manager.ts',
         'lib/ui/**',
         'lib/tools/**',
+        'scripts/**',
       ],
       thresholds: {
         statements: 80,