@bitkyc08/opencodex 2.28.0 → 2.29.0

package/src/responses/reasoning-replay-cache.ts

@@ -52,8 +52,16 @@ interface CacheEntry {
   at: number;
 }
 
+interface ServingIdentityEntry {
+  identity: string;
+  bytes: number;
+  at: number;
+}
+
 const entries = new Map<string, CacheEntry>();
+const servingIdentities = new Map<string, ServingIdentityEntry>();
 let totalBytes = 0;
+let servingIdentityTotalBytes = 0;
 let clockForTests: (() => number) | null = null;
 
 const now = (): number => clockForTests?.() ?? Date.now();
@@ -62,28 +70,136 @@ function nonEmpty(value: unknown): value is string {
   return typeof value === "string" && value.trim().length > 0;
 }
 
-function keyFor(callId: string, scope: OcxReasoningReplayScopeRef | undefined): string | undefined {
-  const identity = scope?.current;
+type ReasoningReplayIdentityTuple = readonly [string, string, string, string, string];
+
+function tupleForIdentity(
+  identity: Readonly<OcxReasoningReplayIdentity> | undefined,
+): ReasoningReplayIdentityTuple | undefined {
   if (
-    !nonEmpty(callId)
-    || !nonEmpty(scope?.clientThreadId)
-    || !nonEmpty(identity?.providerName)
+    !nonEmpty(identity?.providerName)
     || !nonEmpty(identity?.providerDestinationIdentity)
     || !nonEmpty(identity?.adapterName)
     || !nonEmpty(identity?.modelId)
     || !nonEmpty(identity?.credentialIdentity)
   ) return undefined;
-  return JSON.stringify([
-    scope.clientThreadId,
+  return [
     identity.providerName,
     identity.providerDestinationIdentity,
     identity.adapterName,
     identity.modelId,
     identity.credentialIdentity,
+  ];
+}
+
+function tupleForServingIdentity(
+  identity: Readonly<OcxReasoningReplayIdentity> | undefined,
+): ReasoningReplayIdentityTuple | undefined {
+  if (
+    !nonEmpty(identity?.providerName)
+    || !nonEmpty(identity?.providerDestinationDurableIdentity)
+    || !nonEmpty(identity?.adapterName)
+    || !nonEmpty(identity?.modelId)
+    || !nonEmpty(identity?.credentialDurableIdentity)
+  ) return undefined;
+  return [
+    identity.providerName,
+    identity.providerDestinationDurableIdentity,
+    identity.adapterName,
+    identity.modelId,
+    identity.credentialDurableIdentity,
+  ];
+}
+
+function keyFor(callId: string, scope: OcxReasoningReplayScopeRef | undefined): string | undefined {
+  const identity = tupleForIdentity(scope?.current);
+  if (!nonEmpty(callId) || !nonEmpty(scope?.clientThreadId) || !identity) return undefined;
+  return JSON.stringify([
+    scope.clientThreadId,
+    ...identity,
     callId,
   ]);
 }
 
+function deleteServingIdentity(threadId: string): void {
+  const entry = servingIdentities.get(threadId);
+  if (!entry) return;
+  servingIdentities.delete(threadId);
+  servingIdentityTotalBytes -= entry.bytes;
+}
+
+function sweepExpiredServingIdentities(at: number): void {
+  for (const [threadId, entry] of servingIdentities) {
+    if (at - entry.at >= TTL_MS) deleteServingIdentity(threadId);
+  }
+}
+
+function servingIdentityFor(
+  scope: OcxReasoningReplayScopeRef | undefined,
+): { threadId: string; identity: string } | undefined {
+  const threadId = scope?.clientThreadId;
+  const identityTuple = tupleForServingIdentity(scope?.current);
+  if (!nonEmpty(threadId) || !identityTuple) return undefined;
+  return { threadId, identity: JSON.stringify(identityTuple) };
+}
+
+/**
+ * Compare this request's route with the last successfully serving route for its client thread.
+ * A live mismatch means replayed opaque reasoning was minted by another backend and must not be
+ * forwarded to this one. Comparison deliberately does not refresh or replace the recorded route:
+ * a failed candidate request did not serve the thread.
+ *
+ * Serving provenance uses restart-stable destination and credential dimensions so token
+ * generations and other volatile credential material cannot create false route changes. Missing
+ * durable identity, expired, or evicted state is deliberately unknown rather than a mismatch.
+ * This store is process-local, so a backend switch spanning a proxy restart is not detected.
+ */
+export function reasoningReplayServingIdentityChanged(
+  scope: OcxReasoningReplayScopeRef | undefined,
+): boolean {
+  const current = servingIdentityFor(scope);
+  if (!current) return false;
+  const at = now();
+  sweepExpiredServingIdentities(at);
+  const previous = servingIdentities.get(current.threadId);
+  return previous !== undefined && previous.identity !== current.identity;
+}
+
+/** Record the route only after it has successfully served the client thread. */
+export function commitReasoningReplayServingIdentity(
+  scope: OcxReasoningReplayScopeRef | undefined,
+): void {
+  const current = servingIdentityFor(scope);
+  if (!current) return;
+  const at = now();
+  sweepExpiredServingIdentities(at);
+  const previous = servingIdentities.get(current.threadId);
+  const { threadId, identity } = current;
+  const bytes = Buffer.byteLength(JSON.stringify([threadId, identity]), "utf8");
+  if (bytes > MAX_TOTAL_BYTES) {
+    deleteServingIdentity(threadId);
+    return;
+  }
+
+  if (previous) deleteServingIdentity(threadId);
+  servingIdentities.set(threadId, { identity, bytes, at });
+  servingIdentityTotalBytes += bytes;
+  while (
+    (servingIdentityTotalBytes > MAX_TOTAL_BYTES || servingIdentities.size > MAX_ENTRIES)
+    && servingIdentities.size > 1
+  ) {
+    let oldestThreadId: string | undefined;
+    let oldestAt = Infinity;
+    for (const [candidateThreadId, entry] of servingIdentities) {
+      if (entry.at < oldestAt) {
+        oldestAt = entry.at;
+        oldestThreadId = candidateThreadId;
+      }
+    }
+    if (oldestThreadId === undefined) break;
+    deleteServingIdentity(oldestThreadId);
+  }
+}
+
 function processLocalIdentity(domain: string, material: string): string {
   return createHmac("sha256", replayIdentityKey)
     .update(domain)
@@ -303,6 +419,8 @@ export function peekReasoningForCall(
 /** Test-only: reset the cache and optionally pin the clock. */
 export function clearReasoningReplayCacheForTests(clock?: (() => number) | null): void {
   entries.clear();
+  servingIdentities.clear();
   totalBytes = 0;
+  servingIdentityTotalBytes = 0;
   clockForTests = clock ?? null;
 }

package/src/responses/spill-store.ts

@@ -18,6 +18,7 @@ import { createHash, randomBytes } from "node:crypto";
 import { join } from "node:path";
 import { getConfigDir } from "../config";
 import { forgetEphemeralSecretPath, forgetHardenedSecretPath, hardenSecretDir, hardenSecretPath } from "../lib/windows-secret-acl";
+import { isValidProviderContinuationOwner } from "./provider-continuation";
 import type { OcxProviderContinuationState } from "../types";
 
 export const RESPONSE_SPILL_VERSION = 1;
@@ -287,7 +288,11 @@ function validPayload(value: unknown, responseId: string): value is ResponseSpil
   }
   if (payload.providers !== undefined) {
     if (!payload.providers || typeof payload.providers !== "object" || Array.isArray(payload.providers)) return false;
-    for (const providerState of Object.values(payload.providers)) {
+    const providers = payload.providers as Record<string, unknown>;
+    if (providers.__ocxOwner !== undefined
+      && !isValidProviderContinuationOwner(providers.__ocxOwner)) return false;
+    for (const [provider, providerState] of Object.entries(providers)) {
+      if (provider === "__ocxOwner") continue;
       if (!providerState || typeof providerState !== "object" || Array.isArray(providerState)) return false;
     }
   }

package/src/responses/state.ts

@@ -1216,6 +1216,17 @@ export function previousResponseReplayPrefixLength(body: unknown): number {
   return replayedInputPrefixLengths.get(body) ?? 0;
 }
 
+/** Copy proxy-private replay provenance to an internal clone with the same materialized input. */
+export function copyPreviousResponseReplayProvenance(source: unknown, target: unknown): void {
+  if (!source || typeof source !== "object" || Array.isArray(source)) return;
+  if (!target || typeof target !== "object" || Array.isArray(target)) return;
+  const prefixLength = replayedInputPrefixLengths.get(source);
+  if (!prefixLength) return;
+  const input = (target as { input?: unknown }).input;
+  if (!Array.isArray(input) || prefixLength > input.length) return;
+  replayedInputPrefixLengths.set(target, prefixLength);
+}
+
 /** True when a stale or foreign previous_response_id was removed from this exact request body. */
 export function previousResponseScopeMismatch(body: unknown): boolean {
   return !!body && typeof body === "object" && replayScopeMismatches.has(body as object);

package/src/router.ts

@@ -355,6 +355,17 @@ export function routedProviderConfig(providerName: string, provider: OcxProvider
     ...(provider.supportsServiceTier === undefined && registryEntry.supportsServiceTier !== undefined
       ? { supportsServiceTier: registryEntry.supportsServiceTier }
       : {}),
+    // Registry-only web-search capability: without this backfill a saved provider row reaches
+    // the Responses adapter with the flag `undefined`, so the capability gate added in #2262
+    // reads "unclassified" and forwards Codex's OpenAI-only `web_search` config fields. xAI
+    // rejects the whole request before inference ("Argument not supported:
+    // external_web_access"), which killed every routed Grok turn on the Responses lane.
+    // enrichProviderFromRegistry() already fills this, but the request path resolves through
+    // routedProviderConfig() and never called it.
+    ...(provider.supportsOpenAiWebSearchToolFields === undefined
+      && registryEntry.supportsOpenAiWebSearchToolFields !== undefined
+      ? { supportsOpenAiWebSearchToolFields: registryEntry.supportsOpenAiWebSearchToolFields }
+      : {}),
     ...(provider.preserveResponsesReasoningContent === undefined && registryEntry.preserveResponsesReasoningContent !== undefined
       ? { preserveResponsesReasoningContent: registryEntry.preserveResponsesReasoningContent }
       : {}),
@@ -398,6 +409,9 @@ export function routedProviderConfig(providerName: string, provider: OcxProvider
     ...(provider.parallelToolCalls === undefined && registryEntry.parallelToolCalls !== undefined ? { parallelToolCalls: registryEntry.parallelToolCalls } : {}),
     ...(provider.promptCacheKey === undefined && registryEntry.promptCacheKey !== undefined ? { promptCacheKey: registryEntry.promptCacheKey } : {}),
     ...(provider.chatServiceTier === undefined && registryEntry.chatServiceTier !== undefined ? { chatServiceTier: registryEntry.chatServiceTier } : {}),
+    ...(provider.openaiChatEofTolerance === undefined && registryEntry.openaiChatEofTolerance !== undefined
+      ? { openaiChatEofTolerance: registryEntry.openaiChatEofTolerance }
+      : {}),
     ...(provider.reasoningWireFormat === undefined && registryEntry.reasoningWireFormat !== undefined
       ? { reasoningWireFormat: registryEntry.reasoningWireFormat }
       : {}),

package/src/routing/compatibility/behavior.ts

@@ -228,6 +228,7 @@ export function resolveProductionBehaviorValues(
     "cache.forwarding": behaviorRow("provider_config", effective.promptCacheKey === true),
     "cache.retention": behaviorRow("global_config", config.cacheRetention ?? "short"),
     "anthropic.eofPolicy": behaviorRow("provider_config", effective.anthropicEofTolerance === true ? "tolerant" : "strict"),
+    "openai-chat.eofPolicy": behaviorRow("provider_config", effective.openaiChatEofTolerance === true ? "tolerant" : "strict"),
     "google.mode": behaviorRow("provider_config", effective.googleMode ?? null),
     "google.projectFingerprint": behaviorRow(
       "provider_config",

package/src/server/auth-cors.ts

@@ -25,6 +25,7 @@ import { providerConfigSeed } from "../providers/derive";
 import type { OcxConfig, OcxProviderConfig } from "../types";
 import { openRouterRoutingConfigError } from "../providers/openrouter-routing";
 import { googleVertexLocationConfigError } from "../providers/google-vertex-location";
+import { xaiResponsesOptInState } from "../providers/xai-responses-opt-in";
 
 let _corsOrigin = "http://localhost:10100";
 export function setCorsOrigin(port: number): void { _corsOrigin = `http://localhost:${port}`; }
@@ -688,6 +689,9 @@ export function safeConfigDTO(config: OcxConfig): unknown {
       hasApiKey: !!provider.apiKey,
       hasHeaders: !!provider.headers && Object.keys(provider.headers).length > 0,
     };
+    if (name === "xai") {
+      dto.xaiResponsesOptInState = xaiResponsesOptInState(provider);
+    }
     for (const key of [
       "defaultModel",
       "disabled",

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

@@ -56,6 +56,11 @@ import {
   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";
@@ -940,7 +945,10 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
       const observed = inspectDesktop3pConfigLibrary({ appliedFingerprint: savedFingerprint });
       const desiredEnabled = claudeDesktopIntegrationEnabled(persisted);
       const applied = observed.kind === "gateway_ours" || observed.kind === "gateway_drifted";
-      const stale = observed.kind === "gateway_drifted";
+      // "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({
@@ -1065,16 +1073,23 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
       const section = body[field];
       if (section === undefined || section === null) continue;
       if (!isPlainObject(section)) return jsonResponse({ error: `${field} must be an object or null` }, 400);
+      // The widened union applies to the WEB-SEARCH override only (roadmap 060).
+      // Vision keeps its two-backend contract — accepting a wider id there would
+      // persist a backend the vision resolver reads as unset, silently activating
+      // a backend the operator never chose (review F1).
+      const allowedBackends = field === "webSearchSidecar"
+        ? ["openai", "anthropic", "xai", "gemini", "exa"]
+        : ["openai", "anthropic"];
       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; webSearchSidecar has no vision requirement and is left alone. Shares
-      // one policy module with /api/sidecar-settings so the two gates cannot drift.
+      // 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);
@@ -1085,6 +1100,35 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
           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) {
@@ -1094,13 +1138,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) {

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

@@ -70,6 +70,13 @@ import {
   visionDescriberRejection,
   visionModelOptionsFor,
 } from "./vision-sidecar-options";
+import {
+  webSearchCandidateRows,
+  webSearchModelIsRejected,
+  webSearchModelOptionsFrom,
+  webSearchModelRejection,
+} from "./web-search-sidecar-options";
+import { validateXaiSearchOptions } from "../../web-search/xai-executor";
 import { getDebugLogEntries } from "../../lib/debug-log-buffer";
 import { getInjectionDebugLogEntries } from "../../lib/injection-debug-log";
 import {
@@ -120,21 +127,22 @@ async function sidecarVisionResponseSettings(config: OcxConfig): Promise<{
 
 /** One client's outcome from a fan-out sync. Absent from the list means "left alone". */
 interface ClientIntegrationSyncOutcome {
-  readonly client: "grok" | "claude-desktop";
+  readonly client: "grok" | "claude-desktop" | "mcode";
   readonly ok: boolean;
   readonly changed?: boolean;
   readonly reason?: string;
 }
 
 /**
- * Re-inject every client integration the operator has switched ON.
+ * Re-inject native clients that are switched ON and file integrations whose
+ * OpenCodex ownership record is the operator's durable opt-in.
  *
  * Only Codex used to run here, so a catalog change reached Codex and nothing else: a Grok
  * fence or a written Desktop profile kept the context windows it was created with until the
  * next `ocx start`. The startup path already gates each client on its own toggle
  * (`src/cli/index.ts`), and this is that same fan-out for the on-demand command.
  *
- * A client that is OFF is omitted from the result rather than reported as skipped — the
+ * A client that is OFF or never connected is omitted from the result rather than reported as skipped — the
  * caller has to be able to tell "not touched" from "tried and failed". A client that fails
  * does not fail the sync: Codex is the one that matters for routing, and a broken Grok file
  * should surface as a warning, not as a 500 on a command that did its main job.
@@ -183,6 +191,31 @@ async function syncEnabledClientIntegrations(
     }
   }
 
+  try {
+    const { refreshOwnedIntegration } = await import("../../integrations/owned-refresh");
+    const result = await refreshOwnedIntegration({
+      clientId: "mcode",
+      models: async () => {
+        const { loadExportModels } = await import("./model-rows");
+        return loadExportModels(config);
+      },
+      config,
+      port,
+    });
+    if (result) {
+      out.push(result.ok
+        ? {
+            client: "mcode",
+            ok: true,
+            changed: result.changed === true,
+            ...(result.reason ? { reason: result.reason } : {}),
+          }
+        : { client: "mcode", ok: false, reason: result.reason });
+    }
+  } catch (error) {
+    out.push({ client: "mcode", ok: false, reason: error instanceof Error ? error.message : String(error) });
+  }
+
   return out;
 }
 
@@ -511,14 +544,19 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
   if (url.pathname === "/api/sidecar-settings" && req.method === "GET") {
     const ws = config.webSearchSidecar ?? {};
     const vision = await sidecarVisionResponseSettings(config);
+    const webSearchCandidates = await webSearchCandidateRows(config);
     return jsonResponse({
       webSearch: {
         model: ws.model ?? "gpt-5.6-luna",
         backend: ws.backend,
         streamRoutedModelOutput: ws.streamRoutedModelOutput === true,
+        ...(ws.xSearch ? { xSearch: ws.xSearch } : {}),
       },
       vision: publicVisionSidecarSettings(config, vision),
       visionModels: vision.models,
+      // ALWAYS present: the dashboard treats an omitted list as "no filter" and
+      // falls back to the full model union, so empty must be [] (review B3).
+      webSearchModels: webSearchModelOptionsFrom(config, webSearchCandidates),
     });
   }
 
@@ -531,7 +569,7 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
     if (raw.webSearch !== undefined && !isPlainRecord(raw.webSearch)) return jsonResponse({ error: "webSearch must be an object" }, 400);
     if (raw.vision !== undefined && !isPlainRecord(raw.vision)) return jsonResponse({ error: "vision must be an object" }, 400);
     const body = raw as {
-      webSearch?: { model?: unknown; backend?: unknown; reasoning?: unknown; streamRoutedModelOutput?: unknown };
+      webSearch?: { model?: unknown; backend?: unknown; reasoning?: unknown; streamRoutedModelOutput?: unknown; exaApiKey?: unknown; xSearch?: unknown };
       vision?: {
         model?: unknown;
         backend?: unknown;
@@ -541,9 +579,13 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
         timeoutMs?: unknown;
       };
     };
+    const WEB_SEARCH_BACKENDS_UNION = ["openai", "anthropic", "xai", "gemini", "exa"] as const;
     if (body.webSearch && body.webSearch.backend !== undefined && body.webSearch.backend !== null
-      && body.webSearch.backend !== "openai" && body.webSearch.backend !== "anthropic") {
-      return jsonResponse({ error: "webSearch.backend must be openai, anthropic, or null" }, 400);
+      && !WEB_SEARCH_BACKENDS_UNION.includes(body.webSearch.backend as never)) {
+      return jsonResponse({ error: "webSearch.backend must be openai, anthropic, xai, gemini, exa, or null" }, 400);
+    }
+    if (body.webSearch?.model !== undefined && typeof body.webSearch.model !== "string") {
+      return jsonResponse({ error: "webSearch.model must be a string" }, 400);
     }
     if (body.webSearch && body.webSearch.streamRoutedModelOutput !== undefined
       && typeof body.webSearch.streamRoutedModelOutput !== "boolean") {
@@ -600,21 +642,92 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
     }
 
     if (body.webSearch) {
-      config.webSearchSidecar = { ...config.webSearchSidecar };
+      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
+          ? "openai"
+          : config.webSearchSidecar?.backend ?? "openai";
+      const effectiveModel = typeof body.webSearch.model === "string"
+        ? body.webSearch.model || undefined
+        : config.webSearchSidecar?.model;
+      if (pairTouched && effectiveModel) {
+        const candidates = await webSearchCandidateRows(config);
+        if (webSearchModelIsRejected(effectiveBackend, effectiveModel, candidates)) {
+          return jsonResponse(webSearchModelRejection("webSearch.model", effectiveBackend, effectiveModel, candidates), 400);
+        }
+      }
+      const webSearchCandidate = { ...config.webSearchSidecar };
       if (typeof body.webSearch.model === "string") {
-        if (body.webSearch.model === "") delete config.webSearchSidecar.model;
-        else config.webSearchSidecar.model = body.webSearch.model;
+        if (body.webSearch.model === "") delete webSearchCandidate.model;
+        else webSearchCandidate.model = body.webSearch.model;
       }
-      if (body.webSearch.backend === null) delete config.webSearchSidecar.backend;
-      else if (body.webSearch.backend === "openai" || body.webSearch.backend === "anthropic") {
-        config.webSearchSidecar.backend = body.webSearch.backend;
+      if (body.webSearch.backend === null) delete webSearchCandidate.backend;
+      else if (WEB_SEARCH_BACKENDS_UNION.includes(body.webSearch.backend as never)) {
+        webSearchCandidate.backend = body.webSearch.backend as typeof WEB_SEARCH_BACKENDS_UNION[number];
+      }
+      if (typeof body.webSearch.reasoning === "string") webSearchCandidate.reasoning = body.webSearch.reasoning;
+      // Operator secret for the exa backend: string sets, empty string clears. The GET
+      // payload deliberately never carries it and redact.ts strips the key from logs.
+      if (typeof body.webSearch.exaApiKey === "string") {
+        if (body.webSearch.exaApiKey === "") delete webSearchCandidate.exaApiKey;
+        else webSearchCandidate.exaApiKey = body.webSearch.exaApiKey;
+      }
+      // Opt-in x_search block (L7): null clears; an object is doc-validated before persisting.
+      if (body.webSearch.xSearch === null) delete webSearchCandidate.xSearch;
+      else if (body.webSearch.xSearch !== undefined) {
+        if (!isPlainRecord(body.webSearch.xSearch)) {
+          return jsonResponse({ error: "webSearch.xSearch must be an object or null" }, 400);
+        }
+        const x = body.webSearch.xSearch as Record<string, unknown>;
+        const allowedXSearchKeys = new Set([
+          "enabled",
+          "allowedXHandles",
+          "excludedXHandles",
+          "fromDate",
+          "toDate",
+        ]);
+        const unknownKey = Object.keys(x).find(key => !allowedXSearchKeys.has(key));
+        if (unknownKey !== undefined) {
+          return jsonResponse({ error: `webSearch.xSearch.${unknownKey} is not a supported field` }, 400);
+        }
+        if (x.enabled !== undefined && typeof x.enabled !== "boolean") {
+          return jsonResponse({ error: "webSearch.xSearch.enabled must be a boolean" }, 400);
+        }
+        for (const field of ["allowedXHandles", "excludedXHandles"] as const) {
+          const value = x[field];
+          if (value !== undefined && (!Array.isArray(value) || !value.every(handle => typeof handle === "string"))) {
+            return jsonResponse({ error: `webSearch.xSearch.${field} must be an array of strings` }, 400);
+          }
+        }
+        for (const field of ["fromDate", "toDate"] as const) {
+          if (x[field] !== undefined && typeof x[field] !== "string") {
+            return jsonResponse({ error: `webSearch.xSearch.${field} must be an ISO-8601 date (YYYY-MM-DD)` }, 400);
+          }
+        }
+        const candidate = {
+          ...(x.enabled === true ? { enabled: true } : {}),
+          ...(x.allowedXHandles !== undefined ? { allowedXHandles: x.allowedXHandles as string[] } : {}),
+          ...(x.excludedXHandles !== undefined ? { excludedXHandles: x.excludedXHandles as string[] } : {}),
+          ...(x.fromDate !== undefined ? { fromDate: x.fromDate as string } : {}),
+          ...(x.toDate !== undefined ? { toDate: x.toDate as string } : {}),
+        };
+        const invalid = validateXaiSearchOptions({
+          xSearch: candidate.enabled,
+          allowedXHandles: candidate.allowedXHandles,
+          excludedXHandles: candidate.excludedXHandles,
+          fromDate: candidate.fromDate,
+          toDate: candidate.toDate,
+        });
+        if (invalid) return jsonResponse({ error: `webSearch.xSearch invalid: ${invalid}` }, 400);
+        webSearchCandidate.xSearch = candidate;
       }
-      if (typeof body.webSearch.reasoning === "string") config.webSearchSidecar.reasoning = body.webSearch.reasoning;
       if (typeof body.webSearch.streamRoutedModelOutput === "boolean") {
         // `false` is the default — drop the key so config files stay minimal.
-        if (body.webSearch.streamRoutedModelOutput) config.webSearchSidecar.streamRoutedModelOutput = true;
-        else delete config.webSearchSidecar.streamRoutedModelOutput;
+        if (body.webSearch.streamRoutedModelOutput) webSearchCandidate.streamRoutedModelOutput = true;
+        else delete webSearchCandidate.streamRoutedModelOutput;
       }
+      config.webSearchSidecar = webSearchCandidate;
     }
     if (body.vision) {
       config.visionSidecar = { ...config.visionSidecar };
@@ -645,15 +758,21 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
     saveConfigPreservingClaudeCode(config);
     const ws = config.webSearchSidecar ?? {};
     const vision = await sidecarVisionResponseSettings(config);
+    const savedWebSearchCandidates = await webSearchCandidateRows(config);
     return jsonResponse({
       ok: true,
       webSearch: {
         model: ws.model ?? "gpt-5.6-luna",
         backend: ws.backend,
         streamRoutedModelOutput: ws.streamRoutedModelOutput === true,
+        ...(ws.xSearch ? { xSearch: ws.xSearch } : {}),
       },
       vision: publicVisionSidecarSettings(config, vision),
       visionModels: vision.models,
+      // Echoed for the same reason GET always carries it: the dashboard rebuilds
+      // its sidecar state from this body, and an omitted key reads as "old
+      // server" and falls back to the full union (review F1).
+      webSearchModels: webSearchModelOptionsFrom(config, savedWebSearchCandidates),
     });
   }