@bitkyc08/opencodex 2.14.1 → 2.15.0

package/src/codex/catalog/metadata.ts

@@ -15,7 +15,7 @@ import { enrichProviderFromRegistry, shouldCaseFoldMetadataModelId } from "../..
 import { getProviderRegistryEntry } from "../../providers/registry";
 import { applyProviderContextCap, providerContextCap } from "../../providers/context-cap";
 import { routedSlug, slugEquals, slugsEquivalent } from "../../providers/slug-codec";
-import { CODEX_GPT5_IDENTITY_LINE } from "../../adapters/identity";
+import { identifyRoutedModel } 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";
@@ -37,9 +37,23 @@ import type { RawEntry } from "./parsing";
 import { readCurrentCatalogOrCache, readCurrentCodexCatalog, readCurrentCodexModelsCache, unique } from "./bundled";
 import { trustedAccountBoundNativeCatalogSlug, visibleCodexAccountSelectors } from "./account-models";
 import { CODEX_NATIVE_ALIAS_CATALOG_KIND } from "./kinds";
-import { NATIVE_OPENAI_MODELS, SUPPORTED_NATIVE_OPENAI_SLUGS } from "./native-models";
+import {
+  NATIVE_DAYBREAK_BLUE_MODEL,
+  NATIVE_OPENAI_CAPABILITY_ALIAS_MODELS,
+  NATIVE_OPENAI_MODELS,
+  SUPPORTED_NATIVE_OPENAI_SLUGS,
+  isNativeOpenAiCapabilityAliasModel,
+  nativeOpenAiCapabilitySourceSlug,
+} from "./native-models";
 export { CODEX_NATIVE_ALIAS_CATALOG_KIND } from "./kinds";
-export { NATIVE_OPENAI_MODELS, SUPPORTED_NATIVE_OPENAI_SLUGS } from "./native-models";
+export {
+  NATIVE_DAYBREAK_BLUE_MODEL,
+  NATIVE_OPENAI_CAPABILITY_ALIAS_MODELS,
+  NATIVE_OPENAI_MODELS,
+  SUPPORTED_NATIVE_OPENAI_SLUGS,
+  isNativeOpenAiCapabilityAliasModel,
+  nativeOpenAiCapabilitySourceSlug,
+} from "./native-models";
 
 export const DOCUMENTED_NATIVE_OPENAI_ADDITIONS = [
   "gpt-5.3-codex-spark",
@@ -94,18 +108,28 @@ export const NATIVE_OPENAI_CONTEXT_OVERRIDES: Record<string, { contextWindow?: n
   "gpt-5.6-sol": { contextWindow: NATIVE_GPT56_CONTEXT_WINDOW, maxContextWindow: NATIVE_GPT56_CONTEXT_WINDOW },
   "gpt-5.6-terra": { contextWindow: NATIVE_GPT56_CONTEXT_WINDOW, maxContextWindow: NATIVE_GPT56_CONTEXT_WINDOW },
   "gpt-5.6-luna": { contextWindow: NATIVE_GPT56_CONTEXT_WINDOW, maxContextWindow: NATIVE_GPT56_CONTEXT_WINDOW },
+  [NATIVE_DAYBREAK_BLUE_MODEL]: { contextWindow: NATIVE_GPT56_CONTEXT_WINDOW, maxContextWindow: NATIVE_GPT56_CONTEXT_WINDOW },
 };
 
+const PINNED_UPSTREAM_MODELS: Map<string, RawEntry> = new Map(
+  ((upstreamModelsSnapshot as unknown as { models?: RawEntry[] }).models ?? [])
+    .flatMap(model => typeof model.slug === "string" ? [[model.slug, model] as const] : []),
+);
+
+function pinnedNativeCapabilityEntry(slug: string): RawEntry | undefined {
+  return PINNED_UPSTREAM_MODELS.get(nativeOpenAiCapabilitySourceSlug(slug));
+}
+
 /**
  * Pinned capability metadata is safe to use as a fallback for every supported native model.
  * Keep it separate from UPSTREAM_NATIVE_ENTRIES: that narrower map also authorizes replacing
  * persisted native rows during sync, which is currently intentional only for the GPT-5.6 family.
  */
 const PINNED_NATIVE_CAPABILITY_ENTRIES: Map<string, RawEntry> = new Map(
-  ((upstreamModelsSnapshot as unknown as { models?: RawEntry[] }).models ?? [])
-    .filter(m => typeof m.slug === "string"
-      && SUPPORTED_NATIVE_OPENAI_SLUGS.has(m.slug as string))
-    .map(m => [m.slug as string, m]),
+  [...NATIVE_OPENAI_MODELS, ...NATIVE_OPENAI_CAPABILITY_ALIAS_MODELS].flatMap(slug => {
+    const entry = pinnedNativeCapabilityEntry(slug);
+    return entry ? [[slug, entry] as const] : [];
+  }),
 );
 
 export function nativeOpenAiContextWindow(slug: string, contextCap?: number): number | undefined {
@@ -259,12 +283,38 @@ export function applyNativeVisibility(
   return entries;
 }
 
+function upstreamNativeEntryForSlug(slug: string): RawEntry | undefined {
+  const sourceSlug = nativeOpenAiCapabilitySourceSlug(slug);
+  if (!sourceSlug.startsWith("gpt-5.6-")) return undefined;
+  const source = PINNED_UPSTREAM_MODELS.get(sourceSlug);
+  if (!source) return undefined;
+  if (slug === sourceSlug) return source;
+
+  const alias = structuredClone(source) as RawEntry;
+  alias.slug = slug;
+  alias.display_name = "Daybreak Blue";
+  alias.description = "Frontier general-purpose model with safeguards for defensive cybersecurity work.";
+  if (typeof alias.base_instructions === "string") {
+    alias.base_instructions = identifyRoutedModel(alias.base_instructions, slug);
+  }
+  if (alias.model_messages && typeof alias.model_messages === "object" && !Array.isArray(alias.model_messages)) {
+    const modelMessages = alias.model_messages as Record<string, unknown>;
+    if (typeof modelMessages.instructions_template === "string") {
+      alias.model_messages = {
+        ...modelMessages,
+        instructions_template: identifyRoutedModel(modelMessages.instructions_template, slug),
+      };
+    }
+  }
+  delete alias.availability_nux;
+  return alias;
+}
+
 export const UPSTREAM_NATIVE_ENTRIES: Map<string, RawEntry> = new Map(
-  ((upstreamModelsSnapshot as unknown as { models?: RawEntry[] }).models ?? [])
-    .filter(m => typeof m.slug === "string"
-      && SUPPORTED_NATIVE_OPENAI_SLUGS.has(m.slug as string)
-      && (m.slug as string).startsWith("gpt-5.6-"))
-    .map(m => [m.slug as string, m]),
+  [...NATIVE_OPENAI_MODELS, ...NATIVE_OPENAI_CAPABILITY_ALIAS_MODELS].flatMap(slug => {
+    const entry = upstreamNativeEntryForSlug(slug);
+    return entry ? [[slug, entry] as const] : [];
+  }),
 );
 
 export function upstreamNativeEntry(slug: string): RawEntry | null {

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

@@ -1,3 +1,30 @@
+/** ChatGPT/Codex wire id observed for the account-native Daybreak Blue surface. */
+export const NATIVE_DAYBREAK_BLUE_MODEL = "gpt-daybreak-blue-latest";
+
+/**
+ * Account-native aliases whose Codex capabilities track another pinned native row.
+ *
+ * This is catalog metadata inheritance only. Routing always preserves the requested
+ * wire id, so the ChatGPT/Codex `gpt-daybreak-*` surface never collapses into the
+ * separately billed API-key `daybreak-*-latest` surface or into `gpt-5.6-sol`.
+ */
+const NATIVE_OPENAI_CAPABILITY_SOURCES: Readonly<Record<string, string>> = Object.freeze({
+  [NATIVE_DAYBREAK_BLUE_MODEL]: "gpt-5.6-sol",
+});
+
+/** Account-scoped native ids that may inherit metadata but never enter the bare allowlist. */
+export const NATIVE_OPENAI_CAPABILITY_ALIAS_MODELS = Object.freeze(
+  Object.keys(NATIVE_OPENAI_CAPABILITY_SOURCES),
+);
+
+export function isNativeOpenAiCapabilityAliasModel(slug: string): boolean {
+  return Object.hasOwn(NATIVE_OPENAI_CAPABILITY_SOURCES, slug);
+}
+
+export function nativeOpenAiCapabilitySourceSlug(slug: string): string {
+  return NATIVE_OPENAI_CAPABILITY_SOURCES[slug] ?? slug;
+}
+
 /** Native OpenAI model ids that this release can route and restore with authoritative metadata. */
 export const NATIVE_OPENAI_MODELS = [
   "gpt-5.5", "gpt-5.4", "gpt-5.4-mini", "gpt-5.3-codex-spark",

package/src/codex/catalog/parsing.ts

@@ -31,7 +31,7 @@ import { redactSecretString } from "../../lib/redact";
 import upstreamModelsSnapshot from "../data/upstream-models.json";
 
 
-import { NATIVE_OPENAI_CONTEXT_OVERRIDES, SUPPORTED_NATIVE_OPENAI_SLUGS, UPSTREAM_NATIVE_ENTRIES, nativeMultiAgentVersion } from "./metadata";
+import { NATIVE_OPENAI_CONTEXT_OVERRIDES, SUPPORTED_NATIVE_OPENAI_SLUGS, UPSTREAM_NATIVE_ENTRIES, isNativeOpenAiCapabilityAliasModel, nativeMultiAgentVersion } from "./metadata";
 import { trustedAccountBoundNativeCatalogSlug } from "./account-models";
 import { CODEX_NATIVE_ALIAS_CATALOG_KIND } from "./kinds";
 
@@ -116,6 +116,11 @@ export interface CatalogModel {
   inputModalities?: string[];
   /** Provider opted into parallel tool calls (OcxProviderConfig.parallelToolCalls). */
   parallelToolCalls?: boolean;
+  /**
+   * This routed row is an explicitly configured account-native alias on the canonical ChatGPT
+   * forward provider. It may inherit pinned native Codex metadata without changing its wire id.
+   */
+  codexForwardNativeCapabilityAlias?: boolean;
   /** Whether Codex may send Responses text.verbosity for this routed model. */
   supportsVerbosity?: boolean;
   supportsReasoningSummaries?: boolean;
@@ -359,9 +364,19 @@ export function applyMultiAgentMode(entries: RawEntry[], mode: MultiAgentMode, v
     for (const entry of entries) {
       const slug = typeof entry.slug === "string" ? entry.slug : "";
       const nativeAlias = entry.opencodex_catalog_kind === CODEX_NATIVE_ALIAS_CATALOG_KIND;
+      const routedNativeSlug = slug.startsWith(`${OPENAI_CODEX_PROVIDER_ID}/`)
+        ? slug.slice(OPENAI_CODEX_PROVIDER_ID.length + 1)
+        : "";
+      const codexForwardCapabilityAlias = entry.opencodex_catalog_kind === CODEX_CUSTOM_MODEL_CATALOG_KIND
+        && entry.use_responses_lite === true
+        && isNativeOpenAiCapabilityAliasModel(routedNativeSlug)
+        ? routedNativeSlug
+        : undefined;
       const upstreamPin = nativeAlias
         ? nativeMultiAgentVersion(slug)
-        : UPSTREAM_NATIVE_ENTRIES.get(trustedAccountBoundNativeCatalogSlug(entry) ?? slug)?.multi_agent_version;
+        : codexForwardCapabilityAlias
+          ? nativeMultiAgentVersion(codexForwardCapabilityAlias)
+          : UPSTREAM_NATIVE_ENTRIES.get(trustedAccountBoundNativeCatalogSlug(entry) ?? slug)?.multi_agent_version;
       if (typeof upstreamPin === "string") {
         entry.multi_agent_version = upstreamPin;
       } else if (v2FeatureEnabled) {

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

@@ -69,7 +69,7 @@ import { createAdmissionGate, ResourceAdmissionError, type AdmissionMetrics } fr
 
 import { CODEX_CUSTOM_MODEL_CATALOG_KIND, JAWCODE_CATALOG_AUGMENT_PROVIDERS, catalogModelSlug, shouldExposeRoutedModel } from "./parsing";
 import type { CatalogModel } from "./parsing";
-import { disabledNativeSlugs, hasComboTargets, nativeDefaultReasoningEffort, nativeInputModalities, nativeOpenAiContextWindow, nativeOpenAiSlugs, nativeParallelToolCalls, nativeReasoningEfforts } from "./metadata";
+import { disabledNativeSlugs, hasComboTargets, isNativeOpenAiCapabilityAliasModel, nativeDefaultReasoningEffort, nativeInputModalities, nativeOpenAiContextWindow, nativeOpenAiSlugs, nativeParallelToolCalls, nativeReasoningEfforts } from "./metadata";
 import { deriveComboCatalogModel, normalizedOpenAiApiSignature, openAiApiCollisionWarnings, replaceLastComboCatalogOmissions, warnUncataloguedComboOnce } from "./aggregation";
 import type { ComboCatalogOmission } from "./aggregation";
 import type { CatalogGatherProviderAuthEvidence } from "./filesystem-evidence";
@@ -209,6 +209,15 @@ interface GatherInflightEntry {
   readonly promise: Promise<GatherFlightResult>;
 }
 
+function withCanonicalOpenAiForwardAuthDefault(
+  name: string,
+  provider: OcxProviderConfig,
+): OcxProviderConfig {
+  if (name !== OPENAI_CODEX_PROVIDER_ID || provider.authMode !== undefined) return provider;
+  const candidate = { ...provider, authMode: "forward" as const };
+  return isCanonicalOpenAiForwardProvider(candidate) ? candidate : provider;
+}
+
 const gatherInflight = new Map<string, GatherInflightEntry[]>();
 const CATALOG_GATHER_AUTHORITY_KEY = randomBytes(32);
 const REQUEST_CREDENTIAL_SENTINEL = `ocx-catalog-credential-${randomBytes(16).toString("hex")}`;
@@ -390,7 +399,7 @@ function captureProviderGather(
   authResolver: ModelsAuthResolver,
   retainConfiguredModelIds?: ReadonlySet<string>,
 ): CapturedProviderGather {
-  const enriched = detachedClone(configured);
+  const enriched = detachedClone(withCanonicalOpenAiForwardAuthDefault(name, configured));
   enrichProviderFromRegistry(name, enriched);
   const provider = recursivelyFreeze(enriched);
   const observedAuth = authResolver.kind === "observed"
@@ -1714,16 +1723,49 @@ async function gatherRoutedModelsUncached(
   const replacedByRoutedSlug = new Map(all.map(model => [routedSlug(model.provider, model.id), model]));
   const customModels = (config.customModels ?? []).map(cm => {
     const rawProvider = config.providers[cm.provider];
+    // Registry routing backfills an omitted authMode on the built-in OpenAI provider to
+    // forward. Keep the catalog projection on the same contract while still failing closed
+    // for every explicit non-forward mode and every non-canonical endpoint.
+    const providerForCanonicalCheck = rawProvider
+      ? withCanonicalOpenAiForwardAuthDefault(cm.provider, rawProvider)
+      : undefined;
+    const codexForwardNativeCapabilityAlias = cm.provider === OPENAI_CODEX_PROVIDER_ID
+      && providerForCanonicalCheck !== undefined
+      && isCanonicalOpenAiForwardProvider(providerForCanonicalCheck)
+      && isNativeOpenAiCapabilityAliasModel(cm.modelId);
+    const nativeAliasContextWindow = codexForwardNativeCapabilityAlias
+      ? nativeOpenAiContextWindow(cm.modelId, providerContextCap(config, OPENAI_CODEX_PROVIDER_ID))
+      : undefined;
+    const customContextWindow = cm.contextWindow
+      ? nativeAliasContextWindow !== undefined
+        ? Math.min(cm.contextWindow, nativeAliasContextWindow)
+        : cm.contextWindow
+      : nativeAliasContextWindow;
+    const nativeAliasDefaultEffort = codexForwardNativeCapabilityAlias
+      ? nativeDefaultReasoningEffort(cm.modelId)
+      : undefined;
     const supportsReasoningSummaries = configuredReasoningSummarySupport(rawProvider, cm.modelId);
     const base: CatalogModel = {
       id: cm.modelId,
       provider: cm.provider,
       catalogKind: CODEX_CUSTOM_MODEL_CATALOG_KIND,
       // Display-only label: never feeds routing (customModels are keyed by routedSlug below).
-      ...(cm.displayName ? { displayName: cm.displayName } : {}),
-      ...(cm.contextWindow ? { contextWindow: cm.contextWindow } : {}),
-      ...(cm.inputModalities ? { inputModalities: cm.inputModalities } : {}),
+      ...(cm.displayName
+        ? { displayName: cm.displayName }
+        : codexForwardNativeCapabilityAlias ? { displayName: "Daybreak Blue" } : {}),
+      ...(customContextWindow !== undefined ? { contextWindow: customContextWindow } : {}),
+      ...(cm.inputModalities
+        ? { inputModalities: cm.inputModalities }
+        : codexForwardNativeCapabilityAlias ? { inputModalities: nativeInputModalities(cm.modelId) } : {}),
       ...(typeof supportsReasoningSummaries === "boolean" ? { supportsReasoningSummaries } : {}),
+      ...(codexForwardNativeCapabilityAlias
+        ? {
+          codexForwardNativeCapabilityAlias: true,
+          reasoningEfforts: nativeReasoningEfforts(cm.modelId),
+          parallelToolCalls: nativeParallelToolCalls(cm.modelId),
+          ...(nativeAliasDefaultEffort ? { defaultReasoningEffort: nativeAliasDefaultEffort } : {}),
+        }
+        : {}),
     };
     // #962: the dedupe below drops the provider-derived row this custom row replaces. Inherit that
     // row's provider capability metadata (reasoning ladder, default effort, parallel tool calls,

package/src/codex/catalog/sync.ts

@@ -248,6 +248,9 @@ export function deriveEntry(
   contextCap?: number,
 ): RawEntry {
   const preserveExact = isExactComboCatalogModel(model, exactComboSlugs);
+  const codexForwardNativeCapabilityAlias = model?.codexForwardNativeCapabilityAlias === true
+    ? upstreamNativeEntry(model.id)
+    : null;
   const isRouted = model !== undefined;
   if (!isRouted && !slug.includes("/")) {
     // Supported native slug covered by the upstream snapshot: use the REAL entry (exact
@@ -256,8 +259,8 @@ export function deriveEntry(
     const upstream = upstreamNativeEntry(slug);
     if (upstream) return finishUpstreamNativeEntry(upstream, priority, contextCap);
   }
-  if (template) {
-    const e = JSON.parse(JSON.stringify(template)) as RawEntry;
+  if (template || codexForwardNativeCapabilityAlias) {
+    const e = JSON.parse(JSON.stringify(codexForwardNativeCapabilityAlias ?? template)) as RawEntry;
     e.slug = slug;
     e.display_name = routedDisplayName(slug);
     e.description = desc;
@@ -272,9 +275,11 @@ export function deriveEntry(
       // window when /models omits context metadata (#992). Known metadata
       // restores exact values below; otherwise the strict-fields fallback
       // supplies the conservative 128k triple.
-      delete e.context_window;
-      delete e.max_context_window;
-      delete e.auto_compact_token_limit;
+      if (!codexForwardNativeCapabilityAlias) {
+        delete e.context_window;
+        delete e.max_context_window;
+        delete e.auto_compact_token_limit;
+      }
       // Native id for identity text + metadata lookups — the slug may be an encoded
       // alias (`provider/vendor-model`); the model object carries the native id.
       const modelName = model?.id ?? slug.slice(slug.indexOf("/") + 1);
@@ -283,8 +288,17 @@ export function deriveEntry(
         // (leaking that into base_instructions is a non-first-party signature → ToS risk).
         e.base_instructions = identifyRoutedModel(e.base_instructions, modelName);
       }
-      applyReasoningLevels(e, model?.reasoningEfforts, model?.defaultReasoningEffort, preserveExact);
-      normalizeRoutedCatalogEntry(e, model?.parallelToolCalls === true);
+      applyReasoningLevels(
+        e,
+        model?.reasoningEfforts,
+        model?.defaultReasoningEffort,
+        preserveExact || codexForwardNativeCapabilityAlias !== null,
+      );
+      // This exact provider/model pair is the ChatGPT/Codex forward surface. Keep the pinned
+      // native tool/search/responses-lite contract while preserving the routed slug and wire id.
+      if (!codexForwardNativeCapabilityAlias) {
+        normalizeRoutedCatalogEntry(e, model?.parallelToolCalls === true);
+      }
       if (model) applyCatalogMetadata(e, model.provider, model.id, model.contextCap);
       applyCatalogModelMetadata(e, model);
       if (model?.catalogKind) e.opencodex_catalog_kind = model.catalogKind;

package/src/codex/catalog.ts

@@ -2,7 +2,7 @@
 // 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 { accountBoundNativeOpenAiSlugs, accountBoundNativeOpenAiSlugsBySelector, CODEX_NATIVE_ALIAS_CATALOG_KIND, NATIVE_OPENAI_MODELS, configuredNativeAliasSlugs, desktopAllowlistSuppressedNativeSlugs, isNativeAliasCatalogEntry, nativeOpenAiContextWindow, disabledNativeSlugs, visibleNativeSlugs, desktopVisibleNativeSlugs, nativeModelRows, applyNativeVisibility, observedAccountBoundNativeEntries, observedAccountBoundNativeOpenAiSlugs, upstreamNativeEntry, nativeOpenAiSlugs, listCatalogNativeSlugs, nativeInputModalities, nativeReasoningEfforts, nativeDefaultReasoningEffort, shouldIncludeAccountBoundNativeOpenAi, shouldIncludeNativeOpenAi } from "./catalog/metadata";
+export { accountBoundNativeOpenAiSlugs, accountBoundNativeOpenAiSlugsBySelector, CODEX_NATIVE_ALIAS_CATALOG_KIND, NATIVE_DAYBREAK_BLUE_MODEL, NATIVE_OPENAI_CAPABILITY_ALIAS_MODELS, NATIVE_OPENAI_MODELS, configuredNativeAliasSlugs, desktopAllowlistSuppressedNativeSlugs, isNativeAliasCatalogEntry, isNativeOpenAiCapabilityAliasModel, nativeOpenAiCapabilitySourceSlug, nativeOpenAiContextWindow, disabledNativeSlugs, visibleNativeSlugs, desktopVisibleNativeSlugs, nativeModelRows, applyNativeVisibility, observedAccountBoundNativeEntries, observedAccountBoundNativeOpenAiSlugs, upstreamNativeEntry, nativeOpenAiSlugs, listCatalogNativeSlugs, nativeInputModalities, nativeReasoningEfforts, nativeDefaultReasoningEffort, shouldIncludeAccountBoundNativeOpenAi, shouldIncludeNativeOpenAi } from "./catalog/metadata";
 export { isSpawnableCodexCandidate, codexExecInvocation, loadBundledCodexCatalog, materializeBundledCodexCatalog, loadCatalogTemplate } from "./catalog/bundled";
 export { nativeEffortClamp, shouldApplyNativeEffortClamp, catalogModelEfforts, codexSupportedReasoningEfforts, clampedDefaultEffort, clampEntryToCodexSupportedEfforts, clampCatalogModelsToCodexSupport } from "./catalog/effort";
 export { applyProviderConfigHints, isDatedVariantId, filterCatalogVisibleModels, gatherRoutedModels, clearGatherRoutedModelsInflight, augmentRoutedModelsWithRegistryOpenAiApiRows, augmentRoutedModelsWithMetadata, resolveComboCatalogMember, configuredComboTargetModelsByProvider } from "./catalog/provider-fetch";

package/src/config.ts

@@ -1,6 +1,6 @@
 import { execFileSync } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
-import { chmodSync, copyFileSync, existsSync, linkSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, truncateSync, unlinkSync, writeFileSync } from "node:fs";
+import { chmodSync, constants as fsConstants, copyFileSync, existsSync, linkSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, truncateSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { Database } from "bun:sqlite";
@@ -373,7 +373,21 @@ export class OpenAiTierBackupRollbackError extends Error {
 }
 
 export class OpenAiTierBackupCollisionError extends Error {
-  constructor() { super("Existing OpenAI tier backup differs from the current config"); this.name = "OpenAiTierBackupCollisionError"; }
+  readonly configPath?: string;
+  constructor(configPath?: string) {
+    super("Existing OpenAI tier backup differs from the current config");
+    this.name = "OpenAiTierBackupCollisionError";
+    this.configPath = configPath;
+  }
+}
+
+export class OpenAiTierRollbackPreserveError extends Error {
+  readonly code?: "missing" | "not-rollback" | "mismatch" | "exhausted";
+  constructor(message: string, options?: ErrorOptions & { code?: OpenAiTierRollbackPreserveError["code"] }) {
+    super(message, options);
+    this.name = "OpenAiTierRollbackPreserveError";
+    this.code = options?.code;
+  }
 }
 
 export class OpenAiTierBackupSecretResidualError extends Error {
@@ -461,7 +475,7 @@ export function backupConfigBeforeOpenAiTierMigration(
       // point would be surprising and potentially destructive.
       const backupBytes = io.read(backup);
       if (classifyOpenAiTierBackup(backupBytes) === "rollback") {
-        throw new OpenAiTierBackupCollisionError();
+        throw new OpenAiTierBackupCollisionError(source);
       }
       console.warn("[openai-provider-migration] Replacing stale pre-migration backup (post-migration config was rewritten since last migration).");
       io.unlink(backup);
@@ -516,7 +530,7 @@ export function backupConfigBeforeOpenAiTierMigration(
     } catch (cause) {
       if (!isAlreadyExistsError(cause)) throw cause;
       const winner = io.read(backup);
-      if (!sameBytes(original, winner)) throw new OpenAiTierBackupCollisionError();
+      if (!sameBytes(original, winner)) throw new OpenAiTierBackupCollisionError(source);
       scrubUnpublishedTemp();
       return "reused";
     }
@@ -552,6 +566,67 @@ export function backupConfigBeforeOpenAiTierMigration(
   }
 }
 
+export interface OpenAiTierRollbackPreserveIO {
+  exists(path: string): boolean;
+  read(path: string): Uint8Array;
+  copyExclusive(source: string, destination: string): void;
+  unlink(path: string): void;
+}
+
+const DEFAULT_ROLLBACK_PRESERVE_IO: OpenAiTierRollbackPreserveIO = {
+  exists: existsSync,
+  read: target => readFileSync(target),
+  copyExclusive: (source, destination) => {
+    copyFileSync(source, destination, fsConstants.COPYFILE_EXCL);
+  },
+  unlink: unlinkSync,
+};
+
+const OPENAI_TIER_ROLLBACK_PRESERVE_ATTEMPTS = 16;
+
+/**
+ * Copy a rollback-classified `.pre-openai-tiers-v2.bak` to a unique
+ * `.pre-openai-tiers-v1-rollback.<timestamp>[suffix].bak` path, then unlink the
+ * blocking v2 name. The original bytes are copied with no-replace publication;
+ * the v2 path is removed only after the copy is verified. Shared by startup
+ * migration recovery and `ocx init` cleanup so the two paths cannot drift.
+ */
+export function preserveOpenAiTierRollbackSnapshot(
+  configPath = getConfigPath(),
+  io: OpenAiTierRollbackPreserveIO = DEFAULT_ROLLBACK_PRESERVE_IO,
+): string {
+  const backup = `${configPath}.pre-openai-tiers-v2.bak`;
+  if (!io.exists(backup)) {
+    throw new OpenAiTierRollbackPreserveError("OpenAI tier rollback backup is missing", { code: "missing" });
+  }
+  const original = io.read(backup);
+  if (classifyOpenAiTierBackup(original) !== "rollback") {
+    throw new OpenAiTierRollbackPreserveError("OpenAI tier backup is not a rollback snapshot", { code: "not-rollback" });
+  }
+  for (let attempt = 0; attempt < OPENAI_TIER_ROLLBACK_PRESERVE_ATTEMPTS; attempt++) {
+    const preserved = `${configPath}.pre-openai-tiers-v1-rollback.${Date.now()}${attempt ? `-${attempt}` : ""}.bak`;
+    try {
+      io.copyExclusive(backup, preserved);
+    } catch (error) {
+      if (isAlreadyExistsError(error)) continue;
+      throw error;
+    }
+    let copied: Uint8Array;
+    try {
+      copied = io.read(preserved);
+    } catch (error) {
+      throw new OpenAiTierRollbackPreserveError("Failed to read preserved rollback snapshot", { cause: error, code: "mismatch" });
+    }
+    if (!sameBytes(original, copied)) {
+      try { io.unlink(preserved); } catch { /* keep the original backup; incomplete copy is best-effort */ }
+      throw new OpenAiTierRollbackPreserveError("Preserved rollback snapshot does not match source bytes", { code: "mismatch" });
+    }
+    io.unlink(backup);
+    return preserved;
+  }
+  throw new OpenAiTierRollbackPreserveError("Unable to find a unique rollback snapshot path", { code: "exhausted" });
+}
+
 /**
  * Expand a leading `~` to the home directory in user-supplied paths
  * (OPENCODEX_HOME/CODEX_HOME set from GUIs/service files where no shell expanded it).