@mebular/fleet 0.0.0-stage → 0.1.0

package/src/config.ts

@@ -0,0 +1,286 @@
+// Fleet 设备配置与用户主密钥 IO（Step 1b）：全部 **0600**、默认脱敏、绝不回显密钥材料。
+//
+// 目录（device home）权限 0700；配置文件 `fleet.config.json`；主密钥 `master-key.json`；
+// 事件存储 `store.jsonl`（设备身份 `store.jsonl.identity.json` 由 core 落盘）。
+
+import { existsSync } from 'node:fs';
+import { chmod, mkdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { basename, dirname, join } from 'node:path';
+
+const SUBTLE = globalThis.crypto.subtle;
+
+/**
+ * 平台策略：POSIX mode 位是否构成有效保护。
+ *
+ * **Windows 上不成立**（`chmod`/`mode` 只有只读位语义，`stat().mode` 恒为 0666/0444），
+ * 因此 doctor 在 win32 上对权限项**显式 SKIP**（写入 `skipped`），而不是对 0666 判 FAIL。
+ * 威胁模型差异见 `ONBOARDING.md` 的 Windows 章节：Windows 依赖用户配置目录的 ACL
+ * （`%USERPROFILE%` 默认仅本人可读）与 OS 会话边界，等价性由平台保证而非 fleet 断言。
+ *
+ * 参数可注入（默认 `process.platform`），便于在任意平台确定性地测试两种分支。
+ */
+export function permissionsApplicable(platform: string = process.platform): boolean {
+  return platform !== 'win32';
+}
+
+/** core `Mebular` 需要的加密材料（用户主密钥）。令牌加入的设备**只有主公钥**（无主私钥）。 */
+export interface FleetEncryption {
+  userMasterKey: Uint8Array;
+  userMasterPrivateKey?: CryptoKey;
+}
+
+/** 生成 Ed25519 用户主密钥。 */
+export async function generateMasterKey(): Promise<FleetEncryption> {
+  const keyPair = (await SUBTLE.generateKey({ name: 'Ed25519' }, true, ['sign', 'verify'])) as CryptoKeyPair;
+  const userMasterKey = new Uint8Array(await SUBTLE.exportKey('raw', keyPair.publicKey));
+  return { userMasterKey, userMasterPrivateKey: keyPair.privateKey };
+}
+
+/** 写入主密钥文件（0600）。无主私钥（令牌加入设备）时只写主公钥。 */
+export async function writeMasterKeyFile(path: string, encryption: FleetEncryption): Promise<void> {
+  const record: { v: number; alg: string; publicKey: string; privateKeyPkcs8?: string } = {
+    v: 1,
+    alg: 'Ed25519',
+    publicKey: Buffer.from(encryption.userMasterKey).toString('base64'),
+  };
+  if (encryption.userMasterPrivateKey !== undefined) {
+    const pkcs8 = new Uint8Array(await SUBTLE.exportKey('pkcs8', encryption.userMasterPrivateKey));
+    record.privateKeyPkcs8 = Buffer.from(pkcs8).toString('base64');
+  }
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, JSON.stringify(record), { mode: 0o600 });
+  if (permissionsApplicable()) await chmod(path, 0o600);
+}
+
+/** 读取主密钥文件（不校验权限；权限由 doctor 断言）。 */
+export async function readMasterKeyFile(path: string): Promise<FleetEncryption> {
+  const parsed = JSON.parse(await readFile(path, 'utf-8')) as {
+    v?: number;
+    publicKey?: string;
+    privateKeyPkcs8?: string;
+  };
+  // 容忍缺省 `v`：`mebular` 侧生成的主密钥文件（<home>/user-master-key.json）不带版本字段。
+  if ((parsed.v !== undefined && parsed.v !== 1) || typeof parsed.publicKey !== 'string') {
+    throw new Error('master key file: 形状非法');
+  }
+  if (parsed.privateKeyPkcs8 === undefined) {
+    // 令牌加入设备：只有主公钥（无主私钥），用于验证对端/设备证书链。
+    return { userMasterKey: new Uint8Array(Buffer.from(parsed.publicKey, 'base64')) };
+  }
+  const userMasterKey = new Uint8Array(Buffer.from(parsed.publicKey, 'base64'));
+  const userMasterPrivateKey = await SUBTLE.importKey(
+    'pkcs8',
+    Buffer.from(parsed.privateKeyPkcs8, 'base64'),
+    { name: 'Ed25519' },
+    true,
+    ['sign'],
+  );
+  return { userMasterKey, userMasterPrivateKey };
+}
+
+/** 文件权限（低 9 位八进制）。 */
+export async function fileMode(path: string): Promise<number> {
+  return (await stat(path)).mode & 0o777;
+}
+
+export type FleetAgentKind = 'echo' | 'command' | 'hermes' | 'openchamber';
+
+export interface FleetAgentConfig {
+  name: string;
+  kind: FleetAgentKind;
+  /** kind=command 时的可执行文件 */
+  command?: string;
+  baseArgs?: string[];
+  timeoutMs?: number;
+  concurrency?: number;
+}
+
+export interface FleetPeerConfig {
+  device: string;
+  /** 可选 multiaddr（用于拨号；缺省则等待对端拨入） */
+  addr?: string;
+}
+
+export interface FleetConfig {
+  v: 1;
+  device: string;
+  dir: string;
+  storagePath: string;
+  masterKeyFile: string;
+  namespace: string;
+  /** 本机监听 multiaddr（libp2p） */
+  listen: string;
+  /** 已登记对端（地址簿；连接准入由 peerWhitelist/信任链决定） */
+  peers: FleetPeerConfig[];
+  /** 本机 agent 注册表（按 to.agent 名路由） */
+  agents: FleetAgentConfig[];
+  quotaLimitPerDevice?: number;
+  /**
+   * join 服务（T2）：`fleet node` 启动最小 HTTP 端点 `POST /mebular/join` 以签发委派证书。
+   * 令牌是 bearer 凭据（短 TTL + 一次性 nonce）；建议仅在 LAN 绑定。
+   */
+  joinService?: { enabled: boolean; bind?: string; port?: number };
+  /**
+   * W2 存储模式：`daemon`（默认于统一上车；走守护 app 接口，fleet 客户端化）/ `embedded`（**仅测试/CI**）。
+   * 缺省（未设）= `embedded`，以保持既有测试/验收不变；`quickstart` 会写 `daemon`。
+   */
+  store?: 'daemon' | 'embedded';
+  /** W2 守护 app 端点与令牌（daemon 模式必需） */
+  daemon?: { endpoint: string; token?: string; tokenFile?: string };
+}
+
+export const fleetConfigPath = (dir: string): string => join(dir, 'fleet.config.json');
+export const fleetMasterKeyPath = (dir: string): string => join(dir, 'master-key.json');
+export const fleetStoragePath = (dir: string): string => join(dir, 'store.jsonl');
+
+/** 校验配置；返回错误列表（空 = 合法）。 */
+export function validateFleetConfig(input: unknown): string[] {
+  const errors: string[] = [];
+  if (typeof input !== 'object' || input === null || Array.isArray(input)) return ['config 必须是对象'];
+  const c = input as Record<string, unknown>;
+  if (c.v !== 1) errors.push('v 必须为 1');
+  for (const key of ['device', 'dir', 'storagePath', 'masterKeyFile', 'namespace', 'listen']) {
+    if (typeof c[key] !== 'string' || (c[key] as string).length === 0) errors.push(`${key} 必须为非空字符串`);
+  }
+  if (!Array.isArray(c.peers)) errors.push('peers 必须为数组');
+  if (c.store !== undefined && c.store !== 'daemon' && c.store !== 'embedded') errors.push('store 必须为 daemon|embedded');
+  if (c.daemon !== undefined) {
+    const d = c.daemon as Record<string, unknown>;
+    if (typeof d !== 'object' || d === null || typeof d.endpoint !== 'string' || d.endpoint.length === 0) errors.push('daemon.endpoint 必填');
+    else if (d.token !== undefined && typeof d.token !== 'string') errors.push('daemon.token 非法');
+    else if (d.tokenFile !== undefined && typeof d.tokenFile !== 'string') errors.push('daemon.tokenFile 非法');
+  }
+  if (c.joinService !== undefined) {
+    const js = c.joinService as Record<string, unknown>;
+    if (typeof js !== 'object' || js === null || typeof js.enabled !== 'boolean') errors.push('joinService 形状非法');
+    else if (js.port !== undefined && (typeof js.port !== 'number' || js.port < 0 || js.port > 65535)) errors.push('joinService.port 非法');
+    else if (js.bind !== undefined && typeof js.bind !== 'string') errors.push('joinService.bind 非法');
+  }
+  if (!Array.isArray(c.agents) || (c.agents as unknown[]).length === 0) errors.push('agents 必须为非空数组');
+  for (const agent of (Array.isArray(c.agents) ? c.agents : []) as Array<Record<string, unknown>>) {
+    if (typeof agent?.name !== 'string' || agent.name.length === 0) errors.push('agent.name 非法');
+    if (!['echo', 'command', 'hermes', 'openchamber'].includes(String(agent?.kind))) {
+      errors.push(`agent.kind 非法：${String(agent?.kind)}`);
+    }
+    if (agent?.kind === 'command' && (typeof agent.command !== 'string' || agent.command.length === 0)) {
+      errors.push('command agent 需要 command');
+    }
+  }
+  return errors;
+}
+
+/**
+ * 解析 `--agent name:kind[,name:kind…]`（+ `--agent-command` / `--agent-base-args`）。
+ * `command` agent 一律经调用方给定的 `command`（推荐 `process.execPath`）+ `baseArgs`
+ * （如 fixture 路径）调用——**不依赖 shebang/可执行位**，Windows 亦然。
+ */
+export function parseAgentSpecs(
+  value: string,
+  options: { command?: string; baseArgs?: readonly string[] } = {},
+): FleetAgentConfig[] {
+  return value
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0)
+    .map((entry) => {
+      const [name, kind] = entry.split(':');
+      const agent: FleetAgentConfig = { name: name || 'echo', kind: (kind as FleetAgentKind) || 'echo' };
+      if (agent.kind === 'command') {
+        if (options.command !== undefined) agent.command = options.command;
+        if (options.baseArgs !== undefined && options.baseArgs.length > 0) agent.baseArgs = [...options.baseArgs];
+      }
+      return agent;
+    });
+}
+
+/** 保存配置（0600）。 */
+export async function saveFleetConfig(path: string, config: FleetConfig): Promise<void> {
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, JSON.stringify(config, null, 2), { mode: 0o600 });
+  if (permissionsApplicable()) await chmod(path, 0o600);
+}
+
+/** 加载配置（形状非法即抛错）。 */
+export async function loadFleetConfig(path: string): Promise<FleetConfig> {
+  const parsed = JSON.parse(await readFile(path, 'utf-8')) as unknown;
+  const errors = validateFleetConfig(parsed);
+  if (errors.length > 0) throw new Error(`config 非法：${errors.join('; ')}`);
+  return parsed as FleetConfig;
+}
+
+/**
+ * F-UNI：任务工具的 home 适配——两种布局都支持：
+ *   1) fleet home：`<dir>/fleet.config.json`（本机 fleet 设备）
+ *   2) **守护 home**：`<dir>/config.json`（`mebular serve`，含 root/delegated 两种身份）
+ * 由守护发起 `mebular mcp` 时 home 是守护 home，故这里把守护配置映射为等价 FleetConfig；
+ * 业务逻辑（session/工具 handler）保持**唯一**在 fleet 侧。
+ */
+export function daemonConfigToFleet(dir: string, cfg: Record<string, unknown>): FleetConfig {
+  const encryption = (cfg.encryption ?? {}) as Record<string, unknown>;
+  const sync = (cfg.sync ?? {}) as Record<string, unknown>;
+  const network = (cfg.network ?? {}) as Record<string, unknown>;
+  const libp2p = (network.libp2p ?? {}) as Record<string, unknown>;
+  const namespaces = Array.isArray(sync.namespaces) ? sync.namespaces.filter((s): s is string => typeof s === 'string' && s.length > 0) : [];
+  const listen = Array.isArray(libp2p.listen) && typeof libp2p.listen[0] === 'string' ? libp2p.listen[0] : '/ip4/0.0.0.0/tcp/4001';
+  const peers = (Array.isArray(network.peers) ? network.peers : [])
+    .filter((p): p is Record<string, unknown> => typeof p === 'object' && p !== null && typeof (p as Record<string, unknown>).device === 'string')
+    .map((p) => ({ device: String(p.device), ...(typeof p.addr === 'string' && p.addr.length > 0 ? { addr: p.addr } : {}) }));
+  const storagePath = typeof cfg.storagePath === 'string' && cfg.storagePath.length > 0 ? cfg.storagePath : join(dir, 'store.jsonl');
+  const masterKeyFile = typeof encryption.userMasterPublicKeyFile === 'string' && encryption.userMasterPublicKeyFile.length > 0
+    ? encryption.userMasterPublicKeyFile
+    : typeof encryption.keyFile === 'string' && encryption.keyFile.length > 0
+      ? encryption.keyFile
+      : join(dir, 'user-master-key.json');
+  const device = typeof cfg.deviceId === 'string' && cfg.deviceId.length > 0 ? cfg.deviceId : `device-${basename(dir) || 'local'}`;
+  return {
+    v: 1,
+    device,
+    dir,
+    storagePath,
+    masterKeyFile,
+    namespace: namespaces[0] ?? 'tasks',
+    listen,
+    peers,
+    // 守护侧只作任务板（board），不注册执行型 agent；占位满足校验（kind 属合法枚举）
+    agents: [{ name: 'board', kind: 'echo' }],
+    ...(typeof cfg.quotaLimitPerDevice === 'number' ? { quotaLimitPerDevice: cfg.quotaLimitPerDevice } : {}),
+  };
+}
+
+/** 读任务工具上下文配置：优先 fleet.config.json，否则按守护 config.json 适配。 */
+export async function loadToolConfig(dir: string): Promise<FleetConfig> {
+  const fleetPath = fleetConfigPath(dir);
+  if (existsSync(fleetPath)) return loadFleetConfig(fleetPath);
+  const daemonPath = join(dir, 'config.json');
+  if (!existsSync(daemonPath)) {
+    throw new Error(`缺少配置：${fleetPath} 与 ${daemonPath} 均不存在（需要 fleet.config.json 或守护 config.json）`);
+  }
+  const raw = JSON.parse(await readFile(daemonPath, 'utf-8')) as Record<string, unknown>;
+  return daemonConfigToFleet(dir, raw);
+}
+
+export interface OnboardInput {
+  dir: string;
+  device: string;
+  /** 已存在的用户主密钥文件（导入）；不给则生成 */
+  masterKeyFile?: string;
+  peerDevice?: string;
+  peerAddr?: string;
+  namespace?: string;
+  listen?: string;
+  agents?: FleetAgentConfig[];
+  quotaLimitPerDevice?: number;
+}
+
+export interface OnboardResult {
+  config: FleetConfig;
+  alreadyOnboarded: boolean;
+  masterKeyCreated: boolean;
+  masterKeyFingerprint: string;
+}
+
+/** 主密钥指纹（sha256 前 12 hex；**非密钥材料**，可安全展示/用于匹配）。 */
+export function masterKeyFingerprint(publicKey: Uint8Array): string {
+  return `sha256:${createHash('sha256').update(publicKey).digest('hex').slice(0, 12)}`;
+}

package/src/index.ts

@@ -0,0 +1,39 @@
+// @mebular/fleet —— 跨设备多 Agent 协作（任务=记忆）的公共入口。
+//
+// 边界（红线，见 DESIGN.md 与仓库 SEALING.md）：
+// - 只消费 `@mebular/core` 的**公共 API**（`import { ... } from '@mebular/core'`），
+//   不得 `import` core 的内部路径（`src/**`）；
+// - core 不得反向依赖本包（`tests/fleet/boundary.test.ts` 强制）；
+// - 墙钟（`expiresAt`）不进一致性判定。
+export * from './protocol/envelope.js';
+export * from './protocol/events.js';
+export * from './model.js';
+export * from './quota.js';
+export * from './agentdir.js';
+export * from './surface.js';
+export * from './config.js';
+export * from './onboard.js';
+export * from './security.js';
+export * from './quickstart.js';
+export * from './jointoken.js';
+export * from './qr.js';
+export * from './join.js';
+export * from './collab/dag.js';
+export * from './collab/tree.js';
+export * from './collab/negotiation.js';
+export * from './collab/chatter.js';
+export * from './transport/types.js';
+export * from './transport/spool.js';
+export * from './transport/null.js';
+export * from './store/file-store.js';
+export * from './store/mebular-store.js';
+export * from './store/message-store.js';
+export * from './store/daemon-store.js';
+export * from './runtime/planner.js';
+export * from './runtime/fairness.js';
+export * from './runtime/executor.js';
+export * from './runtime/agent.js';
+export * from './runtime/openchamber.js';
+export * from './runtime/openchamber-http.js';
+export * from './runtime/node.js';
+export * from './runtime/worker.js';

package/src/join.ts

@@ -0,0 +1,227 @@
+// 信任模型 v2（T2）：B 持**加入令牌**加入（不复制主密钥）。
+//
+// 流程：生成设备密钥 → 向 inviter 的 join 端点请求**委派证书**（令牌验签/TTL/一次性）→
+// 落盘身份文件（含证书链，**无主私钥**）→ 写**主公钥**文件 → onboard（登记 inviter 地址）→ 声明成员。
+// 主密钥私钥全程不出现；inviter 可为**任意**在册设备。
+
+import { access, mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { constants } from 'node:fs';
+import { Mebular, IdentityManager, bytesToHex, hexToBytes, EndpointBook, FileEndpointStore, derivePeerIdHex, RELAY_SEEDS_KEY } from '@mebular/core';
+import {
+  fleetConfigPath,
+  fleetMasterKeyPath,
+  fleetStoragePath,
+  loadFleetConfig,
+  masterKeyFingerprint,
+  readMasterKeyFile,
+  writeMasterKeyFile,
+  type FleetAgentConfig,
+  type FleetEncryption,
+} from './config.js';
+import type { ServiceInstaller } from './quickstart.js';
+import { offlineMebularOptions, onboardDevice } from './onboard.js';
+import { agentMcpConfig, configureDaemonHome } from './quickstart.js';
+import { decodeJoinToken, requestJoin } from './jointoken.js';
+
+export interface JoinWithTokenInput {
+  dir: string;
+  token: string;
+  device: string;
+  namespace?: string;
+  listen?: string;
+  agents: FleetAgentConfig[];
+  timeoutMs?: number;
+  /** W2：同时配置统一守护（delegated 身份 + fleet daemon 客户端 + 令牌） */
+  daemon?: boolean;
+  daemonPort?: number;
+  joinPort?: number;
+  installDaemon?: ServiceInstaller;
+}
+
+export interface JoinWithTokenResult {
+  /** C2：写入地址簿的 hint 条数（0 = 旧令牌无 hints） */
+  hinted: number;
+  device: string;
+  dir: string;
+  peer: string;
+  namespace: string;
+  fingerprint: string;
+  alreadyJoined: boolean;
+  inviterDeviceId: string;
+  next: string[];
+  /** W2：统一守护配置结果 */
+  daemon?: { endpoint: string; installed: boolean; note?: string };
+  /** W2：Agent MCP 配置片段 */
+  agentMcp: Record<string, unknown>;
+}
+
+/**
+ * C2：把邀请方 hints 落盘到 `<dir>/net/peers.json`（0600）。
+ * 同时写 **deviceId 键**（可读）与 **peerId 键**（由 inviterPublicKey 派生，首次拨号即可命中）。
+ * 返回写入条数；无 hints（旧令牌）→ 0。任何失败都不应让 join 失败。
+ */
+export async function persistInviterHints(dir: string, token: {
+  inviterDeviceId: string;
+  inviterPublicKey: string;
+  endpoints?: string[];
+  relaySeeds?: string[];
+}): Promise<number> {
+  try {
+    const hints = Array.isArray(token.endpoints) ? token.endpoints.filter((a) => typeof a === 'string' && a.length > 0) : [];
+    const seeds = Array.isArray(token.relaySeeds) ? token.relaySeeds.filter((a) => typeof a === 'string' && a.length > 0) : [];
+    if (hints.length === 0 && seeds.length === 0) return 0;
+    const book = new EndpointBook({ store: new FileEndpointStore(join(dir, 'net', 'peers.json')) });
+    await book.load();
+    let count = 0;
+    const keys = [token.inviterDeviceId];
+    try {
+      keys.push(derivePeerIdHex(hexToBytes(token.inviterPublicKey)));
+    } catch {
+      // 公钥非法：只写 deviceId 键
+    }
+    for (const key of keys) {
+      if (hints.length > 0) count += await book.upsert(key, hints, 'paired');
+    }
+    // relay seeds 存保留键（不是对端地址；app 启动时并入 libp2p.relayServers）
+    if (seeds.length > 0) await book.upsert(RELAY_SEEDS_KEY, seeds, 'config');
+    return count;
+  } catch {
+    return 0;
+  }
+}
+
+/** B：用令牌加入（**不持有主密钥私钥**）。 */
+export async function joinWithToken(input: JoinWithTokenInput): Promise<JoinWithTokenResult> {
+  const token = decodeJoinToken(input.token);
+  const namespace = input.namespace ?? token.namespace;
+  const listen = input.listen ?? '/ip4/0.0.0.0/tcp/4001';
+
+  const alreadyJoined = await exists(fleetConfigPath(input.dir));
+  if (alreadyJoined) {
+    const existing = await loadFleetConfig(fleetConfigPath(input.dir));
+    if (existing.device !== input.device) {
+      throw new Error(`目录已被设备 ${existing.device} 占用（--dir ${input.dir}）；换目录或先停用。`);
+    }
+  }
+
+  await mkdir(input.dir, { recursive: true });
+  const storagePath = fleetStoragePath(input.dir);
+  const keyPath = fleetMasterKeyPath(input.dir);
+  let peerAddr: string | undefined;
+  let securityApproval: { approvalId: string; nonce: string; initiator?: string; cosign?: unknown } | undefined;
+
+  if (!alreadyJoined) {
+    const im = new IdentityManager();
+    const deviceKey = await im.generateDeviceKey(input.device, input.device);
+    const issued = await requestJoin({
+      endpoint: token.endpoint,
+      token: input.token,
+      deviceId: input.device,
+      devicePublicKeyHex: bytesToHex(deviceKey.publicKey),
+      ...(input.timeoutMs !== undefined ? { timeoutMs: input.timeoutMs } : {}),
+    });
+    peerAddr = issued.inviterMultiaddrs[0];
+    securityApproval = issued.securityApproval;
+    const privateKeyPkcs8 = await IdentityManager.exportPrivateKey(deviceKey.privateKey);
+    const record = {
+      deviceId: input.device,
+      deviceName: input.device,
+      publicKeyHex: bytesToHex(deviceKey.publicKey),
+      certificate: issued.certificate,
+      certificateChain: issued.chain,
+      createdAt: Date.now(),
+      privateKeyPkcs8,
+    };
+    await writeFile(`${storagePath}.identity.json`, JSON.stringify(record, null, 2), { mode: 0o600 });
+    const publicOnly: FleetEncryption = { userMasterKey: hexToBytes(token.masterPublicKey) };
+    await writeMasterKeyFile(keyPath, publicOnly);
+  }
+
+  // C2：把邀请方 hints（token.endpoints）写入本机地址簿 <dir>/net/peers.json（0600）
+  // 机制在 core（EndpointBook/FileEndpointStore），路径由 app 决定；不改变任何授权。
+  const hinted = await persistInviterHints(input.dir, token);
+
+  const onboard = await onboardDevice({
+    dir: input.dir,
+    device: input.device,
+    namespace,
+    listen,
+    agents: input.agents,
+    peerDevice: token.inviterDeviceId,
+    ...(peerAddr !== undefined ? { peerAddr } : {}),
+  });
+  const config = onboard.config;
+  const encryption = await readMasterKeyFile(config.masterKeyFile);
+
+  const mebular = new Mebular(offlineMebularOptions(config, encryption) as never);
+  await mebular.initialize();
+  try {
+    await mebular.declareNamespaceSubscription({
+      namespace,
+      active: true,
+      note: 'join-token self',
+      ...(securityApproval !== undefined
+        ? {
+            initiator: securityApproval.initiator,
+            nonce: securityApproval.nonce,
+            ...(securityApproval.cosign !== undefined ? { cosign: securityApproval.cosign as never } : {}),
+          }
+        : {}),
+    });
+  } finally {
+    await mebular.shutdown();
+  }
+
+  // W2 B2：delegated 守护 home（无主私钥）+ fleet daemon 客户端 + （可选）mebular-serve
+  let daemonInfo: { endpoint: string; installed: boolean; note?: string } | null = null;
+  if (input.daemon === true) {
+    const publicKeyFile = join(input.dir, 'user-master-key.json');
+    await writeFile(publicKeyFile, JSON.stringify({ publicKey: Buffer.from(encryption.userMasterKey).toString('base64') }, null, 2), { mode: 0o600 });
+    const peer = peerAddr ?? config.peers[0]?.addr;
+    const peers = peer !== undefined ? [{ device: token.inviterDeviceId, addr: peer }] : [{ device: token.inviterDeviceId }];
+    const { endpoint } = await configureDaemonHome(
+      input.dir,
+      config,
+      namespace,
+      input.joinPort ?? 4002,
+      input.daemonPort ?? 7331,
+      { userMasterPublicKeyFile: publicKeyFile },
+      peers,
+    );
+    let installed = false;
+    let note: string | undefined;
+    if (input.installDaemon !== undefined) {
+      const outcome = await input.installDaemon(input.dir);
+      installed = outcome.installed;
+      note = outcome.note;
+    }
+    daemonInfo = { endpoint, installed, ...(note !== undefined ? { note } : {}) };
+  }
+
+  return {
+    hinted,
+    device: config.device,
+    dir: config.dir,
+    peer: token.inviterDeviceId,
+    namespace,
+    fingerprint: masterKeyFingerprint(encryption.userMasterKey),
+    alreadyJoined,
+    inviterDeviceId: token.inviterDeviceId,
+    next: [
+      '本机已声明订阅；对端同步后即可互通（订阅零门槛，无需批准）',
+      ...(hinted > 0 ? [`已写入邀请方地址 hints（${hinted} 条）：本机可在无 --addr 时自动选路连通`] : ['令牌未携带地址 hints（旧令牌）：首次连接仍需显式 --addr']),
+    ],
+    ...(daemonInfo !== null ? { daemon: daemonInfo } : {}),
+    agentMcp: agentMcpConfig(),
+  };
+}
+
+async function exists(path: string): Promise<boolean> {
+  try {
+    await access(path, constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}