sillyspec 3.25.9 → 3.25.11

package/src/run/stage.js

@@ -19,11 +19,12 @@
 import { join, dirname } from 'node:path'
 import { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs'
 import { writeAtomicSync } from '../fs-atomic.js'
-import { resolveSpecDir, resolveChangeDir, triggerSync, safeGit, parsePorcelainPath, formatWaitOptions, checkApproval, getStageSteps } from './shared.js'
+import { resolveSpecDir, resolveChangeDir, resolveRuntimeRoot, resolveQuickSessionsDir, triggerSync, safeGit, parsePorcelainPath, formatWaitOptions, checkApproval, getStageSteps } from './shared.js'
 import { computeScanProfile, applyScanProfileSteps, executeScanPreflight, executeScanPostcheck } from './scan-profile.js'
 import { outputStep } from './prompt.js'
 import { allocateQuicklogEntry, deriveTitleFromLinkedChange } from '../quicklog.js'
 import { checkTransition } from '../stage-contract.js'
+import { completeStageGates } from './gates.js'
 
 export async function runStage(pm, progress, stageName, cwd, changeName, skipApproval = false, platformOpts = {}, quickOpts = {}) {
   const specBase = platformOpts.specRoot || join(cwd, '.sillyspec')
@@ -89,7 +90,7 @@ export async function runStage(pm, progress, stageName, cwd, changeName, skipApp
   if (stageName === 'execute') {
     const { generateExecuteRunId } = await import('../task-review.js')
     const execSpecBase = platformOpts?.specRoot || join(cwd, '.sillyspec')
-    const runtimeRoot = platformOpts?.runtimeRoot || join(execSpecBase, '.runtime')
+    const runtimeRoot = resolveRuntimeRoot(platformOpts, execSpecBase)
     const runIdFile = join(runtimeRoot, `current-execute-run-id-${changeName}`)
     mkdirSync(runtimeRoot, { recursive: true })
     // 优先读取已有的变更专属标记文件
@@ -107,7 +108,7 @@ export async function runStage(pm, progress, stageName, cwd, changeName, skipApp
   // 自动探测 currentChange
   if (autoDetectChange(progress, cwd)) {
     progress.lastActive = new Date().toLocaleString('zh-CN', { hour12: false })
-    await pm._write(cwd, progress, changeName)
+    pm._write(cwd, progress, changeName)
     triggerSync(cwd, changeName, platformOpts)
   }
 
@@ -121,7 +122,7 @@ export async function runStage(pm, progress, stageName, cwd, changeName, skipApp
   if (progress.currentStage !== stageName) {
     progress.currentStage = stageName
     progress.lastActive = new Date().toLocaleString('zh-CN',{hour12:false})
-    await pm._write(cwd, progress, changeName)
+    pm._write(cwd, progress, changeName)
     triggerSync(cwd, changeName, platformOpts)
   }
 
@@ -143,7 +144,7 @@ export async function runStage(pm, progress, stageName, cwd, changeName, skipApp
   // stale 步骤视为可执行（等同于 pending）
   if (currentIdx !== -1 && steps[currentIdx].status === 'stale') {
     steps[currentIdx].status = 'pending'
-    await pm._write(cwd, progress, changeName)
+    pm._write(cwd, progress, changeName)
     triggerSync(cwd, changeName, platformOpts)
   }
 
@@ -159,7 +160,7 @@ export async function runStage(pm, progress, stageName, cwd, changeName, skipApp
     }
     // 保存 profile 供后续 postcheck 使用
     stageData.scanProfile = scanProfile
-    await pm._write(cwd, progress, changeName)
+    pm._write(cwd, progress, changeName)
   } else if (stageName === 'scan' && stageData.scanProfile) {
     scanProfile = stageData.scanProfile
   }
@@ -194,8 +195,8 @@ export async function runStage(pm, progress, stageName, cwd, changeName, skipApp
     // 旧逻辑无条件清空 steps 为 pending 会丢掉已完成的进度且不可恢复。改为走正式
     // completeStage：产物齐则补盖完成戳，不齐则给出 actionable 提示，永不静默清空步骤。
     console.log(`\nℹ️  ${stageName} 所有步骤已完成，但阶段未标记完成（上次可能中断）。尝试补盖完成戳…`)
-    await pm.completeStage(cwd, stageName, changeName)
-    const after = await pm.read(cwd, changeName)
+    pm.completeStage(cwd, stageName, changeName)
+    const after = pm.read(cwd, changeName)
     if (after?.stages?.[stageName]?.status === 'completed') {
       console.log(`   ✅ 已补盖完成戳。下一步: sillyspec run <下一阶段>，或 sillyspec run ${stageName} --status 查看。`)
       process.exit(0)
@@ -212,7 +213,9 @@ export async function runStage(pm, progress, stageName, cwd, changeName, skipApp
   // （D-003@v1：顶层 quickGuard 不跨进程持久化；agent 在 step 间用 `run quick` 取下一步
   // prompt 时每个新进程都进此块，按文件判幂等才不会重复分配 ql-ID / 重复写条目）。
   if (stageName === 'quick') {
-    const sessionGuardDir = join(specBase, '.runtime', 'quick-sessions', changeName)
+    // quick-sessions 目录经 resolveQuickSessionsDir 单一解析（multi-agent-review Q4）：
+    // 平台模式 runtimeRoot 与 specBase/.runtime 不同时，写/读须对齐，否则 guard 写一处、收尾读另一处。
+    const sessionGuardDir = join(resolveQuickSessionsDir(platformOpts, specBase), changeName)
     const guardFile = join(sessionGuardDir, 'guard.json')
     let existingGuard = null
     try {
@@ -222,9 +225,19 @@ export async function runStage(pm, progress, stageName, cwd, changeName, skipApp
       // 跨进程重入：复用已分配的 ql-ID，跳过 baseline 重捕与分配（幂等）
       progress.quickGuard = existingGuard
     } else {
+      // baseline 采集用 safeGit（带 -c safe.directory，避免 linked worktree/容器异 uid/Windows 挂载点
+      // 下裸 `git status` 抛错）。safeGit 已消除 safe.directory 类失败；若仍失败（真非 git 目录等），
+      // 不硬阻断 quick 启动（平台模式/非 git 目录仍需渲染 step prompt），但 fail-visible：大声 warn +
+      // baseline 置空。--done 时 auditQuickCompletion 的 safeGit 同样失败 → blocked，故不存在「静默
+      // 完成」路径（multi-agent-review Q3）。
+      const statusResult = safeGit(cwd, ['status', '--porcelain'], { trim: false })
+      if (statusResult.error) {
+        console.warn(`⚠️ quick baseline 采集失败（git status）: ${statusResult.error}`)
+        console.warn(`   baseline 置空；--done 审计将因 git 不可用而阻断（无静默完成路径）。`)
+        console.warn(`   排查：仓库 safe.directory 配置 / 非 git 目录。`)
+      }
       try {
-        const { execSync } = await import('child_process')
-        const gitStatus = execSync('git status --porcelain', { cwd, encoding: 'utf8', timeout: 10000 })
+        const gitStatus = statusResult.value || ''
         // 记录全部预存脏文件（含 untracked + .sillyspec/ 路径）。quick 会话期间自身写入的元数据
         // （quicklog/.runtime/modules/_module-map 等）由 auditQuickCompletion 的 isQuickMetadata 精确豁免，
         // 不需要这里粗放过滤 .sillyspec/——旧过滤致预存 untracked .sillyspec/changes/ 不进 baseline，
@@ -275,7 +288,7 @@ export async function runStage(pm, progress, stageName, cwd, changeName, skipApp
         if (allowNew) parts.push('允许新增文件')
         console.log(`🛡️ quick 变更边界已记录: ${parts.join(', ')}`)
         console.log(`📝 QUICKLOG 条目已创建: ${qlId}`)
-        await pm._write(cwd, progress, changeName)
+        pm._write(cwd, progress, changeName)
       } catch (e) {
         console.warn(`⚠️ baseline 记录失败: ${e.message}`)
       }
@@ -328,7 +341,7 @@ export async function runStage(pm, progress, stageName, cwd, changeName, skipApp
       }
       stageData.steps[currentIdx].status = 'completed'
       stageData.steps[currentIdx].completedAt = new Date().toLocaleString('zh-CN', { hour12: false })
-      await pm._write(cwd, progress, changeName)
+      pm._write(cwd, progress, changeName)
       // 自动前进到下一步
       const nextIdx = stageData.steps.findIndex(s => s.status === 'pending' || s.status === 'in-progress')
       if (nextIdx !== -1 && defSteps[nextIdx]) {
@@ -338,7 +351,13 @@ export async function runStage(pm, progress, stageName, cwd, changeName, skipApp
         // 所有步骤完成
         stageData.status = 'completed'
         stageData.completedAt = new Date().toLocaleString('zh-CN', { hour12: false })
-        await pm._write(cwd, progress, changeName)
+        // persist _write 移到 completeStageGates 成功之后（task-02 / review-2026-08-09 #2）：gate 异常/失败 → rollback 回 in-progress 落盘，此处未到 _write，DB 不留假 completed。
+        // 阶段完成收尾共享管线（noAI 末步核心修复 S1：plan postcheck independent-tier review verdict=fail /
+        // 平台 scan manifest 此前被绕过）。gate 失败已 rollback 为 in-progress，early-return（不 fall through 到末尾 return）。
+        const _stageGatesResult = await completeStageGates({ stageName, cwd, changeName, platformOpts, specBase, progress, pm, stageData, steps, currentIdx, outputText: null })
+        if (_stageGatesResult) return _stageGatesResult
+        // gate 全过：persist completed（task-02 移后；此处无 triggerSync，与同文件 noAI 末步语义一致）。
+        pm._write(cwd, progress, changeName)
         console.log(`\n✅ ${stageName} 阶段全部完成。`)
       }
       return
@@ -390,20 +409,20 @@ async function executePlanPostcheck(cwd, platformOpts, progress) {
 
 /**
  * execute 入口 deps 自检（D-002，change 2026-06-28-worktree-deps-provision）。
- * 已存在 worktree（create short-circuit 不供给）时，校验 depsStatus 缺失 / node_modules
- * 丢失(missing) / lockfile 变化(stale) → 触发 provisionDeps 重供给并写回 meta。
+ * 已存在 worktree（create short-circuit 不供给）时，校验 deps 状态缺失/漂移 → 触发 provisionDeps 重供给并写回 meta。
+ *
+ * 判定改调共享 checkDepsFreshness（H1，change 2026-08-05-tooling-feedback-fixes task-04）：
+ *   - status ∈ {missing, stale, main-drift, failed} → 触发重供给（main-drift 为新增主仓 lockfile 漂移触发）
+ *   - status === fresh → 跳过
+ *   行为与原内联 noStatus/missing/stale 三判定等价（provisionDeps 调用 / meta 写回不变），新增 main-drift 触发。
  */
 async function ensureDepsFreshness(cwd, changeName, specBase, worktreeMeta) {
   if (!worktreeMeta || !worktreeMeta.worktreePath) return
-  const { provisionDeps, lockfileHash } = await import('../worktree-deps.js')
+  const { provisionDeps, checkDepsFreshness } = await import('../worktree-deps.js')
   const wtPath = worktreeMeta.worktreePath
-  const nodeModulesExists = existsSync(join(wtPath, 'node_modules'))
-  const currentHash = lockfileHash(wtPath)
-  const noStatus = !worktreeMeta.depsStatus
-  const missing = ['linked', 'installed'].includes(worktreeMeta.depsStatus) && !nodeModulesExists
-  const stale = !!(worktreeMeta.depsLockHash && currentHash && currentHash !== worktreeMeta.depsLockHash)
-  if (!noStatus && !missing && !stale) return
-  const reason = noStatus ? 'depsStatus 缺失' : (missing ? 'node_modules 丢失' : 'lockfile 变化')
+  const fresh = checkDepsFreshness(worktreeMeta, wtPath, cwd)
+  if (fresh.status === 'fresh') return
+  const reason = fresh.detail || fresh.status
   console.log(`🔄 worktree deps 自检：${reason}（depsStatus=${worktreeMeta.depsStatus || 'unknown'}），重新供给...`)
   let deps = {}
   try {

package/src/scan-postcheck.js

@@ -8,6 +8,7 @@
 import { existsSync, readdirSync, readFileSync, mkdirSync, writeFileSync } from 'fs'
 import { join, basename } from 'path'
 import { SCAN_STATUS, CHECK_SEVERITY, SCAN_REQUIRED_DOCS, SCAN_REQUIRED_DOCS_QUICK } from './constants.js'
+import { validateScriptCommands } from './stages/cmd-existence.js'
 
 const REQUIRED_SCAN_DOCS = SCAN_REQUIRED_DOCS
 
@@ -119,40 +120,17 @@ export function runScanPostCheck({ cwd, specDir, outputText = '', scanMeta = {},
   const localYamlPath = join(specDir, 'local.yaml')
   if (existsSync(localYamlPath)) {
     const yamlContent = readFileSync(localYamlPath, 'utf8')
-    const packageJsonPath = join(cwd, 'package.json')
-    const invalidCommands = []
-
-    // 简单提取 local.yaml 中的 commands
-    // 注意（X-3, change 2026-06-28-worktree-deps-provision）：仅校验 build/test/lint 这类
-    // `npm run <script>` 形式命令在 package.json scripts 中存在。install/typecheck 是直接
-    // 包管理器调用（pnpm install / npm ci / npx tsc），不是 npm script，不在此校验范围——
-    // 下方的 /npm run (\S+)/g 正则天然不会匹配它们，无需也不应对其做 scripts 校验。
-    const commandMatch = yamlContent.match(/build:\s*"([^"]+)"/) ||
-                        yamlContent.match(/test:\s*"([^"]+)"/) ||
-                        yamlContent.match(/lint:\s*"([^"]+)"/)
-
-    if (commandMatch) {
-      // 提取所有 npm run <script> 形式的命令
-      const npmRunCommands = yamlContent.match(/npm run (\S+)/g) || []
-      if (npmRunCommands.length > 0 && existsSync(packageJsonPath)) {
-        try {
-          const pkg = JSON.parse(readFileSync(packageJsonPath, 'utf8'))
-          const scripts = pkg.scripts || {}
-          for (const cmd of npmRunCommands) {
-            const scriptName = cmd.replace('npm run ', '')
-            if (!scripts[scriptName]) {
-              invalidCommands.push(`${cmd} (package.json 无 ${scriptName} script)`)
-            }
-          }
-        } catch {}
-      }
-    }
-
-    if (invalidCommands.length > 0) {
+    // 改调共享 validateScriptCommands（H2，去重 plan/scan 两处命令校验）。
+    // 严重度维持 WARNING（design D-04：scan 阶段保守，local.yaml 命令误报不阻断 init）；
+    // 不传 modules → 仅查根 package.json，与历史行为一致（monorepo 子包感知由 plan-postcheck 启用）。
+    // 仅校验 `npm|pnpm|yarn run <script>` 这类可静态对账的命令；install/typecheck/npx 等直接
+    // 包管理器调用不在范围（沿用 cmd-existence.js:126-129 注释立场，正则天然不匹配它们）。
+    const { invalid } = validateScriptCommands(yamlContent, { projectRoot: cwd })
+    if (invalid.length > 0) {
       checks.push({
         name: 'local_config_invalid',
         severity: CHECK_SEVERITY.WARNING,
-        detail: `local.yaml 引用不存在的命令: ${invalidCommands.join('; ')}`
+        detail: `local.yaml 引用不存在的命令: ${invalid.map(i => `${i.cmd} (${i.reason})`).join('; ')}`
       })
     }
   }

package/src/sillyhub-mcp/client.js

@@ -0,0 +1,389 @@
+/**
+ * SillyHub MCP 客户端 — streamable HTTP 连接（协议 2025-11-25）
+ *
+ * 设计参考 src/sync.js 的 best-effort 风格：
+ * - 网络失败 / 非 2xx / 异常一律 console.warn 不抛错，绝不抛穿到 execute（约束：HTTP 错误保守返回 unavailable/空/false）
+ * - 未配置（缺 SILLYHUB_MCP_URL 或 SILLYHUB_MCP_TOKEN）→ 所有方法降级，不发网络
+ *
+ * 配置来源：环境变量 SILLYHUB_MCP_URL / SILLYHUB_MCP_TOKEN；
+ *           构造函数可传 { url, token, timeoutMs } 覆盖，缺省读 env。
+ *
+ * 端点：POST ${url}/mcp/（尾斜杠必需，MCP streamable HTTP 协议要求），Bearer token 鉴权。
+ * 请求体：JSON-RPC 2.0（tools/call 调 tool；tools/list 列 tool schema，task-11 路径A 探测用）。
+ * 响应：application/json（直接 JSON-RPC）或 text/event-stream（SSE，取 data: 行拼装后 JSON.parse）。
+ * tool 返回值惯例：从 result.content[0].text 再 JSON.parse 得到（tools/list 例外：result 直接是 {tools:[...]}）。
+ *
+ * 铁律：
+ * - converge_mission 不封装不调用（D-004 SillySpec 自己 apply）。
+ * - worktree_path 仅作 dispatch_worker 入参传递，本文件不碰 DB（不持久化为新列）。
+ * - 仅用 Node 原生 fetch（engine>=18），不引入新依赖。
+ */
+
+const DEFAULT_TIMEOUT_MS = 10_000;
+// MCP streamable HTTP 协议版本（task 指定 2025-11-25）
+const MCP_PROTOCOL_VERSION = '2025-11-25';
+
+export class SillyHubMcpClient {
+  /**
+   * @param {object} [opts]
+   * @param {string} [opts.url]       - 覆盖 SILLYHUB_MCP_URL；显式传空串视为未配置
+   * @param {string} [opts.token]     - 覆盖 SILLYHUB_MCP_TOKEN
+   * @param {number} [opts.timeoutMs] - 请求超时毫秒，默认 10000
+   */
+  constructor({ url, token, timeoutMs } = {}) {
+    const u = url !== undefined ? url : process.env.SILLYHUB_MCP_URL;
+    const t = token !== undefined ? token : process.env.SILLYHUB_MCP_TOKEN;
+    // 去掉 url 尾部斜杠，便于后续稳定拼 /mcp/（跨平台：URL 一律用正斜杠，不用 path.join）
+    this._url = typeof u === 'string' ? u.replace(/\/+$/, '') : '';
+    this._token = typeof t === 'string' ? t : '';
+    this._timeoutMs = typeof timeoutMs === 'number' && timeoutMs > 0
+      ? timeoutMs
+      : DEFAULT_TIMEOUT_MS;
+    // 缺 url 或 token → 视为未配置，所有方法降级不发网络
+    this._configured = Boolean(this._url && this._token);
+    // 端点必须带尾斜杠
+    this._endpoint = this._url ? `${this._url}/mcp/` : '';
+    this._rpcId = 0;
+  }
+
+  // ── 内部辅助 ──
+
+  /**
+   * 调用 MCP tool（JSON-RPC tools/call）。best-effort：任何失败返回 null 不抛。
+   *
+   * task-11 抽出共享骨架：本方法现为薄封装 `_sendRpc('tools/call', {name,arguments})`，
+   * warn 文案经 label=toolName 与改前逐字一致（零回归现有调用方）。
+   * @param {string} toolName
+   * @param {object} args - tool 参数（snake_case 对齐 SillyHub schema）
+   * @param {object} [opts]
+   * @param {boolean} [opts.quiet=false] - 静默失败警告（killLease 等已知 best-effort 路径用）
+   * @returns {Promise<object|null>} MCP tool result（{content:[{type,text}]}），失败返回 null
+   */
+  async _callTool(toolName, args = {}, { quiet = false } = {}) {
+    return this._sendRpc('tools/call', { name: toolName, arguments: args }, { quiet, label: toolName });
+  }
+
+  /**
+   * 发 JSON-RPC 请求（fetch/SSE/鉴权骨架，tools/call 与 tools/list 共用）。best-effort 不抛。
+   *
+   * task-11 抽出：原 _callTool 的网络骨架；method/params 泛化——tools/call 带 {name,arguments}，
+   * tools/list 带空 params。warn 文案用 label 作 tag（tools/call 传 toolName 保文案不变，
+   * tools/list 传 'tools/list'）。
+   * @param {string} method - JSON-RPC method（'tools/call' | 'tools/list'）
+   * @param {object} params - JSON-RPC params（tools/call: {name,arguments}; tools/list: {}）
+   * @param {object} [opts]
+   * @param {boolean} [opts.quiet=false] - 静默失败警告
+   * @param {string} [opts.label] - warn 文案标签（默认 method；tools/call 传 toolName 保文案）
+   * @returns {Promise<object|null>} JSON-RPC result（tools/call: {content}; tools/list: {tools}），失败 null
+   */
+  async _sendRpc(method, params, { quiet = false, label } = {}) {
+    const tag = label || method;
+    if (!this._configured) {
+      if (!quiet) console.warn(`[sillyhub-mcp] 未配置（缺 SILLYHUB_MCP_URL/TOKEN），${tag} 跳过`);
+      return null;
+    }
+
+    this._rpcId += 1;
+    const id = this._rpcId;
+    const body = {
+      jsonrpc: '2.0',
+      id,
+      method,
+      params,
+    };
+
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this._timeoutMs);
+    let res;
+    try {
+      res = await fetch(this._endpoint, {
+        method: 'POST',
+        headers: {
+          Authorization: `Bearer ${this._token}`,
+          'Content-Type': 'application/json',
+          Accept: 'application/json, text/event-stream',
+          'MCP-Protocol-Version': MCP_PROTOCOL_VERSION,
+        },
+        body: JSON.stringify(body),
+        signal: controller.signal,
+      });
+    } catch (err) {
+      if (!quiet) {
+        if (err && err.name === 'AbortError') {
+          console.warn(`[sillyhub-mcp] ${tag} 请求超时 (${this._timeoutMs}ms)`);
+        } else {
+          const msg = err && err.message ? err.message : String(err);
+          console.warn(`[sillyhub-mcp] ${tag} 请求失败: ${msg}`);
+        }
+      }
+      return null;
+    } finally {
+      clearTimeout(timer);
+    }
+
+    if (!res.ok) {
+      if (!quiet) {
+        let detail = '';
+        try { detail = await res.text(); } catch { /* best effort */ }
+        console.warn(`[sillyhub-mcp] ${tag} → HTTP ${res.status} ${String(detail).slice(0, 200)}`);
+      }
+      return null;
+    }
+
+    // 解析响应：JSON 或 SSE（跨平台兼容 \r\n / \n）
+    const ct = res.headers.get('content-type') || '';
+    let rpc = null;
+    try {
+      if (ct.includes('text/event-stream')) {
+        const text = await res.text();
+        rpc = this._parseSseResponse(text, id);
+      } else {
+        // application/json（或其他）：直接 JSON.parse
+        rpc = await res.json();
+      }
+    } catch (err) {
+      if (!quiet) {
+        const msg = err && err.message ? err.message : String(err);
+        console.warn(`[sillyhub-mcp] ${tag} 响应解析失败: ${msg}`);
+      }
+      return null;
+    }
+
+    if (!rpc) {
+      if (!quiet) console.warn(`[sillyhub-mcp] ${tag} 响应无 JSON-RPC 内容`);
+      return null;
+    }
+
+    if (rpc.error) {
+      if (!quiet) console.warn(`[sillyhub-mcp] ${tag} JSON-RPC error: ${JSON.stringify(rpc.error)}`);
+      return null;
+    }
+
+    return rpc.result || null;
+  }
+
+  /**
+   * 解析 SSE 响应：取含 JSON-RPC result/error 的事件；优先 id 精确匹配，否则取首个。
+   * 事件间空行分隔；事件内 data: 行可多行，拼装时用 \n 连接。
+   */
+  _parseSseResponse(text, expectedId) {
+    const events = String(text).split(/\r?\n\r?\n/);
+    let fallback = null;
+    for (const evt of events) {
+      const dataLines = [];
+      for (const line of evt.split(/\r?\n/)) {
+        if (line.startsWith('data:')) {
+          // 去掉 "data:" 前缀与一个可选前导空格
+          dataLines.push(line.slice(5).replace(/^ /, ''));
+        }
+      }
+      if (dataLines.length === 0) continue;
+      const data = dataLines.join('\n');
+      let parsed;
+      try {
+        parsed = JSON.parse(data);
+      } catch {
+        continue; // 非 JSON data（心跳/注释等），跳过
+      }
+      if (!parsed || typeof parsed !== 'object') continue;
+      if (parsed.result !== undefined || parsed.error !== undefined) {
+        if (expectedId !== undefined && parsed.id === expectedId) return parsed;
+        if (!fallback) fallback = parsed;
+      }
+    }
+    return fallback;
+  }
+
+  /**
+   * 从 MCP tool result 提取 content[0].text 并 JSON.parse 为 tool 返回值（MCP tool 结果惯例）。
+   * @returns {any|null} 解析后的 tool 返回值；非 JSON 字符串则原样返回；缺失返回 null
+   */
+  _parseToolReturnValue(result) {
+    if (!result || !Array.isArray(result.content) || result.content.length === 0) return null;
+    const first = result.content[0];
+    if (!first || typeof first.text !== 'string') return null;
+    const text = first.text;
+    try {
+      return JSON.parse(text);
+    } catch {
+      return text; // tool 返回非 JSON 字符串，原样返回
+    }
+  }
+
+  // ── 对外方法（均 async，best-effort 不抛） ──
+
+  /**
+   * 探测 daemon 连通性 + token 有效性（调 list_agent_profiles tool）。
+   * 未配置 / HTTP 异常 / 非 2xx / JSON-RPC error → 返回 false（不阻塞调用方）。
+   * @returns {Promise<boolean>} 成功且 tool 返回非空 → true，否则 false
+   */
+  async probeDaemon() {
+    if (!this._configured) return false;
+    const result = await this._callTool('list_agent_profiles', {});
+    return result !== null;
+  }
+
+  /**
+   * 列出 daemon 暴露的 MCP tools（JSON-RPC `tools/list`，task-11 路径A 探测用）。
+   *
+   * 与 tools/call 的差异：method='tools/list'，无 name/arguments；响应 result 是
+   * `{tools: [{name, description, inputSchema}, ...]}`（MCP 标准）。本方法返回 tools 数组
+   * （优先 result.tools，兼容 daemon 直接返回数组），调用方（probe.js 路径A 探测）据此查
+   * dispatch_worker.inputSchema.properties 是否含 worktree_path + worker_prompt。
+   *
+   * best-effort：未配置 / HTTP 异常 / 非 2xx / JSON-RPC error / 解析失败 → 返回 null 不抛
+   * （R-04 保守，探测失败由调用方降级 false）。默认 quiet=true（探测路径不刷失败噪音，
+   * 区别于业务 tool 调用默认 quiet=false）。
+   * @param {object} [opts]
+   * @param {boolean} [opts.quiet=true] - 静默失败警告（探测路径默认静默）
+   * @returns {Promise<Array<{name:string, inputSchema?:object}>|null>} tools 数组；失败/未配置 null
+   */
+  async listTools({ quiet = true } = {}) {
+    if (!this._configured) return null;
+    const result = await this._sendRpc('tools/list', {}, { quiet, label: 'tools/list' });
+    if (!result) return null;
+    if (Array.isArray(result)) return result;            // daemon 直接返回数组（兼容）
+    if (Array.isArray(result.tools)) return result.tools; // 标准 MCP {tools:[...]}
+    return null;
+  }
+
+  /**
+   * best-effort 从 daemon 拿 workspace root_path（task-12 路径A 越界校验用）。
+   *
+   * 复用 tools/list RPC 机制（与 listTools 同 method，复用 _sendRpc 骨架，task-12 "复用 task-11
+   * listTools"）：defensively 读 result.root_path（若 daemon 在 tools/list 响应顶层暴露）。
+   * 当前 SillyHub gateway 的 tools/list 仅返 `{tools:[...]}` 不含 root_path → 实际返回 null
+   * （probe 跳过越界校验，best-effort 语义）。**不臆造 daemon 接口**（无专用 get_workspace_root
+   * tool，见 task-12 constraints / spike-01 结论）；后续 daemon 若在 tools/list 顶层暴露 root_path，
+   * 本方法自动适配，probe 无需改。
+   *
+   * best-effort：未配置 / 异常 / 无 root_path 字段 → 返回 null 不抛。
+   * @param {object} [opts]
+   * @param {boolean} [opts.quiet=true] - 静默失败警告
+   * @returns {Promise<string|null>} root_path 绝对路径；拿不到 null
+   */
+  async getRootPath({ quiet = true } = {}) {
+    if (!this._configured) return null;
+    const result = await this._sendRpc('tools/list', {}, { quiet, label: 'tools/list' });
+    if (!result || typeof result !== 'object') return null;
+    const rp = result.root_path;
+    return typeof rp === 'string' && rp.length > 0 ? rp : null;
+  }
+
+  /**
+   * 创建 mission（调 create_mission tool）。
+   * @param {object} p
+   * @param {string} p.objective
+   * @param {string} p.changeId
+   * @param {number} [p.budgetUsd]
+   * @param {string} [p.orchestrationMode] - 'team'(默认,不传走原逻辑零回归,FR-05) |
+   *   'external'(路径A,SillySpec 外部调度:跳 orchestrator spawn + converge 跳 merge,FR-08/D-007)。
+   *   传入时 args.orchestration_mode = mode；不传/Null 不加字段（team 默认，零回归）。
+   * @returns {Promise<{missionId: string|null}>} 未配置/失败 → { missionId: null }
+   */
+  async createMission({ objective, changeId, budgetUsd, orchestrationMode } = {}) {
+    if (!this._configured) return { missionId: null };
+    const args = {
+      objective,
+      change_id: changeId,
+    };
+    if (budgetUsd !== undefined && budgetUsd !== null) args.budget_usd = budgetUsd;
+    // task-12：路径A 传 'external'（跳 orchestrator spawn，FR-08）；不传 → 不加字段，daemon 默认 team 零回归
+    if (orchestrationMode !== undefined && orchestrationMode !== null) {
+      args.orchestration_mode = orchestrationMode;
+    }
+    const result = await this._callTool('create_mission', args);
+    if (result === null) return { missionId: null };
+    const value = this._parseToolReturnValue(result);
+    const missionId = value && typeof value === 'object'
+      ? (value.mission_id ?? value.missionId ?? null)
+      : null;
+    return { missionId };
+  }
+
+  /**
+   * 派发 worker（调 dispatch_worker tool，路径A 入参含 worktree_path/branch/worker_prompt）。
+   * worktree_path 仅作 tool 入参传递，不持久化为 DB 列。
+   * @param {object} p
+   * @param {string} p.missionId
+   * @param {string} p.objective
+   * @param {string} [p.worktreePath]
+   * @param {string} [p.branch]
+   * @param {boolean} [p.readOnly]
+   * @param {string} [p.model]
+   * @param {string} [p.agentProfileId]
+   * @param {string} [p.workerPrompt]
+   * @returns {Promise<{workerId: string|null, status: string}>} 未配置/失败 → { workerId: null, status: 'unavailable' }
+   */
+  async dispatchWorker({
+    missionId, objective, worktreePath, branch, readOnly, model, agentProfileId, workerPrompt,
+  } = {}) {
+    if (!this._configured) return { workerId: null, status: 'unavailable' };
+    const args = {
+      mission_id: missionId,
+      objective,
+    };
+    if (readOnly !== undefined) args.read_only = readOnly;
+    if (worktreePath !== undefined && worktreePath !== null) args.worktree_path = worktreePath;
+    // task-12 / D-009：branch 字段名对齐跨仓契约（design §7.3，round-1 worktree_branch 已统一为 branch）
+    if (branch !== undefined && branch !== null) args.branch = branch;
+    if (model !== undefined && model !== null) args.model = model;
+    if (agentProfileId !== undefined && agentProfileId !== null) args.agent_profile_id = agentProfileId;
+    if (workerPrompt !== undefined && workerPrompt !== null) args.worker_prompt = workerPrompt;
+    const result = await this._callTool('dispatch_worker', args);
+    if (result === null) return { workerId: null, status: 'unavailable' };
+    const value = this._parseToolReturnValue(result);
+    const workerId = value && typeof value === 'object'
+      ? (value.worker_id ?? value.workerId ?? null)
+      : null;
+    const status = value && typeof value === 'object'
+      ? (value.status ?? 'unknown')
+      : 'unknown';
+    return { workerId, status };
+  }
+
+  /**
+   * 列出 mission 下的 worker（调 list_workers tool）。
+   * @param {string} missionId
+   * @returns {Promise<Array>} 未配置/失败返回 []；兼容 tool 返回数组或 { workers: [...] }
+   */
+  async listWorkers(missionId) {
+    if (!this._configured) return [];
+    const result = await this._callTool('list_workers', { mission_id: missionId });
+    if (result === null) return [];
+    const value = this._parseToolReturnValue(result);
+    if (Array.isArray(value)) return value;
+    if (value && Array.isArray(value.workers)) return value.workers;
+    return [];
+  }
+
+  /**
+   * 终止 worker lease 防双写（UB-6 超时 fallback 用）。
+   *
+   * 注：SillyHub 当前 8 个 tool 无显式 kill，路径A 未落地；best-effort 实现——
+   * 尝试 report_progress 带 kill 标记投递终止请求；tool 不存在/不支持/HTTP 异常时静默返回不抛。
+   * 由于无专用 kill tool，lease 实际终止不保证，结果保守报 killed=false
+   * （路径A 落地专用 kill tool 后再升级为 killed=true 语义）。
+   * @param {string} workerId
+   * @returns {Promise<{killed: boolean, reason?: string}>}
+   */
+  async killLease(workerId) {
+    if (!this._configured) {
+      return { killed: false, reason: '未配置 SillyHub MCP（路径A 未落地/kill tool 未支持）' };
+    }
+    // best-effort：quiet 抑制已知未落地路径的失败噪音（静默返回不抛）
+    const result = await this._callTool('report_progress', {
+      worker_id: workerId,
+      kill: true,
+      marker: 'sillyspec-kill-lease',
+    }, { quiet: true });
+    if (result === null) {
+      return { killed: false, reason: '路径A 未落地/kill tool 未支持（report_progress kill 标记未生效或被拒）' };
+    }
+    // report_progress 调用成功 ≠ lease 已终止（其非专用 kill tool）；保守报 killed=false
+    return {
+      killed: false,
+      reason: '路径A 未落地/kill tool 未支持（kill 标记已投递，lease 实际终止需 daemon 侧专用 kill tool）',
+    };
+  }
+}