@mzzsfy/dsh-cron-board 0.1.0

package/test/scheduler.test.mjs

@@ -0,0 +1,383 @@
+// scheduler 测试:到期触发 / misfire / 孤儿收尾 / 重复触发防护(设计 §4.1、§7 BDD 调度组)。
+// 虚拟时钟:now 注入,虚拟时间推进驱动 tick。
+
+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'
+import { createScheduler } from '../src/scheduler.mjs'
+
+const TICK_MS = 30 * 1000
+
+// 可控 runner:执行挂起直到测试放行
+function stubRunner() {
+  const pending = []
+  return {
+    pending,
+    releaseAll(status = 'success') {
+      while (pending.length > 0) pending.shift()({ status, exitCode: 0 })
+    },
+    run() {
+      return new Promise((resolve) => { pending.push(resolve) })
+    },
+  }
+}
+
+async function makeScheduler(t, { maxConcurrent = 2 } = {}) {
+  const dir = await mkdtemp(join(tmpdir(), 'cron-board-sched-'))
+  // Windows 下并行测试时 Defender/索引器短暂锁目录,rmdir 报瞬态 EBUSY,有界重试消解
+  t.after(() => rm(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 }))
+  const store = await createStore({ dir })
+  const logger = createLogger({ rootDir: join(dir, 'logs') })
+  const runner = stubRunner()
+  const executor = createExecutor({ store, logger, runner, readMaxConcurrent: () => maxConcurrent })
+  let nowMs = Date.now()
+  const scheduler = createScheduler({
+    store,
+    executor,
+    readTickMs: () => TICK_MS,
+    now: () => nowMs,
+  })
+  return {
+    store,
+    runner,
+    scheduler,
+    advance: (ms) => { nowMs += ms },
+    now: () => nowMs,
+  }
+}
+
+test('scheduler:到期触发产生 cron RunRecord 且 nextRunAt 先推进', async (t) => {
+  // Given 启用任务 nextRunAt 刚过期(宽限内)
+  const { store, runner, scheduler, advance } = await makeScheduler(t)
+  const job = await store.jobs.create({
+    name: '签到', kind: 'shell', command: 'echo hi', schedule: '30 8 * * *',
+    enabled: true, timeoutMs: 60 * 1000, nextRunAt: Date.now() + TICK_MS,
+  })
+  advance(TICK_MS + 1000)
+  // When 时钟到达触发点后的首个 tick
+  await scheduler.tick()
+  // Then 记录预占且 nextRunAt 已推进到未来(先于执行完成)
+  const rows = store.runs.list(job.id)
+  assert.equal(rows.length, 1)
+  assert.equal(rows[0].trigger, 'cron')
+  const updated = store.jobs.get(job.id)
+  assert.ok(updated.nextRunAt > Date.now())
+  assert.ok(updated.lastRunAt > 0)
+  // Then 执行放行后状态流转到 success(等执行单元真正开始再放行,终态写轮询等待)
+  await waitFor(() => (runner.pending.length > 0 ? true : null))
+  runner.releaseAll()
+  const finished = await waitFor(() => {
+    const record = store.runs.get(rows[0].runId)
+    return record && record.status !== 'queued' && record.status !== 'running' ? record : null
+  })
+  assert.equal(finished.status, 'success')
+})
+
+test('scheduler:同一触发点连续两次 tick 不重复触发', async (t) => {
+  const { store, runner, scheduler, advance } = await makeScheduler(t)
+  const job = await store.jobs.create({
+    name: 'j', kind: 'shell', command: 'x', schedule: '* * * * *',
+    enabled: true, timeoutMs: 1000, nextRunAt: Date.now() + 100,
+  })
+  advance(200)
+  // When 未再推进时钟连续两次 tick
+  await scheduler.tick()
+  await scheduler.tick()
+  // Then 仅一次触发(nextRunAt 首次 tick 已推进)
+  assert.equal(store.runs.list(job.id).length, 1)
+  // 收尾:等执行单元开始并放行到终态,再删临时目录
+  await waitFor(() => (runner.pending.length > 0 ? true : null))
+  runner.releaseAll()
+  await waitFor(() => {
+    const rows2 = store.runs.list(job.id)
+    return rows2.length === 1 && rows2[0].status !== 'queued' && rows2[0].status !== 'running' ? true : null
+  })
+})
+
+test('scheduler:停机期间错过不补跑,记 skipped 且推进到未来', async (t) => {
+  // Given nextRunAt 过期远超一个 tick 周期
+  const { store, scheduler, advance } = await makeScheduler(t)
+  const job = await store.jobs.create({
+    name: 'j', kind: 'shell', command: 'x', schedule: '0 23 * * *',
+    enabled: true, timeoutMs: 1000, nextRunAt: Date.now(),
+  })
+  advance(TICK_MS * 10)
+  // When tick
+  await scheduler.tick()
+  // Then skipped(message=停机期间错过)且 nextRunAt 在未来,未执行
+  const rows = store.runs.list(job.id)
+  assert.equal(rows.length, 1)
+  assert.equal(rows[0].status, 'skipped')
+  assert.equal(rows[0].message, '停机期间错过')
+  assert.ok(store.jobs.get(job.id).nextRunAt > Date.now())
+})
+
+test('scheduler:禁用任务不触发', async (t) => {
+  const { store, scheduler, advance } = await makeScheduler(t)
+  const job = await store.jobs.create({
+    name: 'j', kind: 'shell', command: 'x', schedule: '* * * * *',
+    enabled: false, timeoutMs: 1000, nextRunAt: Date.now() - 1000,
+  })
+  advance(TICK_MS + 1000)
+  await scheduler.tick()
+  assert.equal(store.runs.list(job.id).length, 0)
+})
+
+test('scheduler:recover 将遗留 queued/running 孤儿记录标 interrupted', async (t) => {
+  // Given runs.json 遗留 queued 与 running 记录(上次进程遗留)
+  const { store, scheduler } = await makeScheduler(t)
+  await store.runs.create({ runId: 'r-queued', jobId: 'j1', trigger: 'cron', status: 'queued' })
+  await store.runs.create({ runId: 'r-running', jobId: 'j1', trigger: 'cron', status: 'running' })
+  await store.runs.create({ runId: 'r-done', jobId: 'j1', trigger: 'cron', status: 'success' })
+  // When 重启恢复
+  await scheduler.recover()
+  // Then 孤儿标 interrupted(message=dsh 重启中断),终态记录不动
+  assert.equal(store.runs.get('r-queued').status, 'interrupted')
+  assert.equal(store.runs.get('r-queued').message, 'dsh 重启中断')
+  assert.equal(store.runs.get('r-running').status, 'interrupted')
+  assert.equal(store.runs.get('r-done').status, 'success')
+})
+
+test('scheduler:并发闸门——maxConcurrent=1 时第二个单元排队,首个完成后推进', async (t) => {
+  // Given 两个任务同时到期,全局并发 1
+  const { store, runner, scheduler, advance } = await makeScheduler(t, { maxConcurrent: 1 })
+  const j1 = await store.jobs.create({
+    name: 'j1', kind: 'shell', command: 'x', schedule: '* * * * *',
+    enabled: true, timeoutMs: 1000, nextRunAt: Date.now() + 100,
+  })
+  const j2 = await store.jobs.create({
+    name: 'j2', kind: 'shell', command: 'x', schedule: '* * * * *',
+    enabled: true, timeoutMs: 1000, nextRunAt: Date.now() + 100,
+  })
+  await advance(200)
+  await scheduler.tick()
+  // 等第一组真正开始(链上写排空后才调 runner.run)
+  await waitFor(() => (runner.pending.length > 0 ? true : null))
+  // Then 仅第一个进入 running,第二个 queued
+  assert.equal(runner.pending.length, 1)
+  assert.equal(store.runs.list(j1.id)[0].status, 'running')
+  assert.equal(store.runs.list(j2.id)[0].status, 'queued')
+  // When 首个放行
+  runner.releaseAll()
+  await waitFor(() => (runner.pending.length > 0 ? true : null))
+  // Then 第二个获得许可进入 running
+  assert.equal(runner.pending.length, 1)
+  assert.equal(store.runs.list(j2.id)[0].status, 'running')
+  // 收尾:等终态写落定再删临时目录
+  runner.releaseAll()
+  await waitFor(() => {
+    const rows2 = [...store.runs.list(j1.id), ...store.runs.list(j2.id)]
+    return rows2.every((row) => row.status !== 'queued' && row.status !== 'running') ? true : null
+  })
+})
+
+test('scheduler:任务级 concurrency 收紧全局上限', async (t) => {
+  // Given 单任务同名多值两组展开,全局并发 2,任务级 concurrency=1
+  const { store, runner, scheduler, advance } = await makeScheduler(t, { maxConcurrent: 2 })
+  await store.envs.create({ name: 'A', value: '1', enabled: true })
+  await store.envs.create({ name: 'A', value: '2', enabled: true })
+  const job = await store.jobs.create({
+    name: 'j', kind: 'shell', command: 'x', schedule: '* * * * *',
+    enabled: true, timeoutMs: 1000, concurrency: 1, nextRunAt: Date.now() + 100,
+  })
+  advance(200)
+  await scheduler.tick()
+  // 等第一组真正开始(链上写排空后才调 runner.run)
+  await waitFor(() => (runner.pending.length > 0 ? true : null))
+  // Then 同任务仅一组并行
+  assert.equal(runner.pending.length, 1)
+  assert.equal(store.runs.list(job.id).length, 2)
+  runner.releaseAll()
+  await waitFor(() => (runner.pending.length > 0 ? true : null))
+  assert.equal(runner.pending.length, 1)
+  // 收尾:等终态写落定再删临时目录
+  runner.releaseAll()
+  await waitFor(() => {
+    const rows2 = store.runs.list(job.id)
+    return rows2.every((row) => row.status !== 'queued' && row.status !== 'running') ? true : null
+  })
+})
+
+test('scheduler:status 报告活跃与队列深度', async (t) => {
+  const { scheduler } = await makeScheduler(t)
+  assert.deepEqual(scheduler.status(), { active: 0, queued: 0 })
+})
+
+test('scheduler:窗口内正常发起,窗口外 skip 记录且节奏不变', async (t) => {
+  // Given 会话任务窗口 09:00-23:00,onMiss=skip,注入会话 runner 桩
+  const dir = await mkdtemp(join(tmpdir(), 'cron-board-win-'))
+  t.after(() => rm(dir, { recursive: true, force: true }))
+  const store = await createStore({ dir })
+  const logger = createLogger({ rootDir: join(dir, 'logs') })
+  const sessionRuns = []
+  const sessionRunner = { run: async () => { sessionRuns.push(1); return { status: 'success' } } }
+  const executor = createExecutor({ store, logger, sessionRunner, readMaxConcurrent: () => 2 })
+  // 虚拟时钟锚定今日 08:00(窗口外)
+  const base = new Date(); base.setHours(8, 0, 0, 0)
+  let nowMs = base.getTime()
+  const scheduler = createScheduler({ store, executor, readTickMs: () => TICK_MS, now: () => nowMs })
+  const job = await store.jobs.create({
+    name: 'w', kind: 'session', prompt: '早报', schedule: '0 8 * * *', enabled: true,
+    timeoutMs: 60 * 1000, session: { mode: 'fresh', windowStart: '09:00', windowEnd: '23:00', onMiss: 'skip' },
+  })
+  await store.jobs.update(job.id, { nextRunAt: nowMs })
+  // When tick(触发点 08:00,窗口外)
+  await scheduler.tick()
+  // Then skipped(窗口外跳过),未发起,节奏正常推进(明日 08:00)
+  const rows = store.runs.list(job.id)
+  assert.equal(rows.length, 1)
+  assert.equal(rows[0].status, 'skipped')
+  assert.equal(rows[0].message, '窗口外跳过')
+  assert.equal(sessionRuns.length, 0)
+  const tomorrow8 = new Date(base); tomorrow8.setDate(tomorrow8.getDate() + 1)
+  assert.equal(store.jobs.get(job.id).nextRunAt, tomorrow8.getTime())
+})
+
+test('scheduler:窗口外 defer 挂起至窗口起点后发起', async (t) => {
+  const dir = await mkdtemp(join(tmpdir(), 'cron-board-defer-'))
+  t.after(() => rm(dir, { recursive: true, force: true }))
+  const store = await createStore({ dir })
+  const logger = createLogger({ rootDir: join(dir, 'logs') })
+  const sessionRuns = []
+  const sessionRunner = { run: async () => { sessionRuns.push(1); return { status: 'success' } } }
+  const executor = createExecutor({ store, logger, sessionRunner, readMaxConcurrent: () => 2 })
+  // defer 定时桩:捕获 (at, fn),测试手动放行
+  const deferred = []
+  const base = new Date(); base.setHours(8, 0, 0, 0)
+  let nowMs = base.getTime()
+  const scheduler = createScheduler({
+    store, executor, readTickMs: () => TICK_MS, now: () => nowMs,
+    scheduleAt: (at, fn) => { deferred.push({ at, fn }) },
+  })
+  const job = await store.jobs.create({
+    name: 'w', kind: 'session', prompt: '早报', schedule: '0 8 * * *', enabled: true,
+    timeoutMs: 60 * 1000, session: { mode: 'fresh', windowStart: '09:00', windowEnd: '23:00', onMiss: 'defer' },
+  })
+  await store.jobs.update(job.id, { nextRunAt: nowMs })
+  // When tick(窗口外 defer)
+  await scheduler.tick()
+  // Then 立即不发起,挂起点 = 今日 09:00
+  assert.equal(sessionRuns.length, 0)
+  assert.equal(deferred.length, 1)
+  const at = new Date(deferred[0].at)
+  assert.equal(at.getHours(), 9)
+  assert.equal(at.getMinutes(), 0)
+  // When 挂起到点放行(真实时钟推进到窗口起点,重读后窗口内才发起)
+  nowMs = at.getTime()
+  deferred[0].fn()
+  await tickMillis(50)
+  // Then 发起会话
+  assert.equal(sessionRuns.length, 1)
+  // 且 cron 节奏不变(明日 08:00)
+  const tomorrow8 = new Date(base); tomorrow8.setDate(tomorrow8.getDate() + 1)
+  assert.equal(store.jobs.get(job.id).nextRunAt, tomorrow8.getTime())
+})
+
+test('scheduler:窗口外 defer 到点重读任务——已禁用任务放弃发起(不吃旧快照)', async (t) => {
+  const dir = await mkdtemp(join(tmpdir(), 'cron-board-defer2-'))
+  t.after(() => rm(dir, { recursive: true, force: true }))
+  const store = await createStore({ dir })
+  const logger = createLogger({ rootDir: join(dir, 'logs') })
+  const sessionRuns = []
+  const sessionRunner = { run: async () => { sessionRuns.push(1); return { status: 'success' } } }
+  const executor = createExecutor({ store, logger, sessionRunner, readMaxConcurrent: () => 2 })
+  const deferred = []
+  const base = new Date(); base.setHours(8, 0, 0, 0)
+  let nowMs = base.getTime()
+  const scheduler = createScheduler({
+    store, executor, readTickMs: () => TICK_MS, now: () => nowMs,
+    scheduleAt: (at, fn) => { deferred.push({ at, fn }); return () => {} },
+  })
+  const job = await store.jobs.create({
+    name: 'w', kind: 'session', prompt: '早报', schedule: '0 8 * * *', enabled: true,
+    timeoutMs: 60 * 1000, session: { mode: 'fresh', windowStart: '09:00', windowEnd: '23:00', onMiss: 'defer' },
+  })
+  await store.jobs.update(job.id, { nextRunAt: nowMs })
+  await scheduler.tick()
+  assert.equal(deferred.length, 1)
+  // When 挂起期间任务被禁用,到点放行
+  await store.jobs.update(job.id, { enabled: false })
+  deferred[0].fn()
+  await tickMillis(50)
+  // Then 不发起
+  assert.equal(sessionRuns.length, 0)
+})
+
+test('scheduler:dispose 清除未到点的 defer 挂起(生命周期外零触发)', async (t) => {
+  const dir = await mkdtemp(join(tmpdir(), 'cron-board-defer3-'))
+  t.after(() => rm(dir, { recursive: true, force: true }))
+  const store = await createStore({ dir })
+  const logger = createLogger({ rootDir: join(dir, 'logs') })
+  const sessionRuns = []
+  const sessionRunner = { run: async () => { sessionRuns.push(1); return { status: 'success' } } }
+  const executor = createExecutor({ store, logger, sessionRunner, readMaxConcurrent: () => 2 })
+  const deferred = []
+  const cancels = []
+  const base = new Date(); base.setHours(8, 0, 0, 0)
+  let nowMs = base.getTime()
+  const scheduler = createScheduler({
+    store, executor, readTickMs: () => TICK_MS, now: () => nowMs,
+    scheduleAt: (at, fn) => { deferred.push({ at, fn }); cancels.push(0); return () => { cancels[cancels.length - 1] = 1 } },
+  })
+  const job = await store.jobs.create({
+    name: 'w', kind: 'session', prompt: '早报', schedule: '0 8 * * *', enabled: true,
+    timeoutMs: 60 * 1000, session: { mode: 'fresh', windowStart: '09:00', windowEnd: '23:00', onMiss: 'defer' },
+  })
+  await store.jobs.update(job.id, { nextRunAt: nowMs })
+  await scheduler.tick()
+  // When dispose 后再放行挂起回调
+  scheduler.dispose()
+  assert.equal(cancels[0], 1)
+  deferred[0].fn()
+  await tickMillis(50)
+  // Then 不发起
+  assert.equal(sessionRuns.length, 0)
+})
+
+test('scheduler:tick 重入闸门——上一轮未完成时下一轮直接跳过(防同点双触发)', async (t) => {
+  const { store, runner, scheduler, advance } = await makeScheduler(t)
+  await store.jobs.create({
+    name: '单发', kind: 'shell', command: 'echo hi', schedule: '*/5 * * * *',
+    enabled: true, timeoutMs: 60 * 1000, nextRunAt: Date.now() + TICK_MS,
+  })
+  advance(TICK_MS + 1000)
+  // When 同一 tick 未完成时并发发起第二次 tick(store 写链让首 tick 至少跨越一个微任务)
+  const first = scheduler.tick()
+  const second = scheduler.tick()
+  await Promise.all([first, second])
+  // Then 仅预占一条运行记录
+  const rows = store.runs.list()
+  assert.equal(rows.length, 1)
+  await waitFor(() => (runner.pending.length > 0 ? true : null))
+  runner.releaseAll()
+})
+
+async function tickMillis(ms) {
+  await new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+// 轮询等待:超时抛错(链上写时长不定,固定 sleep 不可靠)
+function waitFor(pick, timeoutMs = 10 * 1000) {
+  return new Promise((resolve, reject) => {
+    const started = Date.now()
+    const tick = () => {
+      const value = pick()
+      if (value) {
+        resolve(value)
+        return
+      }
+      if (Date.now() - started > timeoutMs) {
+        reject(new Error('waitFor 超时'))
+        return
+      }
+      setTimeout(tick, 20)
+    }
+    tick()
+  })
+}

package/test/session-driver.test.mjs

@@ -0,0 +1,161 @@
+// session-driver 测试:HostApiDriver 会话编排语义(设计 §4.3、§7 BDD 会话组)。
+// 桩替 sessionController/agents/sessionQuery,验证 fresh/pinned/忙跳过/丢失自愈/超时/完成判定。
+
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { setTimeout as delay } from 'node:timers/promises'
+
+import { createSessionDriver } from '../src/session-driver.mjs'
+
+// 可控桩:会话注册表 + 控制器(autoIdle 模拟宿主投递后处理完成转 idle;超时场景关掉)
+function makeStubs({ autoIdle = true } = {}) {
+  const sessions = new Map()
+  let nextId = 0
+  const created = []
+  const prompts = []
+  const sessionController = {
+    async create({ cwd } = {}) {
+      const sessionId = 's-' + (++nextId)
+      sessions.set(sessionId, { id: sessionId, cwd, status: 'running' })
+      created.push({ sessionId, cwd })
+      return { sessionId }
+    },
+    async prompt(args) {
+      prompts.push(args)
+      if (autoIdle) {
+        queueMicrotask(() => {
+          const entry = sessions.get(args.sessionId)
+          if (entry) entry.status = 'idle'
+        })
+      }
+      return { accepted: true }
+    },
+  }
+  const agents = {
+    get: (id) => sessions.get(id),
+  }
+  const sessionQuery = {
+    async listSessions() {
+      return [...sessions.values()].map((entry) => ({ id: entry.id }))
+    },
+  }
+  return { sessions, created, prompts, sessionController, agents, sessionQuery }
+}
+
+function makeDriver(stubs, overrides = {}) {
+  return createSessionDriver({
+    sessionController: stubs.sessionController,
+    agents: stubs.agents,
+    sessionQuery: stubs.sessionQuery,
+    pollIntervalMs: 5,
+    ...overrides,
+  })
+}
+
+const BASE_JOB = { id: 'j1', kind: 'session', prompt: '跑日报', session: { mode: 'fresh' }, timeoutMs: 60 * 1000 }
+const PINNED_S1 = { ...BASE_JOB, session: { mode: 'pinned', pinnedSessionId: 's-1' } }
+const PINNED_GONE = { ...BASE_JOB, session: { mode: 'pinned', pinnedSessionId: 'gone' } }
+
+test('session-driver:fresh 每次新建,两次触发不同 sessionId', async () => {
+  const stubs = makeStubs()
+  const driver = makeDriver(stubs)
+  // When 同一 fresh 任务发起两次
+  const first = await driver.run({ job: BASE_JOB, env: {} })
+  const second = await driver.run({ job: BASE_JOB, env: {} })
+  // Then 两个不同会话,均被投递
+  assert.notEqual(first.sessionId, second.sessionId)
+  assert.equal(stubs.created.length, 2)
+  assert.equal(stubs.prompts.length, 2)
+  assert.equal(first.status, 'success')
+})
+
+test('session-driver:pinned 复用同一会话,投递指向 S1', async () => {
+  const stubs = makeStubs()
+  stubs.sessions.set('s-1', { id: 's-1', status: 'idle' })
+  const driver = makeDriver(stubs)
+  // When pinned 任务触发
+  const outcome = await driver.run({ job: PINNED_S1, env: {} })
+  // Then 向 S1 投递且 outcome.sessionId=S1
+  assert.equal(outcome.status, 'success')
+  assert.equal(outcome.sessionId, 's-1')
+  assert.equal(stubs.prompts[0].sessionId, 's-1')
+  assert.equal(stubs.prompts[0].mode, 'queue')
+  assert.equal(stubs.created.length, 0)
+})
+
+test('session-driver:pinned 忙时跳过,不投递', async () => {
+  const stubs = makeStubs()
+  stubs.sessions.set('s-1', { id: 's-1', status: 'running' })
+  const driver = makeDriver(stubs)
+  // When pinned 会话正在运行
+  const outcome = await driver.run({ job: PINNED_S1, env: {} })
+  // Then skipped(上一轮仍在进行)且未新建未投递
+  assert.equal(outcome.status, 'skipped')
+  assert.equal(outcome.message, '上一轮仍在进行')
+  assert.equal(stubs.prompts.length, 0)
+  assert.equal(stubs.created.length, 0)
+})
+
+test('session-driver:pinned 会话丢失自愈:新建并回写', async () => {
+  const stubs = makeStubs()
+  const driver = makeDriver(stubs)
+  // When pinned 指向的会话不存在
+  const outcome = await driver.run({ job: PINNED_GONE, env: {} })
+  // Then 新建会话顶替,message 含「原会话丢失已重建」
+  assert.equal(outcome.status, 'success')
+  assert.equal(outcome.pinnedNewId, 's-1')
+  assert.ok(String(outcome.message).includes('原会话丢失已重建'))
+  assert.equal(stubs.created.length, 1)
+})
+
+test('session-driver:投递被拒绝记 fail', async () => {
+  const stubs = makeStubs()
+  stubs.sessionController.prompt = async () => ({ accepted: false })
+  const driver = makeDriver(stubs)
+  const outcome = await driver.run({ job: BASE_JOB, env: {} })
+  assert.equal(outcome.status, 'fail')
+  assert.ok(outcome.message)
+})
+
+test('session-driver:发起成功即写 RunRecord.sessionId', async () => {
+  const stubs = makeStubs()
+  const driver = makeDriver(stubs)
+  const updates = []
+  // When 发起(updateRecord 回调捕获)
+  await driver.run({ job: BASE_JOB, env: {}, updateRecord: (patch) => updates.push(patch) })
+  // Then sessionId 在完成等待前已写入
+  assert.ok(updates.some((patch) => typeof patch.sessionId === 'string' && patch.sessionId !== ''))
+})
+
+test('session-driver:会话 idle 即完成(success)', async () => {
+  const stubs = makeStubs()
+  const driver = makeDriver(stubs)
+  // When 发起后把会话置 idle(模拟完成)
+  const pending = driver.run({ job: BASE_JOB, env: {} })
+  await delay(30)
+  const sessionId = stubs.created[0].sessionId
+  stubs.sessions.get(sessionId).status = 'idle'
+  const outcome = await pending
+  // Then success 且 RunRecord.sessionId 已写
+  assert.equal(outcome.status, 'success')
+  assert.equal(outcome.sessionId, sessionId)
+})
+
+test('session-driver:timeoutMs 到点记 timeout', async () => {
+  // 会话持续 running(autoIdle 关),轮询到超时
+  const stubs = makeStubs({ autoIdle: false })
+  const driver = makeDriver(stubs, { pollIntervalMs: 5 })
+  const outcome = await driver.run({ job: { ...BASE_JOB, timeoutMs: 40 }, env: {} })
+  assert.equal(outcome.status, 'timeout')
+})
+
+test('session-driver:prompt 携带变量折叠文本', async () => {
+  const stubs = makeStubs()
+  const driver = makeDriver(stubs)
+  // When 带环境变量发起
+  await driver.run({ job: BASE_JOB, env: { CITY: 'hangzhou' }, mask: false })
+  // Then 投递文本含 prompt 与变量段
+  const text = stubs.prompts[0].content[0].text
+  assert.ok(text.includes('跑日报'))
+  assert.ok(text.includes('CITY=hangzhou'))
+})

package/test/shell-runner.test.mjs

@@ -0,0 +1,87 @@
+// ShellRunner 测试:child_process 真实 spawn,跨平台用 node -e 构造用例。
+
+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 { createShellRunner } from '../src/shell-runner.mjs'
+
+// 便捷断言:等待执行结束并收集日志
+async function runAndCollect(runner, { command, env, timeoutMs, workdir }) {
+  const chunks = []
+  const outcome = await runner.run({
+    job: { command, workdir, timeoutMs: timeoutMs ?? 10 * 1000 },
+    env: env || {},
+    logSink: { append: (chunk) => { chunks.push(chunk) } },
+  })
+  return { outcome, log: chunks.join('') }
+}
+
+test('shell-runner:命令成功退出码 0 记 success,输出进日志', async (t) => {
+  const dir = await mkdtemp(join(tmpdir(), 'cron-board-runner-'))
+  t.after(() => rm(dir, { recursive: true, force: true }))
+  const runner = createShellRunner({ workdirFallback: dir })
+  // When 执行成功命令
+  const { outcome, log } = await runAndCollect(runner, { command: `${process.execPath} -e "console.log('marker-ok')"` })
+  // Then success 且日志含输出
+  assert.equal(outcome.status, 'success')
+  assert.equal(outcome.exitCode, 0)
+  assert.match(log, /marker-ok/)
+})
+
+test('shell-runner:非零退出记 fail 并保留退出码', async (t) => {
+  const dir = await mkdtemp(join(tmpdir(), 'cron-board-runner-'))
+  t.after(() => rm(dir, { recursive: true, force: true }))
+  const runner = createShellRunner({ workdirFallback: dir })
+  // When 执行 exit 3
+  const { outcome, log } = await runAndCollect(runner, { command: `${process.execPath} -e "process.stderr.write('bad'); process.exit(3)"` })
+  // Then fail 且 stderr 合流入日志
+  assert.equal(outcome.status, 'fail')
+  assert.equal(outcome.exitCode, 3)
+  assert.match(log, /bad/)
+})
+
+test('shell-runner:环境变量注入叠加 process.env 基础之上', async (t) => {
+  const dir = await mkdtemp(join(tmpdir(), 'cron-board-runner-'))
+  t.after(() => rm(dir, { recursive: true, force: true }))
+  const runner = createShellRunner({ workdirFallback: dir })
+  // When 注入 CB_TEST_VAR 并回读 env 与基础 PATH
+  const { log } = await runAndCollect(runner, {
+    command: `${process.execPath} -e "console.log('V=' + process.env.CB_TEST_VAR); console.log('HAS_PATH=' + Boolean(process.env.PATH))"`,
+    env: { CB_TEST_VAR: 'injected' },
+  })
+  // Then 注入值可见且基础 env 未丢
+  assert.match(log, /V=injected/)
+  assert.match(log, /HAS_PATH=true/)
+})
+
+test('shell-runner:workdir 作为子进程 cwd', async (t) => {
+  const dir = await mkdtemp(join(tmpdir(), 'cron-board-runner-'))
+  t.after(() => rm(dir, { recursive: true, force: true }))
+  const runner = createShellRunner({ workdirFallback: dir })
+  // When 声明 workdir 执行回显 cwd
+  const { log } = await runAndCollect(runner, {
+    command: `${process.execPath} -e "console.log(process.cwd())"`,
+    workdir: dir,
+  })
+  // Then cwd 即声明目录
+  assert.match(log, new RegExp(dir.replace(/[/\\]/g, '[/\\\\]')))
+})
+
+test('shell-runner:超时终止进程记 timeout', async (t) => {
+  const dir = await mkdtemp(join(tmpdir(), 'cron-board-runner-'))
+  t.after(() => rm(dir, { recursive: true, force: true }))
+  const runner = createShellRunner({ workdirFallback: dir })
+  // When 运行长任务且 timeoutMs 极短
+  const started = Date.now()
+  const { outcome, log } = await runAndCollect(runner, {
+    command: `${process.execPath} -e "console.log('started'); setTimeout(() => {}, 60000)"`,
+    timeoutMs: 500,
+  })
+  // Then timeout 且进程被提前终止
+  assert.equal(outcome.status, 'timeout')
+  assert.ok(Date.now() - started < 30 * 1000)
+  assert.match(log, /started/)
+})