@yansigit/opencodex 2.35.2-dev.20260829.15 → 2.36.1-dev.20260829.19

package/src/server/index.ts

@@ -17,6 +17,8 @@ import {
   armClaudeCodeBaseline,
   loadConfig,
   saveConfig,
+  saveConfigPreservingClaudeCode,
+  mutatePersistedConfig,
   getConfigDir,
   websocketsEnabled,
 } from "../config";
@@ -531,6 +533,11 @@ export function warnAgentTaskRecoveryStartup(config: {
 }
 
 export function startServer(port?: number, deps: StartServerDeps = {}): Server<WsData> {
+  const managementApi: ManagementApiDeps = {
+    saveConfigPreservingClaudeCode,
+    mutatePersistedConfig,
+    ...deps.managementApi,
+  };
   const localAttestationSecret = deps.localAttestationSecret ?? createLocalAttestationSecret();
   const config = runModelRenameStartupMigration(runAlibabaRegionStartupMigration(runOpenAiTierStartupMigration(loadConfig())));
   warnAgentTaskRecoveryStartup(config);
@@ -1044,7 +1051,7 @@ export function startServer(port?: number, deps: StartServerDeps = {}): Server<W
             method: "POST",
             headers: { Host: req.headers.get("Host") ?? "127.0.0.1" },
           });
-          const probeResponse = await handleManagementAPI(probeRequest, new URL(probeRequest.url), config, deps.managementApi);
+          const probeResponse = await handleManagementAPI(probeRequest, new URL(probeRequest.url), config, managementApi);
           const probe = await probeResponse?.json().catch(() => null) as { ok?: boolean; error?: string } | null;
           if (!probe?.ok) return jsonResponse({ ok: false, error: probe?.error ?? "AI Studio connection probe failed" }, 502, req, policy);
           return jsonResponse({ ok: true, sessionPath: login.sessionPath }, 200, req, policy);
@@ -1122,7 +1129,7 @@ export function startServer(port?: number, deps: StartServerDeps = {}): Server<W
         // gate used. Consent-bearing routes need this: request headers are forgeable
         // by anything holding the admin token, the credential is not.
         const principal = managementPrincipal(req, managementAuth, config, localManagementAuth) ?? undefined;
-        const mgmtResponse = await handleManagementAPI(req, url, config, deps.managementApi, principal);
+        const mgmtResponse = await handleManagementAPI(req, url, config, managementApi, principal);
         if (mgmtResponse) return withManagementCors(mgmtResponse, req, config);
         return withManagementCors(formatErrorResponse(404, "not_found", `Unknown endpoint: ${req.method} ${url.pathname}`), req, config);
       }

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

@@ -10,10 +10,8 @@ import {
   isValidProviderName,
   loadConfig,
   multiAgentGuidanceEnabled,
-  mutatePersistedConfig,
   providerBaseUrlConfigError,
   providerHeadersConfigError,
-  saveConfigPreservingClaudeCode,
   subagentDefaultSyncEffective,
 } from "../../config";
 import {
@@ -91,9 +89,29 @@ let grokApplyTestHooks: { now?: () => number; run?: () => Promise<unknown> } | n
 
 type V2NativeParentOverrideInput = { enabled: boolean; model: string | null };
 type AgentTaskRecoveryInput = { enabled: boolean; model: string | null };
+const V2_CONFIG_KEYS = ["multiAgentMode", "keepNativeChatGptOnV1", "v2NativeParentOverride", "v2RoutedDelegationBridge", "agentTaskRecovery"] as const;
+type V2ConfigKey = typeof V2_CONFIG_KEYS[number];
+type V2ConfigSnapshot = Pick<OcxConfig, V2ConfigKey>;
 
-function persistV2RoutedDelegationBridge(config: OcxConfig, enabled: boolean): { ok: true } | { ok: false; reason: string } {
-  const outcome = mutatePersistedConfig(persisted => {
+function v2ConfigSnapshot(config: OcxConfig): V2ConfigSnapshot {
+  return Object.fromEntries(V2_CONFIG_KEYS.map(key => [key, structuredClone(config[key])])) as V2ConfigSnapshot;
+}
+
+function setV2ConfigField(config: OcxConfig, key: V2ConfigKey, value: OcxConfig[V2ConfigKey]): void {
+  if (value === undefined) delete (config as unknown as Record<string, unknown>)[key];
+  else (config as unknown as Record<string, unknown>)[key] = structuredClone(value);
+}
+
+function sameV2ConfigField(left: unknown, right: unknown): boolean {
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+
+function persistV2RoutedDelegationBridge(
+  deps: ManagementApiDeps,
+  config: OcxConfig,
+  enabled: boolean,
+): { ok: true } | { ok: false; reason: string } {
+  const outcome = mutateManagementConfig(deps, persisted => {
     const changed = persisted.v2RoutedDelegationBridge !== enabled;
     if (changed) persisted.v2RoutedDelegationBridge = enabled;
     return { changed, value: true };
@@ -114,10 +132,11 @@ function agentTaskRecoveryDto(
 }
 
 function persistAgentTaskRecovery(
+  deps: ManagementApiDeps,
   config: OcxConfig,
   next: AgentTaskRecoveryInput,
 ): { ok: true } | { ok: false; reason: string } {
-  const outcome = mutatePersistedConfig(persisted => {
+  const outcome = mutateManagementConfig(deps, persisted => {
     const nextPersisted = {
       enabled: next.enabled,
       ...(next.model === null ? {} : { model: next.model }),
@@ -163,10 +182,11 @@ function v2NativeParentOverrideTargetIsNoncanonical(config: OcxConfig, model: st
 }
 
 function persistV2NativeParentOverride(
+  deps: ManagementApiDeps,
   config: OcxConfig,
   next: V2NativeParentOverrideInput,
 ): { ok: true } | { ok: false; reason: string } {
-  const outcome = mutatePersistedConfig(persisted => {
+  const outcome = mutateManagementConfig(deps, persisted => {
     const nextPersisted = {
       enabled: next.enabled,
       ...(next.model === null ? {} : { model: next.model }),
@@ -215,10 +235,11 @@ function mirrorDesiredEnabledOntoSnapshot(config: OcxConfig, client: "claude-des
  * unrelated key another writer just committed.
  */
 function persistDesktopProfileField(
+  deps: ManagementApiDeps,
   config: OcxConfig,
   desktopProfile: NonNullable<OcxConfig["claudeCode"]>["desktopProfile"],
 ): { ok: true } | { ok: false; reason: "missing" | "invalid" | "conflict" } {
-  const outcome = mutatePersistedConfig(persisted => {
+  const outcome = mutateManagementConfig(deps, persisted => {
     persisted.claudeCode = { ...(persisted.claudeCode ?? {}), desktopProfile };
     return { changed: true, value: true };
   });
@@ -281,7 +302,7 @@ export function setGrokApplyFlightTestHooks(
   grokApplyFlight = null;
   grokApplyHighWaterBytes = 0;
 }
-import type { ManagementContext } from "./context";
+import { ManagementPersistenceError, MissingManagementPersistenceError, mutateManagementConfig, saveManagementConfig, type ManagementApiDeps, type ManagementContext } from "./context";
 
 export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise<Response | null> {
   const { req, url, config, deps, convergeCodexCatalog, syncClaudeAgentDefsBestEffort } = ctx;
@@ -321,7 +342,7 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
       );
       if (result.written && result.fingerprint) {
         current.claudeCode = { ...current.claudeCode, desktopProfile: { ...current.claudeCode.desktopProfile, appliedFingerprint: result.fingerprint, appliedAt: new Date().toISOString() } };
-        saveConfigPreservingClaudeCode(current);
+        saveManagementConfig(deps, current);
       }
     } catch { /* best-effort */ }
   }
@@ -512,19 +533,19 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
     }
     if (wantsV2RoutedDelegationBridge && !wantsFlag && !wantsThreads && !wantsMode && !wantsKeepNative
         && !wantsAgentsEnabled && !wantsMaxDepth && !wantsSubagentInstructions && !wantsModeHintText && !wantsV2NativeParentOverride && !wantsAgentTaskRecovery) {
-      const persisted = persistV2RoutedDelegationBridge(config, body.v2RoutedDelegationBridge as boolean);
+      const persisted = persistV2RoutedDelegationBridge(deps, config, body.v2RoutedDelegationBridge as boolean);
       if (!persisted.ok) return jsonResponse({ error: `persisting v2RoutedDelegationBridge failed: ${persisted.reason}` }, 502);
       return jsonResponse({ ok: true, v2RoutedDelegationBridge: config.v2RoutedDelegationBridge === true });
     }
     if (agentTaskRecovery && !wantsFlag && !wantsThreads && !wantsMode && !wantsKeepNative
         && !wantsAgentsEnabled && !wantsMaxDepth && !wantsSubagentInstructions && !wantsModeHintText && !wantsV2NativeParentOverride) {
-      const persisted = persistAgentTaskRecovery(config, agentTaskRecovery);
+      const persisted = persistAgentTaskRecovery(deps, config, agentTaskRecovery);
       if (!persisted.ok) return jsonResponse({ error: `persisting agentTaskRecovery failed: ${persisted.reason}` }, 502);
       return jsonResponse({ ok: true, agentTaskRecovery: agentTaskRecoveryDto(config) });
     }
     if (v2NativeParentOverride && !wantsFlag && !wantsThreads && !wantsMode && !wantsKeepNative
         && !wantsAgentsEnabled && !wantsMaxDepth && !wantsSubagentInstructions && !wantsModeHintText) {
-      const persisted = persistV2NativeParentOverride(config, v2NativeParentOverride);
+      const persisted = persistV2NativeParentOverride(deps, config, v2NativeParentOverride);
       if (!persisted.ok) return jsonResponse({ error: `persisting v2NativeParentOverride failed: ${persisted.reason}` }, 502);
       return jsonResponse({ ok: true, v2NativeParentOverride: v2NativeParentOverrideDto(config, readMultiAgentV2Enabled()) });
     }
@@ -549,6 +570,87 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
         error: "body.enabled=true conflicts with keepNativeChatGptOnV1: Codex's global multi_agent_v2 override outranks catalog pins",
       }, 400);
     }
+    let rollbackV2Config: (() => string | null) | undefined;
+    if (wantsMode || wantsKeepNative || v2NativeParentOverride || wantsV2RoutedDelegationBridge || agentTaskRecovery) {
+      const requestedKeys = V2_CONFIG_KEYS.filter(key => (
+        (key === "multiAgentMode" && wantsMode)
+        || (key === "keepNativeChatGptOnV1" && wantsKeepNative)
+        || (key === "v2NativeParentOverride" && v2NativeParentOverride !== undefined)
+        || (key === "v2RoutedDelegationBridge" && wantsV2RoutedDelegationBridge)
+        || (key === "agentTaskRecovery" && agentTaskRecovery !== undefined)
+      ));
+      let before!: V2ConfigSnapshot;
+      let committed!: OcxConfig;
+      const persisted = mutateManagementConfig(deps, disk => {
+        before = v2ConfigSnapshot(disk);
+        if (wantsMode) {
+          if (mode === "default") deleteConfigTopLevelKey(disk, "multiAgentMode");
+          else disk.multiAgentMode = mode;
+        }
+        if (wantsKeepNative) {
+          if (body.keepNativeChatGptOnV1 === true) disk.keepNativeChatGptOnV1 = true;
+          else deleteConfigTopLevelKey(disk, "keepNativeChatGptOnV1");
+        }
+        if (v2NativeParentOverride) {
+          disk.v2NativeParentOverride = {
+            enabled: v2NativeParentOverride.enabled,
+            ...(v2NativeParentOverride.model === null ? {} : { model: v2NativeParentOverride.model }),
+          };
+        }
+        if (wantsV2RoutedDelegationBridge) disk.v2RoutedDelegationBridge = body.v2RoutedDelegationBridge as boolean;
+        if (agentTaskRecovery) {
+          disk.agentTaskRecovery = {
+            enabled: agentTaskRecovery.enabled,
+            ...(agentTaskRecovery.model === null ? {} : { model: agentTaskRecovery.model }),
+          };
+        }
+        committed = structuredClone(disk);
+        return { changed: true, value: true };
+      });
+      if (persisted.status === "unavailable") {
+        return jsonResponse({ error: `persisting V2 settings failed: ${persisted.reason}` }, 502);
+      }
+      if (wantsMode) {
+        if (committed.multiAgentMode === undefined) deleteConfigTopLevelKey(config, "multiAgentMode");
+        else config.multiAgentMode = committed.multiAgentMode;
+      }
+      if (wantsKeepNative) {
+        if (committed.keepNativeChatGptOnV1 === undefined) deleteConfigTopLevelKey(config, "keepNativeChatGptOnV1");
+        else config.keepNativeChatGptOnV1 = committed.keepNativeChatGptOnV1;
+      }
+      if (v2NativeParentOverride) config.v2NativeParentOverride = committed.v2NativeParentOverride;
+      if (wantsV2RoutedDelegationBridge) config.v2RoutedDelegationBridge = committed.v2RoutedDelegationBridge;
+      if (agentTaskRecovery) config.agentTaskRecovery = committed.agentTaskRecovery;
+      const committedSnapshot = v2ConfigSnapshot(committed);
+      rollbackV2Config = () => {
+        let finalSnapshot!: V2ConfigSnapshot;
+        try {
+          const rollback = mutateManagementConfig(deps, disk => {
+            let changed = false;
+            for (const key of requestedKeys) {
+              if (!sameV2ConfigField(disk[key], committedSnapshot[key])) continue;
+              setV2ConfigField(disk, key, before[key]);
+              changed = true;
+            }
+            finalSnapshot = v2ConfigSnapshot(disk);
+            return { changed, value: true };
+          });
+          if (rollback.status === "unavailable") return rollback.reason;
+        } catch (error) {
+          return error instanceof Error ? error.message : String(error);
+        }
+        for (const key of requestedKeys) setV2ConfigField(config, key, finalSnapshot[key]);
+        return null;
+      };
+    }
+    const rollbackDiagnostic = (message: string): string => {
+      const failure = rollbackV2Config?.();
+      return failure ? `${message}; config rollback failed: ${failure}` : message;
+    };
+    const externalChanged: string[] = [];
+    const scalarFailureDiagnostic = (message: string): string => externalChanged.length > 0
+      ? `${message}; config retained because earlier external side effects were applied: ${externalChanged.join(", ")}`
+      : rollbackDiagnostic(message);
     const requestedFlag = wantsFlag
       ? body.enabled as boolean
       : modeFlag ?? (wantsKeepNative && hybridPinActive ? false : undefined);
@@ -562,19 +664,15 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
       const result = transitionMultiAgentV2(targetFlag, toggle, {
         ...(wantsThreads ? { threadLimit: body.maxConcurrentThreadsPerSession as number } : {}),
       });
-      if (!result.ok) return jsonResponse({ error: `multi_agent_v2 transition failed: ${result.error}` }, 502);
+      if (!result.ok) return jsonResponse({ error: rollbackDiagnostic(`multi_agent_v2 transition failed: ${result.error}`) }, 502);
+      if (result.changed) externalChanged.push("multi_agent_v2");
       if (result.changed && result.threadLimit !== null) warnings.push(`Thread limit ${result.threadLimit} preserved for ${targetFlag ? "v2" : "v1"}.`);
     }
     if (wantsMode) {
-      if (mode === "default") deleteConfigTopLevelKey(config, "multiAgentMode");
-      else config.multiAgentMode = mode;
-      saveConfigPreservingClaudeCode(config);
       warnings.push(`Multi-agent mode set to '${mode}'. Applies to new sessions.`);
     }
     if (wantsKeepNative) {
-      if (body.keepNativeChatGptOnV1 === true) config.keepNativeChatGptOnV1 = true;
-      else deleteConfigTopLevelKey(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."
@@ -589,21 +687,22 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
     // asserts this route file contains no direct write primitive, and matches on the
     // symbol name even inside a comment.
     const scalarWrites: Array<{ field: string; run: () => { ok: true; changed: boolean } | { ok: false; error: string } }> = [];
-    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) });
+    if (wantsAgentsEnabled) scalarWrites.push({ field: "agentsEnabled", run: () => (deps.v2ScalarWriters?.setAgentsEnabled ?? setAgentsEnabled)(body.agentsEnabled as boolean | null) });
+    if (wantsMaxDepth) scalarWrites.push({ field: "agentsMaxDepth", run: () => (deps.v2ScalarWriters?.setAgentsMaxDepth ?? setAgentsMaxDepth)(body.agentsMaxDepth as number | null) });
+    if (wantsSubagentInstructions) scalarWrites.push({ field: "subagentDeveloperInstructions", run: () => (deps.v2ScalarWriters?.setSubagentDeveloperInstructions ?? setSubagentDeveloperInstructions)(body.subagentDeveloperInstructions as string | null) });
+    if (wantsModeHintText) scalarWrites.push({ field: "multiAgentModeHintText", run: () => (deps.v2ScalarWriters?.setMultiAgentModeHintText ?? setMultiAgentModeHintText)(body.multiAgentModeHintText as string | null) });
     const landed: string[] = [];
     for (const write of scalarWrites) {
       try {
         const result = write.run();
         if (!result.ok) {
-          return jsonResponse({ error: `writing ${write.field} failed: ${result.error}${landed.length > 0 ? ` (already applied: ${landed.join(", ")})` : ""}` }, 502);
+          return jsonResponse({ error: scalarFailureDiagnostic(`writing ${write.field} failed: ${result.error}${landed.length > 0 ? ` (already applied: ${landed.join(", ")})` : ""}`) }, 502);
         }
         landed.push(write.field);
+        if (result.changed) externalChanged.push(write.field);
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
-        return jsonResponse({ error: `writing ${write.field} failed: ${message}${landed.length > 0 ? ` (already applied: ${landed.join(", ")})` : ""}` }, 502);
+        return jsonResponse({ error: scalarFailureDiagnostic(`writing ${write.field} failed: ${message}${landed.length > 0 ? ` (already applied: ${landed.join(", ")})` : ""}`) }, 502);
       }
     }
     // Derived from fresh post-write readers (readConfigText is uncached): upstream
@@ -612,18 +711,6 @@ 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.");
     }
-    if (v2NativeParentOverride) {
-      const persisted = persistV2NativeParentOverride(config, v2NativeParentOverride);
-      if (!persisted.ok) return jsonResponse({ error: `persisting v2NativeParentOverride failed: ${persisted.reason}` }, 502);
-    }
-    if (wantsV2RoutedDelegationBridge) {
-      const persisted = persistV2RoutedDelegationBridge(config, body.v2RoutedDelegationBridge as boolean);
-      if (!persisted.ok) return jsonResponse({ error: `persisting v2RoutedDelegationBridge failed: ${persisted.reason}` }, 502);
-    }
-    if (agentTaskRecovery) {
-      const persisted = persistAgentTaskRecovery(config, agentTaskRecovery);
-      if (!persisted.ok) return jsonResponse({ error: `persisting agentTaskRecovery failed: ${persisted.reason}` }, 502);
-    }
     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();
@@ -806,7 +893,7 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
     if (nextPrompt) config.injectionPrompt = nextPrompt;
     else deleteConfigTopLevelKey(config, "injectionPrompt");
 
-    saveConfigPreservingClaudeCode(config);
+    saveManagementConfig(deps, config);
     return jsonResponse({
       ok: true,
       multiAgentGuidanceEnabled: multiAgentGuidanceEnabled(config),
@@ -841,7 +928,7 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
       }
       config[key] = value;
     }
-    saveConfigPreservingClaudeCode(config);
+    saveManagementConfig(deps, config);
     return jsonResponse({ ok: true, effortCap: config.effortCap ?? null, subagentEffortCap: config.subagentEffortCap ?? null });
   }
 
@@ -887,8 +974,7 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
     try { body = await readManagementJsonBody(req); } catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid JSON body" }, 400); }
     const chosen = Array.isArray(body.models) ? body.models.filter((m): m is string => typeof m === "string").slice(0, 5) : [];
     config.subagentModels = chosen;
-    const { saveConfigPreservingClaudeCode: save } = await import("../../config");
-    save(config);
+    saveManagementConfig(deps, config);
     const catalogRefresh = await convergeCodexCatalog();
     await syncClaudeAgentDefsBestEffort();
     await autoApplyDesktopBestEffort();
@@ -935,8 +1021,7 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
       }
       const id = body.remove.trim();
       config.subagentRoles = (config.subagentRoles ?? []).filter(role => role.id !== id);
-      const { saveConfigPreservingClaudeCode: save } = await import("../../config");
-      save(config);
+      saveManagementConfig(deps, config);
       const warnings = [...syncCodexAgentRoles(config).warnings];
       const catalogRefresh = await convergeCodexCatalog();
       await syncClaudeAgentDefsBestEffort();
@@ -967,8 +1052,7 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
     if ("syncCodexAgentRoles" in body && typeof body.syncCodexAgentRoles === "boolean") {
       config.syncCodexAgentRoles = body.syncCodexAgentRoles;
     }
-    const { saveConfigPreservingClaudeCode: save } = await import("../../config");
-    save(config);
+    saveManagementConfig(deps, config);
     warnings.push(...syncCodexAgentRoles(config).warnings);
     const catalogRefresh = await convergeCodexCatalog();
     await syncClaudeAgentDefsBestEffort();
@@ -1045,7 +1129,7 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
     else deleteConfigTopLevelKey(config, "subagentModelFallback");
     if (nextPollMs !== undefined) config.subagentModelFallbackPollMs = nextPollMs;
     else deleteConfigTopLevelKey(config, "subagentModelFallbackPollMs");
-    saveConfigPreservingClaudeCode(config);
+    saveManagementConfig(deps, config);
     return jsonResponse({
       ok: true,
       models: config.subagentModelFallback ?? [],
@@ -1087,7 +1171,7 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
     if (excluded.length > 2000) return jsonResponse({ error: "excluded list is too large" }, 400);
     if (excluded.length === 0) deleteConfigTopLevelKey(config, "grokExcludedModels");
     else config.grokExcludedModels = excluded;
-    saveConfigPreservingClaudeCode(config);
+    saveManagementConfig(deps, config);
     return jsonResponse({ ok: true, excluded });
   }
 
@@ -1144,11 +1228,12 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
       }
       const state = await buildClaudeDesktopState(config, parsed);
       config.claudeCode = { ...(config.claudeCode ?? {}), desktopProfile: reconcileDesktopProfile(state.profile, state.models) };
-      saveConfigPreservingClaudeCode(config);
+      saveManagementConfig(deps, config);
       const saved = await buildClaudeDesktopState(config);
       const runtimePort = Number(url.port) || config.port;
       return jsonResponse({ ok: true, ...saved, port: runtimePort });
     } catch (error) {
+      if (error instanceof MissingManagementPersistenceError || error instanceof ManagementPersistenceError) throw error;
       return jsonResponse({ error: error instanceof Error ? error.message : String(error) }, 400);
     }
   }
@@ -1197,7 +1282,7 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
       // 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);
+      const profileSaved = persistDesktopProfileField(deps, config, state.profile);
       if (!profileSaved.ok) {
         return jsonResponse({
           error: `Claude Desktop profile could not be saved (${profileSaved.reason}); nothing was applied.`,
@@ -1240,7 +1325,7 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
       if (result.fingerprint) {
         // 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, {
+        const marked = persistDesktopProfileField(deps, config, {
           ...state.profile,
           appliedFingerprint: result.fingerprint,
           appliedAt: new Date().toISOString(),
@@ -1635,8 +1720,6 @@ 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
     // literal subscription — correct for a config written before `auto` existed, fatal
@@ -1645,8 +1728,46 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
     // would be converted into a sticky manual subscription by the next startServer, and
     // auto would survive exactly one proxy lifetime with no way back.
     if (!next.authModeMigratedAt) next.authModeMigratedAt = new Date().toISOString();
-    const { saveConfigPreservingClaudeCode: save } = await import("../../config");
-    save(config);
+    let committedClaude!: OcxClaudeCodeConfig;
+    const persisted = mutateManagementConfig(deps, disk => {
+      const latest = { ...(disk.claudeCode ?? {}) };
+      for (const field of ["enabled", "authMode", "model", "smallFastModel", "modelMap", "classifierModel", "classifierFallbacks", "systemEnv", "alwaysEnableEffort", "maxContextTokens", "autoContext", "injectAgents", "autoCompactWindow", "blockedSkills", "tierModels"] as const) {
+        if (!Object.hasOwn(body, field)) continue;
+        if (Object.hasOwn(next, field)) latest[field] = next[field] as never;
+        else delete latest[field];
+      }
+      for (const field of ["webSearchSidecar", "visionSidecar"] as const) {
+        const section = body[field];
+        if (section === undefined) continue;
+        if (section === null || Object.keys(section as Record<string, unknown>).length === 0) {
+          delete latest[field];
+          continue;
+        }
+        const override = { ...latest[field] } as { backend?: string; model?: string };
+        const desired = next[field] as { backend?: string; model?: string } | undefined;
+        for (const key of ["backend", "model"] as const) {
+          if (!Object.hasOwn(section, key)) continue;
+          if (Object.hasOwn(desired ?? {}, key)) override[key] = desired![key];
+          else delete override[key];
+        }
+        if (Object.keys(override).length > 0) latest[field] = override as never;
+        else delete latest[field];
+      }
+      latest.authModeMigratedAt = next.authModeMigratedAt;
+      disk.claudeCode = latest;
+      committedClaude = structuredClone(latest);
+      if (body.fastMode !== undefined) {
+        if (nextFastMode === undefined) delete disk.fastMode;
+        else disk.fastMode = nextFastMode;
+      }
+      return { changed: true, value: true };
+    });
+    if (persisted.status === "unavailable") return jsonResponse({ error: "management persistence unavailable" }, 500, req, config);
+    config.claudeCode = committedClaude;
+    if (body.fastMode !== undefined) {
+      if (nextFastMode === undefined) deleteConfigTopLevelKey(config, "fastMode");
+      else config.fastMode = nextFastMode;
+    }
     const warnings: string[] = [];
     // authMode changes must reconcile the injected system env too: switching back to
     // Subscription has to remove the opencodex-owned dummy ANTHROPIC_AUTH_TOKEN

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

@@ -11,7 +11,6 @@ import {
   multiAgentGuidanceEnabled,
   providerBaseUrlConfigError,
   providerHeadersConfigError,
-  saveConfigPreservingClaudeCode,
 } from "../../config";
 import {
   clearLoginState,
@@ -63,7 +62,7 @@ import { applySystemEnvToggle } from "../system-env";
 
 import { isPlainRecord, parseDebugLogQuery, tokPerSecondResult, unavailableCostReason, costResult, requestLogDto, stripRegistryOnlyStaticHeaders, fetchAllModels } from "./shared";
 import type { MetricUnavailableReason, TokPerSecondResult, CostEstimateReason, CostResult, MetricSource } from "./shared";
-import type { ManagementContext } from "./context";
+import { saveManagementConfig, type ManagementContext } from "./context";
 import { readManagementJsonBody, rethrowManagementBodyTooLarge } from "./body";
 
 
@@ -236,7 +235,7 @@ export async function handleComboRoutes(ctx: ManagementContext): Promise<Respons
         oldDisabledSelectors.has(model) ? newDisabledModel : model
       )))];
     }
-    saveConfigPreservingClaudeCode(config);
+    saveManagementConfig(deps, config);
     reconcileLiveStateStores();
     clearComboSelectionState(id);
     clearComboTargetCooldowns(id);
@@ -259,7 +258,7 @@ export async function handleComboRoutes(ctx: ManagementContext): Promise<Respons
     const { clearComboSelectionState, clearComboTargetCooldowns } = await import("../../combos");
     delete config.combos![id];
     if (Object.keys(config.combos!).length === 0) deleteConfigTopLevelKey(config, "combos");
-    saveConfigPreservingClaudeCode(config);
+    saveManagementConfig(deps, config);
     reconcileLiveStateStores();
     clearComboSelectionState(id);
     clearComboTargetCooldowns(id);

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

@@ -11,7 +11,6 @@ import {
   multiAgentGuidanceEnabled,
   providerBaseUrlConfigError,
   providerHeadersConfigError,
-  saveConfigPreservingClaudeCode,
 } from "../../config";
 import {
   clearLoginState,
@@ -102,7 +101,7 @@ import { displayCodexRuntimePath, effortClampAppliesToRuntime, loadLastEffortCla
 
 import { isPlainRecord, parseDebugLogQuery, tokPerSecondResult, unavailableCostReason, costResult, requestLogDto, stripRegistryOnlyStaticHeaders, fetchAllModels } from "./shared";
 import type { MetricUnavailableReason, TokPerSecondResult, CostEstimateReason, CostResult, MetricSource } from "./shared";
-import type { ManagementContext } from "./context";
+import { mutateManagementConfig, saveManagementConfig, type ManagementContext } from "./context";
 import { readManagementJsonBody, rethrowManagementBodyTooLarge } from "./body";
 
 async function sidecarVisionResponseSettings(config: OcxConfig): Promise<{
@@ -469,7 +468,7 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
         config.showCodexSparkQuota = body.showCodexSparkQuota;
       }
       pickerIsEnabled = codexAccountPickerEnabled(config);
-      (deps.saveConfigPreservingClaudeCode ?? saveConfigPreservingClaudeCode)(config);
+      saveManagementConfig(deps, config);
     } catch (error) {
       if (previousSettings.hasCodexAutoStart) config.codexAutoStart = previousSettings.codexAutoStart;
       else deleteConfigTopLevelKey(config, "codexAutoStart");
@@ -698,6 +697,7 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
         : normalizeVisionReasoningForModel(model, sourceReasoning);
     }
 
+    const nextConfig = structuredClone(config);
     if (body.webSearch) {
       const pairTouched = body.webSearch.model !== undefined || body.webSearch.backend !== undefined;
       // Validate against the backend the caller SUBMITTED, across the whole
@@ -723,7 +723,7 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
           return jsonResponse(webSearchModelRejection("webSearch.model", effectiveBackend, effectiveModel, candidates), 400);
         }
       }
-      const webSearchCandidate = { ...config.webSearchSidecar };
+      const webSearchCandidate = { ...nextConfig.webSearchSidecar };
       if (typeof body.webSearch.model === "string") {
         if (body.webSearch.model === "") delete webSearchCandidate.model;
         else webSearchCandidate.model = body.webSearch.model;
@@ -793,36 +793,63 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
         if (body.webSearch.streamRoutedModelOutput) webSearchCandidate.streamRoutedModelOutput = true;
         else delete webSearchCandidate.streamRoutedModelOutput;
       }
-      config.webSearchSidecar = webSearchCandidate;
+      nextConfig.webSearchSidecar = webSearchCandidate;
     }
     if (body.vision) {
-      config.visionSidecar = { ...config.visionSidecar };
+      nextConfig.visionSidecar = { ...nextConfig.visionSidecar };
       if (typeof body.vision.model === "string") {
-        if (body.vision.model === "") delete config.visionSidecar.model;
-        else config.visionSidecar.model = body.vision.model;
+        if (body.vision.model === "") delete nextConfig.visionSidecar.model;
+        else nextConfig.visionSidecar.model = body.vision.model;
       }
-      if (body.vision.backend === null) delete config.visionSidecar.backend;
+      if (body.vision.backend === null) delete nextConfig.visionSidecar.backend;
       else if (body.vision.backend === "openai" || body.vision.backend === "anthropic"
         || body.vision.backend === "routed") {
-        config.visionSidecar.backend = body.vision.backend;
+        nextConfig.visionSidecar.backend = body.vision.backend;
       }
       if (typeof body.vision.maxDescriptionsPerTurn === "number") {
-        config.visionSidecar.maxDescriptionsPerTurn = body.vision.maxDescriptionsPerTurn;
+        nextConfig.visionSidecar.maxDescriptionsPerTurn = body.vision.maxDescriptionsPerTurn;
       }
       if (typeof body.vision.enabled === "boolean") {
         // `true` is the default — drop the key so disable/re-enable does not rewrite the file.
-        if (body.vision.enabled) delete config.visionSidecar.enabled;
-        else config.visionSidecar.enabled = false;
+        if (body.vision.enabled) delete nextConfig.visionSidecar.enabled;
+        else nextConfig.visionSidecar.enabled = false;
       }
       if (typeof body.vision.timeoutMs === "number") {
-        config.visionSidecar.timeoutMs = body.vision.timeoutMs;
+        nextConfig.visionSidecar.timeoutMs = body.vision.timeoutMs;
       }
       if (visionReasoningTouched) {
-        if (normalizedVisionReasoning === undefined) delete config.visionSidecar.reasoning;
-        else config.visionSidecar.reasoning = normalizedVisionReasoning;
+        if (normalizedVisionReasoning === undefined) delete nextConfig.visionSidecar.reasoning;
+        else nextConfig.visionSidecar.reasoning = normalizedVisionReasoning;
       }
     }
-    saveConfigPreservingClaudeCode(config);
+    let committedWebSearch: OcxConfig["webSearchSidecar"];
+    let committedVision: OcxConfig["visionSidecar"];
+    const persisted = mutateManagementConfig(deps, disk => {
+      if (body.webSearch) {
+        const latest = { ...disk.webSearchSidecar };
+        for (const key of ["model", "backend", "reasoning", "streamRoutedModelOutput", "exaApiKey", "xSearch"] as const) {
+          if (!Object.hasOwn(body.webSearch, key)) continue;
+          if (Object.hasOwn(nextConfig.webSearchSidecar ?? {}, key)) latest[key] = nextConfig.webSearchSidecar![key] as never;
+          else delete latest[key];
+        }
+        disk.webSearchSidecar = latest;
+        committedWebSearch = structuredClone(latest);
+      }
+      if (body.vision) {
+        const latest = { ...disk.visionSidecar };
+        for (const key of ["model", "backend", "reasoning", "maxDescriptionsPerTurn", "enabled", "timeoutMs"] as const) {
+          if (!Object.hasOwn(body.vision, key) && !(key === "reasoning" && visionReasoningTouched)) continue;
+          if (Object.hasOwn(nextConfig.visionSidecar ?? {}, key)) latest[key] = nextConfig.visionSidecar![key] as never;
+          else delete latest[key];
+        }
+        disk.visionSidecar = latest;
+        committedVision = structuredClone(latest);
+      }
+      return { changed: true, value: true };
+    });
+    if (persisted.status === "unavailable") return jsonResponse({ error: "management persistence unavailable" }, 500, req, config);
+    if (body.webSearch) config.webSearchSidecar = committedWebSearch;
+    if (body.vision) config.visionSidecar = committedVision;
     const ws = config.webSearchSidecar ?? {};
     const vision = await sidecarVisionResponseSettings(config);
     const savedWebSearchCandidates = await webSearchCandidateRows(config);
@@ -869,7 +896,7 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
       if (body.model === "") delete config.shadowCallIntercept.model;
       else config.shadowCallIntercept.model = body.model;
     }
-    saveConfigPreservingClaudeCode(config);
+    saveManagementConfig(deps, config);
     const sci = config.shadowCallIntercept;
     return jsonResponse({
       ok: true,