UNPKG

@bitkyc08/opencodex

Version:

Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code

1,205 lines • 65.6 kB
import { isSubagentModelEntry, rawSubagentModelForce } from "./subagent-models";
import { chmodSync, existsSync } from "node:fs";
import { join } from "node:path";
import { compactionRecoveryConfigError } from "./schema/compaction-recovery";
import { nativeReasoningRetentionConfigError } from "./schema/native-reasoning-retention";
import { workflowBudgetConfigError } from "./schema/workflow-budget";
import { routedCatalogDefaultsConfigError } from "./schema/routed-catalog-defaults";
import { desktopCompatibilityConfigError } from "./schema/desktop-compatibility";
import { blockedModelRedirectsError } from "./schema/blocked-model-redirects";
import { mainAccountHardLockFallbackError } from "./schema/main-account-hard-lock-fallback";
import { fallbackPolicyError } from "./schema/fallback-policy";
import { subscriptionReserveConfigError } from "./schema/subscription-reserve";
import { anthropicSidecarConfigError } from "./schema/anthropic-account-pool";
import { agyAcpProviderFieldIssues, agyAcpUnattendedTargetIssues } from "./schema/agy-acp-references";
import {
  modelPinnedEffortsConfigError,
  pinnedReasoningEffortConfigError,
  autoReviewOverrideConfigError,
  autoReviewModelOverridesConfigError,
  autoReviewModelTargetConfigError,
  modelCapabilitiesConfigError,
  providerInputModalitiesConfigError,
  sanitizeModelCapabilitiesForLoad,
  modelDisplayNamesConfigError,
} from "./provider-validation";
import { UPSTREAM_HOST_CIRCUIT_MAX_THRESHOLD } from "../codex/upstream-host-health";
import { hardenSecretPath } from "../lib/windows-secret-acl";
import { isPassiveRead } from "../lib/passive-read";
import { redactSecretString } from "../lib/redact";
import { isValidProviderName } from "./provider-name";
import { MODEL_ALIAS_PATTERN } from "../providers/default-aliases";
import { aliasTemplateError } from "../providers/alias-template";
import { MODEL_DISCOVERY_MAX_MODELS } from "../providers/model-discovery-limits";
import { getProviderRegistryEntry, providerMatchesRegistryTransport, registryModelServiceTierCapabilityApplies } from "../providers/registry";
import { providerFastSwitchOff } from "../providers/fast-opt-in";
import { isCodexReasoningEffort } from "../reasoning-effort";
import { refreshConfigDerivedRegistries } from "./derived-registries";
import { type OcxClaudeCodeConfig, type OcxConfig } from "../types";
import {
  agentTaskRecoverySchema,
  asideProfileSyncSchema,
  catalogAutoRefreshSchema,
  clientConnectionSchema,
  isUsableApiKeySecret,
  managementIngressSchema,
  codexAuthMethodSchema,
  codexPoolSchema,
  codexAccountAutoSwitchThresholdsSchema,
  providerModelCostsConfigError,
  credentialGroupsSchema,
  hubConfigSchema,
  quotaResetNotifySchema,
  remoteGuiConfigSchema,
  retryOn429PolicySchema,
  retryOnResetPolicySchema,
  transientRetryOn5xxPolicySchema,
  runtimeRoleSchema,
  spendSchema,
  telemetryConfigSchema,
  chatgptDesktopConfigIssue,
  isValidCreditPriceUsd,
} from "./schema/leaf-validators";
import { hasWarnedInheritedFastWireConflict, markWarnedInheritedFastWireConflict } from "./warn-memo";

export function hardenExistingSecret(path: string): void {
  if (existsSync(path) && !isPassiveRead()) {
    if (process.platform === "win32") {
      // Preserve the ACL helper's metadata observation across reads. Windows chmod does
      // not establish a private DACL and can invalidate that observation before every load.
      hardenSecretPath(path, { required: false });
    } else {
      try { chmodSync(path, 0o600); } catch { /* best-effort */ }
    }
  }
}
/** Load only: discard invalid optional pins without rewriting the file or losing providers. */
export function sanitizeReasoningPinsForLoad(parsed: unknown, warn: (message: string) => void = console.warn): void {
  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return;
  const root = parsed as Record<string, unknown>;
  let degraded = false;
  const sanitizeMap = (owner: Record<string, unknown>, field: string) => {
    const value = owner[field];
    if (value === undefined) return;
    if (!value || typeof value !== "object" || Array.isArray(value)
      || ![Object.prototype, null].includes(Object.getPrototypeOf(value))) {
      delete owner[field];
      degraded = true;
      return;
    }
    const counts = new Map<string, number>();
    for (const key of Object.keys(value)) counts.set(key.trim(), (counts.get(key.trim()) ?? 0) + 1);
    const valid: Record<string, string> = Object.create(null);
    for (const [key, effort] of Object.entries(value)) {
      if (counts.get(key.trim()) !== 1 || modelPinnedEffortsConfigError({ [key]: effort }) !== null) {
        degraded = true;
        continue;
      }
      valid[key.trim()] = effort as string;
    }
    if (Object.keys(valid).length) owner[field] = valid;
    else delete owner[field];
  };
  sanitizeMap(root, "modelPinnedEfforts");
  if (root.providers && typeof root.providers === "object" && !Array.isArray(root.providers)) {
    for (const value of Object.values(root.providers)) {
      if (!value || typeof value !== "object" || Array.isArray(value)) continue;
      const provider = value as Record<string, unknown>;
      if (pinnedReasoningEffortConfigError(provider.pinnedReasoningEffort)) {
        delete provider.pinnedReasoningEffort;
        degraded = true;
      }
      sanitizeMap(provider, "modelPinnedReasoningEfforts");
    }
  }
  // Never include a provider/model name or value: malformed pins can contain secrets.
  if (degraded) warn("config.json contains invalid optional reasoning pins — ignoring invalid fields or entries");
}

/**
 * The schema's `.catch(undefined)` silently degrades an invalid persisted
 * `streamMode` to "auto"; surface that once so a hand-edited typo (e.g.
 * "legacy_tee") is discoverable instead of silently changing stream shape.
 */
export function warnDegradedStreamMode(rawParsed: unknown, validated: OcxConfig): void {
  if (!rawParsed || typeof rawParsed !== "object") return;
  const raw = (rawParsed as Record<string, unknown>).streamMode;
  if (raw !== undefined && validated.streamMode === undefined) {
    console.warn(`⚠️  config.json streamMode ${JSON.stringify(raw)} is invalid (expected "auto", "legacy-tee", or "eager-relay") — falling back to "auto"`);
  }
}

export function warnDegradedCompactionRouting(rawParsed: unknown, validated: OcxConfig): void {
  if (!rawParsed || typeof rawParsed !== "object") return;
  const raw = (rawParsed as Record<string, unknown>).compactionRouting;
  if (raw !== undefined && validated.compactionRouting === undefined) {
    console.warn("⚠️  config.json compactionRouting is invalid (expected { model, reasoningEffort?, triggers? } with a nonblank model, a declared effort, and triggers drawn without repetition from \"manual\" and \"auto\") — compaction keeps the conversation model");
  }
}

/**
 * Top-level opt-in blocks whose hand-edited form degrades to "off" instead of failing the whole
 * schema. Grouped behind one entry point because `src/config.ts` sits at its file-size cap, and
 * the ratchet only ever moves down: a per-block call there costs a line the file does not have.
 */
export function warnDegradedTopLevelOptIns(rawParsed: unknown, validated: OcxConfig): void {
  const codexAuthWarning = malformedCodexAuthMethodWarning(rawParsed);
  if (codexAuthWarning) console.warn(`⚠️  config.json ${codexAuthWarning}`);
  if (nativeReasoningRetentionConfigError(rawParsed)) console.warn("⚠️  invalid nativeReasoningRetention disabled; model and account switch allowances remain off");
  if (workflowBudgetConfigError(rawParsed)) console.warn("⚠️  invalid workflowBudget ignored; the built-in workflow ceilings stay in force");
  if (routedCatalogDefaultsConfigError(rawParsed)) console.warn("⚠️  invalid routedCatalogDefaults ignored; routed catalog rows keep their derived values");
  const retentionWarning = degradedReasoningRetentionWarning(rawParsed, validated);
  if (retentionWarning) console.warn(retentionWarning);
  if (compactionRecoveryConfigError(rawParsed)) console.warn("⚠️  invalid compactionRecovery disabled; the original compaction failure is preserved");
  if (desktopCompatibilityConfigError(rawParsed)) console.warn("Invalid desktopCompatibility startup preference ignored; no desktop compatibility service will start automatically.");
  if (blockedModelRedirectsError(rawParsed)) console.warn("⚠️  invalid blockedModelRedirects ignored; provider routing remains available");
  if (mainAccountHardLockFallbackError(rawParsed)) console.warn("⚠️  invalid codexMainAccountHardLockFallback ignored; the main-account hard lock still refuses while blocked");
  if (fallbackPolicyError(rawParsed)) console.warn("⚠️  invalid fallback leaves ignored; those scopes keep today's fallback behavior");
  if (subscriptionReserveConfigError(rawParsed)) console.warn("⚠️  invalid subscriptionReserve disabled; Claude subscription routing remains available");
  const chatgptDesktop = chatgptDesktopConfigIssue(rawParsed);
  if (chatgptDesktop) console.warn(`⚠️  config.json ${chatgptDesktop} — the whole chatgptDesktop block is ignored, so the ChatGPT desktop integration reads as off`);
  warnDegradedStreamMode(rawParsed, validated);
  warnDegradedCompactionRouting(rawParsed, validated);
  warnDegradedMemoryModels(rawParsed, validated);
  warnDegradedTelemetry(rawParsed);
  // The schema replaces a malformed policy with { allProfiles: false }, which silently turns every Aside profile off (#6757).
  const asidePolicy = rawParsed && typeof rawParsed === "object" ? (rawParsed as Record<string, unknown>).asideProfileSync : undefined;
  if (asidePolicy !== undefined && !asideProfileSyncSchema.safeParse(asidePolicy).success) {
    console.warn("⚠️  config.json asideProfileSync is invalid — Aside profile sync falls back to all profiles off; fix the block or inspect `ocx integration client status --client aside`");
  }
}

export function degradedReasoningRetentionWarning(rawParsed: unknown, validated: OcxConfig): string | null {
  if (rawConfigRecord(rawParsed)?.reasoningRetention === undefined || validated.reasoningRetention !== undefined) return null;
  return "config.json reasoningRetention is invalid — reasoning retention is disabled";
}

/**
 * A malformed `memoryModels` phase disables that phase rather than failing the whole schema, so
 * say so once: silently keeping whatever route the phase already had — which may be the shadow
 * intercept rather than Codex's own model — is the outcome a typo must not produce quietly.
 */
export function warnDegradedMemoryModels(rawParsed: unknown, validated: OcxConfig): void {
  if (!rawParsed || typeof rawParsed !== "object") return;
  const raw = (rawParsed as Record<string, unknown>).memoryModels;
  if (raw === undefined) return;
  if (validated.memoryModels === undefined || raw === null || typeof raw !== "object" || Array.isArray(raw)) {
    console.warn("\u26a0\ufe0f  config.json memoryModels is invalid (expected { extract?: { model, reasoningEffort? }, consolidation?: { model, reasoningEffort? } } with a nonblank model and a declared effort per phase) \u2014 the memory pipeline keeps its existing route, which may include shadow-call interception");
    return;
  }
  // A misspelled phase key is stripped by the permissive load schema, so without this warning it
  // disappears silently and the next settings save persists the sanitized map without it.
  for (const key of Object.keys(raw as Record<string, unknown>)) {
    if (key === "extract" || key === "consolidation") continue;
    // Redact and JSON-escape the key name: a malformed hand-edit can place a secret in a property
    // name, and a control character in one must not be able to forge a log line.
    console.warn("\u26a0\ufe0f  config.json memoryModels." + JSON.stringify(redactSecretString(key)) + " is not a recognized phase \u2014 ignoring it");
  }
  for (const phase of ["extract", "consolidation"] as const) {
    if ((raw as Record<string, unknown>)[phase] !== undefined && validated.memoryModels[phase] === undefined) {
      console.warn("\u26a0\ufe0f  config.json memoryModels." + phase + " is invalid (expected { model, reasoningEffort? } with a nonblank model) \u2014 that phase keeps its existing route, which may include shadow-call interception");
    }
  }
}

/** Repair ACP-specific provider fields and unattended selectors on disk reads. */
export function sanitizeAgyAcpForLoad(
  parsed: unknown,
  warn: (message: string) => void = message => console.warn(`⚠️  config.json ${message}`),
): void {
  const root = rawConfigRecord(parsed);
  if (!root) return;
  const report = (issue: ReturnType<typeof agyAcpProviderFieldIssues>[number], repair: string): void => {
    const path = issue.path.map(segment => typeof segment === "string"
      ? redactSecretString(segment).replace(/[\u0000-\u001f\u007f-\u009f\u2028\u2029]/g,
        ch => "\\u" + ch.charCodeAt(0).toString(16).padStart(4, "0"))
      : segment).join(".");
    warn(path + ": " + issue.message + " " + repair);
  };
  // Fallback issues are indexed into their original arrays. Remove later entries first.
  for (const issue of agyAcpUnattendedTargetIssues(root).reverse()) {
    const [section, field, index] = issue.path;
    if (section === "memoryModels" && typeof field === "string") {
      const memory = rawConfigRecord(root.memoryModels);
      if (memory) delete memory[field];
    } else if (section === "injectionModel") {
      root.syncCodexSubagentDefaults = false;
    } else if (section === "compactionRouting") {
      const compaction = rawConfigRecord(root.compactionRouting);
      if (compaction && Array.isArray(compaction.triggers)) {
        const remaining = compaction.triggers.filter(trigger => trigger !== "auto");
        if (remaining.length) compaction.triggers = remaining;
        else delete root.compactionRouting;
      }
    } else if (section === "shadowCallIntercept") {
      const shadow = rawConfigRecord(root.shadowCallIntercept);
      if (shadow) shadow.enabled = false;
    } else if (section === "subagentModelFallback" && Array.isArray(root.subagentModelFallback) && typeof field === "number") {
      root.subagentModelFallback.splice(field, 1);
    } else if (section === "subagentModelFallbackByModel" && typeof field === "string" && typeof index === "number") {
      const byModel = rawConfigRecord(root.subagentModelFallbackByModel);
      const fallback = byModel?.[field];
      if (byModel && Array.isArray(fallback)) {
        fallback.splice(index, 1);
        if (fallback.length === 0) delete byModel[field];
      }
    }
    const repair = section === "injectionModel" ? "Disabling managed subagent default sync on load."
      : section === "compactionRouting" ? "Ignoring the automatic compaction trigger on load."
      : "Ignoring this target on load.";
    report(issue, repair);
  }
  const providers = rawConfigRecord(root.providers);
  // Apply indexed removals from the end so earlier model entries retain their indices.
  for (const issue of agyAcpProviderFieldIssues(root).reverse()) {
    const [, name, field, entry] = issue.path;
    if (typeof name !== "string" || typeof field !== "string") continue;
    const provider = rawConfigRecord(providers?.[name]);
    if (!provider) continue;
    const value = provider[field];
    if (field === "models" && Array.isArray(value) && typeof entry === "number") value.splice(entry, 1);
    else if (field === "modelAliases" && typeof entry === "string") {
      const aliases = rawConfigRecord(value);
      if (aliases) delete aliases[entry];
    } else delete provider[field];
    report(issue, "Ignoring this provider setting on load.");
  }
}

/**
 * Load-time degradation for helper `anthropicInstance` (loadConfig only). A malformed id, or one
 * that conflicts with its block's backend or model, drops just that key with a warning, so the
 * helper inherits the request's pool and every provider/key survives. Validated writes still
 * reject the value and file diagnostics still report it from the raw document.
 *
 * Each location is checked in isolation, global blocks first, so a Claude override is judged
 * against the already-degraded global block it inherits from. An override that owns no
 * `anthropicInstance` of its own is left untouched: the conflicting key lives in the global
 * block, which is valid on its own, and the inherited value is still a well-formed instance.
 */
export function sanitizeAnthropicSidecarInstanceForLoad(parsed: unknown, warn: (message: string) => void = console.warn): void {
  const asRecord = (value: unknown): Record<string, unknown> | undefined =>
    value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
  const root = asRecord(parsed);
  if (!root) return;
  for (const scope of ["global", "claude"] as const) {
    const owner = scope === "global" ? root : asRecord(root.claudeCode);
    for (const field of ["webSearchSidecar", "visionSidecar"] as const) {
      const sidecar = asRecord(owner?.[field]);
      if (!sidecar || !Object.hasOwn(sidecar, "anthropicInstance")) continue;
      const probe = scope === "global"
        ? { [field]: sidecar }
        : { [field]: root[field], claudeCode: { [field]: sidecar } };
      const error = anthropicSidecarConfigError(probe);
      if (!error) continue;
      delete sidecar.anthropicInstance;
      // The message names a static path and reason only; the hand-edited value is never echoed.
      warn(`⚠️  config.json ${error} — ignoring that anthropicInstance; the helper inherits the request's Anthropic pool`);
    }
  }
}

/**
 * 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.
 */
export function sanitizeRetryOn429ForLoad(parsed: unknown, warn: (message: string) => void = console.warn): 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>;
    if (p.cacheAffinity !== undefined && !["auto", "session", "turn", "off"].includes(p.cacheAffinity as string)) {
      delete p.cacheAffinity;
      warn(`⚠️  config.json providers.${safeProviderName}.cacheAffinity is invalid — ignoring the field`);
    }
    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.
      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;
      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 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.
        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;
      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 {
  return strictPolicyConfigError("retryOn429", retryOn429PolicySchema, policy);
}

/**
 * Management write-boundary validation for `retryOnReset`, with the same fail-closed contract
 * as `retryOn429PolicyConfigError`: the load-time schema degrades a malformed block to
 * "absent", so this is the one place a bad value is refused instead of silently dropped.
 */
export function retryOnResetPolicyConfigError(policy: unknown): string | null {
  return strictPolicyConfigError("retryOnReset", retryOnResetPolicySchema, policy);
}

/**
 * Management write-boundary validation for `transientRetryOn5xx`, with the same fail-closed
 * contract as the other retry policies.
 *
 * The load-time schema does not degrade a malformed block: `transientRetryOn5xxPolicySchema` has
 * no `.catch`, so a bad value fails the whole config parse and the loader substitutes the default
 * config, taking every provider with it. That makes this check the only place a malformed ladder
 * can be refused without losing the file, and PATCH never runs the schema — only POST does,
 * through `validateConfigCandidate`.
 */
export function transientRetryOn5xxPolicyConfigError(policy: unknown): string | null {
  return strictPolicyConfigError("transientRetryOn5xx", transientRetryOn5xxPolicySchema, policy);
}

/**
 * The shared body of both. Written once because the two differ only in the field name they
 * report, and a second hand-copied formatter is a second place for the redaction to be
 * forgotten.
 */
function strictPolicyConfigError(
  field: string,
  schema: {
    safeParse: (value: unknown) => { success: true } | {
      success: false;
      error: { issues: Array<{ code: string; message: string; path: PropertyKey[]; keys?: string[] }> };
    };
  },
  policy: unknown,
): string | null {
  if (policy === undefined) return null;
  const result = schema.safeParse(policy);
  if (result.success) return null;
  const first = result.error.issues[0];
  if (!first) return `${field} is invalid`;
  if (first.code === "unrecognized_keys" && first.keys) {
    const names = first.keys.map(key => JSON.stringify(redactSecretString(key))).join(", ");
    return `${field} has unrecognized field${first.keys.length > 1 ? "s" : ""}: ${names}`;
  }
  if (first.path.length === 0) return `${field} is invalid (${first.message})`;
  return `${field}.${String(first.path[first.path.length - 1])} is invalid (${first.message})`;
}

export function sanitizeCapabilityDeclarationsForLoad(parsed: unknown, warn: (message: string) => void = console.warn): void {
  if (!parsed || typeof parsed !== "object") return;
  const providers = (parsed as Record<string, unknown>).providers;
  if (!providers || typeof providers !== "object" || Array.isArray(providers)) return;
  for (const [name, value] of Object.entries(providers)) {
    if (!value || typeof value !== "object" || Array.isArray(value)) continue;
    const provider = value as Record<string, unknown>;
    if (providerInputModalitiesConfigError(provider.inputModalities) !== null) {
      warn(`config.json provider ${JSON.stringify(redactSecretString(name))} has malformed inputModalities; restricting input modalities to text`);
      provider.inputModalities = ["text"];
    }
    if (provider.modelCapabilities === undefined) continue;
    if (modelCapabilitiesConfigError(provider.modelCapabilities) !== null) {
      warn(`config.json provider ${JSON.stringify(redactSecretString(name))} has malformed modelCapabilities; retaining valid axes and restricting malformed input modalities to text`);
      const repaired = sanitizeModelCapabilitiesForLoad(provider.modelCapabilities);
      if (repaired) provider.modelCapabilities = repaired;
      else delete provider.modelCapabilities;
    }
  }
}

/**
 * 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).
 */
export function sanitizeModelCostsForLoad(parsed: unknown, warn: (message: string) => void = console.warn): 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;
      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.
      warn(`⚠️  config.json providers.${safeProviderName}.modelCosts.${JSON.stringify(redactSecretString(modelId))} is invalid — ignoring the row`);
    }
    if (hadEntries && kept === 0) {
      delete p.modelCosts;
      warn(`⚠️  config.json providers.${safeProviderName}.modelCosts has no valid rows left — removing the overlay`);
    }
  }
}

/**
 * Load-time degradation for `providers.<name>.creditPriceUsd`, mirroring
 * {@link sanitizeModelCostsForLoad}: an invalid hand-edited price is dropped with a warning
 * instead of failing the parse and falling back to defaults. The schema still rejects it on writes.
 */
export function sanitizeCreditPriceForLoad(parsed: unknown, warn: (message: string) => void = console.warn): void {
  if (!parsed || typeof parsed !== "object") return;
  const providers = (parsed as Record<string, unknown>).providers;
  if (!providers || typeof providers !== "object" || Array.isArray(providers)) return;
  for (const provider of Object.values(providers as Record<string, unknown>)) {
    if (!provider || typeof provider !== "object" || Array.isArray(provider)) continue;
    const p = provider as Record<string, unknown>;
    if (p.creditPriceUsd === undefined || isValidCreditPriceUsd(p.creditPriceUsd)) continue;
    delete p.creditPriceUsd;
    warn("⚠️  config.json provider has an invalid creditPriceUsd — ignoring the credit price");
  }
}

/**
 * Load-time degradation for provider-scoped auto-review selectors. A malformed
 * hand edit must not fail the whole config parse; the management boundary stays
 * strict and rejects the same shapes before they can be written.
 */
export function sanitizeAutoReviewForLoad(parsed: unknown, warn: (message: string) => void = console.warn): void {
  if (!parsed || typeof parsed !== "object") return;
  const root = parsed as Record<string, unknown>;
  if (root.autoReviewOverride !== undefined
    && autoReviewOverrideConfigError(root.autoReviewOverride) !== null) {
    warn("⚠️  config.json autoReviewOverride is invalid — ignoring the override");
    delete root.autoReviewOverride;
  }
  const providers = root.providers;
  if (!providers || typeof providers !== "object" || Array.isArray(providers)) return;
  for (const [name, providerValue] of Object.entries(providers as Record<string, unknown>)) {
    if (!providerValue || typeof providerValue !== "object" || Array.isArray(providerValue)) continue;
    const provider = providerValue as Record<string, unknown>;
    const safeProviderName = JSON.stringify(redactSecretString(name));
    if (name === "openai") {
      delete provider.autoReviewModel;
      delete provider.autoReviewModelOverrides;
      continue;
    }
    if (provider.autoReviewModel !== undefined
      && autoReviewModelTargetConfigError(provider.autoReviewModel, "autoReviewModel", true) !== null) {
      warn(`⚠️  config.json providers.${safeProviderName}.autoReviewModel is invalid — ignoring the selector`);
      delete provider.autoReviewModel;
    }
    if (provider.autoReviewModelOverrides !== undefined) {
      const overridesError = autoReviewModelOverridesConfigError(
        provider.autoReviewModelOverrides,
        "autoReviewModelOverrides",
        true,
      );
      if (overridesError) {
        warn(`⚠️  config.json providers.${safeProviderName}.autoReviewModelOverrides is invalid — ignoring the map`);
        delete provider.autoReviewModelOverrides;
      }
    }
  }
}

/**
 * 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 —
 * say so once instead of silently ignoring the field.
 */
export function warnDegradedHostname(rawParsed: unknown, validated: OcxConfig): void {
  if (!rawParsed || typeof rawParsed !== "object") return;
  const raw = (rawParsed as Record<string, unknown>).hostname;
  if (raw !== undefined && validated.hostname === undefined) {
    console.warn(`⚠️  config.json hostname ${JSON.stringify(raw)} is not a usable bind address — falling back to 127.0.0.1`);
  }
}

export function degradedListenerWarnings(rawParsed: unknown, validated: OcxConfig): string[] {
  const raw = rawConfigRecord(rawParsed);
  if (!raw) return [];
  const warnings: string[] = [];
  if (raw.unauthenticatedLoopbackListener !== undefined && validated.unauthenticatedLoopbackListener === undefined) {
    warnings.push("unauthenticatedLoopbackListener ignored: invalid listener configuration; repair config.json before enabling the listener");
  }
  const hub = rawConfigRecord(raw.hub);
  if (hub?.managementIngress !== undefined && !managementIngressSchema.safeParse(hub.managementIngress).success) {
    warnings.push("hub.managementIngress ignored: invalid management listener configuration; repair config.json before enabling the listener");
  }
  return warnings;
}

export function warnDegradedListeners(rawParsed: unknown, validated: OcxConfig): void {
  for (const warning of degradedListenerWarnings(rawParsed, validated)) {
    console.warn(`⚠️  config.json ${warning}. Other settings were preserved.`);
  }
}

/**
 * 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.
 */
export 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");
  }
  const rawThresholds = record?.codexAccountAutoSwitchThresholds;
  if (rawThresholds !== undefined && !codexAccountAutoSwitchThresholdsSchema.safeParse(rawThresholds).success) {
    warnings.push(validated.codexAccountAutoSwitchThresholds === undefined
      ? "codexAccountAutoSwitchThresholds is invalid (expected account ids mapped to integers between 0 and 100) — per-account usage thresholds are disabled"
      : "codexAccountAutoSwitchThresholds contains invalid entries (expected account ids mapped to integers between 0 and 100) — invalid entries were ignored");
  }
  return warnings;
}

export function warnDegradedCodexAccountPriorities(rawParsed: unknown, validated: OcxConfig): void {
  for (const warning of degradedCodexAccountPriorityWarnings(rawParsed, validated)) {
    console.warn(`⚠️  config.json ${warning}`);
  }
}

export function degradedCodexQuotaAutoRefreshWarning(rawParsed: unknown, validated: OcxConfig): string | null {
  const raw = rawConfigRecord(rawParsed)?.codexQuotaAutoRefresh;
  if (raw === undefined || validated.codexQuotaAutoRefresh !== undefined) return null;
  return "codexQuotaAutoRefresh is invalid — automatic quota-window activation is disabled";
}

export function warnDegradedCodexQuotaAutoRefresh(rawParsed: unknown, validated: OcxConfig): void {
  const warning = degradedCodexQuotaAutoRefreshWarning(rawParsed, validated);
  if (warning) console.warn(`⚠️  config.json ${warning}`);
}

/**
 * Companion to the degrade warnings above, for a malformed or ambiguous declared
 * grouping. The list now degrades on its own so the rest of `pool` survives, which is
 * also why it needs a voice: nothing else about the config looks different afterwards,
 * and silently ungrouped credentials read as capacity the pool does not have.
 */
export function degradedCredentialGroupsWarning(rawParsed: unknown): string | null {
  const pool = rawConfigRecord(rawConfigRecord(rawParsed)?.pool);
  if (!pool || pool.credentialGroups === undefined) return null;
  const parsed = credentialGroupsSchema.safeParse(pool.credentialGroups);
  if (parsed.success) return null;
  // Every issue message is redacted before it is joined. The custom messages now name
  // group/member positions instead of the offending strings; the redaction stays as a
  // second layer for any schema default message that still embeds a value.
  const details = parsed.error.issues.map(issue => redactSecretString(issue.message)).join("; ");
  return `pool.credentialGroups is invalid (${details}) — declared quota grouping is disabled; other pool settings were preserved`;
}

export function warnDegradedCredentialGroups(rawParsed: unknown): void {
  const warning = degradedCredentialGroupsWarning(rawParsed);
  if (warning) 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
 * mutation. Say so out loud. Compares the raw array against the validated one,
 * the same shape as the degrade warnings above.
 */
/**
 * Give every salvaged key a stable, targetable id.
 *
 * Pure and deterministic on purpose. Two earlier spellings were wrong: minting a
 * UUID inside the schema transform handed out a different id on every parse, and
 * repairing-then-writing during `loadConfig` put a file write on the read path,
 * where it could clobber a concurrent legitimate save with a stale snapshot.
 *
 * So the replacement id is derived from the entry's position, which is already
 * how the file orders these rows: same file in, same ids out, no I/O and no
 * randomness. It is not derived from the secret — a public identifier should
 * never be a function of key material.
 */
export function normalizeApiKeyIds(config: OcxConfig): OcxConfig {
  const keys = config.apiKeys;
  if (!keys?.length) return config;
  // Reserve every explicit id BEFORE synthesizing any, or a synthetic
  // `salvaged-1` assigned to row 1 would push a row that legitimately owns that
  // id onto `salvaged-2`. An id the user already has is the one thing this
  // repair must never take away.
  const reserved = new Set<string>();
  for (const entry of keys) {
    if (entry.id) reserved.add(entry.id);
  }
  const taken = new Set<string>(reserved);
  const kept = new Set<string>();
  keys.forEach((entry, index) => {
    // The first row holding an explicit id keeps it; later collisions are the
    // ones that move.
    if (entry.id && !kept.has(entry.id)) {
      kept.add(entry.id);
      return;
    }
    let candidate = `salvaged-${index + 1}`;
    let suffix = 1;
    while (taken.has(candidate)) candidate = `salvaged-${index + 1}-${++suffix}`;
    entry.id = candidate;
    taken.add(candidate);
    kept.add(candidate);
  });
  return config;
}

export function warnDegradedApiKeys(rawParsed: unknown, validated: OcxConfig): void {
  if (!rawParsed || typeof rawParsed !== "object") return;
  const raw = (rawParsed as Record<string, unknown>).apiKeys;
  if (raw === undefined) return;
  if (!Array.isArray(raw)) {
    console.warn(`⚠️  config.json apiKeys is not an array — ignoring it; generate a new key from the API tab`);
    return;
  }
  const dropped = raw.length - (validated.apiKeys?.length ?? 0);
  if (dropped > 0) {
    console.warn(`⚠️  config.json apiKeys: skipped ${dropped} malformed entr${dropped === 1 ? "y" : "ies"} — the remaining keys still work`);
  }
  // Same-length repairs are invisible to the count above, and they are the ones
  // that show up as a blank name or an unknown date in the dashboard. Say so.
  const repaired = raw.filter(row => {
    if (!row || typeof row !== "object") return false;
    const entry = row as Record<string, unknown>;
    // Must match the schema exactly: a row whose key is unusable was DROPPED, and
    // saying "the key still works" about it would be a lie.
    if (!isUsableApiKeySecret(entry.key)) return false;
    return typeof entry.id !== "string" || !entry.id
      || typeof entry.name !== "string"
      || typeof entry.createdAt !== "string";
  }).length;
  if (repaired > 0) {
    console.warn(`⚠️  config.json apiKeys: repaired metadata on ${repaired} entr${repaired === 1 ? "y" : "ies"} — the key still works, but its name or date may read as unknown`);
  }
  // A duplicate id is repaired too, and it is not visible in either count above.
  const ids = raw.filter(row => row && typeof row === "object" && isUsableApiKeySecret((row as Record<string, unknown>).key))
    .map(row => (row as Record<string, unknown>).id)
    .filter((id): id is string => typeof id === "string" && !!id);
  const duplicates = ids.length - new Set(ids).size;
  if (duplicates > 0) {
    console.warn(`⚠️  config.json apiKeys: ${duplicates} entr${duplicates === 1 ? "y" : "ies"} shared an id — reassigned so each key can be renamed and revoked on its own`);
  }
}

export const CLAUDE_SUBAGENT_EFFORTS = ["low", "medium", "high", "xhigh", "max"] as const;

export function isClaudeSubagentEffort(value: unknown): value is NonNullable<OcxClaudeCodeConfig["subagentEffort"]> {
  return typeof value === "string" && CLAUDE_SUBAGENT_EFFORTS.includes(value as typeof CLAUDE_SUBAGENT_EFFORTS[number]);
}

export function rawClaudeSubagentEffort(rawParsed: unknown): unknown {
  const raw = rawConfigRecord(rawParsed);
  const claudeCode = raw?.claudeCode;
  if (!claudeCode || typeof claudeCode !== "object" || Array.isArray(claudeCode)) return undefined;
  return (claudeCode as Record<string, unknown>).subagentEffort;
}

export function normalizePersistedClaudeCode(claudeCode: unknown): OcxConfig["claudeCode"] {
  if (!claudeCode || typeof claudeCode !== "object" || Array.isArray(claudeCode)) {
    return claudeCode as OcxConfig["claudeCode"];
  }
  const normalized = { ...claudeCode } as Record<string, unknown>;
  if (Object.hasOwn(normalized, "subagentModelForce") && !isSubagentModelEntry(normalized.subagentModelForce)) delete normalized.subagentModelForce;
  // A malformed hand edit must not arm CLI interception or discard the whole config.
  if (Object.hasOwn(normalized, "cliFirstParty") && typeof normalized.cliFirstParty !== "boolean") {
    delete normalized.cliFirstParty;
  }
  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;
  }
  const desktopProfile = normalized.desktopProfile;
  if (desktopProfile && typeof desktopProfile === "object" && !Array.isArray(desktopProfile)) {
    const profile = { ...desktopProfile } as Record<string, unknown>;
    if (typeof profile.appliedFingerprint !== "string") delete profile.appliedFingerprint;
    if (typeof profile.appliedAt !== "string") delete profile.appliedAt;
    normalized.desktopProfile = profile;
  }
  return normalized as OcxConfig["claudeCode"];
}

export 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) };
}

export function warnDegradedClaudeSubagentEffort(rawParsed: unknown): void {
  const force = rawSubagentModelForce(rawParsed);
  if (force !== undefined && !isSubagentModelEntry(force)) console.warn("⚠️ config.json claudeCode.subagentModelForce is invalid — ignoring it. Other settings were preserved.");
  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.`);
  }
}

export 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}`;
}

export function warnDegradedUpstreamHostCircuitThreshold(rawParsed: unknown): void {
  const warning = malformedUpstreamHostCircuitThresholdWarning(rawParsed);
  if (warning) console.warn(`⚠️  config.json ${warning}. Other settings were preserved.`);
}

export function malformedPlaintextV2AgentMessagesWarning(value: unknown): string | null {
  const raw = rawConfigRecord(value);
  if (!raw || raw.plaintextV2AgentMessages === undefined || typeof raw.plaintextV2AgentMessages === "boolean") return null;
  return "plaintextV2AgentMessages ignored: expected a boolean";
}

export function warnDegradedPlaintextV2AgentMessages(value: unknown): void {
  const warning = malformedPlaintextV2AgentMessagesWarning(value);
  if (warning) console.warn(`⚠️  config.json ${warning}. Other settings were preserved.`);
}

export 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`;
}

export function warnDegradedAgentTaskRecovery(rawParsed: unknown): void {
  const warning = malformedAgentTaskRecoveryWarning(rawParsed);
  if (warning) console.warn(`⚠️  config.json ${warning}. Other settings were preserved.`);
}

export function malformedRuntimeRoleWarning(rawParsed: unknown): string | null {
  const raw = rawConfigRecord(rawParsed);
  if (!raw || !Object.hasOwn(raw, "runtimeRole") || raw.runtimeRole === undefined) return null;
  if (runtimeRoleSchema.safeParse(raw.runtimeRole).success) return null;
  return 'runtimeRole ignored: expected "standalone", "hub", or "client"; falling back to "standalone"';
}

export function warnDegradedRuntimeRole(rawParsed: unknown): void {
  const warning = malformedRuntimeRoleWarning(rawParsed);
  if (warning) console.warn(`⚠️  config.json ${warning}. Other settings were preserved.`);
}

export function malformedOptionalRemoteBlockWarning(
  rawParsed: unknown,
  key: "hub" | "remoteGui",
): string | null {
  const raw = rawConfigRecord(rawParsed);
  if (!raw || !Object.hasOwn(raw, key) || raw[key] === undefined) return null;
  const schema = key === "hub" ? hubConfigSchema : remoteGuiConfigSchema;
  const result = schema.safeParse(raw[key]);
  if (result.success) return null;
  const field = result.error.issues[0]?.path.join(".");
  return `${key}${field ? `.${field}` : ""} ignored: invalid remote GUI configuration`;
}

export function malformedClientConnectionWarning(rawParsed: unknown): string | null {
  const raw = rawConfigRecord(rawParsed);
  if (!raw || !Object.hasOwn(raw, "client") || raw.client === undefined) return null;
  const result = clientConnectionSchema.safeParse(raw.client);
  if (result.success) return null;
  const field = result.error.issues[0]?.path.join(".");
  return `client${field ? `.${field}` : ""} invalid: remote client mode is disabled until config.json is repaired`;
}

export function warnDegradedOptionalRemoteBlocks(rawParsed: unknown): void {
  for (const key of ["hub", "remoteGui"] as const) {
    const warning = malformedOptionalRemoteBlockWarning(rawParsed, key);
    if (warning) console.warn(`⚠️  config.json ${warning}. Other settings were preserved.`);
  }
}

export function malformedQuotaResetNotifyWarning(rawParsed: unknown): string | null {
  const raw = rawConfigRecord(rawParsed);
  if (!raw || !Object.hasOwn(raw, "quotaResetNotify")) return null;
  const result = quotaResetNotifySchema.safeParse(raw.quotaResetNotify);
  if (result.success) return null;
  const field = result.error.issues[0]?.path.join(".");
  return `quotaResetNotify${field ? `.${field}` : ""} ignored: invalid quota-reset notification configuration`;
}

export function malformedCatalogAutoRefreshWarning(rawParsed: unknown): string | null {
  const raw = rawConfigRecord(rawParsed);
  if (!raw || !Object.hasOwn(raw, "catalogAutoRefresh")) return null;
  const result = catalogAutoRefreshSchema.safeParse(raw.catalogAutoRefresh);
  if (result.success) return null;
  const field = result.error.issues[0]?.path.join(".");
  return `catalogAutoRefresh${field ? `.${field}` : ""} ignored: invalid catalog auto-refresh configuration`;
}

/**
 * The same silent-in-the-wrong-direction failure, and the most expensive instance of it here:
 * a dropped spend section means the ceilings are not enforced, and an unenforced ceiling is
 * indistinguishable from one nothing has reached. The operator finds out from the bill.
 */
export function malformedSpendWarning(rawParsed: unknown): string | null {
  const raw = rawConfigRecord(rawParsed);
  if (!raw || !Object.hasOwn(raw, "spend")) return null;
  const result = spendSchema.safeParse(raw.spend);
  if (result.success) return null;
  const field = result.error.issues[0]?.path.join(".");
  return `spend${field ? `.${field}` : ""} ignored: invalid spend ceiling configuration, so no token ceiling is enforced`;
}

/**
 * Same silent-in-the-wrong-direction failure as the notification block: a dropped pool policy means
 * the accounts the operator meant to exclude keep taking traffic, and the only visible symptom is
 * traffic going somewhere it was supposed to stop going.
 */
export function malformedCodexPoolWarning(rawParsed: unknown): string | null {
  const raw = rawConfigRecord(rawParsed);
  if (!raw || !Object.hasOwn(raw, "codexPool")) return null;
  const result = codexPoolSchema.safeParse(raw.codexPool);
  if (result.success) return null;
  const field = result.error.issues[0]?.path.join(".");
  return `codexPool${field ? `.${field}` : ""} ignored: invalid Codex pool selection policy`;
}

export function malformedTelemetryWarning(rawParsed: unknown): string | null {
  const raw = rawConfigRecord(rawParsed);
  if (!raw || !Object.hasOwn(raw, "telemetry") || raw.telemetry === undefined) return null;
  const result = telemetryConfigSchema.safeParse(raw.telemetry);
  if (result.success) return null;
  const field = result.error.issues[0]?.path.join(".");
  return `telemetry${field ? `.${field}` : ""} ignored: invalid telemetry consent configuration`;
}

export function warnDegradedTelemetry(rawParsed: unknown): void {
  const warning = malformedTelemetryWarning(rawParsed);
  if (warning) console.warn(`⚠️  config.json ${warning}. Other settings were preserved.`);
}

/**
 * Warn once per load that the section was dropped.
 *
 * This matters more than a usual degradation notice: the failure is SILENT in the direction
 * that hurts. A dropped section means notifications are off, so the operator sees nothing —
 * which is exactly what they would see if the feature were working and no reset had happened.
 */
export function warnDegradedQuotaResetNotify(rawParsed: unknown): void {
  const warning = malformedQuotaResetNotifyWarning(rawParsed);
  if (warning) console.warn(`⚠️  config.json ${warning}. Other settings were preserved.`);
}

/**
 * Warn once per load that the section was dropped.
 *
 * Same silent-in-the-wrong-direction failure as the notification block: a dropped section
 * means the scheduler never starts, so the operator sees a stale catalog — which is exactly
 * what they would see if the feature were working and no new models had shipped.
 */
export function warnDegradedCatalogAutoRefresh(rawParsed: unknown): void {
  const warning = malformedCatalogAutoRefreshWarning(rawParsed);
  if (warning) console.warn(`⚠️  config.json ${warning}. Other settings were preserved.`);
}

/**
 * Warn once per load that the pool policy was dropped.
 *
 * `.catch(undefined)` turns a malformed policy into a SUCCESSFUL parse, so without this the proxy
 * starts, rotates onto the accounts the operator meant to exclude, and prints nothing. The visible
 * symptom would be traffic going exactly where it was told not to go.
 */
export function warnDegradedCodexPool(rawParsed: unknown): void {
  const warning = malformedCodexPoolWarning(rawParsed);
  if (warning) console.warn(`⚠️  config.json ${warning}. Other settings were preserved.`);
}

type NativeSubagentPersistedField = "injectionModel" | "injectionEffort" | "syncCodexSubagentDefaults";

export function rawConfigRecord(rawParsed: unknown): Record<string, unknown> | null {
  return rawParsed !== null && typeof rawParsed === "object" && !Array.isArray(rawParsed)
    ? rawParsed as Record<string, unknown>
    : null;
}

export function malformedNativeSubagentFields(rawParsed: unknown): NativeSubagentPersistedField[] {
  const raw = rawConfigRecord(rawParsed);
  if (!raw) return [];
  const malformed: NativeSubagentPersistedField[] = [];
  if (Object.hasOwn(raw, "injectionModel") && typeof raw.injectionModel !== "string") {
    malformed.push("injectionModel");
  }
  if (Object.hasOwn(raw, "injectionEffort") && typeof raw.injectionEffort !== "string") {
    malformed.push("injectionEffort");
  }
  if (Object.hasOwn(raw, "syncCodexSubagentDefaults") && typeof raw.syncCodexSubagentDefaults !== "boolean") {
    malformed.push("syncCodexSubagentDefaults");
  }
  return malformed;
}

export function malformedNativeSubagentFieldWarning(field: NativeSubagentPersistedField): string {
  const expected = field === "syncCodexSubagentDefaults" ? "a boolean" : "a string";
  return `${field} ignored: expected ${expected}`;
}

export const MALFORMED_CODEX_AUTH_METHOD_WARNING = 'codexAuthMethod ignored: using "auto" for Codex pool logins. Expected "auto", "device-only", or omission.';

export function malformedCodexAuthMethodWarning(rawParsed: unknown): string | null {
  if (codexAuthMethodSchema.safeParse(rawConfigRecord(rawParsed)?.codexAuthMethod).success) return null;
  return MALFORMED_CODEX_AUTH_METHOD_WARNING;
}

export 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";
}

export function warnDegradedCodexAccountPicker(rawParsed: unknown): void {
  const warning = malformedCodexAccountPickerWarning(rawParsed);
  if (warning) console.warn(`⚠️  config.json ${warning}. Other settings were preserved.`);
}

export function nativeSubagentSyncDisabledReason(config: OcxConfig, rawParsed?: unknown): string | null {
  if (config.syncCodexSubagentDefaults !== true) return null;
  const malformed = malformedNativeSubagentFields(rawParsed);
  if (malformed.includes("injectionModel")) return "injectionModel must be a string";
  if (!config.injectionModel?.trim()) return "a nonblank injectionModel is required";
  if (malformed.includes("injectionEffort")) return "injectionEffort must be a string or omitted";
  if (config.injectionEffort !== undefined && !isCodexReasoningEffort(config.injectionEffort)) {
    return "injectionEffort must be a supported Codex reasoning effort";
  }
  return null;
}

export function normalizeNativeSubagentSync(config: OcxConfig, rawParsed?: unknown): OcxConfig {
  if (!nativeSubagentSyncDisabledReason(config, rawParsed)) return config;
  const normalized = { ...config };
  delete normalized.syncCodexSubagentDefaults;
  return normalized;
}

export function warnDegradedNativeSubagentConfig(rawParsed: unknown, config: OcxConfig): void {
  for (const field of malformedNativeSubagentFields(rawParsed)) {
    console.warn(`⚠️  config.json ${malformedNativeSubagentFieldWarning(field)}. Other settings were preserved.`);
  }
  const reason = nativeSubagentSyncDisabledReason(config, rawParsed);
  if (reason) {
    console.warn(`⚠️  config.json syncCodexSubagentDefaults was disabled: ${reason}. Other settings were preserved.`);
  }
}

/**
 * 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.
 */
export 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;
    if (providerFastSwitchOff(name, provider)) 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;
}

export function inheritedFastWireConflictWarning(name: string): string {
  return `providers.${redactSecretString(name)}.fastWire=null overrides service-tier capability inherited from the matching registry entry`;
}

export function warnInheritedFastWireConflicts(configPath: string, config: OcxConfig): void {
  const names = inheritedFastWireConflictProviderNames(config);
  if (names.length === 0 || hasWarnedInheritedFastWireConflict(configPath)) return;
  markWarnedInheritedFastWireConflict(configPath);
  console.warn(
    `⚠️  config.json ${names.map(inheritedFastWireConflictWarning).join("; ")}. `
    + "The persisted providers and API keys were preserved.",
  );
}

/** Hand-edited alias mistakes disable only the bad alias; providers and routing survive. */
export function sanitizeAliasesForLoad(raw: unknown, warn: (message: string) => void = console.warn): 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 [providerName, provider] of Object.entries(providers)) {
    // #7705: a hand-edited template that would not validate loses only itself, not the config.
    if (provider.aliasTemplate !== undefined
      && (typeof provider.aliasTemplate !== "string" || aliasTemplateError(provider.aliasTemplate) !== null)) {
      warn(`Ignoring invalid alias template for provider ${providerName} in config.json`);
      delete provider.aliasTemplate;
    }
    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) 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)) {
        warn(`Ignoring invalid or colliding model alias for ${id} in config.json`);
        delete aliases[id];
      } else claimed.add(lower);
    }
  }
}

/** Hand-edited display-name mistakes disable only the bad label. */
export function sanitizeModelDisplayNamesForLoad(raw: unknown, warn: (message: string) => void = console.warn): 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;
  for (const [providerName, providerValue] of Object.entries(root.providers as Record<string, unknown>)) {
    if (!providerValue || typeof providerValue !== "object" || Array.isArray(providerValue)) continue;
    const provider = providerValue as Record<string, unknown>;
    const value = provider.modelDisplayNames;
    if (value === undefined) continue;
    const providerLabel = JSON.stringify(redactSecretString(providerName));
    if (!value || typeof value !== "object" || Array.isArray(value)
      || Object.entries(value).length > MODEL_DISCOVERY_MAX_MODELS) {
      warn(`Ignoring invalid modelDisplayNames map for provider ${providerLabel} in config.json`);
      delete provider.modelDisplayNames;
      continue;
    }
    const labels = value as Record<string, unknown>;
    for (const [modelId, rawDisplayName] of Object.entries(labels)) {
      const displayName = typeof rawDisplayName === "string" ? rawDisplayName.trim() : rawDisplayName;
      if (modelDisplayNamesConfigError({ [modelId]: displayName })) {
        const safeModelId = JSON.stringify(redactSecretString(modelId));
        warn(`Ignoring invalid modelDisplayNames entry ${safeModelId} for provider ${providerLabel} in config.json`);
        delete labels[modelId];
      } else {
        labels[modelId] = displayName;
      }
    }
    if (Object.keys(labels).length === 0) delete provider.modelDisplayNames;
  }
}

/** Refresh the user cost-overlay registry from `config` and return it unchanged. */
export function withRefreshedCostOverlays(config: OcxConfig): OcxConfig {
  refreshConfigDerivedRegistries(config);
  return config;
}