@whyshu/argent-engine 0.0.0-stage → 0.6.0

package/engine/scripts/license-e2e-drill.mjs

@@ -0,0 +1,426 @@
+#!/usr/bin/env node
+/**
+ * license-e2e-drill —— 许可生命周期**离线端到端演练**（2026-10-04；纯夹具、零真实副作用）
+ *
+ * ## 它演练什么（= M2「许可自助签发/续期」的**本仓库侧**可测面）
+ * 三条路径里**客户端能自证的那部分**，全部离线跑一遍，每步给真机输出：
+ *   · **新客开通**：`license request` 拿设备码 → 自签一份 **v2 夹具许可**（夹具密钥）→
+ *     `install --file --dry-run`（零副作用）→ `install --file --apply`（落到**隔离数据目录**）→
+ *     `status` / `verify` / `explain` 验收 `sigV=2 ∧ deviceSigned=true ∧ state=valid ∧ binding=match`；
+ *   · **续期**：同机续期**不重绑设备**（新文件里的 `device.code` 必须与现役逐字相同）＋
+ *     **幂等判据**（同一份文件再装一次 ⇒ `unchanged:true`，不备份、不重写）；
+ *   · **反向**：改一字节 ⇒ `bad_signature`；换设备码（**重签成合法签名**）⇒ `device_mismatch`
+ *     （宽限内 `verify` 给 `3/grace`、`install` 仍拒绝落盘；宽限用尽 ⇒ `1/denied`）；
+ *     `--rebind` 消耗 1 次；次数用尽 ⇒ `rebind_exhausted`；降级/缩权安装 ⇒ `regression_refused`。
+ *
+ * ## ⛔ 三条纪律（本脚本自身就是"容易做错"的那部分）
+ *   ① **只碰隔离目录**：全部写入落在 `mkdtempSync` 出来的夹具根里，`assertInsideFixture()` 逐条自证；
+ *      目标许可位 = `$ARGENT_DATA_DIR/license.json`（夹具值），**绝不**碰 `~/.dsh/argent/**`；
+ *   ② **绝不用真密钥**：密钥是脚本内的夹具串（`FIXTURE_SECRET`，写进夹具里的 0600 临时文件），
+ *      子进程环境由 `sanitizedEnv()` **显式构造**（清掉 `DSH_HOME`/`ARGENT_DATA_DIR`/`ARGENT_LICENSE_SECRET`）；
+ *   ③ **不联网、只读一项本机事实**：唯一读的真实机器事实是硬件 UUID（判据与算法**只在**
+ *      `core/lib/license-device.mjs`，本脚本只调它、不自己读盘）；
+ *      读不到（非 Darwin）⇒ 默认**如实判 `device_unsupported` 而不是假装通过**（`--allow-unbound` 才降级为"只验 unbound"）。
+ *
+ * 用法：
+ *   node scripts/license-e2e-drill.mjs [--json] [--keep] [--allow-unbound] [--quiet]
+ * 退出码：0 全部符合预期 ｜ 1 有步骤不符合预期（逐条点名）｜ 2 用法/环境错误
+ */
+import { spawnSync } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { assertInsideFixture, sanitizedEnv } from './tests/_env.mjs'
+import { currentDevice } from '../core/lib/license-device.mjs'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const REPO = resolve(HERE, '..')
+const CLI = join(REPO, 'core', 'cli', 'argent.mjs')
+const SELF_SIGN = join(REPO, 'scripts', 'self-sign-license.mjs')
+
+/** 夹具密钥（**不是**任何真实环境的密钥；真密钥只在 ARGENT_LICENSE_SECRET / license.secret）。 */
+export const FIXTURE_SECRET = 'drill-fixture-secret-not-a-real-key'
+const DAY = 86400000
+const iso = (ms) => new Date(ms).toISOString()
+
+const argv = process.argv.slice(2)
+const has = (f) => argv.includes(f)
+
+// ── 小工具 ─────────────────────────────────────────────────────────────────
+/** 数据目录的**逐字节**快照（相对路径 → sha256），用来证明 dry-run 零副作用 / 幂等不重写。 */
+function treeHash(dir) {
+  const out = {}
+  if (!existsSync(dir)) return out
+  const walk = (d, rel) => {
+    for (const e of readdirSync(d, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      const p = join(d, e.name)
+      const r = rel ? `${rel}/${e.name}` : e.name
+      if (e.isDirectory()) walk(p, r)
+      else out[r] = createHash('sha256').update(readFileSync(p)).digest('hex').slice(0, 16)
+    }
+  }
+  walk(dir, '')
+  return out
+}
+const sameTree = (a, b) => JSON.stringify(a) === JSON.stringify(b)
+
+/**
+ * 跑一条命令。`env` **必须**由 `sanitizedEnv()` 显式构造（⛔ 不是"调用方环境 + 补丁"）。
+ * @returns {{exit:number, json:object|null, stdout:string, stderr:string, cmd:string}}
+ */
+function run(args, env, { spawn = spawnSync } = {}) {
+  const r = spawn(process.execPath, args, { encoding: 'utf8', maxBuffer: 32 * 1024 * 1024, env })
+  const stdout = String(r.stdout || '')
+  const stderr = String(r.stderr || '')
+  let json = null
+  const i = stdout.indexOf('{')
+  if (i >= 0) { try { json = JSON.parse(stdout.slice(i)) } catch { json = null } }
+  return { exit: r.status === null || r.status === undefined ? 1 : Number(r.status), json, stdout, stderr, cmd: args.map((a) => (a.includes(' ') ? JSON.stringify(a) : a)).join(' ') }
+}
+
+/**
+ * 主演练。**纯函数式**：所有副作用都在新建的夹具根内；`keep:false` 时收尾删除。
+ * @param {{repo?:string, keep?:boolean, allowUnbound?:boolean, log?:(s:string)=>void}} [o]
+ */
+export async function runDrill({ repo = REPO, keep = false, allowUnbound = false, log = () => {}, spawn = spawnSync } = {}) {
+  const root = mkdtempSync(join(tmpdir(), 'arg-lic-drill-'))
+  const home = join(root, 'home')
+  mkdirSync(home, { recursive: true })
+  const keyFile = join(root, 'fixture.key')
+  writeFileSync(keyFile, `${FIXTURE_SECRET}\n`, { mode: 0o600 })
+  chmodSync(keyFile, 0o600)
+  const cli = join(repo, 'core', 'cli', 'argent.mjs')
+  const selfSign = join(repo, 'scripts', 'self-sign-license.mjs')
+
+  const steps = []
+  /** 一条断言（记进 steps；失败不抛，最后统一判定 —— 演练要跑完，别在第一步就断）。 */
+  const check = (id, title, cond, detail = {}) => {
+    const ok = cond === true
+    steps.push({ id, title, ok, ...detail })
+    log(`${ok ? '  ✅' : '  ❌'} ${id} ${title}${ok ? '' : `  ← ${JSON.stringify(detail).slice(0, 400)}`}`)
+    return ok
+  }
+  const envFor = (dataDir, extra = {}) => sanitizedEnv({
+    home, dataDir: assertInsideFixture(dataDir, root, '数据目录'),
+    extra: { ARGENT_LICENSE_SECRET: null, ARGENT_TELEMETRY_OFF: '1', ...extra },
+  })
+  const data = (name) => {
+    const d = join(root, name)
+    mkdirSync(d, { recursive: true, mode: 0o700 })
+    return assertInsideFixture(d, root, '数据目录')
+  }
+  const writeRebind = (dir, body) => writeFileSync(join(dir, 'license-rebind.json'), `${JSON.stringify(body, null, 2)}\n`, { mode: 0o600 })
+  const lic = (dir, name) => join(dir, name)   // 许可文件放夹具根下（不是数据目录，避免与"落盘"混淆）
+
+  const machine = currentDevice({})
+  try {
+    // ══ S0 前置：本机能不能读设备码（决定后面能验到哪一步）══════════════════
+    check('S0.1', '本机可读设备码（硬件 UUID，只读；判据见 core/lib/license-device.mjs）', machine.ok === true || allowUnbound === true,
+      { deviceReason: machine.reason, deviceCode: machine.ok ? `${machine.code.slice(0, 12)}…` : null, allowUnbound })
+    if (!machine.ok && !allowUnbound) {
+      return finish(root, steps, keep, log, {
+        ok: false, reason: 'device_unsupported',
+        note: `读不到本机设备码（${machine.reason}）：${machine.error} ⇒ 本机验不了绑定=match 这一条。`
+          + '要么在能读硬件 UUID 的 macOS 上跑，要么显式 --allow-unbound（只验 unbound 形态）。',
+      })
+    }
+
+    const D1 = data('data-s1')
+    const E1 = envFor(D1)
+
+    // ══ S1 新客开通（request → 签发 → dry-run → apply → status/verify/explain）══
+    {
+      const r = run([cli, 'license', 'status', '--json'], E1, { spawn })
+      check('S1.1', '未授权机器：无许可 ⇒ exit 1 + reason=missing（不恒 0）',
+        r.exit === 1 && r.json && r.json.reason === 'missing', { exit: r.exit, reason: r.json && r.json.reason })
+    }
+    {
+      const r = run([cli, 'license', 'request', '--json'], E1, { spawn })
+      const code = r.json && r.json.device && r.json.device.code
+      check('S1.2', '`license request` 打印 64hex 设备码（离线激活第一步）',
+        r.exit === 0 && /^[0-9a-f]{64}$/.test(String(code || '')) && r.json.device.algo === 'ioplatformuuid-sha256',
+        { exit: r.exit, deviceCode: code ? `${code.slice(0, 12)}…` : null })
+      if (machine.ok) {
+        check('S1.2b', 'request 给出的码与本机指纹派生的码逐字相同（无随机成分）',
+          code === machine.code, { fromCli: code && code.slice(0, 12), fromLib: machine.code.slice(0, 12) })
+      }
+    }
+    const issued = lic(root, 'issued-v2.json')
+    const days = 365
+    {
+      const r = run([selfSign, '--user', 'drill-user-0001', '--secret-file', keyFile, '--out', issued,
+        '--cap', 'full', '--cap', 'invoice', '--vertical', 'demo-vertical', '--seats', '3',
+        '--days', String(days), '--grace', '14', '--json'], E1, { spawn })
+      const j = r.json || {}
+      check('S1.3', '自签 v2 夹具许可（缺省 v2 + 本机设备码；密钥必须显式）',
+        r.exit === 0 && j.signatureVersion === 2 && j.deviceSigned === true && j.written === true
+        && j.licenseFile && j.licenseFile.v === 2 && j.licenseFile.device && j.licenseFile.device.code === machine.code,
+        { exit: r.exit, signatureVersion: j.signatureVersion, deviceSigned: j.deviceSigned, payloadBytes: j.payload ? j.payload.length : null })
+      check('S1.3b', '自签产物**自验**通过（独立入口 verifyLicenseFile，不是"我签完了"）',
+        Boolean(j.verified && j.verified.ok === true && j.verified.reason === 'ok'), { verified: j.verified })
+      const guard = run([selfSign, '--user', 'drill-user-0001', '--secret-file', keyFile,
+        '--out', join(D1, 'license.json'), '--json'], E1, { spawn })
+      check('S1.3c', '自签工具拒绝把产物直接写到**现役许可位**（须走 install-license）',
+        guard.exit === 2 && /现役许可位/.test(guard.stderr + guard.stdout) && !existsSync(join(D1, 'license.json')),
+        { exit: guard.exit, stderr: guard.stderr.trim().slice(0, 160) })
+    }
+
+    const beforeDry = treeHash(D1)
+    {
+      const r = run([cli, 'license', 'install', '--file', issued, '--secret-file', keyFile, '--dry-run', '--json'], E1, { spawn })
+      const afterDry = treeHash(D1)
+      check('S1.4', '`install --file` 默认/显式 dry-run ⇒ exit 0 且 applied=false',
+        r.exit === 0 && r.json && r.json.dryRun === true && r.json.applied === false && r.json.signatureVersion === 2,
+        { exit: r.exit, dryRun: r.json && r.json.dryRun, applied: r.json && r.json.applied })
+      check('S1.4b', 'dry-run **零持久副作用**（数据目录逐字节不变：无许可、无备份、无计数）',
+        sameTree(beforeDry, afterDry) && Object.keys(afterDry).length === 0,
+        { before: beforeDry, after: afterDry })
+    }
+    {
+      const r = run([cli, 'license', 'install', '--file', issued, '--secret-file', keyFile, '--apply', '--json'], E1, { spawn })
+      const j = r.json || {}
+      const target = join(D1, 'license.json')
+      check('S1.5', '`install --file --apply` 落到**隔离数据目录** 0600 + 写后读回验收',
+        r.exit === 0 && j.applied === true && j.target === target && j.mode === '0600' && j.verifiedAfterInstall === true
+        && j.signatureVersion === 2 && j.deviceSigned === true && j.secretInstalled === true,
+        { exit: r.exit, target: j.target, mode: j.mode, verifiedAfterInstall: j.verifiedAfterInstall, secretInstalled: j.secretInstalled })
+      check('S1.5b', '落盘目标**不在**真实数据目录（夹具自证）',
+        !String(target).includes('/.dsh/argent/') && assertInsideFixture(target, root, '许可位') === target, { target })
+      const raw = JSON.parse(readFileSync(target, 'utf8'))
+      check('S1.5c', '落盘内容 = 签发的 v2 文件（含 device 三键）',
+        raw.v === 2 && raw.device && raw.device.code === machine.code && String(raw.sig).length === 64, { v: raw.v, sigLen: String(raw.sig).length })
+    }
+    {
+      const r = run([cli, 'license', 'status', '--json'], E1, { spawn })
+      const j = r.json || {}
+      check('S1.6', '★ 验收：status ⇒ state=valid ∧ sigV=2 ∧ deviceSigned=true ∧ binding=match',
+        r.exit === 0 && j.state === 'valid' && j.signatureVersion === 2 && j.deviceSigned === true
+        && j.device && j.device.binding === 'match' && j.device.signed === true,
+        { exit: r.exit, state: j.state, signatureVersion: j.signatureVersion, deviceSigned: j.deviceSigned, binding: j.device && j.device.binding })
+      check('S1.6b', 'status 回显能力/业务线/席位/到期（与签发入参一致）',
+        JSON.stringify(j.capabilities) === JSON.stringify(['full', 'invoice'])
+        && JSON.stringify(j.verticals) === JSON.stringify(['demo-vertical']) && j.seats === 3,
+        { capabilities: j.capabilities, verticals: j.verticals, seats: j.seats, expiresAt: j.expiresAt })
+    }
+    {
+      const r = run([cli, 'license', 'verify', '--json'], E1, { spawn })
+      const j = r.json || {}
+      check('S1.7', '`license verify` 单独答"验签本身"：signature.ok ∧ algorithm=HMAC-SHA256 ∧ 不落盘',
+        r.exit === 0 && j.subcommand === 'verify' && j.signature && j.signature.ok === true
+        && j.signature.algorithm === 'HMAC-SHA256' && j.signature.deviceSigned === true && j.signatureVersion === 2,
+        { exit: r.exit, signature: j.signature })
+    }
+    {
+      const r = run([cli, 'license', 'explain', '--json'], E1, { spawn })
+      const j = r.json || {}
+      check('S1.8', '`license explain` 无缺失项 + 明确说清 v2 的局限（HMAC 对称密钥 ≠ 防伪）',
+        r.exit === 0 && Array.isArray(j.missing) && j.missing.length === 0
+        && /不防(伪|止)？|不防.*重签|HMAC/.test(String(j.limitation && j.limitation.device))
+        && /礼貌上限/.test(String(j.limitation && j.limitation.rebind)),
+        { exit: r.exit, missing: j.missing, limitationDevice: String(j.limitation && j.limitation.device).slice(0, 120) })
+    }
+
+    // ══ S2 续期（同机不重绑 + 幂等）══════════════════════════════════════════
+    const renewed = lic(root, 'renewed-v2.json')
+    {
+      const r = run([selfSign, '--user', 'drill-user-0001', '--secret-file', keyFile, '--out', renewed,
+        '--cap', 'full', '--cap', 'invoice', '--vertical', 'demo-vertical', '--seats', '3',
+        '--days', String(days * 2), '--grace', '14', '--json'], E1, { spawn })
+      const j = r.json || {}
+      check('S2.1', '续期许可：**同一本机设备码**再签一份（更晚到期）',
+        r.exit === 0 && j.licenseFile.device.code === machine.code
+        && Date.parse(j.licenseFile.expiresAt) > Date.parse(JSON.parse(readFileSync(join(D1, 'license.json'), 'utf8')).expiresAt),
+        { exit: r.exit, expiresAt: j.licenseFile && j.licenseFile.expiresAt })
+    }
+    {
+      const r = run([cli, 'license', 'renew', '--file', renewed, '--apply', '--json'], E1, { spawn })
+      const j = r.json || {}
+      check('S2.2', '`license renew --file` 走 install 同一条路：落盘 + 设备码保持 match（**不消耗重绑**）',
+        r.exit === 0 && j.applied === true && j.device && j.device.binding === 'match'
+        && j.device.rebindsLeft === 3 && j.incumbent && j.incumbent.present === true,
+        { exit: r.exit, binding: j.device && j.device.binding, rebindsLeft: j.device && j.device.rebindsLeft, unchanged: j.unchanged })
+      check('S2.2b', '续期回显 `renewal.deviceChanged=false`（同机续期**没有**换绑）',
+        Boolean(j.renewal && j.renewal.deviceChanged === false), { renewal: j.renewal })
+    }
+    {
+      const target = join(D1, 'license.json')
+      const before = treeHash(D1)
+      const beforeStat = statSync(target).mtimeMs
+      const r = run([cli, 'license', 'renew', '--file', renewed, '--apply', '--json'], E1, { spawn })
+      const after = treeHash(D1)
+      const j = r.json || {}
+      check('S2.3', '★ 幂等判据：同一份文件再装一次 ⇒ `unchanged:true` ∧ 不备份 ∧ 不重写（mtime 不变）',
+        r.exit === 0 && j.unchanged === true && Array.isArray(j.backups) && j.backups.length === 0
+        && sameTree(before, after) && statSync(target).mtimeMs === beforeStat,
+        { exit: r.exit, unchanged: j.unchanged, backups: j.backups, mtimeSame: statSync(target).mtimeMs === beforeStat })
+    }
+
+    // ══ S3 反向：改一字节 / 换设备码 / 宽限 / 重绑 / 降级缩权 ══════════════════
+    const tampered = lic(root, 'tampered.json')
+    {
+      const raw = readFileSync(renewed, 'utf8').replace('"full"', '"fuLl"')   // 精确改一字节（大小写）
+      writeFileSync(tampered, raw, { mode: 0o600 })
+      const r = run([cli, 'license', 'verify', '--file', tampered, '--json'], E1, { spawn })
+      const j = r.json || {}
+      check('S3.1', '改一字节（capabilities 大小写）⇒ exit 1 + reason=bad_signature',
+        r.exit === 1 && j.reason === 'bad_signature' && j.signature && j.signature.ok === false,
+        { exit: r.exit, reason: j.reason, signature: j.signature && j.signature.reason })
+      const r2 = run([cli, 'license', 'status', '--file', tampered, '--json'], E1, { spawn })
+      check('S3.1b', 'status 对同一份文件也判 denied + bad_signature（两个 verb 同源判据）',
+        r2.exit === 1 && r2.json.state === 'denied' && r2.json.licenseReason === 'bad_signature',
+        { exit: r2.exit, state: r2.json && r2.json.state, licenseReason: r2.json && r2.json.licenseReason })
+    }
+
+    // 换设备码：**重签**成"合法签名但属于另一台机器"的许可（这才是真正的换机场景）
+    const otherMachine = lic(root, 'other-machine-v2.json')
+    const otherCode = createHash('sha256').update('ioplatformuuid-sha256:ANOTHER-MACHINE-FIXTURE').digest('hex')
+    {
+      const base = JSON.parse(readFileSync(renewed, 'utf8'))
+      base.device = { code: otherCode, algo: base.device.algo, issuedAt: base.device.issuedAt }
+      // ⚠️ 必须用夹具密钥**重签**：v2 把 device 纳入签名 ⇒ 改完不重签只会得到 bad_signature，验不到设备这一层
+      const { signLicenseFile } = await import('../core/lib/license-file.mjs')
+      const signed = signLicenseFile(base, FIXTURE_SECRET, { version: 2 })
+      if (!signed.ok) throw new Error(`夹具重签失败：${signed.reason}`)
+      writeFileSync(otherMachine, `${JSON.stringify(signed.file, null, 2)}\n`, { mode: 0o600 })
+      check('S3.2', '构造"合法签名但绑定另一台机器"的许可（换机场景，v2 下改 device 必须重签）',
+        signed.ok === true && signed.file.device.code === otherCode && otherCode !== machine.code, { otherCode: `${otherCode.slice(0, 12)}…` })
+    }
+    const D3 = data('data-s3')
+    const E3 = envFor(D3)
+    {
+      const r = run([cli, 'license', 'verify', '--file', otherMachine, '--secret-file', keyFile, '--json'], E3, { spawn })
+      const j = r.json || {}
+      check('S3.3', '换机许可在本机：**宽限内** verify ⇒ exit 3（grace 放行 + 告警，不 fail-closed）',
+        r.exit === 3 && j.state === 'grace' && j.reason === 'license_grace' && j.device && j.device.binding === 'mismatch'
+        && j.device.sanctioned === true,
+        { exit: r.exit, state: j.state, binding: j.device && j.device.binding, graceUntil: j.device && j.device.graceUntil })
+      const r2 = run([cli, 'license', 'install', '--file', otherMachine, '--dry-run', '--secret-file', keyFile, '--json'], E3, { spawn })
+      check('S3.3b', '但 `install` **一律拒绝落盘**（exit 1 + device_mismatch，数据目录不变）',
+        r2.exit === 1 && r2.json.reason === 'device_mismatch' && Object.keys(treeHash(D3)).length === 0,
+        { exit: r2.exit, reason: r2.json && r2.json.reason, dir: treeHash(D3) })
+    }
+    {
+      // 宽限用尽：把"第一次发现不匹配"的时刻放到 8 天前（夹具里注入，不等待 7 天）
+      writeRebind(D3, { v: 1, count: 0, acceptedCodes: [], rebinds: [], firstMismatchAt: iso(Date.now() - 8 * DAY) })
+      const r = run([cli, 'license', 'verify', '--file', otherMachine, '--secret-file', keyFile, '--json'], E3, { spawn })
+      check('S3.4', '7 天宽限用尽（firstMismatchAt=8 天前）⇒ exit 1 + denied + device_mismatch',
+        r.exit === 1 && r.json.state === 'denied' && r.json.device && r.json.device.binding === 'mismatch'
+        && r.json.device.graceLeftDays === 0,
+        { exit: r.exit, state: r.json && r.json.state, reason: r.json && r.json.reason, graceLeftDays: r.json && r.json.device && r.json.device.graceLeftDays })
+    }
+    {
+      // 自助重绑（计数归零后走 --rebind）：消耗 1 次 ⇒ 放行且 binding=rebound
+      writeRebind(D3, { v: 1, count: 0, acceptedCodes: [], rebinds: [], firstMismatchAt: null })
+      const r = run([cli, 'license', 'install', '--file', otherMachine, '--rebind', '--apply', '--secret-file', keyFile, '--json'], E3, { spawn })
+      const j = r.json || {}
+      check('S3.5', '自助重绑（`--rebind --apply`）⇒ exit 0、消耗 1 次、装完 binding=rebound',
+        r.exit === 0 && j.applied === true && j.rebind && j.rebind.consumed === true && j.rebind.count === 1
+        && j.device && j.device.binding === 'rebound' && j.device.rebindsLeft === 2,
+        { exit: r.exit, rebind: j.rebind, binding: j.device && j.device.binding, rebindsLeft: j.device && j.device.rebindsLeft })
+      const store = JSON.parse(readFileSync(join(D3, 'license-rebind.json'), 'utf8'))
+      check('S3.5b', '计数落 `$ARGENT_DATA_DIR/license-rebind.json`（**在夹具内**，可删 = 礼貌上限）',
+        store.count === 1 && assertInsideFixture(join(D3, 'license-rebind.json'), root, '计数文件') === join(D3, 'license-rebind.json'),
+        { store })
+    }
+    {
+      // 次数用尽：3 次已用 ⇒ 第 4 次拒绝 + 人工指引
+      writeRebind(D3, { v: 1, count: 3, acceptedCodes: [], rebinds: [], firstMismatchAt: iso(Date.now() - DAY) })
+      const r = run([cli, 'license', 'install', '--file', otherMachine, '--rebind', '--apply', '--secret-file', keyFile, '--json'], E3, { spawn })
+      const j = r.json || {}
+      check('S3.6', '重绑用尽（第 4 次）⇒ exit 1 + rebind_exhausted + 人工指引',
+        r.exit === 1 && j.reason === 'rebind_exhausted' && j.device.rebindsLeft === 0
+        && /人工|重签/.test(String(j.device.note || '') + String(j.rebind && j.rebind.note || '')),
+        { exit: r.exit, reason: j.reason, note: String(j.device && j.device.note).slice(0, 100) })
+    }
+
+    // ── S3.7/S3.8 降级与缩权（安装侧的"现役许可比对"守卫）────────────────────
+    const D4 = data('data-s4')
+    const E4 = envFor(D4)
+    {
+      const r = run([cli, 'license', 'install', '--file', renewed, '--secret-file', keyFile, '--apply', '--json'], E4, { spawn })
+      check('S3.7-pre', '装一份现役（用于比对基线）', r.exit === 0 && r.json.applied === true, { exit: r.exit })
+    }
+    const stale = lic(root, 'stale-v2.json')
+    {
+      const base = JSON.parse(readFileSync(renewed, 'utf8'))
+      base.expiresAt = iso(Date.parse(base.expiresAt) - 90 * DAY)      // 更早到期 = 降级
+      const { signLicenseFile } = await import('../core/lib/license-file.mjs')
+      const signed = signLicenseFile(base, FIXTURE_SECRET, { version: 2 })
+      writeFileSync(stale, `${JSON.stringify(signed.file, null, 2)}\n`, { mode: 0o600 })
+      const r = run([cli, 'license', 'install', '--file', stale, '--dry-run', '--json'], E4, { spawn })
+      const j = r.json || {}
+      check('S3.7', '★ 降级安装（更早到期）⇒ exit 1 + `regression_refused`（不静默缩短客户有效期）',
+        r.exit === 1 && j.reason === 'regression_refused' && j.comparison && j.comparison.stale === true
+        && j.incumbent && j.incumbent.present === true,
+        { exit: r.exit, reason: j.reason, comparison: j.comparison })
+      const r2 = run([cli, 'license', 'install', '--file', stale, '--apply', '--json'], E4, { spawn })
+      const rawTarget = JSON.parse(readFileSync(join(D4, 'license.json'), 'utf8'))
+      check('S3.7b', '拒绝时**原许可一个字节都不动**（现役 expiresAt 未变）',
+        r2.exit === 1 && rawTarget.expiresAt === JSON.parse(readFileSync(renewed, 'utf8')).expiresAt,
+        { exit: r2.exit, targetExpiresAt: rawTarget.expiresAt })
+      const r3 = run([cli, 'license', 'install', '--file', stale, '--apply', '--allow-regression', '--json'], E4, { spawn })
+      check('S3.7c', '显式 `--allow-regression` ⇒ 放行（刻意的摩擦：要么给理由，要么别装）',
+        r3.exit === 0 && r3.json.applied === true && r3.json.comparison.stale === true,
+        { exit: r3.exit, comparison: r3.json && r3.json.comparison })
+    }
+    const narrowed = lic(root, 'narrowed-v2.json')
+    {
+      const base = JSON.parse(readFileSync(renewed, 'utf8'))
+      base.capabilities = ['full']                                    // 少了 invoice = 静默收回能力
+      const { signLicenseFile } = await import('../core/lib/license-file.mjs')
+      const signed = signLicenseFile(base, FIXTURE_SECRET, { version: 2 })
+      writeFileSync(narrowed, `${JSON.stringify(signed.file, null, 2)}\n`, { mode: 0o600 })
+      const r = run([cli, 'license', 'install', '--file', narrowed, '--dry-run', '--json'], E4, { spawn })
+      const j = r.json || {}
+      check('S3.8', '★ 缩权安装（少一个 capability）⇒ exit 1 + `regression_refused`（不静默收回能力）',
+        r.exit === 1 && j.reason === 'regression_refused' && j.comparison && j.comparison.narrowed === true
+        && Array.isArray(j.comparison.missingCapabilities) && j.comparison.missingCapabilities.includes('invoice'),
+        { exit: r.exit, reason: j.reason, comparison: j.comparison })
+    }
+  } catch (e) {
+    check('X.1', '演练未抛异常（夹具/环境异常按失败回报，不吞）', false, { error: String(e && e.message || e).slice(0, 300) })
+  }
+  const failed = steps.filter((s) => !s.ok)
+  return finish(root, steps, keep, log, {
+    ok: failed.length === 0,
+    reason: failed.length ? 'drill_assertions_failed' : null,
+    failed: failed.map((s) => s.id),
+  })
+}
+
+function finish(root, steps, keep, log, extra) {
+  if (!keep) { try { rmSync(root, { recursive: true, force: true }) } catch { /* 收尾失败不影响结论 */ } }
+  const failed = steps.filter((s) => !s.ok)
+  const summary = {
+    ok: extra.ok === true, reason: extra.reason || null, note: extra.note || null,
+    fixtureRoot: keep ? root : '(已删除；--keep 可保留)',
+    steps: steps.length, passed: steps.length - failed.length, failed: failed.map((s) => s.id),
+    deviceBindable: steps.find((s) => s.id === 'S0.1')?.ok === true,
+  }
+  return { ...summary, steps, fixtureRootPath: root }
+}
+
+// ── CLI ────────────────────────────────────────────────────────────────────
+const isMain = process.argv[1] && resolve(process.argv[1]) === resolve(fileURLToPath(import.meta.url))
+if (isMain) {
+  if (has('--help') || has('-h')) {
+    console.log('用法：node scripts/license-e2e-drill.mjs [--json|--quiet] [--keep] [--allow-unbound]')
+    console.log('  纯夹具离线演练：request → 自签 v2 → install(dry-run/apply) → status/verify/explain → 反向（改字节/换机/宽限/重绑/降级/缩权）')
+    console.log('  ⛔ 所有写入落在 mkdtemp 夹具内；绝不碰 ~/.dsh/argent/**、绝不联网、绝不用真密钥')
+    process.exit(0)
+  }
+  // A2 纪律：`--json` 时 stdout **只有一份 JSON** ⇒ 与 `--quiet` 同义（人话步骤行自动静音）
+  const quiet = has('--quiet') || has('--json')
+  const r = await runDrill({ keep: has('--keep'), allowUnbound: has('--allow-unbound'), log: quiet ? () => {} : (s) => console.log(s) })
+  if (has('--json')) console.log(JSON.stringify({ ...r, steps: r.steps }, null, 2))
+  else {
+    console.log(`\n  ${r.ok ? '✅' : '❌'} 离线端到端演练：${r.passed}/${r.steps.length} 步符合预期`
+      + (r.reason ? `（reason=${r.reason}${r.note ? `：${r.note}` : ''}）` : ''))
+    if (r.failed.length) console.log(`     失败步骤：${r.failed.join(', ')}`)
+    console.log(`     夹具根：${r.fixtureRoot}`)
+  }
+  process.exit(r.ok ? 0 : 1)
+}
+export { treeHash }