@joekytc/dsh-swarm 0.2.0 → 0.3.0

package/lib/dispatcher/v-orchestrator.js

@@ -11,12 +11,12 @@ export const R20_PHASE_EXPECT = {
     p: { assignee: 'p', mode: 'openspec' },
     pt: { assignee: 'pt', mode: 'review-plan' }, // 由 P 交付 pt_decision.needed=true 触发（需计划评审才进入）
     w2: { assignee: 'w', mode: 'kb' },
-    d: { assignee: 'd', mode: 'execute' }, // R20：D=执行者（实际写代码/git 提交推送），非只读对齐/校验
+    d: { assignee: 'd', mode: 'execute' }, // D=执行者（实际写代码/git 提交推送），非只读对齐/校验
     dt: { assignee: 'dt', mode: 'review-impl' }, // 固定：D 之后必经实现校验+评审
     w3: { assignee: 'w', mode: 'kb' },
     summary: null,
 };
-/** M5：每阶段建卡的 body 生成指令（角色定位确定性模板，消除 V 自由发挥导致的角色漂移）。
+/** 每阶段建卡的 body 生成指令（角色定位确定性模板，消除 V 自由发挥导致的角色漂移）。
  *  P=计划者（绝不执行）、D=唯一执行者（TARGET_REPO 必须取自规格卡 file-prefetch 附件 ref，禁止回退/猜测）、
  *  W=KB 同步（绝不执行代码）。V 把对应模板写入 kanban_create 的 body。 */
 export const PHASE_INSTRUCTIONS = {
@@ -57,7 +57,7 @@ export const PHASE_INSTRUCTIONS = {
     ].join('\n'),
     dt: [
         '## DT 阶段任务体要求（实现校验+评审，只读护栏）',
-        'body 写入实现校验指令：对 D 产物实证校验（test/build/typecheck/diff/git 证据 + open-code-review 评审），输出 verdict+issues 入交接 metadata.review_evidence。评审目标为 D 交接 metadata.branch 指向的 feature 分支（ocr review --from <TARGET_BRANCH> --to <branch>），而非 TARGET_BRANCH。',
+        'body 写入实现校验指令：对 D 产物实证校验（test/build/typecheck/diff/git 证据 + open-code-review 评审），输出 verdict+issues 入交接 metadata.review_evidence。评审目标为 D 交接 metadata.branch 指向的 feature 分支，而非 TARGET_BRANCH。评审引擎：用 ocr_review 工具按配置引擎评审——委托 = preview→rule→git diff 自评；托管 = managed 一次出 findings；托管未配置时按工具指引静默改走委托；ocr 未安装则 kanban_block(\'review-tool-unavailable\') 并注明可在 GUI 配置面板安装。',
         '铁律：DT 是只读校验+评审角色，绝不修改源码/产物；校验经 ToolGuard 硬性只读护栏；不注入 git 凭据。',
     ].join('\n'),
     w3: [
@@ -65,7 +65,7 @@ export const PHASE_INSTRUCTIONS = {
         'body 写入 KB 收尾同步指令：读 D 交接 → wiki_write 同步（pagePath 必须逐字等于下方「KB 页路径规则」给出的路径）→ complete(kb_url)。禁止任何 git/代码操作。',
     ].join('\n'),
 };
-/** D9（W 角色知识库双模式）：按 kbMode 构建各阶段建卡 body 指令（phase 键控——W2/W3 同为
+/** W 角色知识库双模式：按 kbMode 构建各阶段建卡 body 指令（phase 键控——W2/W3 同为
  *  assignee='w'+mode='kb'，assignee+mode 签名无法区分两相文案；系统状态本就按 phase 键控）。
  *  remote → PHASE_INSTRUCTIONS 原文（护栏测试零改动前提）；local → 覆盖 w2/w3/d/dt 四相
  *  （skill 工具加载 llm-wiki + 本地库 fs 读写，禁 wiki_write/wiki_read），p/pt/summary 原样回落。
@@ -82,7 +82,7 @@ export function buildPhaseInstruction(phase, ctx, kbMode) {
         case 'd':
             return '先读父任务交接（W2）里的 page_path（本地库 wiki/sources/ 下相对路径，库根见运行时上下文注入——Task 8 已注入 D），直接 fs 读实施计划原文；如需 KB 经验召回，经 skill 工具加载 llm-wiki query（本地库；kanban-d preset 已挂 tool-skill）——再按计划执行规格卡 solution/testing —— git worktree/branch → 改代码/README → git commit → git push（仅 feature 分支，可选）→ 自检并附产物证据（changed_files/commit_hash）。其余 TDD/TARGET_REPO/TARGET_BRANCH 等要求与 remote 版一致。';
         case 'dt':
-            return `对 D 产物实证校验（test/build/typecheck/diff/git 证据 + open-code-review 评审），输出 verdict+issues 入交接 metadata.review_evidence。评审页经 fs 写本地库 <库根>/wiki/queries/${ctx.chainId}/review/<name>.md（库根见运行时上下文注入——Task 8 已注入 DT）；库根外一律只读，其余铁律与 remote 版一致。`;
+            return `对 D 产物实证校验（test/build/typecheck/diff/git 证据 + open-code-review 评审），输出 verdict+issues 入交接 metadata.review_evidence。评审引擎：用 ocr_review 工具按配置引擎评审（委托 = preview→rule→git diff 自评；托管 = managed 一次出 findings；托管未配置时按工具指引静默改走委托；ocr 未安装则 kanban_block('review-tool-unavailable') 并注明可在 GUI 配置面板安装）。评审页经 fs 写本地库 <库根>/wiki/queries/${ctx.chainId}/review/<name>.md（库根已由系统注入 DT 运行时上下文）；库根外一律只读，其余铁律与 remote 版一致。`;
         default:
             return PHASE_INSTRUCTIONS[phase] ?? '';
     }
@@ -111,7 +111,7 @@ function extractPtPassSuggestions(state, chainId) {
     return Array.isArray(ev?.issues) ? ev.issues : [];
 }
 /** 仅评审卡：archived 且从未处理过 verdict = 作废（void）。human 归档评审卡即作废，编排器视其不存在。
- *  非评审卡（p/d/w…）一律返回 false——避免 B6 误判"该阶段无卡"而重复建卡。 */
+ *  非评审卡（p/d/w…）一律返回 false——避免误判"该阶段无卡"而重复建卡。 */
 const REVIEW_MODES = ['review-plan', 'review-impl'];
 function isVoidReview(task, events) {
     if (task.status !== 'archived')
@@ -120,11 +120,11 @@ function isVoidReview(task, events) {
         return false; // 非评审卡不判 void
     return !events.some((e) => e.taskId === task.id && (e.kind === 'review/passed' || e.kind === 'review/failed' || e.kind === 'review/gave-up'));
 }
-/** Task 4（V 会话注入加固）：V 会话身份标记——setup 完整成功（kanban-v preset mount + 角色工具面）后
+/** V 会话注入加固：V 会话身份标记——setup 完整成功（kanban-v preset mount + 角色工具面）后
  *  写入，live 复用前校验。与 agent-runner.ts roleCompositions 同款机制（进程内 WeakMap 按 incarnation
  *  键控：GUI 重开同名会话/宿主自建 incarnation 查不到标记 → 拒绝盲复用；实例回收标记随 GC 消失）。
  *  不直接复用其 WeakMap：其 marker 结构 {role,taskId} 面向任务会话（V 无 taskId），读取端未导出，
- *  导出需改 agent-runner.ts（本任务硬约束禁止）。 */
+ *  导出需改 agent-runner.ts（硬约束禁止）。 */
 const vSessionCompositions = new WeakMap();
 const V_SESSION_PRESET_ID = 'kanban-v';
 /** 宿主形态防御：dsh 0.1.2-rc.1 移除 Session.events（DSH-0.1.2-A4-03）→ 优先 snapshotEvents()；
@@ -149,15 +149,15 @@ export class VOrchestrator {
         }
         return o;
     }
-    /** Fix D：stall 自动再唤醒上限（同一阶段连续零产出 → 自动重试 ≤3 次，间隔递增）后放弃并显形。 */
+    /** stall 自动再唤醒上限（同一阶段连续零产出 → 自动重试 ≤3 次，间隔递增）后放弃并显形。 */
     static STALL_REWAKE_LIMIT = 3;
-    /** Fix D：stall 再唤醒基础延迟（按 stallCount 倍增：5s/10s/15s），给瞬时故障/采样波动恢复窗口。 */
+    /** stall 再唤醒基础延迟（按 stallCount 倍增：5s/10s/15s），给瞬时故障/采样波动恢复窗口。 */
     static STALL_REWAKE_DELAY_MS = 5_000;
     rewakeTimers = new Map();
     /** 同链 wakeV 并发防护：在途时后续唤醒合并为 pending，完成后补跑一次（事件不丢）。 */
     waking = new Set();
     pendingWake = new Set();
-    /** Fix D：orchestration 变更回调（dispatcher 注入 saveOrchs）——stall re-wake 路径绕过
+    /** orchestration 变更回调（dispatcher 注入 saveOrchs）——stall re-wake 路径绕过
      *  EventWaker，其 stallCount/phase 变化需自行落盘，防重启丢重试进度。 */
     onOrchChange;
     async wakeV(chainId) {
@@ -176,7 +176,7 @@ export class VOrchestrator {
             }
         }
     }
-    /** Fix D：stall 自动再唤醒（≤3 次）。同链 pending 幂等；建卡成功（stallCount=0）后到期的
+    /** stall 自动再唤醒（≤3 次）。同链 pending 幂等；建卡成功（stallCount=0）后到期的
      *  re-wake 自动作废（回调内按 stallCount 判空跳过）。 */
     scheduleRewake(chainId, stallCount) {
         if (this.rewakeTimers.has(chainId))
@@ -191,7 +191,7 @@ export class VOrchestrator {
         }, delay);
         this.rewakeTimers.set(chainId, timer);
     }
-    /** Fix D：清理待触发的 re-wake 定时器（插件 dispose 时调用）。 */
+    /** 清理待触发的 re-wake 定时器（插件 dispose 时调用）。 */
     dispose() {
         for (const t of this.rewakeTimers.values())
             clearTimeout(t);
@@ -224,7 +224,7 @@ export class VOrchestrator {
         // → 向 V 发一轮阻塞复核（本轮 V 唯一动作），V 用 kanban_comment 以 [blocked-review] 开头逐一
         // 评论给方向后待命；无此类任务则正常推进。扩展为所有 blocked（含 kb-insufficient 等），
         // 幂等由 hasBlockReview 保证（每次阻塞至多一轮复核评论，blocked→unblocked→再 blocked
-        // 因新 block 事件 seq 更新才重新评论）。置于 B4 门控之前：即使规格卡未批准（planning/draft），
+        // 因新 block 事件 seq 更新才重新评论）。置于阶段门控之前：即使规格卡未批准（planning/draft），
         // 阻塞也可复核（恢复不依赖批准）。
         const blockedReview = [...state.tasks.values()].filter((t) => {
             if (t.chainId !== chainId || t.status !== 'blocked')
@@ -251,15 +251,15 @@ export class VOrchestrator {
             await agent.whenIdle();
             return; // 本轮 V 唯一动作是阻塞复核，不再推进阶段
         }
-        // B4 阶段门控：V 仅规格卡 approved（链 executing）后才行动（从 p 起跑建执行链卡）；
+        // 阶段门控：V 仅规格卡 approved（链 executing）后才行动（从 p 起跑建执行链卡）；
         // draft/planning 时 V 待命，等 spec-card/approved 事件唤醒（event-waker 已订阅）。
         const approved = chain.status === 'executing' && specCard?.status === 'approved';
         if (!approved)
             return;
-        // 阶段推进循环（修复轮 6，举一反三）：跳过已完成（终态卡）阶段，
+        // 阶段推进循环（举一反三）：跳过已完成（终态卡）阶段，
         // 停在需要建卡的阶段建卡并推进；避免「推进 phase 后不建下一卡」造成的流水线停滞。
         for (;;) {
-            // B4 阶段门控（每轮按当前 phase 重查）：V 仅 approved 后行动（chain/executing 已确认）。
+            // 阶段门控（每轮按当前 phase 重查）：V 仅 approved 后行动（chain/executing 已确认）。
             const approvedHere = chain.status === 'executing' && specCard?.status === 'approved';
             if (!approvedHere)
                 return;
@@ -319,12 +319,12 @@ export class VOrchestrator {
                 }
                 // 无评审卡 → 建卡（走下方通用建卡路径，但建卡后不推进 phase）
             }
-            // B6 幂等：当前 phase 期望卡（R20_PHASE_EXPECT 匹配 assignee+mode）已存在且未终态 → 不重复建卡直接待命
+            // 幂等：当前 phase 期望卡（R20_PHASE_EXPECT 匹配 assignee+mode）已存在且未终态 → 不重复建卡直接待命
             // （防插件重启后重复建卡、V 一轮连发多卡）。
             const existing = chainTasks.find((t) => t.assignee === expect.assignee && t.mode === expect.mode && !isVoidReview(t, state.events));
             if (existing && !terminal.includes(existing.status))
                 return;
-            // 仅当当前 phase 的 (assignee,mode) 在整个 R20 序列唯一时，"已终态 existing 卡 = 本阶段自己的卡已完成"
+            // 仅当当前 phase 的 (assignee,mode) 在整个阶段序列唯一时，"已终态 existing 卡 = 本阶段自己的卡已完成"
             // 才成立；w2/w3 同为 (w,kb) 时 existing 可能是上一阶段（w2）的卡，不能据此推进（否则 w3 被误跳过）。
             const sameExpectCount = R20_PHASE_ORDER.filter((p) => {
                 const e = R20_PHASE_EXPECT[p];
@@ -344,7 +344,7 @@ export class VOrchestrator {
             // 交付契约闸已对所有 actor（含 human 强制收尾）在完成时拦截（缺交付物会先被标 blocked，
             // 不会被 resolve 成父卡），故此处仅剩 legacy（改闸前已落盘的 done-but-missing）。done 不可变、
             // 不能重标 blocked，发 system 评论记录断裂并停住：不建下游卡、不推进 phase，避免拖到下游执行时才报错。
-            // D9：透传当前 baseUrl（local 模式为 '' → strict local 分支认可 kb_url="" 交付）；
+            // 透传当前 baseUrl（local 模式为 '' → strict local 分支认可 kb_url="" 交付）；
             // wikiVault?. 防护测试 stub（getEffective() 返回 {} 时回退 undefined=宽松，行为同旧）。
             const missingParents = missingParentDelivery(state, parents, this.configProvider.getEffective().wikiVault?.baseUrl);
             if (missingParents.length > 0) {
@@ -357,15 +357,15 @@ export class VOrchestrator {
             const ptReason = orch.phase === 'pt' ? extractPtReason(state, chainId) : '';
             // 2026-09-03 P/PT 定位决议：D 卡创建上下文注入 PT pass 留档的非阻塞建议（评审遗留建议随卡传递）。
             const ptSuggestions = orch.phase === 'd' ? extractPtPassSuggestions(state, chainId) : [];
-            // Task 7：KB 页路径规则（W2/W3 wiki_write pagePath 确定性下发）——repoSlug 由链 workspaceDir 派生，
+            // KB 页路径规则（W2/W3 wiki_write pagePath 确定性下发）——repoSlug 由链 workspaceDir 派生，
             // V 不需计算，直接把路径模板写入建卡 context；链无 workspaceDir 时注入空串（不拦截建卡）。
             const kbPageRoot = chain?.workspaceDir ? `projects/${buildRepoSlug(chain.workspaceDir)}` : null;
             const context = [
-                '# V 编排轮次（R20 逐阶段创建）',
+                '# V 编排轮次（逐阶段创建）',
                 `chain=${chainId} phase=${orch.phase}`,
                 `NEXT_TASK_ASSIGNEE=${expect.assignee} MODE=${expect.mode}`,
                 `PARENT_DEPS=${parents.length > 0 ? parents.join(',') : '(无)'}`,
-                // M5：D 阶段额外注入 testing 段（执行指令依赖 solution/testing）；附件 ref 供 V 取真实仓库路径写 TARGET_REPO
+                // D 阶段额外注入 testing 段（执行指令依赖 solution/testing）；附件 ref 供 V 取真实仓库路径写 TARGET_REPO
                 specCard ? `## 规格卡\n${specCard.sections.problem}\n${specCard.sections.solution}${orch.phase === 'd' ? '\n' + specCard.sections.testing : ''}\n附件：${specCard.attachments.map((a) => `${a.kind}:${a.ref}`).join(' | ') || '(无)'}` : '',
                 '## 当前任务\n' + [...state.tasks.values()].filter((t) => t.chainId === chainId)
                     .map((t) => {
@@ -397,17 +397,17 @@ export class VOrchestrator {
             }
             catch (err) {
                 // 防线④：异常收场 = 本轮零产出的一种形态（2026-09-04 mtmgp81q：异常逃出本函数
-                // 被 dispatcher 吞掉，Fix D stall 计数整段被跳过 → 链静默死锁）。在此并入 stall 计数。
-                // Task 4：getVAgent 也纳入——preset mount fail-fast / resume live 冲突等「获取会话失败」
+                // 被 dispatcher 吞掉，stall 计数整段被跳过 → 链静默死锁）。在此并入 stall 计数。
+                // getVAgent 也纳入——preset mount fail-fast / resume live 冲突等「获取会话失败」
                 // 与 turn 执行异常同收场（计 stall → scheduleRewake → 超限 [create-failed] + blockChain）。
                 turnError = err;
                 console.error('[dsh-swarm][debug] V turn error (treated as zero-output) chain=' + chainId + ' phase=' + orch.phase + ': ' + String(err));
             }
-            // R4 建卡数量硬闸：本轮只允许一张期望匹配卡推进 phase——取第一张匹配卡，其余建卡不推进
+            // 建卡数量硬闸：本轮只允许一张期望匹配卡推进 phase——取第一张匹配卡，其余建卡不推进
             // （提取 kanban_create 调用；假实现从会话事件取，真实实现同名）。
-            // 修复轮 6：session.events 条目形态为 {type, data:{name, arguments}}，name 在 data 下且
+            // session.events 条目形态为 {type, data:{name, arguments}}，name 在 data 下且
             // arguments 是 JSON 字符串——统一经 toolName/toolArgs（src/dispatcher/session-events.ts）读取。
-            // Task 5（宿主形态防御）：session.events 缺失（undefined/非数组）时 console.error 留痕（含
+            // 宿主形态防御：session.events 缺失（undefined/非数组）时 console.error 留痕（含
             // chainId/phase/sessionId），随零产出语义计 stall——非静默，但不崩（诊断仅在缺失时打）。
             if (!turnError && agent !== null && !Array.isArray(agent.session?.events) && typeof agent.session?.snapshotEvents !== 'function') {
                 console.error('[dsh-swarm][debug] 宿主会话事件缺失（形态异常），按零产出处理 chain=' + chainId + ' phase=' + orch.phase + ' sessionId=' + String(orch.sessionId));
@@ -419,7 +419,7 @@ export class VOrchestrator {
                 const a = toolArgs(e);
                 return a.assignee === expect.assignee && a.mode === expect.mode;
             });
-            // 建卡失败防护（Fix D）：V 本轮未产生期望卡（assignee+mode 不匹配）→ 记 stall 轮次并自动再唤醒
+            // 建卡失败防护：V 本轮未产生期望卡（assignee+mode 不匹配）→ 记 stall 轮次并自动再唤醒
             // 重试（≤3 次，间隔 5s/10s/15s 递增——覆盖采样波动/瞬时故障，2026-09-02 倒计时链实测：V 首轮
             // 只出文本不调工具、第二轮重放即正常建卡）；超过上限 → 放弃：在链上锚点卡（最近终态卡，无则
             // 最新卡）发 [create-failed] system 评论显形（幂等：已有该评论则不再发）+ blockChain 链级终态
@@ -533,7 +533,7 @@ export class VOrchestrator {
             return 'gave-up';
         }
         // 未超限：createReworkTask（原任务保持 done）+ 新建复审卡（parents=rework，reviewAttempt=rework.reviewAttempt）。
-        // 2026-09-03 P/PT 定位决议铁律3：复审卡 body 确定性注入上一轮 issues 对账输入——复审卡原为空 body，
+        // 2026-09-03 P/PT 定位决议铁律：复审卡 body 确定性注入上一轮 issues 对账输入——复审卡原为空 body，
         // 对账纯靠模型自觉（ch_1_mtjuukv2 三轮空转的结构根因之一）；输入直接取作用域内 evidence，不查事件。
         const reconcileBody = [
             role === 'pt' ? '## PT 复审任务体要求（计划评审，只读）' : '## DT 复审任务体要求（实现校验+评审，只读护栏）',
@@ -561,9 +561,9 @@ export class VOrchestrator {
         return R20_PHASE_ORDER[Math.min(i + 1, R20_PHASE_ORDER.length - 1)];
     }
     async getVAgent(orch) {
-        // B3：resume 与 create 都传 setup——恢复的 V 会话同样装配角色工具面（agent scope 注册随会话重建），
+        // resume 与 create 都传 setup——恢复的 V 会话同样装配角色工具面（agent scope 注册随会话重建），
         // 与 agent-runner.ts 的 installRoleTools 用法一致。
-        // 修复轮 6：V 后台编排会话与 P/W/D 一致，显式设置 approval=never + sandbox=workspace-write，
+        // V 后台编排会话与 P/W/D 一致，显式设置 approval=never + sandbox=workspace-write，
         // 避免在无 preset 装配时因默认审批策略在后台无应答者而挂起（卡死调度器首轮 tick）。
         const setup = async (agentCtx) => {
             // 思考等级强制（waterfall）：与 agent-runner 同缺陷——宿主 selection 无 create-options 覆盖层，
@@ -578,14 +578,14 @@ export class VOrchestrator {
             const session = agentCtx.agent?.session;
             session?.append?.('approval/policy', { policy: 'never', source: 'delegation' });
             session?.append?.('sandbox/mode', { mode: 'workspace-write', source: 'delegation' });
-            // R21 对齐（2026-08-17）：V=butler·orchestrator 零执行能力——先挂 kanban-v 裁剪 preset
+            // 对齐（2026-08-17）：V=butler·orchestrator 零执行能力——先挂 kanban-v 裁剪 preset
             // （组合仅 persona + agent-instructions，无 bash/fs/run_code/web/skill/delegation 等执行/探索工具），
             // 再注入 kanban/spec 工具面；从基座层面落实「V 只路由、不执行」。
             const presets = agentCtx.get?.('agentPresets');
             if (presets) {
-                // Task 4 加固：preset mount 失败即抛（fail-fast），不再 console.error 静默放行——V 会话
+                // preset mount 失败即抛（fail-fast），不再 console.error 静默放行——V 会话
                 // 无 persona 基座不得裸奔。抛错 → create/resume 失败 → getVAgent 抛 → 主推进路径并入
-                // 异常收场（Fix D stall 计数，超限 [create-failed] + blockChain）；候选循环对非 model
+                // 异常收场（stall 计数，超限 [create-failed] + blockChain）；候选循环对非 model
                 // 错误立即失败（isModelUnavailableError=false → throw），不会被候选切换吞掉。
                 const vSessionId = orch.sessionId ?? 'kbn-v-' + orch.chainId;
                 try {
@@ -596,19 +596,19 @@ export class VOrchestrator {
                 }
             }
             await installRoleTools(agentCtx, 'v', { kanban: this.kanban, wiki: this.wiki });
-            // Task 4：setup 完整成功（mount + 工具面）后写身份标记——live 复用校验依据（同 agent-runner 组合标记机制）。
+            // setup 完整成功（mount + 工具面）后写身份标记——live 复用校验依据（同 agent-runner 组合标记机制）。
             const vAgent = agentCtx.agent;
             if (vAgent && typeof vAgent === 'object')
                 vSessionCompositions.set(vAgent, V_SESSION_PRESET_ID);
         };
-        // 模型候选链（Task 12）：V 会话 create/resume 按 primary→fallbacks 静默切换；
+        // 模型候选链：V 会话 create/resume 按 primary→fallbacks 静默切换；
         // V 无任务卡可 block——全候选不可用抛最后错误（wakeV 调用方按既有错误路径处理）。
         const candidates = buildModelCandidates(this.configProvider.getEffective(), 'v', this.defaultModel);
         const spawnWith = async (opts) => {
             if (orch.sessionId) {
-                // 修复轮 6：V 会话首轮创建后保持 live，resume 会抛 "cannot prepare session while it is live"。
+                // V 会话首轮创建后保持 live，resume 会抛 "cannot prepare session while it is live"。
                 // 优先复用 agents registry 中仍 live 的会话（followup 续用），仅当会话已下线时才 resume。
-                // Task 4 加固：live 复用前校验身份标记（参照 agent-runner resumeOrReuse 同款）——标记匹配
+                // live 复用前校验身份标记（参照 agent-runner resumeOrReuse 同款）——标记匹配
                 // 才复用；缺失/不匹配（GUI 重开同名会话/宿主自建 incarnation/历史会话）拒绝盲复用，改走
                 // resume 重跑 setup 重新 mount（身份自愈）；resume 撞 live 冲突则抛错走防线——绝不静默
                 // 把错误身份的会话交给调用方。
@@ -624,7 +624,7 @@ export class VOrchestrator {
                 const h = await this.agents.resume({ resumeSessionId: orch.sessionId, ...opts, setup });
                 return h.agent;
             }
-            // M2(Q5)+归组：V 编排会话创建在主 agent 工作空间；缺失时询问用户注册工作区，仍不可得 → 抛错（dispatcher 捕获日志，V 待命）。
+            // 归组：V 编排会话创建在主 agent 工作空间；缺失时询问用户注册工作区，仍不可得 → 抛错（dispatcher 捕获日志，V 待命）。
             let ws = await this.chainWorkspace(orch.chainId);
             if (!ws) {
                 ws = await resolveOrCreateWorkspace(this.ctx, null, 'chain ' + orch.chainId + ' V');
@@ -652,7 +652,7 @@ export class VOrchestrator {
         }
         throw lastErr;
     }
-    /** M2(Q5)+归组：链的 workspaceDir（发起 /plan: 的主 agent 工作空间）；缺失返回 null（调用方询问/报错，不落 kanban 存储）。 */
+    /** 归组：链的 workspaceDir（发起 /plan: 的主 agent 工作空间）；缺失返回 null（调用方询问/报错，不落 kanban 存储）。 */
     async chainWorkspace(chainId) {
         const state = await this.kanban.snapshot();
         return state.chains.get(chainId)?.workspaceDir ?? null;

package/lib/dispatcher/watchdog.d.ts

@@ -1,6 +1,6 @@
 import type { KanbanService } from '../domain/kanban-service.js';
 /** 心跳超时回收（running 无心跳 → failed，可重试）。
- *  failed 任务的熔断（attempts≥maxRetries → blocked(gave_up)）与重派由调度器（Dispatcher.tick）统一处理（B1）。 */
+ *  failed 任务的熔断（attempts≥maxRetries → blocked(gave_up)）与重派由调度器（Dispatcher.tick）统一处理。 */
 export declare class Watchdog {
     private timer;
     private readonly kanban;

package/lib/dispatcher/watchdog.js

@@ -1,5 +1,5 @@
 /** 心跳超时回收（running 无心跳 → failed，可重试）。
- *  failed 任务的熔断（attempts≥maxRetries → blocked(gave_up)）与重派由调度器（Dispatcher.tick）统一处理（B1）。 */
+ *  failed 任务的熔断（attempts≥maxRetries → blocked(gave_up)）与重派由调度器（Dispatcher.tick）统一处理。 */
 export class Watchdog {
     timer = null;
     kanban;
@@ -11,7 +11,7 @@ export class Watchdog {
             if (t.status === 'running') {
                 const lastBeat = t.heartbeats.at(-1) ?? state.events.find((e) => e.taskId === t.id && e.kind === 'task/claimed')?.at ?? now;
                 if (now - lastBeat > this.cfg.staleTimeoutSeconds * 1000) {
-                    await this.kanban.failTask(t.id, 'stale-reclaim', 'system'); // P0-5：超时回收发 failed（可重试），不直接 block
+                    await this.kanban.failTask(t.id, 'stale-reclaim', 'system'); // 超时回收发 failed（可重试），不直接 block
                 }
             }
             // failed 任务不在此处理：Dispatcher.tick 负责 attempts<maxRetries 重派 / attempts≥maxRetries 熔断

package/lib/domain/config-override.d.ts

@@ -14,6 +14,13 @@ export interface EditableOverride {
     roles?: {
         models?: Partial<Record<Role, EditableModelInput>>;
     };
+    reviewEngine?: {
+        mode?: 'delegate' | 'managed';
+        managed?: {
+            provider?: string;
+            model?: string;
+        };
+    };
 }
 export interface EditableModelSnapshot {
     provider: string;
@@ -28,6 +35,13 @@ export interface EditableSnapshot {
     roles: {
         models: Partial<Record<Role, EditableModelSnapshot>>;
     };
+    reviewEngine: {
+        mode: 'delegate' | 'managed';
+        managed: {
+            provider: string;
+            model: string;
+        };
+    };
 }
 export type ConfigSource = 'override' | 'inherited';
 export type SourceMap = Record<string, ConfigSource>;

package/lib/domain/config-override.js

@@ -6,6 +6,16 @@ export function mergeConfig(baseline, override) {
         wiki.baseUrl = override.wikiVault.baseUrl;
     if (override?.wikiVault?.pagePrefix !== undefined)
         wiki.pagePrefix = override.wikiVault.pagePrefix;
+    const reviewEngine = {
+        mode: baseline.reviewEngine?.mode ?? 'delegate',
+        managed: { provider: baseline.reviewEngine?.managed?.provider ?? '', model: baseline.reviewEngine?.managed?.model ?? '' },
+    };
+    if (override?.reviewEngine?.mode !== undefined)
+        reviewEngine.mode = override.reviewEngine.mode;
+    if (override?.reviewEngine?.managed?.provider !== undefined)
+        reviewEngine.managed.provider = override.reviewEngine.managed.provider;
+    if (override?.reviewEngine?.managed?.model !== undefined)
+        reviewEngine.managed.model = override.reviewEngine.managed.model;
     const models = { ...baseline.roles.models };
     for (const role of ROLES) {
         const base = baseline.roles.models?.[role];
@@ -23,7 +33,7 @@ export function mergeConfig(baseline, override) {
         if (cur.provider && cur.model)
             models[role] = cur;
     }
-    return { ...baseline, wikiVault: wiki, roles: { ...baseline.roles, models } };
+    return { ...baseline, wikiVault: wiki, roles: { ...baseline.roles, models }, reviewEngine };
 }
 export function computeSources(override) {
     const src = {};
@@ -37,6 +47,9 @@ export function computeSources(override) {
             src[`roles.models.${role}.${f}`] = hit ? 'override' : 'inherited';
         }
     }
+    src['reviewEngine.mode'] = override?.reviewEngine?.mode !== undefined ? 'override' : 'inherited';
+    src['reviewEngine.managed.provider'] = override?.reviewEngine?.managed?.provider !== undefined ? 'override' : 'inherited';
+    src['reviewEngine.managed.model'] = override?.reviewEngine?.managed?.model !== undefined ? 'override' : 'inherited';
     return src;
 }
 export function projectEditable(effective) {
@@ -49,6 +62,10 @@ export function projectEditable(effective) {
     return {
         wikiVault: { baseUrl: effective.wikiVault.baseUrl, pagePrefix: effective.wikiVault.pagePrefix },
         roles: { models },
+        reviewEngine: {
+            mode: effective.reviewEngine?.mode ?? 'delegate',
+            managed: { provider: effective.reviewEngine?.managed?.provider ?? '', model: effective.reviewEngine?.managed?.model ?? '' },
+        },
     };
 }
 export function validateConfig(snapshot) {
@@ -59,6 +76,10 @@ export function validateConfig(snapshot) {
         errs.push('wikiVault.baseUrl');
     if (!(snapshot.wikiVault.pagePrefix ?? '').trim())
         errs.push('wikiVault.pagePrefix');
+    // 就绪性（managed provider/model 是否已配好）是运行时探测，不在此校验；仅 mode 枚举把关。
+    const reMode = snapshot.reviewEngine?.mode;
+    if (reMode !== 'delegate' && reMode !== 'managed')
+        errs.push('reviewEngine.mode');
     for (const role of ROLES) {
         const m = snapshot.roles.models[role];
         if (!m)
@@ -97,5 +118,21 @@ export function diffOverride(baseline, snapshot) {
     }
     if (Object.keys(models).length)
         out.roles = { models: models };
+    const bre = baseline.reviewEngine ?? { mode: 'delegate', managed: { provider: '', model: '' } };
+    const snapMode = snapshot.reviewEngine?.mode ?? 'delegate';
+    const snapProvider = snapshot.reviewEngine?.managed?.provider ?? '';
+    const snapModel = snapshot.reviewEngine?.managed?.model ?? '';
+    const re = {};
+    if (snapMode !== bre.mode)
+        re.mode = snapMode;
+    const reManaged = {};
+    if (snapProvider !== bre.managed.provider)
+        reManaged.provider = snapProvider;
+    if (snapModel !== bre.managed.model)
+        reManaged.model = snapModel;
+    if (Object.keys(reManaged).length)
+        re.managed = reManaged;
+    if (Object.keys(re).length)
+        out.reviewEngine = re;
     return out;
 }

package/lib/domain/delivery-contract.d.ts

@@ -4,7 +4,7 @@ export declare function requiredDeliveryKeys(assignee: Role, mode: TaskMode): st
 export declare function missingPtDecisionKeys(handoff: Handoff | undefined): string[];
 /** 缺失的交付键（存在但为空的字符串/非字符串均视为缺失；pt_decision 走结构校验透传细粒度键）。
  *  可选 kbUrlBase：提供时对 w:kb 的 kb_url 做 host 前缀硬校验（防 LLM 手写错域名）、对 page_path 做
- *  命名空间格式校验（Q3&5：防 LLM 自造路径/拼错层级）——未提供则仅非空校验（兼容旧调用/测试）。 */
+ *  命名空间格式校验（防 LLM 自造路径/拼错层级）——未提供则仅非空校验（兼容旧调用/测试）。 */
 export declare function missingDeliveryKeys(assignee: Role, mode: TaskMode, handoff: Handoff | undefined, kbUrlBase?: string): string[];
 export declare function hasRequiredDelivery(assignee: Role, mode: TaskMode, handoff: Handoff | undefined): boolean;
 /** 交付契约缺失的父卡项（供 V 建下游卡前的前置校验）。 */
@@ -15,5 +15,5 @@ export interface MissingParentDelivery {
     missing: string[];
 }
 /** 对一组父任务 id 做交付契约校验，返回缺关键交付物的父卡清单（无缺失返回空数组）。
- *  kbUrlBase 可选透传 missingDeliveryKeys（与 Task 4 的 C1 推导修正配套——local 模式传 '' 走 strict local 分支）。 */
+ *  kbUrlBase 可选透传 missingDeliveryKeys（与上方 kbUrlBase 推导修正配套——local 模式传 '' 走 strict local 分支）。 */
 export declare function missingParentDelivery(state: BoardState, parentIds: string[], kbUrlBase?: string): MissingParentDelivery[];

package/lib/domain/delivery-contract.js

@@ -1,6 +1,6 @@
 import { isAllowedWikiPagePath, isLocalKbPagePath, KB_PAGE_NAMESPACES_HINT } from '../wiki/page-path.js';
 /**
- * 上游交付契约（R20「上游对下游负责」宗旨）：每阶段任务完成交接 metadata 必须产出的键。
+ * 上游交付契约（「上游对下游负责」宗旨）：每阶段任务完成交接 metadata 必须产出的键。
  * key = `${assignee}:${mode}`；仅列出「下游实际读取」的硬交付物——
  *   - w:kb（W2/W3）：kb_url + page_path = KB 同步页（下游 wiki_read 读原文 / 收尾）
  *   - p:openspec（P）：artifacts_path = openspec 实施计划产物路径（W2 读取同步 KB）；
@@ -32,7 +32,7 @@ export function missingPtDecisionKeys(handoff) {
 }
 /** 缺失的交付键（存在但为空的字符串/非字符串均视为缺失；pt_decision 走结构校验透传细粒度键）。
  *  可选 kbUrlBase：提供时对 w:kb 的 kb_url 做 host 前缀硬校验（防 LLM 手写错域名）、对 page_path 做
- *  命名空间格式校验（Q3&5：防 LLM 自造路径/拼错层级）——未提供则仅非空校验（兼容旧调用/测试）。 */
+ *  命名空间格式校验（防 LLM 自造路径/拼错层级）——未提供则仅非空校验（兼容旧调用/测试）。 */
 export function missingDeliveryKeys(assignee, mode, handoff, kbUrlBase) {
     const keys = requiredDeliveryKeys(assignee, mode);
     if (keys.length === 0)
@@ -40,7 +40,7 @@ export function missingDeliveryKeys(assignee, mode, handoff, kbUrlBase) {
     if (!handoff)
         return keys.slice();
     const m = handoff.metadata ?? {};
-    // 推导修正（审查 C1）：kbUrlBase === undefined 才是宽松；'' 是 local strict
+    // 推导修正：kbUrlBase === undefined 才是宽松；'' 是 local strict
     const hasBase = kbUrlBase !== undefined;
     const base = hasBase ? kbUrlBase.replace(/\/$/, '') : null;
     const strict = base !== null;
@@ -52,7 +52,7 @@ export function missingDeliveryKeys(assignee, mode, handoff, kbUrlBase) {
         }
         const v = m[k];
         if (strict && k === 'kb_url' && base === '') {
-            // local 模式（D5）：kb_url 必须显式空串（非缺失键）
+            // local 模式：kb_url 必须显式空串（非缺失键）
             if (typeof v !== 'string' || v.trim() !== '')
                 missing.push(`${k} (本地模式 kb_url 必须为空串)`);
             continue;
@@ -77,7 +77,7 @@ export function hasRequiredDelivery(assignee, mode, handoff) {
     return missingDeliveryKeys(assignee, mode, handoff).length === 0;
 }
 /** 对一组父任务 id 做交付契约校验，返回缺关键交付物的父卡清单（无缺失返回空数组）。
- *  kbUrlBase 可选透传 missingDeliveryKeys（与 Task 4 的 C1 推导修正配套——local 模式传 '' 走 strict local 分支）。 */
+ *  kbUrlBase 可选透传 missingDeliveryKeys（与上方 kbUrlBase 推导修正配套——local 模式传 '' 走 strict local 分支）。 */
 export function missingParentDelivery(state, parentIds, kbUrlBase) {
     const out = [];
     for (const pid of parentIds) {

package/lib/domain/delivery-evidence.d.ts

@@ -1,6 +1,6 @@
 import type { Handoff } from './types.js';
 /**
- * R20 D(execute) 交付物证据判定（C1/C2 共用）：
+ * D(execute) 交付物证据判定：
  * 完成交接 metadata 必须带 changed_files（非空）+ (commit_hash | push) 至少其一，
  * 才算具备"实际执行并产出 git 产物"的证据。无证据 → 不判链完成 / kanban_complete 拒绝。
  *

package/lib/domain/delivery-evidence.js

@@ -1,5 +1,5 @@
 /**
- * R20 D(execute) 交付物证据判定（C1/C2 共用）：
+ * D(execute) 交付物证据判定：
  * 完成交接 metadata 必须带 changed_files（非空）+ (commit_hash | push) 至少其一，
  * 才算具备"实际执行并产出 git 产物"的证据。无证据 → 不判链完成 / kanban_complete 拒绝。
  *

package/lib/domain/event-store.js

@@ -18,7 +18,7 @@ export class FileEventStore {
         }
     }
     async append(ev) {
-        // P1-8：seq 每次从文件尾行重读分配（跨进程安全，多 dsh 实例并发追加时 seq 唯一）；
+        // seq 每次从文件尾行重读分配（跨进程安全，多 dsh 实例并发追加时 seq 唯一）；
         // appendFileSync 单行 JSONL 追加在 POSIX 上原子（行 < 4KB，无锁无残留）。
         const all = this.readAllSync();
         const seq = all.length > 0 ? all[all.length - 1].seq + 1 : 0;

package/lib/domain/im-message.d.ts

@@ -0,0 +1,15 @@
+import type { BoardState, KanbanEvent, Task } from './types.js';
+/** W3 收尾判据（镜像 kanban-service.completeTask 机械规则，但不含 dEvidenceOk 与链状态要求）：
+ *  完成卡为 w+kb、链上无未终态卡、它是最后完成的卡、且链上存在 done 的 D 卡（防 W2 中间态误投）。 */
+export declare function isFinalW3Completion(state: BoardState, chainId: string, completedTaskId: string): boolean;
+/** 成功汇报（markdown）。判据不满足（W2 中间态/非 w:kb/非收尾）返回 null。 */
+export declare function buildCompletionMessage(state: BoardState, chainId: string, completedTaskId: string, now: number): string | null;
+export declare function suggestionsFor(reason: string): string[];
+/** 链下全部 blocked 卡（title + 最近一次 task/blocked 原因）。 */
+export declare function latestBlockedTasks(events: KanbanEvent[], tasks: Iterable<Task>, chainId: string): Array<{
+    id: string;
+    title: string;
+    reason: string;
+}>;
+/** 阻塞通知（markdown）。 */
+export declare function buildBlockMessage(state: BoardState, chainId: string, chainReason: string, storageDir: string): string;