@whyshu/argent-engine 0.0.0-stage → 0.6.0

package/engine/scripts/lib/schedule-probe.mjs

@@ -0,0 +1,835 @@
+#!/usr/bin/env node
+/**
+ * schedule-probe —— 「宿主原生排程到底还在不在、还在不在干活」的**唯一只读判据**（P1-A，2026-10-12）
+ *
+ * ══════════════════════════════════════════════════════════════════════════
+ * 为什么必须有它（本模块的由来）
+ * ══════════════════════════════════════════════════════════════════════════
+ * 把定时从「OS 计划任务 + `scripts/flow-trigger*`」换成「宿主原生排程」时，**观测面会整体搬家**：
+ *   · 现在：定时器在**我们自己的**脚本里 ⇒ 跑没跑看 `verticals/<id>/logs/flow-trigger-<flow>.log`；
+ *   · 换后：定时在**宿主插件**里 ⇒ 「投递失败**只写宿主自己的日志、不重试**」
+ *     （上游设计文档《dsh-排程插件评估与迁移设计》§0.4/§6.2 实测），而且**投递回执只证明
+ *     "消息进了会话收件箱"，不证明"模型执行了"**。
+ * ⇒ 直接切过去 = **净退步**（定时停了没人知道）。本模块把「怎么证明它还在跑」变成**可复制的判据**：
+ *   四道闸（挂载 / 新鲜度 / 执行 / 持久化），每道闸都给出 `state` + 人可读的下一步。
+ *
+ * ══════════════════════════════════════════════════════════════════════════
+ * 纪律（改本文件前先读这三条）
+ * ══════════════════════════════════════════════════════════════════════════
+ * 1. **纯 L1**：只用 node 内建（`fs`/`path`/`os`）+ 同层 `lib/wake-auth.mjs` 的**调用方注入**形态
+ *    —— ⛔ 不 import 任何宿主模块（`node scripts/tests/kernel-purity.test.mjs` 会查）。
+ *    与宿主的全部交互都是**HTTP + 文件读取**，所以本文件可以在没有宿主、没有 python 的机器上跑判据。
+ * 2. **只读**：本文件**不写任何文件、不删任何任务、不读/不落凭据**（cookie 由调用方传进来）。
+ *    唯一会改宿主的动作（停/建任务）在 `scripts/argent-schedule.mjs` 里，且默认 dry-run。
+ * 3. **判据来自宿主契约，不是猜的**（2026-10-12 读 0.1.7-rc.2 的包内 TYPERT + domain 定义）：
+ *    · 端点 = `POST /api/<endpoint>`，信封 `{type:"client-request",rpcId,method,payload:{args}}`
+ *      ⇒ 200 `{type:"server-response",result:{ok:true,value:…}}`；**未挂载 = 404 `not found`**
+ *      （源码：`dsh-client-connection` 的 `rpcFetchHandler` / 共享通道 404 分支）。
+ *    · 排程域 = `defineDomain({name:"schedule",version:1,tables:{tasks:…}})`，落盘布局
+ *      `<存储根>/schedule/tasks/<id>.json`（逐记录）+ 旧整体文件 `<存储根>/schedule.json`（保留不动）。
+ *    · **一条非法任务会拒绝打开整个 domain**（宿主源码原话：malformed tasks reject opening the domain）
+ *      ⇒ 域文件坏掉会拖垮整个宿主（连对话一起）⇒ 这就是第 4 闸存在的理由。
+ *
+ * ══════════════════════════════════════════════════════════════════════════
+ * 四道闸（判据可复制；`scripts/argent-schedule.mjs check` 是它们的 CLI 出口）
+ * ══════════════════════════════════════════════════════════════════════════
+ * | # | 闸 | 判据 | 防的静默 |
+ * |---|---|---|---|
+ * | ① | 挂载 | `POST /api/schedule/catalog` 返回 **404 ⇒ 红**（没挂载）；200 ⇒ 绿 | 宿主升级把组合里那三行删掉（0.1→0.2 实测就是这个行为） |
+ * | ② | 新鲜度 | `now - lastDelivery.deliveredAt > 1.5 × 周期` ⇒ **红**；无回执且已超期 ⇒ 红 | 宿主死了 / 任务被停 / 定时器没起来 |
+ * | ③ | 执行 | 回执推进 **∧** L1（轮次日志 mtime + 台账最新事件）无新证据 ⇒ **红** | 「投递了但没人干活」（排程 prompt 是静态的 ⇒ 确定性从引擎保证退化为模型遵守） |
+ * | ④ | 持久化 | 域文件**可解析** ∧ 关键不变量成立（坏 ⇒ 宿主拒启） | 任务库损坏拖垮整个宿主 |
+ * | ⑤ | 单一调度者 | 同一条流程被**两条线同时**调度 ⇒ **红**（原生任务 × 激活垫片） | 双跑抢同一批生产行（台账每机独立、lease 无跨调度者互斥） |
+ *
+ * ⑤ 的**判据实现只有一处**：`scripts/lib/schedule-mechanism.mjs#resolveScheduleMechanism()` /
+ * `schedulerConflict()`（0.6.0 W8）。本文件只把它的结论**渲染成一道闸**（⛔ 不重写判据）。
+ *
+ * 跑法（回归，纯夹具零网络）：`node scripts/tests/schedule-probe.test.mjs`
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { isAbsolute, join } from 'node:path'
+
+// ══════════════════════════════════════════════════════════════════════════
+// 一、宿主契约常量（**唯一出处**：宿主包的 TYPERT 反射 + domain 定义；⛔ 别在别处再抄一份）
+// ══════════════════════════════════════════════════════════════════════════
+
+/** 共享 RPC 通道（宿主 web 的固定前缀）。 */
+export const API_CHANNEL = '/api'
+
+/** 挂载判据用的端点（**只读、无参数**）：它是"排程服务在不在组合里"的最小探针。 */
+export const MOUNT_ENDPOINT = 'schedule/catalog'
+
+/** 排程服务的全部 RPC 端点（0.1.7-rc.2 与 0.2.0-rc.2 实测**完全相同**）。 */
+export const ENDPOINTS = Object.freeze({
+  catalog: 'schedule/catalog',   // 读：全部任务（含 inactive）+ 会话绑定 + lastDelivery
+  history: 'schedule/history',   // 读：某个任务的投递历史（分页）
+  list: 'schedule/list',         // 读：某个会话的 active 任务
+  delete: 'schedule/delete',     // 写：删任务（行没了 ⇒ 不再排程；投递记录一并消失）
+  update: 'schedule/update',     // 写：改标题/指令/时机（⛔ **改不了 status**）
+})
+
+/**
+ * ⚠️ **能力缺口（2026-10-12 读源码确认，影响 P1-B 的 `onPause: deactivate`）**：
+ * 宿主**没有**任何"把任务置为 inactive"的公开面 ——
+ *   · `schedule/create` **不是** Remote 端点（只在会话内由工具调用，且**恒写 `status:"active"`**）；
+ *   · `schedule/update` 明确拒绝已 inactive 的任务，且 `change` 只含 title/prompt/时机；
+ *   · `schedule/delete` 是**唯一**能让一条重复任务不再触发的远端动作（代价：投递历史随行消失）；
+ *   · `inactive` 只有两种来源：一次性任务投递完成、重复任务算不出下一次发生时点。
+ * ⇒ 「`PAUSE_*` 文件 ⇒ 任务 `inactive`」这条收敛**无法用现成 API 实现**；本模块如实判定，
+ *   把"停"的可用原语（delete + 审计留档）交给 CLI，把"启"（create 需要**会话内工具**）标成待办。
+ */
+export const STATUS_SETTER_AVAILABLE = false
+
+/** 排程域（落盘布局与"坏文件 ⇒ 拒绝启动"的判据都在这里）。 */
+export const DOMAIN = Object.freeze({ name: 'schedule', version: 1, table: 'tasks' })
+
+/** 选择器与限额（宿主硬约束；超了宿主会拒，所以门禁也要按同一套判）。 */
+export const KINDS = Object.freeze(['after', 'at', 'every', 'daily', 'weekly', 'cron'])
+export const MIN_EVERY_SECONDS = 60
+export const MAX_TITLE_LENGTH = 120
+
+/** 新鲜度闸的系数（上游设计 §6.2 第 2 闸：`> 1.5 × 周期` ⇒ 红）。 */
+export const FRESHNESS_FACTOR = 1.5
+
+/** 执行闸的宽限（秒）：投递到"L1 真的动了"之间的正常延迟（会话恢复 + 派发 + 认领）。 */
+export const DEFAULT_GRACE_SEC = 180
+
+/** 台账尾部读取的字节数（台账是追加型 JSONL，可能很大 ⇒ 只读尾巴）。 */
+export const DEFAULT_LEDGER_TAIL_BYTES = 512 * 1024
+
+/** 一天的秒数（daily/weekly 的周期由此推出 —— 与宿主"本地钟表时间"语义一致）。 */
+const DAY_SEC = 86400
+
+// ══════════════════════════════════════════════════════════════════════════
+// 二、位置判据（存储根 / 域文件 / L1 证据面）
+// ══════════════════════════════════════════════════════════════════════════
+
+/**
+ * 宿主的**存储根**：`<DSH_HOME>/storages`（`DSH_HOME` 缺省 `~/.dsh`）。
+ * ⚠️ 这是**宿主自己的**目录，不是 Argent 数据目录（`<DSH_HOME>/argent`，那个的唯一判据在
+ * `core/lib/argent-datadir.mjs`）⇒ 这里不引用它、也不改它。
+ */
+export function storageRoot({ dshHome, env = process.env, home = homedir() } = {}) {
+  const h = dshHome || (env && env.DSH_HOME) || join(home, '.dsh')
+  return join(h, 'storages')
+}
+
+/** 排程域的候选落盘路径（**逐记录布局**优先；旧整体文件是历史形态，宿主读取时会迁移但**保留原文件**）。 */
+export function domainPaths(root) {
+  const base = root || storageRoot()
+  return {
+    root: base,
+    unitDir: join(base, DOMAIN.name),
+    tableDir: join(base, DOMAIN.name, DOMAIN.table),
+    globalFile: join(base, DOMAIN.name, 'global.json'),
+    legacyFile: join(base, `${DOMAIN.name}.json`),
+  }
+}
+
+const statOr = (p) => { try { return statSync(p) } catch { return null } }
+const readText = (p) => { try { return { ok: true, text: readFileSync(p, 'utf8') } } catch (e) { return { ok: false, error: String((e && (e.code || e.message)) || e) } } }
+
+/** 域文件（`<tableDir>/*.json` + 旧整体文件 + `global.json`）的**只读清单**。 */
+export function listDomainFiles(paths) {
+  const out = []
+  const dir = paths.tableDir
+  const st = statOr(dir)
+  if (st && st.isDirectory()) {
+    let names = []
+    try { names = readdirSync(dir) } catch { names = [] }
+    for (const n of names.filter((x) => x.endsWith('.json')).sort()) {
+      out.push({ kind: 'record', key: n.slice(0, -5), path: join(dir, n) })
+    }
+  }
+  if (statOr(paths.legacyFile)) out.push({ kind: 'legacy', key: '', path: paths.legacyFile })
+  if (statOr(paths.globalFile)) out.push({ kind: 'global', key: '', path: paths.globalFile })
+  return out
+}
+
+// ══════════════════════════════════════════════════════════════════════════
+// 三、任务记录校验（宿主 domain schema 的**只读镜像**：只覆盖"会让宿主拒绝打开 domain"的那几条）
+// ══════════════════════════════════════════════════════════════════════════
+
+const isObj = (v) => v !== null && typeof v === 'object' && !Array.isArray(v)
+const isStr = (v) => typeof v === 'string'
+const nonEmptyStr = (v) => isStr(v) && v.trim() !== ''
+const isoOrNull = (v) => (nonEmptyStr(v) && Number.isFinite(Date.parse(v)) ? v : null)
+const HHMMSS = /^([01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d{1,3})?)?$/
+
+/**
+ * 校验一条 `tasks` 记录（`{sessionId, record, status, lastDelivery?, deliveryHistory?}`）。
+ * @returns {string[]} 问题清单（空 = 通过；非空 ⇒ 宿主会拒绝打开整个 domain）
+ */
+export function validateTask(task) {
+  const p = []
+  if (!isObj(task)) return ['任务不是对象']
+  if (!nonEmptyStr(task.sessionId)) p.push('缺 sessionId')
+  if (!['active', 'inactive'].includes(task.status)) p.push(`status=${JSON.stringify(task.status)}（只允许 active|inactive）`)
+  const r = task.record
+  if (!isObj(r)) {
+    p.push('缺 record')
+  } else {
+    if (!nonEmptyStr(r.id)) p.push('record 缺 id')
+    if (!nonEmptyStr(r.title)) p.push('record 缺 title')
+    else if (r.title.length > MAX_TITLE_LENGTH) p.push(`record.title 超长（${r.title.length} > ${MAX_TITLE_LENGTH}）`)
+    else if (r.title.trim() !== r.title) p.push('record.title 首尾有空白（宿主拒）')
+    if (!isStr(r.prompt)) p.push('record 缺 prompt')
+    if (!KINDS.includes(r.kind)) p.push(`record.kind=${JSON.stringify(r.kind)}（只允许 ${KINDS.join('|')}）`)
+    if (!isoOrNull(r.scheduledAt)) p.push('record.scheduledAt 不是可解析的时间')
+    if (r.kind === 'every' && !(Number.isFinite(r.everySeconds) && r.everySeconds >= MIN_EVERY_SECONDS)) {
+      p.push(`kind=every 的 everySeconds 必须 ≥ ${MIN_EVERY_SECONDS}（实得 ${JSON.stringify(r.everySeconds)}）`)
+    }
+    if (['daily', 'weekly', 'cron'].includes(r.kind) && !nonEmptyStr(r.timeZone)) p.push(`kind=${r.kind} 缺 timeZone`)
+    if (['daily', 'weekly'].includes(r.kind) && !HHMMSS.test(String(r.time || ''))) p.push(`kind=${r.kind} 的 time=${JSON.stringify(r.time)} 不是 HH:mm:ss`)
+    if (r.kind === 'weekly' && !(Array.isArray(r.weekdays) && r.weekdays.length)) p.push('kind=weekly 缺 weekdays')
+    if (r.kind === 'cron' && !nonEmptyStr(r.expression)) p.push('kind=cron 缺 expression')
+    if (r.kind === 'after' && !Number.isFinite(r.afterSeconds)) p.push('kind=after 缺 afterSeconds')
+  }
+  const ld = task.lastDelivery
+  if (ld !== undefined) {
+    if (!isObj(ld)) p.push('lastDelivery 不是对象')
+    else {
+      if (!isoOrNull(ld.scheduledAt)) p.push('lastDelivery.scheduledAt 不可解析')
+      if (!isoOrNull(ld.deliveredAt)) p.push('lastDelivery.deliveredAt 不可解析')
+      if (!nonEmptyStr(ld.messageId)) p.push('lastDelivery 缺 messageId')
+    }
+  }
+  const dh = task.deliveryHistory
+  if (dh !== undefined) {
+    if (!isObj(dh) || !Array.isArray(dh.records)) {
+      p.push('deliveryHistory 缺 records 数组')
+    } else {
+      if (typeof dh.earlierRecordsUnavailable !== 'boolean') p.push('deliveryHistory 缺 earlierRecordsUnavailable（布尔）')
+      const latest = dh.records[dh.records.length - 1]
+      // 宿主 schema 的 refine：**最新一条投递记录必须与 lastDelivery 一致**（不一致 ⇒ 拒绝打开 domain）
+      if (latest === undefined) {
+        if (ld !== undefined) p.push('deliveryHistory 为空但存在 lastDelivery（宿主拒）')
+      } else if (ld === undefined) {
+        p.push('有 deliveryHistory 但没有 lastDelivery（宿主拒）')
+      } else if (latest.scheduledAt !== ld.scheduledAt || latest.deliveredAt !== ld.deliveredAt || latest.messageId !== ld.messageId) {
+        p.push('deliveryHistory 最新一条与 lastDelivery 不一致（宿主拒：Last delivery must match the latest saved delivery receipt）')
+      }
+    }
+  }
+  return p
+}
+
+/**
+ * 读并校验排程域文件（**只读**）。
+ * @returns {{state:'absent'|'ok'|'corrupt'|'unreadable', paths:object, files:Array, tasks:Array,
+ *            problems:Array<{path:string, issue:string}>, deliveries:Array}}
+ *   · `absent`     —— 域从未落盘（排程没启用过）⇒ **不是故障**
+ *   · `ok`         —— 全部文件可解析且不变量成立
+ *   · `corrupt`    —— 有文件解析失败或记录非法 ⇒ **宿主会拒绝启动**（红）
+ *   · `unreadable` —— 目录/文件读不了（权限等）⇒ 证据不足
+ */
+export function inspectDomain(paths) {
+  const files = listDomainFiles(paths)
+  const problems = []
+  const tasks = []
+  const deliveries = []
+  let unreadable = 0
+  if (!files.length) {
+    return { state: 'absent', paths, files: [], tasks: [], problems: [], deliveries }
+  }
+  for (const f of files) {
+    const got = readText(f.path)
+    if (!got.ok) { unreadable += 1; problems.push({ path: f.path, issue: `读不了（${got.error}）` }); continue }
+    let doc
+    try { doc = JSON.parse(got.text) } catch (e) {
+      problems.push({ path: f.path, issue: `JSON 解析失败（${e.message}）—— 宿主打开该 domain 会**拒绝启动**` })
+      continue
+    }
+    if (f.kind === 'legacy') {
+      // 旧整体文件：`{unit:{name,version},tables:{<table>:{<key>:record}}}`（宿主迁移后**保留原文件**）
+      const name = doc && doc.unit && doc.unit.name
+      const ver = doc && doc.unit && doc.unit.version
+      if (name !== DOMAIN.name) { problems.push({ path: f.path, issue: `旧整体文件的 unit.name=${JSON.stringify(name)}（期望 ${DOMAIN.name}）⇒ 会被宿主忽略，但它占着名字` }); continue }
+      if (ver !== DOMAIN.version) { problems.push({ path: f.path, issue: `旧整体文件的 unit.version=${JSON.stringify(ver)}（期望 ${DOMAIN.version}）⇒ 会被宿主忽略` }); continue }
+      const table = (doc.tables || {})[DOMAIN.table] || {}
+      for (const [key, task] of Object.entries(table)) {
+        const issues = validateTask(task)
+        for (const issue of issues) problems.push({ path: f.path, issue: `${key}: ${issue}` })
+        if (!issues.length) { tasks.push({ id: key, task, from: f.path }); if (task.lastDelivery) deliveries.push({ id: key, ...task.lastDelivery }) }
+      }
+      continue
+    }
+    if (f.kind === 'global') continue
+    // 逐记录文件：`{version, record}`（version 不匹配 ⇒ 宿主**当作不存在**丢弃，不报错）
+    if (!isObj(doc) || typeof doc.version !== 'number' || !isObj(doc.record)) {
+      problems.push({ path: f.path, issue: '不是逐记录形态 `{version, record}`' })
+      continue
+    }
+    if (doc.version !== DOMAIN.version) {
+      problems.push({ path: f.path, issue: `记录 version=${doc.version}（期望 ${DOMAIN.version}）⇒ 宿主会把它**当作不存在**丢弃（静默）` })
+      continue
+    }
+    const issues = validateTask(doc.record)
+    for (const issue of issues) problems.push({ path: f.path, issue: `${f.key}: ${issue}` })
+    if (!issues.length) {
+      tasks.push({ id: f.key, task: doc.record, from: f.path })
+      if (doc.record.lastDelivery) deliveries.push({ id: f.key, ...doc.record.lastDelivery })
+    }
+  }
+  const state = problems.length ? 'corrupt' : (unreadable && !tasks.length ? 'unreadable' : 'ok')
+  return { state, paths, files, tasks, problems, deliveries }
+}
+
+// ══════════════════════════════════════════════════════════════════════════
+// 四、L1 证据面（"活干了没"的那半边）
+// ══════════════════════════════════════════════════════════════════════════
+
+/** 台账里"这条事件属于该流程"的判据：`caseId = <flowId>__<业务键>`（`flow_case.py` 保证前缀）。 */
+export function caseIdPrefixes(flowIds) {
+  return (flowIds || []).filter(Boolean).map((f) => `${f}__`)
+}
+
+/**
+ * 读 L1 证据（**只读**）：
+ *   · 轮次日志：`mtime` / `size`（定时轮次有没有跑，看它有没有动）；
+ *   · 统一台账：尾部窗口里"属于这些流程"的**最新事件时间**；
+ * 返回 `newestMs`（= 两者取大）作为"L1 最近动过"的判据。
+ */
+export function readL1Evidence({ logPath, ledgerPath, flowIds = [], tailBytes = DEFAULT_LEDGER_TAIL_BYTES } = {}) {
+  const ev = { log: null, ledger: null, newestMs: 0, sources: [] }
+  if (logPath) {
+    const st = statOr(logPath)
+    ev.log = st ? { path: logPath, exists: true, mtimeMs: st.mtimeMs, size: st.size } : { path: logPath, exists: false, mtimeMs: 0, size: 0 }
+    if (st) { ev.newestMs = Math.max(ev.newestMs, st.mtimeMs); ev.sources.push(`轮次日志 ${logPath}（mtime）`) }
+  }
+  if (ledgerPath) {
+    const st = statOr(ledgerPath)
+    const rec = { path: ledgerPath, exists: Boolean(st), mtimeMs: st ? st.mtimeMs : 0, newestTsSec: 0, newestEvent: null, matched: 0, lines: 0, truncated: false, error: '' }
+    if (st) {
+      const size = st.size
+      const start = Math.max(0, size - Math.max(1024, tailBytes))
+      rec.truncated = start > 0
+      let text = ''
+      try {
+        const buf = readFileSync(ledgerPath)
+        text = buf.subarray(start).toString('utf8')
+      } catch (e) { rec.error = String((e && (e.code || e.message)) || e) }
+      if (!rec.error) {
+        const lines = text.split('\n')
+        // 截断读取的第一个片段多半是半行 ⇒ 丢掉
+        for (const line of (rec.truncated ? lines.slice(1) : lines)) {
+          const t = line.trim()
+          if (!t) continue
+          rec.lines += 1
+          let e
+          try { e = JSON.parse(t) } catch { continue }
+          const cid = String((e && e.caseId) || '')
+          if (flowIds.length && !caseIdPrefixes(flowIds).some((pre) => cid.startsWith(pre))) continue
+          rec.matched += 1
+          const ts = Number(e && e.ts)
+          if (Number.isFinite(ts) && ts > rec.newestTsSec) { rec.newestTsSec = ts; rec.newestEvent = { ts, event: e.event, caseId: cid } }
+        }
+        if (rec.newestTsSec) {
+          ev.newestMs = Math.max(ev.newestMs, rec.newestTsSec * 1000)
+          ev.sources.push(`台账 ${ledgerPath}（最新事件 ${new Date(rec.newestTsSec * 1000).toISOString()}${rec.truncated ? '，只看尾部窗口' : ''}）`)
+        }
+      }
+    }
+    ev.ledger = rec
+  }
+  return ev
+}
+
+// ══════════════════════════════════════════════════════════════════════════
+// 五、HTTP：RPC 信封与"挂载/没挂载/见不着"三态
+// ══════════════════════════════════════════════════════════════════════════
+
+/** 组一个 `client-request` 信封（字段名取自宿主 `dsh-client-connection` 的 schema）。 */
+export function rpcEnvelope(endpoint, args = {}, rpcId = 'argent-schedule-probe-1') {
+  return { type: 'client-request', rpcId, method: endpoint, payload: { args } }
+}
+
+/**
+ * POST 一个 RPC 端点（**只读调用方负责**；本函数不区分读写，判据在调用点）。
+ * @returns {Promise<{state:'ok'|'rpc-error'|'unmounted'|'unauthorized'|'unreachable'|'bad-response',
+ *                    httpStatus:number, value:any, code:string, message:string, raw:string}>}
+ *   · **`state:'ok'` ⇔ 服务在组合里**（挂载闸的判据）；
+ *     `rpc-error` 同样是"已挂载"（宿主对参数错也回 200 + `gateway/*` 码）⇒ 由调用方按 `httpStatus` 判挂载。
+ */
+export async function postRpc({ base, endpoint, args = {}, cookie, fetchImpl = fetch, timeoutMs = 8000, rpcId } = {}) {
+  const url = `${String(base).replace(/\/+$/, '')}${API_CHANNEL}/${endpoint}`
+  const ac = new AbortController()
+  const timer = setTimeout(() => ac.abort(), timeoutMs)
+  const headers = { 'content-type': 'application/json' }
+  if (cookie && cookie.name) headers.cookie = `${cookie.name}=${cookie.value}`
+  let res
+  try {
+    res = await fetchImpl(url, { method: 'POST', headers, body: JSON.stringify(rpcEnvelope(endpoint, args, rpcId)), signal: ac.signal, redirect: 'manual' })
+  } catch (e) {
+    return { state: 'unreachable', httpStatus: 0, value: null, code: '', message: String((e && (e.message || e.code)) || e), raw: '', url }
+  } finally {
+    clearTimeout(timer)
+  }
+  const httpStatus = Number(res && res.status) || 0
+  let raw = ''
+  try { raw = await res.text() } catch { raw = '' }
+  if (httpStatus === 404) return { state: 'unmounted', httpStatus, value: null, code: 'http/404', message: raw.slice(0, 200) || 'not found', raw, url }
+  if (httpStatus === 401 || httpStatus === 403) return { state: 'unauthorized', httpStatus, value: null, code: `http/${httpStatus}`, message: raw.slice(0, 200), raw, url }
+  if (httpStatus < 200 || httpStatus >= 300) return { state: 'bad-response', httpStatus, value: null, code: `http/${httpStatus}`, message: raw.slice(0, 200), raw, url }
+  let doc
+  try { doc = JSON.parse(raw) } catch { return { state: 'bad-response', httpStatus, value: null, code: 'envelope/not-json', message: raw.slice(0, 200), raw, url } }
+  const result = doc && doc.result
+  if (result && result.ok === true) return { state: 'ok', httpStatus, value: result.value, code: '', message: '', raw, url }
+  if (result && result.ok === false) {
+    const err = result.error || {}
+    return { state: 'rpc-error', httpStatus, value: null, code: String(err.code || 'gateway/unknown'), message: String(err.message || ''), raw, url }
+  }
+  return { state: 'bad-response', httpStatus, value: null, code: 'envelope/unexpected', message: raw.slice(0, 200), raw, url }
+}
+
+// ══════════════════════════════════════════════════════════════════════════
+// 六、任务 ↔ 流程的对应（"哪条任务属于哪条流程"）
+// ══════════════════════════════════════════════════════════════════════════
+
+/** 归一化一个 catalog 条目（宿主 `catalog()` 的返回项）。 */
+export function normalizeEntry(e) {
+  if (!isObj(e)) return null
+  return {
+    id: String(e.id || ''),
+    kind: String(e.kind || ''),
+    title: String(e.title || ''),
+    prompt: String(e.prompt || ''),
+    sessionId: String(e.sessionId || ''),
+    status: String(e.status || ''),
+    scheduledAt: String(e.scheduledAt || ''),
+    everySeconds: Number.isFinite(e.everySeconds) ? e.everySeconds : null,
+    time: e.time === undefined ? null : String(e.time),
+    timeZone: e.timeZone === undefined ? null : String(e.timeZone),
+    expression: e.expression === undefined ? null : String(e.expression),
+    weekdays: Array.isArray(e.weekdays) ? e.weekdays : null,
+    lastDelivery: isObj(e.lastDelivery) ? { ...e.lastDelivery } : null,
+  }
+}
+
+/** 选择器 → 周期（秒）；**推不出就返回 null**（宁可不判，也不猜）。 */
+export function periodSecondsOf(entry) {
+  if (!entry) return null
+  switch (entry.kind) {
+    case 'every': return Number.isFinite(entry.everySeconds) ? entry.everySeconds : null
+    case 'daily': return DAY_SEC
+    case 'weekly': return 7 * DAY_SEC
+    case 'after': return null            // 一次性（延迟触达）
+    case 'at': return null               // 一次性（绝对时点）
+    // ⛔ cron **刻意不推**：宿主有它自己的五字段解析器（含时区/夏令时语义），
+    //    在 L1 再写一份就是"第二份判据"（本仓库为此付过多次代价）。
+    //    要判 cron 的新鲜度 ⇒ 调用方显式给周期（`--period-sec`）。
+    case 'cron': return null
+    default: return null
+  }
+}
+
+/**
+ * 把 catalog 条目对到某条流程。三种判据（**按可靠性排序**）：
+ *   ① `taskTitle` 精确相等（注册表 `trigger.schedule.taskTitle` —— 声明面的唯一真源）；
+ *   ② 任务的 `prompt` 里出现该流程 id（P1-B 的静态指令会写成一条带 `--flow <id>` 的 L1 命令）；
+ *   ③ 会话 id 相等（调用方给了 `--session-id` 时的兜底）。
+ */
+export function matchTask(entries, { flowId, alternatives = [], taskTitle, sessionId } = {}) {
+  const list = (entries || []).map(normalizeEntry).filter(Boolean)
+  const ids = [flowId, ...alternatives].filter(Boolean)
+  if (taskTitle) {
+    const hit = list.find((e) => e.title === taskTitle)
+    if (hit) return { entry: hit, by: 'title' }
+  }
+  const hit2 = list.find((e) => ids.some((i) => e.prompt.includes(i)))
+  if (hit2) return { entry: hit2, by: 'flow-id-in-prompt' }
+  if (sessionId) {
+    const hit3 = list.find((e) => e.sessionId === sessionId)
+    if (hit3) return { entry: hit3, by: 'session-id' }
+  }
+  return { entry: null, by: 'none', candidates: list }
+}
+
+// ══════════════════════════════════════════════════════════════════════════
+// 七、四道闸（每个都返回统一形状：`{gate, state, headline, detail[], next[], evidence}`）
+// ══════════════════════════════════════════════════════════════════════════
+// state：`green`（绿）｜`red`（红，必须有人处置）｜`yellow`（黄，提醒，不改变退出码）｜`unknown`（证据不足）
+
+const GATE_ZH = { green: '✅ 绿', red: '❌ 红', yellow: '⚠️ 黄', unknown: '❓ 证据不足' }
+
+/** ① 挂载闸：404 ⇒ 红（没挂载）；200 ⇒ 绿（含 `gateway/*` 参数错 —— 那也证明服务在）。 */
+export function gateMount(res, { endpoint = MOUNT_ENDPOINT } = {}) {
+  const at = `POST ${API_CHANNEL}/${endpoint}`
+  if (!res) {
+    return {
+      gate: 'mount', state: 'unknown', headline: `${at}：没有探针结果`,
+      detail: ['调用方没有跑探针'], next: [`跑：node scripts/argent-schedule.mjs probe`],
+    }
+  }
+  if (res.state === 'unmounted') {
+    return {
+      gate: 'mount', state: 'red',
+      headline: `${at} → HTTP 404 ⇒ **排程没挂载**`,
+      detail: [
+        '404 = 组合里没有这个端点（宿主升级**删掉那三行**时就是这个形态：0.1.x 由 dsh-web-app 自带且 disabled，0.2.x 改由可选 bundle 提供）',
+        `探针原文：${String(res.message || '').slice(0, 120)}`,
+      ],
+      next: [
+        '0.1.x：在 profile 的 cordis.patch.yml 里按 id 覆盖三行 `disabled: false`（time-context / schedule / ui-schedule）',
+        '0.2.x：把 dsh-experimental-schedule-bundle 加进 profile 的 dsh.profile.bundles',
+        '改完**需重启宿主**才生效；⛔ 本工具不重启、不改 profile（那是 P1-B 的装机步骤）',
+      ],
+      evidence: res,
+    }
+  }
+  if (res.state === 'unauthorized') {
+    return {
+      gate: 'mount', state: 'unknown', headline: `${at} → HTTP ${res.httpStatus}（鉴权没过，**不能**判"没挂载"）`,
+      detail: ['"问不进去" ≠ "服务不在"：两者必须分开报，否则会把人骗去删组合里的三行'],
+      next: ['确认宿主在跑并且唤醒鉴权可用：`node scripts/lib/wake-auth.mjs --log-paths`', '或显式给凭据文件/日志落点（ARGENT_WAKE_TOKEN_FILE / ARGENT_WAKE_LOG_PATHS）'],
+      evidence: res,
+    }
+  }
+  if (res.state === 'unreachable' || res.state === 'bad-response') {
+    return {
+      gate: 'mount', state: 'unknown', headline: `${at} → ${res.state === 'unreachable' ? '连不上宿主' : `响应不是 RPC 信封（HTTP ${res.httpStatus}）`}`,
+      detail: [String(res.message || '').slice(0, 200)], next: ['确认 dsh web 在跑且 --base 指向它（缺省 http://127.0.0.1:3080）'],
+      evidence: res,
+    }
+  }
+  return {
+    gate: 'mount', state: 'green',
+    headline: `${at} → HTTP ${res.httpStatus} ⇒ **排程已挂载**`,
+    detail: [res.state === 'ok' ? `catalog 正常返回（${Array.isArray(res.value) ? res.value.length : '?'} 条任务）` : `服务在组合里（RPC 回了 ${res.code} —— 参数错也是 200，同样证明挂载）`],
+    next: [], evidence: res,
+  }
+}
+
+/**
+ * ② 新鲜度闸：`now - lastDelivery.deliveredAt > 1.5 × 周期` ⇒ 红。
+ * 无回执：任务 `active` 且**创建时间 + 1.5 周期**已过仍没投递过 ⇒ 红；太新 ⇒ 证据不足（还没到判的时候）。
+ */
+export function gateFreshness({ entry, nowMs, periodSec, factor = FRESHNESS_FACTOR, label = '' } = {}) {
+  const at = label ? `${label}：` : ''
+  if (!entry) {
+    return { gate: 'freshness', state: 'unknown', headline: `${at}没有对应的宿主任务 ⇒ 无法判新鲜度`, detail: [], next: ['先建任务（P1-B）或确认 taskTitle 与注册表一致'] }
+  }
+  const period = Number.isFinite(periodSec) ? periodSec : periodSecondsOf(entry)
+  if (!Number.isFinite(period) || period <= 0) {
+    return {
+      gate: 'freshness', state: 'unknown',
+      headline: `${at}周期推不出来（kind=${entry.kind}）⇒ 证据不足`,
+      detail: [`任务 ${entry.id}（${entry.kind}）没有可直接使用的周期；cron 的周期由宿主解析（含时区/夏令时），L1 不另写一份`],
+      next: ['显式给周期重跑：`--period-sec <秒>`（daily=86400、weekly=604800）'],
+      evidence: { entry, periodSec: null },
+    }
+  }
+  const limitMs = period * factor * 1000
+  const ld = entry.lastDelivery
+  // ⚠️ **先判 status**：`inactive` 的重复型任务永远不会再触发（宿主只在"算不出下一次发生"时才置它）
+  // ⇒ 哪怕它有很新的回执，也已经是死的（回执是它生前留下的）。
+  if (entry.status !== 'active') {
+    return {
+      gate: 'freshness', state: 'red',
+      headline: `${at}任务 status=${entry.status}（**不是 active**）⇒ 它永远不会再触发`,
+      detail: [`任务 ${entry.id}`, `上次投递 ${ld ? ld.deliveredAt : '（从未）'}（那之后的回执不再推进）`],
+      next: ['任务已"死"（重复型任务唯一的 inactive 来源是算不出下一次发生）⇒ 需要重建；见 `pause/apply` 与审计'],
+      evidence: { entry, periodSec: period },
+    }
+  }
+  if (!ld || !Number.isFinite(Date.parse(ld.deliveredAt))) {
+    const created = Date.parse(entry.scheduledAt)
+    const ageMs = Number.isFinite(created) ? (nowMs - created) : null
+    if (ageMs !== null && ageMs > limitMs) {
+      return {
+        gate: 'freshness', state: 'red',
+        headline: `${at}建了 ${Math.round(ageMs / 1000)}s（> ${factor}×周期 ${Math.round(limitMs / 1000)}s）却**一次都没投递过**`,
+        detail: [`任务 ${entry.id}（kind=${entry.kind}，status=${entry.status}，scheduledAt=${entry.scheduledAt}）`, '宿主投递失败**只写它自己的日志、不重试**，也不会写我们的台账 ⇒ 不会有人来告诉你'],
+        next: ['看宿主进程日志里有没有投递准入失败', '`node scripts/argent-schedule.mjs status` 看任务是否 active、下一跳是否在未来'],
+        evidence: { entry, periodSec: period, ageMs },
+      }
+    }
+    return {
+      gate: 'freshness', state: 'unknown',
+      headline: `${at}还没有第一次投递（任务太新：建了 ${ageMs === null ? '?' : Math.round(ageMs / 1000)}s ≤ ${factor}×周期）`,
+      detail: ['还没到能判"它是不是死了"的时候'], next: ['过一个周期再跑一次'],
+      evidence: { entry, periodSec: period, ageMs },
+    }
+  }
+  const deliveredMs = Date.parse(ld.deliveredAt)
+  const ageMs = nowMs - deliveredMs
+  if (ageMs > limitMs) {
+    return {
+      gate: 'freshness', state: 'red',
+      headline: `${at}距上次投递 ${Math.round(ageMs / 1000)}s > ${factor}×周期（${Math.round(limitMs / 1000)}s）⇒ 定时已经不正常`,
+      detail: [`任务 ${entry.id}：lastDelivery.deliveredAt=${ld.deliveredAt}`],
+      next: ['宿主在不在跑？（`launchctl list | grep dsh-web` / Windows 看计划任务 WhyshuDshWeb）', '任务是不是被删/被停？`node scripts/argent-schedule.mjs status`'],
+      evidence: { entry, periodSec: period, ageMs, limitMs },
+    }
+  }
+  return {
+    gate: 'freshness', state: 'green',
+    headline: `${at}上次投递在 ${Math.round(ageMs / 1000)}s 前（≤ ${factor}×周期 ${Math.round(limitMs / 1000)}s）`,
+    detail: [`任务 ${entry.id}（kind=${entry.kind}，status=${entry.status}）`], next: [],
+    evidence: { entry, periodSec: period, ageMs },
+  }
+}
+
+/**
+ * ③ 执行闸（**本批的灵魂**）：回执推进 **∧** L1 无新证据 ⇒ 红。
+ * 为什么不能只看回执：宿主 README 原话 —— 回执"确认收件箱投递，**不表示模型执行**"。
+ */
+export function gateExecution({ entry, evidence, nowMs, graceSec = DEFAULT_GRACE_SEC, label = '' } = {}) {
+  const at = label ? `${label}：` : ''
+  const ld = entry && entry.lastDelivery
+  if (!entry || !ld || !Number.isFinite(Date.parse(ld.deliveredAt))) {
+    return { gate: 'execution', state: 'unknown', headline: `${at}没有投递回执 ⇒ 无从判"投递之后有没有人干活"`, detail: [], next: ['先有回执（见新鲜度闸）'] }
+  }
+  if (!evidence || !evidence.newestMs) {
+    return {
+      gate: 'execution', state: 'unknown',
+      headline: `${at}拿不到 L1 证据（轮次日志/台账都读不到）⇒ **不能**下"没人干活"的结论`,
+      detail: ['证据不足与"没干活"是两件事：混成一句就会把人骗去查一个没坏的东西'],
+      next: ['确认 L1 证据面存在：轮次日志 `<数据目录>/<trigger.log>`、台账 `<数据目录>/flow-ledger.jsonl`'],
+      evidence: { entry, evidence },
+    }
+  }
+  const deliveredMs = Date.parse(ld.deliveredAt)
+  const l1Ms = evidence.newestMs
+  const graceMs = Math.max(0, graceSec) * 1000
+  // 证据强度：台账里有**属于该流程**的新事件 = 强（认领/派发/失败都算"活干了"）；
+  // 只有轮次日志 mtime 动了 = 弱（"本轮无票可认领"是合法绿，但"收到指令却没跑 L1"也会让它动）。
+  const ledgerNew = Boolean(evidence.ledger && evidence.ledger.newestTsSec && evidence.ledger.newestTsSec * 1000 >= deliveredMs - graceMs)
+  const strength = ledgerNew ? 'strong' : 'weak'
+  if (l1Ms >= deliveredMs - graceMs) {
+    return {
+      gate: 'execution', state: 'green',
+      headline: `${at}回执之后 L1 有新证据（相差 ${Math.round((l1Ms - deliveredMs) / 1000)}s，宽限 ${graceSec}s；${strength === 'strong' ? '强证据=台账' : '**弱证据=只有轮次日志 mtime**'}）`,
+      detail: [
+        `投递 ${ld.deliveredAt}`,
+        `L1 最新：${new Date(l1Ms).toISOString()}（${(evidence.sources || []).join('；') || '—'}）`,
+        strength === 'strong'
+          ? '台账里有该流程的新事件（caseId 前缀 <flow>__）⇒ "投递之后确实有人干活"'
+          : '⚠️ 弱证据：只有轮次日志被追加过。⛔ 别把"收到指令但没跑 L1"这类结论写进这个日志 —— 那会让本闸**假绿**',
+      ],
+      next: [], evidence: { entry, evidence, graceSec, strength },
+    }
+  }
+  return {
+    gate: 'execution', state: 'red',
+    headline: `${at}回执推进了，但 L1 **没有任何新证据**（差 ${Math.round((deliveredMs - l1Ms) / 1000)}s > 宽限 ${graceSec}s）`,
+    detail: [
+      `投递：${ld.deliveredAt}（messageId=${ld.messageId}）`,
+      `L1 最新：${new Date(l1Ms).toISOString()}（${(evidence.sources || []).join('；') || '—'}）`,
+      '这正是排程迁移的**头号语义退化**：宿主只保证"消息进了会话收件箱"，排程 prompt 又是**静态**的'
+        + '（创建时固定）⇒ 认领只能靠角色自己去调 L1 ⇒ 模型不照做时，回执照样推进',
+      `判据：投递时刻（减 ${graceSec}s 宽限）之后，轮次日志 mtime 或台账必须出现**属于该流程**的新事件（caseId 前缀 <flow>__）`,
+    ],
+    next: [
+      `看那一轮到底发生了什么：tail -50 <数据目录>/<trigger.log>`,
+      `看台账有没有该流程的新事件：python3 scripts/flow_ledger.py --status --flow <id>`,
+      '确认静态 prompt 里那条 L1 命令**存在且可执行**（P1-A 明确没有 `--no-wake` ⇒ 现在还不许建任务）',
+    ],
+    evidence: { entry, evidence, graceSec, strength: 'none', deliveredMs, l1Ms },
+  }
+}
+
+/**
+ * ④ 持久化闸：域文件可解析 ∧ 关键不变量成立（坏 ⇒ **宿主拒绝启动**，比"定时不跑"严重）。
+ * @param {object} inspection `inspectDomain()` 的结果
+ * @param {{backupRoots?:string[], nowMs?:number}} [opts] 备份覆盖面检查的候选根
+ */
+export function gatePersistence(inspection, { backupRoots = [] } = {}) {
+  if (!inspection) return { gate: 'persistence', state: 'unknown', headline: '没有域文件检查结果', detail: [], next: [] }
+  const files = inspection.files || []
+  if (inspection.state === 'corrupt') {
+    return {
+      gate: 'persistence', state: 'red',
+      headline: `排程域有 ${inspection.problems.length} 处非法 ⇒ **宿主会拒绝启动整个 domain**（连对话一起）`,
+      detail: inspection.problems.map((p) => `${p.path}：${p.issue}`),
+      next: [
+        `先备份现场：cp -a "${inspection.paths.unitDir}" "${inspection.paths.legacyFile}" <备份目录>/ 2>/dev/null`,
+        '再按上面点名的文件修（逐记录文件可直接删：宿主把"读不出/版本不符"的记录**当作不存在**丢弃）',
+        '⛔ 修之前不要重启宿主（正在跑的进程还用着内存里的旧状态）',
+      ],
+      evidence: { files: files.map((f) => f.path), problems: inspection.problems },
+    }
+  }
+  if (inspection.state === 'unreadable') {
+    return {
+      gate: 'persistence', state: 'unknown',
+      headline: '排程域文件**读不了**（权限/IO）⇒ 不能判好坏',
+      detail: inspection.problems.map((p) => `${p.path}：${p.issue}`), next: ['用能读该文件的身份重跑；或 `ls -la` 看权限'],
+      evidence: { files: files.map((f) => f.path) },
+    }
+  }
+  const b = backupCoverage({ files: files.map((f) => f.path), roots: backupRoots })
+  const exists = inspection.state === 'ok'
+  const detail = exists
+    ? [`逐记录 ${files.filter((f) => f.kind === 'record').length} 个、旧整体文件 ${files.filter((f) => f.kind === 'legacy').length} 个，全部可解析且不变量成立（"宿主起得来 ⇒ 这个文件是好的"的反向判据也由此成立）`]
+    : ['域文件尚未落盘（排程从未启用过）—— **不是故障**；但一旦建了任务，这个文件坏了会拖垮整个宿主']
+  const next = []
+  if (b.state !== 'covered') {
+    detail.push(b.detail)
+    next.push(...b.next)
+  }
+  return {
+    gate: 'persistence', state: b.state === 'covered' ? 'green' : (exists ? 'yellow' : 'green'),
+    headline: exists ? '排程域文件可解析、关键不变量成立' : '排程域尚未落盘（还未启用）',
+    detail, next,
+    evidence: { state: inspection.state, files: files.map((f) => f.path), backup: b },
+  }
+}
+
+/**
+ * ⑤ 单一调度者闸（0.6.0 W8）：同一条流程被**两条线同时**调度 ⇒ **红**。
+ *
+ * ⭐ 判据**不在这里**：唯一实现 = `scripts/lib/schedule-mechanism.mjs#resolveScheduleMechanism()`
+ *   （声明面 = 注册表 `schedule.mechanism`；证据 = 原生包 / 已装计划任务文件）。
+ *   本函数只把它的结论渲染成闸的形状（与其它四道闸同一 API）。
+ *
+ * 三态：
+ *   · `conflict`（两条线同时在）⇒ **红**，并**逐字给出怎么关掉一条**（⛔ 不替用户选、⛔ 不静默择一）；
+ *   · `native` / `activation-shim` / `none` ⇒ 绿（附现状说明）；
+ *   · `unknown`（探不到 ⇒ 缺证据）⇒ **黄**（不是红：`unknown` 只说明判不了，不说明出事了；
+ *     但它**必须可见** —— 否则"以为在跑、其实没人调度"就是静默失败）。
+ *
+ * @param {{state:string, declared?:string, reason?:string, next?:string[],
+ *          native?:object|null, shim?:object|null, conflict?:object|null}} res
+ *   `= detectScheduleMechanism()` / `resolveScheduleMechanism()` 的返回值
+ */
+export function gateSchedulerConflict(res, { label = '' } = {}) {
+  const at = label ? `${label}：` : ''
+  if (!res || !res.state) {
+    return {
+      gate: 'scheduler-conflict', state: 'unknown',
+      headline: `${at}没有定时机制判据结果 ⇒ 无法判"是不是两个调度者"`,
+      detail: ['调用方没有跑 scripts/lib/schedule-mechanism.mjs 的判据'],
+      next: ['跑：node scripts/argent-schedule.mjs mechanism'],
+    }
+  }
+  const base = {
+    gate: 'scheduler-conflict',
+    declared: String(res.declared || ''),
+    mechanism: String(res.state),
+    nativeReason: res.native ? String(res.native.reason || '') : '',
+    shimReason: res.shim ? String(res.shim.reason || '') : '',
+    flows: (res.conflict && Array.isArray(res.conflict.flows)) ? res.conflict.flows : [],
+  }
+  if (res.state === 'conflict') {
+    const c = res.conflict || {}
+    return {
+      ...base, state: 'red',
+      headline: `${at}❌ **两个调度者同时在**（原生任务 × 激活垫片）—— 单一调度者纪律被破坏`,
+      detail: [
+        String(c.detail || res.reason || ''),
+        `原生：${base.nativeReason || '（在场）'}`,
+        `垫片：${base.shimReason || '（在场）'}`,
+      ],
+      next: [
+        ...(Array.isArray(c.next) ? c.next : []),
+        ...(Array.isArray(res.next) ? res.next : []),
+      ],
+      closeOne: String(c.closeOne || ''),
+      evidence: { native: res.native || null, shim: res.shim || null, conflict: c },
+    }
+  }
+  if (res.state === 'unknown') {
+    return {
+      ...base, state: 'yellow',
+      headline: `${at}⚠️ 判不了"谁是调度者"（证据不足）——⛔ 别顺手装一份 cron（那会造出第二个调度者）`,
+      detail: [String(res.reason || '')],
+      next: Array.isArray(res.next) ? res.next : [],
+      evidence: { native: res.native || null, shim: res.shim || null },
+    }
+  }
+  const zh = { native: '原生（宿主排程）', 'activation-shim': '激活垫片（flow-timers.sh）', none: '无（这台机器不该有定时器）' }
+  return {
+    ...base, state: 'green',
+    headline: `${at}✅ 单一调度者：${zh[res.state] || res.state}（声明 ${res.declared}）`,
+    detail: [String(res.reason || '')],
+    next: [],
+    evidence: { native: res.native || null, shim: res.shim || null },
+  }
+}
+
+/**
+ * 备份覆盖面（**报告式**判据，不是恒红陷阱）：
+ * 判据 = 给定的备份根下**能不能找到**这份域文件的副本（按文件名/子路径匹配）。
+ * ⛔ 不在这里跑任何备份命令（本模块只读）；找不到就给出一条**可复制**的备份命令。
+ */
+export function backupCoverage({ files = [], roots = [] } = {}) {
+  const wanted = files.filter(Boolean)
+  if (!wanted.length) {
+    return { state: 'none-yet', detail: '还没有域文件 ⇒ 暂无可备份之物', next: [], hits: [] }
+  }
+  const hits = []
+  for (const r of roots.filter(Boolean)) {
+    if (!existsSync(r)) continue
+    for (const w of wanted) {
+      const name = w.split('/').pop()
+      const rel = w.split('/').slice(-3).join('/')
+      if (findUnder(r, [name, rel], 3)) hits.push({ root: r, file: w })
+    }
+  }
+  if (hits.length) return { state: 'covered', detail: `备份覆盖面：在 ${[...new Set(hits.map((h) => h.root))].join('、')} 下找到域文件副本`, next: [], hits }
+  return {
+    state: 'uncovered',
+    detail: `备份覆盖面：**没有**任何备份包含排程域（候选根：${roots.filter(Boolean).join('、') || '（未给）'}）`
+      + ' —— 仓库现有的备份面（`dsh-backup-scope.sh` 只备 node scope）**不含**宿主存储目录',
+    next: [
+      '把宿主存储目录纳入备份面（一条可复制的命令）：',
+      `  mkdir -p "$HOME/.dsh/argent/backup/schedule-$(date +%Y%m%d-%H%M%S)" && cp -a "$HOME/.dsh/storages/schedule" "$HOME/.dsh/storages/schedule.json" "$HOME/.dsh/argent/backup/schedule-$(date +%Y%m%d-%H%M%S)/" 2>/dev/null; ls -la "$HOME/.dsh/argent/backup" | tail -3`,
+      '理由：这个文件坏了 = **宿主拒绝启动**（连对话一起），比"定时不跑"严重',
+    ],
+    hits: [],
+  }
+}
+
+/** 在 `dir` 下浅层找一个名字（深度受限；找不到返回 false）。 */
+function findUnder(dir, needles, depth) {
+  if (depth < 0) return false
+  let entries = []
+  try { entries = readdirSync(dir, { withFileTypes: true }) } catch { return false }
+  for (const e of entries) {
+    if (needles.includes(e.name)) return true
+    if (e.isDirectory() && !e.name.startsWith('.')) {
+      if (findUnder(join(dir, e.name), needles, depth - 1)) return true
+    }
+  }
+  return false
+}
+
+// ══════════════════════════════════════════════════════════════════════════
+// 八、汇总（三态退出码：0 全绿 / 1 有红 / 2 证据不足）
+// ══════════════════════════════════════════════════════════════════════════
+
+/** 汇总多道闸 → `{exitCode, red, yellow, unknown, green, lines[]}`。 */
+export function summarize(gates) {
+  const list = (gates || []).filter(Boolean)
+  const by = (s) => list.filter((g) => g.state === s)
+  const red = by('red'); const yellow = by('yellow'); const unknown = by('unknown'); const green = by('green')
+  const exitCode = red.length ? 1 : (unknown.length ? 2 : 0)
+  const lines = list.map((g) => `${GATE_ZH[g.state] || g.state} [${g.gate}] ${g.headline}`)
+  return { gates: list, exitCode, red, yellow, unknown, green, lines }
+}
+
+/** 人读的一行结论（CLI 与门禁共用同一句，避免两处口径）。 */
+export function verdictLine(sum) {
+  if (sum.exitCode === 1) return `❌ 排程面判红：${sum.red.length} 道闸红了（${sum.red.map((g) => g.gate).join('、')}）`
+  if (sum.exitCode === 2) return `❓ 排程面证据不足：${sum.unknown.length} 道闸无法判定（${sum.unknown.map((g) => g.gate).join('、')}）`
+  return sum.yellow.length
+    ? `✅ 排程面无红（但有 ${sum.yellow.length} 项黄色提醒：${sum.yellow.map((g) => g.gate).join('、')}）`
+    : '✅ 排程面全绿'
+}
+
+/** 结论 + 每道闸的下一步（人可读；CLI 只负责排版）。 */
+export function formatGates(sum, { prefix = '   ' } = {}) {
+  const out = []
+  for (const g of sum.gates) {
+    out.push(`${prefix}${GATE_ZH[g.state] || g.state} [${g.gate}] ${g.headline}`)
+    for (const d of g.detail || []) out.push(`${prefix}     · ${d}`)
+    for (const n of g.next || []) out.push(`${prefix}     ↳ 下一步：${n}`)
+  }
+  return out.join('\n')
+}
+
+/** 绝对路径归一（CLI 传进来的相对路径按 cwd 解析）。 */
+export const absOf = (p) => (p ? (isAbsolute(p) ? p : join(process.cwd(), p)) : p)