@bitkyc08/opencodex 2.57.0 → 2.59.0

package/src/codex/history-job.ts

@@ -23,7 +23,7 @@ import type {
   CodexHistoryWorkerOperation,
   HistoryWorkerResult,
 } from "./history-worker";
-import { historyBackupPathFor } from "./history-provider";
+import { currentHistoryDbBusyTimeoutMs, historyBackupPathFor } from "./history-provider";
 import type { CodexHistoryFailureReason, CodexHistoryVerifiedNoopProof } from "./history-provider";
 import { getCodexHome, resolveCodexStateDbPath } from "./paths";
 
@@ -437,6 +437,10 @@ export async function runCodexHistoryJob(
       canonicalStateDbPath: request.canonicalStateDbPath,
       canonicalBackupPath: request.canonicalBackupPath,
       ...(request.expectedDesiredEnabled === undefined ? {} : { expectedDesiredEnabled: request.expectedDesiredEnabled }),
+      // A Worker is a fresh module realm: it would otherwise open state_5.sqlite with this
+      // module's default rather than the timeout this process resolved. Production sends the
+      // same codex-rs-matching 5s the Worker would have used on its own.
+      busyTimeoutMs: currentHistoryDbBusyTimeoutMs(),
       env: {
         ...(process.env.CODEX_HOME ? { CODEX_HOME: process.env.CODEX_HOME } : {}),
         ...(process.env.OPENCODEX_HOME ? { OPENCODEX_HOME: process.env.OPENCODEX_HOME } : {}),

package/src/codex/history-provider.ts

@@ -4,6 +4,7 @@ import { dirname, join, resolve } from "node:path";
 import { zstdDecompressSync } from "node:zlib";
 import { Database } from "bun:sqlite";
 import { resolveCodexStateDbPath } from "./paths";
+import { openCodexStateForPreflight } from "./history-state-open";
 import { atomicWriteFile, getConfigDir } from "../config";
 import {
   CODEX_HISTORY_RESUMABLE_SOURCES,
@@ -76,6 +77,22 @@ export function setHistoryDbBusyTimeoutForTests(ms: number): void {
   historyDbBusyTimeoutMs = ms;
 }
 
+/**
+ * Carry that timeout across a realm boundary. A Worker starts from the default above and cannot
+ * observe a parent that shortened the window — the same reason its run message carries the homes
+ * explicitly — so `history-job.ts` sends this value and `history-worker.ts` adopts it. In
+ * production both sides already hold the codex-rs-matching 5s. A non-finite or negative value is
+ * refused rather than allowed to disable the wait the app expects.
+ */
+export function currentHistoryDbBusyTimeoutMs(): number {
+  return historyDbBusyTimeoutMs;
+}
+
+export function adoptHistoryDbBusyTimeout(ms: number): void {
+  if (!Number.isFinite(ms) || ms < 0) return;
+  historyDbBusyTimeoutMs = Math.floor(ms);
+}
+
 function openStateDb(stateDbPath: string): Database {
   const db = new Database(stateDbPath);
   try {
@@ -311,6 +328,19 @@ class CodexHistoryIntegrityError extends Error {
  * O_APPEND does not allocate an ordinal or update that writer's in-memory cursor.
  * Refuse before changing the DB, manifest, or first-line provider; never guess N+1.
  */
+/**
+ * The one refusal reason that means "the native writer owns this history", as opposed
+ * to "something is wrong". It is a stand-down for the relabel unit on apply
+ * (`src/codex/inject.ts`) and for the history half of a restore; every other reason is
+ * a hard refusal in both directions.
+ *
+ * Exported as a constant rather than repeated as a literal because the apply and restore
+ * directions have to agree on it exactly. They drifted once already: apply learned to
+ * stand down while restore kept refusing, which is how #4812's uninstall deadlock
+ * survived the fix that was supposed to end it.
+ */
+export const HISTORY_RELABEL_STANDS_DOWN = "history_paginated_requires_native_writer";
+
 function assertLegacyHistoryRecord(line: string): void {
   let value: unknown;
   try { value = JSON.parse(line); } catch { throw new CodexHistoryIntegrityError("history_rollout_record_invalid"); }
@@ -320,7 +350,7 @@ function assertLegacyHistoryRecord(line: string): void {
   const record = value as Record<string, unknown>;
   const payload = record.payload;
   if (Object.hasOwn(record, "ordinal") || (payload !== null && typeof payload === "object" && (payload as Record<string, unknown>).history_mode === "paginated")) {
-    throw new CodexHistoryIntegrityError("history_paginated_requires_native_writer");
+    throw new CodexHistoryIntegrityError(HISTORY_RELABEL_STANDS_DOWN);
   }
 }
 
@@ -381,7 +411,7 @@ function assertLegacyHistoryWritable(path: string, heldFd?: number): void {
 function assertLegacyHistoryStore(db: Database): void {
   const columns = db.query<{ name: string }, []>("PRAGMA table_info(threads)").all();
   if (columns.some(column => column.name === "history_mode")) {
-    throw new CodexHistoryIntegrityError("history_paginated_requires_native_writer");
+    throw new CodexHistoryIntegrityError(HISTORY_RELABEL_STANDS_DOWN);
   }
 }
 
@@ -404,10 +434,12 @@ export function preflightCodexHistoryInjection(
     if (!existsSync(resolvedPath)) {
       return restoreEntries.length > 0 ? "history_state_database_missing" : null;
     }
-    db = new Database(resolvedPath, { readonly: true });
+    // Read-only, and narrowed so a cleanly-closed WAL store is inspected rather than refused
+    // (#4943). The open order is the safety property; see history-state-open.ts.
+    db = openCodexStateForPreflight(resolvedPath);
     const columns = db.query<{ name: string }, []>("PRAGMA table_info(threads)").all();
     const paginatedColumn = columns.some(column => column.name === "history_mode");
-    if (paginatedColumn && restoreEntries.length > 0) return "history_paginated_requires_native_writer";
+    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"}
@@ -417,7 +449,7 @@ export function preflightCodexHistoryInjection(
         : "model_provider = 'opencodex'"}
     `).all();
     for (const row of rows) {
-      if (paginatedColumn || row.history_mode === "paginated") return "history_paginated_requires_native_writer";
+      if (paginatedColumn || row.history_mode === "paginated") return HISTORY_RELABEL_STANDS_DOWN;
       assertLegacyHistoryWritable(row.rollout_path);
     }
     return null;

package/src/codex/history-state-open.ts

@@ -0,0 +1,105 @@
+/**
+ * How the read-only Codex history preflight opens the state store.
+ *
+ * Split out of `history-provider.ts` deliberately. That file is the single largest module in
+ * `src/codex/` and sits just under the repository's 2000-line ratchet; the reasoning below is
+ * load-bearing and long, and appending it there would have pushed the file over. Keeping the
+ * open policy in one small module also puts the decision somewhere it can be read on its own,
+ * which matters because getting it wrong is silent in both directions.
+ */
+import { existsSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+import { Database, constants as sqliteConstants } from "bun:sqlite";
+
+/**
+ * Read-only open flags that skip WAL shared memory entirely.
+ *
+ * `immutable=1` has to arrive as a `file:` URI, and a URI filename needs SQLITE_OPEN_URI.
+ * Same idiom as the storage scanner, the log-guard inspector and the coordinator doctor, for
+ * the same reason: never touch a foreign store's WAL protocol.
+ */
+const IMMUTABLE_READONLY_FLAGS = sqliteConstants.SQLITE_OPEN_READONLY | sqliteConstants.SQLITE_OPEN_URI;
+
+/** Is this the "there is no shared memory and I may not create it" open failure? */
+export function isStateDbCantOpenError(error: unknown): boolean {
+  const code = typeof error === "object" && error && "code" in error ? String((error as { code?: unknown }).code) : "";
+  const message = error instanceof Error ? error.message.toLowerCase() : String(error).toLowerCase();
+  // Matched on the code with a message fallback, exactly like classifyRecoverableHistoryError:
+  // the same SQLite condition reaches us as a code on some platforms and as bare text on others.
+  return code === "SQLITE_CANTOPEN" || message.includes("unable to open database file");
+}
+
+/** Which step of the primary attempt a test wants to fail. */
+export type StateDbPreflightOpenPhase = "open" | "first-read";
+
+/**
+ * Test-only knob: force the primary attempt to fail with a supplied error.
+ *
+ * The fallback below turns on a condition this repository cannot reproduce deterministically
+ * from a test: whether a plain read-only open of a cleanly-closed WAL store fails or quietly
+ * creates the `-shm` depends on the platform VFS and on the directory the store sits in.
+ * Pinning the NARROWING — sidecars absent admits the immutable read, either sidecar present
+ * still refuses — therefore needs the failure supplied rather than provoked, or the test would
+ * assert the host's SQLite build instead of this decision (#4943).
+ *
+ * The phase exists because the platforms disagree about WHEN the condition is raised, not only
+ * about whether it is: see the first-read note on `openCodexStateForPreflight`.
+ */
+let openFailureForTests: ((path: string, phase: StateDbPreflightOpenPhase) => unknown) | undefined;
+export function setStateDbPreflightOpenFailureForTests(hook: typeof openFailureForTests): void {
+  openFailureForTests = hook;
+}
+
+/**
+ * Open the Codex state store for the read-only preflight.
+ *
+ * `{ readonly: true }` is tried FIRST and stays the primary path, because it is the only mode
+ * that can see a live WAL: it joins the writer's shared memory, so a thread another process
+ * just migrated to paginated history is visible here and the preflight refuses on it. An
+ * immutable open reads the last checkpointed main database instead. Making that the primary
+ * path would trade a refusal for a stale snapshot, and a refusal this preflight fails to
+ * observe is a config transition that proceeds over history Codex owns — the exact outcome the
+ * whole guard exists to prevent.
+ *
+ * A WAL store closed cleanly is the case that has no shared memory to join. SQLite cannot
+ * create the `-shm` from a read-only connection, so the open fails SQLITE_CANTOPEN on a store
+ * that is perfectly healthy, the catch-all in the preflight folds that into
+ * `history_injection_preflight_unavailable`, and `ocx sync` refuses on every attempt with no
+ * way forward (#4943).
+ *
+ * So the fallback is admitted only in the state where the absent sidecars are what make an
+ * immutable read exact rather than stale: no `-wal` and no `-shm` on disk means no writer is
+ * attached and no committed content sits outside the main database, so the main file IS the
+ * whole store and the two modes cannot disagree. Either sidecar present keeps the original
+ * error and the refusal that follows from it — a `-wal` holds content this connection would
+ * not read, and a `-shm` means a writer is attached, and neither is a store this preflight
+ * may inspect from a snapshot.
+ *
+ * The first read belongs INSIDE this attempt. `sqlite3_open_v2` does not touch page 1, so a
+ * store whose header says WAL is not inspected until the first prepare — which is where the
+ * missing shared memory is discovered on macOS, one caller frame above this function. Opening
+ * here and reading there put the classification and the failure in different scopes: the
+ * fallback was never reached, and the operator got the catch-all refusal the fix was supposed
+ * to remove. Linux hides this because its SQLite materializes the sidecars on that first read
+ * and never fails at all (#4943, macOS CI).
+ */
+export function openCodexStateForPreflight(resolvedPath: string): Database {
+  let db: Database | undefined;
+  try {
+    const forced = openFailureForTests?.(resolvedPath, "open");
+    if (forced) throw forced;
+    db = new Database(resolvedPath, { readonly: true });
+    const forcedRead = openFailureForTests?.(resolvedPath, "first-read");
+    if (forcedRead) throw forcedRead;
+    // Page 1, read while the failure is still this function's to classify.
+    db.query<{ tables: number }, []>("SELECT count(*) AS tables FROM sqlite_master").get();
+    return db;
+  } catch (error) {
+    db?.close();
+    if (!isStateDbCantOpenError(error)) throw error;
+    if (existsSync(`${resolvedPath}-wal`) || existsSync(`${resolvedPath}-shm`)) throw error;
+    // pathToFileURL percent-encodes the reserved characters a naive `file:${path}` would
+    // misparse as a query or fragment.
+    return new Database(`${pathToFileURL(resolvedPath).href}?immutable=1`, IMMUTABLE_READONLY_FLAGS);
+  }
+}

package/src/codex/history-worker.ts

@@ -33,6 +33,7 @@ import {
 } from "./internal/history-writer";
 import {
   snapshotCodexHistoryNoop,
+  adoptHistoryDbBusyTimeout,
   type CodexHistoryFailureReason,
   type CodexHistoryVerifiedNoopProof,
 } from "./history-provider";
@@ -62,6 +63,11 @@ export interface HistoryWorkerRunMessage {
   readonly canonicalBackupPath: string;
   /** When set, prove this transition's desired direction while H is held. */
   readonly expectedDesiredEnabled?: boolean;
+  /**
+   * The parent realm's `state_5.sqlite` busy timeout. A Worker cannot observe a parent that
+   * resolved a different window, for the same reason the homes below are explicit.
+   */
+  readonly busyTimeoutMs?: number;
   /** Env snapshot: a Worker may not observe parent mutations on every platform. */
   readonly env?: { readonly CODEX_HOME?: string; readonly OPENCODEX_HOME?: string };
 }
@@ -107,7 +113,11 @@ export function isHistoryWorkerRunMessage(data: unknown): data is HistoryWorkerR
     && nonEmpty(message.canonicalCodexHome)
     && nonEmpty(message.canonicalStateDbPath)
     && nonEmpty(message.canonicalBackupPath)
-    && (message.expectedDesiredEnabled === undefined || typeof message.expectedDesiredEnabled === "boolean");
+    && (message.expectedDesiredEnabled === undefined || typeof message.expectedDesiredEnabled === "boolean")
+    && (message.busyTimeoutMs === undefined
+      || (typeof message.busyTimeoutMs === "number"
+        && Number.isFinite(message.busyTimeoutMs)
+        && message.busyTimeoutMs >= 0));
 }
 
 /**
@@ -207,6 +217,9 @@ if (typeof self !== "undefined" && typeof (self as { onmessage?: unknown }) ===
     try {
       if (message.env?.CODEX_HOME) process.env.CODEX_HOME = message.env.CODEX_HOME;
       if (message.env?.OPENCODEX_HOME) process.env.OPENCODEX_HOME = message.env.OPENCODEX_HOME;
+      // Before any DB open: the timeout has to be in force for the first `openStateDb`, not
+      // after the writer has already waited out this realm's default.
+      if (message.busyTimeoutMs !== undefined) adoptHistoryDbBusyTimeout(message.busyTimeoutMs);
       self.postMessage(runHistoryUnitUnderLock(message));
     } catch (error) {
       self.postMessage({

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

@@ -55,6 +55,46 @@ export function applyEol(content: string, eol: "\r\n" | "\n"): string {
   return eol === "\n" ? lf : lf.replace(/\n/g, "\r\n");
 }
 
+/** Label Codex shows for the injected provider when the operator has not chosen one. */
+export const DEFAULT_CODEX_PROVIDER_DISPLAY_NAME = "OpenCodex Proxy";
+
+/** Longest label accepted, matching the display-label policy used for provider names. */
+const MAX_CODEX_PROVIDER_DISPLAY_NAME_LENGTH = 128;
+
+/** Would this label put a control character into config.toml? */
+function hasControlCharacter(value: string): boolean {
+  // Checked by code point rather than by a control-character regex, which needs a lint
+  // suppression this repository's hygiene gate rejects — and which reads no more clearly.
+  for (const character of value) {
+    const code = character.codePointAt(0) ?? 0;
+    if (code < 0x20 || code === 0x7f) return true;
+  }
+  return false;
+}
+
+/**
+ * Which label to write, given whatever the config holds.
+ *
+ * Presentation only, and deliberately separate from identity: routing resolves through the
+ * provider id `opencodex` in the root `model_provider` line and the `[model_providers.opencodex]`
+ * header, neither of which is derived from this value. So a rename cannot reroute a thread or
+ * orphan a row that already names that id (#4810).
+ *
+ * Every rejected value falls back to the default rather than being emitted or omitted. Codex
+ * refuses to load a provider with no name, so writing a blank one would break the whole config
+ * file rather than one thread — strictly worse than the branding it was meant to remove. That is
+ * also why there is no way to suppress the field: suppression here means choosing a neutral
+ * label. A control character or an over-long value is rejected for the same reason, because
+ * `tomlString` would faithfully encode something Codex may still reject.
+ */
+export function resolveCodexProviderDisplayName(configured?: string): string {
+  const trimmed = (configured ?? "").trim();
+  if (!trimmed) return DEFAULT_CODEX_PROVIDER_DISPLAY_NAME;
+  if (trimmed.length > MAX_CODEX_PROVIDER_DISPLAY_NAME_LENGTH) return DEFAULT_CODEX_PROVIDER_DISPLAY_NAME;
+  if (hasControlCharacter(trimmed)) return DEFAULT_CODEX_PROVIDER_DISPLAY_NAME;
+  return trimmed;
+}
+
 export function buildProviderTableBlock(
   port: number,
   supportsWebsockets?: boolean,
@@ -84,12 +124,13 @@ export function buildProviderTableBlock(
 export function buildProviderTableBlockForTarget(
   target: CodexRoutingTarget,
   supportsWebsockets = false,
+  displayName?: string,
 ): string {
   const lines = [
     "",
     OCX_SECTION_MARKER,
     "[model_providers.opencodex]",
-    'name = "OpenCodex Proxy"',
+    `name = ${tomlString(resolveCodexProviderDisplayName(displayName))}`,
     `base_url = ${tomlString(target.baseUrl)}`,
     'wire_api = "responses"',
     // false only in the authless Desktop opt-in (#1107); true keeps the App/TUI account gate.
@@ -518,6 +559,7 @@ export function buildProfileFileForTarget(
   catalogPath?: string | null,
   supportsWebsockets = false,
   fastMode?: boolean,
+  displayName?: string,
 ): string {
   const origin = routingTargetOrigin(target);
   const host = new URL(origin).host;
@@ -542,7 +584,7 @@ export function buildProfileFileForTarget(
   ];
   if (catalogPath) lines.push(`model_catalog_json = ${tomlString(catalogPath)}`);
   if (fastMode !== undefined) lines.push("", "[features]", `fast_mode = ${fastMode ? "true" : "false"}`);
-  lines.push(buildProviderTableBlockForTarget(target, supportsWebsockets).trimEnd(), "");
+  lines.push(buildProviderTableBlockForTarget(target, supportsWebsockets, displayName).trimEnd(), "");
   return lines.join("\n");
 }
 

package/src/codex/inject/remove.ts

@@ -7,7 +7,7 @@ import {
   rootTomlString,
   stripJournaledOpenaiBaseUrl,
 } from "../injected-marker";
-import { preflightCodexHistoryInjection } from "../history-provider";
+import { HISTORY_RELABEL_STANDS_DOWN, preflightCodexHistoryInjection } from "../history-provider";
 import {
   journaledInjectedOpenaiBaseUrl,
   journaledInjectedRealtimeWsBaseUrl,
@@ -79,6 +79,90 @@ export function removeOcxSection(content: string): string {
   );
 }
 
+/**
+ * Capture `[model_providers.opencodex]` verbatim so it can survive a restore that only
+ * takes routing down (#4812).
+ *
+ * This is deliberately NOT a mirror of `removeOcxSection`'s scan. That one opens a
+ * section on any line containing `OCX_SECTION_MARKER`, which is safe there only because
+ * `stripInjectedOpenaiBaseUrl` has already consumed the identical marker that annotates
+ * the root `openai_base_url`. Capture runs against the untouched file, so the same rule
+ * would collect that marker and the routing line under it — and re-appending the result
+ * would restore the exact base-url override the caller just removed.
+ *
+ * So the anchor is the provider header itself, via the shared `isOcxProviderHeaderLine`,
+ * with an immediately preceding marker line pulled in as its comment. Sharing that
+ * predicate is what keeps capture and removal from disagreeing about what our table is.
+ */
+export function extractOcxProviderTableBlock(content: string): string | null {
+  const lines = content.split("\n");
+  const collected: string[] = [];
+  let capturing = false;
+  for (let index = 0; index < lines.length; index++) {
+    const line = lines[index]!;
+    if (isOcxProviderHeaderLine(line.trim())) {
+      if (!capturing) {
+        const previous = lines[index - 1];
+        if (previous !== undefined && previous.includes(OCX_SECTION_MARKER)) collected.push(previous);
+        capturing = true;
+      }
+      collected.push(line);
+      continue;
+    }
+    if (!capturing) continue;
+    // A foreign table header closes ours, exactly as in `removeOcxSection`. A later
+    // `[model_providers.opencodex.*]` sub-table reopens capture on the next iteration,
+    // which is why the two are separate passes over the same predicate.
+    if (/^\s*\[/.test(line)) {
+      capturing = false;
+      continue;
+    }
+    collected.push(line);
+  }
+  if (collected.length === 0) return null;
+  return collected.join("\n").replace(/\n{3,}/g, "\n\n").trimEnd() + "\n";
+}
+
+/**
+ * Append a captured provider table to stripped content, as one buffer.
+ *
+ * Pure on purpose. Upstream resolves `model_provider` against the merged provider map and
+ * fails the WHOLE config load on a miss — not the one thread — so a config carrying root
+ * `model_provider = "opencodex"` without this table breaks every `codex` invocation. The
+ * strip and the re-append therefore have to reach disk in a single write, which they can
+ * only do if the append is a transform rather than a second file operation.
+ */
+export function appendOcxProviderTableBlock(content: string, block: string): string {
+  if (hasOcxProviderTable(content)) return content;
+  return `${content.replace(/\n+$/, "")}\n\n${block.replace(/\n+$/, "")}\n`;
+}
+
+/** Read the provider table straight off disk, before anything has transformed it. */
+export function readOcxProviderTableBlock(): string | null {
+  if (!existsSync(CODEX_CONFIG_PATH)) return null;
+  return extractOcxProviderTableBlock(applyEol(readFileSync(CODEX_CONFIG_PATH, "utf-8"), "\n"));
+}
+
+/**
+ * Re-attach a captured provider table after an exact journal restore.
+ *
+ * This is the one place retention needs a second write, because the journal replays whole
+ * pre-injection bytes rather than transforming the current file. The intermediate state is
+ * the safe one: the journal's config is the user's own, so it carries no
+ * `model_provider = "opencodex"` for a missing table to strand. A crash between the two
+ * writes leaves a fully native config, which is the direction this whole change is trying
+ * to reach anyway.
+ */
+export function retainOcxProviderTableOnDisk(block: string): string[] | null {
+  if (!existsSync(CODEX_CONFIG_PATH)) return null;
+  const rawContent = readFileSync(CODEX_CONFIG_PATH, "utf-8");
+  const eol = dominantEol(rawContent);
+  const content = applyEol(rawContent, "\n");
+  const next = appendOcxProviderTableBlock(content, block);
+  if (next !== content) atomicWriteFile(CODEX_CONFIG_PATH, applyEol(next, eol));
+  return block.replace(/\n+$/, "").split("\n");
+}
+
 interface StripOpencodexConfigResult {
   content: string;
   managedDefaultsError: string | null;
@@ -139,11 +223,52 @@ function hasOpencodexRouting(content: string): boolean {
   );
 }
 
+/**
+ * What the caller already decided about conversation history before calling.
+ *
+ * - `refuse-on-any` — nothing was decided, so re-derive and refuse on any refusal reason.
+ *   This is the default, and it is what a direct caller gets.
+ * - `stand-down-retain` — a stand-down was accepted and `[model_providers.opencodex]` must
+ *   survive, because the rows this home tagged `opencodex` stay tagged and resolve only
+ *   through that table. Those conversations still open; their requests fail against a
+ *   stopped proxy, which is an ordinary connection error.
+ * - `stand-down-remove` — a stand-down was accepted and the user explicitly asked for the
+ *   table to go too, accepting that those conversations stop opening.
+ *
+ * One option rather than two booleans: retention and the refusal are the same decision seen
+ * from two sides, and splitting them is how the explicit-removal path ended up refused by a
+ * preflight its caller had already answered.
+ */
+export type RemoveCodexConfigHistoryDisposition =
+  | "refuse-on-any"
+  | "stand-down-retain"
+  | "stand-down-remove";
+
+export interface RemoveCodexConfigOptions {
+  preserveProfile?: boolean;
+  historyDisposition?: RemoveCodexConfigHistoryDisposition;
+}
+
+export interface RemoveCodexConfigResult {
+  success: boolean;
+  message: string;
+  /** The exact lines left on disk when the disposition was `stand-down-retain`. */
+  retainedProviderTable?: string[];
+}
+
 export function removeCodexConfig(
-  options: { preserveProfile?: boolean } = {},
-): { success: boolean; message: string } {
+  options: RemoveCodexConfigOptions = {},
+): RemoveCodexConfigResult {
+  const historyDisposition = options.historyDisposition ?? "refuse-on-any";
   const historyError = preflightCodexHistoryInjection(false, false);
-  if (historyError) return { success: false, message: `Codex configuration preserved: ${historyError}. Native writer coordination is required.` };
+  // The preflight answers "may I rewrite conversation history?". Routing removal is a
+  // different question, and treating one answer as both is what left `ocx uninstall`
+  // pointing a live config at a port it had just removed (#4812). Only the stand-down
+  // reason is separable; every other reason still means something is wrong with the
+  // history state itself, and those keep the hard refusal even for a caller that decided.
+  if (historyError && !(historyDisposition !== "refuse-on-any" && historyError === HISTORY_RELABEL_STANDS_DOWN)) {
+    return { success: false, message: `Codex configuration preserved: ${historyError}. Native writer coordination is required.` };
+  }
   if (!existsSync(CODEX_CONFIG_PATH)) {
     if (!options.preserveProfile && existsSync(CODEX_PROFILE_PATH))
       unlinkSync(CODEX_PROFILE_PATH);
@@ -166,13 +291,25 @@ export function removeCodexConfig(
     || (journaledRealtimeWsBaseUrl !== null
       && rootTomlString(content, REALTIME_WS_BASE_URL_KEY) === journaledRealtimeWsBaseUrl);
   const stripped = stripOpencodexConfigResult(content, journaledBaseUrl, journaledRealtimeWsBaseUrl);
-  if (had || stripped.content !== content) {
-    atomicWriteFile(CODEX_CONFIG_PATH, applyEol(stripped.content, eol));
+  // Captured from the pre-strip bytes: the strip is what removes the table, so reading it
+  // afterwards would find nothing.
+  const retainedBlock = historyDisposition === "stand-down-retain"
+    ? extractOcxProviderTableBlock(content)
+    : null;
+  const finalContent = retainedBlock === null
+    ? stripped.content
+    : appendOcxProviderTableBlock(stripped.content, retainedBlock);
+  if (had || finalContent !== content) {
+    atomicWriteFile(CODEX_CONFIG_PATH, applyEol(finalContent, eol));
   }
   if (!options.preserveProfile && existsSync(CODEX_PROFILE_PATH))
     unlinkSync(CODEX_PROFILE_PATH);
+  const retainedNote = retainedBlock === null
+    ? ""
+    : " Kept [model_providers.opencodex] so conversations already tagged opencodex still open;"
+      + " remove it with 'ocx restore --remove-codex-provider-table' (those conversations stop opening).";
   const removedMessage = had
-    ? `Removed opencodex routing from Codex config${options.preserveProfile ? "." : " + profile."}`
+    ? `Removed opencodex routing from Codex config${options.preserveProfile ? "." : " + profile."}${retainedNote}`
     : "opencodex not present in Codex config.";
   if (stripped.managedDefaultsError) {
     const routingMessage = had
@@ -188,5 +325,6 @@ export function removeCodexConfig(
   return {
     success: true,
     message: removedMessage,
+    ...(retainedBlock === null ? {} : { retainedProviderTable: retainedBlock.replace(/\n+$/, "").split("\n") }),
   };
 }