ndycode · ndycode · Feb 27, 2026 · Feb 27, 2026 · Feb 27, 2026 · Feb 27, 2026
@@ -1,6 +1,6 @@
-# changelog
+# Changelog
 
-all notable changes to this project. dates are ISO format (YYYY-MM-DD).
+All notable changes to this project. Dates are ISO format (YYYY-MM-DD).
 
 ## [unreleased]
 
@@ -260,7 +260,7 @@ Full Changelog: https://github.com/ndycode/codex-multi-auth/compare/v4.12.1...v4
 - Proactive token refresh - Refreshes tokens 5 minutes before expiry
 - Zod schemas - Runtime validation as single source of truth
 - ### Stats
-- Tests: 580 â†’ 631 (+51)
+- Tests: 580 -> 631 (+51)
 - All passing on Windows with `--pool=forks`
 
 ### Bug Fixes
@@ -372,30 +372,33 @@ Full Changelog: https://github.com/ndycode/codex-multi-auth/compare/v4.9.7...v4.
 
 ### Changelog
 
-Full Changelog: https://github.com/ndycode/codex-multi-auth/compare/v4.9.5...v4.9.7
+Full Changelog: https://github.com/ndycode/codex-multi-auth/compare/v4.9.6...v4.9.7
 
-## [4.9.5] - 2026-01-28
+## [4.9.6] - 2026-02-08
 
 ### Improvements
-- When your ChatGPT subscription didn't include Codex access, the plugin kept rotating through all accounts and retrying forever because it thought it was a temporary rate limit.
-- You get an immediate, clear error: "This model is not included in your ChatGPT subscription."
 
-### Bug Fixes
-- Account error handling - Fixes infinite retry loop when account doesn't have access to Codex models. `usage_not_included` errors now return 403 Forbidden instead of being treated as rate limits. Clear error message explaining the subscription issue. Prevents pointless account rotation for non-recoverable errors. (#16, thanks @rainmeter33-jpg!)
+- tui auth gating: non-tty/ui auth attempts now return a clear instruction to run `codex auth login` in a terminal shell.
+- error-mapping simplification: consolidated entitlement/rate-limit mapping in fetch helpers for a single handling path.
 
 ### Changelog
 
-Full Changelog: https://github.com/ndycode/codex-multi-auth/compare/v4.9.4...v4.9.5
+Full Changelog: https://github.com/ndycode/codex-multi-auth/compare/v4.9.5...v4.9.6
 
-## [4.9.6] - 2026-02-08
+## [4.9.5] - 2026-01-28
 
 ### Improvements
-- tui auth gating: non-tty/ui auth attempts now return a clear instruction to run `codex auth login` in a terminal shell.
-- error-mapping simplification: consolidated entitlement/rate-limit mapping in fetch helpers for a single handling path.
+
+- When your ChatGPT subscription didn't include Codex access, the plugin kept rotating through all accounts and retrying forever because it thought it was a temporary rate limit.
+- You get an immediate, clear error: "This model is not included in your ChatGPT subscription."
+
+### Bug Fixes
+
+- Account error handling - Fixes infinite retry loop when account doesn't have access to Codex models. `usage_not_included` errors now return 403 Forbidden instead of being treated as rate limits. Clear error message explaining the subscription issue. Prevents pointless account rotation for non-recoverable errors. (#16, thanks @rainmeter33-jpg!)
 
 ### Changelog
 
-Full Changelog: https://github.com/ndycode/codex-multi-auth/compare/v5.0.0...v4.9.6
+Full Changelog: https://github.com/ndycode/codex-multi-auth/compare/v4.9.4...v4.9.5
 
 ## [4.9.4] - 2026-01-27
 

@@ -36,10 +36,10 @@ All contributions MUST:
 ## Code Standards
 
 - **TypeScript:** All code must be TypeScript with strict type checking
-- **Testing:** Include tests for new functionality (we maintain 200+ unit tests)
+- **Testing:** Include tests for new functionality and keep coverage gate healthy (80% threshold)
 - **Documentation:** Update README.md for user-facing changes
-- **Modular design:** Keep functions focused and under 40 lines
-- **No external dependencies:** Minimize dependencies (currently only @openauthjs/openauth)
+- **Validation gate:** Run `npm run typecheck`, `npm run lint`, `npm test`, and `npm run build` before opening a PR
+- **Dependencies:** Minimize new dependencies and justify them in the PR
 
 ## Pull Request Process
 
@@ -48,7 +48,7 @@ All contributions MUST:
 3. **Include tests** for new functionality
 4. **Update documentation** (README.md, config examples, etc.)
 5. **Ensure compliance** with guidelines above
-6. **Test thoroughly** with actual ChatGPT Plus/Pro account
+6. **Run the validation gate** (`npm run typecheck`, `npm run lint`, `npm test`, `npm run build`)
 7. **Submit PR** with clear description of changes
 
 ## Reporting Issues

@@ -51,6 +51,7 @@ codex auth check
 | `codex auth check` | Quick health + live session checks |
 | `codex auth forecast --live` | Choose best next account |
 | `codex auth fix --dry-run` | Preview safe fixes |
+| `codex auth fix --live --model gpt-5-codex` | Run fix with live probe on a specific model |
 | `codex auth fix` | Apply safe fixes |
 | `codex auth doctor --fix` | Diagnose + repair common issues |
 | `codex auth report --live --json` | Export machine-readable status |
@@ -67,7 +68,7 @@ Main dashboard:
 - `Enter`: select
 - `1-9`: quick switch
 - `/`: search
-- `?` or `H`: help
+- `?`: toggle help
 - `Q`: back/cancel
 
 Account detail menu:
@@ -97,6 +98,30 @@ Reference: [docs/reference/settings.md](docs/reference/settings.md)
 
 * * *
 
+## Stable Env Overrides
+
+Use these stable overrides first:
+
+| Variable | Purpose |
+| --- | --- |
+| `CODEX_MULTI_AUTH_DIR` | Override the multi-auth root (`settings`, accounts, cache, logs) |
+| `CODEX_MULTI_AUTH_CONFIG_PATH` | Load plugin config from an alternate file |
+| `CODEX_HOME` | Override Codex home used to resolve default paths |
+| `CODEX_MODE` | Toggle Codex mode |
+| `CODEX_TUI_V2` | Toggle TUI v2 |
+| `CODEX_TUI_COLOR_PROFILE` | Set TUI color profile (`truecolor`, `ansi256`, `ansi16`) |
+| `CODEX_TUI_GLYPHS` | Set glyph mode (`ascii`, `unicode`, `auto`) |
+| `CODEX_AUTH_FETCH_TIMEOUT_MS` | Override upstream request timeout |
+| `CODEX_AUTH_STREAM_STALL_TIMEOUT_MS` | Override stream stall timeout |
+| `CODEX_MULTI_AUTH_SYNC_CODEX_CLI` | Toggle Codex CLI state synchronization |
+| `CODEX_CLI_ACCOUNTS_PATH` / `CODEX_CLI_AUTH_PATH` | Override Codex CLI state file locations |
+| `CODEX_MULTI_AUTH_REAL_CODEX_BIN` | Force forwarded Codex binary path |
+| `CODEX_MULTI_AUTH_BYPASS` | Disable local auth interception and always forward |
+
+Advanced/internal toggles are documented in [docs/development/CONFIG_FIELDS.md](docs/development/CONFIG_FIELDS.md).
+
+* * *
+
 ## Documentation
 
 Start here:

@@ -2,12 +2,12 @@
 
 ## Supported Versions
 
-We provide security updates for the latest version of the plugin.
+Security fixes are prioritized for the latest release line.
 
-| Version | Supported          |
-| ------- | ------------------ |
-| Latest  | ✅ Active support |
-| < 1.0   | ❌ No longer supported |
+| Version line | Supported |
+| --- | --- |
+| Latest release line | ✅ Active support |
+| Older release lines | ⚠️ Best effort only; upgrade recommended |
 
 ## Security Considerations
 
@@ -28,6 +28,7 @@ This plugin handles sensitive OAuth tokens. To protect your security:
 - Regularly review authorized apps at [ChatGPT Settings](https://chatgpt.com/settings/apps)
 - 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
+- Avoid `CODEX_PLUGIN_LOG_BODIES=1` unless required for short-lived local debugging
 
 ### Reporting a Vulnerability
 
@@ -72,7 +73,7 @@ The following are **not** security vulnerabilities:
 ### Third-Party Dependencies
 
 This plugin minimizes dependencies for security:
-- Runtime dependencies include OAuth/auth libraries, plugin host SDK dependencies, `hono`, and `zod`
+- Runtime dependencies include OAuth/auth libraries, `@codex-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

@@ -14,6 +14,8 @@ These files are example model/provider templates for `codex-multi-auth`.
 
 - These templates are optional for the OAuth account manager flow.
 - Core auth commands use `codex auth login`.
+- Prefer `codex-modern.json` for new setup; use `codex-legacy.json` only for compatibility testing.
+- Verify account readiness after template updates with `codex auth forecast --live` and `codex auth fix --live --model gpt-5-codex`.
 
 ## Defaults Included
 

@@ -82,6 +82,7 @@ When runtime behavior changes:
 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.
+9. Keep CLI usage text in docs aligned with `lib/codex-manager.ts` usage output.
 
 * * *
 
@@ -95,6 +96,7 @@ Before merge:
 4. Internal links are valid.
 5. Cross-platform examples are present for OS-sensitive flows.
 6. No conflicting duplicate guidance across pages.
+7. `test/documentation.test.ts` passes.
 
 * * *
 

@@ -1,6 +1,6 @@
 # Configuration
 
-Configure behavior from one settings root with optional environment overrides.
+Configure behavior from one settings root with stable env overrides and optional advanced toggles.
 
 ---
 
@@ -55,18 +55,36 @@ Keep these enabled for most users:
 
 ---
 
-## Environment Overrides
+## Stable Environment Overrides
+
+These overrides are stable and intended for day-to-day use:
 
 | Variable | Effect |
 | --- | --- |
-| `CODEX_MULTI_AUTH_DIR` | Override settings/accounts root |
-| `CODEX_MULTI_AUTH_CONFIG_PATH` | Read config from alternate file |
+| `CODEX_MULTI_AUTH_DIR` | Override settings/accounts/cache/log root |
+| `CODEX_MULTI_AUTH_CONFIG_PATH` | Read plugin config from alternate file |
+| `CODEX_HOME` | Change Codex home used for default path resolution |
 | `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 |
+| `CODEX_MULTI_AUTH_SYNC_CODEX_CLI=0/1` | Disable/enable Codex CLI state sync |
+| `CODEX_CLI_ACCOUNTS_PATH=<path>` | Override Codex CLI accounts file path |
+| `CODEX_CLI_AUTH_PATH=<path>` | Override Codex CLI auth file path |
+| `CODEX_MULTI_AUTH_REAL_CODEX_BIN=<path>` | Force official Codex binary used by wrapper |
+| `CODEX_MULTI_AUTH_BYPASS=1` | Bypass local auth handling and forward all commands |
+
+---
+
+## Advanced/Internal Overrides
+
+Advanced runtime controls (failover policy, refresh lease internals, testing toggles) are documented in:
+
+- [development/CONFIG_FIELDS.md](development/CONFIG_FIELDS.md)
+
+Treat those settings as maintainers-only unless explicitly advised.
 
 ---
 

@@ -107,6 +107,7 @@ Canonical root: `~/.codex/multi-auth`.
 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 ...`.
+5. CLI usage/help output must stay in sync with parser-supported flags.
 
 * * *
 

@@ -22,9 +22,9 @@ Top-level shape:
 
 * * *
 
-## Plugin-Host Provider Options (`provider.openai.options`)
+## Provider Options (`provider.openai.options`)
 
-Used only for host plugin mode through the host runtime config file.
+Used in plugin-host runtime configuration.
 
 | Key | Type | Common values | Effect |
 | --- | --- | --- | --- |
@@ -183,28 +183,123 @@ Used only for host plugin mode through the host runtime config file.
 
 * * *
 
-## Environment Overrides
+## Stable Environment Overrides
+
+### Stable (User-Facing)
 
 | Variable | Purpose |
 | --- | --- |
 | `CODEX_MULTI_AUTH_DIR` | Custom root for settings/accounts/cache/logs |
-| `CODEX_MULTI_AUTH_CONFIG_PATH` | Alternate config file input |
+| `CODEX_MULTI_AUTH_CONFIG_PATH` | Alternate plugin config file input |
+| `CODEX_HOME` | Override Codex home path used for default resolution |
 | `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 |
+| `CODEX_CLI_ACCOUNTS_PATH` | Override Codex CLI accounts state path |
+| `CODEX_CLI_AUTH_PATH` | Override Codex CLI auth state path |
+| `CODEX_MULTI_AUTH_REAL_CODEX_BIN` | Force official Codex binary path for wrapper forwarding |
+| `CODEX_MULTI_AUTH_BYPASS` | Bypass local auth handling in wrapper |
+| `ENABLE_PLUGIN_REQUEST_LOGGING` | Enable request logging |
+| `CODEX_PLUGIN_LOG_BODIES` | Include payload bodies in logs (sensitive) |
+| `DEBUG_CODEX_PLUGIN` | Enable debug logging |
+| `CODEX_PLUGIN_LOG_LEVEL` | Set log level (`debug`, `info`, `warn`, `error`) |
+| `CODEX_CONSOLE_LOG` | Emit logs to console in addition to app logger |
+
+### Advanced (Runtime Tuning)
+
+| Variable | Purpose | Stability |
+| --- | --- | --- |
+| `CODEX_AUTH_UNSUPPORTED_MODEL_POLICY` | Override unsupported-model policy (`strict`/`fallback`) | Advanced |
+| `CODEX_AUTH_FAST_SESSION` | Toggle fast-session mode | Advanced |
+| `CODEX_AUTH_FAST_SESSION_STRATEGY` | Override fast session strategy (`hybrid`/`always`) | Advanced |
+| `CODEX_AUTH_FAST_SESSION_MAX_INPUT_ITEMS` | Max fast-session input items retained | Advanced |
+| `CODEX_AUTH_RETRY_ALL_RATE_LIMITED` | Toggle all-accounts retry loop on full rate-limit exhaustion | Advanced |
+| `CODEX_AUTH_RETRY_ALL_MAX_WAIT_MS` | Max wait for all-accounts retry loop (`0` means unlimited) | Advanced |
+| `CODEX_AUTH_RETRY_ALL_MAX_RETRIES` | Max retry rounds for all-accounts retry loop | Advanced |
+| `CODEX_AUTH_FALLBACK_UNSUPPORTED_MODEL` | Legacy fallback policy toggle | Legacy |
+| `CODEX_AUTH_FALLBACK_GPT53_TO_GPT52` | Legacy GPT-5.3 -> GPT-5.2 fallback toggle | Legacy |
+| `CODEX_AUTH_TOKEN_REFRESH_SKEW_MS` | Refresh token skew window | Advanced |
+| `CODEX_AUTH_RATE_LIMIT_TOAST_DEBOUNCE_MS` | Rate-limit toast debounce interval | Advanced |
+| `CODEX_AUTH_TOAST_DURATION_MS` | UI toast duration | Advanced |
+| `CODEX_AUTH_PER_PROJECT_ACCOUNTS` | Toggle per-project account storage mode | Advanced |
+| `CODEX_AUTH_SESSION_RECOVERY` | Toggle session recovery module | Advanced |
+| `CODEX_AUTH_AUTO_RESUME` | Toggle automatic session resume in recovery | Advanced |
+| `CODEX_AUTH_PARALLEL_PROBING` | Toggle parallel account probing | Advanced |
+| `CODEX_AUTH_PARALLEL_PROBING_MAX_CONCURRENCY` | Max probe concurrency | Advanced |
+| `CODEX_AUTH_EMPTY_RESPONSE_MAX_RETRIES` | Max retries for empty/malformed responses | Advanced |
+| `CODEX_AUTH_EMPTY_RESPONSE_RETRY_DELAY_MS` | Delay between empty-response retries | Advanced |
+| `CODEX_AUTH_PID_OFFSET_ENABLED` | Toggle PID-based candidate offset | Advanced |
+| `CODEX_AUTH_LIVE_ACCOUNT_SYNC` | Toggle file-watch account sync | Advanced |
+| `CODEX_AUTH_LIVE_ACCOUNT_SYNC_DEBOUNCE_MS` | Live sync debounce interval | Advanced |
+| `CODEX_AUTH_LIVE_ACCOUNT_SYNC_POLL_MS` | Live sync poll fallback interval | Advanced |
+| `CODEX_AUTH_SESSION_AFFINITY` | Toggle session affinity | Advanced |
+| `CODEX_AUTH_SESSION_AFFINITY_TTL_MS` | Session affinity ttl | Advanced |
+| `CODEX_AUTH_SESSION_AFFINITY_MAX_ENTRIES` | Session affinity entry cap | Advanced |
+| `CODEX_AUTH_PROACTIVE_GUARDIAN` | Toggle proactive refresh guardian | Advanced |
+| `CODEX_AUTH_PROACTIVE_GUARDIAN_INTERVAL_MS` | Guardian tick interval | Advanced |
+| `CODEX_AUTH_PROACTIVE_GUARDIAN_BUFFER_MS` | Guardian pre-expiry buffer window | Advanced |
+| `CODEX_AUTH_NETWORK_ERROR_COOLDOWN_MS` | Cooldown applied after network errors | Advanced |
+| `CODEX_AUTH_SERVER_ERROR_COOLDOWN_MS` | Cooldown applied after 5xx errors | Advanced |
+| `CODEX_AUTH_STORAGE_BACKUP_ENABLED` | Toggle storage backup/WAL safety artifacts | Advanced |
+| `CODEX_AUTH_PREEMPTIVE_QUOTA_ENABLED` | Toggle preemptive quota deferral | Advanced |
+| `CODEX_AUTH_PREEMPTIVE_QUOTA_5H_REMAINING_PCT` | 5h quota deferral threshold percent | Advanced |
+| `CODEX_AUTH_PREEMPTIVE_QUOTA_7D_REMAINING_PCT` | 7d quota deferral threshold percent | Advanced |
+| `CODEX_AUTH_PREEMPTIVE_QUOTA_MAX_DEFERRAL_MS` | Max quota deferral wait | Advanced |
+
+### Advanced / Internal (Maintainers)
+
+| Variable | Purpose | Stability |
+| --- | --- | --- |
+| `CODEX_AUTH_ACCOUNT_ID` | Force workspace/account id for login/request routing | Advanced |
+| `CODEX_AUTH_FAILOVER_MODE` | Stream failover profile (`aggressive`/`balanced`/`conservative`) | Advanced |
+| `CODEX_AUTH_STREAM_FAILOVER_MAX` | Max failover attempts for streaming requests | Advanced |
+| `CODEX_AUTH_STREAM_STALL_SOFT_TIMEOUT_MS` | Soft timeout for stream failover decisions | Advanced |
+| `CODEX_AUTH_STREAM_STALL_HARD_TIMEOUT_MS` | Hard timeout for stream failover abort | Advanced |
+| `CODEX_AUTH_PREWARM` | Toggle startup prompt prewarm | Advanced |
+| `CODEX_AUTH_REFRESH_LEASE` | Toggle cross-process refresh lease | Advanced |
+| `CODEX_AUTH_REFRESH_LEASE_DIR` | Refresh lease state directory | Advanced |
+| `CODEX_AUTH_REFRESH_LEASE_TTL_MS` | Refresh lease ttl | Advanced |
+| `CODEX_AUTH_REFRESH_LEASE_WAIT_MS` | Refresh lease wait timeout | Advanced |
+| `CODEX_AUTH_REFRESH_LEASE_POLL_MS` | Refresh lease poll interval | Advanced |
+| `CODEX_AUTH_REFRESH_LEASE_RESULT_TTL_MS` | Refresh lease result ttl | Advanced |
+| `CODEX_AUTH_SYNC_CODEX_CLI` | Legacy Codex CLI sync toggle | Legacy |
+| `CODEX_MULTI_AUTH_EXPOSE_ADMIN_TOOLS` | Expose advanced plugin tools (`codex-metrics`, `codex-import`, etc.) | Internal |
+| `CODEX_SKIP_EMAIL_HYDRATE` | Skip email hydrate fallback for account metadata | Internal |
+| `CODEX_THREAD_ID` | Request correlation seed | Internal |
+| `CODEX_COLLABORATION_MODE` | Request transformer collaboration mode override | Internal |
+
+### Tooling / Test-Only
+
+| Variable | Purpose |
+| --- | --- |
+| `NODE_ENV`, `VITEST`, `VITEST_WORKER_ID` | Test/runtime mode toggles |
+| `CODEX_BIN`, `CODEX_MATRIX_TIMEOUT_MS`, `CODEX_MODELS_TIMEOUT_MS` | Script-only benchmarking/model-matrix controls |
+
+### Platform / Shell Detection (Informational)
+
+These variables affect runtime detection behavior, not plugin features:
+
+- `FORCE_INTERACTIVE_MODE`
+- `CODEX_TUI`, `CODEX_DESKTOP`
+- `TERM_PROGRAM`, `TERM`, `WT_SESSION`, `ELECTRON_RUN_AS_NODE`
+- `PATH`, `PATHEXT`
+- `APPDATA`, `XDG_DATA_HOME`
+
+Notes:
+
+- Non-plugin shell variables (`PATH`, `PATHEXT`, `TERM`, `WT_SESSION`, etc.) are intentionally excluded from user-facing guidance.
+- Prefer stable overrides; advanced/internal variables may change across releases.
 
 * * *
 
 ## 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.
+- Cross-process refresh lease 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.