fix(codex): auto-restore the codex shim after external npm updates (#320)

README.ja.md

@@ -273,10 +273,17 @@ opencodex にはプロキシを自動起動する方法が 2 つあります:
 | **方式** | OS サービスマネージャー(launchd / systemd / schtasks) | `codex` スクリプトランチャーをラップし実際の `codex.exe` は触らない |
 | **タイミング** | ログイン後に常時実行 | オンデマンド — `codex` 起動時に `ocx ensure` を実行 |
 | **再起動** | クラッシュ時に自動再起動 | `codex` 呼び出しごとに 1 回起動 |
-| **Codex 更新** | 影響なし | `ocx codex-shim install` または `ocx update` 時に修復 |
+| **Codex 更新** | 影響なし | 安定して置換されたランチャーは次の通常の `ocx` コマンドで修復 |
 | **削除** | `ocx service uninstall` | `ocx codex-shim uninstall` |
 
 常にプロキシを起動しておくには **service**(開発マシン推奨)、軽くオンデマンドで使うには **shim** を使ってください。
+
+外部の Codex 更新でインストール済み shim が上書きされた場合、次の通常の `ocx` コマンドが
+安定した新しいランチャーをバックアップして shim を復元します。まだ変更中のランチャーには触れず、
+後続のコマンドで再試行します。修復失敗は要求されたコマンドを失敗させず警告だけを表示し、手動の
+代替手段は `ocx codex-shim install` です。自動修復を無効にするには
+`codexShimAutoRestore` を `false` にするか、プロセスで
+`OPENCODEX_CODEX_SHIM_AUTO_RESTORE=0` を設定します。
 shim 自動起動はデフォルトでオンで、GUI ダッシュボードからオフにできます。設定されたプロキシポートが既に使用
 中の場合、`ocx start` が自動的に別の空きローカルポートを選び、Codex の設定もそのポートに更新します。
 

README.ko.md

@@ -264,10 +264,16 @@ opencodex에는 프록시를 자동 시작하는 두 가지 방법이 있습니
 | **방식** | OS 서비스 관리자 (launchd / systemd / schtasks) | `codex` 스크립트 런처를 래핑하며 실제 `codex.exe`는 건드리지 않음 |
 | **시점** | 로그인 후 항상 실행 | 온디맨드 — `codex` 실행 시 `ocx ensure` 실행 |
 | **재시작** | 크래시 시 자동 재시작 | `codex` 호출마다 한 번 시작 |
-| **Codex 업데이트** | 영향 없음 | `ocx codex-shim install` 또는 `ocx update` 시 복구 |
+| **Codex 업데이트** | 영향 없음 | 안정적으로 교체가 끝난 런처는 다음 일반 `ocx` 명령에서 복구 |
 | **제거** | `ocx service uninstall` | `ocx codex-shim uninstall` |
 
 항상 프록시를 켜두려면 **service** (개발 머신 권장), 가볍게 온디맨드로 쓰려면 **shim**을 사용하세요.
+
+외부 Codex 업데이트가 설치된 shim을 덮어쓰면 다음 일반 `ocx` 명령이 안정화된 새 런처를 백업하고
+shim을 복구합니다. 아직 변경 중인 런처는 건드리지 않고 이후 명령에서 다시 시도합니다. 복구 실패는
+요청한 명령을 실패시키지 않고 경고만 출력하며, 수동 대체 명령은 `ocx codex-shim install`입니다.
+자동 복구를 끄려면 `codexShimAutoRestore`를 `false`로 설정하거나 프로세스에
+`OPENCODEX_CODEX_SHIM_AUTO_RESTORE=0`을 설정하세요.
 shim 자동 시작은 기본으로 켜져 있으며 GUI 대시보드에서 끌 수 있습니다. 설정된 프록시 포트가 이미 사용
 중이면 `ocx start`가 자동으로 다른 빈 로컬 포트를 고르고 Codex 설정도 그 포트로 갱신합니다.
 

README.md

@@ -305,14 +305,20 @@ opencodex has two ways to auto-start the proxy:
 | **How** | OS service manager (launchd / systemd / schtasks) | Wraps script launchers for `codex`; real `codex.exe` is left untouched |
 | **When** | Always running after login | On-demand — runs `ocx ensure` when `codex` is launched |
 | **Restart** | Auto-restarts on crash | Starts once per `codex` invocation |
-| **Codex updates** | Unaffected | Repairs on next `ocx codex-shim install` or `ocx update` |
+| **Codex updates** | Unaffected | A completed stable launcher replacement is repaired by the next ordinary `ocx` command |
 | **Remove** | `ocx service uninstall` | `ocx codex-shim uninstall` |
 
 Use the **service** for always-on proxy (recommended for development machines). Use the **shim** for
 lightweight, on-demand proxy startup without a background daemon. Shim autostart is enabled by default
 and can be disabled from the GUI dashboard. If the configured proxy port is already busy, `ocx start`
 automatically picks another free local port and updates Codex to use it.
 
+If an external Codex update overwrites an installed shim, the next ordinary `ocx` command backs up
+the stable new launcher and restores the shim. A launcher that is still changing is left untouched
+and retried later. Repair failures warn without failing the requested command; use
+`ocx codex-shim install` as the manual fallback. Set `codexShimAutoRestore` to `false`, or set
+`OPENCODEX_CODEX_SHIM_AUTO_RESTORE=0` for a process-level opt-out.
+
 ### Uninstall
 
 Before removing the npm package, clean up local state:

README.ru.md

@@ -305,10 +305,16 @@ ocx update [--tag preview]     # обновить opencodex; preview-устан
 | **Как** | Менеджер служб ОС (launchd / systemd / schtasks) | Оборачивает скриптовые лончеры `codex`; настоящий `codex.exe` не затрагивается |
 | **Когда** | Всегда работает после входа в систему | По требованию — выполняет `ocx ensure` при запуске `codex` |
 | **Перезапуск** | Автоматический перезапуск при сбое | Запускается один раз на каждый вызов `codex` |
-| **Обновления Codex** | Не влияют | Восстанавливается при следующем `ocx codex-shim install` или `ocx update` |
+| **Обновления Codex** | Не влияют | Стабильно заменённый лончер восстанавливается следующей обычной командой `ocx` |
 | **Удаление** | `ocx service uninstall` | `ocx codex-shim uninstall` |
 
 Используйте **службу**, если прокси должен работать постоянно (рекомендуется для машин разработчиков).
+Если внешнее обновление Codex перезапишет установленный shim, следующая обычная команда `ocx`
+сохранит стабильный новый лончер в резервную копию и восстановит shim. Лончер, который ещё меняется,
+остаётся нетронутым до следующей команды. Ошибка восстановления выдаёт предупреждение, но не приводит
+к сбою запрошенной команды; ручной вариант — `ocx codex-shim install`. Для отключения установите
+`codexShimAutoRestore` в `false` или задайте процессу
+`OPENCODEX_CODEX_SHIM_AUTO_RESTORE=0`.
 Используйте **shim** для лёгкого запуска прокси по требованию без фонового демона. Автозапуск через
 shim включён по умолчанию и отключается в GUI-панели управления. Если настроенный порт прокси уже
 занят, `ocx start` автоматически выберет другой свободный локальный порт и обновит настройки Codex.

README.zh-CN.md

@@ -257,10 +257,16 @@ opencodex 提供两种自动启动代理的方式：
 | **方式** | OS 服务管理器（launchd / systemd / schtasks） | 包装 `codex` 脚本启动器；不会改动真实 `codex.exe` |
 | **时机** | 登录后始终运行 | 按需 — 仅在运行 `codex` 时启动 |
 | **重启** | 崩溃后自动重启 | 每次调用 `codex` 时启动一次 |
-| **Codex 更新** | 不受影响 | 下次运行 `ocx codex-shim install` 或 `ocx update` 时修复 |
+| **Codex 更新** | 不受影响 | 稳定完成的启动器替换会在下一条普通 `ocx` 命令中修复 |
 | **移除** | `ocx service uninstall` | `ocx codex-shim uninstall` |
 
 如需常驻代理，使用 **service**（推荐开发环境）。轻量按需启动使用 **shim**。
+
+如果外部 Codex 更新覆盖了已安装的 shim，下一条普通 `ocx` 命令会备份已稳定的新启动器并恢复
+shim。仍在变化的启动器不会被改动，而会在后续命令中重试。修复失败只会警告，不会让请求的命令
+失败；手动备用命令为 `ocx codex-shim install`。若要关闭自动恢复，请将
+`codexShimAutoRestore` 设为 `false`，或为进程设置
+`OPENCODEX_CODEX_SHIM_AUTO_RESTORE=0`。
 如果配置的代理端口已被占用，`ocx start` 会自动选择另一个空闲本地端口并更新 Codex 使用它。
 
 ### 卸载

docs-site/src/content/docs/ja/reference/cli.md

@@ -357,8 +357,12 @@ ocx service uninstall
 PATH 上のスクリプトベース `codex` ランチャーを軽量な自動起動スクリプトで包みます。実際の `codex.exe`
 対象は正確な実行ファイル呼び出しが壊れないように触りません。
 
-Codex 更新がラッパーを上書きしても次の `install` 呼び出しで shim が自己修復します。新しい
-バイナリをバックアップしたのち新しいラッパーを書きます。
+完了した外部 Codex 更新がインストール済み shim を上書きした場合、次の通常の `ocx` コマンドが
+安定した新しいランチャーをバックアップし、コマンド実行前に shim を復元します。まだ変更中の
+ランチャーには触れず、後で再試行します。修復失敗は要求されたコマンドを失敗させず警告だけを
+表示し、手動の代替手段は `ocx codex-shim install` です。自動修復を無効にするには
+`codexShimAutoRestore` を `false` にするか、プロセスで
+`OPENCODEX_CODEX_SHIM_AUTO_RESTORE=0` を設定します。
 
 | Subcommand | Action |
 | --- | --- |

docs-site/src/content/docs/ja/reference/configuration.md

@@ -47,6 +47,7 @@ namespaced selected id を bare id に変えます。
 | `websockets?` | `boolean` | `false` | `supports_websockets` を知らせ Codex が Responses WebSocket 経路を使うようにします。省略または `false` なら HTTP/SSE を維持します。 |
 | `apiKeys?` | `OcxApiKey[]` | `[]` | 非 loopback バインドで管理 API とデータプレーン認証に追加で許可する生成型 `ocx_…` 認証情報。ダッシュボードが管理し、項目フィールドは下で説明します。 |
 | `codexAutoStart?` | `boolean` | `true` | Codex shim が Codex 実行前に `ocx ensure` を実行するようにします。`false` なら `ocx ensure` は何もしません。 |
+| `codexShimAutoRestore?` | `boolean` | `true` | 完了した外部 Codex 更新で以前にインストールした shim が置換された場合に復元します。無効にするには `false`、またはプロセスで `OPENCODEX_CODEX_SHIM_AUTO_RESTORE=0` を設定します。 |
 | `syncResumeHistory?` | `boolean` | `true` | 戻せる Codex App 履歴互換モード。opencodex は元の Codex thread metadata をバックアップし、旧 OpenAI interactive row を `opencodex` に再マッピングし、opencodex が作成した `exec` row を App に見えるソースとして一時的に昇格します。`ocx stop` / `ocx restore` はバックアップした OpenAI row を復元し、残った opencodex user thread を OpenAI に戻し、ネイティブ Codex が `config.toml` からプロキシを削除した後でも開き続けられるようにします。オフにするには `false` に設定します。 |
 | `codexAccounts?` | `CodexAccount[]` | `[]` | Codex Auth ダッシュボードが管理する ChatGPT/Codex pool アカウント metadata。secret は `codex-accounts.json` に別途置きます。 |
 | `activeCodexAccountId?` | `string` | — | 次の新しい Codex thread に使う pool アカウント。既存 thread affinity は元のアカウントを維持します。 |

docs-site/src/content/docs/ko/reference/cli.md

@@ -376,8 +376,11 @@ ocx service uninstall
 PATH에 있는 스크립트 기반 `codex` 런처를 가벼운 자동 시작 스크립트로 감쌉니다. 실제 `codex.exe`
 대상은 정확한 실행 파일 호출이 깨지지 않도록 건드리지 않습니다.
 
-Codex 업데이트가 래퍼를 덮어쓰더라도 다음 `install` 호출에서 shim이 스스로 복구됩니다. 새
-바이너리를 백업한 뒤 새 래퍼를 씁니다.
+완료된 외부 Codex 업데이트가 설치된 shim을 덮어쓰면 다음 일반 `ocx` 명령이 안정화된 새 런처를
+백업하고 명령 실행 전에 shim을 복구합니다. 아직 변경 중인 런처는 건드리지 않고 이후에 다시
+시도합니다. 복구 실패는 요청한 명령을 실패시키지 않고 경고만 출력하며, 수동 대체 명령은
+`ocx codex-shim install`입니다. 자동 복구를 끄려면 `codexShimAutoRestore`를 `false`로 설정하거나
+프로세스에 `OPENCODEX_CODEX_SHIM_AUTO_RESTORE=0`을 설정하세요.
 
 | Subcommand | Action |
 | --- | --- |

docs-site/src/content/docs/ko/reference/configuration.md

@@ -48,6 +48,7 @@ namespaced selected id를 bare id로 바꿉니다.
 | `websockets?` | `boolean` | `false` | `supports_websockets`를 알려 Codex가 Responses WebSocket 경로를 쓰게 합니다. 생략하거나 `false`이면 HTTP/SSE를 유지합니다. |
 | `apiKeys?` | `OcxApiKey[]` | `[]` | 비-loopback 바인드에서 관리 API와 data plane 인증에 추가로 허용할 생성형 `ocx_…` 자격 증명. 대시보드가 관리하며 항목 필드는 아래에 설명합니다. |
 | `codexAutoStart?` | `boolean` | `true` | Codex shim이 Codex 실행 전에 `ocx ensure`를 실행하게 합니다. `false`이면 `ocx ensure`가 아무 작업도 하지 않습니다. |
+| `codexShimAutoRestore?` | `boolean` | `true` | 완료된 외부 Codex 업데이트가 이전에 설치한 shim을 교체하면 자동으로 복구합니다. 끄려면 `false`로 설정하거나 프로세스에 `OPENCODEX_CODEX_SHIM_AUTO_RESTORE=0`을 설정합니다. |
 | `syncResumeHistory?` | `boolean` | `true` | 되돌릴 수 있는 Codex App 기록 호환 모드. opencodex가 원래 Codex thread metadata를 백업하고, 예전 OpenAI interactive row를 `opencodex`로 재매핑하며, opencodex가 만든 `exec` row를 App에 보이는 source로 잠시 승격합니다. `ocx stop` / `ocx restore`는 백업한 OpenAI row를 복원하고 남은 opencodex user thread를 OpenAI로 돌려 네이티브 Codex가 `config.toml`에서 프록시를 제거한 뒤에도 이어서 열 수 있게 합니다. 끄려면 `false`로 설정합니다. |
 | `codexAccounts?` | `CodexAccount[]` | `[]` | Codex Auth 대시보드에서 관리하는 ChatGPT/Codex pool 계정 metadata. secret은 `codex-accounts.json`에 따로 둡니다. |
 | `activeCodexAccountId?` | `string` | — | 다음 새 Codex thread에 쓸 pool 계정. 기존 thread affinity는 원래 계정을 유지합니다. |

docs-site/src/content/docs/reference/cli.md

@@ -372,8 +372,11 @@ ocx service uninstall
 Wrap a script-based `codex` launcher on PATH with a lightweight autostart script. Real `codex.exe`
 targets are left untouched to avoid breaking exact executable invocations.
 
-If Codex is updated and overwrites the wrapper, the shim auto-repairs on the next `install` call —
-the new binary is backed up and a fresh wrapper is written.
+If a completed external Codex update overwrites an installed shim, the next ordinary `ocx` command
+backs up the stable new launcher and restores the shim before dispatch. A launcher that is still
+changing is left untouched and retried later. Repair failures warn without failing the requested
+command; manual fallback: `ocx codex-shim install`. Set `codexShimAutoRestore` to `false`, or set
+`OPENCODEX_CODEX_SHIM_AUTO_RESTORE=0` for a process-level opt-out.
 
 | Subcommand | Action |
 | --- | --- |

docs-site/src/content/docs/reference/configuration.md

@@ -49,6 +49,7 @@ differing backup and rewrites known legacy namespaced selected ids to bare ids.
 | `websockets?` | `boolean` | `false` | Advertise `supports_websockets` so Codex uses the Responses WebSocket path. Omit or set `false` to keep HTTP/SSE. |
 | `apiKeys?` | `OcxApiKey[]` | `[]` | Additional generated `ocx_…` credentials accepted by management and data-plane auth on non-loopback binds. Managed by the dashboard; entry fields are listed below. |
 | `codexAutoStart?` | `boolean` | `true` | Let the Codex shim run `ocx ensure` before launching Codex. `false` makes `ocx ensure` a no-op. |
+| `codexShimAutoRestore?` | `boolean` | `true` | Restore a previously installed Codex shim when a completed external Codex update replaces it. Set `false`, or set `OPENCODEX_CODEX_SHIM_AUTO_RESTORE=0` for a process-level opt-out. |
 | `syncResumeHistory?` | `boolean` | `true` | Reversible Codex App history compatibility mode. opencodex backs up original Codex thread metadata, remaps old OpenAI interactive rows to `opencodex`, and temporarily promotes opencodex-created `exec` rows to an app-visible source. `ocx stop` / `ocx restore` restore backed-up OpenAI rows and eject remaining opencodex user threads to OpenAI so native Codex can resume them after the proxy is removed from `config.toml`. Set `false` to opt out. |
 | `codexAccounts?` | `CodexAccount[]` | `[]` | ChatGPT/Codex pool account metadata managed by the Codex Auth dashboard. Secrets live separately in `codex-accounts.json`. |
 | `activeCodexAccountId?` | `string` | — | Pool account used for the next new Codex thread. Existing thread affinities keep their original account. |

docs-site/src/content/docs/ru/reference/cli.md

@@ -397,8 +397,12 @@ ocx service uninstall
 Оборачивает скриптовый лаунчер `codex` в PATH лёгким скриптом автозапуска. Настоящие цели
 `codex.exe` не затрагиваются, чтобы не ломать вызовы точного исполняемого файла.
 
-Если обновление Codex перезаписало обёртку, shim автоматически восстанавливается при следующем
-вызове `install` — новый бинарный файл резервируется, и записывается свежая обёртка.
+Если завершённое внешнее обновление Codex перезаписало установленный shim, следующая обычная команда
+`ocx` до запуска сохранит стабильный новый лончер в резервную копию и восстановит shim. Лончер,
+который ещё меняется, остаётся нетронутым до следующей попытки. Ошибка восстановления выдаёт
+предупреждение, но не приводит к сбою запрошенной команды; ручной вариант —
+`ocx codex-shim install`. Для отключения установите `codexShimAutoRestore` в `false` или задайте
+процессу `OPENCODEX_CODEX_SHIM_AUTO_RESTORE=0`.
 
 | Subcommand | Action |
 | --- | --- |