@bitkyc08/opencodex 2.83.0 → 2.84.0

package/src/cli/link-enrollment.ts

@@ -0,0 +1,96 @@
+import { createInterface } from "node:readline/promises";
+import { assertSshAlias } from "../link/ssh-argv";
+import { CliUsageError, RuntimeApiError, runtimeBaseUrl, rejectArgs, takeJsonFlag, takeOption, printData } from "./runtime-api";
+import type { LinkCliDeps } from "./link";
+
+const FINGERPRINT = /^SHA256:[A-Za-z0-9+/]{16,88}={0,2}$/;
+const ENROLLMENT_DEADLINE_MS = 360_000;
+const PHASES: Record<string, string> = {
+  remote_port_failed: "remote port selection", remote_port_timeout: "remote port selection",
+  child_preflight_failed: "Child preflight", child_preflight_timeout: "Child preflight",
+  child_restart_unsupported: "Child restart preflight", child_curl_missing: "Child curl preflight",
+  home_setup_failed: "Home setup", home_setup_timeout: "Home setup",
+  remote_connect_failed: "Child enrollment", remote_connect_timeout: "Child enrollment",
+  child_restart_failed: "Child restart", child_restart_timeout: "Child restart",
+  child_relay_failed: "Child relay verification", child_relay_timeout: "Child relay verification",
+  child_runtime_not_client: "Child runtime role verification",
+  remote_platform_unsupported: "remote platform verification", remote_ocx_missing: "remote OpenCodex discovery",
+};
+const RECOVERY = "Run ocx disconnect and ocx restart on the Child before retrying.";
+type LinkRequest = <T>(path: string, init: RequestInit, deps: LinkCliDeps) => Promise<T>;
+
+function record(value: unknown): value is Record<string, unknown> { return value !== null && typeof value === "object" && !Array.isArray(value); }
+function offered(value: unknown): { alias: string; fingerprint: string; keyType: string; ocxVersion: string } {
+  if (!record(value) || Object.keys(value).sort().join(",") !== "alias,fingerprint,keyType,ocxVersion"
+    || typeof value.alias !== "string" || typeof value.fingerprint !== "string" || !FINGERPRINT.test(value.fingerprint)
+    || typeof value.keyType !== "string" || !/^[A-Za-z0-9@._+-]{1,64}$/.test(value.keyType)) throw new Error("Invalid host probe response");
+  if (typeof value.ocxVersion !== "string" || !/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.+-]{1,128})?$/.test(value.ocxVersion)) throw new Error("Invalid host version response");
+  return { alias: value.alias, fingerprint: value.fingerprint, keyType: value.keyType, ocxVersion: value.ocxVersion };
+}
+
+export async function runLinkEnrollment(command: "probe" | "add", args: string[], deps: LinkCliDeps, request: LinkRequest, usage: string): Promise<void> {
+  const wantsJson = takeJsonFlag(args);
+  const expected = takeOption(args, "--expect-fingerprint");
+  const alias = args.shift();
+  if (!alias) throw new CliUsageError(command + " requires an SSH alias", usage);
+  try { assertSshAlias(alias); } catch { throw new CliUsageError("Invalid SSH alias", usage); }
+  rejectArgs(args, usage);
+  if (command === "probe" && expected !== undefined) throw new CliUsageError("--expect-fingerprint is only for link add", usage);
+  if (expected !== undefined && !FINGERPRINT.test(expected)) throw new CliUsageError("Expected a SHA256 SSH fingerprint", usage);
+  if (command === "add" && !expected && !(deps.stdinImpl ?? process.stdin).isTTY) {
+    throw new CliUsageError("Non-interactive link add requires --expect-fingerprint", usage);
+  }
+  const timeout = deps.enrollmentTimeoutMs ?? ENROLLMENT_DEADLINE_MS;
+  if (!Number.isFinite(timeout) || timeout < 1 || timeout > ENROLLMENT_DEADLINE_MS) throw new Error("Invalid link enrollment deadline");
+  const controller = new AbortController();
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const expiry = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => { controller.abort(); reject(new Error("Link enrollment timed out; its outcome is uncertain. Run ocx link status on the Home and ocx connect status on the Child before retrying.")); }, timeout);
+  });
+  let boundDeps = deps;
+  const post = async <T>(path: string, body: unknown): Promise<T> => {
+    controller.signal.throwIfAborted();
+    const result = await request<T>(path, { method: "POST", redirect: "error", signal: controller.signal, headers: { "content-type": "application/json" }, body: JSON.stringify(body) }, boundDeps);
+    controller.signal.throwIfAborted();
+    return result;
+  };
+  let rl: ReturnType<typeof createInterface> | undefined;
+  const work = async () => {
+    boundDeps = { ...deps, baseUrl: await runtimeBaseUrl(deps) };
+    controller.signal.throwIfAborted();
+    const probe = offered(await post<unknown>("/api/link/probe", { alias, includeVersion: true }));
+    if (probe.alias !== alias) throw new Error("Host probe alias did not match");
+    if (command === "probe") { printData(probe, wantsJson, [probe.alias + " " + probe.keyType + " " + probe.fingerprint + " opencodex " + probe.ocxVersion]); return; }
+    if (expected && expected !== probe.fingerprint) throw new CliUsageError("The offered host fingerprint does not match --expect-fingerprint");
+    if (!expected) {
+      let approved: boolean;
+      if (deps.confirmFingerprint) approved = await deps.confirmFingerprint(probe);
+      else {
+        rl = createInterface({ input: deps.stdinImpl ?? process.stdin, output: process.stderr });
+        approved = (await rl.question("Confirm " + alias + " " + probe.keyType + " " + probe.fingerprint + " opencodex " + probe.ocxVersion + " (type yes): ", { signal: controller.signal })).trim() === "yes";
+      }
+      controller.signal.throwIfAborted();
+      if (!approved) throw new CliUsageError("Host fingerprint was not confirmed");
+    }
+    const confirm = await post<unknown>("/api/link/confirm-host", { alias, fingerprint: probe.fingerprint });
+    if (!record(confirm) || Object.keys(confirm).sort().join(",") !== "alias,fingerprint,ocxVersion" || confirm.alias !== alias || confirm.fingerprint !== probe.fingerprint
+      || typeof confirm.ocxVersion !== "string" || !/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.+-]{1,128})?$/.test(confirm.ocxVersion)) throw new Error("Invalid host confirmation response");
+    const result = await post<unknown>("/api/link/apply", { alias, fingerprint: probe.fingerprint });
+    if (!record(result) || Object.keys(result).join(",") !== "linkId" || typeof result.linkId !== "string" || !/^lnk_[0-9a-f]{16}$/.test(result.linkId)) throw new Error("Invalid link apply response");
+    printData({ linkId: result.linkId, alias, state: "connected", childRole: "client" }, wantsJson, ["Connected " + alias + " as a Child (" + result.linkId + ")."]);
+  };
+  try { await Promise.race([work(), expiry]); }
+  catch (error) {
+    if (error instanceof RuntimeApiError && record(error.body)) {
+      const code = record(error.body.error) ? error.body.error.code : undefined;
+      const phase = typeof code === "string" && Object.hasOwn(PHASES, code) ? PHASES[code] : undefined;
+      const message = phase ? "Remote Link failed during " + phase : error.message;
+      if (phase || error.body.residual === true) throw new Error(message + (error.body.residual === true ? ". " + RECOVERY : ""));
+    }
+    throw error;
+  } finally {
+    if (timer) clearTimeout(timer);
+    controller.abort();
+    rl?.close();
+  }
+}

package/src/cli/link.ts

@@ -1,3 +1,8 @@
+import { clientLinkStatusIdentity } from "../client/link-status";
+import { clientLinkTunnelStatus } from "../client/link-tunnel";
+import { loadConfig } from "../config";
+import { projectLinkStatus, type ClientLinkIdentity, type LinkStatusConfig, type LinkStatusDto } from "../link/status-projection";
+import { runLinkEnrollment } from "./link-enrollment";
 import { assertSshAlias } from "../link/ssh-argv";
 import { linkStorePath } from "../link/paths";
 import { isLinkPort } from "../link/ports";
@@ -19,10 +24,13 @@ import {
 } from "./runtime-api";
 
 export const LINK_USAGE = `Usage:
+  ocx link probe <alias> [--json]
+  ocx link add <alias> [--expect-fingerprint SHA256:…] [--json]
   ocx link port [--json]
   ocx link issue --alias <alias> --tunnel-port <port> [--json]
   ocx link status [--json]
   ocx link revoke --link-id <id> [--force --yes] [--json]
+  ocx link reconnect --link-id <id> [--json]
 
 Forced revoke skips remote cleanup. Run ocx disconnect on the remote client.`;
 
@@ -57,7 +65,13 @@ export interface LinkIssuePayload {
 }
 
 export interface LinkCliDeps extends RuntimeApiDeps {
+  /** Test seam can shorten, never extend, the whole enrollment deadline. */
+  enrollmentTimeoutMs?: number;
   choosePort?: () => Promise<number>;
+  readConfig?: () => LinkStatusConfig;
+  readClientLinkIdentity?: (linkId: string) => ClientLinkIdentity | null;
+  readChildStatus?: () => LinkStatusDto["child"];
+  confirmFingerprint?: (host: { alias: string; fingerprint: string; keyType: string }) => Promise<boolean>;
   readStore?: () => LinkStore;
   readAdminToken?: () => string | null;
 }
@@ -172,25 +186,12 @@ function validateRevoke(value: unknown, expectedLinkId: string): void {
   if (value.linkId !== expectedLinkId) throw new Error("invalid link API response: revoke link id");
 }
 
-function localStatus(store: LinkStore): LinkStatusPayload {
-  const hasLinks = store.links.length > 0;
-  return {
-    role: hasLinks ? "home" : "standalone",
-    listener: {
-      state: hasLinks && store.listenerPort !== null ? "listening" : "off",
-      port: hasLinks ? store.listenerPort : null,
-    },
-    links: store.links.map(link => ({
-      id: link.id,
-      alias: link.alias,
-      direction: link.direction,
-      state: "idle",
-      since: link.createdAt,
-      reason: null,
-      tunnelPort: link.tunnelPort,
-    })),
-    child: null,
-  };
+function localStatus(store: LinkStore, deps: LinkCliDeps): LinkStatusPayload {
+  const config = (deps.readConfig ?? loadConfig)();
+  const identity = config.client?.transport === "link" && config.client.link
+    ? (deps.readClientLinkIdentity ?? clientLinkStatusIdentity)(config.client.link.linkId) : null;
+  return projectLinkStatus(store, [], { state: store.links.length > 0 && store.listenerPort !== null ? "listening" : "off", port: store.links.length > 0 ? store.listenerPort : null },
+    config, { version: 1, entries: {} }, (deps.readChildStatus ?? clientLinkTunnelStatus)(), identity);
 }
 
 async function linkRequest<T>(path: string, init: RequestInit, deps: LinkCliDeps): Promise<T> {
@@ -211,10 +212,10 @@ async function linkRequest<T>(path: string, init: RequestInit, deps: LinkCliDeps
   }
 }
 
-function errorCodeBody(body: unknown): { error: { code: string } } | null {
+function errorCodeBody(body: unknown): { error: { code: string }; residual?: true } | null {
   if (!isRecord(body) || !isRecord(body.error)) return null;
   const code = body.error.code;
-  return typeof code === "string" && /^[a-z_]{1,64}$/.test(code) ? { error: { code } } : null;
+  return typeof code === "string" && /^[a-z_]{1,64}$/.test(code) ? { error: { code }, ...(body.residual === true ? { residual: true as const } : {}) } : null;
 }
 
 async function runPort(args: string[], deps: LinkCliDeps): Promise<void> {
@@ -252,7 +253,7 @@ async function runStatus(args: string[], deps: LinkCliDeps): Promise<void> {
   } catch (error) {
     if (!deps.baseUrl && error instanceof RuntimeApiError && error.status === 503) {
       const store = (deps.readStore ?? (() => readLinkStore(linkStorePath())))();
-      console.log(JSON.stringify(localStatus(store)));
+      console.log(JSON.stringify(localStatus(store, deps)));
       return;
     }
     throw error;
@@ -303,14 +304,28 @@ async function runRevoke(args: string[], deps: LinkCliDeps): Promise<void> {
   console.log(JSON.stringify({ linkId }));
 }
 
+async function runReconnect(args: string[], deps: LinkCliDeps): Promise<void> {
+  takeJsonFlag(args);
+  const linkId = takeOption(args, "--link-id");
+  if (!linkId || !LINK_ID.test(linkId)) throw new CliUsageError("reconnect requires a valid --link-id", LINK_USAGE);
+  rejectArgs(args, LINK_USAGE);
+  const response = await linkRequest<unknown>(`/api/link/${encodeURIComponent(linkId)}/reconnect`, { method: "POST" }, deps);
+  if (!isRecord(response)) throw new Error("invalid link API response: reconnect object");
+  assertExactKeys(response, ["linkId"], "reconnect");
+  if (response.linkId !== linkId) throw new Error("invalid link API response: reconnect link id");
+  console.log(JSON.stringify({ linkId }));
+}
+
 export async function runLinkCommand(rawArgs: string[], deps: LinkCliDeps = {}): Promise<number> {
   return runCliAction(async () => {
     const args = [...rawArgs];
     const command = args.shift();
-    if (command === "port") await runPort(args, deps);
+    if (command === "probe" || command === "add") await runLinkEnrollment(command, args, deps, linkRequest, LINK_USAGE);
+    else if (command === "port") await runPort(args, deps);
     else if (command === "issue") await runIssue(args, deps);
     else if (command === "status") await runStatus(args, deps);
     else if (command === "revoke") await runRevoke(args, deps);
-    else throw new CliUsageError("link requires one of: port, issue, status, revoke", LINK_USAGE);
+    else if (command === "reconnect") await runReconnect(args, deps);
+    else throw new CliUsageError("link requires one of: probe, add, port, issue, status, revoke, reconnect", LINK_USAGE);
   });
 }

package/src/cli/observe-stream.ts

@@ -89,7 +89,12 @@ export async function withObserveStream(
       // Snapshot recovery comes from our observed target, never arbitrary transport text.
       if (context.kind === "snapshot") {
         if (!found) throw new ObservationError("Proxy is not running. Start it with: ocx start");
-        if (found.role === "client") throw new ObservationError("This listener runs in the client role and has no management API. Run this command on its serving hub, or open the hub dashboard.");
+        if (found.role === "client") {
+          const { readLinkChildContext, linkChildRefusal } = await import("./link-child");
+          const link = readLinkChildContext();
+          throw new ObservationError(link ? linkChildRefusal(link)
+            : "This listener runs in the client role and has no management API. Run this command on its serving hub, or open the hub dashboard.");
+        }
       }
       return found;
     } }), signal);

package/src/cli/observe.ts

@@ -113,8 +113,12 @@ async function logs(argv: string[], deps: ObserveStreamDeps): Promise<number> {
     return followLogs({ query: new URLSearchParams(query(params)), limit, jsonl: wantsJsonl, events: wantsEvents, formatRow: formatLog }, deps);
   }
   const data = await runtimeRequest(`/api/logs${query(params)}`, {}, deps);
+  const rows = logRows(data);
+  if (!wantsJson && !wantsJsonl && rows.length === 0 && [provider, model, status, conversationId, account].some(Boolean)) {
+    console.log("No log entry matched the filters.");
+  }
   if (wantsJson) printData(data, true);
-  else for (const row of logRows(data)) {
+  else for (const row of rows) {
     if (wantsJsonl) console.log(JSON.stringify(row));
     else console.log(formatLog(row));
   }
@@ -206,8 +210,12 @@ async function usage(argv: string[], deps: RuntimeApiDeps): Promise<void> {
     if (token.kind !== "present" || token.fingerprint !== connection.value.tokenFingerprint) {
       throw new Error("Client usage unavailable: the enrolled data key is missing or changed; repair the client connection");
     }
+    // A Remote Link Child sends this read through the connection-bound link relay (#6957).
+    const link = connection.value.transport === "link" && connection.value.link;
+    const peerFetch = deps.fetchImpl
+      ?? (link ? (await import("../client/link-home")).linkBoundFetch(connection.value, token.token) : undefined);
     result = await fetchHubUsage(connection.value.serverUrl, token.token, new URLSearchParams(suffix), {
-      fetchImpl: deps.fetchImpl, timeoutMs: 60_000,
+      fetchImpl: peerFetch, timeoutMs: 60_000, ...(link ? { peer: "Home" as const } : {}),
     });
     const current = readClientConnectionState();
     const currentToken = readServiceApiTokenState();

package/src/cli/provider.ts

@@ -584,8 +584,19 @@ export async function handleProviderCommand(args: string[], deps: ProviderComman
     return;
   }
 
+  // #6957: a link Child's local providers are inactive; changing them is refused like any other
+  // provider change, which belongs to the Home.
+  if (sub === "add" || sub === "remove" || sub === "set-default") {
+    const refusal = (await import("./link-child")).linkChildProviderChangeRefusal(`ocx provider ${sub}`);
+    if (refusal) {
+      console.error(refusal);
+      process.exitCode = 1;
+      return;
+    }
+  }
   switch (sub) {
     case "list":
+      await (await import("./link-child")).printLinkChildLocalNotice("The providers");
       handleList(subArgs);
       break;
     case "add":
@@ -595,6 +606,7 @@ export async function handleProviderCommand(args: string[], deps: ProviderComman
       handleRemove(subArgs);
       break;
     case "show":
+      await (await import("./link-child")).printLinkChildLocalNotice("The provider settings");
       handleShow(subArgs);
       break;
     case "set-default":

package/src/cli/registry.ts

@@ -144,14 +144,15 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
   },
   {
     name: "link",
-    usage: "ocx link <port|issue|status|revoke>",
+    usage: "ocx link <port|issue|status|revoke|reconnect>",
     summary: "Allocate and manage a loopback remote home link.",
     details: [
       "Port: ocx link port [--json]",
       "Issue: ocx link issue --alias <alias> --tunnel-port <port> [--json]",
       "Status: ocx link status [--json]",
       "Revoke: ocx link revoke --link-id <id> [--force --yes] [--json]",
-      "Issue, status, and revoke use the running proxy's loopback management API and admin token.",
+      "Reconnect: ocx link reconnect --link-id <id> [--json]",
+      "Issue, status, revoke, and reconnect use the running proxy's loopback management API and admin token.",
     ],
   },
   {
@@ -245,8 +246,8 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
   },
   {
     name: "hub",
-    usage: "ocx hub invite [--json] [--data-url <origin>] [--management-url <origin>] [--clients codex,claude]",
-    summary: "Hub-side commands. `invite` prints a ready-to-run `ocx connect` line for one more machine.",
+    usage: "ocx hub invite [--json] [--data-url <origin>] [--management-url <origin>] [--clients codex,claude]\n  ocx hub disable [--revoke-clients --client-key <id> ...] [--json]",
+    summary: "Invite another machine, or disable hub mode in one validated config write.",
     details: [
       "Topology: a hub serves ONE port. Remote machines dial `hostname:port` with their own per-client",
       "key; the hub's own local processes dial `127.0.0.1:<same port>` with no credential, through the",

package/src/cli/runtime-api.ts

@@ -12,6 +12,7 @@
 import { findLiveProxy, probeHostname, type LivenessIo, type LiveProxy } from "../server/proxy-liveness";
 import { runningProxyUpdateHeaders } from "../oauth/login-cli";
 import { redactSecretArgs } from "./secret-args";
+import type { LinkHomeDeps } from "../client/link-home";
 export { redactSecretArgs };
 
 export type CliStdin = NodeJS.ReadableStream & { isTTY?: boolean; readableEnded?: boolean };
@@ -28,6 +29,8 @@ export interface RuntimeApiDeps {
   stdinSignal?: AbortSignal;
   /** Optional proxy liveness probe injection for commands that check or fall back around live runtime state. */
   findLiveProxy?: (io?: LivenessIo) => Promise<LiveProxy | null>;
+  /** Remote Link Child: how allowlisted reads reach the Home (#6957). */
+  linkHome?: LinkHomeDeps;
 }
 
 export class CliUsageError extends Error {
@@ -45,7 +48,7 @@ export class RuntimeApiError extends Error {
     readonly status: number,
     readonly body: unknown,
     /** Local discovery refusals occur before the management request is sent. */
-    readonly code?: "proxy_not_running" | "client_role_management_unavailable",
+    readonly code?: "proxy_not_running" | "client_role_management_unavailable" | "link_child_management_unavailable",
   ) {
     super(message);
     this.name = "RuntimeApiError";
@@ -83,6 +86,10 @@ export async function runtimeBaseUrl(deps: RuntimeApiDeps = {}): Promise<string>
   // this costs no extra request. Only the client role is refused: an absent role is a
   // standalone or hub proxy (or a legacy body that predates the field), and both serve /api/*.
   if (live.role === "client") {
+    // A Remote Link Child has no relay transport to point at; it names its Home instead (#6957).
+    const { readLinkChildContext, linkChildRefusal } = await import("./link-child");
+    const link = readLinkChildContext();
+    if (link) throw new RuntimeApiError(linkChildRefusal(link), 503, null, "link_child_management_unavailable");
     throw new RuntimeApiError(clientRoleManagementRefusal(live.port), 503, null, "client_role_management_unavailable");
   }
   return `http://${probeHostname(live.hostname)}:${live.port}`;
@@ -180,7 +187,25 @@ export async function runtimeRequest<T = unknown>(
   init: RequestInit = {},
   deps: RuntimeApiDeps = {},
 ): Promise<T> {
-  const baseUrl = await runtimeBaseUrl(deps);
+  let baseUrl: string;
+  try {
+    baseUrl = await runtimeBaseUrl(deps);
+  } catch (error) {
+    if (!(error instanceof RuntimeApiError) || error.code !== "link_child_management_unavailable") throw error;
+    // #6957: on a Remote Link Child an allowlisted read is answered by the Home over the link;
+    // every other request is refused with the operation named, before anything is sent.
+    const method = (init.method ?? "GET").toUpperCase();
+    const { readLinkChildContext, linkChildReadable, linkChildRefusal, readLinkHomeJson } = await import("./link-child");
+    const link = readLinkChildContext();
+    if (!link) throw error;
+    const pathname = new URL(path.startsWith("/") ? path : `/${path}`, "http://cli.invalid").pathname;
+    if (!linkChildReadable(method, path)) {
+      throw new RuntimeApiError(linkChildRefusal(link, `${method} ${pathname}`), 503, null, "link_child_management_unavailable");
+    }
+    const { status, body } = await readLinkHomeJson(link, path, deps.linkHome);
+    if (status < 200 || status >= 300) throw new RuntimeApiError(responseMessage(body, status), status, body);
+    return body as T;
+  }
   const headers = runningProxyUpdateHeaders();
   for (const [key, value] of new Headers(init.headers).entries()) headers.set(key, value);
   const fetchImpl = deps.fetchImpl ?? fetch;

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