@joekytc/dsh-swarm 0.3.7 → 0.3.9

package/lib/domain/gate-policy.js

@@ -1,12 +1,50 @@
 // src/domain/gate-policy.ts
-/** kanban_complete 实测闸派生（纯函数，零 IO）：
- * 声明来源单层——tdd.test_files 自动派生 npx --no-install vitest run（runner=vitest 为 review-evidence 既有口径）。
- * cwd 一律 metadata.worktree_dir，缺失即 skip（旧卡向后兼容零感知）。
- * test_files 必须相对路径且规范化后无 .. 段（防绝对路径跑主仓库/越界逃逸——跑错代码即闸被绕过），违规整单 skip。
- * branchMatches 供装配层在 git 查询后做分支一致性比对（current=null 视为不匹配，调用方 skip）。 */
+/** kanban_complete 实测闸派生（纯函数，零 IO）。
+ * 2026-09-16 PR1 互证升级：声明与实际必须互证（GateOutcome 四态）——
+ *  - run：真跑（派生 npx --no-install vitest run，runner=vitest 为 review-evidence 既有口径）
+ *  - bounce：闸失败打回（同会话 throw 修复重交；3 次上限见 kanban-service MAX_GATE_BOUNCES）
+ *  - alarm-skip：警报放行（task/gate-skipped 留痕后照常 completed）
+ *  - silent-skip：不适用（旧 null 语义逐字节兼容：gates disabled / 非 d-execute / 旧卡无 worktree）
+ * diffFiles 由装配层以 `git diff --name-only <TARGET_BRANCH>...HEAD` 取得；null=不可得 → 保守放行（fail-visible 不 fail-closed）。 */
 import { isAbsolute } from 'node:path';
-export function isGatePlan(x) {
-    return x.skipped === false;
+import { isTestFile } from './tdd-classify.js';
+/** 文档/配置扩展白名单——对齐 D 卡 body 既有口径「纯文档/配置变更则带 tdd={skipped:{reason}}」（v-orchestrator d 模板）。 */
+const DOC_CONFIG_EXT = new Set(['md', 'txt', 'json', 'yml', 'yaml', 'toml']);
+function extOf(path) {
+    const m = /\.([A-Za-z0-9]+)$/.exec(path);
+    return m ? m[1].toLowerCase() : '';
+}
+function isDocOrConfig(path) {
+    return DOC_CONFIG_EXT.has(extOf(path));
+}
+/** ④ tdd.skipped 声明互证：diff 实况三分支（改声明 / tdd 先行 / 放行留痕）。
+ * 返回类型排除 proceed（proceed 仅为 test_files 对称核验的"放行"语义）。 */
+export function classifySkippedDeclaration(diffFiles) {
+    if (diffFiles === null)
+        return { action: 'allow-alarm', reason: 'tdd skipped by declaration (diff unavailable, 保守放行)' };
+    if (diffFiles.some(isTestFile)) {
+        return { action: 'bounce', reason: '声明 tdd.skipped 但本次变更包含测试文件：请改声明 tdd.test_files（闸门将实测）' };
+    }
+    const hasCodeChange = diffFiles.some((f) => !isTestFile(f) && !isDocOrConfig(f));
+    if (hasCodeChange) {
+        return { action: 'bounce', reason: 'tdd 先行：本次变更含代码文件，必须声明 tdd.test_files（纯文档/配置变更才允许 skipped）' };
+    }
+    return { action: 'allow-alarm', reason: 'tdd skipped by declaration: pure docs/config change' };
+}
+/** 对称核验：声明 tdd.test_files 但 diff 零测试变更（拿旧测试交差）→ bounce。 */
+export function classifyTestFilesDeclaration(diffFiles) {
+    if (diffFiles === null)
+        return { action: 'proceed' };
+    if (diffFiles.some(isTestFile))
+        return { action: 'proceed' };
+    return { action: 'bounce', reason: 'tdd 先行：本次变更未包含测试文件（新增或修改测试文件后重交）' };
+}
+/** 从 D 卡 body 解析 diff base（body 模板声明 `TARGET_BRANCH=<目标分支名>`，v-orchestrator d:76）。
+ * 与 test_files 同款防线：拒 git 旗标注入（`--output=/x` 可写任意路径文件）与路径逃逸。 */
+export function resolveDiffBase(body) {
+    const m = /TARGET_BRANCH[=:]\s*([^\s，,。；]+)/.exec(body ?? '');
+    const base = m ? m[1] : null;
+    return base && /^[A-Za-z0-9._/-]+$/.test(base) && !base.startsWith('-') ? base : null;
 }
 export function branchMatches(current, declared) {
     return typeof declared === 'string' && declared.trim().length > 0 && current === declared;
@@ -20,25 +58,28 @@ const isSafeRelativeTestFile = (f) => /^[A-Za-z0-9._/-]+$/.test(f) && !isAbsolut
     && !f.startsWith('-'); // 拒绝以 - 开头的条目：防 vitest CLI 旗标注入（如 --passWithNoTests 使 0 tests matched 也 exit 0，空跑绕闸）
 export function deriveGatePlan(input) {
     const m = input.handoff.metadata ?? {};
+    const diff = input.diffFiles ?? null;
     if (!input.config.enabled)
-        return { commands: [], skipped: true, reason: 'gates disabled' };
+        return { kind: 'silent-skip', reason: 'gates disabled' };
     if (!(input.assignee === 'd' && input.mode === 'execute'))
-        return { commands: [], skipped: true, reason: 'not d/execute' };
+        return { kind: 'silent-skip', reason: 'not d/execute' };
     const wt = m['worktree_dir'];
     if (typeof wt !== 'string' || !wt.trim())
-        return { commands: [], skipped: true, reason: 'worktree_dir missing (legacy card)' };
+        return { kind: 'silent-skip', reason: 'worktree_dir missing (legacy card)' };
     const tdd = m['tdd'];
-    if (tdd?.skipped)
-        return { commands: [], skipped: true, reason: 'tdd skipped by declaration' };
+    if (tdd?.skipped) {
+        const v = classifySkippedDeclaration(diff);
+        return v.action === 'allow-alarm' ? { kind: 'alarm-skip', reason: v.reason } : { kind: 'bounce', reason: v.reason };
+    }
     if (!Array.isArray(tdd?.test_files) || tdd.test_files.length === 0)
-        return { commands: [], skipped: true, reason: 'no gate commands' };
+        return { kind: 'bounce', reason: 'tdd 先行：交付代码变更必须声明 tdd.test_files（纯文档/配置变更才允许声明 skipped）' };
     const files = tdd.test_files.filter((f) => typeof f === 'string' && f.trim().length > 0);
     if (files.length === 0)
-        return { commands: [], skipped: true, reason: 'no gate commands' };
+        return { kind: 'bounce', reason: 'tdd 先行：tdd.test_files 为空（纯文档/配置变更才允许声明 skipped）' };
     if (!files.every(isSafeRelativeTestFile))
-        return { commands: [], skipped: true, reason: 'invalid test_files path (relative in-worktree required)' };
-    return {
-        commands: [{ command: `npx --no-install vitest run ${files.join(' ')}`, cwd: wt, source: 'tdd' }],
-        skipped: false,
-    };
+        return { kind: 'bounce', reason: 'invalid test_files path (relative in-worktree required)' };
+    const declared = classifyTestFilesDeclaration(diff);
+    if (declared.action === 'bounce')
+        return { kind: 'bounce', reason: declared.reason };
+    return { kind: 'run', commands: [{ command: `npx --no-install vitest run ${files.join(' ')}`, cwd: wt, source: 'tdd' }] };
 }

package/lib/domain/kanban-service.d.ts

@@ -6,6 +6,29 @@ export type KanbanListener = (event: KanbanEvent) => void;
 export declare function firstSentence(text: string): string;
 /** 默认链标题：【需求】<一句话需求描述>。来源优先级 /plan: rest 首句 → checklist.problem 首句 → 未命名需求。 */
 export declare function buildChainTitle(requirementName: string | null, _openspecRest: string, problem: string): string;
+/** gate hook 三态裁决（PR1 互证）：null=不适用（总开关关/非 D/旧卡，静默零事件）；
+ * {skipped,reason}=警报放行（task/gate-skipped 留痕后照常 completed）；
+ * {ok,detail}=真跑或打回（ok=false → gate-failed + throw 同会话修复重交）。 */
+export type GateHookVerdict = {
+    ok: boolean;
+    detail: string;
+} | {
+    skipped: true;
+    reason: string;
+} | null;
+/** 同一任务实测闸打回上限（累计计数）：超过后 blockTask 转人工。
+ * gate fail 不走 failTask、attempts 不递增（仅会话死亡路径 +1），故按 gate-failed 事件数自建计数。 */
+export declare const MAX_GATE_BOUNCES = 3;
+/** 评审证据核验汇总（PR2，非阻塞）：仅 DT 卡 complete 时调用，结果只发事件留痕
+ * （differs/could-not-replay 不阻塞 complete、不改 verdict——转人工信号走事件流）。 */
+export type EvidenceCheckSummary = {
+    results: Array<{
+        title: string;
+        severity: string;
+        state: string;
+        detail: string;
+    }>;
+} | null;
 /** 看板领域门面：三界面（工具/CLI/UI）统一路由的唯一入口。 */
 export declare class KanbanService {
     private state;
@@ -16,6 +39,7 @@ export declare class KanbanService {
     private onChainCompletedHook;
     private onTaskCompletedHook;
     private gateHook;
+    private evidenceCheckHook;
     constructor(store: EventStore, getKbUrlBase?: () => string | undefined);
     private emit;
     /** 注入链完成核对钩子（由调度层设置；仅一个消费者）。 */
@@ -23,10 +47,9 @@ export declare class KanbanService {
     /** 注入任务完成互链登记钩子（由调度层设置；仅一个消费者）。 */
     setOnTaskCompleted(hook: (taskId: string) => void | Promise<void>): void;
     /** 注入实测闸钩子（由装配层设置；null=关闭实测闸，行为与旧版逐字节一致）。 */
-    setGateHook(hook: ((task: Task, handoff: Handoff) => Promise<{
-        ok: boolean;
-        detail: string;
-    } | null>) | null): void;
+    setGateHook(hook: ((task: Task, handoff: Handoff) => Promise<GateHookVerdict>) | null): void;
+    /** 注入评审证据核验钩子（PR2；null=关闭，行为与旧版一致）。 */
+    setEvidenceCheckHook(hook: ((task: Task, handoff: Handoff) => Promise<EvidenceCheckSummary>) | null): void;
     /** 订阅持久化后的看板事件；返回解除订阅函数。listener 异常不影响已落盘状态。 */
     subscribe(listener: KanbanListener): () => void;
     /** 返回 seq >= 入参 的事件（与 EventStore.readSince 同为 inclusive 语义）。 */

package/lib/domain/kanban-service.js

@@ -51,6 +51,9 @@ function reworkChecklistSection(issues) {
     }
     return lines.join('\n');
 }
+/** 同一任务实测闸打回上限（累计计数）：超过后 blockTask 转人工。
+ * gate fail 不走 failTask、attempts 不递增（仅会话死亡路径 +1），故按 gate-failed 事件数自建计数。 */
+export const MAX_GATE_BOUNCES = 3;
 /** 看板领域门面：三界面（工具/CLI/UI）统一路由的唯一入口。 */
 export class KanbanService {
     state;
@@ -65,9 +68,13 @@ export class KanbanService {
     // W2/W3 完成互链登记钩子（dispatcher 注入：拿 page_path → 机械写三方互链，失败不阻塞完成）
     onTaskCompletedHook = null;
     // 实测闸钩子（装配层注入：gate-policy 派生 + gate-runner 实测执行 + 分支核对）。
-    // null=未启用（行为不变）；hook 返回 null=跳过（零感知，无 gate 事件）。
+    // 三态（PR1 互证）：null=不适用（静默零事件，行为不变）；{skipped,reason}=警报放行；
+    // {ok,detail}=真跑（ok=false → gate-failed + throw 打回，同会话修复重交）。
     // **无 actor 参数——human 无豁免**（2026-09-02 决议收紧）。
     gateHook = null;
+    // 评审证据核验钩子（PR2，非阻塞）：仅 DT 卡 complete 时调用，结果只发 review/evidence-check 事件留痕
+    // （differs/could-not-replay 不阻塞 complete、不改 verdict——转人工信号走事件流）。
+    evidenceCheckHook = null;
     constructor(store, getKbUrlBase) {
         this.store = store;
         this.getKbUrlBase = getKbUrlBase ?? null;
@@ -99,6 +106,10 @@ export class KanbanService {
     setGateHook(hook) {
         this.gateHook = hook;
     }
+    /** 注入评审证据核验钩子（PR2；null=关闭，行为与旧版一致）。 */
+    setEvidenceCheckHook(hook) {
+        this.evidenceCheckHook = hook;
+    }
     /** 订阅持久化后的看板事件；返回解除订阅函数。listener 异常不影响已落盘状态。 */
     subscribe(listener) {
         this.listeners.add(listener);
@@ -272,15 +283,42 @@ export class KanbanService {
         // v2 断代：w:file 交付键随旧 w1 预取阶段移除，manifest 校验块同步删除
         // （validatePrefetchManifest 仍保留于 prefetch-manifest.ts，供清单 schema 校验复用）。
         // 实测闸：hook 由装配层注入（gate-policy 派生 + gate-runner 实测执行 + 分支核对），
-        // hook 返回 null=跳过（未启用/非 D/旧卡/分支不一致）。**无 human 豁免**（2026-09-02 决议收紧）；
-        // ok=false → gate-failed 事件 + 拒绝 complete（卡留 running，throw 经工具边界回 D 会话）。
+        // 三态语义见 GateHookVerdict。**无 human 豁免**（2026-09-02 决议收紧）；
+        // ok=false → gate-failed 事件 + 拒绝 complete（卡留 running，throw 经工具边界回 D 会话）；
+        // 累计打回 ≥MAX_GATE_BOUNCES → blockTask 转人工（防同会话无限循环；人工 unblock 不重置计数——语义取舍见台账）。
         if (this.gateHook) {
             const verdict = await this.gateHook(t, handoff);
             if (verdict !== null) {
-                await this.emit({ chainId: t.chainId, taskId, kind: verdict.ok ? 'task/gate-passed' : 'task/gate-failed',
-                    payload: { detail: verdict.detail }, author: 'system', at: Date.now() });
-                if (!verdict.ok)
-                    throw new Error('gate failed: ' + verdict.detail);
+                if ('skipped' in verdict) {
+                    // 警报放行：留痕后照常 completed（④ 诚实纯文档场景不被打扰，谎报由 DT/人工下游兜底）
+                    await this.emit({ chainId: t.chainId, taskId, kind: 'task/gate-skipped', payload: { reason: verdict.reason }, author: 'system', at: Date.now() });
+                }
+                else {
+                    await this.emit({ chainId: t.chainId, taskId, kind: verdict.ok ? 'task/gate-passed' : 'task/gate-failed',
+                        payload: { detail: verdict.detail }, author: 'system', at: Date.now() });
+                    if (!verdict.ok) {
+                        const bounces = this.state.events.filter((e) => e.taskId === taskId && e.kind === 'task/gate-failed').length;
+                        const escalated = bounces >= MAX_GATE_BOUNCES;
+                        if (escalated) {
+                            await this.blockTask(taskId, `gave_up: gate bounced ${bounces} times — 转人工核对`, 'system');
+                        }
+                        // throw 文案区分升级态（评审 Minor）：blocked 后 D 会话不应误以为还能重试
+                        throw new Error('gate failed' + (escalated ? '（已转人工核对，请勿盲目重试）' : '') + ': ' + verdict.detail);
+                    }
+                }
+            }
+        }
+        // PR2 评审证据核验（非阻塞，仅 DT）：结果发 review/evidence-check 汇总事件（先于 completed）。
+        // hook 异常不阻断 complete；differs/could-not-replay 不改 verdict——转人工信号走事件流。
+        if (this.evidenceCheckHook && t.assignee === 'dt') {
+            try {
+                const summary = await this.evidenceCheckHook(t, handoff);
+                if (summary && summary.results.length > 0) {
+                    await this.emit({ chainId: t.chainId, taskId, kind: 'review/evidence-check', payload: { results: summary.results }, author: 'system', at: Date.now() });
+                }
+            }
+            catch (error) {
+                console.error('[dsh-swarm] evidence check failed (non-blocking): ' + String(error));
             }
         }
         await this.emit({ chainId: t.chainId, taskId, kind: 'task/completed', payload: { ...handoff }, author: actor, at: Date.now() });

package/lib/domain/planning-checklist.d.ts

@@ -25,3 +25,6 @@ export declare function validatePlanningChecklist(raw: unknown): string[];
 export declare function buildChecklistTitle(c: PlanningChecklist): string;
 /** 需求澄清清单落库 body：标题【需求】+ 各段可读 markdown（非裸 JSON）。KB 与临时目录两分支共用。 */
 export declare function formatChecklistBody(c: PlanningChecklist): string;
+/** 从清单页原文提取机读 PlanningChecklist（无损恢复路径）：无段/损坏/校验不过一律返回 null，
+ *  由调用方回退 legacy LLM 重建流程。domain 纯函数，无副作用。 */
+export declare function extractChecklistJson(pageMd: string): PlanningChecklist | null;

package/lib/domain/planning-checklist.js

@@ -151,5 +151,32 @@ export function formatChecklistBody(c) {
     }
     if (doubts.length === 0)
         lines.push('（无）');
+    // 机读段（2026-09-21 恢复流程矫正）：页正文是人读 markdown（有损），重启恢复若让 LLM 读页重建
+    // 再回存 = 有损再创作 + 双重编码风险（销服一体清单 7 轮失败即发生在恢复场景）。页尾内嵌无损
+    // JSON 单行段，/openspec: 路由2 直接提取灌内存建链，LLM 零参与；HTML 注释对人读零干扰。
+    const machine = JSON.stringify({ requirementName: c.requirementName ?? null, spec: c.spec, manifest: c.manifest, clarifications: c.clarifications, doubts: c.doubts, risks: c.risks ?? [] });
+    lines.push('', `<!-- dsh-swarm:checklist-json ${machine} -->`);
     return lines.join('\n').replace(/\n{3,}/g, '\n\n');
 }
+const CHECKLIST_JSON_MARK = '<!-- dsh-swarm:checklist-json ';
+/** 从清单页原文提取机读 PlanningChecklist（无损恢复路径）：无段/损坏/校验不过一律返回 null，
+ *  由调用方回退 legacy LLM 重建流程。domain 纯函数，无副作用。 */
+export function extractChecklistJson(pageMd) {
+    const start = pageMd.indexOf(CHECKLIST_JSON_MARK);
+    if (start < 0)
+        return null;
+    const jsonStart = start + CHECKLIST_JSON_MARK.length;
+    const end = pageMd.indexOf('-->', jsonStart);
+    if (end < 0)
+        return null;
+    let raw;
+    try {
+        raw = JSON.parse(pageMd.slice(jsonStart, end).trim());
+    }
+    catch {
+        return null;
+    }
+    if (validatePlanningChecklist(raw).length > 0)
+        return null;
+    return raw;
+}

package/lib/domain/prefetch-manifest.js

@@ -52,22 +52,33 @@ export function validatePrefetchManifest(raw) {
         errors.push('manifest.files must be an array');
     }
     else {
+        // files[] 逐条错误先收集再聚合（2026-09-21：26 条同文错误墙稀释有效信息，模型只见截断前几条）。
+        // 完全相同的消息合并为 "<msg> ×N"，不同消息保持原样与原序。
+        const fileErrors = [];
         for (const f of m['files']) {
             if (typeof f !== 'object' || f === null) {
-                errors.push('manifest.files entry must be an object');
+                fileErrors.push('manifest.files entry must be an object');
                 continue;
             }
             const e = f;
             if (typeof e['path'] !== 'string' || e['path'].trim().length === 0) {
-                errors.push(`manifest.files[].path (got: ${JSON.stringify(e['path'])})`);
+                fileErrors.push(`manifest.files[].path (got: ${JSON.stringify(e['path'])})`);
             }
             if (typeof e['expected'] !== 'string' || !EXPECTED_VALUES.has(e['expected'])) {
-                errors.push(`manifest.files[].expected (got: ${JSON.stringify(e['expected'])})`);
+                fileErrors.push(`manifest.files[].expected (got: ${JSON.stringify(e['expected'])})`);
             }
             if (e['expected'] === 'content-hash' && (typeof e['note'] !== 'string' || e['note'].trim().length === 0)) {
-                errors.push(`manifest.files[].note required for content-hash (got: ${JSON.stringify(e['note'])})`);
+                fileErrors.push(`manifest.files[].note required for content-hash (got: ${JSON.stringify(e['note'])})`);
             }
         }
+        errors.push(...tallyIdentical(fileErrors));
     }
     return errors;
 }
+/** 相同消息聚合计数：["a","a","b"] → ["a ×2","b"]。domain 纯函数，无副作用。 */
+function tallyIdentical(messages) {
+    const counts = new Map();
+    for (const msg of messages)
+        counts.set(msg, (counts.get(msg) ?? 0) + 1);
+    return [...counts.entries()].map(([msg, n]) => (n > 1 ? `${msg} ×${n}` : msg));
+}

package/lib/domain/review-evidence.js

@@ -45,7 +45,9 @@ export function validateReviewEvidence(role, handoff) {
         const tcOk = ev.typecheck && typeof ev.typecheck === 'object';
         if (!buildOk && !tcOk)
             missing.push('review_evidence.build/typecheck');
-        if (ev.lint === undefined)
+        // PR1 对齐 build 口径（上方 buildOk/typecheckOk）：lint 必须为结构化对象；null/字符串/数字拒收（lint:null 曾溜闸）。
+        const lintOk = ev.lint && typeof ev.lint === 'object';
+        if (!lintOk)
             missing.push('review_evidence.lint');
         const diffOk = ev.diff && typeof ev.diff === 'object' && Object.keys(ev.diff).length > 0;
         if (!diffOk)

package/lib/domain/types.d.ts

@@ -22,6 +22,12 @@ export interface ReviewIssue {
     fix?: string;
     /** 对账标记：true=上一轮遗留 issue 的对账条目；false/缺省=本轮新问题。收敛闸据此判定旧账是否清零（漏标=false=视为新问题，方向安全）。 */
     legacy?: boolean;
+    /** 重放取证（PR2，可选）：评审者声称跑过的命令 + 原始输出存档（绝对路径，首行 [exit code: N]）+ 声明退出码。 */
+    evidence?: {
+        file: string;
+        command: string;
+        exit: number;
+    };
 }
 /** TDD 硬要求证据（评审时收集的测试相关元信息）。 */
 export interface TddEvidence {
@@ -53,7 +59,7 @@ export interface ReviewEvidence {
         kbUrl: string;
     };
 }
-export type EventKind = 'chain/created' | 'chain/executing' | 'chain/completed' | 'chain/aborted' | 'chain/blocked' | 'chain/root-task-set' | 'chain/audit-warning' | 'chain/audit-confirmed' | 'chain/title-updated' | 'chain/im-delivery-failed' | 'spec-card/created' | 'spec-card/edited' | 'spec-card/approved' | 'task/created' | 'task/claimed' | 'task/heartbeat' | 'task/commented' | 'task/completed' | 'task/blocked' | 'task/unblocked' | 'task/archived' | 'task/gate-passed' | 'task/gate-failed' | 'task/failed' | 'task/renamed' | 'review/passed' | 'review/failed' | 'review/gave-up' | 'review/waived' | 'chain/reopened';
+export type EventKind = 'chain/created' | 'chain/executing' | 'chain/completed' | 'chain/aborted' | 'chain/blocked' | 'chain/root-task-set' | 'chain/audit-warning' | 'chain/audit-confirmed' | 'chain/title-updated' | 'chain/im-delivery-failed' | 'spec-card/created' | 'spec-card/edited' | 'spec-card/approved' | 'task/created' | 'task/claimed' | 'task/heartbeat' | 'task/commented' | 'task/completed' | 'task/blocked' | 'task/unblocked' | 'task/archived' | 'task/gate-passed' | 'task/gate-failed' | 'task/gate-skipped' | 'task/failed' | 'task/renamed' | 'review/passed' | 'review/failed' | 'review/gave-up' | 'review/waived' | 'review/evidence-check' | 'chain/reopened';
 export interface SpecCardSections {
     problem: string;
     solution: string;

package/lib/roles/preset-installer.d.ts

@@ -6,3 +6,17 @@ export declare function userPresetsRoot(): string;
  *  尽力而为：单 preset 写失败（用户预设根不可写等）仅告警不抛出，
  *  后续 agentPresets.mount('kanban-<role>') 失败由 runner 降级日志兜底。 */
 export declare function installRolePresets(): string[];
+/** 角色 preset 挂载的容器面（dsh-agent-presets roster 的最小结构类型）。 */
+export interface PresetMountLike {
+    mount(ctx: unknown, id: string): Promise<unknown>;
+    /** 官方重链入口（0.1.2-rc.1 起提供）：已绑定 → binding.rebind；未绑定 → bind。 */
+    recompose?(ctx: unknown, id: string): Promise<unknown>;
+}
+/**
+ * preset 挂载收敛入口（2026-09-21 事故修复）：宿主 dsh-scope 的 scope key 绑定在进程
+ * 生命周期内一次性（bindScopeParent 重复调用抛 "already bound to a parent"），官方重链
+ * 入口是 recompose（已绑 → binding.rebind）。同 agentKey 的二次 setup（P/W/D 卡 blocked/
+ * unblock 多轮唤醒 resume 同一 session、live 复用 re-setup 补挂）此前直接二次 mount 必炸。
+ * 收敛语义：mount 失败且系 already-bound → recompose 重链；其余错误（组合不可用等）原样上抛。
+ */
+export declare function mountOrRecompose(presets: PresetMountLike, agentCtx: unknown, presetId: string): Promise<void>;

package/lib/roles/preset-installer.js

@@ -51,3 +51,20 @@ export function installRolePresets() {
     }
     return installed;
 }
+/**
+ * preset 挂载收敛入口（2026-09-21 事故修复）：宿主 dsh-scope 的 scope key 绑定在进程
+ * 生命周期内一次性（bindScopeParent 重复调用抛 "already bound to a parent"），官方重链
+ * 入口是 recompose（已绑 → binding.rebind）。同 agentKey 的二次 setup（P/W/D 卡 blocked/
+ * unblock 多轮唤醒 resume 同一 session、live 复用 re-setup 补挂）此前直接二次 mount 必炸。
+ * 收敛语义：mount 失败且系 already-bound → recompose 重链；其余错误（组合不可用等）原样上抛。
+ */
+export async function mountOrRecompose(presets, agentCtx, presetId) {
+    try {
+        await presets.mount(agentCtx, presetId);
+    }
+    catch (err) {
+        if (!String(err).includes('already bound to a parent') || typeof presets.recompose !== 'function')
+            throw err;
+        await presets.recompose(agentCtx, presetId);
+    }
+}

package/lib/roles/toolsets.d.ts

@@ -54,33 +54,40 @@ export declare function unregisterDtTaskChain(taskId: string): void;
 export interface SubagentGuardDeps {
     /** kbn-<taskId> → chainId 同步解析（缺省用 module 缓存；测试注入用）。 */
     getTaskChainId?(taskId: string): string | undefined;
+    /** 会话 preset 读取（生产由 dispatcher 注入 session-preset.ts 的统一实现；缺省回落 header
+     *  ——创建事实，仅供测试/未接线场景保留既有行为）。 */
+    readPreset?(agent: unknown): string;
 }
-/** 全局子代理写护栏：仅 DT 角色会话的"子代理"（agentPreset === 'kanban-dt' 且
+/** 全局子代理写护栏：仅 DT 角色会话的"子代理"（preset === 'kanban-dt' 且
  *  header.parentSession 为 kbn-<taskId> 前缀）应用 buildDTWriteGuard。判据：parentSession
  *  缺失或非 kbn- 前缀 → 放行（DT 父会话自身或无关会话；DT 父会话只读由 agent.ctx guard
  *  兜底，双保险）。repoRoot 取子代理 header.cwd（继承 DT 会话 cwd=评审目标仓库）；缺省
  *  '/'（写标记全拦的保守形态）。chainId 从 parentSession（kbn-<taskId>）解析；解析不到
- *  → 空（wiki_write fail-closed 全拒，源码写拦截不受影响）。 */
+ *  → 空（wiki_write fail-closed 全拒，源码写拦截不受影响）。
+ *  preset 判定经 deps.readPreset（统一实现）：子代理继承父组合，引擎真相同样有答案；
+ *  header.parentSession 仍是创建事实（子代理会话由 agent-runner 建，不存在空白期改 preset 的窗口）。 */
 export declare function buildSubagentTreeGuard(deps?: SubagentGuardDeps): (execution: {
     name?: string;
     arguments?: unknown;
     agent?: unknown;
 }) => string | undefined;
-/** 蜂群模式主会话硬闸：全局 guard，按 header.agentPreset==='swarm'
- *  精准判定（先例 buildSubagentTreeGuard）。swarm 会话 = 扩权参数教学拦截（宿主 bash/write/edit
+/** 蜂群模式主会话硬闸：全局 guard，按会话 preset==='swarm'
+ *  精准判定（先例 buildSubagentTreeGuard）。**必须用统一 preset 读面**：web「蜂群模式」标签会话的
+ *  header 落宿主默认 'ptc'（2026-09-17 实测），只读 header 会让本闸对目标会话整体失效。
+ *  swarm 会话 = 扩权参数教学拦截（宿主 bash/write/edit
  *  schema 广播 sandbox_permissions/justification，模型带参重试会触发天花板会话 approveEscalation
  *  死循环——独立 DT 同款拦截）+ git 反选（与独立 DT 共用 GIT_MUTATION_VERBS/dualVerbGitDenyReason，
  *  buildPlanWriteGuard 同款分段提取判定，跳过 git 全局选项、提取不到动词 fail-closed，先行判定——
  *  git 变更动词多数同时命中只读基座的写标记，须以 swarm-guard 文案优先返回）+ 只读基座
  *  （buildReadOnlyWriteGuard：直接写工具全名拦截 + bash/run_code 写标记）。其余会话恒放行
  *  （角色会话自有 agent scope 护栏兜底，双保险不叠加）。 */
-export declare function buildSwarmSessionGuard(): (execution: {
+export declare function buildSwarmSessionGuard(deps?: SubagentGuardDeps): (execution: {
     name?: string;
     arguments?: unknown;
     agent?: unknown;
 }) => string | undefined;
 /** 独立评审（standalone DT）全局硬闸。独立会话判定（同时成立）：
- *  header.agentPreset === 'kanban-dt'、未经角色组合标记（!isRoleComposed）、parentSession
+ *  会话 preset === 'kanban-dt'（经 deps.readPreset 统一读面）、未经角色组合标记（!isRoleComposed）、parentSession
  *  非 kbn- 前缀（与 buildSubagentTreeGuard 判据对齐：有 kbn- parentSession 的是链上系
  *  DT 子代理，交由该 guard 管——其 incarnation 可能无组合标记、宿主 id 也可能非 kbn-
  *  前缀，漏判会把链评审写入误当独立模式拒掉）、且（能从 execution.agent 取到 session
@@ -102,13 +109,17 @@ export declare function buildSwarmSessionGuard(): (execution: {
  *  5. 其余工具（read/glob/grep/ocr_review/wiki_read/wiki_search 等）→ 放行。 */
 /** wiki_write 会话级放行 preset 默认白名单：与 config.ts wikiWritePresets 默认值同源，
  *  仅供 guard deps 未接线（测试/裸调用）时兜底；生产经 dispatcher 注入热读配置。
- *  'ptc'（2026-09-16 实测）：dsh web「蜂群模式」标签会话的 header.agentPreset 实际为
- *  宿主内置 PTC 模式 id 'ptc'（presets/ptc，非插件 'swarm'）——UI 标签与 header id 不同源。 */
+ *  'ptc'：普通（PTC 模式）会话亦可写 wiki 命名空间——写面本身由 wiki_write 工具内的
+ *  五类命名空间白名单硬约束；2026-09-17 起 preset 判定走统一读面（session-preset.ts），
+ *  'ptc' 不再是「蜂群会话被误读成 ptc」的兜底，而是显式放行普通会话。 */
 export declare const DEFAULT_WIKI_WRITE_PRESETS: ReadonlyArray<string>;
 export interface StandaloneDtGuardDeps {
     /** wiki_write 放行 preset 白名单热读（dispatcher 注入 () => getEffective().wikiWritePresets；
      *  缺省回落 DEFAULT_WIKI_WRITE_PRESETS——测试与未接线场景保持默认行为）。 */
     getWikiWritePresets?: () => ReadonlyArray<string>;
+    /** 会话 preset 读取（生产由 dispatcher 注入 session-preset.ts 的统一实现；缺省回落 header
+     *  ——创建事实，仅供测试/未接线场景保留既有行为）。 */
+    readPreset?(agent: unknown): string;
 }
 export declare function buildStandaloneDtGuard(deps?: StandaloneDtGuardDeps): (execution: {
     name?: string;

package/lib/roles/toolsets.js

@@ -5,6 +5,7 @@ import { isInsideKbRoot, ensureLocalKbRoot } from '../wiki/local-kb.js';
 import { LocalWikiClient } from '../wiki/local-kb-client.js';
 import { isStandaloneReviewNamespacePath } from '../domain/ocr-review.js';
 import { isRoleComposed } from '../dispatcher/agent-runner.js';
+import { headerPresetOf } from '../dispatcher/session-preset.js';
 import { ESCALATION_PARAM_KEYS } from './clean-fs-tools.js';
 export { isRoleComposed };
 import { buildKanbanTools } from '../tools/kanban-tools.js';
@@ -437,16 +438,19 @@ function extractSessionHeader(agent) {
     const h = a?.session?.header;
     return h && typeof h === 'object' ? h : undefined;
 }
-/** 全局子代理写护栏：仅 DT 角色会话的"子代理"（agentPreset === 'kanban-dt' 且
+/** 全局子代理写护栏：仅 DT 角色会话的"子代理"（preset === 'kanban-dt' 且
  *  header.parentSession 为 kbn-<taskId> 前缀）应用 buildDTWriteGuard。判据：parentSession
  *  缺失或非 kbn- 前缀 → 放行（DT 父会话自身或无关会话；DT 父会话只读由 agent.ctx guard
  *  兜底，双保险）。repoRoot 取子代理 header.cwd（继承 DT 会话 cwd=评审目标仓库）；缺省
  *  '/'（写标记全拦的保守形态）。chainId 从 parentSession（kbn-<taskId>）解析；解析不到
- *  → 空（wiki_write fail-closed 全拒，源码写拦截不受影响）。 */
+ *  → 空（wiki_write fail-closed 全拒，源码写拦截不受影响）。
+ *  preset 判定经 deps.readPreset（统一实现）：子代理继承父组合，引擎真相同样有答案；
+ *  header.parentSession 仍是创建事实（子代理会话由 agent-runner 建，不存在空白期改 preset 的窗口）。 */
 export function buildSubagentTreeGuard(deps = {}) {
+    const readPreset = deps.readPreset ?? headerPresetOf;
     return (execution) => {
         const header = extractSessionHeader(execution?.agent);
-        if (!header || header.agentPreset !== 'kanban-dt')
+        if (!header || readPreset(execution?.agent) !== 'kanban-dt')
             return undefined;
         // 仅真实子代理（parentSession 为 kbn- 前缀）受全局护栏约束；DT 父会话自身
         // parentSession 是主会话或缺失（非 kbn- 前缀），chainId 解析不到 → 空，若误拦
@@ -461,18 +465,21 @@ export function buildSubagentTreeGuard(deps = {}) {
         return buildDTWriteGuard(repoRoot, chainId)(execution);
     };
 }
-/** 蜂群模式主会话硬闸：全局 guard，按 header.agentPreset==='swarm'
- *  精准判定（先例 buildSubagentTreeGuard）。swarm 会话 = 扩权参数教学拦截（宿主 bash/write/edit
+/** 蜂群模式主会话硬闸：全局 guard，按会话 preset==='swarm'
+ *  精准判定（先例 buildSubagentTreeGuard）。**必须用统一 preset 读面**：web「蜂群模式」标签会话的
+ *  header 落宿主默认 'ptc'（2026-09-17 实测），只读 header 会让本闸对目标会话整体失效。
+ *  swarm 会话 = 扩权参数教学拦截（宿主 bash/write/edit
  *  schema 广播 sandbox_permissions/justification，模型带参重试会触发天花板会话 approveEscalation
  *  死循环——独立 DT 同款拦截）+ git 反选（与独立 DT 共用 GIT_MUTATION_VERBS/dualVerbGitDenyReason，
  *  buildPlanWriteGuard 同款分段提取判定，跳过 git 全局选项、提取不到动词 fail-closed，先行判定——
  *  git 变更动词多数同时命中只读基座的写标记，须以 swarm-guard 文案优先返回）+ 只读基座
  *  （buildReadOnlyWriteGuard：直接写工具全名拦截 + bash/run_code 写标记）。其余会话恒放行
  *  （角色会话自有 agent scope 护栏兜底，双保险不叠加）。 */
-export function buildSwarmSessionGuard() {
+export function buildSwarmSessionGuard(deps = {}) {
+    const readPreset = deps.readPreset ?? headerPresetOf;
     return (execution) => {
         const header = extractSessionHeader(execution?.agent);
-        if (!header || header.agentPreset !== 'swarm')
+        if (!header || readPreset(execution?.agent) !== 'swarm')
             return undefined;
         const name = String(execution?.name ?? '');
         const args = execution?.arguments ?? {};
@@ -565,7 +572,7 @@ function dualVerbGitDenyReason(verb, rest, deny) {
     }
 }
 /** 独立评审（standalone DT）全局硬闸。独立会话判定（同时成立）：
- *  header.agentPreset === 'kanban-dt'、未经角色组合标记（!isRoleComposed）、parentSession
+ *  会话 preset === 'kanban-dt'（经 deps.readPreset 统一读面）、未经角色组合标记（!isRoleComposed）、parentSession
  *  非 kbn- 前缀（与 buildSubagentTreeGuard 判据对齐：有 kbn- parentSession 的是链上系
  *  DT 子代理，交由该 guard 管——其 incarnation 可能无组合标记、宿主 id 也可能非 kbn-
  *  前缀，漏判会把链评审写入误当独立模式拒掉）、且（能从 execution.agent 取到 session
@@ -587,23 +594,26 @@ function dualVerbGitDenyReason(verb, rest, deny) {
  *  5. 其余工具（read/glob/grep/ocr_review/wiki_read/wiki_search 等）→ 放行。 */
 /** wiki_write 会话级放行 preset 默认白名单：与 config.ts wikiWritePresets 默认值同源，
  *  仅供 guard deps 未接线（测试/裸调用）时兜底；生产经 dispatcher 注入热读配置。
- *  'ptc'（2026-09-16 实测）：dsh web「蜂群模式」标签会话的 header.agentPreset 实际为
- *  宿主内置 PTC 模式 id 'ptc'（presets/ptc，非插件 'swarm'）——UI 标签与 header id 不同源。 */
+ *  'ptc'：普通（PTC 模式）会话亦可写 wiki 命名空间——写面本身由 wiki_write 工具内的
+ *  五类命名空间白名单硬约束；2026-09-17 起 preset 判定走统一读面（session-preset.ts），
+ *  'ptc' 不再是「蜂群会话被误读成 ptc」的兜底，而是显式放行普通会话。 */
 export const DEFAULT_WIKI_WRITE_PRESETS = ['swarm', 'kanban-w', 'ptc'];
 export function buildStandaloneDtGuard(deps = {}) {
+    const readPreset = deps.readPreset ?? headerPresetOf;
     return (execution) => {
         const header = extractSessionHeader(execution?.agent);
         const name = String(execution?.name ?? '');
         const agent = execution?.agent;
         const sessionId = typeof agent?.id === 'string' ? agent.id : undefined;
+        const preset = readPreset(execution?.agent);
         // 链上系 DT 子代理（parentSession 为 kbn-<taskId> 前缀）：交由 buildSubagentTreeGuard 管，
         // 本 guard 不按独立模式收紧、也不在非独立分支拒其 wiki_write（链评审目录写入归该 guard 校验）。
         const isDtChainSubagent = !!header
-            && header.agentPreset === 'kanban-dt'
+            && preset === 'kanban-dt'
             && typeof header.parentSession === 'string'
             && header.parentSession.startsWith('kbn-');
         const standalone = !!header
-            && header.agentPreset === 'kanban-dt'
+            && preset === 'kanban-dt'
             && !isRoleComposed(execution?.agent)
             && !isDtChainSubagent
             && !(sessionId !== undefined && sessionId.startsWith('kbn-'));
@@ -659,12 +669,11 @@ export function buildStandaloneDtGuard(deps = {}) {
             // 白名单硬约束；local 模式 wiki_write 未全局注册，无工具面即无暴露面。
             // 放行面配置化（硬规则 6）：白名单经 deps 热读 config.wikiWritePresets，宿主 preset
             // 体系演化/部署自定义模式 id 时改配置即可；config 缺字段回 []（fail-closed，仅内置默认兜底测试）。
-            const preset = header?.agentPreset;
             const allowed = deps.getWikiWritePresets?.() ?? DEFAULT_WIKI_WRITE_PRESETS;
-            if (preset !== undefined && allowed.includes(preset))
+            if (preset !== '' && allowed.includes(preset))
                 return undefined;
             // 诊断尾巴：报错带实际 preset（或"无"），用户重试一次即可定位会话模式判定缺口
-            return 'wiki-write-restricted-to-reviewer-sessions: wiki_write 仅限 DT 评审会话 / W 角色 / swarm 主会话使用（当前会话 preset=' + (preset ?? '无') + '）';
+            return 'wiki-write-restricted-to-reviewer-sessions: wiki_write 仅限 DT 评审会话 / W 角色 / swarm 主会话使用（当前会话 preset=' + (preset || '无') + '）';
         }
         return undefined;
     };

package/lib/services/evidence-replay.d.ts

@@ -0,0 +1,28 @@
+import { type runOne } from './gate-runner.js';
+import { type EvidenceState } from '../domain/evidence-check.js';
+export interface EvidenceCheckResult {
+    title: string;
+    severity: string;
+    state: EvidenceState;
+    detail: string;
+}
+/** 沿父链找最近 execute 卡的 worktree_dir（重放 cwd=被评审代码所在处）。 */
+export declare function resolveTargetWorktree(parents: Array<{
+    assignee: string;
+    mode: string;
+    metadata?: Record<string, unknown>;
+}>): string | null;
+interface ReplayCfg {
+    replayEnabled: boolean;
+    timeoutMs: number;
+    allowPrefixes: string[];
+    /** 黑名单子串预检（沿用 gates.forbidden 纵深，评审 Important：不得清空）。 */
+    forbidden?: string[];
+    worktreeDir: string | null;
+    readFile: (p: string) => Promise<string | null>;
+    run?: typeof runOne;
+}
+export declare function checkIssueEvidence(input: {
+    issues: unknown;
+} & ReplayCfg): Promise<EvidenceCheckResult[]>;
+export {};