@bitkyc08/opencodex 2.11.1 → 2.12.0

package/src/codex/auth-api.ts

@@ -58,6 +58,7 @@ import {
   parseAccountPriority,
 } from "./pool-rotation";
 import { checkAccountIdCollision, getMainChatgptAccountId, readCodexTokens, readCodexTokensResult } from "./auth-collision";
+import { codexPlanValue, isThirtyDayOnlyCodexPlan } from "./plan";
 export { checkAccountIdCollision, getMainChatgptAccountId } from "./auth-collision";
 export { clearAccountNeedsReauth, isAccountNeedsReauth, markAccountNeedsReauth } from "./account-runtime-state";
 import { clearAccountNeedsReauth, isAccountNeedsReauth, markAccountNeedsReauth } from "./account-runtime-state";
@@ -103,7 +104,8 @@ import type { CodexAccount, CodexAccountCredentials, OcxConfig } from "../types"
 import type { CatalogDisposition } from "./convergence-types";
 import { isCanonicalOpenAiForwardProvider, OPENAI_CODEX_PROVIDER_ID } from "../providers/openai-tiers";
 import { providerCodexAccountMode } from "../providers/registry";
-import { readBoundedResponseBody } from "../lib/bounded-body";
+import { BOUNDED_BODY_MAX_BYTES, readBoundedResponseBody } from "../lib/bounded-body";
+import { cancelBodyOnAbort, signalWithTimeout } from "../lib/abort";
 import {
   oauthAccountHealthFields,
   projectCodexAccountHealth,
@@ -208,16 +210,11 @@ function codexAccountPersistenceConflict(
     : undefined;
 }
 
-function isThirtyDayOnlyPlan(plan: string | null | undefined): boolean {
-  const normalized = plan?.trim().toLowerCase();
-  return normalized === "go" || normalized === "free";
-}
-
 function quotaForPlan<T extends Omit<StoredAccountQuota, "updatedAt"> | StoredAccountQuota | null>(
   quota: T,
-  plan: string | null | undefined,
+  plan: unknown,
 ): T {
-  if (!quota || !isThirtyDayOnlyPlan(plan)) return quota;
+  if (!quota || !isThirtyDayOnlyCodexPlan(plan)) return quota;
   return {
     ...(quota.monthlyPercent !== undefined ? { monthlyPercent: quota.monthlyPercent } : {}),
     ...(quota.monthlyResetAt !== undefined ? { monthlyResetAt: quota.monthlyResetAt } : {}),
@@ -233,14 +230,15 @@ function poolAccountDto(
   paused: boolean,
   priority: number,
 ): CodexAuthAccountDto {
-  const quota = quotaForPlan(quotaResult.quota, account.plan);
+  const plan = codexPlanValue(account.plan);
+  const quota = quotaForPlan(quotaResult.quota, plan);
   const needsReauth = !hasCredential || quotaResult.needsReauth || isAccountNeedsReauth(account.id);
   const health = projectCodexAccountHealth({ accountId: account.id, needsReauth });
   return {
     id: account.id,
     email: maskEmail(account.email) ?? account.email,
     ...(account.alias !== undefined ? { alias: account.alias } : {}),
-    ...(account.plan !== undefined ? { plan: account.plan } : {}),
+    ...(plan !== undefined ? { plan } : {}),
     ...(account.logLabel !== undefined ? { logLabel: account.logLabel } : {}),
     isMain: false,
     paused,
@@ -340,6 +338,43 @@ function safeResetCreditConsumeDto(input: unknown): { code: string } {
   return { code: typeof obj.code === "string" ? obj.code : "unknown" };
 }
 
+type ResetCreditJsonRead =
+  | { ok: true; value: unknown }
+  | { ok: false };
+
+function cancelResponseBodyWithoutWaiting(body: ReadableStream<Uint8Array> | null): void {
+  if (!body) return;
+  try {
+    void body.cancel().catch(() => undefined);
+  } catch {
+    // Some stream implementations throw synchronously from cancel().
+  }
+}
+
+async function readResetCreditJson(
+  response: Response,
+  signal: AbortSignal,
+): Promise<ResetCreditJsonRead> {
+  const declaredLength = Number(response.headers.get("content-length"));
+  if (Number.isSafeInteger(declaredLength)
+    && declaredLength >= 0
+    && declaredLength > BOUNDED_BODY_MAX_BYTES) {
+    cancelResponseBodyWithoutWaiting(response.body);
+    return { ok: false };
+  }
+  try {
+    const body = await readBoundedResponseBody(response, {
+      signal,
+      maxBytes: BOUNDED_BODY_MAX_BYTES,
+      fatalUtf8: true,
+    });
+    if (!body.displaySafe || body.truncated || !body.text.trim()) return { ok: false };
+    return { ok: true, value: JSON.parse(body.text) as unknown };
+  } catch {
+    return { ok: false };
+  }
+}
+
 export function isUnverifiedCodexImportEnabled(): boolean {
   return process.env[MANUAL_IMPORT_ENV] === "1";
 }
@@ -398,7 +433,7 @@ const POOL_CACHE_TTL = 5 * 60_000;
 const POOL_QUOTA_REFRESH_CONCURRENCY = 4;
 
 function nonEmptyPlan(value: unknown): string | null {
-  return typeof value === "string" && value.trim() !== "" ? value : null;
+  return codexPlanValue(value) ?? null;
 }
 
 function isRuntimeConfig(config: OcxConfig): boolean {
@@ -1334,7 +1369,7 @@ export async function handleCodexAuthAPI(
   if (url.pathname === "/api/codex-auth/accounts" && req.method === "POST") {
     if (!isUnverifiedCodexImportEnabled()) return manualImportDisabledResponse();
 
-    let body: { id: string; email: string; plan?: string; accessToken: string; refreshToken: string; chatgptAccountId: string };
+    let body: { id: string; email: string; plan?: unknown; accessToken: string; refreshToken: string; chatgptAccountId: string };
     try { body = (await req.json()) as typeof body; } catch { return jsonResponse({ error: "Invalid JSON" }, 400); }
     if (!body.id || !body.email || !body.accessToken || !body.refreshToken || !body.chatgptAccountId) {
       return jsonResponse({ error: "Missing required fields" }, 400);
@@ -1349,8 +1384,9 @@ export async function handleCodexAuthAPI(
     const preflightConflict = codexAccountPersistenceConflict(runtimeConfig, body.id, "create");
     if (preflightConflict) return jsonResponse({ error: preflightConflict }, 400);
     // 1.1: Duplicate check is scoped by personal vs workspace plan bucket.
+    const plan = codexPlanValue(body.plan);
     const derivedAccountId = extractAccountId(undefined, body.accessToken) ?? body.chatgptAccountId;
-    const collision = checkAccountIdCollision(derivedAccountId, body.email, body.plan);
+    const collision = checkAccountIdCollision(derivedAccountId, body.email, plan);
     if (collision.collision) {
       return jsonResponse({ error: collision.reason }, 400);
     }
@@ -1363,7 +1399,12 @@ export async function handleCodexAuthAPI(
     const commitConflict = codexAccountPersistenceConflict(latestConfig, body.id, "create");
     if (commitConflict) return jsonResponse({ error: commitConflict }, 400);
     const addedAccount = withCodexAccountLogLabel(
-      { id: body.id, email: body.email, plan: body.plan, isMain: false },
+      {
+        id: body.id,
+        email: body.email,
+        ...(plan !== undefined ? { plan } : {}),
+        isMain: false,
+      },
       latestConfig.codexAccounts ?? [],
     );
     const persistence = persistNewCodexAccount(
@@ -1679,21 +1720,44 @@ export async function handleCodexAuthAPI(
 
     try {
       const result = await withResetCreditAuth(getRuntimeConfig(config), accountId, async auth => {
-        const resp = await fetch(
-          "https://chatgpt.com/backend-api/wham/rate-limit-reset-credits",
-          {
-            headers: {
-              Authorization: `Bearer ${auth.accessToken}`,
-              "ChatGPT-Account-Id": auth.chatgptAccountId,
-            },
-            signal: AbortSignal.timeout(8000),
-          },
-        );
-        if (!resp.ok) {
-          await resp.body?.cancel().catch(() => {});
-          return jsonResponse({ error: `Upstream error ${resp.status}` }, resp.status);
+        const linkedSignal = signalWithTimeout(8000, req.signal);
+        let detachBodyAbort = () => {};
+        try {
+          let resp: Response;
+          try {
+            resp = await fetch(
+              "https://chatgpt.com/backend-api/wham/rate-limit-reset-credits",
+              {
+                headers: {
+                  Authorization: `Bearer ${auth.accessToken}`,
+                  "ChatGPT-Account-Id": auth.chatgptAccountId,
+                },
+                signal: linkedSignal.signal,
+              },
+            );
+          } catch (error) {
+            if (linkedSignal.signal.aborted) {
+              return jsonResponse({ error: "Invalid upstream reset-credit response" }, 502);
+            }
+            throw error;
+          }
+          // Own the response body before the bounded reader attaches. If the client
+          // disconnects in that narrow window, Bun otherwise tears down the native
+          // body off the awaited path and can report an unhandled rejection.
+          detachBodyAbort = cancelBodyOnAbort(resp.body, linkedSignal.signal);
+          if (!resp.ok) {
+            await resp.body?.cancel().catch(() => {});
+            return jsonResponse({ error: `Upstream error ${resp.status}` }, resp.status);
+          }
+          const parsed = await readResetCreditJson(resp, linkedSignal.signal);
+          if (!parsed.ok) {
+            return jsonResponse({ error: "Invalid upstream reset-credit response" }, 502);
+          }
+          return jsonResponse(safeResetCreditsDto(parsed.value));
+        } finally {
+          detachBodyAbort();
+          linkedSignal.cleanup();
         }
-        return jsonResponse(safeResetCreditsDto(await resp.json()));
       });
       return result.ok ? result.value : result.response;
     } catch (e) {

package/src/codex/auth-collision.ts

@@ -5,6 +5,7 @@ import { loadConfig } from "../config";
 import { resolveCodexHomeDir } from "./home";
 import { extractAccountId } from "../oauth/chatgpt";
 import { isSelectableCodexPoolAccount } from "./account-id";
+import { codexPlanKey } from "./plan";
 
 export interface CodexTokens {
   access_token: string;
@@ -78,8 +79,9 @@ function normalizedEmail(email: string | undefined | null): string | null {
   return trimmed || null;
 }
 
-function isWorkspacePlan(plan: string | undefined | null): boolean {
-  return !!plan && /team|business|enterprise|workspace|edu/i.test(plan);
+function isWorkspacePlan(plan: unknown): boolean {
+  const key = codexPlanKey(plan);
+  return !!key && /team|business|enterprise|workspace|edu/.test(key);
 }
 
 // Main login and managed pool accounts are separate duplicate buckets.
@@ -88,7 +90,7 @@ function isWorkspacePlan(plan: string | undefined | null): boolean {
 export function checkAccountIdCollision(
   chatgptAccountId: string,
   email?: string | null,
-  plan?: string | null,
+  plan?: unknown,
   excludeAccountId?: string | null,
 ): { collision: true; reason: string } | { collision: false } {
   const candidateEmail = normalizedEmail(email);

package/src/codex/catalog/metadata.ts

@@ -253,11 +253,11 @@ export function shouldUpgradeToUpstreamEntry(entry: RawEntry): boolean {
 }
 
 export function nativeOpenAiSlugs(): string[] {
-  const live = listCatalogNativeSlugs();
+  const live = catalogNativeSlugs();
   return live.length > 0 ? unique([...live, ...DOCUMENTED_NATIVE_OPENAI_ADDITIONS]) : NATIVE_OPENAI_MODELS;
 }
 
-export function listCatalogNativeSlugs(): string[] {
+function catalogNativeSlugs(): string[] {
   const cat = readCurrentCatalogOrCache();
   const models = cat?.models ?? [];
   const live = models.flatMap(entry => {
@@ -271,7 +271,11 @@ export function listCatalogNativeSlugs(): string[] {
   // Deliberately ignore `visibility`: it is a rendered projection of disabledModels and account
   // selectors, so treating it as fresh availability would shrink the supported set between syncs.
   // visibleNativeSlugs applies the current disabledModels source of truth for public consumers.
+  return unique([...live, ...accountBound]);
+}
+
+export function listCatalogNativeSlugs(): string[] {
   // Ensure documented additions (e.g. gpt-5.3-codex-spark) appear even when the bundled catalog
   // predates the slug — mirrors nativeOpenAiSlugs() which already merges them for /v1/models.
-  return unique([...live, ...accountBound, ...DOCUMENTED_NATIVE_OPENAI_ADDITIONS]);
+  return unique([...catalogNativeSlugs(), ...DOCUMENTED_NATIVE_OPENAI_ADDITIONS]);
 }

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

@@ -151,6 +151,13 @@ interface CapturedProviderGather {
   readonly policy: CatalogProviderDiscoveryPolicySnapshot;
   readonly request: CapturedModelsRequest;
   readonly observedAuth?: ModelsAuthResolution;
+  /**
+   * Configured model ids this provider must keep even when live discovery omits
+   * them — combo targets that are also listed in providers.*.models (OCX-111).
+   * Combo-only ids (not in models[]) stay out of the public catalog and are
+   * synthesized for combo derivation instead (#1305).
+   */
+  readonly retainConfiguredModelIds?: ReadonlySet<string>;
 }
 
 interface GatherFlightCapture {
@@ -381,6 +388,7 @@ function captureProviderGather(
   name: string,
   configured: OcxProviderConfig,
   authResolver: ModelsAuthResolver,
+  retainConfiguredModelIds?: ReadonlySet<string>,
 ): CapturedProviderGather {
   const enriched = detachedClone(configured);
   enrichProviderFromRegistry(name, enriched);
@@ -422,18 +430,47 @@ function captureProviderGather(
     policy,
     request,
     ...(observedAuth ? { observedAuth: Object.freeze({ ...observedAuth }) } : {}),
+    ...(retainConfiguredModelIds && retainConfiguredModelIds.size > 0
+      ? { retainConfiguredModelIds }
+      : {}),
   });
 }
 
+/** Model ids each provider must retain for combo catalog derivation (OCX-111). */
+export function configuredComboTargetModelsByProvider(
+  config: Pick<OcxConfig, "combos">,
+): Map<string, ReadonlySet<string>> {
+  const byProvider = new Map<string, Set<string>>();
+  for (const id of listComboIds(config)) {
+    const combo = getCombo(config, id);
+    if (!combo) continue;
+    for (const target of combo.targets) {
+      let models = byProvider.get(target.provider);
+      if (!models) {
+        models = new Set();
+        byProvider.set(target.provider, models);
+      }
+      models.add(target.model);
+    }
+  }
+  return byProvider;
+}
+
 function captureGatherFlight(
   config: OcxConfig,
   createAuthResolver: ModelsAuthResolverFactory,
 ): GatherFlightCapture {
   const providerAuthOutcomes: CatalogGatherProviderAuthOutcome[] = [];
   const authResolver = createAuthResolver(providerAuthOutcomes);
+  const comboTargetsByProvider = configuredComboTargetModelsByProvider(config);
   const providers = Object.entries(config.providers)
     .filter(([, provider]) => provider.disabled !== true)
-    .map(([name, provider]) => captureProviderGather(name, provider, authResolver));
+    .map(([name, provider]) => captureProviderGather(
+      name,
+      provider,
+      authResolver,
+      comboTargetsByProvider.get(name),
+    ));
   const discoveryPolicySnapshots = Object.freeze(providers.map(provider => provider.policy));
   return Object.freeze({
     discoveryPolicyIdentity: keyedGatherIdentity("catalog-discovery-policy-v1", discoveryPolicySnapshots),
@@ -460,6 +497,9 @@ function captureGatherFlight(
         // It is the one member of a provider row that is legitimately a function,
         // so it is dropped here rather than allowed to break every encode.
         provider: omitProviderTransportExecutor(provider.provider),
+        // Combo retention is capture-time state, not a provider-row field. Two
+        // gathers that share providers but differ in combo targets must not join.
+        retainConfiguredModelIds: [...(provider.retainConfiguredModelIds ?? [])].sort(),
       }))),
     discoveryPolicySnapshots,
     providers: Object.freeze(providers),
@@ -846,7 +886,9 @@ function normalizedStringList(value: unknown, maxItems = 32, maxLength = 64): st
 function modelCapabilities(item: ProviderModelsApiItem): string[] | undefined {
   const metadata = plainRecord(item.metadata);
   const metadataCapabilities = metadata?.capabilities;
-  const capabilityRecord = plainRecord(metadataCapabilities) ?? plainRecord(item.capabilities);
+  const capabilityRecord = plainRecord(metadataCapabilities)
+    ?? plainRecord(item.capabilities)
+    ?? plainRecord(item.features);
   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);
@@ -876,7 +918,9 @@ function modelInputModalities(
   capabilities: readonly string[] | undefined,
 ): string[] | undefined {
   const metadata = plainRecord(item.metadata);
-  const capabilityRecord = plainRecord(metadata?.capabilities) ?? plainRecord(item.capabilities);
+  const capabilityRecord = plainRecord(metadata?.capabilities)
+    ?? plainRecord(item.capabilities)
+    ?? plainRecord(item.features);
   const explicit = normalizedStringList(
     item.input_modalities
       ?? item.modalities
@@ -903,7 +947,9 @@ function modelInputModalities(
     if (inferred.length > 0) return [...new Set(inferred)];
   }
   if (capabilityRecord?.vision === false) return ["text"];
-  if (capabilityRecord?.vision === true || capabilities?.some(value => value === "vision" || value === "image-input")) {
+  if (capabilityRecord?.vision === true || capabilities?.some(value => (
+    value === "vision" || value === "image-input" || value === "image_input"
+  ))) {
     return ["text", "image"];
   }
   return undefined;
@@ -923,7 +969,16 @@ export function catalogHintsFromModelsApiItem(providerName: string, item: Provid
       item.max_context_length,
     );
   const maxInputTokens = positiveSafeInteger(limits?.max_input_tokens, item.max_input_tokens);
-  const rawReasoningEfforts = capabilityRecord?.reasoning_effort ?? item.reasoning_efforts;
+  // Some OpenAI-compatible catalogs expose the selectable ladder under
+  // `reasoning_parameters.efforts` instead of the older `reasoning_efforts` key.
+  // Treat both as model metadata: otherwise a valid upstream capability disappears
+  // before client exporters (including omp) can advertise it.
+  const reasoningParameters = plainRecord(item.reasoning_parameters)
+    ?? plainRecord(metadata?.reasoning_parameters)
+    ?? plainRecord(capabilityRecord?.reasoning_parameters);
+  const rawReasoningEfforts = capabilityRecord?.reasoning_effort
+    ?? item.reasoning_efforts
+    ?? reasoningParameters?.efforts;
   const listedReasoningEfforts = normalizedStringList(rawReasoningEfforts, 8, 24);
   const reasoningEfforts = listedReasoningEfforts
     ? sanitizeCodexReasoningEfforts(listedReasoningEfforts)
@@ -1004,6 +1059,30 @@ async function fetchProviderModelsWithAuth(
     provider: name,
     ...catalogHintsFromProviderConfig(name, prov, id, contextCap),
   }));
+  const withConfiguredRetention = (
+    models: CatalogModel[],
+    options?: { retainComboTargets?: boolean; warnDrops?: boolean },
+  ): CatalogModel[] => {
+    const { models: merged, droppedConfiguredIds } = mergeConfiguredModelsIntoLiveCatalog({
+      name,
+      provider: prov,
+      models,
+      configured,
+      retainConfiguredModelIds: captured.retainConfiguredModelIds,
+      contextCap,
+      seedVertexDefault,
+      retainComboTargets: options?.retainComboTargets,
+    });
+    if (
+      options?.warnDrops === true
+      && droppedConfiguredIds.length > 0
+      && name !== OPENAI_API_PROVIDER_ID
+      && !QUIET_AUTHORITATIVE_CATALOG_PROVIDERS.has(name)
+    ) {
+      warnDroppedConfiguredIdsOnce(name, droppedConfiguredIds);
+    }
+    return merged;
+  };
   // Static catalogs never need an OAuth refresh or an upstream model request. Clear any
   // discovery failure left by an older live configuration even when the account is logged out.
   if (prov.liveModels === false) {
@@ -1047,12 +1126,17 @@ async function fetchProviderModelsWithAuth(
     // plan (e.g. claude-fable-5) drop out instead of failing ERROR_BAD_MODEL_NAME. Fall back to the seed.
     const cachedCursor = getFreshCached(name, ttlMs);
     if (cachedCursor) {
-      return observed(applyConfigHintsToCachedModels(name, prov, cachedCursor), "authoritative");
+      return observed(
+        withConfiguredRetention(applyConfigHintsToCachedModels(name, prov, cachedCursor)),
+        "authoritative",
+      );
     }
     if (isModelsFetchCoolingDown(name)) {
       const cooling = getStaleCached(name);
       return observed(
-        cooling ? applyConfigHintsToCachedModels(name, prov, cooling) : configured,
+        withConfiguredRetention(
+          cooling ? applyConfigHintsToCachedModels(name, prov, cooling) : configured,
+        ),
         "degraded",
       );
     }
@@ -1060,10 +1144,14 @@ async function fetchProviderModelsWithAuth(
     if (liveResult.ok) {
       const available = filterCursorConfiguredModelsByLiveDiscovery(configured, liveResult.models);
       const result = available.length > 0 ? available : configured;
-      // Count what discovery actually returned, not the configured rows we fall back to.
-      if (!setCached(name, result, Date.now(), cacheGeneration)) return observed(configured, "degraded");
+      // Cache the discovery-filtered roster without combo retention so a later
+      // gather can re-apply the current capture's retain set on read.
+      const forCache = withConfiguredRetention(result, { retainComboTargets: false });
+      if (!setCached(name, forCache, Date.now(), cacheGeneration)) {
+        return observed(withConfiguredRetention(configured), "degraded");
+      }
       markProviderDiscoveryOk(name, liveResult.models.length);
-      return observed(result, "authoritative");
+      return observed(withConfiguredRetention(forCache, { warnDrops: true }), "authoritative");
     }
     if (isCurrentCacheGeneration()) {
       markModelsFetchFailure(name);
@@ -1074,7 +1162,9 @@ async function fetchProviderModelsWithAuth(
     }
     const staleCursor = getStaleCached(name);
     return observed(
-      staleCursor ? applyConfigHintsToCachedModels(name, prov, staleCursor) : configured,
+      withConfiguredRetention(
+        staleCursor ? applyConfigHintsToCachedModels(name, prov, staleCursor) : configured,
+      ),
       "degraded",
     );
   }
@@ -1090,7 +1180,9 @@ async function fetchProviderModelsWithAuth(
   const fresh = getFreshCached(name, ttlMs);
   if (fresh) {
     return observed(
-      withVertexDefaultSeed(applyConfigHintsToCachedModels(name, prov, fresh, contextCap)),
+      withConfiguredRetention(
+        withVertexDefaultSeed(applyConfigHintsToCachedModels(name, prov, fresh, contextCap)),
+      ),
       "authoritative",
     ); // dedups Codex's frequent /v1/models polling within the TTL
   }
@@ -1099,9 +1191,11 @@ async function fetchProviderModelsWithAuth(
     // fetch timeout on every catalog poll — the dashboard polls this path per page load.
     const stale = getStaleCached(name);
     return observed(
-      stale
-        ? withVertexDefaultSeed(applyConfigHintsToCachedModels(name, prov, stale, contextCap))
-        : failedDiscoveryConfigured,
+      withConfiguredRetention(
+        stale
+          ? withVertexDefaultSeed(applyConfigHintsToCachedModels(name, prov, stale, contextCap))
+          : failedDiscoveryConfigured,
+      ),
       "degraded",
     );
   }
@@ -1114,7 +1208,11 @@ async function fetchProviderModelsWithAuth(
     failure: ProviderModelDiscoveryFailure,
   ): { models: CatalogModel[]; fallback: "stale" | "configured"; shouldLog: boolean } => {
     if (!isCurrentCacheGeneration()) {
-      return { models: failedDiscoveryConfigured, fallback: "configured", shouldLog: false };
+      return {
+        models: withConfiguredRetention(failedDiscoveryConfigured),
+        fallback: "configured",
+        shouldLog: false,
+      };
     }
     // Decide logging BEFORE recording the new status, so we can compare against the prior one and
     // suppress an identical repeated failure (#395 log flood). The failure stays observable via the
@@ -1124,9 +1222,11 @@ async function fetchProviderModelsWithAuth(
     markProviderDiscoveryFailed(name, failure);
     const stale = getStaleCached(name);
     return {
-      models: stale
-        ? withVertexDefaultSeed(applyConfigHintsToCachedModels(name, prov, stale, contextCap))
-        : failedDiscoveryConfigured,
+      models: withConfiguredRetention(
+        stale
+          ? withVertexDefaultSeed(applyConfigHintsToCachedModels(name, prov, stale, contextCap))
+          : failedDiscoveryConfigured,
+      ),
       fallback: stale ? "stale" : "configured",
       shouldLog,
     };
@@ -1202,9 +1302,12 @@ async function fetchProviderModelsWithAuth(
         ...(model.contextWindow ? { contextWindow: model.contextWindow } : {}),
         ...(model.inputModalities ? { inputModalities: model.inputModalities } : {}),
       }, contextCap));
-      if (!setCached(name, live, Date.now(), cacheGeneration)) return observed(configured, "degraded");
+      const forCache = withConfiguredRetention(live, { retainComboTargets: false });
+      if (!setCached(name, forCache, Date.now(), cacheGeneration)) {
+        return observed(withConfiguredRetention(configured), "degraded");
+      }
       markProviderDiscoveryOk(name, live.length);
-      return observed(live, "authoritative");
+      return observed(withConfiguredRetention(forCache, { warnDrops: true }), "authoritative");
     }
     const extracted = extractProviderModelItems(bounded.value, discovery);
     if (!extracted.ok) {
@@ -1236,37 +1339,24 @@ async function fetchProviderModelsWithAuth(
     // Capture the count BEFORE the alias/configured augmentation below pushes extra rows into
     // `live`; otherwise configured entries would be reported as discovered ones.
     const liveModelCount = live.length;
-    const liveIds = new Set(live.map(m => m.id));
-    // Dated-release aliases (Anthropic pattern): older models may appear in the live catalog
-    // ONLY under their dated id (claude-haiku-4-5-20251001) while the config names the
-    // API-valid alias (claude-haiku-4-5). Such aliases are real, callable models — keep them
-    // in the authoritative catalog (alias id, hints from the dated live entry) instead of
-    // dropping them and warning on every poll.
-    const droppedConfiguredIds: string[] = [];
-    for (const m of configured) {
-      if (liveIds.has(m.id)) continue;
-      const dated = live.find(l => isDatedVariantId(l.id, m.id));
-      if (dated) {
-        // Reapply config hints so alias-keyed overrides (modelContextWindows etc.) win.
-        live.push(applyProviderConfigHints(name, prov, { ...dated, id: m.id }, contextCap));
-      } else if (seedVertexDefault || shouldRetainConfiguredProviderModel(name, m.id)) {
-        live.push(m);
-      } else {
-        droppedConfiguredIds.push(m.id);
-      }
-    }
-    if (live.length === 0 && name !== OPENAI_API_PROVIDER_ID) {
+    // Dated-release aliases + configured retention (compat allow-list, combo targets,
+    // Vertex default). Cache without combo retention so a later gather re-applies the
+    // current capture's retain set on read (warm-cache OCX-111 / #1308).
+    const forCache = withConfiguredRetention(live, { retainComboTargets: false });
+    const returned = withConfiguredRetention(forCache, { warnDrops: true });
+    const droppedConfiguredIds = configured
+      .map(model => model.id)
+      .filter(id => !returned.some(model => model.id === id));
+    if (returned.length === 0 && name !== OPENAI_API_PROVIDER_ID) {
       console.warn(
         `[opencodex] Provider model discovery for "${name}" returned an authoritative empty catalog; ${droppedConfiguredIds.length > 0 ? `dropping configured model ids: ${droppedConfiguredIds.join(", ")}` : "no models will be exposed"}.`,
       );
-    } else if (droppedConfiguredIds.length > 0
-      && name !== OPENAI_API_PROVIDER_ID
-      && !QUIET_AUTHORITATIVE_CATALOG_PROVIDERS.has(name)) {
-      warnDroppedConfiguredIdsOnce(name, droppedConfiguredIds);
     }
-    if (!setCached(name, live, Date.now(), cacheGeneration)) return observed(configured, "degraded");
+    if (!setCached(name, forCache, Date.now(), cacheGeneration)) {
+      return observed(withConfiguredRetention(configured), "degraded");
+    }
     markProviderDiscoveryOk(name, liveModelCount);
-    return observed(live, "authoritative");
+    return observed(returned, "authoritative");
   } catch (error) {
     if (error instanceof ProviderOutboundPolicyError) {
       const { models, fallback, shouldLog } = failedDiscoveryFallback({ reason: "blocked" });
@@ -1313,6 +1403,60 @@ export function shouldRetainConfiguredProviderModel(providerName: string, modelI
   return false;
 }
 
+/**
+ * Fold dated-release aliases and retain configured rows that must survive an
+ * authoritative live roster (compatibility allow-list, combo targets, Vertex
+ * default). Used on every discovery return — live, fresh cache, stale, and
+ * failure fallback — so a warm cache captured before a combo existed still
+ * surfaces the configured target (OCX-111 / #1308).
+ *
+ * Cache writes should pass `retainComboTargets: false` so combo retention is
+ * re-applied on read against the current capture, not frozen into the TTL entry.
+ */
+export function mergeConfiguredModelsIntoLiveCatalog(opts: {
+  name: string;
+  provider: OcxProviderConfig;
+  models: readonly CatalogModel[];
+  configured: readonly CatalogModel[];
+  retainConfiguredModelIds?: ReadonlySet<string>;
+  contextCap?: number;
+  seedVertexDefault?: boolean;
+  retainComboTargets?: boolean;
+}): { models: CatalogModel[]; droppedConfiguredIds: string[] } {
+  const {
+    name,
+    provider: prov,
+    configured,
+    retainConfiguredModelIds,
+    contextCap,
+    seedVertexDefault,
+    retainComboTargets = true,
+  } = opts;
+  const out = [...opts.models];
+  const present = new Set(out.map(model => model.id));
+  const droppedConfiguredIds: string[] = [];
+  for (const candidate of configured) {
+    if (present.has(candidate.id)) continue;
+    const dated = out.find(live => isDatedVariantId(live.id, candidate.id));
+    if (dated) {
+      out.push(applyProviderConfigHints(name, prov, { ...dated, id: candidate.id }, contextCap));
+      present.add(candidate.id);
+      continue;
+    }
+    if (
+      seedVertexDefault === true
+      || shouldRetainConfiguredProviderModel(name, candidate.id)
+      || (retainComboTargets && retainConfiguredModelIds?.has(candidate.id) === true)
+    ) {
+      out.push(candidate);
+      present.add(candidate.id);
+      continue;
+    }
+    droppedConfiguredIds.push(candidate.id);
+  }
+  return { models: out, droppedConfiguredIds };
+}
+
 export function filterCatalogVisibleModels(
   models: CatalogModel[],
   config: Pick<OcxConfig, "disabledModels" | "providers">,

package/src/codex/catalog.ts

@@ -2,10 +2,10 @@
 // Public surface preserved exactly; importers keep using "src/codex/catalog".
 export { isMediaGenerationModelId, shouldExposeRoutedModel, readCodexCatalogPath, readCatalog, normalizeRoutedCatalogEntry, catalogModelSlug, filterSupportedNativeSlugs, catalogModelSupportsReasoningSummaries } from "./catalog/parsing";
 export type { CatalogModel, MultiAgentMode } from "./catalog/parsing";
-export { CODEX_NATIVE_ALIAS_CATALOG_KIND, NATIVE_OPENAI_MODELS, configuredNativeAliasSlugs, desktopAllowlistSuppressedNativeSlugs, isNativeAliasCatalogEntry, nativeOpenAiContextWindow, disabledNativeSlugs, visibleNativeSlugs, desktopVisibleNativeSlugs, nativeModelRows, applyNativeVisibility, upstreamNativeEntry, nativeOpenAiSlugs, listCatalogNativeSlugs, nativeReasoningEfforts, nativeDefaultReasoningEffort, shouldIncludeAccountBoundNativeOpenAi, shouldIncludeNativeOpenAi } from "./catalog/metadata";
+export { CODEX_NATIVE_ALIAS_CATALOG_KIND, NATIVE_OPENAI_MODELS, configuredNativeAliasSlugs, desktopAllowlistSuppressedNativeSlugs, isNativeAliasCatalogEntry, nativeOpenAiContextWindow, disabledNativeSlugs, visibleNativeSlugs, desktopVisibleNativeSlugs, nativeModelRows, applyNativeVisibility, upstreamNativeEntry, nativeOpenAiSlugs, listCatalogNativeSlugs, nativeInputModalities, nativeReasoningEfforts, nativeDefaultReasoningEffort, shouldIncludeAccountBoundNativeOpenAi, shouldIncludeNativeOpenAi } 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, clearGatherRoutedModelsInflight, augmentRoutedModelsWithRegistryOpenAiApiRows, augmentRoutedModelsWithMetadata, resolveComboCatalogMember } from "./catalog/provider-fetch";
+export { applyProviderConfigHints, isDatedVariantId, filterCatalogVisibleModels, gatherRoutedModels, clearGatherRoutedModelsInflight, augmentRoutedModelsWithRegistryOpenAiApiRows, augmentRoutedModelsWithMetadata, resolveComboCatalogMember, configuredComboTargetModelsByProvider } 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, CANONICAL_NATIVE_CATALOG_CONTENT_POLICY, effectiveSubagentRoster, buildCatalogEntries, mergeCatalogEntriesFromObservedState, resetCatalogRuntimeStateForTests, orderForSubagents, mergeCatalogEntriesForSync, syncCatalogModels, restoreCodexCatalog, invalidateCodexModelsCache } from "./catalog/sync";