@joekytc/dsh-swarm 0.3.1 → 0.3.6

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;

package/lib/services/im-delivery.js

@@ -2,8 +2,13 @@ import { homedir } from 'node:os';
 import { writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { buildCompletionMessage, buildBlockMessage } from '../domain/im-message.js';
+import { createBotProbe, probeDepsFromCtx } from './im-bot-probe.js';
 const RETRYABLE_CODES = new Set(['bot-not-connected', 'delivery-failed']);
 const DEFAULT_RETRY_DELAYS_MS = [5_000, 10_000, 15_000];
+/** 机器人交互选择等待上限（5 分钟）：到点 abort 信号 + 竞速超时，按「未选择」fail-closed 不投。 */
+const ASK_TIMEOUT_MS = 300_000;
+/** 「设为默认」选项文案：提问与应答解析共用一处，改文案两处同步（字符串比对，无 id 兜底）。 */
+const ASK_SET_DEFAULT_LABEL = '设为默认';
 /** dsh-im 未安装的可识别错误前缀（0.3.1：缺插件属环境问题不重试，直接友好提醒安装）。 */
 export const DSH_IM_MISSING_PREFIX = 'dsh-im-not-installed';
 const DSH_IM_MISSING_ERROR = `${DSH_IM_MISSING_PREFIX}: 未检测到 dsh-im 插件服务，请先安装并启用 @xmanrui/dsh-im（安装后重启 dsh 生效）`;
@@ -23,35 +28,115 @@ function resolveDshIm(ctx, log) {
     }
     return svc;
 }
-/** botId/targetId 解析（评审决议）：配置显式指定优先；留空自动发现唯一 wecom bot + 唯一已保存目标（按 kind）。
- *  群/私聊各自仅且只有一个——发现异常返回 error（调用方留痕不投，fail-closed——投错对象比不投更糟）。 */
-export async function resolveTarget(im, cfg, kind) {
-    let botId = cfg.botId.trim();
-    if (!botId) {
-        const bots = await im.listBots();
-        const wecom = bots.filter((b) => b.channel === 'wecom');
-        if (wecom.length !== 1)
-            return { error: `企微机器人数量=${wecom.length}（期望 1），请在插件配置 imDelivery.botId 显式指定` };
-        botId = wecom[0].botId;
+/** 交互选项展示文案：脱敏名 + id（id 是唯一可靠标识，展示名可能重名）。 */
+function askLabel(o) {
+    return o.label ? `${o.label}（${o.botId}）` : o.botId;
+}
+/** 多机器人且无法自动决策时的 fail-closed 报错：列候选（有探针数据则带模式与连接态）。 */
+function botCandidatesError(ids, probed) {
+    const byId = new Map(probed.map((b) => [b.botId, b]));
+    const list = ids.map((id) => {
+        const c = byId.get(id);
+        if (!c)
+            return id;
+        return `${id}(${c.label || '未命名'}·${c.agentPreset || '未设模式'}${c.connected ? '' : '·离线'})`;
+    }).join(' / ');
+    return `企微机器人数量=${ids.length}（期望 1），无法自动确定投递对象。候选：${list}。请在插件配置 imDelivery.botId 显式指定，或在可交互的手动投递会话重试以选择`;
+}
+/** 机器人决策链：显式配置 → 唯一机器人 → 会话 preset 命中 → 默认机器人 → 交互选择。
+ *  每环都 fail-closed（宁可不投也不投错对象）；探针不可用只失去自动匹配能力，不阻断投递。 */
+export async function chooseBot(im, cfg, deps) {
+    const explicit = cfg.botId.trim();
+    if (explicit)
+        return { ok: true, botId: explicit, via: 'explicit' };
+    const wecom = (await im.listBots()).filter((b) => b.channel === 'wecom');
+    if (wecom.length === 0) {
+        return { ok: false, error: '未检测到企微机器人接入：请先在 dsh-im 设置→IM机器人 接入机器人后重试' };
     }
+    const ids = wecom.map((b) => b.botId);
+    if (ids.length === 1)
+        return { ok: true, botId: ids[0], via: 'single' };
+    const fallback = (cfg.fallbackBotId ?? '').trim();
+    const preset = (deps.sessionPreset ?? '').trim();
+    // 只有「能模式匹配」或「能交互」时才值得探针：纯自动路径 + 无默认 → 直接给候选报错，省一次握手。
+    const probed = (preset || deps.ask) ? await deps.probe() : { ok: false, error: 'probe-skipped' };
+    if (!probed.ok && (preset || deps.ask))
+        deps.log(`[im-delivery] bot probe unavailable: ${probed.error}`);
+    const candidates = probed.ok ? probed.bots.filter((b) => ids.includes(b.botId)) : [];
+    if (preset && candidates.length) {
+        const hit = candidates.filter((b) => b.connected && b.agentPreset === preset);
+        if (hit.length === 1)
+            return { ok: true, botId: hit[0].botId, via: 'preset' };
+        deps.log(hit.length > 1
+            ? `[im-delivery] preset ${preset} 命中 ${hit.length} 个已连接机器人，不唯一，转默认/交互`
+            : `[im-delivery] preset ${preset} 未命中已连接机器人（候选模式：${candidates.map((b) => b.agentPreset || '未设').join(', ') || '无元数据'}），转默认/交互`);
+    }
+    if (fallback && ids.includes(fallback))
+        return { ok: true, botId: fallback, via: 'fallback' };
+    if (fallback)
+        deps.log(`[im-delivery] 默认机器人 ${fallback} 不在接入列表，转交互`);
+    if (!deps.ask)
+        return { ok: false, error: botCandidatesError(ids, candidates) };
+    const options = ids.map((id) => {
+        const c = candidates.find((b) => b.botId === id);
+        if (!c)
+            return { botId: id, label: '' };
+        return { botId: id, label: `${c.label || '未命名'}·${c.agentPreset || '未设模式'}${c.connected ? '' : '·离线'}` };
+    });
+    const answer = await deps.ask(options);
+    if (!answer)
+        return { ok: false, error: '未选择投递机器人（交互取消或超时），本次不投递' };
+    if (!answer.setDefault || !deps.setFallback)
+        return { ok: true, botId: answer.botId, via: 'interactive' };
+    const saved = await deps.setFallback(answer.botId);
+    if (!saved)
+        deps.log('[im-delivery] 默认机器人写入失败（配置未更新），本次仍按所选机器人投递');
+    return { ok: true, botId: answer.botId, via: 'interactive', fallbackSaved: saved };
+}
+/** dsh-im 目标列表（宿主同 Host 服务返回裸数组；防御兼容 Connection RPC `target.list` 信封形状）。 */
+async function readTargets(im, botId) {
+    const raw = await im.listTargets(botId);
+    if (Array.isArray(raw))
+        return raw;
+    const enveloped = raw?.targets;
+    return Array.isArray(enveloped) ? enveloped : [];
+}
+/** targetId 解析：配置显式指定优先；留空自动发现该机器人下唯一已保存目标（按 kind）。
+ *  群/私聊各自仅且只有一个——发现异常返回 error（调用方留痕不投，fail-closed）。
+ *  机器人非显式指定（preset/默认/交互选出）而配置又填死了 targetId 时先校验归属：
+ *  targetId 是 per-bot 作用域，填错机器人只会落成 dsh-im 的 unknown-target，这里提前给可行动报错。 */
+export async function resolveTargetId(im, botId, botIdExplicit, cfg, kind) {
     const explicit = (kind === 'group' ? cfg.targetId : cfg.dmTargetId ?? '').trim();
-    let targetId = explicit;
-    if (!targetId) {
-        const raw = await im.listTargets(botId);
-        // 宿主同 Host 服务返回裸数组（PROACTIVE_DELIVERY.md:176）；防御兼容 Connection RPC `target.list` 信封形状。
-        const targets = Array.isArray(raw) ? raw : Array.isArray(raw?.targets)
-            ? raw.targets
-            : [];
-        const matched = targets.filter((x) => x.kind === kind);
-        const label = kind === 'group' ? '群目标' : '私聊目标';
-        const cfgHint = kind === 'group' ? 'imDelivery.targetId' : 'imDelivery.dmTargetId';
-        if (matched.length !== 1) {
-            const candidates = matched.length > 1 ? '，候选：' + matched.map((x) => `${x.targetId}${x.name ? `(${x.name})` : ''}`).join(' / ') : '';
-            return { error: `已保存${label}数量=${matched.length}（期望 1，仅且只有一个）${candidates}。请到 dsh-im 设置→IM机器人 ${matched.length > 1 ? '清理多余目标' : '新建目标'}或在插件配置 ${cfgHint} 显式指定` };
-        }
-        targetId = matched[0].targetId;
+    const label = kind === 'group' ? '群目标' : '私聊目标';
+    const cfgHint = kind === 'group' ? 'imDelivery.targetId' : 'imDelivery.dmTargetId';
+    if (explicit) {
+        if (botIdExplicit)
+            return { targetId: explicit };
+        const targets = await readTargets(im, botId);
+        const owned = targets.some((x) => x.targetId === explicit);
+        if (owned)
+            return { targetId: explicit };
+        return { error: `${cfgHint}=${explicit} 不属于本轮选定的机器人 ${botId}（targetId 按机器人隔离）。请清空该字段改由自动发现，或显式指定 imDelivery.botId 固定机器人` };
+    }
+    const targets = await readTargets(im, botId);
+    const matched = targets.filter((x) => x.kind === kind);
+    if (matched.length !== 1) {
+        const candidates = matched.length > 1 ? '，候选：' + matched.map((x) => `${x.targetId}${x.name ? `(${x.name})` : ''}`).join(' / ') : '';
+        return { error: `已保存${label}数量=${matched.length}（期望 1，仅且只有一个）${candidates}。请到 dsh-im 设置→IM机器人 ${matched.length > 1 ? '清理多余目标' : '新建目标'}或在插件配置 ${cfgHint} 显式指定` };
     }
-    return { botId, targetId };
+    return { targetId: matched[0].targetId };
+}
+/** botId+targetId 一步解析（无交互/无探针的简化入口，保留给单机器人场景与单测）。 */
+export async function resolveTarget(im, cfg, kind) {
+    const choice = await chooseBot(im, cfg, {
+        sessionPreset: null, probe: async () => ({ ok: false, error: 'probe-skipped' }), ask: null, setFallback: null, log: () => { },
+    });
+    if (!choice.ok)
+        return { error: choice.error };
+    const t = await resolveTargetId(im, choice.botId, cfg.botId.trim() !== '', cfg, kind);
+    if ('error' in t)
+        return t;
+    return { botId: choice.botId, targetId: t.targetId };
 }
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 /** 发送 + 退避重试（仅可重试错误码；{sent:true} 即停——dsh-im 无幂等，成功后绝不重发）。 */
@@ -88,13 +173,90 @@ function makeDefaultLog(storageDir) {
         catch { /* 忽略写失败 */ }
     };
 }
-/** 发送器工厂：resolveDshIm → resolveTarget（fail-closed）→ sendWithRetry → 留痕。
+/** 交互选择接线（仅手动投递路径）：两问一次弹——选机器人 + 是否设为默认。
+ *  agent 必传（exec.agent 的 live 实例）：GUI 弹窗按 agent 路由；无询问通道返回 null（调用方 fail-closed 列候选），
+ *  取消/超时/服务端拒绝同样返回 null（不投），失败原因进日志（只带错误码，不含任何敏感载荷）。 */
+function buildBotAsk(ctx, agent, log) {
+    const uq = ctx.get?.('userQuestions');
+    if (typeof uq?.ask !== 'function') {
+        log('[im-delivery] 机器人交互不可用：无 userQuestions 服务');
+        return null;
+    }
+    return async (options) => {
+        const controller = new AbortController();
+        const timer = setTimeout(() => { controller.abort(); }, ASK_TIMEOUT_MS);
+        try {
+            const ans = await Promise.race([
+                uq.ask({
+                    questions: [
+                        {
+                            id: 'im-bot',
+                            header: '投递机器人',
+                            question: '本轮企微投递用哪个机器人？（当前会话模式未匹配到任何机器人）',
+                            detail: '展示名·默认模式；离线机器人不保证能发出。选择只作用于本次投递。',
+                            options: options.map((o) => ({ label: askLabel(o), description: o.botId })),
+                        },
+                        {
+                            id: 'im-bot-default',
+                            header: '设为默认',
+                            question: '是否把所选机器人设为默认机器人？（之后模式未命中时直接使用，不再询问）',
+                            detail: '写入插件配置 imDelivery.fallbackBotId（可在设置面板看到来源标记）。',
+                            options: [{ label: ASK_SET_DEFAULT_LABEL }, { label: '仅本次' }],
+                        },
+                    ],
+                    ...(agent === undefined ? {} : { agent }),
+                    signal: controller.signal,
+                }),
+                new Promise((_, reject) => setTimeout(() => reject(new Error('im-bot-ask-timeout')), ASK_TIMEOUT_MS)),
+            ]);
+            const pick = ans.answers?.find((a) => a.id === 'im-bot');
+            const typed = pick?.custom?.trim() ?? '';
+            const selected = pick?.selected?.[0]?.trim() ?? '';
+            // 自由文本也接受，但必须是候选之一——防手写错 id 投到未知对象。
+            const botId = options.find((o) => askLabel(o) === selected || o.botId === selected || o.botId === typed)?.botId ?? '';
+            if (!botId) {
+                log('[im-delivery] 机器人交互已应答但未映射到候选（selected 与候选不符）');
+                return null;
+            }
+            const setDefault = (ans.answers?.find((a) => a.id === 'im-bot-default')?.selected ?? []).includes(ASK_SET_DEFAULT_LABEL);
+            return { botId, setDefault };
+        }
+        catch (err) {
+            const code = err.code;
+            const name = err.name;
+            log(`[im-delivery] 机器人交互未完成: ${typeof code === 'string' && code ? code : typeof name === 'string' && name ? name : 'unknown'}`);
+            return null;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    };
+}
+/** 写默认机器人接线：经 ConfigProvider.applyOverride 落 config-override.json + 审计留痕。 */
+function buildSetFallback(configProvider) {
+    return async (botId) => {
+        try {
+            const snap = configProvider.snapshot().effective;
+            return configProvider.applyOverride({ ...snap, imDelivery: { fallbackBotId: botId } }).ok;
+        }
+        catch {
+            return false;
+        }
+    };
+}
+/** 发送器工厂：resolveDshIm → chooseBot（fail-closed）→ resolveTargetId → sendWithRetry → 留痕。
  *  auto 路径（wireImDelivery）失败额外写 chain/im-delivery-failed 链事件；
  *  manual 路径（/sms，opts.manual）仅 dispatcher.log 留痕，错误同步返回给调用方。 */
 export function createSender(ctx, kanban, configProvider, opts = {}) {
     const log = opts.log ?? makeDefaultLog(deriveStorageDir(configProvider));
     const delays = opts.retryDelaysMs ?? DEFAULT_RETRY_DELAYS_MS;
     const targetKind = opts.targetKind ?? 'group';
+    // 探针单飞缓存挂在发送器上（连发 /sms 不重复握手）；交互与写默认只在手动路径接线（后台 auto 路径无人应答）。
+    const probe = opts.botChoice?.probe ?? createBotProbe(probeDepsFromCtx(ctx));
+    const ask = opts.botChoice?.ask !== undefined ? opts.botChoice.ask
+        : (opts.manual ? buildBotAsk(ctx, opts.agent, log) : null);
+    const setFallback = opts.botChoice?.setFallback !== undefined ? opts.botChoice.setFallback
+        : (opts.manual ? buildSetFallback(configProvider) : null);
     return async (chainId, text) => {
         const cfg = configProvider.getEffective().imDelivery;
         const im = resolveDshIm(ctx, log);
@@ -111,15 +273,22 @@ export function createSender(ctx, kanban, configProvider, opts = {}) {
             }
             return { ok: false, error: DSH_IM_MISSING_ERROR };
         }
-        const t = await resolveTarget(im, cfg, targetKind);
+        const choice = await chooseBot(im, cfg, {
+            sessionPreset: opts.sessionPreset ?? null, probe, ask, setFallback, log,
+        });
+        if (!choice.ok) {
+            log(`[im-delivery] bot resolve failed chain=${chainId}: ${choice.error}`);
+            return { ok: false, error: choice.error };
+        }
+        const t = await resolveTargetId(im, choice.botId, cfg.botId.trim() !== '', cfg, targetKind);
         if ('error' in t) {
             log(`[im-delivery] target resolve failed chain=${chainId}: ${t.error}`);
             return { ok: false, error: t.error };
         }
-        const r = await sendWithRetry(im, t.botId, t.targetId, text, delays, log);
+        const r = await sendWithRetry(im, choice.botId, t.targetId, text, delays, log);
         if (r.ok) {
-            log(`[im-delivery] delivered chain=${chainId} bot=${t.botId} target=${t.targetId}`);
-            return { ok: true, botId: t.botId, targetId: t.targetId };
+            log(`[im-delivery] delivered chain=${chainId} bot=${choice.botId} target=${t.targetId} via=${choice.via}`);
+            return { ok: true, botId: choice.botId, targetId: t.targetId, via: choice.via, ...(choice.fallbackSaved === undefined ? {} : { fallbackSaved: choice.fallbackSaved }) };
         }
         // 超限显形（评审决议）：dispatcher.log 留痕；auto 路径追加 events.jsonl 双留痕；投递失败绝不 block 链。
         log(`[im-delivery] FAILED chain=${chainId}: ${r.error}`);
@@ -266,7 +435,7 @@ export async function sendChainReport(ctx, kanban, configProvider, opts, variant
             ? { ok: false, error: r.error, guidance: DSH_IM_MISSING_GUIDANCE }
             : { ok: false, error: r.error };
     }
-    return { ok: true, chainId, botId: r.botId, targetId: r.targetId };
+    return { ok: true, chainId, botId: r.botId, targetId: r.targetId, via: r.via, ...(r.fallbackSaved === undefined ? {} : { fallbackSaved: r.fallbackSaved }) };
 }
 /** 接线：订阅看板事件多播通道（不动 setOnTaskCompleted 单消费者钩子）。
  *  listener 同步返回，投递全程 fire-and-forget 自兜异常（publish 在 emit 队列内同步调用，不得拖慢落盘）。 */
@@ -279,8 +448,9 @@ export function wireImDelivery(ctx, kanban, configProvider, opts = {}) {
             const cfg = configProvider.getEffective().imDelivery;
             if (!cfg?.enabled)
                 return; // 功能关闭：零开销早退（非异常，不留痕）
-            // 仅 task/completed（带 taskId）与 chain/blocked 关心事件流；其余早退，避免每个无关事件触发 snapshot 全量重放
-            if (!((ev.kind === 'task/completed' && ev.taskId) || ev.kind === 'chain/blocked'))
+            // 仅 task/completed（带 taskId）/ chain/blocked / review/gave-up 关心事件流；其余早退，避免每个无关事件触发 snapshot 全量重放。
+            // 2026-09-15：+ review/gave-up（评审超限待裁决）——不再静默等看门狗 block，人工在 gave-up 时刻即获通知与两条出口。
+            if (!((ev.kind === 'task/completed' && ev.taskId) || ev.kind === 'chain/blocked' || ev.kind === 'review/gave-up'))
                 return;
             const state = await kanban.snapshot();
             if (ev.kind === 'task/completed' && ev.taskId) {
@@ -295,6 +465,22 @@ export function wireImDelivery(ctx, kanban, configProvider, opts = {}) {
                 const msg = buildBlockMessage(state, ev.chainId, String(ev.payload['reason'] ?? ''), storageDir);
                 await deliver(ev.chainId, msg);
             }
+            else if (ev.kind === 'review/gave-up') {
+                const chain = state.chains.get(ev.chainId);
+                if (!chain)
+                    return;
+                const reviewTaskId = String(ev.payload['reviewTaskId'] ?? '');
+                const targetTaskId = String(ev.payload['targetTaskId'] ?? '');
+                const msg = [
+                    `【评审超限待裁决】${chain.title || ev.chainId} 的评审卡 ${reviewTaskId} 超限放弃（${String(ev.payload['reason'] ?? '')}）。`,
+                    `被评审卡：${targetTaskId}`,
+                    '两条出口：',
+                    '① 人工豁免评审 → 计划评审按通过继续（GUI 任务详情「豁免评审」按钮 / 主会话 kanban_waive_review）；',
+                    '② 人工恢复链后按需返工（GUI 链头「人工恢复」按钮 / 主会话 kanban_reopen_chain）。',
+                    '若无人处置，看门狗将在链持续无进展后把链置 blocked（届时可人工恢复）。',
+                ].join('\n');
+                await deliver(ev.chainId, msg);
+            }
         })().catch((err) => log('[im-delivery] handler failed ev=' + ev.kind + ': ' + String(err)));
     };
     return kanban.subscribe(handle);

package/lib/tools/kanban-tools.js

@@ -2,6 +2,7 @@ import { defineTool } from '@deepseek-ai/dsh-tools';
 import {} from '@deepseek-ai/dsh-util-values';
 import { KanbanService } from '../domain/kanban-service.js';
 import { can } from '../domain/permissions.js';
+import { resolveReviewTarget } from '../domain/review-target.js';
 function guard(action, caller, task = null) {
     if (!can(action, caller.actor, task))
         throw new Error('permission denied: ' + action);
@@ -92,7 +93,7 @@ export function buildKanbanTools(service, getCaller) {
             parameters: {
                 taskId: { type: 'string', required: true },
                 summary: { type: 'string', required: true, description: 'Human-readable completion summary' },
-                metadata: { type: 'json', description: 'Machine-readable handoff: changed_files/verification/kb_url...' },
+                metadata: { type: 'json', description: 'Machine-readable handoff: changed_files/verification/kb_url... W3/kb may add report = { requirement, status, branch, tasks: [{ text, done }], acceptance, verification, leftovers?, todos? } (delivery-report fields; tasks mirrors the OpenSpec plan checklist openspec/changes/<id>/tasks.md verbatim, done = checked)' },
             },
             output: { schema: { type: 'json' }, render: (_a, v) => [{ type: 'text', text: JSON.stringify(v) }] },
             async execute(args) {
@@ -166,5 +167,41 @@ export function buildKanbanTools(service, getCaller) {
                 return task;
             },
         }),
+        // 人工恢复能力（2026-09-15）：仅 human（caller.actor 由主会话/角色装配注入；角色工具面不暴露这两个工具）。
+        defineTool({
+            name: 'kanban_reopen_chain',
+            description: 'Reopen a blocked chain back to executing (human only; reason required).',
+            parameters: {
+                chainId: { type: 'string', required: true, description: 'Chain id (ch_xxx)' },
+                reason: { type: 'string', required: true, description: 'Recovery reason (audited)' },
+            },
+            output: { schema: { type: 'json' }, render: (_a, v) => [{ type: 'text', text: JSON.stringify(v) }] },
+            async execute(args) {
+                const caller = getCaller();
+                const ev = await service.reopenChain(args.chainId, args.reason, caller.actor);
+                return ev;
+            },
+        }),
+        defineTool({
+            name: 'kanban_waive_review',
+            description: 'Waive a failed/gave-up review card for its target task (human only; reason required).',
+            parameters: {
+                taskId: { type: 'string', required: true, description: 'Review card id (pt/dt card)' },
+                reason: { type: 'string', required: true, description: 'Waive reason (audited)' },
+            },
+            output: { schema: { type: 'json' }, render: (_a, v) => [{ type: 'text', text: JSON.stringify(v) }] },
+            async execute(args) {
+                const caller = getCaller();
+                const state = await service.snapshot();
+                const reviewTask = state.tasks.get(args.taskId);
+                if (!reviewTask)
+                    throw new Error('unknown review task: ' + args.taskId);
+                const target = resolveReviewTarget(state, reviewTask, reviewTask.chainId);
+                if (!target)
+                    throw new Error('review target not resolvable for ' + args.taskId);
+                const ev = await service.waiveReview(args.taskId, target.root.id, args.reason, caller.actor);
+                return ev;
+            },
+        }),
     ];
 }

package/lib/tools/main-session-tools.js

@@ -131,6 +131,16 @@ function buildFreeSendGuidance(routes, query, dm) {
         '投递结果只向用户确认成功与目标，不复述正文；失败时把 error/guidance 原样转告，勿编造原因。',
     ].join('\n');
 }
+/** 当前会话 preset（多机器人投递按它匹配机器人的默认 dsh 模式）。
+ *  header.agentPreset 缺省（用默认模式创建的会话可能不落该字段）→ 回落到 agentPresets.defaultId；
+ *  两者都拿不到返回空串，调用方按「无模式匹配」处理（走默认机器人/交互，绝不猜）。 */
+function sessionPresetOf(ctx, exec) {
+    const fromHeader = exec?.agent?.session?.header?.agentPreset;
+    if (typeof fromHeader === 'string' && fromHeader.trim())
+        return fromHeader.trim();
+    const presets = ctx.get?.('agentPresets');
+    return typeof presets?.defaultId === 'string' ? presets.defaultId : '';
+}
 /** v2 主会话工具面：/plan: 捕获规划上下文（零副作用）→ planning_checklist_save 回写 → /openspec: 建链。
  *  工具面 = kanban_route + 只读 kanban 子集 + spec_card_view + planning 工具；
  *  无 spec_card_edit/approve、无 kanban_create/complete/block（主会话越权写由工具面裁剪 + prefetch 子代理只读护栏双保险）。 */
@@ -150,8 +160,10 @@ export function registerMainSessionTools(ctx, configProvider) {
         ? new LocalWikiClient(ensureLocalKbRoot())
         : (ctx.get('wiki') ?? new WikiVaultClient(() => configProvider.getEffective().wikiVault));
     const caller = () => ({ actor: 'human' });
-    // 只读 kanban 子集（无 create/complete/block）
-    const readOnly = new Set(['kanban_show', 'kanban_chain', 'kanban_list', 'kanban_comment']);
+    // 主会话 kanban 工具子集（无 create/complete/block）。2026-09-15 恢复能力：+ 人工恢复双工具
+    //（kanban_reopen_chain / kanban_waive_review）——主会话 caller 恒为 human（服务层再校验 can()），
+    // 角色 toolsets 名单不动（角色工具面零暴露）。
+    const readOnly = new Set(['kanban_show', 'kanban_chain', 'kanban_list', 'kanban_comment', 'kanban_reopen_chain', 'kanban_waive_review']);
     for (const tool of buildKanbanTools(service, caller)) {
         const name = tool.name;
         if (name && readOnly.has(name))
@@ -232,15 +244,23 @@ export function registerMainSessionTools(ctx, configProvider) {
                 // 其余非空 rest → 自由投递（正文由主 agent 按意图生成，显式豁免；事实基准=看板实查）。
                 // -s 独立 token 由 parseSendRequest 剥离置 dm；manual 路径零重试。
                 const parsed = parseSendRequest(plan.rest);
-                const targetOpts = { retryDelaysMs: [], manual: true, targetKind: (parsed.dm ? 'user' : 'group') };
+                const targetOpts = {
+                    retryDelaysMs: [], manual: true,
+                    targetKind: (parsed.dm ? 'user' : 'group'),
+                    sessionPreset: sessionPresetOf(ctx, exec),
+                    agent: exec?.agent,
+                };
                 const deliver = async (variant, query) => {
                     const r = await sendChainReport(ctx, service, configProvider, targetOpts, variant, query);
                     if (r.ok) {
                         const noun = variant === 'blocked' ? '阻塞通知' : '完成汇报';
                         const dest = parsed.dm ? '私聊' : '群聊';
+                        const via = r.via === 'interactive' ? `（本次交互选定${r.fallbackSaved ? '，已设为默认' : ''}）`
+                            : r.via === 'fallback' ? '（未命中会话模式，走默认机器人）'
+                                : r.via === 'preset' ? '（按会话模式匹配机器人）' : '';
                         return {
-                            kind: 'send', chainId: r.chainId, botId: r.botId, targetId: r.targetId,
-                            guidance: `${noun}已投递${dest}（/sms 手动触发）。请仅向用户确认投递成功与目标，勿复述消息正文。`,
+                            kind: 'send', chainId: r.chainId, botId: r.botId, targetId: r.targetId, via: r.via,
+                            guidance: `${noun}已投递${dest}${via}（/sms 手动触发）。请仅向用户确认投递成功与目标，勿复述消息正文。`,
                         };
                     }
                     return { kind: 'send', error: r.error, guidance: r.guidance ?? '请将 error 字段原样转告用户，勿复述消息正文。' };
@@ -328,7 +348,7 @@ export function registerMainSessionTools(ctx, configProvider) {
             dm: { type: 'boolean', description: 'true = private chat; omit/false = group' },
         },
         output: { schema: { type: 'json' }, render: (_a, v) => [{ type: 'text', text: JSON.stringify(v) }] },
-        async execute(args) {
+        async execute(args, exec) {
             // actor 边界与 planning 工具同构：主会话工具面仅限人工触发，非 human caller 一律拒绝
             if (caller().actor !== 'human')
                 throw new Error('permission denied: sms_send');
@@ -338,7 +358,10 @@ export function registerMainSessionTools(ctx, configProvider) {
             if (text.length > 4000)
                 throw new Error(`text too long: ${text.length} > 4000 chars`);
             const dm = args.dm === true;
-            const deliver = createSender(ctx, service, configProvider, { retryDelaysMs: [], manual: true, targetKind: dm ? 'user' : 'group' });
+            const deliver = createSender(ctx, service, configProvider, {
+                retryDelaysMs: [], manual: true, targetKind: dm ? 'user' : 'group',
+                sessionPreset: sessionPresetOf(ctx, exec), agent: exec?.agent,
+            });
             const r = await deliver('free-send', text);
             if (!r.ok) {
                 return {
@@ -347,8 +370,10 @@ export function registerMainSessionTools(ctx, configProvider) {
                 };
             }
             return {
-                kind: 'send', mode: 'free', dm, botId: r.botId, targetId: r.targetId,
-                guidance: '已投递（自由投递）。请仅向用户确认投递成功与目标（群聊/私聊），勿复述正文。',
+                kind: 'send', mode: 'free', dm, botId: r.botId, targetId: r.targetId, via: r.via,
+                guidance: '已投递（自由投递）。请仅向用户确认投递成功与目标（群聊/私聊），勿复述正文。'
+                    + (r.fallbackSaved === true ? '已按你的选择把该机器人设为默认机器人（后续模式未命中时直接使用）。' : '')
+                    + (r.fallbackSaved === false ? '注意：设为默认未写入成功（配置未更新），下次仍需重新选择。' : ''),
             };
         },
     }));

package/lib/tools/ocr-review-tools.js

@@ -28,6 +28,7 @@ export function buildOcrReviewTool(deps) {
             to: { type: 'string', description: '目标分支/引用（range 模式，默认 HEAD）' },
             commit: { type: 'string', description: '单次提交审查' },
             paths: { type: 'array', items: { type: 'string' }, description: 'rule 子命令的文件路径列表' },
+            background: { type: 'string', description: '业务上下文，托管评审时提升评审质量' },
         },
         output: { schema: { type: 'json' }, render: (_a, v) => [{ type: 'text', text: String(v) }] },
         async execute(args) {
@@ -42,18 +43,24 @@ export function buildOcrReviewTool(deps) {
                 throw new Error("ocr_review: sub='rule' requires non-empty paths (file path list)");
             if (args.sub === 'managed' && !args.commit && !args.from)
                 throw new Error("ocr_review: sub='managed' requires commit or from (base ref)");
-            const res = await runOcrFn(buildOcrArgs(args.sub, { repo: args.repo, from: args.from, to: args.to, commit: args.commit, paths: args.paths }), { cwd: deps.cwd?.() ?? process.cwd(), timeoutMs: 600_000 });
-            if (res.error && !res.stdout)
-                throw new Error(`ocr_review: ${res.error} ${res.stderr.slice(0, 500)}`.trim());
+            // 托管评审走 ocr 自带 LLM（官方预算 15min×2 rounds），超时须远大于 preview/rule 的本地 git 操作
+            const timeoutMs = args.sub === 'managed' ? 2_400_000 : 600_000;
+            const res = await runOcrFn(buildOcrArgs(args.sub, { repo: args.repo, from: args.from, to: args.to, commit: args.commit, paths: args.paths, background: args.background }), { cwd: deps.cwd?.() ?? process.cwd(), timeoutMs });
+            // 失败不抛错：结果附 error 摘要（error + stderr 前 500 字符），模型拿得到部分结果与原因后自行降级/重试
+            const errSummary = res.error ? `${res.error} ${res.stderr.slice(0, 500)}`.trim() : '';
             if (args.sub === 'preview') {
                 const preview = parsePreviewJson(res.stdout);
+                const errorPart = errSummary ? { error: errSummary } : {};
                 if (shouldSuggestManaged(preview.files.length)) {
-                    return JSON.stringify({ ...preview, suggestion: `文件较多（N>${SUGGEST_MANAGED_FILES}），可在配置面板切换托管模式` });
+                    return JSON.stringify({ ...preview, ...errorPart, suggestion: `文件较多（N>${SUGGEST_MANAGED_FILES}），可在配置面板切换托管模式` });
                 }
-                return JSON.stringify(preview);
+                return JSON.stringify({ ...preview, ...errorPart });
             }
-            if (args.sub === 'rule')
+            if (args.sub === 'rule') {
+                if (errSummary)
+                    return JSON.stringify({ error: errSummary });
                 return res.stdout.slice(0, 8000);
+            }
             const report = parseManagedJson(res.stdout);
             if (report.status !== 'completed' && res.error)
                 return JSON.stringify({ ...report, message: res.error });