fix(codex): warn or restart stale app-server after sync

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

@@ -191,6 +191,11 @@ If a model is missing from Codex, or the catalog order/visibility looks wrong, c
    independently of other providers.
 5. **Cache and `ocx sync`** — live catalogs are cached for about five minutes (`modelCacheTtlMs`,
    default `300000`). Run `ocx sync` to force a fresh fetch and rewrite the catalog immediately.
+6. **Running Codex `app-server`** — rewriting the on-disk catalog is not enough while a long-lived
+   Codex `app-server` (Desktop / CLI background host) keeps the previous list in memory. `ocx sync`
+   and `ocx sync-cache` warn when those processes are detected. Restart them with
+   `ocx sync --restart-codex` (or stop the matching `app-server` processes yourself), then let Codex
+   recreate them so the new list appears.
 
 :::caution[Other local writers]
 Catalog writes (`opencodex-catalog.json`, `config.toml`) are atomic **inside** opencodex, which only

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

@@ -142,14 +142,21 @@ opencodex local config only if all restore steps succeeded. `remove` is an alias
 
 ## Models & Codex
 
-### `ocx sync`
+### `ocx sync [--restart-codex]`
 
 Fetch the live model list from every configured provider and re-inject the merged catalog into Codex.
 Run it after adding a provider or to refresh available models.
 
-### `ocx sync-cache`
+If long-lived Codex `app-server` processes are still running, `ocx sync` warns that they may keep
+serving the previous in-memory model list even though `opencodex-catalog.json` / `models_cache.json`
+were updated. Pass `--restart-codex` to send `SIGTERM` only to matching `codex … app-server` and
+`codex-code-mode-host` processes owned by the current user (active turns may be interrupted). Broad
+`pkill -f codex` matching is intentionally avoided.
 
-Invalidate Codex's local model picker cache so it is rebuilt from the active opencodex catalog.
+### `ocx sync-cache [--restart-codex]`
+
+Invalidate Codex's local model picker cache so it is rebuilt from the active opencodex catalog. The
+same stale-`app-server` warning and optional `--restart-codex` behavior as `ocx sync` apply.
 
 ### `ocx v2 [subcommand]`
 

gui/src/i18n/de.ts

@@ -189,7 +189,7 @@ export const de: Record<TKey, string> = {
   "dash.syncModels": "Modelle synchronisieren",
   "dash.syncing": "Synchronisiere…",
   "dash.syncOk": "Synchronisierung abgeschlossen. {count} Modell(e) angehängt.",
-  "dash.syncStaleHint": "Falls die Codex-App weiterhin eine alte Liste zeigt, starte ihren langlebigen App-Server-Prozess neu.",
+  "dash.syncStaleHint": "Falls Codex weiterhin eine alte Liste zeigt, starte den langlebigen App-Server neu ({cmd}).",
   "dash.syncFailed": "Synchronisierung fehlgeschlagen: {error}",
   "dash.projectConfigTitle": "Projekt-Codex-Konfig umgeht OpenCodex",
   "dash.projectConfigHint": "Diese repo-lokalen Einstellungen überschreiben den OpenCodex-Proxy (z. B. direkt zu OpenCode Go routen). Entferne sie, damit die Routing aus ~/.codex/config.toml in diesem Projekt greift.",

gui/src/i18n/en.ts

@@ -199,7 +199,7 @@ export const en = {
   "dash.syncModels": "Sync models",
   "dash.syncing": "Syncing…",
   "dash.syncOk": "Sync complete. {count} model(s) appended.",
-  "dash.syncStaleHint": "If Codex App still shows an older list, restart its long-lived app-server process.",
+  "dash.syncStaleHint": "If Codex still shows an older list, restart its long-lived app-server ({cmd}).",
   "dash.syncFailed": "Sync failed: {error}",
   "dash.projectConfigTitle": "Project Codex config bypasses OpenCodex",
   "dash.projectConfigHint": "These repo-local settings override the OpenCodex proxy (e.g. route to OpenCode Go directly). Remove them so ~/.codex/config.toml routing applies in that project.",

gui/src/i18n/ja.ts

@@ -198,7 +198,7 @@ export const ja: Record<TKey, string> = {
   "dash.syncModels": "モデルを同期",
   "dash.syncing": "同期中…",
   "dash.syncOk": "同期完了。{count} 個のモデルを追加しました。",
-  "dash.syncStaleHint": "Codex App がまだ古いリストを表示する場合、長時間稼働の app-server プロセスを再起動してください。",
+  "dash.syncStaleHint": "Codex がまだ古いリストを表示する場合、長時間稼働の app-server を再起動してください（{cmd}）。",
   "dash.syncFailed": "同期失敗: {error}",
   "dash.projectConfigTitle": "プロジェクトの Codex 設定が OpenCodex をバイパスします",
   "dash.projectConfigHint": "これらのリポジローカル設定は OpenCodex プロキシを上書きします(例: OpenCode Go に直接ルーティング)。~/.codex/config.toml のルーティングがそのプロジェクトで適用されるように削除してください。",

gui/src/i18n/ko.ts

@@ -193,7 +193,7 @@ export const ko: Record<TKey, string> = {
   "dash.syncModels": "모델 동기화",
   "dash.syncing": "동기화 중…",
   "dash.syncOk": "동기화 완료. {count}개 모델이 추가됐습니다.",
-  "dash.syncStaleHint": "Codex App에 여전히 예전 목록이 보이면 오래 실행 중인 app-server 프로세스를 재시작하세요.",
+  "dash.syncStaleHint": "Codex에 여전히 예전 목록이 보이면 오래 실행 중인 app-server를 재시작하세요 ({cmd}).",
   "dash.syncFailed": "동기화 실패: {error}",
   "dash.projectConfigTitle": "프로젝트 Codex 설정이 OpenCodex를 우회합니다",
   "dash.projectConfigHint": "저장소 로컬 설정이 OpenCodex 프록시를 덮어씁니다(예: OpenCode Go로 직접 라우팅). 해당 프로젝트에서 ~/.codex/config.toml 프록시를 쓰려면 제거하세요.",

gui/src/i18n/ru.ts

@@ -198,7 +198,7 @@ export const ru: Record<TKey, string> = {
   "dash.syncModels": "Синхронизировать модели",
   "dash.syncing": "Синхронизация…",
   "dash.syncOk": "Синхронизация завершена. Добавлено моделей: {count}.",
-  "dash.syncStaleHint": "Если Codex App всё ещё показывает старый список, перезапустите его долгоживущий процесс app-server.",
+  "dash.syncStaleHint": "Если Codex всё ещё показывает старый список, перезапустите долгоживущий app-server ({cmd}).",
   "dash.syncFailed": "Ошибка синхронизации: {error}",
   "dash.projectConfigTitle": "Конфигурация Codex в проекте обходит OpenCodex",
   "dash.projectConfigHint": "Эти локальные настройки репозитория переопределяют прокси OpenCodex (например, направляют запросы напрямую в OpenCode Go). Удалите их, чтобы в этом проекте действовала маршрутизация из ~/.codex/config.toml.",

gui/src/i18n/zh.ts

@@ -193,7 +193,7 @@ export const zh: Record<TKey, string> = {
   "dash.syncModels": "同步模型",
   "dash.syncing": "同步中…",
   "dash.syncOk": "同步完成。已追加 {count} 个模型。",
-  "dash.syncStaleHint": "如果 Codex App 仍显示旧列表，请重启长期运行的 app-server 进程。",
+  "dash.syncStaleHint": "如果 Codex 仍显示旧列表，请重启长期运行的 app-server（{cmd}）。",
   "dash.syncFailed": "同步失败：{error}",
   "dash.projectConfigTitle": "项目 Codex 配置绕过了 OpenCodex",
   "dash.projectConfigHint": "这些仓库级设置会覆盖 OpenCodex 代理（例如直接走 OpenCode Go）。请移除它们，以便该项目使用 ~/.codex/config.toml 的代理路由。",

gui/src/pages/dashboard-overview-sections.tsx

@@ -1,4 +1,5 @@
 import { IconAlert, IconExternal, IconInfo, IconRefresh } from "../icons";
+import { Trans } from "../i18n/provider";
 import { Select } from "../ui";
 import { EFFORT_CAP_LEVELS, requireJson, sidecarBackendForModel, updateJobLabel } from "./dashboard-shared";
 import type { useDashboardData } from "./use-dashboard-data";
@@ -221,7 +222,7 @@ export function DashboardMaintenancePanel({ d }: { d: Dash }) {
           <span>
             {t("dash.syncOk", { count: syncResult.added })}
             {syncResult.warning ? ` ${syncResult.warning}` : ""}
-            {syncResult.staleAppServerHint ? ` ${t("dash.syncStaleHint")}` : ""}
+            {syncResult.staleAppServerHint ? <>{" "}<Trans k="dash.syncStaleHint" cmd="ocx sync --restart-codex" /></> : null}
           </span>
         </div>
       )}

src/cli/help.ts

@@ -59,8 +59,22 @@ const helpEntries: Record<string, HelpEntry> = {
     ],
   },
   ensure: { usage: "ocx ensure", summary: "Ensure the proxy is running and Codex config/cache are current." },
-  sync: { usage: "ocx sync", summary: "Fetch provider models and inject them into Codex config." },
-  "sync-cache": { usage: "ocx sync-cache", summary: "Refresh Codex's model cache from the active catalog." },
+  sync: {
+    usage: "ocx sync [--restart-codex]",
+    summary: "Fetch provider models and inject them into Codex config.",
+    details: [
+      "After writing the catalog, warns if long-lived Codex app-server processes are still running.",
+      "--restart-codex sends SIGTERM only to matching app-server / code-mode-host processes (may interrupt active turns).",
+    ],
+  },
+  "sync-cache": {
+    usage: "ocx sync-cache [--restart-codex]",
+    summary: "Refresh Codex's model cache from the active catalog.",
+    details: [
+      "Warns when Codex app-server processes still hold an in-memory model list.",
+      "--restart-codex sends SIGTERM only to matching app-server / code-mode-host processes (may interrupt active turns).",
+    ],
+  },
   status: { usage: "ocx status", summary: "Check proxy server status." },
   doctor: { usage: "ocx doctor", summary: "Diagnose environment/network issues (paths, WSL /mnt, proxy env, ChatGPT reachability)." },
   debug: {
@@ -186,8 +200,9 @@ Usage:
   ocx codex-shim <sub>        Auto-start proxy when \`codex\` launches (install|status|uninstall|remove)
   ocx tray <sub>              Windows status tray (install|start|stop|status|uninstall)
   ocx ensure                  Ensure the proxy is running and Codex config/cache are current
-  ocx sync                    Fetch models from providers and inject into Codex config
-  ocx sync-cache              Refresh Codex's model cache from the active catalog
+  ocx sync [--restart-codex]  Fetch models from providers and inject into Codex config
+  ocx sync-cache [--restart-codex]
+                              Refresh Codex's model cache from the active catalog
   ocx status                  Check proxy server status
   ocx doctor                  Diagnose environment/network issues (WSL, proxy, ChatGPT reachability)
   ocx debug [provider|usage ...]

src/cli/index.ts

@@ -744,7 +744,13 @@ switch (command) {
     break;
   }
   case "sync": {
-    await syncModelsToCodex((await findLiveProxy())?.port);
+    const restartCodex = args.slice(1).includes("--restart-codex");
+    const syncResult = await syncModelsToCodex((await findLiveProxy())?.port);
+    // Only warn/restart when a catalog or models_cache write actually happened.
+    if (syncResult.catalogWritten || syncResult.cacheSynced) {
+      const { afterCatalogWriteHandleAppServers } = await import("../codex/app-server-processes");
+      afterCatalogWriteHandleAppServers({ restart: restartCodex, log: console });
+    }
     break;
   }
   case "v2": {
@@ -753,8 +759,13 @@ switch (command) {
     break;
   }
   case "sync-cache": {
+    const restartCodex = args.slice(1).includes("--restart-codex");
     const { invalidateCodexModelsCache } = await import("../codex/catalog");
-    invalidateCodexModelsCache();
+    // Only warn/restart when models_cache was actually rewritten from a readable catalog.
+    if (invalidateCodexModelsCache()) {
+      const { afterCatalogWriteHandleAppServers } = await import("../codex/app-server-processes");
+      afterCatalogWriteHandleAppServers({ restart: restartCodex, log: console });
+    }
     break;
   }
   case "gui": {