@yansigit/opencodex 2.31.3 → 2.33.0

package/src/server/index.ts

@@ -22,10 +22,11 @@ import {
 import { reconcileOAuthProviders } from "../oauth";
 import { withCatalogWriteSerialization } from "../codex/catalog-write-serialization";
 import { invalidateCodexModelsCacheWithPermit } from "../codex/catalog/sync";
-import { getCodexHome } from "../codex/paths";
+import { currentServiceHomes, serviceStatePathsForOpenCodexHome } from "../service";
 import { shouldSyncCodexOnStart } from "../codex/desired-state";
 import {
   inspectNativeCodexOwnership,
+  type NativeCodexOwnership,
   type OwnershipInspection,
 } from "../integrations/native/ownership-preflight";
 import { registerCodexCooldownRecoveryProbeWorker } from "../codex/auth-api";
@@ -175,8 +176,8 @@ import { runClaudeAuthModeMigration } from "../claude/auth-mode-migration";
 import {
   bindNativeMainStartupLifecycle,
   blockNativeMainStartupForUnownedServiceHome,
+  prepareNativeMainStartupLifecycle,
   releaseNativeMainStartupLifecycle,
-  startNativeMainStartupLifecycle,
   type NativeMainStartupGateDeps,
   type NativeMainStartupLifecycle,
 } from "../codex/native-profile-startup";
@@ -444,6 +445,8 @@ export interface StartServerDeps {
   nativeMainStartup?: NativeMainStartupGateDeps;
   /** Test-only ownership evidence; production inspects the installed service state. */
   inspectNativeCodexOwnership?: typeof inspectNativeCodexOwnership;
+  /** Test-only service-home resolver; production resolves the current homes directly. */
+  resolveServiceHomes?: typeof currentServiceHomes;
   /** Test-only seam for an upstream that cannot complete its WebSocket close handshake. */
   liveSidebandWebSocketFactory?: LiveSidebandWebSocketFactory;
   /** Test-only seam; production derives a fresh local-attestation secret per process. */
@@ -452,9 +455,22 @@ export interface StartServerDeps {
   readinessGate?: ReadinessGate;
 }
 
-function inspectStartupOwnership(deps: StartServerDeps): OwnershipInspection {
+function inspectStartupOwnership(
+  deps: StartServerDeps,
+  currentHomes: ReturnType<typeof currentServiceHomes> | null,
+  statePaths: readonly string[] | null,
+): OwnershipInspection {
   try {
-    return (deps.inspectNativeCodexOwnership ?? inspectNativeCodexOwnership)();
+    if (currentHomes === null || statePaths === null) {
+      return {
+        ownership: "unknown",
+        reason: "startup service-home resolution failed",
+      };
+    }
+    if (deps.inspectNativeCodexOwnership) {
+      return deps.inspectNativeCodexOwnership({ currentHomes, statePaths });
+    }
+    return inspectNativeCodexOwnership({ currentHomes, statePaths });
   } catch {
     return {
       ownership: "unknown",
@@ -541,15 +557,27 @@ export function startServer(port?: number, deps: StartServerDeps = {}): Server<W
   // journal, or credential path. Both positive foreign evidence and an unprovable
   // ownership state are non-authority.
   startupCacheInvalidationWrote = false;
-  const startupCacheOwnership = inspectStartupOwnership(deps);
+  const resolveServiceHomes = deps.resolveServiceHomes ?? currentServiceHomes;
+  let startupOwnershipHomes: ReturnType<typeof currentServiceHomes> | null = null;
+  let startupOwnershipStatePaths: readonly string[] | null = null;
+  try {
+    const homes = resolveServiceHomes();
+    const statePaths = serviceStatePathsForOpenCodexHome(homes.opencodexHome);
+    startupOwnershipHomes = homes;
+    startupOwnershipStatePaths = statePaths;
+  } catch { /* inspection below stays unknown */ }
+  const startupCacheOwnership = inspectStartupOwnership(
+    deps,
+    startupOwnershipHomes,
+    startupOwnershipStatePaths,
+  );
   // Startup cache invalidation is best-effort and must never block the server from
-  // serving. It now takes K so it cannot race a convergence commit, but both the
-  // home resolution and the acquisition can fail on a machine with no Codex home —
-  // `getCodexHome()` THROWS when CODEX_HOME names a missing directory, which would
-  // otherwise turn "no Codex installed" into "proxy will not start".
-  if (startupCacheOwnership.ownership === "owned") {
+  // serving. It now takes K so it cannot race a convergence commit. Use the home
+  // paired with the ownership inspection; re-reading ambient CODEX_HOME here could
+  // invalidate a different installation after an environment or mount change.
+  if (startupCacheOwnership.ownership === "owned" && startupOwnershipHomes !== null) {
     try {
-      const startupCodexHome = getCodexHome();
+      const startupCodexHome = startupOwnershipHomes.codexHome;
       // #1046: record whether this actually rewrote the cache. `handleStart` ORs this
       // with the later startup sync and warns ONCE about stale app-servers; warning
       // here instead would read a catalog mtime the sync is about to move.
@@ -706,18 +734,71 @@ export function startServer(port?: number, deps: StartServerDeps = {}): Server<W
   // clients; no Codex request can use this lifecycle in that state.
   // Re-probe here instead of trusting the earlier cache decision: startup work
   // between the two sites must not widen the service-install race.
-  const nativeOwnership = inspectStartupOwnership(deps);
+  const nativeOwnership = inspectStartupOwnership(deps, startupOwnershipHomes, startupOwnershipStatePaths);
+  const preparedNativeMainLifecycle = nativeOwnership.ownership !== "foreign"
+    && startupOwnershipHomes !== null
+    ? prepareNativeMainStartupLifecycle(
+      deps.nativeMainStartup,
+      { codexHome: startupOwnershipHomes.codexHome, configDir: startupOwnershipHomes.opencodexHome },
+    )
+    : null;
+  let retryOwnershipHomes = startupOwnershipHomes;
+  let retryOwnershipStatePaths = startupOwnershipStatePaths;
+  let retryPreparedNativeMainLifecycle = preparedNativeMainLifecycle;
+  const reprobeNativeOwnership = (): NativeCodexOwnership => {
+    // If startup could not resolve the homes at all, preserve a bounded retry
+    // without guessing an authority. The first successful resolution is pinned
+    // together with its service-state paths before ownership is inspected.
+    if (retryOwnershipHomes === null || retryOwnershipStatePaths === null) {
+      try {
+        const homes = resolveServiceHomes();
+        const statePaths = serviceStatePathsForOpenCodexHome(homes.opencodexHome);
+        retryOwnershipHomes = homes;
+        retryOwnershipStatePaths = statePaths;
+      } catch {
+        return "unknown";
+      }
+    }
+    const homes = retryOwnershipHomes;
+    const statePaths = retryOwnershipStatePaths;
+    const answer = inspectStartupOwnership(deps, homes, statePaths).ownership;
+    if (answer !== "owned") return answer;
+    retryPreparedNativeMainLifecycle ??= prepareNativeMainStartupLifecycle(
+      deps.nativeMainStartup,
+      { codexHome: homes.codexHome, configDir: homes.opencodexHome },
+    );
+    // An ownership verdict without a lifecycle bound to that same home is not
+    // enough to reopen native-main admission.
+    return retryPreparedNativeMainLifecycle ? "owned" : "unknown";
+  };
+  const ownershipRetryOptions = {
+    reprobe: reprobeNativeOwnership,
+    expectedHomeId: () => retryPreparedNativeMainLifecycle?.homeId ?? null,
+    startOwnedLifecycle: () => {
+      if (!retryPreparedNativeMainLifecycle) {
+        throw new Error("Native-main ownership became known before its startup lifecycle was prepared.");
+      }
+      return retryPreparedNativeMainLifecycle.start();
+    },
+  };
   const nativeMainLifecycle: NativeMainStartupLifecycle = shouldSyncCodexOnStart(config)
     ? nativeOwnership.ownership === "owned"
-      ? startNativeMainStartupLifecycle(deps.nativeMainStartup)
-      : blockNativeMainStartupForUnownedServiceHome(
-        nativeOwnership.ownership === "foreign" ? "foreign-ownership" : "ownership-unknown",
-        // #2108: an `unknown` verdict means the probe could not answer, not that this host
-        // is unownable. Hand the fence a way to re-ask so a host that becomes answerable
-        // after boot reopens on its own instead of needing `ocx restart`. A `foreign`
-        // verdict ignores this by design — that one is a fact, not a question.
-        { reprobe: () => inspectStartupOwnership(deps).ownership },
-      )
+      ? preparedNativeMainLifecycle
+        ? preparedNativeMainLifecycle.start()
+        : blockNativeMainStartupForUnownedServiceHome(
+          "ownership-unknown",
+          ownershipRetryOptions,
+        )
+      : nativeOwnership.ownership === "foreign"
+        ? blockNativeMainStartupForUnownedServiceHome("foreign-ownership")
+        : blockNativeMainStartupForUnownedServiceHome(
+          "ownership-unknown",
+          // #2108: an `unknown` verdict means the probe could not answer, not that this host
+          // is unownable. Hand the fence a way to re-ask so a host that becomes answerable
+          // after boot reopens on its own instead of needing `ocx restart`. A `foreign`
+          // verdict ignores this by design — that one is a fact, not a question.
+          ownershipRetryOptions,
+        )
     : {
       homeId: null,
       settled: Promise.resolve({ status: "ready", homeId: null }),

package/src/server/local-management-read-client.ts

@@ -1,4 +1,4 @@
-import { readRuntimePort, type RuntimePortState } from "../config";
+import { readRuntimePort, type RuntimePortState } from "../config/process-state";
 import { createLocalAttestationChallenge } from "../lib/local-management-attestation";
 import {
   LOCAL_MANAGEMENT_CAPABILITY_HEADER,

package/src/server/local-provider-reload-client.ts

@@ -1,4 +1,4 @@
-import { readRuntimePort, type RuntimePortState } from "../config";
+import { readRuntimePort, type RuntimePortState } from "../config/process-state";
 import {
   LOCAL_ATTESTATION_CHALLENGE_HEADER,
   LOCAL_ATTESTATION_PROOF_HEADER,

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

@@ -60,6 +60,7 @@ import {
   webSearchCandidateRows,
   webSearchModelIsRejected,
   webSearchModelRejection,
+  type WebSearchBackend,
 } from "./web-search-sidecar-options";
 import { drainAndShutdown } from "../lifecycle";
 import { filterRequestLogs, getRequestLogEntries, type RequestLogEntry } from "../request-log";
@@ -67,6 +68,7 @@ import { estimateComboCost, estimateRequestCost, normalizeCostTokens, tokensPerS
 import type { PersistedUsageAttempt } from "../../usage/log";
 import { isAllowedRequestOrigin, jsonResponse, providerManagementConfigError, publicProviderBaseUrl, safeConfigDTO } from "../auth-cors";
 import { applySystemEnvToggle } from "../system-env";
+import { routeModel } from "../../router";
 
 import { isPlainRecord, parseDebugLogQuery, tokPerSecondResult, unavailableCostReason, costResult, requestLogDto, stripRegistryOnlyStaticHeaders, fetchAllModels, fetchGrokCandidateModels, buildClaudeDesktopState } from "./shared";
 import {
@@ -86,6 +88,90 @@ let grokApplyFlight: { startedAt: number; promise: Promise<unknown>; bytes: numb
 let grokApplyHighWaterBytes = 0;
 let grokApplyTestHooks: { now?: () => number; run?: () => Promise<unknown> } | null = null;
 
+type V2NativeParentOverrideInput = { enabled: boolean; model: string | null };
+type AgentTaskRecoveryInput = { enabled: boolean; model: string | null };
+
+function agentTaskRecoveryDto(
+  config: OcxConfig,
+): { enabled: boolean; model: string | null } {
+  const recovery = config.agentTaskRecovery;
+  return {
+    enabled: recovery?.enabled === true,
+    model: recovery?.model ?? null,
+  };
+}
+
+function persistAgentTaskRecovery(
+  config: OcxConfig,
+  next: AgentTaskRecoveryInput,
+): { ok: true } | { ok: false; reason: string } {
+  const outcome = mutatePersistedConfig(persisted => {
+    const nextPersisted = {
+      enabled: next.enabled,
+      ...(next.model === null ? {} : { model: next.model }),
+    };
+    const previous = persisted.agentTaskRecovery;
+    const changed = previous?.enabled !== nextPersisted.enabled || previous?.model !== nextPersisted.model;
+    if (changed) persisted.agentTaskRecovery = nextPersisted;
+    return { changed, value: true };
+  });
+  if (outcome.status === "unavailable") return { ok: false, reason: outcome.reason };
+  config.agentTaskRecovery = {
+    enabled: next.enabled,
+    ...(next.model === null ? {} : { model: next.model }),
+  };
+  return { ok: true };
+}
+
+function v2NativeParentOverrideDto(
+  config: OcxConfig,
+  upstreamEnabled: boolean,
+): { enabled: boolean; model: string | null; active: boolean } {
+  const override = config.v2NativeParentOverride;
+  const enabled = override?.enabled === true;
+  const model = override?.model ?? null;
+  return {
+    enabled,
+    model,
+    active: enabled
+      && model !== null
+      && v2NativeParentOverrideTargetIsNoncanonical(config, model)
+      && config.multiAgentMode === "v2"
+      && upstreamEnabled
+      && config.keepNativeChatGptOnV1 !== true,
+  };
+}
+
+function v2NativeParentOverrideTargetIsNoncanonical(config: OcxConfig, model: string): boolean {
+  try {
+    return !isCanonicalOpenAiForwardProvider(routeModel(config, model).provider);
+  } catch {
+    return false;
+  }
+}
+
+function persistV2NativeParentOverride(
+  config: OcxConfig,
+  next: V2NativeParentOverrideInput,
+): { ok: true } | { ok: false; reason: string } {
+  const outcome = mutatePersistedConfig(persisted => {
+    const nextPersisted = {
+      enabled: next.enabled,
+      ...(next.model === null ? {} : { model: next.model }),
+    };
+    const previous = persisted.v2NativeParentOverride;
+    const changed = previous?.enabled !== nextPersisted.enabled || previous?.model !== nextPersisted.model;
+    if (changed) persisted.v2NativeParentOverride = nextPersisted;
+    return { changed, value: true };
+  });
+  if (outcome.status === "unavailable") return { ok: false, reason: outcome.reason };
+  config.v2NativeParentOverride = {
+    enabled: next.enabled,
+    ...(next.model === null ? {} : { model: next.model }),
+  };
+  return { ok: true };
+}
+
 class GrokApplyBusyError extends Error {}
 
 /**
@@ -155,7 +241,7 @@ function runGrokApplyFlight(): Promise<unknown> {
   flight.promise = (grokApplyTestHooks?.run ?? (async () => {
     const [{ syncGrokConfig }, { readRuntimePort }] = await Promise.all([
       import("../../grok/sync"),
-      import("../../config"),
+      import("../../config/process-state"),
     ]);
     const currentConfig = loadConfig();
     const runtime = readRuntimePort(process.pid);
@@ -240,6 +326,7 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
       getMultiAgentModeHintText,
     } = await import("../../codex/features");
     const enabled = isMultiAgentV2Enabled();
+    const v2NativeParentOverride = v2NativeParentOverrideDto(config, enabled);
     return jsonResponse({
       enabled,
       agentsMaxThreadsConflict: enabled && hasAgentsMaxThreads(),
@@ -253,6 +340,8 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
       // 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,
+      v2NativeParentOverride,
+      agentTaskRecovery: agentTaskRecoveryDto(config),
     });
   }
   if (url.pathname === "/api/v2" && req.method === "PUT") {
@@ -265,6 +354,8 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
       agentsMaxDepth?: unknown;
       subagentDeveloperInstructions?: unknown;
       multiAgentModeHintText?: unknown;
+      v2NativeParentOverride?: unknown;
+      agentTaskRecovery?: unknown;
     };
     try { body = await readManagementJsonBody(req); } catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid JSON body" }, 400); }
     const wantsFlag = body.enabled !== undefined;
@@ -275,8 +366,10 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
     const wantsMaxDepth = body.agentsMaxDepth !== undefined;
     const wantsSubagentInstructions = body.subagentDeveloperInstructions !== undefined;
     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);
+    const wantsV2NativeParentOverride = body.v2NativeParentOverride !== undefined;
+    const wantsAgentTaskRecovery = body.agentTaskRecovery !== undefined;
+    if (!wantsFlag && !wantsThreads && !wantsMode && !wantsKeepNative && !wantsAgentsEnabled && !wantsMaxDepth && !wantsSubagentInstructions && !wantsModeHintText && !wantsV2NativeParentOverride && !wantsAgentTaskRecovery) {
+      return jsonResponse({ error: "body must set enabled, multiAgentMode, keepNativeChatGptOnV1, maxConcurrentThreadsPerSession, agentsEnabled, agentsMaxDepth, subagentDeveloperInstructions, multiAgentModeHintText, v2NativeParentOverride, and/or agentTaskRecovery" }, 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") {
@@ -316,6 +409,92 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
     if (wantsFlag && modeFlag !== undefined && body.enabled !== modeFlag) {
       return jsonResponse({ error: `body.enabled conflicts with multiAgentMode '${mode}'` }, 400);
     }
+    const { isMultiAgentV2Enabled: readMultiAgentV2Enabled } = await import("../../codex/features");
+    const currentUpstreamEnabled = readMultiAgentV2Enabled();
+    const prospectiveMode = mode ?? config.multiAgentMode ?? "default";
+    const prospectiveKeepNative = wantsKeepNative
+      ? body.keepNativeChatGptOnV1 === true
+      : config.keepNativeChatGptOnV1 === true;
+    const prospectiveUpstreamEnabled = wantsFlag
+      ? body.enabled as boolean
+      : modeFlag ?? currentUpstreamEnabled;
+    let v2NativeParentOverride: V2NativeParentOverrideInput | undefined;
+    if (wantsV2NativeParentOverride) {
+      const raw = body.v2NativeParentOverride;
+      if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        return jsonResponse({ error: "body.v2NativeParentOverride must be an object" }, 400);
+      }
+      const keys = Object.keys(raw as object);
+      if (keys.length !== 2 || !keys.includes("enabled") || !keys.includes("model")) {
+        return jsonResponse({ error: "body.v2NativeParentOverride must contain enabled and model" }, 400);
+      }
+      const candidate = raw as { enabled?: unknown; model?: unknown };
+      if (typeof candidate.enabled !== "boolean") {
+        return jsonResponse({ error: "body.v2NativeParentOverride.enabled must be a boolean" }, 400);
+      }
+      if (candidate.model !== null && (typeof candidate.model !== "string" || candidate.model.trim().length === 0)) {
+        return jsonResponse({ error: "body.v2NativeParentOverride.model must be a nonblank string or null" }, 400);
+      }
+      v2NativeParentOverride = {
+        enabled: candidate.enabled,
+        model: candidate.model === null ? null : (candidate.model as string).trim(),
+      };
+      if (v2NativeParentOverride.model !== null) {
+        let target;
+        try {
+          target = routeModel(config, v2NativeParentOverride.model);
+        } catch {
+          return jsonResponse({ error: "body.v2NativeParentOverride.model must resolve to a configured provider" }, 400);
+        }
+        if (isCanonicalOpenAiForwardProvider(target.provider)) {
+          return jsonResponse({ error: "body.v2NativeParentOverride.model must resolve to a noncanonical provider" }, 400);
+        }
+      }
+      if (v2NativeParentOverride.enabled) {
+        if (v2NativeParentOverride.model === null) {
+          return jsonResponse({ error: "enabling v2NativeParentOverride requires a model" }, 400);
+        }
+        if (prospectiveMode !== "v2") {
+          return jsonResponse({ error: "enabling v2NativeParentOverride requires multiAgentMode 'v2'" }, 400);
+        }
+        if (!prospectiveUpstreamEnabled) {
+          return jsonResponse({ error: "enabling v2NativeParentOverride requires the upstream V2 feature" }, 400);
+        }
+        if (prospectiveKeepNative) {
+          return jsonResponse({ error: "enabling v2NativeParentOverride conflicts with keepNativeChatGptOnV1" }, 400);
+        }
+      }
+    }
+    let agentTaskRecovery: AgentTaskRecoveryInput | undefined;
+    if (wantsAgentTaskRecovery) {
+      const raw = body.agentTaskRecovery;
+      if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        return jsonResponse({ error: "body.agentTaskRecovery must be an object" }, 400);
+      }
+      const candidate = raw as { enabled?: unknown; model?: unknown };
+      if (typeof candidate.enabled !== "boolean") {
+        return jsonResponse({ error: "body.agentTaskRecovery.enabled must be a boolean" }, 400);
+      }
+      if (candidate.model !== undefined && candidate.model !== null && (typeof candidate.model !== "string" || candidate.model.trim().length === 0)) {
+        return jsonResponse({ error: "body.agentTaskRecovery.model must be a nonblank string or null" }, 400);
+      }
+      agentTaskRecovery = {
+        enabled: candidate.enabled,
+        model: candidate.model === null || candidate.model === undefined ? null : (candidate.model as string).trim(),
+      };
+    }
+    if (agentTaskRecovery && !wantsFlag && !wantsThreads && !wantsMode && !wantsKeepNative
+        && !wantsAgentsEnabled && !wantsMaxDepth && !wantsSubagentInstructions && !wantsModeHintText && !wantsV2NativeParentOverride) {
+      const persisted = persistAgentTaskRecovery(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);
+      if (!persisted.ok) return jsonResponse({ error: `persisting v2NativeParentOverride failed: ${persisted.reason}` }, 502);
+      return jsonResponse({ ok: true, v2NativeParentOverride: v2NativeParentOverrideDto(config, readMultiAgentV2Enabled()) });
+    }
     const {
       isMultiAgentV2Enabled, hasAgentsMaxThreads, getLogicalMaxThreads, transitionMultiAgentV2,
       getAgentsEnabled, getAgentsMaxDepth, getSubagentDeveloperInstructions,
@@ -394,6 +573,14 @@ 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 (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();
@@ -409,6 +596,8 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
       subagentDeveloperInstructions: getSubagentDeveloperInstructions(),
       multiAgentModeHintText: getMultiAgentModeHintText(),
       agentsMaxDepthAppliesWhenV2Disabled: !enabled,
+      v2NativeParentOverride: v2NativeParentOverrideDto(config, enabled),
+      agentTaskRecovery: agentTaskRecoveryDto(config),
       warnings,
       catalogRefresh,
     });
@@ -720,19 +909,15 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
     if (!("roles" in body)) return jsonResponse({ error: "body.roles is required" }, 400);
     const parsed = parseSubagentRoles(body.roles);
     if (!parsed.ok) return jsonResponse({ error: parsed.error, index: parsed.index }, 400);
-    if ("syncCodexAgentRoles" in body && body.syncCodexAgentRoles !== null) {
-      if (typeof body.syncCodexAgentRoles !== "boolean") {
-        return jsonResponse({ error: "syncCodexAgentRoles must be a boolean" }, 400);
-      }
+    if ("syncCodexAgentRoles" in body && body.syncCodexAgentRoles !== null && typeof body.syncCodexAgentRoles !== "boolean") {
+      return jsonResponse({ error: "syncCodexAgentRoles must be a boolean" }, 400);
     }
-
     const warnings: string[] = [];
     const union = unionRoleModelsIntoRoster(config.subagentModels, parsed.roles);
     if (union.droppedRoleIds.length > 0) {
       warnings.push(`Featured roster truncated to 5 models; dropped role id(s): ${union.droppedRoleIds.join(", ")}`);
     }
     warnings.push(...routedOnV2Warnings(parsed.roles, config));
-
     config.subagentRoles = parsed.roles;
     config.subagentModels = union.models;
     if ("syncCodexAgentRoles" in body && typeof body.syncCodexAgentRoles === "boolean") {
@@ -1217,13 +1402,18 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
       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";
+        // Validate against the SUBMITTED backend across the whole union, not
+        // just openai/anthropic (#2457). allowedBackends above already refused
+        // unknown literals; Array.includes does not narrow, hence the cast.
+        // null keeps its own meaning here — drop the override and inherit the
+        // global backend — which is deliberately NOT the sidecar-settings rule.
+        const submittedBackend = section.backend;
+        const effectiveBackend = typeof submittedBackend === "string"
+          && allowedBackends.includes(submittedBackend)
+          ? submittedBackend as WebSearchBackend
+          : submittedBackend === null
+            ? config.webSearchSidecar?.backend ?? "openai"
+            : stored?.backend ?? config.webSearchSidecar?.backend ?? "openai";
         const effectiveModel = section.model === ""
           ? config.webSearchSidecar?.model
           : typeof section.model === "string"

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

@@ -200,6 +200,12 @@ export async function handleComboRoutes(ctx: ManagementContext): Promise<Respons
       if (config.injectionModel && migratedModels.has(config.injectionModel)) {
         config.injectionModel = migrateReference(config.injectionModel);
       }
+      if (config.v2NativeParentOverride?.model && migratedModels.has(config.v2NativeParentOverride.model)) {
+        config.v2NativeParentOverride = {
+          ...config.v2NativeParentOverride,
+          model: migrateReference(config.v2NativeParentOverride.model),
+        };
+      }
       if (config.shadowCallIntercept?.model && migratedModels.has(config.shadowCallIntercept.model)) {
         config.shadowCallIntercept = {
           ...config.shadowCallIntercept,

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

@@ -298,6 +298,9 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
       streamMode: config.streamMode ?? "auto",
       appOwnedMemoryBudgetMb: config.appOwnedMemoryBudgetMb ?? 256,
       codexAccountPickerEnabled: codexAccountPickerEnabled(config),
+      // Absent means the historical auto-open, so the GUI can render the toggle
+      // without having to know that `undefined` and `true` mean the same thing.
+      oauthOpenBrowser: config.oauthOpenBrowser !== false,
       startupHealth: await readStartupHealth(config),
       codexRuntime: {
         path: displayCodexRuntimePath(resolved.runtime.command),
@@ -382,16 +385,21 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
       streamMode?: unknown;
       appOwnedMemoryBudgetMb?: unknown;
       codexAccountPickerEnabled?: unknown;
+      oauthOpenBrowser?: unknown;
     };
     if (body.codexAutoStart === undefined
       && body.streamMode === undefined
       && body.appOwnedMemoryBudgetMb === undefined
-      && body.codexAccountPickerEnabled === undefined) {
-      return jsonResponse({ error: "provide codexAutoStart, streamMode, appOwnedMemoryBudgetMb, or codexAccountPickerEnabled" }, 400);
+      && body.codexAccountPickerEnabled === undefined
+      && body.oauthOpenBrowser === undefined) {
+      return jsonResponse({ error: "provide codexAutoStart, streamMode, appOwnedMemoryBudgetMb, codexAccountPickerEnabled, or oauthOpenBrowser" }, 400);
     }
     if (body.codexAutoStart !== undefined && typeof body.codexAutoStart !== "boolean") {
       return jsonResponse({ error: "codexAutoStart boolean is required" }, 400);
     }
+    if (body.oauthOpenBrowser !== undefined && typeof body.oauthOpenBrowser !== "boolean") {
+      return jsonResponse({ error: "oauthOpenBrowser boolean is required" }, 400);
+    }
     if (body.streamMode !== undefined && !isStreamMode(body.streamMode)) {
       return jsonResponse({ error: "streamMode must be auto, legacy-tee, or eager-relay" }, 400);
     }
@@ -418,6 +426,8 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
       hasCodexAccountNamespaces: Object.hasOwn(config, "codexAccountNamespaces"),
       codexAccountPickerEnabled: config.codexAccountPickerEnabled,
       hasCodexAccountPickerEnabled: Object.hasOwn(config, "codexAccountPickerEnabled"),
+      oauthOpenBrowser: config.oauthOpenBrowser,
+      hasOauthOpenBrowser: Object.hasOwn(config, "oauthOpenBrowser"),
     };
     const pickerWasEnabled = codexAccountPickerEnabled(config);
     let pickerIsEnabled = pickerWasEnabled;
@@ -441,6 +451,9 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
       } else if (body.codexAccountPickerEnabled === false) {
         config.codexAccountPickerEnabled = false;
       }
+      if (typeof body.oauthOpenBrowser === "boolean") {
+        config.oauthOpenBrowser = body.oauthOpenBrowser;
+      }
       pickerIsEnabled = codexAccountPickerEnabled(config);
       (deps.saveConfigPreservingClaudeCode ?? saveConfigPreservingClaudeCode)(config);
     } catch (error) {
@@ -457,6 +470,9 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
       if (previousSettings.hasCodexAccountPickerEnabled) {
         config.codexAccountPickerEnabled = previousSettings.codexAccountPickerEnabled;
       } else delete config.codexAccountPickerEnabled;
+      if (previousSettings.hasOauthOpenBrowser) {
+        config.oauthOpenBrowser = previousSettings.oauthOpenBrowser;
+      } else delete config.oauthOpenBrowser;
       throw error;
     }
     if (typeof body.appOwnedMemoryBudgetMb === "number") {
@@ -476,6 +492,7 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
       streamMode: config.streamMode ?? "auto",
       appOwnedMemoryBudgetMb: config.appOwnedMemoryBudgetMb ?? 256,
       codexAccountPickerEnabled: pickerIsEnabled,
+      oauthOpenBrowser: config.oauthOpenBrowser !== false,
       catalogRefreshPending,
       startupHealth: await readStartupHealth(config),
     });
@@ -490,7 +507,10 @@ 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 { readRuntimePort, loadConfig } = await import("../../config");
+    const [{ readRuntimePort }, { loadConfig }] = await Promise.all([
+      import("../../config/process-state"),
+      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);
@@ -662,9 +682,18 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
 
     if (body.webSearch) {
       const pairTouched = body.webSearch.model !== undefined || body.webSearch.backend !== undefined;
-      const effectiveBackend = body.webSearch.backend === "anthropic"
-        ? "anthropic"
-        : body.webSearch.backend === "openai" || body.webSearch.backend === null
+      // Validate against the backend the caller SUBMITTED, across the whole
+      // union — not just openai/anthropic (#2457). The union check above has
+      // already refused unknown literals, so a surviving string is a member;
+      // Array.includes does not narrow, hence the cast. Falling back to the
+      // stored backend for xai/gemini/exa both rejected legal pairs and
+      // accepted illegal ones: a submitted gemini was checked against a stored
+      // openai. null means "unset the backend", and unset resolves to openai.
+      const submittedBackend = body.webSearch.backend;
+      const effectiveBackend = typeof submittedBackend === "string"
+        && WEB_SEARCH_BACKENDS_UNION.includes(submittedBackend as never)
+        ? submittedBackend as typeof WEB_SEARCH_BACKENDS_UNION[number]
+        : submittedBackend === null
           ? "openai"
           : config.webSearchSidecar?.backend ?? "openai";
       const effectiveModel = typeof body.webSearch.model === "string"

package/src/server/management/context.ts

@@ -8,7 +8,7 @@ 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 { RuntimePortState } from "../../config/process-state";
 import type { CatalogDisposition, ConvergeCodex } from "../../codex/convergence-types";
 import type {
   performCodexRestart,