@yansigit/opencodex 2.36.1-dev.20260829.47 → 2.36.1-dev.20260829.48

package/src/cli/provider.ts

@@ -8,7 +8,7 @@
  *   show <name>   Show provider config details (secrets masked)
  *   set-default <name>  Change the default provider
  */
-import { hasOwnProvider, isValidProviderName, loadConfig, sanitizeModelCostsForDisplay, saveConfig } from "../config";
+import { hasOwnProvider, isValidProviderName, loadConfig, mutatePersistedConfig, sanitizeModelCostsForDisplay } from "../config";
 import { apiKeyTransportConfigError } from "../config/provider-validation";
 import { hasHelpFlag } from "./help";
 import { getProviderRegistryEntry, PROVIDER_REGISTRY } from "../providers/registry";
@@ -57,19 +57,26 @@ function maskSecret(value: string): string {
 }
 
 // ---------------------------------------------------------------------------
-// Validation helper (F1 fix: validate before saveConfig)
+// Validation helper
 // ---------------------------------------------------------------------------
 
-function validateAndSave(config: ReturnType<typeof loadConfig>): void {
+function validateProviderConfig(config: ReturnType<typeof loadConfig>): void {
   if (!config.providers || Object.keys(config.providers).length === 0) {
-    console.error("Error: config would have no providers. Aborting.");
-    process.exit(1);
+    throw new Error("config would have no providers");
   }
   if (!hasOwnProvider(config.providers, config.defaultProvider)) {
-    console.error(`Error: defaultProvider "${config.defaultProvider}" does not exist in providers. Aborting.`);
-    process.exit(1);
+    throw new Error(`defaultProvider "${config.defaultProvider}" does not exist in providers`);
+  }
+}
+
+function mutateProviderConfig<T>(mutate: (config: ReturnType<typeof loadConfig>) => { changed: boolean; value: T }): T {
+  const outcome = mutatePersistedConfig(mutate);
+  if (outcome.status === "unavailable") {
+    throw new Error(outcome.reason === "conflict"
+      ? "config changed while applying this provider update; retry"
+      : `config is ${outcome.reason}`);
   }
-  saveConfig(config);
+  return outcome.value;
 }
 
 // ---------------------------------------------------------------------------
@@ -154,19 +161,6 @@ async function handleAdd(args: string[]): Promise<void> {
   const defaultModel = consumeFlagValue(restArgs, "--default-model");
   rejectUnknownArgs(restArgs, ADD_USAGE);
 
-  const config = loadConfig();
-
-  const namespaceCollision = codexAccountNamespaceProviderCollisionError(config.codexAccountNamespaces, name);
-  if (namespaceCollision) {
-    console.error(`Error: ${namespaceCollision}.`);
-    process.exit(1);
-  }
-
-  if (hasOwnProvider(config.providers, name) && !force) {
-    console.error(`Provider "${name}" already exists. Use --force to overwrite.`);
-    process.exit(1);
-  }
-
   let provConfig: OcxProviderConfig;
   const registryEntry = getProviderRegistryEntry(name);
 
@@ -211,18 +205,21 @@ async function handleAdd(args: string[]): Promise<void> {
     provConfig.apiKeyTransport = apiKeyTransport;
   }
 
-  const existingProvider = config.providers[name];
-  config.providers[name] = provConfig;
-  // A --force overwrite rotates the key/endpoint but must not drop a
-  // user-configured price overlay (same rule as the /api/providers path and
-  // the login paths); there is no explicit clear/replace flag yet.
-  if (existingProvider?.modelCosts !== undefined && provConfig.modelCosts === undefined) {
-    provConfig.modelCosts = existingProvider.modelCosts;
-  }
   if (allowPrivateNetwork) provConfig.allowPrivateNetwork = true;
-  if (setDefault) config.defaultProvider = name;
-
-  validateAndSave(config);
+  const saved = mutateProviderConfig(config => {
+    const namespaceCollision = codexAccountNamespaceProviderCollisionError(config.codexAccountNamespaces, name);
+    if (namespaceCollision) throw new Error(`${namespaceCollision}.`);
+    const existingProvider = config.providers[name];
+    if (existingProvider && !force) throw new Error(`Provider "${name}" already exists. Use --force to overwrite.`);
+    const next = structuredClone(provConfig);
+    // A --force overwrite rotates the key/endpoint but must not drop a user-configured price overlay.
+    if (existingProvider?.modelCosts !== undefined && next.modelCosts === undefined) next.modelCosts = existingProvider.modelCosts;
+    config.providers[name] = next;
+    if (setDefault) config.defaultProvider = name;
+    validateProviderConfig(config);
+    return { changed: JSON.stringify(existingProvider) !== JSON.stringify(next) || (setDefault && config.defaultProvider === name), value: { provider: next, defaultProvider: config.defaultProvider } };
+  });
+  provConfig = saved.provider;
 
   if (wantsJson) {
     console.log(JSON.stringify({
@@ -231,7 +228,7 @@ async function handleAdd(args: string[]): Promise<void> {
       adapter: provConfig.adapter,
       baseUrl: provConfig.baseUrl,
       defaultModel: provConfig.defaultModel ?? null,
-      isDefault: config.defaultProvider === name,
+      isDefault: saved.defaultProvider === name,
       source: registryEntry ? "registry" : "custom",
       needsSync: true,
     }, null, 2));
@@ -285,42 +282,32 @@ function handleRemove(args: string[]): void {
   }
   rejectUnknownArgs(restArgs.slice(1), "Usage: ocx provider remove <name> [--json]");
 
-  const config = loadConfig();
-  if (!hasOwnProvider(config.providers, name)) {
-    console.error(`Provider "${name}" is not configured.`);
-    process.exit(1);
-  }
-
-  if (name === config.defaultProvider) {
-    console.error(`Cannot remove "${name}" — it is the default provider. Change the default first: ocx provider set-default <other>`);
-    process.exit(1);
-  }
-
-  if (Object.keys(config.providers).length <= 1) {
-    console.error("Cannot remove the last provider.");
-    process.exit(1);
-  }
-
-  const dependentCombos = Object.entries(config.combos ?? {})
-    .filter(([, combo]) => combo.targets.some(target => target.provider === name))
-    .map(([id]) => id)
-    .sort();
-  if (dependentCombos.length > 0) {
-    console.error(`Cannot remove "${name}" — combo(s) depend on it: ${dependentCombos.join(", ")}`);
-    process.exit(1);
-  }
-
-  delete config.providers[name];
-  const droppedCustomModels = dropProviderCustomModels(config, name);
-  validateAndSave(config);
+  const saved = mutateProviderConfig(config => {
+    if (!hasOwnProvider(config.providers, name)) throw new Error(`Provider "${name}" is not configured.`);
+    if (name === config.defaultProvider) throw new Error(`Cannot remove "${name}" — it is the default provider. Change the default first: ocx provider set-default <other>`);
+    if (Object.keys(config.providers).length <= 1) throw new Error("Cannot remove the last provider.");
+    const dependentCombos = Object.entries(config.combos ?? {})
+      .filter(([, combo]) => combo.targets.some(target => target.provider === name))
+      .map(([id]) => id).sort();
+    if (dependentCombos.length > 0) throw new Error(`Cannot remove "${name}" — combo(s) depend on it: ${dependentCombos.join(", ")}`);
+    const dependentProfiles = Object.entries(config.routingProfiles ?? {})
+      .filter(([, profile]) => profile.candidates.some(candidate => candidate.provider === name))
+      .map(([id]) => id).sort();
+    if (dependentProfiles.length > 0) throw new Error(`Cannot remove "${name}" — routing profile(s) depend on it: ${dependentProfiles.join(", ")}`);
+    delete config.providers[name];
+    const droppedCustomModels = dropProviderCustomModels(config, name);
+    validateProviderConfig(config);
+    return { changed: true, value: { droppedCustomModels, providers: Object.keys(config.providers), defaultProvider: config.defaultProvider } };
+  });
+  const { droppedCustomModels } = saved;
 
 
   if (wantsJson) {
     console.log(JSON.stringify({
       action: "removed",
       provider: name,
-      remainingProviders: Object.keys(config.providers),
-      defaultProvider: config.defaultProvider,
+      remainingProviders: saved.providers,
+      defaultProvider: saved.defaultProvider,
       needsSync: true,
       ...(droppedCustomModels > 0 ? { droppedCustomModels } : {}),
     }, null, 2));
@@ -396,13 +383,14 @@ function handleSetDefault(args: string[]): void {
   }
   rejectUnknownArgs(restArgs.slice(1), "Usage: ocx provider set-default <name> [--json]");
 
-  const config = loadConfig();
-  if (!hasOwnProvider(config.providers, name)) {
-    console.error(`Provider "${name}" is not configured. Add it first: ocx provider add ${name}`);
-    process.exit(1);
-  }
-
-  if (config.defaultProvider === name) {
+  const changed = mutateProviderConfig(config => {
+    if (!hasOwnProvider(config.providers, name)) throw new Error(`Provider "${name}" is not configured. Add it first: ocx provider add ${name}`);
+    if (config.defaultProvider === name) return { changed: false, value: false };
+    config.defaultProvider = name;
+    validateProviderConfig(config);
+    return { changed: true, value: true };
+  });
+  if (!changed) {
     if (wantsJson) {
       console.log(JSON.stringify({ action: "noop", provider: name, defaultProvider: name, needsSync: false }, null, 2));
     } else {
@@ -411,10 +399,6 @@ function handleSetDefault(args: string[]): void {
     return;
   }
 
-  config.defaultProvider = name;
-  validateAndSave(config);
-
-
   if (wantsJson) {
     console.log(JSON.stringify({ action: "set-default", provider: name, defaultProvider: name, needsSync: true }, null, 2));
     return;

package/src/codex/convergence.ts

@@ -1,10 +1,13 @@
 import { join } from "node:path";
 
-import { getConfigDir, saveConfigPreservingClaudeCode, websocketsEnabled, withExpectedConfigGenerationSync } from "../config";
-import { reconcileSuccessfulModelDiscoveries } from "../providers/new-model-policy";
+import { getConfigDir, mutatePersistedConfig, websocketsEnabled, withExpectedConfigGenerationSync } from "../config";
+import {
+  reconcileSuccessfulModelDiscoveries,
+  type KnownModelBaseline,
+} from "../providers/new-model-policy";
 import { COMBO_NAMESPACE } from "../combos";
 import { getAuthStorePath } from "../oauth/store";
-import type { OcxConfig } from "../types";
+import type { OcxConfig, OcxProviderConfig } from "../types";
 import { captureCatalogAdmissionSnapshot } from "./catalog-admission";
 import { legacyCustomModelCatalogSlugs } from "./custom-model-catalog-migration";
 import {
@@ -137,7 +140,22 @@ interface CandidateState {
   readonly changed: boolean;
   readonly notices: readonly CatalogNotice[];
   readonly modelEntitlements: CodexModelEntitlementSnapshot;
-  readonly discoveryConfig?: OcxConfig;
+  readonly discovery: DiscoveryEvidence;
+}
+
+interface DiscoveryEvidence {
+  readonly models: readonly { provider: string; id: string; custom?: boolean }[];
+  readonly authoritativeProviders: readonly string[];
+  readonly providerIdentities: Readonly<Record<string, string>>;
+  readonly now: string;
+}
+
+interface DiscoveryProjection {
+  readonly providers: Readonly<Record<string, Readonly<{
+    knownModel?: KnownModelBaseline;
+    recentArrivals?: readonly { id: string; at: string }[];
+  }>>>;
+  readonly disabledModelsToAdd: readonly string[];
 }
 
 const candidateStates = new WeakMap<object, CandidateState>();
@@ -145,6 +163,16 @@ function same(left: unknown, right: unknown): boolean {
   return JSON.stringify(left) === JSON.stringify(right);
 }
 
+function discoveryProviderIdentity(provider: OcxProviderConfig | undefined): string {
+  if (!provider) return "missing";
+  const row: Record<string, unknown> = { ...provider };
+  delete row.note;
+  delete row.newModelPolicy;
+  return JSON.stringify(row, (_key, value) => value && typeof value === "object" && !Array.isArray(value)
+    ? Object.fromEntries(Object.entries(value as Record<string, unknown>).sort(([left], [right]) => left.localeCompare(right)))
+    : value);
+}
+
 function targetPath(identity: string): string {
   const parsed = JSON.parse(identity) as { path?: unknown };
   if (typeof parsed.path !== "string") throw new TypeError("Catalog target identity has no path.");
@@ -441,13 +469,15 @@ export async function gatherCodexCatalogCandidate(
           : !hasRoutedEntries(source.catalog) ? source.catalog : null)
         : null);
     const discoveryConfig = structuredClone(snapshot.config) as OcxConfig;
-    const discoveryChanged = reconcileSuccessfulModelDiscoveries({
+    const authoritativeProviders = providerModelOutcomes
+      .filter(outcome => outcome.state === "authoritative")
+      .map(outcome => outcome.provider);
+    const discoveryNow = new Date().toISOString();
+    reconcileSuccessfulModelDiscoveries({
       config: discoveryConfig,
       models: routedModels,
-      authoritativeProviders: providerModelOutcomes
-        .filter(outcome => outcome.state === "authoritative")
-        .map(outcome => outcome.provider),
-      now: new Date().toISOString(),
+      authoritativeProviders,
+      now: discoveryNow,
     });
     const preparedCatalog = prepareCatalog(
       discoveryConfig,
@@ -515,7 +545,15 @@ export async function gatherCodexCatalogCandidate(
         || Buffer.from(cacheBytes ?? []).toString("utf8") !== preparedCacheBytes,
       notices: Object.freeze([...notices]),
       modelEntitlements,
-      ...(discoveryChanged ? { discoveryConfig } : {}),
+      discovery: {
+        models: routedModels,
+        authoritativeProviders,
+        providerIdentities: Object.fromEntries(authoritativeProviders.map(provider => [
+          provider,
+          discoveryProviderIdentity(snapshot.config.providers[provider]),
+        ])),
+        now: discoveryNow,
+      },
     });
     return { kind: "candidate", candidate };
   } catch (error) {
@@ -532,6 +570,63 @@ export async function gatherCodexCatalogCandidate(
   }
 }
 
+function reconcilePersistedDiscovery(state: CandidateState) {
+  return mutatePersistedConfig(config => {
+    if (state.discovery.authoritativeProviders.some(provider => (
+      discoveryProviderIdentity(config.providers[provider]) !== state.discovery.providerIdentities[provider]
+    ))) {
+      return { changed: false, value: null };
+    }
+    const disabledBefore = new Set(config.disabledModels ?? []);
+    const changed = reconcileSuccessfulModelDiscoveries({
+      config,
+      ...state.discovery,
+    });
+    const providers = Object.fromEntries(state.discovery.authoritativeProviders.flatMap(provider => {
+      const configured = config.providers[provider];
+      if (!configured || configured.liveModels === false) return [];
+      const knownModel = config.modelDiscovery?.knownModels?.[provider];
+      const recentArrivals = config.modelDiscovery?.recentArrivals?.[provider];
+      return [[provider, {
+        ...(knownModel ? { knownModel: structuredClone(knownModel) } : {}),
+        ...(recentArrivals ? { recentArrivals: structuredClone(recentArrivals) } : {}),
+      }]];
+    }));
+    return {
+      changed,
+      value: {
+        providers,
+        disabledModelsToAdd: (config.disabledModels ?? []).filter(slug => !disabledBefore.has(slug)),
+      } satisfies DiscoveryProjection,
+    };
+  });
+}
+
+function adoptDiscoveryProjection(config: OcxConfig, projection: DiscoveryProjection): void {
+  for (const [provider, discovered] of Object.entries(projection.providers)) {
+    if (discovered.knownModel) {
+      const discovery = config.modelDiscovery ??= {};
+      const knownModels = discovery.knownModels ??= {};
+      knownModels[provider] = structuredClone(discovered.knownModel);
+    } else if (config.modelDiscovery?.knownModels) {
+      delete config.modelDiscovery.knownModels[provider];
+    }
+    if (discovered.recentArrivals) {
+      const discovery = config.modelDiscovery ??= {};
+      const recentArrivals = discovery.recentArrivals ??= {};
+      recentArrivals[provider] = discovered.recentArrivals.map(arrival => ({ ...arrival }));
+    } else if (config.modelDiscovery?.recentArrivals) {
+      delete config.modelDiscovery.recentArrivals[provider];
+    }
+  }
+  if (projection.disabledModelsToAdd.length > 0) {
+    const disabledModels = config.disabledModels ??= [];
+    for (const slug of projection.disabledModelsToAdd) {
+      if (!disabledModels.includes(slug)) disabledModels.push(slug);
+    }
+  }
+}
+
 function revalidateCandidate(state: CandidateState): CodexCatalogCommitResult | null {
   if (!isCodexModelEntitlementSnapshotCurrent(state.modelEntitlements)) {
     return { kind: "stale", reason: "account-entitlement" };
@@ -663,11 +758,11 @@ export async function convergeCodexCatalog(
   const state = candidateStates.get(gathered.candidate as object)!;
   lifecycle.onCommitBegin?.();
   const committed = await commitCodexCatalogCandidate(gathered.candidate, request.deadlineMs);
-  if (committed.kind === "committed" && state.discoveryConfig) {
-    const mutable = snapshot.config as OcxConfig;
-    mutable.modelDiscovery = state.discoveryConfig.modelDiscovery;
-    mutable.disabledModels = state.discoveryConfig.disabledModels;
-    saveConfigPreservingClaudeCode(mutable);
+  if (committed.kind === "committed") {
+    const persisted = reconcilePersistedDiscovery(state);
+    if ((persisted.status === "committed" || persisted.status === "unchanged") && persisted.value) {
+      adoptDiscoveryProjection(snapshot.config as OcxConfig, persisted.value);
+    }
   }
   return {
     changed: committed.kind === "committed" ? committed.changed : false,

package/src/config.ts

@@ -96,7 +96,6 @@ import {
   isValidCost4Rate,
   refreshPreservedProviderOwner,
   refreshUserCostOverlays,
-  withPreservedDiskOnlyProviders,
 } from "./usage/user-cost-overlays";
 import { MAX_COST4_RATE } from "./usage/expected-prices";
 import {
@@ -106,6 +105,8 @@ import {
 } from "./lib/app-owned-memory";
 import { isHostedToolUnsupportedForModel } from "./responses/hosted-tool-policy";
 import {
+  AtomicWriteResidualTempError,
+  AtomicWriteSecretResidualError,
   atomicWriteFile,
   isMissingPathError,
   nextAtomicTempSequence,
@@ -2732,23 +2733,34 @@ export const withExpectedConfigGenerationSync: WithExpectedConfigGenerationSync
  * cost-overlay registry from the persisted config so runtime estimates follow
  * every save path.
  */
-function persistConfigUnlocked(config: OcxConfig): boolean {
+type PersistConfigAuthority = "ordinary" | "mutation" | "replacement";
+
+function persistConfigUnlocked(config: OcxConfig, authority: PersistConfigAuthority = "ordinary"): boolean {
   const configPath = getConfigPath();
   // Check the resolved file target before reading it: a symlink can point from an
   // isolated test home into the protected real home, where another write guard
   // must not mask this refusal based on the target's current contents.
   assertNotRealHomeUnderTest(dirname(resolveWriteTarget(configPath)));
   const raw = readRawConfigJson();
-  if (raw && configNeedsProviderRepair(raw)) {
+  if (authority !== "replacement" && raw && configNeedsProviderRepair(raw)) {
     throw new Error("refusing to overwrite a config repaired with defaults; fix the persisted config first");
   }
-  // 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 snapshot = readConfigFileSnapshot();
+  if (authority !== "replacement" && snapshot.diagnostics.source === "fallback") {
+    throw new Error("refusing to overwrite an invalid persisted config; fix the persisted config first");
+  }
+  // Automatic whole-config writes own non-provider settings only. A valid disk
+  // registry is authoritative; explicit locked mutations pass replacement
+  // authority for intentional provider/default changes.
+  const base = snapshot.diagnostics.source === "file" && authority === "ordinary"
+    ? {
+      ...config,
+      providers: snapshot.diagnostics.config.providers,
+      defaultProvider: snapshot.diagnostics.config.defaultProvider,
+    }
+    : config;
   const provenanceProjection = projectConfigRebaseProvenance(config);
-  const persisted = withPreservedDiskOnlyProviders(config);
+  const persisted = base;
   if (provenanceProjection.configRebaseProvenance === undefined) delete persisted.configRebaseProvenance;
   else persisted.configRebaseProvenance = provenanceProjection.configRebaseProvenance;
   const bytes = JSON.stringify(persisted, null, 2) + "\n";
@@ -2790,6 +2802,183 @@ export function saveConfig(config: OcxConfig): void {
   });
 }
 
+/** Replace a validated config under the shared lock for confirmed import/init flows. */
+export function replacePersistedConfig(config: OcxConfig): void {
+  assertNotRealHomeUnderTest(getConfigDir());
+  withConfigMutationLockSync(() => {
+    const projected = projectCustomModelCatalogMigration(
+      readRawConfigJson(),
+      projectConfigRebaseProvenance(config),
+    );
+    if (persistConfigUnlocked(projected, "replacement")) bumpGenerationForCooperatingConfigWrite();
+    adoptCustomModelCatalogMigration(config, projected);
+    if (projected.configRebaseProvenance === undefined) delete config.configRebaseProvenance;
+    else config.configRebaseProvenance = structuredClone(projected.configRebaseProvenance);
+    clearPendingConfigTopLevelDeletions(config);
+  });
+}
+
+export type PersistedConfigInitializationOutcome = "created" | "exists" | "invalid";
+
+export class PersistedConfigInitializationCleanupError extends Error {
+  constructor(options?: ErrorOptions) {
+    super("Initial config publication cleanup failed after rollback", options);
+    this.name = "PersistedConfigInitializationCleanupError";
+  }
+}
+
+export class PersistedConfigInitializationRollbackError extends Error {
+  constructor(options?: ErrorOptions) {
+    super("Initial config publication rollback failed", options);
+    this.name = "PersistedConfigInitializationRollbackError";
+  }
+}
+
+export interface PersistedConfigInitializationIO {
+  createExclusive(path: string): void;
+  write(path: string, bytes: string): void;
+  harden(path: string): void;
+  publishNoReplace(temp: string, target: string): void;
+  truncate(path: string): void;
+  unlink(path: string): void;
+}
+
+let persistedConfigInitializationBeforePublishForTests: (() => void) | null = null;
+
+/** Test-only one-shot seam: create a competing config after staging, before no-replace publication. */
+export function setPersistedConfigInitializationBeforePublishForTests(hook: (() => void) | null): void {
+  persistedConfigInitializationBeforePublishForTests = hook;
+}
+
+function publishInitialConfigNoReplace(
+  config: OcxConfig,
+  io: PersistedConfigInitializationIO,
+): boolean {
+  const configPath = getConfigPath();
+  const target = resolveWriteTarget(configPath);
+  assertNotRealHomeUnderTest(dirname(target));
+  recordOwnedConfigPath(getConfigDir(), configPath);
+  const persisted = projectConfigRebaseProvenance(config);
+  const bytes = JSON.stringify(persisted, null, 2) + "\n";
+  const temp = `${target}.ocx.${process.pid}.${nextAtomicTempSequence()}.tmp`;
+  let staged = false;
+  let hardened = false;
+  let published = false;
+  let cleanupAttempted = false;
+
+  const scrubUnpublishedTemp = (cause?: unknown): void => {
+    cleanupAttempted = true;
+    let scrubbed = false;
+    try {
+      io.truncate(temp);
+      scrubbed = true;
+    } catch (error) {
+      if (isMissingPathError(error)) scrubbed = true;
+      else {
+        try { io.write(temp, ""); 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 AtomicWriteSecretResidualError(temp, { cause });
+    if (!removed) throw new AtomicWriteResidualTempError(temp, hardened, { cause });
+  };
+
+  try {
+    io.createExclusive(temp);
+    staged = true;
+    io.write(temp, bytes);
+    io.harden(temp);
+    hardened = true;
+    const hook = persistedConfigInitializationBeforePublishForTests;
+    persistedConfigInitializationBeforePublishForTests = null;
+    hook?.();
+    try {
+      io.publishNoReplace(temp, target);
+    } catch (cause) {
+      if (!isAlreadyExistsError(cause)) throw cause;
+      scrubUnpublishedTemp(cause);
+      return false;
+    }
+    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);
+        } else {
+          // Both names point to one inode. Remove the published name before scrubbing.
+          try { io.unlink(target); }
+          catch (cause) { throw new PersistedConfigInitializationRollbackError({ cause }); }
+          published = false;
+          scrubUnpublishedTemp(secondError);
+          throw new PersistedConfigInitializationCleanupError({ cause: secondError });
+        }
+      }
+    }
+    refreshUserCostOverlays(persisted);
+    return true;
+  } catch (cause) {
+    if (staged && !published && !cleanupAttempted) scrubUnpublishedTemp(cause);
+    throw cause;
+  }
+}
+
+function defaultPersistedConfigInitializationIO(configPath: string): PersistedConfigInitializationIO {
+  return {
+    createExclusive: target => { writeFileSync(target, "", { flag: "wx", mode: 0o600 }); },
+    write: (target, bytes) => writeFileSync(target, bytes),
+    harden: target => {
+      try { chmodSync(target, 0o600); } catch { /* platform may ignore chmod */ }
+      if (process.platform === "win32") hardenSecretPath(target, { required: true, timeoutMemoKey: configPath });
+    },
+    publishNoReplace: (temp, target) => linkSync(temp, target),
+    truncate: target => truncateSync(target, 0),
+    unlink: unlinkSync,
+  };
+}
+
+/** Create the initial config under the shared lock, but never replace existing bytes. */
+export function initializePersistedConfigIfMissing(
+  config: OcxConfig,
+  io = defaultPersistedConfigInitializationIO(getConfigPath()),
+): PersistedConfigInitializationOutcome {
+  assertNotRealHomeUnderTest(getConfigDir());
+  return withConfigMutationLockSync(() => {
+    const snapshot = readConfigFileSnapshot();
+    if (snapshot.diagnostics.source === "file") return "exists";
+    if (snapshot.diagnostics.source !== "default") return "invalid";
+    const projected = projectCustomModelCatalogMigration(
+      readRawConfigJson(),
+      projectConfigRebaseProvenance(config),
+    );
+    if (!publishInitialConfigNoReplace(projected, io)) {
+      const winner = readConfigFileSnapshot();
+      return winner.diagnostics.source === "file" ? "exists" : "invalid";
+    }
+    bumpGenerationForCooperatingConfigWrite();
+    adoptCustomModelCatalogMigration(config, projected);
+    return "created";
+  });
+}
+
 export type PersistedConfigMutation<T> = {
   changed: boolean;
   value: T;
@@ -2799,6 +2988,13 @@ export type PersistedConfigMutationOutcome<T> =
   | { status: "committed" | "unchanged"; value: T }
   | { status: "unavailable"; reason: "missing" | "invalid" | "conflict" };
 
+export class ConfigMutationValidationError extends Error {
+  constructor(readonly validationError: string) {
+    super(`Config mutation rejected: ${validationError}`);
+    this.name = "ConfigMutationValidationError";
+  }
+}
+
 const CONFIG_MUTATION_MAX_REBASE_ATTEMPTS = 3;
 let persistedConfigMutationBeforeCommitForTests: (() => void) | null = null;
 
@@ -2871,7 +3067,9 @@ export function mutatePersistedConfig<T>(
         commitBase.diagnostics.config,
         confirmedConfig,
       );
-      if (persistConfigUnlocked(projected)) bumpGenerationForCooperatingConfigWrite();
+      const validation = validateConfigCandidate(projected);
+      if (!validation.ok) throw new ConfigMutationValidationError(validation.error);
+      if (persistConfigUnlocked(projected, "mutation")) bumpGenerationForCooperatingConfigWrite();
       return { status: "committed", value: confirmed.value };
     }
     return { status: "unavailable", reason: "conflict" };
@@ -3193,7 +3391,7 @@ function readPersistedServerBinding(
  *   conflict keeps the live value;
  * - a provider or custom-model row deleted on disk stays deleted even if stale
  *   live state edited that same row;
- * - file missing/unreadable → save what we have, no throw.
+ * - missing file → save what we have; invalid existing file → fail closed.
  *
  * Custom-model rows are merged by their stable `id`, preserving independent
  * edits and deletions across stale whole-config saves.