@zhushanwen/pi-scheduler 0.9.1 → 0.9.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-scheduler",
-  "version": "0.9.1",
+  "version": "0.9.2",
   "type": "module",
   "main": "index.ts",
   "taiji": {
@@ -51,10 +51,10 @@
   },
   "dependencies": {
     "croner": "^9.0.0",
-    "@zhushanwen/extension-protocol": "0.14.0",
-    "@zhushanwen/pi-ext-guards": "0.4.1",
+    "@zhushanwen/extension-protocol": "0.16.0",
+    "@zhushanwen/pi-ext-guards": "0.4.2",
     "@zhushanwen/pi-extension-logger": "0.6.1",
-    "@zhushanwen/pi-llm-shared": "0.10.0"
+    "@zhushanwen/pi-llm-shared": "0.10.1"
   },
   "scripts": {
     "test": "vitest run",

package/src/__tests__/index-generation.test.ts

@@ -15,7 +15,7 @@
 //
 // 本文件用 InstrumentedRuntime（继承真实 SchedulerRuntime，记录构造参 isCtxStale）
 // 捕获注入回调与装配事实。InstrumentedRuntime 全部行为继承父类，不影响装配链本身
-// （F1 停旧 timer 等行为由 index-session-start.test.ts U4 锚定，此处不重复）。
+// （F1 停旧 timer 等行为由本文件 F1 describe 锚定，此处不重复）。
 // steer 直投模型（scheduler-steer-direct-dispatch）：装配点不再创建 delivery handle，
 // runtime 构造收 backend + isCtxStale? + modelOps? 三参（U4：modelOps 缺省 = 无模型
 // 切换能力降级）。
@@ -33,7 +33,9 @@ vi.mock('@zhushanwen/pi-extension-logger', () => ({
   setPiHandle: vi.fn(),
 }))
 
-// 与 index-session-start.test.ts 同款（MF-3）：mock 掉 importer，装配路径仍被调用、FS 副作用为零。
+// MF-3：session_start 会真实执行 importLegacyStore(ctx.cwd, ...)，触碰用户真实 FS
+// （~/.pi/agent/scheduler/... 的 renameSync/existsSync 探测）。mock 掉 importer
+// 模块，装配路径仍被调用、FS 副作用为零。
 vi.mock('../importer.js', () => ({ importLegacyStore: vi.fn(() => vi.fn()) }))
 
 // u-p2b 接线断言：index.ts 的 refreshWidget 必须走结构化/双模入口 `setSchedulerWidget`
@@ -69,11 +71,14 @@ vi.mock('../runtime.js', async (importOriginal) => {
 })
 
 import schedulerExtension from '../index.js'
+import { TASK_ENTRY_TYPE } from '../types.js'
 
 const TICK_INTERVAL_MS = 30_000
+/** 与 index.ts 的 WIDGET_KEEPALIVE_INTERVAL_MS 同值（常量不导出，测试锚定同值）。 */
+const KEEPALIVE_INTERVAL_MS = 10 * 60 * 1000
 
 /**
- * 最小 fake pi：与 index-session-start.test.ts 同款，覆盖 factory 消费的 API 面
+ * 最小 fake pi：覆盖 factory 消费的 API 面
  * （on 捕获事件 handler 供手动触发；registerTool/registerCommand/sendMessage/appendEntry 兜底）。
  */
 function createMockPi(): {
@@ -195,3 +200,101 @@ describe('G1: index.ts 代际接线（S9）', () => {
     }
   })
 })
+
+// ── F1: session_start 停旧 runtime（crash-fix U4）──
+// session_start 多发/重入时先停上一代 runtime 的 tick interval：dispatch 的 await sendMessage
+// 窗口与 session 替换交错时，旧 session_shutdown 可能永远等不到 → 旧 30s tick timer 泄漏 →
+// 下一 tick 的 refreshWidget 访问 stale ctx.ui 抛错 → unhandledRejection → pi 主进程 exit 1。
+// F1 在 session_start 开头幂等 stopScheduler，从源头消灭。
+//
+// 行为断言口径（验收 U4）：观测面 = refreshWidget 的推送调用序列（本文件 mock 环境下
+// refreshWidget 走 setSchedulerWidgetMock，与真实 ctx.ui.setWidget 同一调用序列）。widget
+// 推送修正（D1 指纹跳推 + D2 保活底线帧）后每次 tick 不再必然推帧——任务集静态期间零推送、
+// 空任务集恒零推送，故注入非空任务集、以「跨 10min 保活窗口必推一帧」作为「该 runtime 的
+// timer 是否还在 tick」的行为观测面（保活帧间隔与 index.ts WIDGET_KEEPALIVE_INTERVAL_MS
+// 同值 10min）。F1 缺失时旧 timer 跨窗口必多推一帧，即被捕获。
+describe('F1: session_start 停旧 runtime（crash-fix U4）', () => {
+  const BASE = Date.parse('2026-01-01T00:00:00Z')
+
+  /**
+   * 构造远期到期的启用任务 upsert entry（owner = sessionFile，避免 fork owner 过滤）；
+   * nextRunAt 取 BASE + 1h，测试时间窗（分钟级）内无 dispatch 噪音，任务集保持静态。
+   */
+  function taskEntry(sessionFile: string) {
+    return {
+      type: 'custom',
+      customType: TASK_ENTRY_TYPE,
+      data: {
+        op: 'upsert',
+        taskId: 'aaaa1111',
+        ownerSessionFile: sessionFile,
+        task: {
+          id: 'aaaa1111',
+          name: 'keepalive probe',
+          prompt: 'probe prompt',
+          kind: 'recurring',
+          schedule: { mode: 'interval', intervalMs: 3_600_000 },
+          enabled: true,
+          createdAt: BASE,
+          nextRunAt: BASE + 3_600_000,
+          runCount: 0,
+          history: [],
+        },
+      },
+    }
+  }
+
+  /** 同 createFakeCtx，但注入非空任务集（保活帧只在非空任务集时推送，见上方口径注释）。 */
+  function createFakeCtxWithTasks(sessionFile: string): ExtensionContext {
+    return {
+      cwd: '/test-index-session-start',
+      isIdle: () => true,
+      hasPendingMessages: () => false,
+      ui: { setWidget: vi.fn() },
+      sessionManager: {
+        getEntries: () => [taskEntry(sessionFile)],
+        getSessionFile: () => sessionFile,
+      },
+    } as unknown as ExtensionContext
+  }
+
+  beforeEach(() => {
+    isCtxStaleCaptures.length = 0
+    runtimeInstances.length = 0
+    setSchedulerWidgetMock.mockClear()
+    vi.useFakeTimers()
+    vi.setSystemTime(new Date(BASE))
+  })
+
+  afterEach(() => {
+    for (const rt of runtimeInstances) {
+      rt.stopScheduler()
+    }
+    vi.useRealTimers()
+  })
+
+  it('U4: 双 session_start 后旧 timer 已停——跨保活窗口只有新 runtime 推帧', async () => {
+    const { pi, events } = createMockPi()
+    schedulerExtension(pi)
+    const sessionStart = events.get('session_start')
+    expect(sessionStart).toBeDefined()
+
+    // 第一次 session_start：runtime1 + timer1 启动，初始渲染 1 次
+    sessionStart!({ type: 'session_start', reason: 'startup' }, createFakeCtxWithTasks('/test/session-1.json'))
+    expect(setSchedulerWidgetMock).toHaveBeenCalledTimes(1)
+
+    // 前置因果锚点：静置越过保活窗口，timer1 推一帧保活帧（排除「timer 从未启动」的假绿；
+    // 也锁定跳推行为——窗口内其余 tick 零推送）
+    await vi.advanceTimersByTimeAsync(KEEPALIVE_INTERVAL_MS + TICK_INTERVAL_MS)
+    expect(setSchedulerWidgetMock).toHaveBeenCalledTimes(2)
+
+    // 第二次 session_start（session 替换）：F1 在装配新 runtime 前停掉 timer1
+    sessionStart!({ type: 'session_start', reason: 'new_session' }, createFakeCtxWithTasks('/test/session-2.json'))
+    expect(setSchedulerWidgetMock).toHaveBeenCalledTimes(3) // runtime2 初始渲染（实例态重置，首帧必推）
+
+    // 行为断言（验收口径）：再静置一个保活窗口，只有 runtime2 的 timer 触发推送——恰 +1；
+    // F1 缺失时 timer1/timer2 都活着，此处为 +2
+    await vi.advanceTimersByTimeAsync(KEEPALIVE_INTERVAL_MS + TICK_INTERVAL_MS)
+    expect(setSchedulerWidgetMock).toHaveBeenCalledTimes(4)
+  })
+})

package/src/__tests__/runtime.test.ts

@@ -149,6 +149,8 @@ describe('SchedulerRuntime', () => {
   // 卡死）时，tick2 的 step2 再标 pending → step3 对同一 task 并发第二个 dispatch → 同一
   // prompt 双注入。守卫：同任务在途（Set<taskId>）
   // 时 skip 本轮并 warn；不同任务不受影响。
+  // 末两条为调用方 API 层验收：不经 tick，直接并发/串行调 dispatchTask，
+  // 验证守卫在调用方入口同样拦截（warn + 第二次 false）与完成后放行。
   describe('dispatchTask in-flight 守卫（R3-S1）', () => {
     beforeEach(() => {
       vi.useFakeTimers()
@@ -212,6 +214,54 @@ describe('SchedulerRuntime', () => {
       expect(task1.runCount).toBe(1)
       expect(task2.runCount).toBe(1)
     })
+
+    // ── 调用方 API 层 ──
+    it('调用方守卫：同一 taskId 并发 dispatchTask → 第二次被拦截（send 只调 1 次 + warn）', async () => {
+      loggerMock.warn.mockClear()
+      // 可控延迟的 sendMessage：让第一次 dispatch 挂起
+      let resolveSend: (() => void) | undefined
+      const sendPromise = new Promise<void>(resolve => { resolveSend = resolve })
+      backend.sendMessage = vi.fn(() => sendPromise)
+
+      const task = await runtime.addTask('inflight-test', { mode: 'interval', intervalMs: 60_000 })
+
+      // 第一次 dispatch（挂起），sendMessage 被调 1 次
+      const first = runtime.dispatchTask(task)
+      expect(backend.sendMessage).toHaveBeenCalledTimes(1)
+
+      // 第二次 dispatch（同一 taskId，在途被拦截）
+      const second = await runtime.dispatchTask(task)
+      expect(second).toBe(false)
+
+      // warn 包含 in-flight 提示
+      const warnText = loggerMock.warn.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
+    })
+
+    it('调用方守卫：第一次完成后 → 第二次 dispatchTask 正常执行（send 调 2 次）', async () => {
+      const task = await runtime.addTask('serial-inflight', { mode: 'interval', intervalMs: 60_000 })
+
+      // 第一次 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)
+    })
   })
 
   // ── M10b：rate-limit ──

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

@@ -1,75 +0,0 @@
-/**
- * U4_DISPATCH_INFLIGHT：调用方 in-flight 守卫验收
- *
- * 两个子用例：
- * (1) 同一 taskId 的 dispatchTask 并发调用 → 第二次立即返回 false + logger.warn
- * (2) 第一次 dispatchTask 完成后（finally 清除）→ 第二次正常执行
- *
- * 断言 backend.sendMessage 调用总次数为 1（拦截场景）或 2（串行场景）。
- */
-import { describe, expect, it, vi } from 'vitest'
-
-import { getLogger } from '@zhushanwen/pi-extension-logger'
-
-import { MockSchedulerBackend } from './mock-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(getLogger('scheduler'), '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)
-
-    const task = await runtime.addTask('inflight-test', { mode: 'interval', intervalMs: 60_000 })
-
-    // 第一次 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)
-
-    const task = await runtime.addTask('serial-inflight', { mode: 'interval', intervalMs: 60_000 })
-
-    // 第一次 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)
-  })
-})

package/src/__tests__/index-session-start.test.ts

@@ -1,139 +0,0 @@
-// src/__tests__/index-session-start.test.ts
-//
-// F1 集成单测（crash-fix U4）：session_start 多发/重入时先停上一代 runtime 的 tick interval。
-// 排查结论：dispatch 的 await sendMessage 窗口与 session 替换交错时，旧 session_shutdown 可能
-// 永远等不到 → 旧 30s tick timer 泄漏 → 下一 tick 的 refreshWidget 访问 stale ctx.ui 抛错 →
-// unhandledRejection → pi 主进程 exit 1。F1 在 session_start 开头幂等 stopScheduler，从源头消灭。
-//
-// 行为断言口径（验收 U4）：观测面 = onAfterTick → refreshWidget → ctx.ui.setWidget 的调用
-// 序列。widget 推送修正（D1 指纹跳推 + D2 保活底线帧）后每次 tick 不再必然推帧——任务集
-// 静态期间零推送、空任务集恒零推送，故本套件注入非空任务集、以「跨 10min 保活窗口必推
-// 一帧」作为「该 runtime 的 timer 是否还在 tick」的行为观测面（保活帧间隔与 index.ts
-// WIDGET_KEEPALIVE_INTERVAL_MS 同值 10min）。F1 缺失时旧 timer 跨窗口必多推一帧，即被捕获。
-
-import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent'
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
-
-// 与 sdk-contract.test.ts 同款（MF-3）：session_start 会真实执行 importLegacyStore(ctx.cwd, ...)，
-// 触碰用户真实 FS（~/.pi/agent/scheduler/... 的 renameSync/existsSync 探测）。mock 掉 importer
-// 模块，装配路径仍被调用、FS 副作用为零。
-vi.mock('../importer.js', () => ({ importLegacyStore: vi.fn(() => vi.fn()) }))
-
-import schedulerExtension from '../index.js'
-import { TASK_ENTRY_TYPE } from '../types.js'
-
-const TICK_INTERVAL_MS = 30_000
-/** 与 index.ts 的 WIDGET_KEEPALIVE_INTERVAL_MS 同值（常量不导出，测试锚定同值）。 */
-const KEEPALIVE_INTERVAL_MS = 10 * 60 * 1000
-const BASE = Date.parse('2026-01-01T00:00:00Z')
-
-/**
- * 最小 fake pi：覆盖 index.ts factory + commands.ts 注册路径消费的 API 面
- * （on / registerTool / registerCommand / sendMessage / appendEntry）。
- * on 捕获事件 handler 供手动触发；sendMessage/appendEntry 为 vi.fn 兜底（本套件无任务 dispatch）。
- */
-function createMockPi(): {
-  pi: ExtensionAPI
-  events: Map<string, (...args: unknown[]) => void>
-} {
-  const events = new Map<string, (...args: unknown[]) => void>()
-  const pi = {
-    registerTool: vi.fn(),
-    registerCommand: vi.fn(),
-    on: (event: string, handler: (...args: unknown[]) => void) => events.set(event, handler),
-    sendMessage: vi.fn(),
-    appendEntry: vi.fn(),
-  } as unknown as ExtensionAPI
-  return { pi, events }
-}
-
-/**
- * 构造远期到期的启用任务 upsert entry（owner = sessionFile，避免 fork owner 过滤）；
- * nextRunAt 取 BASE + 1h，测试时间窗（分钟级）内无 dispatch 噪音，任务集保持静态。
- */
-function taskEntry(sessionFile: string) {
-  return {
-    type: 'custom',
-    customType: TASK_ENTRY_TYPE,
-    data: {
-      op: 'upsert',
-      taskId: 'aaaa1111',
-      ownerSessionFile: sessionFile,
-      task: {
-        id: 'aaaa1111',
-        name: 'keepalive probe',
-        prompt: 'probe prompt',
-        kind: 'recurring',
-        schedule: { mode: 'interval', intervalMs: 3_600_000 },
-        enabled: true,
-        createdAt: BASE,
-        nextRunAt: BASE + 3_600_000,
-        runCount: 0,
-        history: [],
-      },
-    },
-  }
-}
-
-/**
- * 最小 fake ctx：覆盖 session_start 装配链读到的全部字段——PiSchedulerBackend 构造
- * （sessionManager：getEntries 注入非空任务集）、runtime 装配、refreshWidget（ui.setWidget）。
- * setWidget 以独立引用导出：session_start 初始渲染 + 保活帧是「哪个 runtime 的 timer 还在
- * tick」的行为观测面（每个实际推送恰一次调用）。
- */
-function createFakeCtx(sessionFile: string): {
-  ctx: ExtensionContext
-  setWidget: ReturnType<typeof vi.fn>
-} {
-  const setWidget = vi.fn()
-  const ctx = {
-    cwd: '/test-index-session-start',
-    isIdle: () => true,
-    hasPendingMessages: () => false,
-    ui: { setWidget },
-    sessionManager: {
-      getEntries: () => [taskEntry(sessionFile)],
-      getSessionFile: () => sessionFile,
-    },
-  } as unknown as ExtensionContext
-  return { ctx, setWidget }
-}
-
-describe('F1: session_start 停旧 runtime（crash-fix U4）', () => {
-  beforeEach(() => {
-    vi.useFakeTimers()
-    vi.setSystemTime(new Date(BASE))
-  })
-
-  afterEach(() => {
-    vi.useRealTimers()
-  })
-
-  it('U4: 双 session_start 后旧 timer 已停——跨保活窗口只有新 runtime 推帧', async () => {
-    const { pi, events } = createMockPi()
-    schedulerExtension(pi)
-    const sessionStart = events.get('session_start')
-    expect(sessionStart).toBeDefined()
-
-    // 第一次 session_start：runtime1 + timer1 启动，初始渲染 1 次
-    const first = createFakeCtx('/test/session-1.json')
-    sessionStart!({ type: 'session_start', reason: 'startup' }, first.ctx)
-    expect(first.setWidget).toHaveBeenCalledTimes(1)
-
-    // 前置因果锚点：静置越过保活窗口，timer1 推一帧保活帧（排除「timer 从未启动」的假绿；
-    // 也锁定跳推行为——窗口内其余 tick 零推送）
-    await vi.advanceTimersByTimeAsync(KEEPALIVE_INTERVAL_MS + TICK_INTERVAL_MS)
-    expect(first.setWidget).toHaveBeenCalledTimes(2)
-
-    // 第二次 session_start（session 替换）：F1 在装配新 runtime 前停掉 timer1
-    const second = createFakeCtx('/test/session-2.json')
-    sessionStart!({ type: 'session_start', reason: 'new_session' }, second.ctx)
-    expect(second.setWidget).toHaveBeenCalledTimes(1) // runtime2 初始渲染（实例态重置，首帧必推）
-
-    // 行为断言（验收口径）：再静置一个保活窗口，只有 runtime2 的 timer 触发推送——
-    // F1 缺失时 timer1/timer2 都活着，first 与 second 各再 +1
-    await vi.advanceTimersByTimeAsync(KEEPALIVE_INTERVAL_MS + TICK_INTERVAL_MS)
-    expect(second.setWidget).toHaveBeenCalledTimes(2) // 恰 +1：新 runtime 正常调度
-    expect(first.setWidget).toHaveBeenCalledTimes(2) // 旧 runtime 的 tick 不再发生（timer 已停）
-  })
-})