@yansigit/opencodex 2.31.0

package/src/codex/autostart-health.ts

@@ -0,0 +1,156 @@
+import { codexAutoStartEnabled } from "../config";
+import { diagnoseService, type ServiceDiagnostic } from "../service";
+import type { OcxConfig } from "../types";
+import { getCodexRoutingKind, type CodexRoutingKind } from "./inject";
+import { diagnoseCodexShim, type CodexShimDiagnostic } from "./shim";
+
+export type StartupProtection = "service" | "shim" | "none";
+export type StartupHealthStatus = "native" | "protected" | "at-risk";
+export type ShimCoverage = "full" | "cli-only" | "none";
+
+export interface StartupHealthInputs {
+  routingKind: CodexRoutingKind;
+  autostartEnabled: boolean;
+  serviceInstalled: boolean;
+  serviceViable: boolean;
+  serviceEnabled: boolean;
+  serviceRunning: boolean;
+  serviceStale: boolean;
+  serviceConflict: boolean;
+  serviceSupported: boolean;
+  shimInstalled: boolean;
+  shimHealthy: boolean;
+  platform: NodeJS.Platform;
+  diagnosticStale?: boolean;
+}
+
+export interface StartupHealth {
+  status: StartupHealthStatus;
+  routingKind: CodexRoutingKind;
+  routingInjected: boolean;
+  localRoutingDependency: boolean;
+  autostartEnabled: boolean;
+  rebootSafe: boolean;
+  protection: StartupProtection;
+  serviceInstalled: boolean;
+  serviceViable: boolean;
+  serviceEnabled: boolean;
+  serviceRunning: boolean;
+  serviceStale: boolean;
+  serviceConflict: boolean;
+  shimInstalled: boolean;
+  shimHealthy: boolean;
+  shimCoverage: ShimCoverage;
+  serviceSupported: boolean;
+  platform: NodeJS.Platform;
+  diagnosticStale: boolean;
+  recommendedCommand: string | null;
+  commands: {
+    installService: string;
+    repairService: string;
+    installShim: string;
+    restoreNative: string;
+  };
+}
+
+const COMMANDS = {
+  installService: "ocx service install",
+  repairService: "ocx service repair",
+  installShim: "ocx codex-shim install",
+  restoreNative: "ocx restore",
+} as const;
+
+export function deriveStartupHealth(inputs: StartupHealthInputs): StartupHealth {
+  const shimEffective = inputs.autostartEnabled && inputs.shimHealthy;
+  const routingInjected = inputs.routingKind === "opencodex-local";
+  const localRoutingDependency = inputs.routingKind === "opencodex-local"
+    || inputs.routingKind === "custom-local"
+    || inputs.routingKind === "unknown";
+  // Script launchers never cover Codex Desktop/app-server surfaces. This is
+  // intentionally conservative on every OS and for WSL-shared Codex homes.
+  const shimCoverage: ShimCoverage = !shimEffective
+    ? "none"
+    : "cli-only";
+  // We can only credit an opencodex service/shim for routing that opencodex owns.
+  // An arbitrary localhost gateway has an independent lifecycle that OCX cannot repair.
+  const ownsLocalRouting = inputs.routingKind === "opencodex-local";
+  const protection: StartupProtection = ownsLocalRouting && inputs.serviceViable
+    ? "service"
+    : ownsLocalRouting && shimEffective
+      ? "shim"
+      : "none";
+  const rebootSafe = !localRoutingDependency || (ownsLocalRouting && inputs.serviceViable);
+  const status: StartupHealthStatus = !localRoutingDependency
+    ? "native"
+    : rebootSafe
+      ? "protected"
+      : "at-risk";
+  const recommendedCommand = status !== "at-risk"
+    ? null
+    : inputs.routingKind === "custom-local" || inputs.routingKind === "unknown"
+      ? COMMANDS.restoreNative
+    : inputs.serviceSupported
+      // An already-registered service is refreshed in place: `repair` rewrites its assets
+      // and restarts it without re-registering, so it needs no elevation on Windows and
+      // cannot switch a WinSW install to Task Scheduler the way `install` would. Only a
+      // genuinely absent (or conflicting, which needs uninstall-then-install) service
+      // gets the registering command.
+      ? (inputs.serviceInstalled && !inputs.serviceConflict ? COMMANDS.repairService : COMMANDS.installService)
+      : COMMANDS.restoreNative;
+  return {
+    ...inputs,
+    diagnosticStale: inputs.diagnosticStale ?? false,
+    routingInjected,
+    localRoutingDependency,
+    status,
+    rebootSafe,
+    protection,
+    shimCoverage,
+    recommendedCommand,
+    commands: { ...COMMANDS },
+  };
+}
+
+export interface StartupHealthDiagnostics {
+  routingKind?: CodexRoutingKind;
+  service?: ServiceDiagnostic;
+  shim?: CodexShimDiagnostic;
+}
+
+/** Collect current machine state without mutating config, services, or shims. */
+export function collectStartupHealth(
+  config: Pick<OcxConfig, "codexAutoStart">,
+  diagnostics: StartupHealthDiagnostics = {},
+): StartupHealth {
+  const shim = diagnostics.shim ?? diagnoseCodexShim();
+  const service = diagnostics.service ?? diagnoseService();
+  return deriveStartupHealth({
+    routingKind: diagnostics.routingKind ?? getCodexRoutingKind(),
+    autostartEnabled: codexAutoStartEnabled(config),
+    serviceInstalled: service.installed,
+    serviceViable: service.viable,
+    serviceEnabled: service.enabled,
+    serviceRunning: service.running,
+    serviceStale: service.stale,
+    serviceConflict: service.conflict,
+    serviceSupported: service.supported,
+    shimInstalled: shim.installed,
+    shimHealthy: shim.healthy,
+    platform: process.platform,
+  });
+}
+
+export function startupHealthSummary(health: StartupHealth): string {
+  if (health.status === "native") return health.routingKind === "custom-remote"
+    ? "custom remote Codex routing (no local restart dependency)"
+    : "native Codex routing (no opencodex restart dependency)";
+  if (health.protection === "service") return "protected by background service";
+  const command = health.recommendedCommand ?? health.commands.restoreNative;
+  if (health.routingKind === "unknown") return `AT RISK after restart (Codex routing could not be verified; run '${command}')`;
+  if (health.routingKind === "custom-local") return `AT RISK after restart (custom local gateway lifecycle is not managed by opencodex; run '${command}')`;
+  if (health.shimCoverage === "cli-only") return `AT RISK for Codex Desktop after restart (launcher shim covers CLI scripts only; run '${command}')`;
+  if (health.serviceConflict) return `AT RISK after restart (background service managers conflict; run '${command}')`;
+  if (health.serviceStale) return `AT RISK after restart (background service files are stale; run '${command}')`;
+  if (health.serviceInstalled && !health.serviceViable) return `AT RISK after restart (installed service is disabled, stopped, or unhealthy; run '${command}')`;
+  return `AT RISK after restart (no viable background service; run '${command}')`;
+}

package/src/codex/catalog/account-models.ts

@@ -0,0 +1,67 @@
+import type { OcxConfig } from "../../types";
+import {
+  codexAccountNamespaceEntries,
+  codexAccountPickerEnabled,
+  isMainCodexAccountTarget,
+} from "../account-namespaces";
+import type { RawEntry } from "./parsing";
+
+/** Stable nonsemantic marker used to distinguish generated rows from provider-owned rows. */
+export const CODEX_ACCOUNT_BOUND_CATALOG_KIND = "account-selector-v1";
+
+/**
+ * Public selectors whose configured account row still exists.
+ *
+ * Stale mappings stay in config so exact routing keeps failing closed, but they must not advertise
+ * a deleted account. Credential health, pause, and reauthentication state intentionally do not
+ * churn catalog identity. Selector keys have already passed config's nonempty, single-segment
+ * namespace validation. Only those public keys leave this boundary; private account ids do not.
+ */
+export function visibleCodexAccountSelectors(
+  config: Pick<OcxConfig, "codexAccounts" | "codexAccountNamespaces" | "codexAccountPickerEnabled">,
+): string[] {
+  if (!codexAccountPickerEnabled(config)) return [];
+  const storedPoolAccounts = new Set(
+    (config.codexAccounts ?? [])
+      .filter(account => !account.isMain)
+      .map(account => account.id),
+  );
+  return codexAccountNamespaceEntries(config)
+    .filter(([, accountId]) =>
+      isMainCodexAccountTarget(accountId) || storedPoolAccounts.has(accountId)
+    )
+    .map(([selector]) => selector);
+}
+
+export function accountBoundNativeDisplayName(selector: string, native: RawEntry): string {
+  const rawModel = typeof native.display_name === "string"
+    ? native.display_name
+    : String(native.slug ?? "");
+  const model = rawModel
+    .replace(/^gpt-/i, "")
+    .split("-")
+    .filter(Boolean)
+    .map(part => /^[a-z]/.test(part) ? part.charAt(0).toUpperCase() + part.slice(1) : part)
+    .join(" ");
+  return `${selector} / ${model}`;
+}
+
+/** Identify current generated rows without changing Codex's semantic model fields. */
+export function trustedAccountBoundNativeCatalogSlug(entry: RawEntry): string | undefined {
+  if (entry.opencodex_catalog_kind !== CODEX_ACCOUNT_BOUND_CATALOG_KIND
+    || typeof entry.slug !== "string") return undefined;
+  const slash = entry.slug.indexOf("/");
+  if (slash <= 0 || slash !== entry.slug.lastIndexOf("/") || slash === entry.slug.length - 1) {
+    return undefined;
+  }
+  return entry.slug.slice(slash + 1);
+}
+
+export function accountBoundNativeModelSlugs(
+  config: Pick<OcxConfig, "codexAccounts" | "codexAccountNamespaces" | "codexAccountPickerEnabled">,
+  nativeSlugs: Iterable<string>,
+): string[] {
+  const natives = [...nativeSlugs];
+  return visibleCodexAccountSelectors(config)
+    .flatMap(selector => natives.map(slug => `${selector}/${slug}`));
+}

package/src/codex/catalog/aggregation.ts

@@ -0,0 +1,436 @@
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, realpathSync } from "node:fs";
+import { delimiter, dirname, join, resolve } from "node:path";
+import { atomicWriteFile, expandUserPath, getConfigDir, websocketsEnabled } from "../../config";
+import { CODEX_CONFIG_PATH, CODEX_MODELS_CACHE_PATH, DEFAULT_CATALOG_PATH, readRootTomlString, resolveCodexConfigPath } from "../paths";
+import { clearModelCache, DEFAULT_MODEL_CACHE_TTL_MS, getFreshCached, getStaleCached, isModelsFetchCoolingDown, markModelsFetchFailure, setCached } from "../model-cache";
+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 { 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, 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,
+  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";
+
+
+import { catalogModelSlug } from "./parsing";
+import type { CatalogModel } from "./parsing";
+
+export const openAiApiCollisionWarnings = new Set<string>();
+
+export const comboCatalogWarningSignatures = new Map<string, string>();
+
+/**
+ * Why `deriveComboCatalogModel` rejected a configured combo (#484 / #516).
+ * Distinguishes unresolved/incomplete member metadata from a complete but empty
+ * modality intersection so diagnostics do not send operators to the wrong fix.
+ */
+export type ComboCatalogOmissionReason =
+  | "incomplete_metadata"
+  | "incompatible_modalities";
+
+/** Combos omitted from the catalog during the most recent `gatherRoutedModels` call (#484). */
+export interface ComboCatalogOmission {
+  id: string;
+  targets: string[];
+  reason: ComboCatalogOmissionReason;
+  message: string;
+}
+
+let lastComboCatalogOmissions: ComboCatalogOmission[] = [];
+
+export function clearLastComboCatalogOmissions(): void {
+  lastComboCatalogOmissions = [];
+}
+
+export function getLastComboCatalogOmissions(): readonly ComboCatalogOmission[] {
+  return lastComboCatalogOmissions;
+}
+
+export function replaceLastComboCatalogOmissions(items: readonly ComboCatalogOmission[]): void {
+  lastComboCatalogOmissions = [...items];
+}
+
+export function intersectStrings(values: readonly string[][]): string[] {
+  if (values.length === 0) return [];
+  const rest = values.slice(1).map(value => new Set(value));
+  return [...new Set(values[0])].filter(value => rest.every(set => set.has(value)));
+}
+
+export function effectiveComboDefault(
+  configured: string | null | undefined,
+  common: readonly string[],
+): string | undefined {
+  if (!configured) return undefined;
+  if (configured && common.includes(configured)) return configured;
+  const requestedRank = codexEffortRank(configured);
+  const ranked = common
+    .map(effort => ({ effort, rank: codexEffortRank(effort) }))
+    .filter(item => item.rank >= 0)
+    .sort((a, b) => a.rank - b.rank);
+  if (ranked.length === 0) return undefined;
+  const atOrBelow = ranked.filter(item => item.rank <= requestedRank);
+  return atOrBelow.at(-1)?.effort ?? ranked[0]!.effort;
+}
+
+/**
+ * Classify a combo derivation failure. Returns `null` when the combo would catalog.
+ * Callers that already know derivation failed can map the reason into diagnostics.
+ */
+export function comboCatalogOmissionReason(
+  combo: NormalizedComboConfig,
+  members: readonly CatalogModel[],
+): ComboCatalogOmissionReason | null {
+  if (combo.targets.length === 0) return "incomplete_metadata";
+  if (new Set(combo.targets.map(targetKey)).size !== combo.targets.length) {
+    return "incomplete_metadata";
+  }
+  if (members.length !== combo.targets.length) return "incomplete_metadata";
+  if (!members.every((member, index) => (
+    `${member.provider}/${member.id}` === targetKey(combo.targets[index]!)
+  ))) {
+    return "incomplete_metadata";
+  }
+  const contexts = members.map(member => member.contextWindow);
+  if (contexts.some(value => typeof value !== "number" || value <= 0)) {
+    return "incomplete_metadata";
+  }
+
+  const inputModalities = intersectStrings(
+    members.map(member => member.inputModalities ?? ["text"]),
+  );
+  if (inputModalities.length === 0) return "incompatible_modalities";
+  return null;
+}
+
+export function deriveComboCatalogModel(
+  id: string,
+  combo: NormalizedComboConfig,
+  members: readonly CatalogModel[],
+): CatalogModel | null {
+  if (comboCatalogOmissionReason(combo, members) !== null) return null;
+
+  const derivedInputModalities = intersectStrings(
+    members.map(member => member.inputModalities ?? ["text"]),
+  );
+  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!),
+  );
+  const defaultReasoningEffort = effectiveComboDefault(
+    combo.defaultEffort,
+    reasoningEfforts,
+  );
+
+  return {
+    provider: COMBO_NAMESPACE,
+    id,
+    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 }
+      : {}),
+  };
+}
+
+export function safeCatalogWarningLabel(value: string): string {
+  return redactSecretString(value)
+    .replace(/[\u0000-\u001f\u007f]/g, "?")
+    .slice(0, 200);
+}
+
+export function comboCatalogWarningSignature(
+  combo: NormalizedComboConfig,
+  members: readonly CatalogModel[],
+): string {
+  const discovered = new Map<string, CatalogModel>(members.map(member => [
+    `${member.provider}/${member.id}`,
+    member,
+  ] as const));
+  return JSON.stringify(combo.targets.map(target => {
+    const key = targetKey(target);
+    const member = discovered.get(key);
+    return {
+      key,
+      contextWindow: member?.contextWindow ?? null,
+      maxInputTokens: member?.maxInputTokens ?? null,
+      inputModalities: [...new Set(member?.inputModalities ?? [])].sort(),
+      reasoningEfforts: [...new Set(member?.reasoningEfforts ?? [])].sort(),
+      parallelToolCalls: member?.parallelToolCalls === true,
+      supportsReasoningSummaries: member?.supportsReasoningSummaries !== false,
+    };
+  }).sort((a, b) => a.key.localeCompare(b.key)));
+}
+
+export function comboCatalogOmissionDetail(reason: ComboCatalogOmissionReason): string {
+  return reason === "incompatible_modalities"
+    ? "members have no common input modalities"
+    : "member capabilities are incomplete";
+}
+
+/** One-line sync/CLI summary that respects the actual omission reason(s). */
+export function summarizeComboCatalogOmissions(
+  omissions: readonly Pick<ComboCatalogOmission, "reason">[],
+): string {
+  const n = omissions.length;
+  const prefix = `${n} combo${n === 1 ? "" : "s"} omitted from the catalog`;
+  if (n === 0) return prefix + ".";
+  const reasons = new Set(omissions.map(item => item.reason));
+  if (reasons.size === 1) {
+    return `${prefix} because ${comboCatalogOmissionDetail([...reasons][0]!)}.`;
+  }
+  return `${prefix}.`;
+}
+
+export function buildComboCatalogOmission(
+  id: string,
+  combo: NormalizedComboConfig,
+  members: readonly CatalogModel[],
+): ComboCatalogOmission {
+  const targets = combo.targets
+    .map(target => safeCatalogWarningLabel(targetKey(target)))
+    .sort((a, b) => a.localeCompare(b));
+  const reason = comboCatalogOmissionReason(combo, members) ?? "incomplete_metadata";
+  return {
+    id,
+    targets,
+    reason,
+    message: `[opencodex] Combo "${safeCatalogWarningLabel(id)}" is omitted from the catalog because ${comboCatalogOmissionDetail(reason)}: ${targets.join(", ")}.`,
+  };
+}
+
+/**
+ * Record a combo omitted from `/v1/models` + on-disk catalog and warn once per signature.
+ * Callers that need a race-free list (catalog sync) pass a local `sink` from the same
+ * gather invocation instead of reading process-global state afterward (#484 review).
+ */
+export function warnUncataloguedComboOnce(
+  id: string,
+  combo: NormalizedComboConfig,
+  members: readonly CatalogModel[],
+  sink: ComboCatalogOmission[] = lastComboCatalogOmissions,
+): ComboCatalogOmission {
+  const omission = buildComboCatalogOmission(id, combo, members);
+  sink.push(omission);
+  const signature = comboCatalogWarningSignature(combo, members);
+  if (comboCatalogWarningSignatures.get(id) !== signature) {
+    comboCatalogWarningSignatures.set(id, signature);
+    console.warn(omission.message);
+  }
+  return omission;
+}
+
+export function exactComboCatalogSlugs(
+  config: Pick<OcxConfig, "combos" | "disabledModels">,
+): Set<string> {
+  const disabled = new Set(config.disabledModels ?? []);
+  return new Set(listComboIds(config).flatMap(id => {
+    const raw = config.combos?.[id];
+    const alias = typeof raw?.alias === "string"
+      ? raw.alias.trim()
+      : "";
+    const canonical = comboModelId(id);
+    const publicSlug = alias || canonical;
+    const comboDisabled = comboDisabledModelSelectors(id, raw ?? {})
+      .some(selector => disabled.has(selector));
+    return comboDisabled ? [] : [publicSlug];
+  }));
+}
+
+export function normalizedOpenAiApiSignature(model: CatalogModel): string {
+  const normalized = {
+    provider: model.provider,
+    id: model.id,
+    contextWindow: model.contextWindow ?? null,
+    maxInputTokens: model.maxInputTokens ?? null,
+    inputModalities: [...new Set(model.inputModalities ?? [])].sort(),
+    reasoningEfforts: [...new Set(model.reasoningEfforts ?? [])].sort(),
+    ownedBy: model.owned_by ?? null,
+  };
+  return JSON.stringify(normalized);
+}
+
+export function resetOpenAiApiCatalogWarningStateForTests(): void {
+  openAiApiCollisionWarnings.clear();
+}
+
+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 {
+  if (generation <= lastWarningReconciledGeneration) return 0;
+  const removed = openAiApiCollisionWarnings.size
+    + comboCatalogWarningSignatures.size
+    + slugAliasCollisionWarnings.size
+    + comboMasqueradeCollisionWarnings.size
+    + comboUnrestorableShadowWarnings.size
+    + accountSelectorShadowCollisionWarnings.size;
+  openAiApiCollisionWarnings.clear();
+  comboCatalogWarningSignatures.clear();
+  slugAliasCollisionWarnings.clear();
+  comboMasqueradeCollisionWarnings.clear();
+  comboUnrestorableShadowWarnings.clear();
+  accountSelectorShadowCollisionWarnings.clear();
+  lastWarningReconciledGeneration = generation;
+  return removed;
+}
+
+export 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.`,
+  );
+}
+
+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>();
+  for (const m of goModels) {
+    // 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);
+      continue;
+    }
+    const winnerIsPlainAlias = !winner.id.includes("/");
+    const currentIsPlainAlias = !m.id.includes("/");
+    if (currentIsPlainAlias && !winnerIsPlainAlias) {
+      skipped.add(winner);
+      winnerByAlias.set(key, m);
+    } else {
+      skipped.add(m);
+    }
+    if (!slugAliasCollisionWarnings.has(key)) {
+      slugAliasCollisionWarnings.add(key);
+      console.warn(
+        `[opencodex] slug alias collision on "${key}": multiple native ids encode to the same Codex-facing slug; `
+        + "the plain-hyphen native id is cataloged, the slash id remains callable via its raw selector.",
+      );
+    }
+  }
+  return skipped;
+}
+
+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;
+}
+
+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;
+}