@whyshu/argent-engine 0.0.0-stage → 0.6.1

package/engine/core/lib/doctor-customer.mjs

@@ -0,0 +1,577 @@
+/**
+ * `argent doctor --customer` —— **客户机一页式自检**（M1 判据③；P4，2026-10-03）。
+ *
+ * ## 它回答什么（M1 判据③ 的原文）
+ * 实施方案 §4.2 M1 判据③ =「`argent doctor --customer` **无 dsh 不报 FAIL**」。
+ * 陪跑式的第一个客户机上**很可能没有 dsh**（客户用的是自己的 agent 宿主：claude-code / codex /
+ * cursor / 桌面端…）⇒ 自检必须能在那台机器上跑完并给出**可照做的下一步**，而不是因为"缺宿主"
+ * 就整体判红（那是把**宿主档事实**当成了**内核故障** —— 契约 §1 的易混点 + §2⑥）。
+ *
+ * ## 检查项（7 条；每条都指向唯一判据，本文件**不复制**任何判据）
+ * | id | 检查 | 唯一判据（本文件只调用） | 什么算 fail |
+ * |---|---|---|---|
+ * | `data_dir` | 数据目录：解析链命中哪一级 / 实际目录 / 是否隔离 / 可写性 | `core/lib/argent-datadir.mjs#resolveDataDir`（判断⑧） | **存在但不可写**（或最近祖先不可写） |
+ * | `interpreter` | 解释器：多候选探测结论 + 缺失时的修复指引 | `core/lib/python.mjs#pickPython`（D3：多候选 + 响亮失败，与 `flow-trigger.sh#pick_py` 同源） | 全部候选不可用（**没有它跑不了任何流程**） |
+ * | `skills` | 外发技能：5 个是否已装 / 装在哪个根 / 内容与仓库是否一致 | 外发集 = `scripts/check-skill-classification.mjs#classify`（唯一真源）；目录约定真源 = `scripts/skill-install.mjs#hostTable`（本文件只做**只读候选表**，由回归测试逐项对拍） | 归类门禁不通过，或**已装但内容与仓库不一致** |
+ * | `license` | 许可：三态（valid/grace/denied）+ 设备绑定态 + 到期/宽限 | `core/lib/license-verdict.mjs#licenseVerdict`（§3.5① 判定点唯一在 CLI 进程内） | `denied` **且不是因为"没装许可"**（验签失败/过期/设备不匹配…） |
+ * | `channels` | 通知通道：可用 / 预留位 | `core/lib/notify/index.mjs#listChannels`（P2 端口） | 一条可用通道都没有（异常上报没有出口） |
+ * | `source` | 数据源可达性：**只读**探测（能否列出流程 / 声明的 kind 是否已实现） | `core/lib/flow-registry.mjs#loadRegistry` + `core/lib/flow-list.mjs#summarizeFlows` + `scripts/flow_source.py --list-sources` | 注册表读不到，或流程声明的 `source.kind` **没有实现** |
+ * | `host` | **宿主档事实**：dsh 在不在 / 补丁清单 / 定时器与面板的权威判据在哪 | 只探测、如实上报（`core/lib/versions.mjs#patchesProfile`）；**从不**调 `launchctl` | **永不 fail**：`applicable:false` = 本档不适用（契约 §1：会话唤醒/宿主调度/系统集成归 L2） |
+ *
+ * ## A1 退出码（唯一口径，§P0-A）
+ *   · `0` —— 全部 `ok`/`warn`。**warn 只在 JSON 里标记，不占用 2**（A1 明写"`2` 不得再被用作
+ *     '有告警 / 部分成功 / 需要人工看一眼'"）；许可宽限也只记 `warn`（`3` 是**业务放行**的码，
+ *     自检不放行任何业务 ⇒ 不回传 3，许可态在 JSON 的 `license.state` 里如实给出）。
+ *   · `1` —— 存在 `fail`（`reason:"check_failed"`，见 `reasonCodes`）。
+ *   · `2` —— **用法错误**（未知参数 / `--customer` 收到 `--flow` 这类互斥形态）。
+ *
+ * ## A2 JSON（`--json` 时 **stdout 只有一份 JSON**）
+ *   `ok/empty/code/reason` 恒在；外加 `checks[]`（每条 `level` ∈ ok|warn|fail + `detail` 事实 +
+ *   `advice` 处置建议 + `evidence` 取证）与 `summary`。`code` 恒等于进程退出码。
+ *
+ * ## A3 / 零副作用（**硬约束，写进代码也写进输出**）
+ *   · 本 verb **只读**：不建目录（缺目录 ⇒ `warn` + 建议 `argent init --apply`）、不写任何文件、
+ *     不写 `~/.dsh/settings.yaml`、不碰 credentials、**不真发通知**（只看通道清单）；
+ *   · 可写性探测用 `accessSync(dir, W_OK)`（**不落探针文件**）；数据源探测**只列流程/只列 kind**，
+ *     不读远端表（"能不能读源"的权限核验是 `python3 scripts/flow_preflight.py --flow <id> --online`）；
+ *   · 输出里的 `sideEffects` 是**机器可读的自证**：调用方可以据此断言"这次自检没动过任何东西"。
+ *
+ * ## ⛔ 本文件不做什么
+ *   ① **不要求 dsh 存在**（M1 判据③）；② 不复述任何判断（数据目录链/解释器候选/许可三态/
+ *   外发集/通道表/注册表合并**全部**从各自唯一判据取）；③ 不 import L2 宿主档模块
+ *   （契约 §1 明写"不得让 L0/L1 反过来依赖 L2"）—— 故技能根的**目录约定**在这里是一张
+ *   **只读候选表**，真源仍是 `scripts/skill-install.mjs#hostTable`，两者由
+ *   `scripts/tests/doctor-customer.test.mjs` **逐项对拍**（漂移即红，形态同 `argent-datadir-parity`）。
+ *
+ * 跑法：`node core/cli/argent.mjs doctor --customer [--json]`；回归 `node scripts/tests/doctor-customer.test.mjs`
+ */
+import { execFileSync } from 'node:child_process'
+import { accessSync, constants as FS, existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
+import { createHash } from 'node:crypto'
+import { delimiter, join, sep } from 'node:path'
+import { dshHomeOf, osHome, resolveDataDir } from './argent-datadir.mjs'
+import { REASON_TEXT, pickPython } from './python.mjs'
+import { licenseVerdict } from './license-verdict.mjs'
+import { listChannels } from './notify/index.mjs'
+import { loadRegistry } from './flow-registry.mjs'
+import { summarizeFlows } from './flow-list.mjs'
+import { patchesProfile, probeDsh } from './versions.mjs'
+import { SKILL_FILE, classify } from '../../scripts/check-skill-classification.mjs'
+
+/** 检查项 id（顺序即人读顺序；`--json` 的 `checks[]` 同序）。 */
+export const CHECK_IDS = ['data_dir', 'interpreter', 'skills', 'license', 'channels', 'source', 'host']
+/** 三档（每条检查恒取其一；"本档不适用"用 `applicable:false` 表达，**不是**第四档，更不是 fail）。 */
+export const LEVELS = ['ok', 'warn', 'fail']
+
+const sha12 = (buf) => createHash('sha256').update(buf).digest('hex').slice(0, 12)
+
+/** `--customer` 的用法串（`--help` 与用法错误共用一份）。 */
+export const DOCTOR_CUSTOMER_USAGE = [
+  '用法：argent doctor --customer [--json]',
+  '',
+  '客户机一页式自检（**只读**）：数据目录 / 解释器 / 外发技能 / 许可 / 通知通道 / 数据源可达性 / 宿主档事实。',
+  '退出码（A1）：全部 ok·warn ⇒ 0（warn 只在 JSON 标记）；存在 fail ⇒ 1；用法错误 ⇒ 2。',
+  '⛔ 不要求本机装 dsh（无宿主 ⇒ 宿主档事实记「本档不适用」，**不算 FAIL**）；',
+  '⛔ 不写任何文件 / 凭据 / settings，不建目录，不真发通知。',
+  '单流程前置检查仍走：`argent doctor --flow <id> [--online]`（同一脚本 flow_preflight.py，判据不重复）。',
+].join('\n')
+
+// ── 只读小工具 ─────────────────────────────────────────────────────────────
+
+/** 在 PATH 上找一个可执行文件（**不 spawn**、不 shell out 到 `which`；极简 PATH 下更可靠）。 */
+export function findOnPath(name, { env = process.env, exists = existsSync } = {}) {
+  for (const dir of String(env.PATH || '').split(delimiter)) {
+    if (!dir) continue
+    const p = join(dir, name)
+    if (exists(p)) return p
+  }
+  return ''
+}
+
+/** 目录可写性：`accessSync(W_OK)`（**只读调用，不落探针文件**）。 */
+export function writableOf(dir, { access = accessSync, exists = existsSync } = {}) {
+  let cur = String(dir || '')
+  const missing = []
+  while (cur && cur !== '/' && !exists(cur)) { missing.push(cur); cur = join(cur, '..') }
+  if (!exists(cur)) return { ok: false, checked: null, missing: missing.length, why: '整条路径都不存在（连根都没有）' }
+  try {
+    access(cur, FS.W_OK)
+    return { ok: true, checked: cur, missing: missing.length, why: '' }
+  } catch (e) {
+    return { ok: false, checked: cur, missing: missing.length, why: `${(e && e.code) || e}` }   // 只给错误码（调用方拼「不可写（…）」）
+  }}
+
+/** 技能目录 → `{相对路径: sha12}`（与 `scripts/skill-install.mjs#skillFiles` 同形；由回归测试逐项对拍）。 */
+export function skillFileDigests(dir, { exists = existsSync, readdir = readdirSync, stat = statSync, readFile = readFileSync } = {}) {
+  const out = {}
+  const walk = (d, base) => {
+    let entries = []
+    try { entries = readdir(d, { withFileTypes: true }) } catch { return }
+    for (const e of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+      if (e.name === '.DS_Store') continue
+      const p = join(d, e.name)
+      let st = null
+      try { st = stat(p) } catch { continue }
+      if (st.isDirectory()) walk(p, base)
+      else if (st.isFile()) out[p.slice(base.length + 1).split(sep).join('/')] = sha12(readFile(p))
+    }
+  }
+  if (!exists(dir)) return out
+  walk(dir, dir)
+  return out
+}
+
+/** 逐文件比较两份摘要（同键集且同 sha ⇒ 一致；给出差异明细，便于"可照做"的建议）。 */
+export function diffDigests(a, b) {
+  const keys = [...new Set([...Object.keys(a), ...Object.keys(b)])].sort()
+  const different = keys.filter((k) => a[k] && b[k] && a[k] !== b[k])
+  const missing = keys.filter((k) => a[k] && !b[k])
+  const extra = keys.filter((k) => !a[k] && b[k])
+  return { same: different.length === 0 && missing.length === 0 && extra.length === 0, different, missing, extra, files: keys.length }
+}
+
+/** SKILL.md frontmatter 的 `version`（与 `scripts/skill-install.mjs#frontmatterVersion` 同形；测试对拍）。 */
+export function frontmatterVersion(text) {
+  const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(String(text || ''))
+  if (!m) return null
+  const v = /^\s*version\s*:\s*(.+?)\s*$/m.exec(m[1])
+  return v ? v[1].replace(/^["']|["']$/g, '') : null
+}
+
+/**
+ * 技能根**候选表**（只读探测用）。
+ * ⚠️ **真源是 `scripts/skill-install.mjs#hostTable`（L2 安装器）** —— 本表只是 L1 侧的**只读副本**
+ * （契约 §1：不得让 L1 反过来依赖 L2）⇒ 由回归测试 `scripts/tests/doctor-customer.test.mjs`
+ * 与 `hostTable()` **逐项对拍**（目录、宿主 id 必须完全一致；漂移即红）。
+ */
+export function skillRootCandidates({ repo = '', dataDir = '', dshHome = '', home = '' } = {}) {
+  const dsh = dshHome || join(home, '.dsh')
+  return [
+    { id: 'data', who: 'Argent 数据目录', dir: join(dataDir, 'skills'), installHost: null, source: false },
+    { id: 'dsh', who: 'dsh 宿主', dir: join(dsh, 'skills'), installHost: 'dsh', source: false },
+    { id: 'claude-code', who: 'Claude Code', dir: join(home, '.claude', 'skills'), installHost: 'claude-code', source: false },
+    { id: 'codex', who: 'Codex', dir: join(home, '.codex', 'skills'), installHost: 'codex', source: false },
+    { id: 'cursor', who: 'Cursor', dir: join(home, '.cursor', 'skills'), installHost: 'cursor', source: false },
+    { id: 'repo', who: '仓库技能源（不是安装目标）', dir: join(repo, 'skills'), installHost: null, source: true },
+  ]
+}
+
+// ── 七条检查（每条返回 { id, title, level, applicable, detail, advice, evidence }）──────
+
+/** ① 数据目录：解析链 / 实际目录 / 是否隔离 / 可写性。 */
+export function checkDataDir({ env = process.env, ...deps } = {}) {
+  const r = deps.resolved || resolveDataDir({ env })
+  const exists = (deps.exists || existsSync)(r.dir)
+  const w = writableOf(r.dir, deps)
+  const isolatedNote = r.isolated
+    ? '隔离态：写入不会进默认目录；失败回路（flow-watch 泵）在隔离目录下**默认暂停**（除非 ARGENT_ALLOW_ISOLATED_PUMP=1）'
+    : '默认目录：失败回路按默认运行'
+  let level = 'ok'; let advice = ''
+  if (!exists && w.ok) {
+    level = 'warn'
+    advice = `目录还不存在（首次运行）：跑 \`node core/cli/argent.mjs init --apply\` 建它；要钉死位置用 ARGENT_DATA_DIR=<绝对路径>`
+  } else if (!exists && !w.ok) {
+    level = 'fail'
+    advice = `最近的已存在祖先也不可写：${w.checked || '(无)'} —— 换一个可写目录（ARGENT_DATA_DIR=<可写绝对路径>），或修正目录权限`
+  } else if (exists && !w.ok) {
+    level = 'fail'
+    advice = `数据目录不可写（${w.why}）：跑 \`chmod u+w ${r.dir}\`，或把 ARGENT_DATA_DIR 指到可写目录；在修好之前一切写类 verb 都会失败`
+  } else if (r.isolated) {
+    level = 'warn'
+    advice = '这是**隔离**目录（非默认）：确认它就是你想要的那棵树；隔离目录不是错误，但失败回路会默认暂停'
+  }
+  return {
+    id: 'data_dir', title: '数据目录', level, applicable: true,
+    detail: `${r.dir}（来源=${r.source}${r.isolated ? '，隔离' : ''}；存在=${exists}；可写=${w.ok}）`,
+    advice,
+    evidence: {
+      dir: r.dir, raw: r.raw, source: r.source, isolated: r.isolated, defaultDir: r.defaultDir, dshHome: r.dshHome,
+      exists, writable: w.ok, writableChecked: w.checked, missingLevels: w.missing,
+      chain: [
+        { level: 'ARGENT_DATA_DIR', hit: r.source === 'ARGENT_DATA_DIR', value: env.ARGENT_DATA_DIR ?? null },
+        { level: 'DSH_HOME', hit: r.source === 'DSH_HOME', value: env.DSH_HOME ? join(r.dshHome, 'argent') : null },
+        { level: 'default', hit: r.source === 'default', value: r.defaultDir },
+      ],
+      note: isolatedNote,
+      authoritative: 'core/lib/argent-datadir.mjs#resolveDataDir（判断⑧，全仓库唯一一份链）',
+    },
+  }
+}
+
+/** ② 解释器：多候选探测结论 + 修复指引（**与 D3 同口径**）。 */
+export function checkInterpreter({ env = process.env, dataDir = '', repo = '', picker = null } = {}) {
+  const p = picker || pickPython({ env, dataDir, repo })
+  const tried = (p.tried || []).map((t) => ({ path: t.path, source: t.source, ok: t.ok, reason: t.reason, detail: t.detail, version: t.version || null }))
+  if (p.ok) {
+    return {
+      id: 'interpreter', title: '解释器', level: 'ok', applicable: true,
+      detail: `${p.path}（${(p.version || []).join('.') || '版本未知'}；来源=${p.source}；探测 ${tried.length} 个候选）`,
+      advice: '',
+      evidence: { ok: true, path: p.path, version: p.version || null, source: p.source || null, tried, authoritative: 'core/lib/python.mjs#pickPython（与 scripts/flow-trigger.sh#pick_py 同源）' },
+    }
+  }
+  return {
+    id: 'interpreter', title: '解释器', level: 'fail', applicable: true,
+    detail: `找不到可用解释器（探测 ${tried.length} 个候选全部失败）：`
+      + (tried.map((t) => `${t.source}=${t.path}（${REASON_TEXT[t.reason] || t.reason}）`).join('；') || '(无候选)'),
+    advice: `修复：① \`python3 -m venv ${dataDir || '<数据目录>'}/venv && ${dataDir || '<数据目录>'}/venv/bin/pip install openpyxl pyyaml\`；`
+      + '② 或显式指定 `ARGENT_PY=/path/to/python3`（须 ≥ 3.10 且能 import openpyxl、yaml）。'
+      + '在修好之前：任何流程都跑不起来（这是硬失败，不是"没结果"）。',
+    evidence: { ok: false, tried, diagnostics: p.diagnostics || null, authoritative: 'core/lib/python.mjs#pickPython（D3：多候选 + 响亮失败）' },
+  }
+}
+
+/**
+ * ③ 技能：外发集是否已装 / 装在哪个根 / 内容与仓库是否一致。
+ * @param {{repo?:string, roots?:Array, classifySkills?:Function, digests?:Function}} o
+ */
+export function checkSkills({ repo = '', roots = [], classifySkills = null, digests = skillFileDigests } = {}) {
+  const cls = (classifySkills || (({ root }) => classify({ root })))({ root: repo })
+  const external = cls.external || []
+  const repoRoot = roots.find((r) => r.source) || null
+  const targets = roots.filter((r) => !r.source)
+  const repoDigests = {}
+  for (const name of external) {
+    const d = join(repo, 'skills', name)
+    repoDigests[name] = (repoRoot && existsSync(d)) ? digests(d) : null
+  }
+  const rows = targets.map((r) => {
+    const installed = []
+    const missing = []
+    const mismatched = []
+    const skills = {}
+    for (const name of external) {
+      const dir = join(r.dir, name)
+      const has = existsSync(join(dir, SKILL_FILE))
+      if (!has) { missing.push(name); continue }
+      installed.push(name)
+      const cur = digests(dir)
+      const want = repoDigests[name]
+      const cmp = want ? diffDigests(want, cur) : { same: null, different: [], missing: [], extra: [], files: Object.keys(cur).length }
+      if (cmp.same === false) mismatched.push({ name, ...cmp })
+      let version = null
+      try { version = frontmatterVersion(readFileSync(join(dir, SKILL_FILE), 'utf8')) } catch { /* 读不到就不报版本 */ }
+      skills[name] = { installed: true, match: cmp.same, version, files: Object.keys(cur).length, diff: cmp.same === false ? { different: cmp.different, missing: cmp.missing, extra: cmp.extra } : null }
+    }
+    return {
+      id: r.id, who: r.who, dir: r.dir, exists: existsSync(r.dir),
+      installed, missing, mismatched: mismatched.map((m) => m.name), skills,
+      manifest: existsSync(join(r.dir, '.argent-skills.json')),
+    }
+  })
+  const clean = rows.filter((r) => r.installed.length === external.length && r.mismatched.length === 0 && external.length > 0)
+  const dirty = rows.filter((r) => r.mismatched.length > 0)
+  const anyInstalled = rows.filter((r) => r.installed.length > 0)
+  const repoMissing = external.length > 0 && repoDigests[external[0]] === null
+
+  let level = 'warn'; let advice = ''
+  let detail = ''
+  if (!cls.ok) {
+    level = 'fail'
+    detail = `归类门禁不通过（${(cls.errors || []).length} 条）⇒ 外发集不可信，先修门禁再谈安装`
+    advice = '跑 `node scripts/check-skill-classification.mjs`（未归类即红）——修好前**不要**安装外发技能'
+  } else if (!external.length) {
+    level = 'warn'
+    detail = '没有任何业务线声明外发技能（外发集为空）'
+    advice = '若这台机器本该跑流程，检查业务线声明 `verticals/*/manifest.json#skills` 是否到位'
+  } else if (repoMissing) {
+    level = 'warn'
+    detail = `本机没有仓库技能源目录（${join(repo, 'skills')}）⇒ 无法比对内容（这不代表技能没装）`
+    advice = '把完整交付包放到本机（`skills/` 与 `core/`、`scripts/` 同批），再重跑本自检'
+  } else if (clean.length) {
+    level = 'ok'
+    detail = `外发 ${external.length} 个全部已装且内容与仓库一致：${clean.map((r) => `${r.id}（${r.dir}）`).join('、')}`
+  } else if (dirty.length) {
+    level = 'fail'
+    const bad = dirty.flatMap((r) => r.mismatched.map((n) => `${r.id}:${n}`))
+    detail = `已装但内容与仓库**不一致**：${bad.join('、')} ⇒ 客户机跑的是改过的/过期的技能（判断会跟着漂）`
+    advice = `重装（会先备份再覆盖）：\`node scripts/skill-install.mjs --host <宿主> --list\` 看清单，\`node scripts/skill-install.mjs --host <宿主> --apply\` 真装`
+  } else if (anyInstalled.length) {
+    level = 'warn'
+    detail = `只装了一部分：${anyInstalled.map((r) => `${r.id} ${r.installed.length}/${external.length}（缺 ${r.missing.join('、')}）`).join('；')}`
+    advice = `补齐：\`node scripts/skill-install.mjs --host <宿主> --apply\`（缺省 dry-run 会先打印计划）`
+  } else {
+    level = 'warn'
+    detail = `外发 ${external.length} 个技能在常见宿主根里都还没装（已探测 ${targets.length} 个根）`
+    advice = '先看清单：`node scripts/skill-install.mjs --host <客户宿主> --list`；确认后 `--apply` 真装（缺省 dry-run）'
+  }
+  return {
+    id: 'skills', title: '外发技能', level, applicable: true, detail, advice,
+    evidence: {
+      external, internal: cls.internal || [], classificationOk: Boolean(cls.ok),
+      classificationErrors: (cls.errors || []).map((e) => `${e.rule}:${e.message}`),
+      repoSkillsDir: join(repo, 'skills'), repoSkillsPresent: !repoMissing,
+      roots: rows,
+      note: '外发集真源 = 各 verticals/*/manifest.json#skills 的并集（scripts/check-skill-classification.mjs#classify）；'
+        + '目录约定真源 = scripts/skill-install.mjs#hostTable（本表由回归测试逐项对拍）',
+    },
+  }
+}
+
+/** ④ 许可：三态 + 设备绑定态 + 到期/宽限（**缺失不算 FAIL**）。 */
+export function checkLicense({ env = process.env, now = Date.now(), verdict = null, verdictFn = null } = {}) {
+  const v = verdict || (verdictFn || licenseVerdict)({ env, now })
+  const dev = v.device || {}
+  const facts = {
+    state: v.state, exit: v.exit, reason: v.reason || null,
+    file: v.path || null, exists: Boolean(v.path && existsSync(v.path)),
+    expiresAt: v.expiresAt || null, graceDays: v.graceDays ?? null, graceUntil: v.graceUntil || null,
+    graceSource: v.graceSource || null, allowed: v.allowed ?? null,
+    device: { present: Boolean(dev.present), signed: Boolean(dev.signed), state: dev.state || null, reason: dev.reason || null, rebindsLeft: dev.rebindsLeft ?? null, graceUntil: dev.graceUntil || null, machineReadable: Boolean(dev.machineReadable) },
+    authoritative: 'core/lib/license-verdict.mjs#licenseVerdict（§3.5① 判定点唯一在 CLI 进程内）',
+  }
+  const deviceText = facts.device.present
+    ? `设备绑定=${facts.device.state}（重绑剩余 ${facts.device.rebindsLeft ?? '—'}）`
+    : '设备绑定=未声明（存量 unbound 许可：不比对、放行 —— D1 兼容）'
+  if (v.state === 'valid') {
+    return { id: 'license', title: '许可', level: 'ok', applicable: true,
+      detail: `valid${facts.reason ? `（${facts.reason}）` : ''}；到期 ${facts.expiresAt || '—'}；${deviceText}`, advice: '', evidence: facts }
+  }
+  if (v.state === 'grace') {
+    return { id: 'license', title: '许可', level: 'warn', applicable: true,
+      detail: `grace（宽限期，业务放行但要上报）：来源=${facts.graceSource || '—'}，宽限至 ${facts.graceUntil || '—'}；到期 ${facts.expiresAt || '—'}；${deviceText}`,
+      advice: '继续跑业务，但**必须**把"许可在宽限期内"上报给人；续期 = 拿一份新许可文件后 `node core/cli/argent.mjs license install --file <path> --apply`',
+      evidence: facts }
+  }
+  // denied：**只有"没装许可"不算 FAIL**（M1 判据③ 的同精神：缺件是事实，不是故障）；其余 denied 是真问题
+  const missingOnly = facts.reason === 'missing' && !facts.exists
+  return {
+    id: 'license', title: '许可',
+    level: missingOnly ? 'warn' : 'fail',
+    applicable: true,
+    detail: missingOnly
+      ? `denied（reason=missing）：本机还没有许可文件（${facts.file || '<数据目录>/license.json'}）`
+      : `denied（reason=${facts.reason || '—'}）：许可存在但不可用（验签失败/过期/设备不匹配…）`,
+    advice: missingOnly
+      ? '**缺许可不是故障**（写类 verb 会被拒，读类与自检照常）：拿签发文件后 `node core/cli/argent.mjs license install --file <path>`（缺省 dry-run，`--apply` 才落盘）；'
+        + '先看设备码：`node core/cli/argent.mjs license request`'
+      : `跑 \`node core/cli/argent.mjs license explain --json\` 看"缺什么/下一步"；`
+        + '设备不匹配且自助重绑没用完 ⇒ `license install --file <path> --rebind --apply`',
+    evidence: facts,
+  }
+}
+
+/** ⑤ 通知通道：可用 / 预留位（**只列表，绝不实发**）。 */
+export function checkChannels({ channels = null, listFn = null } = {}) {
+  const all = channels || (listFn || listChannels)()
+  const available = all.filter((c) => c.implemented).map((c) => c.channel)
+  const reserved = all.filter((c) => !c.implemented).map((c) => c.channel)
+  const level = available.length ? 'ok' : 'fail'
+  return {
+    id: 'channels', title: '通知通道', level, applicable: true,
+    detail: available.length
+      ? `可用：${available.join('、')}｜预留位（端口已定、实现未落地）：${reserved.join('、') || '（无）'}`
+      : `一条可用通道都没有（全部是预留位：${reserved.join('、')}）⇒ 异常/上报没有出口`,
+    advice: available.length
+      ? '预留位不是故障（通知**投递**归 L2 宿主）：`argent notify --channel <id>` 选到未实现通道会**响亮报错**，不会静默成功；'
+        + '要发一次自测（**会真发包**）：`node core/cli/argent.mjs notify --channel webhook --url <你的接收端> --text hi --apply`'
+      : '至少落地一条通道（webhook 端口已实现，配置 URL 即可用）',
+    evidence: { available, reserved, all, probe: false, note: '本自检**不真发通知**（只看通道清单：send 只在 `argent notify --apply` 时发生）' },
+  }
+}
+
+/**
+ * ⑥ 数据源可达性（**只读探测**）：能否列出流程 / 声明的 kind 是否已实现。
+ * ⛔ 不读远端表、不联网、不写任何东西 —— 权限核验是 `flow_preflight.py --flow <id> --online` 的事。
+ */
+export function checkSource({ repo = '', py = '', pyFailure = null, doc = null, kinds = null, listFn = null, loadFn = null, summarizeFn = null } = {}) {
+  const base = { authoritative: 'core/lib/flow-registry.mjs#loadRegistry（合并真源 scripts/flow_registry.py）+ scripts/flow_source.py --list-sources（数据面端口表）', readProbe: { performed: false, why: '本自检不读写远端表：只列流程与数据面；能不能真读源（权限/身份）用 `python3 scripts/flow_preflight.py --flow <id> --online` 核' } }
+  if (pyFailure || !py) {
+    return {
+      id: 'source', title: '数据源可达性', level: 'warn', applicable: true,
+      detail: `未探测（解释器不可用：${(pyFailure || '未指定解释器').split('\n')[0]}）`,
+      advice: '先把解释器修好（见「解释器」一条），再重跑本自检；现在**不知道**流程与数据面是否就位',
+      evidence: { ...base, probed: false, reason: 'python_unavailable', error: pyFailure || null },
+    }
+  }
+  const reg = doc ? { ok: true, doc } : (loadFn || loadRegistry)({ repo, py })
+  if (!reg.ok) {
+    return {
+      id: 'source', title: '数据源可达性', level: 'fail', applicable: true,
+      detail: `列不出流程：注册表读不到（${reg.reason || 'unknown'}）${reg.error ? ` —— ${String(reg.error).split('\n')[0]}` : ''}`,
+      advice: '确认交付包完整（`scripts/flow-requirements.json` + `verticals/*/flows.json` + `scripts/flow_registry.py`），'
+        + '再跑 `node core/cli/argent.mjs flow list --json` 复核',
+      evidence: { ...base, probed: true, registry: { ok: false, reason: reg.reason || null, error: reg.error || null } },
+    }
+  }
+  const sum = (summarizeFn || summarizeFlows)(reg.doc, {})
+  const declaredKinds = [...new Set(sum.rows.map((r) => r.sourceKind).filter(Boolean))].sort()
+  const impl = kinds || probeSourceKinds({ repo, py })
+  const implemented = impl.ok ? Object.keys(impl.kinds) : []
+  const unknown = declaredKinds.filter((k) => !implemented.includes(k))
+  const level = unknown.length ? 'fail' : 'ok'
+  return {
+    id: 'source', title: '数据源可达性', level, applicable: true,
+    detail: `能列出流程 ${sum.rows.length} 条（业务线 ${sum.verticalIds.join('、') || '（无）'}）；`
+      + `声明的数据面：${declaredKinds.join('、') || '（无）'}；引擎已实现：${implemented.join('、') || `（读不到：${impl.error || '未知'}）`}`
+      + (unknown.length ? `；❌ 未实现：${unknown.join('、')}` : ''),
+    advice: unknown.length
+      ? `流程声明的 source.kind「${unknown.join('、')}」没有实现 ⇒ 这些流程**跑不起来**（加数据面 = 加一个 \`scripts/flow_sources/<kind>.py\` 并在 MODULES 登记，见 P4 端口契约）`
+      : (impl.ok ? '' : '数据面端口表读不到（不影响"能否列出流程"的结论，但少了"声明的 kind 有没有实现"这一向）；'
+        + '跑 `python3 scripts/flow_source.py --list-sources` 复核'),
+    evidence: {
+      ...base, probed: true,
+      registry: { ok: true, flows: sum.rows.length, verticals: sum.verticalIds, rows: sum.rows.map((r) => ({ id: r.id, sourceKind: r.sourceKind, capability: r.capability, skill: r.skill })) },
+      kinds: { declared: declaredKinds, implemented, ok: Boolean(impl.ok), error: impl.error || null },
+    },
+  }
+}
+
+/** `python3 scripts/flow_source.py --list-sources`（只读；失败如实回报，不抛栈）。 */
+export function probeSourceKinds({ repo = '', py = '', run = null } = {}) {
+  const exec = run || ((bin, argv) => execFileSync(bin, argv, { encoding: 'utf8', timeout: 30000, stdio: ['ignore', 'pipe', 'pipe'] }))
+  try {
+    const out = exec(py, [join(repo, 'scripts', 'flow_source.py'), '--list-sources'])
+    const json = JSON.parse(String(out).slice(String(out).indexOf('{')))
+    return { ok: true, kinds: json, error: null }
+  } catch (e) {
+    return { ok: false, kinds: {}, error: String((e && e.message) || e).slice(0, 200) }
+  }
+}
+
+/** ⑦ 宿主档事实：dsh / 补丁 / 定时器与面板（**永不 FAIL**；无宿主 ⇒ applicable:false）。 */
+export function checkHost({ env = process.env, repo = '', which = null, dshVersion = undefined, patches = null } = {}) {
+  const dshHome = dshHomeOf(env)
+  const dshHomeExists = existsSync(dshHome)
+  const dshBin = which ? which('dsh') : findOnPath('dsh', { env })
+  const applicable = Boolean(dshBin || dshHomeExists)
+  const version = dshVersion !== undefined ? dshVersion : (dshBin ? probeDsh() : '')
+  const p = patches || patchesProfile(repo)
+  const settingsPath = join(dshHome, 'settings.yaml')
+  const settingsExists = existsSync(settingsPath)
+  const facts = {
+    dshBin: dshBin || null, dshVersion: version || null, dshHome, dshHomeExists,
+    settingsYamlExists: settingsExists,
+    patches: { present: Boolean(p.present), dir: p.dir, count: p.count || 0, patches: p.patches || [] },
+    authoritative: {
+      triggers: 'bash scripts/flow-timers.sh status（launchctl + LaunchAgent 是宿主档；本页**不调** launchctl）',
+      patches: 'node scripts/dsh-upgrade.mjs --patches-only（补丁在不在位）',
+      panels: '宿主 profile 组合（plugins/argent-* 的 settings.section）—— 面板渲染归 L2',
+    },
+    productionHomeRule: '生产在客户机（Huangwei）：**本机（开发/测试 Mac）`launchctl list | grep flow-trigger` 必须为 0**；客户机才应有 4 条。',
+    note: '宿主档事实（触发器/补丁/面板/会话唤醒/系统集成）归 L2（契约 §1）——本页只如实列事实，**不重算判据、不判 FAIL**。',
+  }
+  if (!applicable) {
+    return {
+      id: 'host', title: '宿主档事实', level: 'ok', applicable: false,
+      detail: `本档不适用：本机没有 dsh（dsh 不在 PATH，且 <dsh home>=${dshHome} 不存在）—— `
+        + '触发器/补丁/面板都是**宿主档事实**（契约 §1 归 L2），无宿主时它们**没有意义**，因此**不算 FAIL**（M1 判据③）',
+      advice: '无需处置。这台机器按"无宿主档"（陪跑式：客户用自己的 agent 宿主）使用即可；'
+        + '若之后装了 dsh，重跑本自检会多出宿主档一行',
+      evidence: facts,
+    }
+  }
+  return {
+    id: 'host', title: '宿主档事实', level: 'ok', applicable: true,
+    detail: `dsh=${version || '（在 PATH 上但 --version 读不到）'}｜dsh home=${dshHome}（存在）｜`
+      + `settings.yaml=${settingsExists ? '在' : '不在'}｜补丁清单 ${facts.patches.count} 个${facts.patches.present ? '' : '（缺目录）'}`,
+    advice: '',
+    evidence: facts,
+  }
+}
+
+// ── verb 入口 ──────────────────────────────────────────────────────────────
+
+/**
+ * verb 入口：`argent doctor --customer [--json]`。
+ * @param {string[]} argv  `doctor` 之后的参数（含 `--customer`）
+ * @param {{repo?:string, env?:object, now?:number, deps?:object}} [deps]
+ *   `deps` 里每一项都可注入（夹具用）：`resolved`/`picker`/`verdict`/`channels`/`doc`/`kinds`/`which`/`dshVersion`/`patches`/`roots`/`classifySkills`/`digests`
+ * @returns {{json:object, human:string, stderr:string, exit:number}} CLI 信封（`core/cli/argent.mjs` 消费）
+ */
+export function runDoctorCustomerVerb(argv = [], deps = {}) {
+  let customer = false
+  for (const t of argv) {
+    if (t === '--customer') { customer = true; continue }
+    if (t === '--json') continue
+    if (t === '--help' || t === '-h') {
+      return { json: { ok: true, empty: false, code: 0, reason: null, verb: 'doctor', subcommand: 'customer', usage: DOCTOR_CUSTOMER_USAGE }, human: DOCTOR_CUSTOMER_USAGE, stderr: '', exit: 0 }
+    }
+    if (t === '--flow' || t === '--online') {
+      return doctorFail(2, 'usage_error', `${t} 与 --customer 互斥：整机自检不接受单流程参数（单流程用：argent doctor ${t} <值>）`)
+    }
+    return doctorFail(2, 'usage_error', `未知参数：${t}（用法：argent doctor --customer [--json]）`)
+  }
+  if (!customer) return doctorFail(2, 'usage_error', '缺 --customer（用法：argent doctor --customer [--json]；单流程检查用 argent doctor --flow <id>）')
+
+  const env = deps.env || process.env
+  const repo = deps.repo || ''
+  const now = deps.now || Date.now()
+  const d = deps.deps || {}
+  const home = osHome(env)
+
+  const dd = checkDataDir({ env, ...(d.dataDir || {}) })
+  const dataDir = dd.evidence.dir
+  const dshHome = dshHomeOf(env)
+
+  const interpreter = checkInterpreter({ env, dataDir, repo, picker: d.picker || null })
+  const skills = checkSkills({
+    repo,
+    roots: d.roots || skillRootCandidates({ repo, dataDir, dshHome, home }),
+    classifySkills: d.classifySkills || null,
+    digests: d.digests || skillFileDigests,
+  })
+  const license = checkLicense({ env, now, verdict: d.verdict || null, verdictFn: d.verdictFn || null })
+  const channels = checkChannels({ channels: d.channels || null })
+  const source = checkSource({
+    repo, py: d.py !== undefined ? d.py : (interpreter.evidence.ok ? interpreter.evidence.path : ''),
+    pyFailure: d.pyFailure !== undefined ? d.pyFailure : (interpreter.evidence.ok ? null : (interpreter.evidence.diagnostics || '解释器不可用')),
+    doc: d.doc || null, kinds: d.kinds || null, listFn: d.listFn || null, loadFn: d.loadFn || null, summarizeFn: d.summarizeFn || null,
+  })
+  const host = checkHost({ env, repo, which: d.which || null, dshVersion: d.dshVersion, patches: d.patches || null })
+
+  const checks = [dd, interpreter, skills, license, channels, source, host]
+  const summary = {
+    ok: checks.filter((c) => c.level === 'ok').length,
+    warn: checks.filter((c) => c.level === 'warn').length,
+    fail: checks.filter((c) => c.level === 'fail').length,
+    total: checks.length,
+  }
+  const failed = checks.filter((c) => c.level === 'fail')
+  const ok = failed.length === 0
+  const argent = (() => { try { return readFileSync(join(repo, 'VERSION'), 'utf8').trim() } catch { return null } })()
+
+  const json = {
+    // A2：`ok/empty/code/reason` 恒在；`code` 恒等于进程退出码
+    ok, empty: false, code: ok ? 0 : 1, reason: ok ? null : 'check_failed',
+    verb: 'doctor', subcommand: 'customer', form: 'customer', argent,
+    generatedAt: new Date(now).toISOString(),
+    summary,
+    checks,
+    // 回显**实际生效**的关键条件（A2：过滤/环境条件必须回显，未过滤写 null）
+    dataDir: { dir: dataDir, source: dd.evidence.source, isolated: dd.evidence.isolated, writable: dd.evidence.writable },
+    licenseState: license.evidence.state,
+    interpreterPath: interpreter.evidence.ok ? interpreter.evidence.path : null,
+    hostApplicable: host.applicable,
+    skillRootsScanned: skills.evidence.roots.map((r) => ({ id: r.id, dir: r.dir, installed: r.installed.length })),
+    sideEffects: {
+      writes: 'none', files: [], directories: [], settings: false, credentials: false, notifications: false, subprocesses: ['python（注册表/数据面端口表：只读）'],
+      note: '本 verb **只读**：不建目录、不写文件、不碰 settings.yaml/credentials、不真发通知；可写性用 access(W_OK) 探（不落探针文件）。',
+    },
+    authoritative: {
+      dataDir: dd.evidence.authoritative, interpreter: interpreter.evidence.authoritative, skills: skills.evidence.note,
+      license: license.evidence.authoritative, channels: 'core/lib/notify/index.mjs#listChannels（端口表）',
+      source: source.evidence.authoritative, host: host.evidence.note,
+    },
+    error: failed.length ? `存在 ${failed.length} 条 fail：${failed.map((c) => `${c.id}（${c.title}）`).join('、')}` : null,
+    note: 'M1 判据③：无 dsh **不报 FAIL**（宿主档事实记「本档不适用」）；缺许可、缺技能、缺目录都只记 warn + 处置建议；'
+      + '只有 fail 才 exit 1（A1），warn **不占用 2**。',
+  }
+
+  const icon = { ok: '✅', warn: '⚠️ ', fail: '❌' }
+  const human = [
+    `🩺 Argent 客户机自检（${ok ? '通过' : `未通过：${failed.length} 条 fail`} ｜ ok ${summary.ok} / warn ${summary.warn} / fail ${summary.fail}）`,
+    ...checks.map((c) => `   ${icon[c.level] || '·'} ${c.title}${c.applicable === false ? '（本档不适用）' : ''}：${c.detail}`
+      + (c.advice ? `\n        ↳ ${c.advice}` : '')),
+    '   ⛔ 本次自检没有写任何文件 / 凭据 / settings，也没有发任何通知',
+    summary.fail ? `   ❌ 退出码 1（存在 fail）；修好后重跑：argent doctor --customer` : '   ✅ 退出码 0（warn 只在 JSON 标记，不占用 2）',
+  ].join('\n')
+  return { json, human, stderr: '', exit: Number(json.code) }
+}
+
+function doctorFail(code, reason, error) {
+  return {
+    json: { ok: false, empty: false, code, reason, error, verb: 'doctor', subcommand: 'customer', checks: [], summary: { ok: 0, warn: 0, fail: 0, total: 0 }, usage: DOCTOR_CUSTOMER_USAGE },
+    human: `❌ ${reason}：${error}`, stderr: '', exit: code,
+  }
+}