@yangdcm/dsh-expert-team 1.1.0

package/lib/lead-toolface.js

@@ -0,0 +1,179 @@
+// lead 工具面（A 线 · token 成本治理）· **纯函数，零宿主依赖**。
+//
+// ── 为什么要收 lead 的工具面 ────────────────────────────────────────────────
+// 对真实会话做全量遥测审计的结论（一次性脚本，未随包发布）：
+//   · lead 累积上下文的 **89%~98% 是工具结果**，其中 `read` + `bash` + `edit` 约占 **93%**；
+//     真实用户需求只占 2%~11%。
+//   · 上下文首次越过 10 万 tokens 只发生在全程 **第 1%~2% 的步**，而**越线之后**的步数
+//     贡献了 **97%** 的总 prompt 成本 —— 贵在"带着大上下文反复走"，不在"上下文变大"。
+//   · 最贵的 run 里 **lead 占该 run prompt 总量的 84%**（另一个 92%），而它 3,244 次工具调用里
+//     `subagent` 派工只有 11 次。
+// ⇒ 杠杆不是"少说话"（输出 tokens 只占总量的 0.34%），而是**让执行类工具默认不在 lead 手上**。
+//
+// ── 机制（已由宿主源码闭环证明，不是推断）────────────────────────────────
+// 给 **lead 自己的 agent scope** 施加 `agent.ctx.tools.restrict({deny})` 即可。安全性依据：
+//   `dsh-subagent.applyChildComposition` → `agentPresets.composeFrom(childCtx, parent.ctx)`
+//     → `standingMountFor(parentCtx)` = `scopeParentOf(parentAgentKey)`（= preset 常驻作用域）
+//     → `bindScopeParent(childKey, standingKey)` → `dsh-scope: scopeParents.set(childKey, standingKey)`
+//   `dsh-scope.scopeChainOf()` 沿 `scopeParents` 向上走 ⇒ `scopeChainOf(child) = [child, standing, …]`。
+//   **lead 的 agent 作用域不在子级的祖先链上** ⇒ 收 lead 不会波及角色子代理。
+//   （旁证：本 preset 的 `toolFilter: deny: [bash]`（pm/architect）走的正是同一行代码。）
+//
+// ── 本模块只做"算出该 deny 什么"，不碰宿主 ────────────────────────────────
+// 施加动作在接线处（agent setup 阶段，照宿主自己的时序），本模块保持纯函数以便单测。
+//
+// ── 两条本仓纪律，写死在返回值形状里 ──────────────────────────────────────
+//   ① **两种零必须可区分**：`deny: []` 可能是"真的没什么可收"，也可能是"我根本不知道宿主有哪些工具"。
+//      两者**不能长得一样** ⇒ 用 `status` 区分（`ready` / `nothing-to-deny` / `no-known-names`）。
+//   ② **不静默**：本该存在的名字缺席（核心工具、本平台 shell）必须进 `unexpectedAbsent` 并出声；
+//      只有"另一个平台的 shell"缺席是预期的，不当作异常。
+
+import path from 'node:path';
+
+/** 候选：lead 默认不该持有的**执行/探索**类全局工具名（真实名字取自宿主各 tool 包）。 */
+export const LEAD_DENY_CANDIDATES = Object.freeze(['bash', 'pwsh', 'write', 'edit', 'grep', 'glob']);
+
+/**
+ * 候选里**每个平台都应当存在**的那些。
+ * 它们缺席是异常（插件组合变了 / 没装全），必须出声 —— 与"另一个平台的 shell 缺席"区分开。
+ */
+export const CORE_DENY_TOOLS = Object.freeze(['write', 'edit', 'grep', 'glob']);
+
+/** shell 工具是**平台二选一**的（preset 里 `disabled:` 按平台切）；同时写两个就会让 `restrict()` 抛错。 */
+export const SHELL_TOOL_BY_PLATFORM = Object.freeze({ win32: 'pwsh', posix: 'bash' });
+
+/**
+ * lead **保留**但受路径约束的只读工具：只允许读工件目录内的东西。
+ * 为什么不是直接 deny：lead 必须能读 SPEC/PLAN/REVIEW 才能做阶段门控与裁决；
+ * 要挡的是"整读大源码"这种**探索性**读取（那属于角色子代理的活）。
+ */
+export const LEAD_GUARDED_READ_TOOLS = Object.freeze(['read', 'read_image']);
+
+/** 工件目录名（相对工作区根）。lead 读这个子树以内的路径一律放行。 */
+export const ARTIFACT_SUBDIR = 'team';
+
+/** 归一平台标识：只关心"是不是 Windows"。 */
+export function normalizePlatform(platform) {
+  const p = String(platform ?? '').toLowerCase();
+  return p === 'win32' || p === 'windows' ? 'win32' : 'posix';
+}
+
+/**
+ * 算出 lead 该 deny 哪些工具。
+ *
+ * @param {object} input
+ * @param {string} [input.platform] - `process.platform`
+ * @param {Iterable<string>} [input.knownNames] - 宿主 `tools.view(scope).restrictableNames`
+ * @returns {{deny: string[], absent: string[], unexpectedAbsent: string[], expectedShell: string,
+ *            expectedShellPresent: boolean, effective: boolean, status: string, notes: string[]}}
+ */
+export function planLeadToolFace({ platform, knownNames } = {}) {
+  const expectedShell = SHELL_TOOL_BY_PLATFORM[normalizePlatform(platform)];
+  const otherShell = expectedShell === 'bash' ? 'pwsh' : 'bash';
+
+  // ── 两种零之一：**不知道宿主有哪些工具** ──────────────────────────────────
+  // 这一支绝不能返回"看起来像成功"的结果。`knownNames` 缺失时若返回 `deny: []` 而不加区分，
+  // 调用方会以为"工具面已收窄、只是没什么可收"—— 那是本包最讨厌的静默失败。
+  //
+  // **空数组也算"不知道"**（不是"没什么可收"）：真实部署里 `restrictableNames` 不可能是空的
+  // （至少 shell 与 fs 工具都在），所以空清单只可能是"查不到 / 查错了作用域"。
+  // 而且 `no-known-names`（"我不知道有什么"）在两种情况下都**真实**，
+  // `nothing-to-deny`（"宿主里这些名字都没有"）只在一种情况下真实 —— 拿不准时说那句一定真的。
+  const known = knownNames === undefined || knownNames === null ? new Set() : new Set(knownNames);
+  if (known.size === 0) {
+    return {
+      deny: [], absent: [...LEAD_DENY_CANDIDATES], unexpectedAbsent: [],
+      expectedShell, expectedShellPresent: false, effective: false,
+      status: 'no-known-names',
+      notes: ['拿不到有效的宿主工具名清单（knownNames 缺失或为空）⇒ **没有**收窄工具面。这不是"没什么可收"，是"我不知道有什么"。'],
+    };
+  }
+
+  const deny = [];
+  const absent = [];
+  const unexpectedAbsent = [];
+  const notes = [];
+
+  for (const name of LEAD_DENY_CANDIDATES) {
+    if (known.has(name)) { deny.push(name); continue; }
+    absent.push(name);
+    // 另一个平台的 shell 缺席是**预期**的（preset 按平台 disabled）—— 不算异常。
+    if (name === otherShell) continue;
+    unexpectedAbsent.push(name);
+  }
+
+  const expectedShellPresent = known.has(expectedShell);
+  if (!expectedShellPresent) {
+    notes.push(`本平台（${normalizePlatform(platform)}）的 shell 工具 \`${expectedShell}\` **不在**宿主工具清单里 —— 执行面收窄的前提不成立，请先确认 shell 插件已挂载。`);
+  }
+  if (unexpectedAbsent.length > 0) {
+    notes.push(`本该存在的工具缺席：${unexpectedAbsent.map((n) => `\`${n}\``).join(' · ')} —— 插件组合可能变了或没装全（缺席不是"已经收掉了"）。`);
+  }
+
+  // ── 两种零之二：**确实没什么可收** ───────────────────────────────────────
+  if (deny.length === 0) {
+    return {
+      deny, absent, unexpectedAbsent, expectedShell, expectedShellPresent,
+      effective: false, status: 'nothing-to-deny',
+      notes: [...notes, 'deny 名单为空 ⇒ **本次没有收窄任何工具**（宿主里这些名字一个都不存在）。'],
+    };
+  }
+
+  return { deny, absent, unexpectedAbsent, expectedShell, expectedShellPresent, effective: true, status: 'ready', notes };
+}
+
+/**
+ * lead 的只读工具**是否放行**（`lead` 只读工件）。
+ *
+ * 口径（刻意 fail-open）：判不出来就**放行** —— 与本包既有拦截器的口径一致
+ * （"降级要留痕，但不能把动作变红"）：宁可放过一次探索性读取，也不要因为路径判据写窄
+ * 而把 lead 的合法门控动作卡死。
+ *
+ * @param {object} input
+ * @param {string} [input.filePath] - 模型要读的路径
+ * @param {string} [input.cwd] - 工作区根
+ * @param {string[]} [input.extraRoots] - 额外放行的绝对路径前缀
+ * @returns {{allow: boolean, reason: 'artifact'|'outside-artifacts'|'undecidable'}}
+ */
+export function artifactReadDecision({ filePath, cwd, extraRoots } = {}) {
+  if (typeof filePath !== 'string' || filePath === '' || typeof cwd !== 'string' || cwd === '') {
+    return { allow: true, reason: 'undecidable' };
+  }
+  const root = path.resolve(cwd);
+  const target = path.resolve(root, filePath);
+  const roots = [path.join(root, ARTIFACT_SUBDIR)];
+  if (Array.isArray(extraRoots)) for (const r of extraRoots) if (typeof r === 'string' && r !== '') roots.push(path.resolve(r));
+
+  for (const r of roots) {
+    // 加分隔符再比前缀：否则 `/w/teamx` 会被 `/w/team` 误判为"在里面"。
+    if (target === r || target.startsWith(r + path.sep)) return { allow: true, reason: 'artifact' };
+  }
+  return { allow: false, reason: 'outside-artifacts' };
+}
+
+/** 本 preset 的 id（**实测值**：34 个真实会话头的 `agentPreset` 都是这个串，另 6 个是 `standard`）。 */
+export const LEAD_PRESET_ID = 'expert-team';
+
+/**
+ * 该不该对**这个** agent 收窄工具面。
+ *
+ * 判据两条，缺一不可：
+ *   ① **preset 必须是专家团**。读法 `agentPresets.composedPreset(agent.ctx)` —— 宿主写明它
+ *      "read from the live scope chain rather than from the session"，因此对**还没写会话头**的
+ *      agent 也答得出来。非专家团返回 `false`（**静默返回**，不是失败：绝大多数 agent 都无关）。
+ *   ② **必须是根 agent（lead），不能是角色子代理**。这一条是安全闸门，不是优化：
+ *      角色子代理是用 `composeFrom` 从**同一个 preset** 组合出来的 ⇒ 它们的
+ *      `composedPreset` **同样是 `expert-team`**。若不查 ②，A2 会把角色的 bash 一起收掉 ——
+ *      正好是要避免的事故。判据用 `agents.roots()`（宿主文档："created **without an owning
+ *      agent context**"），它按运行时归属判定，不受会话血缘影响。
+ *
+ * @param {object} input
+ * @param {string|undefined} [input.presetId] - `agentPresets.composedPreset(agent.ctx)`
+ * @param {boolean} [input.isRoot] - `agents.roots().includes(agent)`
+ * @returns {{apply: boolean, reason: 'lead'|'not-expert-team'|'is-subagent'}}
+ */
+export function shouldNarrowLeadToolFace({ presetId, isRoot } = {}) {
+  if (presetId !== LEAD_PRESET_ID) return { apply: false, reason: 'not-expert-team' };
+  if (isRoot !== true) return { apply: false, reason: 'is-subagent' };
+  return { apply: true, reason: 'lead' };
+}

package/lib/log-parse.js

@@ -0,0 +1,181 @@
+// 运行日志解析（B 线第 8 项 · `log-parse.js`）：把 `RUN.log.md` 的一行变成结构化事件。
+//
+// 为什么单独成模块：**同一个解析器被至少四个消费者用** —— METRICS 聚合、`/team check` 的阶段记账、
+// 命令侧的状态行、以及测试里的 `_live`。它以前住在 5000 行的编排器里，而 2026-09-13 我为"阶段记账"
+// 检查**临时抄了一份简化版**（`validate.js` 的 `parseLogLineLite`）—— 那正是本仓头号返工源
+// 「一个事实多份拷贝」的形态（两份解析器迟早分叉，而"哪边对"没人说得清）。搬出来之后**只此一份**。
+//
+// 口径（与 LOGGING.md 逐字对应，**不要在这里"顺手改好一点"**）：
+//   · 时间戳宽容：`HH:MM:SS` 是规范写法，但 `[now]` 这类历史写法**仍然计入事件**（否则当年那些
+//     run 的决策/阶段会被静默丢掉）；
+//   · 判决**只认 `verdict=<token>`**；`verdict=` 一旦出现就**绝不回落**到从中文散文里猜
+//     （历史 bug：`verdict=needs_revision；…通过 10…` 曾被散文正则提升成 pass）；
+//   · 角色名归一（`pm(repair)` → `pm`）与"从 `【中文标签】` 精确表取角色"分开：前者模糊、后者精确。
+//
+// 零 IO、零依赖（只用 vocab.js 的词表）⇒ 可单测。
+
+import { ROLE_LABELS_ZH, SUB_ROLE_WORDS } from './vocab.js';
+
+/**
+ * **从日志散文里**找角色名用的表（含 `lead`）。
+ * ⚠️ 它与 `vocab.js` 的 `KNOWN_ROLES` / 固定 12 角色**不是**同一件事：那份是"编制里有哪些角色"，
+ * 这份是"一行日志文本里出现了哪个角色词"（所以多一个 `lead`）。搬迁时**原样保留**，不合并——
+ * 合并会改变 `normalizeRoleName` 的行为（例如把 `competitive-analyst` 归一成 `competitive`）。
+ * 这是一处**已知的重复**，记在这里以免下次有人"顺手统一"。
+ */
+const ROLE_NAMES = ['pm', 'architect', 'researcher', 'backend', 'frontend', 'ui', 'dba', 'sec', 'devops', 'docs', 'reviewer', 'qa', 'lead'];
+export { ROLE_NAMES };
+
+// Parse STATE.members — the authorative per-run roster bindings written by the
+// lead at dispatch time. TWO formats observed in real runs:
+//   ["<agentSessionId>:<role>", ...]  ← precise (multi-run isolation!)
+//   ["pm:Mia", ...]                   ← role:name (legacy, no agent id)
+// Returns { byRole: Map<role, agentId>, names: Map<role, name> }.
+export function roleNorm(r) {
+  const rr = String(r || '').trim().toLowerCase();
+  const bare = rr.split('-')[0];
+  if (['pm', 'architect', 'researcher', 'backend', 'frontend', 'reviewer', 'qa', 'ui', 'dba', 'sec', 'devops', 'docs'].includes(bare)) return bare;
+  for (const [role, words] of SUB_ROLE_WORDS) {
+    if (words.some((w) => rr.includes(w))) return role;
+  }
+  return rr;
+}
+
+// ── learn: aggregate RUN.log.md events into metrics + distilled learnings ──
+
+export function parseLogLine(line) {
+  // Tolerant timestamp: `HH:MM:SS` (canonical) or ANY marker (real logs use
+  // `[now]`); unknown markers still count the EVENT so aggregations do not
+  // silently drop decisions/phases written by the lead.
+  const m = line.match(/^- \[([^\]]+)\] (\S+) — (.*)$/);
+  return m ? { time: m[1], type: m[2], detail: m[3] } : null;
+}
+
+/** `error:external-write` → 'error'；`role:pm` → 'role'；`phase:clarify` → 'phase'；无冒号则原样。 */
+export function eventFamily(type) {
+  const s = String(type ?? '');
+  const i = s.indexOf(':');
+  return i < 0 ? s : s.slice(0, i);
+}
+
+/**
+ * R10：按**码点**截断，不按 UTF-16 码元。
+ * 旧 `.slice(0, 120)` 会把代理对（emoji）切成半个，落盘后变成 `U+FFFD` 乱码
+ * （T-04 实测：`'x'.repeat(119) + '🙂'` ⇒ 样例末尾出现 `U+FFFD`）。长度上限语义不变。
+ */
+export function truncateCodepoints(s, max) {
+  const str = String(s ?? '');
+  const n = Number(max) > 0 ? Math.floor(Number(max)) : 120;
+  const cps = [...str];
+  return cps.length <= n ? str : cps.slice(0, n).join('');
+}
+
+/** 事件子类计数：`{count, sample}`，sample = 首条 detail 去换行截 120 码点。 */
+export function tallyEvent(map, type, detail) {
+  const cur = map.get(type) ?? { count: 0, sample: '' };
+  cur.count += 1;
+  if (!cur.sample) cur.sample = truncateCodepoints(String(detail ?? '').replace(/[\r\n]+/g, ' ').trim(), 120);
+  map.set(type, cur);
+}
+
+/** 渲染 `- \`<子类>\` × <n> — <样例>`（按次数降序）。 */
+export function eventTallyLines(map, emptyText) {
+  if (!map.size) return `- ${emptyText}`;
+  return [...map.entries()].sort((a, b) => b[1].count - a[1].count)
+    .map(([k, v]) => `- \`${k}\` × ${v.count}${v.sample ? ` — ${v.sample}` : ''}`).join('\n');
+}
+
+/**
+ * R11：角色名归一 —— 取到**第一个 `(`、`:` 或空白**之前为止。
+ * `role:pm(repair)` → `pm`（旧实现 `split(':')[0]` 会造出 `pm(repair)` 这个幽灵桶，
+ * 真实 php/school run 里有 15 条这种行，带 verdict= 时就渲染成幽灵角色行）；
+ * `role:frontend-F4` 这类**合法后缀**保留（`-` 不是分隔符）。
+ */
+export function normalizeRoleName(raw) {
+  const m = String(raw ?? '').trim().match(/^[^(:\s]+/);
+  return m ? m[0] : '';
+}
+
+/**
+ * R2（repair-1 最重要的正确性修复）：`verdict=` 一旦出现，判决**完全由 token 决定**。
+ *
+ * T-04 用真实 php/school run 实测到的失真：3 条 `role:reviewer … verdict=needs_revision`
+ * 里 2 条被记成 pass、1 条被整条丢弃。根因是 `extractVerdict` 把 token 与整条 detail 拼成
+ * haystack 再跑 prose 正则 —— detail 里的「通过」把 `needs_revision` 提升成了 `pass`。
+ *
+ * R18（repair-2）：解析前**先剥掉包裹字符**再整词匹配。真实 `php/school` RUN.log **第 163 行**
+ * 写的是 ```verdict=`needs_revision` ```（反引号 + markdown 粗体包裹），旧正则要求 token 紧跟
+ * `=` ⇒ 解析失败，而该分支**无 prose 兜底** ⇒ 判决被静默丢弃；若它是唯一返工证据 ⇒
+ * `返工/失败率：0%`（返工率虚低）。剥完仍按整词规则匹配，**剥不出合法 token 仍不计判决**。
+ *
+ * 映射逐字、大小写不敏感、**整词**匹配（`verdict=pass` / `verdict=pass,` / `verdict=pass）`
+ * 都算 pass；`verdict=pass_unverified` **不得**判 pass）。
+ * R19：词表补 `conditionally-pass` / `conditional` / `conditionally` → `pass`（该 token 在本仓
+ * 真实日志与 `smoke.test.mjs` 里存在；R2 之后它从"记 pass"退化成"不计判决"，属净减少，必须补回）。
+ * @returns {'pass'|'rework'|'fail'|''|null} `null` = detail 里没有 `verdict=`（调用点自行决定
+ *          是否走 prose）；`''` = 有 `verdict=` 但 token 无法识别 ⇒ **不计判决，绝不回落 prose**。
+ */
+export const VERDICT_TOKEN_WRAPPERS = '`*_"\'「」『』“”‘’()（）【】[]<>《》 \t';
+
+// 用 Map 而非普通对象：`constructor` / `toString` 这类继承键不会漏成一个"判决"。
+export const VERDICT_TOKENS = new Map([
+  ['pass', 'pass'],
+  ['conditionally-pass', 'pass'], ['conditional', 'pass'], ['conditionally', 'pass'],
+  ['needs_revision', 'rework'], ['rework', 'rework'],
+  ['fail', 'fail'],
+]);
+
+export function verdictFromToken(detail) {
+  const s = String(detail ?? '');
+  const at = s.search(/verdict=/i);
+  if (at < 0) return null;                       // 没有 `verdict=`（注意：`verdict:` 不算）
+  let rest = s.slice(at + 'verdict='.length);
+  // R18：剥掉前导包裹字符（markdown 粗体 `**`、反引号、全角/半角引号括号、前后空白）
+  while (rest.length > 0 && VERDICT_TOKEN_WRAPPERS.includes(rest[0])) rest = rest.slice(1);
+  const m = rest.match(/^([A-Za-z_][A-Za-z0-9_-]*)/);
+  if (!m) return '';                             // 剥不出合法 token ⇒ 不计判决（不回落 prose）
+  return VERDICT_TOKENS.get(m[1].toLowerCase()) ?? '';   // 词表外（含 `constructor` 这类）⇒ 不计判决
+}
+
+export function extractRole(detail) {
+  let v = (detail.match(/role=(\S+)/) ?? [])[1] ?? '';
+  if (v) return v.replace(/[,)]/g, '');
+  const hit = ROLE_NAMES.find((r) => new RegExp(`(^|[^a-z])${r}([^a-z]|$)`).test(detail));
+  return hit ?? 'unknown';
+}
+
+export function extractVerdict(detail) {
+  let v = (detail.match(/verdict=(\S+)/) ?? [])[1] ?? '';
+  v = v.split('(')[0];
+  const hay = v + ' ' + detail;
+  if (/fail|失败|报错/.test(hay)) return 'fail';
+  if (/rework|返工|重跑|不一致|缺陷/.test(hay)) return 'rework';
+  if (/pass|通过|可行|成功|conditionally/.test(hay)) return 'pass';
+  return '';
+}
+
+/**
+ * 「环境/平台类」错误族（C 线第 15 项：返工口径三分账）。
+ *
+ * 判据只有一条：**换个环境、或没有并发，就不会发生**。这类返工不是团队过程的问题，
+ * 混进同一个分子里会让"过程改好了没有"看不出来；反过来，把它们**剔除**出分子又会
+ * 让数字与历史不可比 —— 所以本包的做法是**不改上面那个率，只做性质分解**。
+ *
+ * 未列出的族**一律算"过程类"**（宁可算过程，不放过）：把未知当环境类会系统性地美化指标。
+ */
+export const ENV_ERROR_FAMILIES = new Set([
+  'error:external-write',   // 另一个进程/会话改了同一文件（本仓实测最高频：×9）
+  'error:stale-runtime',    // 运行时副本落后于源树
+  'error:platform',         // 平台/调度故障
+  'error:dispatch',         // 派工失败
+  'error:timeout',          // 超时
+]);
+
+/**
+ * 把一个 RUN.log 的 `error:<子类>` 事件归类。
+ * @param type - 事件类型（如 `error:external-write`）。
+ * @returns `'env'` = 环境/平台类；`'process'` = 过程类（含全部未列出的族）。
+ */
+export function classifyErrorFamily(type) {
+  return ENV_ERROR_FAMILIES.has(String(type || '')) ? 'env' : 'process';
+}

package/lib/loop-guard.js

@@ -0,0 +1,165 @@
+// 振荡检测（C 线第 16 项的**收窄版**）：同工具重复调用已由宿主负责，这里只管"A→B→A→B 来回横跳"。
+//
+// 为什么只做这一种（取证在 `docs/Qoder对标/02-Experts编排与提示词.md` 与宿主自带包的 README）：
+//   把"一直循环返工"拆成三种形态后逐一对照：
+//     ① 同工具、同参数的**重复调用** ⇒ **宿主已覆盖**：`@deepseek-ai/dsh-repeat-tool-reminder`
+//        在 dsh-base 里默认启用（thresholds `[3, 5, 8]`），按 agent 记链并注入提醒。
+//        **不要重写它**（用户明确要求过"不要每次都是自己造轮子"）。
+//     ② 同一 finding **跨轮未闭环** ⇒ 本包四支柱的 `FINDING_REOPENED`（读侧违规）已覆盖。
+//     ③ **A→B→A→B 振荡** ⇒ **没人管**。宿主那份 README 写死了它的边界：
+//        "Exact-match detection only — near-identical variants evade the chain"，
+//        且没有任何交替检测；而 Qoder 平台内核里有一条专门的 `[ALTERNATING LOOP DETECTED]`。
+//        这一条正是用户最初抱怨的形态（不是原地重复，而是在两个修法之间来回）。
+//
+// 与宿主那份的**关键差异（为什么这里用"阻断"而不是"只提醒"）**：
+//   宿主那份是 advisory（`never blocks or delays a legitimate repeated call`）—— 因为**完全相同的
+//   轮询/等待调用可能是合法的**。但**振荡从来不是合法行为**：在两个互斥方案之间来回本身就说明
+//   至少有一个判断是错的，继续切只会烧预算。Qoder 对它的处理也是硬性的（`You MUST: 1) STOP
+//   switching between approaches...`）。因此这里用 `block{feedback}` 把结果变成错误 + 模型可见理由。
+//
+// 安全纪律（2026-09-12 监听器签名事故之后立的规矩，本模块逐条遵守）：
+//   ① 按宿主签名 `(exec, result, next)` 声明；② `next` 不是函数时降级为"不干涉"，绝不抛错；
+//   ③ 自身逻辑全部包在 try/catch 里 —— **绝不允许**成为工具调用的故障源。
+
+/** 参数预览的截断长度（只用于提醒文案，不参与判定）。 */
+const DEFAULT_PREVIEW_CHARS = 200;
+
+// 只对**会改文件内容**的工具记链（`write`/`edit`），并且额外要求四次调用指向**同一个文件**。
+//
+// 为什么必须这么窄（写完第一版才意识到的误报）：`编辑 a.js` → `编辑 b.js` → `编辑 a.js` → `编辑 b.js`
+// 形式上也是 A→B→A→B，但那是**完全正常的干活**（两个文件交替改）。窄化后真正的判据是：
+// **在同一个文件上，用两种不同内容来回覆盖 ≥2 个来回** —— 那才是 Qoder 那条
+// `[ALTERNATING LOOP DETECTED]` 说的"在两个互斥方案之间来回"。
+// 误报的代价不是"多一条提醒"：它会把守卫本身变成噪声（本包实测教训 —— 噪声门禁 = 没有门禁）。
+import { WRITE_TOOLS, targetOf } from './interception.js';
+
+/** 本工具的 `file_path`（非写入类工具返回 null ⇒ 不参与记链）。 */
+export function trackedPath(exec) {
+  if (!exec || !WRITE_TOOLS.has(String(exec.name || ''))) return null;
+  return targetOf(exec);
+}
+
+/**
+ * 归一化一次调用的身份：工具名 + 深度键序无关的参数 JSON。
+ * 与宿主那份同思路（深键序排序），但**不追求完全一致** —— 我们只关心"两次调用是不是同一个意图"。
+ * @param exec - 工具执行记录。
+ * @returns 身份串（参数不可序列化时退回 `String(arguments)`）。
+ */
+export function callKey(exec) {
+  const name = String((exec && exec.name) || '');
+  let canon;
+  try {
+    canon = JSON.stringify(sortDeep(exec && exec.arguments));
+  } catch {
+    canon = String(exec && exec.arguments);
+  }
+  return `${name}\u0000${canon}`;
+}
+
+/** 深度键序排序（数组保持原序，只稳定化对象键序）。 */
+export function sortDeep(v) {
+  if (Array.isArray(v)) return v.map(sortDeep);
+  if (v && typeof v === 'object') {
+    const out = {};
+    for (const k of Object.keys(v).sort()) out[k] = sortDeep(v[k]);
+    return out;
+  }
+  return v;
+}
+
+/**
+ * 从调用身份序列尾部判定是否在振荡。
+ * 判据：最后 4 条形如 `a b a b`（且 `a !== b`）—— 即"回到刚才否掉的方案，又回到刚才那个"。
+ * 只认**紧邻**的 4 条，不做模糊匹配：误报会把提醒变成噪声（本包实测过的教训，噪声门禁 = 没有门禁）。
+ * @param history - 最近的调用身份（按时间先后）。
+ * @returns 振荡对的稳定 key（`a|b`，字典序）；未振荡返回 null。
+ */
+export function oscillationPair(history) {
+  const h = Array.isArray(history) ? history : [];
+  if (h.length < 4) return null;
+  const [x1, x2, x3, x4] = h.slice(-4);
+  if (x1 === x2) return null;
+  if (x1 !== x3 || x2 !== x4) return null;
+  return [x1, x2].sort().join('\u0001');
+}
+
+/**
+ * 创建一个 `tools/post-execute` 振荡守卫。
+ *
+ * @param deps - 注入依赖：
+ *   `onEvent(type, payload)`（可观测：让"守卫被行使"看得见）、
+ *   `enabled`（默认 true）、`historySize`（默认 8）、`previewChars`（默认 200）、
+ *   `makeFeedback(text)`（把文案包成宿主认的 `ContentBlock[]`；默认 `[{type:'text',text}]`）。
+ * @returns `(exec, result, next) => Promise<PostToolDecision>`
+ */
+export function createLoopGuard(deps = {}) {
+  const {
+    onEvent = () => {},
+    enabled = true,
+    historySize = 8,
+    previewChars = DEFAULT_PREVIEW_CHARS,
+    makeFeedback = (text) => [{ type: 'text', text }],
+  } = deps;
+
+  /** 每个 agent 一条链（用 agent 对象本身做键 ⇒ 不泄漏、不串号）。 */
+  const chains = new WeakMap();
+
+  function stateFor(agent) {
+    if (!agent || (typeof agent !== 'object' && typeof agent !== 'function')) return null;
+    let st = chains.get(agent);
+    if (!st) { st = { history: [], fired: new Set() }; chains.set(agent, st); }
+    return st;
+  }
+
+  return async function loopGuard(exec, result, next) {
+    // ① 签名纪律：不是瀑布就降级为不干涉（写错签名曾让整个会话的工具链瘫痪）
+    if (typeof next !== 'function') return { kind: 'accept' };
+    const downstream = await next();
+    try {
+      if (!enabled) return downstream;
+      // ② 工具本身已失败 ⇒ 不插嘴（沿用边界拦截器的同一条纪律：不拿无关理由掩盖真错因）
+      if (result && (result.isError === true || result.error)) return downstream;
+      // ③ 只对**会改文件内容**的工具记链（写/编辑）；读类工具交替调用是正常干活
+      const path = trackedPath(exec);
+      if (!path) return downstream;
+      // ④ 只对**agent 发起的**调用记链；直接调用的宿主工具不参与（无法归因到某个子代理）
+      const agent = exec && exec.agent;
+      const st = stateFor(agent);
+      if (!st) return downstream;
+
+      const key = callKey(exec);
+      st.history.push({ key, path });
+      if (st.history.length > historySize) st.history.splice(0, st.history.length - historySize);
+
+      const pair = oscillationPair(st.history.map((e) => e.key));
+      if (!pair) return downstream;
+      // ⑤ **必须同一个文件**：`编辑 a.js`/`编辑 b.js` 交替是正常干活，不是振荡
+      if (new Set(st.history.slice(-4).map((e) => e.path)).size !== 1) return downstream;
+      // ⑥ 同一对**每个 agent 会话只提醒一次**：重复提醒会把守卫变成噪声（宿主那份的已知痛点）
+      if (st.fired.has(pair)) return downstream;
+      st.fired.add(pair);
+
+      const name = String((exec && exec.name) || '');
+      const preview = String(exec && exec.arguments ? JSON.stringify(exec.arguments) : '').slice(0, previewChars);
+      const text = [
+        `⚠️ 检测到**振荡**：你在两个互斥的做法之间来回切换（最近四次调用形如 A→B→A→B，工具「${name}」）。`,
+        '来回切本身说明其中至少一次判断是错的。请按顺序做：',
+        '1) **停止切换**：从两者中选一个最可能正确的，明确写出为什么选它；',
+        '2) 若两者都不成立，**退一步找共同根因**，而不是在两者之间继续换；',
+        '3) 若确实无法推进，**停下来给结论**：已试过什么、各自失败在哪、还剩什么没试。',
+        `（最近一次调用的参数预览：${preview || '（无）'}）`,
+      ].join('\n');
+
+      onEvent('loop-guard-oscillation', { tool: name, pair });
+      const feedback = makeFeedback(text);
+      // ④ 折叠下游结论：下游已 block 就保留它的理由再追加我们的；否则自己 block
+      if (downstream && downstream.kind === 'block') {
+        return { kind: 'block', feedback: [...(downstream.feedback || []), ...feedback] };
+      }
+      return { kind: 'block', feedback };
+    } catch (e) {
+      onEvent('loop-guard-error', { error: String((e && e.message) || e) });
+      return downstream;
+    }
+  };
+}

package/lib/metrics/collect.js

@@ -0,0 +1,70 @@
+// run 的**采集层**（B 线 10b 第二刀）：只做 IO，不做判定。
+//
+// `aggregate()` 原本把六件事压在一个函数里（枚举 / 读取 / 解析 / 计算 / 渲染 / 写盘）。
+// 渲染已切到 `render.js`；这里把**枚举与读取**切出来，让「怎么读盘」与「读出来怎么算」分开 ——
+// 值在于 ① 采集的边界（什么算 run、缺文件怎么办）可以单测；② 计算主体将来搬走时，
+// 依赖面只剩一个 `readRunInputs` 返回值，而不是散落各处的 `readFile`。
+//
+// 设计：**逐 run 读取**（不是"一次读全部"）—— 保持与旧实现相同的内存行为：
+// 旧实现每轮读一个 run 就丢掉；收集成一个大数组会让长日志全留在内存里。
+
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+
+/** 判定「真 run 目录」的标记文件（含任一即可）。 */
+export const RUN_MARKER_FILES = ['STATE.json', 'TASK.md', 'RUN.log.md'];
+
+/** 读 JSON，失败返回 null（不抛）。 */
+async function readJsonSafe(p) {
+  try { return JSON.parse(await readFile(p, 'utf8')); } catch { return null; }
+}
+
+/**
+ * 列出 `<root>` 下的**真 run** 目录名。
+ *
+ * 为什么不能直接 `readdir` 全收：`team/` 里还躺着 METRICS.md / LEARNINGS.md / REPOWIKI.md /
+ * CODEINDEX.json 这些**文件**，以及可能的空目录。旧实现把它们也算进「总 run 数」，
+ * 于是用户看到「总 run 数：8」而真实只有 2（D4 实测）。
+ *
+ * @param root - `<cwd>/team` 的绝对路径。
+ * @returns `{ ok, names, skipped }`；`ok:false` 表示 root 读不了（调用方按「零 run」处理）。
+ */
+export async function listRunNames(root) {
+  const names = [];
+  let skipped = 0;
+  try {
+    const entries = await readdir(root, { withFileTypes: true });
+    for (const ent of entries) {
+      if (!ent.isDirectory()) { skipped += 1; continue; }
+      const dir = join(root, ent.name);
+      let isRun = false;
+      for (const marker of RUN_MARKER_FILES) {
+        if (await stat(join(dir, marker)).then(() => true).catch(() => false)) { isRun = true; break; }
+      }
+      if (isRun) names.push(ent.name); else skipped += 1;
+    }
+    names.sort();
+  } catch {
+    return { ok: false, names: [], skipped: 0 };
+  }
+  return { ok: true, names, skipped };
+}
+
+/**
+ * 读一个 run 的四份输入（缺哪份就返回该份的「空值」，**不抛**）。
+ * @param root - `<cwd>/team` 的绝对路径。
+ * @param name - run 目录名。
+ * @returns `{ dir, state, log, tasksDoc, rosterDoc }`
+ *   —— `state`/`tasksDoc`/`rosterDoc` 读不到或不是合法 JSON 时为 `null`；`log` 读不到时为 `''`。
+ */
+export async function readRunInputs(root, name) {
+  const dir = join(root, name);
+  let state = null;
+  let log = '';
+  let tasksDoc = null;
+  try { state = JSON.parse(await readFile(join(dir, 'STATE.json'), 'utf8')); } catch { /* 缺件按 null */ }
+  try { log = await readFile(join(dir, 'RUN.log.md'), 'utf8'); } catch { /* 缺件按空串 */ }
+  try { tasksDoc = JSON.parse(await readFile(join(dir, 'TASKS.json'), 'utf8')); } catch { /* 缺件按 null */ }
+  const rosterDoc = await readJsonSafe(join(dir, 'ROSTER.json'));
+  return { dir, state, log, tasksDoc, rosterDoc };
+}