@iislee/opencodex 2.11.0 → 2.31.0

package/src/codex/catalog/aggregation.ts

@@ -9,17 +9,18 @@ import { buildModelsRequest, resolveModelsAuthToken } from "../../oauth";
 import type { OcxConfig, OcxProviderConfig } from "../../types";
 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 { getModelMetadata, getModelMetadataCaseInsensitive, listModelMetadata, resolveMetadataProvider } from "../../generated/model-metadata";
 import { enrichProviderFromRegistry, shouldCaseFoldMetadataModelId } from "../../providers/derive";
 import { getProviderRegistryEntry } from "../../providers/registry";
 import { applyProviderContextCap, providerContextCap } from "../../providers/context-cap";
-import { routedSlug, slugEquals, slugsEquivalent } from "../../providers/slug-codec";
+import { routedSlug, slugEquals, slugEquivalenceKey, 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 { isCanonicalOpenAiForwardProvider, OPENAI_API_PROVIDER_ID, OPENAI_CODEX_PROVIDER_ID } from "../../providers/openai-tiers";
 import {
   COMBO_NAMESPACE,
+  comboDisabledModelSelectors,
   comboModelId,
   getCombo,
   listComboIds,
@@ -128,13 +129,30 @@ export function deriveComboCatalogModel(
 ): CatalogModel | null {
   if (comboCatalogOmissionReason(combo, members) !== null) return null;
 
-  const inputModalities = intersectStrings(
+  const derivedInputModalities = intersectStrings(
     members.map(member => member.inputModalities ?? ["text"]),
   );
-  const reasoningEfforts = intersectStrings(
-    members.map(member => member.reasoningEfforts ?? []),
-  );
+  const inputModalities = combo.imageInput === "disabled"
+    ? derivedInputModalities.filter(modality => modality !== "image")
+    : derivedInputModalities;
+  if (inputModalities.length === 0) return null;
+  // Unknown ladders (`undefined`) are wildcards for catalog derivation — same
+  // boundary as the GUI picker. An explicit empty ladder still constrains.
+  const advertisedLadders = members
+    .map(member => member.reasoningEfforts)
+    .filter((ladder): ladder is string[] => ladder !== undefined);
+  const reasoningEfforts = advertisedLadders.length === 0
+    ? []
+    : intersectStrings(advertisedLadders);
   const contextWindow = Math.min(...members.map(member => member.contextWindow!));
+  const limitingMembers = members.filter(member => member.contextWindow === contextWindow);
+  const hasLimitingContextCapMetadata = limitingMembers.some(
+    member => typeof member.contextCapped === "boolean",
+  );
+  // A combo is cap-limited only when every member defining its effective minimum was
+  // itself reduced by a provider cap. An uncapped member at the same minimum means the
+  // combo would have the same window even without the cap.
+  const contextCapped = limitingMembers.every(member => member.contextCapped === true);
   const maxInputTokens = Math.min(
     ...members.map(member => member.maxInputTokens ?? member.contextWindow!),
   );
@@ -149,14 +167,25 @@ export function deriveComboCatalogModel(
     owned_by: COMBO_NAMESPACE,
     contextWindow,
     maxInputTokens,
+    ...(hasLimitingContextCapMetadata ? { contextCapped } : {}),
     inputModalities,
     reasoningEfforts,
     ...(combo.alias ? { alias: combo.alias } : {}),
+    ...(combo.nativeAlias ? { nativeAlias: true } : {}),
+    ...(combo.displayName ? { displayName: combo.displayName } : {}),
     ...(defaultReasoningEffort ? { defaultReasoningEffort } : {}),
     ...(members.every(member => member.parallelToolCalls === true)
       ? { parallelToolCalls: true }
       : {}),
+    ...(members.every(member => member.supportsServiceTier === true)
+      ? { supportsServiceTier: true }
+      : members.some(member => member.supportsServiceTier === false)
+        ? { supportsServiceTier: false }
+        : {}),
     ...(members.some(member => member.supportsReasoningSummaries === false) ? { supportsReasoningSummaries: false } : {}),
+    ...(members.every(member => member.codexToolMode === "shell")
+      ? { codexToolMode: "shell" as const }
+      : {}),
   };
 }
 
@@ -252,12 +281,15 @@ export function exactComboCatalogSlugs(
 ): 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 raw = config.combos?.[id];
+    const alias = typeof raw?.alias === "string"
+      ? raw.alias.trim()
       : "";
     const canonical = comboModelId(id);
     const publicSlug = alias || canonical;
-    return disabled.has(publicSlug) || disabled.has(canonical) ? [] : [publicSlug];
+    const comboDisabled = comboDisabledModelSelectors(id, raw ?? {})
+      .some(selector => disabled.has(selector));
+    return comboDisabled ? [] : [publicSlug];
   }));
 }
 
@@ -281,6 +313,10 @@ export function resetOpenAiApiCatalogWarningStateForTests(): void {
 export const slugAliasCollisionWarnings = new Set<string>();
 
 export const comboMasqueradeCollisionWarnings = new Set<string>();
+
+export const comboUnrestorableShadowWarnings = new Set<string>();
+
+export const accountSelectorShadowCollisionWarnings = new Set<string>();
 let lastWarningReconciledGeneration = 0;
 
 export function reconcileCatalogWarningMemos(generation: number): number {
@@ -288,11 +324,15 @@ export function reconcileCatalogWarningMemos(generation: number): number {
   const removed = openAiApiCollisionWarnings.size
     + comboCatalogWarningSignatures.size
     + slugAliasCollisionWarnings.size
-    + comboMasqueradeCollisionWarnings.size;
+    + comboMasqueradeCollisionWarnings.size
+    + comboUnrestorableShadowWarnings.size
+    + accountSelectorShadowCollisionWarnings.size;
   openAiApiCollisionWarnings.clear();
   comboCatalogWarningSignatures.clear();
   slugAliasCollisionWarnings.clear();
   comboMasqueradeCollisionWarnings.clear();
+  comboUnrestorableShadowWarnings.clear();
+  accountSelectorShadowCollisionWarnings.clear();
   lastWarningReconciledGeneration = generation;
   return removed;
 }
@@ -305,6 +345,24 @@ export function warnComboMasqueradeCollisionOnce(slug: string): void {
   );
 }
 
+export function warnComboUnrestorableShadowOnce(slug: string): void {
+  const key = slugEquivalenceKey(slug);
+  if (comboUnrestorableShadowWarnings.has(key)) return;
+  comboUnrestorableShadowWarnings.add(key);
+  console.warn(
+    `[opencodex] combo alias collision on "${safeCatalogWarningLabel(slug)}": the existing user-managed or foreign catalog row is retained because no pristine backup can restore it. Rename the combo alias to expose both models.`,
+  );
+}
+
+/** Warn once when a live provider row loses its reserved slug to an account selector. */
+export function warnAccountSelectorShadowedProviderOnce(slug: string): void {
+  if (accountSelectorShadowCollisionWarnings.has(slug)) return;
+  accountSelectorShadowCollisionWarnings.add(slug);
+  console.warn(
+    `[opencodex] account selector collision on "${safeCatalogWarningLabel(slug)}": the account-bound native model wins and the shadowed provider model is omitted from the catalog. Rename the provider or account selector.`,
+  );
+}
+
 export function resolveSlugAliasCollisions(goModels: CatalogModel[]): Set<CatalogModel> {
   const skipped = new Set<CatalogModel>();
   const winnerByAlias = new Map<string, CatalogModel>();

package/src/codex/catalog/bundled.ts

@@ -9,7 +9,7 @@ import { buildModelsRequest, resolveModelsAuthToken } from "../../oauth";
 import type { OcxConfig, OcxProviderConfig } from "../../types";
 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 { getModelMetadata, getModelMetadataCaseInsensitive, listModelMetadata, resolveMetadataProvider } from "../../generated/model-metadata";
 import { enrichProviderFromRegistry, shouldCaseFoldMetadataModelId } from "../../providers/derive";
 import { getProviderRegistryEntry } from "../../providers/registry";
 import { applyProviderContextCap, providerContextCap } from "../../providers/context-cap";
@@ -34,28 +34,121 @@ import upstreamModelsSnapshot from "../data/upstream-models.json";
 import { activeCodexModelsCachePath, catalogBackupPathFor, findNativeTemplate, isDefaultCatalogPath, legacyCatalogBackupPath, parseCatalogJson, readCatalog, readCatalogBackup, readCodexCatalogPath } from "./parsing";
 import type { RawCatalog, RawEntry } from "./parsing";
 import { codexExecInvocation, isSpawnableCodexCandidate } from "../exec-invocation";
-import { resolveAndPersistCodexRuntime } from "../runtime";
-import type { EffortClampDiagnostic } from "../runtime";
+import {
+  parsePersistedCodexRuntime,
+  peekCodexRuntimeProcessCache,
+  resolveAndPersistCodexRuntime,
+} from "../runtime";
+import type {
+  DeepReadonly,
+  EffortClampDiagnostic,
+  ResolvedCodexRuntime,
+} from "../runtime";
+import type {
+  CatalogGatherEvidenceSession,
+  CatalogGatherReadableSourceRole,
+} from "./filesystem-evidence";
 
 export { isSpawnableCodexCandidate, codexExecInvocation } from "../exec-invocation";
+export type {
+  CatalogGatherEvidenceSession,
+  CatalogGatherReadableSourceRole,
+} from "./filesystem-evidence";
 
 export const BUNDLED_CATALOG_CACHE_MS = 60_000;
 
-export let bundledCatalogCache: {
+export type ReadonlyRawCatalog = DeepReadonly<RawCatalog>;
+
+interface BundledCatalogMemo {
   /** Selected runtime identity; must change when doctor/sync picks a different binary. */
-  key: string;
-  expiresAt: number;
-  value: RawCatalog | null;
-} | null = null;
+  readonly key: string;
+  readonly expiresAt: number;
+  readonly epoch: number;
+  readonly valueIdentity: string;
+  readonly value: ReadonlyRawCatalog | null;
+}
+
+export interface BundledCatalogCacheState {
+  readonly epoch: number;
+  readonly valueIdentity: string | null;
+}
+
+let bundledCatalogEpoch = 0;
+let bundledCatalogCache: BundledCatalogMemo | null = null;
+
+function cloneAndDeepFreeze<T>(value: T): DeepReadonly<T> {
+  const clone = (current: unknown): unknown => {
+    if (Array.isArray(current)) return current.map(clone);
+    if (current && typeof current === "object") {
+      const out: Record<string, unknown> = {};
+      for (const [key, child] of Object.entries(current)) out[key] = clone(child);
+      return out;
+    }
+    return current;
+  };
+  const freeze = (current: unknown): unknown => {
+    if (!current || typeof current !== "object" || Object.isFrozen(current)) return current;
+    for (const child of Object.values(current)) freeze(child);
+    return Object.freeze(current);
+  };
+  return freeze(clone(value)) as DeepReadonly<T>;
+}
+
+function bundledRuntimeKey(
+  runtime: Pick<ResolvedCodexRuntime, "command" | "version">,
+  opencodexHome: string = process.env.OPENCODEX_HOME ?? "",
+): string {
+  return [runtime.command, runtime.version ?? "", opencodexHome].join("\0");
+}
+
+function publishBundledCatalogCache(
+  key: string,
+  expiresAt: number,
+  value: RawCatalog | null,
+): void {
+  const epoch = ++bundledCatalogEpoch;
+  bundledCatalogCache = {
+    key,
+    expiresAt,
+    epoch,
+    valueIdentity: `bundled:${epoch}`,
+    value: value === null ? null : cloneAndDeepFreeze(value),
+  };
+}
+
+function clearBundledCatalogCache(): void {
+  bundledCatalogEpoch += 1;
+  bundledCatalogCache = null;
+}
+
+export function bundledCatalogCacheState(): Readonly<BundledCatalogCacheState> {
+  return Object.freeze({
+    epoch: bundledCatalogEpoch,
+    valueIdentity: bundledCatalogCache?.valueIdentity ?? null,
+  });
+}
 
 /** Test-only: clear the bundled-catalog cache (owned here; sync.ts calls this instead of assigning the import). */
 export function resetBundledCatalogCacheForTests(): void {
-  bundledCatalogCache = null;
+  clearBundledCatalogCache();
 }
 
 /** Drop the process-local bundled catalog memo (e.g. after runtime selection changes). */
 export function invalidateBundledCatalogCache(): void {
-  bundledCatalogCache = null;
+  clearBundledCatalogCache();
+}
+
+/** Test-only owner mutation seam; input is cloned and frozen before publication. */
+export function setBundledCatalogCacheForTests(
+  runtime: Pick<ResolvedCodexRuntime, "command" | "version">,
+  value: RawCatalog | null,
+  options: Readonly<{ expiresAt?: number; opencodexHome?: string }> = {},
+): void {
+  publishBundledCatalogCache(
+    bundledRuntimeKey(runtime, options.opencodexHome),
+    options.expiresAt ?? Date.now() + BUNDLED_CATALOG_CACHE_MS,
+    value,
+  );
 }
 
 export type ExecFile = (
@@ -143,7 +236,7 @@ export function runCodexDebugModels(
   });
 }
 
-export function loadBundledCodexCatalog(deps: BundledCatalogDeps = {}): RawCatalog | null {
+export function loadBundledCodexCatalog(deps: BundledCatalogDeps = {}): ReadonlyRawCatalog | null {
   const useCache = !deps.commandCandidates && !deps.execFileSync && !deps.configDir && !deps.env;
   const execFile = deps.execFileSync ?? (execFileSync as unknown as ExecFile);
   // Prefer the single resolved runtime so sync/clamp never probe a different binary
@@ -168,11 +261,7 @@ export function loadBundledCodexCatalog(deps: BundledCatalogDeps = {}): RawCatal
       discoverAlternatives: deps.discoverAlternatives ?? false,
     });
     if (useCache) {
-      cacheKey = [
-        resolved.runtime.command,
-        resolved.runtime.version ?? "",
-        process.env.OPENCODEX_HOME ?? "",
-      ].join("\0");
+      cacheKey = bundledRuntimeKey(resolved.runtime);
     }
     return [resolved.runtime.command];
   })();
@@ -183,33 +272,225 @@ export function loadBundledCodexCatalog(deps: BundledCatalogDeps = {}): RawCatal
     && bundledCatalogCache.key === cacheKey
     && bundledCatalogCache.expiresAt > Date.now()
   ) {
-    return bundledCatalogCache.value;
+    return bundledCatalogCache.value === null
+      ? null
+      : cloneAndDeepFreeze(bundledCatalogCache.value);
   }
   for (const command of unique(candidates)) {
     try {
       const catalog = parseCatalogJson(runCodexDebugModels(command, execFile, deps));
       if (catalog && findNativeTemplate(catalog)) {
         if (useCache && cacheKey) {
-          bundledCatalogCache = {
-            key: cacheKey,
-            expiresAt: Date.now() + BUNDLED_CATALOG_CACHE_MS,
-            value: catalog,
-          };
+          publishBundledCatalogCache(
+            cacheKey,
+            Date.now() + BUNDLED_CATALOG_CACHE_MS,
+            catalog,
+          );
+          return cloneAndDeepFreeze(bundledCatalogCache!.value!);
         }
-        return catalog;
+        return cloneAndDeepFreeze(catalog);
       }
     } catch { /* try next candidate */ }
   }
   if (useCache && cacheKey) {
-    bundledCatalogCache = {
-      key: cacheKey,
-      expiresAt: Date.now() + BUNDLED_CATALOG_CACHE_MS,
-      value: null,
-    };
+    publishBundledCatalogCache(
+      cacheKey,
+      Date.now() + BUNDLED_CATALOG_CACHE_MS,
+      null,
+    );
   }
   return null;
 }
 
+export type CatalogGatherProcessLocalObservation =
+  | Readonly<{ state: "unused" }>
+  | Readonly<{ state: "used"; epoch: number; valueIdentity: string }>;
+
+export type CodexRuntimeForCatalogGather =
+  | Readonly<{
+      kind: "available";
+      origin: "process-cache" | "persisted";
+      runtime: DeepReadonly<ResolvedCodexRuntime>;
+      processLocal: CatalogGatherProcessLocalObservation;
+    }>
+  | Readonly<{
+      kind: "runtime-unavailable";
+      processLocal: Readonly<{ state: "unused" }>;
+    }>;
+
+export type CatalogSourceForGather =
+  | Readonly<{
+      kind: "available";
+      source:
+        | "bundled-catalog-template"
+        | "active-catalog-merge"
+        | "hashed-backup-fallback"
+        | "legacy-backup-fallback"
+        | "models-cache-fallback";
+      catalog: ReadonlyRawCatalog;
+      runtimeSupport:
+        | Readonly<{ kind: "available"; catalog: ReadonlyRawCatalog }>
+        | Readonly<{ kind: "unavailable" }>;
+      processLocal: Readonly<{
+        runtime: CatalogGatherProcessLocalObservation;
+        bundledCatalog: CatalogGatherProcessLocalObservation;
+      }>;
+    }>
+  | Readonly<{
+      kind: "catalog-unavailable";
+      processLocal: Readonly<{
+        runtime: Readonly<{ state: "unused" }>;
+        bundledCatalog: Readonly<{ state: "unused" }>;
+      }>;
+    }>;
+
+export type CatalogGatherPathKind = "default" | "custom";
+
+const UNUSED_PROCESS_LOCAL = Object.freeze({ state: "unused" as const });
+
+function sameRuntimeIdentity(
+  left: Pick<ResolvedCodexRuntime, "command" | "version">,
+  right: Pick<ResolvedCodexRuntime, "command" | "version">,
+): boolean {
+  return left.command === right.command && (left.version ?? null) === (right.version ?? null);
+}
+
+/**
+ * Observe an already-resolved runtime only. The evidence owner supplies the
+ * exact persisted bytes (or observed absence); this path never probes or writes.
+ */
+export function peekCodexRuntimeForCatalogGather(
+  evidenceSession: CatalogGatherEvidenceSession,
+): CodexRuntimeForCatalogGather {
+  const persistedBytes = evidenceSession.readSource("runtime-selection");
+  const persisted = persistedBytes === null
+    ? null
+    : parsePersistedCodexRuntime(persistedBytes);
+  const processMemo = peekCodexRuntimeProcessCache();
+
+  if (processMemo.kind === "available") {
+    const runtime = processMemo.value.runtime;
+    if (persistedBytes === null || (persisted && sameRuntimeIdentity(runtime, {
+      command: persisted.command,
+      version: persisted.selectedVersion ?? null,
+    }))) {
+      return cloneAndDeepFreeze({
+        kind: "available" as const,
+        origin: "process-cache" as const,
+        runtime,
+        processLocal: {
+          state: "used" as const,
+          epoch: processMemo.epoch,
+          valueIdentity: processMemo.valueIdentity,
+        },
+      });
+    }
+  }
+
+  if (persisted) {
+    return cloneAndDeepFreeze({
+      kind: "available" as const,
+      origin: "persisted" as const,
+      runtime: {
+        command: persisted.command,
+        version: persisted.selectedVersion ?? null,
+        source: persisted.source,
+      },
+      processLocal: UNUSED_PROCESS_LOCAL,
+    });
+  }
+
+  return Object.freeze({
+    kind: "runtime-unavailable" as const,
+    processLocal: UNUSED_PROCESS_LOCAL,
+  });
+}
+
+/**
+ * Resolve only already-observed catalog sources. A cold process cache falls
+ * through to evidence-owned persisted sources and never becomes probe authority.
+ */
+export function resolveCatalogSourceForGather(
+  evidenceSession: CatalogGatherEvidenceSession,
+  pathKind: CatalogGatherPathKind,
+): CatalogSourceForGather {
+  const bundledMemo = bundledCatalogCache;
+  let runtimeSupport:
+    | Readonly<{ kind: "available"; catalog: ReadonlyRawCatalog }>
+    | Readonly<{ kind: "unavailable" }> = Object.freeze({ kind: "unavailable" });
+  let processLocal: Readonly<{
+    runtime: CatalogGatherProcessLocalObservation;
+    bundledCatalog: CatalogGatherProcessLocalObservation;
+  }> = {
+    runtime: UNUSED_PROCESS_LOCAL,
+    bundledCatalog: UNUSED_PROCESS_LOCAL,
+  };
+  if (bundledMemo?.value && bundledMemo.expiresAt > Date.now()) {
+    const runtime = peekCodexRuntimeForCatalogGather(evidenceSession);
+    if (runtime.kind === "available" && bundledMemo.key === bundledRuntimeKey(runtime.runtime)) {
+      runtimeSupport = Object.freeze({
+        kind: "available" as const,
+        catalog: bundledMemo.value,
+      });
+      processLocal = {
+        runtime: runtime.processLocal,
+        bundledCatalog: {
+          state: "used" as const,
+          epoch: bundledMemo.epoch,
+          valueIdentity: bundledMemo.valueIdentity,
+        },
+      };
+      if (pathKind === "default") {
+        return cloneAndDeepFreeze({
+          kind: "available" as const,
+          source: "bundled-catalog-template" as const,
+          catalog: bundledMemo.value,
+          runtimeSupport,
+          processLocal,
+        });
+      }
+    }
+  }
+
+  const roles = pathKind === "default"
+    ? [
+        "active-catalog-merge",
+        "hashed-backup-fallback",
+        "legacy-backup-fallback",
+        "models-cache-fallback",
+      ] as const
+    : [
+        "active-catalog-merge",
+        "hashed-backup-fallback",
+        "models-cache-fallback",
+      ] as const;
+  for (const role of roles) {
+    const bytes = evidenceSession.readSource(role);
+    if (bytes === null) continue;
+    const catalog = parseCatalogJson(Buffer.from(bytes).toString("utf8"));
+    if (!catalog) continue;
+    // Custom catalogs may intentionally contain only routed rows. Keep their existing source
+    // priority (active, then backup/cache) without imposing the default catalog's native-template
+    // requirement; a valid active custom file therefore remains authoritative over stale fallbacks.
+    if (pathKind === "default" && !findNativeTemplate(catalog)) continue;
+    return cloneAndDeepFreeze({
+      kind: "available" as const,
+      source: role,
+      catalog,
+      runtimeSupport,
+      processLocal,
+    });
+  }
+
+  return Object.freeze({
+    kind: "catalog-unavailable" as const,
+    processLocal: Object.freeze({
+      runtime: UNUSED_PROCESS_LOCAL,
+      bundledCatalog: UNUSED_PROCESS_LOCAL,
+    }),
+  });
+}
+
 export function materializeBundledCodexCatalog(path: string, deps: BundledCatalogDeps = {}): RawCatalog | null {
   const catalog = loadBundledCodexCatalog(deps);
   if (!catalog) return null;
@@ -219,7 +500,7 @@ export function materializeBundledCodexCatalog(path: string, deps: BundledCatalo
   } catch {
     return null;
   }
-  return catalog;
+  return JSON.parse(JSON.stringify(catalog)) as RawCatalog;
 }
 
 export function loadCatalogForSync(path: string): RawCatalog | null {
@@ -236,16 +517,33 @@ export function loadCatalogForSync(path: string): RawCatalog | null {
 
 export function readCurrentCatalogOrCache(): RawCatalog | null {
   const path = readCodexCatalogPath();
-  return (isDefaultCatalogPath(path) ? loadBundledCodexCatalog() : null)
-    ?? readCatalog(path)
-    ?? readCatalog(activeCodexModelsCachePath());
+  const bundled = isDefaultCatalogPath(path) ? loadBundledCodexCatalog() : null;
+  if (bundled) return JSON.parse(JSON.stringify(bundled)) as RawCatalog;
+  return readCatalog(path) ?? readCatalog(activeCodexModelsCachePath());
+}
+
+/**
+ * Read the user-owned Codex catalog surfaces without substituting the bundled catalog.
+ *
+ * The bundled catalog is intentionally the authority for static native metadata on the default
+ * path. Account-qualified discovery needs the opposite view: an exact model id that Codex has
+ * observed in the user's catalog/cache may be account-scoped even when this release does not know
+ * it statically yet.
+ */
+export function readCurrentCodexCatalog(): RawCatalog | null {
+  return readCatalog(readCodexCatalogPath());
+}
+
+export function readCurrentCodexModelsCache(): RawCatalog | null {
+  return readCatalog(activeCodexModelsCachePath());
 }
 
 export function loadCatalogTemplate(): RawEntry | null {
   const catalogPath = readCodexCatalogPath();
+  const bundled = loadBundledCodexCatalog();
   const native = findNativeTemplate(readCatalog(catalogPath))
     ?? findNativeTemplate(readCatalogBackup(catalogPath))
     ?? findNativeTemplate(readCatalog(activeCodexModelsCachePath()))
-    ?? findNativeTemplate(loadBundledCodexCatalog());
+    ?? findNativeTemplate(bundled ? JSON.parse(JSON.stringify(bundled)) as RawCatalog : null);
   return native ? JSON.parse(JSON.stringify(native)) : null;
 }