import { existsSync, readFileSync } from "node:fs";
import { join } from "node:path";
import { initializeConfigOwnership } from "../../lib/config-ownership";
import { getConfigDir, loadConfig, websocketsEnabled } from "../../config";
import { shouldSyncCodexOnStart } from "../desired-state";
import { legacyCustomModelCatalogSlugs } from "../custom-model-catalog-migration";
import { getCodexHome } from "../paths";
import type { OcxConfig } from "../../types";
import { pendingModelSelectionProviders } from "../../providers/initial-model-selection";
import { captureModelDiscoveryBaseline, finalizeModelDiscovery } from "../../providers/new-model-policy-runtime";
import { OPENAI_CODEX_PROVIDER_ID } from "../../providers/openai-tiers";
import { providerCodexAccountMode } from "../../providers/registry";
import { COMBO_NAMESPACE } from "../../combos";
import { codexAccountNamespaceEntries, isMainCodexAccountTarget } from "../account-namespaces";
import { MAIN_CODEX_ACCOUNT_ID } from "../main-account";
import { applyNativeAccessPrograms } from "./access-programs";
import {
  availableAccountGatedNativeModels,
  codexModelEntitlementStateForAccount,
  isCodexModelEntitlementSnapshotCurrent,
  type CodexModelEntitlementSnapshot,
} from "../model-entitlements";
import { resolveAdmittedCodexModelEntitlements } from "../model-entitlement-admission";
import { isAccountNeedsReauth } from "../account-runtime-state";
import { codexRuntimeStatePath } from "../runtime";
import {
  activeCodexModelsCachePath,
  catalogBackupPathFor,
  catalogHasRoutedEntries,
  findNativeTemplate,
  findSupportedNativeTemplate,
  isDefaultCatalogPath,
  legacyCatalogBackupPath,
  readCatalog,
  readCatalogBackup,
  readCodexCatalogPath,
  readCodexCatalogPathForHome,
  readNativeBaseline,
  nativeMultiAgentDefaults,
} from "./parsing";
import type { CatalogModel, MultiAgentMode, RawCatalog, RawEntry } from "./parsing";
import {
  accountBoundNativeOpenAiSlugsBySelector,
  desktopAllowlistSuppressedNativeSlugs,
  disabledNativeSlugs,
  nativeContextLimits,
  observedAccountBoundNativeEntries,
  observedReserveCatalogSource,
  shouldIncludeAccountBoundNativeOpenAi,
  shouldIncludeNativeOpenAi,
  upstreamNativeEntry,
} from "./metadata";
import { trustedAccountBoundNativeCatalogSlug } from "./account-models";
import { bundledCatalogCacheState, loadBundledCodexCatalog } from "./bundled";
import { isMultiAgentV2Enabled } from "../features";
import { clampCatalogModelsToCodexSupport } from "./effort";
import { suppressedSyntheticMaxCatalogSlugs } from "./model-hints";
import { filterCatalogVisibleModels, gatherRoutedModels, type CatalogGatherProviderModelOutcome } from "./provider-fetch";
import { dedupeCatalogEntriesBySlug, enforceCatalogSlugUniqueness, exactComboCatalogSlugs, type ComboCatalogOmission } from "./aggregation";
import {
  withCatalogWriteSerialization,
  type CatalogWritePermit,
} from "../catalog-write-serialization";
import {
  preparedBytesDifferFromDisk,
  publishHashedCodexCatalogBackup,
  publishLegacyCodexCatalogBackup,
  replaceActiveCodexCatalog,
  replaceCodexModelsCache,
  type PreparedCatalogFileWrite,
} from "../internal/catalog-writer";
import { visibleCodexAccountSelectors } from "./account-models";
import { ACCOUNT_GATED_NATIVE_OPENAI_MODELS, NATIVE_OPENAI_MODELS, NATIVE_RESERVE_MODEL } from "./native-models";
import { createReserveCatalogProjection, RESERVE_LUNA_METADATA_SOURCE, RESERVE_SOURCE_CATALOG_FIELD } from "./reserve";
import {
  CANONICAL_NATIVE_CATALOG_CONTENT_POLICY,
  buildCatalogEntriesFromObservedState,
  mergeCatalogEntriesFromObservedState,
  mergeCatalogModelsWithNativeRecovery,
  orderForSubagents,
} from "./build-entries";
import { finishUpstreamNativeEntry } from "./derive-entry";
import { finalizeAutoReviewModelOverride } from "./auto-review";
import { gatedNativeAccountLabel, gatedNativeReauthSuppressionReason, warnGatedNativeSuppressedOnce } from "./gated-native-warn";
import { reserveCatalogSuppressionReason, warnReserveSuppressedOnce } from "./reserve-warn";

interface RetainedCatalogSyncRead {
  readonly catalogPath: string;
  readonly catalog: RawCatalog;
  readonly onDiskCatalog: RawCatalog | null;
  readonly modelsCache: RawCatalog | null;
  readonly evidence: string;
  /**
   * Process-local epochs, baselined AFTER our own gather rather than with the
   * filesystem bytes above. See `retainedCatalogProcessEvidence`.
   */
  readonly processEvidence: string;
}

interface RetainedCatalogSyncResult {
  added: number;
  path: string;
  catalogWritten: boolean;
  comboOmissions: ComboCatalogOmission[];
  /** Validated catalog commit (including identical bytes), or a refused refresh. */
  refreshOutcome?: "committed" | "refused";
  /** `desired_disabled` observed under K after the provider await; nothing was written. */
  skippedReason?: "desired_disabled";
}

/**
 * Catalog/cache commit overrides.
 *
 * An explicit `ocx sync` is also the refresh path for side profiles that consume
 * the OpenCodex catalog without injection (for example a custom `model_provider`
 * that routes to the proxy). In that mode the Codex integration toggle only
 * governs config/history injection; the catalog and models cache may still be
 * refreshed, so `allowWhenDesiredDisabled` lets the commit path ignore the OFF
 * gate that otherwise protects a fully native home.
 */
export interface CodexCatalogSyncOptions {
  allowWhenDesiredDisabled?: boolean;
}

interface RetainedCatalogSyncWrite {
  readonly config: OcxConfig;
  readonly goModels: CatalogModel[];
  readonly providerModelOutcomes: readonly CatalogGatherProviderModelOutcome[];
  readonly comboOmissions: ComboCatalogOmission[];
  readonly read: RetainedCatalogSyncRead;
  readonly permit: CatalogWritePermit;
  readonly owningCodexHome: string;
  readonly modelEntitlements: CodexModelEntitlementSnapshot;
}

function optionalFileBytes(path: string): string | null {
  try {
    return readFileSync(path).toString("base64");
  } catch (error) {
    if ((error as NodeJS.ErrnoException | undefined)?.code === "ENOENT") return null;
    throw error;
  }
}

function loadCatalogForRetainedSync(path: string): RawCatalog | null {
  const bundled = isDefaultCatalogPath(path) ? loadBundledCodexCatalog() : null;
  if (bundled) return JSON.parse(JSON.stringify(bundled)) as RawCatalog;
  const active = readCatalog(path);
  // A valid configured custom file remains the content authority even when it has no bare native
  // template. The null-template builder is deliberate; a stale backup must not replace active
  // custom root metadata merely because the current file contains only routed rows.
  if (active && (!isDefaultCatalogPath(path) || findNativeTemplate(active))) return active;
  return readCatalog(catalogBackupPathFor(path))
    ?? (isDefaultCatalogPath(path) ? readCatalog(legacyCatalogBackupPath()) : null)
    ?? readCatalog(activeCodexModelsCachePath())
    ?? active;
}

function retainedCatalogSyncEvidence(
  config: OcxConfig,
  catalogPath: string,
  catalog: RawCatalog,
): string {
  return JSON.stringify({
    config,
    catalogPath,
    catalog,
    catalogBytes: optionalFileBytes(catalogPath),
    hashedBackupBytes: optionalFileBytes(catalogBackupPathFor(catalogPath)),
    legacyBackupBytes: isDefaultCatalogPath(catalogPath)
      ? optionalFileBytes(legacyCatalogBackupPath()) : null,
    modelsCacheBytes: optionalFileBytes(activeCodexModelsCachePath()),
    // The persisted runtime selection is a pre-await filesystem input, not a
    // process epoch: another PROCESS can move runtime authority by rewriting this
    // file, and that move is invisible to our in-process memo. Recorded PRESENT or
    // ABSENT, because its absence is what makes the resolver fall back.
    runtimeStateBytes: optionalFileBytes(codexRuntimeStatePath()),
  });
}

/**
 * The bundled-template half of the same evidence, observed separately.
 *
 * The runtime process memo is deliberately NOT here, and that exclusion took three
 * attempts to get honest. Gathering resolves the Codex runtime lazily and under its
 * own cache key, so this path cannot pre-settle that memo: baselining it before the
 * await always detected our own side effect and refused every write, and baselining
 * it after the await captured a runtime that ANOTHER process had moved as though it
 * were ours — a catalog prepared from R1 committing after authority reached R2.
 *
 * Runtime authority is covered where it is actually durable instead: the persisted
 * `codex-runtime.json` bytes sit in the pre-await filesystem evidence, PRESENT or
 * ABSENT, so a cross-process runtime move is caught. What is left uncovered, and is
 * written down rather than papered over, is a same-process in-memory runtime swap
 * that never touches that file — WP11 owns the lock that makes that case decidable.
 */
function retainedCatalogProcessEvidence(): string {
  return JSON.stringify({
    bundledCatalogCache: bundledCatalogCacheState(),
  });
}

/**
 * Capture every local catalog input the retained sync path consults before its
 * provider await. The exact evidence is compared after K acquisition; a newer
 * catalog/backup/cache or target selection makes this attempt a no-write.
 */
function readRetainedCatalogSync(config: OcxConfig): RetainedCatalogSyncRead | null {
  const catalogPath = readCodexCatalogPath();
  const catalog = loadCatalogForRetainedSync(catalogPath);
  if (!catalog) return null;

  // The bundled catalog is a reliable native template on the default path, but it is not the
  // merge source. Preservation must inspect the file that this sync is about to overwrite;
  // otherwise an empty/partial provider gather cannot see routed or user-native rows on disk.
  const onDiskCatalog = readCatalog(catalogPath);
  const modelsCache = readCatalog(activeCodexModelsCachePath());
  const evidence = retainedCatalogSyncEvidence(config, catalogPath, catalog);
  // `processEvidence` is filled in after the provider await, not here.
  return { catalogPath, catalog, onDiskCatalog, modelsCache, evidence, processEvidence: "" };
}

function revalidateRetainedCatalogSync(
  config: OcxConfig,
  prepared: RetainedCatalogSyncRead,
): RetainedCatalogSyncRead | null {
  const catalogPath = readCodexCatalogPath();
  if (catalogPath !== prepared.catalogPath) return null;
  const evidence = retainedCatalogSyncEvidence(config, catalogPath, prepared.catalog);
  if (evidence !== prepared.evidence) return null;
  if (retainedCatalogProcessEvidence() !== prepared.processEvidence) return null;
  return {
    catalogPath,
    catalog: JSON.parse(JSON.stringify(prepared.catalog)) as RawCatalog,
    onDiskCatalog: readCatalog(catalogPath),
    modelsCache: readCatalog(activeCodexModelsCachePath()),
    evidence,
    processEvidence: prepared.processEvidence,
  };
}

function pristineCatalogBytes(read: RetainedCatalogSyncRead): string | null {
  if (read.onDiskCatalog && !catalogHasRoutedEntries(read.onDiskCatalog)) {
    try {
      return readFileSync(read.catalogPath, "utf8");
    } catch {
      return null;
    }
  }
  return catalogHasRoutedEntries(read.catalog)
    ? null
    : `${JSON.stringify(read.catalog, null, 2)}\n`;
}

function catalogModelsForMergeWithNativeRecovery(
  catalogPath: string,
  catalog: RawCatalog,
  onDiskCatalog: RawCatalog | null,
): RawEntry[] {
  const primaryCatalogModels = onDiskCatalog?.models ?? catalog.models ?? [];
  // Native-alias compatibility can omit disabled native rows from the effective catalog because
  // Desktop's remote allowlist ignores `visibility: "hide"`. Keep current/pristine native recovery
  // sources beside the on-disk rows so re-enabling a model restores its real metadata. Routed and
  // user-authored rows still come only from the on-disk catalog.
  return mergeCatalogModelsWithNativeRecovery(primaryCatalogModels, [
    catalog.models ?? [],
    readCatalogBackup(catalogPath)?.models ?? [],
  ]);
}

/** Merge retained rows, project confirmed account metadata, and publish only changed catalog bytes. */
function writeRetainedCatalogSync({
  config,
  goModels,
  providerModelOutcomes,
  comboOmissions,
  read,
  permit,
  owningCodexHome,
  modelEntitlements,
}: RetainedCatalogSyncWrite): RetainedCatalogSyncResult {
  const { catalogPath, catalog, onDiskCatalog } = read;
  const catalogModelsForMerge = catalogModelsForMergeWithNativeRecovery(
    catalogPath,
    catalog,
    onDiskCatalog,
  );
  // Strict selector for template inheritance; the validity gate above keeps the broad one.
  const template = findSupportedNativeTemplate(catalog);

  try {
    // Once-only: preserve the PRISTINE pre-opencodex catalog as the native-priority baseline
    // (later syncs would otherwise overwrite it with featured-modified priorities).
    const pristine = pristineCatalogBytes(read);
    if (pristine !== null) {
      // Initialize metadata while the root is empty; never pre-claim the hashed path.
      initializeConfigOwnership(getConfigDir());
      publishHashedCodexCatalogBackup(permit, owningCodexHome, {
        path: catalogBackupPathFor(catalogPath),
        content: pristine,
      });
      if (isDefaultCatalogPath(catalogPath)) {
        publishLegacyCodexCatalogBackup(permit, owningCodexHome, {
          path: legacyCatalogBackupPath(),
          content: pristine,
        });
      }
    }
  } catch { /* backup best-effort */ }

  // Hide disabled models from Codex, then feature the chosen subagent models (native OR routed)
  // by giving them the lowest priority — see buildCatalogEntries for why priority, not array order.
  const enabledGo = filterCatalogVisibleModels(goModels, config);
  const featured = config.subagentModels ?? [];
  const orderedGoModels = orderForSubagents(enabledGo, featured); // stable tie-break among equal priorities
  const suppressedSyntheticMaxSlugs = suppressedSyntheticMaxCatalogSlugs(
    config,
    orderedGoModels,
    catalogModelsForMerge,
  );
  const modelPickerOrder = config.modelPickerOrder ?? [];
  const multiAgentMode: MultiAgentMode = config.multiAgentMode === "v1" || config.multiAgentMode === "v2" ? config.multiAgentMode : "default";
  const exactComboSlugs = exactComboCatalogSlugs(config);
  const bareEligibleAccountIds = providerCodexAccountMode(
    OPENAI_CODEX_PROVIDER_ID,
    config.providers[OPENAI_CODEX_PROVIDER_ID],
  ) === "direct" ? new Set([MAIN_CODEX_ACCOUNT_ID]) : undefined;
  const availableBareGatedNativeSlugs = availableAccountGatedNativeModels(
    modelEntitlements,
    bareEligibleAccountIds,
  );
  const availableAccountGatedNativeSlugs = availableAccountGatedNativeModels(modelEntitlements);
  const availableBareNativeSlugs = NATIVE_OPENAI_MODELS.filter(slug => (
    !ACCOUNT_GATED_NATIVE_OPENAI_MODELS.has(slug) || availableBareGatedNativeSlugs.has(slug)
  ));
  const availableAccountNativeSlugs = NATIVE_OPENAI_MODELS.filter(slug => (
    !ACCOUNT_GATED_NATIVE_OPENAI_MODELS.has(slug) || availableAccountGatedNativeSlugs.has(slug)
  ));
  const unavailableGatedNativeSlugs = new Set([...ACCOUNT_GATED_NATIVE_OPENAI_MODELS].filter(slug => (
    !availableBareGatedNativeSlugs.has(slug)
  )));
  // #4212: this set is the whole record of a model vanishing, and it is a set of strings that
  // nothing downstream ever asks a question of. Explain it here, while the entitlement snapshot
  // that produced it is still in scope, because after this point the model is simply absent and
  // no later surface can tell "never entitled" apart from "the account broke this morning".
  for (const slug of unavailableGatedNativeSlugs) {
    const reason = gatedNativeReauthSuppressionReason({
      snapshot: modelEntitlements,
      slug,
      eligibleAccountIds: bareEligibleAccountIds,
      needsReauth: isAccountNeedsReauth,
      label: accountId => gatedNativeAccountLabel(config, accountId),
    });
    if (reason) warnGatedNativeSuppressedOnce(slug, reason);
  }
  const suppressedBareNativeSlugs = new Set([
    ...desktopAllowlistSuppressedNativeSlugs(config),
    ...unavailableGatedNativeSlugs,
  ]);
  const hasPhysicalComboProvider = Object.hasOwn(config.providers, COMBO_NAMESPACE);
  const includeNativeOpenAi = shouldIncludeNativeOpenAi(config);
  const includeAccountBoundNativeOpenAi = shouldIncludeAccountBoundNativeOpenAi(config);
  // Both user levers. Passing only the cap here is what let a per-model window the dashboard
  // had accepted get written back at full width in the on-disk catalog.
  const openaiContextCap = nativeContextLimits(config);
  const accountSelectors = includeAccountBoundNativeOpenAi
    ? visibleCodexAccountSelectors(config)
    : [];
  const observedAccountNativeEntries = [
    ...(read.modelsCache?.models ?? []),
    ...(onDiskCatalog?.models ?? []).filter(entry =>
      trustedAccountBoundNativeCatalogSlug(entry) !== undefined),
  ];
  const accountTargets = new Map(codexAccountNamespaceEntries(config));
  const reserveMainSelectors = accountSelectors.filter(selector =>
    isMainCodexAccountTarget(accountTargets.get(selector) ?? ""));
  // #4811: an omitted Reserve row carries no reason, so the explanation has to be emitted here,
  // where the selector inputs that produced the omission are still in scope. Silent for every
  // install that did not opt into authless Codex Desktop routing.
  const reserveSuppression = reserveCatalogSuppressionReason(config, {
    includeAccountBoundNativeOpenAi,
    mainSelectors: reserveMainSelectors,
  });
  if (reserveSuppression) warnReserveSuppressedOnce(reserveSuppression);
  // The active file can own a bare source even when the bundled catalog is the build base.
  // A previously clamped qualified projection must not shorten a retained genuine ladder.
  const reserveObservations = [
    ...(onDiskCatalog?.models ?? []),
    ...(read.modelsCache?.models ?? []),
    ...(catalog.models ?? []),
  ];
  const retainedReserve = onDiskCatalog?.[RESERVE_SOURCE_CATALOG_FIELD];
  const retainedReserveSource = retainedReserve && typeof retainedReserve === "object" && !Array.isArray(retainedReserve)
    ? observedReserveCatalogSource([retainedReserve as RawEntry], [])
    : null;
  const observedReserveSource = observedReserveCatalogSource(
    // Cache invalidation carries historical bare observations alongside emitted models.
    // Only unmarked observations are fresh enough to supersede the retained source.
    reserveObservations.filter(entry => entry.slug === NATIVE_RESERVE_MODEL
      && entry.opencodex_account_observed_native === undefined), reserveMainSelectors,
  ) ?? retainedReserveSource ?? observedReserveCatalogSource(reserveObservations, reserveMainSelectors);
  // This root is read only by OCX. Upstream ModelsResponse ignores unknown root fields.
  // Retain before final runtime clamping: an omitted row must not turn into Luna next sync.
  if (observedReserveSource) catalog[RESERVE_SOURCE_CATALOG_FIELD] = structuredClone(observedReserveSource);
  else delete catalog[RESERVE_SOURCE_CATALOG_FIELD];
  const lunaSource = upstreamNativeEntry(RESERVE_LUNA_METADATA_SOURCE);
  const reserve = createReserveCatalogProjection(
    config,
    reserveMainSelectors,
    observedReserveSource,
    lunaSource ? finishUpstreamNativeEntry(lunaSource, 9, openaiContextCap) : null,
  );
  const accountNativeSlugsBySelector = accountSelectors.length > 0
    ? new Map([...accountBoundNativeOpenAiSlugsBySelector(config, observedAccountNativeEntries)].map(([selector, slugs]) => {
      const target = accountTargets.get(selector);
      const accountId = target && isMainCodexAccountTarget(target) ? MAIN_CODEX_ACCOUNT_ID : target;
      return [selector, slugs.filter(slug => (
        !ACCOUNT_GATED_NATIVE_OPENAI_MODELS.has(slug)
        || (accountId !== undefined
          && codexModelEntitlementStateForAccount(modelEntitlements, accountId, slug) === "granted")
      ))] as const;
    }))
    : new Map<string, readonly string[]>();
  const accountNativeSlugs = accountSelectors.length > 0
    ? [...new Set([...accountNativeSlugsBySelector.values()].flatMap(slugs => [...slugs]))]
    : [];
  // Unknown account-native ids have no safe bare/global identity. They are only projected through
  // the selector map above; the no-selector catalog remains the static native/API-key surface.
  const observedNativeSlugs: string[] = [];
  const wsEnabled = websocketsEnabled(config);
  const multiAgentV2Enabled = isMultiAgentV2Enabled();
  const goEntries = buildCatalogEntriesFromObservedState({
    template: template ? JSON.parse(JSON.stringify(template)) : null,
    gptSlugs: [],
    goModels: orderedGoModels,
    featured,
    modelPickerOrder,
    wsEnabled,
    multiAgentMode,
    exactComboSlugs,
    accountSelectors,
    suppressedBareNativeSlugs,
    disabledNativeAccountSlugs: new Set(),
    multiAgentV2Enabled,
    openaiContextCap,
  });
  // Keep genuine native entries (gpt-*, codex-*) with their real per-model fields and append
  // routed providers as namespaced slugs. Cursor and other adopted providers can expose model ids
  // like `gpt-5.5`; those must not delete the native OpenAI/Codex base row.
  const baselineCatalog = readCatalogBackup(catalogPath);
  const baseline = readNativeBaseline(catalogPath);
  const nativePinBaseline = nativeMultiAgentDefaults(baselineCatalog?.models);
  const gatheredProviderNames = new Set(
    Object.entries(config.providers ?? {})
      .filter(([, prov]) => prov.disabled !== true)
      .map(([name]) => name),
  );
  const degradedProviderNames = new Set(
    providerModelOutcomes
      .filter(outcome => outcome.state === "degraded")
      .map(outcome => outcome.provider),
  );
  const selectedModelsByProvider = new Map<string, ReadonlySet<string>>(
    Object.entries(config.providers ?? {}).flatMap(([name, provider]) => (
      provider.disabled !== true
        && Array.isArray(provider.selectedModels)
        && provider.selectedModels.length > 0
        ? [[name, new Set(provider.selectedModels)] as const]
        : []
    )),
  );
  // Central WS capability override on the FINAL on-disk catalog (the file Codex reads). Applies to
  // native AND routed so the advertised flag matches the implemented endpoint (phase 120.4) and a
  // native template can never leak supports_websockets while the flag is off.
  // #636: when the user only configured non-OpenAI providers (e.g. kimi), do not advertise
  // bare gpt-* rows that hard-404 via NoEnabledOpenAiProviderError. Keep natives when no
  // providers are configured yet (fresh install / catalog bootstrap tests).
  const accountBoundEntries = includeAccountBoundNativeOpenAi && accountSelectors.length > 0
    ? buildCatalogEntriesFromObservedState({
      template: template ? JSON.parse(JSON.stringify(template)) : null,
      gptSlugs: availableAccountNativeSlugs,
      goModels: [],
      featured,
      wsEnabled,
      multiAgentMode,
      exactComboSlugs,
      accountSelectors,
      suppressedBareNativeSlugs,
      disabledNativeAccountSlugs: new Set([...disabledNativeSlugs(config)].filter(slug => suppressedBareNativeSlugs.has(slug))),
      multiAgentV2Enabled,
      keepNativeChatGptOnV1: config.keepNativeChatGptOnV1 === true,
      openaiContextCap,
      accountNativeSlugs,
      accountNativeSlugsBySelector,
      reserve,
    }).filter(entry => trustedAccountBoundNativeCatalogSlug(entry) !== undefined)
    : [];
  catalog.models = mergeCatalogEntriesFromObservedState({
    modelPickerOrder,
    accountSelectors,
    catalogModels: catalogModelsForMerge,
    baselineCatalogModels: baselineCatalog?.models ?? [],
    routedEntries: goEntries,
    baseline,
    featured,
    wsEnabled,
    template,
    disabledModels: new Set(config.disabledModels ?? []),
    selectedModelsByProvider,
    gatheredProviderNames,
    pendingProviderNames: pendingModelSelectionProviders(config),
    degradedProviderNames,
    legacyCustomModelSlugs: legacyCustomModelCatalogSlugs(config),
    multiAgentMode,
    multiAgentV2Enabled,
    keepNativeChatGptOnV1: config.keepNativeChatGptOnV1 === true,
    exactComboSlugs,
    hasPhysicalComboProvider,
    includeNativeOpenAi,
    accountBoundEntries,
    suppressedBareNativeSlugs,
    suppressedSyntheticMaxSlugs,
    openaiContextCap,
    nativeDisplayNames: config.providers[OPENAI_CODEX_PROVIDER_ID]?.modelDisplayNames,
    nativeMultiAgentDefaults: nativePinBaseline,
    policy: {
      ...CANONICAL_NATIVE_CATALOG_CONTENT_POLICY,
      nativeBackfillSlugs: [...availableBareNativeSlugs, ...observedNativeSlugs],
      warningPolicy: "emit",
    },
  });
  applyNativeAccessPrograms(catalog.models, modelEntitlements, accountTargets);
  clampCatalogModelsToCodexSupport(catalog.models);
  finalizeAutoReviewModelOverride(catalog.models, catalogModelsForMerge, config);
  // Last mutation before serialization; see `enforceCatalogSlugUniqueness` for why the ordering
  // against the effort clamp is load-bearing rather than cosmetic.
  catalog.models = enforceCatalogSlugUniqueness(catalog.models, true);

  const added = goEntries.length + accountBoundEntries.length;
  const content = `${JSON.stringify(catalog, null, 2)}\n`;
  // A byte-identical rewrite is not a catalog change, but every mtime-keyed reader
  // has to treat it as one. The app-server staleness classifier (#857) is the one
  // that matters: it compares this file's mtime against each running Codex's start
  // time, so an ordinary `ocx start` — or any dashboard action that re-syncs an
  // unchanged model set — marked every already-running Codex as holding an outdated
  // in-memory catalog. Since #1407 that verdict silences opencodex's own model
  // guidance entirely (no preferred model, no roster) for the rest of that Codex's
  // lifetime, so a configured injectionModel stops reaching the session even though
  // nothing about the catalog changed. Skipping the no-op write keeps both the mtime
  // and `catalogWritten` honest; `added` still reports the routed rows the catalog
  // carries, because they are on disk either way.
  const preparedCatalog: PreparedCatalogFileWrite = { path: catalogPath, content };
  if (!preparedBytesDifferFromDisk(preparedCatalog)) {
    return { added, path: catalogPath, catalogWritten: false, comboOmissions };
  }

  replaceActiveCodexCatalog(permit, owningCodexHome, preparedCatalog);
  return {
    added,
    path: catalogPath,
    catalogWritten: true,
    comboOmissions,
  };
}

// Re-exported so the #4730 unit regression keeps importing the guard from the sync module it
// guards; the implementation lives in ./aggregation because the management convergence commit
// is the second writer that has to apply the identical rule.
export { dedupeCatalogEntriesBySlug };

export async function syncCatalogModels(
  config: OcxConfig,
  options?: CodexCatalogSyncOptions,
): Promise<RetainedCatalogSyncResult> {
  if (pendingModelSelectionProviders(config).size) {
    const { resolvePendingInitialModelSelection } = await import("../../providers/initial-model-selection-runtime");
    await resolvePendingInitialModelSelection(config);
  }
  const owningCodexHome = getCodexHome();
  const preflightRead = readRetainedCatalogSync(config);
  if (preflightRead === null) {
    return {
      added: 0,
      path: readCodexCatalogPath(),
      catalogWritten: false,
      comboOmissions: [],
      refreshOutcome: "refused",
    };
  }

  const comboOmissions: ComboCatalogOmission[] = [];
  const providerModelOutcomes: CatalogGatherProviderModelOutcome[] = [];
  // Settle the bundled template, then baseline, and only then await. Reading it
  // here makes the memo ours before anyone else can move it, so a bundled swap
  // during the await is an outside change rather than our own side effect.
  //
  // The persisted runtime selection is covered by the filesystem evidence above
  // rather than by a process epoch; see `retainedCatalogProcessEvidence` for why
  // the in-memory runtime memo cannot be baselined honestly from this path.
  loadBundledCodexCatalog();
  const prepared: RetainedCatalogSyncRead = {
    ...preflightRead,
    evidence: retainedCatalogSyncEvidence(config, preflightRead.catalogPath, preflightRead.catalog),
    processEvidence: retainedCatalogProcessEvidence(),
  };
  const discoveryBaseline = captureModelDiscoveryBaseline(config);
  const providerContentRevisions = new Map<string, string>();
  const [goModels, modelEntitlements] = await Promise.all([
    gatherRoutedModels(config, {
      comboOmissions,
      providerModelOutcomes,
      providerContentRevisions,
    }),
    resolveAdmittedCodexModelEntitlements(config),
  ]);
  const committed = withCatalogWriteSerialization(owningCodexHome, permit => {
    // Desired state can flip OFF during the provider await above. The catalog
    // evidence revalidation below cannot see that — intent lives in our config,
    // not in the catalog files — so the policy is re-read here, under K, right
    // before the only write. A lost race becomes the discriminated skip instead
    // of a routed catalog/cache surviving a completed disable. An explicit
    // catalog-only sync opts out of that gate: the user asked for a refresh even
    // when injection is OFF, and the toggle only protects config/history writes.
    if (!shouldSyncCodexOnStart(loadConfig()) && options?.allowWhenDesiredDisabled !== true) {
      return {
        added: 0,
        path: prepared.catalogPath,
        catalogWritten: false,
        comboOmissions,
        skippedReason: "desired_disabled" as const,
      };
    }
    const current = revalidateRetainedCatalogSync(config, prepared);
    if (current === null) return null;
    if (!isCodexModelEntitlementSnapshotCurrent(modelEntitlements)) return null;
    // Revalidate before adopting discovery: its scoped config mutation would otherwise
    // invalidate our own evidence. K -> C is the catalog/config lock order.
    if (!finalizeModelDiscovery(config, discoveryBaseline, goModels,
      providerModelOutcomes.filter(outcome => outcome.state === "authoritative").map(outcome => outcome.provider),
      providerContentRevisions)) return null;
    return writeRetainedCatalogSync({
      config,
      goModels,
      providerModelOutcomes,
      comboOmissions,
      read: current,
      permit,
      owningCodexHome,
      modelEntitlements,
    });
  });
  if (committed.kind === "completed" && committed.value !== null) {
    return {
      ...committed.value,
      refreshOutcome: committed.value.skippedReason ? "refused" : "committed",
    };
  }
  return {
    added: 0,
    path: prepared.catalogPath,
    catalogWritten: false,
    comboOmissions,
    refreshOutcome: "refused",
  };
}

export type CodexCacheInvalidationOutcome = "written" | "unchanged" | "missing_catalog" | "desired_disabled" | "failed";

export function invalidateCodexModelsCacheWithPermitOutcome(
  permit: CatalogWritePermit,
  owningCodexHome: string,
  options?: CodexCatalogSyncOptions,
): CodexCacheInvalidationOutcome {
  try {
    // This permit is a REACQUISITION: refreshCodexModelCatalog's commit released
    // K before this rewrite runs, so the commit-path desired-state check cannot
    // cover it. A disable landing in that gap must not be overwritten by a
    // routed cache write — re-read intent under this permit, same as the commit.
    // The catalog-only sync override applies here too so an explicit refresh
    // keeps the cache consistent with the catalog it just wrote.
    if (!shouldSyncCodexOnStart(loadConfig()) && options?.allowWhenDesiredDisabled !== true) return "desired_disabled";
    const catalogPath = readCodexCatalogPathForHome(owningCodexHome);
    if (!existsSync(catalogPath)) return "missing_catalog";
    const catalog = JSON.parse(readFileSync(catalogPath, "utf8"));
    const models = catalog.models ?? catalog;
    const cachePath = join(owningCodexHome, "models_cache.json");
    const currentCache = readCatalog(cachePath);
    const existingSlugs = new Set(models.flatMap((entry: RawEntry) =>
      typeof entry.slug === "string" ? [entry.slug] : []));
    const currentConfig = loadConfig();
    const mainSelectors = visibleCodexAccountSelectors(currentConfig).filter(selector => {
      const target = new Map(codexAccountNamespaceEntries(currentConfig)).get(selector);
      return isMainCodexAccountTarget(target ?? "");
    });
    const observedAccountModels = observedAccountBoundNativeEntries(currentCache?.models ?? [])
      .filter(entry => {
        const slug = typeof entry.slug === "string" ? entry.slug : "";
        return !existingSlugs.has(slug);
      })
      .map(entry => ({
        ...entry,
        // Keep the observation in Codex's cache without advertising a new bare picker row. The
        // next OpenCodex catalog sync consumes this marker and creates only selector-qualified
        // rows for the currently configured public account selectors.
        visibility: "hide",
        opencodex_account_observed_native: true,
        opencodex_account_observed_selectors: mainSelectors,
      }));
    const wrapper = {
      fetched_at: "2000-01-01T00:00:00Z",
      client_version: "0.0.0",
      models: [...models, ...observedAccountModels],
    };
    const preparedCache: PreparedCatalogFileWrite = {
      path: cachePath,
      content: `${JSON.stringify(wrapper, null, 2)}\n`,
    };
    // The same no-op rule the active catalog already applies (#1459), for the same
    // reason and at the second writer that has to obey it.
    //
    // This function is what `refreshCodexModelCatalog` reports as `cacheSynced`, and
    // `handleStart` ORs that into the stale-app-server warning. Rewriting identical
    // bytes bumped this file's mtime and returned `true`, so on a start where the
    // catalog reproduced byte-identically — the settled case — the warning still
    // claimed "Disk catalog/cache were updated" and told the operator their Codex
    // model list might be stale, when nothing on disk had changed and Codex held the
    // same model set the file already described. Returning `false` here makes
    // `cacheSynced` mean what its name and its consumers already assume, and what
    // `pullRemoteCatalog` and the early returns in `refreshCodexModelCatalog`
    // already assert: a write happened.
    if (!preparedBytesDifferFromDisk(preparedCache)) return "unchanged";
    replaceCodexModelsCache(permit, owningCodexHome, preparedCache);
    return "written";
  } catch {
    return "failed";
  }
}

export function invalidateCodexModelsCacheWithPermit(
  permit: CatalogWritePermit,
  owningCodexHome: string,
  options?: CodexCatalogSyncOptions,
): boolean {
  return invalidateCodexModelsCacheWithPermitOutcome(permit, owningCodexHome, options) === "written";
}

export function invalidateCodexModelsCache(options?: CodexCatalogSyncOptions): boolean {
  const owningCodexHome = getCodexHome();
  const outcome = withCatalogWriteSerialization(
    owningCodexHome,
    permit => invalidateCodexModelsCacheWithPermit(permit, owningCodexHome, options),
  );
  return outcome.kind === "completed" && outcome.value;
}
