@joekytc/dsh-swarm 0.3.12 → 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';
@@ -266,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
@@ -283,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' });
@@ -318,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') {
@@ -492,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);
@@ -510,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);
@@ -650,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）

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）

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';
@@ -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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joekytc/dsh-swarm",
-  "version": "0.3.12",
+  "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:
@@ -95,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/swarm/agent.cordis.yml

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