@bitkyc08/opencodex 2.11.1 → 2.12.0

package/src/server/index.ts

@@ -25,12 +25,11 @@ import { getCodexHome } from "../codex/paths";
 import { shouldSyncCodexOnStart } from "../codex/desired-state";
 import { inspectNativeCodexOwnership } from "../integrations/native/ownership-preflight";
 import { registerCodexCooldownRecoveryProbeWorker } from "../codex/auth-api";
-import { startMemoryWatchdog } from "./memory-watchdog";
 import {
   reconcileLiveStateStores,
   setLiveStateStoreConfig,
 } from "../lib/state-store-registrations";
-import { startStateStoreSweeper } from "../lib/state-store-sweeper";
+import { startUserCostOverlayReconciler } from "../usage/user-cost-overlay-reconciler";
 import {
   configureAppOwnedMemoryBudget,
   enforceAppOwnedMemoryBudget,
@@ -41,9 +40,7 @@ import {
   registerDefaultAppOwnedMemoryStores,
   registerDefaultAppOwnedObservedBuffers,
 } from "../lib/app-owned-memory-stores";
-import { setStorageCleanupPolicyLiveSink } from "../storage/policy";
-import { setStorageCleanupPolicyJobLiveApply } from "../storage/policy-job";
-import { scheduleStorageCleanupStartupRun, startStorageCleanupScheduler } from "../storage/policy-scheduler";
+import { acquireServerBackgroundLifecycle } from "./background-lifecycle";
 import { runOpenAiTierStartupMigration } from "../providers/openai-tier-startup";
 import { runAlibabaRegionStartupMigration } from "../providers/alibaba-region-startup";
 import { isCanonicalOpenAiForwardProvider } from "../providers/openai-tiers";
@@ -189,11 +186,42 @@ import {
 import { SYSTEM_RESTART_CAPABILITY_VERSION } from "../lib/system-restart-contract";
 import { createReadinessGate, type ReadinessGate } from "./readiness";
 
-const MAX_WS_FRAME_BYTES = 50 * 1024 * 1024;
+export const MAX_WS_FRAME_BYTES = 50 * 1024 * 1024;
 const WEBSOCKET_IDLE_TIMEOUT_SECONDS = 0;
 const LIVE_SIDEBAND_PENDING_MAX = 32;
+const LIVE_SIDEBAND_PENDING_BYTES_MAX = 1024 * 1024;
 const LIVE_SIDEBAND_CLOSE_FALLBACK_MS = 1_000;
 
+export function exceedsLiveSidebandFrameByteLimit(frameBytes: number): boolean {
+  return frameBytes > MAX_WS_FRAME_BYTES;
+}
+
+export function exceedsLiveSidebandPendingByteLimit(pendingBytes: number, incomingBytes: number): boolean {
+  return incomingBytes > LIVE_SIDEBAND_PENDING_BYTES_MAX - pendingBytes;
+}
+
+function webSocketFrameBytes(frame: string | ArrayBuffer | ArrayBufferView | Blob | Buffer): number {
+  if (typeof frame === "string") return Buffer.byteLength(frame);
+  if (frame instanceof ArrayBuffer || ArrayBuffer.isView(frame)) return frame.byteLength;
+  return frame.size;
+}
+
+export type LiveSidebandPendingEnqueueResult = "queued" | "too-many-frames" | "too-many-bytes";
+
+export function enqueueLiveSidebandPendingFrame(
+  data: Pick<WsData, "livePending" | "livePendingBytes">,
+  frame: string | Buffer,
+  frameBytes = webSocketFrameBytes(frame),
+): LiveSidebandPendingEnqueueResult {
+  const pending = data.livePending ?? (data.livePending = []);
+  if (pending.length >= LIVE_SIDEBAND_PENDING_MAX) return "too-many-frames";
+  const pendingBytes = data.livePendingBytes ?? 0;
+  if (exceedsLiveSidebandPendingByteLimit(pendingBytes, frameBytes)) return "too-many-bytes";
+  pending.push(frame);
+  data.livePendingBytes = pendingBytes + frameBytes;
+  return "queued";
+}
+
 type LiveSidebandWebSocketFactory = (
   url: string,
   headers: Record<string, string>,
@@ -228,6 +256,7 @@ function finalizeLiveSideband(ws: ServerWebSocket<WsData>, upstream?: WebSocket)
   }
   ws.data.liveUpstream = undefined;
   ws.data.livePending = undefined;
+  ws.data.livePendingBytes = undefined;
   ws.data.cancel = undefined;
   releaseLiveSidebandAdmission(ws);
 }
@@ -263,6 +292,7 @@ function closeLiveSideband(ws: ServerWebSocket<WsData>, code = 1000, reason = ""
   if (ws.data.liveClosing) return;
   ws.data.liveClosing = true;
   ws.data.livePending = undefined;
+  ws.data.livePendingBytes = undefined;
   ws.data.cancel = undefined;
   const upstream = ws.data.liveUpstream;
   // Bun's `WebSocket` type narrows `readyState` to 0|1|2 even though the DOM
@@ -318,6 +348,7 @@ function attachLiveSidebandUpstream(
     ws.data.liveOpened = true;
     const pending = ws.data.livePending ?? [];
     ws.data.livePending = undefined;
+    ws.data.livePendingBytes = undefined;
     for (const frame of pending) {
       try {
         sendUpstreamFrame(upstream, frame);
@@ -330,6 +361,10 @@ function attachLiveSidebandUpstream(
   upstream.addEventListener("message", (event) => {
     if (ws.data.liveUpstream !== upstream || ws.data.liveClosing) return;
     try {
+      if (exceedsLiveSidebandFrameByteLimit(webSocketFrameBytes(event.data))) {
+        closeLiveSideband(ws, 1009, "message too large");
+        return;
+      }
       logLiveSidebandFrame("u2c", event.data);
       if (typeof event.data === "string") ws.send(event.data);
       else if (event.data instanceof ArrayBuffer) ws.send(event.data);
@@ -426,6 +461,7 @@ export function startServer(port?: number, deps: StartServerDeps = {}): Server<W
   applyProxyEnv(config);
   assertServerAuthConfig(config);
   const managementAuth = deps.managementAuthState ?? initializeManagementAuthState(config);
+  let userCostOverlayReconciler: { stop(): void } | null = null;
   // Arm synchronously before listen. A pending journal therefore makes __main__ unusable
   // before any request can resolve its physical credential, while health/management/Pool stay live.
   // Refresh OAuth provider presets (models/noReasoningModels) from the registry so a proxy update
@@ -486,16 +522,12 @@ export function startServer(port?: number, deps: StartServerDeps = {}): Server<W
   // usage.jsonl already persists every request; rehydrate the in-memory Logs ring so
   // /api/logs (and the GUI) survive `ocx stop` / `ocx start` process restarts.
   hydrateRequestLogsFromDisk();
-  // #314: warn-only RSS observability (unref'd, idempotent — safe under repeated
-  // startServer(0) in tests). Snapshot surfaces via GET /api/system/memory.
-  startMemoryWatchdog();
   registerDefaultAppOwnedMemoryStores();
   registerDefaultAppOwnedObservedBuffers();
   registerAppOwnedMemorySweepFallback();
   configureAppOwnedMemoryBudget(resolveAppOwnedMemoryBudgetBytes(config.appOwnedMemoryBudgetMb));
   enforceAppOwnedMemoryBudget();
   registerCodexCooldownRecoveryProbeWorker(config);
-  startStateStoreSweeper();
   // Issue #42 Phase 3: opt-in archived auto-cleanup (default OFF). Unref'd hourly
   // tick for daily/weekly; startup evaluation is fire-and-forget after listen.
   // Heavy work runs in a Worker via the single-flight job controller.
@@ -503,9 +535,6 @@ export function startServer(port?: number, deps: StartServerDeps = {}): Server<W
   const applyPolicy = (policy: StorageCleanupPolicy) => {
     config.storageCleanupPolicy = policy;
   };
-  setStorageCleanupPolicyLiveSink(applyPolicy);
-  setStorageCleanupPolicyJobLiveApply(applyPolicy);
-  startStorageCleanupScheduler();
 
   const listenPort = port ?? config.port ?? 10100;
   setCorsOrigin(listenPort);
@@ -632,7 +661,14 @@ export function startServer(port?: number, deps: StartServerDeps = {}): Server<W
     };
   let server: Server<WsData>;
   let loopbackServer: Server<WsData> | null = null;
+  let backgroundLifecycle: ReturnType<typeof acquireServerBackgroundLifecycle> | null = null;
   try {
+    backgroundLifecycle = acquireServerBackgroundLifecycle(applyPolicy);
+    // External `ocx config set` / direct config.json edits run in other
+    // processes; poll the file so Logs/Usage display prices follow them live.
+    // Started inside the guarded startup transaction so the catch below can
+    // release the owner-scoped lease on any listener failure.
+    userCostOverlayReconciler = startUserCostOverlayReconciler({ liveConfig: config });
     const serveOptions = {
       idleTimeout: 255,
       async fetch(req: Request, requestServer: Server<WsData>): Promise<Response> {
@@ -1264,6 +1300,7 @@ export function startServer(port?: number, deps: StartServerDeps = {}): Server<W
             liveUpstreamUrl: resolved.upstreamWsUrl,
             liveUpstreamHeaders: resolved.headers,
             livePending: [],
+            livePendingBytes: 0,
             liveOpened: false,
             liveTurnAdmissionLease: turnAdmissionLease,
           } satisfies WsData,
@@ -1297,6 +1334,7 @@ export function startServer(port?: number, deps: StartServerDeps = {}): Server<W
       return withCors(formatErrorResponse(404, "not_found", `Unknown endpoint: ${req.method} ${url.pathname}`), req, config);
     },
     websocket: {
+      maxPayloadLength: MAX_WS_FRAME_BYTES,
       idleTimeout: WEBSOCKET_IDLE_TIMEOUT_SECONDS,
       // Responses WebSocket data plane (phase 120.2). Re-frames the same SSE pipeline onto the
       // socket: parse response.create → run handleResponses unchanged → pump its SSE body as WS
@@ -1321,15 +1359,23 @@ export function startServer(port?: number, deps: StartServerDeps = {}): Server<W
       message(ws: ServerWebSocket<WsData>, raw: string | Buffer) {
         if (ws.data.kind === "live-sideband") {
           if (ws.data.liveClosing) return;
+          const rawBytes = webSocketFrameBytes(raw);
+          if (exceedsLiveSidebandFrameByteLimit(rawBytes)) {
+            closeLiveSideband(ws, 1009, "message too large");
+            return;
+          }
           logLiveSidebandFrame("c2u", raw);
           const upstream = ws.data.liveUpstream;
           if (!upstream || upstream.readyState === WebSocket.CONNECTING || !ws.data.liveOpened) {
-            const pending = ws.data.livePending ?? (ws.data.livePending = []);
-            if (pending.length >= LIVE_SIDEBAND_PENDING_MAX) {
+            const enqueueResult = enqueueLiveSidebandPendingFrame(ws.data, raw, rawBytes);
+            if (enqueueResult === "too-many-frames") {
               closeLiveSideband(ws, 1009, "too many pending frames");
               return;
             }
-            pending.push(raw);
+            if (enqueueResult === "too-many-bytes") {
+              closeLiveSideband(ws, 1009, "too many pending bytes");
+              return;
+            }
             return;
           }
           if (upstream.readyState !== WebSocket.OPEN) {
@@ -1527,6 +1573,8 @@ export function startServer(port?: number, deps: StartServerDeps = {}): Server<W
       }
     }
   } catch (error) {
+    userCostOverlayReconciler?.stop();
+    backgroundLifecycle?.releaseAfterFailedStart();
     void nativeMainLifecycle.release();
     throw error;
   }
@@ -1545,8 +1593,14 @@ export function startServer(port?: number, deps: StartServerDeps = {}): Server<W
           ...(loopbackListenerRef
             ? [() => loopbackListenerRef.stop(closeActiveConnections)]
             : []),
+          async () => {
+            userCostOverlayReconciler?.stop();
+          },
         ],
-        () => releaseNativeMainStartupLifecycle(server),
+        async () => {
+          await backgroundLifecycle.release();
+          await releaseNativeMainStartupLifecycle(server);
+        },
       );
     },
   });
@@ -1590,7 +1644,7 @@ export function startServer(port?: number, deps: StartServerDeps = {}): Server<W
   }
 
   // Opt-in storage policy (default OFF). Never blocks listen; cancellable on shutdown.
-  scheduleStorageCleanupStartupRun();
+  backgroundLifecycle.scheduleStartupRun();
 
   return server;
 }

package/src/server/lifecycle.ts

@@ -447,6 +447,12 @@ export async function drainAndShutdown(
     // then drain leftovers; failures must not prevent `server.stop`.
     stopStorageCleanupScheduler();
     stopStateStoreSweeper();
+    // The overlay reconciler is owner-scoped: the startServer stop override
+    // releases THIS server's lease through runListenerShutdown →
+    // userCostOverlayReconciler.stop(), which also recomputes disk-only
+    // preservation for any remaining owners. A process-wide stop here would
+    // kill reconciliation for every other server in the process, so drain
+    // must not call stopUserCostOverlayReconciler().
     cancelQueuedStorageWorkerSpawns();
     const shutdownJoins = await Promise.allSettled([
       abortStorageCleanupPolicyJobAsync(),

package/src/server/live.ts

@@ -207,8 +207,12 @@ export function parseLiveSidebandTarget(pathname: string, searchParams: URLSearc
  */
 function isLoopbackHost(hostname: string): boolean {
   const lower = hostname.toLowerCase();
+  const ipv4 = lower.split(".");
+  const ipv4Loopback = ipv4.length === 4
+    && ipv4[0] === "127"
+    && ipv4.every(part => /^\d{1,3}$/.test(part) && Number(part) <= 255);
   return lower === "localhost" || lower.endsWith(".localhost")
-    || lower === "127.0.0.1" || lower.startsWith("127.")
+    || ipv4Loopback
     || lower === "::1" || lower === "[::1]";
 }
 

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

@@ -51,6 +51,11 @@ import {
   type DebugFlag,
 } from "../../lib/debug-settings";
 import type { OcxClaudeCodeConfig, OcxConfig, OcxCustomModel, OcxProviderConfig } from "../../types";
+import {
+  visionCandidateRows,
+  visionDescriberIsProvablyBlind,
+  visionDescriberRejection,
+} from "./vision-sidecar-options";
 import { drainAndShutdown } from "../lifecycle";
 import { filterRequestLogs, getRequestLogEntries, type RequestLogEntry } from "../request-log";
 import { estimateComboCost, estimateRequestCost, normalizeCostTokens, tokensPerSecond } from "../../usage/cost";
@@ -60,7 +65,7 @@ import { applySystemEnvToggle } from "../system-env";
 
 import { isPlainRecord, parseDebugLogQuery, tokPerSecondResult, unavailableCostReason, costResult, requestLogDto, stripRegistryOnlyStaticHeaders, fetchAllModels, fetchGrokCandidateModels, buildClaudeDesktopState } from "./shared";
 import type { MetricUnavailableReason, TokPerSecondResult, CostEstimateReason, CostResult, MetricSource } from "./shared";
-import { readManagementJsonBody, rethrowManagementBodyTooLarge } from "./body";
+import { readManagementJsonBody, readOptionalManagementJsonBody, rethrowManagementBodyTooLarge } from "./body";
 
 const GROK_APPLY_JOIN_MS = 120_000;
 export const GROK_APPLY_TERMINAL_MS = 10 * 60_000;
@@ -759,32 +764,22 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
   }
   if (url.pathname === "/api/claude-desktop/apply" && req.method === "POST") {
     try {
-      const { setIntegrationEnabled, claudeDesktopIntegrationEnabled } = await import("../../codex/desired-state");
-      const desired = setIntegrationEnabled("claude-desktop", true);
-      if (!desired.ok) return jsonResponse({ error: desired.message }, desired.retryable ? 409 : 500);
-      // Disk now says ON; the reused server snapshot must agree, or the native
-      // GET reports OFF and a later whole-snapshot save undoes this transition.
-      mirrorDesiredEnabledOntoSnapshot(config, "claude-desktop", true);
-      // Disk now says ON; the reused server snapshot must agree, or the native
-      // GET reports OFF and a later whole-snapshot save undoes this transition.
       // #859: the CLI delegates here so the registry is built in the serving
       // process. Accept an optional mode; default stays static for back-compat.
       let mode: "static" | "hybrid" | "discovery" = "static";
-      const rawBody = await req.text();
       let parsed: unknown;
-      if (rawBody.trim()) {
-        try {
-          parsed = JSON.parse(rawBody);
-        } catch {
-          return jsonResponse({ error: "invalid JSON body" }, 400);
-        }
-        const requested = (parsed as { mode?: unknown } | null)?.mode;
-        if (requested !== undefined) {
-          if (requested === "static" || requested === "hybrid" || requested === "discovery") {
-            mode = requested;
-          } else {
-            return jsonResponse({ error: "mode must be static, hybrid, or discovery" }, 400);
-          }
+      try {
+        parsed = await readOptionalManagementJsonBody(req);
+      } catch (error) {
+        rethrowManagementBodyTooLarge(error);
+        return jsonResponse({ error: "invalid JSON body" }, 400);
+      }
+      const requested = (parsed as { mode?: unknown } | null)?.mode;
+      if (requested !== undefined) {
+        if (requested === "static" || requested === "hybrid" || requested === "discovery") {
+          mode = requested;
+        } else {
+          return jsonResponse({ error: "mode must be static, hybrid, or discovery" }, 400);
         }
       }
       // #859: a delegated CLI apply carries the profile it just saved — the
@@ -800,6 +795,12 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
           return jsonResponse({ error: error instanceof Error ? error.message : String(error) }, 400);
         }
       }
+      const { setIntegrationEnabled, claudeDesktopIntegrationEnabled } = await import("../../codex/desired-state");
+      const desired = setIntegrationEnabled("claude-desktop", true);
+      if (!desired.ok) return jsonResponse({ error: desired.message }, desired.retryable ? 409 : 500);
+      // Disk now says ON; the reused server snapshot must agree, or the native
+      // GET reports OFF and a later whole-snapshot save undoes this transition.
+      mirrorDesiredEnabledOntoSnapshot(config, "claude-desktop", true);
       const state = await buildClaudeDesktopState(config, profileOverride);
       // `setIntegrationEnabled` above wrote desired ON to DISK; it does not touch
       // this long-lived server snapshot. Saving the snapshot wholesale would carry
@@ -866,6 +867,7 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
       }
       return jsonResponse({ ok: true, saved: true, applied: true, path: result.path, fingerprint: result.fingerprint });
     } catch (error) {
+      rethrowManagementBodyTooLarge(error);
       return jsonResponse({ error: error instanceof Error ? error.message : String(error) }, 400);
     }
   }
@@ -1010,6 +1012,19 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
       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.
+      if (field === "visionSidecar" && typeof section.model === "string" && section.model !== "") {
+        const requested = section.model;
+        const candidates = await visionCandidateRows(config);
+        const hint = section.backend === "anthropic" || section.backend === "openai"
+          ? section.backend
+          : config.claudeCode?.visionSidecar?.backend;
+        if (visionDescriberIsProvablyBlind(config, requested, candidates, hint)) {
+          return jsonResponse(visionDescriberRejection("visionSidecar.model", requested, config, candidates), 400);
+        }
+      }
     }
     const next = { ...(config.claudeCode ?? {}) };
     for (const field of ["webSearchSidecar", "visionSidecar"] as const) {
@@ -1118,11 +1133,12 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
         else delete next.tierModels;
       }
     }
+    let nextFastMode = config.fastMode;
     if (body.fastMode !== undefined) {
       if (body.fastMode !== true && body.fastMode !== false && body.fastMode !== null) {
         return jsonResponse({ error: "fastMode must be true, false, or null" }, 400);
       }
-      config.fastMode = body.fastMode === null ? undefined : body.fastMode;
+      nextFastMode = body.fastMode === null ? undefined : body.fastMode;
     }
     for (const field of ["model", "smallFastModel"] as const) {
       const value = body[field];
@@ -1149,6 +1165,7 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
         else delete next.modelMap;
       }
     }
+    if (body.fastMode !== undefined) config.fastMode = nextFastMode;
     config.claudeCode = next;
     // Stamp the migration sentinel on EVERY persist of this block. The migration reads
     // "a claudeCode block with no authMode" as a pre-upgrade subscriber and pins it to

package/src/server/management/body.ts

@@ -11,6 +11,12 @@ export function readManagementJsonBody<T = unknown>(req: Request): Promise<T> {
   return readBoundedJsonRequestBody(req, MANAGEMENT_JSON_BODY_MAX_BYTES) as Promise<T>;
 }
 
+export function readOptionalManagementJsonBody<T = unknown>(req: Request): Promise<T> {
+  return readBoundedJsonRequestBody(req, MANAGEMENT_JSON_BODY_MAX_BYTES, undefined, {
+    emptyBodyFallback: {},
+  }) as Promise<T>;
+}
+
 export function managementBodyTooLargeResponse(
   error: unknown,
   req: Request,

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

@@ -54,6 +54,13 @@ import { stripCodexRuntimeProviderFields } from "../../codex/auth-context";
 import { getProviderRegistryEntry } from "../../providers/registry";
 import { VISION_REASONING_EFFORTS, isVisionReasoningEffort } from "../../reasoning-effort";
 import { normalizeVisionReasoningForModel } from "../../vision/reasoning";
+import { findAnthropicVisionProvider, resolveEffectiveVisionModel, resolveVisionBackend } from "../../vision";
+import {
+  visionCandidateRows,
+  visionDescriberIsProvablyBlind,
+  visionDescriberRejection,
+  visionModelOptionsFor,
+} from "./vision-sidecar-options";
 import { getDebugLogEntries } from "../../lib/debug-log-buffer";
 import { getInjectionDebugLogEntries } from "../../lib/injection-debug-log";
 import {
@@ -80,6 +87,27 @@ import type { MetricUnavailableReason, TokPerSecondResult, CostEstimateReason, C
 import type { ManagementContext } from "./context";
 import { readManagementJsonBody, rethrowManagementBodyTooLarge } from "./body";
 
+async function sidecarVisionResponseSettings(config: OcxConfig): Promise<{
+  model: string;
+  reasoning: string;
+  models: Awaited<ReturnType<typeof visionModelOptionsFor>>;
+}> {
+  const vs = config.visionSidecar ?? {};
+  // Match the runtime's one selected Anthropic executor for both backend fallback
+  // and catalog reachability; resolving it once prevents the two projections drifting.
+  const anthropicSidecar = findAnthropicVisionProvider(config);
+  const backend = resolveVisionBackend(vs.backend, anthropicSidecar);
+  const model = resolveEffectiveVisionModel(config, backend);
+  const reasoning = normalizeVisionReasoningForModel(model, vs.reasoning) ?? "low";
+  const models = await visionModelOptionsFor(config, anthropicSidecar);
+  // Display-only grandfather: a persisted id stays selectable, but the write gate
+  // remains stricter and rejects a model that is positively proven blind.
+  if (!models.some(option => option.value === model)) {
+    models.unshift({ value: model, label: model, backend });
+  }
+  return { model, reasoning, models };
+}
+
 export async function handleConfigRoutes(ctx: ManagementContext): Promise<Response | null> {
   const { req, url, config, deps, convergeCodexCatalog, syncClaudeAgentDefsBestEffort } = ctx;
   if (url.pathname === "/api/config" && req.method === "GET") {
@@ -380,16 +408,16 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
   if (url.pathname === "/api/sidecar-settings" && req.method === "GET") {
     const ws = config.webSearchSidecar ?? {};
     const vs = config.visionSidecar ?? {};
-    const visionModel = vs.model || "gpt-5.4-mini";
-    const visionReasoning = normalizeVisionReasoningForModel(visionModel, vs.reasoning) ?? "low";
+    const vision = await sidecarVisionResponseSettings(config);
     return jsonResponse({
       webSearch: { model: ws.model ?? "gpt-5.6-luna", backend: ws.backend },
       vision: {
-        model: visionModel,
+        model: vision.model,
         backend: vs.backend,
-        reasoning: visionReasoning,
+        reasoning: vision.reasoning,
         maxDescriptionsPerTurn: vs.maxDescriptionsPerTurn,
       },
+      visionModels: vision.models,
     });
   }
 
@@ -422,6 +450,21 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
     if (body.vision?.reasoning !== undefined && !isVisionReasoningEffort(body.vision.reasoning)) {
       return jsonResponse({ error: `vision.reasoning must be ${VISION_REASONING_EFFORTS.join(", ")}` }, 400);
     }
+    // Reject ONLY a model we can prove is blind. An id nothing knows about stays
+    // allowed: the operator may be ahead of our catalog, and the runtime never
+    // required catalog membership (`tests/vision-reasoning-contract.test.ts`
+    // pins `custom-vision` → 200). The catalog is read ONCE and reused for the
+    // rejection body, so a 400 cannot cost two provider fetches.
+    if (body.vision && typeof body.vision.model === "string" && body.vision.model !== "") {
+      const requested = body.vision.model;
+      const candidates = await visionCandidateRows(config);
+      const hint = body.vision.backend === "anthropic" || body.vision.backend === "openai"
+        ? body.vision.backend
+        : config.visionSidecar?.backend;
+      if (visionDescriberIsProvablyBlind(config, requested, candidates, hint)) {
+        return jsonResponse(visionDescriberRejection("vision.model", requested, config, candidates), 400);
+      }
+    }
 
     let normalizedVisionReasoning: ReturnType<typeof normalizeVisionReasoningForModel>;
     let visionReasoningTouched = false;
@@ -469,17 +512,17 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
     saveConfigPreservingClaudeCode(config);
     const ws = config.webSearchSidecar ?? {};
     const vs = config.visionSidecar ?? {};
-    const visionModel = vs.model || "gpt-5.4-mini";
-    const visionReasoning = normalizeVisionReasoningForModel(visionModel, vs.reasoning) ?? "low";
+    const vision = await sidecarVisionResponseSettings(config);
     return jsonResponse({
       ok: true,
       webSearch: { model: ws.model ?? "gpt-5.6-luna", backend: ws.backend },
       vision: {
-        model: visionModel,
+        model: vision.model,
         backend: vs.backend,
-        reasoning: visionReasoning,
+        reasoning: vision.reasoning,
         maxDescriptionsPerTurn: vs.maxDescriptionsPerTurn,
       },
+      visionModels: vision.models,
     });
   }