@whyshu/argent-engine 0.0.0-stage → 0.6.1

package/engine/scripts/check-pack-closure.mjs

@@ -0,0 +1,661 @@
+#!/usr/bin/env node
+/**
+ * check-pack-closure.mjs —— 能力包「运行期闭包」体检：**按 `pack.engine` + files 清单解析
+ * 静态 import / 子进程调用图，报告"运行期需要但未在包内"的文件**（只读；2026-10-04 立）。
+ *
+ * ## 为什么有它（事故）
+ * 能力包以前只有"清单里声明的文件是否存在"这一道校验（`capability_pack.py --validate`），
+ * 而**清单本身对不对**没人查。实测（"包内独立运行复验"）：
+ *   · `scripts/lib/argent-datadir.mjs` 与 `scripts/check-skill-classification.mjs` **漏在
+ *     `pack.engine` 之外** —— 它们是被 `core/lib/*.mjs` import 的**运行期**件；
+ *   · 后果：把包 build 到空目录后，`node core/cli/argent.mjs --help` **当场
+ *     ERR_MODULE_NOT_FOUND**（不是降级、不是告警，是直接崩）；
+ *   · `capability_pack.py --validate` 全程 ✅ —— 因为缺的那个文件**根本没进清单**，
+ *     "校验清单里的文件都在"对它天然为真。
+ * ⇒ 缺的是"**从入口出发把运行期真会读到的文件走一遍**"这一步。本脚本补的就是它。
+ *
+ * ## 它做什么（三步，全部只读）
+ *   1. **拿真实清单**：逐个能力跑 `scripts/capability_pack.py --describe <c> --json`
+ *      （复用现有派生逻辑，**不自己算第二份清单**）；包内文件集 = `integrity` 的键
+ *      （`integrity` 已把目录展开成真实文件）+ build 时会生成的 `scripts/flow-requirements.json`。
+ *   2. **解析运行期引用图**（对包内每个 `.mjs/.js/.cjs/.py/.sh`，先剥注释再解析）：
+ *      · JS：静态 `import`/`export … from`/`require()`/`import()` 的**相对** specifier；
+ *      · Python：行首 `import X` / `from X import` / `from .mod import`（含 `from . import 子模块`）；
+ *      · 子进程/读写路径：`readFileSync|execFileSync|spawnSync|subprocess.*|open|Path` 等
+ *        I/O 调用**实参窗口内**的字面量路径（`join(...)`/`ROOT / "scripts" / "x.py"` 这类
+ *        全字面量的拼接可还原；`HERE`/`__dirname` → 文件所在目录，`ROOT`/`REPO` → 仓库根）；
+ *      · `.sh`：`node|python3|bash <路径>`、`source <路径>`、行内出现的仓库相对路径。
+ *   3. **报差集**：引用到、在仓库里**确实存在**、但**不在包内**的文件 ⇒ 缺件（并给出引用者与行号）。
+ *      再对缺件本身做有界 BFS（深度 ≤ 3）⇒ "补上它之后还会牵出谁"也一并列出，避免补一半。
+ *
+ * ## 覆盖范围（诚实标注）
+ * **覆盖**：`core/**` 与 `scripts/**` 里被包内文件**静态引用**的一切 —— 静态 ESM/CJS import、
+ * Python import（含相对导入）、子进程/读写调用里的字面量路径、shell 里点名的脚本。
+ * `core/cli/argent.mjs`、`core/mcp/*.mjs`、四个带 flow 能力共用的 `scripts/**` 引擎件都在扫面内。
+ * **已知盲区**（静态分析**必然**漏，别把它当"包一定完整"的证明）：
+ *   ① **动态 require / 运行时拼路径**：`import(name)`、`require(variable)`、`join(dir, argv[0])`、
+ *      模板串里插变量 ⇒ 解析不出目标（本脚本会把这些"像路径但没落地"的字面量计入
+ *      「未解析」计数并举例，**看得见**，但不是判定）；
+ *   ② **JSON/YAML 里声明的路径**：注册表/适配器契约/preset 组合里的文件引用（含清单自身的
+ *      `pack.scripts`）—— 那是"声明面"，归 `capability_pack.py --validate`；
+ *   ③ **运行期才决定的文件**：`ARGENT_DATA_DIR` 下的数据、技能目录、宿主动态挂载的 preset；
+ *   ④ **非代码文本**：提示词 `.md`/`.yml` 里提到的脚本名（散文提及 ≠ 调用点，计入会大量假阳性）；
+ *   ⑤ 环境/宿主提供的可执行（`dsh`、`lark-cli` 等）—— 它们**不在**仓库里，本就不该进包。
+ * ⇒ 结论：**本脚本绿 ≠ 包完整**；它是"静态引用面"的下界。补完缺件后仍应按
+ *   `docs/README.md` §六.9⑤ 在**空目录**里真跑一遍独立运行（那才是上界验收）。
+ *
+ * ## 用法
+ *   node scripts/check-pack-closure.mjs                    # 只报告，**恒 exit 0**（缺件只打印）
+ *   node scripts/check-pack-closure.mjs --strict           # 有缺件/豁免表有问题才 exit 1（手动跑 / 单独 CI）
+ *   node scripts/check-pack-closure.mjs --json             # 机器可读（含 exemptions / problems / 每条缺件的 via+line）
+ *   node scripts/check-pack-closure.mjs --quiet            # 只打印结论行
+ *   node scripts/check-pack-closure.mjs --capability invoice   # 只看某个能力（可重复）
+ *   node scripts/check-pack-closure.mjs --drop <仓库相对路径>  # 注入测试：从包内文件集里剔除一项
+ *                                                          #   （模拟"漏登记"，用来证明本门禁**报得出来**）
+ *   node scripts/check-pack-closure.mjs --py <解释器>       # 覆盖 python（默认 $ARGENT_PY 或 python3）
+ * 退出码：0 正常（有缺件也 0，除非 `--strict`）；1 `--strict` 且有缺件/豁免表问题；2 用法错或**量不出来**。
+ *
+ * ## 豁免表（`NOT_PACK_RUNTIME`，默认只有一条）
+ * 判为"**确实不该进包**"的个例写进脚本顶部的常量表（形态照 `kernel-purity` 的 `WHITELIST`）：
+ * 每条**必须带理由**，且**本轮必须被命中** —— 没命中就是「过期豁免」，会在报告里点名、`--strict` 下非零。
+ * 这是唯一的"合法例外"出口：**别**为了消一条缺件去放宽 `NON_RUNTIME` 的类别规则（那会连带吞掉真缺件）。
+ *
+ * ## 纪律
+ *   · **只读**：源码里零写 API（回归用例【7】静态断言）；跑 python 时带 `PYTHONDONTWRITEBYTECODE=1`
+ *     不种 `__pycache__`；不碰数据目录/台账/凭据、不联网、不改 `flow-requirements.json`；
+ *   · **防假绿**：量不出东西（0 个能力 / 0 个包内代码文件 / python 读取失败）一律 **exit 2**，
+ *     绝不打印"全部闭合"——"扫了空集也算通过"正是本脚本要修的那类翻车；
+ *   · **默认不失败**：它**不接** `scripts/run-tests.sh` 的失败判据（缺件常年可能存在，
+ *     接进去就是恒红陷阱）；回归只覆盖 `scripts/tests/pack-closure.test.mjs` 的机制断言。
+ */
+import { spawnSync } from 'node:child_process'
+import { existsSync, readFileSync, statSync } from 'node:fs'
+import { dirname, join, relative, resolve, sep } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const ROOT = resolve(HERE, '..')
+
+// ── 参数 ────────────────────────────────────────────────────────────────────
+const argv = process.argv.slice(2)
+const has = (f) => argv.includes(f)
+const valOf = (f) => {
+  const i = argv.indexOf(f)
+  return i >= 0 ? argv[i + 1] : undefined
+}
+const allOf = (f) => argv.reduce((acc, v, i) => (v === f && argv[i + 1] !== undefined ? [...acc, argv[i + 1]] : acc), [])
+if (has('-h') || has('--help')) {
+  console.log(readFileSync(fileURLToPath(import.meta.url), 'utf8').split('*/')[0].replace(/^\/\*\*?/, '').replace(/^\s*\* ?/gm, '').trim())
+  process.exit(0)
+}
+const STRICT = has('--strict')
+const JSON_OUT = has('--json')
+const QUIET = has('--quiet')
+const PY = valOf('--py') || process.env.ARGENT_PY || 'python3'
+const ONLY = allOf('--capability')
+const DROPS = new Set(allOf('--drop').map((d) => d.split(sep).join('/')))
+const MAX_DEPTH = 3
+
+/** 包内由 `--build` 生成（不在 `integrity` 里，但装到客户机上确实在包里）。 */
+const GENERATED_IN_PACK = 'scripts/flow-requirements.json'
+
+const CODE_RE = /\.(mjs|js|cjs|py|sh)$/
+const REPO_TOP_RE = /^(scripts|core|verticals|skills|presets|plugins|deploy|docs|tools)\//
+
+/**
+ * **非运行期**路径：引用了也不算缺件（客户机的能力包里**就不该有**它们）。
+ * 每条都要写清"为什么不进包"—— 否则这就是个吞掉真缺件的后门。
+ */
+const NON_RUNTIME = [
+  { re: /^scripts\/tests\//, why: '开发期测试（客户机不装；pack.engine 明确不含测试）' },
+  { re: /^scripts\/patches\//, why: 'dsh 热修补丁（宿主侧资产，不由能力包分发）' },
+  { re: /^scripts\/capability-packs\.lock\.json$/, why: '打包版本锁（仓库侧产物）' },
+  { re: /^docs\//, why: '文档' },
+  { re: /^plugins\//, why: 'L2 宿主壳（装机由宿主提供，不在能力包分发面）' },
+  { re: /(^|\/)(__pycache__|node_modules)\//, why: '构建/依赖残留' },
+  { re: /\.(test|probe)\.(mjs|py)$/, why: '测试/探针脚本' },
+  { re: /\.DS_Store$/, why: 'macOS 元数据' },
+]
+const nonRuntimeWhy = (rel) => (NON_RUNTIME.find((x) => x.re.test(rel)) || {}).why || null
+
+/**
+ * **已判定不进能力包**的运行期引用（`{rel, reason}`）。
+ *
+ * 与 {@link NON_RUNTIME} 的区别：`NON_RUNTIME` 是"**按类别**永远不该进包"（测试/文档/插件…）；
+ * 本表是"**按个例**判定不进包，但静态调用图确实指向它" —— 必须逐条写清"为什么它不是能力包的
+ * 运行期面"，否则这就是个把真缺件吞掉的后门（形态照 `kernel-purity` 的 `WHITELIST` 与
+ * `role-gateway-exemptions.json`：**默认空**、每条带理由、条目没命中 =「过期豁免」要报出来）。
+ *
+ * ⛔ 加条目前先问："它真的不在客户机的运行期面上吗？还是只是没登记？"—— 后者请写进 `pack.engine`。
+ */
+const NOT_PACK_RUNTIME = [
+  {
+    rel: 'scripts/dsh-upgrade.mjs',
+    reason: 'L2 宿主侧 dsh 升级工具：仅被 scripts/dsh-upgrade-readiness.mjs 的**可选** --gates 路径调用；'
+      + '它真正的运行期闭包是 scripts/patches/**（补丁 + verify-*.mjs）与 dsh-version-lock/**，'
+      + '那两批**按设计不随能力包分发**（docs/README.md §六.9）⇒ 塞进 pack.engine 会连带要求把补丁目录也塞进去，'
+      + '那才是错的。改判方式：写进 scripts/flow-requirements.json#pack.engine 并删掉本条目。',
+  },
+]
+const NOT_PACK_BY_REL = new Map(NOT_PACK_RUNTIME.map((x) => [x.rel, x]))
+const REASON_MIN = 12
+
+// ── 一、取真实清单（复用 capability_pack.py，不自己派生）────────────────────
+function runPack(args) {
+  const r = spawnSync(PY, [join(ROOT, 'scripts', 'capability_pack.py'), ...args], {
+    encoding: 'utf8',
+    cwd: ROOT,
+    timeout: 180000,
+    // ⛔ 不种 __pycache__（只读门禁不许写仓库）；关遥测（夹具流程的失败事件曾被推到生产告警）
+    env: { ...process.env, PYTHONDONTWRITEBYTECODE: '1', ARGENT_TELEMETRY_OFF: '1' },
+  })
+  if (r.error) return { ok: false, err: `无法执行 ${PY}：${r.error.message}` }
+  if (r.status !== 0) return { ok: false, err: `capability_pack.py ${args.join(' ')} → exit ${r.status}：${((r.stderr || '') + (r.stdout || '')).trim().slice(0, 400)}` }
+  try {
+    return { ok: true, json: JSON.parse(r.stdout) }
+  } catch (e) {
+    return { ok: false, err: `capability_pack.py ${args.join(' ')} 的输出不是 JSON：${String(e.message).slice(0, 200)}` }
+  }
+}
+
+const listed = runPack(['--list', '--json'])
+if (!listed.ok) {
+  console.error(`  ❌ 读不到能力清单（**量不出来就不算通过**）：${listed.err}`)
+  process.exit(2)
+}
+let caps = (Array.isArray(listed.json) ? listed.json : []).map((r) => r.capability).filter(Boolean)
+caps = caps.filter((c) => ONLY.length === 0 || ONLY.includes(c))
+if (caps.length === 0) {
+  console.error(`  ❌ 没有可体检的能力（${ONLY.length ? `--capability ${ONLY.join(',')} 未匹配到任何能力` : '清单为空'}）⇒ 量不出来，exit 2`)
+  process.exit(2)
+}
+
+// ── 二、剥注释（保留字符串内容与**行号**：注释替换成空格，换行原样）──────────
+/** JS/CJS：状态机扫一遍，注释与**正则字面量**体替换成空格；字符串原样保留。 */
+function maskJs(text) {
+  const out = [...text]
+  const n = text.length
+  const blank = (i) => { if (out[i] !== '\n') out[i] = ' ' }
+  let st = 'code'
+  let lastSig = ''            // 上一个非空白字符（判 `/` 是除号还是正则）
+  for (let i = 0; i < n; i += 1) {
+    const c = text[i]
+    const d = i + 1 < n ? text[i + 1] : ''
+    if (st === 'line') { if (c === '\n') st = 'code'; else blank(i); continue }
+    if (st === 'block') {
+      if (c === '*' && d === '/') { blank(i); blank(i + 1); i += 1; st = 'code'; continue }
+      blank(i); continue
+    }
+    if (st === 'regex') {
+      if (c === '\\') { blank(i); if (i + 1 < n) blank(i + 1); i += 1; continue }
+      if (c === '/') { st = 'code'; lastSig = '/'; continue }
+      blank(i); continue
+    }
+    if (st === 'sq' || st === 'dq' || st === 'tpl') {
+      if (c === '\\') { i += 1; continue }
+      if ((st === 'sq' && c === "'") || (st === 'dq' && c === '"') || (st === 'tpl' && c === '`')) st = 'code'
+      lastSig = c
+      continue
+    }
+    // code
+    if (c === '/' && d === '/') { blank(i); blank(i + 1); i += 1; st = 'line'; continue }
+    if (c === '/' && d === '*') { blank(i); blank(i + 1); i += 1; st = 'block'; continue }
+    if (c === '/' && /[(,=:[!&|?{};+\-*%~^<>]|^$/.test(lastSig)) { st = 'regex'; blank(i); continue }
+    if (c === "'") st = 'sq'
+    else if (c === '"') st = 'dq'
+    else if (c === '`') st = 'tpl'
+    if (!/\s/.test(c)) lastSig = c
+  }
+  return out.join('')
+}
+
+/** Python / shell：`#` 注释与（Python 的）三引号块替换成空格；普通字符串原样保留。 */
+function maskPy(text) {
+  const out = [...text]
+  const n = text.length
+  const blank = (i) => { if (out[i] !== '\n') out[i] = ' ' }
+  let st = 'code'
+  for (let i = 0; i < n; i += 1) {
+    const c = text[i]
+    if (st === 'line') { if (c === '\n') st = 'code'; else blank(i); continue }
+    if (st === 'tri1' || st === 'tri2') {
+      const q = st === 'tri1' ? "'''" : '"""'
+      if (text.startsWith(q, i)) { blank(i); blank(i + 1); blank(i + 2); i += 2; st = 'code'; continue }
+      if (c === '\\') { blank(i); if (i + 1 < n) blank(i + 1); i += 1; continue }
+      blank(i); continue
+    }
+    if (st === 'sq' || st === 'dq') {
+      if (c === '\\') { i += 1; continue }
+      if ((st === 'sq' && c === "'") || (st === 'dq' && c === '"')) st = 'code'
+      continue
+    }
+    if (c === '#') { blank(i); st = 'line'; continue }
+    if (text.startsWith("'''", i)) { blank(i); blank(i + 1); blank(i + 2); i += 2; st = 'tri1'; continue }
+    if (text.startsWith('"""', i)) { blank(i); blank(i + 1); blank(i + 2); i += 2; st = 'tri2'; continue }
+    if (c === "'") st = 'sq'
+    else if (c === '"') st = 'dq'
+  }
+  return out.join('')
+}
+const maskShell = maskPy
+
+/** 取**字符串字面量**（含区间，用于"实参窗口内"过滤）。 */
+function literalsOf(text) {
+  const out = []
+  const n = text.length
+  let i = 0
+  while (i < n) {
+    const c = text[i]
+    if (c === "'" || c === '"' || c === '`') {
+      const q = c
+      const start = i
+      i += 1
+      let buf = ''
+      while (i < n) {
+        if (text[i] === '\\') { buf += text[i + 1] || ''; i += 2; continue }
+        if (text[i] === q) break
+        if (text[i] === '\n' && q !== '`') break
+        buf += text[i]
+        i += 1
+      }
+      out.push({ value: buf, start, end: i + 1 })
+      i += 1
+      continue
+    }
+    i += 1
+  }
+  return out
+}
+
+const lineOf = (text, idx) => text.slice(0, Math.max(0, idx)).split('\n').length
+
+// ── 三、引用解析 ────────────────────────────────────────────────────────────
+const abs = (rel) => resolve(ROOT, rel)
+const relOf = (p) => relative(ROOT, p).split(sep).join('/')
+const isRepoFile = (p) => {
+  if (!p.startsWith(ROOT + sep)) return false
+  try { return statSync(p).isFile() } catch { return false }
+}
+
+/** JS 相对 specifier → 仓库文件（补扩展名与 index）。 */
+function resolveJsSpec(fromAbs, spec) {
+  const base = resolve(dirname(fromAbs), spec)
+  const cands = [base, `${base}.mjs`, `${base}.js`, `${base}.cjs`, `${base}.json`,
+    join(base, 'index.mjs'), join(base, 'index.js'), join(base, 'index.cjs')]
+  for (const c of cands) if (isRepoFile(c)) return relOf(c)
+  return null
+}
+
+/** Python 模块名 → 仓库文件（在若干个"运行期 sys.path 候选根"里找；找不到 = 第三方/标准库，忽略）。 */
+function resolvePyModule(fromAbs, dots, dotted) {
+  const parts = dotted ? dotted.split('.').filter(Boolean) : []
+  const roots = [dirname(fromAbs), join(ROOT, 'scripts'), join(ROOT, 'scripts', 'lib'),
+    join(ROOT, 'scripts', 'flow_sources'), join(ROOT, 'core'), join(ROOT, 'core', 'lib'), ROOT]
+  for (const r of roots) {
+    const p = join(r, ...parts)
+    if (isRepoFile(`${p}.py`)) return relOf(`${p}.py`)
+    if (isRepoFile(join(p, '__init__.py'))) return relOf(join(p, '__init__.py'))
+  }
+  return null
+}
+
+/** 从一段 I/O 调用实参里还原"全字面量路径"候选（还原不出/不存在 ⇒ 返回空）。 */
+function pathCandidates(fromAbs, win) {
+  const out = []
+  const lits = win.lits.map((l) => l.value)
+  const pathish = lits.filter((s) => s && s.length < 120 && !/\s/.test(s) && !/^[a-z][a-z0-9+.-]*:\/\//i.test(s))
+  const base = win.hasRoot ? ROOT : dirname(fromAbs)
+  // 取**连续片段**而不只是整串：同一个实参窗口里常有 `'utf8'`/`'--yes'` 之类非路径字面量，
+  // 整串拼接会把路径拼坏 ⇒ 只试连续片段才还原得出真路径（2026-10-04 初版即此漏）。
+  for (let i = 0; i < pathish.length; i += 1) {
+    for (let j = i + 1; j <= Math.min(pathish.length, i + 6); j += 1) {
+      const seg = pathish.slice(i, j)
+      const joined = resolve(base, ...seg.map((s) => s.replace(/^\.\//, '')))
+      if (isRepoFile(joined)) out.push(relOf(joined))
+    }
+  }
+  for (const s of lits) {
+    const clean = s.replace(/^\.\//, '')
+    if (REPO_TOP_RE.test(clean)) {
+      const p = abs(clean)
+      if (isRepoFile(p)) out.push(relOf(p))
+    }
+    if (/^\.{1,2}\//.test(s)) {
+      const p = resolve(dirname(fromAbs), s)
+      if (isRepoFile(p)) out.push(relOf(p))
+    }
+  }
+  return out
+}
+
+/** 在掩码后的代码里取 `call(` 的实参窗口（括号配平；窗口内保留原文以便取字面量）。 */
+function argWindows(code, callRe) {
+  const wins = []
+  callRe.lastIndex = 0
+  let m
+  while ((m = callRe.exec(code)) !== null) {
+    const open = code.indexOf('(', m.index + m[0].length - 1)
+    if (open < 0) continue
+    let depth = 0
+    let i = open
+    let st = null
+    for (; i < code.length && i - open < 900; i += 1) {
+      const c = code[i]
+      if (st) {
+        if (c === '\\') { i += 1; continue }
+        if (c === st) st = null
+        continue
+      }
+      if (c === "'" || c === '"' || c === '`') { st = c; continue }
+      if (c === '(') depth += 1
+      else if (c === ')') { depth -= 1; if (depth === 0) break }
+    }
+    const raw = code.slice(open, i + 1)
+    wins.push({
+      raw,
+      start: open,
+      lits: literalsOf(raw),
+      hasRoot: /\b(ROOT|REPO)\b/.test(raw),
+    })
+    callRe.lastIndex = i + 1
+  }
+  return wins
+}
+
+const JS_IO_RE = /\b(?:readFileSync|readFile|writeFileSync|existsSync|statSync|lstatSync|realpathSync|readdirSync|copyFileSync|mkdirSync|rmSync|unlinkSync|accessSync|openSync|createReadStream|createWriteStream|execFileSync|execFile|spawnSync|spawn|execSync|readFileSync)\s*\(/g
+const PY_IO_RE = /\b(?:open|Path|read_text|write_text|is_file|is_dir|exists|subprocess\.\w+|check_output|check_call|Popen)\s*\(/g
+const JS_IMPORT_ADJ = [
+  { re: /\bfrom\b/g, adjacent: true },
+  { re: /\brequire\s*\(/g, adjacent: true },
+  { re: /\bimport\s*\(/g, adjacent: true },
+  { re: /^[ \t]*import[ \t]+/gm, adjacent: false },
+]
+const PY_IMPORT_RE = /^[ \t]*import[ \t]+([A-Za-z_][\w.]*(?:[ \t]*,[ \t]*[A-Za-z_][\w.]*)*)/gm
+const PY_FROM_RE = /^[ \t]*from[ \t]+(\.*)([A-Za-z_][\w.]*)?[ \t]+import[ \t]+([^\n#]*)/gm
+
+/** 扫一个仓库文件 → 运行期引用列表 `{rel, via, line, kind}`（`rel` 是它引用的文件）。 */
+function refsOf(relPath) {
+  const p = abs(relPath)
+  const text = readFileSync(p, 'utf8')
+  const out = []
+  const excluded = []
+  const push = (target, line, kind) => {
+    if (!target || target === relPath) return
+    const why = nonRuntimeWhy(target)
+    if (why) { excluded.push({ rel: target, via: relPath, line, kind, why }); return }
+    out.push({ rel: target, via: relPath, line, kind })
+  }
+  const unresolved = []
+
+  if (/\.(mjs|js|cjs)$/.test(relPath)) {
+    const code = maskJs(text)
+    const lits = literalsOf(code)
+    for (const { re, adjacent } of JS_IMPORT_ADJ) {
+      re.lastIndex = 0
+      let m
+      while ((m = re.exec(code)) !== null) {
+        const after = m.index + m[0].length
+        const s = lits.find((x) => x.start >= after && (!adjacent || /^\s*$/.test(code.slice(after, x.start))))
+        if (!s) continue
+        if (!/^\.{1,2}\//.test(s.value)) continue                 // 裸 specifier = 宿主/第三方包，不归本门禁
+        const t = resolveJsSpec(p, s.value)
+        if (t) push(t, lineOf(text, s.start), 'import')
+        else unresolved.push({ line: lineOf(text, s.start), value: s.value })
+      }
+    }
+    for (const w of argWindows(code, JS_IO_RE)) {
+      const cands = pathCandidates(p, w)
+      if (cands.length === 0) {
+        for (const l of w.lits) if (/[/\\]|\.(mjs|js|cjs|py|sh|json|yml|md)$/.test(l.value) && !/^[a-z]+:\/\//i.test(l.value)) {
+          unresolved.push({ line: lineOf(text, w.start + l.start), value: l.value })
+        }
+      }
+      for (const c of cands) push(c, lineOf(text, w.start), 'io-path')
+    }
+  } else if (/\.py$/.test(relPath)) {
+    const code = maskPy(text)
+    PY_IMPORT_RE.lastIndex = 0
+    let m
+    while ((m = PY_IMPORT_RE.exec(code)) !== null) {
+      for (const name of m[1].split(',').map((s) => s.trim()).filter(Boolean)) {
+        const t = resolvePyModule(p, '', name)
+        if (t) push(t, lineOf(text, m.index), 'py-import')
+      }
+    }
+    PY_FROM_RE.lastIndex = 0
+    while ((m = PY_FROM_RE.exec(code)) !== null) {
+      const dots = m[1] || ''
+      const mod = m[2] || ''
+      const names = (m[3] || '').split(',').map((s) => s.trim().split(/\s+as\s+/)[0].trim()).filter(Boolean)
+      let hit = null
+      if (dots) {
+        let base = dirname(p)
+        for (let k = 1; k < dots.length; k += 1) base = dirname(base)
+        const parts = mod ? mod.split('.').filter(Boolean) : []
+        const cand = join(base, ...parts)
+        if (isRepoFile(`${cand}.py`)) hit = relOf(`${cand}.py`)
+        else if (isRepoFile(join(cand, '__init__.py'))) hit = relOf(join(cand, '__init__.py'))
+      } else if (mod) {
+        hit = resolvePyModule(p, '', mod)
+      }
+      if (hit) push(hit, lineOf(text, m.index), 'py-import')
+      // `from . import a, b` ⇒ 被导入的名字本身是子模块（只在**确实是仓库文件**时才算，避免误报）
+      if (dots) {
+        let base = dirname(p)
+        for (let k = 1; k < dots.length; k += 1) base = dirname(base)
+        for (const nm of names) {
+          const cand = join(base, nm)
+          if (isRepoFile(`${cand}.py`)) push(relOf(`${cand}.py`), lineOf(text, m.index), 'py-import')
+        }
+      }
+    }
+    for (const w of argWindows(code, PY_IO_RE)) {
+      const cands = pathCandidates(p, w)
+      if (cands.length === 0) {
+        for (const l of w.lits) if (/[/\\]|\.(mjs|js|cjs|py|sh|json|yml|md)$/.test(l.value)) {
+          unresolved.push({ line: lineOf(text, w.start + l.start), value: l.value })
+        }
+      }
+      for (const c of cands) push(c, lineOf(text, w.start), 'io-path')
+    }
+  } else if (/\.sh$/.test(relPath)) {
+    // shell 的引用只在**命令位置**才算（否则 `echo "请先运行 init-ml.sh"` 这类**给人看的提示**
+    // 会全部变成"缺件" —— 2026-10-04 初版实测：flow-timers.sh / daily-report.sh / poll-fulfillment.sh
+    // 的 5 处提示语被误报）。两条取法：
+    //   ① 命令词（node/python/bash/source/…）后的第一个非选项参数 → 裸文件名（`python3 x.py`）；
+    //   ② 任何位置的**仓库相对路径**（`"$REPO/scripts/x.py"`、`${REPO}/scripts/x.py`）—— 提示语里
+    //      不会写 `scripts/` 这个前缀（写 `scripts/` 的一定是真路径）。
+    const code = maskShell(text)
+    const lines = code.split('\n')
+    const CMD_ARG = /\b(?:node|python3?|bash|sh|source|exec|xargs)\b(?:[ \t]+--?[\w-]+)*[ \t]+["']?([^\s"';|&)]+)/g
+    const REPO_REL = /(?:^|["'\s=${}(/])((?:scripts|core|verticals|skills|presets|plugins|deploy|docs)\/[\w./@-]+)/g
+    for (let i = 0; i < lines.length; i += 1) {
+      // 截到本行第一个 `echo`/`printf` 命令词为止：其后是**给人看的文本**，不是调用点
+      const cut = lines[i].search(/(^|[\s;&|({])["']?(echo|printf)["']?[\s(]/)
+      const line = cut >= 0 ? lines[i].slice(0, cut) : lines[i]
+      const found = new Set()
+      for (const m of line.matchAll(CMD_ARG)) found.add(m[1])
+      for (const m of line.matchAll(REPO_REL)) found.add(m[1])
+      for (const tk of found) {
+        const clean = tk.replace(/^["']|["']$/g, '').replace(/^\.\//, '')
+        for (const c of [abs(clean), resolve(dirname(p), clean)]) {
+          if (isRepoFile(c)) { push(relOf(c), i + 1, 'shell'); break }
+        }
+      }
+    }
+  }
+  return { refs: out, unresolved, excluded }
+}
+
+// ── 四、逐个能力跑闭包 ──────────────────────────────────────────────────────
+const report = []
+let fatal = null
+for (const cap of caps) {
+  const d = runPack(['--describe', cap, '--json'])
+  if (!d.ok) { fatal = `能力 ${cap} 的清单读不到：${d.err}`; break }
+  const m = d.json
+  const integrity = m.integrity || {}
+  const packFiles = new Set(Object.keys(integrity))
+  packFiles.add(GENERATED_IN_PACK)                       // build 时生成，装到客户机上确实在包里
+  for (const rel of DROPS) packFiles.delete(rel)         // 注入测试：模拟漏登记
+
+  const codeFiles = [...packFiles].filter((f) => CODE_RE.test(f) && isRepoFile(abs(f)))
+  const refs = []
+  const unresolved = []
+  const excluded = []
+  for (const f of codeFiles) {
+    let r
+    try { r = refsOf(f) } catch (e) { unresolved.push({ via: f, line: 0, value: `<读不到：${String(e.message).slice(0, 80)}>` }); continue }
+    refs.push(...r.refs)
+    for (const u of r.unresolved) unresolved.push({ via: f, ...u })
+    for (const x of r.excluded) excluded.push(x)
+  }
+
+  // 缺件 = 引用到、仓库里有、但不在包内；再对缺件本身做有界 BFS（补一半 ⇒ 下一轮还会红）
+  const missing = new Map()
+  const judgedOut = new Map()
+  const hitExemptions = new Set()
+  const seen = new Set(packFiles)
+  let frontier = []
+  const consider = (r, depth, via) => {
+    const ex = NOT_PACK_BY_REL.get(r.rel)
+    if (ex) {                       // 已判定不进包：记进 judgedOut，**不**当缺件、也**不**再往下 BFS
+      hitExemptions.add(r.rel)
+      if (!judgedOut.has(r.rel)) judgedOut.set(r.rel, { rel: r.rel, depth, via, line: r.line, kind: r.kind, reason: ex.reason })
+      return
+    }
+    if (!missing.has(r.rel)) { missing.set(r.rel, { rel: r.rel, depth, via, line: r.line, kind: r.kind }); frontier.push(r.rel) }
+  }
+  for (const r of refs) {
+    if (!isRepoFile(abs(r.rel))) continue
+    if (packFiles.has(r.rel)) continue
+    consider(r, 1, r.via)
+  }
+  for (let depth = 2; depth <= MAX_DEPTH && frontier.length; depth += 1) {
+    const next = []
+    for (const f of frontier) {
+      if (seen.has(f)) continue
+      seen.add(f)
+      let sub
+      try { sub = refsOf(f) } catch { continue }
+      for (const r of sub.refs) {
+        if (!isRepoFile(abs(r.rel)) || packFiles.has(r.rel) || seen.has(r.rel)) continue
+        consider(r, depth, f)
+      }
+    }
+    frontier = next
+  }
+
+  report.push({
+    capability: cap,
+    version: m.version,
+    flows: m.flows || [],
+    packFiles: packFiles.size,
+    codeFiles: codeFiles.length,
+    refs: refs.length,
+    excluded,
+    declaredMissing: m.missing || [],
+    missing: [...missing.values()].sort((a, b) => (a.depth - b.depth) || a.rel.localeCompare(b.rel)),
+    judgedOut: [...judgedOut.values()].sort((a, b) => a.rel.localeCompare(b.rel)),
+    hitExemptions: [...hitExemptions],
+    unresolved,
+  })
+}
+
+if (fatal) {
+  console.error(`  ❌ ${fatal}（**量不出来就不算通过**）`)
+  process.exit(2)
+}
+// 防假绿：一个能力都没量到代码文件 ⇒ "全部闭合"毫无意义（扫了空集也算通过 = 本脚本要修的那类翻车）
+const totalCode = report.reduce((a, r) => a + r.codeFiles, 0)
+if (totalCode === 0) {
+  console.error('  ❌ 一个能力包里的代码文件都没扫到（清单为空或路径全不对）⇒ 量不出来，exit 2')
+  process.exit(2)
+}
+
+const totalMissing = report.reduce((a, r) => a + r.missing.length, 0)
+const totalUnresolved = report.reduce((a, r) => a + r.unresolved.length, 0)
+const totalJudgedOut = report.reduce((a, r) => a + r.judgedOut.length, 0)
+
+// ── 豁免表的卫生（形态照 kernel-purity WHITELIST / role-gateway-exemptions.json）──────
+//   · 缺理由/理由太短 ⇒ 问题（"我知道它缺着"不等于"判定不进包"）；
+//   · 条目在本轮**没被命中** ⇒ 「过期豁免」也是问题（腐烂的豁免会掩盖日后新增的真缺件）。
+const hitAll = new Set(report.flatMap((r) => r.hitExemptions))
+const exemptionProblems = []
+for (const e of NOT_PACK_RUNTIME) {
+  if (!e.rel) { exemptionProblems.push('豁免条目缺 rel'); continue }
+  if (!e.reason || String(e.reason).trim().length < REASON_MIN) {
+    exemptionProblems.push(`豁免 ${e.rel} 缺理由（须 ≥ ${REASON_MIN} 字：写清"为什么它不在能力包运行期面上"）`)
+  }
+  if (!hitAll.has(e.rel)) exemptionProblems.push(`过期豁免：${e.rel} 本轮没有任何包引用它 ⇒ 请删掉该条目（否则它会掩盖日后新增的真缺件）`)
+}
+
+// ── 五、输出 ────────────────────────────────────────────────────────────────
+if (JSON_OUT) {
+  console.log(JSON.stringify({
+    root: ROOT, python: PY, drops: [...DROPS], strict: STRICT,
+    exemptions: NOT_PACK_RUNTIME.map((e) => ({ rel: e.rel, hit: hitAll.has(e.rel), reason: e.reason })),
+    problems: exemptionProblems,
+    capabilities: report,
+    totals: { capabilities: report.length, codeFiles: totalCode, missing: totalMissing, judgedOut: totalJudgedOut, unresolved: totalUnresolved },
+  }, null, 2))
+} else {
+  if (!QUIET) {
+    console.log('\n能力包运行期闭包体检（只读；默认只报告）')
+    console.log(`  判据：包内文件的 静态 import / Python import / 子进程与读写路径 ⇒ 引用到但**不在包内**的仓库文件`)
+    for (const r of report) {
+      console.log(`\n  ── ${r.capability} v${r.version}（流程 ${r.flows.length}｜包内 ${r.packFiles} 项｜其中代码 ${r.codeFiles} 个｜解析到引用 ${r.refs} 处）`)
+      if (r.declaredMissing.length) {
+        console.log(`     ⚠️ 清单里声明了但仓库里不存在（capability_pack.py --validate 也管这条）：${r.declaredMissing.join('、')}`)
+      }
+      if (r.missing.length === 0) {
+        console.log('     ✅ 静态引用面闭合：引用到的仓库文件都已在包内')
+      } else {
+        console.log(`     ❌ 缺 ${r.missing.length} 个运行期文件（引用到、仓库里有、包里没有）：`)
+        for (const x of r.missing) {
+          const hop = x.depth === 1 ? '' : `（第 ${x.depth} 跳：补上 ${x.via} 之后才会用到）`
+          console.log(`        · ${x.rel}  ← ${x.via}:${x.line} [${x.kind}]${hop}`)
+        }
+        console.log('        ↳ 修法：写进 `scripts/flow-requirements.json#pack.engine`（**按实际 import 关系推导**）；')
+        console.log('          若它是 `core/**` 运行期件，同一批还要进 `scripts/sync-scripts.sh#CORE_KEY`（两处逐项一致，')
+        console.log('          由 `scripts/tests/sync-scripts-core.test.mjs` 判红），再提三个带 flow 的能力包版本 + `--stamp`。')
+      }
+      if (r.judgedOut.length) {
+        console.log(`     ℹ️ 已判定不进包 ${r.judgedOut.length} 条：${r.judgedOut.map((x) => `${x.rel} ← ${x.via}:${x.line} [${x.kind}]`).join('；')}`)
+      }
+      if (r.excluded.length) {
+        const kinds = [...new Set(r.excluded.map((x) => `${x.rel.split('/')[0]}/**：${x.why}`))]
+        console.log(`     ℹ️ 已排除 ${r.excluded.length} 处**非运行期**引用（${kinds.join('；')}）`)
+      }
+      if (r.unresolved.length) {
+        console.log(`     ℹ️ 未解析 ${r.unresolved.length} 处（动态 require / 运行时拼路径 / 非仓库路径 —— 静态法的固有盲区，不等于缺件）：`)
+        for (const u of r.unresolved.slice(0, 5)) console.log(`        · ${u.via}:${u.line} ${u.value}`)
+        if (r.unresolved.length > 5) console.log(`        · …另 ${r.unresolved.length - 5} 处`)
+      }
+    }
+    if (NOT_PACK_RUNTIME.length) {
+      console.log('\n  ── 已判定不进包（豁免表；每条必须写理由，条目没命中＝过期豁免）')
+      for (const e of NOT_PACK_RUNTIME) {
+        console.log(`     · ${e.rel}（本轮命中 ${hitAll.has(e.rel) ? '是' : '否'}）`)
+        console.log(`       ${e.reason}`)
+      }
+    }
+    if (exemptionProblems.length) {
+      console.log('\n  ⚠️ 豁免表自身的问题（每一条都要修，否则"判定不进包"会变成吞缺件的后门）：')
+      for (const p of exemptionProblems) console.log(`     · ${p}`)
+    }
+  }
+  console.log('')
+  console.log(`  =============================================`)
+  console.log(`    闭包体检：${report.length} 个能力包 / 扫 ${totalCode} 个代码文件 ⇒ 缺件 ${totalMissing} 个、`
+    + `豁免 ${NOT_PACK_RUNTIME.length} 条（命中 ${hitAll.size}）、未解析 ${totalUnresolved} 处`)
+  if (DROPS.size) console.log(`    （注入模式：已从包内文件集剔除 ${[...DROPS].join('、')}）`)
+  const bad = totalMissing > 0 || exemptionProblems.length > 0
+  console.log(`    ${!bad ? '✅ 静态引用面闭合（下界；上界仍按 docs/README.md §六.9⑤ 在空目录里真跑一遍）'
+    : (STRICT ? `❌ 有问题（--strict）：缺件 ${totalMissing}、豁免表问题 ${exemptionProblems.length}`
+      : `⚠️ 有问题（默认只报告，exit 0；要非零请加 --strict）：缺件 ${totalMissing}、豁免表问题 ${exemptionProblems.length}`)}`)
+  console.log(`  =============================================`)
+}
+
+if (STRICT && (totalMissing > 0 || exemptionProblems.length > 0)) process.exit(1)
+process.exit(0)