sillyspec 3.28.3 → 3.28.5

package/src/run/complete.js

@@ -19,6 +19,7 @@
 import { join } from 'node:path'
 import { existsSync, readFileSync, mkdirSync, writeFileSync, appendFileSync } from 'node:fs'
 import { writeAtomicSync } from '../fs-atomic.js'
+import { gitQuiet } from '../git-helper.js'
 import { withFileLock } from '../quicklog.js'
 import { triggerSync, WAIT_MARKER_RE, getStageSteps, formatWaitOptions, resolveRuntimeRoot, getOrCreateMultiRepoContext, resolveChangeDir } from './shared.js'
 
@@ -48,7 +49,6 @@ import { formatExecuteSummary } from '../worktree-apply.js'
 import { validateDecisionModuleRefs } from '../design-facts.js'
 import { isEndToEndTaskText } from '../change-risk-profile.js'
 import { deriveTitleFromLinkedChange } from '../quicklog.js'
-import { gitQuiet } from '../git-helper.js'
 
 // validateMetadata / readDesignScale / validateFileLocations 已迁至 ./gates.js（completeStageGates
 // 共享收尾管线，消除 noAI 末步 / continueStep 完成分支绕过 gate 的 S1/S2/S3 不对称）。
@@ -97,6 +97,26 @@ export function resolveWaitingStepWithAnswer(steps, doneAnswer, nowStr) {
   return waitIdx
 }
 
+/**
+ * 事实性步骤摘要合成（P0-2，noai-ir-roadmap §3）：--output 省略时由 CLI 按既有事实合成
+ * ——步骤名 + 变更窗口（git porcelain 计数与前几个路径）+ 门禁以 CLI 校验输出为准。
+ * 纯事实零编造（无「通过/成功」等判断词——判断在 gate，不在摘要）；语义性说明（方案
+ * 取舍/用户反馈）不合成，摘要自带手写指引。长度控制在 MAX_OUTPUT(200) 截断线内。
+ */
+export function synthesizeStepOutput({ stageName, stepName, cwd }) {
+  let windowNote = ''
+  try {
+    const porcelain = gitQuiet(cwd, ['status', '--porcelain'])
+    if (porcelain !== null) {
+      const paths = porcelain.split('\n').filter(Boolean).map((l) => (l.slice(3) || '').trim()).filter(Boolean)
+      windowNote = paths.length === 0
+        ? '；工作区无未提交变更'
+        : `；变更窗口 ${paths.length} 文件（${paths.slice(0, 3).map((p) => p.split(/[\\/]/).pop()).join('、')}${paths.length > 3 ? ' 等' : ''}）`
+    }
+  } catch { /* git 不可读 → 窗口段缺省（摘要仍成立） */ }
+  return `【CLI 合成】步骤「${stepName}」完成${windowNote}；门禁以本次 CLI 校验输出为准（方案取舍等语义说明需 --output 手写）`
+}
+
 export async function completeStep(pm, progress, stageName, cwd, outputText, inputText = null, options = {}) {
   const { printNext = true, confirm = false, changeName, platformOpts = {}, nonInteractive = false, isForceBaseline = false, isAllowNew = false, isAllowDelete = false, quickFiles = [] } = options
   // specRoot(平台) > specDriftAnchor(worktree 漂移锚定主仓) > cwd/.sillyspec(本地)——
@@ -158,6 +178,16 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
     currentIdx = _resolvedWaitIdx
     console.log(`⚠️  Step "${steps[_resolvedWaitIdx].name}" 此前处于 waiting，--done --answer 已补回答并拉回待完成。`)
   }
+
+  // ── P0-2（noai-ir-roadmap §3）：--output 省略 → CLI 按事实合成步骤摘要 ──
+  // agent 手打摘要是每步命中的幻觉源；事实面（步骤名 + 变更窗口 + 门禁以 CLI 校验为准）
+  // CLI 本就持有，纯事实合成零编造（判断词留给 gate）。语义性说明（方案取舍/用户反馈）仍应
+  // --output 手写——合成摘要自带该指引。quick 阶段除外（末步四字段硬契约
+  // validateQuickResult，合成文本过不了四字段校验；quick 的省略提示由其阶段文案承担）。
+  if (!outputText && stageName !== 'quick' && currentIdx !== -1 && steps[currentIdx]) {
+    outputText = synthesizeStepOutput({ stageName, stepName: steps[currentIdx].name, cwd })
+    console.log(`🤖 --output 未提供——CLI 已按事实合成步骤摘要（gate 校验照常；方案取舍等语义说明下次带 --output 手写）。`)
+  }
   // ── waiting 前置守卫（坑 archive-step3-wait-answer-hint-late）──
   // 普通 --done（无 --answer）时若存在 waiting 步骤：currentIdx 会跳过它推进后续步骤
   //（findIndex 只查 pending/in-progress），步骤被静默越过 + --answer 要求要到别处报错才暴露。
@@ -380,11 +410,59 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
     } else if (_cliAction === 'progressConfirm') {
       // 与 stage.js noAI 分支同语义（brainstorm/execute/verify step1 进度确认）
       executeProgressConfirm({ stageName, cwd, stageData, changeName, pm })
+    } else if (_cliAction === 'verifyRunQualityScan') {
+      // 与 stage.js noAI 分支同语义（P0-1 noai-ir-roadmap §3：verify 测试步实测提前 + 指纹复用；
+      // 失败 throw → completeStep 不推进，步骤保持 pending）
+      const { executeVerifyQualityScan } = await import('./verify-quality-scan.js')
+      await executeVerifyQualityScan({ cwd, specBase, changeName, platformOpts })
+    } else if (_cliAction === 'archiveDistill') {
+      // 与 stage.js noAI 分支同语义（P0-4 安全变体：distill 提炼 CLI 机械执行，needsWait 裁决
+      // 收敛到「确认归档 --confirm」；全路径不抛）
+      const { executeArchiveDistill } = await import('./archive-distill.js')
+      await executeArchiveDistill({ cwd, specBase, changeName })
+    } else if (_cliAction === 'doctorRunDiagnostics') {
+      // 2026-09-09-doctor-noai：与 stage.js 分支同语义（诊断+渲染+落盘）
+      const { runDoctorDiagnostics, renderDoctorSummary, writeDoctorDiagnosis } = await import('../doctor-diagnostics.js')
+      const diag = await runDoctorDiagnostics({ cwd })
+      console.log(renderDoctorSummary(diag))
+      try { writeDoctorDiagnosis(diag, (platformOpts?.specRoot || join(cwd, '.sillyspec'))) } catch { /* 落盘 fail-soft */ }
     } else {
       throw new Error(`noAI 步骤 ${steps[currentIdx].name} 的未知 _cliAction: ${_cliAction}——请在 complete.js 注册对应分支`)
     }
   }
 
+  // ── 并发 --done 防护（坑 execute-concurrent-done-skips-next-wave，2026-09-08 实证）──
+  // 会话 B 先 --done 推进了 Wave N，会话 A 随后的 --done 会落到**新的当前步 = Wave N+1**，
+  // 用 Wave N 的摘要静默完成 Wave N+1（产物未落地却标完成）。CLI 短进程无法读心，两层防护：
+  // ① 醒目前置横幅（邻步 60s 内刚被完成 = 疑似并行会话刚推进）——操作者在看到「✅ Step N
+  //    完成：Wave X」与自己所做不符时可立即 --reopen，不静默；
+  // ② 写前重读校验（本命令读库→落盘窗口内的真实竞态）：重读 DB，若本命令要完成的步骤
+  //    已被并行进程标 completed/skipped，拒绝覆盖式推进（防双写交错把状态机写花）。
+  if (stageName === 'execute' && currentIdx > 0) {
+    const prev = steps[currentIdx - 1]
+    const _prevDoneAgoSec = prev?.completedAt ? Math.round((Date.now() - new Date(prev.completedAt.replace(/(\d{4})\/(\d{2})\/(\d{2})/, '$1-$2-$3')).getTime()) / 1000) : null
+    if (_prevDoneAgoSec !== null && Number.isFinite(_prevDoneAgoSec) && _prevDoneAgoSec >= 0 && _prevDoneAgoSec <= 60) {
+      console.warn('')
+      console.warn(`⚠️ 并发防护：上一步「${prev.name}」${_prevDoneAgoSec}s 前刚被（可能另一会话的）--done 完成——本次将完成的是「${steps[currentIdx].name}」。`)
+      console.warn(`   若与你刚做完的 Wave 不符，立即停手：sillyspec run ${stageName} --reopen --from-step ${currentIdx + 1}${changeName ? ` --change ${changeName}` : ''} 退回本步，勿继续下一 Wave。`)
+      console.warn('')
+    }
+  }
+  let _dupCompletedByPeer = false
+  try {
+    const _fresh = pm.read(cwd, changeName)
+    const _freshSteps = _fresh?.stages?.[stageName]?.steps
+    if (Array.isArray(_freshSteps) && _freshSteps[currentIdx] && _freshSteps[currentIdx].name === steps[currentIdx].name
+        && (_freshSteps[currentIdx].status === 'completed' || _freshSteps[currentIdx].status === 'skipped')) {
+      _dupCompletedByPeer = true
+    }
+  } catch { /* 重读失败（平台模式瞬态等）不阻断——横幅防护仍在 */ }
+  if (_dupCompletedByPeer) {
+    console.error(`❌ 步骤「${steps[currentIdx].name}」刚被并行会话完成（本命令读库后被推进），拒绝重复推进——防把下一步误标完成。`)
+    console.error(`   排查：sillyspec progress show${changeName ? ` --change ${changeName}` : ''} 确认当前步；你若也完成了同一 Wave，无需再次 --done；若要完成的是下一步，重跑 --done（此时它会落在正确的当前步）。`)
+    process.exit(1)
+  }
+
   steps[currentIdx].status = 'completed'
   steps[currentIdx].completedAt = new Date().toLocaleString('zh-CN',{hour12:false})
   if (outputText) {
@@ -400,6 +478,13 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
       mkdirSync(artifactBase, { recursive: true })
       const ts = new Date().toISOString().slice(0,19).replace(/[-T:]/g, '')
       writeFileSync(join(artifactBase, `${changeName || 'unknown'}-${stageName}-step${currentIdx + 1}-${ts}.txt`), outputText)
+      // 写入侧滚动裁剪（runtime-hygiene.js，2026-09-08 系统性回收）：artifacts/ 只写不收，
+      // 实证本仓 534 份累积。文件名时间戳在尾部、前缀是变更名（长变更晚收尾会乱序）→ 按
+      // mtime 排序（write-once 本地审计文件，mtime 可靠）。fail-open 静默。
+      try {
+        const { pruneTimestampedEntries } = await import('../runtime-hygiene.js')
+        pruneTimestampedEntries({ dir: artifactBase, keep: 100, orderBy: 'mtime' })
+      } catch { /* 卫生动作 fail-open */ }
     } else {
       steps[currentIdx].output = outputText
     }
@@ -577,6 +662,10 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
     const total = steps.length
     console.log(`✅ ${stageName} 阶段已完成（${total}/${total} 步）`)
 
+    // task-04（2026-09-10-change-scope-audit）：execute 完成打范围对账全表+落 .runtime 快照 /
+    // verify 完成出一行漂移确认。advisory fail-soft（D-006）——helper 内部全兜，绝不阻断完成。
+    await printStageCompletionScopeAudit({ stageName, cwd, changeName, specBase, platformOpts })
+
     if (stageName === 'execute') {
       // execute run summary：展示真实可得的结构化信息
       try {
@@ -621,6 +710,7 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
       // 走下方 _getNextSuggestion 会因 scan 是 STAGE_ORDER 首位、永未完成而误推 scan（回头路），
       // 与 brainstorm 同类问题（见上注释），故给 quick 专属分支。
       console.log('\n👉 quick 已完成。下一步：提交本次改动（git commit / sillyspec-commit），或 sillyspec run <stage> 继续其他阶段。')
+      console.log('   ⚠️ 多会话共享仓禁目录级 git add / git add -A（会夹带并行会话文件，2026-09-10 实证误删已提交文档）：用显式 pathspec（git add -- 文件…），提交前 git status 核对暂存面。')
     } else {
       // D1 暗衔接修：阶段刚完成，CLI 本就知道状态机下一步是哪个阶段（_getNextSuggestion），
       // 却只丢一句「下一步由你决定」让 agent 自己猜命令。改为按 progress 实际状态给出精确命令。
@@ -684,6 +774,95 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
   return { stageCompleted: false, currentIdx, nextPendingIdx }
 }
 
+// ── 变更范围对账 advisory 注入（2026-09-10-change-scope-audit task-04，FR-03）──
+// execute 完成打全表+落快照、verify 完成出一行漂移确认；completeStep 与 continueStep（wait
+// 解除完成）两路径收敛点同调 printStageCompletionScopeAudit（Grill G-2：单锚 completeStep 会漏
+// wait 解除路径致 verify 假报无快照）。全程 fail-soft（D-006）：任何异常只打单行 ⚠️，不阻断
+// 阶段完成、不进任何门禁判定。scope-audit.js 经动态 import 接入（本文件 runtime-hygiene /
+// design-facts 等同款先例）——只读纯函数模块，模块缓存下零重复加载。
+//   - execute：renderScopeAuditTable 全表（maxRows 60 截断 + 完整表跑 scope-audit 指引 +
+//     ⚠️ 出口指引行——计划外补 design.md 声明或 --output 注明原因，均 renderer 内置）+ 落
+//     .runtime/scope-audit-<change>.json 快照（结构即 ScopeAuditResult + savedAt 落盘时间戳，
+//     只写 .runtime 运行时产物区不动 git 状态）。
+//   - verify：读快照对比文件集差集出一行「变更范围：N 文件 +X/-Y（vs execute 时点：一致|漂移
+//     M 文件：<列表截断>）」。漂移过滤面 = filterDeliverableFiles 结果（resolveReconcileActualFiles
+//     已过、本就保留 docs 子树）再排除 .sillyspec/docs/**——verify 阶段合法文档同步不计漂移
+//     （Grill C-5/P2-②：组合过滤在本侧做，不动 worktree-apply.js 过滤器本体）。快照缺失/降级 →
+//     跳过对比只打当前 totals 一行。
+
+/** 漂移对比排除面：verify 阶段合法文档同步子树（posix 归一后前缀匹配） */
+const SCOPE_DRIFT_EXCLUDE_RE = /^\.sillyspec\/docs\//
+
+/** 快照/当前结果 → 漂移对比用文件集（posix 归一 + docs 子树排除）；畸形结构防御式得空集 */
+function scopeAuditPathSet(result) {
+  const rows = Array.isArray(result?.rows) ? result.rows : []
+  const set = new Set()
+  for (const r of rows) {
+    const p = r && typeof r.path === 'string' ? r.path.replace(/\\/g, '/') : ''
+    if (p && !SCOPE_DRIFT_EXCLUDE_RE.test(p)) set.add(p)
+  }
+  return set
+}
+
+/** execute 完成路径：全表 + 快照落盘（快照写失败只提示，verify 对比按无快照降级） */
+async function printExecuteScopeAudit({ cwd, changeName, specBase, platformOpts, computeChangeScopeAudit, renderScopeAuditTable }) {
+  const result = await computeChangeScopeAudit({ cwd, specBase, changeName, platformOpts })
+  console.log(`\n${renderScopeAuditTable(result, { maxRows: 60 })}`)
+  try {
+    const runtimeRoot = resolveRuntimeRoot(platformOpts, specBase)
+    const snapPath = join(runtimeRoot, `scope-audit-${changeName}.json`)
+    mkdirSync(runtimeRoot, { recursive: true })
+    writeFileSync(snapPath, JSON.stringify({ ...result, savedAt: new Date().toISOString() }, null, 2) + '\n')
+  } catch (e) {
+    console.warn(`   ⚠️ 范围对账快照写入失败（不阻断，verify 漂移对比将按无快照降级）：${e && e.message ? String(e.message).split('\n')[0] : e}`)
+  }
+}
+
+/** verify 完成路径：读 execute 时点快照对比文件集差集，一行结论（行数不比——execute 形态 A 锚
+ *  worktree meta、verify 形态 B 锚 merge-base，基点不同行数天然抖动，比行数必假阳） */
+async function printVerifyScopeDrift({ cwd, changeName, specBase, platformOpts, computeChangeScopeAudit }) {
+  const result = await computeChangeScopeAudit({ cwd, specBase, changeName, platformOpts })
+  const totals = result?.totals && typeof result.totals === 'object' ? result.totals : {}
+  const scopeLine = `变更范围：${totals.files ?? (Array.isArray(result?.rows) ? result.rows.length : 0)} 文件 +${totals.additions ?? 0}/-${totals.deletions ?? 0}`
+  if (result?.ok !== true) {
+    console.log(`   ⚠️ ${scopeLine}（对账降级：${result?.degradedReason || '实际侧文件集解析失败'}——advisory，不影响 verify 完成）`)
+    return
+  }
+  let snapshot = null
+  try {
+    snapshot = JSON.parse(readFileSync(join(resolveRuntimeRoot(platformOpts, specBase), `scope-audit-${changeName}.json`), 'utf8'))
+  } catch { /* 快照缺失/损坏 → 跳过对比只打当前 totals */ }
+  if (!snapshot || snapshot.ok !== true) {
+    console.log(`   ${scopeLine}（无 execute 时点快照可对比——完整表跑 sillyspec scope-audit --change ${changeName}）`)
+    return
+  }
+  const current = scopeAuditPathSet(result)
+  const baseline = scopeAuditPathSet(snapshot)
+  const drift = [...new Set([...current, ...baseline])].filter(p => current.has(p) !== baseline.has(p)).sort()
+  if (drift.length === 0) {
+    console.log(`   ${scopeLine}（vs execute 时点：一致）`)
+  } else {
+    const shown = drift.slice(0, 5).join(', ')
+    const tail = drift.length > 5 ? ` 等 ${drift.length} 个` : ''
+    console.log(`   ${scopeLine}（vs execute 时点：漂移 ${drift.length} 文件：${shown}${tail}——advisory 不阻断，请确认 verify 期改动并按需补 design.md 声明）`)
+  }
+}
+
+/** 两完成路径公共入口（stage 派发 + 动态 import + fail-soft 兜底，D-006） */
+async function printStageCompletionScopeAudit({ stageName, cwd, changeName, specBase, platformOpts }) {
+  try {
+    if (!changeName || (stageName !== 'execute' && stageName !== 'verify')) return
+    const { computeChangeScopeAudit, renderScopeAuditTable } = await import('../scope-audit.js')
+    if (stageName === 'execute') {
+      await printExecuteScopeAudit({ cwd, changeName, specBase, platformOpts, computeChangeScopeAudit, renderScopeAuditTable })
+    } else {
+      await printVerifyScopeDrift({ cwd, changeName, specBase, platformOpts, computeChangeScopeAudit })
+    }
+  } catch (e) {
+    console.warn(`⚠️ 变更范围对账输出异常（advisory，不阻断 ${stageName} 阶段完成）：${e && e.message ? String(e.message).split('\n')[0] : e}`)
+  }
+}
+
 // ── Step 调度兄弟函数（W6 Step7b-2 从 run.js 搬入：skip/wait/continue + formatWaitHistory）──
 /**
  * plan.md checkbox 自动勾选：execute 完成 + 各 task review.json 双 verdict 非 fail → 自动勾选。
@@ -813,7 +992,7 @@ export function shouldAutoCheckTask(r, endToEnd, ctx = null) {
 
   return true
 }
-async function autoCheckPlanFromReviews({ stageName, changeName, cwd, platformOpts }) {
+export async function autoCheckPlanFromReviews({ stageName, changeName, cwd, platformOpts }) {
   if (stageName !== 'execute' || !changeName) {
     return { autoChecked: false, checkedCount: 0, skippedCount: 0 }
   }
@@ -1292,6 +1471,9 @@ export async function continueStep(pm, progress, stageName, cwd, answer, options
     // gate 全过：persist completed（task-03 移后；此处无 triggerSync）。
     pm._write(cwd, progress, changeName)
     console.log(`\n✅ ${stageName} 阶段已完成（${stageData.steps.length}/${stageData.steps.length} 步）`)
+    // task-04：wait 解除完成路径与 completeStep 完成分支同源注入（Grill G-2：本路径不漏，
+    // 否则 execute 快照缺失 → verify 假报「无快照可对比」）。
+    await printStageCompletionScopeAudit({ stageName, cwd, changeName, specBase, platformOpts })
     // 阶段完成后明确下一步（agent 常卡：stageData completed 但不知要 run <下一阶段> 推进 currentStage）
     const nextStageHint = { brainstorm: 'plan', plan: 'execute', execute: 'verify', verify: 'archive' }[stageName]
     if (nextStageHint) {

package/src/run/gate-snapshot.js

@@ -0,0 +1,88 @@
+/**
+ * gate-snapshot.js — quick --done test+lint 门禁的隔离快照执行（2026-09-10 驾驭小结第六批②，
+ * 用户实证「lint 实测对账在主仓跑，被并行会话的脏文件拦门」）。
+ *
+ * 问题：门禁在主仓工作区跑 commands.test/lint——多会话共享仓里并行会话的未提交 src/test
+ * 改动（语法错误/半成品/锚漂）会污染实测结果，把无辜会话的 --done 拦在门上（只能走
+ * advisory 逃生口）。
+ *
+ * 修法：HEAD 干净快照 + 会话文件 overlay——`git worktree add --detach <tmp> HEAD` 取干净
+ * 基线（并行脏文件天然不在），把本会话审计/声明的变更文件覆盖进快照，node_modules 经
+ * junction 复用主仓依赖（零拷贝），local.yaml 从主仓复制（gitignore 不进 HEAD），在快照
+ * cwd 跑对账。快照基建任何失败 → 返回 null，调用方回退主仓现行为（零回归兜底）。
+ *
+ * 快照生命周期：一次门禁一批（create → run → cleanup）；崩溃残留由 git worktree prune /
+ * 临时目录自然回收（OS tmp 清理），不进主仓 .runtime。
+ */
+import { execFileSync } from 'node:child_process'
+import { mkdtempSync, mkdirSync, copyFileSync, writeFileSync, rmSync, existsSync, readdirSync, statSync, symlinkSync, readFileSync } from 'node:fs'
+import { join, dirname, relative, resolve } from 'node:path'
+import { tmpdir } from 'node:os'
+
+function git(cwd, args) {
+  return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 60000 }).trim()
+}
+
+/**
+ * 创建隔离快照：HEAD worktree + 会话文件 overlay + node_modules junction + local.yaml。
+ * @param {{ cwd: string, files: string[] }} opts cwd=主仓根；files=本会话变更文件（仓库根相对 POSIX）
+ * @returns {{ snapshotRoot: string, cleanup: () => void, reason?: string }|null} 失败返回 null（调用方回退主仓）
+ */
+export function createGateSnapshot({ cwd, files }) {
+  let snapshotRoot = null
+  try {
+    // 前置：主仓须是 git 仓且有 HEAD（无 git 环境回退主仓现行为）
+    git(cwd, ['rev-parse', 'HEAD'])
+
+    snapshotRoot = mkdtempSync(join(tmpdir(), 'sillyspec-gate-'))
+    git(cwd, ['worktree', 'add', '--detach', '--quiet', snapshotRoot, 'HEAD'])
+
+    // 会话文件 overlay：主仓工作区版本覆盖进快照（本会话的最新态；文件不存在=已删，跳过）。
+    // .sillyspec/ 跳过面收窄（P2-d 落地实证的快照盲区）：原一刀切跳过整个 .sillyspec/ ——
+    // 会话声明的 tracked docs（module-map 补录/知识库/模块卡）进不了快照，门禁读到 HEAD
+    // 旧版恒误报（src 未录 module-map 的修复在主仓生效、快照里仍然失败）。真正需要隔离的
+    // 是共享运行时面：.runtime/（sqlite 锁/在途 marker）与 quicklog/（跨会话共享账本）；
+    // local.yaml 由下方 cfg 段显式复制（单一来源，不经 overlay）。
+    let overlaid = 0
+    for (const f of files) {
+      const isSillyspecRuntime = typeof f === 'string' && (f.startsWith('.sillyspec/.runtime/') || f.startsWith('.sillyspec/quicklog/') || f === '.sillyspec/local.yaml' || f === '.sillyspec/.sillyspec-platform.json')
+      if (typeof f !== 'string' || f.includes('..') || f.startsWith('/') || isSillyspecRuntime) continue
+      const src = join(cwd, f)
+      if (!existsSync(src)) continue
+      const dst = join(snapshotRoot, f)
+      mkdirSync(dirname(dst), { recursive: true })
+      copyFileSync(src, dst)
+      overlaid++
+    }
+
+    // node_modules junction（依赖主仓安装态；junction Windows 无需特权，POSIX 用 symlink）
+    const nmSrc = join(cwd, 'node_modules')
+    if (existsSync(nmSrc)) {
+      try { symlinkSync(nmSrc, join(snapshotRoot, 'node_modules'), 'junction') }
+      catch { /* 依赖链接失败：test/lint 可能跑不起来 → 仍返回快照，命令层报错走 fallback */ }
+    }
+
+    // local.yaml（gitignore 不进 HEAD；门禁命令配置来源）+ package-lock 保持 HEAD 版（npm test 不装新依赖）
+    for (const cfg of [join('.sillyspec', 'local.yaml')]) {
+      const src = join(cwd, cfg)
+      if (existsSync(src)) {
+        mkdirSync(dirname(join(snapshotRoot, cfg)), { recursive: true })
+        copyFileSync(src, join(snapshotRoot, cfg))
+      }
+    }
+
+    const cleanup = () => {
+      try { git(cwd, ['worktree', 'remove', '--force', '--quiet', snapshotRoot]) } catch {
+        try { rmSync(snapshotRoot, { recursive: true, force: true }) } catch { /* 残留交 OS tmp 清理 */ }
+      }
+    }
+    return { snapshotRoot, cleanup, overlaid }
+  } catch (e) {
+    // 基建失败（worktree add 拒绝/磁盘满/…）：尽力清理后回退主仓
+    if (snapshotRoot) {
+      try { git(cwd, ['worktree', 'remove', '--force', '--quiet', snapshotRoot]) } catch {}
+      try { rmSync(snapshotRoot, { recursive: true, force: true }) } catch {}
+    }
+    return null
+  }
+}