@joekytc/dsh-swarm 0.3.8 → 0.3.9

package/lib/dispatcher/agent-runner.js

@@ -5,6 +5,7 @@ import { probeOcr } from '../services/ocr-cli.js';
 import { installRoleTools, buildReadOnlyWriteGuard, buildDTWriteGuard, buildPlanWriteGuard, buildKbWriteGuard, registerDtTaskChain, unregisterDtTaskChain } from '../roles/toolsets.js';
 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 } from './session-events.js';
 import { attachSessionToWorkspace, resolveOrCreateWorkspace } from './workspace-attach.js';
@@ -271,7 +272,10 @@ ${task.body}`);
                     if (presets) {
                         const presetId = 'kanban-' + task.assignee;
                         try {
-                            await presets.mount(agentCtx, presetId);
+                            // mountOrRecompose（2026-09-21）：blocked/unblock 多轮唤醒 resume 同一 session 时，
+                            // 二次 mount 会撞宿主 dsh-scope 一次性绑定（already bound to a parent）——收敛为
+                            // 已绑走 recompose 官方重链；其余挂载错误仍降级放行（角色工具面照常注册）。
+                            await mountOrRecompose(presets, agentCtx, presetId);
                             console.error('[dsh-swarm][debug] preset mounted ' + presetId + ' role=' + task.assignee + ' task=' + taskId);
                         }
                         catch (err) {

package/lib/dispatcher/dispatcher.d.ts

@@ -85,6 +85,14 @@ export declare class Dispatcher {
 /** 启动 reconcile：剔除事件流中已不存在的链的编排 entry（历史残留/外部 purge）。
  *  原地删除并返回被移除的 chainId 列表（调用方负责持久化与日志）。 */
 export declare function reconcileOrchestrations<T>(orch: Map<string, T>, chains: Set<string>): string[];
+/** 启动补扫候选：快照中全部 executing 状态链（2026-09-21 重启吞编排轮事故）。
+ *  EventWaker 纯事件驱动，历史 wakeable 事件（如 PT completed）被重启游标越过即永不重放；
+ *  启动时按链状态补唤醒，与 EventWaker 的实时驱动互补。 */
+export declare function collectExecutingChains(snap: {
+    chains: Map<string, {
+        status: string;
+    }>;
+}): string[];
 /** 启动 reconcile：进程重启会杀死 runner 的 whenIdle 协程，上次遗留的 running 卡无人收尾，
  *  看门狗默认 4h（staleTimeoutSeconds=14400）才回收——重启后立即把 running 孤儿卡收敛为 blocked
  *  （system comment + blockTask），中断显形且可重派续跑（重派将 resume 同一会话，进度保留）。

package/lib/dispatcher/dispatcher.js

@@ -311,6 +311,17 @@ export function reconcileOrchestrations(orch, chains) {
         orch.delete(k);
     return removed;
 }
+/** 启动补扫候选：快照中全部 executing 状态链（2026-09-21 重启吞编排轮事故）。
+ *  EventWaker 纯事件驱动，历史 wakeable 事件（如 PT completed）被重启游标越过即永不重放；
+ *  启动时按链状态补唤醒，与 EventWaker 的实时驱动互补。 */
+export function collectExecutingChains(snap) {
+    const out = [];
+    for (const [chainId, chain] of snap.chains) {
+        if (chain.status === 'executing')
+            out.push(chainId);
+    }
+    return out;
+}
 /** 启动 reconcile：进程重启会杀死 runner 的 whenIdle 协程，上次遗留的 running 卡无人收尾，
  *  看门狗默认 4h（staleTimeoutSeconds=14400）才回收——重启后立即把 running 孤儿卡收敛为 blocked
  *  （system comment + blockTask），中断显形且可重派续跑（重派将 resume 同一会话，进度保留）。
@@ -523,6 +534,16 @@ function startDispatcherInner(ctx, configProvider, storageDir, logFile, provider
                 saveOrchs();
                 logToFile(logFile, '[orch-reconcile] removed dead entries: ' + removed.join(','));
             }
+            // 启动补扫（2026-09-21）：EventWaker 纯事件驱动——实例重启后游标已越过「已完成但未推进」
+            // 的 wakeable 事件（如 PT completed）时编排轮被吞（历史事件不重放），executing 链静默停滞
+            // （销服一体 V3.0 链实测：PT done 后 W2 永不建卡）。启动时对全部 executing 链补一次 wakeV
+            // （幂等：wakeV 按 orchestration/链快照决策 + 在途合并；无可推进阶段时无害空转）。
+            for (const chainId of collectExecutingChains(snap)) {
+                logToFile(logFile, '[startup-rewake] executing chain=' + chainId);
+                void vOrch.wakeV(chainId).catch((err) => {
+                    logToFile(logFile, '[startup-rewake] failed chain=' + chainId + ' ' + String(err));
+                });
+            }
         }
         catch (err) {
             logToFile(logFile, '[orch-reconcile] failed: ' + String(err));

package/lib/dispatcher/v-orchestrator.js

@@ -1,4 +1,5 @@
 import { installRoleTools } from '../roles/toolsets.js';
+import { mountOrRecompose } from '../roles/preset-installer.js';
 import { resolveTaskParents } from '../domain/task-parents.js';
 import { missingParentDelivery } from '../domain/delivery-contract.js';
 import { buildRepoSlug } from '../domain/memory.js';
@@ -636,9 +637,11 @@ export class VOrchestrator {
                 // 无 persona 基座不得裸奔。抛错 → create/resume 失败 → getVAgent 抛 → 主推进路径并入
                 // 异常收场（stall 计数，超限 [create-failed] + blockChain）；候选循环对非 model
                 // 错误立即失败（isModelUnavailableError=false → throw），不会被候选切换吞掉。
+                // mountOrRecompose（2026-09-21）：V 会话跨进程重启 resume / 重入 setup 时二次 mount
+                // 会撞宿主 dsh-scope 一次性绑定——already-bound 收敛为 recompose 官方重链，其余照抛。
                 const vSessionId = orch.sessionId ?? 'kbn-v-' + orch.chainId;
                 try {
-                    await presets.mount(agentCtx, V_SESSION_PRESET_ID);
+                    await mountOrRecompose(presets, agentCtx, V_SESSION_PRESET_ID);
                 }
                 catch (err) {
                     throw new Error(V_SESSION_PRESET_ID + ' preset mount failed for ' + vSessionId + ': ' + String(err));

package/lib/domain/delivery-contract.d.ts

@@ -1,6 +1,7 @@
 import type { BoardState, Handoff, Role, TaskMode } from './types.js';
 export declare function requiredDeliveryKeys(assignee: Role, mode: TaskMode): string[];
-/** v2：pt_decision 结构校验（needed 布尔必填；needed=true 时 reason 必填）。返回缺失键列表。 */
+/** v2：pt_decision 结构校验（needed 布尔必填；needed=true 时 reason 必填）。返回缺失键列表。
+ *  2026-09-21：metadata 非对象（双重编码字符串）时报类型真因，不产生误导性 'pt_decision' 缺键文案。 */
 export declare function missingPtDecisionKeys(handoff: Handoff | undefined): string[];
 /** 缺失的交付键（存在但为空的字符串/非字符串均视为缺失；pt_decision 走结构校验透传细粒度键）。
  *  可选 kbUrlBase：提供时对 w:kb 的 kb_url 做 host 前缀硬校验（防 LLM 手写错域名）、对 page_path 做

package/lib/domain/delivery-contract.js

@@ -17,9 +17,14 @@ const REQUIRED_DELIVERY = {
 export function requiredDeliveryKeys(assignee, mode) {
     return REQUIRED_DELIVERY[`${assignee}:${mode}`] ?? [];
 }
-/** v2：pt_decision 结构校验（needed 布尔必填；needed=true 时 reason 必填）。返回缺失键列表。 */
+/** v2：pt_decision 结构校验（needed 布尔必填；needed=true 时 reason 必填）。返回缺失键列表。
+ *  2026-09-21：metadata 非对象（双重编码字符串）时报类型真因，不产生误导性 'pt_decision' 缺键文案。 */
 export function missingPtDecisionKeys(handoff) {
-    const d = (handoff?.metadata ?? {})['pt_decision'];
+    const rawMeta = handoff?.metadata ?? {};
+    if (typeof rawMeta !== 'object' || rawMeta === null) {
+        return [`pt_decision (metadata must be an object, got ${Array.isArray(rawMeta) ? 'array' : typeof rawMeta})`];
+    }
+    const d = rawMeta['pt_decision'];
     if (typeof d !== 'object' || d === null)
         return ['pt_decision'];
     const o = d;
@@ -39,7 +44,11 @@ export function missingDeliveryKeys(assignee, mode, handoff, kbUrlBase) {
         return [];
     if (!handoff)
         return keys.slice();
-    const m = handoff.metadata ?? {};
+    // 2026-09-21：metadata 非对象（模型双重编码字符串穿透 {type:'json'} 宽参数）时，m[k] 对字符串
+    // 索引静默 undefined → 误导性 "delivery required" 缺键报错。此处报类型真因（纵深防线）。
+    const rawMeta = handoff.metadata ?? {};
+    const metaOk = typeof rawMeta === 'object' && rawMeta !== null && !Array.isArray(rawMeta);
+    const m = metaOk ? rawMeta : null;
     // 推导修正：kbUrlBase === undefined 才是宽松；'' 是 local strict
     const hasBase = kbUrlBase !== undefined;
     const base = hasBase ? kbUrlBase.replace(/\/$/, '') : null;
@@ -50,6 +59,10 @@ export function missingDeliveryKeys(assignee, mode, handoff, kbUrlBase) {
             missing.push(...missingPtDecisionKeys(handoff));
             continue;
         }
+        if (!metaOk) {
+            missing.push(`${k} (metadata must be an object, got ${Array.isArray(rawMeta) ? 'array' : typeof rawMeta})`);
+            continue;
+        }
         const v = m[k];
         if (strict && k === 'kb_url' && base === '') {
             // local 模式：kb_url 必须显式空串（非缺失键）

package/lib/domain/planning-checklist.d.ts

@@ -25,3 +25,6 @@ export declare function validatePlanningChecklist(raw: unknown): string[];
 export declare function buildChecklistTitle(c: PlanningChecklist): string;
 /** 需求澄清清单落库 body：标题【需求】+ 各段可读 markdown（非裸 JSON）。KB 与临时目录两分支共用。 */
 export declare function formatChecklistBody(c: PlanningChecklist): string;
+/** 从清单页原文提取机读 PlanningChecklist（无损恢复路径）：无段/损坏/校验不过一律返回 null，
+ *  由调用方回退 legacy LLM 重建流程。domain 纯函数，无副作用。 */
+export declare function extractChecklistJson(pageMd: string): PlanningChecklist | null;

package/lib/domain/planning-checklist.js

@@ -151,5 +151,32 @@ export function formatChecklistBody(c) {
     }
     if (doubts.length === 0)
         lines.push('（无）');
+    // 机读段（2026-09-21 恢复流程矫正）：页正文是人读 markdown（有损），重启恢复若让 LLM 读页重建
+    // 再回存 = 有损再创作 + 双重编码风险（销服一体清单 7 轮失败即发生在恢复场景）。页尾内嵌无损
+    // JSON 单行段，/openspec: 路由2 直接提取灌内存建链，LLM 零参与；HTML 注释对人读零干扰。
+    const machine = JSON.stringify({ requirementName: c.requirementName ?? null, spec: c.spec, manifest: c.manifest, clarifications: c.clarifications, doubts: c.doubts, risks: c.risks ?? [] });
+    lines.push('', `<!-- dsh-swarm:checklist-json ${machine} -->`);
     return lines.join('\n').replace(/\n{3,}/g, '\n\n');
 }
+const CHECKLIST_JSON_MARK = '<!-- dsh-swarm:checklist-json ';
+/** 从清单页原文提取机读 PlanningChecklist（无损恢复路径）：无段/损坏/校验不过一律返回 null，
+ *  由调用方回退 legacy LLM 重建流程。domain 纯函数，无副作用。 */
+export function extractChecklistJson(pageMd) {
+    const start = pageMd.indexOf(CHECKLIST_JSON_MARK);
+    if (start < 0)
+        return null;
+    const jsonStart = start + CHECKLIST_JSON_MARK.length;
+    const end = pageMd.indexOf('-->', jsonStart);
+    if (end < 0)
+        return null;
+    let raw;
+    try {
+        raw = JSON.parse(pageMd.slice(jsonStart, end).trim());
+    }
+    catch {
+        return null;
+    }
+    if (validatePlanningChecklist(raw).length > 0)
+        return null;
+    return raw;
+}

package/lib/domain/prefetch-manifest.js

@@ -52,22 +52,33 @@ export function validatePrefetchManifest(raw) {
         errors.push('manifest.files must be an array');
     }
     else {
+        // files[] 逐条错误先收集再聚合（2026-09-21：26 条同文错误墙稀释有效信息，模型只见截断前几条）。
+        // 完全相同的消息合并为 "<msg> ×N"，不同消息保持原样与原序。
+        const fileErrors = [];
         for (const f of m['files']) {
             if (typeof f !== 'object' || f === null) {
-                errors.push('manifest.files entry must be an object');
+                fileErrors.push('manifest.files entry must be an object');
                 continue;
             }
             const e = f;
             if (typeof e['path'] !== 'string' || e['path'].trim().length === 0) {
-                errors.push(`manifest.files[].path (got: ${JSON.stringify(e['path'])})`);
+                fileErrors.push(`manifest.files[].path (got: ${JSON.stringify(e['path'])})`);
             }
             if (typeof e['expected'] !== 'string' || !EXPECTED_VALUES.has(e['expected'])) {
-                errors.push(`manifest.files[].expected (got: ${JSON.stringify(e['expected'])})`);
+                fileErrors.push(`manifest.files[].expected (got: ${JSON.stringify(e['expected'])})`);
             }
             if (e['expected'] === 'content-hash' && (typeof e['note'] !== 'string' || e['note'].trim().length === 0)) {
-                errors.push(`manifest.files[].note required for content-hash (got: ${JSON.stringify(e['note'])})`);
+                fileErrors.push(`manifest.files[].note required for content-hash (got: ${JSON.stringify(e['note'])})`);
             }
         }
+        errors.push(...tallyIdentical(fileErrors));
     }
     return errors;
 }
+/** 相同消息聚合计数：["a","a","b"] → ["a ×2","b"]。domain 纯函数，无副作用。 */
+function tallyIdentical(messages) {
+    const counts = new Map();
+    for (const msg of messages)
+        counts.set(msg, (counts.get(msg) ?? 0) + 1);
+    return [...counts.entries()].map(([msg, n]) => (n > 1 ? `${msg} ×${n}` : msg));
+}

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

@@ -6,3 +6,17 @@ export declare function userPresetsRoot(): string;
  *  尽力而为：单 preset 写失败（用户预设根不可写等）仅告警不抛出，
  *  后续 agentPresets.mount('kanban-<role>') 失败由 runner 降级日志兜底。 */
 export declare function installRolePresets(): string[];
+/** 角色 preset 挂载的容器面（dsh-agent-presets roster 的最小结构类型）。 */
+export interface PresetMountLike {
+    mount(ctx: unknown, id: string): Promise<unknown>;
+    /** 官方重链入口（0.1.2-rc.1 起提供）：已绑定 → binding.rebind；未绑定 → bind。 */
+    recompose?(ctx: unknown, id: string): Promise<unknown>;
+}
+/**
+ * preset 挂载收敛入口（2026-09-21 事故修复）：宿主 dsh-scope 的 scope key 绑定在进程
+ * 生命周期内一次性（bindScopeParent 重复调用抛 "already bound to a parent"），官方重链
+ * 入口是 recompose（已绑 → binding.rebind）。同 agentKey 的二次 setup（P/W/D 卡 blocked/
+ * unblock 多轮唤醒 resume 同一 session、live 复用 re-setup 补挂）此前直接二次 mount 必炸。
+ * 收敛语义：mount 失败且系 already-bound → recompose 重链；其余错误（组合不可用等）原样上抛。
+ */
+export declare function mountOrRecompose(presets: PresetMountLike, agentCtx: unknown, presetId: string): Promise<void>;

package/lib/roles/preset-installer.js

@@ -51,3 +51,20 @@ export function installRolePresets() {
     }
     return installed;
 }
+/**
+ * preset 挂载收敛入口（2026-09-21 事故修复）：宿主 dsh-scope 的 scope key 绑定在进程
+ * 生命周期内一次性（bindScopeParent 重复调用抛 "already bound to a parent"），官方重链
+ * 入口是 recompose（已绑 → binding.rebind）。同 agentKey 的二次 setup（P/W/D 卡 blocked/
+ * unblock 多轮唤醒 resume 同一 session、live 复用 re-setup 补挂）此前直接二次 mount 必炸。
+ * 收敛语义：mount 失败且系 already-bound → recompose 重链；其余错误（组合不可用等）原样上抛。
+ */
+export async function mountOrRecompose(presets, agentCtx, presetId) {
+    try {
+        await presets.mount(agentCtx, presetId);
+    }
+    catch (err) {
+        if (!String(err).includes('already bound to a parent') || typeof presets.recompose !== 'function')
+            throw err;
+        await presets.recompose(agentCtx, presetId);
+    }
+}

package/lib/tools/kanban-tools.js

@@ -93,12 +93,20 @@ export function buildKanbanTools(service, getCaller) {
             parameters: {
                 taskId: { type: 'string', required: true },
                 summary: { type: 'string', required: true, description: 'Human-readable completion summary' },
-                metadata: { type: 'json', description: 'Machine-readable handoff: changed_files/verification/kb_url... W3/kb may add report = { requirement, status, branch, tasks: [{ text, done }], acceptance, verification, leftovers?, todos? } (delivery-report fields; tasks mirrors the OpenSpec plan checklist openspec/changes/<id>/tasks.md verbatim, done = checked)' },
+                // metadata 用官方 object schema（2026-09-21：{type:'json'} 不施加约束，模型双重编码字符串静默
+                // 穿透到 delivery 闸才爆出误导性 "delivery required"——open object = 必须对象、键值任意，字符串
+                // 由运行时 ToolArgsError "must be an object" 单轮拦截。additionalProperties 必填（DSL 硬规则）。
+                metadata: { type: 'object', additionalProperties: true, description: 'Machine-readable handoff: changed_files/verification/kb_url... W3/kb may add report = { requirement, status, branch, tasks: [{ text, done }], acceptance, verification, leftovers?, todos? } (delivery-report fields; tasks mirrors the OpenSpec plan checklist openspec/changes/<id>/tasks.md verbatim, done = checked). Pass the object itself — never a JSON-encoded string.' },
             },
             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 });
+                // 运行时诚实检查（纵深）：schema 已强制 object，此处拦截直调/回归路径——绝不静默强转字符串
+                const meta = args.metadata;
+                if (meta !== undefined && (typeof meta !== 'object' || Array.isArray(meta))) {
+                    throw new Error(`metadata must be a JSON object (got ${Array.isArray(meta) ? 'array' : typeof meta}) — pass the object itself, never a JSON-encoded string`);
+                }
+                const done = await service.completeTask(args.taskId, { summary: args.summary, metadata: (meta ?? {}), completedAt: Date.now() }, caller.actor, { boundTaskId: caller.boundTaskId });
                 return done;
             },
         }),

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

@@ -2,7 +2,7 @@ import type { Context } from '@deepseek-ai/cordis';
 import type { PrefixRoutes } from '../config.js';
 import type { ConfigProvider } from '../services/config-provider.js';
 import { type PlanningToolDeps } from './planning-tools.js';
-import type { PlanningChecklist } from '../domain/planning-checklist.js';
+import { type PlanningChecklist } from '../domain/planning-checklist.js';
 /** v2 规划上下文（/plan: 捕获 → planning_checklist_save 回写 → /openspec: 建链）。模块级内存，随插件进程存活。 */
 export interface PlanningContext {
     workspaceDir: string | null;

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

@@ -12,6 +12,7 @@ import { buildPlanningGuidance } from '../routes/planning-driver.js';
 import { attachSessionToWorkspace, resolveOrCreateWorkspace } from '../dispatcher/workspace-attach.js';
 import { sessionPresetOf } from '../dispatcher/session-preset.js';
 import { PREFETCH_MANIFEST_SCHEMA } from '../domain/prefetch-manifest.js';
+import { extractChecklistJson } from '../domain/planning-checklist.js';
 import { WikiVaultClient } from '../wiki/wiki-vault-client.js';
 import { LocalWikiClient } from '../wiki/local-kb-client.js';
 import { ensureLocalKbRoot } from '../wiki/local-kb.js';
@@ -61,9 +62,9 @@ const RECOVERY_KB_GUIDANCE = (routes, candidates) => `
 ${candidates.map((c) => '- ' + c).join('\n')}
 恢复步骤（严格顺序）：
 1. 读取候选页内容，对照当前需求判定哪一页是本次需求的需求澄清清单（页首行标题为「# 【需求】<需求名>」）；
-2. 消化该页内容，重建结构化 PlanningChecklist（spec 六段 + manifest + clarifications + doubts + risks（风险点，若有），requirementName 取页标题中【需求】后的名称；恢复重建时 clarifications 允许登记单条无澄清说明，如 {"q": "本轮无澄清（恢复重建）", "a": "<来源页或原因>"}，其余场景 clarifications 禁止为空）；
-3. 调 planning_checklist_save(checklist, restoreRef=<该候选页路径>) 回存（覆盖原页，勿产生重复页）；
-4. 回存成功后提示用户重新发送 ${routes.openspec} 确认。
+2. 若页尾含 <!-- dsh-swarm:checklist-json ... --> 机读段：不要手动重建、不要调 planning_checklist_save——直接提示用户重新发送 ${routes.openspec}（路由会自动机读恢复并当场建链，LLM 零参与）；
+3. 仅 legacy 页（无机读段）才执行本步：消化该页内容，重建结构化 PlanningChecklist（spec 六段 + manifest + clarifications + doubts + risks（风险点，若有），requirementName 取页标题中【需求】后的名称；恢复重建时 clarifications 允许登记单条无澄清说明，如 {"q": "本轮无澄清（恢复重建）", "a": "<来源页或原因>"}，其余场景 clarifications 禁止为空）；
+4. legacy 页重建后调 planning_checklist_save(checklist, restoreRef=<该候选页路径>) 回存（覆盖原页，勿产生重复页），成功后提示用户重新发送 ${routes.openspec} 确认。
 禁止：跳过恢复直接建链建卡；猜测清单内容；把恢复失败归因于"重试/进程检查"之外的任何原因。
 `;
 const RECOVERY_NONE_GUIDANCE = (routes) => `
@@ -270,13 +271,9 @@ export function registerMainSessionTools(ctx, configProvider) {
             }
             if (plan.kind === 'none')
                 return { kind: 'none' };
-            // 路由1（内存）：planningBySession 命中 → 直接建链
-            const pctx = planningBySession.get('session_main');
-            if (pctx?.checklist && pctx.checklistRef) {
-                // 恢复补捕①：内存有清单但 workspaceDir=null（主 agent 重启后清单经 KB 恢复、异常态）→
-                // 从 exec.agent.session.header.cwd 捡回工作区，路由1 继续正常建链。已有值绝不重解析
-                // （不重复弹 ask，对齐下方 /plan: 分支注释顾虑）；解析 null（无 cwd/无通道/用户跳过）保持
-                // 现状 → 走 handleOpenspecRoute 的 workspace-unknown fail-fast（不吞错、不猜测路径）。
+            // 建链共用段（2026-09-21 从路由1 提取）：恢复补捕① + workspace-mismatch 闸2 + handleOpenspecRoute。
+            // 路由1（内存命中）与路由2（KB 机读恢复命中）同走此函数，建链语义单一事实源。
+            const openChainFromContext = async (pctx) => {
                 if (!pctx.workspaceDir) {
                     const headerCwd = exec?.agent?.session?.header?.cwd ?? null;
                     const workspaceDir = await resolveOrCreateWorkspace(ctx, headerCwd, '主 agent 会话（/openspec: 恢复）');
@@ -303,11 +300,18 @@ export function registerMainSessionTools(ctx, configProvider) {
                     kind: 'openspec', chainId: r.chainId, specCardId: r.specCardId, approved: true, firstCard: r.firstCard,
                     guidance: KANBAN_HANDOFF_RULE(configProvider.getEffective().prefixRoutes, { swarm: planningBySession.get('session_main')?.mode === 'swarm' }) + '\n\n' + buildOpenspecNarrationRule({ chainId: r.chainId, specCardId: r.specCardId, firstCard: r.firstCard }),
                 };
+            };
+            // 路由1（内存）：planningBySession 命中 → 直接建链
+            const pctx = planningBySession.get('session_main');
+            if (pctx?.checklist && pctx.checklistRef) {
+                // 恢复补捕①：内存有清单但 workspaceDir=null（主 agent 重启后清单经 KB 恢复、异常态）→
+                // 从 exec.agent.session.header.cwd 捡回工作区（已有值绝不重解析，不重复弹 ask）。
+                return await openChainFromContext({ ...pctx, checklist: pctx.checklist, checklistRef: pctx.checklistRef });
             }
-            // 路由2（知识库）：内存丢失（插件重启）→ 搜 KB 候选清单页供 LLM 读页重建；搜不到/不可达 → 两条路皆空
-            // 恢复补捕②：无内存条目或工作区未捕获 → 从 header.cwd 捡回，写入 planningBySession（checklist 等
-            // 字段保持 cur 或空缺省），后续 planning_checklist_save 触发 onChecklistSaved 的 { ...cur } 展开自然
-            // 带上 workspaceDir。解析失败不阻塞恢复 guidance 返回（行为同现状，只是少捕一次）。
+            // 路由2（知识库）：内存丢失（插件重启）→ 优先机读恢复（2026-09-21 矫正）：候选页尾含无损 JSON 段
+            // → extractChecklistJson 提取 → 灌内存 → 当场建链（LLM 零参与，杜绝读页重建的失真/双重编码/回存绕路）；
+            // 无段/损坏/校验不过（legacy 页）→ 回退既有 LLM 读页重建+回存流程。搜不到/不可达 → 两条路皆空。
+            // 恢复补捕②：无内存条目或工作区未捕获 → 从 header.cwd 捡回，写入 planningBySession。
             if (!planningBySession.get('session_main')?.workspaceDir) {
                 const headerCwd = exec?.agent?.session?.header?.cwd ?? null;
                 const workspaceDir = await resolveOrCreateWorkspace(ctx, headerCwd, '主 agent 会话（/openspec: 恢复）');
@@ -321,6 +325,24 @@ export function registerMainSessionTools(ctx, configProvider) {
                 candidates = await searchChecklists(wiki, kbMode === 'local' ? LOCAL_CHECKLIST_PREFIX : (configProvider.getEffective().wikiVault?.pagePrefix ?? 'projects/'));
             }
             catch { /* KB 不可达/搜索失败 → 候选为空，走两条路皆空分支 */ }
+            let machineRestored = null;
+            for (const cpath of candidates) {
+                try {
+                    const d = await wiki.read(cpath);
+                    const c = extractChecklistJson(d.rawMd);
+                    if (c) {
+                        machineRestored = { path: cpath, checklist: c };
+                        break;
+                    }
+                }
+                catch { /* 单页读取失败 → 试下一候选 */ }
+            }
+            if (machineRestored) {
+                const cur = planningBySession.get('session_main') ?? { workspaceDir: null, sessionId: 'session_main', checklist: null, checklistRef: null, checklistSource: null, requirementName: null };
+                const rpctx = { ...cur, checklist: machineRestored.checklist, checklistRef: machineRestored.path, checklistSource: 'kb', requirementName: machineRestored.checklist.requirementName ?? null };
+                planningBySession.set('session_main', rpctx);
+                return await openChainFromContext(rpctx);
+            }
             return {
                 kind: 'openspec', approved: false, reason: 'no-checklist',
                 recovery: candidates.length > 0 ? 'kb' : 'none',

package/lib/tools/planning-tools.js

@@ -20,7 +20,93 @@ export function buildPlanningTools(deps) {
         defineTool({
             name: 'planning_checklist_save',
             description: 'Save the converged requirement-clarification checklist (structured schema) to KB, falling back to a temp dir if KB is unreachable. Returns ref/path + authoritative repo path. restoreRef (optional) = existing KB page path to overwrite in place (recovery path when in-memory context was lost); omit for first-time save (creates a new timestamped page).',
-            parameters: { checklist: { type: 'json', required: true, description: 'Structured PlanningChecklist: {requirementName?, spec: {problem, solution, user_stories, impl_decisions, testing, out_of_scope}, manifest, clarifications, doubts: Array<{"q": string, "resolved": boolean, "answer"?: string}>, risks?}. spec.user_stories: array of plain strings — each element ONE sentence "As a <role>, I want <capability>, so that <benefit>"; NEVER objects/nested. spec.impl_decisions: array of plain strings — one decision per element; NEVER objects. clarifications: non-empty required — record every Q&A asked during this planning round; Array<{"q": string, "a": string}> with keys exactly "q"/"a" (NOT "question"/"answer"). risks (optional): Array<{"description": string, "source": string, "mitigation": string}> — register real risks/non-blocking concerns surfaced during clarification; omit or [] when none. checklist.requirementName (optional) = ' + deps.prefixRoutes.plan + ' rest first sentence, used for the checklist page title 【需求】, same source as the task-card title' }, restoreRef: { type: 'string', description: 'Optional KB page path to overwrite in place (recovery path); omit for new save' } },
+            // 参数用官方类型化 schema（dsh-tools DSL：显式 object 必须声明 additionalProperties）在运行时
+            // 强制形状（ToolArgsError/INVALID_ARGS 带"路径+期望+enum"violation）；{type:'json'} 仅注解不
+            // 约束，曾致 spec 数组/双重编码/expected 词表错三连发（2026-09-21 销服一体清单案例，7 轮失败）。
+            // schema 表达不了的语义（非空、确切键名、expected 语义映射）仍由 description + validatePlanningChecklist 承担。
+            parameters: {
+                checklist: {
+                    type: 'object', required: true, additionalProperties: true,
+                    description: 'Structured PlanningChecklist. Shape is runtime-enforced by this schema; semantics not expressible in schema live in the description below.',
+                    properties: {
+                        requirementName: { type: 'string', description: 'Optional; page title 【需求】 source, same as task-card title' },
+                        spec: {
+                            type: 'object', required: true, additionalProperties: true,
+                            description: 'Six sections, all required.',
+                            properties: {
+                                problem: { type: 'string', required: true, description: 'ONE coherent multi-line text (non-empty), never an array' },
+                                solution: { type: 'string', required: true, description: 'ONE coherent multi-line text (non-empty), never an array' },
+                                testing: { type: 'string', required: true, description: 'ONE coherent multi-line text (non-empty), never an array' },
+                                out_of_scope: { type: 'string', required: true, description: 'ONE coherent multi-line text (non-empty), never an array' },
+                                user_stories: { type: 'array', required: true, items: { type: 'string' }, description: 'Plain strings only; each element ONE sentence "As a <role>, I want <capability>, so that <benefit>"; never objects/nested' },
+                                impl_decisions: { type: 'array', required: true, items: { type: 'string' }, description: 'Plain strings only; one decision per element; never objects' },
+                            },
+                        },
+                        manifest: {
+                            type: 'object', required: true, additionalProperties: true,
+                            description: 'Repo-baseline facts (same shape as planning_prefetch output manifest).',
+                            properties: {
+                                repo: {
+                                    type: 'object', required: true, additionalProperties: true,
+                                    properties: {
+                                        localPath: { type: 'string', required: true, description: 'Absolute path of the target repo' },
+                                        remoteUrl: { type: 'string' },
+                                        branch: { type: 'string' },
+                                        dirtyFiles: { type: 'array', required: true, items: { type: 'string' }, description: 'Uncommitted changes; [] when clean' },
+                                    },
+                                },
+                                files: {
+                                    type: 'array', required: true,
+                                    description: 'File baseline; [] when not prefetched.',
+                                    items: {
+                                        type: 'object', additionalProperties: true,
+                                        properties: {
+                                            path: { type: 'string', required: true },
+                                            expected: { type: 'string', required: true, enum: ['exists', 'absent', 'content-hash'], description: 'What the file IS in the repo, NOT your change intent — never "modify"/"create": plan-to-edit file → "exists" + note「计划修改」; plan-to-create file → "absent" + note「计划新建」' },
+                                            note: { type: 'string' },
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                        clarifications: {
+                            type: 'array', required: true,
+                            description: 'Record EVERY Q&A of this planning round; array must be non-empty (recovery rebuild may use {"q":"本轮无澄清（恢复重建）","a":"<来源页>"}).',
+                            items: {
+                                type: 'object', additionalProperties: true,
+                                properties: {
+                                    q: { type: 'string', required: true, description: 'Key is exactly "q", not "question"' },
+                                    a: { type: 'string', required: true, description: 'Key is exactly "a", not "answer"' },
+                                },
+                            },
+                        },
+                        doubts: {
+                            type: 'array', required: true,
+                            items: {
+                                type: 'object', additionalProperties: true,
+                                properties: {
+                                    q: { type: 'string', required: true },
+                                    resolved: { type: 'boolean', required: true },
+                                    answer: { type: 'string' },
+                                },
+                            },
+                        },
+                        risks: {
+                            type: 'array',
+                            description: 'Optional; register real risks/non-blocking concerns surfaced during clarification; omit or [] when none.',
+                            items: {
+                                type: 'object', additionalProperties: true,
+                                properties: {
+                                    description: { type: 'string', required: true },
+                                    source: { type: 'string', required: true },
+                                    mitigation: { type: 'string', required: true },
+                                },
+                            },
+                        },
+                    },
+                },
+                restoreRef: { type: 'string', description: 'Optional KB page path to overwrite in place (recovery path); omit for new save' },
+            },
             output: { schema: { type: 'json' }, render: (_a, v) => [{ type: 'text', text: JSON.stringify(v) }] },
             async execute(args) {
                 const caller = deps.getCaller();

package/lib/tools/spec-card-tools.js

@@ -6,9 +6,13 @@ function guard(action, caller) {
     if (!can(action, caller.actor, null))
         throw new Error('permission denied: ' + action);
 }
-/** 逐字段校验 spec card sections：数组进 string 段（如 testing）会在下游 .trim() 崩溃。 */
+/** 逐字段校验 spec card sections：数组进 string 段（如 testing）会在下游 .trim() 崩溃；
+ *  非对象（双重编码字符串）先报真因，不产生六字段误导性 undefined 墙。 */
 function validateSections(sections) {
     const errors = [];
+    if (sections !== undefined && (typeof sections !== 'object' || Array.isArray(sections))) {
+        return [`sections must be a JSON object (got ${Array.isArray(sections) ? 'array' : typeof sections}) — pass the object itself, never a JSON-encoded string`];
+    }
     const s = (sections ?? {});
     const strFields = [
         ['problem', 'problem'], ['solution', 'solution'], ['testing', 'testing'], ['out_of_scope', 'out_of_scope'],
@@ -47,7 +51,9 @@ export function buildSpecCardTools(service, getCaller) {
             description: 'Edit a draft spec card sections (human only).',
             parameters: {
                 cardId: { type: 'string', required: true },
-                sections: { type: 'json', required: true, description: 'Six-section spec card body' },
+                // 官方 object schema（2026-09-21）：{type:'json'} 不约束，双重编码字符串穿透 validateSections
+                // 产出六字段误导性 undefined 墙；open object 运行时拦字符串。
+                sections: { type: 'object', required: true, additionalProperties: true, description: 'Six-section spec card body (object with problem/solution/testing/out_of_scope strings + user_stories/impl_decisions string arrays). Pass the object itself — never a JSON-encoded string.' },
             },
             output: { schema: { type: 'json' }, render: (_a, v) => [{ type: 'text', text: JSON.stringify(v) }] },
             async execute(args) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joekytc/dsh-swarm",
-  "version": "0.3.8",
+  "version": "0.3.9",
   "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",
@@ -90,4 +90,4 @@
     "typescript": "^5.8.0",
     "vitest": "^3.0.0"
   }
-}
+}