dsh-lan-peers 0.7.0 → 0.7.1

package/HANDOVER.md

@@ -11,7 +11,7 @@
 
 | 位置 | 形态 | 版本 |
 |---|---|---|
-| npm | 公开包 `dsh-lan-peers`，`latest` | **0.4.0**（2026-10-27 发布，34 文件，shasum `204999eb…`）|
+| npm | 公开包 `dsh-lan-peers`，`latest` | **0.7.0**（2026-10-27 发布；51 文件 / 231.7 kB；含群聊 Phase1+2 与 S1/S2/S3）|
 | NAS `192.168.5.51`（fn-302，Debian 12） | `link:` 安装进 `/home/ai/.dsh/profiles/web`，systemd `dsh-web` 托管 | **0.4.2**（2026-10-27 20:35 部署；含 unpair + admin 审计日志）|
 | Windows 桌面版（Electron） | `link:D:/DS-Harness/lan-peers`（见 §7）| **0.4.0**（2026-10-27 重启生效；面板与 SSE 派单已实测）|
 
@@ -352,6 +352,8 @@ node interop/run-interop.mjs    # A 旧→新明文+弃用告警 / B 新→旧
 
 **发布记录**
 
+- **0.7.0 → npm（2026-10-27）**：`npm publish` 成功（granular token，无 OTP）；51 文件 / 231.7 kB；注册表传播比上次慢（约 2 分钟后 `latest` 才变 0.7.0，期间 `npm view` 仍报 0.4.0 —— **拿不准时先查 `dist-tags` 再重试，别急着重发**）。临时 profile 真装验证：`installed 0.7.0`、`bin.dsh-lan-peers=client/cli.mjs`、`lib/group-client.mjs` 在包内、`interop/` 未打包（符合 `files` 白名单）。
+
 - 0.4.0 · 2026-10-27 · `npm publish` 成功（granular token，无 OTP）·34 文件 / 87.9 kB · shasum `204999ebe7fa3190fd2603c81ab4d96767e52538`；NAS 与 npm 均已 0.4.0，桌面待重启。
 - **0.4.1 → NAS（2026-10-27 20:27）**：未发 npm，只部署 NAS。备份 `/tmp/lan-peers-backup-0.4.0-20261027T122711Z.tgz`（88660B，sha256 `5185a9cb…`）；包内 45 条目、双端 sha256 一致、覆盖式解包；`dsh-web` active；health = `0.4.1` + capability 含 `unpair`；真实派单走 SSE 成功（elapsed 1227ms）。
 - **0.4.2 → NAS（2026-10-27 20:35）**：只部署 NAS，未发 npm。备份 `/tmp/lan-peers-backup-0.4.1-20261027T123459Z.tgz`（116433B，49 条目）；包 46 条目、双端 sha256 `675ac1d9…` 一致、覆盖解包；health = `0.4.2` + `unpair`；`[admin] pairing code issued ttl=600s` 实测出现且**日志无 6 位码**（正则命中 0）；真实派单 reply「二次部署」；NAS `peers` 1→1 不变。

package/client/cli-group.test.mjs

@@ -43,7 +43,9 @@ async function startHub(t, overrides = {}) {
   const server = createPeerServer({
     listenHost: '127.0.0.1',
     stateDir,
-    group: { enabled: true, autoJoin: true },
+    // S3：majority 现在真的走 propose/commit（假成员没有投票端点会 503）；
+    // 这个文件测的是 v0.5 的 CLI 行为，固定 quorum:none = 写本地即提交。
+    group: { enabled: true, autoJoin: true, quorum: 'none' },
     ...overrides,
   });
   const info = await server.listen(0, '127.0.0.1');
@@ -161,7 +163,7 @@ test('group tail 跟随事件流并逐条打印（期间别人发的消息也收
 });
 
 test('group join 在 hub 未开 autoJoin 时 exit 2 并说明原因', async (t) => {
-  const hub = await startHub(t, { group: { enabled: true, autoJoin: false } });
+  const hub = await startHub(t, { group: { enabled: true, autoJoin: false, quorum: 'none' } });
   const dir = memberStateDir(t, { baseUrl: hub.baseUrl, hubInstanceId: hub.server.store.instanceId });
 
   const out = await runAsync(['group', 'join', '--peer', 'hub', '--state-dir', dir]);

package/client/cli.mjs

@@ -698,7 +698,8 @@ async function cmdGroupClaim(dir, args) {
   }
   process.stderr.write(
     '接管未成功: ' + (reply?.reason || 'vote-refused')
-      + ' 票数不足（quorum=' + (reply?.needed ?? '?') + '）或本机不在群内\n',
+      + ' 票数=' + (reply?.votes ?? '?') + '/' + (reply?.needed ?? '?')
+      + '（成员表 ' + (reply?.memberCount ?? '?') + ' 人；多数派分母是成员表全集，不是可达成员数）\n',
   );
   process.exitCode = 2;
 }

package/host/server.mjs

@@ -96,7 +96,7 @@ import { parseArgs } from 'node:util';
 // ---------------------------------------------------------------------------
 
 /** 插件版本，用于 /v1/health.version */
-export const PLUGIN_VERSION = '0.7.0';
+export const PLUGIN_VERSION = '0.7.1';
 
 /** §4.1 允许的时钟偏移 */
 export const CLOCK_SKEW_MS = 60_000;
@@ -2938,13 +2938,19 @@ export function createPeerServer(overrides = {}) {
     writeGroupKeyFile(config.stateDir, { ...existing, members });
   }
 
-  /** 对端可达地址：学到的 > hub 群状态里记的 > peers.json 配对时的地址 */
+  /**
+   * 对端可达地址：学到的 > 群成员表（group.json / group-key.json，读盘即最新）> peers.json。
+   * 群成员表必须排在 peers.json 前面：成员节点被 bootstrap 之前，peers.json 里可能是旧地址。
+   */
   function baseUrlOf(peerId) {
     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;
+    const fromGroup = String(localGroupContext()?.members?.[id]?.baseUrl ?? '')
+      .trim().replace(/\/+$/, '');
+    if (fromGroup !== '') return fromGroup;
     const recorded = String(groupStore ? groupStore.state().members[id]?.baseUrl ?? '' : '')
       .trim().replace(/\/+$/, '');
     if (recorded !== '') return recorded;
@@ -2971,21 +2977,20 @@ export function createPeerServer(overrides = {}) {
   }
 
   /**
-   * 承诺集合（决定 quorum 与 propose 目标）：自己 + 在网络上自报过地址的成员。
-   * 依据：契约 §5 的 ack 只能来自**能投递到**的成员；从未在网络上出现过的成员
-   * 既收不到提案也不可能 ack，把它算进多数派只会让整个群永远写不进去。
-   * 三成员真机群里所有成员都会自报地址（probe/pull/replicate），此时与
-   * 契约的「成员总数含自己」完全等价。
+   * 承诺集合 = **成员表全集**（含自己，去重）。
+   * 分母绝不能按「知道地址」过滤：那会让刚启动/还没学到地址的节点把分母压到 1，
+   * 于是自投即当选（2026-10-27 真机事故：桌面节点在两节点群里 epoch=2 自立为 leader）。
+   * 地址只决定「提案/拉票发给谁」，不决定多数派的分母（契约 §3：N = 成员总数含自己）。
    */
   function quorumMembers() {
-    return [store.instanceId, ...groupMemberIds().filter(
-      (id) => id !== store.instanceId && knownMemberAddress(id) !== '',
-    )];
+    const ids = new Set(groupMemberIds());
+    ids.add(store.instanceId);
+    return [...ids];
   }
 
-  /** 提案目标 = 承诺集合里除自己以外的成员 */
+  /** 提案目标 = 除自己以外、地址已知（含 peers.json 兜底）的成员；地址缺失只影响投递 */
   function proposeTargets() {
-    return quorumMembers().filter((id) => id !== store.instanceId);
+    return peerTargets();
   }
 
   /** 契约 §3：majority = floor(N/2)+1（N 含自己），none = 1 */
@@ -3255,8 +3260,11 @@ export function createPeerServer(overrides = {}) {
         return { ok: false, reason: 'no-group-key' };
       }
       const targets = peerTargets();
+      // 成员表里有、但地址未知/不可达的成员：它们不可能投票，票数自然不足
+      const unreachableBase = Math.max(0, quorumMembers().length - 1 - targets.length);
       let votes = 1;
       let ahead = null;
+      let unreachable = unreachableBase;
       const tasks = targets.map(async (peerId) => {
         try {
           const reply = await requestGroupVote({
@@ -3276,6 +3284,8 @@ export function createPeerServer(overrides = {}) {
         } catch (error) {
           const body = error?.body;
           if (Number(body?.epoch) > epoch) ahead = body;
+          // 不可达成员只计数（lost 那行日志里有 unreachable=N），不逐条刷日志
+          unreachable += 1;
           return false;
         }
       });
@@ -3315,8 +3325,12 @@ export function createPeerServer(overrides = {}) {
         // 重试窗口带抖动：两台落败者不会在同一毫秒又同时宣布候选
         leaseUntil: config.now() + leaseMs + Math.floor(Math.random() * leaseMs),
       });
-      if (config.logger) config.logger(`[group] election lost epoch=${epoch} votes=${votes}/${needed} reason=${reason}`);
-      return { ok: false, reason: 'quorum-unavailable', epoch, votes, needed };
+      if (config.logger) {
+        config.logger(
+          `[group] election lost epoch=${epoch} votes=${votes}/${needed} unreachable=${unreachable} reason=${reason}`,
+        );
+      }
+      return { ok: false, reason: 'quorum-unavailable', epoch, votes, needed, unreachable };
     } finally {
       electionInFlight = false;
     }
@@ -3420,6 +3434,9 @@ export function createPeerServer(overrides = {}) {
         commitSeq: st.commitSeq,
         pendingCount: pendingCount(),
         quorum: quorumMode,
+        // 分母与门槛：成员表全集（含没有地址的成员），地址只影响投递
+        memberCount: quorumMembers().length,
+        quorumNeeded: quorumNeeded(),
         degraded: isDegraded(),
         advertiseBaseUrl: localAdvertiseBaseUrl(),
       },
@@ -3515,6 +3532,10 @@ export function createPeerServer(overrides = {}) {
           epoch: after.epoch,
           role: after.role,
           leaderPeerId: after.leaderPeerId,
+          // 运维要能看出「差几票」：分母是成员表全集，不是可达成员数
+          votes: out?.votes ?? null,
+          needed: out?.needed ?? null,
+          memberCount: quorumMembers().length,
         },
         peerId: auth.peerId,
       };
@@ -3727,7 +3748,17 @@ export function createPeerServer(overrides = {}) {
     const method = String(req.method ?? 'GET').toUpperCase();
     // S3：成员节点只有当上 leader 才收 post（否则这些路径仍当作不存在，v0.5.0 语义不变）
     const leaderPost = !groupStore && method === 'POST' && url.pathname === '/v1/group/post' && isLocalLeader();
-    if (!groupStore && !leaderPost) return { status: 404, body: { error: 'not-found' } };
+    if (!groupStore && !leaderPost) {
+      // 成员节点上「post 打到非 leader」与「群没启用」要能分辨：状态码保持 404（v0.5 语义不变），
+      // 但正文与日志点明原因，免得和「leader 拿不到多数派 503」混在一起。
+      if (groupRole !== 'off' && method === 'POST' && url.pathname === '/v1/group/post') {
+        if (config.logger) {
+          config.logger(`[group] post refused reason=not-leader epoch=${roleState()?.epoch ?? 0}`);
+        }
+        return { status: 404, body: { error: 'not-leader' }, peerId: null };
+      }
+      return { status: 404, body: { error: 'not-found' } };
+    }
     if (!GROUP_V1_PATHS.includes(url.pathname)) return { status: 404, body: { error: 'not-found' } };
     if (method === 'GET' && url.pathname === '/v1/group/state') return groupState(req, rawBody);
     if (method === 'POST' && url.pathname === '/v1/group/join') return groupJoin(req, rawBody);

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

@@ -36,11 +36,13 @@ const OUTSIDER = peerFixture('peer-group-auth-2');
 async function startHub(t, overrides = {}) {
   const stateDir = overrides.stateDir ?? makeTempStateDir();
   seedPeers(stateDir, [MEMBER, OUTSIDER]);
+  // S3：与 group.test.mjs 同理 —— 假 peerId 成员无法 ack，固定 quorum:none。
+  const group = { enabled: true, name: 'default', autoJoin: false, retentionDays: 7, quorum: 'none' };
   const started = await startServer(t, {
     stateDir,
     allowRemotePrompts: true,
-    group: { enabled: true, name: 'default', autoJoin: false, retentionDays: 7 },
     ...overrides,
+    group: { ...group, ...(overrides.group ?? {}) },
   });
   return started;
 }

package/host/test/group-cluster.mjs

@@ -16,8 +16,9 @@ import { createPeerServer } from '../server.mjs';
 import { writeGroupKeyFile } from '../../lib/group-client.mjs';
 import { makeTempStateDir, request, writeJson0600 } from './helpers.mjs';
 
-export const heartbeatMs = 60;
-export const commitTimeoutMs = 200;
+// 全量测试是并行跑的，机器很忙：留足余量，避免「提交窗口/投票超时」偶发红
+export const heartbeatMs = 120;
+export const commitTimeoutMs = 600;
 export const tickMs = 25;
 
 export const secretOf = (peerId) => `sec-${peerId}`;
@@ -56,7 +57,7 @@ export function postAsEncrypted(baseUrl, fromId, body, extra = {}) {
   return postAs(baseUrl, fromId, body, { encrypt: true, ...extra });
 }
 
-export async function waitFor(check, { timeoutMs = 3_000, intervalMs = 20 } = {}) {
+export async function waitFor(check, { timeoutMs = 6_000, intervalMs = 20 } = {}) {
   const deadline = Date.now() + timeoutMs;
   let last;
   while (Date.now() < deadline) {
@@ -133,7 +134,7 @@ export async function startCluster(t, options = {}) {
         commitTimeoutMs: commitOverride,
         tickMs: tickOverride,
         jitterMs,
-        peerTimeoutMs: 50,
+        peerTimeoutMs: 250,
       },
     });
     const info = await server.listen(0, '127.0.0.1');

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

@@ -86,7 +86,7 @@ test('S3 ack 不足：成员全部下线 → 503、消息不可见、seq 不被
 });
 
 test('S3 提交超时：对端接受连接但不响应 → 等到 commitTimeoutMs 才 503，消息仍不可见', async (t) => {
-  const cluster = await startCluster(t, { count: 3 });
+  const cluster = await startCluster(t, { count: 3, commitTimeoutMs: 200 });
   const [a, b, c] = cluster.nodes;
   // 黑洞：TCP 握手成功但永不回 HTTP 响应（模拟半死节点，和 ECONNREFUSED 区分开）
   const sockets = new Set();

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

@@ -77,7 +77,7 @@ test('S3 租约过期：leader 被杀的 ≤3 个租约内自动接任，epoch+1
   await a.server.close();
   const survivors = [b, c];
   const winner = await waitFor(() => survivors.find((node) => roleOf(node).role === 'leader'), {
-    timeoutMs: 3_000,
+    timeoutMs: 8_000,
     intervalMs: 10,
   });
   assert.ok(winner, '杀掉 leader 后必须有一台接任');
@@ -331,6 +331,74 @@ test('S3 同 epoch 分裂投票：自投的候选让位给裁决更合法的一
   assert.equal(refused.reason, 'lower-priority');
   assert.deepEqual(readRoleFile(c).votedFor, { epoch: 2, peerId: a.peerId });
 });
+// ---------------------------------------------------------------------------
+// §3 quorum 分母（安全不变量：分母是成员表全集，不是「知道地址的成员」）
+// ---------------------------------------------------------------------------
+
+test('S3 quorum 分母 = 成员表全集：没有任何地址的成员也计入，且能真的挡住写入', async (t) => {
+  const cluster = await startCluster(t, { count: 3, heartbeatMs: 5_000, tickMs: 60_000 });
+  const [a, b] = cluster.nodes;
+  const lease = (node) => fetchGroupLease({ baseUrl: node.baseUrl, ...groupArgs(cluster, b.peerId) });
+
+  const baseline = await lease(a);
+  assert.equal(baseline.memberCount, 3, 'hub 成员表 = 自己 + 两台');
+  assert.equal(baseline.quorumNeeded, 2);
+
+  // 三个只存在于成员表、从来没有地址也从不在线的成员：分母必须跟着变大
+  a.server.group.addMember('peer-ghost-1', 'ghost-1');
+  a.server.group.addMember('peer-ghost-2', 'ghost-2');
+  a.server.group.addMember('peer-ghost-3', 'ghost-3');
+  const grown = await lease(a);
+  assert.equal(grown.memberCount, 6, '分母等于成员表条数（含 3 个无地址成员）');
+  assert.equal(grown.quorumNeeded, 4, 'floor(6/2)+1');
+
+  // 分母变大后，三台可达只凑得出 3 票 → 503（幽灵成员没有地址也必须算进多数派）
+  const blocked = await postAs(a.baseUrl, b.peerId, { kind: 'chat', text: 'ghost-blocked' });
+  assert.equal(blocked.status, 503, blocked.text);
+  assert.equal(blocked.json.error, 'quorum-unavailable');
+  assert.deepEqual(a.server.group.history({ sinceSeq: 0 }), []);
+
+  // 清掉幽灵成员后恢复可写（票数 3 ≥ 3）
+  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);
+});
+
+test('S3 单节点自立为 leader 必败：N=2 且另一台不可达 → quorum-unavailable', async (t) => {
+  // 这一条锁死真机事故：桌面节点曾经在 NAS 不可达时 epoch=2 自立为 leader
+  const cluster = await startCluster(t, { count: 2, heartbeatMs: 5_000, tickMs: 60_000 });
+  const [a, b] = cluster.nodes;
+  await a.server.close();
+
+  const out = await b.server.group.elect({ reason: 'test-lonely' });
+  assert.equal(out.ok, false, JSON.stringify(out));
+  assert.equal(out.reason, 'quorum-unavailable');
+  assert.equal(out.votes, 1, '只有自己那一票');
+  assert.equal(out.needed, 2, 'N=2 → floor(2/2)+1 = 2');
+  assert.equal(roleOf(b).role, 'follower', '绝不能自立为 leader');
+  assert.equal(roleOf(b).leaderPeerId, '');
+});
+
+test('S3 N=3：两台可达能当选（2 ≥ 2），只剩一台不能（1 < 2）', async (t) => {
+  const cluster = await startCluster(t, { count: 3, heartbeatMs: 5_000, tickMs: 60_000 });
+  const [a, b, c] = cluster.nodes;
+  await a.server.close();
+
+  const won = await b.server.group.elect({ reason: 'test-two-alive' });
+  assert.equal(won.ok, true, JSON.stringify(won));
+  assert.equal(won.votes, 2);
+  assert.equal(won.needed, 2);
+  assert.equal(roleOf(b).role, 'leader');
+
+  await b.server.close();
+  const lonely = await c.server.group.elect({ reason: 'test-one-alive' });
+  assert.equal(lonely.ok, false, JSON.stringify(lonely));
+  assert.equal(lonely.reason, 'quorum-unavailable');
+  assert.equal(lonely.votes, 1);
+  assert.equal(lonely.needed, 2);
+  assert.notEqual(roleOf(c).role, 'leader');
+});
 // 说明：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.test.mjs

@@ -31,11 +31,15 @@ const OUTSIDER = peerFixture('peer-group-2');
 async function startHub(t, overrides = {}) {
   const stateDir = overrides.stateDir ?? makeTempStateDir();
   seedPeers(stateDir, [MEMBER, OUTSIDER]);
+  // S3：majority 下 post 走 propose→commit，假 peerId 成员没有投票端点必然 503；
+  // 这个文件测的是 v0.5 端点语义，固定 quorum:none（写本地即提交）。
+  const group = { enabled: true, name: 'default', autoJoin: false, retentionDays: 7, quorum: 'none' };
   const started = await startServer(t, {
     stateDir,
     allowRemotePrompts: true,
-    group: { enabled: true, name: 'default', autoJoin: false, retentionDays: 7 },
     ...overrides,
+    // overrides.group 只覆盖给出的字段，别把 quorum:none 顶掉
+    group: { ...group, ...(overrides.group ?? {}) },
   });
   return started;
 }
@@ -373,7 +377,8 @@ test('同名成员在 state / history / admin 门面里都能区分（渲染层
   const { baseUrl, server } = await startServer(t, {
     stateDir,
     allowRemotePrompts: true,
-    group: { enabled: true, autoJoin: true },
+    // S3：假 peerId 成员没有投票端点 → 固定 quorum:none（与 startHub 同一口径）
+    group: { enabled: true, autoJoin: true, quorum: 'none' },
   });
 
   const join = (peer) => request(baseUrl, {
@@ -661,7 +666,8 @@ test('§6 进度镜像：start/finish 两条落进群，且不含 prompt 原文
   const { baseUrl: hubUrl, server: hub } = await startServer(t, {
     stateDir: hubState,
     allowRemotePrompts: true,
-    group: { enabled: true, autoJoin: true },
+    // S3：镜像用例同样固定 quorum:none（写本地即提交，与 v0.5 语义一致）
+    group: { enabled: true, autoJoin: true, quorum: 'none' },
   });
   hub.group.addMember(MEMBER.peerId, MEMBER.name);
 

package/lib/admin-group.test.mjs

@@ -417,10 +417,13 @@ test('hub 侧：未启用群的 host 一律回 enabled:false（契约 §7.3）',
 test('成员侧：GET/post 由插件进程代理到 hub（含 groupKey 剥离），浏览器不直连对端', async (t) => {
   const hubDir = makeTempStateDir();
   seedPeers(hubDir, [{ peerId: 'member-inst', name: 'me', secret: 'H2M', inboundSecret: 'M2H', baseUrl: 'http://127.0.0.1:1' }]);
+  // S3 起 majority 两阶段提交生效：本夹具里成员没有起真实服务器（baseUrl 打不通），
+  // 拿不到 ack → hub 按契约 §5/§9.3 回 503 是正确行为，而这条测试考的是「管理接口
+  // 代理 + groupKey 剥离」，所以固定 quorum:none（可写优先）以隔离该路径。
   const hub = await startServer(t, {
     stateDir: hubDir,
     name: 'hub-box',
-    group: { enabled: true, hub: '', name: '家里', autoJoin: true },
+    group: { enabled: true, hub: '', name: '家里', autoJoin: true, quorum: 'none' },
   });
   hub.server.group.addMember('member-inst', 'me');
 
@@ -750,8 +753,8 @@ test('S3 · GET 追加 role/leaseUntil/quorum/commitSeq/pendingCount/degraded：
   assert.equal(out.json.pendingCount, 2, '未提交条数来自门面');
   assert.equal(out.json.degraded, false, '有 leader 且租约未过期');
 
-  // 旧字段一个不动
-  assert.deepEqual(out.json.leader, { peerId: 'peer-hub', name: 'hub-box', epoch: 4 });
+  // 旧字段的取法不变，但 epoch 改为以角色门面为准（这里是 9，群元数据是 4）
+  assert.deepEqual(out.json.leader, { peerId: 'peer-hub', name: 'hub-box', epoch: 9 });
   assert.equal(out.json.selfRole, 'member');
   assert.equal(out.json.lastSeq, 8);
   assert.deepEqual(out.json.messages, MESSAGES);
@@ -823,6 +826,43 @@ test('S3 · degraded：租约过期 / 门面明确没有 leader 才报警，缺
   assert.equal(none.json.quorum, 'none', 'group.quorum=none 如实透给面板');
 });
 
+test('S3 · leader.epoch 以角色门面为准：角色 3 / 群元数据 1 → 3；门面缺席回退旧值', async () => {
+  // 真机（NAS 0.7.0）现象：group.json 的 keyVersion 世代是 1，角色文件已经是 3。
+  const metadataEpochOne = () => ({
+    groupId: 'g-1', name: 'default', epoch: 1, members: MEMBERS, messages: MESSAGES, lastSeq: 8,
+  });
+  const roleEpochThree = () => ({
+    role: 'leader', epoch: 3, leaderPeerId: 'inst-self', leaseUntil: Date.now() + 9000,
+    commitSeq: 8, pendingCount: 0,
+  });
+
+  const hubSide = await hit(stubAdmin({
+    group: { enabled: true, hub: '' },
+    api: { ...makeApi(), isHub: true, state: metadataEpochOne },
+    facade: { enabled: true, isHub: true, role: roleEpochThree },
+  }).admin, 'GET', '/api/lan-peers/group');
+  assert.equal(hubSide.json.leader.epoch, 3, 'leader.epoch 必须是选举世代，不是 group.json 的 keyVersion');
+  assert.equal(hubSide.json.leader.peerId, 'inst-self', 'peerId 取法不变');
+  assert.equal(hubSide.json.leader.name, 'self', 'name 取法不变');
+  assert.equal(hubSide.json.role, 'leader');
+
+  const memberSide = await hit(stubAdmin({
+    group: { enabled: true, hub: 'hub-box' },
+    api: { ...makeApi(), isHub: false, state: metadataEpochOne },
+    peers: HUB_PEERS,
+    facade: { enabled: false, isHub: false, role: () => ({ role: 'follower', epoch: 3, leaderPeerId: 'peer-hub' }) },
+  }).admin, 'GET', '/api/lan-peers/group');
+  assert.equal(memberSide.json.leader.epoch, 3, '成员侧同样以角色世代为准');
+  assert.equal(memberSide.json.leader.peerId, 'peer-hub', '成员侧 peerId 仍取 group.hub 指向的 peer');
+
+  // 角色门面缺席（老 host / M 未接线）：回到原来那个值，旧行为不破
+  const fallback = await hit(stubAdmin({
+    group: { enabled: true, hub: '' },
+    api: { ...makeApi(), isHub: true, state: metadataEpochOne },
+  }).admin, 'GET', '/api/lan-peers/group');
+  assert.equal(fallback.json.leader.epoch, 1, '没有角色门面时回退到群元数据的 epoch');
+});
+
 test('S3 · 群状态快照里的角色字段是第二来源（门面缺席时也能显示）', async () => {
   const leaseUntil = Date.now() + 9000;
   const api = apiWith({ isHub: true, lastSeq: 8 });

package/lib/admin.mjs

@@ -339,9 +339,15 @@ export function createAdmin({
     return typeof fromConfig === 'string' ? fromConfig : '';
   });
 
-  /** S1：leader —— hub 侧就是本机，成员侧就是 group.hub 指向的那个 peer。 */
-  const leaderOf = (snapshot, resolved) => {
-    const epoch = asSeqOrNull(snapshot?.epoch);
+  /**
+   * S1：leader —— hub 侧就是本机，成员侧就是 group.hub 指向的那个 peer。
+   *
+   * S3：epoch 优先取角色门面的 `epoch`（选举世代），只有角色门面缺席时才回退到
+   * 群元数据的 epoch。两者含义不同（群元数据那份是 group.json 的 keyVersion 世代），
+   * 真机上出现过「leader.epoch=1 而状态行 epoch=3」的显示打架，这里统一到选举世代。
+   */
+  const leaderOf = (snapshot, resolved, face = null) => {
+    const epoch = asSeqOrNull(face?.epoch) ?? asSeqOrNull(snapshot?.epoch);
     if (resolved.isHub === true) {
       return {
         peerId: String(store?.instanceId ?? ''),
@@ -395,8 +401,8 @@ export function createAdmin({
    * 来源优先级：host 门面 > 群状态快照 > 本文件兜底（hub=leader，成员=follower）。
    * 缺字段时给保守值而不是编造报警：只有「明确没有 leader」或「租约已过期」才算 degraded。
    */
-  const roleView = ({ isHub, settings, snapshot = null, leader = null, lastSeq = null }) => {
-    const face = roleFace() ?? {};
+  const roleView = ({ isHub, settings, snapshot = null, leader = null, lastSeq = null, state = null }) => {
+    const face = state ?? roleFace() ?? {};
     const snap = snapshot && typeof snapshot === 'object' ? snapshot : {};
     const known = [face.role, snap.role].find((value) => GROUP_ROLES.includes(String(value ?? '')));
     const leaseUntil = asSeqOrNull(face.leaseUntil) ?? asSeqOrNull(snap.leaseUntil);
@@ -709,6 +715,9 @@ export function createAdmin({
           // v0.6.0 S1/S2 的可见性字段：只加不改，未启用分支保持旧形状。
           const selfRole = isHub ? 'hub' : 'member';
           const advertise = advertiseAddress();
+          // S3：一次请求只读一次角色门面 —— leader.epoch 与状态行的 epoch 必须同源，
+          // 否则两次读取之间换 leader 就会在同一条响应里自相矛盾。
+          const roleState = roleFace();
           // v0.7.0 S3（契约 §7）：角色/租约/quorum/提交进度只加不改；失败分支也带上，
           // 面板据此显示 degraded，而不是留一片空白。
           const extras = (leader, replica, selfBaseUrl, snapshot = null, lastSeq = null) => ({
@@ -723,6 +732,7 @@ export function createAdmin({
               snapshot,
               leader,
               lastSeq,
+              state: roleState,
               settings: resolved.settings ?? groupSettings(),
             }),
           });
@@ -750,7 +760,7 @@ export function createAdmin({
               const view = memberView(member);
               return { ...view, lag: view.lastSeq == null ? null : Math.max(0, lastSeq - view.lastSeq) };
             });
-            const leader = leaderOf(snapshot, resolved);
+            const leader = leaderOf(snapshot, resolved, roleState);
             const replica = isHub
               ? { lastSeq, leaderLastSeq: lastSeq, lag: 0 }
               : replicaView(coreReplica() ?? readReplica(), lastSeq);

package/package.json

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