@bitkyc08/opencodex 2.7.43 → 2.8.2-preview.20260731

package/src/server/live.ts

@@ -197,42 +197,92 @@ export function parseLiveSidebandTarget(pathname: string, searchParams: URLSearc
   return null;
 }
 
+/**
+ * True for the loopback hosts plaintext development servers listen on.
+ * `URL.hostname` keeps the brackets on IPv6, so both forms are accepted.
+ */
+function isLoopbackHost(hostname: string): boolean {
+  const lower = hostname.toLowerCase();
+  return lower === "localhost" || lower.endsWith(".localhost")
+    || lower === "127.0.0.1" || lower.startsWith("127.")
+    || lower === "::1" || lower === "[::1]";
+}
+
+/**
+ * Normalize the sideband base to end in exactly `/v1`, with no query, fragment,
+ * or userinfo. Any failure closes to the canonical Realtime API root — never to
+ * the input — because this string decides where upstream bearer credentials and
+ * user audio are sent.
+ *
+ * Bounds, all fail-closed:
+ *   - scheme must be https/wss, or http/ws with a loopback host (the local
+ *     development case this knob exists for);
+ *   - URL userinfo is rejected (URL#toString would forward it verbatim);
+ *   - unparseable input is rejected.
+ *
+ * Endpoint-form overrides are recognized the way upstream recognizes them
+ * (codex-rs realtime_websocket/methods.rs:994): a terminal `/realtime`,
+ * `/realtime/calls/<id>`, or `/live/<id>` is stripped so the root can be
+ * re-derived. A path prefix survives (`https://host/api/v1` keeps `/api`).
+ */
+function normalizeSidebandRoot(baseUrl: string): string {
+  let parsed: URL;
+  try {
+    parsed = new URL(baseUrl);
+  } catch {
+    return LIVE_SIDEBAND_API_ROOT;
+  }
+  const secure = parsed.protocol === "https:" || parsed.protocol === "wss:";
+  const plaintext = parsed.protocol === "http:" || parsed.protocol === "ws:";
+  if ((!secure && !plaintext) || (plaintext && !isLoopbackHost(parsed.hostname)) || parsed.username || parsed.password) {
+    return LIVE_SIDEBAND_API_ROOT;
+  }
+  parsed.search = "";
+  parsed.hash = "";
+  const path = parsed.pathname
+    .replace(/\/+$/, "")
+    .replace(/\/realtime(?:\/calls\/[^/]+)?$/, "")
+    .replace(/\/live\/[^/]+$/, "")
+    .replace(/\/v1$/, "");
+  parsed.pathname = `${path}/v1`;
+  return parsed.toString().replace(/\/$/, "");
+}
+
+/**
+ * Resolve the sideband base. Upstream policy (codex-rs 438c9e98d): the sideband
+ * join is NOT derived from the selected model provider — precedence is exactly
+ * the explicit override when configured, otherwise the canonical Realtime API
+ * root. The provider base URL deliberately plays no part; a user who needs a
+ * non-canonical host sets the override, the same escape hatch upstream ships as
+ * `experimental_realtime_ws_base_url`.
+ */
+function sidebandBaseRoot(overrideBaseUrl?: string): string {
+  return normalizeSidebandRoot(overrideBaseUrl?.trim() || LIVE_SIDEBAND_API_ROOT);
+}
+
 /**
  * Build the upstream sideband WebSocket URL for a resolved OpenAI/ChatGPT provider.
  * Mirrors openai/codex `websocket_url_from_api_url_for_call` + `normalize_realtime_path`.
+ *
+ * Deliberate deviation: the realtime-query style keeps `intent=quicksilver`,
+ * which upstream does not send. That URL is live against real OpenAI
+ * infrastructure for every canonical voice user and this parameter is known to
+ * work; dropping it is future work gated on a live smoke test. Parity here is
+ * scoped to the host, override precedence, and provider-query exclusion.
  */
 export function buildLiveSidebandUpstreamWsUrl(
-  providerBaseUrl: string,
-  usesBackendShape: boolean,
   target: LiveSidebandTarget,
+  overrideBaseUrl?: string,
 ): string {
-  const root = providerBaseUrl.replace(/\/$/, "");
-  if (usesBackendShape) {
-    // ChatGPT backend-api call-create, but the sideband join lives on the public API host
-    // (matches openai/codex, which builds the sideband from the ApiKey provider default).
-    if (target.style === "frameless-path") {
-      return httpsToWss(`${LIVE_SIDEBAND_API_ROOT}/live/${target.callId}`);
-    }
-    if (target.style === "realtime-calls-path") {
-      return httpsToWss(`${LIVE_SIDEBAND_API_ROOT}/realtime/calls/${target.callId}`);
-    }
-    return httpsToWss(
-      `${LIVE_SIDEBAND_API_ROOT}/realtime?intent=quicksilver&call_id=${encodeURIComponent(target.callId)}`,
-    );
-  }
+  const sidebandRoot = sidebandBaseRoot(overrideBaseUrl);
   if (target.style === "frameless-path") {
-    // Frameless: normalize to .../live then append /{callId}.
-    const apiRoot = root.replace(/\/v1\/?$/, "");
-    return httpsToWss(`${apiRoot}/v1/live/${target.callId}`);
+    return httpsToWss(`${sidebandRoot}/live/${target.callId}`);
   }
   if (target.style === "realtime-calls-path") {
-    const apiRoot = root.replace(/\/v1\/?$/, "");
-    return httpsToWss(`${apiRoot}/v1/realtime/calls/${target.callId}`);
+    return httpsToWss(`${sidebandRoot}/realtime/calls/${target.callId}`);
   }
-  // Realtime v1/v2: /v1/realtime?intent=quicksilver&call_id=
-  const apiRoot = root.replace(/\/v1\/?$/, "");
   return httpsToWss(
-    `${apiRoot}/v1/realtime?intent=quicksilver&call_id=${encodeURIComponent(target.callId)}`,
+    `${sidebandRoot}/realtime?intent=quicksilver&call_id=${encodeURIComponent(target.callId)}`,
   );
 }
 
@@ -542,7 +592,7 @@ export async function resolveLiveSidebandUpgrade(
   if (relay instanceof Response) return relay;
   return {
     headers: relay.headers,
-    upstreamWsUrl: buildLiveSidebandUpstreamWsUrl(relay.providerBaseUrl, relay.usesBackendShape, target),
+    upstreamWsUrl: buildLiveSidebandUpstreamWsUrl(target, config.experimentalRealtimeWsBaseUrl),
     recordOutcome: relay.recordOutcome,
   };
 }

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

@@ -80,12 +80,12 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
       if (config.claudeCode?.desktopAutoApply === false) return;
       if (!config.claudeCode?.desktopProfile) return;
       const { writeDesktop3pConfig } = await import("../../claude/desktop-3p");
-      const { visibleNativeSlugs, filterCatalogVisibleModels } = await import("../../codex/catalog");
+      const { filterCatalogVisibleModels, desktopVisibleNativeSlugs } = await import("../../codex/catalog");
       const allModels = await fetchAllModels(config);
       const routed = filterCatalogVisibleModels(allModels, config).map(m => ({ provider: m.provider, id: m.id, contextWindow: m.contextWindow }));
       const result = writeDesktop3pConfig(
         config.port ?? 10100,
-        [...visibleNativeSlugs(config)],
+        [...desktopVisibleNativeSlugs(config)],
         routed,
         config.apiKeys?.[0]?.key,
         "static",
@@ -104,22 +104,43 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
   // itself never writes config — this endpoint is the only server-side mutation
   // surface for the flag.
   if (url.pathname === "/api/v2" && req.method === "GET") {
-    const { isMultiAgentV2Enabled, hasAgentsMaxThreads, getLogicalMaxThreads } = await import("../../codex/features");
+    const {
+      isMultiAgentV2Enabled, hasAgentsMaxThreads, getLogicalMaxThreads,
+      getAgentsEnabled, getAgentsMaxDepth, getSubagentDeveloperInstructions,
+    } = await import("../../codex/features");
     const enabled = isMultiAgentV2Enabled();
     return jsonResponse({
       enabled,
       agentsMaxThreadsConflict: enabled && hasAgentsMaxThreads(),
       maxConcurrentThreadsPerSession: getLogicalMaxThreads(),
       multiAgentMode: config.multiAgentMode ?? "default",
+      agentsEnabled: getAgentsEnabled(),
+      agentsMaxDepth: getAgentsMaxDepth(),
+      subagentDeveloperInstructions: getSubagentDeveloperInstructions(),
+      // 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,
     });
   }
   if (url.pathname === "/api/v2" && req.method === "PUT") {
-    let body: { enabled?: unknown; maxConcurrentThreadsPerSession?: unknown; multiAgentMode?: unknown };
+    let body: {
+      enabled?: unknown;
+      maxConcurrentThreadsPerSession?: unknown;
+      multiAgentMode?: unknown;
+      agentsEnabled?: unknown;
+      agentsMaxDepth?: unknown;
+      subagentDeveloperInstructions?: unknown;
+    };
     try { body = await req.json(); } catch { return jsonResponse({ error: "invalid JSON body" }, 400); }
     const wantsFlag = body.enabled !== undefined;
     const wantsThreads = body.maxConcurrentThreadsPerSession !== undefined;
     const wantsMode = body.multiAgentMode !== undefined;
-    if (!wantsFlag && !wantsThreads && !wantsMode) return jsonResponse({ error: "body must set enabled, multiAgentMode, and/or maxConcurrentThreadsPerSession" }, 400);
+    const wantsAgentsEnabled = body.agentsEnabled !== undefined;
+    const wantsMaxDepth = body.agentsMaxDepth !== undefined;
+    const wantsSubagentInstructions = body.subagentDeveloperInstructions !== undefined;
+    if (!wantsFlag && !wantsThreads && !wantsMode && !wantsAgentsEnabled && !wantsMaxDepth && !wantsSubagentInstructions) {
+      return jsonResponse({ error: "body must set enabled, multiAgentMode, maxConcurrentThreadsPerSession, agentsEnabled, agentsMaxDepth, and/or subagentDeveloperInstructions" }, 400);
+    }
     if (wantsFlag && typeof body.enabled !== "boolean") return jsonResponse({ error: "body.enabled must be a boolean" }, 400);
     if (wantsMode && body.multiAgentMode !== "v1" && body.multiAgentMode !== "default" && body.multiAgentMode !== "v2") {
       return jsonResponse({ error: "body.multiAgentMode must be 'v1', 'default', or 'v2'" }, 400);
@@ -127,12 +148,31 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
     if (wantsThreads && (typeof body.maxConcurrentThreadsPerSession !== "number" || !Number.isInteger(body.maxConcurrentThreadsPerSession) || body.maxConcurrentThreadsPerSession < 1)) {
       return jsonResponse({ error: "body.maxConcurrentThreadsPerSession must be an integer >= 1" }, 400);
     }
+    // Validate every new field BEFORE any write, so each 400 leaves config untouched.
+    // null unsets the key; "" is a meaningful value for instructions and must not be
+    // collapsed by a falsy check. The i32 preflight mirrors the upstream Option<i32>
+    // contract — out-of-range would otherwise surface as a mid-sequence write failure.
+    if (wantsAgentsEnabled && body.agentsEnabled !== null && typeof body.agentsEnabled !== "boolean") {
+      return jsonResponse({ error: "body.agentsEnabled must be a boolean or null" }, 400);
+    }
+    if (wantsMaxDepth && body.agentsMaxDepth !== null
+        && (typeof body.agentsMaxDepth !== "number" || !Number.isInteger(body.agentsMaxDepth)
+            || body.agentsMaxDepth < -2_147_483_648 || body.agentsMaxDepth > 2_147_483_647)) {
+      return jsonResponse({ error: "body.agentsMaxDepth must be an integer within signed i32 range, or null" }, 400);
+    }
+    if (wantsSubagentInstructions && body.subagentDeveloperInstructions !== null && typeof body.subagentDeveloperInstructions !== "string") {
+      return jsonResponse({ error: "body.subagentDeveloperInstructions must be a string or null" }, 400);
+    }
     const mode = wantsMode ? body.multiAgentMode as "v1" | "default" | "v2" : undefined;
     const modeFlag = mode === "v2" ? true : mode === "v1" ? false : undefined;
     if (wantsFlag && modeFlag !== undefined && body.enabled !== modeFlag) {
       return jsonResponse({ error: `body.enabled conflicts with multiAgentMode '${mode}'` }, 400);
     }
-    const { isMultiAgentV2Enabled, hasAgentsMaxThreads, getLogicalMaxThreads, transitionMultiAgentV2 } = await import("../../codex/features");
+    const {
+      isMultiAgentV2Enabled, hasAgentsMaxThreads, getLogicalMaxThreads, transitionMultiAgentV2,
+      getAgentsEnabled, getAgentsMaxDepth, getSubagentDeveloperInstructions,
+      setAgentsEnabled, setAgentsMaxDepth, setSubagentDeveloperInstructions,
+    } = await import("../../codex/features");
     const warnings: string[] = [];
     const requestedFlag = wantsFlag ? body.enabled as boolean : modeFlag;
     if (requestedFlag !== undefined || wantsThreads) {
@@ -159,6 +199,36 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
       saveConfigPreservingClaudeCode(config);
       warnings.push(`Multi-agent mode set to '${mode}'. Applies to new sessions.`);
     }
+    // New-key scalar writes: each writer is individually atomic, so apply them in
+    // sequence after the transition. A failure here is a persistence failure (the
+    // writers' ok:false result or a throw from the underlying atomic write helper),
+    // reported as 502 naming the failed key plus the writes that already landed.
+    // NOTE: do not name that helper literally here — tests/grok-writer-boundary.test.ts
+    // 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) });
+    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);
+        }
+        landed.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);
+      }
+    }
+    // Derived from fresh post-write readers (readConfigText is uncached): upstream
+    // lets an enabled multi_agent_v2 feature override [agents].enabled = false, so
+    // warn rather than reject — silently accepting would imply multi-agent is off.
+    if (getAgentsEnabled() === false && isMultiAgentV2Enabled()) {
+      warnings.push("agents.enabled = false has no effect while features.multi_agent_v2 is enabled; upstream keeps V2 active.");
+    }
     await refreshCodexCatalogBestEffort();
     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();
@@ -168,6 +238,10 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
       agentsMaxThreadsConflict: enabled && hasAgentsMaxThreads(),
       maxConcurrentThreadsPerSession: getLogicalMaxThreads(),
       multiAgentMode: config.multiAgentMode ?? "default",
+      agentsEnabled: getAgentsEnabled(),
+      agentsMaxDepth: getAgentsMaxDepth(),
+      subagentDeveloperInstructions: getSubagentDeveloperInstructions(),
+      agentsMaxDepthAppliesWhenV2Disabled: !enabled,
       warnings,
     });
   }
@@ -533,7 +607,7 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
       config.claudeCode = { ...(config.claudeCode ?? {}), desktopProfile: state.profile };
       saveConfigPreservingClaudeCode(config);
       const { writeDesktop3pConfig } = await import("../../claude/desktop-3p");
-      const { visibleNativeSlugs } = await import("../../codex/catalog");
+      const { desktopVisibleNativeSlugs } = await import("../../codex/catalog");
       const routed = state.models
         .filter(model => model.available && !model.route.startsWith("native/"))
         .map(model => {
@@ -542,7 +616,7 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
         });
       const result = writeDesktop3pConfig(
         Number(url.port) || config.port,
-        [...visibleNativeSlugs(config)],
+        [...desktopVisibleNativeSlugs(config)],
         routed,
         config.apiKeys?.[0]?.key,
         "static",

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

@@ -24,6 +24,7 @@ import {
 import { removeCredential } from "../../oauth/store";
 import { providerDestinationResolvedError } from "../../lib/destination-policy";
 import { isStreamMode } from "../../lib/bun-stream-caps";
+import { shadowSourceModels } from "../../lib/shadow-call";
 import { enrichProviderFromCatalog, listKeyLoginProviders } from "../../oauth/key-providers";
 import { deriveProviderPresets } from "../../providers/derive";
 import { providerCodexAccountMode } from "../../providers/registry";
@@ -110,6 +111,11 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
       );
     }
     return jsonResponse({
+      // The dashboard renders request-log timestamps. Without this it formats them in the
+      // BROWSER's zone, so a KST proxy viewed from a UTC browser reports every request nine
+      // hours off (#725). Carried on settings rather than /api/logs because that route's
+      // array response has four consumers that would have to change with it.
+      timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone,
       codexAutoStart: codexAutoStartEnabled(config),
       port: config.port,
       hostname: config.hostname ?? "127.0.0.1",
@@ -140,16 +146,20 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
   }
 
   if (url.pathname === "/api/startup-action" && req.method === "POST") {
-    let body: { action?: unknown };
+    let body: { action?: unknown; repair?: unknown };
     try { body = await req.json(); } catch { return jsonResponse({ error: "invalid JSON body" }, 400); }
     if (!body || !["install-service", "install-shim"].includes(String(body.action))) {
       return jsonResponse({ error: "action must be install-service or install-shim" }, 400);
     }
+    if (body.repair !== undefined && typeof body.repair !== "boolean") {
+      return jsonResponse({ error: "repair must be a boolean when provided" }, 400);
+    }
     try {
       const action = body.action as StartupInstallAction;
-      const result = await (deps.runStartupInstallAction ?? runStartupInstallAction)(action);
+      const repair = body.repair === true;
+      const result = await (deps.runStartupInstallAction ?? runStartupInstallAction)(action, { repair });
       invalidateStartupHealthCache();
-      return jsonResponse({ ok: true, action, message: result.message });
+      return jsonResponse({ ok: true, action, repair, message: result.message });
     } catch (error) {
       return jsonResponse({ error: error instanceof Error ? error.message : String(error) }, 500);
     }
@@ -227,8 +237,6 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
     const { syncModelsToCodex } = await import("../../codex/sync");
     const { attachStaleAppServerHint } = await import("../../codex/app-server-processes");
     const result = await syncModelsToCodex(undefined, config, null);
-    // Hint only after a real catalog/cache write — never enumerate processes here
-    // (WMIC/PowerShell would block Bun's event loop on every dashboard sync).
     return jsonResponse({
       ...attachStaleAppServerHint(result),
       ...(result.ok ? {} : { error: result.message }),
@@ -352,7 +360,11 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
 
   if (url.pathname === "/api/shadow-call-settings" && req.method === "GET") {
     const sci = config.shadowCallIntercept ?? {};
-    return jsonResponse({ enabled: sci.enabled === true, model: sci.model ?? "" });
+    return jsonResponse({
+      enabled: sci.enabled === true,
+      model: sci.model ?? "",
+      sourceModels: shadowSourceModels(sci.sourceModels),
+    });
   }
 
   if (url.pathname === "/api/shadow-call-settings" && req.method === "PUT") {
@@ -374,7 +386,12 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
     }
     saveConfigPreservingClaudeCode(config);
     const sci = config.shadowCallIntercept;
-    return jsonResponse({ ok: true, enabled: sci.enabled === true, model: sci.model ?? "" });
+    return jsonResponse({
+      ok: true,
+      enabled: sci.enabled === true,
+      model: sci.model ?? "",
+      sourceModels: shadowSourceModels(sci.sourceModels),
+    });
   }
   return null;
 }

package/src/server/management/context.ts

@@ -4,10 +4,20 @@ import type { StartupInstallAction } from "../startup-action-control";
 export interface ManagementApiDeps {
   toggleCodexMultiAgentV2?: (enabled: boolean) => void;
   refreshCodexCatalog?: () => Promise<void>;
+  /**
+   * Persistence seam for route-level tests. Production leaves this unset and uses
+   * `saveConfigPreservingClaudeCode`; tests that pass an in-memory fixture config
+   * MUST inject a no-op/spy so the fixture can never overwrite the user's real
+   * OPENCODEX_HOME (incident: devlog 260730.../070).
+   */
+  saveConfigPreservingClaudeCode?: (config: OcxConfig) => void;
   clearThreadAccountMap?: () => void;
   clearProviderQuotaCache?: () => void;
   primeCodexPoolQuotas?: (config: OcxConfig, reason: string) => Promise<void> | void;
-  runStartupInstallAction?: (action: StartupInstallAction) => Promise<{ message: string }>;
+  runStartupInstallAction?: (
+    action: StartupInstallAction,
+    options?: { repair?: boolean },
+  ) => Promise<{ message: string }>;
 }
 
 

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

@@ -1,5 +1,34 @@
 import { randomUUID } from "node:crypto";
 import { readFileSync } from "node:fs";
+
+/**
+ * Codex parses a catalog entry's `input_modalities` as a closed enum, and one out-of-enum
+ * value makes it reject the ENTIRE catalog file — plugins, apps and MCP servers all stop
+ * loading over one model's metadata (#759).
+ *
+ * The catalog writer normalizes on the way out, but a rejected value stored here would still
+ * be handed back to the GUI and CLI as if it were real, and the offline `ocx models add` path
+ * already refuses it. Validate at ingress so all three paths agree.
+ */
+const ALLOWED_INPUT_MODALITIES = new Set(["text", "image", "audio"]);
+
+function readInputModalities(raw: unknown): { values?: string[]; error?: string } {
+  if (raw === undefined) return {};
+  if (!Array.isArray(raw)) return { error: "inputModalities must be an array" };
+  // Reject non-strings rather than filtering them out. Dropping them silently accepted a
+  // malformed POST and, worse, let a PUT of `[42]` clear the stored modalities while
+  // answering 200 — the opposite of the contract this validator exists to state. An empty
+  // array stays valid: that is how `ocx models edit --modalities -` clears the field.
+  const rejected: string[] = [];
+  for (const value of raw) {
+    if (typeof value !== "string") return { error: "inputModalities must contain only strings" };
+    if (!ALLOWED_INPUT_MODALITIES.has(value)) rejected.push(value);
+  }
+  if (rejected.length > 0) {
+    return { error: `unsupported input modality: ${rejected.join(", ")} (allowed: text, image, audio)` };
+  }
+  return { values: raw as string[] };
+}
 import type { CatalogModel } from "../../codex/catalog";
 import { catalogModelSlug, disabledNativeSlugs, invalidateCodexModelsCache, nativeModelRows, uniqueCatalogModelsForPublicList } from "../../codex/catalog";
 import { getProviderLiveModelCount } from "../../codex/model-cache";
@@ -54,7 +83,7 @@ import { drainAndShutdown } from "../lifecycle";
 import { filterRequestLogs, getRequestLogEntries, type RequestLogEntry } from "../request-log";
 import { estimateComboCost, estimateRequestCost, normalizeCostTokens, tokensPerSecond } from "../../usage/cost";
 import type { PersistedUsageAttempt } from "../../usage/log";
-import { isAllowedRequestOrigin, jsonResponse, providerManagementConfigError, publicProviderBaseUrl, safeConfigDTO } from "../auth-cors";
+import { isAllowedRequestOrigin, jsonResponse, providerManagementConfigError, publicProviderBaseUrl, safeConfigDTO, corsHeaders } from "../auth-cors";
 import { applySystemEnvToggle } from "../system-env";
 
 import { isPlainRecord, parseDebugLogQuery, tokPerSecondResult, unavailableCostReason, costResult, requestLogDto, stripRegistryOnlyStaticHeaders, fetchAllModels } from "./shared";
@@ -63,6 +92,25 @@ import type { ManagementContext } from "./context";
 
 export async function handleModelRoutes(ctx: ManagementContext): Promise<Response | null> {
   const { req, url, config, deps, refreshCodexCatalogBestEffort, syncClaudeAgentDefsBestEffort } = ctx;
+  // A handler persists the exact config object passed in. Production defaults to
+  // the real store; tests that pass an in-memory fixture inject a no-op/spy. Do not
+  // bypass this seam with a dynamic config import — doing so replaced a user's
+  // ~/.opencodex/config.json with the `existing-uuid` test fixture.
+  const persistConfig = deps.saveConfigPreservingClaudeCode ?? saveConfigPreservingClaudeCode;
+
+  if (url.pathname === "/api/catalog" && req.method === "GET") {
+    const { readCatalog, readCodexCatalogPath } = await import("../../codex/catalog");
+    const catalog = readCatalog(readCodexCatalogPath());
+    if (!catalog) return jsonResponse({ error: "catalog not found" }, 404, req, config);
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+      ...corsHeaders(req, config),
+    };
+    const { loadPersistedCodexRuntime } = await import("../../codex/runtime");
+    const version = loadPersistedCodexRuntime()?.selectedVersion;
+    if (version) headers["x-opencodex-codex-version"] = version;
+    return new Response(JSON.stringify(catalog), { status: 200, headers });
+  }
 
   if (url.pathname === "/api/models" && req.method === "GET") {
     const models = await fetchAllModels(config);
@@ -123,8 +171,7 @@ export async function handleModelRoutes(ctx: ManagementContext): Promise<Respons
     try { body = await req.json(); } catch { return jsonResponse({ error: "invalid JSON body" }, 400); }
     const disabled = Array.isArray(body.models) ? body.models.filter((m): m is string => typeof m === "string") : [];
     config.disabledModels = disabled;
-    const { saveConfigPreservingClaudeCode: save } = await import("../../config");
-    save(config);
+    persistConfig(config);
     await refreshCodexCatalogBestEffort();
     return jsonResponse({ ok: true, disabled });
   }
@@ -223,7 +270,7 @@ export async function handleModelRoutes(ctx: ManagementContext): Promise<Respons
     }
 
     config.disabledModels = disabled;
-    saveConfigPreservingClaudeCode(config);
+    persistConfig(config);
     await refreshCodexCatalogBestEffort();
     return jsonResponse({ ok: true, scope, provider, enabled: body.enabled, disabled });
   }
@@ -244,7 +291,9 @@ export async function handleModelRoutes(ctx: ManagementContext): Promise<Respons
     const displayName = typeof body.displayName === "string" && body.displayName.trim() ? body.displayName.trim() : undefined;
     if (displayName?.includes("/")) return jsonResponse({ error: "displayName must not contain /" }, 400);
     const contextWindow = typeof body.contextWindow === "number" && body.contextWindow > 0 ? Math.floor(body.contextWindow) : undefined;
-    const inputModalities = Array.isArray(body.inputModalities) ? body.inputModalities.filter((m): m is string => typeof m === "string") : undefined;
+    const modalities = readInputModalities(body.inputModalities);
+    if (modalities.error) return jsonResponse({ error: modalities.error }, 400);
+    const inputModalities = modalities.values;
     const existing = config.customModels ?? [];
     const newSlug = routedSlug(provider, modelId);
     if (existing.some(cm => routedSlug(cm.provider, cm.modelId) === newSlug)) {
@@ -260,8 +309,7 @@ export async function handleModelRoutes(ctx: ManagementContext): Promise<Respons
       addedAt: new Date().toISOString(),
     };
     config.customModels = [...existing, entry];
-    const { saveConfigPreservingClaudeCode: save } = await import("../../config");
-    save(config);
+    persistConfig(config);
     await refreshCodexCatalogBestEffort();
     return jsonResponse(entry, 201);
   }
@@ -289,7 +337,9 @@ export async function handleModelRoutes(ctx: ManagementContext): Promise<Respons
       cm.contextWindow = typeof body.contextWindow === "number" && body.contextWindow > 0 ? Math.floor(body.contextWindow) : undefined;
     }
     if (body.inputModalities !== undefined) {
-      cm.inputModalities = Array.isArray(body.inputModalities) ? body.inputModalities.filter((m): m is string => typeof m === "string") : undefined;
+      const edited = readInputModalities(body.inputModalities);
+      if (edited.error) return jsonResponse({ error: edited.error }, 400);
+      cm.inputModalities = edited.values && edited.values.length > 0 ? edited.values : undefined;
     }
     const updatedSlug = routedSlug(cm.provider, cm.modelId);
     if (list.some((other, i) => i !== idx && routedSlug(other.provider, other.modelId) === updatedSlug)) {
@@ -297,8 +347,7 @@ export async function handleModelRoutes(ctx: ManagementContext): Promise<Respons
     }
     list[idx] = cm;
     config.customModels = list;
-    const { saveConfigPreservingClaudeCode: save } = await import("../../config");
-    save(config);
+    persistConfig(config);
     await refreshCodexCatalogBestEffort();
     return jsonResponse(cm);
   }
@@ -312,8 +361,7 @@ export async function handleModelRoutes(ctx: ManagementContext): Promise<Respons
     if (idx === -1) return jsonResponse({ error: "not found" }, 404);
     list.splice(idx, 1);
     config.customModels = list.length > 0 ? list : undefined;
-    const { saveConfigPreservingClaudeCode: save } = await import("../../config");
-    save(config);
+    persistConfig(config);
     await refreshCodexCatalogBestEffort();
     return jsonResponse({ ok: true });
   }
@@ -349,8 +397,7 @@ export async function handleModelRoutes(ctx: ManagementContext): Promise<Respons
     // Empty list clears the allowlist (provider reverts to exposing all models).
     if (models.length > 0) config.providers[provider].selectedModels = models;
     else delete config.providers[provider].selectedModels;
-    const { saveConfigPreservingClaudeCode: save } = await import("../../config");
-    save(config);
+    persistConfig(config);
     await refreshCodexCatalogBestEffort();
     return jsonResponse({ ok: true, provider, selected: models });
   }

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

@@ -2,7 +2,6 @@ import { randomUUID } from "node:crypto";
 import { readFileSync } from "node:fs";
 import type { CatalogModel } from "../../codex/catalog";
 import { catalogModelSlug, invalidateCodexModelsCache, nativeModelRows, uniqueCatalogModelsForPublicList } from "../../codex/catalog";
-import { providerModelsListFromProbeResponse } from "../../codex/catalog/provider-fetch";
 import {
   DEFAULT_SUBAGENT_MODELS,
   codexAutoStartEnabled,
@@ -24,10 +23,16 @@ import {
 } from "../../oauth";
 import { removeCredential } from "../../oauth/store";
 import { providerDestinationResolvedError } from "../../lib/destination-policy";
-import { providerOutboundGet, providerRedirectError } from "../../lib/provider-outbound";
+import { ProviderOutboundPolicyError, providerOutboundGet, providerRedirectError } from "../../lib/provider-outbound";
 import { enrichProviderFromCatalog, listKeyLoginProviders } from "../../oauth/key-providers";
 import { deriveProviderPresets } from "../../providers/derive";
 import { providerCodexAccountMode } from "../../providers/registry";
+import {
+  extractModelEnvelopeRows,
+  extractProviderModelItems,
+  readBoundedDiscoveryJson,
+  resolveProviderModelDiscovery,
+} from "../../providers/model-discovery";
 import { routedSlug, slugEquals } from "../../providers/slug-codec";
 import { clearProviderQuotaCache, fetchProviderQuotaReports } from "../../providers/quota";
 import { CODEX_FORWARD_BASE_URL, isCanonicalOpenAiForwardProvider } from "../../providers/openai-tiers";
@@ -339,6 +344,7 @@ export async function handleProviderRoutes(ctx: ManagementContext): Promise<Resp
       return jsonResponse({ ok: false, latencyMs: 0, error: "static catalog only — upstream not verified (not logged in)" });
     }
     const { url: modelsUrl, headers } = buildModelsRequest(prov, apiKey, name);
+    const discovery = resolveProviderModelDiscovery(name, prov);
     const started = Date.now();
     try {
       const res = await providerOutboundGet(name, prov, modelsUrl, {
@@ -355,15 +361,42 @@ export async function handleProviderRoutes(ctx: ManagementContext): Promise<Resp
         });
       }
       if (!res.ok) {
+        try {
+          void res.body?.cancel().catch(() => undefined);
+        } catch {
+          // Best-effort release for non-conforming response streams.
+        }
         return jsonResponse({ ok: false, latencyMs, error: `upstream /models returned ${res.status}` });
       }
-      const json = await res.json().catch(() => null);
-      // OpenAI-style { data }, Google { models }, and Together-style top-level arrays (#617).
-      const list = providerModelsListFromProbeResponse(json);
-      if (!Array.isArray(list)) {
-        return jsonResponse({ ok: false, latencyMs, error: "upstream /models returned an unexpected shape" });
+      const bounded = await readBoundedDiscoveryJson(res, discovery.maxResponseBytes);
+      if (!bounded.ok) {
+        return jsonResponse({
+          ok: false,
+          latencyMs,
+          error: bounded.reason === "response_too_large"
+            ? `upstream /models exceeded the ${discovery.maxResponseBytes}-byte response limit`
+            : "upstream /models returned invalid JSON",
+        });
+      }
+      // OpenAI-style lists (and Together top-level arrays) use the same validation/dedupe/filter
+      // as catalog discovery. Google's /v1beta/models uses `models[].name` and remains a
+      // connectivity-only count because it is not an authoritative catalog source.
+      const record = bounded.value !== null && typeof bounded.value === "object" && !Array.isArray(bounded.value)
+        ? bounded.value as Record<string, unknown>
+        : undefined;
+      const extracted = Array.isArray(bounded.value) || Array.isArray(record?.data)
+        ? extractProviderModelItems(bounded.value, discovery)
+        : extractModelEnvelopeRows(bounded.value, discovery.maxModels, ["models"]);
+      if (!extracted.ok) {
+        return jsonResponse({
+          ok: false,
+          latencyMs,
+          error: extracted.reason === "too_many_models"
+            ? `upstream /models exceeded the ${discovery.maxModels}-row model limit`
+            : "upstream /models returned an unexpected shape",
+        });
       }
-      const models = list.length;
+      const models = "items" in extracted ? extracted.items.length : extracted.rows.length;
       return jsonResponse({
         ok: true,
         latencyMs,
@@ -374,7 +407,9 @@ export async function handleProviderRoutes(ctx: ManagementContext): Promise<Resp
       return jsonResponse({
         ok: false,
         latencyMs: Date.now() - started,
-        error: err instanceof Error ? err.message : "Connection test failed",
+        error: err instanceof ProviderOutboundPolicyError
+          ? `upstream /models blocked by destination policy: ${err.message}`
+          : err instanceof Error ? err.message : "Connection test failed",
       });
     }
   }