fix(codex): route prompt-bearing TUI launches through the canonical home (#673)

docs/architecture.md

@@ -60,7 +60,7 @@ The standalone manager normalizes bare account-manager commands, so both `codex-
 - Handles multi-auth `auth` subcommands locally.
 - Forwards non-auth commands to official Codex.
 - For request-bearing sessions with runtime rotation enabled, creates a temporary shadow `CODEX_HOME`, writes a local provider (`codex-multi-auth-runtime-proxy`), and starts a loopback proxy for that process.
-- For interactive TUI sessions, `resume`/`fork`, and `codex app-server`, keeps the canonical `CODEX_HOME` and passes the same provider as `-c` overrides instead, so session history and SQLite state are not copied into a shadow and reindexed on every launch. A resident `app-server` needs the canonical home for a stronger reason than convenience: it cannot start at all on a shadow home whose `app-server-control` is a symlink, and a shadow thread index would stay frozen for the life of the process (#659).
+- For interactive TUI sessions (with or without the optional initial `[PROMPT]`), `resume`/`fork`, and `codex app-server`, keeps the canonical `CODEX_HOME` and passes the same provider as `-c` overrides instead, so session history and SQLite state are not copied into a shadow and reindexed on every launch. A resident `app-server` needs the canonical home for a stronger reason than convenience: it cannot start at all on a shadow home whose `app-server-control` is a symlink, and a shadow thread index would stay frozen for the life of the process (#659).
 - Keeps forwarded sessions on file-backed auth state unless the caller opts out.
 - Supports ephemeral force-pin: `codex-multi-auth-codex --account <index|email|id>` (or `CODEX_MULTI_AUTH_FORCE_ACCOUNT`) for a single invocation only — never mutates the persisted `switch` pin.
 

docs/configuration.md

@@ -142,7 +142,7 @@ Keep these enabled for most environments:
 
 ## Runtime Rotation Proxy
 
-`codexRuntimeRotationProxy` is enabled by default. When enabled through defaults, settings, `codex-multi-auth rotation enable`, or `CODEX_MULTI_AUTH_RUNTIME_ROTATION_PROXY=1`, the `codex-multi-auth-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. For non-interactive request commands and `codex app`, 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. Interactive TUI sessions, `resume`/`fork`, and `codex app-server` instead stay on the canonical `CODEX_HOME` and receive the same provider through `-c` overrides, which avoids reindexing session history on every launch and leaves the real `config.toml` untouched. Set `codexRuntimeRotationProxy=false`, run `codex-multi-auth rotation disable`, or set `CODEX_MULTI_AUTH_RUNTIME_ROTATION_PROXY=0` to bypass the proxy.
+`codexRuntimeRotationProxy` is enabled by default. When enabled through defaults, settings, `codex-multi-auth rotation enable`, or `CODEX_MULTI_AUTH_RUNTIME_ROTATION_PROXY=1`, the `codex-multi-auth-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. For non-interactive request commands and `codex app`, 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. Interactive TUI sessions (with or without the optional initial prompt), `resume`/`fork`, and `codex app-server` instead stay on the canonical `CODEX_HOME` and receive the same provider through `-c` overrides, which avoids reindexing session history on every launch and leaves the real `config.toml` untouched. Set `codexRuntimeRotationProxy=false`, run `codex-multi-auth rotation disable`, or set `CODEX_MULTI_AUTH_RUNTIME_ROTATION_PROXY=0` to bypass the proxy.
 
 A single forwarded run can be pinned to one account with `codex-multi-auth-codex --account <selector>` (or `CODEX_MULTI_AUTH_FORCE_ACCOUNT`). The pin is applied per-invocation by that run's own proxy instance, so it never touches the persisted `switch` pin and cannot leak across concurrent sessions. Because the proxy is required for the pin to take effect, `--account` fails hard when the proxy is disabled rather than silently using a rotated account. See [Force an account for one invocation](reference/commands.md#force-an-account-for-one-invocation).
 

docs/development/ARCHITECTURE.md

@@ -55,7 +55,7 @@ Official Codex CLI
 
 Runtime rotation enabled -> one of two homes, over four branches
   |
-  |- interactive TUI (no forwarded subcommand), resume, fork
+  |- interactive TUI (no forwarded subcommand, or a root [PROMPT]), resume, fork
   |    canonical CODEX_HOME + ephemeral -c provider overrides
   |    (no shadow copy, no provider/transport rewrite of config.toml,
   |     detach on exit; the auth-store reconcile above still applies)
@@ -171,7 +171,7 @@ Policy evaluation (`lib/policy/runtime-policy.ts`) can block paused/drained acco
 
    | Branch | Predicate | Transport |
    | --- | --- | --- |
-   | Interactive TUI | `isCodexInteractiveTuiCommand` — no forwarded subcommand at all | App runtime helper with `useCanonicalHome: true` and `detachOnExit: true`. Runs against the **canonical** `CODEX_HOME`; the provider is passed as ephemeral `-c model_providers.*` overrides. No shadow copy and no state sync-back. Nothing **provider- or transport-related** is written into `config.toml` on this path — the only top-level key the wrapper still reconciles there is `cli_auth_credentials_store`, which is transport-independent (see step 4 note). |
+   | Interactive TUI | `isCodexInteractiveTuiCommand` — no forwarded root subcommand: bare `codex [OPTIONS]`, and `codex [OPTIONS] [PROMPT]` with the optional initial prompt, including one forced by `--`. A first positional that does not name a real root subcommand is that prompt, not a command (#673). | App runtime helper with `useCanonicalHome: true` and `detachOnExit: true`. Runs against the **canonical** `CODEX_HOME`; the provider is passed as ephemeral `-c model_providers.*` overrides. No shadow copy and no state sync-back. Nothing **provider- or transport-related** is written into `config.toml` on this path — the only top-level key the wrapper still reconciles there is `cli_auth_credentials_store`, which is transport-independent (see step 4 note). |
    | Interactive `resume` / `fork` | `isCodexInteractiveResumeCommand` — forwarded command is `resume` or `fork` | Same transport and options as the interactive TUI above. These open a TUI against an existing thread, so they must see the canonical thread index. |
    | `app-server` | `isCodexAppServerCommand` — forwarded command is `app-server` | App runtime helper with `useCanonicalHome: true`, `detachOnExit: false`, `installAppServerShim: false`, and `proxyAppServerAccountRead: true`. Same canonical home as the interactive branches; the differences are that a resident server owns its proxy for its whole lifetime rather than detaching it, and that the account-response rewriting is requested explicitly because no shim is present to set the label env. |
    | `codex app` | `isCodexAppCommand` — forwarded command is `app` | App runtime helper process with a shadow `CODEX_HOME`, plus the app-server CLI shim. |

docs/development/CONFIG_FLOW.md

@@ -70,10 +70,10 @@ For dashboard display values:
 ## 6) Runtime Rotation Flow
 
 1. Resolve `CODEX_MULTI_AUTH_RUNTIME_ROTATION_PROXY`; if unset, read `pluginConfig.codexRuntimeRotationProxy`, which defaults to enabled.
-2. If disabled or the forwarded command is help/non-requesting, forward directly to official Codex.
+2. If disabled or the forwarded command is help/non-requesting, forward directly to official Codex. This includes a help flag on a root launch that also carries a prompt (`codex "prompt" --help`): it prints help and exits clean, and the interactive branch detaches its helper on a clean exit, so a helper started just to print help would idle until its detached timeout. The scan stops at `--`, so help-looking text inside a forced prompt still routes normally (#673).
 3. If enabled, start a loopback Responses proxy with a per-process client token.
 4. Select a transport from the forwarded argv:
-   - **No forwarded subcommand (interactive TUI)** — keep the canonical `CODEX_HOME` and pass `codex-multi-auth-runtime-proxy` as ephemeral `-c model_providers.*` overrides. Nothing is copied, no provider or transport config is written into `config.toml`, and the helper detaches on exit. The transport-independent `cli_auth_credentials_store` reconcile below still applies.
+   - **No forwarded root subcommand (interactive TUI)** — bare `codex [OPTIONS]`, and `codex [OPTIONS] [PROMPT]` carrying the optional initial prompt (including one forced by `--`), whose provider overrides are injected ahead of that prompt rather than appended (#673). Keep the canonical `CODEX_HOME` and pass `codex-multi-auth-runtime-proxy` as ephemeral `-c model_providers.*` overrides. Nothing is copied, no provider or transport config is written into `config.toml`, and the helper detaches on exit. The transport-independent `cli_auth_credentials_store` reconcile below still applies.
    - **`resume` / `fork`** — the same canonical-home transport as the interactive TUI. These resume an existing thread, and the shadow home omits the runtime SQLite state, so the shadow transport could not see the requested thread (#647).
    - **`codex app`** — run the app runtime helper against a shadow `CODEX_HOME`.
    - **Any other request-bearing command** — create a temporary shadow `CODEX_HOME` and rewrite its `config.toml` to use `codex-multi-auth-runtime-proxy`.