dsh-punky-swarm 0.3.6

package/lib/assembly/schema.js

@@ -0,0 +1,253 @@
+/*
+Copyright (C) 2025-2026 Punky
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as
+published by the Free Software Foundation, either version 3 of the
+License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program. If not, see <https://www.gnu.org/licenses/>.
+*/
+
+// 装配配置注册表统一
+// 纯函数 + 数据，零运行时依赖（仅 import 本包 lib/schema.js 默认常量）。
+// 能力键路径保持既有现状（aip.* / capabilities.* 两套不变）= 消费点零改动 = 向后兼容。
+// 校验语义：validateCapabilities 仅对显式 enabled 的非法组合报错（fail-closed 在测试/装配验收层）；
+//   引擎启动侧只 warn 不炸宿主（配置错误不破坏可用性，与「默认关零破坏」一致）。
+
+import { WATCH_DEFAULTS, TRAJECTORY_DEFAULTS, VERIFY_DEFAULTS, DISCOVERY_DEFAULTS, ACPS_DEFAULTS } from '../schema.js';
+
+// ── 能力注册表（11 键：aip/identity/discovery/verify/watch/worktree/budget/trajectory/acps/logs/topic）──
+// path = config 取值路径；default = 缺省值（7 键默认开——aip/discovery/verify/watch/worktree/budget/trajectory；
+//   显式 enabled:false 可逐键关闭；4 键默认关——identity/acps/logs/topic，需显式开启）；
+// consumers = 既有消费点（键路径一致性依据）
+// identity 键：身份体系默认关——config.aip.identity.enabled === true 时
+//   调用方才激活 lib/aip/identity.js 模块 API（AIC 身份码注册 + CAI 证书发行 + 签名 + 信任链验证）；
+//   默认关 → 零开销零破坏；不注册新治理工具（20 工具契约不变），身份能力经模块 API 暴露。
+export const CAPABILITY_REGISTRY = [
+  { key: 'aip', path: ['aip'], default: { enabled: true }, consumers: ['tools/register.js catalog + api.js /tools 端点'] },
+  // acps 键：ACPs 通讯能力——对外 mTLS 服务端点 + 内部桥。
+  // 默认关：acps.enabled 与 acps.endpoint.enabled 均 false 时零加载零监听（config 短路）；显式开启才
+  //   index.js 实例化 createAcpsServer（lib/acps/server.js + certs.js，node:https/tls/crypto 原生，零新依赖）。
+  { key: 'acps', path: ['acps'], default: ACPS_DEFAULTS, consumers: ['index.js acps endpoint 装配 + lib/acps/server.js'] },
+  { key: 'identity', path: ['aip', 'identity'], default: { enabled: false }, consumers: ['lib/aip/identity.js 模块 API（AIC/CAI/sign/verifyTrustChain）'] },
+  { key: 'discovery', path: ['capabilities', 'discovery'], default: DISCOVERY_DEFAULTS, consumers: ['index.js discovery 服务装配 + api.js /discover + /.well-known/aip 端点'] },
+  { key: 'verify', path: ['capabilities', 'verify'], default: VERIFY_DEFAULTS, consumers: ['index.js mountVerify 捕获 hook', 'verify/gate.js createCompletionGate(DI)'] },
+  { key: 'watch', path: ['capabilities', 'watch'], default: WATCH_DEFAULTS, consumers: ['index.js watchdog + watch/lane-heartbeat.js'] },
+  { key: 'worktree', path: ['capabilities', 'worktree'], default: { enabled: true, mergeAgent: { enabled: false, model: null, timeoutMs: 600000 } }, consumers: ['tools/lane-tools.js 三工具注册'] },
+  { key: 'budget', path: ['capabilities', 'budget'], default: { enabled: true, maxChainHops: 4, maxChainRoundTrips: 2 }, consumers: ['comms/budget.js + mailbox-tools.js 发送检查'] },
+  { key: 'trajectory', path: ['capabilities', 'trajectory'], default: TRAJECTORY_DEFAULTS, consumers: ['index.js 桥接订阅'] },
+  // logs 键（E3 增强，P1-01）：日志导出工具注册开关——默认关（与 cordis.patch.yml 显式 logs.enabled:true 相合）；
+  //   消费点经 readCapability(config,'logs') 缺省读取，显式 enabled:false 可关。
+  { key: 'logs', path: ['capabilities', 'logs'], default: { enabled: false }, consumers: ['tools/log-tools.js log_export 注册'] },
+  // topic 键（P1-03）：comms/topic.js 预留模块开关——默认关；接线（trajectory 桥广播改经本模块等）归操作面板批次，本批不实施。
+  { key: 'topic', path: ['capabilities', 'topic'], default: { enabled: false }, consumers: ['comms/topic.js（预留，接线归操作面板批次）'] },
+];
+
+// ── 互斥表（预留空表：当前能力两两可叠加；未来互斥能力登记于此）──
+// 项形如 { keys: ['x', 'y'], message: '...' }：两键同时 enabled=true → validateCapabilities 报 MUTEX error
+export const EXCLUSIONS = [];
+
+// ── 反向断言权威表（对齐 jiufeng-team skill 装配表 8 角色）──
+// manager 显式豁免：Leader 直系拉起、不经 wavePlan lane 角色池，不登记于装配表 roles
+export const REQUIRED_ROLES = ['coordinator', 'designer', 'coder', 'tester', 'reviewer', 'supervisor', 'doc-manager'];
+
+// ── 盲审扩展 ──
+// 三角色 + 六模板键名清单；模板内容由 lib/assembly/audit-blind-review.js 提供
+export const BLIND_REVIEW_ROLES = ['audit-panelist', 'audit-aggregate', 'audit-critic'];
+export const BLIND_REVIEW_TEMPLATE_KEYS = ['bundle', 'panelist', 'aggregate', 'critic', 'checklist', 'config'];
+
+// ── 内部工具 ──
+// R1 热更新（lib/hot/config-watch.js）导出复用本函数做 runtime 覆盖层 deepMerge——
+// 禁止复制散落实现（复制即漂移源，设计 §5.3 风险点 1）；readCapability 缺省合并与本函数同源。
+export function deepMerge(base, override) {
+  if (override === undefined || override === null) return base;
+  if (typeof base !== 'object' || base === null || typeof override !== 'object' || override === null) return override;
+  const out = { ...base };
+  for (const k of Object.keys(override)) {
+    const b = out[k];
+    const o = override[k];
+    out[k] = (b !== null && typeof b === 'object' && !Array.isArray(b)
+      && o !== null && typeof o === 'object' && !Array.isArray(o))
+      ? deepMerge(b, o)
+      : o;
+  }
+  return out;
+}
+
+// ── 统一读取：按注册表 path 取值 + 默认合并（消费点语义等价，供测试与工具面统一读取）──
+export function readCapability(config, key) {
+  const entry = CAPABILITY_REGISTRY.find((e) => e.key === key);
+  if (!entry) return undefined;
+  let val = config;
+  for (const seg of entry.path) val = val?.[seg];
+  return deepMerge(entry.default, val);
+}
+
+// ── 校验：仅对显式 enabled 的非法组合报错；禁用能力零校验零开销 ──
+export function validateCapabilities(config = {}) {
+  const errors = [];
+  const c = config.capabilities ?? {};
+
+  // DEP-1 verify：mode ∈ {advisory, enforce}（createCompletionGate 静默回退，统一校验兜底）
+  if (c.verify?.enabled === true && c.verify.mode !== undefined && !['advisory', 'enforce'].includes(c.verify.mode)) {
+    errors.push('DEP-1: capabilities.verify.mode must be advisory or enforce (got ' + JSON.stringify(c.verify.mode) + ')');
+  }
+
+  // DEP-2 trajectory：autoFail === true ⇒ enabled === true（autoFail 无 enabled 无意义）
+  if (c.trajectory?.autoFail === true && c.trajectory.enabled !== true) {
+    errors.push('DEP-2: capabilities.trajectory.autoFail=true requires enabled=true');
+  }
+
+  // DEP-3 trajectory：poll.enabled === true ⇒ poll.baseUrl 非空字符串（HTTP 轮询需目标地址）
+  if (c.trajectory?.poll?.enabled === true) {
+    const baseUrl = c.trajectory.poll.baseUrl;
+    if (typeof baseUrl !== 'string' || baseUrl.trim().length === 0) {
+      errors.push('DEP-3: capabilities.trajectory.poll.enabled=true requires non-empty poll.baseUrl');
+    }
+  }
+
+  // DEP-4 budget：maxChainHops / maxChainRoundTrips 为正整数（显式声明时；环防护参数合法性）
+  if (c.budget?.enabled === true) {
+    for (const field of ['maxChainHops', 'maxChainRoundTrips']) {
+      if (c.budget[field] !== undefined && (!Number.isInteger(c.budget[field]) || c.budget[field] < 1)) {
+        errors.push('DEP-4: capabilities.budget.' + field + ' must be a positive integer (got ' + JSON.stringify(c.budget[field]) + ')');
+      }
+    }
+  }
+
+  // DEP-5 watch：maxMissed ≥ 1、scanIntervalMinutes ≥ 0.1（显式声明时；resolveWatchConfig 已钳制，校验兜底）
+  if (c.watch?.enabled === true) {
+    if (c.watch.maxMissed !== undefined && (!Number.isFinite(c.watch.maxMissed) || c.watch.maxMissed < 1)) {
+      errors.push('DEP-5: capabilities.watch.maxMissed must be >= 1 (got ' + JSON.stringify(c.watch.maxMissed) + ')');
+    }
+    if (c.watch.scanIntervalMinutes !== undefined && (!Number.isFinite(c.watch.scanIntervalMinutes) || c.watch.scanIntervalMinutes < 0.1)) {
+      errors.push('DEP-5: capabilities.watch.scanIntervalMinutes must be >= 0.1 (got ' + JSON.stringify(c.watch.scanIntervalMinutes) + ')');
+    }
+  }
+
+  // MUTEX：互斥表（当前空表，无天然互斥；心跳/预算/worktree/verify/trajectory/aip 两两可叠加）
+  for (const ex of EXCLUSIONS) {
+    const on = ex.keys.filter((k) => readCapability(config, k)?.enabled === true);
+    if (on.length === ex.keys.length) errors.push('MUTEX: ' + ex.message);
+  }
+
+  return { errors };
+}
+
+// ── 结构校验：team/layers/roles/skills 形状；role ∈ roles ⇒ skills[role] 非空字符串数组 ──
+export function validateAssembly(assembly) {
+  const errors = [];
+  if (assembly === null || typeof assembly !== 'object') {
+    return { errors: ['assembly must be an object'] };
+  }
+  if (typeof assembly.team !== 'string' || assembly.team.length === 0) {
+    errors.push('assembly.team must be a non-empty string');
+  }
+  const layers = assembly.layers;
+  if (layers === null || typeof layers !== 'object' || Array.isArray(layers)) {
+    errors.push('assembly.layers must be an object');
+    return { errors };
+  }
+  for (const [layerName, layer] of Object.entries(layers)) {
+    if (layer === null || typeof layer !== 'object') {
+      errors.push('layers.' + layerName + ' must be an object');
+      continue;
+    }
+    const roles = layer.roles;
+    if (!Array.isArray(roles) || roles.length === 0) {
+      errors.push('layers.' + layerName + '.roles must be a non-empty array');
+      continue;
+    }
+    const skills = layer.skills;
+    if (skills === null || typeof skills !== 'object' || Array.isArray(skills)) {
+      errors.push('layers.' + layerName + '.skills must be an object');
+      continue;
+    }
+    for (const role of roles) {
+      const list = skills[role];
+      if (!Array.isArray(list) || list.length === 0) {
+        errors.push('layers.' + layerName + '.skills.' + role + ' missing or empty');
+      } else {
+        for (const s of list) {
+          if (typeof s !== 'string' || s.length === 0) {
+            errors.push('layers.' + layerName + '.skills.' + role + ' contains non-string skill');
+          }
+        }
+      }
+    }
+  }
+  return { errors };
+}
+
+// ── 完整性断言（三视图，入测试门禁）──
+// 视图 1 正向：装配表自洽（∀ (layer, role)：skills[role] 非空字符串数组且每个 skill 可解析）
+// 视图 2 反向：jiufeng-team 装配表 7 角色（manager 显式豁免）全部出现且映射非空
+// 视图 3 扩展：extensions.blindReview.enabled=true 时三角色映射非空 + 六模板键齐备
+// skillCatalog：{ has(name) -> bool }；生产传 ~/.agents/skills/<name>/SKILL.md 存在性解析器，测试传 fixture
+export function assertAssemblyCompleteness(assembly, skillCatalog) {
+  if (typeof skillCatalog?.has !== 'function') {
+    throw new TypeError('assertAssemblyCompleteness requires skillCatalog.has(name) — production: ~/.agents/skills/<name>/SKILL.md resolver; test: fixture');
+  }
+  const missing = [];
+  const layers = assembly?.layers ?? {};
+
+  // 收集全量角色 → skills（供视图 2/3 复用）
+  const roleSkills = new Map();
+  for (const layer of Object.values(layers)) {
+    for (const role of layer?.roles ?? []) {
+      roleSkills.set(role, layer?.skills?.[role]);
+    }
+  }
+
+  // 视图 1：正向自洽
+  for (const [layerName, layer] of Object.entries(layers)) {
+    for (const role of layer?.roles ?? []) {
+      const skills = layer?.skills?.[role];
+      if (!Array.isArray(skills) || skills.length === 0) {
+        missing.push('layers.' + layerName + '.skills.' + role + ' missing or empty');
+        continue;
+      }
+      for (const s of skills) {
+        if (!skillCatalog.has(s)) missing.push('layers.' + layerName + '.skills.' + role + ': skill "' + s + '" not resolvable');
+      }
+    }
+  }
+
+  // 视图 2：反向对齐 jiufeng-team 手册表（manager 豁免）
+  for (const role of REQUIRED_ROLES) {
+    if (!roleSkills.has(role)) {
+      missing.push('required role "' + role + '" not present in assembly roles');
+    } else if (!Array.isArray(roleSkills.get(role)) || roleSkills.get(role).length === 0) {
+      missing.push('required role "' + role + '" has empty skills');
+    }
+  }
+
+  // 视图 3：blindReview 扩展（默认不启用 → 零影响）
+  const br = assembly?.extensions?.blindReview;
+  if (br?.enabled === true) {
+    for (const role of BLIND_REVIEW_ROLES) {
+      if (!roleSkills.has(role)) {
+        missing.push('blindReview: role "' + role + '" not present in assembly roles');
+      } else if (!Array.isArray(roleSkills.get(role)) || roleSkills.get(role).length === 0) {
+        missing.push('blindReview: role "' + role + '" has empty skills');
+      }
+    }
+    const templates = br.templates;
+    if (templates === null || typeof templates !== 'object') {
+      missing.push('blindReview: templates object missing');
+    } else {
+      for (const k of BLIND_REVIEW_TEMPLATE_KEYS) {
+        if (!(k in templates)) missing.push('blindReview: template "' + k + '" missing');
+      }
+    }
+  }
+
+  return { ok: missing.length === 0, missing };
+}

package/lib/assembly.js

@@ -0,0 +1,41 @@
+/*
+Copyright (C) 2025-2026 Punky
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as
+published by the Free Software Foundation, either version 3 of the
+License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program. If not, see <https://www.gnu.org/licenses/>.
+*/
+
+// 可插拔装配数据（设计 §12.1/§14.2/§15.3 N7）：team → layer → role → skills
+// 引擎只认 "role 契约 + skill 前缀" 通用格式，不感知 team；非 jiufeng 团队 = 换装配（外部路径 config.assembly 或自定义 resolveAssembly）
+export const DEFAULT_ASSEMBLY = {
+  team: 'jiufeng',
+  layers: {
+    plan: {
+      roles: ['coordinator', 'designer'],
+      skills: { coordinator: ['dev-planner'], designer: ['dev-designer', 'spec-writing', 'design-an-interface'] },
+    },
+    exec: {
+      roles: ['coder', 'tester'],
+      skills: { coder: ['dev-coder', 'efficient-edit', 'codebase-design'], tester: ['dev-tester'] },
+    },
+    audit: {
+      roles: ['reviewer', 'supervisor', 'doc-manager'],
+      skills: { reviewer: ['code-review-guideline', 'report-blind-audit'], supervisor: ['report-blind-audit', 'archive'], 'doc-manager': ['doc-generator', 'doc-update'] },
+    },
+  },
+};
+
+export function resolveAssembly(team, configAssembly = null) {
+  if (configAssembly) return configAssembly;
+  return team === 'jiufeng' ? DEFAULT_ASSEMBLY : null;
+}

package/lib/assets.js

@@ -0,0 +1,103 @@
+/*
+Copyright (C) 2025-2026 Punky
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as
+published by the Free Software Foundation, either version 3 of the
+License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program. If not, see <https://www.gnu.org/licenses/>.
+*/
+
+// 资产同步：把包内 presets/ 与 skills/ 同步到用户目录（参照 dsh-liangshen 语义）
+// 幂等：目标目录字节一致则跳过（current），否则整体覆盖（synced）；只动插件自有目录，不碰用户其他预设/技能。
+import { existsSync, mkdirSync, cpSync, rmSync, readdirSync, statSync, readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join, relative } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const MTIME_TOLERANCE_MS = 1000
+
+/** 包根目录（lib/assets.js -> 包根）。 */
+export function packageRoot() {
+  return fileURLToPath(new URL('../', import.meta.url))
+}
+
+function filesUnder(root) {
+  const out = []
+  const walk = (dir) => {
+    for (const entry of readdirSync(dir)) {
+      const p = join(dir, entry)
+      if (statSync(p).isDirectory()) walk(p)
+      else out.push(p)
+    }
+  }
+  walk(root)
+  return out
+}
+
+/** 文件字节一致性（size + mtime 容差快速否定，等价字节比对兜底）。 */
+function sameFile(a, b) {
+  const sa = statSync(a)
+  const sb = statSync(b)
+  if (sa.size !== sb.size) return false
+  if (Math.abs(sa.mtimeMs - sb.mtimeMs) > MTIME_TOLERANCE_MS) return false
+  return readFileSync(a).equals(readFileSync(b))
+}
+
+/** 目录幂等同步：'synced'（已写入/覆盖）| 'current'（已是最新）。 */
+export function syncDir(sourceDir, targetDir) {
+  if (existsSync(targetDir) && !statSync(targetDir).isDirectory()) {
+    rmSync(targetDir, { recursive: true, force: true })
+  }
+  if (!existsSync(targetDir)) {
+    cpSync(sourceDir, targetDir, { recursive: true, preserveTimestamps: true })
+    return 'synced'
+  }
+  for (const file of filesUnder(sourceDir)) {
+    const dest = join(targetDir, relative(sourceDir, file))
+    if (!existsSync(dest) || !sameFile(file, dest)) {
+      rmSync(targetDir, { recursive: true, force: true })
+      cpSync(sourceDir, targetDir, { recursive: true, preserveTimestamps: true })
+      return 'synced'
+    }
+  }
+  return 'current'
+}
+
+/**
+ * 同步预设与技能到用户目录。
+ * @param opts.home - 用户主目录（测试可注入）；缺省 homedir()。
+ * @param opts.packageRoot - 包根（测试可注入）；缺省按 import.meta.url 解析。
+ * @returns [{asset, status: 'synced'|'current'|'missing-source'|'failed', error?}]
+ */
+export function syncAssets(opts = {}) {
+  const home = opts.home ?? homedir()
+  const root = opts.packageRoot ?? packageRoot()
+  const jobs = [
+    { rel: 'presets/jiufeng', target: join(home, '.dsh', '.agent-presets', 'jiufeng') },
+    { rel: 'skills/jiufeng-team', target: join(home, '.agents', 'skills', 'jiufeng-team') },
+  ]
+  const results = []
+  for (const job of jobs) {
+    const src = join(root, job.rel)
+    if (!existsSync(src)) {
+      results.push({ asset: job.rel, status: 'missing-source' })
+      continue
+    }
+    try {
+      mkdirSync(dirname(job.target), { recursive: true })
+      const status = syncDir(src, job.target)
+      results.push({ asset: job.rel, status })
+    } catch (error) {
+      results.push({ asset: job.rel, status: 'failed', error: error instanceof Error ? error.message : String(error) })
+    }
+  }
+  return results
+}

package/lib/bridge/trajectory.js

@@ -0,0 +1,202 @@
+/*
+Copyright (C) 2025-2026 Punky
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as
+published by the Free Software Foundation, either version 3 of the
+License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program. If not, see <https://www.gnu.org/licenses/>.
+*/
+
+// bridge/trajectory.js —— C5 诊断桥接（成熟模式：LangGraph 观测层 / dsh-trajectory-governance）
+// 订阅 trajectory 异常（anomaly）→ sessionId→lane 映射 → notify（默认 notify-only，auto-fail 默认关）
+// 原则：只读消费告警载荷、不 mutate 载荷、不碰内核、不调插件任何控制面动作
+// 事件契约：'member.dispatch' 记录派发映射（既有事件通道，零新字段）；'lane.anomaly' 记录异常证据；broadcast 提示 Manager
+import { join } from 'node:path';
+import { TRAJECTORY_DEFAULTS } from '../schema.js';
+import { readCapability } from '../assembly/schema.js'; // P1-01：装配开关经注册表 default 缺省合并
+
+const ANOMALY_EVENT = 'trajectory/anomaly'; // 首选通道：同运行时实时订阅（Cordis 总线事件）
+const DISPATCH_EVENT = 'member.dispatch';   // 派发时记录 worker 会话 id（桥接器 recordDispatch 写入）
+const ANOMALY_RECORD = 'lane.anomaly';      // 异常留痕事件（batch.events，面板可见）
+const MAILBOX_KIND = 'anomaly';             // broadcast 消息 kind
+
+// 装配开关（P1-01：缺省默认开——readCapability 合并注册表 default {enabled:true}；
+//   显式 capabilities.trajectory.enabled:false 可关，false 时桥接不挂载，零运行时开销）
+export function isTrajectoryEnabled(config) {
+  return readCapability(config, 'trajectory')?.enabled === true;
+}
+
+export function createTrajectoryBridge(ctx, deps) {
+  const { store, config = {}, mailbox } = deps;
+  const trajCfg = config?.capabilities?.trajectory ?? {};
+  const failConfidence = typeof trajCfg.failConfidence === 'number'
+    ? trajCfg.failConfidence
+    : TRAJECTORY_DEFAULTS.failConfidence;
+
+  // sessionId(worker 会话) → { sessionId, batchId, lane }；
+  // 派发时经 recordDispatch 记录；进程重启后从批次事件重建（幂等）
+  const laneBySession = new Map();
+  let pollTimer = null;
+  let lastPollSince = 0;
+  let subscribed = false;
+  let detach = null; // ctx.on 返回的退订函数（若存在）
+
+  function mailboxRootOf(sessionId, batchId) {
+    // 与 tools/mailbox-tools.js boxRoot 同源：<root>/sessions/<sessionId>/mailbox/<batchId>
+    return join(store.sessionsDir, sessionId, 'mailbox', batchId);
+  }
+
+  // 重启重建：扫全部批次事件，幂等（重复调用只覆盖不膨胀）
+  function rebuildFromEvents() {
+    let n = 0;
+    for (const { sessionId, batchId } of store.listAllBatches()) {
+      const batch = store.readBatch(sessionId, batchId);
+      if (!batch?.events) continue;
+      for (const ev of batch.events) {
+        if (ev.type === DISPATCH_EVENT && ev.workerSessionId && ev.lane) {
+          laneBySession.set(ev.workerSessionId, { sessionId, batchId, lane: ev.lane });
+          n++;
+        }
+      }
+    }
+    return n;
+  }
+
+  // 派发记录（member_status → running 派发时的 worker 会话 id 落事件；零新字段，store.appendEvent 既有通道）
+  function recordDispatch({ sessionId, batchId, lane, workerSessionId }) {
+    if (!sessionId || !batchId || !lane || !workerSessionId) {
+      throw new Error('recordDispatch: sessionId/batchId/lane/workerSessionId 均必填');
+    }
+    store.appendEvent(sessionId, batchId, DISPATCH_EVENT, { lane, workerSessionId });
+    laneBySession.set(workerSessionId, { sessionId, batchId, lane });
+    return { ok: true, workerSessionId, batchId, lane };
+  }
+
+  // 只读快照：sessionId → { sessionId, batchId, lane }（gate_status 可选 advisory 展示用，不改门禁语义）
+  function mapping() {
+    const out = {};
+    for (const [k, v] of laneBySession) out[k] = { ...v };
+    return out;
+  }
+
+  // notify（默认 notify-only）：lane.anomaly 事件 + broadcast 提示 Manager；不自动结算（Manager 按纪律裁决）
+  // 注：store.newEvent 展开为 { ts, type, ...fields }——载荷若含顶层 type 会覆盖事件类型（store.js:56-58），
+  //     故 AnomalyAlert 载荷嵌套于 alert 字段（载荷原样保留，事件 type 恒为 lane.anomaly）
+  function notify(hit, alert) {
+    const { sessionId, batchId, lane } = hit;
+    const { anomalyId, type, confidence, severity, message } = alert;
+    store.appendEvent(sessionId, batchId, ANOMALY_RECORD, { lane, alert: { anomalyId, type, confidence, severity, message } });
+    mailbox.send(mailboxRootOf(sessionId, batchId), { type: 'broadcast' }, {
+      kind: MAILBOX_KIND,
+      anomalyId, type, confidence, severity, message,
+      sessionId, batchId, lane,
+      ts: new Date().toISOString(),
+    }, { from: 'trajectory-bridge' });
+  }
+
+  // auto-fail 开关（默认关）：仅 loop_deadlock 且 confidence ≥ 阈值（可配）→ member_settle failed 终态结算
+  // 不自动重试、不自动开新批次、不调插件 fork/auto-stop；settle 判定权仍在 Manager/门禁
+  function maybeAutoFail(hit, alert) {
+    const { sessionId, batchId, lane } = hit;
+    const { anomalyId, type, confidence, message } = alert;
+    if (trajCfg.autoFail !== true) return false;
+    if (type !== 'loop_deadlock') return false;
+    if (confidence < failConfidence) return false;
+    try {
+      store.setMember(sessionId, batchId, lane, 'failed',
+        `anomalyId=${anomalyId}, 证据摘要(type=${type}, confidence=${confidence}${message ? ', ' + message : ''})`);
+      return true;
+    } catch (e) {
+      // 状态机不合法（lane 非 running/review）→ 跳过自动结算，notify 证据已留
+      ctx.logger?.warn?.('[trajectory] auto-fail skipped: ' + String(e?.message ?? e));
+      return false;
+    }
+  }
+
+  // 告警载荷归一化（AnomalyAlert 契约：anomalyId/sessionId/type/confidence/severity/message）
+  function normalizeAlert(raw) {
+    const confidence = Number(raw?.confidence);
+    return {
+      anomalyId: raw?.anomalyId ?? ('anomaly-' + Date.now()),
+      sessionId: raw?.sessionId ?? null,
+      type: raw?.type ?? 'unknown',
+      confidence: Number.isFinite(confidence) ? confidence : 0,
+      severity: raw?.severity ?? 'warning',
+      message: raw?.message ?? '',
+    };
+  }
+
+  // 异常入口：反查 lane → notify（+ 可选 auto-fail）；未映射/无 sessionId → 静默降级（不报错不轮询）
+  function handleAnomaly(rawAlert) {
+    const alert = normalizeAlert(rawAlert);
+    if (!alert.sessionId) {
+      ctx.logger?.warn?.('[trajectory] anomaly without sessionId, dropped');
+      return { routed: false, reason: 'no-session' };
+    }
+    const hit = laneBySession.get(alert.sessionId);
+    if (!hit) {
+      ctx.logger?.warn?.('[trajectory] unmapped session: ' + alert.sessionId);
+      return { routed: false, reason: 'unmapped' };
+    }
+    notify(hit, alert);
+    const autoFailed = maybeAutoFail(hit, alert);
+    return { routed: true, batchId: hit.batchId, lane: hit.lane, autoFailed };
+  }
+
+  // fallback：HTTP 轮询 /api/alerts?since=（可配，默认关；插件未装/无事件时静默降级）
+  async function pollAlerts() {
+    const baseUrl = trajCfg.poll?.baseUrl;
+    if (!baseUrl) return;
+    try {
+      const res = await fetch(baseUrl + '/api/alerts?since=' + lastPollSince);
+      if (!res.ok) return;
+      const alerts = await res.json();
+      if (Array.isArray(alerts)) {
+        for (const a of alerts) handleAnomaly(a);
+        lastPollSince = Date.now();
+      }
+    } catch (e) {
+      ctx.logger?.warn?.('[trajectory] poll failed (silent degrade): ' + String(e?.message ?? e));
+    }
+  }
+
+  function start() {
+    rebuildFromEvents(); // 幂等：重启后从批次事件重建映射
+    if (typeof ctx?.on === 'function') {
+      const handler = (a) => {
+        try { handleAnomaly(a); } catch (e) { ctx.logger?.warn?.('[trajectory] handler error: ' + String(e?.message ?? e)); }
+      };
+      detach = ctx.on(ANOMALY_EVENT, handler);
+      subscribed = true;
+    }
+    if (trajCfg.poll?.enabled === true) {
+      const intervalMs = trajCfg.poll?.intervalMs ?? TRAJECTORY_DEFAULTS.poll.intervalMs;
+      pollTimer = setInterval(() => { pollAlerts().catch(() => {}); }, intervalMs);
+    }
+    return { subscribed, poll: trajCfg.poll?.enabled === true };
+  }
+
+  function stop() {
+    if (subscribed && detach) {
+      try { detach(); } catch {}
+    }
+    if (subscribed && typeof ctx?.off === 'function') {
+      // 兼容 ctx.on 未返回退订函数、仅提供 off 的宿主
+      try { ctx.off(ANOMALY_EVENT); } catch {}
+    }
+    subscribed = false;
+    detach = null;
+    if (pollTimer) { clearInterval(pollTimer); pollTimer = null; }
+    return { stopped: true };
+  }
+
+  return { start, stop, mapping, recordDispatch, handleAnomaly, rebuildFromEvents };
+}