feat(catalog): suppress synthetic max per model while retaining ultra

docs-site/src/content/docs/reference/configuration/providers.md

@@ -181,6 +181,7 @@ Providers can expose a built-in shorthand, such as `agy` for `google-antigravity
 | `refreshPolicy?` | `"proactive" \| "lazy-only" \| "disabled"` | Override this OAuth provider's Token Guardian policy. |
 | `reasoningEfforts?` | `string[]` | Provider-wide Codex reasoning labels to advertise and send. For `google`-adapter providers, a configured ladder also asserts `thinkingLevel` capability: direct and Vertex non-image requests send the selected effort as `generationConfig.thinkingConfig.thinkingLevel`, while Cloud Code Assist uses its envelope-specific path. |
 | `modelReasoningEfforts?` | `Record<string, string[]>` | Per-model labels. An empty list hides effort control. As with `reasoningEfforts`, each configured `google`-adapter ladder asserts `thinkingLevel` capability; direct and Vertex non-image requests use the flat Gemini path, while Cloud Code Assist sends it under its request envelope. |
+| `modelSuppressSyntheticMax?` | `Record<string, boolean>` | Catalog-only per-model switch. `true` prevents OpenCodex from adding a missing synthetic `max` rung while retaining a provider-declared `max` and continuing to add `ultra` to reasoning-capable ladders. A preserved row that already contains `max` keeps it until healthy discovery rebuilds that row, because the catalog does not persist whether an older `max` was synthetic. If a configured default names a suppressed missing `max`, the catalog falls back to the highest real rung below it. Codex uses the same ladder membership for the picker and explicit `spawn_agent` effort validation, so an explicit `max` spawn can fail client-side before proxy clamping; `ultra` remains the supported harness path. |
 | `modelSupportsReasoningSummaries?` | `Record<string, boolean>` | Set a model to `false` to stop advertising summaries and strip summary-delivery fields. |
 | `modelReasoningSummaryDelivery?` | `Record<string, "sequential" \| "sequential_cutoff" \| "concurrent" \| "concurrent_cutoff">` | Per-model Responses delivery enum; rewrites an existing delivery field. |
 | `modelAdapters?` | `Record<string, string>` | Per-model `openai-chat` or `openai-responses` wire override for mixed-wire gateways. Explicit entries beat registry defaults. The OpenCode Go preset selects Responses for `gpt-5.6-luna` while leaving sibling models on their documented wires; DeepSeek can select native Responses for `deepseek-v4-flash`; and GitHub Copilot declares Responses-only defaults for the following models (`gpt-5.3-codex`, `gpt-5.4`, `gpt-5.4-mini`, `gpt-5.5`, `gpt-5.6-luna`, `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-6-astra`, `grok-4.5`, `grok-4.6`, `mai-code-1.1-flash`, `mai-code-1-flash-picker`) because those models reject `/chat/completions` for agent traffic. Models without a built-in default (for example `gpt-5.4-nano`) can be opted in here. Single-wire upstream pins and canonical ChatGPT forward reject overrides. |

scripts/test-layout/layout.json

@@ -924,6 +924,7 @@
     "management-origin-tls.test.ts": "server",
     "management-provider-pinsless-validation.test.ts": "server",
     "management-provider-proto-override.test.ts": "server",
+    "management-provider-synthetic-max.test.ts": "server",
     "management-provider-validation.test.ts": "server",
     "management-route-registry.test.ts": "server",
     "management-workflow-budget-routes.test.ts": "server",

src/codex/catalog/build-entries.ts

@@ -26,7 +26,7 @@ import {
 } from "./metadata";
 import { resetBundledCatalogCacheForTests } from "./bundled";
 import { isMultiAgentV2Enabled } from "../features";
-import { ensureUltraReasoningLevel, isGpt56NativeSlug } from "./effort";
+import { clampedDefaultEffort, ensureUltraReasoningLevel, isGpt56NativeSlug } from "./effort";
 import { clearGatherRoutedModelsInflight, lastDropWarnSignature } from "./provider-fetch";
 import {
   accountSelectorShadowCollisionWarnings,
@@ -490,6 +490,8 @@ export interface ObservedCatalogMergeInput {
   readonly includeNativeOpenAi: boolean;
   readonly accountBoundEntries: readonly RawEntry[];
   readonly suppressedBareNativeSlugs?: ReadonlySet<string>;
+  /** Routed slugs that must not gain a missing synthetic max rung during retained-row repair. */
+  readonly suppressedSyntheticMaxSlugs?: ReadonlySet<string>;
   readonly policy: ObservedCatalogMergePolicy;
   readonly openaiContextCap?: NativeContextLimitsInput;
   /** Exact display-only labels for bare native OpenAI models. */
@@ -528,6 +530,7 @@ export function mergeCatalogEntriesFromObservedState({
   includeNativeOpenAi,
   accountBoundEntries,
   suppressedBareNativeSlugs = new Set(),
+  suppressedSyntheticMaxSlugs = new Set(),
   policy,
   openaiContextCap,
   nativeDisplayNames,
@@ -863,16 +866,29 @@ export function mergeCatalogEntriesFromObservedState({
     });
     // Mock-max universality (260709): preserved routed entries from disk may predate
     // the max rung — ensure it here so subagent max spawns validate on every
-    // reasoning-capable entry. max only: 5.6 exact ladders (luna: no ultra) stay intact.
+    // reasoning-capable entry. A suppressed preserved row that already contains max keeps it;
+    // without persisted provenance, only a healthy provider rebuild can distinguish and remove
+    // an older synthetic rung from a real provider-declared rung. max only: 5.6 exact ladders
+    // (luna: no ultra) stay intact.
     if (!freshCustomEntries.has(m) && !exactCombo && !reserveProjection && !String(e.slug ?? "").startsWith("opencode-go/")) {
       const levels = Array.isArray(e.supported_reasoning_levels)
         ? e.supported_reasoning_levels as Array<{ effort?: string }>
         : [];
-      if (levels.length > 0 && !levels.some(level => level.effort === "max")) {
+      if (levels.length > 0
+        && !suppressedSyntheticMaxSlugs.has(String(e.slug ?? ""))
+        && !levels.some(level => level.effort === "max")) {
         levels.push(CODEX_REASONING_LEVELS.find(level => level.effort === "max")
           ?? { effort: "max", description: "Maximum reasoning depth for the hardest problems" });
         e.supported_reasoning_levels = levels;
       }
+      if (suppressedSyntheticMaxSlugs.has(String(e.slug ?? ""))
+        && typeof e.default_reasoning_level === "string"
+        && !levels.some(level => level.effort === e.default_reasoning_level)) {
+        e.default_reasoning_level = clampedDefaultEffort(
+          e.default_reasoning_level,
+          levels.flatMap(level => typeof level.effort === "string" ? [level.effort] : []),
+        );
+      }
     }
     if (wsEnabled) e.supports_websockets = true;
     else {

src/codex/catalog/derive-entry.ts

@@ -160,6 +160,7 @@ export function deriveEntry(
         preserveExactReasoning
           || codexForwardNativeCapabilityAlias !== null
           || preservePinnedNativeCustomReasoning(model),
+        model?.suppressSyntheticMax === true,
       );
       // This exact provider/model pair is the ChatGPT/Codex forward surface. Keep the pinned
       // native tool/search/responses-lite contract while preserving the routed slug and wire id.
@@ -208,7 +209,13 @@ export function deriveEntry(
   };
   if (isRouted) {
     applyRoutedCodexToolMode(entry, model?.codexToolMode);
-    applyReasoningLevels(entry, model?.reasoningEfforts, model?.defaultReasoningEffort, preserveExactReasoning || preservePinnedNativeCustomReasoning(model));
+    applyReasoningLevels(
+      entry,
+      model?.reasoningEfforts,
+      model?.defaultReasoningEffort,
+      preserveExactReasoning || preservePinnedNativeCustomReasoning(model),
+      model?.suppressSyntheticMax === true,
+    );
   }
   else {
     applyReasoningLevels(entry, isGpt56NativeSlug(slug) ? undefined : ["low", "medium", "high", "xhigh"]);

src/codex/catalog/effort.ts

@@ -226,18 +226,20 @@ export function applyReasoningLevels(
   effortsOverride?: string[],
   defaultOverride?: string,
   preserveExact = false,
+  suppressSyntheticMax = false,
 ): void {
   let efforts = sanitizeCodexReasoningEfforts(effortsOverride) ?? ROUTED_REASONING_LEVELS.map(l => l.effort);
-  // Mock top tiers (user decision 260709): every reasoning-capable model advertises `max`
-  // even when the provider ladder stops lower — subagent spawns pass `max` DIRECTLY
+  // Mock top tiers (user decision 260709): reasoning-capable routed models advertise `max`
+  // even when the provider ladder stops lower, unless the model opts out of that synthesis.
+  // Subagent spawns pass `max` DIRECTLY
   // (no ultra->max client conversion) and codex-rs validates it by catalog membership,
   // so a missing max rung hard-fails spawn_agent effort overrides. The wire stays honest:
   // routed adapters clamp via clampToSupportedCodexEffort and natives via
   // nativeEffortClamp (max -> the model's real top rung). A `none`-only ladder is NOT
   // reasoning-capable, so it must not grow synthetic top rungs.
   if (!preserveExact && efforts.length > 0 && efforts.some(effort => effort !== "none" && effort !== "minimal")) {
     const additions: string[] = [];
-    if (!efforts.includes("max")) additions.push("max");
+    if (!suppressSyntheticMax && !efforts.includes("max")) additions.push("max");
     if (!efforts.includes("ultra")) additions.push("ultra");
     if (additions.length > 0) efforts = sanitizeCodexReasoningEfforts([...efforts, ...additions]) ?? efforts;
   }
@@ -258,9 +260,11 @@ export function applyReasoningLevels(
   }
   entry.default_reasoning_level = defaultOverride && efforts.includes(defaultOverride)
     ? defaultOverride
-    : efforts.includes("medium") ? "medium" : efforts.includes("high") ? "high"
-    // Sentinels never become the implicit default when real rungs are declared.
-    : efforts.find(effort => effort !== "none" && effort !== "minimal") ?? efforts[0];
+    : suppressSyntheticMax && defaultOverride === "max"
+      ? clampedDefaultEffort(defaultOverride, efforts)
+      : efforts.includes("medium") ? "medium" : efforts.includes("high") ? "high"
+        // Sentinels never become the implicit default when real rungs are declared.
+        : efforts.find(effort => effort !== "none" && effort !== "minimal") ?? efforts[0];
 }
 
 /**

src/codex/catalog/gather-capture.ts

@@ -499,6 +499,7 @@ function providerCatalogFingerprint(name: string, prov: OcxProviderConfig): Reco
     inMod: prov.modelInputModalities ?? null,
     capabilities: prov.modelCapabilities ?? null,
     re: prov.modelReasoningEfforts ?? null,
+    suppressMax: prov.modelSuppressSyntheticMax ?? null,
     defRe: prov.modelDefaultReasoningEfforts ?? null,
     rsSum: prov.modelSupportsReasoningSummaries ?? null,
     verbosity: prov.modelSupportsVerbosity ?? null,

src/codex/catalog/model-hints.ts

@@ -296,6 +296,7 @@ export function applyProviderConfigHints(
     inputModalities = base.includes("image") ? [...base] : [...base, "image"];
   }
   const reasoningEfforts = configuredReasoningEfforts(prov, model.id);
+  const suppressSyntheticMax = modelRecordValue(prov.modelSuppressSyntheticMax, model.id) === true;
   const defaultReasoningEffort = modelRecordValue(prov.modelDefaultReasoningEfforts, model.id) ?? model.defaultReasoningEffort;
   const supportsReasoningSummaries = configuredReasoningSummarySupport(prov, model.id);
   const supportsVerbosity = configuredVerbositySupport(name, prov, model.id);
@@ -305,6 +306,7 @@ export function applyProviderConfigHints(
     supportsServiceTier: _staleServiceTier,
     fastTierDescription: _staleFastTierDescription,
     providerAlias: _staleProviderAlias,
+    suppressSyntheticMax: _staleSuppressSyntheticMax,
     ...modelWithoutServiceTier
   } = model;
   // 已发现窗口只允许被配置值压低；缺窗口时，已开的 Context cap 就是实际窗口。
@@ -321,6 +323,7 @@ export function applyProviderConfigHints(
     ...(hintedWindow !== undefined ? { contextWindow: hintedWindow } : {}),
     ...(inputModalities ? { inputModalities } : {}),
     ...(reasoningEfforts !== undefined ? { reasoningEfforts } : {}),
+    ...(suppressSyntheticMax ? { suppressSyntheticMax: true } : {}),
     ...(configuredMaxInput !== undefined
       ? {
         maxInputTokens: typeof model.maxInputTokens === "number" && model.maxInputTokens > 0
@@ -394,6 +397,31 @@ export function applyConfigHintsToCachedModels(
 ): CatalogModel[] {
   return models.map(model => applyProviderConfigHints(name, prov, model, contextCap, metadataModelIdCaseFold, effectiveAlias));
 }
+
+/** Catalog slugs whose configured model must not gain a missing synthetic max rung. */
+export function suppressedSyntheticMaxCatalogSlugs(
+  config: Pick<OcxConfig, "providers">,
+  models: readonly CatalogModel[],
+  observedEntries: readonly { slug?: unknown }[] = [],
+): ReadonlySet<string> {
+  const slugs = new Set(models
+    .filter(model => model.suppressSyntheticMax === true)
+    .map(catalogModelSlug));
+  for (const [provider, providerConfig] of Object.entries(config.providers)) {
+    const configured = providerConfig.modelSuppressSyntheticMax ?? {};
+    const encoded = Object.fromEntries(Object.entries(configured)
+      .map(([modelId, suppress]) => [routedSlug(provider, modelId).slice(provider.length + 1), suppress]));
+    for (const [modelId, suppress] of Object.entries(configured)) {
+      if (suppress === true) slugs.add(routedSlug(provider, modelId));
+    }
+    for (const entry of observedEntries) {
+      const slug = typeof entry.slug === "string" ? entry.slug : "";
+      if (!slug.startsWith(`${provider}/`)) continue;
+      if (modelRecordValue(encoded, slug.slice(provider.length + 1)) === true) slugs.add(slug);
+    }
+  }
+  return slugs;
+}
 export const QUIET_AUTHORITATIVE_CATALOG_PROVIDERS = new Set(["kimi", "xai"]);
 
 export const CALLABLE_CONFIGURED_COMPATIBILITY_MODELS: Readonly<Record<string, ReadonlySet<string>>> = {

src/codex/catalog/parsing.ts

@@ -112,6 +112,8 @@ export interface CatalogModel {
   displayName?: string;
   owned_by?: string;
   reasoningEfforts?: string[];
+  /** Suppress only catalog synthesis of a missing max rung; provider-declared max survives. */
+  suppressSyntheticMax?: boolean;
   defaultReasoningEffort?: string;
   contextWindow?: number;
   maxInputTokens?: number;

src/codex/catalog/retained-sync.ts

@@ -51,6 +51,7 @@ import { trustedAccountBoundNativeCatalogSlug } from "./account-models";
 import { bundledCatalogCacheState, loadBundledCodexCatalog } from "./bundled";
 import { isMultiAgentV2Enabled } from "../features";
 import { clampCatalogModelsToCodexSupport } from "./effort";
+import { suppressedSyntheticMaxCatalogSlugs } from "./model-hints";
 import { filterCatalogVisibleModels, gatherRoutedModels, type CatalogGatherProviderModelOutcome } from "./provider-fetch";
 import { dedupeCatalogEntriesBySlug, enforceCatalogSlugUniqueness, exactComboCatalogSlugs, type ComboCatalogOmission } from "./aggregation";
 import {
@@ -322,6 +323,11 @@ function writeRetainedCatalogSync({
   const enabledGo = filterCatalogVisibleModels(goModels, config);
   const featured = config.subagentModels ?? [];
   const orderedGoModels = orderForSubagents(enabledGo, featured); // stable tie-break among equal priorities
+  const suppressedSyntheticMaxSlugs = suppressedSyntheticMaxCatalogSlugs(
+    config,
+    orderedGoModels,
+    catalogModelsForMerge,
+  );
   const modelPickerOrder = config.modelPickerOrder ?? [];
   const multiAgentMode: MultiAgentMode = config.multiAgentMode === "v1" || config.multiAgentMode === "v2" ? config.multiAgentMode : "default";
   const exactComboSlugs = exactComboCatalogSlugs(config);
@@ -523,6 +529,7 @@ function writeRetainedCatalogSync({
     includeNativeOpenAi,
     accountBoundEntries,
     suppressedBareNativeSlugs,
+    suppressedSyntheticMaxSlugs,
     openaiContextCap,
     nativeDisplayNames: config.providers[OPENAI_CODEX_PROVIDER_ID]?.modelDisplayNames,
     nativeMultiAgentDefaults: nativePinBaseline,

src/codex/convergence.ts

@@ -70,6 +70,7 @@ import {
   clampCatalogModelsToObservedCodexSupport,
   supportedCodexReasoningEffortsFromObservedCatalog,
 } from "./catalog/effort";
+import { suppressedSyntheticMaxCatalogSlugs } from "./catalog/model-hints";
 import { codexRuntimeStatePath, peekCodexRuntimeProcessCache } from "./runtime";
 import { codexAccountNamespaceEntries, isMainCodexAccountTarget } from "./account-namespaces";
 import { MAIN_CODEX_ACCOUNT_ID } from "./main-account";
@@ -306,6 +307,7 @@ function prepareCatalog(
     [catalog.models ?? [], ...nativeRecoverySources],
   );
   const catalogModels = nativeCatalogModels;
+  const suppressedSyntheticMaxSlugs = suppressedSyntheticMaxCatalogSlugs(config, ordered, catalogModels);
   const routedEntries = buildCatalogEntriesFromObservedState({
     template: template ? JSON.parse(JSON.stringify(template)) : null,
     gptSlugs: [],
@@ -372,6 +374,7 @@ function prepareCatalog(
     includeNativeOpenAi,
     accountBoundEntries,
     suppressedBareNativeSlugs,
+    suppressedSyntheticMaxSlugs,
     openaiContextCap,
     nativeDisplayNames: config.providers[OPENAI_CODEX_PROVIDER_ID]?.modelDisplayNames,
     nativeMultiAgentDefaults: nativeMultiAgentDefaults(baselineCatalogModels),

src/config/schema/config-schema.ts

@@ -468,6 +468,17 @@ export const configSchema = z.object({
         message: reasoningSummariesError,
       });
     }
+    const suppressSyntheticMaxError = booleanRecordConfigError(
+      (provider as { modelSuppressSyntheticMax?: unknown }).modelSuppressSyntheticMax,
+      "modelSuppressSyntheticMax",
+    );
+    if (suppressSyntheticMaxError) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["providers", redactSecretString(name), "modelSuppressSyntheticMax"],
+        message: suppressSyntheticMaxError,
+      });
+    }
     const verbositySupportError = booleanRecordConfigError(
       (provider as { modelSupportsVerbosity?: unknown }).modelSupportsVerbosity,
       "modelSupportsVerbosity",

src/config/schema/leaf-validators.ts

@@ -252,6 +252,7 @@ export const providerConfigSchema = z.object({
   fastWire: fastWireSchema.nullable().optional(),
   supportsServiceTier: z.boolean().optional(),
   modelSupportsServiceTier: z.record(z.string().min(1), z.boolean()).optional(),
+  modelSuppressSyntheticMax: z.record(z.string().min(1), z.boolean()).optional(),
   preserveResponsesReasoningContent: z.boolean().optional(),
   decodesNativeCompactionBlobs: z.boolean().optional(),
   allowEncryptedV2AgentTasks: z.boolean().optional(),

src/providers/model-rename-migration.ts

@@ -86,6 +86,7 @@ const MODEL_KEYED_RECORDS = [
   "modelMaxOutputTokens",
   "modelInputModalities",
   "modelReasoningEfforts",
+  "modelSuppressSyntheticMax",
   "modelDefaultReasoningEfforts",
   "modelReasoningEffortMap",
 ] as const;

src/server/auth-cors.ts

@@ -799,6 +799,8 @@ export function providerManagementConfigError(
   }
   const reasoningSummariesError = booleanRecordConfigError(raw.modelSupportsReasoningSummaries, "modelSupportsReasoningSummaries");
   if (reasoningSummariesError) return `provider ${name} ${reasoningSummariesError}`;
+  const suppressSyntheticMaxError = booleanRecordConfigError(raw.modelSuppressSyntheticMax, "modelSuppressSyntheticMax");
+  if (suppressSyntheticMaxError) return `provider ${name} ${suppressSyntheticMaxError}`;
   const reasoningSummaryDeliveryError = reasoningSummaryDeliveryRecordConfigError(
     raw.modelReasoningSummaryDelivery,
     raw.modelSupportsReasoningSummaries,
@@ -986,6 +988,7 @@ const PROVIDER_CONFIG_FIELD_POLICY = {
   refreshPolicy: "editor",
   reasoningEfforts: "editor",
   modelReasoningEfforts: "editor",
+  modelSuppressSyntheticMax: "editor",
   modelDefaultReasoningEfforts: "editor",
   pinnedReasoningEffort: "editor",
   modelPinnedReasoningEfforts: "editor",