sillyspec 3.33.0 → 3.33.2

package/src/run/complete.js

@@ -17,12 +17,13 @@
  *   - node: join(path) + existsSync/readdirSync/readFileSync/mkdirSync/writeFileSync/appendFileSync/statSync(fs)
  */
 import { join, isAbsolute, resolve } from 'node:path'
+import { runtimeStatePath } from '../runtime-paths.js'
 import { existsSync, readFileSync, mkdirSync, writeFileSync, appendFileSync } from 'node:fs'
 import { writeAtomicSync } from '../fs-atomic.js'
 import { gitQuiet } from '../git-helper.js'
 import { writeCloseTraceArtifacts, projectTraceFaceRows } from '../flow-parity.js'
 import { withFileLock } from '../quicklog.js'
-import { triggerSync, WAIT_MARKER_RE, getStageSteps, formatWaitOptions, resolveRuntimeRoot, getOrCreateMultiRepoContext, resolveChangeDir, writePlatformDocsPointer, isRetiredAutoBrainstormTable, printRetiredAutoBrainstormRefusal } from './shared.js'
+import { triggerSync, triggerSyncTerminalStrict, WAIT_MARKER_RE, getStageSteps, formatWaitOptions, resolveRuntimeRoot, getOrCreateMultiRepoContext, resolveChangeDir, writePlatformDocsPointer, isRetiredAutoBrainstormTable, printRetiredAutoBrainstormRefusal } from './shared.js'
 import { isExplicitReviewWrite, collectWorktreeChangedFiles } from '../task-review.js'
 
 // 退役自动道守门（2026-10-14-brainstorm-auto-retire）：brainstorm-auto 4 步表已随自动道删除。
@@ -828,7 +829,10 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
 
     // gate 全过：persist completed（task-01 移后）。此处到 _write 之间若崩，DB 仍 in-progress（内存已 completed 但未落盘），下次进 CLI 读 DB 即 in-progress，不产生"假 completed"。
     pm._write(cwd, progress, changeName)
-    triggerSync(cwd, changeName, platformOpts, { completion: true })
+    // 终态强校验（2026-10-17-archive-half-state-location-stuck-active）：状态机驱动——仅
+    // DB status 已达 archived/deleted（archive 阶段完成即此态）走内联强校验，其余阶段
+    // 原样委托 triggerSync（后台化不变，非终态零行为变化）。见 run/shared.js 契约注释。
+    await triggerSyncTerminalStrict(cwd, changeName, platformOpts, { completion: true })
 
     const total = steps.length
     console.log(`✅ ${stageName} 阶段已完成（${total}/${total} 步）`)
@@ -843,7 +847,7 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
       let stageLedger = null
       let crossStage = false
       try {
-        const ledgerPath = join(specBase, '.runtime', `stage-session-ledger-${changeName}.json`)
+        const ledgerPath = runtimeStatePath(join(specBase, '.runtime'), `stage-session-ledger-${changeName}.json`)
         try { stageLedger = JSON.parse(readFileSync(ledgerPath, 'utf8')) } catch { /* 首阶段 */ }
         const r = updateStageSessionLedger(stageLedger, process.env.SILLYSPEC_SESSION_ID, stageName)
         stageLedger = r.ledger
@@ -1018,7 +1022,7 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
     if (stageName === 'execute' && changeName && defSteps && defSteps[currentIdx] && defSteps[nextPendingIdx] &&
         /Wave \d+ 执行/.test(defSteps[currentIdx].name || '') && /Wave \d+ 执行/.test(defSteps[nextPendingIdx].name || '')) {
       try {
-        const ledgerPath = join(specBase, '.runtime', `wave-session-ledger-${changeName}.json`)
+        const ledgerPath = runtimeStatePath(join(specBase, '.runtime'), `wave-session-ledger-${changeName}.json`)
         let ledger = null
         try { ledger = JSON.parse(readFileSync(ledgerPath, 'utf8')) } catch { /* 首 Wave */ }
         const { ledger: nextLedger, crossWaveAdvisory } = updateWaveSessionLedger(ledger, process.env.SILLYSPEC_SESSION_ID, defSteps[currentIdx].name)
@@ -1141,7 +1145,7 @@ async function printVerifyScopeDrift({ cwd, changeName, specBase, platformOpts,
       snapshot = JSON.parse(readFileSync(join(specBase, 'changes', changeName, 'scope-audit.json'), 'utf8'))
     } catch {
       try {
-        snapshot = JSON.parse(readFileSync(join(resolveRuntimeRoot(platformOpts, specBase), `scope-audit-${changeName}.json`), 'utf8'))
+        snapshot = JSON.parse(readFileSync(runtimeStatePath(resolveRuntimeRoot(platformOpts, specBase), `scope-audit-${changeName}.json`), 'utf8'))
       } catch { /* 快照缺失/损坏 → 跳过对比只打当前 totals */ }
     }
   }
@@ -1559,7 +1563,7 @@ export async function autoTickTasksFromCommitSubjects({ changeName, cwd, specBas
   try {
     const _tasksMdPath = join(specBase, 'changes', changeName, 'tasks.md')
     if (!existsSync(_tasksMdPath)) return { ticked: 0, skippedNoAnchor: 0 }
-    const _runIdFile = join(resolveRuntimeRoot(platformOpts, specBase), `current-execute-run-id-${changeName}`)
+    const _runIdFile = runtimeStatePath(resolveRuntimeRoot(platformOpts, specBase), `current-execute-run-id-${changeName}`)
     let _tickLog = ''
     try {
       if (existsSync(_runIdFile)) {
@@ -1640,7 +1644,7 @@ export async function autoCheckPlanFromReviews({ stageName, changeName, cwd, pla
     // plan.md Wave 引用行无 checkbox，无处可勾）。tasks.md 存在性作前置。
     const tasksMdPath = join(changeDir, 'tasks.md')
     const runtimeRoot = resolveRuntimeRoot(platformOpts, specBaseLc)
-    const runIdFile = join(runtimeRoot, `current-execute-run-id-${changeName}`)
+    const runIdFile = runtimeStatePath(runtimeRoot, `current-execute-run-id-${changeName}`)
     if (!existsSync(tasksMdPath) || !existsSync(runIdFile)) {
       return { autoChecked: false, checkedCount: 0, skippedCount: 0 }
     }
@@ -1798,7 +1802,7 @@ export async function detectExecuteBatchFinish({ pm, stageName, changeName, cwd,
     // 平台模式 runtimeRoot / worktree 漂移 specDriftAnchor 不透传时 marker 恒读不到
     // → 每个 task 进 blockedTasks → 批量完成静默失效
     const runtimeRoot = resolveRuntimeRoot(platformOpts, specBase)
-    const runIdFile = join(runtimeRoot, `current-execute-run-id-${changeName}`)
+    const runIdFile = runtimeStatePath(runtimeRoot, `current-execute-run-id-${changeName}`)
     // ── 缺席草稿自动补齐（坑 task-review-retired-archive-mismatch，2026-10-15 归档门口实证）──
     // Task Review 层退役（2026-09-26）后 execute 批量完成不再产 per-task review.json，但本函数
     // 下方复核循环与 archive step2 完成度判定（真相源=review.json verdict）仍以它在场为前提——

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

@@ -16,6 +16,7 @@
  * 异常面：全部 fail-open 吞掉（账本/回收任一异常零阻断，退现状残留）。
  */
 import { execFileSync } from 'node:child_process'
+import { runtimeStatePath } from '../runtime-paths.js'
 import { existsSync, mkdirSync, readFileSync } from 'node:fs'
 import { basename, dirname, join, resolve, sep } from 'node:path'
 import { tmpdir } from 'node:os'
@@ -28,7 +29,7 @@ const STALE_HOURS_DEFAULT = 24
 
 /** 账本文件路径（runtime 域：.sillyspec/.runtime/active-gate-snapshots.json） */
 export function gateSnapshotLedgerPath(runtimeRoot) {
-  return join(runtimeRoot, LEDGER_FILE)
+  return runtimeStatePath(runtimeRoot, LEDGER_FILE)
 }
 
 /** 读账本（损坏/缺失/非数组 → 空数组，fail-open） */

package/src/run/gate-snapshot.js

@@ -494,7 +494,12 @@ 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, runtimeRoot = null }) {
+export function createGateSnapshot({ cwd, files, carriedFiles = [], sourceRoot = null, skipImportSmoke = false, mergeBase = null, runtimeRoot = null, failRef = null }) {
+  // failRef 可选出参（坑 snapshot-fallback-reason-blind，2026-10-16 下游实证）：所有失败分支
+  // 把结构化原因写进 failRef.reason——调用方（verify --done 实测门 / noAI 质量扫描）消费它
+  // 替换硬编码笼统文案，降级原因可直读（pnpm 布局拒建 ≠ 文件集为空 ≠ junction 失败）。
+  // 返回契约不变（失败恒 null）；不传 failRef 行为与既有逐字节一致。
+  const setFail = (reason) => { if (failRef && typeof failRef === 'object') failRef.reason = reason }
   let snapshotRoot = null
   try {
     // 前置：主仓须是 git 仓且有 HEAD（无 git 环境回退主仓现行为）
@@ -519,6 +524,7 @@ export function createGateSnapshot({ cwd, files, sourceRoot = null, skipImportSm
     // 与其让沙箱报无关错误逼 advisory，不如布局命中即作废快照回退主仓（宁可主仓口径）。
     const layoutHit = detectSymlinkStoreLayout(cwd)
     if (layoutHit) {
+      setFail(`symlink-store 布局拒建（${layoutHit}）：node_modules 符号链接 store 经 junction 跨根失效，实测必假败——设计性回退主仓实测`)
       console.warn(`⚠️ 门禁快照对 ${layoutHit} 布局不可靠（node_modules 符号链接 store 经 junction 跨根失效，实测必假败）——跳过快照回退主仓实测；主仓失败再做污染归属鉴定`)
       return null
     }
@@ -537,7 +543,6 @@ export function createGateSnapshot({ cwd, files, sourceRoot = null, skipImportSm
     // 是共享运行时面：.runtime/（sqlite 锁/在途 marker）与 quicklog/（跨会话共享账本）；
     // local.yaml 由下方 cfg 段显式复制（单一来源，不经 overlay）。
     const overlayRoot = sourceRoot || cwd
-    let overlaid = 0
     // 双写一致性（2026-09-20 红线机检变更实证：主 agent 在主仓直写而 execute 已建 worktree 时，
     // overlay 源=worktree 拿陈旧内容盖掉快照 HEAD 的新版——快照内 import 找不到新导出→门禁假红）。
     // 祖先判据（fr-index-l2 二次实证升级）：基线优先取 merge-base 的每文件祖先内容
@@ -562,9 +567,12 @@ export function createGateSnapshot({ cwd, files, sourceRoot = null, skipImportSm
       }
       try { return cmpText(readFileSync(join(snapshotRoot, rel))) } catch { return null }
     }
-    for (const f of files) {
+    // 单文件 overlay（判定面 files 与携带面 carriedFiles 共用，2026-10-20-gate-snapshot-
+    // carried-deps 提取）：源=overlayRoot；worktree 模式经三态判定（陈旧取主仓/正常取
+    // worktree/分叉取 worktree 血统 M2）；源侧不存在返回 false（已删/不在场不拷）。
+    const overlayOne = (f) => {
       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
+      if (typeof f !== 'string' || f.includes('..') || f.startsWith('/') || isSillyspecRuntime) return false
       let src = join(overlayRoot, f)
       if (sourceRoot && sourceRoot !== cwd) {
         const wtPath = join(sourceRoot, f), cwdPath = join(cwd, f)
@@ -589,11 +597,26 @@ export function createGateSnapshot({ cwd, files, sourceRoot = null, skipImportSm
           }
         }
       }
-      if (!existsSync(src)) continue
+      if (!existsSync(src)) return false
       const dst = join(snapshotRoot, f)
       mkdirSync(dirname(dst), { recursive: true })
       copyFileSync(src, dst)
-      overlaid++
+      return true
+    }
+    let overlaid = 0
+    for (const f of files) { if (overlayOne(f)) overlaid++ }
+
+    // 携带面 overlay（2026-10-20-gate-snapshot-carried-deps，坑 verify-gate-…-three-defects
+    // 缺陷二）：他者声明文件从判定面剔除但物理携带进快照——快照复现本变更实测时真实的依赖
+    // 环境（worktree 模式≈worktree 自洽态；in-place≈主仓混合树）。坑文场景：本变更文件 import
+    // 他者未提交导出（quick 的 stripPathPrefix）→ 原快照装 HEAD 旧版必 TypeError 假红，携带后
+    // 自洽。判定面（files/overlaid）不含携带件——归属语义不变，假红可经控制台清单归因到他者。
+    const carriedList = []
+    if (Array.isArray(carriedFiles) && carriedFiles.length > 0) {
+      for (const f of carriedFiles) {
+        if (files.includes(f)) continue // 判定面已含（own 声明优先级高于他者）——不重复拷
+        if (overlayOne(f)) carriedList.push(f)
+      }
     }
 
     // 环境目录链接（坑 gate-snapshot-env-mismatch，2026-09-12 驾驭第十三批③，用户实证：
@@ -625,6 +648,7 @@ export function createGateSnapshot({ cwd, files, sourceRoot = null, skipImportSm
     // 回退主仓现行为（主仓口径可能被并行脏文件污染，但环境真实；两害取轻 + 回退原因可见）。
     const envMissing = envDirsLinked(cwd, snapshotRoot)
     if (envMissing.length > 0) {
+      setFail(`环境目录链接不完整（${envMissing.join('、')} 在主仓存在、快照内缺失）——快照作废回退主仓实测`)
       console.warn(`⚠️ 门禁快照环境不完整（${envMissing.join('、')} 在主仓存在、快照内缺失）——快照作废回退主仓实测（宁可主仓口径不可假沙箱硬挂；回退后失败先做污染归属鉴定）`)
       // 与正常 cleanup/失败 catch 同一清理体：双清确认才销账（该早退曾残留旧式 --quiet
       // 清理与无重试 rmSync——独立审查 P1-1 根因未除尽的漏网面）
@@ -699,7 +723,7 @@ export function createGateSnapshot({ cwd, files, sourceRoot = null, skipImportSm
     // HEAD 健版保证 import 图闭合。新增文件（HEAD 无版）无法回退 → 醒目 warn 保留。
     // 全链 fail-open：找不到解释器/基建异常只 warn 不作废快照（主场景是 Python 项目，
     // JS/TS 的 vitest load 冒烟成本高留后续）。
-    const overlaidPyFiles = files.filter(f => typeof f === 'string' && f.endsWith('.py')
+    const overlaidPyFiles = [...files, ...carriedList].filter(f => typeof f === 'string' && f.endsWith('.py')
       && !f.startsWith('.sillyspec/')
       && existsSync(join(snapshotRoot, f)))
     if (overlaidPyFiles.length > 0 && !skipImportSmoke) {
@@ -720,10 +744,13 @@ export function createGateSnapshot({ cwd, files, sourceRoot = null, skipImportSm
         if (dirRemoved && worktreeCleaned) unregisterGateSnapshot({ runtimeRoot, snapshotRoot })
       } catch { /* 双失败已由 cleanupSnapshot 吞掉；条目保留 */ }
     }
-    return { snapshotRoot, cleanup, overlaid, pinnedCacheLinks }
+    return { snapshotRoot, cleanup, overlaid, pinnedCacheLinks, carriedFiles: carriedList, carried: carriedList.length }
   } catch (e) {
     // 基建失败（worktree add 拒绝/磁盘满/…）：尽力清理后回退主仓；销账同走双清确认
-    // （D-004@v2：清不掉的条目保留待回收——它不是悬空条目，是待回收记录）
+    // （D-004@v2：清不掉的条目保留待回收——它不是悬空条目，是待回收记录）。
+    // 异常细节不再静默（坑 snapshot-fallback-reason-blind）：failRef 带原因 + warn 落日志。
+    setFail(`快照基建异常: ${e && e.message ? e.message : e}`)
+    try { console.warn(`⚠️ 门禁快照基建失败（回退主仓实测）: ${e && e.message ? e.message : e}`) } catch { /* 输出失败不影响回退 */ }
     if (snapshotRoot) {
       try {
         const { dirRemoved, worktreeCleaned } = cleanupSnapshot({ snapshotRoot, cwd })
@@ -856,8 +883,15 @@ export function envDirsLinked(cwd, snapshotRoot) {
  */
 export function printSnapshotFailureHint(snapInfo, { offEnv = 'SILLYSPEC_VERIFY_GATE_SNAPSHOT_OFF' } = {}) {
   if (!snapInfo || !snapInfo.snapshotRoot) return
-  console.error(`   🔬 本次实测执行于隔离快照：${snapInfo.snapshotRoot}（HEAD + 本变更 ${snapInfo.changeFileCount ?? '?'} 个文件${snapInfo.sourceRoot ? '，overlay 自 worktree' : ''}）`)
-  console.error(`   失败疑点排查顺序：① 本变更文件自身的真实失败（最常见）→ 修代码；② 快照环境差异（monorepo 依赖布局/环境目录链接缺失）→ 设 ${offEnv}=1 回退主仓复跑对照——主仓过而快照挂即环境问题；③ 并行污染已被快照隔离，不在疑点内。`)
+  console.error(`   🔬 本次实测执行于隔离快照：${snapInfo.snapshotRoot}（HEAD + 本变更 ${snapInfo.changeFileCount ?? '?'} 个文件${snapInfo.sourceRoot ? '，overlay 自 worktree' : ''}${snapInfo.carriedFiles && snapInfo.carriedFiles.length > 0 ? `，携带 ${snapInfo.carriedFiles.length} 个他者声明文件（依赖自洽面）` : ''}）`)
+  // 2026-10-20-gate-snapshot-carried-deps 评审 F3 清偿：携带面在场时他者文件**在**疑点内
+  // （原「并行污染不在疑点内」只对未声明脏文件成立——携带件是声明过的他者内容）。
+  if (snapInfo.carriedFiles && snapInfo.carriedFiles.length > 0) {
+    const preview = snapInfo.carriedFiles.slice(0, 5).join('、')
+    console.error(`   失败疑点排查顺序：① 本变更文件自身的真实失败（最常见）→ 修代码；② 携带的他者声明文件坏半态（${snapInfo.carriedFiles.length > 5 ? `${preview} 等` : preview}——他者变更在途内容，非本变更面）→ 核对他者变更状态或 SNAPSHOT_OFF 对照；③ 快照环境差异（monorepo 依赖布局/环境目录链接缺失）→ 设 ${offEnv}=1 回退主仓复跑对照——主仓过而快照挂即环境问题。`)
+  } else {
+    console.error(`   失败疑点排查顺序：① 本变更文件自身的真实失败（最常见）→ 修代码；② 快照环境差异（monorepo 依赖布局/环境目录链接缺失）→ 设 ${offEnv}=1 回退主仓复跑对照——主仓过而快照挂即环境问题；③ 并行污染已被快照隔离，不在疑点内。`)
+  }
 }
 
 /**
@@ -865,12 +899,14 @@ export function printSnapshotFailureHint(snapInfo, { offEnv = 'SILLYSPEC_VERIFY_
  * main 工作区，多会话并发任何人的 WIP 都能弄红别人的门）。等价「--worktree 定向跑」：
  * overlay 文件集 = resolveVerifyChangedFiles（worktree-aware：含 merge-base 补齐与
  * working-tree），overlay 源 = 本变更 worktree 根（meta 感知；in-place 退主仓 cwd）——
- * 并行会话的在途文件物理不进快照。变更文档（changes/<name>/**，test_strategy 的
- * module-impact.md 等消费）从主仓 specBase 随快照复制。
+ * 并行会话**未声明**的在途脏文件物理不进快照（隔离核心）；他者**显式声明**的文件以携带面
+ * 物理进快照（2026-10-20-gate-snapshot-carried-deps：依赖自洽——判定/归因面仍剔除）。
+ * 变更文档（changes/<name>/**，test_strategy 的 module-impact.md 等消费）从主仓 specBase 随快照复制。
  * @param {{ cwd: string, changeName: string, specBase: string, platformOpts?: object }} opts
  * @returns {Promise<{snapshotRoot: string, cleanup: () => void, overlaid: number, changeFileCount: number}|null>}
  */
-export async function createVerifyGateSnapshot({ cwd, changeName, specBase, platformOpts = {} }) {
+export async function createVerifyGateSnapshot({ cwd, changeName, specBase, platformOpts = {}, failRef = null }) {
+  const setFail = (reason) => { if (failRef && typeof failRef === 'object') failRef.reason = reason }
   try {
     const { resolveVerifyChangedFiles } = await import('../verify-postcheck.js')
     const { resolveRuntimeRoot } = await import('./shared.js')
@@ -879,19 +915,35 @@ export async function createVerifyGateSnapshot({ cwd, changeName, specBase, plat
     let verifyRuntimeRoot = null
     try { verifyRuntimeRoot = resolveRuntimeRoot(platformOpts, specBase) } catch { verifyRuntimeRoot = null }
     const { splitOwnVsForeignDiffFiles } = await import('../foreign-declared.js')
-    let changeFiles = resolveVerifyChangedFiles(cwd, changeName, null, {
+    // 变更文件集为空三分成因区分（坑 snapshot-fallback-reason-blind）：null=git 不可用/解析
+    // 失败；[]=HEAD 无 diff；他者声明过滤清空在下方单独计——三者处置同为回退主仓，但排查
+    // 出路完全不同，笼统「变更文件集为空」曾把 pnpm 布局拒建也误标成它。
+    const rawChangeFiles = resolveVerifyChangedFiles(cwd, changeName, null, {
       specBase, includeWorkingTree: true,
-    }) || []
-    if (changeFiles.length === 0) return null // 无变更文件集 → 无从定向，回退主仓
+    })
+    let changeFiles = rawChangeFiles || []
+    if (changeFiles.length === 0) {
+      setFail(rawChangeFiles === null
+        ? '变更文件集为空（git 不可用/解析失败——非 git 仓或 git 异常，无从定向 overlay）'
+        : '变更文件集为空（HEAD 无 diff——改动可能已全部提交，无可隔离面）')
+      return null // 无变更文件集 → 无从定向，回退主仓
+    }
     // 他者声明归属过滤（坑 verify-reconcile-foreign-wip 同款）：in-place 模式 working-tree
     // 并入后主仓全部在途文件进场——他者活跃变更显式声明的文件（quick --files / 他者 design
-    // 清单）剔除，只留本变更相关面（无主文件保留，fail-closed 口径与 probe6 一致）。
+    // 清单）从**判定面**剔除，只留本变更相关面（无主文件保留，fail-closed 口径与 probe6 一致）。
+    // 2026-10-20-gate-snapshot-carried-deps（坑 verify-gate-…-three-defects 缺陷二）：被剔
+    // 文件改以「携带面」物理进快照（carriedFiles）——快照依赖自洽，判定/归属语义不变。
+    let carriedForeignFiles = []
     try {
       const { foreign } = splitOwnVsForeignDiffFiles(cwd, changeName, changeFiles, { specBase, runtimeRoot: verifyRuntimeRoot })
       if (foreign.length > 0) {
         const foreignSet = new Set(foreign.map(x => x.file))
+        carriedForeignFiles = changeFiles.filter(f => foreignSet.has(f))
         changeFiles = changeFiles.filter(f => !foreignSet.has(f))
-        if (changeFiles.length === 0) return null
+        if (changeFiles.length === 0) {
+          setFail(`变更文件集为空（${foreign.length} 个 diff 文件全部被他者声明过滤——并行会话声明面覆盖了本变更全部在途文件）`)
+          return null
+        }
       }
     } catch { /* 过滤失败退全量（fail-closed：宁可多 overlay 不漏本变更文件） */ }
 
@@ -920,8 +972,16 @@ export async function createVerifyGateSnapshot({ cwd, changeName, specBase, plat
       }
     } catch { /* meta 读取失败 → 主仓 cwd 源（files 已含本变更 working-tree 改动） */ }
 
-    const snap = createGateSnapshot({ cwd, files: changeFiles, sourceRoot, mergeBase: snapMergeBase, runtimeRoot: verifyRuntimeRoot })
-    if (!snap) return null
+    const snap = createGateSnapshot({ cwd, files: changeFiles, carriedFiles: carriedForeignFiles, sourceRoot, mergeBase: snapMergeBase, runtimeRoot: verifyRuntimeRoot, failRef })
+    if (!snap) {
+      // createGateSnapshot 已把具体原因写进同一 failRef；无 reason（旧形态兜底）补笼统口径
+      if (failRef && typeof failRef === 'object' && !failRef.reason) setFail('快照基建不可用（createGateSnapshot 返回 null，无更细原因）')
+      return null
+    }
+    if (snap.carriedFiles && snap.carriedFiles.length > 0) {
+      const preview = snap.carriedFiles.slice(0, 5).join('、')
+      console.log(`📦 快照携带 ${snap.carriedFiles.length} 个他者声明文件（依赖自洽面，不进判定/归因面；假红先核对他者变更）${snap.carriedFiles.length > 5 ? `：${preview} 等` : `：${preview}`}`)
+    }
 
     // 变更文档随快照：module-impact.md（test_strategy=evidence-auto 消费）/tasks.md 等
     // 在 .sillyspec（gitignore）不进 HEAD，从主仓 specBase 复制 changes/<name>/**
@@ -940,7 +1000,26 @@ export async function createVerifyGateSnapshot({ cwd, changeName, specBase, plat
     } catch { /* 文档复制失败不连坐快照（test_strategy 降级 module 集仍可跑） */ }
 
     return { ...snap, changeFileCount: changeFiles.length, sourceRoot }
-  } catch {
-    return null // 任一链路异常 → 回退主仓现行为
+  } catch (e) {
+    // 任一链路异常 → 回退主仓现行为。异常细节不再静默（坑 snapshot-fallback-reason-blind）：
+    // failRef 带原因 + warn 落日志，排查不再靠 stdout 考古。
+    setFail(`快照链路异常: ${e && e.message ? e.message : e}`)
+    try { console.warn(`⚠️ 门禁快照链路异常（回退主仓实测）: ${e && e.stack ? e.stack.split('\n')[0] : e}`) } catch { /* 输出失败不影响回退 */ }
+    return null
   }
 }
+
+/**
+ * 快照口径观测字段（坑 snapshot-fallback-reason-blind，FR-04 落盘面）：--done 实测门把
+ * used_snapshot 与降级原因经 runVerifyTestCheck 的 observability 通道带进 test-result.json
+ * extra（对齐 2026-10-09 复用观测先例）。快照在场时记录随快照销毁（无可降级事实）；
+ * 回退主仓时记录恰好落在主仓 .runtime——降级证据存活在主仓，与用途一致。
+ * @param {boolean} used 快照是否真实在场
+ * @param {{ reason?: string }|null} failRef createVerifyGateSnapshot 的出参（可 null）
+ * @returns {{ used_snapshot: boolean, snapshot_fallback_reason?: string }}
+ */
+export function snapshotObservability(used, failRef) {
+  if (used) return { used_snapshot: true }
+  const reason = failRef && failRef.reason ? String(failRef.reason) : 'createVerifyGateSnapshot 返回 null（变更文件集为空 / 快照基建不可用）'
+  return { used_snapshot: false, snapshot_fallback_reason: reason }
+}

package/src/run/gates.js

@@ -28,6 +28,7 @@
  * 不搬：ensureDepsFreshness（execute 入口 deps 自检，调用方 runStage 非 completeStep，归属未来 execute-handler）
  */
 import { basename, join, relative, dirname } from 'node:path'
+import { runtimeStatePath } from '../runtime-paths.js'
 import { createHash } from 'node:crypto'
 import { execFileSync } from 'node:child_process'
 import { existsSync, readFileSync, readdirSync, statSync, mkdirSync, unlinkSync, writeFileSync } from 'node:fs'
@@ -444,8 +445,8 @@ export async function enforceDepsGate(stageName, cwd, changeName, step, steps, c
   if (worktreeGone && changeName) {
     try {
       const runtimeRoot = resolveRuntimeRoot(platformOpts, specBase)
-      const legitimatelyEnded = existsSync(join(runtimeRoot, `apply-pathspec-${changeName}.txt`))
-        || existsSync(join(runtimeRoot, `execute-cleanup-${changeName}.json`))
+      const legitimatelyEnded = existsSync(runtimeStatePath(runtimeRoot, `apply-pathspec-${changeName}.txt`))
+        || existsSync(runtimeStatePath(runtimeRoot, `execute-cleanup-${changeName}.json`))
       if (legitimatelyEnded) {
         console.log('ℹ️  worktree 已在 apply/execute 收尾时正当清理（凭据在 .runtime），deps 门放行')
         return true
@@ -549,7 +550,7 @@ function rollbackCompletionAndReturn(pm, progress, stageData, steps, currentIdx,
 
 /** 档位状态文件路径（runtimeRoot 下 per-change；命名对齐 apply-pathspec-<change>.txt 先例） */
 function ceremonyTierFilePath(runtimeRoot, changeName) {
-  return join(runtimeRoot, `ceremony-tier-${changeName}.json`)
+  return runtimeStatePath(runtimeRoot, `ceremony-tier-${changeName}.json`)
 }
 
 /**
@@ -1100,17 +1101,24 @@ export async function runStageCompletionGates({ stageName, cwd, changeName, plat
     // 变更文档随快照（test_strategy 消费）。并行会话在途文件物理不进快照、不参与本门判定。
     // 快照基建失败 → 回退主仓现行为（失败路径沿用 renderVerifyTestAttribution 归因提示）。
     let verifyGateSnap = null
+    let snapshotFailRef = null // createVerifyGateSnapshot 出参：结构化失败原因（FR-04，替代硬编码笼统文案）
     if (!process.env.SILLYSPEC_VERIFY_GATE_SNAPSHOT_OFF) {
       try {
         const { createVerifyGateSnapshot } = await import('./gate-snapshot.js')
-        verifyGateSnap = await createVerifyGateSnapshot({ cwd, changeName, specBase, platformOpts })
+        snapshotFailRef = {}
+        verifyGateSnap = await createVerifyGateSnapshot({ cwd, changeName, specBase, platformOpts, failRef: snapshotFailRef })
         if (verifyGateSnap) {
-          console.log(`🧪 Verify 实测隔离快照（根：${verifyGateSnap.snapshotRoot}）：HEAD + 本变更 ${verifyGateSnap.changeFileCount} 个文件${verifyGateSnap.sourceRoot ? '（overlay 自 worktree——本变更分支内容定向跑）' : ''}（并行会话脏文件不参与门判定）`)
+          console.log(`🧪 Verify 实测隔离快照（根：${verifyGateSnap.snapshotRoot}）：HEAD + 本变更 ${verifyGateSnap.changeFileCount} 个文件${verifyGateSnap.sourceRoot ? '（overlay 自 worktree——本变更分支内容定向跑）' : ''}${verifyGateSnap.carriedFiles && verifyGateSnap.carriedFiles.length > 0 ? ` + 携带 ${verifyGateSnap.carriedFiles.length} 个他者声明文件（依赖自洽，不进判定面）` : ''}（并行会话未声明脏文件不参与门判定）`)
         } else {
-          // FR-02（2026-10-09-verify-reuse-friction）：null 回退与异常回退同等可见 + 记账
+          // FR-02（2026-10-09-verify-reuse-friction）：null 回退与异常回退同等可见 + 记账；
+          // FR-04（2026-10-16-fix-downstream-tool-defects）：reason 消费 failRef 结构化原因
+          // （pnpm 布局拒建 / 文件集为空三分成因 / junction 失败 / 基建异常详情），不再笼统
           try {
             const { reportGateSnapshotFallback } = await import('./gate-snapshot.js')
-            if (typeof reportGateSnapshotFallback === 'function') await reportGateSnapshotFallback({ cwd, changeName, platformOpts, where: 'verify --done 实测门', reason: 'createVerifyGateSnapshot 返回 null（变更文件集为空 / 快照基建不可用）' })
+            const fbReason = snapshotFailRef && snapshotFailRef.reason
+              ? `createVerifyGateSnapshot 返回 null：${snapshotFailRef.reason}`
+              : 'createVerifyGateSnapshot 返回 null（变更文件集为空 / 快照基建不可用）'
+            if (typeof reportGateSnapshotFallback === 'function') await reportGateSnapshotFallback({ cwd, changeName, platformOpts, where: 'verify --done 实测门', reason: fbReason })
           } catch { /* 报告失败不改变回退行为（含测试 mock 模块缺导出的形态） */ }
         }
       } catch (e) {
@@ -1120,6 +1128,22 @@ export async function runStageCompletionGates({ stageName, cwd, changeName, plat
         } catch { /* 报告失败不改变回退行为（含测试 mock 模块缺导出的形态） */ }
       }
     }
+    // FR-04 降级事实落盘：used_snapshot 与失败原因随 test-result.json extra 持久化（快照在场
+    // 时记录随快照销毁；回退主仓时恰好落在主仓 .runtime——降级证据存活面与用途一致）。
+    // 评审 P3-2 整改：OFF 开关是主动关闸，不得记成「基建故障/文件集为空」的笼统回退原因。
+    let snapObsFields
+    if (process.env.SILLYSPEC_VERIFY_GATE_SNAPSHOT_OFF) {
+      snapObsFields = { used_snapshot: false, snapshot_fallback_reason: 'SILLYSPEC_VERIFY_GATE_SNAPSHOT_OFF=1 主动关闸（快照未尝试，非基建故障）' }
+    } else if (verifyGateSnap) {
+      snapObsFields = { used_snapshot: true }
+    } else {
+      try {
+        const { snapshotObservability } = await import('./gate-snapshot.js')
+        snapObsFields = snapshotObservability(false, snapshotFailRef)
+      } catch {
+        snapObsFields = { used_snapshot: false, snapshot_fallback_reason: snapshotFailRef && snapshotFailRef.reason ? String(snapshotFailRef.reason) : 'createVerifyGateSnapshot 返回 null（变更文件集为空 / 快照基建不可用）' }
+      }
+    }
     const gateCwd = verifyGateSnap ? verifyGateSnap.snapshotRoot : cwd
     const gateSpecBase = verifyGateSnap ? join(verifyGateSnap.snapshotRoot, '.sillyspec') : specBase
     let testCheck
@@ -1220,7 +1244,7 @@ export async function runStageCompletionGates({ stageName, cwd, changeName, plat
         `质量扫描: ${reusableScan ? '命中（上层未消费）' : '指纹失配/无记录'}`,
         `green-cache: ${greenHit ? '命中（上层未消费）' : '指纹失配/过期/无记录'}`,
       ].join('；')
-      testCheck = runVerifyTestCheck({ cwd: gateCwd, specBase: gateSpecBase, changeName, ctx, observability: { fingerprint: _obsFingerprint, reuse_decision: { layer: 'real-run', hit: false, reason: _missReason } }, ...(Array.isArray(_restrict) && _restrict.length > 0 ? { restrictFiles: _restrict } : {}) })
+      testCheck = runVerifyTestCheck({ cwd: gateCwd, specBase: gateSpecBase, changeName, ctx, observability: { fingerprint: _obsFingerprint, reuse_decision: { layer: 'real-run', hit: false, reason: _missReason }, ...snapObsFields }, ...(Array.isArray(_restrict) && _restrict.length > 0 ? { restrictFiles: _restrict } : {}) })
       printVerifyTestCheck(testCheck)
       // 自动绑定补全（full-autopilot-parity，R21 thin 迁移）：测试已跑、test-result.json 已落盘，
       // verify --done 收口时从测试结果自动补全 requirements.md 的空绑定槽——与 thin 同逻辑（逐行扫描）。

package/src/run/prompt.js

@@ -19,6 +19,7 @@
  *   - loadModuleContextIndex/buildModuleContextInjection 内 require('fs'/'path') 改顶部静态 import
  */
 import { basename, dirname, join } from 'node:path'
+import { runtimeStatePath } from '../runtime-paths.js'
 import { existsSync, readFileSync, mkdirSync, readdirSync, writeFileSync, rmSync } from 'node:fs'
 import { createHash } from 'node:crypto'
 import jsYaml from 'js-yaml'
@@ -868,7 +869,7 @@ export async function renderPreflightFailures({ stageName, stepName, cwd, specBa
 export function shouldInjectFullContext({ changeName, stageName, runtimeRoot } = {}) {
   try {
     if (!runtimeRoot || !changeName || !stageName) return { full: true }
-    const ledgerPath = join(runtimeRoot, `prompt-inject-${changeName}.json`)
+    const ledgerPath = runtimeStatePath(runtimeRoot, `prompt-inject-${changeName}.json`)
     if (!existsSync(ledgerPath)) return { full: true }
     const ledger = JSON.parse(readFileSync(ledgerPath, 'utf8'))
     const rec = (ledger && ledger.stages && typeof ledger.stages === 'object') ? ledger.stages[stageName] : null
@@ -906,7 +907,7 @@ function renderPromptInjectSummaryLine({ firstStep, digest, specBase, projectNam
  * @param {{ runtimeRoot: string, changeName: string, stageName: string, firstStep: number, digest: string }} args
  */
 async function recordPromptInjectLedger({ runtimeRoot, changeName, stageName, firstStep, digest }) {
-  const ledgerPath = join(runtimeRoot, `prompt-inject-${changeName}.json`)
+  const ledgerPath = runtimeStatePath(runtimeRoot, `prompt-inject-${changeName}.json`)
   await withFileLock(ledgerPath + '.lock', () => {
     let ledger = null
     try { ledger = JSON.parse(readFileSync(ledgerPath, 'utf8')) } catch { ledger = null }
@@ -1428,7 +1429,7 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
       // 注入结果同步落 runtime JSON（与既有 KNOWLEDGE_HIT_REPORT 落盘口径一致）
       const decRuntimeDir = join(decSpecBase, '.runtime')
       mkdirSync(decRuntimeDir, { recursive: true })
-      writeAtomicSync(join(decRuntimeDir, 'decision-hits.json'), JSON.stringify({ matched: decResult.matched, decisionHits: decResult.decisionHits || [] }, null, 2) + '\n')
+      writeAtomicSync(runtimeStatePath(decRuntimeDir, 'decision-hits.json'), JSON.stringify({ matched: decResult.matched, decisionHits: decResult.decisionHits || [] }, null, 2) + '\n')
     } catch (e) {
       substitute(/\{DECISION_HITS\}/g, `[decisions] 决策命中检测异常（${e.message}），跳过`)
     }
@@ -1495,7 +1496,7 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
       )
       // 写入 runtime JSON（既有机制照旧，新旧遥测共存）
       mkdirSync(runtimeDir, { recursive: true })
-      writeAtomicSync(join(runtimeDir, 'knowledge-hit-report.json'), JSON.stringify(knowledgeInjection.json, null, 2) + '\n')
+      writeAtomicSync(runtimeStatePath(runtimeDir, 'knowledge-hit-report.json'), JSON.stringify(knowledgeInjection.json, null, 2) + '\n')
     } catch (e) {
       substitute(/\{KNOWLEDGE_HIT_REPORT\}/g, 'Status: no matches (error: ' + e.message + ')')
     }
@@ -1552,7 +1553,7 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
     let runId = ''
     const execSpecBase = resolvePromptSpecBase(platformOpts, cwd)
     const runtimeRoot = resolveRuntimeRoot(platformOpts, execSpecBase)
-    const runIdFile = join(runtimeRoot, `current-execute-run-id-${changeName}`)
+    const runIdFile = runtimeStatePath(runtimeRoot, `current-execute-run-id-${changeName}`)
     try {
       if (existsSync(runIdFile)) {
         const c = readFileSync(runIdFile, 'utf8').trim()

package/src/run/scan-profile.js

@@ -9,6 +9,7 @@
  *   - executeScanPostcheck 原冗余动态 import('fs'/'path'/'child_process') 删除，改顶部静态（execSync 实际未直接用，纯遗留）
  */
 import { join, basename, extname } from 'node:path'
+import { runtimeStatePath } from '../runtime-paths.js'
 import { existsSync, readdirSync, statSync, mkdirSync, writeFileSync, unlinkSync, readFileSync } from 'node:fs'
 import { safeGit, resolveRuntimeRoot } from './shared.js'
 import { SCAN_REQUIRED_DOCS } from '../constants.js'
@@ -332,7 +333,7 @@ export async function executeScanResumeCheck(cwd, platformOpts) {
   // .runtime/last-delta.json（归档/delta 补跑写入的最近变更快照），14 天窗口内提示本轮
   // scan 优先核对其涉及模块——advisory 不阻断不改变步骤结构；缺失/过期/解析失败静默。
   try {
-    const sidecarPath = join(resolveRuntimeRoot(platformOpts, specBase), 'last-delta.json')
+    const sidecarPath = runtimeStatePath(resolveRuntimeRoot(platformOpts, specBase), 'last-delta.json')
     if (existsSync(sidecarPath)) {
       const sidecar = JSON.parse(readFileSync(sidecarPath, 'utf8'))
       const ageMs = Date.now() - Date.parse(sidecar.updatedAt || '')