@zhushanwen/pi-scheduler 0.4.3 → 0.5.1

package/README.md

@@ -57,7 +57,7 @@ session_start
 
 ## /schedule 命令用法
 
-注册为 `/schedule` 命令。无参数时显示 usage；第一个参数匹配子命令关键词则走子命令分支，否则尝试创建任务。
+注册为 `/schedule` 命令。无参数时返回 TUI 未实现提示（用 `/schedule list` 查看任务）；第一个参数匹配子命令关键词则走子命令分支，否则尝试创建任务。
 
 ### 子命令
 
@@ -90,7 +90,7 @@ session_start
 
 ### duration（间隔调度）
 
-`<数字><单位>`，数字与单位间可有空格，**大小写不敏感**：
+`<数字><单位>`，数字与单位间不留空格，**大小写不敏感**：
 
 | 单位 | 含义 | 乘数 |
 |------|------|------|
@@ -163,14 +163,14 @@ session_start
 | 默认过期 | **7 天**（`DEFAULT_EXPIRY_MS`） | recurring 任务缺省 `expires` 时；`expires: 'never'` 关闭 |
 | once 任务 | 触发后自动删除 | 不参与后续调度 |
 | cron 失效 | 任务停用 + `lastStatus=failed` + `lastError='cron expression invalid'` | 不会用 `now()` 兜底导致每 tick 重触发死循环 |
-| 忙时 dispatch | 非 force 任务在 agent 忙（非 idle / 有 pending 消息）时跳过，延迟到下次 tick | force=true 可绕过 |
+| 忙时 dispatch | 非 force 任务经 session delivery 内核 park 模式：忙时消息入队等待（等 agent 空闲的 settled 边沿 / 下个 tick flush 投递），不丢弃 | force=true 绕过内核队列直投 |
 | 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`）。
+错误语义：创建时 schedule 解析失败 → `INVALID_SCHEDULE`；`run`/`toggle`/`delete` 引用不存在的 id → `TASK_NOT_FOUND`；`run` 时任务 disabled / rate-limited / 同任务已在投递队列（TTL 窗口内）→ `DISPATCH_SKIPPED`（message 含 `disabled, rate-limited, or already queued for delivery`）。
 
 ## 数据存储位置
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-scheduler",
-  "version": "0.4.3",
+  "version": "0.5.1",
   "type": "module",
   "main": "index.ts",
   "xyz-agent": {
@@ -45,8 +45,8 @@
     }
   },
   "dependencies": {
-    "@xyz-agent/session-delivery": "0.3.0",
-    "@zhushanwen/pi-extension-logger": "0.3.1"
+    "@xyz-agent/session-delivery": "0.3.1",
+    "@zhushanwen/pi-extension-logger": "0.4.1"
   },
   "scripts": {
     "test": "vitest run",

package/skills/scheduler-ext-config/SKILL.md

@@ -33,7 +33,7 @@ description: "使用或排查 @zhushanwen/pi-scheduler（定时任务调度）
 
 - **`schedule`**（创建）：参数 `prompt`（必填，到期注入的消息）、`schedule`（必填，duration 或 cron）、`kind`（`once`/`recurring`，默认 `recurring`）、`name`（可选，缺省从 prompt 自动截取前 30 字）、`expires`（可选，默认 7 天；传 `"never"` 关闭过期）、`force`（可选，默认 `false`）。
 - **`schedule_control`**（管理）：`action` = `list`/`toggle`/`delete`/`run`，`id`（toggle/delete/run 必填），`enabled`（toggle 必填）。
-- 两个工具的返回都是结构化 `{content: [{type:'text', text}], details, isError?}`，业务失败返回 `isError:true` + `details.errorCode`（不抛异常）。
+- 两个工具的返回都是结构化 `{content: [{type:'text', text}], details}`；业务失败以异常抛出（pi 只对 execute throw 置 `isError:true`，错误 message 作为 toolResult content 返回），不通过返回值表达失败。
 
 > 创建/管理操作无需 agent idle——只有**到期 dispatch** 才受 idle/速率限制约束（见「运行限制与 dispatch 行为」）。
 
@@ -52,7 +52,7 @@ description: "使用或排查 @zhushanwen/pi-scheduler（定时任务调度）
 | `h` | `hr`/`hour`/`hours` | 3_600_000 |
 | `d` | `day`/`days` | 86_400_000 |
 
-示例：`5m`、`2h`、`1d`、`30seconds`。正则 `/^(\d+)\s*(s|sec|...)$/i`，不匹配则解析失败。
+示例：`5m`、`2h`、`1d`、`30seconds`。正则 `/^(\d+)\s*(s|sec|...)$/i`（注意：含空格的输入在 parseSchedule 分流时一律走 cron 分支，duration 实际不允许空格，`5 m` 解析失败）。
 
 ### cron（cron 表达式）
 
@@ -119,7 +119,7 @@ description: "使用或排查 @zhushanwen/pi-scheduler（定时任务调度）
 
 dispatch 触发条件（`dispatchTask`）：
 
-- **非 force 任务**：仅在 `ctx.isIdle() && !ctx.hasPendingMessages()` 时触发；否则**延迟到下个 tick**（不丢弃，标记 `pending`，下个 30s tick 重试）。
+- **非 force 任务**：走统一 session delivery 内核（park 模式）——到期即入队，agent 忙时消息 park 在内核队列，等 agent 空闲的 settled 边沿投递，scheduler 每 30s tick 触发一次 flush 兜底重试；不丢弃。
 - **force=true 任务**：即使 agent busy 也立即触发（用于必须准点执行的场景）。
 - dispatch 成功后：recurring 推进 `nextRunAt` 并 append `advance`；once 删除任务并 append `delete`；失败（`sendMessage` 抛错）记 `lastStatus='failed'` 不 rethrow，下个 tick 重试（transient 失败重试语义，不 append advance）。
 - 注入的消息：`{content: task.prompt, customType: 'pi-scheduler:dispatched', display: true}`，`deliverAs: 'followUp'` + `triggerTurn: true`（排进 followUp 队列并唤醒 agent 开新 turn）。
@@ -137,7 +137,7 @@ dispatch 触发条件（`dispatchTask`）：
 - `force`：是否在 agent busy 时强制 dispatch。
 - `createdAt` / `nextRunAt` / `expiresAt?`：时间戳（ms）。
 - `runCount` / `lastRunAt?` / `lastStatus?`（`success`|`failed`）/ `lastError?`：执行统计。
-- `history`：最近 20 条 `ExecutionRecord`（`{at, status, snippet?}`，snippet 为 agent 回复前 100 字）。
+- `history`：最近 20 条 `ExecutionRecord`（`{at, status}`）。
 - `ownerSessionFile?`：归属 session JSONL 路径（fork 过滤用，非持久化业务字段）。
 - `pending?`：运行时标记「到期待 dispatch」，非持久化（与 `enabled` 正交）。
 

package/src/__tests__/commands.test.ts

@@ -181,6 +181,17 @@ describe('/schedule command', () => {
     expect(result).toBe('Usage: /schedule <schedule> <prompt>')
   })
 
+  it('treats prototype-chain key names as unknown (Map lookup, no Object.prototype hit)', async () => {
+    // 路由表用 Map 查找的语义锚：普通对象下标会把 "constructor"/"toString"/"__proto__"
+    // 解析到 Object.prototype（constructor 被当 handler 调用返回对象、__proto__ 直接 TypeError），
+    // 这里必须与其它未知子命令同走创建任务分支（无 schedule 输入 → usage 文案）。
+    for (const key of ['constructor', 'toString', '__proto__']) {
+      expect(await executeScheduleCommand(service, key)).toBe(
+        'Usage: /schedule <schedule> <prompt>',
+      )
+    }
+  })
+
   it('no args returns TUI not-implemented message', async () => {
     const result = await executeScheduleCommand(service, '')
     expect(result).toContain('not yet implemented')

package/src/__tests__/cron.test.ts

@@ -58,7 +58,7 @@ describe('computeNextCronRuns', () => {
 })
 
 describe('parseSchedule (cron 分支)', () => {
-  it('5 字段 cron 表达式补秒字段（note 不再透传到 parseSchedule 结果）', async () => {
+  it('5 字段 cron 表达式补秒字段', async () => {
     const result = await parseSchedule('*/10 * * * *')
     expect(result).toEqual({
       spec: { mode: 'cron', cronExpression: '0 */10 * * * *' },
@@ -85,8 +85,7 @@ describe('parseSchedule (cron 分支)', () => {
 
 describe('normalizeCronExpression', () => {
   it('6 字段 cron 原样返回', () => {
-    const result = normalizeCronExpression('0 9 * * 1-5 0')
-    expect(result).toEqual({ expression: '0 9 * * 1-5 0' })
+    expect(normalizeCronExpression('0 9 * * 1-5 0')).toBe('0 9 * * 1-5 0')
   })
 
   it('2 字段返回 undefined', () => {

package/src/__tests__/parsing.test.ts

@@ -84,16 +84,11 @@ describe('formatDuration', () => {
 
 describe('normalizeCronExpression', () => {
   it('prepends seconds field for 5-field cron', () => {
-    const result = normalizeCronExpression('*/10 * * * *')
-    expect(result).toEqual({
-      expression: '0 */10 * * * *',
-      note: 'Auto-prepended seconds field (0)',
-    })
+    expect(normalizeCronExpression('*/10 * * * *')).toBe('0 */10 * * * *')
   })
 
   it('keeps 6-field cron as-is', () => {
-    const result = normalizeCronExpression('0 */10 * * * *')
-    expect(result).toEqual({ expression: '0 */10 * * * *' })
+    expect(normalizeCronExpression('0 */10 * * * *')).toBe('0 */10 * * * *')
   })
 
   it('returns undefined for invalid field count', () => {

package/src/__tests__/replay.test.ts

@@ -310,6 +310,20 @@ describe('replayFoldEntries', () => {
     expect(msg).toContain('skipping corrupted scheduler entry')
   })
 
+  // ── fork 场景安全：未知 taskId 的 advance/toggle 为静默 no-op，不触发逐条 catch ──
+  it('advance/toggle 对不存在的 taskId 为 no-op（无 upsert 时不产生副作用、不触发逐条 catch warn）', () => {
+    loggerMock.warn.mockClear()
+    const entries = [
+      entry({ op: 'advance', taskId: 'ghost', nextRunAt: 200, at: 100, status: 'success' }),
+      entry({ op: 'toggle', taskId: 'ghost', enabled: false }),
+      entry({ op: 'delete', taskId: 'ghost' }),
+    ]
+    const result = replayFoldEntries(entries, '/s.json')
+    expect(result.size).toBe(0)
+    // no-op 提前返回路径不抛错——MF-2 的逐条跳过 warn 不应被触发
+    expect(loggerMock.warn).not.toHaveBeenCalled()
+  })
+
   afterEach(() => {
     vi.restoreAllMocks()
   })

package/src/__tests__/service.test.ts

@@ -191,7 +191,7 @@ describe('SchedulerService', () => {
       expect(result).toEqual({
         success: false,
         errorCode: 'DISPATCH_SKIPPED',
-        message: `Task ${id} not dispatched (busy, disabled, rate-limited, or a dispatch already in flight).`,
+        message: `Task ${id} not dispatched (disabled, rate-limited, or already queued for delivery).`,
       })
     })
 

package/src/commands.ts

@@ -48,7 +48,7 @@ export function registerScheduleCommand(
   getService: () => SchedulerService | null,
 ) {
   pi.registerCommand('schedule', {
-    description: 'Manage scheduled tasks. No args opens TUI. /schedule <schedule> <prompt> to create.',
+    description: 'Manage scheduled tasks. /schedule <schedule> <prompt> to create; /schedule list to see tasks.',
     getArgumentCompletions(prefix: string) {
       const service = getService()
       const trimmed = prefix.trimStart()
@@ -84,11 +84,77 @@ export function registerScheduleCommand(
   })
 }
 
+/** 单个子命令处理器。service 非空由 executeScheduleCommand 前置保证；parts 为 tokenize 后参数。 */
+type SubcommandHandler = (service: SchedulerService, parts: string[]) => string | Promise<string>
+
+/**
+ * on/off 共享：取 <id>，缺失返回 usage（文案与原 ${first} 一致——handler 仅在
+ * first === 'on' | 'off' 时被查表命中，keyword 即 first 的小写值）。
+ */
+async function handleToggleKeyword(
+  service: SchedulerService,
+  parts: string[],
+  keyword: 'on' | 'off',
+): Promise<string> {
+  const id = parts[1]
+  if (!id) return `Usage: /schedule ${keyword} <id>`
+  const result = await service.toggle(id, keyword === 'on')
+  return result.message
+}
+
+/**
+ * 子命令路由表。查表未命中（落空）= 创建任务分支，与原 if 链的顺序语义一致。
+ * list/rm 保持同步返回、run 保持 await——不改变 async 边界内的微任务时序。
+ * 用 Map 而非普通对象：first 是外部输入（/schedule 命令参数），普通对象查表会命中
+ * Object.prototype 上的键（如 "constructor"/"__proto__"），导致错误路由；Map 只查自身键。
+ */
+const SUBCOMMAND_HANDLERS: ReadonlyMap<string, SubcommandHandler> = new Map<string, SubcommandHandler>([
+  ['list', service => service.list().message],
+  ['on', (service, parts) => handleToggleKeyword(service, parts, 'on')],
+  ['off', (service, parts) => handleToggleKeyword(service, parts, 'off')],
+  [
+    'rm',
+    (service, parts) => {
+      const id = parts[1]
+      if (!id) return 'Usage: /schedule rm <id>'
+      return service.delete(id).message
+    },
+  ],
+  [
+    'run',
+    async (service, parts) => {
+      const id = parts[1]
+      if (!id) return 'Usage: /schedule run <id>'
+      const result = await service.run(id)
+      return result.message
+    },
+  ],
+])
+
+/** 创建任务分支（路由落空）：once 前缀 → once 任务；cron 前缀 → recurring cron 任务；其余按 interval schedule 解析。 */
+async function createTaskFromArgs(
+  service: SchedulerService,
+  parts: string[],
+  first: string,
+): Promise<string> {
+  const kind = first === 'once' ? 'once' as const : first === 'cron' ? 'recurring' as const : undefined
+  const scheduleStart = kind ? 1 : 0
+  const scheduleInput = parts[scheduleStart]
+  if (!scheduleInput) return 'Usage: /schedule <schedule> <prompt>'
+
+  const prompt = parts.slice(scheduleStart + 1).join(' ')
+  if (!prompt) return 'Usage: /schedule <schedule> <prompt>'
+
+  const result = await service.create(prompt, scheduleInput, { kind })
+  return result.message
+}
+
 /**
  * Core logic for /schedule command. Extracted for testability (handler returns
  * void per SDK contract; tests call this function directly to assert output).
  *
  * 命令层只保留参数路由与 usage 文案（C6），业务调用全部走 SchedulerService。
+ * 主函数只留编排：service 守卫 → 空 args → tokenize → 查表分发 → 创建分支。
  */
 export async function executeScheduleCommand(
   service: SchedulerService | null,
@@ -105,40 +171,9 @@ export async function executeScheduleCommand(
   const parts = tokenizeQuoted(trimmed)
   const first = parts[0]!.toLowerCase()
 
-  // 子命令路由
-  if (first === 'list') {
-    return service.list().message
-  }
-
-  if (first === 'on' || first === 'off') {
-    const id = parts[1]
-    if (!id) return `Usage: /schedule ${first} <id>`
-    const result = await service.toggle(id, first === 'on')
-    return result.message
-  }
-
-  if (first === 'rm') {
-    const id = parts[1]
-    if (!id) return 'Usage: /schedule rm <id>'
-    return service.delete(id).message
-  }
-
-  if (first === 'run') {
-    const id = parts[1]
-    if (!id) return 'Usage: /schedule run <id>'
-    const result = await service.run(id)
-    return result.message
-  }
+  // 子命令路由：查表命中走对应分支，落空走创建任务分支
+  const handler = SUBCOMMAND_HANDLERS.get(first)
+  if (handler) return handler(service, parts)
 
-  // 创建任务分支
-  const kind = first === 'once' ? 'once' as const : first === 'cron' ? 'recurring' as const : undefined
-  const scheduleStart = kind ? 1 : 0
-  const scheduleInput = parts[scheduleStart]
-  if (!scheduleInput) return 'Usage: /schedule <schedule> <prompt>'
-
-  const prompt = parts.slice(scheduleStart + 1).join(' ')
-  if (!prompt) return 'Usage: /schedule <schedule> <prompt>'
-
-  const result = await service.create(prompt, scheduleInput, { kind })
-  return result.message
+  return createTaskFromArgs(service, parts, first)
 }

package/src/format.ts

@@ -82,14 +82,10 @@ export function generateTaskId(): string {
 
 /** autoName 任务名最大长度。 */
 const AUTO_NAME_MAX_LENGTH = 30
-/** 截断后保留的长度（预留省略号宽度）。 */
-const AUTO_NAME_KEEP_LENGTH = AUTO_NAME_MAX_LENGTH - ELLIPSIS_LENGTH
 
 /**
  * 从 prompt 自动生成任务名称：取前 30 字。
  */
 export function autoName(prompt: string): string {
-  const trimmed = prompt.trim()
-  if (trimmed.length <= AUTO_NAME_MAX_LENGTH) return trimmed
-  return trimmed.slice(0, AUTO_NAME_KEEP_LENGTH) + '...'
+  return truncate(prompt.trim(), AUTO_NAME_MAX_LENGTH)
 }

package/src/parsing.ts

@@ -82,7 +82,7 @@ async function getCroner(): Promise<typeof import('croner') | null> {
  * 规范化 cron 表达式：5 字段自动补秒字段。
  * 返回 undefined 表示无效。
  */
-export function normalizeCronExpression(input: string): { expression: string; note?: string } | undefined {
+export function normalizeCronExpression(input: string): string | undefined {
   const trimmed = input.trim()
   if (!trimmed) return undefined
 
@@ -90,15 +90,12 @@ export function normalizeCronExpression(input: string): { expression: string; no
 
   // 6 字段原样返回
   if (parts.length === CRON_FIELD_COUNT_WITH_SECONDS) {
-    return { expression: trimmed }
+    return trimmed
   }
 
   // 5 字段补秒字段
   if (parts.length === CRON_FIELD_COUNT) {
-    return {
-      expression: `0 ${trimmed}`,
-      note: 'Auto-prepended seconds field (0)',
-    }
+    return `0 ${trimmed}`
   }
 
   return undefined
@@ -119,7 +116,7 @@ export async function computeNextCronRunAt(
     const normalized = normalizeCronExpression(expression)
     if (!normalized) return undefined
 
-    const job = new croner.Cron(normalized.expression, { startAt: from ? new Date(from) : undefined })
+    const job = new croner.Cron(normalized, { startAt: from ? new Date(from) : undefined })
     const next = job.nextRun()
     return next ? next.getTime() : undefined
   } catch {
@@ -143,7 +140,7 @@ export async function computeNextCronRuns(
     const normalized = normalizeCronExpression(expression)
     if (!normalized) return []
 
-    const job = new croner.Cron(normalized.expression, { startAt: from ? new Date(from) : undefined })
+    const job = new croner.Cron(normalized, { startAt: from ? new Date(from) : undefined })
     const runs: number[] = []
     let current = from ? new Date(from) : new Date()
 
@@ -192,7 +189,7 @@ export async function parseSchedule(
     const nextRun = await computeNextCronRunAt(trimmed)
     if (nextRun !== undefined) {
       return {
-        spec: { mode: 'cron', cronExpression: normalized.expression },
+        spec: { mode: 'cron', cronExpression: normalized },
       }
     }
   }

package/src/replay.ts

@@ -24,16 +24,16 @@ const HISTORY_LIMIT = 20
  * pi-scheduler:task custom entries 折叠成运行时任务 Map。
  *
  * 两步：
- * ① 全量折叠——遍历 customType==='pi-scheduler:task' 的 entries，按 op 类型折叠：
+ * ① 全量折叠（foldEntries）——遍历 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 的任务，重放后整体过滤掉。
+ * ② 折叠完成后按 task.ownerSessionFile !== currentSessionFile 整体过滤（gap1，filterNonOwnerTasks）：
+ *   移除 fork 继承的非 owner 任务——fork 出的 session B 继承了 owner=A 的 upsert+advance 序列，
+ *   但 B 不应拥有 A 的任务，重放后整体过滤掉。
  *
  * append-only 时序保证 nextRunAt 不回退（D1）：advance entry 按写入顺序折叠，自然取到最后推进值。
  *
@@ -45,61 +45,8 @@ export function replayFoldEntries(
 ): 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 不得清空全部任务）
-        logger.warn('skipping corrupted scheduler entry', { error: 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)
-      }
-    }
-
+    foldEntries(entries, tasks)
+    filterNonOwnerTasks(tasks, currentSessionFile)
     return tasks
   } catch (err) {
     // gap4：session JSONL 损坏 / 迭代器抛错时降级为无任务，不让 session_start 崩溃。
@@ -108,6 +55,97 @@ export function replayFoldEntries(
   }
 }
 
+/** 步骤① 全量折叠：跳过非本扩展 entry 与守卫不过的损坏 entry；单条折叠抛错只跳过该条（MF-2）。 */
+function foldEntries(entries: Iterable<SchedulerEntryLike>, tasks: Map<string, ScheduledTask>): void {
+  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 {
+      applyOp(tasks, op)
+    } catch (err) {
+      // MF-2：守卫已按变体校验必填字段，但嵌套数据损坏（如 upsert task.history 非数组 →
+      // snapshotToTask 的 .map 抛）仍可能抛——逐条 try/catch 只跳过该条，
+      // 不让外层整体 catch 把全部任务清成空 Map（一条损坏 entry 不得清空全部任务）
+      logger.warn('skipping corrupted scheduler entry', { error: err instanceof Error ? err.message : String(err) })
+      continue
+    }
+  }
+}
+
+/** 按 op 判别值分发到对应折叠函数；无 default——未知 op 静默跳过（守卫已排除，理论不可达）。 */
+function applyOp(tasks: Map<string, ScheduledTask>, op: SchedulerEntryOp): void {
+  switch (op.op) {
+    case 'upsert':
+      applyUpsert(tasks, op)
+      break
+    case 'advance':
+      applyAdvance(tasks, op)
+      break
+    case 'toggle':
+      applyToggle(tasks, op)
+      break
+    case 'delete':
+      applyDelete(tasks, op)
+      break
+  }
+}
+
+/** upsert → 用快照重建任务（ownerSessionFile 来自 op 顶层）。 */
+function applyUpsert(
+  tasks: Map<string, ScheduledTask>,
+  op: Extract<SchedulerEntryOp, { op: 'upsert' }>,
+): void {
+  tasks.set(op.taskId, { ...snapshotToTask(op.task), ownerSessionFile: op.ownerSessionFile })
+}
+
+/** advance → 推进运行末态；对不存在的 taskId 为 no-op（fork 场景安全）。 */
+function applyAdvance(
+  tasks: Map<string, ScheduledTask>,
+  op: Extract<SchedulerEntryOp, { op: 'advance' }>,
+): void {
+  const task = tasks.get(op.taskId)
+  if (!task) return // 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）
+}
+
+/** toggle → enabled=新值；携带 nextRunAt 时一并应用（P1，防快照回退到旧过期值）。 */
+function applyToggle(
+  tasks: Map<string, ScheduledTask>,
+  op: Extract<SchedulerEntryOp, { op: 'toggle' }>,
+): void {
+  const task = tasks.get(op.taskId)
+  if (!task) return
+  task.enabled = op.enabled
+  // P1：enable 重算到未来的 nextRunAt 随 toggle op 持久化；重放时应用，
+  // 防 upsert 快照回退到旧过期值导致首个 tick 立即触发
+  if (op.nextRunAt !== undefined) task.nextRunAt = op.nextRunAt
+}
+
+/** delete → 从 Map 移除；taskId 不存在时 no-op。 */
+function applyDelete(tasks: Map<string, ScheduledTask>, op: Extract<SchedulerEntryOp, { op: 'delete' }>): void {
+  tasks.delete(op.taskId)
+}
+
+/**
+ * 步骤② fork owner 过滤（gap1）：折叠完成后整体移除非 owner 任务。
+ * currentSessionFile 为 undefined（--no-session 模式）时，所有带 ownerSessionFile 的任务都被移除
+ * （无 session 文件可归属，等同空 session）——该模式下 addTask 用 '' 兜底 owner，此处比较仍一致。
+ */
+function filterNonOwnerTasks(tasks: Map<string, ScheduledTask>, currentSessionFile: string | undefined): void {
+  for (const [id, task] of tasks) {
+    if (task.ownerSessionFile !== currentSessionFile) {
+      tasks.delete(id)
+    }
+  }
+}
+
 /**
  * 类型守卫：判断 entry.data 是否为合法 SchedulerEntryOp——按 op 变体校验必填字段，
  * 不只校验 op 判别值（MF-2 修复）。仅按判别值收窄时，损坏 entry `{op:'upsert'}`（缺 task）

package/src/runtime.ts

@@ -505,10 +505,4 @@ export class SchedulerRuntime {
     const { ownerSessionFile: _o, pending: _p, history, ...rest } = task
     return { ...rest, history: history.slice() }
   }
-
-  // ── 工具方法 ──
-
-  getTaskCount(): number {
-    return this.tasks.size
-  }
 }

package/src/service.ts

@@ -137,7 +137,8 @@ export class SchedulerService {
   /**
    * 立即执行任务。语义细分：
    * 任务不存在 → TASK_NOT_FOUND；任务存在但 dispatch no-op
-   * （disabled / busy / rate-limited / 同任务 dispatch 在途）→ DISPATCH_SKIPPED。
+   * （disabled / rate-limited / 同任务入队已在 TTL 窗口内）→ DISPATCH_SKIPPED。
+   * busy 不再是 no-op：非 force 任务入队 delivery 内核即成功（park 等后续投递）。
    * 修复了旧实现把 no-op 误报为 not found 的混同。
    */
   async run(id: string | undefined): Promise<ServiceResult> {
@@ -152,7 +153,7 @@ export class SchedulerService {
       return {
         success: false,
         errorCode: 'DISPATCH_SKIPPED',
-        message: `Task ${id} not dispatched (busy, disabled, rate-limited, or a dispatch already in flight).`,
+        message: `Task ${id} not dispatched (disabled, rate-limited, or already queued for delivery).`,
       }
     }
     return { success: true, message: `Task ${id} executed.` }

package/src/tool.ts

@@ -11,7 +11,7 @@ export const ScheduleParams = Type.Object({
   schedule: Type.String({ description: 'Schedule spec: duration (5m/2h/1d) for interval, or cron expression (*/10 * * * *).' }),
   kind: Type.Optional(Type.Union([Type.Literal('once'), Type.Literal('recurring')], { description: 'Task kind. Default: recurring.' })),
   name: Type.Optional(Type.String({ description: 'Human-readable task name. Auto-generated from prompt if omitted.' })),
-  expires: Type.Optional(Type.String({ description: 'Expiry duration (30m/2h/7d). Default: 7d. Pass "never" to disable.' })),
+  expires: Type.Optional(Type.String({ description: 'Expiry duration (30m/2h/7d). Default: 7d. Pass "never" to disable. Only applies to recurring tasks (once tasks fire and are removed, expires is ignored).' })),
   force: Type.Optional(Type.Boolean({ description: 'Dispatch even when agent is busy. Default: false.' })),
 })
 
@@ -53,7 +53,7 @@ export const controlGuidelines = [
   'Use action="list" to see all scheduled tasks.',
   'After listing, use the returned id for toggle/delete/run.',
   'Prefer toggle(enabled=false) over delete for temporary pauses.',
-  'action="run" fires the task immediately.',
+  'action="run" dispatches the task now: force tasks are sent directly; non-force tasks are enqueued via the delivery kernel and delivered once the agent is idle (busy messages wait in the queue and are flushed later).',
 ]
 
 export function createScheduleControlHandler(service: SchedulerService) {

package/src/types.ts

@@ -32,7 +32,6 @@ export interface ScheduledTask {
 export interface ExecutionRecord {
   at: number
   status: TaskStatus
-  snippet?: string                  // agent 回复前 100 字
 }
 
 // ── CustomEntry event sourcing（append-only 任务存储）──

package/vitest.config.ts

@@ -2,6 +2,8 @@ import { defineConfig } from 'vitest/config'
 
 export default defineConfig({
   test: {
+    reporters: ['default', 'junit'],
+    outputFile: { junit: './test-results/vitest-junit.xml' },
     include: ['src/__tests__/**/*.test.ts'],
   },
 })