@whyshu/argent-engine 0.0.0-stage → 0.6.0

package/engine/scripts/argent-schedule.mjs

@@ -0,0 +1,620 @@
+#!/usr/bin/env node
+/**
+ * argent-schedule —— **宿主原生排程面**的 CLI（P1-A，2026-10-12）
+ *
+ * ══════════════════════════════════════════════════════════════════════════
+ * 它是什么 / 它不是什么
+ * ══════════════════════════════════════════════════════════════════════════
+ * 是：把「排程还在不在跑」变成**可复制的命令**（`probe`/`status`/`check`），
+ *     并把 `PAUSE_*` 文件与宿主任务状态之间那座桥（`pause`/`apply`）做成**默认 dry-run** 的收敛器。
+ * 不是：装机器（⛔ 不改 profile、不装包）、不是宿主管理器（⛔ 不重启宿主、⛔ 不 bootstrap 任何计划任务）、
+ *     不是第二份判据 —— 四道闸的**判据全在** `scripts/lib/schedule-probe.mjs`，本文件只做
+ *     「取数（注册表 / 凭据 / HTTP）→ 调用判据 → 排版 / 落审计」。
+ *
+ * ══════════════════════════════════════════════════════════════════════════
+ * 子命令
+ * ══════════════════════════════════════════════════════════════════════════
+ * ```bash
+ * node scripts/argent-schedule.mjs probe  [--base URL] [--json]        # ① 挂载闸（只读；404 ⇒ 红）
+ * node scripts/argent-schedule.mjs status [--flow <id>] [--json]       # 声明 vs 任务（只读）
+ * node scripts/argent-schedule.mjs check  [--flow <id>] [--json]       # 五道闸汇总（退出码 0/1/2）
+ * node scripts/argent-schedule.mjs mechanism [--json]                   # 定时机制判据（native/shim/none/conflict/unknown）
+ * node scripts/argent-schedule.mjs pause  [--flow <id>] [--apply]      # PAUSE 文件 ⇒ 停（默认 dry-run）
+ * node scripts/argent-schedule.mjs apply  [--flow <id>] [--apply]      # 双向收敛（默认 dry-run）
+ * ```
+ * 公共开关：`--base <url>`（缺省 `http://127.0.0.1:3080`）、`--flow <id>`、`--dsh-home <dir>`、
+ * `--data-dir <dir>`、`--root <dir>`（仓库根；注册表加载器用）、`--registry-json <file>`（离线夹具）、
+ * `--log-path <file>`、`--ledger-path <file>`、`--now <ISO>`、`--period-sec <n>`、`--grace-sec <n>`、
+ * `--json`、`--apply`（pause/apply 才认）、`--allow-real-home`。
+ *
+ * 退出码（**三态**，与判据同源）：`0` 全绿/已收敛 ｜ `1` **有红**（必须有人处置）｜
+ * `2` **证据不足或需要会话内动作**（例：宿主连不上；`create` 不是远端端点 ⇒ 只能由会话里的工具建任务）。
+ * ⛔ 不用 `3`：按 D4 裁定 `3` 只表示"许可宽限放行"。
+ *
+ * ══════════════════════════════════════════════════════════════════════════
+ * `pause` / `apply` 的两条**如实声明**（都别当成实现细节）
+ * ══════════════════════════════════════════════════════════════════════════
+ * 1. **收敛窗口**：`PAUSE_*` 文件与任务状态之间**不是原子的**。文件刚落地、`apply` 还没跑的那段窗口里，
+ *    定时**可能照跑一轮**（零模型成本做不到，除非窗口内正好被宿主投递）。⇒ 运维改开关后**要主动跑一次收敛**，
+ *    并把这一条写进 SOP（上游设计 §5.3 同口径）。
+ * 2. **`inactive` 置不了**：宿主**没有**任何把任务置为 `inactive` 的远端端点（见 `schedule-probe.mjs` 的
+ *    `STATUS_SETTER_AVAILABLE` 注释）⇒ 「文件在 ⇒ `inactive`」这条声明**无法逐字实现**。
+ *    本 CLI 用**唯一可用的停法**：`schedule/delete`（删行 ⇒ 绝不再触发；代价：投递历史随行消失），
+ *    并把**整条被删记录**写进审计（`<数据目录>/schedule-audit.jsonl`，0600）——**"关停"这个动作因此不会消失**。
+ *    反向（文件不在 ⇒ 应有任务）**无远端端点可做**（`create` 只在会话内由工具调用）⇒ 本 CLI 记
+ *    `create-required` + 打印该会话应当调用的工具参数，exit 2。
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { hostname, userInfo } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import {
+  absOf, ENDPOINTS, MOUNT_ENDPOINT, STATUS_SETTER_AVAILABLE,
+  domainPaths, formatGates, gateExecution, gateFreshness, gateMount, gatePersistence,
+  gateSchedulerConflict,
+  inspectDomain, matchTask, normalizeEntry, periodSecondsOf, postRpc, readL1Evidence,
+  storageRoot, summarize, verdictLine,
+} from './lib/schedule-probe.mjs'
+import { detectScheduleMechanism, mechanismVerdictLine } from './lib/schedule-mechanism.mjs'
+// 0.6.0 F1 修复批（2026-10-14）：native 探针的 scope 候选必须**npx 感知**
+// （`npx @deepseek-ai/dsh web` 的宿主树在 `~/.npm/_npx/<hash>/node_modules/@deepseek-ai`）。
+// npx 感知的候选链**唯一实现**在 L2 `scripts/lib/dsh-scope.mjs#autoScopeCandidates()`；
+// L1 判据（`schedule-mechanism.mjs`）⛔ 不 import 宿主档 ⇒ 由本文件**注入**（`scopeDirsProbe`）。
+import { autoScopeCandidates, resolveDshScope, scopeSourceOf } from './lib/dsh-scope.mjs'
+import { npxCacheDirs } from './lib/dsh-host-resolve.mjs'
+import { resolveDataDir } from './lib/argent-datadir.mjs'
+import { acquireWakeAuth, authFailureText, authSources } from './lib/wake-auth.mjs'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+export const REPO = resolve(HERE, '..')
+const DEFAULT_BASE = 'http://127.0.0.1:3080'
+const AUDIT_NAME = 'schedule-audit.jsonl'
+
+// ── 参数 ────────────────────────────────────────────────────────────────────
+const argv = process.argv.slice(2)
+const CMD = ['probe', 'status', 'check', 'mechanism', 'pause', 'apply'].includes(argv[0]) ? argv[0] : ''
+const has = (f) => argv.includes(f)
+const val = (f, dflt = '') => { const i = argv.indexOf(f); return i > -1 ? (argv[i + 1] ?? dflt) : dflt }
+const USAGE = `用法：node scripts/argent-schedule.mjs <probe|status|check|mechanism|pause|apply> [选项]
+
+  probe     ① 挂载闸：POST /api/${MOUNT_ENDPOINT}（404 ⇒ 没挂载）
+  status    声明 vs 宿主任务（只读）
+  check     五道闸汇总（挂载/新鲜度/执行/持久化/**单一调度者**）⇒ 退出码 0 全绿 / 1 有红 / 2 证据不足
+  mechanism 定时机制判据（native / activation-shim / none / conflict / unknown）—— **唯一实现**在
+            scripts/lib/schedule-mechanism.mjs（声明面 = 注册表 \`schedule.mechanism\`）；本子命令只排版
+  pause     PAUSE_* 文件 ⇒ 停任务（默认 dry-run；--apply 才写）
+  apply     双向收敛（默认 dry-run；--apply 才写）
+
+选项：
+  --base <url>           宿主地址（缺省 ${DEFAULT_BASE}）
+  --flow <id>            只看/只收敛一条流程（缺省：全部声明了 trigger.schedule 的流程）
+  --dsh-home <dir>       宿主 home（缺省 $DSH_HOME 或 ~/.dsh）—— 决定排程域文件的落点
+  --data-dir <dir>       Argent 数据目录（缺省走内核三级链）—— 审计与流程日志的落点
+  --root <dir>           仓库根（注册表加载器用；缺省本仓库）
+  --registry-json <file> 离线夹具：直接读一份**已合并**的注册表 JSON（⛔ 不做合并，只读文件）
+  --log-path <file>      L1 轮次日志（缺省按注册表 trigger.log 推）
+  --ledger-path <file>   L1 台账（缺省 <数据目录>/flow-ledger.jsonl）
+  --now <ISO>            把"现在"钉住（夹具/复算用）
+  --period-sec <n>       覆盖周期（cron 等推不出周期的选择器用）
+  --grace-sec <n>        执行闸宽限秒（缺省 180）
+  --json                 机器可读
+  --launch-agents-dir <dir>  激活垫片计划任务目录（缺省 ~/Library/LaunchAgents；夹具用）
+  --scope-dir <dir>      宿主作用域（可重复；缺省由 --dsh-home/--profile 推）—— 原生排程探测用
+  --apply                pause/apply 真的写（默认 dry-run）
+  --allow-real-home      --apply 时允许落在**真实**数据目录（缺省拒绝，防误写生产）
+  -h, --help             本帮助
+`
+if (has('-h') || has('--help') || !CMD) {
+  process.stdout.write(USAGE)
+  process.exit(CMD ? 0 : 2)
+}
+const AS_JSON = has('--json')
+const APPLY = has('--apply')
+const ALLOW_REAL = has('--allow-real-home')
+const BASE = val('--base', DEFAULT_BASE).replace(/\/+$/, '')
+const FLOW_ARG = val('--flow')
+const NOW_MS = val('--now') ? Date.parse(val('--now')) : Date.now()
+const PERIOD_ARG = val('--period-sec') ? Number(val('--period-sec')) : null
+const GRACE_SEC = val('--grace-sec') ? Number(val('--grace-sec')) : undefined
+const DSH_HOME = val('--dsh-home') || process.env.DSH_HOME || ''
+const LAUNCH_AGENTS_DIR = val('--launch-agents-dir')
+const PROFILE = val('--profile') || process.env.DSH_PROFILE || 'web'
+const SCOPE_DIRS = argv.reduce((acc, a, i) => (a === '--scope-dir' && argv[i + 1] ? [...acc, argv[i + 1]] : acc), [])
+const DATA_DIR = val('--data-dir') || resolveDataDir({ env: process.env }).dir
+const IS_REAL_DATA_DIR = !val('--data-dir') && !process.env.ARGENT_DATA_DIR && DATA_DIR === resolveDataDir({ env: {} }).dir
+
+const out = (obj) => { process.stdout.write(`${JSON.stringify(obj, null, 2)}\n`) }
+const say = (s) => { if (!AS_JSON) process.stdout.write(`${s}\n`) }
+
+// ── 注册表声明面（**只读**；合并的唯一真源仍是 flow_registry.py）─────────────────
+/**
+ * 读合并后的注册表：`--registry-json` 给文件就直接读（离线夹具/半坏机器），
+ * 否则走 `scripts/lib/registry.mjs` 的加载器（= `flow_registry.py --json`，**唯一合并实现**）。
+ */
+async function readRegistry() {
+  const file = val('--registry-json')
+  if (file) {
+    try { return { doc: JSON.parse(readFileSync(absOf(file), 'utf8')), how: `--registry-json ${file}` } }
+    catch (e) { return { doc: null, how: `--registry-json ${file}`, error: String(e.message || e) } }
+  }
+  try {
+    const { loadRegistryDoc } = await import('./lib/registry.mjs')
+    return { doc: loadRegistryDoc({ root: val('--root') || REPO }), how: `flow_registry.py（root=${val('--root') || REPO}）` }
+  } catch (e) {
+    return { doc: null, how: 'flow_registry.py', error: String((e && (e.stderr || e.message)) || e) }
+  }
+}
+
+/** 把注册表里**声明了 `trigger.schedule`** 的流程摊平（含本地 id：台账 caseId 用短名前缀）。 */
+export function declaredSchedules(doc) {
+  const out = []
+  if (!doc) return out
+  const aliases = doc.aliases || {}
+  const back = {}
+  for (const [short, canon] of Object.entries(aliases)) back[canon] = short
+  for (const [flowId, spec] of Object.entries(doc.flows || {})) {
+    const t = (spec && spec.trigger) || {}
+    const s = t.schedule
+    if (!s || typeof s !== 'object') continue
+    const localId = back[flowId] || String(flowId).split('.').pop()
+    out.push({
+      flowId,
+      localId,
+      title: String(spec.title || flowId),
+      schedule: s,
+      enabled: s.enabled === true,
+      taskTitle: String(s.taskTitle || ''),
+      kind: String(s.kind || ''),
+      timeZone: s.timeZone ? String(s.timeZone) : null,
+      promptFile: String(s.promptFile || ''),
+      onPause: String(s.onPause || ''),
+      pauseSwitch: String(t.pauseSwitch || ''),
+      pauseSwitchLegacy: String(t.pauseSwitchLegacy || ''),
+      logRel: String(t.log || ''),
+      intervalSec: Number.isFinite(t.intervalSec) ? t.intervalSec : null,
+    })
+  }
+  return out
+}
+
+/** 选中的流程（`--flow` 给定时按 id/别名/本地名解析）。 */
+function pickFlows(all) {
+  if (!FLOW_ARG) return all.filter((f) => f.enabled)
+  const want = FLOW_ARG
+  const hit = all.filter((f) => f.flowId === want || f.localId === want)
+  return hit
+}
+
+/** 暂停开关的**两个**候选路径（规范名 + 历史兼容名；与 `flow_config` 的 paths 同口径）。 */
+function pauseFiles(flow) {
+  const mk = (rel) => (rel ? join(DATA_DIR, rel) : '')
+  return [mk(flow.pauseSwitch), mk(flow.pauseSwitchLegacy)].filter(Boolean)
+}
+const pausePresent = (flow) => pauseFiles(flow).find((p) => existsSync(p)) || ''
+
+function l1Paths(flow) {
+  const logPath = val('--log-path') || (flow && flow.logRel ? join(DATA_DIR, flow.logRel) : '')
+  const ledgerPath = val('--ledger-path') || join(DATA_DIR, 'flow-ledger.jsonl')
+  return { logPath, ledgerPath }
+}
+
+// ── HTTP 取数（带鉴权；**只读**）────────────────────────────────────────────
+/** 用仓库既有的唤醒鉴权链拿 cookie（**同一份实现**，不新造第二套）。 */
+async function getCookie() {
+  const sources = authSources({ base: BASE, env: process.env, dshHome: DSH_HOME || undefined })
+  const got = await acquireWakeAuth({ sources, base: BASE })
+  return got
+}
+
+async function readCatalog() {
+  const auth = await getCookie()
+  if (!auth.ok) {
+    return { mount: { state: 'unauthorized', httpStatus: 0, message: auth.unreachable || '鉴权链全部失败', url: `${BASE}/api/${MOUNT_ENDPOINT}` }, auth }
+  }
+  const res = await postRpc({ base: BASE, endpoint: ENDPOINTS.catalog, args: {}, cookie: auth.cookie })
+  return { mount: res, catalog: Array.isArray(res.value) ? res.value.map(normalizeEntry).filter(Boolean) : null, auth }
+}
+
+/** 拿不到 catalog 时退化为"只有挂载结论"（`entries: null` = 读不到，**不是**空）。 */
+async function mountOnly() {
+  const auth = await getCookie()
+  if (!auth.ok) return { mount: { state: 'unauthorized', httpStatus: 0, message: auth.unreachable || '鉴权链全部失败' }, auth }
+  const res = await postRpc({ base: BASE, endpoint: MOUNT_ENDPOINT, args: {}, cookie: auth.cookie })
+  return { mount: res, auth }
+}
+
+// ── 审计（"关停"这个动作不能从文件系统上消失）────────────────────────────────
+const auditPath = () => join(DATA_DIR, AUDIT_NAME)
+const AUDIT_HEADER = { _doc: '排程变更审计（P1-A）：谁在什么时候把定时停了/试图停。JSONL 追加 + 0600；与 flow-ledger.jsonl 同风格。' }
+
+/** 追加一条审计（0600）。⛔ 只在**有动作**时写；dry-run 也写（如实记 mode）。 */
+export function writeAudit(rec) {
+  const p = auditPath()
+  try { mkdirSync(dirname(p), { recursive: true }) } catch { /* 已存在 */ }
+  if (!existsSync(p)) {
+    try { writeFileSync(p, `${JSON.stringify(AUDIT_HEADER)}\n`, { mode: 0o600 }) } catch { /* 由下面统一报 */ }
+  }
+  const line = `${JSON.stringify(rec)}\n`
+  appendFileSync(p, line, { mode: 0o600 })
+  return p
+}
+
+function auditOf({ cmd, flow, action, pause, task, stored, result, why }) {
+  return {
+    ts: new Date().toISOString(),
+    tool: 'argent-schedule',
+    cmd,
+    mode: APPLY ? 'apply' : 'dry-run',
+    flow: flow ? flow.flowId : '',
+    localId: flow ? flow.localId : '',
+    action,
+    pauseFile: pause || '',
+    pausePresent: Boolean(pause),
+    taskId: task ? task.id : '',
+    sessionId: task ? task.sessionId : '',
+    taskStatus: task ? task.status : '',
+    // ⚠️ catalog 条目**不是**存储里的那一条记录（字段形状不同）⇒ 两样都留：
+    //   · `taskStored` = 排程域文件里的**整条记录**（`{sessionId, record, status, lastDelivery, deliveryHistory}`）
+    //     —— 这才是"关停之后还能照着重建"的东西（`schedule/delete` 会把行连投递历史一起删掉）；
+    //   · `catalogEntry` = 当时宿主 `catalog()` 看到的那条（回执/状态的第一手证据）。
+    taskStored: stored || null,
+    catalogEntry: task || null,
+    result: result || null,
+    why: why || '',
+    by: `${(() => { try { return userInfo().username } catch { return 'unknown' } })()}@${hostname()}`,
+  }
+}
+
+/** 从排程域文件里取某条任务的**完整存储记录**（找不到 ⇒ null；只读）。 */
+function storedTask(taskId) {
+  if (!taskId) return null
+  try {
+    const paths = domainPaths(storageRoot({ dshHome: DSH_HOME || undefined }))
+    const hit = inspectDomain(paths).tasks.find((t) => t.id === taskId)
+    return hit ? hit.task : null
+  } catch { return null }
+}
+
+/**
+ * 跑一次**机制判据**（唯一实现 = `scripts/lib/schedule-mechanism.mjs`）。
+ * ⛔ 本函数只**取数 + 传参**：声明面（注册表 `schedule` 段）与证据（原生包 / 已装计划任务）
+ *    都由 L1 判据读；本文件不写第二份判据。
+ */
+async function readMechanism() {
+  return detectScheduleMechanism({
+    repo: REPO,
+    dshHome: DSH_HOME || undefined,
+    profile: PROFILE,
+    scopeDirs: SCOPE_DIRS.length ? SCOPE_DIRS : null,
+    // ⭐ F1 修复的接线点：`--scope-dir` 一个都没给 ⇒ 注入 npx 感知的候选链（L2 真源）。
+    //    ⛔ 纯探针（零写盘、零 spawn）；探不到仍如实 `unknown`（见 L1 探针的三条硬纪律）。
+    scopeDirsProbe: SCOPE_DIRS.length ? null : () => runtimeHostScopeDirs(),
+    launchAgentsDir: LAUNCH_AGENTS_DIR || '',
+    env: process.env,
+  })
+}
+
+/**
+ * **运行时宿主 scope 候选**（npx 感知；给 native 探针用）。
+ *
+ * 顺序（决定"哪一棵算这台机器在跑的那棵"）：
+ *   ① 真源解析出的那棵（`resolveDshScope()` —— 显式 > PATH 反推 > profile/global > **npx 缓存**）；
+ *   ② 链上**其余的 profile 形态**候选（保持"现役机器 profile 优先"的老语义）；
+ *   ③ 链上其余候选（node 前缀 / homebrew / Intel 兜底 —— 现役判据里它们本来就在）。
+ * ⛔ 本函数只**产出候选**，不参与判据（判据在 L1 `probeNativeSchedule`）。
+ */
+function runtimeHostScopeDirs() {
+  let hit = null
+  try { hit = resolveDshScope() } catch { hit = null }
+  const npxRoots = npxCacheDirs({ env: process.env })
+  const chain = autoScopeCandidates()
+  const profiles = chain.filter((c) => scopeSourceOf(c.dir, npxRoots) === 'profile').map((c) => c.dir)
+  const rest = chain.filter((c) => scopeSourceOf(c.dir, npxRoots) !== 'profile').map((c) => c.dir)
+  const resolved = hit && !hit.stale ? [hit.scope] : []
+  const out = []
+  for (const p of [...resolved, ...profiles, ...rest]) if (p && !out.includes(p)) out.push(p)
+  return out
+}
+
+async function cmdMechanism() {
+  const r = await readMechanism()
+  const gate = gateSchedulerConflict(r)
+  const sum = summarize([gate])
+  const payload = {
+    ok: gate.state === 'green', tool: 'argent-schedule', cmd: 'mechanism',
+    state: r.state, declared: r.declared, reason: r.reason, next: r.next || [],
+    judge: 'scripts/lib/schedule-mechanism.mjs#resolveScheduleMechanism（唯一实现）',
+    registryHow: r.how || '', flows: r.flows || [],
+    native: r.native || null, shim: r.shim || null, conflict: r.conflict || null,
+    gate, exitCode: gate.state === 'red' ? 1 : (gate.state === 'yellow' ? 2 : 0),
+  }
+  if (AS_JSON) out(payload)
+  else {
+    say(`🔎 定时机制（唯一判据：${payload.judge}）`)
+    say(`   声明面：${payload.registryHow || '（读不到）'}`)
+    say(`   ${mechanismVerdictLine(r)}`)
+    if (r.native) say(`   · 原生探针：state=${r.native.state}${r.native.source ? `｜候选来源=${r.native.source}` : ''}｜${r.native.reason}`)
+    if (r.shim) say(`   · 垫片探针：strength=${r.shim.strength}｜${r.shim.reason}`)
+    if (r.state === 'conflict') {
+      say(`   ${gate.headline}`)
+      for (const d of gate.detail || []) say(`     · ${d}`)
+      if (gate.closeOne) say(`     ↳ 关掉一条（二选一，⛔ 别两条都留）：\n${gate.closeOne}`)
+    }
+    for (const n of r.next || []) say(`     ↳ 下一步：${n}`)
+  }
+  return payload.exitCode
+}
+
+// ── 子命令 ─────────────────────────────────────────────────────────────────
+
+async function cmdProbe() {
+  const { mount, auth } = await mountOnly()
+  const gate = gateMount(mount)
+  const payload = {
+    ok: gate.state === 'green', tool: 'argent-schedule', cmd: 'probe', base: BASE,
+    endpoint: MOUNT_ENDPOINT, gate, authSource: auth.ok ? auth.source : null,
+    authTried: auth.ok ? undefined : auth.tried,
+  }
+  if (AS_JSON) out(payload)
+  else {
+    say(`🔎 排程挂载探针（${BASE}）`)
+    say(formatGates(summarize([gate])))
+    if (!auth.ok) say(`\n⚠️ 鉴权链全部失败（下面列出试过的来源）：\n${authFailureText({ tried: auth.tried, base: BASE })}`)
+  }
+  return gate.state === 'green' ? 0 : (gate.state === 'red' ? 1 : 2)
+}
+
+async function cmdStatus() {
+  const reg = await readRegistry()
+  const all = declaredSchedules(reg.doc)
+  const flows = pickFlows(all)
+  const cat = await readCatalog()
+  const mountGate = gateMount(cat.mount)
+  const rows = flows.map((f) => {
+    const m = cat.catalog ? matchTask(cat.catalog, { flowId: f.flowId, alternatives: [f.localId], taskTitle: f.taskTitle }) : { entry: null, by: 'none' }
+    const e = m.entry
+    return {
+      flow: f.flowId, localId: f.localId, enabled: f.enabled, declaredKind: f.kind, taskTitle: f.taskTitle,
+      matchBy: m.by, found: Boolean(e),
+      task: e ? { id: e.id, kind: e.kind, status: e.status, scheduledAt: e.scheduledAt, time: e.time, timeZone: e.timeZone, everySeconds: e.everySeconds, expression: e.expression, sessionId: e.sessionId, lastDelivery: e.lastDelivery } : null,
+      periodSec: e ? (Number.isFinite(PERIOD_ARG) ? PERIOD_ARG : periodSecondsOf(e)) : null,
+      pauseFile: pausePresent(f) || '',
+      nextAction: e ? '' : '宿主里还没有这条任务（P1-B：装机/升级时建；create 只在会话内可用）',
+    }
+  })
+  const payload = {
+    ok: mountGate.state === 'green', tool: 'argent-schedule', cmd: 'status', base: BASE,
+    registryHow: reg.how, registryError: reg.error || null,
+    declared: all.length, enabled: all.filter((f) => f.enabled).length, rows,
+    mount: mountGate, catalogReadable: Boolean(cat.catalog),
+    statusSetterAvailable: STATUS_SETTER_AVAILABLE,
+  }
+  if (AS_JSON) out(payload)
+  else {
+    say(`🔎 排程状态（${BASE}）｜注册表：${reg.how}${reg.error ? `（❌ ${reg.error.split('\n')[0]}）` : ''}`)
+    if (!cat.catalog) say(`   ⚠️ ${mountGate.headline} ⇒ 读不到任务清单（下面只列声明面）`)
+    say(`   声明了 trigger.schedule 的流程：${all.length} 条（enabled：${all.filter((f) => f.enabled).length}）`)
+    for (const r of rows) {
+      say(`   · ${r.flow}${r.enabled ? '' : '（enabled=false）'}｜kind=${r.declaredKind}${r.timeZone ? ` @${r.timeZone}` : ''}`)
+      if (!r.found) say(`       ⛔ 宿主里没有对应任务（匹配方式：${r.matchBy}）—— ${r.nextAction}`)
+      else {
+        say(`       ✅ 任务 ${r.task.id}｜status=${r.task.status}｜${r.task.kind}${r.task.time ? ` ${r.task.time}@${r.task.timeZone}` : ''}${r.task.everySeconds ? ` every=${r.task.everySeconds}s` : ''}`)
+        say(`          下一跳 ${r.task.scheduledAt}｜周期 ${r.periodSec === null ? '推不出（用 --period-sec）' : `${r.periodSec}s`}｜会话 ${r.task.sessionId}`)
+        say(`          上次投递 ${r.task.lastDelivery ? r.task.lastDelivery.deliveredAt : '（还没有）'}`)
+      }
+      if (r.pauseFile) say(`       ⏸ 暂停开关在：${r.pauseFile}`)
+    }
+    if (!STATUS_SETTER_AVAILABLE) say('   ℹ️ 宿主没有"置 inactive"的远端端点 ⇒ 停 = `schedule/delete`（见 pause --apply 的说明）')
+  }
+  return mountGate.state === 'green' ? 0 : (mountGate.state === 'red' ? 1 : 2)
+}
+
+async function cmdCheck() {
+  const reg = await readRegistry()
+  const all = declaredSchedules(reg.doc)
+  const flows = pickFlows(all)
+  const cat = await readCatalog()
+  const gates = [gateMount(cat.mount)]
+  const perFlow = []
+
+  const paths = domainPaths(storageRoot({ dshHome: DSH_HOME || undefined }))
+  const inspection = inspectDomain(paths)
+  const backupRoots = [join(DATA_DIR, 'backup'), join(DATA_DIR, 'backups')]
+
+  if (!flows.length) {
+    gates.push({
+      gate: 'freshness', state: 'green',
+      headline: all.length
+        ? `没有 enabled=true 的流程声明（声明了 ${all.length} 条但都是 enabled=false）⇒ 无需判新鲜度`
+        : '本机没有任何流程声明 trigger.schedule ⇒ 排程面未启用（无需判新鲜度）',
+      detail: [], next: [],
+    })
+    gates.push({
+      gate: 'execution', state: 'green',
+      headline: all.length ? '同上（没有启用的声明）' : '排程面未启用 ⇒ 没有"投递了没人干活"的对象',
+      detail: [], next: [],
+    })
+  } else {
+    for (const f of flows) {
+      const m = cat.catalog ? matchTask(cat.catalog, { flowId: f.flowId, alternatives: [f.localId], taskTitle: f.taskTitle }) : { entry: null, by: 'none' }
+      const e = m.entry
+      const period = Number.isFinite(PERIOD_ARG) ? PERIOD_ARG : (e ? periodSecondsOf(e) : null)
+      const label = `${f.flowId}（${f.taskTitle || f.kind}）`
+      const fr = gateFreshness({ entry: e, nowMs: NOW_MS, periodSec: period, label })
+      if (!e && cat.catalog) {
+        fr.detail = [`声明：kind=${f.kind}${f.timeZone ? ` @${f.timeZone}` : ''}${f.time ? ` ${f.time}` : ''}；宿主 catalog 里 ${cat.catalog.length} 条任务都没有匹配上（匹配方式 ${m.by}）`,
+          '现状 = 试点**声明已就位、任务未建**（P1-A 明确不切投递）⇒ 这一条**不是红**，但它说明"排程还没真的在跑"']
+        fr.next = ['P1-B：先确认宿主已挂载（① 绿）⇒ 再由**绑定的会话**用 schedule_create 建任务（title 必须等于注册表 taskTitle）']
+      }
+      const { logPath, ledgerPath } = l1Paths(f)
+      const ev = readL1Evidence({ logPath, ledgerPath, flowIds: [f.flowId, f.localId] })
+      const ex = gateExecution({ entry: e, evidence: ev, nowMs: NOW_MS, graceSec: GRACE_SEC, label })
+      gates.push(fr, ex)
+      perFlow.push({ flow: f.flowId, matchBy: m.by, taskId: e ? e.id : null, periodSec: period, l1: { log: ev.log, ledger: ev.ledger, newestMs: ev.newestMs } })
+    }
+  }
+  gates.push(gatePersistence(inspection, { backupRoots }))
+  // ⑤ 单一调度者（0.6.0 W8）—— 判据唯一实现在 scripts/lib/schedule-mechanism.mjs
+  let mechanism = null
+  try {
+    mechanism = await readMechanism()
+    gates.push(gateSchedulerConflict(mechanism))
+  } catch (e) {
+    gates.push(gateSchedulerConflict(null, { label: `判据跑不起来（${String((e && e.message) || e).slice(0, 120)}）` }))
+  }
+  const sum = summarize(gates)
+  const payload = {
+    ok: sum.exitCode === 0, tool: 'argent-schedule', cmd: 'check', base: BASE, now: new Date(NOW_MS).toISOString(),
+    exitCode: sum.exitCode, verdict: verdictLine(sum),
+    counts: { green: sum.green.length, red: sum.red.length, yellow: sum.yellow.length, unknown: sum.unknown.length },
+    gates, perFlow, registryHow: reg.how, registryError: reg.error || null,
+    domain: { state: inspection.state, paths: inspection.paths, files: inspection.files.map((x) => x.path), problems: inspection.problems },
+    mechanism: mechanism ? { state: mechanism.state, declared: mechanism.declared, reason: mechanism.reason, registryHow: mechanism.how } : null,
+    statusSetterAvailable: STATUS_SETTER_AVAILABLE,
+  }
+  if (AS_JSON) out(payload)
+  else {
+    say(`🔎 排程面四道闸（${BASE}）｜现在 ${payload.now}`)
+    say(formatGates(sum))
+    say(`\n${verdictLine(sum)}（exit ${sum.exitCode}）`)
+    if (reg.error) say(`   ⚠️ 注册表读不到（${reg.how}）：${String(reg.error).split('\n')[0]}`)
+  }
+  return sum.exitCode
+}
+
+/** `pause` / `apply` 的公共收敛核（**默认 dry-run**；`--apply` 才写）。 */
+async function converge(cmd) {
+  const reg = await readRegistry()
+  const all = declaredSchedules(reg.doc)
+  const flows = pickFlows(all)
+  if (APPLY && IS_REAL_DATA_DIR && !ALLOW_REAL) {
+    return {
+      exitCode: 2,
+      payload: {
+        ok: false, tool: 'argent-schedule', cmd, error: 'refused',
+        why: `--apply 会写真实数据目录（${DATA_DIR}）的审计并**删宿主任务**；本批纪律是"真实 ~/.dsh 零增量"`,
+        next: ['夹具/隔离：显式给 --data-dir <临时目录>（并配 --dsh-home <临时目录>）',
+          '确实要在本机收敛：显式加 --allow-real-home（并先 `probe`/`status` 看清楚要动哪条任务）'],
+      },
+    }
+  }
+  const cat = await readCatalog()
+  const actions = []
+  for (const f of flows) {
+    const pause = pausePresent(f)
+    const m = cat.catalog ? matchTask(cat.catalog, { flowId: f.flowId, alternatives: [f.localId], taskTitle: f.taskTitle }) : { entry: null, by: 'none' }
+    const e = m.entry
+    const wantStopped = Boolean(pause)
+    // ── 停：文件在 ⇒ 任务不该再触发 ──
+    if (wantStopped && e && e.status === 'active') {
+      let result = null
+      let action = 'stop'
+      if (APPLY) {
+        const r = await postRpc({ base: BASE, endpoint: ENDPOINTS.delete, args: { request: { id: e.id, sessionId: e.sessionId } }, cookie: (await getCookie()).cookie })
+        result = { state: r.state, httpStatus: r.httpStatus, value: r.value, code: r.code, message: r.message }
+        if (r.state === 'ok' && r.value && r.value.deleted === true) action = 'stop'
+        else if (r.state === 'ok') action = 'stop-noop'        // schedule_not_found：任务已不在（幂等）
+        else action = 'stop-failed'
+      }
+      const rec = auditOf({ cmd, flow: f, action, pause, task: e, stored: storedTask(e.id), result, why: wantStopped ? `暂停开关存在（${pause}）⇒ 收敛为"停"` : '' })
+      // ⛔ dry-run **绝不写盘**（否则"默认 dry-run"会在真实数据目录留下文件 —— 本批纪律是"真实 ~/.dsh 零增量"）
+      const p = APPLY ? writeAudit(rec) : ''
+      actions.push({ flow: f.flowId, action, pauseFile: pause, taskId: e.id, applied: APPLY, result, audit: p, auditPreview: rec })
+      continue
+    }
+    if (wantStopped && !e) {
+      const rec = auditOf({ cmd, flow: f, action: 'noop', pause, task: null, stored: null, result: null, why: '暂停开关存在，但宿主里没有这条任务 ⇒ 无需收敛（幂等）' })
+      actions.push({ flow: f.flowId, action: 'noop', pauseFile: pause, taskId: '', applied: APPLY, audit: APPLY ? writeAudit(rec) : '', auditPreview: rec })
+      continue
+    }
+    // ── 启：文件不在 ⇒ 任务应当存在且 active ──
+    if (!wantStopped && !e) {
+      const args = scheduleCreateArgs(f)
+      const rec = auditOf({ cmd, flow: f, action: 'create-required', pause, task: null, stored: null, result: { toolArgs: args }, why: '没有暂停开关，宿主里也没有任务；但 schedule/create **不是远端端点**（只在会话内由工具调用）⇒ CLI 建不了' })
+      const p = APPLY ? writeAudit(rec) : ''
+      actions.push({ flow: f.flowId, action: 'create-required', pauseFile: '', taskId: '', applied: APPLY, toolArgs: args, audit: p, auditPreview: rec })
+      continue
+    }
+    if (!wantStopped && e && e.status !== 'active') {
+      const rec = auditOf({ cmd, flow: f, action: 'dead-task', pause, task: e, stored: storedTask(e.id), result: null, why: `任务 status=${e.status}（重复型任务唯一的 inactive 来源是"算不出下一次发生"）⇒ 需要重建；CLI 建不了（create 不是远端端点）` })
+      const p = APPLY ? writeAudit(rec) : ''
+      actions.push({ flow: f.flowId, action: 'dead-task', pauseFile: '', taskId: e.id, applied: APPLY, toolArgs: scheduleCreateArgs(f), audit: p, auditPreview: rec })
+      continue
+    }
+    const rec = auditOf({ cmd, flow: f, action: 'noop', pause, task: e, stored: storedTask(e.id), result: null, why: wantStopped ? '已停（任务不在或非 active）' : '任务在且 active ⇒ 与开关一致' })
+    actions.push({ flow: f.flowId, action: 'noop', pauseFile: pause, taskId: e ? e.id : '', applied: APPLY, audit: APPLY ? writeAudit(rec) : '', auditPreview: rec })
+  }
+  const needSession = actions.some((a) => ['create-required', 'dead-task'].includes(a.action))
+  const failed = actions.some((a) => a.action === 'stop-failed')
+  const exitCode = failed ? 1 : (needSession ? 2 : 0)
+  return {
+    exitCode,
+    payload: {
+      ok: exitCode === 0, tool: 'argent-schedule', cmd, mode: APPLY ? 'apply' : 'dry-run', base: BASE,
+      dataDir: DATA_DIR, audit: APPLY ? auditPath() : null, actions,
+      statusSetterAvailable: STATUS_SETTER_AVAILABLE,
+      convergenceWindow: '⚠️ PAUSE 文件与任务状态之间**不是原子的**：文件刚落地、收敛还没跑的窗口里，定时可能照跑一轮 ⇒ 改开关后要主动跑一次收敛（写进 SOP）',
+      notes: [
+        `停 = \`schedule/delete\`（宿主没有"置 inactive"的远端端点）；被删的**整条记录**${APPLY ? '已写进审计（可据此重建）' : '会在 --apply 时写进审计（dry-run ⛔ 不写盘）'}`,
+        needSession && cmd === 'apply'
+          ? '启 = **需要会话内动作**：`schedule_create` 只在会话里可用（本 CLI 无远端端点）⇒ 见 actions[].toolArgs'
+          : (needSession ? '（pause 只做"停"方向；"启"方向由 `apply` 负责）' : ''),
+      ].filter(Boolean),
+    },
+  }
+}
+
+/** 会话内建任务时该调用的工具参数（**从注册表声明生成** —— 不在这里另写一份真源）。 */
+export function scheduleCreateArgs(flow) {
+  const s = flow.schedule || {}
+  const args = { title: flow.taskTitle || `${flow.title} · 宿主排程` }
+  switch (flow.kind) {
+    case 'every': args.every_seconds = flow.intervalSec; break
+    case 'daily': args.daily = { time: s.time, time_zone: s.timeZone }; break
+    case 'weekly': args.weekly = { time: s.time, time_zone: s.timeZone, weekdays: s.weekdays }; break
+    case 'cron': args.cron = { expression: s.expression, time_zone: s.timeZone }; break
+    case 'at': args.at = s.at; break
+    default: break
+  }
+  return { tool: 'schedule_create', args, promptFile: flow.promptFile, note: '提示词由宿主在**创建时固定**（静态）⇒ prompt 必须是"调用一条 L1 命令"，⛔ 不要带本轮票号' }
+}
+
+async function cmdConverge(cmd) {
+  const { exitCode, payload } = await converge(cmd)
+  if (AS_JSON) out(payload)
+  else {
+    say(`🔎 排程收敛（${cmd}，${APPLY ? '**apply**' : 'dry-run'}）｜数据目录 ${DATA_DIR}`)
+    if (payload.error) {
+      say(`   ⛔ 拒绝执行：${payload.why}`)
+      for (const n of payload.next || []) say(`     ↳ ${n}`)
+    } else {
+      if (!payload.actions.length) say('   （没有 enabled=true 的流程声明；用 --flow <id> 指定单条）')
+      for (const a of payload.actions) {
+        const tag = { stop: '⏹ 停', 'stop-noop': '⏹ 已是停（幂等）', 'stop-failed': '❌ 停失败', 'create-required': '🆕 需要建任务', 'dead-task': '💀 任务已死', noop: '✅ 无需动作' }[a.action] || a.action
+        say(`   ${tag} ${a.flow}${a.taskId ? `（任务 ${a.taskId}）` : ''}${a.pauseFile ? `｜开关 ${a.pauseFile}` : ''}`)
+        if (a.result) say(`       结果：${JSON.stringify(a.result)}`)
+        if (a.toolArgs) say(`       会话内建任务参数：${JSON.stringify(a.toolArgs.args)}（prompt 取 ${a.toolArgs.promptFile}）`)
+        if (a.audit) say(`       审计：${a.audit}`)
+      }
+      say(`\n   ${payload.convergenceWindow}`)
+      for (const n of payload.notes || []) say(`   ℹ️ ${n}`)
+      if (!APPLY) say('   （默认 dry-run：加 --apply 才真的删任务/写审计）')
+    }
+  }
+  return exitCode
+}
+
+// ── main ───────────────────────────────────────────────────────────────────
+try {
+  const code = CMD === 'probe' ? await cmdProbe()
+    : CMD === 'status' ? await cmdStatus()
+      : CMD === 'check' ? await cmdCheck()
+        : CMD === 'mechanism' ? await cmdMechanism()
+          : await cmdConverge(CMD)
+  process.exit(code)
+} catch (e) {
+  const payload = { ok: false, tool: 'argent-schedule', cmd: CMD, error: String((e && e.stack) || e) }
+  if (AS_JSON) out(payload)
+  else process.stderr.write(`❌ argent-schedule ${CMD} 失败：${payload.error}\n`)
+  process.exit(2)
+}