@bitkyc08/opencodex 2.57.0 → 2.58.0

package/src/cli/uninstall-client-state.ts

@@ -4,6 +4,7 @@ import { readClientConnectionState, sameClientConnectionOwner } from "../client/
 import { assertClientLifecycleHeld, withClientLifecycle } from "../client/lifecycle-lock";
 import { inspectRemoteDesktopCleanup, readDesktopDisconnectReceipt } from "../claude/desktop-remote-store";
 import { removeOwnedConfigState, type ConfigRemovalResult } from "../lib/config-ownership";
+import { windowsSecretAclReapPendingAtOrBelow } from "../lib/windows-secret-acl";
 import { sharedTeardownAuthorized, type UninstallObservation } from "./uninstall-plan";
 
 export interface UninstallClientStateDeps {
@@ -13,6 +14,8 @@ export interface UninstallClientStateDeps {
   disconnect: (options?: Parameters<typeof disconnectClient>[0]) => Promise<unknown>;
   withLifecycle: typeof withClientLifecycle;
   remove: () => ConfigRemovalResult;
+  /** True while a timed-out icacls child still owns a path at or below the config directory. */
+  aclReapPending: (rootPath: string) => boolean;
 }
 
 const defaults: UninstallClientStateDeps = {
@@ -22,6 +25,7 @@ const defaults: UninstallClientStateDeps = {
   disconnect: options => disconnectClient(options),
   withLifecycle: withClientLifecycle,
   remove: () => removeOwnedConfigState(getConfigDir()),
+  aclReapPending: rootPath => windowsSecretAclReapPendingAtOrBelow(rootPath),
 };
 
 /** Restore connection-owned client artifacts before removing their ownership/recovery records. */
@@ -73,6 +77,14 @@ export async function removeOwnedConfigAfterDesktopCleanup(
       || (latestReceipt.kind === "valid" && latestReceipt.value.phase !== "complete")) {
       throw new Error("Client cleanup refused: connection or Desktop state changed before removal.");
     }
+    // The async ACL belt releases its caller on a stalled `icacls.exe`, which is what keeps
+    // startup and shutdown bounded. It is not evidence that the child released the directory,
+    // and on Windows a live handle makes this removal fail partway instead of cleanly. Refuse
+    // promptly and let the operator retry: waiting here would hand a stuck child the power to
+    // hang `ocx uninstall`, which is the bound the belt exists to preserve.
+    if (deps.aclReapPending(getConfigDir())) {
+      throw new Error("Client cleanup refused: ACL hardening still owns a path under the config directory.");
+    }
     return deps.remove();
   });
 }

package/src/codex/auth-context.ts

@@ -96,6 +96,44 @@ function requestOwnedMainPinHasQuotaHeadroom(config: OcxConfig): boolean {
   return usage >= CODEX_UNKNOWN_USAGE_SCORE || usage < threshold;
 }
 
+/**
+ * Whether a request carrying its OWN main credential still serves on main because the operator
+ * manually pinned it (#3166), split from the surrounding resolution so request preview can ask
+ * the identical question (#4850).
+ *
+ * Exported for exactly one reason: two copies of this fence is how #4850 happened. Final
+ * authentication honoured the ownership boundary while request preview, computing its fence from
+ * recovery and drain state alone, still handed pool eligibility the default liveness probe and
+ * opened the physical `auth.json` twice per spawn. A predicate one caller can forget is a
+ * predicate the other caller will eventually disagree with.
+ *
+ * Read-free by construction, which is what makes it usable on the fenced side. Every input is
+ * config, policy, or in-memory runtime state: the pin fields, the paused list, the cached quota
+ * score, and `callerMatchesObservedMain`, which compares HMAC digests against the observed
+ * credential record in `main-account-cache.ts`. Nothing here opens a file.
+ *
+ * `candidate` is the pin before the hard-lock question, because the caller still owes the
+ * pending-binding check that only final authentication can fail closed on.
+ */
+export function requestOwnedMainPinState(
+  headers: Headers,
+  config: OcxConfig,
+  policy: CodexAuthPolicyConfig,
+  requestScopedMainCredential: boolean,
+  fixedAccountId: string | undefined,
+): { candidate: boolean; preserve: boolean } {
+  const candidate = requestScopedMainCredential
+    && fixedAccountId === undefined
+    && config.activeCodexAccountPinned === MAIN_CODEX_ACCOUNT_ID
+    && isEffectiveCodexAccountPinned(config)
+    && !policy.pausedCodexAccountIds?.includes(MAIN_CODEX_ACCOUNT_ID)
+    && requestOwnedMainPinHasQuotaHeadroom(config);
+  return {
+    candidate,
+    preserve: candidate && !(callerMatchesObservedMain(headers) && isMainAccountHardLocked(policy)),
+  };
+}
+
 /**
  * Every thread keys as ITSELF, never as its parent (#4546, wp8).
  *
@@ -816,19 +854,15 @@ export async function resolveCodexAuthContext(
     throw new CodexReserveUnavailableError();
   }
   const fixedAccountId = reserve ? MAIN_CODEX_ACCOUNT_ID : options.accountId;
-  const requestOwnedMainPinCandidate = requestScopedMainCredential
-    && fixedAccountId === undefined
-    && config.activeCodexAccountPinned === MAIN_CODEX_ACCOUNT_ID
-    && isEffectiveCodexAccountPinned(config)
-    && !policy.pausedCodexAccountIds?.includes(MAIN_CODEX_ACCOUNT_ID)
-    && requestOwnedMainPinHasQuotaHeadroom(config);
+  const {
+    candidate: requestOwnedMainPinCandidate,
+    preserve: preserveRequestOwnedMainPin,
+  } = requestOwnedMainPinState(headers, config, policy, requestScopedMainCredential, fixedAccountId);
   // During an owned startup, equality cannot be established until recovery and the
   // memory-only policy binding finish. This read-only fence never probes a foreign home.
   if (policy.codexMainAccountHardLock === true && requestOwnedMainPinCandidate && isMainAccountPolicyBindingPending()) {
     throw new CodexMainProfileDrainingError();
   }
-  const preserveRequestOwnedMainPin = requestOwnedMainPinCandidate
-    && !(callerMatchesObservedMain(headers) && isMainAccountHardLocked(policy));
   if (fixedAccountId !== undefined && options.excludeAccountId !== undefined) {
     throw new Error("Codex auth context cannot select and exclude an account simultaneously");
   }

package/src/codex/desktop-switches.ts

@@ -0,0 +1,145 @@
+import type { OcxConfig } from "../types";
+import { shouldSyncCodexOnStart } from "./desired-state";
+import {
+  isEffectiveCodexClientCompaction,
+  isEffectiveCodexDesktopAuthless,
+} from "./loopback-target";
+
+export type CodexDesktopSwitchInertReason =
+  | "client_role"
+  | "non_loopback_bind_requires_admission_token";
+
+export interface CodexDesktopSwitchState {
+  stored: boolean;
+  effective: boolean;
+  inertReason?: CodexDesktopSwitchInertReason;
+}
+
+export type CodexDesktopSwitchApplyReason =
+  | "not_requested"
+  | "proxy_not_running"
+  | "integration_disabled"
+  | "write_lock_busy"
+  | "injection_refused";
+
+export type CodexDesktopSwitchApply =
+  | { applied: true }
+  | {
+      applied: false;
+      reason: CodexDesktopSwitchApplyReason;
+      retryable: boolean;
+      detail?: string;
+    };
+
+export interface CodexDesktopSwitchReport {
+  codexDesktopAuthless: CodexDesktopSwitchState;
+  codexClientCompaction: CodexDesktopSwitchState;
+  apply: CodexDesktopSwitchApply;
+  authSource: { presentsCodexAccount: boolean; summary: string };
+}
+
+type DesktopSwitchConfig = Pick<
+  OcxConfig,
+  | "clientIntegrations"
+  | "runtimeRole"
+  | "hostname"
+  | "unauthenticatedLoopbackListener"
+  | "codexDesktopAuthless"
+  | "codexClientCompaction"
+>;
+
+function describeSwitch(
+  stored: boolean,
+  effective: boolean,
+  config: Pick<OcxConfig, "runtimeRole">,
+): CodexDesktopSwitchState {
+  if (!stored || effective) return { stored, effective };
+  return {
+    stored,
+    effective,
+    inertReason: config.runtimeRole === "client"
+      ? "client_role"
+      : "non_loopback_bind_requires_admission_token",
+  };
+}
+
+export function describeCodexDesktopSwitches(
+  config: DesktopSwitchConfig,
+  apply: CodexDesktopSwitchApply,
+): CodexDesktopSwitchReport {
+  const authlessStored = config.codexDesktopAuthless === true;
+  const authlessEffective = isEffectiveCodexDesktopAuthless(config);
+  const compactionStored = config.codexClientCompaction === true;
+  const compactionEffective = isEffectiveCodexClientCompaction(config);
+
+  return {
+    codexDesktopAuthless: describeSwitch(authlessStored, authlessEffective, config),
+    codexClientCompaction: describeSwitch(compactionStored, compactionEffective, config),
+    apply,
+    authSource: authlessEffective
+      ? {
+          presentsCodexAccount: false,
+          summary: "The Codex app will not require its own account sign-in.",
+        }
+      : {
+          presentsCodexAccount: true,
+          summary: "The Codex app will require its own account sign-in.",
+        },
+  };
+}
+
+export async function applyCodexDesktopSwitches(
+  config: OcxConfig,
+): Promise<CodexDesktopSwitchApply> {
+  if (!shouldSyncCodexOnStart(config)) {
+    return { applied: false, reason: "integration_disabled", retryable: false };
+  }
+
+  const { readRuntimePort } = await import("../config/process-state");
+  const runtime = readRuntimePort(process.pid);
+  if (!runtime) {
+    return { applied: false, reason: "proxy_not_running", retryable: true };
+  }
+
+  try {
+    // Imported at call time, not module load. The settings route reaches this module on
+    // every GET, and pulling the whole injection graph in just to report stored-versus-
+    // effective state would put it on a read path that never writes anything.
+    const { injectCodexConfig } = await import("./inject");
+    const result = await injectCodexConfig(runtime.port, config);
+    if (result.status === "skipped") {
+      return {
+        applied: false,
+        reason: "integration_disabled",
+        retryable: false,
+        detail: result.message,
+      };
+    }
+    if (result.success) {
+      // history_paginated_requires_native_writer stands down only the legacy relabel;
+      // apply still writes the routing and catalog half for paginated Codex homes.
+      return { applied: true };
+    }
+    if (result.retryable === true) {
+      return {
+        applied: false,
+        reason: "write_lock_busy",
+        retryable: true,
+        detail: result.message,
+      };
+    }
+    return {
+      applied: false,
+      reason: "injection_refused",
+      retryable: false,
+      detail: result.message,
+    };
+  } catch (error) {
+    return {
+      applied: false,
+      reason: "injection_refused",
+      retryable: false,
+      detail: error instanceof Error ? error.message : "Codex config injection failed.",
+    };
+  }
+}

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

@@ -76,6 +76,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 +327,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 +349,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 +410,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);
   }
 }
 
@@ -407,7 +436,7 @@ export function preflightCodexHistoryInjection(
     db = new Database(resolvedPath, { readonly: true });
     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 +446,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-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/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") }),
   };
 }