sillyspec 3.29.4 → 3.30.0

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 源切换为本变更
@@ -389,15 +527,21 @@ export function createGateSnapshot({ cwd, files, sourceRoot = null, skipImportSm
     // 两份都变于祖先且互不相等（真双写分叉）→ 显式警告 + 取 cwd（主仓直写=本会话最新编辑位约定）。
     // 行尾归一（坑 autocrlf-byte-misjudge）：本机 autocrlf=true 时快照 checkout 是 CRLF、
     // 工作区文件常是 LF——字节直比会误判「两边都改」。比较一律 CRLF→LF 归一后做。
+    // 对称 trim（坑 gate-snapshot-ancestor-trim，2026-09-20 taskcard-yaml-hardgate verify 实证）：
+    // git() 助手对全部输出 .trim()（rev-parse 场景需要），git show 的祖先内容因此被剥掉尾换行——
+    // 与磁盘读取（仅 CRLF 归一）不对称，已存在文件恒 anc!==cwd 误判「双写分叉」取主仓旧版，
+    // worktree 交付的修改进不了 verify 门快照→门假红（新文件因主仓不存在幸免）。比较三侧
+    // 统一 normalizeEol+trim 同口径——首尾空白差异不参与分叉判定（语义修改不会只差首尾空白）。
     const normalizeEol = (buf) => String(buf).replace(/\r\n/g, '\n')
+    const cmpText = (t) => normalizeEol(t).trim()
     const headFileContent = (rel) => {
       if (mergeBase) {
         try {
           const anc = git(cwd, ['show', `${mergeBase}:${rel}`])
-          if (typeof anc === 'string') return normalizeEol(anc)
+          if (typeof anc === 'string') return cmpText(anc)
         } catch { /* 祖先无此文件（新增文件）→ 落到快照 HEAD 口径 */ }
       }
-      try { return normalizeEol(readFileSync(join(snapshotRoot, rel))) } catch { return null }
+      try { return cmpText(readFileSync(join(snapshotRoot, rel))) } catch { return null }
     }
     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')
@@ -407,8 +551,8 @@ export function createGateSnapshot({ cwd, files, sourceRoot = null, skipImportSm
         const wtPath = join(sourceRoot, f), cwdPath = join(cwd, f)
         if (existsSync(wtPath) && existsSync(cwdPath)) {
           let wtText = null, cwdText = null
-          try { wtText = normalizeEol(readFileSync(wtPath)) } catch { /* 读失败不介入 */ }
-          try { cwdText = normalizeEol(readFileSync(cwdPath)) } catch { /* 读失败不介入 */ }
+          try { wtText = cmpText(readFileSync(wtPath)) } catch { /* 读失败不介入 */ }
+          try { cwdText = cmpText(readFileSync(cwdPath)) } catch { /* 读失败不介入 */ }
           if (wtText !== null && cwdText !== null && wtText !== cwdText) {
             const base = headFileContent(f)
             const wtDiff = base === null || wtText !== base
@@ -416,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（正常流零改变）
           }
         }
@@ -459,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 面只搬「主仓现有态」供给缺失/陈旧态——本段在环境链接
@@ -520,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
   }
@@ -556,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 } = {}) {
@@ -621,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,
@@ -630,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))
@@ -664,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 等