dsh-lan-peers 0.7.2 → 0.7.4

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.4';
 
 /** §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;
   }
@@ -1074,10 +1095,16 @@ export class GroupStore {
     return name;
   }
 
-  /** 追加一条消息：seq = ++lastSeq（消息被删也不回收号） */
+  /**
+   * 追加一条消息（**单阶段写**：quorum:none、以及管理接口/面板的直写路径）。
+   * 取号必须避开 pending 已预留的空号：两阶段提交的提案先占住 lastSeq+1，
+   * 此时若再来一条直写也取 lastSeq+1，两条消息就会共用同一个 seq ——
+   * 客户端按 seq 去重，后一条会被静默丢弃。
+   */
   append({ peerId, name, kind, text = '', meta = {} }) {
     const data = this.#load();
-    const seq = Number(data.lastSeq) + 1;
+    const reserved = data.pending.reduce((max, entry) => Math.max(max, Number(entry?.seq) || 0), 0);
+    const seq = Math.max(Number(data.lastSeq) || 0, reserved) + 1;
     data.lastSeq = seq;
     const message = {
       seq,
@@ -1809,7 +1836,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 +1851,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 +1865,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 +2530,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 +2716,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 +2817,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 +2984,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 +3026,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;
   }
 
@@ -2946,11 +3092,13 @@ export function createPeerServer(overrides = {}) {
     const id = String(peerId ?? '');
     if (id === '') return '';
     if (id === store.instanceId) return localAdvertiseBaseUrl();
-    const learned = String(peerBaseUrls.get(id) ?? '').trim().replace(/\/+$/, '');
-    if (learned !== '') return learned;
+    // 群成员表优先：它同样是成员自报的地址（hub 写 group.json / 成员写 group-key.json），
+    // 但它是**持久化且运维可见可覆盖**的那一份；学到的缓存只做兜底（两者来源相同，顺序不影响线上）。
     const fromGroup = String(localGroupContext()?.members?.[id]?.baseUrl ?? '')
       .trim().replace(/\/+$/, '');
     if (fromGroup !== '') return fromGroup;
+    const learned = String(peerBaseUrls.get(id) ?? '').trim().replace(/\/+$/, '');
+    if (learned !== '') return learned;
     const recorded = String(groupStore ? groupStore.state().members[id]?.baseUrl ?? '' : '')
       .trim().replace(/\/+$/, '');
     if (recorded !== '') return recorded;
@@ -3152,10 +3300,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 +3356,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 +3419,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 +3488,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 +3639,8 @@ export function createPeerServer(overrides = {}) {
         // 分母与门槛：成员表全集（含没有地址的成员），地址只影响投递
         memberCount: quorumMembers().length,
         quorumNeeded: quorumNeeded(),
+        // 群密钥世代（只给世代，不给密钥）：轮换后可从这里看出来
+        keyVersion: groupKeyVersion(),
         degraded: isDegraded(),
         advertiseBaseUrl: localAdvertiseBaseUrl(),
       },
@@ -3694,7 +3898,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 +3946,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 +4109,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 +4208,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 +4219,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 +4311,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 +4382,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 +4397,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 +4427,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 +4452,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 +4485,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 +4620,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 +4653,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 +4683,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 +4696,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']),