fix(lifecycle): consolidate identity-bound restart and service install cleanup

docs-site/src/content/docs/guides/grok-build.md

@@ -127,11 +127,12 @@ the id `grok-4.5`. Generated aliases avoid dots entirely for this reason.
   rejects unknown event types, so a manually configured `api_backend = "responses"` model
   can fail mid-turn on slow upstreams. The auto-registered entries pin
   `api_backend = "chat_completions"`, which never surfaces raw heartbeat frames.
-- **Service-installed `ocx restart`:** when opencodex runs under a service manager,
-  `ocx restart` currently stops the service and replaces it with an unmanaged process —
-  service persistence (auto-restart, start-at-login) is lost until the next
-  `ocx service` setup, and if that unmanaged process dies the managed block can point at
-  a dead proxy until the next `ocx start`/`ocx ensure` refreshes it.
+- **Service-installed `ocx restart`:** the running proxy owns restart authorization and drain
+  coordination, while the installed service manager launches the replacement after the old process
+  exits. Service supervision remains installed. On loopback auto-registration, the managed block
+  also remains in place across the handoff; non-loopback deployments use manually managed Grok
+  configuration instead. The command succeeds only after a different, identity-verified process is
+  healthy on the same port.
 - **Config read timing:** start opencodex first, then launch `grok` for the most
   predictable results. Grok Build watches `~/.grok/config.toml` and reloads when the
   `[model]` table actually changes (roughly a one-second debounce, compared by content), so

docs-site/src/content/docs/ja/guides/grok-build.md

@@ -78,8 +78,7 @@ api_key = "your-OPENCODEX_API_AUTH_TOKEN"
 
 - **バックエンドとキープアライブの応答:** opencodex は `response.heartbeat` キープアライブを発行します
 アップストリーム沈黙中の `/v1/responses` ストリーム。 Grok Build の Responses デコーダは未知のイベント タイプを拒否するため、手動で構成された `api_backend = "responses"` モデルは低速なアップストリームではターン中に失敗する可能性があります。自動登録されたエントリは `api_backend = "chat_completions"` をピン留めしますが、生のハートビート フレームが表示されることはありません。
-- **サービスでインストールされた `ocx restart`:** opencodex がサービス マネージャーの下で実行される場合、
-現在、`ocx restart` はサービスを停止し、アンマネージド プロセスに置き換えます。サービスの永続性 (自動再起動、ログイン時開始) は、次の `ocx service` セットアップまで失われます。また、そのアンマネージド プロセスが終了した場合、次の `ocx start`/`ocx ensure` が更新するまで、マネージド ブロックは無効なプロキシを指す可能性があります。
+- **サービスでインストールされた `ocx restart`:** 実行中のプロキシが再起動の認可とドレインの調整を担当し、古いプロセスの終了後はインストール済みのサービス マネージャーが置換プロセスを起動します。サービス監視は維持されます。ループバックの自動登録を使用している場合に限り、マネージド ブロックもハンドオフ中に維持されます。非ループバック構成では Grok 設定を手動管理します。同じポートで、別の ID 検証済みプロセスが正常になったことを確認した場合にのみ成功します。
 - **構成読み取りタイミング:** 最初に opencodex を起動し、その後 `grok` を起動します。
 予測可能な結果。 Grok Build は `~/.grok/config.toml` を監視し、`[model]` テーブルが実際に変更されると (内容で比較すると約 1 秒のデバウンス) 再ロードするため、更新されたブロックは再起動せずに開いているセッションに到達します。 Grok が解析した内容を確認するには、`grok inspect` を実行します。ロードされた設定ソースがリストされ、拒否されたフィールドについて警告が表示されます。解決されたモデルのリストは出力されません。単一の TOML エラーがユーザー設定レイヤー「全体」を無効にすることに注意してください。これが、opencodex がファイルをアトミックに書き込む理由です。Grok は書きかけの設定を決して認識しません。
 - **カタログの更新:** フェンスで囲まれたブロックには、射出時のカタログが反映されます。後

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

@@ -28,7 +28,9 @@ ocx start --port 8080
 
 ### `ocx restart`
 
-`stop` に続いて `ensure` を実行します。プロキシ/サービスを停止し、ネイティブ Codex を復元し、バックグラウンドでプロキシを起動し、ライブ ポートを Codex に同期します。
+プロキシが実行中の場合、検証済みの正確な PID とポートに対して in-place 再起動を要求し、通常のドレインを待ってから、同じポートに別のランタイム PID が起動したことを確認します。管理対象ルーティングとサービス監視は維持され、不確実な要求を別の stop/start として再実行しません。実行中のプロキシがない場合に限り、通常の `ensure` 起動にフォールバックします。
+
+稼働中のリスナーをランタイム PID に結び付けて検証できない場合（更新前のプロキシを含む）、`ensure` や stop/start へのフォールバックは行わず安全側で失敗します。所有権を確認してから `ocx stop`、`ocx start` の順に一度実行してください。
 
 ### `ocx ensure`
 

docs-site/src/content/docs/ja/troubleshooting/windows-memory.md

@@ -26,7 +26,7 @@ Windows では、#32111 クラッシュを回避するために、opencodex は
 - **`ocx doctor`** — 「メモリ / ランタイム」セクションには *サービス* が表示されます
 プロセスの Bun バージョン、RSS、外部/ArrayBuffers カウンター、JS ヒープ コンテキスト、およびストリーム モードの決定。バンドルされている Bun 1.3.14 ランタイムでは、`heapUsed` / `jscHeap` 単独ではリーク識別子ではありません。アプリレベルのリークを割り当てる前に、観察されたメモリを `responseState` および繰り返しサンプルと比較します。
 - **`GET /api/system/memory`** — 認証済みの同じデータ
-ダッシュボードまたはスクリプトの管理 API。 RSS/ヒープ/外部カウンターとともに、プロキシのメモリ内 `previous_response_id` 継続ストアのスカラー `responseState` ブロック (エントリ数、シリアル化された合計/最大バイト数、最も古いエントリの経過時間) を報告します。これはさらに成長に起因します。観察された記憶の上昇下での `responseState.totalBytes` の上昇は会話の保持を指します (長い `store:false` チェーンはターンごとに再拡張します)。一方、観察された記憶の上昇の下での横ばいの `responseState` はそのストアから遠ざかることを示します。値はスカラーのみであり、リクエスト本文、トークン、パス、アカウント識別子はありません。また、読み取りには副作用はありません (プルーニングや削除は行われません)。ダッシュボードの **メモリ可観測性** カードは同じフィールドをレンダリングし、確認ゲート付き **ドレインと再起動** アクションを提供します。現在のアクティブ ターン数を表示し、アクティブ ターンを最大 60 秒待機し (既存の 503 + `Retry-After` ドレインを再利用)、残りのターンを中止し、ライブ ポート (または障害専用サービス スーパーバイザ) 上の `ocx start` 経由でプロキシを再起動します。 respawn）Codex インジェクションを破棄せずに。これは、`POST /api/stop` の短いドレインよりも長く、情報に基づいたリサイクルです。
+ダッシュボードまたはスクリプトの管理 API。 RSS/ヒープ/外部カウンターとともに、プロキシのメモリ内 `previous_response_id` 継続ストアのスカラー `responseState` ブロック (エントリ数、シリアル化された合計/最大バイト数、最も古いエントリの経過時間) を報告します。これはさらに成長に起因します。観察された記憶の上昇下での `responseState.totalBytes` の上昇は会話の保持を指します (長い `store:false` チェーンはターンごとに再拡張します)。一方、観察された記憶の上昇の下での横ばいの `responseState` はそのストアから遠ざかることを示します。値はスカラーのみであり、リクエスト本文、トークン、パス、アカウント識別子はありません。また、読み取りには副作用はありません (プルーニングや削除は行われません)。ダッシュボードの **メモリ可観測性** カードは同じフィールドをレンダリングし、確認ゲート付き **ドレインと再起動** アクションを提供します。現在のアクティブ ターン数を表示し、アクティブ ターンを最大 60 秒待機し (既存の 503 + `Retry-After` ドレインを再利用)、残りのターンを中止します。実行中のプロキシは再起動の認可とドレイン調整を担当して終了し、サービス管理下ではインストール済みサービス マネージャーが置換プロセスを起動します。同じポートで、別の ID 検証済みプロセスが正常であることを確認した場合にのみ成功し、Codex インジェクションは破棄しません。これは、`POST /api/stop` の短いドレインよりも長く、情報に基づいたリサイクルです。
 - **ゲートされた代替ストリーム パス** — 制限された単一リーダー リレー。
 境界のないバッファリング形状を完全に削除します。 Windows では、バンドルされた Bun リリースに #32111 修正が確実に適用されると、これが自動的にデフォルトになります。現在はオプトインのみとなっています (以下を参照)。 macOS では、そのようなリリース後でもオプトインのままになります。macOS `auto` を切り替えるかどうかは別の決定となります。
 

docs-site/src/content/docs/ko/guides/grok-build.md

@@ -73,6 +73,6 @@ api_key = "your-OPENCODEX_API_AUTH_TOKEN"
 ## 알려진 제한
 
 - **Responses 백엔드와 keep-alive:** 상위 업스트림이 조용한 동안 opencodex는 `/v1/responses` 스트림에 `response.heartbeat` keep-alive를 보냅니다. Grok Build의 Responses 디코더는 알 수 없는 이벤트 타입을 거부하므로, 수동으로 설정한 `api_backend = "responses"` 모델은 느린 업스트림에서 턴 도중 실패할 수 있습니다. 자동 등록된 항목은 `api_backend = "chat_completions"`로 고정되며, 원시 heartbeat 프레임을 노출하지 않습니다.
-- **서비스 설치된 `ocx restart`:** opencodex가 서비스 관리자 아래에서 실행될 때 `ocx restart`는 현재 서비스를 멈추고 unmanaged 프로세스로 바꿉니다. 서비스 지속성(auto-restart, start-at-login)은 다음 `ocx service` 설정 전까지 사라지며, 그 unmanaged 프로세스가 죽으면 다음 `ocx start`/`ocx ensure`가 갱신하기 전까지 관리 블록이 죽은 프록시를 가리킬 수 있습니다.
+- **서비스 설치된 `ocx restart`:** 실행 중인 프록시는 재시작 권한 확인과 드레인 조정을 담당하고, 기존 프로세스가 종료된 뒤 설치된 서비스 관리자가 교체 프로세스를 시작합니다. 서비스 감독은 그대로 유지됩니다. 루프백 자동 등록을 사용하는 경우에만 관리 블록도 핸드오프 동안 유지되며, 비루프백 배포에서는 Grok 설정을 수동으로 관리합니다. 같은 포트에서 신원이 확인된 다른 프로세스가 정상 상태가 된 뒤에만 명령이 성공합니다.
 - **설정 읽기 시점:** 가장 예측 가능한 결과를 얻으려면 opencodex를 먼저 시작하고 그다음 `grok`를 실행합니다. Grok Build는 `~/.grok/config.toml`을 감시하다가 `[model]` 테이블이 실제로 바뀔 때 다시 불러옵니다(내용을 기준으로 비교하는 약 1초 디바운스). 그래서 새로 고친 블록은 재시작 없이 열린 세션에도 들어갑니다. Grok가 무엇을 파싱했는지 확인하려면 `grok inspect`를 실행합니다. 이 명령은 로드한 설정 원본을 나열하고 거부한 필드가 있으면 경고합니다. 해석된 모델 목록은 출력하지 않습니다. TOML 오류 하나만으로도 사용자 설정 레이어 전체가 무효가 되므로, opencodex가 파일을 원자적으로 쓰는 이유도 여기에 있습니다. Grok는 절반만 써진 설정을 보지 않습니다.
 - **카탈로그 업데이트:** 펜스 블록은 주입 시점의 카탈로그를 반영합니다. 공급자나 모델을 추가한 뒤에는 `ocx ensure`를 실행하거나 프록시를 재시작해 갱신합니다.

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

@@ -36,8 +36,13 @@ ocx start --port 8080
 
 ### `ocx restart`
 
-`stop` 다음에 `ensure`를 실행합니다. 즉, 프록시/서비스를 중지하고 기본 Codex를 복원한 뒤,
-프록시를 백그라운드에서 다시 시작하고 살아 있는 포트를 Codex에 다시 동기화합니다.
+프록시가 실행 중이면 확인된 정확한 PID와 포트에 in-place 재시작을 요청하고, 정상 드레인을
+기다린 뒤 같은 포트에 다른 런타임 PID가 올라왔는지 확인합니다. 이 과정에서 관리형 라우팅과
+서비스 감시는 유지되며, 요청 결과가 불확실해도 별도의 stop/start로 재실행하지 않습니다.
+실행 중인 프록시가 없을 때만 일반 `ensure` 시작 동작으로 전환합니다.
+실행 중인 리스너를 런타임 PID로 증명할 수 없으면(업데이트 전 프록시 포함) `ensure`나
+stop/start 대체 동작 없이 안전하게 실패합니다. 소유권을 확인한 뒤 `ocx stop`과 `ocx start`를
+순서대로 한 번 실행하세요.
 
 ### `ocx ensure`
 

docs-site/src/content/docs/ko/troubleshooting/windows-memory.md

@@ -23,7 +23,7 @@ Windows에서는 opencodex가 #32111 충돌을 피하기 위해 스트리밍 응
 
 - **메모리 감시기** - 프록시는 1분마다 자체 메모리를 샘플링하고, 관측된 메모리가 4 GiB를 넘으면 속도 제한이 걸린 경고를 기록합니다. 관측된 메모리는 RSS, `external`, `arrayBuffers`의 합이 아니라 그중 가장 큰 값입니다. Windows의 working-set/RSS 카운터가 커밋된 external 잔존량을 낮게 잡을 수 있기 때문입니다.
 - **`ocx doctor`** - "Memory / runtime" 섹션에서 *서비스* 프로세스의 Bun 버전, RSS, external/ArrayBuffers 카운터, JS 힙 문맥, 스트림 모드 결정을 보여줍니다. 번들된 Bun 1.3.14 런타임에서는 `heapUsed` / `jscHeap`만으로 누수를 판별할 수 없습니다. 애플리케이션 수준 누수로 단정하기 전에 관측된 메모리, `responseState`, 반복 샘플을 함께 보아야 합니다.
-- **`GET /api/system/memory`** - 대시보드나 스크립트에서 쓸 수 있도록 같은 데이터를 인증된 관리 API로 제공합니다. RSS/heap/external 카운터와 함께, 프록시의 메모리 내 `previous_response_id` 이어받기 저장소에 대한 스칼라 `responseState` 블록(항목 수, 직렬화된 총/최대 바이트, 가장 오래된 항목의 경과 시간)을 보고합니다. 이를 통해 증가 원인을 더 잘 구분할 수 있습니다. 관측된 메모리가 함께 증가하면서 `responseState.totalBytes`도 늘면 대화 보존(long `store:false` 체인이 매 턴 다시 확장되는 경우)을 가리키고, 관측된 메모리는 늘지만 `responseState`는 평평하면 그 저장소와는 무관한 원인을 가리킵니다. 값은 스칼라만 포함하며 요청 본문, 토큰, 경로, 계정 식별자는 포함하지 않습니다. 또한 읽기 동작은 부작용이 없습니다. 절대 prune하거나 evict하지 않습니다. 대시보드의 **Memory observability** 카드는 같은 필드를 렌더링하고, 확인을 거쳐야 하는 **Drain & restart** 동작도 제공합니다. 현재 활성 턴 수를 보여주고, 기존 503 + `Retry-After` 드레인과 같은 방식으로 최대 60초 동안 활성 턴을 기다린 뒤, 남아 있는 턴을 강제로 중단하고 Codex 주입을 해제하지 않은 채 라이브 포트의 `ocx start`(또는 실패했을 때만 동작하는 서비스 슈퍼바이저 재기동)를 통해 프록시를 재시작합니다. 이는 `POST /api/stop`의 짧은 드레인보다 더 길고, 더 많은 정보를 반영한 재순환입니다.
+- **`GET /api/system/memory`** - 대시보드나 스크립트에서 쓸 수 있도록 같은 데이터를 인증된 관리 API로 제공합니다. RSS/heap/external 카운터와 함께, 프록시의 메모리 내 `previous_response_id` 이어받기 저장소에 대한 스칼라 `responseState` 블록(항목 수, 직렬화된 총/최대 바이트, 가장 오래된 항목의 경과 시간)을 보고합니다. 이를 통해 증가 원인을 더 잘 구분할 수 있습니다. 관측된 메모리가 함께 증가하면서 `responseState.totalBytes`도 늘면 대화 보존(long `store:false` 체인이 매 턴 다시 확장되는 경우)을 가리키고, 관측된 메모리는 늘지만 `responseState`는 평평하면 그 저장소와는 무관한 원인을 가리킵니다. 값은 스칼라만 포함하며 요청 본문, 토큰, 경로, 계정 식별자는 포함하지 않습니다. 또한 읽기 동작은 부작용이 없습니다. 절대 prune하거나 evict하지 않습니다. 대시보드의 **Memory observability** 카드는 같은 필드를 렌더링하고, 확인을 거쳐야 하는 **Drain & restart** 동작도 제공합니다. 현재 활성 턴 수를 보여주고, 기존 503 + `Retry-After` 드레인과 같은 방식으로 최대 60초 동안 활성 턴을 기다린 뒤, 남아 있는 턴을 강제로 중단하고 Codex 주입을 해제하지 않은 채 확인된 실행 프로세스가 스스로 교체되게 한 다음 같은 포트의 다른 PID를 검증합니다. 이는 `POST /api/stop`의 짧은 드레인보다 더 길고, 더 많은 정보를 반영한 재순환입니다.
 - **가드된 대체 스트림 경로** - unbounded buffering 형태를 완전히 제거하는 bounded single-reader relay입니다. Windows에서는 번들된 Bun 릴리스가 #32111 수정을 실제로 포함하고 있음이 확인되면 자동으로 기본값이 됩니다. 지금은 아래에서 설명하는 opt-in만 가능합니다. macOS에서는 그런 릴리스 이후에도 계속 opt-in입니다. macOS의 `auto`를 바꾸는 것은 별도의 결정입니다.
 
 이 변경들로 실제 RSS가 얼마나 좋아지는지는 **Windows 사용자의 검증을 기다리고 있습니다**. 아직 이 누수가 해결되었다고 말하지는 않습니다.

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

@@ -36,8 +36,14 @@ The same action is available from the web dashboard's **Stop** button (`POST /ap
 
 ### `ocx restart`
 
-Run `stop` followed by `ensure`: stop the proxy/service, restore native Codex, start the proxy in the
-background, and sync the live port back into Codex.
+When a proxy is running, ask that exact attested PID and port to restart in place, wait for its
+normal drain, and verify a different runtime PID on the same port. Managed routing and service
+supervision stay installed throughout; an uncertain request is observed rather than replayed as a
+separate stop/start. If no proxy is running, the command falls back to the normal `ensure` start.
+If a live listener cannot be attested to a runtime PID (including a pre-update proxy), restart fails
+closed without an `ensure` or stop/start fallback. After confirming ownership, use `ocx stop` then
+`ocx start` for a standalone proxy. For a service-managed proxy, use `ocx stop` followed by
+`ocx service start` so supervision is restored.
 
 ### `ocx ensure`