@twinsearth/w2m-dsh-plugin 1.5.0 → 1.5.2

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

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

package/CHANGELOG.md

@@ -7,6 +7,40 @@
 
 All notable changes to this project are documented here.
 
+## [1.5.2] — 2026-10-23
+
+**新机器自动获得 relay 归属（验签 bootstrap）+ 一次性配置工具。**
+
+- 新增 `src/plugin/bootstrap.mjs`：机器用 fleetKey 派生 HMAC 证明请求 relay 列表；响应必须由
+  operator 公钥（pin）对 canonical payload（fleet_id + 排序后的 relays + issued_at + expires_at）
+  验签；过期/错 fleet/被篡改/坏 JSON 全部命名拒绝。缓存每次读取都重验签名与有效期，手改缓存无效。
+  **任何失败都不改现有 relay 配置**，原因写入 `w2m_status.bootstrap.last_error`。
+- `startLocalStack` 接线：无 `relayUrls` 且配置 `bootstrapUrl`+`fleetKey`+operator 公钥时启动即解析
+  （缓存优先，其次网络），成功则采用该 relay 池（首个为 primary）；`w2m_status` 新增
+  `bootstrap {configured, url, source, relays, expires_at, last_error}`。
+- 新增 `bin/w2m-bootstrap.mjs`：一条命令写 `relayUrls`/`fleetKey`/`autoStartAgent` 到 profile patch，
+  只改受管键、写前备份、所有输入先校验；`--temporary` 写 `relayTemporary: true`，面板以
+  **红色“临时 Relay 节点（回退配置）”**显示。
+- 新增 `bin/w2m-bootstrap-sign.mjs`：运维侧用 operator 私钥签名 relay 列表，输出可静态托管。
+- 控制面板 relay 折叠区支持 temporary 红色标记（仅主题 token，无硬编码颜色）。
+- 层模型修复：bootstrap 模块不依赖 chatops 层（layer-check 保持 clean）。
+- 测试：bootstrap 5/5、bootstrap-cli 6/6、fleet-target 49/49、client-bundle 26/26；
+  证据 `docs/acceptance/1.5.2/VERIFIED-BOOTSTRAP.json`（真实 fleet task `01M5ANYMVKXNU8E`）。
+## [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 健康看门狗。**

package/bin/w2m-bootstrap-sign.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+/**
+ * w2m-bootstrap-sign (v1.5.2) — produce one signed relay-list answer for static hosting.
+ *
+ * The bootstrap endpoint serves a document; its only trust anchor is the Ed25519 signature the
+ * installed plugin verifies against its pinned operator key. Signing is therefore an operator
+ * action, run with the operator private key, and the output is a plain JSON file a static server
+ * can serve. `expires_at` is part of the signed payload, so a stale file stops being accepted
+ * without anyone having to remember to delete it.
+ *
+ * usage:
+ *   w2m-bootstrap-sign.mjs --relays '[{"relays":["https://a:8787","https://b:8787"]}]' ...  *     --relays <json|file> --fleet-key <key> --operator-key <private.pem> [--ttl-hours 24] [--out file]
+ */
+import { readFileSync, writeFileSync } from 'node:fs';
+import { createPrivateKey, sign as signBytes } from 'node:crypto';
+import { canonicalBootstrapPayload, BOOTSTRAP_PROTOCOL, fleetIdOf } from '../src/plugin/bootstrap.mjs';
+import { decodeFleetKey } from '../src/chatops/fleet-join.mjs';
+
+function arg(argv, name) { const i = argv.indexOf(name); return i >= 0 ? argv[i + 1] : undefined; }
+
+const relaysArg = arg(process.argv, '--relays');
+const fleetKey = arg(process.argv, '--fleet-key');
+const operatorKeyPath = arg(process.argv, '--operator-key');
+const ttlHours = Number(arg(process.argv, '--ttl-hours') ?? '24');
+const outPath = arg(process.argv, '--out');
+if (!relaysArg || !fleetKey || !operatorKeyPath) {
+  process.stderr.write('usage: w2m-bootstrap-sign.mjs --relays <json|file> --fleet-key <key> --operator-key <private.pem> [--ttl-hours 24] [--out file]\n');
+  process.exit(2);
+}
+if (decodeFleetKey(fleetKey) === null) { process.stderr.write('w2m-bootstrap-sign: --fleet-key is not a 32-byte base64url key\n'); process.exit(2); }
+let document;
+try { document = JSON.parse(relaysArg.trim().startsWith('{') || relaysArg.trim().startsWith('[') ? relaysArg : readFileSync(relaysArg, 'utf8')); }
+catch (error) { process.stderr.write('w2m-bootstrap-sign: cannot parse --relays: ' + error.message + '\n'); process.exit(2); }
+const relayList = Array.isArray(document) ? document : document.relays;
+const relays = [...new Set((Array.isArray(relayList) ? relayList : []).filter((u) => typeof u === 'string' && u.trim() !== '').map((u) => u.trim().replace(/\/+$/, '')))];
+if (relays.length === 0) { process.stderr.write('w2m-bootstrap-sign: no relay URLs in --relays\n'); process.exit(2); }
+const fleetId = fleetIdOf(fleetKey);
+const now = Date.now();
+const issuedAt = new Date(now).toISOString();
+const expiresAt = new Date(now + Math.max(1, Math.round(ttlHours * 3600_000))).toISOString();
+const payload = canonicalBootstrapPayload({ fleet_id: fleetId, relays, issued_at: issuedAt, expires_at: expiresAt });
+const key = createPrivateKey(readFileSync(operatorKeyPath));
+const signature = signBytes(null, Buffer.from(payload, 'utf8'), key).toString('base64');
+const answer = { protocol: BOOTSTRAP_PROTOCOL, fleet_id: fleetId, relays, issued_at: issuedAt, expires_at: expiresAt, signature: { alg: 'ed25519', value: signature } };
+const text = JSON.stringify(answer, null, 2) + '\n';
+if (outPath) { writeFileSync(outPath, text, 'utf8'); process.stdout.write('w2m-bootstrap-sign: wrote ' + outPath + ' (fleet ' + fleetId.slice(0, 16) + '…, expires ' + expiresAt + ')\n'); }
+else process.stdout.write(text);

package/bin/w2m-bootstrap.mjs

@@ -0,0 +1,303 @@
+#!/usr/bin/env node
+/**
+ * w2m-bootstrap — one command to point a freshly installed plugin at the right relays.
+ *
+ * ## Why a tool instead of hand-editing the profile
+ *
+ * The profile patch is YAML that the loader merges into a bundle row, and three mistakes are easy
+ * and silent: a `name:` assertion that skips the whole patch, an `insert:` that duplicates the row,
+ * and an `autoStartAgent: false` that leaves the agent never starting. This tool writes the small,
+ * known-good shape and refuses the inputs it cannot honour, so the Nth machine costs one command
+ * instead of one careful copy-paste.
+ *
+ * ## Two sources, one destination
+ *
+ * `--bootstrap` accepts either
+ *   * an **http(s) URL** — fetched and (when `--operator-key` is given) verified with the same
+ *     signature check the runtime bootstrap uses, or
+ *   * a **JSON document / file path** — `{"relays": ["https://…", …]}` (a signed answer is accepted
+ *     only together with `--operator-key`; without a pin the document is used as operator-supplied
+ *     configuration, which is the normal case for an install script that already carries the list).
+ *
+ * Nothing is written until every input parses and validates, and the existing patch is backed up.
+ *
+ * ## The temporary marker
+ *
+ * A machine that cannot reach its own fleet may be pointed at a fallback relay list so it is not
+ * stranded. That is honest only if it is visible: `--temporary` writes `relayTemporary: true`, and
+ * the fleet panel renders the relay section in red as **临时 Relay 节点**. Removing the marker (by a
+ * later run without the flag) is what turns the fallback into a settled configuration.
+ *
+ * ## Usage
+ *
+ *   node bin/w2m-bootstrap.mjs \
+ *     --bootstrap https://relays.example/bootstrap \
+ *     --fleet-key <account fleet key> \
+ *     [--operator-key <operator public key PEM file>] \
+ *     [--profile desktop] [--name <machine name>] [--temporary] [--dry-run]
+ */
+import { existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { fleetIdOf, resolveBootstrap } from '../src/plugin/bootstrap.mjs';
+import { decodeFleetKey } from '../src/chatops/fleet-join.mjs';
+
+export const CLI_REFUSAL = Object.freeze({
+  BAD_BOOTSTRAP: 'BOOTSTRAP_CLI_BAD_SOURCE',
+  BAD_FLEET_KEY: 'BOOTSTRAP_CLI_BAD_FLEET_KEY',
+  BAD_RELAYS: 'BOOTSTRAP_CLI_BAD_RELAYS',
+  PATCH_MISSING_ROW: 'BOOTSTRAP_CLI_PATCH_MISSING_ROW',
+  PATCH_MISSING_CONFIG: 'BOOTSTRAP_CLI_PATCH_MISSING_CONFIG',
+  REFUSED: 'BOOTSTRAP_CLI_REFUSED',
+});
+
+/**
+ * Parse the command line. Every flag has one spelling; an unknown flag is a refusal, not a silent
+ * miss — a bootstrap that quietly ignored `--fleet-key` would write a config that cannot join.
+ *
+ * @param {string[]} argv
+ * @returns {object}
+ */
+export function parseBootstrapCliArgs(argv) {
+  const out = {
+    bootstrap: null,
+    fleetKey: null,
+    operatorKeyPath: null,
+    profile: 'desktop',
+    name: null,
+    temporary: false,
+    dryRun: false,
+    help: false,
+  };
+  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 '--bootstrap': out.bootstrap = value(); break;
+      case '--fleet-key': out.fleetKey = value(); break;
+      case '--operator-key': out.operatorKeyPath = value(); break;
+      case '--profile': out.profile = value(); break;
+      case '--name': out.name = value(); break;
+      case '--temporary': out.temporary = true; break;
+      case '--dry-run': out.dryRun = true; break;
+      case '--help':
+      case '-h': out.help = true; break;
+      default: throw new Error(`unknown flag: ${flag}`);
+    }
+  }
+  if (out.help === true) return out;
+  if (typeof out.bootstrap !== 'string' || out.bootstrap.trim() === '') {
+    throw new Error('--bootstrap <json|url> is required');
+  }
+  if (typeof out.fleetKey !== 'string' || out.fleetKey.trim() === '') {
+    throw new Error('--fleet-key <key> is required');
+  }
+  if (decodeFleetKey(out.fleetKey.trim()) === null) {
+    throw Object.assign(new Error('--fleet-key is not a 32-byte base64url fleet key'), { reason_code: CLI_REFUSAL.BAD_FLEET_KEY });
+  }
+  return out;
+}
+
+/**
+ * Turn the `--bootstrap` value into a relay list.
+ *
+ * @param {object} args Parsed CLI args.
+ * @param {{fetchImpl?: Function, nowMs?: number}} [deps]
+ * @returns {Promise<{ok: true, relays: string[], source: 'url'|'json'|'file'}|{ok: false, reason_code: string, detail: string}>}
+ */
+export async function resolveBootstrapSource(args, deps = {}) {
+  const raw = String(args.bootstrap).trim();
+  const fleetKey = args.fleetKey.trim();
+  if (/^https?:\/\//.test(raw)) {
+    const operatorPublicKeyPem = args.operatorKeyPath === null
+      ? ''
+      : readFileSync(resolve(args.operatorKeyPath), 'utf8');
+    if (operatorPublicKeyPem === '') {
+      // A URL without a pin cannot be verified; fetch it as operator-supplied JSON instead and say
+      // so in the returned source, so the caller can warn rather than pretend it was verified.
+      try {
+        const response = await (deps.fetchImpl ?? globalThis.fetch)(raw, { method: 'GET' });
+        if (!response.ok) return { ok: false, reason_code: CLI_REFUSAL.BAD_BOOTSTRAP, detail: `HTTP ${response.status}` };
+        const body = await response.json();
+        return relaysFromDocument(body);
+      } catch (error) {
+        return { ok: false, reason_code: CLI_REFUSAL.BAD_BOOTSTRAP, detail: error instanceof Error ? error.message : String(error) };
+      }
+    }
+    const resolved = await resolveBootstrap({
+      url: raw,
+      fleetKey,
+      operatorPublicKeyPem,
+      cacheFile: '',
+      fetchImpl: deps.fetchImpl,
+      nowMs: deps.nowMs,
+    });
+    return resolved.ok === true
+      ? { ok: true, relays: resolved.relays, source: 'url' }
+      : { ok: false, reason_code: resolved.reason_code, detail: resolved.detail };
+  }
+  // Inline JSON may be an object or a bare array; anything else is a path. The distinction is the
+  // first non-space character, not "does it parse", so a typo'd path fails as a path (a named error)
+  // rather than as a JSON parse error that hides which input was actually read.
+  const trimmed = raw.trim();
+  const text = (trimmed.startsWith('{') || trimmed.startsWith('[')) ? trimmed : readFileSync(resolve(trimmed), 'utf8');
+  try {
+    return relaysFromDocument(JSON.parse(text));
+  } catch (error) {
+    return { ok: false, reason_code: CLI_REFUSAL.BAD_BOOTSTRAP, detail: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+/** Accept `{relays:[…]}` (or an array of URLs) and normalize it. */
+export function relaysFromDocument(document) {
+  const list = Array.isArray(document) ? document
+    : (document !== null && typeof document === 'object' && Array.isArray(document.relays) ? document.relays : null);
+  if (list === null) {
+    return { ok: false, reason_code: CLI_REFUSAL.BAD_RELAYS, detail: 'the bootstrap document must be {"relays": [...]} or an array of relay URLs' };
+  }
+  const relays = [...new Set(list
+    .filter((url) => typeof url === 'string' && url.trim() !== '')
+    .map((url) => url.trim().replace(/\/+$/, '')))];
+  if (relays.length === 0) return { ok: false, reason_code: CLI_REFUSAL.BAD_RELAYS, detail: 'the document carries no relay URLs' };
+  for (const url of relays) {
+    if (!/^https?:\/\/[^\s]+$/.test(url)) return { ok: false, reason_code: CLI_REFUSAL.BAD_RELAYS, detail: `${JSON.stringify(url)} is not an http(s) base URL` };
+  }
+  return { ok: true, relays, source: 'json' };
+}
+
+/**
+ * Rewrite the `- id: w2m` block's config with the resolved values, in place and with a backup.
+ *
+ * Deliberately line-based: this file is edited by humans and must stay readable, and a YAML emitter
+ * would rewrite comments the operator relies on. The block is found by its exact id row, the config
+ * block by its `config:` child; only the keys this tool owns are replaced or appended.
+ *
+ * @param {string} file
+ * @param {{relays: string[], fleetKey: string, relayUrl: null|string, temporary: boolean, machineName: string|null}} values
+ * @returns {{ok: true, file: string, backup: string}|{ok: false, reason_code: string, detail: string}}
+ */
+export function writeBootstrapPatch(file, values) {
+  if (!existsSync(file)) {
+    return { ok: false, reason_code: CLI_REFUSAL.PATCH_MISSING_ROW, detail: `profile patch not found at ${file}` };
+  }
+  // Normalize here as well as in the source resolver: callers that pass a document straight through
+  // must not be able to write a trailing-slash base URL that later compares unequal to every other
+  // use of the same relay.
+  const relays = [...new Set((Array.isArray(values.relays) ? values.relays : [])
+    .filter((url) => typeof url === 'string' && url.trim() !== '')
+    .map((url) => url.trim().replace(/\/+$/, '')))];
+  if (relays.length === 0) {
+    return { ok: false, reason_code: CLI_REFUSAL.BAD_RELAYS, detail: 'no relay URLs were supplied' };
+  }
+  const lines = readFileSync(file, 'utf8').split('\n');
+  const start = lines.findIndex((line) => /^-\s*id:\s*w2m\s*$/.test(line.trim()));
+  if (start < 0) {
+    return { ok: false, reason_code: CLI_REFUSAL.PATCH_MISSING_ROW, detail: 'no `- id: w2m` row exists in the patch; the bundle should have inserted it' };
+  }
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i += 1) {
+    if (/^-\s*id:\s*\S+/.test(lines[i].trim())) { end = i; break; }
+  }
+  let configIndex = -1;
+  for (let i = start + 1; i < end; i += 1) {
+    if (/^\s*config:\s*$/.test(lines[i])) { configIndex = i; break; }
+  }
+  if (configIndex < 0) {
+    return { ok: false, reason_code: CLI_REFUSAL.PATCH_MISSING_CONFIG, detail: 'the `- id: w2m` row has no `config:` block to write into' };
+  }
+  const indent = `${(lines[configIndex].match(/^\s*/) ?? [''])[0]}  `;
+  const managed = {
+    flock: undefined,
+    rabbitUrl: relays[0],
+    fleetKey: `'${values.fleetKey}'`,
+    autoStartAgent: 'true',
+    relayTemporary: values.temporary === true ? 'true' : null,
+    machineName: values.machineName === null ? null : values.machineName,
+  };
+  let block = lines.slice(configIndex + 1, end);
+  // Drop managed keys from the block (they are re-emitted below), keep everything else untouched.
+  block = block.filter((line) => {
+    const key = (line.match(/^\s*([A-Za-z][\w]*)\s*:/) ?? [])[1];
+    return key === undefined || !(key in managed);
+  });
+  const emitted = [];
+  if (managed.machineName !== null) emitted.push(`${indent}machineName: ${managed.machineName}`);
+  emitted.push(`${indent}rabbitUrl: ${managed.rabbitUrl}`);
+  emitted.push(`${indent}relayUrls:`);
+  for (const relay of relays) emitted.push(`${indent}  - ${relay}`);
+  emitted.push(`${indent}fleetKey: ${managed.fleetKey}`);
+  emitted.push(`${indent}autoStartAgent: true`);
+  if (values.temporary === true) emitted.push(`${indent}relayTemporary: true`);
+  const next = [...lines.slice(0, configIndex + 1), ...emitted, ...block, ...lines.slice(end)];
+  const text = `${next.join('\n').replace(/\n{3,}/g, '\n\n').replace(/\n*$/, '')}\n`;
+  const backup = `${file}.bak-${Date.now()}`;
+  writeFileSync(backup, lines.join('\n'), 'utf8');
+  const tmp = `${file}.tmp-${process.pid}`;
+  writeFileSync(tmp, text, 'utf8');
+  renameSync(tmp, file);
+  return { ok: true, file, backup };
+}
+
+/** Default patch path for a profile, resolved the same way the loader does. */
+export function defaultPatchPath(profile) {
+  const home = process.env.DSH_HOME && process.env.DSH_HOME.trim() !== '' ? process.env.DSH_HOME : join(homedir(), '.dsh');
+  return join(home, 'profiles', profile, 'cordis.patch.yml');
+}
+
+async function main() {
+  let args;
+  try {
+    args = parseBootstrapCliArgs(process.argv.slice(2));
+  } catch (error) {
+    process.stderr.write(`w2m-bootstrap: ${error.message}\n`);
+    process.exit(2);
+  }
+  if (args.help === true) {
+    process.stdout.write('usage: w2m-bootstrap.mjs --bootstrap <json|url> --fleet-key <key> [--operator-key <pem>] [--profile desktop] [--name <machine>] [--temporary] [--dry-run]\n\n'
+      + 'Writes relayUrls (first = primary), fleetKey and autoStartAgent: true into the profile patch.\n'
+      + '--temporary marks the relay list as a fallback; the fleet panel then renders it as 临时 Relay 节点.\n');
+    return;
+  }
+  const resolved = await resolveBootstrapSource(args);
+  if (resolved.ok !== true) {
+    process.stderr.write(`w2m-bootstrap: ${resolved.reason_code}: ${resolved.detail}\n`);
+    process.exit(1);
+  }
+  const patch = defaultPatchPath(args.profile);
+  if (args.dryRun === true) {
+    process.stdout.write(`w2m-bootstrap: dry run — would write to ${patch}\n  relays: ${resolved.relays.join(', ')}\n  fleet: ${fleetIdOf(args.fleetKey)?.slice(0, 16)}…\n  temporary: ${args.temporary}\n`);
+    return;
+  }
+  const written = writeBootstrapPatch(patch, {
+    relays: resolved.relays,
+    fleetKey: args.fleetKey.trim(),
+    relayUrl: resolved.relays[0],
+    temporary: args.temporary,
+    machineName: args.name,
+  });
+  if (written.ok !== true) {
+    process.stderr.write(`w2m-bootstrap: ${written.reason_code}: ${written.detail}\n`);
+    process.exit(1);
+  }
+  process.stdout.write([
+    `w2m-bootstrap: wrote ${patch}`,
+    `  relays (primary first): ${resolved.relays.join(', ')}`,
+    `  fleet: ${fleetIdOf(args.fleetKey)?.slice(0, 16)}…`,
+    args.temporary === true ? '  relayTemporary: true — this machine uses a fallback relay list (临时 Relay 节点)' : '  relayTemporary: off',
+    `  backup: ${written.backup}`,
+    'Restart DSH (quick-reload does not re-read the profile), then check w2m_status:',
+    '  rabbitUrl should name the first relay, and the fleet panel should list the relay pool.',
+  ].join('\n') + '\n');
+}
+
+if (process.argv[1] !== undefined && import.meta.url === new URL(`file://${process.argv[1].replace(/\\/g, '/')}`).href) {
+  main().catch((error) => {
+    process.stderr.write(`w2m-bootstrap: ${error?.stack ?? error}\n`);
+    process.exit(1);
+  });
+}

package/bin/w2m-secondary-link.mjs

@@ -47,6 +47,7 @@ const HERE = dirname(fileURLToPath(import.meta.url));
 const DEFAULTS = Object.freeze({
   project: process.cwd(),
   stateDir: null,
+  identityHome: null,
   logFile: null,
   allowedCommands: '[]',
   restartDelayMs: 3000,
@@ -68,6 +69,7 @@ export function parseSecondaryArgs(argv) {
     fleetKey: null,
     name: null,
     stateDir: null,
+    identityHome: null,
     logFile: null,
     project: DEFAULTS.project,
     operatorToken: null,
@@ -86,6 +88,7 @@ export function parseSecondaryArgs(argv) {
       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;
@@ -104,6 +107,18 @@ export function parseSecondaryArgs(argv) {
   }
   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;
 }
@@ -158,10 +173,25 @@ export async function runSupervisor(options, deps) {
   const stopSignal = deps.stopSignal ?? { stopped: false };
   const args = buildLocalsideArgs(options);
   let delay = DEFAULTS.restartDelayMs;
-  log(`supervising secondary link relay=${options.relay} state=${options.stateDir}`);
+  // 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 });
+    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 }));

package/codex/mcp-servers.toml

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

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/docs/acceptance/1.5.2/VERIFIED-BOOTSTRAP.json

@@ -0,0 +1,21 @@
+{
+  "version": "1.5.2",
+  "case": "VERIFIED-BOOTSTRAP",
+  "kind": "positive",
+  "machines": [
+    "b53a37f4-1464-4512-9259-33a7df091e3e"
+  ],
+  "executed_at": "2026-10-23T12:22:38.268Z",
+  "executor": "lead",
+  "requirement": "a fresh installation obtains its relay list from a signed bootstrap answer: HMAC proof, pinned Ed25519 verification over canonical bytes, expiry enforcement, verified cache; and w2m-bootstrap writes the profile patch with the fallback marker",
+  "task_id": "01M5ANYMVKXNU8E",
+  "result": {
+    "outcome": "ok",
+    "assertions": {
+      "bootstrap_suite": "5/5 pass",
+      "bootstrap_cli_suite": "6/6 pass",
+      "fleet_target_suite": "49/49 pass"
+    }
+  },
+  "note": "all three suites ran as one real fleet task on the Tencent relay before packaging"
+}

package/lib/client.js

@@ -105,6 +105,13 @@ window.__ModuleLoader__.load({
         unreachable: '无法连接插件',
         routeMissing: '这个 Harness 没有提供插件目标路由',
         fleetUnreadable: '机器列表读取失败',
+        relays: 'Relay 节点',
+        relayPrimary: '主 relay',
+        relayStandby: '备用',
+        relayOffline: '离线',
+        relayFold: '另有 {count} 个已折叠，点击展开',
+        relayUnfold: '收起折叠的 relay',
+        relayTemporary: '临时 Relay 节点（回退配置）',
         capLabel: 'Node 执行：{state}',
         capDenied: '拒绝',
         capTemporary: '临时 24 小时',
@@ -129,6 +136,13 @@ 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',
+        relayTemporary: 'temporary relay nodes (fallback config)',
         capLabel: 'Node exec: {state}',
         capDenied: 'denied',
         capTemporary: 'temporary 24 h',
@@ -311,6 +325,15 @@ 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_relayToggle[data-temporary="true"]{color:var(--dsw-alias-state-error-primary);font-weight:600}',
+      '.w2mTarget_relayFold[data-temporary="true"]{border-top-color:var(--dsw-alias-state-error-primary)}',
+      '.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 +439,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 +519,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 +604,37 @@ 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'),
+              'data-temporary': relayFold.temporary === true ? 'true' : 'false',
+            }, [
+              h('button', {
+                key: 'toggle',
+                type: 'button',
+                className: cls('relayToggle'),
+                'aria-expanded': relayOpen,
+                'data-temporary': relayFold.temporary === true ? 'true' : 'false',
+                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')}${relayFold.temporary === true ? ` · ${t('relayTemporary')}` : ''}`),
+              ...(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.5.0",
+  "version": "1.5.2",
   "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": "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: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: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: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",
@@ -201,7 +201,9 @@
     "w2m-rabbit": "bin/w2m-rabbit.mjs",
     "w2m-stun": "bin/w2m-stun.mjs",
     "w2m-grant": "./bin/w2m-grant.mjs",
-    "w2m-secondary-link": "bin/w2m-secondary-link.mjs"
+    "w2m-secondary-link": "bin/w2m-secondary-link.mjs",
+    "w2m-bootstrap": "bin/w2m-bootstrap.mjs",
+    "w2m-bootstrap-sign": "bin/w2m-bootstrap-sign.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.5.0",
+  "version": "1.5.2",
   "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/bootstrap.mjs

@@ -0,0 +1,295 @@
+/**
+ * w2m relay bootstrap (v1.5.2) — verified relay assignment for a fresh installation.
+ *
+ * ## The problem
+ *
+ * A new install has no idea which relay its fleet uses: `rabbitUrl` falls back to the hard-coded
+ * shared server, so a machine can look connected while belonging to somebody else's data plane.
+ * Carrying a full `relayUrls` list by hand works, but it is easy to get wrong on the Nth machine.
+ *
+ * ## The shape of the answer
+ *
+ * The machine asks a **bootstrap endpoint** which relays its fleet uses, proves which fleet it is
+ * (an HMAC derived from the account's fleet key), and accepts the answer only if it is **signed by
+ * the operator's pinned Ed25519 key**. Four properties matter, and each has a test:
+ *
+ *   1. **No silent misdirection.** Every failure keeps the existing configuration: the plugin never
+ *      "helpfully" switches a machine to a relay whose answer it could not verify.
+ *   2. **The signature is over a canonical payload** (fleet id + relay list + validity window), so a
+ *      response cannot be replayed for another fleet or trimmed to one relay without detection.
+ *   3. **Replays are bounded by time.** `expires_at` is enforced against the local clock; an expired
+ *      answer is refused even when its signature is valid.
+ *   4. **A cache never outlives the answer.** The cached file is re-verified on every read (signature
+ *      and expiry), so editing it by hand cannot pin the machine to an unverified relay list.
+ *
+ * The request proof is HMAC-SHA256 over the fleet id, timestamp and nonce, keyed by the decoded
+ * fleet key. A static file server can ignore it; a real bootstrap service can rate-limit and scope
+ * by fleet without ever receiving the key itself.
+ */
+import { createHash, createHmac, createPublicKey, verify as verifySignature } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+/**
+ * Fleet-key helpers, implemented here rather than imported: `plugin` may not depend on `chatops`
+ * (the layer model refuses the upward edge), and these two functions are the whole of what this
+ * module needs. Keeping the dependency out is cheaper than an allow-list entry that would have
+ * to be justified forever.
+ */
+function decodeFleetKey(encoded) {
+  if (typeof encoded !== 'string' || encoded === '') return null;
+  try {
+    const buf = Buffer.from(encoded, 'base64url');
+    return buf.length === 32 ? buf : null;
+  } catch {
+    return null;
+  }
+}
+function fleetIdFromKey(key) {
+  return createHash('sha256').update(key).digest('hex');
+}
+
+
+
+export const BOOTSTRAP_PROTOCOL = 'w2m-bootstrap/v1';
+export const BOOTSTRAP_PROOF_PROTOCOL = 'w2m-bootstrap-proof/v1';
+/** Refusals are values with stable names, because the status surface reports them verbatim. */
+export const BOOTSTRAP_REFUSAL = Object.freeze({
+  NOT_CONFIGURED: 'BOOTSTRAP_NOT_CONFIGURED',
+  NO_FLEET_KEY: 'BOOTSTRAP_NO_FLEET_KEY',
+  NO_OPERATOR_PIN: 'BOOTSTRAP_NO_OPERATOR_PIN',
+  UNREACHABLE: 'BOOTSTRAP_UNREACHABLE',
+  BAD_JSON: 'BOOTSTRAP_BAD_JSON',
+  BAD_PROTOCOL: 'BOOTSTRAP_BAD_PROTOCOL',
+  WRONG_FLEET: 'BOOTSTRAP_WRONG_FLEET',
+  EXPIRED: 'BOOTSTRAP_EXPIRED',
+  BAD_SIGNATURE: 'BOOTSTRAP_BAD_SIGNATURE',
+  BAD_RELAYS: 'BOOTSTRAP_BAD_RELAYS',
+});
+
+const MAX_RELAYS = 16;
+
+/**
+ * The fleet id a bootstrap request proves. Derived from the key, never sent as a raw claim.
+ *
+ * @param {string} fleetKeyEncoded base64url 32-byte fleet key
+ * @returns {string|null}
+ */
+export function fleetIdOf(fleetKeyEncoded) {
+  const key = decodeFleetKey(fleetKeyEncoded);
+  return key === null ? null : fleetIdFromKey(key);
+}
+
+/**
+ * The canonical bytes the operator signs. Sorted, newline-joined, no JSON encoder ambiguity.
+ *
+ * @param {{fleet_id: string, relays: string[], issued_at: string, expires_at: string}} answer
+ * @returns {string}
+ */
+export function canonicalBootstrapPayload(answer) {
+  const relays = (Array.isArray(answer.relays) ? answer.relays : [])
+    .map((url) => String(url).trim().replace(/\/+$/, ''))
+    .sort();
+  return [
+    BOOTSTRAP_PROTOCOL,
+    String(answer.fleet_id ?? ''),
+    relays.join(','),
+    String(answer.issued_at ?? ''),
+    String(answer.expires_at ?? ''),
+  ].join('\n');
+}
+
+/**
+ * Build the request proof for one bootstrap call.
+ *
+ * @param {{fleetKey: string, fleetId: string, issuedAtMs?: number, nonce: string}} input
+ * @returns {{protocol: string, fleet_id: string, issued_at_ms: number, nonce: string, alg: string, proof: string}}
+ */
+export function buildBootstrapProof(input) {
+  const key = decodeFleetKey(input.fleetKey);
+  if (key === null) throw new TypeError('fleetKey must be a 32-byte base64url key');
+  const issuedAtMs = Number.isInteger(input.issuedAtMs) ? input.issuedAtMs : Date.now();
+  const nonce = String(input.nonce ?? '');
+  const message = [BOOTSTRAP_PROOF_PROTOCOL, input.fleetId, String(issuedAtMs), nonce].join('\n');
+  const proof = createHmac('sha256', key).update(message, 'utf8').digest('hex');
+  return {
+    protocol: BOOTSTRAP_PROOF_PROTOCOL,
+    fleet_id: input.fleetId,
+    issued_at_ms: issuedAtMs,
+    nonce,
+    alg: 'hmac-sha256',
+    proof,
+  };
+}
+
+/**
+ * Verify one signed bootstrap answer against the pinned operator key and this machine's fleet.
+ *
+ * @param {object} answer Parsed JSON body from the bootstrap endpoint.
+ * @param {{operatorPublicKeyPem: string, fleetId: string, nowMs?: number}} input
+ * @returns {{ok: true, relays: string[], issued_at: string, expires_at: string}
+ *   |{ok: false, reason_code: string, detail: string}}
+ */
+export function verifyBootstrapAnswer(answer, input) {
+  const refuse = (reason_code, detail) => ({ ok: false, reason_code, detail });
+  if (answer === null || typeof answer !== 'object' || Array.isArray(answer)) {
+    return refuse(BOOTSTRAP_REFUSAL.BAD_JSON, 'the bootstrap answer is not a JSON object');
+  }
+  if (answer.protocol !== BOOTSTRAP_PROTOCOL) {
+    return refuse(BOOTSTRAP_REFUSAL.BAD_PROTOCOL, `expected protocol ${BOOTSTRAP_PROTOCOL}, got ${JSON.stringify(answer.protocol ?? null)}`);
+  }
+  if (typeof answer.fleet_id !== 'string' || answer.fleet_id !== input.fleetId) {
+    return refuse(BOOTSTRAP_REFUSAL.WRONG_FLEET, 'the answer names a different fleet; it is not for this machine');
+  }
+  const relays = Array.isArray(answer.relays)
+    ? [...new Set(answer.relays.filter((url) => typeof url === 'string' && url.trim() !== '').map((url) => url.trim().replace(/\/+$/, '')))]
+    : [];
+  if (relays.length === 0) return refuse(BOOTSTRAP_REFUSAL.BAD_RELAYS, 'the answer carries no relay URLs');
+  if (relays.length > MAX_RELAYS) return refuse(BOOTSTRAP_REFUSAL.BAD_RELAYS, `the answer carries ${relays.length} relays, more than ${MAX_RELAYS}`);
+  for (const url of relays) {
+    if (!/^https?:\/\/[^\s]+$/.test(url)) return refuse(BOOTSTRAP_REFUSAL.BAD_RELAYS, `${JSON.stringify(url)} is not an http(s) base URL`);
+  }
+  const nowMs = Number.isInteger(input.nowMs) ? input.nowMs : Date.now();
+  const expiresAt = Date.parse(String(answer.expires_at ?? ''));
+  if (!Number.isFinite(expiresAt)) return refuse(BOOTSTRAP_REFUSAL.BAD_JSON, '`expires_at` is not a timestamp');
+  if (expiresAt <= nowMs) return refuse(BOOTSTRAP_REFUSAL.EXPIRED, `the answer expired at ${answer.expires_at}`);
+  const issuedAt = Date.parse(String(answer.issued_at ?? ''));
+  if (!Number.isFinite(issuedAt)) return refuse(BOOTSTRAP_REFUSAL.BAD_JSON, '`issued_at` is not a timestamp');
+  const signature = answer.signature;
+  const signatureB64 = typeof signature === 'string' ? signature
+    : (signature !== null && typeof signature === 'object' ? signature.value : undefined);
+  if (typeof signatureB64 !== 'string' || signatureB64 === '') {
+    return refuse(BOOTSTRAP_REFUSAL.BAD_SIGNATURE, 'the answer carries no signature');
+  }
+  let publicKey;
+  try {
+    publicKey = createPublicKey(input.operatorPublicKeyPem);
+  } catch (error) {
+    return refuse(BOOTSTRAP_REFUSAL.NO_OPERATOR_PIN, `the pinned operator key is not a usable PEM: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  const signed = canonicalBootstrapPayload({ fleet_id: answer.fleet_id, relays, issued_at: answer.issued_at, expires_at: answer.expires_at });
+  let signatureOk = false;
+  try {
+    signatureOk = verifySignature(null, Buffer.from(signed, 'utf8'), publicKey, Buffer.from(signatureB64, 'base64'));
+  } catch {
+    signatureOk = false;
+  }
+  if (!verifiedSignatureOk(signatureOk)) {
+    return refuse(BOOTSTRAP_REFUSAL.BAD_SIGNATURE, 'the answer signature does not match the pinned operator key and the canonical payload');
+  }
+  return { ok: true, relays, issued_at: answer.issued_at, expires_at: answer.expires_at };
+}
+
+/** Kept separate so a test can assert the failure branch without a real crypto fault. */
+function verifiedSignatureOk(value) {
+  return value === true;
+}
+
+/**
+ * Fetch, verify and cache one bootstrap answer.
+ *
+ * A cached file that still verifies is preferred (no network on every start); any verification
+ * failure falls through to a fresh fetch. Every failure keeps the caller's configuration untouched
+ * and returns a named reason for `w2m_status`.
+ *
+ * @param {object} deps
+ * @param {string} deps.url
+ * @param {string} deps.fleetKey
+ * @param {string} deps.operatorPublicKeyPem
+ * @param {string} deps.cacheFile
+ * @param {Function} [deps.fetchImpl]
+ * @param {number} [deps.timeoutMs]
+ * @param {number} [deps.nowMs]
+ * @param {(line: string) => void} [deps.log]
+ * @returns {Promise<{ok: true, relays: string[], source: 'cache'|'network', expires_at: string}
+ *   |{ok: false, reason_code: string, detail: string}>}
+ */
+export async function resolveBootstrap(deps) {
+  const log = deps.log ?? (() => {});
+  const fleetId = fleetIdOf(deps.fleetKey);
+  if (fleetId === null) {
+    return { ok: false, reason_code: BOOTSTRAP_REFUSAL.NO_FLEET_KEY, detail: 'no usable fleet key is configured, so no bootstrap proof can be made' };
+  }
+  const pinned = readBootstrapCache(deps.cacheFile, { operatorPublicKeyPem: deps.operatorPublicKeyPem, fleetId, nowMs: deps.nowMs });
+  if (pinned.ok === true) {
+    log(`w2m: bootstrap cache is valid (${pinned.relays.join(', ')})`);
+    return { ok: true, relays: pinned.relays, source: 'cache', expires_at: pinned.expires_at };
+  }
+  const fetchImpl = deps.fetchImpl ?? globalThis.fetch;
+  const timeoutMs = Number.isInteger(deps.timeoutMs) ? deps.timeoutMs : 4000;
+  const nonce = createHash('sha256').update(`${fleetId}:${Date.now()}:${Math.random()}`).digest('hex').slice(0, 32);
+  let proof;
+  try {
+    proof = buildBootstrapProof({ fleetKey: deps.fleetKey, fleetId, nonce });
+  } catch (error) {
+    return { ok: false, reason_code: BOOTSTRAP_REFUSAL.NO_FLEET_KEY, detail: error instanceof Error ? error.message : String(error) };
+  }
+  let answer;
+  try {
+    const response = await fetchImpl(deps.url, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ protocol: BOOTSTRAP_PROOF_PROTOCOL, proof }),
+      signal: typeof AbortSignal !== 'undefined' && typeof AbortSignal.timeout === 'function'
+        ? AbortSignal.timeout(timeoutMs) : undefined,
+    });
+    if (!response.ok) {
+      return { ok: false, reason_code: BOOTSTRAP_REFUSAL.UNREACHABLE, detail: `the bootstrap endpoint answered HTTP ${response.status}` };
+    }
+    answer = await response.json();
+  } catch (error) {
+    return { ok: false, reason_code: BOOTSTRAP_REFUSAL.UNREACHABLE, detail: error instanceof Error ? error.message : String(error) };
+  }
+  const verified = verifyBootstrapAnswer(answer, {
+    operatorPublicKeyPem: deps.operatorPublicKeyPem,
+    fleetId,
+    nowMs: deps.nowMs,
+  });
+  if (verified.ok !== true) return verified;
+  writeBootstrapCache(deps.cacheFile, { fleet_id: fleetId, relays: verified.relays, issued_at: verified.issued_at, expires_at: verified.expires_at, signature: answer.signature });
+  log(`w2m: bootstrap assigned relays (${verified.relays.join(', ')}, expires ${verified.expires_at})`);
+  return { ok: true, relays: verified.relays, source: 'network', expires_at: verified.expires_at };
+}
+
+/** Write a verified answer so the next start does not depend on the bootstrap endpoint being up. */
+export function writeBootstrapCache(file, entry) {
+  if (typeof file !== 'string' || file === '') return false;
+  try {
+    mkdirSync(dirname(file), { recursive: true });
+    const tmp = `${file}.tmp-${process.pid}`;
+    writeFileSync(tmp, `${JSON.stringify({ protocol: 'w2m-bootstrap-cache/v1', ...entry }, null, 2)}\n`, 'utf8');
+    renameSync(tmp, file);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Read the cache and re-verify it. A hand-edited cache is not trusted: the same signature check the
+ * network answer goes through runs here, so a cache cannot pin an unverified relay list.
+ *
+ * @param {string} file
+ * @param {{operatorPublicKeyPem: string, fleetId: string, nowMs?: number}} input
+ * @returns {{ok: true, relays: string[], expires_at: string}|{ok: false, reason_code: string, detail: string}}
+ */
+export function readBootstrapCache(file, input) {
+  const refuse = (reason_code, detail) => ({ ok: false, reason_code, detail });
+  if (typeof file !== 'string' || file === '' || !existsSync(file)) {
+    return refuse(BOOTSTRAP_REFUSAL.NOT_CONFIGURED, 'no bootstrap cache exists yet');
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(file, 'utf8'));
+  } catch (error) {
+    return refuse(BOOTSTRAP_REFUSAL.BAD_JSON, `the bootstrap cache is not JSON: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  const answer = {
+    protocol: BOOTSTRAP_PROTOCOL,
+    fleet_id: parsed.fleet_id,
+    relays: parsed.relays,
+    issued_at: parsed.issued_at,
+    expires_at: parsed.expires_at,
+    signature: parsed.signature,
+  };
+  return verifyBootstrapAnswer(answer, input);
+}

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,22 @@ 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,
+          // v1.5.2: a fallback relay list is never presented as settled; the panel renders it red.
+          temporary: relays.temporary === true,
+        },
   };
 }
 
@@ -680,12 +775,40 @@ 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);
+    // v1.5.2: a fallback list is marked so the panel can render it in red, not as a settled config.
+    const withMark = { ...folded, temporary: deps.cfg()?.relayTemporary === true };
+    relayCache = { at: now, value: withMark };
+    return withMark;
+  };
+
   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.5.0';
+const PLUGIN_VERSION = '1.5.2';
 
 /** How long any single HTTP call may take before it is aborted, in milliseconds. */
 const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;
@@ -885,6 +885,19 @@ function readConfig(config = {}) {
     rabbitUrl,
     rabbitSource,
     rabbitUrlOverride,
+    // v1.5.2: the relay pool and the bootstrap inputs. `relayUrls` is what `w2m-bootstrap` writes;
+    // `relayTemporary` marks a fallback list so the fleet panel can say "临时 Relay 节点" out loud
+    // instead of presenting a stranded machine's fallback as a settled configuration.
+    relayUrls: Array.isArray(config.relayUrls)
+      ? config.relayUrls.filter((url) => typeof url === 'string' && url.trim() !== '').map((url) => url.trim().replace(/\/+$/, ''))
+      : [],
+    relayTemporary: config.relayTemporary === true,
+    bootstrapUrl: typeof config.bootstrapUrl === 'string' && config.bootstrapUrl.trim() !== ''
+      ? config.bootstrapUrl.trim()
+      : (typeof process.env.W2M_BOOTSTRAP_URL === 'string' && process.env.W2M_BOOTSTRAP_URL.trim() !== '' ? process.env.W2M_BOOTSTRAP_URL.trim() : null),
+    bootstrapOperatorKeyPem: typeof config.bootstrapOperatorKey === 'string' && config.bootstrapOperatorKey.trim() !== ''
+      ? config.bootstrapOperatorKey
+      : (typeof process.env.W2M_BOOTSTRAP_OPERATOR_KEY === 'string' && process.env.W2M_BOOTSTRAP_OPERATOR_KEY.trim() !== '' ? process.env.W2M_BOOTSTRAP_OPERATOR_KEY : null),
     p2pMode,
     stunServers: stunList,
   };
@@ -2176,6 +2189,7 @@ async function readP2PStatus(cfg, runtime, peersAnnounced = null) {
     device_error: runtime.identityError,
     local: status?.local ?? null,
     rabbit_url: status?.rabbit_url ?? cfg.rabbitUrl,
+      bootstrap: cfg.bootstrap ?? null,
     // 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,
@@ -7354,6 +7368,46 @@ function sleepWithSignal(ms, signal) {
 const resolvedFleetKey = { value: null, source: null, at: 0 };
 
 async function startLocalStack(ctx, cfg) {
+
+  /**
+   * v1.5.2: bootstrap relay assignment. A fresh install has no relay list; without this it falls
+   * back to the compiled shared default, which is how a machine ends up looking connected on somebody
+   * else side. The answer is used only when it verified against the pinned operator key and is for
+   * this machine fleet; every failure leaves the configured relay untouched and is recorded in
+   * status, because a bootstrap that silently failed is indistinguishable from one never configured.
+   */
+  if ((Array.isArray(cfg.relayUrls) ? cfg.relayUrls.length : 0) === 0
+    && typeof cfg.bootstrapUrl === 'string' && typeof cfg.bootstrapOperatorKeyPem === 'string'
+    && typeof cfg.fleetKey === 'string') {
+    try {
+      const { resolveBootstrap } = await import(new URL('./bootstrap.mjs', import.meta.url).href);
+      const { homedir } = await import('node:os');
+      const { join } = await import('node:path');
+      const cacheFile = join(cfg.stateDir ?? join(process.env.DSH_HOME ?? join(homedir(), '.dsh'), 'xclient'), 'bootstrap.json');
+      const outcome = await resolveBootstrap({
+        url: cfg.bootstrapUrl,
+        fleetKey: cfg.fleetKey,
+        operatorPublicKeyPem: cfg.bootstrapOperatorKeyPem,
+        cacheFile,
+        log: (line) => ctx.logger?.info?.(line),
+      });
+      if (outcome.ok === true) {
+        cfg.relayUrls = outcome.relays;
+        if (cfg.rabbitSource === 'shared-default' || !cfg.rabbitUrl) { cfg.rabbitUrl = outcome.relays[0]; cfg.rabbitSource = 'bootstrap'; }
+        cfg.bootstrap = { configured: true, url: cfg.bootstrapUrl, source: outcome.source, relays: outcome.relays, expires_at: outcome.expires_at, last_error: null };
+        ctx.logger?.info?.('w2m: bootstrap assigned relays (' + outcome.relays.join(', ') + ')');
+      } else {
+        cfg.bootstrap = { configured: true, url: cfg.bootstrapUrl, source: null, relays: [], expires_at: null, last_error: { reason_code: outcome.reason_code, detail: outcome.detail } };
+        ctx.logger?.warn?.('w2m: bootstrap kept the configured relay (' + outcome.reason_code + ': ' + outcome.detail + ')');
+      }
+    } catch (error) {
+      cfg.bootstrap = { configured: true, url: cfg.bootstrapUrl, source: null, relays: [], expires_at: null, last_error: { reason_code: 'BOOTSTRAP_ERROR', detail: error instanceof Error ? error.message : String(error) } };
+      ctx.logger?.warn?.('w2m: bootstrap failed (' + (error instanceof Error ? error.message : String(error)) + ')');
+    }
+  } else if (cfg.bootstrap === undefined) {
+    cfg.bootstrap = { configured: typeof cfg.bootstrapUrl === 'string', url: cfg.bootstrapUrl ?? null, source: null, relays: [], expires_at: null, last_error: null };
+  }
+
   const relayUrl = new URL('../relay/server.mjs', import.meta.url);
   const agentUrl = new URL('../agent/agent.mjs', import.meta.url);