@bitkyc08/opencodex 2.59.0 → 2.61.0-preview.20260922

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/inject/config-toml.ts

@@ -4,6 +4,7 @@ import { contextCompatibleBaseLine } from "../context-compat";
 import { resolveEffectiveProjectModelProvider } from "../project-config-warnings";
 import {
   OCX_SECTION_MARKER,
+  OCX_ROUTING_MARKER_LINE,
   REALTIME_WS_BASE_URL_KEY,
   isRootOpenaiBaseUrlLine,
   isRootRealtimeWsBaseUrlLine,
@@ -128,7 +129,7 @@ export function buildProviderTableBlockForTarget(
 ): string {
   const lines = [
     "",
-    OCX_SECTION_MARKER,
+    OCX_ROUTING_MARKER_LINE,
     "[model_providers.opencodex]",
     `name = ${tomlString(resolveCodexProviderDisplayName(displayName))}`,
     `base_url = ${tomlString(target.baseUrl)}`,
@@ -213,6 +214,9 @@ export function setRootOpenaiBaseUrl(
     if (!isRootOpenaiBaseUrlLine(lines[i])) continue;
     const markerOwned = i > 0 && lines[i - 1].includes(OCX_SECTION_MARKER);
     if (!markerOwned) return { content, keptUserBaseUrl: true };
+    // Refresh the marker too, so a config injected by a build that predates the recovery
+    // hint gains it on the next `ocx start` instead of keeping a bare marker forever.
+    lines[i - 1] = OCX_ROUTING_MARKER_LINE;
     lines[i] = key;
     return { content: lines.join("\n"), keptUserBaseUrl: false };
   }
@@ -222,7 +226,7 @@ export function setRootOpenaiBaseUrl(
       content:
         content.replace(/\n+$/, "") +
         "\n" +
-        OCX_SECTION_MARKER +
+        OCX_ROUTING_MARKER_LINE +
         "\n" +
         key +
         "\n",
@@ -231,7 +235,7 @@ export function setRootOpenaiBaseUrl(
   }
   let insertAt = firstTable;
   while (insertAt > 0 && lines[insertAt - 1].trim() === "") insertAt--;
-  lines.splice(insertAt, 0, OCX_SECTION_MARKER, key);
+  lines.splice(insertAt, 0, OCX_ROUTING_MARKER_LINE, key);
   return { content: lines.join("\n"), keptUserBaseUrl: false };
 }
 
@@ -247,18 +251,19 @@ export function setRootOpenaiBaseUrlForTarget(
     if (!isRootOpenaiBaseUrlLine(lines[index])) continue;
     const markerOwned = index > 0 && lines[index - 1].includes(OCX_SECTION_MARKER);
     if (!markerOwned) return { content, keptUserBaseUrl: true };
+    lines[index - 1] = OCX_ROUTING_MARKER_LINE;
     lines[index] = key;
     return { content: lines.join("\n"), keptUserBaseUrl: false };
   }
   if (firstTable === -1) {
     return {
-      content: `${content.replace(/\n+$/, "")}\n${OCX_SECTION_MARKER}\n${key}\n`,
+      content: `${content.replace(/\n+$/, "")}\n${OCX_ROUTING_MARKER_LINE}\n${key}\n`,
       keptUserBaseUrl: false,
     };
   }
   let insertAt = firstTable;
   while (insertAt > 0 && lines[insertAt - 1].trim() === "") insertAt -= 1;
-  lines.splice(insertAt, 0, OCX_SECTION_MARKER, key);
+  lines.splice(insertAt, 0, OCX_ROUTING_MARKER_LINE, key);
   return { content: lines.join("\n"), keptUserBaseUrl: false };
 }
 
@@ -284,13 +289,14 @@ export function setRootRealtimeWsBaseUrl(
     if (!isRootRealtimeWsBaseUrlLine(lines[index])) continue;
     const markerOwned = index > 0 && lines[index - 1].includes(OCX_SECTION_MARKER);
     if (!markerOwned) return { content, keptUserRealtimeWsBaseUrl: true };
+    lines[index - 1] = OCX_ROUTING_MARKER_LINE;
     lines[index] = key;
     return { content: lines.join("\n"), keptUserRealtimeWsBaseUrl: false };
   }
   for (let index = 0; index < rootEnd; index += 1) {
     if (!isRootOpenaiBaseUrlLine(lines[index])) continue;
     if (!(index > 0 && lines[index - 1].includes(OCX_SECTION_MARKER))) continue;
-    lines.splice(index + 1, 0, OCX_SECTION_MARKER, key);
+    lines.splice(index + 1, 0, OCX_ROUTING_MARKER_LINE, key);
     return { content: lines.join("\n"), keptUserRealtimeWsBaseUrl: false };
   }
   // No marker-owned routing override to attach to: the override has no owner, so inject nothing.
@@ -603,3 +609,32 @@ export function chooseCatalogPathForInjection(
 
   return existsSync(DEFAULT_CATALOG_PATH) ? DEFAULT_CATALOG_PATH : null;
 }
+
+/**
+ * The effective `model_catalog_json` is one of ours and the file is gone.
+ *
+ * Codex does not degrade on this: a catalog path it cannot read stops it loading its
+ * configuration at all, which looks exactly like the routing lockout in #5261 and is what the
+ * reporter's machine was left in after the catalog file was deleted by hand.
+ *
+ * Injection already repairs it — the chooser refuses a missing owned path and the caller strips
+ * the stale line. That only helps someone who runs opencodex again, and the whole difficulty of
+ * this state is that Codex is the thing that stopped working, so nothing prompts them to. This
+ * predicate exists so the CLI can say it out loud.
+ *
+ * A user-owned catalog assignment wins here exactly as it does during injection: if they named
+ * the file, its absence is theirs to explain, and we do not claim it.
+ *
+ * Ownership is decided by basename, which is a weak test — a file the user happens to name
+ * `opencodex-catalog.json` is read as ours wherever it sits. That is deliberate rather than
+ * overlooked: it is the same test injection already applies, and a detector that drew the line
+ * somewhere else would report a state injection would then treat differently. Tightening it is a
+ * change to injection, not to this.
+ */
+export function missingOwnedCatalogPath(content: string): string | null {
+  const existing = readRootModelCatalogPath(content);
+  if (!existing) return null;
+  const resolved = resolveCodexConfigPath(existing);
+  if (!isOpencodexCatalogPath(resolved)) return null;
+  return existsSync(resolved) ? null : existing;
+}

package/src/codex/inject/paginated-openai-compat.ts

@@ -0,0 +1,90 @@
+/**
+ * The way forward for a provider-table transition that finds an `openai`-tagged row
+ * Codex has already migrated to paginated history.
+ *
+ * The refusal this resolves is correct about the danger and wrong about the remedy.
+ * A provider-table transition takes the root `openai_base_url` out, and a paginated row
+ * cannot be relabeled, so the transition as planned would send that conversation to
+ * Codex's built-in OpenAI endpoint. Refusing to relabel is right. Refusing the whole
+ * transition left #5321's reporter with 173 conversations and two unsupported exits:
+ * delete them, or downgrade.
+ *
+ * There is a third state, and the injector already builds it for the client-compaction
+ * form: keep the marker-owned root override beside the provider table. Codex merges the
+ * override onto its built-in `openai` entry when it builds the provider map, so the
+ * paginated row keeps reaching this proxy while never being rewritten. The transition
+ * completes, the relabel stands down, and no rollout byte or thread row is touched.
+ *
+ * Two cases cannot reach that state. An admission-token form cannot use the root key at
+ * all, because Codex's built-in `openai` entry carries no `x-opencodex-api-key` header;
+ * that one keeps the refusal and names what the operator can actually do. A root line the
+ * user owns is left alone, and the conversation follows their configuration rather than
+ * this proxy — the same guarantee the injector already makes everywhere else about a line
+ * it does not own.
+ */
+import { HISTORY_PAGINATED_OPENAI_NEEDS_ROOT_OVERRIDE, HISTORY_RELABEL_STANDS_DOWN } from "../history-provider";
+import { applyEol, setRootOpenaiBaseUrlForTarget, stripInjectedOpenaiBaseUrl } from "./config-toml";
+import type { CodexRoutingTarget } from "./routing-target";
+
+export interface PaginatedOpenaiCompatDecision {
+  /** The refusal that survives. `null` only when the preflight raised none. */
+  readonly refusal: string | null;
+  /** Candidate config bytes, carrying the retained root override when one was written. */
+  readonly content: string;
+  /** True only when OpenCodex wrote the retained line and must journal it as its own. */
+  readonly retainedRootOverride: boolean;
+  /** What the caller reports when `refusal` is not the stand-down reason. */
+  readonly message: string;
+}
+
+function genericRefusal(refusal: string): string {
+  return `Codex config injection refused: ${refusal}. `
+    + "Existing provider definitions and conversation files were preserved. "
+    + "Paginated history requires native-writer coordination; do not run legacy recovery or retry this transition blindly.";
+}
+
+/**
+ * Named next actions, because "do not retry" is what trapped the reporter. Both are
+ * configuration the operator already owns: the loopback listener is what makes the root
+ * override usable, and `syncResumeHistory` is the existing opt-out from history remapping.
+ */
+function admissionTokenRefusal(): string {
+  return `Codex config injection refused: ${HISTORY_PAGINATED_OPENAI_NEEDS_ROOT_OVERRIDE}. `
+    + "Existing provider definitions and conversation files were preserved. "
+    + "This home has conversations tagged openai whose history Codex has already migrated to its paginated "
+    + "format, and they cannot be relabeled. Keeping them on this proxy needs a root openai_base_url override, "
+    + "which this routing form cannot use: Codex's built-in openai provider carries no x-opencodex-api-key header. "
+    + "To complete the transition, either route Codex through the loopback listener "
+    + "(unauthenticatedLoopbackListener.enabled, or a loopback hostname) so the override can be retained, "
+    + "or set syncResumeHistory to false to accept that those conversations resume against Codex's own OpenAI endpoint.";
+}
+
+/**
+ * Resolve the transition, retaining the root override when this routing form can own one.
+ *
+ * `content` is the fully assembled provider-table candidate: OpenCodex's own root override
+ * has already been stripped and not re-added, so a root `openai_base_url` still present in it
+ * belongs to the user.
+ */
+export function applyPaginatedOpenaiCompat(
+  refusal: string | null,
+  target: CodexRoutingTarget,
+  content: string,
+  eol: "\r\n" | "\n",
+): PaginatedOpenaiCompatDecision {
+  if (refusal !== HISTORY_PAGINATED_OPENAI_NEEDS_ROOT_OVERRIDE) {
+    return { refusal, content, retainedRootOverride: false, message: refusal ? genericRefusal(refusal) : "" };
+  }
+  if (target.requiresAdmissionToken === true) {
+    return { refusal, content, retainedRootOverride: false, message: admissionTokenRefusal() };
+  }
+  const written = setRootOpenaiBaseUrlForTarget(stripInjectedOpenaiBaseUrl(applyEol(content, "\n")), target);
+  // The relabel still stands down either way: the row stays tagged openai and paginated, and
+  // the caller uses this reason to skip the history unit rather than let it start and refuse.
+  return {
+    refusal: HISTORY_RELABEL_STANDS_DOWN,
+    content: written.keptUserBaseUrl ? content : applyEol(written.content, eol),
+    retainedRootOverride: !written.keptUserBaseUrl,
+    message: "",
+  };
+}

package/src/codex/inject.ts

@@ -41,6 +41,7 @@ import {
   writeJournal,
 } from "./journal";
 import { HISTORY_RELABEL_STANDS_DOWN, preflightCodexHistoryInjection } from "./history-provider";
+import { applyPaginatedOpenaiCompat } from "./inject/paginated-openai-compat";
 import {
   describeHistoryJobFailure,
   deriveCodexHistoryOperation,
@@ -347,12 +348,13 @@ async function injectCodexConfigImpl(
   // first-line repair cannot grow "openai" into "opencodex" without pre-existing padding, and
   // codex re-appends that stale first line whenever it writes git or memory-mode metadata.
   //
-  // Authless is excluded on purpose: its whole point is a provider that carries
-  // requires_openai_auth = false, and admission-token forms cannot use the root key at all.
-  // Those two forms therefore keep their existing behaviour, forward-tagging resume history with
-  // originals backed up, and that includes the case where a user enables authless and client
-  // compaction together. Only the compaction-only form skips the history unit.
-  const keepRootOverrideAlongsideTable = providerTableMode
+  // Authless is excluded here on purpose: its whole point is a provider that carries
+  // requires_openai_auth = false, so it forward-tags resume history with originals backed up
+  // instead, and that includes the case where a user enables authless and client compaction
+  // together. Only the compaction-only form skips the history unit up front. When forward
+  // tagging turns out to be impossible because Codex already paginated those rows, the same
+  // retention is selected below from the preflight verdict rather than from the routing form.
+  let keepRootOverrideAlongsideTable = providerTableMode
     && routingTarget.clientCompaction === true
     && routingTarget.desktopAuthless !== true
     && routingTarget.requiresAdmissionToken !== true;
@@ -472,14 +474,15 @@ async function injectCodexConfigImpl(
     if (observed && observed !== HISTORY_RELABEL_STANDS_DOWN) throw new CodexHistoryPreflightRefusal(observed);
     return observed;
   };
-  const observedHistoryRefusal = historyPreflight();
+  const compat = applyPaginatedOpenaiCompat(historyPreflight(), routingTarget, content, eol);
+  content = compat.content;
+  keepRootOverrideAlongsideTable ||= compat.retainedRootOverride;
+  const observedHistoryRefusal = compat.refusal;
   if (observedHistoryRefusal && observedHistoryRefusal !== HISTORY_RELABEL_STANDS_DOWN) {
     return {
       success: false,
       historyPreflightFailureReason: observedHistoryRefusal,
-      message: `Codex config injection refused: ${observedHistoryRefusal}. `
-        + "Existing provider definitions and conversation files were preserved. "
-        + "Paginated history requires native-writer coordination; do not run legacy recovery or retry this transition blindly.",
+      message: compat.message,
     };
   }
   let historyRelabelRefusal = observedHistoryRefusal;
@@ -607,11 +610,11 @@ async function injectCodexConfigImpl(
     atomicWriteFile(CODEX_PROFILE_PATH, profileContent);
     markJournalInjectedState(content, profileContent, {
       // A root override is ours whenever we wrote one and no user-owned value won. That is
-      // loopback Design B, and now also the client-compaction form, which keeps the same
-      // marker-owned root line beside its provider table. Journaling it matters because the
-      // marker comment is not durable: the Codex app can reserialize config.toml and drop
-      // comments, and restore then has only the journaled value to tell our line from a user's
-      // (#1798). The other table forms never write the key, so they still record null.
+      // loopback Design B, the client-compaction form, and any table form that retained the
+      // root line for a paginated openai row, all of which keep the marker-owned line beside
+      // the table. Journaling it matters because the marker comment is not durable: the Codex
+      // app can reserialize config.toml and drop comments, and restore then has only the
+      // journaled value to tell our line from a user's (#1798). Other table forms record null.
       injectedOpenaiBaseUrl: (providerTableMode && !keepRootOverrideAlongsideTable) || keptUserBaseUrl
         ? null
         : rootTomlString(content, "openai_base_url"),

package/src/codex/injected-marker.ts

@@ -11,6 +11,24 @@ import { parseTomlString } from "./paths";
 
 export const OCX_SECTION_MARKER = "# Auto-injected by opencodex";
 
+/**
+ * The marker line actually written above ROUTING keys, carrying the command that undoes them.
+ *
+ * #5261: a Windows user whose proxy had stopped was locked out of Codex sign-in, because the
+ * root `openai_base_url` we write keeps pointing Codex's built-in openai provider at a port
+ * nothing is listening on. The only surface such a user can still read is `config.toml` itself,
+ * and it said nothing but "Auto-injected by opencodex" — so the recovery they found was to
+ * hand-delete lines and the catalog file, which is strictly worse than `ocx restore`.
+ *
+ * Every ownership predicate below matches on {@link OCX_SECTION_MARKER} as a SUBSTRING, never by
+ * equality, so this longer line is recognized by them and by any opencodex old enough to predate
+ * it. That is the whole reason the hint is appended to the marker instead of occupying a line of
+ * its own: a separate comment line would survive removal as orphaned text.
+ *
+ * Scope is routing only. Prompt layers keep the bare marker: `ocx restore` is not their undo.
+ */
+export const OCX_ROUTING_MARKER_LINE = `${OCX_SECTION_MARKER} (undo: ocx restore)`;
+
 export function isRootOpenaiBaseUrlLine(line: string): boolean {
   return /^\s*openai_base_url\s*=/.test(line);
 }

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/main-account.ts

@@ -404,6 +404,12 @@ async function resolveMainAccountToken(
             : "transient" as const;
           throw new MainAccountTokenRefreshError(reason, { cause });
         }
+        // The refresh may resolve after the caller went away (an implementation that does
+        // not observe the signal, or an abort landing in the window between resolution and
+        // commit). A cancelled request's late refresh must not rewrite auth.json on behalf
+        // of a request that no longer exists -- the same fence the reauth twin applies
+        // before its own commit above.
+        if (dependencies.signal?.aborted) throw dependencies.signal.reason;
         const result = persistRefreshedMainAuthJson(locked, refreshed);
         if (dependencies.preserveReauth !== true) clearAccountNeedsReauth(MAIN_CODEX_ACCOUNT_ID);
         return result;