@whyshu/argent-engine 0.0.0-stage → 0.6.1

package/engine/scripts/check-test-env-safety.mjs

@@ -0,0 +1,627 @@
+#!/usr/bin/env node
+/**
+ * check-test-env-safety.mjs —— **测试环境卫生**门禁（2026-10-03；当天两次事故后补）。
+ *
+ * ══════════════════════════════════════════════════════════════════════════
+ * 一、它防的是什么（两次真实事故，都是"测试写进了真实数据目录"）
+ * ══════════════════════════════════════════════════════════════════════════
+ *   · 事故① `skin-display-prefs.test.mjs`：子进程只改 `HOME`，`ARGENT_DATA_DIR`/`DSH_HOME`
+ *     照抄调用方 ⇒ 显示偏好写进真实 `~/.dsh/argent/skin.json`。
+ *   · 事故② 同类形态在**裸跑**（不经 `scripts/run-tests.sh`）时复现：跑测试的入口会
+ *     `unset DSH_HOME` 兜底，而裸跑没有那层清理 ⇒ 三级链把子进程指到**真实实例**。
+ *   共同根因：**子进程环境是"调用方环境的副本 + 补丁"**，而不是显式构造的。
+ *
+ * ## 二、判据（全部机械可判；白名单必须带理由）
+ * | 规则 | 命中 | 为什么是红的 |
+ * |---|---|---|
+ * | **R1 `spread-unneutralized`** | 测试里 `...process.env` / `os.environ.copy()` / `**os.environ`，而**全文件没有任何一处** `sanitizedEnv(`、`ARGENT_DATA_DIR`、`DSH_HOME` | 子进程会继承调用方的**实例级开关** ⇒ 写目标随"谁跑的测试"改变（两次事故的形态） |
+ * | **R2 `resolve-datadir-without-assert`** | 调 `resolveDataDir(` / `resolve_data_dir(`，却没有 `assertInsideFixture(` | "假 HOME" 仍可能被链上另一级改道 ⇒ 必须**自证**判据算出来的路径在夹具内 |
+ * | **R3 `required-helper`** | `REQUIRED_HELPER` 名单里的测试（会触达数据目录的优先项）没引用助手 | 迁移是**可回归的**：名单里的文件不许退回手拼 env |
+ * | **R4 `real-home-literal`** | 代码行里用 `homedir()` 拼 `.dsh`/`argent` 路径（即解析**真实**数据目录） | 真实目录只允许"只读引用"，且必须逐条给出理由（白名单） |
+ * | **R5 `real-datadir-unchanged`** | `--snapshot` / `--verify` 之间，真实数据目录**三层判据**任一有变化（见下） | 这条是**结果判据**：不管哪条路径漏了，写进真实目录就会被抓住 |
+ * | **W 过期白名单** | 白名单里的文件不存在、理由为空、或该规则在它身上**不再命中** | 名单和代码一样会腐烂（形态照 `skills/internal.json` 的 G5/G6） |
+ *
+ * ## 二·补 R5 的三层（2026-10-04 扩：从"6 个关键文件"到"目录级发现 + 文件级判定"）
+ *
+ * 背景（盲区）：原来只比对 `GUARDED_FILES` 6 个关键文件 ⇒ **"在真实目录里新建文件"完全抓不到**
+ * —— 实测 1016 份夹具备份（sha 前缀 `2ef8426e…`/`29bd6d40…`，各 508 份）就是在
+ * `~/.dsh/argent/backup/` 里被**新建**出来的，而 6 文件比对全程"绿"。
+ *
+ * | 层 | 判据 | 为什么这么定 |
+ * |---|---|---|
+ * | ① **关键文件面** | `GUARDED_FILES` 6 个的 `size/mtime/sha256`（**保持原样**） | 两次事故的直接判据；换了它就没法说"跟以前一样" |
+ * | ② **目录级发现面** | 真实数据目录**全树路径集合差** ⇒ **只报"新增"**（消失的单独提示，因为"删真实文件"比"新建"更该查） | 新增文件是最高信号形态；**不做整目录逐字节比对**——真实目录是**活的**（常驻进程会写日志/戳/锁），逐字节比对必然恒红 |
+ * | ③ **内容面** | 配置形态（`*.json`/`*.yml`/`*.yaml`/`*.toml`）的 `sha256`（**排除体积区**：`venv`/`node_modules`/`packs-cache`/`backup*`/浏览器 profile…，理由逐条写在 `BULK_EXCLUDE`） | "改配置"和"新建文件"是两种事故形态；`*.jsonl` 追加型台账**只走**②（不比对内容，否则每次追加都红） |
+ *
+ * **判定**：②③ 的每一条变化都要被 **`CHURN_ALLOW` 允许表**解释（`glob` + `kinds` + **必写理由** + **锚点**），
+ * 解释不了的 = `violation`（未允许的新增）。允许表的卫生沿用过期的规矩 ——
+ * **条目锚点消失 ⇒ `W-churn` 报出**（锚点两种：`path` 该 glob 在真实目录里已匹配不到任何路径 /
+ * `source` 仓库里点名"谁会造它"的源码文件或其内特征串已不在）⇒ 不留"假绿空间"。
+ *
+ * **姿态（2026-10-04 起步：report-only）**：②③ 的变化**默认只报告、exit 0**（允许表稳定前不判红，
+ * 也**不改 run-tests.sh 的整体退出码语义**）；`--strict` 才让 `violation` 非零。① **不在此列**：
+ * 关键文件变了 ⇒ 仍然 exit 1（原语义，run-tests.sh 的失败判据靠它）。
+ *
+ * ## 三、用法与退出码
+ * ```
+ * node scripts/check-test-env-safety.mjs                       # 扫描（0 通过 / 1 有命中 / 2 用法错误）
+ * node scripts/check-test-env-safety.mjs --json
+ * node scripts/check-test-env-safety.mjs --root <dir>          # 换根（夹具自证用）
+ * node scripts/check-test-env-safety.mjs --snapshot <file>      # 跑测试前：快照真实数据目录（三层）
+ * node scripts/check-test-env-safety.mjs --verify <file>        # 跑测试后：比对（关键文件变了 ⇒ exit 1）
+ * node scripts/check-test-env-safety.mjs --verify <file> --strict   # 未允许的新增也判红（exit 1）
+ * node scripts/check-test-env-safety.mjs --churn-allow <file>   # 换允许表（JSON；夹具自证用，输出会大声标注）
+ * node scripts/check-test-env-safety.mjs --list-churn           # 只列当前允许表 + 锚点是否还活着
+ * ```
+ * `scripts/run-tests.sh` 已接线：跑前 `--snapshot`、跑后 `--verify`（**不带 `--strict`** ⇒ ②③ 只报告）。
+ *
+ * ## 四、纪律
+ *   · **只读**：扫描只读文件；快照只 `stat`+`read`（绝不创建/修改/删除）；不 spawn 任何被测脚本。
+ *   · 数据目录由**内核唯一判据**算（`core/lib/argent-datadir.mjs#resolveDataDir`），本文件不另写链。
+ *   · 允许表**只**解决"真实目录是活的"这一件事：每条都要能回答"**谁**在什么时候造它"；
+ *     回答不上来 ⇒ 不许进表（那正是要报出来的东西）。
+ */
+import { readFileSync, readdirSync, existsSync, writeFileSync } from 'node:fs'
+import { dirname, join, relative, resolve, sep } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { isDirectRun } from './lib/is-direct-run.mjs'
+import { resolveDataDir } from '../core/lib/argent-datadir.mjs'
+import { diffSnapshots, snapshotPaths } from './tests/_env.mjs'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const SELF_ROOT = resolve(HERE, '..')
+
+/** 测试文件扫描面（**只扫用例**；`_*.mjs` 助手自己就是"构造环境"的地方，不在此列）。 */
+export const TEST_GLOBS = [/\.test\.mjs$/, /\.test\.py$/]
+
+/** R3：这些用例会触达数据目录（或曾出过事故）⇒ **必须**引用助手；新增同类用例请加进来。 */
+export const REQUIRED_HELPER = [
+  'argent-datadir-parity.test.mjs', 'argent-datadir.test.mjs', 'core-ledger-query.test.mjs',
+  'core-mcp-shared.test.mjs', 'core-python-pick.test.mjs', 'env-writer.test.mjs',
+  'flow-claim-verb.test.mjs', 'license-gate.test.mjs', 'notify-verb.test.mjs',
+  'role-mapping.test.mjs', 'skin-display-prefs.test.mjs', 'argent-settings-entries.test.mjs',
+  'daily-report-ask.test.mjs', 'daily-report-sections.test.mjs', 'doctor-customer.test.mjs',
+  // 2026-10-04：许可端到端用例（spawn 演练脚本，会写许可/重绑计数）⇒ 必须走助手构造环境
+  'license-e2e-v2.test.mjs',
+  // 2026-10-04：一次性激活码兑换（会**真落盘**许可/密钥/审计 + 起 http 桩子进程）⇒ 必须走助手构造环境
+  'license-activate.test.mjs',
+  // 2026-10-04：诊断上报同意步（**真跑安装器**写 config.json + 清本地队列）⇒ 一律走助手构造环境，
+  // 免得哪天有人图省事写成 `{...process.env, DSH_HOME: 夹具}`（那正是两次事故的形态）。
+  'telemetry-consent.test.mjs',
+]
+
+/**
+ * 白名单：**每条必须带理由**，且必须仍然命中对应规则（过期 ⇒ W 告警，形态照 `skills/internal.json`）。
+ * 允许的四类（评审时逐条问"它真的不会写真实数据目录吗"）：
+ *   · 只读被测对象（巡检/体检/门禁）；· 目标路径由**显式参数**给定（不靠 env 链）；
+ *   · 只读引用真实目录（做"未被碰"的证据）；· 结构性不可写（熔断/纯函数）。
+ */
+export const ALLOW = [
+  { file: 'argent-doctor-lex.test.mjs', rules: ['R1'], reason: '被测对象 scripts/argent-doctor.mjs 是**只读巡检**（脚本头明写"只读，不改任何文件"）；子进程只读真实数据目录，写入面不在本用例范围' },
+  { file: 'billing-mode.test.mjs', rules: ['R1'], reason: '子进程 `check-billing-mode.sh` 是**只读巡检**（四态/写意图熔断）；另一处 spread 只用来探测 `python -c "import yaml"`' },
+  { file: 'creds-records-placement.test.mjs', rules: ['R4'], reason: '只**读**真实 credentials 做三段结构核验（路径可由 `process.argv[2]` 覆盖；写路径全在夹具）' },
+  { file: 'ml-oauth-noninteractive.test.mjs', rules: ['R1'], reason: '授权表/凭据文件路径由 `ML_API_STORES_JSON`/`ML_API_ENV` **显式**指向夹具临时文件；被测脚本不读数据目录链' },
+  { file: 'model-auth-providers.test.mjs', rules: ['R1'], reason: '子进程 `check-model-auth.py --dsh-home <夹具>` 是**只读体检**，目标 home 由**显式参数**给定' },
+  { file: 'no-host-smoke.test.mjs', rules: ['R4'], reason: '正是"真实数据目录**未被碰**"的证据用例：只做只读快照/存在性比对，用于 M1 判据①' },
+  { file: 'plugin-python-paths.test.mjs', rules: ['R4'], reason: '`expandHome(\'~\')` 的**纯函数**语义断言（不触盘、不 spawn）' },
+  // profile-doctor.test.mjs 的 R1 豁免于 2026-10-03 删除：该用例新增「包管理器闸门」一节后改用
+  // `sanitizedEnv()`（显式构造子进程环境，不继承调用方实例开关）⇒ R1 **不再命中**，
+  // 留着就是门禁自己点名的"过期豁免 = 假绿空间"。
+  // 2026-10-04 补 R4：该用例要**只读**真实备份目录做"夹具没被写进去"的证据（哨兵串/夹具路径
+  // 精确搜，只归因本次运行）；它的写路径已全部由 `--backup-dir` 显式改指夹具 ——
+  // 2026-10-04 取证的 1023 份 `*.doctor-<ts>` 就堆在这个目录里（正是缺了这条隔离）。
+  { file: 'profile-doctor.test.mjs', rules: ['R4'], reason: '只**读**真实备份目录做"夹具备份没写进真实目录"的证据（哨兵串精确搜）；doctor 的写路径全部由 `--backup-dir` 显式改指夹具，不靠 env 链' },
+  { file: 'registry-merge.test.mjs', rules: ['R1'], reason: '`flow_registry.py` 合并是**只读**；注册表根由 `ARGENT_REGISTRY_ROOT` 显式指定' },
+  { file: 'repo-root.test.mjs', rules: ['R1'], reason: '`scripts/lib/repo-root.sh` 只做路径解析（纯函数式 shell 片段，零写盘）' },
+  { file: 'restart-trusted-host.test.mjs', rules: ['R1'], reason: '子进程是**假 `ps` 垫片** + `check-billing-mode.sh --fix` 熔断（结构上只能 exit 3，不写文件；不重启任何服务）' },
+  { file: 'source-port-contract.test.mjs', rules: ['R1'], reason: '`flow_sources/*` 端口契约探针（只读，参数全夹具）' },
+  { file: 'sync-scripts-core.test.mjs', rules: ['R1'], reason: '`sync-scripts.sh` 的投递面是**夹具克隆**（`ARGENT_DSH_REPO`/`ARGENT_DISH_HOME` 双显式），不落真实 `~/.argent-dsh`' },
+  { file: 'tests-isolation.test.mjs', rules: ['R4'], reason: '既有元测试：只 `grep` 真实台账找**夹具残留**（只读，不写）' },
+]
+
+/** 真实数据目录里要盯住的关键文件（事故文件 + 许可/角色/配置；**只读比较**）。 */
+export const GUARDED_FILES = ['skin.json', 'flow-ledger.jsonl', 'license-gate.jsonl', 'license.json', 'roles.json', 'gateway.json']
+
+/** ③ 内容比对的扩展名 = "配置形态"。`*.jsonl` **不在**此列：追加型台账每写一行都变 ⇒ 只走②（新增/条目数）。 */
+export const CONFIG_EXTS = ['.json', '.yml', '.yaml', '.toml']
+
+/**
+ * ③ 内容比对的**排除区**（体积区：依赖树/缓存/整树副本/浏览器 profile）。
+ * 为什么排除它们（逐条给理由，不是"看着像就跳过"）：这些目录里的 `*.json` 是**第三方产物或整树副本**，
+ * 内容变动**不指向**"测试写了真实配置"；而"往里新建文件"仍由②发现面覆盖 —— 排除的只是内容面。
+ * 锚点是路径正则（`^` 起、目录名后必须带 `/`）⇒ 误排除会被 `BULK_EXCLUDE` 的回归用例抓住。
+ */
+export const BULK_EXCLUDE = [
+  { re: /^venv\//, reason: 'Python 虚拟环境（第三方包自带 json/yaml，不是本站配置）' },
+  { re: /(?:^|\/)node_modules\//, reason: '依赖树（同上：第三方包自带 json/yaml）' },
+  { re: /^packs-cache\//, reason: '能力包缓存（整树副本，随包刷新）' },
+  { re: /^backup/, reason: '备份/整树副本区（`backup`、`backup-<ts>`、`*-backup-<ts>` 都在此）' },
+  { re: /backup-\d{8}/, reason: '同上：带时间戳的历史备份目录' },
+  { re: /^(?:chrome|firefox|\w+)-profile/, reason: '浏览器 profile（常驻进程随时落盘，且不是本站配置）' },
+  { re: /\/\.git\//, reason: '内嵌 git 元数据' },
+]
+
+/**
+ * ②③ 的**允许表**：真实数据目录是**活的**（常驻进程会写日志/戳/锁、缓存会刷新）⇒
+ * 这些"合法的 churn"必须能解释掉，剩下的才是"测试写进了真实目录"。
+ *
+ * 每条 = `{ glob, kinds, reason, anchor }`：
+ *   · `glob`   —— 相对数据目录的路径通配（`**` 跨目录段；`a/**` 连 `a` 本身一起匹配）；
+ *   · `kinds`  —— 这条覆盖哪些变化：`'add'` 新增 / `'remove'` 消失 / `'content'` 配置内容变化；
+ *   · `reason` —— **必写**（≥ 8 字）：谁会造它、什么时候造（写不清 ⇒ 不许进表）；
+ *   · `anchor` —— 过期判据（**必填**，两种）：
+ *        `{ kind: 'path' }`   该 glob 现在必须还能在真实数据目录里命中**至少一条**路径（来源消失 ⇒ 报出）；
+ *        `{ kind: 'source', file, must? }` 仓库里有"谁造它"的源码（文件必须存在；`must` 正则必须仍命中）。
+ * 纪律：**默认拒绝**。只有"能点名生产者"的 churn 才进表；回答不上"谁造的"就是判据要报的东西。
+ *
+ * 取数（2026-10-04 上线前实测，避免"凭想象放行"）：本机真实数据目录 **22562 条路径 / 1913 个配置文件**，
+ * 一个 **240 秒纯背景窗口**（无任何测试，只留三个常驻 LaunchAgent：web/keepalive/portforward）
+ * 实测 **新增 0 / 消失 0 / 内容变化 0** ⇒ 背景本身是安静的；下表是"**可能**发生且**已点名生产者**"的
+ * churn —— 真发生时会被解释掉，并**在报告里带条目 glob + 理由回显**（不是静默忽略）。
+ */
+export const CHURN_ALLOW = [
+  {
+    glob: 'telemetry/**',
+    kinds: ['add', 'remove', 'content'],
+    reason: '遥测队列/心跳由引擎自己写（`scripts/telemetry.py` 的 outbox 落点），测试期开着 ARGENT_TELEMETRY_OFF=1 也只关"发"，不关"落"',
+    anchor: { kind: 'source', file: 'scripts/telemetry.py', must: 'outbox' },
+  },
+  {
+    glob: '**/*.lock',
+    kinds: ['add', 'remove'],
+    reason: '流程认领锁（`flow-claim*.lock`）由引擎按流程分文件建/删；本机数据目录里既存 10 个即其产物',
+    anchor: { kind: 'path' },
+  },
+  {
+    glob: '**/*.tmp',
+    kinds: ['add', 'remove', 'content'],
+    reason: '落盘的"先写临时文件再改名"形态（如 `.crontab.tmp`）',
+    anchor: { kind: 'path' },
+  },
+  {
+    glob: 'notify-outbox/**',
+    kinds: ['add', 'remove', 'content'],
+    reason: '通知幂等标记 + 投递审计（`core/lib/notify/dedup.mjs#OUTBOX_DIRNAME`）；本机还没有这个目录 ⇒ 用 `source` 锚点',
+    anchor: { kind: 'source', file: 'core/lib/notify/dedup.mjs', must: "OUTBOX_DIRNAME = 'notify-outbox'" },
+  },
+  {
+    glob: '.DS_Store',
+    kinds: ['add', 'remove', 'content'],
+    reason: 'macOS Finder 自己往被浏览过的目录里写（数据目录根下既存一份）',
+    anchor: { kind: 'path' },
+  },
+  {
+    glob: '.*.stamp',
+    kinds: ['add', 'remove', 'content'],
+    reason: '**节流戳**这一类（`*.stamp` 由常驻巡检/触发器按周期刷新，用来"多久做一次"；本机数据目录根下既存 4 个即其产物）',
+    anchor: { kind: 'path' },
+  },
+  {
+    glob: 'cdp-port-map.json',
+    kinds: ['content'],
+    reason: 'CDP 端口表由常驻巡检（`scripts/poll-fulfillment.sh`/`orchestrator.py`）按浏览器实际端口刷新',
+    anchor: { kind: 'path' },
+  },
+  {
+    glob: 'packs-cache/**',
+    kinds: ['add', 'remove', 'content'],
+    reason: '能力包**本地留档缓存**：`install-argent.mjs --from-packs` 装一版就多一个 `<能力>-<版本>/` 目录（回滚原料），换版本必然新增一大批路径',
+    anchor: { kind: 'path' },
+  },
+]
+
+/** 去掉行注释（行级；粗略但足够——判据是"代码里出现"，注释里的说明不算）。 */
+function stripComments(text) {
+  return text.split('\n').filter((l) => {
+    const s = l.trim()
+    return !(s.startsWith('*') || s.startsWith('//') || s.startsWith('#'))
+  }).join('\n')
+}
+
+/**
+ * 文件内**局部豁免**：`// test-env-safety-allow: R4 —— 只读引用真实数据目录里的 XX 夹具`。
+ *
+ * 为什么两套豁免机制（ALLOW 表 + 文件内 pragma）：
+ *   · **ALLOW 表**（本文件上方）= 跨文件、需集中评审的例外；
+ *   · **pragma** = 与**文件强绑定**的例外（改名不失效、就近可读）。
+ * 两者都**必须带理由**（pragma 理由 < 8 字视为无效 ⇒ 该规则照样命中），并在 `--json` 里逐条回显。
+ */
+export function pragmasOf(text) {
+  const out = []
+  for (const m of String(text || '').matchAll(/test-env-safety-allow:\s*(R\d)\s*(?:——|--|:)\s*([^\n]*)/g)) {
+    const reason = m[2].replace(/\*\/\s*$/, '').trim()
+    if (reason.length >= 8) out.push({ rule: m[1], reason })
+  }
+  return out
+}
+
+const toPosix = (p) => p.split(sep).join('/')
+
+/** 列出扫描面里的用例文件（仓库相对 POSIX 路径 → 绝对路径）。 */
+export function listTests(root) {
+  const dir = join(root, 'scripts', 'tests')
+  if (!existsSync(dir)) return []
+  return readdirSync(dir).filter((f) => TEST_GLOBS.some((re) => re.test(f)) && !f.startsWith('_')).sort()
+    .map((f) => ({ name: f, abs: join(dir, f), rel: toPosix(relative(root, join(dir, f))) }))
+}
+
+/**
+ * 单文件判据（纯函数；`readFile` 可注入）。
+ * `applyAllow=false` ⇒ 返回**未过滤**命中（白名单过期检测要用它：豁免的规则必须**仍然命中**）。
+ * @returns {{file:string, hits:Array<{rule:string, detail:string, line:number}>}}
+ */
+export function scanFile(entry, { readFile = (p) => readFileSync(p, 'utf8'), applyAllow = true } = {}) {
+  const raw = readFile(entry.abs)
+  const text = stripComments(raw || '')
+  const hits = []
+  const pragmas = pragmasOf(raw)
+  const allow = applyAllow
+    ? new Set([...ALLOW.filter((a) => a.file === entry.name).flatMap((a) => a.rules), ...pragmas.map((p) => p.rule)])
+    : new Set()
+  const spread = /\.\.\.process\.env|os\.environ\.copy\(\)|\*\*os\.environ/.test(text)
+  const neutralized = /sanitizedEnv\(|ARGENT_DATA_DIR|DSH_HOME/.test(text)
+  if (spread && !neutralized && !allow.has('R1')) {
+    hits.push({ rule: 'R1', line: lineOf(raw, /\.\.\.process\.env|os\.environ\.copy\(\)|\*\*os\.environ/), detail: 'spread 调用方 env 却全文件没有 sanitizedEnv(/ARGENT_DATA_DIR/DSH_HOME ⇒ 子进程会继承**实例级开关**' })
+  }
+  const resolves = /resolveDataDir\(|resolve_data_dir\(/.test(text)
+  const asserts = /assertInsideFixture\(/.test(text)
+  if (resolves && !asserts && !allow.has('R2')) {
+    hits.push({ rule: 'R2', line: lineOf(raw, /resolveDataDir\(|resolve_data_dir\(/), detail: '调了数据目录判据却没 assertInsideFixture( ⇒ 夹具未自证"算出来的路径在夹具内"' })
+  }
+  if (REQUIRED_HELPER.includes(entry.name) && !/sanitizedEnv\(|assertInsideFixture\(|_env\.mjs/.test(text)) {
+    hits.push({ rule: 'R3', line: 1, detail: '在 REQUIRED_HELPER 名单里（会触达数据目录）却没引用 scripts/tests/_env.mjs 助手' })
+  }
+  if (!allow.has('R4')) {
+    for (const [i, l] of text.split('\n').entries()) {
+      if (/homedir\(/.test(l) && /\.dsh|argent/i.test(l)) {
+        hits.push({ rule: 'R4', line: i + 1, detail: `代码行用 homedir() 拼真实数据目录路径：${l.trim().slice(0, 100)}` })
+      }
+    }
+  }
+  return { file: entry.name, hits, pragmas }
+}
+
+const lineOf = (text, re) => { const i = String(text || '').split('\n').findIndex((l) => re.test(l)); return i < 0 ? 1 : i + 1 }
+
+/**
+ * 允许表（②③）的体检面：锚点是否还活着要靠**真实数据目录的路径集合** ⇒ 默认自己走一遍（只读）。
+ * 换根扫描（夹具自证）时数据目录由调用方给（`deps.dataDir`）。
+ */
+export function churnTreePaths(deps = {}) {
+  if (Array.isArray(deps.treePaths)) return deps.treePaths
+  const dir = deps.dataDir !== undefined ? deps.dataDir : resolveDataDir({ env: deps.env || process.env }).dir
+  return existsSync(dir) ? walkTree(dir, deps.readdir ? { readdir: deps.readdir } : {}).rows.map((r) => r.path) : []
+}
+
+/** 全量扫描（`root` 可换 ⇒ 夹具自证）。 */
+export function scanAll(root = SELF_ROOT, deps = {}) {
+  const entries = listTests(root)
+  const files = entries.map((e) => scanFile(e, deps))
+  const rawFiles = entries.map((e) => scanFile(e, { ...deps, applyAllow: false }))
+  const hits = files.flatMap((f) => f.hits.map((h) => ({ ...h, file: f.file })))
+  const pragmas = files.flatMap((f) => f.pragmas.map((p) => ({ ...p, file: f.file })))
+  const churn = deps.churnAllow || CHURN_ALLOW
+  // W-churn：允许表（②③）的过期/写法体检 —— 与白名单过期同形态（条目烂掉 ⇒ 假绿空间）
+  const staleChurn = auditChurnAllow(churn, churnTreePaths(deps), { root: SELF_ROOT })
+  // W：白名单过期（文件不存在 / 理由空 / 规则不再命中）
+  const stale = []
+  const present = new Set(entries.map((e) => e.name))
+  const isSelf = resolve(root) === resolve(SELF_ROOT)   // 换根扫描（夹具自证）时白名单天然"对不上"，不报腐烂
+  for (const p of pragmas) {
+    const raw = rawFiles.find((x) => x.file === p.file)
+    if (!raw || !raw.hits.some((h) => h.rule === p.rule)) stale.push({ file: p.file, why: `pragma ${p.rule} 已不再命中 ⇒ 该行应删除（过期豁免 = 假绿空间）` })
+  }
+  for (const a of ALLOW) {
+    if (!a.reason || !String(a.reason).trim()) stale.push({ file: a.file, why: '理由为空' })
+    if (!present.has(a.file)) {
+      if (isSelf) stale.push({ file: a.file, why: '白名单指向的测试文件不存在（名单腐烂）' })
+      continue
+    }
+    const raw = rawFiles.find((x) => x.file === a.file)
+    for (const r of a.rules) {
+      if (!raw || !raw.hits.some((h) => h.rule === r)) stale.push({ file: a.file, why: `${r} 已不再命中 ⇒ 该白名单条目应删除（过期豁免 = 假绿空间）` })
+    }
+  }
+  return { root, scanned: entries.length, hits, stale, pragmas, allow: ALLOW.length, required: REQUIRED_HELPER.length, churn: churn.length, staleChurn }
+}
+
+// ── R5 的三层：目录级发现（②）+ 配置内容面（③）──────────────────────────────
+/**
+ * 路径通配 → 正则（无依赖）。语义（只在需要的范围内实现，够用且可测）：
+ *   `*`   ⇒ 单层内任意字符（不跨 `/`）；`?` ⇒ 单层内一个字符；
+ *   `**`  ⇒ 跨目录段（`**\/` 允许**零个**目录段 ⇒ `**\/*.lock` 也匹配根下的 `x.lock`）；
+ *   `a/**` ⇒ 连 `a` 本身一起匹配（目录被新建时也命中）。
+ */
+export function globToRegExp(glob) {
+  const esc = (c) => c.replace(/[.+^${}()|[\]\\]/g, '\\$&')
+  const g = String(glob || '')
+  let re = ''
+  for (let i = 0; i < g.length; i++) {
+    const c = g[i]
+    if (c === '*') {
+      if (g[i + 1] === '*') {
+        i++
+        if (g[i + 1] === '/') { i++; re += '(?:.*/)?' }                 // `**/` ⇒ 零个或多个目录段
+        else if (re.endsWith('/')) { re = re.slice(0, -1) + '(?:/.*)?' } // `a/**` ⇒ 也匹配 `a` 本身
+        else re += '.*'
+      } else re += '[^/]*'
+    } else if (c === '?') re += '[^/]'
+    else re += esc(c)
+  }
+  return new RegExp(`^${re}$`)
+}
+
+/**
+ * ② 真实数据目录的**路径集合**（只读；`kind`：f 文件 / d 目录 / l 符号链接）。
+ * 符号链接**当叶子**处理（不跟进去 ⇒ 不会因为链成环而无限走）。
+ * @returns {{ rows: Array<{kind:string, path:string}>, counts: {files:number, dirs:number, links:number, total:number} }}
+ */
+export function walkTree(dir, { readdir = readdirSync } = {}) {
+  const rows = []
+  const counts = { files: 0, dirs: 0, links: 0, total: 0 }
+  if (!existsSync(dir)) return { rows, counts }
+  const stack = ['']
+  while (stack.length) {
+    const rel = stack.pop()
+    const abs = rel ? join(dir, rel) : dir
+    let ents = []
+    try { ents = readdir(abs, { withFileTypes: true }) } catch { continue }   // 读不动就跳过（只读门禁不许因为权限而崩）
+    for (const e of ents) {
+      const child = rel ? `${rel}/${e.name}` : e.name
+      if (e.isSymbolicLink()) { rows.push({ kind: 'l', path: child }); counts.links++; continue }
+      if (e.isDirectory()) { rows.push({ kind: 'd', path: child }); counts.dirs++; stack.push(child); continue }
+      rows.push({ kind: 'f', path: child }); counts.files++
+    }
+  }
+  rows.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))
+  counts.total = rows.length
+  return { rows, counts }
+}
+
+/** 压缩成快照里的形态（`<kind>\t<path>`，省空间且可直接当集合用）。 */
+export const treeKeys = (rows) => (rows || []).map((r) => `${r.kind}\t${r.path}`)
+const parseTreeKey = (k) => { const i = String(k).indexOf('\t'); return { kind: String(k).slice(0, i), path: String(k).slice(i + 1) } }
+
+/** ② 的差：**只报新增**（+ 单独报"消失"，因为删真实文件比新建更该查）。纯函数。 */
+export function diffTree(beforeKeys, afterKeys) {
+  const b = new Set(beforeKeys || [])
+  const a = new Set(afterKeys || [])
+  return {
+    added: (afterKeys || []).filter((k) => !b.has(k)).map(parseTreeKey),
+    removed: (beforeKeys || []).filter((k) => !a.has(k)).map(parseTreeKey),
+  }
+}
+
+/** ③ 内容面的取值面：配置形态扩展名 ∧ 不在 `BULK_EXCLUDE` 里（纯函数 ⇒ 可测）。 */
+export function isConfigPath(relPath, exts = CONFIG_EXTS, excludes = BULK_EXCLUDE) {
+  const p = String(relPath || '')
+  if (!exts.some((e) => p.toLowerCase().endsWith(e))) return false
+  return !excludes.some((x) => x.re.test(p))
+}
+
+/** ③ 内容快照：只 `stat`+`read`（**只读**；不创建/修改/删除）。
+ *  ⛔ **不含** `GUARDED_FILES`（只按**根下同名**精确排除，不是"任意层级同名文件"）：那 6 个由①按
+ *  **更严**的判据（size/mtime/sha256 + 判红）盯着 ⇒ 同一件事不在两层各报一次（否则 `--strict`
+ *  的"未解释变化"计数会虚高）。 */
+export function configSnapshot(dir, rows, { snapshot = snapshotPaths } = {}) {
+  const keyPaths = new Set(GUARDED_FILES)
+  return snapshot((rows || [])
+    .filter((r) => r.kind === 'f' && isConfigPath(r.path) && !keyPaths.has(r.path))
+    .map((r) => join(dir, r.path)))
+}
+
+/** 允许表条目的**锚点**是否还活着（过期判据；`treePaths` = 真实目录的相对路径集合）。 */
+export function churnAnchorStatus(entry, treePaths, { root = SELF_ROOT, readFile = (p) => readFileSync(p, 'utf8') } = {}) {
+  const a = entry.anchor
+  if (!a || !a.kind) return { ok: false, why: '没有锚点（anchor）—— 允许表条目必须说明"过期怎么判"' }
+  if (a.kind === 'source') {
+    const p = join(root, a.file)
+    if (!existsSync(p)) return { ok: false, why: `锚点来源文件已不在：${a.file}` }
+    if (a.must) {
+      let text = ''
+      try { text = readFile(p) } catch { return { ok: false, why: `锚点来源读不出来：${a.file}` } }
+      if (!new RegExp(a.must).test(text)) return { ok: false, why: `锚点来源 ${a.file} 里已找不到特征串 ${JSON.stringify(a.must)}` }
+    }
+    return { ok: true, detail: `source ${a.file}${a.must ? ` ∧ /${a.must}/` : ''}` }
+  }
+  const re = globToRegExp(entry.glob)
+  const hit = (treePaths || []).find((p) => re.test(p))
+  return hit ? { ok: true, detail: `path，命中 ${hit}` } : { ok: false, why: `该 glob 在真实数据目录里**已匹配不到任何路径**（来源消失）` }
+}
+
+/** ③ 的差：只认**内容**（sha256）变化 —— mtime 变了内容没变不算事故（`touch` 不该判红）。纯函数。 */
+export function diffConfigs(beforeList, afterList) {
+  const b = new Map((beforeList || []).map((e) => [e.path, e]))
+  const changed = []
+  for (const a of afterList || []) {
+    const p = b.get(a.path)
+    if (!p || !p.exists || !a.exists) continue          // 新增/消失归②（避免同一件事被报两次）
+    if (p.sha256 !== a.sha256) changed.push({ path: a.path, why: `内容 sha256 变了（${String(p.sha256).slice(0, 12)} → ${String(a.sha256).slice(0, 12)}）` })
+  }
+  return { changed }
+}
+
+/** 允许表整体体检：理由为空 / glob 非法 / 锚点死了 ⇒ 报出来（**W-churn**，形态照白名单过期）。 */
+export function auditChurnAllow(entries, treePaths, deps = {}) {
+  const stale = []
+  for (const e of entries || []) {
+    if (!e.reason || String(e.reason).trim().length < 8) stale.push({ glob: e.glob, why: '理由为空或不足 8 字（允许表条目必须写明"谁会造它"）' })
+    if (!Array.isArray(e.kinds) || !e.kinds.length || e.kinds.some((k) => !['add', 'remove', 'content'].includes(k))) {
+      stale.push({ glob: e.glob, why: `kinds 缺失或含未知项（${JSON.stringify(e.kinds)}；合法值 add/remove/content）` })
+    }
+    try { globToRegExp(e.glob) } catch { stale.push({ glob: e.glob, why: 'glob 解析失败' }) }
+    const st = churnAnchorStatus(e, treePaths, deps)
+    if (!st.ok) stale.push({ glob: e.glob, why: `${st.why} ⇒ 过期豁免（该条目应删除或更新）` })
+  }
+  return stale
+}
+
+/** 一条 churn 是否被允许表解释掉（返回命中的条目，或 null）。 */
+export function matchChurn(entries, { path, kind }) {
+  for (const e of entries || []) {
+    if (!(e.kinds || []).includes(kind)) continue
+    if (globToRegExp(e.glob).test(path)) return e
+  }
+  return null
+}
+
+/**
+ * **真实数据目录的三层快照**（只读；数据目录由内核判据算，不另写链）。
+ *   ① `entries` 关键文件（size/mtime/sha256）—— 2026-10-03 起就在，**语义不变**；
+ *   ② `tree`    全树路径集合（目录级发现）；
+ *   ③ `configs` 配置形态内容 sha256（排除体积区）。
+ * 旧快照（没有 `tree`/`configs`）仍可 `--verify`：③② 跳过并在输出里点名（不假装比过）。
+ */
+export function guardedSnapshot({ env = process.env, readdir = readdirSync, snapshot = snapshotPaths } = {}) {
+  const dir = resolveDataDir({ env }).dir
+  const tree = walkTree(dir, { readdir })
+  return {
+    dataDir: dir,
+    entries: snapshot(GUARDED_FILES.map((f) => join(dir, f))),
+    tree: treeKeys(tree.rows),
+    treeCounts: tree.counts,
+    configs: configSnapshot(dir, tree.rows, { snapshot }),
+  }
+}
+
+// ── CLI ────────────────────────────────────────────────────────────────────
+const relOf = (dir, p) => relative(dir, p).split(sep).join('/')
+
+/** 允许表来源：默认内置；`--churn-allow <file>` 可换（**输出会大声标注**，避免"悄悄放宽"）。 */
+function loadChurnAllow(file) {
+  if (!file) return { entries: CHURN_ALLOW, source: '内置 CHURN_ALLOW' }
+  const raw = JSON.parse(readFileSync(file, 'utf8'))
+  const entries = Array.isArray(raw) ? raw : raw.entries
+  if (!Array.isArray(entries)) throw new Error('允许表文件必须是数组，或 { entries: [...] }')
+  return { entries, source: `⚠️ 显式覆盖 --churn-allow ${file}（内置表**未生效**）` }
+}
+
+function main(argv) {
+  let root = SELF_ROOT
+  let asJson = false
+  let snapshot = ''
+  let verify = ''
+  let strict = false
+  let churnAllowFile = ''
+  let listChurn = false
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--json') { asJson = true; continue }
+    if (a === '--strict') { strict = true; continue }
+    if (a === '--list-churn') { listChurn = true; continue }
+    if (a === '--root') { const v = argv[i + 1]; if (!v || v.startsWith('--')) return { code: 2, out: '❌ --root 缺值' }; root = resolve(v); i++; continue }
+    if (a === '--snapshot') { const v = argv[i + 1]; if (!v || v.startsWith('--')) return { code: 2, out: '❌ --snapshot 缺值' }; snapshot = resolve(v); i++; continue }
+    if (a === '--verify') { const v = argv[i + 1]; if (!v || v.startsWith('--')) return { code: 2, out: '❌ --verify 缺值' }; verify = resolve(v); i++; continue }
+    if (a === '--churn-allow') { const v = argv[i + 1]; if (!v || v.startsWith('--')) return { code: 2, out: '❌ --churn-allow 缺值' }; churnAllowFile = resolve(v); i++; continue }
+    if (a === '-h' || a === '--help') return { code: 0, out: readFileSync(fileURLToPath(import.meta.url), 'utf8').split('*/')[0].replace(/^\/\*\*?/, '').trim() }
+    return { code: 2, out: `❌ 未知参数：${a}（用法：node scripts/check-test-env-safety.mjs [--root <dir>] [--snapshot <file>|--verify <file>] [--strict] [--churn-allow <file>] [--list-churn] [--json]）` }
+  }
+  if (!existsSync(root)) return { code: 2, out: `❌ 根不存在：${root}` }
+  let churn = { entries: CHURN_ALLOW, source: '内置 CHURN_ALLOW' }
+  try { churn = loadChurnAllow(churnAllowFile) } catch (e) { return { code: 2, out: `❌ 允许表读不出来：${churnAllowFile}（${(e && e.message) || e}）` } }
+
+  if (listChurn) {
+    const treePaths = churnTreePaths({})
+    const stale = auditChurnAllow(churn.entries, treePaths)
+    const lines = ['', `【R5 允许表（churn）】${churn.entries.length} 条 ｜ 来源：${churn.source}`, `  锚点体检面：真实数据目录 ${treePaths.length} 条路径`]
+    for (const e of churn.entries) {
+      const st = churnAnchorStatus(e, treePaths)
+      lines.push(`  ${st.ok ? '✅' : '⚠️'} [${(e.kinds || []).join('/')}] ${e.glob}${st.ok ? `（锚点活着：${st.detail}）` : `（${st.why}）`}`)
+      lines.push(`       理由：${e.reason}`)
+    }
+    for (const s of stale) lines.push(`  ⚠️  [W-churn] ${s.glob}：${s.why}`)
+    lines.push(`  结论：${stale.length ? `⚠️ ${stale.length} 条过期/写法问题` : '✅ 全部活着（锚点可查、理由齐备）'}`)
+    return { code: 0, out: lines.join('\n'), json: { churn: churn.entries, source: churn.source, stale } }
+  }
+
+  if (snapshot) {
+    const snap = guardedSnapshot()
+    // 唯一一次"写"：写的是**调用方指定的快照文件**（不在数据目录里），不是数据目录本身
+    writeFileSync(snapshot, JSON.stringify({ ...snap, at: new Date().toISOString() }, null, 2) + '\n')
+    const json = { ok: true, snapshot, ...snap }
+    const c = snap.treeCounts || {}
+    return {
+      code: 0, json,
+      out: asJson ? JSON.stringify(json, null, 2)
+        : `📸 真实数据目录快照已写：${snapshot}\n   目录 ${snap.dataDir}`
+          + `\n   ① 关键文件 ${snap.entries.length} 个 ｜ ② 全树路径 ${c.total || 0} 条（文件 ${c.files || 0} / 目录 ${c.dirs || 0} / 链接 ${c.links || 0}）`
+          + ` ｜ ③ 配置形态内容 ${snap.configs.length} 个 sha256`,
+    }
+  }
+  if (verify) {
+    let before = null
+    try { before = JSON.parse(readFileSync(verify, 'utf8')) } catch (e) { return { code: 2, out: `❌ 快照读不出来：${verify}（${(e && e.message) || e}）` } }
+    const after = guardedSnapshot()
+    // ① 关键文件面（**原语义**：变了 ⇒ exit 1）
+    const d = diffSnapshots(before.entries || [], after.entries || [])
+    const keyChanged = d.changed
+    // ② 目录级发现面（只报新增；消失单独提示）
+    const hasTree = Array.isArray(before.tree)
+    const td = hasTree ? diffTree(before.tree, after.tree || []) : { added: [], removed: [] }
+    const judge = (rows, kind) => rows.map((r) => ({ ...r, allow: matchChurn(churn.entries, { path: r.path, kind }) }))
+    const added = judge(td.added, 'add')
+    const removed = judge(td.removed, 'remove')
+    const violations = added.filter((x) => !x.allow)
+    const allowedAdds = added.filter((x) => x.allow)
+    const removedUnallowed = removed.filter((x) => !x.allow)
+    // ③ 内容面（只认 sha256；`*.jsonl` 台账不在此列）
+    const hasConf = Array.isArray(before.configs)
+    const cfgChangedRaw = hasConf ? diffConfigs(before.configs, after.configs || []).changed : []
+    const cfgChanged = cfgChangedRaw.map((c) => ({ ...c, rel: relOf(after.dataDir, c.path), allow: matchChurn(churn.entries, { path: relOf(after.dataDir, c.path), kind: 'content' }) }))
+    const cfgViolations = cfgChanged.filter((x) => !x.allow)
+    // 允许表体检（锚点活着吗）
+    const staleChurn = auditChurnAllow(churn.entries, (after.tree || []).map((k) => parseTreeKey(k).path))
+    const okKey = keyChanged.length === 0
+    const okNew = violations.length === 0 && cfgViolations.length === 0
+    const code = (!okKey || (strict && !okNew)) ? 1 : 0
+    const json = {
+      ok: okKey && (strict ? okNew : true), dataDir: after.dataDir, verify, strict, churnSource: churn.source,
+      keyChanged, added, removed, removedUnallowed, configChanged: cfgChanged, violations, configViolations: cfgViolations,
+      allowedChurn: allowedAdds.length, staleChurn, treeCounts: after.treeCounts, configCount: (after.configs || []).length,
+      layers: { tree: hasTree, configs: hasConf },
+      // 兼容旧字段名：`changed` 一直是"①关键文件的变化明细"，这里保持同值（别的脚本/会话可能按它取数）
+      changed: keyChanged,
+      note: okKey ? (okNew ? '未变' : '新增/改动未被允许表解释（默认只报告；--strict 才判红）') : '真实数据目录的关键文件在测试期间被改过',
+    }
+    if (asJson) return { code, json, out: JSON.stringify(json, null, 2) }
+
+    const c = after.treeCounts || {}
+    const lines = ['', `【R5 结果判据】真实数据目录 ${after.dataDir}`, `  ① 关键文件（${(after.entries || []).length} 个，size/mtime/sha256）：${okKey ? '✅ 未变' : `❌ 变了 ${keyChanged.length} 个`}`]
+    for (const x of keyChanged) lines.push(`     ❌ ${x.path}：${x.why}`)
+    if (okKey === false) lines.push('     ⇒ 有测试在用真实数据目录（不是夹具）——查 `node scripts/check-test-env-safety.mjs --json` 的命中项。')
+    lines.push(`  ② 目录级发现（路径 ${hasTree ? c.total : '—'} 条：文件 ${c.files || 0} / 目录 ${c.dirs || 0} / 链接 ${c.links || 0}）：新增 ${added.length} ｜ 消失 ${removed.length}`
+      + (hasTree ? '' : '　⚠️ 快照是旧格式（无 tree）⇒ 本层**没比**'))
+    for (const x of violations) lines.push(`     ❌ 新增（未被允许表解释）：${x.kind} ${x.path}`)
+    for (const x of allowedAdds) lines.push(`     ℹ️  新增（允许）：${x.kind} ${x.path}　← [${x.allow.glob}] ${x.allow.reason}`)
+    for (const x of removed) lines.push(`     ${x.allow ? 'ℹ️ ' : '⚠️ '} 消失${x.allow ? '（允许）' : '（**未**被允许表解释）'}：${x.kind} ${x.path}${x.allow ? `　← [${x.allow.glob}]` : ''}`)
+    lines.push(`  ③ 配置形态内容（${hasConf ? (after.configs || []).length : '—'} 个 sha256）：${!hasConf ? '⚠️ 快照是旧格式（无 configs）⇒ 本层**没比**' : (cfgChanged.length ? `变化 ${cfgChanged.length} 个` : '✅ 未变')}`)
+    for (const x of cfgViolations) lines.push(`     ❌ 内容变化（未被允许表解释）：${x.rel}　${x.why}`)
+    for (const x of cfgChanged.filter((y) => y.allow)) lines.push(`     ℹ️  内容变化（允许）：${x.rel}　← [${x.allow.glob}] ${x.allow.reason}`)
+    for (const s of staleChurn) lines.push(`  ⚠️  [W-churn] ${s.glob}：${s.why}`)
+    lines.push(`  允许表：${churn.entries.length} 条（${churn.source}）`)
+    lines.push(`  结论：${okKey ? '✅ 关键文件未变' : '❌ 关键文件被改（**判红**）'}`
+      + `；②③ ${okNew ? '无未解释变化' : `有 ${violations.length + cfgViolations.length} 条未解释变化（默认**只报告**${strict ? '；`--strict` 已开 ⇒ 判红' : '；加 `--strict` 才判红'}）`}`
+      + `${staleChurn.length ? `；允许表过期 ${staleChurn.length} 条` : ''}`)
+    return { code, json, out: lines.join('\n') }
+  }
+
+  const r = scanAll(root, { churnAllow: churn.entries })
+  const bad = r.hits.length
+  if (asJson) return { code: bad ? 1 : 0, out: JSON.stringify({ ...r, code: bad ? 1 : 0 }, null, 2), json: { ...r, code: bad ? 1 : 0 } }
+  const lines = ['', '【测试环境卫生（2026-10-03 两次事故后补）】',
+    `  扫描 ${r.scanned} 个用例 ｜ 白名单 ${r.allow} 条 ｜ 文件内 pragma ${r.pragmas.length} 条 ｜ 必修助手名单 ${r.required} 个 ｜ R5 允许表 ${r.churn} 条`]
+  for (const h of r.hits) lines.push(`  ❌ [${h.rule}] ${h.file}:${h.line} ${h.detail}`)
+  for (const p of r.pragmas) lines.push(`  ℹ️  [pragma] ${p.file} 豁免 ${p.rule}：${p.reason}`)
+  for (const s of r.stale) lines.push(`  ⚠️  [W] ${s.file}：${s.why}`)
+  for (const s of r.staleChurn) lines.push(`  ⚠️  [W-churn] ${s.glob}：${s.why}`)
+  lines.push(`  结论：${bad ? `❌ ${bad} 条命中` : '✅ 通过'}（未用助手就触达真实数据目录的用例 = 0）`
+    + (r.stale.length ? `；白名单过期 ${r.stale.length} 条` : '')
+    + (r.staleChurn.length ? `；R5 允许表过期 ${r.staleChurn.length} 条` : ''))
+  return { code: bad ? 1 : 0, out: lines.join('\n') }
+}
+
+if (isDirectRun(import.meta.url)) {
+  const { code, out } = main(process.argv.slice(2))
+  console.log(out)
+  process.exit(code)
+}