@whyshu/argent-engine 0.0.0-stage → 0.6.0

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

@@ -0,0 +1,659 @@
+#!/usr/bin/env node
+/**
+ * schedule-mechanism —— 「定时到底怎么来」的**唯一判据**（0.6.0 W8，2026-10-14）
+ *
+ * ══════════════════════════════════════════════════════════════════════════
+ * 为什么必须有它（本模块的由来）
+ * ══════════════════════════════════════════════════════════════════════════
+ * 0.6.0 起「定时」要在**两条宿主线**上都成立：
+ *   · **0.2 线（新）**：宿主自带原生排程（`@deepseek-ai/dsh-schedule`）⇒ 定时**原生**，
+ *     ⛔ 客户机不再需要装 launchd/cron；
+ *   · **0.1.7 线（存量）**：保留**激活垫片**（`com.whyshu.flow-trigger-*` + `flow-timers.sh`）。
+ * ⇒ 同一个事实（"这台机器的定时归谁"）此前有**三份**说法：`flow-timers.sh` 自己的命令模板、
+ *   插件 `setup-boot.mjs#detectNativeSchedule`、`argent-setup.mjs#checkTimer` 的 `mechanism` 字符串。
+ *   三份就会漂移（本仓库为此付过多次代价）。本模块把它收敛成**一处声明 + 一处判据**：
+ *
+ *   · **声明面（唯一）** = 注册表 `schedule.mechanism`（引擎级 base：
+ *     `scripts/flow-requirements.json`），取值 `auto | native | activation-shim | none`
+ *     + `schedule.jobs`（激活垫片的安装入口清单：`labelPrefix` / `installCommand` / `source`）。
+ *     运行期**只有两个**读取点，且都是"读它、不重写它"：
+ *       - Node 侧：本模块 `declaredScheduleMechanism()`（经 `scripts/lib/registry.mjs` 读合并注册表）；
+ *       - Python 侧：`scripts/flow_config.py --schedule-declaration`（同一条合并链）。
+ *   · **判据面（唯一）** = 本模块 `resolveScheduleMechanism()`：按声明 + 宿主证据算出**实际机制**。
+ *
+ * ══════════════════════════════════════════════════════════════════════════
+ * 纪律（改本文件前先读这四条）
+ * ══════════════════════════════════════════════════════════════════════════
+ * 1. **纯 L1**：只用 node 内建（`fs`/`path`/`os`）+ 同层模块。⛔ 不 import 宿主模块
+ *    （`node scripts/tests/kernel-purity.test.mjs` 会查），⛔ 不 import L2 插件。
+ * 2. **只读**：本模块**不写任何文件**、不注册任何任务、⛔ 不 bootstrap 任何计划任务
+ *    （AGENTS 红线：本机⛔ 不许 `launchctl bootstrap` 那 4 条 flow-trigger）。
+ * 3. **⛔ 缺证据不许当可用**：`native` 只在**真的探到**宿主排程包时才成立；
+ *    探不到**且**连"该往哪儿探"都拿不到（scope 目录都不存在 / npx 形态 ⇒ F1 未修的坑）
+ *    ⇒ 如实报 `unknown` + 原因，⛔ 不假装、⛔ 不静默装 cron。
+ * 4. **单一调度者**：一条流程**同时**被原生任务与激活垫片调度 ⇒ `conflict`（响亮报冲突，
+ *    ⛔ 不静默择一）。判据是 `schedulerConflict()`，与"两条线各自跑得好不好"分开。
+ */
+
+import { execFileSync } from 'node:child_process'
+import { existsSync, readFileSync, statSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+// ══════════════════════════════════════════════════════════════════════════
+// 一、机制枚举（**唯一出处**：别处只许引用，⛔ 不再写字面量）
+// ══════════════════════════════════════════════════════════════════════════
+
+/**
+ * 三种**生效**机制（外加两个"非机制"状态：`auto` 是声明、`unknown` 是证据不足）。
+ *
+ * | 值 | 谁在调度 | 判据 | 谁负责装 |
+ * |---|---|---|---|
+ * | `native` | 宿主原生排程（`@deepseek-ai/dsh-schedule`） | 作用域里**能探到**该包 | 宿主（⛔ 我们不注册） |
+ * | `activation-shim` | 我们自己的激活垫片（launchd/systemd + `flow-timers.sh`） | 声明允许 ∧ 探到垫片入口或已装 job | 我们（`flow-timers.sh install`） |
+ * | `none` | 没人调度（合法姿态：无定时流程的机器 / 不用宿主排程的客户机） | 声明 `none`，或两条线都**确证**没有 | 无人 |
+ */
+export const MECHANISMS = Object.freeze(['native', 'activation-shim', 'none'])
+
+/** 声明面的全部取值（多一个 `auto` = "按宿主探到的来"）。 */
+export const DECLARED_MECHANISMS = Object.freeze(['auto', ...MECHANISMS])
+
+/** 证据不足（⛔ 与 `none` 是两件事：一个是"不知道"，一个是"确证没有"）。 */
+export const UNKNOWN = 'unknown'
+
+/** 状态取值全集（`resolveScheduleMechanism()` 的 `state`）。 */
+export const STATES = Object.freeze([...MECHANISMS, UNKNOWN])
+
+/** 人读标签（CLI 与插件共用同一句，⛔ 别处不再写第二份）。 */
+export const MECHANISM_ZH = Object.freeze({
+  native: '原生（宿主排程）',
+  'activation-shim': '激活垫片（本机计划任务 + flow-timers.sh）',
+  none: '无（这台机器不该有定时器）',
+  unknown: '证据不足（⛔ 不猜）',
+})
+
+/** 声明读不到时的**中性默认**：`auto` = 让判据按宿主证据决定（⛔ 不写死任何一条线）。 */
+export const DEFAULT_DECLARED = 'auto'
+
+// ══════════════════════════════════════════════════════════════════════════
+// 二、声明面：读注册表 `schedule` 段（**只读**，⛔ 不在这里合并注册表）
+// ══════════════════════════════════════════════════════════════════════════
+
+/** 垫片 job 的**默认**声明（只有当注册表没给 `schedule.jobs` 时才用；⛔ 不覆盖声明值）。 */
+export const DEFAULT_SHIM_JOBS = Object.freeze({
+  source: 'scripts/flow-timers.sh',
+  labelPrefix: 'com.whyshu.flow-trigger',
+  installCommand: 'bash {repo}/scripts/flow-timers.sh install --flow {flow}',
+  platform: 'darwin',
+})
+
+const isObj = (v) => v !== null && typeof v === 'object' && !Array.isArray(v)
+
+/**
+ * 归一化"声明面"（注册表 `schedule` 段 → 稳定形状）。
+ * ⛔ 未知 `mechanism` **原样带出**（由 `errors` 判红），**不静默退回 auto**
+ * —— 静默退回正是"两条线各自写一份"的温床。
+ *
+ * @returns {{declared:string, declaredRaw:any, jobs:object, hostAllow:string[], errors:string[], source:string}}
+ */
+export function normalizeScheduleDeclaration(raw, { source = 'registry' } = {}) {
+  const errors = []
+  const d = isObj(raw) ? raw : {}
+  if (raw !== undefined && !isObj(raw)) errors.push('注册表 `schedule` 段必须是对象')
+  const declared = d.mechanism === undefined ? DEFAULT_DECLARED : d.mechanism
+  if (typeof declared !== 'string' || !DECLARED_MECHANISMS.includes(declared)) {
+    errors.push(`schedule.mechanism=${JSON.stringify(declared)} 不在 ${DECLARED_MECHANISMS.join('|')} 内`)
+  }
+  const jobsRaw = isObj(d.jobs) ? d.jobs : {}
+  const jobs = {
+    source: typeof jobsRaw.source === 'string' && jobsRaw.source ? jobsRaw.source : DEFAULT_SHIM_JOBS.source,
+    labelPrefix: typeof jobsRaw.labelPrefix === 'string' && jobsRaw.labelPrefix
+      ? jobsRaw.labelPrefix : DEFAULT_SHIM_JOBS.labelPrefix,
+    installCommand: typeof jobsRaw.installCommand === 'string' && jobsRaw.installCommand
+      ? jobsRaw.installCommand : DEFAULT_SHIM_JOBS.installCommand,
+    platform: typeof jobsRaw.platform === 'string' && jobsRaw.platform
+      ? jobsRaw.platform : DEFAULT_SHIM_JOBS.platform,
+  }
+  const hostAllow = Array.isArray(d.hostAllow) && d.hostAllow.length
+    ? d.hostAllow.filter((x) => typeof x === 'string')
+    : []
+  return { declared, declaredRaw: d.mechanism, jobs, hostAllow, errors, source }
+}
+
+/** 从**合并后**的注册表文档里取声明（`doc.schedule`；⛔ 不读 base 文件、不自己合并）。 */
+export function declaredScheduleMechanism(doc, { source = 'registry' } = {}) {
+  return normalizeScheduleDeclaration(doc ? doc.schedule : undefined, { source })
+}
+
+/** 把 `installCommand` 模板渲染成人可照抄的一行（`{repo}` / `{flow}` / `{label}` 占位）。 */
+export function renderInstallCommand(jobs, { repo = '', flow = '', label = '' } = {}) {
+  const tpl = (jobs && jobs.installCommand) || DEFAULT_SHIM_JOBS.installCommand
+  return String(tpl)
+    .replace(/\{repo\}/g, repo)
+    .replace(/\{flow\}/g, flow)
+    .replace(/\{label\}/g, label)
+}
+
+/** 激活垫片的 LaunchAgent/计划任务名（`com.whyshu.flow-trigger-<flow>`）。 */
+export function shimLabelOf(jobs, flowId) {
+  const pre = (jobs && jobs.labelPrefix) || DEFAULT_SHIM_JOBS.labelPrefix
+  return `${pre}-${flowId}`
+}
+
+// ══════════════════════════════════════════════════════════════════════════
+// 三、证据面：探针（全都是**只读**的文件系统事实）
+// ══════════════════════════════════════════════════════════════════════════
+
+const statOrNull = (p) => { try { return statSync(p) } catch { return null } }
+
+/**
+ * 宿主原生排程（`@deepseek-ai/dsh-schedule`）到底在不在。
+ *
+ * ⚠️ **三条硬纪律**（F1 修复后仍在 —— 修的是"探得到"，⛔ 不是"放宽缺证据"）：
+ *   ① 目录**存在**且其中**有** `dsh-schedule/` ⇒ `available`（能力探测，⛔ 不认版本号）；
+ *   ② 目录**存在**但没有该包 ⇒ `absent`（**确证没有**）；
+ *   ③ 候选目录**一个都不存在** ⇒ `unknown`（**证据不足**）—— npx 形态若仍探不到就还是这一态，
+ *      ⛔ 不许当成"没有原生排程"（那会把人骗去装一份用不上的 cron）。
+ *
+ * @param {{scopeDirs?: string[], exists?: Function, packages?: string[], source?: string}} [o]
+ *   `source` —— 这批候选**怎么来的**（"本机 profile 候选 N 个 + 运行时解析链 M 个"），
+ *   只进 `reason`/`source`（可诊断），⛔ 不参与判据。
+ * @returns {{state:'available'|'absent'|'unknown', available:boolean, found:string, source:string,
+ *            dirs:string[], existing:string[], reason:string}}
+ */
+export function probeNativeSchedule({ scopeDirs = [], exists = existsSync, packages = ['dsh-schedule'], source = '' } = {}) {
+  const dirs = (scopeDirs || []).filter((d) => typeof d === 'string' && d)
+  const existing = []
+  const found = []
+  for (const dir of dirs) {
+    if (!exists(dir)) continue
+    existing.push(dir)
+    for (const pkg of packages) {
+      const p = join(dir, pkg)
+      if (exists(p)) found.push(p)
+    }
+  }
+  if (found.length) {
+    return {
+      state: 'available', available: true, found: found[0], dirs, existing, source,
+      reason: `作用域里探到宿主排程包（${found[0]}）`,
+    }
+  }
+  if (existing.length) {
+    return {
+      state: 'absent', available: false, found: '', dirs, existing, source,
+      reason: `作用域存在（${existing.join('、')}）但没有 ${packages.join('/')} ⇒ 确证：这条线上没有原生排程`,
+    }
+  }
+  return {
+    state: 'unknown', available: false, found: '', dirs, existing, source,
+    reason: dirs.length
+      ? `候选作用域**一个都不存在**（${dirs.join('、')}）⇒ 探不到 ≠ 没有（候选来源：${source || '未标注'}）`
+      : '没有给出任何候选作用域 ⇒ 无从探测',
+  }
+}
+
+/**
+ * 从已装计划任务路径反推**是哪几条流程**（`<prefix>-<flow>.plist` / `.service`）。
+ * ⛔ 认不出就**不列**（宁可少报一条，也不猜一个流程名）。
+ */
+export function flowsFromPlists(plists = [], jobs = DEFAULT_SHIM_JOBS) {
+  const pre = `${(jobs && jobs.labelPrefix) || DEFAULT_SHIM_JOBS.labelPrefix}-`
+  const out = []
+  for (const p of plists || []) {
+    const base = String(p).split('/').pop() || ''
+    const name = base.replace(/\.(plist|service)$/, '')
+    if (!name.startsWith(pre)) continue
+    const f = name.slice(pre.length)
+    if (f && !out.includes(f)) out.push(f)
+  }
+  return out
+}
+
+/**
+ * 激活垫片（`com.whyshu.flow-trigger-*`）在不在。
+ * 判据（**只看文件系统事实，⛔ 不跑 `launchctl`**）：
+ *   · 已装的计划任务文件（`LaunchAgents/<label>.plist`）—— **最强**证据；
+ *   · 垫片入口脚本本身（`<repo>/scripts/flow-timers.sh`）—— 弱证据（装了 ≠ 已启用）。
+ *
+ * @returns {{present:boolean, strength:'installed'|'entry-only'|'none', plists:string[],
+ *            entry:string, reason:string}}
+ */
+export function probeActivationShim({
+  flows = [], jobs = DEFAULT_SHIM_JOBS, repo = '', launchAgentsDir = '',
+  exists = existsSync, home = homedir(), platform = process.platform,
+} = {}) {
+  const laDir = launchAgentsDir || (platform === 'darwin'
+    ? join(home, 'Library', 'LaunchAgents')
+    : join(home, '.config', 'systemd', 'user'))
+  const plists = []
+  for (const f of flows.filter(Boolean)) {
+    for (const ext of ['.plist', '.service']) {
+      const p = join(laDir, `${shimLabelOf(jobs, f)}${ext}`)
+      if (exists(p)) plists.push(p)
+    }
+  }
+  const entry = repo ? join(repo, 'scripts', 'flow-timers.sh') : ''
+  const entryExists = Boolean(entry && exists(entry))
+  if (plists.length) {
+    return {
+      present: true, strength: 'installed', plists, entry,
+      reason: `已装计划任务 ${plists.length} 个（${plists.slice(0, 3).join('、')}${plists.length > 3 ? ' …' : ''}）`,
+    }
+  }
+  if (entryExists) {
+    return {
+      present: true, strength: 'entry-only', plists, entry,
+      reason: `垫片入口在（${entry}）但没有已装的计划任务 ⇒ 装了 ≠ 已启用`,
+    }
+  }
+  return { present: false, strength: 'none', plists, entry, reason: '既没有已装计划任务、也没有垫片入口' }
+}
+
+// ══════════════════════════════════════════════════════════════════════════
+// 四、判据：声明 + 证据 ⇒ 实际机制（**唯一**的一处推理）
+// ══════════════════════════════════════════════════════════════════════════
+
+/**
+ * 算"这台机器实际的定时机制"。**纯函数**（无 IO —— 证据由调用方探好传进来）。
+ *
+ * 判据表（⛔ 缺证据一律 `unknown`，⛔ 绝不"缺证据就当可用"）：
+ *
+ * | 声明 | native 证据 | shim 证据 | ⇒ 机制 | 说明 |
+ * |---|---|---|---|---|
+ * | `native` | available | — | `native` | 声明与证据一致 |
+ * | `native` | absent/unknown | — | `unknown` | **响亮降级**：声明要原生，但探不到 ⇒ 不假装可用 |
+ * | `activation-shim` | — | present | `activation-shim` | 存量线 |
+ * | `activation-shim` | — | none | `unknown` | 声明要垫片但没装 ⇒ 不假装已装 |
+ * | `none` | — | — | `none` | 明确不要定时器 |
+ * | `auto` | available | none | `native` | 有原生 ⇒ 走原生（⛔ 不再装垫片） |
+ * | `auto` | available | present | `conflict` | 两条线同时在 ⇒ 响亮报冲突（细节见 `schedulerConflict`） |
+ * | `auto` | absent | installed | `activation-shim` | 存量线（0.1.7） |
+ * | `auto` | absent | none/entry-only | `none` | 确证两条线都没有 |
+ * | `auto` | unknown | installed | `activation-shim` | 垫片已确证在用 ⇒ 不因"探不到原生"而停滞 |
+ * | `auto` | unknown | none/entry-only | `unknown` | **证据不足**（npx 形态的典型） |
+ *
+ * @returns {{state:string, declared:string, reason:string, next:string[], native:object|null,
+ *            shim:object|null, conflict:object|null}}
+ */
+export function resolveScheduleMechanism({ declaration, native = null, shim = null } = {}) {
+  const decl = isObj(declaration) && declaration.declared
+    ? declaration
+    : normalizeScheduleDeclaration(declaration)
+  if (decl.errors && decl.errors.length) {
+    return {
+      state: UNKNOWN, declared: String(decl.declaredRaw),
+      reason: `声明面非法（${decl.errors.join('；')}）⇒ ⛔ 不猜机制`,
+      next: ['修注册表 `schedule.mechanism`（唯一声明点）后重跑；判据见 scripts/lib/schedule-mechanism.mjs'],
+      native, shim, conflict: null,
+    }
+  }
+  const declared = decl.declared
+  const natState = native ? native.state : 'unknown'
+  const shimPresent = Boolean(shim && shim.present)
+  const shimStrong = Boolean(shim && shim.strength === 'installed')
+  // ⚠️ **冲突只看已装计划任务**（`strength === 'installed'`）——"垫片入口在"（entry-only）
+  //   在每台有仓库的机器上都成立（那只是"装了仓"），拿它判双跑会**误报**（响亮 ≠ 狼来了）。
+  const conflict = (natState === 'available' && shimStrong)
+    ? schedulerConflict({ native, shim })
+    : null
+
+  if (declared === 'none') {
+    return {
+      state: 'none', declared, reason: '声明 schedule.mechanism=none ⇒ 这台机器不该有定时器（合法姿态）',
+      next: [], native, shim, conflict: null,
+    }
+  }
+  if (declared === 'native') {
+    if (natState === 'available') {
+      return {
+        state: 'native', declared,
+        reason: `声明 native ∧ 探到宿主排程（${native.found}）⇒ 定时归宿主（⛔ 不装垫片）`,
+        next: [], native, shim, conflict,
+      }
+    }
+    return {
+      state: UNKNOWN, declared,
+      reason: `声明 native，但 ${native ? native.reason : '没有原生排程证据'} ⇒ **响亮降级**（⛔ 不假装可用、⛔ 不静默装 cron）`,
+      next: [
+        '确认宿主的排程服务真的在组合里（`node scripts/argent-schedule.mjs probe`：404 ⇒ 没挂载）',
+        '0.2 线：把排程 bundle 加进 profile 的 dsh.profile.bundles；0.1.x：按 id 覆盖三行 disabled:false',
+        '若这台机器本来就该用激活垫片 ⇒ 把声明改成 activation-shim（唯一声明点：注册表 `schedule.mechanism`）',
+      ],
+      native, shim, conflict,
+    }
+  }
+  if (declared === 'activation-shim') {
+    if (shimPresent) {
+      return {
+        state: 'activation-shim', declared,
+        reason: `声明 activation-shim ∧ ${shim.reason}`,
+        next: [], native, shim, conflict,
+      }
+    }
+    return {
+      state: UNKNOWN, declared,
+      reason: `声明 activation-shim，但 ${shim ? shim.reason : '没有垫片证据'} ⇒ 不假装已装`,
+      next: [`按声明面的命令装：${renderInstallCommand(decl.jobs, { flow: '<flow>' })}`],
+      native, shim, conflict,
+    }
+  }
+  // ── auto：按证据决定 ──────────────────────────────────────────────────────
+  if (natState === 'available') {
+    if (shimStrong) {
+      return {
+        state: 'conflict', declared,
+        reason: `原生排程可得（${native.found}）**且**激活垫片**已装计划任务**（${shim.reason}）⇒ **单一调度者**被破坏`,
+        next: conflict ? conflict.next : [],
+        native, shim, conflict,
+      }
+    }
+    return {
+      state: 'native', declared,
+      reason: `auto ∧ ${native.reason} ∧ ${shimPresent ? `垫片只有弱证据（${shim.reason}，不足以判双跑）` : '无垫片'} ⇒ 走原生（⛔ 不再装 cron/launchd）`,
+      next: [], native, shim, conflict: null,
+    }
+  }
+  if (shimStrong) {
+    return {
+      state: 'activation-shim', declared,
+      reason: `auto ∧ 原生${natState === 'unknown' ? '探不到（证据不足，不足以推翻垫片）' : '确证没有'} ∧ ${shim.reason} ⇒ 走垫片`,
+      next: [], native, shim, conflict: null,
+    }
+  }
+  if (natState === 'absent' && !shimPresent) {
+    return {
+      state: 'none', declared,
+      reason: 'auto ∧ 原生确证没有 ∧ 垫片也没装 ⇒ 这台机器当前无定时器（合法姿态，但不是 native）',
+      next: ['要开定时：走原生（装宿主排程）或走垫片（`flow-timers.sh install`）——二选一，⛔ 不许两条都开'],
+      native, shim, conflict: null,
+    }
+  }
+  return {
+    state: UNKNOWN, declared,
+    reason: `auto ∧ ${native ? native.reason : '没有原生证据'}${shimPresent ? `；垫片只有弱证据（${shim.reason}）` : '；垫片也没有'}`,
+    next: [
+      '补证据再判：宿主排程用 `node scripts/argent-schedule.mjs probe`（200=挂载 / 404=没有 / 连不上=证据不足）',
+      '垫片用 `bash scripts/flow-timers.sh status`（本机 ⛔ 不许 bootstrap）',
+      '⛔ 证据不足时**不要**顺手装一份 cron —— 那会造出第二个调度者',
+    ],
+    native, shim, conflict: null,
+  }
+}
+
+/**
+ * **native 注册的计划清单**（"要交给宿主什么"）—— 纯函数、幂等（同样的输入 ⇒ 同样的输出）。
+ *
+ * ⛔ 本函数**不注册任何东西**、**不发任何请求**：它只把声明面的 `trigger.schedule`
+ * 摊成宿主 `schedule_create` 要的那几项（title / 时机 / 静态指令命令），供
+ *   ① 运维照抄（`argent-schedule.mjs status` 的 `toolArgs` 已在做同一件事）、
+ *   ② 幂等判据（把宿主**已有**的条目喂进 `existing` ⇒ `action==='already-native'`，零变化）、
+ *   ③ 冲突排查（`shouldRegisterShim` 让"该不该再装垫片"变成**一个布尔**，不靠人记）。
+ *
+ * @param {{doc:object, native:object|null, shim:object|null, existing?:Array,
+ *          repo?:string, home?:string, component?:string}} opts
+ */
+export function scheduleCatalogRows({ doc, native = null, shim = null, existing = [], repo = '', home = '', component = '<数据目录>' } = {}) {
+  const rows = []
+  const aliases = (doc && doc.aliases) || {}
+  const back = {}
+  for (const [short, canon] of Object.entries(aliases)) back[canon] = short
+  const nativeOk = Boolean(native && native.state === 'available')
+  const shimInstalled = Boolean(shim && shim.strength === 'installed')
+  const existingTitles = new Set((existing || [])
+    .map((e) => String((e && (e.jobTitle || e.taskTitle || e.title)) || ''))
+    .filter(Boolean))
+  for (const [flowId, spec] of Object.entries((doc && doc.flows) || {})) {
+    const t = (spec && spec.trigger) || {}
+    const sc = t.schedule
+    if (!sc || typeof sc !== 'object' || sc.enabled !== true) continue
+    const localId = back[flowId] || String(flowId).split('.').pop()
+    const title = String(sc.taskTitle || '')
+    const logRel = String(t.log || '')
+    const row = {
+      flowId,
+      localId,
+      jobTitle: title,
+      kind: String(sc.kind || ''),
+      // 周期只有一个真源 ⇒ kind=every 时从 trigger.intervalSec 取（声明面的 everySecondsFrom 指回它）
+      everySeconds: sc.everySecondsFrom === 'intervalSec' && Number.isFinite(t.intervalSec) ? t.intervalSec : null,
+      time: sc.time === undefined ? null : sc.time,
+      timeZone: sc.timeZone === undefined ? null : sc.timeZone,
+      expression: sc.expression === undefined ? null : sc.expression,
+      weekdays: sc.weekdays === undefined ? null : sc.weekdays,
+      promptFile: String(sc.promptPath || sc.promptFile || ''),
+      onPause: String(sc.onPause || ''),
+      // 静态轮次指令：宿主在**创建时固定** prompt ⇒ 它必须是"调一条 L1 命令"，⛔ 不带本轮票号。
+      // ⭐ `--no-wake`（0.6.0 P1-B）：宿主的计划任务是**无会话**执行的（只跑这条固定命令）
+      // ⇒ 命令必须是"只认领、不唤起会话"（认领与 `planned` 台账照常，见 flow-trigger.sh 的该开关）。
+      // ⛔ 这条只属于**原生排程**；0.1.7 线的激活垫片跑的是 `flow-timers.sh` 生成的 plist
+      //    （ProgramArguments 直接指向 flow-trigger.sh 的**默认**模式，它要唤醒角色会话）
+      //    —— 两条线各自一条命令，⛔ 不互相抄。
+      promptCommand: `bash ${repo || '<repo>'}/scripts/flow-trigger.sh --flow ${localId} --no-wake`
+        + (logRel ? ` >> ${join(home || component, logRel)} 2>&1` : ''),
+      scheduler: nativeOk ? 'native' : (shimInstalled ? 'activation-shim' : 'none'),
+      shouldRegisterShim: !nativeOk,
+      action: existingTitles.has(title) ? 'already-native' : (nativeOk ? 'register-native' : 'print-shim-command'),
+    }
+    if (!nativeOk && shimInstalled) row.action = 'conflict'
+    rows.push(row)
+  }
+  return rows
+}
+
+/** 取"用于比对幂等"的那几个字段（⛔ 不把 reason/时间戳这类易变字段算进判据）。 */
+export function normalizedNativeRow(row) {
+  return {
+    flowId: row.flowId, localId: row.localId, jobTitle: row.jobTitle, kind: row.kind,
+    everySeconds: row.everySeconds, time: row.time, timeZone: row.timeZone,
+    expression: row.expression, weekdays: row.weekdays, promptFile: row.promptFile, onPause: row.onPause,
+    promptCommand: row.promptCommand, scheduler: row.scheduler,
+  }
+}
+
+/**
+ * 单一调度者纪律：同一条流程**同时**被两条线调度 ⇒ 冲突（⛔ 不静默择一）。
+ * @param {{flows?:string[], native?:object, shim?:object, nativeFlows?:string[], shimFlows?:string[]}} [opts]
+ * @returns {{state:'conflict', flows:string[], detail:string, next:string[], closeOne:string}}
+ *   `closeOne` = **逐字可照抄**的一句"怎么关掉一条"（两条都给，⛔ 不替用户选）。
+ */
+export function schedulerConflict({ flows = [], native = null, shim = null, nativeFlows = [], shimFlows = [] } = {}) {
+  const both = (nativeFlows.length && shimFlows.length)
+    ? nativeFlows.filter((f) => shimFlows.includes(f))
+    : (flows || [])
+  const closeOne = '二选一（⛔ 别两条都留着）：\n'
+    + '  · 关垫片：`bash scripts/flow-timers.sh uninstall --flow <flow>`（会 bootout 该 label）\n'
+    + '  · 关原生：会话内 `schedule_delete`（宿主没有"置 inactive"的远端端点；CLI 侧见 `node scripts/argent-schedule.mjs pause --apply`）'
+  if (!nativeFlows.length && !shimFlows.length && !both.length) {
+    return {
+      state: 'conflict',
+      flows: [],
+      detail: '原生排程与激活垫片**同时在场**；但没有逐条流程的对照证据 ⇒ 只能判"有双跑风险"，⛔ 不能点名是哪几条',
+      next: ['先按上面的 `bootstrap`/`install` 命令把两条线的**逐条**证据取出来，再定点关掉一条'],
+      closeOne,
+    }
+  }
+  return {
+    state: 'conflict',
+    flows: both,
+    detail: `这些流程被**两条线同时**调度：${both.join('、') || '（无法逐条对照）'}`
+      + `｜原生：${native ? native.reason || '（在场）' : '（无证据）'}｜垫片：${shim ? shim.reason || '（在场）' : '（无证据）'}`,
+    next: [
+      '**先停一条再验证**：⛔ 不要靠"两边各跑一半" —— 台账是每机独立文件、lease 无跨机/跨调度者互斥 ⇒ 必然抢行',
+      '关掉一条后盯一个完整周期：另一条线的日志不再增长、无新增认领',
+    ],
+    closeOne,
+  }
+}
+
+// ══════════════════════════════════════════════════════════════════════════
+// 五、一步到位：从**声明 + 探针**算出结论（CLI/插件/门禁共用这一条链）
+// ══════════════════════════════════════════════════════════════════════════
+
+/** 本模块所在目录（定位 `flow_registry.py` 用；⛔ 不依赖 cwd）。 */
+const HERE = dirname(fileURLToPath(import.meta.url))
+
+/**
+ * **同步**读合并注册表（唯一真源仍是 `scripts/flow_registry.py`，⛔ 本模块不实现合并）。
+ * 命令与 `scripts/lib/registry.mjs#loadRegistryDoc()` **同一条**：`<py> scripts/flow_registry.py --json`
+ * + `ARGENT_REGISTRY_ROOT=<root>`；解释器优选 `ARGENT_PY`（与内核口径一致），否则裸 `python3`。
+ * 读不到 ⇒ **抛错**（调用方按"证据不足 + 原因"上报，⛔ 不静默用一份空注册表顶上）。
+ */
+export function defaultSyncRegistryLoader({ repo = '', runSync = null } = {}) {
+  const root = repo || dirname(HERE)
+  const py = (process.env && process.env.ARGENT_PY) || 'python3'
+  return ({ root: r } = {}) => {
+    const use = r || root
+    const args = [join(use, 'scripts', 'flow_registry.py'), '--json']
+    const run = runSync || ((cmd, argv, opts) => execFileSync(cmd, argv, opts))
+    const out = run(py, args, {
+      encoding: 'utf8', maxBuffer: 64 * 1024 * 1024,
+      env: { ...process.env, ARGENT_REGISTRY_ROOT: use },
+    })
+    return JSON.parse(out)
+  }
+}
+
+/**
+ * 组装声明 + native 探针 + shim 探针 ⇒ `resolveScheduleMechanism()`。
+ * `deps` 全可注入（夹具零 IO）：
+ *   · `doc`        —— 已合并注册表（给 `doc` 就不调 `loadRegistryDoc()`）
+ *   · `loadDoc`    —— 注册表加载器（缺省动态 import `./registry.mjs`）
+ *   · `scopeDirs`  —— 宿主作用域候选（缺省由 `scopeDirsFrom()` 从 dshHome/profile 推）
+ *   · `scopeDirsProbe` —— **调用方注入的 scope 候选解析器**（返回字符串数组；缺省 null = 用 `scopeDirsFrom()`）。
+ *     ⚠️ **0.6.0 F1 修复批（2026-10-14）**：npx 形态（`npx @deepseek-ai/dsh web`）的宿主树在
+ *     `~/.npm/_npx/<hash>/node_modules/@deepseek-ai` ⇒ `scopeDirsFrom()` **一条都推不出来** ⇒
+ *     native 恒判 `unknown`（MBP 实测）。npx 感知的候选链**唯一实现在 L2 的
+ *     `scripts/lib/dsh-scope.mjs#autoScopeCandidates()`**（本文件是 L1，⛔ 不 import 宿主档）；
+ *     故由调用方（`scripts/argent-schedule.mjs` / `scripts/argent-setup-check.mjs`，均 L2）注入。
+ *     优先级仍由 L1 定：**profile 候选优先**（现役机器语义不变）＞ 注入链的其余候选。
+ *   · `flows`      —— 已启用的流程 id（垫片 job 名用；缺省从 doc 的 trigger.schedule 推）
+ */
+export async function detectScheduleMechanism(opts = {}) {
+  return detectScheduleMechanismSync(opts)
+}
+
+/**
+ * **同步**版判据（0.6.0 W8）：宿主启动期那条路径要求**同步有界**
+ * （见 `plugins/argent-core/src/index.js` 的"本批刻意不 await"）⇒ 异步版会让状态文件晚一拍落盘。
+ * 判据与异步版**逐字同源**（`resolveScheduleMechanism()` 是纯函数）；差别只在"怎么把注册表读进来"：
+ * 这里走 `execFileSync`（与 `scripts/lib/registry.mjs` 同一条命令），⛔ 不自己实现合并。
+ */
+export function detectScheduleMechanismSync({
+  doc = null, loadDoc = null, dshHome = '', profile = '', repo = '', flows = null,
+  scopeDirs = null, scopeDirsProbe = null, launchAgentsDir = '', platform = process.platform, home = homedir(),
+  exists = existsSync, env = process.env, runSync = null,
+} = {}) {
+  let document = doc
+  let how = 'doc（调用方传入）'
+  if (!document) {
+    try {
+      const loader = loadDoc || defaultSyncRegistryLoader({ repo, runSync })
+      document = loader({ root: repo || undefined })
+      how = 'flow_registry.py（合并，唯一真源）'
+    } catch (e) {
+      return {
+        state: UNKNOWN,
+        declaration: normalizeScheduleDeclaration(undefined, { source: '（读不到）' }),
+        reason: `注册表读不到（${String((e && (e.stderr || e.message)) || e).split('\n')[0]}）⇒ ⛔ 不猜机制`,
+        next: ['确认 python 与 scripts/flow_registry.py 可用：python3 scripts/flow_registry.py --json | head'],
+        native: null, shim: null, conflict: null, how,
+      }
+    }
+  }
+  const declaration = declaredScheduleMechanism(document, { source: how })
+  // scope 候选：显式 > 调用方注入的解析器（**npx 感知**，见 `scopeDirsProbe` 文档）> `scopeDirsFrom()`。
+  // ⚠️ 注入链的候选**排在 profile 候选之后** ⇒ 现役机器的选择不变（F1 修复不制造回归）。
+  const scopePick = Array.isArray(scopeDirs) && scopeDirs.length
+    ? { dirs: scopeDirs, from: '调用方显式传入' }
+    : mergeScopeDirs(scopeDirsFrom({ dshHome, profile, env }), scopeDirsProbe)
+  const native = probeNativeSchedule({ scopeDirs: scopePick.dirs, exists, source: scopePick.from })
+  const flowIds = Array.isArray(flows) && flows.length ? flows : scheduledFlowIds(document)
+  const shim = probeActivationShim({
+    flows: flowIds, jobs: declaration.jobs, repo, launchAgentsDir, exists, home, platform,
+  })
+  const r = resolveScheduleMechanism({ declaration, native, shim })
+  // ⛔ `conflict` 的细节必须**点名是哪几条**流程（判"有双跑风险"而不点名，等于让人自己去猜）——
+  //   逐条证据来自垫片探针（已装计划任务名 ⇒ 流程本地名），原生侧 = 声明里 enabled 的那几条。
+  if (r.state === 'conflict') {
+    const shimFlows = flowsFromPlists(shim.plists, declaration.jobs)
+    r.conflict = schedulerConflict({ native, shim, nativeFlows: flowIds, shimFlows })
+  }
+  return { ...r, declaration, how, flows: flowIds }
+}
+
+/** 从合并注册表里取"声明了 `trigger.schedule` 且 enabled"的流程 id（本地名优先）。 */
+export function scheduledFlowIds(doc) {
+  const out = []
+  const aliases = (doc && doc.aliases) || {}
+  const back = {}
+  for (const [short, canon] of Object.entries(aliases)) back[canon] = short
+  for (const [flowId, spec] of Object.entries((doc && doc.flows) || {})) {
+    const s = spec && spec.trigger && spec.trigger.schedule
+    if (!s || typeof s !== 'object') continue
+    if (s.enabled !== true) continue
+    out.push(back[flowId] || String(flowId).split('.').pop())
+  }
+  return out
+}
+
+/**
+ * 宿主作用域候选（`…/node_modules/@deepseek-ai`）。
+ * ⚠️ 与内核既有口径同源（`scripts/lib/dsh-scope.mjs` / 插件 `setup-boot.mjs#scopeCandidates`），
+ * 但**本函数只产生候选**：探不到就由 `probeNativeSchedule()` 报 `unknown`（F1 未修 ⇒ 必须响亮）。
+ */
+export function scopeDirsFrom({ dshHome = '', profile = '', env = process.env, home = homedir() } = {}) {
+  const out = []
+  const push = (p) => { if (p && !out.includes(p)) out.push(p) }
+  push(env && env.DSH_SCOPE)
+  const dh = dshHome || (env && env.DSH_HOME) || (home ? join(home, '.dsh') : '')
+  if (dh && profile) push(join(dh, 'profiles', profile, 'node_modules', '@deepseek-ai'))
+  return out
+}
+
+/**
+ * 合并 L1 自有候选 + 调用方注入的候选（去重；**L1 侧在前** ⇒ 现役 profile 语义不变）。
+ *
+ * ⚠️ 注入器抛错/返回非数组 ⇒ **静默退到 L1 自有候选**（⛔ 不让一次探针故障把判据打崩 ——
+ *    探不到仍由 `probeNativeSchedule()` 如实报 `unknown`）。返回**来源标签**便于把"试过哪些"打给人看。
+ * @returns {{dirs: string[], from: string}}
+ */
+export function mergeScopeDirs(own = [], probe = null) {
+  const out = []
+  const push = (p) => { if (typeof p === 'string' && p && !out.includes(p)) out.push(p) }
+  for (const p of own || []) push(p)
+  const ownCount = out.length
+  let extra = []
+  if (typeof probe === 'function') {
+    try { extra = probe() || [] } catch { extra = [] }
+  } else if (Array.isArray(probe)) extra = probe
+  for (const p of extra) push(p)
+  const n = out.length - ownCount
+  return {
+    dirs: out,
+    from: n > 0
+      ? `本机 profile 候选 ${ownCount} 个 + 运行时解析链 ${n} 个（npx 感知）`
+      : `本机 profile 候选 ${ownCount} 个`,
+  }
+}
+
+/** 一行结论（CLI / 插件 / 门禁共用；⛔ 别处不再拼第二句）。 */
+export function mechanismVerdictLine(r) {
+  if (!r) return '❓ 定时机制：没有结论'
+  const tag = r.state === 'native' || r.state === 'activation-shim' ? '✅'
+    : r.state === 'none' ? '➖' : r.state === 'conflict' ? '❌' : '❓'
+  return `${tag} 定时机制：${MECHANISM_ZH[r.state] || r.state}（声明 ${r.declared}）—— ${r.reason}`
+}
+
+/** 读一份 JSON（读不到/解析失败 ⇒ `{ok:false, error}`；⛔ 不抛）。 */
+export function readJsonFile(path) {
+  try { return { ok: true, doc: JSON.parse(readFileSync(path, 'utf8')) } }
+  catch (e) { return { ok: false, error: String((e && (e.code || e.message)) || e) } }
+}
+
+/** 文件存在且是非空目录（探针用；`stat` 失败 ⇒ false，⛔ 不抛）。 */
+export function isDir(path) {
+  const st = statOrNull(path)
+  return Boolean(st && st.isDirectory())
+}