@bitkyc08/opencodex 2.81.0 → 2.83.0

package/src/codex/journal.ts

@@ -1,9 +1,13 @@
+import { beginCodexWriteSection, publishCodexArtifact } from "./inject/config-write-section";
 import { createHash } from "node:crypto";
+import type { AtomicWriteHooks } from "../config/atomic-write";
 import { existsSync, readFileSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 import { atomicWriteFile } from "../config";
-import { assertCodexHomeOwner, CODEX_HOME_JOURNAL_FILE, CodexHomeOwnerRefusal, opencodexHomeForInjection, readCodexHomeJournal, type CodexHomeOwnerRefusalReason } from "./codex-home-owner";
+import { assertCodexHomeOwner, codexHomeIsAbsent, CODEX_HOME_JOURNAL_FILE, CodexHomeOwnerRefusal, opencodexHomeForInjection, readCodexHomeJournal, type CodexHomeOwnerRefusalReason } from "./codex-home-owner";
 import { hasInjectedCodexRouting } from "./injected-marker";
+import { configWriteLockFailureMessage, withConfigWriteLockHeld } from "./config-write-lock";
+import type { LockHandle } from "./config-write-lock";
 import { CODEX_HOME, CODEX_CONFIG_PATH, CODEX_PROFILE_PATH } from "./paths";
 
 /**
@@ -80,6 +84,9 @@ interface Journal {
 }
 
 export interface RestoreJournalResult {
+  /** The shared config write lock was held by another opencodex writer; restore did not run. */
+  lockBusy?: true;
+  lockUnsafe?: string;
   /** An unchanged generated profile could not be restored; distinct from a preserved user edit. */
   profileRestoreFailed?: true;
   ownershipRefusal?: CodexHomeOwnerRefusalReason;
@@ -154,7 +161,7 @@ export interface WriteJournalOptions {
  * so an unclean shutdown days later replays a day-one config over the user's
  * plugins, model choice, and trusted projects.
  */
-export function writeJournal(options: WriteJournalOptions = {}): void {
+export function writeJournal(options: WriteJournalOptions = {}, hooks: AtomicWriteHooks = {}): void {
   assertCodexHomeOwner(CODEX_HOME);
   if (!existsSync(CODEX_CONFIG_PATH)) return;
   const config = options.configContent ?? readFileSync(CODEX_CONFIG_PATH, "utf-8");
@@ -185,7 +192,7 @@ export function writeJournal(options: WriteJournalOptions = {}): void {
       : { kind: "process", pid: process.pid },
     timestamp: new Date().toISOString(),
   };
-  atomicWriteFile(JOURNAL_PATH, JSON.stringify(journal));
+  atomicWriteFile(JOURNAL_PATH, JSON.stringify(journal), undefined, hooks);
 }
 
 export interface InjectedJournalOwnership {
@@ -202,6 +209,7 @@ export function markJournalInjectedState(
   config: string,
   profile: string | null,
   ownership: InjectedJournalOwnership,
+  hooks: AtomicWriteHooks = {},
 ): void {
   assertCodexHomeOwner(CODEX_HOME);
   const inspection = readCodexHomeJournal(JOURNAL_PATH);
@@ -224,7 +232,7 @@ export function markJournalInjectedState(
   journal.replacedRootWebSearch = ownership.replacedRootWebSearch ?? null;
   journal.injectedCatalogPath = ownership.injectedCatalogPath;
   journal.opencodexHome = opencodexHomeForInjection(journal.opencodexHome);
-  atomicWriteFile(JOURNAL_PATH, JSON.stringify(journal));
+  atomicWriteFile(JOURNAL_PATH, JSON.stringify(journal), undefined, hooks);
 }
 
 /**
@@ -259,19 +267,21 @@ export function journaledInjectedCatalogPath(): string | null {
   return readJournal()?.injectedCatalogPath ?? null;
 }
 
-export function removeJournal(): void {
+export function removeJournal(hooks: AtomicWriteHooks = {}): void {
   assertCodexHomeOwner(CODEX_HOME);
-  try { unlinkSync(JOURNAL_PATH); } catch { /* ignore */ }
+  hooks.validateBeforeRename?.(JOURNAL_PATH);
+  try { unlinkSync(JOURNAL_PATH); } catch { return; }
+  hooks.afterRename?.(JOURNAL_PATH);
 }
 
 /** Successful field-level native restore releases ownership while retaining recovery evidence. */
-export function releaseJournalHomeBinding(): void {
+export function releaseJournalHomeBinding(hooks: AtomicWriteHooks = {}): void {
   assertCodexHomeOwner(CODEX_HOME);
   const inspection = readCodexHomeJournal(JOURNAL_PATH);
   if (inspection.kind === "unknown") throw new CodexHomeOwnerRefusal("owner-unknown");
   if (inspection.kind === "missing" || inspection.journal.opencodexHome === undefined) return;
   delete inspection.journal.opencodexHome;
-  atomicWriteFile(JOURNAL_PATH, JSON.stringify(inspection.journal));
+  atomicWriteFile(JOURNAL_PATH, JSON.stringify(inspection.journal), undefined, hooks);
 }
 
 // Kept compatible with existing read-only callers; invalid evidence is never cleanup authority.
@@ -298,13 +308,21 @@ export function journalOwner(options: { readOnly?: boolean } = {}): JournalOwner
     : null;
 }
 
-export function restoreJournalState(): RestoreJournalResult {
+export function restoreJournalState(
+  options: { heldConfigWriteLock?: LockHandle } = {},
+): RestoreJournalResult {
+  if (codexHomeIsAbsent(CODEX_HOME)) return {
+    configRestored: false, profileRestored: false, configRewritten: false, profileRewritten: false,
+    configChanged: false, profileChanged: false, complete: false, unverified: false,
+  };
+  const locked = withConfigWriteLockHeld(CODEX_CONFIG_PATH, options.heldConfigWriteLock, held => {
   try { assertCodexHomeOwner(CODEX_HOME); }
   catch (error) {
     if (!(error instanceof CodexHomeOwnerRefusal)) throw error;
     return { configRestored: false, profileRestored: false, configRewritten: false, profileRewritten: false,
       configChanged: false, profileChanged: false, complete: false, unverified: true, ownershipRefusal: error.reason };
   }
+  beginCodexWriteSection(held);
   const journal = readJournal();
   if (!journal) {
     return { configRestored: false, profileRestored: false, configRewritten: false, profileRewritten: false,
@@ -335,13 +353,13 @@ export function restoreJournalState(): RestoreJournalResult {
   let configRewritten = false;
   let profileRewritten = false;
   if (configUnchanged && !configRestored) {
-    atomicWriteFile(CODEX_CONFIG_PATH, comparison.originalConfig);
+    publishCodexArtifact(CODEX_CONFIG_PATH, held, (path, hooks) => atomicWriteFile(path, comparison.originalConfig, undefined, hooks));
     configRestored = true;
     configRewritten = true;
   }
   if (profileUnchanged && !profileRestored) {
     if (comparison.originalProfile !== null) {
-      atomicWriteFile(CODEX_PROFILE_PATH, comparison.originalProfile);
+      publishCodexArtifact(CODEX_PROFILE_PATH, held, (path, hooks) => atomicWriteFile(path, comparison.originalProfile!, undefined, hooks));
       profileRestored = true;
       profileRewritten = true;
     } else if (existsSync(CODEX_PROFILE_PATH)) {
@@ -351,7 +369,7 @@ export function restoreJournalState(): RestoreJournalResult {
       // not be there. ENOENT is the one benign outcome: the file is already gone, which is
       // the state we wanted.
       try {
-        unlinkSync(CODEX_PROFILE_PATH);
+        publishCodexArtifact(CODEX_PROFILE_PATH, held, (path, hooks) => { hooks.validateBeforeRename?.(path); unlinkSync(path); hooks.afterRename?.(path); });
         profileRestored = true;
         profileRewritten = true;
       } catch (error) {
@@ -361,8 +379,11 @@ export function restoreJournalState(): RestoreJournalResult {
       profileRestored = true;
     }
   }
-  const complete = configRestored && profileRestored;
-  if (complete) removeJournal();
+  let complete = configRestored && profileRestored;
+  if (complete) {
+    try { publishCodexArtifact(JOURNAL_PATH, held, (_path, hooks) => removeJournal(hooks)); }
+    catch { complete = false; }
+  }
   return {
     configRestored,
     profileRestored,
@@ -374,6 +395,24 @@ export function restoreJournalState(): RestoreJournalResult {
     unverified: false,
     ...(profileUnchanged && !profileRestored ? { profileRestoreFailed: true as const } : {}),
   };
+  });
+  if (!locked.ok) {
+    // Busy is not a verdict on the journal — report it as its own fact so a
+    // caller cannot mistake it for a failed or unneeded restore. Nothing was
+    // read yet, so the changed-file fields cannot be computed.
+    return {
+      configRestored: false,
+      profileRestored: false,
+      configRewritten: false,
+      profileRewritten: false,
+      configChanged: false,
+      profileChanged: false,
+      complete: false,
+      unverified: false,
+      ...(locked.error === "unsafe" ? { lockUnsafe: configWriteLockFailureMessage(locked) } : { lockBusy: true as const }),
+    };
+  }
+  return locked.value;
 }
 
 export function restoreJournal(): boolean {
@@ -390,18 +429,21 @@ export interface ReconcileJournalOptions {
 }
 
 export function reconcileJournal(options: ReconcileJournalOptions = {}): boolean {
+  if (codexHomeIsAbsent(CODEX_HOME)) return false;
+  const locked = withConfigWriteLockHeld(CODEX_CONFIG_PATH, undefined, handle => {
   try { assertCodexHomeOwner(CODEX_HOME); }
   catch (error) {
     if (!(error instanceof CodexHomeOwnerRefusal)) throw error;
     console.error(error.message);
     return false;
   }
+  beginCodexWriteSection(handle);
   const journal = readJournal();
   if (!journal) return false;
-  const owner = journalOwner();
+  const owner = journal.owner ?? (Number.isSafeInteger(journal.pid) && journal.pid > 0 ? { kind: "process" as const, pid: journal.pid } : null);
   if (owner?.kind === "client") {
     if (options.activeClientApiKeyId === owner.apiKeyId) return false;
-    const restored = restoreJournalState();
+    const restored = restoreJournalState({ heldConfigWriteLock: handle });
     if (restored.unverified) {
       console.error("⚠️ Codex journal recovery was not verified; current configuration files and the journal were preserved.");
       return false;
@@ -425,7 +467,7 @@ export function reconcileJournal(options: ReconcileJournalOptions = {}): boolean
       return false;
     }
   }
-  const restored = restoreJournalState();
+  const restored = restoreJournalState({ heldConfigWriteLock: handle });
   if (restored.unverified) {
     console.error("⚠️ Codex journal recovery was not verified; current configuration files and the journal were preserved.");
     return false;
@@ -440,4 +482,7 @@ export function reconcileJournal(options: ReconcileJournalOptions = {}): boolean
   if (!restored.configRewritten && !restored.profileRewritten) { warnIfJournalRetained(); return false; }
   console.error(`⚠️  Previous session (PID ${pid}) did not shut down cleanly. Codex state restored from journal.`);
   return true;
+  });
+  if (!locked.ok && locked.error === "unsafe") console.error(configWriteLockFailureMessage(locked));
+  return locked.ok ? locked.value : false;
 }

package/src/codex/main-account-cache.ts

@@ -1,4 +1,5 @@
 import { createHash, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import { codexCredentialMutationEpoch } from "./credential-mutation-epoch";
 import type { StoredAccountQuota } from "./quota-types";
 import { truncateRetainedUtf8 } from "../lib/admission";
 
@@ -73,6 +74,48 @@ export function isMainQuotaWriterLive(writer: MainQuotaWriter): boolean {
     && writer.identityGeneration === mainAccountIdentityGeneration;
 }
 
+/** Proof that a dispatch used the observed main credential; process-local, never persisted. */
+export type MainQuotaDispatch = Readonly<{
+  writer: MainQuotaWriter;
+  credentialGeneration: number;
+  credentialMutationEpoch: number;
+  configGeneration: number;
+}>;
+
+// WS quota frames publish through their observer; prelude quota can only come from those frames.
+// A real HTTP fallback after a failed upgrade never invokes the observer and stays unclaimed.
+const wsObservedMainDispatches = new WeakSet<MainQuotaDispatch>();
+
+export function claimMainQuotaDispatchForWs(dispatch: MainQuotaDispatch): void {
+  wsObservedMainDispatches.add(dispatch);
+}
+
+export function isMainQuotaDispatchWsClaimed(dispatch: MainQuotaDispatch): boolean {
+  return wsObservedMainDispatches.has(dispatch);
+}
+
+/** Give a replacement physical attempt its own quota ownership without recapturing credential fences. */
+export function renewMainQuotaDispatchForAttempt(dispatch: MainQuotaDispatch): MainQuotaDispatch {
+  return { ...dispatch };
+}
+
+export function captureMainQuotaDispatch(
+  accessToken: string, accountId: string | undefined, configGeneration: number,
+): MainQuotaDispatch | undefined {
+  if (!accountId || !matchesMainQuotaCredential(accessToken, accountId)) return undefined;
+  const writer = captureMainQuotaWriter(accountId);
+  return writer ? { writer, credentialGeneration: mainQuotaCredentialGeneration,
+    credentialMutationEpoch: codexCredentialMutationEpoch(), configGeneration } : undefined;
+}
+
+export function isMainQuotaDispatchLive(dispatch: MainQuotaDispatch): boolean {
+  // Other OpenCodex-owned credential publications also advance this epoch;
+  // dropping a main quota update after any such publication is the intended safe direction.
+  return isMainQuotaWriterLive(dispatch.writer)
+    && dispatch.credentialGeneration === mainQuotaCredentialGeneration
+    && dispatch.credentialMutationEpoch === codexCredentialMutationEpoch();
+}
+
 export function getObservedMainQuotaIdentityKey(): string | undefined {
   return observedMainQuotaIdentityKey;
 }

package/src/codex/main-account.ts

@@ -510,8 +510,9 @@ async function resolveMainAccountToken(
         }
         const refresh = dependencies.refreshToken ?? refreshNativeMainGrant;
         let refreshed: OAuthCredentials;
+        if (signal.aborted) throw signal.reason;
         try {
-          refreshed = await refresh(locked.refreshToken, { signal });
+          refreshed = await refresh(locked.refreshToken, { signal: refreshTimeout });
         } catch (cause) {
           // A refusal already classified at the endpoint keeps that verdict. An injected refresh
           // threw an ordinary Error and has only its message, so prose still decides there --
@@ -535,16 +536,14 @@ async function resolveMainAccountToken(
           }
           throw new MainAccountTokenRefreshError(reason, { cause });
         }
-        // The refresh may resolve after the caller went away (an implementation that does
-        // not observe the signal, or an abort landing in the window between resolution and
-        // commit). A cancelled request's late refresh must not rewrite auth.json on behalf
-        // of a request that no longer exists -- the same fence the reauth twin applies
-        // before its own commit above.
-        if (dependencies.signal?.aborted) throw dependencies.signal.reason;
+        // Once the exchange starts, only its own timeout may abort it: a successful
+        // rotating grant retires the old refresh token. Save the only live grant before
+        // honoring caller cancellation, while retaining the external-writer guards.
         const result = persistRefreshedMainAuthJson(locked, refreshed);
         // A permitted in-flight success speaks only for its own profile and grant.
         clearMainRefreshGrantRejection(mainRefreshGrantKey(locked)!);
         if (dependencies.preserveReauth !== true) clearAccountNeedsReauth(MAIN_CODEX_ACCOUNT_ID);
+        if (dependencies.signal?.aborted) throw dependencies.signal.reason;
         return result;
       }),
       { waitMs: 30_000, signal },

package/src/codex/paths.ts

@@ -2,6 +2,7 @@ import { readFileSync, realpathSync, statSync } from "node:fs";
 import { isAbsolute, join, resolve } from "node:path";
 import { expandUserPath } from "../config";
 import { defaultCodexHome } from "./home";
+import { codexHomeIsAbsent } from "./codex-home-owner";
 
 function resolveCodexHome(): string {
   const raw = process.env.CODEX_HOME?.trim();
@@ -11,6 +12,7 @@ function resolveCodexHome(): string {
     try {
       stat = statSync(path);
     } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT" && codexHomeIsAbsent(path)) return path;
       const message = err instanceof Error ? err.message : String(err);
       throw new Error(`CODEX_HOME points to ${raw}, but that path could not be read: ${message}`);
     }

package/src/codex/prepared-home.ts

@@ -0,0 +1,18 @@
+import { mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { codexHomeIsAbsent } from "./codex-home-owner";
+
+/**
+ * Create a proven-missing home before a writer that has always created it.
+ * A failed request keeps the directory: a pathname-based removal cannot prove it
+ * still names the directory this request created, so deleting it could remove a
+ * concurrent replacement. An empty home is what Codex itself would create.
+ */
+export function prepareCodexHome(home: string, mode?: number): void {
+  if (!codexHomeIsAbsent(home)) return;
+  mkdirSync(dirname(home), { recursive: true, mode });
+  try { mkdirSync(home, { mode }); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+  }
+}

package/src/codex/prompt-journal.ts

@@ -1,3 +1,5 @@
+import { configWriteLockFailureMessage, withConfigWriteLockHeld, publishConfigWrite, watchConfigWriteTargets, publishConfigWriteTarget, type LockHandle } from "./config-write-lock";
+import { codexHomeIsAbsent } from "./codex-home-owner";
 /**
  * prompt-journal.ts — the write transaction behind the prompt-layer surface.
  *
@@ -19,6 +21,7 @@
  * concrete: crash after writing config.toml, user or Codex then edits it,
  * recovery sees a mismatch and overwrites their work with a stale image.
  */
+import type { AtomicWriteHooks } from "../config/atomic-write";
 import { existsSync, mkdirSync, openSync, closeSync, fsyncSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { createHash, randomBytes } from "node:crypto";
@@ -68,7 +71,7 @@ function fsyncDir(path: string): void {
 }
 
 /** Write at mode 0600 from creation — a later chmod leaves a readable window. */
-export function durableWrite(path: string, content: string): void {
+export function durableWrite(path: string, content: string, hooks: AtomicWriteHooks = {}): void {
   const tmp = `${path}.ocx.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
   let fd: number | undefined;
   try {
@@ -83,7 +86,9 @@ export function durableWrite(path: string, content: string): void {
     // Windows can refuse the replace with EBUSY/EPERM/EACCES while a scanner
     // still holds the target; the shared helper retries that briefly. Losing
     // this publish breaks journal restore, so it should not fail on a blink.
-    renameAtomicFile(tmp, path, undefined, "prompt-journal");
+    hooks.beforeRename?.(tmp, path);
+    renameAtomicFile(tmp, path, undefined, "prompt-journal", hooks);
+    hooks.afterRename?.(path);
     // The temp is renamed away: proven absent — release its ACL memos.
     forgetEphemeralSecretPath(tmp);
     fsyncDir(path);
@@ -108,9 +113,11 @@ export function durableWrite(path: string, content: string): void {
   }
 }
 
-export function durableDelete(path: string): void {
+export function durableDelete(path: string, hooks: AtomicWriteHooks = {}): void {
   try {
+    hooks.validateBeforeRename?.(path);
     if (existsSync(path)) unlinkSync(path);
+    hooks.afterRename?.(path);
     fsyncDir(path);
   } catch (error) {
     // Only absence is the state we wanted; every other deletion failure must
@@ -212,7 +219,7 @@ export function classify(actual: string | null, pre: string, post: string): Targ
 
 export type RecoveryOutcome =
   | { ok: true; action: "none" | "committed" | "rolled-back" }
-  | { ok: false; error: "recovery_required"; detail: string };
+  | { ok: false; error: "recovery_required" | "unsafe"; detail: string };
 
 export interface RecoveryTargets {
   configPath: string;
@@ -247,7 +254,11 @@ export function sameRecoveryPath(
 export function recoverIfNeeded(
   journalPath: string,
   expectedTargets: RecoveryTargets,
+  heldConfigWriteLock?: LockHandle,
 ): RecoveryOutcome {
+  if (codexHomeIsAbsent(dirname(expectedTargets.configPath)) && !existsSync(journalPath)) return { ok: true, action: "none" };
+  const locked = withConfigWriteLockHeld(expectedTargets.configPath, heldConfigWriteLock, held => {
+  watchConfigWriteTargets(held, [journalPath, expectedTargets.storePath]);
   const raw = readOrNull(journalPath);
   if (raw === null) return { ok: true, action: "none" };
 
@@ -285,7 +296,7 @@ export function recoverIfNeeded(
 
   if (config === "post" && store === "post") {
     try {
-      durableDelete(journalPath);
+      publishConfigWriteTarget(expectedTargets.configPath, held, journalPath, (destination, hooks) => durableDelete(destination, hooks));
     } catch (error) {
       return {
         ok: false,
@@ -307,7 +318,7 @@ export function recoverIfNeeded(
       };
     }
     try {
-      restore(expectedTargets.configPath, record.preConfigBytes);
+      publishConfigWrite(expectedTargets.configPath, held, (destination, hooks) => restore(destination, record.preConfigBytes, hooks));
     } catch (error) {
       return {
         ok: false,
@@ -325,7 +336,7 @@ export function recoverIfNeeded(
       };
     }
     try {
-      restore(expectedTargets.storePath, record.preStoreBytes);
+      publishConfigWriteTarget(expectedTargets.configPath, held, expectedTargets.storePath, (destination, hooks) => restore(destination, record.preStoreBytes, hooks));
     } catch (error) {
       return {
         ok: false,
@@ -335,7 +346,7 @@ export function recoverIfNeeded(
     }
   }
   try {
-    durableDelete(journalPath);
+    publishConfigWriteTarget(expectedTargets.configPath, held, journalPath, (destination, hooks) => durableDelete(destination, hooks));
   } catch (error) {
     return {
       ok: false,
@@ -343,10 +354,12 @@ export function recoverIfNeeded(
       detail: `rollback restored but the journal could not be removed: ${error instanceof Error ? error.message : String(error)}`,
     };
   }
-  return { ok: true, action: "rolled-back" };
+  return { ok: true, action: "rolled-back" } as RecoveryOutcome;
+  });
+  return locked.ok ? locked.value as RecoveryOutcome : { ok: false, error: locked.error === "unsafe" ? "unsafe" : "recovery_required", detail: configWriteLockFailureMessage(locked) };
 }
 
-function restore(path: string, bytes: string | null): void {
-  if (bytes === null) durableDelete(path);
-  else durableWrite(path, bytes);
+function restore(path: string, bytes: string | null, hooks: AtomicWriteHooks): void {
+  if (bytes === null) durableDelete(path, hooks);
+  else durableWrite(path, bytes, hooks);
 }

package/src/codex/prompt-layers.ts

@@ -31,6 +31,7 @@ import { dirname, join, resolve } from "node:path";
 import { createHash, randomBytes } from "node:crypto";
 import { expandUserPath } from "../config";
 import { resolveCodexHomeDir } from "./home";
+import { prepareCodexHome } from "./prepared-home";
 import {
   durableWrite,
   durableWriteExclusive,
@@ -42,6 +43,7 @@ import {
   type JournalRecord,
 } from "./prompt-journal";
 import { release, stillHeld, tryAcquire } from "./prompt-lock";
+import { configWriteLockFailureMessage, withConfigWriteLockHeld, publishConfigWrite, publishConfigWriteTarget, watchConfigWriteTargets, type LockHandle } from "./config-write-lock";
 
 // ---------------------------------------------------------------------------
 // Inventory — ONE definition, consumed by the route and the GUI alike.
@@ -644,7 +646,8 @@ export type WriteError =
   // which means another writer won a race — here nobody won and nothing landed.
   | "write_failed"
   | "recovery_required"
-  | "locked";
+  | "locked"
+  | "unsafe";
 
 export type WriteResult =
   | { ok: true; changed: boolean; snapshot: PromptLayerSnapshot }
@@ -669,24 +672,34 @@ function commit(
   revision: string,
   build: (snapshot: PromptLayerSnapshot, configBytes: string | null, storeBytes: string | null)
     => Mutation | { error: WriteError; detail?: string },
+): WriteResult {
+  for (const path of [activeConfigPath(opts), activeStorePath(opts)]) prepareCodexHome(dirname(path), 0o700);
+  return commitPrepared(opts, revision, build);
+}
+
+function commitPrepared(
+  opts: Paths | undefined,
+  revision: string,
+  build: (snapshot: PromptLayerSnapshot, configBytes: string | null, storeBytes: string | null)
+    => Mutation | { error: WriteError; detail?: string },
 ): WriteResult {
   const configPath = activeConfigPath(opts);
   const storePath = activeStorePath(opts);
   const journalPath = journalPathFor(storePath);
   const lockPath = lockPathFor(storePath);
 
-  ensureDir(configPath);
-  ensureDir(storePath);
-
   const acquired = tryAcquire(lockPath);
-  if (!acquired.ok) return { ok: false, error: "locked" };
+  if (!acquired.ok) return { ok: false, error: acquired.error, ...(acquired.error === "unsafe" ? { detail: configWriteLockFailureMessage(acquired) } : {}) };
   const handle = acquired.handle;
 
   try {
+    // Store -> config; cleanup protection starts before config acquisition.
+    const configLocked = withConfigWriteLockHeld(configPath, undefined, configHandle => {
+    watchConfigWriteTargets(configHandle, [storePath, journalPath]);
     // 1. recovery first: a journal on disk means an earlier attempt never
     //    committed, and we must not stack a second transaction on top of it.
-    const recovered = recoverJournal(journalPath, { configPath, storePath });
-    if (!recovered.ok) return { ok: false, error: "recovery_required", detail: recovered.detail };
+    const recovered = recoverJournal(journalPath, { configPath, storePath }, configHandle);
+    if (!recovered.ok) return { ok: false, error: recovered.error, detail: recovered.detail };
 
     // 2. re-read and compare against the caller's edit base.
     const configBytes = readFileOrNull(configPath);
@@ -722,7 +735,7 @@ function commit(
       preStoreBytes: storeBytes,
       postStoreBytes: nextStore,
     };
-    durableWrite(journalPath, encodeJournal(record));
+    publishConfigWriteTarget(configPath, configHandle, journalPath, (destination, hooks) => durableWrite(destination, encodeJournal(record), hooks));
 
     // 4/5. each target re-verifies ITS OWN bytes immediately before its rename,
     //      so a third party writing between step 2 and here is not overwritten.
@@ -740,24 +753,28 @@ function commit(
     try {
       if (configChanged) {
         if (hashBytes(readFileOrNull(configPath)) !== record.preConfig) {
-          return rollback(record, journalPath, "stale_revision");
+          return rollback(record, journalPath, "stale_revision", configHandle);
         }
-        if (nextConfig === null) durableDelete(configPath);
-        else durableWrite(configPath, nextConfig);
+        publishConfigWrite(configPath, configHandle, (destination, hooks) => {
+          if (nextConfig === null) durableDelete(destination, hooks);
+          else durableWrite(destination, nextConfig, hooks);
+        });
       }
       if (storeChanged) {
         if (hashBytes(readFileOrNull(storePath)) !== record.preStore) {
-          return rollback(record, journalPath, "stale_revision");
+          return rollback(record, journalPath, "stale_revision", configHandle);
         }
-        if (nextStore === null) durableDelete(storePath);
-        else durableWrite(storePath, nextStore);
+        publishConfigWriteTarget(configPath, configHandle, storePath, (destination, hooks) => {
+          if (nextStore === null) durableDelete(destination, hooks);
+          else durableWrite(destination, nextStore, hooks);
+        });
       }
     } catch (error) {
       // `rollback` is byte-hash driven and refuses to touch a file it does not
       // recognise, so it is safe to run against a partially applied pair. If it
       // cannot account for what it finds it returns recovery_required, which is the
       // honest answer — better than a silent half-write either way.
-      const undone = rollback(record, journalPath, "write_failed");
+      const undone = rollback(record, journalPath, "write_failed", configHandle);
       return { ...undone, detail: error instanceof Error ? error.message : String(error) } as WriteResult;
     }
 
@@ -768,20 +785,21 @@ function commit(
     if (finalConfig !== record.postConfig || finalStore !== record.postStore) {
       return { ok: false, error: "write_superseded" };
     }
-    if (!stillHeld(handle)) return { ok: false, error: "write_superseded" };
+    if (!stillHeld(handle) || !stillHeld(configHandle)) return { ok: false, error: "write_superseded" };
 
-    durableDelete(journalPath);   // this deletion is the commit
+    publishConfigWriteTarget(configPath, configHandle, journalPath, (destination, hooks) => durableDelete(destination, hooks));   // this deletion is the commit
     // The FULL opts, not just the two paths this transaction owns: rebuilding the
     // snapshot from a narrowed object dropped the injected variant directory, so every
     // successful write reported an empty variant list back to its caller.
     return { ok: true, changed: true, snapshot: readPromptLayers({ ...opts, configPath, storePath }) };
-  } finally {
-    release(handle);
-  }
+    });
+    return configLocked.ok ? configLocked.value as WriteResult : { ok: false, error: configLocked.error === "locked" ? "locked" : "unsafe", ...(configLocked.error !== "locked" ? { detail: configWriteLockFailureMessage(configLocked) } : {}) };
+  } finally { release(handle); }
 }
 
 /** Undo whatever landed, then drop the journal. Never touches an unknown file. */
-function rollback(record: JournalRecord, journalPath: string, error: WriteError): WriteResult {
+function rollback(record: JournalRecord, journalPath: string, error: WriteError, held: LockHandle): WriteResult {
+  try {
   const configNow = hashBytes(readFileOrNull(record.configPath));
   const storeNow = hashBytes(readFileOrNull(record.storePath));
   if (configNow !== record.preConfig && configNow !== record.postConfig) {
@@ -791,15 +809,20 @@ function rollback(record: JournalRecord, journalPath: string, error: WriteError)
     return { ok: false, error: "recovery_required", detail: record.storePath };
   }
   if (configNow === record.postConfig) {
-    if (record.preConfigBytes === null) durableDelete(record.configPath);
-    else durableWrite(record.configPath, record.preConfigBytes);
+    publishConfigWrite(record.configPath, held, (destination, hooks) => {
+      if (record.preConfigBytes === null) durableDelete(destination, hooks);
+      else durableWrite(destination, record.preConfigBytes, hooks);
+    });
   }
   if (storeNow === record.postStore) {
-    if (record.preStoreBytes === null) durableDelete(record.storePath);
-    else durableWrite(record.storePath, record.preStoreBytes);
+    publishConfigWriteTarget(record.configPath, held, record.storePath, (destination, hooks) => {
+      if (record.preStoreBytes === null) durableDelete(destination, hooks);
+      else durableWrite(destination, record.preStoreBytes, hooks);
+    });
   }
-  durableDelete(journalPath);
+  publishConfigWriteTarget(record.configPath, held, journalPath, (destination, hooks) => durableDelete(destination, hooks));
   return { ok: false, error };
+  } catch { return { ok: false, error: "recovery_required" }; }
 }
 
 /** Flip one of the five prompt toggles. */