@joekytc/dsh-swarm 0.3.2 → 0.3.6

package/lib/domain/projection.js

@@ -13,7 +13,8 @@ export function applyTo(state, ev) {
         case 'chain/executing':
         case 'chain/completed':
         case 'chain/aborted':
-        case 'chain/blocked': {
+        case 'chain/blocked':
+        case 'chain/reopened': {
             const c = state.chains.get(ev.chainId);
             if (!c)
                 throw new Error('projection: unknown chain ' + ev.chainId);
@@ -128,12 +129,16 @@ export function applyTo(state, ev) {
         // 评审事件（交付质量链）：非状态转换——按 payload.targetTaskId 更新被评审任务 reviewStatus
         case 'review/passed':
         case 'review/failed':
-        case 'review/gave-up': {
+        case 'review/gave-up':
+        case 'review/waived': {
             const targetId = String(ev.payload['targetTaskId'] ?? '');
             const t = state.tasks.get(targetId);
             if (!t)
                 throw new Error('projection: unknown review target ' + targetId);
-            const status = ev.kind === 'review/passed' ? 'passed' : ev.kind === 'review/failed' ? 'failed' : 'gave-up';
+            const status = ev.kind === 'review/passed' ? 'passed'
+                : ev.kind === 'review/failed' ? 'failed'
+                    : ev.kind === 'review/waived' ? 'waived'
+                        : 'gave-up';
             next.tasks = new Map(state.tasks).set(targetId, { ...t, reviewStatus: status });
             break;
         }

package/lib/domain/review-evidence.js

@@ -20,6 +20,15 @@ export function validateReviewEvidence(role, handoff) {
         missing.push('review_evidence.verdict');
     if (!Array.isArray(ev.issues))
         missing.push('review_evidence.issues');
+    // 2026-09-15 口径锁死（P1-7，仅 PT）：fail 必须至少一条未解决的 critical/high——
+    // persona 口径「fail = 存在 critical/high」机械落地，防 medium 冒充阻断（ch_1_mu235xfz R3 summary 实录）。
+    // 全为非阻断项时应输出 pass（issues 作为非阻塞建议留档）。DT 不适用：其实证失败（test/build/diff）
+    // 未必伴随 high issue，用 severity 门槛会误放行真问题。
+    if (role === 'pt' && ev.verdict === 'fail' && Array.isArray(ev.issues)) {
+        const blocking = ev.issues.some((i) => i.resolved !== true && (i.severity === 'critical' || i.severity === 'high'));
+        if (!blocking)
+            missing.push('review_evidence.issues (verdict=fail 需至少一条未解决的 critical/high；否则应判 pass)');
+    }
     if (role === 'pt') {
         // 计划结构字段：评审须给出被评审计划产物引用（如 artifacts_path/page 结构）——缺则视为证据不足
         const planRef = ev.reviewPage ?? (handoff.metadata ?? {})['artifacts_path'];

package/lib/domain/review-target.d.ts

@@ -0,0 +1,10 @@
+import type { BoardState, Task } from './types.js';
+/** 评审目标推导（PT/DT 共用，2026-09-15 由 v-orchestrator 内联逻辑下沉）：
+ *  - currentTarget = 该评审卡实际评审的任务（复审卡经 reworkOfTaskId 指向返工卡；首评回退 parents[0] → 阶段源任务）；
+ *  - root = 沿 reworkOfTaskId 链到顶（原任务），reviewStatus 落点。
+ *  返回 null = 无法推导（调用方按原语义处理，如 gave-up）。
+ *  编排层与恢复 service 共用同一份推导，消除双份逻辑漂移。 */
+export declare function resolveReviewTarget(state: BoardState, reviewTask: Task, chainId: string): {
+    currentTarget: Task;
+    root: Task;
+} | null;

package/lib/domain/review-target.js

@@ -0,0 +1,24 @@
+/** 评审目标推导（PT/DT 共用，2026-09-15 由 v-orchestrator 内联逻辑下沉）：
+ *  - currentTarget = 该评审卡实际评审的任务（复审卡经 reworkOfTaskId 指向返工卡；首评回退 parents[0] → 阶段源任务）；
+ *  - root = 沿 reworkOfTaskId 链到顶（原任务），reviewStatus 落点。
+ *  返回 null = 无法推导（调用方按原语义处理，如 gave-up）。
+ *  编排层与恢复 service 共用同一份推导，消除双份逻辑漂移。 */
+export function resolveReviewTarget(state, reviewTask, chainId) {
+    const role = reviewTask.assignee === 'dt' ? 'dt' : 'pt';
+    const srcAssignee = role === 'pt' ? 'p' : 'd';
+    const srcMode = role === 'pt' ? 'openspec' : 'execute';
+    let currentTarget = reviewTask.reworkOfTaskId
+        ? state.tasks.get(reviewTask.reworkOfTaskId)
+        : reviewTask.parents[0]
+            ? state.tasks.get(reviewTask.parents[0])
+            : undefined;
+    if (!currentTarget) {
+        currentTarget = [...state.tasks.values()].find((t) => t.chainId === chainId && t.assignee === srcAssignee && t.mode === srcMode && t.status === 'done');
+    }
+    if (!currentTarget)
+        return null;
+    let root = currentTarget;
+    while (root.reworkOfTaskId && state.tasks.get(root.reworkOfTaskId))
+        root = state.tasks.get(root.reworkOfTaskId);
+    return { currentTarget, root };
+}

package/lib/domain/state-machine.js

@@ -11,7 +11,7 @@ const TASK_TRANSITIONS = {
 const CHAIN_TRANSITIONS = {
     planning: { 'chain/executing': 'executing' },
     executing: { 'chain/completed': 'completed', 'chain/aborted': 'aborted', 'chain/blocked': 'blocked' },
-    blocked: {},
+    blocked: { 'chain/reopened': 'executing' }, // 人工恢复唯一出边（其余事件对 blocked 仍非法）
     completed: {},
     aborted: {},
 };

package/lib/domain/types.d.ts

@@ -3,8 +3,8 @@ export type TaskMode = 'file' | 'external' | 'kb' | 'openspec' | 'mattpocock' |
 export type TaskStatus = 'triage' | 'todo' | 'ready' | 'running' | 'blocked' | 'done' | 'failed' | 'archived';
 export type ChainStatus = 'planning' | 'executing' | 'blocked' | 'completed' | 'aborted';
 export type SpecCardStatus = 'draft' | 'approved';
-/** 评审状态（交付质量链）：not-required 普通卡 / pending 等待评审 / passed 通过 / failed 失败待返工 / gave-up 超限放弃。 */
-export type ReviewStatus = 'not-required' | 'pending' | 'passed' | 'failed' | 'gave-up';
+/** 评审状态（交付质量链）：not-required 普通卡 / pending 等待评审 / passed 通过 / failed 失败待返工 / gave-up 超限放弃 / waived 人工豁免。 */
+export type ReviewStatus = 'not-required' | 'pending' | 'passed' | 'failed' | 'gave-up' | 'waived';
 /** 评审结论：pass=通过 / fail=不通过。 */
 export type ReviewVerdict = 'pass' | 'fail';
 /** 评审问题条目（PT/DT 交接 evidence.issues）。 */
@@ -14,6 +14,14 @@ export interface ReviewIssue {
     detail: string;
     location?: string;
     resolved: boolean;
+    /** 依据（上游声明引用或计划内部矛盾点）——评审方运行时扩展字段，注入返工时保留。 */
+    basis?: string;
+    /** 问题说明（违反什么）。 */
+    problem?: string;
+    /** 可执行修改建议（怎么改）——返工方最需要的字段。 */
+    fix?: string;
+    /** 对账标记：true=上一轮遗留 issue 的对账条目；false/缺省=本轮新问题。收敛闸据此判定旧账是否清零（漏标=false=视为新问题，方向安全）。 */
+    legacy?: boolean;
 }
 /** TDD 硬要求证据（评审时收集的测试相关元信息）。 */
 export interface TddEvidence {
@@ -27,6 +35,11 @@ export interface TddEvidence {
 export interface ReviewEvidence {
     verdict: ReviewVerdict;
     issues: ReviewIssue[];
+    /** 收敛闸降级留痕（2026-09-15）：verdict 由 fail 降级为 pass 时记录原判定与原因，审计可查。 */
+    downgraded?: {
+        from: ReviewVerdict;
+        reason: string;
+    };
     tdd?: TddEvidence;
     test?: Record<string, unknown>;
     build?: Record<string, unknown>;
@@ -40,7 +53,7 @@ export interface ReviewEvidence {
         kbUrl: string;
     };
 }
-export type EventKind = 'chain/created' | 'chain/executing' | 'chain/completed' | 'chain/aborted' | 'chain/blocked' | 'chain/root-task-set' | 'chain/audit-warning' | 'chain/audit-confirmed' | 'chain/title-updated' | 'chain/im-delivery-failed' | 'spec-card/created' | 'spec-card/edited' | 'spec-card/approved' | 'task/created' | 'task/claimed' | 'task/heartbeat' | 'task/commented' | 'task/completed' | 'task/blocked' | 'task/unblocked' | 'task/archived' | 'task/gate-passed' | 'task/gate-failed' | 'task/failed' | 'task/renamed' | 'review/passed' | 'review/failed' | 'review/gave-up';
+export type EventKind = 'chain/created' | 'chain/executing' | 'chain/completed' | 'chain/aborted' | 'chain/blocked' | 'chain/root-task-set' | 'chain/audit-warning' | 'chain/audit-confirmed' | 'chain/title-updated' | 'chain/im-delivery-failed' | 'spec-card/created' | 'spec-card/edited' | 'spec-card/approved' | 'task/created' | 'task/claimed' | 'task/heartbeat' | 'task/commented' | 'task/completed' | 'task/blocked' | 'task/unblocked' | 'task/archived' | 'task/gate-passed' | 'task/gate-failed' | 'task/failed' | 'task/renamed' | 'review/passed' | 'review/failed' | 'review/gave-up' | 'review/waived' | 'chain/reopened';
 export interface SpecCardSections {
     problem: string;
     solution: string;

package/lib/routes/kanban-http.js

@@ -5,6 +5,7 @@ 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';
+import { resolveReviewTarget } from '../domain/review-target.js';
 function json(res, status, body) {
     res.statusCode = status;
     res.setHeader('content-type', 'application/json; charset=utf-8');
@@ -170,6 +171,25 @@ export function registerKanbanHttp(ctx, provider, configProvider, llm, config, o
                         json(res, 200, { ok: true });
                         return;
                     }
+                    // 人工恢复被 blocked 的链（2026-09-15 恢复能力，仅 human）：链级 action，在 taskId 守卫前分流。
+                    // 非 blocked 链 → 409（fail-closed）；reason 必填（审计留痕）。
+                    if (body.type === 'reopen-chain') {
+                        const chainId = String(body.chainId ?? '').trim();
+                        const reason = String(body.reason ?? '').trim();
+                        if (!chainId || !reason) {
+                            json(res, 400, { error: 'chainId and reason required' });
+                            return;
+                        }
+                        try {
+                            await provider.service.reopenChain(chainId, reason, 'human');
+                        }
+                        catch (err) {
+                            json(res, 409, { error: String(err instanceof Error ? err.message : err) });
+                            return;
+                        }
+                        json(res, 200, { ok: true });
+                        return;
+                    }
                     // rename 是链级或任务级 action（chainId 或 taskId 二选一），在 taskId 守卫前分流
                     if (body.type === 'rename') {
                         const title = String(body.title ?? '').trim();
@@ -206,6 +226,34 @@ export function registerKanbanHttp(ctx, provider, configProvider, llm, config, o
                         case 'unblock':
                             await provider.service.unblockTask(t, 'human');
                             break;
+                        case 'waive-review': {
+                            // 人工评审豁免（2026-09-15 恢复能力，仅 human）：目标根卡由 resolveReviewTarget 推导
+                            //（评审卡→返工链→root），前端无需重复实现；非 failed/gave-up 目标 → 409（防误豁免）。
+                            const reason = String(body.reason ?? '').trim();
+                            if (!reason) {
+                                json(res, 400, { error: 'reason required' });
+                                return;
+                            }
+                            const state = await provider.service.snapshot();
+                            const reviewTask = state.tasks.get(t);
+                            if (!reviewTask) {
+                                json(res, 404, { error: 'unknown task: ' + t });
+                                return;
+                            }
+                            const target = resolveReviewTarget(state, reviewTask, reviewTask.chainId);
+                            if (!target) {
+                                json(res, 409, { error: 'review target not resolvable for ' + t });
+                                return;
+                            }
+                            try {
+                                await provider.service.waiveReview(t, target.root.id, reason, 'human');
+                            }
+                            catch (err) {
+                                json(res, 409, { error: String(err instanceof Error ? err.message : err) });
+                                return;
+                            }
+                            break;
+                        }
                         case 'retry': {
                             // retry 走 runner（failed→claim→spawn/resume），而非只 claim 造成 running 悬挂
                             const state = await provider.service.snapshot();
@@ -260,8 +308,9 @@ export function registerKanbanHttp(ctx, provider, configProvider, llm, config, o
                 if (req.method === 'PUT' && req.url?.startsWith('/kanban/config')) {
                     const raw = JSON.parse((await readBody(req)) || '{}');
                     // 归一化缺省字段，保证缺字段走 400 校验失败而非 500。
-                    // reviewEngine 缺省时回退当前 effective（再兜底默认）：旧客户端 bundle 不带该字段时保存不清空既有评审引擎配置。
-                    const fb = configProvider.getEffective().reviewEngine;
+                    // reviewEngine/imDelivery 缺省时回退当前 effective（再兜底默认）：旧客户端 bundle 不带这些字段时保存不清空既有配置。
+                    const cur = configProvider.getEffective();
+                    const fb = cur.reviewEngine;
                     const snapshot = {
                         wikiVault: { baseUrl: raw.wikiVault?.baseUrl ?? '', pagePrefix: raw.wikiVault?.pagePrefix ?? '' },
                         roles: { models: raw.roles?.models ?? {} },
@@ -272,6 +321,7 @@ export function registerKanbanHttp(ctx, provider, configProvider, llm, config, o
                                 model: raw.reviewEngine?.managed?.model ?? fb?.managed?.model ?? '',
                             },
                         },
+                        imDelivery: { fallbackBotId: raw.imDelivery?.fallbackBotId ?? cur.imDelivery?.fallbackBotId ?? '' },
                     };
                     const r = configProvider.applyOverride(snapshot);
                     if (!r.ok) {

package/lib/services/config-provider.js

@@ -87,6 +87,8 @@ export class ConfigProvider extends Service {
             if (prev.reviewEngine?.managed?.[f] !== next.reviewEngine?.managed?.[f])
                 keys.add('reviewEngine.managed.' + f);
         }
+        if ((prev.imDelivery?.fallbackBotId ?? '') !== (next.imDelivery?.fallbackBotId ?? ''))
+            keys.add('imDelivery.fallbackBotId');
         return [...keys];
     }
 }

package/lib/services/im-bot-probe.d.ts

@@ -0,0 +1,36 @@
+/** 一个企微机器人的探针视图（字段取自 connection.status 的 bots[]，缺失值归一为空/离线）。 */
+export interface BotCandidate {
+    botId: string;
+    /** 该机器人的默认 dsh 模式（dsh-im 设置页的 agentPreset）；未设置时为空串。 */
+    agentPreset: string;
+    connected: boolean;
+    /** 展示名（appIdMasked，脱敏 id），仅用于交互提示。 */
+    label: string;
+}
+export type ProbeResult = {
+    ok: true;
+    bots: BotCandidate[];
+} | {
+    ok: false;
+    error: string;
+};
+/** 探针依赖（全部注入，便于测试与惰性读取）。 */
+export interface ProbeDeps {
+    /** 监听端口；未就绪（webServer 未挂载/未 listen）返回 null。 */
+    port: () => number | null;
+    /** 进程 token 换 cookie 的入口（ctx.connection.authenticatedUrl）；服务缺失返回 null。 */
+    authenticatedUrl: (base: string) => string | null;
+    fetchImpl: typeof fetch;
+    /** 时钟（缓存 TTL 测试用）。 */
+    now?: () => number;
+}
+/** connection.status 响应信封 → 候选数组。形状不符返回 null（上游改形状即降级，不猜字段）。 */
+export declare function parseBotCandidates(raw: unknown): BotCandidate[] | null;
+/** Set-Cookie 头 → `name=value` 片段（剥属性）。无 dsh-auth 前缀项返回 null。 */
+export declare function pickAuthCookie(lines: readonly string[]): string | null;
+/** 探针工厂：同一实例内结果短期缓存（连发 /sms 不重复握手），失败同样缓存以免每次重试打满超时。 */
+export declare function createBotProbe(deps: ProbeDeps): () => Promise<ProbeResult>;
+/** 从 cordis ctx 装配探针依赖（惰性：每次调用才读端口与 connection，避免 apply 期缓存未就绪的值）。 */
+export declare function probeDepsFromCtx(ctx: {
+    get(name: string): unknown;
+}): ProbeDeps;

package/lib/services/im-bot-probe.js

@@ -0,0 +1,128 @@
+// src/services/im-bot-probe.ts
+// 多机器人消歧探针：读 dsh-im 侧每个企微机器人的 agentPreset（默认 dsh 模式）与连接态。
+//
+// 数据源是 dsh-im 的管理 RPC `/wecom/connection.status`（WECOM_ENDPOINTS.status）。该通道只对浏览器开放
+// （loopback authority + dsh-auth cookie），宿主插件侧没有本地 invoke 面（HostConnectionRpc 只有
+// handle/intercept），故这里走「进程 token 换 cookie 再自调用」的公开路径：
+//   ctx.connection.authenticatedUrl(base) → GET `/` 拿 Set-Cookie → 带 cookie POST 该 RPC。
+// launchToken 只存在于进程内存（WeakMap），不落盘；cookie 是自包含 HMAC，重铸成本极低。
+//
+// 红线（本模块唯一允许接触 cookie 的地方）：
+//   1. cookie / token / URL / 请求头绝不进任何日志、错误消息或链事件（dispatcher.log 与 events.jsonl 都长期留盘）；
+//   2. 探针失败一律降级（返回 {ok:false}），绝不让投递整体失败——调用方退化到默认机器人/交互选择；
+//   3. 上游改 RPC 形状 → parseBotCandidates 返回 null → fail-closed 同样走降级，不静默投错对象。
+const PROBE_TIMEOUT_MS = 1_500;
+const CACHE_TTL_MS = 30_000;
+const STATUS_PATH = '/wecom/connection.status';
+const COOKIE_PREFIX = 'dsh-auth-';
+/** connection.status 响应信封 → 候选数组。形状不符返回 null（上游改形状即降级，不猜字段）。 */
+export function parseBotCandidates(raw) {
+    const bots = raw?.result?.value?.bots;
+    if (!Array.isArray(bots))
+        return null;
+    const out = [];
+    for (const entry of bots) {
+        const botId = entry?.botId;
+        if (typeof botId !== 'string' || !botId)
+            return null;
+        const preset = entry.agentPreset;
+        const label = entry?.bot?.appIdMasked;
+        out.push({
+            botId,
+            agentPreset: typeof preset === 'string' ? preset : '',
+            connected: entry.connected === true,
+            label: typeof label === 'string' ? label : '',
+        });
+    }
+    return out;
+}
+/** Set-Cookie 头 → `name=value` 片段（剥属性）。无 dsh-auth 前缀项返回 null。 */
+export function pickAuthCookie(lines) {
+    for (const line of lines) {
+        const pair = line.split(';')[0]?.trim() ?? '';
+        if (pair.startsWith(COOKIE_PREFIX))
+            return pair;
+    }
+    return null;
+}
+function setCookieLines(headers) {
+    const multi = headers.getSetCookie?.();
+    if (Array.isArray(multi) && multi.length > 0)
+        return multi;
+    const single = headers.get('set-cookie');
+    return single ? [single] : [];
+}
+/** 错误归一：只取错误码/名，绝不带 URL、请求头或 cookie（日志红线）。 */
+function errorCode(err) {
+    const code = err?.code;
+    if (typeof code === 'string' && code)
+        return code;
+    const name = err?.name;
+    return typeof name === 'string' && name ? name : 'probe-failed';
+}
+async function runProbe(deps) {
+    const port = deps.port();
+    if (typeof port !== 'number' || !Number.isInteger(port) || port <= 0) {
+        return { ok: false, error: 'probe-unavailable: web-server-port' };
+    }
+    const base = `http://127.0.0.1:${port}`;
+    const exchangeUrl = deps.authenticatedUrl(`${base}/`);
+    if (!exchangeUrl)
+        return { ok: false, error: 'probe-unavailable: connection' };
+    const controller = new AbortController();
+    const timer = setTimeout(() => { controller.abort(); }, PROBE_TIMEOUT_MS);
+    try {
+        // 进程 token → cookie：GET 应用根，白拿 Set-Cookie（不跟随重定向，避免多一次无用请求）。
+        const index = await deps.fetchImpl(exchangeUrl, { redirect: 'manual', signal: controller.signal });
+        const cookie = pickAuthCookie(setCookieLines(index.headers));
+        if (!cookie)
+            return { ok: false, error: `probe-unauthorized: ${index.status}` };
+        const res = await deps.fetchImpl(base + STATUS_PATH, {
+            method: 'POST',
+            redirect: 'manual',
+            signal: controller.signal,
+            headers: { 'content-type': 'application/json', origin: base, cookie },
+            body: JSON.stringify({ type: 'client-request', rpcId: 'dsh-swarm-bot-probe', method: 'connection.status', payload: {} }),
+        });
+        if (!res.ok)
+            return { ok: false, error: `probe-http: ${res.status}` };
+        const bots = parseBotCandidates(await res.json());
+        if (bots === null)
+            return { ok: false, error: 'probe-shape-mismatch' };
+        return { ok: true, bots };
+    }
+    catch (err) {
+        return { ok: false, error: `probe-failed: ${errorCode(err)}` };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** 探针工厂：同一实例内结果短期缓存（连发 /sms 不重复握手），失败同样缓存以免每次重试打满超时。 */
+export function createBotProbe(deps) {
+    const now = deps.now ?? Date.now;
+    let cached = null;
+    return async () => {
+        if (cached && now() - cached.at < CACHE_TTL_MS)
+            return cached.result;
+        const result = await runProbe(deps);
+        cached = { at: now(), result };
+        return result;
+    };
+}
+/** 从 cordis ctx 装配探针依赖（惰性：每次调用才读端口与 connection，避免 apply 期缓存未就绪的值）。 */
+export function probeDepsFromCtx(ctx) {
+    return {
+        port: () => {
+            const ws = ctx.get('webServer');
+            return typeof ws?.port === 'number' ? ws.port : null;
+        },
+        authenticatedUrl: (base) => {
+            const conn = ctx.get('connection');
+            if (typeof conn?.authenticatedUrl !== 'function')
+                return null;
+            return conn.authenticatedUrl(base);
+        },
+        fetchImpl: ((...args) => fetch(...args)),
+    };
+}

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

@@ -2,6 +2,7 @@ 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';
+import { type ProbeResult } from './im-bot-probe.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 实现为
@@ -33,17 +34,73 @@ export interface ImDeliveryOptions {
     manual?: boolean;
     /** 投递目标类型（0.3.x 自由投递）：group=群聊；user=私聊（仅且只有一个已保存目标）。缺省 group。 */
     targetKind?: 'group' | 'user';
+    /** 手动投递会话的 preset（工具从 session header 注入）：多机器人时用于匹配机器人默认模式。
+     *  缺省=无 preset（auto 路径无会话上下文），跳过模式匹配直接走默认/交互。 */
+    sessionPreset?: string;
+    /** 手动投递会话的 live agent（工具从 exec.agent 注入）：userQuestions 的 GUI answerer 挂在
+     *  Agent-scoped waterfall 上，不传 agent 的询问落在根 ctx 无人应答（NO_PROVIDER）。 */
+    agent?: unknown;
+    /** 测试注入：覆盖机器人决策链的探针/交互/写默认实现（生产由 ctx 与 configProvider 装配）。 */
+    botChoice?: Partial<BotChoiceDeps>;
 }
 /** dsh-im 未安装的可识别错误前缀（0.3.1：缺插件属环境问题不重试，直接友好提醒安装）。 */
 export declare const DSH_IM_MISSING_PREFIX = "dsh-im-not-installed";
 export declare const DSH_IM_MISSING_GUIDANCE = "\u672A\u68C0\u6D4B\u5230 dsh-im \u63D2\u4EF6\uFF0C\u65E0\u6CD5\u6295\u9012\u4F01\u5FAE\u6D88\u606F\u3002\u8BF7\u5148\u5B89\u88C5\u5E76\u542F\u7528 @xmanrui/dsh-im \u63D2\u4EF6\uFF08\u5B89\u88C5\u540E\u91CD\u542F dsh \u751F\u6548\uFF09\uFF0C\u518D\u91CD\u8BD5\u6295\u9012\u3002";
 export declare function isDshImLike(svc: unknown): svc is DshImLike;
-/** botId/targetId 解析（评审决议）：配置显式指定优先；留空自动发现唯一 wecom bot + 唯一已保存目标（按 kind）。
- *  群/私聊各自仅且只有一个——发现异常返回 error（调用方留痕不投，fail-closed——投错对象比不投更糟）。 */
+/** 机器人来源（供调用方在 guidance 里如实转述，勿让模型猜）。 */
+export type BotVia = 'explicit' | 'single' | 'preset' | 'fallback' | 'interactive';
+export interface BotAskOption {
+    botId: string;
+    label: string;
+}
+export interface BotChoiceDeps {
+    /** 当前会话 preset（手动投递由工具从 session header 注入）；null/空 = 无法模式匹配（auto 路径）。 */
+    sessionPreset: string | null;
+    /** 多机器人时读 bot↔preset/连接态；失败=降级（不阻断投递，退化到默认/交互）。 */
+    probe: () => Promise<ProbeResult>;
+    /** 交互选择；无询问通道返回 null，用户取消/超时也返回 null（fail-closed 不投）。 */
+    ask: ((options: BotAskOption[]) => Promise<{
+        botId: string;
+        setDefault: boolean;
+    } | null>) | null;
+    /** 写默认机器人；写失败返回 false（本次投递照常，仅默认未落库）。 */
+    setFallback: ((botId: string) => Promise<boolean>) | null;
+    log: (m: string) => void;
+}
+export interface BotChoice {
+    botId: string;
+    via: BotVia;
+    fallbackSaved?: boolean;
+}
+/** 机器人决策链：显式配置 → 唯一机器人 → 会话 preset 命中 → 默认机器人 → 交互选择。
+ *  每环都 fail-closed（宁可不投也不投错对象）；探针不可用只失去自动匹配能力，不阻断投递。 */
+export declare function chooseBot(im: DshImLike, cfg: {
+    botId: string;
+    fallbackBotId?: string;
+}, deps: BotChoiceDeps): Promise<({
+    ok: true;
+} & BotChoice) | {
+    ok: false;
+    error: string;
+}>;
+/** targetId 解析：配置显式指定优先；留空自动发现该机器人下唯一已保存目标（按 kind）。
+ *  群/私聊各自仅且只有一个——发现异常返回 error（调用方留痕不投，fail-closed）。
+ *  机器人非显式指定（preset/默认/交互选出）而配置又填死了 targetId 时先校验归属：
+ *  targetId 是 per-bot 作用域，填错机器人只会落成 dsh-im 的 unknown-target，这里提前给可行动报错。 */
+export declare function resolveTargetId(im: DshImLike, botId: string, botIdExplicit: boolean, cfg: {
+    targetId: string;
+    dmTargetId?: string;
+}, kind: 'group' | 'user'): Promise<{
+    targetId: string;
+} | {
+    error: string;
+}>;
+/** botId+targetId 一步解析（无交互/无探针的简化入口，保留给单机器人场景与单测）。 */
 export declare function resolveTarget(im: DshImLike, cfg: {
     botId: string;
     targetId: string;
     dmTargetId?: string;
+    fallbackBotId?: string;
 }, kind: 'group' | 'user'): Promise<{
     botId: string;
     targetId: string;
@@ -57,17 +114,20 @@ export declare function sendWithRetry(im: DshImLike, botId: string, targetId: st
     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<{
+export type SendResult = {
     ok: true;
     botId: string;
     targetId: string;
+    via: BotVia;
+    fallbackSaved?: boolean;
 } | {
     ok: false;
     error: string;
-}>;
+};
+/** 发送器工厂：resolveDshIm → chooseBot（fail-closed）→ resolveTargetId → 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<SendResult>;
 export type ReportVariant = 'completion' | 'blocked';
 /** /sms 链解析（纯函数）。空 query：completion=最近满足 W3 完成判据的链（最后完成事件 at 最大）；
  *  blocked=最近阻塞的链（chain/blocked 事件 at 最大）。显式 query：全量链精确/后缀解析后再验判据。 */
@@ -99,6 +159,8 @@ export declare function sendChainReport(ctx: Context, kanban: KanbanService, con
     chainId: string;
     botId: string;
     targetId: string;
+    via: BotVia;
+    fallbackSaved?: boolean;
 } | {
     ok: false;
     error: string;