@bitkyc08/opencodex 2.39.0 → 2.40.0

package/src/server/management/api-key-rotation.ts

@@ -0,0 +1,74 @@
+import { randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
+import type { OcxConfig } from "../../types";
+
+export const API_KEY_ROTATION_TTL_MS = 10 * 60_000;
+
+export type ApiKeyRotationStart = {
+  id: string;
+  name: string;
+  key: string;
+  rotationId: string;
+  expiresAt: string;
+};
+
+function equalOpaqueId(left: string, right: string): boolean {
+  const encoder = new TextEncoder();
+  const a = encoder.encode(left);
+  const b = encoder.encode(right);
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+
+export function removeExpiredApiKeyRotations(config: OcxConfig, now = Date.now()): boolean {
+  let changed = false;
+  for (const entry of config.apiKeys ?? []) {
+    if (entry.pendingRotation && Date.parse(entry.pendingRotation.expiresAt) <= now) {
+      delete entry.pendingRotation;
+      changed = true;
+    }
+  }
+  return changed;
+}
+
+export function startApiKeyRotation(
+  config: OcxConfig,
+  keyId: string,
+  now = Date.now(),
+): ApiKeyRotationStart | { error: "not-found" | "already-pending" } {
+  const entry = (config.apiKeys ?? []).find(candidate => candidate.id === keyId);
+  if (!entry) return { error: "not-found" };
+  if (entry.pendingRotation && Date.parse(entry.pendingRotation.expiresAt) > now) {
+    return { error: "already-pending" };
+  }
+  const key = `ocx_data_${randomBytes(20).toString("hex")}`;
+  const rotationId = randomUUID();
+  const createdAt = new Date(now).toISOString();
+  const expiresAt = new Date(now + API_KEY_ROTATION_TTL_MS).toISOString();
+  entry.pendingRotation = { id: rotationId, key, createdAt, expiresAt };
+  return { id: entry.id, name: entry.name, key, rotationId, expiresAt };
+}
+
+export function commitApiKeyRotation(
+  config: OcxConfig,
+  keyId: string,
+  rotationId: string,
+  now = Date.now(),
+): { ok: true } | { error: "not-found" | "expired" | "mismatch" } {
+  const entry = (config.apiKeys ?? []).find(candidate => candidate.id === keyId);
+  if (!entry?.pendingRotation) return { error: "not-found" };
+  const pending = entry.pendingRotation;
+  if (Date.parse(pending.expiresAt) <= now) {
+    delete entry.pendingRotation;
+    return { error: "expired" };
+  }
+  if (!equalOpaqueId(pending.id, rotationId)) return { error: "mismatch" };
+  entry.key = pending.key;
+  delete entry.pendingRotation;
+  return { ok: true };
+}
+
+export function abortApiKeyRotation(config: OcxConfig, keyId: string, rotationId: string): boolean {
+  const entry = (config.apiKeys ?? []).find(candidate => candidate.id === keyId);
+  if (!entry?.pendingRotation || !equalOpaqueId(entry.pendingRotation.id, rotationId)) return false;
+  delete entry.pendingRotation;
+  return true;
+}

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

@@ -68,12 +68,24 @@ import { readManagementJsonBody, rethrowManagementBodyTooLarge } from "./body";
 import { shadowCallTargetError } from "./shadow-call-validation";
 
 
-/** Management wire shape: omit default imageInput "auto" (persist/response sparse). */
-function sparseComboConfig<T extends { imageInput?: "auto" | "disabled" }>(combo: T): Omit<T, "imageInput"> & { imageInput?: "disabled" } {
-  const { imageInput, ...rest } = combo;
+/**
+ * Management wire shape: omit fields whose value is the default, so GET responses and
+ * persisted config stay sparse. A default echoed here would be written straight back by
+ * any client that round-trips GET into PUT, which is how an unset option ends up
+ * materialized in every user's config.json.
+ */
+function sparseComboConfig<T extends {
+  imageInput?: "auto" | "disabled";
+  reasoningEffortMode?: "strict" | "adaptive";
+}>(combo: T): Omit<T, "imageInput" | "reasoningEffortMode"> & {
+  imageInput?: "disabled";
+  reasoningEffortMode?: "adaptive";
+} {
+  const { imageInput, reasoningEffortMode, ...rest } = combo;
   return {
     ...rest,
     ...(imageInput === "disabled" ? { imageInput: "disabled" as const } : {}),
+    ...(reasoningEffortMode === "adaptive" ? { reasoningEffortMode: "adaptive" as const } : {}),
   };
 }
 
@@ -137,19 +149,19 @@ export async function handleComboRoutes(ctx: ManagementContext): Promise<Respons
     if (error) return jsonResponse({ error }, 400);
     const normalized = normalizeComboConfig(body.combo as import("../../types").OcxComboConfig);
     // Persist only non-default identity/capability fields so config stays sparse.
+    // Capability defaults (`imageInput`, `reasoningEffortMode`) go through the same
+    // helper the GET/PUT responses use, so the wire shape and the stored shape cannot drift.
     const {
       alias: normalizedAlias,
       nativeAlias: normalizedNativeAlias,
       displayName: normalizedDisplayName,
-      imageInput: normalizedImageInput,
       ...normalizedBase
-    } = normalized;
+    } = sparseComboConfig(normalized);
     const stored: import("../../types").OcxComboConfig = {
       ...normalizedBase,
       ...(normalizedAlias ? { alias: normalizedAlias } : {}),
       ...(normalizedNativeAlias ? { nativeAlias: true } : {}),
       ...(normalizedDisplayName ? { displayName: normalizedDisplayName } : {}),
-      ...(normalizedImageInput === "disabled" ? { imageInput: "disabled" as const } : {}),
     };
     const sourceId = renameFrom ?? id;
     const previous = config.combos?.[sourceId];

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

@@ -306,6 +306,8 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
       // Absent means the historical auto-open, so the GUI can render the toggle
       // without having to know that `undefined` and `true` mean the same thing.
       oauthOpenBrowser: config.oauthOpenBrowser !== false,
+      // Absent means off (today's Design B injection), so the GUI/CLI render a plain switch.
+      codexDesktopAuthless: config.codexDesktopAuthless === true,
       startupHealth: await readStartupHealth(config),
       codexRuntime: {
         path: displayCodexRuntimePath(resolved.runtime.command),
@@ -392,14 +394,16 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
       codexAccountPickerEnabled?: unknown;
       oauthOpenBrowser?: unknown;
       showCodexSparkQuota?: unknown;
+      codexDesktopAuthless?: unknown;
     };
     if (body.codexAutoStart === undefined
       && body.streamMode === undefined
       && body.appOwnedMemoryBudgetMb === undefined
       && body.codexAccountPickerEnabled === undefined
       && body.oauthOpenBrowser === undefined
-      && body.showCodexSparkQuota === undefined) {
-      return jsonResponse({ error: "provide codexAutoStart, streamMode, appOwnedMemoryBudgetMb, codexAccountPickerEnabled, oauthOpenBrowser, or showCodexSparkQuota" }, 400);
+      && body.showCodexSparkQuota === undefined
+      && body.codexDesktopAuthless === undefined) {
+      return jsonResponse({ error: "provide codexAutoStart, streamMode, appOwnedMemoryBudgetMb, codexAccountPickerEnabled, oauthOpenBrowser, showCodexSparkQuota, or codexDesktopAuthless" }, 400);
     }
     if (body.codexAutoStart !== undefined && typeof body.codexAutoStart !== "boolean") {
       return jsonResponse({ error: "codexAutoStart boolean is required" }, 400);
@@ -417,6 +421,9 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
     if (body.showCodexSparkQuota !== undefined && typeof body.showCodexSparkQuota !== "boolean") {
       return jsonResponse({ error: "showCodexSparkQuota boolean is required" }, 400);
     }
+    if (body.codexDesktopAuthless !== undefined && typeof body.codexDesktopAuthless !== "boolean") {
+      return jsonResponse({ error: "codexDesktopAuthless boolean is required" }, 400);
+    }
     if (body.appOwnedMemoryBudgetMb !== undefined && (
       typeof body.appOwnedMemoryBudgetMb !== "number"
       || !Number.isInteger(body.appOwnedMemoryBudgetMb)
@@ -440,9 +447,12 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
       hasOauthOpenBrowser: Object.hasOwn(config, "oauthOpenBrowser"),
       showCodexSparkQuota: config.showCodexSparkQuota,
       hasShowCodexSparkQuota: Object.hasOwn(config, "showCodexSparkQuota"),
+      codexDesktopAuthless: config.codexDesktopAuthless,
+      hasCodexDesktopAuthless: Object.hasOwn(config, "codexDesktopAuthless"),
     };
     const pickerWasEnabled = codexAccountPickerEnabled(config);
     let pickerIsEnabled = pickerWasEnabled;
+    const authlessWasEnabled = config.codexDesktopAuthless === true;
     try {
       if (typeof body.codexAutoStart === "boolean") {
         config.codexAutoStart = body.codexAutoStart;
@@ -469,6 +479,8 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
       if (typeof body.showCodexSparkQuota === "boolean") {
         config.showCodexSparkQuota = body.showCodexSparkQuota;
       }
+      if (body.codexDesktopAuthless === true) config.codexDesktopAuthless = true;
+      else if (body.codexDesktopAuthless === false) deleteConfigTopLevelKey(config, "codexDesktopAuthless");
       pickerIsEnabled = codexAccountPickerEnabled(config);
       (deps.saveConfigPreservingClaudeCode ?? saveConfigPreservingClaudeCode)(config);
     } catch (error) {
@@ -491,13 +503,19 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
       if (previousSettings.hasShowCodexSparkQuota) {
         config.showCodexSparkQuota = previousSettings.showCodexSparkQuota;
       } else deleteConfigTopLevelKey(config, "showCodexSparkQuota");
+      if (previousSettings.hasCodexDesktopAuthless) {
+        config.codexDesktopAuthless = previousSettings.codexDesktopAuthless;
+      } else deleteConfigTopLevelKey(config, "codexDesktopAuthless");
       throw error;
     }
     if (typeof body.appOwnedMemoryBudgetMb === "number") {
       configureAppOwnedMemoryBudget(resolveAppOwnedMemoryBudgetBytes(body.appOwnedMemoryBudgetMb));
       enforceAppOwnedMemoryBudget();
     }
-    const catalogRefresh = pickerWasEnabled !== pickerIsEnabled
+    // The authless switch changes the injected config.toml shape, so converge now rather than
+    // waiting for the next start; the injector re-reads config and rewrites the form.
+    const authlessIsEnabled = config.codexDesktopAuthless === true;
+    const catalogRefresh = pickerWasEnabled !== pickerIsEnabled || authlessWasEnabled !== authlessIsEnabled
       ? await convergeCodexCatalog()
       : undefined;
     const catalogRefreshPending = catalogRefresh
@@ -513,6 +531,7 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
       oauthOpenBrowser: config.oauthOpenBrowser !== false,
       catalogRefreshPending,
       showCodexSparkQuota: config.showCodexSparkQuota === true,
+      codexDesktopAuthless: authlessIsEnabled,
       startupHealth: await readStartupHealth(config),
     });
   }

package/src/server/management/context.ts

@@ -4,7 +4,7 @@ import type { CodexLogGuardProtectionDeps } from "../../codex/log-guard/protecti
 import type { CodexLogGuardMaintenanceDeps } from "../../codex/log-guard/maintenance";
 import type { StartupHealth } from "../../codex/autostart-health";
 import type { StartupInstallAction } from "../startup-action-control";
-import type { ManagementPrincipal } from "../management-auth";
+import type { ManagementPrincipal, ManagementSessionControl } from "../management-auth";
 import type { CatalogModel } from "../../codex/catalog";
 import type { Paths as CodexPromptPaths } from "../../codex/prompt-layers";
 import type { injectGrokConfig } from "../../grok/inject";
@@ -109,6 +109,8 @@ export interface ManagementContext {
   url: URL;
   config: OcxConfig;
   deps: ManagementApiDeps;
+  /** Installed package version projected through bounded system identity routes. */
+  version: string;
   /**
    * Which credential authorized this request, resolved by the auth gate before
    * dispatch. Routes that spend the USER's identity (not just the proxy's) must
@@ -118,6 +120,8 @@ export interface ManagementContext {
    * tests, which are treated as the untrusted `admin-token` case.
    */
   principal?: ManagementPrincipal;
+  /** Narrow current-session revocation seam; contains neither the token nor session map. */
+  sessionControl?: ManagementSessionControl;
   convergeCodexCatalog: () => Promise<CatalogDisposition>;
   syncClaudeAgentDefsBestEffort: () => Promise<void>;
 }

package/src/server/management/cursor-integration-routes.ts

@@ -0,0 +1,98 @@
+/**
+ * Read-only status for the Cursor integration card.
+ *
+ * Cursor Private Inference is configured inside Cursor (Settings > Models > Gateway), not by
+ * this proxy: its settings live in a SQLite database the running app rewrites and its API key
+ * in the OS keychain, both out of bounds for opencodex. So this route only answers the three
+ * questions the dashboard needs — which Cursor builds are installed, what to paste into the
+ * gateway form, and whether a Cursor client has actually called `/v1/models` since the proxy
+ * started — plus which active models will show Cursor's Reasoning and Context controls.
+ */
+import { readRuntimePort } from "../../config/process-state";
+import { filterCatalogVisibleModels, nativeContextLimits, nativeOpenAiContextTier, uniqueCatalogModelsForRawPublicList, visibleNativeSlugs } from "../../codex/catalog";
+import { cursorLastSeen, type CursorSeen } from "../../integrations/cursor-seen";
+import { detectCursorInstalls, type CursorInstall } from "../../integrations/cursor-detect";
+import { configuredApiAuthToken, isApiAuthRequired, jsonResponse } from "../auth-cors";
+import { fetchAllModels } from "../management-api";
+import { cursorEffortFamily } from "../models-capabilities";
+import type { ManagementContext } from "./context";
+
+export const CURSOR_GATEWAY_PLACEHOLDER_KEY = "opencodex-loopback";
+export const CURSOR_GUIDE_URL = "https://lidge-jun.github.io/opencodex/guides/cursor-private-inference/";
+
+export interface CursorIntegrationStatus {
+  privateInference: { installed: boolean; path: string | null; version: string | null };
+  regularCursor: { installed: boolean; path: string | null };
+  gateway: { baseUrl: string; apiKeyMode: "credential" | "placeholder"; placeholder: string };
+  lastSeen: CursorSeen | null;
+  models: Array<{
+    id: string;
+    reasoning: string[] | null;
+    context: { defaultWindow: number; longWindow: number } | null;
+  }>;
+  guideUrl: string;
+}
+
+function pick(installs: CursorInstall[], build: CursorInstall["build"]): CursorInstall | undefined {
+  return installs.find(install => install.build === build);
+}
+
+export async function buildCursorIntegrationStatus(
+  ctx: Pick<ManagementContext, "config" | "deps"> & { url?: URL },
+  installs: CursorInstall[] = detectCursorInstalls(),
+): Promise<CursorIntegrationStatus> {
+  const { config, deps } = ctx;
+  const privateInference = pick(installs, "private-inference");
+  const regular = pick(installs, "regular");
+  const runtime = (deps.readRuntimePort ?? readRuntimePort)(process.pid);
+  // The port the browser reached is the one Cursor on the same machine will reach too; the
+  // runtime record and config.port are fallbacks for a request that carries no port.
+  const port = runtime?.port ?? (Number(ctx.url?.port) || config.port);
+  // Describes the public bind. A second unauthenticated loopback listener may exist, but the
+  // value a user pastes into Cursor must work against the bind they will actually reach.
+  const credentialConfigured = !!configuredApiAuthToken(config)
+    || (config.apiKeys ?? []).some(entry => !!entry.key.trim());
+  const apiKeyMode = isApiAuthRequired(config) || credentialConfigured ? "credential" : "placeholder";
+
+  const limits = nativeContextLimits(config);
+  // Same visibility rules as the raw /v1/models list Cursor will read: disabled models and
+  // provider allowlists drop out here too, or the prediction shows rows Cursor never gets.
+  const goModels = filterCatalogVisibleModels(await fetchAllModels(config), config);
+  const ids = [
+    ...visibleNativeSlugs(config),
+    ...uniqueCatalogModelsForRawPublicList(goModels).map(model => model.alias ?? `${model.provider}/${model.id}`),
+  ];
+  const models = ids.map(id => {
+    const tier = nativeOpenAiContextTier(id, limits);
+    return {
+      id,
+      reasoning: cursorEffortFamily(id),
+      context: tier ? { defaultWindow: tier.defaultWindow, longWindow: tier.longWindow } : null,
+    };
+  });
+
+  return {
+    privateInference: {
+      installed: privateInference !== undefined,
+      path: privateInference?.path ?? null,
+      version: privateInference?.version ?? null,
+    },
+    regularCursor: { installed: regular !== undefined, path: regular?.path ?? null },
+    gateway: {
+      baseUrl: `http://127.0.0.1:${port}/v1`,
+      apiKeyMode,
+      placeholder: CURSOR_GATEWAY_PLACEHOLDER_KEY,
+    },
+    lastSeen: cursorLastSeen(),
+    models,
+    guideUrl: CURSOR_GUIDE_URL,
+  };
+}
+
+export async function handleCursorIntegrationRoutes(ctx: ManagementContext): Promise<Response | null> {
+  const { req, url } = ctx;
+  if (url.pathname === "/api/native-integrations/cursor" && req.method === "GET") {
+    return jsonResponse(await buildCursorIntegrationStatus(ctx));
+  }
+  return null;
+}

package/src/server/management/logs-usage-routes.ts

@@ -202,10 +202,11 @@ export async function handleLogsUsageRoutes(ctx: ManagementContext): Promise<Res
     const filter = {
       provider: url.searchParams.get("provider"),
       model: url.searchParams.get("model"),
+      apiKeyId: url.searchParams.get("apiKeyId"),
     };
     const project = <T extends UsageSummary>(summary: T, entries?: PersistedUsageEntry[]) =>
       projectUsageSummary(summary, filter, entries);
-    const filterRequested = Boolean(filter.provider ?? filter.model);
+    const filterRequested = Boolean(filter.provider ?? filter.model ?? filter.apiKeyId);
     const now = Date.now();
     try {
       const cacheKey = `${range}:${surface}`;

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

@@ -72,13 +72,15 @@ function readDefaultReasoningEffort(raw: unknown, efforts: string[] | undefined)
 import type { CatalogModel } from "../../codex/catalog";
 import { accountBoundNativeOpenAiSlugsBySelector, catalogModelSlug, configuredNativeAliasSlugs, disabledNativeSlugs, invalidateCodexModelsCache, nativeModelRows, shouldIncludeAccountBoundNativeOpenAi, uniqueCatalogModelsForPublicList } from "../../codex/catalog";
 import { CatalogGatherBusyError } from "../../codex/catalog/provider-fetch";
+import { clearModelCache, getProviderLiveModelCount } from "../../codex/model-cache";
 import { NATIVE_OPENAI_MODELS } from "../../codex/catalog/native-models";
-import { getProviderLiveModelCount } from "../../codex/model-cache";
+
 import {
   DEFAULT_SUBAGENT_MODELS,
   codexAutoStartEnabled,
   hasOwnProvider,
   isValidProviderName,
+  modelDisplayNamesConfigError,
   multiAgentGuidanceEnabled,
   providerBaseUrlConfigError,
   providerHeadersConfigError,
@@ -101,6 +103,7 @@ import { providerCodexAccountMode } from "../../providers/registry";
 import { encodedModelIdCollides, routedSlug, slugEquals } from "../../providers/slug-codec";
 import { knownModelIdsForProvider } from "../../router";
 import { effectiveModelAliases, MODEL_ALIAS_PATTERN } from "../../providers/default-aliases";
+import { isValidModelDiscoveryModelId } from "../../providers/model-discovery-limits";
 import { comboPublicModelId } from "../../combos/types";
 import { COMBO_NAMESPACE, comboDisabledModelSelectors, comboModelId, preservesPhysicalComboProvider } from "../../combos";
 import { clearProviderQuotaCache, fetchProviderQuotaReports } from "../../providers/quota";
@@ -353,6 +356,81 @@ export async function handleModelRoutes(ctx: ManagementContext): Promise<Respons
     return jsonResponse(await listManagementModelRows(config));
   }
 
+  const displayNameMatch = url.pathname.match(/^\/api\/providers\/([^/]+)\/model-display-names$/);
+  if (displayNameMatch && req.method === "PUT") {
+    let name: string;
+    try { name = decodeURIComponent(displayNameMatch[1]!); } catch { return jsonResponse({ error: "invalid provider encoding" }, 400); }
+    if (name === "keys") return null;
+    if (!hasOwnProvider(config.providers, name)) {
+      return jsonResponse({ error: `provider '${name}' not found` }, 404, req, config);
+    }
+    let body: unknown;
+    try { body = await readManagementJsonBody(req); } catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid JSON body" }, 400); }
+    if (!isPlainRecord(body) || typeof body.modelId !== "string"
+      || (body.displayName !== null && typeof body.displayName !== "string")) {
+      return jsonResponse({ error: "modelId and displayName string or null are required" }, 400, req, config);
+    }
+    const modelId = body.modelId.trim();
+    const displayName = typeof body.displayName === "string" ? body.displayName.trim() : null;
+    if (!isValidModelDiscoveryModelId(modelId)) {
+      return jsonResponse({ error: "modelId must be a valid model id" }, 400, req, config);
+    }
+    const validationError = displayName === null
+      ? null
+      : modelDisplayNamesConfigError({ [modelId]: displayName });
+    if (validationError) return jsonResponse({ error: validationError }, 400, req, config);
+
+    const provider = config.providers[name]!;
+    const hadDisplayNames = Object.hasOwn(provider, "modelDisplayNames");
+    const previousDisplayNames = provider.modelDisplayNames;
+    const nextDisplayNames = Object.assign(
+      Object.create(null) as Record<string, string>,
+      previousDisplayNames ?? {},
+    );
+    if (displayName === null) delete nextDisplayNames[modelId];
+    else nextDisplayNames[modelId] = displayName;
+    const mergedValidationError = modelDisplayNamesConfigError(nextDisplayNames);
+    if (mergedValidationError) return jsonResponse({ error: mergedValidationError }, 400, req, config);
+    if (Object.keys(nextDisplayNames).length > 0) provider.modelDisplayNames = nextDisplayNames;
+    else delete provider.modelDisplayNames;
+
+    try {
+      persistConfig(config);
+    } catch (error) {
+      if (hadDisplayNames) provider.modelDisplayNames = previousDisplayNames;
+      else delete provider.modelDisplayNames;
+      throw error;
+    }
+    clearModelCache(name);
+    const catalogRefresh = await convergeCodexCatalog();
+    const storedDisplayName = provider.modelDisplayNames?.[modelId] ?? null;
+    if (catalogRefresh.status === "failed") {
+      return jsonResponse({
+        error: "model display name saved but catalog refresh failed",
+        saved: true,
+        provider: name,
+        modelId,
+        displayNameOverride: storedDisplayName,
+        catalogRefresh,
+      }, 503, req, config);
+    }
+    const row = (await listManagementModelRows(config)).find(candidate => (
+      candidate.native !== true
+      && candidate.custom !== true
+      && candidate.provider === name
+      && candidate.id === modelId
+    ));
+    return jsonResponse({
+      ok: true,
+      provider: name,
+      modelId,
+      displayName: row?.displayName ?? storedDisplayName ?? routedSlug(name, modelId),
+      displayNameOverride: storedDisplayName,
+      displayNameSource: row?.displayNameSource ?? (storedDisplayName ? "operator" : "fallback"),
+      catalogRefresh,
+    });
+  }
+
   /**
    * Client config document for OpenCode / Pi, built from the SAME function `ocx export`
    * calls, so the bytes a user downloads here and the bytes they pipe from the CLI cannot

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

@@ -41,8 +41,28 @@ export type ManagementModelRow = Partial<CatalogModel> & {
   native?: boolean;
   custom?: boolean;
   customId?: string;
+  displayNameOverride?: string;
+  displayNameSource?: "operator" | "provider" | "fallback";
 };
 
+/** Resolve the exact text and source shown for one routed discovered model. */
+export function effectiveManagementDisplayName(
+  config: Pick<OcxConfig, "providers">,
+  model: CatalogModel,
+): Pick<ManagementModelRow, "displayName" | "displayNameOverride" | "displayNameSource"> {
+  const provider = config.providers[model.provider];
+  const configured = provider?.modelDisplayNames;
+  if (configured && Object.hasOwn(configured, model.id)) {
+    const displayName = configured[model.id]?.trim();
+    if (displayName) {
+      return { displayName, displayNameOverride: displayName, displayNameSource: "operator" };
+    }
+  }
+  const providerDisplayName = model.displayName?.trim();
+  if (providerDisplayName) return { displayName: providerDisplayName, displayNameSource: "provider" };
+  return { displayName: catalogModelSlug(model), displayNameSource: "fallback" };
+}
+
 /**
  * The exact row list `/api/models` returns. Extracted so `/api/client-config` exports the
  * models the GUI's Models tab shows — including this function's `disabled` computation,
@@ -133,8 +153,10 @@ export async function listManagementModelRows(
     if (m.provider !== "combo" && customNamespaced.has(namespaced)) return null;
     const contextCap = providerContextCap(config, m.provider);
     const nativeAlias = m.provider === "combo" && m.nativeAlias === true;
+    const displayName = effectiveManagementDisplayName(config, m);
     return {
       ...m,
+      ...displayName,
       namespaced,
       disabled: [...disabled].some(stored => (
         (!nativeAlias && stored === namespaced) || slugEquals(stored, m.provider, m.id)
@@ -152,7 +174,7 @@ export function toExportModel(row: ManagementModelRow): ExportModel {
     provider: row.provider,
     id: row.id,
     ...(row.native ? { native: true } : {}),
-    ...(row.displayName ? { displayName: row.displayName } : {}),
+    ...(row.displayName && row.displayNameSource !== "fallback" ? { displayName: row.displayName } : {}),
     ...(row.contextWindow !== undefined ? { contextWindow: row.contextWindow } : {}),
     ...(row.inputModalities ? { inputModalities: row.inputModalities } : {}),
     ...(row.reasoningEfforts ? { reasoningEfforts: row.reasoningEfforts } : {}),