@twinsearth/w2m-dsh-plugin 1.5.1 → 1.5.3

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.1"
+    "version": "1.5.3"
   },
   "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.1",
+      "version": "1.5.3",
       "author": {
         "name": "TwinsEarth"
       },
@@ -26,5 +26,5 @@
       ]
     }
   ],
-  "version": "1.5.1"
+  "version": "1.5.3"
 }

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

package/CHANGELOG.md

@@ -7,6 +7,41 @@
 
 All notable changes to this project are documented here.
 
+## [1.5.3] — 2026-10-23
+
+**零接触自动入队：只能升级插件的机器也能自己找到编队。**
+
+v1.5.2 的验签 bootstrap 需要一个 URL、一个 operator 公钥和 fleetKey 才能触发——新装机器三样都没有，
+于是仍然回落到编译期默认 relay 并报 W2M_UNREACHABLE。v1.5.3 把触发条件做进包里：
+
+- 包内置默认 bootstrap 端点与 **operator 公钥 pin**（只含公钥；端点无法签发，私钥不出运维机）。
+- bootstrap 证明改为可选：机器还没拿到 fleetKey 时，仍可凭"签名 + 有效期 + relay 形状"采用
+  operator 声明的 relay 池（relay 列表是公开路由信息；加入编队仍需账号派生密钥，是独立一步）。
+- `startLocalStack` 在无 relayUrls 时始终尝试 bootstrap（默认值生效），成功即用池（首个 primary），
+  失败保持回落并写入 `w2m_status.bootstrap.last_error`。
+- 包内默认 patch：`autoStartAgent: true`（本 fork），新装即启动 agent。
+- 因此只有"升级插件"这一条通道的机器：升级 → 重启 → 自动取 relay 池 → 账号密钥就绪后自动配对入队。
+- 测试：bootstrap 6/6（含 keyless）、bootstrap-cli 6/6、fleet-target 49/49；层模型 clean；
+  证据 `docs/acceptance/1.5.3/ZERO-TOUCH-BOOTSTRAP.json`（真实 fleet task `01M5ANYMVKZ7DHH`）。
+## [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 折叠。**

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/codex/mcp-servers.toml

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

package/cordis.patch.yml

@@ -110,7 +110,7 @@
       config:
         rabbitUrl: ''
         operatorToken: ''
-        autoStartAgent: false
+        autoStartAgent: true
         machineName: ''
         allowedCommands: []
         p2pMode: auto

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/docs/acceptance/1.5.3/ZERO-TOUCH-BOOTSTRAP.json

@@ -0,0 +1,22 @@
+{
+  "version": "1.5.3",
+  "case": "ZERO-TOUCH-BOOTSTRAP",
+  "kind": "positive",
+  "machines": [
+    "b53a37f4-1464-4512-9259-33a7df091e3e"
+  ],
+  "executed_at": "2026-10-23T12:58:49.026Z",
+  "executor": "lead",
+  "requirement": "a machine whose only capability is upgrading the plugin obtains its relay pool without any local command: built-in bootstrap URL and operator public key, signature-verified keyless assignment, autoStartAgent on by default",
+  "task_id": "01M5ANYMVKZ7DHH",
+  "result": {
+    "outcome": "ok",
+    "assertions": {
+      "bootstrap_suite": "6/6 pass incl keyless",
+      "bootstrap_cli_suite": "6/6 pass",
+      "builtin_defaults": "endpoint+pin shipped",
+      "autoStartAgent_default": "true"
+    }
+  },
+  "note": "suites ran as a real fleet task on the Tencent relay; keyless assignment verified by unit test"
+}

package/lib/client.js

@@ -111,6 +111,7 @@ window.__ModuleLoader__.load({
         relayOffline: '离线',
         relayFold: '另有 {count} 个已折叠，点击展开',
         relayUnfold: '收起折叠的 relay',
+        relayTemporary: '临时 Relay 节点（回退配置）',
         capLabel: 'Node 执行：{state}',
         capDenied: '拒绝',
         capTemporary: '临时 24 小时',
@@ -141,6 +142,7 @@ window.__ModuleLoader__.load({
         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',
@@ -325,6 +327,8 @@ window.__ModuleLoader__.load({
       '.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}',
@@ -605,15 +609,17 @@ window.__ModuleLoader__.load({
               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')}`),
+              }, `${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'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twinsearth/w2m-dsh-plugin",
-  "version": "1.5.1",
+  "version": "1.5.3",
   "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.1",
+  "version": "1.5.3",
   "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,311 @@
+/**
+ * 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';
+/**
+ * v1.5.3 built-in bootstrap defaults.
+ *
+ * A machine whose only capability is "upgrade the plugin" cannot be told a URL or a pin by hand,
+ * so the operator's endpoint and public key ship inside the package. Only the PUBLIC key is here:
+ * the endpoint cannot mint answers, and the private key never leaves the operator's machine. A signed
+ * answer still has to verify and be unexpired, so the built-in values are a discovery hint, not trust.
+ */
+export const DEFAULT_BOOTSTRAP_URL = 'http://202.182.123.154:8911/bootstrap';
+export const DEFAULT_BOOTSTRAP_OPERATOR_KEY_PEM = [
+  '-----BEGIN PUBLIC KEY-----',
+  'MCowBQYDK2VwAyEAQdjWX9TggM/S1Bm/OKUI3/Q2IL20Le354AXwiMtua+0=',
+  '-----END PUBLIC KEY-----',
+  '',
+].join(String.fromCharCode(10));
+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)}`);
+  }
+  // v1.5.3: when the machine cannot derive a fleet key yet, it still must not be stranded: the
+  // signed relay list is public routing information, so a signature-only answer is adopted for relay
+  // assignment. Joining the fleet still needs the account-derived key, which is a separate step.
+  if (input.fleetId !== null && input.fleetId !== undefined && (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 = deps.fleetKey === null || deps.fleetKey === undefined ? null : fleetIdOf(deps.fleetKey);
+  if (deps.fleetKey !== null && deps.fleetKey !== undefined && fleetId === null) {
+    return { ok: false, reason_code: BOOTSTRAP_REFUSAL.NO_FLEET_KEY, detail: 'the configured fleet key is not a 32-byte base64url key' };
+  }
+  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);
+  // v1.5.3: the proof is optional. Without a fleet key the request cannot prove which fleet it is,
+  // but the ANSWER is still verified by signature, expiry and relay shape -- so relay assignment can
+  // be automatic even before an account-derived key is available.
+  const proof = deps.fleetKey === null || deps.fleetKey === undefined ? null : buildBootstrapProof({ fleetKey: deps.fleetKey, fleetId, nonce });
+  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

@@ -571,6 +571,8 @@ export function buildUiState(deps) {
           // 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,
         },
   };
 }
@@ -793,8 +795,10 @@ function mountTargetRoutes(connection, deps, status, logger) {
       return { ...item, role: reachableSeen === 1 ? 'primary' : 'standby' };
     });
     const folded = foldRelayItems(items, 3);
-    relayCache = { at: now, value: folded };
-    return folded;
+    // 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) => {

package/src/plugin/tools.mjs

@@ -1,3 +1,4 @@
+import { DEFAULT_BOOTSTRAP_URL, DEFAULT_BOOTSTRAP_OPERATOR_KEY_PEM } from './bootstrap.mjs';
 /**
  * DSH: Windows2MacO - the DSH Cordis plugin.
  *
@@ -276,7 +277,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.1';
+const PLUGIN_VERSION = '1.5.3';
 
 /** How long any single HTTP call may take before it is aborted, in milliseconds. */
 const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;
@@ -885,6 +886,21 @@ 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,
+    // v1.5.3: the operator endpoint and its public pin ship with the package, so a machine whose only
+    // capability is upgrading the plugin still finds its fleet. Explicit config/env still wins.
+    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() : DEFAULT_BOOTSTRAP_URL),
+    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 : DEFAULT_BOOTSTRAP_OPERATOR_KEY_PEM),
     p2pMode,
     stunServers: stunList,
   };
@@ -2176,6 +2192,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,
@@ -4936,7 +4953,12 @@ export async function apply(ctx, config = {}) {
   // Optional: bring up relay + agent in this process
   // -------------------------------------------------------------------------------------------
   if (cfg.autoStartAgent) {
-    ctx.effect?.(() => startLocalStack(ctx, cfg));
+    // 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.logger?.warn?.('w2m: auto-start did not complete: ' + (error instanceof Error ? error.message : String(error)));
+  }));
   } else {
     /**
      * v0.8.5: **say it out loud.**
@@ -7354,6 +7376,45 @@ 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') {
+    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 ?? null,
+        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);