@whyshu/argent-engine 0.0.0-stage → 0.6.0

package/engine/core/lib/license.mjs

@@ -0,0 +1,577 @@
+/**
+ * `argent license <sub>` 适配层（P1 第二批，2026-10-03）—— 把**既有判据**接成机器可判的 verb。
+ *
+ * ## 纪律（§3.5①）：本文件**不复制任何判据**
+ * | 子命令 | 判据在哪（唯一落点） | 本层只做 |
+ * |---|---|---|
+ * | `status`  | `scripts/check-license.mjs --json`（← `core/lib/license-verdict.mjs` 三态 + 设备） | 透传退出码 0/3/1/2 + A2 回显 |
+ * | `verify`  | `core/lib/license-verdict.mjs`（验签 + 判期 + 设备） | 把"验签本身"单独答出来（**不落盘**） |
+ * | `install` | `scripts/install-license.mjs`（验签后落盘 0600 + 备份 + 设备比对 + 自助重绑 + **现役比对**） | 默认 dry-run、`--apply` 才真写 |
+ * | `request` | `core/lib/license-device.mjs`（指纹**只认硬件 UUID 一项**，D3） | 打印设备码（离线激活第一步） |
+ * | `renew`   | 离线 = "验签一份新文件"（走 install 同一条路）；在线端点属外部依赖（策划案②） | 没有新文件 ⇒ **成功但空**（`empty:true`），**绝不**当 denied |
+ * | `explain` | 同上（只重组 `check-license --json` 的既有字段） | 把三态翻译成"缺什么 / 下一步做什么" |
+ *
+ * ## A1/A2/A3
+ *   · A1：`0` 成功（含"成功但空"）｜`3` **仅**许可宽限放行｜`2` 用法/环境（缺 `--file`、显式路径不存在、
+ *     指纹读不到）｜`1` 运行失败（验签不过 / 超宽限 / **设备不匹配且自助重绑用尽** ⇒ 被拒）。
+ *   · A2：`ok/empty/code/reason` 恒在；`$? == json.code`；`--json` 时 stdout 只有一份 JSON。
+ *     回显 `licenseFile`/`state`/`expiresAt`/`graceDays` + **签名版本**（`signatureVersion` 1｜2｜null）
+ *     + 设备绑定态（binding/reason/rebindsLeft + `signed`/`claimSigned`）。
+ *     `signed` 的语义**按版本**：v1 ⇒ `false`（`device` 未进签名，服务端声明 + 客户端比对）；
+ *     v2 ∧ 验签通过 ⇒ `true`（声明的**内容或它的缺位**都被签名覆盖）—— 判据来自验签结果，本层不重算。
+ *   · A3：`install`/`renew` 是写类 ⇒ **默认 dry-run**（真写要 `--apply`/`--yes`/`--confirm`）；
+ *     dry-run **零持久副作用**（不落许可、不备份、不写重绑计数）—— 判据 = 跑两次后数据目录逐字节不变。
+ *   · A4（装机/续期侧，2026-10-04）：**幂等** = 与现役**载荷+签名**逐字节一致 ⇒ `unchanged:true`（不备份、不重写）；
+ *     **拒绝倒退** = 比现役更早到期（`stale`）或能力/席位被收窄（`narrowed`）⇒ `regression_refused`（exit 1，不落盘），
+ *     显式 `--allow-regression` 才放行；**换绑**（`renewal.deviceChanged`）只如实标注 —— 设备侧的拒绝归 ② 的比对。
+ *
+ * ## `renew` 与文档口径的一处如实差异
+ * 实施方案 §3.5① 建议 `renew` "包 `scripts/lease.py`（--status/--check）"。本层**刻意不包**：
+ * 租约（能力订阅）与离线许可是**两条授权链路**，`lease.py` 的判据归 `flow-trigger.sh` 的租约闸门；
+ * 把它的结论塞进 `renew` 只会让"我到底缺哪一样"更难回答（§2.2④ 那种恒 `ok:true` 的翻版）。
+ * `renew` 只回答一件事：**有没有一份可用的新许可文件**；没有 ⇒ `empty:true + no_refresh_source`。
+ */
+import { spawnSync } from 'node:child_process'
+import { existsSync, readFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { licenseVerdict } from './license-verdict.mjs'
+import { MAX_REBINDS, REBIND_GRACE_DAYS, currentDevice, rebindStoreInfo, readRebindStore } from './license-device.mjs'
+import { ACTIVATE_BOOL_FLAGS, ACTIVATE_VALUE_FLAGS, ACTIVATE_USAGE, activateVerb } from './license-activate.mjs'
+// 只读运营巡检（O2：替代 `mongosh`）—— 参数表**从实现模块导入**（不在这里再写一份，避免"帮助里有、解析里没有"）
+import { OPS_BOOL_FLAGS, OPS_REPEAT_FLAGS, OPS_VALUE_FLAGS, runOpsVerb } from './license-ops.mjs'
+
+/** 本组 verb 的子命令（与 `core/contracts/argent.contracts.json#verbs.license.subcommands` 逐字对齐）。 */
+export const LICENSE_SUBCOMMANDS = ['status', 'verify', 'install', 'request', 'renew', 'explain', 'activate', 'ops']
+const CONFIRM_FLAGS = ['--apply', '--yes', '--confirm']
+
+/** 参数规格：`value` 带值（可重复的放 `repeat`），`bool` 无值。 */
+const SPEC = {
+  status: { value: ['--file', '--vertical', '--now'], repeat: ['--cap'], bool: [] },
+  verify: { value: ['--file', '--secret-file', '--now'], repeat: [], bool: [] },
+  install: { value: ['--file', '--secret-file', '--now', '--sign-version', '--device-code'], repeat: [], bool: ['--rebind', '--sign-v2', '--device-from-local', '--no-device', '--allow-regression', ...CONFIRM_FLAGS, '--dry-run'] },
+  request: { value: [], repeat: [], bool: [] },
+  renew: { value: ['--file', '--secret-file', '--now', '--sign-version', '--device-code'], repeat: [], bool: ['--sign-v2', '--device-from-local', '--no-device', '--rebind', '--allow-regression', ...CONFIRM_FLAGS, '--dry-run', '--online'] },
+  explain: { value: ['--file', '--vertical', '--now'], repeat: ['--cap'], bool: [] },
+  // 一次性激活码兑换（§9）：**默认 dry-run**（零网络 + 零落盘），`--apply` 才真兑换；
+  // 参数表与 `license-activate.mjs#ACTIVATE_*_FLAGS` 同源（不各写一份，避免"帮助里有、解析里没有"）。
+  activate: { value: [...ACTIVATE_VALUE_FLAGS], repeat: [], bool: [...ACTIVATE_BOOL_FLAGS] },
+  // 只读运营巡检（O2）：**读类**，没有 `--apply`/`--yes` —— 参数表与 `license-ops.mjs#OPS_*_FLAGS` 同源。
+  // ⚠️ 它的 argv 解析在 `runOpsVerb` 内部（同一张表），因此这里不做 `parseSubArgs('ops', …)`（避免两份解析）。
+  ops: { value: [...OPS_VALUE_FLAGS], repeat: [...OPS_REPEAT_FLAGS], bool: [...OPS_BOOL_FLAGS] },
+}
+const KNOWN = new Set([...Object.values(SPEC).flatMap((s) => [...s.value, ...s.repeat, ...s.bool]), '--json'])
+
+/** 解析 argv（**未知参数一律拒绝** ⇒ 2；"别的参数我替你吃了"是错误推迟到脚本里才暴露的经典坑）。 */
+export function parseSubArgs(sub, argv = []) {
+  const spec = SPEC[sub] || { value: [], repeat: [], bool: [] }
+  const values = {}
+  const repeats = {}
+  const bools = new Set()
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--json') continue
+    if (!KNOWN.has(a)) return { ok: false, reason: 'usage_error', error: `未知参数：${a}（用法：argent license ${sub} …）` }
+    if (spec.bool.includes(a)) { bools.add(a); continue }
+    if (spec.value.includes(a) || spec.repeat.includes(a)) {
+      const v = argv[i + 1]
+      if (v === undefined || String(v).startsWith('--')) return { ok: false, reason: 'usage_error', error: `参数 ${a} 缺值` }
+      if (spec.repeat.includes(a)) (repeats[a] ||= []).push(v)
+      else values[a] = v
+      i++
+      continue
+    }
+    // 属于别的子命令的合法参数 ⇒ 明确报"这个子命令没有它"（不要静默忽略）
+    return { ok: false, reason: 'usage_error', error: `子命令 ${sub} 不支持参数：${a}` }
+  }
+  return { ok: true, values, repeats, bools }
+}
+
+const flag = (v) => (v === undefined ? null : v)
+const envOf = (deps) => deps.env || process.env
+/** 子进程（可注入便于夹具）。 */
+function runNode(script, args, deps = {}) {
+  const spawn = deps.spawn || spawnSync
+  const r = spawn(process.execPath, [script, ...args], { encoding: 'utf8', maxBuffer: 32 * 1024 * 1024, env: envOf(deps) })
+  return { status: r.status === null || r.status === undefined ? 1 : Number(r.status), stdout: r.stdout || '', stderr: r.stderr || '', error: r.error || null }
+}
+/** 解析子进程 stdout 的 JSON（失败 ⇒ null，由调用方转成 bad_output）。 */
+function parseJson(text) {
+  const s = String(text || '')
+  const i = s.indexOf('{')
+  if (i < 0) return null
+  try { return JSON.parse(s.slice(i)) } catch { return null }
+}
+/** 统一失败信封（A2）。 */
+const failJson = (code, reason, error, extra = {}) => ({
+  json: { ok: false, empty: false, code, reason, error, ...extra },
+  human: `❌ ${reason}：${error}`,
+  stderr: '',
+  exit: code,
+})
+/** 设备回显（对外形状；`signed` = 该版本的签名载荷**是否覆盖 device 这一项**，见 §3.6③）。 */
+function deviceEcho(d) {
+  if (!d) return null
+  return {
+    present: d.present, signed: d.signed === true, claimSigned: d.claimSigned === true,
+    binding: d.binding, reason: d.reason, sanctioned: d.sanctioned,
+    code: d.code, algo: d.algo, issuedAt: d.issuedAt, machineCode: d.machineCode,
+    machineReadable: d.machineReadable, rebindsLeft: d.rebindsLeft,
+    graceUntil: d.graceUntil, graceLeftDays: d.graceLeftDays, note: d.note,
+  }
+}
+/** A2 的 `reason` 只认词表里的短码（`argent.contracts.json#reasonCodes`）；这里做**边界翻译**。 */
+function reasonOf({ allowed, state, gateReason, licenseReason }) {
+  if (allowed) return state === 'grace' ? 'license_grace' : null
+  return gateReason || licenseReason || 'guard_rejected'
+}
+
+// ── status ─────────────────────────────────────────────────────────────────
+function statusVerb(sub, args, deps) {
+  const p = parseSubArgs(sub, args)
+  if (!p.ok) return failJson(2, p.reason, p.error)
+  const repo = deps.repo
+  const cli = [join(repo, 'scripts', 'check-license.mjs'), '--json']
+  if (p.values['--file']) cli.push('--file', p.values['--file'])
+  if (p.values['--vertical']) cli.push('--vertical', p.values['--vertical'])
+  if (p.values['--now']) cli.push('--now', p.values['--now'])
+  for (const c of p.repeats['--cap'] || []) cli.push('--cap', c)
+  const child = runNode(cli[0], cli.slice(1), deps)
+  const j = parseJson(child.stdout)
+  if (!j) {
+    return failJson(1, 'bad_output',
+      `check-license 输出不可解析（exit=${child.status}）：${String(child.stderr || child.stdout).trim().slice(0, 300)}`)
+  }
+  const allowed = j.allowed === true
+  const reason = reasonOf({ allowed, state: j.state, gateReason: j.gateReason, licenseReason: j.reason })
+  const json = {
+    ok: allowed,
+    empty: false,
+    code: allowed ? (j.state === 'grace' ? 3 : 0) : 1,
+    reason,
+    // 回显（A2 纪律：生效值 + 判据来源，一眼能看出"真没有"还是"被别人拒了"）
+    subcommand: 'status',
+    licenseFile: j.path,
+    licenseMode: j.mode,
+    state: j.state,
+    licenseReason: j.reason,          // 原始原因（missing/bad_signature/expired/…），供诊断
+    expiresAt: j.expiresAt || null,
+    issuedAt: j.issuedAt || null,
+    graceDays: j.graceDays,
+    graceUntil: j.graceUntil || null,
+    inGrace: j.inGrace === true,
+    graceSource: j.graceSource || null,
+    // 签名版本（1｜2｜null）+ `device` 是否进签名（v1 ⇒ false；v2 ∧ 验签通过 ⇒ true）
+    signatureVersion: j.signatureVersion ?? null,
+    deviceSigned: j.device && j.device.signed === true,
+    userId: j.userId || '',
+    seats: j.seats,
+    capabilities: j.capabilities || [],
+    verticals: j.verticals || [],
+    requestedCaps: j.requestedCaps || [],
+    requestedVertical: j.requestedVertical || null,
+    gateReason: j.gateReason || null,
+    device: j.device || null,
+    conclusion: j.conclusion || '',
+    warnings: j.warnings || [],
+    // 证据/口径来源（**判定点唯一在 CLI 进程内**：本 verb 只是透传，不自己算）
+    judgedBy: 'scripts/check-license.mjs',
+  }
+  const human = humanStatus(json)
+  return { json, human, stderr: '', exit: Number(json.code) }
+}
+
+function humanStatus(j) {
+  const mark = j.ok ? (j.state === 'grace' ? '⚠️' : '✅') : '❌'
+  const lines = [`${mark} 许可状态：${j.state}（${j.reason || j.licenseReason || 'ok'}）`]
+  lines.push(`   文件：${j.licenseFile}${j.licenseMode ? `（${j.licenseMode}）` : ''}`)
+  lines.push(`   签名版本：${j.signatureVersion === 2 ? 'v2（device 已进签名）' : (j.signatureVersion === 1 ? 'v1（device 未进签名）' : '判不出')}`)
+  if (j.expiresAt) lines.push(`   账号：${j.userId || '(未写)'} ｜ 席位：${j.seats} ｜ 到期：${j.expiresAt}（宽限 ${j.graceDays} 天至 ${j.graceUntil}）`)
+  if (j.capabilities.length || j.verticals.length) lines.push(`   能力：${j.capabilities.join(',') || '(空 ⇒ 拒一切能力)'} ｜ 业务线：${j.verticals.join(',') || '(空 = 不限)'}`)
+  if (j.device) {
+    lines.push(`   设备：${j.device.binding}（${j.device.reason}）｜ 重绑还剩 ${j.device.rebindsLeft} 次`
+      + `${j.device.machineCode ? ` ｜ 本机设备码 ${String(j.device.machineCode).slice(0, 12)}…` : ''}`)
+    lines.push(`     ${deviceSignedText({ signatureVersion: j.signatureVersion, device: j.device })}`)
+  }
+  if (j.conclusion) lines.push(`   结论：${j.conclusion}`)
+  for (const w of j.warnings) lines.push(`   ⚠️ ${w}`)
+  return lines.join('\n')
+}
+
+// ── verify ─────────────────────────────────────────────────────────────────
+function verifyVerb(sub, args, deps) {
+  const p = parseSubArgs(sub, args)
+  if (!p.ok) return failJson(2, p.reason, p.error)
+  const explicit = flag(p.values['--file'])
+  if (explicit && !existsSync(resolve(explicit))) {
+    // 显式给了路径却不存在 ⇒ **用法/环境错误（2）**，不是"许可被拒"（这两件事的处置完全不同）
+    return failJson(2, 'usage_error', `--file 指向的许可文件不存在：${resolve(explicit)}`)
+  }
+  const now = p.values['--now'] ? Date.parse(p.values['--now']) : Date.now()
+  if (Number.isNaN(now)) return failJson(2, 'usage_error', `--now 不是可解析的时间：${p.values['--now']}`)
+  const v = licenseVerdict({ file: explicit ? resolve(explicit) : undefined, now, secretPath: p.values['--secret-file'] ? resolve(p.values['--secret-file']) : undefined })
+  const signatureOk = v.baseOk === true
+  const json = {
+    ok: v.ok === true,
+    empty: false,
+    code: v.exit,
+    reason: v.ok === true ? (v.state === 'grace' ? 'license_grace' : null) : (v.device && v.device.binding === 'mismatch' ? v.device.reason : v.reason),
+    subcommand: 'verify',
+    licenseFile: v.path,
+    state: v.state,
+    signatureVersion: v.signatureVersion === 2 ? 2 : (v.signatureVersion === 1 ? 1 : null),
+    deviceSigned: v.deviceSigned === true,
+    signature: { ok: signatureOk, reason: v.reason, version: v.signatureVersion === 2 ? 2 : (v.signatureVersion === 1 ? 1 : null),
+      algorithm: 'HMAC-SHA256', deviceSigned: v.deviceSigned === true },
+    device: deviceEcho(v.device),
+    userId: v.userId || '',
+    seats: v.seats,
+    expiresAt: v.expiresAt || null,
+    issuedAt: v.issuedAt || null,
+    graceDays: v.graceDays,
+    graceUntil: v.graceUntil || null,
+    graceSource: v.graceSource || null,
+    inGrace: v.inGrace === true,
+    capabilities: v.capabilities || [],
+    verticals: v.verticals || [],
+    warnings: v.warnings || [],
+    judgedBy: 'core/lib/license-verdict.mjs',
+  }
+  const human = (signatureOk
+    ? `${v.ok ? (v.state === 'grace' ? '⚠️' : '✅') : '❌'} 验签通过（${v.reason}）⇒ state=${v.state}`
+    : `❌ 验签未通过（${v.reason}）`)
+    + `\n   文件：${v.path}`
+    + `\n   签名版本：${json.signatureVersion === null ? '判不出' : `v${json.signatureVersion}`}`
+      + ` ｜ device 进签名：${v.deviceSigned === true ? '是' : '否'}`
+    + (json.device ? `\n   设备：${json.device.binding}（${json.device.reason}）｜ 重绑还剩 ${json.device.rebindsLeft} 次` : '')
+    + (v.warnings || []).map((w) => `\n   ⚠️ ${w}`).join('')
+  return { json, human, stderr: '', exit: Number(json.code) }
+}
+
+// ── install / renew（写类：默认 dry-run）────────────────────────────────────
+function installLike(sub, args, deps) {
+  const p = parseSubArgs(sub, args)
+  if (!p.ok) return failJson(2, p.reason, p.error)
+  const file = flag(p.values['--file'])
+  if (sub === 'install' && !file) {
+    return failJson(2, 'usage_error', '缺必填参数 --file <许可文件>（用法：argent license install --file <许可> [--apply]）')
+  }
+  if (file && !existsSync(resolve(file))) return failJson(2, 'usage_error', `--file 指向的许可文件不存在：${resolve(file)}`)
+  const confirm = CONFIRM_FLAGS.some((f) => p.bools.has(f))
+  const dryRun = !confirm || p.bools.has('--dry-run')     // A3：默认 dry-run；`--dry-run` 恒优先
+
+  // `renew` 没有 --file ⇒ **成功但空**：本期唯一可用的续期路径是"换一份新许可文件"，
+  // 在线端点属外部依赖（策划案②）。**绝不**把"没刷新成功"当成 denied（§3.5① 纪律 2）。
+  if (sub === 'renew' && !file) {
+    const v = licenseVerdict({ file: undefined })
+    const json = {
+      ok: true, empty: true, code: v.state === 'grace' ? 3 : 0,
+      reason: v.state === 'grace' ? 'license_grace' : 'no_refresh_source',
+      subcommand: 'renew',
+      licenseFile: v.path,
+      state: v.state,
+      expiresAt: v.expiresAt || null,
+      graceDays: v.graceDays,
+      graceUntil: v.graceUntil || null,
+      inGrace: v.inGrace === true,
+      device: deviceEcho(v.device),
+      refresh: {
+        requested: p.bools.has('--online'),
+        online: false,
+        attempted: false,
+        note: '本期没有自建在线续期端点（属外部依赖，见实施方案 Q3/策划案②）；'
+          + '请用 `argent license renew --file <新许可>`（离线换新文件）或让服务端重签。'
+          + '**没有刷新成功 ≠ 许可被拒**：这里维持原状态并如实回报。',
+      },
+      warnings: v.warnings || [],
+      judgedBy: 'core/lib/license-verdict.mjs',
+    }
+    const human = `ℹ️ 没有可用的续期来源（no_refresh_source）⇒ 维持原状态：state=${json.state}`
+      + `\n   ${json.refresh.note}`
+    return { json, human, stderr: '', exit: Number(json.code) }
+  }
+
+  const childArgs = ['--file', resolve(file), '--json']
+  if (p.values['--secret-file']) childArgs.push('--secret-file', resolve(p.values['--secret-file']))
+  if (p.bools.has('--rebind')) childArgs.push('--rebind')
+  // 本地重签（§3.6③ v2）：参数**逐字透传**，判定仍只发生在 install-license.mjs 里
+  if (p.bools.has('--sign-v2')) childArgs.push('--sign-v2')
+  if (p.values['--sign-version']) childArgs.push('--sign-version', p.values['--sign-version'])
+  if (p.values['--device-code']) childArgs.push('--device-code', p.values['--device-code'])
+  if (p.bools.has('--device-from-local')) childArgs.push('--device-from-local')
+  if (p.bools.has('--no-device')) childArgs.push('--no-device')
+  // 装机/续期侧的**现役比对**守卫（2026-10-04）：默认拒绝"比现役更早到期 / 能力席位被收窄"，
+  // 显式 `--allow-regression` 才放行 —— 判定在 install-license.mjs 里，本层只透传（不复制判据）。
+  if (p.bools.has('--allow-regression')) childArgs.push('--allow-regression')
+  if (dryRun) childArgs.push('--dry-run')
+  const script = join(deps.repo, 'scripts', 'install-license.mjs')
+  const child = runNode(script, childArgs, deps)
+  const out = parseJson(child.stdout)
+  if (!out) {
+    return failJson(1, 'bad_output',
+      `install-license 输出不可解析（exit=${child.status}）：${String(child.stderr || child.stdout).trim().slice(0, 300)}`)
+  }
+  // 退出码逐字透传（install-license 的口径：0 已安装/预演 ｜ 1 验签或设备被拒 ｜ 2 用法）
+  const code = child.status === 0 ? 0 : (child.status === 1 ? 1 : 2)
+  const json = {
+    ...out,
+    ok: code === 0,
+    empty: false,
+    code,
+    reason: code === 0 ? null : (out.reason || (code === 1 ? 'guard_rejected' : 'usage_error')),
+    subcommand: sub,
+    dryRun,
+    applied: code === 0 && !dryRun,
+    // 幂等（与现役**载荷+签名**逐字节一致 ⇒ 未重写、未备份）与现役比对（降级/缩权默认拒绝）
+    unchanged: out.unchanged === true,
+    incumbent: out.incumbent || null,
+    comparison: out.comparison || null,
+    renewal: out.renewal || null,
+    allowRegression: out.allowRegression === true,
+    licenseFile: out.source,
+    targetFile: out.target,
+    signatureVersion: out.signatureVersion ?? null,
+    deviceSigned: out.deviceSigned === true,
+    resign: out.resign || null,
+    device: out.device || null,
+    judgedBy: 'scripts/install-license.mjs',
+  }
+  const verb = sub === 'renew' ? '续期' : '安装'
+  const human = code === 0
+    ? `${dryRun ? '🔎 [dry-run] 会' : (json.unchanged ? '✅ 与现役一致、未改动，无需' : '✅ 已')}${verb}许可：${out.source} → ${out.target}`
+      + `\n   账号：${out.userId} ｜ 席位：${out.seats} ｜ 到期：${out.expiresAt}`
+      + `\n   签名版本：${out.signatureVersion === 2 ? 'v2（device 已进签名）' : (out.signatureVersion === 1 ? 'v1（device 未进签名）' : '判不出')}`
+      + (out.resign ? `\n   ✍️ 重签：v${out.resign.from ?? '?'} → v${out.resign.to}` : '')
+      + (out.device ? `\n   设备：${out.device.binding}（${out.device.reason}）｜ 重绑还剩 ${out.device.rebindsLeft} 次` : '')
+      + (json.unchanged ? '\n   ♻️ 幂等：本文件与现役许可逐字节一致 ⇒ **未重写、未备份**（续期重放不再产生 churn）' : '')
+      + (dryRun ? `\n   ⚠️ 本次是 dry-run：**零持久副作用**（不落许可、不备份、不写重绑计数）` : '')
+    : `❌ ${json.reason}：${out.error || ''}`
+  return { json, human, stderr: '', exit: code }
+}
+
+// ── request ────────────────────────────────────────────────────────────────
+function requestVerb(sub, args, deps) {
+  const p = parseSubArgs(sub, args)
+  if (!p.ok) return failJson(2, p.reason, p.error)
+  const dev = currentDevice(deps.deviceRead ? { ...deps.deviceRead } : {})
+  const v = licenseVerdict({ deviceRead: deps.deviceRead || null, rebindStore: deps.rebindStore || null })
+  if (!dev.ok) {
+    // ⛔ 不崩、也**不误判为拒绝**：这是"本机不支持设备绑定"（环境），按 A1 用 2
+    return failJson(2, dev.reason,
+      `${dev.error}（设备绑定是**可选**能力：读不到指纹时许可按 unbound 放行，业务不受影响）`,
+      { subcommand: 'request', device: { code: '', algo: dev.algo, issuedAt: dev.issuedAt, supported: false } })
+  }
+  const storePath = rebindStoreInfo()
+  const json = {
+    ok: true,
+    empty: false,
+    code: 0,
+    reason: null,
+    subcommand: 'request',
+    // 可复制的**设备码**（离线激活第一步；服务端签发许可时写进载荷的 `device.code`）
+    device: { code: dev.code, algo: dev.algo, issuedAt: dev.issuedAt, supported: true },
+    // 本机现状（便于支持人员一眼看到"这台机器现在是什么状态"）
+    license: {
+      state: v.state,
+      licenseFile: v.path,
+      present: v.reason !== 'missing' && v.reason !== 'unreadable',
+      binding: v.device ? v.device.binding : null,
+      bindingReason: v.device ? v.device.reason : null,
+      matchesMachine: dev.code === (v.device && v.device.code),
+    },
+    rebind: { used: Math.max(0, MAX_REBINDS - (v.device ? v.device.rebindsLeft : MAX_REBINDS)), max: MAX_REBINDS, graceDays: REBIND_GRACE_DAYS, store: storePath.path, storeMode: storePath.mode },
+    fingerprint: { algo: dev.algo, source: 'hardware-uuid（唯一来源，D3；实现见 core/lib/license-device.mjs）' },
+    warnings: ['设备码是**指纹摘要**（不含主机名/MAC/IP/安装路径）—— 只用于"这台机器 vs 许可声明"的相等比对'],
+    judgedBy: 'core/lib/license-device.mjs',
+  }
+  const human = `📇 本机设备码（复制给服务端签发许可用）：\n   ${dev.code}\n`
+    + `   算法：${dev.algo} ｜ 生成时间：${dev.issuedAt}\n`
+    + `   当前许可：${json.license.state}（${json.license.binding || '无声明'}）｜ 自助重绑已用 ${json.rebind.used}/${MAX_REBINDS} 次\n`
+    + `   ⚠️ 指纹只来自硬件 UUID（换机才变）；${deviceSignedText({ signatureVersion: v.signatureVersion, device: v.device })}`
+  return { json, human, stderr: '', exit: 0 }
+}
+
+// ── explain ────────────────────────────────────────────────────────────────
+function explainVerb(sub, args, deps) {
+  const p = parseSubArgs(sub, args)
+  if (!p.ok) return failJson(2, p.reason, p.error)
+  const st = statusVerb('status', args, deps)
+  if (st.json.reason === 'bad_output') return st
+  const j = st.json
+  const missing = []
+  const next = []
+  const dev = j.device || {}
+  if (j.licenseReason === 'missing') {
+    missing.push(`本机没有许可文件：${j.licenseFile}`)
+    next.push('把服务端签发的许可文件装上：argent license install --file <许可>（先 --dry-run 看一眼）')
+  } else if (j.licenseReason === 'no_secret') {
+    missing.push('本机没有验签密钥（license.secret / ARGENT_LICENSE_SECRET）')
+    next.push('让服务端把签名密钥一起交付，并在 install 时用 --secret-file 指定')
+  } else if (j.licenseReason === 'bad_signature') {
+    missing.push('许可验签失败（文件被改过，或不是本机这把密钥签的）')
+    next.push('别装这份文件：先确认传输是否损坏 / 是否拿错了密钥，再让服务端重签')
+  } else if (j.licenseReason === 'expired') {
+    missing.push('许可已过期且超出宽限期')
+    next.push('续期：argent license renew --file <新许可>（离线换新文件）')
+  } else if (j.licenseReason === 'malformed' || j.licenseReason === 'bad_version' || j.licenseReason === 'unreadable') {
+    missing.push(`许可文件不可用（${j.licenseReason}）`)
+    next.push('重新装一份完整许可：argent license install --file <许可>')
+  }
+  if (j.gateReason === 'cap_not_allowed') {
+    missing.push(`许可里没有这次要用的能力（要 ${(j.requestedCaps || []).join(',')}，许可只有 ${(j.capabilities || []).join(',') || '（空）'}）`)
+    next.push('让服务端在许可里加上该能力（capabilities），或改跑已授权的流程')
+  }
+  if (j.gateReason === 'vertical_not_allowed') {
+    missing.push(`许可不含业务线 ${j.requestedVertical}（许可业务线：${(j.verticals || []).join(',') || '（空=不限）'}）`)
+    next.push('让服务端把该业务线加进许可，或核对 --vertical 是否写错')
+  }
+  if (dev.binding === 'mismatch') {
+    missing.push(`设备码不匹配（本机 ${String(dev.machineCode || '').slice(0, 12)}… ≠ 许可 ${String(dev.code || '').slice(0, 12)}…）`)
+    next.push(`自助重绑：argent license install --file <许可> --rebind --apply（还剩 ${dev.rebindsLeft} 次，宽限 ${REBIND_GRACE_DAYS} 天）`)
+    next.push('次数用尽 ⇒ 需人工：让服务端按 `argent license request` 的设备码重签一份')
+  }
+  if (dev.binding === 'unsupported') {
+    missing.push('本机读不到设备指纹 ⇒ 这次**没有**做设备绑定校验（按 unbound 放行）')
+    next.push('若要启用绑定，换一台能读到硬件 UUID 的 macOS；否则无需处理（不 fail-closed）')
+  }
+  if (dev.binding === 'unbound') {
+    next.push('（可选）想启用设备绑定：argent license request 拿设备码 → 服务端签发带 device 的许可'
+      + '（本地演练：install-license --file <许可> --sign-v2 --device-code <本机设备码>）')
+  }
+  if (!missing.length) next.push('无需处理：许可有效（valid）')
+  const json = {
+    ok: j.ok,
+    empty: false,
+    code: j.code,
+    reason: j.reason,
+    subcommand: 'explain',
+    state: j.state,
+    licenseFile: j.licenseFile,
+    expiresAt: j.expiresAt,
+    graceDays: j.graceDays,
+    graceUntil: j.graceUntil,
+    inGrace: j.inGrace,
+    graceSource: j.graceSource,
+    signatureVersion: j.signatureVersion === 2 ? 2 : (j.signatureVersion === 1 ? 1 : null),
+    deviceSigned: j.device && j.device.signed === true,
+    device: j.device || null,
+    missing,
+    next,
+    whatIsMissing: missing,          // 别名（文档 §3.5① 的行文用词）
+    warnings: j.warnings || [],
+    // §3.6③ 要求 explain **把局限说给人听**（文案**按签名版本动态化**：v2 不再说"未进签名"）
+    limitation: {
+      device: deviceLimitationText(j),
+      rebind: `自助重绑上限 ${MAX_REBINDS} 次 + ${REBIND_GRACE_DAYS} 天宽限，计数落 $ARGENT_DATA_DIR`
+        + '（删掉计数文件即归零）⇒ 它是**礼貌上限**，不是可强制执行的限制。',
+    },
+    conclusion: j.conclusion || '',
+    judgedBy: j.judgedBy,
+  }
+  const human = `${j.ok ? (j.state === 'grace' ? '⚠️' : '✅') : '❌'} 许可解释：${j.state}（${j.reason || j.licenseReason || 'ok'}）`
+    + (missing.length ? `\n   缺什么：\n${missing.map((m) => `     · ${m}`).join('\n')}` : '')
+    + `\n   下一步：\n${next.map((m) => `     · ${m}`).join('\n')}`
+    + `\n   ⚠️ 局限：${json.limitation.device}`
+  return { json, human, stderr: '', exit: Number(json.code) }
+}
+
+/**
+ * verb 入口：`argent license <sub> …`。
+ * @returns {{json:object, human:string, stderr:string, exit:number}} 信封（CLI 负责打印与退出码）
+ */
+export function runLicenseVerb(argv = [], deps = {}) {
+  const d = { repo: deps.repo || resolve(process.cwd()), env: deps.env || process.env, spawn: deps.spawn, ...deps }
+  // `--json` 是 **CLI 层**的开关（决定打印形状），不是子命令名 ⇒ 判定子命令时先滤掉它
+  const [sub, ...rest] = argv.filter((a) => a !== '--json')
+  // 裸 `argent license` = `status`（旧实现恒 ok:true/exit 0 正是 §2.2④ 要修的那件事）
+  if (!sub) return statusVerb('status', [], d)
+  if (sub === 'status') return statusVerb('status', rest, d)
+  if (sub === 'verify') return verifyVerb('verify', rest, d)
+  if (sub === 'install') return installLike('install', rest, d)
+  if (sub === 'request') return requestVerb('request', rest, d)
+  if (sub === 'renew') return installLike('renew', rest, d)
+  if (sub === 'explain') return explainVerb('explain', rest, d)
+  // `activate` 是**异步**的（真兑换要发 HTTP；CLI 顶层已 `await`，MCP 只走 status 的同步路径）
+  // `asJson` 往上带一层：`--json` 是本层滤掉的开关，而"标注必须被看见"这件事要靠它决定走 stdout 还是 stderr。
+  if (sub === 'activate') return activateVerb(rest, { ...d, asJson: argv.includes('--json') })
+  // `ops`（O2 只读运营巡检）：同样是异步的（服务端模式要发 GET）—— CLI 顶层已 `await`。
+  // ⛔ 读类：没有 `--apply`，`applied` 恒 false；判据/口径在 `core/lib/license-ops.mjs`（本层只分派）。
+  if (sub === 'ops') return runOpsVerb(rest, { ...d, asJson: argv.includes('--json') })
+  if (sub === '--help' || sub === '-h') {
+    // 组帮助不是"用法错误"：列出子命令后 exit 0（与 `flow --help` 同形）
+    const contracts = JSON.parse(readFileSync(join(d.repo, 'core', 'contracts', 'argent.contracts.json'), 'utf8'))
+    const subs = Object.keys(contracts.verbs.license.subcommands || {})
+    return {
+      json: { ok: true, empty: false, code: 0, reason: null, subcommand: 'license', subcommands: subs, usage: ACTIVATE_USAGE },
+      human: `argent license <子命令> —— ${contracts.verbs.license.desc}\n`
+        + Object.entries(contracts.verbs.license.subcommands || {}).map(([s, t]) => `  ${s.padEnd(8)} ${t}`).join('\n')
+        + `\n\n${ACTIVATE_USAGE}`
+        + '\n\n只读运营巡检（O2：在途码/失败码/事件时间线/席位账目/异常清单，替代 `mongosh`）用法见：'
+        + '`argent license ops --help`（⛔ 只读：不写库/不落审计，HTTP 只发 GET）',
+      stderr: '', exit: 0,
+    }
+  }
+  return failJson(2, 'unknown_subcommand',
+    `未知子命令：${sub}（可用：${LICENSE_SUBCOMMANDS.join('、')}）`)
+}
+
+/**
+ * `device` 到底进没进签名 —— **给人和机器看的那一句话**（唯一文案落点，四个 verb + check-license 同口径）。
+ * 判据只有一处：`signatureVersion`（1｜2｜null）。⛔ 不在这里重算版本分派。
+ * @param {{signatureVersion?:number|null, device?:object|null}} r
+ */
+export function deviceSignedText(r = {}) {
+  const dev = r.device || {}
+  if (r.signatureVersion === 2) {
+    return dev.present
+      ? '签名版本 **v2**：`device` **已进签名**（载荷 10 项，含 device{code,algo,issuedAt}）⇒ 改它/摘它/降 v 重拼都会验签失败；'
+        + '⚠️ 签名仍是 HMAC-SHA256（对称密钥，验签方持同一把密钥）⇒ **不防"持有 license.secret 的人重签"**，真防伪需非对称签名'
+      : '签名版本 **v2**：本许可**未声明**设备（unbound）—— **缺位也被签名覆盖**（事后加 `device` 会验签失败）⇒ 不做比对、放行'
+  }
+  if (r.signatureVersion === 1) {
+    return '`device` **未进签名**（v1 只签 v,userId,capabilities,verticals,seats,issuedAt,expiresAt,graceDays,instanceHint 这 9 项）'
+      + '⇒ 它是"服务端声明 + 客户端比对"，能防"误装到别的机器"，**不防伪造**；'
+      + '要让它进签名需 v2（`install-license --sign-v2` 本地重签，或服务端升 v2 后签发，见 §6.2 A-⑨）。'
+  }
+  return '判不出签名版本（许可缺失 / 无密钥 / 文件不可解析）⇒ **本次没有**任何"device 已进签名"的保证'
+}
+
+/** `explain` 的 `limitation.device`：v2 的局限与 v1 **不同**（一个"已覆盖但仍是 HMAC"，一个"根本没覆盖"）。 */
+function deviceLimitationText(j = {}) {
+  if (j.signatureVersion === 2) {
+    const base = '本许可的签名是 **v2**（载荷 10 项，含 `device{code,algo,issuedAt}`）'
+      + '⇒ `device` 的**内容或它的缺位**都被签名覆盖：改它/摘它/把 `v` 降回 1 重拼载荷，都会 **bad_signature**。'
+    return base + (j.device && j.device.present
+      ? '⚠️ 但这**不等于防伪**：签名算法是 HMAC-SHA256（对称密钥），验签方**必须**持有同一把 `license.secret`'
+        + '⇒ 拿到该文件的人能**自签一份**看起来完全合法的许可。v2 堵的是"改字段不改签名"这条最低成本绕过；'
+        + '要真防伪造得换非对称签名（Ed25519，客户端只拿公钥）—— v3 候选。'
+      : '⚠️ 本许可未声明设备（unbound）：放行，但**没有**设备绑定这一层保护。')
+  }
+  if (j.signatureVersion === 1) {
+    return '`device` **未进签名**（v1 只签 v,userId,capabilities,verticals,seats,issuedAt,expiresAt,graceDays,instanceHint 这 9 项）'
+      + '⇒ 它是"服务端声明 + 客户端比对"，能防"误装到别的机器"，**不防伪造**；'
+      + '要让它进签名需服务端升 v2（跨仓库，见 §6.2 A-⑨）—— 本地可先 `install-license --file <许可> --sign-v2` 重签。'
+  }
+  return '本机这份许可**判不出签名版本**（缺失 / 无密钥 / 不合法）⇒ 没有任何"device 已进签名"的保证；'
+    + '在拿到 v2 许可之前，本机现状仍是 v1 口径：`device` **未进签名**（v1 只签 9 项），'
+    + '它是"服务端声明 + 客户端比对"，**不防伪造**。'
+}
+
+/** 供门禁/宿主读的静态信息（**不复制判据**，只是清单）。 */
+export const LICENSE_META = {
+  subcommands: LICENSE_SUBCOMMANDS,
+  confirmFlags: CONFIRM_FLAGS,
+  maxRebinds: MAX_REBINDS,
+  rebindGraceDays: REBIND_GRACE_DAYS,
+}
+
+/** 给测试/诊断用：直接读一份许可的判定结果（不 spawn 任何子进程）。 */
+export function licenseStatusInProcess(opts = {}) {
+  const v = licenseVerdict(opts)
+  return {
+    state: v.state, exit: v.exit, ok: v.ok, reason: v.reason,
+    signatureVersion: v.signatureVersion === 2 ? 2 : (v.signatureVersion === 1 ? 1 : null),
+    deviceSigned: v.deviceSigned === true,
+    device: deviceEcho(v.device), readStore: readRebindStore({ env: opts.env || process.env }),
+    rawJson: (() => { try { return JSON.parse(readFileSync(v.path, 'utf8')) } catch { return null } })(),
+  }
+}