fix(codex): recover proven zero-byte coordinator remnants

docs-site/src/content/docs/guides/codex-integration.md

@@ -203,6 +203,33 @@ Routed catalog entries also get their GPT-5 identity rewritten to the real upstr
 Reasoning controls come from provider/model metadata across Codex's `low | medium | high | xhigh |
 max | ultra` ladder; unsupported values are mapped or clamped before the upstream request.
 
+### Coordinator diagnosis and recovery
+
+Native config/history writes use a per-user SQLite coordinator keyed by the canonical `CODEX_HOME`.
+If a process terminates in SQLite's initial creation window, a zero-byte coordinator can remain even
+though it contains no authoritative transition row. `ocx doctor` reports the exact coordinator path
+and distinguishes zero-byte, unversioned, rowless, valid, unsafe, and unreadable states without
+creating SQLite sidecars. Automatic sync tolerates only an identity-stable zero-byte file that has
+settled for at least one second and whose immutable SQLite snapshot has version zero with no tables;
+a newly created zero-byte file remains on the locked coordinator path.
+
+For a state that doctor proves is a zero-byte creation remnant, stop the OpenCodex proxy/service
+and run:
+
+```bash
+ocx doctor --recover-zero-byte-coordinator --yes
+ocx sync
+```
+
+Recovery moves the still-identical zero-byte file to a same-directory `.zero-byte-backup-*` path;
+it does not delete the evidence or adopt legacy routed state. It refuses a running proxy, lock
+contention, symlinks/reparse points, foreign ownership, changed files, every non-empty database,
+and any coordinator that already has an authoritative row. If the file is less than one second
+old, sync deliberately still treats it as coordinated; stop writers and use the explicit recovery,
+or wait one second before retrying `ocx sync`. Desktop renderer filtering is a
+separate layer: a correct catalog and coordinator do not by themselves bypass the Codex App model
+allowlist.
+
 ### Routed local tools
 
 Non-native routed catalog rows use `tool_mode: "code_mode_only"`. This lets Codex expose its official

docs-site/src/content/docs/ja/guides/codex-integration.md

@@ -134,6 +134,19 @@ Codex には、ディスク上のカタログ (デフォルトでは `$CODEX_HOM
 プロバイダーとモデルメタデータに応じて Codex の `low | medium | high | xhigh | max | ultra` 段階を使い、
 上流がサポートしない値はリクエスト送信前にマッピングまたはサポート範囲に下げます。
 
+### Coordinator の診断と回復
+
+ネイティブ構成/履歴の書き込みは、canonical `CODEX_HOME` をキーとするユーザー単位の SQLite coordinator を使います。プロセスが SQLite の初期作成中に終了すると、権威ある transition row が存在しなくてもゼロバイトの coordinator が残ることがあります。`ocx doctor` は SQLite sidecar を作らずに正確な coordinator パスを報告し、ゼロバイト、未バージョン、row なし、有効、安全でない、読み取り不能の状態を区別します。自動 sync が許容するのは、identity が安定して 1 秒以上経過し、immutable SQLite snapshot の version が 0 で table がないゼロバイトファイルだけです。新しく作成されたゼロバイトファイルはロックされた coordinator パスに残ります。
+
+doctor がゼロバイトの作成残骸だと証明した場合は、OpenCodex proxy/service を停止して実行します。
+
+```bash
+ocx doctor --recover-zero-byte-coordinator --yes
+ocx sync
+```
+
+回復は、同一性が保たれたゼロバイトファイルを同じディレクトリの `.zero-byte-backup-*` へ移動します。証拠を削除したり、既存の routed state を採用したりしません。実行中の proxy、lock 競合、symlink/reparse point、別所有者、変更済みファイル、空でない database、権威ある row を既に持つ coordinator は拒否します。ファイルが作成から 1 秒未満なら、sync は意図的に coordinator 扱いを続けます。writer を停止して明示的な回復を使うか、1 秒待ってから `ocx sync` を再実行してください。Desktop renderer のフィルタリングは別レイヤーであり、catalog と coordinator が正しいだけでは Codex App の model allowlist を回避できません。
+
 ### ルーティングされたローカルツール
 
 ネイティブではないルーティング済みカタログ項目は `tool_mode: "code_mode_only"` を使用します。これにより、

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

@@ -132,9 +132,20 @@ ocx status --json
 
 ### `ocx doctor`
 
-読み取り専用環境と接続の診断を実行します: 状態パスとファイル システム タイプ、WSL デュアル インストール、プロキシ環境/構成、ChatGPT の到達可能性、Codex プラグインとプロジェクト設定の警告、保留中の履歴の移行。 Codex のアプリとホームのターゲット設定セクションでは、Windows Orca ランタイムとホームの狭い不一致も検出し、該当する場合はサービスの移行について説明します。この診断によって表示されるパスでは、OS ユーザー名が編集されます。医師は修復ヒントを出力しますが、適用しません。
+読み取り専用の環境および接続診断を実行します。状態パスとファイルシステム種別、WSL の二重インストール、プロキシ環境/構成、ChatGPT 到達性、Codex プラグインとプロジェクト構成の警告、保留中の履歴移行が含まれます。Codex app-home の対象設定セクションは、限定された Windows Orca runtime-home の不一致も検出し、該当する場合はサービス移行を説明します。表示されるパスでは OS ユーザー名がマスクされます。既定のレポートは修復のヒントを表示しますが、適用しません。
 
-**OAuth の信頼性** セクションでは、資格情報ストレージが書き込み可能かどうか、リフレッシュ シングルフライト/ロック ファイルが `OPENCODEX_HOME` で作成できるかどうか、回復 `Action:` を持つ正常でない OAuth または Codex プール アカウント (編集された ID)、および Codex 転送パスが公式クライアント メタデータを作成しない静的 OK が報告されます。 Doctor は資格情報を変更したり、修復を適用したりすることはありません。
+**OAuth の信頼性** セクションは、資格情報ストレージが書き込み可能か、refresh single-flight/lock ファイルを `OPENCODEX_HOME` に作成できるか、正常でない OAuth または Codex pool アカウント（マスク済み ID）と回復用 `Action:`、そして Codex forward path が公式クライアント metadata を捏造しないことを示す静的 OK を報告します。Doctor は資格情報を変更しません。実際に修復を行うのは、以下の明示的なゼロバイト coordinator 回復だけです。
+
+既定のレポートは immutable な読み取り専用 SQLite 検査を使い、native-write coordinator の状態と正確なパスを表示します。ゼロバイト、空の未バージョン、row のない状態を catalog/app-server の健全性と区別するため、catalog の更新成功を Codex 構成注入の成功と取り違えません。
+
+OpenCodex proxy/service を停止した後、権威ある状態を含まないと証明された coordinator を明示的に保存して移動し、sync を再実行します。
+
+```bash
+ocx doctor --recover-zero-byte-coordinator --yes
+ocx sync
+```
+
+回復は、証明されたゼロバイトの残骸だけを受け入れます。空でない、有効、不明、変更済み、安全でない、または使用中のデータベースはすべて拒否し、削除せず同じディレクトリに `.zero-byte-backup-*` ファイルを作成します。作成から 1 秒未満のファイルは意図的に coordinator 扱いのままです。writer を停止して上記の明示的な回復を使うか、1 秒待ってから `ocx sync` を再実行してください。
 
 ## カタログの同期
 

docs-site/src/content/docs/ko/guides/codex-integration.md

@@ -124,6 +124,29 @@ Codex는 디스크의 카탈로그(`$CODEX_HOME/opencodex-catalog.json`이 기
 프로바이더와 모델 메타데이터에 따라 Codex의 `low | medium | high | xhigh | max | ultra` 단계를 사용하며,
 업스트림이 지원하지 않는 값은 요청을 보내기 전에 매핑하거나 지원 범위로 낮춥니다.
 
+### Coordinator 진단 및 복구
+
+네이티브 설정/기록 쓰기는 canonical `CODEX_HOME`을 키로 하는 사용자별 SQLite coordinator를 사용합니다.
+프로세스가 SQLite 초기 생성 구간에서 종료되면 권한 있는 transition row가 전혀 없는데도 제로 바이트
+coordinator가 남을 수 있습니다. `ocx doctor`는 SQLite sidecar를 만들지 않고 정확한 coordinator 경로를
+보고하며, 제로 바이트, 미버전, row 없는 상태, 유효, 안전하지 않음, 읽을 수 없음 상태를 구분합니다.
+자동 sync는 identity가 안정되고 최소 1초 동안 유지되었으며 immutable SQLite snapshot의 version이 0이고
+table이 없는 제로 바이트 파일만 허용합니다. 새로 생성된 제로 바이트 파일은 잠긴 coordinator 경로에 남습니다.
+
+doctor가 제로 바이트 생성 잔여물이라고 증명한 상태라면 OpenCodex proxy/service를 중지하고 실행하세요.
+
+```bash
+ocx doctor --recover-zero-byte-coordinator --yes
+ocx sync
+```
+
+복구는 동일한 제로 바이트 파일을 같은 디렉터리의 `.zero-byte-backup-*` 경로로 옮깁니다. 증거를 삭제하거나
+기존 routed 상태를 채택하지 않습니다. 실행 중인 proxy, lock 경합, symlink/reparse point, 다른 소유자,
+변경된 파일, 모든 비어 있지 않은 database, 이미 권한 있는 row가 있는 coordinator는 거절합니다. 파일이
+생성된 지 1초 미만이면 sync는 의도적으로 계속 coordinated 상태로 취급합니다. writer를 중지하고 명시적인
+복구를 사용하거나 1초를 기다린 다음 `ocx sync`를 다시 실행하세요. Desktop renderer 필터링은 별도 계층이므로,
+catalog와 coordinator가 올바르다는 사실만으로 Codex App model allowlist를 우회하지는 않습니다.
+
 ### 라우팅된 로컬 도구
 
 네이티브가 아닌 라우팅 catalog 항목은 `tool_mode: "code_mode_only"`를 사용합니다. 이를 통해 Codex는 공식

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

@@ -166,12 +166,30 @@ probe이며, `--wait`는 준비 또는 timeout까지 polling하지만 종단 `fa
 환경/설정, ChatGPT 도달 가능성, Codex 플러그인 및 프로젝트 설정 경고, 보류 중인 기록 마이그레이션이
 포함됩니다. Codex 앱 홈 대상 지정 섹션은 좁은 범위의 Windows Orca 런타임 홈 불일치도 감지하고,
 해당할 때 서비스 마이그레이션을 설명합니다. 이 진단에 표시되는 경로는 OS 사용자 이름을 마스킹합니다.
-doctor는 복구 힌트를 보여 주지만 직접 적용하지는 않습니다.
+기본 보고서는 복구 힌트를 보여 주지만 직접 적용하지는 않습니다.
 
 **OAuth 안정성** 섹션은 자격 증명 저장소에 쓰기 가능한지, `OPENCODEX_HOME` 아래에 refresh
 single-flight/lock 파일을 만들 수 있는지, 건강하지 않은 OAuth 또는 Codex pool 계정(마스킹된 ID)과
 복구용 `Action:`, 그리고 Codex 전달 경로가 공식 클라이언트 메타데이터를 꾸며 내지 않는다는
-정적 OK를 보고합니다. doctor는 자격 증명을 변경하거나 복구를 적용하지 않습니다.
+정적 OK를 보고합니다. doctor는 자격 증명을 변경하지 않으며, 아래의 명시적인 제로 바이트
+coordinator 복구만 실제 복구 작업을 수행합니다.
+
+기본 보고서는 immutable 읽기 전용 SQLite 검사로 네이티브 쓰기 coordinator의 상태와 정확한 경로를
+보여 줍니다. 제로 바이트, 비어 있는 미버전, row 없는 상태를 catalog/app-server 상태와 구분하므로,
+catalog 갱신 성공을 Codex 설정 주입 성공으로 오해하지 않게 합니다.
+
+OpenCodex proxy/service를 중지한 뒤, 권한 있는 상태가 아님이 증명된 coordinator를 명시적으로 보존하여
+옮기고 sync를 다시 실행합니다.
+
+```bash
+ocx doctor --recover-zero-byte-coordinator --yes
+ocx sync
+```
+
+복구는 증명된 제로 바이트 잔여 파일만 허용합니다. 비어 있지 않거나 유효하거나 알 수 없거나 변경되었거나
+안전하지 않거나 사용 중인 데이터베이스는 모두 거절하고, 삭제하지 않고 같은 디렉터리에
+`.zero-byte-backup-*` 파일을 만듭니다. 생성된 지 1초 미만인 파일은 의도적으로 coordinator 상태를 유지합니다.
+writer를 중지한 뒤 위의 명시적 복구를 사용하거나 1초를 기다린 다음 `ocx sync`를 다시 실행하세요.
 
 ## 카탈로그 동기화
 

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

@@ -166,12 +166,31 @@ Run read-only environment and connectivity diagnostics: state paths and filesyst
 installs, proxy environment/config, ChatGPT reachability, Codex plugin and project-config warnings,
 and pending history migration. The Codex app-home targeting section also detects the narrow Windows
 Orca runtime-home mismatch and explains service migration when applicable. Paths shown by this
-diagnostic redact the OS username. Doctor prints repair hints but does not apply them.
+diagnostic redact the OS username. The default report prints repair hints but does not apply them.
 
 The **OAuth reliability** section reports whether credential storage is writable, whether refresh
 single-flight/lock files can be created under `OPENCODEX_HOME`, non-healthy OAuth or Codex pool
 accounts (redacted ids) with a recovery `Action:`, and a static OK that the Codex forward path does
-not fabricate official-client metadata. Doctor never mutates credentials or applies repairs.
+not fabricate official-client metadata. Doctor never mutates credentials; only the explicit
+zero-byte coordinator recovery below applies a repair.
+
+The default report includes the native-write coordinator state and exact path using immutable
+read-only SQLite inspection. Zero-byte, empty-unversioned, and rowless states are shown separately
+from catalog/app-server health, so a successful catalog refresh is not mistaken for successful
+Codex config injection.
+
+After stopping the OpenCodex proxy/service, explicitly preserve and move a proven non-authoritative
+coordinator, then retry sync:
+
+```bash
+ocx doctor --recover-zero-byte-coordinator --yes
+ocx sync
+```
+
+The recovery accepts only a proven zero-byte remnant. It refuses every non-empty, valid, unknown,
+changed, unsafe, or busy database and creates a same-directory `.zero-byte-backup-*` file instead
+of deleting anything. A file younger than one second intentionally remains coordinated; after
+stopping writers, use the explicit recovery above or wait one second before retrying `ocx sync`.
 
 ## Catalog sync
 

docs-site/src/content/docs/ru/guides/codex-integration.md

@@ -204,6 +204,32 @@ Codex показывает модели из каталога на диске (`
 по шкале Codex `low | medium | high | xhigh | max | ultra`; неподдерживаемые значения
 сопоставляются или ограничиваются перед запросом к вышестоящему провайдеру.
 
+### Диагностика и восстановление coordinator
+
+Запись нативной конфигурации и истории использует отдельный для пользователя SQLite coordinator,
+ключом которого служит canonical `CODEX_HOME`. Если процесс завершится в начальном окне создания
+SQLite, может остаться zero-byte coordinator без авторитетной transition row. `ocx doctor`
+сообщает точный путь coordinator и различает состояния zero-byte, unversioned, без строк, valid,
+unsafe и unreadable, не создавая SQLite sidecar-файлы. Автоматический sync допускает только
+стабильный по identity zero-byte файл возрастом не менее секунды, чей immutable SQLite snapshot
+имеет version 0 и не содержит таблиц; только что созданный zero-byte файл остаётся на заблокированном
+пути coordinator.
+
+Если doctor доказал, что это zero-byte остаток создания, остановите proxy/service OpenCodex и выполните:
+
+```bash
+ocx doctor --recover-zero-byte-coordinator --yes
+ocx sync
+```
+
+Восстановление перемещает всё ещё идентичный zero-byte файл в `.zero-byte-backup-*` в том же каталоге;
+оно не удаляет свидетельство и не принимает legacy routed state. Оно отклоняет работающий proxy,
+конфликт блокировки, symlink/reparse point, чужого владельца, изменившийся файл, любую непустую базу и
+coordinator с авторитетной row. Если файл моложе секунды, sync намеренно продолжает считать его
+coordinated; остановите writer'ы и используйте явное восстановление либо подождите секунду перед
+повторным `ocx sync`. Фильтрация Desktop renderer — отдельный слой: корректные catalog и coordinator
+сами по себе не обходят allowlist моделей Codex App.
+
 ### Локальные инструменты для маршрутизируемых моделей
 
 Маршрутизируемые записи, которые не являются нативными, используют