[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이 작성했습니다