@zhushanwen/pi-scheduler 0.1.0 → 0.2.0

package/src/__tests__/runtime.test.ts

@@ -1,30 +1,20 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
-// M11：mock store 模块，避免 SchedulerRuntime 触发真实 FS 写入。
-// 原实现用 new SchedulerRuntime('/test', ...) → createStore('/test') 会写
-// ~/.pi/agent/scheduler/root/test/scheduler.json（store.test.ts:87 stderr 已证实）。
-// mock 后 load 返回空 store、persist/persistSync 为 no-op，runtime 完全不碰 FS。
-vi.mock('../store.js', () => ({
-  createStore: () => ({
-    load: () => ({ version: 1, tasks: [] }),
-    persist: vi.fn(),
-    persistSync: vi.fn(),
-    storePath: '/mocked/scheduler.json',
-  }),
-}))
-
+import { MockSchedulerBackend } from '../backend.js'
 import { SchedulerRuntime } from '../runtime.js'
 
-// Mock pi 和 ctx
-const mockPi = { sendMessage: vi.fn() }
+// MockSchedulerBackend 零 FS 副作用：runtime 不再触碰 store，无需 mock store.js。
+
 const mockCtx = { isIdle: () => true, hasPendingMessages: () => false }
 
 describe('SchedulerRuntime', () => {
+  let backend: MockSchedulerBackend
   let runtime: SchedulerRuntime
 
   beforeEach(() => {
     vi.clearAllMocks()
-    runtime = new SchedulerRuntime('/test', mockPi as never, mockCtx as never)
+    backend = new MockSchedulerBackend()
+    runtime = new SchedulerRuntime(backend, mockCtx)
   })
 
   describe('addTask', () => {
@@ -42,6 +32,11 @@ describe('SchedulerRuntime', () => {
       await expect(runtime.addTask('one more', { mode: 'interval', intervalMs: 60000 }))
         .rejects.toThrow('Task limit reached')
     })
+
+    it('throws for invalid cron expression at creation', async () => {
+      await expect(runtime.addTask('bad cron', { mode: 'cron', cronExpression: 'invalid * *' }))
+        .rejects.toThrow('Invalid cron expression: invalid * *')
+    })
   })
 
   describe('listTasks', () => {
@@ -74,6 +69,22 @@ describe('SchedulerRuntime', () => {
     it('returns false for non-existent task', async () => {
       expect(await runtime.toggleTask('nonexistent', true)).toBe(false)
     })
+
+    it('ERR-2: enable 时 cron 失效 → 停用 + failed + lastError，不落入 ?? now() 死循环', async () => {
+      const task = await runtime.addTask('test', { mode: 'cron', cronExpression: '*/10 * * * *' })
+      await runtime.toggleTask(task.id, false)
+      // 手动破坏 cron 表达式（模拟表达式随环境失效），并让 nextRunAt 过期触发重算
+      task.schedule = { mode: 'cron', cronExpression: 'invalid * *' }
+      task.nextRunAt = 0
+
+      await runtime.toggleTask(task.id, true)
+
+      expect(task.enabled).toBe(false)
+      expect(task.lastStatus).toBe('failed')
+      expect(task.lastError).toBe('cron expression invalid')
+      // nextRunAt 保留原值（0），enabled=false 后 tick 不再触发
+      expect(task.nextRunAt).toBe(0)
+    })
   })
 
   describe('deleteTask', () => {
@@ -91,44 +102,63 @@ describe('SchedulerRuntime', () => {
   describe('dispatchTask', () => {
     it('dispatches task when idle', async () => {
       const task = await runtime.addTask('test', { mode: 'interval', intervalMs: 60000 })
-      runtime.dispatchTask(task)
-      expect(mockPi.sendMessage).toHaveBeenCalledWith(
-        expect.objectContaining({ content: 'test' }),
-        expect.any(Object),
-      )
+      await runtime.dispatchTask(task)
+      expect(backend.sentMessages).toHaveLength(1)
+      expect(backend.sentMessages[0]!.msg).toEqual(expect.objectContaining({ content: 'test' }))
     })
 
     it('skips disabled task', async () => {
       const task = await runtime.addTask('test', { mode: 'interval', intervalMs: 60000 })
       await runtime.toggleTask(task.id, false)
-      runtime.dispatchTask(task)
-      expect(mockPi.sendMessage).not.toHaveBeenCalled()
+      await runtime.dispatchTask(task)
+      expect(backend.sentMessages).toHaveLength(0)
     })
 
     it('skips when not idle and force is false', async () => {
       const busyCtx = { isIdle: () => false, hasPendingMessages: () => false }
-      const busyRuntime = new SchedulerRuntime('/test', mockPi as never, busyCtx as never)
+      const busyBackend = new MockSchedulerBackend()
+      const busyRuntime = new SchedulerRuntime(busyBackend, busyCtx)
       const task = await busyRuntime.addTask('test', { mode: 'interval', intervalMs: 60000 })
-      busyRuntime.dispatchTask(task)
-      expect(mockPi.sendMessage).not.toHaveBeenCalled()
+      await busyRuntime.dispatchTask(task)
+      expect(busyBackend.sentMessages).toHaveLength(0)
     })
 
     it('dispatches when force is true even if busy', async () => {
       const busyCtx = { isIdle: () => false, hasPendingMessages: () => false }
-      const busyRuntime = new SchedulerRuntime('/test', mockPi as never, busyCtx as never)
+      const busyBackend = new MockSchedulerBackend()
+      const busyRuntime = new SchedulerRuntime(busyBackend, busyCtx)
       const task = await busyRuntime.addTask('test', { mode: 'interval', intervalMs: 60000 }, { force: true })
-      busyRuntime.dispatchTask(task)
-      expect(mockPi.sendMessage).toHaveBeenCalled()
+      await busyRuntime.dispatchTask(task)
+      expect(busyBackend.sentMessages).toHaveLength(1)
     })
 
     // OR 组合补全：源码 `!isIdle() || hasPendingMessages()` 任一为真即跳过。
     // idle=true 但有 pending message → dispatch 应被跳过。
     it('skips when idle but has pending messages', async () => {
       const pendingCtx = { isIdle: () => true, hasPendingMessages: () => true }
-      const pendingRuntime = new SchedulerRuntime('/test', mockPi as never, pendingCtx as never)
+      const pendingBackend = new MockSchedulerBackend()
+      const pendingRuntime = new SchedulerRuntime(pendingBackend, pendingCtx)
       const task = await pendingRuntime.addTask('test', { mode: 'interval', intervalMs: 60000 })
-      pendingRuntime.dispatchTask(task)
-      expect(mockPi.sendMessage).not.toHaveBeenCalled()
+      await pendingRuntime.dispatchTask(task)
+      expect(pendingBackend.sentMessages).toHaveLength(0)
+    })
+
+    it('sendMessage 失败 → 记 failed 状态但不 rethrow', async () => {
+      const task = await runtime.addTask('test', { mode: 'interval', intervalMs: 60000 })
+      // backend.sendMessage 抛错模拟注入失败
+      backend.sendMessage = async () => { throw new Error('inject failed') }
+      const dispatched = await runtime.dispatchTask(task)
+      expect(dispatched).toBe(false)
+      expect(task.lastStatus).toBe('failed')
+      expect(task.pending).toBe(false)
+      expect(task.history[task.history.length - 1]!.status).toBe('failed')
+    })
+
+    it('成功 dispatch 后清除 lastError', async () => {
+      const task = await runtime.addTask('test', { mode: 'interval', intervalMs: 60000 })
+      task.lastError = 'cron expression invalid'
+      await runtime.dispatchTask(task)
+      expect(task.lastError).toBeUndefined()
     })
   })
 
@@ -141,6 +171,10 @@ describe('SchedulerRuntime', () => {
       vi.setSystemTime(new Date('2026-01-01T00:00:00Z'))
     })
 
+    afterEach(() => {
+      vi.useRealTimers()
+    })
+
     it('rate-limits dispatch to 6 per minute', async () => {
       // force=true 保证不被 idle/busy 干扰，直接命中 rate-limit
       const tasks: Awaited<ReturnType<typeof runtime.addTask>>[] = []
@@ -154,7 +188,7 @@ describe('SchedulerRuntime', () => {
       }
 
       // 前 6 次成功，第 7 次被限流：sendMessage 只被调 6 次
-      expect(mockPi.sendMessage).toHaveBeenCalledTimes(6)
+      expect(backend.sentMessages).toHaveLength(6)
     })
 
     it('allows dispatch again after 1 minute window slides', async () => {
@@ -164,27 +198,28 @@ describe('SchedulerRuntime', () => {
         // 同一 task 反复 dispatch（interval 模式每次重算 nextRunAt，不影响 rate-limit 计数）
         await runtime.dispatchTask(task)
       }
-      expect(mockPi.sendMessage).toHaveBeenCalledTimes(6)
+      expect(backend.sentMessages).toHaveLength(6)
 
       // 时间前进 61 秒：旧 timestamp 滑出窗口，配额恢复
       vi.setSystemTime(new Date('2026-01-01T00:01:01Z'))
       const dispatched = await runtime.dispatchTask(task)
       expect(dispatched).toBe(true)
-      expect(mockPi.sendMessage).toHaveBeenCalledTimes(7)
+      expect(backend.sentMessages).toHaveLength(7)
     })
   })
 
   // ── M10d：tickScheduler ──
   describe('tickScheduler', () => {
+    beforeEach(() => {
+      vi.useFakeTimers()
+      vi.setSystemTime(new Date('2026-01-01T00:00:00Z'))
+    })
+
     afterEach(() => {
       vi.useRealTimers()
     })
 
     it('dispatches due interval tasks and advances nextRunAt', async () => {
-      vi.useFakeTimers()
-      const start = new Date('2026-01-01T00:00:00Z')
-      vi.setSystemTime(start)
-
       const task = await runtime.addTask('tick me', { mode: 'interval', intervalMs: 60000 })
       // 手动让任务过期（nextRunAt 设为过去）
       task.nextRunAt = Date.now() - 1000
@@ -192,7 +227,7 @@ describe('SchedulerRuntime', () => {
       await runtime.tickScheduler()
 
       // 已 dispatch
-      expect(mockPi.sendMessage).toHaveBeenCalledTimes(1)
+      expect(backend.sentMessages).toHaveLength(1)
       const updated = runtime.getTask(task.id)
       expect(updated).toBeDefined()
       expect(updated!.runCount).toBe(1)
@@ -201,9 +236,6 @@ describe('SchedulerRuntime', () => {
     })
 
     it('removes expired tasks (expiresAt in the past)', async () => {
-      vi.useFakeTimers()
-      vi.setSystemTime(new Date('2026-01-01T00:00:00Z'))
-
       const task = await runtime.addTask('expire me', { mode: 'interval', intervalMs: 60000 })
       // expiresAt 已过：tick 的第 1 步清理会删除
       task.expiresAt = Date.now() - 1000
@@ -212,13 +244,10 @@ describe('SchedulerRuntime', () => {
 
       expect(runtime.getTask(task.id)).toBeUndefined()
       // 过期清理先于 dispatch，不应 dispatch
-      expect(mockPi.sendMessage).not.toHaveBeenCalled()
+      expect(backend.sentMessages).toHaveLength(0)
     })
 
     it('deletes once task after dispatch', async () => {
-      vi.useFakeTimers()
-      vi.setSystemTime(new Date('2026-01-01T00:00:00Z'))
-
       const task = await runtime.addTask('one-shot', { mode: 'interval', intervalMs: 60000 }, { kind: 'once' })
       task.nextRunAt = Date.now() - 1000
 
@@ -226,7 +255,212 @@ describe('SchedulerRuntime', () => {
 
       // once 任务 dispatch 后自删
       expect(runtime.getTask(task.id)).toBeUndefined()
-      expect(mockPi.sendMessage).toHaveBeenCalledTimes(1)
+      expect(backend.sentMessages).toHaveLength(1)
+    })
+
+    // ── TC1：cron 失效任务不死循环 ──
+    // tick1 dispatch 成功、重算 nextRunAt 失败停用；tick2/3 因 enabled=false 不再 dispatch。
+    // 旧实现 `?? Date.now()` 会把 nextRunAt 设为 now → 每 tick 立即重触发 → 死循环。
+    it('TC1: cron 失效任务不死循环（sendMessage 只触发 1 次）', async () => {
+      const task = await runtime.addTask('tick me', { mode: 'cron', cronExpression: '*/10 * * * *' })
+      // 手动把 cron 表达式改为无效（模拟表达式随环境失效），并使任务到期
+      task.schedule = { mode: 'cron', cronExpression: 'invalid * *' }
+      task.nextRunAt = Date.now() - 1000
+
+      // 连跑 3 次 tick
+      await runtime.tickScheduler()
+      await runtime.tickScheduler()
+      await runtime.tickScheduler()
+
+      expect(backend.sentMessages).toHaveLength(1)
+      const updated = runtime.getTask(task.id)
+      expect(updated).toBeDefined()
+      expect(updated!.enabled).toBe(false)
+      expect(updated!.lastStatus).toBe('failed')
+      expect(updated!.lastError).toBe('cron expression invalid')
+    })
+
+    // ── TC-W-APPEND-FAIL：appendEntry 失败捕获（ER-APPEND-FAIL）──
+    it('TC-W-APPEND-FAIL: appendEntry 失败不抛、保留内存态、不污染 lastError', async () => {
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+      backend.appendError = new Error('pi internal')
+
+      // addTask 内 appendEntry 抛错 → 被捕获（console.warn），不 rethrow；内存态已更新（task 仍在）
+      const task = await runtime.addTask('test', { mode: 'interval', intervalMs: 60000 })
+      expect(runtime.getTask(task.id)).toBeDefined()
+      expect(task.enabled).toBe(true)
+      // appendEntrySafe 不污染业务态（append 失败是 transient，不设 lastError）
+      expect(task.lastError).toBeUndefined()
+      expect(warnSpy).toHaveBeenCalled()
+
+      // tickScheduler 同样不抛：dispatch 成功后 append advance 抛错被捕获，nextRunAt 已推进（内存态正确）
+      task.nextRunAt = Date.now() - 1000
+      await expect(runtime.tickScheduler()).resolves.toBeUndefined()
+      const updated = runtime.getTask(task.id)!
+      expect(updated.enabled).toBe(true)
+      expect(updated.runCount).toBe(1)
+      // nextRunAt 已推进到未来（内存态正确，append 失败只丢持久化）
+      expect(updated.nextRunAt).toBe(Date.now() + 60000)
+      expect(updated.lastError).toBeUndefined() // 不被 append 失败污染
+      warnSpy.mockRestore()
+    })
+
+    // ── TC-W-ON-AFTER-TICK：onAfterTick 回调（W2）──
+    it('TC-W-ON-AFTER-TICK: onAfterTick 回调在 tick 完成后被调用 1 次', async () => {
+      const spy = vi.fn()
+      runtime.onAfterTick(spy)
+      await runtime.tickScheduler()
+      expect(spy).toHaveBeenCalledTimes(1)
+    })
+
+    // ── TC-W-ENABLED-FILTER：tickScheduler 步骤3 显式 enabled 过滤（W4）──
+    it('TC-W-ENABLED-FILTER: disabled 且到期的任务不被 dispatch，enabled 到期则 dispatch', async () => {
+      // disabled + 到期
+      const disabled = await runtime.addTask('disabled', { mode: 'interval', intervalMs: 60000 })
+      await runtime.toggleTask(disabled.id, false)
+      disabled.nextRunAt = Date.now() - 1000
+
+      // enabled + 到期（force=true 绕过 idle/busy 检查，隔离 enabled 维度）
+      const enabledTask = await runtime.addTask('enabled', { mode: 'interval', intervalMs: 60000 }, { force: true })
+      enabledTask.nextRunAt = Date.now() - 1000
+
+      await runtime.tickScheduler()
+
+      // 只 dispatch enabled（disabled 被步骤2 不标 pending + 步骤3 +t.enabled 双重过滤）
+      expect(backend.sentMessages).toHaveLength(1)
+      expect(backend.sentMessages[0]!.msg.content).toBe('enabled')
+      // disabled 仍在、未被 dispatch、enabled=false
+      const stillDisabled = runtime.getTask(disabled.id)
+      expect(stillDisabled).toBeDefined()
+      expect(stillDisabled!.enabled).toBe(false)
+      expect(stillDisabled!.runCount).toBe(0)
+    })
+
+    // ── MF-1：toggle enable 重算 nextRunAt 到未来时清除残留 pending ──
+    // 场景：busy tick 标记 pending=true（W4 跨 tick 重试）→ disable → enable 重算到未来。
+    // 修复前 pending 残留 → 下个 tick step3 `pending && enabled` 在重算的未来时间点之前提前 dispatch。
+    it('MF-1: enable 重算 nextRunAt 到未来时清除残留 pending，不提前 dispatch', async () => {
+      // 可控 idle 状态：先 busy 模拟 dispatchTask 跳过保留 pending（W4），后切 idle 排除 busy 干扰
+      let idle = false
+      const controllableCtx = { isIdle: () => idle, hasPendingMessages: () => false }
+      const controllableBackend = new MockSchedulerBackend()
+      const rt = new SchedulerRuntime(controllableBackend, controllableCtx)
+
+      vi.setSystemTime(new Date('2026-01-01T00:00:00Z'))
+      const task = await rt.addTask('mf1', { mode: 'interval', intervalMs: 60000 })
+
+      // T0+61s：任务到期 + busy → step2 标 pending=true，step3 dispatchTask busy 跳过（pending 保留）
+      vi.setSystemTime(new Date('2026-01-01T00:01:01Z'))
+      await rt.tickScheduler()
+      expect(task.pending).toBe(true) // busy tick 残留 pending（W4 跨 tick 重试）
+      expect(controllableBackend.sentMessages).toHaveLength(0)
+
+      // disable → enable：enable 重算 nextRunAt 到未来（T0+61s + 60s = T0+121s）
+      await rt.toggleTask(task.id, false)
+      await rt.toggleTask(task.id, true)
+      expect(task.pending).toBe(false) // 修复后：重算到未来清除残留 pending
+      const recalcedNext = task.nextRunAt
+      expect(recalcedNext).toBeGreaterThan(Date.now()) // 确认重算到了未来
+
+      // T0+90s：在重算的未来 nextRunAt 之前 tick，切 idle 排除 busy 干扰 → 不应 dispatch
+      vi.setSystemTime(new Date('2026-01-01T00:01:30Z'))
+      idle = true
+      await rt.tickScheduler()
+      expect(controllableBackend.sentMessages).toHaveLength(0)
+
+      // 到达重算的未来 nextRunAt 后 tick：才 dispatch
+      vi.setSystemTime(new Date(recalcedNext + 1000))
+      await rt.tickScheduler()
+      expect(controllableBackend.sentMessages).toHaveLength(1)
+    })
+
+    // ── P1：toggle enable 重算的 nextRunAt 跨 session 重放后保持未来值 ──
+    // 场景：addTask → nextRunAt 过期 → disable → enable 重算到未来（内存）→
+    //   新建第二个 SchedulerRuntime + backend.loadTasks() 重放 appendedOps（模拟 resume）→
+    //   重放后 nextRunAt = 重算的未来值（非 upsert 快照旧过期值）+ enabled=true + tick 不立即 dispatch。
+    // 修复前：toggle op 不带 nextRunAt，重放回退到 upsert 快照旧过期值 → 首个 tick 立即 dispatch（跨 session 数据丢失）。
+    it('P1: toggle enable 重算的 nextRunAt 跨 session 重放后保持未来值，不回退到旧过期值', async () => {
+      vi.setSystemTime(new Date('2026-01-01T00:00:00Z'))
+      const task = await runtime.addTask('cross-session', { mode: 'interval', intervalMs: 60000 })
+      const oldNextRunAt = task.nextRunAt // T0+60s（upsert 快照值）
+
+      // T0+120s：nextRunAt(T0+60s) 已过期
+      vi.setSystemTime(new Date('2026-01-01T00:02:00Z'))
+      expect(task.nextRunAt).toBeLessThan(Date.now())
+
+      // disable → enable：enable 重算 nextRunAt 到未来（T0+120s + 60s = T0+180s）
+      await runtime.toggleTask(task.id, false)
+      await runtime.toggleTask(task.id, true)
+      const recalcedNext = task.nextRunAt
+      expect(recalcedNext).toBeGreaterThan(Date.now()) // 内存态已重算到未来
+      expect(recalcedNext).not.toBe(oldNextRunAt) // 确实重算，非旧值
+
+      // 模拟 resume：把第一个 runtime 的 appendedOps 包装成 entries，喂给第二个 backend 重放。
+      // appendedOps = [upsert(T0+60s), toggle(enabled=false), toggle(enabled=true, nextRunAt=T0+180s)]
+      const replayBackend = new MockSchedulerBackend()
+      replayBackend.fakeEntries = backend.appendedOps.map(op => ({
+        type: 'custom',
+        customType: 'pi-scheduler:task',
+        data: op,
+      }))
+      // fakeSessionFile 默认 '/test/session.json'，与第一个 backend 一致 → owner 过滤放行
+      const replayRuntime = new SchedulerRuntime(replayBackend, mockCtx)
+      replayRuntime.loadTasks(replayBackend.loadTasks())
+
+      const replayed = replayRuntime.getTask(task.id)
+      expect(replayed).toBeDefined()
+      expect(replayed!.enabled).toBe(true)
+      // 重放后是重算的未来值（修复核心），非 upsert 快照的旧过期值
+      expect(replayed!.nextRunAt).toBe(recalcedNext)
+      expect(replayed!.nextRunAt).not.toBe(oldNextRunAt)
+
+      // 再 tick 一次（now=T0+120s < 重算 nextRunAt T0+180s）：不应 dispatch。
+      // 修复前此断言会失败：nextRunAt 回退到 oldNextRunAt(T0+60s) < now → 首个 tick 立即触发
+      await replayRuntime.tickScheduler()
+      expect(replayBackend.sentMessages).toHaveLength(0)
+    })
+  })
+
+  // ── TC9：expiresAt 三态（addTask 的 expires 分支）──
+  // 源码逻辑：expires==='never' → undefined；kind==='recurring' 且 expires →
+  // now + parseDuration(expires)（解析失败 ?? 默认 7d）；recurring 无 expires →
+  // 默认 7d；kind==='once' 不进分支 → undefined。
+  // MockSchedulerBackend nowValue 固定为 1_000_000，expiresAt 精确可控。
+  describe('expiresAt', () => {
+    beforeEach(() => {
+      backend.nowValue = 1_000_000
+    })
+
+    it("expires: 'never' → expiresAt undefined", async () => {
+      const task = await runtime.addTask(
+        'test',
+        { mode: 'interval', intervalMs: 60000 },
+        { expires: 'never' },
+      )
+      expect(task.expiresAt).toBeUndefined()
+    })
+
+    it('recurring + expires 30m → now + 1_800_000', async () => {
+      const task = await runtime.addTask(
+        'test',
+        { mode: 'interval', intervalMs: 60000 },
+        { expires: '30m' },
+      )
+      expect(task.expiresAt).toBe(2_800_000)
+    })
+
+    it('recurring + 无 expires → 默认 7d（now + 604_800_000）', async () => {
+      const task = await runtime.addTask('test', { mode: 'interval', intervalMs: 60000 })
+      expect(task.expiresAt).toBe(605_800_000)
+    })
+
+    it("kind once + expires '30m' → expiresAt undefined（once 不设过期）", async () => {
+      const task = await runtime.addTask(
+        'test',
+        { mode: 'interval', intervalMs: 60000 },
+        { kind: 'once', expires: '30m' },
+      )
+      expect(task.expiresAt).toBeUndefined()
     })
   })
 })

package/src/__tests__/sdk-contract.test.ts

@@ -17,18 +17,15 @@
 import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent'
 import { describe, expect, it, vi } from 'vitest'
 
-// Mock store 模块：避免 runtime 触发真实 FS 写入（session_start 会创建 SchedulerRuntime，
-// 进而 createStore(cwd) 写 ~/.pi/agent/scheduler/...）。sdk-contract 只验证注册契约，
-// 不关心持久化，故 store 返回空状态 + no-op persist。
-vi.mock('../store.js', () => ({
-  createStore: () => ({
-    load: () => ({ version: 1, tasks: [] }),
-    persist: vi.fn(),
-    persistSync: vi.fn(),
-    storePath: '/mocked/scheduler.json',
-  }),
-}))
-
+// MF-3：session_start handler 会真实执行 importLegacyStore(ctx.cwd, ...) —— fakeCtx cwd='/test'
+// 会触碰真实用户 FS（~/.pi/agent/scheduler/root/test/scheduler.json 的 renameSync/existsSync/
+// unlinkSync；该目录是活跃数据目录，一旦路径存在会 rename+unlink 真实用户数据且结果不确定）。
+// mock 掉 importer 模块：session_start 装配路径仍被调用（vi.fn 记录调用），FS 副作用为零；
+// 装配时序由 tools/verify-scheduler-e2e.cjs 的 S10/S12/S17 真实环境覆盖。
+// mock 返回 vi.fn() 作为延迟删除 cleanup（MF-1：turn_end / session_shutdown 装配链路可测）。
+vi.mock('../importer.js', () => ({ importLegacyStore: vi.fn(() => vi.fn()) }))
+
+import { importLegacyStore } from '../importer.js'
 import schedulerExtension from '../index.js'
 
 /**
@@ -38,7 +35,11 @@ import schedulerExtension from '../index.js'
 /** 捕获到的 tool definition：只关心我们要断言的字段。 */
 interface CapturedTool {
   name: string
-  execute: (...args: unknown[]) => Promise<Record<string, unknown>>
+  execute: (...args: unknown[]) => Promise<{
+    content: { type: string; text: string }[]
+    details: unknown
+    isError?: boolean
+  }>
   handler?: unknown
   fn?: unknown
   [key: string]: unknown
@@ -58,6 +59,7 @@ function createMockPi(): {
     registerCommand: (name: string, opts: Record<string, unknown>) => commands.push({ name, opts }),
     on: (event: string, handler: (...args: unknown[]) => void) => events.set(event, handler),
     sendMessage: vi.fn(),
+    appendEntry: vi.fn(),
   } as unknown as ExtensionAPI
   return { pi, tools, commands, events }
 }
@@ -72,6 +74,12 @@ function createFakeCtx(): ExtensionContext {
     isIdle: () => true,
     hasPendingMessages: () => false,
     ui: { setWidget: vi.fn() },
+    // append-only 模型：session_start 时 PiSchedulerBackend(ctx, pi) 读 ctx.sessionManager.getEntries()
+    // 折叠恢复任务。fakeCtx 返回空 entries + 固定 sessionFile（无历史任务，等价新 session）。
+    sessionManager: {
+      getEntries: () => [],
+      getSessionFile: () => '/test/session.json',
+    },
   } as unknown as ExtensionContext
 }
 
@@ -145,29 +153,31 @@ describe('pi-scheduler SDK contract', () => {
     expect(result.isError).toBeFalsy()
   })
 
-  it('handler 抛错被 catch 为 isError（而非 throw）—— standards.md §4.2 契约', async () => {
+  it('handler 返回结构化失败被 isError 标记（而非 throw）—— standards.md §4.2 契约', async () => {
     const { pi, tools, events } = createMockPi()
     schedulerExtension(pi)
     const fakeCtx = createFakeCtx()
     await events.get('session_start')!({ type: 'session_start', reason: 'startup' }, fakeCtx)
 
-    // 非法 cron 表达式：parseSchedule 会 reject，handler 抛 'Invalid schedule'，
-    // execute 应 catch 为 isError 而非让 promise reject。
+    // 非法 cron 表达式：service.create 返回 INVALID_SCHEDULE 结构化失败，
+    // handler 返回 isError result（text 为 service message 本体，无 'Error:' 前缀）。
     const result = await tools[0]!.execute('call-err', { prompt: 'x', schedule: 'invalid-cron-expr-xxx' }, undefined, undefined, fakeCtx)
     expect(result.isError).toBe(true)
-    expect(result.content[0].text).toContain('Error:')
+    expect(result.content[0].text).toContain('Invalid schedule')
+    expect(result.content[0].text).not.toContain('Error:')
   })
 
-  it('schedule_control tool 同样 catch handler 错误', async () => {
+  it('schedule_control tool 同样返回结构化 isError', async () => {
     const { pi, tools, events } = createMockPi()
     schedulerExtension(pi)
     const fakeCtx = createFakeCtx()
     await events.get('session_start')!({ type: 'session_start', reason: 'startup' }, fakeCtx)
 
-    // toggle 不存在的 task id：handler 抛 'Task xxx not found'，应被 catch
+    // toggle 不存在的 task id：service 返回 TASK_NOT_FOUND，handler 返回 isError
     const controlTool = tools.find(t => t.name === 'schedule_control')!
     const result = await controlTool.execute('call-ctrl', { action: 'toggle', id: 'deadbeef', enabled: false }, undefined, undefined, fakeCtx)
     expect(result.isError).toBe(true)
+    expect(result.content[0].text).toBe('Task deadbeef not found.')
   })
 
   it('registerCommand 注册了名为 schedule 的命令', () => {
@@ -175,4 +185,29 @@ describe('pi-scheduler SDK contract', () => {
     schedulerExtension(pi)
     expect(commands.map(c => c.name)).toContain('schedule')
   })
+
+  // MF-1（R2）装配链路：session_start → importLegacyStore 返回延迟删除 cleanup；
+  // turn_end 触发 cleanup（主触发点，flush 已发生）；session_shutdown 兜底再调 + 复位。
+  it('MF-1 装配：turn_end / session_shutdown 调用延迟删除 cleanup，importer 仅 session_start 调 1 次', async () => {
+    const { pi, events } = createMockPi()
+    schedulerExtension(pi)
+    const fakeCtx = createFakeCtx()
+
+    // 其他用例也触发 session_start，先清调用记录（mockClear 保留实现）
+    vi.mocked(importLegacyStore).mockClear()
+
+    // session_start → importLegacyStore 调用 1 次，返回 cleanup（新 session 未 flush 延迟删除路径）
+    await events.get('session_start')!({ type: 'session_start', reason: 'startup' }, fakeCtx)
+    expect(importLegacyStore).toHaveBeenCalledTimes(1)
+    const cleanup = vi.mocked(importLegacyStore).mock.results[0]!.value
+    expect(typeof cleanup).toBe('function')
+
+    // turn_end（首个 turn 完成，flush 已发生）→ cleanup 被调用——跨 session 双导入窗口闭合点
+    await events.get('turn_end')!()
+    expect(cleanup).toHaveBeenCalledTimes(1)
+
+    // session_shutdown → 兜底再调一次（覆盖从未产生 turn 的 session），随后复位
+    await events.get('session_shutdown')!()
+    expect(cleanup).toHaveBeenCalledTimes(2)
+  })
 })