@joekytc/dsh-swarm 0.2.0 → 0.3.0

package/lib/routes/kanban-http.js

@@ -1,4 +1,8 @@
+import { execFile } from 'node:child_process';
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
 import { buildLlmCatalog } from '../services/llm-catalog.js';
+import { INSTALL_GUIDANCE, OCR_PACKAGE, managedProviderReady, probeOcr, wireManagedProvider } from '../services/ocr-cli.js';
 import { serveKanbanEvents } from './kanban-sse.js';
 function json(res, status, body) {
     res.statusCode = status;
@@ -13,10 +17,95 @@ function readBody(req) {
         req.on('error', reject);
     });
 }
+const defaultOcrInstaller = (onSpawn) => new Promise((resolve) => {
+    const child = execFile('npm', ['install', '-g', OCR_PACKAGE], { timeout: 600_000 }, (err, stdout, stderr) => {
+        if (err)
+            resolve({ ok: false, log: `${err.message}\n${String(stderr ?? '')}`.trim() });
+        else
+            resolve({ ok: true, log: String(stdout ?? '') });
+    });
+    onSpawn?.(child);
+});
+/** 模块级单飞安装任务态：同一插件进程同时只允许一个 npm 全局安装在跑。 */
+let installJob = null;
+/** 安装关键事件落盘（与 dispatcher.log 同文件同格式，写失败静默——日志只是观测面）。 */
+function logOcrEvent(configProvider, msg) {
+    try {
+        const storageDir = configProvider.getEffective().storageDir.replace('$DSH_HOME', process.env.DSH_HOME ?? process.cwd());
+        writeFileSync(join(storageDir, 'dispatcher.log'), new Date().toISOString() + ' ' + msg + '\n', { flag: 'a' });
+    }
+    catch { /* 忽略写失败 */ }
+}
+async function runOcrInstall(deps, configProvider) {
+    const job = installJob;
+    if (!job)
+        return;
+    try {
+        const r = await (deps?.installer ?? defaultOcrInstaller)((child) => { job.child = child; });
+        if (!job.running)
+            return; // 已取消：cancelled 是终态，迟到的安装结果不覆盖
+        job.running = false;
+        job.log = r.log;
+        if (r.ok) {
+            job.result = 'ok';
+            const probe = await (deps?.probeFn ?? probeOcr)();
+            job.version = probe.version;
+            logOcrEvent(configProvider, '[ocr-install] ok' + (probe.version ? ' version=' + probe.version : ''));
+        }
+        else {
+            job.result = 'failed';
+            logOcrEvent(configProvider, '[ocr-install] failed');
+        }
+    }
+    catch (err) {
+        if (!job.running)
+            return;
+        job.running = false;
+        job.result = 'failed';
+        job.log = String(err);
+        logOcrEvent(configProvider, '[ocr-install] failed: ' + String(err));
+    }
+}
+/** wire 降级文案：解析不到该提供方接入信息时，引导终端手动配置（不写半套 ocr 配置）。 */
+const OCR_WIRE_DEGRADED = '未能从 dsh 解析该提供方的接入信息（baseUrl/apiKey）——请在终端手动执行 ocr config provider 完成托管配置；委托模式不受影响';
+/**
+ * 从宿主设置解析所选提供方的接入信息（baseUrl/协议/apiKey）。
+ * 事实核查结论（实现期探查）：llm 服务的公开 API 不暴露连接事实，但同进程可经
+ * settings 服务的 describe() 读到模型适配器的 provider profile——形如
+ * { providers: { <id>: { baseURL, api, apiKey | apiKeyEnv } } }（apiKeyEnv 指向进程环境变量名）。
+ * 命中 profile 但字段不全时跳过该 descriptor 继续尝试下一个（多 descriptor 场景勿误降级），
+ * 绝不回传半套配置；全部不合才返回 null 走降级。apiKey 只透传给 ocr config，不落日志。
+ */
+function resolveDshProviderAccess(ctx, providerId) {
+    try {
+        const settings = ctx.get('settings');
+        const descriptors = settings?.describe?.() ?? [];
+        for (const d of descriptors) {
+            const providers = d.value?.providers;
+            const profile = providers?.[providerId];
+            if (!profile || typeof profile !== 'object')
+                continue;
+            const baseUrl = typeof profile.baseURL === 'string' ? profile.baseURL : '';
+            const api = typeof profile.api === 'string' ? profile.api : '';
+            const protocol = api.startsWith('openai') ? 'openai' : api.includes('anthropic') ? 'anthropic' : '';
+            let apiKey = typeof profile.apiKey === 'string' ? profile.apiKey : '';
+            if (!apiKey && typeof profile.apiKeyEnv === 'string')
+                apiKey = process.env[profile.apiKeyEnv] ?? '';
+            if (baseUrl && protocol && apiKey)
+                return { baseUrl, protocol, apiKey };
+            continue; // 字段不全：换下一个 descriptor，勿在此误降级
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
 /** 看板 HTTP 桥（Web GUI 浏览器半消费）：GET /kanban/board 读快照；POST /kanban/action 执行状态操作；
- *  GET/PUT /kanban/config + POST /kanban/config/reset 配置读写；GET /kanban/llm-catalog 模型目录。
+ *  GET/PUT /kanban/config 配置读写（无 reset：各用户模型配置不同，无公共默认值）；GET /kanban/llm-catalog 模型目录；
+ *  GET /kanban/ocr/status + POST /kanban/ocr/install(/cancel) + GET install/state + POST /kanban/ocr/wire ocr 评审引擎运维。
  *  仅在 webServer 服务存在时挂载（CLI/headless/测试裸 Context 不挂）。 */
-export function registerKanbanHttp(ctx, provider, configProvider, llm, config) {
+export function registerKanbanHttp(ctx, provider, configProvider, llm, config, ocrDeps) {
     // 可选服务：经 ctx.get 读取（cordis 4 直接属性读取需 inject；get 不需要）
     const webServer = ctx.get('webServer');
     if (!webServer)
@@ -46,7 +135,7 @@ export function registerKanbanHttp(ctx, provider, configProvider, llm, config) {
                 }
                 if (req.method === 'POST' && req.url?.startsWith('/kanban/action')) {
                     const body = JSON.parse((await readBody(req)) || '{}');
-                    // D23：confirm-audit 是链级 action（无 taskId），提前分流处理
+                    // confirm-audit 是链级 action（无 taskId），提前分流处理
                     if (body.type === 'confirm-audit') {
                         const chainId = String(body.chainId ?? '').trim();
                         if (!chainId) {
@@ -71,7 +160,7 @@ export function registerKanbanHttp(ctx, provider, configProvider, llm, config) {
                         json(res, 200, { ok: true });
                         return;
                     }
-                    // T7：rename 是链级或任务级 action（chainId 或 taskId 二选一），在 taskId 守卫前分流
+                    // rename 是链级或任务级 action（chainId 或 taskId 二选一），在 taskId 守卫前分流
                     if (body.type === 'rename') {
                         const title = String(body.title ?? '').trim();
                         if (!title) {
@@ -108,7 +197,7 @@ export function registerKanbanHttp(ctx, provider, configProvider, llm, config) {
                             await provider.service.unblockTask(t, 'human');
                             break;
                         case 'retry': {
-                            // T32 fix：retry 走 runner（failed→claim→spawn/resume），而非只 claim 造成 running 悬挂
+                            // retry 走 runner（failed→claim→spawn/resume），而非只 claim 造成 running 悬挂
                             const state = await provider.service.snapshot();
                             const task = state.tasks.get(t);
                             if (!task) {
@@ -154,21 +243,25 @@ export function registerKanbanHttp(ctx, provider, configProvider, llm, 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
+                    // 归一化缺省字段，保证缺字段走 400 校验失败而非 500。
+                    // reviewEngine 缺省时回退当前 effective（再兜底默认）：旧客户端 bundle 不带该字段时保存不清空既有评审引擎配置。
+                    const fb = configProvider.getEffective().reviewEngine;
                     const snapshot = {
                         wikiVault: { baseUrl: raw.wikiVault?.baseUrl ?? '', pagePrefix: raw.wikiVault?.pagePrefix ?? '' },
                         roles: { models: raw.roles?.models ?? {} },
+                        reviewEngine: {
+                            mode: raw.reviewEngine?.mode ?? fb?.mode ?? 'delegate',
+                            managed: {
+                                provider: raw.reviewEngine?.managed?.provider ?? fb?.managed?.provider ?? '',
+                                model: raw.reviewEngine?.managed?.model ?? fb?.managed?.model ?? '',
+                            },
+                        },
                     };
                     const r = configProvider.applyOverride(snapshot);
                     if (!r.ok) {
@@ -182,6 +275,73 @@ export function registerKanbanHttp(ctx, provider, configProvider, llm, config) {
                     json(res, 200, await buildLlmCatalog(llm));
                     return;
                 }
+                // ocr 运维面：cancel 前置于 install（POST 前缀匹配防遮蔽），install/state 与 install 以 method 区分
+                if (req.method === 'POST' && req.url?.startsWith('/kanban/ocr/install/cancel')) {
+                    if (!installJob?.running) {
+                        json(res, 200, { ok: false, error: 'no-install-running' });
+                        return;
+                    }
+                    installJob.child?.kill('SIGTERM');
+                    installJob.running = false;
+                    installJob.result = 'cancelled';
+                    logOcrEvent(configProvider, '[ocr-install] cancelled');
+                    json(res, 200, { ok: true });
+                    return;
+                }
+                if (req.method === 'POST' && req.url?.startsWith('/kanban/ocr/install')) {
+                    if (installJob?.running) {
+                        json(res, 409, { error: 'install-in-progress' });
+                        return;
+                    }
+                    installJob = { id: 'ocr-install-' + Date.now(), running: true, child: null, log: '' };
+                    logOcrEvent(configProvider, '[ocr-install] start');
+                    void runOcrInstall(ocrDeps, configProvider);
+                    json(res, 200, { ok: true, id: installJob.id });
+                    return;
+                }
+                if (req.method === 'GET' && req.url?.startsWith('/kanban/ocr/install/state')) {
+                    json(res, 200, installJob
+                        ? { running: installJob.running, result: installJob.result, version: installJob.version, log: installJob.log }
+                        : { running: false, log: '' });
+                    return;
+                }
+                if (req.method === 'GET' && req.url?.startsWith('/kanban/ocr/status')) {
+                    const probe = await (ocrDeps?.probeFn ?? probeOcr)();
+                    json(res, 200, {
+                        installed: probe.installed,
+                        version: probe.version,
+                        mode: configProvider.getEffective().reviewEngine.mode,
+                        // kbMode 随状态端点透出：前端据此显示 local 模式下独立评审不落 wiki 的提示
+                        kbMode: configProvider.mode,
+                        managedReady: ocrDeps?.managedReadyFn ? ocrDeps.managedReadyFn() : managedProviderReady(),
+                    });
+                    return;
+                }
+                if (req.method === 'POST' && req.url?.startsWith('/kanban/ocr/wire')) {
+                    const body = JSON.parse((await readBody(req)) || '{}');
+                    const providerId = String(body.provider ?? '').trim();
+                    const model = String(body.model ?? '').trim();
+                    if (!providerId || !model) {
+                        json(res, 400, { error: 'provider and model required' });
+                        return;
+                    }
+                    const probe = await (ocrDeps?.probeFn ?? probeOcr)();
+                    if (!probe.installed) {
+                        json(res, 200, { ok: false, log: INSTALL_GUIDANCE });
+                        return;
+                    }
+                    const access = resolveDshProviderAccess(ctx, providerId);
+                    if (!access) {
+                        json(res, 200, { ok: false, log: OCR_WIRE_DEGRADED });
+                        return;
+                    }
+                    const r = ocrDeps?.wirer
+                        ? await ocrDeps.wirer({ provider: providerId, model })
+                        : await wireManagedProvider({ baseUrl: access.baseUrl, protocol: access.protocol, apiKey: access.apiKey, model });
+                    logOcrEvent(configProvider, '[ocr-wire] ' + (r.ok ? 'ok' : 'fail'));
+                    json(res, 200, { ok: r.ok, log: r.log });
+                    return;
+                }
                 json(res, 404, { error: 'not found' });
             }
             catch (err) {

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

@@ -2,7 +2,7 @@ import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { KanbanService } from '../domain/kanban-service.js';
 import type { KanbanEvent } from '../domain/types.js';
 export declare function writeSseEvent(res: ServerResponse, event: KanbanEvent): void;
-/** T23：SSE 事件桥。先订阅并缓存 live 事件，再补发补偿事件，握手窗口不丢事件。 */
+/** SSE 事件桥。先订阅并缓存 live 事件，再补发补偿事件，握手窗口不丢事件。 */
 export declare function serveKanbanEvents(req: IncomingMessage, res: ServerResponse, service: Pick<KanbanService, 'subscribe' | 'eventsSince'>, options: {
     heartbeatMs: number;
 }): Promise<void>;

package/lib/routes/kanban-sse.js

@@ -10,7 +10,7 @@ function lastSeen(req) {
     const header = Number(headerValue ?? -1);
     return Math.max(Number.isFinite(query) ? query : -1, Number.isFinite(header) ? header : -1);
 }
-/** T23：SSE 事件桥。先订阅并缓存 live 事件，再补发补偿事件，握手窗口不丢事件。 */
+/** SSE 事件桥。先订阅并缓存 live 事件，再补发补偿事件，握手窗口不丢事件。 */
 export async function serveKanbanEvents(req, res, service, options) {
     res.statusCode = 200;
     res.setHeader('content-type', 'text/event-stream; charset=utf-8');

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

@@ -1,10 +1,12 @@
 import { KanbanService } from '../domain/kanban-service.js';
 import type { SpecCard, SpecCardAttachment } from '../domain/types.js';
 import { type PrefixRoutes } from '../config.js';
-/** 阶段 0 规划引导：命令串从 config 派生（决策12），/openspec: 改名时文案自动跟随。
+/** 阶段 0 规划引导：命令串从 config 派生，/openspec: 改名时文案自动跟随。
  *  提问节奏与 skills/grill-me/SKILL.md 对齐：官方 frontier 分轮制（整批问 + 推荐答案 + 答复后解锁下一轮）；
  *  增强项：人话硬规则 + 过程风险登记；收敛产物仍为 planning_checklist_save（KB 清单是建链数据源）。 */
-export declare function buildPlanningGuidance(routes: PrefixRoutes): string;
+export declare function buildPlanningGuidance(routes: PrefixRoutes, opts?: {
+    swarm?: boolean;
+}): string;
 export declare function validateSpecCardForApproval(card: SpecCard): string[];
 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<{

package/lib/routes/planning-driver.js

@@ -1,10 +1,14 @@
 import { KanbanService } from '../domain/kanban-service.js';
 import { parsePrefix } from './prefix-router.js';
 import { DEFAULT_PREFIX_ROUTES } from '../config.js';
-/** 阶段 0 规划引导：命令串从 config 派生（决策12），/openspec: 改名时文案自动跟随。
+/** 阶段 0 规划引导：命令串从 config 派生，/openspec: 改名时文案自动跟随。
  *  提问节奏与 skills/grill-me/SKILL.md 对齐：官方 frontier 分轮制（整批问 + 推荐答案 + 答复后解锁下一轮）；
  *  增强项：人话硬规则 + 过程风险登记；收敛产物仍为 planning_checklist_save（KB 清单是建链数据源）。 */
-export function buildPlanningGuidance(routes) {
+export function buildPlanningGuidance(routes, opts) {
+    // 第 6 条按形态分叉：前缀 = 教学旧命令收尾（逐字节不变）；swarm = 确认闸语义（不提旧命令，与 KANBAN_HANDOFF_RULE swarm 确认闸对齐）。
+    const finish = opts?.swarm
+        ? `6. 收尾（确认闸）：清单落库后向用户征求确认；仅当用户回复含明确肯定语义（确认/开干/开跑/开始/go 等）才调 kanban_route{intent:'openspec'} 建链开跑；模糊回复视为未确认，继续澄清。`
+        : `6. 收尾：提醒用户以 ${routes.openspec} 确认执行结束规划阶段——${routes.openspec} 会从清单建链并自动串行执行。`;
     return `
 # 阶段 0 规划对话（v4：grill-me frontier 分轮，与 skills/grill-me 对齐）
 1. 需求澄清（grill-me，frontier 分轮）：把计划映射为设计决策树——每轮只问当前前提已就绪的问题（frontier），整批问出：编号 + 每问附推荐答案；等用户全部答复后重算 frontier（已定决定向外推进、解锁依赖它的问题）再发下一轮，本轮答不了的依赖问题留到后续轮。先澄清目的、约束、成功标准，逐支拷问直至用户"没有任何疑问"。
@@ -12,7 +16,7 @@ export function buildPlanningGuidance(routes) {
 3. 仓库事实（planning_prefetch）：事实自查是规划者的职责——调只读子代理采集目标仓库/资料/知识库事实（本地路径/分支/目标文件基线/既有实现），不凭空假设、不拿可自查的问题问用户；只把真正的决定留给用户。
 4. 风险登记：每轮答复中若发现真实风险或非阻塞关注点，随手记一行（描述 + 来源决定 + 缓解思路），收敛时并入澄清清单；没有就不写，禁止硬凑。
 5. 收敛（planning_checklist_save）：把结论写成结构化需求澄清清单（spec 六段 + manifest repo.files + 澄清问答 + 疑问点 + 风险点（若有））存入 KB（KB 不可达自动兜底临时目录）。
-6. 收尾：提醒用户以 ${routes.openspec} 确认执行结束规划阶段——${routes.openspec} 会从清单建链并自动串行执行。
+${finish}
 护栏：规划期只读仓库，禁止任何 git/源码写入；只写 KB 与临时目录。
 `;
 }

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

@@ -8,7 +8,7 @@ export declare const OPENSPEC_FIRST_CARD: {
     pollIntervalMs: number;
 };
 export interface PrefixRouteResult {
-    kind: 'plan' | 'openspec' | 'learning' | 'none';
+    kind: 'plan' | 'openspec' | 'learning' | 'send' | 'none';
     chainId?: string;
     specCardId?: string;
     rest: string;
@@ -33,12 +33,12 @@ export interface OpenspecPlanningInput {
     workspaceDir: string | null;
     checklist: PlanningChecklist;
     checklistRef: string;
-    /** T7：/plan: rest 原始需求描述；null=无 /plan: 捕获（回退 checklist.problem 首句/未命名需求）。 */
+    /** /plan: rest 原始需求描述；null=无 /plan: 捕获（回退 checklist.problem 首句/未命名需求）。 */
     requirementName?: string | null;
 }
 /** v2：/openspec: 建链——从清单机械映射规格卡六段 → 挂 file-prefetch(仓库 localPath)+kb(清单页) → 批准 → executing。 */
 export declare function handleOpenspecRoute(message: string, service: KanbanService, cfg: PrefixRoutes, planning: OpenspecPlanningInput, ownerSessionId: string): Promise<PrefixRouteResult>;
-/** /learning 零副作用引导文案：命令串从 config 派生（决策12），歧义/未找到时注入主 agent。 */
+/** /learning 零副作用引导文案：命令串从 config 派生，歧义/未找到时注入主 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

@@ -11,6 +11,8 @@ export function parsePrefix(message, cfg) {
         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() };
+    if (trimmed.startsWith(cfg.send))
+        return { kind: 'send', rest: trimmed.slice(cfg.send.length).trim() };
     return { kind: 'none', rest: trimmed };
 }
 /** v2：/plan: 零副作用——不建链/规格卡/任务卡，仅返回路由结果（workspaceDir/sessionId 由 main-session-tools 捕获）。 */
@@ -64,7 +66,7 @@ async function waitFirstCard(service, chainId) {
         await new Promise((r) => setTimeout(r, Math.min(OPENSPEC_FIRST_CARD.pollIntervalMs, Math.max(1, deadline - Date.now()))));
     }
 }
-/** /learning 零副作用引导文案：命令串从 config 派生（决策12），歧义/未找到时注入主 agent。 */
+/** /learning 零副作用引导文案：命令串从 config 派生，歧义/未找到时注入主 agent。 */
 export function buildLearningGuidance(routes) {
     return [
         '## 经验蒸馏指令（' + routes.learning + '）',

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

@@ -31,10 +31,6 @@ export declare class ConfigProvider extends Service {
         sources: SourceMap;
     };
     applyOverride(snapshot: EditableSnapshot): ApplyResult;
-    reset(): {
-        effective: EditableSnapshot;
-        sources: SourceMap;
-    };
     private readOverride;
     private writeOverride;
     private appendAudit;

package/lib/services/config-provider.js

@@ -20,7 +20,7 @@ export class ConfigProvider extends Service {
     }
     getEffective() { return this.effective; }
     getSources() { return this.sources; }
-    // mode 派生自 effective.wikiVault.baseUrl；运行期改 baseUrl 需重启 dsh 使客户端注册面同步（D11 不可热切换）：
+    // mode 派生自 effective.wikiVault.baseUrl；运行期改 baseUrl 需重启 dsh 使客户端注册面同步（不可热切换）：
     // 注册期冻结（dispatcher、main-session-tools 客户端构造）与运行期活读（agent-runner guard、kanban-provider 交付闸）
     // 分属两类读取点，中途 applyOverride 改 baseUrl 会产生混合态（后果 fail-closed 可见，不静默）。
     get mode() { return (this.effective.wikiVault?.baseUrl ?? '').trim() ? 'remote' : 'local'; }
@@ -41,14 +41,6 @@ export class ConfigProvider extends Service {
         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))
@@ -89,6 +81,12 @@ export class ConfigProvider extends Service {
                     keys.add(`roles.models.${role}.${f}`);
             }
         }
+        if (prev.reviewEngine?.mode !== next.reviewEngine?.mode)
+            keys.add('reviewEngine.mode');
+        for (const f of ['provider', 'model']) {
+            if (prev.reviewEngine?.managed?.[f] !== next.reviewEngine?.managed?.[f])
+                keys.add('reviewEngine.managed.' + f);
+        }
         return [...keys];
     }
 }

package/lib/services/im-delivery.d.ts

@@ -0,0 +1,94 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { KanbanService } from '../domain/kanban-service.js';
+import type { BoardState } from '../domain/types.js';
+import type { ConfigProvider } from './config-provider.js';
+/** dsh-im 宿主服务结构接口（形状以 @xmanrui/dsh-im PROACTIVE_DELIVERY.md 为准，运行时守卫校验）。
+ *  listTargets 证据（2026-09-07）：PROACTIVE_DELIVERY.md:176 `const targets = await ctx.dshIm.listTargets(botId);
+ *  // [{ targetId, name?, kind, route }, ...]`；宿主 lib/index.js 实现为
+ *  `listTargets: async Y => (await H.listTargets(Y)).targets`（同 Host 服务返回裸数组）。
+ *  `{ botId, channel, targets }` 是 Connection RPC `target.list` 的信封形状，与同 Host 服务不同。 */
+export interface DshImLike {
+    send(botId: string, targetId: string, text: string, opts?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        sent?: boolean;
+    }>;
+    listBots(): Promise<Array<{
+        botId: string;
+        channel: string;
+    }>>;
+    listTargets(botId: string): Promise<Array<{
+        targetId: string;
+        name?: string;
+        kind: string;
+        route: Record<string, string>;
+    }>>;
+}
+export interface ImDeliveryOptions {
+    /** 缺省写 storageDir/dispatcher.log（[im-delivery] 前缀；评审决议落盘位置）。 */
+    log?: (msg: string) => void;
+    /** 重试退避间隔（ms）；测试传 [0,0,0]。 */
+    retryDelaysMs?: number[];
+    /** 手动投递路径（/sms）：失败仅 dispatcher.log 留痕，不写 chain/im-delivery-failed 链事件（用户同步可见错误）。 */
+    manual?: boolean;
+}
+export declare function isDshImLike(svc: unknown): svc is DshImLike;
+/** botId/targetId 解析（评审决议）：配置显式指定优先；留空自动发现唯一 wecom bot + 唯一已保存群目标；
+ *  发现异常返回 error（调用方留痕不投，fail-closed——投错群比不投更糟）。 */
+export declare function resolveTarget(im: DshImLike, cfg: {
+    botId: string;
+    targetId: string;
+}): Promise<{
+    botId: string;
+    targetId: string;
+} | {
+    error: string;
+}>;
+/** 发送 + 退避重试（仅可重试错误码；{sent:true} 即停——dsh-im 无幂等，成功后绝不重发）。 */
+export declare function sendWithRetry(im: DshImLike, botId: string, targetId: string, text: string, delays: number[], log: (m: string) => void): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+}>;
+/** 发送器工厂：resolveDshIm → resolveTarget（fail-closed）→ sendWithRetry → 留痕。
+ *  auto 路径（wireImDelivery）失败额外写 chain/im-delivery-failed 链事件；
+ *  manual 路径（/sms，opts.manual）仅 dispatcher.log 留痕，错误同步返回给调用方。 */
+export declare function createSender(ctx: Context, kanban: KanbanService, configProvider: ConfigProvider, opts?: ImDeliveryOptions): (chainId: string, text: string) => Promise<{
+    ok: true;
+    botId: string;
+    targetId: string;
+} | {
+    ok: false;
+    error: string;
+}>;
+export type ReportVariant = 'completion' | 'blocked';
+/** /sms 链解析（纯函数）。空 query：completion=最近满足 W3 完成判据的链（最后完成事件 at 最大）；
+ *  blocked=最近阻塞的链（chain/blocked 事件 at 最大）。显式 query：全量链精确/后缀解析后再验判据。 */
+export declare function resolveReportChainId(state: BoardState, variant: ReportVariant, query: string): {
+    ok: true;
+    chainId: string;
+} | {
+    ok: false;
+    error: string;
+    candidates?: Array<{
+        chainId: string;
+        title: string;
+    }>;
+};
+/** /sms 手动投递：解析链 → 领域函数渲染正文（红线：正文只出自 buildCompletionMessage/buildBlockMessage，
+ *  绝不返回给模型）→ createSender 发送。不受 imDelivery.enabled 门控（显式人工调用即意图），
+ *  但仍要求 dshIm 服务在位且形状合法、目标可解析（同 auto 路径 fail-closed 规则）。 */
+export declare function sendChainReport(ctx: Context, kanban: KanbanService, configProvider: ConfigProvider, opts: ImDeliveryOptions, variant: ReportVariant, query: string): Promise<{
+    ok: true;
+    chainId: string;
+    botId: string;
+    targetId: string;
+} | {
+    ok: false;
+    error: string;
+    guidance?: string;
+}>;
+/** 接线：订阅看板事件多播通道（不动 setOnTaskCompleted 单消费者钩子）。
+ *  listener 同步返回，投递全程 fire-and-forget 自兜异常（publish 在 emit 队列内同步调用，不得拖慢落盘）。 */
+export declare function wireImDelivery(ctx: Context, kanban: KanbanService, configProvider: ConfigProvider, opts?: ImDeliveryOptions): () => void;