@bitkyc08/opencodex 2.7.33 → 2.7.34

package/src/codex/catalog.ts

@@ -13,11 +13,11 @@ import { getJawcodeModelMetadata, getJawcodeModelMetadataCaseInsensitive, listJa
 import { enrichProviderFromRegistry, shouldCaseFoldMetadataModelId } from "../providers/derive";
 import { getProviderRegistryEntry } from "../providers/registry";
 import { applyProviderContextCap, providerContextCap } from "../providers/context-cap";
-import { encodeRoutedModelId, routedSlug, slugEquals, slugsEquivalent } from "../providers/slug-codec";
+import { routedSlug, slugEquals, slugsEquivalent } from "../providers/slug-codec";
 import { CODEX_GPT5_IDENTITY_LINE } from "../adapters/identity";
 import { filterCursorConfiguredModelsByLiveDiscovery } from "../adapters/cursor/discovery";
 import { fetchCursorUsableModels } from "../adapters/cursor/live-models";
-import { OPENAI_API_PROVIDER_ID } from "../providers/openai-tiers";
+import { isCanonicalOpenAiForwardProvider, OPENAI_API_PROVIDER_ID, OPENAI_CODEX_PROVIDER_ID } from "../providers/openai-tiers";
 import {
   COMBO_NAMESPACE,
   comboModelId,
@@ -26,6 +26,7 @@ import {
   targetKey,
 } from "../combos";
 import type { NormalizedComboConfig } from "../combos/types";
+import { providerDestinationResolvedError } from "../lib/destination-policy";
 import { redactSecretString } from "../lib/redact";
 import upstreamModelsSnapshot from "./data/upstream-models.json";
 
@@ -138,6 +139,54 @@ export function nativeOpenAiContextWindow(slug: string): number | undefined {
       : undefined);
 }
 
+/* ── Native-slug capability helpers for combo member resolution (issue #268) ── */
+
+/** Input modalities for a native OpenAI slug, defaulting to the GPT family baseline. */
+function nativeInputModalities(slug: string): string[] {
+  const upstream = UPSTREAM_NATIVE_ENTRIES.get(slug);
+  if (Array.isArray(upstream?.input_modalities) && upstream!.input_modalities!.length > 0) {
+    return [...upstream!.input_modalities as string[]];
+  }
+  // gpt-5.3-codex-spark is not in the upstream snapshot; all supported natives are
+  // text+image capable, so default to the family baseline rather than text-only.
+  return ["text", "image"];
+}
+
+/** Reasoning effort ladder for a native OpenAI slug, mirroring the catalog emission path. */
+function nativeReasoningEfforts(slug: string): string[] {
+  const upstream = UPSTREAM_NATIVE_ENTRIES.get(slug);
+  const levels = Array.isArray(upstream?.supported_reasoning_levels)
+    ? upstream!.supported_reasoning_levels as Array<{ effort?: string }>
+    : [];
+  if (levels.length > 0) {
+    const efforts = levels.flatMap(l => typeof l.effort === "string" ? [l.effort] : []);
+    // gpt-5.6 natives get max+ultra restored (ensureGpt56ReasoningLevels catalog path does
+    // the same); older natives (gpt-5.5/5.4/5.4-mini/5.3-codex-spark) stop at xhigh per
+    // upstream snapshot.
+    if (isGpt56NativeSlug(slug)) {
+      const set = new Set(efforts);
+      for (const e of ["max", "ultra"]) set.add(e);
+      return [...set];
+    }
+    return efforts;
+  }
+  // gpt-5.3-codex-spark is not in upstream snapshot — use the standard old-ladder default.
+  return ["low", "medium", "high", "xhigh"];
+}
+
+/** Whether a native OpenAI slug supports parallel tool calls (per upstream snapshot). */
+function nativeParallelToolCalls(slug: string): boolean {
+  return UPSTREAM_NATIVE_ENTRIES.get(slug)?.supports_parallel_tool_calls === true
+    || false;
+}
+
+/** Quick check whether the config has any combo targets at all. */
+function hasComboTargets(config: { combos?: Record<string, { targets?: unknown[] }> }): boolean {
+  const combos = config.combos;
+  if (!combos) return false;
+  return Object.values(combos).some(c => Array.isArray(c?.targets) && c!.targets!.length > 0);
+}
+
 /**
  * Bare (slash-free) entries of `disabledModels` — the native GPT half of the single
  * enable/disable choke point. Routed ids are always namespaced `provider/id`, so bare
@@ -252,6 +301,22 @@ export function nativeEffortClamp(slug: string, effort: string | undefined): str
   return highest ?? null;
 }
 
+/**
+ * Request-time guard for `nativeEffortClamp`: only the canonical built-in OpenAI/Codex
+ * forward provider should ever use the native mock-max repair. Bare third-party
+ * `defaultModel` selectors are still routed models whose adapters own effort mapping,
+ * and explicit `provider/model` requests are routed by construction.
+ */
+export function shouldApplyNativeEffortClamp(
+  providerName: string,
+  provider: OcxProviderConfig,
+  requestedModelId: string,
+): boolean {
+  return !requestedModelId.includes("/")
+    && providerName === OPENAI_CODEX_PROVIDER_ID
+    && isCanonicalOpenAiForwardProvider(provider);
+}
+
 /**
  * True when a preserved catalog entry for a snapshot-covered slug should be UPGRADED to the
  * pinned upstream entry. Discriminator: `display_name === slug` — both ocx synthesis and the
@@ -292,6 +357,100 @@ export function catalogModelEfforts(slugs: readonly string[]): Map<string, strin
   return out;
 }
 
+export const MAX_SPAWN_AGENT_MODEL_OVERRIDES = 5;
+
+export type SpawnAgentSurface = "v1" | "v2";
+export type SubagentRosterExclusionReason =
+  | "missing_catalog_entry"
+  | "picker_hidden"
+  | "surface_incompatible"
+  | "outside_display_limit";
+
+export interface EffectiveSubagentModel {
+  model: string;
+  efforts: string[];
+}
+
+export interface SubagentRosterExclusion {
+  configured: string;
+  reason: SubagentRosterExclusionReason;
+  catalogModel?: string;
+}
+
+export interface EffectiveSubagentRoster {
+  candidates: EffectiveSubagentModel[];
+  advertised: EffectiveSubagentModel[];
+  excluded: SubagentRosterExclusion[];
+}
+
+function catalogEntryEfforts(entry: RawEntry): string[] {
+  const levels = Array.isArray(entry.supported_reasoning_levels)
+    ? entry.supported_reasoning_levels as Array<{ effort?: string }>
+    : [];
+  return levels.flatMap(level => typeof level.effort === "string" ? [level.effort] : []);
+}
+
+function configuredCatalogEntry(entries: RawEntry[], configured: string): RawEntry | undefined {
+  return entries.find(entry => entry.slug === configured)
+    ?? entries.find(entry => typeof entry.slug === "string" && slugsEquivalent(configured, entry.slug));
+}
+
+/**
+ * The effective sub-agent roster for a collaboration surface: Codex's picker-visible
+ * (`visibility === "list"`), surface-compatible, priority-sorted first five catalog
+ * entries (candidates), intersected with the configured subagentModels (advertised),
+ * plus a reason for every configured entry that did not make the set (excluded).
+ * Canonical `entry.slug` is returned; legacy raw aliases are matching inputs only.
+ */
+export function effectiveSubagentRoster(
+  configuredModels: readonly string[],
+  surface: SpawnAgentSurface,
+): EffectiveSubagentRoster {
+  const configured = configuredModels
+    .filter(model => model.trim().length > 0)
+    .filter((model, index, all) =>
+      !all.slice(0, index).some(previous => slugsEquivalent(previous, model))
+    );
+  const entries = readCatalog(readCodexCatalogPath())?.models ?? [];
+  const ordered = entries
+    .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")
+    .sort((left, right) => {
+      const leftPriority = typeof left.entry.priority === "number" && Number.isFinite(left.entry.priority)
+        ? left.entry.priority : Number.MAX_SAFE_INTEGER;
+      const rightPriority = typeof right.entry.priority === "number" && Number.isFinite(right.entry.priority)
+        ? right.entry.priority : Number.MAX_SAFE_INTEGER;
+      return leftPriority - rightPriority || left.index - right.index;
+    })
+    .slice(0, MAX_SPAWN_AGENT_MODEL_OVERRIDES);
+
+  const candidates = ordered.map(({ entry }) => ({
+    model: entry.slug as string,
+    efforts: catalogEntryEfforts(entry),
+  }));
+  const advertised = candidates.filter(candidate =>
+    configured.some(model => slugsEquivalent(model, candidate.model))
+  );
+  const excluded = configured.flatMap((model): SubagentRosterExclusion[] => {
+    const entry = configuredCatalogEntry(entries, model);
+    if (!entry) return [{ configured: model, reason: "missing_catalog_entry" }];
+    const catalogModel = entry.slug as string;
+    if (entry.visibility !== "list") {
+      return [{ configured: model, catalogModel, reason: "picker_hidden" }];
+    }
+    if (surface === "v2" && entry.multi_agent_version !== "v2") {
+      return [{ configured: model, catalogModel, reason: "surface_incompatible" }];
+    }
+    if (!candidates.some(candidate => candidate.model === catalogModel)) {
+      return [{ configured: model, catalogModel, reason: "outside_display_limit" }];
+    }
+    return [];
+  });
+  return { candidates, advertised, excluded };
+}
+
 /**
  * The native (passthrough) OpenAI slugs to advertise — the LIVE Codex catalog's own bare slugs when
  * available, with documented Codex-native additions layered in, else the static fallback above.
@@ -305,6 +464,8 @@ export function nativeOpenAiSlugs(): string[] {
 export interface CatalogModel {
   id: string;
   provider: string;
+  /** Public Codex-facing slug override (used by combo aliases). */
+  alias?: string;
   owned_by?: string;
   reasoningEfforts?: string[];
   defaultReasoningEffort?: string;
@@ -315,6 +476,8 @@ export interface CatalogModel {
   inputModalities?: string[];
   /** Provider opted into parallel tool calls (OcxProviderConfig.parallelToolCalls). */
   parallelToolCalls?: boolean;
+  /** Whether Codex may send Responses text.verbosity for this routed model. */
+  supportsVerbosity?: boolean;
 }
 
 type RawEntry = Record<string, unknown>;
@@ -443,7 +606,7 @@ function applyNativeOpenAiContextOverride(entry: RawEntry): void {
 
 function ensureStrictCatalogFields(
   entry: RawEntry,
-  options: { preserveExactInputModalities?: boolean } = {},
+  options: { preserveExactInputModalities?: boolean; isRouted?: boolean } = {},
 ): RawEntry {
   if (typeof entry.supports_reasoning_summaries !== "boolean") entry.supports_reasoning_summaries = true;
   if (typeof entry.default_reasoning_summary !== "string") entry.default_reasoning_summary = "none";
@@ -464,7 +627,7 @@ function ensureStrictCatalogFields(
   if (
     typeof entry.max_context_window !== "number"
     || entry.max_context_window <= 0
-    || (!isNativeOpenAiEntry(entry) && entry.max_context_window > contextWindow)
+    || ((options.isRouted === true || !isNativeOpenAiEntry(entry)) && entry.max_context_window > contextWindow)
   ) {
     entry.max_context_window = contextWindow;
   }
@@ -534,7 +697,7 @@ export function normalizeRoutedCatalogEntry(entry: RawEntry, parallelToolCalls =
   // openai-chat adapter stops forcing parallel_tool_calls:false and the buffered stream parser
   // assembles multi-call turns (devlog/_plan/260709_parallel_tool_calls).
   entry.supports_parallel_tool_calls = isCursorEntry || parallelToolCalls === true;
-  return ensureStrictCatalogFields(entry);
+  return ensureStrictCatalogFields(entry, { isRouted: true });
 }
 
 // provider + NATIVE model id are passed separately: the Codex-facing slug may carry an
@@ -732,6 +895,9 @@ const ROUTED_REASONING_LEVELS = [...CODEX_REASONING_LEVELS];
 
 function applyCatalogModelMetadata(entry: RawEntry, model?: CatalogModel): void {
   if (!model) return;
+  // This marker survives strict catalog normalization and lets sync distinguish a stale
+  // bare combo alias from a genuine native model row.
+  if (model.provider === COMBO_NAMESPACE) entry.owned_by = model.owned_by ?? COMBO_NAMESPACE;
   if (typeof model.contextWindow === "number" && model.contextWindow > 0) {
     entry.context_window = model.contextWindow;
     entry.max_context_window = model.contextWindow;
@@ -743,6 +909,9 @@ function applyCatalogModelMetadata(entry: RawEntry, model?: CatalogModel): void
   if (Array.isArray(model.inputModalities) && model.inputModalities.length > 0) {
     entry.input_modalities = model.inputModalities;
   }
+  if (typeof model.supportsVerbosity === "boolean") {
+    entry.support_verbosity = model.supportsVerbosity;
+  }
 }
 
 function applyReasoningLevels(
@@ -910,7 +1079,11 @@ function isExactComboCatalogModel(
   model: CatalogModel | undefined,
   exactComboSlugs: ReadonlySet<string>,
 ): boolean {
-  return model !== undefined && exactComboSlugs.has(`${model.provider}/${model.id}`);
+  return model !== undefined && exactComboSlugs.has(catalogModelSlug(model));
+}
+
+export function catalogModelSlug(model: CatalogModel): string {
+  return model.alias ?? routedSlug(model.provider, model.id);
 }
 
 function deriveEntry(
@@ -922,7 +1095,8 @@ function deriveEntry(
   exactComboSlugs: ReadonlySet<string> = new Set(),
 ): RawEntry {
   const preserveExact = isExactComboCatalogModel(model, exactComboSlugs);
-  if (!slug.includes("/")) {
+  const isRouted = model !== undefined;
+  if (!isRouted && !slug.includes("/")) {
     // Supported native slug covered by the upstream snapshot: use the REAL entry (exact
     // reasoning ladder — e.g. luna has no ultra — default effort, identity, model_messages)
     // instead of cloning an older template.
@@ -940,7 +1114,7 @@ function deriveEntry(
     delete e.availability_nux; // don't replay another model's "now available" NUX
     // Routed (namespaced) models inherit the gpt template — correct its OpenAI/GPT identity
     // and advertise the reasoning ladder Codex accepts.
-    if (slug.includes("/")) {
+    if (isRouted) {
       // Native id for identity text + metadata lookups — the slug may be an encoded
       // alias (`provider/vendor-model`); the model object carries the native id.
       const modelName = model?.id ?? slug.slice(slug.indexOf("/") + 1);
@@ -974,6 +1148,7 @@ function deriveEntry(
     }
     return ensureStrictCatalogFields(normalizeServiceTiers(e), {
       preserveExactInputModalities: preserveExact,
+      isRouted,
     });
   }
   // Fallback when no template is available (best-effort; strict parser may need more).
@@ -981,20 +1156,21 @@ function deriveEntry(
     slug, display_name: slug, description: desc,
     shell_type: "shell_command", visibility: "list", supported_in_api: true,
     priority, base_instructions: "You are a helpful coding assistant.",
-    ...(slug.includes("/") ? { web_search_tool_type: "text_and_image", supports_search_tool: true } : {}),
+    ...(isRouted ? { web_search_tool_type: "text_and_image", supports_search_tool: true } : {}),
   };
-  if (slug.includes("/")) {
+  if (isRouted) {
     applyReasoningLevels(entry, model?.reasoningEfforts, model?.defaultReasoningEffort, preserveExact);
   }
   else {
     applyReasoningLevels(entry, isGpt56NativeSlug(slug) ? undefined : ["low", "medium", "high", "xhigh"]);
     if (isGpt56NativeSlug(slug)) ensureGpt56ReasoningLevels(entry);
   }
-  if (model && slug.includes("/")) applyJawcodeCatalogMetadata(entry, model.provider, model.id, model.contextCap);
+  if (model && isRouted) applyJawcodeCatalogMetadata(entry, model.provider, model.id, model.contextCap);
   applyCatalogModelMetadata(entry, model);
-  applyNativeOpenAiContextOverride(entry);
+  if (!isRouted) applyNativeOpenAiContextOverride(entry);
   return ensureStrictCatalogFields(normalizeServiceTiers(entry), {
     preserveExactInputModalities: preserveExact,
+    isRouted,
   });
 }
 
@@ -1019,6 +1195,9 @@ export function buildCatalogEntries(
   const rank = new Map((featured ?? []).map((slug, i) => [slug, i] as const));
   const out: RawEntry[] = [];
   const collisionSkipped = resolveSlugAliasCollisions(goModels);
+  const comboPublicSlugs = new Set(goModels
+    .filter(model => model.provider === COMBO_NAMESPACE)
+    .map(catalogModelSlug));
   for (const slug of gptSlugs) {
     const e = deriveEntry(template, slug, "OpenAI native model (Codex OAuth passthrough).", 9);
     if (rank.has(slug)) e.priority = rank.get(slug)!;
@@ -1026,9 +1205,13 @@ export function buildCatalogEntries(
   }
   for (const m of goModels) {
     if (collisionSkipped.has(m)) continue;
-    // Codex-facing slug: exactly one "/" (slug-codec). Codex's models-manager metadata
-    // lookup rejects remainders containing "/", so native slash ids are aliased with "_".
-    const slug = routedSlug(m.provider, m.id);
+    const slug = catalogModelSlug(m);
+    if (m.provider !== COMBO_NAMESPACE && comboPublicSlugs.has(slug)) {
+      warnComboMasqueradeCollisionOnce(slug);
+      continue;
+    }
+    // Provider rows use the one-slash slug codec; combo aliases intentionally override that
+    // public slug and may be bare.
     const e = deriveEntry(
       template,
       slug,
@@ -1193,6 +1376,7 @@ export function applyProviderConfigHints(name: string, prov: OcxProviderConfig,
       }
       : {}),
     ...(defaultReasoningEffort ? { defaultReasoningEffort } : {}),
+    ...(prov.adapter === "kiro" ? { supportsVerbosity: false } : {}),
     // Default-on for openai-chat providers (explicit false opts out); other adapters
     // advertise only on explicit opt-in.
     ...(prov.parallelToolCalls === true || (prov.adapter === "openai-chat" && prov.parallelToolCalls !== false)
@@ -1358,28 +1542,64 @@ async function fetchProviderModels(name: string, prov: OcxProviderConfig, ttlMs:
   const urlClass = new URL(url).hostname.endsWith("aiplatform.googleapis.com")
     ? "vertex-aiplatform"
     : "provider-models";
+  const failedDiscoveryFallback = (): { models: CatalogModel[]; fallback: "stale" | "configured" } => {
+    markModelsFetchFailure(name);
+    const stale = getStaleCached(name);
+    return {
+      models: stale
+        ? withVertexDefaultSeed(applyConfigHintsToCachedModels(name, prov, stale, contextCap))
+        : configured,
+      fallback: stale ? "stale" : "configured",
+    };
+  };
   try {
+    const destinationError = await providerDestinationResolvedError(name, {
+      baseUrl: url,
+      allowPrivateNetwork: prov.allowPrivateNetwork,
+    });
+    if (destinationError) {
+      const { models, fallback } = failedDiscoveryFallback();
+      console.warn(
+        `[opencodex] Provider model discovery for "${name}" was blocked by destination policy: ${destinationError} [urlClass=${urlClass}, fallback=${fallback}].`,
+      );
+      return models;
+    }
+
     const res = await fetch(url, { headers, signal: AbortSignal.timeout(8000) });
     if (!res.ok) {
-      markModelsFetchFailure(name);
-      const stale = getStaleCached(name);
-      const fallback = stale ? "stale" : "configured";
+      const { models, fallback } = failedDiscoveryFallback();
       console.warn(
         `[opencodex] Provider model discovery for "${name}" failed with HTTP ${res.status} [urlClass=${urlClass}, fallback=${fallback}].`,
       );
-      return stale ? withVertexDefaultSeed(applyConfigHintsToCachedModels(name, prov, stale, contextCap)) : configured;
+      return models;
+    }
+
+    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 { models, fallback } = failedDiscoveryFallback();
+      const diagnostic = contentType === "application/json" || contentType.endsWith("+json")
+        ? "returned invalid JSON in a 2xx response"
+        : "returned a non-JSON 2xx response";
+      console.warn(
+        `[opencodex] Provider model discovery for "${name}" ${diagnostic} [status=${res.status}, contentType=${contentType}, urlClass=${urlClass}, fallback=${fallback}].`,
+      );
+      return models;
     }
-    const json = await res.json() as unknown;
     const data = json !== null && typeof json === "object" && !Array.isArray(json)
       ? (json as { data?: unknown }).data
       : undefined;
     if (!isProviderModelsApiItems(data)) {
-      markModelsFetchFailure(name);
+      const { models, fallback } = failedDiscoveryFallback();
       console.warn(
-        `[opencodex] Provider model discovery for "${name}" returned malformed 2xx data; using stale/static catalog degradation.`,
+        `[opencodex] Provider model discovery for "${name}" returned malformed 2xx data [status=${res.status}, contentType=${contentType}, urlClass=${urlClass}, fallback=${fallback}].`,
       );
-      const stale = getStaleCached(name);
-      return stale ? withVertexDefaultSeed(applyConfigHintsToCachedModels(name, prov, stale, contextCap)) : configured;
+      return models;
     }
     const items = data;
     const live = items.map(m => applyProviderConfigHints(name, prov, {
@@ -1420,13 +1640,11 @@ async function fetchProviderModels(name: string, prov: OcxProviderConfig, ttlMs:
     setCached(name, live);
     return live;
   } catch (error) {
-    markModelsFetchFailure(name);
-    const stale = getStaleCached(name);
-    const fallback = stale ? "stale" : "configured";
+    const { models, fallback } = failedDiscoveryFallback();
     console.warn(
       `[opencodex] Provider model discovery for "${name}" threw ${error instanceof Error ? error.name : "unknown"} [urlClass=${urlClass}, fallback=${fallback}].`,
     );
-    return stale ? withVertexDefaultSeed(applyConfigHintsToCachedModels(name, prov, stale, contextCap)) : configured;
+    return models;
   }
 }
 
@@ -1461,6 +1679,9 @@ export function filterCatalogVisibleModels(
   return models.filter(m => {
     // disabledModels may be stored raw (canonical) or encoded (legacy UI writes).
     for (const stored of disabled) {
+      // Combo management stores the public alias, while canonical `combo/<id>` references
+      // remain valid for backward compatibility through slugEquals below.
+      if (m.alias !== undefined && stored === catalogModelSlug(m)) return false;
       if (slugEquals(stored, m.provider, m.id)) return false;
     }
     const allow = allowByProvider.get(m.provider);
@@ -1499,6 +1720,51 @@ export async function gatherRoutedModels(config: OcxConfig): Promise<CatalogMode
     // exposure decision goes through shouldExposeRoutedModel (single choke point).
     .filter(shouldExposeRoutedModel);
   const memberByKey = new Map(all.map(model => [`${model.provider}/${model.id}`, model]));
+  // [Decision Log]
+  // - 목적과 의도: 콤보 타겟에 native OpenAI(Codex login) 모델이 포함될 때 카탈로그에서
+  //   누락되는 버그(issue #268)를 수정. "openai" provider는 forward-auth(Codex login
+  //   passthrough)이므로 fetchProviderModels가 항상 []를 반환하고, native slugs는
+  //   별도 정적 경로(nativeOpenAiSlugs)로만 노출됨. 따라서 memberByKey에
+  //   openai/<slug> 키가 존재하지 않아 콤보가 조용히 drop됨.
+  // - 기존 구현 및 제약 조건: memberByKey는 routed provider /models fetch 결과로만 구성.
+  // - 검토한 주요 대안: (A) native slugs를 all 배열에 직접 push — /v1/models와 온디스크
+  //   카탈로그에서 native 모델이 중복 노출되는 부작용 발생. (B) memberByKey에만 synthetic
+  //   CatalogModel을 주입 — 콤보 멤버 해석에만 사용하고 all에는 추가하지 않으므로 기존
+  //   노출 경로에 영향 없음.
+  // - 선택한 방식: (B) — synthetic entries를 memberByKey에만 주입.
+  // - 다른 대안 대신 이 방식을 선택한 이유: 기존 native 모델 노출 경로(/v1/models, 온디스크
+  //   카탈로그 sync, management API)를 전혀 변경하지 않고 콤보 resolution만 수선하기 때문.
+  // - 장점, 단점 및 영향: 장점 — 최소 수정, 기존 경로 무변경. 단점 — synthetic entries의
+  //   capability 데이터가 static/upstream snapshot 기반이므로, 사용자가 커스텀 config
+  //   힌트(modelContextWindows 등)로 native 모델의 context window를 오버라이드한 경우
+  //   반영되지 않음. 하지만 nativeOpenAiContextWindow가 이미 config 오버라이드를
+  //   우선시하므로 실제 충돌 가능성은 낮음.
+  if (!hasComboTargets(config)) {
+    // Skip the native slug injection entirely when no combos are configured — avoids
+    // calling nativeOpenAiSlugs() (which reads the live Codex catalog from disk) for
+    // configs that will never need it.
+  } else {
+    const disabled = disabledNativeSlugs(config);
+    for (const slug of nativeOpenAiSlugs()) {
+      if (disabled.has(slug)) continue;
+      const contextWindow = nativeOpenAiContextWindow(slug);
+      if (contextWindow === undefined) continue;
+      const synthetic: CatalogModel = {
+        provider: "openai",
+        id: slug,
+        owned_by: "openai",
+        contextWindow,
+        maxInputTokens: contextWindow,
+        inputModalities: nativeInputModalities(slug),
+        reasoningEfforts: nativeReasoningEfforts(slug),
+        ...(nativeParallelToolCalls(slug) ? { parallelToolCalls: true } : {}),
+      };
+      const key = `openai/${slug}`;
+      // Only inject when not already present from a routed provider (an API-key
+      // "openai" provider could shadow the native one).
+      if (!memberByKey.has(key)) memberByKey.set(key, synthetic);
+    }
+  }
   for (const id of listComboIds(config)) {
     const combo = getCombo(config, id);
     if (!combo) continue;
@@ -1585,6 +1851,7 @@ export function deriveComboCatalogModel(
     maxInputTokens,
     inputModalities,
     reasoningEfforts,
+    ...(combo.alias ? { alias: combo.alias } : {}),
     ...(defaultReasoningEffort ? { defaultReasoningEffort } : {}),
     ...(members.every(member => member.parallelToolCalls === true)
       ? { parallelToolCalls: true }
@@ -1636,8 +1903,18 @@ function warnUncataloguedComboOnce(
   );
 }
 
-export function exactComboCatalogSlugs(config: Pick<OcxConfig, "combos">): Set<string> {
-  return new Set(listComboIds(config).map(comboModelId));
+export function exactComboCatalogSlugs(
+  config: Pick<OcxConfig, "combos" | "disabledModels">,
+): Set<string> {
+  const disabled = new Set(config.disabledModels ?? []);
+  return new Set(listComboIds(config).flatMap(id => {
+    const alias = typeof config.combos?.[id]?.alias === "string"
+      ? config.combos[id]!.alias!.trim()
+      : "";
+    const canonical = comboModelId(id);
+    const publicSlug = alias || canonical;
+    return disabled.has(publicSlug) || disabled.has(canonical) ? [] : [publicSlug];
+  }));
 }
 
 function normalizedOpenAiApiSignature(model: CatalogModel): string {
@@ -1665,12 +1942,23 @@ export function resetOpenAiApiCatalogWarningStateForTests(): void {
  * callable via its raw full-slash selector — and we warn once per provider+alias.
  */
 const slugAliasCollisionWarnings = new Set<string>();
+const comboMasqueradeCollisionWarnings = new Set<string>();
+
+function warnComboMasqueradeCollisionOnce(slug: string): void {
+  if (comboMasqueradeCollisionWarnings.has(slug)) return;
+  comboMasqueradeCollisionWarnings.add(slug);
+  console.warn(
+    `[opencodex] combo alias collision on "${safeCatalogWarningLabel(slug)}": the combo wins and the shadowed provider model is omitted from the catalog.`,
+  );
+}
 
 function resolveSlugAliasCollisions(goModels: CatalogModel[]): Set<CatalogModel> {
   const skipped = new Set<CatalogModel>();
   const winnerByAlias = new Map<string, CatalogModel>();
   for (const m of goModels) {
-    const key = `${m.provider}/${encodeRoutedModelId(m.id)}`;
+    // Combo aliases have their own collision policy below: they always shadow provider rows.
+    if (m.provider === COMBO_NAMESPACE) continue;
+    const key = catalogModelSlug(m);
     const winner = winnerByAlias.get(key);
     if (!winner) {
       winnerByAlias.set(key, m);
@@ -1695,6 +1983,53 @@ function resolveSlugAliasCollisions(goModels: CatalogModel[]): Set<CatalogModel>
   return skipped;
 }
 
+/** Apply Codex-facing encoded-slug collision policy to management and picker rows. */
+export function uniqueCatalogModelsForPublicList(goModels: CatalogModel[]): CatalogModel[] {
+  const collisionSkipped = resolveSlugAliasCollisions(goModels);
+  const comboPublicSlugs = new Set(goModels
+    .filter(model => model.provider === COMBO_NAMESPACE)
+    .map(catalogModelSlug));
+  const seen = new Set<string>();
+  const out: CatalogModel[] = [];
+  for (const model of goModels) {
+    if (collisionSkipped.has(model)) continue;
+    const slug = catalogModelSlug(model);
+    if (model.provider !== COMBO_NAMESPACE && comboPublicSlugs.has(slug)) {
+      warnComboMasqueradeCollisionOnce(slug);
+      continue;
+    }
+    if (seen.has(slug)) continue;
+    seen.add(slug);
+    out.push(model);
+  }
+  return out;
+}
+
+/**
+ * Deduplicate the ordinary OpenAI `/v1/models` list by the exact id emitted by that
+ * endpoint. Raw selectors that merely encode to the same Codex slug remain independently
+ * callable and visible; an exact combo alias collision still resolves in favor of the combo.
+ */
+export function uniqueCatalogModelsForRawPublicList(goModels: CatalogModel[]): CatalogModel[] {
+  const publicId = (model: CatalogModel): string => model.alias ?? `${model.provider}/${model.id}`;
+  const comboPublicIds = new Set(goModels
+    .filter(model => model.provider === COMBO_NAMESPACE)
+    .map(publicId));
+  const seen = new Set<string>();
+  const out: CatalogModel[] = [];
+  for (const model of goModels) {
+    const id = publicId(model);
+    if (model.provider !== COMBO_NAMESPACE && comboPublicIds.has(id)) {
+      warnComboMasqueradeCollisionOnce(id);
+      continue;
+    }
+    if (seen.has(id)) continue;
+    seen.add(id);
+    out.push(model);
+  }
+  return out;
+}
+
 /** Test-only reset for every process-global catalog cache/warning owner. */
 export function resetCatalogRuntimeStateForTests(): void {
   bundledCatalogCache = null;
@@ -1702,6 +2037,7 @@ export function resetCatalogRuntimeStateForTests(): void {
   openAiApiCollisionWarnings.clear();
   comboCatalogWarningSignatures.clear();
   slugAliasCollisionWarnings.clear();
+  comboMasqueradeCollisionWarnings.clear();
   clearModelCache();
 }
 
@@ -1803,7 +2139,10 @@ export function orderForSubagents(goModels: CatalogModel[], featured?: string[])
   const rank = new Map(featured.map((id, i) => [id, i]));
   // Featured picks may be stored raw (legacy) or encoded — match both forms.
   const rankOf = (m: CatalogModel) =>
-    rank.get(`${m.provider}/${m.id}`) ?? rank.get(routedSlug(m.provider, m.id)) ?? Number.MAX_SAFE_INTEGER;
+    (m.alias ? rank.get(m.alias) : undefined)
+      ?? rank.get(`${m.provider}/${m.id}`)
+      ?? rank.get(routedSlug(m.provider, m.id))
+      ?? Number.MAX_SAFE_INTEGER;
   return [...goModels].sort((a, b) => {
     return rankOf(a) - rankOf(b);
   });
@@ -1831,6 +2170,7 @@ export function mergeCatalogEntriesForSync(
   const native = catalogModels
     .filter(m => typeof m.slug === "string"
       && !(m.slug as string).includes("/")
+      && m.owned_by !== COMBO_NAMESPACE
       && !goIds.has(m.slug as string)
       && !isUnsupportedOpenAiNativeSlug(m.slug as string))
     .map(m => {
@@ -1898,7 +2238,8 @@ export function mergeCatalogEntriesForSync(
   if (!hasPhysicalComboProvider) {
     finalRoutedEntries = finalRoutedEntries.filter(entry => {
       const slug = typeof entry.slug === "string" ? entry.slug : "";
-      return !slug.startsWith(`${COMBO_NAMESPACE}/`) || freshSlugs.has(slug);
+      const comboOwned = slug.startsWith(`${COMBO_NAMESPACE}/`) || entry.owned_by === COMBO_NAMESPACE;
+      return !comboOwned || freshSlugs.has(slug);
     });
   }
   finalRoutedEntries = finalRoutedEntries.filter(entry => {
@@ -1921,6 +2262,7 @@ export function mergeCatalogEntriesForSync(
     const exactCombo = typeof m.slug === "string" && exactComboSlugs.has(m.slug);
     const e = ensureStrictCatalogFields(normalized, {
       preserveExactInputModalities: exactCombo,
+      isRouted: finalRoutedEntries.includes(m),
     });
     // Mock-max universality (260709): preserved routed entries from disk may predate
     // the max rung — ensure it here so subagent max spawns validate on every

package/src/combos/index.ts

@@ -1,14 +1,17 @@
 export {
   COMBO_NAMESPACE,
+  comboAliasIssues,
   comboConfigError,
   comboConfigIssues,
   comboDefaultEffort,
   comboModelId,
+  comboPublicModelId,
   getCombo,
   isValidComboId,
   listComboIds,
   normalizeComboConfig,
   parseComboModelId,
+  resolveComboId,
   targetKey,
 } from "./types";
 export {