@bitkyc08/opencodex 2.90.0 → 2.92.0

package/src/link/diagnostics.ts

@@ -0,0 +1,193 @@
+import { constants } from "node:fs";
+import { chmod, lstat, mkdir, open, rename, unlink } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { assertNotRealHomeUnderTest } from "../lib/test-home-guard";
+import { hardenSecretDirAsync, hardenSecretPathAsync, reattributeHardenedSecretPath, windowsSecretAclApplies } from "../lib/windows-secret-acl";
+import { linkDir } from "./paths";
+import type { TunnelState } from "./tunnel-state";
+
+export type LinkDiagnosticRecord = {
+  event: "owner_lookup" | "relay_retry" | "relay_failure" | "relay_recovered" | "tunnel_transition";
+  outcome: "match" | "mismatch" | "lookup_error" | "deadline" | "stale" | "unavailable"
+    | "identity_unknown" | "identity_mismatch" | "auth_timeout" | "auth_failed"
+    | "transport_error" | "client_abort" | "header_timeout" | "recovered"
+    // tunnel_transition: the Home's -R tunnel changed state, and why (src/link/tunnel-history.ts).
+    | "connected" | "spawned" | "stopped" | "auth" | "hostkey" | "forward" | "remote_forward_conflict"
+    | "timeout" | "network" | "unknown" | "spawn_failed" | "listener_unavailable";
+  requestId?: string;
+  checkId?: string;
+  generation?: number;
+  state?: string;
+  previousState?: string;
+  elapsedMs?: number;
+  attempt?: number;
+  tunnelPort?: number;
+  retryAfterMs?: number;
+};
+export type LinkDiagnosticSink = (record: LinkDiagnosticRecord) => void;
+
+const EVENTS = new Set(["owner_lookup", "relay_retry", "relay_failure", "relay_recovered", "tunnel_transition"]);
+const OUTCOMES = new Set([
+  "match", "mismatch", "lookup_error", "deadline", "stale", "unavailable", "identity_unknown",
+  "identity_mismatch", "auth_timeout", "auth_failed", "transport_error", "client_abort", "header_timeout", "recovered",
+  "connected", "spawned", "stopped", "auth", "hostkey", "forward", "remote_forward_conflict", "timeout", "network",
+  "unknown", "spawn_failed", "listener_unavailable",
+]);
+const STATES = new Set<TunnelState["kind"]>(["idle", "connecting", "connected", "reconnecting", "failed"]);
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const MAX_BYTES = 256 * 1024;
+
+/** Copy only bounded enum, UUID and numeric fields; unknown fields never reach disk. */
+function metadata(record: LinkDiagnosticRecord): LinkDiagnosticRecord | null {
+  if (!record) return null;
+  const { event, outcome, state, previousState } = record;
+  if (!EVENTS.has(event) || !OUTCOMES.has(outcome)) return null;
+  const result: LinkDiagnosticRecord = { event, outcome };
+  for (const key of ["requestId", "checkId"] as const) {
+    const value = record[key];
+    if (typeof value === "string" && value.length === 36 && UUID.test(value)) result[key] = value;
+  }
+  if (typeof state === "string" && STATES.has(state as TunnelState["kind"])) result.state = state;
+  if (typeof previousState === "string" && STATES.has(previousState as TunnelState["kind"])) result.previousState = previousState;
+  for (const key of ["generation", "elapsedMs", "attempt", "retryAfterMs"] as const) {
+    const value = record[key];
+    if (typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= Number.MAX_SAFE_INTEGER
+      && (key === "elapsedMs" || key === "retryAfterMs" || Number.isSafeInteger(value))) result[key] = value;
+  }
+  const { tunnelPort } = record;
+  if (typeof tunnelPort === "number" && Number.isInteger(tunnelPort) && tunnelPort >= 1 && tunnelPort <= 65_535) result.tunnelPort = tunnelPort;
+  return result;
+}
+
+/** Append through a private no-follow handle, keeping at most one 256 KiB rotated backup. */
+async function append(dir: string, line: string): Promise<void> {
+  assertNotRealHomeUnderTest(dirname(dir));
+  await mkdir(dir, { recursive: true, mode: 0o700 });
+  const directory = await lstat(dir);
+  if (!directory.isDirectory() || directory.isSymbolicLink()) return;
+  const windows = windowsSecretAclApplies();
+  if (windows) await hardenSecretDirAsync(dir, { required: true });
+  else await chmod(dir, 0o700);
+  const path = join(dir, "diagnostics.jsonl");
+  const backup = `${path}.1`;
+  let file: Awaited<ReturnType<typeof open>> | undefined;
+  try {
+    // No read of log contents, and no following a file symlink or writing to a pipe.
+    const flags = constants.O_WRONLY | constants.O_APPEND | constants.O_CREAT | constants.O_NOFOLLOW | constants.O_NONBLOCK;
+    file = await open(path, flags, 0o600);
+    const current = await file.stat();
+    if (!current.isFile() || current.nlink !== 1) return;
+    if (windows) await hardenSecretPathAsync(path, { required: true });
+    else await file.chmod(0o600);
+    const previous = await lstat(backup).catch(error => {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+      return null;
+    });
+    if (previous) {
+      if (!previous.isFile() || previous.isSymbolicLink() || previous.nlink !== 1) return;
+      if (previous.size > MAX_BYTES) await unlink(backup);
+      else if (windows) await hardenSecretPathAsync(backup, { required: true });
+      else await chmod(backup, 0o600);
+    }
+    if (current.size > MAX_BYTES) await file.truncate(0);
+    else if (current.size + Buffer.byteLength(line) > MAX_BYTES) {
+      await file.close();
+      file = undefined;
+      await rename(path, backup);
+      file = await open(path, flags, 0o600);
+      const fresh = await file.stat();
+      if (!fresh.isFile() || fresh.nlink !== 1 || fresh.size + Buffer.byteLength(line) > MAX_BYTES) return;
+      if (windows) await hardenSecretPathAsync(path, { required: true });
+      else await file.chmod(0o600);
+    }
+    await file.write(line);
+    if (windows) {
+      const written = await file.stat({ bigint: true });
+      const named = await lstat(path, { bigint: true });
+      if (!named.isSymbolicLink() && named.dev === written.dev && named.ino === written.ino) {
+        // Windows publishes content-write ChangeTime on close; retain only the same object's ACL memo.
+        await file.close();
+        file = undefined;
+        reattributeHardenedSecretPath(path);
+      }
+    }
+  } finally {
+    await file?.close();
+  }
+}
+
+/**
+ * Create a best-effort metadata sink with one-second event/outcome buckets and a bounded queue.
+ * File and ACL work starts on the first eligible record and never blocks admission. flush() waits
+ * at most one second; its timeout does not cancel the writer or guarantee durable storage.
+ */
+export function createLinkDiagnosticSink(
+  { configDir, now = Date.now }: { configDir?: string; now?: () => number } = {},
+): LinkDiagnosticSink & { flush: (timeoutMs?: number) => Promise<void> } {
+  // At most 56 buckets; correlation IDs never become keys or retained memory.
+  const buckets = new Map<string, { at: number; suppressed: number }>();
+  const queue: Array<{ dir: string; line: string }> = [];
+  let flight: Promise<void> | undefined;
+  const drain = async () => {
+    while (queue.length) {
+      const record = queue.shift()!;
+      try { await append(record.dir, record.line); } catch { /* Best effort; never publish raw errors. */ }
+    }
+  };
+  const startWriter = () => {
+    if (flight) return;
+    flight = drain().finally(() => {
+      flight = undefined;
+      if (queue.length) startWriter();
+    });
+  };
+  const sink: LinkDiagnosticSink = record => {
+    try {
+      const safe = metadata(record);
+      if (!safe) return;
+      const at = now();
+      if (!Number.isSafeInteger(at) || at < 0) return;
+      const key = `${safe.event}:${safe.outcome}`;
+      const bucket = buckets.get(key);
+      // Wall-clock rollback starts a new window, even when the writer is backed up.
+      if (bucket && at >= bucket.at && at - bucket.at < 1_000) {
+        bucket.suppressed = Math.min(Number.MAX_SAFE_INTEGER, bucket.suppressed + 1);
+        return;
+      }
+      if (queue.length >= 56) {
+        buckets.set(key, { at: Math.min(bucket?.at ?? at, at),
+          suppressed: Math.min(Number.MAX_SAFE_INTEGER, (bucket?.suppressed ?? 0) + 1) });
+        return;
+      }
+      const suppressed = bucket?.suppressed ?? 0;
+      // Failed writes are rate-limited too; diagnostics cannot hammer an unavailable disk.
+      buckets.set(key, { at, suppressed: 0 });
+      queue.push({ dir: linkDir(configDir), line: `${JSON.stringify({ ...safe, timestamp: at, ...(suppressed ? { suppressed } : {}) })}\n` });
+      startWriter();
+    } catch { /* Diagnostics must never change request admission or expose raw errors. */ }
+  };
+  return Object.assign(sink, { flush: async (timeoutMs = 1_000) => {
+    if (!flight) return;
+    // Keep shutdown bounded even if an asynchronous filesystem or ACL operation stalls.
+    // Timeout leaves the existing writer alone; it may still finish before process exit.
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    try {
+      await Promise.race([
+        (async () => { while (flight) await flight; })(),
+        new Promise<void>(resolve => { timer = setTimeout(resolve, Math.min(1_000, Math.max(0, timeoutMs))); }),
+      ]);
+    } catch { /* Best effort; never publish raw errors. */ }
+    finally { clearTimeout(timer); }
+  } });
+}
+
+let defaultSink: ReturnType<typeof createLinkDiagnosticSink> | undefined;
+/** Lazily enqueue sanitized evidence in the default sink without propagating diagnostic failures. */
+export function recordLinkDiagnostic(record: LinkDiagnosticRecord): void {
+  try { (defaultSink ??= createLinkDiagnosticSink())(record); } catch { /* Best effort. */ }
+}
+
+/** Drain existing diagnostics for at most one second without activating an unused sink. */
+export async function flushLinkDiagnostics(): Promise<void> {
+  await defaultSink?.flush();
+}

package/src/link/management-routes.ts

@@ -29,6 +29,8 @@ export const LINK_MANAGEMENT_READ_PATHS: readonly string[] = [
   "/api/sidecar-settings",
   "/api/v2",
   "/api/provider-quotas",
+  "/api/quota-pool",
+  "/api/fallback",
   "/api/codex-auth/active",
   "/api/codex-auth/accounts",
   "/api/oauth/accounts",

package/src/link/peer-report.ts

@@ -0,0 +1,100 @@
+/**
+ * What a Remote Link Child tells its Home about itself, and what the Home remembers of it.
+ *
+ * A Child sends its release version and its peer feature ids (`src/remote/features.ts`) as two
+ * headers on the credential-free relay-auth challenge it already sends before every relayed
+ * request (`src/client/link-relay-transport.ts`). The Home records them only after the caller
+ * proof verifies, so an observation is bound to the link key; it is still the Child's own claim
+ * and is used for display and compatibility verdicts, never for admission.
+ *
+ * A Home older than this report ignores the headers, and a Child older than it sends none: the
+ * Home then knows only the relay-auth version the challenge itself names. Observations live in
+ * the Home's memory and start empty after a restart; the next relayed request refills them.
+ */
+export const LINK_PEER_REPORT_VERSION = "1";
+export const LINK_PEER_VERSION_HEADER = "x-opencodex-link-peer-version";
+export const LINK_PEER_FEATURES_HEADER = "x-opencodex-link-peer-features";
+
+const RELEASE_VERSION = /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.+-]{1,128})?$/;
+const FEATURE_ID = /^[A-Za-z0-9][A-Za-z0-9._/-]{0,79}$/;
+const MAX_FEATURES = 64;
+const MAX_LINKS = 256;
+
+export interface LinkPeerReport {
+  /** True when the challenge carried either report header, valid or not; false for a pre-report Child. */
+  reported: boolean;
+  version: string | null;
+  features: string[] | null;
+}
+
+/** Header values a Child sends. Invalid input yields no header rather than a malformed one. */
+export function linkPeerReportHeaders(version: string, features: readonly string[]): Record<string, string> {
+  const headers: Record<string, string> = {};
+  if (RELEASE_VERSION.test(version)) headers[LINK_PEER_VERSION_HEADER] = version;
+  const ids = parseFeatureList(features.join(","));
+  if (ids) headers[LINK_PEER_FEATURES_HEADER] = ids.join(",");
+  return headers;
+}
+
+function parseFeatureList(value: string | null): string[] | null {
+  if (value === null || value === "") return null;
+  const ids = value.split(",");
+  if (ids.length > MAX_FEATURES || new Set(ids).size !== ids.length || ids.some(id => !FEATURE_ID.test(id))) return null;
+  return ids;
+}
+
+/** Home side: read a report from challenge headers. Each field is dropped on its own when invalid. */
+export function parseLinkPeerReport(headers: Headers): LinkPeerReport {
+  const version = headers.get(LINK_PEER_VERSION_HEADER);
+  const features = headers.get(LINK_PEER_FEATURES_HEADER);
+  return {
+    reported: version !== null || features !== null,
+    version: version !== null && RELEASE_VERSION.test(version) ? version : null,
+    features: parseFeatureList(features),
+  };
+}
+
+export interface LinkPeerObservation extends LinkPeerReport {
+  /** The relay-auth version of the verified challenge. */
+  relayAuth: string;
+  observedAt: string;
+}
+
+/** A challenge for a known link and key that named a relay-auth version this Home does not speak. */
+export interface LinkPeerRefusal {
+  relayAuth: string;
+  refusedAt: string;
+}
+
+export interface LinkPeerEntry {
+  observed: LinkPeerObservation | null;
+  refused: LinkPeerRefusal | null;
+}
+
+export interface LinkPeerObservations {
+  observe(linkId: string, relayAuth: string, report: LinkPeerReport): void;
+  refuse(linkId: string, relayAuth: string): void;
+  get(linkId: string): LinkPeerEntry;
+}
+
+export function createLinkPeerObservations(now: () => Date = () => new Date()): LinkPeerObservations {
+  const entries = new Map<string, LinkPeerEntry>();
+  const update = (linkId: string, change: Partial<LinkPeerEntry>) => {
+    const current = entries.get(linkId) ?? { observed: null, refused: null };
+    entries.delete(linkId);
+    entries.set(linkId, { ...current, ...change });
+    // Only known link ids reach here; the cap bounds memory if the store churns for a long time.
+    if (entries.size > MAX_LINKS) entries.delete(entries.keys().next().value!);
+  };
+  return {
+    observe(linkId, relayAuth, report) {
+      update(linkId, { observed: { relayAuth, ...report, observedAt: now().toISOString() }, refused: null });
+    },
+    refuse(linkId, relayAuth) {
+      update(linkId, { refused: { relayAuth, refusedAt: now().toISOString() } });
+    },
+    get(linkId) {
+      return entries.get(linkId) ?? { observed: null, refused: null };
+    },
+  };
+}

package/src/link/relay-auth.ts

@@ -2,6 +2,12 @@ import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
 
 export const LINK_RELAY_AUTH_PATH = "/.well-known/opencodex/link-relay-auth";
 export const LINK_RELAY_SESSION_HEADER = "x-opencodex-link-session";
+/**
+ * Marks a challenge that only asks whether the Home answers (the Child's readiness preflight): the
+ * Home proves itself without reserving a session, so no data request can follow it and it holds
+ * neither session capacity nor a drain lease. An older Home ignores it and reserves as before.
+ */
+export const LINK_RELAY_PROBE_HEADER = "x-opencodex-link-probe";
 export const LINK_RELAY_AUTH_VERSION = "2";
 export const LINK_RELAY_AUTH_TIMEOUT_MS = 5_000;
 

package/src/link/remote-platform.ts

@@ -0,0 +1,78 @@
+/**
+ * Windows recognition for Remote Link Children.
+ *
+ * Remote Link drives its Child through a POSIX `sh` prelude, so a Windows Child is refused
+ * before any link key is issued or tunnel started. A Windows OpenSSH server shows up in one of
+ * three ways, depending on its default shell:
+ * - Git Bash, MSYS2 or Cygwin: `uname -s` reports MINGW*, MSYS*, CYGWIN* (or Windows*), and the
+ *   ocx prelude exits with REMOTE_PLATFORM_UNSUPPORTED.
+ * - cmd.exe: a POSIX command such as `true` or `sh` is "not recognized as an internal or
+ *   external command".
+ * - PowerShell: the same command "is not recognized as the name of a cmdlet".
+ *
+ * Hub mode (`ocx hub invite` on a Hub, `ocx connect` on the client) supports Windows clients, so
+ * every refusal points there.
+ */
+import { buildWindowsProbeArgv, REMOTE_COMMAND_NOT_FOUND, REMOTE_PLATFORM_UNSUPPORTED } from "./ssh-argv";
+import type { SshRunner, SshRunResult } from "./ssh-runner";
+
+export type RemotePlatform = "windows" | "posix" | "unknown";
+
+const WINDOWS_UNAME = /^(?:Windows|MSYS|MINGW|CYGWIN)/i;
+const POSIX_UNAME = /^[A-Za-z][A-Za-z0-9_.-]{0,63}$/;
+// Windows PowerShell says "the name of a cmdlet", PowerShell 7 "a name of a cmdlet". Localized
+// installs say neither, which is what confirmWindowsShell is for.
+const WINDOWS_SHELL_REFUSAL = /is not recognized as (?:an internal or external command|(?:the|a) name of a cmdlet)/i;
+/** ssh's own failure status: the remote shell never ran, so there is nothing to ask. */
+const SSH_TRANSPORT_FAILURE = 255;
+
+/** Remote argv that prints the kernel name; under cmd or PowerShell, `sh` itself is refused. */
+export const REMOTE_UNAME_ARGV: readonly string[] = ["sh", "-c", "uname -s 2>/dev/null", "ocx-platform"];
+
+/** Server-side refusal text, shared by the dashboard and the CLI's JSON consumers. */
+export const WINDOWS_CHILD_REFUSAL = "Remote Link Children require macOS or Linux; Windows is unsupported. Connect a Windows computer in Hub mode: run ocx hub invite on a Hub, then the printed ocx connect command on the Windows computer.";
+
+/** Does this output come from cmd.exe or PowerShell refusing a POSIX command? */
+export function isWindowsShellRefusal(output: string): boolean {
+  return WINDOWS_SHELL_REFUSAL.test(output);
+}
+
+/** Classify one remote command result. Transport failures and odd output stay unknown. */
+export function classifyRemotePlatform(result: SshRunResult): RemotePlatform {
+  if (result.code === REMOTE_PLATFORM_UNSUPPORTED) return "windows";
+  if (isWindowsShellRefusal(result.stderr) || isWindowsShellRefusal(result.stdout)) return "windows";
+  if (result.code !== 0) return "unknown";
+  const name = result.stdout.trim().split(/\r?\n/)[0] ?? "";
+  if (WINDOWS_UNAME.test(name)) return "windows";
+  return POSIX_UNAME.test(name) ? "posix" : "unknown";
+}
+
+/**
+ * Could this failure be a Windows shell whose refusal text is localized? Success, the prelude's own
+ * 125/127 answers and ssh transport failures are already explained, so they never cost another call.
+ */
+export function mayBeWindowsShell(result: SshRunResult): boolean {
+  return result.code !== 0 && result.code !== REMOTE_PLATFORM_UNSUPPORTED
+    && result.code !== REMOTE_COMMAND_NOT_FOUND && result.code !== SSH_TRANSPORT_FAILURE;
+}
+
+/** Ask the host the fixed, locale-independent WINDOWS_OS_PROBE. Any failure answers false. */
+export async function confirmWindowsShell(runner: SshRunner, alias: string, knownHostsFile: string, timeoutMs = 30_000): Promise<boolean> {
+  try {
+    const result = await runner.run(buildWindowsProbeArgv({ alias, knownHostsFile }), { timeoutMs });
+    return result.code === 0 && result.stdout.trim().split(/\r?\n/)[0]?.trim() === "Windows_NT";
+  } catch { return false; }
+}
+
+/** classifyRemotePlatform, plus the locale-independent follow-up when the answer could be Windows. */
+export async function detectRemotePlatform(runner: SshRunner, alias: string, knownHostsFile: string, result: SshRunResult): Promise<RemotePlatform> {
+  const platform = classifyRemotePlatform(result);
+  if (platform !== "unknown" || !mayBeWindowsShell(result)) return platform;
+  return await confirmWindowsShell(runner, alias, knownHostsFile) ? "windows" : "unknown";
+}
+
+/** The CLI sentence for a refused Windows Child. */
+export function windowsChildRefusal(alias: string): string {
+  return `${alias} is a Windows computer. Remote Link Children require macOS or Linux, so no link key was issued and no tunnel was started. `
+    + `Connect it in Hub mode instead: run 'ocx hub invite' on a Hub, then run the printed 'ocx connect' command on ${alias}.`;
+}

package/src/link/ssh-argv.ts

@@ -191,6 +191,25 @@ export function buildProbeArgv(options: ProbeArgvOptions): string[] {
   ];
 }
 
+/**
+ * Locale-independent Windows check for a host whose SSH shell is cmd.exe or PowerShell. Both run
+ * `cmd /c echo %OS%`, and cmd expands it to `Windows_NT` regardless of display language. The
+ * command is a fixed literal; a POSIX shell answers "command not found" and nothing else.
+ */
+export const WINDOWS_OS_PROBE = "cmd /c echo %OS%";
+
+/** Run WINDOWS_OS_PROBE against an already trusted (pinned or just-probed) host key only. */
+export function buildWindowsProbeArgv(options: { alias: string; knownHostsFile: string }): string[] {
+  const alias = assertSshAlias(options.alias);
+  return [
+    "ssh", "-T",
+    ...commonOptions(alias, options.knownHostsFile, "yes"),
+    "-o", "ClearAllForwardings=yes",
+    "--", alias,
+    WINDOWS_OS_PROBE,
+  ];
+}
+
 /** Read the fingerprint of the host key recorded by a probe. */
 export function buildFingerprintArgv(tempKnownHostsFile: string): string[] {
   return ["ssh-keygen", "-l", "-f", assertKnownHostsPath(tempKnownHostsFile)];

package/src/link/status-projection.ts

@@ -2,6 +2,9 @@ import type { LinkStore } from "./store";
 import type { LinkTunnelStatus } from "./supervisor";
 import type { TunnelState } from "./tunnel-state";
 import { readCompensation, type CompensationStore } from "./compensation";
+import { EMPTY_LINK_CHILD_PARITY, type LinkChildParity } from "./child-parity";
+import { linkPeerStatus, type LinkLocalPeer, type LinkPeerStatus } from "./compatibility";
+import type { LinkPeerEntry } from "./peer-report";
 import type { OcxClientConnectionConfig } from "../types";
 
 export type LinkWireState = "connecting" | "connected" | "reconnecting" | "failed" | "idle";
@@ -9,7 +12,7 @@ export type LinkWireState = "connecting" | "connected" | "reconnecting" | "faile
 export interface LinkStatusDto {
   role: "standalone" | "home" | "child";
   listener: { state: "off" | "listening" | "failed"; port: number | null };
-  links: Array<{
+  links: Array<LinkChildParity & {
     id: string;
     alias: string;
     direction: "hub-initiated" | "client-initiated";
@@ -17,6 +20,10 @@ export interface LinkStatusDto {
     since: string;
     reason: string | null;
     tunnelPort: number;
+    /** Home only: what the link carried from this Child, and the compatibility verdict. */
+    peer?: LinkPeerStatus;
+    /** Home-initiated links on request (`?diagnostics=1`): retry progress and the last failure. */
+    tunnel?: LinkTunnelDiagnostics;
   }>;
   child: null | {
     alias: string;
@@ -24,6 +31,54 @@ export interface LinkStatusDto {
     since: string;
     reason: string | null;
   };
+  /** This build's version and link protocol, the side every `peer` verdict compares against. */
+  local?: LinkLocalPeer;
+}
+
+/**
+ * The Home's account of one `-R` tunnel: ssh attempts since it was last connected, when the next
+ * one is due (null while one runs or none is scheduled), the last state change and the last
+ * failure. `cause` is a fixed word from `tunnel-history.ts`, never ssh output.
+ */
+export interface LinkTunnelDiagnostics {
+  attempt: number;
+  nextRetryAt: string | null;
+  lastTransition: { from: LinkWireState; to: LinkWireState; at: string; cause: string | null } | null;
+  lastFailure: { cause: string; at: string } | null;
+}
+
+function iso(at: number): string {
+  return new Date(at).toISOString();
+}
+
+/** Add `tunnel` to each Home-initiated link the supervisor reports. */
+export function attachLinkTunnelDiagnostics(dto: LinkStatusDto, supervisorStates: readonly LinkTunnelStatus[]): LinkStatusDto {
+  const byId = new Map(supervisorStates.map(status => [status.linkId, status]));
+  for (const link of dto.links) {
+    const status = byId.get(link.id);
+    if (!status || status.direction !== "hub-initiated") continue;
+    const { state, history } = status;
+    const due = (state.kind === "failed" || state.kind === "reconnecting") && state.retryAt !== undefined && state.inFlight !== true
+      ? state.retryAt : null;
+    link.tunnel = {
+      attempt: history?.attempt ?? 0,
+      nextRetryAt: due === null ? null : iso(due),
+      lastTransition: history?.lastTransition
+        ? { from: history.lastTransition.from, to: history.lastTransition.to, at: iso(history.lastTransition.at), cause: history.lastTransition.cause }
+        : null,
+      lastFailure: history?.lastFailure ? { cause: history.lastFailure.cause, at: iso(history.lastFailure.at) } : null,
+    };
+  }
+  return dto;
+}
+
+/** Add this build's identity and, on a Home, each Child's observed peer status. */
+export function attachLinkPeers(dto: LinkStatusDto, local: LinkLocalPeer, observation: (linkId: string) => LinkPeerEntry): LinkStatusDto {
+  if (dto.role === "home") {
+    for (const link of dto.links) link.peer = linkPeerStatus(local, observation(link.id));
+  }
+  dto.local = local;
+  return dto;
 }
 
 export interface ClientLinkIdentity { direction: "hub-initiated" | "client-initiated"; alias?: string }
@@ -75,6 +130,8 @@ export function projectLinkStatus(
   compensation: CompensationStore = readCompensation(),
   clientChild: LinkStatusDto["child"] = null,
   identity: ClientLinkIdentity | null = null,
+  /** The Home's view of each Child's last apply (OCX-6); every field is null without a report. */
+  parity: (linkId: string) => LinkChildParity = () => EMPTY_LINK_CHILD_PARITY,
 ): LinkStatusDto {
   const byId = new Map(supervisorStates.map(status => [status.linkId, status]));
   const links = store.links.map(record => ({
@@ -83,6 +140,7 @@ export function projectLinkStatus(
     direction: record.direction,
     ...stateDetails(record, byId.get(record.id), compensation),
     tunnelPort: record.tunnelPort,
+    ...parity(record.id),
   }));
   const childRecord = config.runtimeRole === "client"
     ? (config.client?.transport === "link" ? store.links.find(record => record.id === config.client?.link?.linkId) : store.links[0])
@@ -101,7 +159,10 @@ export function projectLinkStatus(
     : client?.link ? { alias: identity?.alias ?? client.serverUrl, state: "idle" as const, since: client.connectedAt, reason: null } : null);
   if (client?.link && child && identity) {
     const active = links.find(link => link.id === client.link!.linkId);
-    const projected = { id: client.link.linkId, direction: identity.direction, tunnelPort: client.link.tunnelPort, ...child, alias: identity.alias ?? child.alias };
+    const projected = {
+      id: client.link.linkId, direction: identity.direction, tunnelPort: client.link.tunnelPort, ...child, alias: identity.alias ?? child.alias,
+      ...parity(client.link.linkId),
+    };
     if (active) Object.assign(active, projected, compensation.entries[active.id] && childRecord ? stateDetails(childRecord, byId.get(active.id), compensation) : {});
     else links.push(projected);
   }