@joekytc/dsh-swarm 0.1.0

package/lib/dispatcher/chain-auditor.js

@@ -0,0 +1,194 @@
+// src/dispatcher/chain-auditor.ts
+import { readdirSync } from 'node:fs';
+import { join } from 'node:path';
+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）。 */
+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( 兜底）。
+ *  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 的字符串值（文件路径线索）。 */
+function collectWorkspacePaths(value, root, out) {
+    if (typeof value === 'string') {
+        if (value.includes(root))
+            out.add(value);
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (const item of value)
+            collectWorkspacePaths(item, root, out);
+        return;
+    }
+    if (value && typeof value === 'object') {
+        for (const v of Object.values(value)) {
+            collectWorkspacePaths(v, root, out);
+        }
+    }
+}
+/** 从会话事件读取任意字段（兼容顶层 / data 嵌套两种落盘形态）。 */
+function dataField(e, key) {
+    const obj = (e ?? {});
+    if (obj[key] !== undefined)
+        return obj[key];
+    const d = obj['data'];
+    return d?.[key];
+}
+/** 文本是否含写操作标记（bash 命令 / 兜底 code 字符串共用；含 Python 写 API 标记）。 */
+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)) {
+        collectWorkspacePaths(args, root, paths);
+        return;
+    }
+    if (subs && subs.length > 0) {
+        // run_code 有派发记录：按实际子调用判定；只读子调用（read/glob/grep/bash 只读命令…）不产生证据
+        for (const sub of subs) {
+            if (DIRECT_WRITE_TOOLS.has(sub.name)) {
+                collectWorkspacePaths(sub.arguments, root, paths);
+            }
+            else if (sub.name === 'bash') {
+                const cmd = String(sub.arguments?.command ?? '');
+                if (hasWriteMarker(cmd) && cmd.includes(root))
+                    paths.add(cmd);
+            }
+            else if (sub.name === 'run_code') {
+                const code = String(sub.arguments?.code ?? '');
+                if (hasWriteMarker(code) && code.includes(root))
+                    paths.add(code);
+            }
+        }
+        return;
+    }
+    if (name === 'run_code') {
+        // 兜底：无派发记录（旧会话/未落盘）——仅当 code 含写标记且含工作区路径时才计为写证据
+        const code = String(args?.code ?? '');
+        if (hasWriteMarker(code) && code.includes(root))
+            paths.add(code);
+        return;
+    }
+    if (name === 'bash') {
+        const cmd = String(args?.command ?? '');
+        if (hasWriteMarker(cmd) && cmd.includes(root))
+            paths.add(cmd);
+        return;
+    }
+}
+function sessionWriteEvidence(id, workspacesRoot, events) {
+    // 外层工具调用索引：callId → {name, arguments}
+    const calls = new Map();
+    // run_code 派发子调用索引：rootCallId → [{name, arguments}]
+    const dispatchByRoot = new Map();
+    for (const ev of events) {
+        const t = eventType(ev);
+        if (t === 'tool/call' || t === 'tool-call') {
+            const callId = String(dataField(ev, 'callId') ?? '');
+            const name = String(toolName(ev) ?? '');
+            const args = toolArgs(ev);
+            if (callId) {
+                calls.set(callId, { name, arguments: args });
+            }
+            else {
+                // 兼容无 callId 的扁平事件（旧形态/测试夹具）：按写标记直接判定
+                const flat = new Set();
+                handleCallEvidence(name, args, null, workspacesRoot, flat);
+                if (flat.size > 0) {
+                    return {
+                        source: 'main-session-scan',
+                        detail: '非角色会话（id=' + id + '）对 kanban 工作区路径发起写能力工具调用，疑似主 agent 越权写产物',
+                        paths: [...flat],
+                    };
+                }
+            }
+        }
+        else if (t === 'tool/code-dispatch-start' || t === 'tool/code-dispatch') {
+            const rootCallId = String(dataField(ev, 'rootCallId') ?? '');
+            const name = String(dataField(ev, 'name') ?? '');
+            if (!rootCallId || !name)
+                continue;
+            const arr = dispatchByRoot.get(rootCallId) ?? [];
+            arr.push({ name, arguments: toolArgs(ev) });
+            dispatchByRoot.set(rootCallId, arr);
+        }
+    }
+    const paths = new Set();
+    for (const [callId, call] of calls) {
+        handleCallEvidence(call.name, call.arguments, dispatchByRoot.get(callId) ?? null, workspacesRoot, paths);
+    }
+    if (paths.size === 0)
+        return null;
+    return {
+        source: 'main-session-scan',
+        detail: '非角色会话（id=' + id + '）对 kanban 工作区路径发起写能力工具调用，疑似主 agent 越权写产物',
+        paths: [...paths],
+    };
+}
+export class ChainAuditor {
+    kanban;
+    workspacesRoot;
+    listLiveAgents;
+    constructor(deps) {
+        this.kanban = deps.kanban;
+        this.workspacesRoot = deps.workspacesRoot;
+        this.listLiveAgents = deps.listLiveAgents ?? (() => []);
+    }
+    /** 执行核对，返回越权证据（空=通过，不阻塞汇报）。
+     *  @param workspaceDir 本链发起工作区（Chain.workspaceDir）；提供时仅扫描工作区内的会话（修复轮 7）。 */
+    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- 开头 → 角色会话
+            // 的子代理（childSessionMeta 记录所 join 的 preset id），产物归属 git 证据链，
+            // 不按"主会话越权"判定；源2（无主产物核对）仍兜底其误写链工作区根。
+            const joinedPreset = agent.session?.header?.agentPreset;
+            if (typeof joinedPreset === 'string' && joinedPreset.startsWith('kanban-'))
+                continue;
+            // 修复轮 7：作用域收窄——仅扫本链发起工作区内的会话；会话无 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 ?? []);
+            if (hit)
+                evidence.push(hit);
+        }
+        // 源 2：产物归属核对——链工作区根下非任务 id 的无主条目
+        const orphan = await this.reconcileArtifacts(chainId);
+        if (orphan.length > 0) {
+            evidence.push({
+                source: 'artifact-reconciliation',
+                detail: '链工作区存在不属于任何任务工作区的无主条目，疑似主 agent 越权写入',
+                paths: orphan,
+            });
+        }
+        return evidence;
+    }
+    async reconcileArtifacts(chainId) {
+        const chainDir = join(this.workspacesRoot, chainId);
+        let entries;
+        try {
+            entries = readdirSync(chainDir);
+        }
+        catch {
+            return []; // 无工作区目录 = 无产物，无越权线索
+        }
+        // 链任务 id 集合（角色 agent 只写各自任务工作区）
+        const state = await this.kanban.snapshot();
+        const taskIds = new Set();
+        for (const t of state.tasks.values())
+            if (t.chainId === chainId)
+                taskIds.add(t.id);
+        return entries.filter((name) => !taskIds.has(name)).map((name) => join(chainDir, name));
+    }
+}

package/lib/dispatcher/dispatcher.d.ts

@@ -0,0 +1,50 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { KanbanConfig } from '../config.js';
+import { EventWaker } from './event-waker.js';
+import { Watchdog } from './watchdog.js';
+import type { KanbanService } from '../domain/kanban-service.js';
+export interface AgentModelOptions {
+    provider: string;
+    model: string;
+    reasoningEffort?: string;
+}
+/** 读取部署默认模型（settings 的 agent-default-model 优先，其次 dsh-agent-default-model），角色未单独配置时回退使用。 */
+export declare function resolveDefaultModel(ctx: Context): AgentModelOptions | undefined;
+export interface DispatcherDeps {
+    kanban: KanbanService;
+    runner: {
+        runTask(taskId: string): Promise<void>;
+    };
+    waker: EventWaker;
+    watchdog: Watchdog;
+    maxRetries: number;
+    /** lastSeq 持久化文件（与事件日志同目录，B6）。 */
+    stateFile: string;
+    /** 修复轮 6：调度器运行日志文件（storageDir/dispatcher.log）。 */
+    logFile: string;
+}
+/** 调度器：事件唤醒 V（R20 逐阶段建卡）+ 每任务一次性角色 agent + 心跳看门狗。
+ *  - B1：failed 且 attempts<maxRetries 的任务重派（claim→running，AgentRunner resume 同一会话）；
+ *        attempts≥maxRetries 熔断 blocked(gave_up)。
+ *  - B6：lastSeq 持久化，重启后仅唤醒 lastSeq 之后的事件。
+ *  - R5：inFlight 互斥，防止慢 tick 与下一轮并发重复派发同一任务。 */
+export declare class Dispatcher {
+    private readonly kanban;
+    private readonly runner;
+    private readonly waker;
+    private readonly watchdog;
+    private readonly maxRetries;
+    private readonly stateFile;
+    private readonly logFile;
+    private lastSeq;
+    private inFlight;
+    private timer;
+    constructor(deps: DispatcherDeps);
+    private ensureLastSeq;
+    tick(): Promise<void>;
+    start(intervalMs: number): void;
+    stop(): void;
+}
+/** 调度层装配：事件唤醒 V（R20 逐阶段建卡）+ 每任务一次性角色 agent + 心跳看门狗。
+ *  仅在 agents 与 kanban 服务同时可用时由插件入口调用（不依赖可能已错过的 ready 事件）。 */
+export declare function startDispatcher(ctx: Context, config: KanbanConfig): void;

package/lib/dispatcher/dispatcher.js

@@ -0,0 +1,280 @@
+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 { EventWaker } from './event-waker.js';
+import { VOrchestrator } from './v-orchestrator.js';
+import { AgentRunner } from './agent-runner.js';
+import { Watchdog } from './watchdog.js';
+import { ChainAuditor } from './chain-auditor.js';
+import { mergeDAfterReview } from './merge-gate.js';
+import { buildSubagentTreeGuard } from '../roles/toolsets.js';
+import { syncKbLinks } from '../wiki/kb-linkage.js';
+/** 读取部署默认模型（settings 的 agent-default-model 优先，其次 dsh-agent-default-model），角色未单独配置时回退使用。 */
+export function resolveDefaultModel(ctx) {
+    try {
+        const settings = ctx.get('settings');
+        const m = settings?.get('agent-default-model');
+        if (m?.provider && m?.model) {
+            return m.reasoningEffort
+                ? { provider: m.provider, model: m.model, reasoningEffort: m.reasoningEffort }
+                : { provider: m.provider, model: m.model };
+        }
+    }
+    catch {
+        // settings 不可用则继续尝试 agentDefaultModel
+    }
+    try {
+        const svc = ctx.get('agentDefaultModel');
+        const sel = svc?.currentSelection();
+        return sel?.provider && sel?.model ? sel : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function parentsDone(task, state) {
+    return task.parents.every((pid) => {
+        const parent = state.tasks.get(pid);
+        return parent !== undefined && (parent.status === 'done' || parent.status === 'archived');
+    });
+}
+/** B6：从状态文件恢复 lastSeq；无文件时回退到事件日志尾行（不重放旧事件重复唤醒 V）。 */
+function loadLastSeq(stateFile) {
+    try {
+        const raw = JSON.parse(readFileSync(stateFile, 'utf8'));
+        return typeof raw.lastSeq === 'number' ? raw.lastSeq : null;
+    }
+    catch {
+        return null;
+    }
+}
+function saveLastSeq(stateFile, lastSeq) {
+    try {
+        writeFileSync(stateFile, JSON.stringify({ lastSeq }));
+    }
+    catch { /* 忽略写失败：事件日志仍是事实源 */ }
+}
+/** 修复轮 6：把 [dsh-swarm] 关键事件追加到 storageDir/dispatcher.log，便于无控制台时观测调度器状态。 */
+function logToFile(file, msg) {
+    try {
+        writeFileSync(file, new Date().toISOString() + ' ' + msg + '\n', { flag: 'a' });
+    }
+    catch { /* 忽略写失败 */ }
+}
+/** 修复轮 6：单次异步操作加超时护栏——一个挂起的 V 编排会话不得卡死整个调度器 tick。 */
+function withTimeout(p, ms, label) {
+    return Promise.race([
+        p,
+        new Promise((_, reject) => setTimeout(() => reject(new Error('timeout: ' + label)), ms)),
+    ]);
+}
+/** 调度器：事件唤醒 V（R20 逐阶段建卡）+ 每任务一次性角色 agent + 心跳看门狗。
+ *  - B1：failed 且 attempts<maxRetries 的任务重派（claim→running，AgentRunner resume 同一会话）；
+ *        attempts≥maxRetries 熔断 blocked(gave_up)。
+ *  - B6：lastSeq 持久化，重启后仅唤醒 lastSeq 之后的事件。
+ *  - R5：inFlight 互斥，防止慢 tick 与下一轮并发重复派发同一任务。 */
+export class Dispatcher {
+    kanban;
+    runner;
+    waker;
+    watchdog;
+    maxRetries;
+    stateFile;
+    logFile;
+    lastSeq = null; // null=尚未加载（首轮 tick 从状态文件/事件日志尾行恢复）
+    inFlight = false;
+    timer = null;
+    constructor(deps) {
+        this.kanban = deps.kanban;
+        this.runner = deps.runner;
+        this.waker = deps.waker;
+        this.watchdog = deps.watchdog;
+        this.maxRetries = deps.maxRetries;
+        this.stateFile = deps.stateFile;
+        this.logFile = deps.logFile;
+    }
+    async ensureLastSeq(state) {
+        if (this.lastSeq !== null)
+            return;
+        // 修复轮 6：无状态文件（首次启动）时从 -1 起处理全部事件，避免跳过已存在的
+        // chain/created / spec-card/approved 等可唤醒事件导致 V 永不建卡（B6 回归）。
+        // 重放安全：VOrchestrator.wakeV 的 B6 幂等（已有匹配卡则跳过）保证不重复建卡。
+        this.lastSeq = loadLastSeq(this.stateFile) ?? -1;
+        logToFile(this.logFile, '[tick] initial lastSeq=' + this.lastSeq);
+    }
+    async tick() {
+        if (this.inFlight)
+            return; // R5：防重叠 tick 并发派发同一任务
+        this.inFlight = true;
+        try {
+            const state = await this.kanban.snapshot();
+            await this.ensureLastSeq(state);
+            let advanced = false;
+            for (const ev of state.events) {
+                if (ev.seq > this.lastSeq) {
+                    this.lastSeq = ev.seq;
+                    advanced = true;
+                    try {
+                        await withTimeout(this.waker.onEvent(ev), 60_000, 'wakeV ev=' + ev.seq + ' chain=' + ev.chainId);
+                    }
+                    catch (err) {
+                        logToFile(this.logFile, '[tick] wakeV failed ev=' + ev.seq + ' chain=' + ev.chainId + ': ' + String(err));
+                    }
+                }
+            }
+            if (advanced)
+                saveLastSeq(this.stateFile, this.lastSeq);
+            for (const t of state.tasks.values()) {
+                if (!parentsDone(t, state))
+                    continue;
+                if (t.status === 'ready' || t.status === 'todo') {
+                    await this.runner.runTask(t.id);
+                }
+                else if (t.status === 'failed' && t.attempts < this.maxRetries) {
+                    // B1：failed 重派——AgentRunner 内 claim→running + resume 同一会话
+                    await this.runner.runTask(t.id);
+                }
+                else if (t.status === 'failed') {
+                    // B1：attempts≥maxRetries 熔断 blocked(gave_up)，人工介入
+                    await this.kanban.blockTask(t.id, 'gave_up: max retries', 'system');
+                }
+            }
+            await this.watchdog.tick();
+        }
+        catch (e) {
+            console.error('[dsh-swarm][debug] tick error: ' + String(e));
+            logToFile(this.logFile, '[tick] error: ' + String(e));
+        }
+        finally {
+            this.inFlight = false;
+        }
+    }
+    start(intervalMs) {
+        this.stop();
+        this.timer = setInterval(() => { void this.tick(); }, intervalMs);
+    }
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+}
+/** 调度层装配：事件唤醒 V（R20 逐阶段建卡）+ 每任务一次性角色 agent + 心跳看门狗。
+ *  仅在 agents 与 kanban 服务同时可用时由插件入口调用（不依赖可能已错过的 ready 事件）。 */
+export function startDispatcher(ctx, config) {
+    const storageDir = config.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');
+    logToFile(logFile, '[startDispatcher] invoked provider=' + Boolean(provider) + ' agents=' + Boolean(agents));
+    if (!provider || !agents) {
+        logToFile(logFile, '[startDispatcher] SKIPPED: agents or kanban provider missing');
+        return;
+    }
+    try {
+        startDispatcherInner(ctx, config, 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) {
+    const kanban = provider.service;
+    const wiki = new WikiVaultClient(config.wikiVault);
+    const defaultModel = resolveDefaultModel(ctx);
+    console.info('[dsh-swarm] role default model = ' + (defaultModel ? defaultModel.provider + '/' + defaultModel.model : 'none'));
+    const orchFile = join(storageDir, 'orchestration.json');
+    const orchestrations = new Map();
+    try {
+        const raw = JSON.parse(readFileSync(orchFile, 'utf8'));
+        for (const [k, v] of raw)
+            orchestrations.set(k, v);
+    }
+    catch { /* 首次启动无文件 */ }
+    const saveOrchs = () => {
+        try {
+            writeFileSync(orchFile, JSON.stringify([...orchestrations.entries()], null, 2));
+        }
+        catch { /* 忽略写失败 */ }
+    };
+    const vOrch = new VOrchestrator(ctx, kanban, agents, config, orchestrations, wiki, defaultModel);
+    // D23：链完成验收核对（重）——Chain(completed) 时核对主会话是否越权写工作区产物；
+    // 发现越权 → chain/audit-warning，阻塞最终汇报直至用户 GUI 确认（chain/audit-confirmed）。
+    const auditor = new ChainAuditor({
+        kanban,
+        workspacesRoot: join(storageDir, 'workspaces'),
+        listLiveAgents: () => (ctx.get('agents')?.list?.() ?? []),
+    });
+    kanban.setOnChainCompleted(async (chainId) => {
+        // 修复轮 7：传入本链发起工作区（Chain.workspaceDir），审计仅扫描该工作区内的会话，排除其他项目主会话
+        const chainState = await kanban.snapshot();
+        const workspaceDir = chainState.chains.get(chainId)?.workspaceDir ?? null;
+        const evidence = await auditor.check(chainId, workspaceDir);
+        if (evidence.length > 0) {
+            console.warn('[dsh-swarm] chain audit warning: ' + chainId + ' evidence=' + evidence.length);
+            await kanban.auditWarning(chainId, evidence, 'system');
+        }
+        // 合入门控（architecture-review 建议1）：DT 通过后由 system 合入 TARGET_BRANCH；D 不再提前 merge/push。
+        // 解析失败软跳过（[merge-skip]），合入失败记录 [merge-failed]，均不阻断收尾（坏代码未被合入 = 方向安全）。
+        try {
+            const r = await mergeDAfterReview(kanban, chainId, storageDir);
+            if (r !== 'skipped')
+                logToFile(logFile, '[merge-gate] chain=' + chainId + ' result=' + r);
+        }
+        catch (err) {
+            console.error('[dsh-swarm][debug] merge gate failed ' + chainId + ': ' + String(err));
+            logToFile(logFile, '[merge-gate] error chain=' + chainId + ' ' + String(err));
+        }
+    });
+    // Q3&5：W2/W3(w:kb) 完成 → 机械互链登记（清单页 ↔ 计划页 ↔ 结果页）。
+    // syncKbLinks 内部对 wiki 读写全容错，失败不阻塞完成；钩子本身再包一层 try（防御未来改动抛错）。
+    kanban.setOnTaskCompleted(async (taskId) => {
+        try {
+            const snap = await kanban.snapshot();
+            await syncKbLinks(wiki, snap, taskId);
+        }
+        catch (err) {
+            console.error('[dsh-swarm][debug] kb linkage failed task=' + taskId + ': ' + String(err));
+        }
+    });
+    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();
+    });
+    // 0.1.0 delegation（spec FR2）：全局子代理写护栏——普通插件 ctx 上注册的 guard 全局
+    // 生效（dsh-tools：普通上下文守卫全局生效，agent.ctx 守卫仅对该 agent 生效）。
+    // guard 内部仅对 kanban-dt 系会话收紧；DT 父会话自身仍由 agent-runner 的 agent.ctx
+    // guard 双保险。dispose 时注销。
+    const toolsSvc = ctx.get('tools');
+    const unguardSubagents = toolsSvc?.guard?.(buildSubagentTreeGuard());
+    if (unguardSubagents) {
+        ctx.on('dispose', unguardSubagents);
+    }
+    const runner = new AgentRunner(ctx, kanban, config, wiki, defaultModel);
+    provider.runner = runner; // T32 fix：HTTP retry 复用同一执行器（failed→claim→spawn/resume）
+    const watchdog = new Watchdog(kanban, config.dispatcher);
+    const dispatcher = new Dispatcher({
+        kanban,
+        runner,
+        waker,
+        watchdog,
+        maxRetries: config.dispatcher.maxRetries,
+        stateFile: join(dirname(orchFile), 'dispatcher-state.json'), // 与事件日志同目录（B6）
+        logFile,
+    });
+    ctx.on('dispose', () => { dispatcher.stop(); watchdog.stop(); });
+    dispatcher.start(2000);
+    watchdog.start(config.dispatcher.heartbeatIntervalSeconds * 1000);
+    logToFile(logFile, '[startDispatcher] dispatcher started (tick=2000ms)');
+    void dispatcher.tick();
+}

package/lib/dispatcher/event-waker.d.ts

@@ -0,0 +1,13 @@
+import type { KanbanEvent } from '../domain/types.js';
+import type { KanbanConfig } from '../config.js';
+type WakeImpl = (chainId: string) => Promise<void>;
+/** 监听 kanban 事件并唤醒 V 编排会话（去重：同一链路在途只唤醒一次）。 */
+export declare class EventWaker {
+    private inFlight;
+    private wakeImpl;
+    constructor(_ctx: unknown, _config: KanbanConfig);
+    /** 注入真实唤醒实现（T11.5：VOrchestrator.wakeV——创建/恢复 V 编排 agent 会话，按 R20 阶段序列建卡）。 */
+    setWakeImpl(impl: WakeImpl): void;
+    onEvent(ev: KanbanEvent): Promise<void>;
+}
+export {};

package/lib/dispatcher/event-waker.js

@@ -0,0 +1,24 @@
+/** 监听 kanban 事件并唤醒 V 编排会话（去重：同一链路在途只唤醒一次）。 */
+export class EventWaker {
+    inFlight = new Set();
+    wakeImpl = async () => { };
+    constructor(_ctx, _config) { }
+    /** 注入真实唤醒实现（T11.5：VOrchestrator.wakeV——创建/恢复 V 编排 agent 会话，按 R20 阶段序列建卡）。 */
+    setWakeImpl(impl) { this.wakeImpl = impl; }
+    async onEvent(ev) {
+        // v2：V 仅在规格卡批准后（spec-card/approved）或任务完成/阻塞（驱动阶段推进）时唤醒；
+        // chain/created 不再唤醒 V（V 不再处理旧 w1 预取阶段，等 /openspec: 建卡 + 批准后再行动）。
+        const wakeable = (ev.kind === 'task/completed' || ev.kind === 'task/blocked' || ev.kind === 'spec-card/approved');
+        if (!wakeable)
+            return;
+        if (this.inFlight.has(ev.chainId))
+            return;
+        this.inFlight.add(ev.chainId);
+        try {
+            await this.wakeImpl(ev.chainId);
+        }
+        finally {
+            this.inFlight.delete(ev.chainId);
+        }
+    }
+}

package/lib/dispatcher/git-credentials.d.ts

@@ -0,0 +1,33 @@
+/**
+ * R20 D(execute) git 凭据注入（M4）：使 D 会话的 git ls-remote/push 可用。
+ *
+ * 机制：D 会话的 bash 每次调用都是新 shell（无环境持久），故 env 变量不可跨调用。
+ * 采用 repo-local http extraheader（AUTHORIZATION: basic），写入 <repo>/.git/config——
+ * 持久跨 bash 调用、由插件进程（web app 侧，不受 D 会话沙箱限制）注入。
+ *
+ * 鉴权按托管方区分：
+ * - GitLab PAT（glpat- 前缀）→ basic base64("oauth2:<PAT>")（GitLab 规范，实测 ls-remote 通过）；
+ * - 其余（GitHub 等）→ basic base64("x-access-token:<PAT>")。
+ * D 会话为 danger-full-access（用户决策 Q4），HOME 可写，故 git 的 credential.helper
+ * （store/osxkeychain 等）不再触发 "credential storage lock"，无需中和。
+ *
+ * PAT 来源（按优先级）：DSH 凭据服务 ctx.credentials（$DSH_HOME/.credentials.yaml 的
+ * KANBAN_GIT_PAT/GIT_PAT）→ 进程 env（KANBAN_GIT_PAT > GIT_PAT > GH_TOKEN > GITHUB_TOKEN）。
+ * 未配置 PAT 时不注入（回退用户已有 git 凭据/SSH）。
+ */
+/** D 会话可用 git PAT 的 env 变量名（按优先级）。 */
+export declare const GIT_PAT_ENV_NAMES: readonly ["KANBAN_GIT_PAT", "GIT_PAT", "GH_TOKEN", "GITHUB_TOKEN"];
+/** 从进程 env 解析非空 PAT；无则返回 null。 */
+export declare function resolveGitPat(env: NodeJS.ProcessEnv): string | null;
+/** 经 DSH 凭据服务解析 PAT（$DSH_HOME/.credentials.yaml / env / .env，见 dsh-credentials-local 分层）；无则回退进程 env。 */
+export declare function resolveGitPatFromCtx(ctx: unknown, env: NodeJS.ProcessEnv): Promise<string | null>;
+/** PAT → http extraheader 值：GitLab(glpat-*) 用 oauth2 前缀，其余 x-access-token。 */
+export declare function gitAuthHeader(pat: string): string;
+/**
+ * 注入 repo-local http extraheader。返回 { ok, detail }（失败不抛——注入失败仅告警，
+ * D 仍可执行；用户自带凭据/SSH 的仓库不受影响）。
+ */
+export declare function injectGitCredentials(repoDir: string, pat: string): {
+    ok: boolean;
+    detail: string;
+};