sillyspec 3.27.2 → 3.27.6

package/.claude/worktrees/sillyspec-data-model-research/src/dispatch/backends/sillyhub-mcp.js

@@ -0,0 +1,245 @@
+/**
+ * SillyHub MCP 后端派发指令模板（task-dispatcher 抽象层）— task-04
+ *
+ * 定位（D-007）：dispatcher **不是 JS 执行体**。SillyHub 的 MCP tool（create_mission /
+ * dispatch_worker / list_workers / report_progress）只有 agent 能调，CLI（Node）进程调不了。
+ * 所以本文件 = **派发指令模板生成器**：生成注入 execute prompt 的「派发指令文本」，告诉
+ * agent 如何经 SillyHub MCP tool 创建 mission / 派 worker / 轮询终态 / kill lease / 回收；
+ * 实际 MCP tool 调用由 agent 执行，本模块不调任何 tool，也不直接 import client.js。
+ *
+ * 路径 A 探测翻真（task-11，D-005 + R-04）：`isPathASupported()` 读 probe.js 预热的
+ * tools/list 探测缓存——`dispatch_worker.inputSchema.properties` 含 `worktree_path` 与
+ * `worker_prompt` → true；任一缺失 / 未预热 / 探测失败 → false（保守回退 Local，**绝不硬试路径A**）。
+ * env 备选（spike-01 不通过时）：`process.env.SILLYHUB_PATH_A==='1'` → true（手动标记 daemon 侧
+ * 已落地）。探测预热住 probe.js `probeSillyHub`（daemon 可达后 best-effort 调 `client.listTools()`），
+ * 本模块只缓存探测结果 + 同步读——保持 `isPathASupported()` sync 签名不改 strategy.js /
+ * execute.js `getDispatchMode` 调用点（探测 = async，读缓存 = sync，解耦）。
+ *
+ * 铁律：
+ * - converge_mission 不出现在任何指令文本（D-004，SillySpec 自己 apply）；JSDoc 仅作开发者锚点。
+ * - worker 不 git commit，改动留 worktree 工作区（D-003@v2 第三处 UB-1，worker_prompt 覆写）。
+ * - 不直接调 client，只生成指令由 agent 执行 MCP tool 调用（探测由 probe.js 调 client，本模块仅读缓存）。
+ * - 路径 A 检测保守：不支持即回退，不硬试。
+ * - 兼容 Win/Linux/macOS：本文件无路径拼接 / 无平台分支，纯模板生成。
+ */
+
+/**
+ * 路径 A 未落地时 strategy.js 拼到降级提示里的原因说明。
+ *
+ * 属指令文本（会注入 prompt），故不含 converge_mission 字面（D-004）。strategy 在探测到
+ * isPathASupported()=false 时把此串拼进降级提示，引导 agent 回退 Local。
+ */
+export const PATH_A_DOWNGRADE_REASON =
+  '路径A 跨仓未落地：dispatch_worker 不支持 worktree_path / render_worker_prompt 仍硬编码 commit，本次派发回退 Local'
+
+/**
+ * SillyHub 后端结果回收约定（worker 终态 → review.json，D-004 + UB-1）。
+ *
+ * 与 Local 后端回收同构（R-07 屏蔽后端差异）：worker 终态后 SillySpec 主体对 worktree
+ * **工作区**做 git diff 写 review.json。差异在 worker 侧产出形态——SillyHub worker **绝不
+ * git commit**（路径A 第三处 UB-1，worker_prompt 已覆写覆盖 daemon 默认 commit 行为），改动
+ * 全留工作区；合并回主干由 SillySpec 自己 apply（worktree-apply 全门控保留），**不调 SillyHub
+ * 合并 tool**（D-004）。
+ *
+ * 抽成独立常量供 strategy.js 在拼接降级 / 回收段时复用，避免 Local 与 SillyHub 两份回收文案
+ * 重复维护。含 `<runId>` 占位符，使用方按实际 contract.runId 替换（见 renderSillyHubInstruction）。
+ */
+export const SILLYHUB_RECYCLE_RULE = `### 回收约定（worker 终态 → review.json，SillySpec 自己 apply）
+
+worker 终态后，**回收不依赖 worker git commit，也不调 SillyHub 合并 tool**：SillySpec 主体
+（你，调度 agent）对 worktree **工作区**做 git diff，按既有 task-review 契约写 review.json；
+合并回主干由 SillySpec 自己 apply（worktree-apply / Review Gate / assess 全门控保留）。
+
+1. worker 终态（completed / failed / killed）后，读取该 task 在 worktree 工作区的 git diff
+   （task 派发 → 终态的工作区变更；worker 未 commit 故全在工作区，不依赖 worker 自报）
+2. 对照 plan.md 与 tasks/task-XX.md 检查实现（不信任 worker 自报，只看当前 task 的 diff）
+3. 写入 review.json：\`.runtime/execute-runs/<runId>/tasks/task-XX/review.json\`
+4. review.json 写入成功后，该 task 的派发回收完成；合并走 SillySpec apply，不调 SillyHub 合并 tool
+
+review.json 复用既有 task-review 契约（必填字段：schemaVersion / task / base / head /
+changedFiles / specVerdict / qualityVerdict / reviewerNotes / requiredEvidence），不发明
+新契约。回收屏蔽后端差异：无论 Local 还是 SillyHub worker，SillySpec 都自己 diff worktree
+工作区写 review.json，再自己 apply（D-004）。`
+
+/**
+ * 路径A 探测结果缓存（task-11）：probe.js `probeSillyHub` 预热 → `isPathASupported` 同步读。
+ *
+ * 保持 `isPathASupported` sync 签名（strategy.js / execute.js `getDispatchMode` 同步调，不改
+ * 调用点）：探测是 async（probe.js 调 client.listTools），读缓存是 sync。未预热（probe 未跑 /
+ * 探测失败）→ 默认 false（保守 R-04，不硬试路径A）。模块级单例，进程内有效；测试用
+ * `clearPathAProbeCache` 隔离。
+ */
+let _pathAProbe = { probed: false, supported: false };
+
+/**
+ * 写路径A 探测结果（probe.js `probeSillyHub` 在 daemon 可达后预热调用）。
+ * @param {boolean} supported - dispatch_worker schema 含 worktree_path + worker_prompt
+ */
+export function setPathAProbeResult(supported) {
+  _pathAProbe = { probed: true, supported: !!supported };
+}
+
+/**
+ * 清空路径A 探测缓存（测试隔离用；生产中进程重启 / 不需要 TTL，probe 每次可达都重预热带新值）。
+ */
+export function clearPathAProbeCache() {
+  _pathAProbe = { probed: false, supported: false };
+}
+
+/**
+ * 路径 A 是否已落地（dispatch_worker 支持 caller worktree + worker_prompt 覆写）。
+ *
+ * task-11 翻真（D-005 + R-04）：读 probe.js 预热的探测结果（probeSillyHub 经 `tools/list` 查
+ * `dispatch_worker.inputSchema.properties` 含 `worktree_path` 与 `worker_prompt`）。保持 sync
+ * 签名（strategy.js / execute.js `getDispatchMode` 同步调），探测预热在 probe 流程。
+ *
+ * 判定顺序（保守，**绝不硬试路径A**）：
+ * 1. **env 强制开启**：`process.env.SILLYHUB_PATH_A==='1'` → true（spike-01 不通过 / tools/list
+ *    不可达时的备选，手动标记 daemon 侧路径A 已落地；优先级最高，让探测不可信时也能启用）
+ * 2. 否则读探测缓存：probe 预热且 dispatch_worker schema 全命中（worktree_path + worker_prompt）→ true
+ * 3. 未预热 / 探测失败 / schema 缺字段 → false（保守回退 Local，R-04）
+ *
+ * @returns {boolean} 路径A 可用 → true；否则 false（保守不硬试，R-04）
+ */
+export function isPathASupported() {
+  // 1. env 强制开启（spike-01 备选）：优先级最高，探测不可信 / 不可达时手动启用
+  if (process.env.SILLYHUB_PATH_A === '1') return true;
+  // 2. 读 probe 预热的 schema 探测缓存（未预热 → supported=false，保守 R-04 不硬试）
+  return _pathAProbe.supported;
+}
+
+/**
+ * @typedef {import('./local-agent.js').DispatchContract} DispatchContract
+ * @see design.md「接口定义」DispatchContract：brief / worktreePath / branch / allowedPaths /
+ *      readOnly / modelHint / agentProfileHint / runId / missionId（与 task-03 Local 后端同构）
+ */
+
+/**
+ * 渲染 SillyHub 后端派发指令文本（路径 A 落地后由 strategy.js 注入 execute prompt）。
+ *
+ * 纯模板生成器：不校验 contract 完整性、不调任何 MCP tool / client，只把 contract 字段拼成
+ * 可注入 execute prompt 的中文指令字符串。contract 缺字段时回退到醒目占位符（`<未提供 ...>`），
+ * 让 agent 在 prompt 里一眼看到派发前必须补齐的参数，而非静默产出错位指令。
+ *
+ * 指令含四要点（D-008 / D-003@v2 / UB-6 / D-004）：
+ * 1. **一 Wave 一 mission**：agent 先调 create_mission（objective/change_id/budget_usd per Wave），
+ *    Wave 内 task→worker 并行 dispatch，Wave 间 mission 串行
+ * 2. **dispatch_worker 参数**：mission_id/objective/worktree_path/branch/read_only/model/
+ *    agent_profile_id/worker_prompt（覆写：worker 不 git commit）
+ * 3. **终态轮询**：agent 轮询 list_workers，per-worker 超时 → report_progress 标记 + kill lease
+ *    防双写 + fallback Local 重派
+ * 4. **回收约定**：worker 不 commit，SillySpec 自己 diff worktree 写 review.json，不调合并 tool
+ *
+ * @param {DispatchContract} [contract] - 派发契约（见 design.md DispatchContract 接口定义）
+ * @returns {string} 注入 execute prompt 的 SillyHub 后端派发指令文本
+ */
+export function renderSillyHubInstruction(contract) {
+  const c = contract || {}
+  const worktreePath = c.worktreePath
+  const branch = c.branch
+  const allowedPaths = Array.isArray(c.allowedPaths) ? c.allowedPaths : null
+  const readOnly = !!c.readOnly
+  const brief = c.brief
+  const runId = c.runId
+  const modelHint = c.modelHint
+  const agentProfileHint = c.agentProfileHint
+  const missionId = c.missionId
+
+  // 回收约定：替换 <runId> 占位符；runId 缺失保留占位符让 agent 警觉
+  const recycleRule = SILLYHUB_RECYCLE_RULE.replaceAll(
+    '<runId>',
+    runId ? String(runId) : '<未提供 runId>'
+  )
+
+  // 各字段缺省醒目占位（派发前必须补齐的参数一眼可见）
+  const worktreeDisplay = worktreePath
+    ? String(worktreePath)
+    : '<未提供 contract.worktreePath — 派发前必须补齐，否则 worker cwd 错位>'
+  const branchDisplay = branch
+    ? String(branch)
+    : '<未提供 contract.branch — 派发前必须补齐 worktree 当前分支>'
+  const briefDisplay = brief
+    ? String(brief)
+    : '<未提供 contract.brief — 派发前必须补齐任务目标与蓝图路径>'
+  const missionDisplay = missionId
+    ? String(missionId)
+    : '<本 Wave mission_id — 先调 create_mission 拿到后填入>'
+
+  const allowedLine = allowedPaths && allowedPaths.length
+    ? `- 本次任务边界（allowedPaths）：${allowedPaths.map(p => `\`${p}\``).join(' / ')}（SillySpec 侧 assess/apply 校验，SillyHub 不物化）`
+    : '- 本次任务边界（allowedPaths）：未提供，按蓝图 tasks/task-XX.md 的 allowed_paths 为准（SillySpec 侧校验）'
+  const modelLine = modelHint
+    ? `- \`model\`：\`${modelHint}\`（来自 tasks.md [model:xxx]，映射到 SillyHub model）`
+    : '- `model`：未提供（contract.modelHint 缺），沿用 daemon 默认模型'
+  const profileLine = agentProfileHint
+    ? `- \`agent_profile_id\`：\`${agentProfileHint}\`（来自 contract.agentProfileHint）`
+    : '- `agent_profile_id`：未提供（contract.agentProfileHint 缺），沿用 daemon 默认 profile'
+
+  const modeLine = readOnly
+    ? '**只读模式（read_only=true）**：worker 只读 / 审查 / 写 review.json，不改源码（注：第一波 execute task 用写模式，acceptance 强制 tier=self，R-03）'
+    : '**写模式（read_only=false）**：worker 按蓝图实现源码（TDD），但**绝不 git commit**（见下方 worker_prompt 覆写）'
+
+  return `### 派发后端：SillyHub MCP — 路径 A 落地后启用
+
+本指令用 **SillyHub MCP tool** 派 worker 执行任务（路径 A 落地后由 strategy.js 注入；当前
+\`isPathASupported()\` 返回 false，strategy 不会调本指令，而是降级提示 + 回退 Local）。
+
+**你的角色是调度者 + 审查者，不要自己写代码。** 实际 MCP tool 调用由你（调度 agent）执行：
+创建 mission → 派 worker → 轮询终态 → kill 异常 lease → 回收 diff。
+
+### 一 Wave 一 mission（D-008）
+
+1. **Wave 开始先建 mission**：调 \`create_mission\` tool 为本 Wave 创建独立 mission
+   - 参数：\`objective\`（本 Wave 目标）/ \`change_id\`（SillySpec change id）/ \`budget_usd\`（per Wave 预算）
+   - 返回 \`mission_id\`，记下供本 Wave 内所有 task→worker 复用：${missionDisplay}
+2. **Wave 内 task → worker 并行 dispatch**：同 Wave 多 task 各调一次 \`dispatch_worker\`，共用本 Wave 的 mission_id（保 Wave 内并行）
+3. **Wave 间 mission 串行**：上一 Wave 全 worker 终态 + 回收完成后，下一 Wave 起新 mission（不把全 Wave 塞一个 mission，否则失串行）
+
+### dispatch_worker 参数（每个 task 调一次）
+
+调 \`dispatch_worker\` tool，参数（snake_case 对齐 SillyHub schema；对照 client.js \`dispatchWorker\` 签名）：
+- \`mission_id\`：${missionDisplay}
+- \`objective\`：${briefDisplay}
+- \`worktree_path\`：\`${worktreeDisplay}\`（路径A：worker cwd = SillySpec worktree，D-002）
+- \`branch\`：\`${branchDisplay}\`（路径A：worktree 当前分支）
+- \`read_only\`：\`${readOnly}\`
+${modelLine}
+${profileLine}
+- \`worker_prompt\`：**必须覆写**（见下方，覆盖 daemon 默认 render_worker_prompt 的 git commit 行为）
+
+${modeLine}
+${allowedLine}
+
+### worker_prompt 覆写（D-003@v2 第三处，UB-1 关键）
+
+dispatch_worker 的 \`worker_prompt\` 参数必须传以下覆写文本（路径A 第三处：daemon 默认
+\`render_worker_prompt\` 硬编码 \`git add -A && git commit\`，会污染 sillyspec/<change> 分支历史
++ 撞 D-004；用 worker_prompt 覆写让 caller 控制 commit 行为）：
+
+\`\`\`
+你是 SillySpec execute 的 worker，在指定 worktree 干活。铁律：
+1. 按 objective + 蓝图（tasks/task-XX.md / design.md）实现任务（TDD：先读后写 → 写测试 → 写实现）
+2. **绝不执行 git add / git commit / git push**：改动留在工作区（staged 或 unstaged 都行），
+   交 SillySpec 主体 git diff 回收（D-004）
+3. 不超出 allowedPaths，不碰其他 task 的文件
+4. 完成后输出简短自报（改了哪些文件 / 跑了哪些测试 / 是否存疑），不自报 review.json（SillySpec 自己写）
+5. 写测试时遵循下方「测试用例设计」规则：
+
+{{include: testcase-design}}
+\`\`\`
+
+### 终态轮询 + 超时 kill lease（UB-6）
+
+dispatch 后在当前 step 内主动轮询，不阻塞等待：
+
+1. **轮询 \`list_workers\`**：间隔默认 15s，可配 local.yaml \`dispatch.poll_interval_ms\`
+   - 入参 \`mission_id\`；关注每个 worker 的 status（pending → running → completed/failed）
+2. **per-worker 超时**：默认可配 local.yaml \`dispatch.worker_timeout_ms\`；超时 → 三步兜底：
+   - a. **标记**：调 \`report_progress\` tool（worker_id + 超时说明）记录该 worker 超时
+   - b. **kill lease 防双写**：调 \`report_progress\` tool（worker_id + \`kill: true\` + marker）终止 lease
+     （等价 client.js \`killLease(workerId)\` 路径；SillyHub 当前无专用 kill tool，路径A 落地后升级为专用 kill）
+   - c. **fallback Local 重派**：该 task 改用本机 Agent tool 重派（调 \`sillyspec dispatch hint\` 走 Local 模板）
+3. **worker 终态（completed / failed / killed）** → 进入下方回收约定
+
+${recycleRule}`
+}

package/.claude/worktrees/sillyspec-data-model-research/src/dispatch/probe.js

@@ -0,0 +1,246 @@
+/**
+ * SillyHub 能力探测（D-005 双后端 fallback 的关键判定）
+ *
+ * 定位（design.md §Phase4 / §接口定义）：probeSillyHub 是"能力探测"，决定 dispatch 用 SillyHub
+ * 还是 Local 后端。无 MCP 配置 / daemon 不可达 / worktree 越界 → 返回 unavailable → 调用方全程
+ * Local（零回归）。纯 JS 可测（task-08 mock client 验三分支）；不直接碰 lease，只感知 daemon 连通性。
+ *
+ * 铁律（design.md R-06 / task-01 constraints）：
+ * - 探测失败保守 fallback（返回 unavailable），**绝不抛异常阻断 execute**（client 契约异常时再兜 try/catch）。
+ * - TTL 可配（local.yaml dispatch.probe_ttl_ms），不硬编码。
+ * - 无 MCP 配置时同步快速路径返回，**不发网络**（零回归的关键）。
+ * - 负面结果 TTL 缓存（daemon 抖动期免反复探测，R-06）；正面结果不缓存（让 daemon 恢复/退化及时反映）。
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join, relative, isAbsolute, sep } from 'node:path';
+import jsYaml from 'js-yaml';
+import { SillyHubMcpClient } from '../sillyhub-mcp/client.js';
+import { readMcpConfig } from '../sillyhub-mcp/config.js';
+import { setPathAProbeResult } from './backends/sillyhub-mcp.js';
+
+/** 默认负面缓存 TTL（毫秒）。可被 local.yaml dispatch.probe_ttl_ms 或 ttlMs 参数覆盖。 */
+export const DEFAULT_PROBE_TTL_MS = 60_000;
+
+/**
+ * HUB-12a：probe 总超时。链路最坏 initialize(10s) + tools/call(10s) + tools/list(10s) 串行，
+ * 慢/挂 daemon 下此前要 ~30-50s 才降级，阻塞 execute。默认 25s 截断（可达 daemon 毫秒级
+ * 响应，不受影响）；opts.totalTimeoutMs 可覆盖。超时按 daemon-unreachable 语义进负面缓存。
+ */
+const DEFAULT_PROBE_TOTAL_TIMEOUT_MS = 25_000;
+
+// 负面缓存：configFingerprint → { result: {available,reason}, expiresAt }
+// 仅缓存网络派生的 unavailable 结果（daemon-unreachable），避免 daemon 抖动期反复探测（R-06）。
+// no-config 由 env 同步派生（不入缓存）；worktree-outside-root 依赖路径入参（每次重算，不入缓存）。
+const negativeCache = new Map();
+
+/**
+ * 读 local.yaml 的 dispatch.probe_ttl_ms（best-effort，绝不抛）。
+ * 文件不存在 / 解析失败 / 无 dispatch 段 / 非正数 → 返回 undefined（调用方降级默认值）。
+ * 读法参考 src/sync.js readLocalYaml 的 best-effort 风格，但用 js-yaml 解析嵌套段（更稳健）。
+ */
+function readProbeTtlFromLocalYaml(cwd) {
+  try {
+    const p = join(cwd, '.sillyspec', 'local.yaml');
+    if (!existsSync(p)) return undefined;
+    const doc = jsYaml.load(readFileSync(p, 'utf8'));
+    if (!doc || typeof doc !== 'object') return undefined;
+    const dispatch = doc.dispatch;
+    if (!dispatch || typeof dispatch !== 'object') return undefined;
+    const v = dispatch.probe_ttl_ms;
+    return typeof v === 'number' && v > 0 ? v : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * 解析生效 TTL。优先级：显式 ttlMs 参数 > local.yaml dispatch.probe_ttl_ms > 默认常量。
+ */
+function resolveTtl(ttlMs, cwd) {
+  if (typeof ttlMs === 'number' && ttlMs > 0) return ttlMs;
+  const fromYaml = readProbeTtlFromLocalYaml(cwd);
+  if (typeof fromYaml === 'number') return fromYaml;
+  return DEFAULT_PROBE_TTL_MS;
+}
+
+/**
+ * 配置指纹（负面缓存 key）。用 local.yaml mcp 段或 env 的 URL 标识 daemon 身份；
+ * token 不入 key（避免敏感信息驻留缓存，保密语义不变）。token 轮换后最迟 TTL 内自动失效重探。
+ */
+function configFingerprint(cwd) {
+  return readMcpConfig(cwd)?.url || '';
+}
+
+/**
+ * 判断 worktreePath 是否在 rootPath 目录内（含相等，R-08）。
+ * 段级 '..' 精确匹配：兼容跨盘符（Windows 不同盘 → rel 绝对路径 → 越界）与字面 '..' 前缀目录名
+ * （如 '..foo' 目录不会被误判越界，区别于粗放的 startsWith('..') 写法）。
+ */
+function isWithinRoot(rootPath, worktreePath) {
+  const rel = relative(rootPath, worktreePath);
+  if (rel === '') return true; // worktree === root，边界视为在内
+  if (isAbsolute(rel)) return false; // 跨盘符（Windows）→ rel 绝对路径 → 越界
+  const segments = rel.split(sep);
+  return !segments.some((s) => s === '..');
+}
+
+/**
+ * 从 tools/list 返回的 tools 数组探测路径A 是否支持（task-11，D-005）。
+ *
+ * 命中条件（全中才 true，任一缺失 → false，保守 R-04）：
+ * - 找到 `name === 'dispatch_worker'` 的 tool
+ * - 其 `inputSchema.properties` 同时声明 `worktree_path` 与 `worker_prompt`（caller-worktree +
+ *   prompt 覆写两处 daemon 侧落地标志，design §7.3）
+ *
+ * 纯函数（不调网络），独立可测（task-11 三分支：含字段→true / 缺字段→false / 异常输入→false）。
+ * @param {Array<{name:string, inputSchema?:object}>|null} tools - client.listTools() 返回的 tools 数组
+ * @returns {boolean} 路径A schema 全命中 → true；否则 false
+ */
+export function detectPathAFromTools(tools) {
+  if (!Array.isArray(tools)) return false;
+  const dw = tools.find((t) => t && t.name === 'dispatch_worker');
+  if (!dw) return false;
+  const props = dw.inputSchema && dw.inputSchema.properties;
+  if (!props || typeof props !== 'object') return false;
+  return Boolean(props.worktree_path) && Boolean(props.worker_prompt);
+}
+
+/**
+ * 能力探测：决定 dispatch 是否可用 SillyHub 后端。
+ *
+ * 决策顺序（design.md §Phase4 / task-01 implementation）：
+ *   1. env 快速路径（无网络）：缺 URL/TOKEN → no-config
+ *   2. 负面缓存命中且未过 TTL → 直接返回缓存（无网络，R-06）
+ *   3. 连通性探测 client.probeDaemon()：false → 缓存 daemon-unreachable 并返回
+ *   3.5 路径A schema 预热 + root_path 获取（HUB-12a 合并）：daemon 可达后**一次**
+ *       tools/list 同时喂 detectPathAFromTools 预热与 root_path 越界校验（此前
+ *       listTools + getRootPath 各发一次同 method 请求）
+ *   4. worktreePath 越界校验（R-08 best-effort）
+ *   5. 全通过 → available=true（不缓存正面结果）
+ *
+ * 整链路受 totalTimeoutMs 总超时保护（HUB-12a）：超时按 daemon-unreachable 进负面缓存。
+ *
+ * @param {object} [opts]
+ * @param {object} [opts.client]       - SillyHubMcpClient 实例；缺省 new SillyHubMcpClient()（经 readMcpConfig 读 local.yaml mcp 段 + env）
+ * @param {string} [opts.worktreePath] - SillySpec worktree 绝对路径（root_path 校验用）
+ * @param {string} [opts.rootPath]     - daemon ws.root_path；未传（undefined）时 best-effort 从 daemon
+ *                                       拿（task-12 #5），拿不到则跳过越界校验（不判 unavailable）
+ * @param {number} [opts.ttlMs]        - 负面缓存 TTL 覆盖（优先于 local.yaml）
+ * @param {number} [opts.totalTimeoutMs] - 总超时覆盖（默认 25s，HUB-12a）
+ * @returns {Promise<{ available: boolean, reason?: string }>}
+ */
+export async function probeSillyHub({ client, worktreePath, rootPath, ttlMs, totalTimeoutMs } = {}) {
+  // 1. 同步快速路径：无 local.yaml mcp 段且 env 缺凭据即 unavailable（不发网络，零回归关键）。
+  //    readMcpConfig 纯 fs + env 读（best-effort 不抛不发网络），返回 null = 两源都缺 → no-config。
+  if (!readMcpConfig(process.cwd())) {
+    return { available: false, reason: 'no-config' };
+  }
+
+  // 2. 负面缓存命中（未过 TTL）→ 直接返回，不发网络（R-06 抖动期免反复探测）
+  const fp = configFingerprint(process.cwd());
+  const cached = negativeCache.get(fp);
+  if (cached && cached.expiresAt > Date.now()) {
+    return cached.result;
+  }
+
+  const cli = client || new SillyHubMcpClient({ cwd: process.cwd() });
+  const cacheNegative = (reason) => {
+    const result = { available: false, reason };
+    const ttl = resolveTtl(ttlMs, process.cwd());
+    negativeCache.set(fp, { result, expiresAt: Date.now() + ttl });
+    return result;
+  };
+
+  // HUB-12a：总超时兜底——慢/挂 daemon 不拖 execute。超时后后台请求由 client 自身
+  // 10s 请求超时自然终结（有界），probe 侧按不可达降级
+  const budgetMs = typeof totalTimeoutMs === 'number' && totalTimeoutMs > 0
+    ? totalTimeoutMs
+    : DEFAULT_PROBE_TOTAL_TIMEOUT_MS;
+
+  const probeBody = (async () => {
+    // 3. 连通性探测：client.probeDaemon 自身 best-effort 不抛；再兜一层 try/catch，
+    //    即便 client 契约异常抛出也保守判 unavailable（铁律：绝不抛穿 execute）
+    let reachable;
+    try {
+      reachable = await cli.probeDaemon();
+    } catch (err) {
+      const msg = err && err.message ? err.message : String(err);
+      console.warn(`[dispatch/probe] probeDaemon 抛异常（保守判 unavailable）: ${msg}`);
+      reachable = false;
+    }
+    if (!reachable) return cacheNegative('daemon-unreachable');
+
+    // 3.5+4 合并（HUB-12a）：一次 tools/list 同时拿 tools 数组（路径A schema 预热）与
+    //     root_path（越界校验）。旧 client 无 listToolsWithMeta 时回退 listTools +
+    //     getRootPath 各一次（兼容旧 mock）
+    let tools = null;
+    let toolsListRoot = undefined;
+    try {
+      if (typeof cli.listToolsWithMeta === 'function') {
+        const raw = await cli.listToolsWithMeta();
+        if (raw) {
+          if (Array.isArray(raw)) tools = raw;
+          else if (Array.isArray(raw.tools)) tools = raw.tools;
+          if (raw && typeof raw === 'object' && typeof raw.root_path === 'string' && raw.root_path) {
+            toolsListRoot = raw.root_path;
+          }
+        }
+      } else if (typeof cli.listTools === 'function') {
+        tools = await cli.listTools();
+      }
+    } catch (err) {
+      const msg = err && err.message ? err.message : String(err);
+      console.warn(`[dispatch/probe] tools/list 异常（路径A 保守判 false）: ${msg}`);
+      tools = null;
+    }
+    try {
+      setPathAProbeResult(detectPathAFromTools(tools));
+    } catch (err) {
+      const msg = err && err.message ? err.message : String(err);
+      console.warn(`[dispatch/probe] 路径A schema 探测异常（保守判 false）: ${msg}`);
+      setPathAProbeResult(false);
+    }
+
+    if (worktreePath) {
+      let effectiveRoot = rootPath;
+      if (effectiveRoot === undefined) {
+        effectiveRoot = toolsListRoot !== undefined ? toolsListRoot : null;
+        if (effectiveRoot === null && typeof cli.getRootPath === 'function') {
+          try {
+            effectiveRoot = await cli.getRootPath();
+          } catch (err) {
+            const msg = err && err.message ? err.message : String(err);
+            console.warn(`[dispatch/probe] rootPath best-effort 拿取异常（跳过越界校验）: ${msg}`);
+            effectiveRoot = null;
+          }
+        }
+      }
+      if (effectiveRoot && !isWithinRoot(effectiveRoot, worktreePath)) {
+        return { available: false, reason: 'worktree-outside-root' };
+      }
+    }
+
+    // 5. 全通过：不缓存正面结果，下次重新探测（让 daemon 恢复/退化及时反映）
+    return { available: true };
+  })();
+
+  let timeoutId = null;
+  let raced;
+  try {
+    raced = await Promise.race([
+      probeBody,
+      new Promise((resolve) => { timeoutId = setTimeout(() => resolve(null), budgetMs) }),
+    ]);
+  } finally {
+    if (timeoutId) clearTimeout(timeoutId);
+  }
+  return raced || cacheNegative('probe-timeout');
+}
+
+/**
+ * 清空负面缓存（测试用；生产中 TTL 自然过期即可）。
+ */
+export function clearProbeCache() {
+  negativeCache.clear();
+}

package/.claude/worktrees/sillyspec-data-model-research/src/dispatch/strategy.js

@@ -0,0 +1,121 @@
+/**
+ * 派发策略生成器（task-dispatcher 抽象层）— task-02
+ *
+ * 定位（D-007 + UB-2）：dispatcher **不是 JS 执行体**。本文件 = **派发策略生成器**：
+ * 依据 probe 结果选择后端（sillyhub / local），并把对应后端的派发指令模板组合成可注入
+ * execute prompt 的「派发指令文本」，告诉 agent 用哪个后端、调什么 tool、传什么参数、
+ * 怎么轮询与回收。**实际 tool 调用（本机 Agent tool / SillyHub MCP tool）由 agent 执行，
+ * 本模块不 import client、不调任何 tool。**
+ *
+ * backend 选择（acceptance #1/#2，**由 probe.available 驱动，不由 isPathASupported 驱动**）：
+ * - `probe.available === true` → backend = `'sillyhub'`（指令走 SillyHub MCP 模板）
+ * - 否则（false / undefined / probe 为 null）→ backend = `'local'`（与现状行为一致，零回归）
+ *
+ * 路径 A 降级（D-003@v2）：`isPathASupported()` **不改 backend 标签**（仍由 probe 驱动），
+ * 而是影响 SillyHub 指令的**文本内容**：path A 未支持时（当前 stub 恒 false），在 SillyHub
+ * 主指令后附加降级提示段（PATH_A_DOWNGRADE_REASON + per-worker 回退 Local 说明），并始终追加
+ * Local 兜底指令全文，让 agent 据此 per-worker 回退本机 Agent tool，不硬试 MCP 路径。
+ *
+ * 铁律（R-09 / UB-7 / D-004）：
+ * - 纯函数：除 import 的模板生成器外无副作用，易测（task-08 mock probe 验两分支）。
+ * - 指令必须明确**单后端**（backend 字段 + 文本只描述选定后端 + 兜底），避免 agent 误执行。
+ * - allowedPaths 不物化到 SillyHub（仅写入指令供 SillySpec 侧 assess/apply 校验）——
+ *   allowedPaths 由各后端模板在指令文本里声明，本策略不额外处理。
+ * - 兼容 Win/Linux/macOS：无路径拼接 / 无平台分支，纯模板组合。
+ */
+
+import { renderLocalInstruction } from './backends/local-agent.js';
+import {
+  isPathASupported,
+  renderSillyHubInstruction,
+  PATH_A_DOWNGRADE_REASON,
+} from './backends/sillyhub-mcp.js';
+
+/**
+ * @typedef {import('./backends/local-agent.js').DispatchContract} DispatchContract
+ * @see design.md「接口定义」DispatchContract：brief / worktreePath / branch / allowedPaths /
+ *      readOnly / modelHint / agentProfileHint / runId / missionId
+ */
+
+/**
+ * @typedef {object} DispatchInstruction
+ * @property {string} instruction - 注入 execute prompt 的派发指令文本（含选定后端 + 兜底）
+ * @property {'sillyhub' | 'local'} backend - 选定后端标签（由 probe.available 驱动）
+ */
+
+/**
+ * 生成派发指令（注入 execute prompt，agent 据此执行派发）。
+ *
+ * 决策（D-007 + task-02 acceptance）：
+ * 1. 解析 probe：`available = !!(probe && probe.available)`；probe 为 null/undefined/缺
+ *    available 均视为 unavailable → local（零回归）。
+ * 2. **backend = available ? 'sillyhub' : 'local'**（acceptance #1/#2，由 probe 驱动）。
+ * 3. contract 兜底为 `{}`（renderLocalInstruction / renderSillyHubInstruction 内部已对
+ *    缺字段回退醒目占位符，不会崩）。
+ * 4. backend==='sillyhub'：
+ *    - 主指令 = renderSillyHubInstruction(contract)（含轮询间隔 / kill lease 防双写 / 回收约定）
+ *    - 若 !isPathASupported()：追加降级提示段（PATH_A_DOWNGRADE_REASON + per-worker 回退 Local）
+ *    - **始终追加 Local 兜底指令全文**（implementation #4，保证可回退）
+ * 5. backend==='local'：主指令 = renderLocalInstruction(contract)（与现状行为一致）
+ *
+ * 注：renderLocalInstruction / renderSillyHubInstruction 内部已自行替换
+ * LOCAL_RECYCLE_RULE / SILLYHUB_RECYCLE_RULE 的 `<runId>` 占位符，本策略不重复替换；
+ * 仅当额外引用含占位符的常量时才需替换，当前实现未额外引用，故无需处理。
+ *
+ * @param {DispatchContract} [contract] - 派发契约（缺省视为空对象，模板内部回退占位符）
+ * @param {{ available?: boolean, reason?: string } | null} [probe] - probeSillyHub() 的结果
+ * @returns {DispatchInstruction} `{ instruction, backend }`
+ */
+export function renderDispatchInstruction(contract, probe) {
+  // 1. 解析 probe：null/undefined/缺 available 均视为 unavailable → local（零回归）
+  const available = !!(probe && probe.available);
+
+  // 2. backend 由 probe.available 驱动（acceptance #1/#2，不由 isPathASupported 驱动）
+  const backend = available ? 'sillyhub' : 'local';
+
+  // 3. contract 兜底（模板内部对缺字段已有醒目占位符处理，不会崩）
+  const c = contract || {};
+
+  if (backend === 'sillyhub') {
+    // SillyHub 主指令：含一 Wave 一 mission / dispatch_worker 参数 / 终态轮询间隔 / kill lease
+    // 防双写 / 回收约定（acceptance #3 轮询间隔与 kill lease 来自此模板）
+    const sillyHubInstruction = renderSillyHubInstruction(c);
+
+    // path A 未支持时的降级提示段（不改 backend 标签，仅追加文本，引导 agent per-worker 回退 Local）
+    const pathADowngrade = isPathASupported()
+      ? ''
+      : [
+          '',
+          '---',
+          '',
+          '### 路径 A 降级提示（per-worker 回退 Local）',
+          '',
+          `${PATH_A_DOWNGRADE_REASON}`,
+          '',
+          '本次派发 backend 标记仍为 `sillyhub`（由 probe 可达驱动，acceptance 要求不改标签），',
+          '但实际执行将回退 Local：agent 调 dispatch_worker 传 worktree_path 会被拒/忽略，',
+          '请 per-worker 回退本机 Agent tool（见下方 Local 兜底），不要硬试 MCP 路径。',
+          '',
+        ].join('\n');
+
+    // 始终追加 Local 兜底指令全文（implementation #4「始终附加 Local 兜底」）：
+    // 保证 SillyHub 路径任一步异常（dispatch 被拒 / 轮询超时 kill 后 fallback / path A 未落地）
+    // 时 agent 可立即改用本机 Agent tool 重派，零回归。
+    const localFallback = [
+      '',
+      '---',
+      '',
+      '### 兜底：Local（本机 Agent tool）— SillyHub 路径异常时回退',
+      '',
+      '当上方 SillyHub MCP 路径任一步失败，立即改用本机 Agent tool 重派该 task。',
+      'Local 后端派发指令全文如下（workdir 强制 = contract.worktreePath）：',
+      '',
+      renderLocalInstruction(c),
+    ].join('\n');
+
+    return { instruction: sillyHubInstruction + pathADowngrade + localFallback, backend };
+  }
+
+  // backend === 'local'：与现状行为一致（acceptance #2），probe 本就 unavailable，无需额外降级提示
+  return { instruction: renderLocalInstruction(c), backend };
+}