@mzzsfy/dsh-cron-board 0.1.0

package/src/config.mjs

@@ -0,0 +1,10 @@
+// 全局默认常量:宿主 settings 未就绪/未覆盖时的兜底值(计算表达式,禁魔法值)
+
+export const DEFAULT_TIMEOUT_MS = 60 * 60 * 1000
+// 同名多值组合数全局上限:超限截断防打爆机器(设计 §4.2)
+export const DEFAULT_MAX_EXPANSION = 20
+// 全局并发上限:同时运行的执行单元数(设计 §4.1)
+export const DEFAULT_MAX_CONCURRENT = 2
+// 调度 tick 周期与下限(设计 §4.1)
+export const DEFAULT_TICK_MS = 30 * 1000
+export const MIN_TICK_MS = 5 * 1000

package/src/cron.mjs

@@ -0,0 +1,50 @@
+// cron 解析薄封装:croner 承担表达式解析与触发点计算(5/6 段通吃、时区、DST)。
+// 非法表达式以业务错误抛出,文案中文原样透传给路由层。
+
+import { Cron } from 'croner'
+
+// 求自 from 起下一次触发点(ms epoch);表达式无未来触发点时返回 null
+export function nextRunAtOf(schedule, from = new Date()) {
+  const job = new Cron(schedule)
+  const next = job.nextRun(from)
+  return next ? next.getTime() : null
+}
+
+// 求自 from 起下 N 次触发点(编辑表单实时预览用)
+export function nextRunsOf(schedule, count, from = new Date()) {
+  const job = new Cron(schedule)
+  return job.nextRuns(count, from).map((date) => date.getTime())
+}
+
+// 表达式合法性校验:合法返回 null,非法抛业务错误
+export function assertValidSchedule(schedule) {
+  try {
+    new Cron(schedule)
+  } catch (error) {
+    throw new Error('cron 表达式不合法: ' + schedule)
+  }
+}
+
+const WEEKDAY_LABELS = ['日', '一', '二', '三', '四', '五', '六']
+const PAD2 = (value) => String(value).padStart(2, '0')
+
+// 人话摘要(轻量规则覆盖常用形态,兜底回原表达式)
+export function summarizeCron(schedule) {
+  const parts = String(schedule).trim().split(/\s+/)
+  if (parts.length !== 5) return schedule
+  const [minute, hour, day, month, weekday] = parts
+  const clock = (h, m) => PAD2(h) + ':' + PAD2(m)
+  const dayFree = day === '*' && month === '*' && weekday === '*'
+  if (dayFree && /^\*\/\d+$/.test(hour) && minute === '0') return '每 ' + hour.slice(2) + ' 小时'
+  if (dayFree && hour.startsWith('*/')) return '每 ' + hour.slice(2) + ' 小时(第 ' + minute + ' 分)'
+  if (dayFree && /^\*\/\d+$/.test(minute) && hour === '*') return '每 ' + minute.slice(2) + ' 分钟'
+  if (!/^\d+$/.test(minute) || !/^\d+$/.test(hour)) return schedule
+  if (month !== '*' || day !== '*') {
+    if (/^\d+$/.test(day) && month === '*') return '每月 ' + day + ' 日 ' + clock(hour, minute)
+    return schedule
+  }
+  if (weekday === '1-5') return '工作日 ' + clock(hour, minute)
+  if (/^\d$/.test(weekday)) return '每周' + (WEEKDAY_LABELS[Number(weekday)] || weekday) + ' ' + clock(hour, minute)
+  if (day === '*' && weekday === '*') return '每天 ' + clock(hour, minute)
+  return schedule
+}

package/src/env-expand.mjs

@@ -0,0 +1,51 @@
+// 环境变量同名多值展开:某名称 N 个启用值贡献 N 次,组合数 = 各多值名称值的笛卡尔积;
+// DFS 按需产出前 maxExpansion 个完整组合(绝不物化指数级全量,每个产出组含全部变量),
+// 截断以 truncated 标志交由调用方告警。
+
+// 多值行(行级 multi 标志,value 为换行拼接)与同名多行两条来源路径归一到值序列;
+// multi 行拆分后为空(勾选多值但未填值)回退单空值,与非 multi 空值行语义一致
+// (否则该名下 0 值导致整体 0 组合,静默不执行)
+function valuesOf(row) {
+  if (row.multi === true) {
+    const values = String(row.value ?? '').split(/\r?\n/).map((line) => line.trim()).filter((line) => line !== '')
+    return values.length > 0 ? values : ['']
+  }
+  return [row.value]
+}
+
+export function expandEnvMatrix({ envs, maxExpansion }) {
+  const enabled = envs.filter((row) => row.enabled)
+  const byName = new Map()
+  for (const row of enabled) {
+    const values = byName.get(row.name) || []
+    values.push(...valuesOf(row))
+    byName.set(row.name, values)
+  }
+  const names = [...byName.keys()]
+
+  // 深度优先按字典序产出;count 达上限即整枝剪断
+  const combinations = []
+  let truncated = false
+  function walk(index, current) {
+    if (combinations.length >= maxExpansion) {
+      truncated = true
+      return
+    }
+    if (index === names.length) {
+      combinations.push({ ...current })
+      return
+    }
+    for (const value of byName.get(names[index])) {
+      if (combinations.length >= maxExpansion) {
+        truncated = true
+        return
+      }
+      current[names[index]] = value
+      walk(index + 1, current)
+      delete current[names[index]]
+    }
+  }
+  walk(0, {})
+
+  return { combinations, truncated }
+}

package/src/env-text.mjs

@@ -0,0 +1,17 @@
+// env-text:会话任务的 prompt 变量折叠与打码(设计 §4.2 定案:变量折叠进 prompt 文本,
+// 掩码开关默认关)。变量打码与 API 列表打码同源(maskValue)。
+
+// 值打码:长度 ≤4 全打码,否则保留前 2 后 2 中段固定 ***(不泄漏原长度)
+export function maskValue(value) {
+  const text = String(value)
+  if (text.length <= 4) return '***'
+  return text.slice(0, 2) + '***' + text.slice(-2)
+}
+
+// 折叠:变量非空时前置变量段(明文或打码),prompt 主体随后
+export function buildPromptText({ prompt, env, mask }) {
+  const entries = Object.entries(env || {})
+  if (entries.length === 0) return prompt
+  const lines = entries.map(([name, value]) => name + '=' + (mask ? maskValue(value) : value))
+  return '【环境变量】\n' + lines.join('\n') + '\n\n' + prompt
+}

package/src/executor.mjs

@@ -0,0 +1,139 @@
+// executor:执行链共用模块(api 手动运行与 scheduler cron 触发同源)。
+// 预占 RunRecord → 全局/任务级并发闸门(内存队列)→ 执行到终态。
+// 会话任务不展开同名多值(设计 §4.2);shell 任务按启用变量笛卡尔积展开。
+
+import { DEFAULT_MAX_EXPANSION } from './config.mjs'
+import { expandEnvMatrix } from './env-expand.mjs'
+import { createShellRunner } from './shell-runner.mjs'
+
+// 会话执行通道缺失时的兜底:记录 fail 而非让执行链崩溃
+const SESSION_UNAVAILABLE = {
+  run: async () => ({ status: 'fail', message: '会话服务不可用' }),
+}
+
+export function createExecutor({ store, logger, runner, sessionRunner, maxExpansion = DEFAULT_MAX_EXPANSION, readMaxConcurrent, readLogKeep, readMaskEnvInPrompt, logSystem }) {
+  const shellRunner = runner || createShellRunner({ workdirFallback: process.cwd() })
+  // 队列与活跃计数:许可数 = min(全局上限, 任务级收紧值);全局上限经 readMaxConcurrent 动态读
+  const queue = []
+  const activeByJob = new Map()
+  let activeTotal = 0
+
+  function activeOf(jobId) {
+    return activeByJob.get(jobId) || 0
+  }
+
+  function limitOf(job) {
+    const globalLimit = readMaxConcurrent ? readMaxConcurrent() : Infinity
+    const jobLimit = Number.isInteger(job.concurrency) && job.concurrency > 0 ? job.concurrency : Infinity
+    return Math.min(globalLimit, jobLimit)
+  }
+
+  function pump() {
+    for (let i = 0; i < queue.length;) {
+      const item = queue[i]
+      if (activeTotal >= (readMaxConcurrent ? readMaxConcurrent() : Infinity)) break
+      if (activeOf(item.job.id) >= limitOf(item.job)) {
+        i++
+        continue
+      }
+      queue.splice(i, 1)
+      activeTotal++
+      activeByJob.set(item.job.id, activeOf(item.job.id) + 1)
+      // 终态写失败不悬挂:状态留在内存,下次任意写落盘自愈
+      runUnit(item).catch(() => {})
+    }
+  }
+
+  async function runUnit({ job, record, env, runnerFor }) {
+    try {
+      const startedAt = Date.now()
+      await store.runs.update(record.runId, { status: 'running', startedAt })
+      const outcome = await runnerFor(job).run({
+        job,
+        env,
+        mask: readMaskEnvInPrompt ? readMaskEnvInPrompt() : false,
+        logSink: { append: (chunk) => logger.append(job.id, record.runId, chunk) },
+        updateRecord: (patch) => store.runs.update(record.runId, patch),
+      })
+      // 终态补记:session 附带 message/sessionId,pinned 自愈时回写新会话 id
+      const patch = {
+        status: outcome.status,
+        endedAt: Date.now(),
+        durationMs: Date.now() - startedAt,
+      }
+      if (outcome.exitCode !== undefined) patch.exitCode = outcome.exitCode
+      if (outcome.message !== undefined) patch.message = outcome.message
+      if (outcome.sessionId !== undefined) patch.sessionId = outcome.sessionId
+      await store.runs.update(record.runId, patch)
+      // 任务卡状态回填:看板状态点/耗时直接读任务行(手动与 cron 同源更新)
+      const jobPatch = { lastStatus: outcome.status, lastDurationMs: patch.durationMs }
+      if (outcome.pinnedNewId !== undefined) jobPatch.pinnedSessionId = outcome.pinnedNewId
+      await store.jobs.update(job.id, jobPatch)
+    } catch (error) {
+      // runner 拒绝(会话服务异常等)也必须有终态,否则运行记录永久停留 running;
+      // 先读当前态:try 侧已落库终态(部分写成功,如任务卡回填失败)不得覆写,
+      // 任务卡回填改报实际终态;补写失败经 logSystem 留痕(store 损坏时文件日志仍可观测)
+      const detail = error && error.message ? error.message : String(error)
+      const current = store.runs.get(record.runId)
+      const persisted = current !== undefined && current.status !== 'queued' && current.status !== 'running'
+      try {
+        if (!persisted) {
+          await store.runs.update(record.runId, {
+            status: 'fail',
+            endedAt: Date.now(),
+            message: detail,
+          })
+        }
+        await store.jobs.update(job.id, { lastStatus: persisted ? current.status : 'fail' })
+      } catch (persistError) {
+        // 两条路径都留痕(可观测性):未落库=数据面缺口须知晓;已落库=任务卡回填缺口
+        const persistDetail = persistError && persistError.message ? persistError.message : String(persistError)
+        if (persisted) {
+          logSystem?.('cron-board 运行已终态但任务卡回填失败 run=' + record.runId + ' 错误=' + persistDetail)
+        } else {
+          logSystem?.('cron-board 运行终态补写失败 run=' + record.runId + ' 原始错误=' + detail + ' 补写错误=' + persistDetail)
+        }
+      }
+    } finally {
+      activeTotal--
+      activeByJob.set(job.id, activeOf(job.id) - 1)
+      pump()
+      // 终态后按保留策略裁剪该任务旧日志(失败不打断执行链)
+      if (readLogKeep) {
+        await logger.prune(job.id, readLogKeep()).catch(() => {})
+      }
+    }
+  }
+
+  return {
+    // 预占记录并按闸门调度执行;返回 runIds 同步可得(执行在后台按许可推进)
+    async dispatch(job, trigger) {
+      const expansion = job.kind === 'session'
+        ? { combinations: [{}], truncated: false }
+        : expandEnvMatrix({ envs: store.envs.list(), maxExpansion })
+      const combinations = expansion.combinations
+      const runnerFor = job.kind === 'session' ? () => (sessionRunner || SESSION_UNAVAILABLE) : () => shellRunner
+      const records = []
+      for (let i = 0; i < combinations.length; i++) {
+        const record = await store.runs.create({ jobId: job.id, trigger, status: 'queued', logFile: joinLog(job.id) })
+        await store.runs.update(record.runId, { logFile: joinLog(job.id, record.runId) })
+        // 截断不静默:受影响运行记录直接带告警文案
+        if (expansion.truncated) {
+          await store.runs.update(record.runId, { message: '环境变量组合超出上限已截断' })
+        }
+        records.push(record)
+        queue.push({ job, record, env: combinations[i], runnerFor })
+      }
+      pump()
+      return records.map((record) => record.runId)
+    },
+    status() {
+      return { active: activeTotal, queued: queue.length }
+    },
+  }
+}
+
+function joinLog(jobId, runId) {
+  const name = runId === undefined ? 'pending' : runId + '.log'
+  return jobId + '/' + name
+}

package/src/index.js

@@ -0,0 +1,167 @@
+// dsh-cron-board Host 半区:轻量级青龙面板。环境变量集中管理 + 定时任务(cron)调度,
+// 执行体两类:本地脚本(宿主进程内 spawn)与 dsh 会话任务(定时向 dsh 会话投递任务文本)。
+// 模块分层:store(持久化)/ logger(日志)/ executor(执行链)/ scheduler(调度)/ api(路由)。
+// timer 为软依赖(嵌套注入,缺失降级只影响自动调度);settings 缺省时读默认常量。
+
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+import schemastery from '@deepseek-ai/schemastery'
+
+import { createApi } from './api.mjs'
+import { DEFAULT_MAX_CONCURRENT, DEFAULT_TICK_MS, MIN_TICK_MS } from './config.mjs'
+import { createExecutor } from './executor.mjs'
+import { createLogger } from './logger.mjs'
+import { createScheduler } from './scheduler.mjs'
+import { createSessionDriver } from './session-driver.mjs'
+import { createStore } from './store.mjs'
+
+export const name = 'dsh-cron-board'
+
+// 会话任务与路由/定时同为本体能力:sessionController 硬依赖声明交 cordis 门控,
+// 服务未就绪/缺失时 fiber 不激活即整体干净禁用(apply 内同步软探测会撞异步挂载时序,mce 同款事故)
+export const inject = ['webServer', 'sessionController']
+
+// 数据目录 env 覆盖:测试注入临时目录(对齐 dsh-usage-panel 先例)
+const DATA_DIR_ENV = 'DSH_CRON_BOARD_DATA_DIR'
+const API_PREFIX = '/api/cron-board'
+const SETTINGS_NS = 'cron-board'
+const TIMER_UNAVAILABLE_REASON = '宿主定时服务不可用,自动调度已停用'
+const DEFAULT_LOG_KEEP_PER_JOB = 200
+
+// 设置 schema(schemastery 声明式):tick 周期 / 全局并发 / 日志与运行元数据保留份数 / 会话投递变量掩码
+const SETTINGS_SCHEMA = schemastery.object({
+  tickSeconds: schemastery.number().min(MIN_TICK_MS / 1000).step(1).default(DEFAULT_TICK_MS / 1000),
+  maxConcurrent: schemastery.number().min(1).step(1).default(DEFAULT_MAX_CONCURRENT),
+  logKeepPerJob: schemastery.number().min(1).step(1).default(200),
+  maskEnvInPrompt: schemastery.boolean().default(false).description('会话任务投递文本中环境变量打码'),
+})
+
+export function resolveDataDir(env = process.env) {
+  const override = env[DATA_DIR_ENV]
+  if (override && override.trim() !== '') return override.trim()
+  return join(homedir(), '.dsh', 'cron-board')
+}
+
+export function apply(ctx, config) {
+  const sessionController = ctx.sessionController
+  const dataDir = resolveDataDir()
+  // 装配惰性单例:首个请求 / timer 激活触发初始化,各组件只建一次
+  let runtimePromise = null
+  // 生命周期解绑引用:惰性装配完成前给安全空实现,装配后指向真实 scheduler
+  const schedulerRef = { current: { dispose() {} } }
+  const getRuntime = () => {
+    if (runtimePromise === null) {
+      runtimePromise = (async () => {
+        const store = await createStore({ dir: dataDir })
+        const logger = createLogger({ rootDir: join(dataDir, 'logs') })
+        const sessionDriver = createSessionDriver({
+          sessionController,
+          agents: ctx.get('agents'),
+          sessionQuery: ctx.get('sessionQuery'),
+        })
+        const executor = createExecutor({
+          store,
+          logger,
+          sessionRunner: sessionDriver,
+          readMaxConcurrent,
+          readLogKeep: () => readNumber('logKeepPerJob', DEFAULT_LOG_KEEP_PER_JOB),
+          readMaskEnvInPrompt: () => readBoolean('maskEnvInPrompt', false),
+          logSystem: (line) => (ctx.logger && ctx.logger.warn ? ctx.logger.warn(line) : undefined),
+        })
+        const scheduler = createScheduler({ store, executor, readTickMs })
+        schedulerRef.current = scheduler
+        await scheduler.recover()
+        const api = createApi({
+          store,
+          logger,
+          executor,
+          scheduler,
+          periodic,
+          logSystem: (line) => (ctx.logger && ctx.logger.warn ? ctx.logger.warn(line) : undefined),
+        })
+        return { api, scheduler }
+      })()
+      runtimePromise.catch(() => {})
+    }
+    return runtimePromise
+  }
+
+  const periodic = { running: false, reason: null }
+  let armTick = null
+  let disposeTick = null
+
+  function readNumber(name, fallback) {
+    const value = readSettingValue(name)
+    return typeof value === 'number' && Number.isFinite(value) ? value : fallback
+  }
+  function readBoolean(name, fallback) {
+    const value = readSettingValue(name)
+    return typeof value === 'boolean' ? value : fallback
+  }
+  function readSettingValue(name) {
+    const settings = ctx.get('settings')
+    const scope = settings && settings.get ? settings.get(SETTINGS_NS) : undefined
+    return scope ? scope[name] : undefined
+  }
+  function readTickMs() {
+    return Math.max(MIN_TICK_MS, readNumber('tickSeconds', DEFAULT_TICK_MS / 1000) * 1000)
+  }
+  function readMaxConcurrent() {
+    return readNumber('maxConcurrent', DEFAULT_MAX_CONCURRENT)
+  }
+
+  ctx.inject(['timer'], (tctx) => {
+    if (typeof tctx.interval !== 'function') {
+      periodic.reason = TIMER_UNAVAILABLE_REASON
+      return () => {}
+    }
+    armTick = () => {
+      if (disposeTick) disposeTick()
+      disposeTick = tctx.interval(() => {
+        getRuntime()
+          .then((runtime) => runtime.scheduler.tick())
+          .catch((error) => {
+            if (ctx.logger && ctx.logger.warn) ctx.logger.warn('[cron-board] 调度 tick 失败: ' + String(error && error.stack || error))
+          })
+      }, readTickMs())
+    }
+    armTick()
+    periodic.running = true
+    return () => {
+      if (disposeTick) disposeTick()
+      disposeTick = null
+      periodic.running = false
+    }
+  })
+
+  ctx.inject(['settings'], (sctx) => {
+    if (typeof sctx.settings.register !== 'function') return
+    const scope = sctx.settings.register(SETTINGS_NS, SETTINGS_SCHEMA, { base: config })
+    // tick 周期等设置变更即时对账(重建 interval)
+    if (scope && typeof scope.watch === 'function') {
+      scope.watch(() => { if (armTick && periodic.running) armTick() })
+    }
+  })
+
+  ctx.effect(
+    () => ctx.webServer.register({
+      kind: 'prefix',
+      path: API_PREFIX,
+      handler: async (req, res) => {
+        try {
+          const runtime = await getRuntime()
+          await runtime.api.handle(req, res)
+        } catch (error) {
+          res.writeHead(400, { 'content-type': 'application/json; charset=utf-8' })
+          res.end(JSON.stringify({ error: '操作失败(系统级错误,详见服务端日志)' }))
+          if (ctx.logger && ctx.logger.warn) ctx.logger.warn('[cron-board] ' + String(error && error.stack || error))
+        }
+      },
+    }),
+    'cron-board api',
+  )
+
+  // defer 挂起定时器随插件生命周期回收,不遗留生命周期外触发
+  ctx.effect(() => () => schedulerRef.current.dispose(), 'cron-board scheduler lifecycle')
+}

package/src/logger.mjs

@@ -0,0 +1,82 @@
+// logger:每次运行一个日志文件,按任务分目录 logs/<jobId>/<runId>.log;
+// 裁剪按文件数(与运行记录元数据同生命周期语义),删除任务连带整目录。
+
+import { mkdir, open, readdir, readFile, rm, stat, truncate, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+const LOG_EXT = '.log'
+// tail 读取安全上限:单行超长时最多读文件尾部字节窗口,防一次性读入超大日志
+const TAIL_READ_BYTES = 512 * 1024
+
+function logPath(rootDir, jobId, runId) {
+  return join(rootDir, jobId, runId + LOG_EXT)
+}
+
+export function createLogger({ rootDir }) {
+  return {
+    append(jobId, runId, chunk) {
+      const file = logPath(rootDir, jobId, runId)
+      return mkdir(join(rootDir, jobId), { recursive: true }).then(() => {
+        // stdout/stderr 合流顺序写入,追加语义
+        return writeFile(file, chunk, { flag: 'a', encoding: 'utf8' })
+      })
+    },
+    async read(jobId, runId, { tailLines } = {}) {
+      const file = logPath(rootDir, jobId, runId)
+      let text
+      try {
+        if (tailLines === undefined) {
+          text = await readFile(file, 'utf8')
+        } else {
+          const handle = await open(file, 'r')
+          try {
+            const { size } = await handle.stat()
+            const window = Math.min(size, TAIL_READ_BYTES)
+            const buffer = Buffer.alloc(window)
+            await handle.read(buffer, 0, window, size - window)
+            text = buffer.toString('utf8')
+          } finally {
+            await handle.close()
+          }
+        }
+      } catch (error) {
+        if (error && error.code === 'ENOENT') return ''
+        throw error
+      }
+      if (tailLines === undefined) return text
+      const lines = text.split('\n')
+      if (lines.length > 0 && lines[lines.length - 1] === '') lines.pop()
+      return lines.slice(-tailLines).join('\n') + (lines.length > 0 ? '\n' : '')
+    },
+    async clear(jobId, runId) {
+      // 清空 = 内容清零而非删除:文件存在性保持稳定,读路径无需区分「从未运行」与「已清空」
+      await truncate(logPath(rootDir, jobId, runId), 0).catch((error) => {
+        if (!(error && error.code === 'ENOENT')) throw error
+      })
+    },
+    // 按文件修改时间保留最新 keep 份(runId 为随机 UUID 与时间无关,禁用名字典序)
+    async prune(jobId, keep) {
+      const dir = join(rootDir, jobId)
+      let names
+      try {
+        names = await readdir(dir)
+      } catch (error) {
+        if (error && error.code === 'ENOENT') return
+        throw error
+      }
+      const logs = names.filter((name) => name.endsWith(LOG_EXT))
+      const withTime = await Promise.all(logs.map(async (name) => {
+        const info = await stat(join(dir, name)).catch(() => null)
+        return { name, mtimeMs: info ? info.mtimeMs : 0 }
+      }))
+      withTime.sort((a, b) => a.mtimeMs - b.mtimeMs)
+      const stale = withTime.slice(0, Math.max(0, withTime.length - keep))
+      for (const item of stale) {
+        await rm(join(dir, item.name), { force: true })
+      }
+    },
+    async removeJob(jobId) {
+      await rm(join(rootDir, jobId), { recursive: true, force: true })
+    },
+  }
+}

package/src/scheduler.mjs

@@ -0,0 +1,99 @@
+// scheduler:单一调度循环。tick 固定四步——扫描到期、先推进 nextRunAt 再执行、
+// 经执行链闸门入队、超时与收尾由执行链负责。misfire 语义:错过触发点超过一个
+// tick 周期即视为停机期间错过,不补跑,记 skipped 并推进(轻量取舍,设计 §4.1)。
+
+import { nextRunAtOf } from './cron.mjs'
+import { hasWindow, inWindow, nextWindowStart } from './session-window.mjs'
+
+const SKIPPED_MISFIRE_MESSAGE = '停机期间错过'
+const SKIPPED_WINDOW_MESSAGE = '窗口外跳过'
+const INTERRUPTED_MESSAGE = 'dsh 重启中断'
+
+export function createScheduler({ store, executor, readTickMs, now = () => Date.now(), scheduleAt = (at, fn) => setTimeout(fn, Math.max(0, at - now())) }) {
+  // 重入闸门:上一 tick 未完成(store 写链排队/慢盘)时跳过本轮,防同一触发点双触发
+  let ticking = false
+  // defer 挂起句柄登记:dispose 统一清除,不遗留生命周期外触发
+  const deferredCancels = new Set()
+
+  // 重启孤儿收尾:上次进程遗留的 queued/running 统一标 interrupted,不误标失败
+  async function recover() {
+    for (const run of [...store.runs.rows]) {
+      if (run.status !== 'queued' && run.status !== 'running') continue
+      await store.runs.update(run.runId, { status: 'interrupted', endedAt: now(), message: INTERRUPTED_MESSAGE })
+    }
+  }
+
+  // defer 到点回调:按 id 重读任务,已删/已停/会话形态变化一律放弃(不吃旧快照)
+  function armDeferred(jobId, at) {
+    const handle = scheduleAt(at, () => {
+      deferredCancels.delete(cancel)
+      void (async () => {
+        const job = store.jobs.get(jobId)
+        if (!job || !job.enabled || job.kind !== 'session' || !hasWindow(job.session)) return
+        if (inWindow(job.session, new Date(now()))) await executor.dispatch(job, 'cron')
+      })().catch(() => {})
+    })
+    // 句柄取消形态归一:函数直接调,定时器对象走 clearTimeout
+    const cancel = typeof handle === 'function' ? handle : () => clearTimeout(handle)
+    deferredCancels.add(cancel)
+  }
+
+  async function tick() {
+    if (ticking) return
+    ticking = true
+    try {
+      const nowMs = now()
+      const graceMs = readTickMs()
+      for (const job of store.jobs.list()) {
+        if (!job.enabled) continue
+        if (typeof job.nextRunAt !== 'number' || Number.isNaN(job.nextRunAt)) continue
+        if (job.nextRunAt > nowMs) continue
+        // misfire 判定须在推进前读取到期值(update 会原地改写任务对象)
+        const dueAt = job.nextRunAt
+        const misfired = nowMs - dueAt > graceMs
+        // 先推进再执行:执行慢或并发堵不引发重复触发
+        const nextAt = nextRunAtOf(job.schedule, new Date(nowMs))
+        await store.jobs.update(job.id, { nextRunAt: nextAt, lastRunAt: nowMs })
+        if (misfired) {
+          await store.runs.create({ jobId: job.id, trigger: 'cron', status: 'skipped', message: SKIPPED_MISFIRE_MESSAGE })
+          continue
+        }
+        // 会话任务窗口:窗口外按 onMiss 跳过或顺延至窗口起点(defer 挂起不持久化,重启按 skip)
+        if (job.kind === 'session' && hasWindow(job.session) && !inWindow(job.session, new Date(nowMs))) {
+          if (job.session.onMiss === 'defer') {
+            armDeferred(job.id, nextWindowStart(job.session, new Date(nowMs)).getTime())
+          } else {
+            await store.runs.create({ jobId: job.id, trigger: 'cron', status: 'skipped', message: SKIPPED_WINDOW_MESSAGE })
+          }
+          continue
+        }
+        await executor.dispatch(job, 'cron')
+      }
+    } finally {
+      ticking = false
+    }
+  }
+
+  function dispose() {
+    for (const cancel of deferredCancels) {
+      try { cancel() } catch { /* 句柄已自行失效即无清理需求 */ }
+    }
+    deferredCancels.clear()
+  }
+
+  // 下次触发预览:启用任务中最小的 nextRunAt(面板状态展示用)
+  function nextRunAt() {
+    const dueList = store.jobs
+      .list((job) => job.enabled && typeof job.nextRunAt === 'number' && !Number.isNaN(job.nextRunAt))
+      .map((job) => job.nextRunAt)
+    return dueList.length > 0 ? Math.min(...dueList) : null
+  }
+
+  return {
+    recover,
+    tick,
+    dispose,
+    status: () => executor.status(),
+    nextRunAt,
+  }
+}