dsh-punky-swarm 0.3.6

package/lib/verify/gate.js

@@ -0,0 +1,161 @@
+/*
+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/>.
+*/
+
+// verify/gate.js —— 完成闸门三态裁决（C3 成熟模式：dsh-verification CompletionGate）
+// 三态：done / failed / blocked；模式 advisory（默认只记录不拦截）/ enforce（显式装配启用则拦截）。
+// 审计消费桥接：audit lane 消费 exec 产物 + evidence → evaluateGate 产出裁决 → 裁决报告落盘为 audit
+// produce（audit/verify-verdict.md）→ Tier3 门禁照常校验该产物存在（既有 gates.js 零改动，verify 是内容层增强）。
+import { createSelectorRegistry } from './selector.js';
+import { createEvidenceRegistry } from './evidence.js';
+import { readCapability } from '../assembly/schema.js'; // P1-01：装配开关经注册表 default 缺省合并
+
+// 状态劣化序：done < failed < blocked（blocked 需人工，优先级最高）；null 视为最低（-1）
+function worse(a, b) {
+  const rank = { done: 0, failed: 1, blocked: 2 };
+  const ra = a == null ? -1 : rank[a];
+  const rb = b == null ? -1 : rank[b];
+  return rb > ra ? b : a;
+}
+
+// 完成闸门三态裁决（纯函数）：
+//   acBindings: [{ acId, selectorRef }]（AC 清单经 freeze+bind 后的形态）
+//   evidence:   { bindingsFor(acId) => [{selectorRef, blobKey}], readBlob(key) => evidence }（注册表+store 适配）
+//   mode:       'advisory'（默认，只记录不拦截）| 'enforce'（拦截，status!==done 时 intercepted=true）
+// 裁决规则：缺绑定 → failed「Missing evidence for AC x」；绑定但证据不满足 → failed+detail；
+//   损坏/截断 blob（读校验 fail closed）→ blocked（需人工）；证据为工具错误 → failed；至少一条成功证据 → done。
+export function evaluateGate({ acBindings = [], evidence = null, mode = 'advisory' }) {
+  if (!Array.isArray(acBindings)) throw new Error('evaluateGate: acBindings must be an array');
+  if (mode !== 'advisory' && mode !== 'enforce') throw new Error('evaluateGate: mode must be advisory|enforce');
+  if (typeof evidence?.bindingsFor !== 'function' || typeof evidence?.readBlob !== 'function') {
+    throw new Error('evaluateGate: evidence must provide bindingsFor(acId) and readBlob(key)');
+  }
+  const defects = [];
+  let status = 'done';
+
+  for (const ac of acBindings) {
+    if (!ac || typeof ac.acId !== 'string') continue;
+    const bound = evidence.bindingsFor(ac.acId);
+    if (bound.length === 0) {
+      defects.push({ acId: ac.acId, selectorRef: ac.selectorRef ?? null, code: 'MISSING_EVIDENCE', detail: 'Missing evidence for AC ' + ac.acId });
+      status = worse(status, 'failed');
+      continue;
+    }
+    let acStatus = null;
+    for (const b of bound) {
+      let blob;
+      try {
+        blob = evidence.readBlob(b.blobKey);
+      } catch (e) {
+        // 损坏 blob fail closed → 需人工（不可用疑似损坏的内容做裁决）
+        defects.push({ acId: ac.acId, selectorRef: b.selectorRef, code: 'EVIDENCE_UNREADABLE', detail: String(e?.message ?? e) });
+        acStatus = worse(acStatus, 'blocked');
+        continue;
+      }
+      if (blob.truncated === true) {
+        defects.push({ acId: ac.acId, selectorRef: b.selectorRef, code: 'EVIDENCE_TRUNCATED', detail: 'evidence over ' + (blob.note ?? 'limit') + ' — needs human review' });
+        acStatus = worse(acStatus, 'blocked');
+        continue;
+      }
+      if (blob.ok === false) {
+        defects.push({ acId: ac.acId, selectorRef: b.selectorRef, code: 'EVIDENCE_ERROR', detail: 'tool ' + blob.tool + ' failed: ' + (blob.error ?? 'unknown') });
+        acStatus = worse(acStatus, 'failed');
+        continue;
+      }
+      acStatus = worse(acStatus, 'done'); // 至少一条成功证据
+    }
+    if (acStatus) status = worse(status, acStatus);
+  }
+
+  // advisory 只记录不拦截；enforce 显式拦截并返回缺陷清单
+  const intercepted = mode === 'enforce' && status !== 'done';
+  return {
+    status,
+    defects,
+    mode,
+    intercepted,
+    message: intercepted
+      ? 'verify gate blocked: ' + status + ' (' + defects.length + ' defect(s)) — see defects'
+      : (defects.length ? 'verify gate recorded ' + defects.length + ' defect(s) in advisory mode' : 'verify gate passed'),
+  };
+}
+
+// 审计消费桥接主入口：AC 清单 × 捕获台账 → 绑定 → 三态裁决。
+//   acList:  [{ id, tool, args }]（audit lane 任务包携带，源自 spec.md「## 验收标准」）
+//   ledger:  捕获台账条目（readLedger 输出，含 selectorKey/blobKey）
+//   readBlob: evidence store 的 readBlob（注入，保持 gate 纯逻辑可测）
+//   mode:    advisory | enforce
+export function evaluateAcEvidence({ acList = [], ledger = [], readBlob, mode = 'advisory' }) {
+  const selectors = createSelectorRegistry();
+  selectors.bindAll(acList); // 重复 selector / 重复 AC 在此拒绝（V1）
+  const registry = createEvidenceRegistry();
+  const acBindings = selectors.list().map((s) => ({ acId: s.acId, selectorRef: s.selectorRef }));
+  for (const entry of ledger) {
+    const acId = selectors.matchByKey(entry.selectorKey); // exact-only 全等匹配
+    if (acId) registry.bindEvidence(acId, acId + ':' + entry.selectorKey, entry.blobKey);
+  }
+  const result = evaluateGate({
+    acBindings,
+    evidence: { bindingsFor: (id) => registry.bindingsFor(id), readBlob },
+    mode,
+  });
+  return { acBindings, bindings: registry, result };
+}
+
+// 裁决报告落盘格式（预留：audit/verify-verdict.md）——audit lane 写为 produce，Tier3 校验其存在
+export function renderVerdictReport({ batchId, sessionId, acList = [], result, evaluatedAt = new Date().toISOString() }) {
+  const lines = [
+    '# verify 裁决报告（audit/verify-verdict.md）',
+    '',
+    '- 批次：' + batchId + ' ｜ 会话：' + sessionId,
+    '- 评估时间：' + evaluatedAt,
+    '- 模式：' + (result?.mode ?? 'advisory') + ' ｜ 裁决：' + (result?.status ?? 'done') + (result?.intercepted ? '（已拦截）' : ''),
+    '',
+    '## 验收标准 × 证据裁决',
+    '',
+    '| AC | 工具 | 裁决 | 缺陷 |',
+    '|---|---|---|---|',
+    ...acList.map((ac) => {
+      const d = (result?.defects ?? []).find((x) => x.acId === ac.id);
+      return '| ' + ac.id + ' | ' + (ac.tool ?? '') + ' | ' + (d ? d.code : 'done') + ' | ' + (d ? d.detail.replace(/\|/g, '\\|') : '') + ' |';
+    }),
+    '',
+    '## 缺陷清单',
+    '',
+    ...((result?.defects ?? []).length
+      ? result.defects.map((d) => '- `' + d.acId + '` [' + d.code + '] ' + d.detail)
+      : ['- 无']),
+    '',
+  ];
+  return lines.join('\n');
+}
+
+// 完成闸门工厂：config.capabilities.verify.{enabled, mode}——P1-01 缺省默认开（readCapability 合并
+//   注册表 default VERIFY_DEFAULTS {enabled:true, mode:'advisory'}）；显式 enabled:false 时 evaluate
+//   返回 skipped（无裁决、零运行时开销）；enforce 仅显式装配启用。
+export function createCompletionGate({ config = {}, mode } = {}) {
+  const vcfg = readCapability(config, 'verify') ?? {};
+  const enabled = vcfg.enabled === true;
+  const effMode = mode ?? vcfg.mode ?? 'advisory';
+  return {
+    enabled,
+    mode: effMode,
+    evaluate(args) {
+      if (!enabled) return { status: 'done', defects: [], mode: effMode, skipped: true, intercepted: false };
+      return evaluateGate({ ...args, mode: effMode });
+    },
+  };
+}

package/lib/verify/mount.js

@@ -0,0 +1,48 @@
+/*
+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/>.
+*/
+
+// verify/mount.js —— verify 引擎级接线（集成注意项 1 收口）
+// index.js 的可测缝：capabilities.verify.enabled 门控挂 installEvidenceCapture（tools/post-execute 证据捕获），
+//   返回 { installed, count, dispose }；enabled=false 零运行时开销；ctx.on 缺失静默降级（宿主能力缺失不炸）。
+// 边界：createCompletionGate 与 audit lane 显式 DI 消费路径一字不动（gate.js 零改动）——本文件只做引擎级捕获装配，
+//   裁决/拦截语义仍在 gate.js（advisory 只记录 / enforce 拦截），捕获侧只落 blob + ledger。
+// TBD-4 核实（2026-08-28）：本文件与 lib/state/gates.js（批次内层间门禁）零耦合——不 import 亦不被其
+//   import；verify/gate.js 的 createCompletionGate / evaluateAcEvidence 消费点 = audit lane 显式 DI 注入
+//   （{acList, ledger, readBlob}）+ 装配层门控（index.js mountVerify 挂捕获 hook；assembly/schema.js verify
+//   键注册表 consumers 标注），无共享调用路径，无需改动任何调用代码。
+import { installEvidenceCapture } from './evidence.js';
+// resolveVerifyConfig/VERIFY_DEFAULTS 统一归口 lib/schema.js（注册表 default：
+//   assembly-schema lane 落地同款实现，本文件不再自包含双实现——语义一致，消费路径单点，防未来字段漂移）
+import { VERIFY_DEFAULTS, resolveVerifyConfig } from '../schema.js';
+export { VERIFY_DEFAULTS, resolveVerifyConfig };
+
+// 引擎级捕获挂载（index.js apply 内调用）：
+//   enabled=true + ctx.on 可用 → installEvidenceCapture 订阅 tools/post-execute（pass-through 不断链）→ installed:true；
+//   enabled=false（默认）→ installed:false / reason:'disabled'，不注册任何监听，零副作用；
+//   ctx.on 缺失 → installed:false / reason:'ctx.on unavailable'，静默降级不 throw。
+export function mountVerify(ctx, { root, config, logger } = {}) {
+  const cfg = resolveVerifyConfig(config);
+  const log = logger ?? ctx?.logger ?? null;
+  const inert = (reason) => ({ installed: false, reason, mode: cfg.mode, count: () => 0, dispose() {} });
+  if (cfg.enabled !== true) return inert('disabled');
+  if (!root || typeof ctx?.on !== 'function') return inert('ctx.on unavailable');
+  const cap = installEvidenceCapture(ctx, { root, enabled: true });
+  if (cap.installed) {
+    log?.info?.('[dsh-punky-swarm] verify capability enabled: post-execute evidence capture mounted (mode=' + cfg.mode + ')');
+  }
+  return { installed: cap.installed, count: cap.count, mode: cfg.mode, dispose() { cap.dispose(); } };
+}

package/lib/verify/selector.js

@@ -0,0 +1,101 @@
+/*
+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/>.
+*/
+
+// verify/selector.js —— AC×selector 冻结（C3 成熟模式：dsh-verification selector 冻结，exact-only）
+// 纯逻辑模块（无 IO、无工具面）：canonicalizeArgs（键递归排序）+ stableHash（sha256 前缀 12）。
+// 服务端权威语义：裁决侧按 identity+tool+argsHash 全等绑定，模型提交值一律忽略（不参与匹配）。
+// AC 声明来源（零核心侵入）：批次 plan 产物 spec.md「## 验收标准」章节 —— audit lane 任务包携带
+// AC 清单 [{id, tool, args}]，不扩展 wave-plan task schema（wave-plan.js 零改动）。
+// TBD-4 核实（2026-08-28）：本文件与 lib/state/gates.js（批次内层间门禁）零耦合——不 import 亦不被
+//   其 import；verify 子系统（selector/mount/gate/evidence）独立成链，裁决纯函数经 DI 由 audit lane
+//   注入消费（evaluateAcEvidence），装配层仅挂载捕获 hook（mountVerify）与注册表门控，无共享调用路径。
+import { createHash } from 'node:crypto';
+
+// 递归规范化参数：对象键递归排序（{a:1,b:2} 与 {b:2,a:1} 同哈希）；数组保序；undefined 剔除；
+// 标量原样（字符串/数字/布尔/null）。用于哈希与全等匹配的规范形态。
+export function canonicalizeArgs(value) {
+  if (Array.isArray(value)) return value.map(canonicalizeArgs);
+  if (value !== null && typeof value === 'object') {
+    const out = {};
+    for (const k of Object.keys(value).sort()) {
+      const v = canonicalizeArgs(value[k]);
+      if (v !== undefined) out[k] = v;
+    }
+    return out;
+  }
+  return value;
+}
+
+// 稳定哈希：sha256 → 12 位 hex 前缀（同输入恒等，键序无关）
+export function stableHash(value) {
+  return createHash('sha256').update(JSON.stringify(canonicalizeArgs(value))).digest('hex').slice(0, 12);
+}
+
+// AC×selector 冻结：同一 (acId, tool, args) 两次冻结 → selectorRef 稳定；参数键序无关；
+// argsHash 只含 tool+args（跨 acId 可比较），selectorRef = acId:argsHash（可回溯到 AC）。
+export function freezeSelector({ acId, tool, args = {} }) {
+  if (typeof acId !== 'string' || !acId.length) throw new Error('freezeSelector: acId required');
+  if (typeof tool !== 'string' || !tool.length) throw new Error('freezeSelector: tool required');
+  const canonical = canonicalizeArgs(args);
+  const argsHash = stableHash({ tool, args: canonical });
+  const selectorRef = acId + ':' + argsHash;
+  return { acId, tool, args: canonical, argsHash, selectorRef };
+}
+
+// AC→selector 绑定注册表（exact-only）：一 selector 只绑一个 AC，重复绑定拒绝。
+// audit lane 在裁决前置入 AC 清单；捕获侧按 argsHash 全等反查命中的 AC。
+export function createSelectorRegistry() {
+  const byAc = new Map();   // acId -> frozen selector
+  const byKey = new Map();  // argsHash -> acId（exact-only 全等身份，无模糊匹配）
+
+  return {
+    // 绑定单个 AC：{id, tool, args}（audit lane AC 清单逐项调用）；重复 AC / 重复 selector 拒绝
+    bindSelector(acId, selector) {
+      if (byAc.has(acId)) throw new Error('duplicate AC binding: ' + acId);
+      if (!selector || typeof selector.tool !== 'string') throw new Error('bindSelector: tool required for ' + acId);
+      const frozen = freezeSelector({ acId, tool: selector.tool, args: selector.args ?? {} });
+      if (byKey.has(frozen.argsHash)) {
+        throw new Error('duplicate selector: ' + frozen.argsHash + ' already bound to AC ' + byKey.get(frozen.argsHash));
+      }
+      byKey.set(frozen.argsHash, acId);
+      byAc.set(acId, frozen);
+      return frozen;
+    },
+
+    // 批量绑定（AC 清单形态 [{id, tool, args}]），返回冻结后的 selector 列表
+    bindAll(acList = []) {
+      if (!Array.isArray(acList)) throw new Error('bindAll: acList must be an array');
+      return acList.map((ac) => this.bindSelector(ac.id, { tool: ac.tool, args: ac.args }));
+    },
+
+    has(acId) { return byAc.has(acId); },
+    get(acId) { return byAc.get(acId) ?? null; },
+    size() { return byAc.size; },
+    list() { return [...byAc.values()]; },
+    clear() { byAc.clear(); byKey.clear(); },
+
+    // exact-only 匹配（捕获侧/审计侧用）：tool+args 全等 → 命中的 acId；未命中 → null（无模糊）
+    match(tool, args) {
+      const key = stableHash({ tool, args: canonicalizeArgs(args) });
+      return byKey.get(key) ?? null;
+    },
+    // 按已算好的 argsHash 反查（台账条目带 selectorKey 时免重算）
+    matchByKey(argsHash) {
+      return typeof argsHash === 'string' ? (byKey.get(argsHash) ?? null) : null;
+    },
+  };
+}

package/lib/watch/lane-heartbeat.js

@@ -0,0 +1,333 @@
+/*
+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/>.
+*/
+
+// lane-heartbeat：lane 过期检测引擎（能力补全 C1，watch 域，新建）
+// 成熟模式：dsh-plugin-heartbeat 退避/硬停引擎（退避/硬停机制）
+// 语义：running lane 无活动 → 退避档位追问（默认 10→20→30 分钟，冷场越久间隔越长）→
+//       连续 N 拍（默认 3）无活动 → appendEvent('lane.stalled', {lane, missed})，停止追问。
+//       只标记不自动处置（Manager/Leader 人审），不新增成员状态（stalled 用事件表达，不碰
+//       schema.js MEMBER_STATES/MEMBER_TRANSITIONS——写事件零侵入，加状态要动 schema/测试/面板/complete gate）。
+// 依赖注入：deps.store（readBatch/appendEvent/listSessions/listBatches/artifactsDirOf）
+//                          deps.mailbox（comms/mailbox.js：send/readUnacked，追问投递与 pending 探测）
+//                          deps.config（capabilities.watch：enabled/intervalsMinutes/maxMissed/scanIntervalMinutes/probeTemplate）
+//                          deps.root（可选，mailbox 根；缺省由 store.sessionsDir 推导）
+//                          deps.now（可选，时钟注入，测试用；缺省 Date.now）
+// 本文件仅导出引擎与工具定义；lane_heartbeat 工具的组装（lane-tools.js/register.js）
+// 组装进 lane-tools.js（避免与 lane-tools 主文件耦合）；本模块只动
+// watch/ 新域 + index.js 挂载 + schema.js watch 配置键 + cordis.patch.yml 注释。
+import { join, dirname } from 'node:path';
+import { statSync } from 'node:fs';
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { resolveWatchConfig, WATCH_DEFAULTS } from '../schema.js';
+import { sessionOf, TEXT_OUTPUT } from '../tools/shared.js'; // P2-01：watch 域不再 import tools/core（共享辅助下沉零依赖 shared.js）
+import { isAbsPath } from '../state/constants.js'; // P1-07 单点（原 :77 内联正则收敛）
+import { findTask } from '../state/task-utils.js'; // P1-04 单点（原 :69 本地定义删除）
+// R-01/R-07 收敛：lane.stalled 事件字面量（发端 :188 + 读端 :101/:139）改引 EVT 常量单点
+import * as EVT from '../state/event-types.js';
+
+// 退避档位（分钟 → ms，单调化钳制）：档位单调不减，冷场越久追问间隔越长
+export function buildSchedule(intervalsMinutes) {
+  const src = Array.isArray(intervalsMinutes) && intervalsMinutes.length > 0
+    ? intervalsMinutes
+    : WATCH_DEFAULTS.intervalsMinutes;
+  const list = src.map((m) => {
+    const n = Number(m);
+    return Number.isFinite(n) && n >= 0 ? n * 60_000 : 0;
+  });
+  for (let i = 1; i < list.length; i++) list[i] = Math.max(list[i], list[i - 1]);
+  return list;
+}
+
+export function createLaneHeartbeat({ store, mailbox, config, root, now }) {
+  const cfg = resolveWatchConfig(config);
+  const schedule = buildSchedule(cfg.intervalsMinutes);
+  const hardStop = cfg.maxMissed; // 硬停拍数：连续 N 拍无活动 → stalled
+  const clock = typeof now === 'function' ? now : () => Date.now();
+  const engineRoot = root ?? (store?.sessionsDir ? dirname(store.sessionsDir) : null);
+  // 状态表 Map<laneKey, { lastActivityAt, lastSeenTs, lastProbeAt, missedCount, stalled, pendingProbeId }>
+  // laneKey = `${sessionId}/${batchId}/${lane}`
+  const state = new Map();
+  let disposed = false;
+
+  function mailboxRootOf(sessionId, batchId) {
+    if (!engineRoot) throw new Error('lane-heartbeat: no root (pass deps.root or store.sessionsDir)');
+    return join(engineRoot, 'sessions', sessionId, 'mailbox', batchId);
+  }
+  const laneKeyOf = (sessionId, batchId, lane) => `${sessionId}/${batchId}/${lane}`;
+
+  // 产物解析（自持只读实现，与 gates.js resolveArtifact/fileExistsNonEmpty 同源模式，避免循环依赖）
+  function resolveArtifact(sessionId, batchId, rel) {
+    const base = store.artifactsDirOf(sessionId, batchId);
+    return isAbsPath(rel) ? rel : join(base, rel);
+  }
+
+  function freshEntry(nowTs) {
+    return {
+      lastActivityAt: nowTs,
+      lastSeenTs: nowTs,
+      lastProbeAt: nowTs, // 新派发 lane 先给 base 档宽限，不立即追问（重派 running 计时重置语义）
+      missedCount: 0,
+      stalled: false,
+      pendingProbeId: null,
+    };
+  }
+  function resetEntry(entry, nowTs) {
+    entry.lastActivityAt = nowTs;
+    entry.lastSeenTs = nowTs;
+    entry.lastProbeAt = nowTs;
+    entry.missedCount = 0;
+    entry.stalled = false;
+    entry.pendingProbeId = null;
+  }
+
+  // ---- 活动判定（三信号任一，防「长任务无产出误判」）----
+  // ① batch.events：本 lane 可归因事件比上次扫描新（lane.stalled 为引擎自写事件，排除防自重置）
+  function laneEventActivity(batch, lane, sinceTs) {
+    const evs = batch.events ?? [];
+    for (let i = evs.length - 1; i >= 0; i--) {
+      const e = evs[i];
+      if (e.type === EVT.EVT_LANE_STALLED) continue;
+      if (e.lane === lane) {
+        const ts = Date.parse(e.ts ?? '');
+        if (Number.isFinite(ts) && ts > sinceTs) return true;
+      }
+    }
+    return false;
+  }
+  // ② outbox：该 lane outbox 目录出现未 ack 消息
+  function outboxActivity(sessionId, batchId, lane) {
+    try {
+      return mailbox.readUnacked(mailboxRootOf(sessionId, batchId), { type: 'outbox', lane }).length > 0;
+    } catch { return false; }
+  }
+  // ③ 产物 mtime：artifacts/<batchId>/ 下该 lane 声明产物（outputs/produce）mtime 变化
+  function artifactActivity(sessionId, batchId, batch, lane, sinceTs) {
+    const t = findTask(batch, lane);
+    const rels = [...(t?.outputs ?? []), ...(t?.produce ?? [])];
+    for (const rel of rels) {
+      try {
+        if (statSync(resolveArtifact(sessionId, batchId, rel)).mtimeMs > sinceTs) return true;
+      } catch { /* 不存在/不可读 → 无活动 */ }
+    }
+    return false;
+  }
+  function hasActivity(sessionId, batchId, batch, lane, sinceTs) {
+    return laneEventActivity(batch, lane, sinceTs)
+      || outboxActivity(sessionId, batchId, lane)
+      || artifactActivity(sessionId, batchId, batch, lane, sinceTs);
+  }
+
+  // 首次追踪某 lane 时把 lastSeenTs 基线对齐到「已知信号最新时间」（本 lane 事件 ts / 声明产物 mtime 的最大值）。
+  // 防时钟偏移/测试注入时钟时把历史活动误判为新鲜活动（历史事件 ts > 冷启动 nowTs 时会被误判持续活动）
+  function baselineTs(sessionId, batchId, batch, lane, nowTs) {
+    let t = nowTs;
+    const evs = batch.events ?? [];
+    for (let i = evs.length - 1; i >= 0; i--) {
+      const e = evs[i];
+      if (e.type === EVT.EVT_LANE_STALLED) continue;
+      if (e.lane === lane) {
+        const ts = Date.parse(e.ts ?? '');
+        if (Number.isFinite(ts) && ts > t) t = ts;
+      }
+    }
+    const task = findTask(batch, lane);
+    for (const rel of [...(task?.outputs ?? []), ...(task?.produce ?? [])]) {
+      try {
+        const m = statSync(resolveArtifact(sessionId, batchId, rel)).mtimeMs;
+        if (m > t) t = m;
+      } catch { /* 不存在 → 忽略 */ }
+    }
+    return t;
+  }
+
+  // 同 lane 至多 1 条 pending 追问（多拍合并语义：mailbox 无 replace → 读 inbox 未 ack 追问，存在则跳过）。
+  // 追问 ts 早于最近一次活动 → 视为已被活动满足的陈旧追问，不再当作未答拍（活动后 reset 语义）
+  function pendingProbe(sessionId, batchId, lane, sinceTs) {
+    try {
+      const items = mailbox.readUnacked(mailboxRootOf(sessionId, batchId), { type: 'inbox' });
+      for (const it of items) {
+        if (it.message?.kind !== 'probe' || it.message?.lane !== lane) continue;
+        const ts = Date.parse(it.ts ?? '');
+        if (Number.isFinite(ts) && ts < sinceTs) continue; // 陈旧追问：活动发生在它之后
+        return it;
+      }
+      return null;
+    } catch { return null; }
+  }
+
+  function probeText(lane, batchId, missed) {
+    if (cfg.probeTemplate) {
+      return cfg.probeTemplate
+        .replaceAll('{lane}', lane)
+        .replaceAll('{batchId}', batchId)
+        .replaceAll('{missed}', String(missed));
+    }
+    // 轻量追问模板：≤5 句、含 lane 标识、不调工具、不复盘全部历史
+    return [
+      `Manager 心跳：lane「${lane}」（批次 ${batchId}）已连续 ${missed} 拍无活动信号。`,
+      '请用 ≤3 句汇报当前进度或阻塞点（走 outbox）。',
+      '不调工具、不复盘全部历史。',
+      '本消息为自动追问，任何活动即重置计时。',
+    ].join('\n');
+  }
+
+  function markStalled(sessionId, batchId, lane, entry, nowTs) {
+    try {
+      store.appendEvent(sessionId, batchId, EVT.EVT_LANE_STALLED, { lane, missed: entry.missedCount });
+    } catch { /* 批次已终态/不存在等 → 忽略（下轮不再扫） */ }
+    entry.stalled = true;
+    entry.lastSeenTs = nowTs; // 自写事件不触发自身重置
+    entry.lastProbeAt = null;
+  }
+
+  // 扫描全部会话 running lane：
+  // - 仅扫 batch.phase === 'running' 且 lane === 'running'；paused/planning/终态批次、idle/终态 lane 不挂心跳
+  //   （恢复语义：running→idle 后不挂，重派 running 时以 fresh entry 重置计时）
+  function tick() {
+    if (disposed) return;
+    const nowTs = clock();
+    for (const sessionId of store.listSessions()) {
+      for (const batchId of store.listBatches(sessionId)) {
+        const batch = store.readBatch(sessionId, batchId);
+        if (!batch) continue;
+        if (batch.phase !== 'running') { dropBatchEntries(batch); continue; }
+        for (const [lane, st] of Object.entries(batch.lanes ?? {})) {
+          const laneKey = laneKeyOf(sessionId, batchId, lane);
+          if (st !== 'running') { state.delete(laneKey); continue; }
+          let entry = state.get(laneKey);
+          if (!entry) {
+            entry = freshEntry(nowTs);
+            entry.lastSeenTs = baselineTs(sessionId, batchId, batch, lane, entry.lastSeenTs);
+            state.set(laneKey, entry);
+          }
+          // 活动 → 重置回 tier0（W3）
+          if (hasActivity(sessionId, batchId, batch, lane, entry.lastSeenTs)) { resetEntry(entry, nowTs); continue; }
+          // 已 stalled：只标记，停止追问（W2）
+          if (entry.stalled) continue;
+          // 退避档位：tier = min(missedCount, len-1)，档位单调（W4）
+          const tier = Math.min(entry.missedCount, schedule.length - 1);
+          if (entry.lastProbeAt !== null && nowTs - entry.lastProbeAt < schedule[tier]) continue;
+          // 一拍 = 一次追问轮次；同 lane 至多 1 条 pending（W1），pending 存在则这一拍=已发未答
+          const pending = pendingProbe(sessionId, batchId, lane, entry.lastActivityAt);
+          if (!pending) {
+            const r = mailbox.send(mailboxRootOf(sessionId, batchId), { type: 'inbox' }, {
+              kind: 'probe',
+              lane,
+              batchId,
+              missed: entry.missedCount + 1,
+              text: probeText(lane, batchId, entry.missedCount + 1),
+            });
+            entry.pendingProbeId = r.ackId;
+          }
+          entry.missedCount += 1;
+          entry.lastProbeAt = nowTs;
+          // 硬停：连续 N 拍无活动 → lane.stalled（只标记不自动处置，不新增成员状态）
+          if (entry.missedCount >= hardStop) markStalled(sessionId, batchId, lane, entry, nowTs);
+        }
+      }
+    }
+  }
+
+  function dropBatchEntries(batch) {
+    for (const lane of Object.keys(batch.lanes ?? {})) state.delete(laneKeyOf(batch.sessionId, batch.batchId, lane));
+  }
+
+  // 只读：lastActivityAt/当前档位/missed/stalled/pendingProbeId
+  function status(laneKey) {
+    const entry = state.get(laneKey);
+    // laneKey = `${sessionId}/${batchId}/${lane}`；lane 未约束可含 '/'，按前两个斜杠定位
+    const i1 = laneKey.indexOf('/');
+    const i2 = i1 >= 0 ? laneKey.indexOf('/', i1 + 1) : -1;
+    const sessionId = i1 >= 0 ? laneKey.slice(0, i1) : null;
+    const batchId = i2 >= 0 ? laneKey.slice(i1 + 1, i2) : null;
+    const lane = i2 >= 0 ? laneKey.slice(i2 + 1) : null;
+    if (!entry) {
+      return { laneKey, tracked: false, lastActivityAt: null, tier: 0, intervalMs: schedule[0], missed: 0, stalled: false, pendingProbeId: null, lastProbeAt: null };
+    }
+    const tier = Math.min(entry.missedCount, schedule.length - 1);
+    return {
+      laneKey,
+      tracked: true,
+      sessionId,
+      batchId,
+      lane,
+      lastActivityAt: new Date(entry.lastActivityAt).toISOString(),
+      tier,
+      intervalMs: schedule[tier],
+      missed: entry.missedCount,
+      stalled: entry.stalled,
+      pendingProbeId: entry.pendingProbeId,
+      lastProbeAt: entry.lastProbeAt ? new Date(entry.lastProbeAt).toISOString() : null,
+    };
+  }
+
+  // 活动信号外部入口：missedCount=0 回 tier0
+  function reset(laneKey) {
+    const entry = state.get(laneKey);
+    if (entry) resetEntry(entry, clock());
+  }
+
+  function dispose() {
+    disposed = true;
+    state.clear();
+  }
+
+  return { tick, status, reset, dispose };
+}
+
+// lane_heartbeat 工具定义（只读查询 + 可选手动触发一拍）。
+// 组装进 lane-tools.js；enabled=false 时本工具不注册。
+// deps: { store, root, config, heartbeat? } —— heartbeat 缺省时自建（注册侧懒加载，与挂载引擎共享状态文件）
+export function createHeartbeatTools(ctx, deps = {}) {
+  if (resolveWatchConfig(deps.config).enabled !== true) return [];
+  const heartbeat = deps.heartbeat
+    ?? createLaneHeartbeat({ store: deps.store, mailbox: deps.mailbox, config: deps.config, root: deps.root });
+  return [
+    defineTool({
+      name: 'lane_heartbeat',
+      description: '查询/手动触发 lane 心跳（watch 能力 C1，只读+可选手动一拍）：返回指定批次 running lane 的过期检测状态（lastActivityAt/当前档位/missed/stalled/pendingProbeId）；beat=true 时先跑一拍扫描再返回。不改变任何成员状态（stalled 用事件表达）。enabled=false 时不注册。',
+      parameters: {
+        batchId: { type: 'string', required: true, description: '批次 ID' },
+        lane: { type: 'string', description: 'lane ID；缺省返回该批全部 running lane' },
+        session: { type: 'string', description: '批次归属会话' },
+        beat: { type: 'boolean', description: '手动触发一拍扫描（tick）后再返回状态' },
+      },
+      output: {
+        schema: { type: 'object', additionalProperties: false, properties: {
+          batchId: { type: 'string', required: true },
+          sessionId: { type: 'string', required: true },
+          lanes: { type: 'array', required: true, items: { type: 'object', additionalProperties: true } },
+        } },
+        render: (_args, value) => TEXT_OUTPUT('lane heartbeat: ' + value.lanes.length + ' lane(s)'),
+      },
+      async execute(args, exec) {
+        const sessionId = sessionOf(args, exec);
+        if (args.beat === true) heartbeat.tick();
+        const batch = deps.store.readBatch(sessionId, args.batchId);
+        if (!batch) throw new Error('batch not found: ' + args.batchId);
+        const laneIds = args.lane
+          ? [args.lane]
+          : Object.keys(batch.lanes ?? {}).filter((l) => batch.lanes[l] === 'running');
+        return {
+          batchId: args.batchId,
+          sessionId,
+          lanes: laneIds.map((l) => heartbeat.status(`${sessionId}/${args.batchId}/${l}`)),
+        };
+      },
+    }),
+  ];
+}