@iislee/opencodex 2.11.0 → 2.35.0

package/src/providers/model-rename-migration.ts

@@ -0,0 +1,255 @@
+// Registry model renames do not reach a saved provider config on their own.
+//
+// `reconcileOAuthProviders` refuses to touch a row whose `authMode` is not
+// `oauth` (src/oauth/index.ts), and `enrichProviderFromRegistry` is fill-only by
+// design: it backfills a MISSING field and never rewrites a present one, so a
+// user's hand-edited model list survives an upgrade. Both postures are correct.
+// Their gap is the case where the registry did not ADD a model but RENAMED one:
+// the saved row keeps a retired id forever, the supported id never appears, and
+// the capability metadata stays keyed to an id the vendor is taking offline
+// (issue #1610 — `qwen3.8-max-preview` persisted through the `qwen3.8-max`
+// rename in six separate fields, including a reasoning ladder that had since
+// diverged from the registry's).
+//
+// This migration is deliberately NOT general reconciliation. It rewrites exactly
+// one thing: an id this file declares retired, on a provider that still carries
+// the registry's transport, and only when the registry currently seeds the
+// replacement. Everything else in the row is left alone.
+
+import { PROVIDER_REGISTRY } from "./registry";
+import type { OcxConfig, OcxProviderConfig } from "../types";
+
+export interface ModelRename {
+  /** Registry provider id whose saved rows may carry the retired model id. */
+  provider: string;
+  from: string;
+  to: string;
+  /** Why the vendor retired it, for the startup warning and future readers. */
+  reason: string;
+  /**
+   * Drop the retired key from `modelReasoningEffortMap` instead of renaming it.
+   *
+   * Renaming preserves the VALUE, which is right for records whose values describe the
+   * model — a context window or an effort ladder survives a rename — and wrong for the
+   * one record whose values are themselves wire ids. An effort map saved as
+   * `high -> gemini-3.6-flash-high` would keep naming a dead wire id under the new key,
+   * and the adapter maps effort BEFORE resolving CCA routing, so that value arrives as
+   * an unrecognised effort and silently degrades to the default tier.
+   *
+   * Only that one record is dropped. Emptying the others would be worse than the bug:
+   * catalog enrichment treats an existing `{}` as "already populated" and will not
+   * restore the registry's records, so the migrated user would keep routing correctly
+   * but lose the reasoning picker entirely.
+   */
+  dropReasoningEffortMap?: boolean;
+}
+
+/**
+ * Renames already applied to `PROVIDER_REGISTRY`. An entry stays here after the
+ * registry moves on: it is what repairs configs saved before that move. Removing
+ * one strands every config that has not started since the rename shipped.
+ */
+export const MODEL_RENAMES: readonly ModelRename[] = [
+  {
+    provider: "alibaba-token-plan",
+    from: "qwen3.8-max-preview",
+    to: "qwen3.8-max",
+    reason: "Alibaba shipped Qwen3.8-Max as stable and documents the preview endpoint as liable to be taken offline once preview concludes",
+  },
+  {
+    provider: "alibaba-token-plan-intl",
+    from: "qwen3.8-max-preview",
+    to: "qwen3.8-max",
+    reason: "Alibaba shipped Qwen3.8-Max as stable and documents the preview endpoint as liable to be taken offline once preview concludes",
+  },
+  // Antigravity Flash generations. Google takes the previous Flash model off Cloud Code
+  // Assist almost immediately when the next ships, so a saved 3.6 (or older 3.5) id is a
+  // dead selection rather than a merely outdated one. Routing already redirects these ids
+  // at request time; this migration repairs the saved config so the picker, the allowlist
+  // and the capability maps stop naming a model the backend no longer serves.
+  ...(["gemini-3.6-flash", "gemini-3.6-flash-low", "gemini-3.6-flash-medium", "gemini-3.6-flash-high",
+    "gemini-3.5-flash-extra-low", "gemini-3.5-flash-low", "gemini-3.5-flash-mid", "gemini-3.5-flash-high",
+    "gemini-3-flash-agent"] as const).map(from => ({
+    provider: "google-antigravity",
+    from,
+    to: "gemini-3.7-flash",
+    reason: "Google retires the previous Antigravity Flash generation from Cloud Code Assist when its successor ships, so the saved id no longer resolves to a live model",
+    // The retired Flash tiers were wire ids, so any saved per-model record keyed by one
+    // may also hold one as a value. 3.7 expresses tiers as thinkingLevel names instead.
+    dropReasoningEffortMap: true,
+  })),
+];
+
+/** Provider fields that key metadata by model id. */
+const MODEL_KEYED_RECORDS = [
+  "modelContextWindows",
+  "modelMaxOutputTokens",
+  "modelInputModalities",
+  "modelReasoningEfforts",
+  "modelDefaultReasoningEfforts",
+  "modelReasoningEffortMap",
+] as const;
+
+/** Provider fields that are flat lists of model ids. */
+const MODEL_ID_LISTS = [
+  "models",
+  // A retired id left here is worse than a stale label: `filterCatalogModels` treats
+  // `selectedModels` as an exact-match allowlist, so a user who allowlisted only the
+  // retired model gets NO replacement row at all — the model silently vanishes from
+  // their catalog instead of being renamed. OAuth reconciliation does not cover this
+  // field, so the rename has to.
+  "selectedModels",
+  "noVisionModels",
+  "noReasoningModels",
+  "noTemperatureModels",
+  "noTopPModels",
+  "noPenaltyModels",
+  "autoToolChoiceOnlyModels",
+  "preserveReasoningContentModels",
+  "thinkingBudgetModels",
+  "directReasoningEffortModels",
+] as const;
+
+function renameInList(value: unknown, from: string, to: string): string[] | null {
+  if (!Array.isArray(value) || !value.includes(from)) return null;
+  const seen = new Set<string>();
+  const next: string[] = [];
+  // Rename in place to preserve ordering, and collapse a duplicate if the target
+  // id was already present alongside the retired one.
+  for (const entry of value) {
+    if (typeof entry !== "string") continue;
+    const mapped = entry === from ? to : entry;
+    if (seen.has(mapped)) continue;
+    seen.add(mapped);
+    next.push(mapped);
+  }
+  return next;
+}
+
+function renameInRecord(value: unknown, from: string, to: string): Record<string, unknown> | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const record = value as Record<string, unknown>;
+  if (!(from in record)) return null;
+  const next: Record<string, unknown> = {};
+  for (const [key, entry] of Object.entries(record)) {
+    const mapped = key === from ? to : key;
+    if (mapped in next) continue;
+    // An explicit entry already saved under the new id is the newer intent.
+    next[mapped] = key === from && to in record ? record[to] : entry;
+  }
+  return next;
+}
+
+/** Drop the retired key entirely, leaving any entry already saved under the new id. */
+function dropFromRecord(value: unknown, from: string): Record<string, unknown> | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const record = value as Record<string, unknown>;
+  if (!(from in record)) return null;
+  const next: Record<string, unknown> = {};
+  for (const [key, entry] of Object.entries(record)) {
+    if (key === from) continue;
+    next[key] = entry;
+  }
+  return next;
+}
+
+/**
+ * `provider/model` rows in the top-level `disabledModels` list.
+ *
+ * The retired row is DROPPED rather than renamed: carrying its disabled state to
+ * the new id would hide the supported model behind a toggle the user set for a
+ * different model. An existing row for the new id is left untouched.
+ */
+function renameDisabledModels(config: OcxConfig, rename: ModelRename): boolean {
+  const list = config.disabledModels;
+  if (!Array.isArray(list)) return false;
+  const retired = `${rename.provider}/${rename.from}`;
+  if (!list.includes(retired)) return false;
+  config.disabledModels = list.filter(entry => entry !== retired);
+  return true;
+}
+
+/**
+ * Only migrate a row that still points at the registry's own endpoint. A user who
+ * repointed `baseUrl` at a different vendor owns their model ids.
+ */
+function providerStillMatchesRegistry(name: string, prov: OcxProviderConfig): boolean {
+  const entry = PROVIDER_REGISTRY.find(row => row.id === name);
+  if (!entry) return false;
+  if (!prov.baseUrl || !entry.baseUrl) return true;
+  const choices = entry.baseUrlChoices?.map(choice => choice.baseUrl) ?? [];
+  const known = [entry.baseUrl, ...choices]
+    .filter((url): url is string => typeof url === "string")
+    .map(url => url.replace(/\/+$/, ""));
+  return known.includes(prov.baseUrl.replace(/\/+$/, ""));
+}
+
+/** Guard against a stale rename: only apply when the registry actually seeds `to`. */
+function registrySeedsTarget(rename: ModelRename): boolean {
+  const entry = PROVIDER_REGISTRY.find(row => row.id === rename.provider);
+  return !!entry?.models?.includes(rename.to);
+}
+
+export interface ModelRenameProjection {
+  config: OcxConfig;
+  changed: boolean;
+  warnings: string[];
+}
+
+/**
+ * Pure projection: apply every applicable rename and report what changed. The
+ * caller decides whether to persist.
+ */
+export function projectModelRenames(
+  config: OcxConfig,
+  renames: readonly ModelRename[] = MODEL_RENAMES,
+): ModelRenameProjection {
+  const warnings: string[] = [];
+  let changed = false;
+
+  for (const rename of renames) {
+    const prov = config.providers?.[rename.provider];
+    if (!prov) continue;
+    if (!registrySeedsTarget(rename)) {
+      warnings.push(
+        `registry no longer seeds "${rename.to}" for "${rename.provider}"; skipping the `
+        + `"${rename.from}" rename rather than writing an id the registry does not know.`,
+      );
+      continue;
+    }
+    if (!providerStillMatchesRegistry(rename.provider, prov)) continue;
+
+    // Provider config is a closed interface, so index through one unknown-cast
+    // view rather than casting at each assignment.
+    const row = prov as unknown as Record<string, unknown>;
+    let touched = false;
+    for (const field of MODEL_ID_LISTS) {
+      const next = renameInList(row[field], rename.from, rename.to);
+      if (!next) continue;
+      row[field] = next;
+      touched = true;
+    }
+    for (const field of MODEL_KEYED_RECORDS) {
+      const next = rename.dropReasoningEffortMap && field === "modelReasoningEffortMap"
+        ? dropFromRecord(row[field], rename.from)
+        : renameInRecord(row[field], rename.from, rename.to);
+      if (!next) continue;
+      row[field] = next;
+      touched = true;
+    }
+    if (prov.defaultModel === rename.from) {
+      prov.defaultModel = rename.to;
+      touched = true;
+    }
+    if (renameDisabledModels(config, rename)) touched = true;
+
+    if (touched) {
+      changed = true;
+      warnings.push(
+        `renamed "${rename.provider}/${rename.from}" to "${rename.to}" in the saved config: ${rename.reason}.`,
+      );
+    }
+  }
+
+  return { config, changed, warnings };
+}

package/src/providers/model-rename-startup.ts

@@ -0,0 +1,28 @@
+import { saveConfig } from "../config";
+import { projectModelRenames } from "./model-rename-migration";
+import type { OcxConfig } from "../types";
+
+export interface ModelRenameStartupDeps {
+  project: typeof projectModelRenames;
+  save: (config: OcxConfig) => void;
+}
+
+/**
+ * Apply registry model renames to the saved config at startup (issue #1610).
+ *
+ * No backup is taken, unlike the OpenAI tier and Alibaba region migrations: those
+ * rewrite credentials and provider identity, where a bad projection is not
+ * recoverable from the config alone. This one only rewrites model ids that the
+ * registry itself no longer seeds, and the pre-migration value is a string this
+ * file still names, so the change is reversible by hand.
+ */
+export function runModelRenameStartupMigration(
+  config: OcxConfig,
+  deps: ModelRenameStartupDeps = { project: projectModelRenames, save: saveConfig },
+): OcxConfig {
+  const projection = deps.project(config);
+  for (const warning of projection.warnings) console.warn(`[model-rename-migration] ${warning}`);
+  if (!projection.changed) return projection.config;
+  deps.save(projection.config);
+  return projection.config;
+}

package/src/providers/new-model-policy.ts

@@ -0,0 +1,146 @@
+import type { OcxConfig } from "../types";
+import { routedSlug } from "./slug-codec";
+
+export const MODEL_REMOVAL_GRACE_FETCHES = 3;
+export const MAX_KNOWN_MODELS_PER_PROVIDER = 2_000;
+export const MAX_RECENT_ARRIVALS_PER_PROVIDER = 50;
+
+export type KnownModelBaseline = NonNullable<NonNullable<OcxConfig["modelDiscovery"]>["knownModels"]>[string];
+export type NewModelPolicy = "on" | "off";
+
+export interface NewModelPolicyResult {
+  newIds: string[];
+  nextBaseline: KnownModelBaseline;
+  slugsToDisable: string[];
+  arrivals: Array<{ id: string; at: string }>;
+  overflow: boolean;
+}
+
+/**
+ * Whether a transition actually changes persisted state.
+ *
+ * `updatedAt` moves on every successful fetch, so comparing whole baselines would report a
+ * change every time and rewrite config.json on every catalog convergence — a write amplification
+ * that also churns the config generation other writers revalidate against. Only the fields that
+ * carry meaning are compared.
+ */
+function baselineDiffers(prior: KnownModelBaseline | undefined, next: KnownModelBaseline): boolean {
+  if (!prior) return true;
+  const sameList = (a: readonly string[], b: readonly string[]) =>
+    a.length === b.length && a.every((value, index) => value === b[index]);
+  if (!sameList(prior.ids, next.ids) || !sameList(prior.removed, next.removed)) return true;
+  const priorMissing = prior.missing ?? {};
+  const nextMissing = next.missing ?? {};
+  const keys = new Set([...Object.keys(priorMissing), ...Object.keys(nextMissing)]);
+  for (const key of keys) if (priorMissing[key] !== nextMissing[key]) return true;
+  return false;
+}
+
+/** Pure successful-discovery transition. An absent baseline bootstraps without hiding anything. */
+export function applyNewModelPolicy(options: {
+  provider: string;
+  discoveredIds: Iterable<string>;
+  baseline?: KnownModelBaseline;
+  policy: NewModelPolicy;
+  hasSelectedModels?: boolean;
+  now: string;
+}): NewModelPolicyResult {
+  const discovered = [...new Set(options.discoveredIds)].sort();
+  const prior = options.baseline;
+  if (!prior) {
+    return {
+      newIds: [],
+      nextBaseline: { ids: discovered, removed: [], updatedAt: options.now },
+      slugsToDisable: [], arrivals: [],
+      overflow: discovered.length > MAX_KNOWN_MODELS_PER_PROVIDER,
+    };
+  }
+  const active = new Set(prior.ids);
+  const removed = new Set(prior.removed);
+  const seen = new Set(discovered);
+  const newIds = discovered.filter(id => !active.has(id) && !removed.has(id));
+  const missing: Record<string, number> = {};
+  for (const id of active) {
+    if (seen.has(id)) continue;
+    const count = (prior.missing?.[id] ?? 0) + 1;
+    if (count >= MODEL_REMOVAL_GRACE_FETCHES) {
+      active.delete(id);
+      removed.add(id);
+    } else missing[id] = count;
+  }
+  for (const id of discovered) active.add(id);
+  const unionSize = active.size + removed.size;
+  const overflow = unionSize > MAX_KNOWN_MODELS_PER_PROVIDER;
+  const arrivals = newIds.map(id => ({ id, at: options.now }));
+  return {
+    newIds,
+    nextBaseline: {
+      ids: [...active].sort(), removed: [...removed].sort(), updatedAt: options.now,
+      ...(Object.keys(missing).length ? { missing } : {}),
+    },
+    // A non-empty preset/custom allowlist already excludes arrivals. This explicit no-op is
+    // deliberate: preset mode owns which matching flagships arrive on.
+    slugsToDisable: !overflow && options.policy === "off" && !options.hasSelectedModels
+      ? newIds.map(id => routedSlug(options.provider, id)) : [],
+    arrivals,
+    overflow,
+  };
+}
+
+export function effectiveNewModelPolicy(config: OcxConfig, provider: string): NewModelPolicy {
+  const local = config.providers[provider]?.newModelPolicy;
+  if (local === "on" || local === "off") return local;
+  return config.modelDiscovery?.newModelPolicy ?? "on";
+}
+
+/** Apply authoritative provider rows to a mutable convergence copy; degraded providers are omitted. */
+export function reconcileSuccessfulModelDiscoveries(options: {
+  config: OcxConfig;
+  models: Iterable<{ provider: string; id: string; custom?: boolean }>;
+  authoritativeProviders: Iterable<string>;
+  now: string;
+}): boolean {
+  const byProvider = new Map<string, string[]>();
+  for (const model of options.models) {
+    if (model.custom) continue;
+    const ids = byProvider.get(model.provider) ?? [];
+    ids.push(model.id); byProvider.set(model.provider, ids);
+  }
+  let changed = false;
+  for (const provider of options.authoritativeProviders) {
+    const configured = options.config.providers[provider];
+    if (!configured || configured.liveModels === false) continue;
+    const discoveredIds = byProvider.get(provider) ?? [];
+    const discovery = options.config.modelDiscovery ??= {};
+    const known = discovery.knownModels ??= {};
+    const result = applyNewModelPolicy({
+      provider, discoveredIds, baseline: known[provider],
+      policy: effectiveNewModelPolicy(options.config, provider),
+      hasSelectedModels: (configured.selectedModels?.length ?? 0) > 0,
+      now: options.now,
+    });
+    if (result.overflow) continue;
+    const priorBaseline = known[provider];
+    const baselineChanged = baselineDiffers(priorBaseline, result.nextBaseline);
+    known[provider] = result.nextBaseline;
+    // Keep the previous timestamp when nothing else moved, so a steady-state roster does not
+    // make the baseline look dirty on the next comparison either.
+    if (!baselineChanged && priorBaseline) known[provider] = priorBaseline;
+    if (result.slugsToDisable.length) {
+      const disabled = options.config.disabledModels ??= [];
+      for (const slug of result.slugsToDisable) {
+        if (disabled.includes(slug)) continue;
+        disabled.push(slug);
+        changed = true;
+      }
+    }
+    if (result.arrivals.length) {
+      const recent = discovery.recentArrivals ??= {};
+      recent[provider] = [...(recent[provider] ?? []), ...result.arrivals]
+        .slice(-MAX_RECENT_ARRIVALS_PER_PROVIDER);
+      changed = true;
+    }
+    if (baselineChanged) changed = true;
+  }
+  return changed;
+}

package/src/providers/openai-sidecar.ts

@@ -1,9 +1,11 @@
 import { resolveEnvValue } from "../config";
 import {
+  CodexPoolAuthenticationError,
   headersForCodexAuthContext,
   hasCallerCodexBearer,
   isCodexAuthContextUsable,
   resolveCodexAuthContext,
+  type CodexAccountSelectionAdmission,
   type CodexAuthContext,
 } from "../codex/auth-context";
 import { recordCodexUpstreamOutcome, type CodexUpstreamOutcome } from "../codex/routing";
@@ -11,6 +13,7 @@ import { extractAccountId } from "../oauth/chatgpt";
 import { ForwardAdmissionCredentialError, validateForwardAdmissionCredential } from "../server/auth-cors";
 import type { CodexAccountMode, OcxConfig, OcxProviderConfig } from "../types";
 import {
+  CODEX_FORWARD_BASE_URL,
   isCanonicalOpenAiForwardProvider,
   OPENAI_API_PROVIDER_ID,
   OPENAI_CODEX_PROVIDER_ID,
@@ -29,6 +32,17 @@ export interface ResolvedOpenAiForwardSidecar extends OpenAiForwardSidecarCandid
   recordOutcome?: (outcome: CodexUpstreamOutcome) => void;
 }
 
+/**
+ * Server-resolved exact account selection for a ChatGPT sidecar call.
+ * `accountId` must come from a validated account-qualified route; request headers
+ * are never trusted as account ids. `modelId` is the sidecar's actual upstream
+ * model so cooldown admission and outcome recording use the correct quota scope.
+ */
+export interface ExactOpenAiSidecarAccount {
+  accountId: string;
+  modelId: string;
+}
+
 export interface OpenAiImagesProviderSelection {
   forwardCandidates: OpenAiForwardSidecarCandidate[];
   keyed?: {
@@ -41,11 +55,24 @@ export interface OpenAiImagesProviderSelection {
 
 export function listOpenAiForwardSidecarCandidates(config: OcxConfig): OpenAiForwardSidecarCandidate[] {
   const provider = config.providers[OPENAI_CODEX_PROVIDER_ID];
-  if (!provider || provider.disabled === true || !isCanonicalOpenAiForwardProvider(provider)) return [];
+  if (!provider || provider.disabled === true) return [];
+  // The built-in registry defaults an omitted authMode to forward. Normalize only that
+  // missing field before the strict adapter/destination check; explicit key mode and
+  // noncanonical destinations remain ineligible for ChatGPT credential injection.
+  const canonicalProvider = provider.authMode === undefined
+    ? { ...provider, authMode: "forward" as const }
+    : provider;
+  if (!isCanonicalOpenAiForwardProvider(canonicalProvider)) return [];
+  // The predicate accepts harmless trailing-slash variants. Pin the provider returned
+  // to credential-bearing sidecars so every consumer builds one exact ChatGPT path
+  // instead of independently concatenating the operator's equivalent spelling.
+  const pinnedProvider = canonicalProvider.baseUrl === CODEX_FORWARD_BASE_URL
+    ? canonicalProvider
+    : { ...canonicalProvider, baseUrl: CODEX_FORWARD_BASE_URL };
   return [{
     providerName: OPENAI_CODEX_PROVIDER_ID,
-    provider,
-    accountMode: providerCodexAccountMode(OPENAI_CODEX_PROVIDER_ID, provider) ?? "pool",
+    provider: pinnedProvider,
+    accountMode: providerCodexAccountMode(OPENAI_CODEX_PROVIDER_ID, pinnedProvider) ?? "pool",
   }];
 }
 
@@ -70,7 +97,12 @@ export async function resolveFirstUsableOpenAiSidecar(
   candidates: readonly OpenAiForwardSidecarCandidate[],
   incomingHeaders: Headers,
   config: OcxConfig,
+  options: {
+    exactAccount?: ExactOpenAiSidecarAccount;
+    beginCodexAccountSelection?: () => CodexAccountSelectionAdmission | undefined;
+  } = {},
 ): Promise<ResolvedOpenAiForwardSidecar | undefined> {
+  const { exactAccount } = options;
   let callerBearerMayBeForwarded = true;
   try {
     validateForwardAdmissionCredential(incomingHeaders, config);
@@ -79,6 +111,39 @@ export async function resolveFirstUsableOpenAiSidecar(
     callerBearerMayBeForwarded = false;
   }
   for (const candidate of candidates) {
+    if (exactAccount) {
+      // An account-qualified model is an explicit user choice. Resolve the stored
+      // credential directly even when the provider is globally Direct, and never
+      // consult Pool active state, affinity, probes, or alternates.
+      const authContext = await resolveCodexAuthContext(incomingHeaders, config, "pool", {
+        accountId: exactAccount.accountId,
+        modelId: exactAccount.modelId,
+        beginCodexAccountSelection: options.beginCodexAccountSelection,
+      });
+      if ((authContext.kind !== "pool" && authContext.kind !== "main-pool")
+        || !isCodexAuthContextUsable(authContext, config)) {
+        // Exact selection is fail-closed. A generation/runtime-state race must not fall through
+        // to the caller-bearer error or let a later candidate select another account.
+        throw new CodexPoolAuthenticationError("Selected Codex account is unavailable");
+      }
+      return {
+        ...candidate,
+        authContext,
+        headers: headersForCodexAuthContext(incomingHeaders, authContext),
+        recordOutcome: (outcome: CodexUpstreamOutcome) => recordCodexUpstreamOutcome(
+          config,
+          authContext.accountId,
+          outcome,
+          {
+            modelId: exactAccount.modelId,
+            fixedAccount: true,
+            probeLeaseId: authContext.probeLeaseId,
+            probeQuotaScope: authContext.probeQuotaScope,
+            writerGeneration: authContext.writerGeneration,
+          },
+        ),
+      };
+    }
     if (candidate.accountMode === "direct") {
       if (!callerBearerMayBeForwarded || !hasCallerCodexBearer(incomingHeaders)) continue;
       const headers = directSidecarHeaders(incomingHeaders);
@@ -89,7 +154,9 @@ export async function resolveFirstUsableOpenAiSidecar(
         headers,
       };
     }
-    const authContext = await resolveCodexAuthContext(incomingHeaders, config, candidate.accountMode);
+    const authContext = await resolveCodexAuthContext(incomingHeaders, config, candidate.accountMode, {
+      beginCodexAccountSelection: options.beginCodexAccountSelection,
+    });
     if (!isCodexAuthContextUsable(authContext, config)) continue;
     return {
       ...candidate,
@@ -102,6 +169,7 @@ export async function resolveFirstUsableOpenAiSidecar(
             authContext.accountId,
             outcome,
             {
+              threadId: authContext.affinityKey,
               probeLeaseId: authContext.probeLeaseId,
               writerGeneration: authContext.writerGeneration,
             },

package/src/providers/openai-tier-startup.ts

@@ -1,4 +1,10 @@
-import { backupConfigBeforeOpenAiTierMigration, saveConfig } from "../config";
+import {
+  backupConfigBeforeOpenAiTierMigration,
+  OpenAiTierBackupCollisionError,
+  OpenAiTierRollbackPreserveError,
+  preserveOpenAiTierRollbackSnapshot,
+  saveConfig,
+} from "../config";
 import type { OcxConfig } from "../types";
 import { projectOpenAiTierMigration } from "./openai-tiers";
 
@@ -6,6 +12,23 @@ export interface OpenAiTierStartupDeps {
   project: typeof projectOpenAiTierMigration;
   backup: () => void;
   save: (config: OcxConfig) => void;
+  preserveRollback?: (error: OpenAiTierBackupCollisionError) => void;
+}
+
+function defaultPreserveRollback(error: OpenAiTierBackupCollisionError): void {
+  if (!error.configPath) throw error;
+  try {
+    const preserved = preserveOpenAiTierRollbackSnapshot(error.configPath);
+    console.warn(`[openai-provider-migration] Preserved rollback snapshot at ${preserved}`);
+  } catch (cause) {
+    if (
+      cause instanceof OpenAiTierRollbackPreserveError
+      && (cause.code === "missing" || cause.code === "not-rollback")
+    ) {
+      throw error;
+    }
+    throw cause;
+  }
 }
 
 const DEFAULT_DEPS: OpenAiTierStartupDeps = {
@@ -20,7 +43,13 @@ export function runOpenAiTierStartupMigration(
 ): OcxConfig {
   const projection = deps.project(config);
   if (!projection.changed) return projection.config;
-  deps.backup();
+  try {
+    deps.backup();
+  } catch (error) {
+    if (!(error instanceof OpenAiTierBackupCollisionError)) throw error;
+    (deps.preserveRollback ?? defaultPreserveRollback)(error);
+    deps.backup();
+  }
   deps.save(projection.config);
   for (const warning of projection.warnings) console.warn(`[openai-provider-migration] ${warning}`);
   return projection.config;