@iislee/opencodex 2.11.0 → 2.31.0

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

@@ -1,7 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { readFileSync } from "node:fs";
 import type { CatalogModel } from "../../codex/catalog";
-import { catalogModelSlug, invalidateCodexModelsCache, nativeModelRows, uniqueCatalogModelsForPublicList } from "../../codex/catalog";
+import { catalogModelSlug, invalidateCodexModelsCache, nativeContextLimits, nativeModelRows, uniqueCatalogModelsForPublicList } from "../../codex/catalog";
 import {
   DEFAULT_SUBAGENT_MODELS,
   codexAutoStartEnabled,
@@ -9,6 +9,7 @@ import {
   isValidProviderName,
   loadConfig,
   multiAgentGuidanceEnabled,
+  mutatePersistedConfig,
   providerBaseUrlConfigError,
   providerHeadersConfigError,
   saveConfigPreservingClaudeCode,
@@ -30,7 +31,7 @@ import { deriveProviderPresets } from "../../providers/derive";
 import { providerCodexAccountMode } from "../../providers/registry";
 import { routedSlug, slugEquals } from "../../providers/slug-codec";
 import { clearProviderQuotaCache, fetchProviderQuotaReports } from "../../providers/quota";
-import { isCanonicalOpenAiForwardProvider } from "../../providers/openai-tiers";
+import { isCanonicalOpenAiForwardProvider, OPENAI_CODEX_PROVIDER_ID } from "../../providers/openai-tiers";
 import { clearThreadAccountMap } from "../../codex/routing";
 import { primeCodexPoolQuotas } from "../../codex/auth-api";
 import { DEFAULT_PROVIDER_CONTEXT_CAP, globalContextCapValue, providerContextCap, providerContextCaps, setAllProviderContextCaps, setGlobalContextCapValue, setProviderContextCap } from "../../providers/context-cap";
@@ -50,6 +51,16 @@ import {
   type DebugFlag,
 } from "../../lib/debug-settings";
 import type { OcxClaudeCodeConfig, OcxConfig, OcxCustomModel, OcxProviderConfig } from "../../types";
+import {
+  visionCandidateRows,
+  visionDescriberIsProvablyBlind,
+  visionDescriberRejection,
+} from "./vision-sidecar-options";
+import {
+  webSearchCandidateRows,
+  webSearchModelIsRejected,
+  webSearchModelRejection,
+} from "./web-search-sidecar-options";
 import { drainAndShutdown } from "../lifecycle";
 import { filterRequestLogs, getRequestLogEntries, type RequestLogEntry } from "../request-log";
 import { estimateComboCost, estimateRequestCost, normalizeCostTokens, tokensPerSecond } from "../../usage/cost";
@@ -59,7 +70,7 @@ import { applySystemEnvToggle } from "../system-env";
 
 import { isPlainRecord, parseDebugLogQuery, tokPerSecondResult, unavailableCostReason, costResult, requestLogDto, stripRegistryOnlyStaticHeaders, fetchAllModels, fetchGrokCandidateModels, buildClaudeDesktopState } from "./shared";
 import type { MetricUnavailableReason, TokPerSecondResult, CostEstimateReason, CostResult, MetricSource } from "./shared";
-import { readManagementJsonBody, rethrowManagementBodyTooLarge } from "./body";
+import { readManagementJsonBody, readOptionalManagementJsonBody, rethrowManagementBodyTooLarge } from "./body";
 
 const GROK_APPLY_JOIN_MS = 120_000;
 export const GROK_APPLY_TERMINAL_MS = 10 * 60_000;
@@ -70,6 +81,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,
@@ -125,28 +179,44 @@ export function setGrokApplyFlightTestHooks(
 import type { ManagementContext } from "./context";
 
 export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise<Response | null> {
-  const { req, url, config, deps, refreshCodexCatalogBestEffort, syncClaudeAgentDefsBestEffort } = ctx;
+  const { req, url, config, deps, convergeCodexCatalog, syncClaudeAgentDefsBestEffort } = ctx;
 
   /** 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,
+        nativeContextLimits(current),
       );
       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 */ }
   }
@@ -160,6 +230,7 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
     const {
       isMultiAgentV2Enabled, hasAgentsMaxThreads, getLogicalMaxThreads,
       getAgentsEnabled, getAgentsMaxDepth, getSubagentDeveloperInstructions,
+      getMultiAgentModeHintText,
     } = await import("../../codex/features");
     const enabled = isMultiAgentV2Enabled();
     return jsonResponse({
@@ -167,9 +238,11 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
       agentsMaxThreadsConflict: enabled && hasAgentsMaxThreads(),
       maxConcurrentThreadsPerSession: getLogicalMaxThreads(),
       multiAgentMode: config.multiAgentMode ?? "default",
+      keepNativeChatGptOnV1: config.keepNativeChatGptOnV1 === true,
       agentsEnabled: getAgentsEnabled(),
       agentsMaxDepth: getAgentsMaxDepth(),
       subagentDeveloperInstructions: getSubagentDeveloperInstructions(),
+      multiAgentModeHintText: getMultiAgentModeHintText(),
       // max_depth is V1-only upstream; this is the global-flag statement, derived
       // server-side so no client can present it as an effective V2 limit.
       agentsMaxDepthAppliesWhenV2Disabled: !enabled,
@@ -180,24 +253,31 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
       enabled?: unknown;
       maxConcurrentThreadsPerSession?: unknown;
       multiAgentMode?: unknown;
+      keepNativeChatGptOnV1?: unknown;
       agentsEnabled?: unknown;
       agentsMaxDepth?: unknown;
       subagentDeveloperInstructions?: unknown;
+      multiAgentModeHintText?: unknown;
     };
     try { body = await readManagementJsonBody(req); } catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid JSON body" }, 400); }
     const wantsFlag = body.enabled !== undefined;
     const wantsThreads = body.maxConcurrentThreadsPerSession !== undefined;
     const wantsMode = body.multiAgentMode !== undefined;
+    const wantsKeepNative = body.keepNativeChatGptOnV1 !== undefined;
     const wantsAgentsEnabled = body.agentsEnabled !== undefined;
     const wantsMaxDepth = body.agentsMaxDepth !== undefined;
     const wantsSubagentInstructions = body.subagentDeveloperInstructions !== undefined;
-    if (!wantsFlag && !wantsThreads && !wantsMode && !wantsAgentsEnabled && !wantsMaxDepth && !wantsSubagentInstructions) {
-      return jsonResponse({ error: "body must set enabled, multiAgentMode, maxConcurrentThreadsPerSession, agentsEnabled, agentsMaxDepth, and/or subagentDeveloperInstructions" }, 400);
+    const wantsModeHintText = body.multiAgentModeHintText !== undefined;
+    if (!wantsFlag && !wantsThreads && !wantsMode && !wantsKeepNative && !wantsAgentsEnabled && !wantsMaxDepth && !wantsSubagentInstructions && !wantsModeHintText) {
+      return jsonResponse({ error: "body must set enabled, multiAgentMode, keepNativeChatGptOnV1, maxConcurrentThreadsPerSession, agentsEnabled, agentsMaxDepth, subagentDeveloperInstructions, and/or multiAgentModeHintText" }, 400);
     }
     if (wantsFlag && typeof body.enabled !== "boolean") return jsonResponse({ error: "body.enabled must be a boolean" }, 400);
     if (wantsMode && body.multiAgentMode !== "v1" && body.multiAgentMode !== "default" && body.multiAgentMode !== "v2") {
       return jsonResponse({ error: "body.multiAgentMode must be 'v1', 'default', or 'v2'" }, 400);
     }
+    if (wantsKeepNative && typeof body.keepNativeChatGptOnV1 !== "boolean") {
+      return jsonResponse({ error: "body.keepNativeChatGptOnV1 must be a boolean" }, 400);
+    }
     if (wantsThreads && (typeof body.maxConcurrentThreadsPerSession !== "number" || !Number.isInteger(body.maxConcurrentThreadsPerSession) || body.maxConcurrentThreadsPerSession < 1)) {
       return jsonResponse({ error: "body.maxConcurrentThreadsPerSession must be an integer >= 1" }, 400);
     }
@@ -216,6 +296,14 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
     if (wantsSubagentInstructions && body.subagentDeveloperInstructions !== null && typeof body.subagentDeveloperInstructions !== "string") {
       return jsonResponse({ error: "body.subagentDeveloperInstructions must be a string or null" }, 400);
     }
+    // null unsets the upstream key (effort-derived policy resumes); an empty/whitespace
+    // string is rejected because codex-rs treats any present hint as an override that
+    // suppresses even the Ultra-derived Proactive message (Option<String>, no blank
+    // special-case in effective_multi_agent_mode).
+    if (wantsModeHintText && body.multiAgentModeHintText !== null
+        && (typeof body.multiAgentModeHintText !== "string" || body.multiAgentModeHintText.trim().length === 0)) {
+      return jsonResponse({ error: "body.multiAgentModeHintText must be a non-empty string or null" }, 400);
+    }
     const mode = wantsMode ? body.multiAgentMode as "v1" | "default" | "v2" : undefined;
     const modeFlag = mode === "v2" ? true : mode === "v1" ? false : undefined;
     if (wantsFlag && modeFlag !== undefined && body.enabled !== modeFlag) {
@@ -224,21 +312,26 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
     const {
       isMultiAgentV2Enabled, hasAgentsMaxThreads, getLogicalMaxThreads, transitionMultiAgentV2,
       getAgentsEnabled, getAgentsMaxDepth, getSubagentDeveloperInstructions,
-      setAgentsEnabled, setAgentsMaxDepth, setSubagentDeveloperInstructions,
+      getMultiAgentModeHintText, probeCodexSupportsModeHint, setAgentsEnabled, setAgentsMaxDepth,
+      setSubagentDeveloperInstructions, setMultiAgentModeHintText, MODE_HINT_UNSUPPORTED_ERROR,
     } = await import("../../codex/features");
+    // Probe the capability before any combined-request mutation. The scalar writer
+    // repeats this check, but doing it here prevents an earlier flag/mode/agents
+    // write from landing before an unsupported runtime returns 502.
+    if (wantsModeHintText && body.multiAgentModeHintText !== null
+        && probeCodexSupportsModeHint() === false) {
+      return jsonResponse({
+        error: `writing multiAgentModeHintText failed: ${MODE_HINT_UNSUPPORTED_ERROR}`,
+      }, 502);
+    }
     const warnings: string[] = [];
     const requestedFlag = wantsFlag ? body.enabled as boolean : modeFlag;
     if (requestedFlag !== undefined || wantsThreads) {
-      const targetFlag = requestedFlag ?? isMultiAgentV2Enabled();
-      let toggle = deps.toggleCodexMultiAgentV2;
-      if (!toggle) {
-        const { execFileSync } = await import("node:child_process");
-        const { codexFeaturesInvocation } = await import("../../cli/v2");
-        toggle = (enabled: boolean) => {
-          const inv = codexFeaturesInvocation(enabled ? "enable" : "disable");
-          execFileSync(inv.file, inv.args,
-            { stdio: ["ignore", "pipe", "pipe"], timeout: 15_000, windowsHide: true, ...inv.options });
-        };
+    const targetFlag = requestedFlag ?? isMultiAgentV2Enabled();
+    let toggle = deps.toggleCodexMultiAgentV2;
+    if (!toggle) {
+      const { runCodexFeaturesCommand } = await import("../../cli/v2");
+      toggle = (enabled: boolean) => runCodexFeaturesCommand(enabled ? "enable" : "disable");
       }
       const result = transitionMultiAgentV2(targetFlag, toggle, {
         ...(wantsThreads ? { threadLimit: body.maxConcurrentThreadsPerSession as number } : {}),
@@ -252,6 +345,17 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
       saveConfigPreservingClaudeCode(config);
       warnings.push(`Multi-agent mode set to '${mode}'. Applies to new sessions.`);
     }
+    if (wantsKeepNative) {
+      if (body.keepNativeChatGptOnV1 === true) config.keepNativeChatGptOnV1 = true;
+      else delete config.keepNativeChatGptOnV1;
+      saveConfigPreservingClaudeCode(config);
+      const effectiveMode = mode ?? config.multiAgentMode ?? "default";
+      warnings.push(body.keepNativeChatGptOnV1 === true
+        ? (effectiveMode === "v2"
+          ? "ChatGPT-native models stay on v1 while other models use v2. Applies to new sessions."
+          : "keepNativeChatGptOnV1 is stored but inactive until multi-agent mode is v2. Applies to new sessions.")
+        : "ChatGPT-native models follow the selected v1/v2/base surface. Applies to new sessions.");
+    }
     // New-key scalar writes: each writer is individually atomic, so apply them in
     // sequence after the transition. A failure here is a persistence failure (the
     // writers' ok:false result or a throw from the underlying atomic write helper),
@@ -263,6 +367,7 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
     if (wantsAgentsEnabled) scalarWrites.push({ field: "agentsEnabled", run: () => setAgentsEnabled(body.agentsEnabled as boolean | null) });
     if (wantsMaxDepth) scalarWrites.push({ field: "agentsMaxDepth", run: () => setAgentsMaxDepth(body.agentsMaxDepth as number | null) });
     if (wantsSubagentInstructions) scalarWrites.push({ field: "subagentDeveloperInstructions", run: () => setSubagentDeveloperInstructions(body.subagentDeveloperInstructions as string | null) });
+    if (wantsModeHintText) scalarWrites.push({ field: "multiAgentModeHintText", run: () => setMultiAgentModeHintText(body.multiAgentModeHintText as string | null) });
     const landed: string[] = [];
     for (const write of scalarWrites) {
       try {
@@ -282,7 +387,7 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
     if (getAgentsEnabled() === false && isMultiAgentV2Enabled()) {
       warnings.push("agents.enabled = false has no effect while features.multi_agent_v2 is enabled; upstream keeps V2 active.");
     }
-    await refreshCodexCatalogBestEffort();
+    const catalogRefresh = await convergeCodexCatalog();
     if (requestedFlag !== undefined) warnings.push("Applies to new sessions; restart the Codex app or wait out its picker cache to see the ladder change.");
     const enabled = isMultiAgentV2Enabled();
     return jsonResponse({
@@ -291,14 +396,71 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
       agentsMaxThreadsConflict: enabled && hasAgentsMaxThreads(),
       maxConcurrentThreadsPerSession: getLogicalMaxThreads(),
       multiAgentMode: config.multiAgentMode ?? "default",
+      keepNativeChatGptOnV1: config.keepNativeChatGptOnV1 === true,
       agentsEnabled: getAgentsEnabled(),
       agentsMaxDepth: getAgentsMaxDepth(),
       subagentDeveloperInstructions: getSubagentDeveloperInstructions(),
+      multiAgentModeHintText: getMultiAgentModeHintText(),
       agentsMaxDepthAppliesWhenV2Disabled: !enabled,
       warnings,
+      catalogRefresh,
     });
   }
 
+  // default_mode_request_user_input feature toggle (Codex Auth page). GET reads the
+  // flag from $CODEX_HOME/config.toml; PUT flips it via the official `codex features`
+  // CLI so the TOML edit stays upstream-owned and format-preserving.
+  if (url.pathname === "/api/codex-auth/features/default-mode-request-user-input" && req.method === "GET") {
+    const { isDefaultModeRequestUserInputEnabled, DEFAULT_MODE_REQUEST_USER_INPUT_FEATURE_KEY } = await import("../../codex/features");
+    return jsonResponse({
+      enabled: isDefaultModeRequestUserInputEnabled(),
+      key: DEFAULT_MODE_REQUEST_USER_INPUT_FEATURE_KEY,
+    });
+  }
+  if (url.pathname === "/api/codex-auth/features/default-mode-request-user-input" && req.method === "PUT") {
+    let parsedBody: unknown;
+    try {
+      parsedBody = await readManagementJsonBody(req);
+    } catch (error) {
+      rethrowManagementBodyTooLarge(error);
+      return jsonResponse({ error: "invalid JSON body" }, 400);
+    }
+    if (!parsedBody || typeof parsedBody !== "object" || Array.isArray(parsedBody)) {
+      return jsonResponse({ error: "body must be a JSON object" }, 400);
+    }
+    const body = parsedBody as { enabled?: unknown };
+    if (typeof body.enabled !== "boolean") return jsonResponse({ error: "body.enabled must be a boolean" }, 400);
+    const { isDefaultModeRequestUserInputEnabled, DEFAULT_MODE_REQUEST_USER_INPUT_FEATURE_KEY } = await import("../../codex/features");
+    const before = isDefaultModeRequestUserInputEnabled();
+    let toggle = deps.toggleDefaultModeRequestUserInput;
+    if (!toggle) {
+      const { runCodexFeaturesCommand } = await import("../../cli/v2");
+      toggle = (enabled: boolean) => runCodexFeaturesCommand(enabled ? "enable" : "disable", DEFAULT_MODE_REQUEST_USER_INPUT_FEATURE_KEY);
+    }
+    let toggleError: string | null = null;
+    try {
+      toggle(body.enabled);
+    } catch (error) {
+      const err = error as { stderr?: unknown; message?: string };
+      const raw = err.stderr;
+      const stderrText = typeof raw === "string"
+        ? raw.trim()
+        : raw instanceof Uint8Array ? new TextDecoder().decode(raw).trim() : "";
+      toggleError = stderrText || (err.message ?? String(error));
+    }
+    const enabled = isDefaultModeRequestUserInputEnabled();
+    if (toggleError !== null || enabled !== body.enabled) {
+      const reason = toggleError
+        ?? `postcondition failed - the installed Codex build may not know the ${DEFAULT_MODE_REQUEST_USER_INPUT_FEATURE_KEY} flag yet`;
+      return jsonResponse({ error: `default_mode_request_user_input toggle failed: ${reason}` }, 502);
+    }
+    const warnings: string[] = [];
+    if (enabled !== before) {
+      warnings.push("Applies to new sessions; restart the Codex app or wait out its picker cache to see the change.");
+    }
+    return jsonResponse({ ok: true, enabled, changed: enabled !== before, warnings });
+  }
+
   // Subagent prompt injection model: single native or routed model whose info is
   // dynamically injected into the v1 proactive prompt, plus an optional reasoning
   // effort the prompt tells the agent to pass to spawn_agent. GET returns the current
@@ -456,15 +618,29 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
         stored === catalogModelSlug(m) || slugEquals(stored, m.provider, m.id)
       ))
       .map(catalogModelSlug))];
-    const available = [
+    const chosen = config.subagentModels ?? [];
+    const selectable = [
       ...listCatalogNativeSlugs().filter(ns => !disabled.has(ns)),
       ...visibleRouted,
     ];
+    // A saved roster slot must stay representable even after its model is disabled
+    // elsewhere (Models page, provider allowlist, a provider row going away). The
+    // dashboard treats `available` as the set of rows it can render, so a chosen id
+    // missing from it disappears from the roster UI and the next Save — which PUTs
+    // exactly what the UI holds — silently truncates the persisted list. Losing a
+    // deliberate 5-model roster to an unrelated visibility toggle is data loss, not a
+    // filter. Same reasoning as `fetchGrokCandidateModels`, which deliberately lists a
+    // model the user already excluded so its switch remains reachable.
+    const selectableSet = new Set(selectable);
+    const available = [
+      ...selectable,
+      ...[...new Set(chosen)].filter(model => !selectableSet.has(model)),
+    ];
     // #857: let CLI/GUI show when a running Codex app-server keeps an older
     // in-memory catalog than the one on disk.
     const { collectCodexAppServerCatalogState } = await import("../../codex/app-server-processes");
     const catalogState = collectCodexAppServerCatalogState();
-    return jsonResponse({ chosen: config.subagentModels ?? [], available, catalogState });
+    return jsonResponse({ chosen, available, catalogState });
   }
   if (url.pathname === "/api/subagent-models" && req.method === "PUT") {
     let body: { models?: unknown };
@@ -473,10 +649,10 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
     config.subagentModels = chosen;
     const { saveConfigPreservingClaudeCode: save } = await import("../../config");
     save(config);
-    await refreshCodexCatalogBestEffort();
+    const catalogRefresh = await convergeCodexCatalog();
     await syncClaudeAgentDefsBestEffort();
     await autoApplyDesktopBestEffort();
-    return jsonResponse({ ok: true, applied: chosen });
+    return jsonResponse({ ok: true, applied: chosen, catalogRefresh });
   }
 
   // Priority-ordered subagent model fallback chain for quota-aware spawn routing.
@@ -783,21 +959,19 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
       // #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";
-      const rawBody = await req.text();
       let parsed: unknown;
-      if (rawBody.trim()) {
-        try {
-          parsed = JSON.parse(rawBody);
-        } catch {
-          return jsonResponse({ error: "invalid JSON body" }, 400);
-        }
-        const requested = (parsed as { mode?: unknown } | null)?.mode;
-        if (requested !== undefined) {
-          if (requested === "static" || requested === "hybrid" || requested === "discovery") {
-            mode = requested;
-          } else {
-            return jsonResponse({ error: "mode must be static, hybrid, or discovery" }, 400);
-          }
+      try {
+        parsed = await readOptionalManagementJsonBody(req);
+      } catch (error) {
+        rethrowManagementBodyTooLarge(error);
+        return jsonResponse({ error: "invalid JSON body" }, 400);
+      }
+      const requested = (parsed as { mode?: unknown } | null)?.mode;
+      if (requested !== undefined) {
+        if (requested === "static" || requested === "hybrid" || requested === "discovery") {
+          mode = requested;
+        } else {
+          return jsonResponse({ error: "mode must be static, hybrid, or discovery" }, 400);
         }
       }
       // #859: a delegated CLI apply carries the profile it just saved — the
@@ -813,9 +987,26 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
           return jsonResponse({ error: error instanceof Error ? error.message : String(error) }, 400);
         }
       }
+      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);
       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
@@ -824,22 +1015,52 @@ 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,
+        nativeContextLimits(latest),
       );
       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) {
+      rethrowManagementBodyTooLarge(error);
       return jsonResponse({ error: error instanceof Error ? error.message : String(error) }, 400);
     }
   }
@@ -847,47 +1068,35 @@ 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";
+      // "Needs update" is only meaningful while the integration is wanted. When the
+      // durable switch is OFF, a leftover drifted profile is residue to clear — not
+      // a stale apply the operator should refresh.
+      const stale = desiredEnabled && 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) {
@@ -921,7 +1130,7 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
       if (isDisabled(m.provider, m.id)) continue;
       aliases.push({ id: claudeCodeAlias(m.provider, m.id), display_name: `${m.id} (${m.provider})` });
     }
-    const contextWindows = buildClaudeContextWindows([...visibleNativeSlugs(config)], models);
+    const contextWindows = buildClaudeContextWindows([...visibleNativeSlugs(config)], models, nativeContextLimits(config));
     const webSearchOverride = config.claudeCode?.webSearchSidecar;
     const visionOverride = config.claudeCode?.visionSidecar;
     // Auto is a RESOLUTION, recomputed per request — never stored state. Detection is
@@ -950,8 +1159,10 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
       smallFastModel: config.claudeCode?.smallFastModel ?? "",
       tierModels: config.claudeCode?.tierModels ?? {},
       modelMap: config.claudeCode?.modelMap ?? {},
+      classifierModel: config.claudeCode?.classifierModel ?? "",
+      classifierFallbacks: config.claudeCode?.classifierFallbacks ?? [],
       systemEnv: config.claudeCode?.systemEnv === true,
-      autoConnectSupported: process.platform === "darwin",
+      autoConnectSupported: (ctx.deps.platform ?? process.platform) === "darwin",
       maxContextTokens: config.claudeCode?.maxContextTokens ?? null,
       alwaysEnableEffort: config.claudeCode?.alwaysEnableEffort === true,
       autoContext: config.claudeCode?.autoContext !== false,
@@ -987,18 +1198,78 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
       return prototype === Object.prototype || prototype === null;
     };
     if (!isPlainObject(parsedBody)) return jsonResponse({ error: "body must be an object" }, 400);
-    const body = parsedBody as { enabled?: unknown; authMode?: unknown; model?: unknown; smallFastModel?: unknown; modelMap?: unknown; systemEnv?: unknown; fastMode?: unknown; maxContextTokens?: unknown; alwaysEnableEffort?: unknown; tierModels?: unknown; autoContext?: unknown; autoCompactWindow?: unknown; blockedSkills?: unknown; injectAgents?: unknown; webSearchSidecar?: unknown; visionSidecar?: unknown };
+    const body = parsedBody as { enabled?: unknown; authMode?: unknown; model?: unknown; smallFastModel?: unknown; modelMap?: unknown; classifierModel?: unknown; classifierFallbacks?: unknown; systemEnv?: unknown; fastMode?: unknown; maxContextTokens?: unknown; alwaysEnableEffort?: unknown; tierModels?: unknown; autoContext?: unknown; autoCompactWindow?: unknown; blockedSkills?: unknown; injectAgents?: unknown; webSearchSidecar?: unknown; visionSidecar?: unknown };
     for (const field of ["webSearchSidecar", "visionSidecar"] as const) {
       const section = body[field];
       if (section === undefined || section === null) continue;
       if (!isPlainObject(section)) return jsonResponse({ error: `${field} must be an object or null` }, 400);
+      // Both overrides now speak their full unions (roadmap 060 web, 170
+      // vision revised). Vision's third arm is "routed" (loopback through the
+      // proxy's own router), never exa: exa is not an LLM, and accepting an
+      // unknown literal would persist a backend the vision resolver reads as
+      // unset (review F1's failure mode).
+      const allowedBackends = field === "webSearchSidecar"
+        ? ["openai", "anthropic", "xai", "gemini", "exa"]
+        : ["openai", "anthropic", "routed"];
       if (section.backend !== undefined && section.backend !== null
-        && section.backend !== "openai" && section.backend !== "anthropic") {
-        return jsonResponse({ error: `${field}.backend must be openai, anthropic, or null` }, 400);
+        && !allowedBackends.includes(section.backend as string)) {
+        return jsonResponse({ error: `${field}.backend must be ${allowedBackends.join(", ")}, or null` }, 400);
       }
       if (section.model !== undefined && typeof section.model !== "string") {
         return jsonResponse({ error: `${field}.model must be a string` }, 400);
       }
+      // Vision override only: reject a model we can prove is blind. Unknown ids stay
+      // allowed. Shares one policy module with /api/sidecar-settings so the two
+      // gates cannot drift.
+      if (field === "visionSidecar" && typeof section.model === "string" && section.model !== "") {
+        const requested = section.model;
+        const candidates = await visionCandidateRows(config);
+        const hint = section.backend === "anthropic" || section.backend === "openai"
+          || section.backend === "routed"
+          ? section.backend
+          : config.claudeCode?.visionSidecar?.backend;
+        // Same coherence rule as /api/sidecar-settings (roadmap 170 r2).
+        const effectiveBackend = hint ?? "openai";
+        const namespaced = requested.includes("/");
+        if (namespaced && effectiveBackend !== "routed") {
+          return jsonResponse({ error: `visionSidecar.model "${requested}" is provider-namespaced; it requires backend "routed"` }, 400);
+        }
+        if (!namespaced && effectiveBackend === "routed") {
+          return jsonResponse({ error: `visionSidecar.backend "routed" requires a provider-namespaced model ("provider/model"); got "${requested}"` }, 400);
+        }
+        if (visionDescriberIsProvablyBlind(config, requested, candidates, hint)) {
+          return jsonResponse(visionDescriberRejection("visionSidecar.model", requested, config, candidates), 400);
+        }
+      }
+      // Web-search override: membership gate (#2188). The executor set is closed,
+      // so an id outside (runnable candidates ∪ auth slots) can never run. Same
+      // module as /api/sidecar-settings — a gate on one route and a stale copy on
+      // the other is no gate at all.
+      if (field === "webSearchSidecar"
+        && (section.model !== undefined || section.backend !== undefined)) {
+        const stored = config.claudeCode?.webSearchSidecar;
+        const effectiveBackend = section.backend === "anthropic"
+          ? "anthropic"
+          : section.backend === "openai"
+            ? "openai"
+            : section.backend === null
+              ? config.webSearchSidecar?.backend ?? "openai"
+              : stored?.backend ?? config.webSearchSidecar?.backend ?? "openai";
+        const effectiveModel = section.model === ""
+          ? config.webSearchSidecar?.model
+          : typeof section.model === "string"
+            ? section.model
+            : stored?.model ?? config.webSearchSidecar?.model;
+        const candidates = await webSearchCandidateRows(config);
+        if (effectiveModel && webSearchModelIsRejected(effectiveBackend, effectiveModel, candidates)) {
+          return jsonResponse(webSearchModelRejection(
+            "webSearchSidecar.model",
+            effectiveBackend,
+            effectiveModel,
+            candidates,
+          ), 400);
+        }
+      }
     }
     const next = { ...(config.claudeCode ?? {}) };
     for (const field of ["webSearchSidecar", "visionSidecar"] as const) {
@@ -1008,13 +1279,17 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
         delete next[field];
         continue;
       }
-      const requested = section as { backend?: "openai" | "anthropic" | null; model?: string };
-      const override: NonNullable<OcxClaudeCodeConfig[typeof field]> = { ...next[field] };
+      // The per-field validation above guarantees vision only ever carries the two-member
+      // union; the cast is the loop's shared-shape compromise, not a wider write path.
+      const requested = section as { backend?: "openai" | "anthropic" | "xai" | "gemini" | "exa" | null; model?: string };
+      const override = { ...next[field] } as NonNullable<OcxClaudeCodeConfig[typeof field]>;
       if (requested.backend === null) delete override.backend;
-      else if (requested.backend !== undefined) override.backend = requested.backend;
+      else if (requested.backend !== undefined) override.backend = requested.backend as never;
       if (requested.model === "") delete override.model;
       else if (requested.model !== undefined) override.model = requested.model;
-      if (Object.keys(override).length > 0) next[field] = override;
+      // Indexed write across the field union collapses to an intersection; runtime
+      // validation above already guarantees the per-field shape.
+      if (Object.keys(override).length > 0) next[field] = override as never;
       else delete next[field];
     }
     if (body.enabled !== undefined) {
@@ -1107,19 +1382,38 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
         else delete next.tierModels;
       }
     }
+    let nextFastMode = config.fastMode;
     if (body.fastMode !== undefined) {
       if (body.fastMode !== true && body.fastMode !== false && body.fastMode !== null) {
         return jsonResponse({ error: "fastMode must be true, false, or null" }, 400);
       }
-      config.fastMode = body.fastMode === null ? undefined : body.fastMode;
+      nextFastMode = body.fastMode === null ? undefined : body.fastMode;
     }
-    for (const field of ["model", "smallFastModel"] as const) {
+    for (const field of ["model", "smallFastModel", "classifierModel"] as const) {
       const value = body[field];
       if (value === undefined) continue;
       if (typeof value !== "string") return jsonResponse({ error: `${field} must be a string` }, 400);
       if (value.trim() === "") delete next[field];
       else next[field] = value.trim();
     }
+    if (body.classifierFallbacks !== undefined) {
+      if (body.classifierFallbacks === null) {
+        delete next.classifierFallbacks;
+      } else {
+        if (!Array.isArray(body.classifierFallbacks)) {
+          return jsonResponse({ error: "classifierFallbacks must be an array of strings, or null" }, 400);
+        }
+        const list: string[] = [];
+        for (const entry of body.classifierFallbacks) {
+          if (typeof entry !== "string" || entry.trim() === "") {
+            return jsonResponse({ error: "classifierFallbacks entries must be non-empty strings" }, 400);
+          }
+          list.push(entry.trim());
+        }
+        if (list.length > 0) next.classifierFallbacks = list;
+        else delete next.classifierFallbacks;
+      }
+    }
     if (body.modelMap !== undefined) {
       if (body.modelMap === null) {
         delete next.modelMap;
@@ -1138,6 +1432,7 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
         else delete next.modelMap;
       }
     }
+    if (body.fastMode !== undefined) config.fastMode = nextFastMode;
     config.claudeCode = next;
     // Stamp the migration sentinel on EVERY persist of this block. The migration reads
     // "a claudeCode block with no authMode" as a pre-upgrade subscriber and pins it to