fix(link): restore owned integrations before native signal exit

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

@@ -32,6 +32,8 @@ ocx start --socks5-off
 
 ### `ocx stop`
 
+Un Link Child non supervisé restaure Codex natif et Grok avant de libérer son listener lors d’un signal, en revérifiant la connexion à chaque écriture. Service/Desktop, sibling, transfert de redémarrage et reçu stop du parent préservent les intégrations. L’arrêt refuse le redémarrage avec `409 runtime_stopping`. Une terminaison forcée peut éviter le signal ; la restauration par `ocx stop` reste nécessaire.
+
 Arrête le proxy actif à partir de son PID, supprime le fichier de PID et rétablit le fonctionnement natif de Codex. Si un service d’arrière-plan géré est installé, `ocx stop` l’arrête d’abord afin qu’il ne puisse pas relancer le proxy. Le bouton **Stop** du tableau de bord Web exécute la même opération (`POST /api/stop`) sur tous les backends, sauf le Planificateur de tâches Windows : le wrapper peut y relancer le proxy après la fin de la tâche, donc le tableau de bord refuse avec `respawnable_service`, ne modifie rien et vous demande d'exécuter `ocx stop`.
 
 Sur un client hub connecté, `ocx stop`, y compris via l’API, conserve le routage Codex, le catalogue et la configuration Grok appartenant à la connexion ; `ocx start` les dessert de nouveau. L’arrêt explicite d’un Remote Link Child rétablit au contraire, si la restauration partagée réussit, le routage natif de Codex, le catalogue et les métadonnées de reprise sauvegardées, et supprime la configuration Grok gérée. La connexion Home enregistrée reste conservée ; `ocx disconnect` la supprime.

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

@@ -28,6 +28,8 @@ ocx start --socks5-off
 
 ### `ocx stop`
 
+監督プロセスのない Link Child は終了シグナル時、各書き込みで接続を再確認し、リスナーを閉じる前に Codex と管理対象 Grok を復元します。サービス・Desktop、sibling、再起動の引き継ぎ、親 stop 記録がある場合は設定を保持します。終了中の再起動は `409 runtime_stopping` です。強制終了はシグナル処理を省略する場合があり、親 `ocx stop` の復元も必要です。
+
 実行中のプロキシを (PID によって) 停止し、PID ファイルを削除します。スタンドアロンの所有者ではネイティブ Codex を復元します。マネージド バックグラウンド サービスがインストールされている場合、`ocx stop` はそれを最初に停止するため、プロキシを再起動できません。Web ダッシュボードの **停止** ボタンは同じ処理 (`POST /api/stop`) を実行しますが、Windows タスク スケジューラだけは例外です。タスク終了後もラッパーがプロキシを再起動しうるため、ダッシュボードは `respawnable_service` で拒否し、何も変更せずに `ocx stop` の実行を促します。
 
 接続済みの hub クライアントでは、`ocx stop`（成功した API 停止を含む）は接続が所有する Codex のルーティング、モデルカタログ、Grok 設定を保持します。`ocx start` はルーティングを再注入せず、その設定で再び処理します。Codex を自身のアカウントへ戻すには `ocx disconnect`、既にネイティブルーティングへ戻した後の再適用には `ocx sync --restart-codex` を使います。

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

@@ -44,6 +44,8 @@ ocx start --socks5-off
 
 ### `ocx stop`
 
+감독 프로세스 없이 실행되는 Link Child는 종료 신호 처리 시 각 쓰기 직전에 연결을 재확인하고 리스너를 닫기 전에 Codex 기본 설정과 관리 Grok 설정을 복원합니다. 서비스·Desktop 감독, sibling, 재시작·재활용 인계, 부모 stop 영수증이 있으면 설정을 보존합니다. 종료 중 재시작 요청은 `409 runtime_stopping`입니다. 강제 종료는 신호 처리를 건너뛸 수 있어 부모 `ocx stop`의 복원도 필요합니다.
+
 실행 중인 프록시를 PID 기준으로 중지하고 PID 파일을 삭제합니다. 독립 실행 소유자라면 기본 Codex를 복원합니다. 관리형
 백그라운드 서비스가 설치되어 있으면 `ocx stop`이 먼저 그 서비스를 중지하므로 프록시가 다시
 올라올 수 없습니다. 웹 대시보드의 **Stop** 버튼도 같은 동작(`POST /api/stop`)을 하지만, Windows 작업 스케줄러는 예외입니다. 작업이 끝나도 래퍼가 프록시를 다시 띄울 수 있어서, 대시보드는 `respawnable_service`로 거절하고 아무것도 바꾸지 않은 채 `ocx stop` 실행을 안내합니다.

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

@@ -82,6 +82,8 @@ ocx start --socks5-off
 
 ### `ocx stop [--json]`
 
+An unsupervised Link Child handling a shutdown signal restores native Codex and managed Grok before releasing its listener, rechecking the served connection before each write. Service/Desktop supervision, sibling ownership, restart/recycle handoff and pending parent stop receipts preserve integrations. Shutdown rejects bound restart with `409 runtime_stopping`. Forced termination can bypass signal handlers; parent `ocx stop` restoration remains necessary. To route Codex through Home again after such a stop, start the Child (`ocx start`, or `ocx service start` for an installed service) and then run `ocx sync --restart-codex`. Starting alone does not reapply routing. A sync run while the Child is stopped still reapplies routing, which points Codex at a listener that is not running, so start the Child first.
+
 Stop the running proxy (by PID), remove the PID file, and restore native Codex for standalone owners. If a managed
 background service is installed, `ocx stop` also stops it first so it cannot respawn the proxy.
 On a connected hub client, `ocx stop` leaves Codex routing, its

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

@@ -50,6 +50,8 @@ ocx start --socks5-off
 
 ### `ocx stop`
 
+Link Child без супервизора при сигнале восстанавливает нативный Codex и управляемый Grok до закрытия listener, проверяя подключение перед каждой записью. Сервис/Desktop, sibling, передача перезапуска и квитанция stop родителя сохраняют настройки. Во время завершения перезапуск возвращает `409 runtime_stopping`. Принудительное завершение может обойти сигнал; восстановление родителем `ocx stop` остаётся необходимым.
+
 Остановить работающий прокси (по PID) и удалить PID-file; для автономного владельца также восстановить native Codex. Если
 установлена managed background service, `ocx stop` сначала останавливает и её, чтобы она не
 перезапустила прокси обратно. Кнопка **Stop** в веб-дашборде выполняет то же действие (`POST /api/stop`) на всех бэкендах, кроме планировщика заданий Windows: там обёртка может перезапустить прокси после завершения задачи, поэтому дашборд отказывает с `respawnable_service`, ничего не меняет и просит выполнить `ocx stop`.

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

@@ -50,6 +50,8 @@ ocx start --socks5-off
 
 ### `ocx stop`
 
+Gözetimsiz Link Child kapanma sinyalinde her yazmadan önce bağlantıyı doğrular ve dinleyiciyi bırakmadan önce yerel Codex ile yönetilen Grok ayarlarını geri yükler. Servis/Desktop, sibling, yeniden başlatma devri ve üst stop makbuzu ayarları korur. Kapanma sırasında yeniden başlatma `409 runtime_stopping` döndürür. Zorla sonlandırma sinyali atlayabilir; üst `ocx stop` geri yüklemesi yine gereklidir.
+
 Çalışan proxy'yi (PID'ye göre) durdurun, PID dosyasını kaldırın ve yerel Codex'i
 geri yükleyin. Yönetilen bir arka plan servisi kuruluysa `ocx stop` proxy'yi
 yeniden oluşturamaması için önce onu da durdurur. Web kontrol panelinin **Durdur** düğmesi aynı eylemi (`POST /api/stop`) Windows Görev Zamanlayıcı dışındaki tüm arka uçlarda çalıştırır: orada görev bittikten sonra sarmalayıcı proxy'yi yeniden başlatabilir, bu yüzden panel `respawnable_service` ile reddeder, hiçbir şeyi değiştirmez ve `ocx stop` çalıştırmanızı ister.

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

@@ -28,6 +28,8 @@ ocx start --socks5-off
 
 ### `ocx stop`
 
+无人监督的 Link Child 处理退出信号时，会在每次写入前核对连接，并在关闭监听器前恢复 Codex 原生配置及受管理的 Grok。服务/Desktop、sibling、重启交接和父进程 stop 收据会保留配置。退出中的重启请求返回 `409 runtime_stopping`。强制终止可能跳过信号处理，仍需父进程 `ocx stop` 的恢复路径。
+
 停止正在运行的代理（按 PID），移除 PID 文件；独立运行的所有者还会恢复原生 Codex。如果安装了受管后台服务，`ocx stop` 还会先停止该服务，这样它就无法重新拉起代理。Web 仪表盘的 **Stop** 按钮在多数后端执行同样的操作（`POST /api/stop`），但 Windows 任务计划程序除外：任务结束后包装器仍可能重新拉起代理，只有运行在代理之外的 stop 才能在恢复客户端配置前确认这个重启窗口，因此仪表盘会以 `respawnable_service` 拒绝、不做任何更改，并提示改用 `ocx stop`。
 
 对于已连接的 hub 客户端，`ocx stop`（包括成功的 API 停止）会保留连接所拥有的 Codex 路由、模型目录和 Grok 配置。`ocx start` 使用这些保留的配置恢复服务，不会重新注入路由。要让 Codex 回到自己的账户，请运行 `ocx disconnect`；若已恢复为原生路由，要重新应用连接路由，请运行 `ocx sync --restart-codex`。

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

@@ -28,6 +28,8 @@ ocx start --socks5-off
 
 ### `ocx stop`
 
+無人監督的 Link Child 處理結束訊號時，會在每次寫入前核對連線，並在關閉接聽器前還原 Codex 原生設定及受管理的 Grok。服務/Desktop、sibling、重新啟動交接和父程序 stop 收據會保留設定。結束中的重新啟動要求回傳 `409 runtime_stopping`。強制終止可能略過訊號處理，仍需父程序 `ocx stop` 的還原路徑。
+
 停止執行中的代理（依 PID）、移除 PID 檔案，並還原原生 Codex。若已安裝受管背景服務，`ocx stop` 也會先停止它，使其無法重新生成代理。網頁儀表板的 **Stop** 按鈕在多數後端執行相同動作（`POST /api/stop`），但 Windows 工作排程器除外：工作結束後包裝程序仍可能重新啟動 Proxy，因此儀表板會以 `respawnable_service` 拒絕、不做任何變更，並請你改用 `ocx stop`。
 
 對已連線的 hub 用戶端，`ocx stop`（包括成功的 API 停止）會保留連線擁有的 Codex 路由、目錄和 Grok 設定，`ocx start` 會再次提供服務。明確停止 Remote Link Child 時，若共用設定還原成功，則會還原原生 Codex 路由、目錄與已備份的續接歷程中繼資料，並移除受管理的 Grok 設定。已儲存的 Home 連線會保留，可用 `ocx disconnect` 移除。

scripts/test-layout/layout-clients.json

@@ -151,6 +151,7 @@
   "client-link-connect.test.ts": "clients",
   "client-link-relay.test.ts": "clients",
   "client-link-runtime.test.ts": "clients",
+  "client-link-stop.test.ts": "clients",
   "link-routes.test.ts": "clients",
   "client-link-state.test.ts": "clients",
   "client-link-status.test.ts": "clients",

src/cli/index.ts

@@ -1139,7 +1139,9 @@ async function handleStopUnlocked(snapshot?: GuardedStopSnapshot) {
     .filter(read => isPendingTeardownAbandoned(read, teardownOwnerStillRunning));
   let teardownNonce: string | undefined;
   // #7423: an update that restarts the proxy asks this stop to leave Codex routing for the replacement.
-  const handoverRequested = updateTeardownHandoverRequested(process.env, () => shouldSyncCodexOnStart(loadConfig())) && !stoppingSibling && !connectedClientSkip;
+  // Client start never discharges a standalone update-handover receipt or reapplies routing.
+  const handoverRequested = updateTeardownHandoverRequested(process.env, () => shouldSyncCodexOnStart(loadConfig()))
+    && !stoppingSibling && readClientConnectionState().kind !== "connected";
   let deferralHonoredByProxy = false;
   const claimTeardown = (endpoint: { hostname: string; port: number }, endpointSource: "exact" | "guessed") => {
     if (teardownNonce || stoppingSibling) return;

src/client/connect.ts

@@ -18,7 +18,8 @@ import {
   withClientLifecycle, withClientLifecycleSync,
   type ClientLifecycleHeld, type ClientLifecycleLockDeps,
 } from "./lifecycle-lock";
-import { invalidateCodexModelsCache } from "../codex/catalog/sync";
+import { invalidateCodexModelsCache, invalidateCodexModelsCacheWithPermit } from "../codex/catalog/sync";
+import { withCatalogWriteSerialization } from "../codex/catalog-write-serialization";
 import {
   injectCodexConfig,
   currentExternalCodexModelProvider,
@@ -30,7 +31,7 @@ import {
   journalOwner,
   restoreJournalState,
 } from "../codex/journal";
-import { DEFAULT_CATALOG_PATH } from "../codex/paths";
+import { DEFAULT_CATALOG_PATH, getCodexHome } from "../codex/paths";
 import {
   readServiceApiTokenState,
   readTokenBackupState,
@@ -95,6 +96,7 @@ import {
 import { hubStateCachePath } from "./hub-state";
 import { ClientLinkStateError, clearClientLinkState, readClientLinkState } from "./link-state";
 import { isLinkPort } from "../link/ports";
+import { clientSyncRuntimeGuard, ClientSyncRuntimeError } from "./sync-runtime";
 
 class RotationRecoveryRequiredError extends Error {
   constructor(message: string, options?: ErrorOptions) {
@@ -901,7 +903,15 @@ async function syncConnectedClientUnlocked(
     if (state.kind !== "connected" || state.value.pendingOperation) throw new Error("client_sync_unavailable");
     const token = readServiceApiTokenState();
     if (token.kind !== "present" || token.fingerprint !== state.value.tokenFingerprint) throw new Error("client_token_changed");
-    return { connection: state.value, token };
+    let assertRuntimeCurrent = () => {};
+    try { if (isLinkConnection(state.value)) assertRuntimeCurrent = clientSyncRuntimeGuard(); }
+    catch (error) {
+      if (options.expect && error instanceof ClientSyncRuntimeError && error.code === "client_runtime_stopping") {
+        throw new ClientSyncExpectationError(options.expect, "pending_operation");
+      }
+      throw error;
+    }
+    return { connection: state.value, token, assertRuntimeCurrent };
   }), deps.lifecycleLockDeps);
   let downloaded: Awaited<ReturnType<typeof downloadClientCatalog>> | undefined;
   let stale = false;
@@ -918,6 +928,7 @@ async function syncConnectedClientUnlocked(
   // they were, which is the known-good state.
   if (downloaded) assertClientCatalogCompatible(downloaded.body, deps.catalogCompatibility);
   const next = withClientLifecycleSync(() => withConfigMutationLockSync(() => {
+    initial.assertRuntimeCurrent();
     assertClientConnectionUnchanged(initial.connection);
     const token = readServiceApiTokenState();
     if (token.kind !== "present" || token.fingerprint !== initial.token.fingerprint) throw new Error("client_token_changed");
@@ -933,10 +944,12 @@ async function syncConnectedClientUnlocked(
   }), deps.lifecycleLockDeps);
   // Read-only: injection invokes this while N/C are held. Acquiring L here would invert C→L.
   const beforeClientWrite = () => {
+    initial.assertRuntimeCurrent();
     assertClientConnectionUnchanged(next);
     const token = readServiceApiTokenState();
     if (next.pendingOperation || token.kind !== "present" || token.fingerprint !== next.tokenFingerprint) throw new Error("client_token_changed");
   };
+  const withClientWrite = <T>(write: () => T): T => withConfigMutationLockSync(() => { beforeClientWrite(); return write(); });
   let injected = false;
   let homeSettings: HomeCodexSettingsSource | undefined;
   let appliedRecord: HomeCodexSettingsRecord | undefined;
@@ -945,12 +958,15 @@ async function syncConnectedClientUnlocked(
     let config = loadConfig();
     // #6957: a link Child applies the Home's OpenCodex-owned Codex settings with the catalog.
     if (isLinkConnection(next)) {
-      homeSettings = await resolveHomeCodexSettings(next, initial.token.token, deps.linkHome);
+      homeSettings = await resolveHomeCodexSettings(next, initial.token.token, { ...deps.linkHome, withWriteGuard: withClientWrite });
       if (homeSettings.source !== "local") config = overlayHomeCodexSettings(config, homeSettings.document.settings);
       // About to write different settings: until their record commits, report no applied digest
       // rather than the previous one (OCX-6). A failed injection then reads "unknown", never a
       // digest of values Codex no longer has or never got.
-      if (homeSettings.source === "home" && next.link) withdrawChangingHomeCodexSettingsRecord(next.link.linkId, homeSettings.document);
+      if (homeSettings.source === "home" && next.link) {
+        const { linkId } = next.link, { document } = homeSettings;
+        withClientWrite(() => withdrawChangingHomeCodexSettingsRecord(linkId, document));
+      }
     }
     const result = await injectCodexConfig(config.port, { ...config, syncResumeHistory: false }, {
       routingTarget: routingTarget(next.serverUrl, isLinkConnection(next) ? config.port : undefined, config), catalogPath: DEFAULT_CATALOG_PATH,
@@ -962,23 +978,24 @@ async function syncConnectedClientUnlocked(
       const linkId = next.link.linkId;
       const settings = homeSettings;
       try {
-        appliedRecord = withClientLifecycleSync(() => {
-          beforeClientWrite();
-          return recordHomeCodexSettings(linkId, settings, deps.now) ?? readHomeCodexSettingsRecord(linkId) ?? undefined;
-        }, deps.lifecycleLockDeps);
+        appliedRecord = withClientLifecycleSync(() => withClientWrite(() =>
+          recordHomeCodexSettings(linkId, settings, deps.now) ?? readHomeCodexSettingsRecord(linkId) ?? undefined), deps.lifecycleLockDeps);
       } catch (error) {
         // An ownership change is not a disk problem: report it as itself.
-        if (error instanceof Error && (error.message === "client_token_changed" || error.message === "client_connection_changed")) throw error;
+        if (error instanceof ClientSyncRuntimeError || (error instanceof Error && (error.message === "client_token_changed" || error.message === "client_connection_changed"))) throw error;
         // The injection committed, so the cache refresh below still runs; the caller reports this.
-        try { clearHomeCodexSettingsRecord(); } catch { /* status already reads no recorded apply or reports the write */ }
+        try { withClientWrite(clearHomeCodexSettingsRecord); } catch { /* status already reads no recorded apply or reports the write */ }
         applyRecordFailed = true;
       }
     }
   }
   const cacheSynced = withClientLifecycleSync(() => {
-    beforeClientWrite();
-    // Cache invalidation acquires K itself (N -> K -> C); never call it while C is held.
-    return invalidateCodexModelsCache({ allowWhenDesiredDisabled: true });
+    // Acquire K before the guarded C commit; never acquire K from inside C.
+    const owningHome = getCodexHome();
+    const result = withCatalogWriteSerialization(owningHome, permit => withClientWrite(() =>
+      invalidateCodexModelsCacheWithPermit(permit, owningHome, { allowWhenDesiredDisabled: true })),
+    { intent: "cache", writer: "cache-invalidate" });
+    return result.kind === "completed" && result.value;
   }, deps.lifecycleLockDeps);
   return {
     catalogWritten: downloaded !== undefined, cacheSynced, injected, stale,