fix(service): complete the repair migration — docs, startup health, doctor, and update advice

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

@@ -135,14 +135,15 @@ Codex のローカル モデル ピッカー キャッシュを無効にし、
 
 ## バックグラウンドサービス
 
-### `ocx service [install|start|stop|status|uninstall|remove]`
+### `ocx service [install|repair|start|stop|status|uninstall|remove]`
 
 opencodex を、ログイン時に自動起動し、クラッシュ時に自動再起動するログイン管理バックグラウンド サービス (macOS **launchd**、Linux **systemd ユーザー ユニット**、Windows **タスク スケジューラ**) として実行します。サービスは `OCX_SERVICE=1` を設定して実行されるため、再起動によって Codex 設定が変更されることはありません。
 
 |サブコマンド |アクション |
 | --- | --- |
 |なし |サービスを作成/更新して開始します。 |
 | `install` |サービスを作成して開始します。 |
+| `repair` | 既存のサービスを再登録せずに更新して再起動します。 |
 | `start` |インストールされているサービスを開始します。 |
 | `stop` |サービスを停止し、ネイティブ Codex を復元します。 |
 | `status` |サービスとプロキシの診断とログ パスをレポートします。 |
@@ -152,6 +153,7 @@ opencodex を、ログイン時に自動起動し、クラッシュ時に自動
 ```bash
 ocx service
 ocx service install
+ocx service repair
 ocx service status
 ocx service uninstall
 ```

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

@@ -40,7 +40,7 @@ Windows では、#32111 クラッシュを回避するために、opencodex は
 修正が適用され、opencodex はバンドルされたランタイムを強化し、より安全なストリーム パスが Windows 上で自動的にオンになります (macOS では引き続き以下の明示的なオプトインが必要です)。
 
 2. **`OPENCODEX_BUN_PATH` を使用して信頼できる Bun ランタイムを実行します。** これは
-未検証の領域 — 私たちがテストしていないランタイムで opencodex を実行しています。自己責任で。サービスのインストールにとって重要: オーバーライドは、サービスの開始時ではなく、**サービス アーティファクトの生成時に**読み込まれます。環境変数を設定し、同じシェルから `ocx service install` を再実行すると、パスが永続サービス定義に組み込まれます。 env を設定するだけでは、すでにインストールされているサービスには何も影響しません。
+未検証の領域 — 私たちがテストしていないランタイムで opencodex を実行しています。自己責任で。サービスのインストールにとって重要: オーバーライドは、サービスの開始時ではなく、**サービス アーティファクトの生成時に**読み込まれます。環境変数を設定し、同じシェルから `ocx service repair` を再実行すると、パスが永続サービス定義に組み込まれます。 env を設定するだけでは、すでにインストールされているサービスには何も影響しません。
 
 3. **`streamMode: "eager-relay"` を使用して有界リレーにオプトインします。** 2 つの方法:
 `config.json` を編集する (`"streamMode": "eager-relay"` を追加する) か、管理 API を呼び出します。`PUT /api/settings` と `{"streamMode":"eager-relay"}` は、再起動せずに新しいターンに適用されます。 **クラッシュのリスク警告:** Bun 1.3.14 では、#32111 の影響を受けるストリーム形状が使用されており、ストリームの途中でプロセスがクラッシュする可能性があります (Windows に限らず、どの OS でも)。サービス マネージャーはサービスを再起動しますが、実行中のリクエストは失敗します。 `"legacy-tee"` は現在のデフォルトを固定します。 Windows では、`"auto"` (デフォルト) によりランタイム ゲートが決定します。 macOS では、`"auto"` は常に T 上にあります。明示的な `"eager-relay"` はオプトインです。

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

@@ -176,7 +176,7 @@ Codex의 로컬 모델 선택기 캐시를 무효화하여, 활성 opencodex 카
 
 ## 백그라운드 서비스
 
-### `ocx service [install|start|stop|status|uninstall|remove]`
+### `ocx service [install|repair|start|stop|status|uninstall|remove]`
 
 로그인 관리형 백그라운드 서비스로 opencodex를 실행합니다(macOS **launchd**, Linux **systemd** 사용자
 유닛, Windows **Task Scheduler**). 로그인 시 자동 시작하고 충돌 시 자동 재시작합니다. 서비스 실행은
@@ -186,6 +186,7 @@ Codex의 로컬 모델 선택기 캐시를 무효화하여, 활성 opencodex 카
 | --- | --- |
 | 없음 | 서비스를 생성/업데이트하고 시작합니다. |
 | `install` | 서비스를 생성하고 시작합니다. |
+| `repair` | 설치된 서비스를 다시 등록하지 않고 제자리에서 새로 고친 뒤 재시작합니다. |
 | `start` | 설치된 서비스를 시작합니다. |
 | `stop` | 서비스를 중지하고 기본 Codex를 복원합니다. |
 | `status` | 서비스와 프록시 진단, 로그 경로를 보고합니다. |
@@ -195,6 +196,7 @@ Codex의 로컬 모델 선택기 캐시를 무효화하여, 활성 opencodex 카
 ```bash
 ocx service
 ocx service install
+ocx service repair
 ocx service status
 ocx service uninstall
 ```

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

@@ -34,7 +34,7 @@ Windows에서는 opencodex가 #32111 충돌을 피하기 위해 스트리밍 응
 
 1. **번들된 런타임 업데이트를 기다립니다.** Bun 릴리스가 수정 사항을 실제로 포함함이 확인되면 opencodex가 번들 런타임을 올리고, Windows에서는 더 안전한 스트림 경로가 자동으로 켜집니다(macOS는 아래의 명시적 opt-in을 계속 요구합니다).
 
-2. **`OPENCODEX_BUN_PATH`로 신뢰하는 Bun 런타임을 사용합니다.** 이 경로는 검증되지 않은 영역입니다. opencodex를 아직 테스트하지 않은 런타임에서 실행하는 것이므로, 위험은 사용자에게 있습니다. 서비스 설치에서 특히 중요한 점은 이 override가 서비스 시작 시가 아니라 **서비스 아티팩트를 생성할 때** 읽힌다는 것입니다. 환경 변수를 설정한 뒤, 같은 셸에서 `ocx service install`을 다시 실행해야 경로가 영구적인 서비스 정의에 반영됩니다. 환경 변수만 설정하면 이미 설치된 서비스에는 아무 영향이 없습니다.
+2. **`OPENCODEX_BUN_PATH`로 신뢰하는 Bun 런타임을 사용합니다.** 이 경로는 검증되지 않은 영역입니다. opencodex를 아직 테스트하지 않은 런타임에서 실행하는 것이므로, 위험은 사용자에게 있습니다. 서비스 설치에서 특히 중요한 점은 이 override가 서비스 시작 시가 아니라 **서비스 아티팩트를 생성할 때** 읽힌다는 것입니다. 환경 변수를 설정한 뒤, 같은 셸에서 `ocx service repair`를 다시 실행해야 경로가 영구적인 서비스 정의에 반영됩니다. 환경 변수만 설정하면 이미 설치된 서비스에는 아무 영향이 없습니다.
 
 3. **`streamMode: "eager-relay"`로 bounded relay를 opt-in합니다.** 방법은 두 가지입니다. `config.json`을 수정해 `"streamMode": "eager-relay"`를 추가하거나, 관리 API에 `PUT /api/settings`와 `{"streamMode":"eager-relay"}`를 보내 새 턴에 재시작 없이 적용합니다. **충돌 위험 경고:** Bun 1.3.14에서는 이 방식이 #32111의 영향을 받는 스트림 형태를 사용하므로, 어떤 OS에서든 스트림 중간에 프로세스가 충돌할 수 있습니다. 서비스 관리자가 다시 시작하겠지만, 진행 중이던 요청은 실패합니다. `"legacy-tee"`는 현재 기본값을 고정합니다. Windows에서는 `"auto"`(기본값)가 런타임 게이트 판단을 따르게 합니다. macOS에서는 `"auto"`가 항상 tee를 유지하고, 명시적 `"eager-relay"`만 opt-in입니다.
 

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

@@ -175,7 +175,7 @@ same stale-`app-server` warning and optional `--restart-codex` behavior as `ocx
 
 ## Background service
 
-### `ocx service [install|start|stop|status|uninstall|remove]`
+### `ocx service [install|repair|start|stop|status|uninstall|remove]`
 
 Run opencodex as a login-managed background service (macOS **launchd**, Linux **systemd user unit**,
 Windows **Task Scheduler**) that auto-starts on login and auto-restarts on crash. Service runs set
@@ -184,7 +184,8 @@ Windows **Task Scheduler**) that auto-starts on login and auto-restarts on crash
 | Subcommand | Action |
 | --- | --- |
 | none | Create/update and start the service. |
-| `install` | Create and start the service. |
+| `install` | Create and start the service. Registers it, which on Windows needs elevation. |
+| `repair` | Refresh an installed service in place and restart it, without re-registering it. |
 | `start` | Start an installed service. |
 | `stop` | Stop the service and restore native Codex. |
 | `status` | Report service and proxy diagnostics plus log paths. |
@@ -194,6 +195,7 @@ Windows **Task Scheduler**) that auto-starts on login and auto-restarts on crash
 ```bash
 ocx service
 ocx service install
+ocx service repair
 ocx service status
 ocx service uninstall
 ```
@@ -230,9 +232,9 @@ log named in the message, and use `ocx start` to serve in the foreground meanwhi
 ⚠️  installed and loaded (launchd; logs: …)
    Registered, but no proxy is answering on port 10100.
    launchd is running an OLDER plist than the one on disk.
-   Fix:    launchctl bootout gui/$(id -u)/com.opencodex.proxy && ocx service install
+   Fix:    launchctl bootout gui/$(id -u)/com.opencodex.proxy && ocx service repair
    Log:    ~/.opencodex/service.log
-   Repair: ocx service install
+   Repair: ocx service repair
    Meanwhile: ocx start           (serves in the foreground)
 ```
 

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

@@ -191,7 +191,7 @@ opencodex. Предупреждение о stale-`app-server` и optional `--res
 
 ## Фоновая служба
 
-### `ocx service [install|start|stop|status|uninstall|remove]`
+### `ocx service [install|repair|start|stop|status|uninstall|remove]`
 
 Запустить opencodex как login-managed background service (macOS **launchd**, Linux **systemd user
 unit**, Windows **Task Scheduler**), которая автоматически стартует при логине и сама
@@ -202,6 +202,7 @@ unit**, Windows **Task Scheduler**), которая автоматически 
 | --- | --- |
 | none | Создать/обновить и запустить службу. |
 | `install` | Создать и запустить службу. |
+| `repair` | Обновить установленную службу на месте и перезапустить её без повторной регистрации. |
 | `start` | Запустить уже установленную службу. |
 | `stop` | Остановить службу и восстановить native Codex. |
 | `status` | Показать диагностику службы и прокси, а также пути к логам. |
@@ -211,6 +212,7 @@ unit**, Windows **Task Scheduler**), которая автоматически 
 ```bash
 ocx service
 ocx service install
+ocx service repair
 ocx service status
 ocx service uninstall
 ```

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

@@ -73,7 +73,7 @@ opencodex поставляет рантайм Bun (сейчас это **1.3.14*
 2. **Запустить Bun, которому вы доверяете, через `OPENCODEX_BUN_PATH`.** Это непроверенная
    территория — вы запускаете opencodex на рантайме, который мы не тестировали, на свой риск.
    Важно для service-установок: override считывается **при генерации артефакта службы**, а не при
-   её старте. Задайте переменную окружения и заново выполните `ocx service install` из той же
+   её старте. Задайте переменную окружения и заново выполните `ocx service repair` из той же
    оболочки, чтобы путь оказался зашит в долговременное определение службы. Одной только
    переменной для уже установленной службы недостаточно.
 

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

@@ -81,7 +81,7 @@ restart it.
    unvalidated territory — you are running opencodex on a runtime we have not
    tested; at your own risk. Important for service installs: the override is
    read **when the service artifact is generated**, not at service start. Set
-   the environment variable, then re-run `ocx service install` from that same
+   the environment variable, then re-run `ocx service repair` from that same
    shell so the path is baked into the durable service definition. Setting
    the env alone does nothing for an already-installed service.
 

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

@@ -135,14 +135,15 @@ ocx status --json
 
 ## 后台服务
 
-### `ocx service [install|start|stop|status|uninstall|remove]`
+### `ocx service [install|repair|start|stop|status|uninstall|remove]`
 
 将 opencodex 作为登录管理的后台服务运行（macOS **launchd**、Linux **systemd user unit**、Windows **Task Scheduler**），在登录时自动启动，在崩溃时自动重启。服务运行会设置 `OCX_SERVICE=1`，因此重启时不会反复改动 Codex 配置。
 
 | 子命令 | 操作 |
 | --- | --- |
 | none | 创建/更新并启动服务。 |
 | `install` | 创建并启动服务。 |
+| `repair` | 就地刷新已安装的服务并重启，不重新注册。 |
 | `start` | 启动已安装的服务。 |
 | `stop` | 停止服务并恢复原生 Codex。 |
 | `status` | 报告服务和代理诊断信息及日志路径。 |
@@ -152,6 +153,7 @@ ocx status --json
 ```bash
 ocx service
 ocx service install
+ocx service repair
 ocx service status
 ocx service uninstall
 ```

docs-site/src/content/docs/zh-cn/troubleshooting/windows-memory.md

@@ -34,7 +34,7 @@ opencodex 打包了 Bun 运行时（当前为 **1.3.14**）。这类内存增长
 
 1. **等待捆绑运行时更新。** 一旦某个 Bun 版本可验证地包含这些修复，opencodex 就会升级捆绑运行时，并在 Windows 上自动启用更安全的流路径（macOS 仍然需要下面的显式启用）。
 
-2. **通过 `OPENCODEX_BUN_PATH` 运行你信任的 Bun 运行时。** 这属于未验证区域，你是在一个我们没有测试过的运行时上运行 opencodex，风险自负。对服务安装而言，这个覆盖值是在生成服务产物时读取的，而不是在服务启动时读取的。先设置环境变量，然后在同一个 shell 中重新运行 `ocx service install`，这样路径才会被写入持久化的服务定义。只设置环境变量对已经安装好的服务没有任何作用。
+2. **通过 `OPENCODEX_BUN_PATH` 运行你信任的 Bun 运行时。** 这属于未验证区域，你是在一个我们没有测试过的运行时上运行 opencodex，风险自负。对服务安装而言，这个覆盖值是在生成服务产物时读取的，而不是在服务启动时读取的。先设置环境变量，然后在同一个 shell 中重新运行 `ocx service repair`，这样路径才会被写入持久化的服务定义。只设置环境变量对已经安装好的服务没有任何作用。
 
 3. **通过 `streamMode: "eager-relay"` 显式启用有界中继。** 有两种方式：编辑 `config.json`（添加 `"streamMode": "eager-relay"`），或调用管理 API - `PUT /api/settings` 携带 `{"streamMode":"eager-relay"}`，即可对新轮次生效，无需重启。**崩溃风险警告：** 在 Bun 1.3.14 上，这会使用受 #32111 影响的流形态，可能在流中途使进程崩溃（任何操作系统都会受影响，不只是 Windows）。服务管理器会把它重启，但正在进行的请求会失败。`"legacy-tee"` 会固定在当前默认路径。Windows 上，`"auto"`（默认值）会交给运行时门控决定。macOS 上，`"auto"` 始终保持 tee；显式 `"eager-relay"` 才是显式启用选项。
 

gui/src/pages/startup-sections.tsx

@@ -225,6 +225,14 @@ export function StartupRecoverySection({
 }) {
   const { t } = useI18n();
 
+  // An already-registered service is refreshed in place. `install` re-registers, which
+  // needs elevation on Windows and can switch a WinSW backend to Task Scheduler, so
+  // handing that command to someone who already has a service costs them a UAC prompt
+  // they do not need. A conflict still needs uninstall-then-install.
+  const serviceCommand = data.serviceInstalled && !data.serviceConflict
+    ? data.commands.repairService
+    : data.commands.installService;
+
   return (
     <section className="panel startup-actions">
       <div className="panel-head">
@@ -237,10 +245,10 @@ export function StartupRecoverySection({
           <div className="startup-command-row">
             <div>
               <strong>{t("startup.command.service")}</strong>
-              <code>{data.commands.installService}</code>
+              <code>{serviceCommand}</code>
             </div>
-            <button type="button" className="btn btn-ghost btn-sm" onClick={() => onCopy(data.commands.installService)}>
-              {copied === data.commands.installService ? t("startup.copied") : t("startup.copy")}
+            <button type="button" className="btn btn-ghost btn-sm" onClick={() => onCopy(serviceCommand)}>
+              {copied === serviceCommand ? t("startup.copied") : t("startup.copy")}
             </button>
           </div>
         )}

gui/src/pages/startup-shared.ts

@@ -27,6 +27,7 @@ export interface StartupHealthData {
   diagnosticStale: boolean;
   commands: {
     installService: string;
+    repairService: string;
     installShim: string;
     restoreNative: string;
   };

src/cli/doctor.ts

@@ -730,11 +730,21 @@ export function proxyDownRestartHint(input: {
   proxyRunning: boolean;
   port: number;
   serviceViable: boolean;
+  /** Absent means "unknown"; the hint then keeps its pre-repair wording. */
+  serviceInstalled?: boolean;
+  serviceConflict?: boolean;
 }): string | null {
   if (input.proxyRunning) return null;
+  // `serviceViable` alone conflates "no service at all" with "registered but stale or
+  // stopped". Only the first wants `install`: re-registering an existing service costs a
+  // UAC prompt on Windows and can switch a WinSW backend to Task Scheduler. A conflict
+  // still needs uninstall-then-install, which repairService() refuses outright.
+  const installedButBroken = input.serviceInstalled === true && input.serviceConflict !== true;
   const restart = input.serviceViable
     ? "Restart it with 'ocx service start' (service installed) or 'ocx start'."
-    : "Restart it with 'ocx start', or install the persistent service: 'ocx service install'.";
+    : installedButBroken
+      ? "Restart it with 'ocx start', or refresh the installed service: 'ocx service repair'."
+      : "Restart it with 'ocx start', or install the persistent service: 'ocx service install'.";
   return `The ocx proxy is not running. Codex/Claude clients pinned to 127.0.0.1:${input.port} fail with errors like "error sending request for url (http://127.0.0.1:${input.port}/v1/responses)". ${restart}`;
 }
 
@@ -950,6 +960,8 @@ export async function runDoctor(args: string[] = []): Promise<void> {
     proxyRunning: Boolean(live),
     port: live?.port ?? doctorConfig.port ?? 10100,
     serviceViable: startup.serviceViable,
+    serviceInstalled: startup.serviceInstalled,
+    serviceConflict: startup.serviceConflict,
   });
   if (proxyDown) hints.push(proxyDown);
   for (const row of providerApiKeys) {