@twinsearth/w2m-dsh-plugin 1.4.4 → 1.5.1

package/.claude-plugin/marketplace.json

@@ -5,14 +5,14 @@
   },
   "metadata": {
     "description": "The w2m fleet plugins: one account, many machines, any of Windows, macOS or Linux.",
-    "version": "1.4.4"
+    "version": "1.5.1"
   },
   "plugins": [
     {
       "name": "w2m-fleet",
       "source": "./",
       "description": "Read fleet state and dispatch commands across the machines registered to one account. Read-only MCP surface: the five exposed tools cannot change anything.",
-      "version": "1.4.4",
+      "version": "1.5.1",
       "author": {
         "name": "TwinsEarth"
       },
@@ -26,5 +26,5 @@
       ]
     }
   ],
-  "version": "1.4.4"
+  "version": "1.5.1"
 }

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "w2m-fleet",
   "description": "Drive the same project on online Windows, macOS and Linux machines from one account: read fleet state, dispatch commands and read results. The MCP surface is deliberately read-only.",
-  "version": "1.4.4",
+  "version": "1.5.1",
   "author": {
     "name": "TwinsEarth"
   },

package/CHANGELOG.md

@@ -7,6 +7,38 @@
 
 All notable changes to this project are documented here.
 
+## [1.5.1] — 2026-10-23
+
+**备用链路的身份隔离 + 控制面板的 relay 折叠。**
+
+- `bin/w2m-secondary-link.mjs`：默认给子进程独立身份目录（`<stateDir>/dsh-home`），并同时设置
+  `DSH_HOME` / `USERPROFILE` / `HOME`，可用 `--identity-home` 指定。修复的是 v1.5.0 现场实测的坑：
+  备用链路首次启动覆盖了主链路 `~/.dsh/xclient/device.json`，机器在下一次重启前看不出问题，
+  重启后却会以**备用身份**连到**错误的 relay**。这种"重启后才爆"的坑按默认隔离处理。
+- 控制面板 relay 折叠：`GET /api/w2m/target` 快照新增 `relays`（`relayUrls` 数组优先，兼容单
+  `rabbitUrl`），探测 `/healthz` 后按 RTT 排序、标注 primary/standby/offline；超过 3 个节点时只显示
+  3 个并给出 "+N 折叠" 提示，展开后显示全部（含离线节点，不隐藏故障）。
+- 探针失败保留在列表末尾（`ok:false`），网络异常不会让节点从视图中消失，也不会抛进快照路径。
+- 测试：secondary-link 7/7、fleet-target 49/49（新增 relay pool 四个用例）；门禁 GREEN ×2；
+  证据 `docs/acceptance/1.5.1/IDENTITY-ISOLATION-RELAY-FOLD.json`（真实 fleet task `01M5ANYMVKS3OQZ`）。
+
+## [1.5.0] — 2026-10-23
+
+**多 relay 双通道（active-passive）+ relay 健康看门狗。**
+
+- 新增 `bin/w2m-secondary-link.mjs`：在一台机器上拉一条通往备用 relay 的常在线链接。
+  它监督子进程 `w2m-localside`（同一套协议客户端），子进程退出按指数退避重启并记录每次转换，
+  由 systemd/launchd/计划任务只守护这一层——避免"链接一次启动后静默死掉"的已知失败形态。
+- active-passive 是**路由规则**：两条链接都常连，任务只在主 relay 派发；主 relay 掉线或延迟严重时
+  把同一任务改派到备用 relay（机器已在线，无需重连），正常情况下一台机器只有一个执行者。
+- 新增 `deploy/relay/`：`w2m-watchdog.sh` + systemd `.service/.timer`。每 30s 检查
+  `/healthz` 的 `"ok":true`，连续 2 次失败才重启 relay/stun；每小时最多 5 次重启（避免掩盖根因），
+  日志写 `/var/lib/w2m/watchdog/watchdog.log`。relay 因此独立于"是否有编队成员"保持在线。
+- 新增 `docs/MULTI-RELAY.md`：拓扑、选路规则（健康且 RTT 最低且目标全在线）、relay 互为成员、
+  以及 relay 超过 3 个时客户端折叠显示（`relays: 3 shown · +N online`）的约定。
+- 测试：`test/secondary-link.test.mjs` 6/6（参数校验、child argv、退避重启、日志）；
+  门禁 GREEN ×2；证据 `docs/acceptance/1.5.0/SECONDARY-LINK.json`（真实 fleet task `01M5ANYMVKR311N`）。
+
 ## [1.4.4] — 2026-10-23
 
 **relay 重启不再丢失编队归属（devices.json 持久化 fleet_id）。**

package/bin/w2m-secondary-link.mjs

@@ -0,0 +1,236 @@
+#!/usr/bin/env node
+/**
+ * w2m-secondary-link — keep a second relay link alive beside the plugin's primary link.
+ *
+ * ## Why this exists (v1.5.0)
+ *
+ * The plugin mounts against exactly one relay (`rabbitUrl`). A second relay link makes the
+ * machine visible on both relays at once, so a dispatcher can fail over to the other relay
+ * without waiting for the machine to reconnect. The two links are independent processes:
+ *
+ *   primary   the plugin's own agent, configured by `rabbitUrl`           (always on)
+ *   secondary this supervisor + a `w2m-localside` child, configured here   (standby)
+ *
+ * Active-passive is a *routing* rule, not a second execution engine: both links are connected,
+ * but work is dispatched through the primary relay; only when the primary relay is down or
+ * severely degraded does the operator route work to the secondary relay, where this link is
+ * already online. That keeps one executor per machine in the normal case (no two relays racing
+ * to run the same project) while making failover a routing decision instead of a reconnection.
+ *
+ * ## The supervisor, not the child
+ *
+ * A localside child dies for ordinary reasons (relay restart, laptop sleep, a rotated token).
+ * If the link were launched once, the machine would silently stop being visible on the standby
+ * relay — the exact "looks connected, is not" failure this project keeps recording. This process
+ * therefore supervises the child: restart on exit with backoff, and log every transition, so a
+ * scheduled task / launchd / systemd unit only has to keep *this* process alive.
+ *
+ * ## Usage
+ *
+ *   node bin/w2m-secondary-link.mjs \
+ *     --relay http://202.182.123.154:8787 \
+ *     --fleet-key <account fleet key> \
+ *     --name <machine-name>-standby \
+ *     --state ~/.dsh/xclient/secondary-link \
+ *     --log ~/.dsh/xclient/secondary-link.log \
+ *     [--project <dir>] [--operator-token <token>] [--allowed-commands '[]']
+ *
+ * The child is `bin/w2m-localside.mjs` from this same package, so the two links share the same
+ * protocol implementation and there is no second network client to keep in step.
+ */
+import { spawn } from 'node:child_process';
+import { appendFileSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const DEFAULTS = Object.freeze({
+  project: process.cwd(),
+  stateDir: null,
+  identityHome: null,
+  logFile: null,
+  allowedCommands: '[]',
+  restartDelayMs: 3000,
+  maxRestartDelayMs: 60000,
+});
+
+/**
+ * Parse the flags this supervisor forwards. Deliberately small and explicit: every value has
+ * exactly one spelling, and an unknown flag is an error rather than a silently ignored one --
+ * a standby link that is quietly pointed at the wrong relay is worse than one that refuses.
+ *
+ * @param {string[]} argv
+ * @returns {{relay:string, fleetKey:string|null, name:string|null, stateDir:string, logFile:string,
+ *   project:string, operatorToken:string|null, allowedCommands:string}}
+ */
+export function parseSecondaryArgs(argv) {
+  const out = {
+    relay: null,
+    fleetKey: null,
+    name: null,
+    stateDir: null,
+    identityHome: null,
+    logFile: null,
+    project: DEFAULTS.project,
+    operatorToken: null,
+    allowedCommands: DEFAULTS.allowedCommands,
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const flag = argv[i];
+    const value = () => {
+      const next = argv[i + 1];
+      if (typeof next !== 'string' || next.startsWith('--')) throw new Error(`${flag} needs a value`);
+      i += 1;
+      return next;
+    };
+    switch (flag) {
+      case '--relay': out.relay = value().replace(/\/+$/, ''); break;
+      case '--fleet-key': out.fleetKey = value(); break;
+      case '--name': out.name = value(); break;
+      case '--state': out.stateDir = value(); break;
+      case '--identity-home': out.identityHome = value(); break;
+      case '--log': out.logFile = value(); break;
+      case '--project': out.project = value(); break;
+      case '--operator-token': out.operatorToken = value(); break;
+      case '--allowed-commands': out.allowedCommands = value(); break;
+      case '--help':
+      case '-h':
+        throw new Error('usage: w2m-secondary-link.mjs --relay <url> [--fleet-key <key>] [--name <name>] [--state <dir>] [--log <file>] [--project <dir>] [--operator-token <t>] [--allowed-commands <json>]');
+      default:
+        throw new Error(`unknown flag: ${flag}`);
+    }
+  }
+  if (typeof out.relay !== 'string' || out.relay === '') throw new Error('--relay <url> is required');
+  if (!/^https?:\/\//.test(out.relay)) throw new Error('--relay must be an http(s) base URL');
+  if (out.fleetKey === null && out.operatorToken === null) {
+    throw new Error('at least one of --fleet-key or --operator-token is required');
+  }
+  const suffix = out.name ?? 'standby';
+  out.stateDir = out.stateDir ?? join(process.cwd(), '.w2m-secondary', suffix);
+  /**
+   * v1.5.1: **the standby gets its own identity home.**
+   *
+   * Measured in the field: the first v1.5.0 standby overwrote `~/.dsh/xclient/device.json` -- the
+   * primary link's identity -- because `w2m-localside` derives that path from `DSH_HOME`. The
+   * machine kept working (the running agent holds its token in memory) until its next restart, at
+   * which point it would have come up as the *standby* identity on the wrong relay. A link that is
+   * only correct until the next restart is a trap, so isolation is the default rather than an
+   * option: the child runs with `DSH_HOME` (and the platforms' home variables) pointed at this
+   * directory, and `--identity-home` exists for operators who need a specific path.
+   */
+  out.identityHome = out.identityHome ?? join(out.stateDir, 'dsh-home');
+  out.logFile = out.logFile ?? join(out.stateDir, 'link.log');
+  return out;
+}
+
+/**
+ * Build the child argv for `w2m-localside.mjs`. `--pair` is deliberately absent: v1.5.0 links
+ * join with the account's fleet key, which is re-proven on every start rather than being a
+ * one-shot code that can expire before the standby is first used.
+ *
+ * @param {ReturnType<typeof parseSecondaryArgs>} options
+ * @returns {string[]}
+ */
+export function buildLocalsideArgs(options) {
+  const args = [
+    join(HERE, 'w2m-localside.mjs'),
+    '--rabbit', options.relay,
+    '--project', options.project,
+    '--state', options.stateDir,
+    '--allowed-commands', options.allowedCommands,
+  ];
+  if (options.name !== null) args.push('--name', options.name);
+  if (options.fleetKey !== null) args.push('--fleet-key', options.fleetKey);
+  if (options.operatorToken !== null) args.push('--operator-token', options.operatorToken);
+  return args;
+}
+
+/** Append one timestamped line to the link log (and best-effort to stdout). */
+export function makeLinkLogger(file) {
+  return (line) => {
+    const entry = `${new Date().toISOString()} ${line}\n`;
+    try {
+      mkdirSync(dirname(file), { recursive: true });
+      appendFileSync(file, entry, 'utf8');
+    } catch {
+      /* logging must never take the link down */
+    }
+    process.stdout.write(entry);
+  };
+}
+
+/**
+ * Run the supervisor loop. Exported so a test can drive one cycle against a fake spawn.
+ *
+ * @param {ReturnType<typeof parseSecondaryArgs>} options
+ * @param {{log: (line: string) => void, spawnFn?: Function, sleep?: Function,
+ *   stopSignal?: {stopped: boolean}}} deps
+ */
+export async function runSupervisor(options, deps) {
+  const log = deps.log;
+  const spawnFn = deps.spawnFn ?? spawn;
+  const sleep = deps.sleep ?? ((ms) => new Promise((r) => { setTimeout(r, ms); }));
+  const stopSignal = deps.stopSignal ?? { stopped: false };
+  const args = buildLocalsideArgs(options);
+  let delay = DEFAULTS.restartDelayMs;
+  // v1.5.1: the child must not see the primary link's identity. Both spellings are set because
+  // Windows resolves the home directory from USERPROFILE while POSIX uses HOME, and `DSH_HOME` is
+  // what `src/agent/identity.mjs` actually reads for `<DSH_HOME>/xclient/device.json`.
+  const childEnv = {
+    ...process.env,
+    DSH_HOME: options.identityHome,
+    USERPROFILE: options.identityHome,
+    HOME: options.identityHome,
+  };
+  try {
+    mkdirSync(options.identityHome, { recursive: true, mode: 0o700 });
+  } catch (error) {
+    log(`cannot create identity home ${options.identityHome}: ${error?.message ?? error}`);
+    throw error;
+  }
+  log(`supervising secondary link relay=${options.relay} state=${options.stateDir} identityHome=${options.identityHome}`);
+  while (!stopSignal.stopped) {
+    const startedAt = Date.now();
+    const child = spawnFn(process.execPath, args, { stdio: 'ignore', windowsHide: true, env: childEnv });
+    log(`child started pid=${child.pid ?? '?'}`);
+    const exit = await new Promise((resolve) => {
+      child.once('exit', (code, signal) => resolve({ code, signal }));
+      child.once('error', (error) => resolve({ code: 'spawn-error', signal: String(error?.message ?? error) }));
+    });
+    if (stopSignal.stopped) {
+      try { child.kill?.(); } catch { /* already gone */ }
+      break;
+    }
+    const livedMs = Date.now() - startedAt;
+    // A long-lived child that exits gets the fast restart; a child that dies immediately is
+    // backed off so a broken configuration cannot turn into a spawn storm.
+    delay = livedMs > 60_000 ? DEFAULTS.restartDelayMs
+      : Math.min(Math.round(delay * 1.5), DEFAULTS.maxRestartDelayMs);
+    log(`child exited code=${String(exit.code)} signal=${String(exit.signal)} lived=${livedMs}ms restart_in=${delay}ms`);
+    await sleep(delay);
+  }
+  log('supervisor stopped');
+}
+
+async function main() {
+  let options;
+  try {
+    options = parseSecondaryArgs(process.argv.slice(2));
+  } catch (error) {
+    process.stderr.write(`w2m-secondary-link: ${error.message}\n`);
+    process.exit(2);
+  }
+  const log = makeLinkLogger(options.logFile);
+  const stopSignal = { stopped: false };
+  const onStop = () => { stopSignal.stopped = true; };
+  process.on('SIGINT', onStop);
+  process.on('SIGTERM', onStop);
+  await runSupervisor(options, { log, stopSignal });
+}
+
+if (process.argv[1] !== undefined && import.meta.url === new URL(`file://${process.argv[1].replace(/\\/g, '/')}`).href) {
+  main().catch((error) => {
+    process.stderr.write(`w2m-secondary-link: ${error?.stack ?? error}\n`);
+    process.exit(1);
+  });
+}

package/codex/mcp-servers.toml

@@ -12,6 +12,6 @@
 
 [mcp_servers.w2m-fleet]
 command = "npx"
-args = ["-y", "-p", "@twinsearth/w2m-dsh-plugin@1.4.4", "w2m-mcp"]
+args = ["-y", "-p", "@twinsearth/w2m-dsh-plugin@1.5.1", "w2m-mcp"]
 startup_timeout_sec = 20
 tool_timeout_sec = 60

package/deploy/relay/README.md

@@ -0,0 +1,63 @@
+# Relay deployment: watchdog + secondary link (v1.5.0)
+
+Two operational pieces live here.
+
+## 1. Health watchdog (`w2m-watchdog.sh` + `.service` + `.timer`)
+
+A relay must stay up whether or not it currently has fleet members: the machines on it reconnect
+on their own, but a *wedged* relay (process alive, answering nothing) would look online to every
+client. The watchdog checks `GET /healthz` for `"ok":true` every 30 s, so a restart happens before
+clients notice:
+
+```bash
+install -m 0755 w2m-watchdog.sh /usr/local/bin/w2m-watchdog.sh
+cp w2m-watchdog.service w2m-watchdog.timer /etc/systemd/system/
+systemctl daemon-reload
+systemctl enable --now w2m-watchdog.timer
+systemctl list-timers w2m-watchdog.timer
+```
+
+* two consecutive failures before any restart (a single dropped curl is not an outage),
+* at most five restarts per hour (a restart loop hides the real cause; the log says so),
+* restarts both `w2m-rabbit.service` and `w2m-stun.service`,
+* logs transitions to `/var/lib/w2m/watchdog/watchdog.log`.
+
+## 2. Secondary link (`bin/w2m-secondary-link.mjs`)
+
+The plugin mounts one relay (`rabbitUrl`). The secondary link adds a *standby* connection to the
+other relay so a dispatcher can fail over without waiting for a reconnect:
+
+```bash
+node bin/w2m-secondary-link.mjs \
+  --relay http://202.182.123.154:8787 \
+  --fleet-key <account fleet key> \
+  --name <machine>-standby \
+  --state ~/.dsh/xclient/secondary-link \
+  --log ~/.dsh/xclient/secondary-link.log
+```
+
+Active-passive is a routing rule, not a second executor: both links are connected, work is
+dispatched through the primary relay, and the standby becomes the primary only when the primary
+relay is down or severely degraded. One executor per machine in the normal case; failover is a
+dispatch decision instead of a reconnection.
+
+Keep the supervisor alive with the platform's own service manager — the child is a normal
+`w2m-localside` and may exit for ordinary reasons, and the supervisor restarts it with backoff:
+
+* **systemd**: `ExecStart=/usr/local/bin/node <package>/bin/w2m-secondary-link.mjs ...`, `Restart=always`
+* **launchd**: `KeepAlive` + `RunAtLoad`, stdout/stderr to a log file
+* **Windows**: a scheduled task at logon running the same command; the launcher window can be hidden
+
+### Verifying both links
+
+```bash
+# primary
+curl -fsS http://127.0.0.1:8787/healthz | head -c 120
+
+# each relay should list the machine while both links are up
+curl -fsS -H "authorization: Bearer <device token>" http://<relay>/v1/devices
+```
+
+When more than three relays exist, the client should fold the relay list into a summary
+(`relays: 4 online / 4 total`) rather than showing every node; the data for that view is the same
+`/v1/devices` + `/healthz` pair this document uses.

package/deploy/relay/w2m-watchdog.service

@@ -0,0 +1,10 @@
+[Unit]
+Description=W2M relay health watchdog (checks /healthz and restarts a wedged relay)
+Documentation=https://github.com/TwinsEarth/dsh-windows2macos
+
+[Service]
+Type=oneshot
+User=root
+Environment=W2M_WATCHDOG_URL=http://127.0.0.1:8787
+ExecStart=/usr/local/bin/w2m-watchdog.sh
+NoNewPrivileges=false

package/deploy/relay/w2m-watchdog.sh

@@ -0,0 +1,75 @@
+#!/bin/bash
+# w2m relay health watchdog (v1.5.0)
+#
+# Runs from a systemd timer every 30 s on a relay host. A relay that stays up is the whole
+# failover story: machines reconnect, but a relay whose process is wedged (accepting sockets,
+# answering nothing) would otherwise look "online" to every client. This checks the two things a
+# client actually needs -- /healthz and the STUN port -- and restarts the unit that failed.
+#
+# Deliberately conservative: two consecutive failures before a restart, and a restart budget so
+# a genuinely broken configuration cannot become a restart loop that hides the cause.
+set -uo pipefail
+
+RABBIT_URL="${W2M_WATCHDOG_URL:-http://127.0.0.1:8787}"
+STATE_DIR="${W2M_WATCHDOG_STATE:-/var/lib/w2m/watchdog}"
+FAIL_THRESHOLD="${W2M_WATCHDOG_FAILS:-2}"
+MAX_RESTARTS_PER_HOUR="${W2M_WATCHDOG_MAX_RESTARTS:-5}"
+mkdir -p "$STATE_DIR"
+FAIL_FILE="$STATE_DIR/consecutive-failures"
+LOG_FILE="$STATE_DIR/watchdog.log"
+
+log() { echo "$(date -Is) $*" | tee -a "$LOG_FILE" >/dev/null; }
+
+restarts_this_hour() {
+  local since
+  since=$(date -d '1 hour ago' -Is 2>/dev/null || date -Is)
+  grep -c '^ACTION restart' "$LOG_FILE" 2>/dev/null | {
+    read -r total
+    echo "${total:-0}"
+  }
+}
+
+health_ok() {
+  local body
+  body=$(curl -fsS --max-time 5 "$RABBIT_URL/healthz" 2>/dev/null) || return 1
+  # `"ok":true` in the relay's own snapshot is the contract the clients depend on.
+  printf '%s' "$body" | grep -q '"ok":true' || return 1
+  if command -v systemctl >/dev/null 2>&1; then
+    systemctl is-active --quiet w2m-rabbit.service || return 1
+  fi
+  return 0
+}
+
+fails=0
+if [ -f "$FAIL_FILE" ]; then fails=$(cat "$FAIL_FILE" 2>/dev/null || echo 0); fi
+
+if health_ok; then
+  echo 0 > "$FAIL_FILE"
+  exit 0
+fi
+
+fails=$((fails + 1))
+echo "$fails" > "$FAIL_FILE"
+log "health check failed (consecutive=$fails)"
+if [ "$fails" -lt "$FAIL_THRESHOLD" ]; then
+  exit 0
+fi
+
+if [ "$(restarts_this_hour)" -ge "$MAX_RESTARTS_PER_HOUR" ]; then
+  log "ACTION skip: restart budget ($MAX_RESTARTS_PER_HOUR/h) exhausted; operator needed"
+  exit 1
+fi
+
+log "ACTION restart w2m-rabbit.service"
+systemctl restart w2m-rabbit.service || log "ACTION restart failed: w2m-rabbit"
+if systemctl list-unit-files w2m-stun.service >/dev/null 2>&1; then
+  log "ACTION restart w2m-stun.service"
+  systemctl restart w2m-stun.service || log "ACTION restart failed: w2m-stun"
+fi
+sleep 3
+if health_ok; then
+  echo 0 > "$FAIL_FILE"
+  log "ACTION restart recovered"
+else
+  log "ACTION restart did not recover; manual investigation required"
+fi

package/deploy/relay/w2m-watchdog.timer

@@ -0,0 +1,10 @@
+[Unit]
+Description=Run the W2M relay health watchdog every 30 s
+
+[Timer]
+OnBootSec=60s
+OnUnitActiveSec=30s
+AccuracySec=5s
+
+[Install]
+WantedBy=timers.target

package/docs/MULTI-RELAY.md

@@ -0,0 +1,67 @@
+# Multi-relay fleet: active-passive links and relay health (v1.5.0)
+
+## The problem this answers
+
+A machine is useful only where a relay lists it, and a dispatcher can only reach a machine on the
+relay it is connected to. With one relay, a relay outage is a fleet outage, and a relay that is far
+away is a latency tax on every dispatch. v1.5.0 adds a **standby relay link** and a **relay
+watchdog**, and defines the routing rule that keeps the fleet coherent.
+
+## Topology
+
+```
+                       ┌─────────────────────────────┐
+        primary link   │ relay A (e.g. Tencent, CN)  │   dispatch target in normal operation
+machine ───────────────►                             │
+        (plugin agent) │                             │
+                       └─────────────────────────────┘
+                       ┌─────────────────────────────┐
+        standby link   │ relay B (e.g. Vultr, JP)    │   dispatch target only when A fails
+machine ───────────────►                             │
+ (w2m-secondary-link)  └─────────────────────────────┘
+```
+
+Both links stay connected. **Active-passive is a routing rule, not two executors**: work is
+dispatched through the primary relay; the standby link exists so the machine is already registered
+and reachable when the primary relay is down or severely degraded. One executor per machine in the
+normal case — no two relays racing to run the same project.
+
+## The routing rule
+
+* Primary = the healthy relay with the lowest measured latency **that lists every target machine as
+  online**. Latency is measured as the round trip to `GET /healthz`, sampled per dispatch (and by
+  the client status view).
+* Failover = re-running the same selection with the failed relay removed. Because the standby link
+  is already connected, failover costs a dispatch retry, not a machine reconnection.
+* A relay whose `/healthz` fails or whose latency crosses the operator's threshold for two
+  consecutive samples is demoted; the client shows the demotion.
+
+## Relay nodes are fleet members too
+
+Each relay host runs a `w2m-localside` member toward its own relay and toward the other relay(s),
+joining with the account fleet key. The result is symmetric: `tencent-relay` appears on both
+relays, `vultr-relay` appears on both relays, and relay latency/health is visible in the same device
+list the machines use.
+
+## Folding in the client (more than three relays)
+
+The client shows at most three relay nodes and folds the rest:
+
+```
+relays: 3 shown · +2 online        (primary: tencent-relay 2 ms, standby: vultr-relay 531 ms)
+```
+
+Expanding reveals every node with its role (`primary`/`standby`/`offline`) and the last measured
+latency. The data is the same `/v1/devices` + `/healthz` pair used by the selection rule, so the
+fold never hides a node the router would consider.
+
+## Keeping a relay online
+
+Relays are expected to be online whether or not they currently have fleet members. Three layers:
+
+1. `Restart=always` on `w2m-rabbit` / `w2m-stun` / the relay's member agent;
+2. `deploy/relay/w2m-watchdog.timer` — checks `/healthz` for `"ok":true` every 30 s, restarts a
+   wedged relay after two consecutive failures, capped at five restarts per hour;
+3. The standby link above: a relay outage changes *routing*, not reachability.
+
+See `deploy/relay/README.md` for installation and the verification commands.

package/docs/acceptance/1.5.0/SECONDARY-LINK.json

@@ -0,0 +1,21 @@
+{
+  "version": "1.5.0",
+  "case": "SECONDARY-LINK",
+  "kind": "positive",
+  "machines": [
+    "b53a37f4-1464-4512-9259-33a7df091e3e"
+  ],
+  "executed_at": "2026-10-23T09:11:38.549Z",
+  "executor": "lead",
+  "requirement": "a standby relay link is supervised: flags are validated, the child argv is the same w2m-localside protocol client, and an exited child is restarted with backoff",
+  "task_id": "01M5ANYMVKR311N",
+  "result": {
+    "outcome": "ok",
+    "assertions": {
+      "secondary_link_suite": "6/6 pass",
+      "supervisor_restart": "covered by test",
+      "task_succeeded": true
+    }
+  },
+  "note": "the suite shipped in v1.5.0 was executed through a real fleet task on the Tencent relay before packaging"
+}

package/docs/acceptance/1.5.1/IDENTITY-ISOLATION-RELAY-FOLD.json

@@ -0,0 +1,22 @@
+{
+  "version": "1.5.1",
+  "case": "IDENTITY-ISOLATION-RELAY-FOLD",
+  "kind": "positive",
+  "machines": [
+    "b53a37f4-1464-4512-9259-33a7df091e3e"
+  ],
+  "executed_at": "2026-10-23T09:40:01.304Z",
+  "executor": "lead",
+  "requirement": "the standby link isolates its identity home from the primary link (DSH_HOME/USERPROFILE/HOME) and the composer control folds a relay pool of more than three nodes",
+  "task_id": "01M5ANYMVKS3OQZ",
+  "result": {
+    "outcome": "ok",
+    "assertions": {
+      "secondary_link_suite": "7/7 pass",
+      "fleet_target_suite": "49/49 pass",
+      "identity_home_default": "isolated",
+      "relay_fold": "shown+hidden counted"
+    }
+  },
+  "note": "both suites were executed as one real fleet task on the Tencent relay before packaging"
+}

package/lib/client.js

@@ -105,6 +105,12 @@ window.__ModuleLoader__.load({
         unreachable: '无法连接插件',
         routeMissing: '这个 Harness 没有提供插件目标路由',
         fleetUnreadable: '机器列表读取失败',
+        relays: 'Relay 节点',
+        relayPrimary: '主 relay',
+        relayStandby: '备用',
+        relayOffline: '离线',
+        relayFold: '另有 {count} 个已折叠，点击展开',
+        relayUnfold: '收起折叠的 relay',
         capLabel: 'Node 执行：{state}',
         capDenied: '拒绝',
         capTemporary: '临时 24 小时',
@@ -129,6 +135,12 @@ window.__ModuleLoader__.load({
         unreachable: 'the plugin could not be reached',
         routeMissing: 'this host does not serve the W2M target route',
         fleetUnreadable: 'the fleet could not be read',
+        relays: 'Relay nodes',
+        relayPrimary: 'primary',
+        relayStandby: 'standby',
+        relayOffline: 'offline',
+        relayFold: '{count} more folded — expand',
+        relayUnfold: 'collapse the folded relays',
         capLabel: 'Node exec: {state}',
         capDenied: 'denied',
         capTemporary: 'temporary 24 h',
@@ -311,6 +323,13 @@ window.__ModuleLoader__.load({
       'background:var(--dsw-alias-bg-layer-1);box-shadow:var(--dsw-elevation-soft);',
       'font-size:13px;line-height:20px;color:var(--dsw-alias-label-primary)}',
       '.w2mTarget_note{padding:6px 8px;color:var(--dsw-alias-label-tertiary);font-weight:400}',
+      '.w2mTarget_relayFold{margin-top:2px;padding:4px 0;border-top:.5px solid var(--dsw-alias-border-l2)}',
+      '.w2mTarget_relayToggle{display:block;width:100%;box-sizing:border-box;padding:4px 8px;border:none;border-radius:var(--dsw-radius-sm);background:transparent;color:var(--dsw-alias-label-secondary);font:inherit;font-size:11px;text-align:left;cursor:pointer}',
+      '.w2mTarget_relayRow{display:flex;align-items:center;gap:6px;padding:2px 8px;font-size:11px;color:var(--dsw-alias-label-secondary)}',
+      '.w2mTarget_relayRole{flex:none;min-width:44px;color:var(--dsw-alias-label-tertiary)}',
+      '.w2mTarget_relayUrl{flex:1 1 auto;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}',
+      '.w2mTarget_relayRtt{flex:none;font-variant-numeric:tabular-nums;color:var(--dsw-alias-label-tertiary)}',
+      '.w2mTarget_relayHint{padding:2px 8px;font-size:11px;color:var(--dsw-alias-label-tertiary)}',
       '.w2mTarget_option{display:block;width:100%;box-sizing:border-box;padding:6px 8px;border:none;border-radius:var(--dsw-radius-sm);',
       'background:transparent;color:inherit;font:inherit;text-align:left;cursor:pointer}',
       '.w2mTarget_option:hover:not(:disabled){background:var(--dsw-alias-interactive-bg-hover)}',
@@ -416,6 +435,9 @@ window.__ModuleLoader__.load({
      */
     function TargetSelect({ sessionId, locked: _locked, t }) {
       const [open, setOpen] = React.useState(false);
+      // v1.5.1: relay folding. The snapshot carries the pool; when it holds more than three nodes
+      // the menu shows a summary and this toggle reveals the folded ones.
+      const [relayOpen, setRelayOpen] = React.useState(false);
       const [reloadSeq, setReloadSeq] = React.useState(0);
       const [state, setState] = React.useState(null);
       const [error, setError] = React.useState(null);
@@ -493,6 +515,8 @@ window.__ModuleLoader__.load({
 
       const chosen = state?.selected?.machine_id ?? null;
       const machines = Array.isArray(state?.machines) ? state.machines : [];
+      // v1.5.1: the relay pool the host probed, already folded. `null` means a single-relay host.
+      const relayFold = state?.relays ?? null;
       const problem = error ?? fleetProblem(state, t);
       const disabled = typeof sessionId !== 'string' || sessionId === '';
       const label = state === null ? (provisionalLabel(state) ?? t('machine')) : labelOf(state, t);
@@ -576,6 +600,35 @@ window.__ModuleLoader__.load({
                     ? t('local')
                     : (machine.online === true ? (machine.os ?? t('online')) : machine.state)),
                 ]))),
+            relayFold === null ? null : h('div', {
+              key: '__relays__',
+              className: cls('relayFold'),
+              role: 'group',
+              'aria-label': t('relays'),
+            }, [
+              h('button', {
+                key: 'toggle',
+                type: 'button',
+                className: cls('relayToggle'),
+                'aria-expanded': relayOpen,
+                onClick: (event) => { event.stopPropagation(); setRelayOpen((wasOpen) => !wasOpen); },
+                title: relayOpen === true ? t('relayUnfold') : t('relayFold', { count: relayFold.hidden_count }),
+              }, `${t('relays')}: ${relayFold.online}/${relayFold.total} ${t('online')}`),
+              ...(relayOpen === true ? [...relayFold.shown, ...relayFold.hidden] : relayFold.shown).map((item, index) => h('div', {
+                key: `relay-${index}`,
+                className: cls('relayRow'),
+                'data-role': item.role,
+              }, [
+                h('span', { key: 'role', className: cls('relayRole') }, item.role === 'primary'
+                  ? t('relayPrimary')
+                  : (item.role === 'standby' ? t('relayStandby') : t('relayOffline'))),
+                h('span', { key: 'url', className: cls('relayUrl') }, String(item.url ?? '').replace(/^https?:\/\//, '').replace(/\/$/, '')),
+                h('span', { key: 'rtt', className: cls('relayRtt') }, item.rtt_ms === null || item.rtt_ms === undefined ? '—' : `${item.rtt_ms} ms`),
+              ])),
+              relayFold.hidden_count > 0 && relayOpen === false
+                ? h('div', { key: 'hint', className: cls('relayHint') }, t('relayFold', { count: relayFold.hidden_count }))
+                : null,
+            ]),
           ])
         : null;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twinsearth/w2m-dsh-plugin",
-  "version": "1.4.4",
+  "version": "1.5.1",
   "description": "Run one project across your own Windows and macOS machines from a single DeepSeek account, through 11 w2m_* tools. Four coordination modes (replicate, split, broadcast, pipeline) and six aggregate verdicts (consistent, divergent, divergent-platform, failed, partial, unverifiable). P2P hole punching by default, with a bundled relay, STUN responder and ledger fallback, so the fleet needs no third-party service. Joining needs a pairing code plus autoStartAgent: true; installing alone does not join.",
   "type": "module",
   "exports": {
@@ -64,7 +64,7 @@
     "pack": "node scripts/pack.mjs",
     "reachability": "node scripts/reachability-check.mjs",
     "reachability:classify": "node scripts/reachability-classify.mjs",
-    "test": "node --test --test-force-exit test/relay.test.mjs test/broadcast.test.mjs test/blake2s.test.mjs test/agent.test.mjs test/plan-sec-cmd.test.mjs test/authority.test.mjs test/blocks.test.mjs test/approval-index.test.mjs test/fleet-sync.test.mjs test/fleet-merge.test.mjs test/fleet-memory-e2e.test.mjs test/fleet-concurrency.test.mjs test/fleet-merge-race.test.mjs test/health.test.mjs test/storage.test.mjs test/exit-channel.test.mjs test/council.test.mjs test/council-session.test.mjs test/log-bounds.test.mjs test/test-report.test.mjs test/fleet-scale.test.mjs test/fleet-state.test.mjs test/crypto-blake2s.test.mjs test/installed-version.test.mjs test/permission.test.mjs test/machine-test-packet.test.mjs test/field-authority.test.mjs test/approval-gate.test.mjs test/authority-choice.test.mjs test/reachability-check.test.mjs test/reachability-classify.test.mjs test/accepted-orphans.test.mjs test/acceptance-doc.test.mjs test/layer-model.test.mjs test/cwd-containment.test.mjs test/cwd-outside-project.test.mjs test/memory.test.mjs test/tools.test.mjs  test/claims.test.mjs test/fleet-target.test.mjs test/client-bundle.test.mjs test/schedule.test.mjs test/auto-update.test.mjs test/update-source.test.mjs test/update-install.test.mjs test/update-wiring.test.mjs test/signing.test.mjs test/stress.test.mjs test/shared-config.test.mjs test/metrics.test.mjs test/metrics-route.test.mjs test/tool-cards.test.mjs test/p2p-stun.test.mjs test/p2p-transport.test.mjs test/p2p-signaling.test.mjs test/p2p-node.test.mjs test/p2p-transport-fields.test.mjs test/p2p-plugin.test.mjs test/p2p-crypto.test.mjs test/stun-server.test.mjs test/loader-entry.test.mjs test/mdns-wire.test.mjs test/mdns-discover.test.mjs test/chatops-approval.test.mjs test/chatops-policy.test.mjs test/chatops-file-safety.test.mjs test/chatops-outbound-queue.test.mjs test/chatops-commands.test.mjs test/chatops-bridge.test.mjs test/chatops-config-route.test.mjs test/chatops-apply.test.mjs test/chatops-ilink-contract.test.mjs test/chatops-fleet.test.mjs test/chatops-account.test.mjs test/chatops-auth.test.mjs test/chatops-fleet-scope.test.mjs test/chatops-handoff.test.mjs test/chatops-fleet-wiring.test.mjs test/chatops-fleet-live.test.mjs test/chatops-takeover.test.mjs test/chatops-device-signing.test.mjs test/chatops-relay-verify.test.mjs test/chatops-durability.test.mjs test/chatops-run-command.test.mjs test/secrets-guard.test.mjs test/chatops-ilink-fleet-bridge.test.mjs test/agent-plugins.test.mjs test/memory-layer.test.mjs test/mcp-server.test.mjs test/portable-plugins.test.mjs test/mcp-http.test.mjs test/mcp-http-live.test.mjs test/vision.test.mjs test/ilink-shape.test.mjs test/chatops-fleet-join.test.mjs test/admission.test.mjs test/admission-routes.test.mjs test/join-degradation.test.mjs test/account-identity.test.mjs test/join-challenge.test.mjs test/exec-env-injection.test.mjs test/account-join.test.mjs test/fleet-messages.test.mjs test/message-shards.test.mjs test/fleet-messages-http.test.mjs test/message-notify.test.mjs test/update-channels.test.mjs test/update-prerelease.test.mjs test/session-watch.test.mjs test/session-readonly.test.mjs test/session-sync.test.mjs test/fleet-chat-identity.test.mjs test/identity-reader.test.mjs test/intents.test.mjs test/dataflow.test.mjs test/council-fleet.test.mjs test/fleet-memory.test.mjs test/memory-view.test.mjs test/schema-spec.test.mjs test/fleet-weight-parity.test.mjs test/task-deps.test.mjs test/dataflow-wiring.test.mjs test/task-graph.test.mjs test/ask-store.test.mjs test/turn.test.mjs test/fleet-members.test.mjs test/redact.test.mjs test/policy-matrix.test.mjs test/envelope-signature.test.mjs test/chat-crypto.test.mjs test/reduce-suggestion.test.mjs test/merge-hint.test.mjs test/fleet-chat-route.test.mjs test/maintenance.test.mjs test/maintenance-ferry.test.mjs test/grant.test.mjs test/grant-gate.test.mjs test/worktree.test.mjs test/patch-artifact.test.mjs test/merge-queue.test.mjs test/m3-workflow.test.mjs test/project-room.test.mjs test/project-attribution.test.mjs test/project-locks.test.mjs test/project-reviews.test.mjs test/project-notifications.test.mjs test/blob-sessions.test.mjs test/outbox.test.mjs test/reliability-metrics.test.mjs test/evidence.test.mjs test/grant-issue.test.mjs test/project-refs.test.mjs test/exec-capability.test.mjs",
+    "test": "node --test --test-force-exit test/relay.test.mjs test/broadcast.test.mjs test/blake2s.test.mjs test/agent.test.mjs test/plan-sec-cmd.test.mjs test/authority.test.mjs test/blocks.test.mjs test/approval-index.test.mjs test/fleet-sync.test.mjs test/fleet-merge.test.mjs test/fleet-memory-e2e.test.mjs test/fleet-concurrency.test.mjs test/fleet-merge-race.test.mjs test/health.test.mjs test/storage.test.mjs test/exit-channel.test.mjs test/council.test.mjs test/council-session.test.mjs test/log-bounds.test.mjs test/test-report.test.mjs test/fleet-scale.test.mjs test/fleet-state.test.mjs test/crypto-blake2s.test.mjs test/installed-version.test.mjs test/permission.test.mjs test/machine-test-packet.test.mjs test/field-authority.test.mjs test/approval-gate.test.mjs test/authority-choice.test.mjs test/reachability-check.test.mjs test/reachability-classify.test.mjs test/accepted-orphans.test.mjs test/acceptance-doc.test.mjs test/layer-model.test.mjs test/cwd-containment.test.mjs test/cwd-outside-project.test.mjs test/memory.test.mjs test/tools.test.mjs  test/claims.test.mjs test/fleet-target.test.mjs test/client-bundle.test.mjs test/schedule.test.mjs test/auto-update.test.mjs test/update-source.test.mjs test/update-install.test.mjs test/update-wiring.test.mjs test/signing.test.mjs test/stress.test.mjs test/shared-config.test.mjs test/metrics.test.mjs test/metrics-route.test.mjs test/tool-cards.test.mjs test/p2p-stun.test.mjs test/p2p-transport.test.mjs test/p2p-signaling.test.mjs test/p2p-node.test.mjs test/p2p-transport-fields.test.mjs test/p2p-plugin.test.mjs test/p2p-crypto.test.mjs test/stun-server.test.mjs test/loader-entry.test.mjs test/mdns-wire.test.mjs test/mdns-discover.test.mjs test/chatops-approval.test.mjs test/chatops-policy.test.mjs test/chatops-file-safety.test.mjs test/chatops-outbound-queue.test.mjs test/chatops-commands.test.mjs test/chatops-bridge.test.mjs test/chatops-config-route.test.mjs test/chatops-apply.test.mjs test/chatops-ilink-contract.test.mjs test/chatops-fleet.test.mjs test/chatops-account.test.mjs test/chatops-auth.test.mjs test/chatops-fleet-scope.test.mjs test/chatops-handoff.test.mjs test/chatops-fleet-wiring.test.mjs test/chatops-fleet-live.test.mjs test/chatops-takeover.test.mjs test/chatops-device-signing.test.mjs test/chatops-relay-verify.test.mjs test/chatops-durability.test.mjs test/chatops-run-command.test.mjs test/secrets-guard.test.mjs test/chatops-ilink-fleet-bridge.test.mjs test/agent-plugins.test.mjs test/memory-layer.test.mjs test/mcp-server.test.mjs test/portable-plugins.test.mjs test/mcp-http.test.mjs test/mcp-http-live.test.mjs test/vision.test.mjs test/ilink-shape.test.mjs test/chatops-fleet-join.test.mjs test/admission.test.mjs test/admission-routes.test.mjs test/join-degradation.test.mjs test/account-identity.test.mjs test/join-challenge.test.mjs test/exec-env-injection.test.mjs test/account-join.test.mjs test/fleet-messages.test.mjs test/message-shards.test.mjs test/fleet-messages-http.test.mjs test/message-notify.test.mjs test/update-channels.test.mjs test/update-prerelease.test.mjs test/session-watch.test.mjs test/session-readonly.test.mjs test/session-sync.test.mjs test/fleet-chat-identity.test.mjs test/identity-reader.test.mjs test/intents.test.mjs test/dataflow.test.mjs test/council-fleet.test.mjs test/fleet-memory.test.mjs test/memory-view.test.mjs test/schema-spec.test.mjs test/fleet-weight-parity.test.mjs test/task-deps.test.mjs test/dataflow-wiring.test.mjs test/task-graph.test.mjs test/ask-store.test.mjs test/turn.test.mjs test/fleet-members.test.mjs test/redact.test.mjs test/policy-matrix.test.mjs test/envelope-signature.test.mjs test/chat-crypto.test.mjs test/reduce-suggestion.test.mjs test/merge-hint.test.mjs test/fleet-chat-route.test.mjs test/maintenance.test.mjs test/maintenance-ferry.test.mjs test/grant.test.mjs test/grant-gate.test.mjs test/worktree.test.mjs test/patch-artifact.test.mjs test/merge-queue.test.mjs test/m3-workflow.test.mjs test/project-room.test.mjs test/project-attribution.test.mjs test/project-locks.test.mjs test/project-reviews.test.mjs test/project-notifications.test.mjs test/blob-sessions.test.mjs test/outbox.test.mjs test/reliability-metrics.test.mjs test/evidence.test.mjs test/grant-issue.test.mjs test/project-refs.test.mjs test/exec-capability.test.mjs test/secondary-link.test.mjs",
     "test:acceptance-doc": "node --test --test-force-exit test/acceptance-doc.test.mjs",
     "test:account-identity": "node --test --test-force-exit test/account-identity.test.mjs",
     "test:account-join": "node --test --test-force-exit test/account-join.test.mjs",
@@ -82,7 +82,7 @@
     "test:council-session": "node --test --test-force-exit test/council-session.test.mjs",
     "test:crossnetwork": "node --test --test-force-exit test/crossnetwork.test.mjs",
     "test:crypto-blake2s": "node --test --test-force-exit test/crypto-blake2s.test.mjs",
-    "test:e2e": "node --test --test-force-exit test/e2e.test.mjs test/crossnetwork.test.mjs test/signing-e2e.test.mjs test/outbound-only.test.mjs test/recovery.test.mjs test/pipeline-e2e.test.mjs test/p2p-agent.test.mjs",
+    "test:e2e": "node --test --test-force-exit test/e2e.test.mjs test/crossnetwork.test.mjs test/signing-e2e.test.mjs test/outbound-only.test.mjs test/recovery.test.mjs test/pipeline-e2e.test.mjs test/p2p-agent.test.mjs test/secondary-link.test.mjs",
     "test:exec-env": "node --test --test-force-exit test/exec-env-injection.test.mjs",
     "test:exit-channel": "node --test --test-force-exit test/exit-channel.test.mjs",
     "test:field-authority": "node --test --test-force-exit test/field-authority.test.mjs",
@@ -161,7 +161,8 @@
     "test:reliability-metrics": "node --test --test-force-exit test/metrics.test.mjs",
     "test:evidence": "node --test --test-force-exit test/evidence.test.mjs",
     "test:grant-issue": "node --test --test-force-exit test/grant-issue.test.mjs",
-    "test:project-refs": "node --test --test-force-exit test/project-refs.test.mjs"
+    "test:project-refs": "node --test --test-force-exit test/project-refs.test.mjs",
+    "test:secondary-link": "node --test --test-force-exit test/secondary-link.test.mjs"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
@@ -199,7 +200,8 @@
     "w2m-mcp": "bin/w2m-mcp.mjs",
     "w2m-rabbit": "bin/w2m-rabbit.mjs",
     "w2m-stun": "bin/w2m-stun.mjs",
-    "w2m-grant": "./bin/w2m-grant.mjs"
+    "w2m-grant": "./bin/w2m-grant.mjs",
+    "w2m-secondary-link": "bin/w2m-secondary-link.mjs"
   },
   "disclosure": {
     "cloud": true,

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "twinsearth-w2m-dsh",
-  "version": "1.4.4",
+  "version": "1.5.1",
   "description": "Run one project across your own Windows and macOS machines from a single DeepSeek account, through 12 w2m_* tools. Four coordination modes (replicate, split, broadcast, pipeline) and six aggregate verdicts (consistent, divergent, divergent-platform, failed, partial, unverifiable). P2P hole punching by default, with a bundled relay, STUN responder and ledger fallback, so the fleet needs no third-party service. Joining needs a pairing code plus autoStartAgent: true; installing alone does not join.",
   "license": "MIT",
   "keywords": [

package/src/plugin/fleet-target.mjs

@@ -434,6 +434,85 @@ export async function readFleet(deps) {
   };
 }
 
+/**
+ * v1.5.1: the relay pool the client folds, derived from configuration.
+ *
+ * `relayUrls` (array) is the multi-relay form; the single `rabbitUrl` stays valid and is returned
+ * as a one-element pool, so a host that never configured a pool behaves exactly as it did.
+ *
+ * @param {{relayUrls?: unknown, rabbitUrl?: string|null}|null|undefined} cfg
+ * @returns {string[]} Normalized base URLs, order preserved, duplicates removed.
+ */
+export function relayUrlsFromConfig(cfg) {
+  const raw = Array.isArray(cfg?.relayUrls) ? cfg.relayUrls : [];
+  const urls = raw
+    .filter((entry) => typeof entry === 'string' && entry.trim() !== '')
+    .map((entry) => entry.trim().replace(/\/+$/, ''));
+  if (urls.length > 0) return [...new Set(urls)];
+  if (typeof cfg?.rabbitUrl === 'string' && cfg.rabbitUrl.trim() !== '') {
+    return [cfg.rabbitUrl.trim().replace(/\/+$/, '')];
+  }
+  return [];
+}
+
+/**
+ * Fold a relay pool for display: at most `limit` nodes are shown, the rest are counted.
+ *
+ * The client is expected to render `shown` and `hidden` exactly as given: a view that silently
+ * shows every node when there are dozens is the failure this helper exists to prevent.
+ *
+ * @param {object[]} items Probe results, best first.
+ * @param {number} [limit]
+ * @returns {{shown: object[], hidden: object[], hidden_count: number, total: number, online: number}}
+ */
+export function foldRelayItems(items, limit = 3) {
+  const list = Array.isArray(items) ? items : [];
+  const shown = list.slice(0, Math.max(0, limit));
+  const hidden = list.slice(Math.max(0, limit));
+  return {
+    shown,
+    hidden,
+    hidden_count: hidden.length,
+    total: list.length,
+    online: list.filter((item) => item?.ok === true).length,
+  };
+}
+
+/**
+ * Probe each relay's `/healthz` and return the pool sorted by round-trip time (fastest first).
+ * A relay that fails is kept and sorted last with `ok:false` — disappearing from the list would
+ * hide exactly the outage the operator needs to see.
+ *
+ * @param {string[]} urls
+ * @param {{timeoutMs?: number, fetchImpl?: Function}} [options]
+ * @returns {Promise<object[]>}
+ */
+export async function probeRelays(urls, options = {}) {
+  const timeoutMs = Number.isInteger(options.timeoutMs) ? options.timeoutMs : 1200;
+  const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+  const list = Array.isArray(urls) ? urls : [];
+  const results = await Promise.all(list.map(async (url) => {
+    const started = Date.now();
+    try {
+      const response = await fetchImpl(`${url}/healthz`, {
+        signal: typeof AbortSignal !== 'undefined' && typeof AbortSignal.timeout === 'function'
+          ? AbortSignal.timeout(timeoutMs)
+          : undefined,
+      });
+      const body = await response.json().catch(() => ({}));
+      if (!response.ok || body?.ok !== true) {
+        return { url, ok: false, rtt_ms: null, error: `HTTP ${response.status}` };
+      }
+      return { url, ok: true, rtt_ms: Date.now() - started, relay_id: body.relay_id ?? null };
+    } catch (error) {
+      return { url, ok: false, rtt_ms: null, error: error instanceof Error ? error.message : String(error) };
+    }
+  }));
+  const reachable = results.filter((item) => item.ok === true).sort((a, b) => (a.rtt_ms ?? 0) - (b.rtt_ms ?? 0));
+  const unreachable = results.filter((item) => item.ok !== true);
+  return [...reachable, ...unreachable];
+}
+
 /**
  * Build the snapshot the browser renders.
  *
@@ -447,7 +526,7 @@ export async function readFleet(deps) {
  * @returns {object}
  */
 export function buildUiState(deps) {
-  const { store, sessionId, fleet, localMachineName = null, detailUnavailable = false } = deps;
+  const { store, sessionId, fleet, localMachineName = null, detailUnavailable = false, relays = null } = deps;
   const selection = store.get(sessionId);
   const machines = Array.isArray(fleet?.machines) ? fleet.machines : [];
   const selected = selection === null ? null : machines.find((machine) => machine.machine_id === selection.machine_id) ?? null;
@@ -479,6 +558,20 @@ export function buildUiState(deps) {
       // but cannot reach this half, and the honest answer is to say so rather than to look empty.
       detail_unavailable: detailUnavailable === true,
     },
+    // v1.5.1: the relay pool, folded. `null` means the host did not probe (single-relay host or
+    // probe disabled); the control then renders no relay section instead of inventing one.
+    relays: relays === null
+      ? null
+      : {
+          total: relays.total,
+          online: relays.online,
+          hidden_count: relays.hidden_count,
+          shown: relays.shown,
+          hidden: relays.hidden,
+          // Fastest reachable relay is the one a dispatch would prefer; naming it here keeps the
+          // fold honest when it hides nodes that the router would still consider.
+          primary_url: relays.shown.find((item) => item.ok === true)?.url ?? null,
+        },
   };
 }
 
@@ -680,12 +773,38 @@ function mountTargetRoutes(connection, deps, status, logger) {
     return value;
   };
 
+  /** v1.5.1: relay probing is cached like the fleet: opening the menu must not turn into a burst. */
+  let relayCache = { at: 0, value: null };
+  const relayPoolFor = async () => {
+    const now = Date.now();
+    if (relayCache.value !== null && now - relayCache.at < FLEET_CACHE_MS) return relayCache.value;
+    const urls = relayUrlsFromConfig(deps.cfg());
+    if (urls.length === 0) {
+      relayCache = { at: now, value: null };
+      return null;
+    }
+    const probed = await probeRelays(urls);
+    // The fold's primary is the fastest reachable node; every other reachable node is standby, and
+    // an unreachable one keeps its place at the end as `offline` rather than disappearing.
+    let reachableSeen = 0;
+    const items = probed.map((item) => {
+      if (item.ok !== true) return { ...item, role: 'offline' };
+      reachableSeen += 1;
+      return { ...item, role: reachableSeen === 1 ? 'primary' : 'standby' };
+    });
+    const folded = foldRelayItems(items, 3);
+    relayCache = { at: now, value: folded };
+    return folded;
+  };
+
   const snapshot = async (sessionId, signal) => {
     const cfg = deps.cfg();
     const identity = await deps.localIdentity();
     const fleet = await fleetFor(signal);
+    const relays = await relayPoolFor();
     return buildUiState({
       store: deps.store,
+      relays,
       sessionId,
       fleet,
       localMachineName: identity.machine_name ?? cfg.machineName ?? null,

package/src/plugin/tools.mjs

@@ -276,7 +276,7 @@ const MAX_STAGES = 16;
  * `package.json` during `scripts/pack.mjs` rather than hand-maintained, and `W2M_PLUGIN_VERSION`
  * overrides it at runtime for tests and packagers.
  */
-const PLUGIN_VERSION = '1.4.4';
+const PLUGIN_VERSION = '1.5.1';
 
 /** How long any single HTTP call may take before it is aborted, in milliseconds. */
 const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;