@bitkyc08/opencodex 2.82.0 → 2.84.0

package/src/client/hub-client.ts

@@ -485,7 +485,7 @@ export async function fetchHubUsage(
   serverUrl: string,
   admissionToken: string,
   query: URLSearchParams,
-  options: { timeoutMs?: number; fetchImpl?: typeof fetch } = {},
+  options: { timeoutMs?: number; fetchImpl?: typeof fetch; peer?: "hub" | "Home" } = {},
 ): Promise<HubUsageReport> {
   const origin = normalizeHubOrigin(serverUrl);
   if (!isHubTransportPermitted(origin)) {
@@ -498,9 +498,12 @@ export async function fetchHubUsage(
   }, options.timeoutMs);
   if (!response.ok) {
     try { await response.body?.cancel(); } catch { /* best effort */ }
-    const message = response.status === 404 ? "Hub does not support client usage; upgrade the hub"
-      : response.status === 401 || response.status === 403 ? "Hub rejected this client's usage credential"
-      : `Hub usage request failed (${response.status})`;
+    // A Remote Link Child reads the same route from its Home (#6957).
+    const peer = options.peer ?? "hub";
+    const Peer = peer === "Home" ? "Home" : "Hub";
+    const message = response.status === 404 ? `${Peer} does not support client usage; upgrade the ${peer}`
+      : response.status === 401 || response.status === 403 ? `${Peer} rejected this ${peer === "Home" ? "Child's link key" : "client's usage credential"}`
+      : `${Peer} usage request failed (${response.status})`;
     throw new HubClientError(`hub_usage_http_${response.status}`, message, response.status);
   }
   if (!jsonCompatibleContentType(response)) {
@@ -527,16 +530,20 @@ export async function fetchHubUsage(
  */
 export async function fetchHubState(
   serverUrl: string,
-  admissionToken: string,
+  admissionToken: string | null,
   options: { timeoutMs?: number; fetchImpl?: typeof fetch } = {},
 ): Promise<HubStateDTO> {
   const origin = normalizeHubOrigin(serverUrl);
   const response = await fetchBounded(options.fetchImpl ?? fetch, `${origin}/v1/hub-state`, {
     method: "GET",
-    headers: new Headers({ Accept: "application/json", "x-opencodex-api-key": admissionToken }),
+    headers: new Headers({ Accept: "application/json", ...(admissionToken === null ? {} : { "x-opencodex-api-key": admissionToken }) }),
   }, options.timeoutMs, "headers");
   if (response.status === 404) {
-    try { await response.body?.cancel(); } catch { /* best effort */ }
+    let body: unknown = null;
+    try { body = JSON.parse(await boundedText(response, 4096, { inactivityTimeoutMs: safeTimeout(options.timeoutMs) })); } catch { /* legacy/non-JSON 404 stays unsupported */ }
+    if (body && typeof body === "object" && !Array.isArray(body) && (body as { error?: { code?: unknown } }).error?.code === "hub_state_not_a_hub") {
+      throw new HubClientError("hub_state_not_a_hub", "the remote host does not publish hub state", 404);
+    }
     throw new HubClientError("hub_state_unsupported", "Hub does not serve /v1/hub-state; upgrade the hub", 404);
   }
   if (!response.ok) {

package/src/client/hub-state.ts

@@ -124,37 +124,43 @@ export function writeCachedHubState(owner: HubStateOwner, state: HubStateDTO, fe
  * banner reading `state unavailable (hub_state_http_507)` sends the reader looking for a client
  * bug when the hub has in fact answered and said something.
  */
-export function hubStateFailureReason(error: unknown): string {
+export function hubStateFailureReason(error: unknown, peer: "hub" | "Home" = "hub"): string {
+  // A Remote Link Child reads the same route from its Home (#6957); the sentences name the peer
+  // the operator actually configured.
+  const holder = peer === "Home" ? "this Child's link key" : "this client's data key";
   if (error instanceof HubClientError) {
     switch (error.code) {
+      case "hub_state_not_a_hub":
+        return "the remote host does not publish hub state";
       case "hub_state_unsupported":
-        return "this hub is too old to report its state; upgrade the hub";
+        return `this ${peer} is too old to report its state; upgrade the ${peer}`;
       case "hub_state_unauthorized":
-        return "the hub rejected this client's data key";
+        return `the ${peer} rejected ${holder}`;
       case "hub_state_schema_invalid":
       case "hub_state_invalid":
-        return "the hub returned an unreadable hub-state document";
+        return `the ${peer} returned an unreadable hub-state document`;
       case "hub_state_content_type_invalid":
         // Usually a captive portal, a TLS-terminating proxy or an error page in front of the
         // hub: the request reached SOMETHING, and that something is not the hub's API.
-        return "the hub's state response was not JSON";
+        return `the ${peer}'s state response was not JSON`;
       case "body_too_large":
-        return "the hub's state response exceeded the allowed size";
+        return `the ${peer}'s state response exceeded the allowed size`;
       case "unreachable":
-        return "the hub is unreachable";
+        return `the ${peer} is unreachable`;
       case "redirect_refused":
-        return "the hub redirected the state request";
+        return `the ${peer} redirected the state request`;
       default: {
         const status = error.code.startsWith("hub_state_http_")
           ? error.code.slice("hub_state_http_".length)
           : null;
         return status && /^\d+$/.test(status)
-          ? `the hub answered HTTP ${status} to the state request`
+          ? `the ${peer} answered HTTP ${status} to the state request`
           : error.code;
       }
     }
   }
-  return "the hub state could not be read";
+  if (error instanceof Error && error.name === "LinkRelayAuthenticationError") return error.message;
+  return `the ${peer} state could not be read`;
 }
 
 export interface ResolveHubStateOptions {
@@ -167,6 +173,8 @@ export interface ResolveHubStateOptions {
    * token for a different connection, and the operator acts on that difference.
    */
   withheldTokenReason?: string;
+  /** Identity-checked local Child transport that strips credentials and owns Home admission. */
+  localRelayFetchImpl?: typeof fetch;
   timeoutMs?: number;
   fetchImpl?: typeof fetch;
   now?: number;
@@ -174,6 +182,8 @@ export interface ResolveHubStateOptions {
   allowNetwork?: boolean;
   /** False skips the cache write, for read-only callers. */
   persist?: boolean;
+  /** Which peer the sentences name: a hub, or a Remote Link Child's Home. */
+  peer?: "hub" | "Home";
 }
 
 function withAge(
@@ -201,20 +211,21 @@ export async function resolveHubState(options: ResolveHubStateOptions): Promise<
       ? withAge("cache", cached.state, cached.fetchedAt, now, reason)
       : withAge("unavailable", null, undefined, now, reason);
   };
-  if (!options.token) {
+  if (!options.token && !options.localRelayFetchImpl) {
     return fromCache(options.withheldTokenReason ?? "this client has no usable data-plane token");
   }
   if (options.allowNetwork === false) return fromCache("a live hub read was not attempted");
   let state: HubStateDTO;
   try {
-    state = await fetchHubState(options.owner.serverUrl, options.token, {
+    state = await fetchHubState(options.owner.serverUrl, options.localRelayFetchImpl ? null : options.token, {
       timeoutMs: options.timeoutMs ?? DEFAULT_HUB_STATE_TIMEOUT_MS,
-      ...(options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}),
+      ...((options.localRelayFetchImpl ?? options.fetchImpl) ? { fetchImpl: options.localRelayFetchImpl ?? options.fetchImpl } : {}),
     });
   } catch (error) {
     // Deliberately no local-state fallback here. A stale cache is still the HUB's state; the
     // client's own providers and logins are not, at any age.
-    return fromCache(hubStateFailureReason(error));
+    if (error instanceof HubClientError && error.code === "hub_state_not_a_hub") return withAge("unavailable", null, undefined, now, hubStateFailureReason(error, options.peer));
+    return fromCache(hubStateFailureReason(error, options.peer));
   }
   const fetchedAt = new Date(now).toISOString();
   if (options.persist !== false) writeCachedHubState(options.owner, state, fetchedAt);

package/src/client/link-home.ts

@@ -0,0 +1,248 @@
+/**
+ * A Remote Link Child's view of its Home (#6957): the Home's name for refusal and status text,
+ * the Home's OpenCodex-owned Codex settings, and authenticated read-only management reads.
+ *
+ * Every read goes through the connection-bound link relay (`fetchBoundLinkRelay`): the link key
+ * is sent only after the listener on the tunnel port proves it holds the same link identity, so a
+ * process that took the tunnel port never sees the key.
+ */
+import { chmodSync, lstatSync, mkdirSync, readFileSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { atomicWriteFile, isMissingPathError } from "../config/atomic-write";
+import { readBoundedResponseBytes } from "../lib/bounded-body";
+import { assertNotRealHomeUnderTest } from "../lib/test-home-guard";
+import { hardenSecretDir } from "../lib/windows-secret-acl";
+import {
+  parseHomeCodexSettingsDocument,
+  type HomeCodexSettingsDocument,
+} from "../link/codex-settings";
+import {
+  LINK_CODEX_SETTINGS_PATH,
+  LINK_MANAGEMENT_PREFIX,
+  linkManagementReadAllowed,
+} from "../link/management-routes";
+import { linkDir } from "../link/paths";
+import type { OcxClientConnectionConfig } from "../types";
+import { fetchBoundLinkRelay } from "./link-relay-transport";
+import { readClientLinkState, type ClientLinkState } from "./link-state";
+
+const RECORD_MAX_BYTES = 64 * 1024;
+const SETTINGS_MAX_BYTES = 64 * 1024;
+const READ_TIMEOUT_MS = 10_000;
+
+export interface LinkHomeDeps {
+  /** Trusted complete-send test seam; production uses the connection-bound transport. */
+  fetchImpl?: typeof fetch;
+  timeoutMs?: number;
+}
+
+/** The connection fields a Home read needs; connect calls these before its state is committed. */
+export type LinkHomeConnection = Pick<OcxClientConnectionConfig, "transport" | "link" | "apiKeyId">;
+
+export interface HomeCodexSettingsRecord {
+  linkId: string;
+  fetchedAt: string;
+  document: HomeCodexSettingsDocument;
+}
+
+export function homeCodexSettingsPath(): string {
+  return join(linkDir(), "home-codex-settings.json");
+}
+
+function linkTarget(connection: LinkHomeConnection, admissionKey: string) {
+  if (connection.transport !== "link" || !connection.link) throw new Error("not a Remote Link Child");
+  return {
+    tunnelPort: connection.link.tunnelPort,
+    linkId: connection.link.linkId,
+    apiKeyId: connection.apiKeyId,
+    admissionKey,
+  };
+}
+
+/** The last applied Home settings for this link, or null when absent, malformed or another link's. */
+export function readHomeCodexSettingsRecord(linkId: string, path = homeCodexSettingsPath()): HomeCodexSettingsRecord | null {
+  try {
+    const stat = lstatSync(path);
+    if (!stat.isFile() || stat.size > RECORD_MAX_BYTES) return null;
+    const raw = JSON.parse(readFileSync(path, "utf8")) as unknown;
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+    const record = raw as Record<string, unknown>;
+    if (record.linkId !== linkId || typeof record.fetchedAt !== "string" || Number.isNaN(Date.parse(record.fetchedAt))) return null;
+    const document = parseHomeCodexSettingsDocument(record.document);
+    return document ? { linkId, fetchedAt: record.fetchedAt, document } : null;
+  } catch {
+    return null;
+  }
+}
+
+export function writeHomeCodexSettingsRecord(record: HomeCodexSettingsRecord, path = homeCodexSettingsPath()): void {
+  const dir = linkDir();
+  assertNotRealHomeUnderTest(join(dir, ".."));
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  if (process.platform === "win32") hardenSecretDir(dir, { required: true });
+  else chmodSync(dir, 0o700);
+  atomicWriteFile(path, `${JSON.stringify(record, null, 2)}\n`);
+  if (process.platform !== "win32") chmodSync(path, 0o600);
+}
+
+export function clearHomeCodexSettingsRecord(path = homeCodexSettingsPath()): void {
+  try { unlinkSync(path); } catch (error) { if (!isMissingPathError(error)) throw error; }
+}
+
+/**
+ * The Home's name as this Child knows it: the SSH alias of a Child-initiated link, else the
+ * host name the Home published with its Codex settings, else null ("its Home").
+ */
+export function linkHomeName(
+  connection: OcxClientConnectionConfig,
+  readSidecar: () => ClientLinkState | null = readClientLinkState,
+): string | null {
+  const linkId = connection.link?.linkId;
+  if (!linkId) return null;
+  try {
+    const sidecar = readSidecar();
+    if (sidecar && sidecar.linkId === linkId) return sidecar.alias;
+  } catch { /* an unreadable sidecar names nothing */ }
+  return readHomeCodexSettingsRecord(linkId)?.document.home.name ?? null;
+}
+
+/** "Home home-box" or "its Home": the phrase every link Child message uses. */
+export function linkHomePhrase(
+  connection: OcxClientConnectionConfig,
+  readSidecar?: () => ClientLinkState | null,
+): string {
+  const name = linkHomeName(connection, readSidecar);
+  return name ? `Home ${name}` : "its Home";
+}
+
+/**
+ * A `fetch` for the existing data-plane reads (`/v1/hub-state`, `/v1/usage`) that sends each
+ * request through the connection-bound link relay, so the link key reaches only the Home.
+ */
+export function linkBoundFetch(connection: LinkHomeConnection, admissionKey: string): typeof fetch {
+  const target = linkTarget(connection, admissionKey);
+  return ((input: RequestInfo | URL, init?: RequestInit) => {
+    // A Request keeps its method, headers and signal unless init overrides them.
+    const request = input instanceof Request ? input : null;
+    const url = request ? request.url : String(input);
+    return fetchBoundLinkRelay(target, url, {
+      ...(request ? { method: request.method, headers: request.headers, signal: request.signal } : {}),
+      ...(init ?? {}),
+      redirect: "manual",
+    });
+  }) as typeof fetch;
+}
+
+/**
+ * One authenticated, read-only management read on the Home. `path` is a Home management path
+ * with an optional query (`/api/providers`); anything outside the shared allowlist throws before
+ * a request is built.
+ */
+export async function fetchLinkHomeManagement(
+  connection: LinkHomeConnection,
+  admissionKey: string,
+  path: string,
+  init: { method?: "GET" | "HEAD"; signal?: AbortSignal } = {},
+  deps: LinkHomeDeps = {},
+): Promise<Response> {
+  const method = init.method ?? "GET";
+  const local = new URL(path, "http://link.invalid");
+  if (local.origin !== "http://link.invalid" || !linkManagementReadAllowed(method, local.pathname, local.searchParams)) {
+    throw new Error("path is not readable over the Remote Link");
+  }
+  const target = linkTarget(connection, admissionKey);
+  const destination = `http://127.0.0.1:${target.tunnelPort}${LINK_MANAGEMENT_PREFIX}${local.pathname}${local.search}`;
+  const signal = init.signal
+    ? AbortSignal.any([init.signal, AbortSignal.timeout(deps.timeoutMs ?? READ_TIMEOUT_MS)])
+    : AbortSignal.timeout(deps.timeoutMs ?? READ_TIMEOUT_MS);
+  const request: RequestInit = {
+    method,
+    headers: { accept: "application/json", authorization: `Bearer ${admissionKey}` },
+    redirect: "manual",
+    signal,
+  };
+  return deps.fetchImpl ? deps.fetchImpl(destination, request) : fetchBoundLinkRelay(target, destination, request);
+}
+
+export type HomeCodexSettingsFetch =
+  | { kind: "fresh"; document: HomeCodexSettingsDocument }
+  | { kind: "unsupported" }
+  | { kind: "failed"; reason: string };
+
+export async function fetchHomeCodexSettings(
+  connection: LinkHomeConnection,
+  admissionKey: string,
+  deps: LinkHomeDeps = {},
+): Promise<HomeCodexSettingsFetch> {
+  let response: Response;
+  try {
+    const target = linkTarget(connection, admissionKey);
+    const destination = `http://127.0.0.1:${target.tunnelPort}${LINK_CODEX_SETTINGS_PATH}`;
+    const request: RequestInit = {
+      method: "GET",
+      headers: { accept: "application/json", authorization: `Bearer ${admissionKey}` },
+      redirect: "manual",
+      signal: AbortSignal.timeout(deps.timeoutMs ?? READ_TIMEOUT_MS),
+    };
+    response = deps.fetchImpl ? await deps.fetchImpl(destination, request) : await fetchBoundLinkRelay(target, destination, request);
+  } catch (error) {
+    return { kind: "failed", reason: error instanceof Error && error.name === "LinkRelayAuthenticationError" ? error.message : "the Home is unreachable" };
+  }
+  if (response.status === 404) {
+    try { await response.body?.cancel(); } catch { /* best effort */ }
+    return { kind: "unsupported" };
+  }
+  if (!response.ok) {
+    try { await response.body?.cancel(); } catch { /* best effort */ }
+    return { kind: "failed", reason: `the Home answered HTTP ${response.status}` };
+  }
+  try {
+    const result = await readBoundedResponseBytes(response, { maxBytes: SETTINGS_MAX_BYTES, signal: AbortSignal.timeout(deps.timeoutMs ?? READ_TIMEOUT_MS) });
+    if (result.oversized) return { kind: "failed", reason: "the Home's settings exceeded the allowed size" };
+    const document = parseHomeCodexSettingsDocument(JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(result.bytes)));
+    return document ? { kind: "fresh", document } : { kind: "failed", reason: "the Home returned an unreadable settings document" };
+  } catch {
+    return { kind: "failed", reason: "the Home returned an unreadable settings document" };
+  }
+}
+
+export type HomeCodexSettingsSource =
+  | { source: "home"; document: HomeCodexSettingsDocument; fetchedAt: string }
+  | { source: "cached"; document: HomeCodexSettingsDocument; fetchedAt: string; reason: string }
+  | { source: "local"; reason: string };
+
+/**
+ * The settings a sync applies. A failed read reuses the last record for this link so a brief
+ * outage never flips the Child back to its local values; a Home that predates the route leaves
+ * the Child's local values in place and says so. A fresh read is NOT recorded here: the caller
+ * records it with `recordHomeCodexSettings` only after the injection that applies it succeeds,
+ * because `ocx status` reads the record as "applied".
+ */
+export async function resolveHomeCodexSettings(
+  connection: LinkHomeConnection,
+  admissionKey: string,
+  deps: LinkHomeDeps & { now?: () => Date } = {},
+): Promise<HomeCodexSettingsSource> {
+  const linkId = connection.link?.linkId;
+  if (!linkId) return { source: "local", reason: "not a Remote Link Child" };
+  const fetched = await fetchHomeCodexSettings(connection, admissionKey, deps);
+  if (fetched.kind === "fresh") {
+    return { source: "home", document: fetched.document, fetchedAt: (deps.now ?? (() => new Date()))().toISOString() };
+  }
+  if (fetched.kind === "unsupported") {
+    clearHomeCodexSettingsRecord();
+    return { source: "local", reason: "the Home does not publish Codex settings; upgrade the Home" };
+  }
+  const cached = readHomeCodexSettingsRecord(linkId);
+  return cached
+    ? { source: "cached", document: cached.document, fetchedAt: cached.fetchedAt, reason: fetched.reason }
+    : { source: "local", reason: fetched.reason };
+}
+
+/** Record settings a successful injection applied. Best effort: the config is already written. */
+export function recordHomeCodexSettings(linkId: string, settings: HomeCodexSettingsSource): void {
+  if (settings.source !== "home") return;
+  try {
+    writeHomeCodexSettingsRecord({ linkId, fetchedAt: settings.fetchedAt, document: settings.document });
+  } catch { /* the next sync records it */ }
+}

package/src/client/link-management-relay.ts

@@ -0,0 +1,61 @@
+/**
+ * The Child end of the Remote Link management relay (#6957).
+ *
+ * The Child's dashboard reaches its Home's management reads at `/api/machine/hub-relay/api/*`,
+ * the same base a hub client's dashboard uses. The browser authenticates to the Child with the
+ * Child's own dashboard session; this relay drops every browser header, builds a fresh GET for
+ * the Home's `/v1/link-management` prefix and sends it through the connection-bound link relay,
+ * which attaches the link key only after the tunnel listener proves the link identity. Anything
+ * outside the shared read allowlist is refused here, before a request exists.
+ */
+import { HUB_RELAY_RESPONSE_BODY_MAX_BYTES } from "./hub-relay";
+import type { LinkIngress } from "./link-ingress";
+import { relayLinkDataRequest } from "./link-relay";
+import {
+  LINK_MANAGEMENT_PREFIX,
+  linkChildManagementRefusal,
+  linkManagementReadAllowed,
+  linkManagementRouteAllowed,
+} from "../link/management-routes";
+
+export const LINK_CHILD_READ_ONLY = "link_child_read_only";
+
+export function linkChildRefusalResponse(homePhrase: string, linkId: string, operation: string): Response {
+  return Response.json({
+    error: linkChildManagementRefusal(homePhrase, linkId, operation),
+    code: LINK_CHILD_READ_ONLY,
+    linkId,
+  }, { status: 403, headers: { "cache-control": "no-store" } });
+}
+
+export async function relayLinkManagementRead(
+  req: Request,
+  suffix: string,
+  ingress: LinkIngress,
+  homePhrase: string,
+): Promise<Response> {
+  const linkId = ingress.linkId ?? "unknown";
+  const query = suffix.indexOf("?");
+  const pathname = query === -1 ? suffix : suffix.slice(0, query);
+  const search = query === -1 ? "" : suffix.slice(query);
+  if (!linkManagementReadAllowed(req.method, pathname, new URLSearchParams(search.slice(1)))) {
+    return linkChildRefusalResponse(homePhrase, linkId, `${req.method.toUpperCase()} ${pathname}`);
+  }
+  const admissionKey = ingress.linkKey();
+  if (!admissionKey) return Response.json({ error: "link_credential_unavailable" }, { status: 503 });
+  const outbound = new Request(`http://127.0.0.1${LINK_MANAGEMENT_PREFIX}${pathname}${search}`, {
+    method: req.method,
+    headers: { accept: "application/json" },
+    signal: req.signal,
+  });
+  return relayLinkDataRequest(outbound, {
+    tunnelPort: ingress.tunnelPort,
+    admissionKey,
+    linkId: ingress.linkId,
+    apiKeyId: ingress.apiKeyId,
+  }, {
+    ...ingress.relay,
+    bodyLimitBytes: HUB_RELAY_RESPONSE_BODY_MAX_BYTES,
+    routeAllowed: linkManagementRouteAllowed,
+  });
+}

package/src/client/link-relay.ts

@@ -69,6 +69,11 @@ export interface LinkRelayDeps {
   /** The longest a request waits for a reconnecting tunnel, from its first wait. */
   holdMs?: number;
   now?: () => number;
+  /**
+   * The route table this relay enforces. Defaults to the data-plane table; only the Child's
+   * authenticated management relay passes the read-only management table (#6957).
+   */
+  routeAllowed?: (url: URL, req: Request) => boolean;
 }
 
 export const LINK_RELAY_RETRY_AFTER_SECONDS = 1;
@@ -305,7 +310,7 @@ export async function relayLinkDataRequest(
   deps: LinkRelayDeps = {},
 ): Promise<Response> {
   const url = new URL(req.url);
-  if (!linkRouteAllowed(url, req)) return jsonError(404, "not_found");
+  if (!(deps.routeAllowed ?? linkRouteAllowed)(url, req)) return jsonError(404, "not_found");
   let destination: string;
   try { destination = linkRelayDestination(url, target); } catch { return jsonError(404, "not_found"); }
   const validation = validateHubRelayRequestHeaders(linkFramingHeaders(req.headers));

package/src/client/link-status.ts

@@ -1,3 +1,7 @@
+import { lstatSync } from "node:fs";
+import { isMissingPathError } from "../config/atomic-write";
+import { readClientLinkState, childLinkMarkerPath } from "./link-state";
+import type { ClientLinkIdentity } from "../link/status-projection";
 import type { LinkStatusDto } from "../link/status-projection";
 import type { ClientLinkState } from "./link-state";
 import type { ClientLinkSupervisorStatus } from "./link-tunnel";
@@ -37,3 +41,13 @@ function childState(sidecar: ClientLinkSidecarRead, supervisor: ClientLinkSuperv
     reason: supervisor.probe ?? (tunnel.kind === "failed" ? tunnel.reason : null),
   };
 }
+
+/** Only client-owned evidence can establish who owns the tunnel. Unreadable evidence stays unknown. */
+export function clientLinkStatusIdentity(linkId: string): ClientLinkIdentity | null {
+  try {
+    const sidecar = readClientLinkState();
+    if (sidecar) return sidecar.linkId === linkId ? { direction: "client-initiated", alias: sidecar.alias } : null;
+    try { lstatSync(childLinkMarkerPath()); return null; }
+    catch (error) { return isMissingPathError(error) ? { direction: "hub-initiated" } : null; }
+  } catch { return null; }
+}

package/src/client/machine-api.ts

@@ -3,6 +3,7 @@ import { diagnoseCodexShim, installCodexShim, uninstallCodexShim } from "../code
 import { readManagementJsonBody } from "../server/management/body";
 import type { OcxClientConnectionConfig } from "../types";
 import { disconnectClient, syncConnectedClient } from "./connect";
+import { linkHomeName } from "./link-home";
 import { isLinkConnection } from "./state";
 
 export type HubReachability = "unknown" | "online" | "offline" | "unauthorized";
@@ -19,6 +20,8 @@ export interface MachineStatusV1 {
   connectedAt: string;
   catalogSyncedAt?: string;
   hubReachability: HubReachability;
+  /** Present only on a Remote Link Child: the dashboard shows "managed by Home <name>". */
+  link?: { linkId: string; home: string | null; readOnly: true };
 }
 
 export interface MachineApiDeps {
@@ -27,6 +30,8 @@ export interface MachineApiDeps {
   scheduleStandaloneRecycle: (disconnectedTokenFingerprint: string) => void;
   hubReachability?: () => HubReachability;
   setHubReachability?: (value: HubReachability) => void;
+  /** Link mode: the Home's name as this listener knows it (sidecar alias or recorded host name). */
+  linkHomeName?: () => string | null;
 }
 
 const defaultDeps: MachineApiDeps = {
@@ -52,24 +57,26 @@ async function jsonBody(req: Request): Promise<unknown | Response> {
 function statusPayload(req: Request, state: OcxClientConnectionConfig, deps: MachineApiDeps): MachineStatusV1 {
   const machineBase = new URL(req.url).origin;
   // A link Child's management URL is the tunnel, whose hub-link ingress serves no /api/* and no
-  // session bootstrap. Its dashboard reads the Child's own listener instead (`/api/link/status`).
+  // session bootstrap. Its dashboard therefore uses this listener's relay base: the browser holds
+  // only this listener's session, and the listener relays allowlisted reads to the Home with the
+  // link key (#6957, src/client/link-management-relay.ts).
   const linkMode = isLinkConnection(state);
+  const relay = linkMode || state.managementTransport === "relay";
   return {
     mode: "client",
     connected: true,
     machineBase,
-    sharedBase: linkMode
-      ? machineBase
-      : state.managementTransport === "relay"
-        ? `${machineBase}/api/machine/hub-relay`
-        : state.managementUrl,
+    sharedBase: relay ? `${machineBase}/api/machine/hub-relay` : state.managementUrl,
     sharedServerOrigin: linkMode ? machineBase : state.managementUrl,
-    managementTransport: state.managementTransport,
+    managementTransport: relay ? "relay" : state.managementTransport,
     apiKeyId: state.apiKeyId,
     protocolVersion: state.protocolVersion,
     connectedAt: state.connectedAt,
     ...(state.catalogSyncedAt ? { catalogSyncedAt: state.catalogSyncedAt } : {}),
     hubReachability: deps.hubReachability?.() ?? "unknown",
+    ...(linkMode && state.link
+      ? { link: { linkId: state.link.linkId, home: deps.linkHomeName ? deps.linkHomeName() : linkHomeName(state), readOnly: true as const } }
+      : {}),
   };
 }
 

package/src/client/machine-listener.ts

@@ -23,6 +23,8 @@ import { projectClientLinkChild, type ClientLinkSidecarRead } from "./link-statu
 import type { ClientLinkSupervisorStatus } from "./link-tunnel";
 import { packageVersion } from "../lib/package-version";
 import { linkRouteAllowed } from "../link/routes";
+import { linkHomeName, linkHomePhrase } from "./link-home";
+import { relayLinkManagementRead } from "./link-management-relay";
 
 const VERSION = packageVersion("0.0.0");
 const GUI_SPA_PATHS = new Set([
@@ -100,6 +102,8 @@ export function startMachineListener(
   if (linkMode && !connection.link) throw new Error("link machine listener requires link transport metadata");
   const managementAuth = deps.managementAuthState ?? initializeManagementAuthState(config);
   let hubReachability: HubReachability = "unknown";
+  const readSidecar = deps.readSidecar ?? (() => readClientLinkState());
+  const sidecarOrNull = () => { const read = readSidecarSafely(readSidecar); return read === "invalid" ? null : read; };
   const machineApiDeps: MachineApiDeps = {
     sync: deps.machineApi?.sync ?? syncConnectedClient,
     disconnect: deps.machineApi?.disconnect ?? disconnectClient,
@@ -108,8 +112,11 @@ export function startMachineListener(
     }),
     hubReachability: deps.machineApi?.hubReachability ?? (() => hubReachability),
     setHubReachability: deps.machineApi?.setHubReachability ?? (value => { hubReachability = value; }),
+    ...(linkMode ? { linkHomeName: () => linkHomeName(connection, sidecarOrNull) } : {}),
   };
-  const relayEnabled = !linkMode && connection.managementTransport === "relay";
+  // A link Child relays its dashboard's management reads to the Home over the link (#6957);
+  // a hub client relays over its management transport when that is `relay`.
+  const relayEnabled = linkMode || connection.managementTransport === "relay";
   // Link mode only. Everything is resolved once here, so a relayed request reads no file and
   // builds no policy: the key is cached, the loopback policy is fixed at bind like the listener.
   const inboundBodyLimit = resolveInboundBodyLimitBytes(config.maxInboundBodyBytes);
@@ -123,8 +130,6 @@ export function startMachineListener(
       relay: { fetchImpl: deps.fetchImpl, bodyLimitBytes: inboundBodyLimit, tunnel: deps.linkTunnel, ...deps.linkRelay },
     }
     : null;
-  const readSidecar = deps.readSidecar ?? (() => readClientLinkState());
-
   return (deps.serve ?? (options => Bun.serve(options)))({
     port: port ?? config.port ?? 10100,
     hostname: "127.0.0.1",
@@ -147,9 +152,29 @@ export function startMachineListener(
       }
       if (url.pathname.startsWith("/api/machine/hub-relay/")) {
         if (!relayEnabled) return json404(req);
+        const prefix = "/api/machine/hub-relay";
+        if (linkIngress) {
+          const suffix = `${url.pathname.slice(prefix.length)}${url.search}`;
+          // The dashboard's shared plane bootstraps here. On a link Child that plane is this
+          // listener, so it receives this listener's own session; no Home credential exists.
+          if (suffix === "/opencodex-session") {
+            if (req.method !== "GET") return json404(req);
+            const session = issueGuiSession(req, config, managementAuth, { trustedTailscaleIngress: false });
+            return session ? serveSessionBootstrap(session) : Response.json({ error: "session unavailable" }, { status: 503 });
+          }
+          const authError = requireManagementAuth(req, managementAuth, config);
+          if (authError) return authError;
+          if (managementPrincipal(req, managementAuth, config) !== "gui-session") {
+            return Response.json({ error: "opencodex machine GUI session required" }, { status: 401 });
+          }
+          const response = await relayLinkManagementRead(req, suffix, linkIngress, linkHomePhrase(connection, sidecarOrNull));
+          if (response.status === 401) hubReachability = "unauthorized";
+          else if (response.status >= 500) hubReachability = "offline";
+          else if (response.status !== 403) hubReachability = "online";
+          return response;
+        }
         const authError = requireMachineAuth(req, managementAuth, config);
         if (authError) return authError;
-        const prefix = "/api/machine/hub-relay";
         const suffix = `${url.pathname.slice(prefix.length)}${url.search}`;
         const response = await relayHubManagementRequest(req, suffix, {
           managementUrl: connection.managementUrl,

package/src/clients/config-export/model-metadata.ts

@@ -2,6 +2,7 @@
 import { getModelMetadata, resolveMetadataProvider } from "../../generated/model-metadata";
 import { SCHEMA_REQUIRED_OUTPUT_BUDGET } from "./constants";
 import { expandFastExportModels } from "./fast-models";
+import { sanitizeCodexReasoningEfforts } from "../../reasoning-effort";
 import type { OpencodeCatalogModel, ExportModel, ExportClientId, ManagedContribution } from "./contracts";
 import type { OcxConfig } from "../../types";
 import { shouldInjectApiAuthHeader } from "../../codex/inject";
@@ -84,6 +85,21 @@ export function inputModalitiesForClient(
   return kept.length > 0 ? kept : null;
 }
 
+/**
+ * Effort ladder a ZCode surface can offer as picker values, or undefined when the row
+ * has nothing selectable.
+ *
+ * Both ZCode exports — the legacy `v2/config.json` block's `reasoning.variants` and the
+ * `v2/provider_config.json` store's `optionSpecs.reasoningLevel.values` — carry the same
+ * Codex vocabulary: the client validates the chosen level against the emitted list and
+ * forwards it verbatim, and `/v1/responses` reads that vocabulary natively. `none` is a
+ * Codex omit-sentinel, not a picker option, so it never survives into the values.
+ */
+export function zcodeSelectableEfforts(efforts: readonly string[] | undefined): string[] | undefined {
+  const selectable = sanitizeCodexReasoningEfforts(efforts)?.filter(effort => effort !== "none");
+  return selectable && selectable.length > 0 ? selectable : undefined;
+}
+
 /**
  * Input modalities opencode's model schema accepts (opencode.ai/config.json, both
  * `modalities.input` and `modalities.output`). Wider than our internal `text | image | audio`