@joekytc/dsh-swarm 0.1.1 → 0.2.0

package/lib/roles/wiki-worker.d.ts

@@ -8,6 +8,7 @@ export declare class WikiWorker {
     private readonly cfg;
     constructor(kanban: KanbanService, wiki: WikiVaultClient, cfg: {
         pagePrefix: string;
+        kbMode?: 'remote' | 'local';
     });
     executePrefetch(task: Task, mode: 'file' | 'external' | 'kb', source: string): Promise<{
         ref: string;

package/lib/roles/wiki-worker.js

@@ -1,5 +1,6 @@
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { buildRepoSlug } from '../domain/memory.js';
 function workspaceOf(chainId, taskId) {
     return join(process.env.DSH_HOME ?? process.cwd(), 'storages', 'kanban', 'workspaces', chainId, taskId);
 }
@@ -26,15 +27,22 @@ export class WikiWorker {
                 throw new Error('prefetch source outside workspace: ' + source);
             return { ref: source || ref };
         }
-        // kb 模式：知识库查询产物（wiki-vault search/read 由 wiki 工具执行，agent 落盘 ws/prefetch-kb.md）
+        // kb 模式：知识库查询产物。local 模式（D2）不走 wiki 工具——明确指引改用 skill 加载 llm-wiki。
+        if (this.cfg.kbMode === 'local') {
+            throw new Error('prefetch_kb unavailable in local KB mode: use the skill tool to load llm-wiki for KB search instead');
+        }
+        // remote：知识库查询产物（wiki-vault search/read 由 wiki 工具执行，agent 落盘 ws/prefetch-kb.md）
         const ref = join(ws, 'prefetch-kb.md');
         if (!source.startsWith(ws) && source !== '')
             throw new Error('prefetch source outside workspace: ' + source);
         return { ref: source || ref };
     }
     async syncToWiki(task, sourceRef) {
+        const chain = (await this.kanban.snapshot()).chains.get(task.chainId);
+        if (!chain?.workspaceDir)
+            throw new Error('syncToWiki requires chain.workspaceDir: ' + task.chainId);
         const content = readFileSync(sourceRef, 'utf8'); // 原汁原味：不压缩不蒸馏
-        const pagePath = this.cfg.pagePrefix + task.chainId + '/' + task.id + '.md';
+        const pagePath = `${this.cfg.pagePrefix}${buildRepoSlug(chain.workspaceDir)}/${task.chainId}/${task.id}.md`;
         await this.wiki.write(pagePath, content);
         return { kb_url: this.wikiBase() + '/#/page/' + pagePath, page_path: pagePath };
     }

package/lib/routes/kanban-http.d.ts

@@ -1,6 +1,9 @@
 import type { Context } from '@deepseek-ai/cordis';
 import type { KanbanConfig } from '../config.js';
 import type { KanbanProvider } from '../services/kanban-provider.js';
-/** 看板 HTTP 桥（Web GUI 浏览器半消费）：GET /kanban/board 读快照；POST /kanban/action 执行状态操作。
+import type { ConfigProvider } from '../services/config-provider.js';
+import type { LlmRuntimeLike } from '../services/llm-catalog.js';
+/** 看板 HTTP 桥（Web GUI 浏览器半消费）：GET /kanban/board 读快照；POST /kanban/action 执行状态操作；
+ *  GET/PUT /kanban/config + POST /kanban/config/reset 配置读写；GET /kanban/llm-catalog 模型目录。
  *  仅在 webServer 服务存在时挂载（CLI/headless/测试裸 Context 不挂）。 */
-export declare function registerKanbanHttp(ctx: Context, provider: KanbanProvider, config?: Pick<KanbanConfig, 'ui'>): void;
+export declare function registerKanbanHttp(ctx: Context, provider: KanbanProvider, configProvider: ConfigProvider, llm: LlmRuntimeLike, config?: Pick<KanbanConfig, 'ui'>): void;

package/lib/routes/kanban-http.js

@@ -1,3 +1,4 @@
+import { buildLlmCatalog } from '../services/llm-catalog.js';
 import { serveKanbanEvents } from './kanban-sse.js';
 function json(res, status, body) {
     res.statusCode = status;
@@ -12,9 +13,10 @@ function readBody(req) {
         req.on('error', reject);
     });
 }
-/** 看板 HTTP 桥（Web GUI 浏览器半消费）：GET /kanban/board 读快照；POST /kanban/action 执行状态操作。
+/** 看板 HTTP 桥（Web GUI 浏览器半消费）：GET /kanban/board 读快照；POST /kanban/action 执行状态操作；
+ *  GET/PUT /kanban/config + POST /kanban/config/reset 配置读写；GET /kanban/llm-catalog 模型目录。
  *  仅在 webServer 服务存在时挂载（CLI/headless/测试裸 Context 不挂）。 */
-export function registerKanbanHttp(ctx, provider, config) {
+export function registerKanbanHttp(ctx, provider, configProvider, llm, config) {
     // 可选服务：经 ctx.get 读取（cordis 4 直接属性读取需 inject；get 不需要）
     const webServer = ctx.get('webServer');
     if (!webServer)
@@ -55,7 +57,8 @@ export function registerKanbanHttp(ctx, provider, config) {
                         json(res, 200, { ok: true });
                         return;
                     }
-                    // 整链硬删除（仅 human；GUI 二次确认）：purge 无事件流，客户端需自行 resync
+                    // 整链硬删除（仅 human；GUI 二次确认）：purge 无事件流，客户端需自行 resync。
+                    // E/F：删链后联动 dispatcher（游标同步钳回）+ V 编排 entry 清理，防运行中实例跳过后续新链事件。
                     if (body.type === 'delete') {
                         const chainId = String(body.chainId ?? '').trim();
                         if (!chainId) {
@@ -63,6 +66,8 @@ export function registerKanbanHttp(ctx, provider, config) {
                             return;
                         }
                         await provider.service.deleteChain(chainId, 'human');
+                        if (provider.onChainDeleted)
+                            await provider.onChainDeleted(chainId);
                         json(res, 200, { ok: true });
                         return;
                     }
@@ -149,6 +154,34 @@ export function registerKanbanHttp(ctx, provider, config) {
                     json(res, 200, { ok: true });
                     return;
                 }
+                // 配置读写：reset 是 POST，与 GET/PUT config 经 method 区分（reset 分支前置，防前缀遮蔽）
+                if (req.method === 'POST' && req.url?.startsWith('/kanban/config/reset')) {
+                    json(res, 200, configProvider.reset());
+                    return;
+                }
+                if (req.method === 'GET' && req.url?.startsWith('/kanban/config')) {
+                    json(res, 200, configProvider.snapshot());
+                    return;
+                }
+                if (req.method === 'PUT' && req.url?.startsWith('/kanban/config')) {
+                    const raw = JSON.parse((await readBody(req)) || '{}');
+                    // 归一化缺省字段，保证缺字段走 400 校验失败而非 500
+                    const snapshot = {
+                        wikiVault: { baseUrl: raw.wikiVault?.baseUrl ?? '', pagePrefix: raw.wikiVault?.pagePrefix ?? '' },
+                        roles: { models: raw.roles?.models ?? {} },
+                    };
+                    const r = configProvider.applyOverride(snapshot);
+                    if (!r.ok) {
+                        json(res, 400, { error: 'validation failed', fields: r.errors });
+                        return;
+                    }
+                    json(res, 200, { ok: true, effective: r.effective, sources: r.sources });
+                    return;
+                }
+                if (req.method === 'GET' && req.url?.startsWith('/kanban/llm-catalog')) {
+                    json(res, 200, await buildLlmCatalog(llm));
+                    return;
+                }
                 json(res, 404, { error: 'not found' });
             }
             catch (err) {

package/lib/routes/planning-driver.d.ts

@@ -1,12 +1,13 @@
 import { KanbanService } from '../domain/kanban-service.js';
 import type { SpecCard, SpecCardAttachment } from '../domain/types.js';
-export declare const MATTPOCOCK_PLANNING_GUIDANCE = "\n# \u9636\u6BB5 0 \u89C4\u5212\u5BF9\u8BDD\uFF08v2\uFF1A\u9700\u6C42\u6F84\u6E05\u524D\u7F6E\u5316\uFF09\n1. \u9700\u6C42\u6F84\u6E05\uFF08grill-me\uFF09\uFF1A\u4E00\u6B21\u53EA\u95EE\u4E00\u4E2A\u95EE\u9898\uFF0C\u5148\u6F84\u6E05\u76EE\u7684\u3001\u7EA6\u675F\u3001\u6210\u529F\u6807\u51C6\uFF1B\u9010\u9879\u62F7\u95EE\u5047\u8BBE\u76F4\u81F3\u7528\u6237\"\u6CA1\u6709\u4EFB\u4F55\u7591\u95EE\"\u3002\n2. \u4ED3\u5E93\u4E8B\u5B9E\uFF08planning_prefetch\uFF09\uFF1A\u8C03\u53EA\u8BFB\u5B50\u4EE3\u7406\u91C7\u96C6\u76EE\u6807\u4ED3\u5E93/\u8D44\u6599/\u77E5\u8BC6\u5E93\u4E8B\u5B9E\uFF08\u672C\u5730\u8DEF\u5F84/\u5206\u652F/\u76EE\u6807\u6587\u4EF6\u57FA\u7EBF/\u65E2\u6709\u5B9E\u73B0\uFF09\uFF0C\u4E0D\u51ED\u7A7A\u5047\u8BBE\u3002\n3. \u6536\u655B\uFF08planning_checklist_save\uFF09\uFF1A\u628A\u7ED3\u8BBA\u5199\u6210\u7ED3\u6784\u5316\u9700\u6C42\u6F84\u6E05\u6E05\u5355\uFF08spec \u516D\u6BB5 + manifest repo.files + \u6F84\u6E05\u95EE\u7B54 + \u7591\u95EE\u70B9\uFF09\u5B58\u5165 KB\uFF08KB \u4E0D\u53EF\u8FBE\u81EA\u52A8\u515C\u5E95\u4E34\u65F6\u76EE\u5F55\uFF09\u3002\n4. \u6536\u5C3E\uFF1A\u63D0\u9192\u7528\u6237\u4EE5 /openspec: \u786E\u8BA4\u6267\u884C\u7ED3\u675F\u89C4\u5212\u9636\u6BB5\u2014\u2014/openspec: \u4F1A\u4ECE\u6E05\u5355\u5EFA\u94FE\u5E76\u81EA\u52A8\u4E32\u884C\u6267\u884C\u3002\n\u62A4\u680F\uFF1A\u89C4\u5212\u671F\u53EA\u8BFB\u4ED3\u5E93\uFF0C\u7981\u6B62\u4EFB\u4F55 git/\u6E90\u7801\u5199\u5165\uFF1B\u53EA\u5199 KB \u4E0E\u4E34\u65F6\u76EE\u5F55\u3002\n";
+import { type PrefixRoutes } from '../config.js';
+/** 阶段 0 规划引导：命令串从 config 派生（决策12），/openspec: 改名时文案自动跟随。
+ *  提问节奏与 skills/grill-me/SKILL.md 对齐：官方 frontier 分轮制（整批问 + 推荐答案 + 答复后解锁下一轮）；
+ *  增强项：人话硬规则 + 过程风险登记；收敛产物仍为 planning_checklist_save（KB 清单是建链数据源）。 */
+export declare function buildPlanningGuidance(routes: PrefixRoutes): string;
 export declare function validateSpecCardForApproval(card: SpecCard): string[];
-export declare function buildPlanningContext(chainId: string, card: SpecCard, attachments: SpecCardAttachment[]): string;
-export declare function approveIfReady(message: string, service: KanbanService, cfg: {
-    plan: string;
-    openspec: string;
-}, chainId: string, specCardId: string): Promise<{
+export declare function buildPlanningContext(chainId: string, card: SpecCard, attachments: SpecCardAttachment[], routes?: PrefixRoutes): string;
+export declare function approveIfReady(message: string, service: KanbanService, cfg: PrefixRoutes, chainId: string, specCardId: string): Promise<{
     ok: true;
     card: SpecCard;
 } | {

package/lib/routes/planning-driver.js

@@ -1,13 +1,21 @@
 import { KanbanService } from '../domain/kanban-service.js';
 import { parsePrefix } from './prefix-router.js';
-export const MATTPOCOCK_PLANNING_GUIDANCE = `
-# 阶段 0 规划对话（v2：需求澄清前置化）
-1. 需求澄清（grill-me）：一次只问一个问题，先澄清目的、约束、成功标准；逐项拷问假设直至用户"没有任何疑问"。
-2. 仓库事实（planning_prefetch）：调只读子代理采集目标仓库/资料/知识库事实（本地路径/分支/目标文件基线/既有实现），不凭空假设。
-3. 收敛（planning_checklist_save）：把结论写成结构化需求澄清清单（spec 六段 + manifest repo.files + 澄清问答 + 疑问点）存入 KB（KB 不可达自动兜底临时目录）。
-4. 收尾：提醒用户以 /openspec: 确认执行结束规划阶段——/openspec: 会从清单建链并自动串行执行。
+import { DEFAULT_PREFIX_ROUTES } from '../config.js';
+/** 阶段 0 规划引导：命令串从 config 派生（决策12），/openspec: 改名时文案自动跟随。
+ *  提问节奏与 skills/grill-me/SKILL.md 对齐：官方 frontier 分轮制（整批问 + 推荐答案 + 答复后解锁下一轮）；
+ *  增强项：人话硬规则 + 过程风险登记；收敛产物仍为 planning_checklist_save（KB 清单是建链数据源）。 */
+export function buildPlanningGuidance(routes) {
+    return `
+# 阶段 0 规划对话（v4：grill-me frontier 分轮，与 skills/grill-me 对齐）
+1. 需求澄清（grill-me，frontier 分轮）：把计划映射为设计决策树——每轮只问当前前提已就绪的问题（frontier），整批问出：编号 + 每问附推荐答案；等用户全部答复后重算 frontier（已定决定向外推进、解锁依赖它的问题）再发下一轮，本轮答不了的依赖问题留到后续轮。先澄清目的、约束、成功标准，逐支拷问直至用户"没有任何疑问"。
+2. 人话硬规则：问题正文与选项必须通俗；术语避不开时首次出现括号一句话解释；发问前自检「不懂本仓库的人能直接回答吗」，不能就重写。
+3. 仓库事实（planning_prefetch）：事实自查是规划者的职责——调只读子代理采集目标仓库/资料/知识库事实（本地路径/分支/目标文件基线/既有实现），不凭空假设、不拿可自查的问题问用户；只把真正的决定留给用户。
+4. 风险登记：每轮答复中若发现真实风险或非阻塞关注点，随手记一行（描述 + 来源决定 + 缓解思路），收敛时并入澄清清单；没有就不写，禁止硬凑。
+5. 收敛（planning_checklist_save）：把结论写成结构化需求澄清清单（spec 六段 + manifest repo.files + 澄清问答 + 疑问点 + 风险点（若有））存入 KB（KB 不可达自动兜底临时目录）。
+6. 收尾：提醒用户以 ${routes.openspec} 确认执行结束规划阶段——${routes.openspec} 会从清单建链并自动串行执行。
 护栏：规划期只读仓库，禁止任何 git/源码写入；只写 KB 与临时目录。
 `;
+}
 export function validateSpecCardForApproval(card) {
     const missing = [];
     const s = card.sections;
@@ -25,10 +33,10 @@ export function validateSpecCardForApproval(card) {
         missing.push('attachments:file-prefetch');
     return missing;
 }
-export function buildPlanningContext(chainId, card, attachments) {
+export function buildPlanningContext(chainId, card, attachments, routes = DEFAULT_PREFIX_ROUTES) {
     return [
         `# 规划上下文 chain=${chainId} specCard=${card.id}`,
-        MATTPOCOCK_PLANNING_GUIDANCE,
+        buildPlanningGuidance(routes),
         `## 当前规格卡\n${JSON.stringify(card.sections, null, 2)}`,
         `## 仓库事实附件\n${attachments.map((a) => `${a.name}: ${a.ref}`).join('\n') || '(无)'}`,
     ].join('\n\n');
@@ -36,16 +44,16 @@ export function buildPlanningContext(chainId, card, attachments) {
 export async function approveIfReady(message, service, cfg, chainId, specCardId) {
     const parsed = parsePrefix(message, cfg);
     if (parsed.kind !== 'openspec')
-        return { ok: false, missing: ['prefix'], guidance: MATTPOCOCK_PLANNING_GUIDANCE };
+        return { ok: false, missing: ['prefix'], guidance: buildPlanningGuidance(cfg) };
     const state = await service.snapshot();
     const card = state.specCards.get(specCardId);
     if (!card)
-        return { ok: false, missing: ['spec-card'], guidance: MATTPOCOCK_PLANNING_GUIDANCE };
+        return { ok: false, missing: ['spec-card'], guidance: buildPlanningGuidance(cfg) };
     if (card.status === 'approved')
         return { ok: true, card };
     const missing = validateSpecCardForApproval(card);
     if (missing.length > 0) {
-        return { ok: false, missing, guidance: MATTPOCOCK_PLANNING_GUIDANCE };
+        return { ok: false, missing, guidance: buildPlanningGuidance(cfg) };
     }
     const approved = await service.approveSpecCard(specCardId, 'human');
     return { ok: true, card: approved };

package/lib/routes/prefix-router.d.ts

@@ -1,20 +1,34 @@
 import { KanbanService } from '../domain/kanban-service.js';
 import type { PlanningChecklist } from '../domain/planning-checklist.js';
+import type { PrefixRoutes } from '../config.js';
+/** 防线D：/openspec: 建链后同步等待首张任务卡的最长时长与轮询间隔（fail-open：超时返回 pending，
+ *  由链级看门狗接管）。可变对象供测试注入短值（vitest 文件级隔离）。 */
+export declare const OPENSPEC_FIRST_CARD: {
+    timeoutMs: number;
+    pollIntervalMs: number;
+};
 export interface PrefixRouteResult {
-    kind: 'plan' | 'openspec' | 'none';
+    kind: 'plan' | 'openspec' | 'learning' | 'none';
     chainId?: string;
     specCardId?: string;
     rest: string;
+    brief?: string;
+    guidance?: string;
+    error?: string;
+    /** /openspec: 建链结果；false=被护栏拦截（reason 说明原因），未建任何链/卡。 */
+    approved?: boolean;
+    reason?: string;
+    /** 防线D：建链后同步等待的首卡结果。{taskId,status}=V 已建卡；{pending:true}=等待超时（fail-open，看门狗接管）。 */
+    firstCard?: {
+        taskId: string;
+        status: string;
+    } | {
+        pending: true;
+    };
 }
-export declare function parsePrefix(message: string, cfg: {
-    plan: string;
-    openspec: string;
-}): PrefixRouteResult;
+export declare function parsePrefix(message: string, cfg: PrefixRoutes): PrefixRouteResult;
 /** v2：/plan: 零副作用——不建链/规格卡/任务卡，仅返回路由结果（workspaceDir/sessionId 由 main-session-tools 捕获）。 */
-export declare function handlePlanRoute(message: string, _service: KanbanService, cfg: {
-    plan: string;
-    openspec: string;
-}, _ownerSessionId: string): Promise<PrefixRouteResult>;
+export declare function handlePlanRoute(message: string, _service: KanbanService, cfg: PrefixRoutes, _ownerSessionId: string): Promise<PrefixRouteResult>;
 export interface OpenspecPlanningInput {
     workspaceDir: string | null;
     checklist: PlanningChecklist;
@@ -23,7 +37,8 @@ export interface OpenspecPlanningInput {
     requirementName?: string | null;
 }
 /** v2：/openspec: 建链——从清单机械映射规格卡六段 → 挂 file-prefetch(仓库 localPath)+kb(清单页) → 批准 → executing。 */
-export declare function handleOpenspecRoute(message: string, service: KanbanService, cfg: {
-    plan: string;
-    openspec: string;
-}, planning: OpenspecPlanningInput, ownerSessionId: string): Promise<PrefixRouteResult>;
+export declare function handleOpenspecRoute(message: string, service: KanbanService, cfg: PrefixRoutes, planning: OpenspecPlanningInput, ownerSessionId: string): Promise<PrefixRouteResult>;
+/** /learning 零副作用引导文案：命令串从 config 派生（决策12），歧义/未找到时注入主 agent。 */
+export declare function buildLearningGuidance(routes: PrefixRoutes): string;
+/** v2：/learning 零副作用——不建链建卡，仅机械提取证据包供主 agent 蒸馏。歧义返回候选列表，链不存在返回错误文本（不 throw）。 */
+export declare function handleLearningRoute(message: string, service: KanbanService, cfg: PrefixRoutes, _ownerSessionId: string): Promise<PrefixRouteResult>;

package/lib/routes/prefix-router.js

@@ -1,10 +1,16 @@
 import { KanbanService, buildChainTitle } from '../domain/kanban-service.js';
+import { buildLearningBrief, resolveLearningChainId } from '../domain/memory.js';
+/** 防线D：/openspec: 建链后同步等待首张任务卡的最长时长与轮询间隔（fail-open：超时返回 pending，
+ *  由链级看门狗接管）。可变对象供测试注入短值（vitest 文件级隔离）。 */
+export const OPENSPEC_FIRST_CARD = { timeoutMs: 120_000, pollIntervalMs: 1_000 };
 export function parsePrefix(message, cfg) {
     const trimmed = message.trim();
     if (trimmed.startsWith(cfg.plan))
         return { kind: 'plan', rest: trimmed.slice(cfg.plan.length).trim() };
     if (trimmed.startsWith(cfg.openspec))
         return { kind: 'openspec', rest: trimmed.slice(cfg.openspec.length).trim() };
+    if (trimmed.startsWith(cfg.learning))
+        return { kind: 'learning', rest: trimmed.slice(cfg.learning.length).trim() };
     return { kind: 'none', rest: trimmed };
 }
 /** v2：/plan: 零副作用——不建链/规格卡/任务卡，仅返回路由结果（workspaceDir/sessionId 由 main-session-tools 捕获）。 */
@@ -16,6 +22,23 @@ export async function handleOpenspecRoute(message, service, cfg, planning, owner
     const parsed = parsePrefix(message, cfg);
     if (parsed.kind !== 'openspec')
         return parsed;
+    // 护栏前移（fail-fast）：无 workspaceDir 的链会让 V 在 getVAgent 抛 workspace-unknown
+    // 且被 dispatcher 静默吞掉（链上零任务 → 无任何后续事件重试）→ 空壳链死锁。
+    // 典型成因：主 agent 进程重启后 planningBySession 重建，仅重存清单未重走 /plan:，
+    // workspaceDir 为 null。此处禁止建链建卡，引导用户先 /plan: 重新捕获工作区。
+    if (!planning.workspaceDir || !planning.workspaceDir.trim()) {
+        return {
+            kind: 'openspec', approved: false, reason: 'workspace-unknown', rest: parsed.rest,
+            guidance: [
+                '## 建链被拦截：workspaceDir 缺失（workspace-unknown）',
+                '当前规划上下文没有目标仓库工作区（多为主 agent 重启后清单内存重建所致）。',
+                '处理步骤（严格顺序）：',
+                '1. 重新发送 ' + cfg.plan + ' <需求描述> 让主 agent 捕获工作区（必要时按提示注册工作区）；',
+                '2. 清单仍在时重发 ' + cfg.openspec + ' 确认即可建链；清单丢失则重新澄清后再确认。',
+                '禁止：在无工作区时建链建卡；猜测工作区路径。',
+            ].join('\n'),
+        };
+    }
     const chain = await service.createChain({
         title: buildChainTitle(planning.checklist.requirementName ?? planning.requirementName ?? null, parsed.rest, planning.checklist.spec.problem),
         ownerSessionId, workspaceDir: planning.workspaceDir,
@@ -24,5 +47,47 @@ export async function handleOpenspecRoute(message, service, cfg, planning, owner
     await service.addSpecCardAttachment(card.id, { name: '需求澄清清单(仓库事实)', kind: 'file-prefetch', ref: planning.checklist.manifest.repo.localPath }, 'v');
     await service.addSpecCardAttachment(card.id, { name: '需求澄清清单(完整资料)', kind: 'kb', ref: planning.checklistRef }, 'v');
     await service.approveSpecCard(card.id, 'human');
-    return { kind: 'openspec', chainId: chain.id, specCardId: card.id, rest: parsed.rest };
+    const firstCard = await waitFirstCard(service, chain.id);
+    return { kind: 'openspec', chainId: chain.id, specCardId: card.id, rest: parsed.rest, firstCard };
+}
+/** 防线D：轮询看板等首张任务卡（任意 assignee/mode，V 首轮建 p 卡）。成功即返；
+ *  超时 fail-open 返回 {pending:true}——不挂死工具调用，失败面由链级看门狗兜底。 */
+async function waitFirstCard(service, chainId) {
+    const deadline = Date.now() + OPENSPEC_FIRST_CARD.timeoutMs;
+    for (;;) {
+        const state = await service.snapshot();
+        const t = [...state.tasks.values()].filter((x) => x.chainId === chainId).at(-1);
+        if (t)
+            return { taskId: t.id, status: t.status };
+        if (Date.now() >= deadline)
+            return { pending: true };
+        await new Promise((r) => setTimeout(r, Math.min(OPENSPEC_FIRST_CARD.pollIntervalMs, Math.max(1, deadline - Date.now()))));
+    }
+}
+/** /learning 零副作用引导文案：命令串从 config 派生（决策12），歧义/未找到时注入主 agent。 */
+export function buildLearningGuidance(routes) {
+    return [
+        '## 经验蒸馏指令（' + routes.learning + '）',
+        '消化上方「链上下文 + 机械信号证据包」，蒸馏 1-3 条可复用经验（返工根因 / 阻塞原因 / 审计教训）。',
+        '每条约成 LearningEntry（title 一句话≤80 字符；lesson 教训；evidence 必须填本链 chain id 作机械证据；tags 自由标签）。',
+        '调 planning_learning_save：scope=chain 存需求级 projects/<repoSlug>/<chainId>/learnings/；仓库通用经验用 scope=project（projects/<repoSlug>/learnings/，repoSlug 由链 workspaceDir 派生）。',
+        '无值得沉淀的经验时，明确回复「无新经验」，不要硬凑。',
+    ].join('\n');
+}
+/** v2：/learning 零副作用——不建链建卡，仅机械提取证据包供主 agent 蒸馏。歧义返回候选列表，链不存在返回错误文本（不 throw）。 */
+export async function handleLearningRoute(message, service, cfg, _ownerSessionId) {
+    const parsed = parsePrefix(message, cfg);
+    if (parsed.kind !== 'learning')
+        return parsed;
+    const state = await service.snapshot();
+    const resolved = resolveLearningChainId(state, parsed.rest);
+    if (resolved === null) {
+        return { kind: 'learning', rest: parsed.rest, error: 'chain-not-found', guidance: `未找到可蒸馏经验的链。可用 ${cfg.learning} <chainId> 指定，或先经 ${cfg.plan}${cfg.openspec} 建立链路。` };
+    }
+    if ('candidates' in resolved) {
+        const list = resolved.candidates.map((c) => `- ${c.chainId} ${c.title}`).join('\n');
+        return { kind: 'learning', rest: parsed.rest, error: 'chain-ambiguous', guidance: `匹配到多条链，请用 ${cfg.learning} <chainId> 精确指定：\n${list}` };
+    }
+    const brief = buildLearningBrief(state, resolved.chainId);
+    return { kind: 'learning', chainId: resolved.chainId, rest: parsed.rest, brief, guidance: buildLearningGuidance(cfg) };
 }

package/lib/services/config-provider.d.ts

@@ -0,0 +1,42 @@
+import { Service, type Context } from '@deepseek-ai/cordis';
+import type { EditableSnapshot, SourceMap } from '../domain/config-override.js';
+import type { KanbanConfig } from '../config.js';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        swarmConfig: ConfigProvider;
+    }
+}
+export type ApplyResult = {
+    ok: true;
+    effective: EditableSnapshot;
+    sources: SourceMap;
+    changed: string[];
+} | {
+    ok: false;
+    errors: string[];
+};
+export declare class ConfigProvider extends Service {
+    private readonly baseline;
+    private readonly overrideFile;
+    private readonly auditFile;
+    private override;
+    private effective;
+    private sources;
+    constructor(ctx: Context, baseline: KanbanConfig, storageDir: string);
+    getEffective(): KanbanConfig;
+    getSources(): SourceMap;
+    get mode(): 'remote' | 'local';
+    snapshot(): {
+        effective: EditableSnapshot;
+        sources: SourceMap;
+    };
+    applyOverride(snapshot: EditableSnapshot): ApplyResult;
+    reset(): {
+        effective: EditableSnapshot;
+        sources: SourceMap;
+    };
+    private readOverride;
+    private writeOverride;
+    private appendAudit;
+    private diffKeys;
+}

package/lib/services/config-provider.js

@@ -0,0 +1,94 @@
+import { Service } from '@deepseek-ai/cordis';
+import { readFileSync, writeFileSync, renameSync, existsSync, appendFileSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { mergeConfig, computeSources, projectEditable, validateConfig, diffOverride, } from '../domain/config-override.js';
+export class ConfigProvider extends Service {
+    baseline;
+    overrideFile;
+    auditFile;
+    override;
+    effective;
+    sources;
+    constructor(ctx, baseline, storageDir) {
+        super(ctx, 'swarmConfig');
+        this.baseline = baseline;
+        this.overrideFile = join(storageDir, 'config-override.json');
+        this.auditFile = join(storageDir, 'config-audit.log');
+        this.override = this.readOverride();
+        this.effective = mergeConfig(baseline, this.override);
+        this.sources = computeSources(this.override);
+    }
+    getEffective() { return this.effective; }
+    getSources() { return this.sources; }
+    // mode 派生自 effective.wikiVault.baseUrl；运行期改 baseUrl 需重启 dsh 使客户端注册面同步（D11 不可热切换）：
+    // 注册期冻结（dispatcher、main-session-tools 客户端构造）与运行期活读（agent-runner guard、kanban-provider 交付闸）
+    // 分属两类读取点，中途 applyOverride 改 baseUrl 会产生混合态（后果 fail-closed 可见，不静默）。
+    get mode() { return (this.effective.wikiVault?.baseUrl ?? '').trim() ? 'remote' : 'local'; }
+    snapshot() {
+        return { effective: projectEditable(this.effective), sources: this.sources };
+    }
+    applyOverride(snapshot) {
+        const errors = validateConfig(snapshot);
+        if (errors.length)
+            return { ok: false, errors };
+        const next = diffOverride(this.baseline, snapshot);
+        const changed = this.diffKeys(this.override, next);
+        this.writeOverride(next);
+        if (changed.length)
+            this.appendAudit(changed);
+        this.override = next;
+        this.effective = mergeConfig(this.baseline, next);
+        this.sources = computeSources(next);
+        return { ok: true, effective: projectEditable(this.effective), sources: this.sources, changed };
+    }
+    reset() {
+        const next = {};
+        this.writeOverride(next);
+        this.override = next;
+        this.effective = mergeConfig(this.baseline, next);
+        this.sources = computeSources(next);
+        return { effective: projectEditable(this.effective), sources: this.sources };
+    }
+    readOverride() {
+        try {
+            if (!existsSync(this.overrideFile))
+                return {};
+            const raw = JSON.parse(readFileSync(this.overrideFile, 'utf8'));
+            return raw ?? {};
+        }
+        catch (err) {
+            console.warn('[dsh-swarm] config-override.json 损坏，回退基线: ' + String(err));
+            return {};
+        }
+    }
+    writeOverride(next) {
+        mkdirSync(dirname(this.overrideFile), { recursive: true });
+        const tmp = this.overrideFile + '.tmp-' + Date.now();
+        writeFileSync(tmp, JSON.stringify(next, null, 2));
+        renameSync(tmp, this.overrideFile);
+    }
+    appendAudit(changed) {
+        const line = new Date().toISOString() + ' | ' + changed.join(', ') + '\n';
+        try {
+            mkdirSync(dirname(this.auditFile), { recursive: true });
+            appendFileSync(this.auditFile, line);
+        }
+        catch { /* 审计失败不阻断 */ }
+    }
+    diffKeys(prev, next) {
+        const keys = new Set();
+        for (const k of ['baseUrl', 'pagePrefix']) {
+            if (prev.wikiVault?.[k] !== next.wikiVault?.[k])
+                keys.add('wikiVault.' + k);
+        }
+        for (const role of ['v', 'p', 'w', 'd', 'pt', 'dt']) {
+            for (const f of ['provider', 'model', 'reasoningEffort']) {
+                const a = prev.roles?.models?.[role]?.[f];
+                const b = next.roles?.models?.[role]?.[f];
+                if (a !== b)
+                    keys.add(`roles.models.${role}.${f}`);
+            }
+        }
+        return [...keys];
+    }
+}

package/lib/services/gate-runner.d.ts

@@ -0,0 +1,24 @@
+import type { GateCommand } from '../domain/gate-policy.js';
+export interface GateResult {
+    command: string;
+    exitCode: number | null;
+    durationMs: number;
+    output: string;
+    truncated: boolean;
+}
+export interface GateRunReport {
+    ok: boolean;
+    results: GateResult[];
+    failure?: {
+        command: string;
+        code: 'NONZERO' | 'TIMEOUT' | 'FORBIDDEN' | 'SPAWN_FAIL';
+        detail: string;
+    };
+}
+export declare function runOne(cmd: GateCommand, timeoutMs: number): Promise<GateResult & {
+    timedOut?: boolean;
+}>;
+export declare function runGateCommands(commands: GateCommand[], cfg: {
+    timeoutMs: number;
+    forbidden: string[];
+}, run?: typeof runOne): Promise<GateRunReport>;

package/lib/services/gate-runner.js

@@ -0,0 +1,87 @@
+// src/services/gate-runner.ts
+/** kanban_complete 实测闸执行层（services 层唯一允许 child_process 之处之一）：
+ * spawn bash -c 执行 GateCommand，带超时整组 SIGKILL（detached 独立进程组，连孙进程一起杀，
+ * 防其持住 stdio 管道导致 close 不触发、Promise 挂死）、输出 256KB 截断、
+ * 黑名单子串预检（纵深防御，命中即不执行）。
+ * 命令串行执行，任一失败（FORBIDDEN/TIMEOUT/SPAWN_FAIL/NONZERO）立即返回，后续命令不再执行。 */
+import { spawn } from 'node:child_process';
+const MAX_OUTPUT = 256 * 1024;
+/** exit 后 close 迟迟不触发（如整组击杀失败、孙进程仍持管道）时的兜底 resolve 宽限 */
+const EXIT_GRACE_MS = 1000;
+export function runOne(cmd, timeoutMs) {
+    return new Promise((resolve) => {
+        const started = Date.now();
+        const child = spawn('bash', ['-c', cmd.command], {
+            cwd: cmd.cwd,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            detached: process.platform !== 'win32', // 独立进程组：超时按组 SIGKILL，防孙进程持管道挂死
+        });
+        let out = '';
+        let truncated = false;
+        let timedOut = false;
+        let settled = false;
+        let exitGrace;
+        const finish = (exitCode, output) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (exitGrace !== undefined)
+                clearTimeout(exitGrace);
+            resolve({ command: cmd.command, exitCode, durationMs: Date.now() - started, output, truncated, timedOut });
+        };
+        const killGroup = () => {
+            if (child.pid === undefined) {
+                child.kill('SIGKILL');
+                return;
+            }
+            try {
+                process.kill(-child.pid, 'SIGKILL');
+            }
+            catch {
+                child.kill('SIGKILL');
+            }
+        };
+        const timer = setTimeout(() => { timedOut = true; killGroup(); }, timeoutMs);
+        const collect = (chunk) => {
+            if (out.length >= MAX_OUTPUT) {
+                truncated = true;
+                return;
+            }
+            out += chunk.toString('utf8');
+            if (out.length > MAX_OUTPUT) {
+                out = out.slice(0, MAX_OUTPUT);
+                truncated = true;
+            }
+        };
+        child.stdout.on('data', collect);
+        child.stderr.on('data', collect);
+        child.on('error', (err) => {
+            finish(null, String(err));
+        });
+        // close 需 stdio 管道全部关闭；exit 先到而 close 迟迟不来时按宽限兜底 resolve（尽力收集已到输出）
+        child.on('exit', (code) => {
+            exitGrace = setTimeout(() => finish(code, out), EXIT_GRACE_MS);
+        });
+        child.on('close', (code) => {
+            finish(code, out);
+        });
+    });
+}
+export async function runGateCommands(commands, cfg, run = runOne) {
+    const results = [];
+    for (const cmd of commands) {
+        if (cfg.forbidden.some((f) => cmd.command.includes(f))) {
+            return { ok: false, results, failure: { command: cmd.command, code: 'FORBIDDEN', detail: '黑名单命中（纵深防御，不执行）' } };
+        }
+        const r = await run(cmd, cfg.timeoutMs);
+        results.push({ command: r.command, exitCode: r.exitCode, durationMs: r.durationMs, output: r.output, truncated: r.truncated });
+        if (r.timedOut)
+            return { ok: false, results, failure: { command: r.command, code: 'TIMEOUT', detail: `超时（${cfg.timeoutMs}ms）` } };
+        if (r.exitCode === null)
+            return { ok: false, results, failure: { command: r.command, code: 'SPAWN_FAIL', detail: r.output } };
+        if (r.exitCode !== 0)
+            return { ok: false, results, failure: { command: r.command, code: 'NONZERO', detail: `退出码 ${r.exitCode}` } };
+    }
+    return { ok: true, results };
+}

package/lib/services/kanban-provider.d.ts

@@ -1,6 +1,7 @@
 import { Service, type Context } from '@deepseek-ai/cordis';
 import { KanbanService } from '../domain/kanban-service.js';
 import type { KanbanConfig } from '../config.js';
+import type { ConfigProvider } from './config-provider.js';
 declare module '@deepseek-ai/cordis' {
     interface Context {
         kanban: KanbanProvider;
@@ -12,5 +13,8 @@ export declare class KanbanProvider extends Service {
     runner: {
         runTask(taskId: string): Promise<void>;
     } | null;
-    constructor(ctx: Context, config: KanbanConfig);
+    /** 整链硬删除后的联动钩子（由 startDispatcher 装配注入）：dispatcher 游标同步 + V 编排 entry 清理。
+     *  purge 物理重排 events seq，若不同步则删链后新建链的可唤醒事件被运行中实例永久跳过。 */
+    onChainDeleted: ((chainId: string) => Promise<void> | void) | null;
+    constructor(ctx: Context, config: KanbanConfig, configProvider: ConfigProvider);
 }