@whyshu/argent-engine 0.0.0-stage → 0.6.0

package/engine/scripts/check-version-consistency.mjs

@@ -0,0 +1,452 @@
+#!/usr/bin/env node
+/**
+ * 版本一致性门禁（0.4.0 起）—— 「**活引用 == 唯一真源**」的可执行形式。
+ *
+ * ## 为什么有它
+ * 平台版本此前**只出现在 `CHANGELOG.md` / `VERSION` / 版本规则文档**三处，靠人记着同批改。
+ * 0.4.0 起 Argent 从"能力层"重定位为**智能体平台**（版本语义见
+ * `docs/Argent-宿主适配契约.md` §8），版本会被**宿主**、**安装器**、**业务线兼容区间**、
+ * **MCP 握手**分别读走 ⇒ "改一处、漏一处"的漂移代价从"文档不一致"升级为
+ * **"装得上但跑不起来" / "页面说版本不满足而实际能跑"**（后者真发生过，见
+ * `docs/Argent-工作台口径审计-2026-10-06.md` 的 P0-5）。故把判据固化。
+ *
+ * ## 判据（每条都点名 文件:行）
+ *   R0-TRUTH     唯一真源存在且是 **semver**（缺 / 非 semver ⇒ 红）
+ *   R1-LOCKSTEP  **活引用**逐条等于真源（清单见 `LIVE_REFS`，⛔ 不写第二份清单）
+ *   R2-RUNTIME   **跑起来也一致**：CLI `version` / CLI `versions` / MCP `initialize.serverInfo`
+ *   R3-CARRIER   版本**载体**必须"从 `VERSION` 读"，⛔ 不许写死（结构性断言）
+ *   R4-SCAN      **反向**：活引用面里**新写死一个别的版本** ⇒ 红（这才是"有牙"的那一半）
+ *   R5-CHANGELOG 最新一段 `## X.Y.Z` = 真源；更旧的段按定义历史（**降级为 info，不误判**）
+ *   R6-DSH-LOCK  `dsh-version-lock/**`（宿主依赖版本，**另一条轴**）产出 **0 条**发现
+ *   R7-HISTDOC   `docs/H1-…` 必须带「本文实测时 Argent 平台版本 = …」标注；带标注 ⇒ 其历史值豁免
+ *   R8-COVERAGE  扫描面**真扫到了东西**（防"永远返回 0 违规的扫描器也能绿"）
+ *
+ * ## 为什么 R4 只扫"活引用面"（`core/ scripts/ plugins/ presets/ verticals/ deploy/ configs/` + `VERSION`）
+ * `docs/**` 与 `CHANGELOG.md` **按定义是历史记录面**：里面大量 `0.3.0` 是**当轮实测值 / 沿革**，
+ * 把它们拉进红判据 = **恒红陷阱**（实测：全仓扫描会出 63 条，63 条全是合法历史）。
+ * ⇒ 活引用面**判红**，历史面**按规则豁免**（R5/R6/R7 各给证据），这正是本文件头的分工。
+ *
+ * ## 用法
+ *   node scripts/check-version-consistency.mjs [--root <dir>] [--json] [--strict] [--no-runtime]
+ *   退出码：0 = 无 error（**默认只报告**，与 `check-docs-drift` / `check-pack-closure` 同档）
+ *          1 = 有 error（**只有 `--strict` 才非零退出**）
+ *          2 = 用法 / 真源缺失（**恒非零**：拿不到真源就无法判定，⛔ 不许静默成功）
+ *
+ * 回归与**有牙证明**：`scripts/tests/version-consistency.test.mjs`（真仓 0 error +
+ * 注入"写死别的版本"必须变红 + 历史文档不被误判 + 真源缺失/非 semver 必须红）。
+ */
+import { execFileSync, spawn } from 'node:child_process'
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
+import { dirname, extname, join, relative, resolve, sep } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const SELF = fileURLToPath(import.meta.url)
+const SELF_ROOT = resolve(HERE, '..')
+
+// ── 扫描面（**活引用面**；历史记录面见文件头 R4 说明）──────────────────────────
+const SURFACE = ['VERSION', 'core', 'scripts', 'plugins', 'presets', 'verticals', 'deploy', 'configs']
+const SKIP_DIR = /(^|\/)(node_modules|\.git|archive)(\/|$)/
+const TEXT_EXT = new Set(['.md', '.mjs', '.js', '.cjs', '.json', '.yml', '.yaml', '.sh', '.py', '.txt'])
+const MAX_BYTES = 3_000_000
+
+/** 版本**载体**：这些文件的版本必须来自 `VERSION`，⛔ 不许写死。 */
+const CARRIERS = [
+  { file: 'core/cli/argent.mjs', why: 'CLI `argent version` 的唯一出口' },
+  { file: 'core/mcp/server.mjs', why: 'MCP `initialize.serverInfo.version` 的唯一出口' },
+  { file: 'plugins/argent-core/src/index.js', why: '设置页 / `/api/argent-state/version` 的版本展示' },
+]
+
+/** 声明式**活引用清单**：每条 = 一个"必须等于真源"的落点（⛔ 不另抄第二份）。 */
+const LIVE_REFS = [
+  { id: 'VERSION', file: 'VERSION', how: '整个文件 trim 后即真源本身' },
+  { id: 'contracts.argentVersion', file: 'core/contracts/argent.contracts.json', how: '契约自带版本，X/Y 位必须与 VERSION 同批一致' },
+  { id: 'deploy/mcp/README.md 标题', file: 'deploy/mcp/README.md', how: '部署 runbook 的首行标题必须写明现役平台版本' },
+]
+
+/** 历史实测文档：**必须带"当时版本"标注**才豁免（标注本身就是豁免条件）。 */
+const HIST_DOCS = ['docs/H1-第三方宿主采信-2026-10-06.md']
+const ANNOTATION_RE = /本文实测时\s*Argent\s*平台版本\s*=\s*`?([0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)?)`?/
+
+// ── 版本号识别（**轴**的区分是本门禁的核心，别把别的轴当成 Argent）──────────────
+/** Argent 平台版本轴：`0.X.Y`。⛔ 能力包是 `1.x.y`、插件/角色/业务线是各自的小版本。 */
+const ARGENT_TOK = /(?<![\d.])0\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?![\d.])/g
+/** 哨兵值：`VERSION` 读不到时的占位（`core/mcp/server.mjs`），⛔ 不是版本声明。 */
+const SENTINELS = new Set(['0.0.0'])
+/**
+ * 「Argent 版本声明」语境 —— 只有命中才把这一行的版本字面量当**声明**看。
+ * ⚠️ 刻意**不含**裸 `version:`：插件包（`0.1.0`/`0.2.0`）、能力包、业务线版本都是**别的轴**，
+ * 认它会立刻退化成假红机器（详见 `docs/Argent-宿主适配契约.md` §8 的三级版本语义）。
+ */
+const CONTEXT = [
+  [/argentVersion|ARGENT_VERSION/i, 'argentVersion'],
+  [/server[_-]?info/i, 'serverInfo'],
+  [/requires\.argent/, 'requires.argent'],
+  [/(?<![-\w])(?:Argent|argent)(?![-\w])[^\n]{0,16}?\d+\.\d+\.\d+/, 'Argent+版本'],
+  [/\d+\.\d+\.\d+[^\n]{0,16}?(?<![-\w])(?:Argent|argent)(?![-\w])/, '版本+Argent'],
+  [/(平台版本|产品版本|版本线|现役版本|当前版本|现行版本|Argent 平台)/, '版本声明词'],
+  [/["']argent["']\s*:/, '"argent":'],
+]
+/** 行内**历史语境**：命中 ⇒ 该处是沿革/实测记录 ⇒ 降级 info（与 `check-docs-drift` 的 R1/R3 同法）。 */
+const HISTORY = /历史|归档|退役|旧版|旧名|旧行为|曾经|曾|当年|当轮|实测|修复|血泪|不再维护|前身|遗留|迁移|沿革|起强制|verifiedOn|由\s*`?>=/
+
+const isSemver = (s) => /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(String(s || ''))
+
+/** npm 风格区间子集（仓库实际只用这几种）：`>=A <B` / `>=A` / `<B` / `A`。缺位按 0 补。 */
+function satisfies(version, range) {
+  const p = (s) => {
+    const m = /^(\d+)(?:\.(\d+))?(?:\.(\d+))?(?:-([0-9A-Za-z.-]+))?$/.exec(String(s).trim())
+    return m ? [Number(m[1]), Number(m[2] || 0), Number(m[3] || 0), m[4] || '~'] : null
+  }
+  const cmp = (a, b) => {
+    for (let i = 0; i < 3; i += 1) if (a[i] !== b[i]) return a[i] - b[i]
+    if (a[3] === b[3]) return 0
+    if (a[3] === '~') return 1   // 正式版 > 预发布
+    if (b[3] === '~') return -1
+    return a[3] < b[3] ? -1 : 1
+  }
+  const v = p(version)
+  if (!v) return false
+  const parts = String(range || '').trim().split(/\s+/).filter(Boolean)
+  if (!parts.length) return false
+  for (const part of parts) {
+    const m = /^(>=|<=|>|<|=)?\s*(.+)$/.exec(part)
+    if (!m) return false
+    const bound = p(m[2])
+    if (!bound) return false
+    const d = cmp(v, bound)
+    const op = m[1] || '='
+    const okOp = op === '>=' ? d >= 0 : op === '<=' ? d <= 0 : op === '>' ? d > 0 : op === '<' ? d < 0 : d === 0
+    if (!okOp) return false
+  }
+  return true
+}
+
+/** 该 token 是否只是**文件名/路径**的一部分（`docs/Argent-0.3.0-验收清单.md`）⇒ 不是版本声明。 */
+function insideFilename(line, idx, tok) {
+  const after = line.slice(idx + tok.length)
+  if (/^[-\w]*\.(?:md|json|mjs|js|cjs|yml|yaml|sh|py|txt)\b/.test(after)) return true
+  const before = line.slice(0, idx)
+  return /[\w./-]$/.test(before) && /^[-\w]/.test(after)
+}
+
+function walkFiles(abs, root, out = []) {
+  let st
+  try { st = statSync(abs) } catch { return out }
+  if (st.isFile()) { out.push(abs); return out }
+  for (const e of readdirSync(abs, { withFileTypes: true })) {
+    const c = join(abs, e.name)
+    const rel = relative(root, c)
+    if (SKIP_DIR.test(rel)) continue
+    if (e.isDirectory()) walkFiles(c, root, out)
+    else if (TEXT_EXT.has(extname(e.name)) && statSync(c).size < MAX_BYTES) out.push(c)
+  }
+  return out
+}
+
+/** 只读：把一行按判据分类。返回 findings（不含 == 真源的 token）。 */
+function scanLine({ rel, line, lineNo, truth, findings, info, whyText }) {
+  let filenameHit = false
+  for (const m of line.matchAll(ARGENT_TOK)) {
+    const tok = m[0]
+    // ① 别的轴：`0.1.x` 是**宿主（dsh）**轴 —— 仓库里 Argent 从未是 0.1.x
+    //    （0.9.9 → 0.2.0 → 0.3.0 → 0.4.0），而 dsh 全是 0.1.x（快照 `dsh-version-lock/*.json`）。
+    if (m[1] === '1') continue
+    // ② 哨兵占位（读不到 VERSION 时的兜底），不是版本声明。
+    if (SENTINELS.has(tok)) continue
+    // ③ 宿主**预发布**轴：`0.x.y-rc.N` 且本行点名 dsh ⇒ 宿主版本（如桌面端内置 `0.2.0-rc.2`）。
+    if (/-rc\.\d+$/.test(tok) && /\bdsh\b/i.test(line)) continue
+    // ④ 文件名 / 路径里的版本号不是声明。
+    if (insideFilename(line, m.index, tok)) continue
+    // ⑤ 与真源一致 ⇒ 无需报告。
+    if (tok === truth) continue
+    const hit = CONTEXT.find(([re]) => re.test(line))
+    if (!hit) continue
+    const rec = { file: rel, line: lineNo, token: tok, context: hit[1], text: line.trim().slice(0, 140) }
+    if (HISTORY.test(line)) info.push({ ...rec, rule: 'R4-SCAN', why: '行内含历史语境（沿革/实测/已修）⇒ 降级为 info，不判红' })
+    else findings.push({ rule: 'R4-SCAN', file: rel, line: lineNo, token: tok,
+      message: `活引用面出现 Argent 版本字面量 \`${tok}\`（语境：${hit[1]}），与唯一真源 \`${truth}\` 不一致`,
+      why: whyText })
+  }
+}
+
+// ── 主入口 ──────────────────────────────────────────────────────────────────
+export function run(opts = {}) {
+  const root = resolve(opts.root || SELF_ROOT)
+  const findings = []
+  const info = []
+  const err = (rule, file, line, message, why) => findings.push({ rule, file, line, token: null, message, why })
+
+  // ── R0-TRUTH ─────────────────────────────────────────────────────────────
+  const versionPath = join(root, 'VERSION')
+  if (!existsSync(versionPath)) {
+    err('R0-TRUTH', 'VERSION', 0, '唯一真源 `VERSION` 不存在 ⇒ 无法判定（⛔ 不静默成功）', '平台版本唯一真源 = 仓库根 `VERSION`')
+    return { ok: false, findings, info, truth: null, stats: { files: 0 } }
+  }
+  const truth = readFileSync(versionPath, 'utf8').trim()
+  if (!isSemver(truth)) {
+    err('R0-TRUTH', 'VERSION', 1, `唯一真源不是 semver：${JSON.stringify(truth)}`, '`VERSION` 必须是 X.Y.Z（可带 -rc.N）')
+  }
+
+  // ── R1-LOCKSTEP ──────────────────────────────────────────────────────────
+  for (const ref of LIVE_REFS) {
+    const abs = join(root, ref.file)
+    if (!existsSync(abs)) { err('R1-LOCKSTEP', ref.file, 0, `活引用声明的文件不存在（${ref.id}）`, ref.how); continue }
+    const text = readFileSync(abs, 'utf8')
+    if (ref.id === 'VERSION') {
+      if (text.trim() !== truth) err('R1-LOCKSTEP', ref.file, 1, `活引用 ${ref.id} = ${JSON.stringify(text.trim())} ≠ 真源 ${truth}`, ref.how)
+      continue
+    }
+    if (ref.id === 'contracts.argentVersion') {
+      let j = null
+      try { j = JSON.parse(text) } catch { err('R1-LOCKSTEP', ref.file, 0, '契约文件不是合法 JSON', ref.how); continue }
+      // 契约里的 argentVersion 就是真源之一：X/Y 位必须与 VERSION 一致（§3.2「唯一出口」）
+      const [tx, ty] = truth.split(/[.-]/).map(Number)
+      const [cx, cy] = String(j.argentVersion || '').split(/[.-]/).map(Number)
+      if (!isSemver(j.argentVersion)) err('R1-LOCKSTEP', ref.file, 2, `argentVersion 不是 semver：${JSON.stringify(j.argentVersion)}`, ref.how)
+      else if (tx !== cx || ty !== cy) err('R1-LOCKSTEP', ref.file, 2, `argentVersion = ${j.argentVersion}，与 VERSION ${truth} 的 X/Y 位不一致`, ref.how)
+      continue
+    }
+    // deploy/mcp/README.md：首行标题
+    const head = text.split('\n').find((l) => l.trim()) || ''
+    if (!head.includes(truth)) err('R1-LOCKSTEP', ref.file, 1, `标题未写明现役平台版本 ${truth}：${head.slice(0, 100)}`, ref.how)
+  }
+
+  // 业务线兼容区间（`verticals/*/manifest.json#requires.argent` 必须**容纳**真源）
+  const vdir = join(root, 'verticals')
+  const verticals = []
+  if (existsSync(vdir)) {
+    for (const e of readdirSync(vdir, { withFileTypes: true })) {
+      if (!e.isDirectory()) continue
+      const man = join(vdir, e.name, 'manifest.json')
+      if (!existsSync(man)) continue
+      let j = null
+      try { j = JSON.parse(readFileSync(man, 'utf8')) } catch { err('R1-LOCKSTEP', `verticals/${e.name}/manifest.json`, 0, 'manifest.json 不是合法 JSON', '业务线兼容区间必须可判'); continue }
+      const rel = `verticals/${e.name}/manifest.json`
+      const range = j.requires?.argent
+      if (!range) { err('R1-LOCKSTEP', rel, 0, '缺 `requires.argent` 兼容区间', '业务线必须声明兼容的 Argent 平台区间'); continue }
+      verticals.push({ id: j.id, version: j.version, range, ok: satisfies(truth, range) })
+      if (!satisfies(truth, range)) {
+        err('R1-LOCKSTEP', rel, 0, `平台版本 ${truth} **不落在**本线声明的兼容区间 \`${range}\` 内`,
+          '平台抬版必须同批抬兼容区间 —— 否则「Argent 能力 → 概览」会把能跑的业务线标成 `⚠️ 版本不满足`（P0-5 实测发生过）')
+      }
+    }
+  }
+
+  // ── R5-CHANGELOG（历史段豁免，但**最新段**必须等于真源）────────────────────
+  const clPath = join(root, 'CHANGELOG.md')
+  let changelog = { sections: [], newest: null }
+  if (!existsSync(clPath)) err('R5-CHANGELOG', 'CHANGELOG.md', 0, 'CHANGELOG.md 不存在', '发布记录是版本线的对外凭证')
+  else {
+    readFileSync(clPath, 'utf8').split('\n').forEach((line, i) => {
+      const m = /^##\s+(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)/.exec(line)
+      if (m) changelog.sections.push({ version: m[1], line: i + 1 })
+    })
+    changelog.newest = changelog.sections[0]?.version || null
+    if (!changelog.sections.length) err('R5-CHANGELOG', 'CHANGELOG.md', 0, '没有任何 `## X.Y.Z` 段', '发布记录格式：`## X.Y.Z（日期）`')
+    else if (changelog.newest !== truth) {
+      err('R5-CHANGELOG', 'CHANGELOG.md', changelog.sections[0].line, `最新段是 \`${changelog.newest}\`，真源是 \`${truth}\` ⇒ 抬版没写发布记录`, '最新段 = 现役版本；更旧的段按定义是历史')
+    }
+    // 更旧的段：**按定义历史** ⇒ 显式登记为 info（证明"没被误判"，⛔ 不是漏扫）
+    for (const s of changelog.sections.slice(1)) {
+      info.push({ rule: 'R5-CHANGELOG', file: 'CHANGELOG.md', line: s.line, token: s.version,
+        why: '发布记录的**历史段**（不是现行声明）⇒ 按定义豁免，⛔ 不追改' })
+    }
+  }
+
+  // ── R6-DSH-LOCK（宿主依赖版本是**另一条轴**，必须 0 发现）──────────────────
+  const lockDir = join(root, 'dsh-version-lock')
+  let lockFiles = []
+  if (existsSync(lockDir)) lockFiles = walkFiles(lockDir, root)
+  for (const f of lockFiles) {
+    const rel = relative(root, f)
+    const text = readFileSync(f, 'utf8')
+    for (const m of text.matchAll(/(?<![\d.])0\.(\d+)\.(\d+)(?:-rc\.(\d+))?(?![\d.])/g)) {
+      if (m[1] !== '1') info.push({ rule: 'R6-DSH-LOCK', file: rel, line: 0, token: m[0], why: '宿主快照里的版本（dsh 轴）⇒ 与 Argent 平台版本不同轴，登记为 info 以自证"未误判"' })
+    }
+  }
+
+  // ── R7-HISTDOC（历史实测文档须带"当时版本"标注）──────────────────────────
+  const histDocs = []
+  for (const rel of HIST_DOCS) {
+    const abs = join(root, rel)
+    if (!existsSync(abs)) { err('R7-HISTDOC', rel, 0, '声明的历史实测文档不存在', 'HIST_DOCS 清单过期'); continue }
+    const text = readFileSync(abs, 'utf8')
+    const m = ANNOTATION_RE.exec(text)
+    const lineNo = m ? text.slice(0, m.index).split('\n').length : 0
+    if (!m) {
+      err('R7-HISTDOC', rel, 0, '历史实测文档**缺**「本文实测时 Argent 平台版本 = X.Y.Z」标注',
+        '标注既是"这是当轮证据"的声明，也是本文件豁免它历史值的**条件**（⛔ 不追改实测值）')
+    } else {
+      histDocs.push({ file: rel, line: lineNo, annotated: m[1] })
+      // 证据面 = **标注行以外**的正文（标注自己写着那个版本，不去掉就会自证 ⇒ 假绿）。
+      const body = text.slice(0, m.index) + text.slice(m.index + m[0].length)
+      const toks = [...body.matchAll(ARGENT_TOK)].map((x) => x[0]).filter((t) => !SENTINELS.has(t))
+      const others = [...new Set(toks.filter((t) => t !== truth))]
+      if (m[1] !== truth && !others.includes(m[1])) {
+        err('R7-HISTDOC', rel, lineNo, `标注写的版本 \`${m[1]}\` 在本文件正文里找不到对应实测值（标注与证据不符）`, '标注必须指向文中的真实返回值')
+      }
+      info.push({ rule: 'R7-HISTDOC', file: rel, line: lineNo, token: m[1],
+        why: `带"当时版本"标注 ⇒ 其历史值（如 ${others.slice(0, 3).join(' / ') || '无'}）按纪律豁免，⛔ 不追改` })
+    }
+  }
+
+  // ── R3-CARRIER（载体必须"读 VERSION"，不许写死）────────────────────────────
+  for (const c of CARRIERS) {
+    const abs = join(root, c.file)
+    if (!existsSync(abs)) { err('R3-CARRIER', c.file, 0, '声明的版本载体不存在', c.why); continue }
+    const text = readFileSync(abs, 'utf8')
+    if (!/['"`]VERSION['"`]/.test(text)) {
+      err('R3-CARRIER', c.file, 0, '没有从 `VERSION` 读版本（找不到 `\'VERSION\'` 字面量）—— 版本被写死了？', c.why)
+    }
+  }
+
+  // ── R4-SCAN（反向：活引用面不得写死别的版本）──────────────────────────────
+  const files = []
+  for (const s of SURFACE) {
+    const abs = join(root, s)
+    if (existsSync(abs)) walkFiles(abs, root, files)
+  }
+  // 门禁自己**不扫自己**（判据里必然含示例版本号）；它的**回归夹具**同理
+  // （`scripts/tests/version-consistency.test.mjs` 的职责就是注入错误版本 ⇒ 必须豁免，否则恒红）。
+  // ⚠️ 豁免面 = **这两个精确路径**，⛔ 不是 `scripts/tests/**` 整个目录 ——
+  // 目录级豁免会漏掉真·活引用（2026-10-10 实测：`scripts/tests/no-host-smoke.test.mjs` 曾把
+  // 平台版本写死成字面量，正是本门禁要抓的那类）。
+  const SELF_EXCLUDED = new Set([SELF, join(root, 'scripts', 'tests', 'version-consistency.test.mjs')].map((p) => resolve(p)))
+  const scanned = files.filter((f) => !SELF_EXCLUDED.has(resolve(f)))
+  for (const f of scanned) {
+    let text
+    try { text = readFileSync(f, 'utf8') } catch { continue }
+    if (text.includes('\u0000')) continue
+    const rel = relative(root, f)
+    text.split('\n').forEach((line, i) => scanLine({
+      rel, line, lineNo: i + 1, truth, findings, info,
+      whyText: `活引用面的 Argent 版本字面量必须等于 \`VERSION\`（${truth}）或改从 \`VERSION\` 读；`
+        + '确属历史记录 ⇒ 请写进 `CHANGELOG.md` / 带"当时版本"标注的阶段文档（见契约 §8 纪律 2）',
+    }))
+  }
+
+  // ── R8-COVERAGE（防"扫描器什么都没扫也能绿"）─────────────────────────────
+  if (typeof opts.skipCoverage !== 'boolean' || !opts.skipCoverage) {
+    if (scanned.length < 100) err('R8-COVERAGE', '.', 0, `只扫到 ${scanned.length} 个文件（< 100）⇒ 扫描面可能失效`, '扫描面 = 活引用面；扫不到东西的门禁等于没有门禁')
+  }
+
+  return {
+    ok: findings.length === 0,
+    findings,
+    info,
+    truth,
+    stats: { files: scanned.length, surface: SURFACE, info: info.length, carriers: CARRIERS.length, lockFiles: lockFiles.length, verticals },
+    changelog,
+    histDocs,
+  }
+}
+
+// ── R2-RUNTIME（跑起来也一致；`--no-runtime` 可跳过，用于纯静态夹具）──────────
+export async function runRuntime(opts = {}) {
+  const root = resolve(opts.root || SELF_ROOT)
+  const findings = []
+  const detail = {}
+  const cli = join(root, 'core', 'cli', 'argent.mjs')
+  const truth = readFileSync(join(root, 'VERSION'), 'utf8').trim()
+  try {
+    const j = JSON.parse(execFileSync(process.execPath, [cli, 'version', '--json'], { encoding: 'utf8' }))
+    detail.cliVersion = j.argent
+    if (j.argent !== truth) findings.push({ rule: 'R2-RUNTIME', file: 'core/cli/argent.mjs', line: 0, token: j.argent, message: `CLI \`argent version\` 回 ${j.argent} ≠ 真源 ${truth}`, why: '活引用必须等于唯一真源' })
+  } catch (e) {
+    findings.push({ rule: 'R2-RUNTIME', file: 'core/cli/argent.mjs', line: 0, token: null, message: `CLI \`argent version\` 跑不起来：${String(e.message).split('\n')[0]}`, why: '跑不起来 ⇒ 无法判定（⛔ 不当通过）' })
+  }
+  try {
+    const j = JSON.parse(execFileSync(process.execPath, [cli, 'versions', '--json'], { encoding: 'utf8' }))
+    detail.cliVersions = { cli: j.cli?.argent, contracts: j.contracts?.argentVersion }
+    if (j.cli?.argent !== truth) findings.push({ rule: 'R2-RUNTIME', file: 'core/cli/argent.mjs', line: 0, token: j.cli?.argent, message: `\`versions --json\` 的 cli.argent = ${j.cli?.argent} ≠ 真源 ${truth}`, why: '五面对账的版本出口' })
+    if (j.contracts?.argentVersion && j.contracts.argentVersion !== truth) findings.push({ rule: 'R2-RUNTIME', file: 'core/contracts/argent.contracts.json', line: 0, token: j.contracts.argentVersion, message: `\`versions --json\` 的 contracts.argentVersion = ${j.contracts.argentVersion} ≠ 真源 ${truth}`, why: '五面对账的版本出口' })
+  } catch (e) {
+    findings.push({ rule: 'R2-RUNTIME', file: 'core/cli/argent.mjs', line: 0, token: null, message: `CLI \`versions --json\` 跑不起来：${String(e.message).split('\n')[0]}`, why: '跑不起来 ⇒ 无法判定（⛔ 不当通过）' })
+  }
+  detail.mcp = await mcpServerInfo(root)
+  if (detail.mcp.error) findings.push({ rule: 'R2-RUNTIME', file: 'core/mcp/server.mjs', line: 0, token: null, message: `MCP 握手失败：${detail.mcp.error}`, why: '宿主读的就是这个版本' })
+  else if (detail.mcp.version !== truth) findings.push({ rule: 'R2-RUNTIME', file: 'core/mcp/server.mjs', line: 50, token: detail.mcp.version, message: `MCP \`initialize.serverInfo.version\` = ${detail.mcp.version} ≠ 真源 ${truth}`, why: '宿主读的就是这个版本（H1 采信证据即此项）' })
+  return { findings, detail }
+}
+
+/** 起一个 stdio MCP 子进程握手一次，取 `initialize.serverInfo`（**只读、零副作用**）。 */
+export function mcpServerInfo(root, timeoutMs = 15000) {
+  const server = join(root, 'core', 'mcp', 'server.mjs')
+  if (!existsSync(server)) return { error: 'core/mcp/server.mjs 不存在' }
+  const child = spawn(process.execPath, [server], { stdio: ['pipe', 'pipe', 'ignore'], env: { ...process.env, ARGENT_TELEMETRY_OFF: '1' } })
+  return new Promise((res) => {
+    let buf = ''
+    let done = false
+    const finish = (v) => { if (done) return; done = true; try { child.kill() } catch {} ; res(v) }
+    const timer = setTimeout(() => finish({ error: `握手超时（${timeoutMs}ms）` }), timeoutMs)
+    child.stdout.setEncoding('utf8')
+    child.stdout.on('data', (c) => {
+      buf += c
+      let i
+      while ((i = buf.indexOf('\n')) >= 0) {
+        const line = buf.slice(0, i).trim(); buf = buf.slice(i + 1)
+        if (!line) continue
+        let m; try { m = JSON.parse(line) } catch { continue }
+        if (m.id === 1) {
+          clearTimeout(timer)
+          finish(m.error ? { error: m.error.message } : { name: m.result?.serverInfo?.name, version: m.result?.serverInfo?.version, protocolVersion: m.result?.protocolVersion })
+        }
+      }
+    })
+    child.on('error', (e) => { clearTimeout(timer); finish({ error: e.message }) })
+    child.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'initialize', params: { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'version-consistency', version: '1' } } })}\n`)
+  })
+}
+
+// ── CLI ─────────────────────────────────────────────────────────────────────
+const isMain = process.argv[1] && resolve(process.argv[1]) === SELF
+if (isMain) {
+  const argv = process.argv.slice(2)
+  const has = (f) => argv.includes(f)
+  const val = (f) => { const i = argv.indexOf(f); return i >= 0 ? argv[i + 1] : undefined }
+  if (has('-h') || has('--help')) {
+    console.log(readFileSync(SELF, 'utf8').split('*/')[0].replace(/^\/\*\*?/, '').replace(/^ \* ?/gm, '').trim())
+    process.exit(0)
+  }
+  const STRICT = has('--strict')
+  const JSON_OUT = has('--json')
+  const NO_RUNTIME = has('--no-runtime')
+  const root = val('--root')
+  const r = run({ root })
+  if (r.truth === null) {
+    console.error(`✗ 版本一致性：拿不到唯一真源 ⇒ 停住（⛔ 不静默成功）`)
+    process.exit(2)
+  }
+  let runtime = { findings: [], detail: {} }
+  if (!NO_RUNTIME) runtime = await runRuntime({ root })
+  const findings = [...r.findings, ...runtime.findings]
+  const out = {
+    ok: findings.length === 0,
+    truth: r.truth,
+    findings,
+    info: r.info,
+    runtime: runtime.detail,
+    stats: r.stats,
+    changelog: r.changelog,
+    histDocs: r.histDocs,
+  }
+  if (JSON_OUT) {
+    console.log(JSON.stringify(out, null, 2))
+  } else {
+    console.log('\n【版本一致性】活引用 == 唯一真源')
+    console.log(`  唯一真源：VERSION = ${r.truth}`)
+    console.log(`  活引用：${LIVE_REFS.map((x) => x.id).join(' ｜ ')} ｜ 业务线 ${r.stats.verticals.length} 条`)
+    console.log(`  版本载体（必须读 VERSION）：${r.stats.carriers} 个`)
+    for (const v of r.stats.verticals) {
+      console.log(`     · ${v.id} ${v.version}  requires.argent \`${v.range}\`  ⇒ ${v.ok ? '✅ 容纳现役平台' : '❌ 不兼容'}`)
+    }
+    if (r.changelog.newest) console.log(`  CHANGELOG 最新段：${r.changelog.newest}（共 ${r.changelog.sections.length} 段；更旧的段按定义历史）`)
+    if (!NO_RUNTIME) console.log(`  跑起来：CLI version=${runtime.detail.cliVersion} ｜ versions.cli=${runtime.detail.cliVersions?.cli} ｜ MCP serverInfo=${runtime.detail.mcp?.name},${runtime.detail.mcp?.version}`)
+    console.log(`  反向扫描：${r.stats.files} 个文件（活引用面）｜ dsh 快照 ${r.stats.lockFiles} 个`)
+    console.log(`  历史记录（豁免，⛔ 不追改）：${r.info.length} 条`)
+    for (const f of findings) console.log(`  ❌ [${f.rule}] ${f.file}:${f.line || 0} ${f.message}`)
+    console.log(`\n${findings.length === 0 ? '✅' : '❌'} version-consistency: ${findings.length} 个 error / ${r.info.length} 条历史豁免`)
+  }
+  process.exit(findings.length === 0 ? 0 : (STRICT ? 1 : 0))
+}