@bitkyc08/opencodex 2.59.0 → 2.60.0

package/src/codex/model-entitlements.ts

@@ -2,7 +2,11 @@ import { createHash } from "node:crypto";
 import { readBoundedResponseBody } from "../lib/bounded-body";
 import type { CodexAccountCredentialRecord, OcxConfig } from "../types";
 import { isSelectableCodexPoolAccount } from "./account-id";
-import { getValidCodexToken, loadCodexAccountRecordSnapshot } from "./account-store";
+import {
+  beginCodexAccountGenerationLiveCheck,
+  getValidCodexToken,
+  loadCodexAccountRecordSnapshot,
+} from "./account-store";
 import {
   getMainAccountToken,
   getValidMainAccountToken,
@@ -22,6 +26,7 @@ import {
   forgetObservedCodexModelDenialsForAccount,
   observedDeniedCodexAccountIdsForModel,
   recordObservedCodexModelDenial,
+  setObservedDenialGenerationCheck,
   resetObservedCodexModelDenialsForTests,
 } from "./observed-model-denials";
 
@@ -1297,13 +1302,14 @@ export function cachedDeniedCodexAccountIdsForModel(
   // absent an ongoing catalog sync the loop above contributes nothing at all. An upstream
   // refusal does not expire on that schedule and is not a snapshot of a pending answer: it is
   // the account's own Codex surface naming this model and declining it (#4906).
-  for (const accountId of observedDeniedCodexAccountIdsForModel(modelId, now) ?? []) {
-    // Under the caller's read fence, like the roster loop above. Nothing here reads account
-    // storage, but an excluded account must stay UNKNOWN rather than denied so a profile switch
-    // or a request-owned credential produces the same selection it does today.
-    if (options.excludeAccountIds?.has(accountId)) continue;
-    denied.add(accountId);
-  }
+  // The caller's read fence is passed IN rather than applied to the result, so an excluded
+  // account is skipped before the credential-generation validation reads account storage
+  // (#4952). An excluded account must stay UNKNOWN rather than denied, so a profile switch or
+  // a request-owned credential produces the same selection it does today.
+  const observedDenied = observedDeniedCodexAccountIdsForModel(modelId, now, {
+    ...(options.excludeAccountIds ? { excludeAccountIds: options.excludeAccountIds } : {}),
+  });
+  for (const accountId of observedDenied ?? []) denied.add(accountId);
   // One account holds one entry per client version, and upstream filters the roster by that
   // version. So the same account can legitimately carry a granted entry under a current client
   // and a denied one under an older client that predates the model. Positive evidence is
@@ -1330,23 +1336,36 @@ export function cachedDeniedCodexAccountIdsForModel(
  * admissible here: 400 covers every malformed request too, and remembering one of those as an
  * entitlement fact would steer routing away from a perfectly capable account.
  */
+// Denial evidence is credential-scoped (#4952). The store stays a leaf module, so the
+// liveness predicate is injected here, where the account store is already a dependency.
+setObservedDenialGenerationCheck(beginCodexAccountGenerationLiveCheck);
+
 export function recordCodexModelDenialEvidence(
   accountId: string | null | undefined,
   modelId: string | undefined,
+  generation: number | null | undefined,
   now = Date.now(),
 ): void {
   if (!accountId || !modelId) return;
   if (!ENTITLEMENT_PREFERRED_NATIVE_OPENAI_MODELS.has(modelId)) return;
-  recordObservedCodexModelDenial(accountId, modelId, now);
+  // A caller that cannot name a credential generation records ACCOUNT-scoped evidence rather
+  // than none. The one production context in that position is `main-pool`, whose credential
+  // lives in `auth.json` and has no pool generation; discarding its refusals would revert
+  // #4906 for the stored main login (#4952). Request-owned `main` never reaches here — its
+  // `accountId` is null and the guard above returns.
+  recordObservedCodexModelDenial(accountId, modelId, typeof generation === "number" ? generation : undefined, now);
 }
 
 /** Drop the refusal evidence for a pair the account has just served successfully. */
 export function clearCodexModelDenialEvidence(
   accountId: string | null | undefined,
   modelId: string | undefined,
+  generation: number | null | undefined,
 ): void {
   if (!accountId || !modelId) return;
-  clearObservedCodexModelDenial(accountId, modelId);
+  // Mirror of the write: an account-scoped success clears account-scoped evidence. It cannot
+  // clear a credential-scoped entry that names a newer generation, and vice versa (#4952).
+  clearObservedCodexModelDenial(accountId, modelId, typeof generation === "number" ? generation : undefined);
 }
 
 /** Synchronous projection for management/catalog readers after a discovery pass. */

package/src/codex/observed-model-denials.ts

@@ -48,8 +48,55 @@ const OBSERVED_DENIAL_TTL_MS = 6 * 60 * 60_000;
 /** Bounded like the roster cache: pool size times flagship count, with room to spare. */
 const OBSERVED_DENIAL_MAX_ENTRIES = 512;
 
-/** `accountId\u0000modelId` -> expiry. Insertion order is the eviction order. */
-const observedDenials = new Map<string, number>();
+/**
+ * One entry of refusal evidence.
+ *
+ * `generation` is the credential generation the refusal was observed under (#4952). Evidence
+ * is about a CREDENTIAL, not an account id: reauthenticating the same internal account can
+ * swap the subscription underneath it, so a refusal from the previous credential says nothing
+ * about the replacement. Carrying the generation lets a reader ignore superseded evidence and
+ * lets a late reply from an older generation be refused rather than applied.
+ *
+ * It is OPTIONAL because not every account that can be refused has one. A `main-pool` context
+ * — the stored main login taking part in rotation — carries a real `accountId` and a
+ * `writerGeneration`, but no pool credential generation, because its credential lives in
+ * `auth.json` rather than the pool store. Dropping its evidence would have silently reverted
+ * #4906 for that account: the pool would re-send the same model to the login that just refused
+ * it, on every request, forever. An entry without a generation is account-scoped, and the
+ * generation fences below simply do not apply to it. This is the same rule the quota writer
+ * already uses in `core-codex-account.ts`, where an absent credential generation skips the
+ * liveness check instead of discarding the write.
+ */
+interface ObservedDenial {
+  expiresAt: number;
+  generation?: number;
+}
+
+/** `accountId\u0000modelId` -> entry. Insertion order is the eviction order. */
+const observedDenials = new Map<string, ObservedDenial>();
+
+/** Whether `generation` is still the account's live credential. */
+type GenerationLiveCheck = (accountId: string, generation: number) => boolean;
+
+/**
+ * Opens one liveness check.
+ *
+ * A FACTORY rather than a bare predicate because the production implementation reads the
+ * credential store, and a lookup can ask about several accounts. Loading once per lookup and
+ * closing over that snapshot is the shape `loadCodexAccountRecordSnapshot` exists for; a bare
+ * predicate would reload and reparse the whole store per row, on the request path.
+ *
+ * Injected rather than imported at module scope so this stays a leaf module: `account-store`
+ * reads the credential file, and a unit test of this map should not have to stand one up.
+ */
+type GenerationLiveCheckFactory = () => GenerationLiveCheck;
+
+let beginGenerationLiveCheck: GenerationLiveCheckFactory = () => () => true;
+
+/** Wire the liveness predicate. Called once at startup; tests substitute their own. */
+export function setObservedDenialGenerationCheck(begin: GenerationLiveCheckFactory): void {
+  beginGenerationLiveCheck = begin;
+}
 
 function denialKey(accountId: string, modelId: string): string {
   return `${accountId}\u0000${modelId}`;
@@ -72,12 +119,24 @@ function modelIdOfDenialKey(key: string): string {
 export function recordObservedCodexModelDenial(
   accountId: string,
   modelId: string,
+  generation: number | undefined,
   now = Date.now(),
 ): void {
+  // A refusal dispatched under generation G can arrive after G+1 has been saved. Reject it
+  // BEFORE touching the map at all, not merely when this key already holds newer evidence:
+  // with no entry for this key the stale row would otherwise be inserted, and at the entry
+  // bound it would evict a valid row that nothing can restore (#4952).
+  if (generation !== undefined && !beginGenerationLiveCheck()(accountId, generation)) return;
   const key = denialKey(accountId, modelId);
+  const existing = observedDenials.get(key);
+  // Second fence, for the window where the replacement credential has been dispatched but the
+  // store read above still answers live. Both sides must name a generation to be comparable;
+  // an account-scoped entry is not older or newer than a credential-scoped one.
+  if (existing !== undefined && existing.generation !== undefined && generation !== undefined
+    && existing.generation > generation) return;
   // Delete before set so the refreshed entry moves to the back of the eviction order.
   observedDenials.delete(key);
-  observedDenials.set(key, now + OBSERVED_DENIAL_TTL_MS);
+  observedDenials.set(key, { expiresAt: now + OBSERVED_DENIAL_TTL_MS, generation });
   while (observedDenials.size > OBSERVED_DENIAL_MAX_ENTRIES) {
     const oldest = observedDenials.keys().next();
     if (oldest.done) break;
@@ -91,8 +150,20 @@ export function recordObservedCodexModelDenial(
  * A success is newer and stronger evidence than the refusal that preceded it: whatever the
  * entitlement was when upstream refused, it is not that now.
  */
-export function clearObservedCodexModelDenial(accountId: string, modelId: string): void {
-  observedDenials.delete(denialKey(accountId, modelId));
+export function clearObservedCodexModelDenial(
+  accountId: string,
+  modelId: string,
+  generation: number | undefined,
+): void {
+  const key = denialKey(accountId, modelId);
+  const existing = observedDenials.get(key);
+  if (!existing) return;
+  // The mirror of the write fence: a success dispatched under G arriving after G+1 was
+  // refused must not clear the replacement's evidence (#4952). Equal generations clear,
+  // because that is the ordinary "this account just served this model" case.
+  if (existing.generation !== undefined && generation !== undefined
+    && existing.generation > generation) return;
+  observedDenials.delete(key);
 }
 
 /**
@@ -119,19 +190,41 @@ export function forgetObservedCodexModelDenialsForAccount(accountId: string | nu
 export function observedDeniedCodexAccountIdsForModel(
   modelId: string | undefined,
   now = Date.now(),
+  options: { excludeAccountIds?: ReadonlySet<string> } = {},
 ): ReadonlySet<string> | undefined {
   if (!modelId) return undefined;
   const denied = new Set<string>();
-  for (const [key, expiresAt] of [...observedDenials]) {
-    if (expiresAt <= now) {
+  // Opened lazily and at most once: a lookup that matches no credential-scoped row must not
+  // read the credential store at all.
+  let isLive: GenerationLiveCheck | undefined;
+  for (const [key, entry] of [...observedDenials]) {
+    if (entry.expiresAt <= now) {
       observedDenials.delete(key);
       continue;
     }
-    if (modelIdOfDenialKey(key) === modelId) denied.add(accountIdOfDenialKey(key));
+    // Model and the caller's exclusion fence FIRST. The issue asks for identity validation
+    // after the exclusion read, and an excluded account — a draining profile switch, or a
+    // request-owned credential — must produce no credential-store read on its behalf.
+    if (modelIdOfDenialKey(key) !== modelId) continue;
+    const accountId = accountIdOfDenialKey(key);
+    if (options.excludeAccountIds?.has(accountId)) continue;
+    if (entry.generation !== undefined) {
+      isLive ??= beginGenerationLiveCheck();
+      // Superseded evidence stops denying the replacement. It is SKIPPED, not deleted: the
+      // predicate cannot tell "this account reauthenticated" from "the credential store could
+      // not be read", and deleting on the second would throw away valid evidence that a
+      // transient read failure was never entitled to touch. Skipping already delivers the
+      // routing outcome the issue asks for, on every read, without depending on the
+      // conditional account-wide forget that cannot run when no roster was ever cached.
+      // Superseded rows still leave by TTL, by eviction, and by the account-wide forget.
+      if (!isLive(accountId, entry.generation)) continue;
+    }
+    denied.add(accountId);
   }
   return denied.size > 0 ? denied : undefined;
 }
 
 export function resetObservedCodexModelDenialsForTests(): void {
   observedDenials.clear();
+  beginGenerationLiveCheck = () => () => true;
 }

package/src/codex/prompt-text-probe.ts

@@ -75,7 +75,7 @@ const UNMAPPED_LAYER_IDS = [
   // The Rust source names a <git_attribution> marker pair, but a world-state section is
   // DIFF-rendered: it emits nothing on a turn where its state has not changed. Live
   // `codex debug prompt-input` (codex-cli 0.145.0, 32978 bytes) showed no such block and
-  // no attribution text. Listing the id here reports "not exposed" honestly instead of
+  // no attribution text. Listing the id here reports "unmapped" honestly instead of
   // claiming a tag this extractor has never actually matched - the same mistake the
   // header above records for permissions.
   "git-attribution",
@@ -85,7 +85,7 @@ export interface LayerText {
   /** Rendered text, when this layer produced a section on the probed turn. */
   text: string | null;
   /** Why the text is absent, when it is. */
-  reason: "ok" | "empty-source" | "not-rendered" | "not-exposed" | "unavailable";
+  reason: "ok" | "empty-source" | "not-rendered" | "not-exposed" | "unmapped" | "unavailable";
   bytes: number;
   /**
    * `expanded` is text Codex sends as written. `template` is a catalog
@@ -103,7 +103,7 @@ export interface LayerText {
 
 /**
  * Why the base prompt is or is not readable, at the granularity a reader can act
- * on. `LayerText.reason` has five coarse values and cannot express any of this,
+ * on. `LayerText.reason` has six coarse values and cannot express any of this,
  * which is why the detailed answer travels on its own record.
  */
 export type BasePromptReason =
@@ -374,7 +374,7 @@ function readBasePrompt(codexHome: string): BasePromptText {
 /**
  * Project the base prompt onto the legacy `base-instructions` layer slot.
  *
- * The slot is lossy by construction - five coarse reasons, no renderer that reads
+ * The slot is lossy by construction - six coarse reasons, no renderer that reads
  * `representation` - so it carries only what it can carry honestly: published text
  * when the source is text Codex sends, and otherwise no text at all. A template is
  * deliberately NOT `ok` here, because the dialog labels every `ok` layer "Text
@@ -944,9 +944,12 @@ export async function probePromptText(
 
   // Layers whose rendered tag we have not confirmed against live output. Leaving
   // them absent made the GUI fall through to "unavailable", which claims the probe
-  // failed when it succeeded. Saying we have no mapping is the smaller claim.
+  // failed when it succeeded. Keep this distinct from the base prompt's
+  // "not-exposed", which is confirmed to travel outside the printable message
+  // list - reusing it showed a base-prompt-specific explanation for unrelated
+  // layers.
   for (const id of UNMAPPED_LAYER_IDS) {
-    layers[id] ??= { text: null, reason: "not-exposed", bytes: 0 };
+    layers[id] ??= { text: null, reason: "unmapped", bytes: 0 };
   }
   return { ok: true, codexHome, layers, base, ...(reportedRuntime ? { runtime: reportedRuntime } : {}) };
 }

package/src/codex/routing.ts

@@ -1,5 +1,6 @@
 import { saveConfigPreservingClaudeCode } from "../config";
-import { isCodexAccountGenerationLive } from "./account-store";
+import { isCodexAccountGenerationLive, registerCodexRefreshGenerationHandoff } from "./account-store";
+import { handOffThreadAffinityGeneration } from "./routing/thread-affinity";
 import { codexAccountLogLabel } from "./account-label";
 import { isCodexAccountPaused } from "./account-pause";
 import { clearCodexAccountPin, pinnedCodexAccountId } from "./account-priority";
@@ -205,6 +206,11 @@ export {
 } from "./routing/active-account";
 export { codexAccountPinDrainReason } from "./routing/pin-drain";
 export type { CodexPinDrainReason } from "./routing/pin-drain";
+
+// A shared refresh can outlive the request that opened it. Register the affinity
+// handoff with the flight so a detached G -> G+1 commit cannot strand bindings at G.
+registerCodexRefreshGenerationHandoff(handOffThreadAffinityGeneration);
+
 function hasConfiguredPoolAccount(
   config: OcxConfig,
   accountId: string,

package/src/codex/shim.ts

@@ -241,7 +241,7 @@ function backupPathFor(path: string): string {
  */
 function destroyedShimMessage(file: ShimFileState): string {
   const wrapper = existsSync(file.wrapperPath)
-    ? isShim(file.wrapperPath) ? "present but unusable" : "present but not an opencodex shim"
+    ? stableShimPathProbe(file.wrapperPath)?.prefix.includes(SHIM_MARKER) ? "present but unusable" : "present but not an opencodex shim"
     : "missing";
   const backup = existsSync(file.backupPath) ? "present" : "missing";
   const base = `Codex autostart shim not restored: wrapper ${wrapper} at ${file.wrapperPath}; original backup ${backup} at ${file.backupPath}.`;

package/src/codex/subagent-model-fallback.ts

@@ -905,8 +905,16 @@ export function hasCodexAgentModelFallbackField(role: string, codexHome = CODEX_
 }
 
 /** Roles whose TOML still carries `model_fallback`, including empty arrays. */
-export function scanCodexAgentRolesWithTomlModelFallback(codexHome = CODEX_HOME): string[] {
-  return listCodexAgentRoles(codexHome).filter(role => hasCodexAgentModelFallbackField(role, codexHome));
+export function scanCodexAgentRolesWithTomlModelFallback(
+  codexHome = CODEX_HOME,
+  onListError?: (cause: unknown) => void,
+): string[] {
+  try {
+    return listCodexAgentRoles(codexHome).filter(role => hasCodexAgentModelFallbackField(role, codexHome));
+  } catch (cause) {
+    onListError?.(cause);
+    return [];
+  }
 }
 
 const TOML_MODEL_KEY = /^\s*(?:model|"model"|'model')\s*=/;
@@ -984,9 +992,19 @@ const OPENCODEX_DERIVED_ROLE_MARKERS = ["generated-by: opencodex", "ocx-route:"]
  * authorizes writing to, repairing, or removing these files, and the marker-based ownership rules
  * that govern the files opencodex does write are unchanged.
  */
-export function scanOpencodexDerivedCodexAgentRolesWithoutModelPin(codexHome = CODEX_HOME): string[] {
+export function scanOpencodexDerivedCodexAgentRolesWithoutModelPin(
+  codexHome = CODEX_HOME,
+  onListError?: (cause: unknown) => void,
+): string[] {
   const findings: string[] = [];
-  for (const role of listCodexAgentRoles(codexHome)) {
+  let roles: string[];
+  try {
+    roles = listCodexAgentRoles(codexHome);
+  } catch (cause) {
+    onListError?.(cause);
+    return [];
+  }
+  for (const role of roles) {
     let content: string;
     try {
       content = readFileSync(join(codexHome, "agents", `${role}.toml`), "utf8");

package/src/combos/failover.ts

@@ -399,6 +399,9 @@ function isRequestLocalTargetIncompatibility(status: number, message: string, co
     if (errorCode === "unsupported_value"
       && (e.param === "reasoning.effort" || e.param === "reasoning_effort")
       && e.message.startsWith("Unsupported value:") && e.message.includes("not supported")) return true;
+    if (e.code === null
+      && e.param === "reasoning_effort"
+      && /^Function tools with reasoning_effort are not supported for gpt-6-astra(?:-\d{4}-\d{2}-\d{2})? in \/v1\/chat\/completions\. To use function tools, use \/v1\/responses or set reasoning_effort to 'none'\.$/.test(e.message)) return true;
     return e.param === "input"
       && (errorCode === "" || errorCode === "invalid_request_error")
       && /^Model '[^']{1,256}' does not support image inputs\./.test(e.message);

package/src/config/admitted-identity.ts

@@ -0,0 +1,222 @@
+import { readConfigAdmissionSnapshot } from "./diagnostics";
+import { getConfigPath } from "./paths";
+import { canonicalPlainData, copyPlainData, isPlainObject, ownDataKeys } from "../lib/plain-data";
+import type { OcxConfig } from "../types";
+
+/**
+ * A configuration a roster may be built from, detached from the object the caller holds.
+ *
+ * The detachment is the point. A gather suspends, and while it is suspended a management route can
+ * edit the resident configuration in place; gathering from one state and projecting from another
+ * would produce rows that belong to neither. Every authoritative pass uses this copy from
+ * beginning to end, so what the resident object does in the meantime becomes a question about
+ * whether the result may be retained rather than a question about what the result is.
+ *
+ * What this deliberately does NOT do is require the resident configuration to equal the file on
+ * disk. The proxy routes by the configuration it is holding, so that is the configuration a
+ * preview and the mutation it authorizes must both describe. A file the operator has edited and
+ * the process has not adopted is a supported state rather than a fault: live reconciliation
+ * (src/config/live-reconcile.ts) merges persisted state while deliberately retaining live changes
+ * and the active listener binding, and can persist a binding the resident object does not have.
+ * Demanding equality would make preview permanently unavailable on exactly those configurations
+ * while proving nothing about the rows, which come from the resident object either way.
+ */
+export interface ExportConfigAdmission {
+  readonly config: OcxConfig;
+}
+
+/**
+ * What was true when an admission was captured, kept here rather than on the admission object.
+ *
+ * None of it is data a consumer has any business reading: the file term is a digest of the
+ * operator's configuration file and the canonical form contains their credentials. Holding it in a
+ * module WeakMap means an admission can be passed around, and even serialized by a careless
+ * caller, without carrying any of it.
+ */
+interface AdmissionEvidence {
+  readonly path: string;
+  readonly file: string;
+  readonly data: string;
+  readonly executors: ReadonlyMap<string, unknown>;
+}
+
+const evidence = new WeakMap<ExportConfigAdmission, AdmissionEvidence>();
+
+/**
+ * Detach the configuration a roster is about to be built from, and record what it was.
+ *
+ * Two things are recorded because two things can move independently. The resident configuration is
+ * what the rows are derived from, so its complete structure is captured: structurally rather than
+ * as a list of the fields that seemed to matter, because such a list is only as complete as
+ * whoever last thought about it and this one had already missed export-affecting configuration.
+ * The configuration file is recorded beside it, so a roster does not outlive an operator editing
+ * the configuration under a process that has not adopted it yet.
+ *
+ * Null when the file cannot be read, when it is there but the loader would have had to salvage it,
+ * and when the configuration object cannot be copied as plain data. Every caller fails closed on
+ * it: refusing a preview costs an ordinary load, and serving one that describes a configuration
+ * nobody has costs a file the operator did not ask for.
+ */
+export function captureExportConfigAdmission(live: OcxConfig): ExportConfigAdmission | null {
+  const path = getConfigPath();
+  const file = admittedFileTerm();
+  if (file === null) return null;
+  const resident = detachConfig(live);
+  if (resident === null) return null;
+  const config = withExecutors(resident);
+  if (config === null) return null;
+  const admission: ExportConfigAdmission = { config };
+  evidence.set(admission, { path, file, data: canonicalPlainData(resident.data), executors: resident.executors });
+  return admission;
+}
+
+/**
+ * Whether an admission still describes the configuration in hand and the file it was taken beside.
+ *
+ * Three things are checked because three things can move: the file can be rewritten, the resident
+ * object can be edited in place, and a consumer of the detached copy can mutate what it was given.
+ * The last matters as much as the others, because a pass that edited its own input and then
+ * published would be retaining a roster under a state that no longer describes even that input.
+ *
+ * Passive: it reads the configuration file and nothing else. No credential is resolved, no
+ * provider is contacted, no path is hardened and nothing is written.
+ */
+export function isExportConfigAdmissionCurrent(admission: ExportConfigAdmission, live: OcxConfig): boolean {
+  const captured = evidence.get(admission);
+  if (captured === undefined) return false;
+  // A different configuration home is a different question, not a stale answer to this one.
+  if (getConfigPath() !== captured.path) return false;
+  const file = admittedFileTerm();
+  if (file === null || file !== captured.file) return false;
+  const resident = detachConfig(live);
+  if (resident === null || canonicalPlainData(resident.data) !== captured.data) return false;
+  if (!sameExecutors(resident.executors, captured.executors)) return false;
+  const working = detachConfig(admission.config);
+  return working !== null
+    && canonicalPlainData(working.data) === captured.data
+    && sameExecutors(working.executors, captured.executors);
+}
+
+/**
+ * A plain-data copy of a configuration for a consumer that must not observe later edits, or null.
+ *
+ * The integration writer is the case this exists for. It freezes every other resolution seam
+ * before its first await and then held the configuration by reference, so a plan checked under one
+ * configuration could be written from another: the check and the document it authorized were
+ * reading the same object at two different moments. One copy taken before the await gives both of
+ * them the same configuration.
+ *
+ * Null rather than the caller's object when the copy cannot be made. Handing back the reference
+ * would have been a copy in name only, and the caller would have gone on to describe it as the
+ * configuration it checked.
+ */
+export function detachedConfigSnapshot(config: OcxConfig): OcxConfig | null {
+  const detached = detachConfig(config);
+  return detached === null ? null : withExecutors(detached);
+}
+
+/**
+ * The configuration file as an opaque term: its exact bytes, or the distinguished absence of one.
+ *
+ * This is a byte observation and nothing more. It says the operator's configuration file has not
+ * been rewritten since a roster was built; it is not a claim about whether the configuration the
+ * process is holding agrees with that file.
+ *
+ * Null for a file that cannot be read, because then a later read cannot tell whether it changed.
+ * Null too for one that is there and does not load cleanly, which is the existing contract for a
+ * derived roster rather than an inference about the resident configuration. Before this, a digest
+ * was accepted ahead of any look at what the parse produced.
+ *
+ * Absence is a configuration rather than the lack of one. No file means defaults, which is an
+ * ordinary fresh install and the ordinary state in CI.
+ */
+function admittedFileTerm(): string | null {
+  const snapshot = readConfigAdmissionSnapshot();
+  const { source, error } = snapshot.diagnostics;
+  if (snapshot.kind === "read") return source === "file" && error === null ? snapshot.contentSha256 : null;
+  return source === "default" && error === null ? "absent" : null;
+}
+
+interface DetachedConfig {
+  readonly data: Record<string, unknown>;
+  readonly executors: ReadonlyMap<string, unknown>;
+}
+
+/**
+ * A configuration as plain data, with the transport executors kept out of it.
+ *
+ * The copier refuses everything JSON could not have produced, so the one thing that needs handling
+ * here is a provider's fetch executor: a caller owns it and the gather uses it instead of the
+ * global transport. It is held by reference for the detached copy and compared by reference
+ * afterwards, so replacing it invalidates the binding while it is never serialized.
+ */
+function detachConfig(live: OcxConfig): DetachedConfig | null {
+  const executors = new Map<string, unknown>();
+  const root = live as unknown;
+  if (!isPlainObject(root)) return null;
+  const data: Record<string, unknown> = {};
+  for (const key of ownDataKeys(root)) {
+    if (key === null) return null;
+    const value = root[key];
+    if (value === undefined) continue;
+    if (key !== "providers") {
+      const copied = copyPlainData(value);
+      if (!copied.ok) return null;
+      data[key] = copied.value;
+      continue;
+    }
+    if (!isPlainObject(value)) return null;
+    const providers: Record<string, unknown> = {};
+    for (const name of ownDataKeys(value)) {
+      if (name === null) return null;
+      const provider = value[name];
+      if (provider === undefined) continue;
+      if (!isPlainObject(provider)) return null;
+      const copiedProvider: Record<string, unknown> = {};
+      for (const field of ownDataKeys(provider)) {
+        if (field === null) return null;
+        const fieldValue = provider[field];
+        if (fieldValue === undefined) continue;
+        // The executor exception applies to an executor. A provider entry keeps unknown
+        // configuration keys, so a fetch value that is not a function is something an operator
+        // wrote into the file, and it is copied and compared as the data it is. Discovery reads it
+        // the same way: the outbound transport takes its built-in path unless the value is
+        // callable.
+        if (field === "fetch" && typeof fieldValue === "function") {
+          executors.set(name, fieldValue);
+          continue;
+        }
+        const copied = copyPlainData(fieldValue);
+        if (!copied.ok) return null;
+        copiedProvider[field] = copied.value;
+      }
+      providers[name] = copiedProvider;
+    }
+    data[key] = providers;
+  }
+  return { data, executors };
+}
+
+/** The copy a consumer runs against, with the executors put back by reference. */
+function withExecutors(detached: DetachedConfig): OcxConfig | null {
+  // A second copy, so what is compared later is never the object handed to a consumer.
+  const copied = copyPlainData(detached.data);
+  if (!copied.ok) return null;
+  const config = copied.value;
+  const providers = config.providers;
+  if (isPlainObject(providers)) {
+    for (const [name, executor] of detached.executors) {
+      const provider = providers[name];
+      if (isPlainObject(provider)) provider.fetch = executor;
+    }
+  }
+  return config as unknown as OcxConfig;
+}
+
+function sameExecutors(left: ReadonlyMap<string, unknown>, right: ReadonlyMap<string, unknown>): boolean {
+  if (left.size !== right.size) return false;
+  for (const [name, executor] of left) {
+    if (!right.has(name) || right.get(name) !== executor) return false;
+  }
+  return true;
+}

package/src/config/diagnostics.ts

@@ -60,6 +60,7 @@ import {
   remoteGuiConfigSchema,
   runtimeRoleSchema,
   spendSchema,
+  compactionRoutingSchema,
 } from "./schema/leaf-validators";
 
 export type ConfigDiagnostics = {
@@ -561,7 +562,26 @@ function managementIngressConfigError(value: unknown): string | null {
   return null;
 }
 
+/** Load degrades malformed metrics export config to off; live writes reject the same shape. */
+export function metricsExportConfigError(value: unknown): string | null {
+  const raw = rawConfigRecord(value);
+  if (!raw || !Object.hasOwn(raw, "metricsExport") || raw.metricsExport === undefined) return null;
+  const metricsExport = rawConfigRecord(raw.metricsExport);
+  if (!metricsExport) return "schema_invalid: metricsExport: must be an object or omitted";
+  if (Object.keys(metricsExport).some(key => key !== "enabled")) {
+    return "schema_invalid: metricsExport: contains an unsupported field";
+  }
+  if (metricsExport.enabled !== undefined && typeof metricsExport.enabled !== "boolean") {
+    return "schema_invalid: metricsExport.enabled: must be a boolean";
+  }
+  return null;
+}
+
 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 boundaryError = configReasoningPinsConfigError(value)
     ?? blankHostnameError(value)
     ?? claudeSubagentEffortError(value)
@@ -586,7 +606,8 @@ export function validateConfigCandidate(value: unknown): { ok: true; config: Ocx
     ?? clientConnectionConfigError(value)
     ?? clientRolePairError(value)
     ?? loopbackListenerPortError(value)
-    ?? managementIngressConfigError(value);
+    ?? managementIngressConfigError(value)
+    ?? metricsExportConfigError(value);
   if (boundaryError) return { ok: false, error: boundaryError };
   const result = configSchema.safeParse(value);
   if (result.success) {

package/src/config/feature-flags.ts

@@ -12,6 +12,11 @@ export function ultraFastTierEnabled(config: Pick<OcxConfig, "ultraFastTier">):
   return config.ultraFastTier === true;
 }
 
+/** Default-off aggregate request metrics; activation is fixed for one server process lifetime. */
+export function metricsExportEnabled(config: Pick<OcxConfig, "metricsExport">): boolean {
+  return config.metricsExport?.enabled === true;
+}
+
 /**
  * Default cadence for the opt-in catalog auto-refresh (issue #3630): one converge pass
  * per hour. Each pass spends a live /models call against every enabled provider, and