@whyshu/argent-engine 0.0.0-stage → 0.6.0

package/engine/core/lib/argent-datadir.mjs

@@ -0,0 +1,223 @@
+/**
+ * Argent 数据目录 —— **唯一判据**（三级解析链 + 隔离安全阀）。
+ *
+ * ══════════════════════════════════════════════════════════════════════════
+ * 一、为什么要有这个文件（2026-10-01 桌面端隔离事故）
+ * ══════════════════════════════════════════════════════════════════════════
+ * 官方桌面端（`/Applications/DeepSeek Harness.app`，内置 dsh 0.2.0-rc.2）能承载 Argent，
+ * 但**首次隔离启动时误写了生产一行**：`plugins/argent-flow` 的 `dataDir` 只认
+ * `ARGENT_DATA_DIR`，未设时直接回退 `homedir()/.dsh/argent`，**完全不看 `DSH_HOME`**
+ * ⇒ 以 `DSH_HOME=~/.dsh-desktop-trial` 起的隔离实例把日志追加进了
+ * 生产 `~/.dsh/argent/flow-watch.log`。
+ *
+ * 更反直觉的风险在失败回路：**只隔离 `ARGENT_DATA_DIR` 而不放暂停开关更危险** ——
+ * 隔离目录里没有 `PAUSE_FLOW_WATCH`，泵会**真的去扫/派发生产流程**（抢客户机的活）。
+ * 故本文件除了统一解析链，还导出 `loopGate()` 安全阀：**数据目录一旦偏离默认
+ * `~/.dsh/argent`（被 `DSH_HOME` 或 `ARGENT_DATA_DIR` 改到别处），失败回路默认暂停**，
+ * 除非显式 `ARGENT_ALLOW_ISOLATED_PUMP=1`。
+ *
+ * ══════════════════════════════════════════════════════════════════════════
+ * 二、解析链（**全仓库唯一一份**，插件/脚本/内核都从这里取）
+ * ══════════════════════════════════════════════════════════════════════════
+ *     ARGENT_DATA_DIR  →  $DSH_HOME/argent  →  默认目录
+ *      （显式隔离）        （宿主 home 隔离）      （见下"默认目录两步走"）
+ *
+ * **默认目录（§6.2 Q6 选项 B，2026-10-03 批准；两步走：① 存在即沿用 → ② 新装 `~/.argent`）**
+ *   · **存在即沿用**：`~/.dsh/argent` **已存在** ⇒ 它就是默认目录 —— **老机器**（装过 dsh/Argent、
+ *     数据都在这儿）绝不被误判成"隔离"（隔离态会让失败回路**默认暂停** ⇒ 老机器集体停摆）；
+ *   · 否则（**新装、无宿主**）⇒ `~/.argent`（宿主无关的 home 位置，不再借 `.dsh` 这个宿主目录名）。
+ *   · 判据锚在 **OS home**（只认 `$HOME`）：默认目录里**不含** `DSH_HOME`，否则隔离实例会把自己当默认。
+ *   · **优先级链不变**：只改"默认"这一级的**取值**，不改链的结构（`DSH_HOME` 一级必须留着 ——
+ *     dsh 多实例隔离靠它）。
+ *   · ⚠️ **残留风险（如实登记，别当没有）**：判据是"老位置在不在"，所以**先**在 `~/.argent` 落过
+ *     数据、**后来**才出现 `~/.dsh/argent`（例：先只用 CLI，之后才跑安装器）的机器，默认目录会
+ *     切回老位置 ⇒ 可能读到空台账。已知处置：`argent init --json` 会把**两个候选路径 + 是否在用**
+ *     如实打出来；要钉死目录用 `ARGENT_DATA_DIR`（或 `DSH_HOME`）显式指定。
+ *
+ * ⚠️ **不允许**在任何插件/脚本里另写一份这条链（哪怕只有两级）。历史教训就是
+ *    "每个文件各自 `ARGENT_DATA_DIR || ~/.dsh/argent`" ⇒ 有的看 `DSH_HOME`、有的不看，
+ *    隔离实例一半写隔离目录、一半写生产。
+ *
+ * 分层：本文件是 **L1 内核**（只用 node 内建，不 import 任何宿主模块）。
+ *   · `core/**`    → 相对路径直接 import（同层）。
+ *   · `scripts/**` → 相对路径 import `../core/lib/argent-datadir.mjs`（既有先例：
+ *                    scripts/check-license.mjs 就是 import core/lib/license-file.mjs）。
+ *   · `plugins/**`（L2 宿主壳）→ profile 里插件是 `node_modules/<pkg>` 下的独立包，
+ *                    **静态 import 不到内核** ⇒ 运行时 `await import()` 内核文件
+ *                    （见各插件的 `KERNEL` 加载段与 `docs/Argent-宿主适配契约.md` §3.3）；
+ *                    取不到内核 ⇒ 一律 **fail-closed**（阀门保持"暂停"），
+ *                    **绝不**退回本地重写的判据。
+ *
+ * 跑法（回归）：`node scripts/tests/argent-datadir.test.mjs`
+ *              `node scripts/tests/argent-datadir-parity.test.mjs`（JS ⟷ Python **逐字段**对拍）
+ */
+
+import { existsSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join, resolve as resolvePath } from 'node:path'
+
+/** 显式数据目录（最高优先级）。 */
+export const ENV_DATA_DIR = 'ARGENT_DATA_DIR'
+/** 宿主 home（dsh 多实例隔离开关）。 */
+export const ENV_DSH_HOME = 'DSH_HOME'
+/** 隔离目录下**显式**放开失败回路的开关（必须精确等于 `1`）。 */
+export const ENV_ALLOW_ISOLATED_PUMP = 'ARGENT_ALLOW_ISOLATED_PUMP'
+
+/** **老机器**的数据目录（`~/.dsh/argent`）：存在即沿用 —— 这一级同时是"客户机现状"。 */
+export const DATA_DIR_SEGMENTS = ['.dsh', 'argent']
+/** **新装（无宿主）**的默认目录：`~/.argent`（§6.2 Q6 选项 B）；只在老位置不存在时生效。 */
+export const NO_HOST_DATA_DIR_SEGMENTS = ['.argent']
+
+/**
+ * OS 用户 home（只认 `$HOME`，**故意不认 `DSH_HOME`**）。
+ * 判据"是否偏离默认目录"必须锚在 OS home 上，否则隔离实例会把自己当成默认。
+ */
+export function osHome(env = process.env) {
+  const h = env && env.HOME ? String(env.HOME) : ''
+  return h || homedir()
+}
+
+/**
+ * 宿主 home：`$DSH_HOME` → `~/.dsh`（dsh 多实例隔离：每个实例独立 home）。
+ * 注意这不是数据目录，是**数据目录的父目录**。
+ */
+export function dshHomeOf(env = process.env, home = osHome(env)) {
+  const v = env && env.DSH_HOME ? String(env.DSH_HOME) : ''
+  return v || join(home, '.dsh')
+}
+
+/** **老位置** `~/.dsh/argent`（**只算路径，不看存在性**；存在性判据见 `legacyDataDirExists`）。 */
+export function legacyDataDir(env = process.env, home = osHome(env)) {
+  return join(home, ...DATA_DIR_SEGMENTS)
+}
+
+/**
+ * **"存在即沿用"的判据本体**：老位置 `~/.dsh/argent` 在不在？
+ *
+ * 为什么单独一个函数：这条判据决定"默认目录是哪一个"，而默认目录又决定 `isolated`
+ * （安全阀据此暂停失败回路）⇒ 它必须**只有一处实现**，且能被夹具逐态验证。
+ * `exists` 可注入（夹具用），缺省 `fs.existsSync`（**不是** `statSync().isDirectory()`：
+ * 与 Python 侧 `os.path.exists` 逐字同解 —— 存在性判据不许两边各写一套）。
+ */
+export function legacyDataDirExists(env = process.env, home = osHome(env), exists = existsSync) {
+  return Boolean(exists(legacyDataDir(env, home)))
+}
+
+/**
+ * 默认数据目录（**两步走**，实施方案 P1③ / §6.2 Q6 选项 B，2026-10-03 已批准）：
+ *   · ① **存在即沿用**：`~/.dsh/argent` **已存在** ⇒ 它就是默认目录（**老机器永不被误判隔离**；
+ *     隔离态会让失败回路默认暂停 ⇒ 直接停摆）；
+ *   · ② 不存在（**新装、无宿主**）⇒ `~/.argent`。
+ *
+ * 两步走的意义（为什么不是"直接改默认值"）：顺序反了会让**所有老机器**的目录瞬间被判成隔离、
+ * 失败回路集体停摆；故 ①（存在即沿用 + 不变量回归）先落，②（改这一行的取值）后落，两批都带
+ * JS/Python 对拍（`scripts/tests/argent-datadir-parity.test.mjs`）。
+ */
+export function defaultDataDir(env = process.env, home = osHome(env)) {
+  if (legacyDataDirExists(env, home)) return legacyDataDir(env, home)          // ① 存在即沿用（老机器）
+  return join(home, ...NO_HOST_DATA_DIR_SEGMENTS)                              // ② 新装（无宿主）⇒ ~/.argent
+}
+
+/**
+ * 三级链解析。
+ * @param {{ env?: Record<string, string|undefined>, home?: string }} [opts]
+ * @returns {{ dir: string, source: 'ARGENT_DATA_DIR'|'DSH_HOME'|'default', isolated: boolean,
+ *             defaultDir: string, dshHome: string, raw: string }}
+ *   `dir`       解析结果（绝对路径；`ARGENT_DATA_DIR` 是相对路径时按 cwd 解析）
+ *   `source`    命中链上的哪一级（日志/面板用）
+ *   `isolated`  `dir` **不等于**默认目录（`defaultDataDir()`：老机器 = `~/.dsh/argent`）⇒ 隔离态（安全阀据此生效）
+ */
+export function resolveDataDir(opts = {}) {
+  const env = opts.env || process.env
+  const home = opts.home || osHome(env)
+  const defaultDir = defaultDataDir(env, home)
+  const dshHome = dshHomeOf(env, home)
+  const explicit = env && env[ENV_DATA_DIR] ? String(env[ENV_DATA_DIR]) : ''
+  const raw = explicit || (env && env[ENV_DSH_HOME] ? join(dshHome, 'argent') : defaultDir)
+  const dir = resolvePath(raw)
+  return {
+    dir,
+    raw,
+    source: explicit ? ENV_DATA_DIR : (env && env[ENV_DSH_HOME] ? ENV_DSH_HOME : 'default'),
+    isolated: dir !== resolvePath(defaultDir),
+    defaultDir: resolvePath(defaultDir),
+    dshHome,
+  }
+}
+
+/** 解析结果的单行描述（日志用）。 */
+export function describeDataDir(resolved) {
+  if (!resolved || !resolved.dir) return '数据目录未解析（内核解析器不可用）'
+  return `${resolved.dir}（来源=${resolved.source}${resolved.isolated ? '，隔离' : ''}）`
+}
+
+/**
+ * 对**任意**数据目录求安全阀（宿主把 `dataDir` 放在插件配置里显式指定时用）。
+ * 判据仍在内核：这里只把"配置里的目录"包装成与 `resolveDataDir()` 同形的结果，
+ * 隔离判定**不**在调用方重写。
+ */
+export function loopGateForDir(dir, opts = {}) {
+  const env = opts.env || process.env
+  const home = opts.home || osHome(env)
+  const raw = String(dir || '')
+  if (!raw) return loopGate(null, { env })
+  const defaultDir = resolvePath(defaultDataDir(env, home))
+  const abs = resolvePath(raw)
+  return loopGate({
+    dir: abs,
+    raw,
+    source: 'config',
+    isolated: abs !== defaultDir,
+    defaultDir,
+    dshHome: dshHomeOf(env, home),
+  }, { env })
+}
+
+/**
+ * **隔离安全阀**：失败回路该不该跑。
+ *
+ * 规则（唯一判据，插件不得自行判断）：
+ *   · 解析器不可用（`resolved` 为空 / `dir` 为空）⇒ **暂停**（fail-closed）；
+ *   · `isolated`（数据目录 ≠ 默认目录，判据 = `defaultDataDir()`）且未显式
+ *     `ARGENT_ALLOW_ISOLATED_PUMP=1` ⇒ **暂停**，并给出可照做的开启提示；
+ *   · 其余 ⇒ 允许运行。
+ *
+ * @returns {{ enabled: boolean, paused: boolean, reason: string, isolated: boolean,
+ *             dir: string, notice: string }}
+ */
+export function loopGate(resolved, opts = {}) {
+  const env = opts.env || process.env
+  const allow = String((env && env[ENV_ALLOW_ISOLATED_PUMP]) || '') === '1'
+  const enabledText = `设 ${ENV_ALLOW_ISOLATED_PUMP}=1 可开启`
+  if (!resolved || !resolved.dir) {
+    return {
+      enabled: false,
+      paused: true,
+      reason: 'datadir-unresolved',
+      isolated: true,
+      dir: '',
+      notice: `失败回路保持暂停：内核数据目录解析器不可用（core/lib/argent-datadir.mjs 没找到）⇒ 不敢猜目录。修好后重启即可。`,
+    }
+  }
+  if (resolved.isolated && !allow) {
+    return {
+      enabled: false,
+      paused: true,
+      reason: 'isolated-data-dir',
+      isolated: true,
+      dir: resolved.dir,
+      notice: `失败回路因隔离数据目录而默认暂停（${describeDataDir(resolved)}）；`
+        + `隔离目录通常没有 PAUSE_FLOW_WATCH，默认运行会误扫/派发生产流程 ⇒ ${enabledText}`,
+    }
+  }
+  return {
+    enabled: true,
+    paused: false,
+    reason: resolved.isolated ? 'isolated-allowed' : 'default-dir',
+    isolated: Boolean(resolved.isolated),
+    dir: resolved.dir,
+    notice: resolved.isolated
+      ? `失败回路已按 ${ENV_ALLOW_ISOLATED_PUMP}=1 在隔离数据目录上开启（${describeDataDir(resolved)}）——请确认它扫的是隔离源，不是生产`
+      : '',
+  }
+}

package/engine/core/lib/audit.mjs

@@ -0,0 +1,187 @@
+/**
+ * `argent audit` —— **审计只读汇总**（P1；§2.1 审计行、策划案⑮）。只读，永不写。
+ *
+ * 今天仓库里有 4 处审计 JSONL，散在数据目录的不同子目录里，谁也不知道"这台机器到底记了什么"。
+ * 本 verb 把"读审计"收口成一条命令：**先读全量 → 按 `--since` 过滤 → 合并排序 → 取末尾 N 行**
+ * （顺序照 D1 的教训钉死：**先截断后过滤**会让空结果分不清"真没有"和"被截掉了"）。
+ *
+ * ## 审计源登记表（`SOURCES`）
+ * | id | 相对数据目录 | 写它的地方 | 判据来源 |
+ * |---|---|---|---|
+ * | `invoice-writeback` | `invoice-writeback/audit.jsonl` | `scripts/wenyao-invoice-writeback.mjs` | 判断⑨（审计与备份） |
+ * | `license-gate` | `license-gate.jsonl` | `scripts/license-gate.mjs` | 判断⑦（许可三态，observe 留证据） |
+ * | `notify-outbox` | `notify-outbox/audit.jsonl` | `core/lib/notify/dedup.mjs`（P2 新增） | 判断⑩（通知幂等 + 投递留痕） |
+ * | `env-writeback` | `env-writeback/audit.jsonl` | `scripts/argent-env-write.mjs` | 判断②⑨（受控 env 写入） |
+ *
+ * 新增审计源 = 在 `SOURCES` 加一行（**只登记路径与出处，不复制写它的判据**）。
+ *
+ * ## A1/A2
+ *   · `0` 读成功（**没有匹配行 = `empty:true + no_match`**，不是错误 —— 新机器本来就没有审计）；
+ *   · `2` 用法错误（未知 `--source` / `--since` 解析不了 / `--tail` 不是正整数）；
+ *   · `1` 某个**已存在**的审计文件读不出来（权限/IO）⇒ 如实报 `unreadable`，**不得**降级成"空"。
+ *   · 回显**实际生效值**：`sources`（请求的）/ `since`（归一化后的 ISO 或 null）/ `tail` /
+ *     `scanned` / `matched` / `returned` + 每源计数 —— 空结果一眼可分。
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { resolveDataDir } from './argent-datadir.mjs'
+
+/** 审计源登记表（id → 相对数据目录的路径 + 谁写的）。 */
+export const SOURCES = [
+  { id: 'invoice-writeback', path: 'invoice-writeback/audit.jsonl', writtenBy: 'scripts/wenyao-invoice-writeback.mjs', note: '回写：写前备份 + 字段 diff + 读回验收' },
+  { id: 'license-gate', path: 'license-gate.jsonl', writtenBy: 'scripts/license-gate.mjs', note: '许可闸门：每次判定一行（observe 只留证据）' },
+  { id: 'notify-outbox', path: 'notify-outbox/audit.jsonl', writtenBy: 'core/lib/notify/dedup.mjs', note: '通知投递（每次真发一行；dry-run 不落）' },
+  { id: 'env-writeback', path: 'env-writeback/audit.jsonl', writtenBy: 'scripts/argent-env-write.mjs', note: '受控 env 写入：字段白名单 + 写前备份' },
+  { id: 'license-activation', path: 'license-activation/audit.jsonl', writtenBy: 'core/lib/license-activate.mjs', note: '一次性激活码兑换（apply 的成败各一行；**只落 codePrefix**，绝不落明文码/密钥）；dry-run 不落' },
+  { id: 'install', path: 'install-audit.jsonl', writtenBy: 'install-argent.mjs', note: '安装**放行留痕**：`--allow-unlicensed`（送装/断网）、逃生阀 `ARGENT_LICENSE_ENFORCE=off`、以及宿主门禁逃生阀 `--allow-unsupported-host`（内部/验证用；行内含 hostVersion/supportedWindow/args）各一行；含 who/host/能力/包名/planSha，⛔ 不含任何密钥' },
+]
+export const SOURCE_IDS = SOURCES.map((s) => s.id)
+export const DEFAULT_TAIL = 20
+
+/**
+ * `--since` 解析：ISO 8601 / `YYYY-MM-DD` / epoch 秒（10 位）/ epoch 毫秒（13 位）。
+ * @returns {{ok:true, since:number, iso:string} | {ok:false, error:string}}
+ */
+export function parseSince(raw, now = Date.now()) {
+  const s = String(raw == null ? '' : raw).trim()
+  if (!s) return { ok: false, error: '--since 缺值' }
+  if (/^\d{10}$/.test(s)) return { ok: true, since: Number(s) * 1000, iso: new Date(Number(s) * 1000).toISOString() }
+  if (/^\d{13}$/.test(s)) return { ok: true, since: Number(s), iso: new Date(Number(s)).toISOString() }
+  if (/^\d{4}-\d{2}-\d{2}$/.test(s)) {
+    // 纯日期按**本地**零点解释（人在看"今天之后"时就是这个意思），并回显归一化结果
+    const [y, m, d] = s.split('-').map(Number)
+    const t = new Date(y, m - 1, d, 0, 0, 0, 0).getTime()
+    return { ok: true, since: t, iso: new Date(t).toISOString() }
+  }
+  const t = Date.parse(s)
+  if (Number.isNaN(t)) return { ok: false, error: `--since 解析不了：${JSON.stringify(s)}（支持 ISO 8601 / YYYY-MM-DD / epoch 秒 / epoch 毫秒）` }
+  void now
+  return { ok: true, since: t, iso: new Date(t).toISOString() }
+}
+
+/** 单源读取（坏行保留为 `{raw}`，**绝不丢证据**）。 */
+export function readSource(dataDir, src) {
+  const p = join(String(dataDir), src.path)
+  if (!existsSync(p)) return { ...src, file: p, exists: false, lines: 0, rows: [], error: null }
+  let text = ''
+  try { text = readFileSync(p, 'utf8') } catch (e) {
+    return { ...src, file: p, exists: true, lines: 0, rows: [], error: `读不出来：${(e && e.message) || e}` }
+  }
+  const rows = []
+  const raw = text.split('\n')
+  raw.forEach((l, i) => {
+    const s = l.trim()
+    if (!s) return
+    let data = null
+    try { data = JSON.parse(s) } catch { data = { raw: s } }
+    rows.push({ source: src.id, line: i + 1, at: data && typeof data.at === 'string' ? data.at : null, data })
+  })
+  return { ...src, file: p, exists: true, lines: raw.filter((l) => l.trim()).length, rows, error: null }
+}
+
+/**
+ * verb 入口：`argent audit [--source <id>]… [--since <t>] [--tail <n>] [--json]`。
+ * @param {string[]} argv
+ * @param {{env?:object, dataDir?:string}} [deps]
+ */
+export function runAuditVerb(argv = [], deps = {}) {
+  const wantSources = []
+  let sinceRaw = null
+  let tailRaw = null
+  for (let i = 0; i < argv.length; i++) {
+    const t = argv[i]
+    if (t === '--json') continue
+    if (t === '--source') {
+      const v = argv[i + 1]
+      if (v === undefined || String(v).startsWith('--')) return auditFail(2, 'usage_error', '--source 缺值')
+      if (!SOURCE_IDS.includes(v)) return auditFail(2, 'usage_error', `未知审计源：${v}（可用：${SOURCE_IDS.join('、')}）`)
+      wantSources.push(v); i++
+      continue
+    }
+    if (t === '--since') { const v = argv[i + 1]; if (v === undefined || String(v).startsWith('--')) return auditFail(2, 'usage_error', '--since 缺值'); sinceRaw = v; i++; continue }
+    if (t === '--tail') { const v = argv[i + 1]; if (v === undefined || String(v).startsWith('--')) return auditFail(2, 'usage_error', '--tail 缺值'); tailRaw = v; i++; continue }
+    if (t === '--help' || t === '-h') return { json: { ok: true, empty: false, code: 0, reason: null, verb: 'audit', usage: AUDIT_USAGE }, human: AUDIT_USAGE, stderr: '', exit: 0 }
+    if (t.startsWith('--')) return auditFail(2, 'usage_error', `未知参数：${t}（用法：argent audit [--source <id>]… [--since <t>] [--tail <n>] [--json]）`)
+    return auditFail(2, 'usage_error', `多余的位置参数：${t}`)
+  }
+
+  let tail = DEFAULT_TAIL
+  if (tailRaw !== null) {
+    const n = Number(String(tailRaw).trim())
+    if (!Number.isFinite(n) || n < 1 || !Number.isInteger(n)) return auditFail(2, 'usage_error', `--tail 必须是 ≥1 的整数，实得 ${JSON.stringify(tailRaw)}`)
+    tail = n
+  }
+  let since = null
+  if (sinceRaw !== null) {
+    const p = parseSince(sinceRaw)
+    if (!p.ok) return auditFail(2, 'usage_error', p.error)
+    since = p
+  }
+
+  const env = deps.env || process.env
+  const dataDir = deps.dataDir || resolveDataDir({ env }).dir
+  const requested = wantSources.length ? wantSources : SOURCE_IDS
+  const perSource = requested.map((id) => readSource(dataDir, SOURCES.find((s) => s.id === id)))
+
+  // 已存在却读不出来 ⇒ 如实报错（**不得**降级成"空"，那会让"审计丢了"看起来像"本来就没有"）
+  const broken = perSource.filter((s) => s.exists && s.error)
+  const all = perSource.flatMap((s) => s.rows)
+  const filtered = since
+    ? all.filter((r) => {
+      if (!r.at) return false                        // 没有时间戳的行无法判定"是否在 since 之后" ⇒ 保守排除（并在回显说明）
+      const t = Date.parse(r.at)
+      return !Number.isNaN(t) && t >= since.since
+    })
+    : all
+  const merged = filtered.slice().sort((a, b) => {
+    const ta = a.at ? Date.parse(a.at) : NaN
+    const tb = b.at ? Date.parse(b.at) : NaN
+    if (Number.isNaN(ta) || Number.isNaN(tb)) return 0
+    return ta - tb
+  })
+  const returned = merged.slice(-tail)
+
+  const json = {
+    ok: broken.length === 0,
+    empty: returned.length === 0,
+    code: broken.length ? 1 : 0,
+    reason: broken.length ? 'unreadable' : (returned.length === 0 ? 'no_match' : null),
+    error: broken.length ? broken.map((b) => `${b.id}（${b.file}）：${b.error}`).join('；') : null,
+    verb: 'audit',
+    dataDir,
+    sources: requested,
+    sourceCount: requested.length,
+    since: since ? since.iso : null,
+    sinceInput: sinceRaw,
+    tail,
+    scanned: all.length,
+    matched: filtered.length,
+    returned: returned.length,
+    rowsTruncated: Math.max(0, merged.length - returned.length),
+    perSource: perSource.map((s) => ({ id: s.id, file: s.file, exists: s.exists, lines: s.lines, error: s.error })),
+    rows: returned.map((r) => ({ source: r.source, line: r.line, at: r.at, data: r.data })),
+    note: since
+      ? '`--since` 按行内 `at` 过滤；**没有 `at` 或 `at` 解析不了的行会被排除**（无法判定时间先后）。顺序 = 读全量 → 过滤 → 合并排序 → 取末尾 N 行。'
+      : '顺序 = 读全量 → 过滤（无 --since）→ 合并排序 → 取末尾 N 行；`--tail` 只截断尾部，不影响每源计数。',
+  }
+  const human = [
+    `${json.ok ? '📜' : '❌'} 审计（${requested.length} 源 ｜ since=${json.since || '未过滤'} ｜ tail=${tail}）`,
+    ...json.perSource.map((s) => `   · ${s.id.padEnd(18)} ${s.exists ? `${s.lines} 行` : '（无此文件）'}${s.error ? ` ❌ ${s.error}` : ''}  ${s.file}`),
+    `   扫描 ${json.scanned} 行 → 过滤后 ${json.matched} 行 → 返回末尾 ${json.returned} 行${json.rowsTruncated ? `（截掉 ${json.rowsTruncated}）` : ''}`,
+    ...json.rows.map((r) => `   ${r.at || '(无 at)'}  [${r.source}#${r.line}] ${JSON.stringify(r.data).slice(0, 160)}`),
+    json.error ? `   ❌ ${json.error}` : null,
+  ].filter(Boolean).join('\n')
+  return { json, human, stderr: '', exit: Number(json.code) }
+}
+
+function auditFail(code, reason, error, echo = {}) {
+  return { json: { ok: false, empty: false, code, reason, error, verb: 'audit', ...echo }, human: `❌ ${reason}：${error}`, stderr: '', exit: code }
+}
+
+export const AUDIT_USAGE = [
+  '用法：argent audit [--source <id>]… [--since <ISO|YYYY-MM-DD|epoch>] [--tail <n>] [--json]',
+  '',
+  `审计源：${SOURCES.map((s) => s.id).join('、')}（缺省=全部）`,
+  '只读：读全量 → 按 --since 过滤 → 按 at 合并排序 → 取末尾 --tail 行；每源计数一并回显。',
+  '没有匹配行 = exit 0 + empty:true（新机器本来就没有审计，不是错误）。',
+].join('\n')