@zhushanwen/pi-scheduler 0.3.0 → 0.3.1

package/package.json

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

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

@@ -0,0 +1,171 @@
+// src/__tests__/index-generation.test.ts
+//
+// G1（S9 review 修复 / R3-M1 模块级化）集成单测：index.ts 装配点为每代 SchedulerRuntime
+// 注入代际检测回调（模块级 sessionGeneration 比对），使 stale 分诊不依赖 pi 错误文案。
+//
+// 两类拓扑：
+// - 同闭包重复 fire session_start（rpc-mode bindExtensions 重调等次要路径）——第一组用例
+//   在同一 factory 闭包上连续触发验证代数接线。
+// - factory 重跑（生产主路径：pi 每次 session 替换 newSession/fork/switchSession 都重跑
+//   factory 函数体，loader.ts extensionCache 只缓存 factory 函数对象不缓存执行结果）——
+//   装配级用例模拟两次独立 factory() 调用（各自新闭包、共享模块级代数），实证模块级变量
+//   跨 factory 重跑保留：第二代 session_start 递增模块级计数器后，第一代 runtime 的
+//   isCtxStale 翻转为 true 且其泄漏 timer 在下个 tick 前置检查自停。闭包级实现（R3-M1
+//   修复前）在此拓扑下恒 false——正是被 R3 实测证伪的生产失效路径。
+//
+// 本文件用 InstrumentedRuntime（继承真实 SchedulerRuntime，仅记录构造第三参 isCtxStale）
+// 捕获注入回调。InstrumentedRuntime 全部行为继承父类，不影响装配链本身（F1 停旧 timer
+// 等行为由 index-session-start.test.ts U4 锚定，此处不重复）。
+
+import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+// 与 index-session-start.test.ts 同款（MF-3）：mock 掉 importer，装配路径仍被调用、FS 副作用为零。
+vi.mock('../importer.js', () => ({ importLegacyStore: vi.fn(() => vi.fn()) }))
+
+// vi.mock factory 会被提升，跨模块共享状态必须经 vi.hoisted。
+const { isCtxStaleCaptures, runtimeInstances } = vi.hoisted(() => ({
+  isCtxStaleCaptures: [] as Array<(() => boolean) | undefined>,
+  runtimeInstances: [] as Array<{ stopScheduler(): void }>,
+}))
+
+// InstrumentedRuntime 继承真实实现（loadTasks/onAfterTick/startScheduler 均真实执行），
+// 仅捕获构造第三参并登记实例（afterEach 统一停 timer，避免真实 setInterval 残留）。
+vi.mock('../runtime.js', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('../runtime.js')>()
+  const RealSchedulerRuntime = actual.SchedulerRuntime
+  class InstrumentedRuntime extends RealSchedulerRuntime {
+    constructor(
+      backend: ConstructorParameters<typeof RealSchedulerRuntime>[0],
+      ctx: ConstructorParameters<typeof RealSchedulerRuntime>[1],
+      isCtxStale?: () => boolean,
+    ) {
+      super(backend, ctx, isCtxStale)
+      isCtxStaleCaptures.push(isCtxStale)
+      runtimeInstances.push(this)
+    }
+  }
+  return { ...actual, SchedulerRuntime: InstrumentedRuntime }
+})
+
+import schedulerExtension from '../index.js'
+
+const TICK_INTERVAL_MS = 30_000
+
+/**
+ * 最小 fake pi：与 index-session-start.test.ts 同款，覆盖 factory 消费的 API 面
+ * （on 捕获事件 handler 供手动触发；registerTool/registerCommand/sendMessage/appendEntry 兜底）。
+ */
+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 }
+}
+
+/** 最小 fake ctx：覆盖 session_start 装配链读到的全部字段（backend 构造 / runtime 构造 / refreshWidget）。 */
+function createFakeCtx(sessionFile: string): ExtensionContext {
+  return {
+    cwd: '/test-index-generation',
+    isIdle: () => true,
+    hasPendingMessages: () => false,
+    ui: { setWidget: vi.fn() },
+    sessionManager: {
+      getEntries: () => [],
+      getSessionFile: () => sessionFile,
+    },
+  } as unknown as ExtensionContext
+}
+
+describe('G1: index.ts 代际接线（S9）', () => {
+  beforeEach(() => {
+    isCtxStaleCaptures.length = 0
+    runtimeInstances.length = 0
+  })
+
+  afterEach(() => {
+    for (const rt of runtimeInstances) {
+      rt.stopScheduler()
+    }
+  })
+
+  it('每次 session_start 注入 isCtxStale：当前代 false、任意前代 true（跨三代）', () => {
+    const { pi, events } = createMockPi()
+    schedulerExtension(pi)
+    const sessionStart = events.get('session_start')
+    expect(sessionStart).toBeDefined()
+
+    // 第 1 代
+    sessionStart!({ type: 'session_start', reason: 'startup' }, createFakeCtx('/test/gen-1.json'))
+    expect(isCtxStaleCaptures[0]).toBeTypeOf('function')
+    expect(isCtxStaleCaptures[0]!()).toBe(false) // 当前代未替换
+
+    // 第 2 代（session 替换）：第 1 代自此 stale，第 2 代为当前代
+    sessionStart!({ type: 'session_start', reason: 'new_session' }, createFakeCtx('/test/gen-2.json'))
+    expect(isCtxStaleCaptures[0]!()).toBe(true)
+    expect(isCtxStaleCaptures[1]!()).toBe(false)
+
+    // 第 3 代（resume 重入）：前两代均 stale
+    sessionStart!({ type: 'session_start', reason: 'resume' }, createFakeCtx('/test/gen-3.json'))
+    expect(isCtxStaleCaptures[0]!()).toBe(true)
+    expect(isCtxStaleCaptures[1]!()).toBe(true)
+    expect(isCtxStaleCaptures[2]!()).toBe(false)
+  })
+
+  // ── R3-M1/R3-S5：factory 重跑装配级用例（生产主路径拓扑）──
+  // pi 每次 session 替换都重跑 factory 函数体（新闭包）。本用例模拟两次独立 factory()
+  // 调用 + 各 fire 一次 session_start，实证「模块级 sessionGeneration 跨 factory 重跑保留」：
+  // 闭包级实现（修复前）在第二代 session_start 后 firstStale() 仍恒 false——测试即失败。
+  it('factory 重跑：第二次 factory 执行 + session_start 后，第一代 runtime isCtxStale 为 true 且 tick 前置自停', async () => {
+    vi.useFakeTimers()
+    vi.setSystemTime(new Date('2026-01-01T00:00:00Z'))
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    try {
+      // 第一代：独立 factory 执行 + session_start 装配（runtime1 真实 startScheduler）
+      const first = createMockPi()
+      schedulerExtension(first.pi)
+      const firstSessionStart = first.events.get('session_start')
+      expect(firstSessionStart).toBeDefined()
+      firstSessionStart!({ type: 'session_start', reason: 'startup' }, createFakeCtx('/test/factory-rerun-1.json'))
+      const firstStale = isCtxStaleCaptures[0]!
+      expect(firstStale).toBeTypeOf('function')
+      expect(firstStale()).toBe(false) // 第一代是当前代
+
+      // 第二代：再次独立执行 factory（模拟 newSession/fork/switchSession 的 factory 重跑，
+      // 新闭包的 service 为 null——第一代闭包的 service 对它不可见，F1 停不到第一代 timer，
+      // 复现「F1 未能触达、只剩 G1 前置检查」的泄漏路径）+ session_start
+      const second = createMockPi()
+      schedulerExtension(second.pi)
+      const secondSessionStart = second.events.get('session_start')
+      expect(secondSessionStart).toBeDefined()
+      secondSessionStart!({ type: 'session_start', reason: 'new_session' }, createFakeCtx('/test/factory-rerun-2.json'))
+
+      // 核心断言：模块级计数器被第二代闭包的 session_start 递增，第一代 runtime 的
+      // isCtxStale 生效（闭包级实现在此恒 false——R3-M1 修复的生产失效路径）
+      expect(firstStale()).toBe(true)
+      expect(isCtxStaleCaptures[1]!()).toBe(false) // 第二代是当前代
+
+      // tick 前置自停：第一代 runtime 的泄漏 timer 在下个 tick 被代际前置检查拦截
+      // （G1-b 的生产路径验证：warn "tick stopped" + timer 自停，后续 tick 不再发生）
+      await vi.advanceTimersByTimeAsync(TICK_INTERVAL_MS)
+      const warnText = warnSpy.mock.calls.map(c => String(c[0])).join('\n')
+      expect(warnText).toContain('tick stopped')
+      expect(warnText).not.toContain('tick error')
+
+      const warnCountAfterSelfStop = warnSpy.mock.calls.length
+      await vi.advanceTimersByTimeAsync(TICK_INTERVAL_MS * 2) // timer 已停，无新 warn
+      expect(warnSpy.mock.calls.length).toBe(warnCountAfterSelfStop)
+    } finally {
+      warnSpy.mockRestore()
+      vi.useRealTimers()
+    }
+  })
+})

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

@@ -0,0 +1,107 @@
+// 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）：第二次 session_start 后 advance 30s，tick 引起的 widget 刷新
+// 增量恰 +1（只有新 runtime 的 timer 在跑）；F1 缺失时两个 timer 都活着，增量为 +2。
+// 观测面说明：session_start 硬编码 new PiSchedulerBackend（now() = Date.now()，无法注入计数），
+// 故用 onAfterTick → refreshWidget → ctx.ui.setWidget 的调用计数作为 tick 发生次数的
+// 行为观测面（每个 tick 恰好一次，与 backend.now 计数等价）。
+
+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'
+
+const TICK_INTERVAL_MS = 30_000
+
+/**
+ * 最小 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 }
+}
+
+/**
+ * 最小 fake ctx：覆盖 session_start 装配链读到的全部字段——PiSchedulerBackend 构造
+ * （sessionManager）、SchedulerRuntime 构造（isIdle/hasPendingMessages）、importLegacyStore
+ * （cwd，已 mock）、refreshWidget（ui.setWidget）。
+ * setWidget 以独立引用导出：session_start 初始渲染 + 每次 tick 末 onAfterTick 各调一次，
+ * 是「哪个 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: () => [],
+      getSessionFile: () => sessionFile,
+    },
+  } as unknown as ExtensionContext
+  return { ctx, setWidget }
+}
+
+describe('F1: session_start 停旧 runtime（crash-fix U4）', () => {
+  beforeEach(() => {
+    vi.useFakeTimers()
+    vi.setSystemTime(new Date('2026-01-01T00:00:00Z'))
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  it('U4: 双 session_start 后旧 timer 已停——advance 30s tick 引起的刷新恰 +1 而非 +2', 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)
+
+    // 前置因果锚点：advance 30s，timer1 正常 tick 一次（排除「timer 从未启动」的假绿）
+    await vi.advanceTimersByTimeAsync(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 初始渲染
+
+    // 行为断言（验收口径）：再 advance 30s，只有 runtime2 的 timer 触发一次 tick——
+    // F1 缺失时 timer1/timer2 都活着，first 与 second 的 spy 各 +1（合计 +2）
+    await vi.advanceTimersByTimeAsync(TICK_INTERVAL_MS)
+    expect(second.setWidget).toHaveBeenCalledTimes(2) // 恰 +1：新 runtime 正常调度
+    expect(first.setWidget).toHaveBeenCalledTimes(2) // 旧 runtime 的 tick 不再发生（timer 已停）
+  })
+})

package/src/__tests__/runtime.test.ts

@@ -162,6 +162,77 @@ describe('SchedulerRuntime', () => {
     })
   })
 
+  // ── R3-S1：dispatchTask in-flight 守卫 ──
+  // tick 为 fire-and-forget：tick1 的 await sendMessage 挂起超过 TICK_INTERVAL_MS（如 pi
+  // 卡死）时，tick2 的 step2 再标 pending → step3 对同一 task 并发第二个 dispatch → 同一
+  // prompt 双注入（force 任务绕过 isIdle gate 直接受影响）。守卫：同任务在途（Set<taskId>）
+  // 时 skip 本轮并 warn；不同任务不受影响。
+  describe('dispatchTask in-flight 守卫（R3-S1）', () => {
+    beforeEach(() => {
+      vi.useFakeTimers()
+      vi.setSystemTime(new Date('2026-01-01T00:00:00Z'))
+    })
+
+    afterEach(() => {
+      vi.useRealTimers()
+    })
+
+    it('sendMessage 挂起期间下一 tick 同任务被跳过：不双注入、warn in-flight、完成后 runCount=1', async () => {
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+      let resolveSend: (() => void) | undefined
+      const sendPromise = new Promise<void>(resolve => { resolveSend = resolve })
+      backend.sendMessage = vi.fn(() => sendPromise)
+
+      const task = await runtime.addTask('in-flight', { mode: 'interval', intervalMs: 60000 }, { force: true })
+      task.nextRunAt = Date.now() - 1000
+
+      // tick1：dispatch 进入 sendMessage 挂起（同步段已置 in-flight 标记）
+      const tick1 = runtime.tickScheduler()
+      expect(backend.sendMessage).toHaveBeenCalledTimes(1)
+      expect(task.pending).toBe(true) // dispatch 未完成，pending 未清
+
+      // tick2（模拟 30s 后 pi 仍卡死）：同任务再标 pending → step3 dispatchTask 命中
+      // in-flight 守卫 → skip + warn（修复前：同一 prompt 双注入）
+      await runtime.tickScheduler()
+      expect(backend.sendMessage).toHaveBeenCalledTimes(1)
+      const warnText = warnSpy.mock.calls.map(c => String(c[0])).join('\n')
+      expect(warnText).toContain('already in flight')
+
+      // 放行挂起的 sendMessage：tick1 正常收尾（状态推进恰好一次）
+      resolveSend!()
+      await tick1
+      expect(backend.sendMessage).toHaveBeenCalledTimes(1)
+      expect(task.runCount).toBe(1)
+      expect(task.pending).toBe(false)
+      warnSpy.mockRestore()
+    })
+
+    it('挂起 dispatch 只挡同任务：其他任务在下一 tick 正常 dispatch 不受影响', async () => {
+      let resolveSend: (() => void) | undefined
+      const sendPromise = new Promise<void>(resolve => { resolveSend = resolve })
+      backend.sendMessage = vi.fn(() => sendPromise)
+
+      const task1 = await runtime.addTask('first', { mode: 'interval', intervalMs: 60000 }, { force: true })
+      const task2 = await runtime.addTask('second', { mode: 'interval', intervalMs: 60000 }, { force: true })
+      task1.nextRunAt = Date.now() - 1000
+      task2.nextRunAt = Date.now() - 1000
+
+      // tick1：task1 dispatch 挂起（step3 顺序 await，task2 尚未轮到）
+      const tick1 = runtime.tickScheduler()
+      expect(backend.sendMessage).toHaveBeenCalledTimes(1)
+
+      // tick2：task1 命中守卫跳过，task2 无在途 → 正常 dispatch（守卫按 taskId 粒度隔离）。
+      // 注：tick2 挂起在 task1 的 await dispatchTask（守卫命中即 resolved promise）与 task2
+      // 的 await sendMessage 上，先放行再 await，完成态统一断言
+      const tick2 = runtime.tickScheduler()
+      resolveSend!()
+      await Promise.all([tick1, tick2])
+      expect(backend.sendMessage).toHaveBeenCalledTimes(2)
+      expect(task1.runCount).toBe(1)
+      expect(task2.runCount).toBe(1)
+    })
+  })
+
   // ── M10b：rate-limit ──
   // dispatchTask 受 RATE_LIMIT_PER_MINUTE=6 限制。前 6 次成功（sendMessage 被调），
   // 第 7 次被 hasDispatchCapacity 拒绝（dispatchTimestamps.length 已达 6）。
@@ -463,4 +534,199 @@ describe('SchedulerRuntime', () => {
       expect(task.expiresAt).toBeUndefined()
     })
   })
+
+  // ── F2：tick 错误分诊（crash-fix）──
+  // startScheduler 的 interval 回调对 fire-and-forget 的 tickScheduler() 加 catch：
+  // stale 类错误（session 替换后泄漏 timer 访问 stale ctx）→ warn "tick stopped" + stopScheduler
+  // 自停；其他错误 → warn "tick error" 继续调度。修复前 tick 内异常无人接住 →
+  // unhandledRejection → pi 主进程 exit 1。
+  describe('tick 错误分诊（F2）', () => {
+    const TICK_INTERVAL_MS = 30_000
+
+    beforeEach(() => {
+      vi.useFakeTimers()
+      vi.setSystemTime(new Date('2026-01-01T00:00:00Z'))
+    })
+
+    afterEach(() => {
+      runtime.stopScheduler()
+      vi.useRealTimers()
+    })
+
+    it('U1: stale 错误 → warn "tick stopped" + timer 自停，后续 tick 不再发生', async () => {
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+      const nowSpy = vi.spyOn(backend, 'now')
+      runtime.onAfterTick(() => {
+        throw new Error('This extension ctx is stale after session replacement or reload.')
+      })
+
+      runtime.startScheduler()
+      await vi.advanceTimersByTimeAsync(TICK_INTERVAL_MS) // tick1：stale 抛 → catch 分诊 → 自停
+
+      const warnText = warnSpy.mock.calls.map(c => String(c[0])).join('\n')
+      expect(warnText).toContain('tick stopped')
+      expect(warnText).not.toContain('tick error')
+
+      const countAfterSelfStop = nowSpy.mock.calls.length
+      expect(countAfterSelfStop).toBeGreaterThan(0) // tick1 确实跑过（排除「timer 未启动」假绿）
+
+      await vi.advanceTimersByTimeAsync(TICK_INTERVAL_MS * 2) // 60s：timer 已停，无新 tick
+      expect(nowSpy.mock.calls.length).toBe(countAfterSelfStop) // now 计数不再增长
+      warnSpy.mockRestore()
+      nowSpy.mockRestore()
+    })
+
+    it('U2: 非 stale 错误 → warn "tick error" 且调度继续（advance 两次 now 计数 +2）', async () => {
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+      const nowSpy = vi.spyOn(backend, 'now')
+      runtime.onAfterTick(() => {
+        throw new Error('boom')
+      })
+
+      runtime.startScheduler()
+      await vi.advanceTimersByTimeAsync(TICK_INTERVAL_MS) // tick1：warn 但不停
+
+      const warnText = warnSpy.mock.calls.map(c => String(c[0])).join('\n')
+      expect(warnText).toContain('tick error')
+      expect(warnText).not.toContain('tick stopped')
+
+      const countAfterFirstTick = nowSpy.mock.calls.length
+      expect(countAfterFirstTick).toBeGreaterThan(0)
+
+      await vi.advanceTimersByTimeAsync(TICK_INTERVAL_MS * 2) // 2 个后续 tick 照常
+      expect(nowSpy.mock.calls.length).toBe(countAfterFirstTick + 2)
+      warnSpy.mockRestore()
+      nowSpy.mockRestore()
+    })
+
+    it('U5: stopScheduler 幂等——连续调用两次不抛、无副作用', () => {
+      runtime.startScheduler()
+      expect(() => {
+        runtime.stopScheduler()
+        runtime.stopScheduler()
+      }).not.toThrow()
+    })
+  })
+
+  // ── G1：代际检测分诊（S9 review 修复 / R3-M1 模块级化）──
+  // isCtxStale（index.ts 注入的模块级代数比对）为主判，替代对 pi 错误文案的依赖：
+  // - G1-a：in-flight tick 内代际翻转 + 任意非文案错误 → catch 分诊走 stale 自停（不依赖文案）
+  // - G1-b：代际翻转后（无任何错误）泄漏 timer 在下个 tick 前置检查自停，不进入 tick
+  // - G1-c：显式注入 isCtxStale=false + 非 stale 错误 → 仍 "tick error" 继续调度（不误伤）
+  // - G1-d：isCtxStale=false 但错误文案含 stale 片段 → 文案兜底仍自停（覆盖 reload 盲区：
+  //   clearExtensionCache 后 jiti 重 import 全新模块环境，旧闭包的模块级代数冻结不再递增，
+  //   只剩文案能识别 stale；模块级方案的装配级验证见 index-generation.test.ts factory 重跑用例）
+  describe('G1: 代际检测分诊（S9）', () => {
+    const TICK_INTERVAL_MS = 30_000
+    let staleFlag: boolean
+    let genRuntime: SchedulerRuntime
+
+    beforeEach(() => {
+      vi.useFakeTimers()
+      vi.setSystemTime(new Date('2026-01-01T00:00:00Z'))
+      staleFlag = false
+      genRuntime = new SchedulerRuntime(backend, mockCtx, () => staleFlag)
+    })
+
+    afterEach(() => {
+      genRuntime.stopScheduler()
+      vi.useRealTimers()
+    })
+
+    it('G1-a: in-flight tick 期间代际翻转 + 非文案错误 → warn "tick stopped" + 自停（不依赖 pi 错误文案）', async () => {
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+      const nowSpy = vi.spyOn(backend, 'now')
+      // tick 内先翻世代（模拟 session 替换交错发生在 dispatch await 窗口），再抛与
+      // pi 文案完全无关的错误——旧实现按文案分诊会误判为普通错误继续调度（若 pi 改文案）
+      genRuntime.onAfterTick(() => {
+        staleFlag = true
+        throw new Error('some unexpected failure')
+      })
+
+      genRuntime.startScheduler()
+      await vi.advanceTimersByTimeAsync(TICK_INTERVAL_MS) // tick1：catch 分诊走 G1 代际 → 自停
+
+      const warnText = warnSpy.mock.calls.map(c => String(c[0])).join('\n')
+      expect(warnText).toContain('tick stopped')
+      expect(warnText).not.toContain('tick error')
+
+      const countAfterSelfStop = nowSpy.mock.calls.length
+      expect(countAfterSelfStop).toBeGreaterThan(0) // tick1 确实跑过（排除「timer 未启动」假绿）
+
+      await vi.advanceTimersByTimeAsync(TICK_INTERVAL_MS * 2) // timer 已停，无新 tick
+      expect(nowSpy.mock.calls.length).toBe(countAfterSelfStop)
+      warnSpy.mockRestore()
+      nowSpy.mockRestore()
+    })
+
+    it('G1-b: 代际翻转后泄漏 timer 在下个 tick 前置检查自停——不进入 tick（backend.now 零调用）', async () => {
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+      const nowSpy = vi.spyOn(backend, 'now')
+      genRuntime.startScheduler()
+      // session 替换：代际翻转（F1 未能触达的泄漏 timer 场景；无任何错误发生）
+      staleFlag = true
+
+      await vi.advanceTimersByTimeAsync(TICK_INTERVAL_MS) // tick1：前置检查命中 → 自停
+
+      const warnText = warnSpy.mock.calls.map(c => String(c[0])).join('\n')
+      expect(warnText).toContain('tick stopped')
+      expect(warnText).not.toContain('tick error')
+      // 前置检查在 tickScheduler 之前拦截：tick 本体未执行（now 零调用，无 dispatch/append）
+      expect(nowSpy).not.toHaveBeenCalled()
+
+      await vi.advanceTimersByTimeAsync(TICK_INTERVAL_MS * 2) // timer 已停，仍零调用
+      expect(nowSpy).not.toHaveBeenCalled()
+      warnSpy.mockRestore()
+      nowSpy.mockRestore()
+    })
+
+    it('G1-c: isCtxStale 注入但返回 false + 非 stale 错误 → warn "tick error" 且调度继续', async () => {
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+      const nowSpy = vi.spyOn(backend, 'now')
+      // staleFlag 恒 false（beforeEach 初始化）：代际未翻转，注入存在不改变分诊结果
+      genRuntime.onAfterTick(() => {
+        throw new Error('boom')
+      })
+
+      genRuntime.startScheduler()
+      await vi.advanceTimersByTimeAsync(TICK_INTERVAL_MS) // tick1：非 stale → warn 继续调度
+
+      const warnText = warnSpy.mock.calls.map(c => String(c[0])).join('\n')
+      expect(warnText).toContain('tick error')
+      expect(warnText).not.toContain('tick stopped')
+
+      const countAfterFirstTick = nowSpy.mock.calls.length
+      expect(countAfterFirstTick).toBeGreaterThan(0)
+
+      await vi.advanceTimersByTimeAsync(TICK_INTERVAL_MS * 2) // 2 个后续 tick 照常
+      expect(nowSpy.mock.calls.length).toBe(countAfterFirstTick + 2)
+      warnSpy.mockRestore()
+      nowSpy.mockRestore()
+    })
+
+    it('G1-d: isCtxStale 返回 false 但错误文案含 stale 片段 → 文案兜底仍自停（覆盖 reload 盲区）', async () => {
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+      const nowSpy = vi.spyOn(backend, 'now')
+      // reload 场景模拟：factory 重跑后旧闭包代际计数不再递增（staleFlag 恒 false），
+      // 只有错误文案能识别 stale——兜底支必须独立于代际检测生效
+      genRuntime.onAfterTick(() => {
+        throw new Error('This extension ctx is stale after session replacement or reload.')
+      })
+
+      genRuntime.startScheduler()
+      await vi.advanceTimersByTimeAsync(TICK_INTERVAL_MS) // tick1：文案兜底 → 自停
+
+      const warnText = warnSpy.mock.calls.map(c => String(c[0])).join('\n')
+      expect(warnText).toContain('tick stopped')
+      expect(warnText).not.toContain('tick error')
+
+      const countAfterSelfStop = nowSpy.mock.calls.length
+      expect(countAfterSelfStop).toBeGreaterThan(0)
+
+      await vi.advanceTimersByTimeAsync(TICK_INTERVAL_MS * 2)
+      expect(nowSpy.mock.calls.length).toBe(countAfterSelfStop)
+      warnSpy.mockRestore()
+      nowSpy.mockRestore()
+    })
+  })
 })

package/src/__tests__/service.test.ts

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

package/src/index.ts

@@ -17,6 +17,22 @@ import {
 } from './tool.js'
 import { renderSchedulerWidget } from './widget.js'
 
+// G1（代际检测，S9/R3-M1）：session 代际计数器。必须声明在模块级而非 factory 体内：
+// pi 每次 session 替换（newSession/fork/switchSession）都重跑 extension factory 函数体
+// （loader.ts loadExtension 无条件 `await factory(api)`；extensionCache 只缓存 factory
+// 函数对象、不缓存执行结果）——闭包级声明每次重跑即重置，各代 runtime 的 isCtxStale 恒
+// false（R3 实测证伪的回归）。模块级声明下，extensionCache 命中期间（同 cwd 未 reload）
+// factory 是同一函数对象、共享同一模块环境绑定，计数器跨 factory 重跑保留递增：新闭包的
+// session_start 递增本计数器，各代 runtime 构造时捕获的代数从此小于模块值 → isCtxStale
+// 生效——stale 分诊不依赖 pi 错误文案（Error message 非契约 API，pi 升级改文案即静默失效）。
+//
+// 残余盲区（reload）：显式 reload / cwd 变化触发 clearExtensionCache → jiti 重新 import
+// （moduleCache:false）产生全新模块环境，本计数器随新环境重置；旧闭包引用的是旧模块环境的
+// 绑定，永不再递增 → 其 isCtxStale 恒 false。该盲区由两道既有防线覆盖：pi 在替换前 await
+// fire session_shutdown（F1 stopScheduler 主防线，teardownCurrent）+ runtime 侧
+// STALE_CTX_MARKER 文案兜底（F2 catch 分诊）。
+let sessionGeneration = 0
+
 /**
  * pi-scheduler extension factory。
  * 注册 schedule + schedule_control 两个 tool、/schedule command、session 事件。
@@ -41,13 +57,24 @@ export default function schedulerExtension(pi: ExtensionAPI): void {
   }
 
   pi.on('session_start', (_event, ctx: ExtensionContext) => {
+    // G1：先递增模块级代数再装配——自此同模块环境内所有前代 runtime 的 isCtxStale 返回
+    // true（stale）。myGeneration 是本 handler 的代数，注入的比对闭包读实时模块级
+    // sessionGeneration 与之比较（factory 重跑的新闭包与本闭包共享同一模块绑定）。
+    sessionGeneration += 1
+    const myGeneration = sessionGeneration
+    // F1（治本）：session 替换/重入时先停上一代 runtime 的 tick interval——dispatch 的 await sendMessage
+    // 窗口与 session 替换交错时旧 session_shutdown 可能永远等不到（timer 泄漏源头）。stopScheduler 幂等，
+    // shutdown 已停过再停一次无副作用。
+    service?.runtime.stopScheduler()
     // 装配点：backend（ctx.sessionManager 读 entries / pi.appendEntry 写 op）→ runtime（内存态 + 调度）→ service（业务入口）
     const backend = new PiSchedulerBackend(ctx, pi)
     // 旧 store 原子导入（CL3 方案A）：必须在 backend.loadTasks() 之前执行——
     // append 的 upsert entry 进入 pi 内存 fileEntries，紧接的 loadTasks replay 统一重放读到导入任务。
     // ctx.cwd 类型为 string（SDK ExtensionContext 必填），无需 ?? process.cwd() 兜底（CL2）。
     importCleanup = importLegacyStore(ctx.cwd, pi, ctx.sessionManager.getSessionFile())
-    const runtime = new SchedulerRuntime(backend, ctx)
+    // G1：注入代际比对（本 runtime 建立时的代数 vs 实时代数），供 tick 前置检查与
+    // F2 catch 分诊判定 stale——不依赖 pi 错误文案。
+    const runtime = new SchedulerRuntime(backend, ctx, () => sessionGeneration !== myGeneration)
     runtime.loadTasks(backend.loadTasks())
     // W2：tick 后回调刷新 widget（替代独立 widgetTimer + setInterval，节奏对齐 TICK_INTERVAL_MS）
     runtime.onAfterTick(() => refreshWidget(ctx))

package/src/runtime.ts

@@ -16,6 +16,16 @@ const RATE_LIMIT_PER_MINUTE = 6
 const TICK_INTERVAL_MS = 30_000
 const DEFAULT_EXPIRY_MS = 7 * 24 * 60 * 60 * 1000 // 7 days
 const HISTORY_LIMIT = 20 // 与 replayFoldEntries 的裁剪上限一致（advance 折叠 / dispatch 累积共用）
+// pi ExtensionRunner 在 session 替换后访问 stale ctx 时抛出的错误文案片段。
+// 兜底通道（防御纵深）：G1 模块级代际检测（isCtxStale）为主判，覆盖同模块环境内的 session
+// 替换路径（newSession/fork/switchSession：extensionCache 命中，factory 重跑但模块环境共享，
+// 模块级代数被新闭包递增）；本子串覆盖代际盲区——显式 reload / cwd 变化触发
+// clearExtensionCache 后 jiti 重新 import 产生全新模块环境，旧闭包引用的模块级代数冻结
+// 不再递增，isCtxStale 恒 false，此时除 session_shutdown teardown 主防线外只剩错误文案
+// 能识别 stale。
+// 注意：pi 非契约 API（Error message 非稳定接口），pi 升级需回归验证 runtime.test.ts 的
+// U1 / G1-d 文案锚定用例；文案变更时此兜底失效，后果为 timer 泄漏 + 每 30s warn（不 crash）。
+const STALE_CTX_MARKER = 'stale after session replacement'
 
 export class SchedulerRuntime {
   private tasks: Map<string, ScheduledTask> = new Map()
@@ -24,17 +34,26 @@ export class SchedulerRuntime {
   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>()
 
   /**
    * 依赖反转构造：backend 承担 appendEntry/pi.sendMessage/时间源，runtime 只持有内存态。
    * 不触碰任何 FS / session JSONL（测试可用 MockSchedulerBackend 零副作用注入）。
+   *
+   * isCtxStale（G1 代际检测，S9/R3-M1）：返回 true 表示本 runtime 建立时的 session 已被
+   * 替换。index.ts 装配点注入（模块级代数比对，R3-M1），使 stale 分诊不依赖 pi 错误文案；
+   * 缺省（不注入）恒视为非 stale——纯 runtime 单测与旧装配路径行为不变。
    */
   constructor(
     backend: SchedulerBackend,
     ctx: Pick<ExtensionContext, 'isIdle' | 'hasPendingMessages'>,
+    isCtxStale?: () => boolean,
   ) {
     this.backend = backend
     this.ctx = ctx
+    this.isCtxStale = isCtxStale
   }
 
   // ── 任务 CRUD ──
@@ -160,7 +179,30 @@ export class SchedulerRuntime {
 
   startScheduler(): void {
     if (this.tickTimer) return
-    this.tickTimer = setInterval(() => void this.tickScheduler(), TICK_INTERVAL_MS)
+    this.tickTimer = setInterval(() => {
+      // G1（代际前置检查，S9）：本 runtime 所属 session 已被替换 → timer 属泄漏资源，
+      // 自停退场且不进入本轮 tick（不触碰捕获的 stale ctx）。主防线是 F1（session_start
+      // 停旧 timer），此处覆盖 F1 未能触达的泄漏路径——且不依赖「stale ctx 访问恰好抛错」
+      // 或 pi 错误文案，代际一翻转即可静默退场。
+      if (this.isCtxStale?.()) {
+        this.retireStaleTimer()
+        return
+      }
+      // F2（防御兜底）：fire-and-forget 的 tick 链路必须自带 catch——tick 内任何异常
+      // （典型：session 替换后泄漏 timer 的 onAfterTick → refreshWidget 访问 stale ctx.ui 抛错）
+      // 若无人接住即 unhandledRejection，直接崩掉 pi 主进程。分诊：G1 模块级代数比对为主判
+      // （契约内，不受 pi 文案变更影响），STALE_CTX_MARKER 子串为兜底（覆盖 reload 产生全新
+      // 模块环境后旧闭包代数冻结、isCtxStale 恒 false 的盲区）。stale 类错误说明本 runtime
+      // 所属 session 已被替换，timer 属泄漏资源，自停退场；其他错误仅告警，不终止调度。
+      void this.tickScheduler().catch((err: unknown) => {
+        const message = err instanceof Error ? err.message : String(err)
+        if (this.isCtxStale?.() || message.includes(STALE_CTX_MARKER)) {
+          this.retireStaleTimer()
+        } else {
+          console.warn(`[scheduler] tick error: ${message}`)
+        }
+      })
+    }, TICK_INTERVAL_MS)
   }
 
   stopScheduler(): void {
@@ -170,6 +212,16 @@ export class SchedulerRuntime {
     }
   }
 
+  /**
+   * stale 自停退场（G1 前置检查与 F2 catch 分诊共用）：warn 观测口径与 crash-fix 一致
+   * （含 "tick stopped"，U1 断言锚定）+ stopScheduler（幂等）。timer 自停后调度由
+   * session_start 重建的新一代 runtime 接管。
+   */
+  private retireStaleTimer(): void {
+    console.warn(`[scheduler] tick stopped: stale extension ctx (session replaced); timer self-retired`)
+    this.stopScheduler()
+  }
+
   /**
    * 注册 tick 后回调（W2）。index.ts 注册 refreshWidget 替代独立 widgetTimer——
    * 每次 tickScheduler 末尾调用，对齐 TICK_INTERVAL_MS 刷新 widget。
@@ -218,15 +270,38 @@ export class SchedulerRuntime {
 
   /**
    * dispatch 单个任务。返回 true 表示真的发送了 message，false 表示 no-op
-   * （task disabled / rate-limited / 非 force 且 busy）。
-   * sendMessage 抛错时记录 failed 状态但不 rethrow，让 tick 继续处理其他任务。
+   * （task disabled / 已有同任务在途 / rate-limited / 非 force 且 busy）。
    *
-   * 持久化（append-only）：recurring 成功推进 nextRunAt → append advance（status='success' CL8）；
-   * once 成功 → append delete。失败 dispatch 不 append（CL7 重试语义，transient 失败 nextRunAt 未推进）。
+   * R3-S1 in-flight 守卫：tick 为 fire-and-forget，若 tick1 的 `await backend.sendMessage`
+   * 挂起超过 TICK_INTERVAL_MS（如 pi 卡死），tick2 的 step2 会再标 pending、step3 对同一
+   * task 并发第二个 dispatch → 同一 prompt 双注入（force 任务绕过 isIdle gate 直接受影响）。
+   * 参照 subagent-workflow resumesInFlight 模式：入口同步置位、finally 清除（覆盖 gate /
+   * rate-limit / sendMessage 抛错 / 成功推进全部退出路径）；命中时 skip 本轮并 warn
+   * （不 throw——tick 继续处理其他任务，本任务 pending 保留到下轮重试）。
    */
   async dispatchTask(task: ScheduledTask): Promise<boolean> {
     if (!task.enabled) return false
+    if (this.dispatchesInFlight.has(task.id)) {
+      console.warn(`[scheduler] dispatch already in flight for task ${task.id}; skipping this tick`)
+      return false
+    }
+    this.dispatchesInFlight.add(task.id)
+    try {
+      return await this.dispatchTaskInner(task)
+    } finally {
+      this.dispatchesInFlight.delete(task.id)
+    }
+  }
 
+  /**
+   * dispatch 本体（dispatchTask 守卫置位后执行；runTaskNow 与 tick step3 共用入口，
+   * 手动 run-now 与挂起中的 tick dispatch 并发时同样被守卫拦截）。
+   * sendMessage 抛错时记录 failed 状态但不 rethrow，让 tick 继续处理其他任务。
+   *
+   * 持久化（append-only）：recurring 成功推进 nextRunAt → append advance（status='success' CL8）；
+   * 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()) {

package/src/service.ts

@@ -133,7 +133,7 @@ export class SchedulerService {
   /**
    * 立即执行任务。语义细分：
    * 任务不存在 → TASK_NOT_FOUND；任务存在但 dispatch no-op
-   * （disabled / busy / rate-limited）→ DISPATCH_SKIPPED。
+   * （disabled / busy / rate-limited / 同任务 dispatch 在途）→ DISPATCH_SKIPPED。
    * 修复了旧实现把 no-op 误报为 not found 的混同。
    */
   async run(id: string | undefined): Promise<ServiceResult> {
@@ -148,7 +148,7 @@ export class SchedulerService {
       return {
         success: false,
         errorCode: 'DISPATCH_SKIPPED',
-        message: `Task ${id} not dispatched (busy, disabled, or rate-limited).`,
+        message: `Task ${id} not dispatched (busy, disabled, rate-limited, or a dispatch already in flight).`,
       }
     }
     return { success: true, message: `Task ${id} executed.` }