@bitkyc08/opencodex 2.11.0 → 2.11.1

package/src/codex/catalog-refresh-status.ts

@@ -0,0 +1,87 @@
+import type { CatalogDisposition, CatalogNotice } from "./convergence-types";
+
+const INVALID_CATALOG_DISPOSITION_FIELD = Symbol("invalid-catalog-disposition-field");
+
+/** Read an own data property without invoking prototype getters or accessors. */
+function ownDataProperty(value: object, key: PropertyKey): unknown {
+  const descriptor = Object.getOwnPropertyDescriptor(value, key);
+  return descriptor && "value" in descriptor
+    ? descriptor.value
+    : INVALID_CATALOG_DISPOSITION_FIELD;
+}
+
+/** Accept only the public catalog degradation codes. */
+function isCatalogNotice(value: unknown): value is CatalogNotice {
+  return value === "provider-auth" || value === "provider-network" || value === "fallback";
+}
+
+/** Copy a bounded notice array without trusting accessors or a custom iterator. */
+function normalizeCatalogNotices(value: unknown): CatalogNotice[] | null {
+  if (!Array.isArray(value)) return null;
+  const length = ownDataProperty(value, "length");
+  if (typeof length !== "number" || !Number.isInteger(length) || length < 0 || length > 3) {
+    return null;
+  }
+  const notices: CatalogNotice[] = [];
+  for (let index = 0; index < length; index += 1) {
+    const notice = ownDataProperty(value, String(index));
+    if (!isCatalogNotice(notice)) return null;
+    notices.push(notice);
+  }
+  return notices;
+}
+
+/**
+ * Rebuild a catalog disposition from a strict set of own data properties.
+ *
+ * Management callbacks are internal today, but this response is a privacy
+ * boundary. Avoid coercion, accessors, custom iterators, and `toJSON` hooks so a
+ * malformed callback cannot smuggle private provider or account detail into a
+ * management response.
+ */
+export function normalizeCatalogDisposition(value: unknown): CatalogDisposition | null {
+  if (value === null || typeof value !== "object") return null;
+  try {
+    if (Array.isArray(value)) return null;
+    const status = ownDataProperty(value, "status");
+    if (status === "committed") {
+      const changed = ownDataProperty(value, "changed");
+      const degraded = ownDataProperty(value, "degraded");
+      const notices = normalizeCatalogNotices(ownDataProperty(value, "notices"));
+      if (typeof changed !== "boolean" || typeof degraded !== "boolean" || notices === null) {
+        return null;
+      }
+      return { status, changed, degraded, notices };
+    }
+    if (status === "skipped") {
+      const reason = ownDataProperty(value, "reason");
+      const retryable = ownDataProperty(value, "retryable");
+      if ((reason !== "not-requested"
+        && reason !== "catalog-unavailable"
+        && reason !== "busy"
+        && reason !== "stale"
+        && reason !== "refused")
+        || typeof retryable !== "boolean") return null;
+      return { status, reason, retryable };
+    }
+    if (status === "failed") {
+      const reason = ownDataProperty(value, "reason");
+      const phase = ownDataProperty(value, "phase");
+      const retryable = ownDataProperty(value, "retryable");
+      const partialWrite = ownDataProperty(value, "partialWrite");
+      if ((reason !== "provider-auth" && reason !== "provider-network" && reason !== "disk")
+        || (phase !== "gather" && phase !== "commit")
+        || typeof retryable !== "boolean"
+        || typeof partialWrite !== "boolean") return null;
+      return { status, reason, phase, retryable, partialWrite };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/** Whether a persisted mutation still needs a successful catalog commit. */
+export function catalogRefreshIsPending(disposition: CatalogDisposition): boolean {
+  return disposition.status !== "committed";
+}

package/src/codex/catalog-write-serialization.ts

@@ -32,6 +32,7 @@ import {
   CodexUserIdentityRefusal,
   resolveCodexCatalogSerializationDatabasePath,
   resolveEffectiveUserIdentity,
+  samePathIdentity,
 } from "./user-identity";
 
 /**
@@ -180,7 +181,7 @@ export function withCatalogWriteSerialization<T>(
     }
     const opened = lstatSync(databasePath);
     if (opened.isSymbolicLink() || !opened.isFile()
-      || realpathSync.native(databasePath) !== databasePath) {
+      || !samePathIdentity(realpathSync.native(databasePath), databasePath)) {
       return { kind: "unavailable", reason: "unsafe-path" };
     }
 

package/src/codex/catalog.ts

@@ -2,12 +2,13 @@
 // 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 { NATIVE_OPENAI_MODELS, 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, 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, augmentRoutedModelsWithJawcodeMetadata } from "./catalog/provider-fetch";
+export { applyProviderConfigHints, isDatedVariantId, filterCatalogVisibleModels, gatherRoutedModels, clearGatherRoutedModelsInflight, augmentRoutedModelsWithRegistryOpenAiApiRows, augmentRoutedModelsWithMetadata, resolveComboCatalogMember } 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";
+export { MAX_SPAWN_AGENT_MODEL_OVERRIDES, CANONICAL_NATIVE_CATALOG_CONTENT_POLICY, effectiveSubagentRoster, buildCatalogEntries, mergeCatalogEntriesFromObservedState, resetCatalogRuntimeStateForTests, orderForSubagents, mergeCatalogEntriesForSync, syncCatalogModels, restoreCodexCatalog, invalidateCodexModelsCache } from "./catalog/sync";
+export type { ObservedCatalogMergeInput } from "./catalog/sync";
 export type { SpawnAgentSurface, SubagentRosterExclusionReason, EffectiveSubagentModel, SubagentRosterExclusion, EffectiveSubagentRoster } from "./catalog/sync";
 export { accountBoundNativeDisplayName, accountBoundNativeModelSlugs, CODEX_ACCOUNT_BOUND_CATALOG_KIND, trustedAccountBoundNativeCatalogSlug, visibleCodexAccountSelectors } from "./catalog/account-models";

package/src/codex/convergence-types.ts

@@ -422,7 +422,7 @@ export interface CatalogProviderDiscoveryPolicySnapshot {
     readonly path: CatalogDiscoveryPolicyField<string | undefined>;
     readonly query: CatalogDiscoveryPolicyField<Readonly<Record<string, string>> | undefined>;
   }>;
-  readonly finalMethod: "GET";
+  readonly finalMethod: "GET" | "POST";
   readonly finalUrl: string;
   readonly filter: CatalogDiscoveryPolicyField<ProviderModelDiscoveryFilter | undefined>;
   readonly maxResponseBytes: number;

package/src/codex/convergence.ts

@@ -2,16 +2,17 @@ import { join } from "node:path";
 
 import { getConfigDir, websocketsEnabled, withExpectedConfigGenerationSync } from "../config";
 import { COMBO_NAMESPACE } from "../combos";
-import { isCanonicalOpenAiForwardProvider } from "../providers/openai-tiers";
 import { getAuthStorePath } from "../oauth/store";
 import type { OcxConfig } from "../types";
 import { captureCatalogAdmissionSnapshot } from "./catalog-admission";
+import { legacyCustomModelCatalogSlugs } from "./custom-model-catalog-migration";
 import {
+  type CatalogGatherPathKind,
   type CatalogSourceForGather,
   bundledCatalogCacheState,
   resolveCatalogSourceForGather,
-} from "./catalog/bundled";
-import {
+  } from "./catalog/bundled";
+  import {
   acceptCatalogGatherSourcePath,
   captureAndSealCatalogHomeSelection,
   captureCatalogGatherTargetIdentity,
@@ -19,28 +20,49 @@ import {
   readCatalogGatherSource,
   sealCatalogGatherEvidenceSession,
   type CatalogFilesystemEvidenceSession,
-} from "./catalog/filesystem-evidence";
-import {
+  } from "./catalog/filesystem-evidence";
+  import {
   CatalogGatherBusyError,
   createCatalogGatherAuthorityIdentity,
   filterCatalogVisibleModels,
   gatherRoutedModelsForCatalogGather,
   type CatalogGatherProviderAuthOutcome,
-} from "./catalog/provider-fetch";
-import {
+  type CatalogGatherProviderModelOutcome,
+  } from "./catalog/provider-fetch";
+  import {
   catalogBackupPathFor,
   catalogHasRoutedEntries,
   findNativeTemplate,
   legacyCatalogBackupPath,
   parseCatalogJson,
   type RawCatalog,
-} from "./catalog/parsing";
-import {
-  buildCatalogEntries,
+  type RawEntry,
+  } from "./catalog/parsing";
+  import {
+  buildCatalogEntriesFromObservedState,
+  CANONICAL_NATIVE_CATALOG_CONTENT_POLICY,
+  mergeCatalogEntriesFromObservedState,
+  mergeCatalogModelsWithNativeRecovery,
   orderForSubagents,
-} from "./catalog/sync";
-import { exactComboCatalogSlugs } from "./catalog/aggregation";
-import { disabledNativeSlugs } from "./catalog/metadata";
+  } from "./catalog/sync";
+  import { multiAgentV2EnabledFromConfigText } from "./features";
+  import { exactComboCatalogSlugs } from "./catalog/aggregation";
+  import {
+  isNativeAliasCatalogEntry,
+  disabledNativeSlugs,
+  desktopAllowlistSuppressedNativeSlugs,
+  NATIVE_OPENAI_MODELS,
+  shouldIncludeAccountBoundNativeOpenAi,
+  shouldIncludeNativeOpenAi,
+} from "./catalog/metadata";
+import {
+  trustedAccountBoundNativeCatalogSlug,
+  visibleCodexAccountSelectors,
+} from "./catalog/account-models";
+import {
+  clampCatalogModelsToObservedCodexSupport,
+  supportedCodexReasoningEffortsFromObservedCatalog,
+} from "./catalog/effort";
 import { codexRuntimeStatePath, peekCodexRuntimeProcessCache } from "./runtime";
 import { withCatalogWriteSerialization } from "./catalog-write-serialization";
 import {
@@ -119,12 +141,23 @@ function catalogBytes(catalog: RawCatalog): string {
   return `${JSON.stringify(catalog, null, 2)}\n`;
 }
 
+function nativePriorityBaseline(catalog: ReadonlyRawCatalogLike | null): Map<string, number> {
+  return new Map((catalog?.models ?? []).flatMap(entry => (
+    typeof entry.slug === "string"
+      && !entry.slug.includes("/")
+      && typeof entry.priority === "number"
+      ? [[entry.slug, entry.priority] as const]
+      : []
+  )));
+}
+
 interface ReadonlyRawCatalogLike {
   readonly models?: readonly Readonly<Record<string, unknown>>[];
 }
 
 function hasRoutedEntries(catalog: ReadonlyRawCatalogLike): boolean {
-  return (catalog.models ?? []).some(entry => typeof entry.slug === "string" && entry.slug.includes("/"));
+  return (catalog.models ?? []).some(entry => typeof entry.slug === "string"
+    && (entry.slug.includes("/") || isNativeAliasCatalogEntry(entry as RawEntry)));
 }
 
 function processEvidence(source: CatalogSourceForGather): CatalogProcessLocalEvidence {
@@ -137,7 +170,14 @@ function processEvidence(source: CatalogSourceForGather): CatalogProcessLocalEvi
 function bindGatherPaths(
   session: CatalogFilesystemEvidenceSession,
   snapshot: CatalogAdmissionSnapshot,
-): Readonly<{ catalog: string; cache: string; keyedBackup: string; legacyBackup?: string }> {
+): Readonly<{
+  catalog: string;
+  cache: string;
+  keyedBackup: string;
+  legacyBackup?: string;
+  catalogKind: CatalogGatherPathKind;
+  multiAgentV2Enabled: boolean;
+}> {
   const catalog = targetPath(snapshot.targets.catalog);
   const cache = targetPath(snapshot.targets.cache);
   const keyedBackup = targetPath(snapshot.targets.catalogBackups[0]!);
@@ -146,7 +186,7 @@ function bindGatherPaths(
   const configPath = snapshot.sourceEvidence.required["catalog-target-selection"].logicalPath;
 
   acceptCatalogGatherSourcePath(session, "catalog-target-selection", configPath);
-  readCatalogGatherSource(session, "catalog-target-selection");
+  const configBytes = readCatalogGatherSource(session, "catalog-target-selection");
   acceptCatalogGatherSourcePath(session, "active-catalog-merge", catalog);
   acceptCatalogGatherSourcePath(session, "hashed-backup-fallback", keyedBackup);
   acceptCatalogGatherSourcePath(session, "legacy-backup-fallback", legacyBackup ?? legacyCatalogBackupPath());
@@ -154,7 +194,16 @@ function bindGatherPaths(
   acceptCatalogGatherSourcePath(session, "runtime-selection", codexRuntimeStatePath(getConfigDir()));
   acceptCatalogGatherSourcePath(session, "provider-auth-selection", getAuthStorePath());
   acceptCatalogGatherSourcePath(session, "native-catalog-selection", catalog);
-  return { catalog, cache, keyedBackup, ...(legacyBackup ? { legacyBackup } : {}) };
+  return {
+    catalog,
+    cache,
+    keyedBackup,
+    ...(legacyBackup ? { legacyBackup } : {}),
+    catalogKind: legacyBackup ? "default" : "custom",
+    multiAgentV2Enabled: multiAgentV2EnabledFromConfigText(
+      configBytes === null ? null : Buffer.from(configBytes).toString("utf8"),
+    ),
+  };
 }
 
 function prepareCatalog(
@@ -162,6 +211,11 @@ function prepareCatalog(
   source: Extract<CatalogSourceForGather, { kind: "available" }>,
   active: RawCatalog | null,
   routedModels: Awaited<ReturnType<typeof gatherRoutedModelsForCatalogGather>>,
+  multiAgentV2Enabled: boolean,
+  baseline: ReadonlyMap<string, number>,
+  baselineCatalogModels: readonly Readonly<Record<string, unknown>>[],
+  degradedProviderNames: ReadonlySet<string>,
+  nativeRecoverySources: readonly (readonly RawEntry[])[] = [],
 ): RawCatalog {
   const catalog = JSON.parse(JSON.stringify(source.catalog)) as RawCatalog;
   const template = findNativeTemplate(catalog);
@@ -171,41 +225,87 @@ function prepareCatalog(
   const multiAgentMode = config.multiAgentMode === "v1" || config.multiAgentMode === "v2"
     ? config.multiAgentMode : "default";
   const exactComboSlugs = exactComboCatalogSlugs(config);
+  const suppressedBareNativeSlugs = desktopAllowlistSuppressedNativeSlugs(config);
   const hasPhysicalComboProvider = Object.hasOwn(config.providers, COMBO_NAMESPACE);
   const enabledProviders = Object.entries(config.providers).filter(([, provider]) => provider.disabled !== true);
-  const includeNativeOpenAi = enabledProviders.length === 0 || enabledProviders.some(([name, provider]) => (
-    name === "openai" && isCanonicalOpenAiForwardProvider(provider)
-  ));
-  const disabledNative = disabledNativeSlugs(config);
-  const nativeSlugs = includeNativeOpenAi
-    ? [...new Set((active?.models ?? catalog.models ?? []).flatMap(entry => (
-        typeof entry.slug === "string" && !entry.slug.includes("/") && !disabledNative.has(entry.slug)
-          ? [entry.slug] : []
-      )))]
+  const includeNativeOpenAi = shouldIncludeNativeOpenAi(config);
+  const accountSelectors = shouldIncludeAccountBoundNativeOpenAi(config)
+    ? visibleCodexAccountSelectors(config)
     : [];
-  const entries = buildCatalogEntries(
-    template ? JSON.parse(JSON.stringify(template)) : null,
-    nativeSlugs, ordered, featured, websocketsEnabled(config), multiAgentMode, exactComboSlugs,
+  const disabledNative = disabledNativeSlugs(config);
+  const nativeCatalogModels = mergeCatalogModelsWithNativeRecovery(
+    active?.models ?? catalog.models ?? [],
+    [catalog.models ?? [], ...nativeRecoverySources],
   );
-  if (entries.length === nativeSlugs.length) {
-    const configuredProviders = new Set(enabledProviders.map(([name]) => name));
-    const preserved = (active?.models ?? []).filter(entry => {
-      if (typeof entry.slug !== "string" || !entry.slug.includes("/")) return false;
-      const provider = entry.slug.slice(0, entry.slug.indexOf("/"));
-      const description = typeof entry.description === "string" ? entry.description : "";
-      return configuredProviders.has(provider) || !description.startsWith("Routed via opencodex → ");
-    });
-    entries.push(...preserved);
-  }
-  if (!hasPhysicalComboProvider) {
-    const exact = exactComboSlugs;
-    catalog.models = entries.filter(entry => (
-      typeof entry.slug !== "string" || !exact.has(entry.slug)
-      || (Array.isArray(entry.input_modalities) && entry.input_modalities.length > 0)
-    ));
-  } else {
-    catalog.models = entries;
-  }
+  const catalogModels = nativeCatalogModels;
+  const routedEntries = buildCatalogEntriesFromObservedState({
+    template: template ? JSON.parse(JSON.stringify(template)) : null,
+    gptSlugs: [],
+    goModels: ordered,
+    featured,
+    wsEnabled: websocketsEnabled(config),
+    multiAgentMode,
+    exactComboSlugs,
+    accountSelectors,
+    suppressedBareNativeSlugs,
+    disabledNativeAccountSlugs: new Set(),
+    multiAgentV2Enabled,
+  });
+  const accountBoundEntries = accountSelectors.length === 0
+    ? []
+    : buildCatalogEntriesFromObservedState({
+      template: template ? JSON.parse(JSON.stringify(template)) : null,
+      gptSlugs: NATIVE_OPENAI_MODELS,
+      goModels: [],
+      featured,
+      wsEnabled: websocketsEnabled(config),
+      multiAgentMode,
+      exactComboSlugs,
+      accountSelectors,
+      suppressedBareNativeSlugs,
+      disabledNativeAccountSlugs: new Set([...disabledNative].filter(slug => suppressedBareNativeSlugs.has(slug))),
+      multiAgentV2Enabled,
+    }).filter(entry => trustedAccountBoundNativeCatalogSlug(entry) !== undefined);
+  const gatheredProviderNames = new Set(enabledProviders.map(([name]) => name));
+  const selectedModelsByProvider = new Map<string, ReadonlySet<string>>(
+    enabledProviders.flatMap(([name, provider]) => (
+      Array.isArray(provider.selectedModels) && provider.selectedModels.length > 0
+        ? [[name, new Set(provider.selectedModels)] as const]
+        : []
+    )),
+  );
+  const mergedModels = mergeCatalogEntriesFromObservedState({
+    catalogModels,
+    baselineCatalogModels,
+    routedEntries,
+    baseline,
+    featured,
+    wsEnabled: websocketsEnabled(config),
+    template,
+    disabledModels: new Set(config.disabledModels ?? []),
+    selectedModelsByProvider,
+    gatheredProviderNames,
+    degradedProviderNames,
+    legacyCustomModelSlugs: legacyCustomModelCatalogSlugs(config),
+    multiAgentMode,
+    multiAgentV2Enabled,
+    exactComboSlugs,
+    hasPhysicalComboProvider,
+    includeNativeOpenAi,
+    accountBoundEntries,
+    suppressedBareNativeSlugs,
+    policy: {
+      ...CANONICAL_NATIVE_CATALOG_CONTENT_POLICY,
+      warningPolicy: "suppress",
+    },
+  });
+  clampCatalogModelsToObservedCodexSupport(
+    mergedModels,
+    source.runtimeSupport.kind === "available"
+      ? supportedCodexReasoningEffortsFromObservedCatalog(source.runtimeSupport.catalog)
+      : null,
+  );
+  catalog.models = mergedModels;
   return catalog;
 }
 
@@ -220,7 +320,7 @@ export async function gatherCodexCatalogCandidate(
       return { kind: "disposition", disposition: { status: "skipped", reason: "stale", retryable: true } };
     }
     const paths = bindGatherPaths(session, snapshot);
-    const source = resolveCatalogSourceForGather(session);
+    const source = resolveCatalogSourceForGather(session, paths.catalogKind);
     if (source.kind === "catalog-unavailable") {
       return { kind: "disposition", disposition: { status: "skipped", reason: "catalog-unavailable", retryable: false } };
     }
@@ -234,10 +334,12 @@ export async function gatherCodexCatalogCandidate(
       readCatalogGatherSource(session, "native-catalog-selection");
     }
     const authOutcomes: CatalogGatherProviderAuthOutcome[] = [];
+    const providerModelOutcomes: CatalogGatherProviderModelOutcome[] = [];
     const discoveryPolicies: CatalogProviderDiscoveryPolicySnapshot[] = [];
     providerGatherStarted = true;
     const routedModels = await gatherRoutedModelsForCatalogGather(snapshot.config, session, {
       providerAuthOutcomes: authOutcomes,
+      providerModelOutcomes,
       discoveryPolicySnapshots: discoveryPolicies,
     });
     const processLocal = processEvidence(source);
@@ -255,7 +357,34 @@ export async function gatherCodexCatalogCandidate(
     }
 
     const active = catalogFrom(activeBytes);
-    const preparedCatalog = prepareCatalog(snapshot.config, source, active, routedModels);
+    // Retained sync restores native priorities from the once-only pristine backup. Convergence
+    // must use the same admitted evidence instead of treating its already-featured active catalog
+    // as the baseline, or feature A -> feature B -> none would retain stale priorities.
+    const backupCanAcceptPristineCatalog = keyedBackupBytes === null
+      || (paths.legacyBackup !== undefined && legacyBackupBytes === null);
+    const baselineCatalog = catalogFrom(keyedBackupBytes)
+      ?? catalogFrom(legacyBackupBytes)
+      ?? (backupCanAcceptPristineCatalog
+        ? (active && !catalogHasRoutedEntries(active)
+          ? active
+          : !hasRoutedEntries(source.catalog) ? source.catalog : null)
+        : null);
+    const preparedCatalog = prepareCatalog(
+      snapshot.config,
+      source,
+      active,
+      routedModels,
+      paths.multiAgentV2Enabled,
+      nativePriorityBaseline(baselineCatalog),
+      baselineCatalog?.models ?? [],
+      new Set(providerModelOutcomes
+        .filter(outcome => outcome.state === "degraded")
+        .map(outcome => outcome.provider)),
+      [
+        catalogFrom(keyedBackupBytes)?.models ?? [],
+        catalogFrom(legacyBackupBytes)?.models ?? [],
+      ],
+    );
     const preparedCatalogBytes = catalogBytes(preparedCatalog);
     const preparedCacheBytes = `${JSON.stringify({
       fetched_at: "2000-01-01T00:00:00Z",
@@ -266,8 +395,17 @@ export async function gatherCodexCatalogCandidate(
       ? Buffer.from(activeBytes!).toString("utf8")
       : !hasRoutedEntries(source.catalog) ? `${JSON.stringify(source.catalog, null, 2)}\n` : null;
     const notices = new Set<CatalogNotice>();
-    if (source.source !== "bundled-catalog-template") notices.add("fallback");
-    if (authOutcomes.some(outcome => outcome.state !== "available")) notices.add("provider-auth");
+    const sourceIsAuthoritative = paths.catalogKind === "default"
+      ? source.source === "bundled-catalog-template"
+      : source.source === "active-catalog-merge";
+    if (!sourceIsAuthoritative) notices.add("fallback");
+    const authDegradedProviders = new Set(authOutcomes
+      .filter(outcome => outcome.state !== "available")
+      .map(outcome => outcome.provider));
+    if (authDegradedProviders.size > 0) notices.add("provider-auth");
+    if (providerModelOutcomes.some(outcome => (
+      outcome.state === "degraded" && !authDegradedProviders.has(outcome.provider)
+    ))) notices.add("provider-network");
     const candidate = {} as CodexCatalogCandidate;
     candidateStates.set(candidate, {
       consumed: false,

package/src/codex/custom-model-catalog-migration.ts

@@ -0,0 +1,176 @@
+import { routedSlug, slugEquivalenceKey } from "../providers/slug-codec";
+import type { OcxConfig } from "../types";
+
+const MIGRATION_FIELD = "customModelCatalogMigration";
+const MIGRATION_VERSION = 1;
+
+type ConfigRecord = Record<string, unknown>;
+
+interface SupportedMigrationState {
+  readonly record: ConfigRecord;
+  readonly legacyOwnedSlugs: readonly string[];
+}
+
+type ParsedMigrationState =
+  | { readonly kind: "absent" }
+  | { readonly kind: "supported"; readonly state: SupportedMigrationState }
+  | { readonly kind: "unsupported"; readonly value: unknown };
+
+type CustomModelSlugSet =
+  | { readonly kind: "valid"; readonly byKey: ReadonlyMap<string, string> }
+  | { readonly kind: "invalid" };
+
+function configRecord(value: unknown): ConfigRecord | null {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? value as ConfigRecord
+    : null;
+}
+
+function canonicalRoutedSlug(value: unknown): string | null {
+  if (typeof value !== "string") return null;
+  const slug = value.trim();
+  const slash = slug.indexOf("/");
+  if (slash <= 0 || slash === slug.length - 1) return null;
+  const provider = slug.slice(0, slash).trim();
+  const modelId = slug.slice(slash + 1).trim();
+  if (!provider || !modelId || provider.includes("/")) return null;
+  return routedSlug(provider, modelId);
+}
+
+function canonicalSlugMap(values: readonly unknown[]): ReadonlyMap<string, string> | null {
+  const byKey = new Map<string, string>();
+  for (const value of values) {
+    const slug = canonicalRoutedSlug(value);
+    if (slug === null) return null;
+    byKey.set(slugEquivalenceKey(slug), slug);
+  }
+  return byKey;
+}
+
+function parseMigrationState(config: unknown): ParsedMigrationState {
+  const record = configRecord(config);
+  if (!record || !Object.hasOwn(record, MIGRATION_FIELD)) return { kind: "absent" };
+  const value = record[MIGRATION_FIELD];
+  const state = configRecord(value);
+  if (!state || state.version !== MIGRATION_VERSION || !Array.isArray(state.legacyOwnedSlugs)) {
+    return { kind: "unsupported", value };
+  }
+  const slugs = canonicalSlugMap(state.legacyOwnedSlugs);
+  if (slugs === null) return { kind: "unsupported", value };
+  return {
+    kind: "supported",
+    state: {
+      record: state,
+      legacyOwnedSlugs: [...slugs.values()].sort(),
+    },
+  };
+}
+
+function customModelSlugs(config: unknown): CustomModelSlugSet {
+  const record = configRecord(config);
+  if (!record || record.customModels === undefined) {
+    return { kind: "valid", byKey: new Map() };
+  }
+  if (!Array.isArray(record.customModels)) return { kind: "invalid" };
+  const byKey = new Map<string, string>();
+  for (const value of record.customModels) {
+    const custom = configRecord(value);
+    if (!custom || typeof custom.provider !== "string" || typeof custom.modelId !== "string") {
+      return { kind: "invalid" };
+    }
+    const provider = custom.provider.trim();
+    const modelId = custom.modelId.trim();
+    if (!provider || !modelId || provider.includes("/")) return { kind: "invalid" };
+    const slug = routedSlug(provider, modelId);
+    byKey.set(slugEquivalenceKey(slug), slug);
+  }
+  return { kind: "valid", byKey };
+}
+
+function copyMigrationField(target: OcxConfig, source: OcxConfig): void {
+  const targetRecord = target as unknown as ConfigRecord;
+  const sourceRecord = source as unknown as ConfigRecord;
+  if (Object.hasOwn(sourceRecord, MIGRATION_FIELD)) {
+    targetRecord[MIGRATION_FIELD] = structuredClone(sourceRecord[MIGRATION_FIELD]);
+  } else {
+    delete targetRecord[MIGRATION_FIELD];
+  }
+}
+
+/**
+ * Project one-time legacy custom-model ownership onto a whole-config write.
+ *
+ * The persisted pre-write config is the only authority for pre-marker ownership.
+ * Unknown future/malformed state is carried forward byte-for-value and grants no
+ * deletion authority; an older binary must never reinterpret or erase it.
+ */
+export function projectCustomModelCatalogMigration(
+  persistedConfig: unknown,
+  candidateConfig: OcxConfig,
+): OcxConfig {
+  const persistedState = parseMigrationState(persistedConfig);
+  const candidateState = parseMigrationState(candidateConfig);
+  const projected = { ...candidateConfig } as OcxConfig;
+  const projectedRecord = projected as unknown as ConfigRecord;
+
+  if (persistedState.kind === "unsupported") {
+    projectedRecord[MIGRATION_FIELD] = structuredClone(persistedState.value);
+    return projected;
+  }
+  if (persistedState.kind === "absent" && candidateState.kind === "unsupported") {
+    projectedRecord[MIGRATION_FIELD] = structuredClone(candidateState.value);
+    return projected;
+  }
+
+  const legacyByKey = new Map<string, string>();
+  const addLegacy = (slugs: readonly string[]): void => {
+    for (const slug of slugs) legacyByKey.set(slugEquivalenceKey(slug), slug);
+  };
+  if (persistedState.kind === "supported") addLegacy(persistedState.state.legacyOwnedSlugs);
+  if (candidateState.kind === "supported") addLegacy(candidateState.state.legacyOwnedSlugs);
+
+  const persistedCustom = customModelSlugs(persistedConfig);
+  const candidateCustom = customModelSlugs(candidateConfig);
+  // Only an absent persisted version means these rows can predate the ownership marker.
+  // Never add candidate-only or post-version models: those are born with custom-model-v1.
+  if (persistedState.kind === "absent" && persistedCustom.kind === "valid") {
+    for (const [key, slug] of persistedCustom.byKey) legacyByKey.set(key, slug);
+  }
+
+  // Establish an empty v1 on the first custom-model add too: the cutover, not list
+  // non-emptiness, proves that candidate-only models can never be inferred as legacy.
+  // Unrelated saves for users who never configured custom models remain untouched.
+  const shouldVersion = persistedState.kind === "supported"
+    || candidateState.kind === "supported"
+    || (persistedState.kind === "absent"
+      && ((persistedCustom.kind === "valid" && persistedCustom.byKey.size > 0)
+        || (candidateCustom.kind === "valid" && candidateCustom.byKey.size > 0)));
+  if (!shouldVersion) {
+    delete projectedRecord[MIGRATION_FIELD];
+    return projected;
+  }
+
+  const priorRecord = persistedState.kind === "supported" ? persistedState.state.record : {};
+  const nextRecord = candidateState.kind === "supported" ? candidateState.state.record : {};
+  projectedRecord[MIGRATION_FIELD] = {
+    ...structuredClone(priorRecord),
+    ...structuredClone(nextRecord),
+    version: MIGRATION_VERSION,
+    legacyOwnedSlugs: [...legacyByKey.values()].sort(),
+  };
+  return projected;
+}
+
+/** Copy only the internal migration state after the projected write succeeds. */
+export function adoptCustomModelCatalogMigration(
+  target: OcxConfig,
+  projected: OcxConfig,
+): void {
+  copyMigrationField(target, projected);
+}
+
+/** Canonical slugs that may classify old, unmarked OpenCodex custom rows. */
+export function legacyCustomModelCatalogSlugs(config: OcxConfig): ReadonlySet<string> {
+  const state = parseMigrationState(config);
+  return new Set(state.kind === "supported" ? state.state.legacyOwnedSlugs : []);
+}