codex-multi-auth 1.2.6 → 1.3.0

package/README.md

@@ -3,7 +3,7 @@
 [![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)
 
-Codex CLI-first multi-account OAuth manager for the official `@openai/codex` CLI.
+Codex CLI-first multi-account OAuth manager for the official Codex CLI, including the `@openai/codex` npm launcher and native `codex` installs.
 
 <img width="1270" height="729" alt="2026-02-28 12_54_58-prompt txt ‎- Notepads" src="https://github.com/user-attachments/assets/0cecb77e-a6d3-432a-ba48-3577db0c7093" />
 
@@ -11,6 +11,7 @@ Codex CLI-first multi-account OAuth manager for the official `@openai/codex` CLI
 > [!NOTE]
 > Legacy scoped prerelease package `@ndycode/codex-multi-auth` is migration-only.
 > Use `codex-multi-auth` for all new installs.
+
 ## What You Get
 
 - Canonical `codex auth ...` workflow for account login, switching, checks, and diagnostics
@@ -19,7 +20,7 @@ Codex CLI-first multi-account OAuth manager for the official `@openai/codex` CLI
 - Interactive dashboard for account actions and settings
 - Experimental settings tab for staged sync, backup, and refresh-guard controls
 - Forecast, report, fix, and doctor commands for operational safety
-- Runtime counters, budget/cooldown state, and multi-auth probe visibility in `codex auth status` / `codex auth report`
+- Runtime counters, budget/cooldown state, and multi-auth probe visibility in `codex auth status` / `codex auth report`
 - Flagged account verification and restore flow
 - Session affinity and live account sync controls
 - Proactive refresh and preemptive quota deferral controls
@@ -71,6 +72,8 @@ codex-multi-auth --version
 codex auth status
 ```
 
+Any official install path is fine as long as `codex` is on `PATH`: `npm i -g @openai/codex`, `brew install --cask codex`, or an official release binary.
+
 </details>
 
 <details>
@@ -105,6 +108,13 @@ npm i -g codex-multi-auth
 codex auth login
 ```
 
+If you already installed the official native CLI via Homebrew or a release binary, you only need:
+
+```bash
+npm i -g codex-multi-auth
+codex auth login
+```
+
 Verify the wrapper and the new account:
 
 ```bash
@@ -147,6 +157,7 @@ If browser launch is blocked, use the alternate login paths in [docs/getting-sta
 | Command | What it answers |
 | --- | --- |
 | `codex auth verify-flagged` | Can any previously flagged account be restored? |
+| `codex auth verify --paths` | Do my storage path chain and sandbox probes still pass self-test? |
 | `codex auth fix --dry-run` | What safe storage or account repairs are available? |
 | `codex auth doctor --fix` | Can the CLI diagnose and apply the safest fixes now? |
 
@@ -156,6 +167,7 @@ If browser launch is blocked, use the alternate login paths in [docs/getting-sta
 | --- | --- |
 | `codex auth report --live --json` | How do I get the full machine-readable health report? |
 | `codex auth fix --live --model gpt-5-codex` | How do I run live repair probes with a chosen model? |
+| `codex auth why-selected --json` | Which account does the selector pick now, and why? |
 
 ### Reliability behavior
 
@@ -163,7 +175,7 @@ If browser launch is blocked, use the alternate login paths in [docs/getting-sta
 - active requests use a bounded outbound request budget so one prompt cannot walk the full pool indefinitely
 - repeated cross-account 5xx bursts trigger a short cooldown instead of continuing aggressive rotation
 - proactive refresh is staggered to reduce background refresh bursts
-- `codex auth status` surfaces recent runtime request metrics in text output, and `codex auth report --json` exposes the machine-readable cooldown/runtime snapshot
+- `codex auth status` surfaces recent runtime request metrics in text output, and `codex auth report --json` exposes the machine-readable cooldown/runtime snapshot
 
 ---
 
@@ -196,12 +208,12 @@ If browser launch is blocked, use the alternate login paths in [docs/getting-sta
 | File | Default path |
 | --- | --- |
 | Settings | `~/.codex/multi-auth/settings.json` |
-| Accounts | `~/.codex/multi-auth/openai-codex-accounts.json` |
-| Flagged accounts | `~/.codex/multi-auth/openai-codex-flagged-accounts.json` |
-| Quota cache | `~/.codex/multi-auth/quota-cache.json` |
-| Runtime observability | `~/.codex/multi-auth/runtime-observability.json` |
-| Logs | `~/.codex/multi-auth/logs/codex-plugin/` |
-| Per-project accounts | `~/.codex/multi-auth/projects/<project-key>/openai-codex-accounts.json` |
+| Accounts | `~/.codex/multi-auth/openai-codex-accounts.json` |
+| Flagged accounts | `~/.codex/multi-auth/openai-codex-flagged-accounts.json` |
+| Quota cache | `~/.codex/multi-auth/quota-cache.json` |
+| Runtime observability | `~/.codex/multi-auth/runtime-observability.json` |
+| Logs | `~/.codex/multi-auth/logs/codex-plugin/` |
+| Per-project accounts | `~/.codex/multi-auth/projects/<project-key>/openai-codex-accounts.json` |
 
 Override root with `CODEX_MULTI_AUTH_DIR=<path>`.
 
@@ -273,12 +285,12 @@ codex auth login
 <details>
 <summary><b>Common symptoms</b></summary>
 
-- `codex auth` unrecognized: run `where codex`, then follow `docs/troubleshooting.md` for routing fallback commands
+- `codex auth` unrecognized: run `where codex` or `which codex`, then follow `docs/troubleshooting.md` for routing fallback commands
 - Switch succeeds but wrong account appears active: run `codex auth switch <index>`, then restart session
-- Requests fail fast with a pool cooldown message: wait for the cooldown window or inspect `codex auth status`
-- Requests fail fast after repeated upstream 5xx errors: inspect `codex auth report --json` for runtime traffic and cooldown details
-- Storage cleanup fails with `EBUSY` / `EPERM` (Windows): run `codex auth doctor --fix` to retry, or manually remove `~/.codex/multi-auth/<project-key>/` and re-login
-- OAuth callback on port `1455` fails: free the port and re-run `codex auth login`
+- Requests fail fast with a pool cooldown message: wait for the cooldown window or inspect `codex auth status`
+- Requests fail fast after repeated upstream 5xx errors: inspect `codex auth report --json` for runtime traffic and cooldown details
+- Storage cleanup fails with `EBUSY` / `EPERM` (Windows): run `codex auth doctor --fix` to retry, or manually remove `~/.codex/multi-auth/<project-key>/` and re-login
+- OAuth callback on port `1455` fails: free the port and re-run `codex auth login`
 - Browser launch is blocked or you are in a headless shell: re-run `codex auth login --manual` or set `CODEX_AUTH_NO_BROWSER=1`
 - `missing field id_token` / `token_expired` / `refresh_token_reused`: re-login affected account
 
@@ -321,10 +333,10 @@ codex auth doctor --json
 
 ## Release Notes
 
-- Current stable: [docs/releases/v1.2.6.md](docs/releases/v1.2.6.md)
-- Recent patch release: [docs/releases/v1.2.5.md](docs/releases/v1.2.5.md)
-- Previous stable: [docs/releases/v1.2.2.md](docs/releases/v1.2.2.md)
-- Earlier stable: [docs/releases/v1.2.1.md](docs/releases/v1.2.1.md)
+- Current stable: [docs/releases/v1.3.0.md](docs/releases/v1.3.0.md)
+- Previous stable: [docs/releases/v1.2.6.md](docs/releases/v1.2.6.md)
+- Earlier stable: [docs/releases/v1.2.5.md](docs/releases/v1.2.5.md)
+- Full release archive: [docs/README.md#release-history](docs/README.md#release-history)
 - Archived prerelease: [docs/releases/v0.1.0-beta.0.md](docs/releases/v0.1.0-beta.0.md)
 
 ## License

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAe,MAAM,kBAAkB,CAAC;AAyR5D;;;;;;;;;;;;;;;GAeG;AAEH,eAAO,MAAM,iBAAiB,EAAE,MA2/H/B,CAAC;AAEF,eAAO,MAAM,gBAAgB,KAAoB,CAAC;AAElD,eAAe,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAe,MAAM,kBAAkB,CAAC;AAwR5D;;;;;;;;;;;;;;;GAeG;AAEH,eAAO,MAAM,iBAAiB,EAAE,MA+hI/B,CAAC;AAEF,eAAO,MAAM,gBAAgB,KAAoB,CAAC;AAElD,eAAe,iBAAiB,CAAC"}

package/dist/index.js

@@ -25,7 +25,7 @@
 import { tool } from "@codex-ai/plugin/tool";
 import { AccountManager, extractAccountEmail, extractAccountId, formatAccountLabel, formatCooldown, formatWaitTime, getAccountIdCandidates, isCodexCliSyncEnabled, lookupCodexCliTokensByEmail, parseRateLimitReason, resolveRequestAccountId, resolveRuntimeRequestIdentity, sanitizeEmail, selectBestAccountCandidate, shouldUpdateAccountIdFromToken, } from "./lib/accounts.js";
 import { createAuthorizationFlow, exchangeAuthorizationCode, parseAuthorizationInput, redactOAuthUrlForLog, REDIRECT_URI, } from "./lib/auth/auth.js";
-import { isBrowserLaunchSuppressed, openBrowserUrl } from "./lib/auth/browser.js";
+import { isBrowserLaunchSuppressed, openBrowserUrl, } from "./lib/auth/browser.js";
 import { startLocalOAuthServer } from "./lib/auth/server.js";
 import { checkAndNotify } from "./lib/auto-update-checker.js";
 import { CapabilityPolicyStore } from "./lib/capability-policy.js";
@@ -74,7 +74,7 @@ import { buildLoginMenuAccounts } from "./lib/runtime/login-menu-accounts.js";
 import { ensureLiveAccountSyncEntry } from "./lib/runtime/live-sync-entry.js";
 import { applyLoaderRuntimeSetup } from "./lib/runtime/loader-setup.js";
 import { buildManualOAuthFlow } from "./lib/runtime/manual-oauth-flow.js";
-import { applyPreemptiveQuotaSettingsFromConfig, } from "./lib/runtime/quota-settings.js";
+import { applyPreemptiveQuotaSettingsFromConfig } from "./lib/runtime/quota-settings.js";
 import { ensureLiveAccountSyncState, ensureRefreshGuardianState, ensureSessionAffinityState, } from "./lib/runtime/runtime-services.js";
 import { mutateRuntimeObservabilitySnapshot } from "./lib/runtime/runtime-observability.js";
 import { applyAccountStorageScopeFromConfig } from "./lib/runtime/storage-scope.js";
@@ -88,7 +88,7 @@ import { clearAccounts, clearFlaggedAccounts, exportAccounts, findMatchingAccoun
 import { buildTableHeader, buildTableRow, } from "./lib/table-formatter.js";
 import { createHashlineEditTool, createHashlineReadTool, } from "./lib/tools/hashline-tools.js";
 import { formatUiBadge, formatUiHeader, formatUiItem, formatUiKeyValue, formatUiSection, paintUiText, } from "./lib/ui/format.js";
-import { setUiRuntimeOptions, } from "./lib/ui/runtime.js";
+import { setUiRuntimeOptions } from "./lib/ui/runtime.js";
 /**
  * OpenAI Codex OAuth authentication plugin for Codex CLI host runtime
  *
@@ -191,13 +191,9 @@ export const OpenAIOAuthPlugin = async ({ client }) => {
             const burstRemaining = getServerBurstCooldownRemaining(now);
             snapshot.currentRequestId = requestId;
             snapshot.poolExhaustionCooldownUntil =
-                poolRemaining > 0
-                    ? now + poolRemaining
-                    : null;
+                poolRemaining > 0 ? now + poolRemaining : null;
             snapshot.serverBurstCooldownUntil =
-                burstRemaining > 0
-                    ? now + burstRemaining
-                    : null;
+                burstRemaining > 0 ? now + burstRemaining : null;
             snapshot.responsesRequests = runtimeMetrics.responsesRequests;
             snapshot.authRefreshRequests = runtimeMetrics.authRefreshRequests;
             snapshot.diagnosticProbeRequests = runtimeMetrics.diagnosticProbeRequests;
@@ -300,8 +296,7 @@ export const OpenAIOAuthPlugin = async ({ client }) => {
         });
         refreshGuardian = next.refreshGuardian;
         refreshGuardianConfigKey = next.refreshGuardianConfigKey;
-        refreshGuardianCleanupRegistered =
-            next.refreshGuardianCleanupRegistered;
+        refreshGuardianCleanupRegistered = next.refreshGuardianCleanupRegistered;
     };
     const ensureSessionAffinity = (pluginConfig) => {
         const next = ensureSessionAffinityState({
@@ -593,7 +588,12 @@ export const OpenAIOAuthPlugin = async ({ client }) => {
                                         error: {
                                             message: `The account pool is cooling down after recent rate-limit exhaustion. Try again in ${formatWaitTime(poolCooldownRemainingMs)} or inspect \`codex auth status\`.`,
                                         },
-                                    }), { status: 429, headers: { "content-type": "application/json; charset=utf-8" } });
+                                    }), {
+                                        status: 429,
+                                        headers: {
+                                            "content-type": "application/json; charset=utf-8",
+                                        },
+                                    });
                                 }
                                 const serverBurstCooldownRemainingMs = getServerBurstCooldownRemaining();
                                 if (serverBurstCooldownRemainingMs > 0) {
@@ -605,7 +605,12 @@ export const OpenAIOAuthPlugin = async ({ client }) => {
                                         error: {
                                             message: `Multiple accounts recently failed with upstream server errors. Try again in ${formatWaitTime(serverBurstCooldownRemainingMs)} or inspect \`codex auth report --json\`.`,
                                         },
-                                    }), { status: 503, headers: { "content-type": "application/json; charset=utf-8" } });
+                                    }), {
+                                        status: 503,
+                                        headers: {
+                                            "content-type": "application/json; charset=utf-8",
+                                        },
+                                    });
                                 }
                                 const maxOutboundRequestAttempts = computeOutboundRequestAttemptBudget({
                                     accountCount: accountManager.getAccountCount(),
@@ -628,8 +633,7 @@ export const OpenAIOAuthPlugin = async ({ client }) => {
                                 const tryConsumeOutboundRequestAttempt = (reason, accountIndex) => {
                                     if (outboundRequestAttemptsRemaining <= 0) {
                                         runtimeMetrics.requestAttemptBudgetExhaustions += 1;
-                                        runtimeMetrics.lastError =
-                                            `Request attempt budget exhausted after ${maxOutboundRequestAttempts} outbound request(s)`;
+                                        runtimeMetrics.lastError = `Request attempt budget exhausted after ${maxOutboundRequestAttempts} outbound request(s)`;
                                         logWarn("Request attempt budget exhausted.", {
                                             requestTraceId,
                                             reason,
@@ -730,7 +734,8 @@ export const OpenAIOAuthPlugin = async ({ client }) => {
                                                 if (retryableRefreshPolicy.recordFailure) {
                                                     accountManager.recordFailure(account, modelFamily, model);
                                                 }
-                                                if (typeof retryableRefreshPolicy.cooldownMs === "number" &&
+                                                if (typeof retryableRefreshPolicy.cooldownMs ===
+                                                    "number" &&
                                                     retryableRefreshPolicy.cooldownReason) {
                                                     accountManager.markAccountCoolingDown(account, retryableRefreshPolicy.cooldownMs, retryableRefreshPolicy.cooldownReason);
                                                     accountManager.saveToDiskDebounced();
@@ -1224,10 +1229,18 @@ export const OpenAIOAuthPlugin = async ({ client }) => {
                                                     preemptiveQuotaScheduler.markRateLimited(quotaScheduleKey, cooldownMs);
                                                     const waitLabel = formatWaitTime(cooldownMs);
                                                     const shortRetryThresholdMs = getConfiguredRateLimitShortRetryThresholdMs();
-                                                    if (cooldownMs <=
-                                                        shortRetryThresholdMs &&
+                                                    if (cooldownMs <= shortRetryThresholdMs &&
                                                         shortRateLimitRetryCount < MAX_SHORT_RETRY_ATTEMPTS) {
                                                         shortRateLimitRetryCount += 1;
+                                                        // Mark the account unavailable BEFORE we sleep so
+                                                        // concurrent in-flight requests do not select the
+                                                        // same freshly rate-limited account during the retry
+                                                        // window. Without this, the fetch loop amplifies the
+                                                        // throttling pressure instead of spreading load.
+                                                        // The current request will continue after the sleep
+                                                        // regardless of the cooldown mark (AUDIT-H3 / D-07).
+                                                        accountManager.markRateLimitedWithReason(account, cooldownMs, modelFamily, parseRateLimitReason(rateLimit?.code), model);
+                                                        accountManager.recordRateLimit(account, modelFamily, model);
                                                         if (accountManager.shouldShowAccountToast(account.index, rateLimitToastDebounceMs)) {
                                                             await showRuntimeToast(client, `Rate limited. Retrying in ${waitLabel} (attempt ${shortRateLimitRetryCount})...`, "warning", { duration: toastDurationMs });
                                                             accountManager.markToastShown(account.index);
@@ -1382,7 +1395,7 @@ export const OpenAIOAuthPlugin = async ({ client }) => {
                                                                 preemptiveQuotaScheduler.update(`${fallbackEntitlementAccountKey}:${model ?? modelFamily}`, fallbackSnapshot);
                                                             }
                                                             if (!fallbackResponse.ok) {
-                                                                const { response: handledFallbackResponse, rateLimit: fallbackRateLimit } = await handleErrorResponse(fallbackResponse);
+                                                                const { response: handledFallbackResponse, rateLimit: fallbackRateLimit, } = await handleErrorResponse(fallbackResponse);
                                                                 try {
                                                                     await fallbackResponse.body?.cancel();
                                                                 }
@@ -1391,7 +1404,9 @@ export const OpenAIOAuthPlugin = async ({ client }) => {
                                                                 }
                                                                 if (handledFallbackResponse.status === 429) {
                                                                     const retryAfterMs = fallbackRateLimit?.retryAfterMs ?? 60_000;
-                                                                    const fallbackQuotaKey = model ? `${modelFamily}:${model}` : modelFamily;
+                                                                    const fallbackQuotaKey = model
+                                                                        ? `${modelFamily}:${model}`
+                                                                        : modelFamily;
                                                                     const { delayMs } = getRateLimitBackoff(fallbackAccount.index, fallbackQuotaKey, retryAfterMs);
                                                                     const cooldownMs = Math.max(delayMs, retryAfterMs);
                                                                     preemptiveQuotaScheduler.markRateLimited(`${fallbackEntitlementAccountKey}:${model ?? modelFamily}`, cooldownMs);
@@ -1502,7 +1517,12 @@ export const OpenAIOAuthPlugin = async ({ client }) => {
                                                                     error: {
                                                                         message: `Upstream server failures were observed across multiple accounts. Pausing retries for ${formatWaitTime(serverBurstCooldownUntil - Date.now())}. Check \`codex auth report --json\` for runtime metrics.`,
                                                                     },
-                                                                }), { status: 503, headers: { "content-type": "application/json; charset=utf-8" } });
+                                                                }), {
+                                                                    status: 503,
+                                                                    headers: {
+                                                                        "content-type": "application/json; charset=utf-8",
+                                                                    },
+                                                                });
                                                             }
                                                         }
                                                         logWarn(`Empty response after ${emptyResponseMaxRetries} retries. Returning as-is.`);