@bitkyc08/opencodex 2.83.0 → 2.84.0

package/src/client/connect.ts

@@ -74,6 +74,16 @@ import {
   assertNoClientDisconnectPending, assertClientConnectionUnchanged, sameClientConnectionOwner,
 } from "./state";
 import { assertClientCatalogCompatible, type CatalogCompatibilityDeps } from "./catalog-compatibility";
+import { overlayHomeCodexSettings } from "../link/codex-settings";
+import {
+  clearHomeCodexSettingsRecord,
+  fetchHomeCodexSettings,
+  resolveHomeCodexSettings,
+  recordHomeCodexSettings,
+  writeHomeCodexSettingsRecord,
+  type HomeCodexSettingsSource,
+  type LinkHomeDeps,
+} from "./link-home";
 import { hubStateCachePath } from "./hub-state";
 import { ClientLinkStateError, clearClientLinkState, readClientLinkState } from "./link-state";
 import { isLinkPort } from "../link/ports";
@@ -110,6 +120,8 @@ export interface ClientConnectDeps {
   now?: () => Date;
   lifecycleLockDeps?: ClientLifecycleLockDeps;
   catalogCompatibility?: CatalogCompatibilityDeps;
+  /** Link mode: how the Home's Codex settings are read (#6957). */
+  linkHome?: LinkHomeDeps;
 }
 
 export interface RotateClientOptions {
@@ -687,7 +699,16 @@ export async function connectClient(
 
     const config = earlyConfig ?? loadConfig();
     const target = routingTarget(serverUrl, linkMode ? config.port : undefined, config);
-    const injectConfig = { ...config, syncResumeHistory: false };
+    // A link Child writes the Home's OpenCodex-owned Codex settings, not its own (#6957). A read
+    // that fails here keeps the local values; the next `ocx sync` applies the Home's.
+    // Read only: the record is written after the connection commits, so a rollback leaves none.
+    const homeSettings = linkMode && linkMetadata && options.selectedClients.includes("codex")
+      ? await fetchHomeCodexSettings({ transport: "link", link: linkMetadata, apiKeyId }, admissionToken, deps.linkHome)
+      : undefined;
+    const injectConfig = {
+      ...(homeSettings?.kind === "fresh" ? overlayHomeCodexSettings(config, homeSettings.document.settings) : config),
+      syncResumeHistory: false,
+    };
     const preflight = await injectCodexConfig(config.port, injectConfig, {
       validateOnly: true,
       routingTarget: target,
@@ -734,6 +755,12 @@ export async function connectClient(
       commitClientConnection(connection);
       committed = true;
     }), deps.lifecycleLockDeps);
+    // Recorded only when the injection that applied it ran (not with --no-sync).
+    if (homeSettings?.kind === "fresh" && linkMetadata && injectionCommitted) {
+      try {
+        writeHomeCodexSettingsRecord({ linkId: linkMetadata.linkId, fetchedAt: now, document: homeSettings.document });
+      } catch { /* the next sync records it; the applied config is already committed */ }
+    }
     return connection;
   } catch (error) {
     const rollbackFailures: string[] = [];
@@ -780,7 +807,7 @@ export async function connectClient(
 export async function syncConnectedClient(
   _options: { restartCodex?: boolean } = {},
   deps: ClientConnectDeps = {},
-): Promise<{ catalogWritten: boolean; cacheSynced: boolean; injected: boolean; stale: boolean }> {
+): Promise<{ catalogWritten: boolean; cacheSynced: boolean; injected: boolean; stale: boolean; homeSettings?: HomeCodexSettingsSource }> {
   if (siblingOfLivePort() !== null) throw new Error(siblingSkipMessage());
   const initial = withClientLifecycleSync(() => withConfigMutationLockSync(() => {
     assertNoClientDisconnectPending();
@@ -825,21 +852,28 @@ export async function syncConnectedClient(
     if (next.pendingOperation || token.kind !== "present" || token.fingerprint !== next.tokenFingerprint) throw new Error("client_token_changed");
   };
   let injected = false;
+  let homeSettings: HomeCodexSettingsSource | undefined;
   if (next.selectedClients.includes("codex")) {
-    const config = loadConfig();
+    let config = loadConfig();
+    // #6957: a link Child applies the Home's OpenCodex-owned Codex settings with the catalog.
+    if (isLinkConnection(next)) {
+      homeSettings = await resolveHomeCodexSettings(next, initial.token.token, deps.linkHome);
+      if (homeSettings.source !== "local") config = overlayHomeCodexSettings(config, homeSettings.document.settings);
+    }
     const result = await injectCodexConfig(config.port, { ...config, syncResumeHistory: false }, {
       routingTarget: routingTarget(next.serverUrl, isLinkConnection(next) ? config.port : undefined, config), catalogPath: DEFAULT_CATALOG_PATH,
       journalOwner: { kind: "client", apiKeyId: next.apiKeyId }, beforeClientWrite,
     });
     if (!result.success || result.status === "skipped") throw new Error(result.message);
     injected = true;
+    if (homeSettings && next.link) recordHomeCodexSettings(next.link.linkId, homeSettings);
   }
   const cacheSynced = withClientLifecycleSync(() => {
     beforeClientWrite();
     // Cache invalidation acquires K itself (N -> K -> C); never call it while C is held.
     return invalidateCodexModelsCache({ allowWhenDesiredDisabled: true });
   }, deps.lifecycleLockDeps);
-  return { catalogWritten: downloaded !== undefined, cacheSynced, injected, stale };
+  return { catalogWritten: downloaded !== undefined, cacheSynced, injected, stale, ...(homeSettings ? { homeSettings } : {}) };
 }
 
 /**
@@ -1035,6 +1069,7 @@ export async function disconnectClient(
         if (!(error instanceof ClientLinkStateError)) throw error;
       }
       if (sidecarLinkId === connection.link.linkId) clearClientLinkState(connection.link.linkId);
+      try { clearHomeCodexSettingsRecord(); } catch { /* derived data; never fails a disconnect */ }
     }
     removeHubStateCache();
     requireDesktopResult(finishRemoteDesktopCleanup(held, receipt.owner));

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 } }
+      : {}),
   };
 }