@bitkyc08/opencodex 2.82.0 → 2.84.0

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/redact.ts

@@ -7,7 +7,7 @@ export const REDACTED_SECRET = "[REDACTED]";
  * credentials over an unsafe channel (e.g. plaintext non-loopback HTTP) rather than
  * re-deriving a narrower local list.
  */
-export const SENSITIVE_KEY_PATTERN = /^(?:authorization|proxy-authorization|cookie|set-cookie|set-cookie2|api[-_]?key|x-api-key|x-goog-api-key|x-amz-security-token|access[-_]?token|refresh[-_]?token|id[-_]?token|token|secret|client[-_]?secret|password|profile[-_]?arn|exa[-_]?api[-_]?key)$/i;
+export const SENSITIVE_KEY_PATTERN = /^(?:authorization|proxy-authorization|cookie|set-cookie|set-cookie2|api[-_]?key|x-api-key|x-goog-api-key|x-amz-security-token|copilot[-_]?session[-_]?token|session[-_]?token|access[-_]?token|refresh[-_]?token|id[-_]?token|token|secret|client[-_]?secret|password|profile[-_]?arn|exa[-_]?api[-_]?key)$/i;
 
 /**
  * Colon-labelled credential headers echoed back inside an error body
@@ -40,7 +40,7 @@ export const SENSITIVE_KEY_PATTERN = /^(?:authorization|proxy-authorization|cook
 // Every letter position also accepts \u0001, the placeholder the fold emits for
 // an unresolved HTML named reference: `authorⅈzation` is the label with one
 // character we cannot name, and that is still the label.
-const CREDENTIAL_HEADER_LABEL_RAW = "x-api-key|x-goog-api-key|x-amz-security-token|api[_-]?key|apiKey|exa[_-]?api[_-]?key|exaApiKey|access[_-]?token|accessToken|refresh[_-]?token|refreshToken|id[_-]?token|client[_-]?secret|clientSecret|authorization|proxy-authorization|cookie|set-cookie|password|secret|token";
+const CREDENTIAL_HEADER_LABEL_RAW = "copilot[_-]?session[_-]?token|session[_-]?token|sessionToken|x-api-key|x-goog-api-key|x-amz-security-token|api[_-]?key|apiKey|exa[_-]?api[_-]?key|exaApiKey|access[_-]?token|accessToken|refresh[_-]?token|refreshToken|id[_-]?token|client[_-]?secret|clientSecret|authorization|proxy-authorization|cookie|set-cookie|password|secret|token";
 
 const CREDENTIAL_HEADER_LABEL = CREDENTIAL_HEADER_LABEL_RAW
   .replace(/(?<![\[\\])([A-Za-z])(?![\]\-])/g, "[$1\u0001]");

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"}`,
+  ];
+}

package/src/link/management-routes.ts

@@ -0,0 +1,89 @@
+/**
+ * The read-only management surface a Remote Link Child may reach on its Home (#6957).
+ *
+ * Default deny: a path is readable only when it is listed here, the method is GET or HEAD, and
+ * the query does not ask the Home to refresh upstream state. Everything else is refused on both
+ * ends: the Child's listener and CLI refuse before sending, and the Home's link listener answers
+ * 404 for any other path under the prefix. No route here returns a credential value; provider
+ * and account projections report presence and masked identities only.
+ *
+ * A link read must not change the Home. The Home runs these reads passively
+ * (`src/lib/passive-read.ts`): model discovery, which reaches provider upstreams and persists the
+ * initial model selection of a pending provider, config writes and diagnostics do not run (#6959).
+ * `tests/server/link-management-relay.test.ts` reads every path here and asserts that the Home
+ * config and its upstreams are untouched.
+ */
+export const LINK_MANAGEMENT_PREFIX = "/v1/link-management";
+/** The Home's OpenCodex-owned Codex settings a Child applies when it syncs. */
+export const LINK_CODEX_SETTINGS_PATH = `${LINK_MANAGEMENT_PREFIX}/codex-settings`;
+
+export const LINK_MANAGEMENT_READ_PATHS: readonly string[] = [
+  "/api/system/health",
+  "/api/startup-health",
+  "/api/providers",
+  "/api/settings",
+  "/api/usage",
+  "/api/effort-caps",
+  "/api/injection-model",
+  "/api/shadow-call-settings",
+  "/api/sidecar-settings",
+  "/api/v2",
+  "/api/provider-quotas",
+  "/api/codex-auth/active",
+  "/api/codex-auth/accounts",
+  "/api/oauth/accounts",
+  "/api/providers/keys",
+  "/api/oauth/providers",
+  "/api/catalog",
+  "/api/system/memory",
+  "/api/provider-presets",
+  "/api/provider-context-caps",
+];
+const READ_PATHS = new Set(LINK_MANAGEMENT_READ_PATHS);
+/**
+ * Query keys that make a read trigger upstream work on the Home: forced refreshes and the
+ * per-account quota probes `?quota=1` starts on the OAuth-account and key-pool reads.
+ * `/api/models`, `/api/model-presets`, `/api/subagent-models` and `/api/subagent-model-fallback`
+ * are absent for the same reason: they run live provider discovery and may persist initial model
+ * selection. The preset preview exists only to decide a write a Child cannot make.
+ */
+const REFRESH_KEYS = ["refresh", "reload", "force", "quota"];
+
+/** Is `method path?query` (a Home management path, without the link prefix) readable over the link? */
+export function linkManagementReadAllowed(method: string, pathname: string, search: URLSearchParams | string = ""): boolean {
+  const upper = method.toUpperCase();
+  if (upper !== "GET" && upper !== "HEAD") return false;
+  if (!READ_PATHS.has(pathname)) return false;
+  const query = typeof search === "string" ? new URLSearchParams(search) : search;
+  return !REFRESH_KEYS.some(key => query.has(key));
+}
+
+/** The Home management URL a prefixed link request names, or null when it names none. */
+export function linkManagementTarget(url: URL): URL | null {
+  if (!url.pathname.startsWith(`${LINK_MANAGEMENT_PREFIX}/api/`)) return null;
+  const target = new URL(url.href);
+  target.pathname = url.pathname.slice(LINK_MANAGEMENT_PREFIX.length);
+  return target;
+}
+
+/** Home side: may the hub-link listener dispatch this request to the link management handler? */
+export function linkManagementRouteAllowed(url: URL, req: Request): boolean {
+  if (req.headers.has("upgrade")) return false;
+  if (url.pathname === LINK_CODEX_SETTINGS_PATH) return req.method === "GET" && url.search === "";
+  const target = linkManagementTarget(url);
+  return target !== null && linkManagementReadAllowed(req.method, target.pathname, target.searchParams);
+}
+
+export function isLinkManagementPath(pathname: string): boolean {
+  return pathname === LINK_MANAGEMENT_PREFIX || pathname.startsWith(`${LINK_MANAGEMENT_PREFIX}/`);
+}
+
+/**
+ * The one refusal every management surface on a link Child uses: the dashboard relay, the CLI,
+ * and the Child's listener. It names the Home and the link and never suggests a relay transport.
+ * `homePhrase` is "Home <name>" or "its Home" when the Child does not know the Home's name.
+ */
+export function linkChildManagementRefusal(homePhrase: string, linkId: string, operation = "This management command"): string {
+  return `This machine is a Remote Link Child managed by ${homePhrase} (link ${linkId}). `
+    + `${operation} runs on the Home, not on this Child: use the Home's dashboard or run the command there. No request was sent.`;
+}

package/src/link/remote-probe.ts

@@ -0,0 +1,38 @@
+import { MEMORY_DRAIN_RESTART_MS, REPLACEMENT_READY_TIMEOUT_MS } from "../lib/system-restart-contract";
+
+export const LINK_COMMAND_WORK_MS = 15_000;
+export const LINK_COMMAND_MAX_MS = 60_000;
+export const LINK_RELAY_VERIFY_MS = 15_000;
+export const LINK_CATALOG_MAX_BYTES = 4 * 1024 * 1024;
+
+/** Probe latency pays for SSH setup without making the remote work window unbounded. */
+export function linkCommandBudget(latencyMs = 0): number {
+  const latency = Number.isFinite(latencyMs) ? Math.max(0, latencyMs) : 0;
+  return Math.min(LINK_COMMAND_MAX_MS, LINK_COMMAND_WORK_MS + Math.ceil(latency * 4));
+}
+
+export function linkRestartBudget(latencyMs = 0): number {
+  return MEMORY_DRAIN_RESTART_MS + REPLACEMENT_READY_TIMEOUT_MS + linkCommandBudget(latencyMs);
+}
+
+/** Credential-free Child HTTP probe. Ignore curlrc/proxies; never follow a redirect. */
+export function remoteChildHttpArgv(port: number, path: "healthz" | "v1/catalog", timeoutMs = LINK_RELAY_VERIFY_MS): string[] {
+  if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error("invalid Child port");
+  const seconds = Math.max(1, Math.ceil(Math.min(LINK_RELAY_VERIFY_MS, timeoutMs) / 1000));
+  return ["sh", "-c", 'curl -q --noproxy "*" --silent --show-error --fail --connect-timeout 3 --max-time "$3" --write-out "\\n%{http_code}" "http://127.0.0.1:$1/$2"', "ocx-child-http", String(port), path, String(seconds)];
+}
+
+export const REMOTE_CURL_PREFLIGHT = ["sh", "-c", 'command -v curl >/dev/null 2>&1 && curl -q --version >/dev/null 2>&1', "ocx-curl-preflight"];
+
+export function parseChildHttp(stdout: string): unknown {
+  const match = /\n200$/.exec(stdout.trimEnd());
+  if (!match) throw new Error("Child HTTP probe did not return 200");
+  return JSON.parse(stdout.trimEnd().slice(0, match.index));
+}
+
+export function isChildHealth(value: unknown, role: "standalone" | "client", expectedPort: number): boolean {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const body = value as Record<string, unknown>;
+  return body.port === expectedPort && body.service === "opencodex" && Number.isInteger(body.pid) && (body.pid as number) > 0
+    && (role === "client" ? body.role === "client" : (body.role === undefined || body.role === "standalone") && body.restartCapability === "v1");
+}

package/src/link/ssh-argv.ts

@@ -131,15 +131,36 @@ export function buildExecArgv(options: ExecArgvOptions): string[] {
   ];
 }
 
+/** The POSIX shell's exit status for a command it could not find. */
+export const REMOTE_COMMAND_NOT_FOUND = 127;
+/** Reserved prelude status: the remote OS cannot run the POSIX Remote Link workflow. */
+export const REMOTE_PLATFORM_UNSUPPORTED = 125;
+
 /**
  * The remote sh script for every ocx call. `quoteRemote` single-quotes it, so the login shell
  * passes it through untouched and `$HOME`/`$PATH` expand in the remote `sh`; the arguments reach
- * ocx as `"$@"` without another round of parsing. The fallback directories are appended, so an
- * ocx the remote PATH already resolves keeps winning. A missing ocx exits 127.
+ * ocx as `"$@"` without another round of parsing. Desktop binaries precede PATH candidates;
+ * each candidate must run --version successfully. A missing runnable ocx exits 127.
  */
-export const REMOTE_OCX_SCRIPT = 'PATH="$PATH:$HOME/.bun/bin:$HOME/.local/bin:/opt/homebrew/bin:/usr/local/bin"; exec ocx "$@"';
-/** The POSIX shell's exit status for a command it could not find. */
-export const REMOTE_COMMAND_NOT_FOUND = 127;
+export const REMOTE_OCX_SCRIPT = `export PATH="$PATH:$HOME/.bun/bin:$HOME/.local/bin:/opt/homebrew/bin:/usr/local/bin"
+case "$(uname -s 2>/dev/null)" in Windows*|MSYS*|MINGW*|CYGWIN*) exit ${REMOTE_PLATFORM_UNSUPPORTED};; esac
+try_ocx() {
+  if [ -x "$1" ] && "$1" --version >/dev/null 2>&1; then
+    executable=$1
+    shift
+    exec "$executable" "$@"
+  fi
+}
+for candidate in "$HOME/.opencodex-desktop/bin/ocx" "/Applications/OpenCodex.app/Contents/MacOS/ocx" "/usr/bin/ocx"; do
+  try_ocx "$candidate" "$@"
+done
+remaining=$PATH
+while :; do
+  directory=\${remaining%%:*}
+  try_ocx "\${directory:-.}/ocx" "$@"
+  case "$remaining" in *:*) remaining=\${remaining#*:};; *) break;; esac
+done
+exit ${REMOTE_COMMAND_NOT_FOUND}`;
 
 export function remoteOcxArgv(args: readonly string[]): string[] {
   return ["sh", "-c", REMOTE_OCX_SCRIPT, "ocx", ...args];