@bitkyc08/opencodex 2.43.0 → 2.44.0

package/src/cli/capabilities.ts

@@ -526,6 +526,45 @@ export const CAPABILITIES: readonly Capability[] = [
       "Each client has its own route because a toggle rewrites that client's own config file.",
     ],
   },
+  {
+    command: ["integration", "client"],
+    summary: "Inspect and toggle Aside profile catalogs, read their history, and restore a selected profile operation.",
+    routes: [
+      { method: "GET", path: "/api/client-integrations/aside/profiles" },
+      { method: "PUT", path: "/api/client-integrations/aside/profiles" },
+      { method: "GET", path: "/api/client-integrations/aside/profiles/{profileId}" },
+      { method: "PUT", path: "/api/client-integrations/aside/profiles/{profileId}" },
+      { method: "GET", path: "/api/client-integrations/aside/profiles/journal" },
+      { method: "GET", path: "/api/client-integrations/aside/profiles/{profileId}/journal" },
+      { method: "POST", path: "/api/client-integrations/aside/profiles/{profileId}/restore" },
+    ],
+    flags: [
+      { name: "--client", value: "string", summary: "Select the file integration; use aside for profile controls." },
+      { name: "--profile", value: "number", summary: "Select one registered Aside account; omitted toggles affect all profiles." },
+      { name: "--op", value: "string", summary: "Operation ID for restore." },
+      { name: "--confirm-drift", value: "boolean", summary: "Explicitly allow restore to replace subsequent edits." },
+      { name: "--overwrite-conflict", value: "boolean", summary: "Explicitly allow enable to replace a conflicting provider block." },
+      { name: "--json", value: "boolean", summary: "Emit the profile state, history, or mutation result as JSON." },
+    ],
+    mutates: true,
+    json: "payload",
+    details: [
+      "Use status/show/list, history/journal, enable/disable, or restore after integration client.",
+      "These declarations cover the dedicated Aside profile paths; existing generic client routes retain their separate parity inventory.",
+    ],
+  },
+  {
+    command: ["sync"],
+    summary: "Synchronize client catalogs, including Aside profiles through the running server's mutation owner.",
+    routes: [{ method: "POST", path: "/api/client-integrations/aside/sync" }],
+    flags: [
+      { name: "--restart-codex", value: "boolean", summary: "Restart Codex app-servers after a catalog or cache write." },
+      { name: "--restart-desktop-app", value: "boolean", summary: "Restart the Codex desktop app after a catalog or cache write." },
+    ],
+    mutates: true,
+    json: "none",
+    details: ["The Aside refresh uses the live server; other catalog synchronization also performs local work."],
+  },
   {
     command: ["agent", "request-user-input"],
     summary: "Show or set whether default mode may ask the operator a question mid-task.",

package/src/cli/claude-agent-startup-sync.ts

@@ -10,7 +10,7 @@ export interface ClaudeAgentStartupSyncDeps {
 }
 
 /**
- * Keep the public readiness gate pending until both startup reconciliations have settled.
+ * Keep readiness pending until the roster and optional Desktop registry have settled.
  *
  * The Codex sync remains the authority for ready versus failed. Claude roster repair is
  * deliberately best-effort (#2200), but readiness must not become observable between the
@@ -22,6 +22,7 @@ export async function reconcileClientStartupBeforeReady<T>(
   readinessGate: ReadinessGate,
   syncCodex: (deferredGate: ReadinessGate) => Promise<T>,
   syncClaudeRoster: () => Promise<unknown>,
+  syncDesktopRegistry?: () => Promise<unknown>,
 ): Promise<T> {
   let codexReady = false;
   const deferredGate: ReadinessGate = {
@@ -32,6 +33,7 @@ export async function reconcileClientStartupBeforeReady<T>(
 
   const result = await syncCodex(deferredGate);
   await syncClaudeRoster();
+  await syncDesktopRegistry?.();
   if (codexReady) readinessGate.markReady();
   return result;
 }

package/src/cli/claude-desktop.ts

@@ -1,7 +1,12 @@
 import { readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
-import { loadConfig, saveConfigPreservingClaudeCode } from "../config";
-import { setIntegrationEnabled } from "../codex/desired-state";
+import { loadConfig, mutatePersistedConfig, withConfigMutationLockSync } from "../config";
+import { claudeDesktopIntegrationEnabledNow, setIntegrationEnabled } from "../codex/desired-state";
+import { readClientConnectionState, assertClientConnectionUnchanged, assertNoClientDisconnectPending, type ClientConnectionState } from "../client/state";
+import { downloadDesktop3pModels, HubClientError, normalizeHubOrigin } from "../client/hub-client";
+import { readServiceApiTokenState } from "../lib/service-secrets";
+import { applyRemoteDesktopStore, type DesktopStoreResult } from "../claude/desktop-remote-store";
+import { withClientLifecycleSync, type ClientLifecycleLockDeps } from "../client/lifecycle-lock";
 import {
   DESKTOP_FAMILIES,
   moveDesktopRoute,
@@ -11,6 +16,7 @@ import {
   type DesktopProfile,
 } from "../claude/desktop-profile";
 import { writeDesktop3pConfig, type Desktop3pConfigMode, parseDesktop3pModeArgs } from "../claude/desktop-3p";
+import { claudeDesktopPolicyWarning, probeClaudeDesktopPolicy } from "../claude/desktop-policy";
 import { filterCatalogVisibleModels, desktopVisibleNativeSlugs, nativeContextLimits } from "../codex/catalog";
 import { buildClaudeDesktopState, fetchAllModels } from "../server/management-api";
 import { findLiveProxy } from "../server/proxy-liveness";
@@ -33,6 +39,9 @@ function printDesktopHelp(): void {
 }
 
 export interface ApplyProfileDeps {
+  downloadDesktop3pModelsImpl?: typeof downloadDesktop3pModels;
+  applyRemoteDesktopStoreImpl?: typeof applyRemoteDesktopStore;
+  lifecycleLockDeps?: ClientLifecycleLockDeps;
   findLiveProxyImpl?: typeof findLiveProxy;
   postApplyImpl?: (
     mode: Desktop3pConfigMode,
@@ -41,20 +50,110 @@ export interface ApplyProfileDeps {
   probeClaudeDesktopPolicy?: typeof import("../claude/desktop-policy").probeClaudeDesktopPolicy;
 }
 
-export async function applyProfile(
+/** Persist only the requested local profile, never an await-old whole configuration. */
+function saveLocalDesktopProfile(
   profile: DesktopProfile,
+  expectedProfile: DesktopProfile | undefined,
+  expectedConnection: ClientConnectionState,
+  deps: ApplyProfileDeps,
+): void {
+  withClientLifecycleSync(() => {
+    const outcome = mutatePersistedConfig(current => {
+      assertNoClientDisconnectPending();
+      if (expectedConnection.kind === "connected") {
+        assertClientConnectionUnchanged(expectedConnection.value);
+        if (expectedConnection.value.pendingOperation) throw new Error("client_rotation_pending");
+        const token = readServiceApiTokenState();
+        if (token.kind !== "present" || token.fingerprint !== expectedConnection.value.tokenFingerprint) {
+          throw new Error("client_token_changed");
+        }
+      } else if (expectedConnection.kind !== "disconnected" || readClientConnectionState().kind !== "disconnected") {
+        throw new Error("client_connection_changed");
+      }
+      if (JSON.stringify(current.claudeCode?.desktopProfile) !== JSON.stringify(expectedProfile)) {
+        throw new Error("desktop_profile_changed");
+      }
+      const changed = JSON.stringify(current.claudeCode?.desktopProfile) !== JSON.stringify(profile);
+      if (changed) current.claudeCode = { ...(current.claudeCode ?? {}), desktopProfile: structuredClone(profile) };
+      return { changed, value: undefined };
+    });
+    if (outcome.status === "unavailable") throw new Error("desktop_profile_save_unavailable");
+  }, deps.lifecycleLockDeps);
+}
+
+async function applyConnectedDesktopProfile(
+  mode: Desktop3pConfigMode,
+  connection: Extract<ClientConnectionState, { kind: "connected" }>,
+  deps: ApplyProfileDeps,
+): Promise<{ ok: boolean; path: string; reason?: string; warning?: string }> {
+  try {
+    const token = withClientLifecycleSync(() => withConfigMutationLockSync(() => {
+      assertClientConnectionUnchanged(connection.value);
+      if (connection.value.pendingOperation) throw new Error("client_rotation_pending");
+      const current = readServiceApiTokenState();
+      if (current.kind === "absent") throw new Error("client_token_absent");
+      if (current.kind === "unsafe") throw new Error("client_token_unsafe");
+      if (current.fingerprint !== connection.value.tokenFingerprint) {
+        throw new Error("client_token_mismatch");
+      }
+      const desired = setIntegrationEnabled("claude-desktop", true);
+      if (!desired.ok) throw new Error("desktop_desired_state_write_failed");
+      return current;
+    }), deps.lifecycleLockDeps);
+    const baseUrl = normalizeHubOrigin(connection.value.serverUrl);
+    let snapshot: Awaited<ReturnType<typeof downloadDesktop3pModels>>;
+    try {
+      snapshot = await (deps.downloadDesktop3pModelsImpl ?? downloadDesktop3pModels)(baseUrl, token.token);
+    } catch (error) {
+      return { ok: false, path: "", reason: error instanceof HubClientError ? error.code : "desktop_download_failed" };
+    }
+    const result: DesktopStoreResult = withClientLifecycleSync(held => withConfigMutationLockSync(() => {
+      assertClientConnectionUnchanged(connection.value);
+      const currentToken = readServiceApiTokenState();
+      if (currentToken.kind !== "present" || currentToken.fingerprint !== connection.value.tokenFingerprint) {
+        throw new Error("client_connection_changed");
+      }
+      if (!claudeDesktopIntegrationEnabledNow()) throw new Error("desired_state_changed");
+      if (snapshot.models.length === 0) throw new Error("desktop_unavailable");
+      return (deps.applyRemoteDesktopStoreImpl ?? applyRemoteDesktopStore)(held, {
+        owner: { serverUrl: connection.value.serverUrl, apiKeyId: connection.value.apiKeyId, connectedAt: connection.value.connectedAt },
+        expectedTokenFingerprint: currentToken.fingerprint,
+        baseUrl, apiKey: currentToken.token, mode, models: snapshot.models,
+      });
+    }), deps.lifecycleLockDeps);
+    if (!result.ok) return { ok: false, path: "", reason: `desktop_lifecycle_${result.reason}` };
+    // Policy probes may spawn a process; perform them only after L/C have been released.
+    const policyWarning = claudeDesktopPolicyWarning((deps.probeClaudeDesktopPolicy ?? probeClaudeDesktopPolicy)());
+    const fallbackWarning = result.baselineKind === "standard_fallback"
+      ? "Previous Desktop settings were not recorded. Disconnect will switch this managed profile to standard mode."
+      : undefined;
+    const warning = [fallbackWarning, policyWarning].filter(Boolean).join(" ");
+    return { ok: true, path: result.path ?? "", ...(warning ? { warning } : {}) };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "";
+    return { ok: false, path: "", reason: /^[a-z][a-z0-9_]{1,100}$/.test(message) ? message : "desktop_apply_failed" };
+  }
+}
+
+export async function applyProfile(
+  profile: DesktopProfile | undefined,
   mode: Desktop3pConfigMode,
   deps: ApplyProfileDeps = {},
 ): Promise<{ ok: boolean; path: string; reason?: string; warning?: string }> {
+  try { assertNoClientDisconnectPending(); } catch { return { ok: false, path: "", reason: "client_disconnect_pending" }; }
+  const connection = readClientConnectionState();
+  if (connection.kind === "connected") return applyConnectedDesktopProfile(mode, connection, deps);
+  if (connection.kind !== "disconnected") return { ok: false, path: "", reason: "client_connection_invalid" };
   // Explicit apply is an enable action. Persist intent before any Desktop write
   // so a process crash cannot leave a gateway profile that startup immediately removes.
   const desired = setIntegrationEnabled("claude-desktop", true);
   if (!desired.ok) return { ok: false, path: "", reason: desired.message };
   const config = loadConfig();
   const state = await buildClaudeDesktopState(config, profile);
-  config.claudeCode = { ...(config.claudeCode ?? {}), desktopProfile: state.profile };
-  saveConfigPreservingClaudeCode(config);
+  saveLocalDesktopProfile(state.profile, config.claudeCode?.desktopProfile, connection, deps);
   const live = await (deps.findLiveProxyImpl ?? findLiveProxy)();
+  assertNoClientDisconnectPending();
+  if (readClientConnectionState().kind !== "disconnected") throw new Error("client_connection_changed");
   if (live) {
     // #859: the Desktop alias reverse-map is process-local. Applying through the
     // serving process installs the map there; a local-only write leaves the
@@ -86,7 +185,8 @@ export async function applyProfile(
   // The toggle can persist OFF while fetchAllModels was awaiting (same race the
   // management writers fence). Re-read persisted intent immediately before the
   // writer; a lost race is a discriminated skip, not a write.
-  const { claudeDesktopIntegrationEnabledNow } = await import("../codex/desired-state");
+  assertNoClientDisconnectPending();
+  if (readClientConnectionState().kind !== "disconnected") throw new Error("client_connection_changed");
   if (!claudeDesktopIntegrationEnabledNow()) {
     return { ok: false, path: "", reason: "desired_state_changed" };
   }
@@ -103,8 +203,8 @@ export async function applyProfile(
     mode,
     state.profile,
     nativeContextLimits(config),
+    deps.lifecycleLockDeps,
   );
-  const { claudeDesktopPolicyWarning, probeClaudeDesktopPolicy } = await import("../claude/desktop-policy");
   const policyState = (deps.probeClaudeDesktopPolicy ?? probeClaudeDesktopPolicy)();
   const warning = result.written ? claudeDesktopPolicyWarning(policyState) : undefined;
   return {
@@ -134,12 +234,9 @@ export async function handleClaudeDesktopCommand(argv: string[], deps: ApplyProf
     const parsedMode = parseDesktop3pModeArgs(legacyFlags);
     if ("error" in parsedMode) { console.error(parsedMode.error); return 2; }
     try {
-      const config = loadConfig();
-      const state = await buildClaudeDesktopState(config);
-      const result = await applyProfile(state.profile, parsedMode.mode, deps);
+      const result = await applyProfile(undefined, parsedMode.mode, deps);
       if (!result.ok) {
         console.error(`설정 적용 실패: ${result.reason ?? "unknown error"}`);
-        console.error("프로필은 저장되었지만 Claude Desktop 설정 파일에는 반영되지 않았습니다. 프록시 상태를 확인한 뒤 다시 적용해 주세요.");
         return 1;
       }
       console.log(`Claude Desktop 설정을 적용했습니다: ${result.path}`);
@@ -155,6 +252,17 @@ export async function handleClaudeDesktopCommand(argv: string[], deps: ApplyProf
   }
 
   try {
+    const connection = readClientConnectionState();
+    if (command === "import" && argv.includes("--apply")) assertNoClientDisconnectPending();
+    if (command === "import" && argv.includes("--apply") && connection.kind !== "disconnected") {
+      throw new CliUsageError(connection.kind === "connected"
+        ? "Connected Desktop apply uses the hub profile. Import on the hub, then run ocx claude desktop apply here."
+        : "Client connection state is invalid; refusing import --apply.");
+    }
+    const localView = connection.kind === "connected";
+    if (localView && ["show", "export", "move", "default", "import"].includes(command ?? "")) {
+      console.warn("Local client profile only; connected Desktop apply uses the hub profile.");
+    }
     const config = loadConfig();
     // `status` is API-backed and must NOT build local state first: the whole point of the
     // route the GUI polls (/api/claude-desktop/status) is the applied-vs-desired comparison,
@@ -178,7 +286,7 @@ export async function handleClaudeDesktopCommand(argv: string[], deps: ApplyProf
       const rest = argv.slice(1);
       const wantsJson = takeJsonFlag(rest);
       if (rest.length > 0) throw new CliUsageError("Usage: ocx claude desktop show [--json]");
-      if (wantsJson) console.log(JSON.stringify(state));
+      if (wantsJson) console.log(JSON.stringify(localView ? { ...state, scope: "local" } : state));
       else {
         for (const family of DESKTOP_FAMILIES) {
           console.log(`${family.toUpperCase()}${state.profile.defaults[family] ? ` (default: ${state.profile.defaults[family]})` : ""}`);
@@ -194,8 +302,7 @@ export async function handleClaudeDesktopCommand(argv: string[], deps: ApplyProf
       if (!route || !isFamily(familyRaw) || flags.some(flag => flag !== "--default")) throw new CliUsageError("Usage: ocx claude desktop move <route> <family> [--default]");
       if (!state.models.some(model => model.route === route && model.available)) throw new Error(`현재 사용할 수 없는 모델입니다: ${route}`);
       const profile = moveDesktopRoute(state.profile, route, familyRaw, flags.includes("--default"));
-      config.claudeCode = { ...(config.claudeCode ?? {}), desktopProfile: profile };
-      saveConfigPreservingClaudeCode(config);
+      saveLocalDesktopProfile(profile, config.claudeCode?.desktopProfile, connection, deps);
       console.log(`${route} 모델을 ${familyRaw} 그룹으로 옮겼습니다.`);
       return 0;
     }
@@ -205,8 +312,7 @@ export async function handleClaudeDesktopCommand(argv: string[], deps: ApplyProf
       const route = routeRaw === "none" ? null : routeRaw;
       if (route && !state.models.some(model => model.route === route && model.available)) throw new Error(`현재 사용할 수 없는 모델입니다: ${route}`);
       const profile = setDesktopFamilyDefault(state.profile, familyRaw, route);
-      config.claudeCode = { ...(config.claudeCode ?? {}), desktopProfile: profile };
-      saveConfigPreservingClaudeCode(config);
+      saveLocalDesktopProfile(profile, config.claudeCode?.desktopProfile, connection, deps);
       console.log(`${familyRaw} 기본 모델을 ${route ?? "없음"}으로 지정했습니다.`);
       return 0;
     }
@@ -224,8 +330,11 @@ export async function handleClaudeDesktopCommand(argv: string[], deps: ApplyProf
       if (!source || flags.some(flag => flag !== "--apply")) throw new CliUsageError("Usage: ocx claude desktop import <path> [--apply]");
       const profile = parseDesktopProfile(JSON.parse(readFileSync(resolve(source), "utf8")));
       const reconciled = (await buildClaudeDesktopState(config, profile)).profile;
-      config.claudeCode = { ...(config.claudeCode ?? {}), desktopProfile: reconciled };
-      saveConfigPreservingClaudeCode(config);
+      if (flags.includes("--apply")) assertNoClientDisconnectPending();
+      if (flags.includes("--apply") && readClientConnectionState().kind !== "disconnected") {
+        throw new CliUsageError("Client connection changed; refusing import --apply. Connected Desktop apply uses the hub profile.");
+      }
+      saveLocalDesktopProfile(reconciled, config.claudeCode?.desktopProfile, connection, deps);
       if (flags.includes("--apply")) {
         const result = await applyProfile(reconciled, "static", deps);
         if (!result.ok) { console.error(`프로필은 저장했지만 Desktop 적용에 실패했습니다: ${result.reason ?? "unknown error"}`); return 1; }

package/src/cli/connect.ts

@@ -8,6 +8,8 @@ import {
 } from "../client/connect";
 import { inspectClientRotationRecoveryGate, readClientConnectionState } from "../client/state";
 import { readServiceApiTokenState } from "../lib/service-secrets";
+import type { ClientLifecycleLockDeps } from "../client/lifecycle-lock";
+import { inspectRemoteDesktopStore } from "../claude/desktop-remote-store";
 import type { OcxConnectedClientId } from "../types";
 import {
   CliUsageError,
@@ -22,6 +24,10 @@ import {
   type RuntimeApiDeps,
 } from "./runtime-api";
 
+export interface ClientCommandDeps extends RuntimeApiDeps {
+  lifecycleLockDeps?: ClientLifecycleLockDeps;
+}
+
 export const CONNECT_USAGE = `Usage:
   ocx connect <url> [--management-url <url>]
       (--pairing-code-stdin | --admin-token-stdin)
@@ -52,10 +58,10 @@ export type ClientConnectionStatus = {
   rotation: "clean" | "orphan-cleaned" | "recovery-required" | "unsafe";
 };
 
-export function collectClientConnectionStatus(now = Date.now()): ClientConnectionStatus {
+export function collectClientConnectionStatus(now = Date.now(), lifecycleLockDeps?: ClientLifecycleLockDeps): ClientConnectionStatus {
   const state = readClientConnectionState();
   const tokenState = readServiceApiTokenState();
-  const rotation = inspectClientRotationRecoveryGate(state).kind;
+  const rotation = inspectClientRotationRecoveryGate(state, lifecycleLockDeps).kind;
   let catalog: ClientConnectionStatus["catalog"] = "missing";
   if (existsSync(DEFAULT_CATALOG_PATH)) {
     try {
@@ -124,7 +130,7 @@ function statusLines(status: ClientConnectionStatus): string[] {
   ];
 }
 
-async function runRotate(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+async function runRotate(argv: string[], deps: ClientCommandDeps): Promise<void> {
   const args = [...argv];
   const wantsJson = takeFlag(args, "--json");
   const pairing = takeFlag(args, "--pairing-code-stdin");
@@ -136,13 +142,17 @@ async function runRotate(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   const value = new TextEncoder().encode(await readSecretLine(deps, pairing ? "pairing code" : "admin token"));
   const connection = await rotateConnectedClientKey({
     credential: { kind: pairing ? "pairing-grant" : "admin", value },
-  }, { fetchImpl: deps.fetchImpl });
-  printData({ apiKeyId: connection.apiKeyId, rotation: "committed" }, wantsJson, [
-    `Rotated connected API key ${connection.apiKeyId}; the previous key is no longer admitted.`,
+  }, { fetchImpl: deps.fetchImpl, lifecycleLockDeps: deps.lifecycleLockDeps });
+  const restartRequired = inspectRemoteDesktopStore({ serverUrl: connection.serverUrl, apiKeyId: connection.apiKeyId, connectedAt: connection.connectedAt }).kind !== "absent";
+  printData({ apiKeyId: connection.apiKeyId, rotation: connection.rotationOutcome, restartRequired }, wantsJson, [
+    connection.rotationOutcome === "committed"
+      ? `Rotated connected API key ${connection.apiKeyId}; the previous key is no longer admitted.`
+      : `Rotation rolled back for API key ${connection.apiKeyId}; the previous key was retained or restored.`,
+    ...(restartRequired ? ["Fully quit and reopen Claude Desktop; a running app may still hold the previous credential."] : []),
   ]);
 }
 
-async function runConnect(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+async function runConnect(argv: string[], deps: ClientCommandDeps): Promise<void> {
   const args = [...argv];
   const serverUrl = args.shift();
   if (!serverUrl || serverUrl.startsWith("--")) throw new CliUsageError("hub URL is required", CONNECT_USAGE);
@@ -173,28 +183,28 @@ async function runConnect(argv: string[], deps: RuntimeApiDeps): Promise<void> {
     managementTransport,
     noSync,
     ...(catalogTimeoutSeconds === undefined ? {} : { catalogTimeoutMs: catalogTimeoutSeconds * 1_000 }),
-  }, { fetchImpl: deps.fetchImpl });
+  }, { fetchImpl: deps.fetchImpl, lifecycleLockDeps: deps.lifecycleLockDeps });
   console.log(`Connected to ${connection.serverUrl} as key ${connection.apiKeyId}.`);
 }
 
-async function runRevoke(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+async function runRevoke(argv: string[], deps: ClientCommandDeps): Promise<void> {
   const args = [...argv];
   const wantsJson = takeFlag(args, "--json");
   const admin = takeFlag(args, "--admin-token-stdin");
   if (!admin) throw new CliUsageError("revoke requires --admin-token-stdin", CONNECT_USAGE);
   rejectArgs(args, CONNECT_USAGE, { redactValues: true });
   const value = new TextEncoder().encode(await readSecretLine(deps, "admin token"));
-  const result = await revokeConnectedClientKey({ kind: "admin", value }, { fetchImpl: deps.fetchImpl });
+  const result = await revokeConnectedClientKey({ kind: "admin", value }, { fetchImpl: deps.fetchImpl, lifecycleLockDeps: deps.lifecycleLockDeps });
   printData(result, wantsJson, [`Revoked connected API key ${result.apiKeyId}. Disconnect this client next.`]);
 }
 
-export async function handleConnectCommand(argv: string[], deps: RuntimeApiDeps = {}): Promise<number> {
+export async function handleConnectCommand(argv: string[], deps: ClientCommandDeps = {}): Promise<number> {
   return runCliAction(async () => {
     if (argv[0] === "status") {
       const args = argv.slice(1);
       const wantsJson = takeFlag(args, "--json");
       rejectArgs(args, CONNECT_USAGE, { redactValues: true });
-      const status = collectClientConnectionStatus();
+      const status = collectClientConnectionStatus(Date.now(), deps.lifecycleLockDeps);
       printData(status, wantsJson, statusLines(status));
       return;
     }
@@ -210,13 +220,13 @@ export async function handleConnectCommand(argv: string[], deps: RuntimeApiDeps
   });
 }
 
-export async function handleDisconnectCommand(argv: string[]): Promise<number> {
+export async function handleDisconnectCommand(argv: string[], deps: Pick<ClientCommandDeps, "lifecycleLockDeps"> = {}): Promise<number> {
   return runCliAction(async () => {
     const args = [...argv];
     const keepCatalog = takeFlag(args, "--keep-catalog");
     const wantsJson = takeFlag(args, "--json");
     rejectArgs(args, DISCONNECT_USAGE, { redactValues: true });
-    const result = await disconnectClient({ keepCatalog });
+    const result = await disconnectClient({ keepCatalog }, deps);
     const payload = {
       ...result,
       revoke: {
@@ -226,6 +236,9 @@ export async function handleDisconnectCommand(argv: string[]): Promise<number> {
     };
     printData(payload, wantsJson, [
       "Disconnected locally; native Codex state was restored.",
+      ...(result.desktopRestoration === "standard_fallback"
+        ? ["Previous Desktop settings were not recorded; the managed profile was switched to standard mode."] : []),
+      ...(result.restartRequired ? ["Fully quit and reopen Claude Desktop; local cleanup cannot revoke an in-memory credential."] : []),
       `The hub key ${result.apiKeyId} is still valid. Revoke it from Integrations → API Keys.`,
     ]);
   });

package/src/cli/dispatch.ts

@@ -14,6 +14,7 @@ import type { CliHead } from "./root";
 import type { ReadyArgs } from "./ready";
 import type { LivenessIo, LiveProxy } from "../server/proxy-liveness";
 import type { OcxConfig } from "../types";
+import type { OwnedIntegrationRefreshOutcome } from "../integrations/owned-refresh";
 import { hasHelpFlag, printSubcommandUsage, printUsage } from "./help";
 import { setIntegrationEnabled, shouldSyncCodexOnStart } from "../codex/desired-state";
 import { syncModelsToCodex } from "../codex/sync";
@@ -387,25 +388,38 @@ const commandRunners: Record<string, CommandRunner> = {
       if (restartDesktopApp) await handleDesktopAppRestart(console);
     }
     // `ocx sync` is a direct CLI path; it does not call the management
-    // `/api/sync` route. Refresh the already-connected MCode block here too,
+    // `/api/sync` route. Refresh already-connected file integrations here too,
     // after Codex has published the catalog that supplies its capabilities.
-    if (synced.status !== "refused" && live) {
+    if (synced.status !== "refused") {
+      const results: OwnedIntegrationRefreshOutcome[] = [];
+      if (live) {
+        try {
+          const config = deps.loadConfig();
+          const { refreshOwnedCatalogIntegrations } = await import("../integrations/catalog-refresh");
+          results.push(...await refreshOwnedCatalogIntegrations({
+            models: async () => {
+              const { loadExportModels } = await import("../server/management/model-rows");
+              return loadExportModels(config);
+            },
+            config,
+            port: live.port,
+          }, ["mcode", "pi"]));
+        } catch (error) {
+          console.warn(`Client integrations were not refreshed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+      }
+      // Even without a live proxy, report why Aside could not sync. Its server
+      // owner is never bypassed, and another client's failure cannot hide it.
       try {
-        const config = deps.loadConfig();
-        const { refreshOwnedIntegration } = await import("../integrations/owned-refresh");
-        const result = await refreshOwnedIntegration({
-          clientId: "mcode",
-          models: async () => {
-            const { loadExportModels } = await import("../server/management/model-rows");
-            return loadExportModels(config);
-          },
-          config,
-          port: live.port,
-        });
-        if (result?.changed) console.log("MCode integration refreshed from the current catalog.");
-        else if (result?.reason) console.warn(`MCode integration was not refreshed: ${result.reason}`);
+        const { refreshAsideProfilesThroughServer } = await import("./aside-profiles");
+        results.push(...await refreshAsideProfilesThroughServer({ findLiveProxy: async () => live }));
       } catch (error) {
-        console.warn(`MCode integration was not refreshed: ${error instanceof Error ? error.message : String(error)}`);
+        console.warn(`Aside profiles were not refreshed: ${error instanceof Error ? error.message : String(error)}`);
+      }
+      for (const result of results) {
+        const label = result.profileId === undefined ? result.client : `${result.client}:${result.profileId}`;
+        if (result.changed) console.log(`${label} integration refreshed from the current catalog.`);
+        else if (result.reason) console.warn(`${label} integration was not refreshed: ${result.reason}${result.residual ? " Recovery did not finish." : ""}${result.snapshotPath ? ` Backup: ${result.snapshotPath}` : ""}`);
       }
     }
     return code;

package/src/cli/export-command.ts

@@ -171,12 +171,14 @@ export async function handleExportCommand(argv: string[], deps: ExportCommandDep
     rejectArgs(args, USAGE);
 
     const spec = EXPORT_CLIENTS[client];
-    const config = (deps.configImpl ?? loadConfig)();
     const root = await runtimeBaseUrl(deps);
     const rows = await runtimeRequest<ExportProxyModelRow[]>("/api/models", {}, { ...deps, baseUrl: root });
     if (!Array.isArray(rows)) {
       throw new RuntimeApiError("Management API returned an unexpected /api/models payload.", 502, rows);
     }
+    // Discovery can persist pending -> ready selection. Read from the caller's
+    // config source after the response, rather than filtering with a stale snapshot.
+    const config = (deps.configImpl ?? loadConfig)();
     const models = exportModelsFromProxyRows(rows, config);
     // The text is the client's OWN format — YAML, TOML and JSON5 clients would
     // otherwise receive a JSON rendering their parser reads differently.

package/src/cli/index.ts

@@ -106,7 +106,7 @@ function reportShellHookFailure(result: { state: "installed" | "absent" | "faile
 }
 
 
-import { removeOwnedConfigState } from "../lib/config-ownership";
+import { removeOwnedConfigAfterDesktopCleanup } from "./uninstall-client-state";
 import { withProcessRuntimeProvenance } from "../lib/bun-runtime";
 import { selfLaunchArgv } from "../lib/self-launch-argv";
 import { initializeNodeLauncherContext } from "./launcher-context";
@@ -459,8 +459,8 @@ async function handleStart(options: { block?: boolean } = {}) {
   reportShellHookFailure(reconcileShellHook(systemEnv.injected));
   await maybeShowStarPrompt(); // once-only Yes/No GitHub-star prompt on first interactive start
   // Codex sync owns the ready/failed verdict, but its successful transition is
-  // deferred until the best-effort Claude roster reconciliation settles. This
-  // keeps /readyz closed across both startup writes without making an optional
+  // deferred until the best-effort Claude roster and Desktop registry settle. This
+  // keeps /readyz closed across startup initialization without making an optional
   // Claude integration failure prevent the proxy from starting.
   const startupSync = await reconcileClientStartupBeforeReady(
     readinessGate,
@@ -468,6 +468,29 @@ async function handleStart(options: { block?: boolean } = {}) {
     () => systemEnv.injected
       ? Promise.resolve(null)
       : syncClaudeAgentDefsAtProxyStartup(config, port),
+    async () => {
+      try {
+        const { fetchAllModels } = await import("../server/management-api");
+        const { desktopVisibleNativeSlugs } = await import("../codex/catalog");
+        const { resolveCodexModelEntitlements } = await import("../codex/model-entitlements");
+        const { buildDesktopDiscoveryInputs } = await import("../claude/desktop-discovery-inputs");
+        const [models, modelEntitlements] = await Promise.all([
+          fetchAllModels(config),
+          resolveCodexModelEntitlements(config, { clientVersion: null }),
+        ]);
+        const inputs = buildDesktopDiscoveryInputs({
+          config, models, modelEntitlements,
+          desktopNativeCandidates: desktopVisibleNativeSlugs(config),
+        });
+        buildDesktop3pRegistry(
+          inputs.nativeSlugs, inputs.routedModels,
+          config.claudeCode?.desktopProfile, inputs.nativeContextCap,
+        );
+      } catch {
+        // Best-effort; model discovery can rebuild it. Never reflect credential or provider errors.
+        console.warn("[opencodex] Claude Desktop model registry could not be initialized at startup.");
+      }
+    },
   );
   if (!startupSync.ran) console.log("   Codex integration OFF; startup left Codex native.");
   // #1046: one warning per startup, after BOTH writes. The server's cache
@@ -482,17 +505,6 @@ async function handleStart(options: { block?: boolean } = {}) {
   if (!currentExternalCodexModelProvider() && !shouldInjectApiAuthHeader(config) && config.syncResumeHistory !== false) {
     historyGuardian = startHistoryMigrationGuardian();
   }
-  // Build Desktop 3P alias registry so inbound claude-opus-4-8-{code} aliases (and legacy claude-opus-4-{code}) decode correctly.
-  try {
-    const { fetchAllModels } = await import("../server/management-api");
-    const { visibleNativeSlugs, filterCatalogVisibleModels } = await import("../codex/catalog");
-    const models = filterCatalogVisibleModels(await fetchAllModels(config), config);
-    buildDesktop3pRegistry(
-      [...visibleNativeSlugs(config)],
-      models.map(m => ({ provider: m.provider, id: m.id, contextWindow: m.contextWindow })),
-      config.claudeCode?.desktopProfile,
-    );
-  } catch { /* best-effort — registry rebuilds on first /v1/models call */ }
   // Grok Build auto-registration: additive fenced block in ~/.grok/config.toml so an installed
   // grok CLI can pick opencodex-routed models without manual config. No-op when ~/.grok is
   // absent or the bind is non-loopback; removed again by stop/eject/uninstall/shutdown.
@@ -1268,8 +1280,8 @@ async function handleUninstall() {
   }
 
   if (failures.length === 0) {
-    await runStep("opencodex config removed", () => {
-      const result = removeOwnedConfigState(getConfigDir());
+    await runStep("opencodex config removed", async () => {
+      const result = await removeOwnedConfigAfterDesktopCleanup(observed);
       if (result.status === "absent") return false;
       if (result.status === "removed") return true;
       const residual = result.residualPaths.length > 0