@zhushanwen/pi-scheduler 0.3.3 → 0.4.0

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "@zhushanwen/pi-scheduler",
-  "version": "0.3.3",
+  "version": "0.4.0",
   "type": "module",
   "main": "index.ts",
+  "xyz-agent": {
+    "role": "universal"
+  },
   "pi": {
     "extensions": [
       "./index.ts"
@@ -26,7 +29,7 @@
     "vitest.config.ts"
   ],
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-coding-agent": "^0.84.1",
     "croner": "^9.0.0",
     "typebox": "*"
   },
@@ -41,6 +44,9 @@
       "optional": true
     }
   },
+  "dependencies": {
+    "@xyz-agent/session-delivery": "0.2.0"
+  },
   "scripts": {
     "test": "vitest run",
     "test:watch": "vitest"

package/src/__tests__/U4-AFTER_RUN_INTENT.test.ts

@@ -0,0 +1,99 @@
+/**
+ * U4_AFTER_RUN_INTENT：after-run intent 映射验收
+ *
+ * 两个子用例：
+ * (1) 装配层 createDelivery config.intent='after-run'，dispatchTask 后 port.send 收到 intent='after-run'
+ * (2) 现有 sendMessage 调用参数验证——force 路径 backend.sendMessage 参数为 {deliverAs:'followUp', triggerTurn:true}
+ */
+import { describe, expect, it, vi } from 'vitest'
+
+import { MockSchedulerBackend } from '../backend.js'
+import { SchedulerRuntime } from '../runtime.js'
+
+describe('U4_AFTER_RUN_INTENT: intent 映射', () => {
+  it('(1) dispatchTask 通过 delivery → port.send 收到 intent=after-run', async () => {
+    // 内核级 mock：记录 port.send 的 intent 参数
+    const sentIntents: string[] = []
+    const mockDelivery = {
+      send: vi.fn((msg: any) => {
+        // delivery handle 的 send 不直接暴露 intent（intent 在 createDelivery config 中）
+        // 但我们可以验证 send 被调用（入队），intent 由内核传递给 port.send
+        sentIntents.push(msg.intent ?? 'config-default')
+      }),
+      sendChecked: vi.fn(),
+      flush: vi.fn(),
+      depth: vi.fn(() => 0),
+      dispose: vi.fn(),
+    }
+    const backend = new MockSchedulerBackend()
+    backend.deliveryHandle = mockDelivery as any
+    const runtime = new SchedulerRuntime(backend, { isIdle: () => true, hasPendingMessages: () => false })
+
+    const task = await runtime.addTask('intent-test', { mode: 'interval', intervalMs: 60_000 })
+    await runtime.dispatchTask(task)
+
+    // delivery.send 被调用
+    expect(mockDelivery.send).toHaveBeenCalledTimes(1)
+    // send 调用的 payload 包含正确的 content
+    expect(mockDelivery.send).toHaveBeenCalledWith(
+      expect.objectContaining({
+        payload: expect.objectContaining({
+          kind: 'custom',
+          customType: 'pi-scheduler:dispatched',
+          content: 'intent-test',
+          display: true,
+        }),
+        intent: 'after-run',
+      }),
+    )
+    // 不直调 backend.sendMessage
+    expect(backend.sentMessages).toHaveLength(0)
+  })
+
+  it('(2) force 路径直调 sendMessage 参数等价（deliverAs:followUp + triggerTurn:true）', async () => {
+    const backend = new MockSchedulerBackend()
+    const runtime = new SchedulerRuntime(backend, { isIdle: () => true, hasPendingMessages: () => false })
+
+    const task = await runtime.addTask(
+      'force-intent',
+      { mode: 'interval', intervalMs: 60_000 },
+      { force: true },
+    )
+    await runtime.dispatchTask(task)
+
+    // force 直投走 backend.sendMessage
+    expect(backend.sentMessages).toHaveLength(1)
+    expect(backend.sentMessages[0]!.msg).toEqual(
+      expect.objectContaining({
+        content: 'force-intent',
+        customType: 'pi-scheduler:dispatched',
+        display: true,
+      }),
+    )
+    // 迁移后参数与迁移前一致
+    expect(backend.sentMessages[0]!.opts).toEqual({
+      deliverAs: 'followUp',
+      triggerTurn: true,
+    })
+  })
+
+  it('(3) 有 delivery handle 时非 force 任务不直投 backend.sendMessage', async () => {
+    const mockDelivery = {
+      send: vi.fn(),
+      sendChecked: vi.fn(),
+      flush: vi.fn(),
+      depth: vi.fn(() => 0),
+      dispose: vi.fn(),
+    }
+    const backend = new MockSchedulerBackend()
+    backend.deliveryHandle = mockDelivery as any
+    const runtime = new SchedulerRuntime(backend, { isIdle: () => true, hasPendingMessages: () => false })
+
+    const task = await runtime.addTask('delivery-only-test', { mode: 'interval', intervalMs: 60_000 })
+    const dispatched = await runtime.dispatchTask(task)
+
+    expect(dispatched).toBe(true)
+    expect(mockDelivery.send).toHaveBeenCalledTimes(1)
+    expect(backend.sentMessages).toHaveLength(0)
+  })
+})

package/src/__tests__/U4-DISPATCH_INFLIGHT.test.ts

@@ -0,0 +1,107 @@
+/**
+ * U4_DISPATCH_INFLIGHT：调用方 in-flight 守卫验收
+ *
+ * 两个子用例：
+ * (1) 同一 taskId 的 dispatchTask 并发调用 → 第二次立即返回 false + console.warn
+ * (2) 第一次 dispatchTask 完成后（finally 清除）→ 第二次正常执行
+ *
+ * 断言 delivery send 调用总次数为 1（拦截场景）或 2（串行场景）。
+ */
+import { describe, expect, it, vi } from 'vitest'
+
+import { MockSchedulerBackend } from '../backend.js'
+import { SchedulerRuntime } from '../runtime.js'
+
+describe('U4_DISPATCH_INFLIGHT: 调用方 in-flight 守卫', () => {
+  it('(1) 同一 taskId 并发 dispatch → 第二次被拦截（send 只调 1 次 + warn）', async () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+
+    // 可控延迟的 sendMessage：让第一次 dispatch 挂起
+    let resolveSend: (() => void) | undefined
+    const sendPromise = new Promise<void>(resolve => {
+      resolveSend = resolve
+    })
+    const backend = new MockSchedulerBackend()
+    backend.sendMessage = vi.fn(() => sendPromise)
+    const runtime = new SchedulerRuntime(backend, { isIdle: () => true, hasPendingMessages: () => false })
+
+    const task = await runtime.addTask(
+      'inflight-test',
+      { mode: 'interval', intervalMs: 60_000 },
+      { force: true },
+    )
+
+    // 第一次 dispatch（挂起）
+    const first = runtime.dispatchTask(task)
+    // sendMessage 被调 1 次
+    expect(backend.sendMessage).toHaveBeenCalledTimes(1)
+
+    // 第二次 dispatch（同一 taskId，在途被拦截）
+    const second = await runtime.dispatchTask(task)
+    expect(second).toBe(false)
+
+    // warn 包含 in-flight 提示
+    const warnText = warnSpy.mock.calls.map(c => String(c[0])).join('\n')
+    expect(warnText).toContain('already in flight')
+
+    // sendMessage 仍只有 1 次（拦截有效）
+    expect(backend.sendMessage).toHaveBeenCalledTimes(1)
+
+    // 放行第一次 dispatch
+    resolveSend!()
+    await first
+
+    warnSpy.mockRestore()
+  })
+
+  it('(2) 第一次完成后 → 第二次 dispatchTask 正常执行（send 调 2 次）', async () => {
+    const backend = new MockSchedulerBackend()
+    const runtime = new SchedulerRuntime(backend, { isIdle: () => true, hasPendingMessages: () => false })
+
+    const task = await runtime.addTask(
+      'serial-inflight',
+      { mode: 'interval', intervalMs: 60_000 },
+      { force: true },
+    )
+
+    // 第一次 dispatch（串行等待完成）
+    const first = await runtime.dispatchTask(task)
+    expect(first).toBe(true)
+    expect(backend.sentMessages).toHaveLength(1)
+
+    // 第二次 dispatch（in-flight 已清除，正常执行）
+    // 需要重置 nextRunAt 让任务再次到期
+    task.nextRunAt = 0
+    const second = await runtime.dispatchTask(task)
+    expect(second).toBe(true)
+
+    // send 被调 2 次（串行完成）
+    expect(backend.sentMessages).toHaveLength(2)
+  })
+
+  it('(3) 非 force + 有 delivery handle 时，in-flight 守卫同样拦截并发 dispatch', async () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    const backend = new MockSchedulerBackend()
+    backend.deliveryHandle = {
+      send: vi.fn(),
+      sendChecked: vi.fn(),
+      flush: vi.fn(),
+      depth: vi.fn(() => 0),
+      dispose: vi.fn(),
+    } as any
+    const runtime = new SchedulerRuntime(backend, { isIdle: () => true, hasPendingMessages: () => false })
+
+    const task = await runtime.addTask('delivery-inflight', { mode: 'interval', intervalMs: 60_000 })
+
+    const first = runtime.dispatchTask(task)
+    const second = await runtime.dispatchTask(task)
+
+    expect(await first).toBe(true)
+    expect(second).toBe(false)
+    expect(backend.deliveryHandle.send).toHaveBeenCalledTimes(1)
+
+    const warnText = warnSpy.mock.calls.map(c => String(c[0])).join('\n')
+    expect(warnText).toContain('already in flight')
+    warnSpy.mockRestore()
+  })
+})

package/src/__tests__/U4-ONSETTLED.test.ts

@@ -0,0 +1,124 @@
+/**
+ * U4_ONSETTLED：onSettled 失败记账验收
+ *
+ * 三条子用例：
+ * (1) delivery send 抛错 → task.lastStatus='failed' + history 追加 + pending=false
+ * (2) once 任务 send 抛错 → task 不从 tasks Map 删除、不 append delete op（at-least-once）
+ * (3) recurring 任务 send 成功 → task.lastStatus='success' + nextRunAt 推进 + append advance op
+ *
+ * 断言 backend.appendedOps 含预期 op 类型。
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { MockSchedulerBackend } from '../backend.js'
+import type { DeliveryMessage } from '@xyz-agent/session-delivery'
+
+import { SchedulerRuntime } from '../runtime.js'
+
+/** 构造 delivery onSettled 回调入参消息（dispatchViaDelivery 挂 dedupeKey=task.id）。 */
+function settledMsg(content: string, taskId: string): DeliveryMessage {
+  return {
+    payload: {
+      kind: 'custom',
+      customType: 'pi-scheduler:dispatched',
+      content,
+      display: true,
+    },
+    intent: 'after-run',
+    dedupeKey: taskId,
+  }
+}
+
+describe('U4_ONSETTLED: onSettled 失败记账', () => {
+  beforeEach(() => {
+    vi.useFakeTimers()
+    vi.setSystemTime(new Date('2026-01-01T00:00:00Z'))
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  it('(1) delivery onSettled rejected → task.lastStatus=failed + history + pending=false', async () => {
+    const backend = new MockSchedulerBackend()
+    const runtime = new SchedulerRuntime(backend, { isIdle: () => true, hasPendingMessages: () => false })
+
+    const task = await runtime.addTask('rejected-test', { mode: 'interval', intervalMs: 60_000 })
+
+    // 模拟 delivery onSettled rejected 回调（dedupeKey=task.id 反查）
+    runtime.handleSettled(settledMsg('rejected-test', task.id), 'rejected')
+
+    expect(task.lastStatus).toBe('failed')
+    expect(task.history[task.history.length - 1]!.status).toBe('failed')
+    // pending 在 addTask 时未设置（undefined），dispatchViaDelivery 中显式清除为 false
+    // rejected 回调不修改 pending，保持 dispatchViaDelivery 后的 false 状态
+    expect(task.pending).toBeFalsy()
+  })
+
+  it('(2) once 任务 rejected → task 不删（at-least-once 语义）', async () => {
+    const backend = new MockSchedulerBackend()
+    const runtime = new SchedulerRuntime(backend, { isIdle: () => true, hasPendingMessages: () => false })
+
+    const task = await runtime.addTask(
+      'once-rejected',
+      { mode: 'interval', intervalMs: 60_000 },
+      { kind: 'once' },
+    )
+    const taskId = task.id
+
+    // 模拟 delivery onSettled rejected
+    runtime.handleSettled(settledMsg('once-rejected', taskId), 'rejected')
+
+    // once 任务失败不删——任务仍在 Map 中
+    expect(runtime.getTask(taskId)).toBeDefined()
+    expect(task.lastStatus).toBe('failed')
+    // 不应 append delete op（失败不删持久化）
+    const deleteOps = backend.appendedOps.filter(
+      op => op.op === 'delete' && 'taskId' in op && op.taskId === taskId,
+    )
+    expect(deleteOps).toHaveLength(0)
+  })
+
+  it('(2b) 通过 handleSettled rejected 触发时，任务不删除且保留失败历史', async () => {
+    const backend = new MockSchedulerBackend()
+    const runtime = new SchedulerRuntime(backend, { isIdle: () => true, hasPendingMessages: () => false })
+
+    const task = await runtime.addTask(
+      'once-rejected-via-handler',
+      { mode: 'interval', intervalMs: 60_000 },
+      { kind: 'once' },
+    )
+
+    runtime.handleSettled(settledMsg('once-rejected-via-handler', task.id), 'rejected')
+
+    expect(task.lastStatus).toBe('failed')
+    expect(task.history[task.history.length - 1]!.status).toBe('failed')
+    expect(runtime.getTask(task.id)).toBeDefined()
+  })
+
+  it('(3) recurring 任务 delivered → lastStatus=success + nextRunAt 推进 + append advance', async () => {
+    const backend = new MockSchedulerBackend()
+    const runtime = new SchedulerRuntime(backend, { isIdle: () => true, hasPendingMessages: () => false })
+
+    const task = await runtime.addTask('delivered-test', { mode: 'interval', intervalMs: 60_000 })
+    const oldNextRunAt = task.nextRunAt
+    // 时间前进：让 onDispatchSuccess 的 computeNextRunAt 基于更晚的时间计算
+    vi.setSystemTime(new Date('2026-01-01T00:01:01Z'))
+
+    // 模拟 delivery onSettled delivered
+    runtime.handleSettled(settledMsg('delivered-test', task.id), 'delivered')
+
+    // onDispatchSuccess 是 async，等一个 microtask
+    await vi.waitFor(() => {
+      expect(task.lastStatus).toBe('success')
+    })
+
+    expect(task.runCount).toBe(1)
+    expect(task.lastError).toBeUndefined()
+    // nextRunAt 推进到未来
+    expect(task.nextRunAt).toBeGreaterThan(oldNextRunAt)
+    // append advance op
+    const advanceOps = backend.appendedOps.filter(op => op.op === 'advance')
+    expect(advanceOps.length).toBeGreaterThanOrEqual(1)
+  })
+})

package/src/__tests__/U4-PARK_GATE.test.ts

@@ -0,0 +1,206 @@
+/**
+ * U4_PARK_GATE：park 模式 gate 行为验收
+ *
+ * 三条子用例：
+ * (1) isIdle=false 时 dispatchTask → delivery 入队（busy 不直投，等 tick 重触发）
+ * (2) isIdle=false → flush() 外部调用 → 任务被投递（tick 外部重触发路径）
+ * (3) force=true 时绕过 gate 直投（即使 isIdle=false 也 sendMessage）
+ *
+ * 断言 delivery send 调用次数和 intent 参数。
+ */
+import { describe, expect, it, vi } from 'vitest'
+
+import { MockSchedulerBackend } from '../backend.js'
+import { SchedulerRuntime } from '../runtime.js'
+
+describe('U4_PARK_GATE: park 模式 gate 行为', () => {
+  it('(1) isIdle=false 时 dispatchTask → delivery 入队不直投', async () => {
+    // busy ctx：isIdle()=false
+    const busyCtx = { isIdle: () => false, hasPendingMessages: () => true }
+    const mockDelivery = {
+      send: vi.fn(),
+      sendChecked: vi.fn(),
+      flush: vi.fn(),
+      depth: vi.fn(() => 0),
+      dispose: vi.fn(),
+    }
+    const backend = new MockSchedulerBackend()
+    backend.deliveryHandle = mockDelivery as any
+    const runtime = new SchedulerRuntime(backend, busyCtx)
+
+    const task = await runtime.addTask('park-gate-test', { mode: 'interval', intervalMs: 60_000 })
+    const dispatched = await runtime.dispatchTask(task)
+
+    // dispatchViaDelivery 入队成功返回 true
+    expect(dispatched).toBe(true)
+    // delivery.send 被调用 1 次（入队），backend.sendMessage 未被直调
+    expect(mockDelivery.send).toHaveBeenCalledTimes(1)
+    expect(mockDelivery.send).toHaveBeenCalledWith(
+      expect.objectContaining({
+        payload: expect.objectContaining({ content: 'park-gate-test' }),
+      }),
+    )
+    // 不直调 backend.sendMessage（非 force 走 delivery）
+    expect(backend.sentMessages).toHaveLength(0)
+    // pending 在 dispatchViaDelivery 后清除
+    expect(task.pending).toBe(false)
+  })
+
+  it('(2) isIdle=false → flush() 外部调用 → 队列消息被投递', async () => {
+    const busyCtx = { isIdle: () => false, hasPendingMessages: () => true }
+    // 内核级 flush 模拟：调用 port.send 投递已入队的消息
+    const portSendCalls: Array<{ msg: unknown; intent: string }> = []
+    const mockPort = {
+      supportedPayloads: ['custom'] as const,
+      isIdle: () => false,
+      hasPendingMessages: () => true,
+      send: vi.fn((msg: any, intent: string) => {
+        portSendCalls.push({ msg, intent })
+      }),
+    }
+    // 使用真实 createDelivery 但 mock port——验证 park 模式下 flush 触发投递
+    // 但为了隔离测试，直接用 mock delivery handle 模拟 flush 行为
+    let flushed = false
+    const mockDelivery = {
+      send: vi.fn(),
+      sendChecked: vi.fn(),
+      flush: vi.fn(() => { flushed = true }),
+      depth: vi.fn(() => (flushed ? 0 : 1)),
+      dispose: vi.fn(),
+    }
+    const backend = new MockSchedulerBackend()
+    backend.deliveryHandle = mockDelivery as any
+    const runtime = new SchedulerRuntime(backend, busyCtx)
+
+    await runtime.addTask('flush-test', { mode: 'interval', intervalMs: 60_000 })
+    // 模拟 tickScheduler：dispatchTask 入队 + tick 末尾 flush
+    // 直接调 flush 验证外部触发路径
+    mockDelivery.flush()
+
+    expect(mockDelivery.flush).toHaveBeenCalledTimes(1)
+    expect(flushed).toBe(true)
+  })
+
+  it('(4) busy ctx 下 flush 由 tick 显式触发，而非内核自动重试', async () => {
+    const busyCtx = { isIdle: () => false, hasPendingMessages: () => true }
+    const mockDelivery = {
+      send: vi.fn(),
+      sendChecked: vi.fn(),
+      flush: vi.fn(),
+      depth: vi.fn(() => 1),
+      dispose: vi.fn(),
+    }
+    const backend = new MockSchedulerBackend()
+    backend.deliveryHandle = mockDelivery as any
+    const runtime = new SchedulerRuntime(backend, busyCtx)
+
+    const task = await runtime.addTask('tick-flush', { mode: 'interval', intervalMs: 60_000 })
+    await runtime.dispatchTask(task)
+
+    expect(mockDelivery.send).toHaveBeenCalledTimes(1)
+    expect(mockDelivery.flush).not.toHaveBeenCalled()
+
+    await runtime.tickScheduler()
+
+    expect(mockDelivery.flush).toHaveBeenCalledTimes(1)
+    expect(backend.sentMessages).toHaveLength(0)
+  })
+
+  it('(3) force=true 时绕过 delivery 直投（即使 isIdle=false 也 sendMessage）', async () => {
+    const busyCtx = { isIdle: () => false, hasPendingMessages: () => true }
+    const mockDelivery = {
+      send: vi.fn(),
+      sendChecked: vi.fn(),
+      flush: vi.fn(),
+      depth: vi.fn(() => 0),
+      dispose: vi.fn(),
+    }
+    const backend = new MockSchedulerBackend()
+    backend.deliveryHandle = mockDelivery as any
+    const runtime = new SchedulerRuntime(backend, busyCtx)
+
+    const task = await runtime.addTask(
+      'force-bypass-test',
+      { mode: 'interval', intervalMs: 60_000 },
+      { force: true },
+    )
+    const dispatched = await runtime.dispatchTask(task)
+
+    // force 任务直投成功
+    expect(dispatched).toBe(true)
+    // delivery.send 不被调用（force 绕过 delivery）
+    expect(mockDelivery.send).not.toHaveBeenCalled()
+    // backend.sendMessage 被直调
+    expect(backend.sentMessages).toHaveLength(1)
+    expect(backend.sentMessages[0]!.msg.content).toBe('force-bypass-test')
+    expect(backend.sentMessages[0]!.opts).toEqual(
+      expect.objectContaining({ deliverAs: 'followUp', triggerTurn: true }),
+    )
+  })
+
+  it('(5) 到期任务 + 持续 busy 多 tick 不重复入队；settled 后可再入队（回归：nextRunAt 未推进期曾每 tick 重压副本）', async () => {
+    const busyCtx = { isIdle: () => false, hasPendingMessages: () => true }
+    const mockDelivery = {
+      send: vi.fn(),
+      sendChecked: vi.fn(),
+      flush: vi.fn(),
+      depth: vi.fn(() => 1),
+      dispose: vi.fn(),
+    }
+    const backend = new MockSchedulerBackend()
+    backend.deliveryHandle = mockDelivery as any
+    const runtime = new SchedulerRuntime(backend, busyCtx)
+
+    const task = await runtime.addTask('dup-test', { mode: 'interval', intervalMs: 60_000 })
+    // 任务到期（nextRunAt 已过）
+    task.nextRunAt = backend.now() - 1
+
+    // 3 个连续 tick：每次 step2 都会重标 pending，防重标记应拦截重复入队
+    await runtime.tickScheduler()
+    await runtime.tickScheduler()
+    await runtime.tickScheduler()
+    expect(mockDelivery.send).toHaveBeenCalledTimes(1)
+
+    // 终态回调（delivered）清除标记 + 记账推进 nextRunAt → 下轮到期可再入队
+    runtime.handleSettled(
+      { payload: { kind: 'custom', customType: 'pi-scheduler:dispatched', content: 'dup-test', display: true }, dedupeKey: task.id },
+      'delivered',
+    )
+    // onDispatchSuccess 为 fire-and-forget async，等微任务落定后再断言
+    await new Promise((r) => setTimeout(r, 0))
+    expect(task.lastStatus).toBe('success')
+    expect(task.nextRunAt).toBeGreaterThan(backend.now())
+
+    task.nextRunAt = backend.now() - 1
+    await runtime.tickScheduler()
+    expect(mockDelivery.send).toHaveBeenCalledTimes(2)
+  })
+
+  it('(6) rejected 终态同样清除防重标记', async () => {
+    const busyCtx = { isIdle: () => false, hasPendingMessages: () => true }
+    const mockDelivery = {
+      send: vi.fn(),
+      sendChecked: vi.fn(),
+      flush: vi.fn(),
+      depth: vi.fn(() => 1),
+      dispose: vi.fn(),
+    }
+    const backend = new MockSchedulerBackend()
+    backend.deliveryHandle = mockDelivery as any
+    const runtime = new SchedulerRuntime(backend, busyCtx)
+
+    const task = await runtime.addTask('reject-test', { mode: 'interval', intervalMs: 60_000 })
+    task.nextRunAt = backend.now() - 1
+    await runtime.tickScheduler()
+    expect(mockDelivery.send).toHaveBeenCalledTimes(1)
+
+    runtime.handleSettled(
+      { payload: { kind: 'custom', customType: 'pi-scheduler:dispatched', content: 'reject-test', display: true }, dedupeKey: task.id },
+      'rejected',
+    )
+    expect(task.lastStatus).toBe('failed')
+
+    await runtime.tickScheduler()
+    expect(mockDelivery.send).toHaveBeenCalledTimes(2)
+  })
+})

package/src/__tests__/runtime.test.ts

@@ -1,4 +1,5 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import type { DeliveryMessage } from '@xyz-agent/session-delivery'
 
 import { MockSchedulerBackend } from '../backend.js'
 import { SchedulerRuntime } from '../runtime.js'
@@ -7,6 +8,20 @@ import { SchedulerRuntime } from '../runtime.js'
 
 const mockCtx = { isIdle: () => true, hasPendingMessages: () => false }
 
+/** 构造 delivery onSettled 回调入参消息（dispatchViaDelivery 挂 dedupeKey=task.id）。 */
+function settledMsg(content: string, taskId: string): DeliveryMessage {
+  return {
+    payload: {
+      kind: 'custom',
+      customType: 'pi-scheduler:dispatched',
+      content,
+      display: true,
+    },
+    intent: 'after-run',
+    dedupeKey: taskId,
+  }
+}
+
 describe('SchedulerRuntime', () => {
   let backend: MockSchedulerBackend
   let runtime: SchedulerRuntime
@@ -114,13 +129,14 @@ describe('SchedulerRuntime', () => {
       expect(backend.sentMessages).toHaveLength(0)
     })
 
-    it('skips when not idle and force is false', async () => {
+    it('non-force 任务在 busy 时走 delivery 入队（不直调 sendMessage）', async () => {
       const busyCtx = { isIdle: () => false, hasPendingMessages: () => false }
       const busyBackend = new MockSchedulerBackend()
       const busyRuntime = new SchedulerRuntime(busyBackend, busyCtx)
       const task = await busyRuntime.addTask('test', { mode: 'interval', intervalMs: 60000 })
+      // 无 delivery handle 时走 dispatchDirect（直投），busy 不影响（直投不检查 idle）
       await busyRuntime.dispatchTask(task)
-      expect(busyBackend.sentMessages).toHaveLength(0)
+      expect(busyBackend.sentMessages).toHaveLength(1)
     })
 
     it('dispatches when force is true even if busy', async () => {
@@ -134,13 +150,56 @@ describe('SchedulerRuntime', () => {
 
     // OR 组合补全：源码 `!isIdle() || hasPendingMessages()` 任一为真即跳过。
     // idle=true 但有 pending message → dispatch 应被跳过。
-    it('skips when idle but has pending messages', async () => {
+    // U4 变更：gate 已交 delivery 内核，无 delivery handle 时走 dispatchDirect（直投不检查 idle）
+    it('无 delivery handle 时直投不受 idle/pending 影响', async () => {
       const pendingCtx = { isIdle: () => true, hasPendingMessages: () => true }
       const pendingBackend = new MockSchedulerBackend()
       const pendingRuntime = new SchedulerRuntime(pendingBackend, pendingCtx)
       const task = await pendingRuntime.addTask('test', { mode: 'interval', intervalMs: 60000 })
       await pendingRuntime.dispatchTask(task)
+      expect(pendingBackend.sentMessages).toHaveLength(1)
+    })
+
+    // U4 区分力补强：有 delivery handle 时非 force 任务走 delivery 入队而非直投
+    it('有 delivery handle 时非 force 任务走 delivery 入队', async () => {
+      const pendingCtx = { isIdle: () => true, hasPendingMessages: () => true }
+      const pendingBackend = new MockSchedulerBackend()
+      pendingBackend.deliveryHandle = {
+        send: vi.fn(),
+        sendChecked: vi.fn(),
+        flush: vi.fn(),
+        depth: vi.fn(() => 0),
+        dispose: vi.fn(),
+      } as any
+      const pendingRuntime = new SchedulerRuntime(pendingBackend, pendingCtx)
+      const task = await pendingRuntime.addTask('test', { mode: 'interval', intervalMs: 60000 })
+      const dispatched = await pendingRuntime.dispatchTask(task)
+
+      expect(dispatched).toBe(true)
+      expect(pendingBackend.deliveryHandle.send).toHaveBeenCalledTimes(1)
       expect(pendingBackend.sentMessages).toHaveLength(0)
+      expect(task.pending).toBe(false)
+    })
+
+    // U4 区分力补强：busy 时 delivery 入队成功，不触发直投
+    it('busy 时 delivery 入队成功，不触发直投', async () => {
+      const busyCtx = { isIdle: () => false, hasPendingMessages: () => true }
+      const busyBackend = new MockSchedulerBackend()
+      busyBackend.deliveryHandle = {
+        send: vi.fn(),
+        sendChecked: vi.fn(),
+        flush: vi.fn(),
+        depth: vi.fn(() => 0),
+        dispose: vi.fn(),
+      } as any
+      const busyRuntime = new SchedulerRuntime(busyBackend, busyCtx)
+      const task = await busyRuntime.addTask('test', { mode: 'interval', intervalMs: 60000 })
+      const dispatched = await busyRuntime.dispatchTask(task)
+
+      expect(dispatched).toBe(true)
+      expect(busyBackend.deliveryHandle.send).toHaveBeenCalledTimes(1)
+      expect(busyBackend.sentMessages).toHaveLength(0)
+      expect(task.pending).toBe(false)
     })
 
     it('sendMessage 失败 → 记 failed 状态但不 rethrow', async () => {
@@ -408,8 +467,8 @@ describe('SchedulerRuntime', () => {
     })
 
     // ── MF-1：toggle enable 重算 nextRunAt 到未来时清除残留 pending ──
-    // 场景：busy tick 标记 pending=true（W4 跨 tick 重试）→ disable → enable 重算到未来。
-    // 修复前 pending 残留 → 下个 tick step3 `pending && enabled` 在重算的未来时间点之前提前 dispatch。
+    // U4 变更：gate 已交 delivery 内核，非 force 任务在 busy 时通过 delivery 入队（无 handle 时直投）。
+    // pending 在 dispatchViaDelivery/dispatchDirect 成功后清除（不再依赖 gate 跳过保留 pending）。
     it('MF-1: enable 重算 nextRunAt 到未来时清除残留 pending，不提前 dispatch', async () => {
       // 可控 idle 状态：先 busy 模拟 dispatchTask 跳过保留 pending（W4），后切 idle 排除 busy 干扰
       let idle = false
@@ -420,29 +479,26 @@ describe('SchedulerRuntime', () => {
       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 保留）
+      // T0+61s：任务到期 + 无 delivery handle → dispatchDirect（直投，不检查 idle）
+      // 直投成功后 pending=false
       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)
+      expect(task.pending).toBe(false) // 直投成功后 pending 已清除
+      expect(controllableBackend.sentMessages).toHaveLength(1) // 直投成功
 
-      // 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
+      // 重算 nextRunAt 到未来（recurring 任务 dispatch 后 nextRunAt 已推进）
       const recalcedNext = task.nextRunAt
-      expect(recalcedNext).toBeGreaterThan(Date.now()) // 确认重算到了未来
+      expect(recalcedNext).toBeGreaterThan(Date.now()) // 已推进到未来
 
-      // T0+90s：在重算的未来 nextRunAt 之前 tick，切 idle 排除 busy 干扰 → 不应 dispatch
+      // T0+90s：在重算的未来 nextRunAt 之前 tick → 不应 dispatch
       vi.setSystemTime(new Date('2026-01-01T00:01:30Z'))
-      idle = true
       await rt.tickScheduler()
-      expect(controllableBackend.sentMessages).toHaveLength(0)
+      expect(controllableBackend.sentMessages).toHaveLength(1) // 仍是 1 次
 
       // 到达重算的未来 nextRunAt 后 tick：才 dispatch
       vi.setSystemTime(new Date(recalcedNext + 1000))
       await rt.tickScheduler()
-      expect(controllableBackend.sentMessages).toHaveLength(1)
+      expect(controllableBackend.sentMessages).toHaveLength(2)
     })
 
     // ── P1：toggle enable 重算的 nextRunAt 跨 session 重放后保持未来值 ──
@@ -535,6 +591,146 @@ describe('SchedulerRuntime', () => {
     })
   })
 
+  // ── U4：delivery 内核集成 ──
+  // scheduler 的非 force 任务走 delivery 内核（park 模式）。
+  // force 任务和无 delivery handle 时走 dispatchDirect（直投）。
+  describe('U4: delivery 内核集成', () => {
+    it('有 delivery handle 时非 force 任务走 delivery 入队（不直调 sendMessage）', async () => {
+      // 模拟 delivery handle（必须在 runtime 构造前设置，构造时从 backend 获取）
+      const sentViaDelivery: Array<{ content: string; intent: string }> = []
+      const mockDelivery = {
+        send: vi.fn((msg: { payload: { content: string }; intent?: string }) => {
+          sentViaDelivery.push({
+            content: msg.payload.content,
+            intent: msg.intent ?? 'after-run',
+          })
+        }),
+        sendChecked: vi.fn(),
+        flush: vi.fn(),
+        depth: vi.fn(() => 0),
+        dispose: vi.fn(),
+      }
+      backend.deliveryHandle = mockDelivery as any
+      // 重新创建 runtime（构造时获取 delivery handle）
+      const deliveryRuntime = new SchedulerRuntime(backend, mockCtx)
+
+      const task = await deliveryRuntime.addTask('delivery-test', { mode: 'interval', intervalMs: 60000 })
+      await deliveryRuntime.dispatchTask(task)
+
+      // 非 force 任务走 delivery 入队
+      expect(mockDelivery.send).toHaveBeenCalledTimes(1)
+      expect(sentViaDelivery[0]!.content).toBe('delivery-test')
+      expect(sentViaDelivery[0]!.intent).toBe('after-run')
+      // 不直调 sendMessage
+      expect(backend.sentMessages).toHaveLength(0)
+      // pending 已清除（入队后移交内核管理）
+      expect(task.pending).toBe(false)
+    })
+
+    it('force 任务绕过 delivery 直投', async () => {
+      const mockDelivery = {
+        send: vi.fn(),
+        sendChecked: vi.fn(),
+        flush: vi.fn(),
+        depth: vi.fn(() => 0),
+        dispose: vi.fn(),
+      }
+      backend.deliveryHandle = mockDelivery as any
+      const deliveryRuntime = new SchedulerRuntime(backend, mockCtx)
+
+      const task = await deliveryRuntime.addTask('force-test', { mode: 'interval', intervalMs: 60000 }, { force: true })
+      await deliveryRuntime.dispatchTask(task)
+
+      // force 任务直投（不走 delivery）
+      expect(mockDelivery.send).not.toHaveBeenCalled()
+      expect(backend.sentMessages).toHaveLength(1)
+      expect(backend.sentMessages[0]!.msg.content).toBe('force-test')
+    })
+
+    it('tick 末尾调 delivery.flush()', async () => {
+      const mockDelivery = {
+        send: vi.fn(),
+        sendChecked: vi.fn(),
+        flush: vi.fn(),
+        depth: vi.fn(() => 0),
+        dispose: vi.fn(),
+      }
+      backend.deliveryHandle = mockDelivery as any
+      const deliveryRuntime = new SchedulerRuntime(backend, mockCtx)
+
+      await deliveryRuntime.tickScheduler()
+
+      // tick 完成后调 flush
+      expect(mockDelivery.flush).toHaveBeenCalledTimes(1)
+    })
+
+    it('handleSettled delivered（dedupeKey=task.id 反查）→ 成功记账', async () => {
+      const task = await runtime.addTask('settle-test', { mode: 'interval', intervalMs: 60000 })
+
+      // 模拟 delivery onSettled 回调（dispatchViaDelivery 挂 dedupeKey=task.id）
+      runtime.handleSettled(settledMsg('settle-test', task.id), 'delivered')
+
+      // onDispatchSuccess 是异步的，等待完成
+      await vi.waitFor(() => {
+        expect(task.runCount).toBe(1)
+        expect(task.lastStatus).toBe('success')
+      })
+      expect(task.lastError).toBeUndefined()
+    })
+
+    it('handleSettled rejected → 失败记账（once 不删持久化）', async () => {
+      const task = await runtime.addTask('settle-fail', { mode: 'interval', intervalMs: 60000 }, { kind: 'once' })
+
+      // 模拟 delivery onSettled 回调
+      runtime.handleSettled(settledMsg('settle-fail', task.id), 'rejected')
+
+      // 失败记账
+      expect(task.lastStatus).toBe('failed')
+      expect(task.history[task.history.length - 1]!.status).toBe('failed')
+      // once 任务失败不删持久化（任务仍在）
+      expect(runtime.getTask(task.id)).toBeDefined()
+    })
+
+    it('#11 同 prompt 两任务：各自 onSettled 按 dedupeKey 精确记账（不互相错配）', async () => {
+      const taskA = await runtime.addTask('same-prompt', { mode: 'interval', intervalMs: 60000 })
+      const taskB = await runtime.addTask('same-prompt', { mode: 'interval', intervalMs: 60000 })
+      expect(taskA.id).not.toBe(taskB.id)
+
+      // A 的投递终态：只记 A 的账（旧 content 反查 find 取首个命中，B 先入 Map 时错记 B）
+      runtime.handleSettled(settledMsg('same-prompt', taskA.id), 'delivered')
+
+      await vi.waitFor(() => {
+        expect(taskA.runCount).toBe(1)
+      })
+      expect(taskA.lastStatus).toBe('success')
+      expect(taskB.runCount).toBe(0)
+      expect(taskB.lastStatus).toBeUndefined()
+
+      // B 的投递终态：记 B 的账
+      runtime.handleSettled(settledMsg('same-prompt', taskB.id), 'delivered')
+
+      await vi.waitFor(() => {
+        expect(taskB.runCount).toBe(1)
+      })
+      expect(taskB.lastStatus).toBe('success')
+    })
+
+    it('#11 任务先删后 delivered → 不炸不误记其他任务', async () => {
+      const taskA = await runtime.addTask('deleted-task', { mode: 'interval', intervalMs: 60000 })
+      const taskB = await runtime.addTask('other-task', { mode: 'interval', intervalMs: 60000 })
+
+      // once 成功 / 手动删除后 delivered 迟到：dedupeKey 反查未命中 → no-op
+      runtime.deleteTask(taskA.id)
+      expect(() => {
+        runtime.handleSettled(settledMsg('deleted-task', taskA.id), 'delivered')
+      }).not.toThrow()
+
+      // 不误记其他任务的账
+      expect(taskB.runCount).toBe(0)
+      expect(taskB.lastStatus).toBeUndefined()
+    })
+  })
+
   // ── F2：tick 错误分诊（crash-fix）──
   // startScheduler 的 interval 回调对 fire-and-forget 的 tickScheduler() 加 catch：
   // stale 类错误（session 替换后泄漏 timer 访问 stale ctx）→ warn "tick stopped" + stopScheduler

package/src/__tests__/service.test.ts

@@ -195,10 +195,9 @@ describe('SchedulerService', () => {
       })
     })
 
-    // TC8：busy 场景（任务 enabled 但 ctx.isIdle() 返回 false）→ dispatch no-op →
-    // DISPATCH_SKIPPED。m2 只覆盖了 disabled 场景，busy 是 dispatchTask 的
-    // `!task.force && (!ctx.isIdle() || ctx.hasPendingMessages())` 独立分支。
-    it('returns DISPATCH_SKIPPED when ctx is busy (isIdle=false)', async () => {
+    // U4 变更：gate 已交 delivery 内核，无 delivery handle 时走 dispatchDirect（直投不检查 idle）。
+    // busy 不再导致 DISPATCH_SKIPPED（直投成功）。
+    it('无 delivery handle 时 busy 不影响 dispatch（直投）', async () => {
       const busyCtx = { isIdle: () => false, hasPendingMessages: () => false }
       const busyBackend = new MockSchedulerBackend()
       const busyService = new SchedulerService(new SchedulerRuntime(busyBackend, busyCtx), () => busyBackend.now())
@@ -207,11 +206,9 @@ describe('SchedulerService', () => {
       const id = created.data!.task.id
       const result = await busyService.run(id)
 
-      expect(result.success).toBe(false)
-      expect(result.errorCode).toBe('DISPATCH_SKIPPED')
-      expect(result.message).toContain('busy')
-      // 未发送任何 message（dispatch no-op）
-      expect(busyBackend.sentMessages).toHaveLength(0)
+      // 直投成功（无 delivery handle → dispatchDirect，不检查 idle）
+      expect(result.success).toBe(true)
+      expect(busyBackend.sentMessages).toHaveLength(1)
     })
   })
 })

package/src/backend.ts

@@ -1,4 +1,5 @@
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
+import type { DeliveryHandle } from '@xyz-agent/session-delivery'
 
 import { replayFoldEntries, type SchedulerEntryLike } from './replay.js'
 import type { ScheduledTask, SchedulerEntryOp } from './types.js'
@@ -33,6 +34,8 @@ export interface SchedulerBackend {
   appendEntry(op: SchedulerEntryOp): void
   getSessionFile(): string | undefined
   now(): number
+  /** 获取 delivery handle（装配点注入；未注入时 force 路径仍用 sendMessage 直投）。 */
+  getDeliveryHandle?(): DeliveryHandle | undefined
 }
 
 /**
@@ -59,6 +62,7 @@ export interface SchedulerBackendCtx {
 export class PiSchedulerBackend implements SchedulerBackend {
   private ctx: SchedulerBackendCtx
   private pi: Pick<ExtensionAPI, 'sendMessage' | 'appendEntry'>
+  private deliveryHandle: DeliveryHandle | undefined
 
   constructor(ctx: SchedulerBackendCtx, pi: Pick<ExtensionAPI, 'sendMessage' | 'appendEntry'>) {
     this.ctx = ctx
@@ -93,6 +97,18 @@ export class PiSchedulerBackend implements SchedulerBackend {
   now(): number {
     return Date.now()
   }
+
+  /**
+   * 注入 delivery handle（装配点创建后调用）。
+   * runtime 通过 getDeliveryHandle() 获取，非 force 任务走内核队列。
+   */
+  setDeliveryHandle(handle: DeliveryHandle): void {
+    this.deliveryHandle = handle
+  }
+
+  getDeliveryHandle(): DeliveryHandle | undefined {
+    return this.deliveryHandle
+  }
 }
 
 // ── 测试实现 ──
@@ -120,6 +136,7 @@ export class MockSchedulerBackend implements SchedulerBackend {
   fakeSessionFile: string | undefined = '/test/session.json'
   nowValue: number | undefined
   appendError: Error | null = null
+  deliveryHandle: DeliveryHandle | undefined
 
   async sendMessage(
     msg: { content: string; customType: string; display: boolean },
@@ -141,6 +158,10 @@ export class MockSchedulerBackend implements SchedulerBackend {
     return this.nowValue ?? Date.now()
   }
 
+  getDeliveryHandle(): DeliveryHandle | undefined {
+    return this.deliveryHandle
+  }
+
   /**
    * 读路径（非接口成员，与 PiSchedulerBackend.loadTasks 对称）：经 replayFoldEntries 折叠
    * fakeEntries + fakeSessionFile 恢复任务。测试用它验证 backend→replay 委托（TC-W-BACKEND-REPLAY）。

package/src/index.ts

@@ -1,4 +1,5 @@
 import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent'
+import { createDelivery, type DeliveryHandle, type DeliveryMessage } from '@xyz-agent/session-delivery'
 
 import { PiSchedulerBackend } from './backend.js'
 import { registerScheduleCommand } from './commands.js'
@@ -43,6 +44,7 @@ let sessionGeneration = 0
  */
 export default function schedulerExtension(pi: ExtensionAPI): void {
   let service: SchedulerService | null = null
+  let deliveryHandle: DeliveryHandle | undefined
   // IMPORT-FLUSH-GUARD（MF-1）：importLegacyStore 对未 flush 的新 session 返回延迟删除 .imported
   // 的 cleanup——turn_end / session_shutdown 时执行：确认 flush（sessionFile 已出现）则删，
   // 未 flush 保留供崩溃恢复重导入（否则未 flush 即退出 → 全部旧任务丢失且源文件已销毁）。
@@ -66,15 +68,58 @@ export default function schedulerExtension(pi: ExtensionAPI): void {
     // 窗口与 session 替换交错时旧 session_shutdown 可能永远等不到（timer 泄漏源头）。stopScheduler 幂等，
     // shutdown 已停过再停一次无副作用。
     service?.runtime.stopScheduler()
+    // 销毁旧 delivery handle（清队列 + 清 timer + 退订 settled）
+    deliveryHandle?.dispose()
     // 装配点：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())
+    // 创建 delivery handle（U4：scheduler 切换内核）
+    // busyPolicy: 'park'（busy 入队不重试，等 tick 外部 flush）
+    // intent: 'after-run'（保持 followUp 语义）
+    // onSettled：延迟绑定——runtime 创建后填充（闭包变量）
+    // #11：整条 msg 透传（runtime 按 msg.dedupeKey=task.id 精确反查，不再 content 匹配）
+    const settledHandlerRef: { current: ((msg: DeliveryMessage, outcome: 'delivered' | 'rejected') => void) | undefined } = { current: undefined }
+    deliveryHandle = createDelivery({
+      supportedPayloads: ['custom'],
+      isIdle: () => ctx.isIdle(),
+      hasPendingMessages: () => ctx.hasPendingMessages(),
+      subscribeSettled: (cb) => {
+        // 无退订语义（pi 0.84.1 `pi.on(...)` 全重载返回 void、无 off——实装锚点：
+        // node_modules @earendil-works/pi-coding-agent dist/core/extensions/types.d.ts
+        // `on()` 系列，0.84.1 实测）；disposed 标志包装兑现退订（notifier.ts 同款）
+        let disposed = false
+        pi.on('agent_settled', () => { if (!disposed) cb() })
+        return () => { disposed = true }
+      },
+      send: (msg, intent) => {
+        const piOpts = intent === 'interrupt-at-turn-boundary'
+          ? { triggerTurn: true, deliverAs: 'steer' as const }
+          : { triggerTurn: true, deliverAs: 'followUp' as const }
+        // supportedPayloads 已收窄到 'custom'，payload.kind 恒为 'custom'
+        const content = msg.payload.content
+        return pi.sendMessage(
+          { content, customType: 'pi-scheduler:dispatched', display: true },
+          piOpts,
+        )
+      },
+    }, {
+      intent: 'after-run',
+      busyPolicy: 'park',
+      onSettled: (msg, outcome) => {
+        // 委托给 runtime 的 settledHandler（延迟绑定）
+        settledHandlerRef.current?.(msg, outcome)
+      },
+    })
+    backend.setDeliveryHandle(deliveryHandle)
+
     // G1：注入代际比对（本 runtime 建立时的代数 vs 实时代数），供 tick 前置检查与
     // F2 catch 分诊判定 stale——不依赖 pi 错误文案。
     const runtime = new SchedulerRuntime(backend, ctx, () => sessionGeneration !== myGeneration)
+    // 延迟绑定：runtime 的 handleSettled 绑定到 delivery onSettled 回调
+    settledHandlerRef.current = (msg, outcome) => runtime.handleSettled(msg, outcome)
     runtime.loadTasks(backend.loadTasks())
     // W2：tick 后回调刷新 widget（替代独立 widgetTimer + setInterval，节奏对齐 TICK_INTERVAL_MS）
     runtime.onAfterTick(() => refreshWidget(ctx))
@@ -100,6 +145,9 @@ export default function schedulerExtension(pi: ExtensionAPI): void {
     if (service) {
       service.runtime.stopScheduler()
     }
+    // 销毁 delivery handle（清队列 + 清 timer + 退订 settled）
+    deliveryHandle?.dispose()
+    deliveryHandle = undefined
     // IMPORT-FLUSH-GUARD（MF-1）：兜底清理——正常路径已由首个 turn_end 完成；此处覆盖
     // 从未产生 turn 的 session（打开未发消息即关闭）。cleanup 确认 flush（sessionFile 已出现）
     // 则删 .imported，未 flush 保留供崩溃恢复重导入

package/src/runtime.ts

@@ -1,5 +1,7 @@
 import type { ExtensionContext } from '@earendil-works/pi-coding-agent'
 
+import type { DeliveryHandle, DeliveryMessage } from '@xyz-agent/session-delivery'
+
 import type { SchedulerBackend } from './backend.js'
 import { autoName, generateTaskId } from './format.js'
 import { computeNextRunAt, parseDuration } from './parsing.js'
@@ -12,6 +14,8 @@ import type {
 } from './types.js'
 
 const MAX_TASKS = 50
+// 入队防重标记 TTL（合批非首条任务无终态回调，过期后放行重投；10 min >> 合批窗口）
+const QUEUE_DEDUPE_TTL_MS = 10 * 60 * 1000
 const RATE_LIMIT_PER_MINUTE = 6
 const TICK_INTERVAL_MS = 30_000
 const DEFAULT_EXPIRY_MS = 7 * 24 * 60 * 60 * 1000 // 7 days
@@ -30,13 +34,21 @@ const STALE_CTX_MARKER = 'stale after session replacement'
 export class SchedulerRuntime {
   private tasks: Map<string, ScheduledTask> = new Map()
   private backend: SchedulerBackend
-  private ctx: Pick<ExtensionContext, 'isIdle' | 'hasPendingMessages'>
   private tickTimer: ReturnType<typeof setInterval> | null = null
   private dispatchTimestamps: number[] = []
   private onAfterTickCallback: (() => void) | null = null
   private readonly isCtxStale: (() => boolean) | undefined
   // R3-S1：同任务 dispatch 在途标记（Set<taskId>），见 dispatchTask 注释
   private readonly dispatchesInFlight = new Set<string>()
+  // 入队防重标记（Map<taskId, enqueuedAt>）：非 force 任务 send 进 delivery 内核后、
+  // 终态回调（handleSettled）前，nextRunAt 未推进——tick step2 会按 `now >= nextRunAt`
+  // 重新置 pending，若无此标记，agent busy 的每个 tick 都会再压一份同 prompt 副本进队列
+  // （合批后重复注入）。入队置位、delivered/rejected 清除；任务删除（delete/过期）同步清除。
+  // TTL 兜底：合批投递时 onSettled 只带首条 dedupeKey，非首条任务收不到终态回调——
+  // 标记过期后允许重投，保持 at-least-once（与旧「nextRunAt 未推进下 tick 重投」等价）。
+  private readonly queuedInDeliveryAt = new Map<string, number>()
+  // delivery handle（装配点注入；非 force 任务走内核队列）
+  private delivery: DeliveryHandle | undefined
 
   /**
    * 依赖反转构造：backend 承担 appendEntry/pi.sendMessage/时间源，runtime 只持有内存态。
@@ -48,12 +60,15 @@ export class SchedulerRuntime {
    */
   constructor(
     backend: SchedulerBackend,
-    ctx: Pick<ExtensionContext, 'isIdle' | 'hasPendingMessages'>,
+    ctx?: Pick<ExtensionContext, 'isIdle' | 'hasPendingMessages'>,
     isCtxStale?: () => boolean,
   ) {
     this.backend = backend
-    this.ctx = ctx
+    // ctx 不再存实例变量（gate 已交内核）；isCtxStale 保留用于代际检测
+    void ctx
     this.isCtxStale = isCtxStale
+    // 从 backend 获取 delivery handle（装配点注入）
+    this.delivery = backend.getDeliveryHandle?.()
   }
 
   // ── 任务 CRUD ──
@@ -161,6 +176,7 @@ export class SchedulerRuntime {
 
   deleteTask(id: string): boolean {
     const deleted = this.tasks.delete(id)
+    if (deleted) this.queuedInDeliveryAt.delete(id)
     if (deleted) {
       this.appendEntrySafe({ op: 'delete', taskId: id })
     }
@@ -239,6 +255,7 @@ export class SchedulerRuntime {
     for (const [id, task] of this.tasks) {
       if (task.expiresAt && now >= task.expiresAt) {
         this.tasks.delete(id)
+        this.queuedInDeliveryAt.delete(id)
         this.appendEntrySafe({ op: 'delete', taskId: id })
       }
     }
@@ -264,6 +281,10 @@ export class SchedulerRuntime {
 
     // W2：tick 完成后刷新 widget（index.ts 注册 refreshWidget）
     this.onAfterTickCallback?.()
+
+    // delivery flush：park 模式下内核不主动重试，由 scheduler tick 外部触发 flush
+    // 让积压在队列中的消息在每个 tick 尝试投递
+    this.delivery?.flush()
   }
 
   // ── dispatch ──
@@ -302,17 +323,28 @@ export class SchedulerRuntime {
    * once 成功 → append delete。失败 dispatch 不 append（CL7 重试语义，transient 失败 nextRunAt 未推进）。
    */
   private async dispatchTaskInner(task: ScheduledTask): Promise<boolean> {
-    // 检查 force 或 idle
-    if (!task.force) {
-      if (!this.ctx.isIdle() || this.ctx.hasPendingMessages()) {
-        return false // 延迟到下次 tick
-      }
-    }
-
     // 检查速率限制
     if (!this.hasDispatchCapacity(this.backend.now())) return false
 
-    // 注入 message（await：async 错误必须被捕获，fire-and-forget 会漏）
+    if (task.force || !this.delivery) {
+      // force 任务或无 delivery handle 时直投（绕过内核队列）
+      return this.dispatchDirect(task)
+    }
+
+    // 已在内核队列中（入队后未终态且未过 TTL）——step2 会按未推进的 nextRunAt 重新置
+    // pending，此处拦截防重复入队（见 queuedInDeliveryAt 字段注释）
+    const queuedAt = this.queuedInDeliveryAt.get(task.id)
+    if (queuedAt !== undefined && this.backend.now() - queuedAt < QUEUE_DEDUPE_TTL_MS) return false
+
+    // 非 force 任务走 delivery 内核（park 模式：busy 入队等下次 tick flush）
+    return this.dispatchViaDelivery(task)
+  }
+
+  /**
+   * force 任务直投：绕过 delivery 内核队列，直接调 backend.sendMessage。
+   * 无 delivery handle 时也走此路径（向后兼容）。
+   */
+  private async dispatchDirect(task: ScheduledTask): Promise<boolean> {
     try {
       await this.backend.sendMessage(
         { content: task.prompt, customType: 'pi-scheduler:dispatched', display: true },
@@ -325,49 +357,111 @@ export class SchedulerRuntime {
       if (task.history.length > HISTORY_LIMIT) task.history.shift()
       return false
     }
+    return this.onDispatchSuccess(task)
+  }
+
+  /**
+   * 非 force 任务走 delivery 内核：入队后由内核 flush 时投递。
+   * gate（isIdle/hasPendingMessages）由内核管理，busy 时入队不重试（park 模式）。
+   * onSettled 回调处理成功/失败记账。
+   * 返回 true 表示已入队（非实际发送）。
+   */
+  private dispatchViaDelivery(task: ScheduledTask): boolean {
+    const delivery = this.delivery!
+
+    delivery.send({
+      payload: {
+        kind: 'custom',
+        customType: 'pi-scheduler:dispatched',
+        content: task.prompt,
+        display: true,
+      },
+      intent: 'after-run',
+      // #11：task.id 作为 onSettled 反查键（本 handle 未开 dedupe，dedupeKey 不驱动
+      // 去重，仅随消息透传给 onSettled 回调）。content 反查在同 prompt 多任务下错配。
+      dedupeKey: task.id,
+    })
 
-    // 更新状态（收敛到一个 now 值，避免多次 backend.now() 在真实时钟下漂移）
+    // send() 不 throw（park 模式下入队即返回）。
+    // 入队即挂防重标记 + 计入速率限制（nextRunAt 要等 delivered 后才推进，期间 step2
+    // 会持续重标 pending——防重标记拦截重复入队，速率记账覆盖入队侧消耗）。
+    // 成功/失败记账由 onSettled 回调异步处理。
+    this.queuedInDeliveryAt.set(task.id, this.backend.now())
+    this.dispatchTimestamps.push(this.backend.now())
+    task.pending = false
+    return true
+  }
+
+  /**
+   * dispatch 成功后的状态更新与持久化（dispatchDirect 成功后、onSettled delivered 后共用）。
+   * countRate=false 时不再计速率（delivery 路径入队时已计入，delivered 再计会双算）。
+   */
+  private async onDispatchSuccess(task: ScheduledTask, countRate = true): Promise<boolean> {
     const now = this.backend.now()
     task.runCount++
     task.lastRunAt = now
     task.lastStatus = 'success'
     task.pending = false
-    task.lastError = undefined // 成功 dispatch 后清除历史错误
+    task.lastError = undefined
     task.history.push({ at: now, status: 'success' })
     if (task.history.length > HISTORY_LIMIT) task.history.shift()
 
-    // 计算下次执行 + 持久化（append-only）
     if (task.kind === 'once') {
       this.tasks.delete(task.id)
-      // once 成功 → append delete（CL7：抵消 upsert，防 resume 复活已执行的 once 任务）
       this.appendEntrySafe({ op: 'delete', taskId: task.id })
     } else {
       const next = await computeNextRunAt(task.schedule, now)
       if (next === undefined) {
-        // ERR-2 fallback：cron 表达式失效 → 停用任务，避免 `?? now()` 死循环。
-        // 不 append advance（nextRunAt 未推进，CL7 重试语义）；cron 失效停用的 enabled=false
-        // 持久化缺口属 at-least-once 已知窗口（首个 tick 会再停用），非 must-fix
         task.enabled = false
         task.lastStatus = 'failed'
         task.lastError = 'cron expression invalid'
-        // nextRunAt 保留原值（enabled=false 后 tick 不再触发）
       } else {
         task.nextRunAt = next
-        // recurring 成功推进 nextRunAt → append advance（D1 核心：持久化新 nextRunAt，防 resume 回退重放）
         this.appendEntrySafe({
           op: 'advance',
           taskId: task.id,
           nextRunAt: next,
           at: now,
-          status: 'success', // CL8：对齐 TaskStatus，非 'ok'
+          status: 'success',
         })
       }
     }
 
-    this.dispatchTimestamps.push(now)
+    if (countRate) this.dispatchTimestamps.push(now)
     return true
   }
 
+  /**
+   * onSettled 回调入口（index.ts 装配点绑定）：delivery 内核投递终态时调用。
+   * delivered → 成功记账（onDispatchSuccess）；rejected → 失败记账。
+   * once 任务失败不删持久化（at-least-once 语义）。
+   * #11：按 msg.dedupeKey（dispatch 时挂的 task.id，见 dispatchViaDelivery）精确反查
+   * tasks Map——旧 content 反查在「同 prompt 多任务」下错配（find 取首个命中），
+   * 任务已删除时静默丢弃不误记。反查未命中（once 成功已删 / 批量合投非首条 /
+   * 非 scheduler 消息）直接返回。
+   * 已知限制：内核 busy 期间多条消息合投为一批时（doSend splice 全队列），onSettled
+   * 只收到保留首条 dedupeKey 的 composed 消息——非首条任务不记账，靠下个 tick 的
+   * nextRunAt 未推进重投（at-least-once 兜底），与旧 content 反查行为等价不劣化。
+   */
+  handleSettled(msg: DeliveryMessage, outcome: 'delivered' | 'rejected'): void {
+    const taskId = msg.dedupeKey
+    // 防重标记先清（任务可能已被删除，反查未命中也要清）
+    if (taskId !== undefined) this.queuedInDeliveryAt.delete(taskId)
+    const task = taskId !== undefined ? this.tasks.get(taskId) : undefined
+    if (!task) return // 任务已被删除（once 成功后删）或非 scheduler 发出的消息
+
+    if (outcome === 'delivered') {
+      // fire-and-forget：onDispatchSuccess 内部 catch 不 rethrow（countRate=false：入队时已计速率）
+      void this.onDispatchSuccess(task, false).catch(() => {})
+    } else {
+      // 失败记账
+      task.lastStatus = 'failed'
+      task.history.push({ at: this.backend.now(), status: 'failed' })
+      if (task.history.length > HISTORY_LIMIT) task.history.shift()
+      // once 任务失败不删持久化（at-least-once 语义）
+    }
+  }
+
   private hasDispatchCapacity(now: number): boolean {
     const oneMinuteAgo = now - 60_000
     this.dispatchTimestamps = this.dispatchTimestamps.filter(t => t > oneMinuteAgo)