@bitkyc08/opencodex 2.55.0 → 2.57.0

package/src/config/mutation-lock.ts

@@ -0,0 +1,244 @@
+import { Database } from "bun:sqlite";
+import { chmodSync, existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { getConfigDir } from "./paths";
+import { hardenSecretDir, windowsSecretAclApplies } from "../lib/windows-secret-acl";
+import { recordOwnedConfigPath } from "../lib/config-ownership";
+import { assertNotRealHomeUnderTest } from "../lib/test-home-guard";
+import {
+  bumpConfigGenerationAtPath,
+  bumpCurrentConfigGeneration,
+  initializeConfigGeneration,
+  observeConfigGenerationAtPath,
+  readConfigGenerationAtPath,
+  readConfigGenerationInTransaction,
+  type ConfigGenerationObservation,
+} from "../codex/generation";
+import type {
+  BumpConfigGeneration,
+  ConfigGeneration,
+  ReadConfigGeneration,
+  WithExpectedConfigGenerationSync,
+} from "../codex/convergence-types";
+
+const CONFIG_MUTATION_DB_FILENAME = "config-mutation.sqlite";
+const CONFIG_MUTATION_DB_SIDECARS = ["-journal", "-wal", "-shm"] as const;
+let warnedConfigMutationDirectoryAcl = false;
+
+export class ConfigMutationLockError extends Error {
+  readonly code = "CONFIG_MUTATION_LOCK_UNAVAILABLE";
+
+  constructor(message: string, options?: { cause?: unknown }) {
+    super(message, options);
+    this.name = "ConfigMutationLockError";
+  }
+}
+
+function configMutationDatabasePath(): string {
+  const dir = getConfigDir();
+  // First statement on purpose: a rejected mutation must leave nothing behind, not a
+  // freshly created/chmod'd directory or database. See src/lib/test-home-guard.ts.
+  assertNotRealHomeUnderTest(dir);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+  } else {
+    try { chmodSync(dir, 0o700); } catch { /* best-effort on existing dir */ }
+  }
+  if (windowsSecretAclApplies()) {
+    try {
+      // Distinct timeout memo from management-token directory harden: a required
+      // management-dir timeout must not poison config mutation on the same home
+      // (windows-latest server-management-auth cases).
+      hardenSecretDir(dir, { required: true, timeoutMemoKey: `${dir}::config-mutation` });
+    } catch (error) {
+      if (!warnedConfigMutationDirectoryAcl) {
+        warnedConfigMutationDirectoryAcl = true;
+        const diagnostics = error instanceof Error ? error.message : "ACL hardening failed";
+        console.warn(
+          `[opencodex] Config mutation coordination directory ACL hardening did not complete; continuing without it. ${diagnostics}`,
+        );
+      }
+    }
+  }
+  const path = join(dir, CONFIG_MUTATION_DB_FILENAME);
+  recordOwnedConfigPath(dir, path);
+  for (const suffix of CONFIG_MUTATION_DB_SIDECARS) {
+    recordOwnedConfigPath(dir, `${path}${suffix}`);
+  }
+  return path;
+}
+
+/** Raised when an independent config-mutation transaction is requested recursively. */
+export class NestedConfigMutationError extends Error {
+  constructor() {
+    super("prepareConfigMutationDatabasePathForWrite must not run inside withConfigMutationLockSync");
+    this.name = "NestedConfigMutationError";
+  }
+}
+
+/**
+ * Prepare the shared config-mutation database path for an independent top-level
+ * SQLite transaction. Callers must not invoke this while holding
+ * {@link withConfigMutationLockSync}; a second `BEGIN IMMEDIATE` deliberately
+ * fails busy instead of joining an uncommitted transaction.
+ *
+ * @throws {NestedConfigMutationError} If a config mutation lock is already held.
+ */
+export function prepareConfigMutationDatabasePathForWrite(): string {
+  if (configMutationLockDepth > 0) {
+    throw new NestedConfigMutationError();
+  }
+  return configMutationDatabasePath();
+}
+
+let configMutationLockDepth = 0;
+let configMutationDatabase: Database | null = null;
+
+/**
+ * Serialize synchronous config and Codex credential-generation commits across processes with an
+ * OS-backed SQLite write transaction. `busy_timeout=0` is deliberate: runtime request paths must
+ * fail immediately under contention rather than freeze the Bun event loop. Process exit releases
+ * SQLite locks without stale-owner deletion or lease recovery races.
+ *
+ * Reentrancy is limited to the current synchronous call stack; never return a Promise from `fn`.
+ */
+export function withConfigMutationLockSync<T>(fn: () => T): T {
+  if (configMutationLockDepth > 0) {
+    configMutationLockDepth += 1;
+    try {
+      return fn();
+    } finally {
+      configMutationLockDepth -= 1;
+    }
+  }
+  const path = configMutationDatabasePath();
+  let database: Database | undefined;
+  let transactionOpen = false;
+  try {
+    database = new Database(path, { create: true });
+    try { chmodSync(path, 0o600); } catch { /* platform may ignore chmod */ }
+    database.exec("PRAGMA busy_timeout = 0; BEGIN IMMEDIATE");
+    transactionOpen = true;
+    initializeConfigGeneration(database);
+  } catch (cause) {
+    if (transactionOpen) {
+      try { database?.exec("ROLLBACK"); } catch { /* close below still releases the OS lock */ }
+    }
+    try { database?.close(); } catch { /* acquisition already failed */ }
+    const code = cause && typeof cause === "object" && "code" in cause
+      ? String((cause as { code?: unknown }).code)
+      : "";
+    throw new ConfigMutationLockError(
+      code === "SQLITE_BUSY" ? "Config mutation already in progress" : "Could not acquire config mutation transaction",
+      { cause },
+    );
+  }
+
+  configMutationLockDepth = 1;
+  configMutationDatabase = database;
+  try {
+    const value = fn();
+    database.exec("COMMIT");
+    transactionOpen = false;
+    return value;
+  } catch (error) {
+    if (transactionOpen) {
+      try { database.exec("ROLLBACK"); } catch { /* close below still releases the OS lock */ }
+      transactionOpen = false;
+    }
+    throw error;
+  } finally {
+    configMutationLockDepth = 0;
+    configMutationDatabase = null;
+    try { database.close(); } catch { /* the OS lock is released with the handle */ }
+  }
+}
+
+export function bumpGenerationForCooperatingConfigWrite(): void {
+  if (!configMutationDatabase) {
+    throw new Error("A cooperating config write requires the config mutation transaction.");
+  }
+  bumpCurrentConfigGeneration(configMutationDatabase);
+}
+
+export const readConfigGeneration: ReadConfigGeneration = () => {
+  try {
+    return readConfigGenerationAtPath(configMutationDatabasePath());
+  } catch {
+    return { kind: "unavailable", reason: "database" };
+  }
+};
+
+export function observeConfigGeneration(): ConfigGenerationObservation {
+  return observeConfigGenerationAtPath(join(getConfigDir(), CONFIG_MUTATION_DB_FILENAME));
+}
+
+/**
+ * Read the generation from the transaction that is open RIGHT NOW.
+ *
+ * The observer cannot do this job. On the very first acquisition the
+ * `BEGIN IMMEDIATE` that creates the table has not committed yet, so a separate
+ * read-only connection cannot read a generation from it — measured, not
+ * assumed. A caller that compared a pre-lock observation against an observer
+ * re-read would therefore refuse every first write as stale.
+ *
+ * Throwing when no transaction is open is deliberate. Being called outside the
+ * lock is broken plumbing, and returning a typed "unavailable" would let that
+ * bug arrive disguised as an environmental failure — retried forever, on a
+ * machine where nothing is wrong.
+ */
+export function readConfigGenerationInCurrentMutationTransaction(): ConfigGeneration {
+  if (configMutationLockDepth < 1 || !configMutationDatabase) {
+    throw new Error(
+      "readConfigGenerationInCurrentMutationTransaction requires an open config mutation transaction.",
+    );
+  }
+  return readConfigGenerationInTransaction(configMutationDatabase);
+}
+
+export const bumpConfigGeneration: BumpConfigGeneration = expected => {
+  try {
+    return bumpConfigGenerationAtPath(configMutationDatabasePath(), expected);
+  } catch {
+    return { kind: "unavailable", reason: "database" };
+  }
+};
+
+function configGenerationFailureReason(error: unknown): "busy" | "database" {
+  const cause = error instanceof ConfigMutationLockError ? error.cause : error;
+  const code = cause && typeof cause === "object" && "code" in cause
+    ? String((cause as { code?: unknown }).code)
+    : "";
+  const message = cause instanceof Error ? cause.message : "";
+  return code === "SQLITE_BUSY"
+    || code === "SQLITE_LOCKED"
+    || /database (?:is|table is) locked/i.test(message)
+    ? "busy"
+    : "database";
+}
+
+export const withExpectedConfigGenerationSync: WithExpectedConfigGenerationSync = (
+  expected,
+  commit,
+) => {
+  let callbackThrew = false;
+  let callbackError: unknown;
+  try {
+    return withConfigMutationLockSync(() => {
+      const database = configMutationDatabase;
+      if (!database) throw new Error("Config mutation transaction database is unavailable.");
+      const current = readConfigGenerationInTransaction(database);
+      if (current.value !== expected.value) return { kind: "conflict", current };
+      try {
+        return { kind: "matched", generation: current, value: commit() };
+      } catch (error) {
+        callbackThrew = true;
+        callbackError = error;
+        throw error;
+      }
+    });
+  } catch (error) {
+    if (callbackThrew && error === callbackError) throw error;
+    return { kind: "unavailable", reason: configGenerationFailureReason(error) };
+  }
+};

package/src/config/openai-tier-backup.ts

@@ -0,0 +1,268 @@
+import { chmodSync, constants as fsConstants, copyFileSync, existsSync, linkSync, readFileSync, truncateSync, unlinkSync, writeFileSync } from "node:fs";
+import { getConfigPath } from "./paths";
+import { isMissingPathError, nextAtomicTempSequence } from "./atomic-write";
+import { forgetEphemeralSecretPath, hardenSecretPath } from "../lib/windows-secret-acl";
+
+export class OpenAiTierBackupCleanupError extends Error {
+  constructor() { super("OpenAI tier backup temporary cleanup failed"); this.name = "OpenAiTierBackupCleanupError"; }
+}
+
+export class OpenAiTierBackupRollbackError extends Error {
+  constructor() { super("OpenAI tier backup rollback failed"); this.name = "OpenAiTierBackupRollbackError"; }
+}
+
+export class OpenAiTierBackupCollisionError extends Error {
+  readonly configPath?: string;
+  constructor(configPath?: string) {
+    super("Existing OpenAI tier backup differs from the current config");
+    this.name = "OpenAiTierBackupCollisionError";
+    this.configPath = configPath;
+  }
+}
+
+export class OpenAiTierRollbackPreserveError extends Error {
+  readonly code?: "missing" | "not-rollback" | "mismatch" | "exhausted";
+  constructor(message: string, options?: ErrorOptions & { code?: OpenAiTierRollbackPreserveError["code"] }) {
+    super(message, options);
+    this.name = "OpenAiTierRollbackPreserveError";
+    this.code = options?.code;
+  }
+}
+
+export class OpenAiTierBackupSecretResidualError extends Error {
+  constructor(readonly tempPath: string, options?: ErrorOptions) {
+    super("OpenAI tier backup could not scrub or remove a secret-bearing temporary file", options);
+    this.name = "OpenAiTierBackupSecretResidualError";
+  }
+}
+
+export interface OpenAiTierBackupIO {
+  exists(path: string): boolean;
+  read(path: string): Uint8Array;
+  createExclusive(path: string): void;
+  write(path: string, bytes: Uint8Array): void;
+  harden(path: string): void;
+  publishNoReplace(temp: string, backup: string): void;
+  truncate(path: string): void;
+  unlink(path: string): void;
+}
+
+function sameBytes(left: Uint8Array, right: Uint8Array): boolean {
+  return left.byteLength === right.byteLength && left.every((value, index) => value === right[index]);
+}
+
+function isAlreadyExistsError(error: unknown): boolean {
+  return (error as NodeJS.ErrnoException | undefined)?.code === "EEXIST";
+}
+
+/**
+ * Classify an existing `.pre-openai-tiers-v2.bak` snapshot.
+ *
+ * - `"stale"`: unparseable JSON (not written by us / truncated) or already a
+ *   post-migration (tier v2) snapshot — safe to delete or replace.
+ * - `"rollback"`: parses as a valid pre-migration (v1) config — a
+ *   user-intentional rollback point that must never be silently destroyed.
+ *
+ * Shared by the startup migration backup path and `ocx init` cleanup so both
+ * apply the same preservation policy (issue #257 / sol review 260722).
+ */
+export function classifyOpenAiTierBackup(backupBytes: Uint8Array): "stale" | "rollback" {
+  try {
+    // Use Buffer.from to ensure proper UTF-8 decoding from Uint8Array/Buffer.
+    const parsed = JSON.parse(Buffer.from(backupBytes).toString("utf8")) as Record<string, unknown>;
+    return parsed.openaiProviderTierVersion === 2 ? "stale" : "rollback";
+  } catch {
+    // Unparseable: not a config file we created, treat as stale.
+    return "stale";
+  }
+}
+
+export function backupConfigBeforeOpenAiTierMigration(
+  configPath = getConfigPath(),
+  io: OpenAiTierBackupIO = {
+    exists: existsSync,
+    read: target => readFileSync(target),
+    createExclusive: target => { writeFileSync(target, new Uint8Array(), { flag: "wx", mode: 0o600 }); },
+    write: (target, bytes) => writeFileSync(target, bytes),
+    harden: target => {
+      try { chmodSync(target, 0o600); } catch { /* platform may ignore chmod */ }
+      // Soft-fail: a wedged/failed icacls on CI temp volumes must not abort
+      // startServer mid-suite (timeout + EBUSY cascade on shared TEST_DIR).
+      // chmod above still applies; live credential writes keep required:true.
+      if (process.platform === "win32") hardenSecretPath(target, { required: false });
+    },
+    publishNoReplace: (temp, backup) => linkSync(temp, backup),
+    truncate: target => truncateSync(target, 0),
+    unlink: unlinkSync,
+  },
+): "absent" | "created" | "reused" {
+  const source = configPath;
+  if (!io.exists(source)) return "absent";
+  const original = io.read(source);
+  // v2 snapshot path. The historical `.pre-openai-tiers-v1.bak` is read only by restore
+  // docs/fixtures and is never reused or overwritten as the v2 snapshot.
+  const backup = `${source}.pre-openai-tiers-v2.bak`;
+  if (io.exists(backup)) {
+    if (!sameBytes(original, io.read(backup))) {
+      // The backup differs from the current config. Only treat it as stale when it is
+      // clearly not a user-intentional rollback point:
+      //   - unparseable JSON: written by a different tool or truncated
+      //   - already at tier version 2: the backup is from a post-migration config (e.g.
+      //     ocx init wrote a fresh v2 config, making the old backup obsolete)
+      // A backup that parses as a valid pre-migration (v1) config is kept as-is and
+      // we throw a collision error, because silently replacing a user-created rollback
+      // point would be surprising and potentially destructive.
+      const backupBytes = io.read(backup);
+      if (classifyOpenAiTierBackup(backupBytes) === "rollback") {
+        throw new OpenAiTierBackupCollisionError(source);
+      }
+      console.warn("[openai-provider-migration] Replacing stale pre-migration backup (post-migration config was rewritten since last migration).");
+      io.unlink(backup);
+    } else {
+      return "reused";
+    }
+  }
+  const temp = `${backup}.ocx.${process.pid}.${nextAtomicTempSequence()}.tmp`;
+  let published = false;
+  let cleanupAttempted = false;
+
+  const scrubUnpublishedTemp = (): void => {
+    cleanupAttempted = true;
+    let scrubbed = false;
+    try {
+      io.truncate(temp);
+      scrubbed = true;
+    } catch (error) {
+      if (isMissingPathError(error)) scrubbed = true;
+      else {
+        try { io.write(temp, new Uint8Array()); scrubbed = true; } catch { /* removal may still succeed */ }
+      }
+    }
+    let removed = false;
+    try {
+      io.unlink(temp);
+      removed = true;
+    } catch (error) {
+      if (isMissingPathError(error)) {
+        removed = true;
+      }
+      else {
+        try { io.unlink(temp); removed = true; }
+        catch (retryError) {
+          if (isMissingPathError(retryError)) {
+            removed = true;
+          }
+        }
+      }
+    }
+    if (removed) forgetEphemeralSecretPath(temp);
+    if (!removed && !scrubbed) throw new OpenAiTierBackupSecretResidualError(temp);
+    if (!removed) throw new OpenAiTierBackupCleanupError();
+  };
+
+  try {
+    io.createExclusive(temp);
+    io.write(temp, original);
+    io.harden(temp);
+    try {
+      io.publishNoReplace(temp, backup);
+    } catch (cause) {
+      if (!isAlreadyExistsError(cause)) throw cause;
+      const winner = io.read(backup);
+      if (!sameBytes(original, winner)) throw new OpenAiTierBackupCollisionError(source);
+      scrubUnpublishedTemp();
+      return "reused";
+    }
+    published = true;
+    try {
+      io.unlink(temp);
+      forgetEphemeralSecretPath(temp);
+    } catch (firstError) {
+      if (isMissingPathError(firstError)) {
+        forgetEphemeralSecretPath(temp);
+      } else try {
+        io.unlink(temp);
+        forgetEphemeralSecretPath(temp);
+      } catch (secondError) {
+        if (isMissingPathError(secondError)) {
+          forgetEphemeralSecretPath(temp);
+          return "created";
+        }
+        // temp and backup are hard links to the same inode. Roll back the backup
+        // link before any truncation so the downgrade snapshot is never zeroed.
+        try { io.unlink(backup); } catch { throw new OpenAiTierBackupRollbackError(); }
+        published = false;
+        scrubUnpublishedTemp();
+        throw new OpenAiTierBackupCleanupError();
+      }
+    }
+    return "created";
+  } catch (cause) {
+    if (!published && !cleanupAttempted) {
+      scrubUnpublishedTemp();
+    }
+    throw cause;
+  }
+}
+
+export interface OpenAiTierRollbackPreserveIO {
+  exists(path: string): boolean;
+  read(path: string): Uint8Array;
+  copyExclusive(source: string, destination: string): void;
+  unlink(path: string): void;
+}
+
+const DEFAULT_ROLLBACK_PRESERVE_IO: OpenAiTierRollbackPreserveIO = {
+  exists: existsSync,
+  read: target => readFileSync(target),
+  copyExclusive: (source, destination) => {
+    copyFileSync(source, destination, fsConstants.COPYFILE_EXCL);
+  },
+  unlink: unlinkSync,
+};
+
+const OPENAI_TIER_ROLLBACK_PRESERVE_ATTEMPTS = 16;
+
+/**
+ * Copy a rollback-classified `.pre-openai-tiers-v2.bak` to a unique
+ * `.pre-openai-tiers-v1-rollback.<timestamp>[suffix].bak` path, then unlink the
+ * blocking v2 name. The original bytes are copied with no-replace publication;
+ * the v2 path is removed only after the copy is verified. Shared by startup
+ * migration recovery and `ocx init` cleanup so the two paths cannot drift.
+ */
+export function preserveOpenAiTierRollbackSnapshot(
+  configPath = getConfigPath(),
+  io: OpenAiTierRollbackPreserveIO = DEFAULT_ROLLBACK_PRESERVE_IO,
+): string {
+  const backup = `${configPath}.pre-openai-tiers-v2.bak`;
+  if (!io.exists(backup)) {
+    throw new OpenAiTierRollbackPreserveError("OpenAI tier rollback backup is missing", { code: "missing" });
+  }
+  const original = io.read(backup);
+  if (classifyOpenAiTierBackup(original) !== "rollback") {
+    throw new OpenAiTierRollbackPreserveError("OpenAI tier backup is not a rollback snapshot", { code: "not-rollback" });
+  }
+  for (let attempt = 0; attempt < OPENAI_TIER_ROLLBACK_PRESERVE_ATTEMPTS; attempt++) {
+    const preserved = `${configPath}.pre-openai-tiers-v1-rollback.${Date.now()}${attempt ? `-${attempt}` : ""}.bak`;
+    try {
+      io.copyExclusive(backup, preserved);
+    } catch (error) {
+      if (isAlreadyExistsError(error)) continue;
+      throw error;
+    }
+    let copied: Uint8Array;
+    try {
+      copied = io.read(preserved);
+    } catch (error) {
+      throw new OpenAiTierRollbackPreserveError("Failed to read preserved rollback snapshot", { cause: error, code: "mismatch" });
+    }
+    if (!sameBytes(original, copied)) {
+      try { io.unlink(preserved); } catch { /* keep the original backup; incomplete copy is best-effort */ }
+      throw new OpenAiTierRollbackPreserveError("Preserved rollback snapshot does not match source bytes", { code: "mismatch" });
+    }
+    io.unlink(backup);
+    return preserved;
+  }
+  throw new OpenAiTierRollbackPreserveError("Unable to find a unique rollback snapshot path", { code: "exhausted" });
+}
+

package/src/config/pending-teardown.ts

@@ -202,6 +202,37 @@ export function pendingTeardownOutstanding(): boolean {
   }
 }
 
+/**
+ * Are the outstanding obligations EXACTLY the ones this stop chose to keep?
+ *
+ * `ocx stop` can preserve its own obligations deliberately — the Codex history preflight
+ * refuses before anything is restored, so the receipt has to survive for a later stop
+ * (#4718). That is safe for an update to continue past, because the stop knows those
+ * receipts describe a proxy it just proved down.
+ *
+ * Nothing else is. A quarantined receipt is waiting on a human, and a receipt belonging
+ * to a live owner means another stop is in flight; letting either ride along would turn
+ * "we deliberately kept ours" into "we ignored everyone's". So membership is the test,
+ * not a count of ours: an unrecognized obligation of any kind answers false and the
+ * caller falls back to the ordinary failure code.
+ *
+ * Quarantined names are included in the scan on purpose. They do not correspond to any
+ * nonce this run preserved, so their presence always answers false.
+ */
+export function pendingTeardownsAreExactly(nonces: readonly string[]): boolean {
+  const expected = new Set(nonces.map(nonce => `${PREFIX}${nonce}${SUFFIX}`));
+  let names: string[];
+  try {
+    names = readdirSync(getConfigDir());
+  } catch (error) {
+    // A home that does not exist holds nothing, which matches only an empty expectation.
+    // Any other scan failure may be hiding an obligation and must not answer "exactly".
+    return (error as NodeJS.ErrnoException).code === "ENOENT" && expected.size === 0;
+  }
+  const found = names.filter(isAnyTeardownObligationFileName);
+  return found.length === expected.size && found.every(name => expected.has(name));
+}
+
 /** Paths of quarantined obligations awaiting a human. */
 export function listQuarantinedTeardowns(): string[] {
   try {

package/src/config/persist-unlocked.ts

@@ -0,0 +1,92 @@
+import { existsSync, readFileSync } from "node:fs";
+import { configReasoningPinsConfigError } from "./provider-validation";
+import type { OcxConfig } from "../types";
+import { refreshUserCostOverlays, withPreservedDiskOnlyProviders } from "../usage/user-cost-overlays";
+import { atomicWriteFile, isMissingPathError } from "./atomic-write";
+import { getConfigPath } from "./paths";
+import { configRebaseDeletionKeys, projectConfigRebaseProvenance } from "./rebase-provenance";
+import { clientConnectionSchema } from "./schema/leaf-validators";
+
+/** The literal file, with no schema merge or default injection. */
+export function readRawConfigJson(): Record<string, unknown> | undefined {
+  try {
+    const configPath = getConfigPath();
+    if (!existsSync(configPath)) return undefined;
+    const raw = readFileSync(configPath, "utf-8").replace(/^\uFEFF/, "");
+    const parsed = JSON.parse(raw) as unknown;
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return undefined;
+    return parsed as Record<string, unknown>;
+  } catch {
+    // Unreadable or corrupt: behave exactly as before. Never fail a save over protection.
+    return undefined;
+  }
+}
+
+function failClosedClientPersistenceError(
+  raw: Record<string, unknown> | undefined,
+  candidate: OcxConfig,
+): string | null {
+  if (!raw) return null;
+  const rawHasClient = Object.hasOwn(raw, "client") && raw.client !== undefined;
+  const rawRole = raw.runtimeRole;
+  const rawRoleValid = rawRole === undefined
+    || rawRole === "standalone"
+    || rawRole === "hub"
+    || rawRole === "client";
+  const rawClientValid = !rawHasClient || clientConnectionSchema.safeParse(raw.client).success;
+  const rawPairValid = rawRoleValid
+    && ((rawRole === "client" && rawHasClient && rawClientValid)
+      || (rawRole !== "client" && !rawHasClient));
+  if (rawPairValid) return null;
+
+  const candidateValid = candidate.runtimeRole === "client"
+    && clientConnectionSchema.safeParse(candidate.client).success;
+  const deletions = configRebaseDeletionKeys(candidate);
+  const explicitClear = deletions.has("client") && deletions.has("runtimeRole");
+  if (candidateValid || explicitClear) return null;
+  return "config write refused: malformed or mismatched remote client state must be repaired or explicitly cleared";
+}
+
+/**
+ * Atomic config.json write WITHOUT the mutation lock; callers must hold
+ * `withConfigMutationLockSync`. Returns true when bytes changed. Refreshes the
+ * cost-overlay registry from the persisted config so runtime estimates follow
+ * every save path.
+ */
+export function persistConfigUnlocked(config: OcxConfig): boolean {
+  const pinError = configReasoningPinsConfigError(config);
+  if (pinError) throw new Error(pinError);
+  const configPath = getConfigPath();
+  const rawBeforeWrite = readRawConfigJson();
+  const clientPersistenceError = failClosedClientPersistenceError(rawBeforeWrite, config);
+  if (clientPersistenceError) throw new Error(clientPersistenceError);
+  // External editors can add provider rows the live config deliberately does
+  // not route with yet; merge them at the serialization boundary so an
+  // unrelated in-process save cannot erase the provider or its overlay.
+  // Provider preservation reads symbol-keyed live-owner state, which structuredClone
+  // intentionally drops. Resolve that ownership before projecting JSON provenance.
+  const provenanceProjection = projectConfigRebaseProvenance(config);
+  const persisted = withPreservedDiskOnlyProviders(config);
+  if (provenanceProjection.configRebaseProvenance === undefined) delete persisted.configRebaseProvenance;
+  else persisted.configRebaseProvenance = provenanceProjection.configRebaseProvenance;
+  const bytes = JSON.stringify(persisted, null, 2) + "\n";
+  let unchanged = false;
+  try {
+    unchanged = readFileSync(configPath, "utf8") === bytes;
+  } catch (error) {
+    if (!isMissingPathError(error)) throw error;
+  }
+  // Keep the runtime overlay registry in sync with EVERY persist path,
+  // including byte-identical saves: a cooperating CLI process may have written
+  // the same bytes (e.g. before a proxy notification), and Logs/Usage must
+  // adopt the overlay without waiting for a changed save or restart.
+  if (unchanged) {
+    refreshUserCostOverlays(persisted);
+    return false;
+  }
+  atomicWriteFile(configPath, bytes);
+  // For changed saves, refresh only AFTER the write succeeded so a failed
+  // write cannot leave estimates reflecting configuration never persisted.
+  refreshUserCostOverlays(persisted);
+  return true;
+}