@bitkyc08/opencodex 2.58.0 → 2.60.0

package/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,10 +490,14 @@ 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. */
   readonly nativeDisplayNames?: Readonly<Record<string, string>>;
+  /** Pristine installed-catalog multi-agent pins; see MultiAgentModeOptions.nativeDefaults. */
+  readonly nativeMultiAgentDefaults?: ReadonlyMap<string, string | null>;
 }
 
 /**
@@ -526,9 +530,11 @@ export function mergeCatalogEntriesFromObservedState({
   includeNativeOpenAi,
   accountBoundEntries,
   suppressedBareNativeSlugs = new Set(),
+  suppressedSyntheticMaxSlugs = new Set(),
   policy,
   openaiContextCap,
   nativeDisplayNames,
+  nativeMultiAgentDefaults,
 }: ObservedCatalogMergeInput): RawEntry[] {
   // Raw catalog rows contain nested arrays/objects that normalization mutates. Detach every row at
   // the observed-core boundary so callers can safely retain evidence objects or repeat the merge.
@@ -860,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 {
@@ -886,7 +905,7 @@ export function mergeCatalogEntriesFromObservedState({
     applyNativeVisibility(mergedEntries, disabledModels, alignedAccountBoundEntries.length > 0, observedNativeSlugs),
     multiAgentMode,
     multiAgentV2Enabled,
-    { keepNativeChatGptOnV1, preserveDefaultMultiAgentVersion: isReserveCatalogProjection },
+    { keepNativeChatGptOnV1, preserveDefaultMultiAgentVersion: isReserveCatalogProjection, nativeDefaults: nativeMultiAgentDefaults },
   );
   applyFullModelPickerOrder(versionedEntries, modelPickerOrder);
   for (const entry of versionedEntries) {
@@ -937,6 +956,7 @@ export function mergeCatalogEntriesForSync(
   ),
   openaiContextCap?: NativeContextLimitsInput,
   keepNativeChatGptOnV1 = false,
+  nativeMultiAgentDefaults?: ReadonlyMap<string, string | null>,
 ): RawEntry[] {
   // Retained for source compatibility with the original helper contract. Raw provider ids must
   // not suppress same-named native rows; actual admitted combo entries own that decision now.
@@ -973,6 +993,7 @@ export function mergeCatalogEntriesForSync(
     accountBoundEntries,
     suppressedBareNativeSlugs,
     openaiContextCap,
+    nativeMultiAgentDefaults,
     policy: {
       ...CANONICAL_NATIVE_CATALOG_CONTENT_POLICY,
       warningPolicy: "emit",

package/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"]);

package/src/codex/catalog/effort.ts

@@ -226,10 +226,12 @@ 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
@@ -237,7 +239,7 @@ export function applyReasoningLevels(
   // 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];
 }
 
 /**

package/src/codex/catalog/gather-capture.ts

@@ -100,8 +100,9 @@ import type {
   CatalogSourceEvidence,
   CatalogTrustedOpenAiApiPolicySnapshot,
 } from "../convergence-types";
-import { applyRegistryCapabilitySeedFill, modelCapabilities, modelInputModalities } from "./model-hints";
+import { modelCapabilities, modelInputModalities } from "./model-hints";
 import { configuredComboTargetModelsByProvider } from "./combo-member";
+import { resolveModelPolicy } from "../../providers/resolved-model-policy";
 
 /** Concurrent gatherRoutedModels callers with the same catalog identity share one live discovery.
  *  Keyed by gatherFlightKey so a different config cannot join or evict the wrong flight. */
@@ -344,8 +345,26 @@ export function captureProviderGather(
 ): CapturedProviderGather {
   const enriched = detachedClone(withCanonicalOpenAiForwardAuthDefault(name, configured));
   enrichProviderFromRegistry(name, enriched);
-  applyRegistryCapabilitySeedFill(name, enriched);
   const registryTransportMatch = providerMatchesRegistryTransport(name, enriched);
+  const registryEntry = registryTransportMatch ? getProviderRegistryEntry(name) : undefined;
+  const staticProvider = resolveModelPolicy({
+    providerName: name,
+    modelId: enriched.defaultModel ?? "__catalog_capture__",
+    provider: enriched,
+    registryEntry,
+    transportMatchedRegistry: registryTransportMatch,
+    ...(enriched.authMode ? { effectiveAuth: { authMode: enriched.authMode } } : {}),
+  }).provider;
+  for (const key of [
+    "modelContextWindows", "modelInputModalities", "modelMaxInputTokens", "modelMaxOutputTokens",
+    "modelReasoningEfforts", "modelSupportsReasoningSummaries",
+    "modelSupportsVerbosity", "modelSupportsServiceTier",
+  ] as const) {
+    if (staticProvider[key] !== undefined) enriched[key] = detachedClone(staticProvider[key]) as never;
+  }
+  // A present modelDefaultReasoningEfforts object is a whole-map catalog authority, including
+  // explicit {}. enrichProviderFromRegistry already preserves/fills that contract; replacing it
+  // with the resolver's per-key registry fill would turn "no configured default" into a seed default.
   const provider = recursivelyFreeze(enriched);
   const fastPolicyAuthority = captureFastPolicyAuthority(
     name,
@@ -499,6 +518,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,

package/src/codex/catalog/model-hints.ts

@@ -90,6 +90,7 @@ import type { CatalogModel } from "./parsing";
 import { disabledNativeSlugs, hasComboTargets, hasNativeOpenAiCapabilityMetadata, NATIVE_GPT56_MAX_INPUT_TOKENS, nativeContextLimits, nativeOpenAiCapabilityDisplayName, nativeDefaultReasoningEffort, nativeInputModalities, nativeOpenAiAutoCompactTokenLimit, nativeOpenAiContextWindow, nativeOpenAiMaxInputTokens, nativeOpenAiMaxOutputTokens, nativeOpenAiSlugs, nativeParallelToolCalls, nativeReasoningEfforts } from "./metadata";
 import { deriveComboCatalogModel, normalizedOpenAiApiSignature, openAiApiCollisionWarnings, replaceLastComboCatalogOmissions, warnUncataloguedComboOnce } from "./aggregation";
 import type { ComboCatalogOmission } from "./aggregation";
+import { clampObservedModelLimits, resolveModelPolicy } from "../../providers/resolved-model-policy";
 import type { CatalogGatherProviderAuthEvidence } from "./filesystem-evidence";
 import type {
   CatalogAdmissionSnapshot,
@@ -246,22 +247,6 @@ export function configuredReasoningSummarySupport(prov: OcxProviderConfig | unde
   return modelRecordValue(prov.modelReasoningSummaryDelivery, id) !== undefined ? true : undefined;
 }
 
-function configuredVerbositySupport(name: string, prov: OcxProviderConfig | undefined, id: string): boolean | undefined {
-  const explicit = prov ? modelRecordValue(prov.modelSupportsVerbosity, id) : undefined;
-  if (explicit !== undefined) return explicit;
-  if (!prov) return undefined;
-  void name;
-  // Provider-wide fallback for ids the per-model map does not enumerate — a live-discovered
-  // model would otherwise re-advertise a control the upstream accepts and ignores.
-  //
-  // Read from the PROVIDER CONFIG, never from PROVIDER_REGISTRY. A gather flight captures its
-  // registry authority up front and forbids any later registry read, so consulting the registry
-  // here made a custom-destination flight fall back to "configured" instead of serving its own
-  // discovery result (tests/codex-integration/codex-gather-authority.test.ts). `applyVerbosityDefaults` in
-  // providers/derive.ts materializes the registry default into the config at seed/enrich time.
-  return prov.supportsVerbosity;
-}
-
 export function applyProviderConfigHints(
   name: string,
   prov: OcxProviderConfig,
@@ -270,6 +255,15 @@ export function applyProviderConfigHints(
   metadataModelIdCaseFold?: boolean,
   effectiveAlias?: string | null,
 ): CatalogModel {
+  const staticPolicy = resolveModelPolicy({
+    providerName: name,
+    modelId: model.id,
+    provider: prov,
+    transportMatchedRegistry: false,
+    modelCapabilities: prov.modelCapabilities?.[model.id],
+    ...(prov.authMode ? { effectiveAuth: { authMode: prov.authMode } } : {}),
+    ...(effectiveAlias !== undefined ? { effectiveAlias } : {}),
+  });
   const displayName = configuredModelDisplayName(prov, model.id);
   // The alias decision is resolved once at flight admission (captureProviderGather) and threaded
   // through as `effectiveAlias`. Re-deriving it here would read PROVIDER_REGISTRY after admission,
@@ -279,11 +273,15 @@ export function applyProviderConfigHints(
   const providerAlias = typeof effectiveAlias === "string" || effectiveAlias === null
     ? effectiveAlias
     : model.providerAlias;
-  const configuredCap = configuredContextWindow(prov, model.id);
-  const configuredMaxInput = configuredMaxInputTokens(prov, model.id);
+  const configuredCap = staticPolicy.model.contextWindow ?? configuredContextWindow(prov, model.id);
+  const configuredMaxInput = staticPolicy.model.maxInputTokens;
   const maxOutputTokens = routedMaxOutputTokens(name, prov, model, model.id, metadataModelIdCaseFold);
   const configuredAutoCompact = configuredAutoCompactTokenLimit(prov, model.id);
-  let inputModalities = configuredInputModalities(prov, model.id);
+  // The resolver owns exact capability precedence and legacy exact/colon-family/case-fold fallback.
+  // Removing an exact capability row therefore returns this projection to legacy-map inference.
+  let inputModalities = staticPolicy.model.inputModalities
+    ? [...staticPolicy.model.inputModalities]
+    : undefined;
   // The shared vision-sidecar consumer predicate keeps catalog advertisement and request-time
   // planning aligned. The catalog must still advertise image input — the Codex app
   // gates attachments client-side on input_modalities, and a text-only entry would block images
@@ -296,24 +294,31 @@ export function applyProviderConfigHints(
     inputModalities = base.includes("image") ? [...base] : [...base, "image"];
   }
   const reasoningEfforts = configuredReasoningEfforts(prov, model.id);
-  const defaultReasoningEffort = modelRecordValue(prov.modelDefaultReasoningEfforts, model.id) ?? model.defaultReasoningEffort;
-  const supportsReasoningSummaries = configuredReasoningSummarySupport(prov, model.id);
-  const supportsVerbosity = configuredVerbositySupport(name, prov, model.id);
+  const suppressSyntheticMax = modelRecordValue(prov.modelSuppressSyntheticMax, model.id) === true;
+  const defaultReasoningEffort = staticPolicy.model.defaultReasoningEffort ?? model.defaultReasoningEffort;
+  const supportsReasoningSummaries = staticPolicy.model.supportsReasoningSummaries;
+  const supportsVerbosity = staticPolicy.model.supportsVerbosity;
   const fastPolicy = fastPolicyForModel(prov, model.id, name);
+  // Frozen gather providers retain the captured Fast authority. That late/captured eligibility
+  // owns catalog publication, including an explicit provider-level false.
   const supportsServiceTier = serviceTierSupportFromPolicy(fastPolicy);
   const {
     supportsServiceTier: _staleServiceTier,
     fastTierDescription: _staleFastTierDescription,
     providerAlias: _staleProviderAlias,
+    suppressSyntheticMax: _staleSuppressSyntheticMax,
     ...modelWithoutServiceTier
   } = model;
   // 已发现窗口只允许被配置值压低；缺窗口时，已开的 Context cap 就是实际窗口。
   const discoveredWindow = typeof model.contextWindow === "number" && model.contextWindow > 0
     ? model.contextWindow
     : undefined;
-  const hintedWindow = discoveredWindow !== undefined
-    ? (configuredCap !== undefined ? Math.min(discoveredWindow, configuredCap) : discoveredWindow)
-    : (configuredCap ?? (providerCap !== undefined ? resolveUnknownRoutedContextWindow(providerCap) : undefined));
+  const projectedLimits = clampObservedModelLimits(staticPolicy.model, {
+    ...(discoveredWindow !== undefined ? { contextWindow: discoveredWindow } : {}),
+    ...(typeof model.maxInputTokens === "number" && model.maxInputTokens > 0 ? { maxInputTokens: model.maxInputTokens } : {}),
+  });
+  const hintedWindow = projectedLimits.contextWindow
+    ?? (providerCap !== undefined ? resolveUnknownRoutedContextWindow(providerCap) : undefined);
   const hinted = {
     ...modelWithoutServiceTier,
     ...(displayName !== undefined ? { displayName } : {}),
@@ -321,11 +326,10 @@ 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
-          ? Math.min(model.maxInputTokens, configuredMaxInput)
-          : configuredMaxInput,
+        maxInputTokens: projectedLimits.maxInputTokens ?? configuredMaxInput,
       }
       : {}),
     ...(maxOutputTokens !== undefined ? { maxOutputTokens } : {}),
@@ -394,6 +398,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>>> = {
@@ -582,10 +611,11 @@ function discoveredPricingRate(value: unknown): number | undefined {
 /**
  * Cost class for one discovered row, read from the provider's own `pricing` object (#3666).
  *
- * Fail closed. Only a complete pair of non-negative numeric rates classifies at all; a missing,
- * one-sided, non-numeric, or negative rate is "unknown" and therefore excluded from a free-only
- * filter. Showing a paid model under a Free filter spends the user's money, while hiding a free
- * one costs a click.
+ * Fail closed. Any positive numeric component proves the model is paid. Calling it free requires
+ * a complete prompt/completion pair and every published pricing component to be a non-negative
+ * numeric zero; an unsupported component is "unknown" because it may describe another charge.
+ * Showing a paid model under a Free filter spends the user's money, while hiding a free one costs
+ * a click.
  *
  * Two things that look like evidence and are not. A `:free` id suffix is an OpenRouter naming
  * convention, not a price — Nous ships `:free` slugs on a provider whose `freeTier` is false on
@@ -598,10 +628,13 @@ function discoveredPricingRate(value: unknown): number | undefined {
 export function discoveredPricingStatus(item: ProviderModelsApiItem): "free" | "paid" | "unknown" {
   const pricing = plainRecord(item.pricing) ?? plainRecord(plainRecord(item.metadata)?.pricing);
   if (!pricing) return "unknown";
+  const rates = Object.values(pricing).map(discoveredPricingRate);
+  if (rates.some(rate => rate !== undefined && rate > 0)) return "paid";
+  if (rates.some(rate => rate === undefined)) return "unknown";
   const prompt = discoveredPricingRate(pricing.prompt ?? pricing.input);
   const completion = discoveredPricingRate(pricing.completion ?? pricing.output);
   if (prompt === undefined || completion === undefined) return "unknown";
-  return prompt === 0 && completion === 0 ? "free" : "paid";
+  return "free";
 }
 
 export function catalogHintsFromModelsApiItem(providerName: string, item: ProviderModelsApiItem): Partial<CatalogModel> {

package/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;
@@ -255,12 +257,19 @@ export function readCodexCatalogPath(): string {
   return activeDefaultCatalogPath();
 }
 
-/** Resolve the configured catalog without consulting ambient CODEX_HOME again. */
-export function readCodexCatalogPathForHome(codexHome: string): string {
+/**
+ * Resolve the configured catalog without consulting ambient CODEX_HOME again.
+ *
+ * `configText` is for a caller that has already read that same `config.toml` under
+ * its own constraints - the prompt-text probe reads it bounded, on the request
+ * thread - so resolving the catalog does not cost a second, unbounded read of the
+ * file the caller is holding. Omitting it keeps the original behaviour.
+ */
+export function readCodexCatalogPathForHome(codexHome: string, configText?: string): string {
   try {
     const configPath = join(codexHome, "config.toml");
-    if (existsSync(configPath)) {
-      const toml = readFileSync(configPath, "utf-8");
+    if (configText !== undefined || existsSync(configPath)) {
+      const toml = configText ?? readFileSync(configPath, "utf-8");
       const path = readRootTomlString(toml, "model_catalog_json");
       if (path) return resolve(codexHome, path);
     }
@@ -284,6 +293,30 @@ export function readConfiguredAutoReviewModel(): string | null {
   return null;
 }
 
+/**
+ * Read the root `model` pin from Codex's config.toml (issue #4646).
+ *
+ * Codex starts every new session on this id, and nothing in opencodex checks that the id is one
+ * the proxy actually exposes: the pin lives in Codex's config, while exposure is decided here by
+ * `disabledModels`, provider `selectedModels`, and account entitlements. When the two disagree
+ * every turn fails and no surface says why, which is what the `ocx doctor` section added for
+ * #4646 reports.
+ *
+ * Read-only, and deliberately the same shape and the same swallow-and-return-null error policy as
+ * `readConfiguredAutoReviewModel` above: a diagnostic must degrade to "unknown" on an unreadable
+ * or absent config rather than throw out of the surface that called it.
+ */
+export function readConfiguredDefaultModel(): string | null {
+  try {
+    const configPath = activeCodexConfigPath();
+    if (existsSync(configPath)) {
+      const toml = readFileSync(configPath, "utf-8");
+      return readRootTomlString(toml, "model");
+    }
+  } catch { /* ignore */ }
+  return null;
+}
+
 export function parseCatalogJson(raw: string): RawCatalog | null {
   try {
     const cat = JSON.parse(raw);
@@ -627,6 +660,14 @@ export interface MultiAgentModeOptions {
    * so they can still spawn Grok/Claude — ChatGPT encrypts v2 NEW_TASK bodies.
    */
   keepNativeChatGptOnV1?: boolean;
+  /**
+   * Pristine installed-catalog pins keyed by bare native slug. When provided, the
+   * backup — not the bundled snapshot — is authoritative for the rows it contains,
+   * and a preserved live/native row outside it keeps the pin it already carries:
+   * an absent baseline entry cannot distinguish a stale forced stamp from a
+   * legitimate user- or provider-preserved pin, so the non-destructive read wins.
+   */
+  nativeDefaults?: ReadonlyMap<string, string | null>;
 }
 
 /** Catalog rows that run on the ChatGPT backend (encrypt v2 child tasks). */
@@ -707,13 +748,34 @@ export function applyMultiAgentMode(
         && hasNativeOpenAiCapabilityMetadata(routedNativeSlug)
         ? routedNativeSlug
         : undefined;
+      const accountBoundNativeSlug = trustedAccountBoundNativeCatalogSlug(entry);
+      const nativeLookupSlug = accountBoundNativeSlug ?? slug;
+      // The baseline is built from bare native slugs only, so "absent from the
+      // baseline" is not evidence about a routed row — it is guaranteed. Only a
+      // native row can carry a pin the baseline legitimately failed to mention;
+      // a routed row keeps the documented default-mode normalization.
+      const isNativeCatalogEntry = accountBoundNativeSlug !== undefined || !slug.includes("/");
+      const hasNativeDefault = !nativeAlias
+        && codexForwardCapabilityAlias === undefined
+        && options.nativeDefaults?.has(nativeLookupSlug) === true;
       const upstreamPin = nativeAlias
         ? nativeMultiAgentVersion(slug)
         : codexForwardCapabilityAlias
           ? nativeMultiAgentVersion(codexForwardCapabilityAlias)
-          : UPSTREAM_NATIVE_ENTRIES.get(trustedAccountBoundNativeCatalogSlug(entry) ?? slug)?.multi_agent_version;
+          : hasNativeDefault
+            ? options.nativeDefaults?.get(nativeLookupSlug)
+            : options.nativeDefaults === undefined
+              ? UPSTREAM_NATIVE_ENTRIES.get(nativeLookupSlug)?.multi_agent_version
+              : undefined;
       if (typeof upstreamPin === "string") {
         entry.multi_agent_version = upstreamPin;
+      } else if (options.nativeDefaults !== undefined
+        && !nativeAlias
+        && codexForwardCapabilityAlias === undefined
+        && isNativeCatalogEntry
+        && !hasNativeDefault
+        && typeof entry.multi_agent_version === "string") {
+        continue;
       } else if (v2FeatureEnabled) {
         entry.multi_agent_version = "v2";
       } else {
@@ -741,6 +803,13 @@ export function normalizeRoutedCatalogEntry(
   delete entry.multi_agent_reasoning_effort;
   delete entry.use_responses_lite;
   delete entry.supports_websockets;
+  // Routed rows cloned from native templates must not inherit OpenAI-only experimental context
+  // delivery. Codex reads the flag as "this model accepts experimental context history" and drives
+  // its context-management cadence from it, so a third-party provider that never negotiated it gets
+  // a compact-after-every-step loop instead (observed on a routed DeepSeek row: 1,600+ compactions
+  // in a single thread). Nothing re-applies the field from provider metadata during this step, so
+  // the row leaves this normalization without it.
+  delete entry.supports_experimental_context;
   /*
    * Tier metadata is stripped from routed rows because a row cloned from a native template
    * would otherwise hand a third-party provider OpenAI's tiers.
@@ -888,3 +957,19 @@ export function readNativeBaseline(catalogPath: string): Map<string, number> {
   }
   return out;
 }
+
+/**
+ * Extract the pristine baseline's per-slug multi-agent pins. A bare native row that
+ * carried no pin maps to null so "baseline says unpinned" stays distinguishable
+ * from "baseline never contained this row".
+ */
+export function nativeMultiAgentDefaults(
+  models: readonly Readonly<Record<string, unknown>>[] | null | undefined,
+): Map<string, string | null> {
+  const out = new Map<string, string | null>();
+  for (const entry of models ?? []) {
+    if (typeof entry.slug !== "string" || entry.slug.includes("/")) continue;
+    out.set(entry.slug, typeof entry.multi_agent_version === "string" ? entry.multi_agent_version : null);
+  }
+  return out;
+}

package/src/codex/catalog/provider-models.ts

@@ -11,6 +11,7 @@ import {
   clearModelCache,
   clearProviderDiscoveryStatus,
   captureModelCacheGeneration,
+  observeModelCacheRevision,
   DEFAULT_MODEL_CACHE_TTL_MS,
   getFreshCached,
   getStaleCached,
@@ -108,6 +109,14 @@ import { captureProviderGather, materializeCapturedHeaders } from "./gather-capt
 export interface ProviderModelsResult {
   readonly models: CatalogModel[];
   readonly outcome: CatalogGatherProviderModelOutcome;
+  /**
+   * The provider's cache content revision as it stood when these rows were chosen.
+   *
+   * Sampled here rather than by the caller because only this point is synchronous with the
+   * choice. A caller reading it after its own await can observe a revision another flight
+   * published in between, and would then record these rows under that flight's identity.
+   */
+  readonly contentRevision: string;
 }
 export const refreshingModelsAuthResolver: ModelsAuthResolver = { kind: "refreshing" };
 
@@ -145,7 +154,11 @@ export async function fetchProviderModelsWithAuth(
   const observed = (
     models: CatalogModel[],
     state: CatalogGatherProviderModelOutcome["state"],
-  ): ProviderModelsResult => ({ models, outcome: { provider: name, state } });
+  ): ProviderModelsResult => ({
+    models,
+    outcome: { provider: name, state },
+    contentRevision: observeModelCacheRevision(name),
+  });
   // Capture before any credential refresh or outbound await. OAuth account changes clear this
   // generation, so a request started with the former account cannot later publish its result.
   const cacheGeneration = captureModelCacheGeneration(name);
@@ -372,7 +385,11 @@ export async function fetchProviderModelsWithAuth(
       ...(cursorFetch ? { fetch: cursorFetch } : {}),
     });
     if (liveResult.ok) {
-      const available = filterCursorConfiguredModelsByLiveDiscovery(configured, liveResult.models);
+      const available = filterCursorConfiguredModelsByLiveDiscovery(
+        configured,
+        liveResult.models,
+        liveResult.maxModeModels ?? [],
+      );
       const result = available.length > 0 ? available : configured;
       // Cache the discovery-filtered roster without combo retention so a later
       // gather can re-apply the current capture's retain set on read.