@joekytc/dsh-swarm 0.1.2 → 0.3.0

package/lib/dispatcher/agent-runner.js

@@ -1,41 +1,101 @@
 import { SessionId } from '@deepseek-ai/dsh-session';
-import { installRoleTools, buildReadOnlyWriteGuard, buildDTWriteGuard, buildPlanWriteGuard, registerDtTaskChain, unregisterDtTaskChain } from '../roles/toolsets.js';
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { probeOcr } from '../services/ocr-cli.js';
+import { installRoleTools, buildReadOnlyWriteGuard, buildDTWriteGuard, buildPlanWriteGuard, buildKbWriteGuard, registerDtTaskChain, unregisterDtTaskChain } from '../roles/toolsets.js';
+import { ensureLocalKbRoot } from '../wiki/local-kb.js';
+import { installCleanFsTools } from '../roles/clean-fs-tools.js';
 import { buildModelCandidates, isModelUnavailableError } from './model-candidates.js';
-import { attachSessionToWorkspace, resolveOrCreateWorkspace } from './workspace-attach.js';
 import { toolName } from './session-events.js';
+import { attachSessionToWorkspace, resolveOrCreateWorkspace } from './workspace-attach.js';
 import { isPathInside, resolveTargetRepoDir } from './target-repo.js';
 import { injectGitCredentials, resolveGitPatFromCtx } from './git-credentials.js';
-/** M3(B)：目标仓库在会话工作空间外、已 claim+block 等待用户授权且尚未建会话的任务集合（key=taskId）。
+/** 目标仓库在会话工作空间外、已 claim+block 等待用户授权且尚未建会话的任务集合（key=taskId）。
  *  人工放行后再次调度会重新询问；已授权后从集合移除。仅进程内记忆，重启后从事件日志恢复（block 事件仍在）。 */
 const permissionBlockedTasks = new Set();
-/** D4 goal 条件启用（spec FR6）：spec 卡六段或父交接命中关键词 → 注入目标模式指令。 */
+/** goal 条件启用：spec 卡六段或父交接命中关键词 → 注入目标模式指令。 */
 const GOAL_MODE_KEYWORDS = ['/goal', '目标模式', 'goal mode'];
-/** RC4：瞬时基础设施错误（会话 live 锁/网络超时）与任务质量失败区分——infra 不计入 attempts 重试预算。 */
+/** 瞬时基础设施错误（会话 live 锁/网络超时）与任务质量失败区分——infra 不计入 attempts 重试预算。 */
 function isInfraError(err) {
     return /cannot prepare session|while it is live|timeout|ETIMEDOUT|ECONNREFUSED|ECONNRESET|socket/i.test(String(err));
 }
+/** 关键事件追加落盘 storageDir/dispatcher.log（与 dispatcher.ts 同一文件、同一行格式）——
+ *  agent-runner 未注入 logFile，按 dispatcher 同款方式经 configProvider 派生 storageDir；
+ *  写失败静默忽略（日志只是观测面，事件日志才是事实源）。 */
+function logToDispatcherLog(configProvider, msg) {
+    try {
+        const storageDir = configProvider.getEffective().storageDir.replace('$DSH_HOME', process.env.DSH_HOME ?? process.cwd());
+        writeFileSync(join(storageDir, 'dispatcher.log'), new Date().toISOString() + ' ' + msg + '\n', { flag: 'a' });
+    }
+    catch { /* 忽略写失败 */ }
+}
+/** 组合标记存储：按 Agent 实例（incarnation）键控的进程内 WeakMap。
+ *  机制取舍（探明宿主 lib 后确定）：
+ *  - 不用 session.append('kanban/role-composition')：自定义事件类型不在宿主 KNOWN_SESSION_EVENT_TYPES
+ *    （dsh-session/lib/types/known-event-types.js），持久化读路径 assertEventsSupported
+ *    （dsh-session-persistence/lib/index.js:1117）对未标 ignorable 的未知类型整份拒绝加载
+ *    （SessionFormatUnsupportedError）→ 会话日志变成无法 resume 的毒日志；且 append 公共 API
+ *    不暴露 ignorable 信封字段，无法规避。
+ *  - 不用 agentCtx.provide：cordis 服务 store 的 isolate 键解析到根作用域
+ *    （cordis/lib/index.js provide → ctx.root[symbols.isolate][name]），多 agent 同名 provide 冲突。
+ *  - WeakMap 按 incarnation 键控：GUI 重开同名会话是新 Agent 实例 → 查不到标记 → 不盲用；
+ *    实例被回收标记随 GC 消失，无泄漏。 */
+const roleCompositions = new WeakMap();
+/** 写入角色组合标记（setup 在 installRoleTools 成功后调用；导出仅供测试直接构造标记场景）。 */
+export function markRoleComposition(agent, marker) {
+    if (agent && typeof agent === 'object')
+        roleCompositions.set(agent, marker);
+}
+/** 只读判定：该 agent incarnation 是否带角色组合标记（全局 guard 消费；不读 marker 内容）。
+ *  与 markRoleComposition 同一 WeakMap 单一事实源；未标记 incarnation（GUI 新开/子代理）
+ *  返回 false。 */
+export function isRoleComposed(agent) {
+    return !!agent && typeof agent === 'object' && roleCompositions.has(agent);
+}
 /** 每任务一次性角色 agent：创建/resume、上下文组装、协议违规检测。 */
 export class AgentRunner {
     ctx;
     kanban;
-    config;
+    configProvider;
     wiki;
     defaultModel;
-    constructor(ctx, kanban, config, wiki, defaultModel) { this.ctx = ctx; this.kanban = kanban; this.config = config; this.wiki = wiki; this.defaultModel = defaultModel; }
+    probeOcrFn;
+    constructor(ctx, kanban, configProvider, wiki, defaultModel, deps) {
+        this.ctx = ctx;
+        this.kanban = kanban;
+        this.configProvider = configProvider;
+        this.wiki = wiki;
+        this.defaultModel = defaultModel;
+        this.probeOcrFn = deps?.probeOcrFn ?? probeOcr;
+    }
     buildContext(task, state, resume) {
         const parts = [`# Task ${task.id}: ${task.title}`, `assignee=${task.assignee} mode=${task.mode}`];
-        // Q3：权限提示仅对受限角色显示（v 无写、d/execute 全权、p/w 全权但受工具级写护栏约束——写边界不靠 prompt 软约束）
+        // 权限提示仅对受限角色显示（v 无写、d/execute 全权、p/w 全权但受工具级写护栏约束——写边界不靠 prompt 软约束）
         if (task.assignee !== 'v' && !(task.assignee === 'd' && task.mode === 'execute') && task.assignee !== 'p' && task.assignee !== 'w') {
             parts.push('权限提示：你的权限范围固定在会话工作区（workspace-write），越权操作（如 sandbox_permissions 升级写工作区外）会被自动拒绝且不可重试。遇到拒绝不要重试被拒操作，改用工作区内可行方式记录结果，然后调用 kanban_complete。');
         }
-        // A3/B5：D(execute) = 唯一执行者（danger-full-access，无权限提示）——目标仓库内实际写代码 + git 提交推送
+        // D(execute) = 唯一执行者（danger-full-access，无权限提示）——目标仓库内实际写代码 + git 提交推送
         if (task.assignee === 'd' && task.mode === 'execute') {
             parts.push('## 执行者职责\n你是链路唯一执行者（不是只读对齐/校验）：在目标仓库（见 Body 的 TARGET_REPO）内 git worktree/branch → 按规格卡 solution/testing 改代码/README → git commit → git push → 自检（跑测试/构建）。本会话为 full-access（可写目标仓库与 git 凭据已注入），不要做只读对齐/校验交差。调用 kanban_complete 时 metadata 必须带 git 产物证据：changed_files（数组）+ commit_hash 与 push 至少其一，否则完成会被拒绝、链路不会收尾。');
         }
         if (task.body)
             parts.push(`## Body
 ${task.body}`);
-        // P1-1：规格卡六段 + 附件注入（经 Chain.specCardId），角色 agent 的输入契约，原汁原味
+        // W local KB 模式：注入本地库根 + llm-wiki 用法 + 排序原则 + 交付约定（remote 模式不注入）。
+        // 库内复制/移动补句：DIRECT cp/mv/mkdir 工具永远匹配不到 KB 目标（无 path/file_path
+        // 实参）会被护栏拒绝——必须显式指引 W 用 write 工具做库内复制/移动。
+        if (task.assignee === 'w' && this.configProvider.mode === 'local') {
+            const kbRoot = ensureLocalKbRoot();
+            parts.push('## 知识库（本地模式）', `- 本地库根：${kbRoot}（llm-wiki 原生结构；只读仓库源码，唯一可写区域为该库根）；库内复制/移动一律用 write 工具（cp/mv 会被护栏拒绝）`, '- 经 skill 工具加载 llm-wiki 完成查写（query/ingest/crystallize）；库未初始化时先按其 init 工作流初始化（幂等）', '- 检索排序原则：相关性优先 7 : 新鲜度 3', '- 交付：page_path = 库根下 wiki/** 相对路径（如 wiki/sources/ch_<chainId>/t_<taskId>.md）；kb_url = 空串', '- 本地模式不 ingest 外部 URL；wiki_search/wiki_read/wiki_write 不可用（未注册）');
+        }
+        // D/DT local 库根注入（审查修订）：d:execute local 文案称「库根见运行时上下文」，
+        // 此处必须真的注入，否则 D 不知道去哪读计划；DT fs 写评审页同理。
+        if ((task.assignee === 'd' || task.assignee === 'dt') && this.configProvider.mode === 'local') {
+            parts.push('## 本地知识库（local KB mode）', `- 本地库根：${ensureLocalKbRoot()}`, task.assignee === 'd'
+                ? '- 实施计划原文 = 父任务交接 page_path（库根下 wiki/** 相对路径）→ 直接 fs 读 <库根>/<page_path>；KB 经验召回经 skill 工具加载 llm-wiki（本地库）'
+                : '- 评审页经 fs 写 <库根>/wiki/queries/ch_<chainId>/review/<name>.md（库根外一律只读）');
+        }
+        // 规格卡六段 + 附件注入（经 Chain.specCardId），角色 agent 的输入契约，原汁原味
         const chain = state.chains.get(task.chainId);
         const specCard = chain?.specCardId ? state.specCards.get(chain.specCardId) : null;
         if (specCard) {
@@ -56,7 +116,7 @@ ${task.body}`);
                 parts.push(`- metadata: ${JSON.stringify(h.metadata)}`);
             }
         }
-        // 0.1.0 delegation（spec FR6）：D(execute) 目标模式条件注入——spec 卡/父交接命中
+        // 0.1.0 delegation：D(execute) 目标模式条件注入——spec 卡/父交接命中
         // GOAL_MODE_KEYWORDS 才注入；否则默认执行（行为不变）。
         if (task.assignee === 'd' && task.mode === 'execute') {
             const specText = specCard
@@ -70,7 +130,7 @@ ${task.body}`);
             }
         }
         if (resume) {
-            // B2：resume 注入运行历史与上次失败原因（不只次数），返工/重试同会话可参考前因
+            // resume 注入运行历史与上次失败原因（不只次数），返工/重试同会话可参考前因
             const lastFail = state.events.filter((e) => e.taskId === task.id && e.kind === 'task/failed').at(-1);
             const reason = lastFail ? String(lastFail.payload['reason'] ?? '') : '';
             parts.push(`## Prior attempts: ${task.attempts} (resume session)` + (reason ? `\nlast failure: ${reason}` : ''));
@@ -126,12 +186,12 @@ ${task.body}`);
         // todo（V 建卡默认态，无父任务即就绪）/ ready / failed（重试）均可调度；其余状态拒
         if (task.status !== 'ready' && task.status !== 'todo' && task.status !== 'failed')
             throw new Error('task not schedulable: ' + task.status);
-        // 0.1.0 delegation（spec FR2）：DT 任务运行期注册 chainId（全局子代理 guard 的
+        // 0.1.0 delegation：DT 任务运行期注册 chainId（全局子代理 guard 的
         // wiki review namespace 同步解析源）；runTask 结束注销。
         if (task.assignee === 'dt')
             registerDtTaskChain(task.id, task.chainId);
         try {
-            // M2(Q5)+归组：角色会话 cwd 恒为主 agent 工作空间（Chain.workspaceDir）。
+            // 归组：角色会话 cwd 恒为主 agent 工作空间（Chain.workspaceDir）。
             // 缺失时询问用户注册工作区；仍不可得 → block('workspace-unknown')，绝不静默落 kanban 存储目录。
             const chain = state.chains.get(task.chainId);
             let sessionCwd = chain?.workspaceDir ?? null;
@@ -139,16 +199,16 @@ ${task.body}`);
                 sessionCwd = await resolveOrCreateWorkspace(this.ctx, null, 'task ' + task.id + ' ' + task.assignee + '/' + task.mode);
             }
             if (!sessionCwd) {
-                await this.kanban.comment(taskId, `链未绑定工作区（Chain.workspaceDir 缺失且用户未提供工作区路径）。请重新 ${this.config.prefixRoutes.plan} 绑定主 agent 工作空间后重试。`, 'system');
+                await this.kanban.comment(taskId, `链未绑定工作区（Chain.workspaceDir 缺失且用户未提供工作区路径）。请重新 ${this.configProvider.getEffective().prefixRoutes.plan} 绑定主 agent 工作空间后重试。`, 'system');
                 await this.kanban.claimTask(taskId, 'system');
                 await this.kanban.blockTask(taskId, 'workspace-unknown: 链未绑定工作区（Chain.workspaceDir 缺失）', 'system');
                 return;
             }
-            // R20 D(execute)：目标仓库解析（供 M3 前置授权判定 + B4 git 凭据注入目标 + 上下文）；
-            // 会话 cwd 不再指向仓库（会话必须在主 agent 工作空间，见 Q5）。
+            // D(execute)：目标仓库解析（供前置授权判定 + git 凭据注入目标 + 上下文）；
+            // 会话 cwd 不再指向仓库（会话必须在主 agent 工作空间）。
             const isDExecute = task.assignee === 'd' && task.mode === 'execute';
             const dRepo = isDExecute ? resolveTargetRepoDir(task, state, sessionCwd) : null;
-            // M3(B)：D 目标仓库在会话工作空间外 → 跑 D 前先询问用户是否允许（一次授权，D 以 full-access 执行不再逐次提示）。
+            // D 目标仓库在会话工作空间外 → 跑 D 前先询问用户是否允许（一次授权，D 以 full-access 执行不再逐次提示）。
             // 不允许/无询问通道 → claim+block 等待人工放行（状态机要求 running 才能 block）；
             // 放行后再次调度会重新询问。授权前不创建会话，permissionBlockedTasks 避免误走 resume。
             if (isDExecute && dRepo && !isPathInside(dRepo, sessionCwd)) {
@@ -162,7 +222,7 @@ ${task.body}`);
                 }
                 permissionBlockedTasks.delete(taskId);
             }
-            // B2：resume 判定 = 有运行历史（attempts>0 或存在 claimed 事件）且不是「无会话授权阻塞」的任务；
+            // resume 判定 = 有运行历史（attempts>0 或存在 claimed 事件）且不是「无会话授权阻塞」的任务；
             // 后者虽有 claimed 事件但从未创建会话，必须走 create 而非 resume（否则 resume 不存在会话抛错）。
             const hasRunHistory = !permissionBlockedTasks.has(taskId) &&
                 (task.attempts > 0 || state.events.some((e) => e.taskId === taskId && e.kind === 'task/claimed'));
@@ -174,7 +234,7 @@ ${task.body}`);
                 // 里的 reasoningEffort 不被宿主消费，新建角色会话思考等级会落回宿主默认。改走 DSH agent/request
                 // waterfall 逐请求强制（宿主 installModelSelection 同机制），作用域仅本角色会话；
                 // effort 可由 per-role config 覆盖，默认 'high'（与 model-candidates.ts 默认一致）。
-                const effort = this.config.roles?.models?.[task.assignee]?.reasoningEffort ?? 'high';
+                const effort = this.configProvider.getEffective().roles?.models?.[task.assignee]?.reasoningEffort ?? 'high';
                 const scoped = agentCtx;
                 scoped.on('agent/request', async (_payload, next) => {
                     // 异常不吞：await next() 失败原样向上抛
@@ -182,14 +242,14 @@ ${task.body}`);
                     return { ...resolved, reasoningEffort: effort };
                 });
                 // 角色 agent 等同委派子 agent：固定 approval=never（避免后台会话悬挂等审批）。
-                // Q3：P/W/D = full access（跨目录读：P 读仓库/外部实证、W 读计划、D 执行）；
+                // P/W/D = full access（跨目录读：P 读仓库/外部实证、W 读计划、D 执行）；
                 // 但 P 挂 plan 写护栏、W 挂只读护栏（写边界由工具级强制，防"改动源码"，不靠 prompt 软约束）；
                 // PT/DT/V → workspace-write（评审/编排最小权限，PT/DT 只读护栏由 ToolGuard 独立保证）。
                 const session = agentCtx.agent?.session;
                 session?.append?.('approval/policy', { policy: 'never', source: 'delegation' });
                 const fullAccess = isDExecute || task.assignee === 'p' || task.assignee === 'w';
                 session?.append?.('sandbox/mode', fullAccess ? { mode: 'danger-full-access', source: 'delegation' } : { mode: 'workspace-write', source: 'delegation' });
-                // 执行角色（P/W/D）先挂载 D22 裁剪 preset（kanban-p/w/d），把 shell/approval 等服务注入 agent scope；
+                // 执行角色（P/W/D）先挂载裁剪 preset（kanban-p/w/d），把 shell/approval 等服务注入 agent scope；
                 // 不再整包继承官方 code preset：bash/fs/fs-search 由裁剪组合装配，run_code/jobs/skill/goal/
                 // plan-mode/compaction/delegation/web/todo 按角色裁剪（组合文件随包分发 + 运行时安装到
                 // $DSH_HOME/.agent-presets/，见 preset-installer.ts）。否则官方 apply 会抛
@@ -208,30 +268,56 @@ ${task.body}`);
                         }
                     }
                 }
-                await installRoleTools(agentCtx, task.assignee, { kanban: this.kanban, wiki: this.wiki, taskId: task.id });
+                await installRoleTools(agentCtx, task.assignee, { kanban: this.kanban, wiki: this.wiki, taskId: task.id, kbMode: this.configProvider.mode });
+                // danger-full-access 会话（P、D(execute)）write/edit/bash 菜单去毒
+                // （agent scope shadow 注册干净版盖住宿主带毒版本 + execute 剥参转发，详见 src/roles/clean-fs-tools.ts）。
+                // 挂载点选在 setup 内、preset.mount 之后：shadow 需经 get(name, agent) 取 preset standing
+                // 祖先层里的宿主原定义（kanban-p/d 的 fs/bash 由 preset 提供），且必须在会话开始前完成注册。
+                // 仅 P 与 D(execute)：两者是 danger-full-access 天花板，escalation 参数无更宽可升（必被拒）；
+                // PT/DT 是 workspace-write（sandbox_permissions 扩权到天花板是合法功能，剥了破坏官方能力）；
+                // W 虽 fullAccess 但只读护栏全拒 write，shadow 无意义（最小挂载面，V 无执行工具不涉及）。
+                if (task.assignee === 'p' || isDExecute) {
+                    installCleanFsTools(agentCtx, agentCtx.agent);
+                }
+                // 组合标记——角色工具面成功组合后，把 { role, taskId } 记到进程内 WeakMap（键=Agent 实例）。
+                // 宿主探明：setup 收到的 agentCtx.agent 与发布后 agents.get(id) 返回的是同一 Agent 实例
+                // （dsh-agent types/index.d.ts:38 `agent?: Agent` 安装为 Agent.ctx own property），
+                // 故此处键入的实例即 resumeOrReuse 里 agents.get 命中的实例。agentCtx.agent 缺失（宿主变体）时
+                // 不写标记 → live 复用走工具面校验路径（kanban_complete 可见性），能力无损。
+                const liveAgent = agentCtx.agent;
+                if (liveAgent)
+                    markRoleComposition(liveAgent, { role: task.assignee, taskId: task.id });
                 // 只读评审角色（PT/DT）注册 ToolGuard：拦截 tracked source 写入 / git mutation / 含写标记 bash。
                 // 以 dsh-tools 类型为准：tools.guard(execution => reason|undefined)，execution.name/arguments 为实际字段。
                 if (task.assignee === 'pt' || task.assignee === 'dt') {
                     const repoRoot = dRepo ?? sessionCwd; // DT 评审目标仓库；PT 以会话工作区为只读边界
                     const toolsSvc = agentCtx.tools;
-                    // DT 额外叠加 wiki review namespace 收窄（projects/<chain>/review/）
+                    // DT 额外叠加 wiki review namespace 收窄（projects/<repoSlug>/<chain>/review/）；
+                    // local KB 模式：DT 改用 KB 写护栏（唯一可写区域=本地库根，评审页经 fs 写库根），
+                    // remote 模式仍用 DT 收窄护栏（库根外全只读 + review namespace）。
+                    const kbMode = this.configProvider.mode;
                     const guardFn = task.assignee === 'dt'
-                        ? buildDTWriteGuard(repoRoot, task.chainId)
+                        ? (kbMode === 'local' ? buildKbWriteGuard(ensureLocalKbRoot()) : buildDTWriteGuard(repoRoot, task.chainId))
                         : buildReadOnlyWriteGuard(repoRoot);
                     toolsSvc?.guard?.((e) => guardFn(e));
                 }
-                // Q3：P/W 挂写护栏（wsRoot = 链 workspaceDir = sessionCwd，同 PT/DT 解析方式）。
+                // P/W 挂写护栏（wsRoot = 链 workspaceDir = sessionCwd，同 PT/DT 解析方式）。
                 // P = plan 写护栏（openspec/changes/** 内可写，禁改源码）；W = 只读护栏（交付=读计划→wiki API，
-                // fs 零写——I2 起全名拦截，repo 外/workspace 内任意路径 fs 写一律拒，不再依赖 repoRoot 边界）。
+                // fs 零写——全名拦截，repo 外/workspace 内任意路径 fs 写一律拒，不再依赖 repoRoot 边界）。
                 // 挂载方式同 PT/DT：tools.guard 是注册方法（dsh-tools 类型），execution 以 { name, arguments } 传入。
                 if (task.assignee === 'p' || task.assignee === 'w') {
                     const toolsSvc = agentCtx.tools;
+                    // local KB 模式：W 改用 KB 写护栏（唯一可写区域=本地库根，交付页经 write 写库根），
+                    // remote 模式 W 仍只读护栏（fs 零写）；P 恒为 plan 写护栏（与 KB 模式无关）。
+                    const kbMode = this.configProvider.mode;
                     const guardFn = task.assignee === 'p'
                         ? buildPlanWriteGuard(sessionCwd)
-                        : buildReadOnlyWriteGuard(sessionCwd);
+                        : (kbMode === 'local' && task.assignee === 'w')
+                            ? buildKbWriteGuard(ensureLocalKbRoot())
+                            : buildReadOnlyWriteGuard(sessionCwd);
                     toolsSvc?.guard?.((e) => guardFn(e));
                 }
-                // M4：D(execute) 注入 git 凭据（repo-local http extraheader，GitLab glpat-* 用 oauth2 basic）。
+                // D(execute) 注入 git 凭据（repo-local http extraheader，GitLab glpat-* 用 oauth2 basic）。
                 // 由插件进程（不受 D 会话沙箱限制）写入 <repo>/.git/config；PAT 经 DSH 凭据服务/env 解析；
                 // 注入失败仅告警（用户自带凭据/SSH 的仓库不受影响），未配置 PAT 不注入。
                 if (isDExecute && dRepo) {
@@ -246,18 +332,31 @@ ${task.body}`);
                 }
             };
             try {
-                // R1：claim 后任何异常（buildContext/spawn）→ failTask（attempts+1）→ 调度器重派/看门狗熔断；
+                // claim 后任何异常（buildContext/spawn）→ failTask（attempts+1）→ 调度器重派/看门狗熔断；
                 // 不留 "running 无 agent" 悬挂。
                 await this.kanban.claimTask(taskId, 'system');
                 console.error('[dsh-swarm][debug] runner claimed ' + taskId + ' attempts=' + task.attempts);
+                // DT spawn 前预检：评审角色依赖 ocr CLI，缺失时模型会在会话内穷尽探活最后才 block（真实事故，
+                // 白烧 30+ 步整轮预算）。这里在 spawn 之前直接 block 终态等人工安装——不走 failTask（attempts+1
+                // 会触发重派，而重派前 ocr 依旧缺失，纯烧重试预算）。插在 buildContext/模型候选与 create/resume
+                // 分叉之前：resume 路径（有运行历史的复用/resume）同样先过预检。
+                // probeOcr 内部已吞掉一切异常（网络/权限等一律降级为 installed=false，永不 throw），此处天然 fail-closed。
+                if (task.assignee === 'dt') {
+                    const probe = await this.probeOcrFn();
+                    if (!probe.installed) {
+                        await this.kanban.blockTask(taskId, 'review-tool-unavailable: ocr 未安装——GUI 配置面板「评审引擎（ocr）」卡可一键安装，或终端执行 npm install -g @alibaba-group/open-code-review', 'system');
+                        logToDispatcherLog(this.configProvider, '[ocr-precheck] dt task=' + taskId + ' blocked: ocr not installed');
+                        return;
+                    }
+                }
                 context = this.buildContext(task, state, hasRunHistory);
-                // 模型候选链（Task 12）：primary + fallbacks，model/provider 不可用时静默切换下一候选；
+                // 模型候选链：primary + fallbacks，model/provider 不可用时静默切换下一候选；
                 // 全部候选不可用 → block(model-unavailable) 抛给用户；非 model 错误 → failTask（原逻辑）。
-                const candidates = buildModelCandidates(this.config, task.assignee, this.defaultModel);
+                const candidates = buildModelCandidates(this.configProvider.getEffective(), task.assignee, this.defaultModel);
                 if (candidates.length === 0) {
                     // 无任何候选配置：不传 agentOptions（用部署默认），单次尝试
                     agent = hasRunHistory
-                        ? await this.resumeOrReuse(this.ctx.get('agents'), task.resumeSessionId ?? `kbn-${taskId}`, { setup })
+                        ? await this.resumeOrReuse(this.ctx.get('agents'), task.resumeSessionId ?? `kbn-${taskId}`, { setup, role: task.assignee, taskId: task.id })
                         : (await this.ctx.get('agents').create({
                             sessionId: SessionId(`kbn-${taskId}`),
                             meta: { cwd: sessionCwd },
@@ -272,7 +371,7 @@ ${task.body}`);
                             // hasRunHistory → resumeOrReuse 直接返回 AgentLike（内部已解包 .agent）；create 返回 { agent } 需解包。
                             // 统一归一化为 AgentLike，避免二次解包（h.agent=undefined → if(!agent) 误标 failed）。
                             const h = hasRunHistory
-                                ? await this.resumeOrReuse(agents, task.resumeSessionId ?? `kbn-${taskId}`, { agentOptions: candidate, setup })
+                                ? await this.resumeOrReuse(agents, task.resumeSessionId ?? `kbn-${taskId}`, { agentOptions: candidate, setup, role: task.assignee, taskId: task.id })
                                 : (await agents.create({ sessionId: SessionId(`kbn-${taskId}`), meta: { cwd: sessionCwd }, agentOptions: candidate, setup })).agent;
                             agent = h;
                             // 切换成功且非首选 → 发可审计 model/fallback 评论（记录证据，不弹用户）
@@ -302,7 +401,7 @@ ${task.body}`);
                 }
             }
             catch (err) {
-                // P0-5/R1：claim/buildContext/spawn 失败也走 failed（attempts 递增）→ 调度器重派/看门狗熔断；不再让任务永久 claimed
+                // claim/buildContext/spawn 失败也走 failed（attempts 递增）→ 调度器重派/看门狗熔断；不再让任务永久 claimed
                 console.error('[dsh-swarm][debug] runner spawn error ' + taskId + ': ' + String(err));
                 try {
                     await this.kanban.failTask(taskId, 'runner-error: ' + String(err), 'system', { infra: isInfraError(err) });
@@ -315,6 +414,11 @@ ${task.body}`);
             }
             if (!agent)
                 return; // 防御：候选链耗尽已在上方 block(model-unavailable)/throw 处理
+            // 本轮增量事件基线——agent 拿到之后、followup 之前记录。
+            // 0.1.2（DSH-0.1.2-A4-03）：Session.events 已移除 → followup 前记录 seq 基线，
+            // snapshotEvents(eventsBase) 即「本轮新增事件」（排除旧 incarnation 持久化事件），
+            // 供 protocol_violation 时识别 comment-only 收尾（交付滞留 comments，会话10事故形态）。
+            const eventsBase = Number(agent.session.seq);
             // 归组：角色会话 attach 到 cwd 对应工作区（无则询问创建；失败不阻断）
             const attachId = task.resumeSessionId ?? `kbn-${task.id}`;
             await attachSessionToWorkspace(this.ctx, attachId, sessionCwd, 'task ' + task.id + ' ' + task.assignee + '/' + task.mode);
@@ -323,56 +427,63 @@ ${task.body}`);
                 console.error('[dsh-swarm][debug] runner followup sent ' + taskId);
                 await agent.whenIdle();
                 console.error('[dsh-swarm][debug] runner whenIdle resolved ' + taskId);
-                // 修复轮 6：session.events 条目形态为 {type, data:{name}}，name 在 data 下，需经 toolName 读取
-                const used = agent.session.events.some((e) => {
-                    const n = toolName(e);
-                    return n === 'kanban_complete' || n === 'kanban_block';
-                });
-                if (!used) {
-                    // 防御：任务可能已被其他路径完成/归档（终态），此时 blockTask 会抛非法转换（done --task/blocked-->）
-                    const fresh = await this.kanban.snapshot();
-                    const cur = fresh.tasks.get(taskId);
-                    const terminal = cur && (cur.status === 'done' || cur.status === 'archived');
-                    if (terminal) {
-                        console.error('[dsh-swarm][debug] runner skip block ' + taskId + ' status=' + (cur ? cur.status : 'gone'));
+                // 终态判据（session 10 事故修复）：whenIdle resolve 后一次 snapshot，只看任务真实状态——
+                // 不再扫 session.events 全历史工具名（旧 incarnation 的 kanban_* 事件会污染判据，
+                // 「历史上调过工具名」≠「本轮成功提交」，骗过检查后卡永驻 running）。
+                // 确定态（done/archived/blocked/failed，TaskStatus 全集见 src/domain/types.ts）→ 防御日志 skip：
+                // blocked 上再 block 抛非法转换；failed 交调度器重派，不做 violation block。
+                // 非确定态（running/ready/todo/triage）→ protocol_violation 流程（证据链保留）。
+                const fresh = await this.kanban.snapshot();
+                const cur = fresh.tasks.get(taskId);
+                const settled = !!cur &&
+                    (cur.status === 'done' || cur.status === 'archived' || cur.status === 'blocked' || cur.status === 'failed');
+                if (settled) {
+                    console.error('[dsh-swarm][debug] runner skip block ' + taskId + ' status=' + (cur ? cur.status : 'gone'));
+                }
+                else {
+                    // 协议违规护栏：连续 protocol_violation 阻塞 ≥ maxProtocolViolations（默认 2）后，
+                    // 下一次违规直接 gave_up（不再恢复，走 [blocked-final] 证据链抛给主 agent）。任意角色（含 pt/dt）统一。
+                    const maxPV = this.configProvider.getEffective().dispatcher?.maxProtocolViolations ?? 2;
+                    const priorViolations = fresh.events.filter((e) => e.taskId === taskId && e.kind === 'task/blocked' &&
+                        String(e.payload['reason'] ?? '').startsWith('protocol_violation')).length;
+                    const finalBlock = priorViolations >= maxPV;
+                    const reason = finalBlock
+                        ? 'gave_up: protocol_violation after ' + maxPV + ' review cycles without complete/block'
+                        : 'protocol_violation: idle without complete/block';
+                    await this.kanban.blockTask(taskId, reason, 'system');
+                    // comment-only 收尾显形——放 block 之后（保证 block 一定先发生，
+                    // 告警只追加在已阻塞卡上，不影响终态判据与 [blocked-final] 证据链快照）。
+                    // 本轮增量事件命中 kanban_comment（经 toolName 兼容读取落盘/live 两形态）且未成功提交
+                    // （能走到这里即终态判据已确认非确定态）→ 交付内容很可能滞留 comments，显形告警。
+                    const commentOnly = agent.session.snapshotEvents(eventsBase).some((e) => toolName(e) === 'kanban_comment');
+                    if (commentOnly) {
+                        await this.kanban.comment(taskId, '[comment-only-closeout] 本轮仅用 kanban_comment 交付（无 complete/block）。交付内容可能滞留 comments（如角色工具缺失/会话被错误复用）；请人工核对 comments 与产物后解除阻塞重派。', 'system');
                     }
-                    else {
-                        // 协议违规护栏：连续 protocol_violation 阻塞 ≥ maxProtocolViolations（默认 2）后，
-                        // 下一次违规直接 gave_up（不再恢复，走 [blocked-final] 证据链抛给主 agent）。任意角色（含 pt/dt）统一。
-                        const maxPV = this.config.dispatcher?.maxProtocolViolations ?? 2;
-                        const priorViolations = fresh.events.filter((e) => e.taskId === taskId && e.kind === 'task/blocked' &&
-                            String(e.payload['reason'] ?? '').startsWith('protocol_violation')).length;
-                        const finalBlock = priorViolations >= maxPV;
-                        const reason = finalBlock
-                            ? 'gave_up: protocol_violation after ' + maxPV + ' review cycles without complete/block'
-                            : 'protocol_violation: idle without complete/block';
-                        await this.kanban.blockTask(taskId, reason, 'system');
-                        if (finalBlock) {
-                            // [blocked-final] 证据链：block 时间线 + 复核/评论时间线 + 最终 reason（system 确定性写入）
-                            const evs = fresh.events.filter((e) => e.taskId === taskId);
-                            const blockTimeline = evs
-                                .filter((e) => e.kind === 'task/blocked')
-                                .map((e) => `  - seq=${e.seq} at=${e.at} author=${e.author} reason=${String(e.payload['reason'] ?? '')}`)
-                                .join('\n');
-                            const reviewTimeline = evs
-                                .filter((e) => e.kind === 'task/commented')
-                                .map((e) => `  - seq=${e.seq} at=${e.at} author=${e.author}: ${String(e.payload['body'] ?? '')}`)
-                                .join('\n');
-                            await this.kanban.comment(taskId, [
-                                '[blocked-final] 协议违规超护栏，任务不再自动恢复（人工解除后仍按 gave_up 终态处理）。',
-                                '## block 时间线',
-                                blockTimeline,
-                                '## 复核/评论时间线',
-                                reviewTimeline || '  - (无复核评论)',
-                                '最终原因: ' + reason,
-                            ].join('\n'), 'system');
-                        }
+                    if (finalBlock) {
+                        // [blocked-final] 证据链：block 时间线 + 复核/评论时间线 + 最终 reason（system 确定性写入）
+                        const evs = fresh.events.filter((e) => e.taskId === taskId);
+                        const blockTimeline = evs
+                            .filter((e) => e.kind === 'task/blocked')
+                            .map((e) => `  - seq=${e.seq} at=${e.at} author=${e.author} reason=${String(e.payload['reason'] ?? '')}`)
+                            .join('\n');
+                        const reviewTimeline = evs
+                            .filter((e) => e.kind === 'task/commented')
+                            .map((e) => `  - seq=${e.seq} at=${e.at} author=${e.author}: ${String(e.payload['body'] ?? '')}`)
+                            .join('\n');
+                        await this.kanban.comment(taskId, [
+                            '[blocked-final] 协议违规超护栏，任务不再自动恢复（人工解除后仍按 gave_up 终态处理）。',
+                            '## block 时间线',
+                            blockTimeline,
+                            '## 复核/评论时间线',
+                            reviewTimeline || '  - (无复核评论)',
+                            '最终原因: ' + reason,
+                        ].join('\n'), 'system');
                     }
                 }
             }
             catch (err) {
                 console.error('[dsh-swarm][debug] runner error ' + taskId + ': ' + String(err));
-                // 失败语义（P0-5 统一）：发 failed 事件（attempts 递增），由调度器重派或看门狗熔断；不直接 block。
+                // 失败语义（统一）：发 failed 事件（attempts 递增），由调度器重派或看门狗熔断；不直接 block。
                 // 防御：任务可能已被完成/归档（终态），failTask 会抛非法转换（done --task/failed-->）
                 try {
                     await this.kanban.failTask(taskId, 'runner-error: ' + String(err), 'system', { infra: isInfraError(err) });
@@ -387,17 +498,59 @@ ${task.body}`);
                 unregisterDtTaskChain(task.id);
         }
     }
-    /** RC2：resume 前先查 agents registry 同名会话是否仍 live——live 则直接复用（后续 followup 续用），
-     *  避免 block→unblock→重跑同一会话时 resume 抛 "cannot prepare session while it is live"
-     *  （对齐 VOrchestrator.getVAgent 的 live 复用逻辑）。agents.get 未实现 → 防御回退 resume。 */
+    /** resume 前先查 agents registry 同名会话是否仍 live——live 且组合标记匹配（role+taskId 一致）才复用。
+     *  会话10事故根因A：此前对 live agent 盲复用——GUI 打开同名会话产生的默认组合 incarnation
+     *  没有角色 preset/kanban_complete 工具面（setup 被跳过），模型只能把交付塞 kanban_comment。
+     *  现在标记缺失/不匹配时按宿主能力降级（探明结论）：
+     *  - (i) dispose 不可行：AgentHandle.dispose 仅创建者持有（dsh-agent types/index.d.ts:155-158，
+     *    "ctx.agents.get(id) still returns a bare Agent"），无从释放他人 incarnation。
+     *  - (ii) 修复可行（生产主路径）：Agent.ctx 公开（runtime-types.d.ts:72）且经它访问的 tools 注册表
+     *    可枚举/可注册（ToolRuntime.get(name, scope) 返回该 scope 可见定义；register 经 traced ctx 落到
+     *    该 agent 的 scope 层）→ 重跑 setup 幂等补挂（effort/approval/sandbox/preset/角色工具/护栏），
+     *    补挂后必须验证 kanban_complete 可见才算修复成功。kanban_complete 是所有 runner 角色
+     *    （p/w/d/pt/dt）都注册的任务工具，且全局面只读子集不含它（main-session-tools.ts:134），
+     *    故「scope 内可见 kanban_complete」⟺「该 incarnation 经我方角色 setup 组合过」。
+     *  - (iii) 兜底：工具注册表不可达（异常宿主/测试桩）→ 抛错走 failTask。错误信息刻意不含
+     *    isInfraError 关键词 → attempts+1 计入重试预算：每次重派都会撞同一个 live 错误 incarnation
+     *    直至重试预算耗尽——有界，不会形成无限重派循环（若误标 infra 则 attempts 不递增才会无限）。
+     *  agents.get 未实现 → 回退 resume（原行为不回归）。 */
     async resumeOrReuse(agents, sessionId, opts) {
         const live = agents.get?.(sessionId);
-        if (live)
-            return live;
-        const h = await agents.resume({ resumeSessionId: SessionId(sessionId), ...opts });
+        if (live) {
+            // 标记匹配（同 incarnation、同角色、同卡）→ 与 setup 组合完全一致 → 安全复用（原行为收窄版）
+            const marker = typeof live === 'object' && live !== null ? roleCompositions.get(live) : undefined;
+            if (marker && marker.role === opts.role && marker.taskId === opts.taskId)
+                return live;
+            // 标记缺失/不匹配 → 绝不盲用。工具注册表（live.ctx.tools，与 installRoleTools 同一访问路径）：
+            const liveCtx = live.ctx;
+            const toolsSvc = liveCtx ? liveCtx.tools : undefined;
+            if (toolsSvc?.get) {
+                if (toolsSvc.get('kanban_complete', live)) {
+                    // 工具面完备但标记缺失/不匹配：标记写入失败的历史 incarnation，或旧/手工数据把
+                    // resumeSessionId 指向同角色其它卡（注：2026-09-07 起 createReworkTask 不再继承源卡
+                    // resumeSessionId——返工卡走自己的 kbn-<id> 会话，此「跨卡复用」分支为 dead path 防御）——
+                    // 验证过工具面后复用，不重复补挂（重复 register 同名工具会被 dsh-tools 拒绝）。
+                    return live;
+                }
+                // GUI 默认组合 incarnation：缺 kanban_complete → 重跑 setup 幂等补挂后复用。
+                // setup 对 live ctx 的各步均可加：effort waterfall/approval+sandbox append（known 事件类型、
+                // latest-wins）/preset mount（bindings 覆盖）/角色工具（此前为默认组合，无同名冲突）/护栏。
+                await opts.setup(liveCtx);
+                if (toolsSvc.get('kanban_complete', live))
+                    return live; // 修复后必须验证到位，防静默半修复
+                throw new Error('live session composition repair failed: kanban_complete still missing after re-setup (session ' + sessionId + ')');
+            }
+            // (iii)：既无标记又无法访问工具注册表 → 拒绝盲复用（会复现事故），failTask 有界重试（见上）。
+            throw new Error('live session composition mismatch and unverifiable (no marker, no tool registry): ' + sessionId + ' — refusing blind reuse (incident root cause A)');
+        }
+        const { agentOptions, setup } = opts;
+        const resumeOpts = { resumeSessionId: SessionId(sessionId), setup };
+        if (agentOptions)
+            resumeOpts['agentOptions'] = agentOptions;
+        const h = await agents.resume(resumeOpts);
         return h.agent;
     }
-    /** M3(B)：D(execute) 目标仓库在会话工作空间外时，跑 D 前询问用户是否允许。
+    /** D(execute) 目标仓库在会话工作空间外时，跑 D 前询问用户是否允许。
      *  经 ctx.userQuestions（GUI 弹窗）单次询问；无询问通道或拒绝 → 返回 false（由调用方 claim+block 等待人工放行）。 */
     async requestRepoPermission(task, repo, sessionCwd) {
         const uq = this.ctx.get?.('userQuestions');

package/lib/dispatcher/chain-auditor.d.ts

@@ -1,13 +1,13 @@
 import type { KanbanService } from '../domain/kanban-service.js';
 import type { AuditEvidence, Task } from '../domain/types.js';
 /**
- * D23 链完成验收核对：Chain(completed) 时核对主会话是否越权写工作区产物。
+ * 链完成验收核对：Chain(completed) 时核对主会话是否越权写工作区产物。
  *
- * 数据源（修复轮 7，修复「评估项目只读排查 run_code 被误判为越权写产物」）：
+ * 数据源（修复「评估项目只读排查 run_code 被误判为越权写产物」）：
  * 1. 主会话会话事件扫描（primary，尽力而为）：枚举活 agent 注册表（ctx.agents.list），
  *    对 id 非 kbn-*（角色会话确定性 id：kbn-<taskId> / kbn-v-<chainId>）的会话，
  *    扫描其 session.events 中的工具调用。插件无法解析主会话真实 session id（路由只用
- *    逻辑 id 'session_main'），故以"非角色会话写 kanban 工作区"为近似。修复轮 7 收紧三点：
+ *    逻辑 id 'session_main'），故以"非角色会话写 kanban 工作区"为近似。收紧三点：
  *    a. 作用域收窄：仅扫描会话工作区（session.header.cwd）位于本链发起工作区
  *       （Chain.workspaceDir = /plan: 主 agent 所在工作空间）内的会话，
  *       排除其他项目的主会话（如 评估 项目里调试 dsh-swarm 的会话）；
@@ -40,7 +40,7 @@ export declare class ChainAuditor {
     private readonly listLiveAgents;
     constructor(deps: ChainAuditorDeps);
     /** 执行核对，返回越权证据（空=通过，不阻塞汇报）。
-     *  @param workspaceDir 本链发起工作区（Chain.workspaceDir）；提供时仅扫描工作区内的会话（修复轮 7）。 */
+     *  @param workspaceDir 本链发起工作区（Chain.workspaceDir）；提供时仅扫描工作区内的会话。 */
     check(chainId: string, workspaceDir?: string | null): Promise<AuditEvidence[]>;
     private reconcileArtifacts;
 }

package/lib/dispatcher/chain-auditor.js

@@ -5,12 +5,14 @@ import { eventType, toolArgs, toolName } from './session-events.js';
 import { isPathInside } from './target-repo.js';
 /** 直接写工具（无条件视为写能力；只读工具如 read/glob/grep 不算）。 */
 const DIRECT_WRITE_TOOLS = new Set(['write', 'edit', 'rm', 'mv', 'cp', 'mkdir', 'mkfile']);
-/** run_code：写能力载体，需结合派发子调用判定（修复轮 7）。 */
+/** run_code：写能力载体，需结合派发子调用判定。 */
 const CODE_RUN_TOOLS = new Set(['run_code']);
 /** bash 命令中的写操作标记（写证据启发式；ls/cat/grep/git status 等只读不算）。
- *  重定向标记用 \s>>?（要求 > 前有空白），避免把 2>/dev/null、2>&1 等只读 stderr 重定向误判为写。 */
-const BASH_WRITE_RE = /(?:\b(?:touch|mkdir|rm|rmdir|mv|cp|tee|truncate|install|ln|dd|chmod|chown|make|cmake)\b|\bgit\s+(?:add|commit|push|mv|rm|checkout\s+-b|switch\s+-c|worktree\s+add|merge|rebase|reset|clean|restore|tag|remote\s+add)\b|\bpnpm\s+(?:add|install|remove|update|link)\b|\bnpm\s+(?:i|install|add|remove|uninstall|update)\b|\byarn\s+(?:add|remove)\b|\bbun\s+(?:add|install|remove)\b|\bsed\s+-i\b|\bperl\s+-i\b|\s>>?)/i;
-/** run_code/兜底 code 字符串中的 Python 写 API 标记（Fix round 2 F2 同源：audit 补 open( 兜底）。
+ *  重定向标记用 \s>>?（要求 > 前有空白），避免把 2>/dev/null、2>&1 等只读 stderr 重定向误判为写。
+ *  git 细化（2026-09-08）：merge(?!-base) 防 merge-base 查询被误判；tag 只认带非 -l/-n 参数的
+ *  变更形态（tag -l/-n/裸 为列表查询），两份正则（toolsets/chain-auditor）改动须同步。 */
+const BASH_WRITE_RE = /(?:\b(?:touch|mkdir|rm|rmdir|mv|cp|tee|truncate|install|ln|dd|chmod|chown|make|cmake)\b|\bgit\s+(?:add|commit|push|mv|rm|checkout\s+-b|switch\s+-c|worktree\s+add|merge(?!-base)|rebase|reset|clean|restore|tag\s+(?!-l\b|-n\b)\S+|remote\s+add)\b|\bpnpm\s+(?:add|install|remove|update|link)\b|\bnpm\s+(?:i|install|add|remove|uninstall|update)\b|\byarn\s+(?:add|remove)\b|\bbun\s+(?:add|install|remove)\b|\bsed\s+-i\b|\bperl\s+-i\b|\s>>?)/i;
+/** run_code/兜底 code 字符串中的 Python 写 API 标记（audit 补 open( 兜底）。
  *  open() 写模式精确版（读模式 'r' 不命中）、os. 模块写、pathlib Path 写、shutil 复制/移动/删除。 */
 const PY_CODE_WRITE_RE = /(?:\bopen\(\s*['"][^'"\n]*['"]\s*,\s*(?:(?:mode|encoding|errors|buffering|newline|closefd|opener|text)\s*=\s*)?['"][wa][^'"\n]*['"]|\bos\s*\.\s*(?:remove|unlink|write|rmdir|makedirs|rename)\b|\.(?:write_text|write_bytes|unlink|mkdir|rename)\(|shutil\s*\.\s*(?:copy|move|rmtree))/i;
 /** 从工具调用参数中收集含 workspacesRoot 的字符串值（文件路径线索）。 */
@@ -43,7 +45,7 @@ function dataField(e, key) {
 function hasWriteMarker(text) {
     return BASH_WRITE_RE.test(text) || PY_CODE_WRITE_RE.test(text);
 }
-/** 判定单个工具调用是否构成写证据（修复轮 7：行为判定 + 只读排除）。
+/** 判定单个工具调用是否构成写证据（行为判定 + 只读排除）。
  *  @param subs 该调用的 run_code 派发子调用（无则 null，走兜底/直接判定）。 */
 function handleCallEvidence(name, args, subs, root, paths) {
     if (DIRECT_WRITE_TOOLS.has(name)) {
@@ -142,24 +144,27 @@ export class ChainAuditor {
         this.listLiveAgents = deps.listLiveAgents ?? (() => []);
     }
     /** 执行核对，返回越权证据（空=通过，不阻塞汇报）。
-     *  @param workspaceDir 本链发起工作区（Chain.workspaceDir）；提供时仅扫描工作区内的会话（修复轮 7）。 */
+     *  @param workspaceDir 本链发起工作区（Chain.workspaceDir）；提供时仅扫描工作区内的会话。 */
     async check(chainId, workspaceDir = null) {
         const evidence = [];
         // 源 1：主会话（非 kbn- 角色会话）写能力工具事件扫描
         for (const agent of this.listLiveAgents()) {
             if (String(agent.id ?? '').startsWith('kbn-'))
                 continue; // 角色会话（P/W/D/V）跳过
-            // 0.1.0 delegation 豁免（spec FR5）：header.agentPreset 以 kanban- 开头 → 角色会话
+            // 0.1.0 delegation 豁免：header.agentPreset 以 kanban- 开头 → 角色会话
             // 的子代理（childSessionMeta 记录所 join 的 preset id），产物归属 git 证据链，
             // 不按"主会话越权"判定；源2（无主产物核对）仍兜底其误写链工作区根。
             const joinedPreset = agent.session?.header?.agentPreset;
             if (typeof joinedPreset === 'string' && joinedPreset.startsWith('kanban-'))
                 continue;
-            // 修复轮 7：作用域收窄——仅扫本链发起工作区内的会话；会话无 cwd（测试伪造）时保守保留扫描
+            // 作用域收窄——仅扫本链发起工作区内的会话；会话无 cwd（测试伪造）时保守保留扫描
             if (workspaceDir && agent.session?.header?.cwd && !isPathInside(agent.session.header.cwd, workspaceDir)) {
                 continue;
             }
-            const hit = sessionWriteEvidence(String(agent.id), this.workspacesRoot, agent.session?.events ?? []);
+            // 0.1.2（DSH-0.1.2-A4-03）：Session.events 移除 → snapshotEvents() 优先，回退 events（旧宿主/测试）
+            const ses = agent.session;
+            const sessionEvents = ses?.snapshotEvents?.() ?? ses?.events ?? [];
+            const hit = sessionWriteEvidence(String(agent.id), this.workspacesRoot, sessionEvents);
             if (hit)
                 evidence.push(hit);
         }