@bitkyc08/opencodex 2.65.0-preview.20260925 → 2.66.0-preview.20260925

package/src/link/paths.ts

@@ -0,0 +1,19 @@
+import { join } from "node:path";
+// Definition-site import, not the ../config barrel: the link modules stay small and load nothing
+// from the server or the config loader.
+import { getConfigDir } from "../config/paths";
+
+/** Directory that holds link state: `<configDir>/link`, created with mode 0700 on first write. */
+export function linkDir(configDir: string = getConfigDir()): string {
+  return join(configDir, "link");
+}
+
+/** Link records. Holds no secrets: data keys stay in the running proxy's `apiKeys`. */
+export function linkStorePath(configDir?: string): string {
+  return join(linkDir(configDir), "links.json");
+}
+
+/** The only known_hosts file link SSH commands trust. Entries are keyed by host alias. */
+export function linkKnownHostsPath(configDir?: string): string {
+  return join(linkDir(configDir), "known_hosts");
+}

package/src/link/ports.ts

@@ -0,0 +1,12 @@
+/**
+ * Port contract for the client side of a link: the loopback port P that the client's
+ * `ssh -L` tunnel listens on. Privileged ports are refused so that an ordinary user
+ * process can always bind it. The hub listener port L is chosen by the OS and keeps the
+ * plain 1-65535 range; it does not use this contract.
+ */
+export const MIN_LINK_PORT = 1024;
+export const MAX_LINK_PORT = 65535;
+
+export function isLinkPort(value: unknown): value is number {
+  return typeof value === "number" && Number.isInteger(value) && value >= MIN_LINK_PORT && value <= MAX_LINK_PORT;
+}

package/src/link/routes.ts

@@ -0,0 +1,32 @@
+const CONTEXT_PATHS = new Set([
+  "/v1/alpha/history/v2/list_windows",
+  "/v1/alpha/history/v2/list_items",
+  "/v1/alpha/history/v2/read_item",
+  "/v1/alpha/history/v2/search_contents",
+  "/v1/alpha/notes/v2/thread_hint",
+  "/v1/alpha/notes/v2/list_files_by_prefix",
+  "/v1/alpha/notes/v2/read_file",
+  "/v1/alpha/notes/v2/search_contents",
+  "/v1/alpha/notes/v2/append_to_file",
+  "/v1/alpha/notes/v2/write_file",
+]);
+
+/** The link socket is an HTTP data plane; every upgrade header is rejected first. */
+export function linkRouteAllowed(url: URL, req: Request): boolean {
+  if (req.headers.has("upgrade")) return false;
+  const { pathname } = url;
+  if (pathname === "/readyz") return req.method === "GET";
+  if (pathname === "/v1/catalog" || pathname === "/v1/hub-state") {
+    return req.method === "GET" || req.method === "HEAD";
+  }
+  if (pathname === "/v1/usage" || pathname === "/v1/models") return req.method === "GET";
+  if (pathname === "/v1/responses" || pathname === "/v1/responses/compact"
+    || pathname === "/v1/messages" || pathname === "/v1/messages/count_tokens"
+    || pathname === "/v1/chat/completions" || pathname === "/v1/audio/transcriptions"
+    || pathname === "/v1/alpha/search" || pathname === "/v1/images/generations"
+    || pathname === "/v1/images/edits" || pathname === "/v1/live"
+    || pathname === "/v1/realtime/calls" || CONTEXT_PATHS.has(pathname)) {
+    return req.method === "POST";
+  }
+  return req.method === "GET" && pathname.startsWith("/v1/opencodex/artifacts/");
+}

package/src/link/ssh-argv.ts

@@ -0,0 +1,170 @@
+/**
+ * Argument vectors for the system OpenSSH client used by machine links.
+ *
+ * Every command is built here so the security-relevant options live in one place:
+ * - BatchMode=yes: no password or passphrase prompt, keys and agents only.
+ * - HostKeyAlias=<alias> with UserKnownHostsFile=<link known_hosts> and
+ *   GlobalKnownHostsFile=none: only a host key the user confirmed for this link is trusted,
+ *   and the stored entry has the same form for every port and ProxyJump route.
+ * - KnownHostsCommand=none, VerifyHostKeyDNS=no and CheckHostIP=no: no other source of host-key
+ *   trust (a helper command, DNS SSHFP records, IP entries) can stand in for the link file.
+ *   Command-line options win over ~/.ssh/config, so a user config cannot re-enable them.
+ * - Tunnel and exec commands use StrictHostKeyChecking=yes. Only the probe uses accept-new,
+ *   against an empty temporary file, so the key it records can be shown to the user first.
+ * - Forwards always bind 127.0.0.1 on both ends.
+ */
+
+import { isAbsolute } from "node:path";
+
+export type TunnelDirection = "R" | "L";
+
+const ALIAS_PATTERN = /^[A-Za-z0-9_][A-Za-z0-9._@%+:\[\]-]{0,252}$/;
+
+export class LinkSshArgumentError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "LinkSshArgumentError";
+  }
+}
+
+/** A host alias as ssh reads it. A leading "-" would be parsed as an option, so it is refused. */
+export function isSshAlias(alias: string): boolean {
+  return ALIAS_PATTERN.test(alias);
+}
+
+export function assertSshAlias(alias: string): string {
+  if (!ALIAS_PATTERN.test(alias)) throw new LinkSshArgumentError(`invalid ssh host alias: ${JSON.stringify(alias)}`);
+  return alias;
+}
+
+function assertPort(port: number, label: string): number {
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new LinkSshArgumentError(`${label} must be an integer port between 1 and 65535`);
+  }
+  return port;
+}
+
+/**
+ * ssh splits `-o` values on whitespace, expands `%` tokens, `${ENV}` and a leading `~` in
+ * UserKnownHostsFile, treats the value `none` as "no file" and resolves a relative path against
+ * its working directory. Any of those could name a different file than the one written, so only
+ * an absolute path without expansion syntax is accepted; whitespace is quoted.
+ */
+function assertKnownHostsPath(path: string): string {
+  if (!path || !isAbsolute(path) || /["%$\x00-\x1f]/.test(path) || path.startsWith("~")) {
+    throw new LinkSshArgumentError("known_hosts path is not usable in an ssh option");
+  }
+  return path;
+}
+
+function optionPath(path: string): string {
+  assertKnownHostsPath(path);
+  return /\s/.test(path) ? `"${path}"` : path;
+}
+
+function commonOptions(alias: string, knownHostsFile: string, strict: "yes" | "accept-new"): string[] {
+  return [
+    "-o", "BatchMode=yes",
+    "-o", "ConnectTimeout=10",
+    "-o", "ServerAliveInterval=15",
+    "-o", "ServerAliveCountMax=3",
+    "-o", `StrictHostKeyChecking=${strict}`,
+    "-o", `HostKeyAlias=${alias}`,
+    "-o", `UserKnownHostsFile=${optionPath(knownHostsFile)}`,
+    "-o", "GlobalKnownHostsFile=none",
+    "-o", "KnownHostsCommand=none",
+    "-o", "VerifyHostKeyDNS=no",
+    "-o", "CheckHostIP=no",
+    "-o", "UpdateHostKeys=no",
+    "-o", "ControlMaster=no",
+    "-o", "ControlPath=none",
+    "-o", "ForwardAgent=no",
+    "-o", "ForwardX11=no",
+    "-o", "PermitLocalCommand=no",
+    "-o", "LogLevel=ERROR",
+  ];
+}
+
+export interface TunnelArgvOptions {
+  alias: string;
+  /** "R": listen on the remote host and reach this host. "L": listen here and reach the remote host. */
+  direction: TunnelDirection;
+  /** Port the forward listens on (remote for "R", local for "L"). */
+  bindPort: number;
+  /** Port the forward connects to on the other side's 127.0.0.1. */
+  targetPort: number;
+  knownHostsFile: string;
+}
+
+export function buildTunnelArgv(options: TunnelArgvOptions): string[] {
+  const alias = assertSshAlias(options.alias);
+  const bind = assertPort(options.bindPort, "bindPort");
+  const target = assertPort(options.targetPort, "targetPort");
+  if (options.direction !== "R" && options.direction !== "L") throw new LinkSshArgumentError("direction must be R or L");
+  return [
+    "ssh", "-N", "-T",
+    ...commonOptions(alias, options.knownHostsFile, "yes"),
+    "-o", "ExitOnForwardFailure=yes",
+    `-${options.direction}`, `127.0.0.1:${bind}:127.0.0.1:${target}`,
+    "--", alias,
+  ];
+}
+
+export interface ExecArgvOptions {
+  alias: string;
+  /** Remote argv. Each element is quoted for the remote POSIX shell. */
+  argv: readonly string[];
+  knownHostsFile: string;
+}
+
+export function buildExecArgv(options: ExecArgvOptions): string[] {
+  const alias = assertSshAlias(options.alias);
+  if (options.argv.length === 0) throw new LinkSshArgumentError("remote argv must not be empty");
+  return [
+    "ssh", "-T",
+    ...commonOptions(alias, options.knownHostsFile, "yes"),
+    "-o", "ClearAllForwardings=yes",
+    "--", alias,
+    quoteRemote(options.argv),
+  ];
+}
+
+export interface ProbeArgvOptions {
+  alias: string;
+  /** An empty, private, temporary file. The probe records the offered host key here. */
+  tempKnownHostsFile: string;
+}
+
+/**
+ * First contact with a host that has no confirmed key. accept-new writes the offered key to the
+ * temporary file; the caller reads it with `ssh-keygen -lf` and shows the fingerprint before
+ * anything is trusted. The remote command is `true` and its result is not trusted either.
+ */
+export function buildProbeArgv(options: ProbeArgvOptions): string[] {
+  const alias = assertSshAlias(options.alias);
+  return [
+    "ssh", "-T",
+    ...commonOptions(alias, options.tempKnownHostsFile, "accept-new"),
+    "-o", "ClearAllForwardings=yes",
+    "--", alias,
+    "true",
+  ];
+}
+
+/** Read the fingerprint of the host key recorded by a probe. */
+export function buildFingerprintArgv(tempKnownHostsFile: string): string[] {
+  return ["ssh-keygen", "-l", "-f", assertKnownHostsPath(tempKnownHostsFile)];
+}
+
+/** `ssh -G <alias>`: resolve an alias the same way ssh itself does, without connecting. */
+export function buildResolveArgv(alias: string): string[] {
+  return ["ssh", "-G", "--", assertSshAlias(alias)];
+}
+
+/** Quote argv for a POSIX remote shell: every element single-quoted, embedded quotes escaped. */
+export function quoteRemote(argv: readonly string[]): string {
+  return argv.map(arg => {
+    if (arg.includes("\0")) throw new LinkSshArgumentError("remote argument contains NUL");
+    return `'${arg.replaceAll("'", `'"'"'`)}'`;
+  }).join(" ");
+}

package/src/link/ssh-config.ts

@@ -0,0 +1,152 @@
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { isSshAlias } from "./ssh-argv";
+
+/**
+ * Host candidates from OpenSSH client configuration.
+ *
+ * Candidates are offers, not trust: a host is usable only after a probe proves key login and the
+ * user confirms its host key. Patterns (`*`, `?`, `!`) and `Match` blocks name no single host,
+ * so they are skipped. An `Include` inside a `Host` or `Match` block applies only under that
+ * block's condition, so only top-level includes are followed.
+ */
+export interface HostCandidate {
+  alias: string;
+  source: "ssh_config";
+}
+
+export interface ParseHostCandidatesOptions {
+  /** Contents of every file an `Include` pattern names, in order. */
+  resolveInclude?: (pattern: string) => string[];
+  /** Include nesting limit; OpenSSH uses 16. */
+  maxDepth?: number;
+}
+
+/**
+ * Split arguments exactly the way OpenSSH's argv_split (misc.c) does when readconf calls it with
+ * terminate_on_comment set:
+ * - blanks and tabs separate arguments; an unquoted `#` at the start of an argument ends the line;
+ * - a backslash before `'`, `"` or `\\` — or, outside quotes, before a space — yields that
+ *   character; any other backslash (including a trailing one) is kept literally;
+ * - single or double quotes group, and the backslash rule above applies inside them too.
+ * Returns null for an unterminated quote, which OpenSSH rejects as an invalid line.
+ */
+export function splitSshArgs(text: string): string[] | null {
+  const out: string[] = [];
+  let i = 0;
+  while (i < text.length) {
+    const lead = text[i];
+    if (lead === " " || lead === "\t") { i += 1; continue; }
+    if (lead === "#") break;
+    let arg = "";
+    let quote: "'" | '"' | null = null;
+    for (; i < text.length; i += 1) {
+      const ch = text[i]!;
+      const next = text[i + 1];
+      if (ch === "\\") {
+        if (next === "'" || next === '"' || next === "\\" || (quote === null && next === " ")) {
+          i += 1;
+          arg += next;
+        } else {
+          arg += ch;
+        }
+      } else if (quote === null && (ch === " " || ch === "\t")) {
+        break;
+      } else if (quote === null && (ch === '"' || ch === "'")) {
+        quote = ch;
+      } else if (quote !== null && ch === quote) {
+        quote = null;
+      } else {
+        arg += ch;
+      }
+    }
+    if (quote !== null) return null;
+    out.push(arg);
+  }
+  return out;
+}
+
+function splitDirective(raw: string): { keyword: string; args: string[] } | null {
+  const line = raw.trim();
+  if (!line || line.startsWith("#")) return null;
+  const match = /^([A-Za-z]+)(?:\s*=\s*|\s+)(.*)$/.exec(line);
+  if (!match) return null;
+  const args = splitSshArgs(match[2]!);
+  if (!args) return null;
+  return { keyword: match[1]!.toLowerCase(), args };
+}
+
+export function parseHostCandidates(text: string, options: ParseHostCandidatesOptions = {}): HostCandidate[] {
+  const seen = new Set<string>();
+  const out: HostCandidate[] = [];
+  const maxDepth = options.maxDepth ?? 16;
+  const visit = (body: string, depth: number): void => {
+    let block: "top" | "host" | "match" = "top";
+    for (const raw of body.split(/\r?\n/)) {
+      const directive = splitDirective(raw);
+      if (!directive) continue;
+      if (directive.keyword === "match") { block = "match"; continue; }
+      if (directive.keyword === "include") {
+        if (block !== "top" || depth >= maxDepth || !options.resolveInclude) continue;
+        for (const pattern of directive.args) {
+          for (const included of options.resolveInclude(pattern)) visit(included, depth + 1);
+        }
+        continue;
+      }
+      if (directive.keyword !== "host") continue;
+      block = "host";
+      for (const alias of directive.args) {
+        if (/[*?!]/.test(alias) || !isSshAlias(alias)) continue;
+        const key = alias.toLowerCase();
+        if (seen.has(key)) continue;
+        seen.add(key);
+        out.push({ alias, source: "ssh_config" });
+      }
+    }
+  };
+  visit(text, 0);
+  return out;
+}
+
+export interface LoadHostCandidatesOptions {
+  /** Home directory whose `.ssh/config` is read. Defaults to the user's home. */
+  home?: string;
+  readFile?: (path: string) => string;
+  /** Expand one absolute glob pattern to file paths. */
+  glob?: (pattern: string) => string[];
+}
+
+function defaultGlob(pattern: string): string[] {
+  if (!/[*?[]/.test(pattern)) return [pattern];
+  const base = dirname(pattern.slice(0, pattern.search(/[*?[]/) + 1));
+  const relative = pattern.slice(base.length + 1);
+  return [...new Bun.Glob(relative).scanSync({ cwd: base, absolute: true, onlyFiles: true })].sort();
+}
+
+/**
+ * Read `~/.ssh/config` and its includes. A missing or unreadable file yields no candidates.
+ * Include patterns support a leading `~/`, absolute and `~/.ssh`-relative paths and globs;
+ * `~user`, environment variables and `%` tokens are not expanded, so such an include adds no
+ * candidates (the host can still be entered by hand).
+ */
+export function loadHostCandidates(options: LoadHostCandidatesOptions = {}): HostCandidate[] {
+  const home = options.home ?? homedir();
+  const sshDir = join(home, ".ssh");
+  const read = options.readFile ?? ((path: string) => readFileSync(path, "utf8"));
+  const glob = options.glob ?? defaultGlob;
+  const safeRead = (path: string): string | null => {
+    try { return read(path); } catch { return null; }
+  };
+  const root = safeRead(join(sshDir, "config"));
+  if (root === null) return [];
+  return parseHostCandidates(root, {
+    resolveInclude: pattern => {
+      const expanded = pattern.startsWith("~/") ? join(home, pattern.slice(2)) : pattern;
+      const absolute = isAbsolute(expanded) ? expanded : resolve(sshDir, expanded);
+      let paths: string[];
+      try { paths = glob(absolute); } catch { return []; }
+      return paths.map(safeRead).filter((body): body is string => body !== null);
+    },
+  });
+}

package/src/link/ssh-runner.ts

@@ -0,0 +1,161 @@
+const DEFAULT_OUTPUT_BYTES = 64 * 1024;
+
+export interface SshRunResult {
+  code: number;
+  stdout: string;
+  stderr: string;
+}
+
+export interface SshChild {
+  readonly pid: number;
+  readonly argv: readonly string[];
+  readonly exited: Promise<number>;
+  readonly stdout?: Promise<string>;
+  readonly stderr?: Promise<string>;
+  kill(signal?: NodeJS.Signals): void;
+}
+
+export interface SshRunner {
+  run(argv: readonly string[], options?: {
+    stdin?: string | Uint8Array;
+    timeoutMs?: number;
+    maxOutputBytes?: number;
+  }): Promise<SshRunResult>;
+  spawnTunnel(argv: readonly string[]): SshChild;
+}
+
+export class SshRunnerError extends Error {
+  constructor(readonly code: "spawn" | "timeout" | "output_limit" | "decode", message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = "SshRunnerError";
+  }
+}
+
+async function readOutput(stream: ReadableStream<Uint8Array>, maxBytes: number, kill?: () => void): Promise<string> {
+  const reader = stream.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  try {
+    for (;;) {
+      const next = await reader.read();
+      if (next.done) break;
+      total += next.value.byteLength;
+      if (total > maxBytes) {
+        kill?.();
+        throw new SshRunnerError("output_limit", `ssh output exceeded ${maxBytes} bytes`);
+      }
+      chunks.push(next.value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  const bytes = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  try {
+    return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  } catch (error) {
+    throw new SshRunnerError("decode", "ssh output was not valid UTF-8", { cause: error });
+  }
+}
+
+function outputStream(stream: Bun.Subprocess["stdout"]): ReadableStream<Uint8Array> {
+  if (!stream || typeof stream === "number") throw new SshRunnerError("spawn", "ssh output was not piped");
+  return stream;
+}
+
+function defaultKill(process: Bun.Subprocess, signal?: NodeJS.Signals): void {
+  process.kill(signal);
+}
+
+export function createSshRunner(deps: { spawn?: typeof Bun.spawn; timeoutMs?: number } = {}): SshRunner {
+  const spawn = deps.spawn ?? ((argv, options) => Bun.spawn(argv, options));
+  const defaultTimeoutMs = deps.timeoutMs ?? 30_000;
+
+  const spawnChild = (argv: readonly string[]): SshChild => {
+    let child: Bun.Subprocess;
+    try {
+      child = spawn([...argv], { stdin: "ignore", stdout: "pipe", stderr: "pipe" });
+    } catch (error) {
+      throw new SshRunnerError("spawn", `could not spawn ${argv[0] ?? "ssh"}`, { cause: error });
+    }
+    const stdout = readOutput(outputStream(child.stdout), DEFAULT_OUTPUT_BYTES, () => defaultKill(child, "SIGTERM"));
+    const stderr = readOutput(outputStream(child.stderr), DEFAULT_OUTPUT_BYTES, () => defaultKill(child, "SIGTERM"));
+    void stdout.catch(() => {});
+    void stderr.catch(() => {});
+    return {
+      pid: child.pid,
+      argv: [...argv],
+      exited: child.exited,
+      stdout,
+      stderr,
+      kill: signal => defaultKill(child, signal),
+    };
+  };
+
+  return {
+    async run(argv, options = {}) {
+      const maxOutputBytes = options.maxOutputBytes ?? DEFAULT_OUTPUT_BYTES;
+      if (!Number.isInteger(maxOutputBytes) || maxOutputBytes < 0) {
+        throw new SshRunnerError("output_limit", "maxOutputBytes must be a non-negative integer");
+      }
+      let child: Bun.Subprocess;
+      try {
+        child = spawn([...argv], {
+          stdin: options.stdin === undefined ? "ignore" : "pipe",
+          stdout: "pipe",
+          stderr: "pipe",
+        });
+      } catch (error) {
+        throw new SshRunnerError("spawn", `could not spawn ${argv[0] ?? "ssh"}`, { cause: error });
+      }
+
+    const stdout = readOutput(outputStream(child.stdout), Math.min(maxOutputBytes, DEFAULT_OUTPUT_BYTES), () => defaultKill(child, "SIGTERM"));
+    const stderr = readOutput(outputStream(child.stderr), Math.min(maxOutputBytes, DEFAULT_OUTPUT_BYTES), () => defaultKill(child, "SIGTERM"));
+      if (options.stdin !== undefined) {
+        try {
+          const input = child.stdin;
+          if (!input || typeof input === "number") throw new Error("ssh stdin was not piped");
+          await input.write(options.stdin);
+          await input.end();
+        } catch (error) {
+          child.kill("SIGTERM");
+          throw new SshRunnerError("spawn", "could not write ssh stdin", { cause: error });
+        }
+      }
+
+      const timeoutMs = options.timeoutMs ?? defaultTimeoutMs;
+      let timedOut = false;
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      const timeout = new Promise<never>((_, reject) => {
+        timer = setTimeout(() => {
+          timedOut = true;
+          defaultKill(child, "SIGTERM");
+          reject(new SshRunnerError("timeout", `ssh command exceeded ${timeoutMs}ms`));
+        }, timeoutMs);
+      });
+      try {
+        const code = await Promise.race([child.exited, timeout]);
+        const [out, err] = await Promise.all([stdout, stderr]);
+        if (timedOut) throw new SshRunnerError("timeout", `ssh command exceeded ${timeoutMs}ms`);
+        return { code, stdout: out, stderr: err };
+      } catch (error) {
+        if (error instanceof SshRunnerError) throw error;
+        throw new SshRunnerError("spawn", "ssh command failed", { cause: error });
+      } finally {
+        if (timer !== undefined) clearTimeout(timer);
+        void Promise.allSettled([stdout, stderr, child.exited]);
+      }
+    },
+    spawnTunnel,
+  };
+
+  function spawnTunnel(argv: readonly string[]): SshChild {
+    return spawnChild(argv);
+  }
+}
+
+export const SSH_OUTPUT_CAP_BYTES = DEFAULT_OUTPUT_BYTES;

package/src/link/status-projection.ts

@@ -0,0 +1,96 @@
+import type { LinkStore } from "./store";
+import type { LinkTunnelStatus } from "./supervisor";
+import type { TunnelState } from "./tunnel-state";
+import { readCompensation, type CompensationStore } from "./compensation";
+
+export type LinkWireState = "connecting" | "connected" | "reconnecting" | "failed" | "idle";
+
+export interface LinkStatusDto {
+  role: "standalone" | "home" | "child";
+  listener: { state: "off" | "listening" | "failed"; port: number | null };
+  links: Array<{
+    id: string;
+    alias: string;
+    direction: "hub-initiated" | "client-initiated";
+    state: LinkWireState;
+    since: string;
+    reason: string | null;
+    tunnelPort: number;
+  }>;
+  child: null | {
+    alias: string;
+    state: LinkWireState;
+    since: string;
+    reason: string | null;
+  };
+}
+
+export interface LinkListenerStatusProjection {
+  state: "off" | "listening" | "failed";
+  port: number | null;
+}
+
+export interface LinkStatusConfig {
+  runtimeRole?: "standalone" | "hub" | "client";
+}
+
+function asWireState(state: TunnelState | "client-owned"): LinkWireState {
+  if (state === "client-owned") return "idle";
+  return state.kind;
+}
+
+function stateDetails(
+  record: LinkStore["links"][number],
+  status: LinkTunnelStatus | undefined,
+  compensation?: CompensationStore,
+): { state: LinkWireState; since: string; reason: string | null } {
+  const failure = compensation?.entries[record.id];
+  if (failure) return { state: "failed", since: failure.since, reason: failure.reason };
+  if (!status || status.state === "client-owned") {
+    return { state: "idle", since: record.createdAt, reason: null };
+  }
+  if (status.orphan === "orphan-unverified") {
+    return { state: "failed", since: record.createdAt, reason: "stale tunnel may hold the port" };
+  }
+  const tunnel = status.state;
+  const reason = tunnel.kind === "failed" ? tunnel.reason : null;
+  const since = tunnel.kind === "idle" ? record.createdAt : new Date(tunnel.since).toISOString();
+  return { state: asWireState(tunnel), since, reason };
+}
+
+/**
+ * Project private link state into the exact K16 wire DTO. `clientChild` lets a client-side caller
+ * report a child state this module cannot read itself (an invalid client sidecar); link code
+ * stays free of client imports, so the caller supplies it.
+ */
+export function projectLinkStatus(
+  store: LinkStore,
+  supervisorStates: readonly LinkTunnelStatus[],
+  listenerStatus: LinkListenerStatusProjection,
+  config: LinkStatusConfig,
+  compensation: CompensationStore = readCompensation(),
+  clientChild: LinkStatusDto["child"] = null,
+): LinkStatusDto {
+  const byId = new Map(supervisorStates.map(status => [status.linkId, status]));
+  const links = store.links.map(record => ({
+    id: record.id,
+    alias: record.alias,
+    direction: record.direction,
+    ...stateDetails(record, byId.get(record.id), compensation),
+    tunnelPort: record.tunnelPort,
+  }));
+  const childRecord = config.runtimeRole === "client" ? store.links[0] : undefined;
+  const invalidClientSidecar = config.runtimeRole === "client" ? clientChild : null;
+  const childStatus = childRecord
+    ? stateDetails(childRecord, byId.get(childRecord.id), compensation)
+    : undefined;
+  const role = config.runtimeRole === "client"
+    ? "child"
+    : store.links.length > 0 ? "home" : "standalone";
+  return {
+    role,
+    listener: { state: listenerStatus.state, port: listenerStatus.port },
+    links,
+    child: invalidClientSidecar ?? (childRecord && childStatus ? { alias: childRecord.alias, ...childStatus } : null),
+  };
+}