@joekytc/dsh-swarm 0.1.0

package/lib/routes/kanban-http.js

@@ -0,0 +1,159 @@
+import { serveKanbanEvents } from './kanban-sse.js';
+function json(res, status, body) {
+    res.statusCode = status;
+    res.setHeader('content-type', 'application/json; charset=utf-8');
+    res.end(JSON.stringify(body));
+}
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        req.on('data', (c) => chunks.push(c));
+        req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+        req.on('error', reject);
+    });
+}
+/** 看板 HTTP 桥（Web GUI 浏览器半消费）：GET /kanban/board 读快照；POST /kanban/action 执行状态操作。
+ *  仅在 webServer 服务存在时挂载（CLI/headless/测试裸 Context 不挂）。 */
+export function registerKanbanHttp(ctx, provider, config) {
+    // 可选服务：经 ctx.get 读取（cordis 4 直接属性读取需 inject；get 不需要）
+    const webServer = ctx.get('webServer');
+    if (!webServer)
+        return;
+    webServer.register({
+        kind: 'prefix',
+        path: '/kanban',
+        async handler(req, res) {
+            try {
+                if (req.method === 'GET' && req.url?.startsWith('/kanban/board')) {
+                    const state = await provider.service.snapshot();
+                    json(res, 200, {
+                        chains: [...state.chains.values()],
+                        tasks: [...state.tasks.values()],
+                        specCards: [...state.specCards.values()],
+                        handoffs: [...state.handoffs.entries()].map(([k, v]) => ({ id: k, ...v })),
+                        auditWarnings: [...state.auditWarnings.entries()].map(([k, v]) => ({ chainId: k, ...v })),
+                        events: state.events,
+                        lastSeq: state.events.at(-1)?.seq ?? -1,
+                    });
+                    return;
+                }
+                if (req.method === 'GET' && req.url?.startsWith('/kanban/events')) {
+                    const heartbeatMs = (config?.ui.sseHeartbeatSeconds ?? 20) * 1000;
+                    await serveKanbanEvents(req, res, provider.service, { heartbeatMs });
+                    return;
+                }
+                if (req.method === 'POST' && req.url?.startsWith('/kanban/action')) {
+                    const body = JSON.parse((await readBody(req)) || '{}');
+                    // D23：confirm-audit 是链级 action（无 taskId），提前分流处理
+                    if (body.type === 'confirm-audit') {
+                        const chainId = String(body.chainId ?? '').trim();
+                        if (!chainId) {
+                            json(res, 400, { error: 'chainId required' });
+                            return;
+                        }
+                        await provider.service.confirmAudit(chainId, 'human');
+                        json(res, 200, { ok: true });
+                        return;
+                    }
+                    // 整链硬删除（仅 human；GUI 二次确认）：purge 无事件流，客户端需自行 resync
+                    if (body.type === 'delete') {
+                        const chainId = String(body.chainId ?? '').trim();
+                        if (!chainId) {
+                            json(res, 400, { error: 'chainId required' });
+                            return;
+                        }
+                        await provider.service.deleteChain(chainId, 'human');
+                        json(res, 200, { ok: true });
+                        return;
+                    }
+                    // T7：rename 是链级或任务级 action（chainId 或 taskId 二选一），在 taskId 守卫前分流
+                    if (body.type === 'rename') {
+                        const title = String(body.title ?? '').trim();
+                        if (!title) {
+                            json(res, 400, { error: 'title required' });
+                            return;
+                        }
+                        if (body.chainId)
+                            await provider.service.updateChainTitle(String(body.chainId), title, 'human');
+                        else if (body.taskId)
+                            await provider.service.renameTask(String(body.taskId), title, 'human');
+                        else {
+                            json(res, 400, { error: 'chainId or taskId required' });
+                            return;
+                        }
+                        json(res, 200, { ok: true });
+                        return;
+                    }
+                    const t = body.taskId;
+                    if (!t) {
+                        json(res, 400, { error: 'taskId required' });
+                        return;
+                    }
+                    switch (body.type) {
+                        case 'block': {
+                            const reason = String(body.reason ?? '').trim();
+                            if (!reason) {
+                                json(res, 400, { error: 'reason required' });
+                                return;
+                            }
+                            await provider.service.blockTask(t, reason, 'human');
+                            break;
+                        }
+                        case 'unblock':
+                            await provider.service.unblockTask(t, 'human');
+                            break;
+                        case 'retry': {
+                            // T32 fix：retry 走 runner（failed→claim→spawn/resume），而非只 claim 造成 running 悬挂
+                            const state = await provider.service.snapshot();
+                            const task = state.tasks.get(t);
+                            if (!task) {
+                                json(res, 404, { error: 'unknown task: ' + t });
+                                return;
+                            }
+                            if (task.status !== 'failed') {
+                                json(res, 409, { error: 'invalid state: task ' + t + ' is ' + task.status + ', only failed tasks can be retried' });
+                                return;
+                            }
+                            if (!provider.runner) {
+                                json(res, 503, { error: 'dispatcher not ready' });
+                                return;
+                            }
+                            void provider.runner.runTask(t).catch((err) => { console.error('[dsh-swarm] retry dispatch failed: ' + String(err)); });
+                            break;
+                        }
+                        case 'complete': {
+                            const summary = String(body.summary ?? '').trim();
+                            if (!summary) {
+                                json(res, 400, { error: 'summary required' });
+                                return;
+                            }
+                            await provider.service.completeTask(t, { summary, metadata: body.metadata ?? {}, completedAt: Date.now() }, 'human');
+                            break;
+                        }
+                        case 'archive':
+                            await provider.service.archiveTask(t, 'human');
+                            break;
+                        case 'comment': {
+                            const bodyText = String(body.body ?? '').trim();
+                            if (!bodyText) {
+                                json(res, 400, { error: 'body required' });
+                                return;
+                            }
+                            await provider.service.comment(t, bodyText, 'human');
+                            break;
+                        }
+                        default:
+                            json(res, 400, { error: 'unknown action: ' + String(body.type) });
+                            return;
+                    }
+                    json(res, 200, { ok: true });
+                    return;
+                }
+                json(res, 404, { error: 'not found' });
+            }
+            catch (err) {
+                json(res, 500, { error: String(err) });
+            }
+        },
+    });
+}

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

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

package/lib/routes/kanban-sse.js

@@ -0,0 +1,58 @@
+export function writeSseEvent(res, event) {
+    res.write(`id: ${event.seq}\ndata: ${JSON.stringify(event)}\n\n`);
+}
+function lastSeen(req) {
+    const url = new URL(req.url ?? '/kanban/events', 'http://localhost');
+    const query = Number(url.searchParams.get('after') ?? -1);
+    const headerValue = Array.isArray(req.headers['last-event-id'])
+        ? req.headers['last-event-id'][0]
+        : req.headers['last-event-id'];
+    const header = Number(headerValue ?? -1);
+    return Math.max(Number.isFinite(query) ? query : -1, Number.isFinite(header) ? header : -1);
+}
+/** T23：SSE 事件桥。先订阅并缓存 live 事件，再补发补偿事件，握手窗口不丢事件。 */
+export async function serveKanbanEvents(req, res, service, options) {
+    res.statusCode = 200;
+    res.setHeader('content-type', 'text/event-stream; charset=utf-8');
+    res.setHeader('cache-control', 'no-cache, no-transform');
+    res.setHeader('connection', 'keep-alive');
+    res.flushHeaders?.();
+    let cursor = lastSeen(req);
+    let replaying = true;
+    const buffered = [];
+    let heartbeat;
+    const stop = service.subscribe((event) => {
+        if (replaying)
+            buffered.push(event);
+        else if (event.seq > cursor) {
+            writeSseEvent(res, event);
+            cursor = event.seq;
+        }
+    });
+    let closed = false;
+    const close = () => {
+        if (closed)
+            return;
+        closed = true;
+        stop();
+        if (heartbeat)
+            clearInterval(heartbeat);
+    };
+    req.once('close', close);
+    req.once('aborted', close);
+    res.once('close', close);
+    heartbeat = setInterval(() => { res.write(': heartbeat\n\n'); }, options.heartbeatMs);
+    for (const event of await service.eventsSince(cursor + 1)) {
+        if (event.seq > cursor) {
+            writeSseEvent(res, event);
+            cursor = event.seq;
+        }
+    }
+    replaying = false;
+    for (const event of buffered.sort((a, b) => a.seq - b.seq)) {
+        if (event.seq > cursor) {
+            writeSseEvent(res, event);
+            cursor = event.seq;
+        }
+    }
+}

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

@@ -0,0 +1,16 @@
+import { KanbanService } from '../domain/kanban-service.js';
+import type { SpecCard, SpecCardAttachment } from '../domain/types.js';
+export declare const MATTPOCOCK_PLANNING_GUIDANCE = "\n# \u9636\u6BB5 0 \u89C4\u5212\u5BF9\u8BDD\uFF08v2\uFF1A\u9700\u6C42\u6F84\u6E05\u524D\u7F6E\u5316\uFF09\n1. \u9700\u6C42\u6F84\u6E05\uFF08grill-me\uFF09\uFF1A\u4E00\u6B21\u53EA\u95EE\u4E00\u4E2A\u95EE\u9898\uFF0C\u5148\u6F84\u6E05\u76EE\u7684\u3001\u7EA6\u675F\u3001\u6210\u529F\u6807\u51C6\uFF1B\u9010\u9879\u62F7\u95EE\u5047\u8BBE\u76F4\u81F3\u7528\u6237\"\u6CA1\u6709\u4EFB\u4F55\u7591\u95EE\"\u3002\n2. \u4ED3\u5E93\u4E8B\u5B9E\uFF08planning_prefetch\uFF09\uFF1A\u8C03\u53EA\u8BFB\u5B50\u4EE3\u7406\u91C7\u96C6\u76EE\u6807\u4ED3\u5E93/\u8D44\u6599/\u77E5\u8BC6\u5E93\u4E8B\u5B9E\uFF08\u672C\u5730\u8DEF\u5F84/\u5206\u652F/\u76EE\u6807\u6587\u4EF6\u57FA\u7EBF/\u65E2\u6709\u5B9E\u73B0\uFF09\uFF0C\u4E0D\u51ED\u7A7A\u5047\u8BBE\u3002\n3. \u6536\u655B\uFF08planning_checklist_save\uFF09\uFF1A\u628A\u7ED3\u8BBA\u5199\u6210\u7ED3\u6784\u5316\u9700\u6C42\u6F84\u6E05\u6E05\u5355\uFF08spec \u516D\u6BB5 + manifest repo.files + \u6F84\u6E05\u95EE\u7B54 + \u7591\u95EE\u70B9\uFF09\u5B58\u5165 KB\uFF08KB \u4E0D\u53EF\u8FBE\u81EA\u52A8\u515C\u5E95\u4E34\u65F6\u76EE\u5F55\uFF09\u3002\n4. \u6536\u5C3E\uFF1A\u63D0\u9192\u7528\u6237\u4EE5 /openspec: \u786E\u8BA4\u6267\u884C\u7ED3\u675F\u89C4\u5212\u9636\u6BB5\u2014\u2014/openspec: \u4F1A\u4ECE\u6E05\u5355\u5EFA\u94FE\u5E76\u81EA\u52A8\u4E32\u884C\u6267\u884C\u3002\n\u62A4\u680F\uFF1A\u89C4\u5212\u671F\u53EA\u8BFB\u4ED3\u5E93\uFF0C\u7981\u6B62\u4EFB\u4F55 git/\u6E90\u7801\u5199\u5165\uFF1B\u53EA\u5199 KB \u4E0E\u4E34\u65F6\u76EE\u5F55\u3002\n";
+export declare function validateSpecCardForApproval(card: SpecCard): string[];
+export declare function buildPlanningContext(chainId: string, card: SpecCard, attachments: SpecCardAttachment[]): string;
+export declare function approveIfReady(message: string, service: KanbanService, cfg: {
+    plan: string;
+    openspec: string;
+}, chainId: string, specCardId: string): Promise<{
+    ok: true;
+    card: SpecCard;
+} | {
+    ok: false;
+    missing: string[];
+    guidance: string;
+}>;

package/lib/routes/planning-driver.js

@@ -0,0 +1,52 @@
+import { KanbanService } from '../domain/kanban-service.js';
+import { parsePrefix } from './prefix-router.js';
+export const MATTPOCOCK_PLANNING_GUIDANCE = `
+# 阶段 0 规划对话（v2：需求澄清前置化）
+1. 需求澄清（grill-me）：一次只问一个问题，先澄清目的、约束、成功标准；逐项拷问假设直至用户"没有任何疑问"。
+2. 仓库事实（planning_prefetch）：调只读子代理采集目标仓库/资料/知识库事实（本地路径/分支/目标文件基线/既有实现），不凭空假设。
+3. 收敛（planning_checklist_save）：把结论写成结构化需求澄清清单（spec 六段 + manifest repo.files + 澄清问答 + 疑问点）存入 KB（KB 不可达自动兜底临时目录）。
+4. 收尾：提醒用户以 /openspec: 确认执行结束规划阶段——/openspec: 会从清单建链并自动串行执行。
+护栏：规划期只读仓库，禁止任何 git/源码写入；只写 KB 与临时目录。
+`;
+export function validateSpecCardForApproval(card) {
+    const missing = [];
+    const s = card.sections;
+    if (typeof s.problem !== 'string' || !s.problem.trim())
+        missing.push('problem');
+    if (typeof s.solution !== 'string' || !s.solution.trim())
+        missing.push('solution');
+    if (!Array.isArray(s.user_stories) || s.user_stories.length === 0)
+        missing.push('user_stories');
+    if (typeof s.testing !== 'string' || !s.testing.trim())
+        missing.push('testing');
+    if (typeof s.out_of_scope !== 'string' || !s.out_of_scope.trim())
+        missing.push('out_of_scope');
+    if (!card.attachments.some((a) => a.kind === 'file-prefetch'))
+        missing.push('attachments:file-prefetch');
+    return missing;
+}
+export function buildPlanningContext(chainId, card, attachments) {
+    return [
+        `# 规划上下文 chain=${chainId} specCard=${card.id}`,
+        MATTPOCOCK_PLANNING_GUIDANCE,
+        `## 当前规格卡\n${JSON.stringify(card.sections, null, 2)}`,
+        `## 仓库事实附件\n${attachments.map((a) => `${a.name}: ${a.ref}`).join('\n') || '(无)'}`,
+    ].join('\n\n');
+}
+export async function approveIfReady(message, service, cfg, chainId, specCardId) {
+    const parsed = parsePrefix(message, cfg);
+    if (parsed.kind !== 'openspec')
+        return { ok: false, missing: ['prefix'], guidance: MATTPOCOCK_PLANNING_GUIDANCE };
+    const state = await service.snapshot();
+    const card = state.specCards.get(specCardId);
+    if (!card)
+        return { ok: false, missing: ['spec-card'], guidance: MATTPOCOCK_PLANNING_GUIDANCE };
+    if (card.status === 'approved')
+        return { ok: true, card };
+    const missing = validateSpecCardForApproval(card);
+    if (missing.length > 0) {
+        return { ok: false, missing, guidance: MATTPOCOCK_PLANNING_GUIDANCE };
+    }
+    const approved = await service.approveSpecCard(specCardId, 'human');
+    return { ok: true, card: approved };
+}

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

@@ -0,0 +1,29 @@
+import { KanbanService } from '../domain/kanban-service.js';
+import type { PlanningChecklist } from '../domain/planning-checklist.js';
+export interface PrefixRouteResult {
+    kind: 'plan' | 'openspec' | 'none';
+    chainId?: string;
+    specCardId?: string;
+    rest: string;
+}
+export declare function parsePrefix(message: string, cfg: {
+    plan: string;
+    openspec: string;
+}): PrefixRouteResult;
+/** v2：/plan: 零副作用——不建链/规格卡/任务卡，仅返回路由结果（workspaceDir/sessionId 由 main-session-tools 捕获）。 */
+export declare function handlePlanRoute(message: string, _service: KanbanService, cfg: {
+    plan: string;
+    openspec: string;
+}, _ownerSessionId: string): Promise<PrefixRouteResult>;
+export interface OpenspecPlanningInput {
+    workspaceDir: string | null;
+    checklist: PlanningChecklist;
+    checklistRef: string;
+    /** T7：/plan: rest 原始需求描述；null=无 /plan: 捕获（回退 checklist.problem 首句/未命名需求）。 */
+    requirementName?: string | null;
+}
+/** v2：/openspec: 建链——从清单机械映射规格卡六段 → 挂 file-prefetch(仓库 localPath)+kb(清单页) → 批准 → executing。 */
+export declare function handleOpenspecRoute(message: string, service: KanbanService, cfg: {
+    plan: string;
+    openspec: string;
+}, planning: OpenspecPlanningInput, ownerSessionId: string): Promise<PrefixRouteResult>;

package/lib/routes/prefix-router.js

@@ -0,0 +1,28 @@
+import { KanbanService, buildChainTitle } from '../domain/kanban-service.js';
+export function parsePrefix(message, cfg) {
+    const trimmed = message.trim();
+    if (trimmed.startsWith(cfg.plan))
+        return { kind: 'plan', rest: trimmed.slice(cfg.plan.length).trim() };
+    if (trimmed.startsWith(cfg.openspec))
+        return { kind: 'openspec', rest: trimmed.slice(cfg.openspec.length).trim() };
+    return { kind: 'none', rest: trimmed };
+}
+/** v2：/plan: 零副作用——不建链/规格卡/任务卡，仅返回路由结果（workspaceDir/sessionId 由 main-session-tools 捕获）。 */
+export async function handlePlanRoute(message, _service, cfg, _ownerSessionId) {
+    return parsePrefix(message, cfg);
+}
+/** v2：/openspec: 建链——从清单机械映射规格卡六段 → 挂 file-prefetch(仓库 localPath)+kb(清单页) → 批准 → executing。 */
+export async function handleOpenspecRoute(message, service, cfg, planning, ownerSessionId) {
+    const parsed = parsePrefix(message, cfg);
+    if (parsed.kind !== 'openspec')
+        return parsed;
+    const chain = await service.createChain({
+        title: buildChainTitle(planning.checklist.requirementName ?? planning.requirementName ?? null, parsed.rest, planning.checklist.spec.problem),
+        ownerSessionId, workspaceDir: planning.workspaceDir,
+    }, 'human');
+    const card = await service.createSpecCard(chain.id, planning.checklist.spec, 'human');
+    await service.addSpecCardAttachment(card.id, { name: '需求澄清清单(仓库事实)', kind: 'file-prefetch', ref: planning.checklist.manifest.repo.localPath }, 'v');
+    await service.addSpecCardAttachment(card.id, { name: '需求澄清清单(完整资料)', kind: 'kb', ref: planning.checklistRef }, 'v');
+    await service.approveSpecCard(card.id, 'human');
+    return { kind: 'openspec', chainId: chain.id, specCardId: card.id, rest: parsed.rest };
+}

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

@@ -0,0 +1,16 @@
+import { Service, type Context } from '@deepseek-ai/cordis';
+import { KanbanService } from '../domain/kanban-service.js';
+import type { KanbanConfig } from '../config.js';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        kanban: KanbanProvider;
+    }
+}
+export declare class KanbanProvider extends Service {
+    readonly service: KanbanService;
+    /** T32 fix：GUI retry 的任务执行器（由 startDispatcher 装配后注入；webServer 先于 agents 就绪时可为 null）。 */
+    runner: {
+        runTask(taskId: string): Promise<void>;
+    } | null;
+    constructor(ctx: Context, config: KanbanConfig);
+}

package/lib/services/kanban-provider.js

@@ -0,0 +1,14 @@
+import { Service } from '@deepseek-ai/cordis';
+import { homedir } from 'node:os';
+import { KanbanService } from '../domain/kanban-service.js';
+import { FileEventStore } from '../domain/event-store.js';
+export class KanbanProvider extends Service {
+    service;
+    /** T32 fix：GUI retry 的任务执行器（由 startDispatcher 装配后注入；webServer 先于 agents 就绪时可为 null）。 */
+    runner = null;
+    constructor(ctx, config) {
+        super(ctx, 'kanban');
+        const dir = config.storageDir.replace('$DSH_HOME', process.env.DSH_HOME ?? homedir());
+        this.service = new KanbanService(new FileEventStore(dir), config.wikiVault?.baseUrl);
+    }
+}

package/lib/tools/kanban-tools.d.ts

@@ -0,0 +1,11 @@
+import { KanbanService } from '../domain/kanban-service.js';
+import { type Actor } from '../domain/permissions.js';
+/** 工具执行上下文：由角色 agent scope 注入；主会话=human；调度器=system。
+ *  boundTaskId：角色 agent 会话绑定的任务（AgentSessionRef.task_id，P1-4 会话绑定）。 */
+export interface ToolCaller {
+    actor: Actor;
+    boundTaskId?: string;
+}
+/** 工具定义工厂（P1-3）：不直接注册；由 T15 toolsets 按角色 agent-scope 装配，或由主会话注册其专属子集。
+ *  getCaller：装配方提供的闭包（捕获 actor/boundTaskId），execute 内取用——不依赖 execute 第二参数（DSH ToolRunContext 真实形状以官方为准）。 */
+export declare function buildKanbanTools(service: KanbanService, getCaller: () => ToolCaller): import("@deepseek-ai/dsh-tools").ToolDefinition[];

package/lib/tools/kanban-tools.js

@@ -0,0 +1,169 @@
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { KanbanService } from '../domain/kanban-service.js';
+import { can } from '../domain/permissions.js';
+function guard(action, caller, task = null) {
+    if (!can(action, caller.actor, task))
+        throw new Error('permission denied: ' + action);
+}
+/** 工具定义工厂（P1-3）：不直接注册；由 T15 toolsets 按角色 agent-scope 装配，或由主会话注册其专属子集。
+ *  getCaller：装配方提供的闭包（捕获 actor/boundTaskId），execute 内取用——不依赖 execute 第二参数（DSH ToolRunContext 真实形状以官方为准）。 */
+export function buildKanbanTools(service, getCaller) {
+    return [
+        defineTool({
+            name: 'kanban_show',
+            description: 'Show a kanban task with its handoffs and comments.',
+            parameters: {
+                taskId: { type: 'string', required: true, description: 'Task id (t_xxx)' },
+            },
+            output: { schema: { type: 'json' }, render: (_a, v) => [{ type: 'text', text: JSON.stringify(v) }] },
+            async execute(args) {
+                const caller = getCaller();
+                guard('comment', caller);
+                const state = await service.snapshot();
+                const task = state.tasks.get(args.taskId);
+                if (!task)
+                    throw new Error('unknown task: ' + args.taskId);
+                const handoff = state.handoffs.get(args.taskId) ?? null;
+                const comments = state.events.filter((e) => e.taskId === args.taskId && e.kind === 'task/commented').map((e) => e.payload['body']);
+                return { task, handoff, comments };
+            },
+        }),
+        defineTool({
+            name: 'kanban_chain',
+            description: 'Show a chain\u2019s full status at a glance: chain + spec card + all task cards (with handoffs/comments) + audit warning. Read-only inspection for requirement-chain tracing.',
+            parameters: {
+                chainId: { type: 'string', required: true, description: 'Chain id (ch_xxx)' },
+            },
+            output: { schema: { type: 'json' }, render: (_a, v) => [{ type: 'text', text: JSON.stringify(v) }] },
+            async execute(args) {
+                const caller = getCaller();
+                guard('comment', caller);
+                const state = await service.snapshot();
+                const chain = state.chains.get(args.chainId);
+                if (!chain)
+                    throw new Error('unknown chain: ' + args.chainId);
+                const specCard = state.specCards.get(chain.specCardId ?? '') ?? null;
+                const tasks = [...state.tasks.values()]
+                    .filter((t) => t.chainId === args.chainId)
+                    .sort((a, b) => a.priority - b.priority)
+                    .map((t) => ({
+                    id: t.id,
+                    title: t.title,
+                    assignee: t.assignee,
+                    mode: t.mode,
+                    status: t.status,
+                    parents: t.parents,
+                    children: t.children,
+                    attempts: t.attempts,
+                    blockedReason: state.events
+                        .filter((e) => e.taskId === t.id && e.kind === 'task/blocked')
+                        .at(-1)?.payload['reason'] ?? null,
+                    comments: state.events
+                        .filter((e) => e.taskId === t.id && e.kind === 'task/commented')
+                        .map((e) => e.payload['body']),
+                    handoff: state.handoffs.get(t.id) ?? null,
+                }));
+                const auditWarning = state.auditWarnings.get(args.chainId) ?? null;
+                return { chain, specCard, tasks, auditWarning };
+            },
+        }),
+        defineTool({
+            name: 'kanban_create',
+            description: 'Create a kanban task (orchestrator V or human only).',
+            parameters: {
+                chainId: { type: 'string', required: true, description: 'Chain id (ch_xxx)' },
+                title: { type: 'string', required: true },
+                body: { type: 'string', description: 'Task body; handoffs are injected via parents, not body' },
+                assignee: { type: 'string', enum: ['v', 'p', 'w', 'd', 'pt', 'dt'], required: true },
+                mode: { type: 'string', enum: ['file', 'external', 'kb', 'openspec', 'mattpocock', 'align', 'execute', 'review-plan', 'review-impl'], required: true },
+                parents: { type: 'array', items: { type: 'string' } },
+            },
+            output: { schema: { type: 'json' }, render: (_a, v) => [{ type: 'text', text: JSON.stringify(v) }] },
+            async execute(args) {
+                const caller = getCaller();
+                guard('create-task', caller);
+                return (await service.createTask(args, caller.actor));
+            },
+        }),
+        defineTool({
+            name: 'kanban_complete',
+            description: 'Complete a task with handoff summary and metadata.',
+            parameters: {
+                taskId: { type: 'string', required: true },
+                summary: { type: 'string', required: true, description: 'Human-readable completion summary' },
+                metadata: { type: 'json', description: 'Machine-readable handoff: changed_files/verification/kb_url...' },
+            },
+            output: { schema: { type: 'json' }, render: (_a, v) => [{ type: 'text', text: JSON.stringify(v) }] },
+            async execute(args) {
+                const caller = getCaller();
+                const done = await service.completeTask(args.taskId, { summary: args.summary, metadata: args.metadata ?? {}, completedAt: Date.now() }, caller.actor, { boundTaskId: caller.boundTaskId });
+                return done;
+            },
+        }),
+        defineTool({
+            name: 'kanban_block',
+            description: 'Block a task with a reason (needs human input).',
+            parameters: {
+                taskId: { type: 'string', required: true },
+                reason: { type: 'string', required: true },
+            },
+            output: { schema: { type: 'json' }, render: (_a, v) => [{ type: 'text', text: JSON.stringify(v) }] },
+            async execute(args) {
+                const caller = getCaller();
+                const blocked = await service.blockTask(args.taskId, args.reason, caller.actor, { boundTaskId: caller.boundTaskId });
+                return blocked;
+            },
+        }),
+        defineTool({
+            name: 'kanban_heartbeat',
+            description: 'Signal liveness during a long task.',
+            parameters: { taskId: { type: 'string', required: true } },
+            output: { schema: { type: 'json' }, render: (_a, v) => [{ type: 'text', text: JSON.stringify(v) }] },
+            async execute(args) {
+                const caller = getCaller();
+                const beat = await service.heartbeat(args.taskId, caller.actor, { boundTaskId: caller.boundTaskId });
+                return beat;
+            },
+        }),
+        defineTool({
+            name: 'kanban_comment',
+            description: 'Append a persistent comment to a task thread.',
+            parameters: {
+                taskId: { type: 'string', required: true },
+                body: { type: 'string', required: true },
+            },
+            output: { schema: { type: 'json' }, render: (_a, v) => [{ type: 'text', text: JSON.stringify(v) }] },
+            async execute(args) {
+                const caller = getCaller();
+                const ev = await service.comment(args.taskId, args.body, caller.actor);
+                return ev;
+            },
+        }),
+        defineTool({
+            name: 'kanban_list',
+            description: 'List tasks filtered by assignee/status.',
+            parameters: {
+                assignee: { type: 'string', enum: ['v', 'p', 'w', 'd', 'pt', 'dt'] },
+                status: { type: 'string' },
+            },
+            output: { schema: { type: 'json' }, render: (_a, v) => [{ type: 'text', text: JSON.stringify(v) }] },
+            async execute(args) {
+                const caller = getCaller();
+                guard('comment', caller);
+                const list = await service.listTasks(args);
+                return list;
+            },
+        }),
+        defineTool({
+            name: 'kanban_unblock',
+            description: 'Unblock a task (human only).',
+            parameters: { taskId: { type: 'string', required: true } },
+            output: { schema: { type: 'json' }, render: (_a, v) => [{ type: 'text', text: JSON.stringify(v) }] },
+            async execute(args) {
+                const caller = getCaller();
+                const task = await service.unblockTask(args.taskId, caller.actor);
+                return task;
+            },
+        }),
+    ];
+}

package/lib/tools/main-session-tools.d.ts

@@ -0,0 +1,20 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { KanbanConfig } from '../config.js';
+import { type PlanningToolDeps } from './planning-tools.js';
+import type { PlanningChecklist } from '../domain/planning-checklist.js';
+/** v2 规划上下文（/plan: 捕获 → planning_checklist_save 回写 → /openspec: 建链）。模块级内存，随插件进程存活。 */
+export interface PlanningContext {
+    workspaceDir: string | null;
+    sessionId: string;
+    checklist: PlanningChecklist | null;
+    checklistRef: string | null;
+    checklistSource: 'kb' | 'temp' | null;
+    /** T7：/plan: rest 原始需求描述（建链默认标题来源，优先级最高）。 */
+    requirementName: string | null;
+}
+export declare const planningBySession: Map<string, PlanningContext>;
+export declare function buildSpawnPrefetch(ctx: Context): PlanningToolDeps['spawnPrefetch'] | undefined;
+/** v2 主会话工具面：/plan: 捕获规划上下文（零副作用）→ planning_checklist_save 回写 → /openspec: 用清单建链。
+ *  工具面 = kanban_route + 只读 kanban 子集 + spec_card_view + planning 工具；
+ *  无 spec_card_edit/approve、无 kanban_create/complete/block（主会话越权写由工具面裁剪 + prefetch 子代理只读护栏双保险）。 */
+export declare function registerMainSessionTools(ctx: Context, config: KanbanConfig): void;