@twinsearth/w2m-dsh-plugin 2.0.7 → 2.0.8

package/src/agent/transfer/reference.mjs

@@ -0,0 +1,97 @@
+/**
+ * ArtifactRef v2 + 本地引用登记（C2 的基础形状）与解析阶梯（C3 的本地分支）。
+ *
+ * 控制面只承载元数据：object_id / task / machine / kind / sink / 大小 / 块数 / 根哈希 / TTL。
+ * 字节永远在本机对象库或用户 sink 里。resolver 不回落 relay：本地没有就明确
+ * TRANSFER_UNREACHABLE（远端 P2P 拉取是下一阶段接线）。
+ */
+import { mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const HEX64 = /^[0-9a-f]{64}$/;
+const OBJECT = /^[0-9a-f]{32,64}$/;
+
+export function createRef(manifest, { ttlMs = 24 * 3600 * 1000, now = Date.now } = {}) {
+  if (manifest === null || typeof manifest !== 'object') return { ok: false, code: 'XFER_MANIFEST_INVALID' };
+  if (!OBJECT.test(String(manifest.object_id ?? ''))) return { ok: false, code: 'XFER_OBJECT_ID_INVALID' };
+  if (!HEX64.test(String(manifest.root_sha256 ?? ''))) return { ok: false, code: 'XFER_ROOT_INVALID' };
+  if (!Number.isSafeInteger(manifest.size_bytes) || !Number.isSafeInteger(manifest.chunks)) return { ok: false, code: 'XFER_MANIFEST_INVALID' };
+  return {
+    ok: true,
+    ref: {
+      v: 2,
+      object_id: manifest.object_id,
+      task_id: manifest.task_id ?? null,
+      machine_id: manifest.machine_id ?? null,
+      kind: manifest.kind ?? 'stdout',
+      sink: { kind: manifest.sink?.kind ?? 'cache', rel_path: manifest.sink?.rel_path ?? manifest.object_id + '.bin' },
+      size_bytes: manifest.size_bytes,
+      chunk_bytes: manifest.chunk_bytes,
+      chunks: manifest.chunks,
+      root_sha256: manifest.root_sha256,
+      created_at: new Date(now()).toISOString(),
+      expires_at: new Date(now() + ttlMs).toISOString(),
+    },
+  };
+}
+
+export function verifyRef(ref, { now = Date.now } = {}) {
+  const nowMs = typeof now === 'function' ? now() : now;
+  if (ref === null || typeof ref !== 'object' || ref.v !== 2) return { ok: false, code: 'DELIVERY_REF_INVALID' };
+  if (!OBJECT.test(String(ref.object_id ?? ''))) return { ok: false, code: 'DELIVERY_REF_INVALID' };
+  if (!HEX64.test(String(ref.root_sha256 ?? ''))) return { ok: false, code: 'DELIVERY_REF_INVALID' };
+  if (!Number.isSafeInteger(ref.size_bytes) || !Number.isSafeInteger(ref.chunks) || ref.chunks < 0) return { ok: false, code: 'DELIVERY_REF_INVALID' };
+  if (typeof ref.expires_at === 'string' && Date.parse(ref.expires_at) <= nowMs) return { ok: false, code: 'DELIVERY_STALE' };
+  return { ok: true };
+}
+
+export function createRefRegistry({ root }) {
+  if (typeof root !== 'string' || root === '') throw new TypeError('XFER_REF_ROOT_REQUIRED');
+  const dir = join(root, 'refs');
+  const fileOf = (objectId) => join(dir, objectId + '.json');
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  return {
+    publish(ref) {
+      const checked = verifyRef(ref);
+      if (checked.ok !== true) return checked;
+      const file = fileOf(ref.object_id);
+      writeFileSync(file, JSON.stringify(ref), { encoding: 'utf8', mode: 0o600 });
+      return { ok: true, ref, path: file };
+    },
+    get(objectId) {
+      try {
+        const ref = JSON.parse(readFileSync(fileOf(objectId), 'utf8').replace(/^\uFEFF/, ''));
+        const checked = verifyRef(ref);
+        return checked.ok === true ? { ok: true, ref } : checked;
+      } catch {
+        return { ok: false, code: 'DELIVERY_REF_NOT_FOUND' };
+      }
+    },
+    list() {
+      const refs = [];
+      let names = [];
+      try { names = readdirSync(dir); } catch { return { ok: true, refs }; }
+      for (const name of names) {
+        if (!name.endsWith('.json')) continue;
+        try { const ref = JSON.parse(readFileSync(join(dir, name), 'utf8')); if (verifyRef(ref).ok === true) refs.push(ref); } catch { /* skip corrupt */ }
+      }
+      return { ok: true, refs };
+    },
+  };
+}
+
+/**
+ * 本地解析：对象已完整且根哈希匹配 → 返回路径；否则显式失败（不回落 relay）。
+ * 远端 P2P 拉取（C3 的 xfer 分支）在下一阶段接入，这里保留明确的失败语义。
+ */
+export function resolveLocal(ref, { store }) {
+  const checked = verifyRef(ref);
+  if (checked.ok !== true) return checked;
+  const local = store.has(ref.object_id);
+  if (local.ok !== true) return { ok: false, code: 'TRANSFER_UNREACHABLE', detail: { object_id: ref.object_id, reason: 'not in local object store; remote P2P fetch not wired yet' } };
+  if (local.complete !== true) return { ok: false, code: 'TRANSFER_INCOMPLETE', detail: { object_id: ref.object_id } };
+  const manifestPath = join(store.root, ref.object_id + '.ref.json');
+  const manifest = JSON.parse(readFileSync(manifestPath, 'utf8').replace(/^\uFEFF/, ''));
+  if (manifest.root_sha256 !== ref.root_sha256) return { ok: false, code: 'DELIVERY_ROOT_MISMATCH' };
+  return { ok: true, path: join(store.root, ref.object_id + '.bin'), bytes: manifest.size_bytes, object_id: ref.object_id };
+}

package/src/agent/transfer/want-block.mjs

@@ -0,0 +1,89 @@
+/**
+ * P2P want-block 协议（传输无关的最小实现）。
+ *
+ * 帧只在两台机器之间流动，绝不经过 relay：
+ *   xfer.want   { transferId, rootCid, indices }
+ *   xfer.chunk  { transferId, index, sha256, size, data(base64) }
+ *   xfer.error  { transferId, code, index? }
+ * 接收端把 chunk 交给 createReceiver().writeChunk；全部到齐后 finalize。
+ * 传输由调用方注入（P2PChannel / 测试用 duplex），本模块不发起 HTTP。
+ */
+import { createHash } from 'node:crypto';
+import { readSync, openSync, closeSync } from 'node:fs';
+
+export const WANT = 'xfer.want';
+export const CHUNK = 'xfer.chunk';
+export const ERROR = 'xfer.error';
+export const MAX_WINDOW = 8;
+export const MAX_CHUNK_B64 = 3 * 1024 * 1024;
+
+const isHex64 = (value) => typeof value === 'string' && /^[0-9a-f]{64}$/.test(value);
+
+/** 发送端：按请求读取文件块并编码为帧。 */
+export function createChunkSource({ chunked, filePath, transferId = null }) {
+  if (chunked === null || typeof chunked !== 'object' || !Array.isArray(chunked.chunks)) return { ok: false, code: 'XFER_SOURCE_INVALID' };
+  const tid = transferId ?? chunked.rootCid;
+  return {
+    ok: true,
+    handle(frame) {
+      if (frame?.type !== WANT) return { ok: false, code: 'XFER_FRAME_UNEXPECTED' };
+      if (frame.transferId !== tid) return { ok: false, code: 'XFER_TRANSFER_MISMATCH' };
+      if (frame.rootCid !== chunked.rootCid) return { ok: false, code: 'XFER_ROOT_MISMATCH' };
+      const indices = Array.isArray(frame.indices) ? frame.indices : [];
+      if (indices.length === 0 || indices.length > MAX_WINDOW) return { ok: false, code: 'XFER_WINDOW_INVALID' };
+      const out = [];
+      const fd = openSync(filePath, 'r');
+      try {
+        for (const index of indices) {
+          const chunk = chunked.chunks[index];
+          if (!Number.isInteger(index) || chunk === undefined) { out.push({ type: ERROR, transferId: tid, code: 'XFER_CHUNK_INDEX_INVALID', index }); continue; }
+          const buf = Buffer.alloc(chunk.size);
+          const read = readSync(fd, buf, 0, chunk.size, index * chunked.chunkBytes);
+          if (read !== chunk.size) { out.push({ type: ERROR, transferId: tid, code: 'XFER_READ_SHORT', index }); continue; }
+          out.push({ type: CHUNK, transferId: tid, index, sha256: chunk.sha256, size: chunk.size, data: buf.toString('base64') });
+        }
+      } finally { closeSync(fd); }
+      return { ok: true, frames: out };
+    },
+  };
+}
+
+/** 接收端：把帧写入 createReceiver；缺失块由 receiver 的位图反推。 */
+export function createWantClient({ transferId, rootCid, receiver }) {
+  if (typeof transferId !== 'string' || !isHex64(rootCid?.replace(/^sha256:/, ''))) return { ok: false, code: 'XFER_ROOT_INVALID' };
+  return {
+    ok: true,
+    missing() {
+      const have = receiver.have();
+      const total = receiver.progress().total;
+      const out = [];
+      for (let index = 0; index < total; index += 1) if (!have.has(index)) out.push(index);
+      return out;
+    },
+    requestFrames(indices) {
+      return [{ type: WANT, transferId, rootCid, indices: indices.slice(0, MAX_WINDOW) }];
+    },
+    accept(frame) {
+      if (frame?.type === ERROR) return { ok: false, code: frame.code ?? 'XFER_PEER_ERROR', index: frame.index ?? null };
+      if (frame?.type !== CHUNK) return { ok: false, code: 'XFER_FRAME_UNEXPECTED' };
+      if (frame.transferId !== transferId) return { ok: false, code: 'XFER_TRANSFER_MISMATCH' };
+      if (String(frame.data ?? '').length > MAX_CHUNK_B64) return { ok: false, code: 'XFER_CHUNK_TOO_LARGE' };
+      const data = Buffer.from(String(frame.data), 'base64');
+      const written = receiver.writeChunk(frame.index, data, frame.sha256);
+      if (written.ok !== true) return written;
+      return { ok: true, index: frame.index, complete: receiver.progress().complete };
+    },
+  };
+}
+
+/** 两帧之间的纯函数检查：块哈希与大小必须与声明一致（不依赖 receiver）。 */
+export function verifyChunkFrame(frame) {
+  if (frame?.type !== CHUNK) return { ok: false, code: 'XFER_FRAME_UNEXPECTED' };
+  if (!Number.isInteger(frame.index) || frame.index < 0) return { ok: false, code: 'XFER_CHUNK_INDEX_INVALID' };
+  if (!isHex64(frame.sha256)) return { ok: false, code: 'XFER_CHUNK_HASH_INVALID' };
+  const data = Buffer.from(String(frame.data ?? ''), 'base64');
+  if (data.length !== frame.size) return { ok: false, code: 'XFER_CHUNK_LENGTH_INVALID' };
+  const digest = createHash('sha256').update(data).digest('hex');
+  if (digest !== frame.sha256) return { ok: false, code: 'XFER_CHUNK_HASH_MISMATCH' };
+  return { ok: true, data };
+}

package/src/game/xiangqi.mjs

@@ -0,0 +1,217 @@
+/**
+ * 中国象棋核心规则（联合开发演示用，零依赖）。
+ *
+ * 棋盘 10 行 × 9 列：row 0 为黑方底线，row 9 为红方底线；红先。
+ * 棋子：K 帅/将, A 仕/士, E 相/象, H 马, R 车, C 炮, P 兵/卒。
+ * 已实现：全部走子规则、炮架、马腿、象眼、过河兵、九宫、飞将、将军/将死/困毙（困毙判负）。
+ */
+export const COLS = 9;
+export const ROWS = 10;
+const RED = 'r';
+const BLACK = 'b';
+
+const START = [
+  ['r', 'h', 'e', 'a', 'k', 'a', 'e', 'h', 'r'],
+  [null, null, null, null, null, null, null, null, null],
+  [null, 'c', null, null, null, null, null, 'c', null],
+  ['p', null, 'p', null, 'p', null, 'p', null, 'p'],
+  [null, null, null, null, null, null, null, null, null],
+  [null, null, null, null, null, null, null, null, null],
+  ['P', null, 'P', null, 'P', null, 'P', null, 'P'],
+  [null, 'C', null, null, null, null, null, 'C', null],
+  [null, null, null, null, null, null, null, null, null],
+  ['R', 'H', 'E', 'A', 'K', 'A', 'E', 'H', 'R'],
+];
+
+const isRed = (piece) => piece !== null && piece === piece.toUpperCase();
+const sideOf = (piece) => (piece === null ? null : isRed(piece) ? RED : BLACK);
+
+export function createGame() {
+  return {
+    board: START.map((row) => row.slice()),
+    turn: RED,
+    ply: 0,
+    history: [],
+    result: null,
+  };
+}
+
+const cloneBoard = (board) => board.map((row) => row.slice());
+const inBoard = (r, c) => r >= 0 && r < ROWS && c >= 0 && c < COLS;
+const inPalace = (side, r, c) => {
+  if (c < 3 || c > 5) return false;
+  return side === RED ? r >= 7 && r <= 9 : r >= 0 && r <= 2;
+};
+const crossedRiver = (side, r) => (side === RED ? r <= 4 : r >= 5);
+
+function pseudoMoves(board, side, r, c) {
+  const piece = board[r][c];
+  if (piece === null || sideOf(piece) !== side) return [];
+  const type = piece.toUpperCase();
+  const out = [];
+  const push = (rr, cc) => {
+    if (!inBoard(rr, cc)) return;
+    const target = board[rr][cc];
+    if (target === null || sideOf(target) !== side) out.push([rr, cc]);
+  };
+  if (type === 'K') {
+    for (const [dr, dc] of [[1, 0], [-1, 0], [0, 1], [0, -1]]) {
+      const rr = r + dr; const cc = c + dc;
+      if (inPalace(side, rr, cc)) push(rr, cc);
+    }
+  } else if (type === 'A') {
+    for (const [dr, dc] of [[1, 1], [1, -1], [-1, 1], [-1, -1]]) {
+      const rr = r + dr; const cc = c + dc;
+      if (inPalace(side, rr, cc)) push(rr, cc);
+    }
+  } else if (type === 'E') {
+    for (const [dr, dc] of [[2, 2], [2, -2], [-2, 2], [-2, -2]]) {
+      const rr = r + dr; const cc = c + dc;
+      if (!inBoard(rr, cc) || crossedRiver(side, rr)) continue;
+      if (board[r + dr / 2][c + dc / 2] !== null) continue;
+      push(rr, cc);
+    }
+  } else if (type === 'H') {
+    for (const [dr, dc, lr, lc] of [
+      [2, 1, 1, 0], [2, -1, 1, 0], [-2, 1, -1, 0], [-2, -1, -1, 0],
+      [1, 2, 0, 1], [-1, 2, 0, 1], [1, -2, 0, -1], [-1, -2, 0, -1],
+    ]) {
+      const rr = r + dr; const cc = c + dc;
+      if (!inBoard(rr, cc)) continue;
+      if (board[r + lr][c + lc] !== null) continue;
+      push(rr, cc);
+    }
+  } else if (type === 'R' || type === 'C') {
+    for (const [dr, dc] of [[1, 0], [-1, 0], [0, 1], [0, -1]]) {
+      let rr = r + dr; let cc = c + dc; let screen = false;
+      while (inBoard(rr, cc)) {
+        const target = board[rr][cc];
+        if (type === 'R') {
+          if (target === null) out.push([rr, cc]);
+          else { if (sideOf(target) !== side) out.push([rr, cc]); break; }
+        } else if (target === null) {
+          if (!screen) out.push([rr, cc]);
+        } else if (!screen) {
+          screen = true;
+        } else {
+          if (sideOf(target) !== side) out.push([rr, cc]);
+          break;
+        }
+        rr += dr; cc += dc;
+      }
+    }
+  } else if (type === 'P') {
+    const forward = side === RED ? -1 : 1;
+    push(r + forward, c);
+    if (crossedRiver(side, r)) { push(r, c - 1); push(r, c + 1); }
+  }
+  return out;
+}
+
+function kingAt(board, side) {
+  for (let r = 0; r < ROWS; r += 1) for (let c = 0; c < COLS; c += 1) {
+    const p = board[r][c];
+    if (p !== null && p.toUpperCase() === 'K' && sideOf(p) === side) return [r, c];
+  }
+  return null;
+}
+
+function kingsFace(board) {
+  const rk = kingAt(board, RED); const bk = kingAt(board, BLACK);
+  if (rk === null || bk === null || rk[1] !== bk[1]) return false;
+  const c = rk[1];
+  const from = Math.min(rk[0], bk[0]) + 1; const to = Math.max(rk[0], bk[0]);
+  for (let r = from; r < to; r += 1) if (board[r][c] !== null) return false;
+  return true;
+}
+
+/** 某方是否被将军（含飞将）。 */
+export function inCheck(board, side) {
+  if (kingsFace(board)) return true;
+  const king = kingAt(board, side);
+  if (king === null) return true;
+  const enemy = side === RED ? BLACK : RED;
+  for (let r = 0; r < ROWS; r += 1) for (let c = 0; c < COLS; c += 1) {
+    const p = board[r][c];
+    if (p === null || sideOf(p) !== enemy) continue;
+    if (pseudoMoves(board, enemy, r, c).some(([rr, cc]) => rr === king[0] && cc === king[1])) return true;
+  }
+  return false;
+}
+
+export function legalMovesFrom(board, side, r, c) {
+  return pseudoMoves(board, side, r, c).filter(([rr, cc]) => {
+    const next = cloneBoard(board);
+    next[rr][cc] = next[r][c]; next[r][c] = null;
+    return !inCheck(next, side);
+  });
+}
+
+export function allLegalMoves(board, side) {
+  const out = [];
+  for (let r = 0; r < ROWS; r += 1) for (let c = 0; c < COLS; c += 1) {
+    if (board[r][c] !== null && sideOf(board[r][c]) === side) {
+      for (const [rr, cc] of legalMovesFrom(board, side, r, c)) out.push({ from: [r, c], to: [rr, cc] });
+    }
+  }
+  return out;
+}
+
+const FILE = 'abcdefghi';
+export const squareName = (r, c) => FILE[c] + String(ROWS - r);
+
+/** @returns {{ok: true, state: object, move: object} | {ok: false, code: string}} */
+export function applyMove(game, from, to) {
+  if (game.result !== null) return { ok: false, code: 'GAME_OVER' };
+  if (!Array.isArray(from) || !Array.isArray(to) || !inBoard(from[0], from[1]) || !inBoard(to[0], to[1])) return { ok: false, code: 'SQUARE_INVALID' };
+  const piece = game.board[from[0]][from[1]];
+  if (piece === null || sideOf(piece) !== game.turn) return { ok: false, code: 'NOT_YOUR_PIECE' };
+  const legal = legalMovesFrom(game.board, game.turn, from[0], from[1]);
+  if (!legal.some(([r, c]) => r === to[0] && c === to[1])) return { ok: false, code: 'ILLEGAL_MOVE' };
+  const board = cloneBoard(game.board);
+  const captured = board[to[0]][to[1]];
+  board[to[0]][to[1]] = piece; board[from[0]][from[1]] = null;
+  const mover = game.turn;
+  const next = { ...game, board, turn: mover === RED ? BLACK : RED, ply: game.ply + 1, history: [...game.history, { from, to, piece, captured }] };
+  const opponentHasMoves = allLegalMoves(board, next.turn).length > 0;
+  const opponentChecked = inCheck(board, next.turn);
+  if (!opponentHasMoves) {
+    next.result = { winner: mover, reason: captured !== null && captured.toUpperCase() === 'K' ? 'KING_CAPTURED' : opponentChecked ? 'CHECKMATE' : 'STALEMATE' };
+  } else if (opponentChecked) {
+    next.check = true;
+  } else {
+    next.check = false;
+  }
+  next.lastMove = { from, to, piece, captured, check: opponentChecked === true && next.result === null };
+  return { ok: true, state: next, move: next.lastMove };
+}
+
+const GLYPH = { K: '帅', A: '仕', E: '相', H: '马', R: '车', C: '炮', P: '兵', k: '将', a: '士', e: '象', h: '马', r: '车', c: '炮', p: '卒' };
+
+export function boardAscii(game) {
+  const lines = ['    a b c d e f g h i'];
+  for (let r = 0; r < ROWS; r += 1) {
+    const cells = [];
+    for (let c = 0; c < COLS; c += 1) {
+      const p = game.board[r][c];
+      cells.push(p === null ? '·' : GLYPH[p] ?? p);
+    }
+    lines.push(String(ROWS - r).padStart(2, ' ') + '  ' + cells.join(' '));
+  }
+  lines.push('    a b c d e f g h i');
+  return lines.join('\n');
+}
+
+export function moveText(move) {
+  return squareName(move.from[0], move.from[1]) + '-' + squareName(move.to[0], move.to[1]);
+}
+
+export function describeProgress(game) {
+  const side = game.turn === RED ? '红' : '黑';
+  if (game.result !== null) {
+    const winner = game.result.winner === RED ? '红方' : '黑方';
+    return `第 ${game.ply} 手结束：${winner}胜（${game.result.reason}）`;
+  }
+  const last = game.lastMove ? `上一手 ${moveText(game.lastMove)}${game.lastMove.captured ? ' 吃 ' + GLYPH[game.lastMove.captured] : ''}` : '开局';
+  return `第 ${game.ply} 手 · ${side}方行棋 · ${last}${game.check ? ' · 将军！' : ''}`;
+}

package/src/plugin/fleet-binding.mjs

@@ -0,0 +1,105 @@
+/**
+ * Fleet binding diagnostics (read-only).
+ *
+ * A device token can be valid while `fleet_id` is null: the relay lists the machine globally
+ * ("all machines") but filters it out of every fleet view ("this fleet"). v0.8.7's
+ * "already paired -> do not pair again" rule made that state sticky, so it needs to be
+ * *observed* rather than inferred from "paired: true".
+ *
+ * Nothing here writes: the status tool reports, and the auto-start path decides whether to
+ * re-admit using the fleet key it already holds.
+ */
+
+export const FLEET_BINDING_CODE = Object.freeze({
+  BOUND: 'FLEET_BOUND',
+  UNBOUND: 'FLEET_UNBOUND',
+  UNPAIRED: 'FLEET_UNPAIRED',
+  TOKEN_REJECTED: 'FLEET_TOKEN_REJECTED',
+  UNKNOWN: 'FLEET_UNKNOWN',
+});
+
+/**
+ * Should a start-up re-admit even though a token exists?
+ * Only when the token is valid, the machine has no fleet, and a key is available to bind it.
+ */
+export function shouldRejoin({ token, fleetId, fleetKey }) {
+  return typeof token === 'string' && token !== ''
+    && (fleetId === null || fleetId === undefined || fleetId === '')
+    && typeof fleetKey === 'string' && fleetKey.trim() !== '';
+}
+
+/**
+ * Read this machine's relay record and classify its fleet binding.
+ *
+ * @param {{relayUrl: string, token: string|null, machineId: string|null,
+ *          fleetKey: string|null, fetchImpl?: Function, timeoutMs?: number}} input
+ * @returns {Promise<object>} a bounded, token-free status block
+ */
+export async function diagnoseFleetBinding({ relayUrl, token, machineId, fleetKey = null, fetchImpl = fetch, timeoutMs = 2500 }) {
+  const checkedAt = new Date().toISOString();
+  const fleetKeyConfigured = typeof fleetKey === 'string' && fleetKey.trim() !== '';
+  const base = {
+    ok: true,
+    state: 'unknown',
+    code: FLEET_BINDING_CODE.UNKNOWN,
+    fleet_id: null,
+    token_present: typeof token === 'string' && token !== '',
+    fleet_key_configured: fleetKeyConfigured,
+    machine_id: machineId,
+    checked_at: checkedAt,
+    detail: null,
+    remedy: null,
+  };
+  if (base.token_present !== true) {
+    return { ...base, state: 'unpaired', code: FLEET_BINDING_CODE.UNPAIRED, detail: 'this machine has no device token' };
+  }
+  if (typeof relayUrl !== 'string' || relayUrl === '') {
+    return { ...base, detail: 'no relay URL is configured' };
+  }
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetchImpl(relayUrl.replace(/\/+$/, '') + '/v1/devices', {
+      headers: { authorization: 'Bearer ' + token, accept: 'application/json' },
+      signal: controller.signal,
+    });
+    if (response.status === 401 || response.status === 403) {
+      return {
+        ...base,
+        state: 'token_rejected',
+        code: FLEET_BINDING_CODE.TOKEN_REJECTED,
+        detail: 'the relay rejected this device token (HTTP ' + response.status + ')',
+        remedy: 're-pair this machine (the stored token is stale for this relay)',
+      };
+    }
+    if (response.ok !== true) {
+      return { ...base, detail: 'the relay answered HTTP ' + response.status };
+    }
+    const body = await response.json().catch(() => null);
+    const devices = Array.isArray(body?.devices) ? body.devices : [];
+    const self = devices.find((entry) => entry?.machine_id === machineId) ?? null;
+    if (self === null) {
+      return { ...base, detail: 'the relay answered 200 but does not list this machine' };
+    }
+    const fleetId = typeof self.fleet_id === 'string' && self.fleet_id !== '' ? self.fleet_id : null;
+    if (fleetId === null) {
+      return {
+        ...base,
+        state: 'unbound',
+        code: FLEET_BINDING_CODE.UNBOUND,
+        detail: 'the token is valid, but the relay records this machine with fleet_id=null',
+        remedy: fleetKeyConfigured
+          ? 'a fleet key is configured; the next start re-admits this machine into its fleet'
+          : 'set fleetKey / W2M_FLEET_KEY, then restart the agent so the machine can join its fleet',
+      };
+    }
+    return { ...base, state: 'bound', code: FLEET_BINDING_CODE.BOUND, fleet_id: fleetId };
+  } catch (error) {
+    return {
+      ...base,
+      detail: 'the fleet binding could not be read: ' + (error instanceof Error ? error.message : String(error)),
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/src/plugin/tools.mjs

@@ -1,4 +1,5 @@
-import { FAILOVER_DEFAULTS, createRelayFailover, relayPool } from './relay-failover.mjs';
+import { FAILOVER_DEFAULTS, createRelayFailover, relayPool } from './relay-failover.mjs';
+import { diagnoseFleetBinding, shouldRejoin } from './fleet-binding.mjs';
 import { DEFAULT_BOOTSTRAP_URL, DEFAULT_BOOTSTRAP_OPERATOR_KEY_PEM } from './bootstrap.mjs';
 /**
  * DSH: Windows2MacO - the DSH Cordis plugin.
@@ -290,7 +291,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 = '2.0.7';
+const PLUGIN_VERSION = '2.0.8';
 
 /** How long any single HTTP call may take before it is aborted, in milliseconds. */
 const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;
@@ -4997,6 +4998,13 @@ const result = await request({
       };
       })();
 
+      const fleetBinding = await diagnoseFleetBinding({
+        relayUrl: cfg.rabbitUrl,
+        token: device.device_token,
+        machineId: device.machine_id,
+        fleetKey: cfg.fleetKey,
+      });
+
       return JSON.stringify(
         {
           ok: true,
@@ -5020,7 +5028,8 @@ const result = await request({
            */
           rabbit_source: cfg.rabbitSource,
           rabbit_url: cfg.rabbitUrl,
-          p2p: p2pStatus,
+          p2p: p2pStatus,
+          fleet: fleetBinding,
           rtt,
           config: {
             rabbitUrl: cfg.rabbitUrl,
@@ -5030,7 +5039,8 @@ const result = await request({
             projectDir: cfg.projectDir,
             autoStartAgent: cfg.autoStartAgent,
             allowedCommands: cfg.allowedCommands,
-            pairingCode_configured: cfg.pairingCode !== null,
+            pairingCode_configured: cfg.pairingCode !== null,
+            fleetKey_configured: cfg.fleetKey !== null,
             p2pMode: cfg.p2pMode,
             // The resolved list, shared server first, exactly as the node will query it.
             stunServers: cfg.stunServers,
@@ -8029,6 +8039,18 @@ async function startLocalStack(ctx, cfg) {
             if (identityOptions.identity !== undefined && identityOptions.identity !== null) identityOptions.identity.device_token = null;
             ctx.logger?.warn?.('w2m: stored device token was rejected by ' + relayForToken + ' (HTTP ' + probe.status + '); pairing again with the fleet key');
           }
+          if (alreadyPaired && fleetKeyFromConfig !== null) {
+            const binding = await diagnoseFleetBinding({
+              relayUrl: relayForToken,
+              token: existingToken,
+              machineId: loaded.identity.machine_id,
+              fleetKey: fleetKeyFromConfig,
+            });
+            if (shouldRejoin({ token: existingToken, fleetId: binding.fleet_id, fleetKey: fleetKeyFromConfig })) {
+              alreadyPaired = false;
+              ctx.logger?.warn?.('w2m: FLEET_UNBOUND (token valid, fleet_id=null); re-admitting with the configured fleet key');
+            }
+          }
         } catch { /* network error: keep the token, do not force a re-pair */ }
       }
     }