@bitkyc08/opencodex 2.81.0 → 2.83.0

package/src/codex/inject/config-write-section.ts

@@ -0,0 +1,34 @@
+import type { AtomicWriteHooks } from "../../config/atomic-write";
+import { existsSync, readFileSync } from "node:fs";
+import { withConfigMutationLockSync } from "../../config";
+import { ConfigWriteLockRefusal, assertConfigWriteDestination, publishConfigWriteTarget, watchConfigWriteTargets, withConfigWriteLockHeld, type LockHandle } from "../config-write-lock";
+import { CODEX_CONFIG_PATH, CODEX_PROFILE_PATH } from "../paths";
+import { getCodexHome } from "../paths";
+import { codexHomeIsAbsent } from "../codex-home-owner";
+import { JOURNAL_PATH, removeJournal } from "../journal";
+import { externalCodexModelProvider } from "./config-toml";
+
+export function beginCodexWriteSection(held: LockHandle): void {
+  assertConfigWriteDestination(CODEX_CONFIG_PATH, held);
+  watchConfigWriteTargets(held, [CODEX_CONFIG_PATH, CODEX_PROFILE_PATH, JOURNAL_PATH]);
+}
+export function publishCodexArtifact<T>(path: string, held: LockHandle | undefined, run: (destination: string, hooks: AtomicWriteHooks) => T): T {
+  if (!held) throw new Error("Codex artifact publication requires a held configuration lock");
+  return publishConfigWriteTarget(CODEX_CONFIG_PATH, held, path, run);
+}
+/** Courtesy cleanup re-reads provider ownership inside the same config section. */
+export function cleanExternalProviderJournal(beforeClientWrite?: () => void): void {
+  if (codexHomeIsAbsent(getCodexHome())) return;
+  const locked = withConfigWriteLockHeld(CODEX_CONFIG_PATH, undefined, held => {
+    beginCodexWriteSection(held);
+    const cleanup = () => {
+      beforeClientWrite?.();
+      if (existsSync(CODEX_CONFIG_PATH) && externalCodexModelProvider(readFileSync(CODEX_CONFIG_PATH, "utf8"))) {
+        publishCodexArtifact(JOURNAL_PATH, held, (_path, hooks) => removeJournal(hooks));
+      }
+    };
+    if (beforeClientWrite) withConfigMutationLockSync(cleanup);
+    else cleanup();
+  });
+  if (!locked.ok) throw new ConfigWriteLockRefusal(locked);
+}

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

@@ -1,5 +1,6 @@
 import { readFileSync } from "node:fs";
 import type { OcxConfig } from "../../types";
+import { ConfigWriteDestinationChanged, type LockHandle } from "../config-write-lock";
 import { CODEX_CONFIG_PATH } from "../paths";
 
 /**
@@ -18,11 +19,11 @@ export type InjectedV1SurfaceReconcile =
   | { ok: true; content: string; changed: boolean }
   | { ok: false; message: string };
 
-let toggleForTests: ((enabled: boolean) => void) | undefined;
+let toggleForTests: ((enabled: boolean, env: NodeJS.ProcessEnv, validateBeforeSpawn: () => void) => void) | undefined;
 
 /** Test seam: substitute the native `codex features` toggle so no Codex runtime is required. */
 export function setCodexMultiAgentV2ToggleForTests(
-  toggle: ((enabled: boolean) => void) | undefined,
+  toggle: ((enabled: boolean, env: NodeJS.ProcessEnv, validateBeforeSpawn: () => void) => void) | undefined,
 ): void {
   toggleForTests = toggle;
 }
@@ -43,7 +44,11 @@ export interface PreparedV1SurfaceReconcile {
    * only — `run()` re-checks the flag on the bytes present under the lock.
    */
   readonly enabledAtPrepare: boolean;
-  run(): InjectedV1SurfaceReconcile;
+  /**
+   * `heldConfigWriteLock` is the injector's own held write-lock handle: the
+   * transition would otherwise re-acquire the same file and refuse itself.
+   */
+  run(heldConfigWriteLock?: LockHandle): InjectedV1SurfaceReconcile;
 }
 
 /**
@@ -66,19 +71,22 @@ export async function prepareInjectedV1SurfaceReconcile(
   let toggle = toggleForTests;
   if (!toggle) {
     const { runCodexFeaturesCommand } = await import("../../cli/v2");
-    toggle = enabled => runCodexFeaturesCommand(enabled ? "enable" : "disable");
+    toggle = (enabled, env, validate) => runCodexFeaturesCommand(enabled ? "enable" : "disable", "multi_agent_v2", env, validate);
   }
   const resolvedToggle = toggle;
   return {
     enabledAtPrepare,
-    run() {
+    run(heldConfigWriteLock) {
       // 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);
+      const transition = transitionMultiAgentV2(false, resolvedToggle, {
+        ...(heldConfigWriteLock !== undefined ? { heldConfigWriteLock } : {}),
+      });
       if (!transition.ok) {
+        if (transition.retryable === false) throw new ConfigWriteDestinationChanged(transition.error);
         return {
           ok: false,
           message: `Codex config injection refused: could not reconcile the v1 surface with the global multi_agent_v2 feature: ${transition.error}.`,

package/src/codex/inject/remove.ts

@@ -1,6 +1,9 @@
+import { beginCodexWriteSection, publishCodexArtifact } from "./config-write-section";
 import { existsSync, readFileSync, unlinkSync } from "node:fs";
 import { normalizeStructuralWhitespace, rootAssignmentKey, rootSourceLines, sourceAssignment, sourceText } from "../toml-source-lines";
 import { atomicWriteFile } from "../../config";
+import { ConfigWriteLockRefusal, configWriteLockFailureMessage, withConfigWriteLockHeld } from "../config-write-lock";
+import type { LockHandle } from "../config-write-lock";
 import {
   REALTIME_WS_BASE_URL_KEY,
   hasInjectedOpenaiBaseUrl,
@@ -15,6 +18,8 @@ import {
   journaledReplacedRootWebSearch,
 } from "../journal";
 import { CODEX_CONFIG_PATH, CODEX_PROFILE_PATH } from "../paths";
+import { getCodexHome } from "../paths";
+import { codexHomeIsAbsent } from "../codex-home-owner";
 import { transformManagedSubagentDefaults } from "../subagent-defaults";
 import {
   applyEol,
@@ -45,14 +50,22 @@ export function readOcxProviderTableBlock(): string | null {
  * 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");
+export function retainOcxProviderTableOnDisk(block: string, heldConfigWriteLock?: LockHandle): string[] | null {
+  // The read, the append, and the rename are one section under the shared
+  // write lock; an unlocked read+rename here could discard a concurrent
+  // scalar or projection write.
+  const locked = withConfigWriteLockHeld(CODEX_CONFIG_PATH, heldConfigWriteLock, held => {
+    beginCodexWriteSection(held);
+    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) publishCodexArtifact(CODEX_CONFIG_PATH, held, (path, hooks) => atomicWriteFile(path, applyEol(next, eol), undefined, hooks));
+    return block.replace(/\n+$/, "").split("\n");
+  });
+  if (!locked.ok) throw new ConfigWriteLockRefusal(locked);
+  return locked.value;
 }
 
 interface StripOpencodexConfigResult {
@@ -162,9 +175,12 @@ export type RemoveCodexConfigHistoryDisposition =
 export interface RemoveCodexConfigOptions {
   preserveProfile?: boolean;
   historyDisposition?: RemoveCodexConfigHistoryDisposition;
+  /** Run under a config write lock this process already holds (restore's single section). */
+  heldConfigWriteLock?: LockHandle;
 }
 
 export interface RemoveCodexConfigResult {
+  retryable?: boolean;
   success: boolean;
   message: string;
   /** The exact lines left on disk when the disposition was `stand-down-retain`. */
@@ -174,6 +190,10 @@ export interface RemoveCodexConfigResult {
 export function removeCodexConfig(
   options: RemoveCodexConfigOptions = {},
 ): RemoveCodexConfigResult {
+  if (codexHomeIsAbsent(getCodexHome())) return {
+    success: true,
+    message: `Codex config not found; no native restore was needed${options.preserveProfile ? "." : ", and the opencodex profile was removed if present."}`,
+  };
   const historyDisposition = options.historyDisposition ?? "refuse-on-any";
   const historyError = preflightCodexHistoryInjection(false, false);
   // The preflight answers "may I rewrite conversation history?". Routing removal is a
@@ -184,9 +204,11 @@ export function removeCodexConfig(
   if (historyError && !(historyDisposition !== "refuse-on-any" && historyError === HISTORY_RELABEL_STANDS_DOWN)) {
     return { success: false, message: `Codex configuration preserved: ${historyError}. Native writer coordination is required.` };
   }
+  const locked = withConfigWriteLockHeld(CODEX_CONFIG_PATH, options.heldConfigWriteLock, held => {
+  beginCodexWriteSection(held);
   if (!existsSync(CODEX_CONFIG_PATH)) {
     if (!options.preserveProfile && existsSync(CODEX_PROFILE_PATH))
-      unlinkSync(CODEX_PROFILE_PATH);
+      publishCodexArtifact(CODEX_PROFILE_PATH, held, (path, hooks) => { hooks.validateBeforeRename?.(path); unlinkSync(path); hooks.afterRename?.(path); });
     return {
       success: true,
       message: `Codex config not found; no native restore was needed${options.preserveProfile ? "." : ", and the opencodex profile was removed if present."}`,
@@ -223,10 +245,10 @@ export function removeCodexConfig(
     ? stripped.content
     : appendOcxProviderTableBlock(stripped.content, retainedBlock);
   if (had || finalContent !== content) {
-    atomicWriteFile(CODEX_CONFIG_PATH, applyEol(finalContent, eol));
+    publishCodexArtifact(CODEX_CONFIG_PATH, held, (path, hooks) => atomicWriteFile(path, applyEol(finalContent, eol), undefined, hooks));
   }
   if (!options.preserveProfile && existsSync(CODEX_PROFILE_PATH))
-    unlinkSync(CODEX_PROFILE_PATH);
+    publishCodexArtifact(CODEX_PROFILE_PATH, held, (path, hooks) => { hooks.validateBeforeRename?.(path); unlinkSync(path); hooks.afterRename?.(path); });
   const retainedNote = retainedBlock === null
     ? ""
     : " Kept [model_providers.opencodex] so conversations already tagged opencodex still open;"
@@ -250,4 +272,7 @@ export function removeCodexConfig(
     message: removedMessage,
     ...(retainedBlock === null ? {} : { retainedProviderTable: retainedBlock.replace(/\n+$/, "").split("\n") }),
   };
+  });
+  if (!locked.ok) return { success: false, retryable: locked.error === "locked", message: configWriteLockFailureMessage(locked) };
+  return locked.value;
 }

package/src/codex/inject/restore.ts

@@ -1,4 +1,5 @@
-import { assertCodexHomeOwner, codexHomeOwnerBlocksCompensation, CodexHomeOwnerRefusal, type CodexHomeOwnerRefusalReason } from "../codex-home-owner";
+import { beginCodexWriteSection, cleanExternalProviderJournal, publishCodexArtifact } from "./config-write-section";
+import { assertCodexHomeOwner, codexHomeIsAbsent, codexHomeOwnerBlocksCompensation, CodexHomeOwnerRefusal, type CodexHomeOwnerRefusalReason } from "../codex-home-owner";
 import { loadConfig } from "../../config";
 import { shouldSyncCodexOnStart } from "../desired-state";
 import { siblingOfLivePort, siblingSkipMessage } from "../sibling-start";
@@ -26,7 +27,7 @@ import {
 } from "../user-identity";
 import {
   journaledInjectedCatalogPath,
-  removeJournal,
+  JOURNAL_PATH,
   releaseJournalHomeBinding,
   restoreJournalState,
 } from "../journal";
@@ -44,10 +45,17 @@ import {
   type CodexHistoryJobOutcome,
 } from "../history-job";
 import {
+  CODEX_CONFIG_PATH,
   DEFAULT_CATALOG_PATH,
   getCodexHome,
   tomlString,
 } from "../paths";
+import {
+  acquireConfigWriteLock,
+  releaseConfigWriteLock,
+  configWriteLockFailureMessage, withConfigWriteLockHeld,
+} from "../config-write-lock";
+import type { LockHandle } from "../config-write-lock";
 import { shouldInjectApiAuthHeader } from "../loopback-target";
 import { currentExternalCodexModelProvider } from "./config-toml";
 import {
@@ -110,6 +118,7 @@ export interface CodexRestoreConfigResult {
     | "failed";
   message: string;
   retained?: RetainedCodexProviderTable;
+  retryable?: boolean;
 }
 
 export interface CodexRestoreCatalogResult {
@@ -343,20 +352,45 @@ export interface RestoreConfigOptions {
 }
 
 /** The config/profile half of a native restore, reported as one artifact. */
-function restoreCodexConfigInline(kind = "sync", options: RestoreConfigOptions = {}): CodexRestoreConfigResult {
-  assertCodexHomeOwner(getCodexHome());
-  beforeRestoreConfigForTests?.(kind);
-  assertCodexHomeOwner(getCodexHome());
-  const preImages = captureCodexPreImages();
-  const result = restoreCodexConfigInlineImpl(kind, options);
-  if (result.state === "failed") {
-    const compensated = restoreCodexPreImages(preImages);
-    if (!compensated.complete) throw new CodexPartialWriteError(compensated.unrestored);
+function restoreCodexConfigInline(
+  kind = "sync",
+  options: RestoreConfigOptions = {},
+  heldConfigWriteLock?: LockHandle,
+): CodexRestoreConfigResult {
+  /*
+   * The whole config half — preimage capture, journal replay, removal, the
+   * provider-table re-attach, and failure compensation — is ONE section of the
+   * shared write lock. Splitting it let a foreign write land between the pieces
+   * and left preimage compensation replaying over bytes that writer committed.
+   */
+  const locked = withConfigWriteLockHeld(CODEX_CONFIG_PATH, heldConfigWriteLock, (held) => {
+    beginCodexWriteSection(held);
+    assertCodexHomeOwner(getCodexHome());
+    beforeRestoreConfigForTests?.(kind);
+    assertCodexHomeOwner(getCodexHome());
+    const preImages = captureCodexPreImages();
+    const result = restoreCodexConfigInlineImpl(kind, options, held);
+    if (result.state === "failed") {
+      const compensated = restoreCodexPreImages(preImages, held);
+      if (!compensated.complete) throw new CodexPartialWriteError(compensated.unrestored);
+    }
+    return result;
+  });
+  if (!locked.ok) {
+    // Nothing was captured or written — there is nothing to compensate.
+    return {
+      state: "failed", changed: false, action: "failed",
+      retryable: locked.error === "locked", message: configWriteLockFailureMessage(locked),
+    };
   }
-  return result;
+  return locked.value;
 }
 
-function restoreCodexConfigInlineImpl(kind: string, options: RestoreConfigOptions): CodexRestoreConfigResult {
+function restoreCodexConfigInlineImpl(
+  kind: string,
+  options: RestoreConfigOptions,
+  heldConfigWriteLock: LockHandle,
+): CodexRestoreConfigResult {
   try {
     const disposition = resolveRestoreHistoryDisposition(options.removeProviderTable);
     if (disposition.kind === "refuse") {
@@ -374,8 +408,17 @@ function restoreCodexConfigInlineImpl(kind: string, options: RestoreConfigOption
     // The one caller that must not capture is the explicit removal flag: it is the user
     // accepting that tagged conversations stop opening.
     const capturedBlock = options.removeProviderTable === true ? null : readOcxProviderTableBlock();
-    const journal = restoreJournalState();
+    const journal = restoreJournalState({ heldConfigWriteLock });
     if (journal.ownershipRefusal) throw new CodexHomeOwnerRefusal(journal.ownershipRefusal);
+    if (journal.lockUnsafe) return { state: "failed", changed: false, action: "failed", retryable: false, message: journal.lockUnsafe };
+    if (journal.lockBusy) {
+      // Only reachable when this impl ran without a live held handle — the
+      // outer section takes the file lock before anything else runs.
+      return {
+        state: "failed", changed: false, action: "failed",
+        retryable: true, message: "Another process is writing Codex configuration right now. Retry shortly.",
+      };
+    }
     if (journal.unverified) {
       return {
         state: "failed", changed: false, action: "failed",
@@ -398,6 +441,7 @@ function restoreCodexConfigInlineImpl(kind: string, options: RestoreConfigOption
           historyDisposition: disposition.kind === "stand-down"
             ? disposition.retainProviderTable ? "stand-down-retain" : "stand-down-remove"
             : "refuse-on-any",
+          heldConfigWriteLock,
         });
     let retainedLines = restored.retainedProviderTable ?? null;
     if (restored.success) {
@@ -416,11 +460,11 @@ function restoreCodexConfigInlineImpl(kind: string, options: RestoreConfigOption
       // idempotent — it checks for the table before appending — so the three do not have to
       // be told apart here.
       if (settled.kind === "stand-down" && settled.retainProviderTable && capturedBlock !== null) {
-        retainedLines = retainOcxProviderTableOnDisk(capturedBlock) ?? retainedLines;
+        retainedLines = retainOcxProviderTableOnDisk(capturedBlock, heldConfigWriteLock) ?? retainedLines;
       }
       // All native work and the final migration check succeeded. A field-level
       // fallback retains its snapshot, but no longer owns this Codex home.
-      releaseJournalHomeBinding();
+      publishCodexArtifact(JOURNAL_PATH, heldConfigWriteLock, (_path, hooks) => releaseJournalHomeBinding(hooks));
     }
     if (restored.success && retainedLines !== null) {
       return {
@@ -504,6 +548,7 @@ function restoreCodexCatalogArtifact(
 export async function restoreNativeCodexAsync(
   options: { revalidateDesiredState?: boolean; removeProviderTable?: boolean } = {},
 ): Promise<CodexNativeRestoreResult> {
+  if (codexHomeIsAbsent(getCodexHome())) return skippedRestoreEnvelope(true, "Codex config not found; no native restore was needed.");
   const sibling = siblingRestoreSkip();
   if (sibling) return sibling;
   try {
@@ -524,7 +569,7 @@ async function restoreNativeCodexAsyncImpl(
     // External-provider courtesy: only the stale journal is removed. The
     // history worker must not launch — it would turn a read-mostly courtesy
     // result into a history mutation on a home we do not own.
-    removeJournal();
+    cleanExternalProviderJournal();
     return externalProviderRestoreResult(activeProvider);
   }
 
@@ -560,6 +605,22 @@ async function restoreNativeCodexAsyncImpl(
   let transitionReceipt: { nativeGeneration: number; currentTxId: string } | undefined;
 
   if (eligibility.kind === "coordinated" || eligibility.kind === "adopt") {
+    /*
+     * File lock BEFORE N — the same order injection takes. With the config
+     * writes living inside the journal replay under the file lock, a restore
+     * that took N first while a sibling held the file lock was the one
+     * deliberate inversion; acquiring here first removes it.
+     */
+    const configLock = await acquireConfigWriteLock(CODEX_CONFIG_PATH);
+    if (!configLock.ok) {
+      config = {
+        state: "failed",
+        changed: false,
+        action: "failed",
+        retryable: configLock.error === "locked", message: configWriteLockFailureMessage(configLock),
+      };
+    } else try {
+    beginCodexWriteSection(configLock.handle);
     // The restore has no candidate bytes to witness; freshness comes from the
     // filesystem reads and the desired-state re-read performed under the lock.
     const witness = { authoritySnapshotId: "codex-native-restore" };
@@ -595,12 +656,12 @@ async function restoreNativeCodexAsyncImpl(
         const preImages = captureCodexPreImages();
         let restored: CodexRestoreConfigResult;
         try {
-          restored = restoreCodexConfigInline(eligibility.kind, options);
+          restored = restoreCodexConfigInline(eligibility.kind, options, configLock.handle);
           // Throw inside N so the published remove transition rolls back too.
           if (restored.state === "failed") throw new CodexRestoreRefusal(restored);
         } catch (error) {
           if (codexHomeOwnerBlocksCompensation(getCodexHome(), error)) throw error;
-          const compensated = restoreCodexPreImages(preImages);
+          const compensated = restoreCodexPreImages(preImages, configLock.handle);
           if (!compensated.complete) throw new CodexPartialWriteError(compensated.unrestored);
           throw error;
         }
@@ -632,6 +693,9 @@ async function restoreNativeCodexAsyncImpl(
       config = coordinated.value.config;
       transitionReceipt = coordinated.value.receipt;
     }
+    } finally {
+      releaseConfigWriteLock(configLock.handle);
+    }
   } else {
     // Legacy-uncoordinated (or unresolvable) homes keep the unserialized path
     // they have always had; restore is the escape hatch and must not strand
@@ -713,6 +777,7 @@ function homeOwnerRestoreRefusal(error: CodexHomeOwnerRefusal): CodexNativeResto
 export function restoreNativeCodex(
   options: { skipHistory?: boolean; revalidateDesiredState?: boolean; removeProviderTable?: boolean } = {},
 ): CodexNativeRestoreResult {
+  if (codexHomeIsAbsent(getCodexHome())) return skippedRestoreEnvelope(true, "Codex config not found; no native restore was needed.");
   const sibling = siblingRestoreSkip();
   if (sibling) return sibling;
   try {
@@ -729,7 +794,7 @@ function restoreNativeCodexImpl(
 ): CodexNativeRestoreResult {
   const activeProvider = currentExternalCodexModelProvider();
   if (activeProvider) {
-    removeJournal();
+    cleanExternalProviderJournal();
     return externalProviderRestoreResult(activeProvider);
   }
   if (options.revalidateDesiredState && shouldSyncCodexOnStart(loadConfig())) {

package/src/codex/inject-coordination.ts

@@ -7,6 +7,8 @@
 import { createHash } from "node:crypto";
 import { existsSync, lstatSync, readFileSync } from "node:fs";
 
+import { publishCodexArtifact } from "./inject/config-write-section";
+import { withConfigWriteLockHeld, type LockHandle } from "./config-write-lock";
 import { atomicWriteFile } from "../config";
 import type { CodexWriteLockResult, CodexWriteLockSkipReason } from "./codex-write-lock";
 import { HUB_GATED_SKIP_MESSAGE } from "./desired-state";
@@ -367,7 +369,9 @@ export function recordCodexNativeTransactionProvenance(
  */
 export function restoreCodexPreImages(
   pre: CodexPreImages,
+  heldConfigWriteLock?: LockHandle,
 ): { complete: boolean; unrestored: readonly string[] } {
+  const locked = withConfigWriteLockHeld(CODEX_CONFIG_PATH, heldConfigWriteLock, held => {
   const unrestored: string[] = [];
   const surfaces: readonly [string, string, string | null][] = [
     ["config", CODEX_CONFIG_PATH, pre.config],
@@ -375,18 +379,23 @@ export function restoreCodexPreImages(
     ["journal", JOURNAL_PATH, pre.journal],
   ];
   for (const [name, path, bytes] of surfaces) {
+    // The current journal remains recovery authority until both artifacts are restored.
+    if (name === "journal" && unrestored.length > 0) { unrestored.push(name); continue; }
     try {
-      if (bytes === null) {
-        // Absent before, so absent after. A leftover file is not a restoration.
-        if (existsSync(path)) require("node:fs").unlinkSync(path);
-      } else if (readOrNull(path) !== bytes) {
-        atomicWriteFile(path, bytes);
-      }
+      publishCodexArtifact(path, held, (destination, hooks) => {
+        if (bytes === null) {
+          hooks.validateBeforeRename?.(destination);
+          if (existsSync(destination)) require("node:fs").unlinkSync(destination);
+          hooks.afterRename?.(destination);
+        } else if (readOrNull(destination) !== bytes) atomicWriteFile(destination, bytes, undefined, hooks);
+      });
     } catch {
       unrestored.push(name);
     }
   }
   return { complete: unrestored.length === 0, unrestored };
+  });
+  return locked.ok ? locked.value : { complete: false, unrestored: ["config", "profile", "journal"] };
 }
 
 export function buildInjectWitness(

package/src/codex/inject.ts

@@ -1,3 +1,4 @@
+import { beginCodexWriteSection, cleanExternalProviderJournal, publishCodexArtifact } from "./inject/config-write-section";
 import { closeSync, existsSync, openSync, readFileSync, statSync } from "node:fs";
 import { dirname } from "node:path";
 import {
@@ -9,6 +10,7 @@ import {
 } from "../config";
 import { assertCodexHomeOwner, codexHomeOwnerBlocksCompensation, CodexHomeOwnerRefusal, type CodexHomeOwnerRefusalReason } from "./codex-home-owner";
 import { CodexWriteLockSkipped, withCodexWriteLock } from "./codex-write-lock";
+import { ConfigWriteDestinationChanged, ConfigWriteLockRefusal, configWriteLockFailureMessage, acquireConfigWriteLock, CONFIG_WRITE_LOCK_WAIT_MS, releaseConfigWriteLock, type LockHandle } from "./config-write-lock";
 import {
   localClientSkipMessage,
   localClientSkipReason,
@@ -36,7 +38,7 @@ import {
   resolveEffectiveUserIdentity,
 } from "./user-identity";
 import {
-  hasUnverifiedJournalBaseline,
+  JOURNAL_PATH, hasUnverifiedJournalBaseline,
   markJournalInjectedState,
   journaledInjectedOpenaiBaseUrl,
   journaledInjectedRealtimeWsBaseUrl,
@@ -196,6 +198,8 @@ export async function injectCodexConfig(
   }
   try { assertCodexHomeOwner(getCodexHome()); return await injectCodexConfigImpl(port, config, options); }
   catch (error) {
+    if (error instanceof ConfigWriteDestinationChanged) return { success: false, retryable: false, message: error.message };
+    if (error instanceof ConfigWriteLockRefusal) return { success: false, retryable: error.retryable, message: error.message };
     if (error instanceof CodexHomeOwnerRefusal) return { success: false, ownershipRefusal: error.reason, message: error.message };
     if (error instanceof CodexHistoryPreflightRefusal) return { success: false, historyPreflightFailureReason: error.message, message: `Codex config injection refused: ${error.message}. Existing configuration and history were preserved.` };
     if (error instanceof CodexInjectRefusal) return error.result;
@@ -239,12 +243,7 @@ async function injectCodexConfigImpl(
     // A launcher may have journaled before the provider manager took ownership. Never let shutdown
     // replay that stale snapshot over externally managed config.
     if (!options.validateOnly) {
-      if (options.beforeClientWrite) {
-        withConfigMutationLockSync(() => {
-          runClientWriteGuard(options.beforeClientWrite);
-          removeJournal();
-        });
-      } else removeJournal();
+      cleanExternalProviderJournal(options.beforeClientWrite ? () => runClientWriteGuard(options.beforeClientWrite) : undefined);
     }
     const nativeSubagentDefaultsWarning = configuredManagedSubagentDefaults(
       config,
@@ -419,11 +418,26 @@ async function injectCodexConfigImpl(
    */
   const reconcileAndDerivePlan = (): { plan: CodexInjectionPlanOk; nativeInput: string } => {
     assertCodexHomeOwner(getCodexHome());
-    if (missingConfig) createEmptyCodexConfigInBoundary();
+    /*
+     * Re-admission under the file lock: `rawContent` and `admittedPlan` were
+     * read before this section acquired it, so the file may have moved while
+     * the lock was being waited out — committing the stale plan would rename
+     * over bytes a competing writer landed. Refuse retryably; the next pass
+     * re-reads fresh bytes (the same witness check the coordinated path does).
+     */
+    if ((existsSync(CODEX_CONFIG_PATH) ? readFileSync(CODEX_CONFIG_PATH, "utf-8") : null)
+      !== (missingConfig ? null : rawContent)) {
+      throw new CodexInjectRefusal({
+        success: false,
+        retryable: true,
+        message: "Codex config injection refused: config.toml changed while the write lock was being acquired. Retry to inject on the latest bytes.",
+      });
+    }
+    if (missingConfig) publishCodexArtifact(CODEX_CONFIG_PATH, heldConfigWriteLock, (_path, hooks) => { hooks.validateBeforeRename?.(CODEX_CONFIG_PATH); createEmptyCodexConfigInBoundary(); hooks.afterRename?.(CODEX_CONFIG_PATH); });
     let nativeInput = rawContent;
     let plan = admittedPlan;
     if (v1Reconcile) {
-      const reconciled = v1Reconcile.run();
+      const reconciled = v1Reconcile.run(heldConfigWriteLock);
       if (!reconciled.ok) {
         throw new CodexInjectRefusal({ success: false, message: reconciled.message });
       }
@@ -458,19 +472,19 @@ async function injectCodexConfigImpl(
     plan.historyRelabelRefusal = observeHistoryRefusalOrThrow(plan);
     historyArtifactStageForTests?.("after-preflight");
     assertCodexHomeOwner(getCodexHome());
-    writeJournal({
+    publishCodexArtifact(JOURNAL_PATH, heldConfigWriteLock, (_path, hooks) => writeJournal({
       currentStateIsNative: journalBaselineIsNative(nativeInput),
       configContent: plan.baselineContent,
       owner: options.journalOwner,
-    });
+    }, hooks));
     // A native snapshot may have been refreshed above. An older hashless routed snapshot
     // must not gain the new injection's hash and later overwrite preserved user edits.
     if (hasUnverifiedJournalBaseline(plan.baselineContent, readCurrentProfile())) throw new Error(unverifiedJournalMessage);
-    atomicWriteFile(CODEX_CONFIG_PATH, plan.content);
+    publishCodexArtifact(CODEX_CONFIG_PATH, heldConfigWriteLock, (path, hooks) => atomicWriteFile(path, plan.content, undefined, hooks));
     historyArtifactStageForTests?.("after-config");
     assertCodexHomeOwner(getCodexHome());
-    atomicWriteFile(CODEX_PROFILE_PATH, plan.profileContent);
-    markJournalInjectedState(plan.content, plan.profileContent, {
+    publishCodexArtifact(CODEX_PROFILE_PATH, heldConfigWriteLock, (path, hooks) => atomicWriteFile(path, plan.profileContent, undefined, hooks));
+    publishCodexArtifact(JOURNAL_PATH, heldConfigWriteLock, (_path, hooks) => markJournalInjectedState(plan.content, plan.profileContent, {
       // A root override is ours whenever we wrote one and no user-owned value won. That is
       // loopback Design B, the client-compaction form, and a table form that retained the
       // root line for paginated history. Journaling it matters because the marker comment
@@ -494,7 +508,7 @@ async function injectCodexConfigImpl(
       // This is the catalog artifact selected for this injection, even when config.toml
       // already points at that path and therefore needs no textual rewrite.
       injectedCatalogPath: plan.catalogPath,
-    });
+    }, hooks));
     historyArtifactStageForTests?.("after-artifacts");
     // Detect migration throughout the artifact transaction, not just at entry.
     plan.historyRelabelRefusal = observeHistoryRefusalOrThrow(plan);
@@ -508,6 +522,16 @@ async function injectCodexConfigImpl(
    */
   let transitionReceipt: { nativeGeneration: number; currentTxId: string } | undefined;
 
+  /*
+   * The file-level write lock every config.toml writer shares (see
+   * config-write-lock.ts). The injector takes it FIRST — before the SQLite N
+   * lock below — so the feature transition and the artifact commit can never
+   * be interleaved with a scalar edit, a remove/restore transform, or a
+   * prompt-layers commit. The reconcile consumes the same handle rather than
+   * re-acquiring the file it is already holding.
+   */
+  let heldConfigWriteLock: LockHandle | undefined;
+
   /*
    * The plan the committed write actually used: the admitted plan, or the
    * re-derivation from the post-reconcile bytes when the feature transition
@@ -516,6 +540,19 @@ async function injectCodexConfigImpl(
    */
   let effectivePlan: CodexInjectionPlanOk = admittedPlan;
 
+  const configLock = await acquireConfigWriteLock(CODEX_CONFIG_PATH, {
+    timeoutMs: Math.min(options.lockTimeoutMs ?? CONFIG_WRITE_LOCK_WAIT_MS, CONFIG_WRITE_LOCK_WAIT_MS),
+  });
+  if (!configLock.ok) {
+    return {
+      success: false,
+      retryable: configLock.error === "locked",
+      message: configWriteLockFailureMessage(configLock),
+    };
+  }
+  heldConfigWriteLock = configLock.handle;
+  try {
+  beginCodexWriteSection(configLock.handle);
   if (eligibility.kind === "legacy-uncoordinated") {
     const applyLegacy = (): CodexInjectResult | undefined => {
       const legacyGateSnapshot = loadConfig();
@@ -544,8 +581,8 @@ async function injectCodexConfigImpl(
         applyNativeArtifacts(resolved.plan, resolved.nativeInput);
         effectivePlan = resolved.plan;
       } catch (error) {
-        if (codexHomeOwnerBlocksCompensation(getCodexHome(), error)) throw error;
-        const restored = restoreCodexPreImages(preImages);
+        if (error instanceof ConfigWriteDestinationChanged || codexHomeOwnerBlocksCompensation(getCodexHome(), error)) throw error;
+        const restored = restoreCodexPreImages(preImages, heldConfigWriteLock);
         if (!restored.complete) throw new CodexPartialWriteError(restored.unrestored);
         throw error;
       }
@@ -565,7 +602,7 @@ async function injectCodexConfigImpl(
         ...(eligibility.kind === "adopt" ? { adoption: { direction: "apply" as const } } : {}),
         onPostCallbackFailure: () => {
           if (!coordinatedPreImages) throw new Error("Codex injection preimages were not captured.");
-          const restored = restoreCodexPreImages(coordinatedPreImages);
+          const restored = restoreCodexPreImages(coordinatedPreImages, heldConfigWriteLock);
           if (!restored.complete) throw new CodexPartialWriteError(restored.unrestored);
         },
         admitted: { authoritySnapshotId: witness.comparisonId },
@@ -639,10 +676,10 @@ async function injectCodexConfigImpl(
           }
           applyNativeArtifacts(resolved.plan, resolved.nativeInput);
         } catch (error) {
-          if (codexHomeOwnerBlocksCompensation(getCodexHome(), error)) throw error;
+          if (error instanceof ConfigWriteDestinationChanged || codexHomeOwnerBlocksCompensation(getCodexHome(), error)) throw error;
           // Compensate, then ALWAYS throw. Returning a partial result would let the
           // lock commit a row describing an apply that did not finish.
-          const restored = restoreCodexPreImages(preImages);
+          const restored = restoreCodexPreImages(preImages, heldConfigWriteLock);
           if (!restored.complete) {
             throw new CodexPartialWriteError(restored.unrestored);
           }
@@ -676,6 +713,10 @@ async function injectCodexConfigImpl(
     );
     transitionReceipt = coordinated.value.receipt;
   }
+  } finally {
+    releaseConfigWriteLock(configLock.handle);
+    heldConfigWriteLock = undefined;
+  }
   // Legacy mode still forward-tags history so re-tagged threads stay listable. Design B needs
   // the opposite: a one-time migration of previously re-tagged threads BACK to openai (restore
   // machinery; cheap no-op when there is nothing to migrate). The client-compaction opt-in keeps
@@ -926,6 +967,7 @@ function missingCodexConfigAdmission(): MissingCodexConfig {
  * exclusive: a file that appeared since admission belongs to another writer, and this plan,
  * derived from an absent file, must not replace it.
  */
+
 function createEmptyCodexConfigInBoundary(): void {
   try {
     closeSync(openSync(CODEX_CONFIG_PATH, "wx", 0o600));