@twinsearth/w2m-dsh-plugin 1.4.3 → 1.5.0

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.3"
+    "version": "1.5.0"
   },
   "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.3",
+      "version": "1.5.0",
       "author": {
         "name": "TwinsEarth"
       },
@@ -26,5 +26,5 @@
       ]
     }
   ],
-  "version": "1.4.3"
+  "version": "1.5.0"
 }

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.3",
+  "version": "1.5.0",
   "author": {
     "name": "TwinsEarth"
   },

package/CHANGELOG.md

@@ -7,6 +7,38 @@
 
 All notable changes to this project are documented here.
 
+## [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）。**
+
+- 持久化修复：`devices.json` 快照新增 `fleet_id` / `fleet_source`，`restore()` 同步恢复。
+  在此之前，relay 重启后设备全在、token 仍有效，但每台设备的 fleet 归属全变成 null——
+  编队"静默消失"且没有任何错误可看（本次在共享 relay 上实测复现）。
+- 桥接 getupdates 看门狗：空闲时每 10 分钟输出 `polling ... connection live`；
+  40s 长轮询超时明确记录 `poll timeout after 40s -- reconnecting`；
+  连续 5 分钟没有一次成功轮询则退出（exit 3），由 launchd KeepAlive / systemd Restart= 拉起新连接，
+  避免"进程活着但没人知道它是否还在轮询"的静默状态。
+- 测试：relay 新增 fleet 重启往返用例（pair by fleet_key → 重启 → fleet_id/fleet_source 保留）；
+  bridge 套件 36/36；门禁 GREEN ×2。
+- 证据：docs/acceptance/1.4.4/FLEET-PERSISTENCE.json（真实 fleet task `01M5FLEETPERSIST0000000002`）。
+
 ## [1.4.3] — 2026-10-22
 
 **微信编队桥接：回复可靠性修复（不回复/静默问题）。**

package/bin/w2m-secondary-link.mjs

@@ -0,0 +1,206 @@
+#!/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,
+  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,
+    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 '--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);
+  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;
+  log(`supervising secondary link relay=${options.relay} state=${options.stateDir}`);
+  while (!stopSignal.stopped) {
+    const startedAt = Date.now();
+    const child = spawnFn(process.execPath, args, { stdio: 'ignore', windowsHide: true });
+    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.3", "w2m-mcp"]
+args = ["-y", "-p", "@twinsearth/w2m-dsh-plugin@1.5.0", "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.4.4/FLEET-PERSISTENCE.json

@@ -0,0 +1,20 @@
+{
+  "version": "1.4.4",
+  "case": "FLEET-PERSISTENCE",
+  "kind": "positive",
+  "machines": [
+    "d89d5817-953d-4571-883d-23800e67d20c"
+  ],
+  "executed_at": "2026-10-22T16:32:38.180Z",
+  "executor": "lead",
+  "requirement": "a relay restart keeps every device in the fleet it was paired into: devices.json persists fleet_id/fleet_source and restore rebuilds them",
+  "task_id": "01M5FLEETPERSIST0000000002",
+  "result": {
+    "outcome": "ok",
+    "assertions": {
+      "fleet_roundtrip_test": "pass",
+      "node_test_exit": 0
+    }
+  },
+  "note": "executed as a real fleet task (node --test, fleet round-trip case) on the local machine before packaging"
+}

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twinsearth/w2m-dsh-plugin",
-  "version": "1.4.3",
+  "version": "1.5.0",
   "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.3",
+  "version": "1.5.0",
   "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/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.3';
+const PLUGIN_VERSION = '1.5.0';
 
 /** How long any single HTTP call may take before it is aborted, in milliseconds. */
 const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;

package/src/relay/persistence.mjs

@@ -213,6 +213,18 @@ export class Persistence {
         device_token: d.device_token ?? null,
         paired_at: rfc3339(d.paired_at_ms ?? this._now()),
         re_paired: d.re_paired === true,
+        /**
+         * v1.4.4: **the fleet binding is part of the device, so it must survive a restart.**
+         *
+         * Measured on the shared relay (2026-10-23): a relay restart came back with every device
+         * present and every fleet assignment gone, because this snapshot did not carry the two
+         * fields the pairing decision had produced. The devices were still authorised, so nothing
+         * looked broken -- they simply stopped being in a fleet, which is the one thing the fleet
+         * key had been bought to guarantee. `fleet_id` is a derived hash (not a secret) and
+         * `fleet_source` is the provenance that makes a wrong binding visible.
+         */
+        fleet_id: d.fleet_id ?? null,
+        fleet_source: d.fleet_source ?? null,
       };
     }
     const body = JSON.stringify(out, null, 2);

package/src/relay/state.mjs

@@ -750,6 +750,11 @@ export class RabbitState {
           device_token: typeof d.device_token === 'string' ? d.device_token : null,
           paired_at_ms: Number.isFinite(pairedAt) ? pairedAt : this.nowMs(),
           re_paired: d.re_paired === true,
+          // v1.4.4: restore the fleet binding with the device. Without this the snapshot brought the
+          // device back but dropped the fleet it was paired into, so a restart silently un-joined
+          // every machine while leaving it fully authorised (measured 2026-10-23 on the shared relay).
+          fleet_id: typeof d.fleet_id === 'string' && d.fleet_id !== '' ? d.fleet_id : null,
+          fleet_source: typeof d.fleet_source === 'string' && d.fleet_source !== '' ? d.fleet_source : null,
           last_seen_at_ms: this.nowMs(),
           // a snapshot proves the device exists, not that it is connected
           online: false,