@mzzsfy/dsh-cron-board 0.1.0

package/src/session-driver.mjs

@@ -0,0 +1,82 @@
+// session-driver:HostApiDriver 会话编排(设计 §4.3,生产实现唯一)。
+// 发起 = 新建/复用会话 + queue 投递;完成判定 = agents 状态脱离 running(轮询 + timeoutMs 收尾);
+// pinned 忙跳过、丢失自愈、发起成功即写 RunRecord.sessionId。变量折叠与掩码由 env 文本构造承担。
+
+import { randomUUID } from 'node:crypto'
+
+import { buildPromptText } from './env-text.mjs'
+
+const BUSY_MESSAGE = '上一轮仍在进行'
+const RECREATED_MESSAGE = '原会话丢失已重建'
+const REJECTED_MESSAGE = '会话输入投递被拒绝'
+
+const DEFAULT_TIMEOUT_MS = 60 * 60 * 1000
+
+export function createSessionDriver({ sessionController, agents, sessionQuery, pollIntervalMs = 2 * 1000, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), now = () => Date.now() }) {
+  // pinned 会话存在性:持久层 headers 比对(冷会话不在 agents 注册表)
+  async function pinnedExists(sessionId) {
+    if (!sessionQuery || typeof sessionQuery.listSessions !== 'function') return Boolean(agents.get(sessionId))
+    const records = await sessionQuery.listSessions()
+    return records.some((record) => record && record.id === sessionId)
+  }
+
+  async function run({ job, env, mask, updateRecord }) {
+    const session = job.session || {}
+    const isPinned = session.mode === 'pinned'
+    let sessionId = isPinned ? session.pinnedSessionId : null
+    let recreated = false
+
+    if (isPinned) {
+      // pinned 串行:上轮未完成直接跳过(不排队)
+      const entry = agents ? agents.get(sessionId) : undefined
+      if (entry && entry.status === 'running') {
+        return { status: 'skipped', message: BUSY_MESSAGE }
+      }
+      if (!sessionId || !(await pinnedExists(sessionId))) {
+        recreated = true
+      }
+    }
+
+    if (recreated || !isPinned) {
+      const created = await sessionController.create(job.workdir ? { cwd: job.workdir } : undefined)
+      sessionId = created.sessionId
+    }
+
+    const submission = await sessionController.prompt({
+      requestId: randomUUID(),
+      sessionId,
+      mode: 'queue',
+      content: [{ type: 'text', text: buildPromptText({ prompt: job.prompt || '', env, mask }) }],
+    })
+    if (!submission || submission.accepted !== true) {
+      return { status: 'fail', message: REJECTED_MESSAGE, sessionId }
+    }
+    if (typeof updateRecord === 'function') {
+      await updateRecord({ sessionId })
+    }
+
+    // 完成等待:状态脱离 running 即结算,timeoutMs 到点收尾
+    const timeoutMs = Number.isInteger(job.timeoutMs) && job.timeoutMs > 0 ? job.timeoutMs : DEFAULT_TIMEOUT_MS
+    const deadline = now() + timeoutMs
+    while (now() < deadline) {
+      const entry = agents ? agents.get(sessionId) : undefined
+      if (!entry || entry.status !== 'running') {
+        return {
+          status: 'success',
+          sessionId,
+          ...(recreated ? { pinnedNewId: sessionId, message: RECREATED_MESSAGE } : {}),
+        }
+      }
+      await sleep(pollIntervalMs)
+    }
+    return {
+      status: 'timeout',
+      sessionId,
+      ...(recreated ? { pinnedNewId: sessionId, message: RECREATED_MESSAGE + ';超时未完成' } : {}),
+    }
+  }
+
+  return {
+    run,
+  }
+}

package/src/session-window.mjs

@@ -0,0 +1,37 @@
+// session-window:会话任务时间窗口判定(设计 §4.3)。start>=end 视为跨零点(如 22:00-06:00)。
+
+const MINUTES_PER_DAY = 24 * 60
+
+function parseMinutes(hhmm) {
+  const [hours, minutes] = String(hhmm).split(':').map((part) => parseInt(part, 10))
+  return hours * 60 + minutes
+}
+
+function minutesOfDay(date) {
+  return date.getHours() * 60 + date.getMinutes()
+}
+
+// 触发时刻是否落在窗口内;start>=end 即跨零点区间。session = job.session 子对象
+export function inWindow(session, date) {
+  const start = parseMinutes(session.windowStart)
+  const end = parseMinutes(session.windowEnd)
+  const nowMinutes = minutesOfDay(date)
+  if (start <= end) return nowMinutes >= start && nowMinutes < end
+  return nowMinutes >= start || nowMinutes < end
+}
+
+// 最近的窗口起点时刻(defer 挂起目标):起点未过用今日,已过用明日
+export function nextWindowStart(session, date) {
+  const start = parseMinutes(session.windowStart)
+  const at = new Date(date)
+  at.setSeconds(0, 0)
+  at.setHours(Math.floor(start / 60), start % 60)
+  if (at.getTime() <= date.getTime()) at.setDate(at.getDate() + 1)
+  return at
+}
+
+export function hasWindow(session) {
+  return Boolean(session && session.windowStart && session.windowEnd)
+}
+
+export { MINUTES_PER_DAY }

package/src/shell-runner.mjs

@@ -0,0 +1,71 @@
+// ShellRunner:shell 形式执行 command,stdout/stderr 合流写 logSink(日志文件即执行现场);
+// 环境变量注入叠加 process.env 基础之上;超时强制终止进程树记 timeout。
+// Windows 下 shell:true 生成 cmd.exe 包装进程,直接 kill 不杀孙进程且管道不关闭,
+// 须按平台杀整棵进程树:Windows taskkill /T,POSIX detached 进程组信号。
+
+import { spawn } from 'node:child_process'
+
+const KILL_GRACE_MS = 5 * 1000
+
+const isWindows = process.platform === 'win32'
+
+// 杀整棵进程树;调用方保证 child 仍在运行
+function killTree(child) {
+  if (isWindows) {
+    spawn('taskkill', ['/T', '/F', '/PID', String(child.pid)], { stdio: 'ignore' })
+    return
+  }
+  try {
+    process.kill(-child.pid, 'SIGTERM')
+  } catch {
+    child.kill('SIGKILL')
+  }
+}
+
+export function createShellRunner({ workdirFallback }) {
+  return {
+    run({ job, env, logSink }) {
+      return new Promise((resolve) => {
+        const child = spawn(job.command, {
+          shell: true,
+          cwd: job.workdir || workdirFallback,
+          env: { ...process.env, ...env },
+          detached: !isWindows,
+        })
+        let timedOut = false
+        let timeoutGuard
+
+        const onChunk = (chunk) => {
+          logSink.append(chunk.toString('utf8'))
+        }
+        child.stdout.on('data', onChunk)
+        child.stderr.on('data', onChunk)
+
+        if (job.timeoutMs > 0) {
+          timeoutGuard = setTimeout(() => {
+            timedOut = true
+            logSink.append('\n[cron-board] 运行超时,强制终止\n')
+            killTree(child)
+            // 终止宽限兜底:树未被清干净时直接 SIGKILL 兜底(POSIX;Windows /F 已强杀)
+            setTimeout(() => {
+              if (child.exitCode === null && child.signalCode === null) child.kill('SIGKILL')
+            }, KILL_GRACE_MS)
+          }, job.timeoutMs)
+        }
+
+        child.on('error', (error) => {
+          clearTimeout(timeoutGuard)
+          logSink.append('\n[cron-board] 进程启动失败: ' + String(error) + '\n')
+          resolve({ status: 'fail', exitCode: null })
+        })
+        child.on('close', (code) => {
+          clearTimeout(timeoutGuard)
+          resolve({
+            status: timedOut ? 'timeout' : code === 0 ? 'success' : 'fail',
+            exitCode: code,
+          })
+        })
+      })
+    },
+  }
+}

package/src/status-meta.mjs

@@ -0,0 +1,16 @@
+// status-meta:运行状态五态+中断的展示元数据(core 侧单一事实源)。
+// client.js LOGIC 段镜像此表,parity 测试锁定(双实现同源规约)。
+
+export const STATUS_META = {
+  success: { label: '成功', tone: 'ok' },
+  fail: { label: '失败', tone: 'bad' },
+  timeout: { label: '超时', tone: 'warn' },
+  skipped: { label: '跳过', tone: 'mute' },
+  interrupted: { label: '中断', tone: 'mute' },
+  running: { label: '运行中', tone: 'run' },
+}
+
+export const TRIGGER_META = {
+  cron: { label: '定时' },
+  manual: { label: '手动' },
+}

package/src/store.mjs

@@ -0,0 +1,195 @@
+// store:envs/jobs/runs 三份 JSON 的原子读写。读走内存缓存,写经进程内互斥链串行化,
+// 单次写 = 临时文件 + 改名(原子替换);坏文件备份 .bak 后拒绝该集合写入,防空 store 覆盖。
+
+import { randomUUID } from 'node:crypto'
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+
+const BAK_SUFFIX = '.bak'
+const TMP_SUFFIX = '.tmp'
+
+// Windows 下对刚写入目标的替换 rename 会报瞬态 EACCES/EBUSY/EPERM(Defender/索引器短暂锁定),
+// 有界重试消解;节奏镜像官方 dsh-atomic-write 的同名处理
+const RETRY_INITIAL_MS = 20
+const RETRY_MAX_MS = 200
+const RETRY_LIMIT = 8
+
+function isTransientRenameError(error) {
+  return process.platform === 'win32' && ['EACCES', 'EBUSY', 'EPERM'].includes(error && error.code)
+}
+
+async function renameWithRetry(temp, file) {
+  let delay = RETRY_INITIAL_MS
+  for (let attempt = 0; ; attempt++) {
+    try {
+      await rename(temp, file)
+      return
+    } catch (error) {
+      if (!isTransientRenameError(error) || attempt >= RETRY_LIMIT) throw error
+    }
+    await new Promise((resolve) => setTimeout(resolve, delay))
+    delay = Math.min(delay * 2, RETRY_MAX_MS)
+  }
+}
+
+// 每任务运行记录元数据保留上限:超限裁最旧,防 runs.json 无界增长
+export const RUNS_KEEP_PER_JOB = 200
+
+function isMissing(error) {
+  return Boolean(error) && error.code === 'ENOENT'
+}
+
+// 单集合持久化:加载/读缓存/互斥链写。所有集合经 link 容器共享一条写链(link.chain 重绑),
+// 保证跨文件写序与进程内串行;损坏标记集合级隔离:单文件损坏只禁该集合写,其余集合不受连坐
+function createCollection({ file, link, idKey }) {
+  let rows = []
+  let loaded = false
+  let broken = false
+
+  function assertUsable() {
+    if (broken) throw new Error('数据文件已损坏已备份,已暂停写入以防数据丢失: ' + file)
+  }
+
+  async function persistLocked() {
+    await mkdir(dirname(file), { recursive: true })
+    const tmp = file + TMP_SUFFIX
+    await writeFile(tmp, JSON.stringify(rows), 'utf8')
+    await renameWithRetry(tmp, file)
+  }
+
+  return {
+    get rows() {
+      return rows
+    },
+    async load() {
+      if (loaded) return
+      loaded = true
+      try {
+        const text = await readFile(file, 'utf8')
+        const parsed = JSON.parse(text)
+        if (Array.isArray(parsed)) rows = parsed
+      } catch (error) {
+        if (!isMissing(error)) {
+          broken = true
+          await rename(file, file + BAK_SUFFIX).catch(() => {})
+        }
+      }
+    },
+    list(filter) {
+      const source = filter ? rows.filter(filter) : rows
+      // 对外浅拷贝:防调用方原地修改污染内存态(mutate 以 Object.assign 原地生效)
+      return source.map((row) => ({ ...row }))
+    },
+    get(id) {
+      const row = rows.find((item) => item[idKey] === id)
+      return row ? { ...row } : undefined
+    },
+    // 读改写经共享互斥链串行化;链上失败不传播到后续写,调用方 await 本次结果感知单次失败
+    mutate(fn) {
+      assertUsable()
+      const result = link.chain.then(async () => {
+        const outcome = await fn(rows)
+        if (outcome !== false) await persistLocked()
+        return outcome
+      })
+      link.chain = result.catch(() => {})
+      return result
+    },
+    async create(data) {
+      const now = Date.now()
+      const row = {
+        ...data,
+        [idKey]: data[idKey] || randomUUID(),
+        createdAt: now,
+        updatedAt: now,
+      }
+      await this.mutate((list) => {
+        list.push(row)
+      })
+      return row
+    },
+    async update(id, patch) {
+      let updated
+      await this.mutate((list) => {
+        const row = list.find((item) => item[idKey] === id)
+        if (row === undefined) return false
+        Object.assign(row, patch, { updatedAt: Date.now() })
+        updated = row
+      })
+      return updated
+    },
+    async remove(id) {
+      let removed = false
+      await this.mutate((list) => {
+        const index = list.findIndex((item) => item[idKey] === id)
+        if (index < 0) return false
+        list.splice(index, 1)
+        removed = true
+      })
+      return removed
+    },
+  }
+}
+
+export async function createStore({ dir }) {
+  const link = { chain: Promise.resolve() }
+  const makeFile = (name) => join(dir, name)
+
+  const envs = createCollection({ file: makeFile('envs.json'), link, idKey: 'id' })
+  const jobsBase = createCollection({ file: makeFile('jobs.json'), link, idKey: 'id' })
+  const runs = createCollection({ file: makeFile('runs.json'), link, idKey: 'runId' })
+  await Promise.all([envs.load(), jobsBase.load(), runs.load()])
+
+  // 任务删除连带清除其运行记录(日志目录由调用方连带清理)
+  const jobs = {
+    get rows() {
+      return jobsBase.rows
+    },
+    load: () => jobsBase.load(),
+    list: (filter) => jobsBase.list(filter),
+    get: (id) => jobsBase.get(id),
+    mutate: (fn) => jobsBase.mutate(fn),
+    create: (data) => jobsBase.create(data),
+    update: (id, patch) => jobsBase.update(id, patch),
+    async remove(id) {
+      const removed = await jobsBase.remove(id)
+      if (!removed) return false
+      await runs.mutate((list) => {
+        const keep = list.filter((row) => row.jobId !== id)
+        list.length = 0
+        list.push(...keep)
+      })
+      return true
+    },
+  }
+
+  // 运行记录创建:同一任务超出保留上限时裁掉最旧(数组头部新,尾部旧)
+  async function createRun(data) {
+    const row = await runs.create(data)
+    await runs.mutate((list) => {
+      const mine = list.filter((item) => item.jobId === row.jobId)
+      const excess = mine.length - RUNS_KEEP_PER_JOB
+      if (excess <= 0) return false
+      const staleIds = new Set(mine.slice(0, excess).map((item) => item.runId))
+      const keep = list.filter((item) => !(item.jobId === row.jobId && staleIds.has(item.runId)))
+      list.length = 0
+      list.push(...keep)
+    })
+    return row
+  }
+
+  return {
+    envs,
+    jobs,
+    runs: {
+      get rows() {
+        return runs.rows
+      },
+      list: (jobId) => (jobId ? runs.list((row) => row.jobId === jobId) : runs.list()),
+      get: (runId) => runs.get(runId),
+      create: createRun,
+      update: (runId, patch) => runs.update(runId, patch),
+      remove: (runId) => runs.remove(runId),
+    },
+  }
+}

package/test/env-expand.test.mjs

@@ -0,0 +1,101 @@
+// 环境变量同名多值展开测试(青龙多账号语义,设计 §4.2)。
+
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { expandEnvMatrix } from '../src/env-expand.mjs'
+
+test('env-expand:同名多值展开为笛卡尔积,单值名称每组携带', () => {
+  // Given 启用变量 A=1/A=2(同名多值)与 B=x
+  const envs = [
+    { name: 'A', value: '1', enabled: true },
+    { name: 'A', value: '2', enabled: true },
+    { name: 'B', value: 'x', enabled: true },
+  ]
+  // When 展开
+  const { combinations, truncated } = expandEnvMatrix({ envs, maxExpansion: 20 })
+  // Then 两组:第一次 A=1,B=x;第二次 A=2,B=x
+  assert.equal(truncated, false)
+  assert.deepEqual(combinations, [
+    { A: '1', B: 'x' },
+    { A: '2', B: 'x' },
+  ])
+})
+
+test('env-expand:禁用变量不注入', () => {
+  // Given 含禁用变量 C=3
+  const envs = [
+    { name: 'A', value: '1', enabled: true },
+    { name: 'C', value: '3', enabled: false },
+  ]
+  // When 展开
+  const { combinations } = expandEnvMatrix({ envs, maxExpansion: 20 })
+  // Then C 不出现
+  assert.deepEqual(combinations, [{ A: '1' }])
+})
+
+test('env-expand:空集合产出单组空组合,shell 任务无变量也可运行', () => {
+  // Given 无启用变量
+  // When 展开
+  const { combinations } = expandEnvMatrix({ envs: [], maxExpansion: 20 })
+  // Then 一组空组合
+  assert.deepEqual(combinations, [{}])
+})
+
+test('env-expand:组合数超上限截断并标记', () => {
+  // Given 三个名称各 4 个启用值 = 64 组,上限 20
+  const names = ['A', 'B', 'C']
+  const envs = []
+  for (const name of names) {
+    for (let i = 1; i <= 4; i++) envs.push({ name, value: String(i), enabled: true })
+  }
+  // When 展开
+  const { combinations, truncated } = expandEnvMatrix({ envs, maxExpansion: 20 })
+  // Then 仅前 20 组且 truncated=true
+  assert.equal(combinations.length, 20)
+  assert.equal(truncated, true)
+})
+
+test('env-expand:大组合限量生成,不物化指数级全量', () => {
+  // Given 两个名称各 30 值 = 900 组,上限 10
+  const envs = []
+  for (const name of ['A', 'B']) {
+    for (let i = 1; i <= 30; i++) envs.push({ name, value: String(i), enabled: true })
+  }
+  // When 展开
+  const { combinations, truncated } = expandEnvMatrix({ envs, maxExpansion: 10 })
+  // Then 恰好 10 组且每组结构完整(前缀组合,而非部分展开的残缺组)
+  assert.equal(truncated, true)
+  assert.equal(combinations.length, 10)
+  for (const row of combinations) {
+    assert.ok(row.A !== undefined && row.B !== undefined)
+  }
+})
+
+test('env-expand:multi 行按换行拆值,空行与首尾空白剔除', () => {
+  // Given 单行 multi 存储形态(客户端 values 数组经 API 折叠为换行拼接)
+  const envs = [
+    { name: 'TOKEN', value: 'aaa\n\n bbb \n', multi: true, enabled: true },
+    { name: 'MODE', value: 'run', enabled: true },
+  ]
+  // When 展开
+  const { combinations, truncated } = expandEnvMatrix({ envs, maxExpansion: 20 })
+  // Then 拆出两值,单值名称每组携带
+  assert.equal(truncated, false)
+  assert.deepEqual(combinations, [
+    { TOKEN: 'aaa', MODE: 'run' },
+    { TOKEN: 'bbb', MODE: 'run' },
+  ])
+})
+
+test('env-expand:multi 行与同名单行合并贡献组合', () => {
+  // Given multi 行两值 + 同名单行一值
+  const envs = [
+    { name: 'A', value: '1\n2', multi: true, enabled: true },
+    { name: 'A', value: '3', enabled: true },
+  ]
+  // When 展开
+  const { combinations } = expandEnvMatrix({ envs, maxExpansion: 20 })
+  // Then 三组按序
+  assert.deepEqual(combinations.map((row) => row.A), ['1', '2', '3'])
+})

package/test/executor.test.mjs

@@ -0,0 +1,107 @@
+// executor 执行链 BDD:runner 拒绝的终态收尾与部分写失败下的历史保护。
+// 场景对应 runUnit catch:补写不覆写已落库终态、补写失败经 logSystem 留痕。
+
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { createStore } from '../src/store.mjs'
+import { createLogger } from '../src/logger.mjs'
+import { createExecutor } from '../src/executor.mjs'
+
+async function makeExecutor(t, { jobsBroken = false, logLines = [] } = {}) {
+  const dir = await mkdtemp(join(tmpdir(), 'cron-board-exec-'))
+  // Windows 下并行测试时 Defender/索引器短暂锁目录,rmdir 报瞬态 EBUSY,有界重试消解
+  t.after(() => rm(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 }))
+  const store = await createStore({ dir: join(dir, 'data') })
+  const logger = createLogger({ rootDir: join(dir, 'logs') })
+  if (jobsBroken) {
+    // 模拟 jobs 集合损坏(mutate 直接拒绝),runs 集合保持健康
+    store.jobs.update = async () => { throw new Error('数据文件已损坏已备份,已暂停写入以防数据丢失') }
+  }
+  const runner = {
+    run: async () => ({ status: 'success', exitCode: 0 }),
+  }
+  const executor = createExecutor({
+    store,
+    logger,
+    runner,
+    readMaxConcurrent: () => 2,
+    logSystem: (line) => logLines.push(line),
+  })
+  return { store, executor, logLines }
+}
+
+const JOB_BASE = { name: 't', kind: 'shell', command: 'echo hi', schedule: '* * * * *', enabled: true, timeoutMs: 60 * 1000 }
+
+async function dispatchAndSettle(executor, store, jobId) {
+  const [runId] = await executor.dispatch({ ...JOB_BASE, id: jobId }, 'manual')
+  // 等执行链收尾:pump 后单元在后台,轮询至终态或超时
+  for (let i = 0; i < 200; i++) {
+    const row = store.runs.get(runId)
+    if (row && row.status !== 'queued' && row.status !== 'running') return runId
+    await new Promise((resolve) => setTimeout(resolve, 10))
+  }
+  return runId
+}
+
+test('executor:正常路径终态 success 且任务卡回填', async (t) => {
+  const { store, executor } = await makeExecutor(t)
+  await store.jobs.create({ ...JOB_BASE, id: 'j1' })
+  const runId = await dispatchAndSettle(executor, store, 'j1')
+  assert.equal(store.runs.get(runId).status, 'success')
+  assert.equal(store.jobs.get('j1').lastStatus, 'success')
+})
+
+test('executor:runner 拒绝时补写 fail 终态', async (t) => {
+  const dir = await mkdtemp(join(tmpdir(), 'cron-board-exec-'))
+  t.after(() => rm(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 }))
+  const store = await createStore({ dir: join(dir, 'data') })
+  const logger = createLogger({ rootDir: join(dir, 'logs') })
+  const logLines = []
+  const executor = createExecutor({
+    store,
+    logger,
+    runner: { run: async () => { throw new Error('会话服务爆炸') } },
+    readMaxConcurrent: () => 2,
+    logSystem: (line) => logLines.push(line),
+  })
+  await store.jobs.create({ ...JOB_BASE, id: 'j2' })
+  const [runId] = await executor.dispatch({ ...JOB_BASE, id: 'j2' }, 'manual')
+  for (let i = 0; i < 200; i++) {
+    const row = store.runs.get(runId)
+    if (row && row.status === 'fail') break
+    await new Promise((resolve) => setTimeout(resolve, 10))
+  }
+  const row = store.runs.get(runId)
+  assert.equal(row.status, 'fail')
+  assert.match(row.message, /会话服务爆炸/)
+  assert.equal(store.jobs.get('j2').lastStatus, 'fail')
+  assert.equal(logLines.length, 0, '补写成功不留痕')
+})
+
+test('executor:运行终态已落库而任务卡回填失败,历史不被覆写', async (t) => {
+  const { store, executor, logLines } = await makeExecutor(t, { jobsBroken: true })
+  await store.jobs.create({ ...JOB_BASE, id: 'j3' })
+  const runId = await dispatchAndSettle(executor, store, 'j3')
+  // Then 事实成功保留,不被 catch 覆写为 fail;回填缺口留痕可观测
+  assert.equal(store.runs.get(runId).status, 'success')
+  assert.equal(logLines.length, 1)
+  assert.ok(logLines[0].includes(runId))
+  assert.ok(logLines[0].includes('任务卡回填失败'))
+})
+
+test('executor:运行终态补写失败经 logSystem 留痕', async (t) => {
+  const { store, executor, logLines } = await makeExecutor(t)
+  await store.jobs.create({ ...JOB_BASE, id: 'j4' })
+  const [runId] = await executor.dispatch({ ...JOB_BASE, id: 'j4' }, 'manual')
+  // dispatch 完成(记录已落库、runUnit 已入队)后再让 runs 集合损坏:终态写入必失败
+  store.runs.update = async () => { throw new Error('数据文件已损坏已备份,已暂停写入以防数据丢失') }
+  await new Promise((resolve) => setTimeout(resolve, 200))
+  // Then 补写失败恰留痕一次,含 runId 与原始错误
+  assert.equal(logLines.length, 1)
+  assert.ok(logLines[0].includes(runId))
+  assert.ok(logLines[0].includes('补写失败'))
+})