@bitkyc08/opencodex 2.73.0 → 2.74.0

package/src/codex/autostart-health.ts

@@ -4,12 +4,14 @@ import type { OcxConfig } from "../types";
 import { getCodexRoutingKind, type CodexRoutingKind } from "./inject";
 import { collectRoutingAdoption, type RoutingAdoptionEvidence } from "./routing-adoption";
 import { diagnoseCodexShim, type CodexShimDiagnostic } from "./shim";
+import { diagnoseMacDesktopStartup, type DesktopStartupDiagnostic } from "../service/desktop-startup";
 
-export type StartupProtection = "service" | "shim" | "none";
+export type StartupProtection = "service" | "desktop" | "shim" | "none";
 export type StartupHealthStatus = "native" | "protected" | "at-risk";
 export type ShimCoverage = "full" | "cli-only" | "none";
 
 export interface StartupHealthInputs {
+  desktop?: DesktopStartupDiagnostic;
   routingKind: CodexRoutingKind;
   autostartEnabled: boolean;
   serviceInstalled: boolean;
@@ -27,6 +29,7 @@ export interface StartupHealthInputs {
 }
 
 export interface StartupHealth {
+  desktop?: DesktopStartupDiagnostic;
   status: StartupHealthStatus;
   routingKind: CodexRoutingKind;
   routingInjected: boolean;
@@ -77,18 +80,22 @@ export function deriveStartupHealth(inputs: StartupHealthInputs): StartupHealth
   // 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 desktopEffective = inputs.platform === "darwin" && !inputs.diagnosticStale
+    && inputs.desktop?.owned === true && inputs.desktop.loginEnabled
+    && inputs.desktop.running && inputs.desktop.viable;
   const protection: StartupProtection = ownsLocalRouting && inputs.serviceViable
     ? "service"
+    : ownsLocalRouting && desktopEffective ? "desktop"
     : ownsLocalRouting && shimEffective
       ? "shim"
       : "none";
-  const rebootSafe = !localRoutingDependency || (ownsLocalRouting && inputs.serviceViable);
+  const rebootSafe = !localRoutingDependency || (ownsLocalRouting && (inputs.serviceViable || desktopEffective));
   const status: StartupHealthStatus = !localRoutingDependency
     ? "native"
     : rebootSafe
       ? "protected"
       : "at-risk";
-  const recommendedCommand = status !== "at-risk"
+  const recommendedCommand = status !== "at-risk" || (ownsLocalRouting && inputs.desktop?.owned)
     ? null
     : inputs.routingKind === "custom-local" || inputs.routingKind === "unknown"
       ? COMMANDS.restoreNative
@@ -115,6 +122,7 @@ export function deriveStartupHealth(inputs: StartupHealthInputs): StartupHealth
 }
 
 export interface StartupHealthDiagnostics {
+  desktop?: DesktopStartupDiagnostic;
   routingKind?: CodexRoutingKind;
   service?: ServiceDiagnostic;
   shim?: CodexShimDiagnostic;
@@ -129,9 +137,11 @@ export function collectStartupHealth(
   const shim = diagnostics.shim ?? diagnoseCodexShim();
   const service = diagnostics.service ?? diagnoseService();
   const routingKind = diagnostics.routingKind ?? getCodexRoutingKind();
+  const desktop = diagnostics.desktop ?? diagnoseMacDesktopStartup();
   const routingAdoption = diagnostics.routingAdoption
     ?? (routingKind === "opencodex-local" ? collectRoutingAdoption({ routingKind }) : undefined);
   return deriveStartupHealth({
+    ...(desktop ? { desktop } : {}),
     routingKind,
     autostartEnabled: codexAutoStartEnabled(config),
     serviceInstalled: service.installed,
@@ -187,9 +197,11 @@ function classifyStartupHealthSummary(health: StartupHealth): string {
     ? "custom remote Codex routing (no local restart dependency)"
     : "native Codex routing (no opencodex restart dependency)";
   if (health.protection === "service") return "protected by background service";
+  if (health.protection === "desktop") return "protected by desktop app at login and its proxy supervisor";
   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.desktop?.owned) return "AT RISK after restart (desktop startup could not be verified; reopen OpenCodex and check Start at Login)";
   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}')`;

package/src/codex/catalog/discovered-natives.ts

@@ -0,0 +1,166 @@
+import { existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { atomicWriteFile } from "../../config/atomic-write";
+import { getConfigDir } from "../../config/paths";
+import { assertNotRealHomeUnderTest } from "../../lib/test-home-guard";
+import { isEligibleConfiguredNativeOpenAiModel, setDiscoveredNativeOpenAiModels } from "./native-models";
+
+export const DISCOVERED_NATIVE_MAX_ROWS = 32;
+/**
+ * A real row carries its full base instructions twice (`base_instructions` and the
+ * `model_messages` template): GPT-6.1 Sol's live row was 87,183 bytes on 2026-09-30, so a
+ * 64 KiB bound silently rejected exactly the model this store exists to discover.
+ */
+export const DISCOVERED_NATIVE_MAX_ROW_BYTES = 256 * 1024;
+export const DISCOVERED_NATIVE_MAX_FILE_BYTES = DISCOVERED_NATIVE_MAX_ROWS * (DISCOVERED_NATIVE_MAX_ROW_BYTES + 1024);
+export const DISCOVERED_NATIVE_RETENTION_MS = 14 * 24 * 60 * 60 * 1000;
+/**
+ * An unchanged row renews its last-seen time on disk at most this often. The entitlement path
+ * records on every successful roster fetch, including request-time ones, so writing each renewal
+ * would put a synchronous file replace (and on Windows an ACL pass) on ordinary traffic.
+ */
+export const DISCOVERED_NATIVE_RENEW_INTERVAL_MS = 60 * 60 * 1000;
+const FILE_NAME = "discovered-native-models.json";
+
+export interface DiscoveredNativeModel {
+  slug: string;
+  row: Record<string, unknown>;
+  firstSeenAt: number;
+  lastSeenAt: number;
+  clientVersion: string;
+}
+
+let loadedPath: string | undefined;
+let models: DiscoveredNativeModel[] = [];
+let fingerprint = "[]";
+let generation = 0;
+
+/** Validate untrusted roster rows without filesystem effects; keep upstream capability metadata. */
+export function validateDiscoveredNativeRows(rows: unknown): Record<string, unknown>[] {
+  if (!Array.isArray(rows)) return [];
+  const accepted = new Map<string, Record<string, unknown>>();
+  for (const candidate of rows) {
+    if (!candidate || typeof candidate !== "object" || Array.isArray(candidate)) continue;
+    const row = candidate as Record<string, unknown>;
+    if (typeof row.slug !== "string" || row.slug.length > 128
+      || !isEligibleConfiguredNativeOpenAiModel(row.slug)
+      || row.supported_in_api !== true || row.visibility === "hide"
+      || typeof row.display_name !== "string" || !row.display_name.trim()
+      || !Array.isArray(row.supported_reasoning_levels)
+      || row.supported_reasoning_levels.length > 16
+      || !row.supported_reasoning_levels.every(level => level && typeof level === "object"
+        && !Array.isArray(level) && typeof level.effort === "string" && level.effort.length > 0
+        && level.effort.length <= 32 && typeof level.description === "string")) continue;
+    if ([row.context_window, row.max_context_window].some(value => value !== undefined && value !== null
+      && (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0))) continue;
+    try {
+      const serialized = JSON.stringify(row);
+      if (Buffer.byteLength(serialized, "utf8") > DISCOVERED_NATIVE_MAX_ROW_BYTES) continue;
+      if (accepted.size >= DISCOVERED_NATIVE_MAX_ROWS && !accepted.has(row.slug)) continue;
+      accepted.set(row.slug, JSON.parse(serialized) as Record<string, unknown>);
+    } catch { /* Cyclic/non-JSON rows cannot be persisted or sent to Codex. */ }
+  }
+  return [...accepted.values()];
+}
+
+function boundedModels(entries: DiscoveredNativeModel[], now: number): DiscoveredNativeModel[] {
+  return entries.filter(entry => entry.lastSeenAt >= now - DISCOVERED_NATIVE_RETENTION_MS)
+    .sort((a, b) => b.lastSeenAt - a.lastSeenAt || a.slug.localeCompare(b.slug))
+    .slice(0, DISCOVERED_NATIVE_MAX_ROWS);
+}
+
+function readModels(path: string, now: number): DiscoveredNativeModel[] {
+  return readModelsWithCount(path, now).models;
+}
+
+/** `storedCount` is the raw entry count, so a caller can tell pruning from an unchanged store. */
+function readModelsWithCount(path: string, now: number): { models: DiscoveredNativeModel[]; storedCount: number } {
+  const empty = { models: [], storedCount: 0 };
+  try {
+    if (statSync(path).size > DISCOVERED_NATIVE_MAX_FILE_BYTES) return empty;
+    const bytes = readFileSync(path, "utf8");
+    if (Buffer.byteLength(bytes, "utf8") > DISCOVERED_NATIVE_MAX_FILE_BYTES) return empty;
+    const data = JSON.parse(bytes) as { version?: unknown; models?: unknown };
+    if (data.version !== 1 || !Array.isArray(data.models) || data.models.length > DISCOVERED_NATIVE_MAX_ROWS) return empty;
+    const valid = new Map<string, DiscoveredNativeModel>();
+    for (const entry of data.models) {
+      if (!entry || typeof entry !== "object" || Array.isArray(entry)) continue;
+      const row = validateDiscoveredNativeRows([entry.row])[0];
+      if (!row || entry.slug !== row.slug
+        || !Number.isSafeInteger(entry.firstSeenAt) || entry.firstSeenAt < 0
+        || !Number.isSafeInteger(entry.lastSeenAt) || entry.lastSeenAt < entry.firstSeenAt
+        || entry.lastSeenAt > now
+        || typeof entry.clientVersion !== "string" || entry.clientVersion.length > 64) continue;
+      valid.set(entry.slug, { slug: entry.slug, row, firstSeenAt: entry.firstSeenAt,
+        lastSeenAt: entry.lastSeenAt, clientVersion: entry.clientVersion });
+    }
+    return { models: boundedModels([...valid.values()], now), storedCount: data.models.length };
+  } catch { return empty; }
+}
+
+function publish(entries: DiscoveredNativeModel[]): void {
+  models = entries;
+  // Seen-at timestamps extend retention but do not invalidate an otherwise identical catalog.
+  const next = JSON.stringify(entries.map(({ slug, row }) => ({ slug, row })).sort((a, b) => a.slug.localeCompare(b.slug)));
+  if (next === fingerprint) return;
+  fingerprint = next;
+  generation += 1;
+  setDiscoveredNativeOpenAiModels(entries.map(entry => entry.row));
+}
+
+/** Load on config activation; switching OpenCodex homes never carries the previous home's rows. */
+export function loadDiscoveredNativeModels(now = Date.now()): void {
+  const path = join(getConfigDir(), FILE_NAME);
+  loadedPath = path;
+  publish(readModels(path, now));
+}
+
+/** Monotonic process-local catalog evidence generation, independent of account identity. */
+export function discoveredNativeModelsGeneration(): number {
+  return generation;
+}
+
+/** A confirmed nonempty roster owns discovery. Optional persistence must never fail entitlement. */
+export function recordDiscoveredNativeModels(rows: unknown, clientVersion: string, now = Date.now()): void {
+  try {
+    if (!Number.isSafeInteger(now) || now < 0 || clientVersion.length > 64) return;
+    const dir = getConfigDir();
+    const path = join(dir, FILE_NAME);
+    // Re-read the store rather than trusting this process's snapshot: another OpenCodex process
+    // sharing the home may have recorded a model since, and merging onto a stale copy would drop
+    // it at the replace below. The write is atomic, not locked, so only a same-instant race remains.
+    const { models: onDisk, storedCount } = readModelsWithCount(path, now);
+    const merged = new Map(loadedPath === path ? models.map(entry => [entry.slug, entry]) : []);
+    for (const entry of onDisk) {
+      const known = merged.get(entry.slug);
+      if (!known || entry.lastSeenAt >= known.lastSeenAt) merged.set(entry.slug, entry);
+    }
+    loadedPath = path;
+    for (const row of validateDiscoveredNativeRows(rows)) {
+      const slug = row.slug as string;
+      const previous = merged.get(slug);
+      if (previous && previous.lastSeenAt > now) continue;
+      if (previous && JSON.stringify(previous.row) === JSON.stringify(row)
+        && now - previous.lastSeenAt < DISCOVERED_NATIVE_RENEW_INTERVAL_MS) continue;
+      merged.set(slug, { slug, row, firstSeenAt: previous?.firstSeenAt ?? now, lastSeenAt: now, clientVersion });
+    }
+    const next = boundedModels([...merged.values()], now);
+    const serialized = JSON.stringify({ version: 1, models: next });
+    if (Buffer.byteLength(serialized, "utf8") > DISCOVERED_NATIVE_MAX_FILE_BYTES) return;
+    publish(next);
+    // Nothing new to say: skip the write (and, for empty rosters, never create the file).
+    if (storedCount === onDisk.length && serialized === JSON.stringify({ version: 1, models: onDisk })) return;
+    if (next.length === 0 && !existsSync(path)) return;
+    assertNotRealHomeUnderTest(dir);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    atomicWriteFile(path, serialized + "\n");
+  } catch { /* Discovery is optional; current in-memory metadata survives a disk write failure. */ }
+}
+
+export function resetDiscoveredNativeModelsForTests(): void {
+  loadedPath = undefined;
+  models = [];
+  fingerprint = "[]";
+  generation += 1;
+  setDiscoveredNativeOpenAiModels([]);
+}

package/src/codex/catalog/metadata.ts

@@ -55,6 +55,8 @@ import {
   SUPPORTED_NATIVE_OPENAI_SLUGS,
   RETIRED_NATIVE_OPENAI_MODELS,
   configuredNativeOpenAiModels,
+  discoveredNativeOpenAiModels,
+  discoveredNativeOpenAiRow,
   hasNativeOpenAiCapabilityMetadata,
   isConfiguredNativeOpenAiModel,
   isNativeOpenAiCapabilityAliasModel,
@@ -219,7 +221,9 @@ const PINNED_UPSTREAM_MODELS: Map<string, RawEntry> = new Map(
 );
 
 function pinnedNativeCapabilityEntry(slug: string): RawEntry | undefined {
-  return PINNED_UPSTREAM_MODELS.get(nativeOpenAiCapabilitySourceSlug(slug));
+  const discovered = discoveredNativeOpenAiRow(slug);
+  return discovered ? discoveredNativeCapabilityEntry(discovered)
+    : PINNED_UPSTREAM_MODELS.get(nativeOpenAiCapabilitySourceSlug(slug));
 }
 
 /**
@@ -419,7 +423,7 @@ export function nativeReasoningEfforts(slug: string): string[] {
   const levels = Array.isArray(upstream?.supported_reasoning_levels)
     ? upstream!.supported_reasoning_levels as Array<{ effort?: string }>
     : [];
-  if (levels.length > 0) {
+  if (levels.length > 0 || discoveredNativeOpenAiRow(slug)) {
     // Preserve the exact pinned per-model ladder. In particular, GPT-5.6 Sol and Terra
     // include ultra while Luna intentionally ends at max.
     return levels.flatMap(l => typeof l.effort === "string" ? [l.effort] : []);
@@ -565,6 +569,8 @@ export function applyNativeVisibility(
 }
 
 function upstreamNativeEntryForSlug(slug: string): RawEntry | undefined {
+  const discovered = discoveredNativeOpenAiRow(slug);
+  if (discovered) return discoveredNativeCapabilityEntry(discovered);
   const sourceSlug = nativeOpenAiCapabilitySourceSlug(slug);
   // A self-described native returns its OWN pinned row; the alias-cloning branch below stays
   // reserved for slugs that genuinely borrow another model's identity. The allowlist is explicit
@@ -605,6 +611,14 @@ function upstreamNativeEntryForSlug(slug: string): RawEntry | undefined {
   return alias;
 }
 
+/** Account-specific grants and prompts are projected from entitlement evidence, never a shared row. */
+function discoveredNativeCapabilityEntry(row: RawEntry): RawEntry {
+  const entry = withDerivedBaseInstructions(structuredClone(row));
+  delete entry.available_access_programs;
+  delete entry.availability_nux;
+  return entry;
+}
+
 /**
  * Backfill `base_instructions` from `model_messages.instructions_template` when upstream ships
  * only the latter.
@@ -633,7 +647,7 @@ export const UPSTREAM_NATIVE_ENTRIES: Map<string, RawEntry> = new Map(
   }),
 );
 
-// Configured natives join the three per-slug tables in place: other modules hold these exact
+// Configured and discovered natives join the per-slug tables in place: modules hold these exact
 // objects, so a replacement would go unseen. Built-in ids are never configured, so a removal
 // cannot delete a built-in row.
 subscribeConfiguredNativeOpenAiModels((current, removed) => {
@@ -647,7 +661,11 @@ subscribeConfiguredNativeOpenAiModels((current, removed) => {
     if (pinned) PINNED_NATIVE_CAPABILITY_ENTRIES.set(slug, pinned);
     const upstream = upstreamNativeEntryForSlug(slug);
     if (upstream) UPSTREAM_NATIVE_ENTRIES.set(slug, upstream);
-    NATIVE_OPENAI_CONTEXT_OVERRIDES[slug] = { ...NATIVE_GPT6_CONTEXT };
+    const discovered = discoveredNativeOpenAiRow(slug);
+    const contextWindow = positiveInt(discovered?.context_window) ?? NATIVE_GPT6_CONTEXT.contextWindow;
+    const maxContextWindow = Math.max(contextWindow,
+      positiveInt(discovered?.max_context_window) ?? NATIVE_GPT6_CONTEXT.maxContextWindow);
+    NATIVE_OPENAI_CONTEXT_OVERRIDES[slug] = { contextWindow, maxContextWindow, maxInputTokens: maxContextWindow };
   }
 });
 
@@ -692,6 +710,7 @@ const SELF_AUTHORED_NATIVE_ROWS: ReadonlySet<string> = new Set([NATIVE_GPT6_ASTR
 
 export function shouldUpgradeToUpstreamEntry(entry: RawEntry): boolean {
   if (typeof entry.slug !== "string" || !UPSTREAM_NATIVE_ENTRIES.has(entry.slug)) return false;
+  if (discoveredNativeOpenAiRow(entry.slug)) return true;
   if (entry.display_name === entry.slug) return true;
   // A row this project authored from a guess is not evidence of upstream truth, however genuine
   // its display name looks. Replace it once, from the pin.
@@ -703,7 +722,7 @@ export function nativeOpenAiSlugs(): string[] {
   const live = catalogNativeSlugs();
   const availableGated = cachedAvailableAccountGatedNativeModels();
   const candidates = live.length > 0
-    ? unique([...live, ...DOCUMENTED_NATIVE_OPENAI_ADDITIONS, ...configuredNativeOpenAiModels()])
+    ? unique([...live, ...DOCUMENTED_NATIVE_OPENAI_ADDITIONS, ...configuredNativeOpenAiModels(), ...discoveredNativeOpenAiModels()])
     : NATIVE_OPENAI_MODELS;
   return candidates.filter(slug => (
     !ACCOUNT_GATED_NATIVE_OPENAI_MODELS.has(slug) || availableGated.has(slug)
@@ -913,5 +932,5 @@ function catalogNativeSlugs(): string[] {
 export function listCatalogNativeSlugs(): string[] {
   // Ensure documented additions (e.g. gpt-6-astra) appear even when the bundled catalog
   // predates the slug — mirrors nativeOpenAiSlugs() which already merges them for /v1/models.
-  return unique([...catalogNativeSlugs(), ...DOCUMENTED_NATIVE_OPENAI_ADDITIONS, ...configuredNativeOpenAiModels()]);
+  return unique([...catalogNativeSlugs(), ...DOCUMENTED_NATIVE_OPENAI_ADDITIONS, ...configuredNativeOpenAiModels(), ...discoveredNativeOpenAiModels()]);
 }

package/src/codex/catalog/model-hints.ts

@@ -437,6 +437,14 @@ export const CALLABLE_CONFIGURED_COMPATIBILITY_MODELS: Readonly<Record<string, R
   "codebuddy-cn": new Set([
     "default",
   ]),
+  // MiniMax serves MiniMax-M3.1-Flash-Preview to Token Plan keys, but its /v1/models roster
+  // does not list the preview (probed 2026-09-30), so a live roster would drop it.
+  minimax: new Set([
+    "MiniMax-M3.1-Flash-Preview",
+  ]),
+  "minimax-cn": new Set([
+    "MiniMax-M3.1-Flash-Preview",
+  ]),
   kimi: new Set([
     "k3[1m]",
     "kimi-k2.7-code",

package/src/codex/catalog/model-visibility.ts

@@ -1,4 +1,5 @@
 import { effectiveProviderAlias, effectiveProviderAliasDecision } from "../../providers/default-aliases";
+import { XAI_OAUTH_FAST_VARIANT_IDS } from "../../providers/xai-fast-model";
 import { initialModelSelectionPending } from "../../providers/initial-model-selection";
 import { execFileSync } from "node:child_process";
 import { createHash, createHmac, randomBytes } from "node:crypto";
@@ -191,6 +192,9 @@ export function shouldExposeProviderModel(providerName: string, modelId: string)
   // xAI /models advertises both the dated deployment and this floating alias.
   // Keep only grok-4.20-multi-agent-0309; the alias is the same server-side id.
   if (providerName === "xai" && modelId === "grok-4.20-multi-agent-beta-latest") return false;
+  // grok-4.7-build-fast is grok-4.7 on a faster serving lane; it is reached through grok-4.7's Fast
+  // selection on OAuth (xai-fast-model.ts), so the lane id is not published as a second model.
+  if (providerName === "xai" && XAI_OAUTH_FAST_VARIANT_IDS.has(modelId)) return false;
   return true;
 }
 

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

@@ -129,7 +129,7 @@ const NATIVE_OPENAI_CAPABILITY_SOURCES: Readonly<Record<string, string>> = Objec
  * keeps rows this runtime does not expose, which is exactly why presence in the pin cannot be
  * the predicate: `gpt-5.4` is still pinned (hidden, with an upgrade to Terra) after its retirement.
  */
-export const SELF_DESCRIBED_NATIVE_OPENAI_MODELS: ReadonlySet<string> = new Set([
+const selfDescribedNativeModels = new Set<string>([
   NATIVE_GPT6_ASTRA_MODEL,
   // Rows come from roster-pinned-models.json via pinnedNativeModelRows(), not the codex-rs pin.
   NATIVE_GPT6_SOL_MODEL,
@@ -137,6 +137,8 @@ export const SELF_DESCRIBED_NATIVE_OPENAI_MODELS: ReadonlySet<string> = new Set(
   NATIVE_GPT61_SOL_MODEL,
 ]);
 
+export const SELF_DESCRIBED_NATIVE_OPENAI_MODELS: ReadonlySet<string> = selfDescribedNativeModels;
+
 /**
  * Native ids whose capability metadata is inherited from another pinned native row.
  *
@@ -155,7 +157,7 @@ export const NATIVE_OPENAI_CAPABILITY_ALIAS_MODELS = Object.freeze(
 );
 
 export function isNativeOpenAiCapabilityAliasModel(slug: string): boolean {
-  return Object.hasOwn(NATIVE_OPENAI_CAPABILITY_SOURCES, slug) || configuredNativeSlugs.has(slug);
+  return Object.hasOwn(NATIVE_OPENAI_CAPABILITY_SOURCES, slug) || (configuredNativeSlugs.has(slug) && !discoveredNativeRows.has(slug));
 }
 
 /**
@@ -175,7 +177,7 @@ export function hasNativeOpenAiCapabilityMetadata(slug: string): boolean {
 
 export function nativeOpenAiCapabilitySourceSlug(slug: string): string {
   return NATIVE_OPENAI_CAPABILITY_SOURCES[slug]
-    ?? (configuredNativeSlugs.has(slug) ? CONFIGURED_NATIVE_OPENAI_TEMPLATE_MODEL : slug);
+    ?? (configuredNativeSlugs.has(slug) && !discoveredNativeRows.has(slug) ? CONFIGURED_NATIVE_OPENAI_TEMPLATE_MODEL : slug);
 }
 
 /**
@@ -196,7 +198,7 @@ export const NATIVE_OPENAI_ALIAS_PRESENTATION: Readonly<Record<string, { display
 
 export function nativeOpenAiAliasPresentation(slug: string): { displayName: string; description: string } | undefined {
   return NATIVE_OPENAI_ALIAS_PRESENTATION[slug]
-    ?? (configuredNativeSlugs.has(slug) ? configuredNativePresentation(slug) : undefined);
+    ?? (configuredNativeSlugs.has(slug) && !discoveredNativeRows.has(slug) ? configuredNativePresentation(slug) : undefined);
 }
 
 /** `gpt-6-nova` -> `GPT-6-Nova`, the same casing upstream uses for its own GPT-6 rows. */
@@ -240,8 +242,8 @@ const BUILT_IN_NATIVE_OPENAI_MODELS: readonly string[] = Object.freeze([
 ]);
 
 /**
- * The built-in list plus every configured native, appended in config order. The array and the Set
- * below are shared by reference across the catalog, `/v1/models` and the dashboard, so
+ * The built-in list plus configured and discovered natives in registration order. The array and
+ * Set below are shared by reference across the catalog, `/v1/models` and the dashboard, so
  * registration edits them in place rather than replacing them.
  */
 export const NATIVE_OPENAI_MODELS: string[] = [...BUILT_IN_NATIVE_OPENAI_MODELS];
@@ -260,6 +262,7 @@ export const SUPPORTED_NATIVE_OPENAI_SLUGS = new Set(NATIVE_OPENAI_MODELS);
  * persist/reconcile path, so any process that loads config — `ocx ensure` included — sees it.
  */
 const configuredNativeSlugs = new Set<string>();
+const discoveredNativeRows = new Map<string, Record<string, unknown>>();
 type ConfiguredNativeListener = (current: readonly string[], removed: readonly string[]) => void;
 const configuredNativeListeners: ConfiguredNativeListener[] = [];
 
@@ -286,25 +289,49 @@ export function setConfiguredNativeOpenAiModels(ids: readonly string[]): void {
   const next = [...new Set(ids.filter(isEligibleConfiguredNativeOpenAiModel))];
   const previous = [...configuredNativeSlugs];
   if (next.length === previous.length && next.every((id, index) => id === previous[index])) return;
-  const removed = previous.filter(id => !next.includes(id));
-  for (const id of previous) {
-    configuredNativeSlugs.delete(id);
-    SUPPORTED_NATIVE_OPENAI_SLUGS.delete(id);
-    const index = NATIVE_OPENAI_MODELS.indexOf(id);
-    if (index >= 0) NATIVE_OPENAI_MODELS.splice(index, 1);
-  }
-  for (const id of next) {
-    configuredNativeSlugs.add(id);
-    SUPPORTED_NATIVE_OPENAI_SLUGS.add(id);
-    NATIVE_OPENAI_MODELS.push(id);
+  configuredNativeSlugs.clear();
+  for (const id of next) configuredNativeSlugs.add(id);
+  refreshDynamicNativeOpenAiModels();
+}
+
+export function discoveredNativeOpenAiModels(): readonly string[] {
+  return [...discoveredNativeRows.keys()];
+}
+
+export function discoveredNativeOpenAiRow(slug: string): Record<string, unknown> | undefined {
+  const row = discoveredNativeRows.get(slug);
+  return row ? structuredClone(row) : undefined;
+}
+
+/** Validated roster rows stay self-described; a later built-in registration wins automatically. */
+export function setDiscoveredNativeOpenAiModels(rows: readonly Record<string, unknown>[]): void {
+  for (const slug of discoveredNativeRows.keys()) selfDescribedNativeModels.delete(slug);
+  discoveredNativeRows.clear();
+  for (const row of rows) {
+    if (typeof row.slug !== "string" || !isEligibleConfiguredNativeOpenAiModel(row.slug)) continue;
+    discoveredNativeRows.set(row.slug, structuredClone(row));
+    selfDescribedNativeModels.add(row.slug);
   }
+  refreshDynamicNativeOpenAiModels();
+}
+
+function dynamicNativeOpenAiModels(): string[] {
+  return [...new Set([...configuredNativeSlugs, ...discoveredNativeRows.keys()])];
+}
+
+function refreshDynamicNativeOpenAiModels(): void {
+  const next = dynamicNativeOpenAiModels();
+  const removed = NATIVE_OPENAI_MODELS.filter(id => !BUILT_IN_NATIVE_OPENAI_MODELS.includes(id) && !next.includes(id));
+  NATIVE_OPENAI_MODELS.splice(0, NATIVE_OPENAI_MODELS.length, ...BUILT_IN_NATIVE_OPENAI_MODELS, ...next);
+  SUPPORTED_NATIVE_OPENAI_SLUGS.clear();
+  for (const id of NATIVE_OPENAI_MODELS) SUPPORTED_NATIVE_OPENAI_SLUGS.add(id);
   for (const listener of configuredNativeListeners) listener(next, removed);
 }
 
-/** Keep derived tables in step; the listener runs immediately with the current set. */
+/** Keep derived tables in step with the configured/discovered union, including metadata updates. */
 export function subscribeConfiguredNativeOpenAiModels(listener: ConfiguredNativeListener): void {
   configuredNativeListeners.push(listener);
-  listener(configuredNativeOpenAiModels(), []);
+  listener(dynamicNativeOpenAiModels(), []);
 }
 
 export function resetConfiguredNativeOpenAiModelsForTests(): void {

package/src/codex/catalog-auto-refresh-sources.ts

@@ -0,0 +1,71 @@
+import type { OcxConfig } from "../types";
+
+const SOURCE_WAIT_MS = 15_000;
+const PROCESS_WAIT_MS = 1_000;
+
+/**
+ * A source failure or slow roster must not prevent publication from existing evidence. The signal
+ * aborts when the wait bound passes or the step ends, so a late source cannot publish afterwards.
+ */
+async function bestEffortSource(step: (active: () => boolean, signal: AbortSignal) => Promise<unknown>): Promise<void> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let active = true;
+  const controller = new AbortController();
+  try {
+    await Promise.race([
+      Promise.resolve().then(() => step(() => active, controller.signal)),
+      new Promise<void>(resolve => {
+        timer = setTimeout(resolve, SOURCE_WAIT_MS);
+        timer.unref?.();
+      }),
+    ]);
+  } catch {
+    // Convergence can still use the last confirmed source snapshots.
+  } finally {
+    active = false;
+    controller.abort();
+    clearTimeout(timer);
+  }
+}
+
+/** Settle source observations before admission captures them; gather itself never probes. */
+export async function refreshCatalogAutoRefreshSources(
+  config: OcxConfig,
+  current: () => boolean,
+): Promise<void> {
+  // Runtime selection also supplies the roster's trusted client version after an upgrade.
+  await bestEffortSource(async active => {
+    const { loadBundledCodexCatalog } = await import("./catalog/bundled");
+    if (active() && current()) loadBundledCodexCatalog();
+    // The synchronous loader bounds its selected-runtime subprocess probes itself.
+  });
+  if (!current()) return;
+  await bestEffortSource(async active => {
+    const { ensureCodexEntitlementFreshness } = await import("./model-entitlements");
+    if (active() && current()) await ensureCodexEntitlementFreshness(config, { waitMs: SOURCE_WAIT_MS });
+  });
+  if (!current()) return;
+  // The entitlement roster above is asked under the installed client version, which upstream's
+  // rollout gate can hide a new model from (GPT-6.1 Sol was invisible to 0.158 on release day).
+  // Discovery asks as a newer client so an unpinned native reaches the converge below.
+  await bestEffortSource(async (active, signal) => {
+    const { discoverCodexNativeRoster } = await import("./model-entitlements");
+    // A stopped scheduler generation aborts too, so a stale tick cannot record discoveries.
+    if (active() && current()) await discoverCodexNativeRoster(config, { signal, isCurrent: () => active() && current() });
+  });
+}
+
+/** Observation only: running sessions own static copies and require an operator restart. */
+export async function catalogAutoRefreshReloadRequired(changed = true): Promise<boolean> {
+  try {
+    const { listCodexAppServerProcesses, collectCodexAppServerCatalogStateWithin } = await import("./app-server-processes");
+    // A cold Windows start-time walk can miss a short deadline. The changed-set hint
+    // needs only the bounded process listing, so it does not depend on that walk.
+    if (changed) return listCodexAppServerProcesses().length > 0;
+    const status = await collectCodexAppServerCatalogStateWithin(PROCESS_WAIT_MS);
+    return status.state === "stale" || status.state === "unknown";
+  } catch {
+    // Failure to observe a restart cannot clear a previously recorded requirement.
+    return !changed;
+  }
+}