@bitkyc08/opencodex 2.83.0 → 2.84.0

package/src/lib/app-owned-memory-stores.ts

@@ -169,12 +169,16 @@ export const APP_OWNED_RETAINED_STORE_REGISTRATIONS = [
     category: "caches",
     snapshot: usageSummaryRetainedStoreSnapshot,
     evictOldest: evictOldestUsageSummaryForBudget,
+    // Deletes one in-memory summary entry.
+    passiveEvictable: true,
   },
   {
     id: "usage_snapshot",
     category: "caches",
     snapshot: usageSnapshotRetainedStoreSnapshot,
     evictOldest: evictOldestUsageSnapshot,
+    // Drops the retained ledger snapshot or one unpinned aggregate, both in memory.
+    passiveEvictable: true,
   },
   {
     id: "cursor_blobs",

package/src/lib/app-owned-memory.ts

@@ -1,3 +1,5 @@
+import { isPassiveRead } from "./passive-read";
+
 export type AppOwnedRetainedCategory = "logs" | "caches" | "blobs" | "continuation";
 export type AppOwnedObservedCategory = "translator" | "serialized_tails";
 
@@ -14,6 +16,11 @@ export interface RetainedStoreRegistration {
   category: AppOwnedRetainedCategory;
   snapshot(): RetainedStoreSnapshot;
   evictOldest(): number;
+  /**
+   * Eviction only releases memory: no spill, snapshot or other write. Only such stores are
+   * demoted inside a passive read (#6959); the rest wait for this process's own next enforcement.
+   */
+  passiveEvictable?: true;
 }
 
 export interface ObservedBufferRegistration {
@@ -168,11 +175,15 @@ function nextCandidate(
   snapshots: ReadonlyMap<string, RetainedStoreSnapshot>,
   ineligible: Set<string>,
 ): RetainedStoreRegistration | undefined {
+  // A passive read (a Remote Link Child's, #6959) demotes only stores whose eviction is memory-only:
+  // a continuation spills to disk and a replay cache rewrites its snapshot.
+  const passive = isPassiveRead();
   for (const category of CATEGORY_ORDER) {
     let candidate: RetainedStoreRegistration | undefined;
     let candidateAt = Number.POSITIVE_INFINITY;
     for (const registration of retainedStores.values()) {
       if (registration.category !== category || ineligible.has(registration.id)) continue;
+      if (passive && registration.passiveEvictable !== true) continue;
       const snapshot = snapshots.get(registration.id);
       if (!snapshot || snapshot.evictableBytes <= 0) continue;
       const oldestAt = snapshot.oldestAt;

package/src/lib/json-byte-size.ts

@@ -1,5 +1,36 @@
 import { TRANSLATOR_MAX_TURN_BYTES, TranslatorBudgetExceededError } from "./translator-budget";
 
+/** Count one JSON string formed from parts without joining, serializing or encoding it. */
+export function jsonStringPartsUtf8Bytes(parts: readonly string[], limit = TRANSLATOR_MAX_TURN_BYTES): number {
+  let bytes = 0;
+  let highSurrogate = false;
+  const add = (count: number) => {
+    if (count > limit - bytes) throw new TranslatorBudgetExceededError("request_copies", limit);
+    bytes += count;
+  };
+  add(2); // The joined string has one pair of JSON quotes.
+  for (const text of parts) {
+    if (text.length > limit - bytes) throw new TranslatorBudgetExceededError("request_copies", limit);
+    for (let i = 0; i < text.length; i++) {
+      const code = text.charCodeAt(i);
+      if (highSurrogate) {
+        highSurrogate = false;
+        if (code >= 0xdc00 && code <= 0xdfff) { add(4); continue; }
+        add(6);
+      }
+      if (code >= 0xd800 && code <= 0xdbff) highSurrogate = true;
+      else if (code === 0x22 || code === 0x5c || code === 8 || code === 9 || code === 10 || code === 12 || code === 13) add(2);
+      else if (code < 0x20) add(6);
+      else if (code < 0x80) add(1);
+      else if (code < 0x800) add(2);
+      else if (code >= 0xdc00 && code <= 0xdfff) add(6);
+      else add(3);
+    }
+  }
+  if (highSurrogate) add(6);
+  return bytes;
+}
+
 /** Measure plain JSON data without allocating its serialized string or UTF-8 copy. */
 export function jsonUtf8Bytes(value: unknown, limit = TRANSLATOR_MAX_TURN_BYTES): number {
   let bytes = 0;

package/src/lib/optional-shutdown-hooks.ts

@@ -70,5 +70,40 @@ export function runOptionalShutdownHooks(): void {
 /** Test-only reset so an isolated lifecycle test does not inherit registrations. */
 export function resetOptionalShutdownHooksForTests(): void {
   hooks.clear();
+  drainStartHooks.clear();
+  drainStartHooksRan = false;
   hooksRan = false;
 }
+
+const drainStartHooks = new Map<string, ShutdownHook>();
+let drainStartHooksRan = false;
+
+/**
+ * Register work that must run the moment a drain begins, before in-flight turns are awaited.
+ * The service health sentinel (#6671) uses it: a deliberate stop whose drain stalls must stay a
+ * stop, so the sentinel is withdrawn before the drain can look unresponsive. Same contract as
+ * {@link registerOptionalShutdownHook}: keyed, synchronous, best-effort, detachable.
+ */
+export function registerDrainStartHook(key: string, hook: ShutdownHook): () => void {
+  drainStartHooks.set(key, hook);
+  return () => {
+    if (drainStartHooks.get(key) === hook) drainStartHooks.delete(key);
+  };
+}
+
+/** Run every drain-start hook. Never throws. */
+export function runDrainStartHooks(): void {
+  drainStartHooksRan = true;
+  for (const [key, hook] of [...drainStartHooks]) {
+    try {
+      hook();
+    } catch (err) {
+      console.warn(`[shutdown] drain-start hook "${key}" failed:`, err instanceof Error ? err.message : err);
+    }
+  }
+}
+
+/** Whether a drain has begun in this process; work that must not start mid-drain checks this. */
+export function didRunDrainStartHooks(): boolean {
+  return drainStartHooksRan;
+}

package/src/lib/outbound-credential-registry.ts

@@ -0,0 +1,210 @@
+/**
+ * Process-local record of credential values this process has handed to an upstream.
+ *
+ * Upstream diagnostics (error codes, request ids) are provider-controlled. A gateway can echo a
+ * credential it received back into those fields, and a credential with no recognizable format slips
+ * past pattern redaction. Configured credentials are read directly at capture time (see
+ * server/configured-credentials); this registry adds the values that only exist at send time, such
+ * as a client-forwarded bearer or a plugin-added header.
+ *
+ * Two tiers keep ordinary traffic from disabling diagnostics. Values of credential-named headers are
+ * strict: they match at any length, and once one is evicted coverage is incomplete for the rest of
+ * the process, so callers fail closed. Every other header value is best effort: it matches only at
+ * eight characters or more and its eviction never disables diagnostics, so per-turn metadata cannot
+ * exhaust anything that matters. Correlation ids (request ids, trace context) are left out of the
+ * best-effort tier because a gateway legitimately echoes them as its request id; a configured header
+ * of that name is still covered by the configured set. Values are held in memory only: nothing here
+ * is serialized, persisted or exposed.
+ */
+import { SENSITIVE_KEY_PATTERN } from "./redact";
+
+/** Containment only for credentials long enough that a diagnostic cannot contain one by chance. */
+export const CREDENTIAL_SUBSTRING_MIN_LENGTH = 8;
+const CREDENTIAL_HEADER_NAME = /api[-_]?key|secret|passw|credential|auth|(?:^|[-_])token$/i;
+const CORRELATION_HEADER_NAME = /^(?:x-(?:client-)?request-id|request-id|traceparent|tracestate)$/i;
+const AUTH_SCHEMES = new Set(["bearer", "basic", "token", "digest", "apikey", "api-key", "key", "sso-key", "negotiate", "dpop"]);
+const TOKEN_CHAR = /[!#$%&'*+.^_`|~0-9A-Za-z-]/;
+const BASIC_BASE64 = /^[A-Za-z0-9+/]+={0,2}$/;
+const PRINTABLE_USER_PASS = /^[\x20-\x7e]*:[\x20-\x7e]*$/;
+
+/** True for a header (or config field) name whose value is a credential by its name. */
+export function isCredentialName(name: string): boolean {
+  return SENSITIVE_KEY_PATTERN.test(name) || CREDENTIAL_HEADER_NAME.test(name);
+}
+
+/**
+ * Values of RFC 9110 auth-params (token BWS "=" BWS ( token / quoted-string )), cookie pairs and
+ * other name=value pairs, in one linear pass: every character is visited a bounded number of times,
+ * so a long header value cannot stall the event loop.
+ */
+function parameterValues(value: string): string[] {
+  const out: string[] = [];
+  const n = value.length;
+  let unclosedFrom = n; // no closing quote exists for any opening quote at or after this index
+  let i = 0;
+  while (i < n) {
+    if (!TOKEN_CHAR.test(value[i]!)) { i++; continue; }
+    while (i < n && TOKEN_CHAR.test(value[i]!)) i++;
+    let j = i;
+    while (j < n && (value[j] === " " || value[j] === "\t")) j++;
+    if (value[j] !== "=") { i = j; continue; }
+    j++;
+    while (j < n && (value[j] === " " || value[j] === "\t")) j++;
+    if (value[j] === "\"") {
+      let k = j + 1;
+      let text = "";
+      let closed = false;
+      if (j < unclosedFrom) {
+        while (k < n) {
+          const char = value[k]!;
+          if (char === "\\" && k + 1 < n) { text += value[k + 1]; k += 2; continue; }
+          if (char === "\"") { closed = true; break; }
+          text += char;
+          k++;
+        }
+      }
+      if (closed) {
+        if (text) out.push(text);
+        i = k + 1;
+      } else {
+        unclosedFrom = Math.min(unclosedFrom, j);
+        i = j + 1;
+      }
+      continue;
+    }
+    const start = j;
+    while (j < n && !/[\s,;"]/.test(value[j]!)) j++;
+    const raw = value.slice(start, j);
+    if (raw && !/^=+$/.test(raw)) out.push(raw);
+    i = j;
+  }
+  return out;
+}
+
+/**
+ * The whole value plus every part a server could authenticate with on its own: tokens split on
+ * whitespace, commas and semicolons with auth scheme words dropped, the value of each name=value
+ * parameter (cookies, digest; whitespace around "=" and quoted strings with escapes are parsed
+ * first, before any splitting), and both halves of a standard Basic credential.
+ */
+export function credentialComponents(value: string): string[] {
+  const whole = value.trim();
+  if (!whole) return [];
+  const out = new Set([whole]);
+  for (const param of parameterValues(whole)) out.add(param);
+  let previous: string | undefined;
+  for (const part of whole.split(/[\s,;]+/)) {
+    if (!part) continue;
+    const lower = part.toLowerCase();
+    if (AUTH_SCHEMES.has(lower)) { previous = lower; continue; }
+    out.add(part);
+    if (previous === "basic" && BASIC_BASE64.test(part)) {
+      const decoded = Buffer.from(part, "base64").toString("utf8");
+      if (PRINTABLE_USER_PASS.test(decoded) && Buffer.from(decoded, "utf8").toString("base64").replace(/=+$/, "") === part.replace(/=+$/, "")) {
+        const colon = decoded.indexOf(":");
+        out.add(decoded.slice(0, colon));
+        out.add(decoded.slice(colon + 1));
+      }
+    }
+    previous = undefined;
+  }
+  out.delete("");
+  return [...out];
+}
+
+/** Exact equality at any length at or above minLength; containment for values of 8+ characters. */
+export function credentialSetMatches(values: Iterable<string>, has: (value: string) => boolean, value: string, minLength = 1): boolean {
+  if (value.length >= minLength && has(value)) return true;
+  for (const secret of values) {
+    if (secret.length >= Math.max(minLength, CREDENTIAL_SUBSTRING_MIN_LENGTH) && value.includes(secret)) return true;
+  }
+  return false;
+}
+
+export interface OutboundCredentialRegistryOptions {
+  maxEntries?: number;
+  maxBytes?: number;
+  maxValueBytes?: number;
+}
+
+/** Bounded LRU of values; eviction marks it incomplete. */
+class BoundedValueSet {
+  readonly values = new Map<string, number>();
+  private totalBytes = 0;
+  complete = true;
+  constructor(private readonly maxEntries: number, private readonly maxBytes: number, private readonly maxValueBytes: number) {}
+
+  add(value: string): void {
+    if (!value) return;
+    const bytes = Buffer.byteLength(value, "utf8");
+    if (bytes > this.maxValueBytes) {
+      this.complete = false;
+      return;
+    }
+    if (this.values.has(value)) {
+      this.values.delete(value);
+      this.values.set(value, bytes);
+      return;
+    }
+    this.values.set(value, bytes);
+    this.totalBytes += bytes;
+    while (this.values.size > this.maxEntries || this.totalBytes > this.maxBytes) {
+      const oldest = this.values.keys().next().value as string;
+      this.totalBytes -= this.values.get(oldest)!;
+      this.values.delete(oldest);
+      this.complete = false;
+    }
+  }
+
+  matches(value: string, minLength: number): boolean {
+    return credentialSetMatches(this.values.keys(), candidate => this.values.has(candidate), value, minLength);
+  }
+}
+
+export class OutboundCredentialRegistry {
+  private readonly strict: BoundedValueSet;
+  private readonly observed: BoundedValueSet;
+
+  constructor(options: OutboundCredentialRegistryOptions = {}) {
+    const entries = options.maxEntries ?? 4096;
+    const bytes = options.maxBytes ?? 1 << 20;
+    const valueBytes = options.maxValueBytes ?? 16_384;
+    this.strict = new BoundedValueSet(entries, bytes, valueBytes);
+    this.observed = new BoundedValueSet(entries, bytes, valueBytes);
+  }
+
+  /** Record the components of every value in headers that are about to be sent. */
+  remember(headers: HeadersInit | Headers | undefined): void {
+    if (!headers) return;
+    new Headers(headers).forEach((value, name) => {
+      const strict = isCredentialName(name);
+      if (!strict && CORRELATION_HEADER_NAME.test(name)) return;
+      const tier = strict ? this.strict : this.observed;
+      for (const part of credentialComponents(value)) tier.add(part);
+    });
+  }
+
+  /** True when value repeats a recorded credential (strict at any length, best effort at 8+). */
+  matches(value: string): boolean {
+    return this.strict.matches(value, 1) || this.observed.matches(value, CREDENTIAL_SUBSTRING_MIN_LENGTH);
+  }
+
+  /** False once a credential-named value was dropped; callers must then fail closed. */
+  complete(): boolean {
+    return this.strict.complete;
+  }
+}
+
+let active = new OutboundCredentialRegistry();
+
+/** The registry fed by the HTTP executor boundary and the Codex WebSocket dial. */
+export function outboundCredentials(): OutboundCredentialRegistry {
+  return active;
+}
+
+/** Swap the active registry for sequential in-file tests; returns the restore function. */
+export function setOutboundCredentialRegistryForTests(registry: OutboundCredentialRegistry): () => void {
+  const previous = active;
+  active = registry;
+  return () => { active = previous; };
+}

package/src/lib/passive-read.ts

@@ -0,0 +1,35 @@
+/**
+ * A passive management read: it shows what this process already knows and does not make it act on
+ * providers, accounts, processes or files (#6959).
+ *
+ * The Remote Link management relay runs every Child read inside this scope
+ * (`src/server/index/link-management.ts`), so a Child can show its Home's state without changing
+ * it or making it act. Inside the scope:
+ *
+ * - model discovery yields no routed models (`fetchAllModels`, the management model rows): it would
+ *   reach provider upstreams, refresh Codex entitlements and persist a pending provider's initial
+ *   model selection;
+ * - provider quota and the Codex account list are served from what the Home has observed, with no
+ *   probe, token refresh, native-main claim or publication into routing evidence;
+ * - the startup-health diagnostic, the Codex runtime version probes and the bundled-catalog refresh
+ *   are not started, so no process runs and no runtime record is written;
+ * - a native-main fence raised for unknown service ownership is reported, not re-inspected;
+ * - config-directory and credential-file hardening and malformed-file backups are skipped;
+ * - memory-budget enforcement demotes only stores registered as `passiveEvictable` (eviction that
+ *   only releases memory: the usage caches), never a continuation spill or a replay snapshot.
+ *
+ * The Home's own dashboard and traffic keep those caches current. A passive read may still join
+ * work the Home already started; that work keeps the Home's scope and its writes are the Home's.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+
+const passive = new AsyncLocalStorage<true>();
+
+/** Run a management read passively, including everything it awaits or schedules. */
+export function runPassiveRead<T>(run: () => Promise<T>): Promise<T> {
+  return passive.run(true, run);
+}
+
+export function isPassiveRead(): boolean {
+  return passive.getStore() === true;
+}

package/src/lib/shadow-call.ts

@@ -81,19 +81,58 @@ export function shadowCallTargetsIntersect(
     && target.modelId.startsWith(source.modelId);
 }
 
+/**
+ * Preserve explicit user turns and spawned children before either intercept site.
+ * HTTP provenance is `x-codex-turn-metadata` or `x-openai-subagent: collab_spawn`.
+ * `x-openai-subagent` is connection-level on both transports: a child session opens
+ * its own connection, so a `collab_spawn` upgrade header still names every frame.
+ * Turn metadata is per-frame on WebSocket (`CODEX_WS_FRAME_HEADERS`): only the frame's
+ * `client_metadata["x-codex-turn-metadata"]` describes this turn, because the
+ * upgrade's copy can describe an earlier user or helper turn.
+ * `request_kind: "turn"` alone is not user provenance (#1684). Maintenance
+ * markers such as `x-openai-subagent: compact`/`review` and metadata naming
+ * `memory_consolidation` remain eligible helpers, subject to memory routing.
+ * Missing/malformed metadata retains the legacy opt-in source-prefix behavior.
+ */
+export function shadowCallPreservesSelectedModel(
+  body: unknown,
+  headers: Headers,
+  transport?: "websocket",
+): boolean {
+  if (headers.get("x-openai-subagent") === "collab_spawn") return true;
+  let metadata: unknown = headers.get("x-codex-turn-metadata");
+  if (transport === "websocket") {
+    const client = body && typeof body === "object" && !Array.isArray(body)
+      ? (body as Record<string, unknown>).client_metadata : undefined;
+    metadata = client && typeof client === "object" && !Array.isArray(client)
+      && Object.hasOwn(client, "x-codex-turn-metadata")
+      ? (client as Record<string, unknown>)["x-codex-turn-metadata"] : undefined;
+  }
+  if (typeof metadata !== "string") return false;
+  try {
+    const parsed: unknown = JSON.parse(metadata);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return false;
+    const turn = parsed as Record<string, unknown>;
+    return turn.subagent_kind === "thread_spawn"
+      || (turn.request_kind === "turn" && turn.thread_source === "user");
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Decide whether a matching source model should use the opt-in intercept.
  *
  * Before Codex 0.147.0 this checked x-codex-turn-metadata and exempted
  * request_kind "turn". Codex 0.147.0 can label background helper calls as
- * "turn", causing them to bypass the intercept (#1684). The fix is to
- * intercept every configured shadow source model regardless of request kind.
+ * "turn", causing them to bypass the intercept (#1684). Request kind alone
+ * cannot exempt a configured source model: callers first preserve explicit
+ * user/child provenance with `shadowCallPreservesSelectedModel` (#6921).
  * A replacement intersecting the same provider+model source set remains a
  * no-op because rewriting it would only create self-interception (#2706).
  *
- * Callers skip this check entirely for spawned sub-agent turns
- * (`isThreadSpawnRequest`): `gpt-6-luna` is both the helper slug and a default
- * sub-agent model, and an explicitly spawned child must keep the model it chose.
+ * `gpt-6-luna` is both the helper slug and a selectable user/sub-agent model;
+ * explicit user turns and spawned children must keep the model they chose.
  */
 export function shouldInterceptShadowCall(
   modelId: string,

package/src/link/codex-settings.ts

@@ -0,0 +1,155 @@
+/**
+ * The Codex settings a Remote Link Home decides for its Children (#6957).
+ *
+ * A link Child relays every model request to its Home, so everything the Home's proxy applies
+ * per request already follows the Home: effort caps, the sub-agent roster and fallback, the
+ * injection prompt, sidecar and compaction routing, and the catalog itself (served by
+ * `/v1/catalog`). What does NOT follow is the part of the Home's OpenCodex config that the
+ * injector writes into the Child's own Codex `config.toml`. This module carries exactly that
+ * part, which is every OpenCodex config field the Codex injection plan reads that is a policy
+ * decision rather than a fact about the Child's own listener:
+ *
+ * - `fastMode` -> `[features] fast_mode`
+ * - `multiAgentMode` -> the native `features.multi_agent_v2` reconcile (v1 mode)
+ * - `webSearchSidecar.enabled` -> the root `web_search` switch
+ * - `syncCodexSubagentDefaults` + `injectionModel` + `injectionEffort` -> the managed
+ *   `[agents]` defaults
+ *
+ * Root `model_reasoning_effort` and the `desktop.*` picker keys are Codex app settings that
+ * OpenCodex never writes on any machine, so they are deliberately not part of this document.
+ * Listener facts (port, hostname, Desktop authless and client compaction routing forms, resume
+ * history) stay the Child's own because they describe how the Child's Codex reaches the Child.
+ *
+ * It rides on its own authenticated link read rather than inside the catalog because the
+ * catalog bytes are written verbatim to `model_catalog_json`, which Codex parses itself.
+ */
+import { hostname } from "node:os";
+import type { OcxConfig } from "../types";
+
+export const HOME_CODEX_SETTINGS_VERSION = 1;
+const MULTI_AGENT_MODES = ["v1", "default", "v2"] as const;
+type MultiAgentMode = (typeof MULTI_AGENT_MODES)[number];
+
+export interface HomeCodexSettings {
+  /** null: the Home leaves `fast_mode` alone. */
+  fastMode: boolean | null;
+  /** null: the Home has no explicit mode. */
+  multiAgentMode: MultiAgentMode | null;
+  webSearchSidecarEnabled: boolean;
+  subagentDefaults: { model: string; reasoningEffort: string | null } | null;
+}
+
+export interface HomeCodexSettingsDocument {
+  version: typeof HOME_CODEX_SETTINGS_VERSION;
+  home: { name: string; version: string };
+  settings: HomeCodexSettings;
+}
+
+const NAME_MAX = 255;
+const VALUE_MAX = 256;
+
+function safeLabel(value: string, max: number): string | null {
+  const trimmed = value.trim();
+  if (!trimmed || trimmed.length > max) return null;
+  for (const character of trimmed) {
+    const code = character.codePointAt(0) ?? 0;
+    if (code < 0x20 || code === 0x7f || (code >= 0x202a && code <= 0x202e) || (code >= 0x2066 && code <= 0x2069)) return null;
+  }
+  return trimmed;
+}
+
+export function projectHomeCodexSettings(config: OcxConfig, version: string): HomeCodexSettingsDocument {
+  const mode = config.multiAgentMode;
+  // Same predicate as `subagentDefaultSyncEffective` (src/config/diagnostics.ts), inlined so
+  // this module stays inside the src/link import boundary.
+  const sync = config.syncCodexSubagentDefaults === true && Boolean(config.injectionModel?.trim());
+  const effort = config.injectionEffort?.trim();
+  return {
+    version: HOME_CODEX_SETTINGS_VERSION,
+    home: { name: safeLabel(hostname(), NAME_MAX) ?? "Home", version },
+    settings: {
+      fastMode: typeof config.fastMode === "boolean" ? config.fastMode : null,
+      multiAgentMode: mode && (MULTI_AGENT_MODES as readonly string[]).includes(mode) ? mode : null,
+      webSearchSidecarEnabled: config.webSearchSidecar?.enabled !== false,
+      subagentDefaults: sync
+        ? { model: config.injectionModel!.trim(), reasoningEffort: effort ? effort : null }
+        : null,
+    },
+  };
+}
+
+function exactKeys(value: unknown, keys: readonly string[]): value is Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const actual = Object.keys(value);
+  return actual.length === keys.length && actual.every(key => keys.includes(key));
+}
+
+/** Strict parse: an unknown field, a wrong type or an unsafe label rejects the whole document. */
+export function parseHomeCodexSettingsDocument(value: unknown): HomeCodexSettingsDocument | null {
+  if (!exactKeys(value, ["version", "home", "settings"]) || value.version !== HOME_CODEX_SETTINGS_VERSION) return null;
+  const home = value.home;
+  if (!exactKeys(home, ["name", "version"]) || typeof home.name !== "string" || typeof home.version !== "string") return null;
+  const name = safeLabel(home.name, NAME_MAX);
+  const homeVersion = safeLabel(home.version, 64);
+  if (!name || !homeVersion) return null;
+  const s = value.settings;
+  if (!exactKeys(s, ["fastMode", "multiAgentMode", "webSearchSidecarEnabled", "subagentDefaults"])) return null;
+  if (s.fastMode !== null && typeof s.fastMode !== "boolean") return null;
+  if (s.multiAgentMode !== null && !(MULTI_AGENT_MODES as readonly unknown[]).includes(s.multiAgentMode)) return null;
+  if (typeof s.webSearchSidecarEnabled !== "boolean") return null;
+  let subagentDefaults: HomeCodexSettings["subagentDefaults"] = null;
+  if (s.subagentDefaults !== null) {
+    const d = s.subagentDefaults;
+    if (!exactKeys(d, ["model", "reasoningEffort"]) || typeof d.model !== "string") return null;
+    const model = safeLabel(d.model, VALUE_MAX);
+    if (!model) return null;
+    let reasoningEffort: string | null = null;
+    if (d.reasoningEffort !== null) {
+      if (typeof d.reasoningEffort !== "string" || !/^[a-z][a-z0-9_-]{0,31}$/.test(d.reasoningEffort)) return null;
+      reasoningEffort = d.reasoningEffort;
+    }
+    subagentDefaults = { model, reasoningEffort };
+  }
+  return {
+    version: HOME_CODEX_SETTINGS_VERSION,
+    home: { name, version: homeVersion },
+    settings: {
+      fastMode: s.fastMode as boolean | null,
+      multiAgentMode: s.multiAgentMode as MultiAgentMode | null,
+      webSearchSidecarEnabled: s.webSearchSidecarEnabled,
+      subagentDefaults,
+    },
+  };
+}
+
+/** The Child's config as the Codex injector should see it: local listener facts, Home policy. */
+export function overlayHomeCodexSettings(config: OcxConfig, settings: HomeCodexSettings): OcxConfig {
+  const next: OcxConfig = {
+    ...config,
+    webSearchSidecar: { ...(config.webSearchSidecar ?? {}), enabled: settings.webSearchSidecarEnabled },
+  };
+  if (settings.fastMode === null) delete next.fastMode;
+  else next.fastMode = settings.fastMode;
+  if (settings.multiAgentMode === null) delete next.multiAgentMode;
+  else next.multiAgentMode = settings.multiAgentMode;
+  if (settings.subagentDefaults) {
+    next.injectionModel = settings.subagentDefaults.model;
+    next.syncCodexSubagentDefaults = true;
+    if (settings.subagentDefaults.reasoningEffort) next.injectionEffort = settings.subagentDefaults.reasoningEffort;
+    else delete next.injectionEffort;
+  } else {
+    next.syncCodexSubagentDefaults = false;
+  }
+  return next;
+}
+
+/** One line per applied value, for `ocx sync`, `ocx status` and the dashboard. */
+export function describeHomeCodexSettings(settings: HomeCodexSettings): string[] {
+  const d = settings.subagentDefaults;
+  return [
+    `fast mode: ${settings.fastMode === null ? "unset" : settings.fastMode ? "on" : "off"}`,
+    `multi-agent mode: ${settings.multiAgentMode ?? "default"}`,
+    `web search sidecar: ${settings.webSearchSidecarEnabled ? "on" : "off"}`,
+    `native sub-agent defaults: ${d ? `${d.model}${d.reasoningEffort ? ` (${d.reasoningEffort})` : ""}` : "not synced"}`,
+  ];
+}