@bitkyc08/opencodex 2.10.2 → 2.11.0

package/src/server/lifecycle.ts

@@ -292,6 +292,42 @@ export function getServerListenPort(): number | undefined {
  * ordinary drain's finally block; both callers must observe the same stop result
  * before any replacement process is allowed to bind the port.
  */
+/**
+ * Run every shutdown step, then report whether any of them failed.
+ *
+ * Extracted from `startServer`'s composite `stop` because the two properties it has to hold
+ * pull in opposite directions and neither is testable in place:
+ *
+ * - Cleanup COMPLETES. A listener whose stop rejects cannot prevent the other listener, or the
+ *   native lifecycle release, from running.
+ * - Failure PROPAGATES. `stopServerListener` deliberately surfaces a stop rejection so every
+ *   caller sees the same result before a replacement binds the port. Swallowing it would let
+ *   `drainAndShutdown` report success while a socket is still held.
+ *
+ * `always` runs after the listeners regardless of their outcome, and its own failure joins the
+ * reported set rather than replacing it.
+ */
+export async function runListenerShutdown(
+  steps: Array<() => Promise<void>>,
+  always: () => Promise<void>,
+): Promise<void> {
+  const failures: unknown[] = [];
+  for (const step of steps) {
+    try {
+      await step();
+    } catch (error) {
+      failures.push(error);
+    }
+  }
+  try {
+    await always();
+  } catch (error) {
+    failures.push(error);
+  }
+  if (failures.length === 1) throw failures[0];
+  if (failures.length > 1) throw new AggregateError(failures, "listener shutdown failed");
+}
+
 export function stopServerListener(
   server: ReturnType<typeof Bun.serve> | undefined = _serverRef,
 ): Promise<void> {

package/src/server/management/agent-settings-routes.ts

@@ -9,6 +9,7 @@ import {
   isValidProviderName,
   loadConfig,
   multiAgentGuidanceEnabled,
+  mutatePersistedConfig,
   providerBaseUrlConfigError,
   providerHeadersConfigError,
   saveConfigPreservingClaudeCode,
@@ -70,6 +71,49 @@ let grokApplyTestHooks: { now?: () => number; run?: () => Promise<unknown> } | n
 
 class GrokApplyBusyError extends Error {}
 
+/**
+ * Mirror a durable desired-state transition onto the long-lived server snapshot.
+ *
+ * `setIntegrationEnabled` writes DISK only. The server reuses one `config` object
+ * for every request, so leaving it stale makes the native GET report the opposite
+ * of what was just persisted, and makes any later whole-snapshot save (the Desktop
+ * profile PUT does exactly that) write the stale value back over the transition.
+ * ON is the ABSENCE of the key, matching `setIntegrationEnabled`'s on-disk shape.
+ */
+function mirrorDesiredEnabledOntoSnapshot(config: OcxConfig, client: "claude-desktop", enabled: boolean): void {
+  const integrations = { ...(config.clientIntegrations ?? {}) };
+  if (enabled) delete integrations[client];
+  else integrations[client] = false;
+  if (Object.keys(integrations).length === 0) delete config.clientIntegrations;
+  else config.clientIntegrations = integrations;
+}
+
+/**
+ * Persist ONLY `claudeCode.desktopProfile`, field-scoped, against the CURRENT
+ * on-disk config.
+ *
+ * `saveConfigPreservingClaudeCode(ctx.config)` writes the whole long-lived server
+ * snapshot. On the apply path that snapshot still carries the `clientIntegrations`
+ * it was loaded with, so a save right after `setIntegrationEnabled("claude-desktop",
+ * true)` carried the stale OFF back over the enable and made the route cancel its
+ * own apply. Mutating one field under the config-mutation lock cannot regress an
+ * unrelated key another writer just committed.
+ */
+function persistDesktopProfileField(
+  config: OcxConfig,
+  desktopProfile: NonNullable<OcxConfig["claudeCode"]>["desktopProfile"],
+): { ok: true } | { ok: false; reason: "missing" | "invalid" | "conflict" } {
+  const outcome = mutatePersistedConfig(persisted => {
+    persisted.claudeCode = { ...(persisted.claudeCode ?? {}), desktopProfile };
+    return { changed: true, value: true };
+  });
+  // Only mirror into memory once the durable write actually landed; an
+  // `unavailable` outcome must not leave the snapshot claiming a saved profile.
+  if (outcome.status === "unavailable") return { ok: false, reason: outcome.reason };
+  config.claudeCode = { ...(config.claudeCode ?? {}), desktopProfile };
+  return { ok: true };
+}
+
 export function grokApplyFlightSnapshot(): { currentBytes: number; highWaterBytes: number; active: number } {
   return {
     currentBytes: grokApplyFlight?.bytes ?? 0,
@@ -130,23 +174,38 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
   /** Best-effort Desktop 3P config auto-reconcile when providers change. */
   async function autoApplyDesktopBestEffort(): Promise<void> {
     try {
-      if (config.claudeCode?.desktopAutoApply === false) return;
-      if (!config.claudeCode?.desktopProfile) return;
-      const { writeDesktop3pConfig } = await import("../../claude/desktop-3p");
+      const { claudeDesktopIntegrationEnabled } = await import("../../codex/desired-state");
+      const admitted = loadConfig();
+      if (!claudeDesktopIntegrationEnabled(admitted)) return;
+      if (admitted.claudeCode?.desktopAutoApply === false) return;
+      if (!admitted.claudeCode?.desktopProfile) return;
+      const { inspectDesktop3pConfigLibrary, writeDesktop3pConfig } = await import("../../claude/desktop-3p");
+      const beforeKind = inspectDesktop3pConfigLibrary({
+        appliedFingerprint: admitted.claudeCode.desktopProfile.appliedFingerprint ?? null,
+      }).kind;
+      if (["not_installed", "no_owned_state", "foreign", "unsafe", "broken"].includes(beforeKind)) return;
       const { filterCatalogVisibleModels, desktopVisibleNativeSlugs } = await import("../../codex/catalog");
-      const allModels = await fetchAllModels(config);
-      const routed = filterCatalogVisibleModels(allModels, config).map(m => ({ provider: m.provider, id: m.id, contextWindow: m.contextWindow }));
-      const result = writeDesktop3pConfig(
-        config.port ?? 10100,
-        [...desktopVisibleNativeSlugs(config)],
+      const allModels = await (deps.fetchAllModels ?? fetchAllModels)(admitted);
+      const current = loadConfig();
+      // This is the real guard: the catalog await admits a concurrent explicit OFF.
+      if (!claudeDesktopIntegrationEnabled(current)) return;
+      if (current.claudeCode?.desktopAutoApply === false || !current.claudeCode?.desktopProfile) return;
+      const afterKind = inspectDesktop3pConfigLibrary({
+        appliedFingerprint: current.claudeCode.desktopProfile.appliedFingerprint ?? null,
+      }).kind;
+      if (["not_installed", "no_owned_state", "foreign", "unsafe", "broken"].includes(afterKind)) return;
+      const routed = filterCatalogVisibleModels(allModels, current).map(m => ({ provider: m.provider, id: m.id, contextWindow: m.contextWindow }));
+      const result = (deps.writeDesktop3pConfig ?? writeDesktop3pConfig)(
+        current.port ?? 10100,
+        [...desktopVisibleNativeSlugs(current)],
         routed,
-        config.apiKeys?.[0]?.key,
+        current.apiKeys?.[0]?.key,
         "static",
-        config.claudeCode.desktopProfile,
+        current.claudeCode.desktopProfile,
       );
       if (result.written && result.fingerprint) {
-        config.claudeCode = { ...config.claudeCode, desktopProfile: { ...config.claudeCode.desktopProfile, appliedFingerprint: result.fingerprint, appliedAt: new Date().toISOString() } };
-        saveConfigPreservingClaudeCode(config);
+        current.claudeCode = { ...current.claudeCode, desktopProfile: { ...current.claudeCode.desktopProfile, appliedFingerprint: result.fingerprint, appliedAt: new Date().toISOString() } };
+        saveConfigPreservingClaudeCode(current);
       }
     } catch { /* best-effort */ }
   }
@@ -700,6 +759,14 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
   }
   if (url.pathname === "/api/claude-desktop/apply" && req.method === "POST") {
     try {
+      const { setIntegrationEnabled, claudeDesktopIntegrationEnabled } = await import("../../codex/desired-state");
+      const desired = setIntegrationEnabled("claude-desktop", true);
+      if (!desired.ok) return jsonResponse({ error: desired.message }, desired.retryable ? 409 : 500);
+      // Disk now says ON; the reused server snapshot must agree, or the native
+      // GET reports OFF and a later whole-snapshot save undoes this transition.
+      mirrorDesiredEnabledOntoSnapshot(config, "claude-desktop", true);
+      // Disk now says ON; the reused server snapshot must agree, or the native
+      // GET reports OFF and a later whole-snapshot save undoes this transition.
       // #859: the CLI delegates here so the registry is built in the serving
       // process. Accept an optional mode; default stays static for back-compat.
       let mode: "static" | "hybrid" | "discovery" = "static";
@@ -734,8 +801,19 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
         }
       }
       const state = await buildClaudeDesktopState(config, profileOverride);
-      config.claudeCode = { ...(config.claudeCode ?? {}), desktopProfile: state.profile };
-      saveConfigPreservingClaudeCode(config);
+      // `setIntegrationEnabled` above wrote desired ON to DISK; it does not touch
+      // this long-lived server snapshot. Saving the snapshot wholesale would carry
+      // its stale `clientIntegrations` back over that write and turn the enable
+      // action into an immediate self-cancelling OFF — the guard below would then
+      // refuse the apply it was asked to perform. Persist ONLY the profile field.
+      const profileSaved = persistDesktopProfileField(config, state.profile);
+      if (!profileSaved.ok) {
+        return jsonResponse({
+          error: `Claude Desktop profile could not be saved (${profileSaved.reason}); nothing was applied.`,
+          saved: false,
+          applied: false,
+        }, profileSaved.reason === "conflict" ? 409 : 500);
+      }
       const { writeDesktop3pConfig } = await import("../../claude/desktop-3p");
       const { desktopVisibleNativeSlugs } = await import("../../codex/catalog");
       const routed = state.models
@@ -744,19 +822,47 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
           const slash = model.route.indexOf("/");
           return { provider: model.route.slice(0, slash), id: model.route.slice(slash + 1), contextWindow: model.contextWindow };
         });
-      const result = writeDesktop3pConfig(
-        Number(url.port) || config.port,
-        [...desktopVisibleNativeSlugs(config)],
+      // State construction can await catalog work; never write from the stale
+      // config captured before that await if another request turned Desktop off.
+      const latest = loadConfig();
+      if (!claudeDesktopIntegrationEnabled(latest)) {
+        return jsonResponse({
+          error: "Claude Desktop apply was cancelled because the desired state changed to off.",
+          code: "claude_desktop_apply_skipped",
+          reason: "desired_state_changed",
+          desiredEnabled: false,
+          saved: true,
+          applied: false,
+        }, 409);
+      }
+      const result = (deps.writeDesktop3pConfig ?? writeDesktop3pConfig)(
+        Number(url.port) || latest.port,
+        [...desktopVisibleNativeSlugs(latest)],
         routed,
-        config.apiKeys?.[0]?.key,
+        latest.apiKeys?.[0]?.key,
         mode,
         state.profile,
       );
       if (!result.written) return jsonResponse({ error: result.reason ?? "Claude Desktop apply failed", saved: true, path: result.path }, 500);
       // Persist applied fingerprint + timestamp so GUI can show saved-vs-applied state.
       if (result.fingerprint) {
-        config.claudeCode = { ...(config.claudeCode ?? {}), desktopProfile: { ...state.profile, appliedFingerprint: result.fingerprint, appliedAt: new Date().toISOString() } };
-        saveConfigPreservingClaudeCode(config);
+        // The Desktop write already landed, so a failed bookkeeping save is not
+        // an apply failure: report the miss instead of claiming a clean apply.
+        const marked = persistDesktopProfileField(config, {
+          ...state.profile,
+          appliedFingerprint: result.fingerprint,
+          appliedAt: new Date().toISOString(),
+        });
+        if (!marked.ok) {
+          return jsonResponse({
+            ok: true,
+            applied: true,
+            saved: false,
+            path: result.path,
+            fingerprint: result.fingerprint,
+            warning: `Claude Desktop was applied, but the applied marker was not saved (${marked.reason}).`,
+          });
+        }
       }
       return jsonResponse({ ok: true, saved: true, applied: true, path: result.path, fingerprint: result.fingerprint });
     } catch (error) {
@@ -767,47 +873,32 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
   // Desktop applied-state + health status.
   if (url.pathname === "/api/claude-desktop/status" && req.method === "GET") {
     try {
-      const { readFileSync: readFile, existsSync } = await import("node:fs");
-      const { createHash } = await import("node:crypto");
-      const { join } = await import("node:path");
-      const { resolveDesktop3pConfigLibraryPath } = await import("../../claude/desktop-3p");
-      const libraryPath = resolveDesktop3pConfigLibraryPath();
-      const metaPath = join(libraryPath, "_meta.json");
-      let onDiskFingerprint: string | null = null;
-      let configPath: string | null = null;
-      // Desktop serves ONLY the profile named by _meta.json's appliedId, so an
-      // opencodex entry that merely EXISTS does not mean Desktop is using it.
-      // null = undeterminable (no metadata / unreadable / no appliedId).
-      let activeProfile: boolean | null = null;
-      if (existsSync(metaPath)) {
-        try {
-          const meta = JSON.parse(readFile(metaPath, "utf8"));
-          const entry = Array.isArray(meta.entries) ? meta.entries.find((e: { name?: string }) => e?.name === "opencodex") : undefined;
-          const appliedId = typeof meta.appliedId === "string" ? meta.appliedId : null;
-          // A readable appliedId with no opencodex entry is a KNOWN false, not unknown.
-          activeProfile = appliedId === null ? null : (entry?.id ? appliedId === entry.id : false);
-          if (entry?.id) {
-            configPath = join(libraryPath, `${entry.id}.json`);
-            if (existsSync(configPath)) {
-              const onDisk = readFile(configPath, "utf8");
-              onDiskFingerprint = createHash("sha256").update(onDisk).digest("hex").slice(0, 16);
-            }
-          }
-        } catch { /* unreadable metadata */ }
-      }
-      const savedFingerprint = config.claudeCode?.desktopProfile?.appliedFingerprint ?? null;
-      const appliedAt = config.claudeCode?.desktopProfile?.appliedAt ?? null;
-      const stale = savedFingerprint !== null && onDiskFingerprint !== null && savedFingerprint !== onDiskFingerprint;
+      const { claudeDesktopIntegrationEnabled } = await import("../../codex/desired-state");
+      const { inspectDesktop3pConfigLibrary } = await import("../../claude/desktop-3p");
+      const persisted = loadConfig();
+      const savedFingerprint = persisted.claudeCode?.desktopProfile?.appliedFingerprint ?? null;
+      const observed = inspectDesktop3pConfigLibrary({ appliedFingerprint: savedFingerprint });
+      const desiredEnabled = claudeDesktopIntegrationEnabled(persisted);
+      const applied = observed.kind === "gateway_ours" || observed.kind === "gateway_drifted";
+      const stale = observed.kind === "gateway_drifted";
       const { getDesktopHealth } = await import("../../claude/desktop-health");
       const health = getDesktopHealth();
       return jsonResponse({
-        applied: savedFingerprint !== null,
-        appliedAt,
+        desiredEnabled,
+        installed: observed.kind !== "not_installed",
+        observedKind: observed.kind,
+        applied,
+        appliedAt: persisted.claudeCode?.desktopProfile?.appliedAt ?? null,
         savedFingerprint,
-        onDiskFingerprint,
-        configPath,
+        onDiskFingerprint: observed.fingerprint ?? null,
+        configPath: observed.selectedProfilePath,
         stale,
-        activeProfile,
+        // Tri-state by ID match, independent of profile health: null =
+        // undeterminable (no/unreadable metadata or no appliedId); a readable
+        // appliedId with no owned entry is a KNOWN false. Predates the inspector.
+        activeProfile: observed.ownedProfileActive,
+        drift: desiredEnabled ? !applied || stale : applied || observed.kind === "unsafe",
+        driftReason: desiredEnabled ? (!applied ? "desired_on_not_current" : stale ? "profile_drift" : null) : (applied ? "desired_off_gateway_selected" : null),
         health,
       });
     } catch (error) {

package/src/server/management/config-routes.ts

@@ -261,11 +261,16 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
   if (url.pathname === "/api/sync" && req.method === "POST") {
     const { syncModelsToCodex } = await import("../../codex/sync");
     const { attachStaleAppServerHint } = await import("../../codex/app-server-processes");
-    const result = await syncModelsToCodex(undefined, config, null);
+    const { readRuntimePort, loadConfig } = await import("../../config");
+    // Never use the server-captured startup object for a durable integration
+    // decision. A toggle may have persisted while this process was gathering.
+    const runtime = readRuntimePort(process.pid);
+    const result = await syncModelsToCodex(runtime?.port, loadConfig(), null);
+    const status = result.status === "refused" ? 409 : (result.status === "skipped" || result.ok ? 200 : 500);
     return jsonResponse({
       ...attachStaleAppServerHint(result),
       ...(result.ok ? {} : { error: result.message }),
-    }, result.ok ? 200 : 500);
+    }, status);
   }
 
   if (url.pathname === "/api/update/check" && req.method === "GET") {

package/src/server/management/context.ts

@@ -4,6 +4,7 @@ import type { StartupInstallAction } from "../startup-action-control";
 import type { ManagementPrincipal } from "../management-auth";
 import type { CatalogModel } from "../../codex/catalog";
 import type { injectGrokConfig } from "../../grok/inject";
+import type { removeDesktop3pStandardPivot, writeDesktop3pConfig } from "../../claude/desktop-3p";
 import type { RuntimePortState } from "../../config";
 import type { CatalogDisposition, ConvergeCodex } from "../../codex/convergence-types";
 
@@ -31,6 +32,9 @@ export interface ManagementApiDeps {
    * tests). Production leaves this unset and uses the real writer.
    */
   injectGrokConfig?: typeof injectGrokConfig;
+  /** Desktop mutation seams keep route tests inside temporary config libraries. */
+  removeDesktop3pStandardPivot?: typeof removeDesktop3pStandardPivot;
+  writeDesktop3pConfig?: typeof writeDesktop3pConfig;
   /**
    * Runtime-state seam: the fence must name the host/port the RUNNING process
    * bound (agent-settings-routes.ts:99-103 pattern), and a test must not depend