@bitkyc08/opencodex 2.63.0-preview.20260923 → 2.64.0-preview.20260923

package/src/codex/cli-installation-targets.ts

@@ -1,4 +1,3 @@
-import { closeSync, existsSync, openSync, readSync } from "node:fs";
 import { win32 } from "node:path";
 import { SHIM_MARKER } from "./shim-templates";
 import type { CodexCliInstallationIdentityInput } from "./cli-installation-identity";
@@ -27,45 +26,30 @@ export type CodexCliInstallationTargetDerivation =
 
 export interface CodexCliInstallationTargetDeps {
   readonly platform?: NodeJS.Platform;
-  readonly exists?: (path: string) => boolean;
+  /** `refused` means the probe could not decide; a PATH scan must stop rather than
+   *  attest a later candidate that the real launcher would never reach. */
+  readonly exists?: (path: string) => boolean | "refused" | "volume-unavailable" | Promise<boolean | "refused" | "volume-unavailable">;
   /** Bounded prefix read used only to recognize an OpenCodex-owned wrapper. */
-  readonly fileContains?: (path: string, marker: string) => boolean;
+  readonly fileContains?: (path: string, marker: string) =>
+    boolean | "unavailable" | Promise<boolean | "unavailable">;
 }
 
 const DEFAULT_PATH_EXT = ".COM;.EXE;.BAT;.CMD;.PS1";
 const SHIM_PROBE_BYTES = 8 * 1024;
 const CODEX_PACKAGE_SUFFIX = "\\node_modules\\@openai\\codex\\bin\\codex.js";
 
-function defaultFileContains(path: string, marker: string): boolean {
-  let descriptor: number | undefined;
-  let contains = false;
-  try {
-    descriptor = openSync(path, "r");
-    const bytes = Buffer.allocUnsafe(SHIM_PROBE_BYTES);
-    const count = readSync(descriptor, bytes, 0, bytes.length, 0);
-    contains = bytes.subarray(0, count).toString("utf8").includes(marker);
-  } catch {
-    contains = false;
-  } finally {
-    if (descriptor !== undefined) {
-      try { closeSync(descriptor); } catch { contains = false; }
-    }
-  }
-  return contains;
-}
-
 /**
  * First match wins, mirroring PATH resolution: directories in order, and within
  * each directory every PATHEXT suffix in order (or the exact name when it
  * already carries an extension). Skipping a hit to keep scanning would attest
  * something other than the launcher that actually resolves.
  */
-function scanPath(
+async function scanPath(
   name: string,
   pathValue: string | null | undefined,
   pathExt: string | null | undefined,
-  exists: (path: string) => boolean,
-): string | null {
+  exists: (path: string) => boolean | "refused" | "volume-unavailable" | Promise<boolean | "refused" | "volume-unavailable">,
+): Promise<string | null> {
   const extensions = (pathExt ?? DEFAULT_PATH_EXT).split(";").map(value => value.trim()).filter(Boolean);
   const names = /\.[a-z0-9]+$/i.test(name) ? [name] : extensions.map(ext => name + ext.toLowerCase());
   for (const entry of (pathValue ?? "").split(";")) {
@@ -73,7 +57,10 @@ function scanPath(
     if (!dir) continue;
     for (const candidateName of names) {
       const candidate = win32.join(dir, candidateName);
-      if (exists(candidate)) return candidate;
+      const found = await exists(candidate);
+      if (found === "volume-unavailable") break;
+      if (found === "refused") return null;
+      if (found) return candidate;
     }
   }
   return null;
@@ -86,40 +73,57 @@ function scanPath(
  * false identity. No ambient environment is read: without a snapshot the result
  * is unavailable rather than silently trusting the child's environment.
  */
-export function deriveCodexCliInstallationInput(
+export async function deriveCodexCliInstallationInput(
   snapshot: CodexCliInstallationSnapshot,
   deps: CodexCliInstallationTargetDeps = {},
-): CodexCliInstallationTargetDerivation {
+): Promise<CodexCliInstallationTargetDerivation> {
   if ((deps.platform ?? process.platform) !== "win32") {
     return { kind: "unavailable", reason: "unsupported_platform" };
   }
-  const exists = deps.exists ?? existsSync;
-  const fileContains = deps.fileContains ?? defaultFileContains;
+  const safeRead = async (path: string, maxBytes: number, prefixOnly = false) => {
+    const { inspectWindowsInstallationFiles } = await import("./windows-installation-files");
+    return inspectWindowsInstallationFiles([{ path, maxBytes, metadataOnly: maxBytes === 0, prefixOnly }]);
+  };
+  const exists = deps.exists ?? (async (path: string) => {
+    const result = await safeRead(path, 0);
+    if (result.kind === "observed") return true;
+    return result.reason === "not-found" ? false
+      : result.reason === "volume-unavailable" ? "volume-unavailable" : "refused";
+  });
+  const fileContains = deps.fileContains ?? (async (path: string, marker: string) => {
+    const result = await safeRead(path, SHIM_PROBE_BYTES, true);
+    if (result.kind !== "observed") return "unavailable";
+    return Buffer.from(result.files[0]!.bytes).toString("utf8").includes(marker);
+  });
   const configured = snapshot.codexCliPath;
 
   let candidate: string | null;
   if (configured) {
     if (/^[a-z]:[\\/]/i.test(configured)) {
-      if (!exists(configured)) return { kind: "unavailable", reason: "candidate_unavailable" };
+      if (await exists(configured) !== true) return { kind: "unavailable", reason: "candidate_unavailable" };
       candidate = win32.normalize(configured);
     } else {
       if (configured.includes("/") || configured.includes("\\")) {
         return { kind: "unavailable", reason: "candidate_unavailable" };
       }
-      candidate = scanPath(configured, snapshot.path, snapshot.pathExt, exists);
+      candidate = await scanPath(configured, snapshot.path, snapshot.pathExt, exists);
       if (!candidate) return { kind: "unavailable", reason: "candidate_unavailable" };
     }
   } else {
-    candidate = scanPath("codex", snapshot.path, snapshot.pathExt, exists);
+    candidate = await scanPath("codex", snapshot.path, snapshot.pathExt, exists);
     if (!candidate) return { kind: "unavailable", reason: "candidate_unavailable" };
   }
 
   // An OpenCodex wrapper at the npm prefix is our own launcher, not the npm
   // artifact. The renamed original beside it is the file npm wrote.
-  if (/\.cmd$/i.test(candidate) && fileContains(candidate, SHIM_MARKER)) {
-    const backing = candidate.slice(0, -".cmd".length) + ".opencodex-real.cmd";
-    if (!exists(backing)) return { kind: "unavailable", reason: "unsupported_layout" };
-    candidate = backing;
+  if (/\.cmd$/i.test(candidate)) {
+    const marker = await fileContains(candidate, SHIM_MARKER);
+    if (marker === "unavailable") return { kind: "unavailable", reason: "candidate_unavailable" };
+    if (marker) {
+      const backing = candidate.slice(0, -".cmd".length) + ".opencodex-real.cmd";
+      if (await exists(backing) !== true) return { kind: "unavailable", reason: "unsupported_layout" };
+      candidate = backing;
+    }
   }
 
   const base = win32.basename(candidate).toLowerCase();
@@ -131,19 +135,19 @@ export function deriveCodexCliInstallationInput(
   } else {
     return { kind: "unavailable", reason: "unsupported_layout" };
   }
-  if (!exists(win32.join(prefix, "node_modules", "@openai", "codex", "package.json"))) {
+  if (await exists(win32.join(prefix, "node_modules", "@openai", "codex", "package.json")) !== true) {
     return { kind: "unavailable", reason: "unsupported_layout" };
   }
 
   // The npm cmd-shim itself prefers %dp0%\node.exe before falling back to PATH.
   let node = win32.join(prefix, "node.exe");
-  if (!exists(node)) {
-    const resolved = scanPath("node.exe", snapshot.path, null, exists);
+  if (await exists(node) !== true) {
+    const resolved = await scanPath("node.exe", snapshot.path, null, exists);
     if (!resolved) return { kind: "unavailable", reason: "toolchain_unresolved" };
     node = resolved;
   }
   const npmCli = win32.join(win32.dirname(node), "node_modules", "npm", "bin", "npm-cli.js");
-  if (!exists(npmCli)) return { kind: "unavailable", reason: "toolchain_unresolved" };
+  if (await exists(npmCli) !== true) return { kind: "unavailable", reason: "toolchain_unresolved" };
 
   return {
     kind: "derived",

package/src/codex/codex-write-lock.ts

@@ -95,6 +95,18 @@ export interface CodexWriteLockOptions {
   readAdmissionUnderLock(): CodexWriteWitness;
   /** Positively authorized migration of an already-routed pre-substrate home. */
   adoption?: { readonly direction: "apply" | "remove" };
+  /**
+   * Synchronous filesystem compensation if publication or commit fails after the callback
+   * returns. Runs under N and C, before the coordinator transaction rolls back. Callers that
+   * need no compensation retain the existing commit boundary.
+   */
+  onPostCallbackFailure?: (error: unknown) => void;
+}
+
+let beforeCoordinatorCommitForTests: (() => void) | undefined;
+/** Test seam for a failure after the callback has returned but before SQLite commits. */
+export function setBeforeCoordinatorCommitForTests(hook: typeof beforeCoordinatorCommitForTests): void {
+  beforeCoordinatorCommitForTests = hook;
 }
 
 /**
@@ -357,11 +369,29 @@ export async function withCodexWriteLock<T>(
         if (result && typeof (result as { then?: unknown }).then === "function") {
           throw new TypeError("The Codex write-lock commit callback must be synchronous.");
         }
+        // Only compensating callers keep C through coordinator finalization: a failure
+        // must restore their filesystem preimages before either lock is released.
+        if (options.onPostCallbackFailure) {
+          try {
+            transaction!.assertPublished(expectation);
+            beforeCoordinatorCommitForTests?.();
+            transaction!.commit();
+          } catch (error) {
+            const compensation: unknown = options.onPostCallbackFailure(error);
+            if (compensation && typeof (compensation as { then?: unknown }).then === "function") {
+              void Promise.resolve(compensation).catch(() => {});
+              throw new TypeError("The Codex write-lock failure hook must be synchronous.");
+            }
+            throw error;
+          }
+        }
         return result;
       }));
 
-      transaction.assertPublished(expectation);
-      transaction.commit();
+      if (!options.onPostCallbackFailure) {
+        transaction.assertPublished(expectation);
+        transaction.commit();
+      }
       return { status: "acquired", value: value as T, waitedMs: waited(), lockId: target.lockId };
     } catch (error) {
       transaction.rollback();

package/src/codex/inject/multi-agent-v2.ts

@@ -0,0 +1,90 @@
+import { readFileSync } from "node:fs";
+import type { OcxConfig } from "../../types";
+import { CODEX_CONFIG_PATH } from "../paths";
+
+/**
+ * Reconcile the native `features.multi_agent_v2` override when an injection carries an
+ * explicit v1 surface pin.
+ *
+ * Codex resolves the global v2 feature before catalog-level `multi_agent_version` pins, so a
+ * config.toml that still enables `multi_agent_v2` would run v2 sessions under a catalog the
+ * injection just stamped v1 — and the child tasks it then produces are undeliverable ciphertext
+ * to a v1 reader. Fresh OpenCodex configs write `multiAgentMode: "v1"`, which makes first
+ * injection on a previously-v2 Codex home the common trigger. The explicit mode selectors
+ * (`ocx v2 mode`, `PUT /api/v2`) already run the same format-preserving transition; this is
+ * the injection-side half of that contract.
+ */
+export type InjectedV1SurfaceReconcile =
+  | { ok: true; content: string; changed: boolean }
+  | { ok: false; message: string };
+
+let toggleForTests: ((enabled: boolean) => void) | undefined;
+
+/** Test seam: substitute the native `codex features` toggle so no Codex runtime is required. */
+export function setCodexMultiAgentV2ToggleForTests(
+  toggle: ((enabled: boolean) => void) | undefined,
+): void {
+  toggleForTests = toggle;
+}
+
+/**
+ * A reconcile whose dependencies are resolved ahead of the Codex write lock.
+ *
+ * The write-lock commit callback is synchronous, so the dynamic imports and the
+ * toggle seam are settled in `prepareInjectedV1SurfaceReconcile` before
+ * acquisition. `run()` is the synchronous half and must be called while the
+ * coordinated write boundary is held: the transition mutates config.toml and a
+ * caller that lets it escape the boundary leaves the file changed when a later
+ * step refuses.
+ */
+export interface PreparedV1SurfaceReconcile {
+  /**
+   * Whether the on-disk flag was enabled when the prepare ran. A pre-lock hint
+   * only — `run()` re-checks the flag on the bytes present under the lock.
+   */
+  readonly enabledAtPrepare: boolean;
+  run(): InjectedV1SurfaceReconcile;
+}
+
+/**
+ * Resolve the reconcile for a v1 injection, or null when none can apply.
+ *
+ * Read-only preflight and non-v1 modes are pass-throughs, and externally owned
+ * provider configs never reach this point — the caller returns before
+ * preparing. Resolve the native toggle before the lock even when the flag is
+ * currently off: another writer may enable it before the under-lock re-read.
+ */
+export async function prepareInjectedV1SurfaceReconcile(
+  config: Pick<OcxConfig, "multiAgentMode"> | undefined,
+  options: { validateOnly?: boolean },
+): Promise<PreparedV1SurfaceReconcile | null> {
+  if (options.validateOnly || config?.multiAgentMode !== "v1") {
+    return null;
+  }
+  const { isMultiAgentV2Enabled, transitionMultiAgentV2 } = await import("../features");
+  const enabledAtPrepare = isMultiAgentV2Enabled();
+  let toggle = toggleForTests;
+  if (!toggle) {
+    const { runCodexFeaturesCommand } = await import("../../cli/v2");
+    toggle = enabled => runCodexFeaturesCommand(enabled ? "enable" : "disable");
+  }
+  const resolvedToggle = toggle;
+  return {
+    enabledAtPrepare,
+    run() {
+      // Decide on the bytes present NOW, under the lock — the prepare-time
+      // answer is stale the moment another writer could have touched the file.
+      if (!isMultiAgentV2Enabled()) {
+        return { ok: true, content: readFileSync(CODEX_CONFIG_PATH, "utf-8"), changed: false };
+      }
+      const transition = transitionMultiAgentV2(false, resolvedToggle);
+      if (!transition.ok) {
+        return {
+          ok: false,
+          message: `Codex config injection refused: could not reconcile the v1 surface with the global multi_agent_v2 feature: ${transition.error}.`,
+        };
+      }
+      return { ok: true, content: readFileSync(CODEX_CONFIG_PATH, "utf-8"), changed: transition.changed };
+    },
+  };
+}

package/src/codex/inject/plan.ts

@@ -0,0 +1,365 @@
+/**
+ * The injection plan: every byte the artifact commit will write, plus the
+ * journal baseline, derived from one native config.toml text.
+ *
+ * This is pure transformation and read-only preflight — no filesystem
+ * mutation — so the caller derives once at admission time for the write
+ * witness and pre-lock checks, and then AGAIN under the write lock when the
+ * v1-surface reconcile changes config.toml there. Re-deriving from the
+ * post-transition bytes is what keeps the committed file from re-enabling the
+ * flag the reconcile just turned off.
+ */
+import { websocketsEnabled } from "../../config";
+import {
+  HISTORY_RELABEL_STANDS_DOWN,
+  preflightCodexHistoryInjection,
+} from "../history-provider";
+import {
+  journaledInjectedOpenaiBaseUrl,
+  journaledInjectedRealtimeWsBaseUrl,
+} from "../journal";
+import { stripJournaledOpenaiBaseUrl } from "../injected-marker";
+import { CODEX_CONFIG_PATH, resolveCodexStateDbPath } from "../paths";
+import { transformManagedSubagentDefaults } from "../subagent-defaults";
+import type { OcxConfig } from "../../types";
+import type { CodexWriteCandidate } from "../write-coordination";
+import {
+  applyEol,
+  buildProfileFileForTarget,
+  buildProviderTableBlockForTarget,
+  chooseCatalogPathForInjection,
+  dominantEol,
+  ensureFastModeFeature,
+  normalizeServiceTier,
+  removeProfileSection,
+  setRootModelCatalogPath,
+  setRootModelProvider,
+  setRootOpenaiBaseUrlForTarget,
+  setRootRealtimeWsBaseUrl,
+  stripExistingModelProvider,
+  stripInjectedOpenaiBaseUrl,
+  stripOpencodexCatalogPath,
+  stripRootContextWindowOverrides,
+} from "./config-toml";
+import { hasOcxProviderTable, removeOcxSection } from "./remove";
+import {
+  configuredManagedSubagentDefaults,
+  usesProviderTable,
+  type CodexRoutingTarget,
+} from "./routing-target";
+import { applyPaginatedOpenaiCompat } from "./paginated-openai-compat";
+
+/** Everything the plan needs that is not the config.toml input text. */
+export interface CodexInjectionPlanContext {
+  readonly config: OcxConfig | undefined;
+  readonly routingTarget: CodexRoutingTarget;
+  /** The caller's catalog path option — the RESOLVED path lands on the plan. */
+  readonly catalogPathOption: string | null | undefined;
+  /** Journal reads stay read-only while a client guard owns the write channel. */
+  readonly journalReadOnly: boolean;
+}
+
+/** The ok-variant of the plan: every derived artifact and reportable warning. */
+export interface CodexInjectionPlanOk {
+  kind: "ok";
+  /** The input with marker-owned residue removed — what writeJournal snapshots. */
+  baselineContent: string;
+  /** The exact string about to replace config.toml. */
+  content: string;
+  /** The exact string about to replace the profile file. */
+  profileContent: string;
+  /** The resolved catalog path, never the raw option. */
+  catalogPath: string | null;
+  providerTableMode: boolean;
+  keepRootOverrideAlongsideTable: boolean;
+  keptUserBaseUrl: boolean;
+  keptUserRealtimeWsBaseUrl: boolean;
+  nativeSubagentDefaultsWarning: string | undefined;
+  managedDefaultsMessage: string;
+  /**
+   * Mutable: the artifact commit re-observes the history store mid-write and
+   * records the outcome here so the caller's message reflects it.
+   */
+  historyRelabelRefusal: string | null;
+  /** Read-only history preflight bound to this plan's candidate bytes. */
+  historyPreflight(): string | null;
+  /** The witness candidate: the bytes this plan commits. */
+  candidate: CodexWriteCandidate;
+}
+
+export type CodexInjectionPlan =
+  | {
+      kind: "refused";
+      message: string;
+      historyPreflightFailureReason?: string;
+    }
+  | CodexInjectionPlanOk;
+
+export function deriveCodexInjectionPlan(
+  source: string,
+  ctx: CodexInjectionPlanContext,
+): CodexInjectionPlan {
+  const { config, routingTarget } = ctx;
+  const preflightTableMode = usesProviderTable(routingTarget);
+  const compactionOnly = routingTarget.clientCompaction === true
+    && routingTarget.desktopAuthless !== true
+    && routingTarget.requiresAdmissionToken !== true;
+
+  // Marker-owned native defaults are OpenCodex residue, never part of the
+  // user's journal baseline. Clean them before either snapshotting or adding a
+  // root routing key: inserting that key ahead of a marker-owned first table
+  // would otherwise separate the table marker from its header. Ambiguous
+  // markers fail closed without writing config, profile, or journal state.
+  const nativeDefaultsBaseline = transformManagedSubagentDefaults(
+    source,
+    null,
+  );
+  if (!nativeDefaultsBaseline.ok) {
+    return {
+      kind: "refused",
+      message:
+        `Codex config injection refused: existing OpenCodex-managed native sub-agent defaults are ambiguous: ${nativeDefaultsBaseline.error}. ` +
+        `No files were changed; inspect ${CODEX_CONFIG_PATH}.`,
+    };
+  }
+  const baselineContent = nativeDefaultsBaseline.content;
+
+  /*
+   * The journal write happens inside the write lock, after this plan is
+   * derived. The lock's witness hashes the CANDIDATE BYTES, and those are not
+   * final until `profileContent` and the EOL-applied `content` exist.
+   * Opening the lock before them would leave nothing to hash; keeping the
+   * journal outside the lock would leave the first artifact-creating write
+   * unserialized.
+   *
+   * The split is safe because derivation performs no filesystem mutation — its
+   * only touch is `existsSync` on the catalog paths
+   * (`chooseCatalogPathForInjection`) — and because `writeJournal` is called
+   * with `configContent`, so it snapshots the baseline it is handed rather
+   * than rereading config.toml underneath the transforms.
+   */
+  // EOL boundary: transforms below are LF-pure; preserve the file's dominant ending on write.
+  const eol = dominantEol(source);
+  let content = applyEol(baselineContent, "\n");
+
+  // Idempotent clean-up of any prior injection: drop the provider table (marker-based) and every
+  // stray/mis-nested model_provider line, so re-injecting can't duplicate keys or leave the buggy
+  // table-nested key behind.
+  // Design B form FIRST: removeOcxSection also keys on the marker line, so a root-level
+  // marker + openai_base_url pair must be gone before it scans or it would swallow root keys.
+  content = stripInjectedOpenaiBaseUrl(content);
+  // #1798: after a Codex app rewrite the markers are gone but the values we recorded writing
+  // are still ours. Consume them by value here, BEFORE the routing form is chosen, so a
+  // Design B -> provider-table transition (hostname change, authless opt-in) cannot leave our
+  // own root URLs behind as if they were the user's, and so re-inject never journals them as
+  // not-ours (which would make them unrestorable).
+  content = stripJournaledOpenaiBaseUrl(
+    content,
+    journaledInjectedOpenaiBaseUrl({ readOnly: ctx.journalReadOnly }),
+    journaledInjectedRealtimeWsBaseUrl({ readOnly: ctx.journalReadOnly }),
+  );
+  // Whether this home already published the provider id that its thread rows may reference.
+  // Design B strips the table below; it may only stay stripped if those rows can be relabeled.
+  const hadOcxProviderTableOnDisk = hasOcxProviderTable(content);
+  if (hadOcxProviderTableOnDisk) {
+    content = removeOcxSection(content);
+  }
+  content = removeProfileSection(content);
+  content = stripExistingModelProvider(content);
+  content = stripRootContextWindowOverrides(content);
+  content = normalizeServiceTier(content);
+  content = ensureFastModeFeature(content, config?.fastMode);
+
+  const catalogPath = chooseCatalogPathForInjection(
+    content,
+    ctx.catalogPathOption,
+  );
+  content = catalogPath
+    ? setRootModelCatalogPath(content, catalogPath)
+    : stripOpencodexCatalogPath(content);
+
+  // Provider-table form: non-loopback admission or an explicit Desktop policy.
+  const providerTableMode = usesProviderTable(routingTarget);
+  // Client compaction is the one table form that must not orphan existing threads. It changes
+  // the DEFAULT provider to `opencodex`, but a thread already tagged `openai` keeps resolving
+  // to Codex's built-in entry, and without the root override that entry is api.openai.com —
+  // the thread would resume outside this proxy and outside configured routing. Keeping the
+  // marker-owned root override alongside the table fixes that at the source: codex builds its
+  // provider map as merge_configured_model_providers(built_in_model_providers(openai_base_url),
+  // model_providers), so the override lands on the built-in `openai` entry when the map is
+  // built, independent of which id is the default, and the merge leaves that entry alone for
+  // every id except the two Amazon Bedrock ones. With the managed override in place both
+  // entries point at this proxy. That is a guarantee about the line we own: when the user owns
+  // the root line we inject nothing, and the built-in entry keeps whatever destination they
+  // chose, so an `openai`-tagged thread follows their configuration rather than this proxy.
+  //
+  // Re-tagging history was the alternative and it cannot be made durable: the length-preserving
+  // 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.
+  let keepRootOverrideAlongsideTable = providerTableMode
+    && routingTarget.clientCompaction === true
+    && routingTarget.desktopAuthless !== true
+    && routingTarget.requiresAdmissionToken !== true;
+  let keptUserBaseUrl = false;
+  let keptUserRealtimeWsBaseUrl = false;
+  if (providerTableMode) {
+    // Legacy (non-loopback) injection: the built-in openai provider cannot carry the
+    // x-opencodex-api-key env header, so keep the opencodex provider table + root re-tag.
+    // The authless opt-in needs the same table because only a dedicated provider can carry
+    // requires_openai_auth = false.
+    // 1) Root key BEFORE the first table header (must be a global, not nested under a table).
+    content = setRootModelProvider(content);
+    // 2) Provider table appended at EOF (position-independent).
+    content =
+      content.trimEnd() +
+      "\n" +
+      buildProviderTableBlockForTarget(routingTarget, websocketsEnabled(config ?? {}), config?.codexProviderDisplayName);
+    // 3) Keep existing `openai`-tagged threads reaching the proxy (see above). Ownership rules
+    // are the Design B ones: a user's own root line is never replaced.
+    if (keepRootOverrideAlongsideTable) {
+      content = stripInjectedOpenaiBaseUrl(content);
+      const rootFallback = setRootOpenaiBaseUrlForTarget(content, routingTarget);
+      content = rootFallback.content;
+      keptUserBaseUrl = rootFallback.keptUserBaseUrl;
+    }
+  } else {
+    // Design B (loopback): a single root override; codex keeps its native `openai` provider id
+    // so thread history is never remapped. Any legacy form was already stripped above.
+    content = stripInjectedOpenaiBaseUrl(content); // normalize before idempotent re-insert
+    const result = setRootOpenaiBaseUrlForTarget(content, routingTarget);
+    content = result.content;
+    keptUserBaseUrl = result.keptUserBaseUrl;
+    // Voice sideband override rides on the routing override: same value, same ownership rule,
+    // and never when the user owns the routing line (we inject nothing in that case).
+    if (!keptUserBaseUrl) {
+      const realtime = setRootRealtimeWsBaseUrl(content, routingTarget);
+      content = realtime.content;
+      keptUserRealtimeWsBaseUrl = realtime.keptUserRealtimeWsBaseUrl;
+    }
+  }
+
+  const desiredSubagentDefaults = configuredManagedSubagentDefaults(config);
+  const routingOwnershipWarning =
+    keptUserBaseUrl && desiredSubagentDefaults
+      ? "Native Codex sub-agent defaults were not injected: a user-owned root openai_base_url prevents OpenCodex from managing active Codex routing."
+      : undefined;
+  const managedDefaults = transformManagedSubagentDefaults(
+    content,
+    keptUserBaseUrl ? null : desiredSubagentDefaults,
+  );
+  let nativeSubagentDefaultsWarning = routingOwnershipWarning;
+  let managedDefaultsMessage = routingOwnershipWarning
+    ? `  ⚠️ ${routingOwnershipWarning}\n`
+    : "";
+  if (managedDefaults.ok) {
+    content = managedDefaults.content;
+    if (desiredSubagentDefaults && managedDefaults.conflicts.length > 0) {
+      const keys = managedDefaults.conflicts
+        .map((conflict) => `agents.${conflict.key}`)
+        .join(", ");
+      nativeSubagentDefaultsWarning = `Native Codex sub-agent defaults were not injected: user-owned ${keys} preserved.`;
+      managedDefaultsMessage = `  ⚠️ ${nativeSubagentDefaultsWarning}\n`;
+    }
+  } else {
+    const action =
+      desiredSubagentDefaults && !keptUserBaseUrl
+        ? "were not injected"
+        : "could not be safely removed";
+    nativeSubagentDefaultsWarning = `Native Codex sub-agent defaults ${action}: ${managedDefaults.error}.`;
+    managedDefaultsMessage = `  ⚠️ ${nativeSubagentDefaultsWarning}\n`;
+  }
+
+  const profileContent = buildProfileFileForTarget(
+    routingTarget,
+    catalogPath,
+    websocketsEnabled(config ?? {}),
+    config?.fastMode,
+    config?.codexProviderDisplayName,
+  );
+  content = applyEol(content, eol);
+
+  // Resolve storage from the normalized candidate. Owned duplicate catalog keys
+  // are repairable above and must not make this read-only preflight throw.
+  const historyPreflight = (): string | null => {
+    try {
+      return preflightCodexHistoryInjection(
+        preflightTableMode,
+        config?.syncResumeHistory !== false && !compactionOnly,
+        resolveCodexStateDbPath({ readConfig: () => content }),
+      );
+    } catch {
+      return "history_injection_preflight_unavailable";
+    }
+  };
+  /*
+   * ONE refusal stands the relabel unit down instead of vetoing the config transition, and
+   * only because it is permanent. Codex allocates paginated rollout ordinals in its own
+   * writer, so `assertLegacyHistoryRecord` refuses every rollout on a current install and no
+   * amount of retrying changes that. While it vetoed the write, `model_catalog_json` never
+   * reached config.toml, so the app and the CLI both fell back to their built-in model list
+   * while `ocx sync` still reported success.
+   *
+   * Every other reason — an unreadable state database, a rollout whose identity changed, a
+   * preflight that could not run — describes a store that may well be relabelable on the next
+   * attempt. Treating those as a stand-down would record the transition as converged and
+   * suppress the relabel permanently, so they keep the hard refusal and the rollback.
+   */
+  /*
+   * Re-observed inside the artifact transaction. A store that migrates to paginated history
+   * mid-write can retire the relabel unit while its already-admitted candidate leaves
+   * existing provider references resolvable. Existing provider definitions are retained
+   * before the witness; no post-commit compensation may overwrite a newer native write.
+   */
+  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 {
+      kind: "refused",
+      historyPreflightFailureReason: observedHistoryRefusal,
+      message: compat.message,
+    };
+  }
+
+  /*
+   * Rows this home may have tagged `opencodex` resolve only through a provider table. Design B
+   * selects built-in `openai` for new work, but background relabel and native publication are
+   * not atomic. Codex can paginate after the final check or when the worker starts. Retain
+   * an existing definition BEFORE the witness regardless of preflight, so worker failure
+   * cannot orphan old references. Explicit restoration keeps its removal and history guards.
+   */
+  if (hadOcxProviderTableOnDisk && !providerTableMode) {
+    content = applyEol(
+      content.trimEnd() + "\n" + buildProviderTableBlockForTarget(routingTarget, websocketsEnabled(config ?? {}), config?.codexProviderDisplayName),
+      eol,
+    );
+  }
+
+  return {
+    kind: "ok",
+    baselineContent,
+    content,
+    profileContent,
+    catalogPath,
+    providerTableMode,
+    keepRootOverrideAlongsideTable,
+    keptUserBaseUrl,
+    keptUserRealtimeWsBaseUrl,
+    nativeSubagentDefaultsWarning,
+    managedDefaultsMessage,
+    historyRelabelRefusal: observedHistoryRefusal,
+    historyPreflight,
+    candidate: {
+      configBytes: content,
+      profileBytes: profileContent,
+      catalogPath,
+    },
+  };
+}