@bitkyc08/opencodex 2.68.0-preview.20260927 → 2.69.0-preview.20260928

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

@@ -29,7 +29,12 @@ const MIN_INTERVAL_MS = 15 * 60_000;
  * callers fail fast and defer (ConvergeRequest.mode) rather than holding the
  * write lock across a slow tick.
  */
+import { closeSync, constants, fstatSync, lstatSync, openSync, readSync } from "node:fs";
+import type { OcxConfig } from "../types";
+
 const TICK_DEADLINE_MS = 1_000;
+const MAX_JOURNAL_BYTES = 1024 * 1024;
+const MAX_CATALOG_BYTES = 64 * 1024 * 1024;
 
 let timer: ReturnType<typeof setInterval> | null = null;
 let detachShutdownHook: (() => void) | null = null;
@@ -43,6 +48,111 @@ let generation = 0;
 /** setInterval does not skip a firing while the previous callback is still awaiting. */
 let inFlight = false;
 
+/** Read only a regular file, with a byte limit even if it grows after the stat. */
+function readBoundedRegularFile(path: string, maxBytes: number): string | null {
+  let fd: number | undefined;
+  try {
+    const entry = lstatSync(path);
+    if (!entry.isFile() || entry.size > maxBytes) return null;
+    fd = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    const opened = fstatSync(fd);
+    if (!opened.isFile() || opened.size > maxBytes) return null;
+    const bytes = Buffer.alloc(opened.size + 1);
+    let length = 0;
+    while (length < bytes.length) {
+      const read = readSync(fd, bytes, length, bytes.length - length, null);
+      if (read === 0) break;
+      length += read;
+    }
+    return length > maxBytes ? null : bytes.subarray(0, length).toString("utf8");
+  } catch {
+    return null;
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+}
+
+/** A background observation must not use journaledInjectedCatalogPath(), which cleans invalid journals. */
+function readJournaledCatalogPath(journalPath: string): string | null {
+  const bytes = readBoundedRegularFile(journalPath, MAX_JOURNAL_BYTES);
+  if (bytes === null) return null;
+  try {
+    const journal: unknown = JSON.parse(bytes);
+    if (!journal || typeof journal !== "object" || Array.isArray(journal)) return null;
+    const record = journal as Record<string, unknown>;
+    return record.version === 1 && typeof record.injectedCatalogPath === "string" && record.injectedCatalogPath.trim()
+      ? record.injectedCatalogPath
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+function usableCatalogPath(path: string | null): string | null {
+  if (!path) return null;
+  const bytes = readBoundedRegularFile(path, MAX_CATALOG_BYTES);
+  if (bytes === null) return null;
+  try {
+    const catalog: unknown = JSON.parse(bytes);
+    return catalog && typeof catalog === "object" && Array.isArray((catalog as { models?: unknown }).models)
+      ? path : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Testable path decision with no journal mutation or catalog write. */
+export function selectDriftHealCatalogPath(
+  journalPath: string,
+  defaultCatalogPath: string,
+  resolvePath: (path: string) => string,
+): string | null {
+  const recorded = readJournaledCatalogPath(journalPath);
+  return usableCatalogPath(recorded ? resolvePath(recorded) : null)
+    ?? usableCatalogPath(defaultCatalogPath);
+}
+
+/** Repair only the missing config roots; catalog convergence remains the later tick step. */
+async function healCodexConfigDrift(config: OcxConfig, entryGeneration: number): Promise<"none" | "healed" | "not-healed"> {
+  const [{ codexConfigDrift }, { JOURNAL_PATH, journaledInjectedOpenaiBaseUrl, journaledInjectedRealtimeWsBaseUrl }, { shouldSyncCodexOnStart }, { injectCodexConfig }, { DEFAULT_CATALOG_PATH, resolveCodexConfigPath }, { loadConfig }] =
+    await Promise.all([
+      import("./config-drift-heal"),
+      import("./journal"),
+      import("./desired-state"),
+      import("./inject"),
+      import("./paths"),
+      import("../config"),
+    ]);
+  const capturedSettings = JSON.stringify(config);
+  const current = () => entryGeneration === generation && JSON.stringify(loadConfig()) === capturedSettings;
+  if (!current()) return "none";
+  if (!shouldSyncCodexOnStart(config)) return "none";
+  const journaled = {
+    injectedOpenaiBaseUrl: journaledInjectedOpenaiBaseUrl({ readOnly: true }),
+    injectedRealtimeWsBaseUrl: journaledInjectedRealtimeWsBaseUrl({ readOnly: true }),
+  };
+  const drift = codexConfigDrift(() => journaled);
+  if (!drift.drifted) return "none";
+  const { readRuntimePort } = await import("../config/process-state");
+  if (!current()) return "none";
+  const runtime = readRuntimePort(process.pid);
+  if (!runtime) return "not-healed";
+  const catalogPath = selectDriftHealCatalogPath(JOURNAL_PATH, DEFAULT_CATALOG_PATH, resolveCodexConfigPath);
+  if (!current()) return "none";
+  // Keep the missing routing roots visible to the next tick. Catalog-only convergence below
+  // may recreate the file now, but it does not re-inject config.toml in this tick.
+  if (catalogPath === null) return "not-healed";
+  await injectCodexConfig(runtime.port, config, {
+    catalogPath,
+    lockTimeoutMs: TICK_DEADLINE_MS,
+    beforeClientWrite: () => {
+      if (!current()) throw new Error("Catalog drift heal tick is stale");
+    },
+  }).catch(() => null);
+  if (!current()) return "none";
+  return codexConfigDrift(() => journaled).drifted ? "not-healed" : "healed";
+}
+
 /** Number of ticks that have run. Test-only observability; carries no catalog data. */
 let tickCount = 0;
 
@@ -89,6 +199,18 @@ async function tick(): Promise<void> {
     // callee at all. Only while this tick still owns the timer.
     restartIfCadenceChanged(configured);
     tickCount += 1;
+    // Config-surface healing precedes catalog work: a desktop app rewrite that stripped the
+    // injected routing keys leaves the catalog file untouched, so the converge below would
+    // report "no change" while Codex serves its native model picker. Re-injecting through the
+    // standard sync rewrites the keys, re-journals the baseline, and only runs when the
+    // integration is on and this install is allowed to manage its local client.
+    const heal = await healCodexConfigDrift(config, entryGeneration);
+    if (entryGeneration !== generation) return;
+    if (heal === "healed") {
+      console.info("[catalog-auto-refresh] injected Codex config keys were rewritten externally; re-injected");
+    } else if (heal === "not-healed") {
+      console.info("[catalog-auto-refresh] injected Codex config keys were rewritten externally; not re-injected this tick");
+    }
     const [{ createManagementConvergeCodex }, { createCatalogConvergeRequest }] = await Promise.all([
       import("./management-convergence"),
       import("./catalog-admission"),

package/src/codex/config-drift-heal.ts

@@ -0,0 +1,80 @@
+/**
+ * Config-surface drift detection for the injected Codex config.
+ *
+ * The Codex desktop app rewrites `~/.codex/config.toml` on its own schedule — app updates,
+ * settings changes, reserializations — and a 26.924-era rewrite strips the injected root keys
+ * (`openai_base_url`, `model_catalog_json`, the realtime sideband) that carry proxy routing
+ * and the model list. Nothing else notices: the catalog file survives, so the catalog-only
+ * converge funnel reports "no change", and the app keeps serving its native model picker.
+ * Startup sync re-injects, but the proxy may run for days between restarts.
+ *
+ * This module answers the one question the journal was built to answer and nobody asked in
+ * the background: are the bytes on disk still the bytes opencodex injected? The journal
+ * records the values the last injection wrote (`injectedOpenaiBaseUrl`,
+ * `injectedRealtimeWsBaseUrl`). A caller polls `codexConfigDrift()`; when a journaled root
+ * key is absent while the journal says it should be present, the caller re-runs the standard
+ * injection, which rewrites the keys and re-journals the new baseline.
+ *
+ * Deliberately not a filesystem watcher: launchd/FSWatcher coverage for an arbitrary home
+ * adds an agent surface for a file that also changes for legitimate reasons (the user's own
+ * edits, `ocx restore`). Polling at the auto-refresh cadence bounds staleness to one interval
+ * and reuses an already-armed timer.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { CODEX_CONFIG_PATH } from "./paths";
+import {
+  REALTIME_WS_BASE_URL_KEY,
+  rootTomlString,
+} from "./injected-marker";
+
+export interface CodexConfigDrift {
+  /**
+   * An injected routing key is absent from the on-disk config while the journal says the
+   * last injection wrote it: the surface was rewritten underneath opencodex.
+   */
+  readonly drifted: boolean;
+  /** Which injected keys went missing. Empty when not drifted. */
+  readonly missingKeys: readonly string[];
+}
+
+/**
+ * Compare the on-disk config against what the journal says the last injection wrote.
+ *
+ * The journal is the only authority: a config that never was injected (no journal, or a
+ * journal without recorded URLs) reports no drift, because there is nothing to heal. A
+ * PRESENT key always satisfies the check regardless of its value — the injector's own
+ * user-ownership rules (a user's `openai_base_url` without the marker is kept, reported as
+ * `keptUserBaseUrl`, and re-journaled as null) own that case, so a heal triggered on a
+ * missing key runs into them and stops on its own rather than stomping a user's routing.
+ */
+export function codexConfigDrift(
+  readJournal: () => { injectedOpenaiBaseUrl?: string | null; injectedRealtimeWsBaseUrl?: string | null } | null,
+  configPath: string = CODEX_CONFIG_PATH,
+  readFile: (path: string) => string = path => readFileSync(path, "utf-8"),
+  fileExists: (path: string) => boolean = existsSync,
+): CodexConfigDrift {
+  const journal = readJournal();
+  const journaledBaseUrl = journal?.injectedOpenaiBaseUrl;
+  const journaledRealtimeWsUrl = journal?.injectedRealtimeWsBaseUrl;
+  if (!journaledBaseUrl && !journaledRealtimeWsUrl) {
+    return { drifted: false, missingKeys: [] };
+  }
+  if (!fileExists(configPath)) {
+    return { drifted: false, missingKeys: [] };
+  }
+  let content: string;
+  try {
+    content = readFile(configPath);
+  } catch {
+    return { drifted: false, missingKeys: [] };
+  }
+  const missingKeys: string[] = [];
+  if (journaledBaseUrl && rootTomlString(content, "openai_base_url") === null) {
+    missingKeys.push("openai_base_url");
+  }
+  if (journaledRealtimeWsUrl && rootTomlString(content, REALTIME_WS_BASE_URL_KEY) === null) {
+    missingKeys.push(REALTIME_WS_BASE_URL_KEY);
+  }
+  return { drifted: missingKeys.length > 0, missingKeys };
+}

package/src/codex/desktop-switches.ts

@@ -116,14 +116,16 @@ export function describeCodexDesktopSwitches(
  */
 export async function observedCodexDesktopSwitchApply(): Promise<CodexDesktopSwitchApply> {
   // Same lazy boundary as applyCodexConfigInjection: the ownership predicate lives in the
-  // injection graph, which the settings read path must not pull in at module scope.
-  const { currentExternalCodexModelProvider } = await import("./inject/config-toml");
+  // injection graph, which the settings read path must not pull in at module scope. This
+  // path uses the bounded variant — a special or oversized config.toml must answer
+  // "undetermined", never stall a settings read the way an unbounded readFileSync would.
+  const { observedExternalCodexModelProvider } = await import("./inject/config-toml");
   let provider: string | null;
   try {
-    provider = currentExternalCodexModelProvider();
+    provider = observedExternalCodexModelProvider();
   } catch (error) {
-    // A present-but-unreadable config.toml (permissions, deletion racing existsSync)
-    // must not take down the whole settings report. The undetermined reason keeps the
+    // A present-but-unreadable config.toml (permissions, deletion racing the bounded
+    // read) must not take down the whole settings report. The undetermined reason keeps the
     // reporting contract honest: effective values and the sign-in answer stay null instead
     // of presenting local state a foreign provider may still control.
     return {

package/src/codex/inject/bounded-config-reader.ts

@@ -0,0 +1,69 @@
+import { closeSync, constants, fstatSync, openSync, readSync, statSync, type Stats } from "node:fs";
+
+const MAX_CODEX_CONFIG_BYTES = 1024 * 1024;
+
+/**
+ * Read config.toml the way Codex and the injector resolve it — a symlink's target IS the
+ * config — without blocking on a special file or buffering without bound.
+ *
+ * `null` means only "absent at the initial lookup". A path that vanishes or is swapped
+ * underneath the read throws the changed-file error instead, because the observation is
+ * then undetermined rather than negative: the caller must not report a config the probe
+ * watched disappear as simply not there.
+ */
+export function readBoundedCodexConfig(path: string): string | null {
+  let fd: number | undefined;
+  try {
+    let namedBefore: Stats;
+    try {
+      namedBefore = statSync(path);
+    } catch (error) {
+      const code = (error as NodeJS.ErrnoException).code;
+      if (code === "ENOENT" || code === "ENOTDIR") return null;
+      throw error;
+    }
+    if (!namedBefore.isFile() || namedBefore.size > MAX_CODEX_CONFIG_BYTES) {
+      throw new Error("config.toml is not a bounded regular file");
+    }
+    // Deliberately no O_NOFOLLOW: Codex and the injector read through a symlinked
+    // config.toml, so refusing the link here would disagree with the writes this probe
+    // stands in front of. O_NONBLOCK is what keeps a FIFO — linked or direct — from
+    // stalling the open; the descriptor checks below still reject anything non-regular.
+    const guardedFlags = process.platform === "win32"
+      ? 0
+      : (constants.O_NONBLOCK ?? 0);
+    fd = openSync(path, constants.O_RDONLY | guardedFlags);
+    const before = fstatSync(fd);
+    if (before.dev !== namedBefore.dev || before.ino !== namedBefore.ino) {
+      throw new Error("config.toml changed while it was read");
+    }
+    if (!before.isFile() || before.size > MAX_CODEX_CONFIG_BYTES) {
+      throw new Error("config.toml is not a bounded regular file");
+    }
+
+    const buffer = Buffer.allocUnsafe(before.size + 1);
+    let bytesRead = 0;
+    while (bytesRead < buffer.length) {
+      const count = readSync(fd, buffer, bytesRead, buffer.length - bytesRead, null);
+      if (count === 0) break;
+      bytesRead += count;
+    }
+    const after = fstatSync(fd);
+    const namedAfter = statSync(path);
+    if (bytesRead !== before.size || after.size !== before.size
+      || after.mtimeMs !== before.mtimeMs || after.ctimeMs !== before.ctimeMs
+      || !namedAfter.isFile()
+      || namedAfter.dev !== before.dev || namedAfter.ino !== before.ino) {
+      throw new Error("config.toml changed while it was read");
+    }
+    return buffer.toString("utf8", 0, bytesRead);
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === "ENOENT" || code === "ENOTDIR") {
+      throw new Error("config.toml changed while it was read");
+    }
+    throw error;
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+}

package/src/codex/inject/config-toml.ts

@@ -8,6 +8,8 @@ import {
   REALTIME_WS_BASE_URL_KEY,
   isRootOpenaiBaseUrlLine,
   isRootRealtimeWsBaseUrlLine,
+  providerTableStart,
+  providerTableString,
   rootTomlString,
   tomlStringPattern,
 } from "../injected-marker";
@@ -18,6 +20,7 @@ import {
   resolveCodexConfigPath,
   tomlString,
 } from "../paths";
+import { readBoundedCodexConfig } from "./bounded-config-reader";
 import {
   type CodexRoutingTarget,
   providerBaseHost,
@@ -28,16 +31,41 @@ import {
 
 export function externalCodexModelProvider(content: string): string | null {
   const provider = resolveEffectiveProjectModelProvider(content).provider;
-  return provider && provider !== "openai" && provider !== "opencodex"
-    ? provider
-    : null;
+  if (!provider || provider === "openai" || provider === "opencodex") return null;
+  // A provider table counts as an external owner only when it carries a `base_url` — a
+  // gateway names somebody else's endpoint. A base-url-less table is the Codex desktop
+  // app's own native-routing placeholder (since app 26.924 each app-managed rewrite
+  // writes `model_provider = "custom"` plus such a table, stripping the injected root
+  // keys alongside), which re-injects cleanly because the injector strips a root
+  // `model_provider` line first. A REAL external provider must carry a base_url.
+  if (providerTableStart(content.split("\n"), provider) !== -1 && providerTableString(content, provider, "base_url") === null) {
+    return null;
+  }
+  return provider;
 }
 
+/**
+ * The ownership answer for read/write paths — inject, sync, connect, restore, and the
+ * shutdown gate. It deliberately reads the whole file like Codex does (links included):
+ * a large or link-mediated config is still a valid config, and these callers must
+ * classify it exactly rather than degrade to "undetermined".
+ */
 export function currentExternalCodexModelProvider(): string | null {
   if (!existsSync(CODEX_CONFIG_PATH)) return null;
   return externalCodexModelProvider(readFileSync(CODEX_CONFIG_PATH, "utf8"));
 }
 
+/**
+ * The same ownership answer for read-only observation (the settings GET / poll path),
+ * through a bounded read so a special or oversized config.toml cannot stall a request.
+ * A present-but-unreadable config throws so the caller reports undetermined ownership
+ * instead of "none".
+ */
+export function observedExternalCodexModelProvider(): string | null {
+  const content = readBoundedCodexConfig(CODEX_CONFIG_PATH);
+  return content === null ? null : externalCodexModelProvider(content);
+}
+
 /**
  * Detect the file's dominant line ending. Every transform in this module is LF-pure
  * (split("\n") + hard "\n" joins), so CRLF configs (Windows-edited config.toml) are

package/src/codex/inject/routing-target.ts

@@ -50,6 +50,12 @@ export function usesProviderTable(target: CodexRoutingTarget): boolean {
     || target.clientCompaction === true;
 }
 
+/** Listing is owned by native app-server, not the inference proxy; never repair it by retagging. */
+export function remoteThreadListCompatibilityWarning(target: CodexRoutingTarget): string {
+  if (!usesProviderTable(target)) return "";
+  return "  ⚠️ Codex remote history: some app-server/mobile versions filter thread/list to the default provider and may hide existing openai-tagged threads. This is listing visibility, not deleted history. A compatible list client can request modelProviders: []; otherwise verify native client/app-server compatibility. OpenCodex does not change history tags for this warning.\n";
+}
+
 export function standaloneCodexRoutingTarget(
   port: number,
   config?: Pick<
@@ -122,4 +128,3 @@ export function providerBaseHost(hostname: string | undefined): string {
   if (trimmed.startsWith("[") && trimmed.endsWith("]")) return trimmed;
   return trimmed.includes(":") ? `[${trimmed}]` : trimmed;
 }
-

package/src/codex/inject.ts

@@ -65,6 +65,7 @@ import {
 import type { OcxConfig } from "../types";
 import {
   configuredManagedSubagentDefaults,
+  remoteThreadListCompatibilityWarning,
   standaloneCodexRoutingTarget,
   validateCodexRoutingTarget,
   type CodexRoutingTarget,
@@ -718,6 +719,7 @@ async function injectCodexConfigImpl(
   const catalogMessage = effectivePlan.catalogPath
     ? `  Codex model catalog: ${effectivePlan.catalogPath}\n`
     : `  Codex model catalog not injected because no opencodex catalog file exists yet.\n`;
+  const remoteHistoryMessage = remoteThreadListCompatibilityWarning(routingTarget);
   const ejected = (history as { ejectedRows?: number }).ejectedRows ?? 0;
   const migratedRows = (history.rows ?? 0) + ejected;
   const historyMessage =
@@ -753,6 +755,7 @@ async function injectCodexConfigImpl(
         `  Your root openai_base_url was left exactly as you set it, so opencodex did not add its own.\n` +
         catalogMessage +
         historyMessage +
+        remoteHistoryMessage +
         effectivePlan.managedDefaultsMessage +
         `  New threads use the injected opencodex provider and route through the proxy.\n` +
         `  Threads already tagged openai resolve through Codex's built-in provider, which your root openai_base_url points at.\n` +
@@ -791,6 +794,7 @@ async function injectCodexConfigImpl(
       headline +
       catalogMessage +
       historyMessage +
+      remoteHistoryMessage +
       effectivePlan.managedDefaultsMessage +
       `  All models now route through opencodex proxy (like OpenRouter).\n` +
       `  OpenAI models (gpt-5.5, etc.) are passed through to OpenAI.\n` +

package/src/codex/model-entitlements.ts

@@ -408,6 +408,7 @@ interface CachedAccountModels {
   readonly expiresAt: number;
   readonly models: ReadonlySet<string>;
   readonly accessProgramsByModel?: ReadonlyMap<string, CodexAvailableAccessPrograms>;
+  readonly availabilityNuxByModel?: ReadonlyMap<string, { message: string }>;
   readonly confirmed: boolean;
   readonly provenance?: CodexModelEntitlementProvenance;
 }
@@ -415,6 +416,7 @@ interface CachedAccountModels {
 export interface CodexModelEntitlementSnapshot {
   readonly modelsByAccount: ReadonlyMap<string, ReadonlySet<string>>;
   readonly accessProgramsByAccount?: ReadonlyMap<string, ReadonlyMap<string, CodexAvailableAccessPrograms>>;
+  readonly availabilityNuxByAccount?: ReadonlyMap<string, ReadonlyMap<string, { message: string }>>;
   readonly clientVersionByAccount: ReadonlyMap<string, string>;
   readonly confirmedAccountIds: ReadonlySet<string>;
   readonly credentialIdentities: ReadonlyMap<string, string>;
@@ -637,16 +639,36 @@ async function accountCredentialSnapshot(
   }
 }
 
-/** Keep valid roster slugs while dropping malformed program metadata; preserve explicit null separately from absence. */
-function parseAccountModels(text: string): { models: ReadonlySet<string>; accessProgramsByModel: ReadonlyMap<string, CodexAvailableAccessPrograms> } | null {
+const AVAILABILITY_MESSAGE_MAX_CODE_UNITS = 2_000;
+// Codex parses the catalog with a strict JSON reader that rejects a lone surrogate escape.
+const LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g;
+
+/** Trim and cap a prompt without leaving half of a surrogate pair at the cut or anywhere else. */
+function boundedAvailabilityMessage(message: string): string {
+  return message.trim().slice(0, AVAILABILITY_MESSAGE_MAX_CODE_UNITS).replace(LONE_SURROGATE, "").trim();
+}
+
+/** Keep valid roster slugs while dropping malformed program and availability metadata. */
+function parseAccountModels(text: string): {
+  models: ReadonlySet<string>;
+  accessProgramsByModel: ReadonlyMap<string, CodexAvailableAccessPrograms>;
+  availabilityNuxByModel: ReadonlyMap<string, { message: string }>;
+} | null {
   try {
     const payload = JSON.parse(text) as { models?: unknown };
     if (!Array.isArray(payload.models)) return null;
     const accessProgramsByModel = new Map<string, CodexAvailableAccessPrograms>();
+    const availabilityNuxByModel = new Map<string, { message: string }>();
     const models = payload.models.flatMap(entry => {
       if (!entry || typeof entry !== "object" || Array.isArray(entry)) return [];
-      const row = entry as { slug?: unknown; supported_in_api?: unknown; visibility?: unknown; available_access_programs?: unknown };
+      const row = entry as { slug?: unknown; supported_in_api?: unknown; visibility?: unknown; available_access_programs?: unknown; availability_nux?: unknown };
       if (typeof row.slug !== "string" || row.supported_in_api !== true || row.visibility === "hide") return [];
+      const nux = row.availability_nux;
+      if (nux && typeof nux === "object" && !Array.isArray(nux)) {
+        const message = (nux as { message?: unknown }).message;
+        const bounded = typeof message === "string" ? boundedAvailabilityMessage(message) : "";
+        if (bounded) availabilityNuxByModel.set(row.slug, { message: bounded });
+      }
       const programs = row.available_access_programs;
       if (programs === null) accessProgramsByModel.set(row.slug, null);
       else if (programs && typeof programs === "object" && !Array.isArray(programs)) {
@@ -659,7 +681,7 @@ function parseAccountModels(text: string): { models: ReadonlySet<string>; access
       }
       return [row.slug];
     });
-    return { models: new Set(models), accessProgramsByModel };
+    return { models: new Set(models), accessProgramsByModel, availabilityNuxByModel };
   } catch {
     return null;
   }
@@ -730,7 +752,7 @@ async function fetchAccountModels(
     // account asked under too old a client version answers with no gated rows, and treating
     // that as authoritative is exactly how 2.36.0 denied sol/terra/luna to accounts that own
     // them (#3022). No usable rows means unconfirmed, on the 15s failure TTL, asked again.
-    const { models, accessProgramsByModel } = parsed;
+    const { models, accessProgramsByModel, availabilityNuxByModel } = parsed;
     const usable = models.size > 0;
     if (!usable) {
       return unconfirmedAccountModels(credential, clientVersion, now, { kind: "parsed-empty" });
@@ -754,6 +776,7 @@ async function fetchAccountModels(
         : MODEL_ROSTER_FAILURE_TTL_MS),
       models,
       accessProgramsByModel,
+      availabilityNuxByModel,
       confirmed: true,
     };
   } catch (error) {
@@ -1196,6 +1219,10 @@ export async function resolveCodexModelEntitlements(
       result.confirmed && result.accessProgramsByModel
         ? [[credential.accountId, result.accessProgramsByModel] as const] : []
     ))),
+    availabilityNuxByAccount: new Map(results.flatMap(({ credential, result }) => (
+      result.confirmed && result.availabilityNuxByModel
+        ? [[credential.accountId, result.availabilityNuxByModel] as const] : []
+    ))),
     clientVersionByAccount: new Map(results.map(({ credential, result }) => (
       [credential.accountId, result.clientVersion]
     ))),

package/src/codex/native-profile-startup.ts

@@ -78,6 +78,8 @@ interface StartupEntry {
   recoveryStarted: boolean;
   policyBindingPending: boolean;
   settled: Promise<NativeMainStartupGateSnapshot>;
+  /** Publication provenance only; never substitutes for the live convergence drain. */
+  snapshotSettled?: Promise<NativeMainStartupGateSnapshot>;
   resolveAcquisition?: (value: NativeMainStartupGateSnapshot) => void;
   deps: NativeMainStartupGateDeps;
   manager: NativeProfileManager;
@@ -401,6 +403,7 @@ export function startNativeMainStartupLifecycle(
     released = true;
     entry!.refs = Math.max(0, entry!.refs - 1);
     if (entry!.refs !== 0) return;
+    const releasedEpoch = entry!.epoch;
     entry!.epoch += 1;
     entry!.sweepStopping = true;
     if (entry!.sweepTimer) clearTimeout(entry!.sweepTimer);
@@ -413,11 +416,17 @@ export function startNativeMainStartupLifecycle(
     // the process exited, because a server whose config does not sync Codex installs a no-op
     // lifecycle that never touches the gate.
     //
-    // The gate state belonged only to this entry, so reset it to the process-initial state here,
-    // synchronously and before the first await: a NEW entry created for the same home afterwards
-    // re-arms its own gate and cannot be clobbered by this release. The epoch bump retires any
-    // in-flight `initializeNativeMainStartupGate`/convergence write from the released generation.
-    if (snapshot.homeId === homeId && !startupEntries.has(homeId)) {
+    // Reset only a snapshot published by this startup generation. A profile transaction can
+    // independently replace it with a same-home recovery fence, which must survive this release.
+    // The epoch provenance misses one case: that fence advances the global epoch while this
+    // generation's convergence is still in flight, and `completeNativeMainRecovery` then rebinds
+    // the shared `settled` to this entry's own pending chain without re-stamping either epoch.
+    // The pending snapshot is again this generation's own, so `settled` identity proves it too.
+    // Do this synchronously and before the first await: a NEW entry created for the same home
+    // afterwards re-arms its own gate and cannot be clobbered by this release. The epoch bump
+    // retires any in-flight convergence write from the released generation.
+    if (snapshot.homeId === homeId && !startupEntries.has(homeId)
+      && (epoch === releasedEpoch || settled === entry!.settled || settled === entry!.snapshotSettled)) {
       epoch += 1;
       snapshot = ready(null);
       settled = Promise.resolve(snapshot);
@@ -728,6 +737,9 @@ export function completeNativeMainRecovery(homeId: string): boolean {
   clearAccountNeedsReauth(MAIN_CODEX_ACCOUNT_ID);
   snapshot = ready(homeId);
   settled = Promise.resolve(snapshot);
+  // Remember who published this snapshot without replacing an in-flight recovery/sweep
+  // promise: last-reference release must still drain that original convergence chain.
+  if (entry) entry.snapshotSettled = settled;
   return true;
 }