@whyshu/argent-engine 0.0.0-stage → 0.6.0

package/engine/configs/notify.json

@@ -0,0 +1,264 @@
+{
+  "_doc": "配置目录 · 通知与投递域（引擎级）。声明格式与四道门禁见 docs/Argent-宿主适配契约.md §7。webhook / 群 ID 这类「拿到就能发消息」的值按 secret 处理（页面只显示已配置/未配置）。",
+  "domain": "notify",
+  "order": 20,
+  "items": [
+    {
+      "key": "notify.feishu.chat_id",
+      "label": "飞书推送群（通用兜底）",
+      "category": "通知与投递",
+      "type": "string",
+      "source": "json",
+      "secret": true,
+      "required": false,
+      "validation": {
+        "pattern": "^oc_[A-Za-z0-9]+$|^ou_[A-Za-z0-9]+$"
+      },
+      "capability": null,
+      "vertical": null,
+      "editable": true,
+      "help": "流程通知/告警的兜底落点（能被 @ 到就能被投递，故按密钥处理）。",
+      "binding": {
+        "kind": "json",
+        "file": "config.json",
+        "field": "feishuChatId"
+      }
+    },
+    {
+      "key": "notify.daily.chat_id",
+      "label": "日报推送群",
+      "category": "通知与投递",
+      "type": "string",
+      "source": "json",
+      "secret": true,
+      "required": false,
+      "validation": {
+        "pattern": "^oc_[A-Za-z0-9]+$|^ou_[A-Za-z0-9]+$"
+      },
+      "capability": "daily-report",
+      "vertical": "mercadolibre",
+      "editable": true,
+      "help": "日报专属落点；留空则回落通用群。",
+      "binding": {
+        "kind": "json",
+        "file": "config.json",
+        "field": "mlDailyChatId"
+      },
+      "todayChain": [
+        "json",
+        "env"
+      ]
+    },
+    {
+      "key": "notify.daily.profile",
+      "label": "日报投递身份",
+      "category": "通知与投递",
+      "type": "string",
+      "source": "json",
+      "secret": false,
+      "required": false,
+      "capability": "daily-report",
+      "vertical": "mercadolibre",
+      "editable": true,
+      "help": "用哪个机器人身份发日报（客户端身份名）。",
+      "binding": {
+        "kind": "json",
+        "file": "config.json",
+        "field": "mlDailyProfile"
+      },
+      "todayChain": [
+        "json",
+        "env"
+      ]
+    },
+    {
+      "key": "notify.daily.webhook",
+      "label": "日报自定义 Webhook",
+      "category": "通知与投递",
+      "type": "string",
+      "source": "json",
+      "secret": true,
+      "required": false,
+      "capability": "daily-report",
+      "vertical": "mercadolibre",
+      "editable": true,
+      "help": "非飞书通道的自定义投递地址（URL 本身就是凭据）。",
+      "binding": {
+        "kind": "json",
+        "file": "config.json",
+        "field": "mlDailyWebhook"
+      },
+      "todayChain": [
+        "json",
+        "env"
+      ]
+    },
+    {
+      "key": "notify.daily.alert_chat_id",
+      "label": "日报告警群",
+      "category": "通知与投递",
+      "type": "string",
+      "source": "json",
+      "secret": true,
+      "required": false,
+      "capability": "daily-report",
+      "vertical": "mercadolibre",
+      "editable": true,
+      "help": "日报失败/异常告警的落点（与日报正文分开，避免刷屏）。",
+      "binding": {
+        "kind": "json",
+        "file": "config.json",
+        "field": "mlDailyAlertChatId"
+      },
+      "todayChain": [
+        "env",
+        "json"
+      ],
+      "_note": "批 3-1（2026-10-09）声明纠正：原写 [json,env]，与代码事实**相反**。读取点为证 —— scripts/daily-report.mjs:1006 逐字是 `env.ML_DAILY_ALERT_CHAT_ID || (cfg && cfg.mlDailyAlertChatId) || ML_DAILY_ALERT_CHAT_ID`（最后一项是内部群常量）⇒ 实际是 env 优先。本批**代码零改动**；链首级纠正为 env 后与规范链首级一致 ⇒ 设置页「旧优先级」提示自然消失。⛔ 这不是删提示，是声明与代码事实一致后才消失的。"
+    },
+    {
+      "key": "notify.daily.alert_profile",
+      "label": "日报告警身份",
+      "category": "通知与投递",
+      "type": "string",
+      "source": "json",
+      "secret": false,
+      "required": false,
+      "capability": "daily-report",
+      "vertical": "mercadolibre",
+      "editable": true,
+      "help": "用哪个机器人身份发日报告警。",
+      "binding": {
+        "kind": "json",
+        "file": "config.json",
+        "field": "mlDailyAlertProfile"
+      },
+      "todayChain": [
+        "env",
+        "json"
+      ],
+      "_note": "批 3-1（2026-10-09）声明纠正：同 notify.daily.alert_chat_id —— 原写 [json,env]，与代码事实相反。**5 个读取点全部 env 优先**：scripts/daily-report.mjs:1007（`env.ML_DAILY_ALERT_PROFILE || cfg.mlDailyAlertProfile`）、scripts/feishu-card.mjs:174（`dailyEnv.LARK_PROFILE || cfg.mlDailyAlertProfile`）、scripts/feishu-card.mjs:177（`fullEnv.NOTIFY_PROFILE || cfg.mlDailyAlertProfile`）、scripts/flow_preflight.py:277 与 scripts/flow_preflight.py:280（envs/shared 的 *_PROFILE 优先，cfgj.mlDailyAlertProfile 作回落）⇒ 实际是 env 优先。⚠️ feishu-card / flow_preflight 读的 env 名与声明登记的 ML_DAILY_ALERT_PROFILE 并不一致（已知缺陷，调查产物 #13 的 regression 已单列，⛔ 不在本批改）—— 此处只纠正**层级次序**，不涉及 env 名。本批代码零改动；提示因声明与事实一致而消失。"
+    },
+    {
+      "key": "notify.flow.profile",
+      "label": "流程通知身份",
+      "category": "通知与投递",
+      "type": "string",
+      "source": "envfile",
+      "secret": false,
+      "required": false,
+      "capability": null,
+      "vertical": null,
+      "editable": false,
+      "help": "流程通知默认用哪个身份投递。",
+      "binding": {
+        "kind": "envfile",
+        "file": "fulfillment.env",
+        "env": "NOTIFY_PROFILE",
+        "vertical": "mercadolibre"
+      }
+    },
+    {
+      "key": "notify.flow.lark_profile",
+      "label": "流程读表身份",
+      "category": "通知与投递",
+      "type": "string",
+      "source": "envfile",
+      "secret": false,
+      "required": false,
+      "capability": null,
+      "vertical": null,
+      "editable": false,
+      "help": "流程读写飞书表默认用的 CLI 身份。",
+      "binding": {
+        "kind": "envfile",
+        "file": "fulfillment.env",
+        "env": "LARK_PROFILE",
+        "vertical": "mercadolibre"
+      }
+    },
+    {
+      "key": "notify.full.internal_chat_id",
+      "label": "货件流程内部群",
+      "category": "通知与投递",
+      "type": "string",
+      "source": "envfile",
+      "secret": true,
+      "required": false,
+      "capability": "full",
+      "vertical": "mercadolibre",
+      "editable": false,
+      "help": "货件流程的过程通知落点（内部群）。",
+      "binding": {
+        "kind": "envfile",
+        "file": "fulfillment.env",
+        "env": "FULL_INTERNAL_CHAT_ID",
+        "vertical": "mercadolibre"
+      }
+    },
+    {
+      "key": "notify.full.done_chat_id",
+      "label": "货件完成通知群",
+      "category": "通知与投递",
+      "type": "string",
+      "source": "envfile",
+      "secret": true,
+      "required": false,
+      "capability": "full",
+      "vertical": "mercadolibre",
+      "editable": false,
+      "help": "货件完成后的对外通知落点。",
+      "binding": {
+        "kind": "envfile",
+        "file": "fulfillment.env",
+        "env": "FULL_DONE_CHAT_ID",
+        "vertical": "mercadolibre"
+      }
+    },
+    {
+      "key": "notify.full.done_profile",
+      "label": "货件完成通知身份",
+      "category": "通知与投递",
+      "type": "string",
+      "source": "envfile",
+      "secret": false,
+      "required": false,
+      "capability": "full",
+      "vertical": "mercadolibre",
+      "editable": false,
+      "help": "货件完成通知用哪个身份投递。",
+      "binding": {
+        "kind": "envfile",
+        "file": "fulfillment.env",
+        "env": "FULL_DONE_PROFILE",
+        "vertical": "mercadolibre"
+      }
+    },
+    {
+      "key": "notify.full.mode",
+      "label": "货件通知模式",
+      "category": "通知与投递",
+      "type": "enum",
+      "source": "envfile",
+      "secret": false,
+      "required": false,
+      "validation": {
+        "enum": [
+          "final",
+          "feishu"
+        ]
+      },
+      "capability": "full",
+      "vertical": "mercadolibre",
+      "editable": false,
+      "help": "final = 只在终态通知；feishu = 恢复旧行为（每步都发）。",
+      "binding": {
+        "kind": "envfile",
+        "file": "fulfillment.env",
+        "env": "FULL_NOTIFY_MODE",
+        "vertical": "mercadolibre"
+      }
+    }
+  ],
+  "entries": []
+}

package/engine/core/cli/argent.mjs

@@ -0,0 +1,277 @@
+#!/usr/bin/env node
+/**
+ * Argent 单入口（0.3 P1）—— `argent <verb> [args…]`
+ *
+ * 目的：把宿主（dsh / 未来任何 agent / 云端 MCP）对 Argent 的依赖**收敛成一条命令族**，
+ * 而不是散落的 `scripts/*.py|mjs` 文件名 —— 这是"抽离基座"的第一步。
+ *
+ * ⚠️ **薄别名层**：本文件**不复制任何业务逻辑**，只把 verb 映射到既有脚本（或 core/lib 里的共享实现）
+ * 并把参数原样透传 ⇒ 行为与今天直接调脚本**完全一致**（P1 的红线：不动现网行为）。
+ * 契约见 core/contracts/argent.contracts.json。
+ *
+ * 2026-10-03 修两处"假绿"缺陷（均有复现原文，见各自模块头注释）：
+ *   · D1 `ledger` 返回假空 ⇒ 走 `core/lib/ledger.mjs`（读全量 → 过滤 → 再取末尾 N 行；回显生效条件）
+ *   · D3 解释器单候选 + 空 catch 吞异常 ⇒ 走 `core/lib/python.mjs`（多候选 + 响亮失败）
+ *
+ * 2026-10-03 P1 第二批：
+ *   · `license` 组落地（status｜verify｜install｜request｜renew｜explain，§3.5①）：判定点唯一在 CLI 进程内、
+ *     离线可验；**旧行为**（恒 `ok:true` 只回计费巡检文本）正是 §2.2④ 要修的假绿；
+ *   · **写类 verb 接许可闸门**（`flow claim --apply` / `writeback --yes`）：调既有
+ *     `scripts/license-gate.mjs`（**不复制判据**），默认 `observe`（只留证据不拦），`enforce` 才拒写；
+ *   · `--help --json` 改为报**代码里实际存在**的 verb/子命令（此前直接照抄契约 ⇒ 门禁的
+ *     "契约声明了、CLI 里没有"这一向恒绿，是假绿空间）。
+ *
+ * 2026-10-03 P1 第三批（M1 外围三件）：
+ *   · `notify`（P2 webhook 一条）：端口 + 通道实现落在 `core/lib/notify/`，**判据与投递分离**
+ *     （去重/审计/dry-run 在 verb 层，通道只负责"送到没送到"）；默认 dry-run，真发要 `--apply`；
+ *   · `init`（数据目录画像，默认 dry-run，`--apply` 才建目录；⛔ 不写 settings/credentials）、
+ *     `versions`（五面对账）、`audit`（4 处审计 JSONL 只读汇总）、`flow list`（注册表只读清单）。
+ *
+ * 2026-10-03 P1 首批（`flow claim`）：
+ *   · `claim` 从"其实是分诊"改成**真正的原子认领**（包 `scripts/flow_claim.py`，退出码 3 ⇒ 0 + empty:true）；
+ *     旧行为逐字保留在 `flow triage` / `claim --plan-only`；
+ *   · 新增 `flow` 组（claim｜triage）+ `triage` 别名；适配层在 `core/lib/claim.mjs`（A1/A2/A3 口径）；
+ *   · `--help --json` 输出机器可读的 verb 清单（门禁 `scripts/check-judgment-drift.mjs` 的"代码侧"来源）。
+ *
+ * 2026-10-03 P4 收尾（M1 判据③）：
+ *   · `doctor --customer` = **客户机一页式自检**（`core/lib/doctor-customer.mjs`）：整机、只读、
+ *     **不要求本机装 dsh**（无宿主 ⇒ 宿主档事实记 `applicable:false`「本档不适用」，**不算 FAIL**）；
+ *     退出码按 A1：全 ok/warn ⇒ `0`（warn 只在 JSON 标记）、存在 fail ⇒ `1`、用法错误 ⇒ `2`；
+ *   · `doctor --flow <id> [--online]` 的旧行为**逐字保留**（仍转发 `scripts/flow_preflight.py`，判据不重复）；
+ *   · ⚠️ `doctor --help` 现在打**自检形态**的用法（那份用法里同时写了单流程形态的出口）；
+ *     单流程的前置检查帮助仍可直接跑 `python3 scripts/flow_preflight.py --help`。
+ */
+import { execFileSync } from 'node:child_process'
+import { readFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { resolveSop } from '../lib/sop.mjs'
+import { queryLedger, resolveLedgerFlow } from '../lib/ledger.mjs'
+import { pickPython } from '../lib/python.mjs'
+import { resolveDataDir } from '../lib/argent-datadir.mjs'
+import { buildInvocation, runFlowVerb } from '../lib/claim.mjs'
+import { runLicenseVerb, LICENSE_SUBCOMMANDS } from '../lib/license.mjs'
+import { applyGate, gateWrite } from '../lib/license-guard.mjs'
+import { loadRegistry, resolveFlow } from '../lib/flow-registry.mjs'
+import { runNotifyVerb } from '../lib/notify/verb.mjs'
+import { runInitVerb } from '../lib/init.mjs'
+import { runVersionsVerb } from '../lib/versions.mjs'
+import { runAuditVerb } from '../lib/audit.mjs'
+import { runFlowListVerb } from '../lib/flow-list.mjs'
+import { runDoctorCustomerVerb } from '../lib/doctor-customer.mjs'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const REPO = resolve(HERE, '..', '..')
+// 数据目录：内核三级链（唯一判据）
+const DATA_DIR = resolveDataDir({ env: process.env }).dir
+const script = (p) => join(REPO, p)
+
+// 解释器（D3）：**多候选 + 响亮失败**。惰性解析 —— 不用 Python 的 verb（version/license，
+// 以及不带 --flow 的 ledger）既不付探测开销，也不因缺解释器而失败（"无宿主机器上 version 仍可用"）。
+let _py = null
+const python = () => (_py ||= pickPython({ env: process.env, dataDir: DATA_DIR, repo: REPO }))
+const pyPath = () => { const p = python(); return p.ok ? p.path : '' }
+const pyFailure = () => { const p = python(); return p.ok ? null : p.diagnostics }
+
+/** `flow claim` / `flow triage` / `claim --plan-only`：同一个适配层（退出码翻译 + A2 回显）。 */
+const flowVerb = (args) => runFlowVerb(args, { repo: REPO, py: pyPath(), pyFailure: pyFailure() })
+
+// ── 写类 verb 的许可闸门（P1 第二批，§3.6① 第 4 步）──────────────────────────
+// **不复制判据**：调既有 `scripts/license-gate.mjs`（flow-trigger.sh:238 用的同一个；判定↔取证一份），
+// 本层只决定"这次调用是不是真写"以及"被拒时怎么回"。默认 `observe` ⇒ **只留证据、不拦**。
+const CONFIRM = ['--apply', '--confirm', '--yes', '--write']
+const isRealWrite = (args) => CONFIRM.some((f) => args.includes(f)) && !args.includes('--dry-run')
+
+/**
+ * 闸门上下文：能力 id 与业务线**从注册表解析**（与 flow-trigger.sh 用 `flow_config.py --get capability`
+ * 同源）。注册表读不到 ⇒ 退化为"以流程名当能力"并**如实标注**（宁可不拦 / 不可误停，与 flow-trigger.sh
+ * 的 `LICENSE_CAP="$CAP"; [ -n "$LICENSE_CAP" ] || LICENSE_CAP="$FLOW"` 逐字同口径）。
+ */
+function gateContext(flow) {
+  const py = pyPath()
+  if (!py) return { cap: flow, vertical: null, capSource: 'fallback_no_python' }
+  const reg = loadRegistry({ repo: REPO, py })
+  if (!reg.ok) return { cap: flow, vertical: null, capSource: `fallback_registry:${reg.reason}` }
+  const r = resolveFlow({ input: flow, doc: reg.doc })
+  const f = (reg.doc.flows || {})[r.canonical] || {}
+  const vertical = r.canonical.includes('.') ? r.canonical.split('.')[0] : null
+  return { cap: String(f.capability || r.local || flow), vertical, capSource: 'registry' }
+}
+
+const runGate = (flow) => {
+  const ctx = gateContext(flow)
+  const gate = gateWrite({ repo: REPO, flow, cap: ctx.cap, vertical: ctx.vertical, env: process.env })
+  return { ...gate, capSource: ctx.capSource, cap: ctx.cap, vertical: ctx.vertical, flow }
+}
+
+/** 被闸门拒绝（只在 `enforce` 下发生）：**整体拒绝 + 零副作用**（不认领、不回写、不落台账）。 */
+const deniedEnvelope = (name, flow, gate) => {
+  const json = applyGate({ ok: true, empty: false, code: 0, reason: null, verb: name, flow }, gate)
+  return {
+    json,
+    human: `⛔ 许可闸门[enforce]：${gate.human || gate.reason} ⇒ 拒绝 ${name}（零副作用：没有写任何东西）`,
+    stderr: '', exit: 1,
+  }
+}
+
+/** `claim`（含 `flow claim`）：真写前过闸门；dry-run 不查（不打扰只读路径，也不污染证据）。 */
+function gatedClaim(args) {
+  const built = buildInvocation(args)
+  const flow = built.ok ? built.echo.flow : (argOf(args, '--flow') || '?')
+  const gate = built.ok && !built.dryRun ? runGate(flow) : null
+  if (gate && gate.blocked) return deniedEnvelope('claim', flow, gate)
+  const res = flowVerb(args)
+  if (gate) res.json = applyGate(res.json, gate)
+  return res
+}
+
+/** `writeback`：真写（`--yes`/`--write`）前过闸门；默认 dry-run 不查。 */
+function gatedWriteback(args) {
+  const flow = argOf(args, '--flow') || 'wenyao-invoice'   // 该回写器服务的就是文鳐发票流程
+  const gate = isRealWrite(args) ? runGate(flow) : null
+  if (gate && gate.blocked) return deniedEnvelope('writeback', flow, gate)
+  const out = run('node', [script('scripts/wenyao-invoice-writeback.mjs'), ...args])
+  return gate ? applyGate(out, gate) : out
+}
+
+
+/** 未知子命令：A1 的"用法错误"（2）+ A2 的 reason（**不是**静默成功）。 */
+const unknownSub = (sub) => ({
+  json: { ok: false, empty: false, code: 2, reason: 'unknown_subcommand',
+    error: `未知子命令：${sub || '(缺)'}（可用：claim、triage、list）`,
+    flow: null, flowPrefix: null, flowKnown: false, dryRun: null, casesFromDir: null },
+  human: `❌ unknown_subcommand：未知子命令 ${sub || '(缺)'}（可用：claim、triage、list）`,
+  stderr: '', exit: 2,
+})
+
+/** `argent flow <claim|triage|list> …` —— 组 verb 只做分派，不另立判据。 */
+const flowGroup = (args) => {
+  const [sub, ...rest] = args
+  if (sub === 'claim') return gatedClaim(rest)
+  if (sub === 'triage') return flowVerb(rest.includes('--plan-only') ? rest : [...rest, '--plan-only'])
+  // P1 第三批：`flow list` = 注册表只读清单（薄包 flow_registry.py --json，不实现合并）
+  if (sub === 'list') return runFlowListVerb(rest, { repo: REPO, env: process.env })
+  if (sub === '--help' || sub === '-h') {          // 组帮助不是"用法错误"：列出子命令后 exit 0
+    const contracts = JSON.parse(readFileSync(join(HERE, '..', 'contracts', 'argent.contracts.json'), 'utf8'))
+    return { json: { ok: true, flow: 'flow', subcommands: Object.keys(contracts.verbs.flow.subcommands || {}) },
+      human: `argent flow <子命令> —— ${contracts.verbs.flow.desc}\n`
+        + Object.entries(contracts.verbs.flow.subcommands || {}).map(([s, d]) => `  ${s.padEnd(8)} ${d}`).join('\n'),
+      stderr: '', exit: 0 }
+  }
+  return unknownSub(sub)
+}
+
+/** verb → 具体实现（薄映射；后续逐步把实现搬进 core/，宿主侧不用改） */
+const VERBS = {
+  version: () => {
+    const argent = (readFileSync(script('VERSION'), 'utf8') || '').trim()
+    let dsh = ''
+    try { dsh = execFileSync('dsh', ['--version'], { encoding: 'utf8' }).trim() } catch { /* 不在 PATH */ }
+    return { ok: true, argent, dsh }
+  },
+  sop: (args) => resolveSop(argOf(args, '--flow') || 'full', { repo: REPO, py: pyPath(), pyFailure: pyFailure() }),
+  source: (args) => runPy([script('scripts/flow_source.py'), ...args]),
+  flow: (args) => flowGroup(args),
+  // P1 首批：`claim` = **真认领**（默认 dry-run；`--plan-only` 走旧的分诊行为）
+  // P1 第二批：**真写**（--apply/--confirm）前过许可闸门（observe 只留证据；enforce 直接拒绝）
+  claim: (args) => gatedClaim(args),
+  // 旧 `claim` 的行为（只出计划）——名字还给它，行为逐字保留
+  triage: (args) => flowVerb(args.includes('--plan-only') ? args : [...args, '--plan-only']),
+  gap: (args) => runPy([script('scripts/flow_preflight.py'), ...args]),
+  // 真写（--yes/--write）前过许可闸门；dry-run（默认）不查 —— 写操作的判据一致，读操作不打扰
+  writeback: (args) => gatedWriteback(args),
+  report: (args) => runPy([script('scripts/flow_failure.py'), ...args]),
+  // D1：读全量 → 过滤 → 再取末尾 N 行；`flow` 回显**实际生效**的过滤条件（null = 未过滤）
+  ledger: (args) => queryLedger({
+    file: join(DATA_DIR, 'flow-ledger.jsonl'),
+    flow: argOf(args, '--flow'),
+    tailInput: argOf(args, '--tail'),
+    resolveFilter: (f) => resolveLedgerFlow(f, { repo: REPO, py: pyPath(), pyFailure: pyFailure() }),
+  }),
+  // P1 第二批：许可组（status｜verify｜install｜request｜renew｜explain）——判定点唯一在 CLI 进程内
+  license: (args) => runLicenseVerb(args, { repo: REPO, env: process.env }),
+  // `doctor`：**两种形态，判据不重复**。
+  //   · `doctor --customer`（M1 判据③）= 客户机一页式自检：整机、**只读**、**不要求 dsh**
+  //     （无宿主 ⇒ 宿主档事实记「本档不适用」，不算 FAIL）—— 见 core/lib/doctor-customer.mjs；
+  //   · `doctor --flow <id> [--online]`（旧行为，逐字保留）= 单流程前置检查：仍转发
+  //     `scripts/flow_preflight.py`（同一个脚本，`--customer` 之前它要求 `--flow` ⇒ exit 2）。
+  doctor: (args) => (args.includes('--customer') || args.includes('--help') || args.includes('-h')
+    ? runDoctorCustomerVerb(args, { repo: REPO, env: process.env })
+    : runPy([script('scripts/flow_preflight.py'), ...args])),
+  // ── P1 第三批（2026-10-03）：补齐 M1 判据的外围三件 ──────────────────────────
+  // notify：通道选择 + 幂等 + dry-run（判断⑩；适配层在 core/lib/notify/，通道实现可替换）
+  notify: (args) => runNotifyVerb(args, { repo: REPO, env: process.env }),
+  // init：数据目录画像（判断⑧）；默认 dry-run，--apply 才建目录（⛔ 不写 settings/credentials）
+  init: (args) => runInitVerb(args, { repo: REPO, env: process.env }),
+  // versions：CLI/内核/契约/补丁/能力包版本对账（只读）
+  versions: (args) => runVersionsVerb(args, { repo: REPO, env: process.env }),
+  // audit：审计 JSONL 只读汇总（先全量→过滤→排序→取末尾 N 行，不回退成"先截断"）
+  audit: (args) => runAuditVerb(args, { repo: REPO, env: process.env }),
+}
+
+function run(bin, argv) {
+  try {
+    const out = execFileSync(bin, argv, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] })
+    return { ok: true, output: out }
+  } catch (e) {
+    return { ok: false, code: e.status ?? 1, output: String(e.stdout || ''), error: String(e.stderr || e.message).slice(0, 400) }
+  }
+}
+
+/** 需要 Python 的 verb：解释器不可用时**响亮失败**（不 exec 一个不存在的路径当"没结果"）。 */
+function runPy(argv) {
+  const p = python()
+  if (!p.ok) return { ok: false, code: 2, reason: 'python_unavailable', error: p.diagnostics }
+  return run(p.path, argv)
+}
+
+const argOf = (args, name) => { const i = args.indexOf(name); return i > -1 ? args[i + 1] : '' }
+
+const [verb, ...args] = process.argv.slice(2)
+if (!verb || verb === '--help' || verb === '-h') {
+  const contracts = JSON.parse(readFileSync(join(HERE, '..', 'contracts', 'argent.contracts.json'), 'utf8'))
+  // ⚠️ **代码侧清单**：列 `VERBS` 里**真的有实现**的（P1 第二批改）——此前直接照抄契约，
+  // 于是门禁 `check-judgment-drift` 的 "契约声明了 verb，CLI 里没有"（R1a）**恒绿**（假绿空间）。
+  // 子命令同理：只报本进程真的分派得动的那些。
+  const SUBCOMMANDS = { flow: ['claim', 'triage', 'list'], license: [...LICENSE_SUBCOMMANDS] }
+  const implemented = Object.keys(VERBS)
+  const meta = (name) => {
+    const c = contracts.verbs[name] || {}
+    return { kind: c.kind || 'read', desc: c.desc || '(未在契约声明 —— 门禁会报 R1b 漂移)' }
+  }
+  // `--help --json`：机器可读的 verb 清单（门禁/宿主用它拿"代码里实际存在什么"，不用解析人话）
+  if (args.includes('--json')) {
+    const verbs = implemented.map((name) => ({
+      name, ...meta(name),
+      ...(SUBCOMMANDS[name] ? { subcommands: SUBCOMMANDS[name] } : {}),
+      ...((contracts.verbs[name] || {}).aliases ? { aliases: contracts.verbs[name].aliases } : {}),
+    }))
+    console.log(JSON.stringify({ ok: true, argent: (readFileSync(script('VERSION'), 'utf8') || '').trim(), verbs }, null, 2))
+    process.exit(0)
+  }
+  console.log('argent <verb> [args…]   —— Argent 单入口（0.3 P1，薄别名层）\n')
+  for (const name of implemented) {
+    const c = meta(name)
+    console.log(`  ${name.padEnd(10)} [${c.kind}] ${c.desc}`)
+    for (const s of SUBCOMMANDS[name] || []) console.log(`    · ${s.padEnd(8)} ${(contracts.verbs[name]?.subcommands || {})[s] || ''}`)
+  }
+  process.exit(0)
+}
+const fn = VERBS[verb]
+if (!fn) { console.error(`未知 verb：${verb}（可用：${Object.keys(VERBS).join(', ')}）`); process.exit(2) }
+const AS_JSON = args.includes('--json') || ['version', 'ledger'].includes(verb)
+// P1 第三批：`notify` 的投递是异步的（`--json <payload>` 与 A2 开关同名，由 parseNotifyArgs 自己判形态）
+// ⇒ 顶层 await（本文件是 ESM）；同步 verb 不受影响（await 一个非 Promise 值是恒等的）。
+const raw = await fn(args)
+// 适配层 verb 返回信封 `{json, human, stderr}`：人类输出与 JSON 载荷分离 ⇒ `--json` 时 stdout 只有合同字段
+const isEnvelope = Boolean(raw && typeof raw === 'object' && raw.json && typeof raw.json === 'object')
+const out = isEnvelope ? raw.json : raw
+const human = isEnvelope ? raw.human : null
+if (isEnvelope && raw.stderr) process.stderr.write(raw.stderr.endsWith('\n') ? raw.stderr : `${raw.stderr}\n`)
+if (AS_JSON) console.log(JSON.stringify(out, null, 2))
+else console.log(human !== null ? human : (typeof out === 'string' ? out : (out.output || JSON.stringify(out, null, 2))))
+// 失败一律**留痕**（D3：诊断必须看得见；退出码沿用既有口径：ok:false ⇒ code 或 1）
+if (out && out.ok === false && out.error) console.error(String(out.error))
+// A1：`3` **只**表示许可宽限放行 —— 写类 verb 在宽限期内照常完成，但必须用 3 让调用方上报
+const exitCode = out && out.ok === false ? (out.code || 1) : (out && out.code === 3 ? 3 : 0)
+process.exit(exitCode)