Add runtime rotation proxy

README.md

@@ -165,9 +165,10 @@ If browser launch is blocked, use the alternate login paths in [docs/getting-sta
 
 | Command | What it answers |
 | --- | --- |
-| `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? |
+| `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? |
+| `codex auth rotation status` | Is live runtime account rotation enabled for forwarded Codex sessions? |
 
 ### Reliability behavior
 
@@ -230,9 +231,13 @@ Selected runtime/environment overrides:
 | Variable | Effect |
 | --- | --- |
 | `CODEX_MULTI_AUTH_DIR` | Override settings/accounts root |
-| `CODEX_MULTI_AUTH_CONFIG_PATH` | Alternate config file path |
-| `CODEX_MODE=0/1` | Disable/enable Codex mode |
-| `CODEX_TUI_V2=0/1` | Disable/enable TUI v2 |
+| `CODEX_MULTI_AUTH_CONFIG_PATH` | Alternate config file path |
+| `CODEX_MODE=0/1` | Disable/enable Codex mode |
+| `CODEX_MULTI_AUTH_RUNTIME_ROTATION_PROXY=0/1` | Opt in/out of live Responses proxy rotation for forwarded Codex CLI/app sessions |
+| `CODEX_MULTI_AUTH_APP_ROTATION_IDLE_MS=<ms>` | Override automatic Codex app helper idle shutdown |
+| `CODEX_MULTI_AUTH_APP_BIND_INSTALL=0/1` | Opt out/in of packaged Codex app bind self-heal during install/update or rotation enable |
+| `CODEX_MULTI_AUTH_APP_LAUNCHER_INSTALL=0/1` | Opt out/in of routing supported app shortcuts during rotation enable |
+| `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_BACKGROUND_RESPONSES=0/1` | Opt in/out of stateful Responses `background: true` compatibility |

docs/configuration.md

@@ -29,6 +29,7 @@ Runtime configuration is resolved from unified settings, optional override files
   },
   "pluginConfig": {
     "codexMode": true,
+    "codexRuntimeRotationProxy": false,
     "liveAccountSync": true,
     "sessionAffinity": true,
     "proactiveRefreshGuardian": true,
@@ -63,6 +64,7 @@ These are safe for most operators and frequently used in day-to-day workflows.
 | `CODEX_MULTI_AUTH_DIR` | Override root directory for plugin-managed runtime files |
 | `CODEX_MULTI_AUTH_CONFIG_PATH` | Load configuration from alternate path |
 | `CODEX_MODE=0/1` | Disable or enable Codex mode |
+| `CODEX_MULTI_AUTH_RUNTIME_ROTATION_PROXY=0/1` | Opt in to live Codex Responses routing through the localhost account-rotation proxy |
 | `CODEX_TUI_V2=0/1` | Disable or enable TUI v2 |
 | `CODEX_TUI_COLOR_PROFILE=truecolor|ansi256|ansi16` | Color profile selection |
 | `CODEX_TUI_GLYPHS=ascii|unicode|auto` | Glyph mode selection |
@@ -99,6 +101,22 @@ Keep these enabled for most environments:
 
 ---
 
+## Runtime Rotation Proxy
+
+`codexRuntimeRotationProxy` is disabled by default. When enabled through settings, `codex auth rotation enable`, or `CODEX_MULTI_AUTH_RUNTIME_ROTATION_PROXY=1`, the `codex` wrapper starts a localhost-only Responses proxy for forwarded official Codex sessions, including CLI request commands, `codex app-server`, and `codex app` launches through the wrapper. The wrapper writes a temporary shadow `CODEX_HOME/config.toml` that selects a custom provider named `codex-multi-auth-runtime-proxy`, launches the official Codex surface against that provider, and removes the shadow home after the owning process exits.
+
+The proxy preserves request bodies and streaming responses, replaces outbound auth headers with the selected managed account, and rotates to another account before response bytes are streamed when it sees rate limits, server errors, network failures, or refresh failures. If every account is unavailable, the proxy returns a structured pool-exhaustion error that points to `codex auth rotation status`.
+
+For `codex app` launches that go through the wrapper, the wrapper automatically starts a small internal helper so rotation can keep working if the desktop app launcher detaches. The helper stores only local runtime status, uses the same per-session proxy client key as the CLI path, and exits after an idle timeout.
+
+`codex auth rotation enable` also binds the packaged desktop app to a persistent localhost router. This backs up the real Codex `config.toml`, writes the `codex-multi-auth-runtime-proxy` provider into the real Codex home, starts the router immediately, and installs a user login startup entry: a Startup `.cmd` on Windows or a LaunchAgent on macOS. The persistent provider is marked as not requiring OpenAI auth and uses a local app-bind client token, so the desktop runtime does not display the selected multi-auth account while codex-multi-auth status and quota views still read the router's last-account telemetry. `codex auth rotation disable` and `codex auth rotation unbind-app` stop that router, remove the startup entry, and restore the backed-up Codex config. The official app files are not patched.
+
+Package install/update also self-heals this bind when runtime rotation was already enabled and a Codex desktop app is detected. Set `CODEX_MULTI_AUTH_APP_BIND_INSTALL=0` to skip install/update self-heal, or `CODEX_MULTI_AUTH_APP_BIND_INSTALL=1` to force it. Supported user-level launcher routing remains available for `.lnk` and managed wrapper app cases; set `CODEX_MULTI_AUTH_APP_LAUNCHER_INSTALL=0` before enabling rotation to skip that shortcut routing, or run `codex-multi-auth-app-launcher --remove` to restore backed-up Windows shortcuts or remove the managed macOS wrapper later.
+
+Some Windows installs expose Codex only as a packaged `shell:AppsFolder` app entry. Those entries cannot be retargeted like `.lnk` files, so the persistent app bind is the supported path for making the pinned packaged app use rotation automatically.
+
+---
+
 ## Shipped Templates
 
 The shipped config templates expose first-class GPT-5.5 model aliases:

docs/development/CONFIG_FIELDS.md

@@ -44,6 +44,7 @@ Used only for host plugin mode through the host runtime config file.
 | Key | Default |
 | --- | --- |
 | `codexMode` | `true` |
+| `codexRuntimeRotationProxy` | `false` |
 | `codexTuiV2` | `true` |
 | `codexTuiColorProfile` | `truecolor` |
 | `codexTuiGlyphMode` | `ascii` |
@@ -200,6 +201,7 @@ Upgrade note:
 | `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_MULTI_AUTH_RUNTIME_ROTATION_PROXY` | Toggle opt-in localhost Responses proxy for forwarded Codex sessions (`1`/`true` to enable, `0`/`false` to disable) |
 | `CODEX_TUI_V2` | Toggle TUI v2 |
 | `CODEX_TUI_COLOR_PROFILE` | TUI color profile |
 | `CODEX_TUI_GLYPHS` | TUI glyph mode |

docs/features.md

@@ -24,6 +24,7 @@ User-facing capability map for `codex-multi-auth`.
 | Readiness and risk forecast | Suggests the best next account | `codex auth forecast` |
 | Live quota probe mode | Uses live headers for stronger decisions | `codex auth forecast --live` |
 | JSON report output | Lets you inspect account state in automation or support workflows | `codex auth report --live --json` |
+| Runtime rotation proxy (opt-in) | Lets forwarded official Codex CLI/app sessions rotate managed accounts between Responses requests without restarting the session. Disabled by default; enable per install. | `codex auth rotation enable` |
 
 ---
 

docs/reference/commands.md

@@ -58,6 +58,7 @@ Compatibility aliases are supported:
 | `codex auth features` | Print implemented feature summary |
 | `codex auth report` | Generate full health report |
 | `codex auth why-selected [--now|--last]` | Explain which account the selector picks now or via the last persisted runtime snapshot |
+| `codex auth rotation enable\|disable\|status\|bind-app\|unbind-app` | Manage the opt-in runtime Responses proxy for live Codex account rotation |
 
 ---
 
@@ -150,6 +151,39 @@ The `runtimeSnapshot` field is present only with `--last`. `selected` is
 
 ---
 
+## `codex auth rotation`
+
+Manages the opt-in runtime Responses proxy used by forwarded official Codex sessions. This is separate from normal `codex auth switch`: the proxy can rotate managed accounts between backend Responses requests while a Codex session stays open.
+
+Usage:
+
+```bash
+codex auth rotation enable
+codex auth rotation disable
+codex auth rotation status
+codex auth rotation bind-app
+codex auth rotation unbind-app
+```
+
+Behavior:
+
+- `enable` persists `codexRuntimeRotationProxy=true`, binds the packaged desktop app to the same persistent localhost router, and routes supported user-level app shortcuts when possible.
+- `disable` persists `codexRuntimeRotationProxy=false` and removes the persistent packaged-app bind.
+- `status` prints the effective setting, environment override state, automatic Codex app helper state, persistent Codex app bind state, account count, current account, disabled accounts, cooldowns, and rate-limit waits.
+- `bind-app` repairs or installs the persistent packaged-app bind without changing the stored rotation setting.
+- `unbind-app` removes the persistent packaged-app bind and restores the backed-up Codex config.
+- `CODEX_MULTI_AUTH_RUNTIME_ROTATION_PROXY=1` enables the proxy for the current process without changing settings.
+
+When enabled, the wrapper creates a temporary shadow `CODEX_HOME/config.toml` with a custom provider named `codex-multi-auth-runtime-proxy`, starts a `127.0.0.1` proxy on a random port, and forwards official Codex Responses traffic through that provider. This applies to CLI request commands plus `codex app-server` and `codex app` when they are launched through the wrapper. Existing behavior is unchanged while the setting and env override are off.
+
+Packaged desktop app support uses a reversible bind instead of patching app files. It backs up the real Codex `config.toml`, writes the same custom provider to the real Codex home, starts a localhost-only router, and installs a user login startup entry: a Startup `.cmd` on Windows or a LaunchAgent on macOS. The provider uses a local app-bind client token and `requires_openai_auth=false`, which keeps the selected multi-auth account out of the runtime composer while preserving router last-account telemetry for codex-multi-auth status and quota views. Package install/update runs the same bind only when runtime rotation was already enabled and a Codex desktop app is detected; set `CODEX_MULTI_AUTH_APP_BIND_INSTALL=0` to skip that self-heal or `CODEX_MULTI_AUTH_APP_BIND_INSTALL=1` to force it.
+
+The app launcher routing helper is also available directly as `codex-multi-auth-app-launcher`. On Windows, it retargets existing user-level `Codex` shortcuts and taskbar pins to the wrapper while backing up their original target for restore. On macOS, it creates or removes a user-level `Codex Multi Auth.app` wrapper because Dock entries cannot safely launch a shell command directly. It does not patch the official app files. Use `codex-multi-auth-app-launcher --remove` to restore backed-up Windows shortcuts or remove the managed macOS wrapper.
+
+If Windows exposes Codex only as a packaged `shell:AppsFolder` entry, shortcut routing may still report that there is no retargetable `.lnk`. The persistent app bind is the path that makes those packaged entries use rotation when the official app is opened directly.
+
+---
+
 ## `codex auth verify`
 
 Supersedes `codex auth verify-flagged` as a single entry point for

docs/reference/settings.md

@@ -185,6 +185,8 @@ Common operator overrides:
 - `CODEX_MULTI_AUTH_DIR`
 - `CODEX_MULTI_AUTH_CONFIG_PATH`
 - `CODEX_MODE`
+- `CODEX_MULTI_AUTH_RUNTIME_ROTATION_PROXY`
+- `CODEX_MULTI_AUTH_APP_BIND_INSTALL`
 - `CODEX_TUI_V2`
 - `CODEX_TUI_COLOR_PROFILE`
 - `CODEX_TUI_GLYPHS`

docs/releases/v1.3.1.md

@@ -23,6 +23,14 @@ This patch release finalizes the GPT-5.5 runtime rollout work for `codex-multi-a
 - verified native `gpt-5.5` behavior on official Codex `0.124.0`
 - preserved deterministic fallback behavior for older official Codex runtimes and non-entitled or quota-limited accounts
 
+### Runtime Rotation Proxy
+
+- added opt-in `codexRuntimeRotationProxy` and `CODEX_MULTI_AUTH_RUNTIME_ROTATION_PROXY=1`
+- added `codex auth rotation enable|disable|status`
+- forwarded official Codex sessions can use a temporary shadow `CODEX_HOME` and localhost Responses proxy to rotate managed accounts between backend requests
+- `codex app-server` and wrapper-launched `codex app` now use the same runtime rotation path automatically when rotation is enabled
+- rotation enable routes existing Windows user-level `Codex` shortcuts and taskbar pins through the wrapper-backed `codex app` path, and creates a managed macOS wrapper for the same path, without patching official Codex app files
+
 ## Validation
 
 - `npm run build`

lib/codex-manager.ts

@@ -71,6 +71,7 @@ import {
 import { runForecastCommand } from "./codex-manager/commands/forecast.js";
 import { runInitConfigCommand } from "./codex-manager/commands/init-config.js";
 import { runReportCommand } from "./codex-manager/commands/report.js";
+import { runRotationCommand } from "./codex-manager/commands/rotation.js";
 import {
 	runFeaturesCommand,
 	runStatusCommand,
@@ -83,7 +84,17 @@ import {
 	configureUnifiedSettings,
 	resolveMenuLayoutMode,
 } from "./codex-manager/settings-hub.js";
-import { getPluginConfigExplainReport } from "./config.js";
+import {
+	getCodexRuntimeRotationProxy,
+	getPluginConfigExplainReport,
+	loadPluginConfig,
+	savePluginConfig,
+} from "./config.js";
+import {
+	bindCodexAppRuntimeRotation,
+	getAppBindStatus,
+	unbindCodexAppRuntimeRotation,
+} from "./runtime/app-bind.js";
 import { ACCOUNT_LIMITS } from "./constants.js";
 import {
 	type DashboardAccountSortMode,
@@ -1193,6 +1204,55 @@ function toExistingAccountInfo(
 	}));
 }
 
+function activeAccountMatchesCodexCliState(
+	account: AccountMetadataV3,
+	state: Awaited<ReturnType<typeof loadCodexCliState>>,
+): boolean {
+	if (!state) return true;
+	const accountId = account.accountId?.trim();
+	const activeAccountId = state.activeAccountId?.trim();
+	if (accountId && activeAccountId) {
+		return accountId === activeAccountId;
+	}
+
+	const email = sanitizeEmail(account.email);
+	const activeEmail = sanitizeEmail(state.activeEmail);
+	if (email && activeEmail) {
+		return email === activeEmail;
+	}
+
+	return false;
+}
+
+async function syncCodexCliActiveSelectionIfDrifted(
+	storage: AccountStorageV3,
+): Promise<boolean> {
+	const activeIndex = resolveActiveIndex(storage, "codex");
+	if (activeIndex < 0 || activeIndex >= storage.accounts.length) {
+		return false;
+	}
+	const account = storage.accounts[activeIndex];
+	if (!account) {
+		return false;
+	}
+
+	try {
+		const cliState = await loadCodexCliState({ forceRefresh: true });
+		if (!cliState || activeAccountMatchesCodexCliState(account, cliState)) {
+			return false;
+		}
+		return setCodexCliActiveSelection({
+			accountId: account.accountId,
+			email: account.email,
+			accessToken: account.accessToken,
+			refreshToken: account.refreshToken,
+			expiresAt: account.expiresAt,
+		});
+	} catch {
+		return false;
+	}
+}
+
 function resolveAccountSelection(
 	tokens: TokenSuccess,
 ): TokenSuccessWithAccount {
@@ -2726,6 +2786,7 @@ async function runAuthLogin(args: string[]): Promise<number> {
 					}
 				}
 				const flaggedStorage = await loadFlaggedAccounts();
+				await syncCodexCliActiveSelectionIfDrifted(currentStorage);
 
 				const menuResult = await promptLoginMode(
 					toExistingAccountInfo(currentStorage, quotaCache, displaySettings),
@@ -3378,6 +3439,20 @@ export async function runCodexMultiAuthCli(rawArgs: string[]): Promise<number> {
 				loadPersistedRuntimeObservabilitySnapshot,
 		});
 	}
+	if (command === "rotation") {
+		return runRotationCommand(rest, {
+			loadPluginConfig,
+			savePluginConfig,
+			getCodexRuntimeRotationProxy,
+			setStoragePath,
+			getStoragePath,
+			loadAccounts,
+			resolveActiveIndex,
+			bindCodexApp: bindCodexAppRuntimeRotation,
+			unbindCodexApp: unbindCodexAppRuntimeRotation,
+			getCodexAppBindStatus: getAppBindStatus,
+		});
+	}
 	if (command === "why-selected") {
 		return runWhySelectedCommand(rest, {
 			parseWhySelectedArgs,