Updater can leave `codex` on an older version when `~/.local/bin/codex` points at a stale user-local install

What version of Codex CLI is running?

Observed before fix on this machine:

codex-cli 0.118.0

Observed installed latest package at the same time:

@openai/codex@0.135.0

What subscription do you have?

This report comes from a Sprite Linux environment. Subscription tier is not relevant to reproduction.

Which model were you using?

Not relevant.

What platform is your computer?

Linux (Sprite VM / Ubuntu-family environment).

What terminal emulator and version are you using (if applicable)?

Shell environment in Sprite VM.

Codex doctor report

_Not captured before local repair._

What issue are you seeing?

Codex can appear to be "stuck" on an older CLI version even though a newer global npm install already exists.

The root cause was a stale user-local launcher symlink:

/home/sprite/.local/bin/codex -> ../lib/node_modules/@openai/codex/bin/codex.js

That symlink resolved to an older package tree:

/home/sprite/.local/lib/node_modules/@openai/codex/package.json = 0.118.0

At the same time, the active npm global prefix already contained a newer Codex install:

npm config get prefix
# /.sprite/languages/node/nvm/versions/node/v22.20.0

npm list -g --depth=0
# @openai/codex@0.135.0

So the machine had:

• current global package: @openai/codex@0.135.0
• active shell command found first in PATH: /home/sprite/.local/bin/codex
• stale target behind that command: ~/.local/lib/node_modules/@openai/codex at 0.118.0

Because /home/sprite/.local/bin came earlier in PATH, codex --version reported the old version even though the newer package was already installed and available elsewhere.

This is the same bug family as multiple-install / mismatched-update-target issues, but the specific failure mode here is a stale ~/.local/bin/codex symlink that silently keeps launching an older user-local package tree after a newer install lands under a different npm prefix.

What steps can reproduce the bug?

One way to reproduce this class of issue:

1. Have an older user-local install under:

``text
~/.local/lib/node_modules/@openai/codex
``

1. Have ~/.local/bin/codex symlink to that old install:

``text
~/.local/bin/codex -> ../lib/node_modules/@openai/codex/bin/codex.js
``

1. Later install a newer Codex globally under a different npm prefix, for example an nvm-managed prefix:

``text
<other-prefix>/lib/node_modules/@openai/codex
``

1. Keep ~/.local/bin ahead of the newer prefix's bin directory in PATH.
2. Run:

``bash
which codex
codex --version
npm list -g --depth=0
npm config get prefix
``

1. Observe that:

• codex --version reports the old CLI version from ~/.local/bin/codex
• npm list -g shows a newer @openai/codex already installed under a different prefix

Concrete values from the affected machine:

which codex
# /home/sprite/.local/bin/codex

codex --version
# codex-cli 0.118.0

/home/sprite/.local/lib/node_modules/@openai/codex/package.json
# 0.118.0

npm list -g --depth=0
# @openai/codex@0.135.0

npm config get prefix
# /.sprite/languages/node/nvm/versions/node/v22.20.0

What is the expected behavior?

Codex should detect and surface this mismatch clearly.

At minimum, update/install diagnostics should warn when:

• the codex executable first in PATH points at one package root
• npm install -g @openai/codex would update a different package root
• codex --version is therefore likely to stay old even after a successful install

Even better:

• the updater should refuse to claim success if the active codex in PATH still resolves to a different older install
• codex doctor / update diagnostics should explicitly call out a stale launcher symlink such as ~/.local/bin/codex
• the installer/updater could recommend or offer to repoint the launcher to the active npm prefix's bin/codex

Additional information

Local fix on the affected machine was simply to repoint the stale launcher:

ln -sfn /.sprite/languages/node/nvm/versions/node/v22.20.0/bin/codex /home/sprite/.local/bin/codex

After that:

which codex
# /home/sprite/.local/bin/codex

codex --version
# codex-cli 0.135.0

This looks closely related to:

• #21897 (multiple install targets / updater mismatch)

but this issue adds a concrete Linux/Sprite reproduction where the stale path is specifically ~/.local/bin/codex pointing into an old ~/.local/lib/node_modules tree while the newer install lives under a different npm prefix.

cc @Onlydole