[Bug]: a package-manager reinstall of codex destroys the shim and its .opencodex-real backup, with no self-heal

[garysassano]

Client or integration

Codex CLI

Area

Installation or packaging

Summary

When codex is installed by a version manager (mise, asdf, volta, and similar layouts), upgrading it overwrites the opencodex autostart shim and the codex.opencodex-real backup the shim depends on. Nothing detects or repairs this on the next ocx start / ocx ensure, and routing silently reverts to native — producing the misleading symptom reported in #2411.

Reproduction

1. Install codex through a version manager so the binary lives under its install tree, e.g. mise at ~/.local/share/mise/installs/codex/latest/bin/codex.

2. Install the opencodex autostart shim:

   ocx codex-shim install

3. Upgrade codex through the version manager (this replaces the binary in place):

   mise upgrade codex

4. Inspect the shim:

   ocx codex-shim status

   Codex autostart shim: wrapper present but not an opencodex shim at
   /home/<user>/.local/share/mise/installs/codex/latest/bin/codex;
   original backup missing at
   /home/<user>/.local/share/mise/installs/codex/latest/bin/codex.opencodex-real.
   

5. Note that neither ocx start nor ocx ensure repairs or reports it, and that ocx service repair reports success while leaving the condition in place:

   ocx service repair
   # ✅ opencodex service repaired and serving on port 10100.
   
   ocx doctor | grep -A2 'Codex restart safety'
   #   !!  AT RISK after restart (installed service is disabled, stopped, or unhealthy; run 'ocx service repair')
   #        routing=opencodex-local, service=installed-but-unhealthy, shim=stale

6. Timestamps confirm the sequence:

   stat -c '%y %n' ~/.local/share/mise/installs/codex/latest/bin/codex
   # 2026-08-20 22:23:45  (version-manager upgrade to 0.149.0)
   stat -c '%y %n' ~/.codex/config.toml
   # 2026-08-21 21:50:57  (no openai_base_url present)

Expected: the stale shim is detected and either repaired or reported prominently, rather than silently leaving routing native.

Actual: it is only visible via ocx codex-shim status or ocx doctor; ocx status stays green and routing quietly reverts.

Version

opencodex 2.29.0

Operating system

Ubuntu 24.04.4 LTS (WSL2, kernel 6.18.33.2-microsoft-standard-WSL2); codex-cli 0.149.0 installed via mise

Provider and model

Not model-specific — affects every routed model once the shim is stale.

Logs or error output

$ ocx codex-shim status
Codex autostart shim: wrapper present but not an opencodex shim at
/home/<user>/.local/share/mise/installs/codex/latest/bin/codex;
original backup missing at
/home/<user>/.local/share/mise/installs/codex/latest/bin/codex.opencodex-real.

$ ocx doctor | grep -A2 'Codex restart safety'
Codex restart safety
  !!  AT RISK after restart (installed service is disabled, stopped, or unhealthy; run 'ocx service repair')
       routing=opencodex-local, service=installed-but-unhealthy, shim=stale

Why it is awkward to fix locally: the shim replaces the codex binary in place, but under a version manager that binary is owned by the version manager and will be overwritten again on the next upgrade. Reinstalling the shim also cannot restore .opencodex-real, since the original was already overwritten.

Suggestions: (1) report the stale-shim condition in ocx status, not only in codex-shim status / doctor; (2) self-heal on ocx start / ocx ensure where safe, or fall back cleanly and say which; (3) document the version-manager interaction — for version-manager-owned codex, the openai_base_url config route alone may be the supported path, since the shim and the version manager contend for the same file.

Related: #2411 is the user-visible symptom this produces.

[github-actions]

Issue reopened

The report now contains the information required by the automated check. Thanks for updating it.

[lidge-jun]

리뷰 · 우선순위 58 / 80

설명: 이 이슈는 버전 관리자가 코덱스를 덮어 쓰면, 오토스타트 심과 그 옆에 둔 원본 백업이 같이 사라지고, 다음 시작이 고치지 않는다고 한다. 그래서 라우팅이 조용히 네이티브로 돌아간다. 증상은 2411 이다. 지금 CURRENT dev HEAD 는 4f41a8e93 이다. 이번 시간에 origin/dev 는 그대로다. 새 머지는 없다. 착지는 여전히 2396 사용량 CLI 오늘 비용이다. package.json 은 2.27.0 이다. src/config.ts 는 3975줄이다. src/runtime 폴더는 지금 HEAD 에 없다. 지금 HEAD 의 src/codex/shim.ts 603줄은 원본 옆에 .opencodex-real 백업을 둔다. 버전 관리자가 그 폴더의 바이너리를 통째로 바꾸면 심과 백업이 같이 없어진다. 2134줄 diagnoseCodexShim 는 작성자가 본 문구 그대로, 래퍼가 오픈코덱스 심이 아니고 백업이 없다고 말한다. 2015줄 autoRestoreCodexShim 는 2045줄에서 백업도 realPath 도 없으면 ineligible 로 끝낸다. 메시지가 없는 ineligible 은 경고도 없다. src/cli/codex-shim-autorestore.ts 25줄 maybeAutoRestoreCodexShim 는 start 와 ensure 앞에서도 돈다. 고칠 백업이 없으면 조용히 지나친다. 1887줄 자동 복구는 새 설치를 허용하지 않는다. 서비스 repair 는 서비스를 고치고 심은 안 본다. src/cli/index.ts 843줄 상태는 프록시가 살아 있으면 초록이다. 심 요약은 869줄에 있지만 첫 줄은 여전히 초록이다. 작성자 버전은 2.29.0, 우분투 24.04 WSL2, 코덱스 0.149.0 을 mise 로 깔았다. 지금 origin/dev 패키지는 2.27.0 이지만 같은 백업 옆 심 길이 있다. PR 이 아직 없다. bug, install, service 라벨이 있다. 사용자 길이로는 업그레이드 한 번으로 라우팅이 네이티브로 돌아가고 시작이 고치지 않는 구멍이라서 58. 카탈로그 팁은 Ox Alpha x-preview-f-free + deepseek-v4-flash-vision-exp. Cursor 정적 카탈로그는 opus-4-8-fast / opus-5-fast. 2334 CursorCredentialRouter 는 여전히 src/providers/cursor-pool.ts 모듈+테스트만 있고 어댑터에 연결되지 않았다. 2332 H2 는 discovery 전용. 2320 overflow + 2342 는 이미 dev. 2188 사이드카는 이미 dev. 2382 데스크톱 앱 재시작은 이미 dev. 2292 는 아직 연다.

src/codex/shim.ts 라인 603 - 백업은 원본 옆 .opencodex-real 이다. 버전 관리자가 그 칸을 덮으면 심과 백업이 같이 사라진다
src/codex/shim.ts 라인 2045 - autoRestore 는 백업과 realPath 가 둘 다 없으면 ineligible 이다. 메시지 없는 ineligible 은 경고가 없다
src/codex/shim.ts 라인 1887 - 자동 복구는 새 설치를 허용하지 않는다. 사라진 원본을 새로 감싸지 않는다
src/cli/codex-shim-autorestore.ts 라인 25 - start 와 ensure 앞에서도 자동 복구가 돈다. 고칠 백업이 없으면 조용히 지나친다
src/codex/shim.ts 라인 2134 - diagnoseCodexShim 는 작성자가 본 문구 그대로다. 서비스 repair 는 이 길을 안 본다
이슈 본문 2.29.0 / mise / 코덱스 0.149.0 - 작성자 환경이다. 지금 origin/dev 는 2.27.0 이지만 같은 옆 백업 구멍이 있다

메인테이너의 판단이 필요한 지점

• 백업이 없을 때 지금 바이너리를 새 원본으로 감쌀지. 그건 새 설치에 가깝고 자동으로 하면 위험할 수 있다
• 상태 첫 줄에 심이 상했다고 경고할지. 지금은 심 요약이 아래쪽에 있고 프록시는 초록이다
• 버전 관리자가 소유한 코덱스에는 심 대신 openai_base_url 만 지원한다고 문서에 적을지
• 2411 과 한 PR 로 묶을지. 2411 은 상태 표시, 이 이슈는 심이 파괴되는 원인이다

너의 추천
자동 복구를 새 설치로 올리지 말 것. 백업이 사라진 심은 상태가 경고하게 하고, 버전 관리자 소유 코덱스는 설정 주입만 지원한다고 적는다. 이슈는 열어 둔다. 2411 은 닫지 않는다. 라벨은 그대로 둔다. 프리뷰 배포가 아니다.

이 댓글은 grok-bot이 작성했습니다

[lidge-jun]

Landed on dev as 47a31d76e via #2519. PRs here target dev, so GitHub does not auto-close.

Auto-restore now explains itself instead of returning a message-less ineligible, so ocx start, ocx ensure, and ocx service repair surface it. The message names the wrapper state, the missing backup, both paths, and — for a version-manager tree — why no repair is coming.

It deliberately does not repair by adopting the newly installed binary as a replacement original: that records a provenance that never happened, and the next mise upgrade codex would destroy it again, so the fix would silently undo itself on the version manager's schedule.

Per the plan audit, every reachable silent bail now carries a message, not only the one you hit. docs-site/.../cli/lifecycle.md records that a version-manager install tree is not a supported shim target.