sillyspec 3.26.11 → 3.26.14

package/src/run/shared.js

@@ -11,7 +11,7 @@
  *     本模块仅 re-export，run/ 层现有调用方路径与行为不变。
  */
 import { basename, join, resolve, dirname, sep } from 'node:path'
-import { existsSync, readdirSync, readFileSync, statSync, mkdirSync, writeFileSync } from 'node:fs'
+import { existsSync, readdirSync, readFileSync, statSync, mkdirSync, writeFileSync, appendFileSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 import os from 'node:os'
 
@@ -336,12 +336,26 @@ export const PLATFORM_MANAGED_FILENAME = '.sillyspec-platform-managed'
 
 export function writePlatformPointer(cwd, platformOpts, extra = {}) {
   if (!platformOpts || (!platformOpts.specRoot && !platformOpts.runtimeRoot)) return false
+  // HUB-05：合并保留既有生命周期字段。scan 完成时指针被写入 status/completedAt/scanStatus
+  //（complete-handlers），但下一次任何平台模式 run（含只读 --status）都会重写指针——
+  // 恢复链只回填 specRoot 等四字段，不保留 status → 指针永远回 active、isPointerStale
+  // 恒 false、`platform pointer --cleanup` 的 STALE 分支不可达。extra 显式传值仍可覆盖。
+  let preserved = {}
+  try {
+    const existing = JSON.parse(readFileSync(join(cwd, '.sillyspec-platform.json'), 'utf8'))
+    if (existing && typeof existing === 'object') {
+      for (const k of ['status', 'completedAt', 'scanStatus']) {
+        if (existing[k] !== undefined && extra[k] === undefined) preserved[k] = existing[k]
+      }
+    }
+  } catch { /* 无既有指针/损坏 → 全新写入 */ }
   const payload = {
     specRoot: platformOpts.specRoot || null,
     runtimeRoot: platformOpts.runtimeRoot || null,
     workspaceId: platformOpts.workspaceId || null,
     scanRunId: platformOpts.scanRunId || null,
     savedAt: new Date().toISOString(),
+    ...preserved,
     ...extra,
   }
   // 声明文件字段集独立于指针 payload（D-E@v2 四字段：无 status/savedAt/scanRunId——
@@ -353,8 +367,14 @@ export function writePlatformPointer(cwd, platformOpts, extra = {}) {
     declaredAt: new Date().toISOString(),
   }
   try {
-    mkdirSync(join(platformOpts.specRoot, '.runtime'), { recursive: true })
-    writeFileSync(join(platformOpts.specRoot, '.runtime', 'platform-scan.json'), JSON.stringify(payload, null, 2) + '\n')
+    // platform-scan.json 只在 specRoot 存在时可写（坑 pointer-runtime-root-only-null-join）：
+    // runtimeRoot-only 平台组合（command.js 明确允许）下 specRoot 为 null，此前 join(null,…)
+    // 抛 ERR_INVALID_ARG_TYPE 落入总 catch → 指针与接管声明也一并静默未写，双入口 fail-closed
+    // 对该组合整体失效。分步写：specRoot 缺失只跳过 platform-scan.json，指针/声明照写。
+    if (platformOpts.specRoot) {
+      mkdirSync(join(platformOpts.specRoot, '.runtime'), { recursive: true })
+      writeFileSync(join(platformOpts.specRoot, '.runtime', 'platform-scan.json'), JSON.stringify(payload, null, 2) + '\n')
+    }
     writeFileSync(join(cwd, '.sillyspec-platform.json'), JSON.stringify(payload, null, 2) + '\n')
     writeFileSync(join(cwd, PLATFORM_MANAGED_FILENAME), JSON.stringify(declaration, null, 2) + '\n')
     return true
@@ -415,54 +435,90 @@ export function resolveChangeDir(cwd, progress, specDir = null) {
 // sync 总超时熔断：sync.js 是 best-effort 后台回传（每请求已有 10s 超时），但 sync() 可能串行多次
 // fetchJson 累积等待、阻塞 --done。给 8s 总超时，超时放弃（best-effort，失败不影响正确性，下次 --done 重试）。
 // 历史痛点：--done 在 sync 慢时体感 hang，用户被迫用外部 timeout 兜底。
+// HUB-09：熔断超时时必须 abort 底层在飞请求（opts.signal 一路传到 fetch）——否则熔断后请求
+// 仍在跑，平台可能已接受推送而客户端当作超时放弃（spec 树推送无 base_ts 自愈兜底）。
 const SYNC_TOTAL_TIMEOUT_MS = 8_000
 
+/**
+ * 熔断 race + 确定性取消：超时触发 controller.abort() 并 resolve，在飞 fetch 收到
+ * AbortError 后自然失败（各调用方 catch 返回降级值，进程不挂起）。
+ * @param {() => Promise} op 接收 { signal } 的异步操作
+ * @param {number} timeoutMs 熔断时长（测试可缩短）
+ */
+async function raceWithAbort(op, timeoutMs = SYNC_TOTAL_TIMEOUT_MS) {
+  const controller = new AbortController()
+  let timer
+  try {
+    await Promise.race([
+      op({ signal: controller.signal }),
+      new Promise((resolve) => { timer = setTimeout(() => { controller.abort(); resolve(null) }, timeoutMs) }),
+    ])
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
 // quick 会话 ID 形态（quick-<hex8>）。与 run/command.js QUICK_SID_RE、progress.js
 // initChange 的跳过实体目录判断同源；shared.js 不反向 import command.js（重模块），
 // 局部复制正则保持轻载——改形态时三处同改。
 const QUICK_SID_RE = /^quick-[0-9a-f]{8}$/
 
-export async function triggerSync(cwd, changeName, platformOpts = {}) {
+export async function triggerSync(cwd, changeName, platformOpts = {}, opts = {}) {
   // 平台模式（SillyHub）走自己的回传链路，不走 CLI 内置 sync
   if (platformOpts?.specRoot || platformOpts?.runtimeRoot) return
   try {
-    if (changeName && !existsSync(join(cwd, '.sillyspec', 'changes', changeName))) {
-      // ql-20260818-011：quick 会话按设计无实体变更目录（progress.js initChange 同款
-      // 跳过建目录），progress/四件套上行对它是孤儿数据；但 spec 树增量（QUICKLOG/
-      // 模块文档的上行通道）以服务器清单为锚，与变更目录无关——降级只推 spec 树。
-      // 其余形态（真实变更名拼错）维持静默 return，防噪音混入 spec 树通道。
-      if (QUICK_SID_RE.test(changeName)) {
-        // shared.js 在 src/run/，sync.js 在 src/ → 退一层
-        const syncMod = await import('../sync.js')
-        let timer
-        try {
-          await Promise.race([
-            syncMod.syncSpecTreeOnly(changeName, cwd),
-            new Promise((resolve) => { timer = setTimeout(resolve, SYNC_TOTAL_TIMEOUT_MS) }),
-          ])
-        } finally {
-          clearTimeout(timer)
-        }
-      }
+    // ql-20260818-011：quick 会话按设计无实体变更目录（progress.js initChange 同款
+    // 跳过建目录），progress/四件套上行对它是孤儿数据；但 spec 树增量（QUICKLOG/
+    // 模块文档的上行通道）以服务器清单为锚，与变更目录无关——降级只推 spec 树。
+    if (changeName && QUICK_SID_RE.test(changeName) && !existsSync(join(cwd, '.sillyspec', 'changes', changeName))) {
+      // shared.js 在 src/run/，sync.js 在 src/ → 退一层
+      const syncMod = await import('../sync.js')
+      await raceWithAbort((sig) => syncMod.syncSpecTreeOnly(changeName, cwd, sig), opts.timeoutMs)
       return
     }
+    // 目录缺失的非 quick 变更不再静默 return（archive-final-state-sync）：归档把
+    // changes/<name>/ 移到 changes/archive/<name>/ 并注销 DB 行后，第 4/5 步收尾的
+    // triggerSync 仍会触发——DB 里的终态（steps 完成态 + status='archived'）与文件树
+    // 移动必须推平台，否则平台进度永远停在移动前的最后一步。sync() 内部对目录缺失
+    // 本就是 warn-and-continue（serializeForSync 从 DB 读不依赖目录）；真实拼错名时
+    // 无 DB 行，sync() 在发出任何 HTTP 前即 return，仅多一行 warn（未连接平台则完全静默）。
     // shared.js 在 src/run/，sync.js 在 src/ → 退一层
     const syncMod = await import('../sync.js')
-    let timer
-    try {
-      await Promise.race([
-        syncMod.sync(changeName, cwd),
-        new Promise((resolve) => { timer = setTimeout(resolve, SYNC_TOTAL_TIMEOUT_MS) }),
-      ])
-    } finally {
-      clearTimeout(timer) // sync 先完成则清掉未触发的 timer，避免泄漏
-    }
+    await raceWithAbort((sig) => syncMod.sync(changeName, cwd, sig), opts.timeoutMs)
   } catch (e) {
     // sync.js 不存在或同步失败，静默跳过
     console.warn('⚠️ 同步失败:', e.message)
   }
 }
 
+/**
+ * 自动 pull 节流（体检 PERF-02）：triggerPull/triggerPullActiveChange 在每条 stage 命令
+ * 启动时注入，agent 命令往往是秒级连发——每次都发 HTTP GET（daemon 挂/慢时单命令最多
+ * 阻塞 8s）。跨进程 marker 节流：10s 内已有自动 pull 则跳过（手动 `platform pull` 不走
+ * 此门，语义不变）。错过窗口的平台更新由下一条 >10s 的命令或 push 409 自愈兜底。
+ */
+const AUTO_PULL_THROTTLE_MS = 10_000
+
+function _autoPullThrottlePath(cwd) {
+  return join(cwd, '.sillyspec', '.runtime', 'auto-pull-throttle.json')
+}
+
+function _autoPullRecently(cwd) {
+  try {
+    const t = JSON.parse(readFileSync(_autoPullThrottlePath(cwd), 'utf8'))
+    return typeof t.at === 'number' && Date.now() - t.at < AUTO_PULL_THROTTLE_MS
+  } catch {
+    return false
+  }
+}
+
+function _stampAutoPull(cwd) {
+  try {
+    mkdirSync(dirname(_autoPullThrottlePath(cwd)), { recursive: true })
+    writeFileSync(_autoPullThrottlePath(cwd), JSON.stringify({ at: Date.now() }) + '\n', 'utf8')
+  } catch { /* best-effort：节流失效仅退化为逐次 pull */ }
+}
+
 /**
  * 触发 pull（下行同步，task-10 / D-009 / FR-04 / FR-06）。
  * 复用 triggerSync 的 8s 熔断与 Best Effort 语义；未连接平台静默跳过（与现状一致）。
@@ -474,23 +530,18 @@ export async function triggerSync(cwd, changeName, platformOpts = {}) {
  * @param {string} changeName - 当前活跃变更（多变更时传 null 跳过，避免误拉）
  * @param {object} [platformOpts] - 平台模式 opts（specRoot/runtimeRoot 存在则跳过，走平台自有链路）
  */
-export async function triggerPull(cwd, changeName, platformOpts = {}) {
+export async function triggerPull(cwd, changeName, platformOpts = {}, opts = {}) {
   // 平台模式（SillyHub）走自己的链路，跳过
   if (platformOpts?.specRoot || platformOpts?.runtimeRoot) return
   try {
     const syncMod = await import('../sync.js')
     const sm = new syncMod.SyncManager(cwd)
-    // 未连接平台静默跳过（本地独立用户合法状态，不噪音）
+    // 未连接平台静默跳过（本地独立用户合法状态，不噪音）——节流 stamp 必须在此之后：
+    // 否则未连接的项目每次 run 都写 .sillyspec/.runtime/ 标记（凭空造目录）
     if (!sm._getPlatform()) return
-    let timer
-    try {
-      await Promise.race([
-        sm.pull(changeName, { skipIfLocalDirty: true }),
-        new Promise((resolve) => { timer = setTimeout(resolve, SYNC_TOTAL_TIMEOUT_MS) }),
-      ])
-    } finally {
-      clearTimeout(timer)
-    }
+    if (_autoPullRecently(cwd)) return
+    _stampAutoPull(cwd)
+    await raceWithAbort((sig) => sm.pull(changeName, { skipIfLocalDirty: true, signal: sig.signal }), opts.timeoutMs)
   } catch (e) {
     // pull 失败静默跳过（Best Effort，失败不影响正确性）
     console.warn('⚠️ 拉取失败:', e.message)
@@ -513,6 +564,10 @@ export async function triggerPullActiveChange(cwd, platformOpts = {}) {
   } catch {
     return
   }
+  // PERF-02 节流（连接确认后才 stamp——未连接项目不得凭空写 .sillyspec/.runtime/）：
+  // 与 triggerPull 共用同一 marker（本函数与它在同一命令启动链上互斥出现）
+  if (_autoPullRecently(cwd)) return
+  _stampAutoPull(cwd)
   let cn = null
   try {
     const { ProgressManager } = await import('../progress.js')
@@ -523,29 +578,48 @@ export async function triggerPullActiveChange(cwd, platformOpts = {}) {
     // progress 不可达则跳过（Best Effort）
   }
   if (!cn) return
-  // 已确认连接 + 单活跃变更，调 pull（复用 triggerPull 的 8s 熔断；skipIfLocalDirty 保守守卫
+  // 已确认连接 + 单活跃变更，调 pull（复用 8s 熔断 + abort（HUB-09）；skipIfLocalDirty 保守守卫
   // 同 triggerPull——本地脏时跳过 import，防平台旧快照覆盖本地领先进度，ql-20260818-008）
   try {
-    let timer
-    try {
-      await Promise.race([
-        sm.pull(cn, { skipIfLocalDirty: true }),
-        new Promise((resolve) => { timer = setTimeout(resolve, SYNC_TOTAL_TIMEOUT_MS) }),
-      ])
-    } finally {
-      clearTimeout(timer)
-    }
+    await raceWithAbort((sig) => sm.pull(cn, { skipIfLocalDirty: true, signal: sig.signal }))
   } catch (e) {
     console.warn('⚠️ 拉取失败:', e.message)
   }
 }
 
+/**
+ * 审批状态 unknown（体检 HUB-07）的统一处置：醒目多行警告 + 落 .runtime/approval-unknown.log 留痕。
+ *
+ * 语义边界：unknown = 已连接平台但 404/断网/超时/非 JSON——**不是审批通过**。放行是
+ * fail-open 的既定取舍（网络故障不应硬阻断每一条 execute），但静默放行会让团队审批
+ * 形同虚设且无迹可查；至少要（a）让操作者当场看见（b）留下可审计记录。
+ * 留痕选 .runtime 日志而非 QUICKLOG：QUICKLOG 是 quick 会话的任务记录，run 流程的
+ * 审批事件写进去会污染 quick 语义与边界审计。
+ * @param {string} cwd
+ * @param {string} changeName
+ * @param {string} reason checkApproval 返回的 reason
+ */
+export function warnApprovalUnknown(cwd, changeName, reason) {
+  console.warn('')
+  console.warn('⚠️⚠️⚠️══════════════════════════════════════════════')
+  console.warn(`⚠️ 审批状态未知：变更「${changeName}」无法核实审批（${reason || '请求失败'}）`)
+  console.warn('⚠️ 本次 execute 按 fail-open 放行——这不是审批通过；平台恢复后请到平台复核审批记录')
+  console.warn('⚠️ 排查：平台服务是否可达（sillyspec platform status）/ 网络代理；确认无需审批可 --skip-approval 显式跳过')
+  console.warn('⚠️ 本次放行已记录：.sillyspec/.runtime/approval-unknown.log')
+  console.warn('⚠️⚠️══════════════════════════════════════════════')
+  try {
+    const logDir = join(cwd, '.sillyspec', '.runtime')
+    mkdirSync(logDir, { recursive: true })
+    appendFileSync(join(logDir, 'approval-unknown.log'),
+      `${new Date().toISOString()} | change=${changeName} | reason=${reason || 'unknown'}\n`, 'utf8')
+  } catch { /* 留痕失败不阻断流程（警告横幅已输出） */ }
+}
+
 /**
  * 审批检查：execute 阶段启动前检查（W6 Step8a 从 run.js 搬入，runStage + runAutoMode 共用）。
  * 平台模式走自己的链路，跳过；否则 await import sync.js。
  * @returns {{ status: string, reason?: string } | null}
- */
-export async function checkApproval(cwd, changeName, platformOpts = {}) {
+ */export async function checkApproval(cwd, changeName, platformOpts = {}) {
   // 平台模式不需要 CLI 内置审批检查
   if (platformOpts?.specRoot || platformOpts?.runtimeRoot) return null
   try {
@@ -774,7 +848,11 @@ export async function auditQuickCompletion(cwd, guard, options = {}) {
     ]
 
     for (const entry of currentEntries) {
-      const status = entry.slice(0, 2).trim()
+      // porcelain 两字符状态码（X=暂存区 Y=工作区）不能先 trim：' D'.trim()==='D' 使第二分支恒假、
+      // 'DD'/'AD' 等 trim 后不等于 'D' 而漏检——--allow-delete 门对此类删除静默放行（体检 BUG-04）。
+      // 用原始两字符判定任一侧为 D 即删除。
+      const rawStatus = entry.slice(0, 2)
+      const status = rawStatus.trim()
       const file = parsePorcelainPath(entry)   // 已去引号/处理 rename/归一化，修正首行丢首字符
       if (!file) continue
 
@@ -786,7 +864,7 @@ export async function auditQuickCompletion(cwd, guard, options = {}) {
       if (isBaselineFile(file)) continue
 
       result.changedFiles.push(file)
-      if (status === 'D' || status === ' D') result.deletedFiles.push(file)
+      if (rawStatus[0] === 'D' || rawStatus[1] === 'D') result.deletedFiles.push(file)
       if (status === '??') result.newFiles.push(file)
 
       // 检查是否命中 baseline protected files
@@ -841,13 +919,17 @@ export async function auditQuickCompletion(cwd, guard, options = {}) {
     // 致 flag 对 status 失效。）
     if ((!forceBaseline && result.baselineHit.length > 0) || (!allowDelete && result.deletedFiles.length > 0) || result.reasons.some(r => r.startsWith('危险') || r.startsWith('删除'))) {
       result.status = 'blocked'
-    } else if ((!allowNew && result.newFiles.length > 0) || (allowedFiles.length > 0 && result.reasons.some(r => r.startsWith('超出')))) {
+    } else if ((!allowNew && result.newFiles.some(f => !isQuickMetadata(f, guard.linkedChanges))) || (allowedFiles.length > 0 && result.reasons.some(r => r.startsWith('超出')))) {
+      // newFiles 按元数据过滤后判定（坑 quick-metadata-warning-no-reason）：.sillyspec/ 被 git
+      // 跟踪的仓库里 quick 新建的 quicklog/*.md 是合法元数据，不过滤会 status=warning 而
+      // reasons 为空（reasons 侧已过滤），打印空原因的 WARNING 噪声。
       result.status = 'warning'
     }
 
-    // quicklog 存在性检查
+    // quicklog 存在性检查（specBase 感知：平台模式 quicklog 写在 specRoot 下，stage.js
+    // allocateQuicklogEntry 同源；硬编码 cwd/.sillyspec 会恒误报「目录不存在」抬 warning）
     try {
-      const quicklogDir = join(cwd, '.sillyspec', 'quicklog')
+      const quicklogDir = join(specBase || join(cwd, '.sillyspec'), 'quicklog')
       if (existsSync(quicklogDir)) {
         const qlFiles = readdirSync(quicklogDir).filter(f => f.endsWith('.md'))
         if (qlFiles.length === 0) {
@@ -885,8 +967,12 @@ export async function auditQuickCompletion(cwd, guard, options = {}) {
     const mdChanged = result.changedFiles.filter((f) => f.endsWith('.md') && !deletedSet.has(f) && !isQuickMetadata(f, guard.linkedChanges))
     if (mdChanged.length > 0) {
       try {
-        const { runDocsCheck } = await import('../docs-check.js')
-        const dc = runDocsCheck({ projectRoot: cwd, docs: mdChanged })
+        const { runDocsCheck, readDocsCheckConfig } = await import('../docs-check.js')
+        // HUB-06：补传 crossRepoRoots（与 docs gate / index.js docs check 同口径）——
+        // 否则 repo:// 跨仓引用在这条链路恒跳过；无 local.yaml 配置时 undefined = 不启用
+        let quickCfg = {}
+        try { quickCfg = readDocsCheckConfig(cwd) || {} } catch { quickCfg = {} }
+        const dc = runDocsCheck({ projectRoot: cwd, docs: mdChanged, crossRepoRoots: quickCfg.crossRepoRoots })
         if (!dc.ok) {
           result.reasons.push(`本次改动文档含 ${dc.invalid.length} 处失效 file:line 引用（sillyspec docs check 可复现）`)
           result.docsCheckHint = { invalid: dc.invalid.length, total: dc.total }
@@ -906,7 +992,11 @@ export async function auditQuickCompletion(cwd, guard, options = {}) {
     const srcChangedFiles = result.changedFiles.filter((f) => f.startsWith('src/') && !deletedSet.has(f))
     if (srcChangedFiles.length > 0) {
       try {
-        const { collectDocRefs, runDocsCheck } = await import('../docs-check.js')
+        const { collectDocRefs, runDocsCheck, readDocsCheckConfig } = await import('../docs-check.js')
+        // HUB-06：活文档（platform-interface-map.md 等最可能写 repo:// 引用的文档）同样补传
+        // crossRepoRoots；配置读一次提到循环外（per-cwd 恒同）
+        let livingCfg = {}
+        try { livingCfg = readDocsCheckConfig(cwd) || {} } catch { livingCfg = {} }
         const livingDocs = await resolveLivingDocs(cwd)
         const files = []
         const docs = []
@@ -918,7 +1008,7 @@ export async function auditQuickCompletion(cwd, guard, options = {}) {
           if (hit.length === 0) continue
           files.push(...hit)
           docs.push(docRel)
-          const r = runDocsCheck({ projectRoot: cwd, docs: [docRel], keywordAssert: true })
+          const r = runDocsCheck({ projectRoot: cwd, docs: [docRel], keywordAssert: true, crossRepoRoots: livingCfg.crossRepoRoots })
           for (const x of r.invalid) invalidAll.push({ ...x, doc: docRel })
         }
         const invalid = matchInvalidRefsToChanged(invalidAll, srcChangedFiles)
@@ -1262,6 +1352,17 @@ export async function getStageSteps(stageName, cwd, progress, specDir = null) {
     const changeDir = resolveChangeDir(cwd, progress, specDir)
     return buildPlanSteps(changeDir)
   }
+  if (stageName === 'scan') {
+    // quick 档感知（坑 scan-quick-profile-step-mismatch）：scan 的 scanProfile 在首进程
+    // runStage 里算出并持久化（stageData.scanProfile），quick 档把 11 步注册表裁成 3 步。
+    // 此处恒返回注册表会让后续进程 ensureStageSteps 见 3 vs 11 触发漂移重播种（quick 已完成
+    // 步丢失、从未执行的注册表步骤被 --done），同进程 outputStep 也用错位 defSteps 渲染。
+    // quick 档 → 与 applyScanProfileSteps 同源返回 3 步表；standard/deep 与注册表同长度零影响。
+    if (progress?.stages?.scan?.scanProfile?.mode === 'quick') {
+      const { buildQuickScanSteps } = await import('./scan-profile.js')
+      return buildQuickScanSteps()
+    }
+  }
   const def = stageRegistry[stageName]
   return def ? def.steps : null
 }

package/src/run/stage.js

@@ -19,7 +19,7 @@
 import { join, dirname } from 'node:path'
 import { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs'
 import { writeAtomicSync } from '../fs-atomic.js'
-import { resolveSpecDir, resolveChangeDir, resolveRuntimeRoot, resolveQuickSessionsDir, triggerSync, safeGit, parsePorcelainPath, formatWaitOptions, checkApproval, getStageSteps } from './shared.js'
+import { resolveSpecDir, resolveChangeDir, resolveRuntimeRoot, resolveQuickSessionsDir, triggerSync, safeGit, parsePorcelainPath, formatWaitOptions, checkApproval, getStageSteps, warnApprovalUnknown } from './shared.js'
 import { computeScanProfile, applyScanProfileSteps, executeScanPreflight, executeScanPostcheck } from './scan-profile.js'
 import { outputStep } from './prompt.js'
 import { allocateQuicklogEntry, deriveTitleFromLinkedChange, sanitizeDesc } from '../quicklog.js'
@@ -56,6 +56,11 @@ export async function runStage(pm, progress, stageName, cwd, changeName, skipApp
         console.log(`⏳ 变更 ${changeName} 的执行审批待处理中...`)
         console.log('  提示：使用 --skip-approval 跳过审批检查')
       }
+      // HUB-07：unknown（连接了平台但 404/断网/非 JSON）此前静默落空（fail-open 无提示）——
+      // 醒目警告 + 留痕，放行但可审计
+      if (approval.status === 'unknown') {
+        warnApprovalUnknown(cwd, changeName, approval.reason)
+      }
     }
   }
 
@@ -118,6 +123,10 @@ export async function runStage(pm, progress, stageName, cwd, changeName, skipApp
           `请检查该路径是否为普通文件/只读，清理后重跑（sillyspec run execute --change ${changeName} --skip-approval）`)
       }
       writeFileSync(runIdFile, currentExecuteRunId + '\n')
+      // change 归属戳（坑 worktree-cleanup-marker-chain 根治）：run 目录自带变更身份，
+      // marker 断裂（worktree cleanup / 归档清理 / 并行误删）后按戳归属，不再错配其他变更的 run
+      const { stampExecuteRunChange } = await import('../task-review.js')
+      stampExecuteRunChange(runtimeRoot, currentExecuteRunId, changeName)
     }
   }
 
@@ -244,6 +253,25 @@ export async function runStage(pm, progress, stageName, cwd, changeName, skipApp
     if (existingGuard) {
       // 跨进程重入：复用已分配的 ql-ID，跳过 baseline 重捕与分配（幂等）
       progress.quickGuard = existingGuard
+      // 中途追加边界：会话中途发现要改启动声明外的文件，此前 resume 会把 --files 静默丢弃、
+      // 边界冻结在启动时刻，只能靠事后归属/审计行兜底。恢复时带 --files 即并入 allowedFiles
+      // （追加不替换、去重保序），同时点录 allowedFilesHash 供同文件并发检测（文件不存在跳过，
+      // 与启动同语义）。--done 审计直读 guard.json（complete-handlers §4.6），追加即被归属消费。
+      const resumeFiles = Array.isArray(quickOpts?.quickFiles) ? quickOpts.quickFiles.filter(Boolean) : []
+      if (resumeFiles.length > 0) {
+        const known = new Set(progress.quickGuard.allowedFiles || [])
+        const added = resumeFiles.filter(f => !known.has(f))
+        if (added.length > 0) {
+          progress.quickGuard.allowedFiles = [...(progress.quickGuard.allowedFiles || []), ...added]
+          progress.quickGuard.allowedFilesHash = { ...(progress.quickGuard.allowedFilesHash || {}) }
+          for (const f of added) {
+            try { progress.quickGuard.allowedFilesHash[f] = createHash('sha256').update(readFileSync(join(cwd, f))).digest('hex') }
+            catch { /* 预声明将新建的文件，与启动时 allowedFilesHash 同语义：不存在跳过 */ }
+          }
+          writeAtomicSync(guardFile, JSON.stringify(progress.quickGuard, null, 2))
+          console.log(`🛡️ quick 边界已追加: ${added.length} 个文件（累计 ${progress.quickGuard.allowedFiles.length} 个）: ${added.join(', ')}`)
+        }
+      }
     } else {
       // baseline 采集用 safeGit（带 -c safe.directory，避免 linked worktree/容器异 uid/Windows 挂载点
       // 下裸 `git status` 抛错）。safeGit 已消除 safe.directory 类失败；若仍失败（真非 git 目录等），
@@ -317,6 +345,16 @@ export async function runStage(pm, progress, stageName, cwd, changeName, skipApp
         if (allowDelete) parts.push('允许删除文件')
         console.log(`🛡️ quick 变更边界已记录: ${parts.join(', ')}`)
         console.log(`📝 QUICKLOG 条目已创建: ${qlId}`)
+        // 缺 --input 且关联变更无可提取标题 → 条目落「(quick 任务)」占位标题，平台「快速修复」列表
+        // 默认隐藏进行中占位（task-06 口径），长会话全程不可见、语义标题要到最终 --done 才回填。
+        // 此刻会话刚起步零沉没成本，提示放弃重启带 --input 是最便宜的自愈点。
+        if (!quickDesc) {
+          console.warn('')
+          console.warn('⚠️ 本次 quick 未带 --input：QUICKLOG 条目将以占位标题「(quick 任务)」落盘')
+          console.warn('   平台「快速修复」列表默认隐藏进行中的占位条目，语义标题要到最终 --done 才回填。')
+          console.warn('   长任务建议放弃本会话、带一句话任务描述重启（旧会话 run quick --reset --change <sessionId> 重置）：')
+          console.warn('     sillyspec run quick --input "<一句话任务描述>" [--linked-changes <a,b>] [--files <...>]')
+        }
         // 回填 DB changes 行的 title + quicklog_id，让 quick-<hex> 可读、DB↔QUICKLOG 可对账。
         // title 用 quickDesc（任务描述或关联变更标题）经 sanitizeDesc 压一行限长，与 QUICKLOG 条目标题同源。
         try {
@@ -380,6 +418,8 @@ export async function runStage(pm, progress, stageName, cwd, changeName, skipApp
         await executeScanPostcheck(cwd, platformOpts, scanProfile)
       } else if (cliAction === 'planPostcheck') {
         await executePlanPostcheck(cwd, platformOpts, progress)
+      } else {
+        throw new Error(`noAI 步骤 ${stepName} 的未知 _cliAction: ${cliAction}——请在 stage.js 注册对应分支`)
       }
       stageData.steps[currentIdx].status = 'completed'
       stageData.steps[currentIdx].completedAt = new Date().toLocaleString('zh-CN', { hour12: false })

package/src/setup.js

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
 import { join, dirname } from 'path';
-import { execSync, execFileSync } from 'child_process';
+import { execSync } from 'child_process';
+import { gitQuiet } from './git-helper.js';
 import chalk from 'chalk';
 import ora from 'ora';
 import { checkbox, input } from '@inquirer/prompts';
@@ -359,16 +360,13 @@ export async function cmdSetup(dir, options = {}) {
       // 凭据提交风险提示（sec-c）：.claude/mcp.json / .cursor/mcp.json 是项目共享文件、通常随 git
       // 提交，而 DB MCP 的 env 含明文连接串/密码。检测 git 跟踪状态，已跟踪/未忽略时显式警告。
       if (selectedDb.length > 0) {
-        try {
-          execFileSync('git', ['-C', dir, 'ls-files', '--error-unmatch', path], { stdio: 'pipe' });
+        // QUAL-01 收口：裸 execFileSync → git-helper（-C 由 helper 统一注入）。
+        // 语义映射：ls-files --error-unmatch 命中（exit 0）= 已跟踪 → 警告；
+        // check-ignore -q 命中（exit 0）= 已忽略 → 不警告
+        if (gitQuiet(dir, ['ls-files', '--error-unmatch', path]) !== null) {
           console.warn(chalk.yellow(`  ⚠️ ${path} 已被 git 跟踪——其中数据库连接串/密码会随提交进入仓库，建议加入 .gitignore 或改用环境变量`));
-        } catch {
-          // 未被跟踪：再查是否被 ignore；都不满足（未忽略未跟踪）时提示防止将来误提交
-          try {
-            execFileSync('git', ['-C', dir, 'check-ignore', '-q', path], { stdio: 'pipe' });
-          } catch {
-            console.warn(chalk.yellow(`  ⚠️ ${path} 含数据库连接串/密码且未被 .gitignore 忽略——提交前请先加入 .gitignore 或改用环境变量`));
-          }
+        } else if (gitQuiet(dir, ['check-ignore', '-q', path]) === null) {
+          console.warn(chalk.yellow(`  ⚠️ ${path} 含数据库连接串/密码且未被 .gitignore 忽略——提交前请先加入 .gitignore 或改用环境变量`));
         }
       }
     }

package/src/sillyhub-mcp/client.js

@@ -49,7 +49,6 @@ export class SillyHubMcpClient {
     if (this._url && !/^https:\/\//i.test(this._url) && !/^http:\/\/(localhost|127\.0\.0\.1|\[::1\])(:|\/|$)/i.test(this._url)) {
       console.warn(`[sillyhub-mcp] mcp.url 非 https（${this._url.slice(0, 60)}），Bearer token 将明文传输——请确认为受控环境`);
     }
-    this._token = typeof t === 'string' ? t : '';
     this._timeoutMs = typeof timeoutMs === 'number' && timeoutMs > 0
       ? timeoutMs
       : DEFAULT_TIMEOUT_MS;
@@ -206,6 +205,13 @@ export class SillyHubMcpClient {
     }
 
     if (rpc.error) {
+      // HUB-11：session 过期第二种形态——HTTP 200 + JSON-RPC error -32600「Missing session」
+      // （api-reference 记载的形态；FastMCP 实测走 HTTP 400，两种都认）。落哨兵触发
+      // _sendRpc 重置重连；其余 error 维持 warn+null（如 -32602 Invalid params 是调用侧问题，
+      // 重连救不回，不误触发）
+      if (rpc.error.code === -32600 && /missing session/i.test(String(rpc.error.message || ''))) {
+        return SESSION_EXPIRED;
+      }
       if (!quiet) console.warn(`[sillyhub-mcp] ${tag} JSON-RPC error: ${JSON.stringify(rpc.error)}`);
       return null;
     }
@@ -228,11 +234,8 @@ export class SillyHubMcpClient {
 
   /**
    * MCP initialize 握手：POST initialize → 从响应 header（或 body _meta）读 mcp-session-id。
-   * 成功存 this._sessionId；失败返回 false（best-effort，warn 不抛）。
-   *
-   * 注：协议要求 initialize 后发 notifications/initialized，本客户端只做探测
-   * （tools/list / 只读 tool），实测 FastMCP 不强制该通知即可用（2026-08-14 验证），
-   * 为省一次 RPC 不发；若未来 server 强校验再补。
+   * 成功存 this._sessionId 并补发 notifications/initialized（协议要求；FastMCP 实测不强制，
+   * best-effort 失败仅 warn）；失败返回 false（best-effort，warn 不抛）。
    * @returns {Promise<boolean>}
    */
   async _initialize(quiet = false) {
@@ -299,6 +302,28 @@ export class SillyHubMcpClient {
       return false;
     }
     this._sessionId = sid;
+    // MCP 2025-11-25 协议要求 initialize 后发 notifications/initialized（无 id 通知，server 不回包）。
+    // 2026-08-14 实测 FastMCP v1.29 不强制；补发是为防未来 server 强校验拒掉所有 tools/call。
+    // best-effort：失败仅 warn，不阻断（session 已建，宽松 server 仍可用）。
+    try {
+      const noteController = new AbortController();
+      const noteTimer = setTimeout(() => noteController.abort(), this._timeoutMs);
+      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,
+          'Mcp-Session-Id': this._sessionId,
+        },
+        body: JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized' }),
+        signal: noteController.signal,
+      }).catch(() => { /* best-effort */ });
+      clearTimeout(noteTimer);
+    } catch (err) {
+      if (!quiet) console.warn(`[sillyhub-mcp] notifications/initialized 发送失败（忽略）: ${err && err.message ? err.message : err}`);
+    }
     return true;
   }
 
@@ -387,6 +412,49 @@ export class SillyHubMcpClient {
     return null;
   }
 
+  /**
+   * HUB-12a：tools/list 的完整 result（一次请求同时喂路径A schema 预热与 root_path 越界
+   * 校验——此前 listTools + getRootPath 各发一次同 method 请求，probe 链路重复 RPC）。
+   * best-effort：未配置/失败 → null 不抛。形态：{tools:[...], root_path?} 或裸数组。
+   */
+  async listToolsWithMeta({ quiet = true } = {}) {
+    if (!this._configured) return null;
+    return this._sendRpc('tools/list', {}, { quiet, label: 'tools/list' });
+  }
+
+  /**
+   * HUB-12b：关闭 MCP session（streamable HTTP DELETE，2025-11-25 协议规定的会话终止方式）。
+   * CLI 短进程原本把 session 留给 server TTL 清理；长驻场景（未来 daemon 化）会积累半开
+   * session。best-effort：网络失败/无 session 返回 false 不抛；成功后清本地 session 态，
+   * 后续调用自动重新 initialize。
+   * @returns {Promise<boolean>} 是否发出了有效的 DELETE
+   */
+  async close() {
+    if (!this._configured || !this._sessionId) return false;
+    const sid = this._sessionId;
+    this._sessionId = null; // 先清本地态：DELETE 失败也不留「以为还活着」的 session
+    try {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), this._timeoutMs);
+      try {
+        const res = await fetch(this._endpoint, {
+          method: 'DELETE',
+          headers: {
+            Authorization: `Bearer ${this._token}`,
+            'MCP-Protocol-Version': MCP_PROTOCOL_VERSION,
+            'Mcp-Session-Id': sid,
+          },
+          signal: controller.signal,
+        });
+        return res.ok;
+      } finally {
+        clearTimeout(timer);
+      }
+    } catch {
+      return false;
+    }
+  }
+
   /**
    * best-effort 从 daemon 拿 workspace root_path（task-12 路径A 越界校验用）。
    *

package/src/spec-dir-typo.js

@@ -13,30 +13,9 @@
 
 import { dirname, basename, join } from 'path'
 import { readdirSync } from 'fs'
-
-/**
- * 计算两字符串的 Levenshtein 编辑距离（大小写不敏感比较字符）。
- * @param {string} a
- * @param {string} b
- * @returns {number}
- */
-function levenshtein(a, b) {
-  const m = a.length
-  const n = b.length
-  if (m === 0) return n
-  if (n === 0) return m
-  let prev = Array.from({ length: n + 1 }, (_, j) => j)
-  let curr = new Array(n + 1)
-  for (let i = 1; i <= m; i++) {
-    curr[0] = i
-    for (let j = 1; j <= n; j++) {
-      const cost = a[i - 1].toLowerCase() === b[j - 1].toLowerCase() ? 0 : 1
-      curr[j] = Math.min(prev[j] + 1, curr[j - 1] + 1, prev[j - 1] + cost)
-    }
-    ;[prev, curr] = [curr, prev]
-  }
-  return prev[n]
-}
+// levenshtein 单一实现收敛到 run/shared.js（原本地副本与 shared.js 逐行相同）；
+// shared.js 不静态 import review 族，此处引入不成环
+import { levenshtein } from './run/shared.js'
 
 /**
  * 检测 spec 目录拼写变体。