@bitkyc08/opencodex 2.59.0 → 2.61.0-preview.20260922

package/src/companion/settings.ts

@@ -0,0 +1,132 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { getConfigDir } from "../config/paths";
+import {
+  TIMELINE_HOURS,
+  isTimelineModelId,
+  type TimelineAggregation,
+  type TimelineGrouping,
+  type TimelineMetric,
+} from "../usage/timeline";
+
+export interface CompanionSettings {
+  menuBarMetric: "requests" | "tokens" | "cost" | "quota" | "none";
+  menuBarTemplate: string | null;
+  showToday: boolean;
+  showChart: boolean;
+  showModels: boolean;
+  showCost: boolean;
+  showAccounts: boolean;
+  chartHours: typeof TIMELINE_HOURS[number];
+  bucketMinutes: number;
+  chartStyle: "line" | "stackedBar";
+  tokenMetric: TimelineMetric;
+  aggregation: TimelineAggregation;
+  chartGrouping: TimelineGrouping;
+  models: string[] | null;
+  hiddenProviders: string[];
+}
+
+export const DEFAULT_COMPANION_SETTINGS: CompanionSettings = {
+  menuBarMetric: "tokens",
+  menuBarTemplate: null,
+  showToday: true,
+  showChart: true,
+  showModels: true,
+  showCost: true,
+  showAccounts: true,
+  chartHours: 24,
+  bucketMinutes: 60,
+  chartStyle: "line",
+  tokenMetric: "total",
+  aggregation: "sum",
+  chartGrouping: "model",
+  models: null,
+  hiddenProviders: [],
+};
+
+const TEMPLATE_FIELDS = new Set(["requests", "totalTokens", "inputTokens", "outputTokens", "costUsd", "quotaPercent"]);
+const MENU_BAR_METRICS = new Set(["requests", "tokens", "cost", "quota", "none"]);
+const CHART_STYLES = new Set(["line", "stackedBar"]);
+const TIMELINE_METRICS = new Set(["total", "input", "output", "cached"]);
+const AGGREGATIONS = new Set(["sum", "average", "max"]);
+const GROUPINGS = new Set(["model", "modelAccount"]);
+const SETTINGS_KEYS = Object.keys(DEFAULT_COMPANION_SETTINGS) as (keyof CompanionSettings)[];
+
+export function companionSettingsPath(): string {
+  return join(getConfigDir(), "companion.json");
+}
+
+function invalid(message: string): { error: string } {
+  return { error: message };
+}
+
+function validModels(value: unknown, key: string): value is string[] | null {
+  return value === null
+    || (Array.isArray(value)
+      && value.length <= 100
+      && value.every(isTimelineModelId));
+}
+
+function validateValue(key: keyof CompanionSettings, value: unknown): string | null {
+  if (key === "menuBarMetric") return typeof value === "string" && MENU_BAR_METRICS.has(value) ? null : "menuBarMetric is invalid";
+  if (key === "menuBarTemplate") {
+    if (value === null) return null;
+    if (typeof value !== "string" || value.length > 200) return "menuBarTemplate must be null or at most 200 characters";
+    for (const match of value.matchAll(/\{([^{}]+)\}/g)) {
+      if (!TEMPLATE_FIELDS.has(match[1]!)) return `menuBarTemplate contains unknown placeholder: ${match[1]}`;
+    }
+    return null;
+  }
+  if (["showToday", "showChart", "showModels", "showCost", "showAccounts"].includes(key)) {
+    return typeof value === "boolean" ? null : `${key} must be a boolean`;
+  }
+  if (key === "chartHours") return TIMELINE_HOURS.includes(value as typeof TIMELINE_HOURS[number]) ? null : "chartHours is invalid";
+  if (key === "bucketMinutes") return typeof value === "number" && Number.isInteger(value) && value >= 1 && value <= 1440 ? null : "bucketMinutes must be an integer from 1 through 1440";
+  if (key === "chartStyle") return typeof value === "string" && CHART_STYLES.has(value) ? null : "chartStyle is invalid";
+  if (key === "tokenMetric") return typeof value === "string" && TIMELINE_METRICS.has(value) ? null : "tokenMetric is invalid";
+  if (key === "aggregation") return typeof value === "string" && AGGREGATIONS.has(value) ? null : "aggregation is invalid";
+  if (key === "chartGrouping") return typeof value === "string" && GROUPINGS.has(value) ? null : "chartGrouping is invalid";
+  if (key === "models") return validModels(value, key) ? null : "models must be null or at most 100 provider/model identifiers";
+  if (key === "hiddenProviders") return Array.isArray(value) && value.length <= 100 && value.every(item => typeof item === "string" && item.length > 0 && !/\s/.test(item))
+    ? null : "hiddenProviders must contain at most 100 provider names";
+  return `${key} is unsupported`;
+}
+
+export function applyCompanionSettingsPatch(
+  current: CompanionSettings,
+  patch: unknown,
+): CompanionSettings | { error: string } {
+  if (!patch || typeof patch !== "object" || Array.isArray(patch)) return invalid("settings must be an object");
+  const values = patch as Record<string, unknown>;
+  for (const key of Object.keys(values)) {
+    if (!SETTINGS_KEYS.includes(key as keyof CompanionSettings)) return invalid(`unknown settings key: ${key}`);
+    const error = validateValue(key as keyof CompanionSettings, values[key]);
+    if (error) return invalid(error);
+  }
+  return { ...current, ...values } as CompanionSettings;
+}
+
+export function loadCompanionSettings(): { settings: CompanionSettings; updatedAt: number | null; corrupt?: true } {
+  const path = companionSettingsPath();
+  if (!existsSync(path)) return { settings: { ...DEFAULT_COMPANION_SETTINGS }, updatedAt: null };
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8")) as unknown;
+    const settings = applyCompanionSettingsPatch(DEFAULT_COMPANION_SETTINGS, parsed);
+    if ("error" in settings) return { settings: { ...DEFAULT_COMPANION_SETTINGS }, updatedAt: null, corrupt: true };
+    return { settings, updatedAt: statSync(path).mtimeMs };
+  } catch {
+    return { settings: { ...DEFAULT_COMPANION_SETTINGS }, updatedAt: null, corrupt: true };
+  }
+}
+
+export function saveCompanionSettings(settings: CompanionSettings): void {
+  const path = companionSettingsPath();
+  const dir = getConfigDir();
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const temp = `${path}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(temp, `${JSON.stringify(settings, null, 2)}\n`, { mode: 0o600 });
+  chmodSync(temp, 0o600);
+  renameSync(temp, path);
+  chmodSync(path, 0o600);
+}

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/atomic-write.ts

@@ -2,6 +2,7 @@ import {
   chmodSync,
   closeSync,
   fchmodSync,
+  fsyncSync,
   fstatSync,
   lstatSync,
   openSync,
@@ -10,7 +11,7 @@ import {
   unlinkSync,
   writeFileSync,
 } from "node:fs";
-import { dirname } from "node:path";
+import { basename, dirname, join } from "node:path";
 import { recordOwnedConfigPath } from "../lib/config-ownership";
 import { assertNotRealHomeUnderTest } from "../lib/test-home-guard";
 import {
@@ -162,6 +163,27 @@ function carryHardenAcrossContentWrite(path: string): void {
   reattributeHardenedSecretPath(path);
 }
 
+/**
+ * Commit the directory entry a rename just wrote.
+ *
+ * Best effort by platform, not by importance: Windows has no directory descriptor to sync and
+ * some filesystems refuse the open, and failing a replacement that already happened would be
+ * worse than reporting it. The throw that matters is the temp's own `fsync`, which runs before
+ * the rename and stops it.
+ */
+function syncParentDirectory(target: string): void {
+  if (process.platform === "win32") return;
+  let descriptor: number | undefined;
+  try {
+    descriptor = openSync(dirname(target), "r");
+    fsyncSync(descriptor);
+  } catch {
+    /* the rename already landed; a directory that cannot be synced is not a reason to undo it */
+  } finally {
+    if (descriptor !== undefined) { try { closeSync(descriptor); } catch { /* already closed */ } }
+  }
+}
+
 function writePrivateTempFile(
   path: string,
   content: string,
@@ -191,6 +213,40 @@ function writePrivateTempFile(
   carryHardenAcrossContentWrite(path);
 }
 
+/**
+ * The same private temp, filled by a writer that streams into the descriptor.
+ *
+ * For content that must not be held in memory as one string. The identity assertions, the
+ * ownership handshake and the hardening are the same; the difference is that the bytes arrive in
+ * bounded chunks and the descriptor is flushed before it closes.
+ *
+ * The `fsync` is not optional here and its failure is not swallowed. A replacement whose
+ * REPLACEMENT is not on disk can lose the rows it was supposed to retain, so the throw is what
+ * stops the rename from happening at all.
+ */
+function writePrivateTempFileWith(
+  path: string,
+  write: (descriptor: number) => void,
+  timeoutMemoKey: string,
+  onCreated: () => void,
+): void {
+  const descriptor = openSync(path, "wx", 0o600);
+  onCreated();
+  try {
+    if (windowsHardeningApplies()) {
+      hardenSecretPath(path, { required: true, timeoutMemoKey });
+    }
+    if (process.platform !== "win32") fchmodSync(descriptor, 0o600);
+    assertPrivateTempDescriptor(path, descriptor);
+    write(descriptor);
+    assertPrivateTempDescriptor(path, descriptor);
+    fsyncSync(descriptor);
+  } finally {
+    closeSync(descriptor);
+  }
+  carryHardenAcrossContentWrite(path);
+}
+
 async function writePrivateTempFileAsync(
   path: string,
   content: string,
@@ -215,14 +271,14 @@ async function writePrivateTempFileAsync(
   carryHardenAcrossContentWrite(path);
 }
 
-export function atomicWriteFile(
+function atomicWriteFileToTarget(
   path: string,
-  content: string,
+  content: string | ((descriptor: number) => void),
+  target: string,
   io?: AtomicWriteIO,
   hooks: AtomicWriteHooks = {},
 ): void {
   recordOwnedConfigPath(getConfigDir(), path);
-  const target = resolveWriteTarget(path);
   assertResolvedTargetAllowed(path, target);
   const tmp = `${target}.ocx.${process.pid}.${nextAtomicTempSequence()}.tmp`;
   let hardened = false;
@@ -246,13 +302,26 @@ export function atomicWriteFile(
   };
   try {
     if (io) ownsTemp = true;
-    effective.write(tmp, content);
+    // A streaming writer bypasses the string form of `write` and nothing else. Every later
+    // step -- harden, the pre-rename hooks, the rename and the whole residual-cleanup path,
+    // which still scrubs through `effective.write(tmp, "")` -- is shared with the string form.
+    if (typeof content === "function") writePrivateTempFileWith(tmp, content, path, () => { ownsTemp = true; });
+    else effective.write(tmp, content);
     hooks.afterTempWrite?.(tmp, target);
     effective.harden(tmp);
     hardened = true;
     hooks.beforeRename?.(tmp, target);
     hooks.validateBeforeRename?.(target);
     effective.rename(tmp, target);
+    // The rename is only as durable as the directory entry recording it. Fsyncing the temp's
+    // CONTENT and then losing the entry in a power cut leaves the old file in place, or the
+    // directory in an indeterminate state, while the caller was told the replacement landed.
+    //
+    // Only the streaming form does this. It is the one that makes a durability claim -- a
+    // replacement is not an append, and losing it can lose the rows it was meant to keep -- and
+    // adding a directory sync to the string form would charge every config write for a promise
+    // its callers have never been given.
+    if (typeof content === "function") syncParentDirectory(target);
     forgetEphemeralSecretPath(tmp);
   } catch (cause) {
     if (!ownsTemp) throw cause;
@@ -287,6 +356,49 @@ export function atomicWriteFile(
   }
 }
 
+export function atomicWriteFile(
+  path: string,
+  content: string,
+  io?: AtomicWriteIO,
+  hooks: AtomicWriteHooks = {},
+): void {
+  atomicWriteFileToTarget(path, content, resolveWriteTarget(path), io, hooks);
+}
+
+/**
+ * Atomically replace a file with bytes produced straight into the temporary descriptor.
+ *
+ * Same publication contract as {@link atomicWriteFile}: an exclusively created private temp, the
+ * identity assertions around the write, `hooks.validateBeforeRename` immediately before the
+ * rename, the platform-aware replace, and the residual cleanup on any failure. A custom
+ * {@link AtomicWriteIO} is not accepted, because the point of this form is that the default
+ * writer owns the descriptor.
+ */
+export function atomicWriteFileStreamed(
+  path: string,
+  write: (descriptor: number) => void,
+  hooks: AtomicWriteHooks = {},
+): void {
+  atomicWriteFileToTarget(path, write, resolveWriteTarget(path), undefined, hooks);
+}
+
+/**
+ * Atomically replace the named directory entry without resolving a symlink at
+ * that entry. This is for files in directories writable by another process:
+ * a raced symlink is replaced, never followed to a more privileged target.
+ */
+export function atomicWriteFileNoFollow(
+  path: string,
+  content: string,
+  io?: AtomicWriteIO,
+  hooks: AtomicWriteHooks = {},
+): void {
+  // Only the final entry is no-follow: the parent still resolves, because an
+  // OS alias above the configured root (a home junction, /tmp) is legitimate
+  // and Windows cannot exclusive-create a temp through a junction.
+  atomicWriteFileToTarget(path, content, join(resolveWriteTarget(dirname(path)), basename(path)), io, hooks);
+}
+
 export interface AtomicWriteAsyncIO {
   write: (path: string, content: string) => void | Promise<void>;
   harden: (path: string) => void | Promise<void>;

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

package/src/config/load-degrade.ts

@@ -32,6 +32,7 @@ import {
   quotaResetNotifySchema,
   remoteGuiConfigSchema,
   retryOn429PolicySchema,
+  retryOnResetPolicySchema,
   runtimeRoleSchema,
   spendSchema,
 } from "./schema/leaf-validators";
@@ -101,6 +102,24 @@ export function warnDegradedStreamMode(rawParsed: unknown, validated: OcxConfig)
   }
 }
 
+export function warnDegradedCompactionRouting(rawParsed: unknown, validated: OcxConfig): void {
+  if (!rawParsed || typeof rawParsed !== "object") return;
+  const raw = (rawParsed as Record<string, unknown>).compactionRouting;
+  if (raw !== undefined && validated.compactionRouting === undefined) {
+    console.warn("⚠️  config.json compactionRouting is invalid (expected { model, reasoningEffort?, triggers? } with a nonblank model, a declared effort, and triggers drawn without repetition from \"manual\" and \"auto\") — compaction keeps the conversation model");
+  }
+}
+
+/**
+ * Top-level opt-in blocks whose hand-edited form degrades to "off" instead of failing the whole
+ * schema. Grouped behind one entry point because `src/config.ts` sits at its file-size cap, and
+ * the ratchet only ever moves down: a per-block call there costs a line the file does not have.
+ */
+export function warnDegradedTopLevelOptIns(rawParsed: unknown, validated: OcxConfig): void {
+  warnDegradedStreamMode(rawParsed, validated);
+  warnDegradedCompactionRouting(rawParsed, validated);
+}
+
 /**
  * Load-time degradation for `retryOn429` (loadConfig only): one hand-edited invalid optional
  * field (e.g. `attempts: 0` or a string) must not trip the whole provider schema and hide every
@@ -177,18 +196,44 @@ export function sanitizeRetryOn429ForLoad(parsed: unknown): void {
  * redacted (a malformed write can place a secret in a property name).
  */
 export function retryOn429PolicyConfigError(policy: unknown): string | null {
+  return strictPolicyConfigError("retryOn429", retryOn429PolicySchema, policy);
+}
+
+/**
+ * Management write-boundary validation for `retryOnReset`, with the same fail-closed contract
+ * as `retryOn429PolicyConfigError`: the load-time schema degrades a malformed block to
+ * "absent", so this is the one place a bad value is refused instead of silently dropped.
+ */
+export function retryOnResetPolicyConfigError(policy: unknown): string | null {
+  return strictPolicyConfigError("retryOnReset", retryOnResetPolicySchema, policy);
+}
+
+/**
+ * The shared body of both. Written once because the two differ only in the field name they
+ * report, and a second hand-copied formatter is a second place for the redaction to be
+ * forgotten.
+ */
+function strictPolicyConfigError(
+  field: string,
+  schema: {
+    safeParse: (value: unknown) => { success: true } | {
+      success: false;
+      error: { issues: Array<{ code: string; message: string; path: PropertyKey[]; keys?: string[] }> };
+    };
+  },
+  policy: unknown,
+): string | null {
   if (policy === undefined) return null;
-  const result = retryOn429PolicySchema.safeParse(policy);
+  const result = schema.safeParse(policy);
   if (result.success) return null;
   const first = result.error.issues[0];
-  if (!first) return "retryOn429 is invalid";
-  if (first.code === "unrecognized_keys") {
+  if (!first) return `${field} is invalid`;
+  if (first.code === "unrecognized_keys" && first.keys) {
     const names = first.keys.map(key => JSON.stringify(redactSecretString(key))).join(", ");
-    return `retryOn429 has unrecognized field${first.keys.length > 1 ? "s" : ""}: ${names}`;
+    return `${field} has unrecognized field${first.keys.length > 1 ? "s" : ""}: ${names}`;
   }
-  if (first.path.length === 0) return `retryOn429 is invalid (${first.message})`;
-  const field = String(first.path[first.path.length - 1]);
-  return `retryOn429.${field} is invalid (${first.message})`;
+  if (first.path.length === 0) return `${field} is invalid (${first.message})`;
+  return `${field}.${String(first.path[first.path.length - 1])} is invalid (${first.message})`;
 }
 
 export function sanitizeCapabilityDeclarationsForLoad(parsed: unknown): void {