@bitkyc08/opencodex 2.59.0 → 2.60.0

package/src/codex/catalog/routed-gather.ts

@@ -113,6 +113,15 @@ export interface GatherRoutedModelsOptions {
   providerModelOutcomes?: CatalogGatherProviderModelOutcome[];
   /** Internal convergence sink for the immutable policy that produced the returned rows. */
   discoveryPolicySnapshots?: CatalogProviderDiscoveryPolicySnapshot[];
+  /**
+   * Each provider's cache content revision as of the moment its rows were chosen.
+   *
+   * A caller that derives something from these rows and wants to know later whether the rows are
+   * still current must use this, not a revision sampled after the gather returns: another flight
+   * can publish between the choice and the sample, and the derived value would then carry that
+   * flight's identity while holding these rows.
+   */
+  providerContentRevisions?: Map<string, string>;
 }
 
 interface GatherFlightResult {
@@ -121,6 +130,7 @@ interface GatherFlightResult {
   providerAuthOutcomes: readonly CatalogGatherProviderAuthOutcome[];
   providerModelOutcomes: readonly CatalogGatherProviderModelOutcome[];
   discoveryPolicySnapshots: readonly CatalogProviderDiscoveryPolicySnapshot[];
+  providerContentRevisions: ReadonlyMap<string, string>;
 }
 interface GatherInflightEntry {
   readonly discoveryPolicyIdentity: string;
@@ -256,6 +266,7 @@ async function gatherRoutedModelsWithAuth(
     providerAuthOutcomes,
     providerModelOutcomes,
     discoveryPolicySnapshots,
+    providerContentRevisions,
   } = await entry.promise;
   if (options?.comboOmissions) {
     options.comboOmissions.length = 0;
@@ -269,6 +280,12 @@ async function gatherRoutedModelsWithAuth(
     options.providerModelOutcomes.length = 0;
     options.providerModelOutcomes.push(...providerModelOutcomes);
   }
+  if (options?.providerContentRevisions) {
+    options.providerContentRevisions.clear();
+    for (const [provider, revision] of providerContentRevisions) {
+      options.providerContentRevisions.set(provider, revision);
+    }
+  }
   if (options?.discoveryPolicySnapshots) {
     options.discoveryPolicySnapshots.length = 0;
     options.discoveryPolicySnapshots.push(...discoveryPolicySnapshots);
@@ -763,6 +780,8 @@ async function gatherRoutedModelsUncached(
     providerAuthOutcomes: localProviderAuthOutcomes,
     providerModelOutcomes,
     discoveryPolicySnapshots: capture.discoveryPolicySnapshots,
+    // Stamped by each provider at the moment it chose its rows, not sampled here.
+    providerContentRevisions: new Map(providerResults.map(result => [result.outcome.provider, result.contentRevision])),
   };
 }
 

package/src/codex/context-compat.ts

@@ -7,14 +7,17 @@ export const CONTEXT_BACKEND_PREFIX = "/backend-api/codex";
 
 /** The single definition of the opt-in, shared by injection and the runtime gate. */
 export function contextExperimentalEnabled(configContent: string): boolean {
-  let parsed: { features?: { context_management?: { experimental_mode?: boolean } } };
+  let parsed: { features?: { context_management?: boolean | { experimental_mode?: boolean } } };
   try {
     parsed = Bun.TOML.parse(configContent) as typeof parsed;
   } catch {
     // Injection tolerates incomplete user config; malformed TOML is not an opt-in.
     return false;
   }
-  return parsed.features?.context_management?.experimental_mode === true;
+  // Codex FeatureToml accepts either a boolean or the experimental_mode table.
+  // Keep strict true checks: malformed values must not activate a credentialed relay.
+  const setting = parsed.features?.context_management;
+  return setting === true || (typeof setting === "object" && setting?.experimental_mode === true);
 }
 
 let activation: { key: string; active: boolean } | undefined;

package/src/codex/desired-state.ts

@@ -260,7 +260,10 @@ export async function syncCodexOnStartIfEnabled(
   // The `.catch` is deliberate and stays: a failure to APPLY must not stop the
   // proxy from coming up. A failed sync simply reports no writes. The readiness
   // gate observes the real outcome so /readyz reflects the sync state exactly as
-  // the PR contract defines (ready only on ok=true with no warning).
+  // the contract defines: ready on ok=true once the sync has settled. A nonempty
+  // `warning` is a local-Codex-artifact degradation the sync chose to continue
+  // past, and #5181 is what it cost to treat it as terminal — a healthy
+  // multi-provider proxy reported itself permanently unready.
   const outcome = readinessGate
     ? await runStartupReadinessSync(readinessGate, async () => (await sync(port)) ?? null)
     : await sync(port).catch(() => undefined);

package/src/codex/history-job.ts

@@ -23,7 +23,7 @@ import type {
   CodexHistoryWorkerOperation,
   HistoryWorkerResult,
 } from "./history-worker";
-import { currentHistoryDbBusyTimeoutMs, historyBackupPathFor } from "./history-provider";
+import { currentHistoryDbBusyTimeoutMs, resolveExistingHistoryBackupPath } from "./history-provider";
 import type { CodexHistoryFailureReason, CodexHistoryVerifiedNoopProof } from "./history-provider";
 import { getCodexHome, resolveCodexStateDbPath } from "./paths";
 
@@ -32,7 +32,7 @@ import { getCodexHome, resolveCodexStateDbPath } from "./paths";
  *
  * The SQLite root can differ from CODEX_HOME and both environment/config inputs
  * can change between invocations. The parent resolves one exact target and hands
- * those canonical paths to the Worker rather than asking the Worker to infer a
+ * those resolved paths to the Worker rather than asking the Worker to infer a
  * possibly different environment.
  */
 export function resolveCodexHistoryJobTarget(): {
@@ -45,10 +45,10 @@ export function resolveCodexHistoryJobTarget(): {
   return {
     canonicalCodexHome: home,
     canonicalStateDbPath: stateDb,
-    // Derived by the provider's own rule rather than guessed: the manifest lives
-    // in the config directory under a hash of the state database, so a
-    // hand-built path would address a different file entirely.
-    canonicalBackupPath: historyBackupPathFor(stateDb),
+    // Resolve through the provider's canonical-first compatibility rule. Passing
+    // only the newly normalized name would hide a pre-#4442 Windows manifest from
+    // the Worker and make an upgrade look like an empty backup.
+    canonicalBackupPath: resolveExistingHistoryBackupPath(stateDb),
   };
 }
 

package/src/codex/history-provider.ts

@@ -1,7 +1,8 @@
 import { createHash } from "node:crypto";
 import { closeSync, constants, existsSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, statSync, unlinkSync, writeSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
-import { zstdDecompressSync } from "node:zlib";
+import { parseSessionMetaLine, type ParsedSessionMeta } from "./history-rollout-read";
+export { MAX_ROLLOUT_ZST_DECOMPRESSED_BYTES, readThreadFieldsFromRollout, type RolloutThreadFields } from "./history-rollout-read";
 import { Database } from "bun:sqlite";
 import { resolveCodexStateDbPath } from "./paths";
 import { openCodexStateForPreflight } from "./history-state-open";
@@ -16,13 +17,6 @@ import {
   type CodexHistoryBackupManifest,
 } from "./history-manifest";
 
-/**
- * Cap for decompressing a lone `.jsonl.zst` rollout during quarantine restore.
- * Bounds peak memory while reconstructing thread rows; never write the decoded
- * JSONL to disk.
- */
-export const MAX_ROLLOUT_ZST_DECOMPRESSED_BYTES = 64 * 1024 * 1024;
-
 /**
  * The manifest that shadows one state database.
  *
@@ -441,18 +435,32 @@ export function preflightCodexHistoryInjection(
     const paginatedColumn = columns.some(column => column.name === "history_mode");
     if (paginatedColumn && restoreEntries.length > 0) return HISTORY_RELABEL_STANDS_DOWN;
     for (const entry of restoreEntries) assertLegacyHistoryWritable(entry.rolloutPath);
-    const rows = db.query<{ rollout_path: string; history_mode: string | null }, []>(`
-      SELECT rollout_path, ${paginatedColumn ? "history_mode" : "NULL AS history_mode"}
+    const rows = db.query<{ rollout_path: string; history_mode: string | null; model_provider: string }, []>(`
+      SELECT rollout_path, ${paginatedColumn ? "history_mode" : "NULL AS history_mode"}, model_provider
       FROM threads
       WHERE ${providerTableMode
         ? resumeHistory ? "model_provider IN ('openai', 'opencodex')" : "0"
         : "model_provider = 'opencodex'"}
     `).all();
+    // No ORDER BY: a paginated opencodex row can precede a paginated openai one, so the
+    // verdict waits for the full scan instead of standing down on the first paginated row.
+    let foundPaginatedRow = false;
+    let foundPaginatedOpenaiRow = false;
     for (const row of rows) {
-      if (paginatedColumn || row.history_mode === "paginated") return HISTORY_RELABEL_STANDS_DOWN;
+      if (paginatedColumn || row.history_mode === "paginated") {
+        foundPaginatedRow = true;
+        // A provider-table transition removes the root openai_base_url, and a row already
+        // paginated cannot be relabeled: standing it down would route the openai-tagged
+        // thread to Codex's built-in OpenAI endpoint. A still-legacy row only stands down.
+        if (providerTableMode && row.history_mode === "paginated" && row.model_provider === "openai") {
+          foundPaginatedOpenaiRow = true;
+        }
+        continue;
+      }
       assertLegacyHistoryWritable(row.rollout_path);
     }
-    return null;
+    if (foundPaginatedOpenaiRow) return "history_paginated_openai_requires_native_writer";
+    return foundPaginatedRow ? HISTORY_RELABEL_STANDS_DOWN : null;
   } catch (error) {
     return error instanceof CodexHistoryIntegrityError
       ? error.message
@@ -1021,24 +1029,6 @@ function assertRestoreReadback(
   }
 }
 
-interface ParsedSessionMeta {
-  record: { type?: unknown; timestamp?: unknown; payload: { model_provider?: unknown; source?: unknown } & Record<string, unknown> };
-}
-
-/** Parse one JSONL line into a `session_meta` record, or null if it isn't one. */
-function parseSessionMetaLine(line: string): ParsedSessionMeta | null {
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(line);
-  } catch {
-    return null;
-  }
-  if (!parsed || typeof parsed !== "object") return null;
-  const record = parsed as ParsedSessionMeta["record"];
-  if (record.type !== "session_meta" || !record.payload || typeof record.payload !== "object") return null;
-  return { record };
-}
-
 /**
  * Find the LAST `session_meta` line in a rollout, mirroring the app's last-writer-wins fold
  * (codex-rs `apply_session_meta_from_item`). We base our patch on the most recent metadata so we
@@ -1107,142 +1097,6 @@ function compensateConcurrentSessionMetaAppend(
   }
 }
 
-/**
- * Fields needed to re-insert a production-shaped `threads` row from a rollout JSONL when a
- * Phase-2 quarantine predates full `satellite-backup.json` thread snapshots.
- *
- * Uses the same last-writer-wins `session_meta` fold as {@link readLatestSessionMeta}, plus the
- * first user-message preview (codex-rs `list.rs` / `EventMsg::UserMessage` path).
- */
-export interface RolloutThreadFields {
-  id: string;
-  modelProvider: string;
-  source: string;
-  firstUserMessage: string;
-  hasUserEvent: number;
-  cwd?: string;
-  historyMode?: string;
-  cliVersion?: string;
-}
-
-function textFromContentParts(content: unknown): string | null {
-  if (typeof content === "string" && content.trim()) return content.trim();
-  if (!Array.isArray(content)) return null;
-  const parts: string[] = [];
-  for (const part of content) {
-    if (!part || typeof part !== "object") continue;
-    const p = part as Record<string, unknown>;
-    if (typeof p.text === "string" && p.text.trim()) parts.push(p.text.trim());
-    else if (typeof p.input_text === "string" && p.input_text.trim()) parts.push(p.input_text.trim());
-  }
-  const joined = parts.join("\n").trim();
-  return joined || null;
-}
-
-/** Extract the first user-message preview from a rollout line, or null. */
-function extractUserMessagePreview(line: string): string | null {
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(line);
-  } catch {
-    return null;
-  }
-  if (!parsed || typeof parsed !== "object") return null;
-  const record = parsed as { type?: unknown; payload?: unknown };
-  const payload = record.payload;
-  if (!payload || typeof payload !== "object") return null;
-  const p = payload as Record<string, unknown>;
-
-  if (record.type === "event_msg") {
-    // codex-rs EventMsg::UserMessage — payload.type is "user_message" (or omitted in fixtures).
-    if (p.type === "user_message" || typeof p.message === "string") {
-      if (typeof p.message === "string" && p.message.trim()) return p.message.trim();
-      const fromContent = textFromContentParts(p.content);
-      if (fromContent) return fromContent;
-    }
-    return null;
-  }
-
-  if (record.type === "response_item") {
-    if (p.type === "message" && p.role === "user") {
-      return textFromContentParts(p.content);
-    }
-  }
-  return null;
-}
-
-/**
- * Reconstruct thread identity + listing fields from a staged/restored rollout JSONL.
- * Returns null when the file is missing or has no parseable `session_meta`.
- *
- * Accepts plain `.jsonl` or a lone `.jsonl.zst` (legacy Phase-2 quarantine). Compressed
- * rollouts are decompressed in memory with {@link MAX_ROLLOUT_ZST_DECOMPRESSED_BYTES};
- * no decompressed copy is written to disk.
- */
-export function readThreadFieldsFromRollout(path: string): RolloutThreadFields | null {
-  if (!path || !existsSync(path)) return null;
-  let raw: string;
-  try {
-    raw = path.endsWith(".zst")
-      ? decompressRolloutZstUtf8(path)
-      : readFileSync(path, "utf8");
-  } catch {
-    return null;
-  }
-  return parseThreadFieldsFromRolloutText(raw);
-}
-
-function decompressRolloutZstUtf8(
-  path: string,
-  maxBytes: number = MAX_ROLLOUT_ZST_DECOMPRESSED_BYTES,
-): string {
-  const compressed = readFileSync(path);
-  const decoded = zstdDecompressSync(compressed as Uint8Array<ArrayBuffer>, {
-    maxOutputLength: maxBytes,
-  });
-  if (decoded.byteLength > maxBytes) {
-    throw new Error("rollout_zst_too_large");
-  }
-  return new TextDecoder().decode(decoded);
-}
-
-function parseThreadFieldsFromRolloutText(raw: string): RolloutThreadFields | null {
-  const lines = raw.split("\n");
-  let latest: ParsedSessionMeta | null = null;
-  let firstUserMessage = "";
-  for (const line of lines) {
-    if (!line) continue;
-    if (line.includes("\"session_meta\"")) {
-      const meta = parseSessionMetaLine(line);
-      if (meta) latest = meta;
-    }
-    if (!firstUserMessage) {
-      const preview = extractUserMessagePreview(line);
-      if (preview) firstUserMessage = preview;
-    }
-  }
-  if (!latest) return null;
-  const payload = latest.record.payload;
-  const id = typeof payload.id === "string" ? payload.id : "";
-  if (!id) return null;
-  const modelProvider = typeof payload.model_provider === "string" && payload.model_provider
-    ? payload.model_provider
-    : "openai";
-  const source = typeof payload.source === "string" && payload.source
-    ? payload.source
-    : "cli";
-  return {
-    id,
-    modelProvider,
-    source,
-    firstUserMessage,
-    hasUserEvent: firstUserMessage.trim() ? 1 : 0,
-    ...(typeof payload.cwd === "string" ? { cwd: payload.cwd } : {}),
-    ...(typeof payload.history_mode === "string" ? { historyMode: payload.history_mode } : {}),
-    ...(typeof payload.cli_version === "string" ? { cliVersion: payload.cli_version } : {}),
-  };
-}
-
 /**
  * Make a thread's rollout reflect a provider/source change by APPENDING a new `session_meta` line,
  * rather than rewriting line 1. The appended line clones the latest metadata payload (so no field

package/src/codex/history-rollout-read.ts

@@ -0,0 +1,174 @@
+import { existsSync, readFileSync } from "node:fs";
+import { zstdDecompressSync } from "node:zlib";
+
+/**
+ * Reading side of Codex rollout JSONL files: the `session_meta` fold and the thread fields a
+ * quarantine restore reconstructs from a rollout.
+ *
+ * Split out of `history-provider.ts` when that file crossed the repository file-size ratchet at
+ * 2009 lines. The cut follows a real seam rather than a line count: everything here reads a
+ * rollout file and returns plain data, while the module it left keeps the database and manifest
+ * writes. Nothing here opens a database or touches a backup manifest.
+ *
+ * `history-provider.ts` re-exports the public names, so existing importers are unaffected.
+ */
+/**
+ * Cap for decompressing a lone `.jsonl.zst` rollout during quarantine restore.
+ * Bounds peak memory while reconstructing thread rows; never write the decoded
+ * JSONL to disk.
+ */
+export const MAX_ROLLOUT_ZST_DECOMPRESSED_BYTES = 64 * 1024 * 1024;
+
+export interface ParsedSessionMeta {
+  record: { type?: unknown; timestamp?: unknown; payload: { model_provider?: unknown; source?: unknown } & Record<string, unknown> };
+}
+
+/** Parse one JSONL line into a `session_meta` record, or null if it isn't one. */
+export function parseSessionMetaLine(line: string): ParsedSessionMeta | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(line);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== "object") return null;
+  const record = parsed as ParsedSessionMeta["record"];
+  if (record.type !== "session_meta" || !record.payload || typeof record.payload !== "object") return null;
+  return { record };
+}
+
+/**
+ * Fields needed to re-insert a production-shaped `threads` row from a rollout JSONL when a
+ * Phase-2 quarantine predates full `satellite-backup.json` thread snapshots.
+ *
+ * Uses the same last-writer-wins `session_meta` fold as {@link readLatestSessionMeta}, plus the
+ * first user-message preview (codex-rs `list.rs` / `EventMsg::UserMessage` path).
+ */
+export interface RolloutThreadFields {
+  id: string;
+  modelProvider: string;
+  source: string;
+  firstUserMessage: string;
+  hasUserEvent: number;
+  cwd?: string;
+  historyMode?: string;
+  cliVersion?: string;
+}
+
+function textFromContentParts(content: unknown): string | null {
+  if (typeof content === "string" && content.trim()) return content.trim();
+  if (!Array.isArray(content)) return null;
+  const parts: string[] = [];
+  for (const part of content) {
+    if (!part || typeof part !== "object") continue;
+    const p = part as Record<string, unknown>;
+    if (typeof p.text === "string" && p.text.trim()) parts.push(p.text.trim());
+    else if (typeof p.input_text === "string" && p.input_text.trim()) parts.push(p.input_text.trim());
+  }
+  const joined = parts.join("\n").trim();
+  return joined || null;
+}
+
+/** Extract the first user-message preview from a rollout line, or null. */
+function extractUserMessagePreview(line: string): string | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(line);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== "object") return null;
+  const record = parsed as { type?: unknown; payload?: unknown };
+  const payload = record.payload;
+  if (!payload || typeof payload !== "object") return null;
+  const p = payload as Record<string, unknown>;
+
+  if (record.type === "event_msg") {
+    // codex-rs EventMsg::UserMessage — payload.type is "user_message" (or omitted in fixtures).
+    if (p.type === "user_message" || typeof p.message === "string") {
+      if (typeof p.message === "string" && p.message.trim()) return p.message.trim();
+      const fromContent = textFromContentParts(p.content);
+      if (fromContent) return fromContent;
+    }
+    return null;
+  }
+
+  if (record.type === "response_item") {
+    if (p.type === "message" && p.role === "user") {
+      return textFromContentParts(p.content);
+    }
+  }
+  return null;
+}
+
+/**
+ * Reconstruct thread identity + listing fields from a staged/restored rollout JSONL.
+ * Returns null when the file is missing or has no parseable `session_meta`.
+ *
+ * Accepts plain `.jsonl` or a lone `.jsonl.zst` (legacy Phase-2 quarantine). Compressed
+ * rollouts are decompressed in memory with {@link MAX_ROLLOUT_ZST_DECOMPRESSED_BYTES};
+ * no decompressed copy is written to disk.
+ */
+export function readThreadFieldsFromRollout(path: string): RolloutThreadFields | null {
+  if (!path || !existsSync(path)) return null;
+  let raw: string;
+  try {
+    raw = path.endsWith(".zst")
+      ? decompressRolloutZstUtf8(path)
+      : readFileSync(path, "utf8");
+  } catch {
+    return null;
+  }
+  return parseThreadFieldsFromRolloutText(raw);
+}
+
+function decompressRolloutZstUtf8(
+  path: string,
+  maxBytes: number = MAX_ROLLOUT_ZST_DECOMPRESSED_BYTES,
+): string {
+  const compressed = readFileSync(path);
+  const decoded = zstdDecompressSync(compressed as Uint8Array<ArrayBuffer>, {
+    maxOutputLength: maxBytes,
+  });
+  if (decoded.byteLength > maxBytes) {
+    throw new Error("rollout_zst_too_large");
+  }
+  return new TextDecoder().decode(decoded);
+}
+
+function parseThreadFieldsFromRolloutText(raw: string): RolloutThreadFields | null {
+  const lines = raw.split("\n");
+  let latest: ParsedSessionMeta | null = null;
+  let firstUserMessage = "";
+  for (const line of lines) {
+    if (!line) continue;
+    if (line.includes("\"session_meta\"")) {
+      const meta = parseSessionMetaLine(line);
+      if (meta) latest = meta;
+    }
+    if (!firstUserMessage) {
+      const preview = extractUserMessagePreview(line);
+      if (preview) firstUserMessage = preview;
+    }
+  }
+  if (!latest) return null;
+  const payload = latest.record.payload;
+  const id = typeof payload.id === "string" ? payload.id : "";
+  if (!id) return null;
+  const modelProvider = typeof payload.model_provider === "string" && payload.model_provider
+    ? payload.model_provider
+    : "openai";
+  const source = typeof payload.source === "string" && payload.source
+    ? payload.source
+    : "cli";
+  return {
+    id,
+    modelProvider,
+    source,
+    firstUserMessage,
+    hasUserEvent: firstUserMessage.trim() ? 1 : 0,
+    ...(typeof payload.cwd === "string" ? { cwd: payload.cwd } : {}),
+    ...(typeof payload.history_mode === "string" ? { historyMode: payload.history_mode } : {}),
+    ...(typeof payload.cli_version === "string" ? { cliVersion: payload.cli_version } : {}),
+  };
+}

package/src/codex/internal/catalog-writer.ts

@@ -1,4 +1,4 @@
-import { chmodSync, linkSync, mkdirSync, truncateSync, unlinkSync, writeFileSync } from "node:fs";
+import { chmodSync, linkSync, mkdirSync, readFileSync, truncateSync, unlinkSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 
 import {
@@ -37,6 +37,38 @@ export interface CatalogBackupWriteIO {
 
 let backupTempSequence = 0;
 
+/**
+ * Do the prepared bytes differ from what is already on disk at `prepared.path`?
+ *
+ * The single no-op rule for both files the catalog layer owns — the active catalog
+ * and Codex's models cache — so the two writers cannot drift apart. Every
+ * mtime-keyed reader has to treat a rewrite as a change: the app-server staleness
+ * classifier (#857) compares a file's mtime against each running Codex's start
+ * time, so rewriting identical bytes marks every already-running Codex as stale
+ * even though nothing changed. #1459 established this rule for the catalog; the
+ * cache is the second writer that has to apply it, because
+ * `refreshCodexModelCatalog` reports `cacheSynced` straight into the startup
+ * warning in `handleStart`.
+ *
+ * Deliberately a Buffer rather than a decoded string: `readFileSync(path, "utf8")`
+ * substitutes U+FFFD for every invalid byte, so a file holding a raw 0x80 decodes
+ * equal to prepared content holding a legitimately encoded U+FFFD. Comparing
+ * decoded strings would then classify a malformed file as identical, skip the
+ * atomic repair write, and leave the corruption on disk.
+ *
+ * An unreadable or absent file reports "differs", so the caller performs the real
+ * write; that also converges a file that does not exist yet.
+ */
+export function preparedBytesDifferFromDisk(prepared: PreparedCatalogFileWrite): boolean {
+  let onDisk: Buffer;
+  try {
+    onDisk = readFileSync(prepared.path);
+  } catch {
+    return true;
+  }
+  return !onDisk.equals(Buffer.from(prepared.content, "utf8"));
+}
+
 function isMissingPathError(error: unknown): boolean {
   return (error as NodeJS.ErrnoException | undefined)?.code === "ENOENT";
 }

package/src/codex/model-cache.ts

@@ -71,6 +71,8 @@ function deleteCachedProvider(provider: string): number {
   cache.delete(provider);
   cacheBytes = Math.max(0, cacheBytes - entry.sizeBytes);
   if (oldestCachedProvider === provider) recomputeOldestCachedProvider();
+  // A removal changes this provider's content as surely as a publication does.
+  bumpProviderCacheRevision(provider);
   return entry.sizeBytes;
 }
 
@@ -177,6 +179,34 @@ export function isModelCacheGenerationCurrent(provider: string, generation: stri
   return generation === captureModelCacheGeneration(provider);
 }
 
+/**
+ * How many times this provider's cached content has actually changed.
+ *
+ * Deliberately separate from the generation. A generation revokes an in-flight discovery's right
+ * to publish, so it advances on an authority clear and must not be repurposed: moving it on a
+ * successful publication would cancel writes that are still legitimate. This counts accepted
+ * publications and removals instead, which is what a reader holding a derived roster needs to
+ * know, and it advances on exactly the event a generation does not: a discovery that succeeded
+ * and changed the rows.
+ *
+ * Reading is passive. An unseen provider reads as `0` rather than seeding an entry, so observing
+ * one cannot alter what a later capture or publication sees.
+ */
+const providerCacheRevisions = new Map<string, number>();
+let globalContentRevision = 0;
+
+function bumpProviderCacheRevision(provider: string): void {
+  providerCacheRevisions.set(provider, (providerCacheRevisions.get(provider) ?? 0) + 1);
+}
+
+export function observeModelCacheRevision(provider: string): string {
+  // The global term covers a clear that empties the map wholesale, which per-provider counters
+  // cannot express: without it, wiping every entry and republishing identical-looking rows would
+  // read as unchanged. It also survives pruning, so a retired provider cannot come back with a
+  // counter that matches a roster built before it left.
+  return `${globalContentRevision}:${providerCacheRevisions.get(provider) ?? 0}`;
+}
+
 /**
  * Store a live result unless the cache was cleared while that asynchronous discovery was running.
  * The optional generation keeps existing direct cache writers unchanged while discovery callers can
@@ -200,6 +230,8 @@ export function setCached(
     oldestCachedAt = now;
   }
   enforceAppOwnedMemoryBudget();
+  // Published and accepted, so anything derived from this provider's rows is now out of date.
+  bumpProviderCacheRevision(provider);
   return true;
 }
 
@@ -220,6 +252,11 @@ export function clearModelCache(
   } else {
     if (revokesInFlightDiscovery) globalCacheGeneration += 1;
     cache.clear();
+    // A wholesale clear changes every provider's content at once, and clearing the map means no
+    // per-provider counter can record it. Advancing the global term retires every derived roster
+    // and lets the per-provider entries be dropped without an ABA on the way back.
+    globalContentRevision += 1;
+    providerCacheRevisions.clear();
     cacheBytes = 0;
     oldestCachedProvider = undefined;
     oldestCachedAt = null;
@@ -237,6 +274,7 @@ export function reconcileModelCacheProviders(
   const removedProviders = new Set<string>();
   const trackedProviders = new Set([
     ...providerCacheGenerations.keys(),
+    ...providerCacheRevisions.keys(),
     ...failureAt.keys(),
     ...discoveryStatus.keys(),
     ...liveModelCounts.keys(),
@@ -247,6 +285,10 @@ export function reconcileModelCacheProviders(
     if (validProviders.has(provider)) continue;
     if (!revokedRemovedProviderAuthority) {
       globalCacheGeneration += 1;
+      // Advanced BEFORE any revision entry is dropped, so a provider that comes back cannot
+      // present the counter a roster was built against. Without this the delete below is an ABA:
+      // the entry returns at zero and an old stamp matches again.
+      globalContentRevision += 1;
       revokedRemovedProviderAuthority = true;
     }
     providerCacheGenerations.set(provider, (providerCacheGenerations.get(provider) ?? 0) + 1);
@@ -255,6 +297,11 @@ export function reconcileModelCacheProviders(
     failureAt.delete(provider);
     discoveryStatus.delete(provider);
     liveModelCounts.delete(provider);
+    // AFTER the cache deletion, which bumps this provider's revision and would otherwise recreate
+    // the entry we just removed. Dropped rather than left behind: a provider the configuration no
+    // longer has must not keep an entry alive for the life of the process merely because nothing
+    // cleared the whole cache. The global epoch advanced above, so the removal is not an ABA.
+    providerCacheRevisions.delete(provider);
     removedProviders.add(provider);
   }
   lastReconciledGeneration = generation;