@joekytc/dsh-swarm 0.3.11 → 0.5.0

package/client/index.ts

@@ -15,14 +15,15 @@ declare module '@deepseek-ai/cordis' {
 }
 import { ConfigSection } from './ConfigSection.js';
 import { SWARM_CONFIG_NS } from './config-store.js';
-import { setSessionsService } from './session-bridge.js';
+import { setSessionsService, setSessionNavigator } from './session-bridge.js';
 import css from './kanban.css';
 import configCss from './config.css';
 
 export const name = 'kanban-board';
 
-/** 所需 client 服务（cordis fiber inject——loader 把模块导出当作对象插件传入）。 */
-export const inject = ['slots', 'sessions'];
+/** 所需 client 服务（cordis fiber inject——loader 把模块导出当作对象插件传入）。
+ *  uiWorkspace：0.1.7 起宿主内置的视图所有者导航（会话跳转新接缝），fiber inject 会等待其就绪。 */
+export const inject = ['slots', 'sessions', 'uiWorkspace'];
 
 /** 浏览器半入口（roster 行 id: kanban-board）：把看板挂到 conversation.view（会话中心 tab，additive）。
  *  对齐 DSH 原生注册：对话(id=chat, order=0) → 轨迹(id=trajectory, order=10) → 看板(id=kanban, order=20)。
@@ -32,6 +33,9 @@ export function apply(ctx: Context): (() => void) | void {
   // cast：@deepseek-ai/dsh-session（服务端包）也 merge 了 cordis Context.sessions: SessionStore，
   // 类型面被其覆盖；浏览器半运行时注入的实为 dsh-api-session-controller 的 ISessions。
   setSessionsService(ctx.sessions as unknown as ISessions);
+  // 会话跳转导航：0.2.0+ 宿主提供 uiWorkspace（视图所有者），但注册晚于 client apply——
+  // 只传惰性 getter（点击时解析+try/catch 降级），apply 期绝不触碰属性，防 cordis 未就绪 throw 炸掉入口注册。
+  setSessionNavigator(() => (ctx as { uiWorkspace?: { openSession(target: string): void } }).uiWorkspace ?? null);
   let style: HTMLStyleElement | null = null;
   let configStyle: HTMLStyleElement | null = null;
   if (typeof document !== 'undefined') {
@@ -62,5 +66,5 @@ export function apply(ctx: Context): (() => void) | void {
       ConfigSection as never,
     ),
   );
-  return () => { if (style) style.remove(); if (configStyle) configStyle.remove(); setSessionsService(null); };
+  return () => { if (style) style.remove(); if (configStyle) configStyle.remove(); setSessionsService(null); setSessionNavigator(null); };
 }

package/client/session-bridge.ts

@@ -32,8 +32,32 @@ export function useSessionIds(): ReadonlySet<string> {
   );
 }
 
-/** 应用内跳转到指定会话（宿主 ISessions.open 对不在列表的 id fail loud，调用方须先经 useSessionIds 门控）。 */
+/** 新宿主导航接缝：dsh 0.2.0 起 ISessions.open 移除，会话导航归视图所有者（uiWorkspace.openSession）。
+ *  宿主以 getter 惰性供给（uiWorkspace 注册晚于 client apply，apply 期属性访问会在 cordis 上 throw）；
+ *  0.1.7 底线宿主无此服务，getter 返回 null 走旧 open 转发。 */
+let navigator: (() => { openSession(target: string): void } | null) | null = null;
+
+export function setSessionNavigator(next: (() => { openSession(target: string): void } | null) | null): void {
+  navigator = next;
+}
+
+/** 应用内跳转到指定会话（调用方须先经 useSessionIds 门控，宿主对不在列表的 id fail loud）。 */
 export function openSession(id: string): void {
+  // 优先 0.2.0+ 视图所有者导航；解析失败视同服务缺席；旧宿主退回 ISessions.open 转发；两者皆缺则响亮报错。
+  if (navigator) {
+    let viaWorkspace: { openSession(target: string): void } | null = null;
+    try {
+      viaWorkspace = navigator();
+    } catch {
+      viaWorkspace = null;
+    }
+    if (viaWorkspace) {
+      viaWorkspace.openSession(id);
+      return;
+    }
+  }
   if (!service) throw new Error('sessions service unavailable');
-  service.open(id as never);
+  const open = (service as { open?: (target: string) => void }).open;
+  if (!open) throw new Error('host exposes neither uiWorkspace nor sessions.open; session jump unavailable');
+  open(id);
 }

package/lib/client.js

@@ -560,9 +560,27 @@ window.__ModuleLoader__.load({
 		    () => EMPTY
 		  );
 		}
+		var navigator = null;
+		function setSessionNavigator(next) {
+		  navigator = next;
+		}
 		function openSession(id) {
+		  if (navigator) {
+		    let viaWorkspace = null;
+		    try {
+		      viaWorkspace = navigator();
+		    } catch {
+		      viaWorkspace = null;
+		    }
+		    if (viaWorkspace) {
+		      viaWorkspace.openSession(id);
+		      return;
+		    }
+		  }
 		  if (!service) throw new Error("sessions service unavailable");
-		  service.open(id);
+		  const open = service.open;
+		  if (!open) throw new Error("host exposes neither uiWorkspace nor sessions.open; session jump unavailable");
+		  open(id);
 		}
 		
 		// client/BoardCard.tsx
@@ -2897,9 +2915,10 @@ window.__ModuleLoader__.load({
 		
 		// client/index.ts
 		var name = "kanban-board";
-		var inject = ["slots", "sessions"];
+		var inject = ["slots", "sessions", "uiWorkspace"];
 		function apply(ctx) {
 		  setSessionsService(ctx.sessions);
+		  setSessionNavigator(() => ctx.uiWorkspace ?? null);
 		  let style = null;
 		  let configStyle = null;
 		  if (typeof document !== "undefined") {
@@ -2936,6 +2955,7 @@ window.__ModuleLoader__.load({
 		    if (style) style.remove();
 		    if (configStyle) configStyle.remove();
 		    setSessionsService(null);
+		    setSessionNavigator(null);
 		  };
 		}
 		

package/lib/dispatcher/agent-runner.js

@@ -1,5 +1,6 @@
 import { SessionId } from '@deepseek-ai/dsh-session';
 import { writeFileSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
 import { join } from 'node:path';
 import { probeOcr } from '../services/ocr-cli.js';
 import { installRoleTools, buildReadOnlyWriteGuard, buildDTWriteGuard, buildPlanWriteGuard, buildKbWriteGuard, registerDtTaskChain, unregisterDtTaskChain } from '../roles/toolsets.js';
@@ -7,7 +8,8 @@ import { ensureLocalKbRoot } from '../wiki/local-kb.js';
 import { installCleanFsTools } from '../roles/clean-fs-tools.js';
 import { mountOrRecompose } from '../roles/preset-installer.js';
 import { buildModelCandidates, isModelUnavailableError } from './model-candidates.js';
-import { toolName, isGuardSynthesizedReply } from './session-events.js';
+import { toolName, isGuardSynthesizedReply, lastTurnEnd } from './session-events.js';
+import { filterCandidatesByCatalog } from '../services/llm-catalog.js';
 import { attachSessionToWorkspace, resolveOrCreateWorkspace } from './workspace-attach.js';
 import { isPathInside, resolveTargetRepoDir } from './target-repo.js';
 import { injectGitCredentials, resolveGitPatFromCtx } from './git-credentials.js';
@@ -21,6 +23,18 @@ const GOAL_MODE_KEYWORDS = ['/goal', '目标模式', 'goal mode'];
 function isInfraError(err) {
     return /cannot prepare session|while it is live|timeout|ETIMEDOUT|ECONNREFUSED|ECONNRESET|socket/i.test(String(err));
 }
+/** turn 级错误分类（环境中止 ≠ 角色不收敛）：
+ *  - 'config'：provider/model/effort 组合性永久错误（重派必撞同一错误）→ 终态 block(model-unavailable) 等人工修配置；
+ *  - 'transient'：配额/限流/网络类瞬时错误 → failTask({infra:true})（不计 attempts，靠调度 tick 重派）；
+ *  - 'unknown'：未识别错误 → failTask 计入 attempts（有界重试，防未知错误无限重派）。
+ *  三种去向都不写 protocol_violation、不烧 PV 护栏预算——环境错误不是角色协议违规。 */
+function classifyTurnError(code, message) {
+    if (code === 'UNKNOWN_MODEL' || code === 'UNSUPPORTED_REASONING_EFFORT' || code === 'INVALID_REQUEST')
+        return 'config';
+    if (code === 'QUOTA' || /quota|rate.?limit|\b429\b/i.test(message) || isInfraError(message))
+        return 'transient';
+    return 'unknown';
+}
 /** 关键事件追加落盘 storageDir/dispatcher.log（与 dispatcher.ts 同一文件、同一行格式）——
  *  agent-runner 未注入 logFile，按 dispatcher 同款方式经 configProvider 派生 storageDir；
  *  写失败静默忽略（日志只是观测面，事件日志才是事实源）。 */
@@ -253,7 +267,7 @@ ${task.body}`);
                 (task.attempts > 0 || state.events.some((e) => e.taskId === taskId && e.kind === 'task/claimed'));
             let agent;
             let context = '';
-            const setup = async (agentCtx) => {
+            const setup = async (agentCtx, agent) => {
                 // 思考等级强制（waterfall）：宿主 selection 无 create-options 覆盖层（dsh-host-apiproxy 的
                 // selectionFor 不消费 agentOptions），AgentOptions 也仅有 provider/model/maxTokens——agentOptions
                 // 里的 reasoningEffort 不被宿主消费，新建角色会话思考等级会落回宿主默认。改走 DSH agent/request
@@ -270,7 +284,8 @@ ${task.body}`);
                 // P/W/D = full access（跨目录读：P 读仓库/外部实证、W 读计划、D 执行）；
                 // 但 P 挂 plan 写护栏、W 挂只读护栏（写边界由工具级强制，防"改动源码"，不靠 prompt 软约束）；
                 // PT/DT/V → workspace-write（评审/编排最小权限，PT/DT 只读护栏由 ToolGuard 独立保证）。
-                const session = agentCtx.agent?.session;
+                // approval/sandbox 种子事件经 AgentSetup 第二参的 agent 显式直写（0.2.0 起 ctx.agent 挂载已移除）。
+                const session = agent?.session;
                 session?.append?.('approval/policy', { policy: 'never', source: 'delegation' });
                 const fullAccess = isDExecute || task.assignee === 'p' || task.assignee === 'w';
                 session?.append?.('sandbox/mode', fullAccess ? { mode: 'danger-full-access', source: 'delegation' } : { mode: 'workspace-write', source: 'delegation' });
@@ -305,16 +320,13 @@ ${task.body}`);
                 // PT/DT 是 workspace-write（sandbox_permissions 扩权到天花板是合法功能，剥了破坏官方能力）；
                 // W 虽 fullAccess 但只读护栏全拒 write，shadow 无意义（最小挂载面，V 无执行工具不涉及）。
                 if (task.assignee === 'p' || isDExecute) {
-                    installCleanFsTools(agentCtx, agentCtx.agent);
+                    installCleanFsTools(agentCtx, agent);
                 }
                 // 组合标记——角色工具面成功组合后，把 { role, taskId } 记到进程内 WeakMap（键=Agent 实例）。
-                // 宿主探明：setup 收到的 agentCtx.agent 与发布后 agents.get(id) 返回的是同一 Agent 实例
-                // （dsh-agent types/index.d.ts:38 `agent?: Agent` 安装为 Agent.ctx own property），
-                // 故此处键入的实例即 resumeOrReuse 里 agents.get 命中的实例。agentCtx.agent 缺失（宿主变体）时
-                // 不写标记 → live 复用走工具面校验路径（kanban_complete 可见性），能力无损。
-                const liveAgent = agentCtx.agent;
-                if (liveAgent)
-                    markRoleComposition(liveAgent, { role: task.assignee, taskId: task.id });
+                // AgentSetup 第二参收到的 Agent 与发布后 agents.get(id) 返回的是同一实例，故此处键入的实例
+                // 即 resumeOrReuse 里 agents.get 命中的实例（live 复用走标记匹配，能力无损）。
+                if (agent)
+                    markRoleComposition(agent, { role: task.assignee, taskId: task.id });
                 // 只读评审角色（PT/DT）注册 ToolGuard：拦截 tracked source 写入 / git mutation / 含写标记 bash。
                 // 以 dsh-tools 类型为准：tools.guard(execution => reason|undefined)，execution.name/arguments 为实际字段。
                 if (task.assignee === 'pt' || task.assignee === 'dt') {
@@ -380,7 +392,35 @@ ${task.body}`);
                 context = this.buildContext(task, state, hasRunHistory);
                 // 模型候选链：primary + fallbacks，model/provider 不可用时静默切换下一候选；
                 // 全部候选不可用 → block(model-unavailable) 抛给用户；非 model 错误 → failTask（原逻辑）。
-                const candidates = buildModelCandidates(this.configProvider.getEffective(), task.assignee, this.defaultModel);
+                const builtCandidates = buildModelCandidates(this.configProvider.getEffective(), task.assignee, this.defaultModel);
+                // 派发前预校验（LLM 目录）：不存在的 provider/model 组合、模型未声明的 reasoningEffort
+                // 直接剔除，不再打进网络白烧会话（UNKNOWN_MODEL / UNSUPPORTED_REASONING_EFFORT 秒退实证形态——
+                // 候选 fallback 只护 create/resume 抛错，turn 期错误不触发切换，必须前置拦截）。
+                // fail-open：llm 服务未就绪/目录探测失败 → 全放行，不阻断派发。
+                // 全部候选被拒 → block(model-unavailable) 终态（与 spawn 全候选失败同语义，等人工修配置）。
+                let candidates = builtCandidates;
+                if (builtCandidates.length > 0) {
+                    // llm 服务可能尚未接线（runner 只依赖 agents+kanban 就绪）——缺失/异常一律 fail-open。
+                    let llmRuntime;
+                    try {
+                        llmRuntime = this.ctx.get('llm');
+                    }
+                    catch {
+                        llmRuntime = undefined;
+                    }
+                    const precheck = await filterCandidatesByCatalog(llmRuntime, builtCandidates);
+                    if (precheck.rejected.length > 0) {
+                        const detail = precheck.rejected.map((r) => `${r.candidate.provider}/${r.candidate.model}: ${r.reason}`).join('；');
+                        console.error('[dsh-swarm][debug] model precheck rejected task=' + taskId + ': ' + detail);
+                        logToDispatcherLog(this.configProvider, '[model-precheck] task=' + taskId + ' rejected: ' + detail);
+                    }
+                    if (precheck.ok.length === 0) {
+                        await this.kanban.blockTask(taskId, 'model-unavailable: 配置的模型候选与 LLM 目录不匹配 —— '
+                            + precheck.rejected.map((r) => `${r.candidate.provider}/${r.candidate.model}: ${r.reason}`).join('；'), 'system');
+                        return;
+                    }
+                    candidates = precheck.ok;
+                }
                 if (candidates.length === 0) {
                     // 无任何候选配置：不传 agentOptions（用部署默认），单次尝试
                     agent = hasRunHistory
@@ -451,7 +491,7 @@ ${task.body}`);
             const attachId = task.resumeSessionId ?? `kbn-${task.id}`;
             await attachSessionToWorkspace(this.ctx, attachId, sessionCwd, 'task ' + task.id + ' ' + task.assignee + '/' + task.mode);
             try {
-                agent.followup({ content: [{ type: 'text', text: context }], source: { kind: 'user' } });
+                agent.followup({ id: randomUUID(), content: [{ type: 'text', text: context }], source: { kind: 'user' } });
                 console.error('[dsh-swarm][debug] runner followup sent ' + taskId);
                 await agent.whenIdle();
                 console.error('[dsh-swarm][debug] runner whenIdle resolved ' + taskId);
@@ -469,7 +509,7 @@ ${task.body}`);
                     : (sessionLike.events ?? []);
                 if (turnEvents.filter((e) => (Number(e?.seq) || 0) > eventsBase).some(isGuardSynthesizedReply)) {
                     console.error('[dsh-swarm][debug] runner guard-synthesized reply detected (from-cache/from-security-guard) ' + taskId + ' — auto followup retry once');
-                    agent.followup({ content: [{ type: 'text', text: '继续未完成的任务：上一条回复是网关安全护栏/语义缓存误拦的合成拒答，并非你的真实结论。请忽略它，从中断处继续执行任务，直至按协议收敛终态（kanban_complete 或 kanban_block）。' }], source: { kind: 'user' } });
+                    agent.followup({ id: randomUUID(), content: [{ type: 'text', text: '继续未完成的任务：上一条回复是网关安全护栏/语义缓存误拦的合成拒答，并非你的真实结论。请忽略它，从中断处继续执行任务，直至按协议收敛终态（kanban_complete 或 kanban_block）。' }], source: { kind: 'user' } });
                     console.error('[dsh-swarm][debug] runner guard-retry followup sent ' + taskId);
                     await agent.whenIdle();
                     console.error('[dsh-swarm][debug] runner guard-retry whenIdle resolved ' + taskId);
@@ -488,43 +528,70 @@ ${task.body}`);
                     console.error('[dsh-swarm][debug] runner skip block ' + taskId + ' status=' + (cur ? cur.status : 'gone'));
                 }
                 else {
-                    // 协议违规护栏：连续 protocol_violation 阻塞 ≥ maxProtocolViolations（默认 2）后，
-                    // 下一次违规直接 gave_up（不再恢复，走 [blocked-final] 证据链抛给主 agent）。任意角色（含 pt/dt）统一。
-                    const maxPV = this.configProvider.getEffective().dispatcher?.maxProtocolViolations ?? 2;
-                    const priorViolations = fresh.events.filter((e) => e.taskId === taskId && e.kind === 'task/blocked' &&
-                        String(e.payload['reason'] ?? '').startsWith('protocol_violation')).length;
-                    const finalBlock = priorViolations >= maxPV;
-                    const reason = finalBlock
-                        ? 'gave_up: protocol_violation after ' + maxPV + ' review cycles without complete/block'
-                        : 'protocol_violation: idle without complete/block';
-                    await this.kanban.blockTask(taskId, reason, 'system');
-                    // comment-only 收尾显形——放 block 之后（保证 block 一定先发生，
-                    // 告警只追加在已阻塞卡上，不影响终态判据与 [blocked-final] 证据链快照）。
-                    // 本轮增量事件命中 kanban_comment（经 toolName 兼容读取落盘/live 两形态）且未成功提交
-                    // （能走到这里即终态判据已确认非确定态）→ 交付内容很可能滞留 comments，显形告警。
-                    const commentOnly = agent.session.snapshotEvents(eventsBase).some((e) => toolName(e) === 'kanban_comment');
-                    if (commentOnly) {
-                        await this.kanban.comment(taskId, '[comment-only-closeout] 本轮仅用 kanban_comment 交付（无 complete/block）。交付内容可能滞留 comments（如角色工具缺失/会话被错误复用）；请人工核对 comments 与产物后解除阻塞重派。', 'system');
+                    // 环境中止识别：读本轮最后一轮 turn/end（拒答重试会产生第二轮，取 seq 最大者）。
+                    // whenIdle resolve 只说明会话空闲，不区分「正常收敛」与「模型/网关错误秒退」——
+                    // 后者按原判据会误记 protocol_violation（UNKNOWN_MODEL 误判实证：claim→block 1.3s、
+                    // 0 次模型调用、0 token）。turn 以 error 结束 → 按 classifyTurnError 分流
+                    // （config → block(model-unavailable) 终态；transient → failTask(infra) 靠 tick 重派；
+                    // unknown → failTask 计预算有界重试），一律不写 protocol_violation、不烧 PV 预算。
+                    // 只有 turn 正常 completed（或无 turn 事件的测试桩/宿主变体兜底）才进入下方协议违规
+                    // 判据——PV 从此只剩真实语义：模型正常收敛但未调 terminal 工具（comment-only 等）。
+                    const finalTurnEvents = typeof sessionLike.snapshotEvents === 'function'
+                        ? sessionLike.snapshotEvents(eventsBase)
+                        : (sessionLike.events ?? []);
+                    const turnInfo = lastTurnEnd(finalTurnEvents, eventsBase);
+                    if (turnInfo?.kind === 'error') {
+                        const cls = classifyTurnError(turnInfo.code, turnInfo.message ?? '');
+                        const detail = (turnInfo.code ?? 'UNKNOWN') + ': ' + (turnInfo.message ?? 'unknown turn error');
+                        console.error('[dsh-swarm][debug] turn abort(' + cls + ') ' + taskId + ': ' + detail);
+                        logToDispatcherLog(this.configProvider, '[turn-abort] task=' + taskId + ' ' + cls
+                            + (cls === 'config' ? ' → blocked model-unavailable: ' : ' → failed(infra=' + (cls === 'transient') + '): ') + detail);
+                        if (cls === 'config') {
+                            await this.kanban.blockTask(taskId, 'model-unavailable: turn aborted (' + detail + ')', 'system');
+                        }
+                        else {
+                            await this.kanban.failTask(taskId, 'turn-abort: ' + detail, 'system', { infra: cls === 'transient' });
+                        }
                     }
-                    if (finalBlock) {
-                        // [blocked-final] 证据链：block 时间线 + 复核/评论时间线 + 最终 reason（system 确定性写入）
-                        const evs = fresh.events.filter((e) => e.taskId === taskId);
-                        const blockTimeline = evs
-                            .filter((e) => e.kind === 'task/blocked')
-                            .map((e) => `  - seq=${e.seq} at=${e.at} author=${e.author} reason=${String(e.payload['reason'] ?? '')}`)
-                            .join('\n');
-                        const reviewTimeline = evs
-                            .filter((e) => e.kind === 'task/commented')
-                            .map((e) => `  - seq=${e.seq} at=${e.at} author=${e.author}: ${String(e.payload['body'] ?? '')}`)
-                            .join('\n');
-                        await this.kanban.comment(taskId, [
-                            '[blocked-final] 协议违规超护栏，任务不再自动恢复（人工解除后仍按 gave_up 终态处理）。',
-                            '## block 时间线',
-                            blockTimeline,
-                            '## 复核/评论时间线',
-                            reviewTimeline || '  - (无复核评论)',
-                            '最终原因: ' + reason,
-                        ].join('\n'), 'system');
+                    else {
+                        // 协议违规护栏：连续 protocol_violation 阻塞 ≥ maxProtocolViolations（默认 2）后，
+                        // 下一次违规直接 gave_up（不再恢复，走 [blocked-final] 证据链抛给主 agent）。任意角色（含 pt/dt）统一。
+                        const maxPV = this.configProvider.getEffective().dispatcher?.maxProtocolViolations ?? 2;
+                        const priorViolations = fresh.events.filter((e) => e.taskId === taskId && e.kind === 'task/blocked' &&
+                            String(e.payload['reason'] ?? '').startsWith('protocol_violation')).length;
+                        const finalBlock = priorViolations >= maxPV;
+                        const reason = finalBlock
+                            ? 'gave_up: protocol_violation after ' + maxPV + ' review cycles without complete/block'
+                            : 'protocol_violation: idle without complete/block';
+                        await this.kanban.blockTask(taskId, reason, 'system');
+                        // comment-only 收尾显形——放 block 之后（保证 block 一定先发生，
+                        // 告警只追加在已阻塞卡上，不影响终态判据与 [blocked-final] 证据链快照）。
+                        // 本轮增量事件命中 kanban_comment（经 toolName 兼容读取落盘/live 两形态）且未成功提交
+                        // （能走到这里即终态判据已确认非确定态）→ 交付内容很可能滞留 comments，显形告警。
+                        const commentOnly = agent.session.snapshotEvents(eventsBase).some((e) => toolName(e) === 'kanban_comment');
+                        if (commentOnly) {
+                            await this.kanban.comment(taskId, '[comment-only-closeout] 本轮仅用 kanban_comment 交付（无 complete/block）。交付内容可能滞留 comments（如角色工具缺失/会话被错误复用）；请人工核对 comments 与产物后解除阻塞重派。', 'system');
+                        }
+                        if (finalBlock) {
+                            // [blocked-final] 证据链：block 时间线 + 复核/评论时间线 + 最终 reason（system 确定性写入）
+                            const evs = fresh.events.filter((e) => e.taskId === taskId);
+                            const blockTimeline = evs
+                                .filter((e) => e.kind === 'task/blocked')
+                                .map((e) => `  - seq=${e.seq} at=${e.at} author=${e.author} reason=${String(e.payload['reason'] ?? '')}`)
+                                .join('\n');
+                            const reviewTimeline = evs
+                                .filter((e) => e.kind === 'task/commented')
+                                .map((e) => `  - seq=${e.seq} at=${e.at} author=${e.author}: ${String(e.payload['body'] ?? '')}`)
+                                .join('\n');
+                            await this.kanban.comment(taskId, [
+                                '[blocked-final] 协议违规超护栏，任务不再自动恢复（人工解除后仍按 gave_up 终态处理）。',
+                                '## block 时间线',
+                                blockTimeline,
+                                '## 复核/评论时间线',
+                                reviewTimeline || '  - (无复核评论)',
+                                '最终原因: ' + reason,
+                            ].join('\n'), 'system');
+                        }
                     }
                 }
             }
@@ -582,7 +649,8 @@ ${task.body}`);
                 // GUI 默认组合 incarnation：缺 kanban_complete → 重跑 setup 幂等补挂后复用。
                 // setup 对 live ctx 的各步均可加：effort waterfall/approval+sandbox append（known 事件类型、
                 // latest-wins）/preset mount（bindings 覆盖）/角色工具（此前为默认组合，无同名冲突）/护栏。
-                await opts.setup(liveCtx);
+                // 双参签名（0.2.0）：repair 重跑 setup 时显式传 live agent 实例（标记随修复自愈）。
+                await opts.setup(liveCtx, live);
                 if (toolsSvc.get('kanban_complete', live))
                     return live; // 修复后必须验证到位，防静默半修复
                 throw new Error('live session composition repair failed: kanban_complete still missing after re-setup (session ' + sessionId + ')');

package/lib/dispatcher/chain-auditor.d.ts

@@ -11,8 +11,9 @@ import type { AuditEvidence, Task } from '../domain/types.js';
  *    a. 作用域收窄：仅扫描会话工作区（session.header.cwd）位于本链发起工作区
  *       （Chain.workspaceDir = /plan: 主 agent 所在工作空间）内的会话，
  *       排除其他项目的主会话（如 评估 项目里调试 dsh-swarm 的会话）；
- *    b. 行为判定：run_code 按实际派发子调用（tool/code-dispatch-start / tool/code-dispatch，
- *       经 rootCallId 关联外层调用）判定是否真的发生写，而非把 run_code 一律视为写；
+ *    b. 行为判定：run_code 按实际派发子调用（新旧宿主双名 tool/code-dispatch[-start] /
+ *       tool/ptc-dispatch[-start]，经 rootCallId 关联外层调用）判定是否真的发生写，而非把
+ *       run_code 一律视为写；
  *    c. 只读排除：bash 命令 / 兜底 code 字符串仅当含写操作标记（BASH_WRITE_RE）且
  *       含 workspacesRoot 路径时才计为写证据；纯只读排查（ls/cat/glob/read/grep）不产生证据。
  * 2. 产物归属核对（fallback，机械可测）：枚举 workspaces/<chainId>/ 下条目；

package/lib/dispatcher/chain-auditor.js

@@ -1,7 +1,7 @@
 // src/dispatcher/chain-auditor.ts
 import { readdirSync } from 'node:fs';
 import { join } from 'node:path';
-import { eventType, toolArgs, toolName } from './session-events.js';
+import { eventType, isRunCodeDispatchEvent, toolArgs, toolName } from './session-events.js';
 import { isPathInside } from './target-repo.js';
 import { headerPresetOf } from './session-preset.js';
 /** 直接写工具（无条件视为写能力；只读工具如 read/glob/grep 不算）。 */
@@ -113,7 +113,7 @@ function sessionWriteEvidence(id, workspacesRoot, events) {
                 }
             }
         }
-        else if (t === 'tool/code-dispatch-start' || t === 'tool/code-dispatch') {
+        else if (isRunCodeDispatchEvent(ev)) {
             const rootCallId = String(dataField(ev, 'rootCallId') ?? '');
             const name = String(dataField(ev, 'name') ?? '');
             if (!rootCallId || !name)

package/lib/dispatcher/session-events.d.ts

@@ -18,6 +18,13 @@ export declare function eventType(e: {
 export declare function toolName(e: unknown): string | undefined;
 /** 取工具调用参数对象（兼容 JSON 字符串 / 对象两种落盘形态）。 */
 export declare function toolArgs(e: unknown): Record<string, unknown>;
+/** run_code 派发子调用事件名（start 与完成两种）新旧宿主双名集合：
+ *  旧宿主会话落盘为 tool/code-dispatch-start / tool/code-dispatch；
+ *  宿主 V3+ 会话格式改名为 tool/ptc-dispatch-start / tool/ptc-dispatch。
+ *  消费方（链审计器按派发子调用判定 run_code 实际写行为）双名等价命中，勿散落硬编码。 */
+export declare const RUN_CODE_DISPATCH_EVENT_TYPES: ReadonlySet<string>;
+/** 该事件是否为 run_code 派发子调用事件（start 或完成，新旧事件名皆认）。 */
+export declare function isRunCodeDispatchEvent(e: unknown): boolean;
 /** 取 assistant 消息的网关缓存回放标记（replayState.response.responseModel，如 'from-cache'）。
  *  非 assistant/message 或无标记返回 null。2026-09-04：远程网关回复缓存整包回放时由 SSE
  *  id/model 字段透传（dsh 纯透传），插件侧据此识别缓存劫持零产出。兼容落盘（data.message）
@@ -30,3 +37,17 @@ export declare function replayModel(e: unknown): string | null;
 export declare const GUARD_SYNTH_REPLAY_MODELS: ReadonlySet<string>;
 /** 该事件是否为网关合成拒答/缓存回放的 assistant 消息（判定与标记集单一事实源）。 */
 export declare function isGuardSynthesizedReply(e: unknown): boolean;
+/** turn/end 结束原因（区分「环境错误秒退」与「角色正常收敛」的单一读取点）：
+ *  落盘形态 {"type":"turn/end","seq":N,"data":{"turn":T,"reason":{"kind":"completed"} |
+ *  {"kind":"error","error":{"code":"UNKNOWN_MODEL","message":"…"}}}}；
+ *  live 顶层展开形态经顶层 turn/reason 兜底兼容。非 turn/end 或 reason 不可读 → null。 */
+export interface TurnEndInfo {
+    turn: number;
+    kind: string;
+    code: string | null;
+    message: string | null;
+}
+export declare function turnEndOf(e: unknown): TurnEndInfo | null;
+/** 本轮增量（seq > fromSeq）内最后一轮 turn/end——拒答重试会产生第二轮，取 seq 最大者。
+ *  无 turn/end（测试桩/宿主变体）→ null，调用方按「无轮信息」回退原判据，不改变既有行为。 */
+export declare function lastTurnEnd(events: ReadonlyArray<unknown>, fromSeq: number): TurnEndInfo | null;

package/lib/dispatcher/session-events.js

@@ -35,6 +35,21 @@ export function toolArgs(e) {
     }
     return {};
 }
+/** run_code 派发子调用事件名（start 与完成两种）新旧宿主双名集合：
+ *  旧宿主会话落盘为 tool/code-dispatch-start / tool/code-dispatch；
+ *  宿主 V3+ 会话格式改名为 tool/ptc-dispatch-start / tool/ptc-dispatch。
+ *  消费方（链审计器按派发子调用判定 run_code 实际写行为）双名等价命中，勿散落硬编码。 */
+export const RUN_CODE_DISPATCH_EVENT_TYPES = new Set([
+    'tool/code-dispatch-start',
+    'tool/code-dispatch',
+    'tool/ptc-dispatch-start',
+    'tool/ptc-dispatch',
+]);
+/** 该事件是否为 run_code 派发子调用事件（start 或完成，新旧事件名皆认）。 */
+export function isRunCodeDispatchEvent(e) {
+    const t = eventType(e);
+    return t !== undefined && RUN_CODE_DISPATCH_EVENT_TYPES.has(t);
+}
 /** 取 assistant 消息的网关缓存回放标记（replayState.response.responseModel，如 'from-cache'）。
  *  非 assistant/message 或无标记返回 null。2026-09-04：远程网关回复缓存整包回放时由 SSE
  *  id/model 字段透传（dsh 纯透传），插件侧据此识别缓存劫持零产出。兼容落盘（data.message）
@@ -55,3 +70,37 @@ export function isGuardSynthesizedReply(e) {
     const m = replayModel(e);
     return m !== null && GUARD_SYNTH_REPLAY_MODELS.has(m);
 }
+export function turnEndOf(e) {
+    const rec = e;
+    const t = rec?.type ?? rec?.data?.type;
+    if (t !== 'turn/end')
+        return null;
+    const reason = rec?.data?.reason ?? rec?.reason;
+    const kind = typeof reason?.kind === 'string' ? reason.kind : null;
+    if (!kind)
+        return null;
+    return {
+        turn: Number(rec?.data?.turn ?? rec?.turn) || 0,
+        kind,
+        code: typeof reason?.error?.code === 'string' ? reason.error.code : null,
+        message: typeof reason?.error?.message === 'string' ? reason.error.message : null,
+    };
+}
+/** 本轮增量（seq > fromSeq）内最后一轮 turn/end——拒答重试会产生第二轮，取 seq 最大者。
+ *  无 turn/end（测试桩/宿主变体）→ null，调用方按「无轮信息」回退原判据，不改变既有行为。 */
+export function lastTurnEnd(events, fromSeq) {
+    let best = null;
+    let bestSeq = -1;
+    for (const e of events) {
+        const rec = e;
+        const seq = Number(rec?.seq ?? rec?.data?.seq) || 0;
+        if (seq <= fromSeq)
+            continue;
+        const info = turnEndOf(e);
+        if (info && seq >= bestSeq) {
+            best = info;
+            bestSeq = seq;
+        }
+    }
+    return best;
+}

package/lib/dispatcher/v-orchestrator.d.ts

@@ -34,7 +34,9 @@ export declare function buildPhaseInstruction(phase: VPhase, ctx: {
     taskId?: string;
 }, kbMode: 'remote' | 'local'): string;
 interface AgentLike {
+    /** 宿主 UserMessage 要求 identified（id 必填）：缺 id 的消息会被 v4 会话校验拒读。 */
     followup(msg: {
+        id: string;
         content: {
             type: string;
             text: string;

package/lib/dispatcher/v-orchestrator.js

@@ -1,3 +1,4 @@
+import { randomUUID } from 'node:crypto';
 import { installRoleTools } from '../roles/toolsets.js';
 import { mountOrRecompose } from '../roles/preset-installer.js';
 import { resolveTaskParents } from '../domain/task-parents.js';
@@ -64,7 +65,7 @@ export const PHASE_INSTRUCTIONS = {
     ].join('\n'),
     dt: [
         '## DT 阶段任务体要求（实现校验+评审，只读护栏）',
-        'body 写入实现校验指令：对 D 产物实证校验（test/build/typecheck/diff/git 证据 + open-code-review 评审），输出 verdict+issues 入交接 metadata.review_evidence。评审目标为 D 交接 metadata.branch 指向的 feature 分支，而非 TARGET_BRANCH。评审引擎：用 ocr_review 工具按配置引擎评审——委托 = preview→rule→git diff 自评；托管 = managed 一次出 findings；托管未配置时按工具指引静默改走委托；ocr 未安装则 kanban_block(\'review-tool-unavailable\') 并注明可在 GUI 配置面板安装。ocr_review 的 repo 参数缺省 = 会话工作目录；评审目标不在其内（D 的 worktree / 其他仓库）时须显式传仓库绝对路径（取 D 交接 metadata.worktree_dir 或规格卡 file-prefetch 附件 ref）。',
+        'body 写入实现校验指令：对 D 产物实证校验（test/build/typecheck/diff/git 证据 + open-code-review 评审），输出 verdict+issues 入交接 metadata.review_evidence。review_evidence.test 必须带两键：exit（数字 0，键名 exit 非 exit_code）与 runner（固定 \'vitest\'，与 D 卡 gate 实测口径一致）——评审闸机械校验，键名/取值错一处即拒绝 complete。评审目标为 D 交接 metadata.branch 指向的 feature 分支，而非 TARGET_BRANCH。评审引擎：用 ocr_review 工具按配置引擎评审——委托 = preview→rule→git diff 自评；托管 = managed 一次出 findings；托管未配置时按工具指引静默改走委托；ocr 未安装则 kanban_block(\'review-tool-unavailable\') 并注明可在 GUI 配置面板安装。ocr_review 的 repo 参数缺省 = 会话工作目录；评审目标不在其内（D 的 worktree / 其他仓库）时须显式传仓库绝对路径（取 D 交接 metadata.worktree_dir 或规格卡 file-prefetch 附件 ref）。',
         '铁律：DT 是只读校验+评审角色，绝不修改源码/产物；校验经 ToolGuard 硬性只读护栏；不注入 git 凭据。',
     ].join('\n'),
     w3: [
@@ -89,7 +90,7 @@ export function buildPhaseInstruction(phase, ctx, kbMode) {
         case 'd':
             return '先读父任务交接（W2）里的 page_path（本地库 wiki/sources/ 下相对路径，库根见运行时上下文注入——Task 8 已注入 D），直接 fs 读实施计划原文；如需 KB 经验召回，经 skill 工具加载 llm-wiki query（本地库；kanban-d preset 已挂 tool-skill）——再按计划执行规格卡 solution/testing —— git worktree/branch → 改代码/README → git commit → git push（仅 feature 分支，可选）→ 自检并附产物证据（changed_files/commit_hash）。其余 TDD/TARGET_REPO/TARGET_BRANCH 等要求与 remote 版一致。';
         case 'dt':
-            return `对 D 产物实证校验（test/build/typecheck/diff/git 证据 + open-code-review 评审），输出 verdict+issues 入交接 metadata.review_evidence。评审引擎：用 ocr_review 工具按配置引擎评审（委托 = preview→rule→git diff 自评；托管 = managed 一次出 findings；托管未配置时按工具指引静默改走委托；ocr 未安装则 kanban_block('review-tool-unavailable') 并注明可在 GUI 配置面板安装）。ocr_review 的 repo 缺省 = 会话工作目录，评审目标不在其内（D 的 worktree / 其他仓库）时显式传仓库绝对路径（D 交接 metadata.worktree_dir / 规格卡 file-prefetch ref）。评审页经 fs 写本地库 <库根>/wiki/queries/${ctx.chainId}/review/<name>.md（库根已由系统注入 DT 运行时上下文）；库根外一律只读，其余铁律与 remote 版一致。`;
+            return `对 D 产物实证校验（test/build/typecheck/diff/git 证据 + open-code-review 评审），输出 verdict+issues 入交接 metadata.review_evidence。review_evidence.test 必须带两键：exit（数字 0，键名 exit 非 exit_code）与 runner（固定 'vitest'）——评审闸机械校验，键名/取值错一处即拒绝 complete。评审引擎：用 ocr_review 工具按配置引擎评审（委托 = preview→rule→git diff 自评；托管 = managed 一次出 findings；托管未配置时按工具指引静默改走委托；ocr 未安装则 kanban_block('review-tool-unavailable') 并注明可在 GUI 配置面板安装）。ocr_review 的 repo 缺省 = 会话工作目录，评审目标不在其内（D 的 worktree / 其他仓库）时显式传仓库绝对路径（D 交接 metadata.worktree_dir / 规格卡 file-prefetch ref）。评审页经 fs 写本地库 <库根>/wiki/queries/${ctx.chainId}/review/<name>.md（库根已由系统注入 DT 运行时上下文）；库根外一律只读，其余铁律与 remote 版一致。`;
         default:
             return PHASE_INSTRUCTIONS[phase] ?? '';
     }
@@ -266,7 +267,7 @@ export class VOrchestrator {
                 'gave_up 任务说明链路已停止，建议查看对应 [blocked-final] 证据链（block 时间线 + 复核/评论时间线 + 最终原因），给出终态解释。',
                 '规则：只评论、不建卡、不改任务状态；已有 [blocked-review] 评论的任务不要重复评论。',
             ].join('\n\n');
-            agent.followup({ content: [{ type: 'text', text: context }], source: { kind: 'user' } });
+            agent.followup({ id: randomUUID(), content: [{ type: 'text', text: context }], source: { kind: 'user' } });
             await agent.whenIdle();
             return; // 本轮 V 唯一动作是阻塞复核，不再推进阶段
         }
@@ -411,7 +412,7 @@ export class VOrchestrator {
             let turnError = null;
             try {
                 agent = await this.getVAgent(orch);
-                agent.followup({ content: [{ type: 'text', text: context }], source: { kind: 'user' } });
+                agent.followup({ id: randomUUID(), content: [{ type: 'text', text: context }], source: { kind: 'user' } });
                 await agent.whenIdle();
             }
             catch (err) {
@@ -619,7 +620,7 @@ export class VOrchestrator {
         // 与 agent-runner.ts 的 installRoleTools 用法一致。
         // V 后台编排会话与 P/W/D 一致，显式设置 approval=never + sandbox=workspace-write，
         // 避免在无 preset 装配时因默认审批策略在后台无应答者而挂起（卡死调度器首轮 tick）。
-        const setup = async (agentCtx) => {
+        const setup = async (agentCtx, agent) => {
             // 思考等级强制（waterfall）：与 agent-runner 同缺陷——宿主 selection 无 create-options 覆盖层，
             // agentOptions.reasoningEffort 不被消费，V 编排会话思考等级会落回宿主默认。走 DSH agent/request
             // waterfall 逐请求强制 'high'（宿主 installModelSelection 同机制），作用域仅本 V 会话。
@@ -629,7 +630,8 @@ export class VOrchestrator {
                 const resolved = await next();
                 return { ...resolved, reasoningEffort: 'high' };
             });
-            const session = agentCtx.agent?.session;
+            // approval/sandbox 种子事件经 AgentSetup 第二参的 agent 显式直写（0.2.0 起 ctx.agent 挂载已移除）。
+            const session = agent?.session;
             session?.append?.('approval/policy', { policy: 'never', source: 'delegation' });
             session?.append?.('sandbox/mode', { mode: 'workspace-write', source: 'delegation' });
             // 对齐（2026-08-17）：V=butler·orchestrator 零执行能力——先挂 kanban-v 裁剪 preset
@@ -653,9 +655,9 @@ export class VOrchestrator {
             }
             await installRoleTools(agentCtx, 'v', { kanban: this.kanban, wiki: this.wiki });
             // setup 完整成功（mount + 工具面）后写身份标记——live 复用校验依据（同 agent-runner 组合标记机制）。
-            const vAgent = agentCtx.agent;
-            if (vAgent && typeof vAgent === 'object')
-                vSessionCompositions.set(vAgent, V_SESSION_PRESET_ID);
+            // 键 = AgentSetup 第二参的 Agent 实例（与发布后 agents.get(id) 返回同一实例）。
+            if (agent)
+                vSessionCompositions.set(agent, V_SESSION_PRESET_ID);
         };
         // 模型候选链：V 会话 create/resume 按 primary→fallbacks 静默切换；
         // V 无任务卡可 block——全候选不可用抛最后错误（wakeV 调用方按既有错误路径处理）。

package/lib/domain/review-evidence.js

@@ -39,8 +39,9 @@ export function validateReviewEvidence(role, handoff) {
         // DT：实证校验证据（fail 评审同样必须已实证——test 字段必须存在；仅 pass 要求 exit 0）
         if (!ev.test || typeof ev.test !== 'object')
             missing.push('review_evidence.test');
+        // 报错文案带明确键名：agent 不读源码也能一轮自纠（exit_code 等别名一律不收）
         else if (ev.verdict === 'pass' && ev.test['exit'] !== 0)
-            missing.push('review_evidence.test (exit 0)');
+            missing.push('review_evidence.test.exit 必须为数字 0（键名 exit，非 exit_code；pass 门槛）');
         const buildOk = ev.build && typeof ev.build === 'object';
         const tcOk = ev.typecheck && typeof ev.typecheck === 'object';
         if (!buildOk && !tcOk)
@@ -76,7 +77,7 @@ export function validateReviewEvidence(role, handoff) {
                 missing.push('review_evidence.tdd (test_files)');
             }
             if (ev.test && typeof ev.test === 'object' && ev.test['runner'] !== 'vitest') {
-                missing.push('review_evidence.test (runner=vitest)');
+                missing.push("review_evidence.test.runner 必须为 'vitest'（键名 runner，与 D 卡 gate 实测口径一致）");
             }
             if (ev.verdict === 'pass' && tdd.test_first !== true) {
                 missing.push('review_evidence.tdd (test_first=true)');

package/lib/index.js

@@ -36,10 +36,13 @@ export function apply(ctx, config) {
     const configProvider = new ConfigProvider(ctx, config, storageDir);
     // KanbanProvider 持 ConfigProvider 引用，kb_url base 经 getter 热读取（配置面板改后无需重建）。
     const provider = new KanbanProvider(ctx, config, configProvider);
-    // 把包内角色裁剪 preset 组合安装到 $DSH_HOME/.agent-presets/（真实 API 下唯一可发现的自定义根）。
-    const installed = installRolePresets();
+    // 双路安装角色裁剪 preset：目录写 $DSH_HOME/.agent-presets/（0.1.7-rc.x 宿主发现根）+
+    // 运行时注册 agentPresets.register（0.2.0 宿主唯一生效路径）。注册等服务就绪后完成，
+    // 由 installer 如实记录「目录写 / 运行时注册」各自清单，不假阳性。
+    void installRolePresets(ctx).catch((err) => {
+        console.warn('[dsh-swarm] role preset install error: ' + String(err));
+    });
     installLlWikiSkill(); // 尽力而为：失败仅告警不阻断
-    console.info('[dsh-swarm] role presets installed: ' + (installed.length ? installed.join(',') : 'none'));
     // IM 投递（企微，2026-09-07 评审决议）：W3 收尾/链阻塞时经 dsh-im 投群。
     // imDelivery.enabled=false（默认）时事件处理器零开销早退；dshIm 服务缺失显式降级留痕。
     const disposeImDelivery = wireImDelivery(ctx, provider.service, configProvider);

package/lib/roles/preset-installer.d.ts

@@ -1,11 +1,56 @@
 /** 包内组合目录（随包分发）。src/roles/ 与 lib/roles/ 深度一致，均经 ../../ 回到包根。 */
 export declare function packagePresetsDir(): string;
-/** $DSH_HOME/.agent-presets（agent-presets 服务 includeUserRoot 派生根；DSH_HOME 缺省 ~/.dsh）。 */
+/** $DSH_HOME/.agent-presets（0.1.7-rc.x 宿主用户预设根；DSH_HOME 缺省 ~/.dsh）。 */
 export declare function userPresetsRoot(): string;
-/** 安装角色裁剪 preset 到用户预设根；返回成功安装的 preset id 列表（空=无随包组合）。
- *  尽力而为：单 preset 写失败（用户预设根不可写等）仅告警不抛出，
- *  后续 agentPresets.mount('kanban-<role>') 失败由 runner 降级日志兜底。 */
-export declare function installRolePresets(): string[];
+/** 单条 preset 组合行（官方 PresetDefinition.plugins 行的结构面：cordis entry list）。 */
+export interface PresetPluginRow {
+    readonly id?: string;
+    readonly name: string;
+    readonly config?: unknown;
+    readonly disabled?: unknown;
+}
+/** 注册给宿主 registry 的 preset 定义（官方 PresetDefinition 的结构面）。 */
+export interface PresetDefinitionLike {
+    readonly id: string;
+    readonly name?: string;
+    readonly description?: string;
+    readonly order?: number;
+    readonly plugins: readonly PresetPluginRow[];
+}
+/** 宿主 agentPresets registry 的结构面（本插件只消费 register）。 */
+export interface PresetRegistryLike {
+    register(definition: PresetDefinitionLike): Promise<() => Promise<void>>;
+}
+/** 安装期 ctx 的最小面（只需可选 get）。 */
+export interface PresetCtxLike {
+    get?(name: string): unknown;
+}
+/** 解析包内单个 preset 的组合与元数据为宿主 registry 定义；组合缺失返回 undefined。 */
+export declare function readPresetDefinition(pkgDir: string, id: string): PresetDefinitionLike | undefined;
+/** 路径二：运行时注册全部包内 preset；返回注册成功/失败 id 列表与成功项的撤销句柄（组合缺失的 id 不计）。 */
+export declare function registerRolePresets(registry: PresetRegistryLike, ids: readonly string[], pkgDir?: string): Promise<{
+    registered: string[];
+    failed: string[];
+    disposers: Array<() => Promise<void>>;
+}>;
+/** 安装结果（如实区分两条路径，不假阳性）。 */
+export interface RolePresetInstallReport {
+    /** 目录写成功的 preset id（路径一）。 */
+    dirWritten: string[];
+    /** 运行时注册成功的 preset id（路径二；服务不可用时为空）。 */
+    runtimeRegistered: string[];
+    /** 运行时注册失败的 preset id。 */
+    runtimeFailed: string[];
+    /** 路径二实际形态：runtime=已注册；unavailable=宿主无 agentPresets 服务（仅目录写生效）。 */
+    runtimeMode: 'runtime' | 'unavailable';
+}
+/**
+ * 双路安装入口。目录写同步完成并即时留痕；运行时注册等服务就绪后完成并留痕。
+ * 返回前目录写已落盘；注册部分异步收敛（fire-and-forget 调用方须 catch）。
+ */
+export declare function installRolePresets(ctx: PresetCtxLike, opts?: {
+    registerWaitMs?: number;
+}): Promise<RolePresetInstallReport>;
 /** 角色 preset 挂载的容器面（dsh-agent-presets roster 的最小结构类型）。 */
 export interface PresetMountLike {
     mount(ctx: unknown, id: string): Promise<unknown>;

package/lib/roles/preset-installer.js

@@ -1,36 +1,103 @@
 // src/roles/preset-installer.ts
-import { copyFileSync, existsSync, mkdirSync } from 'node:fs';
+import { copyFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { JSON_SCHEMA, load as loadYaml, Type } from 'js-yaml';
 /**
- * 角色裁剪 preset 的运行时安装（2026-08-15 取舍记录）：
- * - 组合文件随包分发（personas/kanban-{v,p,w,d}/agent.cordis.yml，随 npm 包分发）。
- *   kanban-v 于 2026-08-17 补充：V=butler·orchestrator 零执行能力，组合仅 persona+instructions。
- * - 官方 dsh-agent-presets 的 roots 在 web 启动的 composeProfile 中被强制覆盖为
- *   官方 shipped root 单一路径（profile-boot 内 SHIPPED_PRESET_ROOT 硬编码），
- *   因此 cordis.patch.yml 追加 roots 指向包内目录在真实 API 下无效；
- *   唯一可发现的自定义根是 includeUserRoot 派生的 `$DSH_HOME/.agent-presets`。
- * - 故插件 apply 时把包内组合复制到 `$DSH_HOME/.agent-presets/<id>/`，
- *   agentPresets.mount(agentCtx, 'kanban-v'|'kanban-p'|'kanban-w'|'kanban-d') 即可解析。
- * - 幂等：重复安装覆盖同名文件；缺组合文件（未随包）则跳过并让 runner 降级日志。
+ * 角色裁剪 preset 的双路安装：
+ *
+ * 路径一 · 目录写（0.1.7-rc.x 宿主的底线）：把包内组合复制到 `$DSH_HOME/.agent-presets/<id>/`，
+ * 老宿主的 agent-presets 发现逻辑扫该目录完成装载。0.2.0 宿主不再扫描任何目录，此路不影响新宿主。
+ *
+ * 路径二 · 运行时注册（0.2.0 起的唯一生效路径）：0.2.0 的 dsh-agent-preset-registry 是纯运行时
+ * 服务，preset 定义只经 `agentPresets.register(definition)` 进入（官方 dsh-agent-preset 插件
+ * 即在 Service.init 中 yield register(config)），无任何目录发现。本插件经 ctx 取 agentPresets
+ * 服务（未就绪则短轮询等待），把与目录写同一份 yml 解析出的定义注册进去，两个路径语义同源。
+ *
+ * 幂等：目录写覆盖同名文件；运行时注册遇宿主 "Duplicate agent preset" 视为已注册成功。
+ * 尽力而为：单 preset 目录写/注册失败仅告警不阻断插件启动，后续挂载失败由 runner 降级日志兜底。
  */
 const PRESET_IDS = ['kanban-v', 'kanban-p', 'kanban-w', 'kanban-d', 'kanban-pt', 'kanban-dt', 'swarm'];
+/** 等待 agentPresets 服务就绪的超时（宿主组合启动期服务装配可能晚于插件 apply）。 */
+const REGISTER_WAIT_MS = 60000;
 /** 包内组合目录（随包分发）。src/roles/ 与 lib/roles/ 深度一致，均经 ../../ 回到包根。 */
 export function packagePresetsDir() {
     return fileURLToPath(new URL('../../personas/', import.meta.url));
 }
-/** $DSH_HOME/.agent-presets（agent-presets 服务 includeUserRoot 派生根；DSH_HOME 缺省 ~/.dsh）。 */
+/** $DSH_HOME/.agent-presets（0.1.7-rc.x 宿主用户预设根；DSH_HOME 缺省 ~/.dsh）。 */
 export function userPresetsRoot() {
     return join(process.env.DSH_HOME ?? join(homedir(), '.dsh'), '.agent-presets');
 }
-/** 安装角色裁剪 preset 到用户预设根；返回成功安装的 preset id 列表（空=无随包组合）。
- *  尽力而为：单 preset 写失败（用户预设根不可写等）仅告警不抛出，
- *  后续 agentPresets.mount('kanban-<role>') 失败由 runner 降级日志兜底。 */
-export function installRolePresets() {
+// 宿主 entry-list YAML 方言的镜像（@deepseek-ai/cordis-plugin-include 的 entryListSchema）：
+// `!!js` 标量解析为 { __jsExpr } 表达式节点，由宿主 Loader 在行激活时求值（组合内
+// `disabled: !!js process.platform === 'win32'` 等行依赖此节点形态，禁在解析期求值）。
+const JS_EXPR_TAG = new Type('tag:yaml.org,2002:js', {
+    kind: 'scalar',
+    resolve: (data) => typeof data === 'string',
+    construct: (data) => ({ __jsExpr: data }),
+});
+const ENTRY_LIST_SCHEMA = JSON_SCHEMA.extend(JS_EXPR_TAG);
+/** 镜像宿主 registry 的入口列表形状校验：顶层为带 name 的行数组（组行递归其 config）。 */
+function entryListProblem(rows, at = '') {
+    if (!Array.isArray(rows))
+        return at === '' ? 'composition must be a top-level list of plugin rows' : `group ${at} must hold a list of plugin rows`;
+    for (const [index, row] of rows.entries()) {
+        const label = at === '' ? `row ${String(index + 1)}` : `${at} row ${String(index + 1)}`;
+        if (typeof row !== 'object' || row === null || Array.isArray(row))
+            return `${label} is not a plugin row`;
+        const name = row.name;
+        if (typeof name !== 'string' || name === '')
+            return `${label} names no plugin (a "name" string is required)`;
+        const config = row.config;
+        if (row.group === true && config !== undefined) {
+            const nested = entryListProblem(config, label);
+            if (nested !== undefined)
+                return nested;
+        }
+    }
+    return undefined;
+}
+/** 解析包内单个 preset 的组合与元数据为宿主 registry 定义；组合缺失返回 undefined。 */
+export function readPresetDefinition(pkgDir, id) {
+    const srcFile = join(pkgDir, id, 'agent.cordis.yml');
+    if (!existsSync(srcFile))
+        return undefined;
+    let rows;
+    let meta;
+    try {
+        rows = loadYaml(readFileSync(srcFile, 'utf8'), { schema: ENTRY_LIST_SCHEMA });
+        const metaFile = join(pkgDir, id, 'preset.yml');
+        meta = existsSync(metaFile)
+            ? loadYaml(readFileSync(metaFile, 'utf8'), { schema: JSON_SCHEMA })
+            : {};
+    }
+    catch (err) {
+        console.warn('[dsh-swarm] role preset parse failed ' + id + ': ' + String(err));
+        return undefined;
+    }
+    const problem = entryListProblem(rows);
+    if (problem !== undefined) {
+        console.warn('[dsh-swarm] role preset composition invalid ' + id + ': ' + problem);
+        return undefined;
+    }
+    const definition = {
+        id,
+        plugins: rows,
+    };
+    if (typeof meta.name === 'string')
+        definition.name = meta.name;
+    if (typeof meta.description === 'string')
+        definition.description = meta.description;
+    if (typeof meta.order === 'number')
+        definition.order = meta.order;
+    return definition;
+}
+/** 路径一：目录写（0.1.7-rc.x 宿主发现根）。返回成功写入的 preset id 列表。 */
+function writeUserDirPresets() {
     const src = packagePresetsDir();
     const dstRoot = userPresetsRoot();
-    const installed = [];
+    const written = [];
     for (const id of PRESET_IDS) {
         const srcFile = join(src, id, 'agent.cordis.yml');
         if (!existsSync(srcFile))
@@ -42,14 +109,81 @@ export function installRolePresets() {
             const meta = join(src, id, 'preset.yml');
             if (existsSync(meta))
                 copyFileSync(meta, join(dstDir, 'preset.yml'));
-            installed.push(id);
+            written.push(id);
         }
         catch (err) {
             // 尽力而为：写入失败（如沙箱/权限拒绝）仅告警，不阻断插件启动
-            console.warn('[dsh-swarm] role preset install skipped ' + id + ' -> ' + dstRoot + ': ' + String(err));
+            console.warn('[dsh-swarm] role preset dir write skipped ' + id + ' -> ' + dstRoot + ': ' + String(err));
         }
     }
-    return installed;
+    return written;
+}
+/** 路径二：运行时注册全部包内 preset；返回注册成功/失败 id 列表与成功项的撤销句柄（组合缺失的 id 不计）。 */
+export async function registerRolePresets(registry, ids, pkgDir = packagePresetsDir()) {
+    const registered = [];
+    const failed = [];
+    const disposers = [];
+    for (const id of ids) {
+        const definition = readPresetDefinition(pkgDir, id);
+        if (!definition)
+            continue;
+        try {
+            disposers.push(await registry.register(definition));
+            registered.push(id);
+        }
+        catch (err) {
+            // 插件重 apply 时定义已在 registry：与首次注册语义等价，按成功计
+            if (String(err).includes('Duplicate agent preset')) {
+                registered.push(id);
+                continue;
+            }
+            failed.push(id);
+            console.warn('[dsh-swarm] role preset runtime register failed ' + id + ': ' + String(err));
+        }
+    }
+    return { registered, failed, disposers };
+}
+/** 短轮询等待宿主 agentPresets 服务就绪；超时返回 undefined（降级仅目录写）。 */
+async function waitForPresets(ctx, timeoutMs) {
+    const started = Date.now();
+    return new Promise((resolve) => {
+        const poll = setInterval(() => {
+            const found = ctx.get?.('agentPresets');
+            if (found) {
+                clearInterval(poll);
+                resolve(found);
+            }
+            else if (Date.now() - started >= timeoutMs) {
+                clearInterval(poll);
+                resolve(undefined);
+            }
+        }, 500);
+    });
+}
+/**
+ * 双路安装入口。目录写同步完成并即时留痕；运行时注册等服务就绪后完成并留痕。
+ * 返回前目录写已落盘；注册部分异步收敛（fire-and-forget 调用方须 catch）。
+ */
+export async function installRolePresets(ctx, opts = {}) {
+    const dirWritten = writeUserDirPresets();
+    console.info('[dsh-swarm] role preset dir write: ' + (dirWritten.length ? dirWritten.join(',') : 'none'));
+    const registry = await waitForPresets(ctx, opts.registerWaitMs ?? REGISTER_WAIT_MS);
+    if (!registry) {
+        console.warn('[dsh-swarm] role presets installed: dir-write=' + (dirWritten.join(',') || 'none')
+            + ' runtime-register=none (agentPresets service unavailable; directory write only)');
+        return { dirWritten, runtimeRegistered: [], runtimeFailed: [], runtimeMode: 'unavailable' };
+    }
+    const { registered, failed, disposers } = await registerRolePresets(registry, PRESET_IDS);
+    console.info('[dsh-swarm] role presets installed: dir-write=' + (dirWritten.join(',') || 'none')
+        + ' runtime-register=' + (registered.join(',') || 'none')
+        + (failed.length ? ' failed=' + failed.join(',') : ''));
+    // 插件卸载/重载时撤销注册，避免宿主 registry 留下失效定义（官方 register 契约：声明方持有 disposer）。
+    ctx.on?.('dispose', () => {
+        for (const dispose of disposers.splice(0))
+            void dispose().catch(() => { });
+    });
+    const report = { dirWritten, runtimeRegistered: registered, runtimeFailed: failed, runtimeMode: 'runtime' };
+    return report;
 }
 /**
  * preset 挂载收敛入口（2026-09-21 事故修复）：宿主 dsh-scope 的 scope key 绑定在进程

package/lib/routes/kanban-http.js

@@ -2,7 +2,8 @@ import { credentialRef } from '@deepseek-ai/dsh-credentials';
 import { execFile } from 'node:child_process';
 import { writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { buildLlmCatalog } from '../services/llm-catalog.js';
+import { buildLlmCatalog, filterCandidatesByCatalog } from '../services/llm-catalog.js';
+import { ROLES } from '../domain/config-override.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';
@@ -323,6 +324,27 @@ export function registerKanbanHttp(ctx, provider, configProvider, llm, config, o
                         },
                         imDelivery: { fallbackBotId: raw.imDelivery?.fallbackBotId ?? cur.imDelivery?.fallbackBotId ?? '' },
                     };
+                    // 模型配置保存口预检（堵源头）：角色模型与 managed 评审组合 (provider, model, effort)
+                    // 与 LLM 目录比对，确认不匹配 → 400 附明细。与派发前预检（agent-runner 消费同一目录）
+                    // 同口径——跨层拼接的死组合（provider/model 来自不同层）在保存时即被拦下，不再流入派发。
+                    // fail-open：llm 运行时缺失/目录探测失败放行（网络抖动 ≠ 配置错误），不阻断无关字段保存。
+                    const toProbe = [];
+                    for (const role of ROLES) {
+                        const m = snapshot.roles.models[role];
+                        if (m?.provider?.trim() && m?.model?.trim())
+                            toProbe.push({ provider: m.provider, model: m.model, reasoningEffort: m.reasoningEffort });
+                    }
+                    if (snapshot.reviewEngine.mode === 'managed' && snapshot.reviewEngine.managed.provider.trim() && snapshot.reviewEngine.managed.model.trim()) {
+                        toProbe.push({ provider: snapshot.reviewEngine.managed.provider, model: snapshot.reviewEngine.managed.model });
+                    }
+                    const catalogProbe = await filterCandidatesByCatalog(llm, toProbe);
+                    if (catalogProbe.rejected.length > 0) {
+                        json(res, 400, {
+                            error: 'validation failed',
+                            fields: catalogProbe.rejected.map((r) => `${r.candidate.provider}/${r.candidate.model}: ${r.reason}`),
+                        });
+                        return;
+                    }
                     const r = configProvider.applyOverride(snapshot);
                     if (!r.ok) {
                         json(res, 400, { error: 'validation failed', fields: r.errors });

package/lib/services/llm-catalog.d.ts

@@ -33,3 +33,21 @@ export interface LlmRuntimeLike {
     }>;
 }
 export declare function buildLlmCatalog(llm: LlmRuntimeLike): Promise<LlmCatalog>;
+/** 候选模型（与 dispatcher AgentModelOptions 结构同形；不 import 防环）。 */
+export interface ModelCandidateLike {
+    provider: string;
+    model: string;
+    reasoningEffort?: string;
+}
+export interface CandidateReject {
+    candidate: ModelCandidateLike;
+    reason: string;
+}
+/** 派发/保存前候选预校验：provider 已配置、model 属该 provider、reasoningEffort ∈ 模型声明集。
+ *  fail-open 原则：运行时缺失、provider 枚举失败、单候选探测异常一律放行——只拦「确实查到
+ *  不匹配」的组合，目录不可达（网络抖动）≠ 配置错误，不应阻断派发/保存。
+ *  effort 声明集为空（resolveModelInfo 降级）时跳过 effort 把关。 */
+export declare function filterCandidatesByCatalog(runtime: LlmRuntimeLike | undefined, candidates: readonly ModelCandidateLike[]): Promise<{
+    ok: ModelCandidateLike[];
+    rejected: CandidateReject[];
+}>;

package/lib/services/llm-catalog.js

@@ -17,3 +17,44 @@ export async function buildLlmCatalog(llm) {
     }
     return { providers, models };
 }
+/** 派发/保存前候选预校验：provider 已配置、model 属该 provider、reasoningEffort ∈ 模型声明集。
+ *  fail-open 原则：运行时缺失、provider 枚举失败、单候选探测异常一律放行——只拦「确实查到
+ *  不匹配」的组合，目录不可达（网络抖动）≠ 配置错误，不应阻断派发/保存。
+ *  effort 声明集为空（resolveModelInfo 降级）时跳过 effort 把关。 */
+export async function filterCandidatesByCatalog(runtime, candidates) {
+    if (!runtime || candidates.length === 0)
+        return { ok: [...candidates], rejected: [] };
+    let providerIds;
+    try {
+        providerIds = new Set(runtime.listProviders().map((p) => p.id));
+    }
+    catch {
+        return { ok: [...candidates], rejected: [] };
+    }
+    const ok = [];
+    const rejected = [];
+    for (const c of candidates) {
+        try {
+            if (!providerIds.has(c.provider)) {
+                rejected.push({ candidate: c, reason: `provider "${c.provider}" 未配置` });
+                continue;
+            }
+            const models = await runtime.listModels(c.provider);
+            if (!models.some((m) => m.id === c.model)) {
+                rejected.push({ candidate: c, reason: `provider "${c.provider}" 无模型 "${c.model}"` });
+                continue;
+            }
+            const info = await runtime.resolveModelInfo(c.provider, c.model).catch(() => undefined);
+            const efforts = (info?.reasoning?.efforts ?? []).map((e) => e.id);
+            if (efforts.length > 0 && c.reasoningEffort && !efforts.includes(c.reasoningEffort)) {
+                rejected.push({ candidate: c, reason: `模型 "${c.model}" 不支持 reasoningEffort "${c.reasoningEffort}"（声明：${efforts.join('/')}）` });
+                continue;
+            }
+            ok.push(c);
+        }
+        catch {
+            ok.push(c); // 单候选探测异常 fail-open
+        }
+    }
+    return { ok, rejected };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joekytc/dsh-swarm",
-  "version": "0.3.11",
+  "version": "0.5.0",
   "description": "A governed swarm of six specialist DSH agents (orchestrator, planner, knowledge-base bridge, developer and two reviewers) that turns a requirement into a strict phase pipeline with machine-verified delivery evidence, review-gated merges, a full audit-log event stream and a live kanban tab; design inspired by the Hermes Agent kanban",
   "license": "MIT",
   "author": "joekytc",
@@ -33,7 +33,8 @@
     "client": {
       "platform": "web",
       "inject": [
-        "@deepseek-ai/dsh-client-ui-conversation"
+        "@deepseek-ai/dsh-client-ui-conversation",
+        "@deepseek-ai/dsh-client-ui-workspace"
       ]
     }
   },
@@ -58,27 +59,32 @@
     "test": "vitest run",
     "build:client": "node scripts/build-client.mjs"
   },
+  "dependencies": {
+    "js-yaml": "^4.3.2"
+  },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-agent": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-api-session-controller": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-client-ui-conversation": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-credentials": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-persona": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-session": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-tool-bash": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-tool-fs": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-tool-fs-search": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-tools": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-util-values": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-agent": "~0.1.7-rc.2 || ^0.2.0-rc.2",
+    "@deepseek-ai/dsh-api-session-controller": "~0.1.7-rc.2 || ^0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-conversation": "~0.1.7-rc.2 || ^0.2.0-rc.2",
+    "@deepseek-ai/dsh-credentials": "~0.1.7-rc.2 || ^0.2.0-rc.2",
+    "@deepseek-ai/dsh-persona": "~0.1.7-rc.2 || ^0.2.0-rc.2",
+    "@deepseek-ai/dsh-session": "~0.1.7-rc.2 || ^0.2.0-rc.2",
+    "@deepseek-ai/dsh-tool-bash": "~0.1.7-rc.2 || ^0.2.0-rc.2",
+    "@deepseek-ai/dsh-tool-fs": "~0.1.7-rc.2 || ^0.2.0-rc.2",
+    "@deepseek-ai/dsh-tool-fs-search": "~0.1.7-rc.2 || ^0.2.0-rc.2",
+    "@deepseek-ai/dsh-tools": "~0.1.7-rc.2 || ^0.2.0-rc.2",
+    "@deepseek-ai/dsh-util-values": "~0.1.7-rc.2 || ^0.2.0-rc.2",
     "@deepseek-ai/schemastery": "^3.18.1"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-client-store": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-client-ui-layout": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-client-ui-slots": "^0.1.2-rc.1",
+    "@deepseek-ai/cordis-plugin-include": "^1.0.9",
+    "@deepseek-ai/dsh-client-store": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-layout": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.2.0-rc.2",
     "@testing-library/dom": "^10.4.0",
     "@testing-library/react": "^16.1.0",
+    "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.0.0",
     "@types/react": "^18.3.0",
     "@types/react-dom": "^18.3.0",

package/personas/kanban-d/agent.cordis.yml

@@ -12,7 +12,7 @@
 - id: persona
   name: '@deepseek-ai/dsh-persona'
   config:
-    text: >-
+    prefix: >-
       You are the fullstack development agent (the ONLY executor) powered by the {{model}} model.
       Your working directory is {{cwd}}. You implement and test the aligned spec; you are
       the sole accountable executor and may delegate implementation subtasks. Rules:
@@ -134,12 +134,14 @@
   config:
     provider: spawn
     toolName: subagent
+    maxDepth: 3
 
 - id: tool-subagent-fork
   name: '@deepseek-ai/dsh-tool-subagent'
   config:
     provider: fork
     toolName: subagent_fork
+    maxDepth: 3
 
 - id: tool-subagent-control
   name: '@deepseek-ai/dsh-tool-subagent-control'

package/personas/kanban-dt/agent.cordis.yml

@@ -11,7 +11,7 @@
 - id: persona
   name: '@deepseek-ai/dsh-persona'
   config:
-    text: >-
+    prefix: >-
       You are the implementation verifier + reviewer agent (read-only) powered by the {{model}}
       model. Your working directory is {{cwd}}. You empirically verify D's implementation and
       review it — you never modify source and you never execute writes. Rules:
@@ -59,6 +59,10 @@
       { verdict: 'pass'|'fail', issues: [...], test/build/typecheck/lint/diff/git/
       openCodeReview/reviewPage }: pass = all six checks pass (system advances to W3);
       fail = critical/high unresolved (system creates a D rework task + fresh review card).
+      test must carry two mechanically-gated keys (wrong key name or value rejects the
+      complete call): test = { exit: 0, runner: 'vitest', targeted/full } — the key is
+      exit (a number, never exit_code) and runner is fixed to 'vitest' (same runner the
+      D-side gate actually runs).
       6. Never call kanban_create; only complete/block/comment your own bound task.
 
 - id: agent-instructions
@@ -91,3 +95,4 @@
   config:
     provider: spawn
     toolName: subagent
+    maxDepth: 3

package/personas/kanban-p/agent.cordis.yml

@@ -15,7 +15,7 @@
 - id: persona
   name: '@deepseek-ai/dsh-persona'
   config:
-    text: >-
+    prefix: >-
       You are the planning agent (planner) powered by the {{model}} model. Your working
       directory is {{cwd}}. You produce the implementation plan only — you are NOT the
       executor. When injected repo facts are insufficient, you may do READ-ONLY self-inspection

package/personas/kanban-pt/agent.cordis.yml

@@ -9,7 +9,7 @@
 - id: persona
   name: '@deepseek-ai/dsh-persona'
   config:
-    text: >-
+    prefix: >-
       You are the plan-review agent (read-only) powered by the {{model}} model. Your working
       directory is {{cwd}}. You review P's plan deliverable only — you never modify any artifact
       and you never execute code. Rules:

package/personas/kanban-v/agent.cordis.yml

@@ -12,7 +12,7 @@
 - id: persona
   name: '@deepseek-ai/dsh-persona'
   config:
-    text: >-
+    prefix: >-
       You are the orchestration agent (butler) powered by the {{model}} model. Your working
       directory is {{cwd}}. You only decompose, dispatch and summarize — you are NEVER the executor.
       Rules:

package/personas/kanban-w/agent.cordis.yml

@@ -12,7 +12,7 @@
 - id: persona
   name: '@deepseek-ai/dsh-persona'
   config:
-    text: >-
+    prefix: >-
       You are the knowledge officer (Knowledge Officer) powered by the {{model}} model. Your
       working directory is {{cwd}}. You curate the requirement knowledge base (KB) in one of two
       modes (the active mode and the local KB root, when local, are stated in your task context);

package/personas/persona-dt.md

@@ -9,6 +9,7 @@
 3. 评审引擎由配置面板 reviewEngine.mode 决定（默认委托）：①委托 = 调 ocr_review{sub:'preview'} 获取评审范围 → ocr_review{sub:'rule'} 获取各文件评审规则 → 自行 git diff 逐文件深入评审 → 按严重级归类（Critical/High 必报、Medium 带上下文、Low 默认丢弃）；②托管 = 调 ocr_review{sub:'managed', from:<TARGET_BRANCH>, to:<branch>} 一次出归一化 findings（branch 取 D 交接 metadata.branch；可带 background 传业务上下文，从规格卡/任务描述提炼一句话背景），status 非 completed 或返回托管未配置指引时静默改走委托流程。
 4. wiki 只读 + 写仅限 `projects/<repoSlug>/<chain>/review/` 评审命名空间（repoSlug 由系统按链工作区派生；写评审结论/证据链，不替代 W 的产物同步）。
 5. 评审结论写进 kanban_complete 的交接 metadata.review_evidence = { verdict: 'pass'|'fail', issues: [...], test/build/typecheck/lint/diff/git/openCodeReview/reviewPage }：
+   - test 必须带两键（评审闸机械校验，键名/取值错一处即拒绝 complete）：test = { exit: 0, runner: 'vitest', targeted/full }——键名是 `exit`（数字，非 exit_code），`runner` 固定 'vitest'（与 D 卡 gate 实测口径一致）。
    - pass = 六项校验全过 → 系统推进 W3；
    - fail = critical/high 未处置 → 系统 createReworkTask 让 D 返工 + 新建复审卡。
 6. 不得调用 kanban_create；只可 complete/block/comment 本任务（会话绑定）。

package/personas/swarm/agent.cordis.yml

@@ -6,7 +6,7 @@
 - id: persona
   name: '@deepseek-ai/dsh-persona'
   config:
-    text: >-
+    prefix: >-
       你是蜂群模式的领队。本模式下你负责把「要动手开发的需求」转化为一条多角色工作流链并跟进到交付；其余对话正常应答。
 
       ## 分流判定（每轮先判）