@mebular/fleet 0.0.0-stage → 0.1.0

package/src/onboard.ts

@@ -0,0 +1,601 @@
+// Fleet 设备上车 + 自检（Step 1b）。
+//
+// `onboardDevice`：一次（幂等）完成 主密钥（生成/导入，0600）→ 配置 → 设备证书（core 落盘）。
+// `doctor`：逐项 PASS/FAIL/SKIP（含脱敏与修复建议）；`skipped` 明列原因。
+
+import { access, chmod, mkdir } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import net from 'node:net';
+import {
+  Mebular,
+  type NamespaceHandoffPlan,
+  type NamespaceHandoffResult,
+  type NamespaceRejoinResult,
+} from '@mebular/core';
+import { isHeartbeatFresh, readHeartbeat, registeredServicesForDir } from '../../service/dist/index.js';
+
+import {
+  fileMode,
+  permissionsApplicable,
+  fleetConfigPath,
+  fleetMasterKeyPath,
+  fleetStoragePath,
+  generateMasterKey,
+  loadFleetConfig,
+  loadToolConfig,
+  masterKeyFingerprint,
+  readMasterKeyFile,
+  saveFleetConfig,
+  validateFleetConfig,
+  writeMasterKeyFile,
+  type FleetAgentConfig,
+  type FleetConfig,
+  type FleetEncryption,
+  type OnboardInput,
+  type OnboardResult,
+} from './config.js';
+import { CommandAgent, ExecutorRegistry, HermesAgent } from './runtime/agent.js';
+import { HttpOpenChamberSeam } from './runtime/openchamber-http.js';
+import { OpenChamberAgent } from './runtime/openchamber.js';
+import { EchoExecutor } from './runtime/executor.js';
+
+async function exists(path: string): Promise<boolean> {
+  try {
+    await access(path, constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** 由 agent 配置构建执行器注册表（未知 kind 已在校验期拒绝）。 */
+export function buildRegistry(agents: readonly FleetAgentConfig[]): ExecutorRegistry {
+  const registry = new ExecutorRegistry();
+  for (const a of agents) {
+    if (a.kind === 'echo') registry.register(a.name, new EchoExecutor());
+    else if (a.kind === 'command') {
+      registry.register(
+        a.name,
+        new CommandAgent({
+          command: a.command ?? '',
+          ...(a.baseArgs !== undefined ? { baseArgs: a.baseArgs } : {}),
+          ...(a.timeoutMs !== undefined ? { timeoutMs: a.timeoutMs } : {}),
+          ...(a.concurrency !== undefined ? { concurrency: a.concurrency } : {}),
+        }),
+      );
+    } else if (a.kind === 'hermes') {
+      registry.register(a.name, new HermesAgent({ ...(a.timeoutMs !== undefined ? { timeoutMs: a.timeoutMs } : {}) }));
+    } else {
+      registry.register(
+        a.name,
+        new OpenChamberAgent(new HttpOpenChamberSeam({ ...(a.timeoutMs !== undefined ? { timeoutMs: a.timeoutMs } : {}) })),
+      );
+    }
+  }
+  return registry;
+}
+
+/** 由配置 + 加密材料构造 core `Mebular` 选项（订阅自主；对端自行声明）。 */
+export function mebularOptions(config: FleetConfig, encryption: FleetEncryption): Record<string, unknown> {
+  return {
+    storagePath: config.storagePath,
+    deviceId: config.device,
+    encryption,
+    network: { enabled: true, libp2p: { listen: [config.listen] } },
+    sync: {
+      autoSync: true,
+      pushOnWrite: true,
+      pushOnWriteThrottleMs: 20,
+      namespaces: [config.namespace],
+      antiEntropy: { enabled: true, intervalMs: 600_000, jitterRatio: 0.2 },
+    },
+  };
+}
+
+/** 离线（不启网络）`Mebular` 选项：onboard/doctor/subscribe 用，只读写本地存储。 */
+export function offlineMebularOptions(config: FleetConfig, encryption: FleetEncryption): Record<string, unknown> {
+  return {
+    storagePath: config.storagePath,
+    deviceId: config.device,
+    encryption,
+    network: { enabled: false },
+  };
+}
+
+/** 生成/导入主密钥并写配置；幂等（重复执行不损坏身份）。 */
+export async function onboardDevice(input: OnboardInput): Promise<OnboardResult> {
+  if (typeof input.device !== 'string' || input.device.length === 0) throw new Error('onboard 需要 --device');
+  await mkdir(input.dir, { recursive: true });
+  if (permissionsApplicable()) await chmod(input.dir, 0o700);
+
+  const keyPath = fleetMasterKeyPath(input.dir);
+  let masterKeyCreated = false;
+  let encryption: FleetEncryption;
+  if (input.masterKeyFile !== undefined) {
+    encryption = await readMasterKeyFile(input.masterKeyFile);
+    await writeMasterKeyFile(keyPath, encryption); // 归一化到设备目录，0600
+  } else if (await exists(keyPath)) {
+    encryption = await readMasterKeyFile(keyPath);
+  } else {
+    encryption = await generateMasterKey();
+    await writeMasterKeyFile(keyPath, encryption);
+    masterKeyCreated = true;
+  }
+
+  const config: FleetConfig = {
+    v: 1,
+    device: input.device,
+    dir: input.dir,
+    storagePath: fleetStoragePath(input.dir),
+    masterKeyFile: keyPath,
+    namespace: input.namespace ?? 'tasks',
+    listen: input.listen ?? '/ip4/0.0.0.0/tcp/0',
+    peers: input.peerDevice !== undefined ? [{ device: input.peerDevice, ...(input.peerAddr !== undefined ? { addr: input.peerAddr } : {}) }] : [],
+    agents: input.agents ?? [{ name: 'echo', kind: 'echo' }],
+    ...(input.quotaLimitPerDevice !== undefined ? { quotaLimitPerDevice: input.quotaLimitPerDevice } : {}),
+  };
+  const errors = validateFleetConfig(config);
+  if (errors.length > 0) throw new Error(`onboard 配置非法：${errors.join('; ')}`);
+
+  const alreadyOnboarded = await exists(fleetConfigPath(input.dir));
+  await saveFleetConfig(fleetConfigPath(input.dir), config);
+
+  // 用 core 落盘设备身份/证书（幂等：已存在则复用）。
+  const mebular = new Mebular({
+    storagePath: config.storagePath,
+    deviceId: config.device,
+    encryption,
+    network: { enabled: false },
+  } as never);
+  await mebular.initialize();
+  try {
+    // 上车即声明本机对该域的订阅（订阅自主、零门槛；其他人仍需自行订阅）。
+    await mebular.subscribeNamespace(config.namespace);
+  } finally {
+    await mebular.shutdown();
+  }
+
+  return { config, alreadyOnboarded, masterKeyCreated, masterKeyFingerprint: masterKeyFingerprint(encryption.userMasterKey) };
+}
+
+/**
+ * 工具/CLI 共用的 app 生命周期：注入 live app（运行中 daemon）时**复用它**——不 initialize、
+ * 不 shutdown；否则按目录新建离线实例并在结束时关闭。这样同一份 handler 既能服务 daemon，也能离线跑。
+ */
+async function withToolMebular<T>(
+  dir: string,
+  live: Mebular | undefined,
+  run: (mebular: Mebular, config: FleetConfig) => Promise<T>,
+): Promise<T> {
+  const config = await loadToolConfig(dir);
+  if (live !== undefined) return run(live, config);
+  const encryption = await readMasterKeyFile(config.masterKeyFile);
+  const mebular = new Mebular(offlineMebularOptions(config, encryption) as never);
+  await mebular.initialize();
+  try {
+    return await run(mebular, config);
+  } finally {
+    await mebular.shutdown();
+  }
+}
+
+/**
+ * 本机订阅/退订某记忆域（**只能改自己**；写 `namespace_subscription` 到 `__policy__`）。
+ * `active=false` 只退订，不清本地数据；退出并交接走 `leaveNamespace`。
+ *
+ * `mebular`：运行中 daemon 的 live app（可选）；提供时写入同一 EventLog，不另开离线实例。
+ */
+export async function subscribeNamespace(
+  dir: string,
+  input: { namespace?: string; active?: boolean; note?: string; mebular?: Mebular },
+): Promise<{ member: string; namespace: string; active: boolean; eventId: string }> {
+  const active = input.active ?? true;
+  return withToolMebular(dir, input.mebular, async (mebular, config) => {
+    const namespace = input.namespace ?? config.namespace;
+    const event = active
+      ? await mebular.subscribeNamespace(namespace)
+      : await mebular.unsubscribeNamespace(namespace);
+    return { member: config.device, namespace, active, eventId: event.id };
+  });
+}
+
+/** 某分区的 active 订阅者（只读）。 */
+export async function namespaceSubscribers(dir: string, namespace?: string): Promise<string[]> {
+  const config = await loadToolConfig(dir);
+  const encryption = await readMasterKeyFile(config.masterKeyFile);
+  const mebular = new Mebular(offlineMebularOptions(config, encryption) as never);
+  await mebular.initialize();
+  try {
+    return await mebular.getNamespaceSubscribers(namespace ?? config.namespace);
+  } finally {
+    await mebular.shutdown();
+  }
+}
+
+/** 某分区订阅视图（只读）。 */
+export async function namespaceSubscriptions(
+  dir: string,
+  namespace?: string,
+): Promise<{ active: boolean; subscribers: string[] }> {
+  const config = await loadToolConfig(dir);
+  const encryption = await readMasterKeyFile(config.masterKeyFile);
+  const mebular = new Mebular(offlineMebularOptions(config, encryption) as never);
+  await mebular.initialize();
+  try {
+    return await mebular.getNamespaceSubscriptions(namespace ?? config.namespace);
+  } finally {
+    await mebular.shutdown();
+  }
+}
+
+/** 建域（零门槛）：写 `namespace_declare`；不自动订阅。`mebular` 为运行中 daemon 的 live app（可选）。 */
+export async function declareNamespace(
+  dir: string,
+  input: { namespace: string; note?: string; mebular?: Mebular },
+): Promise<{ namespace: string; eventId: string }> {
+  if (typeof input.namespace !== 'string' || input.namespace.length === 0) throw new Error('namespace 不能为空');
+  return withToolMebular(dir, input.mebular, async (mebular) => {
+    const event = await mebular.declareNamespace({ namespace: input.namespace, ...(input.note !== undefined ? { note: input.note } : {}) });
+    return { namespace: input.namespace, eventId: event.id };
+  });
+}
+
+/** 恢复被移出的设备（写 `device_restore`；high 档证明由调用方给出）。 */
+export async function restoreDevice(
+  dir: string,
+  input: {
+    subject: string;
+    note?: string;
+    nonce?: string;
+    cosign?: unknown;
+    breakGlass?: unknown;
+  },
+): Promise<{ subject: string; eventId: string }> {
+  if (typeof input.subject !== 'string' || input.subject.length === 0) throw new Error('restore 需要 --to <deviceId>');
+  const config = await loadToolConfig(dir);
+  const encryption = await readMasterKeyFile(config.masterKeyFile);
+  const mebular = new Mebular(offlineMebularOptions(config, encryption) as never);
+  await mebular.initialize();
+  try {
+    const event = await mebular.restoreDevice({
+      subject: input.subject,
+      ...(input.note !== undefined ? { note: input.note } : {}),
+      ...(input.nonce !== undefined ? { nonce: input.nonce } : {}),
+      ...(input.cosign !== undefined ? { cosign: input.cosign as never } : {}),
+      ...(input.breakGlass !== undefined ? { breakGlass: input.breakGlass as never } : {}),
+    });
+    return { subject: input.subject, eventId: event.id };
+  } finally {
+    await mebular.shutdown();
+  }
+}
+
+/** 重订阅恢复（准入：曾订阅 ∧ 未被移出；写图外 reset 标记）。 */
+export async function rejoinNamespace(
+  dir: string,
+  input: { namespace?: string } = {},
+): Promise<NamespaceRejoinResult> {
+  const config = await loadToolConfig(dir);
+  const encryption = await readMasterKeyFile(config.masterKeyFile);
+  const mebular = new Mebular(offlineMebularOptions(config, encryption) as never);
+  await mebular.initialize();
+  try {
+    return await mebular.rejoinNamespace({ namespace: input.namespace ?? config.namespace });
+  } finally {
+    await mebular.shutdown();
+  }
+}
+
+/** 本机是否已声明某分区重置（读图外标记）。只读。 */
+export async function rejoinReset(dir: string, namespace?: string): Promise<boolean> {
+  const config = await loadToolConfig(dir);
+  const encryption = await readMasterKeyFile(config.masterKeyFile);
+  const mebular = new Mebular(offlineMebularOptions(config, encryption) as never);
+  await mebular.initialize();
+  try {
+    return await mebular.hasRejoinReset(namespace ?? config.namespace);
+  } finally {
+    await mebular.shutdown();
+  }
+}
+
+/** 交接前置校验（只读）——继任者是否订阅且已 ack 本机在该分区的全部事件。 */
+export async function planHandoff(
+  dir: string,
+  input: { namespace?: string; successor: string },
+): Promise<NamespaceHandoffPlan> {
+  const config = await loadToolConfig(dir);
+  const encryption = await readMasterKeyFile(config.masterKeyFile);
+  const mebular = new Mebular(offlineMebularOptions(config, encryption) as never);
+  await mebular.initialize();
+  try {
+    return await mebular.planNamespaceHandoff({ namespace: input.namespace ?? config.namespace, successor: input.successor });
+  } finally {
+    await mebular.shutdown();
+  }
+}
+
+/** 退出并交接（默认要求继任者全量 ack；`force` 仅本地 CLI，仍如实记录）。 */
+export async function leaveNamespace(
+  dir: string,
+  input: { namespace?: string; successor: string; force?: boolean; note?: string },
+): Promise<NamespaceHandoffResult> {
+  const config = await loadToolConfig(dir);
+  const encryption = await readMasterKeyFile(config.masterKeyFile);
+  const mebular = new Mebular(offlineMebularOptions(config, encryption) as never);
+  await mebular.initialize();
+  try {
+    return await mebular.leaveNamespace({
+      namespace: input.namespace ?? config.namespace,
+      successor: input.successor,
+      ...(input.force !== undefined ? { force: input.force } : {}),
+      ...(input.note !== undefined ? { note: input.note } : {}),
+    });
+  } finally {
+    await mebular.shutdown();
+  }
+}
+
+/** `WARN` = 非致命告警（不使 `ok=false`），用于暴露加固/运维风险。 */
+export type DoctorStatus = 'PASS' | 'FAIL' | 'SKIP' | 'WARN';
+export interface DoctorCheck {
+  name: string;
+  status: DoctorStatus;
+  detail: string;
+  hint?: string;
+}
+export interface DoctorReport {
+  ok: boolean;
+  device: string;
+  checks: DoctorCheck[];
+  skipped: string[];
+}
+
+function parseTcp(multiaddr: string): { host: string; port: number } | null {
+  const m = /\/ip4\/([0-9.]+)\/tcp\/(\d+)/.exec(multiaddr);
+  return m ? { host: m[1]!, port: Number(m[2]) } : null;
+}
+
+function tcpReachable(host: string, port: number, timeoutMs = 1500): Promise<boolean> {
+  return new Promise((resolve) => {
+    const socket = net.connect({ host, port });
+    const done = (ok: boolean): void => {
+      socket.destroy();
+      resolve(ok);
+    };
+    socket.setTimeout(timeoutMs);
+    socket.once('connect', () => done(true));
+    socket.once('timeout', () => done(false));
+    socket.once('error', () => done(false));
+  });
+}
+
+/** 从 multiaddr 取监听主机（`/ip4|ip6/<host>/tcp/<port>`）；无法解析 → null。 */
+function listenHostOf(multiaddr: string): string | null {
+  const m = /^\/(?:ip4|ip6)\/([^/]+)\/tcp\/\d+/.exec(multiaddr);
+  return m ? m[1]! : null;
+}
+
+/** 回环/私有/链路本地/ULA 视为“非公网”；`0.0.0.0`/`::`/全局地址 → false。 */
+function isPrivateListenHost(host: string): boolean {
+  if (host === '127.0.0.1' || host === '::1' || host === 'localhost') return true;
+  if (/^10\./.test(host) || /^192\.168\./.test(host)) return true;
+  if (/^172\.(1[6-9]|2\d|3[01])\./.test(host)) return true;
+  if (/^169\.254\./.test(host)) return true;
+  if (/^fe80:/i.test(host)) return true;
+  if (/^f[cd]/i.test(host)) return true; // IPv6 ULA
+  return false;
+}
+
+/** 逐项自检；默认脱敏（不含任何密钥材料）。 */
+export async function doctor(dir: string): Promise<DoctorReport> {
+  const checks: DoctorCheck[] = [];
+  const cfgPath = fleetConfigPath(dir);
+  const add = (name: string, status: DoctorStatus, detail: string, hint?: string): void => {
+    checks.push({ name, status, detail, ...(hint !== undefined ? { hint } : {}) });
+  };
+
+  let config: FleetConfig;
+  try {
+    config = await loadFleetConfig(cfgPath);
+  } catch (error) {
+    add('config', 'FAIL', `无法加载配置：${(error as Error).message}`, `先运行：fleet onboard --dir ${dir} --device <id>`);
+    return { ok: false, device: '<unknown>', checks, skipped: [] };
+  }
+
+  // 1) 配置权限（POSIX mode；Windows 无该语义 → SKIP，依赖用户目录 ACL）
+  const posix = permissionsApplicable();
+  if (posix) {
+    const cfgMode = await fileMode(cfgPath).catch(() => -1);
+    add('config 权限', cfgMode === 0o600 ? 'PASS' : 'FAIL', `mode=${cfgMode.toString(8)}`, cfgMode === 0o600 ? undefined : `chmod 600 ${cfgPath}`);
+  } else {
+    add('config 权限', 'SKIP', 'Windows 无 POSIX mode；依赖用户目录 ACL（见 ONBOARDING Windows 章节）');
+  }
+
+  // 1.5) 监听地址：绑定全接口/公网 → **WARN**（不静默；给加固建议）。不使 ok=false。
+  const listenHost = listenHostOf(config.listen);
+  if (listenHost === null) {
+    add('监听地址', 'SKIP', `无法解析 listen：${config.listen}`);
+  } else if (isPrivateListenHost(listenHost)) {
+    add('监听地址', 'PASS', config.listen);
+  } else {
+    add(
+      '监听地址',
+      'WARN',
+      `${config.listen} 绑定到全接口/公网地址（${listenHost}）`,
+      '改绑回环或 LAN 地址（/ip4/127.0.0.1 或内网 IP）+ 经 relay 互联，或仅放行已授权对端（见 RELAY-OPS.md）',
+    );
+  }
+
+  // 2) 主密钥（存在 + 权限 + 可加载）
+  let encryption: FleetEncryption | null = null;
+  try {
+    encryption = await readMasterKeyFile(config.masterKeyFile);
+  } catch {
+    encryption = null;
+  }
+  if (!posix) {
+    add('主密钥权限', 'SKIP', 'Windows 无 POSIX mode；依赖用户目录 ACL（见 ONBOARDING Windows 章节）');
+    if (encryption === null) add('主密钥', 'FAIL', '无法加载主密钥文件', '重新生成或导入（--master-key）');
+    else add('主密钥', 'PASS', `fingerprint=${masterKeyFingerprint(encryption.userMasterKey)}`);
+  } else {
+    const keyMode = await fileMode(config.masterKeyFile).catch(() => -1);
+    if (keyMode !== 0o600) add('主密钥权限', 'FAIL', `mode=${keyMode.toString(8)}`, `chmod 600 ${config.masterKeyFile}`);
+    else if (encryption === null) add('主密钥', 'FAIL', '无法加载主密钥文件', '重新生成或导入（--master-key）');
+    else add('主密钥', 'PASS', `fingerprint=${masterKeyFingerprint(encryption.userMasterKey)}`);
+  }
+
+  // 3) 设备身份 + 主密钥链（core 验签设备证书）
+  const identityPath = `${config.storagePath}.identity.json`;
+  add('设备身份文件', (await exists(identityPath)) ? 'PASS' : 'FAIL', identityPath, `fleet onboard --dir ${dir} --device ${config.device}`);
+  if (encryption !== null) {
+    try {
+      const m = new Mebular({ storagePath: config.storagePath, deviceId: config.device, encryption, network: { enabled: false } } as never);
+      await m.initialize();
+      await m.shutdown();
+      add('主密钥链', 'PASS', '设备证书链到用户主密钥');
+    } catch (error) {
+      add('主密钥链', 'FAIL', `初始化失败：${(error as Error).message}`, '确认 --master-key 与既有身份一致');
+    }
+  }
+
+  // 4) 对端可达（有 addr 才测；否则等待对端拨入）
+  const withAddr = config.peers.filter((p) => typeof p.addr === 'string');
+  if (config.peers.length === 0) {
+    add('peer 可达', 'SKIP', '未配置任何对端（默认拒绝）', 'fleet onboard … --peer-device <id> [--peer-addr <multiaddr>]');
+  } else if (withAddr.length === 0) {
+    add('peer 可达', 'SKIP', '对端未提供 addr（等待对端拨入）', undefined);
+  } else {
+    for (const peer of withAddr) {
+      const tcp = parseTcp(peer.addr!);
+      const reachable = tcp !== null && (await tcpReachable(tcp.host, tcp.port));
+      add(`peer 可达(${peer.device})`, reachable ? 'PASS' : 'FAIL', peer.addr!, '确认对端已启动且地址/端口可达');
+    }
+  }
+
+  // 5) 订阅：本机自声明 + 对端自声明（没有「授权」项）。
+  const peerDevices = config.peers.map((p) => p.device);
+  if (encryption === null) {
+    add('namespace 订阅', 'SKIP', `主密钥不可用，无法读取图上订阅（namespace=${config.namespace}）`, '导入主密钥后重试（--master-key）');
+  } else {
+    try {
+      const m = new Mebular(offlineMebularOptions(config, encryption) as never);
+      await m.initialize();
+      const view = await m.getNamespaceSubscriptions(config.namespace);
+      const blocked = await m.getBlockedDevices();
+      const peerParts: string[] = [];
+      let allPeersSubscribed = peerDevices.length > 0;
+      for (const device of peerDevices) {
+        const subscribed = (await m.getSubscriptions(device)).includes(config.namespace);
+        peerParts.push(`${device}:${subscribed ? 'subscribed' : 'not-yet'}`);
+        if (!subscribed) allPeersSubscribed = false;
+      }
+      await m.shutdown();
+      const selfSubscribed = view.subscribers.includes(config.device);
+      add(
+        'namespace 订阅',
+        selfSubscribed ? 'PASS' : 'FAIL',
+        `namespace=${config.namespace} subscribers=[${view.subscribers.join(', ')}] self=${config.device}`,
+        selfSubscribed ? undefined : `fleet subscribe --namespace ${config.namespace}`,
+      );
+      add(
+        '对端订阅',
+        peerDevices.length === 0 ? 'SKIP' : allPeersSubscribed ? 'PASS' : 'SKIP',
+        peerDevices.length === 0 ? '未登记对端' : `peers=[${peerParts.join(', ')}]`,
+        allPeersSubscribed ? undefined : '对端自行声明订阅后即可互通（订阅零门槛）',
+      );
+      add(
+        '移出状态',
+        blocked.includes(config.device) ? 'FAIL' : blocked.length > 0 ? 'WARN' : 'PASS',
+        blocked.length === 0 ? '无设备被移出' : `blocked=[${blocked.join(', ')}]`,
+        blocked.includes(config.device) ? '本机已被移出：请由其他设备执行 device_restore 后重新订阅' : undefined,
+      );
+    } catch (error) {
+      add('namespace 订阅', 'FAIL', `读取本地订阅失败：${(error as Error).message}`, '确认存储/主密钥可用');
+    }
+  }
+
+  // 5.5) W2 守护（仅当 fleet 走 daemon 客户端时检查；embedded 不引入新 SKIP，保持既有验收不变）
+  if (config.daemon?.endpoint !== undefined) {
+    try {
+      const res = await fetch(`${config.daemon.endpoint.replace(/\/+$/, '')}/healthz`);
+      add('守护', res.ok ? 'PASS' : 'FAIL', `${config.daemon.endpoint}（HTTP ${res.status}）`, res.ok ? undefined : '确认 mebular serve 已启动（mebular service install mebular-serve）');
+    } catch (error) {
+      add('守护', 'FAIL', `${config.daemon.endpoint} 不可达`, `启动守护：mebular serve（${(error as Error).message}）`);
+    }
+  }
+
+  // 6) agent 注册表可解析
+  const agentErrors = validateFleetConfig({ ...config, agents: config.agents }).filter((e) => e.startsWith('agent'));
+  try {
+    buildRegistry(config.agents);
+    add('agent 注册表', agentErrors.length === 0 ? 'PASS' : 'FAIL', config.agents.map((a) => `${a.name}:${a.kind}`).join(','), '修正 agents 配置');
+  } catch (error) {
+    add('agent 注册表', 'FAIL', (error as Error).message, '修正 agents 配置');
+  }
+
+  // 7) 同步已收敛（本地是否已见对端署名的任务事件）
+  if (encryption === null) {
+    add('同步已收敛', 'SKIP', '主密钥不可用，跳过');
+  } else {
+    try {
+      const m = new Mebular({ storagePath: config.storagePath, deviceId: config.device, encryption, network: { enabled: false } } as never);
+      await m.initialize();
+      const nodes = (await m.graph.listNodes({ type: 'task_event' })) as Array<{
+        namespace?: string;
+        content?: { actor?: { device?: string }; author?: string };
+      }>;
+      await m.shutdown();
+      const taskNodes = nodes.filter((n) => n.namespace === config.namespace);
+      if (taskNodes.length === 0) {
+        add('同步已收敛', 'SKIP', '尚无任务事件，无法判断（可在派活后重跑 doctor）');
+      } else {
+        const peerDevices = new Set(config.peers.map((p) => p.device));
+        const authors = taskNodes
+          .map((n) => n.content?.actor?.device ?? n.content?.author)
+          .filter((a): a is string => typeof a === 'string');
+        const seen = new Set(authors.filter((a) => peerDevices.has(a)));
+        add('同步已收敛', seen.size > 0 ? 'PASS' : 'FAIL', `对端署名事件：${seen.size}/${peerDevices.size}`, '确认对端在线、已授权且已产生同步');
+      }
+    } catch (error) {
+      add('同步已收敛', 'FAIL', `读取本地状态失败：${(error as Error).message}`);
+    }
+  }
+
+  // 7.4) 2c 重入状态：本机是否已声明某分区重置（图外标记，不同步）。恒 PASS，供审计。
+  const rejoinMarker = `${config.storagePath}.rejoin.${config.namespace}.json`;
+  add(
+    '重入状态',
+    'PASS',
+    (await exists(rejoinMarker)) ? `namespace=${config.namespace} reset=true（已声明重置；下次同步将从零拉取）` : 'reset=false',
+  );
+
+  // 7.5) 2b 交接状态：存在未完成意图（图外 sidecar）→ FAIL（重跑 `fleet leave` 幂等续跑）。
+  const intentPath = `${config.storagePath}.handoff.json`;
+  if (await exists(intentPath)) {
+    add('交接状态', 'FAIL', `存在未完成交接意图：${intentPath}`, '重跑 `fleet leave --successor <id>`（幂等续跑）');
+  } else {
+    add('交接状态', 'PASS', '无未完成交接');
+  }
+
+  // 8) 服务已注册（D4）：是否有常驻服务**指向本目录**（读 manifest，dir-scoped，temp 目录可复现）。
+  const registered = registeredServicesForDir(dir);
+  if (registered.length === 0) {
+    add('服务已注册', 'SKIP', '未安装常驻服务', 'fleet service install fleet-node|fleet-worker（或 mebular service install）');
+  } else {
+    add('服务已注册', 'PASS', `services=[${registered.join(', ')}]`);
+  }
+
+  // 9) 心跳新鲜（D4）：process 写 `<dir>/service.heartbeat`；无文件 → SKIP，陈旧 → FAIL。
+  const heartbeat = readHeartbeat(dir);
+  if (heartbeat === null) {
+    add('心跳新鲜', 'SKIP', '无 service.heartbeat（服务未运行/未安装）');
+  } else if (isHeartbeatFresh(dir)) {
+    add('心跳新鲜', 'PASS', `role=${heartbeat.role} pid=${heartbeat.pid} age=${Date.now() - heartbeat.ts}ms sha=${heartbeat.sha}`);
+  } else {
+    add('心跳新鲜', 'FAIL', `心跳陈旧 age=${Date.now() - heartbeat.ts}ms（role=${heartbeat.role} pid=${heartbeat.pid}）`, '服务可能已崩溃：`fleet service status` / `fleet service logs`');
+  }
+
+  const skipped = checks.filter((c) => c.status === 'SKIP').map((c) => c.name);
+  return { ok: !checks.some((c) => c.status === 'FAIL'), device: config.device, checks, skipped };
+}