@iislee/opencodex 2.11.0 → 2.35.0

package/src/config.ts

@@ -1,10 +1,37 @@
-import { execFileSync } from "node:child_process";
-import { randomUUID } from "node:crypto";
-import { chmodSync, copyFileSync, existsSync, linkSync, mkdirSync, readFileSync, renameSync, truncateSync, unlinkSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { join, resolve } from "node:path";
+import { createHash } from "node:crypto";
+import { chmodSync, constants as fsConstants, copyFileSync, existsSync, linkSync, mkdirSync, readFileSync, truncateSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
 import { Database } from "bun:sqlite";
 import * as z from "zod/v4";
+import { isValidProviderName, hasOwnProvider } from "./config/provider-name";
+import {
+  apiKeyTransportConfigError,
+  booleanRecordConfigError,
+  modelAdapterRecordConfigError,
+  nonBlankStringArrayConfigError,
+  normalizeNonBlankStringArray,
+  positiveIntegerConfigError,
+  positiveIntegerRecordConfigError,
+  providerBaseUrlConfigError,
+  providerHeadersConfigError,
+  reasoningSummaryDeliveryRecordConfigError,
+  upstreamHttpVersionConfigError,
+} from "./config/provider-validation";
+import {
+  bumpConfigGenerationAtPath,
+  bumpCurrentConfigGeneration,
+  initializeConfigGeneration,
+  observeConfigGenerationAtPath,
+  readConfigGenerationAtPath,
+  readConfigGenerationInTransaction,
+  type ConfigGenerationObservation,
+} from "./codex/generation";
+import type {
+  BumpConfigGeneration,
+  ConfigGeneration,
+  ReadConfigGeneration,
+  WithExpectedConfigGenerationSync,
+} from "./codex/convergence-types";
 import {
   CODEX_ACCOUNT_NAMESPACE_COMBO_ALIAS_COLLISION_ERROR,
   codexAccountNamespaceForModel,
@@ -12,234 +39,118 @@ import {
   isValidCodexAccountNamespaceTarget,
   MAIN_CODEX_ACCOUNT_NAMESPACE_TARGET,
 } from "./codex/account-namespace-match";
+import { isCodexAccountPriorityKey } from "./codex/account-priority";
+import { UPSTREAM_HOST_CIRCUIT_MAX_THRESHOLD } from "./codex/upstream-host-health";
+import {
+  adoptCustomModelCatalogMigration,
+  projectCustomModelCatalogMigration,
+} from "./codex/custom-model-catalog-migration";
+import { parseAccountPriority } from "./codex/pool-rotation";
 import { COMBO_NAMESPACE, comboConfigIssues } from "./combos/types";
+import { routingProfileIssues } from "./routing/profile";
+import { POLICY_NAMESPACE } from "./routing/profile-namespace";
 import {
-  forgetHardenedSecretPath,
+  forgetEphemeralSecretPath,
   hardenSecretDir,
   hardenSecretPath,
-  hardenSecretPathAsync,
   windowsSecretAclApplies,
 } from "./lib/windows-secret-acl";
 import { recordOwnedConfigPath } from "./lib/config-ownership";
 import { assertNotRealHomeUnderTest } from "./lib/test-home-guard";
 import { providerDestinationConfigError } from "./lib/destination-policy";
+import { redactSecretString } from "./lib/redact";
 import { openRouterRoutingConfigError } from "./providers/openrouter-routing";
+import { MODEL_ALIAS_PATTERN } from "./providers/default-aliases";
 import {
-  isWirePinnedModel,
   MODEL_ADAPTER_OVERRIDE_ALLOWED,
   OPENAI_PROVIDER_TIER_VERSION,
-  REASONING_SUMMARY_DELIVERY_VALUES,
+  pinnedWireAdapter,
+  UPSTREAM_HTTP_VERSION_VALUES,
   type OcxClaudeCodeConfig,
   type OcxConfig,
   type OcxApiKeyEntry,
   type OcxProviderConfig,
+  type FastWire,
+  type ProviderCostOverlay,
 } from "./types";
-import { isCanonicalOpenAiForwardProvider, OPENAI_CODEX_PROVIDER_ID } from "./providers/openai-tiers";
+import { OPENAI_CODEX_PROVIDER_ID } from "./providers/openai-tiers";
+import { modelAutoCompactTokenLimitsConfigError } from "./providers/auto-compact-budget";
+import { fastWireDeclarationError, hasFastWireCapabilityConflict } from "./providers/fastwire";
+import {
+  getProviderRegistryEntry,
+  providerMatchesRegistryTransport,
+  providerModelWireDefault,
+  registryModelServiceTierCapabilityApplies,
+} from "./providers/registry";
+import { resolveOpenAiVirtualModel } from "./providers/openai-virtual-models";
 import { parseDesktopProfile } from "./claude/desktop-profile";
-import { isCodexReasoningEffort, modelRecordValue } from "./reasoning-effort";
+import { isCodexReasoningEffort } from "./reasoning-effort";
+import {
+  COST4_RATE_KEYS,
+  isValidCost4Rate,
+  refreshPreservedProviderOwner,
+  refreshUserCostOverlays,
+  withPreservedDiskOnlyProviders,
+} from "./usage/user-cost-overlays";
+import { MAX_COST4_RATE } from "./usage/expected-prices";
 import {
   DEFAULT_APP_OWNED_MEMORY_BUDGET_BYTES,
   MAX_APP_OWNED_MEMORY_BUDGET_MB,
   MIN_APP_OWNED_MEMORY_BUDGET_MB,
 } from "./lib/app-owned-memory";
-
-let _atomicSeq = 0;
-
-interface AtomicRenameIO {
-  platform: NodeJS.Platform;
-  rename: (source: string, destination: string) => void;
-  sleep: (milliseconds: number) => void;
-}
-
-export function renameAtomicFile(
-  source: string,
-  destination: string,
-  io: AtomicRenameIO = {
-    platform: process.platform,
-    rename: renameSync,
-    sleep: Bun.sleepSync,
-  },
-): void {
-  for (let attempt = 0; ; attempt += 1) {
-    try {
-      io.rename(source, destination);
-      return;
-    } catch (error) {
-      const code = (error as NodeJS.ErrnoException).code;
-      const transientWindowsError = io.platform === "win32"
-        && (code === "EBUSY" || code === "EPERM" || code === "EACCES");
-      if (!transientWindowsError || attempt >= 2) throw error;
-      io.sleep(25 * (attempt + 1));
-    }
-  }
-}
-
-/**
- * Write a file atomically (temp + rename) so concurrent writers — e.g. `ocx stop` and the
- * proxy's own shutdown handler both restoring Codex — can never leave a half-written file.
- */
-export interface AtomicWriteIO {
-  write: (path: string, content: string) => void;
-  harden: (path: string) => void;
-  rename: (source: string, destination: string) => void;
-  truncate: (path: string) => void;
-  unlink: (path: string) => void;
-}
-
-export class AtomicWriteResidualTempError extends Error {
-  constructor(readonly tempPath: string, readonly hardened = true, options?: ErrorOptions) {
-    super(`Atomic config write left a ${hardened ? "hardened " : ""}zero-byte temporary file`, options);
-    this.name = "AtomicWriteResidualTempError";
-  }
-}
-
-export class AtomicWriteSecretResidualError extends Error {
-  constructor(readonly tempPath: string, options?: ErrorOptions) {
-    super("Atomic config write could not scrub or remove a secret-bearing temporary file", options);
-    this.name = "AtomicWriteSecretResidualError";
-  }
-}
-
-function isMissingPathError(error: unknown): boolean {
-  return (error as NodeJS.ErrnoException | undefined)?.code === "ENOENT";
-}
-
-export function atomicWriteFile(path: string, content: string, io: AtomicWriteIO = {
-  write: (target, value) => writeFileSync(target, value, { encoding: "utf-8", mode: 0o600 }),
-  harden: target => {
-    try { chmodSync(target, 0o600); } catch { /* platform may ignore chmod */ }
-    if (process.platform === "win32") hardenSecretPath(target, { required: true });
-  },
-  rename: renameAtomicFile,
-  truncate: target => truncateSync(target, 0),
-  unlink: unlinkSync,
-}): void {
-  recordOwnedConfigPath(resolveConfigDir(), path);
-  const tmp = `${path}.ocx.${process.pid}.${++_atomicSeq}.tmp`;
-  let hardened = false;
-  try {
-    io.write(tmp, content);
-    io.harden(tmp);
-    hardened = true;
-    io.rename(tmp, path);
-    forgetHardenedSecretPath(tmp);
-  } catch (cause) {
-    let scrubbed = false;
-    try {
-      io.truncate(tmp);
-      scrubbed = true;
-    } catch (error) {
-      if (isMissingPathError(error)) scrubbed = true;
-      else {
-        try { io.write(tmp, ""); scrubbed = true; } catch { /* removal may still succeed */ }
-      }
-    }
-    let removed = false;
-    try {
-      io.unlink(tmp);
-      removed = true;
-    } catch (error) {
-      if (isMissingPathError(error)) removed = true;
-      else {
-        try { io.unlink(tmp); removed = true; }
-        catch (retryError) { if (isMissingPathError(retryError)) removed = true; }
-      }
-    }
-    if (!removed && !scrubbed) throw new AtomicWriteSecretResidualError(tmp, { cause });
-    if (!removed && !hardened) {
-      try { io.harden(tmp); hardened = true; } catch { /* zero-byte residual is reported honestly */ }
-    }
-    if (removed) forgetHardenedSecretPath(tmp);
-    if (!removed) throw new AtomicWriteResidualTempError(tmp, hardened, { cause });
-    throw cause;
-  }
-}
-
-/** Async atomic-write I/O: harden may await icacls without blocking the event loop (#612). */
-export interface AtomicWriteAsyncIO {
-  write: (path: string, content: string) => void | Promise<void>;
-  harden: (path: string) => void | Promise<void>;
-  rename: (source: string, destination: string) => void | Promise<void>;
-  truncate: (path: string) => void | Promise<void>;
-  unlink: (path: string) => void | Promise<void>;
-}
-
-async function renameAtomicFileAsync(source: string, destination: string): Promise<void> {
-  for (let attempt = 0; ; attempt += 1) {
-    try {
-      renameSync(source, destination);
-      return;
-    } catch (error) {
-      const code = (error as NodeJS.ErrnoException).code;
-      const transientWindowsError = process.platform === "win32"
-        && (code === "EBUSY" || code === "EPERM" || code === "EACCES");
-      if (!transientWindowsError || attempt >= 2) throw error;
-      await Bun.sleep(25 * (attempt + 1));
-    }
-  }
-}
-
-/**
- * Async atomic write (#612): same temp+harden+rename and residual-temp policy as
- * atomicWriteFile, but Windows ACL harden yields the event loop. Timeout memo is keyed
- * by the final destination path (not the unique temp, not the parent directory).
- */
-export async function atomicWriteFileAsync(
-  path: string,
-  content: string,
-  io?: AtomicWriteAsyncIO,
-): Promise<void> {
-  const effective: AtomicWriteAsyncIO = io ?? {
-    write: (target, value) => writeFileSync(target, value, { encoding: "utf-8", mode: 0o600 }),
-    harden: async target => {
-      try { chmodSync(target, 0o600); } catch { /* platform may ignore chmod */ }
-      if (process.platform === "win32") {
-        await hardenSecretPathAsync(target, { required: true, timeoutMemoKey: path });
-      }
-    },
-    rename: renameAtomicFileAsync,
-    truncate: target => truncateSync(target, 0),
-    unlink: unlinkSync,
-  };
-  const tmp = `${path}.ocx.${process.pid}.${++_atomicSeq}.tmp`;
-  let hardened = false;
-  try {
-    await effective.write(tmp, content);
-    await effective.harden(tmp);
-    hardened = true;
-    await effective.rename(tmp, path);
-    forgetHardenedSecretPath(tmp);
-  } catch (cause) {
-    let scrubbed = false;
-    try {
-      await effective.truncate(tmp);
-      scrubbed = true;
-    } catch (error) {
-      if (isMissingPathError(error)) scrubbed = true;
-      else {
-        try { await effective.write(tmp, ""); scrubbed = true; } catch { /* removal may still succeed */ }
-      }
-    }
-    let removed = false;
-    try {
-      await effective.unlink(tmp);
-      removed = true;
-    } catch (error) {
-      if (isMissingPathError(error)) removed = true;
-      else {
-        try { await effective.unlink(tmp); removed = true; }
-        catch (retryError) { if (isMissingPathError(retryError)) removed = true; }
-      }
-    }
-    if (!removed && !scrubbed) throw new AtomicWriteSecretResidualError(tmp, { cause });
-    if (!removed && !hardened) {
-      try { await effective.harden(tmp); hardened = true; } catch { /* zero-byte residual is reported honestly */ }
-    }
-    if (removed) forgetHardenedSecretPath(tmp);
-    if (!removed) throw new AtomicWriteResidualTempError(tmp, hardened, { cause });
-    throw cause;
-  }
-}
+import { isHostedToolUnsupportedForModel } from "./responses/hosted-tool-policy";
+import {
+  atomicWriteFile,
+  isMissingPathError,
+  nextAtomicTempSequence,
+} from "./config/atomic-write";
+export {
+  AtomicWriteResidualTempError,
+  AtomicWriteSecretResidualError,
+  atomicWriteFile,
+  atomicWriteFileAsync,
+  renameAtomicFile,
+  resolveWriteTarget,
+  type AtomicRenameIO,
+  type AtomicWriteAsyncIO,
+  type AtomicWriteAsyncTestSeam,
+  type AtomicWriteIO,
+} from "./config/atomic-write";
+import { getConfigDir, getConfigPath, hardenConfigDir } from "./config/paths";
+export { expandUserPath, getConfigDir, getConfigPath, hardenConfigDir } from "./config/paths";
+export {
+  getPidPath,
+  getRuntimePortPath,
+  isOcxStartCommandLine,
+  ocxStartProcessCacheSizeForTests,
+  parsePidFile,
+  readAlivePid,
+  readPid,
+  readPidFileValue,
+  readRuntimePort,
+  removePid,
+  removePidIfValueIs,
+  removeRuntimePort,
+  removeRuntimePortIfPidIs,
+  setOcxStartProcessCacheForTests,
+  setOcxStartProcessProbeForTests,
+  setProcessCommandLineExecForTests,
+  setProcessCommandLinePlatformForTests,
+  sweepDeadOcxStartProcessCache,
+  verifyPidIdentity,
+  writePid,
+  writeRuntimePort,
+  type RuntimePortState,
+} from "./config/process-state";
+import {
+  clearPendingConfigTopLevelDeletions,
+  configHasRebaseProvenance,
+  configRebaseDeletionKeys,
+  CONFIG_REBASE_PROVENANCE_KEY,
+  deleteConfigTopLevelKey,
+  projectConfigRebaseProvenance,
+} from "./config/rebase-provenance";
+export { deleteConfigTopLevelKey } from "./config/rebase-provenance";
 
 export class OpenAiTierBackupCleanupError extends Error {
   constructor() { super("OpenAI tier backup temporary cleanup failed"); this.name = "OpenAiTierBackupCleanupError"; }
@@ -250,7 +161,21 @@ export class OpenAiTierBackupRollbackError extends Error {
 }
 
 export class OpenAiTierBackupCollisionError extends Error {
-  constructor() { super("Existing OpenAI tier backup differs from the current config"); this.name = "OpenAiTierBackupCollisionError"; }
+  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 {
@@ -338,7 +263,7 @@ export function backupConfigBeforeOpenAiTierMigration(
       // point would be surprising and potentially destructive.
       const backupBytes = io.read(backup);
       if (classifyOpenAiTierBackup(backupBytes) === "rollback") {
-        throw new OpenAiTierBackupCollisionError();
+        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);
@@ -346,7 +271,7 @@ export function backupConfigBeforeOpenAiTierMigration(
       return "reused";
     }
   }
-  const temp = `${backup}.ocx.${process.pid}.${++_atomicSeq}.tmp`;
+  const temp = `${backup}.ocx.${process.pid}.${nextAtomicTempSequence()}.tmp`;
   let published = false;
   let cleanupAttempted = false;
 
@@ -379,7 +304,7 @@ export function backupConfigBeforeOpenAiTierMigration(
         }
       }
     }
-    if (removed) forgetHardenedSecretPath(temp);
+    if (removed) forgetEphemeralSecretPath(temp);
     if (!removed && !scrubbed) throw new OpenAiTierBackupSecretResidualError(temp);
     if (!removed) throw new OpenAiTierBackupCleanupError();
   };
@@ -393,23 +318,23 @@ export function backupConfigBeforeOpenAiTierMigration(
     } catch (cause) {
       if (!isAlreadyExistsError(cause)) throw cause;
       const winner = io.read(backup);
-      if (!sameBytes(original, winner)) throw new OpenAiTierBackupCollisionError();
+      if (!sameBytes(original, winner)) throw new OpenAiTierBackupCollisionError(source);
       scrubUnpublishedTemp();
       return "reused";
     }
     published = true;
     try {
       io.unlink(temp);
-      forgetHardenedSecretPath(temp);
+      forgetEphemeralSecretPath(temp);
     } catch (firstError) {
       if (isMissingPathError(firstError)) {
-        forgetHardenedSecretPath(temp);
+        forgetEphemeralSecretPath(temp);
       } else try {
         io.unlink(temp);
-        forgetHardenedSecretPath(temp);
+        forgetEphemeralSecretPath(temp);
       } catch (secondError) {
         if (isMissingPathError(secondError)) {
-          forgetHardenedSecretPath(temp);
+          forgetEphemeralSecretPath(temp);
           return "created";
         }
         // temp and backup are hard links to the same inode. Roll back the backup
@@ -429,103 +354,198 @@ export function backupConfigBeforeOpenAiTierMigration(
   }
 }
 
-/**
- * Expand a leading `~` to the home directory in user-supplied paths
- * (OPENCODEX_HOME/CODEX_HOME set from GUIs/service files where no shell expanded it).
- * `~user` and `%VAR%`/`$VAR` forms pass through untouched — those belong to the shell.
- */
-export function expandUserPath(raw: string): string {
-  if (raw === "~") return homedir();
-  if (raw.startsWith("~/") || raw.startsWith("~\\")) return join(homedir(), raw.slice(2));
-  return raw;
-}
-
-let resolvedConfigDirCache: { raw: string | undefined; path: string } | null = null;
-
-function resolveConfigDir(): string {
-  const raw = process.env["OPENCODEX_HOME"]?.trim() || undefined;
-  if (resolvedConfigDirCache && resolvedConfigDirCache.raw === raw) return resolvedConfigDirCache.path;
-  const path = raw ? resolve(expandUserPath(raw)) : join(homedir(), ".opencodex");
-  resolvedConfigDirCache = { raw, path };
-  return path;
+export interface OpenAiTierRollbackPreserveIO {
+  exists(path: string): boolean;
+  read(path: string): Uint8Array;
+  copyExclusive(source: string, destination: string): void;
+  unlink(path: string): void;
 }
 
-function resolveConfigPath(): string {
-  return join(resolveConfigDir(), "config.json");
-}
+const DEFAULT_ROLLBACK_PRESERVE_IO: OpenAiTierRollbackPreserveIO = {
+  exists: existsSync,
+  read: target => readFileSync(target),
+  copyExclusive: (source, destination) => {
+    copyFileSync(source, destination, fsConstants.COPYFILE_EXCL);
+  },
+  unlink: unlinkSync,
+};
 
-function resolvePidPath(): string {
-  return join(resolveConfigDir(), "ocx.pid");
-}
+const OPENAI_TIER_ROLLBACK_PRESERVE_ATTEMPTS = 16;
 
-function resolveRuntimePortPath(): string {
-  return join(resolveConfigDir(), "runtime-port.json");
+/**
+ * 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" });
 }
 
 const warnedConfigFallbacks = new Set<string>();
+const warnedInheritedFastWireConflicts = new Set<string>();
 let lastWarningReconciledGeneration = 0;
 
 export function reconcileConfigWarningMemos(generation: number): number {
   if (generation <= lastWarningReconciledGeneration) return 0;
-  const removed = warnedConfigFallbacks.size;
+  const removed = warnedConfigFallbacks.size + warnedInheritedFastWireConflicts.size;
   warnedConfigFallbacks.clear();
+  warnedInheritedFastWireConflicts.clear();
   lastWarningReconciledGeneration = generation;
   return removed;
 }
 
+/**
+ * Bounds for the opt-in same-target 429 wait-and-retry policy. Single source of truth
+ * shared by the config schema, the load-time sanitizer, and the management write
+ * boundary. Strict, so an unknown key is rejected at every validation boundary instead
+ * of being silently ignored (the load-time sanitizer still degrades unknown keys with a
+ * warning before schema validation, so hand-edited configs keep loading).
+ */
+const retryOn429PolicySchema = z.object({
+  enabled: z.boolean().optional(),
+  attempts: z.number().int().min(1).max(20).optional(),
+  intervalMs: z.number().int().min(100).max(600_000).optional(),
+  // The effective cap for a single wait is MAX_COOLDOWN_MS (10 min) in key-failover.ts;
+  // larger configured values would be dead config.
+  maxIntervalMs: z.number().int().min(100).max(600_000).optional(),
+  respectRetryAfter: z.boolean().optional(),
+}).strict();
+
+const requestPacingRuleSchema = z.object({
+  // Keep the RPM-derived timer within the same one-hour bound as minIntervalMs.
+  requestsPerMinute: z.number().min(1 / 60).max(60_000).optional(),
+  minIntervalMs: z.number().int().min(1).max(3_600_000).optional(),
+}).strict().refine(value => value.requestsPerMinute !== undefined || value.minIntervalMs !== undefined, {
+  message: "request pacing rules need requestsPerMinute or minIntervalMs",
+});
+
+const requestPacingSchema = z.object({
+  enabled: z.boolean(),
+  requestsPerMinute: z.number().min(1 / 60).max(60_000).optional(),
+  minIntervalMs: z.number().int().min(1).max(3_600_000).optional(),
+  models: z.record(z.string().trim().min(1), requestPacingRuleSchema).optional(),
+}).strict().refine(value => value.enabled === false
+  || value.requestsPerMinute !== undefined
+  || value.minIntervalMs !== undefined
+  || (value.models !== undefined && Object.keys(value.models).length > 0), {
+  message: "enabled request pacing needs a provider rule or model override",
+});
+
+export function requestPacingConfigError(value: unknown): string | null {
+  if (value === undefined) return null;
+  const parsed = requestPacingSchema.safeParse(value);
+  if (parsed.success) return null;
+  return "requestPacing must contain enabled and a valid requestsPerMinute/minIntervalMs provider rule or model overrides";
+}
+
+const fastWireSchema = z.object({
+  kind: z.string(),
+  canonicalToWire: z.record(z.string().trim(), z.string().trim()),
+  foreignCallerTiers: z.string(),
+  betas: z.array(z.string().trim()).optional(),
+}).strict().superRefine((fastWire, ctx) => {
+  const error = fastWireDeclarationError({ fastWire });
+  if (error) ctx.addIssue({ code: "custom", message: error });
+}).transform(fastWire => fastWire as FastWire);
+
+/**
+ * Zod schema for one provider entry: known fields are validated strictly while unknown
+ * fields pass through (preserved for runtime extensions).
+ */
 const providerConfigSchema = z.object({
   adapter: z.string().min(1),
   baseUrl: z.string().min(1),
+  alias: z.string().optional(),
+  modelAliases: z.record(z.string(), z.string()).optional(),
+  defaultAliases: z.boolean().optional(),
+  requestPacing: requestPacingSchema.optional().catch(undefined),
   mcpMaxTools: z.number().int().positive().optional(),
   mcpMaxSchemaBytes: z.number().int().positive().optional(),
   mcpMaxResultBytes: z.number().int().positive().optional(),
   apiKeyTransport: z.enum(["x-api-key", "bearer"]).optional(),
   responsesPath: z.string().min(1).optional(),
   statelessResponses: z.boolean().optional(),
+  requiresAdjacentResponsesToolResults: z.boolean().optional(),
+  fastWire: fastWireSchema.nullable().optional(),
+  supportsServiceTier: z.boolean().optional(),
+  modelSupportsServiceTier: z.record(z.string().min(1), z.boolean()).optional(),
+  preserveResponsesReasoningContent: z.boolean().optional(),
+  decodesNativeCompactionBlobs: z.boolean().optional(),
   allowPrivateNetwork: z.boolean().optional(),
+  // The management API accepts `null` as "clear this", so a config written before the POST
+  // canonicalization below can hold one on disk. Rejecting it here would send the operator
+  // through invalid-config recovery for a value the API told them was fine.
+  upstreamHttpVersion: z.enum(UPSTREAM_HTTP_VERSION_VALUES)
+    .nullish()
+    .transform(value => value ?? undefined),
+  directGeminiWireRenames: z.boolean().optional(),
+  noStructuredOutputModels: z.array(z.string().min(1))
+    .transform(normalizeNonBlankStringArray)
+    .optional(),
+  retryOn429: retryOn429PolicySchema.optional(),
   codexAccountMode: z.enum(["pool", "direct"]).optional(),
+  // Validated rather than passed through: this schema ends in `.passthrough()`, so an
+  // undeclared key survives verbatim. A misspelled `codexToolMode` therefore used to be
+  // accepted, persisted, and then silently resolved to the `code_mode_only` default — the
+  // operator asked for shell mode, got code mode, and was told nothing (#2106).
+  codexToolMode: z.enum(["code_mode_only", "shell"]).optional(),
   responsesItemIdRepair: z.object({
     message: z.array(z.string().min(1)).optional(),
     reasoning: z.array(z.string().min(1)).optional(),
     repairMissingTerminalIds: z.boolean().optional(),
+    repairInvalidIds: z.boolean().optional(),
   }).strict().optional(),
+  responsesSnapshotRepair: z.boolean().optional(),
 }).passthrough();
 
-const RESERVED_PROVIDER_NAMES = new Set(["__proto__", "prototype", "constructor"]);
-const PROVIDER_NAME_PATTERN = /^[A-Za-z0-9](?:[A-Za-z0-9._-]{0,62}[A-Za-z0-9])?$/;
-const HEADER_NAME_PATTERN = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/;
-const SENSITIVE_PROVIDER_HEADERS = new Set([
-  "authorization",
-  "cookie",
-  "set-cookie",
-  "proxy-authorization",
-  "x-api-key",
-  "x-goog-api-key",
-  "x-amz-security-token",
-]);
-
-export function isValidProviderName(name: string): boolean {
-  const trimmed = name.trim();
-  return trimmed === name
-    && PROVIDER_NAME_PATTERN.test(name)
-    && !RESERVED_PROVIDER_NAMES.has(name.toLowerCase());
-}
-
-export function hasOwnProvider(providers: Record<string, unknown>, name: string): boolean {
-  return Object.prototype.hasOwnProperty.call(providers, name);
-}
-
-export function providerBaseUrlConfigError(baseUrl: string): string | null {
-  try {
-    const parsed = new URL(baseUrl.trim());
-    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return "baseUrl must be an http(s) URL";
-    if (parsed.username || parsed.password) return "baseUrl must not include embedded credentials";
-    if (parsed.search || parsed.hash) return "baseUrl must not include query strings or fragments";
-  } catch {
-    return "baseUrl must be a valid URL";
-  }
-  return null;
-}
+export { isValidProviderName, hasOwnProvider } from "./config/provider-name";
+export {
+  apiKeyTransportConfigError,
+  booleanRecordConfigError,
+  modelAdapterRecordConfigError,
+  nonBlankStringArrayConfigError,
+  normalizeNonBlankStringArray,
+  positiveIntegerConfigError,
+  positiveIntegerRecordConfigError,
+  providerBaseUrlConfigError,
+  providerHeadersConfigError,
+  reasoningSummaryDeliveryRecordConfigError,
+  upstreamHttpVersionConfigError,
+} from "./config/provider-validation";
 
 function providerResponsesPathConfigError(responsesPath: string | undefined): string | null {
   if (responsesPath === undefined) return null;
@@ -539,128 +559,164 @@ function providerResponsesPathConfigError(responsesPath: string | undefined): st
   return null;
 }
 
-export function providerHeadersConfigError(headers: unknown): string | null {
-  if (headers === undefined) return null;
-  if (!headers || typeof headers !== "object" || Array.isArray(headers)) return "headers must be an object";
-  for (const [name, value] of Object.entries(headers)) {
-    const normalized = name.trim().toLowerCase();
-    if (!normalized || !HEADER_NAME_PATTERN.test(name)) return "headers must use valid HTTP header names";
-    if (SENSITIVE_PROVIDER_HEADERS.has(normalized)) return `headers must not include sensitive header "${name}"; use apiKey/authMode instead`;
-    if (typeof value !== "string") return `header "${name}" value must be a string`;
-    if (/[\r\n]/.test(value)) return `header "${name}" value must not include line breaks`;
-  }
-  return null;
-}
-
-/** Keep the configured API-key header style scoped to Anthropic-compatible key auth. */
-export function apiKeyTransportConfigError(
-  provider: Pick<OcxProviderConfig, "adapter" | "authMode" | "apiKeyTransport">,
-): string | null {
-  if (provider.apiKeyTransport === undefined) return null;
-  if (provider.apiKeyTransport !== "x-api-key" && provider.apiKeyTransport !== "bearer") {
-    return 'apiKeyTransport must be "x-api-key" or "bearer"';
-  }
-  if (provider.adapter !== "anthropic") {
-    return "apiKeyTransport is supported only by the anthropic adapter";
-  }
-  if (provider.authMode === "oauth" || provider.authMode === "forward" || provider.authMode === "local") {
-    return "apiKeyTransport requires Anthropic API-key authentication";
-  }
-  return null;
-}
-
-export function positiveIntegerRecordConfigError(value: unknown, field: string): string | null {
+/**
+ * Validate `providers.<name>.modelCosts`: a plain object keyed by exact model
+ * id, each value a 4-tuple of non-negative finite USD-per-1M-token rates.
+ * Returns null when valid/absent, else a human-readable error.
+ */
+export function providerModelCostsConfigError(value: unknown, field = "modelCosts"): string | null {
   if (value === undefined) return null;
-  if (!value || typeof value !== "object" || Array.isArray(value)) return `${field} must be a plain object`;
-  const prototype = Object.getPrototypeOf(value);
-  if (prototype !== Object.prototype && prototype !== null) return `${field} must be a plain object with own properties`;
-  for (const [key, entry] of Object.entries(value)) {
-    if (!key.trim()) return `${field} keys must be nonblank model ids`;
-    if (typeof entry !== "number" || !Number.isFinite(entry) || !Number.isInteger(entry) || entry <= 0) {
-      return `${field}.${key} must be a positive finite integer`;
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return `${field} must be a plain object keyed by model id`;
+  }
+  for (const [modelId, entry] of Object.entries(value)) {
+    if (!modelId.trim()) return `${field} keys must be nonblank model ids`;
+    // Redact secret-shaped model ids and JSON-escape control characters so a
+    // malformed write cannot echo a pasted key/secret back through the
+    // management API response.
+    const safeModelId = JSON.stringify(redactSecretString(modelId));
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+      return `${field}.${safeModelId} must be an object with input, output, cacheRead, and cacheWrite (USD per 1M tokens)`;
     }
-  }
-  return null;
-}
-
-export function positiveIntegerConfigError(value: unknown, field: string): string | null {
-  if (value === undefined) return null;
-  if (typeof value !== "number" || !Number.isFinite(value) || !Number.isInteger(value) || value <= 0) {
-    return `${field} must be a positive finite integer`;
-  }
-  return null;
-}
-
-export function booleanRecordConfigError(value: unknown, field: string): string | null {
-  if (value === undefined) return null;
-  if (!value || typeof value !== "object" || Array.isArray(value)) return `${field} must be a plain object`;
-  const prototype = Object.getPrototypeOf(value);
-  if (prototype !== Object.prototype && prototype !== null) return `${field} must be a plain object with own properties`;
-  for (const [key, entry] of Object.entries(value)) {
-    if (!key.trim()) return `${field} keys must be nonblank model ids`;
-    if (typeof entry !== "boolean") return `${field}.${key} must be a boolean`;
-  }
-  return null;
-}
-
-const REASONING_SUMMARY_DELIVERY_SET = new Set<string>(REASONING_SUMMARY_DELIVERY_VALUES);
-
-export function reasoningSummaryDeliveryRecordConfigError(
-  value: unknown,
-  supportsReasoningSummaries: unknown,
-  field = "modelReasoningSummaryDelivery",
-): string | null {
-  if (value === undefined) return null;
-  if (!value || typeof value !== "object" || Array.isArray(value)) return `${field} must be a plain object`;
-  const prototype = Object.getPrototypeOf(value);
-  if (prototype !== Object.prototype && prototype !== null) return `${field} must be a plain object with own properties`;
-
-  const supports = booleanRecordConfigError(supportsReasoningSummaries, "modelSupportsReasoningSummaries") === null
-    && supportsReasoningSummaries && typeof supportsReasoningSummaries === "object"
-    ? supportsReasoningSummaries as Record<string, boolean>
-    : undefined;
-  for (const [key, entry] of Object.entries(value)) {
-    if (!key.trim()) return `${field} keys must be nonblank model ids`;
-    if (typeof entry !== "string" || !REASONING_SUMMARY_DELIVERY_SET.has(entry)) {
-      return `${field}.${key} must be one of: ${REASONING_SUMMARY_DELIVERY_VALUES.join(", ")}`;
+    const rates = entry as Record<string, unknown>;
+    for (const key of COST4_RATE_KEYS) {
+      const rate = rates[key];
+      if (!isValidCost4Rate(rate)) {
+        return `${field}.${safeModelId}.${key} must be a non-negative finite number at most ${MAX_COST4_RATE} (USD per 1M tokens)`;
+      }
     }
-    if (modelRecordValue(supports, key) === false) {
-      return `${field}.${key} conflicts with modelSupportsReasoningSummaries=false`;
+    // Reject unknown fields: a misplaced apiKey/apiKeyPool under a cost row
+    // would otherwise be persisted and echoed verbatim by display paths that
+    // mask only top-level provider secrets.
+    const extraKeys = Object.keys(rates)
+      .filter((key) => !(COST4_RATE_KEYS as readonly string[]).includes(key));
+    if (extraKeys.length > 0) {
+      return `${field}.${safeModelId} has unexpected fields ${JSON.stringify(extraKeys.map(redactSecretString).join(", "))} — only input, output, cacheRead, and cacheWrite are allowed (USD per 1M tokens)`;
     }
   }
   return null;
 }
 
 /**
- * Validate a provider's per-model wire override map (#404).
- *
- * Rejects, rather than silently ignoring, configurations the resolver would refuse:
- * a value outside the allowed wires, a model the upstream pins to one wire, and any
- * override on a canonical forward provider (where switching wires would drop the
- * caller's forwarded credential). Silently dropping them would leave the user
- * believing an override is in effect.
+ * Serialize `providers.<name>.modelCosts` for display: copy ONLY the four
+ * numeric rate fields per model and DROP secret-shaped model ids, so a pasted
+ * API key in a key position cannot be echoed back by CLI/DTO display paths.
+ * The result uses a null prototype so "__proto__" remains an own row.
  */
-export function modelAdapterRecordConfigError(
+export function sanitizeModelCostsForDisplay(costs: unknown): Record<string, ProviderCostOverlay> | undefined {
+  if (!costs || typeof costs !== "object" || Array.isArray(costs)) return undefined;
+  const out = Object.create(null) as Record<string, ProviderCostOverlay>;
+  for (const [modelId, entry] of Object.entries(costs)) {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) continue;
+    const rates = entry as Record<string, unknown>;
+    const input = rates.input;
+    const output = rates.output;
+    const cacheRead = rates.cacheRead;
+    const cacheWrite = rates.cacheWrite;
+    if (
+      isValidCost4Rate(input)
+      && isValidCost4Rate(output)
+      && isValidCost4Rate(cacheRead)
+      && isValidCost4Rate(cacheWrite)
+    ) {
+      // Secret-shaped ids are DROPPED rather than mapped to "[REDACTED]" so
+      // distinct rows cannot collapse into one placeholder key.
+      if (redactSecretString(modelId) !== modelId) continue;
+      out[modelId] = { input, output, cacheRead, cacheWrite };
+    }
+  }
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
+const SUPPORTED_PREFERRED_HOSTED_TOOLS = new Set(["image_generation"]);
+
+export function modelPreferHostedToolsConfigError(
   value: unknown,
   field: string,
   providerName: string,
-  provider: { adapter?: unknown; authMode?: unknown; baseUrl?: unknown },
+  provider: { adapter?: unknown; authMode?: unknown; modelAdapters?: unknown; baseUrl?: unknown },
 ): string | null {
   if (value === undefined) return null;
   if (!value || typeof value !== "object" || Array.isArray(value)) return `${field} must be a plain object`;
   const prototype = Object.getPrototypeOf(value);
   if (prototype !== Object.prototype && prototype !== null) return `${field} must be a plain object with own properties`;
   const entries = Object.entries(value);
-  if (entries.length > 0 && isCanonicalOpenAiForwardProvider(provider as OcxProviderConfig)) {
-    return `${field} is not supported on the canonical ChatGPT forward provider`;
-  }
+  const registry = getProviderRegistryEntry(providerName);
+  // Effective transport: a `preserveCustomDestination` registry row reused under a
+  // different endpoint keeps its own adapter AND its own auth at runtime, because
+  // `routedProviderConfig()` honors `providerMatchesRegistryTransport()`. Both the
+  // wire check below and the forward-auth check here have to start from the same
+  // decision, or validation accepts a preference the adapter never applies —
+  // `preferConfiguredHostedTools()` runs only on the non-forward branch.
+  const registryTransportMatches = typeof provider.baseUrl === "string"
+    && providerMatchesRegistryTransport(providerName, {
+      baseUrl: provider.baseUrl,
+      adapter: provider.adapter as OcxProviderConfig["adapter"],
+      ...(typeof provider.authMode === "string" ? { authMode: provider.authMode as OcxProviderConfig["authMode"] } : {}),
+    });
+  const effectiveForwardAuth = registryTransportMatches
+    ? registry?.authKind === "forward"
+    : provider.authMode === "forward";
+  if (entries.length > 0 && effectiveForwardAuth) {
+    return `${field} is not supported on forward-auth Responses providers`;
+  }
+  const requestedWireFor = (modelId: string): unknown => provider.modelAdapters
+    && typeof provider.modelAdapters === "object"
+    && !Array.isArray(provider.modelAdapters)
+    ? (provider.modelAdapters as Record<string, unknown>)[modelId]
+    : undefined;
+  const resolveEffectiveWire = (modelId: string, currentWire: unknown): unknown => {
+    const pinned = pinnedWireAdapter(providerName, modelId);
+    if (pinned) return pinned;
+    const requestedWire = requestedWireFor(modelId);
+    if (typeof requestedWire === "string" && MODEL_ADAPTER_OVERRIDE_ALLOWED.has(requestedWire)) {
+      return requestedWire;
+    }
+    // No explicit override: fall back to the registry's per-model wire default before
+    // the provider-wide adapter, because that is the order `resolveModelAdapter()`
+    // uses at request time (src/server/adapter-resolve.ts:38-48). Skipping it rejected
+    // preferences the runtime would have honored — DeepSeek routes `deepseek-v4-flash`
+    // over native Responses for a Responses inbound while the provider-wide wire stays
+    // openai-chat. Hosted-tool preferences only apply to Responses traffic, so the
+    // inbound to ask about is "responses".
+    const registryDefault = typeof currentWire === "string" && typeof provider.baseUrl === "string"
+      ? providerModelWireDefault(
+        providerName,
+        {
+          baseUrl: provider.baseUrl,
+          adapter: currentWire,
+          ...(typeof provider.authMode === "string" ? { authMode: provider.authMode as OcxProviderConfig["authMode"] } : {}),
+        },
+        modelId,
+        MODEL_ADAPTER_OVERRIDE_ALLOWED,
+        "responses",
+      )
+      : undefined;
+    return registryDefault ?? currentWire;
+  };
   for (const [key, entry] of entries) {
     if (!key.trim()) return `${field} keys must be nonblank model ids`;
-    if (typeof entry !== "string" || !MODEL_ADAPTER_OVERRIDE_ALLOWED.has(entry)) {
-      return `${field}.${key} must be one of: ${[...MODEL_ADAPTER_OVERRIDE_ALLOWED].join(", ")}`;
+    if (!Array.isArray(entry)) return `${field}.${key} must be an array`;
+    if (entry.length === 0) return `${field}.${key} must include image_generation`;
+    for (const tool of entry) {
+      if (typeof tool !== "string" || !SUPPORTED_PREFERRED_HOSTED_TOOLS.has(tool)) {
+        return `${field}.${key} supports only image_generation`;
+      }
+      if (isHostedToolUnsupportedForModel(key, tool)) {
+        return `${field}.${key} cannot prefer ${tool}: the model does not support it`;
+      }
     }
-    if (isWirePinnedModel(providerName, key.trim())) {
-      return `${field}.${key} cannot be overridden: the upstream only speaks one wire for this model`;
+    // Same `registryTransportMatches` decision the forward-auth check above uses:
+    // start from the registry adapter only when this config still points at the
+    // registry's documented transport.
+    const baseWire = registryTransportMatches ? registry?.adapter ?? provider.adapter : provider.adapter;
+    let effectiveWire = resolveEffectiveWire(key, baseWire);
+    const virtualWireModel = resolveOpenAiVirtualModel(providerName, key)?.wireModelId;
+    if (virtualWireModel && virtualWireModel !== key) {
+      effectiveWire = resolveEffectiveWire(virtualWireModel, effectiveWire);
+    }
+    if (effectiveWire !== "openai-responses") {
+      return `${field}.${key} requires the openai-responses wire`;
     }
   }
   return null;
@@ -712,6 +768,33 @@ const codexAccountNamespacesSchema = z.custom<Record<string, unknown>>(
   }
 }).pipe(z.record(z.string(), z.string()));
 
+const CODEX_ACCOUNT_PRIORITIES_RECORD_ERROR =
+  "codexAccountPriorities must be a plain object mapping Codex account ids to selection-order integers";
+const CODEX_ACCOUNT_PRIORITY_KEY_ERROR =
+  "selection-order keys must be a Codex pool-account id or the main Codex account and cannot be reserved JavaScript object keys";
+const CODEX_ACCOUNT_PRIORITY_VALUE_ERROR =
+  "selection order must be an integer between -100 and 100";
+
+const CODEX_ACCOUNT_PIN_PATTERN = /^[a-zA-Z0-9._-]{1,64}$/;
+
+const codexAccountPrioritiesSchema = z.custom<Record<string, unknown>>(
+  (value): value is Record<string, unknown> => !!value
+    && typeof value === "object"
+    && !Array.isArray(value)
+    && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null),
+  { error: CODEX_ACCOUNT_PRIORITIES_RECORD_ERROR },
+).superRefine((priorities, ctx) => {
+  // Inspect raw own entries before z.record parses them; Zod omits __proto__ record keys.
+  for (const [accountId, priority] of Object.entries(priorities)) {
+    if (!isCodexAccountPriorityKey(accountId)) {
+      ctx.addIssue({ code: "custom", path: [accountId], message: CODEX_ACCOUNT_PRIORITY_KEY_ERROR });
+    }
+    if (parseAccountPriority(priority) === null) {
+      ctx.addIssue({ code: "custom", path: [accountId], message: CODEX_ACCOUNT_PRIORITY_VALUE_ERROR });
+    }
+  }
+}).pipe(z.record(z.string(), z.number().int()));
+
 /**
  * Deliberately permissive. A user's config is not ours to invalidate: a strict
  * entry fails the whole parse, and loadConfig's fallback then backs the file up
@@ -742,9 +825,37 @@ const apiKeyEntrySchema = z.object({
   createdAt: z.string().catch(""),
 }).passthrough();
 
+/**
+ * Durable per-client intent.
+ *
+ * `.passthrough()` is load-bearing: a binary that only knows `codex` must not
+ * erase a key a later version wrote during a field-scoped mutation. And each key
+ * degrades on its own — a hand edit of `{"codex": "false", "future": false}`
+ * drops `codex` to absent (which reads as ON) and keeps `future`, rather than
+ * invalidating the object or, worse, the whole config.
+ */
+const clientIntegrationsSchema = z.object({
+  codex: z.boolean().optional().catch(undefined),
+  grok: z.boolean().optional().catch(undefined),
+  "claude-desktop": z.boolean().optional().catch(undefined),
+}).passthrough();
+
+const agentTaskRecoverySchema = z.object({
+  enabled: z.boolean().optional(),
+  model: z.string().trim().min(1).optional(),
+  timeoutMs: z.number().int().min(1_000).max(120_000).optional(),
+  cacheEntries: z.number().int().min(1).max(512).optional(),
+}).strict();
+
 const configSchema = z.object({
   port: z.number().int().min(0).max(65535).default(10100),
   managementUsageMaxReadBytes: z.number().int().positive().default(64 * 1024 * 1024),
+  // Invalid hand edits disable only this opt-in circuit. Live writes remain strict.
+  upstreamHostCircuitThreshold: z.number().int()
+    .min(0)
+    .max(UPSTREAM_HOST_CIRCUIT_MAX_THRESHOLD)
+    .optional()
+    .catch(undefined),
   appOwnedMemoryBudgetMb: z.number().int()
     .min(MIN_APP_OWNED_MEMORY_BUDGET_MB)
     .max(MAX_APP_OWNED_MEMORY_BUDGET_MB)
@@ -757,15 +868,34 @@ const configSchema = z.object({
   // is safe: startServer() already falls back to 127.0.0.1 for a missing hostname. Write-time
   // rejection lives in validateConfigCandidate() so bad values still surface to the caller.
   hostname: z.string().trim().min(1).optional().catch(undefined),
+  // Discriminated on `enabled` so a disabled entry cannot be forced to carry a port, and an
+  // enabled one cannot omit it (#1102). A malformed value degrades to undefined rather than
+  // failing the whole parse: this is an opt-in convenience surface, and a hand-edit typo here
+  // must never reset providers/apiKeys through the backup-and-defaults repair path.
+  unauthenticatedLoopbackListener: z.union([
+    z.object({ enabled: z.literal(false) }),
+    z.object({ enabled: z.literal(true), port: z.number().int().min(1).max(65535) }),
+  ]).optional().catch(undefined),
   providers: z.record(z.string(), providerConfigSchema),
   defaultProvider: z.string().min(1).default("openai"),
+  defaultModelAliases: z.boolean().optional(),
+  // Future versions remain opaque through passthrough-compatible whole-config saves.
+  // Only version 1 grants deletion authority in the rebase path.
+  configRebaseProvenance: z.unknown().optional(),
+  // A retry can be billable, so absence and malformed hand edits both stay off.
+  emptyCompletionRetry: z.boolean().optional().catch(false),
+  // A malformed hand edit must not silently stop opening the browser: fall back
+  // to undefined, which resolves to the historical auto-open behavior.
+  oauthOpenBrowser: z.boolean().optional().catch(undefined),
   openaiProviderTierVersion: z.union([z.literal(1), z.literal(2)]).optional(),
-  // Invalid hand edits must not discard an otherwise usable config. Treat them as
-  // pre-migration so startup can safely re-run the one-time normalization.
-  googleAntigravityStaticCatalogVersion: z.literal(1).optional().catch(undefined),
+  // Invalid hand edits must not discard an otherwise usable config.
+  googleAntigravityStaticCatalogVersion: z.union([z.literal(1), z.literal(2)]).optional().catch(undefined),
+  clientIntegrations: clientIntegrationsSchema.optional().catch(undefined),
   providerContextCaps: z.record(z.string(), z.number().int().positive()).optional(),
   contextCapValue: z.number().int().positive().optional(),
   multiAgentGuidanceEnabled: z.boolean().optional(),
+  // Invalid optional recovery config must not discard unrelated provider/account state.
+  agentTaskRecovery: agentTaskRecoverySchema.optional().catch(undefined),
   // These selections pre-date schema validation and used to pass through as
   // unknown fields. Invalid hand edits must disable only the optional
   // delegation/native-default feature, not reject the whole config and hide
@@ -773,9 +903,27 @@ const configSchema = z.object({
   injectionModel: z.string().optional().catch(undefined),
   injectionEffort: z.string().optional().catch(undefined),
   syncCodexSubagentDefaults: z.boolean().optional().catch(undefined),
+  // Per-primary-model fallback chains. Values must be non-empty string arrays;
+  // malformed entries degrade to undefined rather than rejecting the whole config.
+  subagentModelFallbackByModel: z.record(
+    z.string(),
+    z.array(z.string().trim().min(1)).min(1),
+  ).optional().catch(undefined),
   codexShimAutoRestore: z.boolean().optional(),
   pausedCodexAccountIds: z.array(z.string().regex(/^[a-zA-Z0-9._-]{1,64}$/)).optional(),
   codexAccountNamespaces: codexAccountNamespacesSchema.optional(),
+  // Selection order is a preference, not a safety control like pause: a malformed
+  // map degrades to "no ordering" rather than failing the parse, so a hand-edited
+  // typo cannot trip the backup-and-defaults repair path and wipe providers or
+  // pool accounts. Warning emitted in loadConfig.
+  codexAccountPriorities: codexAccountPrioritiesSchema.optional().catch(undefined),
+  activeCodexAccountPinned: z.string().regex(CODEX_ACCOUNT_PIN_PATTERN).optional().catch(undefined),
+  // A malformed hand edit must degrade to false without discarding providers, accounts,
+  // or the exact selector map. Live writes remain strict.
+  codexAccountPickerEnabled: z.boolean().optional().catch(false),
+  // Same degrade-not-reject rule: a malformed hand edit hides Spark rather than discarding the
+  // whole config. Hidden is also the default, so `catch(false)` and the default agree.
+  showCodexSparkQuota: z.boolean().optional().catch(false),
   // Model ids excluded from the Grok Build managed block (dashboard switches).
   grokExcludedModels: z.array(z.string()).optional(),
   // Invalid values degrade to undefined ("auto") instead of failing the whole
@@ -828,6 +976,7 @@ const configSchema = z.object({
     const configuredProviderNamespaces = new Set([
       COMBO_NAMESPACE,
       OPENAI_CODEX_PROVIDER_ID,
+      POLICY_NAMESPACE,
       ...Object.keys(config.providers),
     ].map(codexProviderNamespaceKey));
     const namespaceTargets = new Set(
@@ -839,7 +988,7 @@ const configSchema = z.object({
         ctx.addIssue({
           code: "custom",
           path: ["codexAccountNamespaces", namespace],
-          message: "account selectors must not collide with configured provider or combo namespaces",
+          message: "account selectors must not collide with configured provider, combo, or routing policy namespaces",
         });
       }
       if (configuredAccountIds.has(namespace) || namespaceTargets.has(namespace)) {
@@ -855,18 +1004,25 @@ const configSchema = z.object({
     if (!isValidProviderName(name)) {
       ctx.addIssue({
         code: "custom",
-        path: ["providers", name],
-        message: "provider names must use letters, numbers, dot, underscore, or hyphen and cannot be reserved JavaScript object keys",
+        path: ["providers", redactSecretString(name)],
+        message: "provider names must use letters, numbers, dot, underscore, or hyphen and cannot be reserved JavaScript object keys or routing namespaces (policy)",
       });
     }
     const provider = config.providers[name];
+    if (hasFastWireCapabilityConflict(provider)) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["providers", redactSecretString(name), "fastWire"],
+        message: "fastWire=null conflicts with supportsServiceTier=true",
+      });
+    }
     const openRouterRoutingError = openRouterRoutingConfigError(provider);
     if (openRouterRoutingError) {
       ctx.addIssue({
         code: "custom",
         path: [
           "providers",
-          name,
+          redactSecretString(name),
           openRouterRoutingError.startsWith("modelOpenRouterRouting")
             ? "modelOpenRouterRouting"
             : "openRouterRouting",
@@ -877,7 +1033,7 @@ const configSchema = z.object({
     if (Object.hasOwn(provider, "virtualModels")) {
       ctx.addIssue({
         code: "custom",
-        path: ["providers", name, "virtualModels"],
+        path: ["providers", redactSecretString(name), "virtualModels"],
         message: "virtualModels is registry-only and must not be persisted",
       });
     }
@@ -885,7 +1041,7 @@ const configSchema = z.object({
     if (baseUrlError) {
       ctx.addIssue({
         code: "custom",
-        path: ["providers", name, "baseUrl"],
+        path: ["providers", redactSecretString(name), "baseUrl"],
         message: baseUrlError,
       });
     } else {
@@ -893,7 +1049,7 @@ const configSchema = z.object({
       if (destinationError) {
         ctx.addIssue({
           code: "custom",
-          path: ["providers", name, "baseUrl"],
+          path: ["providers", redactSecretString(name), "baseUrl"],
           message: destinationError,
         });
       }
@@ -902,7 +1058,7 @@ const configSchema = z.object({
     if (responsesPathError) {
       ctx.addIssue({
         code: "custom",
-        path: ["providers", name, "responsesPath"],
+        path: ["providers", redactSecretString(name), "responsesPath"],
         message: responsesPathError,
       });
     }
@@ -910,15 +1066,25 @@ const configSchema = z.object({
     if (headersError) {
       ctx.addIssue({
         code: "custom",
-        path: ["providers", name, "headers"],
+        path: ["providers", redactSecretString(name), "headers"],
         message: headersError,
       });
     }
+    const modelCostsError = providerModelCostsConfigError((provider as { modelCosts?: unknown }).modelCosts);
+    if (modelCostsError) {
+      ctx.addIssue({
+        code: "custom",
+        // The provider key is caller-controlled and can be token-shaped; redact it
+        // before schemaDiagnosticsError serializes the path (ocx config validate/import).
+        path: ["providers", redactSecretString(name), "modelCosts"],
+        message: modelCostsError,
+      });
+    }
     const apiKeyTransportError = apiKeyTransportConfigError(provider as OcxProviderConfig);
     if (apiKeyTransportError) {
       ctx.addIssue({
         code: "custom",
-        path: ["providers", name, "apiKeyTransport"],
+        path: ["providers", redactSecretString(name), "apiKeyTransport"],
         message: apiKeyTransportError,
       });
     }
@@ -931,10 +1097,23 @@ const configSchema = z.object({
     if (modelAdaptersError) {
       ctx.addIssue({
         code: "custom",
-        path: ["providers", name, "modelAdapters"],
+        path: ["providers", redactSecretString(name), "modelAdapters"],
         message: modelAdaptersError,
       });
     }
+    const preferHostedToolsError = modelPreferHostedToolsConfigError(
+      (provider as { modelPreferHostedTools?: unknown }).modelPreferHostedTools,
+      "modelPreferHostedTools",
+      name,
+      provider,
+    );
+    if (preferHostedToolsError) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["providers", redactSecretString(name), "modelPreferHostedTools"],
+        message: preferHostedToolsError,
+      });
+    }
     const maxInputError = positiveIntegerRecordConfigError(
       (provider as { modelMaxInputTokens?: unknown }).modelMaxInputTokens,
       "modelMaxInputTokens",
@@ -942,10 +1121,21 @@ const configSchema = z.object({
     if (maxInputError) {
       ctx.addIssue({
         code: "custom",
-        path: ["providers", name, "modelMaxInputTokens"],
+        path: ["providers", redactSecretString(name), "modelMaxInputTokens"],
         message: maxInputError,
       });
     }
+    const autoCompactError = modelAutoCompactTokenLimitsConfigError(
+      (provider as { modelAutoCompactTokenLimits?: unknown }).modelAutoCompactTokenLimits,
+      { requireNativeIds: name === OPENAI_CODEX_PROVIDER_ID },
+    );
+    if (autoCompactError) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["providers", redactSecretString(name), "modelAutoCompactTokenLimits"],
+        message: autoCompactError,
+      });
+    }
     const reasoningSummariesError = booleanRecordConfigError(
       (provider as { modelSupportsReasoningSummaries?: unknown }).modelSupportsReasoningSummaries,
       "modelSupportsReasoningSummaries",
@@ -953,10 +1143,32 @@ const configSchema = z.object({
     if (reasoningSummariesError) {
       ctx.addIssue({
         code: "custom",
-        path: ["providers", name, "modelSupportsReasoningSummaries"],
+        path: ["providers", redactSecretString(name), "modelSupportsReasoningSummaries"],
         message: reasoningSummariesError,
       });
     }
+    const verbositySupportError = booleanRecordConfigError(
+      (provider as { modelSupportsVerbosity?: unknown }).modelSupportsVerbosity,
+      "modelSupportsVerbosity",
+    );
+    if (verbositySupportError) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["providers", redactSecretString(name), "modelSupportsVerbosity"],
+        message: verbositySupportError,
+      });
+    }
+    const serviceTierModelsError = booleanRecordConfigError(
+      (provider as { modelSupportsServiceTier?: unknown }).modelSupportsServiceTier,
+      "modelSupportsServiceTier",
+    );
+    if (serviceTierModelsError) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["providers", redactSecretString(name), "modelSupportsServiceTier"],
+        message: serviceTierModelsError,
+      });
+    }
     const reasoningSummaryDeliveryError = reasoningSummaryDeliveryRecordConfigError(
       (provider as { modelReasoningSummaryDelivery?: unknown }).modelReasoningSummaryDelivery,
       (provider as { modelSupportsReasoningSummaries?: unknown }).modelSupportsReasoningSummaries,
@@ -964,7 +1176,7 @@ const configSchema = z.object({
     if (reasoningSummaryDeliveryError) {
       ctx.addIssue({
         code: "custom",
-        path: ["providers", name, "modelReasoningSummaryDelivery"],
+        path: ["providers", redactSecretString(name), "modelReasoningSummaryDelivery"],
         message: reasoningSummaryDeliveryError,
       });
     }
@@ -975,7 +1187,7 @@ const configSchema = z.object({
     if (defaultMaxOutputError) {
       ctx.addIssue({
         code: "custom",
-        path: ["providers", name, "defaultMaxOutputTokens"],
+        path: ["providers", redactSecretString(name), "defaultMaxOutputTokens"],
         message: defaultMaxOutputError,
       });
     }
@@ -986,10 +1198,21 @@ const configSchema = z.object({
     if (maxOutputError) {
       ctx.addIssue({
         code: "custom",
-        path: ["providers", name, "modelMaxOutputTokens"],
+        path: ["providers", redactSecretString(name), "modelMaxOutputTokens"],
         message: maxOutputError,
       });
     }
+    const structuredOutputOptOutError = nonBlankStringArrayConfigError(
+      (provider as { noStructuredOutputModels?: unknown }).noStructuredOutputModels,
+      "noStructuredOutputModels",
+    );
+    if (structuredOutputOptOutError) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["providers", redactSecretString(name), "noStructuredOutputModels"],
+        message: structuredOutputOptOutError,
+      });
+    }
     if (Object.hasOwn(provider, "codexAccountMode") && provider.codexAccountMode !== undefined) {
       // Persisted account mode is valid ONLY on the canonical built-in `openai` forward provider.
       // Old openai-multi rows stay parseable (they never carry a mode) so startup can migrate them.
@@ -1001,7 +1224,7 @@ const configSchema = z.object({
       if (!canonicalOpenAiShape) {
         ctx.addIssue({
           code: "custom",
-          path: ["providers", name, "codexAccountMode"],
+          path: ["providers", redactSecretString(name), "codexAccountMode"],
           message: "codexAccountMode is valid only on the canonical built-in openai provider",
         });
       }
@@ -1045,6 +1268,27 @@ const configSchema = z.object({
       }
     }
   }
+  const routingProfiles = (config as { routingProfiles?: unknown }).routingProfiles;
+  if (routingProfiles !== undefined) {
+    if (!routingProfiles || typeof routingProfiles !== "object" || Array.isArray(routingProfiles)) {
+      ctx.addIssue({ code: "custom", path: ["routingProfiles"], message: "routingProfiles must be an object" });
+    } else {
+      for (const [id, raw] of Object.entries(routingProfiles as Record<string, unknown>)) {
+        for (const issue of routingProfileIssues(id, raw, {
+          providers: config.providers,
+          combos: combos as Record<string, import("./types").OcxComboConfig> | undefined,
+          routingProfiles: routingProfiles as Record<string, import("./types").OcxRoutingProfileConfig>,
+          codexAccountNamespaces: accountNamespaces,
+        }, { excludeProfileId: id })) {
+          ctx.addIssue({
+            code: "custom",
+            path: ["routingProfiles", id, ...issue.path],
+            message: issue.message,
+          });
+        }
+      }
+    }
+  }
 });
 
 /**
@@ -1058,32 +1302,6 @@ const configSchema = z.object({
  */
 export const DEFAULT_SUBAGENT_MODELS = ["gpt-5.5", "gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", "gpt-5.4-mini"];
 
-export function getConfigDir(): string {
-  return resolveConfigDir();
-}
-
-export function getConfigPath(): string {
-  return resolveConfigPath();
-}
-
-export function getPidPath(): string {
-  return resolvePidPath();
-}
-
-export function getRuntimePortPath(): string {
-  return resolveRuntimePortPath();
-}
-
-export function hardenConfigDir(): void {
-  const dir = getConfigDir();
-  if (existsSync(dir)) {
-    try { chmodSync(dir, 0o700); } catch { /* best-effort */ }
-    if (process.platform === "win32") {
-      hardenSecretDir(dir, { required: false });
-    }
-  }
-}
-
 export function hardenExistingSecret(path: string): void {
   if (existsSync(path)) {
     try { chmodSync(path, 0o600); } catch { /* best-effort */ }
@@ -1105,6 +1323,144 @@ function warnDegradedStreamMode(rawParsed: unknown, validated: OcxConfig): void
   }
 }
 
+/**
+ * Load-time degradation for `retryOn429` (loadConfig only): one hand-edited invalid optional
+ * field (e.g. `attempts: 0` or a string) must not trip the whole provider schema and hide every
+ * provider/key behind a default config. Invalid fields are dropped with a warning; the management
+ * write boundary still rejects invalid policies explicitly.
+ */
+function sanitizeRetryOn429ForLoad(parsed: unknown): void {
+  if (!parsed || typeof parsed !== "object") return;
+  const root = parsed as Record<string, unknown>;
+  const providers = root.providers;
+  if (!providers || typeof providers !== "object" || Array.isArray(providers)) return;
+  for (const [name, provider] of Object.entries(providers as Record<string, unknown>)) {
+    // This sanitizer runs BEFORE schema validation, so the provider name is untrusted: redact
+    // secret-shaped names and JSON-escape control characters before it reaches any warning.
+    const safeProviderName = JSON.stringify(redactSecretString(name));
+    if (!provider || typeof provider !== "object" || Array.isArray(provider)) continue;
+    const p = provider as Record<string, unknown>;
+    const policy = p.retryOn429;
+    if (policy === undefined) continue;
+    if (!policy || typeof policy !== "object" || Array.isArray(policy)) {
+      delete p.retryOn429;
+      // Never serialize the value: an accidental `retryOn429: "sk-..."` would leak the secret.
+      console.warn(`⚠️  config.json providers.${safeProviderName}.retryOn429 (${typeof policy}) is invalid — ignoring the policy`);
+      continue;
+    }
+    const policyRecord = policy as Record<string, unknown>;
+    // An explicitly present but invalid master switch must not silently default to ENABLED:
+    // drop the whole policy so a hand-edit that tried to disable retries stays disabled.
+    if ("enabled" in policyRecord && typeof policyRecord.enabled !== "boolean") {
+      delete p.retryOn429;
+      console.warn(`⚠️  config.json providers.${safeProviderName}.retryOn429.enabled (${typeof policyRecord.enabled}) is invalid — ignoring the whole policy`);
+      continue;
+    }
+    // Field checks derive from the shared policy schema so the bounds cannot drift
+    // between the load-time sanitizer, the config schema, and the write boundary.
+    const policyShape = retryOn429PolicySchema.shape;
+    const hadPolicyEntries = Object.keys(policyRecord).length > 0;
+    const cleaned: Record<string, unknown> = {};
+    for (const [key, fieldSchema] of Object.entries(policyShape)) {
+      const value = policyRecord[key];
+      if (value === undefined) continue;
+      if (fieldSchema.safeParse(value).success) cleaned[key] = value;
+      // Log only the received type, never the value (provider config can hold secrets).
+      else console.warn(`⚠️  config.json providers.${safeProviderName}.retryOn429.${key} (${typeof value}) is invalid — ignoring the field`);
+    }
+    const knownKeys = new Set(Object.keys(policyShape));
+    for (const key of Object.keys(policyRecord)) {
+      if (!knownKeys.has(key)) {
+        // Redact the field NAME before logging: a malformed hand-edit can place a secret in a
+        // property name (`retryOn429: { "sk-...": true }`). Ordinary typos (e.g. `attempt`)
+        // stay readable, secret-shaped names become [REDACTED]. JSON-escape afterwards so a
+        // control-character property name (newline/ANSI) can never forge a log line.
+        console.warn(`⚠️  config.json providers.${safeProviderName}.retryOn429.${JSON.stringify(redactSecretString(key))} is not a recognized field — ignoring it`);
+      }
+    }
+    if (hadPolicyEntries && Object.keys(cleaned).length === 0) {
+      // Every supplied field was invalid: drop the whole policy. Persisting `{}` here would
+      // opt IN to retries with defaults, which is the opposite of what a malformed
+      // disable-oriented edit (`retryOn429: { enabled: "false" }`, `attempts: 0`) asked for.
+      delete p.retryOn429;
+      console.warn(`⚠️  config.json providers.${safeProviderName}.retryOn429 has no valid fields left — removing the policy (an empty policy would enable retries with defaults)`);
+    } else {
+      // Preserve an intentionally empty `retryOn429: {}` (presence = opt-in with defaults).
+      p.retryOn429 = cleaned;
+    }
+  }
+}
+
+/**
+ * Management write-boundary validation for `retryOn429` (fail closed). Unlike the
+ * lenient load-time sanitizer, invalid values and unknown keys are rejected outright so
+ * a POST/PATCH cannot persist a policy the proxy would then silently degrade. Reuses the
+ * shared policy schema. Never echoes values, and secret-shaped unknown field names are
+ * redacted (a malformed write can place a secret in a property name).
+ */
+export function retryOn429PolicyConfigError(policy: unknown): string | null {
+  if (policy === undefined) return null;
+  const result = retryOn429PolicySchema.safeParse(policy);
+  if (result.success) return null;
+  const first = result.error.issues[0];
+  if (!first) return "retryOn429 is invalid";
+  if (first.code === "unrecognized_keys") {
+    const names = first.keys.map(key => JSON.stringify(redactSecretString(key))).join(", ");
+    return `retryOn429 has unrecognized field${first.keys.length > 1 ? "s" : ""}: ${names}`;
+  }
+  if (first.path.length === 0) return `retryOn429 is invalid (${first.message})`;
+  const field = String(first.path[first.path.length - 1]);
+  return `retryOn429.${field} is invalid (${first.message})`;
+}
+
+/**
+ * Load-time degradation for `providers.<name>.modelCosts`, mirroring
+ * {@link sanitizeRetryOn429ForLoad}. A hand-edited malformed display-price row
+ * must not fail the whole config parse — that would back up config.json and
+ * fall back to defaults, dropping otherwise valid providers and the default
+ * route for a typo in a non-runtime display field. Invalid rows are dropped
+ * with a warning; strict rejection stays at the management/write boundary
+ * (providerManagementConfigError).
+ */
+function sanitizeModelCostsForLoad(parsed: unknown): void {
+  if (!parsed || typeof parsed !== "object") return;
+  const root = parsed as Record<string, unknown>;
+  const providers = root.providers;
+  if (!providers || typeof providers !== "object" || Array.isArray(providers)) return;
+  for (const [name, provider] of Object.entries(providers as Record<string, unknown>)) {
+    // Runs before schema validation, so the provider name is untrusted: redact
+    // secret-shaped names and JSON-escape control characters for the warning.
+    const safeProviderName = JSON.stringify(redactSecretString(name));
+    if (!provider || typeof provider !== "object" || Array.isArray(provider)) continue;
+    const p = provider as Record<string, unknown>;
+    const costs = p.modelCosts;
+    if (costs === undefined) continue;
+    if (!costs || typeof costs !== "object" || Array.isArray(costs)) {
+      delete p.modelCosts;
+      console.warn(`⚠️  config.json providers.${safeProviderName}.modelCosts (${typeof costs}) is invalid — ignoring the overlay`);
+      continue;
+    }
+    const costsRecord = costs as Record<string, unknown>;
+    const hadEntries = Object.keys(costsRecord).length > 0;
+    let kept = 0;
+    for (const [modelId, entry] of Object.entries(costsRecord)) {
+      // Reuse the shared per-row shape contract so the load-time sanitizer
+      // cannot drift from the schema and the write boundary.
+      if (providerModelCostsConfigError({ [modelId]: entry }) === null) {
+        kept++;
+        continue;
+      }
+      delete costsRecord[modelId];
+      // Redact the model id: a hand-edit can place a secret in a key name.
+      console.warn(`⚠️  config.json providers.${safeProviderName}.modelCosts.${JSON.stringify(redactSecretString(modelId))} is invalid — ignoring the row`);
+    }
+    if (hadEntries && kept === 0) {
+      delete p.modelCosts;
+      console.warn(`⚠️  config.json providers.${safeProviderName}.modelCosts has no valid rows left — removing the overlay`);
+    }
+  }
+}
+
 /**
  * Companion to {@link warnDegradedStreamMode} for a blank persisted `hostname`. The bind
  * falls back to loopback, which is the safe direction but not what the file asked for —
@@ -1118,6 +1474,32 @@ function warnDegradedHostname(rawParsed: unknown, validated: OcxConfig): void {
   }
 }
 
+/**
+ * Companion to {@link warnDegradedStreamMode} for a malformed selection-order map.
+ * Priority is a preference, so the schema drops the whole map rather than failing
+ * the parse — say so once, otherwise the pool silently reverts to flat ordering.
+ */
+function degradedCodexAccountPriorityWarnings(rawParsed: unknown, validated: OcxConfig): string[] {
+  const record = rawConfigRecord(rawParsed);
+  const warnings: string[] = [];
+  // The pin degrades silently otherwise, which reads as the manual selection simply
+  // not having survived the restart.
+  if (record?.activeCodexAccountPinned !== undefined && validated.activeCodexAccountPinned === undefined) {
+    warnings.push("activeCodexAccountPinned is not a valid account id — the manually selected account is no longer pinned");
+  }
+  const raw = record?.codexAccountPriorities;
+  if (raw !== undefined && validated.codexAccountPriorities === undefined) {
+    warnings.push("codexAccountPriorities is invalid (expected account ids mapped to integers between -100 and 100) — account selection order is disabled");
+  }
+  return warnings;
+}
+
+function warnDegradedCodexAccountPriorities(rawParsed: unknown, validated: OcxConfig): void {
+  for (const warning of degradedCodexAccountPriorityWarnings(rawParsed, validated)) {
+    console.warn(`⚠️  config.json ${warning}`);
+  }
+}
+
 /**
  * The apiKeys schema salvages entry by entry rather than failing the parse, so a
  * dropped key is otherwise invisible — and it will not be re-saved by the next
@@ -1230,20 +1612,69 @@ function normalizePersistedClaudeCode(claudeCode: unknown): OcxConfig["claudeCod
   if (Object.hasOwn(normalized, "subagentEffort") && !isClaudeSubagentEffort(normalized.subagentEffort)) {
     delete normalized.subagentEffort;
   }
+  // A hand-authored config never passes through the management validator, so coerce here too.
+  // A malformed classifierFallbacks (a bare string, or an array with non-string entries) would
+  // otherwise reach the resolver unchecked.
+  if (Object.hasOwn(normalized, "classifierModel")) {
+    const value = typeof normalized.classifierModel === "string" ? normalized.classifierModel.trim() : "";
+    if (value.length > 0) normalized.classifierModel = value;
+    else delete normalized.classifierModel;
+  }
+  if (Object.hasOwn(normalized, "classifierFallbacks")) {
+    const raw = normalized.classifierFallbacks;
+    const kept = Array.isArray(raw)
+      ? raw.filter((entry): entry is string => typeof entry === "string" && entry.trim().length > 0).map(entry => entry.trim())
+      : [];
+    if (kept.length > 0) normalized.classifierFallbacks = kept;
+    else delete normalized.classifierFallbacks;
+  }
   return normalized as OcxConfig["claudeCode"];
 }
 
-function normalizeClaudeSubagentEffort(config: OcxConfig, rawParsed: unknown): OcxConfig {
-  const rawEffort = rawClaudeSubagentEffort(rawParsed);
-  if (rawEffort === undefined || isClaudeSubagentEffort(rawEffort)) return config;
+function normalizeClaudeSubagentEffort(config: OcxConfig, _rawParsed: unknown): OcxConfig {
+  // Unconditional. This used to short-circuit when `subagentEffort` was absent or already valid,
+  // which meant a config whose ONLY defect was elsewhere in `claudeCode` was never normalized.
+  // The specialized subagentEffort WARNING is a separate concern and stays exactly as it is.
+  if (!config.claudeCode) return config;
   return { ...config, claudeCode: normalizePersistedClaudeCode(config.claudeCode) };
 }
 
-function warnDegradedClaudeSubagentEffort(rawParsed: unknown): void {
-  const rawEffort = rawClaudeSubagentEffort(rawParsed);
-  if (rawEffort !== undefined && !isClaudeSubagentEffort(rawEffort)) {
-    console.warn(`⚠️  config.json claudeCode.subagentEffort is invalid (expected ${CLAUDE_SUBAGENT_EFFORTS.join(", ")}) — ignoring it. Other settings were preserved.`);
-  }
+function warnDegradedClaudeSubagentEffort(rawParsed: unknown): void {
+  const rawEffort = rawClaudeSubagentEffort(rawParsed);
+  if (rawEffort !== undefined && !isClaudeSubagentEffort(rawEffort)) {
+    console.warn(`⚠️  config.json claudeCode.subagentEffort is invalid (expected ${CLAUDE_SUBAGENT_EFFORTS.join(", ")}) — ignoring it. Other settings were preserved.`);
+  }
+}
+
+function malformedUpstreamHostCircuitThresholdWarning(rawParsed: unknown): string | null {
+  const raw = rawConfigRecord(rawParsed);
+  if (!raw || !Object.hasOwn(raw, "upstreamHostCircuitThreshold")) return null;
+  const threshold = raw.upstreamHostCircuitThreshold;
+  if (threshold === undefined) return null;
+  if (typeof threshold === "number"
+    && Number.isInteger(threshold)
+    && threshold >= 0
+    && threshold <= UPSTREAM_HOST_CIRCUIT_MAX_THRESHOLD) return null;
+  return `upstreamHostCircuitThreshold ignored: expected an integer from 0 to ${UPSTREAM_HOST_CIRCUIT_MAX_THRESHOLD}`;
+}
+
+function warnDegradedUpstreamHostCircuitThreshold(rawParsed: unknown): void {
+  const warning = malformedUpstreamHostCircuitThresholdWarning(rawParsed);
+  if (warning) console.warn(`⚠️  config.json ${warning}. Other settings were preserved.`);
+}
+
+function malformedAgentTaskRecoveryWarning(rawParsed: unknown): string | null {
+  const raw = rawConfigRecord(rawParsed);
+  if (!raw || !Object.hasOwn(raw, "agentTaskRecovery")) return null;
+  const result = agentTaskRecoverySchema.safeParse(raw.agentTaskRecovery);
+  if (result.success) return null;
+  const field = result.error.issues[0]?.path.join(".");
+  return `agentTaskRecovery${field ? `.${field}` : ""} ignored: invalid experimental recovery configuration`;
+}
+
+function warnDegradedAgentTaskRecovery(rawParsed: unknown): void {
+  const warning = malformedAgentTaskRecoveryWarning(rawParsed);
+  if (warning) console.warn(`⚠️  config.json ${warning}. Other settings were preserved.`);
 }
 
 type NativeSubagentPersistedField = "injectionModel" | "injectionEffort" | "syncCodexSubagentDefaults";
@@ -1275,6 +1706,18 @@ function malformedNativeSubagentFieldWarning(field: NativeSubagentPersistedField
   return `${field} ignored: expected ${expected}`;
 }
 
+function malformedCodexAccountPickerWarning(rawParsed: unknown): string | null {
+  const raw = rawConfigRecord(rawParsed);
+  if (!raw || !Object.hasOwn(raw, "codexAccountPickerEnabled")) return null;
+  if (typeof raw.codexAccountPickerEnabled === "boolean") return null;
+  return "codexAccountPickerEnabled ignored: expected a boolean";
+}
+
+function warnDegradedCodexAccountPicker(rawParsed: unknown): void {
+  const warning = malformedCodexAccountPickerWarning(rawParsed);
+  if (warning) console.warn(`⚠️  config.json ${warning}. Other settings were preserved.`);
+}
+
 function nativeSubagentSyncDisabledReason(config: OcxConfig, rawParsed?: unknown): string | null {
   if (config.syncCodexSubagentDefaults !== true) return null;
   const malformed = malformedNativeSubagentFields(rawParsed);
@@ -1304,6 +1747,61 @@ function warnDegradedNativeSubagentConfig(rawParsed: unknown, config: OcxConfig)
   }
 }
 
+/**
+ * Registry metadata can gain service-tier capability after a config was written. An explicit
+ * `fastWire: null` remains authoritative on load and on whole-document writes; rejecting either
+ * would discard or lock access to unrelated providers and API keys. Direct contradictions within
+ * one provider row remain schema errors through the outer config refinement, where the dynamic
+ * provider name can be redacted before it reaches diagnostics.
+ */
+function inheritedFastWireConflictProviderNames(
+  config: Pick<OcxConfig, "providers">,
+): string[] {
+  const conflicts: string[] = [];
+  for (const [name, provider] of Object.entries(config.providers)) {
+    if (provider.fastWire !== null || provider.supportsServiceTier === false) continue;
+    const registry = providerMatchesRegistryTransport(name, provider)
+      ? getProviderRegistryEntry(name)
+      : undefined;
+    if (!registry) continue;
+    const effectiveProviderCapability = provider.supportsServiceTier ?? registry.supportsServiceTier;
+    const effectiveModelCapabilities = {
+      ...(registryModelServiceTierCapabilityApplies(registry, provider)
+        ? registry.modelSupportsServiceTier ?? {}
+        : {}),
+      ...(provider.modelSupportsServiceTier ?? {}),
+    };
+    if (
+      effectiveProviderCapability === true
+      || Object.values(effectiveModelCapabilities).some(value => value === true)
+    ) {
+      conflicts.push(name);
+    }
+  }
+  return conflicts;
+}
+
+function inheritedFastWireConflictWarning(name: string): string {
+  return `providers.${redactSecretString(name)}.fastWire=null overrides service-tier capability inherited from the matching registry entry`;
+}
+
+function warnInheritedFastWireConflicts(configPath: string, config: OcxConfig): void {
+  const names = inheritedFastWireConflictProviderNames(config);
+  if (names.length === 0 || warnedInheritedFastWireConflicts.has(configPath)) return;
+  warnedInheritedFastWireConflicts.add(configPath);
+  console.warn(
+    `⚠️  config.json ${names.map(inheritedFastWireConflictWarning).join("; ")}. `
+    + "The persisted providers and API keys were preserved.",
+  );
+}
+
+/**
+ * Load and validate config.json into an OcxConfig. Missing files reset to
+ * defaults and clear stale overlays. Broken existing files also fall back to
+ * default routing (after backup), but keep the last-good cost-overlay registry
+ * until a valid config or a genuinely missing file is observed. A partially-
+ * invalid config is merged with defaults so providers and pool accounts survive.
+ */
 export function loadConfig(): OcxConfig {
   const dir = getConfigDir();
   const configPath = getConfigPath();
@@ -1311,20 +1809,28 @@ export function loadConfig(): OcxConfig {
   hardenExistingSecret(configPath);
   hardenExistingSecret(join(dir, "auth.json"));
   if (!existsSync(configPath)) {
-    return getDefaultConfig();
+    return withRefreshedCostOverlays(getDefaultConfig());
   }
   try {
     const raw = readFileSync(configPath, "utf-8").replace(/^\uFEFF/, "");
     const parsed = JSON.parse(raw);
+    sanitizeAliasesForLoad(parsed);
+    sanitizeRetryOn429ForLoad(parsed);
+    sanitizeModelCostsForLoad(parsed);
     const result = configSchema.safeParse(parsed);
     if (result.success) {
       const config = normalizeApiKeyIds(result.data as OcxConfig);
+      warnInheritedFastWireConflicts(configPath, config);
       warnDegradedStreamMode(parsed, config);
       warnDegradedHostname(parsed, config);
       warnDegradedApiKeys(parsed, config);
+      warnDegradedCodexAccountPriorities(parsed, config);
       warnDegradedClaudeSubagentEffort(parsed);
       warnDegradedNativeSubagentConfig(parsed, config);
-      return normalizeClaudeSubagentEffort(normalizeNativeSubagentSync(config, parsed), parsed);
+      warnDegradedCodexAccountPicker(parsed);
+      warnDegradedUpstreamHostCircuitThreshold(parsed);
+      warnDegradedAgentTaskRecovery(parsed);
+      return withRefreshedCostOverlays(normalizeClaudeSubagentEffort(normalizeNativeSubagentSync(config, parsed), parsed));
     }
     // Schema validation failed — merge defaults into the raw object instead of
     // discarding it entirely, so pool accounts and providers survive a missing
@@ -1339,11 +1845,37 @@ export function loadConfig(): OcxConfig {
     if (retryResult.success) {
       warnConfigRepaired(configPath, result.error);
       const config = normalizeApiKeyIds(retryResult.data as OcxConfig);
+      warnInheritedFastWireConflicts(configPath, config);
       warnDegradedHostname(parsed, config);
       warnDegradedApiKeys(parsed, config);
+      warnDegradedCodexAccountPriorities(parsed, config);
       warnDegradedClaudeSubagentEffort(parsed);
       warnDegradedNativeSubagentConfig(parsed, config);
-      return normalizeClaudeSubagentEffort(normalizeNativeSubagentSync(config, parsed), parsed);
+      warnDegradedCodexAccountPicker(parsed);
+      warnDegradedUpstreamHostCircuitThreshold(parsed);
+      warnDegradedAgentTaskRecovery(parsed);
+      return withRefreshedCostOverlays(normalizeClaudeSubagentEffort(normalizeNativeSubagentSync(config, parsed), parsed));
+    }
+    // Still failing, but if every complaint is about one or more named entries
+    // in an independent section, drop exactly those and keep the rest. Falling
+    // back to defaults here would silently retire the operator's providers,
+    // keys and prices over a mistake in one routing profile.
+    const salvaged = salvageConfigCandidate(merged, retryResult.error);
+    if (salvaged) {
+      {
+        warnDroppedConfigSections(configPath, salvaged.dropped, salvaged.issues);
+        const config = normalizeApiKeyIds(salvaged.parsed);
+        warnInheritedFastWireConflicts(configPath, config);
+        warnDegradedHostname(parsed, config);
+        warnDegradedApiKeys(parsed, config);
+        warnDegradedCodexAccountPriorities(parsed, config);
+        warnDegradedClaudeSubagentEffort(parsed);
+        warnDegradedNativeSubagentConfig(parsed, config);
+        warnDegradedCodexAccountPicker(parsed);
+        warnDegradedUpstreamHostCircuitThreshold(parsed);
+        warnDegradedAgentTaskRecovery(parsed);
+        return withRefreshedCostOverlays(normalizeClaudeSubagentEffort(normalizeNativeSubagentSync(config, parsed), parsed));
+      }
     }
     // Merge couldn't fix it — truly broken config
     warnAndBackupInvalidConfig(configPath, result.error);
@@ -1354,6 +1886,49 @@ export function loadConfig(): OcxConfig {
   }
 }
 
+/** Hand-edited alias mistakes disable only the bad alias; providers and routing survive. */
+function sanitizeAliasesForLoad(raw: unknown): void {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return;
+  const root = raw as Record<string, unknown>;
+  if (!root.providers || typeof root.providers !== "object" || Array.isArray(root.providers)) return;
+  const providers = root.providers as Record<string, Record<string, unknown>>;
+  const providerNames = new Set(Object.keys(providers).map(name => name.toLowerCase()));
+  const claimedProviders = new Set<string>();
+  const comboAliases = new Set(Object.values((root.combos as Record<string, { alias?: unknown }> | undefined) ?? {})
+    .map(combo => typeof combo?.alias === "string" ? combo.alias.toLowerCase() : "").filter(Boolean));
+  const accountNamespaces = new Set(Object.keys((root.codexAccountNamespaces as Record<string, unknown> | undefined) ?? {}).map(name => name.toLowerCase()));
+  for (const provider of Object.values(providers)) {
+    const alias = provider.alias;
+    if (typeof alias !== "string" || !isValidProviderName(alias)
+      || providerNames.has(alias.toLowerCase()) || claimedProviders.has(alias.toLowerCase())
+      || comboAliases.has(alias.toLowerCase()) || accountNamespaces.has(alias.toLowerCase())) {
+      if (alias !== undefined) console.warn("Ignoring invalid or colliding provider alias in config.json");
+      delete provider.alias;
+    } else claimedProviders.add(alias.toLowerCase());
+    if (!provider.modelAliases || typeof provider.modelAliases !== "object" || Array.isArray(provider.modelAliases)) {
+      if (provider.modelAliases !== undefined) delete provider.modelAliases;
+      continue;
+    }
+    const aliases = provider.modelAliases as Record<string, unknown>;
+    const nativeIds = new Set((Array.isArray(provider.models) ? provider.models : []).filter((id): id is string => typeof id === "string").map(id => id.toLowerCase()));
+    const claimed = new Set<string>();
+    for (const [id, value] of Object.entries(aliases)) {
+      const lower = typeof value === "string" ? value.toLowerCase() : "";
+      if (typeof value !== "string" || !MODEL_ALIAS_PATTERN.test(value) || claimed.has(lower)
+        || nativeIds.has(lower) || comboAliases.has(lower) || /^(?:gpt-|o1-|o3-|o4-|codex-)/i.test(value)) {
+        console.warn(`Ignoring invalid or colliding model alias for ${id} in config.json`);
+        delete aliases[id];
+      } else claimed.add(lower);
+    }
+  }
+}
+
+/** Refresh the user cost-overlay registry from `config` and return it unchanged. */
+function withRefreshedCostOverlays(config: OcxConfig): OcxConfig {
+  refreshUserCostOverlays(config);
+  return config;
+}
+
 export type ConfigDiagnostics = {
   config: OcxConfig;
   source: "default" | "file" | "fallback";
@@ -1387,10 +1962,18 @@ function validFileConfigDiagnostics(config: OcxConfig, rawParsed: unknown): Conf
   const rawEffort = rawClaudeSubagentEffort(rawParsed);
   const normalized = normalizeClaudeSubagentEffort(normalizeNativeSubagentSync(config, rawParsed), rawParsed);
   const warnings = configPlaceholderWarnings(normalized);
+  warnings.push(...inheritedFastWireConflictProviderNames(normalized).map(inheritedFastWireConflictWarning));
+  warnings.push(...degradedCodexAccountPriorityWarnings(rawParsed, normalized));
   if (rawEffort !== undefined && !isClaudeSubagentEffort(rawEffort)) {
     warnings.push(`claudeCode.subagentEffort ignored: expected one of ${CLAUDE_SUBAGENT_EFFORTS.join(", ")}`);
   }
   warnings.push(...malformedNativeSubagentFields(rawParsed).map(malformedNativeSubagentFieldWarning));
+  const pickerWarning = malformedCodexAccountPickerWarning(rawParsed);
+  if (pickerWarning) warnings.push(pickerWarning);
+  const hostCircuitWarning = malformedUpstreamHostCircuitThresholdWarning(rawParsed);
+  if (hostCircuitWarning) warnings.push(hostCircuitWarning);
+  const recoveryWarning = malformedAgentTaskRecoveryWarning(rawParsed);
+  if (recoveryWarning) warnings.push(recoveryWarning);
   if (syncDisabledReason) {
     warnings.push(`syncCodexSubagentDefaults ignored: ${syncDisabledReason}`);
   }
@@ -1460,39 +2043,193 @@ function appOwnedMemoryBudgetError(value: unknown): string | null {
   return null;
 }
 
+function upstreamHostCircuitThresholdError(value: unknown): string | null {
+  const raw = rawConfigRecord(value);
+  if (!raw || !Object.hasOwn(raw, "upstreamHostCircuitThreshold")) return null;
+  const threshold = raw.upstreamHostCircuitThreshold;
+  if (threshold === undefined) return null;
+  if (typeof threshold === "number"
+    && Number.isInteger(threshold)
+    && threshold >= 0
+    && threshold <= UPSTREAM_HOST_CIRCUIT_MAX_THRESHOLD) return null;
+  return `schema_invalid: upstreamHostCircuitThreshold: must be an integer from 0 to ${UPSTREAM_HOST_CIRCUIT_MAX_THRESHOLD}`;
+}
+
+function agentTaskRecoveryError(value: unknown): string | null {
+  const raw = rawConfigRecord(value);
+  if (!raw || !Object.hasOwn(raw, "agentTaskRecovery") || raw.agentTaskRecovery === undefined) return null;
+  const result = agentTaskRecoverySchema.safeParse(raw.agentTaskRecovery);
+  if (result.success) return null;
+  const issue = result.error.issues[0];
+  const field = issue?.path.join(".");
+  return `schema_invalid: agentTaskRecovery${field ? `.${field}` : ""}: ${issue?.message ?? "invalid configuration"}`;
+}
+
+/**
+ * Same reasoning as {@link blankHostnameError}, and more urgent: the read path degrades a
+ * malformed selection-order map to undefined, which on a write would drop every entry the
+ * user had accumulated and still report success. A load-time degrade leaves the raw map in
+ * the file to be repaired by hand; a degraded write erases it. One bad `ocx config set`
+ * must not cost the whole map, so a live caller is told instead.
+ */
+function codexAccountPrioritiesError(value: unknown): string | null {
+  const raw = rawConfigRecord(value);
+  if (!raw) return null;
+  if (raw.codexAccountPriorities !== undefined) {
+    const parsed = codexAccountPrioritiesSchema.safeParse(raw.codexAccountPriorities);
+    if (!parsed.success) {
+      return schemaDiagnosticsError(parsed.error).replace("schema_invalid: ", "schema_invalid: codexAccountPriorities.");
+    }
+  }
+  // Tested as a string rather than coerced: `String(123)` matches the id pattern, so a
+  // coercing guard waves a non-string pin through to the schema, where `.catch(undefined)`
+  // drops it and reports the write as a success — the exact silent-degrade this guards.
+  const pin = raw.activeCodexAccountPinned;
+  if (pin !== undefined && (typeof pin !== "string" || !CODEX_ACCOUNT_PIN_PATTERN.test(pin))) {
+    return "schema_invalid: activeCodexAccountPinned: must be an account id";
+  }
+  return null;
+}
+
 function googleAntigravityStaticCatalogVersionError(value: unknown): string | null {
   const raw = rawConfigRecord(value);
   if (!raw || !Object.hasOwn(raw, "googleAntigravityStaticCatalogVersion")) return null;
   const version = raw.googleAntigravityStaticCatalogVersion;
-  if (version === undefined || version === 1) return null;
-  return "schema_invalid: googleAntigravityStaticCatalogVersion: must be 1 or omitted";
+  if (version === undefined || version === 1 || version === 2) return null;
+  return "schema_invalid: googleAntigravityStaticCatalogVersion: must be 1, 2, or omitted";
+}
+
+function codexAccountPickerEnabledError(value: unknown): string | null {
+  const raw = rawConfigRecord(value);
+  if (!raw) return null;
+  const descriptor = Object.getOwnPropertyDescriptor(raw, "codexAccountPickerEnabled");
+  if (!descriptor) {
+    return "codexAccountPickerEnabled" in raw
+      ? "schema_invalid: codexAccountPickerEnabled: must be an own boolean data property or omitted"
+      : null;
+  }
+  if (!("value" in descriptor)) {
+    return "schema_invalid: codexAccountPickerEnabled: must be an own boolean data property or omitted";
+  }
+  const enabled = descriptor.value;
+  if (enabled === undefined || typeof enabled === "boolean") return null;
+  return "schema_invalid: codexAccountPickerEnabled: must be a boolean or omitted";
+}
+
+function emptyCompletionRetryError(value: unknown): string | null {
+  const raw = rawConfigRecord(value);
+  if (!raw || !Object.hasOwn(raw, "emptyCompletionRetry")) return null;
+  const enabled = raw.emptyCompletionRetry;
+  if (enabled === undefined || typeof enabled === "boolean") return null;
+  return "schema_invalid: emptyCompletionRetry: must be a boolean or omitted";
+}
+
+function oauthOpenBrowserError(value: unknown): string | null {
+  const raw = rawConfigRecord(value);
+  if (!raw || !Object.hasOwn(raw, "oauthOpenBrowser")) return null;
+  const enabled = raw.oauthOpenBrowser;
+  if (enabled === undefined || typeof enabled === "boolean") return null;
+  return "schema_invalid: oauthOpenBrowser: must be a boolean or omitted";
 }
 
 /** Validate an in-memory config candidate without touching disk. Used by headless CLI import/set. */
+/**
+ * Reject a loopback-listener port that collides with the proxy port (#1102).
+ *
+ * The schema can only check the shape of each field on its own; the two ports being distinct
+ * is a relationship between them. Letting the pair through would surface as a startup failure
+ * after the public listener already bound, which reads like an unrelated port conflict.
+ *
+ * This is write-time only, matching `blankHostnameError`: a live caller can be told the value
+ * is wrong, whereas a hand-edited config on the read path degrades to undefined rather than
+ * resetting the whole file.
+ */
+function loopbackListenerPortError(value: unknown): string | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const listener = (value as Record<string, unknown>).unauthenticatedLoopbackListener;
+  if (listener === undefined) return null;
+  if (!listener || typeof listener !== "object" || Array.isArray(listener)) {
+    return "schema_invalid: unauthenticatedLoopbackListener: must be an object or omitted";
+  }
+  const entry = listener as Record<string, unknown>;
+  // `enabled` must be a real boolean. The schema's `.catch(undefined)` would otherwise DELETE
+  // a `"true"` string entry and report success, leaving an operator convinced they enabled an
+  // unauthenticated listener that is in fact off. Load-time still degrades quietly — a hand
+  // edit must not reset the file — but a live caller gets told.
+  if (typeof entry.enabled !== "boolean") {
+    return "schema_invalid: unauthenticatedLoopbackListener.enabled: must be a boolean";
+  }
+  if (entry.enabled !== true) return null;
+  const listenerPort = entry.port;
+  if (typeof listenerPort !== "number" || !Number.isInteger(listenerPort) || listenerPort < 1 || listenerPort > 65535) {
+    return "schema_invalid: unauthenticatedLoopbackListener.port: must be an integer port when enabled";
+  }
+  const proxyPort = (value as Record<string, unknown>).port;
+  if (typeof proxyPort === "number" && proxyPort === listenerPort) {
+    return "schema_invalid: unauthenticatedLoopbackListener.port: must differ from the proxy port";
+  }
+  return null;
+}
+
 export function validateConfigCandidate(value: unknown): { ok: true; config: OcxConfig } | { ok: false; error: string } {
   const boundaryError = blankHostnameError(value)
     ?? claudeSubagentEffortError(value)
     ?? appOwnedMemoryBudgetError(value)
-    ?? googleAntigravityStaticCatalogVersionError(value);
+    ?? upstreamHostCircuitThresholdError(value)
+    ?? agentTaskRecoveryError(value)
+    ?? googleAntigravityStaticCatalogVersionError(value)
+    ?? codexAccountPrioritiesError(value)
+    ?? codexAccountPickerEnabledError(value)
+    ?? emptyCompletionRetryError(value)
+    ?? oauthOpenBrowserError(value)
+    ?? loopbackListenerPortError(value);
   if (boundaryError) return { ok: false, error: boundaryError };
   const result = configSchema.safeParse(value);
-  if (result.success) return { ok: true, config: normalizeApiKeyIds(result.data as OcxConfig) };
+  if (result.success) {
+    const config = normalizeApiKeyIds(result.data as OcxConfig);
+    return { ok: true, config };
+  }
   return { ok: false, error: schemaDiagnosticsError(result.error) };
 }
 
 function configDiagnosticsFromRaw(raw: string): ConfigDiagnostics {
   try {
     const parsed = JSON.parse(raw.replace(/^\uFEFF/, ""));
+    // Same degradation as loadConfig: a hand-edited invalid retryOn429 must not trip the
+    // schema and send the caller a default-config fallback (the config command could then
+    // persist that fallback over the user's providers/keys).
+    sanitizeRetryOn429ForLoad(parsed);
+    sanitizeModelCostsForLoad(parsed);
     const result = configSchema.safeParse(parsed);
     if (result.success) {
       return validFileConfigDiagnostics(normalizeApiKeyIds(result.data as OcxConfig), parsed);
     }
 
-    const retryResult = configSchema.safeParse(mergeConfigDefaults(parsed));
+    const merged = mergeConfigDefaults(parsed);
+    const retryResult = configSchema.safeParse(merged);
     if (retryResult.success) {
       return validFileConfigDiagnostics(normalizeApiKeyIds(retryResult.data as OcxConfig), parsed);
     }
 
+    // #1785: one invalid routing profile must not make diagnostics report the built-in
+    // defaults AS the config, because a later config write persists those defaults over the
+    // operator's providers, keys and prices.
+    //
+    // The failure is still reported. `source` stays "fallback" and `error` keeps the real
+    // schema message -- diagnostics is the surface that tells callers the file is invalid,
+    // and every consumer that must refuse an invalid config (provider reload, catalog sync,
+    // cost reconcile, codex admission) gates on exactly those two fields. Only `config`
+    // changes: it carries the salvaged document instead of factory defaults, so a caller
+    // that ignores the error and writes it back preserves what the operator configured.
+    const salvaged = salvageConfigCandidate(merged, retryResult.error);
+    if (salvaged) {
+      return {
+        config: normalizeApiKeyIds(salvaged.parsed),
+        source: "fallback",
+        error: schemaDiagnosticsError(result.error),
+      };
+    }
+
     return { config: getDefaultConfig(), source: "fallback", error: schemaDiagnosticsError(result.error) };
   } catch {
     return { config: getDefaultConfig(), source: "fallback", error: "invalid_json" };
@@ -1519,6 +2256,54 @@ export function readConfigDiagnostics(): ConfigDiagnostics {
   return readConfigFileSnapshot().diagnostics;
 }
 
+/**
+ * The persisted config, plus a digest of the EXACT bytes it was parsed from.
+ *
+ * A union rather than a nullable digest, because `{ kind: "read" }` with no
+ * digest is a state that cannot occur — and a state that cannot occur should
+ * not be a state that can be written down. Refusing it at runtime is a check
+ * somebody eventually forgets; making it unrepresentable is not.
+ *
+ * Why a byte digest at all: the Codex write lock compares an authority snapshot
+ * taken before the lock against one taken while holding it, and its config
+ * component used to hash the PARSED object. Two files that differ only in
+ * whitespace or key order parse identically, so a non-cooperating writer could
+ * rewrite the file between admission and commit and the comparison would see
+ * nothing. Hashing what was actually read closes that.
+ *
+ * `readConfigFileSnapshot` stays private on purpose. Its `raw` carries provider
+ * API keys and admission tokens, and `privacy:scan` reads tracked source text,
+ * not runtime values — so it would not catch a caller that logged or serialized
+ * that string. The digest travels; the bytes do not.
+ */
+export type ConfigAdmissionSnapshot =
+  | Readonly<{ kind: "read"; diagnostics: ConfigDiagnostics; contentSha256: string }>
+  | Readonly<{ kind: "unreadable"; diagnostics: ConfigDiagnostics; contentSha256: null }>;
+
+export function readConfigAdmissionSnapshot(): ConfigAdmissionSnapshot {
+  let bytes: Buffer;
+  try {
+    // ONE read. Hashing the file and then reading it again to parse would leave
+    // a window for the two to disagree, which is the exact hazard this exists
+    // to detect — the check would become a second chance to be wrong.
+    bytes = readFileSync(getConfigPath());
+  } catch (error) {
+    return {
+      kind: "unreadable",
+      diagnostics: isMissingPathError(error)
+        ? { config: getDefaultConfig(), source: "default", error: null }
+        : { config: getDefaultConfig(), source: "fallback", error: "invalid_json" },
+      contentSha256: null,
+    };
+  }
+  return {
+    kind: "read",
+    // Decoded from the same buffer that was hashed, not re-read from disk.
+    diagnostics: configDiagnosticsFromRaw(bytes.toString("utf-8")),
+    contentSha256: createHash("sha256").update(bytes).digest("hex"),
+  };
+}
+
 const CONFIG_MUTATION_DB_FILENAME = "config-mutation.sqlite";
 const CONFIG_MUTATION_DB_SIDECARS = ["-journal", "-wal", "-shm"] as const;
 let warnedConfigMutationDirectoryAcl = false;
@@ -1567,6 +2352,7 @@ function configMutationDatabasePath(): string {
 }
 
 let configMutationLockDepth = 0;
+let configMutationDatabase: Database | null = null;
 
 /**
  * Serialize synchronous config and Codex credential-generation commits across processes with an
@@ -1593,7 +2379,11 @@ export function withConfigMutationLockSync<T>(fn: () => T): T {
     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)
@@ -1605,6 +2395,7 @@ export function withConfigMutationLockSync<T>(fn: () => T): T {
   }
 
   configMutationLockDepth = 1;
+  configMutationDatabase = database;
   try {
     const value = fn();
     database.exec("COMMIT");
@@ -1618,19 +2409,154 @@ export function withConfigMutationLockSync<T>(fn: () => T): T {
     throw error;
   } finally {
     configMutationLockDepth = 0;
+    configMutationDatabase = null;
     try { database.close(); } catch { /* the OS lock is released with the handle */ }
   }
 }
 
-function persistConfigUnlocked(config: OcxConfig): void {
+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) };
+  }
+};
+
+/**
+ * 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.
+ */
+function persistConfigUnlocked(config: OcxConfig): boolean {
   const configPath = getConfigPath();
-  atomicWriteFile(configPath, JSON.stringify(config, null, 2) + "\n");
+  // 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;
 }
 
+/** Persist `config` to config.json under the config-mutation lock. */
 export function saveConfig(config: OcxConfig): void {
   // Keep the real-home assertion ahead of even lock-directory preparation.
   assertNotRealHomeUnderTest(getConfigDir());
-  withConfigMutationLockSync(() => persistConfigUnlocked(config));
+  withConfigMutationLockSync(() => {
+    const withProvenance = projectCustomModelCatalogMigration(
+      readRawConfigJson(),
+      projectConfigRebaseProvenance(config),
+    );
+    if (persistConfigUnlocked(withProvenance)) bumpGenerationForCooperatingConfigWrite();
+    adoptCustomModelCatalogMigration(config, withProvenance);
+    if (withProvenance.configRebaseProvenance === undefined) delete config.configRebaseProvenance;
+    else config.configRebaseProvenance = structuredClone(withProvenance.configRebaseProvenance);
+    clearPendingConfigTopLevelDeletions(config);
+  });
 }
 
 export type PersistedConfigMutation<T> = {
@@ -1710,7 +2636,11 @@ export function mutatePersistedConfig<T>(
         continue;
       }
 
-      persistConfigUnlocked(confirmedConfig);
+      const projected = projectCustomModelCatalogMigration(
+        commitBase.diagnostics.config,
+        confirmedConfig,
+      );
+      if (persistConfigUnlocked(projected)) bumpGenerationForCooperatingConfigWrite();
       return { status: "committed", value: confirmed.value };
     }
     return { status: "unavailable", reason: "conflict" };
@@ -1738,7 +2668,12 @@ export function websocketsEnabled(config: Pick<OcxConfig, "websockets">): boolea
  * against, or a later stale save would masquerade as "our own change".
  */
 const claudeCodeBaseline = new WeakMap<OcxConfig, unknown>();
-
+/**
+ * Full live-config baseline used to rebase unrelated cooperating writes. The
+ * Claude subtree and the bound listener fields remain on their dedicated
+ * reconciliation paths below.
+ */
+const liveConfigBaseline = new WeakMap<OcxConfig, OcxConfig>();
 /**
  * The live config retains the address of the socket Bun actually opened, while
  * this map retains the operator's desired address for the next process start.
@@ -1755,9 +2690,28 @@ const persistedLiveServerBinding = new WeakMap<OcxConfig, PersistedServerBinding
  * save, which is the case the guard exists for.
  */
 export function armClaudeCodeBaseline(config: OcxConfig): void {
+  liveConfigBaseline.set(config, structuredClone(config));
   claudeCodeBaseline.set(config, structuredClone(config.claudeCode));
 }
 
+/**
+ * Adopt one schema-validated provider that was read from the authoritative disk
+ * config into a long-lived server config without rebasing any unrelated field.
+ * Updating the matching baseline row keeps a later guarded save from treating the
+ * adopted provider as an unsaved live edit that should defeat a newer disk change.
+ */
+export function adoptPersistedProviderIntoLiveConfig(
+  config: OcxConfig,
+  name: string,
+  provider: OcxProviderConfig,
+  persistedConfig?: OcxConfig,
+): void {
+  config.providers[name] = structuredClone(provider);
+  const baseline = liveConfigBaseline.get(config);
+  if (baseline) baseline.providers[name] = structuredClone(provider);
+  if (persistedConfig) refreshPreservedProviderOwner(config, persistedConfig);
+}
+
 /** Test seam only: is this instance armed? */
 export function claudeCodeBaselineArmed(config: OcxConfig): boolean {
   return claudeCodeBaseline.has(config);
@@ -1802,20 +2756,80 @@ function cloneConfigValue(value: ConfigMergeValue): ConfigMergeValue {
   return value === MISSING_CONFIG_VALUE ? value : structuredClone(value);
 }
 
+type IndexedCustomModels = {
+  order: string[];
+  byId: Map<string, Record<string, unknown>>;
+};
+
+function indexCustomModels(value: ConfigMergeValue): IndexedCustomModels | null {
+  if (!Array.isArray(value)) return null;
+  const order: string[] = [];
+  const byId = new Map<string, Record<string, unknown>>();
+  for (const item of value) {
+    if (!isPlainConfigRecord(item) || typeof item.id !== "string" || item.id.length === 0 || byId.has(item.id)) {
+      return null;
+    }
+    order.push(item.id);
+    byId.set(item.id, item);
+  }
+  return { order, byId };
+}
+
+/**
+ * Merge custom-model rows by their stable id instead of treating the array as
+ * one opaque value. A row changed only on disk is adopted, a row changed only
+ * in the live config is retained, and disjoint edits to the same row recurse
+ * through the normal three-way object merge. A newer persisted row deletion
+ * wins over a stale live edit to that row.
+ */
+function reconcileCustomModels(
+  baseline: ConfigMergeValue,
+  live: ConfigMergeValue,
+  persisted: ConfigMergeValue,
+): ConfigMergeValue | null {
+  const baselineRows = indexCustomModels(baseline);
+  const liveRows = indexCustomModels(live);
+  const persistedRows = indexCustomModels(persisted);
+  if (!baselineRows || !liveRows || !persistedRows) return null;
+
+  const order = [...liveRows.order, ...persistedRows.order.filter(id => !liveRows.byId.has(id))];
+  const merged: Array<Record<string, unknown>> = [];
+  for (const id of order) {
+    const baselineRow = baselineRows.byId.get(id) ?? MISSING_CONFIG_VALUE;
+    const persistedRow = persistedRows.byId.get(id) ?? MISSING_CONFIG_VALUE;
+    const row = baselineRow !== MISSING_CONFIG_VALUE && persistedRow === MISSING_CONFIG_VALUE
+      ? MISSING_CONFIG_VALUE
+      : reconcileConfigValue(
+          baselineRow,
+          liveRows.byId.get(id) ?? MISSING_CONFIG_VALUE,
+          persistedRow,
+        );
+    if (row !== MISSING_CONFIG_VALUE) merged.push(row as Record<string, unknown>);
+  }
+  return merged;
+}
+
 function reconcileConfigRecord(
   live: Record<string, unknown>,
   baseline: Record<string, unknown>,
   persisted: Record<string, unknown>,
   skippedKeys?: ReadonlySet<string>,
+  persistedDeletionsWin = false,
 ): void {
   const keys = new Set([...Object.keys(baseline), ...Object.keys(live), ...Object.keys(persisted)]);
   for (const key of keys) {
     if (skippedKeys?.has(key)) continue;
-    const merged = reconcileConfigValue(
-      ownConfigValue(baseline, key),
-      ownConfigValue(live, key),
-      ownConfigValue(persisted, key),
-    );
+    const baselineValue = ownConfigValue(baseline, key);
+    const liveValue = ownConfigValue(live, key);
+    const persistedValue = ownConfigValue(persisted, key);
+    const merged = persistedDeletionsWin
+        && baselineValue !== MISSING_CONFIG_VALUE
+        && persistedValue === MISSING_CONFIG_VALUE
+      ? MISSING_CONFIG_VALUE
+      : key === "customModels"
+        ? reconcileCustomModels(baselineValue, liveValue, persistedValue)
+          ?? reconcileConfigValue(baselineValue, liveValue, persistedValue)
+        : reconcileConfigValue(baselineValue, liveValue, persistedValue, key === "providers");
     if (merged === MISSING_CONFIG_VALUE) delete live[key];
     else live[key] = merged;
   }
@@ -1825,6 +2839,7 @@ function reconcileConfigValue(
   baseline: ConfigMergeValue,
   live: ConfigMergeValue,
   persisted: ConfigMergeValue,
+  persistedChildDeletionsWin = false,
 ): ConfigMergeValue {
   const liveChanged = !deepEqual(live, baseline);
   const persistedChanged = !deepEqual(persisted, baseline);
@@ -1854,6 +2869,8 @@ function reconcileConfigValue(
       live,
       isPlainConfigRecord(baseline) ? baseline : {},
       persisted,
+      undefined,
+      persistedChildDeletionsWin,
     );
   }
   // Same-leaf conflicts prefer the pending live management mutation.
@@ -1893,6 +2910,10 @@ export function reconcileLiveConfigFromDisk(config: OcxConfig, persistedBaseline
     else config.claudeCode = structuredClone(persisted.claudeCode);
     claudeCodeBaseline.set(config, structuredClone(config.claudeCode));
   }
+  // The reconciliation may have adopted a providers.<name>.modelCosts edit made
+  // by a cooperating process while the OAuth login was pending; keep the overlay
+  // registry (and the usage-cache overlay version) in sync with the live config.
+  refreshUserCostOverlays(config);
 }
 
 /** The literal file, with no schema merge or default injection. */
@@ -1937,20 +2958,57 @@ function readPersistedServerBinding(
  *
  * Conflict policy, chosen deliberately:
  * - disk changed, we did not → their hand edit wins;
- * - disk changed AND we changed → our change wins and the baseline rebases, so the
- *   user's next edit starts from the new value (a three-way merge is out of scope);
+ * - disk changed AND we changed → disjoint fields are merged, while a same-leaf
+ *   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.
  *
- * Scope residual: only `claudeCode` is reconciled. A hand edit to `providers` is still
- * clobbered — recorded and asserted in tests so it cannot drift into an assumed
- * guarantee.
+ * Custom-model rows are merged by their stable `id`, preserving independent
+ * edits and deletions across stale whole-config saves.
  */
 export function saveConfigPreservingClaudeCode(config: OcxConfig): void {
   withConfigMutationLockSync(() => {
     const bindingBaseline = persistedLiveServerBinding.get(config);
-    const onDisk = claudeCodeBaseline.has(config) || bindingBaseline
-      ? readRawConfigJson()
-      : undefined;
+    // One authoritative pre-write read feeds both the live-config reconciliation and
+    // custom-model deletion migration. A second read could observe different bytes.
+    const onDisk = readRawConfigJson();
+    const baseline = liveConfigBaseline.get(config);
+    if (baseline && onDisk !== undefined) {
+      const persistedDiagnostics = configDiagnosticsFromRaw(JSON.stringify(onDisk));
+      if (persistedDiagnostics.source === "file") {
+        const deletedKeys = configRebaseDeletionKeys(config);
+        const provenanceExists = configHasRebaseProvenance(config);
+        // Only keys this live config is actually known to have diverged on may be
+        // rebased. The baseline is captured once when the server arms it, so any key
+        // that appeared on disk afterwards — through saveConfig(), a hand edit, or
+        // another process — is absent from the baseline as well as from the live
+        // config. Reconciling those keys reads "live never changed this" and adopts
+        // the disk value, which resurrects a field the live writer had deliberately
+        // deleted (#1462 regression: PUT /api/grok/selection with an empty list).
+        // Restrict the merge to keys the baseline knew about, plus keys the live
+        // config still carries; a key that exists only on disk is left to the
+        // ordinary whole-config write below.
+        const rebaseableKeys = new Set([
+          ...Object.keys(baseline as unknown as Record<string, unknown>),
+          ...Object.keys(config as unknown as Record<string, unknown>),
+          ...(provenanceExists
+            ? Object.keys(persistedDiagnostics.config as unknown as Record<string, unknown>)
+            : []),
+        ]);
+        const skipped = new Set(["hostname", "port", "claudeCode", CONFIG_REBASE_PROVENANCE_KEY]);
+        for (const key of Object.keys(persistedDiagnostics.config as unknown as Record<string, unknown>)) {
+          if (!rebaseableKeys.has(key)) skipped.add(key);
+        }
+        reconcileConfigRecord(
+          config as unknown as Record<string, unknown>,
+          baseline as unknown as Record<string, unknown>,
+          persistedDiagnostics.config as unknown as Record<string, unknown>,
+          skipped,
+        );
+        for (const key of deletedKeys) delete (config as unknown as Record<string, unknown>)[key];
+      }
+    }
     if (claudeCodeBaseline.has(config)) {
       if (onDisk !== undefined) {
         const baseline = claudeCodeBaseline.get(config);
@@ -1962,21 +3020,35 @@ export function saveConfigPreservingClaudeCode(config: OcxConfig): void {
         }
       }
     }
+    const provenanceProjection = projectConfigRebaseProvenance(config);
+    const projectedConfig = projectCustomModelCatalogMigration(
+      onDisk,
+      config,
+    );
+    if (provenanceProjection.configRebaseProvenance === undefined) delete projectedConfig.configRebaseProvenance;
+    else projectedConfig.configRebaseProvenance = provenanceProjection.configRebaseProvenance;
     const persistedBinding = bindingBaseline && onDisk
       ? readPersistedServerBinding(onDisk, bindingBaseline)
       : bindingBaseline;
     if (persistedBinding) {
-      const persistedConfig: OcxConfig = { ...config, port: persistedBinding.port };
+      const persistedConfig: OcxConfig = { ...projectedConfig, port: persistedBinding.port };
       if (persistedBinding.hostname === undefined) delete persistedConfig.hostname;
       else persistedConfig.hostname = persistedBinding.hostname;
-      persistConfigUnlocked(persistedConfig);
+      if (persistConfigUnlocked(persistedConfig)) bumpGenerationForCooperatingConfigWrite();
       persistedLiveServerBinding.set(config, persistedBinding);
     } else {
-      persistConfigUnlocked(config);
+      if (persistConfigUnlocked(projectedConfig)) bumpGenerationForCooperatingConfigWrite();
     }
+    adoptCustomModelCatalogMigration(config, projectedConfig);
     if (claudeCodeBaseline.has(config)) {
       claudeCodeBaseline.set(config, structuredClone(config.claudeCode));
     }
+    if (liveConfigBaseline.has(config)) {
+      if (projectedConfig.configRebaseProvenance === undefined) delete config.configRebaseProvenance;
+      else config.configRebaseProvenance = structuredClone(projectedConfig.configRebaseProvenance);
+      liveConfigBaseline.set(config, structuredClone(projectedConfig));
+    }
+    clearPendingConfigTopLevelDeletions(config);
   });
 }
 
@@ -2005,6 +3077,7 @@ export function getDefaultConfig(): OcxConfig {
   // Adding extra providers (e.g. opencode-go) and switching defaultProvider is a user/runtime choice.
   return {
     port: 10100,
+    emptyCompletionRetry: false,
     managementUsageMaxReadBytes: 64 * 1024 * 1024,
     appOwnedMemoryBudgetMb: DEFAULT_APP_OWNED_MEMORY_BUDGET_BYTES / (1024 * 1024),
     // Fresh/re-initialized configs are already written in the current three-tier
@@ -2051,92 +3124,22 @@ export function applyProxyEnv(config: OcxConfig): void {
   const existing = process.env.NO_PROXY ?? process.env.no_proxy ?? "";
   const entries = existing.split(",").map(s => s.trim()).filter(Boolean);
   const seen = new Set(entries.map(e => e.toLowerCase()));
-  for (const host of ["localhost", "127.0.0.1", "::1", "[::1]"]) {
-    if (!seen.has(host)) {
+  // Configured entries first, then loopback: loopback is unconditional, so appending it last
+  // keeps it present even when the operator lists a loopback host themselves.
+  const raw = config.noProxy;
+  const configured = (Array.isArray(raw) ? raw : (resolveEnvValue(raw) ?? "").split(","))
+    .map(entry => entry.trim())
+    .filter(Boolean);
+  for (const host of [...configured, "localhost", "127.0.0.1", "::1", "[::1]"]) {
+    const key = host.toLowerCase();
+    if (!seen.has(key)) {
       entries.push(host);
-      seen.add(host);
+      seen.add(key);
     }
   }
   process.env.NO_PROXY = entries.join(",");
 }
 
-export function writePid(pid: number): void {
-  const dir = getConfigDir();
-  if (!existsSync(dir)) {
-    mkdirSync(dir, { recursive: true, mode: 0o700 });
-  } else {
-    hardenConfigDir();
-  }
-  atomicWriteFile(getPidPath(), String(pid));
-}
-
-export type RuntimePortState = {
-  pid: number;
-  port: number;
-  hostname?: string;
-};
-
-function isValidRuntimePortState(value: unknown): value is RuntimePortState {
-  if (!value || typeof value !== "object") return false;
-  const state = value as Record<string, unknown>;
-  const hostnameOk = state.hostname === undefined || typeof state.hostname === "string";
-  return Number.isSafeInteger(state.pid)
-    && Number(state.pid) > 0
-    && Number.isInteger(state.port)
-    && Number(state.port) > 0
-    && Number(state.port) <= 65535
-    && hostnameOk;
-}
-
-export function writeRuntimePort(state: RuntimePortState): void {
-  const dir = getConfigDir();
-  if (!existsSync(dir)) {
-    mkdirSync(dir, { recursive: true, mode: 0o700 });
-  } else {
-    hardenConfigDir();
-  }
-  atomicWriteFile(getRuntimePortPath(), JSON.stringify(state, null, 2) + "\n");
-}
-
-export function readPid(): number | null {
-  const pidPath = getPidPath();
-  if (!existsSync(pidPath)) return null;
-  try {
-    const raw = readFileSync(pidPath, "utf-8").trim();
-    const pid = parsePidFile(raw);
-    if (pid === null) return null;
-    try {
-      process.kill(pid, 0);
-      return isLikelyOcxStartProcess(pid) ? pid : null;
-    } catch (e: unknown) {
-      if ((e as NodeJS.ErrnoException).code === "EPERM") {
-        return isLikelyOcxStartProcess(pid) ? pid : null;
-      }
-      return null;
-    }
-  } catch {
-    return null;
-  }
-}
-
-export function readRuntimePort(expectedPid?: number): RuntimePortState | null {
-  try {
-    const parsed = JSON.parse(readFileSync(getRuntimePortPath(), "utf-8"));
-    if (!isValidRuntimePortState(parsed)) return null;
-    if (expectedPid !== undefined && parsed.pid !== expectedPid) return null;
-    return parsed;
-  } catch {
-    return null;
-  }
-}
-
-export function removePid(expectedPid?: number): void {
-  if (expectedPid !== undefined && readPidFileValue() !== expectedPid) return;
-  try {
-    unlinkSync(getPidPath());
-  } catch { /* ignore */ }
-}
-
 function warnConfigRepaired(configPath: string, error: z.ZodError): void {
   if (warnedConfigFallbacks.has(configPath)) return;
   warnedConfigFallbacks.add(configPath);
@@ -2144,191 +3147,192 @@ function warnConfigRepaired(configPath: string, error: z.ZodError): void {
   console.error(`opencodex config at ${configPath}: repaired missing field(s) [${fields}] with defaults. Your providers and accounts are preserved.`);
 }
 
-export function readPidFileValue(): number | null {
-  try {
-    return parsePidFile(readFileSync(getPidPath(), "utf-8"));
-  } catch {
-    return null;
-  }
-}
+/**
+ * Sections whose entries are independent of one another, so one bad entry is
+ * safe to drop without changing what the rest mean.
+ *
+ * Both are validated entry-by-entry in the `superRefine` above, which raises
+ * every finding as a *document*-level issue. That is what made a single routing
+ * candidate naming a disabled provider discard the operator's whole config —
+ * all eleven providers, every API key, and the entire `modelCosts` table —
+ * while the proxy carried on serving from built-in defaults and reporting
+ * healthy.
+ */
+const SALVAGEABLE_CONFIG_SECTIONS = ["routingProfiles", "combos"] as const;
 
-export function removeRuntimePort(expectedPid?: number): void {
-  if (expectedPid !== undefined && readRuntimePort(expectedPid) === null) return;
-  try {
-    unlinkSync(getRuntimePortPath());
-  } catch { /* ignore */ }
+/**
+ * Drop just the named entries a parse failure blamed, so the rest of the
+ * document survives.
+ *
+ * Returns `null` when the failure was not confined to those sections — the
+ * caller then keeps its existing behaviour rather than guessing.
+ *
+ * The whole entry goes, not the individual offending candidate. A routing
+ * profile that quietly loses one candidate still routes, just not where the
+ * operator said it should, and a policy that silently changed shape is a worse
+ * outcome than one that is plainly absent. Absent is also the loud option: a
+ * dry-run against it answers `unknown_profile`, which — paired with the warning
+ * this emits — points at the real mistake.
+ */
+function dropInvalidConfigSections(
+  parsed: unknown,
+  error: z.ZodError,
+): { candidate: Record<string, unknown>; dropped: string[] } | null {
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+
+  const doomed = new Map<string, Set<string>>();
+  for (const issue of error.issues) {
+    if (isUnsalvageableIssue(issue)) return null;
+    const [section, id] = issue.path;
+    if (typeof section !== "string" || typeof id !== "string") return null;
+    if (!(SALVAGEABLE_CONFIG_SECTIONS as readonly string[]).includes(section)) return null;
+    // A complaint about the container itself ("combos must be an object") is
+    // not about one entry, so there is nothing selective to drop.
+    if (issue.path.length < 2) return null;
+    let ids = doomed.get(section);
+    if (!ids) doomed.set(section, ids = new Set());
+    ids.add(id);
+  }
+  if (doomed.size === 0) return null;
+
+  const candidate: Record<string, unknown> = { ...(parsed as Record<string, unknown>) };
+  const dropped: string[] = [];
+  for (const [section, ids] of doomed) {
+    const current = candidate[section];
+    if (!current || typeof current !== "object" || Array.isArray(current)) return null;
+    const kept: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(current as Record<string, unknown>)) {
+      if (ids.has(key)) dropped.push(`${section}.${key}`);
+      else kept[key] = value;
+    }
+    candidate[section] = kept;
+  }
+  return dropped.length > 0 ? { candidate, dropped } : null;
 }
 
 /**
- * Snapshot-guarded stale-state purge: remove the pid/runtime files only when their content
- * still matches what the caller saw BEFORE its liveness probe. A concurrent `ocx start` can
- * write fresh records mid-probe; an unconditional purge would erase the new proxy's state.
+ * Salvage until the document parses, not just once.
+ *
+ * One pass is not enough because the sections depend on each other: routing
+ * profiles are validated against the combo map, so dropping an invalid combo can
+ * expose a profile that referenced it. A single-pass salvage sees that second
+ * failure and gives up, discarding the whole config -- the exact outcome this
+ * code exists to prevent.
+ *
+ * `rawDocument` is the operator's document before defaults were merged in. When
+ * supplied, the same entries are deleted from it too, so a diagnostics caller can
+ * still tell an absent optional setting from one we injected.
  */
-export function removePidIfValueIs(snapshot: number | null): void {
-  if (!existsSync(getPidPath())) return;
-  if (readPidFileValue() !== snapshot) return;
-  try {
-    unlinkSync(getPidPath());
-  } catch { /* ignore */ }
-}
 
-export function removeRuntimePortIfPidIs(snapshotPid: number | null): void {
-  const current = readRuntimePort();
-  if ((current?.pid ?? null) !== snapshotPid) return;
-  try {
-    unlinkSync(getRuntimePortPath());
-  } catch { /* ignore */ }
-}
-
-export function parsePidFile(raw: string): number | null {
-  const trimmed = raw.trim();
-  if (!/^\d+$/.test(trimmed)) return null;
-  const pid = Number.parseInt(trimmed, 10);
-  return Number.isSafeInteger(pid) && pid > 0 ? pid : null;
-}
-
-export function isOcxStartCommandLine(commandLine: string): boolean {
-  const normalized = commandLine.toLowerCase().replace(/\\/g, "/");
-  // "src/cli.ts" matches pre-restructure installs still running; "src/cli/index.ts" is current.
-  // `@scope/.opencodex-*` is npm's in-place rename of the global package during
-  // `npm install -g` — a Windows service wrapper can respawn from that temp tree
-  // mid-update, and must still count as ocx for port reclaim.
-  // Match both the upstream scope (@bitkyc08) and this fork's publish scope (@iislee).
-  const hasOcxEntrypoint = normalized.includes("src/cli.ts")
-    || normalized.includes("src/cli/index.ts")
-    || normalized.includes("@bitkyc08/opencodex")
-    || normalized.includes("@iislee/opencodex")
-    || /@bitkyc08\/\.opencodex-/.test(normalized)
-    || /@iislee\/\.opencodex-/.test(normalized)
-    || /(?:^|[\s/"'])(?:ocx|opencodex)(?:\.cmd)?(?:$|[\s"'])/.test(normalized);
-  return hasOcxEntrypoint && /(?:^|[\s"'])start(?:$|[\s"'])/.test(normalized);
-}
-
-/** Per-process memo: waitForProxy/findLiveProxy used to spawn powershell on every 150ms poll. */
-const ocxStartProcessCache = new Map<number, boolean>();
-let ocxStartProcessSweepCursor = 0;
-let ocxStartProcessProbe: (pid: number) => void = pid => { process.kill(pid, 0); };
-
-export function setOcxStartProcessProbeForTests(probe: ((pid: number) => void) | null): void {
-  ocxStartProcessProbe = probe ?? (pid => { process.kill(pid, 0); });
-}
-
-export function setOcxStartProcessCacheForTests(entries: Iterable<readonly [number, boolean]>): void {
-  ocxStartProcessCache.clear();
-  for (const [pid, value] of entries) ocxStartProcessCache.set(pid, value);
-  ocxStartProcessSweepCursor = 0;
-}
-
-export function sweepDeadOcxStartProcessCache(maxProbes = 64): number {
-  const pids: number[] = [];
-  let removed = 0;
-  for (const pid of ocxStartProcessCache.keys()) {
-    if (Number.isSafeInteger(pid) && pid > 0) pids.push(pid);
-    else if (ocxStartProcessCache.delete(pid)) removed += 1;
-  }
-  if (pids.length === 0 || maxProbes <= 0) {
-    ocxStartProcessSweepCursor = 0;
-    return removed;
-  }
-  const probeCount = Math.min(Math.floor(maxProbes), pids.length);
-  const start = ocxStartProcessSweepCursor % pids.length;
-  for (let offset = 0; offset < probeCount; offset += 1) {
-    const pid = pids[(start + offset) % pids.length]!;
-    try {
-      ocxStartProcessProbe(pid);
-    } catch (error) {
-      if ((error as NodeJS.ErrnoException).code !== "ESRCH") continue;
-      if (ocxStartProcessCache.delete(pid)) removed += 1;
+/**
+ * Findings that must never be salvaged away.
+ *
+ * Salvage removes the entry a finding blamed, which is right for an ordinary
+ * validation mistake and wrong for a namespace collision: the collision is a
+ * *relationship* between a combo/profile and a Codex account selector, and it is
+ * reported on the combo. Dropping that combo makes the document parse and quietly
+ * admits the account selector the schema just refused, turning a hard admission
+ * boundary into a config that loads. Refuse the whole document instead.
+ */
+const UNSALVAGEABLE_ISSUE_MESSAGES: readonly string[] = [
+  CODEX_ACCOUNT_NAMESPACE_COMBO_ALIAS_COLLISION_ERROR,
+];
+
+function isUnsalvageableIssue(issue: z.ZodIssue): boolean {
+  return UNSALVAGEABLE_ISSUE_MESSAGES.some(message => issue.message.includes(message));
+}
+function salvageConfigCandidate(
+  merged: unknown,
+  initialError: z.ZodError,
+  rawDocument?: unknown,
+): {
+  candidate: Record<string, unknown>;
+  rawCandidate: unknown;
+  parsed: OcxConfig;
+  dropped: string[];
+  issues: z.ZodIssue[];
+} | null {
+  let candidate: unknown = merged;
+  let rawCandidate: unknown = rawDocument;
+  let error = initialError;
+  const dropped: string[] = [];
+  const issues: z.ZodIssue[] = [];
+  // Bounded by construction: every pass must remove at least one entry, and there
+  // are only so many entries to remove.
+  const budget = countSalvageableEntries(merged) + 1;
+  for (let pass = 0; pass < budget; pass++) {
+    const step = dropInvalidConfigSections(candidate, error);
+    if (!step || step.dropped.length === 0) return null;
+    dropped.push(...step.dropped);
+    issues.push(...error.issues);
+    candidate = step.candidate;
+    rawCandidate = deleteEntryPaths(rawCandidate, step.dropped);
+    const result = configSchema.safeParse(candidate);
+    if (result.success) {
+      return { candidate: step.candidate, rawCandidate, parsed: result.data as OcxConfig, dropped, issues };
     }
+    error = result.error;
   }
-  ocxStartProcessSweepCursor = (start + probeCount) % pids.length;
-  return removed;
+  return null;
 }
 
-export function ocxStartProcessCacheSizeForTests(): number {
-  return ocxStartProcessCache.size;
+function countSalvageableEntries(document: unknown): number {
+  if (!document || typeof document !== "object" || Array.isArray(document)) return 0;
+  let total = 0;
+  for (const section of SALVAGEABLE_CONFIG_SECTIONS) {
+    const value = (document as Record<string, unknown>)[section];
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+      total += Object.keys(value as Record<string, unknown>).length;
+    }
+  }
+  return total;
 }
 
-function isLikelyOcxStartProcess(pid: number): boolean {
-  const cached = ocxStartProcessCache.get(pid);
-  if (cached !== undefined) return cached;
-  const commandLine = readProcessCommandLine(pid);
-  if (commandLine === undefined) return false;
-  const ok = isOcxStartCommandLine(commandLine);
-  ocxStartProcessCache.set(pid, ok);
-  return ok;
+/** Delete `section.id` entries from a copy of the raw document. */
+function deleteEntryPaths(document: unknown, entryPaths: readonly string[]): unknown {
+  if (!document || typeof document !== "object" || Array.isArray(document)) return document;
+  const next: Record<string, unknown> = { ...(document as Record<string, unknown>) };
+  for (const entryPath of entryPaths) {
+    const separator = entryPath.indexOf(".");
+    if (separator <= 0) continue;
+    const section = entryPath.slice(0, separator);
+    const id = entryPath.slice(separator + 1);
+    const container = next[section];
+    if (!container || typeof container !== "object" || Array.isArray(container)) continue;
+    const kept: Record<string, unknown> = { ...(container as Record<string, unknown>) };
+    delete kept[id];
+    next[section] = kept;
+  }
+  return next;
 }
 
 /**
- * Alive pid from the pid file without the expensive Windows command-line probe.
- * Safe for liveness polls: callers still identity-check /healthz before trusting the proxy.
- * Destructive stop/kill paths should keep using {@link readPid}, which verifies the cmdline.
+ * Entry ids are operator-chosen and can be token-shaped, so nothing dynamic reaches
+ * the log unredacted. Static section names stay readable -- they are the part that
+ * tells the operator where to look.
  */
-export function readAlivePid(): number | null {
-  const pid = readPidFileValue();
-  if (pid === null) return null;
-  try {
-    process.kill(pid, 0);
-    return pid;
-  } catch (e: unknown) {
-    if ((e as NodeJS.ErrnoException).code === "EPERM") return pid;
-    return null;
-  }
+function redactEntryPath(entryPath: string): string {
+  const separator = entryPath.indexOf(".");
+  if (separator <= 0) return redactSecretString(entryPath);
+  return entryPath.slice(0, separator) + "." + redactSecretString(entryPath.slice(separator + 1));
 }
 
-/**
- * Full identity check of a KNOWN candidate pid (alive + ocx-start command line).
- * Companion to {@link readAlivePid}: liveness discovery may be cheap, but any pid
- * handed to a destructive caller must pass this check — and must equal the candidate
- * it was asked about, so a pidfile rewrite between discovery and verification can
- * never swap in a different process (TOCTOU guard).
- */
-export function verifyPidIdentity(candidatePid: number): number | null {
-  try {
-    process.kill(candidatePid, 0);
-  } catch (e: unknown) {
-    if ((e as NodeJS.ErrnoException).code !== "EPERM") return null;
-  }
-  return isLikelyOcxStartProcess(candidatePid) ? candidatePid : null;
+function redactIssuePath(path: readonly PropertyKey[]): string {
+  return path
+    .map((segment, index) => (index === 0 && typeof segment === "string" ? segment : redactSecretString(String(segment))))
+    .join(".");
 }
 
-function readProcessCommandLine(pid: number): string | undefined {
-  try {
-    if (process.platform === "win32") {
-      // Prefer WMIC over PowerShell: much faster cold start, and windowsHide avoids console flash.
-      // Fall back to PowerShell when WMIC is absent (newer Windows images).
-      const wmic = `${process.env.SystemRoot ?? "C:\\Windows"}\\System32\\wbem\\WMIC.exe`;
-      try {
-        const output = execFileSync(wmic, [
-          "process", "where", `ProcessId=${pid}`, "get", "CommandLine", "/VALUE",
-        ], { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"], timeout: 3000, windowsHide: true });
-        const match = /^CommandLine=(.*)$/m.exec(output.replace(/\r/g, ""));
-        const value = match?.[1]?.trim();
-        if (value) return value;
-      } catch {
-        /* WMIC missing or failed — fall through */
-      }
-      const output = execFileSync("powershell.exe", [
-        "-NoProfile",
-        "-NoLogo",
-        "-NonInteractive",
-        "-WindowStyle",
-        "Hidden",
-        "-Command",
-        `(Get-CimInstance Win32_Process -Filter "ProcessId = ${pid}").CommandLine`,
-      ], { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"], timeout: 3000, windowsHide: true });
-      return output.trim() || undefined;
-    }
-    const output = execFileSync("ps", ["-p", String(pid), "-o", "command="], {
-      encoding: "utf-8",
-      stdio: ["ignore", "pipe", "ignore"],
-      timeout: 1000,
-      windowsHide: true,
-    });
-    return output.trim() || undefined;
-  } catch {
-    return undefined;
-  }
+function warnDroppedConfigSections(configPath: string, dropped: string[], issues: readonly z.ZodIssue[]): void {
+  if (warnedConfigFallbacks.has(configPath)) return;
+  warnedConfigFallbacks.add(configPath);
+  const reasons = issues
+    .map(issue => `${redactIssuePath(issue.path)}: ${redactSecretString(issue.message)}`)
+    .join("; ");
+  console.error(
+    `opencodex config at ${configPath}: dropped [${dropped.map(redactEntryPath).join(", ")}] and loaded the rest — ${reasons}. `
+    + "Everything else in your config, including providers and modelCosts, is preserved.",
+  );
 }
 
 function warnAndBackupInvalidConfig(configPath: string, error: unknown): void {