@zhushanwen/pi-scheduler 0.1.1 → 0.2.0

package/README.md

@@ -1,6 +1,20 @@
 # scheduler
 
-定时任务调度扩展：按 duration（`5m` / `2h` / `1d`）间隔或 cron 表达式，在指定时间向 agent 注入消息。支持一次性提醒（once）、强制触发（force）、过期策略（expires）与持久化（重启后任务保留）。
+定时任务调度扩展：按 duration（`5m` / `2h` / `1d`）间隔或 cron 表达式，在指定时间向 agent 注入消息。支持一次性提醒（once）、强制触发（force）与过期策略（expires）。任务随 owner session 持久化，resume 后继续触发。
+
+## 产品定位
+
+pi-scheduler 是 **session 存活期间的 AI 提醒器**——在 pi 进程运行、session 打开时，按计划向当前 session 注入消息。
+
+**非系统级 cron**：
+
+- pi 进程不开 = 不触发（与常驻后台的系统 cron daemon 不同，本扩展不是后台守护进程）
+- 电脑睡眠 / 关机 = 不触发
+- 不依赖系统 crontab，不注册任何开机自启
+
+**任务归属创建它的 session**：任务物理存储在创建它的 session 的 JSONL 文件内，**只在 owner session 打开（继续对话 / resume）时才触发**。
+
+> **这是设计决策，不是 bug（D9）**：本扩展从 cwd 级定时器改为 **session 级 AI 提醒器**——任务归属创建它的 session，只在 owner session 存活时触发。如果你每天开新 session，昨天建的"明早检查 CI"任务今天不会响，除非你 resume 昨天创建该任务的那个 session。这不是"任务丢了"：任务随 session 持久化，session 不打开就不调度。**用户若发现「昨天建的任务今天没响」，这是预期行为**，请 resume 创建该任务的 session。
 
 ## 简介与安装
 
@@ -20,15 +34,26 @@ npm install @zhushanwen/pi-scheduler
 
 ```
 session_start
-  └─ PiSchedulerBackend（FS 读写 + pi.sendMessage + 时间源）
-       └─ SchedulerRuntime（内存态 + 30s tick 调度 + 限流）
-            └─ SchedulerService（tool/command 唯一业务入口）
-  ├─ runtime.loadTasks(backend.loadTasks())  ← 从磁盘恢复任务
-  ├─ runtime.startScheduler()                ← 启动 tick
-  └─ 注册 scheduler widget（30s 刷新）
+  ├─ PiSchedulerBackend（pi.sendMessage + 时间源 + appendEntry + getEntries）
+  │    └─ SchedulerRuntime（内存态 + 30s tick 调度 + 限流）
+  │         └─ SchedulerService（tool/command 唯一业务入口）
+  ├─ runtime.loadTasks(replay(getEntries()))  ← 重放 session JSONL 的 custom entry 折叠恢复任务
+  │                                             （仅 ownerSessionFile 匹配的加载，fork 副本被过滤）
+  ├─ runtime.startScheduler()                  ← 启动 30s tick
+  └─ 注册 scheduler widget（每个 tick 后刷新）
 ```
 
-`session_shutdown` 时执行 `runtime.persistSync()`（立即写盘）并停止 tick。任务状态因此随 session 持久化：关闭重开 session 后任务仍存在、到期仍会触发。
+运行时每次状态变更会 append 一条 custom entry 到创建任务的 session 的 JSONL（统一 `customType: pi-scheduler:task`，`op` 字段区分）：
+
+| op | 触发时机 | 携带数据 |
+|----|---------|---------|
+| `upsert` | 创建 / 更新任务 | task 全快照（含 nextRunAt 初值、ownerSessionFile） |
+| `advance` | dispatch 成功后 | 推进后的 nextRunAt、本次执行 at / status |
+| `toggle` | 启用 / 停用 | enabled |
+| `delete` | 删除；once 触发后自动 delete | taskId |
+
+- fork 出的 session 重放时按 `ownerSessionFile` 过滤，不加载、不执行继承的任务副本（原 session resume 照常）
+- `session_shutdown` 停止 tick + 兜底执行延迟删除 cleanup（正常路径已由首个 turn_end 完成）——任务已 append 到 JSONL，无需额外写盘
 
 ## /schedule 命令用法
 
@@ -93,7 +118,7 @@ session_start
 |------|------|------|
 | `kind` | `recurring`（默认）/ `once` | recurring 每次触发后按 schedule 重算下次时间；once 触发一次后自动删除 |
 | `name` | 字符串 | 任务可读名称，缺省从 prompt 自动生成（≤30 字原样，超长截前 27 字加省略号） |
-| `expires` | duration 字符串 / `never` | recurring 任务的过期时间：`now + duration`；`never` 永不过期；缺省 7 天。**once 任务不设过期**（触发即删，expires 忽略） |
+| `expires` | duration 字符串 / `never` | recurring 任务的过期时间：`now + duration`；`never` 永不过期；缺省 7 天。**once 任务忽略 expires 参数**（触发即删，传不传都不生效） |
 | `force` | `true` / `false`（默认） | `true` 时即使 agent 忙（非 idle 或有 pending 消息）也强制 dispatch；`false` 时忙则延迟到下次 tick |
 
 ## 示例
@@ -122,7 +147,7 @@ session_start
 {"prompt": "deploy staging", "schedule": "*/10 * * * *", "force": true}
 ```
 
-**永不过期**（tool 调用：长期任务不设 7 天默认过期）：
+**永不过期**（tool 调用：长期 recurring 任务不设 7 天默认过期）：
 
 ```json
 {"prompt": "monthly report", "schedule": "1d", "expires": "never"}
@@ -138,25 +163,61 @@ session_start
 | 默认过期 | **7 天**（`DEFAULT_EXPIRY_MS`） | recurring 任务缺省 `expires` 时；`expires: 'never'` 关闭 |
 | once 任务 | 触发后自动删除 | 不参与后续调度 |
 | cron 失效 | 任务停用 + `lastStatus=failed` + `lastError='cron expression invalid'` | 不会用 `now()` 兜底导致每 tick 重触发死循环 |
-| persist 失败 | `console.warn` + 内存态保留 + `lastError='persist failed'` | 不打断调度，下次 tick 继续尝试 |
 | 忙时 dispatch | 非 force 任务在 agent 忙（非 idle / 有 pending 消息）时跳过，延迟到下次 tick | force=true 可绕过 |
-| history | 保留最近 **20** 条执行记录 | 超出丢弃最旧 |
-| 持久化 | 每次变更写盘（session_shutdown 强制同步写） | 重启后任务保留 |
+| history | 保留最近 **20** 条执行记录 | 超出丢弃最旧；重放折叠时同样裁剪 |
+| 持久化 | custom entry append 到 session JSONL（dispatch 成功后立即 append advance 记录执行） | 任务随 owner session 持久化，resume 后重放恢复，无需额外写盘 |
+| 交付语义 | **at-least-once**（至少一次） | dispatch 成功后内存更新 nextRunAt 并 append advance；append 之前若进程崩溃可能重复注入一次（无精确一次保证，可接受） |
+| 延迟写入窗口 | 新 session 首 turn 内建任务后进程崩溃可能丢失 | pi 延迟写入：首条 assistant 消息前不 flush。窗口窄、概率极低、无恢复手段 |
+| 触发条件 | pi 进程需存活且 session 打开 | 电脑睡眠 / pi 进程未运行 = 不触发（非系统 cron，无后台守护） |
 
 错误语义：创建时 schedule 解析失败 → `INVALID_SCHEDULE`；`run`/`toggle`/`delete` 引用不存在的 id → `TASK_NOT_FOUND`；`run` 时任务 disabled / busy / rate-limited → `DISPATCH_SKIPPED`（message 含 `busy, disabled, or rate-limited`）。
 
 ## 数据存储位置
 
-任务存储为单个 JSON 文件，按 workspace 路径隔离（不同 cwd 存不同文件）：
+### 当前机制
 
-```
-~/.pi/agent/scheduler/<root>/<segments>/scheduler.json
-```
+任务存储为 custom entry，写入创建它的 session 的 JSONL 文件（统一 `customType: pi-scheduler:task`，`op` 字段区分 upsert / advance / toggle / delete）。任务物理归属于创建它的 session——`appendEntry` 把 entry 写入当前 session 的 JSONL，`getEntries()` 重放折叠恢复内存态。
+
+### append-only
+
+custom entry 物理追加到 JSONL，不修改、不删除——pi 依赖 JSONL 物理保留来维持 session tree 的 parentId 链。重放时 per-taskId 按 entry 顺序折叠得到当前态：
+
+- `upsert` → 任务以快照覆盖（last-write-wins，含 ownerSessionFile / nextRunAt 初值）
+- `advance` → 推进 nextRunAt、记录本次执行（at / status）
+- `toggle` → 切换 enabled
+- `delete` → 该任务标记消失（once 触发后自动 delete，重放即不见）
+
+末态 = per taskId 最后一个非 delete op 的结果。
+
+### 不进入 LLM context
+
+pi 的 context 构建对 custom entry 无 case（被过滤）——任务数据零污染对话上下文，不影响 token / 模型上下文。
+
+### 归属即结构性质
+
+任务物理存在于创建 session 的 JSONL 内。**session 文件删除 = 任务消失**，无残留、无需 GC、无分片文件。fork 出的 session 不加载继承的任务副本（ownerSessionFile 过滤），subagent 也不受主 session 任务干扰。
+
+### 旧版迁移
+
+升级前任务存在 cwd 共享的旧 store（`~/.pi/agent/scheduler/<cwd>/scheduler.json`）。升级后首个检测到旧文件的 session 原子 `rename` 为 `scheduler.json.imported`，逐任务 appendEntry upsert 到自己的 JSONL，然后删除 `.imported`（⚠️ 删除时机依赖 flush：resumed session 已落盘可立即删；新 session（pi 延迟写入，entries 仅内存）延迟到首个 `turn_end`（该轮 message_end 已全部持久化，flush 必已发生）确认 flush 后删，`session_shutdown` 兜底；未 flush 保留 `.imported` 供崩溃恢复重导入，避免源文件销毁 + 数据未落盘的双重丢失）：
+
+- **归属**：旧任务无 owner 信息，**归属首个完成导入的 session**（无更好近似）
+- **过期任务立即触发**：导入后若 nextRunAt 已过期，**首个 tick 立即 dispatch**（once 立即注入、recurring 补跑）
+
+### entry 累积
+
+recurring 长期 session 的 scheduler entry 会持续累积（每次 dispatch append 一条 advance）。量级可控：约 100B/条，1h 任务运行一年约 8760 条 ≈ 876KB。且 custom entry 不进 LLM context，不影响 token / 模型上下文。**不做物理裁剪**（append-only 约束 + advance 是 nextRunAt 正确性的必要记录，不可省）。未来若成问题，方向是等 pi 提供 compaction hook，不是本 extension 自建裁剪。
+
+## 依赖的 pi 行为清单
+
+本扩展的存储方案（custom entry event sourcing）依赖以下 pi 源码行为。这些是**实测存在但非 SDK 契约承诺**的隐式行为，pi 升级后需逐条复核：
 
-- `<root>`：路径根（如 `/` → `root`）
-- `<segments>`：cwd 相对根的路径段（如 `/Users/me/project` → `Users/me/project`）
+1. **`pi.appendEntry` / `ctx.sessionManager.getEntries()` 存在且 custom entry 不进 LLM context**：custom entry 在 pi 的 context 构建（`sessionEntryToContextMessages`）中无 case，被 flatMap 过滤，任务数据零污染对话上下文。若 pi 未来把 custom entry 纳入 context，会污染 token / 模型输入
+2. **fork（`forkFrom`）全文件复制 custom entry**：forkFrom 是全文件复制（含被放弃分支的 entries，无 fork 点概念），不是 fork 点路径复制。本扩展靠 owner 过滤兜底两条复制路径。若 pi 改为按分支选择性复制，fork 隔离逻辑需重新评估
+3. **`getEntries()` 返回全量 entries（不按当前分支过滤）**：实测 `getEntries()` 返回全部 fileEntries（session-manager.js:980-982），navigate 只改 leafId 指针不改 entries。因此任务不随 navigate 消失。若 pi 改为按 leafId / 分支过滤 getEntries，切换分支会导致任务丢失
+4. **navigate / 切换分支不改任务 entries**：navigate 只移动 leafId 指针，不增删 custom entry，任务 entries 跨分支稳定存在。若 pi 未来在 navigate 时裁剪 entries，任务持久性会破坏
 
-删除文件即清除全部任务；损坏的 JSON 自动降级为空 store 并 `console.warn`。
+任一条行为变更都需重新验证 design 的 D1 / D2 断言与验收场景（尤其 resume、fork 场景）。
 
 ## 开发
 
@@ -167,9 +228,9 @@ npx vitest run src/__tests__/<file>.test.ts   # 单个文件
 
 测试策略：
 
-- **依赖反转**：`SchedulerRuntime` 只依赖 `SchedulerBackend` 接口（`sendMessage` / `persist` / `now`），不触碰 FS/pi。测试注入 `MockSchedulerBackend`（`src/backend.ts` 同文件 export）实现零副作用测试：`sentMessages` 记录发送、`persistedStores` 记录持久化、`persistError` 注入失败、`nowValue` 固定时间源
+- **依赖反转**：`SchedulerRuntime` 只依赖 `SchedulerBackend` 接口（`sendMessage` / `appendEntry` / `now`），不触碰 FS/pi。测试注入 `MockSchedulerBackend`（`src/backend.ts` 同文件 export）实现零副作用测试
 - **纯函数**：`parseDuration` / `formatDuration` / `parseSchedule` / `computeNextRunAt` / `computeNextRuns`（`src/parsing.ts`）无副作用，可直接断言
-- **property-based**：`src/__tests__/property.test.ts` 用 fast-check 生成随机组合验证不变量（interval 精确、duration round-trip、format↔parse 一致性），生成器范围契约见该文件注释
-- **round-trip**：`store.test.ts`（mock fs）验证路径与 GC；`store-roundtrip.test.ts`（真实 fs，os.tmpdir 隔离）验证 load 白名单字段（lastError/lastStatus/lastRunAt/expiresAt/force/history）持久化往返
+- **重放折叠**：custom entry 折叠协议（upsert / advance / toggle / delete，含 nextRunAt 重放恢复、fork owner 过滤）
+- **旧 store 导入**：rename `.imported` 原子收敛（单成功者、崩溃恢复）
 
-扩展内部结构：`backend.ts`（后端抽象）→ `runtime.ts`（调度核心）→ `service.ts`（业务入口）→ `tool.ts`/`commands.ts`（tool 与 /schedule 命令适配层）→ `widget.ts`（状态栏 widget）。
+扩展内部结构：`backend.ts`（后端抽象）→ `replay.ts`（custom entry 重放折叠）→ `runtime.ts`（调度核心）→ `service.ts`（业务入口）→ `tool.ts` / `commands.ts`（tool 与 /schedule 命令适配层）→ `widget.ts`（状态栏 widget）→ `importer.ts`（旧 store 导入）。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-scheduler",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "type": "module",
   "main": "index.ts",
   "pi": {

package/src/__tests__/backend.test.ts

@@ -2,10 +2,28 @@ import { describe, expect, it } from 'vitest'
 
 import { MockSchedulerBackend } from '../backend.js'
 import { SchedulerRuntime } from '../runtime.js'
-import type { SchedulerStore } from '../types.js'
+import type { SchedulerEntryOp, TaskSnapshot } from '../types.js'
 
 const mockCtx = { isIdle: () => true, hasPendingMessages: () => false }
 
+/** 构造 base task 快照（upsert op 用）。 */
+function snapshot(overrides: Partial<TaskSnapshot> = {}): TaskSnapshot {
+  return {
+    id: 'aaa',
+    name: 'test',
+    prompt: 'p',
+    kind: 'recurring',
+    schedule: { mode: 'interval', intervalMs: 60000 },
+    enabled: true,
+    force: false,
+    createdAt: 0,
+    nextRunAt: 100,
+    runCount: 0,
+    history: [],
+    ...overrides,
+  }
+}
+
 describe('MockSchedulerBackend', () => {
   it('records sendMessage calls', async () => {
     const backend = new MockSchedulerBackend()
@@ -22,17 +40,17 @@ describe('MockSchedulerBackend', () => {
     expect(backend.sentMessages[0]!.opts).toEqual({ deliverAs: 'followUp', triggerTurn: true })
   })
 
-  it('records persist calls and throws injected persistError', async () => {
+  it('records appendEntry calls and throws injected appendError', () => {
     const backend = new MockSchedulerBackend()
-    const store: SchedulerStore = { version: 1, tasks: [] }
+    const op: SchedulerEntryOp = { op: 'delete', taskId: 'aaa' }
 
-    await backend.persist(store)
-    expect(backend.persistedStores).toHaveLength(1)
-    expect(backend.persistedStores[0]).toBe(store)
+    backend.appendEntry(op)
+    expect(backend.appendedOps).toHaveLength(1)
+    expect(backend.appendedOps[0]).toBe(op)
 
-    // persistError 注入：persist 抛该错（ERR-6 语义——错误必须能传到调用栈）
-    backend.persistError = new Error('disk full')
-    await expect(backend.persist(store)).rejects.toThrow('disk full')
+    // appendError 注入：appendEntry 抛该错（ER-APPEND-FAIL 语义——错误必须能传到调用栈供 runtime 捕获）
+    backend.appendError = new Error('pi internal')
+    expect(() => backend.appendEntry(op)).toThrow('pi internal')
   })
 
   it('now() returns injected nowValue or Date.now()', () => {
@@ -42,6 +60,44 @@ describe('MockSchedulerBackend', () => {
     expect(backend.now()).toBe(123456)
   })
 
+  // ── TC-W-BACKEND-REPLAY：loadTasks 委托 replayFoldEntries（IF-BACKEND-REPLAY）──
+  it('TC-W-BACKEND-REPLAY: loadTasks 经 replayFoldEntries 恢复 owner 匹配的任务', () => {
+    const backend = new MockSchedulerBackend()
+    backend.fakeSessionFile = '/a.json'
+    backend.fakeEntries = [
+      // 非 scheduler entry：应被折叠忽略
+      { type: 'message', data: {} },
+      { type: 'custom', customType: 'other-ext', data: {} },
+      // owner 匹配的 upsert
+      {
+        type: 'custom',
+        customType: 'pi-scheduler:task',
+        data: { op: 'upsert', taskId: 'X', ownerSessionFile: '/a.json', task: snapshot({ id: 'X' }) },
+      },
+      // owner 不匹配的 upsert（fork 继承）：应被过滤
+      {
+        type: 'custom',
+        customType: 'pi-scheduler:task',
+        data: { op: 'upsert', taskId: 'Y', ownerSessionFile: '/other.json', task: snapshot({ id: 'Y' }) },
+      },
+    ]
+
+    const tasks = backend.loadTasks()
+
+    expect(tasks).toHaveLength(1)
+    expect(tasks[0]!.id).toBe('X')
+    expect(tasks[0]!.ownerSessionFile).toBe('/a.json')
+  })
+
+  it('TC-W-BACKEND-REPLAY: getSessionFile 返回 fakeSessionFile（缺省值）', () => {
+    const backend = new MockSchedulerBackend()
+    expect(backend.getSessionFile()).toBe('/test/session.json')
+    backend.fakeSessionFile = '/custom.json'
+    expect(backend.getSessionFile()).toBe('/custom.json')
+    backend.fakeSessionFile = undefined
+    expect(backend.getSessionFile()).toBeUndefined()
+  })
+
   // ── TC2：new SchedulerRuntime(mockBackend) 可注入单测，零 FS ──
 
   it('TC2: SchedulerRuntime with MockSchedulerBackend constructs and dispatches via mock', async () => {
@@ -50,8 +106,9 @@ describe('MockSchedulerBackend', () => {
     const runtime = new SchedulerRuntime(backend, mockCtx)
     const task = await runtime.addTask('probe', { mode: 'interval', intervalMs: 60000 })
     expect(task).toBeDefined()
-    // addTask 的 persist 走了 mock backend（零 FS）
-    expect(backend.persistedStores).toHaveLength(1)
+    // addTask 后 append upsert op（append-only，零 FS）
+    expect(backend.appendedOps).toHaveLength(1)
+    expect(backend.appendedOps[0]!.op).toBe('upsert')
 
     await runtime.dispatchTask(task)
 

package/src/__tests__/commands.test.ts

@@ -25,8 +25,10 @@ describe('/schedule command', () => {
         commandOpts = opts
       },
     }
+    const backend = new MockSchedulerBackend()
     service = new SchedulerService(
-      new SchedulerRuntime(new MockSchedulerBackend(), { isIdle: () => true, hasPendingMessages: () => false }),
+      new SchedulerRuntime(backend, { isIdle: () => true, hasPendingMessages: () => false }),
+      () => backend.now(),
     )
     registerScheduleCommand(mockPi as never, () => service)
   })

package/src/__tests__/importer.test.ts

@@ -0,0 +1,283 @@
+import * as fs from 'node:fs'
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { getLegacyStorePath, importLegacyStore } from '../importer.js'
+import type { ScheduledTask } from '../types.js'
+
+// vi.mock 必须在 import 之前提升。mock 工厂替换 node:fs 命名空间，
+// importer.ts 内 `import * as fs` 拿到的就是这 4 个 vi.fn()。
+vi.mock('node:fs', () => ({
+  renameSync: vi.fn(),
+  existsSync: vi.fn(),
+  readFileSync: vi.fn(),
+  unlinkSync: vi.fn(),
+}))
+
+const cwd = '/fake/workspace'
+const storePath = getLegacyStorePath(cwd)
+const importedPath = storePath + '.imported'
+const sessionFile = '/x/sess.json'
+
+/** 构造合法旧 store 任务（参考 types.ts ScheduleSpec / TaskKind 默认值）。 */
+function makeTask(overrides: Partial<ScheduledTask> = {}): ScheduledTask {
+  return {
+    id: 'task-1',
+    name: 'test task',
+    prompt: 'do something',
+    kind: 'recurring',
+    schedule: { mode: 'interval', intervalMs: 60000 },
+    enabled: true,
+    force: false,
+    createdAt: 1000,
+    nextRunAt: 2000,
+    runCount: 0,
+    history: [],
+    ...overrides,
+  }
+}
+
+/** 构造带 code 属性的 ENOENT 错误（模拟 fs.renameSync 源文件不存在）。 */
+function enoentError(): Error & { code: string } {
+  return Object.assign(new Error('ENOENT: no such file or directory'), { code: 'ENOENT' })
+}
+
+describe('importLegacyStore', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    // 默认 implementation：rename 成功、existsSync false、readFileSync 空、unlink 无副作用
+    vi.mocked(fs.renameSync).mockImplementation(() => {})
+    vi.mocked(fs.existsSync).mockReturnValue(false)
+    vi.mocked(fs.readFileSync).mockReturnValue('{}')
+    vi.mocked(fs.unlinkSync).mockImplementation(() => {})
+    // 抑制 importer 的 console.log/warn 输出（断言用 spy）
+    vi.spyOn(console, 'log').mockImplementation(() => {})
+    vi.spyOn(console, 'warn').mockImplementation(() => {})
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  // ── TC1：rename 原子单成功 + 逐任务 append upsert + 删 .imported ──
+  it('TC1: rename 成功独占 + 2 任务逐个 appendEntry upsert + 删 .imported', () => {
+    const taskA = makeTask({ id: 'aaaa', name: 'A' })
+    const taskB = makeTask({ id: 'bbbb', name: 'B' })
+    vi.mocked(fs.readFileSync).mockReturnValue(
+      JSON.stringify({ version: 1, tasks: [taskA, taskB] }),
+    )
+    const appendEntry = vi.fn()
+    // resumed session：sessionFile 已存在（pi flushed=true，append 即时落盘）→ 立即 unlink 安全
+    vi.mocked(fs.existsSync).mockImplementation(p => p === sessionFile)
+
+    importLegacyStore(cwd, { appendEntry }, sessionFile)
+    // 1) rename 原子独占：scheduler.json → scheduler.json.imported
+    expect(fs.renameSync).toHaveBeenCalledTimes(1)
+    expect(fs.renameSync).toHaveBeenCalledWith(storePath, importedPath)
+
+    // 2) appendEntry 调 2 次，customType + op 形状正确
+    expect(appendEntry).toHaveBeenCalledTimes(2)
+    expect(appendEntry).toHaveBeenNthCalledWith(1, 'pi-scheduler:task', {
+      op: 'upsert',
+      taskId: 'aaaa',
+      ownerSessionFile: sessionFile,
+      task: expect.objectContaining({ id: 'aaaa', name: 'A' }),
+    })
+    expect(appendEntry).toHaveBeenNthCalledWith(2, 'pi-scheduler:task', {
+      op: 'upsert',
+      taskId: 'bbbb',
+      ownerSessionFile: sessionFile,
+      task: expect.objectContaining({ id: 'bbbb', name: 'B' }),
+    })
+
+    // 3) task snapshot 不含 ownerSessionFile/pending（显式剥离）
+    const firstOp = appendEntry.mock.calls[0]![1] as { task: Record<string, unknown> }
+    expect(firstOp.task).not.toHaveProperty('ownerSessionFile')
+    expect(firstOp.task).not.toHaveProperty('pending')
+
+    // 4) unlinkSync 删 .imported
+    expect(fs.unlinkSync).toHaveBeenCalledTimes(1)
+    expect(fs.unlinkSync).toHaveBeenCalledWith(importedPath)
+
+    // 5) 进度日志（console.warn，项目 convention 禁 console.log）
+    expect(console.warn).toHaveBeenCalledWith(
+      expect.stringContaining(`imported 2 legacy tasks from ${importedPath}`),
+    )
+  })
+
+  // ── TC2：.imported 残留崩溃恢复幂等 ──
+  it('TC2: scheduler.json 不存在(rename ENOENT) + .imported 残留 → 读 .imported 导入 + 删 .imported', () => {
+    // 实现A：scheduler.json 不存在时 renameSync 抛 ENOENT → 走 handleImportedResidue
+    vi.mocked(fs.renameSync).mockImplementation(() => {
+      throw enoentError()
+    })
+    // .imported 存在 + resumed session（sessionFile 已存在 → 已落盘 → 立即删）
+    vi.mocked(fs.existsSync).mockImplementation(p => p === importedPath || p === sessionFile)
+    const taskA = makeTask({ id: 'cccc' })
+    vi.mocked(fs.readFileSync).mockReturnValue(
+      JSON.stringify({ version: 1, tasks: [taskA] }),
+    )
+    const appendEntry = vi.fn()
+
+    importLegacyStore(cwd, { appendEntry }, sessionFile)
+
+    expect(appendEntry).toHaveBeenCalledTimes(1)
+    expect(appendEntry).toHaveBeenCalledWith('pi-scheduler:task', {
+      op: 'upsert',
+      taskId: 'cccc',
+      ownerSessionFile: sessionFile,
+      task: expect.objectContaining({ id: 'cccc' }),
+    })
+    expect(fs.unlinkSync).toHaveBeenCalledWith(importedPath)
+  })
+
+  // ── TC3：scheduler.json 与 .imported 都不存在 → no-op ──
+  it('TC3: 双不存在（rename ENOENT + .imported 不存在）→ no-op，不抛错', () => {
+    vi.mocked(fs.renameSync).mockImplementation(() => {
+      throw enoentError()
+    })
+    vi.mocked(fs.existsSync).mockReturnValue(false) // .imported 也不存在
+    const appendEntry = vi.fn()
+
+    expect(() => importLegacyStore(cwd, { appendEntry }, sessionFile)).not.toThrow()
+    expect(appendEntry).toHaveBeenCalledTimes(0)
+    expect(fs.unlinkSync).not.toHaveBeenCalled()
+  })
+
+  // ── TC4：并发单成功者——rename 抛 ENOENT + .imported 也不存在 → skip（S10 并发场景）──
+  it('TC4: 并发竞争——rename 抛 ENOENT + .imported 不存在 → 幂等 skip，不抛错', () => {
+    // 两进程并发：本进程 rename 时 scheduler.json 已被另一进程 rename 走 → ENOENT
+    vi.mocked(fs.renameSync).mockImplementation(() => {
+      throw enoentError()
+    })
+    vi.mocked(fs.existsSync).mockReturnValue(false) // 本进程也没看到 .imported
+    const appendEntry = vi.fn()
+
+    expect(() => importLegacyStore(cwd, { appendEntry }, sessionFile)).not.toThrow()
+    expect(appendEntry).toHaveBeenCalledTimes(0) // 别人已导入，本进程 skip
+  })
+
+  // ── TC5：currentSessionFile=undefined（--no-session 模式）→ 早 return skip ──
+  it('TC5: currentSessionFile=undefined → 整个 importer skip，不碰 fs', () => {
+    const appendEntry = vi.fn()
+
+    importLegacyStore(cwd, { appendEntry }, undefined)
+
+    expect(appendEntry).toHaveBeenCalledTimes(0)
+    expect(fs.renameSync).not.toHaveBeenCalled() // 早 return，不碰 fs
+    expect(fs.readFileSync).not.toHaveBeenCalled()
+    expect(fs.unlinkSync).not.toHaveBeenCalled()
+  })
+
+  // ── TC6：JSON 损坏降级（warn 不 rethrow）──
+  it('TC6: readFileSync 返回损坏 JSON → console.warn + 不 rethrow，appendEntry 0 次', () => {
+    vi.mocked(fs.readFileSync).mockReturnValue('not-json{')
+    const appendEntry = vi.fn()
+
+    expect(() => importLegacyStore(cwd, { appendEntry }, sessionFile)).not.toThrow()
+    expect(console.warn).toHaveBeenCalledWith(
+      expect.stringContaining('[scheduler] import failed'),
+    )
+    expect(appendEntry).toHaveBeenCalledTimes(0) // parse 失败，无 append
+  })
+
+  // ── TC7：owner 归属——upsert op.ownerSessionFile === currentSessionFile（非旧 store 路径）──
+  it('TC7: op.ownerSessionFile 严格等于传入的 currentSessionFile，非 getLegacyStorePath 推导路径', () => {
+    const ownSession = '/my/session.json'
+    const taskA = makeTask({ id: 'dddd' })
+    vi.mocked(fs.readFileSync).mockReturnValue(
+      JSON.stringify({ version: 1, tasks: [taskA] }),
+    )
+    const appendEntry = vi.fn()
+
+    importLegacyStore(cwd, { appendEntry }, ownSession)
+
+    expect(appendEntry).toHaveBeenCalledTimes(1)
+    const op = appendEntry.mock.calls[0]![1] as { ownerSessionFile: string }
+    expect(op.ownerSessionFile).toBe(ownSession)
+    expect(op.ownerSessionFile).not.toBe(storePath)
+    expect(op.ownerSessionFile).not.toBe(importedPath)
+  })
+
+  // ── TC8：新 session 未 flush → 延迟 unlink（IMPORT-FLUSH-GUARD，MF-1）──
+  it('TC8: 新 session（sessionFile 不存在）→ 不立即 unlink，返回 cleanup；flush 后删，未 flush 保留', () => {
+    const taskA = makeTask({ id: 'eeee' })
+    vi.mocked(fs.readFileSync).mockReturnValue(
+      JSON.stringify({ version: 1, tasks: [taskA] }),
+    )
+    vi.mocked(fs.existsSync).mockReturnValue(false) // 新 session：sessionFile 尚不存在（pi 未 flush，entries 仅内存）
+    const appendEntry = vi.fn()
+
+    const cleanup = importLegacyStore(cwd, { appendEntry }, sessionFile)
+
+    // append 已发生，但 unlink 未执行——数据可能仅内存，销毁源文件 = 永久丢失
+    expect(appendEntry).toHaveBeenCalledTimes(1)
+    expect(fs.unlinkSync).not.toHaveBeenCalled()
+    expect(console.warn).toHaveBeenCalledWith(expect.stringContaining('deferring'))
+
+    // 情形1：flush 已发生（sessionFile 出现，.imported 仍在）→ cleanup 删除 .imported
+    vi.mocked(fs.existsSync).mockImplementation(p => p === sessionFile || p === importedPath)
+    cleanup?.()
+    expect(fs.unlinkSync).toHaveBeenCalledTimes(1)
+    expect(fs.unlinkSync).toHaveBeenCalledWith(importedPath)
+
+    // 情形2：从未 flush → cleanup 保留 .imported（不 unlink、不抛错，供崩溃恢复重导入）
+    vi.mocked(fs.unlinkSync).mockClear()
+    vi.mocked(fs.existsSync).mockReturnValue(false)
+    expect(() => cleanup?.()).not.toThrow()
+    expect(fs.unlinkSync).not.toHaveBeenCalled()
+  })
+
+  // ── TC8b：cleanup 幂等 + unlink ENOENT 守卫（MF-2，R2 修复）──
+  it('TC8b: cleanup 幂等（已删后 no-op）+ unlink 仅静默 ENOENT，其他 fs 错误向上抛', () => {
+    const taskA = makeTask({ id: 'ffff' })
+    vi.mocked(fs.readFileSync).mockReturnValue(
+      JSON.stringify({ version: 1, tasks: [taskA] }),
+    )
+    vi.mocked(fs.existsSync).mockReturnValue(false) // 新 session 未 flush → 延迟删除路径
+    const appendEntry = vi.fn()
+
+    const cleanup = importLegacyStore(cwd, { appendEntry }, sessionFile)!
+    expect(cleanup).toBeDefined()
+
+    // 情形1：flush 已发生 → 正常 unlink
+    vi.mocked(fs.existsSync).mockReturnValue(true)
+    cleanup()
+    expect(fs.unlinkSync).toHaveBeenCalledTimes(1)
+    expect(fs.unlinkSync).toHaveBeenCalledWith(importedPath)
+
+    // 情形2（MF-2）：并发——另一进程已 unlink（unlinkSync 抛 ENOENT）→ 静默吞掉不抛
+    vi.mocked(fs.unlinkSync).mockClear()
+    vi.mocked(fs.unlinkSync).mockImplementation(() => {
+      throw enoentError()
+    })
+    expect(() => cleanup()).not.toThrow()
+    expect(fs.unlinkSync).toHaveBeenCalledTimes(1)
+
+    // 情形3（MF-2）：非 ENOENT fs 错误（EACCES）→ 不吞，向上抛（index.ts try/finally 兜底复位）
+    vi.mocked(fs.unlinkSync).mockImplementation(() => {
+      throw Object.assign(new Error('EACCES: permission denied'), { code: 'EACCES' })
+    })
+    expect(() => cleanup()).toThrow(/EACCES/)
+
+    // 情形4：幂等——.imported 已不存在（本进程或并发已删）→ no-op，不抛
+    vi.mocked(fs.unlinkSync).mockClear()
+    vi.mocked(fs.existsSync).mockReturnValue(false)
+    expect(() => cleanup()).not.toThrow()
+    expect(fs.unlinkSync).not.toHaveBeenCalled()
+  })
+
+  // ── TC9：0 任务空 store → 无持久化依赖，仍立即 unlink ──
+  it('TC9: 空 store（tasks 空数组）→ 0 次 append，直接 unlink .imported（无数据可丢）', () => {
+    vi.mocked(fs.readFileSync).mockReturnValue(JSON.stringify({ version: 1, tasks: [] }))
+    vi.mocked(fs.existsSync).mockReturnValue(false) // 新 session 也不影响：0 任务无持久化依赖
+    const appendEntry = vi.fn()
+
+    const cleanup = importLegacyStore(cwd, { appendEntry }, sessionFile)
+
+    expect(appendEntry).toHaveBeenCalledTimes(0)
+    expect(fs.unlinkSync).toHaveBeenCalledTimes(1)
+    expect(fs.unlinkSync).toHaveBeenCalledWith(importedPath)
+    expect(cleanup).toBeUndefined()
+  })
+})