@twinsearth/w2m-dsh-plugin 1.6.5 → 1.6.7

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.6.5"
+    "version": "1.6.7"
   },
   "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.6.5",
+      "version": "1.6.7",
       "author": {
         "name": "TwinsEarth"
       },
@@ -26,5 +26,5 @@
       ]
     }
   ],
-  "version": "1.6.5"
+  "version": "1.6.7"
 }

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

package/CHANGELOG.md

@@ -7,6 +7,36 @@
 
 All notable changes to this project are documented here.
 
+## [1.6.7] — 2026-10-24
+
+**修复 v1.6.6 failover 的阻塞 bug：远端 relay 模式下清理函数抛错，切换后无法重启 stack。**
+
+现场演练（停主 relay 180s）暴露：机器掉线后没有切到备用，恢复主 relay 后才重新上线。根因：
+
+- `startLocalStack` 的清理函数无条件执行 `await relay.close()`；而 `relay` 只在"本进程自建本地 relay"
+  时才非空，远端 relay 模式下是 `null` → 抛 TypeError；
+- failover 的切换流程 `await stop()` 抛错后被 catch 吞掉，**后续的 restart 从未执行**（stack 停了没起来）。
+
+修复：
+- 清理函数 null-safe/idempotent：仅当 `relay` 是带 `close()` 的对象才调用；`agent.stop()` 失败也继续清理。
+- 切换流程：`stop()` 失败不再跳过 restart；并写诊断日志 `xclient/relay-failover.log`（每轮探测/切换/重启错误）。
+- 测试：relay-failover 5/5、relay 200/200；证据 `docs/acceptance/1.6.7/FAILOVER-CLEANUP-FIX.json`
+  （fleet task `01M5ANYMVMFSSP3`）。
+## [1.6.6] — 2026-10-24
+
+**relay 自动 failover：主 relay 故障时自动切到备用，恢复后自动切回。**
+
+现场事故（2026-10-24）：主 relay 主机整体不可达（8787 与 SSH 22 都超时），备用 relay 一直健康，
+但每台机器仍死连主 relay——备用链路只是常驻成员，不会接管，编队停摆。
+
+- 新增 `src/plugin/relay-failover.mjs`：非对称滞回状态机（**连续 3 次**探测失败才切走，**连续 5 次**
+  健康才切回；没有可达备选则不切）。纯函数，边界可单测。
+- `startLocalStack` 外包一层 `startFailoverStack`：每 10s 探测池内各 relay `/healthz`；
+  决策为切换时，停止当前 in-process stack，把 `cfg.rabbitUrl` 设为备 relay 并重启 stack——
+  **切换是重新入队（fleet key 重新配对），不是重连**（device token 是按 relay 签发的）。
+- `w2m_status` 新增 `failover` 快照：primary/active/pool、失败计数、切换次数、最近切换原因与历史。
+- 测试：relay-failover 5/5、relay 200/200；证据 `docs/acceptance/1.6.6/RELAY-FAILOVER.json`
+  （fleet task `01M5ANYMVM9GEKQ`）。
 ## [1.6.5] — 2026-10-24
 
 **Windows 后台自动化不再弹窗：VBScript 隐藏包装 + 计划任务工具 + 文档。**

package/codex/mcp-servers.toml

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

package/docs/acceptance/1.6.6/RELAY-FAILOVER.json

@@ -0,0 +1,22 @@
+{
+  "version": "1.6.6",
+  "case": "RELAY-FAILOVER",
+  "kind": "positive",
+  "machines": [
+    "b53a37f4-1464-4512-9259-33a7df091e3e"
+  ],
+  "executed_at": "2026-10-24T10:33:27.234Z",
+  "executor": "lead",
+  "requirement": "when the active relay is unreachable for 3 consecutive probes the plugin moves its in-process stack to the next healthy relay in the pool (re-joining through the fleet key), and returns to the primary after 5 consecutive healthy probes",
+  "task_id": "01M5ANYMVM9GEKQ",
+  "result": {
+    "outcome": "ok",
+    "assertions": {
+      "failover_suite": "5/5 pass",
+      "hysteresis": "3 failures to leave, 5 successes to return",
+      "no_alternative": "stays put",
+      "status": "failover snapshot exposed"
+    }
+  },
+  "note": "suites ran as a real fleet task; live drill follows the release"
+}

package/docs/acceptance/1.6.7/FAILOVER-CLEANUP-FIX.json

@@ -0,0 +1,22 @@
+{
+  "version": "1.6.7",
+  "case": "FAILOVER-CLEANUP-FIX",
+  "kind": "positive",
+  "machines": [
+    "b53a37f4-1464-4512-9259-33a7df091e3e"
+  ],
+  "executed_at": "2026-10-24T13:31:02.803Z",
+  "executor": "lead",
+  "requirement": "a remote-relay in-process stack can be stopped and restarted for failover: the cleanup must not assume a local relay object, a failed stop must not skip the restart, and the switch must leave a diagnostics log",
+  "task_id": "01M5ANYMVMFSSP3",
+  "result": {
+    "outcome": "ok",
+    "assertions": {
+      "failover_suite": "5/5",
+      "relay_suite": "200/200",
+      "cleanup": "null-safe and idempotent",
+      "diagnostics": "xclient/relay-failover.log"
+    }
+  },
+  "note": "v1.6.6 field drill stopped the stack and never restarted it: relay.close() threw on remote-relay stacks"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twinsearth/w2m-dsh-plugin",
-  "version": "1.6.5",
+  "version": "1.6.7",
   "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/secondary-link.test.mjs test/bootstrap-cli.test.mjs test/bootstrap.test.mjs test/windows-hidden-task.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/bootstrap-cli.test.mjs test/bootstrap.test.mjs test/windows-hidden-task.test.mjs test/relay-failover.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/secondary-link.test.mjs test/bootstrap-cli.test.mjs test/bootstrap.test.mjs test/windows-hidden-task.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/bootstrap-cli.test.mjs test/bootstrap.test.mjs test/windows-hidden-task.test.mjs test/relay-failover.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",

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.6.5",
+  "version": "1.6.7",
   "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/relay-failover.mjs

@@ -0,0 +1,158 @@
+/**
+ * Relay failover supervisor (v1.6.6).
+ *
+ * ## The failure this exists for
+ *
+ * On 2026-10-24 the primary relay's host went down entirely (HTTP 8787 and SSH 22 both timed out).
+ * Every machine kept dialling the dead primary: the fleet was unreachable even though the backup
+ * relay was healthy the whole time. The backup carried a "standby member" per machine, but nothing
+ * ever *moved* the working connection to it. This module is the decision half of the fix; the wiring
+ * in `tools.mjs` restarts the in-process stack against the chosen relay, and re-pairing happens
+ * through the fleet key (per-relay tokens differ, so a switch is a re-join, not a reconnect).
+ *
+ * ## Hysteresis, deliberately asymmetric
+ *
+ * Switching away needs **3 consecutive** failed probes (a single dropped health request during a
+ * deploy must not move a fleet), while returning to the primary needs **5 consecutive** successes.
+ * Coming back is the riskier direction — a flapping primary that answers twice must not drag every
+ * machine back and forth — so it requires more evidence than leaving does.
+ *
+ * Pure state machine: no timers, no network. The caller probes and feeds results in, which is what
+ * makes the thresholds testable without waiting ten seconds per transition.
+ */
+
+/** Defaults are exported so the tests and the status report cannot invent different numbers. */
+export const FAILOVER_DEFAULTS = Object.freeze({
+  probeIntervalMs: 10_000,
+  probeTimeoutMs: 2_000,
+  failuresToSwitch: 3,
+  successesToReturn: 5,
+});
+
+/**
+ * The ordered relay pool for this machine.
+ *
+ * `relayUrls` is the operator's pool (v1.5.1+); `rabbitUrl` is the active one. Deduplicated and
+ * normalized so a trailing slash cannot make one relay look like two.
+ *
+ * @param {{rabbitUrl?: string|null, relayUrls?: string[]|null}} cfg
+ * @returns {string[]}
+ */
+export function relayPool(cfg) {
+  const cleaned = (Array.isArray(cfg?.relayUrls) ? cfg.relayUrls : [])
+    .filter((url) => typeof url === 'string' && url.trim() !== '')
+    .map((url) => url.trim().replace(/\/+$/, ''));
+  const active = typeof cfg?.rabbitUrl === 'string' && cfg.rabbitUrl.trim() !== ''
+    ? cfg.rabbitUrl.trim().replace(/\/+$/, '')
+    : null;
+  const pool = [];
+  for (const url of [...(active === null ? [] : [active]), ...cleaned]) {
+    if (!pool.includes(url)) pool.push(url);
+  }
+  return pool;
+}
+
+/**
+ * Create the failover state machine.
+ *
+ * @param {object} options
+ * @param {string[]} options.pool Ordered relay URLs; `pool[0]` is the primary.
+ * @param {string} [options.primary] Overrides which URL counts as "the one to return to".
+ * @param {number} [options.failuresToSwitch]
+ * @param {number} [options.successesToReturn]
+ * @param {() => number} [options.now]
+ */
+export function createRelayFailover(options) {
+  const pool = Array.isArray(options?.pool) ? [...options.pool] : [];
+  if (pool.length === 0) throw new TypeError('pool must contain at least one relay URL');
+  const primary = typeof options?.primary === 'string' && pool.includes(options.primary) ? options.primary : pool[0];
+  const failuresToSwitch = Number.isInteger(options?.failuresToSwitch) && options.failuresToSwitch > 0
+    ? options.failuresToSwitch : FAILOVER_DEFAULTS.failuresToSwitch;
+  const successesToReturn = Number.isInteger(options?.successesToReturn) && options.successesToReturn > 0
+    ? options.successesToReturn : FAILOVER_DEFAULTS.successesToReturn;
+  const now = typeof options?.now === 'function' ? options.now : Date.now;
+
+  let active = typeof options?.active === 'string' && pool.includes(options.active) ? options.active : primary;
+  let failures = 0;
+  let primarySuccesses = 0;
+  let switches = 0;
+  let lastSwitchAtMs = null;
+  let lastReason = null;
+  const history = [];
+
+  /**
+   * Feed one round of health results and get the decision.
+   *
+   * @param {Map<string, boolean>|Record<string, boolean>} health url -> reachable
+   * @returns {{action: 'stay'|'switch', active: string, target?: string, reason?: string}}
+   */
+  function assess(health) {
+    const reachable = (url) => (health instanceof Map ? health.get(url) : health?.[url]) === true;
+    const activeOk = reachable(active);
+
+    if (activeOk) {
+      failures = 0;
+      if (active === primary) {
+        primarySuccesses = 0;
+      }
+      // A healthy non-primary route still watches the primary for the way home.
+    } else {
+      failures += 1;
+    }
+
+    if (active !== primary && reachable(primary)) {
+      primarySuccesses += 1;
+    } else if (active !== primary) {
+      primarySuccesses = 0;
+    }
+
+    if (activeOk !== true && failures >= failuresToSwitch) {
+      const alternative = pool.find((url) => url !== active && reachable(url));
+      if (alternative !== undefined) {
+        const reason = `active relay ${active} failed ${failures} consecutive probes`;
+        history.push({ at_ms: now(), from: active, to: alternative, reason });
+        active = alternative;
+        failures = 0;
+        primarySuccesses = 0;
+        switches += 1;
+        lastSwitchAtMs = now();
+        lastReason = reason;
+        return { action: 'switch', active, target: alternative, reason };
+      }
+      // No reachable alternative: stay, but keep reporting the failure streak.
+    }
+
+    if (active !== primary && primarySuccesses >= successesToReturn) {
+      const reason = `primary relay ${primary} healthy ${primarySuccesses} consecutive probes`;
+      history.push({ at_ms: now(), from: active, to: primary, reason });
+      active = primary;
+      failures = 0;
+      primarySuccesses = 0;
+      switches += 1;
+      lastSwitchAtMs = now();
+      lastReason = reason;
+      return { action: 'switch', active, target: primary, reason };
+    }
+
+    return { action: 'stay', active };
+  }
+
+  /** What `w2m_status` reports: which relay is in use and why it last moved. */
+  function snapshot() {
+    return {
+      primary,
+      active,
+      pool: [...pool],
+      failures,
+      failures_to_switch: failuresToSwitch,
+      primary_successes: primarySuccesses,
+      successes_to_return: successesToReturn,
+      switches,
+      last_switch_at_ms: lastSwitchAtMs,
+      last_reason: lastReason,
+      history: history.slice(-10),
+    };
+  }
+
+  return { assess, snapshot, thresholds: { failuresToSwitch, successesToReturn } };
+}

package/src/plugin/tools.mjs

@@ -1,3 +1,4 @@
+import { FAILOVER_DEFAULTS, createRelayFailover, relayPool } from './relay-failover.mjs';
 import { DEFAULT_BOOTSTRAP_URL, DEFAULT_BOOTSTRAP_OPERATOR_KEY_PEM } from './bootstrap.mjs';
 /**
  * DSH: Windows2MacO - the DSH Cordis plugin.
@@ -89,6 +90,9 @@ import { DEFAULT_BOOTSTRAP_URL, DEFAULT_BOOTSTRAP_OPERATOR_KEY_PEM } from './boo
  * implementation, and vice versa.
  */
 
+/** v1.6.6: last failover snapshot, reported by w2m_status and refreshed by the supervisor interval. */
+let relayFailoverStatus = null;
+
 import { execFile } from 'node:child_process';
 
 import { resolveChannels } from './update-channels.mjs';
@@ -277,7 +281,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.6.5';
+const PLUGIN_VERSION = '1.6.7';
 
 /** How long any single HTTP call may take before it is aborted, in milliseconds. */
 const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;
@@ -2193,6 +2197,8 @@ async function readP2PStatus(cfg, runtime, peersAnnounced = null) {
     local: status?.local ?? null,
     rabbit_url: status?.rabbit_url ?? cfg.rabbitUrl,
       bootstrap: cfg.bootstrap ?? null,
+      // v1.6.6: which relay is in use and why it last moved.
+      failover: relayFailoverStatus,
     // How many machines the relay holds a live announcement for. `w2m_devices` says which machines
     // paired; this says which of them can be punched at, and the two differ constantly.
     peers_announced: peersAnnounced,
@@ -4956,7 +4962,7 @@ export async function apply(ctx, config = {}) {
     // v1.5.3: a failed auto-start must not surface as an unhandled rejection. The bundled patch now
   // starts the agent by default, and a host whose plugin wiring forbids that (a restricted test
   // harness, a missing relay module) would otherwise reject where nothing can catch it.
-  ctx.effect?.(() => startLocalStack(ctx, cfg).catch((error) => {
+  ctx.effect?.(() => startFailoverStack(ctx, cfg).catch((error) => {
     ctx.logger?.warn?.('w2m: auto-start did not complete: ' + (error instanceof Error ? error.message : String(error)));
   }));
   } else {
@@ -7375,6 +7381,84 @@ function sleepWithSignal(ms, signal) {
  */
 const resolvedFleetKey = { value: null, source: null, at: 0 };
 
+/** Probe one relay /healthz; any failure is `false` (a timeout must not throw into the interval). */
+async function probeRelayHealth(url, timeoutMs) {
+  try {
+    const response = await fetch(url + '/healthz', {
+      signal: typeof AbortSignal !== 'undefined' && typeof AbortSignal.timeout === 'function' ? AbortSignal.timeout(timeoutMs) : undefined,
+    });
+    if (response.ok !== true) return false;
+    const body = await response.json().catch(() => null);
+    return body?.ok === true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * v1.6.6: keep the in-process stack on a reachable relay.
+ *
+ * The primary relay can disappear entirely (2026-10-24: its host was down, so 8787 and SSH were both
+ * unreachable). The stack is restartable: stop it, point cfg.rabbitUrl at the next healthy relay in
+ * the pool, start it again. A switch is a re-join, not just a reconnect -- device tokens are relay-
+ * specific, so startLocalStack pairs again through the account fleet key.
+ *
+ * The decision itself (3 failed probes to leave, 5 healthy ones to come home) lives in
+ * relay-failover.mjs and is unit-tested there; this function only supplies health and performs the
+ * restart.
+ */
+/** Append one line to the failover diagnostics log; failures are swallowed (diagnostics must not break the switch). */
+async function appendFailoverLog(cfg, line) {
+  try {
+    const { appendFileSync, mkdirSync, statSync, writeFileSync } = await import('node:fs');
+    const { join, dirname } = await import('node:path');
+    const { homedir } = await import('node:os');
+    const dir = cfg.stateDir ?? join(process.env.DSH_HOME ?? join(homedir(), '.dsh'), 'xclient');
+    const file = join(dir, 'relay-failover.log');
+    mkdirSync(dirname(file), { recursive: true });
+    try { if (statSync(file).size > 256 * 1024) writeFileSync(file, ''); } catch { /* absent is fine */ }
+    appendFileSync(file, new Date().toISOString() + ' ' + line + '\n');
+  } catch { /* diagnostics only */ }
+}
+async function startFailoverStack(ctx, cfg) {
+  let stop = await startLocalStack(ctx, cfg);
+  const pool = relayPool(cfg);
+  if (pool.length < 2) {
+    relayFailoverStatus = null;
+    return stop;
+  }
+  const failover = createRelayFailover({ pool });
+  relayFailoverStatus = failover.snapshot();
+  let switching = false;
+  const timer = setInterval(async () => {
+    if (switching) return;
+    const health = {};
+    await Promise.all(pool.map(async (url) => { health[url] = await probeRelayHealth(url, FAILOVER_DEFAULTS.probeTimeoutMs); }));
+    const decision = failover.assess(health);
+    await appendFailoverLog(cfg, 'probe ' + JSON.stringify(health) + ' -> ' + decision.action + (decision.target ? ' ' + decision.target : ''));
+    relayFailoverStatus = failover.snapshot();
+    if (decision.action !== 'switch') return;
+    switching = true;
+    try {
+      ctx.logger?.warn?.('w2m: relay failover ' + decision.active + ' (' + decision.reason + ')');
+      await stop();
+      cfg.rabbitUrl = decision.target;
+      cfg.relaySource = 'failover';
+      stop = await startLocalStack(ctx, cfg);
+      ctx.logger?.info?.('w2m: relay failover stack restarted on ' + decision.target);
+    } catch (error) {
+      ctx.logger?.warn?.('w2m: relay failover restart failed: ' + (error instanceof Error ? error.message : String(error)));
+    } finally {
+      switching = false;
+    }
+  }, FAILOVER_DEFAULTS.probeIntervalMs);
+  timer.unref?.();
+  return async () => {
+    clearInterval(timer);
+    relayFailoverStatus = null;
+    await stop();
+  };
+}
 async function startLocalStack(ctx, cfg) {
 
   /**
@@ -8007,7 +8091,14 @@ async function startLocalStack(ctx, cfg) {
     ensureFleetJoin = null;
     inProcessAgentStatus = null;
     await agent.stop();
-    await relay.close();
+    // v1.6.7: `relay` is only a real relay object when THIS stack started a local relay; a remote-
+    // relay stack has null here. The unconditional close() threw, which is what made the first
+    // failover attempt stop the stack and never restart it.
+    if (relay !== null && typeof relay.close === 'function') {
+      try { await relay.close(); } catch (error) {
+        ctx.logger?.warn?.('w2m: local relay close failed: ' + (error instanceof Error ? error.message : String(error)));
+      }
+    }
   };
 }