@zhushanwen/pi-scheduler 0.1.0 → 0.2.0

package/src/importer.ts

@@ -0,0 +1,261 @@
+import * as fs from 'node:fs'
+import * as os from 'node:os'
+import * as path from 'node:path'
+
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
+
+import type { ScheduledTask, SchedulerEntryOp, SchedulerStore, TaskSnapshot } from './types.js'
+
+/**
+ * 获取旧 store 文件路径：~/.pi/agent/scheduler/<root>/<segments>/scheduler.json。
+ *
+ * 内联自 store.ts getStorePath——store.ts 本 wave 删除后此函数是旧路径的唯一推导实现，
+ * 不能 import 已删 store。workspace 路径隔离，不同 cwd 存不同文件。
+ *
+ * export 供测试推导期望路径（断言 renameSync/unlinkSync 参数）。
+ *
+ * ⚠️ 路径硬编码说明：硬编码 `~/.pi/agent/scheduler/` 是因为已发布版（npm 0.1.1）的 store.ts
+ * 即用此路径，旧数据确在此处，必须按此路径探测才能迁移。注意分支 `feat-auto-name-session-refactor`
+ * 的 commit 4b5513b5e 把 store 路径改为 getAgentDir()（读 PI_CODING_AGENT_DIR，用于 xyz-agent
+ * 数据目录隔离）；该分支合并后此处需改为双候选路径探测（先 getAgentDir() 再 fallback ~/.pi/agent），
+ * 否则 xyz-agent 隔离目录下的旧任务探测不到。
+ */
+export function getLegacyStorePath(cwd: string): string {
+  const home = os.homedir()
+  const resolved = path.resolve(cwd)
+  const parsed = path.parse(resolved)
+  const segments = resolved.slice(parsed.root.length)
+    .split(path.sep).filter(Boolean)
+  const root = parsed.root
+    .replaceAll(/[^a-zA-Z0-9]+/g, '-')
+    .replaceAll(/^-+|-+$/g, '')
+    .toLowerCase() || 'root'
+  return path.join(home, '.pi', 'agent', 'scheduler', root, ...segments, 'scheduler.json')
+}
+
+/**
+ * 旧 store 任务字段补全（参考 store.ts load() 默认值兜底）：旧数据可能缺字段，逐字段给默认值。
+ * ownerSessionFile/pending 不补全——旧数据本无此二字段，由 toTaskSnapshot 显式剥离。
+ */
+function normalizeLegacyTask(t: Partial<ScheduledTask>): ScheduledTask {
+  return {
+    id: t.id ?? '',
+    name: t.name ?? '',
+    prompt: t.prompt ?? '',
+    kind: t.kind ?? 'recurring',
+    schedule: t.schedule ?? { mode: 'interval', intervalMs: 60000 },
+    createdAt: t.createdAt ?? 0,
+    nextRunAt: t.nextRunAt ?? 0,
+    runCount: t.runCount ?? 0,
+    enabled: t.enabled ?? true,
+    force: t.force ?? false,
+    history: t.history ?? [],
+    expiresAt: t.expiresAt,
+    lastRunAt: t.lastRunAt,
+    lastStatus: t.lastStatus,
+    lastError: t.lastError,
+  }
+}
+
+/**
+ * ScheduledTask → TaskSnapshot：显式构造 15 字段
+ * （id/name/prompt/kind/schedule/enabled/force/createdAt/nextRunAt/expiresAt?/
+ * runCount/lastRunAt?/lastStatus?/lastError?/history），剥离 ownerSessionFile（在 op 顶层）
+ * 与 pending（运行时标记），history 用 slice() 深拷贝。
+ *
+ * 显式构造而非复用 runtime.toSnapshot 的解构写法（T-C3-explicit）：旧 store 数据本无
+ * ownerSessionFile/pending 运行时字段，显式构造更安全。两处构造逻辑需保持形状一致
+ * （对照 types.ts TaskSnapshot 15 字段）。
+ */
+function toTaskSnapshot(task: ScheduledTask): TaskSnapshot {
+  return {
+    id: task.id,
+    name: task.name,
+    prompt: task.prompt,
+    kind: task.kind,
+    schedule: task.schedule,
+    enabled: task.enabled,
+    force: task.force,
+    createdAt: task.createdAt,
+    nextRunAt: task.nextRunAt,
+    expiresAt: task.expiresAt,
+    runCount: task.runCount,
+    lastRunAt: task.lastRunAt,
+    lastStatus: task.lastStatus,
+    lastError: task.lastError,
+    history: task.history.slice(),
+  }
+}
+
+/**
+ * 判断 err 是否为 ENOENT（fs.renameSync 源文件不存在）。
+ * Record 守卫模式与 replay.ts isSchedulerEntryOp 同款（避免 taste/no-unsafe-cast）。
+ */
+function isENOENT(err: unknown): boolean {
+  if (!(err instanceof Error)) return false
+  if (!('code' in err)) return false
+  return (err as Record<'code', unknown>).code === 'ENOENT'
+}
+
+/**
+ * 从 .imported 路径读取旧 store JSON、逐任务 pi.appendEntry upsert、按 flush 状态删除 .imported。
+ * read/parse/append 任一异常由外层 importLegacyStore 的 try/catch 兜底（C1 整体降级）。
+ *
+ * 返回值为延迟删除 cleanup（未 flush 的新 session 场景），由 index.ts 在首个 turn_end 与
+ * session_shutdown 时调用（cleanup 幂等，可重复调用）；已安全删除或无需导入时返回 undefined。
+ *
+ * ⚠️ unlink 时机（IMPORT-FLUSH-GUARD，MF-1 修复）：pi SessionManager._persist 延迟写入——
+ * 新 session（sessionFile 尚不存在 → flushed=false）的 appendEntry 只进内存 fileEntries，
+ * 首个 assistant message 到达才 flush 落盘（openSync "wx" 全量写 fileEntries）。若紧随 append
+ * 循环 unlink，未 flush 即退出（打开未发消息即关闭、xyz-agent 自动打开/恢复的 session）→
+ * 全部旧任务永久丢失且源文件已销毁，崩溃恢复路径（.imported 残留）同时失效。
+ * resumed session（sessionFile 已存在 → _setSessionFile 载入时 flushed=true）每次 append
+ * 即时写盘，unlink 安全。
+ *
+ * 判定依据（pi SDK 源码，非推理）：dist/core/session-manager.js `_persist` 的 !hasAssistant
+ * 分支——flushed=true 时 appendFileSync 直写盘，flushed=false 时仅内存；flushed 仅在
+ * _setSessionFile 载入已存在文件（或零字节文件重写）时置 true，新 session 恒 false。
+ * sessionFile 进程内只可能由首次 flush 创建（openSync "wx" 全量写），故
+ * fs.existsSync(currentSessionFile) 在 session_start 时点与 flushed 状态等价。
+ */
+function importFromFile(
+  importedPath: string,
+  pi: Pick<ExtensionAPI, 'appendEntry'>,
+  currentSessionFile: string,
+): (() => void) | undefined {
+  const content = fs.readFileSync(importedPath, 'utf-8')
+  const data = JSON.parse(content) as Partial<SchedulerStore>
+  const tasks = (data.tasks ?? []).map(normalizeLegacyTask)
+
+  for (const task of tasks) {
+    const op: SchedulerEntryOp = {
+      op: 'upsert',
+      taskId: task.id,
+      ownerSessionFile: currentSessionFile,
+      task: toTaskSnapshot(task),
+    }
+    // customType 与 backend.ts PiSchedulerBackend.appendEntry 同源，改一处必改两处
+    pi.appendEntry('pi-scheduler:task', op)
+  }
+
+  // 空 store（0 任务）无持久化依赖，直接删；resumed session（sessionFile 已存在）已即时落盘，删
+  if (tasks.length === 0 || fs.existsSync(currentSessionFile)) {
+    fs.unlinkSync(importedPath)
+    // 内部诊断日志（非用户可见消息）：用 console.warn 而非 console.log（项目 convention：
+    // extensions 禁 console.log/info 防泄漏到 TUI；诊断输出统一 console.warn）
+    console.warn(`[scheduler] imported ${tasks.length} legacy tasks from ${importedPath}`)
+    return undefined
+  }
+
+  // 新 session（未 flush）：延迟删除，cleanup 由 index.ts 在首个 turn_end（该轮 message_end 已全部
+  // 持久化，flush 必已发生——agent-session.js _handleAgentEvent 在 message_end 处理中调
+  // appendMessage 触发 _persist 全量落盘）与 session_shutdown 时重复调用——flush 后 sessionFile
+  // 出现 → 删；仍未 flush → 静默保留 .imported 供下次 session_start 的 handleImportedResidue
+  // 崩溃恢复重导入。跨 session 重导入窗口 = session_start → 首个 turn_end（秒级）：turn_end 后
+  // .imported 已删，后续 session 启动看不到残留 → 双导入窗口闭合（R-CONCURRENT-IMPORT 已更新）
+  console.warn(
+    `[scheduler] imported ${tasks.length} legacy tasks (session not flushed; deferring ${importedPath} removal)`,
+  )
+  return () => {
+    // 幂等：已删（本进程或并发另一进程已处理）→ no-op。cleanup 在每次 turn_end 都会调用，重复调用安全
+    if (!fs.existsSync(importedPath)) return
+    if (fs.existsSync(currentSessionFile)) {
+      // flush 已发生（sessionFile 由首次 flush 创建，fileEntries 全量落盘）→ 安全删除
+      try {
+        fs.unlinkSync(importedPath)
+      } catch (err) {
+        // MF-2：并发——另一进程（resumed B）已 unlink → ENOENT 静默；其他 fs 错误（EACCES）不吞
+        if (!isENOENT(err)) throw err
+      }
+    }
+    // 从未 flush：保留 .imported，下次 session_start 崩溃恢复重导入（不 unlink；不告警——
+    // 每次 turn_end 都会走到这里，避免刷屏；保留依据见上方 IMPORT-FLUSH-GUARD 注释）
+  }
+}
+
+/**
+ * 残留恢复：rename 抛 ENOENT（别人已把 scheduler.json rename 走）后处理 .imported 残留。
+ *
+ * 并发 + 崩溃恢复交叉窗口（R-CONCURRENT-IMPORT）：若 .imported 存在，可能是
+ *   a) 本进程上次崩溃留下的 .imported（崩溃恢复）→ 导入正确
+ *   b) 另一进程 winner rename 后、unlinkSync 前的 .imported（rename 竞态）→ 本进程也会导入
+ *   c) 另一进程新 session 延迟删除窗口内的 .imported（IMPORT-FLUSH-GUARD：session_start →
+ *      首个 turn_end 之间）→ 本进程也会导入
+ * 窗口：b 为 rename→unlinkSync 毫秒级（需两进程同时 session_start 同 cwd，罕见）；c 为秒级
+ * （A 存活且首 turn 未完成时 B 启动）。c 由 turn_end 触发的清理收敛：A 首个 turn 完成后
+ * .imported 删除，此后 B 启动 → 双不存在 → skip。
+ *
+ * ⚠️ 双导入后果（如实记录，非「已被消除」）：情况 b/c 下 A/B 各自导入一份副本、owner 各为自己，
+ * 同一个逻辑任务会在两个 session 各触发一次（跨 session 双触发，正是 G5 要防的）。owner 过滤
+ * （按 ownerSessionFile）只保证「单一 session 内不重复」，并不能消除此跨 session 双触发——
+ * owner 过滤针对的是 fork 继承的「owner=他者」任务，而此处两副本的 owner 各自匹配本 session。
+ * 窗口（毫秒级竞态 + 秒级延迟删除窗口）远小于「.imported 全程驻留」，可接受，不引入锁机制（过度工程）。
+ */
+function handleImportedResidue(
+  importedPath: string,
+  pi: Pick<ExtensionAPI, 'appendEntry'>,
+  currentSessionFile: string,
+): (() => void) | undefined {
+  if (fs.existsSync(importedPath)) {
+    return importFromFile(importedPath, pi, currentSessionFile)
+  }
+  // else: 双不存在（TC3），no-op
+  return undefined
+}
+
+/**
+ * 导入旧 scheduler store 到当前 session（append-only event sourcing 迁移，IF-IMPORT-LEGACY）。
+ *
+ * 策略：原子 rename scheduler.json → scheduler.json.imported 独占迁移；成功者读取 .imported
+ * 逐任务 pi.appendEntry('pi-scheduler:task', upsert) 后删除 .imported；rename 抛 ENOENT
+ * 说明并发场景下别人已 rename 走，走 handleImportedResidue 幂等恢复。
+ *
+ * 时序（CL3 方案A）：必须在 backend.loadTasks() 之前执行——append 的 upsert entry 进入 pi
+ * 内存 fileEntries，紧接的 loadTasks replay 统一重放读到导入任务（pi _appendEntry 同步 push
+ * fileEntries，design-review 已实测验证）。
+ *
+ * 整体降级（C1）：read/parse/appendEntry 任一异常 → console.warn + 不 rethrow，不让
+ * session_start 崩溃（与 replay gap4 / ER-APPEND-FAIL 同款降级语义）。append 中途失败时
+ * .imported 保留（不 unlink）——下次 session 的 handleImportedResidue 会重导入全部任务，
+ * 已成功 append 的子集可能跨 session 双触发；取舍：删除则失败任务永久丢失（更糟），
+ * 保留则与 R-CONCURRENT-IMPORT / IMPORT-FLUSH-GUARD 同属 at-least-once 已接受窗口（SG-1）。
+ *
+ * nextRunAt 原样保留不重算、不 gc 过滤（CL4）：导入后首个 tick 立即 dispatch（D3 立即触发语义）。
+ *
+ * 返回值：延迟删除 cleanup（新 session 未 flush 时保留 .imported 待首个 turn_end /
+ * session_shutdown 确认 flush 后删除；cleanup 幂等，可重复调用），已安全处理时为 undefined。
+ * index.ts 在 turn_end 与 session_shutdown 调用它。
+ */
+export function importLegacyStore(
+  cwd: string,
+  pi: Pick<ExtensionAPI, 'appendEntry'>,
+  currentSessionFile: string | undefined,
+): (() => void) | undefined {
+  // TC5：--no-session 模式无 owner session 可归属，导入无意义，早 return 不碰 fs
+  if (currentSessionFile === undefined) return undefined
+
+  const storePath = getLegacyStorePath(cwd)
+  const importedPath = storePath + '.imported'
+
+  try {
+    try {
+      fs.renameSync(storePath, importedPath)
+    } catch (err) {
+      if (isENOENT(err)) {
+        // 并发 S10 / 崩溃恢复：scheduler.json 已不在（被别人 rename 走或上次崩溃）→ 残留恢复
+        return handleImportedResidue(importedPath, pi, currentSessionFile)
+      }
+      // 其他 fs 错误走整体降级 warn
+      throw err
+    }
+
+    // 成功 rename → 导入 .imported
+    return importFromFile(importedPath, pi, currentSessionFile)
+  } catch (err) {
+    // C1 整体降级：read/parse/appendEntry 任一异常不崩 session_start
+    console.warn(
+      `[scheduler] import failed: ${err instanceof Error ? err.message : String(err)}`,
+    )
+    return undefined
+  }
+}

package/src/index.ts

@@ -1,7 +1,10 @@
 import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent'
 
+import { PiSchedulerBackend } from './backend.js'
 import { registerScheduleCommand } from './commands.js'
+import { importLegacyStore } from './importer.js'
 import { SchedulerRuntime } from './runtime.js'
+import { SchedulerService } from './service.js'
 import {
   controlGuidelines,
   createScheduleControlHandler,
@@ -14,54 +17,77 @@ import {
 } from './tool.js'
 import { renderSchedulerWidget } from './widget.js'
 
-/** widget 刷新节奏：对齐 runtime 的 TICK_INTERVAL_MS（30s），保证 nextRunAt 倒计时随 tick 更新。 */
-const WIDGET_REFRESH_MS = 30_000
-
 /**
  * pi-scheduler extension factory。
  * 注册 schedule + schedule_control 两个 tool、/schedule command、session 事件。
  *
- * runtime 生命周期：在 session_start 中创建（依赖 ctx），factory 顶层只声明为 null。
- * tool/command 的 execute/handler 通过 getRuntime() 延迟读取，避免在 factory 顶层
- * 捕获 null——那时 session_start 尚未触发，runtime! 非空断言会骗过编译器但运行时是 null。
+ * service 生命周期：在 session_start 中创建（依赖 ctx），factory 顶层只声明为 null。
+ * tool/command 的 execute/handler 通过 getService() 延迟读取，避免在 factory 顶层
+ * 捕获 null——那时 session_start 尚未触发，service! 非空断言会骗过编译器但运行时是 null。
  */
 export default function schedulerExtension(pi: ExtensionAPI): void {
-  let runtime: SchedulerRuntime | null = null
-  // widget 刷新计时器：与 runtime 同生命周期，session_shutdown 时清理。
-  let widgetTimer: ReturnType<typeof setInterval> | null = null
+  let service: SchedulerService | null = null
+  // IMPORT-FLUSH-GUARD（MF-1）：importLegacyStore 对未 flush 的新 session 返回延迟删除 .imported
+  // 的 cleanup——turn_end / session_shutdown 时执行：确认 flush（sessionFile 已出现）则删，
+  // 未 flush 保留供崩溃恢复重导入（否则未 flush 即退出 → 全部旧任务丢失且源文件已销毁）。
+  // 触发点用 turn_end（而非仅 session_shutdown）：turn_end 时该轮 message_end 已全部持久化
+  // （flush 必已发生），把跨 session 双导入窗口从「session 整个生命周期」缩回
+  // 「session_start → 首个 turn_end」秒级。cleanup 幂等（importer.ts importFromFile），重复调用安全。
+  let importCleanup: (() => void) | undefined
 
-  const getRuntime = (): SchedulerRuntime => {
-    if (!runtime) throw new Error('Scheduler not initialized: session not started')
-    return runtime
+  const getService = (): SchedulerService => {
+    if (!service) throw new Error('Scheduler not initialized: session not started')
+    return service
   }
 
   pi.on('session_start', (_event, ctx: ExtensionContext) => {
-    runtime = new SchedulerRuntime(ctx.cwd, pi, ctx)
-    runtime.loadTasks()
+    // 装配点：backend（ctx.sessionManager 读 entries / pi.appendEntry 写 op）→ runtime（内存态 + 调度）→ service（业务入口）
+    const backend = new PiSchedulerBackend(ctx, pi)
+    // 旧 store 原子导入（CL3 方案A）：必须在 backend.loadTasks() 之前执行——
+    // append 的 upsert entry 进入 pi 内存 fileEntries，紧接的 loadTasks replay 统一重放读到导入任务。
+    // ctx.cwd 类型为 string（SDK ExtensionContext 必填），无需 ?? process.cwd() 兜底（CL2）。
+    importCleanup = importLegacyStore(ctx.cwd, pi, ctx.sessionManager.getSessionFile())
+    const runtime = new SchedulerRuntime(backend, ctx)
+    runtime.loadTasks(backend.loadTasks())
+    // W2：tick 后回调刷新 widget（替代独立 widgetTimer + setInterval，节奏对齐 TICK_INTERVAL_MS）
+    runtime.onAfterTick(() => refreshWidget(ctx))
     runtime.startScheduler()
+    service = new SchedulerService(runtime, () => backend.now())
 
-    // 注册 widget（SDK setWidget 第一重载：直接传 string[]）。
-    // string[] 只渲染一次，调度器需要随 task 状态/nextRunAt 倒计时刷新，
-    // 因此用一个对齐 TICK_INTERVAL_MS 的 interval 周期性重发 string[]，
-    // 等价于 plan 扩展的 push 模式（plan/src/widget.ts:13）。
+    // 注册 widget（SDK setWidget 第一重载：直接传 string[]）。初始渲染一次，
+    // 后续随每次 tickScheduler 末尾的 onAfterTick 回调刷新（nextRunAt 倒计时 + task 状态）。
     refreshWidget(ctx)
-    widgetTimer = setInterval(() => refreshWidget(ctx), WIDGET_REFRESH_MS)
   })
 
-  pi.on('session_shutdown', () => {
-    if (widgetTimer) {
-      clearInterval(widgetTimer)
-      widgetTimer = null
+  pi.on('turn_end', () => {
+    // IMPORT-FLUSH-GUARD（MF-1）：延迟删除的主触发点——turn_end 前该轮所有 message_end 已持久化
+    // （agent-session.js _handleAgentEvent 在 message_end 处理中调 appendMessage 触发 flush），
+    // sessionFile 已出现 → cleanup 删 .imported；仍未 flush（无 assistant 消息的轮次）→ 静默保留，
+    // 下次 turn_end / session_shutdown 重试。cleanup 幂等（importer.ts importFromFile）。
+    importCleanup?.()
+  })
+
+  pi.on('session_shutdown', async () => {
+    // append-only 模型无 persistSync（runtime 已按 op appendEntry 落盘到 owner session JSONL）；
+    // widgetTimer 已移除（由 runtime.onAfterTick 替代）。仅停止 scheduler tick。
+    if (service) {
+      service.runtime.stopScheduler()
     }
-    if (runtime) {
-      runtime.persistSync()
-      runtime.stopScheduler()
+    // IMPORT-FLUSH-GUARD（MF-1）：兜底清理——正常路径已由首个 turn_end 完成；此处覆盖
+    // 从未产生 turn 的 session（打开未发消息即关闭）。cleanup 确认 flush（sessionFile 已出现）
+    // 则删 .imported，未 flush 保留供崩溃恢复重导入
+    try {
+      importCleanup?.()
+    } finally {
+      // MF-2：cleanup 抛非 ENOENT 错误（如 EACCES）也必须复位，避免残留闭包
+      importCleanup = undefined
     }
   })
 
   // 注册 schedule tool
   // execute 内联闭包：从 SDK 全签名 (toolCallId, params, signal, onUpdate, ctx) 提取 params 转调
-  // handler，并 catch 业务层抛出的错误转为 { isError: true }（standards.md §4.2 禁止抛）。
+  // handler。catch 兜底 INTERNAL + 未初始化异常（R3：handler 不 catch getService()，
+  // 初始化异常穿透到这里，保持 'Error: Scheduler not initialized' 格式）。
   pi.registerTool({
     name: 'schedule',
     label: 'Schedule',
@@ -76,7 +102,7 @@ export default function schedulerExtension(pi: ExtensionAPI): void {
       _ctx: ExtensionContext,
     ) {
       try {
-        return await createScheduleHandler(getRuntime())(params)
+        return await createScheduleHandler(getService())(params)
       } catch (err) {
         return {
           content: [{ type: 'text' as const, text: `Error: ${err instanceof Error ? err.message : String(err)}` }],
@@ -102,7 +128,7 @@ export default function schedulerExtension(pi: ExtensionAPI): void {
       _ctx: ExtensionContext,
     ) {
       try {
-        return await createScheduleControlHandler(getRuntime())(params)
+        return await createScheduleControlHandler(getService())(params)
       } catch (err) {
         return {
           content: [{ type: 'text' as const, text: `Error: ${err instanceof Error ? err.message : String(err)}` }],
@@ -113,15 +139,17 @@ export default function schedulerExtension(pi: ExtensionAPI): void {
     },
   })
 
-  // 注册 /schedule command。传 getter 而非 runtime 实例：factory 执行时 runtime 还是 null。
-  registerScheduleCommand(pi, () => runtime)
+  // 注册 /schedule command。传 getter 而非 service 实例：factory 执行时 service 还是 null。
+  registerScheduleCommand(pi, () => service)
 
   /**
    * 重新计算并推送 scheduler widget（string[] 重载）。
-   * 读外层 runtime 变量而非 getRuntime()：session_start 尚未触发时刷新不应报错，直接跳过。
+   * 读外层 service 变量而非 getService()：session_start 尚未触发时刷新不应报错，直接跳过。
    */
   function refreshWidget(ctx: ExtensionContext): void {
-    if (!runtime) return
-    ctx.ui.setWidget('scheduler', renderSchedulerWidget(runtime.listTasks()))
+    if (!service) return
+    const result = service.list()
+    if (!result.success || !result.data) return
+    ctx.ui.setWidget('scheduler', renderSchedulerWidget(result.data.tasks))
   }
 }

package/src/parsing.ts

@@ -180,7 +180,6 @@ export async function parseSchedule(
     if (nextRun !== undefined) {
       return {
         spec: { mode: 'cron', cronExpression: normalized.expression },
-        note: normalized.note,
       }
     }
   }
@@ -188,6 +187,25 @@ export async function parseSchedule(
   return undefined
 }
 
+/**
+ * 统一计算 schedule 的下次执行时间（IF-5：runtime 内唯一 nextRunAt 计算入口）。
+ * interval → from + intervalMs（from 缺省 Date.now()）；
+ * cron → 下次命中时间戳（> from）；cron 无效或 croner 不可用 → undefined。
+ * undefined 语义按调用方决策：addTask → 创建即抛错；
+ * toggleTask/dispatchTask 重算 → ERR-2 fallback（停用 + failed）。
+ */
+export async function computeNextRunAt(
+  spec: ScheduleSpec,
+  from?: number,
+): Promise<number | undefined> {
+  if (spec.mode === 'interval') {
+    const start = from ?? Date.now()
+    return start + spec.intervalMs
+  }
+
+  return computeNextCronRunAt(spec.cronExpression, from)
+}
+
 // ── Next Runs 计算 ──
 
 /**

package/src/replay.ts

@@ -0,0 +1,181 @@
+import type { ScheduledTask, SchedulerEntryOp, TaskSnapshot } from './types.js'
+
+/**
+ * CustomEntry 的最小可识别形状（duck-typed，不依赖 @earendil-works/pi-coding-agent 的
+ * 具体 SessionEntry 类型）。与 pending-notifications/state.ts、goal/ports.ts 同款：
+ * 纯函数可独立单测，调用方传入真实 SessionEntry[] 时按结构兼容。
+ */
+export interface SchedulerEntryLike {
+  type: string
+  customType?: string
+  data?: unknown
+}
+
+const HISTORY_LIMIT = 20
+
+/**
+ * 从 CustomEntry 序列折叠恢复 per-task 末态（event sourcing）。
+ *
+ * session_start 重放入口：PiSchedulerBackend.loadTasks() 委托本函数，把当前 session 的
+ * pi-scheduler:task custom entries 折叠成运行时任务 Map。
+ *
+ * 两步：
+ * ① 全量折叠——遍历 customType==='pi-scheduler:task' 的 entries，按 op 类型折叠：
+ *    - upsert → 用快照重建任务（ownerSessionFile 来自 op 顶层）
+ *    - advance → nextRunAt=新值 / lastRunAt=at / runCount++ / history.push(裁20) / lastStatus=status（gap2）
+ *    - toggle → enabled=新值
+ *    - delete → 从 Map 移除（后续同 taskId 的 advance/toggle 对不存在 taskId 为 no-op，安全）
+ *   advance/toggle/delete 对不存在的 taskId 为 no-op，因此 fork 继承的完整序列必须先全量折叠，
+ *   不能在处理 upsert 时按 owner 跳过（否则后续无 owner 字段的 op 会作用于「不存在的 taskId」丢失）。
+ * ② 折叠完成后按 task.ownerSessionFile !== currentSessionFile 整体过滤（gap1）：移除 fork
+ *   继承的非 owner 任务——fork 出的 session B 继承了 owner=A 的 upsert+advance 序列，但 B
+ *   不应拥有 A 的任务，重放后整体过滤掉。
+ *
+ * append-only 时序保证 nextRunAt 不回退（D1）：advance entry 按写入顺序折叠，自然取到最后推进值。
+ *
+ * getEntries 解析/迭代异常 → console.warn + 返回空 Map（gap4）：降级为无任务而非崩溃 session_start。
+ */
+export function replayFoldEntries(
+  entries: Iterable<SchedulerEntryLike>,
+  currentSessionFile: string | undefined,
+): Map<string, ScheduledTask> {
+  try {
+    const tasks = new Map<string, ScheduledTask>()
+
+    for (const entry of entries) {
+      if (entry.type !== 'custom' || entry.customType !== 'pi-scheduler:task') continue
+      if (!isSchedulerEntryOp(entry.data)) continue
+      const op = entry.data // SchedulerEntryOp（守卫 isSchedulerEntryOp 收窄）
+
+      try {
+        switch (op.op) {
+          case 'upsert': {
+            tasks.set(op.taskId, { ...snapshotToTask(op.task), ownerSessionFile: op.ownerSessionFile })
+            break
+          }
+          case 'advance': {
+            const task = tasks.get(op.taskId)
+            if (!task) break // no-op for unknown taskId（fork 场景安全）
+            task.nextRunAt = op.nextRunAt
+            task.lastRunAt = op.at
+            task.runCount += 1
+            task.history.push({ at: op.at, status: op.status })
+            if (task.history.length > HISTORY_LIMIT) task.history.shift()
+            task.lastStatus = op.status // gap2：advance 必须恢复 lastStatus（不只 nextRunAt/lastRunAt/runCount/history）
+            break
+          }
+          case 'toggle': {
+            const task = tasks.get(op.taskId)
+            if (!task) break
+            task.enabled = op.enabled
+            // P1：enable 重算到未来的 nextRunAt 随 toggle op 持久化；重放时应用，
+            // 防 upsert 快照回退到旧过期值导致首个 tick 立即触发
+            if (op.nextRunAt !== undefined) task.nextRunAt = op.nextRunAt
+            break
+          }
+          case 'delete': {
+            tasks.delete(op.taskId)
+            break
+          }
+        }
+      } catch (err) {
+        // MF-2：守卫已按变体校验必填字段，但嵌套数据损坏（如 upsert task.history 非数组 →
+        // snapshotToTask 的 .map 抛）仍可能抛——逐条 try/catch 只跳过该条，
+        // 不让外层整体 catch 把全部任务清成空 Map（一条损坏 entry 不得清空全部任务）
+        console.warn(
+          `[scheduler] skipping corrupted scheduler entry: ${err instanceof Error ? err.message : String(err)}`,
+        )
+        continue
+      }
+    }
+
+    // 步骤② fork owner 过滤（gap1）：折叠完成后整体移除非 owner 任务。
+    // currentSessionFile 为 undefined（--no-session 模式）时，所有带 ownerSessionFile 的任务都被移除
+    // （无 session 文件可归属，等同空 session）——该模式下 addTask 用 '' 兜底 owner，此处比较仍一致。
+    for (const [id, task] of tasks) {
+      if (task.ownerSessionFile !== currentSessionFile) {
+        tasks.delete(id)
+      }
+    }
+
+    return tasks
+  } catch (err) {
+    // gap4：session JSONL 损坏 / 迭代器抛错时降级为无任务，不让 session_start 崩溃。
+    console.warn(
+      `[scheduler] replayFoldEntries failed: ${err instanceof Error ? err.message : String(err)}`,
+    )
+    return new Map()
+  }
+}
+
+/**
+ * 类型守卫：判断 entry.data 是否为合法 SchedulerEntryOp——按 op 变体校验必填字段，
+ * 不只校验 op 判别值（MF-2 修复）。仅按判别值收窄时，损坏 entry `{op:'upsert'}`（缺 task）
+ * 会通过守卫后在 snapshotToTask(undefined) 抛 TypeError，被外层整体 catch 捕获 → 返回空 Map
+ * → 一条损坏 entry 清空全部任务（违反「只忽略该条」的设计意图）。
+ *
+ * 变体必填校验：
+ *   upsert  → taskId: string + task: 非 null 对象（嵌套字段损坏由重放循环内逐条 try/catch 兜底跳过）
+ *   advance → taskId: string + nextRunAt: number + at: number + status: 'success'
+ *   toggle  → taskId: string + enabled: boolean（nextRunAt?: number 可选——合法 toggle 可缺省，不能误拒）
+ *   delete  → taskId: string
+ * 校验不过 → 返回 false，该条被跳过（不触发整体 catch）。
+ *
+ * 替代 `as { op?: unknown }` 结构断言（taste/no-unsafe-cast）：守卫函数内做真实校验，
+ * Record<string, unknown> 配合 typeof/值校验，不是「无校验断言」。
+ */
+function isSchedulerEntryOp(data: unknown): data is SchedulerEntryOp {
+  if (!data || typeof data !== 'object') return false
+  const record = data as Record<string, unknown>
+  const op = record.op
+  if (op === 'upsert') {
+    return (
+      typeof record.taskId === 'string' &&
+      typeof record.task === 'object' &&
+      record.task !== null
+    )
+  }
+  if (op === 'advance') {
+    return (
+      typeof record.taskId === 'string' &&
+      typeof record.nextRunAt === 'number' &&
+      typeof record.at === 'number' &&
+      record.status === 'success'
+    )
+  }
+  if (op === 'toggle') {
+    return (
+      typeof record.taskId === 'string' &&
+      typeof record.enabled === 'boolean' &&
+      (record.nextRunAt === undefined || typeof record.nextRunAt === 'number')
+    )
+  }
+  if (op === 'delete') {
+    return typeof record.taskId === 'string'
+  }
+  return false
+}
+
+/**
+ * 从 TaskSnapshot 重建 ScheduledTask（剥离 pending——运行时标记不持久化）。
+ * history 深拷贝：避免快照与运行时 task 共享同一数组引用（upsert 后 task 继续被 mutate）。
+ */
+function snapshotToTask(snapshot: TaskSnapshot): ScheduledTask {
+  return {
+    id: snapshot.id,
+    name: snapshot.name,
+    prompt: snapshot.prompt,
+    kind: snapshot.kind,
+    schedule: snapshot.schedule,
+    enabled: snapshot.enabled,
+    force: snapshot.force,
+    createdAt: snapshot.createdAt,
+    nextRunAt: snapshot.nextRunAt,
+    expiresAt: snapshot.expiresAt,
+    runCount: snapshot.runCount,
+    lastRunAt: snapshot.lastRunAt,
+    lastStatus: snapshot.lastStatus,
+    lastError: snapshot.lastError,
+    history: snapshot.history.map(h => ({ ...h })),
+  }
+}