@whyshu/argent-engine 0.0.0-stage → 0.6.1

package/engine/core/lib/license-activate.mjs

@@ -0,0 +1,813 @@
+/**
+ * 一次性激活码 —— **客户机那一半**（方案《许可自助签发与续期》§8-③ 路径 (a) 的落地；2026-10-04）
+ *
+ * ## 为什么需要它（一句话）
+ * 客户机是 **BYO + 不登录**（没有账号 JWT）⇒ **它自己调不了签发端点**。一次性激活码让"持有这台机器的人"
+ * 用**网页/手机端登录后的身份**换到一份**绑定这台机器设备码**的许可 ⇒ 把"每加一个客户/每次续期都要我们人工"
+ * 降为"客户自助 + 我们只做账务"。协议、状态机与错误码表见方案 §9（服务端契约）；本文件 = **客户端的全部实现**。
+ *
+ * ## 纪律（三条，都可判）
+ * | # | 纪律 | 落点 |
+ * |---|---|---|
+ * | ① | **判定点不在本文件**：码与权益归**服务端**判；产物能不能落盘归 `scripts/install-license.mjs` 判（验签/设备比对/0600/备份/读回/幂等/拒绝倒退） | 本文件只做"翻译 + 前置断言 + 转交"，**不自己写许可文件** |
+ * | ② | **明文码零泄漏**：对外只出现 `codePrefix`（前 8 位，供人工核对）；stdout/stderr/审计 JSONL 里**搜不到**明文码 | 回显由白名单字段构造（响应体**不透传**）+ 服务端给的人话文本先过 `redactActivationCode()` 再落地 + 审计只落 `codePrefix` |
+ * | ③ | **默认 dry-run（A3）**：不带 `--apply` ⇒ **零网络请求 + 零落盘**（连审计都不写）；真兑换要显式确权 | `dryRun` 分支在任何 `fetch`/临时文件/子进程**之前**返回 |
+ *
+ * ## A1 / A2
+ *   · A1：`0` 兑换并落盘成功（含"与现役逐字节一致 ⇒ 未改动"）｜`2` 用法/环境（码形态非法、**未配置端点**、
+ *     `--server` 非 TLS 且非回环、设备码形状非法、读不到本机设备码）｜`1` 兑换被拒（服务端错误码映射、
+ *     网络不可达/超时、产物验签不过/设备不匹配/倒退被拒 —— 后三者由 `install-license.mjs` 判）。
+ *   · A2：`ok/empty/code/reason` 恒在；`$? == json.code`；`--json` 时 stdout **只有一份 JSON**；
+ *     回显**实际生效值**（`server`/`endpoint`/`codePrefix`/`request.device`/`request.target`）——**绝不含明文码**。
+ *
+ * ## 与设备绑定/v2 的关系（§3.6 是唯一权威，本文件只引用）
+ *   · 上传的是 **64hex 设备码**（指纹摘要；**唯一实现在 `license-device.mjs`** —— 本文件只搬运，不碰指纹来源）；
+ *     **绝不**上传主机名/MAC/IP/安装路径（D3）。
+ *   · 兑换产物必须是 **v2（`device` 进签名）**；验收 = `signatureVersion:2 ∧ deviceSigned:true ∧ binding:match`
+ *     （这三个值**全部**来自 `install-license.mjs` 的验签/比对结论，本文件不重算）。
+ *   · 读不到本机设备码 ⇒ **不静默降级成 unbound**：显式 `--no-device` 才走 unbound（与 `install-license` 同一条纪律）。
+ *
+ * ## ⛔ 不做
+ *   · **不**把账号 JWT 落到客户机（本文件里没有任何令牌概念：兑换只凭一次性码）；
+ *   · **不**在 dry-run 里"先探一下"（那会有网络副作用、还可能占用一次性码）—— dry-run 只打印将要做什么；
+ *   · **不**自己实现验签/落盘/备份（那样就有第二份判据，日后必然漂移）。
+ */
+import { appendFileSync, chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { createHash, randomUUID } from 'node:crypto'
+import { tmpdir } from 'node:os'
+import { join, resolve } from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { resolveDataDir } from './argent-datadir.mjs'
+import { signaturePayloadOf } from './license-file.mjs'
+import { currentDevice } from './license-device.mjs'
+
+// ── 码的形态（**服务端生成、客户端只归一化与校验**；契约见方案 §9.1）──────────────
+/** Crockford base32：去掉 I/L/O/U（易混），归一化时 I,L→1、O→0。 */
+export const ACTIVATION_CODE_ALPHABET = '0123456789ABCDEFGHJKMNPQRSTVWXYZ'
+/** 有效字符数（20 × 5 bit = **100 bit** 熵）。 */
+export const ACTIVATION_CODE_LENGTH = 20
+/** 展示分组长度（`XXXXX-XXXXX-XXXXX-XXXXX`，仅展示/人抄；判定一律按归一化后的 20 位）。 */
+export const ACTIVATION_CODE_GROUP = 5
+/** 归一化后的形态（判据只有这一条）。 */
+export const ACTIVATION_CODE_RE = /^[0-9A-HJKMNP-TV-Z]{20}$/
+/** 人工核对用的短前缀长度（**唯一允许出现在输出/审计里的码片段**）。 */
+export const ACTIVATION_CODE_PREFIX_LENGTH = 8
+/** 建议 TTL（服务端强制；这里只用于回显/文案 —— **客户端不判期**，码的有效性归服务端判）。 */
+export const ACTIVATION_CODE_TTL_MINUTES = 15
+/** 同码同机的**幂等复用窗口**（网络超时后重试 ⇒ 服务端返回同一份许可，而不是"码已被用掉"）。 */
+export const ACTIVATION_REUSE_WINDOW_HOURS = 24
+/** 状态机（与服务端 `ActivationCode.state` 逐字一致；`redeeming` 只在 CAS 的中间态出现）。 */
+export const ACTIVATION_CODE_STATES = ['issued', 'redeeming', 'redeemed', 'expired', 'revoked']
+/** 码的意图（续期/重绑**复用同一端点**，见方案 §9.5）。 */
+export const ACTIVATION_INTENTS = ['activate', 'renew', 'rebind']
+
+// ── 端点（`--server` 只给 **base URL**；路径相对它解析 ⇒ 支持反代下的路径前缀）──
+export const REDEEM_PATH = 'api/argent/license/redeem'
+export const CODE_STATUS_PATH = 'api/argent/license/activation-code/'
+export const DEFAULT_TIMEOUT_MS = 15000
+/** 客户端审计（`argent audit --source license-activation` 可读）。 */
+export const ACTIVATION_AUDIT = 'license-activation/audit.jsonl'
+
+/**
+ * 归一化一次性码：去空白/分隔符 → 大写 → Crockford 别名（I,L→1；O→0）→ 形状校验。
+ * @returns {{ok:boolean, code:string, error:string}}
+ */
+export function normalizeActivationCode(raw) {
+  const s = String(raw == null ? '' : raw).trim()
+  if (!s) return { ok: false, code: '', error: '激活码是空的' }
+  const compact = s.replace(/[\s\-_·]/g, '').toUpperCase()
+  const mapped = compact.replace(/[IL]/g, '1').replace(/O/g, '0')
+  if (mapped.length !== ACTIVATION_CODE_LENGTH) {
+    return { ok: false, code: '', error: `激活码应为 ${ACTIVATION_CODE_LENGTH} 位有效字符（不区分大小写，连字符可有可无），实得 ${mapped.length} 位` }
+  }
+  if (!ACTIVATION_CODE_RE.test(mapped)) {
+    return { ok: false, code: '', error: `激活码含非法字符（字符集 = Crockford base32：${ACTIVATION_CODE_ALPHABET}；没有 I/L/O/U）` }
+  }
+  return { ok: true, code: mapped, error: '' }
+}
+
+/** 人工核对的短前缀（**唯一允许出现在输出/审计里的码片段**）。 */
+export function activationCodePrefix(code) {
+  return String(code || '').slice(0, ACTIVATION_CODE_PREFIX_LENGTH)
+}
+
+/** 展示形态（`XXXXX-XXXXX-XXXXX-XXXXX`；只用于"请核对这串"的人话，**不用于判定**）。 */
+export function displayActivationCode(code) {
+  const s = String(code || '')
+  const g = ACTIVATION_CODE_GROUP
+  return s.length === ACTIVATION_CODE_LENGTH ? s.match(new RegExp(`.{1,${g}}`, 'g')).join('-') : s
+}
+
+/** 是否回环地址（唯一允许明文 `http://` 的场合：本机 http 桩/内网自测）。 */
+export function isLoopbackHost(hostname) {
+  const h = String(hostname || '').toLowerCase().replace(/^\[|\]$/g, '')
+  return h === 'localhost' || h === '::1' || h === '0:0:0:0:0:0:0:1' || /^127\./.test(h)
+}
+
+/** base URL → 端点（保留路径前缀：`https://h/p` ⇒ `https://h/p/api/argent/license/redeem`）。 */
+export function endpointOf(baseUrl, relPath = REDEEM_PATH) {
+  const b = String(baseUrl || '')
+  return new URL(relPath, b.endsWith('/') ? b : `${b}/`).toString()
+}
+
+/**
+ * 解析生效的端点（**A2：回显实际生效值与它的来源**）。
+ * 优先级：`--server` > `ARGENT_LICENSE_SERVER` > `WHYSHU_API_URL`（与 `scripts/lease.py` 等的既有约定一致）。
+ * ⛔ **不给任何默认值**：没配置 ⇒ `activation_server_unconfigured`（exit 2）——**绝不**静默指向某个线上地址。
+ * ⛔ 非回环地址**必须 https**（明文 http 直接拒，exit 2）。
+ * @returns {{ok:boolean, reason:string, error:string, baseUrl:string, source:string, endpoint:string, tls:boolean, loopback:boolean}}
+ */
+export function resolveActivationServer({ flag = null, env = {} } = {}) {
+  const candidates = [
+    { source: 'flag', label: '--server', value: flag },
+    { source: 'env:ARGENT_LICENSE_SERVER', label: 'ARGENT_LICENSE_SERVER', value: env.ARGENT_LICENSE_SERVER },
+    { source: 'env:WHYSHU_API_URL', label: 'WHYSHU_API_URL', value: env.WHYSHU_API_URL },
+  ]
+  const miss = { ok: false, baseUrl: '', source: '', endpoint: '', tls: false, loopback: false }
+  const hit = candidates.find((c) => String(c.value == null ? '' : c.value).trim())
+  if (!hit) {
+    return {
+      ...miss, reason: 'activation_server_unconfigured',
+      error: '没有配置签发服务端点：请用 `--server https://whyshu.com`（**只给 base URL** —— 端点路径由客户端拼，'
+        + '⛔ 别写成 `https://whyshu.com/api/argent`：那会拼成 `…/api/argent/api/argent/license/redeem` ⇒ 404），或设置环境变量 '
+        + '`ARGENT_LICENSE_SERVER`（也可沿用 `WHYSHU_API_URL`）——⛔ 不提供任何默认地址'
+        + '（避免"以为在跟本机演练、其实打到了线上"）',
+    }
+  }
+  let u = null
+  try { u = new URL(String(hit.value).trim()) } catch {
+    return { ...miss, reason: 'usage_error', source: hit.source, error: `${hit.label} 不是合法 URL：${JSON.stringify(String(hit.value).trim())}` }
+  }
+  if (!['http:', 'https:'].includes(u.protocol)) {
+    return { ...miss, reason: 'usage_error', source: hit.source, error: `${hit.label} 只认 http/https，实得 ${u.protocol}` }
+  }
+  const loopback = isLoopbackHost(u.hostname)
+  if (u.protocol === 'http:' && !loopback) {
+    return {
+      ...miss, reason: 'usage_error', source: hit.source,
+      error: `拒绝明文传输：${hit.label}=${u.origin} 是 **http** 且不是回环地址 ⇒ 一次性码会以明文过网。`
+        + '请用 https（只有 127.0.0.1/localhost/::1 允许明文 http，供本机演练）',
+    }
+  }
+  const baseUrl = u.toString().replace(/\/+$/, '')
+  return {
+    ok: true, reason: 'ok', error: '', baseUrl, source: hit.source,
+    endpoint: endpointOf(baseUrl), tls: u.protocol === 'https:', loopback,
+  }
+}
+
+/**
+ * **服务端错误码 → 客户端 reason/A1 退出码**（唯一映射表；方案 §9.3 的错误码表与它逐条一致）。
+ * 这些短码**不是客户端新发明的判据**，而是服务端词表在客户端的**同名映射**（服务端的 `no_entitlement`
+ * 就是客户端的 `no_entitlement`）；客户端自己产生的码一律 `activation_` 前缀 ⇒ 一眼分得开。
+ */
+export const SERVER_ERROR_MAP = {
+  // ① 码的问题（客户：重新生成一个码）
+  code_unknown: { exit: 1, category: 'code', hint: '码不存在（抄错，或不是这台服务器的码）⇒ 在网页/手机端**重新生成**一个' },
+  code_expired: { exit: 1, category: 'code', hint: `码已过期（TTL ${ACTIVATION_CODE_TTL_MINUTES} 分钟）⇒ 重新生成一个，生成后**尽快**兑换` },
+  code_already_redeemed: { exit: 1, category: 'code', hint: '码已被用掉（且超出同机幂等复用窗口）⇒ 重新生成一个；若这台机器其实收到过许可，先 `argent license status`' },
+  code_device_locked: { exit: 1, category: 'code', hint: '这个码已经绑定到**另一台机器**（码被转发/双花）⇒ 在那台机器上兑换，或重新生成一个' },
+  code_revoked: { exit: 1, category: 'code', hint: '码被运营撤销 ⇒ 联系运营确认' },
+  code_locked: { exit: 1, category: 'code', hint: '该码失败尝试超限已锁定 ⇒ 重新生成一个（并核对该机器的设备码）' },
+  // ② 账号/权益/席位（客户：找商务/运营）
+  no_entitlement: { exit: 1, category: 'entitlement', hint: '该账号没有任何有效许可 ⇒ 先购买/开通，再生成码' },
+  no_license: { exit: 1, category: 'entitlement', hint: '该账号没有许可记录 ⇒ 开通' },
+  license_revoked: { exit: 1, category: 'entitlement', hint: '该账号的许可已被吊销 ⇒ 联系运营' },
+  capability_not_owned: { exit: 1, category: 'entitlement', hint: '请求的能力超出账号权益（签发**不扩权**）⇒ 以账号权益为准' },
+  seat_limit_reached: { exit: 1, category: 'entitlement', hint: '席位已满（新设备会超 `seats`）⇒ 解绑旧设备或加席位' },
+  device_bound_elsewhere: { exit: 1, category: 'entitlement', hint: '同账号同席位已被另一台设备占用 ⇒ 走重绑或人工解绑' },
+  rebind_exhausted: { exit: 1, category: 'entitlement', hint: '换绑次数已用尽（服务端权威计数 3 次）⇒ 人工重绑：运营解绑旧设备码后重签' },
+  rebind_window_expired: { exit: 1, category: 'entitlement', hint: '首次发现不匹配已超过 7 天宽限 ⇒ 人工重绑' },
+  payment_required: { exit: 1, category: 'entitlement', hint: '未核账不放行（姿态 A）⇒ 走人工核账' },
+  // ③ 请求/服务端环境（服务端 §2.2-D 的既有码）
+  bad_request: { exit: 1, category: 'client', hint: '服务端认为请求不合法（字段缺失/类型错）⇒ 客户端与服务端契约版本不一致：先核对两边版本，别反复重试' },
+  signing_secret_missing: { exit: 1, category: 'server', hint: '服务端未配置 `LICENSE_SIGNING_SECRET`（⛔ 不回退默认串）⇒ 运营处置后重试（**同一个码**重试安全）' },
+  // ④ 限流 / 设备
+  rate_limited: { exit: 1, category: 'throttle', hint: '触发限流 ⇒ 退避后重试（**同一个码**重试是安全的：同码同机走幂等复用）' },
+  bad_device: { exit: 1, category: 'device', hint: '服务端拒绝了设备码（形状/算法不认识）⇒ 重跑 `argent license request`，别手抄' },
+  // ⑤ 灰度开关（方案 §9.8）：灰度未开或已回滚 ⇒ 明确说"用人工入口"，别让客户反复重试
+  activation_disabled: { exit: 1, category: 'server', hint: '服务端**灰度未开启/已回滚**（`ACTIVATION_ENABLED=0`）⇒ 改走人工签发入口：让运营按 `argent license request` 的设备码签一份，再 `argent license install --file <许可>`' },
+}
+
+/** 客户端自己产生的码（`activation_` 前缀 = 与"服务端词表"一眼可分）。 */
+export const CLIENT_ERROR_MAP = {
+  activation_server_unconfigured: { exit: 2, category: 'config', hint: '配置端点：`--server https://whyshu.com`（**只给 base URL**：别写成 `…/api/argent`，那会多一层前缀 ⇒ 404）或 `ARGENT_LICENSE_SERVER`（也可用 `WHYSHU_API_URL`）' },
+  activation_unauthorized: { exit: 1, category: 'server', hint: '兑换端点返回 401：该端点**不应要求账号令牌**（客户机不登录）⇒ 服务端路由/部署配错了' },
+  activation_server_error: { exit: 1, category: 'server', hint: '服务端 5xx（含 `signing_secret_missing`）⇒ 运营处置；稍后可用**同一个码**重试（幂等复用）' },
+  activation_bad_response: { exit: 1, category: 'server', hint: '服务端响应不可解析或缺字段 ⇒ **不要**重试到成功：先核对服务端版本/契约' },
+  activation_server_unreachable: { exit: 1, category: 'network', hint: '连不上端点（DNS/连接失败）⇒ 查网络与 `--server`；同一个码重试是安全的' },
+  activation_timeout: { exit: 1, category: 'network', hint: '请求超时。**码可能已被消费**：用**同一个码**重试会命中"同码同机幂等复用"；仍不行 ⇒ 运营用 `GET /license/activation-code/:prefix` 查状态' },
+  activation_denied: { exit: 1, category: 'server', hint: '服务端拒绝但 reason 不在本客户端词表里 ⇒ 看 `serverReason` 字段与服务端日志（客户端不把未知串当判据）' },
+}
+
+/** 全部激活相关短码（契约登记用；两边合并）。 */
+export const ACTIVATION_REASONS = { ...SERVER_ERROR_MAP, ...CLIENT_ERROR_MAP }
+
+/**
+ * 服务端应答 → `{reason, exit, hint}`（**未知 reason 一律收敛成 `activation_denied`**，
+ * 绝不把服务端返回的任意字符串当判据 —— A2：`reason` 只能是词表里的短码）。
+ */
+export function mapServerOutcome({ httpStatus = 0, reason = '' } = {}) {
+  const raw = String(reason || '').trim()
+  // `serverReason` 会被回显 ⇒ 只可能是"短码形态"（≤64 且 [a-z0-9_]）；否则一律当"不认识"（不给任意串留回显位）
+  const r = /^[a-z][a-z0-9_]{0,63}$/.test(raw) ? raw : ''
+  if (SERVER_ERROR_MAP[r]) return { reason: r, exit: SERVER_ERROR_MAP[r].exit, hint: SERVER_ERROR_MAP[r].hint, serverReason: r, known: true }
+  const st = Number(httpStatus) || 0
+  if (st === 401) return { ...CLIENT_ERROR_MAP.activation_unauthorized, reason: 'activation_unauthorized', serverReason: r || null, known: false }
+  if (st >= 500) return { ...CLIENT_ERROR_MAP.activation_server_error, reason: 'activation_server_error', serverReason: r || null, known: false }
+  if (st === 429) return { ...SERVER_ERROR_MAP.rate_limited, reason: 'rate_limited', serverReason: r || null, known: true }
+  if (st === 404) {
+    // **与"码不存在"区分开**：服务端真正的 `code_unknown` 也走 404，但它**带 reason** ⇒ 上面就命中了。
+    // 走到这里 = 404 且响应体不是我们的错误信封（Fastify 的 `Route … not found` 就是这一形态）
+    // ⇒ 十有八九是 `--server` 把**端点路径**当成了 base（多一层前缀）。2026-10-04 客户机试点踩到过。
+    return {
+      ...CLIENT_ERROR_MAP.activation_denied, reason: 'activation_denied', serverReason: r || null, known: false,
+      hint: '端点返回 404 且响应体不是本服务的错误信封（多是 Fastify 的 `Route … not found`）⇒ 先怀疑 `--server`：'
+        + '它只给 **base URL**（正确值 `https://whyshu.com`）；写成 `https://whyshu.com/api/argent` 会拼成'
+        + ' `https://whyshu.com/api/argent/api/argent/license/redeem` ⇒ 404',
+    }
+  }
+  return { ...CLIENT_ERROR_MAP.activation_denied, reason: 'activation_denied', serverReason: r || null, known: false }
+}
+
+/** 响应里 `licenseFileSha256` 的口径 = `sha256(canonicalJson(载荷))`（与方案 §6.2/§9.3 的字节锚点同源）。 */
+export function payloadSha256(licenseFile) {
+  const p = signaturePayloadOf(licenseFile)
+  if (!p) return null
+  return createHash('sha256').update(p.payload).digest('hex')
+}
+
+/**
+ * **把明文码从任意文本里抹掉**（客户端最后一道"零泄漏"防线）。
+ *
+ * 为什么需要它：客户端会**转述**服务端的人话字段（`error`/`hint`）—— 若服务端（或因配置错误/被改）
+ * 把明文码塞进那些字段，客户端就会把它打到客户终端与日志里。这里按"码的任意 ≥12 位连续片段"
+ * 替换（前缀只有 8 位 ⇒ 不会误伤 `codePrefix`）⇒ **无论服务端怎么写，明文码都出不去**。
+ */
+export function redactActivationCode(text, code) {
+  const out0 = String(text == null ? '' : text)
+  const full = String(code || '')
+  if (full.length < 12) return out0
+  let out = out0
+  // **从最长匹配到最短**（20 → 12）：只按 12 位窗口替换会把"尾巴"（≤8 位）留在文本里 ——
+  // 虽然仍满足"没有 ≥12 位连续片段"的不变量，但没必要留残渣。从长到短保证整段被吃掉。
+  for (let len = full.length; len >= 12; len--) {
+    for (let i = 0; i + len <= full.length; i++) out = out.split(full.slice(i, i + len)).join('‹码已隐去›')
+  }
+  return out
+}
+
+/** 服务端回显的前缀：**只在不扩大泄漏面时**才采信（必须是我们自己前缀的子串，且 ≤8 位）。 */
+export function acceptCodePrefix(value, own) {
+  const v = String(value == null ? '' : value).trim()
+  return v && v.length <= ACTIVATION_CODE_PREFIX_LENGTH && String(own).startsWith(v) ? v : own
+}
+
+/** 服务端回显的摘要：只认 64hex（否则丢掉 —— 免得把服务端塞进来的任意串当"摘要"落进审计）。 */
+function acceptSha(value) {
+  const v = String(value == null ? '' : value).trim().toLowerCase()
+  return /^[0-9a-f]{64}$/.test(v) ? v : null
+}
+
+/** 审计路径（`argent audit --source license-activation`）。 */
+export function activationAuditPath(dataDir) {
+  return join(String(dataDir), ACTIVATION_AUDIT)
+}
+
+/** 追一行审计（**只有 apply 才调用**；dry-run 一行都不落 —— A3 零副作用）。 */
+export function appendActivationAudit(dataDir, record) {
+  const dir = join(String(dataDir), 'license-activation')
+  mkdirSync(dir, { recursive: true, mode: 0o700 })
+  const p = join(dir, 'audit.jsonl')
+  appendFileSync(p, `${JSON.stringify(record)}\n`, { mode: 0o600 })
+  try { chmodSync(p, 0o600) } catch { /* 权限拿不到：审计仍已落盘 */ }
+  return p
+}
+
+/** 失败信封（A2）。 */
+const failJson = (code, reason, error, extra = {}) => ({
+  json: { ok: false, empty: false, code, reason, error, subcommand: 'activate', ...extra },
+  human: `❌ ${reason}：${error}`,
+  stderr: '',
+  exit: code,
+})
+
+export const ACTIVATE_VALUE_FLAGS = ['--code', '--code-file', '--server', '--device-code', '--secret-file', '--instance', '--intent']
+export const ACTIVATE_BOOL_FLAGS = ['--no-device', '--apply', '--yes', '--confirm', '--dry-run', '--allow-regression', '--help', '-h']
+
+export const ACTIVATE_USAGE = [
+  '用法：argent license activate --code <一次性激活码> [--server https://whyshu.com] [--apply] [--allow-regression] [--json]',
+  '',
+  '端点（`--server` 只给 **base URL** —— 路径由客户端拼，见 core/lib/license-activate.mjs#REDEEM_PATH）：',
+  '  · 正确值：`--server https://whyshu.com` ⇒ 实际请求 `https://whyshu.com/api/argent/license/redeem`；',
+  '  · ⛔ 别写成 `--server https://whyshu.com/api/argent`：base URL 的**路径前缀是保留的**（反代下有用）⇒',
+  '    会拼成 `https://whyshu.com/api/argent/api/argent/license/redeem` 而 **404**（多写一段 = 多一层前缀）；',
+  '  · 也可用 `ARGENT_LICENSE_SERVER`（兜底 `WHYSHU_API_URL`）；⛔ 没有默认地址（不静默指向线上）。',
+  '',
+  '两步话术（先取设备码，再兑换）：',
+  '  ① argent license request --json                 # 打印本机设备码（64hex），交给网页/手机端',
+  '  ② 在网页/手机端**登录后**生成一次性激活码（TTL 15 分钟、一次性、绑定这台机器的设备码）',
+  '  ③ argent license activate --code <码>            # 先 dry-run：只打印"将请求哪个端点、将写哪个文件"',
+  '  ④ argent license activate --code <码> --apply     # 确认无误再真兑换（服务端签发 → 落盘）',
+  '',
+  '安全：',
+  '  · 建议**先 dry-run 再 --apply**：dry-run 不发任何网络请求、不写任何文件，连审计都不落；',
+  '  · 明文码**不会**出现在任何输出里（只回显前 8 位 codePrefix 供人工核对）；共享机器上建议用 --code-file；',
+  '  · 端点必须 https（只有 127.0.0.1/localhost/::1 允许明文 http，供本机演练）；',
+  '  · 落盘复用 `scripts/install-license.mjs` 的既有判据：验签 + 设备比对 + 0600 + 覆盖前备份 + 写后读回。',
+  '',
+  '倒退放行（A4 守卫的逃生阀 `--allow-regression`）：',
+  '  · 兑换回来的许可若比现役**更早到期**（stale）或能力/业务线/席位被**收窄**（narrowed）⇒ 默认拒绝',
+  '    （`regression_refused`，exit 1，**不落盘**；判定在 scripts/install-license.mjs，本层只透传）；',
+  '  · 确实要装（纠错/吊销/换绑）⇒ 显式加 `--allow-regression`：**放行这一次**，并在回显/告警里如实标注；',
+  '  · ⚠️ 它只是"签字确认"，不是"修复"：⛔ 不要把它当成续期流程的常规参数 —— 正确做法是',
+  '    签发前先跑 `argent license status --json` 抄下现役 `expiresAt`/`capabilities`，确保新许可 **≥** 现役。',
+].join('\n')
+
+/**
+ * `argent license activate` 的 verb 入口（**异步**：真兑换要发 HTTP；CLI 顶层已 `await`）。
+ * @param {string[]} argv 子命令参数（**不含** `--json`：那是 CLI 层开关，由调用方经 `deps.asJson` 告知）
+ * @param {object} deps   `{repo, env, dataDir, spawn, fetch, deviceRead, requestId, asJson}`
+ */
+export async function activateVerb(argv = [], deps = {}) {
+  const env = deps.env || process.env
+  const repo = deps.repo || resolve(process.cwd())
+  const spawn = deps.spawn || spawnSync
+  /** `--json`：stdout 只留合同字段（human 被藏起来）⇒ 少数**必须被看见**的标注要走 stderr。
+   *  由调用方（`runLicenseVerb`）告知，因为 `--json` 在那一层就被滤掉了。 */
+  const asJson = deps.asJson === true
+
+  // ── 参数（未知参数一律拒绝 ⇒ 2：不静默吃掉别人的参数）──────────────────────
+  const values = {}
+  const bools = new Set()
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--json') continue
+    if (ACTIVATE_BOOL_FLAGS.includes(a)) { bools.add(a); continue }
+    if (ACTIVATE_VALUE_FLAGS.includes(a)) {
+      const v = argv[i + 1]
+      if (v === undefined || String(v).startsWith('--')) {
+        return failJson(2, 'usage_error', `参数 ${a} 缺值（用法：argent license activate --code <码> [--apply]）`)
+      }
+      values[a] = v; i++; continue
+    }
+    return failJson(2, 'usage_error', `未知参数：${a}（用法见 \`argent license activate --help\`）`)
+  }
+  if (bools.has('--help') || bools.has('-h')) {
+    return { json: { ok: true, empty: false, code: 0, reason: null, subcommand: 'activate', usage: ACTIVATE_USAGE }, human: ACTIVATE_USAGE, stderr: '', exit: 0 }
+  }
+
+  // ① 明文码：来源二选一（`--code` 便于手抄；`--code-file` 不进 shell 历史/进程列表）
+  if (values['--code'] !== undefined && values['--code-file'] !== undefined) {
+    return failJson(2, 'usage_error', '`--code` 与 `--code-file` 只能给一个（避免"到底用了哪个"说不清）')
+  }
+  const rawCode = values['--code'] !== undefined ? String(values['--code'])
+    : (values['--code-file'] !== undefined ? readCodeFile(values['--code-file']) : null)
+  if (rawCode === null) {
+    return failJson(2, 'usage_error', '缺必填参数：`--code <一次性激活码>`（或 `--code-file <文件>`）——用法见 `argent license activate --help`')
+  }
+  if (rawCode && typeof rawCode === 'object' && rawCode.__error) return failJson(2, 'usage_error', rawCode.__error)
+  const norm = normalizeActivationCode(rawCode)
+  if (!norm.ok) {
+    // ⛔ 错误消息里**不回显用户输入**（它可能是"抄错一位的真码"）；只报位数/字符集
+    return failJson(2, 'usage_error', `${norm.error}（先在网页/手机端复制；共享机器上建议 --code-file；⛔ 不要把码贴进工单/聊天）`)
+  }
+  const code = norm.code
+  const codePrefix = activationCodePrefix(code)
+
+  // ② 端点（未配置 ⇒ 2，**不得**静默假装成功；非回环 http ⇒ 拒绝明文）
+  const server = resolveActivationServer({ flag: values['--server'], env })
+  if (!server.ok) return failJson(2, server.reason, server.error, { server: { source: server.source || null } })
+
+  // ③ 设备码（默认取本机；读不到 ⇒ 显式 `--no-device` 才走 unbound —— **不静默降级**）
+  const noDevice = bools.has('--no-device')
+  const explicitCode = values['--device-code'] !== undefined ? String(values['--device-code']).trim().toLowerCase() : null
+  if (noDevice && explicitCode) return failJson(2, 'usage_error', '`--no-device` 与 `--device-code` 互斥（要么绑这台机器，要么显式不绑）')
+  const readOpts = deps.deviceRead ? { ...deps.deviceRead } : {}
+  let device = null
+  let deviceSource = 'none'
+  if (noDevice) {
+    deviceSource = 'none'
+  } else if (explicitCode) {
+    if (!/^[0-9a-f]{64}$/.test(explicitCode)) {
+      return failJson(2, 'usage_error', '--device-code 必须是 64 位十六进制的**设备码**（`argent license request` 打印的那串）：'
+        + '⛔ 不要给主机名/MAC/IP（D3：指纹只认硬件 UUID 一项）')
+    }
+    device = { code: explicitCode, algo: currentDevice(readOpts).algo, issuedAt: new Date().toISOString() }
+    deviceSource = 'flag'
+  } else {
+    const dev = currentDevice(readOpts)
+    if (!dev.ok) {
+      return failJson(2, dev.reason === 'device_unsupported' ? 'device_unsupported' : 'device_read_failed',
+        `${dev.error} ⇒ 要么显式给 \`--device-code <64hex>\`（在能读到指纹的机器上跑 \`argent license request\`），`
+        + '要么显式 `--no-device`（**不静默降级成 unbound**：那会把"绑不上"悄悄变成"没绑定"）',
+        { device: { supported: false, reason: dev.reason } })
+    }
+    device = { code: dev.code, algo: dev.algo, issuedAt: dev.issuedAt }
+    deviceSource = 'local'
+  }
+
+  // ④ 目标与密钥来源（回显"将写哪个文件"）
+  const dataDir = deps.dataDir || resolveDataDir({ env }).dir
+  const targetLicense = join(dataDir, 'license.json')
+  const targetSecret = join(dataDir, 'license.secret')
+  const auditFile = activationAuditPath(dataDir)
+  const explicitSecretPath = values['--secret-file'] ? resolve(String(values['--secret-file'])) : null
+  if (explicitSecretPath && !existsSync(explicitSecretPath)) {
+    return failJson(2, 'usage_error', `--secret-file 指向的密钥文件不存在：${explicitSecretPath}`)
+  }
+  const explicitSecret = Boolean(explicitSecretPath) || Boolean(String(env.ARGENT_LICENSE_SECRET || '').trim())
+  // 密钥来源优先级：显式（--secret-file / 环境变量）> 本机已装 license.secret > 服务端随兑换返回
+  const secretSource = explicitSecret ? 'explicit' : (existsSync(targetSecret) ? 'local' : 'server')
+  const acceptSecret = secretSource === 'server'
+
+  const confirm = ['--apply', '--yes', '--confirm'].some((f) => bools.has(f))
+  const dryRun = !confirm || bools.has('--dry-run')          // A3：默认 dry-run；`--dry-run` 恒优先
+  // A4 守卫（`regression_refused`）的**逃生阀**：本层**只透传**，判定仍在 scripts/install-license.mjs
+  // （不复制判据 —— 否则"什么算倒退"会有第二份定义）。默认 false：倒退必须被显式签字确认。
+  const allowRegression = bools.has('--allow-regression')
+  const requestId = deps.requestId || randomUUID()
+  const timeoutMs = resolveTimeoutMs(env)
+  const instanceHint = values['--instance'] ? String(values['--instance']).trim() : null
+  if (instanceHint && !/^[A-Za-z0-9._:-]{1,128}$/.test(instanceHint)) {
+    return failJson(2, 'usage_error', '--instance 只接受 `^[A-Za-z0-9._:-]{1,128}$`（它只是**提示串**：不参与任何判定）')
+  }
+  const intent = values['--intent'] ? String(values['--intent']) : 'activate'
+  if (!ACTIVATION_INTENTS.includes(intent)) {
+    return failJson(2, 'usage_error', `--intent 只认 ${ACTIVATION_INTENTS.join('｜')}（续期/重绑复用同一端点，见方案 §9.5）`)
+  }
+
+  // 生效值回显（A2）：**白名单字段**，不放任何响应体的原始内容
+  const request = {
+    activation: {
+      codePrefix, codeLength: ACTIVATION_CODE_LENGTH, requestId,
+      ttlMinutes: ACTIVATION_CODE_TTL_MINUTES, reuseWindowHours: ACTIVATION_REUSE_WINDOW_HOURS,
+      // ⛔ 这里**不放**展示形态：`codePrefix`（8 位）已够人工核对，多给一位就多一分泄漏面
+      displayNote: `展示形态 ${ACTIVATION_CODE_GROUP} 位一组（${'X'.repeat(ACTIVATION_CODE_GROUP)}-…）只用于人读；输出里只回显前缀`,
+    },
+    device: device
+      ? { requested: true, source: deviceSource, code: device.code, algo: device.algo, issuedAt: device.issuedAt }
+      : { requested: false, source: 'none', code: null, algo: null, issuedAt: null },
+    secret: {
+      source: secretSource, acceptServerSecret: acceptSecret, target: targetSecret,
+      explicitPath: explicitSecretPath,
+    },
+    target: { dataDir, licenseFile: targetLicense, secretFile: targetSecret, auditFile },
+    instanceHint, intent, confirmFlagsUsed: confirm, timeoutMs, allowRegression,
+  }
+
+  // ── A3：dry-run —— 在任何 fetch/临时文件/子进程**之前**返回（零网络 + 零落盘）──
+  if (dryRun) {
+    const json = {
+      ok: true, empty: false, code: 0, reason: null,
+      subcommand: 'activate', dryRun: true, applied: false,
+      server: { baseUrl: server.baseUrl, source: server.source, endpoint: server.endpoint, tls: server.tls, loopback: server.loopback },
+      endpoint: server.endpoint, codePrefix,
+      request,
+      audit: { attempted: false, file: auditFile, written: false, note: 'dry-run **不落**审计（A3 零副作用）' },
+      would: {
+        request: `POST ${server.endpoint}`,
+        writes: [
+          `${targetLicense}（0600，覆盖前备份；判据在 scripts/install-license.mjs）`,
+          ...(secretSource === 'server' ? [`${targetSecret}（0600，来自兑换响应；本机当前没有密钥）`] : []),
+        ],
+        network: '**零请求**（dry-run 不探测、也不占用一次性码）',
+      },
+      next: [
+        '确认无误后重跑并加 `--apply`（真兑换；同一个码只会被消费一次）',
+        '还没有设备码 ⇒ 先跑 `argent license request --json`，把 64hex 设备码交给网页/手机端生成码',
+        ...(allowRegression
+          ? ['⚠️ 本次带了 `--allow-regression`：若兑换回来的许可**比现役更早到期/被收窄**，落盘将被放行一次'
+            + '（默认是被 `regression_refused` 拒掉的）—— 请先 `argent license status --json` 核对现役到期值']
+          : ['若被 `regression_refused` 拒掉（新许可比现役更早到期/被收窄）⇒ ⛔ 先核对是不是拿错了权益，'
+            + '确需倒退才加 `--allow-regression`']),
+      ],
+      judgedBy: 'core/lib/license-activate.mjs（dry-run：只打印计划，不判定）',
+    }
+    const human = [
+      '🔎 [dry-run] 许可激活（一次性激活码兑换）—— 本次**不发任何网络请求、不写任何文件**',
+      `   端点：POST ${server.endpoint}（来源 ${server.source}${server.tls ? '' : '；明文 http 仅限回环'}）`,
+      `   激活码：前缀 ${codePrefix}…（${ACTIVATION_CODE_LENGTH} 位；**明文码不会出现在任何输出里**）`,
+      `   设备：${device ? `${deviceSource} ${String(device.code).slice(0, 12)}…（64hex 设备码）` : '**不声明设备**（unbound：服务端会签一份没有 device 的许可）'}`,
+      `   将写入：${targetLicense}（0600，覆盖前备份）`
+        + (secretSource === 'server'
+          ? ` ＋ ${targetSecret}（0600，来自兑换响应）`
+          : `（密钥：沿用${secretSource === 'explicit' ? '显式来源' : '本机已有 license.secret'}）`),
+      `   审计：${auditFile}（dry-run 不落）`,
+      ...(allowRegression
+        ? ['   ⚠️ 已带 `--allow-regression`：**允许放行一次倒退**（新许可比现役更早到期/被收窄时，默认会被 `regression_refused` 拒掉）']
+        : []),
+      '',
+      '   下一步：',
+      '     · 确认无误 ⇒ 重跑并加 `--apply`',
+      '     · 还没有设备码 ⇒ `argent license request --json`，把它交给网页/手机端生成一次性码',
+    ].join('\n')
+    return { json, human, stderr: '', exit: 0 }
+  }
+
+  // ── 真兑换（apply）────────────────────────────────────────────────────────
+  const fetchImpl = deps.fetch || globalThis.fetch
+  const finish = (json, human, exit) => {
+    const rec = auditRecord(json, { codePrefix, device, deviceSource, server, secretSource })
+    try {
+      const p = appendActivationAudit(dataDir, rec)
+      json.audit = { attempted: true, file: p, written: true, error: null }
+    } catch (e) {
+      json.audit = { attempted: true, file: auditFile, written: false, error: String((e && e.message) || e) }
+      json.warnings = [...(json.warnings || []), `审计写不下（${json.audit.error}）：兑换本身已发生，请人工补记`]
+    }
+    // ⛔ 逃生阀**不得被静默使用**：`--json` 会把 human 藏掉（stdout 只留合同字段）⇒
+    //    放行一次倒退时把同一条标注**额外写 stderr**，让 CI/管道里的人也一定看得见。
+    const banner = asJson && json.regressionNote ? `${json.regressionNote}\n` : ''
+    return { json, human: json.audit.written ? human : `${human}\n   ⚠️ 审计写不下：${json.audit.error}`, stderr: banner, exit }
+  }
+  /** 服务端文本的统一"去码"处理（闭包：需要本次的明文码才能抹）。 */
+  const redact = (t) => redactActivationCode(t, code)
+  const shell = () => ({
+    subcommand: 'activate', dryRun: false, applied: false,
+    server: { baseUrl: server.baseUrl, source: server.source, endpoint: server.endpoint, tls: server.tls, loopback: server.loopback },
+    endpoint: server.endpoint, codePrefix, request,
+  })
+
+  if (typeof fetchImpl !== 'function') {
+    return failJson(1, 'activation_server_unreachable', '本运行时没有 fetch 实现（Node ≥18 才有）⇒ 无法兑换', shell())
+  }
+  const startedAt = new Date().toISOString()
+  const red = await postJson({
+    endpoint: server.endpoint,
+    timeoutMs,
+    fetchImpl,
+    body: {
+      code,
+      requestId,
+      device,
+      instanceHint,
+      acceptSecret,
+      intent,
+      client: { name: 'argent', version: clientVersionOf(repo) },
+    },
+  })
+  const redemption = { httpStatus: red.status, attempted: true, requestId, at: startedAt }
+
+  // 网络层失败（连接失败 / 超时）——**注意**：码可能已被消费，因此同一个码重试是安全的（幂等复用）
+  if (red.network) {
+    const reason = red.network === 'timeout' ? 'activation_timeout' : 'activation_server_unreachable'
+    const info = CLIENT_ERROR_MAP[reason]
+    const json = { ok: false, empty: false, code: info.exit, reason, error: red.error, hint: info.hint, ...shell(), redemption }
+    return finish(json, `❌ ${reason}：${red.error}\n   下一步：${info.hint}`, Number(info.exit))
+  }
+
+  const body = red.body
+  const okBody = Boolean(body && typeof body === 'object' && body.ok === true)
+
+  // 服务端拒绝（含 2xx 但 ok!=true ⇒ **一律**按拒绝处理，绝不假装成功）
+  if (!okBody) {
+    const mapped = mapServerOutcome({ httpStatus: red.status, reason: body && body.reason })
+    // ⛔ 服务端给的文本**先抹掉明文码**再落地：客户端是"零泄漏"这条不变量的责任方（见 redactActivationCode）
+    const json = {
+      ok: false, empty: false, code: mapped.exit, reason: mapped.reason,
+      error: redact(pickText(body, ['error', 'message', 'hint'])) || `服务端返回 HTTP ${red.status}（响应不可解析或缺 ok:true）`,
+      hint: redact(pickText(body, ['hint'])) || mapped.hint,
+      serverReason: mapped.serverReason, ...shell(),
+      redemption: { ...redemption, codePrefix: acceptCodePrefix(pickText(body, ['codePrefix']), codePrefix), serverReason: mapped.serverReason },
+    }
+    return finish(json, redact(`❌ 兑换被拒（${mapped.reason}${mapped.serverReason && mapped.serverReason !== mapped.reason ? ` ← 服务端 ${mapped.serverReason}` : ''}｜HTTP ${red.status}）`
+      + `\n   ${json.error}\n   下一步：${json.hint}`), Number(mapped.exit))
+  }
+
+  // 产物检查（**只查"契约要求的字段在不在"**；形状/验签判据不在这里复制 —— 交给 install-license）
+  const licenseFile = body.licenseFile
+  const serverSecret = typeof body.secret === 'string' ? body.secret.trim() : ''
+  const serverSha = acceptSha(body.licenseFileSha256)
+  const clientSha = licenseFile && typeof licenseFile === 'object' ? payloadSha256(licenseFile) : null
+  const missing = []
+  if (!licenseFile || typeof licenseFile !== 'object' || Array.isArray(licenseFile)) missing.push('licenseFile')
+  if (acceptSecret && !serverSecret) missing.push('secret（请求了 acceptSecret:true，响应却没给）')
+  if (missing.length) {
+    const json = {
+      ok: false, empty: false, code: 1, reason: 'activation_bad_response',
+      error: redact(`服务端响应缺字段：${missing.join('、')}`),
+      hint: CLIENT_ERROR_MAP.activation_bad_response.hint, ...shell(),
+      redemption: { ...redemption, seat: body.seat || null, serverSha, clientSha },
+    }
+    return finish(json, `❌ activation_bad_response：${json.error}\n   下一步：${json.hint}`, 1)
+  }
+
+  const warnings = []
+  if (serverSha && clientSha && serverSha !== clientSha) {
+    // 不据此拒绝（安全判据是 HMAC 验签，归 install-license）；但必须如实标注 —— 便于与服务端审计行对账
+    warnings.push(`响应里的 licenseFileSha256 与本机复算不一致（服务端 ${String(serverSha).slice(0, 16)}… ≠ 本机 ${String(clientSha).slice(0, 16)}…）⇒ 请与服务端审计行核对`)
+  }
+  if (!acceptSecret && serverSecret) {
+    warnings.push('本机已有密钥（或用了 --secret-file）⇒ **忽略**响应里的 secret，不覆盖本机密钥')
+  }
+
+  // 临时目录：把兑换产物交给 install-license（**唯一落盘判据**）读；无论成败都删掉
+  const tmpDir = mkdtempSync(join(tmpdir(), 'argent-activate-'))
+  try {
+    const tmpLicense = join(tmpDir, 'license.json')
+    writeFileSync(tmpLicense, `${JSON.stringify(licenseFile, null, 2)}\n`, { mode: 0o600 })
+    chmodSync(tmpLicense, 0o600)
+    const childArgs = ['--file', tmpLicense, '--json']
+    let tmpSecret = null
+    if (secretSource === 'server' && serverSecret) {
+      tmpSecret = join(tmpDir, 'license.secret')
+      writeFileSync(tmpSecret, `${serverSecret}\n`, { mode: 0o600 })
+      chmodSync(tmpSecret, 0o600)
+    }
+    if (secretSource === 'explicit' && explicitSecretPath) childArgs.push('--secret-file', explicitSecretPath)
+    else if (tmpSecret) childArgs.push('--secret-file', tmpSecret)
+    // A4 守卫的逃生阀：**逐字透传**给 install-license（判定只发生在那里：`regression_refused` 的判据不自建第二份）
+    if (allowRegression) childArgs.push('--allow-regression')
+    const script = join(repo, 'scripts', 'install-license.mjs')
+    const r = spawn(process.execPath, [script, ...childArgs], { encoding: 'utf8', maxBuffer: 32 * 1024 * 1024, env })
+    const childStatus = r && r.status !== null && r.status !== undefined ? Number(r.status) : 1
+    const childOut = String((r && r.stdout) || '')
+    let inst = null
+    try { inst = JSON.parse(childOut.slice(childOut.indexOf('{'))) } catch { inst = null }
+    if (!inst) {
+      const json = {
+        ok: false, empty: false, code: 1, reason: 'bad_output',
+        error: `install-license 输出不可解析（exit=${childStatus}）：${String((r && r.stderr) || childOut).trim().slice(0, 300)}`,
+        ...shell(),
+        redemption: { ...redemption, seat: body.seat || null, serverSha, clientSha },
+      }
+      return finish(json, `❌ bad_output：${json.error}`, 1)
+    }
+    // 退出码逐字透传（install-license：0 已安装/幂等 ｜ 1 验签/设备/倒退被拒 ｜ 2 用法）
+    const exit = childStatus === 0 ? 0 : (childStatus === 1 ? 1 : 2)
+    // A4：本次是否**真的**放行了一次倒退（而不是"带了标志但没倒退"）—— 只在真放行时才标注，
+    // 否则告警会变成噪音，运营就学会忽略它了。
+    const cmp = inst && inst.comparison && typeof inst.comparison === 'object' ? inst.comparison : null
+    const releasedRegression = exit === 0 && inst.allowRegression === true && Boolean(cmp)
+      && (cmp.stale === true || cmp.narrowed === true)
+    const regressionWhy = releasedRegression
+      ? [
+        cmp.stale === true ? `更早到期（现役 ${cmp.incumbentExpiresAt} → 新 ${cmp.incomingExpiresAt}）` : '',
+        cmp.narrowed === true
+          ? `能力/业务线/席位被收窄（缺 ${[...(cmp.missingCapabilities || []), ...(cmp.missingVerticals || [])].join(',') || '—'}`
+            + `${cmp.seatsNarrowed ? `；席位被收窄` : ''}）` : '',
+      ].filter(Boolean).join('；')
+      : ''
+    const json = {
+      // 判据落点（install-license）的关键字段**显式**抄到顶层（不用 spread：两边都有 `device`/`target`，spread 会互相覆盖）
+      ok: exit === 0,
+      empty: false,
+      code: exit,
+      reason: exit === 0 ? null : (inst.reason || (exit === 1 ? 'guard_rejected' : 'usage_error')),
+      error: exit === 0 ? null : (inst.error || null),
+      ...shell(),
+      applied: exit === 0,
+      redemption: {
+        ...redemption, seat: body.seat || null, reused: body.reused === true,
+        state: typeof body.state === 'string' ? redact(body.state).slice(0, 32) : null,
+        serverSha, clientSha, codePrefix: acceptCodePrefix(pickText(body, ['codePrefix']), codePrefix),
+      },
+      // 判据落点的原始输出（**原样**透传，便于排障；不含明文码）
+      install: inst,
+      signatureVersion: inst.signatureVersion === 2 ? 2 : (inst.signatureVersion === 1 ? 1 : null),
+      deviceSigned: inst.deviceSigned === true,
+      unchanged: inst.unchanged === true,
+      // A4 逃生阀的**如实回显**：`allowRegression` = 本次是否带了标志（透传自 install-license）；
+      // `regressionReleased` = 它是否**真的**放行了一次倒退（带了标志但没倒退 ⇒ false，不虚报）。
+      allowRegression: inst.allowRegression === true,
+      regressionReleased: releasedRegression,
+      // 显式标注（人话；`--json` 时同一句还会写 stderr）—— 逃生阀用一次要留一次字据
+      regressionNote: releasedRegression ? `⚠️ 本次放行了一次倒退（--allow-regression）：${regressionWhy}` : null,
+      device: inst.device || null,
+      comparison: inst.comparison || null,
+      renewal: inst.renewal || null,
+      backups: inst.backups || [],
+      userId: inst.userId || '', seats: inst.seats, capabilities: inst.capabilities || [], verticals: inst.verticals || [],
+      expiresAt: inst.expiresAt || null, graceDays: inst.graceDays, licenseFile: inst.source, targetFile: inst.target,
+      warnings: [...warnings, ...((inst && inst.warnings) || [])],
+      judgedBy: 'scripts/install-license.mjs（验签/设备比对/0600/备份/读回/幂等/拒绝倒退）',
+    }
+    const human = exit === 0
+      ? `✅ 已激活：一次性码（前缀 ${codePrefix}…）→ ${targetLicense}`
+        + `\n   账号：${inst.userId} ｜ 席位：${inst.seats} ｜ 到期：${inst.expiresAt}`
+        + `\n   签名版本：${inst.signatureVersion === 2 ? 'v2（device 已进签名）' : (inst.signatureVersion === 1 ? 'v1（device 未进签名）' : '判不出')}`
+        + ` ｜ 设备绑定：${inst.device ? `${inst.device.binding}（${inst.device.reason}）` : '（未声明）'}`
+        + (inst.unchanged ? '\n   ♻️ 与现役许可逐字节一致 ⇒ 未重写、未备份（幂等）' : '')
+        + (releasedRegression
+          ? `\n   ${json.regressionNote}`
+            + '\n      ↳ 这是**签字确认**而不是修复：现役有效期/能力已被这份许可覆盖，'
+            + '下一步请核对权益（⛔ 续期流程不该常态化带这个标志）'
+          : '')
+        + `\n   自检：argent license status --json（期望 signatureVersion:2 ∧ deviceSigned:true ∧ device.binding:match）`
+      : `❌ 兑换成功但**落盘被拒**（${json.reason}）：${inst.error || ''}\n   ⛔ 原许可一个字节未动（判据在 scripts/install-license.mjs）`
+        + (json.reason === 'regression_refused'
+          ? '\n   ↳ 确需放行这次倒退（纠错/吊销/换绑）⇒ **重跑并加 `--allow-regression`**（不是 `--rebind`）；'
+            + '⛔ 但先核对是不是拿错了权益 —— 新许可比现役更早到期/被收窄时，续期会被**每次**打回'
+          : '')
+    return finish(json, human, exit)
+  } finally {
+    try { rmSync(tmpDir, { recursive: true, force: true }) } catch { /* 临时目录清不掉不影响结论 */ }
+  }
+}
+
+/**
+ * 超时（默认 15s）：可用 `ARGENT_LICENSE_ACTIVATE_TIMEOUT_MS` 覆盖（慢网络/测试桩用），
+ * 夹在 [200, 120000] 之间 —— 下界防"设成 0 等于必超时"，上界防"设成一天"把 CLI 挂死。
+ */
+export function resolveTimeoutMs(env = {}) {
+  const raw = Number(String((env && env.ARGENT_LICENSE_ACTIVATE_TIMEOUT_MS) || '').trim())
+  if (!Number.isFinite(raw) || raw <= 0) return DEFAULT_TIMEOUT_MS
+  return Math.min(120000, Math.max(200, Math.round(raw)))
+}
+
+/** 读 `--code-file`（0600 建议；**不回显内容**）。 */function readCodeFile(p) {
+  const path = resolve(String(p))
+  if (!existsSync(path)) return { __error: `--code-file 指向的文件不存在：${path}` }
+  try {
+    const t = readFileSync(path, 'utf8').trim()
+    if (!t) return { __error: `--code-file 是空文件：${path}` }
+    return t.split('\n')[0].trim()          // 只取第一行（文件里可能带说明行）
+  } catch (e) {
+    return { __error: `--code-file 读不出来（${path}）：${(e && e.message) || e}` }
+  }
+}
+
+/** 客户端版本（仅用于服务端审计/排障；读不到就不带该字段）。 */
+function clientVersionOf(repo) {
+  try { return String(readFileSync(join(repo, 'VERSION'), 'utf8')).trim() || null } catch { return null }
+}
+
+/** 从响应里挑一个**非空字符串**字段（白名单式取值：绝不把响应体透传出去）。 */
+function pickText(body, keys) {
+  if (!body || typeof body !== 'object') return ''
+  for (const k of keys) {
+    const v = body[k]
+    if (typeof v === 'string' && v.trim()) return v.trim().slice(0, 500)
+  }
+  return ''
+}
+
+/**
+ * POST JSON（唯一网络出口）。
+ * @returns {Promise<{status:number|null, body:object|null, text:string, network:string|null, error:string}>}
+ */
+async function postJson({ endpoint, body, timeoutMs, fetchImpl }) {
+  const ctl = new AbortController()
+  const timer = setTimeout(() => ctl.abort(), timeoutMs)
+  try {
+    const res = await fetchImpl(endpoint, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', accept: 'application/json' },
+      body: JSON.stringify(body),
+      signal: ctl.signal,
+    })
+    const text = String(await res.text())
+    let parsed = null
+    try { parsed = JSON.parse(text) } catch { parsed = null }
+    return { status: Number(res.status), body: parsed, text, network: null, error: '' }
+  } catch (e) {
+    const msg = String((e && e.message) || e)
+    const timeout = (e && e.name === 'AbortError') || /abort/i.test(msg)
+    return {
+      status: null, body: null, text: '', network: timeout ? 'timeout' : 'unreachable',
+      error: timeout ? `请求超时（${timeoutMs}ms）：${endpoint}` : `连不上 ${endpoint}：${msg}`,
+    }
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+/**
+ * 审计行（**只落 codePrefix，绝不落明文码/密钥**；apply 的成败都留一行）。
+ * 字段口径对齐方案 §9.4"审计事件"（客户端侧）：服务端另有一份（它才记 `ipHash`/`uaHash`）。
+ */
+function auditRecord(json, { codePrefix, device, deviceSource, server, secretSource }) {
+  return {
+    at: new Date().toISOString(),
+    verb: 'license.activate',
+    ok: json.ok === true,
+    code: json.code,
+    reason: json.reason || null,
+    subcommand: 'activate',
+    activation: {
+      codePrefix, codeLength: ACTIVATION_CODE_LENGTH,
+      requestId: (json.request && json.request.activation && json.request.activation.requestId) || null,
+    },
+    server: { host: safeHost(server.baseUrl), endpoint: server.endpoint, source: server.source, tls: server.tls },
+    device: { source: deviceSource, code: device ? device.code : null, algo: device ? device.algo : null },
+    secret: { source: secretSource },
+    redemption: json.redemption ? {
+      httpStatus: json.redemption.httpStatus ?? null,
+      reused: json.redemption.reused === true,
+      serverSha: json.redemption.serverSha || null,
+      clientSha: json.redemption.clientSha || null,
+    } : null,
+    result: json.install ? {
+      licenseFile: json.install.target, signatureVersion: json.install.signatureVersion ?? null,
+      deviceSigned: json.install.deviceSigned === true, unchanged: json.install.unchanged === true,
+      backups: (json.install.backups || []).length, binding: json.install.device ? json.install.device.binding : null,
+    } : null,
+    dataDir: (json.request && json.request.target && json.request.target.dataDir) || null,
+  }
+}
+
+/** 审计里只留 host（不落完整 URL 的查询串之类）。 */
+function safeHost(baseUrl) {
+  try { return new URL(baseUrl).host } catch { return String(baseUrl || '') }
+}