@bitkyc08/opencodex 2.68.0 → 2.69.0-preview.20260928

package/src/codex/project-config-warnings.ts

@@ -5,13 +5,13 @@ import {
   fstatSync,
   lstatSync,
   openSync,
-  readFileSync,
   readSync,
   realpathSync,
 } from "node:fs";
 import path, { dirname, join, resolve } from "node:path";
 import { expandUserPath } from "../config";
 import { defaultCodexHome } from "./home";
+import { readBoundedCodexConfig } from "./inject/bounded-config-reader";
 import { readRootTomlString } from "./paths";
 import { truncateRetainedUtf8 } from "../lib/admission";
 
@@ -53,7 +53,8 @@ function resolveCodexConfigPath(): string {
   return join(home, "config.toml");
 }
 
-export type ProjectCodexConfigIssueCode = "model_providers_table" | "profile_selector" | "model_provider_root";
+export type ProjectCodexConfigIssueCode = "model_providers_table" | "profile_selector" | "model_provider_root"
+  | "global_config_unreadable";
 
 export interface ProjectCodexConfigWarning {
   path: string;
@@ -265,17 +266,18 @@ export function resolveEffectiveProjectModelProvider(content: string): Effective
 /** True when global Codex config routes through the opencodex proxy. */
 export function isGlobalOpencodexRoutingActive(
   codexConfigPath: string = resolveCodexConfigPath(),
-  content?: string,
+  content?: string | null,
 ): boolean {
   let text = content;
   if (text === undefined) {
-    if (!existsSync(codexConfigPath)) return false;
     try {
-      text = readFileSync(codexConfigPath, "utf-8");
+      text = readBoundedCodexConfig(codexConfigPath) ?? undefined;
     } catch {
       return false;
     }
+    if (text === undefined) return false;
   }
+  if (text === null) return false;
   if (hasInjectedOpenaiBaseUrl(text)) return true;
   if (readRootTomlString(text, "model_provider") === "opencodex") return true;
   return false;
@@ -379,6 +381,8 @@ export function discoverProjectCodexConfigPaths(options: {
   cwd?: string;
   codexConfigPath?: string;
   maxWalkParents?: number;
+  /** Explicit null keeps an absent/unreadable observation; undefined permits a fresh read. */
+  globalContent?: string | null;
 } = {}): string[] {
   const found = new Set<string>();
   const codexConfigPath = options.codexConfigPath ?? resolveCodexConfigPath();
@@ -416,15 +420,16 @@ export function discoverProjectCodexConfigPaths(options: {
     cwd = parent;
   }
 
-  if (existsSync(codexConfigPath)) {
-    try {
-      const global = readFileSync(codexConfigPath, "utf-8");
+  try {
+    const global = options.globalContent === undefined
+      ? readBoundedCodexConfig(codexConfigPath) : options.globalContent;
+    if (global !== null) {
       for (const projectPath of parseTrustedProjectPathsFromCodexConfig(global)) {
         addIfExists(projectPath);
       }
-    } catch {
-      /* ignore unreadable global config */
     }
+  } catch {
+    /* ignore unreadable global config */
   }
 
   return [...found];
@@ -437,10 +442,32 @@ export function collectProjectCodexConfigWarnings(options: {
 } = {}): ProjectCodexConfigWarning[] {
   const codexConfigPath = options.codexConfigPath ?? resolveCodexConfigPath();
   const requireRouting = options.requireOpencodexRouting ?? true;
-  if (requireRouting && !isGlobalOpencodexRoutingActive(codexConfigPath)) return [];
+
+  // The routing question has three answers: active, inactive, and unreadable. An oversized
+  // or swapped-underneath global config must not silently collapse to "inactive" — that
+  // would erase both project-bypass coverage and trusted-path discovery without a trace.
+  let globalContent: string | null = null;
+  let globalUnreadable = false;
+  try {
+    globalContent = readBoundedCodexConfig(codexConfigPath);
+  } catch {
+    globalUnreadable = true;
+  }
+  if (requireRouting && !globalUnreadable
+    && !isGlobalOpencodexRoutingActive(codexConfigPath, globalContent)) {
+    return [];
+  }
 
   const warnings: ProjectCodexConfigWarning[] = [];
-  for (const path of discoverProjectCodexConfigPaths({ cwd: options.cwd, codexConfigPath })) {
+  if (globalUnreadable) {
+    warnings.push({
+      path: codexConfigPath,
+      code: "global_config_unreadable",
+      detail: "unreadable",
+      message: "The global Codex config could not be read within the 1 MiB bound — whether it routes through OpenCodex, and which projects it declares trusted, is undetermined.",
+    });
+  }
+  for (const path of discoverProjectCodexConfigPaths({ cwd: options.cwd, codexConfigPath, globalContent })) {
     const content = readBoundedProjectConfig(path);
     if (content !== null) warnings.push(...analyzeProjectCodexConfig(content, path));
   }
@@ -480,6 +507,8 @@ export function summarizeProjectCodexIssue(warning: ProjectCodexConfigWarning):
       return warning.profileName ? `profile="${warning.profileName}"` : `model_provider="${warning.detail}"`;
     case "model_provider_root":
       return `model_provider="${warning.detail}"`;
+    case "global_config_unreadable":
+      return "config.toml unreadable or oversized";
   }
 }
 
@@ -501,6 +530,8 @@ export interface ProjectCodexConfigWarningGroup {
   path: string;
   issues: string[];
   bypass: string;
+  /** True when the group is the global-config-unreadable caveat, not a project bypass. */
+  globalUnreadable?: boolean;
 }
 
 export function groupProjectCodexConfigWarningsByPath(
@@ -512,22 +543,34 @@ export function groupProjectCodexConfigWarningsByPath(
     list.push(warning);
     grouped.set(warning.path, list);
   }
-  return [...grouped.entries()].map(([path, pathWarnings]) => ({
-    path,
-    issues: pathWarnings.map(summarizeProjectCodexIssue),
-    bypass: explainProjectConfigBypass(pathWarnings),
-  }));
+  return [...grouped.entries()].map(([path, pathWarnings]) => {
+    const globalUnreadable = pathWarnings.every(warning => warning.code === "global_config_unreadable");
+    return {
+      path,
+      issues: pathWarnings.map(summarizeProjectCodexIssue),
+      bypass: globalUnreadable ? pathWarnings[0]!.message : explainProjectConfigBypass(pathWarnings),
+      ...(globalUnreadable ? { globalUnreadable } : {}),
+    };
+  });
 }
 
 export function formatProjectCodexConfigWarningsForDoctor(warnings: ProjectCodexConfigWarning[]): string[] {
   const grouped = groupProjectCodexConfigWarningsByPath(warnings);
   if (grouped.length === 0) return [];
   const lines: string[] = [];
-  for (const { path, issues, bypass } of grouped) {
+  let hasBypassEntries = false;
+  for (const { path, issues, bypass, globalUnreadable } of grouped) {
     lines.push(`  --     ${relPath(path)} — ${issues.join(", ")}`);
     lines.push(`         ${bypass}`);
+    if (globalUnreadable) {
+      lines.push("       fix: keep the global config.toml a readable regular file within the 1 MiB bound");
+    } else {
+      hasBypassEntries = true;
+    }
+  }
+  if (hasBypassEntries) {
+    lines.push("       fix: remove those entries so OpenCodex proxy routing applies in this project");
   }
-  lines.push("       fix: remove those entries so OpenCodex proxy routing applies in this project");
   return lines;
 }
 
@@ -535,11 +578,19 @@ export function formatProjectCodexConfigWarningsForConsole(warnings: ProjectCode
   const grouped = groupProjectCodexConfigWarningsByPath(warnings);
   if (grouped.length === 0) return [];
   const lines = ["⚠️  Project Codex config bypasses OpenCodex:"];
-  for (const { path, issues, bypass } of grouped) {
+  let hasBypassEntries = false;
+  for (const { path, issues, bypass, globalUnreadable } of grouped) {
     lines.push(`    ${relPath(path)} — ${issues.join(", ")}`);
     lines.push(`    ${bypass}`);
+    if (globalUnreadable) {
+      lines.push("    fix: keep the global config.toml a readable regular file within the 1 MiB bound");
+    } else {
+      hasBypassEntries = true;
+    }
+  }
+  if (hasBypassEntries) {
+    lines.push("    fix: remove those entries so OpenCodex proxy routing applies in this project");
   }
-  lines.push("    fix: remove those entries so OpenCodex proxy routing applies in this project");
   return lines;
 }
 

package/src/codex/quota-auto-refresh-state.ts

@@ -2,10 +2,16 @@
 /** Completed/due markers use epoch milliseconds; persisted legacy markers may use seconds. */
 export type CodexQuotaAutoRefreshWindows = { fiveHour?: number; weekly?: number };
 
+/**
+ * Backoff evidence for one account. `generation` names the credential the failure was observed
+ * under; a record from another generation says nothing about the credential in use now.
+ */
+export type CodexQuotaRetry = { after: number; delay: number; generation: string };
+
 export const completedByAccount = new Map<string, CodexQuotaAutoRefreshWindows>();
-export const retryAfterByAccount = new Map<string, number>();
+export const retryAfterByAccount = new Map<string, CodexQuotaRetry>();
 export const scheduledByAccount = new Map<string, CodexQuotaAutoRefreshWindows>();
-export const quotaRefreshAfterByAccount = new Map<string, number>();
+export const quotaRefreshAfterByAccount = new Map<string, CodexQuotaRetry>();
 
 /** Drop every activation record when its account is removed. */
 export function forgetCodexQuotaAutoRefreshAccount(accountId: string): void {

package/src/codex/quota-auto-refresh.ts

@@ -21,13 +21,14 @@ import { CodexWarmupError, codexWarmupFailureReason, warmCodexAccount } from "./
 import {
   completedByAccount, retryAfterByAccount, scheduledByAccount, quotaRefreshAfterByAccount,
   resetCodexQuotaAutoRefreshStateForTests,
-  type CodexQuotaAutoRefreshWindows,
+  type CodexQuotaAutoRefreshWindows, type CodexQuotaRetry,
 } from "./quota-auto-refresh-state";
 export type { CodexQuotaAutoRefreshWindows } from "./quota-auto-refresh-state";
 export { forgetCodexQuotaAutoRefreshAccount } from "./quota-auto-refresh-state";
 
 export const FIVE_HOUR_WINDOW_SECONDS = 5 * 60 * 60;
 const RETRY_MS = 5 * 60_000;
+const MAX_RETRY_MS = 60 * 60_000;
 const CONCURRENCY = 4;
 
 export interface CodexQuotaAutoRefreshStatus {
@@ -51,6 +52,57 @@ export interface CodexQuotaAutoRefreshRunDeps {
 
 let inFlight: Promise<void> | null = null;
 
+const LOCAL_BUSY_RETRY_MS = 60_000;
+
+/** The native main profile was claimed locally, so no upstream request was sent. */
+export class NativeMainBusyError extends Error {
+  constructor() {
+    super("native main busy");
+    this.name = "NativeMainBusyError";
+  }
+}
+
+/** The credential a retry record describes: main's quota generation, or the pool record's. */
+function credentialGeneration(accountId: string): string {
+  return accountId === MAIN_CODEX_ACCOUNT_ID
+    ? `main:${getMainQuotaCredentialGeneration()}`
+    : `pool:${readCodexAccountRecord(accountId)?.generation ?? "none"}`;
+}
+
+/** A retry recorded under a replaced credential is spent; drop it rather than hold the new one. */
+function liveRetry(
+  retries: Map<string, CodexQuotaRetry>,
+  accountId: string,
+  generation: string,
+): CodexQuotaRetry | undefined {
+  const retry = retries.get(accountId);
+  if (retry && retry.generation !== generation) {
+    retries.delete(accountId);
+    return undefined;
+  }
+  return retry;
+}
+
+/** Back off unsuccessful discovery/activation without adding another timer. */
+function deferRetry(
+  retries: Map<string, CodexQuotaRetry>,
+  accountId: string,
+  now: number,
+  generation: string,
+): number {
+  const delay = Math.min((liveRetry(retries, accountId, generation)?.delay ?? RETRY_MS / 2) * 2, MAX_RETRY_MS);
+  retries.set(accountId, { after: now + delay, delay, generation });
+  return delay;
+}
+
+/** Every enabled window needs a retained, uncompleted deadline, not fresh usage percentages. */
+function hasScheduledWindows(config: OcxConfig, accountId: string): boolean {
+  const setting = config.codexQuotaAutoRefresh?.[accountId];
+  const scheduled = scheduledByAccount.get(accountId);
+  return (!setting?.fiveHour || scheduled?.fiveHour !== undefined)
+    && (!setting?.weekly || scheduled?.weekly !== undefined);
+}
+
 /** Report upstream window availability separately from persisted spending intent. */
 export function codexQuotaAutoRefreshStatus(
   config: OcxConfig,
@@ -187,7 +239,7 @@ async function warmAccount(config: OcxConfig, accountId: string): Promise<void |
     return;
   }
   const lease = tryAcquireNativeMainProfileClaim();
-  if (!lease) throw new Error("native main busy");
+  if (!lease) throw new NativeMainBusyError();
   try {
     reconcileMainCodexAccountRuntimeState();
     if (mainWarmupRestricted(config)) return false;
@@ -309,14 +361,21 @@ export async function runCodexQuotaAutoRefresh(
         // Capture before WHAM can move an idle window's reset into the future.
         rememberWindows(config, accountId, quotaFor(accountId));
         const quota = quotaFor(accountId);
-        if ((!quota || now - quota.updatedAt >= RETRY_MS)
-          && (quotaRefreshAfterByAccount.get(accountId) ?? 0) <= now) {
-          quotaRefreshAfterByAccount.set(accountId, now + RETRY_MS);
-          try { await refresh(config, accountId); } catch { /* Retry metadata at the bounded cadence. */ }
+        // A known deadline remains actionable even when its usage snapshot is old.
+        // Only discover missing windows; never poll merely to keep percentages fresh.
+        if (hasScheduledWindows(config, accountId)) {
+          quotaRefreshAfterByAccount.delete(accountId);
+        } else if ((!quota || now - quota.updatedAt >= RETRY_MS)
+          && (liveRetry(quotaRefreshAfterByAccount, accountId, credentialGeneration(accountId))?.after ?? 0) <= now) {
+          deferRetry(quotaRefreshAfterByAccount, accountId, now, credentialGeneration(accountId));
+          try { await refresh(config, accountId); } catch { /* Retry missing metadata with backoff. */ }
         }
         if (!eligible(accountId)) return;
         rememberWindows(config, accountId, quotaFor(accountId));
-        if ((retryAfterByAccount.get(accountId) ?? 0) > now) return;
+        // Backoff from a replaced credential is dropped here, so reauthenticating or rotating an
+        // account never waits out the failures of the credential it replaced.
+        const generation = credentialGeneration(accountId);
+        if ((liveRetry(retryAfterByAccount, accountId, generation)?.after ?? 0) > now) return;
         const windows = dueCodexQuotaAutoRefreshWindows(config, accountId, quotaFor(accountId), now);
         if (!windows) return;
         try {
@@ -327,11 +386,23 @@ export async function runCodexQuotaAutoRefresh(
           persist(config, accountId, completed);
           rememberWindows(config, accountId, quotaFor(accountId));
         } catch (error) {
-          retryAfterByAccount.set(accountId, now + RETRY_MS);
+          // A failure that raced a credential replacement describes the old credential; the next
+          // sweep evaluates the replacement on its own evidence.
+          if (credentialGeneration(accountId) !== generation) return;
+          if (error instanceof NativeMainBusyError) {
+            // Local admission refused before any upstream request: retry soon, and keep the
+            // upstream backoff where it was instead of doubling it.
+            const previous = liveRetry(retryAfterByAccount, accountId, generation);
+            retryAfterByAccount.set(accountId, {
+              after: now + LOCAL_BUSY_RETRY_MS, delay: previous?.delay ?? RETRY_MS / 2, generation,
+            });
+            return;
+          }
+          const delay = deferRetry(retryAfterByAccount, accountId, now, generation);
           const account = config.codexAccounts?.find(candidate => candidate.id === accountId);
           const label = account ? codexAccountLogLabel(account) : "main";
           console.warn(`[codex-quota-auto-refresh] ${label}: ${codexWarmupFailureReason(error)}; ${
-            isAccountNeedsReauth(accountId) ? "reauthentication required" : "retry in five minutes"
+            isAccountNeedsReauth(accountId) ? "reauthentication required" : `retry in ${delay / 60_000} minutes`
           }`);
         }
       }));

package/src/codex/sync.ts

@@ -132,6 +132,16 @@ export async function syncModelsToCodex(
   // the injector, before it gets a chance to create any artifact.
   const admission = (deps.admitCodexWrite ?? admitCodexWrite)();
   if (admission.kind === "refused" && admission.authority === "service-home") {
+    // Startup turns this result into a failed /readyz and records nothing else, and
+    // `ocx sync` only says the sync did not complete, so an unattended refusal must
+    // leave one line behind (#5782). The admission message can name private home and
+    // service-definition paths, so the log carries the authority only; POST /api/sync
+    // returns the specific reason to an authenticated operator.
+    log?.error(
+      "[opencodex] Codex write refused (service-home): this proxy could not prove it owns the "
+        + "installed service homes, so catalog sync and Codex config injection were skipped. "
+        + "POST /api/sync returns the specific reason.",
+    );
     return {
       status: "refused",
       authority: "service-home",

package/src/combos/failover.ts

@@ -326,7 +326,10 @@ function normalizedFailureCode(code?: string | null): string {
 // are quota-limit codes whose window length this gateway has no evidence for, and guessing long on
 // them would hold a target that may clear sooner.
 const ACCOUNT_EXHAUSTION_CODES = new Set(["usage_limit_exceeded", "usage_limit_reached", "1308"]);
-const ACCOUNT_EXHAUSTION_TEXT = /usage limit (?:has been )?reached/;
+// Token-plan windows (Alibaba's DeepSeek/Qwen plans) report "Your token-plan 1-week quota has been
+// exhausted" (#5494). The match is anchored to that phrasing: a looser "quota ... exhausted" would
+// also catch per-minute limits, and this arm outranks the transient rate-limit duration.
+const ACCOUNT_EXHAUSTION_TEXT = /usage limit (?:has been )?reached|token-plan\s+\S+\s+quota has been exhausted/;
 
 function isAccountWindowExhausted(message: string, code?: string | null): boolean {
   return ACCOUNT_EXHAUSTION_CODES.has(normalizedFailureCode(code))

package/src/combos/jev.ts

@@ -6,6 +6,7 @@ import {
 import { resolveProviderApiKey } from "../providers/api-key-resolve";
 import { providerMatchesRegistryTransport } from "../providers/registry";
 import type { OcxComboDefaultEffort, OcxConfig, OcxProviderConfig } from "../types";
+import { JEV_MAX_CANDIDATE_FIELD_CHARS } from "./types";
 
 export const JEV_PROVIDER_ID = "jev";
 export const JEV_API_URL = "https://api.typesafe.ai/v1/systemone";
@@ -13,7 +14,6 @@ export const JEV_MODEL = "jev-latest";
 
 const JEV_TIMEOUT_MS = 4_000;
 const JEV_MAX_CANDIDATES = 64;
-const JEV_MAX_CANDIDATE_FIELD_CHARS = 512;
 const JEV_MAX_REQUEST_BYTES = 65_536;
 const JEV_MAX_RESPONSE_BYTES = 65_536;
 const JEV_OUTBOUND_DEPENDENCIES = {
@@ -70,6 +70,8 @@ export interface JevCandidate {
   provider: string;
   model: string;
   reasoningEfforts: readonly OcxComboDefaultEffort[];
+  /** Optional operator note sent as decision evidence for this target only. */
+  modelProfile?: string;
 }
 
 export interface JevDecision {
@@ -337,7 +339,7 @@ function hasImageContent(item: Record<string, unknown>): boolean {
   return item.content.some(part => isRecord(part) && (part.type === "input_image" || part.type === "image_url"));
 }
 
-export function buildJevState(body: unknown): Record<string, unknown> {
+export function buildJevState(body: unknown, candidates: readonly JevCandidate[] = []): Record<string, unknown> {
   const input = isRecord(body) ? body.input : undefined;
   let task = "";
   let previousAssistant = "";
@@ -383,11 +385,18 @@ export function buildJevState(body: unknown): Record<string, unknown> {
     }
   }
 
+  const operatorNotes: Record<string, string> = {};
+  for (const candidate of candidates) {
+    const note = candidate.modelProfile?.trim();
+    if (note) operatorNotes[candidate.key] = note;
+  }
+
   return {
     task,
     signals: { has_image: hasImage, tool_history: toolHistory },
     step,
     ...(previousAssistant ? { previous_assistant: previousAssistant.slice(-ASSISTANT_TAIL_CHARS) } : {}),
+    ...(Object.keys(operatorNotes).length ? { operator_notes: operatorNotes } : {}),
   };
 }
 
@@ -425,7 +434,9 @@ function candidateOptions(candidates: readonly JevCandidate[]): Map<string, JevR
 function candidatesFitRequestBounds(candidates: readonly JevCandidate[]): boolean {
   if (candidates.length > JEV_MAX_CANDIDATES) return false;
   return candidates.every(candidate => [candidate.key, candidate.provider, candidate.model]
-    .every(value => value.length > 0 && value.length <= JEV_MAX_CANDIDATE_FIELD_CHARS));
+    .every(value => value.length > 0 && value.length <= JEV_MAX_CANDIDATE_FIELD_CHARS)
+    && (candidate.modelProfile === undefined
+      || (typeof candidate.modelProfile === "string" && candidate.modelProfile.length <= JEV_MAX_CANDIDATE_FIELD_CHARS)));
 }
 
 function modelProfile(candidate: JevCandidate): string {
@@ -566,7 +577,7 @@ export async function resolveJevDecision(options: ResolveJevDecisionOptions): Pr
 
   let requestBody: string;
   try {
-    const state = buildJevState(options.body);
+    const state = buildJevState(options.body, options.candidates);
     if (!hasJevDecisionState(state)) return failed("no_state");
     requestBody = JSON.stringify({
       model: JEV_MODEL,

package/src/combos/types.ts

@@ -4,6 +4,7 @@ import type { OcxComboConfig, OcxComboCooldownWaitPolicy, OcxComboDefaultEffort,
 import { COMBO_NAMESPACE, isValidComboId, targetKey } from "./identifiers";
 
 export const COMBO_DEFAULT_WAIT_FOR_COOLDOWN_MS = 0;
+export const JEV_MAX_CANDIDATE_FIELD_CHARS = 512;
 export { COMBO_NAMESPACE, preservesPhysicalComboProvider, isNativeAliasCombo, targetKey, parseComboModelId, comboModelId, comboPublicModelId, comboDisabledModelId, comboDisabledModelSelectors, resolveComboId, isValidComboId } from "./identifiers";
 
 /**
@@ -27,6 +28,8 @@ export interface NormalizedComboTarget {
   /** Emergency-only target, deferred under `cooldownWaitPolicy` (#5691). */
   lastResort: boolean;
   reasoningEfforts?: OcxComboDefaultEffort[];
+  /** Optional JEV decision description. */
+  modelProfile?: string;
 }
 
 export interface NormalizedComboConfig {
@@ -333,6 +336,16 @@ export function comboConfigIssues(
         message: `targets[${i}].lastResort must be a boolean`,
       });
     }
+    if (target.modelProfile !== undefined
+      && (typeof target.modelProfile !== "string"
+        || target.modelProfile.trim().length === 0
+        || target.modelProfile.length > JEV_MAX_CANDIDATE_FIELD_CHARS
+        || /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/.test(target.modelProfile))) {
+      issues.push({
+        path: ["targets", i, "modelProfile"],
+        message: `targets[${i}].modelProfile must be a non-empty string of at most ${JEV_MAX_CANDIDATE_FIELD_CHARS} characters; only tab, line feed and carriage return are allowed among control characters`,
+      });
+    }
 
     if (provider && model) {
       const key = targetKey({ provider, model });
@@ -389,6 +402,9 @@ export function normalizeComboConfig(raw: OcxComboConfig): NormalizedComboConfig
       ...(target.reasoningEfforts !== undefined
         ? { reasoningEfforts: [...target.reasoningEfforts] }
         : {}),
+      ...(typeof target.modelProfile === "string" && target.modelProfile.trim()
+        ? { modelProfile: target.modelProfile.trim() }
+        : {}),
       lastResort: target.lastResort === true,
     })),
   };

package/src/config/diagnostics.ts

@@ -63,6 +63,8 @@ import {
   runtimeRoleSchema,
   spendSchema,
   compactionRoutingSchema,
+  skillsConfigSchema,
+  memoryModelsSchema,
 } from "./schema/leaf-validators";
 
 export type ConfigDiagnostics = {
@@ -594,11 +596,26 @@ export function metricsExportConfigError(value: unknown): string | null {
   return null;
 }
 
+
+function skillsConfigError(value: unknown): string | null {
+  const raw = rawConfigRecord(value);
+  if (!raw || !Object.hasOwn(raw, "skills") || raw.skills === undefined) return null;
+  const result = skillsConfigSchema.safeParse(raw.skills);
+  if (result.success) return null;
+  const issue = result.error.issues[0];
+  const field = issue?.path.join(".");
+  return "schema_invalid: skills" + (field ? "." + field : "") + ": " + (issue?.message ?? "invalid configuration");
+}
+
 export function validateConfigCandidate(value: unknown): { ok: true; config: OcxConfig } | { ok: false; error: string } {
   const compactionRouting = rawConfigRecord(value)?.compactionRouting;
   if (compactionRouting !== undefined && !compactionRoutingSchema.safeParse(compactionRouting).success) {
     return { ok: false, error: "schema_invalid: compactionRouting: requires a nonblank model, an optional valid reasoningEffort, and optional non-repeating triggers drawn from \"manual\" and \"auto\"" };
   }
+  const memoryModels = rawConfigRecord(value)?.memoryModels;
+  if (memoryModels !== undefined && !memoryModelsSchema.safeParse(memoryModels).success) {
+    return { ok: false, error: "schema_invalid: memoryModels: requires a nonblank model and an optional declared reasoningEffort per configured phase, and no other fields" };
+  }
   const boundaryError = compactionRecoveryConfigError(value) ?? configReasoningPinsConfigError(value)
     ?? blankHostnameError(value)
     ?? claudeSubagentEffortError(value)
@@ -625,7 +642,8 @@ export function validateConfigCandidate(value: unknown): { ok: true; config: Ocx
     ?? clientRolePairError(value)
     ?? loopbackListenerPortError(value)
     ?? managementIngressConfigError(value)
-    ?? metricsExportConfigError(value);
+    ?? metricsExportConfigError(value)
+    ?? skillsConfigError(value);
   if (boundaryError) return { ok: false, error: boundaryError };
   const result = configSchema.safeParse(value);
   if (result.success) {

package/src/config/load-degrade.ts

@@ -122,6 +122,35 @@ export function warnDegradedTopLevelOptIns(rawParsed: unknown, validated: OcxCon
   if (compactionRecoveryConfigError(rawParsed)) console.warn("⚠️  invalid compactionRecovery disabled; the original compaction failure is preserved");
   warnDegradedStreamMode(rawParsed, validated);
   warnDegradedCompactionRouting(rawParsed, validated);
+  warnDegradedMemoryModels(rawParsed, validated);
+}
+
+/**
+ * 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");
+    }
+  }
 }
 
 /**