@bitkyc08/opencodex 2.52.0 → 2.53.0

package/src/codex/routing.ts

@@ -10,7 +10,7 @@ import { clearAccountNeedsReauth, isAccountNeedsReauth, markAccountNeedsReauth }
 import {
   POOL_KEY_CODEX,
   normalizeAccountPoolStickyLimit,
-  normalizeAccountPoolStrategy,
+  normalizeCodexAccountPoolStrategy,
   notePoolRotationFailure,
   notePoolRotationSuccess,
   peekRoundRobinAccount,
@@ -18,7 +18,13 @@ import {
   seedPoolRotationAccount,
   selectPriorityTier,
 } from "./pool-rotation";
-import { CODEX_EXHAUSTED_USAGE_PERCENT, CODEX_UNKNOWN_USAGE_SCORE, getAccountQuota, resetAtToMs } from "./quota";
+import {
+  CODEX_EXHAUSTED_USAGE_PERCENT,
+  CODEX_UNKNOWN_USAGE_SCORE,
+  getAccountQuota,
+  isRetiredCodexSparkModel,
+  resetAtToMs,
+} from "./quota";
 import { codexPlanKey, isThirtyDayOnlyCodexPlan } from "./plan";
 import {
   MAIN_CODEX_ACCOUNT_ID,
@@ -199,7 +205,7 @@ export type CodexCooldownSource = "retry-after" | "reset-derived" | "default";
  * Add a new explicit group here only when its independent upstream quota is
  * confirmed, so shared limits never receive cross-model bypasses.
  */
-export type CodexQuotaScope = "shared" | "spark" | "reserve";
+export type CodexQuotaScope = "shared" | "reserve";
 
 export type CodexQuotaRecoveryProbeClaim = {
   accountId: string;
@@ -218,7 +224,7 @@ export type CodexQuotaRecoveryProbeProof = {
 /**
  * Requests without a resolved native model retain the historic one-account-per-
  * thread behavior. Requests with a known quota scope get an independent
- * affinity so a Spark failover cannot displace the same thread's Terra/Luna
+ * affinity so a Reserve failover cannot displace the same thread's Terra/Luna
  * account (and vice versa).
  */
 type BaseThreadAffinityScope = CodexQuotaScope | "legacy";
@@ -233,7 +239,6 @@ function isModelDetourAffinityScope(scope: ThreadAffinityScope): scope is ModelD
 }
 
 const NATIVE_MODEL_QUOTA_SCOPES: Readonly<Record<string, CodexQuotaScope>> = {
-  "gpt-5.3-codex-spark": "spark",
   [NATIVE_RESERVE_MODEL]: "reserve",
 };
 
@@ -688,7 +693,7 @@ export function claimDueCodexQuotaRecoveryProbes(
       { scope: undefined, health: upstreamHealth.get(account.id) },
       ...[...(quotaScopedHealth.get(account.id) ?? [])].map(([scope, health]) => ({ scope, health })),
     ].filter((entry): entry is { scope?: CodexQuotaScope; health: CodexUpstreamHealth } =>
-      // Generic WHAM evidence can recover only ordinary quota, never Spark or Reserve.
+      // Generic WHAM evidence can recover only ordinary quota, never Reserve.
       // Do not spend this account's one claim per pass on an independent scope and
       // delay the shared scope that the response can actually recover.
       (entry.scope === undefined || entry.scope === "shared")
@@ -1169,7 +1174,7 @@ function excludedCodexPoolPlanKeys(config: OcxConfig): ReadonlySet<string> | und
  * selection-only drain so routing never reads the fenced native credential for it, so a rule that
  * covered main would disagree with itself between drain and ordinary routing.
  */
-function isCodexAccountPlanExcluded(
+export function isCodexAccountPlanExcluded(
   config: OcxConfig,
   accountId: string,
   precomputed?: ReadonlySet<string>,
@@ -1474,6 +1479,12 @@ function listEligibleCodexAccountIds(
   return getEligiblePoolAccounts(config, undefined, now, quotaScope, selectionOptions);
 }
 
+/** Shared reset timestamps are not evidence for independent model-quota groups. */
+function accountPoolStrategyForScope(config: OcxConfig, quotaScope?: CodexQuotaScope) {
+  const strategy = normalizeCodexAccountPoolStrategy(config.accountPoolStrategy);
+  return strategy === "reset-first" && isIndependentCodexQuotaScope(quotaScope) ? "quota" : strategy;
+}
+
 function stickyLimitForConfig(config: OcxConfig): number {
   return normalizeAccountPoolStickyLimit(config.accountPoolStickyLimit);
 }
@@ -1505,6 +1516,32 @@ function hasCodexQuotaHeadroom(
   return usage < threshold;
 }
 
+/** Earliest future shared short/weekly reset; missing evidence and ties use usage order. */
+function pickResetFirstCodexAccount(
+  config: OcxConfig,
+  ids: readonly string[],
+  now: number,
+  selectionOptions?: CodexAccountUsabilityOptions,
+): string | null {
+  const available = ids.filter(id => hasCodexQuotaHeadroom(config, id, selectionOptions, now));
+  if (available.length === 0) return pickLowestUsageAmong(config, ids, selectionOptions, now);
+  let earliest = Number.POSITIVE_INFINITY;
+  let candidates: string[] = [];
+  for (const id of available) {
+    const quota = getAccountQuota(id);
+    const resets = [quota?.shortResetAt, quota?.weeklyResetAt]
+      .filter((reset): reset is number => typeof reset === "number" && Number.isFinite(reset))
+      .map(resetAtToMs)
+      .filter(reset => reset > now);
+    const next = Math.min(...resets);
+    if (next < earliest) {
+      earliest = next;
+      candidates = [id];
+    } else if (next === earliest) candidates.push(id);
+  }
+  return pickLowestUsageAmong(config, candidates, selectionOptions, now);
+}
+
 /**
  * Fill-first: keep selectable active under threshold; otherwise advance to the next
  * eligible id in stable sorted order after the current active (wrapping).
@@ -1595,7 +1632,7 @@ function pickUnboundStrategyAccount(
   commitSharedActive = commit,
   commitAffinity = commit,
 ): string | null {
-  const strategy = normalizeAccountPoolStrategy(config.accountPoolStrategy);
+  const strategy = accountPoolStrategyForScope(config, quotaScope);
   if (strategy === "quota") return null;
   const poolKey = codexPoolKeyForScope(quotaScope);
 
@@ -1619,8 +1656,10 @@ function pickUnboundStrategyAccount(
     return picked;
   }
 
-  if (strategy === "fill-first") {
-    picked = pickFillFirstCodexAccount(config, now, quotaScope, selectionOptions);
+  if (strategy === "fill-first" || strategy === "reset-first") {
+    picked = strategy === "reset-first"
+      ? pickResetFirstCodexAccount(config, listEligibleCodexAccountIds(config, now, quotaScope, selectionOptions), now, selectionOptions)
+      : pickFillFirstCodexAccount(config, now, quotaScope, selectionOptions);
     if (!picked) return null;
     if (commitSharedActive) {
       if (!isIndependentCodexQuotaScope(quotaScope)
@@ -1753,7 +1792,7 @@ export function pickAlternateCodexAccount(
   quotaScope?: CodexQuotaScope,
   selectionOptions?: CodexAccountUsabilityOptions,
 ): string | null {
-  const strategy = normalizeAccountPoolStrategy(config.accountPoolStrategy);
+  const strategy = accountPoolStrategyForScope(config, quotaScope);
   // The exclusion is passed into eligibility rather than post-filtered off its
   // result: when the excluded account is the only healthy member of the top
   // tier, the tier walk must be free to descend instead of selecting that tier
@@ -1766,6 +1805,9 @@ export function pickAlternateCodexAccount(
     const eligible = getEligiblePoolAccounts(config, excludeId, now, quotaScope, selectionOptions);
     return pickNextFillFirstCodexAccount(config, excludeId, eligible, now, selectionOptions);
   }
+  if (strategy === "reset-first") {
+    return pickResetFirstCodexAccount(config, getEligiblePoolAccounts(config, excludeId, now, quotaScope, selectionOptions), now, selectionOptions);
+  }
   return pickLowestUsageCodexAccount(config, excludeId, now, quotaScope, selectionOptions);
 }
 
@@ -1862,7 +1904,7 @@ function setActiveCodexAccount(config: OcxConfig, accountId: string): void {
 
 /** Quota strategy persists; RR/fill-first keep a process-local cursor only. */
 function promoteActiveCodexAccount(config: OcxConfig, accountId: string): void {
-  if (normalizeAccountPoolStrategy(config.accountPoolStrategy) === "quota") {
+  if (normalizeCodexAccountPoolStrategy(config.accountPoolStrategy) === "quota") {
     setActiveCodexAccount(config, accountId);
     return;
   }
@@ -2147,9 +2189,12 @@ function previewReusableAffinityAccount(
   ) {
     return null;
   }
+  if (accountPoolStrategyForScope(config, quotaScope) === "reset-first") {
+    return resetFirstAffinityReplacement(entry, config, now, quotaScope, selectionOptions) ?? entry.accountId;
+  }
   // Quota strategy only: non-quota strategies keep affinity for ongoing threads
   // (new-session-only rotation — docs / affinity policy A).
-  if (normalizeAccountPoolStrategy(config.accountPoolStrategy) === "quota") {
+  if (accountPoolStrategyForScope(config, quotaScope) === "quota") {
     const threshold = config.autoSwitchThreshold ?? 80;
     if (threshold > 0) {
       const usage = computeCodexUsageScore(
@@ -2202,6 +2247,23 @@ function mayRebindAffinityForQuota(
     || (!isUnknownUsage(usage) && usage >= 100);
 }
 
+/** Reset ordering may move a binding only under the existing cache-affinity release policy. */
+function resetFirstAffinityReplacement(
+  entry: ThreadAffinityEntry,
+  config: OcxConfig,
+  now: number,
+  quotaScope?: CodexQuotaScope,
+  selectionOptions?: CodexAccountUsabilityOptions,
+): string | null {
+  const threshold = config.autoSwitchThreshold ?? 80;
+  if (threshold <= 0) return null;
+  const usage = computeCodexUsageScore(getAccountQuota(entry.accountId), getPoolAccountPlanForSelection(config, entry.accountId, selectionOptions), now);
+  if (!mayRebindAffinityForQuota(config, entry.accountId, usage, threshold, selectionOptions)) return null;
+  const candidates = getEligiblePoolAccounts(config, entry.accountId, now, quotaScope, selectionOptions, true)
+    .filter(id => hasCodexQuotaHeadroom(config, id, selectionOptions, now));
+  return pickResetFirstCodexAccount(config, candidates, now, selectionOptions);
+}
+
 /**
  * Re-evaluate an affined account under the quota strategy. Returns a strictly
  * cooler replacement, or null when the current binding should remain.
@@ -2213,7 +2275,13 @@ function reevaluateAffinityQuota(
   quotaScope?: CodexQuotaScope,
   selectionOptions?: CodexAccountUsabilityOptions,
 ): string | null {
-  if (normalizeAccountPoolStrategy(config.accountPoolStrategy) !== "quota") return null;
+  const strategy = accountPoolStrategyForScope(config, quotaScope);
+  if (strategy === "reset-first") {
+    const replacement = resetFirstAffinityReplacement(entry, config, now, quotaScope, selectionOptions);
+    if (replacement || now - entry.lastReevalAt >= CODEX_THREAD_AFFINITY_REEVAL_INTERVAL_MS) entry.lastReevalAt = now;
+    return replacement;
+  }
+  if (strategy !== "quota") return null;
   const threshold = config.autoSwitchThreshold ?? 80;
   const usage = threshold > 0
     ? computeCodexUsageScore(
@@ -2306,6 +2374,7 @@ export function previewCodexAccountForRequest(
     else if (
       hasConfiguredPoolAccount(config, active, selectionOptions)
       && !isCodexAccountPaused(config, active)
+      && !isCodexAccountPlanExcluded(config, active)
     ) return active;
     else return null;
   }
@@ -2440,7 +2509,7 @@ export function resolveCodexAccountForThreadDetailed(
       const cooler = reevaluateAffinityQuota(entry, config, now, quotaScope, selectionOptions);
       if (cooler) {
         if (!isIndependentCodexQuotaScope(quotaScope)) {
-          setActiveCodexAccount(config, cooler);
+          promoteActiveCodexAccount(config, cooler);
         }
         bindThreadAffinity(threadId, cooler, now, quotaScope); // rebinds + resets clocks
         return { status: "selected", accountId: cooler };
@@ -2548,6 +2617,7 @@ export function resolveCodexAccountForThreadDetailed(
     } else if (
       hasConfiguredPoolAccount(config, active, selectionOptions)
       && !isCodexAccountPaused(config, active)
+      && !isCodexAccountPlanExcluded(config, active)
     ) {
       return { status: "selected", accountId: active };
     } else {
@@ -2628,6 +2698,9 @@ export function recordCodexUpstreamOutcome(
   if (writerGeneration < lastReconciledGeneration && !liveHealthAccountIds.has(accountId)) return;
   const now = meta.now ?? Date.now();
   const outcomeClass = classifyCodexUpstreamOutcome(outcome, meta.denial);
+  // Reject retired quota evidence before stale-credential cleanup or any shared mutation.
+  if (outcomeClass === "quota" && isRetiredCodexSparkModel(meta.modelId)
+      && computeQuotaCooldown(meta).source === "reset-derived") return;
   const quotaScope = codexQuotaScopeForModel(meta.modelId);
   /*
    * Spend a stale credential failure BEFORE any branch reads health (#2892 gap 4 review).
@@ -2799,7 +2872,7 @@ export function recordCodexUpstreamOutcome(
     const { until, source } = computeQuotaCooldown(meta);
     // A reset timestamp is an advisory quota-window announcement. When the
     // selected native model belongs to a confirmed independent group, preserve
-    // it there so a different group (Spark versus the shared native quota) can
+    // it there so a different group (Reserve versus the shared native quota) can
     // still reach upstream. Explicit Retry-After/default 429s remain account-wide.
     if (source === "reset-derived" && quotaScope) {
       const prior = scopedHealthFor(accountId, quotaScope);
@@ -2824,7 +2897,7 @@ export function recordCodexUpstreamOutcome(
       });
       // The shared native scope is the existing account-wide native behavior:
       // threads must leave it and new requests should prefer an eligible account.
-      // Spark remains isolated so a same-account Terra/Luna combo fallback can run.
+      // Reserve remains isolated so a same-account Terra/Luna combo fallback can run.
       if (quotaScope === "shared" && !meta.fixedAccount) {
         clearThreadAccountMapForAccount(accountId);
         notePoolRotationFailure(POOL_KEY_CODEX, accountId);

package/src/codex/sync.ts

@@ -19,7 +19,7 @@ export interface CodexSyncResult {
   /**
    * `skipped` is policy truth, never evidence that Codex was written.
    * `catalog-only` means an explicit sync refreshed the catalog/cache while
-   * Codex injection stayed OFF; config and history were not touched.
+   * config/history injection was skipped (OFF, externally owned, or protected history).
    */
   status: "applied" | "skipped" | "catalog-only" | "refused";
   ok: boolean;
@@ -32,6 +32,12 @@ export interface CodexSyncResult {
   catalogExists: boolean;
   catalogWritten: boolean;
   cacheSynced: boolean;
+  /**
+   * Whether the catalog owner committed a validated catalog or refused the
+   * refresh. Only a `catalog-only` result carries it; `ok` already answers the
+   * question for callers that do not care which half refused.
+   */
+  refreshOutcome?: "committed" | "refused";
   message: string;
   warning?: string;
   comboOmissions?: ComboCatalogOmission[];
@@ -45,8 +51,8 @@ export interface CodexSyncOptions {
    * Explicit `ocx sync` is also the refresh path for side profiles that consume
    * the OpenCodex catalog without injection. When set, the sync still refreshes
    * the catalog and models cache even if the Codex integration toggle is OFF or
-   * an external `model_provider` owns config.toml. Config/history injection is
-   * skipped in those cases, so the behavior is harmless to a native home.
+   * an external `model_provider` owns config.toml, or paginated history refuses
+   * injection. Config/history injection is skipped in those cases.
    */
   catalogEvenWhenNotInjected?: boolean;
 }
@@ -203,6 +209,25 @@ export async function syncModelsToCodex(
   // working catalog/cache into the partial result of an otherwise unnecessary refresh.
   const preflight = await deps.injectCodexConfig(p, config, { validateOnly: true });
   if (!preflight.success) {
+    // Explicit model refresh does not require legacy history relabeling. Keep the
+    // injector's refusal intact and publish only through the existing catalog owner.
+    // Unattended sync and other config/integrity refusals retain their hard failure.
+    if (catalogEvenWhenNotInjected
+      && preflight.historyPreflightFailureReason === "history_paginated_requires_native_writer") {
+      applyProxyEnv(config);
+      const refreshed = await refreshCatalogForSync(config, deps, undefined, log);
+      const ok = refreshed.refreshOutcome === "committed" && refreshed.catalogExists;
+      const message = ok
+        ? "Model catalog synchronized; Codex config and conversation history left unchanged because paginated history requires its native writer."
+        : "Model catalog refresh did not complete; Codex config and conversation history were left unchanged.";
+      reportCodexHomeTarget(log, deps.collectCodexHomeDiagnostic ?? collectOrcaCodexHomeDiagnostic);
+      return {
+        ...refreshed,
+        status: "catalog-only",
+        ok,
+        message,
+      };
+    }
     log?.error(preflight.message);
     reportCodexHomeTarget(log, deps.collectCodexHomeDiagnostic ?? collectOrcaCodexHomeDiagnostic);
     return {
@@ -308,6 +333,7 @@ async function refreshCatalogForSync(
   catalogWritten: boolean;
   cacheSynced: boolean;
   comboOmissions: ComboCatalogOmission[];
+  refreshOutcome?: "committed" | "refused";
   warning?: string;
 }> {
   let added = 0;
@@ -316,9 +342,11 @@ async function refreshCatalogForSync(
   let catalogWritten = false;
   let cacheSynced = false;
   let warning: string | undefined;
+  let refreshOutcome: "committed" | "refused" | undefined;
   let comboOmissions: ComboCatalogOmission[] = [];
   try {
     const cat = await deps.refreshCodexModelCatalog(config, undefined, catalogOptions);
+    refreshOutcome = cat.refreshOutcome;
     added = cat.added;
     catalogExists = cat.catalogExists;
     catalogWritten = cat.catalogWritten;
@@ -340,5 +368,6 @@ async function refreshCatalogForSync(
     warning = `catalog sync skipped: ${e instanceof Error ? e.message : String(e)}`;
     log?.error(warning);
   }
-  return { added, catalogPath, catalogExists, catalogWritten, cacheSynced, comboOmissions, ...(warning ? { warning } : {}) };
+  return { added, catalogPath, catalogExists, catalogWritten, cacheSynced, comboOmissions,
+    ...(refreshOutcome ? { refreshOutcome } : {}), ...(warning ? { warning } : {}) };
 }

package/src/combos/request.ts

@@ -1,4 +1,4 @@
-import type { OcxComboDefaultEffort, OcxComboTarget, OcxConfig } from "../types";
+import type { OcxComboDefaultEffort, OcxComboReasoningEffortMode, OcxComboTarget, OcxConfig } from "../types";
 import { resolveEffortAtOrBelow } from "../reasoning-effort";
 import { resolveComboId } from "./types";
 
@@ -59,9 +59,14 @@ export function concreteComboRequestBody(
   target: Pick<OcxComboTarget, "provider" | "model">,
   defaultEffort: OcxComboDefaultEffort | null,
   targetReasoningEfforts: readonly string[] | undefined,
+  reasoningEffortMode: OcxComboReasoningEffortMode = "strict",
 ): Record<string, unknown> {
   const clone = structuredClone(body) as Record<string, unknown>;
   clone.model = `${target.provider}/${target.model}`;
+  if (targetReasoningEfforts?.length === 0
+    || (reasoningEffortMode === "adaptive" && targetReasoningEfforts === undefined)) {
+    stripUnsupportedReasoningControls(clone);
+  }
   if (!defaultEffort) return clone;
   const reasoning = clone.reasoning;
   const needsDefault = reasoning === undefined || (
@@ -104,3 +109,16 @@ export function concreteComboRequestBody(
   }
   return clone;
 }
+
+function stripUnsupportedReasoningControls(body: Record<string, unknown>): void {
+  const reasoning = body.reasoning;
+  if (reasoning && typeof reasoning === "object" && !Array.isArray(reasoning)) {
+    const next = { ...(reasoning as Record<string, unknown>) };
+    delete next.effort;
+    if (Object.keys(next).length > 0) body.reasoning = next;
+    else delete body.reasoning;
+  }
+  delete body.reasoning_effort;
+  delete body.thinking_budget;
+  delete body.thinking;
+}

package/src/config/multi-agent-surface.ts

@@ -0,0 +1,61 @@
+import type { MultiAgentMode } from "../codex/catalog/parsing";
+import type { OcxConfig } from "../types";
+
+/**
+ * Bump to raise the sub-agent surface advisory again for installs that already answered
+ * the previous one. A version rather than a boolean, so that the day the upstream
+ * encrypted-task limitation is fixed, the notice saying so reaches the same operators
+ * without a second config key.
+ */
+export const MULTI_AGENT_SURFACE_ADVISORY_VERSION = 1;
+
+/** The published explanation both advisory surfaces link to. */
+export const SUBAGENT_SURFACE_GUIDE_URL = "https://opencodex.me/guides/subagent-v1-default/";
+
+/**
+ * The surface an operator effectively runs. An absent key still means base: the key is
+ * deleted when base is selected, so its absence cannot be read as "never configured".
+ * What changed in this release is the written default, not this resolution.
+ */
+export function resolveMultiAgentMode(config: Pick<OcxConfig, "multiAgentMode">): MultiAgentMode {
+  return config.multiAgentMode === "v1" || config.multiAgentMode === "v2" ? config.multiAgentMode : "default";
+}
+
+type AdvisoryConfig = Pick<OcxConfig, "multiAgentMode" | "multiAgentSurfaceAdvisoryVersion">;
+
+/**
+ * True when this install should be told once that v1 is now the default surface.
+ *
+ * A v1 install is silent because it has nothing to decide. A fresh install is silent
+ * because `getDefaultConfig()` writes the current version alongside the v1 default. What
+ * is left is the case this exists for: an install that predates the change and is running
+ * base or v2, where a ChatGPT-native parent cannot hand a task to a routed child.
+ */
+export function multiAgentSurfaceAdvisoryRequired(config: AdvisoryConfig): boolean {
+  if (resolveMultiAgentMode(config) === "v1") return false;
+  return (config.multiAgentSurfaceAdvisoryVersion ?? 0) < MULTI_AGENT_SURFACE_ADVISORY_VERSION;
+}
+
+export type MultiAgentSurfaceAdvisory = {
+  /** Whether the dashboard should raise the notice. */
+  required: boolean;
+  /** The surface stored today. */
+  mode: MultiAgentMode;
+  /** What the notice recommends. */
+  recommended: "v1";
+  /** The advisory revision a client acknowledges. */
+  version: number;
+  /** Where the notice sends a reader for the explanation. */
+  docsUrl: string;
+};
+
+/** Response-only projection; none of this is a writable config field. */
+export function multiAgentSurfaceAdvisory(config: AdvisoryConfig): MultiAgentSurfaceAdvisory {
+  return {
+    required: multiAgentSurfaceAdvisoryRequired(config),
+    mode: resolveMultiAgentMode(config),
+    recommended: "v1",
+    version: MULTI_AGENT_SURFACE_ADVISORY_VERSION,
+    docsUrl: SUBAGENT_SURFACE_GUIDE_URL,
+  };
+}

package/src/config/provider-validation.ts

@@ -5,12 +5,14 @@ import {
   MODEL_DISCOVERY_MAX_MODELS,
 } from "../providers/model-discovery-limits";
 import { isDeclaredReasoningEffort, modelRecordValue } from "../reasoning-effort";
+import { encodeRoutedModelId } from "../providers/slug-codec";
 import {
   isWirePinnedModel,
   MODEL_ADAPTER_OVERRIDE_ALLOWED,
   REASONING_SUMMARY_DELIVERY_VALUES,
   UPSTREAM_HTTP_VERSION_VALUES,
   type OcxProviderConfig,
+  type ModelCapabilities,
 } from "../types";
 
 const HEADER_NAME_PATTERN = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/;
@@ -233,6 +235,85 @@ export function modelDisplayNamesConfigError(
   return null;
 }
 
+/** Characters that make a Codex catalog selector ambiguous or unrepresentable. */
+export const AUTO_REVIEW_MODEL_CONTROL_CHARS = /[\u0000-\u001f\u007f-\u009f\u2028\u2029\s]/;
+
+/** Validate one auto-review target (provider-wide value or map value). */
+export function autoReviewModelTargetConfigError(
+  value: unknown,
+  field = "autoReviewModel",
+  allowClear = false,
+): string | null {
+  if (value === undefined || (allowClear && (value === null || value === ""))) return null;
+  if (typeof value !== "string") return `${field} must be a string`;
+  const trimmed = value.trim();
+  if (!trimmed) return `${field} must be nonblank`;
+  if (trimmed.length > 1024 || AUTO_REVIEW_MODEL_CONTROL_CHARS.test(trimmed)) {
+    return `${field} must be a catalog selector without whitespace or control characters`;
+  }
+  return null;
+}
+
+/** True when the value is a valid Codex catalog auto-review selector. */
+export function isValidAutoReviewModel(value: unknown): value is string {
+  return typeof value === "string" && autoReviewModelTargetConfigError(value) === null;
+}
+
+/** Canonical model key used for map matching, duplicate detection, and route tombstones. */
+export function canonicalAutoReviewModelKey(modelId: string): string {
+  return encodeRoutedModelId(modelId.trim());
+}
+
+/** Validate a per-model auto-review override map. */
+export function autoReviewModelOverridesConfigError(
+  value: unknown,
+  field = "autoReviewModelOverrides",
+  allowTombstones = false,
+): string | null {
+  if (value === undefined) return null;
+  if (value === null && allowTombstones) return null;
+  if (!value || typeof value !== "object" || Array.isArray(value)) return `${field} must be a plain object`;
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) {
+    return `${field} must be a plain object with own properties`;
+  }
+  const entries = Object.entries(value);
+  if (entries.length > MODEL_DISCOVERY_MAX_MODELS) {
+    return `${field} must contain at most ${MODEL_DISCOVERY_MAX_MODELS} entries`;
+  }
+  const canonicalKeys = new Set<string>();
+  for (const [modelId, target] of entries) {
+    if (!isValidModelDiscoveryModelId(modelId) || ["__proto__", "prototype", "constructor"].includes(modelId)) {
+      return `${field} keys must be valid non-reserved model ids`;
+    }
+    const safeModelId = JSON.stringify(redactSecretString(modelId));
+    const canonicalKey = canonicalAutoReviewModelKey(modelId);
+    if (canonicalKeys.has(canonicalKey)) {
+      return `${field} keys must be unique after trimming and slash normalization`;
+    }
+    canonicalKeys.add(canonicalKey);
+    if (allowTombstones && (target === null || target === "")) continue;
+    const targetError = autoReviewModelTargetConfigError(target, `${field}.${safeModelId}`);
+    if (targetError) return targetError;
+  }
+  return null;
+}
+
+/** Normalize a persisted auto-review override map (trim, drop blanks, keep insertion order). */
+export function normalizeAutoReviewModelOverrides(value: unknown): Record<string, string> | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const out = Object.create(null) as Record<string, string>;
+  for (const [modelId, target] of Object.entries(value)) {
+    const key = modelId.trim();
+    if (!key) continue;
+    if (target === null || typeof target !== "string") continue;
+    const trimmed = target.trim();
+    if (!trimmed) continue;
+    out[key] = trimmed;
+  }
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
 /** Validate the management DTO boundary for the opt-in empty-tool-output annotation. */
 export function providerEmptyToolOutputConfigError(name: string, provider: unknown): string | null {
   const raw = provider as Record<string, unknown> | null | undefined;
@@ -295,3 +376,98 @@ export function modelAdapterRecordConfigError(
   }
   return null;
 }
+
+
+function capabilityRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    && [Object.prototype, null].includes(Object.getPrototypeOf(value));
+}
+
+/** Strict writes; only PATCH may carry deletion tombstones. Model IDs are exact. */
+export function modelCapabilitiesConfigError(value: unknown, allowTombstones = false): string | null {
+  if (value === undefined || (allowTombstones && value === null)) return null;
+  if (!capabilityRecord(value)) return "modelCapabilities must be a plain object";
+  if (Object.keys(value).length > MODEL_DISCOVERY_MAX_MODELS) return "modelCapabilities has too many models";
+  for (const [id, row] of Object.entries(value)) {
+    if (!isValidModelDiscoveryModelId(id) || ["__proto__", "prototype", "constructor"].includes(id)) {
+      return "modelCapabilities keys must be exact non-reserved model ids without surrounding whitespace";
+    }
+    if (allowTombstones && row === null) continue;
+    if (!capabilityRecord(row)) return "modelCapabilities rows must be plain objects";
+    for (const [axis, declaration] of Object.entries(row)) {
+      if (!["inputModalities", "contextTier", "video"].includes(axis)) return "modelCapabilities contains an unknown axis";
+      if (allowTombstones && declaration === null) continue;
+      if (axis === "inputModalities") {
+        if (!Array.isArray(declaration) || declaration.length === 0
+          || declaration.some(item => typeof item !== "string" || !["text", "image", "audio", "video"].includes(item))) {
+          return "modelCapabilities inputModalities must be a nonempty array of text, image, audio or video";
+        }
+      } else if (axis === "contextTier") {
+        if (declaration !== "default" && declaration !== "long_context") return "modelCapabilities contextTier must be default or long_context";
+      } else {
+        if (!capabilityRecord(declaration) || Object.keys(declaration).some(key => key !== "processing")) {
+          return "modelCapabilities video must be a plain object containing only processing";
+        }
+        if (Object.hasOwn(declaration, "processing") && declaration.processing !== "static" && declaration.processing !== "agentic"
+          && !(allowTombstones && declaration.processing === null)) return "modelCapabilities video processing must be static or agentic";
+      }
+    }
+  }
+  return null;
+}
+
+/** Merge a validated patch without sharing nested objects with the live provider. */
+export function mergeModelCapabilities(
+  current: Record<string, ModelCapabilities> | undefined,
+  patch: unknown,
+): Record<string, ModelCapabilities> | undefined {
+  if (patch === null) return undefined;
+  const next = Object.fromEntries(Object.entries(current ?? {}).map(([id, row]) => [id, structuredClone(row)]));
+  if (patch !== undefined) for (const [id, raw] of Object.entries(patch as Record<string, Record<string, unknown> | null>)) {
+    if (raw === null) { delete next[id]; continue; }
+    const row: ModelCapabilities = Object.hasOwn(next, id) ? next[id]! : {};
+    for (const [axis, value] of Object.entries(raw)) {
+      if (axis === "inputModalities") {
+        if (value === null) delete row.inputModalities;
+        else row.inputModalities = [...(value as NonNullable<ModelCapabilities["inputModalities"]>)];
+      } else if (axis === "contextTier") {
+        if (value === null) delete row.contextTier;
+        else row.contextTier = value as ModelCapabilities["contextTier"];
+      } else if (axis === "video") {
+        if (value === null) delete row.video;
+        else {
+          const video = { ...(row.video ?? {}) };
+          const change = value as { processing?: "static" | "agentic" | null };
+          if (Object.hasOwn(change, "processing")) {
+            if (change.processing === null) delete video.processing;
+            else video.processing = change.processing;
+          }
+          if (Object.keys(video).length) row.video = video;
+          else delete row.video;
+        }
+      }
+    }
+    if (Object.keys(row).length) next[id] = row;
+    else delete next[id];
+  }
+  return Object.keys(next).length ? next : undefined;
+}
+
+/** Load-only repair preserves independent valid axes; malformed explicit modalities restrict to text. */
+export function sanitizeModelCapabilitiesForLoad(value: unknown): Record<string, ModelCapabilities> | undefined {
+  if (!capabilityRecord(value)) return undefined;
+  const rows: Record<string, ModelCapabilities> = Object.create(null);
+  for (const [id, raw] of Object.entries(value).slice(0, MODEL_DISCOVERY_MAX_MODELS)) {
+    if (!capabilityRecord(raw) || !isValidModelDiscoveryModelId(id) || ["__proto__", "prototype", "constructor"].includes(id)) continue;
+    const row: Record<string, unknown> = {};
+    for (const axis of ["inputModalities", "contextTier", "video"] as const) {
+      if (!Object.hasOwn(raw, axis)) continue;
+      const declaration = raw[axis];
+      if (modelCapabilitiesConfigError({ [id]: { [axis]: declaration } }) === null) row[axis] = declaration;
+      else if (axis === "inputModalities") row.inputModalities = ["text"];
+    }
+    const normalized = mergeModelCapabilities(undefined, { [id]: row });
+    if (normalized?.[id]) rows[id] = normalized[id];
+  }
+  return Object.keys(rows).length ? rows : undefined;
+}