@bitkyc08/opencodex 2.83.0 → 2.86.0

package/src/cli/status.ts

@@ -5,7 +5,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { codexAutoStartEnabled, getConfigPath, readConfigDiagnostics } from "../config";
 import { getPidPath, readPid, readRuntimePort, type RuntimePortState } from "../config/process-state";
 import { diagnoseCodexBundledPlugins, type CodexPluginsDiagnostic } from "../codex/plugins-doctor";
-import { findLiveProxy, probeHostname } from "../server/proxy-liveness";
+import { findLiveProxy, probeHostname, type LiveProxy } from "../server/proxy-liveness";
 import type { OcxConfig } from "../types";
 import { diagnoseService, serviceLogPath } from "../service";
 import { inspectDesktopSupervision } from "../service/desktop-supervision.mjs";
@@ -104,6 +104,16 @@ export type CliRemoteHubStatus = {
   truncated: boolean;
   /** The hub's own Claude Code toggle; a client cannot infer it from local config. */
   claudeCodeEnabled: boolean | null;
+  /**
+   * Present on a Remote Link Child (#6957): the peer is a Home reached over the link, not a hub,
+   * and every sentence names it that way. `codexSettings` lists the Home's Codex settings the
+   * last sync applied, or why the Child's local values are in effect.
+   */
+  link?: {
+    linkId: string;
+    homePhrase: string;
+    codexSettings: { source: "home"; fetchedAt: string; lines: string[] } | { source: "local"; reason: string };
+  };
 };
 
 export type CliStatusJson = {
@@ -152,6 +162,7 @@ export type CliStatusJson = {
   };
   connection: {
     state: "disconnected" | "connected" | "invalid" | "mismatched";
+    transport?: "hub" | "link";
     reason?: string;
     serverUrl?: string;
     managementUrl?: string;
@@ -321,8 +332,12 @@ export function selectStatusStartupHealth(
     if (evidence?.kind === "desktop" && evidence.runtimePid === livePid) {
       const local = fallback();
       const supervisor = local.desktop?.supervisor;
-      // The local probe runs later; it must still describe the same unowned process pair.
-      if (local.desktop?.owned === false && supervisor
+      // The local probe runs later; it must still describe the same process pair. macOS and Linux
+      // accept only an unowned pair. On Windows an older runtime never published a Desktop
+      // diagnostic, so a durable Desktop claim beside proven live parentage qualifies too.
+      const ownershipEligible = local.desktop?.owned === false
+        || (local.desktop?.owned === true && local.platform === "win32");
+      if (ownershipEligible && supervisor
         && supervisor.runtimePid === evidence.runtimePid && supervisor.supervisorPid === evidence.supervisorPid) {
         return { startup: local, startupSource: "local-supervision-override" };
       }
@@ -499,8 +514,8 @@ function boundHubStateToken(
  * degradation.
  */
 export async function collectRemoteHubStatus(
-  connection: Pick<ClientConnectionStatus, "state" | "serverUrl" | "apiKeyId" | "connectedAt">,
-  options: { fetchImpl?: typeof fetch; timeoutMs?: number; now?: number } = {},
+  connection: Pick<ClientConnectionStatus, "state" | "serverUrl" | "apiKeyId" | "connectedAt"> & { transport?: "hub" | "link" },
+  options: { fetchImpl?: typeof fetch; timeoutMs?: number; now?: number; findChild?: () => Promise<LiveProxy | null> } = {},
 ): Promise<CliRemoteHubStatus> {
   if (connection.state !== "connected" || !connection.serverUrl || !connection.apiKeyId || !connection.connectedAt) {
     return disconnectedRemoteHubStatus();
@@ -512,14 +527,50 @@ export async function collectRemoteHubStatus(
     connectedAt: connection.connectedAt,
   };
   const bound = boundHubStateToken(readClientConnectionState(), readServiceApiTokenState(), owner);
+  // Link credentials never go to the persisted tunnel URL from this CLI. Ask the local Child
+  // without a credential; its connection-bound relay authenticates the actual Home connection.
+  let fetchImpl = options.fetchImpl;
+  let allowNetwork = true;
+  let localRelayFetchImpl: typeof fetch | undefined;
+  if (connection.transport === "link") {
+    const live = await (options.findChild ?? findLiveProxy)();
+    const current = readClientConnectionState();
+    allowNetwork = live?.role === "client" && current.kind === "connected" && sameClientConnectionOwner(current.value, owner);
+    if (allowNetwork && live) {
+      const localOrigin = `http://${probeHostname(live.hostname)}:${live.port}`;
+      localRelayFetchImpl = ((_, init) => (options.fetchImpl ?? fetch)(localOrigin + "/v1/hub-state", {
+        method: "GET", redirect: "manual", signal: init?.signal, headers: { Accept: "application/json" },
+      })) as typeof fetch;
+    }
+  }
+  // #6957: the Home's name, the link id and the Codex settings the last sync applied.
+  const linkState = readClientConnectionState();
+  const linkConnection = connection.transport === "link" && linkState.kind === "connected" && linkState.value.transport === "link" && linkState.value.link
+    ? linkState.value : null;
+  const linkHome = linkConnection ? await import("../client/link-home") : null;
   const resolved = await resolveHubState({
     owner,
-    token: bound.token,
+    token: connection.transport === "link" ? null : bound.token,
+    ...(localRelayFetchImpl ? { localRelayFetchImpl } : {}),
     ...(bound.withheldReason ? { withheldTokenReason: bound.withheldReason } : {}),
-    ...(options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}),
+    ...(fetchImpl ? { fetchImpl } : {}),
+    allowNetwork,
+    ...(connection.transport === "link" ? { peer: "Home" as const } : {}),
     ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
     ...(options.now === undefined ? {} : { now: options.now }),
   });
+  let link: CliRemoteHubStatus["link"];
+  if (linkConnection && linkHome) {
+    const { describeHomeCodexSettings } = await import("../link/codex-settings");
+    const record = linkHome.readHomeCodexSettingsRecord(linkConnection.link!.linkId);
+    link = {
+      linkId: linkConnection.link!.linkId,
+      homePhrase: linkHome.linkHomePhrase(linkConnection),
+      codexSettings: record
+        ? { source: "home", fetchedAt: record.fetchedAt, lines: describeHomeCodexSettings(record.document.settings) }
+        : { source: "local", reason: "no Home settings recorded yet; run: ocx sync" },
+    };
+  }
   return {
     connected: true,
     // The hub's own advertised origin when it publishes one; otherwise the URL this client
@@ -535,6 +586,7 @@ export async function collectRemoteHubStatus(
     subagentModels: resolved.state?.subagentModels ?? [],
     truncated: resolved.state?.truncated === true,
     claudeCodeEnabled: resolved.state ? resolved.state.claudeCode.enabled : null,
+    ...(link ? { link } : {}),
   };
 }
 
@@ -546,8 +598,24 @@ export async function collectRemoteHubStatus(
  * A buried `Remote hub: connected (<url>)` line — which is all this report had — does not stop
  * that, as #4236 demonstrated.
  */
-export function remoteHubBannerLine(remoteHub: CliRemoteHubStatus): string | null {
+export function remoteHubBannerLine(remoteHub: CliRemoteHubStatus, transport?: "hub" | "link"): string | null {
   if (!remoteHub.connected) return null;
+  if (remoteHub.link) {
+    const peer = `${remoteHub.link.homePhrase} over Remote Link (${remoteHub.link.linkId})`;
+    if (remoteHub.stateSource === "unavailable") {
+      return `⚠️  ${peer}: state unavailable (${remoteHub.reason ?? "unknown reason"}) — provider and login lines below are LOCAL and do not describe the Home.`;
+    }
+    const cached = remoteHub.stateSource === "cache"
+      ? ` — cached ${remoteHub.ageSeconds ?? "?"}s ago (${remoteHub.reason ?? "live read failed"})`
+      : "";
+    return `🔗 State from ${peer}${cached}: provider credentials, logins and delegable models below are the Home's, not this machine's.`;
+  }
+  if (transport === "link") {
+    const origin = remoteHub.origin ?? "unknown";
+    return remoteHub.stateSource === "unavailable"
+      ? `🔗 Remote Link Home ${origin}: provider credentials and routing come from Home. State unavailable (${remoteHub.reason ?? "unknown reason"}).`
+      : `🔗 State from Remote Link Home ${origin}${remoteHub.stateSource === "cache" ? " (cached)" : ""}: provider credentials, logins and models below come from Home.`;
+  }
   const origin = remoteHub.origin ?? "the hub";
   if (remoteHub.stateSource === "unavailable") {
     return `⚠️  Hub ${origin}: state unavailable (${remoteHub.reason ?? "unknown reason"}) — provider and login lines below are LOCAL and do not describe the hub.`;
@@ -562,32 +630,47 @@ export function remoteHubBannerLine(remoteHub: CliRemoteHubStatus): string | nul
  * The hub-sourced provider/login/model block, owned here so the sentences are testable without
  * spawning the CLI. Indentation is the caller's. Empty when nothing true is known.
  */
-export function remoteHubStatusLines(remoteHub: CliRemoteHubStatus): string[] {
-  if (!remoteHub.connected || remoteHub.stateSource === "unavailable") return [];
-  const origin = remoteHub.origin ?? "hub";
+export function remoteHubStatusLines(remoteHub: CliRemoteHubStatus, transport?: "hub" | "link"): string[] {
+  if (!remoteHub.connected) return [];
+  const settings = remoteHub.link ? linkCodexSettingsLines(remoteHub.link) : [];
+  if (remoteHub.stateSource === "unavailable") return settings;
+  const isLink = Boolean(remoteHub.link) || transport === "link";
+  const peer = remoteHub.link?.homePhrase ?? `${isLink ? "Home" : "hub"} ${remoteHub.origin ?? (isLink ? "Home" : "hub")}`;
+  const subject = isLink ? "the Home" : "the hub";
   const lines = [
-    `OAuth logins (hub ${origin}):`,
+    `OAuth logins (${peer}):`,
     ...(remoteHub.oauth.length === 0
-      ? ["  (the hub reported no OAuth providers)"]
+      ? [`  (${subject} reported no OAuth providers)`]
       : remoteHub.oauth.map(entry => `  ${entry.provider.padEnd(10)} ${entry.loggedIn ? "✓ logged in" : "✗ not logged in"}`)),
-    `Providers (hub ${origin}):`,
+    `Providers (${peer}):`,
     ...(remoteHub.providers.length === 0
-      ? ["  (the hub reported no providers)"]
+      ? [`  (${subject} reported no providers)`]
       : remoteHub.providers.map(provider => {
         // `authMode` is what keeps "no API key" from reading as "not configured": an `oauth`
         // provider legitimately has no key and is still fully usable.
         const credential = provider.hasCredential ? "credential stored" : `no API key (authMode ${provider.authMode ?? "key"})`;
         return `  ${provider.name.padEnd(10)} ${provider.adapter} — ${credential}${provider.disabled ? ", disabled" : ""}`;
       })),
-    `Delegable models (hub ${origin}): ${remoteHub.subagentModels.length === 0 ? "none" : remoteHub.subagentModels.join(", ")}`,
+    `Delegable models (${peer}): ${remoteHub.subagentModels.length === 0 ? "none" : remoteHub.subagentModels.join(", ")}`,
   ];
-  if (remoteHub.hubVersion) lines.push(`Hub version: ${remoteHub.hubVersion}`);
+  if (remoteHub.hubVersion) lines.push(`${remoteHub.link ? "Home" : "Hub"} version: ${remoteHub.hubVersion}`);
   // The hub told us its own lists are a prefix. Saying nothing here would make this report claim
   // completeness it does not have — the same shape of confident-and-wrong answer as #4236.
   if (remoteHub.truncated) {
-    lines.push("  (the hub truncated this state to fit its response caps; some rows are not listed)");
+    lines.push(`  (${subject} truncated this state to fit its response caps; some rows are not listed)`);
   }
-  return lines;
+  return [...lines, ...settings];
+}
+
+/** Which Codex settings the last sync took from the Home (#6957). */
+export function linkCodexSettingsLines(link: NonNullable<CliRemoteHubStatus["link"]>): string[] {
+  if (link.codexSettings.source === "local") {
+    return [`Codex settings: this machine's local values (${link.codexSettings.reason})`];
+  }
+  return [
+    `Codex settings from ${link.homePhrase} (applied ${link.codexSettings.fetchedAt}):`,
+    ...link.codexSettings.lines.map(line => `  ${line}`),
+  ];
 }
 
 export function selectListenTarget(
@@ -760,7 +843,7 @@ export async function collectStatus(options: { mainAccountPolicy?: boolean } = {
   // Asked before the local probes below so a connected client's report is hub-sourced from its
   // first line. Bounded and failure-tolerant: an offline hub degrades the remoteHub block, it
   // does not fail `ocx status`.
-  const remoteHub = await collectRemoteHubStatus(clientConnection);
+  const remoteHub = await collectRemoteHubStatus({ ...clientConnection, transport: config.client?.transport });
   // Prefer identity-verified liveness (runtime-port + /healthz) over ocx.pid alone (#618).
   // Pass the already-resolved diagnostics config so findLiveProxy does not re-load and
   // warn on malformed config.json (status --json must stay stderr-clean).
@@ -960,6 +1043,7 @@ export async function collectStatus(options: { mainAccountPolicy?: boolean } = {
       },
       connection: {
         state: clientConnection.state,
+        ...(config.client?.transport ? { transport: config.client.transport } : {}),
         ...(clientConnection.reason ? { reason: clientConnection.reason } : {}),
         ...(clientConnection.serverUrl ? { serverUrl: clientConnection.serverUrl } : {}),
         ...(clientConnection.managementUrl ? { managementUrl: clientConnection.managementUrl } : {}),

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);