@joekytc/dsh-swarm 0.1.2 → 0.2.0

package/lib/dispatcher/dispatcher.js

@@ -2,6 +2,8 @@ import { readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { KanbanProvider } from '../services/kanban-provider.js';
 import { WikiVaultClient } from '../wiki/wiki-vault-client.js';
+import { LocalWikiClient } from '../wiki/local-kb-client.js';
+import { ensureLocalKbRoot } from '../wiki/local-kb.js';
 import { EventWaker } from './event-waker.js';
 import { VOrchestrator } from './v-orchestrator.js';
 import { AgentRunner } from './agent-runner.js';
@@ -62,6 +64,21 @@ function logToFile(file, msg) {
     }
     catch { /* 忽略写失败 */ }
 }
+/** wakeImpl 装配（防线②，2026-09-04 mtmgp81q 死法教训）：wakeV 异常必须落盘 dispatcher.log——
+ *  原实现仅 console.error，无控制台运行时零痕迹（排障最大障碍）。吞异常是为防 withTimeout
+ *  超时后迟到的 rejection 变 unhandledRejection；onSettled（saveOrchs）无论成败都执行。 */
+export function makeWakeImpl(wakeV, logFile, onSettled) {
+    return async (chainId) => {
+        try {
+            await wakeV(chainId);
+        }
+        catch (err) {
+            console.error('[dsh-swarm][debug] wakeV error chain=' + chainId + ': ' + String(err));
+            logToFile(logFile, '[wakeV] error chain=' + chainId + ': ' + String(err));
+        }
+        onSettled();
+    };
+}
 /** 修复轮 6：单次异步操作加超时护栏——一个挂起的 V 编排会话不得卡死整个调度器 tick。 */
 function withTimeout(p, ms, label) {
     return Promise.race([
@@ -69,6 +86,10 @@ function withTimeout(p, ms, label) {
         new Promise((_, reject) => setTimeout(() => reject(new Error('timeout: ' + label)), ms)),
     ]);
 }
+/** 防线①：链级进度看门狗阈值。tick=2000ms × 45 ticks = 90s 无进展即重唤醒（grill Q2 决议）。 */
+export const STALL_WATCHDOG_TICKS = 45;
+/** 防线①：链级重唤醒上限（grill Q3 决议：超限 [create-failed] + chain/blocked）。 */
+export const STALL_WATCHDOG_REWAKE_LIMIT = 3;
 /** 调度器：事件唤醒 V（R20 逐阶段建卡）+ 每任务一次性角色 agent + 心跳看门狗。
  *  - B1：failed 且 attempts<maxRetries 的任务重派（claim→running，AgentRunner resume 同一会话）；
  *        attempts≥maxRetries 熔断 blocked(gave_up)。
@@ -82,8 +103,12 @@ export class Dispatcher {
     maxRetries;
     stateFile;
     logFile;
+    agents; // Fix round 1：宿主 agents 注册表（热重载豁免判据）
+    stallProbe;
     lastSeq = null; // null=尚未加载（首轮 tick 从状态文件/事件日志尾行恢复）
+    orphanReconciled = false; // 启动 reconcile（G）一次性闸：仅首轮 tick 执行孤儿收敛
     inFlight = false;
+    stallState = new Map();
     timer = null;
     constructor(deps) {
         this.kanban = deps.kanban;
@@ -93,6 +118,8 @@ export class Dispatcher {
         this.maxRetries = deps.maxRetries;
         this.stateFile = deps.stateFile;
         this.logFile = deps.logFile;
+        this.agents = deps.agents;
+        this.stallProbe = deps.stallProbe;
     }
     async ensureLastSeq(state) {
         if (this.lastSeq !== null)
@@ -100,7 +127,17 @@ export class Dispatcher {
         // 修复轮 6：无状态文件（首次启动）时从 -1 起处理全部事件，避免跳过已存在的
         // chain/created / spec-card/approved 等可唤醒事件导致 V 永不建卡（B6 回归）。
         // 重放安全：VOrchestrator.wakeV 的 B6 幂等（已有匹配卡则跳过）保证不重复建卡。
-        this.lastSeq = loadLastSeq(this.stateFile) ?? -1;
+        let loaded = loadLastSeq(this.stateFile) ?? -1;
+        // 游标自愈：purge/renumber（整链硬删除物理重排 events.jsonl seq）或外部修复会把
+        // 新事件 seq 压到旧游标之下，若不钳回，spec-card/approved 等可唤醒事件将被永久
+        // 跳过 → V 永不建卡（2026-09-02 实测事故）。游标超前即视为状态文件失效，回退
+        // 全量重放；重复唤醒由 wakeV B6 幂等与 done 卡不可变兜底。
+        const maxSeq = state.events.length > 0 ? state.events[state.events.length - 1].seq : -1;
+        if (loaded > maxSeq) {
+            logToFile(this.logFile, '[tick] lastSeq=' + loaded + ' > maxSeq=' + maxSeq + ' (post-purge cursor skew) → rewind to -1 and replay');
+            loaded = -1;
+        }
+        this.lastSeq = loaded;
         logToFile(this.logFile, '[tick] initial lastSeq=' + this.lastSeq);
     }
     async tick() {
@@ -110,6 +147,13 @@ export class Dispatcher {
         try {
             const state = await this.kanban.snapshot();
             await this.ensureLastSeq(state);
+            // 启动 reconcile（G）：仅首轮执行，位置在游标自愈之后、正常事件消费之前——
+            // 游标 rewind 可能全量重放旧事件，必须先把上次进程遗留的 running 孤儿卡收敛为 blocked，
+            // 消除「进程重启 → whenIdle 协程死亡 → 卡 running 悬挂到看门狗 4h」的口子。
+            if (!this.orphanReconciled) {
+                this.orphanReconciled = true;
+                await reconcileOrphanRunningTasks(this.kanban, state.tasks.values(), this.logFile, this.agents);
+            }
             let advanced = false;
             for (const ev of state.events) {
                 if (ev.seq > this.lastSeq) {
@@ -141,6 +185,7 @@ export class Dispatcher {
                 }
             }
             await this.watchdog.tick();
+            await this.chainStallWatchdog(state);
         }
         catch (e) {
             console.error('[dsh-swarm][debug] tick error: ' + String(e));
@@ -150,10 +195,103 @@ export class Dispatcher {
             this.inFlight = false;
         }
     }
+    /** 防线①：链级进度看门狗（与 wakeVInner 内建 stall 互补，后者挂在 wakeVInner 内部，
+     *  异常退出/挂起/未触发时失效——2026-09-04 mtmgp81q）。只看最终事实：
+     *  executing 非 summary + 链上零非终态任务卡 + 无在途唤醒 + 本链无新看板事件，
+     *  持续 STALL_WATCHDOG_TICKS 个 tick → 重唤醒（≤STALL_WATCHDOG_REWAKE_LIMIT 次）→
+     *  仍停滞 → [create-failed] 评论（有锚点卡时）+ blockChain 终态（人工恢复=删链重跑）。 */
+    async chainStallWatchdog(state) {
+        if (!this.stallProbe)
+            return;
+        for (const chain of state.chains.values()) {
+            if (chain.status !== 'executing') {
+                this.stallState.delete(chain.id);
+                continue;
+            }
+            const orch = this.stallProbe.orchestrationOf(chain.id);
+            if (!orch || orch.phase === 'summary') {
+                this.stallState.delete(chain.id);
+                continue;
+            }
+            const seen = this.stallState.get(chain.id) ?? { ticks: 0, rewakes: 0, lastSeq: -1 };
+            const set = () => this.stallState.set(chain.id, seen);
+            // 本链最新事件 seq：有新事件 = 链有活动（任何 kind，含评论/心跳）。
+            // 重置计数后不 continue：无新事件的首个观测 tick 即停滞计数起点（否则 45 tick 只累计 44，
+            // 与 brief 测试「STALL_WATCHDOG_TICKS 个 tick → 重唤醒」差一拍——实测 2026-09-04）。
+            let chainMaxSeq = -1;
+            for (let i = state.events.length - 1; i >= 0; i--) {
+                const e = state.events[i];
+                if (e.chainId === chain.id) {
+                    chainMaxSeq = e.seq;
+                    break;
+                }
+            }
+            if (chainMaxSeq > seen.lastSeq) {
+                seen.lastSeq = chainMaxSeq;
+                seen.ticks = 0;
+                set();
+            }
+            if (this.stallProbe.isWakeInFlight(chain.id)) {
+                seen.ticks = 0;
+                set();
+                continue;
+            }
+            const chainTasks = [...state.tasks.values()].filter((t) => t.chainId === chain.id);
+            if (chainTasks.some((t) => t.status !== 'done' && t.status !== 'archived')) {
+                seen.ticks = 0;
+                set();
+                continue;
+            }
+            seen.ticks += 1;
+            if (seen.ticks < STALL_WATCHDOG_TICKS) {
+                set();
+                continue;
+            }
+            if (seen.rewakes < STALL_WATCHDOG_REWAKE_LIMIT) {
+                seen.rewakes += 1;
+                seen.ticks = 0;
+                set();
+                logToFile(this.logFile, `[stall-watchdog] zero-progress chain=${chain.id} phase=${orch.phase} → rewake ${seen.rewakes}/${STALL_WATCHDOG_REWAKE_LIMIT}`);
+                this.stallProbe.wake(chain.id).catch((err) => logToFile(this.logFile, '[stall-watchdog] wake failed chain=' + chain.id + ': ' + String(err)));
+                continue;
+            }
+            // 终态显形
+            const anchor = chainTasks.at(-1);
+            if (anchor) {
+                const already = state.events.some((e) => e.taskId === anchor.id && e.kind === 'task/commented' && String(e.payload['body'] ?? '').startsWith('[create-failed]'));
+                if (!already) {
+                    try {
+                        await this.kanban.comment(anchor.id, `[create-failed] 看门狗：链持续无进展且自动重唤醒 ${STALL_WATCHDOG_REWAKE_LIMIT} 次未建卡（phase=${orch.phase}），已置 blocked，请人工处理。`, 'system');
+                    }
+                    catch (err) {
+                        logToFile(this.logFile, '[stall-watchdog] comment failed chain=' + chain.id + ': ' + String(err));
+                    }
+                }
+            }
+            try {
+                await this.kanban.blockChain(chain.id, `[stall-watchdog] phase=${orch.phase} 持续无进展，重唤醒 ${STALL_WATCHDOG_REWAKE_LIMIT} 次未建卡`);
+            }
+            catch (err) {
+                logToFile(this.logFile, '[stall-watchdog] blockChain failed chain=' + chain.id + ': ' + String(err));
+            }
+            logToFile(this.logFile, `[stall-watchdog] chain=${chain.id} → blocked`);
+            this.stallState.delete(chain.id);
+        }
+    }
     start(intervalMs) {
         this.stop();
         this.timer = setInterval(() => { void this.tick(); }, intervalMs);
     }
+    /** 整链硬删除联动（E）：purge 物理重排 events.jsonl seq，游标必须同步钳到当前 maxSeq。
+     *  否则删链后新建链的可唤醒事件（seq < 旧内存游标）被运行中实例永久跳过——A1 仅在启动时自愈，
+     *  覆盖不了运行中删链场景（2026-09-02 残留审计结论）。 */
+    async onPurge() {
+        const state = await this.kanban.snapshot();
+        const maxSeq = state.events.length > 0 ? state.events[state.events.length - 1].seq : -1;
+        this.lastSeq = maxSeq;
+        saveLastSeq(this.stateFile, maxSeq);
+        logToFile(this.logFile, '[onPurge] cursor synced to maxSeq=' + maxSeq);
+    }
     stop() {
         if (this.timer) {
             clearInterval(this.timer);
@@ -162,9 +300,70 @@ export class Dispatcher {
     }
 }
 /** 调度层装配：事件唤醒 V（R20 逐阶段建卡）+ 每任务一次性角色 agent + 心跳看门狗。
- *  仅在 agents 与 kanban 服务同时可用时由插件入口调用（不依赖可能已错过的 ready 事件）。 */
-export function startDispatcher(ctx, config) {
-    const storageDir = config.storageDir.replace('$DSH_HOME', process.env.DSH_HOME ?? process.cwd());
+ *  仅在 agents 与 kanban 服务同时可用时由插件入口调用（不依赖可能已错过的 ready 事件）。
+ *  Task 7：收 ConfigProvider——storageDir 取启动时快照；wiki/模型链经 getEffective() 调用时热读取。 */
+/** 启动 reconcile（F）：剔除事件流中已不存在的链的编排 entry（历史残留/外部 purge）。
+ *  原地删除并返回被移除的 chainId 列表（调用方负责持久化与日志）。 */
+export function reconcileOrchestrations(orch, chains) {
+    const removed = [...orch.keys()].filter((k) => !chains.has(k));
+    for (const k of removed)
+        orch.delete(k);
+    return removed;
+}
+/** 启动 reconcile（G）：进程重启会杀死 runner 的 whenIdle 协程，上次遗留的 running 卡无人收尾，
+ *  看门狗默认 4h（staleTimeoutSeconds=14400）才回收——重启后立即把 running 孤儿卡收敛为 blocked
+ *  （system comment + blockTask），中断显形且可重派续跑（重派将 resume 同一会话，进度保留）。
+ *  状态机注：TaskStatus 无独立 'claimed' 态——claimTask 发 task/claimed 事件后投影即为 running，
+ *  扫描 running 即覆盖「claimed 未收尾」；todo/ready/triage 从未派发，done/blocked/failed/archived
+ *  已有归属或终态（且 failed 的处置归 B1 重派/熔断管辖），均不动。
+ *  Fix round 1（热重载兼容，双重判据）：收敛每张 running 卡前先查宿主 agents 注册表
+ *  ctx.get('agents').get('kbn-<taskId>')（session id 构造同 AgentRunner.resumeOrReuse，Task 2 同款探明）。
+ *  两个世界的分野：
+ *  - 进程重启：agents 注册表随宿主进程消亡，新进程内 kbn-<taskId> 必然查不到（undefined）
+ *    → 会话已死 → 全部收敛，语义与修复前一致；
+ *  - 插件热重载：宿主进程未死，dsh 插件重载重跑 startDispatcherInner → orphanReconciled 闸复位，
+ *    但宿主 agent 会话仍 live（注册表命中）→ 本进程真在跑，不是孤儿 → 跳过该卡，
+ *    避免把合法 running 卡误收敛为 blocked。
+ *  agents 服务缺失 / 无 get 方法（测试桩/异常宿主）→ 无法证明 live，按原行为收敛（保守）。
+ *  调用位置必须在游标自愈（ensureLastSeq）之后、事件消费之前：游标 rewind 会全量重放旧事件，
+ *  先收敛孤儿可保证本次 tick 消费的重放事件面对的是已收敛状态，且孤儿产生的 block 事件天然
+ *  落在本轮快照之外（下一轮才被消费唤醒 V 走阻塞复核），不与启动重放交错。
+ *  幂等：仅启动执行一次（调用方置闸）；对同一卡重复调用时状态机拒绝 running→blocked 之外的
+ *  非法转换，comment/block 失败均 try/catch 记日志跳过不抛（单卡失败不阻断其余收敛）。 */
+export async function reconcileOrphanRunningTasks(kanban, tasks, logFile, agents) {
+    const orphans = [...tasks].filter((t) => t.status === 'running');
+    const agentsSvc = agents;
+    const handled = [];
+    for (const t of orphans) {
+        const live = typeof agentsSvc?.get === 'function' ? agentsSvc.get('kbn-' + t.id) : undefined;
+        if (live) {
+            // 宿主注册表命中 → 会话仍 live（热重载世界），本进程真在跑，跳过不收敛
+            logToFile(logFile, '[orphan-reconcile] skip live session task=' + t.id + ' (host reload, session alive)');
+            continue;
+        }
+        try {
+            await kanban.comment(t.id, '[runner-interrupted] dsh 重启中断会话，置为阻塞以便重派续跑（进度保留，重派将 resume 同会话）', 'system');
+        }
+        catch (err) {
+            // comment 无状态语义且恒放行，失败仅可能是存储层异常——记日志后仍继续 block
+            logToFile(logFile, '[orphan-reconcile] comment failed task=' + t.id + ': ' + String(err));
+        }
+        try {
+            await kanban.blockTask(t.id, 'runner-interrupted: 进程重启，会话中断', 'system');
+            handled.push(t.id);
+        }
+        catch (err) {
+            // 防御：状态机拒绝（卡恰被并发流转/已收敛）→ 记日志跳过，不抛
+            logToFile(logFile, '[orphan-reconcile] block failed task=' + t.id + ': ' + String(err));
+        }
+    }
+    if (handled.length > 0) {
+        logToFile(logFile, '[orphan-reconcile] reconciled orphan running tasks: ' + handled.join(','));
+    }
+    return handled;
+}
+export function startDispatcher(ctx, configProvider) {
+    const storageDir = configProvider.getEffective().storageDir.replace('$DSH_HOME', process.env.DSH_HOME ?? process.cwd());
     const logFile = join(storageDir, 'dispatcher.log');
     const provider = ctx.get('kanban');
     const agents = ctx.get('agents');
@@ -174,17 +373,24 @@ export function startDispatcher(ctx, config) {
         return;
     }
     try {
-        startDispatcherInner(ctx, config, storageDir, logFile, provider, agents);
+        startDispatcherInner(ctx, configProvider, storageDir, logFile, provider, agents);
     }
     catch (err) {
         logToFile(logFile, '[startDispatcher] FAILED: ' + String(err));
         console.error('[dsh-swarm][debug] startDispatcher failed: ' + String(err));
     }
 }
-/** 调度器装配主体（startDispatcher 的容错包裹内执行，异常落盘不阻断插件加载）。 */
-function startDispatcherInner(ctx, config, storageDir, logFile, provider, agents) {
+/** 调度器装配主体（startDispatcher 的容错包裹内执行，异常落盘不阻断插件加载）。
+ *  config = 启动时快照，仅喂静态依赖（EventWaker/Watchdog/maxRetries）；
+ *  wiki 与模型链读点走 configProvider.getEffective() 热生效（Task 7）。 */
+function startDispatcherInner(ctx, configProvider, storageDir, logFile, provider, agents) {
+    const config = configProvider.getEffective();
     const kanban = provider.service;
-    const wiki = new WikiVaultClient(config.wikiVault);
+    // D2 双模式：local 走 LocalWikiClient（互链读写落本地库），remote 用配置的 WikiVaultClient（Task 10 同款分支）。
+    // 消费方（AgentRunner/VOrchestrator）字段仍标 WikiVaultClient——local 为 LocalWikiClient（read/write/search 同面），Task 10 同款断言。
+    const wiki = (configProvider.mode === 'local'
+        ? new LocalWikiClient(ensureLocalKbRoot())
+        : new WikiVaultClient(() => configProvider.getEffective().wikiVault));
     const defaultModel = resolveDefaultModel(ctx);
     console.info('[dsh-swarm] role default model = ' + (defaultModel ? defaultModel.provider + '/' + defaultModel.model : 'none'));
     const orchFile = join(storageDir, 'orchestration.json');
@@ -201,7 +407,7 @@ function startDispatcherInner(ctx, config, storageDir, logFile, provider, agents
         }
         catch { /* 忽略写失败 */ }
     };
-    const vOrch = new VOrchestrator(ctx, kanban, agents, config, orchestrations, wiki, defaultModel);
+    const vOrch = new VOrchestrator(ctx, kanban, agents, configProvider, orchestrations, wiki, defaultModel);
     // D23：链完成验收核对（重）——Chain(completed) 时核对主会话是否越权写工作区产物；
     // 发现越权 → chain/audit-warning，阻塞最终汇报直至用户 GUI 确认（chain/audit-confirmed）。
     const auditor = new ChainAuditor({
@@ -242,15 +448,8 @@ function startDispatcherInner(ctx, config, storageDir, logFile, provider, agents
         }
     });
     const waker = new EventWaker(ctx, config);
-    waker.setWakeImpl(async (chainId) => {
-        try {
-            await vOrch.wakeV(chainId);
-        }
-        catch (err) {
-            console.error('[dsh-swarm][debug] wakeV error chain=' + chainId + ': ' + String(err));
-        }
-        saveOrchs();
-    });
+    vOrch.onOrchChange = saveOrchs; // Fix D：stall re-wake 路径绕过 EventWaker，orch 变化自行落盘
+    waker.setWakeImpl(makeWakeImpl(vOrch.wakeV.bind(vOrch), logFile, saveOrchs));
     // 0.1.0 delegation（spec FR2）：全局子代理写护栏——普通插件 ctx 上注册的 guard 全局
     // 生效（dsh-tools：普通上下文守卫全局生效，agent.ctx 守卫仅对该 agent 生效）。
     // guard 内部仅对 kanban-dt 系会话收紧；DT 父会话自身仍由 agent-runner 的 agent.ctx
@@ -260,7 +459,7 @@ function startDispatcherInner(ctx, config, storageDir, logFile, provider, agents
     if (unguardSubagents) {
         ctx.on('dispose', unguardSubagents);
     }
-    const runner = new AgentRunner(ctx, kanban, config, wiki, defaultModel);
+    const runner = new AgentRunner(ctx, kanban, configProvider, wiki, defaultModel);
     provider.runner = runner; // T32 fix：HTTP retry 复用同一执行器（failed→claim→spawn/resume）
     const watchdog = new Watchdog(kanban, config.dispatcher);
     const dispatcher = new Dispatcher({
@@ -271,10 +470,34 @@ function startDispatcherInner(ctx, config, storageDir, logFile, provider, agents
         maxRetries: config.dispatcher.maxRetries,
         stateFile: join(dirname(orchFile), 'dispatcher-state.json'), // 与事件日志同目录（B6）
         logFile,
+        agents, // Fix round 1：启动 reconcile 热重载豁免判据（宿主 agents 注册表）
+        stallProbe: vOrch, // 防线①：链级停滞探针（orchestrationOf/isWakeInFlight/wake）
     });
-    ctx.on('dispose', () => { dispatcher.stop(); watchdog.stop(); });
+    ctx.on('dispose', () => { dispatcher.stop(); watchdog.stop(); vOrch.dispose(); });
     dispatcher.start(2000);
     watchdog.start(config.dispatcher.heartbeatIntervalSeconds * 1000);
     logToFile(logFile, '[startDispatcher] dispatcher started (tick=2000ms)');
     void dispatcher.tick();
+    // 整链硬删除联动（E/F/G-min）：purge 物理重排事件 seq → 游标同步钳回（运行中实例不重启发跳过）；
+    // V 编排 entry 同步剔除。kanban-http 的 delete 分支调用 provider.onChainDeleted。
+    provider.onChainDeleted = async (chainId) => {
+        await dispatcher.onPurge();
+        orchestrations.delete(chainId);
+        saveOrchs();
+        logToFile(logFile, '[chain-deleted] cursor synced + orch entry removed chain=' + chainId);
+    };
+    // 启动 reconcile（F）：历史残留/外部 purge 留下的死链编排 entry，按事件流存活链剔除
+    void (async () => {
+        try {
+            const snap = await kanban.snapshot();
+            const removed = reconcileOrchestrations(orchestrations, new Set(snap.chains.keys()));
+            if (removed.length > 0) {
+                saveOrchs();
+                logToFile(logFile, '[orch-reconcile] removed dead entries: ' + removed.join(','));
+            }
+        }
+        catch (err) {
+            logToFile(logFile, '[orch-reconcile] failed: ' + String(err));
+        }
+    })();
 }

package/lib/dispatcher/session-events.d.ts

@@ -1,9 +1,11 @@
 /**
  * 会话事件条目统一读取助手（修复轮 6，举一反三）：
- * dsh-session 的 session.events 条目落盘形态为 { type, seq, time, data: { ... } }（append 时
- * data 嵌套在 data 键下），name/arguments 等字段位于 e.data 下而非顶层。
+ * 0.1.2（DSH-0.1.2-A4-03）起 Session.events getter 已移除——宿主新读取面是
+ * `session.seq`（日志长度）+ `session.snapshotEvents(fromSeq?, toSeqExclusive?)`。
+ * 事件条目形态（落盘与快照一致）为 { type, seq, time, data: { ... } }（append 时
+ * name/arguments 位于 e.data 下而非顶层）。
  * 本助手兼容两种形态（顶层展开 / data 嵌套），供 v-orchestrator / agent-runner / chain-auditor
- * 等所有读取 agent.session.events 的消费点使用，避免逐个踩 `e.name 取不到` 的坑。
+ * 等所有消费点使用（先 snapshotEvents()、无则回退 events、再 []），避免逐个踩 `e.name 取不到` 的坑。
  */
 /** 取事件类型（如 'tool/call'）。 */
 export declare function eventType(e: {
@@ -13,16 +15,10 @@ export declare function eventType(e: {
     };
 }): string | undefined;
 /** 取工具调用名（如 'kanban_complete' / 'bash' / 'kanban_create'）。 */
-export declare function toolName(e: {
-    name?: unknown;
-    data?: {
-        name?: unknown;
-    };
-}): string | undefined;
+export declare function toolName(e: unknown): string | undefined;
 /** 取工具调用参数对象（兼容 JSON 字符串 / 对象两种落盘形态）。 */
-export declare function toolArgs(e: {
-    arguments?: unknown;
-    data?: {
-        arguments?: unknown;
-    };
-}): Record<string, unknown>;
+export declare function toolArgs(e: unknown): Record<string, unknown>;
+/** 取 assistant 消息的网关缓存回放标记（replayState.response.responseModel，如 'from-cache'）。
+ *  非 assistant/message 或无标记返回 null。2026-09-04：远程网关回复缓存整包回放时由 SSE
+ *  id/model 字段透传（dsh 纯透传），插件侧据此识别缓存劫持零产出。 */
+export declare function replayModel(e: unknown): string | null;

package/lib/dispatcher/session-events.js

@@ -1,10 +1,12 @@
 // src/dispatcher/session-events.ts
 /**
  * 会话事件条目统一读取助手（修复轮 6，举一反三）：
- * dsh-session 的 session.events 条目落盘形态为 { type, seq, time, data: { ... } }（append 时
- * data 嵌套在 data 键下），name/arguments 等字段位于 e.data 下而非顶层。
+ * 0.1.2（DSH-0.1.2-A4-03）起 Session.events getter 已移除——宿主新读取面是
+ * `session.seq`（日志长度）+ `session.snapshotEvents(fromSeq?, toSeqExclusive?)`。
+ * 事件条目形态（落盘与快照一致）为 { type, seq, time, data: { ... } }（append 时
+ * name/arguments 位于 e.data 下而非顶层）。
  * 本助手兼容两种形态（顶层展开 / data 嵌套），供 v-orchestrator / agent-runner / chain-auditor
- * 等所有读取 agent.session.events 的消费点使用，避免逐个踩 `e.name 取不到` 的坑。
+ * 等所有消费点使用（先 snapshotEvents()、无则回退 events、再 []），避免逐个踩 `e.name 取不到` 的坑。
  */
 /** 取事件类型（如 'tool/call'）。 */
 export function eventType(e) {
@@ -13,12 +15,14 @@ export function eventType(e) {
 }
 /** 取工具调用名（如 'kanban_complete' / 'bash' / 'kanban_create'）。 */
 export function toolName(e) {
-    const n = e?.name ?? e?.data?.name;
+    const rec = e;
+    const n = rec?.name ?? rec?.data?.name;
     return typeof n === 'string' ? n : undefined;
 }
 /** 取工具调用参数对象（兼容 JSON 字符串 / 对象两种落盘形态）。 */
 export function toolArgs(e) {
-    const a = e?.arguments ?? e?.data?.arguments;
+    const rec = e;
+    const a = rec?.arguments ?? rec?.data?.arguments;
     if (a && typeof a === 'object')
         return a;
     if (typeof a === 'string') {
@@ -31,3 +35,11 @@ export function toolArgs(e) {
     }
     return {};
 }
+/** 取 assistant 消息的网关缓存回放标记（replayState.response.responseModel，如 'from-cache'）。
+ *  非 assistant/message 或无标记返回 null。2026-09-04：远程网关回复缓存整包回放时由 SSE
+ *  id/model 字段透传（dsh 纯透传），插件侧据此识别缓存劫持零产出。 */
+export function replayModel(e) {
+    const rec = e;
+    const m = rec?.data?.message?.source?.replayState?.response?.responseModel;
+    return typeof m === 'string' ? m : null;
+}

package/lib/dispatcher/v-orchestrator.d.ts

@@ -1,6 +1,6 @@
 import type { Context } from '@deepseek-ai/cordis';
 import type { KanbanService } from '../domain/kanban-service.js';
-import type { KanbanConfig } from '../config.js';
+import type { ConfigProvider } from '../services/config-provider.js';
 import type { Role, TaskMode } from '../domain/types.js';
 import type { WikiVaultClient } from '../wiki/wiki-vault-client.js';
 import type { AgentModelOptions } from './dispatcher.js';
@@ -22,6 +22,15 @@ export declare const R20_PHASE_EXPECT: Record<VPhase, {
  *  P=计划者（绝不执行）、D=唯一执行者（TARGET_REPO 必须取自规格卡 file-prefetch 附件 ref，禁止回退/猜测）、
  *  W=KB 同步（绝不执行代码）。V 把对应模板写入 kanban_create 的 body。 */
 export declare const PHASE_INSTRUCTIONS: Partial<Record<VPhase, string>>;
+/** D9（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 原样回落。
+ *  ctx.taskId 给出则插值确切页路径，缺省用占位符（建卡时 taskId 尚不存在，消费点传 undefined）。 */
+export declare function buildPhaseInstruction(phase: VPhase, ctx: {
+    chainId: string;
+    taskId?: string;
+}, kbMode: 'remote' | 'local'): string;
 interface AgentLike {
     followup(msg: {
         content: {
@@ -33,18 +42,19 @@ interface AgentLike {
         };
     }): void;
     whenIdle(): Promise<void>;
-    session: {
-        events: Array<{
-            name?: string;
-            arguments?: unknown;
-        }>;
-    };
+    /** 宿主形态容忍：dsh 0.1.2-rc.1 下 Session.events 已移除（DSH-0.1.2-A4-03）→
+     *  经 seq/snapshotEvents 读取；events 声明仅为兼容旧宿主/测试。 */
+    session?: {
+        seq?: number;
+        snapshotEvents?(fromSeq?: number, toSeqExclusive?: number): Array<Record<string, unknown>>;
+        events?: Array<Record<string, unknown>>;
+    } | undefined;
 }
 export declare class VOrchestrator {
     private readonly ctx;
     private readonly kanban;
     private readonly agents;
-    private readonly config;
+    private readonly configProvider;
     private readonly orchestrations;
     private readonly wiki;
     private readonly defaultModel;
@@ -55,9 +65,32 @@ export declare class VOrchestrator {
         resume(o: unknown): Promise<{
             agent: AgentLike;
         }>;
-    }, config: KanbanConfig, orchestrations: Map<string, ChainOrchestration>, wiki: WikiVaultClient, defaultModel?: AgentModelOptions);
+    }, configProvider: ConfigProvider, orchestrations: Map<string, ChainOrchestration>, wiki: WikiVaultClient, defaultModel?: AgentModelOptions);
     private currentPhase;
+    /** Fix D：stall 自动再唤醒上限（同一阶段连续零产出 → 自动重试 ≤3 次，间隔递增）后放弃并显形。 */
+    private static readonly STALL_REWAKE_LIMIT;
+    /** Fix D：stall 再唤醒基础延迟（按 stallCount 倍增：5s/10s/15s），给瞬时故障/采样波动恢复窗口。 */
+    private static readonly STALL_REWAKE_DELAY_MS;
+    private rewakeTimers;
+    /** 同链 wakeV 并发防护：在途时后续唤醒合并为 pending，完成后补跑一次（事件不丢）。 */
+    private waking;
+    private pendingWake;
+    /** Fix D：orchestration 变更回调（dispatcher 注入 saveOrchs）——stall re-wake 路径绕过
+     *  EventWaker，其 stallCount/phase 变化需自行落盘，防重启丢重试进度。 */
+    onOrchChange?: () => void;
     wakeV(chainId: string): Promise<void>;
+    /** Fix D：stall 自动再唤醒（≤3 次）。同链 pending 幂等；建卡成功（stallCount=0）后到期的
+     *  re-wake 自动作废（回调内按 stallCount 判空跳过）。 */
+    private scheduleRewake;
+    /** Fix D：清理待触发的 re-wake 定时器（插件 dispose 时调用）。 */
+    dispose(): void;
+    /** 链级看门狗（Dispatcher，防线①）探针：编排 entry；无 entry 返回 null。 */
+    orchestrationOf(chainId: string): ChainOrchestration | null;
+    /** 链级看门狗探针：该链是否有在途唤醒 / 待补跑唤醒 / 待触发再唤醒——任一为真视为「有人在管」。 */
+    isWakeInFlight(chainId: string): boolean;
+    /** 链级看门狗重唤醒入口（Dispatcher 防线①）：复用 wakeV（同链并发合并/补跑幂等内建）。 */
+    wake(chainId: string): Promise<void>;
+    private wakeVInner;
     /** 阻塞复核幂等判定：任务最近一次 task/blocked 之后已存在 [blocked-review] 开头的评论。
      *  注：at 为 Date.now() 毫秒精度，block 与评论可能同毫秒（测试/快路径实测碰撞）→ 用 seq 比较（确定性）。 */
     private hasBlockReview;