dsh-lan-peers 0.7.2 → 0.7.3

package/HANDOVER.md

@@ -180,7 +180,11 @@ ssh ai@192.168.5.51 "sudo systemctl restart dsh-web"
 4. 重启桌面版。
 
 改完文件不必重启：**改 profile 的 `cordis.patch.yml` 会触发热重载**（改包内文件不会，需要动一下 profile 文件）。
-> ⚠️ **2026-10-27 实测反例**：桌面版（0.4.0，Windows）`touch ~/.dsh/profiles/desktop/cordis.patch.yml` **没有**触发热重载——`~/.dsh/lan-peers.log` 无新的 `listening` 行，`/api/lan-peers/panel.js` 仍返回旧内容。改动包内 `lib/` 后要生效必须**重启桌面应用**。这条待复核是否与版本有关，暂勿再把它当作可靠热重载手段。
+> ✅ **2026-10-27 更正（重要）**：**改 profile `cordis.patch.yml` 的内容会触发插件热重载**——实测桌面版 14:58:06 因新增一行 `hubPriority: 10` 而重载，日志出现新的 `module imported` 与 `listening`，`/v1/health` 从 0.7.0 直接变成 0.7.2（说明它重新 import 了 `link:` 指向的最新代码）。
+> 但**单纯 `touch`（不改内容）不会**触发——早先据此写下的「热重载不可靠」是**错误结论**，已更正。
+> 实用含义：想在不重启应用的前提下加载新的服务端代码，**改一下 profile 配置内容（哪怕加一行注释）** 即可；客户端组件（面板 UI）是否随之刷新仍未验证，界面上看不到变化时仍需重启。
+
+> ⚠️ 旧的错误结论（保留作教训）：曾记录「touch profile 不触发热重载」——错在只 `touch` 没改内容。
 
 ## 8. 回归检查清单（发版/部署后跑）
 

package/host/server.mjs

@@ -96,7 +96,7 @@ import { parseArgs } from 'node:util';
 // ---------------------------------------------------------------------------
 
 /** 插件版本，用于 /v1/health.version */
-export const PLUGIN_VERSION = '0.7.2';
+export const PLUGIN_VERSION = '0.7.3';
 
 /** §4.1 允许的时钟偏移 */
 export const CLOCK_SKEW_MS = 60_000;
@@ -986,6 +986,9 @@ export class GroupStore {
     if (!Array.isArray(data.messages)) data.messages = [];
     // S3 §5：未提交区。与 messages 分开存，读写都不进 history/pull/events。
     if (!Array.isArray(data.pending)) data.pending = [];
+    // 被移除的成员：记住它，防止它用「自助 join」把自己加回来（踢人要真的踢掉）。
+    // 只有运维显式 addMember 会把这条记录清掉（等价于重新邀请）。
+    if (typeof data.blocked !== 'object' || data.blocked === null || Array.isArray(data.blocked)) data.blocked = {};
     data.pending = data.pending.filter((entry) => entry && typeof entry === 'object'
       && Number.isFinite(Number(entry.seq)) && Number(entry.seq) > 0);
     if (typeof data.members !== 'object' || data.members === null || Array.isArray(data.members)) data.members = {};
@@ -1044,6 +1047,11 @@ export class GroupStore {
     const id = String(peerId ?? '').trim();
     if (id === '') throw new Error('member peerId must not be empty');
     const data = this.#load();
+    // 运维显式加人 = 重新邀请：解除「被移除」记录
+    if (Object.prototype.hasOwnProperty.call(data.blocked ?? {}, id)) {
+      delete data.blocked[id];
+      this.#save(data);
+    }
     const existing = data.members[id];
     if (!existing) {
       data.members[id] = { name: String(name ?? ''), addedAt: nowIso(this.#now()) };
@@ -1055,11 +1063,24 @@ export class GroupStore {
     return data.members[id];
   }
 
+  /** 这个 peerId 是否被运维移除过（自助 join 必须拒绝） */
+  isBlocked(peerId) {
+    const data = this.#load();
+    return Object.prototype.hasOwnProperty.call(data.blocked ?? {}, String(peerId ?? ''));
+  }
+
   removeMember(peerId) {
     const data = this.#load();
     const id = String(peerId ?? '');
     if (!Object.prototype.hasOwnProperty.call(data.members, id)) return false;
     delete data.members[id];
+    // 记住「被移除」：否则它还能用 per-peer 签名走 /v1/group/join（autoJoin）把自己加回来
+    data.blocked[id] = nowIso(this.#now());
+    // 移除成员 = 它可能还握着旧 groupKey：必须立刻轮换密钥，否则「踢人」形同虚设
+    // （被移除者只要还能用旧钥签名，就能把自己的心跳送进来）。
+    data.key = randomBytes(32).toString('base64url');
+    const version = Number(data.keyVersion);
+    data.keyVersion = (Number.isInteger(version) && version >= 1 ? version : 1) + 1;
     this.#save(data);
     return true;
   }
@@ -1809,7 +1830,7 @@ export function createPeerServer(overrides = {}) {
    * groupId 一致、senderPeerId 在成员表、ts ±60s、nonce 120s 去重。
    * 返回 {ok:true, senderId, ctx} 或 {ok:false, status, error}。
    */
-  function verifyGroupAuth(req, rawBody) {
+  function verifyGroupAuth(req, rawBody, { allowUnknownSender = false } = {}) {
     const senderId = headerValue(req, 'x-peer-id');
     const groupId = headerValue(req, GROUP_ID_HEADER.toLowerCase());
     const tsRaw = headerValue(req, 'x-peer-ts');
@@ -1824,9 +1845,8 @@ export function createPeerServer(overrides = {}) {
     const ctx = localGroupContext();
     if (!ctx || !ctx.groupKey) return { ok: false, status: 401, error: 'group-auth-unavailable' };
     if (String(groupId) !== String(ctx.groupId)) return { ok: false, status: 401, error: 'group-mismatch' };
-    if (senderId !== store.instanceId && !Object.prototype.hasOwnProperty.call(ctx.members, senderId)) {
-      return { ok: false, status: 401, error: 'not-a-member' };
-    }
+    // 先验签、再查成员表：被移除的成员拿着**旧群密钥**打进来应当是 bad-signature（密钥世代不对），
+    // 而不是 not-a-member —— 这样「移除成员即轮换密钥」才有可验证的信号。
     const canonical = buildGroupCanonical({
       method: req.method,
       path: req.url,
@@ -1839,6 +1859,15 @@ export function createPeerServer(overrides = {}) {
     const { signKey } = deriveGroupKeys(ctx.groupKey);
     const expected = signGroupCanonical({ signKey, canonical });
     if (!timingSafeStringEqual(expected, signature)) return { ok: false, status: 401, error: 'bad-signature' };
+    if (senderId !== store.instanceId && !Object.prototype.hasOwnProperty.call(ctx.members, senderId)) {
+      // hub 是权威成员表：不认识就是不属于群，一律拒绝（自愈只给成员侧的副本用）
+      if (!allowUnknownSender || groupStore) return { ok: false, status: 401, error: 'not-a-member' };
+      // 自愈（真机 not-a-member 回归）：群密钥签名已经证明对端握有群密钥，只是本机成员表
+      // 还停在一份不完整的快照上（成员在 bootstrap 之后才加入）。选举/心跳是领导权协议，
+      // 先把它补进成员表，否则对端永远投不进来、整个群选不出 leader。
+      upsertGroupMember(senderId);
+      if (config.logger) config.logger(`[group] member healed peer=${shortPeerId(senderId)}`);
+    }
     // 只有签名通过的 nonce 才登记（同 per-peer 路径）
     rememberGroupNonce(nonce, nowMs);
     return { ok: true, senderId, ctx };
@@ -2495,6 +2524,11 @@ export function createPeerServer(overrides = {}) {
     const existing = groupMemberOf(auth.peerId);
     if (!existing) {
       if (!config.group.autoJoin) return { status: 403, body: { error: 'not-a-member' }, peerId: auth.peerId };
+      // 被移除过的成员：自助 join 不生效（必须有运维显式 addMember 重新邀请）
+      if (groupStore.isBlocked(auth.peerId)) {
+        if (config.logger) config.logger(`[group] join refused peer=${shortPeerId(auth.peerId)} reason=removed`);
+        return { status: 403, body: { error: 'not-a-member' }, peerId: auth.peerId };
+      }
       groupStore.addMember(auth.peerId, requestedName ?? auth.peer?.name ?? '');
       if (config.logger) config.logger(`[group] join ${auth.peerId}`);
     } else if (requestedName && requestedName !== existing.name) {
@@ -2676,6 +2710,97 @@ export function createPeerServer(overrides = {}) {
     memberProgress.set(id, { lastSeq: Math.floor(seq), at: config.now() });
   }
 
+  /** 把对端补进本机成员表（自愈用）：hub 写 group.json，成员写 group-key.json */
+  /** 群密钥世代（hub 读 group.json 的 keyVersion，成员读 group-key.json 的 epoch） */
+  function groupKeyVersion() {
+    const ctx = localGroupContext();
+    return Number(ctx?.epoch) || 0;
+  }
+
+  /**
+   * 成员侧换钥：hub 轮换 groupKey（例如移除成员）后，老密钥的请求会变成 401 bad-signature。
+   * 用 per-peer 签名重取 GET /v1/group/state（响应加密、含 groupKey/keyVersion），
+   * 更新本地 group-key.json 后由调用方重试一次。
+   */
+  let lastKeyRefreshAt = 0;
+
+  async function refreshGroupKeyFromHub() {
+    if (groupRole !== 'member') return { ok: false, reason: 'not-member' };
+    // 节流：同一秒内的连续坏签名不重复拉 state（脏请求打不爆）
+    if (config.now() - lastKeyRefreshAt < 1_000) return { ok: false, reason: 'throttled' };
+    lastKeyRefreshAt = config.now();
+    const hub = groupHubPeer();
+    if (!hub) return { ok: false, reason: 'hub-not-paired' };
+    try {
+      const state = await fetchGroupState({
+        baseUrl: hub.baseUrl,
+        secret: hub.secret,
+        senderId: store.instanceId,
+        timeoutMs: 5_000,
+      });
+      if (!state?.groupId || !state?.groupKey) return { ok: false, reason: 'group-state-incomplete' };
+      const existing = readGroupKeyFile(config.stateDir) ?? { members: {} };
+      const keyVersion = Number(state.keyVersion) || Number(state.epoch) || 0;
+      const members = { ...(existing.members ?? {}) };
+      if (!members[store.instanceId]) members[store.instanceId] = { name: config.name, baseUrl: '' };
+      writeGroupKeyFile(config.stateDir, {
+        ...existing,
+        groupId: String(state.groupId),
+        key: String(state.groupKey),
+        // epoch 只增不减：轮换后这里跟着 keyVersion 走，角色初始化再用 max() 兜一次
+        epoch: Math.max(Number(existing.epoch) || 0, keyVersion),
+        leaderPeerId: String(existing.leaderPeerId ?? ''),
+        name: config.name,
+        members,
+      });
+      replicaStore?.ensureHeader?.({ groupId: String(state.groupId) });
+      if (config.logger) config.logger(`[group] key refreshed keyVersion=${keyVersion}`);
+      return { ok: true, keyVersion };
+    } catch (error) {
+      if (config.logger) {
+        config.logger(`[group] key refresh failed reason=${String(error?.message ?? error).slice(0, 60)}`);
+      }
+      return { ok: false, reason: 'refresh-failed' };
+    }
+  }
+
+  /**
+   * 群级请求的统一入口：正常发一次；成员侧遇到 401 bad-signature 就换钥再发**一次**。
+   * callFn 拿到的 ctx（groupKey/groupId）在重试时是重新读盘得到的，保证用的是新钥。
+   */
+  async function withGroupKey(callFn) {
+    const ctx = localGroupContext();
+    if (!ctx?.groupKey) throw new Error('group-key-missing');
+    try {
+      return await callFn(ctx);
+    } catch (error) {
+      const code = String(error?.code ?? '');
+      const status = Number(error?.status);
+      const retryable = groupRole === 'member'
+        && ((status === 401 && code === 'bad-signature')
+          || (status === 400 && code === 'bad-encryption'));
+      if (!retryable) throw error;
+      const refreshed = await refreshGroupKeyFromHub();
+      if (refreshed.ok !== true) throw error;
+      const fresh = localGroupContext();
+      if (!fresh?.groupKey) throw error;
+      return callFn(fresh);
+    }
+  }
+
+  function upsertGroupMember(peerId) {
+    const id = String(peerId ?? '');
+    if (id === '') return;
+    if (groupStore) {
+      groupStore.addMember(id, '');
+      return;
+    }
+    const existing = readGroupKeyFile(config.stateDir);
+    if (!existing || existing.members?.[id]) return;
+    const members = { ...existing.members, [id]: { name: '', baseUrl: '' } };
+    writeGroupKeyFile(config.stateDir, { ...existing, members });
+  }
+
   function groupMemberName(peerId) {
     const ctx = localGroupContext();
     return String(ctx?.members?.[peerId]?.name ?? '') || config.name;
@@ -2686,9 +2811,13 @@ export function createPeerServer(overrides = {}) {
    *   1) X-Peer-Auth: group —— 群级签名（成员之间、成员→hub 的复制/补差）；
    *   2) 现有 per-peer 签名 —— CLI 排障用（仍要过成员门控，与 state/history 同口径）。
    */
-  function authorizeGroupRequest(req, rawBody) {
+  /** 领导权协议：允许「成员表未同步」的对端自愈进来（其余路径仍严格按成员表 401） */
+  const GROUP_SELF_HEAL_PATHS = new Set(['/v1/group/election', '/v1/group/leader']);
+
+  function authorizeGroupRequest(req, rawBody, url = null) {
     if (headerValue(req, GROUP_AUTH_HEADER.toLowerCase()) === GROUP_AUTH_VALUE) {
-      const checked = verifyGroupAuth(req, rawBody);
+      const allowUnknownSender = Boolean(url && GROUP_SELF_HEAL_PATHS.has(url.pathname));
+      const checked = verifyGroupAuth(req, rawBody, { allowUnknownSender });
       if (!checked.ok) return checked;
       return { ok: true, mode: 'group', peerId: checked.senderId, ctx: checked.ctx };
     }
@@ -2849,6 +2978,12 @@ export function createPeerServer(overrides = {}) {
   let roleTimer = null;
   let heartbeatTimer = null;
   let roleSeeded = false;
+  /** 本进程启动时刻（受限启动竞选的「稳定期」起点） */
+  const processStartedAtMs = config.now();
+  /** 契约补充：每个进程生命周期最多尝试一次按优先级接管 */
+  let takeoverAttempted = false;
+  let takeoverAttempts = 0;
+  const takeoverStableMs = heartbeatMs * 2;
   /** 提交串行化：一次只让一条消息走 propose→commit，seq 才连续、pending 区才不撞号 */
   let postChain = Promise.resolve();
 
@@ -2885,7 +3020,12 @@ export function createPeerServer(overrides = {}) {
         groupId: String(ctx?.groupId ?? st.groupId ?? ''),
       });
     }
-    if (st.groupId === '' && ctx?.groupId) return roleStore.update({ groupId: String(ctx.groupId) });
+    if (st.groupId === '' && ctx?.groupId) {
+      return roleStore.update({ groupId: String(ctx.groupId) });
+    }
+    // 密钥轮换（keyVersion 变大）后角色 epoch 至少跟上：epoch 只升不降，
+    // 否则重启后会以更低的 epoch 参与裁决（契约 §4 里 epoch 低就是服从）。
+    if (st.epoch < baseEpoch) return roleStore.update({ epoch: baseEpoch });
     return st;
   }
 
@@ -3152,10 +3292,12 @@ export function createPeerServer(overrides = {}) {
       selfBaseUrl: localAdvertiseBaseUrl(),
       timeoutMs: peerTimeoutMs,
     };
-    const results = await Promise.allSettled(targets.map((peerId) => sendGroupHeartbeat({
+    const results = await Promise.allSettled(targets.map((peerId) => withGroupKey((keyCtx) => sendGroupHeartbeat({
       ...base,
+      groupKey: keyCtx.groupKey,
+      groupId: String(keyCtx.groupId),
       baseUrl: baseUrlOf(peerId),
-    })));
+    }))));
     let conflictWith = '';
     let ahead = null;
     for (const result of results) {
@@ -3206,10 +3348,12 @@ export function createPeerServer(overrides = {}) {
       timeoutMs: peerTimeoutMs,
     };
     const targets = peerTargets();
-    const results = await Promise.allSettled(targets.map((peerId) => commitGroupMessage({
+    const results = await Promise.allSettled(targets.map((peerId) => withGroupKey((keyCtx) => commitGroupMessage({
       ...base,
+      groupKey: keyCtx.groupKey,
+      groupId: String(keyCtx.groupId),
       baseUrl: baseUrlOf(peerId),
-    })));
+    }))));
     return { ok: true, delivered: results.filter((entry) => entry.status === 'fulfilled').length, total: targets.length };
   }
 
@@ -3267,17 +3411,17 @@ export function createPeerServer(overrides = {}) {
       let unreachable = unreachableBase;
       const tasks = targets.map(async (peerId) => {
         try {
-          const reply = await requestGroupVote({
+          const reply = await withGroupKey((keyCtx) => requestGroupVote({
             baseUrl: baseUrlOf(peerId),
-            groupKey: ctx.groupKey,
-            groupId: String(ctx.groupId),
+            groupKey: keyCtx.groupKey,
+            groupId: String(keyCtx.groupId),
             senderId: store.instanceId,
             epoch,
             candidate: store.instanceId,
             priority: hubPriority,
             selfBaseUrl: localAdvertiseBaseUrl(),
             timeoutMs: peerTimeoutMs,
-          });
+          }));
           if (Number(reply?.epoch) > epoch && String(reply?.leaderPeerId ?? '') !== '') ahead = reply;
           if (typeof reply?.advertiseBaseUrl === 'string') rememberPeerBaseUrl(peerId, reply.advertiseBaseUrl);
           return reply?.vote === true;
@@ -3336,11 +3480,61 @@ export function createPeerServer(overrides = {}) {
     }
   }
 
+  /**
+   * 受限的「启动后按优先级接管」（每进程最多一次）。
+   *
+   * 背景：契约 §4 是「epoch 高者胜，同 epoch 才比 priority」，所以优先级**不能跨 epoch** 夺权。
+   * 真机事故形态：优先节点（NAS，hubPriority=0）重启期间备份节点抢到 epoch=4 当了 leader，
+   * NAS 回来只能一直当 follower —— priority 永远等不到生效的机会。
+   *
+   * 因此给「配置上没有 group.hub 的本机」（即配置上的 hub）一次**有边界**的重试权：
+   * 进程启动稳定 2×heartbeatMs、当前有一个租约有效的 leader、且本机优先级严格更高时，
+   * 发起一次 epoch+1 的选举。赢则收回 leadership，输则本进程内永久放弃（不循环重试）。
+   * 成员节点（配了 group.hub）不参与：运维的接线意图是「以 hub 为准」。
+   */
+  async function maybePriorityTakeover() {
+    if (!roleStore || takeoverAttempted) return { attempted: false, reason: 'already-done-or-off' };
+    if (String(config.group.hub ?? '') !== '') return { attempted: false, reason: 'member-role' };
+    const st = ensureRole();
+    if (!st || st.role !== 'follower') return { attempted: false, reason: 'not-follower' };
+    // 只在「跟得好好的」时候动手：没有 leader 或租约已过期，交给正常的 lease-expired 选举
+    if (st.leaderPeerId === '' || config.now() > st.leaseUntil) {
+      return { attempted: false, reason: 'no-stable-leader' };
+    }
+    if (config.now() - processStartedAtMs < takeoverStableMs) {
+      return { attempted: false, reason: 'not-stable-yet' };
+    }
+    const leaderPriority = priorityOf(st.leaderPeerId);
+    // 只有**严格**更高（数值更小）才值得动一次；相等一律不动（避免同优先级互抢）
+    if (!(hubPriority < leaderPriority)) return { attempted: false, reason: 'not-higher-priority' };
+    takeoverAttempted = true;
+    takeoverAttempts += 1;
+    const epoch = st.epoch + 1;
+    if (config.logger) {
+      config.logger(`[group] takeover attempt epoch=${epoch} priority=${hubPriority} leaderPriority=${leaderPriority}`);
+    }
+    const out = await runElection({ reason: 'priority-takeover', forcedEpoch: epoch });
+    if (config.logger) {
+      if (out?.ok === true) {
+        config.logger(`[group] takeover won epoch=${out.epoch} votes=${out.votes}/${out.needed}`);
+      } else {
+        config.logger(
+          `[group] takeover lost epoch=${out?.epoch ?? epoch} votes=${out?.votes ?? 1}/${out?.needed ?? quorumNeeded()}`
+            + ` reason=${out?.reason ?? 'unknown'}`,
+        );
+      }
+    }
+    return { attempted: true, result: out };
+  }
   /** 租约检查：非 leader 且租约过期 → 进入候选并发起选举（抖动在 runElection 里） */
   async function roleTick() {
     const st = ensureRole();
     if (!st || st.role === 'leader') return { ok: false, reason: 'leader-or-off' };
     if (electionInFlight) return { ok: false, reason: 'election-in-flight' };
+    // ① 受限的启动竞选（每进程最多一次；不满足条件时什么也不做）
+    const takeover = await maybePriorityTakeover();
+    if (takeover.attempted) return takeover.result ?? { ok: false, reason: 'takeover-attempted' };
+    // ② 租约过期 → 正常选举
     if (config.now() <= st.leaseUntil) return { ok: false, reason: 'lease-valid' };
     if (peerTargets().length === 0) return { ok: false, reason: 'no-peers-with-address' };
     return runElection({ reason: 'lease-expired' });
@@ -3437,6 +3631,8 @@ export function createPeerServer(overrides = {}) {
         // 分母与门槛：成员表全集（含没有地址的成员），地址只影响投递
         memberCount: quorumMembers().length,
         quorumNeeded: quorumNeeded(),
+        // 群密钥世代（只给世代，不给密钥）：轮换后可从这里看出来
+        keyVersion: groupKeyVersion(),
         degraded: isDegraded(),
         advertiseBaseUrl: localAdvertiseBaseUrl(),
       },
@@ -3694,7 +3890,12 @@ export function createPeerServer(overrides = {}) {
     };
     const tasks = targets.map(async (peerId) => {
       try {
-        const reply = await proposeGroupMessage({ ...base, baseUrl: baseUrlOf(peerId) });
+        const reply = await withGroupKey((keyCtx) => proposeGroupMessage({
+          ...base,
+          groupKey: keyCtx.groupKey,
+          groupId: String(keyCtx.groupId),
+          baseUrl: baseUrlOf(peerId),
+        }));
         return reply?.ok === true;
       } catch {
         return false;
@@ -3737,7 +3938,13 @@ export function createPeerServer(overrides = {}) {
     };
     const handler = handlers[`${method} ${url.pathname}`];
     if (!handler) return { status: 405, body: { error: 'method-not-allowed' } };
-    const auth = authorizeGroupRequest(req, rawBody);
+    let auth = authorizeGroupRequest(req, rawBody, url);
+    if (!auth.ok && groupRole === 'member' && String(auth.error) === 'bad-signature') {
+      // hub 轮换密钥后，成员手里的旧钥会让**入站**请求也变成 bad-signature；
+      // 这里先按 per-peer 换钥，再验一次（只重试一次），避免「谁也没法先动」的死锁。
+      const refreshed = await refreshGroupKeyFromHub();
+      if (refreshed.ok === true) auth = authorizeGroupRequest(req, rawBody, url);
+    }
     if (!auth.ok) return { status: auth.status, body: { error: auth.error }, peerId: null };
     return handler(req, rawBody, url, auth);
   }
@@ -3894,10 +4101,15 @@ export function createPeerServer(overrides = {}) {
     return { peerId: String(hub.peerId ?? ''), name: String(hub.name ?? ''), baseUrl, secret: String(hub.secret) };
   }
 
+  /**
+   * 刷新成员侧成员表。**只增不减**：一份过早/不完整的快照（成员在 bootstrap 之后才加入）
+   * 不该把仍在群的成员从本机表里抹掉 —— 真机上这会让该成员的心跳/投票被 401 not-a-member 挡在门外。
+   * 移除成员的权威在 hub 侧 group.json（本机表里多出来的条目只会让多数派更保守）。
+   */
   function saveGroupMembers(members, names = {}) {
     const existing = readGroupKeyFile(config.stateDir);
     if (!existing) return;
-    const next = {};
+    const next = { ...existing.members };
     for (const peerId of members) {
       const id = String(peerId ?? '');
       if (id === '') continue;
@@ -3988,10 +4200,10 @@ export function createPeerServer(overrides = {}) {
       }
       if (!ctx?.groupKey) return { ok: false, reason: 'no-group-key' };
       const sinceSeq = replicaStore.state().lastSeq;
-      const page = await pullGroupMessages({
+      const page = await withGroupKey((keyCtx) => pullGroupMessages({
         baseUrl: hub.baseUrl,
-        groupKey: ctx.groupKey,
-        groupId: ctx.groupId,
+        groupKey: keyCtx.groupKey,
+        groupId: keyCtx.groupId,
         senderId: store.instanceId,
         sinceSeq,
         limit: GROUP_HISTORY_MAX_LIMIT,
@@ -3999,7 +4211,7 @@ export function createPeerServer(overrides = {}) {
         // 自报复制进度：hub 的面板据此显示「落后 leader 多少条」
         lastSeq: sinceSeq,
         timeoutMs: Math.max(1000, replicaPullMs),
-      });
+      }));
       if (String(page?.groupId ?? '') !== String(ctx.groupId)) {
         throw new Error('group-mismatch');
       }
@@ -4091,14 +4303,38 @@ export function createPeerServer(overrides = {}) {
         if (groupAuthRequest) {
           const groupCtx = localGroupContext();
           if (groupCtx?.groupKey) {
-            const { bodyKey } = deriveGroupKeys(groupCtx.groupKey);
+            let bodyKey = deriveGroupKeys(groupCtx.groupKey).bodyKey;
             groupResponseKey = bodyKey;
             const encrypted = String(req.headers[ENC_HEADER] ?? '') === ENC_VERSION;
             if (encrypted && rawBody.length > 0) {
+              let decrypted = false;
               try {
                 rawBody = decryptGroupBody(bodyKey, rawBody.toString('utf8'));
+                decrypted = true;
               } catch {
+                decrypted = false;
+              }
+              if (!decrypted) {
+                // hub 轮换了群密钥：成员侧先按 per-peer 换钥再解一次（只一次）
+                const healed = groupRole === 'member' ? await refreshGroupKeyFromHub() : { ok: false };
+                if (healed.ok === true) {
+                  const freshCtx = localGroupContext();
+                  if (freshCtx?.groupKey) {
+                    bodyKey = deriveGroupKeys(freshCtx.groupKey).bodyKey;
+                    groupResponseKey = bodyKey;
+                    try {
+                      rawBody = decryptGroupBody(bodyKey, rawBody.toString('utf8'));
+                      decrypted = true;
+                    } catch {
+                      decrypted = false;
+                    }
+                  }
+                }
+              }
+              if (!decrypted) {
+                // 对端拿的可能仍是旧钥：错误体走**明文**，否则它连信封都解不开
                 result = { status: 400, body: { error: 'bad-encryption' } };
+                groupResponseKey = null;
               }
             }
           }
@@ -4138,7 +4374,9 @@ export function createPeerServer(overrides = {}) {
 
     if (!res.headersSent) {
       try {
-        const body = groupResponseKey
+        // 错误体一律明文：群级请求失败时对端可能拿着旧钥（密钥刚轮换），加密过去它连错误码都读不到，
+        // 也就无法据此换钥重试。错误体只有 {error, epoch, ...} 之类的码，不含任何密钥。
+        const body = (groupResponseKey && result.status < 400)
           ? {
               enc: ENC_VERSION,
               data: encryptGroupBody(groupResponseKey, Buffer.from(JSON.stringify(result.body), 'utf8')),
@@ -4151,10 +4389,13 @@ export function createPeerServer(overrides = {}) {
     }
     if (config.logger) {
       const elapsedMs = Number(process.hrtime.bigint() - startedAt) / 1e6;
-      // 只记录方法、路径、状态、耗时、peerId；绝不记录 header / secret / 签名原文
+      // 只记录方法、路径、状态、耗时、peerId、错误码（4xx/5xx 时才带，便于排障）；
+      // 绝不记录 header / secret / 签名原文
+      const errorCode = result.status >= 400 ? String(result.body?.error ?? '') : '';
       config.logger(
         `${nowIso(Date.now())} ${String(req.method).toUpperCase()} ${url.pathname} `
-        + `${result.status} ${elapsedMs.toFixed(1)}ms peer=${result.peerId ?? '-'}`,
+        + `${result.status} ${elapsedMs.toFixed(1)}ms peer=${result.peerId ?? '-'}`
+        + `${errorCode === '' ? '' : ` err=${errorCode}`}`,
       );
     }
   });
@@ -4178,6 +4419,7 @@ export function createPeerServer(overrides = {}) {
         groupId: st.groupId,
         degraded: isDegraded(),
         quorum: quorumMode,
+        keyVersion: groupKeyVersion(),
       };
     },
     /** 契约 §7：POST /api/lan-peers/group/leader {action:claim} 的落点 */
@@ -4202,6 +4444,15 @@ export function createPeerServer(overrides = {}) {
     heartbeat: () => broadcastHeartbeat(),
     quorumMode: () => quorumMode,
     pendingCount: () => pendingCount(),
+    /** 受限启动竞选的状态：attempted 只在本进程尝试过后为 true，attempts 恒 ≤ 1 */
+    takeover: () => ({
+      attempted: takeoverAttempted,
+      attempts: takeoverAttempts,
+      stableMs: takeoverStableMs,
+      sinceStartMs: config.now() - processStartedAtMs,
+      priority: hubPriority,
+      leaderPriority: roleState()?.leaderPeerId ? priorityOf(roleState().leaderPeerId) : null,
+    }),
     degraded: () => isDegraded(),
     roleFile: roleStore ? roleStore.rolePath : null,
   };
@@ -4226,7 +4477,18 @@ export function createPeerServer(overrides = {}) {
           state: (options = {}) => groupStore.state(options),
           members: () => groupMembersView(),
           addMember: (peerId, name) => groupStore.addMember(peerId, name),
-          removeMember: (peerId) => groupStore.removeMember(peerId),
+          removeMember: (peerId) => {
+            const removed = groupStore.removeMember(peerId);
+            if (!removed) return removed;
+            const id = String(peerId ?? '');
+            memberProgress.delete(id);
+            peerBaseUrls.delete(id);
+            peerPriorities.delete(id);
+            if (config.logger) {
+              config.logger(`[group] key rotated keyVersion=${groupStore.state().keyVersion} reason=member-removed`);
+            }
+            return removed;
+          },
           rename: (nextName) => groupStore.renameGroup(nextName),
           post: (input) => groupStore.append(input),
           // 与 /v1/group/history 同一个渲染口径：同名成员在这里就已经带上短 id 后缀
@@ -4350,7 +4612,10 @@ Options:
   --group-auto-join           允许已配对成员自助加入（默认关闭）
   --group-retention-days <n>  历史保留天数（默认 7，0 = 读到时立即清旧）
   --group-advertise-base-url <url>  本机对外可达地址（默认自动探测私有 IPv4）
-  --group-quorum <mode>       majority|none（S3 生效；本轮只解析）
+  --group-quorum <mode>       majority|none（S3：majority = propose/commit 两阶段）
+  --group-heartbeat-ms <ms>   leader 心跳间隔（默认 3000；租约 = 3×）
+  --group-commit-timeout-ms <ms>  propose→commit 超时（默认 3000）
+  --group-hub-priority <n>    同 epoch 裁决优先级（数值小者优先，默认 0）
   --group-replica-pull-ms <ms>  成员向 leader 补差间隔（默认 10000）
   --code                      只生成并打印一次性配对码，然后退出
   -h, --help                  显示帮助
@@ -4380,6 +4645,9 @@ async function main(argv) {
       'group-retention-days': { type: 'string' },
       'group-advertise-base-url': { type: 'string' },
       'group-quorum': { type: 'string' },
+      'group-heartbeat-ms': { type: 'string' },
+      'group-commit-timeout-ms': { type: 'string' },
+      'group-hub-priority': { type: 'string' },
       'group-replica-pull-ms': { type: 'string' },
       code: { type: 'boolean', default: false },
       help: { type: 'boolean', short: 'h', default: false },
@@ -4407,6 +4675,8 @@ async function main(argv) {
     group: (values.group || values['group-hub'] != null || values['group-name'] != null
       || values['group-auto-join'] || values['group-retention-days'] != null
       || values['group-advertise-base-url'] != null || values['group-quorum'] != null
+      || values['group-heartbeat-ms'] != null || values['group-commit-timeout-ms'] != null
+      || values['group-hub-priority'] != null
       || values['group-replica-pull-ms'] != null)
       ? {
           enabled: values.group === true,
@@ -4418,6 +4688,15 @@ async function main(argv) {
             : Number(values['group-retention-days']),
           advertiseBaseUrl: values['group-advertise-base-url'],
           quorum: values['group-quorum'],
+          heartbeatMs: values['group-heartbeat-ms'] == null
+            ? undefined
+            : Number(values['group-heartbeat-ms']),
+          commitTimeoutMs: values['group-commit-timeout-ms'] == null
+            ? undefined
+            : Number(values['group-commit-timeout-ms']),
+          hubPriority: values['group-hub-priority'] == null
+            ? undefined
+            : Number(values['group-hub-priority']),
           replicaPullMs: values['group-replica-pull-ms'] == null
             ? undefined
             : Number(values['group-replica-pull-ms']),

package/host/test/group-cluster.mjs

@@ -89,6 +89,12 @@ export async function startCluster(t, options = {}) {
     commitTimeoutMs: commitOverride = commitTimeoutMs,
     tickMs: tickOverride = tickMs,
     jitterMs = 0,
+    // S3 补充：哪些下标是「hub 角色」（配置上没有 group.hub，可参与启动接管）。默认只有 0。
+    hubRoles = [0],
+    // 预置角色文件：{ 下标: leader 下标 } → 该节点以 follower 起步（leader 指向另一台）
+    followerOf = {},
+    // 假时钟（「推进 30s 验证不再重试」这类断言用）
+    now: nowOverride = null,
   } = options;
 
   const ids = customIds ?? Array.from({ length: count }, (_, index) => `peer-s3-${String.fromCharCode(97 + index)}`);
@@ -106,9 +112,46 @@ export async function startCluster(t, options = {}) {
 
   const nodes = [];
   const urls = [];
+  const hubRoleIndexes = new Set(hubRoles);
+  hubRoleIndexes.add(0);
+  /** node0 的群快照：后面的 hub 角色节点要复用同一 groupId/groupKey */
+  let hubSnapshot = null;
   for (let index = 0; index < count; index += 1) {
     // 先写 peers.json 再 listen：成员启动那一轮就能解析到 hub
     writePeersJson(dirs[index], ids, names, urls, index);
+    const isHubRole = hubRoleIndexes.has(index);
+    if (index > 0 && isHubRole && hubSnapshot) {
+      // 第二个 hub 角色节点：先把 group.json 写成与 node0 同一把群密钥/groupId，
+      // 否则 GroupStore 首次 load 会自己生成一份新的（那就不是一个群了）
+      const members = {};
+      for (let other = 0; other < index; other += 1) {
+        members[ids[other]] = { name: names[other], baseUrl: urls[other], addedAt: new Date().toISOString() };
+      }
+      members[ids[index]] = { name: names[index], addedAt: new Date().toISOString() };
+      writeJson0600(path.join(dirs[index], 'group.json'), {
+        groupId: hubSnapshot.groupId,
+        key: hubSnapshot.groupKey,
+        keyVersion: hubSnapshot.epoch,
+        name: hubSnapshot.name,
+        createdAt: new Date().toISOString(),
+        members,
+        messages: [],
+        pending: [],
+        lastSeq: 0,
+      });
+    }
+    if (index in followerOf) {
+      // 预置角色文件：以 follower 起步（leader 指向 followerOf[index] 那台）
+      writeJson0600(path.join(dirs[index], 'group-role.json'), {
+        role: 'follower',
+        epoch: hubSnapshot ? hubSnapshot.epoch : 1,
+        leaderPeerId: ids[followerOf[index]],
+        leaseUntil: Date.now() + 60_000,
+        commitSeq: 0,
+        votedFor: null,
+        groupId: hubSnapshot ? hubSnapshot.groupId : '',
+      });
+    }
     const group = {
       enabled: true,
       name: 's3',
@@ -119,11 +162,12 @@ export async function startCluster(t, options = {}) {
       commitTimeoutMs: commitOverride,
       hubPriority: priorities[index] ?? 0,
     };
-    if (index > 0) group.hub = names[0];
+    if (!isHubRole) group.hub = names[0];
     const server = createPeerServer({
       listenHost: '127.0.0.1',
       stateDir: dirs[index],
       requireEncryption,
+      ...(nowOverride ? { now: nowOverride } : {}),
       allowRemotePrompts: true,
       logger,
       group,
@@ -140,6 +184,11 @@ export async function startCluster(t, options = {}) {
     const info = await server.listen(0, '127.0.0.1');
     server.config.group.advertiseBaseUrl = info.url;
     urls[index] = info.url;
+    if (isHubRole) {
+      const self = server.group.state().members[ids[index]];
+      if (self) self.baseUrl = info.url;
+      if (!hubSnapshot) hubSnapshot = server.group.state({ includeKey: true });
+    }
     nodes.push({
       index,
       peerId: ids[index],
@@ -160,6 +209,16 @@ export async function startCluster(t, options = {}) {
     hub.server.group.state().members[ids[index]].baseUrl = urls[index];
   }
 
+  // 第二个及以后的 hub 角色节点：成员表补齐（自己那条地址在 listen 后已写）
+  for (const node of nodes.slice(1)) {
+    if (!node.server.group.isHub) continue;
+    for (let index = 0; index < count; index += 1) {
+      if (index === node.index) continue;
+      node.server.group.addMember(ids[index], names[index]);
+      node.server.group.state().members[ids[index]].baseUrl = urls[index];
+    }
+  }
+
   const snapshot = hub.server.group.state({ includeKey: true });
   for (let index = 1; index < count; index += 1) {
     const members = {};

package/host/test/group-election.test.mjs

@@ -11,8 +11,11 @@ import fs from 'node:fs';
 import { setTimeout as sleep } from 'node:timers/promises';
 import {
   fetchGroupLease,
+  pullGroupMessages,
+  readGroupKeyFile,
   requestGroupVote,
   sendGroupHeartbeat,
+  writeGroupKeyFile,
 } from '../../lib/group-client.mjs';
 import { fileMode, makeTempStateDir } from './helpers.mjs';
 import { postAs, readRoleFile, roleOf, startCluster, waitFor } from './group-cluster.mjs';
@@ -362,7 +365,26 @@ test('S3 quorum 分母 = 成员表全集：没有任何地址的成员也计入
   for (const id of ['peer-ghost-1', 'peer-ghost-2', 'peer-ghost-3']) a.server.group.removeMember(id);
   const ok = await postAs(a.baseUrl, b.peerId, { kind: 'chat', text: 'ghost-gone' });
   assert.equal(ok.status, 201, ok.text);
-  assert.equal((await lease(a)).quorumNeeded, 2);
+  // 移除成员会轮换群密钥（keyVersion+1）：旧钥必须被拒，新钥照常
+  const rotated = a.server.group.state({ includeKey: true });
+  assert.ok(rotated.keyVersion > 1, 'removeMember 必须轮换 keyVersion');
+  assert.notEqual(rotated.groupKey, cluster.groupKey, '轮换后 groupKey 必须变化');
+  await assert.rejects(
+    () => fetchGroupLease({ baseUrl: a.baseUrl, groupKey: cluster.groupKey, groupId: cluster.groupId, senderId: b.peerId }),
+    (error) => {
+      assert.equal(error.status, 401);
+      assert.equal(error.code, 'bad-signature');
+      return true;
+    },
+  );
+  const after = await fetchGroupLease({
+    baseUrl: a.baseUrl,
+    groupKey: rotated.groupKey,
+    groupId: cluster.groupId,
+    senderId: b.peerId,
+  });
+  assert.equal(after.quorumNeeded, 2);
+  assert.equal(after.keyVersion, rotated.keyVersion, 'lease 必须暴露 keyVersion');
 });
 
 test('S3 单节点自立为 leader 必败：N=2 且另一台不可达 → quorum-unavailable', async (t) => {
@@ -399,6 +421,47 @@ test('S3 N=3：两台可达能当选（2 ≥ 2），只剩一台不能（1 < 2
   assert.equal(lonely.needed, 2);
   assert.notEqual(roleOf(c).role, 'leader');
 });
+test('S3 成员表未同步时：选举/心跳自愈入表（真机 not-a-member 的回归）', async (t) => {
+  const cluster = await startCluster(t, { count: 3, heartbeatMs: 5_000, tickMs: 60_000 });
+  const [a, b, c] = cluster.nodes;
+  // 造「c 的成员表来自一份不完整的快照」：把 b 从 c 的 group-key.json 里删掉
+  const keyFile = readGroupKeyFile(c.dir);
+  delete keyFile.members[b.peerId];
+  writeGroupKeyFile(c.dir, keyFile);
+  const stale = readGroupKeyFile(c.dir);
+  assert.equal(Boolean(stale.members[b.peerId]), false, '前提：c 不认识 b');
+
+  // b 拉票：原来会 401 not-a-member（对端永远投不进来 → 群选不出 leader）
+  const vote = await requestGroupVote({
+    baseUrl: c.baseUrl,
+    ...groupArgs(cluster, b.peerId),
+    epoch: 3,
+    candidate: b.peerId,
+  });
+  assert.equal(vote.vote, true, JSON.stringify(vote));
+  assert.equal(vote.epoch, 3);
+  // 自愈：c 把 b 补回成员表（并落盘）
+  const healed = readGroupKeyFile(c.dir);
+  assert.ok(healed.members[b.peerId], 'c 必须把 b 补回成员表并落盘');
+  // 第二次直接投，不再走自愈分支
+  const again = await requestGroupVote({
+    baseUrl: c.baseUrl,
+    ...groupArgs(cluster, b.peerId),
+    epoch: 4,
+    candidate: b.peerId,
+  });
+  assert.equal(again.vote, true);
+
+  // 非领导权路径仍然严格：成员表没有的发送方打 pull 仍 401 not-a-member（不自愈）
+  await assert.rejects(
+    () => pullGroupMessages({ baseUrl: c.baseUrl, ...groupArgs(cluster, 'peer-not-in-group') }),
+    (error) => {
+      assert.equal(error.status, 401);
+      assert.equal(error.code, 'not-a-member');
+      return true;
+    },
+  );
+});
 // 说明：post 走 per-peer 签名，这里顺带确认 leader 真的能收（详情见 group-commit.test.mjs）
 test('S3 leader 就绪：hub leader 的 post 通道可用（202/201 由 commit 测试覆盖）', async (t) => {
   const cluster = await startCluster(t, { count: 2, quorum: 'none' });

package/host/test/group-key-rotation.test.mjs

@@ -0,0 +1,219 @@
+/**
+ * v0.7.3 安全硬化 · 移除成员即轮换群密钥 + 成员侧换钥自愈（契约补充）。
+ *
+ * 两个洞的回归：
+ *  ① hub 收到「不在成员表但握着有效 groupKey」的心跳时必须拒绝，且**不得**把它写回成员表
+ *  ② removeMember 必须轮换 keyVersion；被移除者的旧钥一律 401 bad-signature
+ * 另外两条保护：③成员侧换钥后自动重试一次 ④成员侧（副本）自愈仍然有效
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { setTimeout as sleep } from 'node:timers/promises';
+import {
+  fetchGroupLease,
+  readGroupKeyFile,
+  requestGroupVote,
+  sendGroupHeartbeat,
+  writeGroupKeyFile,
+} from '../../lib/group-client.mjs';
+import { postAs, roleOf, startCluster, waitFor } from './group-cluster.mjs';
+
+const groupArgs = (cluster, senderId) => ({
+  groupKey: cluster.groupKey,
+  groupId: cluster.groupId,
+  senderId,
+});
+
+test('① hub 永不自愈：持有有效 groupKey 但不在成员表 → 401 not-a-member，且不写回成员表', async (t) => {
+  const cluster = await startCluster(t, { count: 2, heartbeatMs: 5_000, tickMs: 60_000 });
+  const [hub] = cluster.nodes;
+  const before = Object.keys(hub.server.group.state().members).sort();
+  const outsider = 'peer-not-invited-9f3a';
+
+  const heartbeat = await assert.rejects(
+    () => sendGroupHeartbeat({
+      baseUrl: hub.baseUrl,
+      ...groupArgs(cluster, outsider),
+      epoch: 1,
+      leaderPeerId: outsider,
+    }),
+    (error) => {
+      assert.equal(error.status, 401);
+      assert.equal(error.code, 'not-a-member');
+      return true;
+    },
+  );
+  assert.equal(heartbeat, undefined);
+  // 投票端点同样是领导权协议，但 hub 侧也不得自愈
+  await assert.rejects(
+    () => requestGroupVote({
+      baseUrl: hub.baseUrl,
+      ...groupArgs(cluster, outsider),
+      epoch: 2,
+      candidate: outsider,
+    }),
+    (error) => {
+      assert.equal(error.status, 401);
+      assert.equal(error.code, 'not-a-member');
+      return true;
+    },
+  );
+  assert.deepEqual(Object.keys(hub.server.group.state().members).sort(), before, 'group.json 的成员表不得被自愈写入');
+  assert.equal(readGroupKeyFile(hub.dir), null, 'hub 不写 group-key.json');
+});
+
+test('② 移除成员即轮换密钥：keyVersion+1，被移除者用旧钥打 election/leader → 401 bad-signature', async (t) => {
+  const lines = [];
+  const cluster = await startCluster(t, { count: 3, heartbeatMs: 5_000, tickMs: 60_000, logger: (line) => lines.push(String(line)) });
+  const [hub, , removed] = cluster.nodes;
+  const before = hub.server.group.state({ includeKey: true });
+  assert.equal(before.keyVersion, 1);
+
+  assert.equal(hub.server.group.removeMember(removed.peerId), true);
+  const after = hub.server.group.state({ includeKey: true });
+  assert.equal(after.keyVersion, before.keyVersion + 1, '移除成员必须抬 keyVersion');
+  assert.notEqual(after.groupKey, before.groupKey, '必须换一把新 groupKey');
+  assert.equal(after.members[removed.peerId], undefined, '成员表里不能再有它');
+  // 日志：一行摘要，且绝不打印密钥本身
+  const rotatedLine = lines.find((line) => line.startsWith('[group] key rotated '));
+  assert.ok(rotatedLine, '必须有 [group] key rotated 日志');
+  assert.match(rotatedLine, new RegExp(`keyVersion=${after.keyVersion} reason=member-removed`));
+  assert.equal(rotatedLine.includes(after.groupKey), false, '日志不得打印密钥');
+  assert.equal(rotatedLine.includes(before.groupKey), false, '日志不得打印旧密钥');
+  if (process.platform !== 'win32') {
+    const mode = (await import('node:fs')).statSync(hub.server.group.state ? hub.dir + '/group.json' : '').mode & 0o777;
+    assert.equal(mode, 0o600, 'group.json 仍必须 0600');
+  }
+
+  // 被移除者仍握着旧钥（它的 group-key.json 没变）→ 一律拒绝，且**不是** not-a-member。
+  // 有 body 的请求（心跳/投票）在信封层就先炸：400 bad-encryption；
+  // 无 body 的请求（GET /v1/group/lease）能走到验签：401 bad-signature。两者都证明旧钥已失效。
+  const rejectedWithOldKey = (error) => {
+    assert.equal(error.status === 401 || error.status === 400, true, '状态必须是 401/400，实际 ' + error.status);
+    assert.equal(['bad-signature', 'bad-encryption'].includes(String(error.code)), true, '错误码 ' + error.code);
+    assert.notEqual(String(error.code), 'not-a-member', '不能只是 not-a-member —— 说明密钥没轮换');
+    return true;
+  };
+  await assert.rejects(
+    () => sendGroupHeartbeat({
+      baseUrl: hub.baseUrl,
+      ...groupArgs(cluster, removed.peerId),
+      epoch: 2,
+      leaderPeerId: removed.peerId,
+    }),
+    rejectedWithOldKey,
+  );
+  await assert.rejects(
+    () => requestGroupVote({
+      baseUrl: hub.baseUrl,
+      ...groupArgs(cluster, removed.peerId),
+      epoch: 2,
+      candidate: removed.peerId,
+    }),
+    rejectedWithOldKey,
+  );
+  // 无 body 的那条给出精确的 401 bad-signature（验签先于成员表检查）
+  await assert.rejects(
+    () => fetchGroupLease({
+      baseUrl: hub.baseUrl,
+      ...groupArgs(cluster, removed.peerId),
+    }),
+    (error) => {
+      assert.equal(error.status, 401);
+      assert.equal(error.code, 'bad-signature');
+      return true;
+    },
+  );
+  // hub 侧不再把它算进多数派分母
+  const lease = await fetchGroupLease({
+    baseUrl: hub.baseUrl,
+    groupKey: after.groupKey,
+    groupId: cluster.groupId,
+    senderId: cluster.nodes[1].peerId,
+  });
+  assert.equal(lease.memberCount, 2);
+  assert.equal(lease.keyVersion, after.keyVersion);
+});
+
+test('②b 被移除的成员不能靠自助 join 回来（同一个洞的另一扇门）', async (t) => {
+  const cluster = await startCluster(t, { count: 2, heartbeatMs: 5_000, tickMs: 60_000 });
+  const [hub, member] = cluster.nodes;
+  assert.equal(hub.server.group.state().members[member.peerId] !== undefined, true);
+  hub.server.group.removeMember(member.peerId);
+  // 成员用 per-peer 签名打 /v1/group/join（autoJoin 是开的）——原来会被加回成员表
+  const res = await postAs(hub.baseUrl, member.peerId, { name: 'sneak-back' }, { path: '/v1/group/join' });
+  assert.equal(res.status, 403, res.text);
+  assert.equal(res.json.error, 'not-a-member');
+  assert.equal(hub.server.group.state().members[member.peerId], undefined, '成员表不得被 join 写回');
+  // 运维显式重新邀请（addMember）会解除 blocked，之后 join 也恢复正常语义
+  hub.server.group.addMember(member.peerId, 'node-b');
+  assert.equal(hub.server.group.state().members[member.peerId] !== undefined, true);
+});
+test('③ 成员换钥：hub 轮换后首次请求被拒 → 自动 refetch state → 重试一次成功', async (t) => {
+  const cluster = await startCluster(t, { count: 2, heartbeatMs: 5_000, tickMs: 60_000 });
+  const [hub, member] = cluster.nodes;
+  // 让 hub 轮换密钥，但 member 仍在成员表里（模拟「踢掉第三台」后的换钥）
+  hub.server.group.addMember('peer-ghost-1', 'ghost');
+  hub.server.group.removeMember('peer-ghost-1');
+  const rotated = hub.server.group.state({ includeKey: true });
+  assert.ok(rotated.keyVersion > 1);
+  assert.notEqual(readGroupKeyFile(member.dir)?.key, rotated.groupKey, '前提：成员手里还是旧钥');
+  assert.equal(hub.server.group.members().some((entry) => entry.peerId === member.peerId), true);
+
+  // 成员的下一次出站群请求（拉补差）会先撞 401 bad-signature → 换钥 → 重试一次
+  let out = await member.server.group.pull();
+  for (let attempt = 0; attempt < 40 && out?.reason === 'skipped'; attempt += 1) {
+    await sleep(25);
+    out = await member.server.group.pull();
+  }
+  assert.equal(out.ok, true, JSON.stringify(out));
+  const refreshed = readGroupKeyFile(member.dir);
+  assert.equal(refreshed.key, rotated.groupKey, '成员必须把新钥落进 group-key.json');
+  assert.equal(roleOf(member).keyVersion, rotated.keyVersion, 'role() 必须暴露新 keyVersion');
+  // 只重试一次：再拉一次应当直接成功
+  const second = await member.server.group.pull();
+  assert.equal(second.ok, true);
+});
+
+test('④ 成员侧（副本）自愈仍然有效：表未同步但未移除的成员，election 仍被接受并补表', async (t) => {
+  const cluster = await startCluster(t, { count: 3, heartbeatMs: 5_000, tickMs: 60_000 });
+  const [, b, c] = cluster.nodes;
+  // 造「c 的成员表来自不完整快照」：把 b 从 c 的 group-key.json 里删掉
+  const keyFile = readGroupKeyFile(c.dir);
+  delete keyFile.members[b.peerId];
+  writeGroupKeyFile(c.dir, keyFile);
+  assert.equal(Boolean(readGroupKeyFile(c.dir).members[b.peerId]), false);
+
+  const vote = await requestGroupVote({
+    baseUrl: c.baseUrl,
+    ...groupArgs(cluster, b.peerId),
+    epoch: 3,
+    candidate: b.peerId,
+  });
+  assert.equal(vote.vote, true, JSON.stringify(vote));
+  assert.ok(readGroupKeyFile(c.dir).members[b.peerId], '成员侧必须把对端补回成员表');
+});
+
+test('⑥ 轮换后 epoch 不回退：重启（新的 server 实例读同一份状态）时角色 epoch 不小于 keyVersion', async (t) => {
+  const cluster = await startCluster(t, { count: 2, heartbeatMs: 5_000, tickMs: 60_000 });
+  const [hub] = cluster.nodes;
+  hub.server.group.addMember('peer-ghost-2', 'ghost');
+  hub.server.group.removeMember('peer-ghost-2');
+  const keyVersion = hub.server.group.state().keyVersion;
+  assert.ok(keyVersion >= 2);
+  // 同一份 stateDir 再起一个实例（等价于重启）：角色 epoch 必须 ≥ keyVersion
+  const { createPeerServer } = await import('../server.mjs');
+  const restarted = createPeerServer({
+    listenHost: '127.0.0.1',
+    stateDir: hub.dir,
+    requireEncryption: false,
+    group: { enabled: true, name: 's3', quorum: 'none', heartbeatMs: 5_000 },
+    groupElection: { heartbeatMs: 5_000, tickMs: 60_000, peerTimeoutMs: 200 },
+  });
+  t.after(async () => { await restarted.close(); });
+  const info = await restarted.listen(0, '127.0.0.1');
+  assert.equal(info.port > 0, true);
+  const role = restarted.group.role();
+  assert.ok(role.epoch >= keyVersion, '角色 epoch 不得小于 keyVersion，实际 ' + role.epoch + ' vs ' + keyVersion);
+});
+

package/host/test/group-takeover.test.mjs

@@ -0,0 +1,122 @@
+/**
+ * v0.7.0 S3 补充 · 受限的启动竞选（priority-takeover）。
+ *
+ * 契约 §4 是「epoch 高者胜，同 epoch 才比 priority」——优先级不能跨 epoch 夺权，
+ * 于是优先节点重启期间被别人抢到更高 epoch 后会永久当 follower。这里给它一次有边界的重试权：
+ * 配置上没有 group.hub 的本机，启动稳定 2×heartbeatMs 后、优先级**严格更高**时尝试一次。
+ *
+ * 覆盖：①一次成功接管（epoch+1，原 leader 降级）②priority 相等不触发
+ *      ③接管失败后推进 30s 也不重试 ④配了 group.hub 的成员不触发
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { roleOf, startCluster, waitFor } from './group-cluster.mjs';
+
+const takeoverOf = (node) => node.server.group.takeover();
+
+const electionLines = (lines, kind) => lines
+  .filter((line) => line.includes('[group] election ' + kind) && line.includes('reason=priority-takeover'));
+
+test('S3 启动接管：高优先节点一次接管成功（epoch+1），原 leader 降级', async (t) => {
+  const lines = [];
+  const cluster = await startCluster(t, {
+    count: 2,
+    // 两台都是 hub 角色（配置上没有 group.hub），才有接管资格
+    hubRoles: [0, 1],
+    // 低优先（10）先当 leader；高优先（0）以 follower 起步
+    priorities: [10, 0],
+    followerOf: { 1: 0 },
+    logger: (line) => lines.push(String(line)),
+  });
+  const [low, high] = cluster.nodes;
+  assert.equal(roleOf(low).role, 'leader');
+  assert.equal(roleOf(high).role, 'follower');
+  assert.equal(roleOf(high).leaderPeerId, low.peerId);
+  assert.equal(takeoverOf(high).attempts, 0, '刚开始还不该动手');
+
+  await waitFor(() => takeoverOf(high).attempts === 1, { timeoutMs: 5_000 });
+  await waitFor(() => roleOf(high).role === 'leader', { timeoutMs: 5_000 });
+  await waitFor(() => roleOf(low).leaderPeerId === high.peerId, { timeoutMs: 5_000 });
+
+  assert.equal(roleOf(high).epoch, 2, '接管必须抬 epoch');
+  assert.equal(roleOf(low).role, 'follower');
+  assert.equal(roleOf(low).epoch, 2);
+  assert.equal(takeoverOf(high).attempts, 1);
+  assert.equal(takeoverOf(high).attempted, true);
+
+  const text = lines.join('\n');
+  assert.match(text, /\[group\] takeover attempt epoch=2 priority=0 leaderPriority=10/);
+  assert.equal(electionLines(lines, 'won').length, 1, '一次成功接管要留一行带票数的日志');
+  assert.match(text, /\[group\] takeover won epoch=2 votes=2\/2/);
+
+  // 稳定后不再重试：推进到远超过稳定期，attempts 仍然是 1
+  await sleep(400);
+  assert.equal(takeoverOf(high).attempts, 1);
+  assert.equal(electionLines(lines, 'won').length, 1);
+});
+
+test('S3 启动接管：priority 相等时一律不触发', async (t) => {
+  const cluster = await startCluster(t, {
+    count: 2,
+    hubRoles: [0, 1],
+    priorities: [0, 0],
+    followerOf: { 1: 0 },
+  });
+  const [low, high] = cluster.nodes;
+  // 等过稳定期（2×heartbeat=240ms）再多等几轮 tick
+  await sleep(700);
+  assert.equal(takeoverOf(high).attempts, 0, '优先级相等不得夺权');
+  assert.equal(takeoverOf(high).attempted, false);
+  assert.equal(roleOf(high).role, 'follower');
+  assert.equal(roleOf(high).leaderPeerId, low.peerId);
+  assert.equal(roleOf(low).role, 'leader');
+});
+
+test('S3 启动接管：失败一次后不再重试（假时钟推进 30s，接管仍只有 1 次）', async (t) => {
+  let fake = Date.now();
+  const clock = () => fake;
+  const lines = [];
+  const cluster = await startCluster(t, {
+    count: 2,
+    hubRoles: [0, 1],
+    priorities: [10, 0],
+    followerOf: { 1: 0 },
+    // 心跳放慢，好让「稳定期」在假时钟里可控（租约 = 3×400 = 1200ms）
+    heartbeatMs: 400,
+    tickMs: 25,
+    now: clock,
+    logger: (line) => lines.push(String(line)),
+  });
+  const [low, high] = cluster.nodes;
+  // 让 low 的心跳把「leader 优先级=10」教给 high（假时钟下真实时间照样走几轮）
+  await sleep(600);
+  assert.equal(takeoverOf(high).attempts, 0, '还没到稳定期（2×400=800ms）');
+
+  // 把 leader 打死，再跨过稳定期：这一枪注定落空
+  await low.server.close();
+  fake += 900;
+  await waitFor(() => takeoverOf(high).attempts === 1, { timeoutMs: 3_000 });
+  assert.equal(roleOf(high).role, 'follower', '失败后不得成为 leader');
+  assert.equal(electionLines(lines, 'lost').length, 1);
+  assert.match(lines.join('\n'), /\[group\] takeover lost epoch=2 votes=1\/2/);
+
+  // 推进 30s：普通租约过期选举可以重试，但**接管**必须一次就停
+  fake += 30_000;
+  await sleep(400);
+  assert.equal(takeoverOf(high).attempts, 1, '接管每进程只允许一次');
+  assert.equal(electionLines(lines, 'lost').length, 1);
+  assert.equal(electionLines(lines, 'won').length, 0);
+});
+
+test('S3 启动接管：配了 group.hub 的成员节点不触发（即使优先级更高）', async (t) => {
+  const cluster = await startCluster(t, { count: 2, priorities: [10, 0] });
+  const [low, member] = cluster.nodes;
+  assert.equal(low.server.group.isHub, true);
+  assert.equal(member.server.group.isHub, false);
+  await sleep(700);
+  assert.equal(takeoverOf(member).attempts, 0, '成员节点（配置了 group.hub）不得夺权');
+  assert.equal(roleOf(member).role, 'follower');
+  assert.equal(roleOf(low).role, 'leader');
+});
+

package/host/test/group.test.mjs

@@ -278,7 +278,8 @@ test('§4 hub 首次初始化：group.json 0600、hub 自己是成员、管理
   const raw = JSON.parse(fs.readFileSync(groupFile, 'utf8'));
   // S3 §5：group.json 追加 pending（未提交区，与 messages 分开存）
   assert.deepEqual(Object.keys(raw).sort(), [
-    'createdAt', 'groupId', 'key', 'keyVersion', 'lastSeq', 'members', 'messages', 'name', 'pending',
+    // blocked：被移除的成员（自助 join 不得把 ta 加回来）
+    'blocked', 'createdAt', 'groupId', 'key', 'keyVersion', 'lastSeq', 'members', 'messages', 'name', 'pending',
   ]);
   assert.equal(Buffer.from(raw.key, 'base64url').length, 32);
   assert.equal(raw.name, 'team');

package/lib/admin-group.test.mjs

@@ -863,6 +863,95 @@ test('S3 · leader.epoch 以角色门面为准：角色 3 / 群元数据 1 → 3
   assert.equal(fallback.json.leader.epoch, 1, '没有角色门面时回退到群元数据的 epoch');
 });
 
+test('S3 · 成员侧 leader.peerId 同样以角色门面为准（配置的 group.hub 只是引导入口）', async () => {
+  // 动态 hub 的语义：leader 可能是任何成员，group.hub 只是引导入口，不代表当前 leader。
+  const members = [
+    { peerId: 'peer-hub', name: 'hub-box', online: true, lastSeen: null, joinedAt: 1, baseUrl: 'http://192.168.5.51:7788', lastSeq: 8 },
+    { peerId: 'peer-other', name: 'dsh-desktop', online: true, lastSeen: null, joinedAt: 2, baseUrl: 'http://192.168.5.20:7788', lastSeq: 8 },
+    { peerId: 'member-inst', name: 'me', online: true, lastSeen: null, joinedAt: 3, baseUrl: '', lastSeq: null },
+  ];
+  const leadsAs = (leaderPeerId) => stubAdmin({
+    group: { enabled: true, hub: 'hub-box' },
+    api: apiWith({ isHub: false, lastSeq: 8, members }),
+    peers: HUB_PEERS,
+    facade: { enabled: false, isHub: false, role: () => ({ role: 'follower', epoch: 3, leaderPeerId, leaseUntil: Date.now() + 9000 }) },
+  });
+
+  const out = await hit(leadsAs('peer-other').admin, 'GET', '/api/lan-peers/group');
+  assert.equal(out.json.selfRole, 'member');
+  assert.equal(out.json.role, 'follower');
+  assert.equal(out.json.leader.peerId, 'peer-other', '门面的 leaderPeerId 压过配置的 group.hub');
+  assert.notEqual(out.json.leader.peerId, 'peer-hub');
+  assert.equal(out.json.leader.name, 'dsh-desktop', '名字从群成员表查');
+  assert.equal(out.json.leader.epoch, 3);
+
+  // 本机自己当 leader：成员表里有名字就用表里的，没有就用本机名（不是 UUID）
+  const named = await hit(leadsAs('member-inst').admin, 'GET', '/api/lan-peers/group');
+  assert.equal(named.json.leader.peerId, 'member-inst');
+  assert.equal(named.json.leader.name, 'me');
+  // 成员表里没有本机那条（还没进群状态）：本机自己当 leader 时用自己的名字，不是 UUID
+  const unnamed = await hit(stubAdmin({
+    group: { enabled: true, hub: 'hub-box' },
+    api: apiWith({ isHub: false, lastSeq: 8 }),
+    peers: HUB_PEERS,
+    facade: { enabled: false, isHub: false, role: () => ({ role: 'leader', epoch: 3, leaderPeerId: 'inst-self' }) },
+  }).admin, 'GET', '/api/lan-peers/group');
+  assert.equal(unnamed.json.leader.peerId, 'inst-self', '本机（store.instanceId）当选');
+  assert.equal(unnamed.json.leader.name, 'self', '查不到时本机用自己的名字');
+
+  // 门面缺席 / leaderPeerId 为空：回退到配置的 group.hub（旧行为不破）
+  const legacy = await hit(stubAdmin({
+    group: { enabled: true, hub: 'hub-box' },
+    api: apiWith({ isHub: false, lastSeq: 8, members }),
+    peers: HUB_PEERS,
+  }).admin, 'GET', '/api/lan-peers/group');
+  assert.equal(legacy.json.leader.peerId, 'peer-hub', '没有角色门面时仍认配置的 hub');
+  assert.equal(legacy.json.leader.name, 'hub-box');
+
+  const emptyLeader = await hit(leadsAs('').admin, 'GET', '/api/lan-peers/group');
+  assert.equal(emptyLeader.json.leader.peerId, 'peer-hub', 'leaderPeerId 为空字符串等于没接线');
+});
+
+test('S3 · hub 且选举为 follower：leader.peerId 是真 leader（不是本机），selfRole 仍是 hub', async () => {
+  // 真机（0.7.2 NAS）：配置上是 hub，但选举输给了 dsh-desktop。
+  const members = [
+    { peerId: 'inst-self', name: 'fn-302', online: true, lastSeen: null, joinedAt: 1, baseUrl: 'http://192.168.5.51:7788', lastSeq: 8 },
+    { peerId: 'peer-desktop', name: 'dsh-desktop', online: true, lastSeen: null, joinedAt: 2, baseUrl: 'http://192.168.5.20:7788', lastSeq: 8 },
+  ];
+  const state = () => ({
+    groupId: 'g-1', name: 'default', epoch: 4, members, messages: MESSAGES, lastSeq: 8,
+  });
+  const followerHub = await hit(stubAdmin({
+    group: { enabled: true, hub: '' },
+    api: { ...makeApi(), isHub: true, state },
+    facade: { enabled: true, isHub: true, role: () => ({ role: 'follower', epoch: 4, leaderPeerId: 'peer-desktop', leaseUntil: Date.now() + 9000 }) },
+  }).admin, 'GET', '/api/lan-peers/group');
+
+  assert.equal(followerHub.json.selfRole, 'hub', 'selfRole 是「配置上的 hub」，与选举角色不是一个概念');
+  assert.equal(followerHub.json.role, 'follower', '选举角色如实透出');
+  assert.equal(followerHub.json.leader.peerId, 'peer-desktop', 'leader 必须是选举赢家，不能写死本机');
+  assert.notEqual(followerHub.json.leader.peerId, 'inst-self');
+  assert.equal(followerHub.json.leader.name, 'dsh-desktop', '名字从成员表里查');
+  assert.equal(followerHub.json.leader.epoch, 4);
+
+  // 成员表里查不到那个 peerId：名字退回 peerId（不编名字，也不回退本机）
+  const ghost = await hit(stubAdmin({
+    group: { enabled: true, hub: '' },
+    api: { ...makeApi(), isHub: true, state },
+    facade: { enabled: true, isHub: true, role: () => ({ role: 'follower', epoch: 4, leaderPeerId: 'peer-ghost' }) },
+  }).admin, 'GET', '/api/lan-peers/group');
+  assert.equal(ghost.json.leader.peerId, 'peer-ghost');
+  assert.equal(ghost.json.leader.name, 'peer-ghost', '查不到名字就用 peerId');
+
+  // 角色门面缺席（老 host / 未接线）：回退到「hub 就是本机」的旧行为
+  const legacy = await hit(stubAdmin({
+    group: { enabled: true, hub: '' },
+    api: { ...makeApi(), isHub: true, state },
+  }).admin, 'GET', '/api/lan-peers/group');
+  assert.equal(legacy.json.leader.peerId, 'inst-self', '没有角色门面时回退本机');
+  assert.equal(legacy.json.leader.name, 'self');
+});
+
 test('S3 · 群状态快照里的角色字段是第二来源（门面缺席时也能显示）', async () => {
   const leaseUntil = Date.now() + 9000;
   const api = apiWith({ isHub: true, lastSeq: 8 });

package/lib/admin.mjs

@@ -339,15 +339,39 @@ export function createAdmin({
     return typeof fromConfig === 'string' ? fromConfig : '';
   });
 
+  /** 群状态成员表里的名字（找不到就是空串）：给「真 leader 不是本机」时用。 */
+  const memberNameOf = (snapshot, peerId) => {
+    if (peerId === '') return '';
+    const list = Array.isArray(snapshot?.members) ? snapshot.members : [];
+    const found = list.find((member) => String(member?.peerId ?? '') === peerId);
+    return String(found?.name ?? '');
+  };
+
   /**
-   * S1：leader —— hub 侧就是本机，成员侧就是 group.hub 指向的那个 peer。
+   * S1：leader —— 没有选举信息时，hub 侧就是本机，成员侧就是 group.hub 指向的那个 peer。
    *
-   * S3：epoch 优先取角色门面的 `epoch`（选举世代），只有角色门面缺席时才回退到
-   * 群元数据的 epoch。两者含义不同（群元数据那份是 group.json 的 keyVersion 世代），
-   * 真机上出现过「leader.epoch=1 而状态行 epoch=3」的显示打架，这里统一到选举世代。
+   * S3：角色门面说了算的两个字段：
+   *   - `epoch` 取选举世代（群元数据那份是 group.json 的 keyVersion 世代，真机上出现
+   *     过「leader.epoch=1 而状态行 epoch=3」的打架）；
+   *   - `leaderPeerId` 取真 leader（配置上是 hub 的机器可能输掉选举，那时 selfRole 仍是
+   *     hub、role 是 follower，leader 必须是赢家，而不是本机）。
+   * 门面缺席（老 host / 未接线）时两者都回退到 S1 的旧口径，行为不变。
    */
   const leaderOf = (snapshot, resolved, face = null) => {
     const epoch = asSeqOrNull(face?.epoch) ?? asSeqOrNull(snapshot?.epoch);
+    const declared = face && typeof face === 'object' ? face.leaderPeerId : undefined;
+    const declaredId = declared == null ? '' : String(declared);
+    if (declaredId !== '') {
+      const fromMembers = memberNameOf(snapshot, declaredId);
+      // 成员表里查不到时：若声明的 leader 就是本机，仍用本机名称（别把 peerId 当名字显示）；
+      // 是别的机器就退到 peerId（面板会原样显示，不会编名字）。
+      const name = fromMembers !== ''
+        ? fromMembers
+        : (declaredId === String(store?.instanceId ?? '')
+          ? String(typeof nameOf === 'function' ? nameOf() : '')
+          : declaredId);
+      return { peerId: declaredId, name, epoch };
+    }
     if (resolved.isHub === true) {
       return {
         peerId: String(store?.instanceId ?? ''),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-lan-peers",
-  "version": "0.7.2",
+  "version": "0.7.3",
   "description": "局域网 DSH 协同：一次性配对互认、HMAC 签名 + AES-256-GCM 加密、agent 互派任务",
   "type": "module",
   "main": "lib/index.js",