@zhushanwen/pi-scheduler 0.9.0 → 0.9.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-scheduler",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "type": "module",
   "main": "index.ts",
   "taiji": {
@@ -51,10 +51,10 @@
   },
   "dependencies": {
     "croner": "^9.0.0",
-    "@zhushanwen/extension-protocol": "0.13.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.9.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/format.ts

@@ -1,6 +1,19 @@
+// 时间格式化器（r4 M1 locale 版）：formatSchedule / formatRelativeTime 是 locale 必填的
+// 本地实现（UiLocale 双语输出，i18n.ts / widget / service / commands 消费）；fix 轨 locale
+// 化与 U2 protocol 下沉（无 locale 面，服务 taiji plugin 管理面）暂双轨并存，收敛待后续
+// 把 locale 版提升进 @zhushanwen/extension-protocol。formatDuration / MS_PER_* 单源
+// @zhushanwen/extension-protocol（re-export 保持既有 import 路径）。
 import { formatDuration, MS_PER_DAY, MS_PER_HOUR, MS_PER_MINUTE, MS_PER_SECOND } from './parsing.js'
 import type { ScheduleSpec, TaskKind } from './types.js'
 
+export {
+  MS_PER_DAY,
+  MS_PER_HOUR,
+  MS_PER_MINUTE,
+  MS_PER_SECOND,
+  formatDuration,
+} from '@zhushanwen/extension-protocol'
+
 /**
  * 界面语言（L2 extension 侧文案语言，经 `<dataDir>/ui-preferences.json` 通道获取）。
  * 定义在 format.ts：i18n.ts 依赖本模块的格式化器，类型反向定义会成环——i18n.ts 再导出。

package/src/replay.ts

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

package/src/types.ts

@@ -1,103 +1,28 @@
-import type { ProviderConfig } from '@earendil-works/pi-coding-agent'
-
-// ── 调度规格 ──
-
-export type ScheduleSpec =
-  | { mode: 'cron'; cronExpression: string }
-  | { mode: 'interval'; intervalMs: number }
-
-// ── 任务 ──
-
-export type TaskKind = 'once' | 'recurring'
-export type TaskStatus = 'success' | 'failed'
-
-export interface ScheduledTask {
-  id: string                        // 8 位 hex，自动生成
-  name: string                      // 可读名称（用户指定或从 prompt 自动截取前 30 字）
-  prompt: string                    // 到期时注入的 message
-  kind: TaskKind
-  schedule: ScheduleSpec            // once 时 intervalMs = delayMs
-  model?: string                    // 任务执行模型（scoped model id，provider/model）；undefined = 跟随会话当前模型
-  enabled: boolean
-  createdAt: number
-  nextRunAt: number
-  expiresAt?: number                // undefined = 永不过期
-  runCount: number
-  lastRunAt?: number
-  lastStatus?: TaskStatus
-  lastError?: string                // 最近一次失败原因（cron 失效 / appendEntry 失败）
-  history: ExecutionRecord[]        // 最近 HISTORY_LIMIT 条
-  ownerSessionFile?: string         // append-only owner：记录任务创建时所属的 session JSONL，fork 重放时按此过滤非 owner 任务（gap1）
-  pending?: boolean                 // 运行时标记：到期待 dispatch（非持久化语义，勿与 TaskStatus 混淆）
-}
-
-export interface ExecutionRecord {
-  at: number
-  status: TaskStatus
-}
-
-/**
- * history 裁剪上限（ext-simplify-08 L5 单点）：runtime 侧 dispatch 累积
- * （onDispatchSuccess）与 replay 侧 advance 折叠共用同一上限——
- * 双处各持字面量会漂移（曾 runtime.ts / replay.ts 各写一份 20），收敛到 types.ts 单点导出。
- */
-export const HISTORY_LIMIT = 20
-
-/**
- * 追加执行记录并按 HISTORY_LIMIT 裁剪（ext-simplify-17 B4 单点）：runtime 侧 dispatch
- * 累积与 replay 侧 advance 折叠共用的 push+trim——三处内联时与上限字面量同源存在
- * 「漏改一处」漂移风险，随上限一并收敛。
- */
-export function appendExecutionRecord(task: ScheduledTask, at: number, status: TaskStatus): void {
-  task.history.push({ at, status })
-  if (task.history.length > HISTORY_LIMIT) task.history.shift()
-}
-
-// ── CustomEntry event sourcing（append-only 任务存储）──
+// entry 契约与折叠器单源于 @zhushanwen/extension-protocol（U2 折叠器下沉：扩展与 taiji plugin
+// 同源消费，杜绝双实现漂移）。本文件保持既有 import 路径不变（re-export），仅保留
+// 扩展侧写面私有物（toTaskSnapshot / 旧 store 形状 / 工具参数 / ack 机制类型）。
 
-/**
- * pi.appendEntry 写入的 custom entry customType 标识（ext-simplify-17 B1 单点）：
- * backend.appendEntry 写入 / replay.foldEntries 过滤 / importer 旧 store 导入三处共用——
- * 各持字面量时「改一处漏两处」会使写入与重放识别脱节（写入新标识、重放不认，任务静默丢失）。
- */
-export const TASK_ENTRY_TYPE = 'pi-scheduler:task'
-
-/**
- * upsert op 携带的全量任务快照（不含 ownerSessionFile / pending）。
- * ownerSessionFile 放在 op 顶层（见 SchedulerEntryOp.upsert），
- * pending 是运行时标记不持久化。其余字段与 ScheduledTask 对齐。
- */
-export interface TaskSnapshot {
-  id: string
-  name: string
-  prompt: string
-  kind: TaskKind
-  schedule: ScheduleSpec
-  model?: string
-  enabled: boolean
-  createdAt: number
-  nextRunAt: number
-  expiresAt?: number
-  runCount: number
-  lastRunAt?: number
-  lastStatus?: TaskStatus
-  lastError?: string
-  history: ExecutionRecord[]
-}
+// ack 覆写 config 类型同源自 pi（文件尾 SchedulerCurrentModel / SchedulerProviderOverride 消费）
+import type { ProviderConfig } from '@earendil-works/pi-coding-agent'
 
-/**
- * pi.appendEntry(TASK_ENTRY_TYPE, SchedulerEntryOp) 写入 session JSONL 的 op 联合类型。
- *
- * advance.status 固定为 'success'（CL8）：对齐现有 TaskStatus='success'|'failed'，
- * 而非继承的 DM-SCHEDULER-OP 词表 'ok'。唯一 emit 值——按 CL7，advance 仅在 dispatch
- * 成功（nextRunAt 实际推进）时 append，失败 dispatch 不 append（transient 失败重试语义）。
- * fold 的 `task.lastStatus = entry.status` 直接赋值合法（'success' 属 TaskStatus）。
- */
-export type SchedulerEntryOp =
-  | { op: 'upsert'; taskId: string; ownerSessionFile: string; task: TaskSnapshot }
-  | { op: 'advance'; taskId: string; nextRunAt: number; at: number; status: 'success' }
-  | { op: 'toggle'; taskId: string; enabled: boolean; nextRunAt?: number }
-  | { op: 'delete'; taskId: string }
+export {
+  appendExecutionRecord,
+  HISTORY_LIMIT,
+  snapshotToTask,
+  TASK_ENTRY_TYPE,
+} from '@zhushanwen/extension-protocol'
+export type {
+  ExecutionRecord,
+  ScheduleSpec,
+  ScheduledTask,
+  SchedulerEntryOp,
+  TaskKind,
+  TaskSnapshot,
+  TaskStatus,
+} from '@zhushanwen/extension-protocol'
+
+// 本地保留面（写侧 helper / 旧 store 形状 / 工具参数）签名引用的类型——re-export 不引入作用域，需显式 import
+import type { ScheduledTask, TaskKind, TaskSnapshot } from '@zhushanwen/extension-protocol'
 
 /**
  * ScheduledTask → TaskSnapshot（ext-simplify-17 B2 canonical，解构剥离式）：剥离
@@ -114,31 +39,6 @@ export function toTaskSnapshot(task: ScheduledTask): TaskSnapshot {
   return { ...rest, history: history.slice() }
 }
 
-/**
- * TaskSnapshot → ScheduledTask（replay 侧重建）：pending 不持久化故不恢复，
- * ownerSessionFile 由调用方（replay applyUpsert）从 op 顶层补回。history 逐项深拷贝——
- * 避免恢复出的运行时 task 与快照共享数组/元素引用（task 后续被 mutate 时不污染快照）。
- */
-export function snapshotToTask(snapshot: TaskSnapshot): ScheduledTask {
-  return {
-    id: snapshot.id,
-    name: snapshot.name,
-    prompt: snapshot.prompt,
-    kind: snapshot.kind,
-    schedule: snapshot.schedule,
-    model: snapshot.model,
-    enabled: snapshot.enabled,
-    createdAt: snapshot.createdAt,
-    nextRunAt: snapshot.nextRunAt,
-    expiresAt: snapshot.expiresAt,
-    runCount: snapshot.runCount,
-    lastRunAt: snapshot.lastRunAt,
-    lastStatus: snapshot.lastStatus,
-    lastError: snapshot.lastError,
-    history: snapshot.history.map(h => ({ ...h })),
-  }
-}
-
 // ── 持久化 ──
 
 export interface SchedulerStore {

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 已停）
-  })
-})