Commit 92d0f6f

A corrective release. No new features and no configuration changes.

`codex app-server` was unusable through the wrapper with runtime rotation enabled — which, since rotation is on by default, means it was unusable. On any machine that had ever run an app-server it refused to start; where it did start, every attached client drove threads against a frozen copy of the thread index. This is the third command to move onto the canonical Codex home, after the interactive TUI in v2.8.0 and `resume`/`fork` in v2.8.1, and for the same underlying reason.

Closes [#659](https://github.com/ndycode/codex-multi-auth/issues/659). Landed as [#662](https://github.com/ndycode/codex-multi-auth/pull/662).

Reported with a complete reproduction by [@possibilities](https://github.com/possibilities), who also sent the original patch in [#660](https://github.com/ndycode/codex-multi-auth/pull/660).

$ codex-multi-auth-codex --account <id> app-server --listen unix:///path/to/a.sock

Exit 1, no server. Codex requires `<CODEX_HOME>/app-server-control` to be a directory and checks it with a strict `lstat`. Codex itself creates that directory the first time an app-server runs, so most real homes have one — and the shadow mirror links directories rather than copying them, so the shadow home got a symlink at exactly that path. Deleting `~/.codex/app-server-control` made it start again, which is what pinned the mirror's symlink as the trigger.

The shadow mirror snapshots `state_N.sqlite` rather than linking it. For `resume` that was [#647](https://github.com/ndycode/codex-multi-auth/issues/647): the requested thread was absent and the TUI hung. For an app-server the same divergence is worse in kind rather than degree — it is held for the entire life of the process and handed to every client that attaches, and any thread the server creates is written into a copy that is discarded at exit.

Both failures have one cause, and one fix. `app-server` now takes the canonical-home transport that the bare TUI and `resume`/`fork` already use: a real `app-server-control` directory, the live thread index, and sessions that persist. Rotation stays on and travels as `-c` overrides, so the canonical `config.toml` is never rewritten ([#662](https://github.com/ndycode/codex-multi-auth/pull/662)).

Moving a command onto the canonical-home transport also moves it onto the shared app-helper, and three of that helper's behaviours were wrong for a resident server rather than merely suboptimal.

The shim exists for one purpose: letting the Codex **desktop app** have its own `codex app-server` spawn intercepted through `CODEX_CLI_PATH`. It is reachable only from the app-helper, so any command routed through that helper picks it up silently — and it stamps three things onto the environment the forwarded child inherits:

| Variable | Value | Why it matters for a resident server |

| --- | --- | --- |

| `CODEX_MULTI_AUTH_RUNTIME_ROTATION_PROXY` | `0` | Codex passes its environment to shell tools and MCP servers, so every nested `codex-multi-auth-codex` or `mcodex` run reads rotation as disabled and bills whatever account the official CLI resolves. A nested `--account` fails outright. |

| `CODEX_CLI_PATH` | the shim directory | The file named `codex` there is a copy of `node`. Anything resolving the CLI through this variable and running a subcommand other than `app-server` executes bare node with no script. |

| `NODE_OPTIONS` | `--import=<shim>/…preload.mjs` | Inherited by every Node subprocess the server spawns — on a directory removed at wrapper exit and swept on the next helper start. |

A wrapper-invoked app-server is already launched with the rotation overrides on its own command line and never needs the interception, so it no longer pays for the shim or inherits any of that. On Windows it also no longer copies the ~100 MB Node image into a per-pid directory on every launch. `codex app` and the interactive branches, which do need the shim, are unchanged.

Because there is then no `CODEX_MULTI_AUTH_APP_SERVER_ACCOUNT_LABEL` in the environment, the branch requests `account/read`, `getAuthStatus`, and `account/rateLimits/read` rewriting explicitly instead of inferring it from that variable. Stdio clients see the same responses as before.

The helper detached on any clean exit inside a five-second window, regardless of what the caller asked for. A client that attached, ran one query, and disconnected therefore left a helper running for the full 12-hour idle timeout with nothing left to refresh its activity clock. A supervisor restarting the server stranded one per cycle. A resident server now owns its proxy for its whole lifetime and stops it on exit; the interactive TUI, which detaches deliberately, is unaffected.

The window's clock also started before the helper was launched rather than after it reported ready. Launching is bounded at 15 seconds, so on a cold or loaded machine the entire grace period could elapse during startup — and `codex app`, which relies on the window rather than an explicit flag, would kill the helper it had just handed the desktop app off to.

The shadow path degrades to rotation-off when its proxy will not start. The helper branches have no such shape to fall back to, and the failure surfaced as `ERR_UNHANDLED_REJECTION` with a raw stack trace, leaking the compatibility home the caller had already built. It is now a one-line diagnostic and exit 1, with the compatibility home released first.

The hard failure is deliberate. A resident server that quietly loses rotation serves every attached client on whatever account the official CLI resolves — a billing error you would not see, where a failed launch is one you would. This matches how `--account` has always behaved.

No migration is required, and no settings were added, renamed, or repurposed:

That should report `2.8.4`. Then confirm the fix against a real socket path:

codex-multi-auth-codex app-server --listen unix:///tmp/codex-app-server.sock

It should start instead of exiting 1 on `app-server-control`, and attached clients should see your existing threads.

Note that Codex applies the same strict `lstat` check to the listen socket's own parent directory, so `--listen unix:///tmp/x.sock` fails on macOS because `/tmp` is a symlink to `/private/tmp`. Use a real path — that behaviour is Codex's and is unrelated to this fix.

Three consequences are worth knowing rather than discovering:

- `app-server` no longer creates a shadow home under `<CODEX_HOME>/multi-auth/runtime-shadow-homes/`, or a shim directory under `app-server-shims/`. It reads and writes your canonical home in place, which is what makes threads persist.

- Its rotation helper is stopped when the server exits rather than left to idle out. This is the opposite of the interactive TUI, and it is intentional.

- A rotation proxy that cannot start now fails the server rather than silently running it unrotated.

If you had been running `CODEX_MULTI_AUTH_RUNTIME_ROTATION_PROXY=0` to get an app-server to start at all, drop it — that workaround bought a working server by turning off account rotation:

unset CODEX_MULTI_AUTH_RUNTIME_ROTATION_PROXY

codex-multi-auth rotation status

That should report the runtime rotation proxy as enabled.

Five wrapper tests cover the canonical-home routing, a real `app-server-control` directory and a live thread index the server can append to, the absence of every shim side effect, helper reaping on both clean and non-zero server exits, the clean-diagnostic startup-failure path with its compatibility-home release, and `--account` propagation across the detached helper boundary.

Helper reaping is asserted by polling the helper pid rather than by waiting for a shutdown marker, because Windows hard-terminates the helper and it never reaches its own cleanup handler. None of the tests shortens the idle timeout, so a stranded helper fails them instead of passing quietly.

The full local suite passed with 337 test files passing and 1 skipped, for 5,364 tests passing and 4 skipped.