@bitkyc08/opencodex 2.89.0 → 2.91.0

package/src/lib/upstream-retry.ts

@@ -34,6 +34,20 @@ export function markResponseNonReplayable(response: Response): void {
   nonReplayableResponses.add(response);
 }
 
+/**
+ * A server-instructed wait longer than the retry budget: same-target 429 replay loops stop and
+ * return the original response, while key rotation and ordinary error delivery are unaffected.
+ */
+const sameTargetRetryHolds = new WeakSet<Response>();
+
+export function markSameTargetRetryHold(response: Response): void {
+  sameTargetRetryHolds.add(response);
+}
+
+export function isSameTargetRetryHold(response: Response): boolean {
+  return sameTargetRetryHolds.has(response);
+}
+
 export function isNonReplayableResponse(response: Response): boolean {
   return nonReplayableResponses.has(response);
 }
@@ -144,6 +158,7 @@ export function retainReplayRefusal<T extends Response>(response: T): T {
 
 /** Carry the verdict from a response onto the one that replaces it. */
 export function carryReplayRefusal<T extends Response>(source: Response, rewrapped: T): T {
+  if (sameTargetRetryHolds.has(source)) sameTargetRetryHolds.add(rewrapped);
   return isReplayRefusalResponse(source) ? retainReplayRefusal(rewrapped) : rewrapped;
 }
 

package/src/link/child-parity.ts

@@ -0,0 +1,124 @@
+/**
+ * What a Remote Link Child tells its Home about the last settings apply (OCX-6).
+ *
+ * The Child knows when it last applied the Home's Codex settings, which digest it applied and when
+ * its runtime started; the Home knows none of it. The Child reports these facts over the link
+ * (`POST` to {@link LINK_CHILD_PARITY_PATH}, admitted by its link key) and the Home shows them on
+ * each link row of `GET /api/link/status` (`lastApplyAt`, `runtimeStartedAt`,
+ * `appliedCodexSettingsDigest`), so a peer can compare apply time with runtime start, and the
+ * applied digest with the Home's own, without reading the Child.
+ *
+ * Display only. A report never admits, routes or changes anything on the Home, carries no setting
+ * value, and lives in memory: a Home restart forgets it until the Child's next report (at most a
+ * minute later).
+ */
+import { CODEX_SETTINGS_DIGEST_PATTERN } from "./codex-settings";
+import { LINK_MANAGEMENT_PREFIX } from "./management-routes";
+
+/** The one write a Child may send its Home over the link. */
+export const LINK_CHILD_PARITY_PATH = `${LINK_MANAGEMENT_PREFIX}/child-parity`;
+/** A report is four short fields; anything larger is refused while it is still being read. */
+export const LINK_CHILD_PARITY_MAX_BYTES = 1024;
+
+const LINK_ID = /^lnk_[0-9a-f]{16}$/;
+/** 2001-09-09 .. 2286-11-20: any epoch-millisecond time a real clock reports. */
+const MIN_EPOCH_MS = 1_000_000_000_000;
+const MAX_EPOCH_MS = 9_999_999_999_999;
+
+export interface LinkChildParityReport {
+  linkId: string;
+  /** Epoch ms of the Child's last successful apply of a different Home settings document. */
+  lastApplyAt: number | null;
+  /** Epoch ms of the Child runtime's process start. */
+  runtimeStartedAt: number;
+  /** `appliedCodexSettingsDigest` of the applied settings; null before any apply. */
+  appliedCodexSettingsDigest: string | null;
+  /**
+   * Increases with every report this runtime process sends. With `runtimeStartedAt` it orders
+   * reports, so a late POST from an older runtime or an earlier send never replaces a newer one.
+   */
+  sequence: number;
+}
+
+/** The per-link fields `GET /api/link/status` carries; every one is null until a report arrives. */
+export interface LinkChildParity {
+  lastApplyAt: number | null;
+  runtimeStartedAt: number | null;
+  appliedCodexSettingsDigest: string | null;
+  /** Epoch ms the Home received the report (the Home's clock; the other times are the Child's). */
+  reportedAt: number | null;
+}
+
+export const EMPTY_LINK_CHILD_PARITY: LinkChildParity = Object.freeze({
+  lastApplyAt: null, runtimeStartedAt: null, appliedCodexSettingsDigest: null, reportedAt: null,
+});
+
+export function isEpochMs(value: unknown): value is number {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= MIN_EPOCH_MS && value <= MAX_EPOCH_MS;
+}
+
+function exactKeys(value: unknown, keys: readonly string[]): value is Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const actual = Object.keys(value);
+  return actual.length === keys.length && actual.every(key => keys.includes(key));
+}
+
+/** Strict: an unknown field, a non-integer time or a malformed digest rejects the report. */
+export function parseLinkChildParityReport(value: unknown): LinkChildParityReport | null {
+  if (!exactKeys(value, ["linkId", "lastApplyAt", "runtimeStartedAt", "appliedCodexSettingsDigest", "sequence"])) return null;
+  const { linkId, lastApplyAt, runtimeStartedAt, appliedCodexSettingsDigest: digest, sequence } = value;
+  if (typeof linkId !== "string" || !LINK_ID.test(linkId)) return null;
+  if (lastApplyAt !== null && !isEpochMs(lastApplyAt)) return null;
+  if (!isEpochMs(runtimeStartedAt)) return null;
+  if (digest !== null && (typeof digest !== "string" || !CODEX_SETTINGS_DIGEST_PATTERN.test(digest))) return null;
+  // An apply has both a time and a digest; before the first apply it has neither.
+  if ((lastApplyAt === null) !== (digest === null)) return null;
+  if (typeof sequence !== "number" || !Number.isSafeInteger(sequence) || sequence < 0) return null;
+  return { linkId, lastApplyAt, runtimeStartedAt, appliedCodexSettingsDigest: digest, sequence };
+}
+
+export interface LinkChildParityStore {
+  /**
+   * Keep the report for its link unless a newer one is already kept (by `runtimeStartedAt`, then
+   * `sequence`), dropping every entry whose link is not in `currentLinkIds`. True when kept.
+   */
+  record(report: LinkChildParityReport, currentLinkIds: ReadonlySet<string>): boolean;
+  get(linkId: string): LinkChildParity;
+  clear(): void;
+}
+
+export function createLinkChildParityStore(now: () => number = Date.now): LinkChildParityStore {
+  const reports = new Map<string, LinkChildParity & { sequence: number }>();
+  return {
+    record(report, currentLinkIds) {
+      for (const id of reports.keys()) if (!currentLinkIds.has(id)) reports.delete(id);
+      if (!currentLinkIds.has(report.linkId)) return false;
+      const kept = reports.get(report.linkId);
+      if (kept && (kept.runtimeStartedAt! > report.runtimeStartedAt
+        || (kept.runtimeStartedAt === report.runtimeStartedAt && kept.sequence >= report.sequence))) return false;
+      reports.set(report.linkId, {
+        lastApplyAt: report.lastApplyAt,
+        runtimeStartedAt: report.runtimeStartedAt,
+        appliedCodexSettingsDigest: report.appliedCodexSettingsDigest,
+        reportedAt: now(),
+        sequence: report.sequence,
+      });
+      return true;
+    },
+    get(linkId) {
+      const kept = reports.get(linkId);
+      if (!kept) return { ...EMPTY_LINK_CHILD_PARITY };
+      const { sequence: _sequence, ...parity } = kept;
+      return parity;
+    },
+    clear() { reports.clear(); },
+  };
+}
+
+/** The Home's reports: one process-wide store, bounded by the link store on every write. */
+export const homeLinkChildParity: LinkChildParityStore = createLinkChildParityStore();
+
+/** Home link listener: is this the Child's report (exact path, POST, no query, no upgrade)? */
+export function linkChildParityRouteAllowed(url: URL, req: Request): boolean {
+  return url.pathname === LINK_CHILD_PARITY_PATH && req.method === "POST" && url.search === "" && !req.headers.has("upgrade");
+}

package/src/link/codex-settings.ts

@@ -23,6 +23,7 @@
  * It rides on its own authenticated link read rather than inside the catalog because the
  * catalog bytes are written verbatim to `model_catalog_json`, which Codex parses itself.
  */
+import { createHash } from "node:crypto";
 import { hostname } from "node:os";
 import type { OcxConfig } from "../types";
 
@@ -153,3 +154,39 @@ export function describeHomeCodexSettings(settings: HomeCodexSettings): string[]
     `native sub-agent defaults: ${d ? `${d.model}${d.reasoningEffort ? ` (${d.reasoningEffort})` : ""}` : "not synced"}`,
   ];
 }
+
+/** 64 lowercase hex digits: the only form a settings digest takes on the wire. */
+export const CODEX_SETTINGS_DIGEST_PATTERN = /^[0-9a-f]{64}$/;
+
+/**
+ * The exact bytes {@link codexSettingsDigest} hashes: compact UTF-8 JSON in a fixed key order,
+ *
+ *   {"version":1,"settings":{"fastMode":…,"multiAgentMode":…,"webSearchSidecarEnabled":…,
+ *    "subagentDefaults":null|{"model":…,"reasoningEffort":…}}}
+ *
+ * This is a published contract (GOAT's hub recomputes it byte for byte), so the order is written
+ * out here rather than left to a canonicalizer, and every value is copied by name: whatever key
+ * order or extra field the input object has, the output is the same.
+ */
+export function codexSettingsDigestPayload(settings: HomeCodexSettings): string {
+  const d = settings.subagentDefaults;
+  return JSON.stringify({
+    version: HOME_CODEX_SETTINGS_VERSION,
+    settings: {
+      fastMode: settings.fastMode,
+      multiAgentMode: settings.multiAgentMode,
+      webSearchSidecarEnabled: settings.webSearchSidecarEnabled,
+      subagentDefaults: d ? { model: d.model, reasoningEffort: d.reasoningEffort } : null,
+    },
+  });
+}
+
+/**
+ * `appliedCodexSettingsDigest` (OCX-6b): lowercase hex SHA-256 of
+ * {@link codexSettingsDigestPayload}. It covers the applied values only, never the Home's name or
+ * version, so a Home and a Child that applied the same values agree, and any value change differs.
+ * It carries no setting value, so it is safe wherever `ocx status --json` goes.
+ */
+export function codexSettingsDigest(settings: HomeCodexSettings): string {
+  return createHash("sha256").update(codexSettingsDigestPayload(settings), "utf8").digest("hex");
+}

package/src/link/compatibility.ts

@@ -0,0 +1,119 @@
+/**
+ * Home and Child compatibility over a Remote Link.
+ *
+ * `LINK_PROTOCOL_RELEASES` is the published record of which release first spoke each part of the
+ * link protocol. It is history, so it cannot be derived at run time; `tests/clients/link-peer-
+ * compatibility.test.ts` holds every id to the live feature registry and every release to the
+ * package version. The verdict uses only what the link carries: the relay-auth version of a
+ * verified challenge and, from 2.91.0, the Child's own version and feature report
+ * (`src/link/peer-report.ts`).
+ */
+import { LINK_RELAY_AUTH_VERSION } from "./relay-auth";
+import { LINK_PEER_REPORT_VERSION, type LinkPeerEntry } from "./peer-report";
+
+export interface LinkProtocolRelease {
+  /** The peer feature id, as `GET /readyz` lists it. */
+  readonly id: string;
+  /** First release that speaks it on both sides of a link. */
+  readonly since: string;
+  readonly summary: string;
+}
+
+export const LINK_PEER_REPORT_FEATURE = `link-peer-report/${LINK_PEER_REPORT_VERSION}`;
+
+export const LINK_PROTOCOL_RELEASES: readonly LinkProtocolRelease[] = [
+  { id: "relay-auth/2", since: "2.69.0", summary: "Connection-bound relay authentication before every relayed request." },
+  { id: "link-management-relay", since: "2.84.0", summary: "Read-only Home management and Home Codex settings for the Child." },
+  { id: LINK_PEER_REPORT_FEATURE, since: "2.91.0", summary: "The Child reports its version and features on the relay challenge." },
+];
+
+export type LinkCompatibilityVerdict = "compatible" | "degraded" | "incompatible" | "unknown";
+
+export interface LinkLocalPeer {
+  version: string;
+  relayAuth: string;
+  features: string[];
+}
+
+export interface LinkPeerStatus {
+  observedAt: string | null;
+  /** The Child's reported release, or null when it predates the report. */
+  version: string | null;
+  /** For an unreported version: the oldest release the observed protocol implies, and the first that would report. */
+  versionRange: { min: string | null; below: string } | null;
+  relayAuth: string | null;
+  features: string[] | null;
+  compatibility: LinkCompatibilityVerdict;
+  reasons: string[];
+}
+
+function releaseParts(version: string): number[] {
+  return version.split(/[-+]/, 1)[0]!.split(".").map(part => Number(part));
+}
+
+export function compareReleases(a: string, b: string): number {
+  const left = releaseParts(a), right = releaseParts(b);
+  for (let i = 0; i < 3; i++) {
+    const diff = (left[i] ?? 0) - (right[i] ?? 0);
+    if (diff !== 0) return Math.sign(diff);
+  }
+  return 0;
+}
+
+function sinceOf(id: string): string | null {
+  return LINK_PROTOCOL_RELEASES.find(release => release.id === id)?.since ?? null;
+}
+
+function relayAuthNumber(value: string): number {
+  return /^\d{1,4}$/.test(value) ? Number(value) : Number.NaN;
+}
+
+export function linkPeerStatus(local: LinkLocalPeer, entry: LinkPeerEntry): LinkPeerStatus {
+  const { observed, refused } = entry;
+  if (refused && (!observed || observed.observedAt <= refused.refusedAt)) {
+    const newerChild = relayAuthNumber(refused.relayAuth) > relayAuthNumber(local.relayAuth);
+    return {
+      observedAt: refused.refusedAt, version: null, versionRange: null, relayAuth: refused.relayAuth, features: null,
+      compatibility: "incompatible",
+      reasons: [`The Child speaks relay-auth/${refused.relayAuth} and this Home speaks relay-auth/${local.relayAuth}, so relayed requests are refused. Upgrade the ${newerChild ? "Home" : "Child"}.`],
+    };
+  }
+  if (!observed) {
+    return {
+      observedAt: null, version: null, versionRange: null, relayAuth: null, features: null,
+      compatibility: "unknown", reasons: ["No relayed request from this Child since the Home started."],
+    };
+  }
+  const base = { observedAt: observed.observedAt, relayAuth: observed.relayAuth, features: observed.features };
+  if (!observed.reported) {
+    return {
+      ...base, version: null,
+      versionRange: { min: sinceOf(`relay-auth/${observed.relayAuth}`), below: sinceOf(LINK_PEER_REPORT_FEATURE)! },
+      compatibility: "compatible",
+      reasons: [`relay-auth/${observed.relayAuth} matches. The Child does not report its version; it predates ${LINK_PEER_REPORT_FEATURE}.`],
+    };
+  }
+  if (observed.version === null || observed.features === null) {
+    // A reporting Child whose version or feature list was missing or rejected: the Home cannot tell what it uses.
+    return {
+      ...base, version: observed.version, versionRange: null, compatibility: "unknown",
+      reasons: [`relay-auth/${observed.relayAuth} matches, but the Child's ${observed.version === null && observed.features === null ? "version and feature list were" : observed.version === null ? "version was" : "feature list was"} missing or invalid, so its features cannot be checked.`],
+    };
+  }
+  const childOnly = observed.features.filter(id => !local.features.includes(id));
+  if (childOnly.length > 0) {
+    return {
+      ...base, version: observed.version, versionRange: null, compatibility: "degraded",
+      reasons: [`The Child (${observed.version}) uses ${childOnly.join(", ")}, which this Home (${local.version}) does not serve. Upgrade the Home.`],
+    };
+  }
+  return {
+    ...base, version: observed.version, versionRange: null, compatibility: "compatible",
+    reasons: [compareReleases(observed.version, local.version) === 0 ? "Same release as this Home."
+      : `relay-auth/${observed.relayAuth} matches and this Home (${local.version}) serves every feature the Child (${observed.version}) uses.`],
+  };
+}
+
+export function localLinkPeer(version: string, features: readonly string[]): LinkLocalPeer {
+  return { version, relayAuth: LINK_RELAY_AUTH_VERSION, features: [...features] };
+}

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/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,8 @@ 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;
   }>;
   child: null | {
     alias: string;
@@ -24,6 +29,17 @@ export interface LinkStatusDto {
     since: string;
     reason: string | null;
   };
+  /** This build's version and link protocol, the side every `peer` verdict compares against. */
+  local?: LinkLocalPeer;
+}
+
+/** 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 +91,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 +101,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 +120,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);
   }