@whyshu/argent-engine 0.0.0-stage → 0.6.0

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

@@ -0,0 +1,1645 @@
+/**
+ * `argent license ops` —— 许可**只读运营巡检**（O2：替代 `mongosh`；2026-10-04）
+ *
+ * ## 为什么有它（判据出处）
+ * 《Argent-1.0-退出判据与版本规则》§2.6 O2：**只读运营视图**（在途码 / 失败码 / 设备）替代 `mongosh`。
+ * 验收 = 三个问题各一条查询（**在途码数 / 近 7 天失败码 Top / 某设备挂在谁名下**）不碰 `mongosh` 即可回答。
+ * 该节同时点名两个**已知陷阱**，本文件把它们变成**可判的守卫**（而不是注释里的提醒）：
+ *   ① 码状态字段是 **`state`**，不是 `status` —— 按 `status` 查**恒空**，会把"有在途码"误读成"没有"；
+ *   ② 席位**不是**存储字段（`used` 不是）—— 必须按 **`releasedAt` 为空的设备码去重**算出来。
+ * ⇒ 本文件对这两个陷阱都是**响亮失败**（`field_missing`，exit 2），**绝不静默返回 0**（那正是假绿）。
+ *
+ * ## 三条纪律（每条都可判）
+ * | # | 纪律 | 落点 |
+ * |---|---|---|
+ * | ① | **只读**：不写任何集合/文件/审计；HTTP **只发 GET**，且⛔**绝不**调 `POST /api/argent/license/release-device`（该端点的 200 成功路径在生产库**从未跑过** ⇒ 视图不得触发任何写） | 全文件零写调用；`httpGet()` 是唯一网络出口且 method 硬编码 `GET` |
+ * | ② | **缺数据源就说"缺"，不用 0 充数**：每一节都带 `available`；不可用的节给 `reason` + `needs`（要哪个接口/哪份数据），`missingEndpoints` 列出缺的服务端只读接口 | `unavailable()` / `OPS_READ_ENDPOINTS` |
+ * | ③ | **凭证只从 600 的文件读、绝不回显**：`--token-file` > `$ARGENT_OPS_TOKEN` > `$ARGENT_OPS_TOKEN_FILE` > `<数据目录>/*.env`（**权限必须是 600**，否则拒用）；token 不进 JSON/人读/错误串 | `resolveOpsToken()` |
+ *
+ * ## A1 / A2 / A3
+ *   · A1：`0` 读成功（含"成功但空" `empty:true + no_match`）｜`2` 用法/环境（未知参数、`--from` 与 `--server` 同时给、快照不可解析、**缺必需字段 `field_missing`**、端点未配置、缺 token、token 文件权限不是 600）｜`1` 数据源读失败（服务端连不上/超时、响应不合约）。
+ *   · A2：`ok/empty/code/reason` 恒在；`$? == json.code`；`--json` 时 stdout 只有一份 JSON；回显**实际生效值**（`source` / `now` / `days` / `filters` / 每节的 `available`）。
+ *   · A3：**读类 verb，零副作用**（不落审计、不写数据目录、不发写请求），因此**没有** `--apply`/`--yes`；
+ *     JSON 里以 `readOnly:true` + `sideEffects:"none"` 表达（⛔ **不写** `dryRun` —— 那会让宿主去找一个不存在的 `--apply`）。
+ *
+ * ## 与判断面清单的关系（⚠️ 如实登记，不假装）
+ * 本 verb 是**只读报告**，不做任何门禁/放行判定（J1–J10 全部不涉及）。它内部的阈值
+ * （`OPS_TTL_GRACE_MINUTES` / `OPS_DENIED_REPEAT` / 席位口径）是**告警口径**，只影响 `anomalies` 的内容，
+ * ⛔ 不影响任何写操作是否放行 ⇒ **未登记为第 11 条 judgment**（登记与否是 Y 位改动的取舍，见守则 §3.2）。
+ * 两个陷阱守卫（`state` / `devices`）是**输入形状校验**（与 `parseSubArgs` 同类），不是业务判定。
+ *
+ * ## 数据源三选一（互斥；默认 = 本机只读产物）
+ * | 形态 | 参数 | 能回答什么 |
+ * |---|---|---|
+ * | 离线快照 | `--from <snapshot.json>` | 五节全给（在途/失败/时间线/席位/异常）—— 快照形态见 `OPS_SNAPSHOT_SHAPE` |
+ * | 服务端只读接口 | `--server <base>`（管理员 JWT） | **五节全给**（4 个只读接口自 2026-10-04 起已在服务端就绪，契约见 `whyshu-svr/docs/ops/license-ops-readonly.md`）；接口**未部署**或某节读不到时如实标 `available:false + endpoint_missing`（⛔ 不是 0） |
+ * | 本机产物（默认） | 无参数 | 本机许可声明（席位/到期）+ 本机激活审计（见过的 `codePrefix` 与结果）；需要服务端的节标 `needs_server` |
+ *
+ * ### 服务端 → 客户端：**四处字段映射**（服务端回报点名；改这里之前先读服务端契约 §5）
+ * | # | 服务端给的 | 客户端要的 | 落点 |
+ * |---|---|---|---|
+ * | ① | `seats.items[].devices[].codePrefix`（**12 位前缀**） | `accounts[].devices[].code`（`OPS_REQUIRED_FIELDS.devices=['code']`；⛔ **不把 64hex 全码补回来**） | `mapServerSeats()` |
+ * | ② | `seats.items` / `seats.totals`；`deviceLimitSource: 'deviceLimit'｜'seats'`（**机器值**） | `seats.principals` / `seats.totals`（客户端**自己算**）；展示串 `deviceLimit 字段`｜`seats（缺省跟随 seats）` 由客户端拼 | `mapServerSeats()` / `OPS_SEAT_LIMIT_SOURCE_TEXT` |
+ * | ③ | `devices/:codePrefix` 的 **`total`** | `device.found`（判定"命中几处"只看它；`count` 只是本页条数） | `mapServerDevice()` |
+ * | ④ | `events` 的 **`total`（窗口内总数）/ `count`（本页条数）** | `timeline.server.total`（窗口内）/ `timeline.count`（本页，= 本页条数）——⚠️ `timeline.scanned` 是**客户端窗口过滤后**的条数（≤ 本页），⛔ 别拿它当"窗口内总数"；请求**显式 `limit=200`**（服务端上限） | `serverPageMeta()`（每节的 `server` 元信息）+ `runOpsVerb` 的服务端分支 |
+ *
+ * ⛔ **本仓库不直连生产库**：`--from` 的快照由服务端**只读**导出（或运营用 `mongosh` 的只读查询自己导出一次），
+ * 本仓库既不持有库凭证、也不开库连接 —— 于是"视图会不会误写生产"这个问题在**形态上**就不存在。
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { resolveDataDir } from './argent-datadir.mjs'
+import { SOURCES, readSource } from './audit.mjs'
+import {
+  ACTIVATION_CODE_STATES, ACTIVATION_CODE_TTL_MINUTES,
+  CODE_STATUS_PATH, endpointOf, resolveActivationServer, resolveTimeoutMs,
+} from './license-activate.mjs'
+import { licenseVerdict } from './license-verdict.mjs'
+
+// ── 参数表（**唯一一份**：`core/lib/license.mjs` 的 SPEC.ops 直接引用它，不各写一遍）──────
+export const OPS_VALUE_FLAGS = ['--from', '--server', '--token-file', '--days', '--now', '--device']
+export const OPS_REPEAT_FLAGS = ['--filter', '--prefix']
+export const OPS_BOOL_FLAGS = ['--local', '--probe', '--json', '--help', '-h']
+
+export const OPS_DEFAULT_DAYS = 7
+/** TTL 宽限（分钟）：`redeeming` 是 CAS 中间态 + 允许一点时钟偏差 ⇒ 超期超过它才算"该终态没终态"。 */
+export const OPS_TTL_GRACE_MINUTES = 5
+/** 同一前缀的 `*_denied` 事件达到这个数 ⇒ 记一条异常（锁定/探针痕迹）。 */
+export const OPS_DENIED_REPEAT = 3
+/** 设备码**只回前 12 位**（与 `licenseevents` 审计同口径；库里存的才是 64hex）。 */
+export const OPS_DEVICE_ECHO = 12
+/** 时间线最多回多少条（先过滤后截断 —— D1 的教训）。 */
+export const OPS_MAX_EVENTS = 200
+/**
+ * 服务端分页上限（契约 §0：`limit` 缺省 50 / **上限 200**，超限 ⇒ 400 `bad_limit`，⛔ 不静默截断）。
+ * 客户端**显式**给 200（`--probe` 那次例外：占位探测用服务端缺省），一次尽量把窗口/在途取全。
+ */
+export const OPS_PAGE_LIMIT = 200
+
+// ── 服务端只读接口的**相对路径**（拼 URL 用；显示的 `path` 在 `OPS_READ_ENDPOINTS`）──────────
+export const CODES_LIST_REL = 'api/argent/license/activation-codes'
+export const EVENTS_REL = 'api/argent/license/events'
+export const SEATS_REL = 'api/argent/license/seats'
+export const DEVICE_LOOKUP_REL = 'api/argent/license/devices/'
+
+/** `deviceLimitSource`：服务端给**机器值**（`'deviceLimit'|'seats'`），展示串在客户端拼（映射②）。 */
+export const OPS_SEAT_LIMIT_SOURCE_TEXT = {
+  deviceLimit: 'deviceLimit 字段',
+  seats: 'seats（缺省跟随 seats）',
+}
+
+/** 码的状态机（与服务端 `ActivationCode.state` 逐字一致；引用自 `license-activate.mjs`）。 */
+export const OPS_CODE_STATES = ACTIVATION_CODE_STATES
+/** 在途 = 还没终态的两个状态（O2 的"在途码"定义）。 */
+export const OPS_INFLIGHT_STATES = ['issued', 'redeeming']
+/** `codes-list` 一次拉哪几个状态：`issued,redeeming` 喂 `inflight`（在途），`revoked` 喂 `failures`。 */
+export const OPS_CODES_QUERY_STATES = [...OPS_INFLIGHT_STATES, 'revoked']
+
+/** `licenseevents.action` 的**已知**取值（词表来源见文件头；未知动作只登记不判红 —— 服务端可能新增）。 */
+export const OPS_EVENT_ACTIONS = ['code_issue', 'code_redeem', 'code_redeem_denied', 'code_revoke', 'code_revoke_denied', 'device_release']
+
+/**
+ * **字段契约**（域必需字段）—— 每个集合**非空时必须带全**，否则 `field_missing`（exit 2）。
+ * ⛔ 这条判据的存在就是为了那两个陷阱：缺 `state`（写成 `status`）⇒ 报错；缺 `devices` ⇒ 报错。
+ * **绝不**把"字段不在"降级成"计数为 0"。
+ */
+export const OPS_REQUIRED_FIELDS = {
+  codes: ['codePrefix', 'state'],
+  events: ['at', 'action', 'result'],
+  accounts: ['userId', 'seats', 'devices'],
+  devices: ['code'],
+}
+
+/** `--filter` 允许的码字段（**本域的词表**；不在这张表里 ⇒ `field_missing`）。 */
+export const OPS_FILTER_FIELDS = ['state', 'codePrefix', 'intent', 'userId', 'failCount']
+
+/** 字段缺失时给人看的那句话（**陷阱的唯一文案落点**）。 */
+export const OPS_FIELD_HINTS = {
+  state: '码状态字段是 **`state`**（' + OPS_CODE_STATES.join('｜') + '），**不是 `status`** —— '
+    + '按 `status` 查**恒空**，会把"有在途码"误读成"没有"（O2 已知陷阱①）。请核对导出/接口的字段名。',
+  devices: '席位**不是**存储字段（`used` 也不是）—— 必须按 **`releasedAt` 为空的设备码去重**算出来（O2 已知陷阱②）。'
+    + '缺 `devices` 就无法回答"用了几个席位"，⛔ 不接受用 `used` 字段充数。',
+  codePrefix: '码记录缺 `codePrefix`（前 8 位，人工核对用；明文码库里本来就没有）。',
+  at: '事件缺 `at`（ISO 时间）—— 没有时间就无法做"近 N 天"时间线。',
+  action: '事件缺 `action`（如 `code_issue`/`code_redeem`/`code_redeem_denied`/`code_revoke`/`device_release`）。',
+  result: '事件缺 `result`（`ok`｜`rejected`）。',
+  userId: '账号记录缺 `userId` —— 席位账目按账号归属，缺它无法回答"挂在谁名下"。',
+  seats: '账号记录缺 `seats`（许可声明的席位数）。',
+  code: '设备记录缺 `code`（64hex 设备码；输出只回前 ' + OPS_DEVICE_ECHO + ' 位）。',
+  devicesCodePrefix: '服务端席位行的设备记录缺 `codePrefix`（**12 位前缀**；⛔ 服务端本来就不回 64hex 全码，'
+    + '⛔ 客户端也不许把全码补回去）—— 缺它就算不出 `used`（`releasedAt` 为空的设备码去重数）。',
+}
+
+/**
+ * **服务端只读接口登记表** —— `exists` = 服务端契约里**已就绪**（`whyshu-svr` `92c6233`；
+ * 契约文档 `whyshu-svr/docs/ops/license-ops-readonly.md`）。`missingEndpoints` = 本表里 `exists:false` 的
+ * **∪ 运行时实测 404（路由不在）** 的 —— 后者用于"接口已就绪但**还没部署**"这个真实窗口：
+ * 静态登记说在位、线上却回 404 ⇒ 那一节标 `available:false + endpoint_missing`，⛔ **不是空集**。
+ * `rel` = 拼 URL 用的相对路径（`endpointOf()` 拼；`path` 只用于显示，带前导 `/`）。
+ * ⛔ 本表**只列读**（GET）。写端点（`POST /api/argent/license/release-device`）**不入表、不探测、不调用**。
+ */
+export const OPS_READ_ENDPOINTS = [
+  {
+    id: 'code-status', method: 'GET', path: '/api/argent/license/activation-code/{prefix}', exists: true,
+    rel: 'api/argent/license/activation-code/',
+    neededFor: 'inflight',
+    note: '**已上线**（管理员 JWT）：按 8 位前缀单查一个码的状态；`deviceCodePrefix` 只回前 12 位。'
+      + '它只能"按前缀查"，没有"列出全部在途码"的能力（后者见 `codes-list`）——'
+      + '`codes-list` 读不到时本视图退回按前缀单查（`coverage:"prefix-only"`，⛔ 不假装是全量）。',
+  },
+  {
+    id: 'codes-list', method: 'GET', path: '/api/argent/license/activation-codes?state=issued,redeeming,revoked&limit=N',
+    rel: 'api/argent/license/activation-codes', exists: true,
+    neededFor: 'inflight',
+    note: '**已就绪**（服务端 `92c6233`）：全量在途码列表（`activationcodes` 的只读投影，每行只有 '
+      + '`codePrefix/state/intent/expiresAt/failCount/deviceCodePrefix`）。客户端一次拉 `issued,redeeming,revoked`：'
+      + '前两态喂 `inflight`（⇒ `coverage:"full"`），`revoked` 喂 `failures`（⛔ 不去读明文码/`codeHash`）。'
+      + '`hasMore:true` ⇒ 本页不是全量（`coverage:"page-only"`，⛔ 不当成全量）。',
+  },
+  {
+    id: 'events', method: 'GET', path: '/api/argent/license/events?since={iso}&limit=N',
+    rel: 'api/argent/license/events', exists: true,
+    neededFor: 'timeline',
+    note: '**已就绪**（服务端 `92c6233`）：`licenseevents` 的只读投影（**只回 `at`/`action`/`result`/`codePrefix`**）。'
+      + '`total` = 窗口内总数、`count` = 本页条数（客户端显式 `limit=200`）；`hasMore:true` ⇒ 窗口内还有更早的。',
+  },
+  {
+    id: 'seats', method: 'GET', path: '/api/argent/license/seats?limit=N', rel: 'api/argent/license/seats', exists: true,
+    neededFor: 'seats',
+    note: '**已就绪**（服务端 `92c6233`）：席位账目（每账号 `seats` / `deviceLimit` / `deviceLimitSource` / `used` / `free` '
+      + '+ 设备列表含 `releasedAt`）。服务端按 `releasedAt` 为空的设备码去重算 `used`；客户端**再算一遍**并把两边的差'
+      + '记成异常 `seat_used_mismatch`（⛔ 不盲信任何一边、⛔ 也不接受 `used` 当存储字段）。',
+  },
+  {
+    id: 'device-lookup', method: 'GET', path: '/api/argent/license/devices/{codePrefix}',
+    rel: 'api/argent/license/devices/', exists: true,
+    neededFor: 'device',
+    note: '**已就绪**（服务端 `92c6233`）：设备归属（8..64 位 hex 都能查，回 `userId/licenseId/codePrefix/releasedAt/boundAt`）。'
+      + '查无此码 = **200 `empty:true`**（⛔ 不是 404）；命中处数看 **`total`**（客户端 `device.found`），'
+      + '`--probe` 用占位前缀探它时会回 **400 `bad_device`** ——"路由在、参数被拒"是正常的。',
+  },
+]
+
+/** 快照形态（`--from` 读的就是它；字段名与服务端集合逐字对齐 ⇒ 导出脚本不用改名）。 */
+export const OPS_SNAPSHOT_SHAPE = {
+  generatedAt: 'ISO 时间（可选；缺省用 `--now`）',
+  source: '字符串（可选）：这份快照是怎么来的（审计/可追溯）',
+  codes: '[{ codePrefix(8), state, intent?, issuedAt?, expiresAt?, ttlMinutes?, failCount?, lockedUntil?, userId?, deviceCode? }]',
+  events: '[{ at, action, result, codePrefix? }]',
+  accounts: '[{ userId, seats, deviceLimit?, devices:[{ code, releasedAt?, boundAt? }] }]',
+}
+
+export const OPS_USAGE = [
+  '用法：argent license ops [--from <快照.json> | --server <base>] [--days N] [--now <iso>] [--json]',
+  '',
+  '⛔ 只读：不发任何写请求、不落审计、不写数据目录（本 verb **没有** `--apply`）。',
+  '',
+  '数据源（三选一，互斥；缺省 = 本机只读产物）：',
+  '  --from <file>       离线快照（字段形态见 core/lib/license-ops.mjs#OPS_SNAPSHOT_SHAPE）；五节全给',
+  '  --server <base>     服务端只读接口（管理员 JWT）—— base URL 只给域名，别写成 `…/api/argent`；',
+  '                      4 个只读接口已在服务端就绪（activation-codes / events / seats / devices/:prefix）',
+  '                      ⇒ 五节全给、`coverage:"full"`；接口**未部署**时那一节标 available:false + endpoint_missing',
+  '                      （⛔ 不是"0 条" —— 用 `--probe` 看实测在不在）',
+  '',
+  '凭证（只从 600 的文件读、绝不回显；优先级从高到低）：',
+  '  --token-file <file>  >  $ARGENT_OPS_TOKEN  >  $ARGENT_OPS_TOKEN_FILE  >  <数据目录>/*.env（含 ARGENT_OPS_TOKEN/OPS_TOKEN）',
+  '',
+  '查询：',
+  '  --prefix <8位>      按前缀单查（可重复；回答了"这个码现在什么状态"，含已终态的码）',
+  '  --local             显式选「本机只读产物」（= 不带 --from/--server 时的缺省形态）',
+  '  --device <hex>      某设备挂在谁名下（12 位前缀或 64hex 全码都能给；命中处数看服务端 `total`）',
+  '  --filter <字段=值>  筛码，可重复；字段 ∈ ' + OPS_FILTER_FIELDS.join('｜'),
+  '  --days <N>          时间线窗口（缺省 ' + OPS_DEFAULT_DAYS + ' 天）｜ --now <iso> 固定"现在"（可复算）',
+  '  --probe             逐个**实测**只读接口在不在（只发 GET；写端点一律不探）：',
+  '                      已在本轮取数里打过的接口用那次实测结果（`via:"live-call"`），其余用占位参数真探一次',
+  '                      （`via:"explicit"`）⇒ 报 exists/missing，并标出与登记表不一致（`mismatch`）',
+  '',
+  '⚠️ 两个已知陷阱（本 verb 会**响亮报错**，不会静默给 0）：',
+  '  · 码状态字段是 `state` 不是 `status`（`--filter status=issued` ⇒ exit 2 + field_missing；',
+  '    服务端对 `?status=` 也回 400 `field_unknown` ⇒ 本视图同样 exit 2）',
+  '  · 席位是**算出来的**：`seats` + `deviceLimit`（缺省跟随 seats），`used` = `releasedAt` 为空的设备码去重数',
+].join('\n')
+
+// ── 小工具 ────────────────────────────────────────────────────────────────────
+const failJson = (code, reason, error, extra = {}) => ({
+  json: { ok: false, empty: false, code, reason, error, subcommand: 'ops', ...extra },
+  human: `❌ ${reason}：${error}`,
+  stderr: '', exit: code,
+})
+
+/** 设备码**只回前 12 位**（审计同口径；⛔ 绝不出全码）。 */
+export const echoDevice = (code) => String(code == null ? '' : code).slice(0, OPS_DEVICE_ECHO)
+
+const parseTime = (v) => {
+  if (v == null || v === '') return null
+  const t = Date.parse(String(v))
+  return Number.isNaN(t) ? null : t
+}
+const iso = (ms) => (Number.isFinite(ms) ? new Date(ms).toISOString() : null)
+const num = (v) => (Number.isFinite(Number(v)) ? Number(v) : null)
+
+/** 每节不可用时的统一形状（纪律②：说清"缺什么"，⛔ 不给 0）。 */
+const unavailable = (reason, needs, note) => ({ available: false, reason, needs, note })
+
+/**
+ * 节级 `reason` 的取值（**宿主在 `json.<section>.reason` 上分支**）。
+ * ⚠️ 它们**不是**顶层 `reason`（顶层只会是 0/1/2 那几种），但仍**登记进** `core/contracts/argent.contracts.json#reasonCodes`
+ * （`exit:0`）—— 让"宿主可能要分支的短码"只有**一份**词表（`check-judgment-drift` R1e 就扫这个）。
+ * 唯一真源仍是本表；契约里的登记只是入口。
+ */
+export const OPS_SECTION_REASONS = {
+  endpoint_missing: '服务端**没有**这个只读接口（缺哪个见 `missingEndpoints`）',
+  needs_server: '本机产物答不了，要服务端只读接口（`--server`）',
+  no_prefix: '没有可查的码前缀（既没 `--prefix`，本机审计里也没有）',
+  no_data: '快照里**没有这个集合**（缺席 ≠ 为空，⛔ 不报 0）',
+}
+
+/**
+ * `empty` 的**唯一判据**：**至少有一节"真答得上来"**，且所有可用的节都没有内容。
+ * ⚠️ 三层都在防假绿：
+ *   · 不可用的节**不参与**判空（"答不了"与"没有"是两件事）；
+ *   · **一节都答不了 ⇒ `empty:false`**（⛔ 不是 `no_match`）—— "服务端 4 个只读接口都还没部署"这种情形下
+ *     回 `empty:true + no_match` 就是最典型的假绿：读的人会以为"真的没有在途码"；
+ *   · `local`（本机许可/审计附注）**只影响"有没有内容"，不算"答得上一节"** —— 否则"远端一节都没读到"
+ *     会因为本机那行附注而变成 `empty:true`。
+ */
+export function computeEmpty(sections = {}) {
+  let anyAnswerable = false
+  for (const [name, s] of Object.entries(sections)) {
+    if (!s || s.available === false) continue
+    if (name === 'local') {
+      if (s.present === true || (s.activations && (s.activations.count || 0) > 0)) return false
+      continue
+    }
+    anyAnswerable = true
+    if (name === 'seats') { if ((s.principals || []).length > 0) return false; continue }
+    if (name === 'device') { if ((s.found || 0) > 0) return false; continue }
+    if ((s.count || 0) > 0) return false
+  }
+  return anyAnswerable
+}
+
+// ── 参数解析（表来自本文件；⛔ 未知参数一律拒绝，不静默吃掉别人的参数）──────────────
+/**
+ * @returns {{ok:true, values:object, repeat:object, bools:Set<string>} | {ok:false, code:number, reason:string, error:string}}
+ */
+export function parseOpsArgs(argv = []) {
+  const values = {}
+  const repeat = {}
+  const bools = new Set()
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--json') continue                     // CLI 层开关（决定打印形状），不是本层的参数
+    if (OPS_BOOL_FLAGS.includes(a)) { bools.add(a); continue }
+    if (OPS_VALUE_FLAGS.includes(a) || OPS_REPEAT_FLAGS.includes(a)) {
+      const v = argv[i + 1]
+      if (v === undefined || String(v).startsWith('--')) {
+        return { ok: false, code: 2, reason: 'usage_error', error: `参数 ${a} 缺值（用法见 \`argent license ops --help\`）` }
+      }
+      if (OPS_REPEAT_FLAGS.includes(a)) (repeat[a] ||= []).push(v)
+      else values[a] = v
+      i++
+      continue
+    }
+    return { ok: false, code: 2, reason: 'usage_error', error: `未知参数：${a}（用法见 \`argent license ops --help\`）` }
+  }
+  return { ok: true, values, repeat, bools }
+}
+
+// ── 凭证（纪律③）────────────────────────────────────────────────────────────
+const OPS_TOKEN_KEYS = ['ARGENT_OPS_TOKEN', 'OPS_TOKEN']
+
+/** 一个文件是不是"仅属主可读写"（0600；symlink 按目标判 —— `statSync` 本就跟链接）。 */
+function modeOf(path) {
+  try { return statSync(path).mode & 0o777 } catch { return null }
+}
+
+/** 从 `KEY=VALUE` 文本里取第一个命中的键（去掉引号/空白；**不回显内容**）。 */
+export function tokenFromEnvText(text, keys = OPS_TOKEN_KEYS) {
+  for (const line of String(text || '').split('\n')) {
+    const s = line.trim()
+    if (!s || s.startsWith('#')) continue
+    const i = s.indexOf('=')
+    if (i < 0) continue
+    const k = s.slice(0, i).trim().replace(/^export\s+/, '')
+    if (!keys.includes(k)) continue
+    const v = s.slice(i + 1).trim().replace(/^["']|["']$/g, '')
+    if (v) return { key: k, token: v }
+  }
+  return null
+}
+
+/**
+ * 解析管理员 JWT（**只读视图用**）。优先级：`--token-file` > `$ARGENT_OPS_TOKEN` > `$ARGENT_OPS_TOKEN_FILE`
+ * > `<数据目录>/*.env`（字典序，命中即止）。文件**必须是 0600** —— 否则拒用（凭证不得被同机其它用户读到）。
+ * ⛔ 返回值里的 `token` 只进 Authorization 头，**绝不进任何回显**。
+ */
+export function resolveOpsToken({ flag = null, env = {}, dataDir = '' } = {}) {
+  const miss = { ok: false, token: '', source: '', file: null, mode: null }
+  const fromFile = (p, source) => {
+    const path = resolve(String(p))
+    if (!existsSync(path)) return { ...miss, reason: 'usage_error', source, error: `token 文件不存在：${path}` }
+    const mode = modeOf(path)
+    if (mode === null) return { ...miss, reason: 'usage_error', source, file: path, error: `token 文件读不到：${path}` }
+    if ((mode & 0o077) !== 0) {
+      return {
+        ...miss, reason: 'usage_error', source, file: path, mode,
+        error: `${path} 的权限是 0${mode.toString(8)}（同组/他人可读）⇒ **拒用**。凭证只从 0600 的文件读：`
+          + `\`chmod 600 ${path}\` 后重试（⛔ 不要把 token 抄进命令行参数 —— 那会进 shell 历史与进程列表）`,
+      }
+    }
+    let text = ''
+    try { text = readFileSync(path, 'utf8') } catch (e) {
+      return { ...miss, reason: 'usage_error', source, file: path, mode, error: `token 文件读不出来：${(e && e.message) || e}` }
+    }
+    const hit = tokenFromEnvText(text)
+    if (!hit) {
+      return {
+        ...miss, reason: 'usage_error', source, file: path, mode,
+        error: `${path} 里没有 ${OPS_TOKEN_KEYS.join(' / ')}（只认这两个键；文件的其它内容**没有被使用**）`,
+      }
+    }
+    return { ok: true, token: hit.token, source, file: path, mode, key: hit.key }
+  }
+
+  if (flag) return fromFile(flag, 'flag:--token-file')
+  const fromEnv = String(env.ARGENT_OPS_TOKEN || '').trim()
+  if (fromEnv) return { ok: true, token: fromEnv, source: 'env:ARGENT_OPS_TOKEN', file: null, mode: null, key: 'ARGENT_OPS_TOKEN' }
+  const envFile = String(env.ARGENT_OPS_TOKEN_FILE || '').trim()
+  if (envFile) return fromFile(envFile, 'env:ARGENT_OPS_TOKEN_FILE')
+  // `<数据目录>/*.env`：只扫描**文件名以 .env 结尾**的（含 symlink；按目标判权限）
+  if (dataDir && existsSync(dataDir)) {
+    let names = []
+    try { names = readdirSync(dataDir).filter((n) => n.endsWith('.env')).sort() } catch { names = [] }
+    for (const n of names) {
+      const p = join(String(dataDir), n)
+      let text = ''
+      try { text = readFileSync(p, 'utf8') } catch { continue }
+      if (!tokenFromEnvText(text)) continue          // 不含这两个键 ⇒ 与它无关（内容不外传）
+      return fromFile(p, `datadir:${n}`)
+    }
+  }
+  return {
+    ...miss, reason: 'usage_error',
+    error: `没有管理员 token（只读视图要它才能调服务端只读接口）：用 \`--token-file <600 的文件>\`，或设 `
+      + `\`ARGENT_OPS_TOKEN\`/\`ARGENT_OPS_TOKEN_FILE\`，或把 \`ARGENT_OPS_TOKEN=…\` 放进 <数据目录>/*.env（600）。`
+      + `⛔ 本仓库不直连生产库、也不接受把 token 写在命令行上（会进 shell 历史）。`,
+  }
+}
+
+// ── 快照读取 + 字段契约（陷阱守卫）─────────────────────────────────────────────
+/** 读一份只读快照（显式路径不存在 ⇒ 2；不是 JSON/不是对象 ⇒ 2 —— 与 `license verify --file` 同口径）。 */
+export function loadOpsSnapshot(path) {
+  const p = resolve(String(path))
+  if (!existsSync(p)) return { ok: false, code: 2, reason: 'usage_error', error: `--from 指向的快照不存在：${p}` }
+  let text = ''
+  try { text = readFileSync(p, 'utf8') } catch (e) {
+    return { ok: false, code: 2, reason: 'usage_error', error: `--from 的快照读不出来（${p}）：${(e && e.message) || e}` }
+  }
+  let data = null
+  try { data = JSON.parse(text) } catch (e) {
+    return { ok: false, code: 2, reason: 'usage_error', error: `--from 的快照不是 JSON（${p}）：${(e && e.message) || e}` }
+  }
+  if (!data || typeof data !== 'object' || Array.isArray(data)) {
+    return { ok: false, code: 2, reason: 'usage_error', error: `--from 的快照顶层必须是对象（形如 {codes,events,accounts}）：${p}` }
+  }
+  return { ok: true, path: p, data }
+}
+
+/**
+ * 字段契约检查（**假绿守卫**）：集合非空时，域必需字段必须在**至少一条**记录里出现。
+ * @returns {{ok:true, missing:[], profile:object} | {ok:false, missing:string[], hint:string}}
+ */
+export function checkOpsFields({ codes = [], events = [], accounts = [], devices = [] } = {}) {
+  const cols = { codes, events, accounts, devices }
+  const missing = []
+  const profile = {}
+  for (const [name, rows] of Object.entries(cols)) {
+    const keys = new Set()
+    for (const r of rows) if (r && typeof r === 'object') for (const k of Object.keys(r)) keys.add(k)
+    profile[name] = [...keys].sort()
+    const required = OPS_REQUIRED_FIELDS[name] || []
+    if (!rows.length) continue                        // 空集合没有"字段"可言（空是合法结论，不是缺字段）
+    for (const f of required) if (!keys.has(f)) missing.push(`${name}[].${f}`)
+  }
+  if (!missing.length) return { ok: true, missing: [], profile }
+  const bare = missing.map((m) => m.split('.').pop())
+  const hints = [...new Set(bare.map((f) => OPS_FIELD_HINTS[f]).filter(Boolean))]
+  return {
+    ok: false, missing, profile,
+    hint: `数据源缺**域必需字段**：${missing.join('、')}。`
+      + (hints.length ? `\n   ${hints.join('\n   ')}` : '')
+      + '\n   ⛔ 本视图**不会**把"字段不在"降级成"计数为 0"（那正是把"有在途码"误读成"没有"的假绿）。',
+  }
+}
+
+// ── 服务端行的**字段契约**（服务端契约 §0 的镜像；字段名按**服务端**的叫法）────────────
+/**
+ * 服务端行级必需字段（⛔ 与 `OPS_REQUIRED_FIELDS` **不同名**：服务端设备记录给的是 `codePrefix`（12 位），
+ * 不是 64hex 全码 —— 这正是映射①）。缺席时的 `missingFields` 用**服务端口径**的路径串
+ * （`items[].state` / `items[].devices[].codePrefix`），与服务端自己的 `field_missing` 逐字可对。
+ * ⚠️ 服务端侧两处**刻意不报**（`License.devices` 键缺席 ⇒ 空数组；`License.seats` 缺席 ⇒ 模型缺省 1）
+ * 在这里**照样不报** —— 那两处有唯一权威兜底，报错只会造成假红（见服务端契约 §0）。
+ */
+export const OPS_SERVER_FIELDS = {
+  codes: ['codePrefix', 'state'],
+  events: ['at', 'action', 'result'],
+  accounts: ['userId', 'devices'],
+  devices: ['codePrefix'],
+}
+
+/** 服务端字段 → `OPS_FIELD_HINTS` 的键（文案只有一份，两处共用）。 */
+export const OPS_SERVER_FIELD_HINTS = {
+  'items[].codePrefix': 'codePrefix',
+  'items[].state': 'state',
+  'items[].at': 'at',
+  'items[].action': 'action',
+  'items[].result': 'result',
+  'items[].userId': 'userId',
+  'items[].devices': 'devices',
+  'items[].devices[].codePrefix': 'devicesCodePrefix',
+}
+
+/**
+ * 服务端响应 → **行级字段契约检查**（客户端侧的镜像守卫；`items` 为空是合法结论，不报缺字段）。
+ * @returns {{ok:true, missing:[]} | {ok:false, missing:string[], hint:string}}
+ */
+export function checkServerRows({ codes = [], events = [], accounts = [], devices = [] } = {}) {
+  const cols = [
+    ['items[]', codes, OPS_SERVER_FIELDS.codes],
+    ['items[]', events, OPS_SERVER_FIELDS.events],
+    ['items[]', accounts, OPS_SERVER_FIELDS.accounts],
+    ['items[].devices[]', devices, OPS_SERVER_FIELDS.devices],
+  ]
+  const missing = []
+  for (const [prefix, rows, required] of cols) {
+    if (!rows.length) continue
+    const keys = new Set()
+    for (const r of rows) if (r && typeof r === 'object') for (const k of Object.keys(r)) keys.add(k)
+    for (const f of required) if (!keys.has(f)) missing.push(`${prefix}.${f}`)
+  }
+  const uniq = [...new Set(missing)]
+  if (!uniq.length) return { ok: true, missing: [] }
+  const hints = [...new Set(uniq.map((m) => OPS_FIELD_HINTS[OPS_SERVER_FIELD_HINTS[m]]).filter(Boolean))]
+  return {
+    ok: false, missing: uniq,
+    hint: `服务端响应缺**行级必需字段**：${uniq.join('、')}。`
+      + (hints.length ? `\n   ${hints.join('\n   ')}` : '')
+      + '\n   ⛔ 本视图**不会**把"字段不在"降级成"计数为 0"（服务端契约 §0：这种情形它回 200 但 `ok:false`，'
+      + '判定只看 `ok`，⛔ 不看状态码）。',
+  }
+}
+
+// ── 服务端响应 → 客户端形状（**四处映射陷阱的唯一落点**）──────────────────────────
+/**
+ * 映射①：`codes-list.items` → `codes`（`state` 原样透传；`deviceCodePrefix` 只回 12 位）。
+ * ⛔ 白名单式投影：服务端哪天多回一个字段也不会漏进输出（PII/明文码的防线在这里，不靠服务端单侧）。
+ */
+export function mapServerCodes(items = []) {
+  return (Array.isArray(items) ? items : []).filter((r) => r && typeof r === 'object').map((r) => ({
+    codePrefix: r.codePrefix ?? null,
+    state: r.state ?? null,
+    intent: r.intent ?? null,
+    expiresAt: r.expiresAt ?? null,
+    failCount: num(r.failCount) || 0,
+    deviceCodePrefix: r.deviceCodePrefix ? echoDevice(r.deviceCodePrefix) : null,
+  }))
+}
+
+/** 映射（时间线）：`events.items` → `events`（**只** at/action/result/codePrefix 四个字段）。 */
+export function mapServerEvents(items = []) {
+  return (Array.isArray(items) ? items : []).filter((r) => r && typeof r === 'object').map((r) => ({
+    at: r.at ?? null, action: r.action ?? null, result: r.result ?? null, codePrefix: r.codePrefix ?? null,
+  }))
+}
+
+/**
+ * 映射①②：`seats.items` → `accounts`：`devices[].codePrefix → code`（值仍是 **12 位前缀**，
+ * ⛔ **不把 64hex 全码补回来**）；`deviceLimitSource` 的**机器值**留在 `deviceLimitSourceRaw`，
+ * 展示串（`'deviceLimit 字段'`｜`'seats（缺省跟随 seats）'`）由客户端拼。
+ */
+export function mapServerSeats(items = []) {
+  return (Array.isArray(items) ? items : []).filter((r) => r && typeof r === 'object').map((r) => {
+    const src = r.deviceLimitSource === 'deviceLimit' || r.deviceLimitSource === 'seats' ? r.deviceLimitSource : null
+    return {
+      userId: r.userId ?? null,
+      seats: num(r.seats),
+      deviceLimit: num(r.deviceLimit),
+      deviceLimitSourceRaw: src,
+      serverUsed: num(r.used),
+      serverFree: num(r.free),
+      devices: (Array.isArray(r.devices) ? r.devices : []).filter((d) => d && typeof d === 'object')
+        .map((d) => ({ code: d.codePrefix ?? null, releasedAt: d.releasedAt ?? null, boundAt: d.boundAt ?? null })),
+    }
+  })
+}
+
+/** 映射②：`deviceLimitSource` 机器值 → 展示串（服务端契约 §3 的文案规定）。 */
+export const seatLimitSourceText = (raw, fallback) => (raw && OPS_SEAT_LIMIT_SOURCE_TEXT[raw]) || fallback
+
+/**
+ * 映射③：`devices/:codePrefix` 响应 → `device` 一节。
+ * ⚠️ **命中处数看服务端 `total`**（`empty:true ⇔ total === 0`），`count` 只是本页条数（超 200 时 `hasMore`）。
+ */
+export function mapServerDevice(body = {}, { query = '' } = {}) {
+  const items = (Array.isArray(body.items) ? body.items : []).filter((r) => r && typeof r === 'object')
+  const byUser = new Map()
+  for (const r of items) {
+    const k = String(r.userId ?? '(未知)')
+    const list = byUser.get(k) || []
+    list.push({
+      codePrefix: r.codePrefix ? echoDevice(r.codePrefix) : null,
+      licenseId: r.licenseId ?? null,
+      releasedAt: r.releasedAt ?? null,
+      boundAt: r.boundAt ?? null,
+    })
+    byUser.set(k, list)
+  }
+  const total = num(body.total)
+  return {
+    available: true,
+    coverage: body.hasMore === true ? 'page-only' : 'full',
+    query: body.query ? echoDevice(body.query) : echoDevice(query),
+    found: total === null ? items.length : total,          // ⚠️ 映射③：判定用 total（含已释放的绑定）
+    total: total === null ? items.length : total,
+    count: items.length,
+    empty: body.empty === true,
+    hasMore: body.hasMore === true,
+    codeMatches: [],
+    accounts: [...byUser.entries()].map(([userId, devices]) => ({ userId, devices })),
+    server: { endpoint: 'devices/{codePrefix}', note: '含**已释放**的绑定（`releasedAt` 非空 = 曾挂过）' },
+    definition: '**设备归属**：服务端回"这个码曾挂过哪些账号"（含已释放）。'
+      + '命中处数看 `total`（`empty:true ⇔ total === 0` ⇒ 查无此码是**空集**，不是错误/404）；'
+      + `⛔ 设备码只回前 ${OPS_DEVICE_ECHO} 位。`,
+  }
+}
+
+// ── 分析（纯函数：喂数据 → 五节；夹具/内存桩直接调它）────────────────────────────
+/** 码的到期时刻：优先 `expiresAt`；缺则 `issuedAt + ttlMinutes`（缺 `ttlMinutes` 用客户端的 TTL 常量）。 */
+
+export function expiryMsOf(code) {
+  const e = parseTime(code && code.expiresAt)
+  if (e !== null) return e
+  const i = parseTime(code && code.issuedAt)
+  if (i === null) return null
+  const ttl = num(code && code.ttlMinutes)
+  return i + (ttl && ttl > 0 ? ttl : ACTIVATION_CODE_TTL_MINUTES) * 60000
+}
+
+/** 在途码一条（含 TTL 剩余/超期分钟；`overdueMinutes > 0` 即"超 TTL 未终态"）。 */
+export function inflightEntry(code, now) {
+  const exp = expiryMsOf(code)
+  const left = exp === null ? null : Math.round((exp - now) / 60000)
+  const overdue = left !== null && left < -OPS_TTL_GRACE_MINUTES ? -left : 0
+  return {
+    codePrefix: code.codePrefix,
+    state: code.state,
+    intent: code.intent ?? null,
+    issuedAt: code.issuedAt ?? null,
+    expiresAt: code.expiresAt ?? iso(exp),
+    ttlLeftMinutes: left,
+    overdueMinutes: overdue,
+    failCount: num(code.failCount) || 0,
+    lockedUntil: code.lockedUntil ?? null,
+    userId: code.userId ?? code.issuedBy ?? null,
+    deviceCodePrefix: code.deviceCodePrefix ? echoDevice(code.deviceCodePrefix)
+      : (code.deviceCode ? echoDevice(code.deviceCode) : null),
+  }
+}
+
+/**
+ * 五节分析（**纯函数**，不读文件/不发网络 ⇒ 夹具与内存桩直接调）。
+ * @param {{codes?:Array, events?:Array, accounts?:Array}} data
+ * @param {{now?:number, days?:number, filters?:Array<{field:string,value:string}>, device?:string}} [opts]
+ */
+export function analyzeOps(data = {}, opts = {}) {
+  const now = Number.isFinite(opts.now) ? opts.now : Date.now()
+  const days = Number.isFinite(opts.days) ? opts.days : OPS_DEFAULT_DAYS
+  const filters = Array.isArray(opts.filters) ? opts.filters : []
+  const deviceQuery = String(opts.device || '').trim().toLowerCase()
+
+  const codes = Array.isArray(data.codes) ? data.codes.filter((c) => c && typeof c === 'object') : []
+  const events = Array.isArray(data.events) ? data.events.filter((e) => e && typeof e === 'object') : []
+  const accounts = Array.isArray(data.accounts) ? data.accounts.filter((a) => a && typeof a === 'object') : []
+
+  const match = (c) => filters.every((f) => String(c[f.field] ?? '') === String(f.value))
+  const filtered = codes.filter(match)
+
+  // ① 在途码
+  const inflightAll = filtered.filter((c) => OPS_INFLIGHT_STATES.includes(c.state))
+  const inflight = inflightAll.map((c) => inflightEntry(c, now))
+    .sort((a, b) => String(a.expiresAt || '').localeCompare(String(b.expiresAt || '')))
+
+  // ② 失败码（failCount>0 或 revoked）+ 拒绝事件计数（口径 = 数据源里的全部事件，不随 --days 变）
+  const failedCodes = filtered
+    .filter((c) => (num(c.failCount) || 0) > 0 || c.state === 'revoked')
+    .map((c) => ({
+      codePrefix: c.codePrefix, state: c.state, failCount: num(c.failCount) || 0,
+      lockedUntil: c.lockedUntil ?? null, userId: c.userId ?? c.issuedBy ?? null,
+    }))
+  const deniedCounts = {}
+  for (const e of events) if (String(e.action || '').endsWith('_denied')) deniedCounts[e.action] = (deniedCounts[e.action] || 0) + 1
+  const byState = {}
+  for (const c of failedCodes) byState[c.state || '(未知)'] = (byState[c.state || '(未知)'] || 0) + 1
+
+  // ③ 时间线（近 N 天；**只** action/result/codePrefix —— 先过滤后截断，D1 的教训）
+  const since = now - days * 86400000
+  const inWindow = events
+    .map((e) => ({ at: e.at ?? null, ms: parseTime(e.at), action: e.action ?? null, result: e.result ?? null, codePrefix: e.codePrefix ?? null }))
+    .filter((e) => e.ms !== null && e.ms >= since && e.ms <= now)
+    .sort((a, b) => a.ms - b.ms)
+  const timeline = inWindow.slice(-OPS_MAX_EVENTS).map(({ ms, ...rest }) => { void ms; return rest })
+  const counts = {}
+  for (const e of inWindow) { const k = `${e.action}/${e.result}`; counts[k] = (counts[k] || 0) + 1 }
+  // 未知动作**不判红**（服务端可能新增动作），只单独列出来给运营看（`unknownActions`）
+  const unknownActions = [...new Set(events.map((e) => e.action).filter((a) => a && !OPS_EVENT_ACTIONS.includes(a)))]
+
+  // ④ 席位账目（`used` **算出来**：`releasedAt` 为空的设备码去重数；`deviceLimit` 缺省跟随 `seats`）
+  const seatMismatches = []
+  const seatAccounts = accounts.map((a) => {
+    const devices = (Array.isArray(a.devices) ? a.devices : []).filter((d) => d && typeof d === 'object')
+    const active = devices.filter((d) => !d.releasedAt)
+    const used = new Set(active.map((d) => String(d.code || ''))).size
+    const dl = num(a.deviceLimit)
+    const deviceLimit = dl === null ? num(a.seats) : dl
+    const rawSource = a.deviceLimitSourceRaw === 'deviceLimit' || a.deviceLimitSourceRaw === 'seats' ? a.deviceLimitSourceRaw : null
+    // ⚠️ 数据源自己也回了 `used`（服务端席位账目就有）⇒ **再算一遍并比对**：
+    //    已释放的设备**不**计入 `used`（映射②/陷阱②）；两边不一致 ⇒ 异常 `seat_used_mismatch`（⛔ 不盲信任一边）。
+    const serverUsed = num(a.serverUsed)
+    if (serverUsed !== null && serverUsed !== used) {
+      seatMismatches.push({
+        id: 'seat_used_mismatch', severity: 'alert', subject: a.userId ?? '(未知账号)',
+        detail: `席位口径不一致：数据源回 \`used=${serverUsed}\`，本视图按"**\`releasedAt\` 为空**的设备码去重"算出 \`used=${used}\``
+          + `（该账号 ${devices.length} 条设备记录，其中已释放 ${devices.length - active.length} 条不占席位）`,
+        needs: '核对设备记录：已释放（`releasedAt` 非空）的绑定**不占席位**；'
+          + '若两边只差"同码重复/前缀去重"，以设备记录为准（本视图口径见 `definition.seat`）',
+      })
+    }
+    return {
+      userId: a.userId, seats: num(a.seats), deviceLimit,
+      deviceLimitSourceRaw: rawSource,
+      deviceLimitSource: seatLimitSourceText(rawSource, dl === null ? 'seats（缺省跟随 seats）' : 'deviceLimit 字段'),
+      used, free: deviceLimit === null ? null : Math.max(0, deviceLimit - used),
+      devices: devices.map((d) => ({ codePrefix: echoDevice(d.code), releasedAt: d.releasedAt ?? null, boundAt: d.boundAt ?? null })),
+    }
+  })
+  const seatTotals = {
+    accounts: seatAccounts.length,
+    seats: seatAccounts.reduce((n, a) => n + (a.seats || 0), 0),
+    deviceLimit: seatAccounts.reduce((n, a) => n + (a.deviceLimit || 0), 0),
+    used: seatAccounts.reduce((n, a) => n + a.used, 0),
+    free: seatAccounts.reduce((n, a) => n + (a.free || 0), 0),
+  }
+
+  // ⑤ 异常清单（**只看不判**：不影响任何写操作的放行，见文件头"与判断面清单的关系"）
+  const anomalies = []
+  for (const c of inflight) {
+    if (c.overdueMinutes > 0) {
+      anomalies.push({
+        id: 'inflight_over_ttl', severity: 'warn', subject: c.codePrefix,
+        detail: `在途码超 TTL 未终态：state=${c.state}，超期 ${c.overdueMinutes} 分钟（宽限 ${OPS_TTL_GRACE_MINUTES} 分钟）`,
+        needs: '让服务端把它终态化（expired/redeemed）或核对 TTL 判据；⛔ 本视图不会替它改库',
+      })
+    }
+  }
+  const byDevice = new Map()
+  for (const a of seatAccounts) {
+    for (const d of a.devices) {
+      if (d.releasedAt) continue
+      const k = String(d.codePrefix || '')
+      if (!k) continue
+      const list = byDevice.get(k) || []
+      list.push(a.userId)
+      byDevice.set(k, list)
+    }
+  }
+  for (const [codePrefix, users] of byDevice) {
+    const uniq = [...new Set(users)]
+    if (uniq.length > 1) {
+      anomalies.push({
+        id: 'device_multi_account', severity: 'alert', subject: codePrefix,
+        detail: `同一设备码挂在 ${uniq.length} 个账号名下且 \`releasedAt\` 均为空：${uniq.join('、')}（设备码只显示前 ${OPS_DEVICE_ECHO} 位）`,
+        needs: '确认哪台机器该保留：走受支持的释放端点（POST /api/argent/license/release-device）后重签；'
+          + '⛔ 只读视图**不会**代触发释放（该端点的 200 路径在生产库尚未跑过）',
+      })
+    }
+  }
+  for (const a of seatAccounts) {
+    if (a.deviceLimit !== null && a.used > a.deviceLimit) {
+      anomalies.push({
+        id: 'device_over_limit', severity: 'alert', subject: a.userId,
+        detail: `未释放设备数 ${a.used} 超过 deviceLimit ${a.deviceLimit}（seats ${a.seats}）—— 席位账目与设备记录不自洽`,
+        needs: '核对该账号的设备记录（是否有漏写 releasedAt 的僵尸绑定）',
+      })
+    }
+  }
+  // 映射②的守卫：数据源回的 `used` 与"按 releasedAt 去重算出来"的必须一致（⛔ 不盲信任一边）
+  for (const m of seatMismatches) anomalies.push({ ...m, needs: m.needs + `（${SEAT_DEFINITION}）` })
+  const releaseRejected = events.filter((e) => e.action === 'device_release' && e.result === 'rejected')
+  if (releaseRejected.length) {
+    anomalies.push({
+      id: 'release_probe_rejected', severity: 'alert', subject: 'device_release/rejected',
+      detail: `审计里出现 ${releaseRejected.length} 条 \`device_release/rejected\`（探针痕迹）：`
+        + `该端点的 **200 成功路径在生产库仍未跑过**（O2/L2 的存量条件）`,
+      needs: '先按 L2 判据做一次**双验收**的真释放（端点在位 + 200 + 审计行），再据此判断拒绝是权限还是实现问题',
+    })
+  }
+  for (const [action, n] of Object.entries(deniedCounts)) {
+    if (n < OPS_DENIED_REPEAT) continue
+    const prefixes = [...new Set(events.filter((e) => e.action === action).map((e) => e.codePrefix).filter(Boolean))]
+    anomalies.push({
+      id: 'denied_repeat', severity: 'warn', subject: action,
+      detail: `${action} 出现 ${n} 次（≥${OPS_DENIED_REPEAT}）${prefixes.length ? `，涉及前缀 ${prefixes.slice(0, 5).join('、')}` : ''}`
+        + ' —— 可能是锁定/双花/转发，也可能只是运营反复试',
+      needs: '按前缀逐个 `GET /api/argent/license/activation-code/:prefix` 看 state/failCount/lockedUntil',
+    })
+  }
+
+  // ⑥ 设备归属（`--device`；答 O2 的第三个问题）
+  let device = null
+  if (deviceQuery) {
+    const hitCode = (v) => String(v || '').toLowerCase().startsWith(deviceQuery)
+    const devMatches = []
+    for (const c of codes) {
+      const dc = c.deviceCode || c.deviceCodePrefix
+      if (dc && hitCode(dc)) devMatches.push({ codePrefix: c.codePrefix, state: c.state, deviceCodePrefix: echoDevice(dc) })
+    }
+    const devAccounts = seatAccounts
+      .map((a) => ({ userId: a.userId, devices: a.devices.filter((d) => hitCode(d.codePrefix)) }))
+      .filter((a) => a.devices.length)
+    device = { available: true, query: echoDevice(deviceQuery), codeMatches: devMatches, accounts: devAccounts, found: devMatches.length + devAccounts.length }
+  }
+
+  const empty = inflight.length === 0 && failedCodes.length === 0 && timeline.length === 0
+    && seatAccounts.length === 0 && anomalies.length === 0 && (!device || device.found === 0)
+
+  return {
+    now: iso(now), days, since: iso(since),
+    filters: filters.map((f) => `${f.field}=${f.value}`),
+    inflight: { available: true, coverage: 'full', states: [...OPS_INFLIGHT_STATES], count: inflight.length, codes: inflight },
+    failures: {
+      available: true, coverage: 'full', count: failedCodes.length, byState, byReason: deniedCounts,
+      scope: '数据源内的全部事件（不随 --days 收窄）', codes: failedCodes,
+    },
+    timeline: {
+      available: true, coverage: 'full', days, from: iso(since), to: iso(now), count: timeline.length,
+      returned: timeline.length, scanned: inWindow.length, counts, events: timeline, unknownActions,
+    },
+    seats: { available: true, coverage: 'full', principals: seatAccounts, totals: seatTotals, definition: SEAT_DEFINITION },
+    anomalies: { available: true, count: anomalies.length, items: anomalies },
+    ...(device ? { device } : {}),
+    empty,
+  }
+}
+
+/** 席位口径的**唯一文案落点**（陷阱②；文档只引用不复述）。 */
+export const SEAT_DEFINITION = '席位 = `seats`（许可声明的席位数）；未释放设备数 `used` = 设备记录里 **`releasedAt` 为空**的设备码**去重**数；'
+  + '`deviceLimit`（允许绑定的设备上限）缺省**跟随 `seats`**。⛔ `used` **不是**存储字段 —— 直接查它会得到空/错值（O2 陷阱②）。'
+
+// ── 本机只读产物（默认数据源）────────────────────────────────────────────────
+/** 读本机许可声明 + 本机激活审计（**只读**；审计里本来就只有 `codePrefix`，不会有明文码）。 */
+export function readLocalOps({ env = {}, dataDir, now = Date.now() } = {}) {
+  const dir = dataDir || resolveDataDir({ env }).dir
+  const v = licenseVerdict({ env, now })
+  const src = SOURCES.find((s) => s.id === 'license-activation')
+  const audit = src ? readSource(dir, src) : { exists: false, rows: [], file: null, error: null }
+  const activations = (audit.rows || []).map((r) => {
+    const d = r.data || {}
+    const a = d.activation || {}
+    return {
+      at: d.at ?? r.at ?? null,
+      ok: d.ok === true,
+      reason: d.reason ?? null,
+      codePrefix: a.codePrefix ?? null,
+      deviceCodePrefix: d.device && d.device.code ? echoDevice(d.device.code) : null,
+      server: d.server && d.server.host ? d.server.host : null,
+    }
+  })
+  return {
+    dataDir: dir,
+    license: {
+      available: true,
+      licenseFile: v.path,
+      state: v.state,
+      reason: v.reason ?? null,
+      present: v.reason !== 'missing' && v.reason !== 'unreadable',
+      userId: v.userId || null,
+      seats: v.seats ?? null,
+      capabilities: v.capabilities || [],
+      verticals: v.verticals || [],
+      expiresAt: v.expiresAt || null,
+      graceDays: v.graceDays ?? null,
+      signatureVersion: v.signatureVersion === 2 ? 2 : (v.signatureVersion === 1 ? 1 : null),
+      deviceBinding: v.device ? v.device.binding : null,
+      deviceCodePrefix: v.device && v.device.code ? echoDevice(v.device.code) : null,
+    },
+    activations: { available: true, file: audit.file, exists: audit.exists === true, error: audit.error || null, count: activations.length, rows: activations },
+    prefixes: [...new Set(activations.map((a) => a.codePrefix).filter(Boolean))],
+  }
+}
+
+// ── 服务端只读接口（只发 GET）───────────────────────────────────────────────
+/**
+ * **唯一网络出口**：只发 `GET`（method 硬编码 —— 想写也写不了），带管理员 JWT，超时用 activate 的同一判据。
+ * @returns {Promise<{status:number|null, body:object|null, network:string|null, error:string}>}
+ */
+export async function httpGet({ endpoint, token, timeoutMs, fetchImpl }) {
+  const ctl = new AbortController()
+  const timer = setTimeout(() => ctl.abort(), timeoutMs)
+  try {
+    const res = await fetchImpl(endpoint, {
+      method: 'GET',                                    // ⛔ 硬编码：本视图绝不发写方法
+      headers: { accept: 'application/json', authorization: `Bearer ${token}` },
+      signal: ctl.signal,
+    })
+    const text = String(await res.text())
+    let body = null
+    try { body = JSON.parse(text) } catch { body = null }
+    return { status: Number(res.status), body, 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)
+  }
+}
+
+/**
+ * 服务端响应 → 码记录（**形状校验也在陷阱守卫里**：返回 `status` 而不是 `state` ⇒ 响亮失败）。
+ * @returns {{ok:true, code:object} | {ok:false, code:number, reason:string, error:string}}
+ */
+export function normalizeServerCode(body, { prefix = '', httpStatus = 0 } = {}) {
+  if (!body || typeof body !== 'object') {
+    return { ok: false, code: 1, reason: 'bad_output', error: `端点返回的响应不可解析（HTTP ${httpStatus}，prefix ${prefix}）` }
+  }
+  if (body.ok !== true) {
+    const reason = String(body.reason || '').trim()
+    if (httpStatus === 404 || reason === 'code_unknown') {
+      return { ok: true, code: { codePrefix: prefix, state: null, unknown: true, serverReason: reason || 'code_unknown' } }
+    }
+    return { ok: true, code: { codePrefix: prefix, state: null, error: reason || `HTTP ${httpStatus}` } }
+  }
+  if (!('state' in body)) {
+    const trap = 'status' in body
+      ? '响应里出现的是 `status` —— 码状态字段是 **`state`**（O2 陷阱①）；按 `status` 读**恒空**，会把"有在途码"误读成"没有"'
+      : '响应里既没有 `state`（`ActivationCodeStatus.state` 是必填项）'
+    return {
+      ok: false, code: 2, reason: 'field_missing',
+      error: `GET ${CODE_STATUS_PATH}${prefix} 的响应缺 \`state\`：${trap}。⛔ 本视图不会把它当成"没有在途码"。`,
+    }
+  }
+  return {
+    ok: true,
+    code: {
+      codePrefix: body.codePrefix || prefix, state: body.state, intent: body.intent ?? null,
+      issuedAt: body.issuedAt ?? null, expiresAt: body.expiresAt ?? null, redeemedAt: body.redeemedAt ?? null,
+      failCount: num(body.failCount) || 0, lockedUntil: body.lockedUntil ?? null,
+      userId: body.issuedBy ?? null, deviceCodePrefix: body.deviceCodePrefix ?? null, licenseId: body.licenseId ?? null,
+    },
+  }
+}
+
+/**
+ * **一次只读取数的统一出口**（4 个新接口 + `code-status` 都走它）：只发 GET（`httpGet` 里 method 硬编码），
+ * 并把"服务端**明确**说不行"的情形**响亮**映射成 top-level 失败（A2/A3：exit 2 + 明确 reason），
+ * 把"路由不在"（404 且响应体**不是**本服务信封）留给**节级** `endpoint_missing`（⛔ 不是空集）。
+ *
+ * 服务端契约（`whyshu-svr/docs/ops/license-ops-readonly.md` §0）：
+ *   · `405 + Allow: GET` = 动词不对（本客户端只发 GET ⇒ 见到它就说明链路不对）⇒ `method_not_allowed`（exit 2）
+ *   · `400 field_unknown`（尤其 `?status=`）= 参数名不存在 ⇒ **绝不静默当空集** ⇒ `field_unknown`（exit 2）
+ *   · `429` = 6 次/分限流 ⇒ `rate_limited`（exit 2，附"等 60 秒"的处置）
+ *   · `200 {ok:false, reason:"field_missing"}` = 行级必需字段缺席 ⇒ `field_missing`（exit 2，回显 missingFields）
+ *
+ * @returns {Promise<{ok:true, body:object, status:number} | {ok:false, kind:string, exit:number, reason:string, error:string, httpStatus:number|null, body:object|null, missingFields?:string[]}>}
+ */
+export async function opsServerGet({ id, relPath, baseUrl, token, timeoutMs, fetchImpl, observed = null }) {
+  const url = endpointOf(baseUrl, relPath)
+  const r = await httpGet({ endpoint: url, token, timeoutMs, fetchImpl })
+  const body = r.body && typeof r.body === 'object' ? r.body : null
+  const enveloped = Boolean(body && typeof body.reason === 'string')
+  if (observed && typeof observed.set === 'function') observed.set(id, { httpStatus: r.status, body, url, network: r.network })
+  const tag = `GET ${url}`
+  if (r.network) {
+    return {
+      ok: false, kind: r.network, httpStatus: null, body: null, exit: 1,
+      reason: r.network === 'timeout' ? 'activation_timeout' : 'activation_server_unreachable',
+      error: `${r.error}（服务端只读接口是**唯一**的远端数据源 ⇒ 读不到就没有结论，⛔ 不降级成"没有在途码"）`,
+    }
+  }
+  const s = Number(r.status)
+  if (s === 401 || s === 403) {
+    return {
+      ok: false, kind: 'admin_required', httpStatus: s, body, exit: 2, reason: 'admin_required',
+      error: `${tag} 被拒：HTTP ${s}（服务端契约：\`adminAuth\` —— \`Bearer\` 令牌 + 该账号必须是管理员）。`
+        + '⇒ 换一个管理员 JWT（`--token-file <600 的文件>`），⛔ 本视图不会用别的端点绕过鉴权。',
+    }
+  }
+  if (s === 405) {
+    return {
+      ok: false, kind: 'method_not_allowed', httpStatus: s, body, exit: 2, reason: 'method_not_allowed',
+      error: `${tag} 回了 **405**（服务端契约：这些只读端点**只接受 GET**，其它动词一律 405 + \`Allow: GET\`）。`
+        + '本客户端**只会发 GET** ⇒ 405 说明链路/网关改写了动词或指错了端点，⛔ 不当作"没有数据"。',
+    }
+  }
+  if (s === 429) {
+    return {
+      ok: false, kind: 'rate_limited', httpStatus: s, body, exit: 2, reason: 'rate_limited',
+      error: `${tag} 回了 **429**（服务端契约：同一管理员 **6 次/分**）。这是**限流**、不是"没有数据"：`
+        + '等 60 秒后重跑（⛔ 本视图不会自动重试、更不会降级成 0 条）。',
+    }
+  }
+  if (s === 404 && !enveloped) {
+    return {
+      ok: false, kind: 'route_missing', httpStatus: s, body, exit: 2, reason: 'endpoint_missing',
+      error: `${tag} ⇒ 404 且响应体**不是**本服务的信封（\`{ok,reason,…}\`）⇒ **路由不在**（接口未部署 / base URL 指错）。`
+        + '⛔ 这不是"空集"：那一节会标 `available:false + endpoint_missing`。',
+    }
+  }
+  if (s !== 200 && !enveloped) {
+    return {
+      ok: false, kind: 'http_error', httpStatus: s, body, exit: 1, reason: 'bad_output',
+      error: `${tag} ⇒ HTTP ${s}（不是 200/404/401/405/429，且响应体不是本服务的信封）⇒ 无法判定这一节的内容，⛔ 不降级成 0 条。`,
+    }
+  }
+  if (!body) {
+    return {
+      ok: false, kind: 'bad_output', httpStatus: s, body: null, exit: 1, reason: 'bad_output',
+      error: `${tag} 的响应不是 JSON 对象（HTTP ${s}）⇒ 无法判定这一节的内容。`,
+    }
+  }
+  // ⚠️ 服务端的业务性拒绝**可能挂在 400 上**（`?status=` ⇒ 400 `field_unknown`；分页越界 ⇒ 400 `bad_limit`），
+  //    也可能挂在 200 上（`field_missing`）⇒ 判定**只看 `ok` 与 `reason`**，⛔ 不看状态码（服务端契约 §0）。
+  if (body.ok !== true) {
+    const srvReason = String(body.reason || '').trim()
+    const missingFields = Array.isArray(body.missingFields) ? body.missingFields.map(String) : []
+    const hintOf = () => missingFields
+      .map((m) => OPS_FIELD_HINTS[OPS_SERVER_FIELD_HINTS[m] || String(m).split('.').pop()])
+      .filter(Boolean).slice(0, 3)
+    if (srvReason === 'field_missing') {
+      return {
+        ok: false, kind: 'field_missing', httpStatus: s, body, exit: 2, reason: 'field_missing', missingFields,
+        error: `${tag} ⇒ HTTP ${s} + \`ok:false, reason:"field_missing"\`（服务端契约 §0：**判定只看 \`ok\`**，⛔ 不看状态码）。`
+          + (missingFields.length ? `\n   服务端点名的缺字段：${missingFields.join('、')}` : '')
+          + (hintOf().length ? `\n   ${hintOf().join('\n   ')}` : '')
+          + '\n   ⛔ 本视图**不会**把"字段不在"降级成"计数为 0"，也**不会**替你筛掉坏行（那正是假绿）。',
+      }
+    }
+    if (srvReason === 'field_unknown') {
+      const field = String(body.field || '').trim()
+      const isStatusTrap = field === 'status' || field === ''
+      return {
+        ok: false, kind: 'field_unknown', httpStatus: s, body, exit: 2, reason: 'field_unknown',
+        error: `${tag} ⇒ HTTP ${s} \`field_unknown\`：服务端**不认识**参数 ${field ? `\`${field}\`` : '（未点名）'}。`
+          + (isStatusTrap ? `\n   ⚠️ O2 陷阱①：码状态字段是 **\`state\`**，**不是 \`status\`** —— 服务端对 \`?status=\` 就是回这个码`
+            + '（⛔ 它**不会**静默按 `status` 筛出一页空，本视图也不把这种响应当"没有在途码"）。' : '')
+          + (body.error ? `\n   服务端原文：${String(body.error).slice(0, 300)}` : ''),
+      }
+    }
+    if (/^bad_/.test(srvReason)) {
+      return {
+        ok: false, kind: 'bad_request', httpStatus: s, body, exit: 2, reason: 'bad_request',
+        error: `${tag} ⇒ 服务端拒绝了参数（\`reason:"${srvReason}"\`）：${body.error ? String(body.error).slice(0, 300) : ''}`
+          + '\n   ⛔ 分页/取值越界不是"没有数据"（服务端契约：`limit` 上限 200、超限 400 而**不静默截断**）。',
+      }
+    }
+    return {
+      ok: false, kind: 'server_refused', httpStatus: s, body, exit: 1, reason: 'bad_output',
+      error: `${tag} ⇒ HTTP ${s} 但 \`ok:false\`（reason=${JSON.stringify(srvReason || null)}）⇒ 无法判定这一节的内容。`
+        + (body.error ? `\n   服务端原文：${String(body.error).slice(0, 300)}` : ''),
+    }
+  }
+  return { ok: true, body, status: s }
+}
+
+/**
+ * 探测用的占位值：带 `{prefix}`/`{codePrefix}` 的按占位符替换；以 `/` 结尾的路径（`activation-code/`、
+ * `devices/`）直接**追加** 8 位占位前缀。⚠️ 两条路径的服务端语义不同且都算"在位"：
+ * `activation-code/ZZZZZZZZ` ⇒ 404 + 本服务信封（码不存在）；`devices/ZZZZZZZZ` ⇒ 400 `bad_device`（非 hex）。
+ */
+const probePlaceholder = (rel) => {
+  let p = String(rel || '')
+  if (p.includes('{prefix}')) return p.replace('{prefix}', 'ZZZZZZZZ')
+  if (p.includes('{codePrefix}')) return p.replace('{codePrefix}', 'ZZZZZZZZ')
+  if (p.endsWith('/')) p += 'ZZZZZZZZ'
+  return p
+}
+
+/**
+ * `--probe`：**逐个实测**读端点（写端点一律不探）—— 给"在不在"提供实测证据，并标出与登记表是否一致。
+ * 两种证据**都算实测**：`via:"live-call"`（本轮取数已经打过它，用那次的状态码/响应体判定）与
+ * `via:"explicit"`（占位参数真探一次）。⇒ `--probe` 不会白烧限流额度（4 个数据接口本来就要打）。
+ * ⛔ 404 + 响应体不是本服务信封 ⇒ `missing`；429 ⇒ **`unknown`**（限流钩子在路由之前 ⇒ 它证明不了路由在不在）。
+ */
+export async function probeReadEndpoints({ baseUrl, token, timeoutMs, fetchImpl, endpoints = OPS_READ_ENDPOINTS, observed = null }) {
+  const out = []
+  for (const ep of endpoints) {
+    const seen = observed && typeof observed.get === 'function' ? observed.get(ep.id) : null
+    let obs = seen
+    let via = 'live-call'
+    if (!obs) {
+      // ⛔ 只探 GET；URL 里带占位前缀（服务端按"码不存在"/"参数不合法"回 404/400 —— 与"路由不存在"用响应体区分）
+      const url = endpointOf(baseUrl, probePlaceholder(ep.rel || ep.path.replace(/^\//, '')))
+      const r = await httpGet({ endpoint: url, token, timeoutMs, fetchImpl })
+      obs = { httpStatus: r.status, body: r.body && typeof r.body === 'object' ? r.body : null, url, network: r.network }
+      via = 'explicit'
+    }
+    const enveloped = Boolean(obs.body && typeof obs.body.reason === 'string')
+    const verdict = obs.network ? `探不到（${obs.network}）`
+      : obs.httpStatus === 200 ? (obs.body && obs.body.ok === false
+        ? `exists（但响应 ok:false/${obs.body.reason} ⇒ 数据面有缺口）` : 'exists')
+        : (obs.httpStatus === 401 || obs.httpStatus === 403) ? 'exists（需 admin 鉴权）'
+          : obs.httpStatus === 405 ? 'exists（路由在，但 GET 被拒 ⇒ 405）'
+            : obs.httpStatus === 400 ? (enveloped ? `exists（路由在，参数被拒：${obs.body.reason}）` : 'unknown（400 且非本服务信封）')
+              : obs.httpStatus === 404 ? (enveloped ? 'exists（路由在，资源不存在）' : 'missing（路由不在）')
+                : obs.httpStatus === 429 ? 'unknown（429 限流命中，路由在不在判不了）'
+                  : `unknown（HTTP ${obs.httpStatus}）`
+    const live = verdict.startsWith('exists') ? 'exists' : verdict.startsWith('missing') ? 'missing' : 'unknown'
+    const registered = ep.exists ? 'exists' : 'missing'
+    out.push({
+      id: ep.id, method: ep.method, path: ep.path, probed: true, via, httpStatus: obs.httpStatus ?? null,
+      registered, verdict, live,
+      agrees: live === 'unknown' ? null : live === registered,
+    })
+  }
+  return out
+}
+
+// ── 服务端节的**元信息**（宿主可判"这一页是不是全量"）─────────────────────────────
+/**
+ * 服务端分页元信息（映射④的落点）：`total` = 分页前总数、`count` = 本页条数、`hasMore` = 还有更多。
+ * ⚠️ `total`/`count` 的**语义由服务端定义**（`events.total` = 窗口内总数；`codes.total` = 命中的状态集合总数）
+ * ⇒ 客户端**原样透传**并另给 `coverage`（`hasMore:true` ⇒ `page-only`），⛔ 不把它当"在途码数"用。
+ */
+export function serverPageMeta({ endpoint, query = null, body = {}, states = null, limit = null }) {
+  const b = body && typeof body === 'object' ? body : {}
+  const items = Array.isArray(b.items) ? b.items : null
+  return {
+    endpoint,
+    ...(query ? { query } : {}),
+    ...(states ? { states } : {}),
+    count: num(b.count) ?? (items ? items.length : null),
+    total: num(b.total),
+    limit: num(b.limit) ?? limit,
+    offset: num(b.offset) ?? 0,
+    hasMore: b.hasMore === true,
+  }
+}
+
+/** 异常清单：并入"服务端口径类"异常并重算 count（⛔ 只增不改判；判定仍在 `analyzeOps`）。 */
+export function mergeAnomalies(section, extra = []) {
+  const items = [...((section && section.items) || []), ...extra]
+  return { ...(section || { available: true }), count: items.length, items }
+}
+
+/**
+ * **顶层覆盖率**（`coverage`）：`'full'` ⇔ 每个可用节都是 `coverage:'full'` 且**没有** `available:false` 的节。
+ * `'partial'` = 至少答了一节但没全绿；`detail` 逐节给出 `coverage` 或 `unavailable:<reason>`（宿主可分支）。
+ * ⚠️ `local` 那一节是**附注**（本机许可/审计），不参与覆盖口径。
+ */
+export function summarizeCoverage(sections = {}) {
+  const detail = {}
+  let available = 0
+  let full = 0
+  for (const [k, s] of Object.entries(sections)) {
+    if (k === 'local' || !s || typeof s !== 'object') continue
+    if (s.available === false) { detail[k] = `unavailable:${s.reason || 'unknown'}`; continue }
+    detail[k] = s.coverage || 'unknown'
+    available += 1
+    if ((s.coverage || '') === 'full') full += 1
+  }
+  const coverage = available > 0 && full === available ? 'full' : (available > 0 ? 'partial' : 'none')
+  return { coverage, coverageDetail: detail, coverageSections: { available, full } }
+}
+
+// ── verb 入口 ────────────────────────────────────────────────────────────────
+/**
+ * `argent license ops [--from|--server] …`。
+ * @param {string[]} argv 子命令参数（不含 `--json`；那是 CLI 层开关）
+ * @param {{env?:object, dataDir?:string, repo?:string, fetch?:Function, now?:number, parsed?:object}} [deps]
+ * @returns {Promise<{json:object, human:string, stderr:string, exit:number}>}
+ */
+export async function runOpsVerb(argv = [], deps = {}) {
+  const env = deps.env || process.env
+  const p = deps.parsed || parseOpsArgs(argv)
+  if (!p.ok) return failJson(p.code, p.reason, p.error, { usage: OPS_USAGE })
+  const { values, repeat, bools } = p
+  const asJson = deps.asJson === true || bools.has('--json') || argv.includes('--json')
+  if (bools.has('--help') || bools.has('-h')) {
+    return { json: { ok: true, empty: false, code: 0, reason: null, subcommand: 'ops', usage: OPS_USAGE }, human: OPS_USAGE, stderr: '', exit: 0 }
+  }
+
+  const dataDir = deps.dataDir || resolveDataDir({ env }).dir
+  const now = deps.now ?? (values['--now'] ? parseTime(values['--now']) : Date.now())
+  if (!Number.isFinite(now)) {
+    return failJson(2, 'usage_error', `--now 不是可解析的时间：${values['--now']}（用 ISO 8601，如 2026-10-04T12:00:00Z）`)
+  }
+  let days = OPS_DEFAULT_DAYS
+  if (values['--days'] !== undefined) {
+    const d = num(values['--days'])
+    if (d === null || !Number.isInteger(d) || d <= 0 || d > 365) {
+      return failJson(2, 'usage_error', `--days 只接受 1..365 的整数，实得 ${JSON.stringify(values['--days'])}`)
+    }
+    days = d
+  }
+
+  // `--filter`：字段必须在**本域词表**里 —— 否则 `field_missing`（陷阱①的入口）
+  const filters = []
+  for (const raw of repeat['--filter'] || []) {
+    const i = String(raw).indexOf('=')
+    if (i <= 0) return failJson(2, 'usage_error', `--filter 需要 <字段=值> 形态，实得 ${JSON.stringify(raw)}（可用字段：${OPS_FILTER_FIELDS.join('、')}）`)
+    const field = String(raw).slice(0, i).trim()
+    const value = String(raw).slice(i + 1)
+    if (!OPS_FILTER_FIELDS.includes(field)) {
+      return failJson(2, 'field_missing',
+        `--filter 用了本域不存在的字段 \`${field}\`（可用：${OPS_FILTER_FIELDS.join('、')}）。`
+        + (OPS_FIELD_HINTS[field] ? `\n   ${OPS_FIELD_HINTS[field]}` : '')
+        + '\n   ⛔ 本视图**不会**把"字段不存在"变成"筛出 0 条"（那正是假绿）。')
+    }
+    filters.push({ field, value })
+  }
+
+  // `--prefix`：形态即服务端契约（8 位 Crockford base32）
+  const prefixes = []
+  for (const raw of repeat['--prefix'] || []) {
+    const s = String(raw).trim().toUpperCase()
+    if (!/^[0-9A-HJKMNP-TV-Z]{8}$/.test(s)) {
+      return failJson(2, 'usage_error', '--prefix 必须是 **8 位** Crockford base32'
+        + '（`0123456789ABCDEFGHJKMNPQRSTVWXYZ`，没有 I/L/O/U；连字符可有可无），'
+        + `实得 ${JSON.stringify(raw)}`)
+    }
+    prefixes.push(s)
+  }
+  const deviceQuery = values['--device'] ? String(values['--device']).trim().toLowerCase() : ''
+  if (deviceQuery && !/^[0-9a-f]{8,64}$/.test(deviceQuery)) {
+    return failJson(2, 'usage_error', '--device 只接受 8..64 位十六进制（12 位前缀或 64hex 全码；⛔ 不接受主机名/MAC/IP）')
+  }
+
+  // 数据源互斥
+  const srcCount = [values['--from'], values['--server'], bools.has('--local') ? 'local' : null].filter(Boolean).length
+  if (srcCount > 1) {
+    return failJson(2, 'usage_error', '`--from` / `--server` / `--local` 只能给一个（三种数据源互斥 —— 混用时"这个数是从哪来的"说不清）')
+  }
+
+  // ── 分支 1：离线快照 ──────────────────────────────────────────────────────
+  if (values['--from']) {
+    const snap = loadOpsSnapshot(values['--from'])
+    if (!snap.ok) return failJson(snap.code, snap.reason, snap.error)
+    const snapNow = values['--now'] ? now : (parseTime(snap.data.generatedAt) ?? now)
+    const fields = checkOpsFields({
+      codes: snap.data.codes || [], events: snap.data.events || [], accounts: snap.data.accounts || [],
+      devices: (snap.data.accounts || []).flatMap((a) => (a && Array.isArray(a.devices) ? a.devices : [])),
+    })
+    if (!fields.ok) return failJson(2, 'field_missing', fields.hint, { fieldProfile: fields.profile, missingFields: fields.missing })
+    const a = analyzeOps(snap.data, { now: snapNow, days, filters, device: deviceQuery })
+    // ⚠️ **集合缺席 ≠ 集合为空**：快照里根本没有 `accounts` 键 ⇒ 席位账目那一节标 `no_data`（附要哪个集合），
+    //     ⛔ 不报"0 个账号"（那与"真没有账号"分不开，正是本视图要防的假绿形态）。
+    const has = (k) => Object.prototype.hasOwnProperty.call(snap.data, k)
+    const sections = {
+      inflight: has('codes') ? a.inflight
+        : unavailable('no_data', '快照里的 `codes` 集合', '这份快照没有码记录 ⇒ 在途码（与失败码）答不了（⛔ 不是"没有在途码"）'),
+      failures: has('codes') || has('events') ? a.failures
+        : unavailable('no_data', '快照里的 `codes`/`events` 集合', '失败码 = failCount>0 或 revoked 的码 + 拒绝事件计数，两者都不在快照里'),
+      timeline: has('events') ? a.timeline
+        : unavailable('no_data', '快照里的 `events` 集合', '没有事件集合 ⇒ 近 N 天时间线答不了'),
+      seats: has('accounts') ? a.seats
+        : unavailable('no_data', '快照里的 `accounts` 集合', `席位账目要账号 + 设备记录；${SEAT_DEFINITION}`),
+      anomalies: (has('codes') || has('events') || has('accounts')) ? a.anomalies
+        : unavailable('no_data', '快照里的 `codes`/`events`/`accounts` 集合', '三类记录都不在快照里 ⇒ 一条异常也判不了'),
+      ...(a.device ? { device: a.device } : {}),
+    }
+    return envelope({
+      a, mode: 'snapshot', dataDir, now: snapNow, days, asJson, sectionsObj: sections, empty: computeEmpty(sections),
+      source: { kind: 'snapshot', from: snap.path, generatedAt: snap.data.generatedAt ?? null, note: snap.data.source ?? null },
+      fieldProfile: fields.profile,
+      missingEndpoints: [], probe: null, prefixes: null, prefixSource: null, local: null,
+    })
+  }
+
+  // ── 分支 2：服务端只读接口 ────────────────────────────────────────────────
+  if (values['--server']) {
+    const server = resolveActivationServer({ flag: values['--server'], env })
+    if (!server.ok) return failJson(2, server.reason, server.error, { server: { source: server.source || null } })
+    const tok = resolveOpsToken({ flag: values['--token-file'] || null, env, dataDir })
+    if (!tok.ok) return failJson(2, tok.reason, tok.error, { token: { source: tok.source || null, file: tok.file || null, mode: tok.mode === null || tok.mode === undefined ? null : `0${tok.mode.toString(8)}` } })
+    const fetchImpl = deps.fetch || globalThis.fetch
+    if (typeof fetchImpl !== 'function') return failJson(1, 'activation_server_unreachable', '本运行时没有 fetch 实现（Node ≥18 才有）⇒ 无法调服务端只读接口')
+    const timeoutMs = resolveTimeoutMs(env)
+    const local = readLocalOps({ env, dataDir, now })
+
+    // ── 只读取数（**只发 GET**）：4 个服务端只读接口 + 显式 `--prefix` 的单查 ──────────────
+    //   · 404 且响应体**不是**本服务信封 ⇒ **路由不在**（接口未部署 / base URL 指错）⇒ 那一节标 endpoint_missing，
+    //     ⛔ **不是空集**（这正是"接口已就绪但还没部署"这个真实窗口要防的假绿）；
+    //   · 其余异常（401/403/405/429/400/200-ok:false/连不上）⇒ **响亮失败**（exit 2/1 + 明确 reason），
+    //     ⛔ 绝不降级成"0 条"。
+    const observed = new Map()                     // endpoint id → 本轮**实测**到的状态码/响应体（`--probe` 复用）
+    const routeMissing = new Map()                 // endpoint id → 实测"路由不在"的证据串
+    const get = (id, relPath) => opsServerGet({ id, relPath, baseUrl: server.baseUrl, token: tok.token, timeoutMs, fetchImpl, observed })
+    const epOf = (id) => OPS_READ_ENDPOINTS.find((e) => e.id === id)
+    const fatal = (res, id) => failJson(res.exit, res.reason, res.error, {
+      server: { baseUrl: server.baseUrl, baseUrlSource: server.source, tls: server.tls, endpoint: id },
+      ...(res.missingFields ? { missingFields: res.missingFields } : {}),
+    })
+
+    const sinceMs = now - days * 86400000
+    const codesQuery = `state=${OPS_CODES_QUERY_STATES.join(',')}&limit=${OPS_PAGE_LIMIT}&offset=0`
+    const eventsQuery = `since=${encodeURIComponent(iso(sinceMs))}&limit=${OPS_PAGE_LIMIT}&offset=0`
+    const seatsQuery = `limit=${OPS_PAGE_LIMIT}&offset=0`
+
+    const codesRes = await get('codes-list', `${CODES_LIST_REL}?${codesQuery}`)
+    if (!codesRes.ok && codesRes.kind !== 'route_missing') return fatal(codesRes, 'codes-list')
+    if (!codesRes.ok) routeMissing.set('codes-list', codesRes.error)
+    const eventsRes = await get('events', `${EVENTS_REL}?${eventsQuery}`)
+    if (!eventsRes.ok && eventsRes.kind !== 'route_missing') return fatal(eventsRes, 'events')
+    if (!eventsRes.ok) routeMissing.set('events', eventsRes.error)
+    const seatsRes = await get('seats', `${SEATS_REL}?${seatsQuery}`)
+    if (!seatsRes.ok && seatsRes.kind !== 'route_missing') return fatal(seatsRes, 'seats')
+    if (!seatsRes.ok) routeMissing.set('seats', seatsRes.error)
+    const deviceRes = deviceQuery ? await get('device-lookup', `${DEVICE_LOOKUP_REL}${deviceQuery}`) : null
+    if (deviceRes && !deviceRes.ok && deviceRes.kind !== 'route_missing') return fatal(deviceRes, 'device-lookup')
+    if (deviceRes && !deviceRes.ok) routeMissing.set('device-lookup', deviceRes.error)
+
+    const codesOk = codesRes.ok
+    const eventsOk = eventsRes.ok
+    const seatsOk = seatsRes.ok
+    const deviceOk = Boolean(deviceRes && deviceRes.ok)
+
+    // 前缀：**只查显式 `--prefix`**（含 code-status 里已终态的码）；codes-list 在位时不再拿本机审计的前缀去凑数
+    const prefixSource = prefixes.length ? 'flag:--prefix'
+      : codesOk ? 'none（codes-list 已在位 ⇒ 不需要按前缀凑数）'
+        : (local.prefixes.length ? 'local-audit（codes-list 不在位 ⇒ 退回本机激活审计见过的前缀）' : 'none')
+    const wantPrefixes = prefixes.length ? prefixes : (codesOk ? [] : local.prefixes.slice(0, 20))
+    const prefixCodes = []
+    let prefixRouteMissing = false
+    for (const pre of wantPrefixes) {
+      const url = endpointOf(server.baseUrl, `${CODE_STATUS_PATH}${pre}`)
+      const r = await httpGet({ endpoint: url, token: tok.token, timeoutMs, fetchImpl })
+      observed.set('code-status', { httpStatus: r.status, body: r.body && typeof r.body === 'object' ? r.body : null, url, network: r.network })
+      if (r.network) {
+        return failJson(1, r.network === 'timeout' ? 'activation_timeout' : 'activation_server_unreachable',
+          `${r.error}（服务端只读接口是**唯一**的远端数据源 ⇒ 读不到就没有结论，⛔ 不降级成"没有在途码"）`,
+          { server: { baseUrl: server.baseUrl, endpoint: server.endpoint, source: server.source, tls: server.tls } })
+      }
+      if (r.status === 404 && !(r.body && typeof r.body.reason === 'string')) {
+        prefixRouteMissing = true
+        routeMissing.set('code-status', `GET ${url} ⇒ 404 且响应体**不是**本服务信封 ⇒ 路由不在`)
+        break
+      }
+      const norm = normalizeServerCode(r.body, { prefix: pre, httpStatus: r.status })
+      if (!norm.ok) return failJson(norm.code, norm.reason, norm.error, { server: { baseUrl: server.baseUrl }, prefix: pre })
+      prefixCodes.push({ ...norm.code, httpStatus: r.status })
+    }
+
+    // ── 服务端行 → 客户端形状（**四处映射陷阱的唯一落点**；⛔ 只白名单投影，不整行透传）────────
+    const rawCodes = codesOk ? codesRes.body.items : []
+    const rawEvents = eventsOk ? eventsRes.body.items : []
+    const rawAccounts = seatsOk ? seatsRes.body.items : []
+    const rawDevices = deviceOk && Array.isArray(deviceRes.body.items) ? deviceRes.body.items : []
+    // 行级字段契约（服务端口径的镜像；⛔ 空集合不算缺字段）
+    const fieldCheck = checkServerRows({
+      codes: Array.isArray(rawCodes) ? rawCodes : [],
+      events: Array.isArray(rawEvents) ? rawEvents : [],
+      accounts: Array.isArray(rawAccounts) ? rawAccounts : [],
+      devices: rawDevices,
+    })
+    if (!fieldCheck.ok) return failJson(2, 'field_missing', fieldCheck.hint, { missingFields: fieldCheck.missing })
+
+    const codes = [...(codesOk ? mapServerCodes(rawCodes) : []), ...prefixCodes.filter((c) => c.state)]
+      .reduce((m, c) => (c && c.codePrefix ? m.set(String(c.codePrefix).toUpperCase(), c) : m), new Map())
+    const codeRows = [...codes.values()]
+    const events = eventsOk ? mapServerEvents(rawEvents) : []
+    const accounts = seatsOk ? mapServerSeats(rawAccounts) : []
+
+    // 一次 analyzeOps：五节与异常清单**只有这一处判据**（与快照/本机模式同源）
+    const a = analyzeOps({ codes: codeRows, events, accounts }, { now, days, filters, device: deviceQuery })
+
+    // ── 五节（服务端口径；每节带 `server` 元信息 + `coverage`，宿主可判"这一页是不是全量"）──────
+    const sections = {}
+    const prefixUsable = wantPrefixes.length > 0 && !prefixRouteMissing
+
+    // ① 在途码
+    if (codesOk) {
+      const hasMore = codesRes.body.hasMore === true
+      sections.inflight = {
+        ...a.inflight,
+        coverage: hasMore ? 'page-only' : 'full',
+        server: serverPageMeta({ endpoint: epOf('codes-list').path, query: codesQuery, body: codesRes.body, states: OPS_CODES_QUERY_STATES }),
+        ...(hasMore ? { note: `服务端还有更多行（total ${num(codesRes.body.total)} > 本页 ${a.inflight.count}）⇒ 这一节是"最新一页"，⛔ 不是全量` } : {}),
+      }
+    } else if (prefixUsable) {
+      sections.inflight = {
+        ...a.inflight, coverage: 'prefix-only', prefixes: wantPrefixes, prefixSource,
+        note: `GET ${epOf('codes-list').path} 不在位（路由 404）⇒ 退回按前缀单查：只有 ${wantPrefixes.length} 个前缀被查过`
+          + `（来源：${prefixSource}）—— ⛔ 这不是"全部在途码"`,
+      }
+    } else {
+      sections.inflight = unavailable('endpoint_missing', epOf('codes-list').path,
+        `全量在途码要 GET ${epOf('codes-list').path}（本轮实测 404 路由不在 ⇒ 接口未部署或 base URL 指错）`
+        + `${wantPrefixes.length ? '，且按前缀单查那条路也不在位' : '；也没有可用前缀可退'}（⛔ 不是"没有在途码"）`)
+    }
+
+    // ② 失败码（`failCount>0`/`revoked` 的码 + `*_denied` 事件计数）
+    if (codesOk || eventsOk) {
+      const sources = [codesOk ? 'codes' : null, eventsOk ? 'events' : null].filter(Boolean)
+      sections.failures = {
+        ...a.failures,
+        coverage: codesOk && eventsOk ? 'full' : 'partial',
+        server: {
+          sources,
+          ...(codesOk ? { codes: serverPageMeta({ endpoint: epOf('codes-list').path, query: codesQuery, body: codesRes.body }) } : {}),
+          ...(eventsOk ? { events: serverPageMeta({ endpoint: epOf('events').path, query: eventsQuery, body: eventsRes.body }) } : {}),
+        },
+        ...(codesOk && eventsOk ? {} : { note: `只有 ${sources.join('+')} 在位 ⇒ 失败码口径不完整（⛔ 不是"全量"）` }),
+      }
+      if (prefixUsable) sections.failures.partial = a.failures
+    } else if (prefixUsable) {
+      sections.failures = {
+        ...unavailable('endpoint_missing', epOf('events').path,
+          '失败码分布与拒绝事件计数都要读 `licenseevents`；按前缀单查只能看 `failCount`/`lockedUntil` 两个字段'),
+        partial: a.failures,
+      }
+    } else {
+      sections.failures = unavailable('endpoint_missing', `${epOf('codes-list').path} + ${epOf('events').path}`,
+        '失败码 = `failCount>0`/`revoked` 的码 + `*_denied` 事件计数；两个数据源都不在位（⛔ 不是"没有失败码"）')
+    }
+
+    // ③ 时间线（近 N 天；服务端 `total` = 窗口内总数、`count` = 本页 —— 映射④）
+    if (eventsOk) {
+      const hasMore = eventsRes.body.hasMore === true
+      sections.timeline = {
+        ...a.timeline,
+        coverage: hasMore ? 'page-only' : 'full',
+        server: serverPageMeta({ endpoint: epOf('events').path, query: eventsQuery, body: eventsRes.body }),
+        ...(hasMore ? { note: `服务端只回窗口内**最新** ${OPS_PAGE_LIMIT} 条（total ${num(eventsRes.body.total)}）⇒ 更早的没进这一页` } : {}),
+      }
+    } else {
+      sections.timeline = unavailable('endpoint_missing', epOf('events').path,
+        `近 N 天事件时间线要读 \`licenseevents\` 的只读投影（${epOf('events').path}；本轮实测 404 路由不在 ⇒ 接口未部署）`
+        + '（⛔ 不是"这 N 天没有事件"）')
+    }
+
+    // ④ 席位账目（映射②：`items/totals` → `accounts/seatTotals`；`used` 客户端**自己算**并比对）
+    let totalsMismatch = null
+    if (seatsOk) {
+      const hasMore = seatsRes.body.hasMore === true
+      const serverTotals = seatsRes.body.totals && typeof seatsRes.body.totals === 'object' ? seatsRes.body.totals : null
+      const mine = a.seats.totals
+      if (serverTotals) {
+        const keys = ['accounts', 'seats', 'deviceLimit', 'used', 'free']
+        const diff = keys.filter((k) => num(serverTotals[k]) !== null && num(serverTotals[k]) !== mine[k])
+        if (diff.length) {
+          totalsMismatch = {
+            id: 'seat_totals_mismatch', severity: 'warn', subject: 'seats.totals',
+            detail: `席位合计与服务端不一致（字段：${diff.join('、')}）：服务端 ${JSON.stringify(serverTotals)}`
+              + ` vs 本视图按设备记录重算 ${JSON.stringify(mine)}（已释放的 \`releasedAt\` 非空）记录**不占**席位）`,
+            needs: `核对设备记录与服务端口径；${SEAT_DEFINITION}`,
+          }
+        }
+      }
+      sections.seats = {
+        ...a.seats,
+        coverage: hasMore ? 'page-only' : 'full',
+        server: {
+          ...serverPageMeta({ endpoint: epOf('seats').path, query: seatsQuery, body: seatsRes.body }),
+          ...(serverTotals ? { totals: serverTotals } : {}),
+          ...(seatsRes.body.definition ? { definition: seatsRes.body.definition } : {}),
+        },
+        totalsMatch: totalsMismatch === null,
+        note: '`principals[].used` / `totals` 是**本视图按 `releasedAt` 为空的设备码去重**算出来的（映射②/陷阱②）；'
+          + '`server.totals` 是服务端自己的口径，两边不一致会记一条 `seat_used_mismatch`/`seat_totals_mismatch`。',
+      }
+    } else {
+      sections.seats = unavailable('endpoint_missing', epOf('seats').path,
+        `席位账目要服务端按 \`releasedAt\` 为空的设备码去重算 \`used\` 再回（${epOf('seats').path}；`
+        + `本轮实测 404 路由不在 ⇒ 接口未部署）（⛔ 不是"没有账号/没有席位"）。${SEAT_DEFINITION}`)
+    }
+
+    // ⑤ 异常清单（只看不判；席位口径不一致的两类在这里并入）
+    const anomalySources = [codesOk, eventsOk, seatsOk, prefixUsable].filter(Boolean).length
+    sections.anomalies = anomalySources
+      ? {
+        ...mergeAnomalies(a.anomalies, totalsMismatch ? [totalsMismatch] : []),
+        coverage: codesOk && eventsOk && seatsOk ? 'full' : 'partial',
+        ...(codesOk && eventsOk && seatsOk ? {} : { note: '部分只读接口不在位 ⇒ 只有拿到的那些记录参与判定（⛔ 不是"没有异常"）' }),
+      }
+      : unavailable('endpoint_missing', `${epOf('codes-list').path} + ${epOf('events').path} + ${epOf('seats').path}`,
+        '三类记录（码/事件/席位）都没读到 ⇒ 一条异常也判不了（⛔ 不是"没有异常"）')
+
+    // ⑥ 设备归属（映射③：命中处数看服务端 **`total`**）
+    if (deviceQuery) {
+      if (deviceOk) {
+        const dev = mapServerDevice(deviceRes.body, { query: deviceQuery })
+        sections.device = { ...dev, server: { ...dev.server, query: deviceQuery } }
+      } else {
+        sections.device = unavailable('endpoint_missing', `${epOf('device-lookup').path}{codePrefix}`,
+          '设备归属要服务端按设备码查绑定记录'
+          + `（${epOf('device-lookup').path}{codePrefix}；本轮实测 404 路由不在 ⇒ 接口未部署）（⛔ 不是"这台设备没挂过账号"）`)
+      }
+    }
+    sections.local = { ...local.license, activations: local.activations }
+
+    // 缺接口清单 = 静态登记 `exists:false` ∪ **本轮实测 404**（"已就绪但未部署"就是这么被抓出来的）
+    const missingEndpoints = [
+      ...OPS_READ_ENDPOINTS.filter((e) => !e.exists)
+        .map((e) => ({ id: e.id, method: e.method, path: e.path, neededFor: e.neededFor, why: e.note })),
+      ...[...routeMissing.entries()].map(([id, error]) => {
+        const e = epOf(id)
+        return {
+          id, method: e.method, path: e.path, neededFor: e.neededFor, why: e.note,
+          runtime: true, httpStatus: 404, error,
+        }
+      }),
+    ]
+
+    const probe = bools.has('--probe')
+      ? await probeReadEndpoints({ baseUrl: server.baseUrl, token: tok.token, timeoutMs, fetchImpl, observed })
+      : null
+    const empty = computeEmpty(sections)
+    return envelope({
+      a: null, mode: 'server', dataDir, now, days, asJson,
+      source: {
+        kind: 'server', baseUrl: server.baseUrl, baseUrlSource: server.source, tls: server.tls, loopback: server.loopback,
+        endpoints: OPS_READ_ENDPOINTS.map((e) => `${e.method} ${e.path}`),
+        timeoutMs, pageLimit: OPS_PAGE_LIMIT,
+        tokenSource: tok.source, tokenFile: tok.file, token: '(已配置，⛔ 不回显)',
+      },
+      sectionsObj: sections, missingEndpoints, probe, empty, prefixSource, prefixes: wantPrefixes,
+      observed, local, fieldProfile: null,
+    })
+  }
+
+  // ── 分支 3（默认）：本机只读产物 ──────────────────────────────────────────
+  const local = readLocalOps({ env, dataDir, now })
+  const localAnomalies = []
+  const rejected = local.activations.rows.filter((r) => r.ok === false)
+  if (rejected.length) {
+    localAnomalies.push({
+      id: 'local_activation_rejected', severity: 'warn', subject: 'license-activation/audit.jsonl',
+      detail: `本机激活审计里有 ${rejected.length} 条失败兑换（最近：${rejected.slice(-3).map((r) => `${r.codePrefix || '?'}/${r.reason || '?'}`).join('、')}）`,
+      needs: '按前缀走 `argent license ops --server <base> --prefix <前缀>` 查服务端状态（或 `argent license activate` 的重试话术）',
+    })
+  }
+  const missingEndpoints = OPS_READ_ENDPOINTS.filter((e) => !e.exists).map((e) => ({ id: e.id, method: e.method, path: e.path, neededFor: e.neededFor, why: e.note }))
+  const sections = {
+    inflight: unavailable('needs_server', OPS_READ_ENDPOINTS[1].path, '本机产物里没有别人的码；在途码要服务端只读接口（`--server <base>`）'),
+    failures: unavailable('needs_server', OPS_READ_ENDPOINTS[2].path, '失败码分布要读 `licenseevents`（本机只有自己那几次兑换的审计）'),
+    timeline: unavailable('needs_server', OPS_READ_ENDPOINTS[2].path, '近 N 天事件时间线要读 `licenseevents`'),
+    seats: unavailable('needs_server', OPS_READ_ENDPOINTS[3].path, `席位账目（含全部账号）要服务端；本机只能看自己这一份许可声明的席位。${SEAT_DEFINITION}`),
+    anomalies: localAnomalies.length
+      ? { available: true, coverage: 'local-only', count: localAnomalies.length, items: localAnomalies }
+      : { available: true, coverage: 'local-only', count: 0, items: [], note: '本机审计里没有失败兑换；服务端侧异常需要上面缺的接口' },
+    local: { ...local.license, activations: local.activations },
+  }
+  const empty = computeEmpty(sections)
+  return envelope({
+    a: null, mode: 'local', dataDir, now, days, asJson,
+    source: { kind: 'local', dataDir, note: '本机只读产物：许可声明 + 激活审计（零网络、零副作用）' },
+    sectionsObj: sections, missingEndpoints, probe: null, empty, prefixSource: null, prefixes: local.prefixes,
+    local, fieldProfile: null,
+  })
+}
+
+/** 统一信封（A2：`ok/empty/code/reason` 恒在；`$? == json.code`）。 */
+function envelope({ a, mode, dataDir, now, days, asJson, source, sectionsObj = null, missingEndpoints, probe, empty, prefixSource, prefixes, local = null, fieldProfile, observed = null }) {
+  void asJson
+  const sections = sectionsObj || {
+    inflight: a.inflight, failures: a.failures, timeline: a.timeline, seats: a.seats, anomalies: a.anomalies,
+    ...(a.device ? { device: a.device } : {}),
+  }
+  const unavailableList = Object.entries(sections)
+    .filter(([, s]) => s && s.available === false)
+    .map(([k, s]) => ({ section: k, reason: s.reason, needs: s.needs }))
+  // 顶层覆盖率（宿主一条字段就能判"这份视图是不是全的"）；⛔ 与逐节 `coverage` 同源，不另立判据
+  const cov = summarizeCoverage(sections)
+  const json = {
+    ok: true,
+    empty: empty === true,
+    code: 0,
+    reason: empty === true ? 'no_match' : null,
+    subcommand: 'ops',
+    readOnly: true,
+    sideEffects: 'none',
+    mode,
+    source,
+    dataDir,
+    now: iso(now),
+    days,
+    coverage: cov.coverage,
+    coverageDetail: cov.coverageDetail,
+    ...(prefixSource ? { prefixSource } : {}),
+    ...(prefixes ? { prefixes } : {}),
+    ...(fieldProfile ? { fieldProfile } : {}),
+    ...sections,
+    ...(a ? { filters: a.filters, since: a.since } : {}),
+    ...(probe ? { probe } : {}),
+    missingEndpoints,
+    unavailable: unavailableList,
+    ...(local ? { local } : {}),
+    definition: { seat: SEAT_DEFINITION, ttlGraceMinutes: OPS_TTL_GRACE_MINUTES, deniedRepeat: OPS_DENIED_REPEAT, inflightStates: OPS_INFLIGHT_STATES },
+    warnings: [
+      '只读视图：⛔ 不写任何集合/文件/审计；HTTP 只发 GET；⛔ 绝不调 `POST /api/argent/license/release-device`'
+        + '（该端点的 200 成功路径在生产库**从未跑过** ⇒ 视图不代触发写）。',
+      ...(mode === 'local' || mode === 'server'
+        ? ['缺席的小节是 `available:false`（附 `needs`），**不是 0** —— 这正是 O2 两个陷阱（`state` 不是 `status`、席位是算出来的）要防的假绿。']
+        : []),
+      ...(mode === 'server' && (missingEndpoints || []).some((e) => e.runtime)
+        ? ['服务端有只读接口**实测 404（路由不在）**：接口已就绪但**还没部署** ⇒ 相关小节标 `endpoint_missing`，⛔ 不是"0 条"。']
+        : []),
+    ],
+    endpoints: OPS_READ_ENDPOINTS.map((e) => {
+      const obs = observed && typeof observed.get === 'function' ? observed.get(e.id) : null
+      return {
+        id: e.id, method: e.method, path: e.path, exists: e.exists, neededFor: e.neededFor,
+        ...(obs ? { observed: { httpStatus: obs.httpStatus ?? null, network: obs.network || null } } : {}),
+      }
+    }),
+    judgedBy: 'core/lib/license-ops.mjs（只读；分析在 analyzeOps，纯函数）',
+  }
+  // A1：本 verb 只有两个出口 —— `0`（成功，含"成功但空"）与失败信封（2 用法/环境、1 数据源读失败）。
+  return { json, human: humanOps(json), stderr: '', exit: 0 }
+}
+
+/** 人读形态（一眼能看出"哪节缺"与"为什么缺"）。 */
+export function humanOps(j) {
+  const L = []
+  const mark = j.empty ? 'ℹ️' : '🔎'
+  L.push(`${mark} 许可运营巡检（只读）—— 数据源 ${j.mode} ｜ 现在 ${j.now} ｜ 窗口 ${j.days} 天`)
+  if (j.mode === 'snapshot') L.push(`   快照：${j.source.from}${j.source.generatedAt ? `（生成于 ${j.source.generatedAt}）` : ''}`)
+  if (j.mode === 'server') L.push(`   服务端：${j.source.baseUrl}（TLS ${j.source.tls ? '是' : '否，仅回环'}）｜ token 来源 ${j.source.tokenSource}`)
+  if (j.mode === 'local') L.push(`   数据目录：${j.dataDir}`)
+
+  const sec = (k) => j[k] || {}
+  const inf = sec('inflight')
+  if (inf.available === false) L.push(`   ⛔ 在途码：**答不了** —— ${inf.reason}（需要 ${inf.needs}）`)
+  else {
+    L.push(`   在途码 ${inf.count} 个（覆盖 ${inf.coverage}）${inf.coverage === 'prefix-only' ? `（仅已查的 ${(inf.prefixes || []).length} 个前缀 —— ⛔ 不是全量）` : ''}`)
+    for (const c of inf.codes || []) {
+      const tail = c.overdueMinutes > 0 ? `  ⚠️ **超 TTL ${c.overdueMinutes} 分钟未终态**` : (c.ttlLeftMinutes !== null ? `  TTL 剩 ${c.ttlLeftMinutes} 分` : '')
+      L.push(`     · ${c.codePrefix}  ${c.state}${c.intent ? `/${c.intent}` : ''}${c.failCount ? `  failCount ${c.failCount}` : ''}${tail}`)
+    }
+  }
+  const fal = sec('failures')
+  if (fal.available === false) L.push(`   ⛔ 失败码：**答不了** —— ${fal.reason}（需要 ${fal.needs}）`)
+  else {
+    const reasons = Object.entries(fal.byReason || {}).map(([k, v]) => `${k} ${v}`).join(' ｜ ') || '无'
+    L.push(`   失败码 ${fal.count} 个（覆盖 ${fal.coverage}；${Object.entries(fal.byState || {}).map(([k, v]) => `${k} ${v}`).join('、') || '无'}）｜ 拒绝事件：${reasons}`)
+    for (const c of fal.codes || []) L.push(`     · ${c.codePrefix}  ${c.state}  failCount ${c.failCount}`)
+  }
+  const tl = sec('timeline')
+  if (tl.available === false) L.push(`   ⛔ 事件时间线：**答不了** —— ${tl.reason}（需要 ${tl.needs}）`)
+  else {
+    const win = tl.server && tl.server.total !== null && tl.server.total !== undefined
+      ? `（服务端窗口内 total ${tl.server.total}，本页 ${tl.count}${tl.server.hasMore ? '，hasMore ⇒ 更早的没进这一页' : ''}）` : ''
+    L.push(`   近 ${tl.days} 天事件 ${tl.count} 条${win}（覆盖 ${tl.coverage}）：${Object.entries(tl.counts || {}).map(([k, v]) => `${k} ${v}`).join(' ｜ ') || '无'}`)
+    for (const e of (tl.events || []).slice(-8)) L.push(`     · ${e.at}  ${e.action}/${e.result}${e.codePrefix ? `  ${e.codePrefix}` : ''}`)
+    if ((tl.events || []).length > 8) L.push(`     …（另有 ${tl.events.length - 8} 条，--json 看全量）`)
+  }
+  const st = sec('seats')
+  if (st.available === false) L.push(`   ⛔ 席位账目：**答不了** —— ${st.reason}（需要 ${st.needs}）`)
+  else {
+    L.push(`   席位账目（覆盖 ${st.coverage}；${st.totals.accounts} 个账号：seats ${st.totals.seats} ｜ 上限 ${st.totals.deviceLimit} ｜ 已用 ${st.totals.used} ｜ 余 ${st.totals.free}）`
+      + `${st.totalsMatch === false ? '  ⚠️ 与服务端 totals 不一致（见异常 seat_totals_mismatch）' : ''}`)
+    for (const a of st.principals || []) {
+      L.push(`     · ${a.userId}  seats ${a.seats}  deviceLimit ${a.deviceLimit}（${a.deviceLimitSource}）  已用 ${a.used}  余 ${a.free}`)
+    }
+    L.push(`     口径：${st.definition}`)
+  }
+  const an = sec('anomalies')
+  if (an.available === false) L.push(`   ⛔ 异常清单：**答不了** —— ${an.reason}（需要 ${an.needs}）`)
+  else if ((an.count || 0) === 0) L.push(`   异常：0 条${an.note ? `（${an.note}）` : ''}`)
+  else {
+    L.push(`   异常 ${an.count} 条：`)
+    for (const it of an.items) L.push(`     ${it.severity === 'alert' ? '🚨' : '⚠️'} ${it.id} ${it.subject}：${it.detail}\n        ↳ ${it.needs}`)
+  }
+  if (j.device) {
+    const d = j.device
+    if (d.available === false) L.push(`   ⛔ 设备归属（${d.query || ''}）：**答不了** —— ${d.reason}（需要 ${d.needs}）`)
+    else L.push(`   设备归属 ${d.query}…：命中 ${d.found} 处（= 服务端 \`total\`；本页 ${d.count} 条${d.hasMore ? '，hasMore' : ''}）`
+      + `（账号 ${d.accounts.map((x) => x.userId).join('、') || '无'}${d.accounts.some((x) => x.devices.some((v) => v.releasedAt)) ? '；含已释放的绑定' : ''}）`)
+  }
+  if (j.local) {
+    const lic = j.local.license || {}
+    L.push(`   本机许可：${lic.state}${lic.present ? ` ｜ 账号 ${lic.userId || '(未写)'} ｜ 席位 ${lic.seats} ｜ 到期 ${lic.expiresAt || '-'}` : '（没有许可文件）'}`)
+    const act = j.local.activations || { count: 0 }
+    L.push(`   本机激活审计：${act.exists ? `${act.count} 行（${act.file}）` : '无（这台机器没兑换过）'}`)
+  }
+  if (j.coverage) L.push(`   📊 覆盖率：**${j.coverage}**（${Object.entries(j.coverageDetail || {}).map(([k, v]) => `${k}:${v}`).join(' ｜ ')}）`)
+  if (j.mode === 'server' && j.source && j.source.token) L.push(`   🔑 token：${j.source.token}（来源 ${j.source.tokenSource}）`)
+  if ((j.missingEndpoints || []).length) {
+    L.push(`   ⛔ 缺的服务端**只读**接口 ${j.missingEndpoints.length} 个（答不了的部分已标 available:false，**没有用 0 充数**）：`)
+    for (const e of j.missingEndpoints) {
+      L.push(`     · ${e.method} ${e.path}${e.runtime ? `\n        ↳ **本轮实测 404（路由不在）**：接口已就绪但还没部署 / base URL 指错` : `\n        ↳ ${e.why}`}`)
+    }
+  }
+  if (j.probe) {
+    L.push('   🔍 端点探测（**实测**：只发 GET；写端点一律不探；`live-call` = 本轮取数那次，`explicit` = 占位真探一次）：')
+    for (const p of j.probe) {
+      L.push(`     · ${p.method} ${p.path} ⇒ ${p.verdict}（登记 ${p.registered}${p.probed ? ` ｜ 证据 ${p.via}${p.httpStatus === null ? '' : ` HTTP ${p.httpStatus}`}` : ''}`
+        + `${p.agrees === false ? ' ｜ ⚠️ **与登记表不一致**' : ''}）`)
+    }
+  }
+  return L.join('\n')
+}