@whyshu/argent-engine 0.0.0-stage → 0.6.0

package/engine/scripts/argent-doctor.mjs

@@ -0,0 +1,624 @@
+#!/usr/bin/env node
+/**
+ * argent-doctor — Argent 运行时巡检（v0.8 M1 雏形；只读，不改任何文件）
+ *
+ * 检查项：
+ *  1. 三副本漂移：dev 仓库 / ~/.argent-dsh 基座 / 运行库 node_modules 的插件 src+dist md5 一致性
+ *  2. 敏感文件权限：~/.dsh/argent 下 env/config 是否 600（世界可读 = 告警）
+ *  3. 双调度检测：crontab 与 LaunchAgent 是否同时注册同一跑批（poll-fulfillment / poll-invoice / invoice）
+ *  4. 数据卫生：kanban-events.jsonl 体量、invoice 假绿探测（最近 run-*.log 尾含 Traceback/JSONDecodeError）、
+ *     顶层调试 png 数量
+ *  5. gateway.json 基础结构（roles 数组、role 唯一）
+ *  6. 代码卫生（KB-105）：dev 仓库 TODO/FIXME/HACK/XXX 计数（阈值 0，防回归）
+ *  7. 单文件增长（KB-105）：invoice cron.log / fulfillment-logs failures.jsonl / kanban-events.jsonl 超 5MB → WARN
+ *  8. .bak 轮转（KB-105）：~/.dsh/argent 顶层 .bak-* 数量 >6 或权限非 600 → 提示
+ *  9. **排程面体检**（P1-A，2026-10-12；只读；**最高 WARN，从不 FAIL**）：宿主原生排程的
+ *     ① 域文件（`<DSH_HOME>/storages/schedule*`）可解析性 —— 坏了会让**整个宿主拒绝启动**；
+ *     ② 注册表里的 `trigger.schedule` 声明面（读不到 ⇒ WARN，**不能**当成"没声明"）。
+ *     判据 = `scripts/lib/schedule-probe.mjs`（⚠️ 同一份实现；⛔ 这里不另写一套）。
+ *     ⚠️ 本项**不做**在线探针（不访问宿主、不读凭据）—— "宿主挂载了没 / 定时还活着没"要跑
+ *     `node scripts/argent-schedule.mjs check`（四道闸，exit 0/1/2）。
+ *
+ * 用法：node scripts/argent-doctor.mjs [--json]
+ * 退出码：0=全过  1=有 FAIL  2=有 WARN 无 FAIL（默认也返回 2 供肉眼区分）
+ */
+import { createHash } from 'node:crypto'
+import { readFile, readdir, stat } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { execSync, spawnSync } from 'node:child_process'
+import { readdirSync, existsSync, readFileSync } from 'node:fs'
+import { resolveDataDir } from './lib/argent-datadir.mjs'
+
+const HOME = homedir()
+const DEV = fileURLToPath(new URL('..', import.meta.url)) // 本机开发仓库（脚本所在仓库上级）
+const BASE = join(HOME, '.argent-dsh')
+// 运行时插件根可覆盖（2026-09-21）：回归测试用隔离夹具目录跑同一个 doctor，
+// 否则"符号引用"这类静态检查只能靠真机环境验，容易漏掉误报修复的回归。
+const RUNTIME = process.env.ARGENT_DOCTOR_RUNTIME || join(HOME, '.dsh', 'profiles', 'web', 'node_modules')
+// 数据目录：内核三级链（原为硬编码 ~/.dsh/argent ⇒ 隔离实例查的是生产目录，结论会骗人）
+const DATA = resolveDataDir({ env: process.env }).dir
+const jsonOut = process.argv.includes('--json')
+
+const results = []
+const report = (level, check, msg) => results.push({ level, check, msg })
+
+function md5(buf) {
+  return createHash('md5').update(buf).digest('hex')
+}
+
+async function md5File(p) {
+  try {
+    return md5(await readFile(p))
+  } catch {
+    return null
+  }
+}
+
+// ── 1. 三副本漂移 ──────────────────────────────
+async function checkDrift() {
+  const plugins = []
+  try {
+    for (const d of await readdir(join(RUNTIME))) {
+      if (d.startsWith('argent-') && !d.startsWith('argent-bak')) plugins.push(d)
+    }
+  } catch (err) {
+    report('FAIL', '三副本漂移', `读运行库失败: ${err.message}`)
+    return
+  }
+  let bad = 0
+  for (const name of plugins.sort()) {
+    for (const rel of ['src/index.js', 'dist/client.js']) {
+      const dev = await md5File(join(DEV, 'plugins', name, rel))
+      const base = await md5File(join(BASE, 'plugins', name, rel))
+      const run = await md5File(join(RUNTIME, name, rel))
+      if (dev === null && run === null && base === null) continue
+      if (dev !== run || (dev !== null && base !== null && dev !== base)) {
+        bad++
+        report('FAIL', '三副本漂移', `${name}/${rel}: dev=${dev ? dev.slice(0, 7) : '无'} base=${base ? base.slice(0, 7) : '无'} run=${run ? run.slice(0, 7) : '无'}`)
+      }
+    }
+  }
+  if (!bad) report('PASS', '三副本漂移', `检查 ${plugins.length} 个插件 src+dist，三副本一致`)
+}
+
+// ── 2. 敏感文件权限 ────────────────────────────
+async function checkPerms() {
+  const secrets = ['fulfillment.env', 'daily-report.env', 'ziniao-webdriver.env', 'config.json', '.credentials.yaml']
+  for (const f of secrets) {
+    try {
+      const st = await stat(join(DATA, f))
+      const mode = st.mode & 0o777
+      const worldReadable = (mode & 0o004) !== 0
+      if (worldReadable) report('WARN', '文件权限', `${f} 权限 ${mode.toString(8)} 世界可读（建议 600）`)
+    } catch {
+      /* 不存在跳过 */
+    }
+  }
+  const creds = await stat(join(HOME, '.dsh', '.credentials.yaml')).catch(() => null)
+  if (creds) {
+    const mode = creds.mode & 0o777
+    if ((mode & 0o004) !== 0) report('WARN', '文件权限', `.credentials.yaml 权限 ${mode.toString(8)} 世界可读`)
+  }
+}
+
+// ── 3. 双调度检测 ──────────────────────────────
+function checkScheduling() {
+  let cron = ''
+  try {
+    cron = execSync('crontab -l 2>/dev/null || true', { encoding: 'utf8', shell: '/bin/bash' })
+  } catch {
+    cron = ''
+  }
+  let launch = ''
+  try {
+    launch = execSync('launchctl list 2>/dev/null | grep -i "com.whyshu" || true', { encoding: 'utf8', shell: '/bin/bash' })
+  } catch {
+    launch = ''
+  }
+  const cronJobs = [...new Set((cron.match(/poll-fulfillment|poll-invoice|invoice|daily-report/g) || []).map((x) => x))]
+  const launchJobs = [...new Set((launch.match(/com\.whyshu\.[a-z-]+/g) || []).map((x) => x))]
+  for (const key of ['poll-fulfillment', 'poll-invoice', 'invoice', 'daily']) {
+    const inCron = cron.includes(key)
+    const inLaunch = launchJobs.some((l) => l.includes(key) || (key === 'invoice' && l.includes('invoice')))
+    if (inCron && inLaunch) report('WARN', '双调度', `${key}: crontab 与 LaunchAgent 同时注册（可能双跑）`)
+  }
+  if (cronJobs.length || launchJobs.length) {
+    report('PASS', '调度注册', `cron: [${cronJobs.join(', ') || '无'}] launchd: [${launchJobs.join(', ') || '无'}]`)
+  } else {
+    report('PASS', '调度注册', '未发现 whyshu 相关调度项（可能全部在远程机）')
+  }
+}
+
+// ── 4. 数据卫生 ────────────────────────────────
+async function checkHygiene() {
+  try {
+    const ev = await stat(join(DATA, 'kanban-events.jsonl'))
+    const mb = ev.size / 1024 / 1024
+    if (mb > 5) report('WARN', '数据卫生', `kanban-events.jsonl ${mb.toFixed(1)}MB（建议轮转/归档）`)
+  } catch { /* 无文件 */ }
+  // invoice 假绿探测：最近一个 run-*.log 尾部的异常
+  try {
+    const dir = join(DATA, 'invoice-logs')
+    const files = (await readdir(dir)).filter((f) => f.startsWith('run-') && f.endsWith('.log'))
+    if (files.length) {
+      const sorted = files.sort().reverse()
+      const tail = await readFile(join(dir, sorted[0]), 'utf8').catch(() => '')
+      const lines = tail.split('\n').slice(-15)
+      // 判定取「最后出现的运行特征」：日志为追加式，历史失败残留后若已有更新成功输出
+      // （2026-09-06 修复后「无待上传…」跟在旧 traceback 之后）应判 PASS，不得因残留误报
+      let verdict = null
+      for (let i = lines.length - 1; i >= 0; i--) {
+        const ln = lines[i]
+        if (/Traceback|JSONDecodeError|Error|失败/.test(ln)) { verdict = 'FAIL'; break }
+        if (/无待上传|轮询完成|上传|下载标签|阶段 B|成功/.test(ln)) { verdict = 'PASS'; break }
+      }
+      // 陈旧证据容忍（2026-09-24）：判定只能代表**当时**的运行。日志若已 N 小时没更新，
+      // 异常多半是"环境已修好但还没跑过"的残留（实测：09-22 的 openpyxl 缺失 traceback 一直
+      // 把本门禁挂在 FAIL，挡住了 sync-plugins.sh 的整条同步门禁）⇒ 降为 WARN 并写明复核时机。
+      let staleH = 0
+      try {
+        const st = await stat(join(dir, sorted[0]))
+        staleH = (Date.now() - st.mtimeMs) / 3600000
+      } catch { /* 取不到 mtime 按新鲜处理（保守） */ }
+      const STALE_H = Number(process.env.ARGENT_DOCTOR_LOG_STALE_H || 24)
+      if (verdict === 'FAIL' && staleH > STALE_H) {
+        report('WARN', '发票假绿',
+          `最近日志 ${sorted[0]} 尾部含异常，但已 ${staleH.toFixed(1)}h 未更新（>${STALE_H}h）`
+          + ' ⇒ 无法代表当前状态；下次发票运行后复核')
+      } else if (verdict === 'FAIL') {
+        report('FAIL', '发票假绿', `最近日志 ${sorted[0]} 尾部含异常：${lines.slice(-200)}`)
+      } else {
+        report('PASS', '发票假绿', `最近日志 ${sorted[0]} 尾部${verdict === 'PASS' ? '最近输出正常' : '无异常特征'}`)
+      }
+    }
+  } catch { /* 无目录 */ }
+  try {
+    const pngs = (await readdir(DATA)).filter((f) => f.endsWith('.png'))
+    if (pngs.length > 5) report('WARN', '数据卫生', `~/.dsh/argent 顶层 ${pngs.length} 张调试 png（建议清理）`)
+  } catch { /* 忽略 */ }
+}
+
+// ── 5. gateway.json 基础结构 ───────────────────
+async function checkGateway() {
+  try {
+    const gw = JSON.parse(await readFile(join(DATA, 'gateway.json'), 'utf8'))
+    const roles = gw.roles
+    if (!Array.isArray(roles) || !roles.length) {
+      report('FAIL', 'gateway.json', 'roles 缺失或为空')
+      return
+    }
+    const ids = roles.map((r) => r.role)
+    const dup = ids.filter((v, i) => ids.indexOf(v) !== i)
+    if (dup.length) report('FAIL', 'gateway.json', `role 重复: ${[...new Set(dup)].join(',')}`)
+    else report('PASS', 'gateway.json', `${roles.length} 个角色：${ids.join(', ')}`)
+  } catch (err) {
+    report('FAIL', 'gateway.json', `解析失败: ${err.message}`)
+  }
+}
+
+// ── 6. 代码卫生：TODO/FIXME 计数（KB-105）────────────────
+// 扫描 dev 仓库 scripts/plugins/presets/skills（排除 node_modules/.git/dist），
+// 只匹配「注释形态」的 TODO/FIXME/HACK/XXX 标记（排除 mktemp/URL 的 XXX 占位）。
+async function checkCodeHygiene() {
+  const rootDirs = ['scripts', 'plugins', 'presets', 'skills']
+  const exts = ['py', 'js', 'mjs', 'ts', 'sh', 'yml', 'yaml']
+  try {
+    const out = execSync(
+      `grep -rn --include='*.${exts.join("' --include='*.")}' -E '(#|//|/\\*|<!--|--)\\s*(TODO|FIXME|HACK|XXX)\\s*[:：]?\\s*[^Xx]{3,}' ${rootDirs.join(' ')} 2>/dev/null | grep -vE 'node_modules|\\.git/|__pycache__|/dist/' | wc -l`,
+      { encoding: 'utf8', shell: '/bin/bash', cwd: DEV }
+    )
+    const n = parseInt(out.trim(), 10) || 0
+    if (n > 0) report('WARN', '代码卫生', `dev 仓库 ${n} 条 TODO/FIXME/HACK/XXX 注释（阈值 0，建议清理防回归）`)
+    else report('PASS', '代码卫生', 'dev 仓库 0 条 TODO/FIXME/HACK/XXX 注释（无卫生欠账）')
+  } catch {
+    report('PASS', '代码卫生', '扫描跳过（grep 不可用）')
+  }
+}
+
+// ── 7. 单文件增长（KB-105）：>5MB → WARN ─────────────
+async function checkGrowth() {
+  const targets = [
+    ['invoice cron.log', join(DATA, 'invoice-logs', 'cron.log')],
+    ['fulfillment failures.jsonl', join(DATA, 'fulfillment-logs', 'failures.jsonl')],
+    ['kanban-events.jsonl', join(DATA, 'kanban-events.jsonl')],
+  ]
+  for (const [label, p] of targets) {
+    try {
+      const st = await stat(p)
+      const mb = st.size / 1024 / 1024
+      if (mb > 5) report('WARN', '数据卫生', `${label} ${mb.toFixed(1)}MB（建议轮转/归档）`)
+      else report('PASS', '文件增长', `${label} ${mb.toFixed(1)}MB（<5MB）`)
+    } catch { /* 无文件：跳过（非 WARN，文件可能不存在） */ }
+  }
+}
+
+// ── 8. .bak 轮转（KB-105）：>6 份或权限非 600 → 提示 ──
+async function checkBakRotation() {
+  try {
+    const files = (await readdir(DATA)).filter((f) => f.includes('.bak-'))
+    if (!files.length) {
+      report('PASS', '备份轮转', '无 .bak- 备份文件（干净）')
+      return
+    }
+    let permBad = 0
+    for (const f of files) {
+      const st = await stat(join(DATA, f)).catch(() => null)
+      if (st && (st.mode & 0o004) !== 0) permBad++
+    }
+    const hints = []
+    if (files.length > 6) hints.push(`${files.length} 份 .bak-（建议保留近期 3-5 份，超期归档/清理）`)
+    if (permBad) hints.push(`${permBad} 份权限非 600（含敏感配置副本，建议 chmod 600）`)
+    if (hints.length) report('WARN', '备份轮转', hints.join('；'))
+    else report('PASS', '备份轮转', `${files.length} 份 .bak-（≤6 且权限 600）`)
+  } catch {
+    report('PASS', '备份轮转', '检查跳过')
+  }
+}
+
+// ── 9/10 插件静态自检（v0.8-B1 事故复盘 2026-09-04：gateway/drive 双 ctx.provide('argentRoles')
+// 曾致 dsh web 启动崩溃——服务重复注册与语法错误均可静态检出，host 改动发布前必跑）──
+function checkPluginSyntax() {
+  let bad = 0
+  try {
+    const files = []
+    for (const d of readdirSync(RUNTIME)) {
+      if (!d.startsWith('argent-')) continue
+      for (const rel of ['src/index.js', 'dist/client.js']) {
+        const f = join(RUNTIME, d, rel)
+        if (existsSync(f)) files.push(f)
+      }
+    }
+    for (const f of files) {
+      const r = spawnSync(process.execPath, ['--check', f], { encoding: 'utf8' })
+      if (r.status !== 0) {
+        bad++
+        report('FAIL', '插件语法', `${f}: ${(r.stderr || '').slice(0, 200)}`)
+      }
+    }
+    if (!bad) report('PASS', '插件语法', `node --check ${files.length} 个插件文件全部通过`)
+  } catch (e) {
+    report('FAIL', '插件语法', e.message)
+  }
+}
+function checkServiceConflicts() {
+  try {
+    const svcOf = {}
+    const dirs = readdirSync(RUNTIME).filter((d) => d.startsWith('argent-') && !d.startsWith('argent-bak'))
+    for (const d of dirs) {
+      const f = join(RUNTIME, d, 'src', 'index.js')
+      if (!existsSync(f)) continue
+      const lines = readFileSync(f, 'utf8').split('\n')
+      for (const ln of lines) {
+        const t = ln.trim()
+        if (!t || t.startsWith('//') || t.startsWith('*')) continue
+        const m = /ctx\.provide\(\s*['"]([\w]+)['"]/.exec(t)
+        if (m) {
+          const key = m[1]
+          ;(svcOf[key] = svcOf[key] || []).push(d)
+        }
+      }
+    }
+    let dup = 0
+    for (const [name, plugins] of Object.entries(svcOf)) {
+      const uniq = [...new Set(plugins)]
+      if (uniq.length > 1) {
+        dup++
+        report('FAIL', '服务重复注册', `ctx.provide('${name}') 出现在多个插件: ${uniq.join(', ')}（cordis 启动将崩溃）`)
+      }
+    }
+    if (!dup) report('PASS', '服务重复注册', `共 ${Object.keys(svcOf).length} 个服务名，无跨插件重复`)
+  } catch (e) {
+    report('FAIL', '服务重复注册', e.message)
+  }
+}
+
+// ── 11 符号引用完整性（v0.8-B2 事故复盘 2026-09-04：瘦身误删 MENTION_NAMES/ROLE_NAMES/
+// ROLE_PREFIX 与 CONFIG_FILE/GATEWAY_FILE——引用仍在而定义被删，前者 ReferenceError、
+// 后者在 try/catch 内静默失败。host 插件重构后跑本检查可拦截此类误删）──
+const JS_BUILTIN_UPPER = new Set(('JSON Math Date Promise Buffer URL URLSearchParams AbortController AbortSignal TextEncoder TextDecoder Map Set WeakMap WeakSet Symbol Error TypeError RangeError SyntaxError ReferenceError RegExp Proxy Reflect Object Array String Number Boolean BigInt Function Atomics ArrayBuffer DataView Intl WebAssembly Headers Request Response FormData Blob File Event EventTarget setTimeout clearTimeout setInterval clearInterval queueMicrotask structuredClone crypto performance navigator window document React globalThis fetch').split(' '))
+
+/**
+ * 逐字符 JS 扫描器（2026-10-02 重写词法器 + 加**作用域**建模）。
+ * 返回 `{ defs: Map<名字, [定义处的大括号深度…]>, refs: [{name, depth}] }`。
+ *
+ * ## 为什么必须换成状态机（真因，实测）
+ * 旧管线是"正则互相踩"：先按块注释 `/* … *\/` 删，**再**删行注释。而
+ * `plugins/argent-core/src/index.js:1290` 的**行注释**里有一个 `/*`（`` …/env/*.env` ``）⇒
+ * 被当成块注释开头，一路吞到下一个 `*\/`（:1424），把中间 **134 行**（含 :1387 的
+ * `const BILLING_SETTINGS = …`）从"已定义集合"里删掉，而 :1427 的**使用**还在
+ * ⇒ 假阳性「引用未定义常量 BILLING_SETTINGS」。
+ * （实测佐证：原文 2075 行；只跑块注释那一步就剩 1912 行，BILLING_SETTINGS 出现次数 2 → 1。）
+ *
+ * ## 作用域（第二条判据）
+ * 定义记在**它所在的大括号深度**上；一个引用只有在**同层或外层**（`定义深度 <= 引用深度`）
+ * 才能算已定义 —— 于是"同一 apply/闭包里的 const 被内层嵌套函数引用"是合法的（不再误报），
+ * 而"只在内层/兄弟作用域定义过"仍会被抓住。注意这条比旧版**更严**（旧版是全文级 defined 集合）。
+ *
+ * ## 有意保守之处（宁可漏报，不可误报）
+ * · `深度 <= ` 不区分兄弟块 ⇒ `{ const A = 1 }  { A }` 仍判"已定义"（漏报，不是误报）；
+ * · 函数/箭头**形参**不建定义（实测本仓插件无大写形参；真出现会退化成"引用"，属已知保守边界）。
+ */
+function scanJsSymbols(src) {
+  const defs = new Map()
+  const refs = []
+  const n = src.length
+  const ID_START = /[A-Za-z_$]/
+  const ID_PART = /[A-Za-z0-9_$]/
+  // 这些"上一个 token"之后出现的 `/` 只可能是**正则字面量**（除法不会出现在这些位置）
+  const REGEX_OK = new Set(['', '(', '=', ',', ':', '[', '!', '&', '|', '?', '{', '}', ';',
+    'return', 'typeof', 'case', '=>', '+', '-', '*', '%', '<', '>', '~', '^'])
+  const skipString = (i, q) => {
+    let j = i + 1
+    while (j < n) {
+      const c = src[j]
+      if (c === '\\') { j += 2; continue }
+      if (c === q) return j + 1
+      if (c === '\n') return j          // 未闭合（多半不是字符串）⇒ 止损，别吞掉后面整片
+      j++
+    }
+    return j
+  }
+  const skipRegex = (i) => {
+    let j = i + 1, inClass = false
+    while (j < n) {
+      const c = src[j]
+      if (c === '\\') { j += 2; continue }
+      if (c === '\n') break             // 未闭合 ⇒ 当除法止损
+      if (c === '[') inClass = true
+      else if (c === ']') inClass = false
+      else if (c === '/' && !inClass) { j++; break }
+      j++
+    }
+    while (j < n && /[gimsuy]/.test(src[j])) j++
+    return j
+  }
+  const addDef = (name, d) => { const a = defs.get(name) || []; a.push(d); defs.set(name, a) }
+
+  let i = 0, depth = 0, prev = '', decl = null, importing = false
+  const tmpl = []                        // 模板栈：{mode:'body'|'expr', depth}
+  while (i < n) {
+    const top = tmpl.length ? tmpl[tmpl.length - 1] : null
+    if (top && top.mode === 'body') {    // 模板正文态：只认 `\` / 反引号 / `${`
+      const c = src[i]
+      if (c === '\\') { i += 2; continue }
+      if (c === '`') { tmpl.pop(); i++; prev = '`'; continue }
+      if (c === '$' && src[i + 1] === '{') { top.mode = 'expr'; i += 2; prev = '('; continue }
+      i++
+      continue
+    }
+    const c = src[i]
+    if (c === ' ' || c === '\t' || c === '\r' || c === '\n') { i++; continue }
+    if (c === '/' && src[i + 1] === '/') { while (i < n && src[i] !== '\n') i++; continue }        // 行注释
+    if (c === '/' && src[i + 1] === '*') {                                                          // 块注释
+      i += 2
+      while (i < n && !(src[i] === '*' && src[i + 1] === '/')) i++
+      i += 2
+      continue
+    }
+    if (c === '/' && REGEX_OK.has(prev)) { i = skipRegex(i); prev = 'RE'; continue }                 // 正则字面量
+    if (c === '"' || c === "'") { i = skipString(i, c); prev = 'STR'; importing = false; continue }  // 字符串
+    if (c === '`') { tmpl.push({ mode: 'body', depth }); i++; continue }                             // 模板开始
+    if (ID_START.test(c)) {
+      let j = i + 1
+      while (j < n && ID_PART.test(src[j])) j++
+      const name = src.slice(i, j)
+      i = j
+      let k = i
+      while (k < n && /\s/.test(src[k])) k++
+      const isKey = src[k] === ':' && prev !== 'case' && prev !== '?'   // 对象键/标签；`case X:`、`a ? X :` 不算
+      if (prev === '.') { /* 成员访问：不是引用 */ }
+      else if (importing) { if (name !== 'from' && name !== 'as' && name !== 'type') addDef(name, depth) }
+      else if (prev === 'import') importing = true
+      else if (prev === 'function' || prev === 'class') addDef(name, depth)
+      else if (prev === 'const' || prev === 'let' || prev === 'var') { if (!isKey) addDef(name, depth); decl = depth }
+      else if (decl !== null) {
+        if (name === 'of' || name === 'in') decl = null                  // for (const K of …)
+        else if (!isKey) addDef(name, depth)                             // 解构/多声明：const { A, B } = …
+      } else if (!isKey) refs.push({ name, depth })
+      prev = name
+      continue
+    }
+    if (c === '{') { depth++; prev = '{'; i++; continue }
+    if (c === '}') {
+      if (top && top.mode === 'expr' && depth === top.depth) top.mode = 'body'   // 关掉 ${…}，回模板正文
+      else { depth--; if (decl !== null && decl > depth) decl = null }
+      prev = '}'
+      i++
+      continue
+    }
+    if (c === '(' || c === ')' || c === '[' || c === ']' || c === ';' || c === '=') {
+      if (decl !== null && (c === '=' || c === ';' || c === ')')) decl = null
+      prev = c
+      i++
+      continue
+    }
+    prev = c
+    i++
+  }
+  return { defs, refs }
+}
+
+function checkSymbolIntegrity() {
+  try {
+    // 词法/作用域：见上方 scanJsSymbols（逐字符状态机 + 大括号作用域）
+    const dirs = readdirSync(RUNTIME).filter((d) => d.startsWith('argent-') && !d.startsWith('argent-bak'))
+    let totalBad = 0
+    // ⚠️ 这里**没有白名单**（2026-10-02 删掉旧的 `FEISHU_WEBHOOK_URL` 条目）：新扫描器下它只出现在
+    //    行注释/字符串/正则字面量里（argent-core:1664/1667/1673）⇒ 根本不会成为 token，无需豁免。
+    //    修假阳性的正确姿势是**修判据**（见 scanJsSymbols），不是把名字加进豁免表。
+    const IS_CONST = /^[A-Z][A-Z0-9_]{2,}$/
+    for (const d of dirs) {
+      const f = join(RUNTIME, d, 'src', 'index.js')
+      if (!existsSync(f)) continue
+      const { defs, refs } = scanJsSymbols(readFileSync(f, 'utf8'))
+      // 已定义 = 存在 `定义深度 <= 引用深度` 的定义（本层或**外层**作用域 ⇒ 闭包里的 const 合法）
+      const definedAt = (name, depth) => (defs.get(name) || []).some((dep) => dep <= depth)
+      const bad = new Map()
+      for (const r of refs) {
+        if (!IS_CONST.test(r.name)) continue
+        if (JS_BUILTIN_UPPER.has(r.name)) continue
+        if (definedAt(r.name, r.depth)) continue
+        bad.set(r.name, (bad.get(r.name) || 0) + 1)
+      }
+      for (const [name, cnt] of bad) {
+        totalBad++
+        report('FAIL', '符号引用', `${d}: 引用未定义常量「${name}」（${cnt} 处；疑似重构误删定义——host 启动将崩溃或静默失败）`)
+      }
+      for (const name of defs.keys()) {
+        if (!IS_CONST.test(name)) continue
+        if (refs.some((r) => r.name === name)) continue
+        report('WARN', '符号死代码', `${d}: 常量 ${name} 无引用（可清理）`)
+      }
+    }
+    if (!totalBad) report('PASS', '符号引用完整', `扫描 ${dirs.length} 个插件 src：无「引用未定义」大写常量`)
+  } catch (e) {
+    report('FAIL', '符号引用完整', e.message)
+  }
+}
+
+/**
+ * 看板写路径收口（§8.5 P0-③）：把"看板是投影窗口"变成**发布门禁**，而不只是单测守卫。
+ * 判据（扫 dev 仓库所有插件源文件）：
+ *   ① 裸写 `kb.(comment|move|create|update|remove)(` 只允许出现在**收口文件**里（CHOKE 白名单，含理由）；
+ *   ② 收口文件必须同时打审计行（writeAuditLine）——否则无法复盘"这条写是投影还是意图"；
+ *   ③ 除 kanban 服务自身外，**任何插件不得出现 `kb.create(`/`kb.remove(`**（自动化不得建卡/删卡）；
+ *   ④ 源码里出现的每个 `comment./move./create.` op 字面量都必须已在 WRITE_SURFACE 登记类别。
+ * 写面清单的**真源是插件模块本身**（这里直接 import，避免 doctor 抄一份而漂移）。
+ */
+async function checkKanbanWrites() {
+  try {
+    const pluginsDir = join(DEV, 'plugins')
+    // 2026-09-15 P4-4c：argent-drive / argent-kanban 已退场 ⇒ 该检查失去对象，
+    // 直接跳过（否则 import 崩溃会被误报成 FAIL）。
+    {
+      const { existsSync } = await import('node:fs')
+      if (!existsSync(join(pluginsDir, 'argent-drive', 'src', 'kanban-writes.js'))) {
+        report('PASS', '看板写收口', 'argent-drive/kanban 已退场，跳过该检查')
+        return
+      }
+    }
+    const driveMod = await import(pathToFileURL(join(pluginsDir, 'argent-drive', 'src', 'kanban-writes.js')).href)
+    const registered = new Set(Object.keys(driveMod.WRITE_SURFACE || {}))
+    const CHOKE = new Map([
+      ['argent-drive/src/index.js', 'drive 执行内核：kbWrite 收口 + kbComment/kbMove'],
+      ['argent-drive/src/observe.js', 'observe 投影：project() 是其唯一写入口'],
+      ['argent-kanban/src/index.js', 'kanban 服务自身实现'],
+      ['argent-notify/src/index.js', '渠道层：飞书全链失败时的卡评论留痕（kbComment 是唯一写入口）'],
+    ])
+    const RAW_WRITE = /\bkb\.(comment|move|create|update|remove)\(/g
+    const stripComments = (s) => s.split('\n').filter((l) => !/^\s*(\/\/|\*|\/\*)/.test(l)).join('\n')
+    let bad = 0
+    let scanned = 0
+    const chokeSeen = new Set()
+    for (const d of readdirSync(pluginsDir).filter((x) => x.startsWith('argent-') && !x.startsWith('argent-bak'))) {
+      const srcDir = join(pluginsDir, d, 'src')
+      if (!existsSync(srcDir)) continue
+      for (const f of readdirSync(srcDir).filter((x) => x.endsWith('.js'))) {
+        const rel = `${d}/src/${f}`
+        const raw = readFileSync(join(srcDir, f), 'utf8')
+        const code = stripComments(raw)
+        scanned++
+        const rawHits = [...code.matchAll(RAW_WRITE)]
+        if (rawHits.length) {
+          if (CHOKE.has(rel)) {
+            chokeSeen.add(rel)
+            // 审计行判据二选一：① 调用共享 helper `writeAuditLine(`（格式集中在 kanban-writes.js）；
+            // ② 自带一个同格式字面量 `[write] class=`（跨插件不便 import 时，格式仍必须统一）。
+            // 这样 `grep '\[write\] class='` 能一次看到全系统写面。
+            // 注意：必须查**剥掉注释**后的代码——否则文件里的文档注释（"须打 [write] class=…"）会假通过
+            const auditOk = code.includes('writeAuditLine(') || /\[write\] class=/.test(code)
+            if (!auditOk) {
+              bad++
+              report('FAIL', '看板写收口', `${rel}: 有裸写但没有审计行（须打 "[<who>][write] class=… op=… card=…"）→ 无法复盘写类别`)
+            }
+          } else {
+            bad++
+            report('FAIL', '看板写收口', `${rel}: 出现裸写 ${rawHits[0][0]} —— 必须经收口（或在 doctor 的 CHOKE 白名单登记并写明理由）`)
+          }
+        }
+        if (rel !== 'argent-kanban/src/index.js' && /\bkb\.(create|remove)\(/.test(code)) {
+          bad++
+          report('FAIL', '看板写收口', `${rel}: 出现 kb.create(/kb.remove( —— 自动化不得建卡/删卡（§8.5 P0-③ origination 禁用）`)
+        }
+        for (const m of code.matchAll(/'(comment|move|create)\.[a-z][a-z-]*'/g)) {
+          const op = m[0].slice(1, -1)
+          if (!registered.has(op)) {
+            bad++
+            report('FAIL', '看板写收口', `${rel}: 未登记的写 op「${op}」（须在 kanban-writes.WRITE_SURFACE 登记类别）`)
+          }
+        }
+      }
+    }
+    if (!bad) {
+      report('PASS', '看板写收口', `扫描 ${scanned} 个插件源文件：裸写仅在 ${chokeSeen.size} 个收口处且都有审计行；无未登记 op、无建卡/删卡`)
+    }
+  } catch (e) {
+    report('FAIL', '看板写收口', e.message)
+  }
+}
+
+// ── 13. 排程面体检（P1-A，2026-10-12；只读；最高 WARN，**从不 FAIL**）──
+// 判据 = `scripts/lib/schedule-probe.mjs`（同一份实现）。离线档：只读域文件 + 注册表声明。
+// ⛔ 不访问宿主、不读凭据（"挂载/新鲜度/执行"三闸在 `scripts/argent-schedule.mjs check` 里）。
+async function checkScheduleFace() {
+  let probe
+  try {
+    probe = await import('./lib/schedule-probe.mjs')
+  } catch (e) {
+    report('WARN', '排程面', `判据模块取不到（scripts/lib/schedule-probe.mjs）：${e.message} ⇒ **不能**当成"排程面没问题"`)
+    return
+  }
+  // ① 域文件（坏了 ⇒ 宿主拒绝启动；不存在 ⇒ 排程从未启用，**不是故障**）
+  let inspection
+  try {
+    const paths = probe.domainPaths(probe.storageRoot({ dshHome: process.env.DSH_HOME || undefined }))
+    inspection = probe.inspectDomain(paths)
+    if (inspection.state === 'corrupt') {
+      report('WARN', '排程面', `排程域文件非法（${inspection.problems.length} 处）⇒ **宿主会拒绝启动整个 domain（连对话一起）**：`
+        + inspection.problems.slice(0, 3).map((p) => `${p.path}：${p.issue}`).join('；')
+        + `｜修法：先整份备份 ${inspection.paths.unitDir} 与 ${inspection.paths.legacyFile}，再按点名文件修`
+        + '（逐记录文件可直接删：宿主把读不出的记录**当作不存在**丢弃）')
+    } else if (inspection.state === 'unreadable') {
+      report('WARN', '排程面', `排程域文件读不了（${inspection.problems[0] ? inspection.problems[0].issue : '权限/IO'}）⇒ 不能判好坏`)
+    }
+  } catch (e) {
+    report('WARN', '排程面', `域文件检查没跑成：${e.message}`)
+    return
+  }
+  // ② 声明面（注册表读不到 ⇒ WARN；⛔ 不静默当"没声明"）
+  let declared = []
+  try {
+    const { loadRegistryDoc } = await import('./lib/registry.mjs')
+    const doc = loadRegistryDoc({ root: DEV })
+    declared = Object.entries(doc.flows || {})
+      .map(([id, spec]) => ({ id, s: spec && spec.trigger && spec.trigger.schedule }))
+      .filter((x) => x.s && typeof x.s === 'object')
+  } catch (e) {
+    report('WARN', '排程面', `注册表读不到 ⇒ **不能**下"没有流程声明排程"的结论：${String((e && (e.stderr || e.message)) || e).split('\n')[0]}`)
+    return
+  }
+  const enabled = declared.filter((d) => d.s.enabled === true)
+  if (inspection.state === 'absent' && !enabled.length) {
+    report('PASS', '排程面', `排程未启用（域文件未落盘；声明 ${declared.length} 条、enabled ${enabled.length} 条）⇒ 无需判`)
+    return
+  }
+  report('PASS', '排程面', `域文件 ${inspection.state}（${inspection.files.length} 个）｜声明 ${declared.length} 条、enabled ${enabled.length} 条`
+    + `${enabled.length ? `（${enabled.map((d) => d.id).join('、')}）` : ''}`
+    + '｜"挂载了没 / 定时还活着没"跑 `node scripts/argent-schedule.mjs check`')
+}
+
+const checks = [checkDrift, checkPerms, checkScheduling, checkHygiene, checkGateway, checkCodeHygiene, checkGrowth, checkBakRotation, checkPluginSyntax, checkServiceConflicts, checkSymbolIntegrity, checkKanbanWrites, checkScheduleFace]
+for (const c of checks) await c()
+
+const fails = results.filter((r) => r.level === 'FAIL')
+const warns = results.filter((r) => r.level === 'WARN')
+const passes = results.filter((r) => r.level === 'PASS')
+if (jsonOut) {
+  process.stdout.write(JSON.stringify({ summary: { pass: passes.length, warn: warns.length, fail: fails.length }, results }, null, 2) + '\n')
+} else {
+  for (const r of results) process.stdout.write(`[${r.level}] ${r.check}: ${r.msg}\n`)
+  process.stdout.write(`\nargent-doctor: PASS ${passes.length} / WARN ${warns.length} / FAIL ${fails.length}\n`)
+}
+process.exit(fails.length ? 1 : warns.length ? 2 : 0)