@iislee/opencodex 2.31.0 → 2.35.0

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

@@ -5,6 +5,7 @@ import { catalogModelSlug, invalidateCodexModelsCache, nativeContextLimits, nati
 import {
   DEFAULT_SUBAGENT_MODELS,
   codexAutoStartEnabled,
+  deleteConfigTopLevelKey,
   hasOwnProvider,
   isValidProviderName,
   multiAgentGuidanceEnabled,
@@ -298,6 +299,12 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
       streamMode: config.streamMode ?? "auto",
       appOwnedMemoryBudgetMb: config.appOwnedMemoryBudgetMb ?? 256,
       codexAccountPickerEnabled: codexAccountPickerEnabled(config),
+      // Absent means hidden, so the GUI renders the switch without having to know that
+      // `undefined` and `false` mean the same thing.
+      showCodexSparkQuota: config.showCodexSparkQuota === true,
+      // Absent means the historical auto-open, so the GUI can render the toggle
+      // without having to know that `undefined` and `true` mean the same thing.
+      oauthOpenBrowser: config.oauthOpenBrowser !== false,
       startupHealth: await readStartupHealth(config),
       codexRuntime: {
         path: displayCodexRuntimePath(resolved.runtime.command),
@@ -382,16 +389,23 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
       streamMode?: unknown;
       appOwnedMemoryBudgetMb?: unknown;
       codexAccountPickerEnabled?: unknown;
+      oauthOpenBrowser?: unknown;
+      showCodexSparkQuota?: unknown;
     };
     if (body.codexAutoStart === undefined
       && body.streamMode === undefined
       && body.appOwnedMemoryBudgetMb === undefined
-      && body.codexAccountPickerEnabled === undefined) {
-      return jsonResponse({ error: "provide codexAutoStart, streamMode, appOwnedMemoryBudgetMb, or codexAccountPickerEnabled" }, 400);
+      && body.codexAccountPickerEnabled === undefined
+      && body.oauthOpenBrowser === undefined
+      && body.showCodexSparkQuota === undefined) {
+      return jsonResponse({ error: "provide codexAutoStart, streamMode, appOwnedMemoryBudgetMb, codexAccountPickerEnabled, oauthOpenBrowser, or showCodexSparkQuota" }, 400);
     }
     if (body.codexAutoStart !== undefined && typeof body.codexAutoStart !== "boolean") {
       return jsonResponse({ error: "codexAutoStart boolean is required" }, 400);
     }
+    if (body.oauthOpenBrowser !== undefined && typeof body.oauthOpenBrowser !== "boolean") {
+      return jsonResponse({ error: "oauthOpenBrowser boolean is required" }, 400);
+    }
     if (body.streamMode !== undefined && !isStreamMode(body.streamMode)) {
       return jsonResponse({ error: "streamMode must be auto, legacy-tee, or eager-relay" }, 400);
     }
@@ -399,6 +413,9 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
       && typeof body.codexAccountPickerEnabled !== "boolean") {
       return jsonResponse({ error: "codexAccountPickerEnabled boolean is required" }, 400);
     }
+    if (body.showCodexSparkQuota !== undefined && typeof body.showCodexSparkQuota !== "boolean") {
+      return jsonResponse({ error: "showCodexSparkQuota boolean is required" }, 400);
+    }
     if (body.appOwnedMemoryBudgetMb !== undefined && (
       typeof body.appOwnedMemoryBudgetMb !== "number"
       || !Number.isInteger(body.appOwnedMemoryBudgetMb)
@@ -418,6 +435,10 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
       hasCodexAccountNamespaces: Object.hasOwn(config, "codexAccountNamespaces"),
       codexAccountPickerEnabled: config.codexAccountPickerEnabled,
       hasCodexAccountPickerEnabled: Object.hasOwn(config, "codexAccountPickerEnabled"),
+      oauthOpenBrowser: config.oauthOpenBrowser,
+      hasOauthOpenBrowser: Object.hasOwn(config, "oauthOpenBrowser"),
+      showCodexSparkQuota: config.showCodexSparkQuota,
+      hasShowCodexSparkQuota: Object.hasOwn(config, "showCodexSparkQuota"),
     };
     const pickerWasEnabled = codexAccountPickerEnabled(config);
     let pickerIsEnabled = pickerWasEnabled;
@@ -427,7 +448,7 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
       }
       if (body.streamMode !== undefined) {
         if (body.streamMode === "auto") {
-          delete config.streamMode;
+          deleteConfigTopLevelKey(config, "streamMode");
         } else {
           config.streamMode = body.streamMode as "legacy-tee" | "eager-relay";
         }
@@ -441,22 +462,34 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
       } else if (body.codexAccountPickerEnabled === false) {
         config.codexAccountPickerEnabled = false;
       }
+      if (typeof body.oauthOpenBrowser === "boolean") {
+        config.oauthOpenBrowser = body.oauthOpenBrowser;
+      }
+      if (typeof body.showCodexSparkQuota === "boolean") {
+        config.showCodexSparkQuota = body.showCodexSparkQuota;
+      }
       pickerIsEnabled = codexAccountPickerEnabled(config);
       (deps.saveConfigPreservingClaudeCode ?? saveConfigPreservingClaudeCode)(config);
     } catch (error) {
       if (previousSettings.hasCodexAutoStart) config.codexAutoStart = previousSettings.codexAutoStart;
-      else delete config.codexAutoStart;
+      else deleteConfigTopLevelKey(config, "codexAutoStart");
       if (previousSettings.hasStreamMode) config.streamMode = previousSettings.streamMode;
-      else delete config.streamMode;
+      else deleteConfigTopLevelKey(config, "streamMode");
       if (previousSettings.hasAppOwnedMemoryBudgetMb) {
         config.appOwnedMemoryBudgetMb = previousSettings.appOwnedMemoryBudgetMb;
-      } else delete config.appOwnedMemoryBudgetMb;
+      } else deleteConfigTopLevelKey(config, "appOwnedMemoryBudgetMb");
       if (previousSettings.hasCodexAccountNamespaces) {
         config.codexAccountNamespaces = previousSettings.codexAccountNamespaces;
-      } else delete config.codexAccountNamespaces;
+      } else deleteConfigTopLevelKey(config, "codexAccountNamespaces");
       if (previousSettings.hasCodexAccountPickerEnabled) {
         config.codexAccountPickerEnabled = previousSettings.codexAccountPickerEnabled;
-      } else delete config.codexAccountPickerEnabled;
+      } else deleteConfigTopLevelKey(config, "codexAccountPickerEnabled");
+      if (previousSettings.hasOauthOpenBrowser) {
+        config.oauthOpenBrowser = previousSettings.oauthOpenBrowser;
+      } else deleteConfigTopLevelKey(config, "oauthOpenBrowser");
+      if (previousSettings.hasShowCodexSparkQuota) {
+        config.showCodexSparkQuota = previousSettings.showCodexSparkQuota;
+      } else deleteConfigTopLevelKey(config, "showCodexSparkQuota");
       throw error;
     }
     if (typeof body.appOwnedMemoryBudgetMb === "number") {
@@ -476,7 +509,9 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
       streamMode: config.streamMode ?? "auto",
       appOwnedMemoryBudgetMb: config.appOwnedMemoryBudgetMb ?? 256,
       codexAccountPickerEnabled: pickerIsEnabled,
+      oauthOpenBrowser: config.oauthOpenBrowser !== false,
       catalogRefreshPending,
+      showCodexSparkQuota: config.showCodexSparkQuota === true,
       startupHealth: await readStartupHealth(config),
     });
   }
@@ -490,7 +525,10 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
   if (url.pathname === "/api/sync" && req.method === "POST") {
     const { syncModelsToCodex } = await import("../../codex/sync");
     const { attachStaleAppServerHint } = await import("../../codex/app-server-processes");
-    const { readRuntimePort, loadConfig } = await import("../../config");
+    const [{ readRuntimePort }, { loadConfig }] = await Promise.all([
+      import("../../config/process-state"),
+      import("../../config"),
+    ]);
     // Never use the server-captured startup object for a durable integration
     // decision. A toggle may have persisted while this process was gathering.
     const runtime = readRuntimePort(process.pid);
@@ -662,9 +700,18 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
 
     if (body.webSearch) {
       const pairTouched = body.webSearch.model !== undefined || body.webSearch.backend !== undefined;
-      const effectiveBackend = body.webSearch.backend === "anthropic"
-        ? "anthropic"
-        : body.webSearch.backend === "openai" || body.webSearch.backend === null
+      // Validate against the backend the caller SUBMITTED, across the whole
+      // union — not just openai/anthropic (#2457). The union check above has
+      // already refused unknown literals, so a surviving string is a member;
+      // Array.includes does not narrow, hence the cast. Falling back to the
+      // stored backend for xai/gemini/exa both rejected legal pairs and
+      // accepted illegal ones: a submitted gemini was checked against a stored
+      // openai. null means "unset the backend", and unset resolves to openai.
+      const submittedBackend = body.webSearch.backend;
+      const effectiveBackend = typeof submittedBackend === "string"
+        && WEB_SEARCH_BACKENDS_UNION.includes(submittedBackend as never)
+        ? submittedBackend as typeof WEB_SEARCH_BACKENDS_UNION[number]
+        : submittedBackend === null
           ? "openai"
           : config.webSearchSidecar?.backend ?? "openai";
       const effectiveModel = typeof body.webSearch.model === "string"

package/src/server/management/context.ts

@@ -6,9 +6,10 @@ import type { StartupHealth } from "../../codex/autostart-health";
 import type { StartupInstallAction } from "../startup-action-control";
 import type { ManagementPrincipal } from "../management-auth";
 import type { CatalogModel } from "../../codex/catalog";
+import type { Paths as CodexPromptPaths } from "../../codex/prompt-layers";
 import type { injectGrokConfig } from "../../grok/inject";
 import type { removeDesktop3pStandardPivot, writeDesktop3pConfig } from "../../claude/desktop-3p";
-import type { RuntimePortState } from "../../config";
+import type { RuntimePortState } from "../../config/process-state";
 import type { CatalogDisposition, ConvergeCodex } from "../../codex/convergence-types";
 import type {
   performCodexRestart,
@@ -87,6 +88,14 @@ export interface ManagementApiDeps {
    * state inside their temporary Codex home.
    */
   codexLogGuardMaintenanceDeps?: CodexLogGuardMaintenanceDeps;
+  /**
+   * Prompt-layer path seam. Production leaves this unset and
+   * `src/codex/prompt-layers.ts` resolves the real CODEX_HOME. A route test
+   * that could not inject paths would read AND WRITE the developer's live
+   * ~/.codex/config.toml — the same class of incident
+   * `saveConfigPreservingClaudeCode` above exists to prevent.
+   */
+  codexPromptPaths?: CodexPromptPaths;
 }
 
 

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

@@ -32,8 +32,6 @@ import { isCanonicalOpenAiForwardProvider } from "../../providers/openai-tiers";
 import { clearThreadAccountMap } from "../../codex/routing";
 import { primeCodexPoolQuotas } from "../../codex/auth-api";
 import { DEFAULT_PROVIDER_CONTEXT_CAP, globalContextCapValue, providerContextCap, providerContextCaps, setAllProviderContextCaps, setGlobalContextCapValue, setProviderContextCap } from "../../providers/context-cap";
-import { resolveCodexHomeDir } from "../../codex/home";
-import { scanStorage } from "../../storage/scanner";
 import { executeArchivedCleanup, listTrashEntries, pickWireCleanupTestHooks, previewArchivedCleanup, type CleanupMode, type RestoreErrorCode } from "../../storage/cleanup";
 import { runArchivedCleanupJob } from "../../storage/cleanup-job";
 import { getRestoreTrashTestStreamResponse, runRestoreTrashEntryJob } from "../../storage/restore-job";
@@ -55,7 +53,7 @@ import {
   type PersistedUsageEntry,
 } from "../../usage/log";
 import { getUsageDebugLogEntries } from "../../usage/debug";
-import { parseRange, parseUsageSurface, rangeWindow, summarizeUsage, type UsageRange, type UsageSummary, type UsageSurface } from "../../usage/summary";
+import { USAGE_RANGES, USAGE_SURFACES, parseRange, parseUsageSurface, projectUsageSummary, rangeWindow, summarizeUsage, type UsageRange, type UsageSummary, type UsageSurface } from "../../usage/summary";
 import { stripCodexRuntimeProviderFields } from "../../codex/auth-context";
 import { getProviderRegistryEntry } from "../../providers/registry";
 import { getDebugLogEntries } from "../../lib/debug-log-buffer";
@@ -316,6 +314,17 @@ export async function handleLogsUsageRoutes(ctx: ManagementContext): Promise<Res
   if (url.pathname === "/api/usage" && req.method === "GET") {
     const range = parseRange(url.searchParams.get("range"));
     const surface = parseUsageSurface(url.searchParams.get("surface"));
+    // Applied to the OUTGOING payload only. A filtered summary must never reach
+    // the cache or the warm loop below: the key is `range:surface`, so a
+    // filtered entry stored under it would be served to the next unfiltered
+    // caller, dashboard included.
+    const filter = {
+      provider: url.searchParams.get("provider"),
+      model: url.searchParams.get("model"),
+    };
+    const project = <T extends UsageSummary>(summary: T, entries?: PersistedUsageEntry[]) =>
+      projectUsageSummary(summary, filter, entries);
+    const filterRequested = Boolean(filter.provider ?? filter.model);
     const now = Date.now();
     try {
       const cacheKey = `${range}:${surface}`;
@@ -325,6 +334,12 @@ export async function handleLogsUsageRoutes(ctx: ManagementContext): Promise<Res
       const observedSize = observed?.size ?? 0;
       const cached = getUsageSummaryCacheEntry(cacheKey);
       if (cached
+        // A filtered response is re-summarised from entries, which a cached
+        // summary does not carry. Serving it from cache would mean projecting
+        // over collapsed breakdown rows again — the exact defect the
+        // re-summarisation replaced. The unfiltered cache stays warm either
+        // way; only the filtered caller pays for the read.
+        && !filterRequested
         && cached.identityKey === identityKey
         && cached.maxReadBytes === effectiveReadLimit
         && cached.overlayVersion === userCostOverlayVersion()
@@ -333,7 +348,7 @@ export async function handleLogsUsageRoutes(ctx: ManagementContext): Promise<Res
         && observedSize >= cached.lastSeenSize) {
         return jsonResponse(refreshedUsageSummary(cached.summary, range, now));
       }
-      if (cached) discardUsageSummaryCacheEntry(cacheKey);
+      if (cached && !filterRequested) discardUsageSummaryCacheEntry(cacheKey);
       // Capture the overlay version BEFORE reading/computing: the cache entry
       // must be stamped with the version the summary was priced under. Reading
       // it again at stamp time could cache an old-price summary as current,
@@ -357,14 +372,18 @@ export async function handleLogsUsageRoutes(ctx: ManagementContext): Promise<Res
         // summary may mix old and new prices. Serve it uncached: the next
         // request recomputes against the settled overlay instead of caching a
         // mixed-price entry under either version.
-        return jsonResponse(summary);
+        return jsonResponse(project(summary, snapshot.entries));
       }
       const freshUntil = now + 60_000;
       const snapshotIdentity = `${usageLogIdentityKey(snapshot.revision)}\0${effectiveReadLimit}`;
       const revisionKey = `${usageLogRevisionKey(snapshot.revision)}\0${effectiveReadLimit}`;
       const lastSeenSize = snapshot.revision?.size ?? 0;
-      const ranges: UsageRange[] = ["7d", "30d", "all"];
-      const surfaces: UsageSurface[] = ["all", "codex", "claude", "grok"];
+      // Derived from the canonical constants rather than re-listed: a subset
+      // literal type-checks perfectly happily, so a range added to the union
+      // and forgotten here would never be warmed and never invalidated
+      // alongside its siblings.
+      const ranges: readonly UsageRange[] = USAGE_RANGES;
+      const surfaces: readonly UsageSurface[] = USAGE_SURFACES;
       for (const nextRange of ranges) {
         for (const nextSurface of surfaces) {
           const nextSummary = nextRange === range && nextSurface === surface ? summary : {
@@ -398,7 +417,7 @@ export async function handleLogsUsageRoutes(ctx: ManagementContext): Promise<Res
         effectiveReadLimit,
         now,
       );
-      return jsonResponse(summary);
+      return jsonResponse(project(summary, snapshot.entries));
     } catch {
       return jsonResponse({
         range,
@@ -450,8 +469,9 @@ export async function handleLogsUsageRoutes(ctx: ManagementContext): Promise<Res
   if (url.pathname === "/api/usage/ingest" && req.method === "POST") {
     let body: unknown;
     try {
-      body = await req.json();
-    } catch {
+      body = await readManagementJsonBody(req);
+    } catch (error) {
+      rethrowManagementBodyTooLarge(error);
       return jsonResponse({ error: "invalid JSON body" }, 400);
     }
     const rawEntries = extractIngestRawEntries(body);
@@ -512,20 +532,6 @@ export async function handleLogsUsageRoutes(ctx: ManagementContext): Promise<Res
     }, status);
   }
 
-  if (url.pathname === "/api/storage" && req.method === "GET") {
-    try {
-      return jsonResponse(scanStorage());
-    } catch {
-      return jsonResponse({
-        codexHome: resolveCodexHomeDir(),
-        generatedAt: Date.now(),
-        total: { bytes: 0, fileCount: 0 },
-        buckets: [],
-        error: "scan_failed",
-      });
-    }
-  }
-
   if (url.pathname === "/api/storage/cleanup/preview" && req.method === "POST") {
     let body: { percent?: unknown };
     try { body = await readManagementJsonBody(req); } catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid_json" }, 400); }

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

@@ -99,6 +99,8 @@ import { deriveProviderPresets } from "../../providers/derive";
 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 { comboPublicModelId } from "../../combos/types";
 import { COMBO_NAMESPACE, comboDisabledModelSelectors, comboModelId, preservesPhysicalComboProvider } from "../../combos";
 import { clearProviderQuotaCache, fetchProviderQuotaReports } from "../../providers/quota";
 import { isCanonicalOpenAiForwardProvider } from "../../providers/openai-tiers";
@@ -149,6 +151,12 @@ import type { MetricUnavailableReason, TokPerSecondResult, CostEstimateReason, C
 import type { ManagementContext } from "./context";
 import { listManagementModelRows, loadExportModels } from "./model-rows";
 import { readManagementJsonBody, rethrowManagementBodyTooLarge } from "./body";
+import {
+  hasModelPreset,
+  markModelPresetDiverged,
+  materializeModelPreset,
+  modelPresetFor,
+} from "../../providers/model-presets";
 
 /**
  * Counts read back off the SERIALIZED document rather than recomputed from the input rows.
@@ -171,6 +179,158 @@ export async function handleModelRoutes(ctx: ManagementContext): Promise<Respons
   // ~/.opencodex/config.json with the `existing-uuid` test fixture.
   const persistConfig = deps.saveConfigPreservingClaudeCode ?? saveConfigPreservingClaudeCode;
 
+  if (url.pathname === "/api/model-discovery" && req.method === "GET") {
+    const providers = Object.fromEntries(Object.entries(config.providers).map(([name, provider]) => [
+      name, provider.newModelPolicy ?? "inherit",
+    ]));
+    const recentArrivals = Object.fromEntries(Object.entries(config.modelDiscovery?.recentArrivals ?? {}).map(([name, rows]) => [
+      name,
+      rows.map(row => ({
+        ...row,
+        state: (config.disabledModels ?? []).some(slug => slugEquals(slug, name, row.id))
+          ? "auto-disabled" : "enabled",
+      })),
+    ]));
+    const baselineCounts = Object.fromEntries(Object.entries(config.modelDiscovery?.knownModels ?? {}).map(([name, baseline]) => [
+      name, baseline.ids.length,
+    ]));
+    return jsonResponse({
+      policy: config.modelDiscovery?.newModelPolicy ?? "on", providers, recentArrivals, baselineCounts,
+    });
+  }
+
+  if (url.pathname === "/api/model-discovery" && req.method === "PUT") {
+    let body: { policy?: unknown; provider?: unknown };
+    try { body = await readManagementJsonBody(req); } catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid JSON body" }, 400); }
+    if (body.policy !== "on" && body.policy !== "off") return jsonResponse({ error: "policy must be on or off" }, 400);
+    const provider = typeof body.provider === "string" && body.provider.trim() ? body.provider.trim() : null;
+    let baselineBootstrapped = false;
+    if (provider) {
+      if (!hasOwnProvider(config.providers, provider)) return jsonResponse({ error: "unknown provider" }, 404);
+      config.providers[provider].newModelPolicy = body.policy;
+    } else {
+      const wasAbsent = config.modelDiscovery?.newModelPolicy === undefined;
+      config.modelDiscovery ??= {};
+      config.modelDiscovery.newModelPolicy = body.policy;
+      if (body.policy === "off" && wasAbsent) {
+        const models = await fetchAllModels(config);
+        const known = config.modelDiscovery.knownModels ??= {};
+        const at = new Date().toISOString();
+        for (const name of Object.keys(config.providers)) {
+          known[name] ??= { ids: [...new Set(models.filter(m => m.provider === name).map(m => m.id))].sort(), removed: [], updatedAt: at };
+        }
+        baselineBootstrapped = true;
+      }
+    }
+    persistConfig(config);
+    const catalogRefresh = await convergeCodexCatalog();
+    return jsonResponse({ ok: true, policy: body.policy, provider, ...(baselineBootstrapped ? { baselineBootstrapped } : {}), catalogRefresh });
+  }
+
+  if (url.pathname === "/api/model-discovery/acknowledge" && req.method === "POST") {
+    let body: { provider?: unknown; ids?: unknown };
+    try { body = await readManagementJsonBody(req); } catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid JSON body" }, 400); }
+    const provider = typeof body.provider === "string" ? body.provider.trim() : "";
+    if (!provider || !Array.isArray(body.ids) || body.ids.some(id => typeof id !== "string")) {
+      return jsonResponse({ error: "provider and string ids are required" }, 400);
+    }
+    const acknowledged = new Set(body.ids as string[]);
+    const recent = config.modelDiscovery?.recentArrivals;
+    if (recent?.[provider]) recent[provider] = recent[provider].filter(row => !acknowledged.has(row.id));
+    persistConfig(config);
+    const catalogRefresh = await convergeCodexCatalog();
+    return jsonResponse({ ok: true, provider, acknowledged: [...acknowledged], catalogRefresh });
+  }
+
+  if (url.pathname === "/api/aliases" && req.method === "GET") {
+    const providers: Record<string, string> = {};
+    const models: Record<string, Record<string, { alias: string; source: "user" | "builtin"; stale?: boolean }>> = {};
+    for (const [name, provider] of Object.entries(config.providers)) {
+      if (provider.alias) providers[name] = provider.alias;
+      const known = knownModelIdsForProvider(name, provider, config);
+      const knownSet = new Set(known);
+      const rows: Record<string, { alias: string; source: "user" | "builtin"; stale?: boolean }> = {};
+      for (const [id, value] of effectiveModelAliases(config, provider, new Set([...known, ...Object.keys(provider.modelAliases ?? {})]))) {
+        rows[id] = { ...value, ...(!knownSet.has(id) ? { stale: true } : {}) };
+      }
+      if (Object.keys(rows).length) models[name] = rows;
+    }
+    return jsonResponse({ providers, models, defaults: {
+      global: config.defaultModelAliases ?? false,
+      providers: Object.fromEntries(Object.entries(config.providers).filter(([, p]) => p.defaultAliases !== undefined).map(([n, p]) => [n, p.defaultAliases])),
+    } });
+  }
+
+  const providerAliasMatch = url.pathname.match(/^\/api\/providers\/([^/]+)\/alias$/);
+  if (providerAliasMatch && req.method === "PUT") {
+    const name = decodeURIComponent(providerAliasMatch[1]!);
+    // `keys` is not a provider name: `/api/providers/keys/alias` is the API-KEY POOL's rename
+    // endpoint (oauth-account-routes.ts), and model routes are dispatched BEFORE it. Without
+    // this guard the alias route matched `name = "keys"`, found no such provider, and returned
+    // 404 for every key-pool rename.
+    if (name === "keys") return null;
+    const provider = config.providers[name];
+    if (!provider) return jsonResponse({ error: `provider '${name}' not found` }, 404, req, config);
+    let raw: unknown;
+    try { raw = await readManagementJsonBody(req); } catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid JSON body" }, 400); }
+    if (!isPlainRecord(raw) || (raw.alias !== null && typeof raw.alias !== "string")) return jsonResponse({ error: "alias must be a string or null" }, 400, req, config);
+    const alias = typeof raw.alias === "string" ? raw.alias.trim() : null;
+    if (alias && !isValidProviderName(alias)) return jsonResponse({ error: "invalid provider alias" }, 400, req, config);
+    const lower = alias?.toLowerCase();
+    const collision = lower && Object.entries(config.providers).find(([other, p]) =>
+      other !== name && (other.toLowerCase() === lower || p.alias?.toLowerCase() === lower));
+    const comboCollision = lower && Object.entries(config.combos ?? {}).find(([, combo]) => comboPublicModelId("", combo).toLowerCase() === lower);
+    const accountCollision = lower && Object.keys(config.codexAccountNamespaces ?? {}).find(value => value.toLowerCase() === lower);
+    if (collision || comboCollision || accountCollision) return jsonResponse({ error: `alias conflicts with '${collision?.[0] ?? comboCollision?.[0] ?? accountCollision}'` }, 409, req, config);
+    if (alias) provider.alias = alias; else delete provider.alias;
+    persistConfig(config);
+    const catalogRefresh = await convergeCodexCatalog();
+    return jsonResponse({ ok: true, provider: name, alias, catalogRefresh });
+  }
+
+  const modelAliasMatch = url.pathname.match(/^\/api\/providers\/([^/]+)\/model-aliases$/);
+  if (modelAliasMatch && req.method === "PUT") {
+    const name = decodeURIComponent(modelAliasMatch[1]!);
+    if (name === "keys") return null;
+    const provider = config.providers[name];
+    if (!provider) return jsonResponse({ error: `provider '${name}' not found` }, 404, req, config);
+    let raw: unknown;
+    try { raw = await readManagementJsonBody(req); } catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid JSON body" }, 400); }
+    if (!isPlainRecord(raw) || (raw.set !== undefined && !isPlainRecord(raw.set)) || (raw.remove !== undefined && !Array.isArray(raw.remove))) return jsonResponse({ error: "invalid model alias update" }, 400, req, config);
+    const next = { ...(provider.modelAliases ?? {}) };
+    for (const id of (raw.remove ?? []) as unknown[]) if (typeof id === "string") delete next[id];
+    const conflicts: Array<{ alias: string; heldBy: string }> = [];
+    const known = knownModelIdsForProvider(name, provider, config);
+    for (const [id, value] of Object.entries((raw.set ?? {}) as Record<string, unknown>)) {
+      if (typeof value !== "string" || !MODEL_ALIAS_PATTERN.test(value)) return jsonResponse({ error: `invalid model alias for '${id}'` }, 400, req, config);
+      const lower = value.toLowerCase();
+      const heldBy = Object.entries(next).find(([other, alias]) => other !== id && alias.toLowerCase() === lower)?.[0]
+        ?? known.find(native => native.toLowerCase() === lower)
+        ?? Object.entries(config.combos ?? {}).find(([, combo]) => comboPublicModelId("", combo).toLowerCase() === lower)?.[0];
+      if (heldBy || /^(?:gpt-|o1-|o3-|o4-|codex-)/i.test(value)) conflicts.push({ alias: value, heldBy: heldBy ?? "native OpenAI family" });
+      else next[id] = value;
+    }
+    if (conflicts.length) return jsonResponse({ error: "model alias collision", conflicts }, 409, req, config);
+    provider.modelAliases = next;
+    persistConfig(config);
+    const catalogRefresh = await convergeCodexCatalog();
+    return jsonResponse({ ok: true, aliases: next, catalogRefresh });
+  }
+
+  if (url.pathname === "/api/default-aliases" && req.method === "PUT") {
+    let raw: unknown;
+    try { raw = await readManagementJsonBody(req); } catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid JSON body" }, 400); }
+    if (!isPlainRecord(raw) || typeof raw.enabled !== "boolean" || (raw.provider !== undefined && typeof raw.provider !== "string")) return jsonResponse({ error: "enabled must be boolean" }, 400, req, config);
+    if (typeof raw.provider === "string") {
+      const provider = config.providers[raw.provider];
+      if (!provider) return jsonResponse({ error: `provider '${raw.provider}' not found` }, 404, req, config);
+      provider.defaultAliases = raw.enabled;
+    } else config.defaultModelAliases = raw.enabled;
+    persistConfig(config);
+    const catalogRefresh = await convergeCodexCatalog();
+    return jsonResponse({ ok: true, catalogRefresh });
+  }
+
   if (url.pathname === "/api/catalog" && req.method === "GET") {
     const { readCatalog, readCodexCatalogPath } = await import("../../codex/catalog");
     const catalog = readCatalog(readCodexCatalogPath());
@@ -370,6 +530,10 @@ export async function handleModelRoutes(ctx: ManagementContext): Promise<Respons
           providerConfig.selectedModels = [...new Set([...providerConfig.selectedModels, ...additions])];
         }
         disabled = disabled.filter(stored => !targets.some(target => matchesTarget(stored, target)));
+        const arrivals = config.modelDiscovery?.recentArrivals?.[provider];
+        if (arrivals) config.modelDiscovery!.recentArrivals![provider] = arrivals.filter(row => (
+          !targets.some(target => !target.native && target.id === row.id)
+        ));
       }
     } else {
       for (const target of targets) {
@@ -394,8 +558,10 @@ export async function handleModelRoutes(ctx: ManagementContext): Promise<Respons
   }
 
   if (url.pathname === "/api/custom-models" && req.method === "POST") {
-    let body: { provider?: unknown; modelId?: unknown; displayName?: unknown; contextWindow?: unknown; inputModalities?: unknown; reasoningEfforts?: unknown; defaultReasoningEffort?: unknown };
-    try { body = await readManagementJsonBody(req); } catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid JSON body" }, 400); }
+    let parsedBody: unknown;
+    try { parsedBody = await readManagementJsonBody(req); } catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid JSON body" }, 400); }
+    if (!isPlainRecord(parsedBody)) return jsonResponse({ error: "invalid JSON body" }, 400);
+    const body = parsedBody;
     const provider = typeof body.provider === "string" ? body.provider.trim() : "";
     const modelId = typeof body.modelId === "string" ? body.modelId.trim() : "";
     if (!provider || !modelId) return jsonResponse({ error: "provider and modelId are required" }, 400);
@@ -441,8 +607,10 @@ export async function handleModelRoutes(ctx: ManagementContext): Promise<Respons
   if (customPutMatch && req.method === "PUT") {
     let id: string;
     try { id = decodeURIComponent(customPutMatch[1]); } catch { return jsonResponse({ error: "invalid id encoding" }, 400); }
-    let body: { displayName?: unknown; contextWindow?: unknown; inputModalities?: unknown; modelId?: unknown; reasoningEfforts?: unknown; defaultReasoningEffort?: unknown };
-    try { body = await readManagementJsonBody(req); } catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid JSON body" }, 400); }
+    let parsedBody: unknown;
+    try { parsedBody = await readManagementJsonBody(req); } catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid JSON body" }, 400); }
+    if (!isPlainRecord(parsedBody)) return jsonResponse({ error: "invalid JSON body" }, 400);
+    const body = parsedBody;
     const list = config.customModels ?? [];
     const idx = list.findIndex(cm => cm.id === id);
     if (idx === -1) return jsonResponse({ error: "not found" }, 404);
@@ -562,6 +730,104 @@ export async function handleModelRoutes(ctx: ManagementContext): Promise<Respons
     const refreshing = catalogGatherNeedsLiveRefresh(config);
     return jsonResponse({ selected, available, liveModelCounts, refreshing });
   }
+  if (url.pathname === "/api/model-presets" && req.method === "GET") {
+    // Preview without applying: rules evaluated against the CURRENT catalog, so the count the
+    // user sees is the count they would get.
+    const models = await fetchAllModels(config);
+    const byProvider = new Map<string, string[]>();
+    for (const m of models) {
+      const ids = byProvider.get(m.provider) ?? [];
+      ids.push(m.id);
+      byProvider.set(m.provider, ids);
+    }
+    const providers: Record<string, unknown> = {};
+    for (const [name, prov] of Object.entries(config.providers)) {
+      const preset = modelPresetFor(name);
+      if (!preset) continue;
+      const catalogIds = byProvider.get(name) ?? [];
+      const presetIds = materializeModelPreset(name, catalogIds);
+      providers[name] = {
+        mode: prov.modelPreset?.mode ?? "all",
+        ...(prov.modelPreset?.appliedVersion !== undefined
+          ? { appliedVersion: prov.modelPreset.appliedVersion }
+          : {}),
+        availableVersion: preset.version,
+        presetIds,
+        presetCount: presetIds.length,
+        totalCount: catalogIds.length,
+        ...(prov.modelPreset?.fallback ? { fallback: prov.modelPreset.fallback } : {}),
+      };
+    }
+    return jsonResponse({ providers });
+  }
+  if (url.pathname === "/api/model-presets" && req.method === "PUT") {
+    let body: { provider?: unknown; mode?: unknown };
+    try { body = await readManagementJsonBody(req); } catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid JSON body" }, 400); }
+    const provider = typeof body.provider === "string" ? body.provider : "";
+    if (!provider || !hasOwnProvider(config.providers, provider)) {
+      return jsonResponse({ error: "unknown provider" }, provider ? 404 : 400);
+    }
+    const mode = body.mode;
+    if (mode !== "preset" && mode !== "all" && mode !== "custom") {
+      return jsonResponse({ error: "mode must be preset, all, or custom" }, 400);
+    }
+    const target = config.providers[provider];
+    if (mode === "all") {
+      // Same effect as today's empty-list PUT: no allowlist, no marker to reconcile.
+      delete target.selectedModels;
+      delete target.modelPreset;
+      persistConfig(config);
+      return jsonResponse({ ok: true, provider, mode, selected: [], catalogRefresh: await convergeCodexCatalog() });
+    }
+    if (mode === "custom") {
+      // Keep whatever is selected; only the marker changes, so a user can pin their edits
+      // without the proxy re-materializing over them.
+      target.modelPreset = { ...(target.modelPreset ?? {}), mode: "custom" };
+      persistConfig(config);
+      return jsonResponse({ ok: true, provider, mode, selected: [...(target.selectedModels ?? [])] });
+    }
+    if (!hasModelPreset(provider)) {
+      return jsonResponse({ error: `no model preset is shipped for provider '${provider}'` }, 400);
+    }
+    const models = await fetchAllModels(config);
+    const catalogIds = models.filter(m => m.provider === provider).map(m => m.id);
+    const presetIds = materializeModelPreset(provider, catalogIds);
+    const preset = modelPresetFor(provider)!;
+    if (presetIds.length === 0) {
+      // NEVER write an empty allowlist from a preset: empty means ALL, so it would silently
+      // un-curate instead of curating. Keep the previous selection and record the fallback so
+      // the next convergence can retry.
+      target.modelPreset = {
+        mode: "all",
+        appliedVersion: preset.version,
+        appliedAt: new Date().toISOString(),
+        fallback: "preset-empty",
+      };
+      persistConfig(config);
+      return jsonResponse({
+        ok: true,
+        provider,
+        mode: "all",
+        fallback: "preset-empty",
+        selected: [...(target.selectedModels ?? [])],
+      });
+    }
+    target.selectedModels = presetIds;
+    target.modelPreset = {
+      mode: "preset",
+      appliedVersion: preset.version,
+      appliedAt: new Date().toISOString(),
+    };
+    persistConfig(config);
+    return jsonResponse({
+      ok: true,
+      provider,
+      mode: "preset",
+      appliedVersion: preset.version,
+      selected: presetIds,
+      catalogRefresh: await convergeCodexCatalog(),
+    });
+  }
   if (url.pathname === "/api/selected-models" && req.method === "PUT") {
     let body: { provider?: unknown; models?: unknown };
     try { body = await readManagementJsonBody(req); } catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid JSON body" }, 400); }
@@ -575,6 +841,10 @@ 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;
+    // Divergence is detected at the WRITE path, not by diffing (#2465): a user edit while the
+    // provider is in preset mode makes the selection theirs, and the proxy must never
+    // re-materialize over it afterwards.
+    markModelPresetDiverged(config.providers[provider]);
     persistConfig(config);
     const catalogRefresh = await convergeCodexCatalog();
     return jsonResponse({ ok: true, provider, selected: models, catalogRefresh });