@joekytc/dsh-swarm 0.3.8 → 0.3.10

package/lib/config.d.ts

@@ -95,7 +95,7 @@ export interface KanbanConfig {
      *  打的补丁；2026-09-17 起 preset 判定统一走 session-preset.ts（引擎真相优先），此处
      *  'ptc' 语义变为「显式放行普通 PTC 模式会话」（写面仍由 wiki_write 路径白名单硬约束）。
      *  宿主 preset 体系演化/部署自定义模式 id 时改配置即可，无需改代码。
-     *  写面仍由 wiki_write 工具内 assertAllowedWikiPagePath 五类命名空间白名单硬约束。 */
+     *  写面仍由 wiki_write 工具内 assertAllowedWikiPagePath 六类命名空间白名单硬约束。 */
     wikiWritePresets: string[];
 }
 export declare const Config: Schema<KanbanConfig>;

package/lib/dispatcher/agent-runner.js

@@ -5,8 +5,9 @@ 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 { toolName, isGuardSynthesizedReply } from './session-events.js';
 import { attachSessionToWorkspace, resolveOrCreateWorkspace } from './workspace-attach.js';
 import { isPathInside, resolveTargetRepoDir } from './target-repo.js';
 import { injectGitCredentials, resolveGitPatFromCtx } from './git-credentials.js';
@@ -82,6 +83,18 @@ export class AgentRunner {
         if (task.body)
             parts.push(`## Body
 ${task.body}`);
+        // 评审引擎（配置事实）：reviewEngine.mode 决定 ocr_review 走托管还是委托。此前全链无注入点，
+        // 模型只能猜——真实事故（2026-09-23）：面板配 managed 且已 wire，DT 仍按委托跑，并引用旧链
+        // 交接里「托管未配置→回落委托」的过期叙述当现状。本节热读配置，是运行时唯一权威来源。
+        if (task.assignee === 'dt') {
+            const re = this.configProvider.getEffective().reviewEngine;
+            const mode = re?.mode ?? 'delegate';
+            const provider = re?.managed?.provider ?? '';
+            const model = re?.managed?.model ?? '';
+            parts.push('## 评审引擎（配置事实，唯一权威；禁止从历史交接推断）', `- reviewEngine.mode = ${mode}${provider && model ? `（managed: provider=${provider} model=${model}）` : ''}`, mode === 'managed'
+                ? "- 托管：调 ocr_review{sub:'managed', from:<TARGET_BRANCH>, to:<branch>} 一次取归一化 findings；仅当工具返回「托管未配置」指引或 status !== 'completed' 时才静默改走委托（preview → rule → git diff 自评）"
+                : "- 委托：ocr_review{sub:'preview'} → ocr_review{sub:'rule'} → 自行 git diff 逐文件评审", '- 历史 handoff / 旧链交接里的「托管未配置 / 回落委托」等叙述属过期事实，不得当现状。');
+        }
         // W local KB 模式：注入本地库根 + llm-wiki 用法 + 排序原则 + 交付约定（remote 模式不注入）。
         // 库内复制/移动补句：DIRECT cp/mv/mkdir 工具永远匹配不到 KB 目标（无 path/file_path
         // 实参）会被护栏拒绝——必须显式指引 W 用 write 工具做库内复制/移动。
@@ -271,7 +284,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) {
@@ -439,6 +455,25 @@ ${task.body}`);
                 console.error('[dsh-swarm][debug] runner followup sent ' + taskId);
                 await agent.whenIdle();
                 console.error('[dsh-swarm][debug] runner whenIdle resolved ' + taskId);
+                // 网关合成拒答兜底（2026-09-22）：jz 网关语义缓存（from-cache）/ 安全护栏（from-security-guard）
+                // 会对首轮任务 prompt 合成 usage 全 0 的拒答，角色会话拿拒答当结论空闲退出
+                // （protocol_violation 源头之一，销服一体 W2 卡会话 5 例实证）。检测到即自动
+                // followup「继续未完成的任务」重试一次（限一次，防护栏连续拦截打穿重派链）；
+                // 重试后再拦则照旧走终态判据（running → protocol_violation 显形）。
+                // 读取容错对齐 session-events.ts 约定（snapshotEvents → events → []）；
+                // seq > eventsBase 过滤本轮增量（防 resume 时历史 from-cache 标记误触发；fake/宿主
+                // 变体无 seq 时 Number→NaN，比较恒 false → 检测跳过，不误伤）。
+                const sessionLike = agent.session;
+                const turnEvents = typeof sessionLike.snapshotEvents === 'function'
+                    ? sessionLike.snapshotEvents(eventsBase)
+                    : (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' } });
+                    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);
+                }
                 // 终态判据（session 10 事故修复）：whenIdle resolve 后一次 snapshot，只看任务真实状态——
                 // 不再扫 session.events 全历史工具名（旧 incarnation 的 kanban_* 事件会污染判据，
                 // 「历史上调过工具名」≠「本轮成功提交」，骗过检查后卡永驻 running）。

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/merge-gate.d.ts

@@ -5,6 +5,7 @@ export interface MergeInput {
     repoDir: string;
     targetBranch: string;
     featureBranch: string;
+    greenfield: boolean;
 }
 export declare const MERGE_DONE_PREFIX = "[merge-done]";
 export declare const MERGE_SKIP_PREFIX = "[merge-skip]";

package/lib/dispatcher/merge-gate.js

@@ -20,7 +20,8 @@ export function resolveMergeInput(dTask, state, fallbackRepo) {
     const featureBranch = String(state.handoffs.get(dTask.id)?.metadata?.['branch'] ?? '').trim();
     if (!targetBranch || !featureBranch)
         return null;
-    return { repoDir, targetBranch, featureBranch };
+    const greenfield = /GREENFIELD\s*=\s*1/.test(dTask.body ?? '');
+    return { repoDir, targetBranch, featureBranch, greenfield };
 }
 /** 幂等判定：已存在 [merge-done] 评论，或 feature 分支已是 target 祖先（git merge-base --is-ancestor exit 0）。 */
 export function isAlreadyMerged(state, dTaskId, repoDir, targetBranch, featureBranch, git) {
@@ -46,6 +47,32 @@ export async function runMergeGate(kanban, state, dTask, input, git = realGitRun
     const { repoDir, targetBranch, featureBranch } = input;
     if (isAlreadyMerged(state, dTask.id, repoDir, targetBranch, featureBranch, git))
         return 'skipped';
+    if (input.greenfield) {
+        // 首合入建基线：target 分支不存在（rev-parse --verify 非零）→ 以 feature HEAD 建基线分支
+        let targetExists = true;
+        try {
+            git(['rev-parse', '--verify', targetBranch], repoDir);
+        }
+        catch {
+            targetExists = false;
+        }
+        if (!targetExists) {
+            try {
+                // 免 checkout 建分支：D 在 linked git worktree 中 feature 分支已检出，checkout 会硬失败；
+                // branch 自 featureBranch 指针对齐（linked-worktree 与原地场景均可用）。
+                git(['branch', targetBranch, featureBranch], repoDir);
+                git(['push', '-u', 'origin', targetBranch], repoDir);
+                const hash = git(['rev-parse', featureBranch], repoDir);
+                await kanban.comment(dTask.id, `${MERGE_DONE_PREFIX} greenfield baseline ${targetBranch} ← ${featureBranch} hash=${hash}`, 'system');
+                return 'merged';
+            }
+            catch (err) {
+                await kanban.comment(dTask.id, `${MERGE_FAILED_PREFIX} greenfield baseline ${featureBranch} → ${targetBranch} failed: ${String(err)}`, 'system');
+                return 'failed';
+            }
+        }
+        // target 已存在（后续卡）→ 落回既有 checkout/merge 路径
+    }
     try {
         git(['checkout', targetBranch], repoDir);
         git(['merge', '--no-ff', featureBranch, '-m', `[AI-GEN] merge ${featureBranch} into ${targetBranch} after DT pass`], repoDir);

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

@@ -20,5 +20,13 @@ export declare function toolName(e: unknown): string | undefined;
 export declare function toolArgs(e: unknown): Record<string, unknown>;
 /** 取 assistant 消息的网关缓存回放标记（replayState.response.responseModel，如 'from-cache'）。
  *  非 assistant/message 或无标记返回 null。2026-09-04：远程网关回复缓存整包回放时由 SSE
- *  id/model 字段透传（dsh 纯透传），插件侧据此识别缓存劫持零产出。 */
+ *  id/model 字段透传（dsh 纯透传），插件侧据此识别缓存劫持零产出。兼容落盘（data.message）
+ *  与 live 内存（顶层 message）两种形态。 */
 export declare function replayModel(e: unknown): string | null;
+/** 网关合成拒答/缓存回放标记集（usage 全 0，非真实模型输出）：
+ *  - from-cache：Higress 语义缓存命中（网关侧可用请求头 x-higress-skip-ai-cache: on 跳过，2026-09-22 网关团队确认）
+ *  - from-security-guard：安全护栏合成拒答（销服一体 W2 卡会话 5 例实证，responseId 可供网关审计）
+ *  角色会话拿到合成文本会当结论空闲退出（protocol_violation 源头之一），必须识别。 */
+export declare const GUARD_SYNTH_REPLAY_MODELS: ReadonlySet<string>;
+/** 该事件是否为网关合成拒答/缓存回放的 assistant 消息（判定与标记集单一事实源）。 */
+export declare function isGuardSynthesizedReply(e: unknown): boolean;

package/lib/dispatcher/session-events.js

@@ -37,9 +37,21 @@ export function toolArgs(e) {
 }
 /** 取 assistant 消息的网关缓存回放标记（replayState.response.responseModel，如 'from-cache'）。
  *  非 assistant/message 或无标记返回 null。2026-09-04：远程网关回复缓存整包回放时由 SSE
- *  id/model 字段透传（dsh 纯透传），插件侧据此识别缓存劫持零产出。 */
+ *  id/model 字段透传（dsh 纯透传），插件侧据此识别缓存劫持零产出。兼容落盘（data.message）
+ *  与 live 内存（顶层 message）两种形态。 */
 export function replayModel(e) {
     const rec = e;
-    const m = rec?.data?.message?.source?.replayState?.response?.responseModel;
+    const m = rec?.data?.message?.source?.replayState?.response?.responseModel
+        ?? rec?.message?.source?.replayState?.response?.responseModel;
     return typeof m === 'string' ? m : null;
 }
+/** 网关合成拒答/缓存回放标记集（usage 全 0，非真实模型输出）：
+ *  - from-cache：Higress 语义缓存命中（网关侧可用请求头 x-higress-skip-ai-cache: on 跳过，2026-09-22 网关团队确认）
+ *  - from-security-guard：安全护栏合成拒答（销服一体 W2 卡会话 5 例实证，responseId 可供网关审计）
+ *  角色会话拿到合成文本会当结论空闲退出（protocol_violation 源头之一），必须识别。 */
+export const GUARD_SYNTH_REPLAY_MODELS = new Set(['from-cache', 'from-security-guard']);
+/** 该事件是否为网关合成拒答/缓存回放的 assistant 消息（判定与标记集单一事实源）。 */
+export function isGuardSynthesizedReply(e) {
+    const m = replayModel(e);
+    return m !== null && GUARD_SYNTH_REPLAY_MODELS.has(m);
+}

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';
@@ -24,6 +25,7 @@ export const PHASE_INSTRUCTIONS = {
         '## P 阶段任务体要求（计划者，非执行者）',
         'body 写入规划指令：读规格卡（含 file-prefetch/kb 附件=需求澄清清单）→ 产出 openspec 实施计划。仓库事实不足时先只读自查仓库代码实证（fs/search/grep 均可），再产出计划。',
         '产物路径（OpenSpec 规范）：写入目标仓库 `openspec/changes/<change_name>/` 下 proposal.md / design.md / tasks.md（change_name 依规格自拟 kebab-case，如 autoNote-tab）；complete 时 metadata.artifacts_path = 该目录绝对路径。',
+        'greenfield（清单 greenfield:true）：openspec 产物仍写目标目录 `openspec/changes/<change_name>/`（目录可先不存在，空目录可写）；P 不 git init——建仓属 D 职责，P 保持只读。',
         'tasks.md 拆分粒度（结构准备度，与 PT 同一判据）：每个任务条目必须有单一、可独立核对的完成判据；禁止一条任务/一条测试用例混 N≥2 个互不依赖的可观察结果——按可独立验证的行为逐条拆分。完成判据必须是实施完成后的单一终态；不写执行层阶段态判据（RED/GREEN/REFACTOR、"先失败再通过"属 D 阶段执行协议，见 D 阶段模板）。',
         'proposal.md 必须含「上游协议遵循说明」节：逐条列规格卡/澄清清单声明的工程协议引用（可定位出处：路径/明确协议名）+ 计划如何遵守；未声明任何协议则该节写「无」。禁止引用规格卡之外的协议标准。',
         '需求对齐（颗粒度）：澄清清单/规格卡的任务项、任务点、注意点 ↔ 计划任务逐条双向映射——不遗漏；超纲任务须能溯源到澄清回答。',
@@ -52,6 +54,7 @@ export const PHASE_INSTRUCTIONS = {
         '## D 阶段任务体要求（执行者，唯一，非只读对齐/校验）',
         'body 写入执行指令：先读父任务交接（W2）里的 page_path/kb_url，用 wiki_read 读取 openspec 实施计划原文，再按计划执行规格卡 solution/testing —— git worktree/branch → 改代码/README → git commit → git push（仅 feature 分支，可选）→ 自检（跑测试/构建）并附产物证据（changed_files/commit_hash）。',
         'body 第一行以 TARGET_REPO=<真实仓库绝对路径> 声明目标仓库：必须取自规格卡 file-prefetch 附件 ref，禁止写 kanban 存储目录、禁止猜测回退。',
+        'greenfield（清单 greenfield:true 声明）：TARGET_REPO 取清单 manifest.repo.localPath（无 file-prefetch 附件 ref 时）；body 额外声明 GREENFIELD=1（merge-gate 首合入建基线用）。首步建仓前置：mkdir -p 目标目录 → git init -b main → 写 .gitignore/README → git add + commit 初始提交（tdd 声明用 { skipped: { reason: "greenfield scaffold" } }）→ 再按既有 git worktree/branch → 改代码 → commit → push(feature) 流程。；若目标目录已有 .git（声明与事实不符）→ 跳过建仓前置，直接走既有 worktree 流程，并在 complete 摘要注明声明与事实不符',
         'body 同时声明 TARGET_BRANCH=<目标分支名>（来自规格卡/用户声明）：D 在 worktree feature 分支完成实现并验证后即 complete，禁止合并回 TARGET_BRANCH、禁止推 TARGET_BRANCH——合入由 DT 通过后 system 统一执行。',
         'complete 时 metadata 必须带 branch=<feature 分支名>（DT 评审与 system 合入定位该分支用）；git 证据 changed_files + commit_hash 必须（push 可选，可推 feature 分支）。',
         'complete 时 metadata 建议携带 worktree_dir=<你的 feature worktree 绝对路径>：系统将在该目录实测 tdd.test_files（npx vitest run）；缺失则跳过实测（仅声明校验）。',
@@ -61,7 +64,7 @@ export const PHASE_INSTRUCTIONS = {
     ].join('\n'),
     dt: [
         '## DT 阶段任务体要求（实现校验+评审，只读护栏）',
-        'body 写入实现校验指令：对 D 产物实证校验（test/build/typecheck/diff/git 证据 + open-code-review 评审），输出 verdict+issues 入交接 metadata.review_evidence。评审目标为 D 交接 metadata.branch 指向的 feature 分支，而非 TARGET_BRANCH。评审引擎：用 ocr_review 工具按配置引擎评审——委托 = preview→rule→git diff 自评；托管 = managed 一次出 findings；托管未配置时按工具指引静默改走委托；ocr 未安装则 kanban_block(\'review-tool-unavailable\') 并注明可在 GUI 配置面板安装。',
+        'body 写入实现校验指令：对 D 产物实证校验（test/build/typecheck/diff/git 证据 + open-code-review 评审），输出 verdict+issues 入交接 metadata.review_evidence。评审目标为 D 交接 metadata.branch 指向的 feature 分支，而非 TARGET_BRANCH。评审引擎：用 ocr_review 工具按配置引擎评审——委托 = preview→rule→git diff 自评；托管 = managed 一次出 findings；托管未配置时按工具指引静默改走委托；ocr 未安装则 kanban_block(\'review-tool-unavailable\') 并注明可在 GUI 配置面板安装。ocr_review 的 repo 参数缺省 = 会话工作目录；评审目标不在其内（D 的 worktree / 其他仓库）时须显式传仓库绝对路径（取 D 交接 metadata.worktree_dir 或规格卡 file-prefetch 附件 ref）。',
         '铁律：DT 是只读校验+评审角色，绝不修改源码/产物；校验经 ToolGuard 硬性只读护栏；不注入 git 凭据。',
     ].join('\n'),
     w3: [
@@ -86,7 +89,7 @@ export function buildPhaseInstruction(phase, ctx, kbMode) {
         case 'd':
             return '先读父任务交接（W2）里的 page_path（本地库 wiki/sources/ 下相对路径，库根见运行时上下文注入——Task 8 已注入 D），直接 fs 读实施计划原文；如需 KB 经验召回，经 skill 工具加载 llm-wiki query（本地库；kanban-d preset 已挂 tool-skill）——再按计划执行规格卡 solution/testing —— git worktree/branch → 改代码/README → git commit → git push（仅 feature 分支，可选）→ 自检并附产物证据（changed_files/commit_hash）。其余 TDD/TARGET_REPO/TARGET_BRANCH 等要求与 remote 版一致。';
         case 'dt':
-            return `对 D 产物实证校验（test/build/typecheck/diff/git 证据 + open-code-review 评审），输出 verdict+issues 入交接 metadata.review_evidence。评审引擎：用 ocr_review 工具按配置引擎评审（委托 = preview→rule→git diff 自评；托管 = managed 一次出 findings；托管未配置时按工具指引静默改走委托；ocr 未安装则 kanban_block('review-tool-unavailable') 并注明可在 GUI 配置面板安装）。评审页经 fs 写本地库 <库根>/wiki/queries/${ctx.chainId}/review/<name>.md（库根已由系统注入 DT 运行时上下文）；库根外一律只读，其余铁律与 remote 版一致。`;
+            return `对 D 产物实证校验（test/build/typecheck/diff/git 证据 + open-code-review 评审），输出 verdict+issues 入交接 metadata.review_evidence。评审引擎：用 ocr_review 工具按配置引擎评审（委托 = preview→rule→git diff 自评；托管 = managed 一次出 findings；托管未配置时按工具指引静默改走委托；ocr 未安装则 kanban_block('review-tool-unavailable') 并注明可在 GUI 配置面板安装）。ocr_review 的 repo 缺省 = 会话工作目录，评审目标不在其内（D 的 worktree / 其他仓库）时显式传仓库绝对路径（D 交接 metadata.worktree_dir / 规格卡 file-prefetch ref）。评审页经 fs 写本地库 <库根>/wiki/queries/${ctx.chainId}/review/<name>.md（库根已由系统注入 DT 运行时上下文）；库根外一律只读，其余铁律与 remote 版一致。`;
         default:
             return PHASE_INSTRUCTIONS[phase] ?? '';
     }
@@ -442,9 +445,11 @@ export class VOrchestrator {
             // blocked（防线A：零任务链也有数据侧终态，人工恢复=删链重跑）。零任务无锚点可评论 →
             // 落 console.error（无任务卡载体，auditWarning 语义不符不用），orchestration.json 已留 stallCount。
             if (!firstMatch) {
-                const fromCache = !turnError && agent !== null && sessionEventsOf(agent).some((e) => replayModel(e) === 'from-cache');
-                if (fromCache) {
-                    console.error('[dsh-swarm][debug] V turn replayed from gateway cache (from-cache, usage=0) chain=' + chainId + ' phase=' + orch.phase + ' — 缓存污染嫌疑，按零产出计 stall');
+                // 2026-09-22：标记集扩展 from-security-guard（安全护栏合成拒答与语义缓存同族——
+                // guard 拒答被语义缓存收录后，语义相近的新任务 prompt 全部命中回放）。
+                const guardReplay = !turnError && agent !== null && sessionEventsOf(agent).some((e) => replayModel(e) === 'from-cache' || replayModel(e) === 'from-security-guard');
+                if (guardReplay) {
+                    console.error('[dsh-swarm][debug] V turn synthesized by gateway (from-cache/from-security-guard, usage=0) chain=' + chainId + ' phase=' + orch.phase + ' — 缓存/护栏污染嫌疑，按零产出计 stall');
                 }
                 orch.stallCount = (orch.stallCount ?? 0) + 1;
                 if (orch.stallCount > VOrchestrator.STALL_REWAKE_LIMIT) {
@@ -636,9 +641,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/ocr-review.d.ts

@@ -2,6 +2,7 @@
 export type OcrSub = 'preview' | 'rule' | 'managed';
 /** OCR 调用可选参数集合。 */
 export interface OcrArgsInput {
+    /** 目标仓库根绝对路径（调用方解析：显式入参 → 当前会话工作目录）；缺省时 ocr 用进程 current dir。 */
     repo?: string;
     from?: string;
     to?: string;
@@ -12,7 +13,10 @@ export interface OcrArgsInput {
 }
 /** 构造 OCR CLI 参数：preview/rule 走 delegate，managed 走 review。
  * preview 默认输出 text，必须显式 --format json 才能拿到可解析输出；
- * managed 恒带 --audience agent（agent 场景标准参数，抑制 progress 输出）。 */
+ * managed 恒带 --audience agent（agent 场景标准参数，抑制 progress 输出）。
+ * 三子命令一律透传 --repo（preview/rule/review 均支持该 flag，实测 --help）：
+ * ocr 探测仓库默认用 current dir，而本插件进程 cwd 不是目标仓库（实测为 ~/.codebuddy，
+ * 非 git 仓库）——漏传即稳定报 "Error: <cwd> is not a git repository"。 */
 export declare function buildOcrArgs(sub: OcrSub, a: OcrArgsInput): string[];
 /** 预览结果归一化结构。 */
 export interface PreviewResult {

package/lib/domain/ocr-review.js

@@ -1,6 +1,9 @@
 /** 构造 OCR CLI 参数：preview/rule 走 delegate，managed 走 review。
  * preview 默认输出 text，必须显式 --format json 才能拿到可解析输出；
- * managed 恒带 --audience agent（agent 场景标准参数，抑制 progress 输出）。 */
+ * managed 恒带 --audience agent（agent 场景标准参数，抑制 progress 输出）。
+ * 三子命令一律透传 --repo（preview/rule/review 均支持该 flag，实测 --help）：
+ * ocr 探测仓库默认用 current dir，而本插件进程 cwd 不是目标仓库（实测为 ~/.codebuddy，
+ * 非 git 仓库）——漏传即稳定报 "Error: <cwd> is not a git repository"。 */
 export function buildOcrArgs(sub, a) {
     if (sub === 'preview') {
         const args = ['delegate', 'preview', '--format', 'json'];
@@ -17,7 +20,10 @@ export function buildOcrArgs(sub, a) {
         return args;
     }
     if (sub === 'rule') {
-        return ['delegate', 'rule', ...(a.paths ?? [])];
+        const args = ['delegate', 'rule', ...(a.paths ?? [])];
+        if (a.repo)
+            args.push('--repo', a.repo);
+        return args;
     }
     const args = ['review'];
     if (a.commit)
@@ -31,6 +37,8 @@ export function buildOcrArgs(sub, a) {
     args.push('--format', 'json', '--audience', 'agent');
     if (a.background)
         args.push('--background', a.background);
+    if (a.repo)
+        args.push('--repo', a.repo);
     return args;
 }
 /** 解析失败的兜底结果。 */

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

@@ -1,5 +1,24 @@
 import type { SpecCardSections } from './types.js';
 import { type PrefetchManifest } from './prefetch-manifest.js';
+export interface SourceEntry {
+    type: 'TAPD' | 'Jira' | '其他';
+    url: string;
+    note: string;
+}
+export interface PrdCollectionEntry {
+    url: string;
+    platform?: string;
+    status: 'collected' | 'blocked';
+    summary: string;
+    pages?: string[];
+    blockedReason?: string;
+    degraded?: boolean;
+}
+export interface PlaceholderEntry {
+    target: string;
+    value: string;
+    replace: string;
+}
 export interface PlanningChecklist {
     requirementName?: string;
     spec: SpecCardSections;
@@ -18,10 +37,24 @@ export interface PlanningChecklist {
         source: string;
         mitigation: string;
     }>;
+    sources: SourceEntry[];
+    prdCollection: PrdCollectionEntry[];
+    placeholders?: PlaceholderEntry[];
+    greenfield?: boolean;
 }
+/** 闸2 禁词表：澄清答案中指代不明的缩写；宁窄后扩，避免误伤正常表述。 */
+export declare const FORBIDDEN_SHORTHANDS: string[];
 /** 需求澄清清单 schema 硬校验：返回错误列表（空数组=合法）。清单缺段即拒绝保存（硬闸，主 agent 会话内修正）。 */
 export declare function validatePlanningChecklist(raw: unknown): string[];
 /** 需求澄清清单页标题：与任务卡 title 同源同逻辑（buildChainTitle），保证 KB 可检索。 */
 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;
+/** PRD 链接域名路由：已知平台直接判定，其余返回 null 交 LLM 自判。 */
+export declare function routePrdPlatform(url: string): string | null;
+/** PRD 原文切片：优先按一级标题（# 开头）切章，单片超 maxBytes 按行硬切。
+ *  默认 45KB/片（wiki 大文档拆页惯例，低于服务端 body 上限留余量）。 */
+export declare function slicePrdMarkdown(md: string, maxBytes?: number): string[];