@bitkyc08/opencodex 2.7.43-preview.20260728 → 2.8.0

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

@@ -24,7 +24,7 @@ import { modelInList } from "../../types";
 import { CODEX_REASONING_LEVELS, codexEffortRank, configuredReasoningEfforts, modelRecordValue, sanitizeCodexReasoningEfforts } from "../../reasoning-effort";
 import { getJawcodeModelMetadata, getJawcodeModelMetadataCaseInsensitive, listJawcodeModelMetadata, resolveJawcodeProvider } from "../../generated/jawcode-model-metadata";
 import { enrichProviderFromRegistry, shouldCaseFoldMetadataModelId } from "../../providers/derive";
-import { getProviderRegistryEntry } from "../../providers/registry";
+import { getProviderRegistryEntry, providerMatchesRegistryTransport } from "../../providers/registry";
 import { applyProviderContextCap, providerContextCap } from "../../providers/context-cap";
 import { routedSlug, slugEquals, slugsEquivalent } from "../../providers/slug-codec";
 import { CODEX_GPT5_IDENTITY_LINE } from "../../adapters/identity";
@@ -39,8 +39,19 @@ import {
   targetKey,
 } from "../../combos";
 import type { NormalizedComboConfig } from "../../combos/types";
-import { providerDestinationResolvedError } from "../../lib/destination-policy";
+import {
+  ProviderOutboundPolicyError,
+  providerOutboundGet,
+  providerRedirectError,
+} from "../../lib/provider-outbound";
 import { redactSecretString } from "../../lib/redact";
+import {
+  extractProviderModelItems,
+  readBoundedDiscoveryJson,
+  resolveProviderModelDiscovery,
+  type ModelDiscoveryResponseFailure,
+  type ProviderModelsApiItem,
+} from "../../providers/model-discovery";
 import upstreamModelsSnapshot from "../data/upstream-models.json";
 
 
@@ -50,25 +61,72 @@ import { disabledNativeSlugs, hasComboTargets, nativeInputModalities, nativeOpen
 import { deriveComboCatalogModel, normalizedOpenAiApiSignature, openAiApiCollisionWarnings, replaceLastComboCatalogOmissions, warnUncataloguedComboOnce } from "./aggregation";
 import type { ComboCatalogOmission } from "./aggregation";
 
-export type ProviderModelsApiItem = {
-  id: string;
-  owned_by?: string;
-  context_length?: number;
-  max_model_len?: number;
-  metadata?: {
-    capabilities?: Record<string, unknown>;
-    limits?: Record<string, unknown>;
+/** 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. */
+interface GatherFlightResult {
+  models: CatalogModel[];
+  comboOmissions: ComboCatalogOmission[];
+}
+
+const gatherInflight = new Map<string, Promise<GatherFlightResult>>();
+
+function stableJson(value: unknown): string {
+  return JSON.stringify(value, (_key, nested) => {
+    if (nested && typeof nested === "object" && !Array.isArray(nested)) {
+      return Object.fromEntries(Object.entries(nested as Record<string, unknown>).sort(([a], [b]) => a.localeCompare(b)));
+    }
+    return nested;
+  });
+}
+
+function providerCatalogFingerprint(name: string, prov: OcxProviderConfig): Record<string, unknown> {
+  return {
+    n: name,
+    live: prov.liveModels !== false,
+    base: prov.baseUrl ?? "",
+    adapter: prov.adapter ?? "",
+    models: [...(prov.models ?? [])].sort(),
+    selected: [...(prov.selectedModels ?? [])].sort(),
+    defaultModel: prov.defaultModel ?? null,
+    ctx: prov.contextWindow ?? null,
+    ctxW: prov.modelContextWindows ?? null,
+    maxIn: prov.modelMaxInputTokens ?? null,
+    inMod: prov.modelInputModalities ?? null,
+    re: prov.modelReasoningEfforts ?? null,
+    defRe: prov.modelDefaultReasoningEfforts ?? null,
+    rsSum: prov.modelSupportsReasoningSummaries ?? null,
+    rsDel: prov.modelReasoningSummaryDelivery ?? null,
+    noVis: [...(prov.noVisionModels ?? [])].sort(),
+    ptc: prov.parallelToolCalls ?? null,
+    gMode: prov.googleMode ?? null,
   };
-};
+}
 
-export function isProviderModelsApiItems(value: unknown): value is ProviderModelsApiItem[] {
-  return Array.isArray(value) && value.every(item =>
-    item !== null
-    && typeof item === "object"
-    && !Array.isArray(item)
-    && typeof (item as { id?: unknown }).id === "string"
-    && (item as { id: string }).id.trim().length > 0
-  );
+function gatherFlightKey(config: OcxConfig): string {
+  const providers = Object.entries(config.providers)
+    .filter(([, prov]) => prov.disabled !== true)
+    .map(([name, prov]) => providerCatalogFingerprint(name, prov))
+    .sort((a, b) => String(a.n).localeCompare(String(b.n)));
+  const assembly = stableJson({
+    providers,
+    disabledModels: [...(config.disabledModels ?? [])].sort(),
+    combos: config.combos ?? {},
+    customModels: (config.customModels ?? []).map((cm) => ({
+      p: cm.provider,
+      m: cm.modelId,
+      d: cm.displayName ?? null,
+      cw: cm.contextWindow ?? null,
+      im: cm.inputModalities ?? null,
+    })),
+    caps: config.providerContextCaps ?? null,
+  });
+  const digest = createHash("sha256").update(assembly).digest("hex").slice(0, 16);
+  return `${digest}#${config.modelCacheTtlMs ?? DEFAULT_MODEL_CACHE_TTL_MS}`;
+}
+
+/** Drop in-flight gather so tests / full cache clears do not reuse a stale promise. */
+export function clearGatherRoutedModelsInflight(): void {
+  gatherInflight.clear();
 }
 
 export function configuredContextWindow(prov: OcxProviderConfig, id: string): number | undefined {
@@ -193,31 +251,134 @@ export function isGlm52ModelId(id: string): boolean {
   return normalized === "glm-5.2" || normalized === "glm-5.2[1m]";
 }
 
+function plainRecord(value: unknown): Record<string, unknown> | undefined {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : undefined;
+}
+
+const MODEL_DISCOVERY_METADATA_CONTROL_CHARS = /[\u0000-\u001f\u007f-\u009f\u2028\u2029]/;
+
+function positiveSafeInteger(...values: unknown[]): number | undefined {
+  return values.find(value => typeof value === "number" && Number.isSafeInteger(value) && value > 0) as number | undefined;
+}
+
+function normalizedMetadataString(raw: string, maxLength: number): string | undefined {
+  if (raw.length > maxLength * 4 || MODEL_DISCOVERY_METADATA_CONTROL_CHARS.test(raw)) return undefined;
+  const normalized = raw.trim().toLowerCase().replace(/\s+/g, "-").slice(0, maxLength);
+  return normalized || undefined;
+}
+
+function normalizedStringList(value: unknown, maxItems = 32, maxLength = 64): string[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const out: string[] = [];
+  const maxInspectedItems = Math.max(maxItems * 8, maxItems);
+  for (let i = 0; i < value.length && i < maxInspectedItems; i += 1) {
+    const raw = value[i];
+    if (typeof raw !== "string") continue;
+    const normalized = normalizedMetadataString(raw, maxLength);
+    if (normalized && !out.includes(normalized)) out.push(normalized);
+    if (out.length >= maxItems) break;
+  }
+  return out.length > 0 ? out : undefined;
+}
+
+function modelCapabilities(item: ProviderModelsApiItem): string[] | undefined {
+  const metadata = plainRecord(item.metadata);
+  const metadataCapabilities = metadata?.capabilities;
+  const capabilityRecord = plainRecord(metadataCapabilities) ?? plainRecord(item.capabilities);
+  const out = new Set<string>();
+  for (const list of [item.capabilities, item.features, item.supported_features, metadataCapabilities]) {
+    for (const capability of normalizedStringList(list) ?? []) out.add(capability);
+  }
+  const capabilityFields = capabilityRecord ?? {};
+  let inspectedCapabilityFields = 0;
+  for (const key in capabilityFields) {
+    if (!Object.hasOwn(capabilityFields, key)) continue;
+    inspectedCapabilityFields += 1;
+    if (inspectedCapabilityFields > 256 || out.size >= 32) break;
+    if (capabilityFields[key] === true) {
+      const normalized = normalizedMetadataString(key, 64);
+      if (normalized) out.add(normalized);
+    }
+  }
+  for (const field of ["supports_tools", "supports_tool_calling", "supports_function_calling"] as const) {
+    if (item[field] === true) out.add("tools");
+  }
+  for (const field of ["supports_reasoning", "reasoning"] as const) {
+    if (item[field] === true) out.add("reasoning");
+  }
+  return out.size > 0 ? [...out].filter(Boolean).slice(0, 32) : undefined;
+}
+
+function modelInputModalities(
+  item: ProviderModelsApiItem,
+  capabilities: readonly string[] | undefined,
+): string[] | undefined {
+  const metadata = plainRecord(item.metadata);
+  const capabilityRecord = plainRecord(metadata?.capabilities) ?? plainRecord(item.capabilities);
+  const explicit = normalizedStringList(
+    item.input_modalities
+      ?? item.modalities
+      ?? metadata?.input_modalities
+      ?? capabilityRecord?.input_modalities,
+    8,
+    24,
+  )?.filter(value => (
+    // Codex parses `input_modalities` as a closed enum of text | image | audio. A provider that
+    // advertises anything else (zenmux reports "video") must not reach the catalog: Codex rejects
+    // the whole file, so plugins, apps and MCP servers all stop loading over one model's metadata.
+    value === "text" || value === "image" || value === "audio"
+  ));
+  if (explicit && explicit.length > 0) return explicit;
+  if (capabilityRecord?.vision === false) return ["text"];
+  if (capabilityRecord?.vision === true || capabilities?.some(value => value === "vision" || value === "image-input")) {
+    return ["text", "image"];
+  }
+  return undefined;
+}
+
 export function catalogHintsFromModelsApiItem(providerName: string, item: ProviderModelsApiItem): Partial<CatalogModel> {
-  const capabilities = item.metadata?.capabilities;
-  const limits = item.metadata?.limits;
+  const metadata = plainRecord(item.metadata);
+  const capabilityRecord = plainRecord(metadata?.capabilities) ?? plainRecord(item.capabilities);
+  const limits = plainRecord(metadata?.limits);
   const contextWindow =
-    typeof limits?.max_context_length === "number" ? limits.max_context_length
-      : typeof item.context_length === "number" ? item.context_length
-      : typeof item.max_model_len === "number" ? item.max_model_len
-        : undefined;
- const reasoningEfforts = capabilities && typeof capabilities.reasoning_effort === "boolean"
-   ? (capabilities.reasoning_effort
-     ? ((providerName === "neuralwatt" || providerName === "zai") && isGlm52ModelId(item.id)
-       ? ["low", "medium", "high", "xhigh", "max"]
-       : ["low", "medium", "high", "xhigh"])
-     : [])
-   : undefined;
- const inputModalities = capabilities && typeof capabilities.vision === "boolean"
-    ? (capabilities.vision ? ["text", "image"] : ["text"])
-    : undefined;
+    positiveSafeInteger(
+      limits?.max_context_length,
+      item.context_length,
+      item.context_size,
+      item.max_model_len,
+      item.max_context_length,
+    );
+  const maxInputTokens = positiveSafeInteger(limits?.max_input_tokens, item.max_input_tokens);
+  const rawReasoningEfforts = capabilityRecord?.reasoning_effort ?? item.reasoning_efforts;
+  const listedReasoningEfforts = normalizedStringList(rawReasoningEfforts, 8, 24);
+  const reasoningEfforts = listedReasoningEfforts
+    ? sanitizeCodexReasoningEfforts(listedReasoningEfforts)
+    : typeof rawReasoningEfforts === "boolean"
+      ? (rawReasoningEfforts
+        ? ((providerName === "neuralwatt" || providerName === "zai") && isGlm52ModelId(item.id)
+          ? ["low", "medium", "high", "xhigh", "max"]
+          : ["low", "medium", "high", "xhigh"])
+        : [])
+      : undefined;
+  const capabilities = modelCapabilities(item);
+  const inputModalities = modelInputModalities(item, capabilities);
   return {
     ...(contextWindow && contextWindow > 0 ? { contextWindow } : {}),
+    ...(maxInputTokens && maxInputTokens > 0 ? { maxInputTokens } : {}),
     ...(reasoningEfforts !== undefined ? { reasoningEfforts } : {}),
     ...(inputModalities ? { inputModalities } : {}),
+    ...(capabilities ? { capabilities } : {}),
   };
 }
 
+function boundedOwnedBy(value: unknown): string | undefined {
+  if (typeof value !== "string" || value.length === 0 || value.length > 256) return undefined;
+  if (MODEL_DISCOVERY_METADATA_CONTROL_CHARS.test(value)) return undefined;
+  return value;
+}
+
 export async function fetchProviderModels(name: string, prov: OcxProviderConfig, ttlMs: number, contextCap?: number): Promise<CatalogModel[]> {
   if (prov.authMode === "forward") return []; // ChatGPT backend has no /models
   const apiKey = await resolveModelsAuthToken(name, prov);
@@ -299,6 +460,7 @@ export async function fetchProviderModels(name: string, prov: OcxProviderConfig,
     const stale = getStaleCached(name);
     return stale ? withVertexDefaultSeed(applyConfigHintsToCachedModels(name, prov, stale, contextCap)) : failedDiscoveryConfigured;
   }
+  const discovery = resolveProviderModelDiscovery(name, prov);
   const { url, headers } = buildModelsRequest(prov, apiKey, name);
   const urlClass = new URL(url).hostname.endsWith("aiplatform.googleapis.com")
     ? "vertex-aiplatform"
@@ -322,21 +484,20 @@ export async function fetchProviderModels(name: string, prov: OcxProviderConfig,
     };
   };
   try {
-    const destinationError = await providerDestinationResolvedError(name, {
-      baseUrl: url,
-      allowPrivateNetwork: prov.allowPrivateNetwork,
+    const res = await providerOutboundGet(name, prov, url, {
+      headers,
+      signal: AbortSignal.timeout(8000),
     });
-    if (destinationError) {
-      const { models, fallback, shouldLog } = failedDiscoveryFallback({ reason: "blocked" });
+    const redirectError = await providerRedirectError(res, url);
+    if (redirectError) {
+      const { models, fallback, shouldLog } = failedDiscoveryFallback({ reason: "http", httpStatus: res.status });
       if (shouldLog) {
         console.warn(
-          `[opencodex] Provider model discovery for "${name}" was blocked by destination policy: ${destinationError} [urlClass=${urlClass}, fallback=${fallback}].`,
+          `[opencodex] Provider model discovery for "${name}" ${redirectError} [urlClass=${urlClass}, fallback=${fallback}].`,
         );
       }
       return models;
     }
-
-    const res = await fetch(url, { headers, signal: AbortSignal.timeout(8000) });
     if (!res.ok) {
       const { models, fallback, shouldLog } = failedDiscoveryFallback({ reason: "http", httpStatus: res.status });
       if (shouldLog) {
@@ -350,15 +511,14 @@ export async function fetchProviderModels(name: string, prov: OcxProviderConfig,
     const contentType = (
       res.headers.get("content-type")?.split(";", 1)[0]?.trim().toLowerCase() || "missing"
     ).slice(0, 80);
-    const body = await res.text();
-    let json: unknown;
-    try {
-      json = JSON.parse(body) as unknown;
-    } catch {
+    const bounded = await readBoundedDiscoveryJson(res, discovery.maxResponseBytes);
+    if (!bounded.ok) {
       const { models, fallback, shouldLog } = failedDiscoveryFallback({ reason: "invalid_response" });
-      const diagnostic = contentType === "application/json" || contentType.endsWith("+json")
-        ? "returned invalid JSON in a 2xx response"
-        : "returned a non-JSON 2xx response";
+      const diagnostic = bounded.reason === "response_too_large"
+        ? `exceeded the ${discovery.maxResponseBytes}-byte response limit`
+        : contentType === "application/json" || contentType.endsWith("+json")
+          ? "returned invalid JSON in a 2xx response"
+          : "returned a non-JSON 2xx response";
       if (shouldLog) {
         console.warn(
           `[opencodex] Provider model discovery for "${name}" ${diagnostic} [status=${res.status}, contentType=${contentType}, urlClass=${urlClass}, fallback=${fallback}].`,
@@ -366,25 +526,32 @@ export async function fetchProviderModels(name: string, prov: OcxProviderConfig,
       }
       return models;
     }
-    const data = json !== null && typeof json === "object" && !Array.isArray(json)
-      ? (json as { data?: unknown }).data
-      : undefined;
-    if (!isProviderModelsApiItems(data)) {
+    const extracted = extractProviderModelItems(bounded.value, discovery);
+    if (!extracted.ok) {
       const { models, fallback, shouldLog } = failedDiscoveryFallback({ reason: "invalid_response" });
+      const diagnostic: Record<ModelDiscoveryResponseFailure, string> = {
+        response_too_large: "returned an oversized 2xx response",
+        invalid_json: "returned invalid JSON in a 2xx response",
+        invalid_shape: "returned malformed 2xx data",
+        too_many_models: `exceeded the ${discovery.maxModels}-row model limit`,
+      };
       if (shouldLog) {
         console.warn(
-          `[opencodex] Provider model discovery for "${name}" returned malformed 2xx data [status=${res.status}, contentType=${contentType}, urlClass=${urlClass}, fallback=${fallback}].`,
+          `[opencodex] Provider model discovery for "${name}" ${diagnostic[extracted.reason]} [status=${res.status}, contentType=${contentType}, urlClass=${urlClass}, fallback=${fallback}].`,
         );
       }
       return models;
     }
-    const items = data;
-    const live = items.map(m => applyProviderConfigHints(name, prov, {
-      id: m.id,
-      provider: name,
-      owned_by: m.owned_by,
-      ...catalogHintsFromModelsApiItem(name, m),
-    }, contextCap))
+    const items = extracted.items;
+    const live = items.map(m => {
+      const ownedBy = boundedOwnedBy(m.owned_by);
+      return applyProviderConfigHints(name, prov, {
+        id: m.id,
+        provider: name,
+        ...(ownedBy ? { owned_by: ownedBy } : {}),
+        ...catalogHintsFromModelsApiItem(name, m),
+      }, contextCap);
+    })
       .filter(m => shouldExposeProviderModel(name, m.id));
     // Capture the count BEFORE the alias/configured augmentation below pushes extra rows into
     // `live`; otherwise configured entries would be reported as discovered ones.
@@ -421,6 +588,15 @@ export async function fetchProviderModels(name: string, prov: OcxProviderConfig,
     setCached(name, live);
     return live;
   } catch (error) {
+    if (error instanceof ProviderOutboundPolicyError) {
+      const { models, fallback, shouldLog } = failedDiscoveryFallback({ reason: "blocked" });
+      if (shouldLog) {
+        console.warn(
+          `[opencodex] Provider model discovery for "${name}" was blocked by destination policy: ${error.message} [urlClass=${urlClass}, fallback=${fallback}].`,
+        );
+      }
+      return models;
+    }
     const { models, fallback, shouldLog } = failedDiscoveryFallback({ reason: "network" });
     if (shouldLog) {
       console.warn(
@@ -469,7 +645,29 @@ export async function gatherRoutedModels(
   config: OcxConfig,
   options?: { comboOmissions?: ComboCatalogOmission[] },
 ): Promise<CatalogModel[]> {
-  // Per-invocation list: sync passes `comboOmissions` so overlapping gathers cannot race.
+  const key = gatherFlightKey(config);
+  let promise = gatherInflight.get(key);
+  if (!promise) {
+    // Claim the slot synchronously before any await so same-key callers join this flight.
+    // Distinct keys keep their own entries — a second config must not evict the first.
+    const flight = gatherRoutedModelsUncached(config).finally(() => {
+      if (gatherInflight.get(key) === flight) gatherInflight.delete(key);
+    });
+    gatherInflight.set(key, flight);
+    promise = flight;
+  }
+  const { models, comboOmissions } = await promise;
+  if (options?.comboOmissions) {
+    options.comboOmissions.length = 0;
+    options.comboOmissions.push(...comboOmissions);
+  }
+  return models;
+}
+
+async function gatherRoutedModelsUncached(
+  config: OcxConfig,
+): Promise<GatherFlightResult> {
+  // Flight-local list: joiners copy from the resolved promise, not a process-global last write.
   const localOmissions: ComboCatalogOmission[] = [];
   const ttlMs = config.modelCacheTtlMs ?? DEFAULT_MODEL_CACHE_TTL_MS;
   // Persisted provider entries can predate newer registry fields (noVisionModels,
@@ -551,10 +749,6 @@ export async function gatherRoutedModels(
     else warnUncataloguedComboOnce(id, combo, members, localOmissions);
   }
   replaceLastComboCatalogOmissions(localOmissions);
-  if (options?.comboOmissions) {
-    options.comboOmissions.length = 0;
-    options.comboOmissions.push(...localOmissions);
-  }
   all.sort((a, b) => (a.provider === b.provider ? a.id.localeCompare(b.id) : a.provider.localeCompare(b.provider)));
   // Enriched (registry-hydrated) provider clones, keyed by name — the same view used above so
   // custom rows get the same noVisionModels / inputModalities treatment as discovered rows.
@@ -588,7 +782,7 @@ export async function gatherRoutedModels(
   // Custom rows override discovered rows that encode to the same Codex-facing slug.
   const customKeys = new Set(customModels.map(c => routedSlug(c.provider, c.id)));
   const deduped = all.filter(m => !customKeys.has(routedSlug(m.provider, m.id)));
-  return [...deduped, ...customModels];
+  return { models: [...deduped, ...customModels], comboOmissions: localOmissions };
 }
 
 export function augmentRoutedModelsWithRegistryOpenAiApiRows(
@@ -596,7 +790,7 @@ export function augmentRoutedModelsWithRegistryOpenAiApiRows(
   config: OcxConfig,
 ): CatalogModel[] {
   const configured = config.providers[OPENAI_API_PROVIDER_ID];
-  if (!configured || configured.disabled === true) return models;
+  if (!configured || configured.disabled === true || !providerMatchesRegistryTransport(OPENAI_API_PROVIDER_ID, configured)) return models;
   const entry = getProviderRegistryEntry(OPENAI_API_PROVIDER_ID);
   if (!entry?.models) return models;
 

package/src/codex/catalog/sync.ts

@@ -35,8 +35,9 @@ import { activeCodexModelsCachePath, applyJawcodeCatalogMetadata, applyMultiAgen
 import type { CatalogModel, MultiAgentMode, RawEntry } from "./parsing";
 import { applyNativeVisibility, disabledNativeSlugs, isUnsupportedOpenAiNativeSlug, nativeOpenAiSlugs, shouldUpgradeToUpstreamEntry, upstreamNativeEntry } from "./metadata";
 import { loadCatalogForSync, resetBundledCatalogCacheForTests } from "./bundled";
+import { isMultiAgentV2Enabled } from "../features";
 import { applyCatalogModelMetadata, applyReasoningLevels, catalogEntryEfforts, clampCatalogModelsToCodexSupport, ensureGpt56ReasoningLevels, ensureUltraReasoningLevel, isGpt56NativeSlug } from "./effort";
-import { filterCatalogVisibleModels, gatherRoutedModels, lastDropWarnSignature } from "./provider-fetch";
+import { clearGatherRoutedModelsInflight, filterCatalogVisibleModels, gatherRoutedModels, lastDropWarnSignature } from "./provider-fetch";
 import { clearLastComboCatalogOmissions, comboCatalogWarningSignatures, comboMasqueradeCollisionWarnings, exactComboCatalogSlugs, openAiApiCollisionWarnings, resolveSlugAliasCollisions, slugAliasCollisionWarnings, warnComboMasqueradeCollisionOnce } from "./aggregation";
 import type { ComboCatalogOmission } from "./aggregation";
 
@@ -50,6 +51,26 @@ export type SubagentRosterExclusionReason =
   | "surface_incompatible"
   | "outside_display_limit";
 
+/**
+ * Whether a catalog entry may be offered as a V2 subagent model.
+ *
+ * Upstream (codex-rs 92938d880) requires `multi_agent_version === "v2"` exactly,
+ * because upstream assumes a single backend serves every model. opencodex routes
+ * many providers, so that equality would reject the cross-provider spawns this
+ * proxy exists to enable.
+ *
+ * Decision (option B, devlog 260730_codex_rs_upstream_v2_live_handoff/060): any
+ * model opencodex actually routes is eligible. An entry pinned to a DIFFERENT
+ * multi-agent backend (`v1`) stays excluded, because that pin is a real capability
+ * statement rather than an absence of information. An unpinned entry (null or
+ * absent) is a routed or unpinned-native model and is allowed. The three-way
+ * distinction is the substance; do not flatten it into a truthiness check.
+ */
+export function isEligibleV2SubagentEntry(entry: RawEntry): boolean {
+  const pinned = entry.multi_agent_version;
+  return pinned === "v2" || pinned === null || pinned === undefined;
+}
+
 export interface EffectiveSubagentModel {
   model: string;
   efforts: string[];
@@ -86,7 +107,7 @@ export function effectiveSubagentRoster(
     .map((entry, index) => ({ entry, index }))
     .filter(({ entry }) => typeof entry.slug === "string")
     .filter(({ entry }) => entry.visibility === "list")
-    .filter(({ entry }) => surface !== "v2" || entry.multi_agent_version === "v2")
+    .filter(({ entry }) => surface !== "v2" || isEligibleV2SubagentEntry(entry))
     .sort((left, right) => {
       const leftPriority = typeof left.entry.priority === "number" && Number.isFinite(left.entry.priority)
         ? left.entry.priority : Number.MAX_SAFE_INTEGER;
@@ -110,7 +131,7 @@ export function effectiveSubagentRoster(
     if (entry.visibility !== "list") {
       return [{ configured: model, catalogModel, reason: "picker_hidden" }];
     }
-    if (surface === "v2" && entry.multi_agent_version !== "v2") {
+    if (surface === "v2" && !isEligibleV2SubagentEntry(entry)) {
       return [{ configured: model, catalogModel, reason: "surface_incompatible" }];
     }
     if (!candidates.some(candidate => candidate.model === catalogModel)) {
@@ -284,7 +305,7 @@ export function buildCatalogEntries(
       delete entry.prefer_websockets;
     }
   }
-  return applyMultiAgentMode(out, multiAgentMode);
+  return applyMultiAgentMode(out, multiAgentMode, isMultiAgentV2Enabled());
 }
 
 export function resetCatalogRuntimeStateForTests(): void {
@@ -296,6 +317,7 @@ export function resetCatalogRuntimeStateForTests(): void {
   comboMasqueradeCollisionWarnings.clear();
   clearLastComboCatalogOmissions();
   clearModelCache();
+  clearGatherRoutedModelsInflight();
 }
 
 export function orderForSubagents(goModels: CatalogModel[], featured?: string[]): CatalogModel[] {
@@ -329,9 +351,11 @@ export function mergeCatalogEntriesForSync(
   multiAgentMode: MultiAgentMode = "default",
   exactComboSlugs: ReadonlySet<string> = new Set(),
   hasPhysicalComboProvider = false,
+  includeNativeOpenAi = true,
 ): RawEntry[] {
   const rank = new Map(featured.map((slug, i) => [slug, i] as const));
-  const native = catalogModels
+  const native = includeNativeOpenAi
+    ? catalogModels
     .filter(m => typeof m.slug === "string"
       && !(m.slug as string).includes("/")
       && m.owned_by !== COMBO_NAMESPACE
@@ -367,11 +391,14 @@ export function mergeCatalogEntriesForSync(
       // for subagent max spawns; wire-clamped to the model's real top rung).
       if (!isGpt56NativeSlug(slug)) ensureUltraReasoningLevel(preserved);
       return preserved;
-    });
+    })
+    : [];
 
   // Backfill any native OpenAI slug that the on-disk catalog is missing (e.g. gpt-5.5), so a
   // routed provider exposing the same id can never delete the native OpenAI/Codex base row.
+  // Skip when no enabled canonical openai provider exists (#636) — bare gpt-* would 404.
   const nativeSlugs = new Set(native.flatMap(m => typeof m.slug === "string" ? [m.slug] : []));
+  if (includeNativeOpenAi) {
   for (const slug of nativeOpenAiSlugs()) {
     if (nativeSlugs.has(slug)) continue;
     nativeSlugs.add(slug);
@@ -382,6 +409,7 @@ export function mergeCatalogEntriesForSync(
         : 9;
     native.push(deriveEntry(template ? JSON.parse(JSON.stringify(template)) : null, slug, "OpenAI native model (Codex OAuth passthrough).", priority));
   }
+  }
 
   const freshSlugs = new Set(
     routedEntries.flatMap(entry => typeof entry.slug === "string" ? [entry.slug] : []),
@@ -451,7 +479,7 @@ export function mergeCatalogEntriesForSync(
   });
   // Native enable/disable (single choke point: bare slugs in `disabledModels`). Runs as the
   // LAST pass so the upstream-upgrade branch above can never clobber a hide flag back to list.
-  return applyMultiAgentMode(applyNativeVisibility(mergedEntries, disabledNative), multiAgentMode);
+  return applyMultiAgentMode(applyNativeVisibility(mergedEntries, disabledNative), multiAgentMode, isMultiAgentV2Enabled());
 }
 
 export async function syncCatalogModels(config: OcxConfig): Promise<{
@@ -497,7 +525,16 @@ export async function syncCatalogModels(config: OcxConfig): Promise<{
   // native AND routed so the advertised flag matches the implemented endpoint (phase 120.4) and a
   // native template can never leak supports_websockets while the flag is off.
   const wsEnabled = websocketsEnabled(config);
-  catalog.models = mergeCatalogEntriesForSync(catalog.models ?? [], goEntries, baseline, featured, wsEnabled, goIds, template, disabledNativeSlugs(config), gatheredProviderNames, multiAgentMode, exactComboSlugs, hasPhysicalComboProvider);
+  const enabledProviders = Object.entries(config.providers ?? {})
+    .filter(([, prov]) => prov.disabled !== true);
+  const hasCanonicalOpenai = enabledProviders.some(([name, prov]) =>
+    name === "openai" && isCanonicalOpenAiForwardProvider(prov),
+  );
+  // #636: when the user only configured non-OpenAI providers (e.g. kimi), do not advertise
+  // bare gpt-* rows that hard-404 via NoEnabledOpenAiProviderError. Keep natives when no
+  // providers are configured yet (fresh install / catalog bootstrap tests).
+  const includeNativeOpenAi = enabledProviders.length === 0 || hasCanonicalOpenai;
+  catalog.models = mergeCatalogEntriesForSync(catalog.models ?? [], goEntries, baseline, featured, wsEnabled, goIds, template, disabledNativeSlugs(config), gatheredProviderNames, multiAgentMode, exactComboSlugs, hasPhysicalComboProvider, includeNativeOpenAi);
   clampCatalogModelsToCodexSupport(catalog.models);
 
   atomicWriteFile(catalogPath, JSON.stringify(catalog, null, 2) + "\n");

package/src/codex/catalog.ts

@@ -1,11 +1,11 @@
 // AUTO-SPLIT facade: original catalog.ts body moved into ./catalog/* modules.
 // Public surface preserved exactly; importers keep using "src/codex/catalog".
-export { isMediaGenerationModelId, readCodexCatalogPath, normalizeRoutedCatalogEntry, catalogModelSlug, filterSupportedNativeSlugs, catalogModelSupportsReasoningSummaries } from "./catalog/parsing";
+export { isMediaGenerationModelId, shouldExposeRoutedModel, readCodexCatalogPath, normalizeRoutedCatalogEntry, catalogModelSlug, filterSupportedNativeSlugs, catalogModelSupportsReasoningSummaries } from "./catalog/parsing";
 export type { CatalogModel, MultiAgentMode } from "./catalog/parsing";
 export { NATIVE_OPENAI_MODELS, nativeOpenAiContextWindow, disabledNativeSlugs, visibleNativeSlugs, nativeModelRows, applyNativeVisibility, upstreamNativeEntry, nativeOpenAiSlugs, listCatalogNativeSlugs } from "./catalog/metadata";
 export { isSpawnableCodexCandidate, codexExecInvocation, loadBundledCodexCatalog, materializeBundledCodexCatalog, loadCatalogTemplate } from "./catalog/bundled";
 export { nativeEffortClamp, shouldApplyNativeEffortClamp, catalogModelEfforts, codexSupportedReasoningEfforts, clampedDefaultEffort, clampEntryToCodexSupportedEfforts, clampCatalogModelsToCodexSupport } from "./catalog/effort";
-export { applyProviderConfigHints, isDatedVariantId, filterCatalogVisibleModels, gatherRoutedModels, augmentRoutedModelsWithRegistryOpenAiApiRows, augmentRoutedModelsWithJawcodeMetadata } from "./catalog/provider-fetch";
+export { applyProviderConfigHints, isDatedVariantId, filterCatalogVisibleModels, gatherRoutedModels, clearGatherRoutedModelsInflight, augmentRoutedModelsWithRegistryOpenAiApiRows, augmentRoutedModelsWithJawcodeMetadata } from "./catalog/provider-fetch";
 export { deriveComboCatalogModel, exactComboCatalogSlugs, getLastComboCatalogOmissions, resetOpenAiApiCatalogWarningStateForTests, uniqueCatalogModelsForPublicList, uniqueCatalogModelsForRawPublicList, buildComboCatalogOmission, comboCatalogOmissionReason, summarizeComboCatalogOmissions } from "./catalog/aggregation";
 export type { ComboCatalogOmission, ComboCatalogOmissionReason } from "./catalog/aggregation";
 export { MAX_SPAWN_AGENT_MODEL_OVERRIDES, effectiveSubagentRoster, buildCatalogEntries, resetCatalogRuntimeStateForTests, orderForSubagents, mergeCatalogEntriesForSync, syncCatalogModels, restoreCodexCatalog, invalidateCodexModelsCache } from "./catalog/sync";