@bitkyc08/opencodex 2.63.0 → 2.64.0

package/src/config/persisted-mutation.ts

@@ -0,0 +1,94 @@
+import type { OcxConfig } from "../types";
+import { projectCustomModelCatalogMigration } from "../codex/custom-model-catalog-migration";
+import { readConfigFileSnapshot, type ConfigFileSnapshot } from "./diagnostics";
+import { bumpGenerationForCooperatingConfigWrite, withConfigMutationLockSync } from "./mutation-lock";
+import { persistConfigUnlocked } from "./persist-unlocked";
+import { projectConfigRebaseProvenance } from "./rebase-provenance";
+
+export type PersistedConfigMutation<T> = {
+  changed: boolean;
+  value: T;
+};
+
+export type PersistedConfigMutationOutcome<T> =
+  | { status: "committed" | "unchanged"; value: T }
+  | { status: "unavailable"; reason: "missing" | "invalid" | "conflict" };
+
+const CONFIG_MUTATION_MAX_REBASE_ATTEMPTS = 3;
+let persistedConfigMutationBeforeCommitForTests: (() => void) | null = null;
+
+/** Test-only one-shot seam: inject a competing mutation after the first decision, before freshness revalidation. */
+export function setPersistedConfigMutationBeforeCommitForTests(hook: (() => void) | null): void {
+  persistedConfigMutationBeforeCommitForTests = hook;
+}
+
+function unavailableConfigMutationReason(snapshot: ConfigFileSnapshot): "missing" | "invalid" {
+  return snapshot.diagnostics.source === "default" ? "missing" : "invalid";
+}
+
+/**
+ * Patch a schema-valid on-disk config under the shared mutation lock. Cooperating writers are
+ * serialized; the callback is rerun on the newest snapshot so observed direct byte changes rebase
+ * and credential predicates are re-evaluated immediately before the atomic commit. A writer that
+ * ignores the coordinator can still change bytes after the final check because the filesystem has
+ * no portable conditional rename. Missing or malformed config always fails closed and is never
+ * recreated from a prior snapshot.
+ */
+export function mutatePersistedConfig<T>(
+  mutate: (config: OcxConfig) => PersistedConfigMutation<T>,
+): PersistedConfigMutationOutcome<T> {
+  // Avoid creating/opening the coordinator database for a read-path update that already knows
+  // there is no valid config. The same check runs again under the transaction for authority.
+  const observed = readConfigFileSnapshot();
+  if (observed.diagnostics.source !== "file" || observed.raw === undefined) {
+    return { status: "unavailable", reason: unavailableConfigMutationReason(observed) };
+  }
+  return withConfigMutationLockSync(() => {
+    let base = readConfigFileSnapshot();
+    for (let attempt = 0; attempt < CONFIG_MUTATION_MAX_REBASE_ATTEMPTS; attempt += 1) {
+      if (base.diagnostics.source !== "file" || base.raw === undefined) {
+        return { status: "unavailable", reason: unavailableConfigMutationReason(base) };
+      }
+
+      const tentativeConfig = structuredClone(base.diagnostics.config);
+      const tentative = mutate(tentativeConfig);
+      if (!tentative.changed) return { status: "unchanged", value: tentative.value };
+
+      const hook = persistedConfigMutationBeforeCommitForTests;
+      persistedConfigMutationBeforeCommitForTests = null;
+      hook?.();
+
+      const latest = readConfigFileSnapshot();
+      if (latest.diagnostics.source !== "file" || latest.raw === undefined) {
+        return { status: "unavailable", reason: unavailableConfigMutationReason(latest) };
+      }
+      if (latest.raw !== base.raw) {
+        base = latest;
+        continue;
+      }
+
+      // Re-run against a fresh clone even when config bytes are unchanged: a Codex credential
+      // generation lives in a separate file and may have changed at the injected seam.
+      const confirmedConfig = structuredClone(latest.diagnostics.config);
+      const confirmed = mutate(confirmedConfig);
+      if (!confirmed.changed) return { status: "unchanged", value: confirmed.value };
+
+      const commitBase = readConfigFileSnapshot();
+      if (commitBase.diagnostics.source !== "file" || commitBase.raw === undefined) {
+        return { status: "unavailable", reason: unavailableConfigMutationReason(commitBase) };
+      }
+      if (commitBase.raw !== latest.raw) {
+        base = commitBase;
+        continue;
+      }
+
+      const projected = projectCustomModelCatalogMigration(
+        commitBase.diagnostics.config,
+        projectConfigRebaseProvenance(confirmedConfig),
+      );
+      if (persistConfigUnlocked(projected)) bumpGenerationForCooperatingConfigWrite();
+      return { status: "committed", value: confirmed.value };
+    }
+    return { status: "unavailable", reason: "conflict" };
+  });
+}

package/src/config/provider-validation.ts

@@ -370,7 +370,7 @@ export function modelAdapterRecordConfigError(
     if (typeof entry !== "string" || !MODEL_ADAPTER_OVERRIDE_ALLOWED.has(entry)) {
       return `${field}.${key} must be one of: ${[...MODEL_ADAPTER_OVERRIDE_ALLOWED].join(", ")}`;
     }
-    if (isWirePinnedModel(providerName, key.trim())) {
+    if (isWirePinnedModel(providerName, key.trim(), provider)) {
       return `${field}.${key} cannot be overridden: the upstream only speaks one wire for this model`;
     }
   }

package/src/config/proxy-env.ts

@@ -1,4 +1,4 @@
-import { configureSocks5Fetch } from "../lib/proxy-env";
+import { configureSocks5Fetch, socks5ProxyFromEnv } from "../lib/proxy-env";
 import { redactUrlForLog } from "../lib/redact";
 import { join } from "node:path";
 import { DEFAULT_SUBAGENT_MODELS, SUBAGENT_MODELS_VERSION } from "./subagent-models";
@@ -98,6 +98,60 @@ function warnProxyConfigDiscardOnce(kind: "proxy" | "noProxy" | "noProxyElements
   }
 }
 
+const LOOPBACK_NO_PROXY = ["localhost", "127.0.0.1", "::1", "[::1]"] as const;
+const LOOPBACK_ADDRESS_NO_PROXY = ["127.0.0.1", "::1", "[::1]"] as const;
+
+// With no config.proxy, which loopback bypasses are written depends on who reads them. The
+// installed SOCKS fetch wrapper (src/lib/proxy-env.ts configuredOutboundFetch) matches these
+// entries as exact hosts. Bun applies an inherited HTTP(S) proxy itself and matches NO_PROXY
+// entries as domain suffixes, so a bare "localhost" there would also send any *.localhost name
+// direct, including from a fetch that never passes the wrapper. The full list is therefore
+// written only when an inherited SOCKS proxy is the only one. Whenever Bun applies an inherited
+// HTTP(S) proxy, only the loopback addresses are added: they cannot widen that way (a URL host
+// ending in a numeric label parses as IPv4) and keep local health and management calls to
+// 127.0.0.1 off the proxy. A proxy-free process is left untouched: writing NO_PROXY into it is
+// itself a proxy-env mutation callers observe (the lab sandbox rejects these keys).
+function inheritedLoopbackBypass(): readonly string[] | undefined {
+  const schemeProxy = ["HTTP_PROXY", "HTTPS_PROXY", "http_proxy", "https_proxy"].some(key => process.env[key]?.trim());
+  const httpAllProxy = ["ALL_PROXY", "all_proxy"].some(key => {
+    const value = process.env[key]?.trim();
+    if (!value) return false;
+    try {
+      return ["http:", "https:"].includes(new URL(value).protocol);
+    } catch {
+      return false;
+    }
+  });
+  if (schemeProxy || httpAllProxy) return LOOPBACK_ADDRESS_NO_PROXY;
+  return socks5ProxyFromEnv() !== undefined ? LOOPBACK_NO_PROXY : undefined;
+}
+
+function withNoProxyEntries(existing: string, configured: readonly string[], loopback: readonly string[]): string {
+  const entries = existing.split(",").map(s => s.trim()).filter(Boolean);
+  const seen = new Set(entries.map(entry => entry.toLowerCase()));
+  for (const host of [...configured, ...loopback]) {
+    const key = host.toLowerCase();
+    if (!seen.has(key)) {
+      entries.push(host);
+      seen.add(key);
+    }
+  }
+  return entries.join(",");
+}
+
+function mergeNoProxyEntries(configured: readonly string[] = [], loopback: readonly string[] = LOOPBACK_NO_PROXY): void {
+  process.env.NO_PROXY = withNoProxyEntries(process.env.NO_PROXY ?? process.env.no_proxy ?? "", configured, loopback);
+  // Bun's native fetch reads a non-empty lowercase no_proxy before NO_PROXY
+  // (src/codex/catalog/remote.ts), so an inherited one would shadow the loopback entries above.
+  // Only the loopback addresses join it: Bun matches entries as domain suffixes, and any name
+  // (a bare "localhost", or a configured noProxy entry the inherited value always shadowed)
+  // would send its subdomains past a proxy the inherited value kept them on.
+  const inherited = process.env.no_proxy;
+  if (inherited !== undefined && inherited.trim() !== "") {
+    process.env.no_proxy = withNoProxyEntries(inherited, [], loopback.filter(host => host !== "localhost"));
+  }
+}
+
 /**
  * Mirror `config.proxy` into HTTP(S)_PROXY env vars. Bun fetch consumes them natively; transports
  * such as the ChatGPT upstream WebSocket select the same environment explicitly. User-set HTTP(S)_PROXY
@@ -130,6 +184,12 @@ export function applyProxyEnvWith(
   let proxy = typeof rawProxy === "string" ? resolveEnvValue(rawProxy) : undefined;
   if (!proxy) {
     if (rawProxy !== undefined) warnProxyConfigDiscardOnce("proxy");
+    // Inherited-SOCKS path: only loopback bypasses are appended. A configured noProxy is
+    // deliberately NOT merged here — with no config.proxy the operator's bypass list has
+    // no declared proxy to apply against, and merging it would silently widen direct
+    // egress beyond the loopback fix this branch exists for.
+    const loopback = inheritedLoopbackBypass();
+    if (loopback) mergeNoProxyEntries([], loopback);
     configureSocks5Fetch();
     return;
   }
@@ -178,9 +238,6 @@ export function applyProxyEnvWith(
       if (!process.env.HTTPS_PROXY?.trim() && !process.env.https_proxy?.trim()) process.env.HTTPS_PROXY = proxy;
     }
   }
-  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()));
   // 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;
@@ -200,13 +257,6 @@ export function applyProxyEnvWith(
   const configured = configuredEntries
     .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(key);
-    }
-  }
-  process.env.NO_PROXY = entries.join(",");
+  mergeNoProxyEntries(configured);
   configureSocks5Fetch();
 }

package/src/config/rebase-provenance.ts

@@ -1,8 +1,17 @@
 import type { OcxConfig } from "../types";
 
 const pendingTopLevelDeletions = new WeakMap<OcxConfig, Set<string>>();
+const pendingObjectChildDeletions = new WeakMap<OcxConfig, Map<string, Set<string>>>();
 export const CONFIG_REBASE_PROVENANCE_KEY = "configRebaseProvenance";
 
+export type ConfigObjectChildDeletions = Map<string, Set<string>>;
+
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
 export function parsedConfigRebaseDeletionKeys(config: OcxConfig): Set<string> | null {
   const value = config.configRebaseProvenance;
   if (!value || typeof value !== "object" || Array.isArray(value)) return null;
@@ -63,15 +72,79 @@ export function deleteConfigTopLevelKey<K extends keyof OcxConfig>(config: OcxCo
   pendingTopLevelDeletions.set(config, deleted);
 }
 
+/** Delete one child from a record-valued field without tombstoning concurrent sibling keys. */
+export function deleteConfigObjectChildKey<K extends keyof OcxConfig>(
+  config: OcxConfig,
+  key: K,
+  childKey: string,
+): void {
+  const record = config as unknown as Record<string, unknown>;
+  const value = record[key as string];
+  if (isPlainRecord(value)) {
+    delete value[childKey];
+    if (Object.keys(value).length === 0) delete record[key as string];
+  }
+  const byParent = pendingObjectChildDeletions.get(config) ?? new Map<string, Set<string>>();
+  const deleted = byParent.get(key as string) ?? new Set<string>();
+  deleted.add(childKey);
+  byParent.set(key as string, deleted);
+  pendingObjectChildDeletions.set(config, byParent);
+}
+
+/**
+ * Materialize record containers so the normal recursive three-way merge can adopt
+ * concurrent sibling keys. Returned child tombstones must be applied after that merge.
+ */
+export function prepareConfigObjectChildDeletionRebase(config: OcxConfig): ConfigObjectChildDeletions {
+  const pending = pendingObjectChildDeletions.get(config);
+  const active: ConfigObjectChildDeletions = new Map();
+  if (!pending) return active;
+  const record = config as unknown as Record<string, unknown>;
+  for (const [key, children] of pending) {
+    const current = record[key];
+    const deleted = new Set([...children].filter(child =>
+      !isPlainRecord(current) || !Object.hasOwn(current, child) || current[child] === undefined));
+    if (deleted.size === 0) continue;
+    active.set(key, deleted);
+    if (!isPlainRecord(current)) record[key] = {};
+  }
+  return active;
+}
+
+/** Reassert explicit child deletions after rebasing, then omit an empty parent record. */
+export function applyConfigObjectChildDeletions(
+  config: OcxConfig,
+  deletions: ConfigObjectChildDeletions,
+): void {
+  const record = config as unknown as Record<string, unknown>;
+  for (const [key, children] of deletions) {
+    const current = record[key];
+    if (!isPlainRecord(current)) continue;
+    for (const child of children) delete current[child];
+    if (Object.keys(current).length === 0) delete record[key];
+  }
+}
+
 export function clearPendingConfigTopLevelDeletions(config: OcxConfig): void {
   pendingTopLevelDeletions.delete(config);
 }
 
+export function clearPendingConfigObjectChildDeletions(config: OcxConfig): void {
+  pendingObjectChildDeletions.delete(config);
+}
+
+/** Consume both kinds of pending deletion only after a successful config publication. */
+export function clearPendingConfigDeletions(config: OcxConfig): void {
+  clearPendingConfigObjectChildDeletions(config);
+  clearPendingConfigTopLevelDeletions(config);
+}
+
 /**
  * Capture field replacements and deletion intent for a synchronous live-config save.
  * Restore before yielding on failure: an asynchronous rollback could overwrite a newer
  * mutation. Descriptors preserve absent versus explicitly undefined properties; the
- * private pending set must also retain its original presence, even when it was empty.
+ * private pending deletion collections must also retain their original presence, even when empty.
+ * Nested values are not cloned: callers must replace containers before mutating their children.
  * Unrelated fields and the live object's identity/baselines are left in place.
  */
 export function captureConfigTopLevelRollback(
@@ -82,6 +155,9 @@ export function captureConfigTopLevelRollback(
     .map(key => [key, Object.getOwnPropertyDescriptor(config, key)] as const));
   const pending = pendingTopLevelDeletions.get(config);
   const pendingBefore = pending === undefined ? undefined : new Set(pending);
+  const pendingChildren = pendingObjectChildDeletions.get(config);
+  const childrenBefore = pendingChildren === undefined ? undefined
+    : new Map([...pendingChildren].map(([key, children]) => [key, new Set(children)]));
   return () => {
     for (const [key, descriptor] of descriptors) {
       if (descriptor) Object.defineProperty(config, key, descriptor);
@@ -90,5 +166,8 @@ export function captureConfigTopLevelRollback(
     // The absent fields above are restoration, not new user deletion commands.
     if (pendingBefore === undefined) pendingTopLevelDeletions.delete(config);
     else pendingTopLevelDeletions.set(config, new Set(pendingBefore));
+    if (childrenBefore === undefined) pendingObjectChildDeletions.delete(config);
+    else pendingObjectChildDeletions.set(config,
+      new Map([...childrenBefore].map(([key, children]) => [key, new Set(children)])));
   };
 }

package/src/config/schema/config-schema.ts

@@ -5,6 +5,7 @@ import {
   clientConnectionSchema,
   CODEX_ACCOUNT_PIN_PATTERN,
   codexAccountPrioritiesSchema,
+  salvageCodexAccountAutoSwitchThresholds,
   codexPoolSchema,
   codexQuotaAutoRefreshSchema,
   credentialGroupsSchema,
@@ -217,6 +218,10 @@ export const configSchema = z.object({
   // typo cannot trip the backup-and-defaults repair path and wipe providers or
   // pool accounts. Warning emitted in loadConfig.
   codexAccountPriorities: codexAccountPrioritiesSchema.optional().catch(undefined),
+  // A bad hand-edited entry must not retire valid overrides on the next unrelated save.
+  codexAccountAutoSwitchThresholds: z.unknown().optional().transform(salvageCodexAccountAutoSwitchThresholds),
+  // An invalid optional preference must not discard providers or credential rows.
+  codexAccountPriorityFailback: z.boolean().optional().catch(false),
   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.

package/src/config/schema/leaf-validators.ts

@@ -14,6 +14,7 @@ import {
 } from "../provider-validation";
 import { isValidCodexAccountNamespaceTarget } from "../../codex/account-namespace-match";
 import { isCodexAccountPriorityKey } from "../../codex/account-priority";
+import { isCodexAccountAutoSwitchThresholdKey, parseCodexAutoSwitchThreshold } from "../../codex/account-auto-switch";
 import { parseAccountPriority } from "../../codex/pool-rotation";
 import { credentialGroupIssues } from "../../routing/identity-domains";
 import { providerDestinationConfigError } from "../../lib/destination-policy";
@@ -490,7 +491,7 @@ export function modelPreferHostedToolsConfigError(
     ? (provider.modelAdapters as Record<string, unknown>)[modelId]
     : undefined;
   const resolveEffectiveWire = (modelId: string, currentWire: unknown): unknown => {
-    const pinned = pinnedWireAdapter(providerName, modelId);
+    const pinned = pinnedWireAdapter(providerName, modelId, provider);
     if (pinned) return pinned;
     const requestedWire = requestedWireFor(modelId);
     if (typeof requestedWire === "string" && MODEL_ADAPTER_OVERRIDE_ALLOWED.has(requestedWire)) {
@@ -633,6 +634,54 @@ const codexQuotaAutoRefreshEntrySchema = z.object({
 const CODEX_QUOTA_AUTO_REFRESH_KEY_ERROR =
   "quota auto-refresh keys must be a Codex pool-account id or the main Codex account and cannot be reserved JavaScript object keys";
 
+const CODEX_ACCOUNT_AUTO_SWITCH_THRESHOLDS_RECORD_ERROR =
+  "codexAccountAutoSwitchThresholds must be a plain object mapping Codex account ids to usage thresholds";
+const CODEX_ACCOUNT_AUTO_SWITCH_THRESHOLD_KEY_ERROR =
+  "usage-threshold keys must be a Codex pool-account id or the main Codex account and cannot be reserved JavaScript object keys";
+const CODEX_ACCOUNT_AUTO_SWITCH_THRESHOLD_VALUE_ERROR =
+  "account usage threshold must be an integer between 0 and 100";
+
+export const codexAccountAutoSwitchThresholdsSchema = 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_AUTO_SWITCH_THRESHOLDS_RECORD_ERROR },
+).superRefine((thresholds, ctx) => {
+  for (const [accountId, threshold] of Object.entries(thresholds)) {
+    if (!isCodexAccountAutoSwitchThresholdKey(accountId)) {
+      ctx.addIssue({
+        code: "custom",
+        path: [accountId],
+        message: CODEX_ACCOUNT_AUTO_SWITCH_THRESHOLD_KEY_ERROR,
+      });
+    }
+    if (parseCodexAutoSwitchThreshold(threshold) === null) {
+      ctx.addIssue({
+        code: "custom",
+        path: [accountId],
+        message: CODEX_ACCOUNT_AUTO_SWITCH_THRESHOLD_VALUE_ERROR,
+      });
+    }
+  }
+}).pipe(z.record(z.string(), z.number().int()));
+
+/** Load only: retain valid overrides from a hand-edited map; writes use the strict schema above. */
+export function salvageCodexAccountAutoSwitchThresholds(value: unknown): Record<string, number> | undefined {
+  const parsed = codexAccountAutoSwitchThresholdsSchema.safeParse(value);
+  if (parsed.success) return parsed.data;
+  if (!value || typeof value !== "object" || Array.isArray(value)
+    || ![Object.prototype, null].includes(Object.getPrototypeOf(value))) return undefined;
+  const valid: Record<string, number> = Object.create(null);
+  for (const [accountId, threshold] of Object.entries(value)) {
+    const parsedThreshold = parseCodexAutoSwitchThreshold(threshold);
+    if (isCodexAccountAutoSwitchThresholdKey(accountId) && parsedThreshold !== null) {
+      valid[accountId] = parsedThreshold;
+    }
+  }
+  return Object.keys(valid).length ? valid : undefined;
+}
+
 export const codexQuotaAutoRefreshSchema = z.custom<Record<string, unknown>>(
   (value): value is Record<string, unknown> => !!value
     && typeof value === "object"

package/src/config/subagent-models.ts

@@ -1,24 +1,50 @@
 import type { OcxConfig } from "../types";
-import { NATIVE_GPT6_ASTRA_MODEL } from "../codex/catalog/native-models";
+import { NATIVE_GPT6_ASTRA_MODEL, NATIVE_GPT6_LUNA_MODEL, NATIVE_GPT6_SOL_MODEL } from "../codex/catalog/native-models";
 
-export const SUBAGENT_MODELS_VERSION = 1;
+export const SUBAGENT_MODELS_VERSION = 2;
 
-/** Native featured defaults; Codex advertises at most five picker-visible rows. */
-export const DEFAULT_SUBAGENT_MODELS = [
-  NATIVE_GPT6_ASTRA_MODEL, "gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", "gpt-5.5",
-];
+/** Native featured defaults: the GPT-6 trio. Codex advertises at most five picker-visible rows. */
+export const DEFAULT_SUBAGENT_MODELS = [NATIVE_GPT6_ASTRA_MODEL, NATIVE_GPT6_SOL_MODEL, NATIVE_GPT6_LUNA_MODEL];
 
-/** One-time upgrade; later user edits (including removing Astra) remain authoritative. */
+/** Bare native families the version-2 upgrade removes from a roster. */
+const RETIRED_ROSTER_FAMILY = /^gpt-5\.[56](?:-|$)/;
+/** Retired rows whose GPT-6 successor takes their place. */
+const ROSTER_SUCCESSORS: ReadonlyMap<string, string> = new Map([
+  ["gpt-5.6-sol", NATIVE_GPT6_SOL_MODEL],
+  ["gpt-5.6-luna", NATIVE_GPT6_LUNA_MODEL],
+]);
+const SUCCESSOR_IDS = new Set(ROSTER_SUCCESSORS.values());
+
+/**
+ * Replace Sol/Luna with their GPT-6 rows and drop every other bare 5.5/5.6 id, in place order.
+ * Ids with a "/" name a routed or account-qualified target and keep their exact spelling.
+ * A list that only held retired rows receives the defaults instead of becoming empty.
+ */
+function upgradeRetiredRosterRows(models: readonly string[]): string[] {
+  const upgraded: string[] = [];
+  for (const model of models) {
+    const next = ROSTER_SUCCESSORS.get(model) ?? (RETIRED_ROSTER_FAMILY.test(model) ? null : model);
+    if (next === null || (SUCCESSOR_IDS.has(next) && upgraded.includes(next))) continue;
+    upgraded.push(next);
+  }
+  return upgraded.length === 0 && models.length > 0 ? [...DEFAULT_SUBAGENT_MODELS] : upgraded;
+}
+
+/** One-time upgrades; later user edits (including removing Astra) remain authoritative. */
 export function migrateSubagentModels(config: OcxConfig): boolean {
-  if ((config.subagentModelsVersion ?? 0) >= SUBAGENT_MODELS_VERSION) return false;
-  if (config.subagentModels === undefined) {
-    config.subagentModels = [...DEFAULT_SUBAGENT_MODELS];
-  } else {
-    const retained = [...new Set([NATIVE_GPT6_ASTRA_MODEL, ...config.subagentModels])].slice(0, 5);
-    // Cap first: do not rescue a fifth old choice. Retained 5.5 belongs at the bottom.
-    config.subagentModels = retained.filter(model => model !== "gpt-5.5");
-    if (retained.includes("gpt-5.5")) config.subagentModels.push("gpt-5.5");
+  const version = config.subagentModelsVersion ?? 0;
+  if (version >= SUBAGENT_MODELS_VERSION) return false;
+  if (version < 1) {
+    if (config.subagentModels === undefined) {
+      config.subagentModels = [...DEFAULT_SUBAGENT_MODELS];
+    } else {
+      const retained = [...new Set([NATIVE_GPT6_ASTRA_MODEL, ...config.subagentModels])].slice(0, 5);
+      // Cap first: do not rescue a fifth old choice. Retained 5.5 belongs at the bottom.
+      config.subagentModels = retained.filter(model => model !== "gpt-5.5");
+      if (retained.includes("gpt-5.5")) config.subagentModels.push("gpt-5.5");
+    }
   }
+  if (config.subagentModels !== undefined) config.subagentModels = upgradeRetiredRosterRows(config.subagentModels);
   config.subagentModelsVersion = SUBAGENT_MODELS_VERSION;
   return true;
 }

package/src/config.ts

@@ -8,9 +8,9 @@ import {
   adoptCustomModelCatalogMigration,
   projectCustomModelCatalogMigration,
 } from "./codex/custom-model-catalog-migration";
-import { refreshUserCostOverlays } from "./usage/user-cost-overlays";
+import { refreshConfigDerivedRegistries } from "./config/derived-registries";
 import {
-  clearPendingConfigTopLevelDeletions,
+  clearPendingConfigDeletions,
   projectConfigRebaseProvenance,
 } from "./config/rebase-provenance";
 import { getConfigDir, getConfigPath, hardenConfigDir } from "./config/paths";
@@ -53,6 +53,12 @@ export {
   type RuntimePortState,
 } from "./config/process-state";
 export { deleteConfigTopLevelKey } from "./config/rebase-provenance";
+export {
+  mutatePersistedConfig,
+  setPersistedConfigMutationBeforeCommitForTests,
+  type PersistedConfigMutation,
+  type PersistedConfigMutationOutcome,
+} from "./config/persisted-mutation";
 export { isValidProviderName, hasOwnProvider } from "./config/provider-name";
 export {
   apiKeyTransportConfigError,
@@ -146,9 +152,7 @@ import { observeInitialConfigState } from "./config/diagnostics";
 import {
   configDiagnosticsFromRaw,
   mergeConfigDefaults,
-  readConfigFileSnapshot,
   validateConfigCandidate,
-  type ConfigFileSnapshot,
 } from "./config/diagnostics";
 
 // replace path — never publishInitialConfigNoReplace
@@ -247,6 +251,13 @@ export function loadConfig(): OcxConfig {
       warnDegradedCredentialGroups(parsed);
       return withRefreshedCostOverlays(normalizeClaudeSubagentEffort(normalizeNativeSubagentSync(config, parsed), parsed));
     }
+    // Only object-shaped configs are repairable. Spreading another JSON value
+    // into defaults can manufacture a valid config and bypass the invalid-file
+    // backup.
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      warnAndBackupInvalidConfig(configPath, result.error);
+      return getDefaultConfig();
+    }
     // Schema validation failed — merge defaults into the raw object instead of
     // discarding it entirely, so pool accounts and providers survive a missing
     // field like defaultProvider.
@@ -343,8 +354,8 @@ export function initializePersistedConfigIfMissing(
     adoptCustomModelCatalogMigration(config, persisted);
     if (persisted.configRebaseProvenance === undefined) delete config.configRebaseProvenance;
     else config.configRebaseProvenance = structuredClone(persisted.configRebaseProvenance);
-    clearPendingConfigTopLevelDeletions(config);
-    refreshUserCostOverlays(persisted);
+    clearPendingConfigDeletions(config);
+    refreshConfigDerivedRegistries(persisted);
     return "created";
   } catch (cause) {
     if (published) throw new InitialConfigPublicationError("published", false, false, { cause });
@@ -367,94 +378,6 @@ export function saveConfig(config: OcxConfig): void {
     adoptCustomModelCatalogMigration(config, withProvenance);
     if (withProvenance.configRebaseProvenance === undefined) delete config.configRebaseProvenance;
     else config.configRebaseProvenance = structuredClone(withProvenance.configRebaseProvenance);
-    clearPendingConfigTopLevelDeletions(config);
-  });
-}
-
-export type PersistedConfigMutation<T> = {
-  changed: boolean;
-  value: T;
-};
-
-export type PersistedConfigMutationOutcome<T> =
-  | { status: "committed" | "unchanged"; value: T }
-  | { status: "unavailable"; reason: "missing" | "invalid" | "conflict" };
-
-const CONFIG_MUTATION_MAX_REBASE_ATTEMPTS = 3;
-let persistedConfigMutationBeforeCommitForTests: (() => void) | null = null;
-
-/** Test-only one-shot seam: inject a competing mutation after the first decision, before freshness revalidation. */
-export function setPersistedConfigMutationBeforeCommitForTests(hook: (() => void) | null): void {
-  persistedConfigMutationBeforeCommitForTests = hook;
-}
-
-function unavailableConfigMutationReason(snapshot: ConfigFileSnapshot): "missing" | "invalid" {
-  return snapshot.diagnostics.source === "default" ? "missing" : "invalid";
-}
-
-/**
- * Patch a schema-valid on-disk config under the shared mutation lock. Cooperating writers are
- * serialized; the callback is rerun on the newest snapshot so observed direct byte changes rebase
- * and credential predicates are re-evaluated immediately before the atomic commit. A writer that
- * ignores the coordinator can still change bytes after the final check because the filesystem has
- * no portable conditional rename. Missing or malformed config always fails closed and is never
- * recreated from a prior snapshot.
- */
-export function mutatePersistedConfig<T>(
-  mutate: (config: OcxConfig) => PersistedConfigMutation<T>,
-): PersistedConfigMutationOutcome<T> {
-  // Avoid creating/opening the coordinator database for a read-path update that already knows
-  // there is no valid config. The same check runs again under the transaction for authority.
-  const observed = readConfigFileSnapshot();
-  if (observed.diagnostics.source !== "file" || observed.raw === undefined) {
-    return { status: "unavailable", reason: unavailableConfigMutationReason(observed) };
-  }
-  return withConfigMutationLockSync(() => {
-    let base = readConfigFileSnapshot();
-    for (let attempt = 0; attempt < CONFIG_MUTATION_MAX_REBASE_ATTEMPTS; attempt += 1) {
-      if (base.diagnostics.source !== "file" || base.raw === undefined) {
-        return { status: "unavailable", reason: unavailableConfigMutationReason(base) };
-      }
-
-      const tentativeConfig = structuredClone(base.diagnostics.config);
-      const tentative = mutate(tentativeConfig);
-      if (!tentative.changed) return { status: "unchanged", value: tentative.value };
-
-      const hook = persistedConfigMutationBeforeCommitForTests;
-      persistedConfigMutationBeforeCommitForTests = null;
-      hook?.();
-
-      const latest = readConfigFileSnapshot();
-      if (latest.diagnostics.source !== "file" || latest.raw === undefined) {
-        return { status: "unavailable", reason: unavailableConfigMutationReason(latest) };
-      }
-      if (latest.raw !== base.raw) {
-        base = latest;
-        continue;
-      }
-
-      // Re-run against a fresh clone even when config bytes are unchanged: a Codex credential
-      // generation lives in a separate file and may have changed at the injected seam.
-      const confirmedConfig = structuredClone(latest.diagnostics.config);
-      const confirmed = mutate(confirmedConfig);
-      if (!confirmed.changed) return { status: "unchanged", value: confirmed.value };
-
-      const commitBase = readConfigFileSnapshot();
-      if (commitBase.diagnostics.source !== "file" || commitBase.raw === undefined) {
-        return { status: "unavailable", reason: unavailableConfigMutationReason(commitBase) };
-      }
-      if (commitBase.raw !== latest.raw) {
-        base = commitBase;
-        continue;
-      }
-
-      const projected = projectCustomModelCatalogMigration(
-        commitBase.diagnostics.config,
-        projectConfigRebaseProvenance(confirmedConfig),
-      );
-      if (persistConfigUnlocked(projected)) bumpGenerationForCooperatingConfigWrite();
-      return { status: "committed", value: confirmed.value };
-    }
-    return { status: "unavailable", reason: "conflict" };
+    clearPendingConfigDeletions(config);
   });
 }