sillyspec 3.29.5 → 3.31.0

package/src/run/gate-snapshot-ledger.js

@@ -0,0 +1,213 @@
+/**
+ * gate-snapshot-ledger.js — 门禁隔离快照的生命周期账本与陈旧回收
+ * （2026-09-24-gate-snapshot-lifecycle，task-01；D-003@v2 / D-004@v2 / D-005@v1）
+ *
+ * 存在理由：门禁快照（%TEMP%/sillyspec-gate-*，src/run/gate-snapshot.js 建、quick/verify
+ * 门 finally 清）在三条路径必然泄漏——进程被杀（cleanup 根本没跑）、Windows rmSync 无重试
+ * 遇 EPERM/junction 锁、git worktree remove 失败留 prunable 注册。实证攒到 41 个目录+2 个
+ * prunable 注册且全仓无清扫机制。本模块提供：
+ *   ①账本（create 登记 / cleanup 销账，幂等原子写）——崩溃残留的可追踪凭据；
+ *   ②路径与条目 fail-closed 守卫——账本是可变 JSON，删除原语调用前必过（D-005@v1）；
+ *   ③TTL×pid 三态保守判定（D-003@v2）与「目录+worktree 注册双清」回收执行（D-004@v2）：
+ *     双清确认才销号——删不掉的残留必须留在账本里等下一轮，否则永久失追踪。
+ *
+ * 信任边界：删除原语仅由本模块的回收路径调用，且每个条目先过 isSafeLedgerEntry；
+ * gate-snapshot.js 自身 cleanup 的 root 来自 mkdtemp（生成即受信）不经过账本。
+ * 异常面：全部 fail-open 吞掉（账本/回收任一异常零阻断，退现状残留）。
+ */
+import { execFileSync } from 'node:child_process'
+import { existsSync, mkdirSync, readFileSync } from 'node:fs'
+import { basename, dirname, join, resolve, sep } from 'node:path'
+import { tmpdir } from 'node:os'
+import { writeAtomicSync } from '../fs-atomic.js'
+import { safeRemoveDirWithLinks, unlinkLinkPath, collectLinkPathsUnder } from './junction-rm.js'
+
+const LEDGER_FILE = 'active-gate-snapshots.json'
+const HOUR_MS = 3600_000
+const STALE_HOURS_DEFAULT = 24
+
+/** 账本文件路径（runtime 域：.sillyspec/.runtime/active-gate-snapshots.json） */
+export function gateSnapshotLedgerPath(runtimeRoot) {
+  return join(runtimeRoot, LEDGER_FILE)
+}
+
+/** 读账本（损坏/缺失/非数组 → 空数组，fail-open） */
+export function readGateSnapshotLedger(runtimeRoot) {
+  if (!runtimeRoot) return []
+  try {
+    const p = gateSnapshotLedgerPath(runtimeRoot)
+    if (!existsSync(p)) return []
+    const data = JSON.parse(readFileSync(p, 'utf8'))
+    if (!Array.isArray(data)) return []
+    return data.filter((e) => e && typeof e === 'object' && typeof e.snapshotRoot === 'string')
+  } catch {
+    return []
+  }
+}
+
+function writeLedger(runtimeRoot, entries) {
+  mkdirSync(runtimeRoot, { recursive: true })
+  writeAtomicSync(gateSnapshotLedgerPath(runtimeRoot), JSON.stringify(entries, null, 2))
+}
+
+/** 登记快照（幂等：同 root 重复调用不追加；runtimeRoot 缺失退 no-op） */
+export function registerGateSnapshot({ runtimeRoot, snapshotRoot, pid = process.pid }) {
+  if (!runtimeRoot || !snapshotRoot) return
+  try {
+    const entries = readGateSnapshotLedger(runtimeRoot)
+    if (entries.some((e) => e.snapshotRoot === snapshotRoot)) return
+    entries.push({ snapshotRoot, pid, createdAt: Date.now() })
+    writeLedger(runtimeRoot, entries)
+  } catch { /* fail-open：登记失败仅退化为残留不可追踪，不阻断门禁 */ }
+}
+
+/** 销账（幂等：缺失不抛；调用方负责先确认双清——本函数不判目录/注册状态） */
+export function unregisterGateSnapshot({ runtimeRoot, snapshotRoot }) {
+  if (!runtimeRoot || !snapshotRoot) return
+  try {
+    const entries = readGateSnapshotLedger(runtimeRoot)
+    const next = entries.filter((e) => e.snapshotRoot !== snapshotRoot)
+    if (next.length === entries.length) return
+    writeLedger(runtimeRoot, next)
+  } catch { /* fail-open：销账失败保留条目，下轮重试 */ }
+}
+
+/**
+ * 路径守卫（D-005@v1）：必须是 tmpdir 的**直接子目录**且 basename 严格匹配
+ * sillyspec-gate-* ——账本可被篡改，删除原语调用前唯一路径闸门。
+ */
+export function isSafeSnapshotRoot(snapshotRoot, { tmpBase = tmpdir() } = {}) {
+  if (typeof snapshotRoot !== 'string' || !snapshotRoot) return false
+  if (snapshotRoot.includes('..')) return false
+  // 路径比较口径：win32 不区分大小写（TEMP/TMP 跨进程大小写漂移会让合法残留永不满足守卫）
+  const fold = (p) => (process.platform === 'win32' ? p.toLowerCase() : p)
+  const norm = resolve(snapshotRoot)
+  if (fold(dirname(norm)) !== fold(resolve(tmpBase))) return false
+  return /^sillyspec-gate-/.test(basename(norm))
+}
+
+/** 条目结构守卫：根过路径守卫 ∧ pid 正整数 ∧ createdAt 有限毫秒值 */
+export function isSafeLedgerEntry(entry, opts) {
+  return !!entry
+    && isSafeSnapshotRoot(entry.snapshotRoot, opts)
+    && Number.isInteger(entry.pid) && entry.pid > 0
+    && Number.isFinite(entry.createdAt)
+}
+
+/** staleHours 值域：非有限/非正 → 回退 24h（D-003@v2 单一入口） */
+export function resolveStaleHours(value = process.env.SILLYSPEC_GATE_SNAPSHOT_STALE_HOURS) {
+  const n = Number(value)
+  return Number.isFinite(n) && n > 0 ? n : STALE_HOURS_DEFAULT
+}
+
+/**
+ * pid 活性三态（D-003@v2，破坏性场景从严）：成功/EPERM=活，ESRCH=死，
+ * 无效 pid/其他异常=按活跳过。与 bg-sync 终止扫描口径（无效 pid 按死）有意分歧——
+ * 那边误判代价=进程残留，这边误判代价=删掉活跃快照目录。
+ */
+function defaultIsProcessAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return true
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (e) {
+    return !(e && e.code === 'ESRCH')
+  }
+}
+
+/**
+ * 纯判定：守卫 ∧ 超 TTL ∧ 明确死 三合取才 stale；其余（未超期/存活/守卫不过/
+ * 异常）一律保留。staleHours 非法值回退 24h。
+ */
+export function selectStaleSnapshots(entries, { now = Date.now(), staleHours, isProcessAlive = defaultIsProcessAlive } = {}) {
+  const hours = resolveStaleHours(staleHours)
+  const probe = typeof isProcessAlive === 'function' ? isProcessAlive : defaultIsProcessAlive
+  const stale = []
+  const alive = []
+  for (const e of Array.isArray(entries) ? entries : []) {
+    if (!isSafeLedgerEntry(e)) { alive.push(e); continue }
+    if ((now - e.createdAt) / HOUR_MS <= hours) { alive.push(e); continue }
+    let isAlive
+    try { isAlive = !!probe(e.pid) } catch { isAlive = true }
+    if (isAlive) { alive.push(e); continue }
+    stale.push(e)
+  }
+  return { stale, alive }
+}
+
+function defaultRunGit(cwd, args) {
+  return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 60000, windowsHide: true }).trim()
+}
+
+function defaultRemoveDir(p) {
+  // junction 安全删除（坑 junction-pierce-rm-sync，2026-09-24 实证）：残留快照内
+  // node_modules/venv junction 的目标是主仓真身，裸 rmSync(recursive) 穿透链接清空目标
+  // （收口期三次实证）——删前先解链（junction-rm.js 单一实现）；解链失败抛错由调用方
+  // 按「删不掉保留条目待下轮」处置，绝不回落裸 rmSync。
+  safeRemoveDirWithLinks(p, { maxRetries: 5, retryDelay: 100 })
+}
+
+/** worktree 注册是否仍登记该 root（跨平台路径归一 + win32 大小写不敏感） */
+function defaultWorktreeRegistered(cwd, snapshotRoot) {
+  const out = defaultRunGit(cwd, ['worktree', 'list', '--porcelain'])
+  const norm = (s) => {
+    const v = String(s).replace(/\\/g, '/')
+    return process.platform === 'win32' ? v.toLowerCase() : v
+  }
+  const target = norm(snapshotRoot)
+  return out.split('\n').some((line) => line.startsWith('worktree ') && norm(line.slice('worktree '.length)) === target)
+}
+
+/**
+ * 回收执行（D-004@v2）：逐条 remove → rmSync（remove 失败补 prune），双清确认
+ * （目录不存在 ∧ worktree list 无注册）才销号；删不掉的计入 skipped 保留条目。
+ * 返回 {reclaimed, skipped}；异常全吞退零副作用。
+ */
+export function reclaimStaleGateSnapshots({
+  runtimeRoot,
+  cwd,
+  now = Date.now(),
+  staleHours,
+  isProcessAlive = defaultIsProcessAlive,
+  runGit = defaultRunGit,
+  removeDir = defaultRemoveDir,
+  worktreeRegistered = defaultWorktreeRegistered,
+} = {}) {
+  if (!runtimeRoot || !cwd) return { reclaimed: [], skipped: [] }
+  try {
+    const { stale } = selectStaleSnapshots(readGateSnapshotLedger(runtimeRoot), { now, staleHours, isProcessAlive })
+    const reclaimed = []
+    const skipped = []
+    for (const e of stale) {
+      const root = e.snapshotRoot
+      let removeFailed = false
+      // 先解链（坑 git-worktree-remove-pierce，2026-09-24 实证：git worktree remove --force
+      // 在 Windows 跟随 junction 删主仓真身内容——残留快照内 node_modules/venv/copy 链接必须
+      // 先解链再删。解链失败按删不掉处置：保留条目待下轮，绝不带着链接跑删除）。
+      let linksCleared = true
+      try {
+        for (const link of collectLinkPathsUnder(root)) unlinkLinkPath(link)
+      } catch { linksCleared = false }
+      if (linksCleared) {
+        try { runGit(cwd, ['worktree', 'remove', '--force', root]) } catch { removeFailed = true }
+        try { removeDir(root) } catch { /* 目录删不掉→下方双清判定保留条目 */ }
+      } else {
+        removeFailed = true
+      }
+      if (removeFailed) { try { runGit(cwd, ['worktree', 'prune']) } catch { /* prune 失败→下方判定保留 */ } }
+      let dirGone = false
+      let regGone = false
+      try { dirGone = !existsSync(root) } catch { dirGone = false }
+      try { regGone = !worktreeRegistered(cwd, root) } catch { regGone = false }
+      if (dirGone && regGone) {
+        unregisterGateSnapshot({ runtimeRoot, snapshotRoot: root })
+        reclaimed.push(root)
+      } else {
+        skipped.push(root)
+      }
+    }
+    return { reclaimed, skipped }
+  } catch {
+    return { reclaimed: [], skipped: [] }
+  }
+}

package/src/run/gate-snapshot.js

@@ -11,16 +11,103 @@
  * junction 复用主仓依赖（零拷贝），local.yaml 从主仓复制（gitignore 不进 HEAD），在快照
  * cwd 跑对账。快照基建任何失败 → 返回 null，调用方回退主仓现行为（零回归兜底）。
  *
- * 快照生命周期：一次门禁一批（create → run → cleanup）；崩溃残留由 git worktree prune /
- * 临时目录自然回收（OS tmp 清理），不进主仓 .runtime。
+ * 快照生命周期：一次门禁一批（create → run → cleanup）；崩溃残留（进程被杀时 cleanup
+ * 不跑）由账本回收路径兜底——gate-snapshot-ledger.js 登记 create、cleanup 双清确认后销账，
+ * 下个门禁建快照前按 TTL×pid 双闸自愈回收（账本落 runtime 域 .sillyspec/.runtime/，
+ * 不进 git 不上平台）。
  */
 import { execFileSync, spawnSync } 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 { mkdtempSync, mkdirSync, copyFileSync, writeFileSync, existsSync, readdirSync, statSync, symlinkSync, readFileSync } from 'node:fs'
+import { join, dirname, relative, resolve, isAbsolute } from 'node:path'
 import { tmpdir } from 'node:os'
+import { registerGateSnapshot, unregisterGateSnapshot, reclaimStaleGateSnapshots } from './gate-snapshot-ledger.js'
+import { safeRemoveDirWithLinks, unlinkLinkPath, collectLinkPathsUnder } from './junction-rm.js'
+
+/**
+ * worktree 会话跳快照判定（2026-09-23 R9/R10 双实证根治）：cwd 位于 sillyspec 会话专属
+ * execute worktree（.sillyspec/.runtime/worktrees/<change>）时，隔离快照的立命之本——
+ * 「主仓共享工作区并行会话脏文件不污染本会话门禁」——天然不成立问题不存在：worktree
+ * 本身就是单会话独占的隔离环境。而快照在此场景只剩纯成本：venv/node_modules junction
+ * 冻结与慢 I/O 面（R9 3MB/0CPU 冻结、R10 15min 慢跑均出自 Temp 快照内）、快照构建时延、
+ * 双层 overlay。跳过 = 直接在 worktree cwd 实测（口径与主仓 fallback 同构）。
+ * 判定（跨平台）：路径分隔符先归一为 /，再匹配 /.sillyspec/.runtime/worktrees/<name>。
+ */
+export function shouldSkipGateSnapshotForWorktree(cwd) {
+  const p = String(cwd || '').replace(/\\/g, '/')
+  return /\/\.sillyspec\/\.runtime\/worktrees\/[^/]+/.test(p)
+}
 
 function git(cwd, args) {
-  return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 60000 }).trim()
+  return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 60000, windowsHide: true }).trim()
+}
+
+/** worktree 注册是否仍登记该 root（跨平台路径归一 + win32 大小写不敏感） */
+function worktreeListContains(cwd, snapshotRoot) {
+  const out = git(cwd, ['worktree', 'list', '--porcelain'])
+  const norm = (s) => {
+    const v = String(s).replace(/\\/g, '/')
+    return process.platform === 'win32' ? v.toLowerCase() : v
+  }
+  const target = norm(snapshotRoot)
+  return out.split('\n').some((line) => line.startsWith('worktree ') && norm(line.slice('worktree '.length)) === target)
+}
+
+/**
+ * 快照目录 + worktree 注册的清理体（2026-09-24-gate-snapshot-lifecycle task-02，FR-02）——
+ * Windows 硬化：rmSync 带重试（EPERM/junction 锁是本次 41 个残留目录的实证成因），
+ * worktree remove 失败后补 prune 清 prunable 注册（本次实证 2 条）。
+ * git/删目录/存在性判定的依赖均可注入（故障注入测试见 test/gate-snapshot-cleanup.test.mjs）。
+ * 返回双清结果供调用方决定账本销账（D-004@v2）；全失败不抛（fail-open）。
+ */
+const REMOVE_DIR_RETRY = { maxRetries: 5, retryDelay: 100 }
+
+export function cleanupSnapshot({
+  snapshotRoot,
+  cwd,
+  runGit = (c, a) => git(c, a),
+  // junction 安全删除（坑 git-worktree-remove-pierce，2026-09-24 实证）：`git worktree remove
+  // --force` 的递归删在 Windows **跟随 junction 删目标内容**（实测 victim 复现；worktree.js
+  // cleanup 链的 unlinkNodeModulesLinks 先解链正是防它）——快照内 node_modules/venv/copy 面/
+  // 钉定缓存链接全部指向主仓真身，必须**先解链再交给 git/rmSync 删目录本体**。解链失败 →
+  // 保护性放弃本次删除（目录留账本待回收——双清契约天然兼容）。
+  removeDir = (p, opts) => safeRemoveDirWithLinks(p, opts),
+  dirExists = (p) => existsSync(p),
+  worktreeRegistered = (c, p) => worktreeListContains(c, p),
+}) {
+  let worktreeCleaned = true
+  // 0. 先解链快照内全部 junction/reparse 点（含深层：venv 族与 gate_snapshot.copy 面在
+  //    子目录层）。解链失败不删目录（穿透风险下，保护主仓优先于清理彻底性）。
+  let linksCleared = true
+  try {
+    for (const link of collectLinkPathsUnder(snapshotRoot)) unlinkLinkPath(link)
+  } catch (e) {
+    linksCleared = false
+    console.warn(`⚠️ 快照 junction 解链失败（保护主仓链接目标，本次不删快照目录——条目留账本待下轮回收）: ${e && e.message ? e.message : e}`)
+  }
+  if (linksCleared) {
+    // 注：worktree remove/prune 无 --quiet 选项（非法 flag 会必抛并被 catch 吞掉——旧实现
+    // 正是因此让 git remove 每次都失败、只剩无重试 rmSync 兜底，41 个残留目录的根因之一）
+    try {
+      runGit(cwd, ['worktree', 'remove', '--force', snapshotRoot])
+    } catch {
+      worktreeCleaned = false
+    }
+  } else {
+    worktreeCleaned = false
+  }
+  let dirRemoved = !dirExists(snapshotRoot)
+  if (linksCleared && !dirRemoved) {
+    try { removeDir(snapshotRoot, REMOVE_DIR_RETRY) } catch { /* 删不掉→下方按实际存在性判定 */ }
+    dirRemoved = !dirExists(snapshotRoot)
+  }
+  if (!worktreeCleaned) {
+    // remove 失败：prune 清掉「目录已不在但注册悬空」的 prunable 条目
+    try { runGit(cwd, ['worktree', 'prune']) } catch { /* prune 失败→下方复核 */ }
+  }
+  // 双清契约（D-004@v2）：worktreeCleaned 只认 git worktree list 的确认答复——remove 退出码
+  // 为零不等于注册已清（prune 未生效或 list 仍含该 root 时仍可能残留）。查询异常按未清。
+  try { worktreeCleaned = !worktreeRegistered(cwd, snapshotRoot) } catch { worktreeCleaned = false }
+  return { dirRemoved, worktreeCleaned }
 }
 
 /**
@@ -50,7 +137,7 @@ function runOverlayImportSmoke(pythonBin, snapshotRoot, overlaidFiles) {
     let acted = false
     for (const f of overlaidFiles) {
       if (reverted.has(f)) continue
-      const bad = smokeImportPython(pythonBin, snapshotRoot, f)
+      const bad = smokeImportPython(pythonBin, snapshotRoot, f, byModule)
       if (!bad) continue
       acted = true
       // 依赖归因：报错点名另一 overlay 文件 → 回退依赖（ importer 自身往往无恙）
@@ -82,32 +169,66 @@ function findSnapshotPython(envRelDirs, snapshotRoot) {
 }
 
 /**
- * 单文件 import 冒烟：`python -c "import <mod>"`，cwd 取该文件所在包根（模块路径按
- * 目录结构推导：剥 .py、/→.、丢 __init__；相对包根 import）。非 0 退出且 stderr 命中
- * ImportError/ModuleNotFoundError/SyntaxError 才判坏（其余失败如缺第三方依赖是环境问题，
- * 不回退——回退语义只针对「部分态坏文件」）。超时 10s 防挂。
+ * 单文件 import 冒烟：`python -c "import <mod>"`，包根从浅到深全尝试后才定性。
+ *
+ * 坑 verify-gate-worktree-crossrepo-three-defects 缺陷一（2026-09-21 实证）：旧实现首个
+ * import-class 错误立即判坏——浅根（快照根）下 `No module named 'backend'`（backend 不是
+ * 快照根顶层包，包根本就该在 backend/）属 **cwd 假阳性**，却触发交付文件被回退 HEAD →
+ * 快照内丢 stats() 等新增 → 模块子集 AttributeError 连环假红。
+ *
+ * 定性规则（全根耗尽后）：
+ *   - 任一根 import 成功 → 文件健康（null）；
+ *   - SyntaxError → 立即判坏（语法坏与包根无关）；
+ *   - `cannot import name X`（模块已解析、缺名）→ 判坏（真部分态，根无关）；
+ *   - `ModuleNotFoundError: No module named 'X'` → 仅当 X 末段映射到**另一 overlay .py**
+ *     （byModule）才判坏（overlay 依赖缺失）；第三方依赖缺失/浅根前缀 → 环境问题不判坏
+ *     （回退语义只针对「部分态坏文件」，坑原文口径）。
+ *
+ * @param {string} pythonBin 解释器
+ * @param {string} snapshotRoot 快照根
+ * @param {string} relFile overlay 文件（仓库根相对 POSIX）
+ * @param {Map<string,string>} byModule 末段模块名 → overlay 文件（缺失归因用）
  * @returns {string|null} 失败原因（判坏时）；通过/环境性失败返回 null
  */
-function smokeImportPython(pythonBin, snapshotRoot, relFile) {
+function smokeImportPython(pythonBin, snapshotRoot, relFile, byModule) {
   const noExt = relFile.replace(/\.py$/, '')
   const parts = noExt.split('/')
   while (parts.length > 0 && parts[parts.length - 1] === '__init__') parts.pop()
   if (parts.length === 0) return null
-  // 包根推导：从深到浅尝试（backend/app/x/y.py → 先 app.x.y（cwd=backend）再 x.y（cwd=backend/app））
+  let nameErr = null
+  let missingOverlayErr = null
   for (let cut = 0; cut < parts.length; cut++) {
     const mod = parts.slice(cut).join('.')
     if (!mod || !/^[A-Za-z_][\w.]*$/.test(mod)) continue
     const pkgRoot = join(snapshotRoot, ...parts.slice(0, cut))
     const r = spawnSync(pythonBin, ['-c', `import ${mod}`], {
-      cwd: pkgRoot, encoding: 'utf-8', timeout: 10_000,
+      cwd: pkgRoot, encoding: 'utf-8', timeout: 10_000, windowsHide: true,
     })
     if (r.status === 0) return null
     const err = String((r.stderr || '') + (r.stdout || ''))
-    if (/ImportError|ModuleNotFoundError|SyntaxError|cannot import name/i.test(err)) {
-      return (err.match(/(?:ImportError|ModuleNotFoundError|SyntaxError|cannot import name)[^\n]*/) || ['import 失败'])[0].slice(0, 120)
+    if (/SyntaxError/i.test(err)) {
+      // 语法坏与包根无关：该文件任何根下都不可导入，立即判坏
+      return (err.match(/SyntaxError[^\n]*/) || ['语法错误'])[0].slice(0, 120)
+    }
+    if (/cannot import name/i.test(err)) {
+      // 模块已解析、缺名 = 真部分态（依赖 overlay 兄弟缺符号）；记录，全根耗尽后判坏
+      if (!nameErr) nameErr = (err.match(/cannot import name[^\n]*/) || ['cannot import name'])[0].slice(0, 120)
+      continue
+    }
+    const mnf = err.match(/ModuleNotFoundError: No module named '([A-Za-z_][\w.]*)'/)
+    if (mnf) {
+      const missingLast = mnf[1].split('.').pop()
+      if (byModule.has(missingLast)) {
+        // 缺的模块是 overlay 兄弟（如 crud.py 未进快照）→ 部分态候选，记录
+        if (!missingOverlayErr) missingOverlayErr = (err.match(/ModuleNotFoundError[^\n]*/) || ['module not found'])[0].slice(0, 120)
+      }
+      // else：第三方依赖缺失 / 浅根前缀（cwd 假阳性）→ 环境问题，继续试更深包根
+      continue
     }
-    // 环境性失败（如缺第三方依赖、非模块入口冲突）→ 不判坏，继续试更浅包根
+    // 其余失败（超时/崩溃等）→ 环境性，继续
   }
+  if (nameErr) return nameErr
+  if (missingOverlayErr) return missingOverlayErr
   return null
 }
 
@@ -240,7 +361,7 @@ export function runGateSnapshotCommands(snapshotRoot, commands) {
     ran++
     let r = null
     try {
-      r = spawnSync(cmd, { shell: true, cwd: snapshotRoot, timeout: 300_000, encoding: 'utf8' })
+      r = spawnSync(cmd, { shell: true, cwd: snapshotRoot, timeout: 300_000, encoding: 'utf8', windowsHide: true })
     } catch (e) {
       const reason = `spawn 异常：${e && e.message ? e.message : e}`
       failed.push({ cmd, reason })
@@ -332,7 +453,9 @@ export function applyGateSnapshotCopy(cwd, snapshotRoot) {
         viaLink = existsSync(dst)
       } catch { viaLink = false }
       if (!viaLink) {
-        try { rmSync(dst, { recursive: true, force: true }) } catch { /* 假链接残留清不掉 → 下方复制报错走 warn */ }
+        // 假链接残留清理：dst 是 junction 本体——rmSync(dst) 在 Node v24 Windows 会穿透删
+        // 链接目标（主仓 copy 面真身，坑 junction-pierce-rm-sync），必须 rmdir 解链语义
+        try { unlinkLinkPath(dst) } catch { /* 假链接残留清不掉 → 下方复制报错走 warn */ }
         if (srcStat.isDirectory()) copyDirRecursive(src, dst)
         else copyFileSync(src, dst)
       }
@@ -352,12 +475,25 @@ export function applyGateSnapshotCopy(cwd, snapshotRoot) {
  * @param {{ cwd: string, files: string[] }} opts cwd=主仓根；files=本会话变更文件（仓库根相对 POSIX）
  * @returns {{ snapshotRoot: string, cleanup: () => void, reason?: string }|null} 失败返回 null（调用方回退主仓）
  */
-export function createGateSnapshot({ cwd, files, sourceRoot = null, skipImportSmoke = false, mergeBase = null }) {
+export function createGateSnapshot({ cwd, files, sourceRoot = null, skipImportSmoke = false, mergeBase = null, runtimeRoot = null }) {
   let snapshotRoot = null
   try {
     // 前置：主仓须是 git 仓且有 HEAD（无 git 环境回退主仓现行为）
     git(cwd, ['rev-parse', 'HEAD'])
 
+    // 陈旧快照自愈（2026-09-24-gate-snapshot-lifecycle，D-002@v1/D-003@v2/D-004@v2）：
+    // 建快照前同步回收账本内「守卫通过 ∧ 超 TTL ∧ pid 明确死」的条目（目录+worktree 注册
+    // 双清，删不掉的保留待下轮）。全 try/catch 恒吞——回收异常零阻断建快照；reclaimed 空
+    // 时零输出（正常路径逐字节不变）。runtimeRoot 缺失→账本链路退 no-op（禁 cwd 猜）。
+    try {
+      if (runtimeRoot) {
+        const { reclaimed, skipped } = reclaimStaleGateSnapshots({ runtimeRoot, cwd })
+        if (reclaimed.length > 0) {
+          console.log(`🧹 门禁快照自愈：回收 ${reclaimed.length} 个失活残留${skipped.length > 0 ? `（${skipped.length} 个删不掉，留账本待下轮）` : ''}`)
+        }
+      }
+    } catch { /* 回收异常 fail-open 退现状 */ }
+
     // symlink-store 布局探测（坑 gate-snapshot-pnpm-store-break，2026-09-12 驾驭第十七批②，
     // 用户第三次踩「lint 沙箱临时目录跑 pnpm 必假败」）：pnpm/bun/lerna 的 node_modules 内部
     // 是指向 store 的符号链接网——junction 进临时目录后跨根解析失效，实测必假败。
@@ -370,6 +506,8 @@ export function createGateSnapshot({ cwd, files, sourceRoot = null, skipImportSm
 
     snapshotRoot = mkdtempSync(join(tmpdir(), 'sillyspec-gate-'))
     git(cwd, ['worktree', 'add', '--detach', '--quiet', snapshotRoot, 'HEAD'])
+    // 登记账本（D-004@v2）：进程被杀时 cleanup 不跑，条目是残留唯一的可追踪凭据
+    registerGateSnapshot({ runtimeRoot, snapshotRoot })
 
     // 会话文件 overlay：主仓工作区版本覆盖进快照（本会话的最新态；文件不存在=已删，跳过）。
     // sourceRoot（verify 门定向跑用，2026-09-10 驾驭小结第八批）：overlay 源切换为本变更
@@ -422,8 +560,12 @@ export function createGateSnapshot({ cwd, files, sourceRoot = null, skipImportSm
             if (cwdDiff && !wtDiff) {
               src = cwdPath // 主仓直写新、worktree 停在基线 → 取主仓
             } else if (!(wtDiff && !cwdDiff)) {
-              console.warn(`⚠️ 快照双写分叉：${f} 在主仓与 worktree 均有不同修改——取主仓（本会话最新编辑位），请尽快对齐两边`)
-              src = cwdPath
+              // M2（2026-09-21-r5-efficiency-batch2 D-002@v2）：双写分叉改取 worktree 分支版——sourceRoot=worktree
+              // 定向跑的语义=验证本变更分支交付（batch1 实证：分叉取主仓拿走无本变更代码的版本，配上
+              // worktree 新增测试文件 → src/test 血统断裂 → module 实测假红一轮）。主仓侧同文件异动是
+              // 干扰源，其内容在 apply/对齐后由主仓单源复核兜底。
+              console.warn(`⚠️ 快照双写分叉：${f} 在主仓与 worktree 均有不同修改——取 worktree 分支版（本变更交付血统）；主仓侧改动若需保留请 apply/对齐后复跑`)
+              src = wtPath
             } // wtDiff && !cwdDiff → 保持 worktree（正常流零改变）
           }
         }
@@ -465,11 +607,36 @@ export function createGateSnapshot({ cwd, files, sourceRoot = null, skipImportSm
     const envMissing = envDirsLinked(cwd, snapshotRoot)
     if (envMissing.length > 0) {
       console.warn(`⚠️ 门禁快照环境不完整（${envMissing.join('、')} 在主仓存在、快照内缺失）——快照作废回退主仓实测（宁可主仓口径不可假沙箱硬挂；回退后失败先做污染归属鉴定）`)
-      try { git(cwd, ['worktree', 'remove', '--force', '--quiet', snapshotRoot]) } catch {}
-      try { rmSync(snapshotRoot, { recursive: true, force: true }) } catch {}
+      // 与正常 cleanup/失败 catch 同一清理体：双清确认才销账（该早退曾残留旧式 --quiet
+      // 清理与无重试 rmSync——独立审查 P1-1 根因未除尽的漏网面）
+      try {
+        const { dirRemoved: dGone, worktreeCleaned: wClean } = cleanupSnapshot({ snapshotRoot, cwd })
+        if (dGone && wClean) unregisterGateSnapshot({ runtimeRoot, snapshotRoot })
+      } catch {}
       return null
     }
 
+    // env 钉定缓存链接面（r5l 方案 5 / P17，通用机制见 resolvePinnedCacheLinks jsdoc）：
+    // 工具把缓存钉在仓内（UV_CACHE_DIR=.uv-cache 类）时 gitignored 不进 HEAD，快照缺它 →
+    // 构建隔离环境（含已装构建后端）缺失 → 快照内构建假红。junction 同相对路径进快照，
+    // 与环境目录族同款链接原语。整段 fail-soft：链接失败只 warn 不作废快照（缓存面缺失的
+    // 影响是工具自身的构建失败，失败输出自带归因提示）；未钉定/钉在仓外 → 全段零行为零输出。
+    const pinnedCacheLinks = []
+    for (const link of resolvePinnedCacheLinks({ cwd })) {
+      if (!existsSync(link.srcAbs)) continue
+      const dst = join(snapshotRoot, link.rel)
+      try {
+        mkdirSync(dirname(dst), { recursive: true })
+        symlinkSync(link.srcAbs, dst, 'junction')
+        pinnedCacheLinks.push({ envName: link.envName, tool: link.tool, rel: link.rel })
+      } catch (e) {
+        console.warn(`⚠️ 门禁快照构建缓存链接失败（${link.envName}=${link.rel}）：${e && e.message ? e.message : e}——快照内该工具构建可能缺缓存假红，失败先对照主仓口径`)
+      }
+    }
+    if (pinnedCacheLinks.length > 0) {
+      console.log(`🔬 门禁快照构建缓存面：${pinnedCacheLinks.map((x) => `${x.envName}=${x.rel}`).join('、')} 已 junction 进快照（P17：gitignored 仓内缓存携带构建隔离环境——缺它快照内构建假红；⚠️ 活链接，快照内构建写穿回主仓缓存）`)
+    }
+
     // gate_snapshot.commands 命令面（D-002@v2，2026-09-17-feedback-hardening R1，用户
     // 2026-09-17 负面①实证「全量快照必挂」）：主仓侧生成物缺失（fresh clone 未跑
     // postinstall）或过期时，copy 面只搬「主仓现有态」供给缺失/陈旧态——本段在环境链接
@@ -526,16 +693,23 @@ export function createGateSnapshot({ cwd, files, sourceRoot = null, skipImportSm
     }
 
     const cleanup = () => {
-      try { git(cwd, ['worktree', 'remove', '--force', '--quiet', snapshotRoot]) } catch {
-        try { rmSync(snapshotRoot, { recursive: true, force: true }) } catch { /* 残留交 OS tmp 清理 */ }
-      }
+      // 残留不再「交 OS tmp 清理」（%TEMP% 不会被 OS 清）——删不掉的快照由账本回收路径
+      // （下个 create 前按 TTL×pid 双闸自愈，2026-09-24-gate-snapshot-lifecycle）兜底；
+      // 销账只在「目录+worktree 注册双清确认」后执行（D-004@v2），删不掉保留条目待下轮
+      try {
+        const { dirRemoved, worktreeCleaned } = cleanupSnapshot({ snapshotRoot, cwd })
+        if (dirRemoved && worktreeCleaned) unregisterGateSnapshot({ runtimeRoot, snapshotRoot })
+      } catch { /* 双失败已由 cleanupSnapshot 吞掉；条目保留 */ }
     }
-    return { snapshotRoot, cleanup, overlaid }
+    return { snapshotRoot, cleanup, overlaid, pinnedCacheLinks }
   } catch (e) {
-    // 基建失败（worktree add 拒绝/磁盘满/…）：尽力清理后回退主仓
+    // 基建失败（worktree add 拒绝/磁盘满/…）：尽力清理后回退主仓；销账同走双清确认
+    // （D-004@v2：清不掉的条目保留待回收——它不是悬空条目，是待回收记录）
     if (snapshotRoot) {
-      try { git(cwd, ['worktree', 'remove', '--force', '--quiet', snapshotRoot]) } catch {}
-      try { rmSync(snapshotRoot, { recursive: true, force: true }) } catch {}
+      try {
+        const { dirRemoved, worktreeCleaned } = cleanupSnapshot({ snapshotRoot, cwd })
+        if (dirRemoved && worktreeCleaned) unregisterGateSnapshot({ runtimeRoot, snapshotRoot })
+      } catch {}
     }
     return null
   }
@@ -562,9 +736,48 @@ export function detectSymlinkStoreLayout(cwd) {
 /** 环境目录名集（根与子包通用） */
 const ENV_DIR_NAMES = new Set(['node_modules', '.venv', 'venv', 'env'])
 
+/**
+ * 「env 钉定缓存目录」注册表（r5l-forensic-verdict 方案 5 / P17，用户裁定走通用机制不做
+ * 单一工具硬编码）：构建/包管理工具用 env var 把缓存钉在**仓内**（相对 cwd 或仓内绝对路径）
+ * 时，该目录 gitignored 不进 HEAD——隔离快照（HEAD worktree）天然缺它，快照内构建隔离
+ * （uv builds-v0 / pip build 隔离环境）拿不到已装好的构建后端（P17：hatchling EPERM 假红
+ * 两轮卡 37min）。机制对任意工具通用：解析「注册的 env var → 仓内路径 → junction 进快照
+ * 同相对路径」，工具只是注册表一行数据——扩新工具（cargo/poetry/自定义）加一行即可，
+ * 不新增代码分支。家目录缺省形态（~/.cache/uv、%LOCALAPPDATA%/uv 等）**刻意不链接**：
+ * 快照内命令继承完整进程 env，家目录绝对路径直达真实缓存，junction 同一批文件零机制增益。
+ * pnpm-store 族不入表：符号链接 store 经 junction 跨根失效（detectSymlinkStoreLayout 先例）。
+ */
+const PINNED_CACHE_ENV_VARS = [
+  { env: 'UV_CACHE_DIR', tool: 'uv' },
+  { env: 'PIP_CACHE_DIR', tool: 'pip' },
+  { env: 'POETRY_CACHE_DIR', tool: 'poetry' },
+]
+
+/**
+ * 解析 env 钉定的仓内缓存目录（纯解析，不做链接/IO 判存在——可测性）。
+ * 规则：注册表逐项取 env 值；相对路径按 cwd 解析（与 uv/pip 相对 cwd 语义一致）；解析后
+ * 落在仓内（relative 不出仓）才算钉定缓存；仓外路径（家目录/自定义绝对位置）经继承 env
+ * 直达，不属于本面。同 var 多次出现取首个命中。
+ * @returns {{ envName: string, tool: string, srcAbs: string, rel: string }[]} 仓内钉定缓存清单
+ */
+export function resolvePinnedCacheLinks({ cwd, env = process.env } = {}) {
+  const out = []
+  for (const entry of PINNED_CACHE_ENV_VARS) {
+    const v = env[entry.env]
+    if (!v || !String(v).trim()) continue
+    const abs = isAbsolute(String(v).trim()) ? String(v).trim() : resolve(cwd, String(v).trim())
+    let rel = null
+    try { rel = relative(cwd, abs) } catch { continue }
+    if (!rel || rel.startsWith('..') || isAbsolute(rel)) continue // 仓外直达，无需链接
+    if (out.some((x) => x.rel === rel.split('\\').join('/'))) continue
+    out.push({ envName: entry.env, tool: entry.tool, srcAbs: abs, rel: rel.split('\\').join('/') })
+  }
+  return out
+}
+
 /**
  * 递归依赖发现（坑 gate-snapshot-monorepo-layout）：深度 ≤3 扫描（跳过环境目录自身内部/
- * .git/dist/build/.sillyspec），返回所有环境目录的仓库根相对 POSIX 路径（含根级四目录）。
+ * .git/dist/build/.sillyspec），返回所有环境目录的仓库根相对 POSIX 路径（含根四目录）。
  * pnpm/nx/lerna workspace 的 packages/<pkg>/node_modules 覆盖。
  */
 export function discoverEnvDirs(cwd, { maxDepth = 3 } = {}) {
@@ -627,6 +840,10 @@ export async function createVerifyGateSnapshot({ cwd, changeName, specBase, plat
   try {
     const { resolveVerifyChangedFiles } = await import('../verify-postcheck.js')
     const { resolveRuntimeRoot } = await import('./shared.js')
+    // 账本 runtimeRoot（2026-09-24-gate-snapshot-lifecycle task-03）：函数级解析一次，
+    // 平台/漂移模式口径与本函数内他处一致；解析失败退 null（账本链路 no-op，禁 cwd 猜）
+    let verifyRuntimeRoot = null
+    try { verifyRuntimeRoot = resolveRuntimeRoot(platformOpts, specBase) } catch { verifyRuntimeRoot = null }
     const { splitOwnVsForeignDiffFiles } = await import('../foreign-declared.js')
     let changeFiles = resolveVerifyChangedFiles(cwd, changeName, null, {
       specBase, includeWorkingTree: true,
@@ -636,8 +853,7 @@ export async function createVerifyGateSnapshot({ cwd, changeName, specBase, plat
     // 并入后主仓全部在途文件进场——他者活跃变更显式声明的文件（quick --files / 他者 design
     // 清单）剔除，只留本变更相关面（无主文件保留，fail-closed 口径与 probe6 一致）。
     try {
-      const runtimeRoot = resolveRuntimeRoot(platformOpts, specBase)
-      const { foreign } = splitOwnVsForeignDiffFiles(cwd, changeName, changeFiles, { specBase, runtimeRoot })
+      const { foreign } = splitOwnVsForeignDiffFiles(cwd, changeName, changeFiles, { specBase, runtimeRoot: verifyRuntimeRoot })
       if (foreign.length > 0) {
         const foreignSet = new Set(foreign.map(x => x.file))
         changeFiles = changeFiles.filter(f => !foreignSet.has(f))
@@ -670,7 +886,7 @@ export async function createVerifyGateSnapshot({ cwd, changeName, specBase, plat
       }
     } catch { /* meta 读取失败 → 主仓 cwd 源（files 已含本变更 working-tree 改动） */ }
 
-    const snap = createGateSnapshot({ cwd, files: changeFiles, sourceRoot, mergeBase: snapMergeBase })
+    const snap = createGateSnapshot({ cwd, files: changeFiles, sourceRoot, mergeBase: snapMergeBase, runtimeRoot: verifyRuntimeRoot })
     if (!snap) return null
 
     // 变更文档随快照：module-impact.md（test_strategy=evidence-auto 消费）/tasks.md 等