@joekytc/dsh-swarm 0.1.2 → 0.3.0

package/lib/domain/config-override.js

@@ -0,0 +1,138 @@
+export const ROLES = ['v', 'p', 'w', 'd', 'pt', 'dt'];
+const MODEL_FIELDS = ['provider', 'model', 'reasoningEffort'];
+export function mergeConfig(baseline, override) {
+    const wiki = { ...baseline.wikiVault };
+    if (override?.wikiVault?.baseUrl !== undefined)
+        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];
+        const over = override?.roles?.models?.[role];
+        if (!over)
+            continue;
+        const cur = { ...base };
+        if (over.provider !== undefined)
+            cur.provider = over.provider;
+        if (over.model !== undefined)
+            cur.model = over.model;
+        // 防御：空字符串 reasoningEffort 视为"未设置"，永不覆盖 baseline/默认（读点回退 'high'）。
+        if (over.reasoningEffort !== undefined && over.reasoningEffort.trim() !== '')
+            cur.reasoningEffort = over.reasoningEffort;
+        if (cur.provider && cur.model)
+            models[role] = cur;
+    }
+    return { ...baseline, wikiVault: wiki, roles: { ...baseline.roles, models }, reviewEngine };
+}
+export function computeSources(override) {
+    const src = {};
+    for (const k of ['wikiVault.baseUrl', 'wikiVault.pagePrefix']) {
+        const hit = k === 'wikiVault.baseUrl' ? override?.wikiVault?.baseUrl !== undefined : override?.wikiVault?.pagePrefix !== undefined;
+        src[k] = hit ? 'override' : 'inherited';
+    }
+    for (const role of ROLES) {
+        for (const f of MODEL_FIELDS) {
+            const hit = override?.roles?.models?.[role]?.[f] !== undefined;
+            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) {
+    const models = {};
+    for (const role of ROLES) {
+        const m = effective.roles.models?.[role];
+        if (m?.provider && m?.model)
+            models[role] = { provider: m.provider, model: m.model, reasoningEffort: m.reasoningEffort ?? 'high' };
+    }
+    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) {
+    const errs = [];
+    const baseUrl = snapshot.wikiVault.baseUrl ?? '';
+    // 空 baseUrl = 本地 llm-wiki 回退（合法）；仅非空时校验 ^https?://。
+    if (baseUrl.trim() && !/^https?:\/\//.test(baseUrl))
+        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)
+            continue;
+        if (!m.provider?.trim())
+            errs.push(`roles.models.${role}.provider`);
+        if (!m.model?.trim())
+            errs.push(`roles.models.${role}.model`);
+    }
+    return errs;
+}
+export function diffOverride(baseline, snapshot) {
+    const out = {};
+    const w = {};
+    if (snapshot.wikiVault.baseUrl !== baseline.wikiVault.baseUrl)
+        w.baseUrl = snapshot.wikiVault.baseUrl;
+    if (snapshot.wikiVault.pagePrefix !== baseline.wikiVault.pagePrefix)
+        w.pagePrefix = snapshot.wikiVault.pagePrefix;
+    if (Object.keys(w).length)
+        out.wikiVault = w;
+    const models = {};
+    for (const role of ROLES) {
+        const snap = snapshot.roles.models[role];
+        const base = baseline.roles.models?.[role];
+        const cur = {};
+        if (snap && snap.provider !== base?.provider)
+            cur.provider = snap.provider;
+        if (snap && snap.model !== base?.model)
+            cur.model = snap.model;
+        // 空/空白 reasoningEffort 视为"跟随默认"：不写入 override，effective 保持 baseline/默认。
+        const snapEffort = snap?.reasoningEffort?.trim() ? snap.reasoningEffort : undefined;
+        if (snapEffort !== undefined && snapEffort !== (base?.reasoningEffort ?? 'high'))
+            cur.reasoningEffort = snapEffort;
+        if (Object.keys(cur).length)
+            models[role] = cur;
+    }
+    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 建下游卡前的前置校验）。 */
@@ -14,5 +14,6 @@ export interface MissingParentDelivery {
     mode: TaskMode;
     missing: string[];
 }
-/** 对一组父任务 id 做交付契约校验，返回缺关键交付物的父卡清单（无缺失返回空数组）。 */
-export declare function missingParentDelivery(state: BoardState, parentIds: string[]): MissingParentDelivery[];
+/** 对一组父任务 id 做交付契约校验，返回缺关键交付物的父卡清单（无缺失返回空数组）。
+ *  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 } from '../wiki/page-path.js';
+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,24 +40,35 @@ export function missingDeliveryKeys(assignee, mode, handoff, kbUrlBase) {
     if (!handoff)
         return keys.slice();
     const m = handoff.metadata ?? {};
-    const base = kbUrlBase ? kbUrlBase.replace(/\/$/, '') : null;
+    // 推导修正：kbUrlBase === undefined 才是宽松；'' 是 local strict
+    const hasBase = kbUrlBase !== undefined;
+    const base = hasBase ? kbUrlBase.replace(/\/$/, '') : null;
     const strict = base !== null;
     const missing = [];
     for (const k of keys) {
         if (k === 'pt_decision') {
             missing.push(...missingPtDecisionKeys(handoff));
+            continue;
+        }
+        const v = m[k];
+        if (strict && k === 'kb_url' && base === '') {
+            // local 模式：kb_url 必须显式空串（非缺失键）
+            if (typeof v !== 'string' || v.trim() !== '')
+                missing.push(`${k} (本地模式 kb_url 必须为空串)`);
+            continue;
+        }
+        if (typeof v !== 'string' || v.trim().length === 0) {
+            missing.push(k);
+        }
+        else if (strict && k === 'kb_url' && !v.startsWith(base)) {
+            missing.push(`${k} (host 前缀必须为 ${base})`);
+        }
+        else if (strict && k === 'page_path' && base === '') {
+            if (!isLocalKbPagePath(v))
+                missing.push(`${k} (本地模式必须为本地库 wiki/** 相对路径)`);
         }
-        else {
-            const v = m[k];
-            if (typeof v !== 'string' || v.trim().length === 0) {
-                missing.push(k);
-            }
-            else if (strict && k === 'kb_url' && !v.startsWith(base)) {
-                missing.push(`${k} (host 前缀必须为 ${base})`);
-            }
-            else if (strict && k === 'page_path' && !isAllowedWikiPagePath(v)) {
-                missing.push(`${k} (必须为 projects/checklists/、projects/learnings/、projects/<slug>/learnings/、projects/ch_*/learnings/、projects/ch_*/t_*.md 或 projects/ch_*/review/ 命名空间)`);
-            }
+        else if (strict && k === 'page_path' && !isAllowedWikiPagePath(v)) {
+            missing.push(`${k} (必须为 ${KB_PAGE_NAMESPACES_HINT} 命名空间)`);
         }
     }
     return missing;
@@ -65,14 +76,15 @@ export function missingDeliveryKeys(assignee, mode, handoff, kbUrlBase) {
 export function hasRequiredDelivery(assignee, mode, handoff) {
     return missingDeliveryKeys(assignee, mode, handoff).length === 0;
 }
-/** 对一组父任务 id 做交付契约校验，返回缺关键交付物的父卡清单（无缺失返回空数组）。 */
-export function missingParentDelivery(state, parentIds) {
+/** 对一组父任务 id 做交付契约校验，返回缺关键交付物的父卡清单（无缺失返回空数组）。
+ *  kbUrlBase 可选透传 missingDeliveryKeys（与上方 kbUrlBase 推导修正配套——local 模式传 '' 走 strict local 分支）。 */
+export function missingParentDelivery(state, parentIds, kbUrlBase) {
     const out = [];
     for (const pid of parentIds) {
         const pt = state.tasks.get(pid);
         if (!pt)
             continue;
-        const missing = missingDeliveryKeys(pt.assignee, pt.mode, state.handoffs.get(pid));
+        const missing = missingDeliveryKeys(pt.assignee, pt.mode, state.handoffs.get(pid), kbUrlBase);
         if (missing.length > 0)
             out.push({ taskId: pid, assignee: pt.assignee, mode: pt.mode, missing });
     }

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/gate-policy.d.ts

@@ -0,0 +1,26 @@
+export interface GateCommand {
+    command: string;
+    cwd: string;
+    source: 'tdd';
+}
+export interface GatePlan {
+    commands: GateCommand[];
+    skipped: false;
+}
+export interface GateSkip {
+    commands: [];
+    skipped: true;
+    reason: string;
+}
+export declare function isGatePlan(x: GatePlan | GateSkip): x is GatePlan;
+export declare function branchMatches(current: string | null, declared: unknown): boolean;
+export declare function deriveGatePlan(input: {
+    assignee: string;
+    mode: string;
+    handoff: {
+        metadata?: Record<string, unknown>;
+    };
+    config: {
+        enabled: boolean;
+    };
+}): GatePlan | GateSkip;

package/lib/domain/gate-policy.js

@@ -0,0 +1,44 @@
+// src/domain/gate-policy.ts
+/** kanban_complete 实测闸派生（纯函数，零 IO）：
+ * 声明来源单层——tdd.test_files 自动派生 npx --no-install vitest run（runner=vitest 为 review-evidence 既有口径）。
+ * cwd 一律 metadata.worktree_dir，缺失即 skip（旧卡向后兼容零感知）。
+ * test_files 必须相对路径且规范化后无 .. 段（防绝对路径跑主仓库/越界逃逸——跑错代码即闸被绕过），违规整单 skip。
+ * branchMatches 供装配层在 git 查询后做分支一致性比对（current=null 视为不匹配，调用方 skip）。 */
+import { isAbsolute } from 'node:path';
+export function isGatePlan(x) {
+    return x.skipped === false;
+}
+export function branchMatches(current, declared) {
+    return typeof declared === 'string' && declared.trim().length > 0 && current === declared;
+}
+/** 相对路径 + 不得含 .. 段（含 a/../b 形式，一并拒绝，从简从严）。
+ * 另限字符 allowlist [A-Za-z0-9._/-]：test_files 会被拼入 `bash -c` 执行（见 gate-runner），
+ * 白名单一并拒绝空白与 ; | & $ ` () 等元字符——既防 shell 注入（如 'x || true' 拼成
+ * `vitest run x || true`，未跑闸却 exit 0 通过），也防借空白等变体绕 runner 黑名单子串匹配
+ * （如 'a;git  push' 双空格躲过 includes('git push')）。 */
+const isSafeRelativeTestFile = (f) => /^[A-Za-z0-9._/-]+$/.test(f) && !isAbsolute(f) && !f.split(/[/\\]/).includes('..')
+    && !f.startsWith('-'); // 拒绝以 - 开头的条目：防 vitest CLI 旗标注入（如 --passWithNoTests 使 0 tests matched 也 exit 0，空跑绕闸）
+export function deriveGatePlan(input) {
+    const m = input.handoff.metadata ?? {};
+    if (!input.config.enabled)
+        return { commands: [], skipped: true, reason: 'gates disabled' };
+    if (!(input.assignee === 'd' && input.mode === 'execute'))
+        return { commands: [], skipped: true, reason: 'not d/execute' };
+    const wt = m['worktree_dir'];
+    if (typeof wt !== 'string' || !wt.trim())
+        return { commands: [], skipped: true, reason: 'worktree_dir missing (legacy card)' };
+    const tdd = m['tdd'];
+    if (tdd?.skipped)
+        return { commands: [], skipped: true, reason: 'tdd skipped by declaration' };
+    if (!Array.isArray(tdd?.test_files) || tdd.test_files.length === 0)
+        return { commands: [], skipped: true, reason: 'no gate commands' };
+    const files = tdd.test_files.filter((f) => typeof f === 'string' && f.trim().length > 0);
+    if (files.length === 0)
+        return { commands: [], skipped: true, reason: 'no gate commands' };
+    if (!files.every(isSafeRelativeTestFile))
+        return { commands: [], skipped: true, reason: 'invalid test_files path (relative in-worktree required)' };
+    return {
+        commands: [{ command: `npx --no-install vitest run ${files.join(' ')}`, cwd: wt, source: 'tdd' }],
+        skipped: false,
+    };
+}

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;

package/lib/domain/im-message.js

@@ -0,0 +1,149 @@
+import { hasDeliveryEvidence } from './delivery-evidence.js';
+/** W3 收尾判据（镜像 kanban-service.completeTask 机械规则，但不含 dEvidenceOk 与链状态要求）：
+ *  完成卡为 w+kb、链上无未终态卡、它是最后完成的卡、且链上存在 done 的 D 卡（防 W2 中间态误投）。 */
+export function isFinalW3Completion(state, chainId, completedTaskId) {
+    const task = state.tasks.get(completedTaskId);
+    if (!task || task.chainId !== chainId || task.assignee !== 'w' || task.mode !== 'kb')
+        return false;
+    const chainTasks = [...state.tasks.values()].filter((t) => t.chainId === chainId);
+    if (chainTasks.some((t) => t.status !== 'done' && t.status !== 'archived'))
+        return false;
+    const completedEvents = state.events.filter((e) => e.chainId === chainId && e.kind === 'task/completed' && e.taskId);
+    if (completedEvents.at(-1)?.taskId !== completedTaskId)
+        return false;
+    return chainTasks.some((t) => (t.mode === 'execute' || t.mode === 'align') && t.status === 'done');
+}
+function fmtTime(ms) {
+    const d = new Date(ms);
+    const p = (n) => String(n).padStart(2, '0');
+    return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}`;
+}
+function strMeta(handoff, key) {
+    const v = (handoff?.metadata ?? {})[key];
+    return typeof v === 'string' ? v.trim() : '';
+}
+/** 人工关注点：TDD 跳过声明、D 证据缺失（链完成门禁拦截）、审计警告状态。 */
+function completionAttention(state, chainId, dHandoff) {
+    const out = [];
+    const tdd = (dHandoff?.metadata ?? {})['tdd'];
+    const skipReason = tdd?.skipped && typeof tdd.skipped['reason'] === 'string' ? tdd.skipped['reason'].trim() : '';
+    if (skipReason)
+        out.push(`TDD 曾跳过：${skipReason}`);
+    if (!hasDeliveryEvidence(dHandoff))
+        out.push('D 卡缺 git 产物证据，链未自动收链，请人工核对');
+    const audit = state.auditWarnings.get(chainId);
+    if (audit && !audit.confirmedAt)
+        out.push(`审计警告待 GUI 确认（${audit.evidence.length} 条证据）`);
+    else if (audit?.confirmedAt)
+        out.push(`审计警告已于 ${fmtTime(audit.confirmedAt)} 确认`);
+    return out;
+}
+/** 成功汇报（markdown）。判据不满足（W2 中间态/非 w:kb/非收尾）返回 null。 */
+export function buildCompletionMessage(state, chainId, completedTaskId, now) {
+    if (!isFinalW3Completion(state, chainId, completedTaskId))
+        return null;
+    const chain = state.chains.get(chainId);
+    if (!chain)
+        return null;
+    const chainTasks = [...state.tasks.values()].filter((t) => t.chainId === chainId);
+    const wHandoff = state.handoffs.get(completedTaskId);
+    const dTask = chainTasks.find((t) => (t.mode === 'execute' || t.mode === 'align') && t.status === 'done');
+    const dHandoff = state.handoffs.get(dTask.id);
+    const pTask = [...chainTasks].reverse().find((t) => t.assignee === 'p' && t.status === 'done');
+    const artifacts = strMeta(pTask ? state.handoffs.get(pTask.id) : undefined, 'artifacts_path');
+    const lines = [];
+    lines.push(`**【DSH 需求完成】${chain.title}**`);
+    lines.push('');
+    lines.push(`**完成清单**（${fmtTime(now)}）`);
+    for (const t of chainTasks)
+        lines.push(`- ✅ ${t.title}`);
+    lines.push('');
+    lines.push('**产出**');
+    const kbUrl = strMeta(wHandoff, 'kb_url');
+    const pagePath = strMeta(wHandoff, 'page_path');
+    if (kbUrl)
+        lines.push(`- KB 文档：${kbUrl}`);
+    if (pagePath)
+        lines.push(`- KB 页：${pagePath}`);
+    lines.push(`- 产出物：${artifacts || '（无）'}`);
+    const attention = completionAttention(state, chainId, dHandoff);
+    if (attention.length > 0) {
+        lines.push('');
+        lines.push('**人工关注点**');
+        for (const a of attention)
+            lines.push(`- ${a}`);
+    }
+    return lines.join('\n');
+}
+/** 阻塞建议映射表（静态工程知识，禁止模型现场生成——评审决议）。 */
+const SUGGESTION_TABLE = [
+    {
+        pattern: /\[create-failed\]/,
+        lines: [
+            'V 连续多轮建卡失败：查 dispatcher.log 的 [wakeV] / [tick] error 行，确认编排会话报错原因',
+            '核对 roles.models.v 模型路由配置；历史案例：网关回复缓存回放（from-cache）会致零工具调用，可更换 provider/model 后重试',
+        ],
+    },
+    {
+        pattern: /\[stall-watchdog\]/,
+        lines: [
+            '链持续无进展且重唤醒耗尽：查 dispatcher.log [stall-watchdog] 行与 orchestration.json 的 phase/stallCount',
+            '检查最后一张卡会话（kbn-<taskId>）session.jsonl 是否空壳（仅 4 行骨架）——空壳需人工清理后删链重跑',
+        ],
+    },
+];
+export function suggestionsFor(reason) {
+    const out = [];
+    for (const row of SUGGESTION_TABLE) {
+        if (row.pattern.test(reason))
+            out.push(...row.lines);
+    }
+    if (out.length === 0) {
+        out.push('查 events.jsonl 最近事件定位阻塞前最后一个动作');
+        out.push('GUI 打开该链逐卡核对状态；人工恢复 = 删链重跑');
+    }
+    return out;
+}
+/** 链下全部 blocked 卡（title + 最近一次 task/blocked 原因）。 */
+export function latestBlockedTasks(events, tasks, chainId) {
+    const reasons = new Map();
+    for (const e of events) {
+        if (e.chainId !== chainId || e.kind !== 'task/blocked' || !e.taskId)
+            continue;
+        reasons.set(e.taskId, String(e.payload['reason'] ?? ''));
+    }
+    const out = [];
+    for (const t of tasks) {
+        if (t.chainId !== chainId || t.status !== 'blocked')
+            continue;
+        out.push({ id: t.id, title: t.title, reason: reasons.get(t.id) ?? '（原因见事件流）' });
+    }
+    return out;
+}
+/** 阻塞通知（markdown）。 */
+export function buildBlockMessage(state, chainId, chainReason, storageDir) {
+    const chain = state.chains.get(chainId);
+    const blocked = latestBlockedTasks(state.events, state.tasks.values(), chainId);
+    const lines = [];
+    lines.push(`**【DSH 需求阻塞】${chain?.title ?? chainId}**`);
+    lines.push('');
+    lines.push('**阻塞卡**');
+    if (blocked.length === 0)
+        lines.push('- 无（链级停滞，见阻塞原因）');
+    else
+        for (const b of blocked)
+            lines.push(`- ${b.title}：${b.reason}`);
+    lines.push('');
+    lines.push('**阻塞原因**');
+    lines.push(`> ${chainReason}`);
+    lines.push('');
+    lines.push('**排查建议**');
+    for (const s of suggestionsFor(chainReason))
+        lines.push(`- ${s}`);
+    lines.push('');
+    lines.push('**取证路径**');
+    lines.push(`- 事件：${storageDir}/events.jsonl`);
+    lines.push(`- 编排：${storageDir}/orchestration.json`);
+    lines.push(`- 调度：${storageDir}/dispatcher.log`);
+    return lines.join('\n');
+}

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

@@ -2,7 +2,7 @@ import type { EventStore } from './event-store.js';
 import { type Actor } from './permissions.js';
 import type { AuditEvidence, BoardState, Chain, Handoff, KanbanEvent, SpecCard, SpecCardAttachment, SpecCardSections, Task, TaskMode, Role, ReviewEvidence } from './types.js';
 export type KanbanListener = (event: KanbanEvent) => void;
-/** 首句：trim 后按首个换行或「。？！ 」截断；超长兜底 40 字（T7 需求标题规范化）。 */
+/** 首句：trim 后按首个换行或「。？！ 」截断；超长兜底 40 字（需求标题规范化）。 */
 export declare function firstSentence(text: string): string;
 /** 默认链标题：【需求】<一句话需求描述>。来源优先级 /plan: rest 首句 → checklist.problem 首句 → 未命名需求。 */
 export declare function buildChainTitle(requirementName: string | null, _openspecRest: string, problem: string): string;
@@ -10,20 +10,26 @@ export declare function buildChainTitle(requirementName: string | null, _openspe
 export declare class KanbanService {
     private state;
     private readonly store;
-    private readonly kbUrlBase;
+    private readonly getKbUrlBase;
     private emitQueue;
     private readonly listeners;
     private onChainCompletedHook;
     private onTaskCompletedHook;
-    constructor(store: EventStore, kbUrlBase?: string);
+    private gateHook;
+    constructor(store: EventStore, getKbUrlBase?: () => string | undefined);
     private emit;
-    /** D23：注入链完成核对钩子（由调度层设置；仅一个消费者）。 */
+    /** 注入链完成核对钩子（由调度层设置；仅一个消费者）。 */
     setOnChainCompleted(hook: (chainId: string) => void | Promise<void>): void;
-    /** Q3&5：注入任务完成互链登记钩子（由调度层设置；仅一个消费者）。 */
+    /** 注入任务完成互链登记钩子（由调度层设置；仅一个消费者）。 */
     setOnTaskCompleted(hook: (taskId: string) => void | Promise<void>): void;
-    /** T22：订阅持久化后的看板事件；返回解除订阅函数。listener 异常不影响已落盘状态。 */
+    /** 注入实测闸钩子（由装配层设置；null=关闭实测闸，行为与旧版逐字节一致）。 */
+    setGateHook(hook: ((task: Task, handoff: Handoff) => Promise<{
+        ok: boolean;
+        detail: string;
+    } | null>) | null): void;
+    /** 订阅持久化后的看板事件；返回解除订阅函数。listener 异常不影响已落盘状态。 */
     subscribe(listener: KanbanListener): () => void;
-    /** T22：返回 seq >= 入参 的事件（与 EventStore.readSince 同为 inclusive 语义）。 */
+    /** 返回 seq >= 入参 的事件（与 EventStore.readSince 同为 inclusive 语义）。 */
     eventsSince(seq: number): Promise<KanbanEvent[]>;
     private publish;
     private chainOf;
@@ -36,6 +42,12 @@ export declare class KanbanService {
     createSpecCard(chainId: string, sections: SpecCardSections, actor: Actor): Promise<SpecCard>;
     editSpecCard(cardId: string, sections: SpecCardSections, actor: Actor): Promise<SpecCard>;
     approveSpecCard(cardId: string, actor: Actor): Promise<SpecCard>;
+    /** 链级停滞终态（防线A，看门狗/V stall 超限专用机械记账）：executing → blocked。
+     *  非 executing 调用即抛（fail-closed）；人工恢复=GUI 删链重跑（blocked 无出边）。 */
+    blockChain(chainId: string, reason: string): Promise<void>;
+    /** IM 投递失败留痕（仅 system 机械记账）：非状态转换注记事件，仅落盘供取证/GUI 观察。
+     *  投递是旁路通知，失败绝不 block 链（评审决议）；留痕满足「禁止静默 skip」红线。 */
+    noteImDeliveryFailed(chainId: string, detail: string, actor: Actor): Promise<KanbanEvent>;
     createTask(input: {
         chainId: string;
         title: string;
@@ -49,11 +61,11 @@ export declare class KanbanService {
     completeTask(taskId: string, handoff: Handoff, actor: Actor, opts?: {
         boundTaskId?: string;
     }): Promise<Task>;
-    /** D23：链完成验收核对发警告（仅 system/dispatcher 可发）。Chain 状态保持 completed。 */
+    /** 链完成验收核对发警告（仅 system/dispatcher 可发）。Chain 状态保持 completed。 */
     auditWarning(chainId: string, evidence: AuditEvidence[], actor: Actor): Promise<KanbanEvent>;
-    /** D23：用户确认产物归属（仅 human，GUI confirm-audit action）。放行最终汇报。 */
+    /** 用户确认产物归属（仅 human，GUI confirm-audit action）。放行最终汇报。 */
     confirmAudit(chainId: string, actor: Actor): Promise<KanbanEvent>;
-    /** T7：链标题改名（仅 human，GUI）。发 chain/title-updated 事件（非状态转换）。 */
+    /** 链标题改名（仅 human，GUI）。发 chain/title-updated 事件（非状态转换）。 */
     updateChainTitle(chainId: string, title: string, actor: Actor): Promise<Chain>;
     /** 整链硬删除（含其下全部角色卡/规格卡事件；仅 human，GUI 二次确认）。物理 purge 事件行，不可恢复。 */
     deleteChain(chainId: string, actor: Actor): Promise<void>;
@@ -71,7 +83,7 @@ export declare class KanbanService {
     }): Promise<Task>;
     comment(taskId: string, body: string, actor: Actor): Promise<KanbanEvent>;
     archiveTask(taskId: string, actor: Actor): Promise<Task>;
-    /** T10.5：仅 draft 规格卡可挂附件（V 挂清单附件（/openspec: 建链）/ human GUI 上传）。 */
+    /** 仅 draft 规格卡可挂附件（V 挂清单附件（/openspec: 建链）/ human GUI 上传）。 */
     addSpecCardAttachment(cardId: string, attachment: SpecCardAttachment, actor: Actor): Promise<SpecCard>;
     /** 评审事件（交付质量链）：recordReview 记录评审卡结论并更新被评审任务 reviewStatus。
      *  actor 必须 system（V/角色不可伪造评审结论）；verdict=pass → review/passed，否则 review/failed。
@@ -80,7 +92,11 @@ export declare class KanbanService {
     /** 评审超限放弃：review/gave-up（含证据链信息）。仅 system。 */
     reviewGaveUp(reviewTaskId: string, targetTaskId: string, reason: string, actor: Actor): Promise<KanbanEvent>;
     /** 评审失败返工卡创建（评审失败闭环）：原任务保持 done（不可变），新建返工卡继承 rework 字段。
-     *  仅 system（can('create-rework-task')=system）；V 建执行卡、system 建返工卡。 */
+     *  仅 system（can('create-rework-task')=system）；V 建执行卡、system 建返工卡。
+     *  语义（2026-09-07 修正）：返工=该卡自己的独立会话——resumeSessionId 不继承源卡会话（置 null），
+     *  首跑由 runTask create `kbn-<reworkId>`，卡自身失败重试再 resume 该会话；reworkOfTaskId 保留溯源。
+     *  旧实现继承 source.sessionId 造成三方错位：runTask 首跑不消费它（hasRunHistory=false→create 新会话）、
+     *  UI（BoardCard resumeSessionId??sessionId）却跳到源卡会话 → 「返工在后台跑但哪都找不到它」。 */
     createReworkTask(input: {
         sourceTaskId: string;
         reviewTaskId: string;