@zhushanwen/pi-scheduler 0.9.2 → 0.10.0

package/src/__tests__/active-path.test.ts

@@ -0,0 +1,253 @@
+/**
+ * U6c：backend.loadTasks 折叠接活跃路径裁剪 + session_tree handler 重折叠。
+ *
+ * 从 leafId 沿 parentId 回溯得活跃路径，被撤子树的任务 op entry 不再恢复 pending
+ * 定时任务——到点不触发真实 turn（A14 可观察验收锚）。
+ */
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
+import { describe, expect, it, vi } from 'vitest'
+
+import { PiSchedulerBackend, type SchedulerBackendCtx } from '../backend.js'
+import { SchedulerRuntime, TICK_INTERVAL_MS } from '../runtime.js'
+import { TASK_ENTRY_TYPE } from '../types.js'
+import type { ScheduledTask, SchedulerEntryOp, TaskSnapshot } from '../types.js'
+
+const SESSION_FILE = '/test/session.json'
+
+// ── fixture ─────────────────────────────────────────
+
+interface BranchEntry {
+  id: string
+  parentId: string | null
+  type: string
+  customType?: string
+  data?: unknown
+}
+
+/** 构造 base task 快照（upsert op 用，字段集对齐 replay.test.ts 惯例） */
+function snapshot(overrides: Partial<TaskSnapshot> = {}): TaskSnapshot {
+  return {
+    id: 't1',
+    name: 'test',
+    prompt: 't1 prompt',
+    kind: 'recurring',
+    schedule: { mode: 'interval', intervalMs: 60000 },
+    enabled: true,
+    createdAt: 0,
+    nextRunAt: 100,
+    runCount: 0,
+    history: [],
+    ...overrides,
+  }
+}
+
+function upsertOp(taskId: string, overrides: Partial<TaskSnapshot> = {}): SchedulerEntryOp {
+  return {
+    op: 'upsert',
+    taskId,
+    ownerSessionFile: SESSION_FILE,
+    task: snapshot({ id: taskId, prompt: `${taskId} prompt`, ...overrides }),
+  }
+}
+
+function taskOpEntry(id: string, parentId: string | null, op: SchedulerEntryOp): BranchEntry {
+  return { type: 'custom', id, parentId, customType: TASK_ENTRY_TYPE, data: op }
+}
+
+/** 撤回后真实形态：label entry 落文件尾（parentId = 回退后叶子），leafId 指向它 */
+function labelEntry(id: string, parentId: string | null): BranchEntry {
+  return { type: 'label', id, parentId, targetId: 'u-x', label: 'taiji:revoked' }
+}
+
+/** 可变树状态的 ctx（模拟撤回前后 swap：entries + leafId 经闭包读取） */
+function makeCtx(initialEntries: BranchEntry[], initialLeafId: string | null) {
+  let entries = initialEntries
+  let leafId = initialLeafId
+  const ctx: SchedulerBackendCtx = {
+    sessionManager: {
+      getEntries: () => entries.slice(),
+      getSessionFile: () => SESSION_FILE,
+      getLeafId: () => leafId,
+    },
+  }
+  return {
+    ctx,
+    setTree(nextEntries: BranchEntry[], nextLeafId: string | null): void {
+      entries = nextEntries
+      leafId = nextLeafId
+    },
+  }
+}
+
+/** 捕获 pi.on 注册的 handler + 副作用记录面（sendMessage / appendEntry vi.fn）。
+ * on 字段仅满足 ExtensionAPI 结构完整性：session_tree 注册面已迁至 factory 顶层
+ * （index.ts），backend 构造不再调 pi.on（注册面契约见 session-tree-registration.test.ts）。 */
+function makePi() {
+  const handlers = new Map<string, (...args: unknown[]) => unknown>()
+  const sendMessage = vi.fn(async () => {})
+  const appendEntry = vi.fn()
+  const registerProvider = vi.fn()
+  const unregisterProvider = vi.fn()
+  const pi = {
+    on: (event: string, handler: (...args: unknown[]) => unknown) => {
+      handlers.set(event, handler)
+    },
+    sendMessage,
+    appendEntry,
+    registerProvider,
+    unregisterProvider,
+  }
+  return { pi: pi as unknown as ExtensionAPI, handlers, sendMessage, appendEntry }
+}
+
+// ── loadTasks 活跃路径裁剪（U6c）─────────────────────
+
+describe('PiSchedulerBackend.loadTasks 活跃路径裁剪（U6c）', () => {
+  it('有分支 fixture：被撤子树的任务 op 不进重建态', () => {
+    // 树：e1(t1 upsert，active)；e1 → e3(t2 upsert，revoked-branch 物理后写)；
+    // 撤回落 label 锚 L（parentId = 回退后叶子 e1），leafId = L → 活跃路径 {L, e1}
+    const entries = [
+      taskOpEntry('e1', null, upsertOp('t1')),
+      taskOpEntry('e3', 'e1', upsertOp('t2')),
+      labelEntry('L', 'e1'),
+    ]
+    const { ctx } = makeCtx(entries, 'L')
+
+    const tasks = new PiSchedulerBackend(ctx, makePi().pi).loadTasks()
+
+    const ids = tasks.map(t => t.id)
+    expect(ids).toContain('t1')
+    // 反向断言：被撤子树任务不恢复 pending（无裁剪时会从 e3 折叠复活）
+    expect(ids).not.toContain('t2')
+  })
+
+  it('同任务跨分支：取活跃路径内最新 upsert（分支上被撤的后续推进不参与折叠）', () => {
+    const entries = [
+      taskOpEntry('e1', null, upsertOp('t1', { prompt: 'old prompt' })),
+      taskOpEntry('e2', 'e1', upsertOp('t1', { prompt: 'active-branch prompt' })),
+      taskOpEntry('e3', 'e1', upsertOp('t1', { prompt: 'revoked-branch prompt' })),
+      labelEntry('L', 'e2'),
+    ]
+    const { ctx } = makeCtx(entries, 'L')
+
+    const tasks = new PiSchedulerBackend(ctx, makePi().pi).loadTasks()
+
+    expect(tasks).toHaveLength(1)
+    expect(tasks[0]!.prompt).toBe('active-branch prompt')
+  })
+
+  it('无分支回归：leafId = 文件尾 → 线性折叠最新（现行为不变）', () => {
+    const entries = [
+      taskOpEntry('e1', null, upsertOp('t1', { prompt: 'v1' })),
+      taskOpEntry('e2', 'e1', upsertOp('t1', { prompt: 'v2' })),
+    ]
+    const { ctx } = makeCtx(entries, 'e2')
+
+    const tasks = new PiSchedulerBackend(ctx, makePi().pi).loadTasks()
+
+    expect(tasks).toHaveLength(1)
+    expect(tasks[0]!.prompt).toBe('v2')
+  })
+
+  it('legacy fixture 回归：entry 无 id/parentId（duck-typed 最小形状）→ 线性全量折叠，行为与裁剪前一致', () => {
+    const entries = [
+      { type: 'custom', customType: TASK_ENTRY_TYPE, data: upsertOp('t1') },
+      { type: 'custom', customType: TASK_ENTRY_TYPE, data: upsertOp('t2') },
+    ]
+    const ctx: SchedulerBackendCtx = {
+      sessionManager: {
+        getEntries: () => entries.slice(),
+        getSessionFile: () => SESSION_FILE,
+      },
+    }
+
+    const tasks = new PiSchedulerBackend(ctx, makePi().pi).loadTasks()
+
+    expect(tasks.map(t => t.id).sort()).toEqual(['t1', 't2'])
+  })
+
+  it('leafId 防御：null / 指向不存在 entry → 回退文件尾（撤回落 label 锚在尾，等价命中活跃路径）', () => {
+    const entries = [
+      taskOpEntry('e1', null, upsertOp('t1')),
+      taskOpEntry('e3', 'e1', upsertOp('t2')),
+      labelEntry('L', 'e1'),
+    ]
+
+    for (const leafId of [null, 'missing-id']) {
+      const { ctx } = makeCtx(entries, leafId)
+      const tasks = new PiSchedulerBackend(ctx, makePi().pi).loadTasks()
+      // 尾部锚 = label L（parentId=e1）→ 回溯 {L, e1}，被撤子树 t2 仍被裁掉
+      expect(tasks.map(t => t.id)).toEqual(['t1'])
+    }
+  })
+})
+
+// ── session_tree handler 重折叠 + 到点不触发（U6c / A14）──
+
+describe('session_tree 重折叠（U6c）', () => {
+  it('撤回后 session_tree → runtime 任务集重折叠（被撤任务移除）；handler 本身零 dispatch 零 append', () => {
+    // 撤回前：线性文件（leaf=尾=e2），t1/t2 均在
+    const preRevoke = [
+      taskOpEntry('e1', null, upsertOp('t1')),
+      taskOpEntry('e2', 'e1', upsertOp('t2')),
+    ]
+    const { ctx, setTree } = makeCtx(preRevoke, null)
+    const { pi, sendMessage, appendEntry } = makePi()
+
+    const backend = new PiSchedulerBackend(ctx, pi)
+    const runtime = new SchedulerRuntime(backend)
+    runtime.loadTasks(backend.loadTasks())
+    expect(runtime.getTask('t1')).toBeDefined()
+    expect(runtime.getTask('t2')).toBeDefined()
+
+    // 撤回：树回退（label 锚落尾 + leafId 指向它）→ session_tree 事件 → 重折叠
+    // （生产注册面在 factory 顶层 index.ts，此处直接驱动委托体）
+    setTree([...preRevoke, labelEntry('L', 'e1')], 'L')
+    backend.refoldSessionTree()
+
+    expect(runtime.getTask('t1')).toBeDefined()
+    expect(runtime.getTask('t2')).toBeUndefined()
+
+    // 纯重建断言：handler 自身不 dispatch、不 append op（不污染回退后的新分支）
+    expect(sendMessage).not.toHaveBeenCalled()
+    expect(appendEntry).not.toHaveBeenCalled()
+  })
+
+  it('到点不触发（A14）：重折叠后被撤子树任务 interval 到点无 turn；活跃路径任务照常 dispatch', async () => {
+    vi.useFakeTimers()
+    vi.setSystemTime(new Date('2026-01-01T00:00:00Z'))
+    try {
+      // 两任务同在撤回前文件上，nextRunAt = now + 1s（首个 30s tick 即到期）
+      const dueAt = Date.now() + 1000
+      const preRevoke = [
+        taskOpEntry('e1', null, upsertOp('t1', { nextRunAt: dueAt })),
+        taskOpEntry('e2', 'e1', upsertOp('t2', { nextRunAt: dueAt })),
+      ]
+      const { ctx, setTree } = makeCtx(preRevoke, null)
+      const { pi, sendMessage } = makePi()
+
+      const backend = new PiSchedulerBackend(ctx, pi)
+      const runtime = new SchedulerRuntime(backend)
+      runtime.loadTasks(backend.loadTasks())
+
+      // 撤回回退到 e1（t2 所在子树被移出活跃路径）
+      setTree([...preRevoke, labelEntry('L', 'e1')], 'L')
+      backend.refoldSessionTree()
+      expect(runtime.getTask('t2')).toBeUndefined()
+
+      // tick 常驻循环不动启停逻辑：重折叠后照常消费新任务集
+      runtime.startScheduler()
+      await vi.advanceTimersByTimeAsync(TICK_INTERVAL_MS)
+
+      const prompts = sendMessage.mock.calls.map(call => (call[0] as { content: string }).content)
+      expect(prompts).toContain('t1 prompt')
+      // A14 验收锚：被撤子树任务到点不触发真实 turn
+      expect(prompts).not.toContain('t2 prompt')
+      expect(sendMessage).toHaveBeenCalledTimes(1)
+    } finally {
+      // tick interval 在 fake timers 域内清理，防泄漏到后续用例
+      vi.clearAllTimers()
+      vi.useRealTimers()
+    }
+  })
+})

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

@@ -47,13 +47,15 @@ vi.mock('../widget.js', async (importOriginal) => {
 })
 
 // vi.mock factory 会被提升，跨模块共享状态必须经 vi.hoisted。
-const { isCtxStaleCaptures, runtimeInstances } = vi.hoisted(() => ({
+const { isCtxStaleCaptures, runtimeInstances, stopSchedulerCalls } = vi.hoisted(() => ({
   isCtxStaleCaptures: [] as Array<(() => boolean) | undefined>,
   runtimeInstances: [] as Array<{ stopScheduler(): void }>,
+  stopSchedulerCalls: [] as Array<{ stopScheduler(): void }>,
 }))
 
 // InstrumentedRuntime 继承真实实现（loadTasks/onAfterTick/startScheduler 均真实执行），
-// 仅捕获构造参（isCtxStale）并登记实例（afterEach 统一停 timer，避免真实 setInterval 残留）。
+// 仅捕获构造参（isCtxStale）并登记实例（afterEach 统一停 timer，避免真实 setInterval 残留）；
+// stopScheduler 调用按序记录（F1 验收断言面：新装配前旧实例必须被停）。
 vi.mock('../runtime.js', async (importOriginal) => {
   const actual = await importOriginal<typeof import('../runtime.js')>()
   const RealSchedulerRuntime = actual.SchedulerRuntime
@@ -66,17 +68,18 @@ vi.mock('../runtime.js', async (importOriginal) => {
       isCtxStaleCaptures.push(isCtxStale)
       runtimeInstances.push(this)
     }
+    override stopScheduler(): void {
+      stopSchedulerCalls.push(this)
+      super.stopScheduler()
+    }
   }
   return { ...actual, SchedulerRuntime: InstrumentedRuntime }
 })
 
 import schedulerExtension from '../index.js'
+import { TICK_INTERVAL_MS } from '../runtime.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：覆盖 factory 消费的 API 面
  * （on 捕获事件 handler 供手动触发；registerTool/registerCommand/sendMessage/appendEntry 兜底）。
@@ -207,12 +210,9 @@ describe('G1: index.ts 代际接线（S9）', () => {
 // 下一 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 跨窗口必多推一帧，即被捕获。
+// 行为断言口径（验收 U4）：观测面 = InstrumentedRuntime 的 stopScheduler 调用序列
+// （widget 推送是 D1 指纹跳推语义——任务集静态期间零推送，不能靠推送计数区分新旧 timer；
+// stopScheduler 白盒断言直接锁定「新装配前旧实例必须被停」的 F1 语义本身）。
 describe('F1: session_start 停旧 runtime（crash-fix U4）', () => {
   const BASE = Date.parse('2026-01-01T00:00:00Z')
 
@@ -244,7 +244,7 @@ describe('F1: session_start 停旧 runtime（crash-fix U4）', () => {
     }
   }
 
-  /** 同 createFakeCtx，但注入非空任务集（保活帧只在非空任务集时推送，见上方口径注释）。 */
+  /** 同 createFakeCtx，但注入非空任务集（首帧渲染需要非空任务集可断言）。 */
   function createFakeCtxWithTasks(sessionFile: string): ExtensionContext {
     return {
       cwd: '/test-index-session-start',
@@ -261,6 +261,7 @@ describe('F1: session_start 停旧 runtime（crash-fix U4）', () => {
   beforeEach(() => {
     isCtxStaleCaptures.length = 0
     runtimeInstances.length = 0
+    stopSchedulerCalls.length = 0
     setSchedulerWidgetMock.mockClear()
     vi.useFakeTimers()
     vi.setSystemTime(new Date(BASE))
@@ -273,7 +274,7 @@ describe('F1: session_start 停旧 runtime（crash-fix U4）', () => {
     vi.useRealTimers()
   })
 
-  it('U4: 双 session_start 后旧 timer 已停——跨保活窗口只有新 runtime 推帧', async () => {
+  it('U4: 双 session_start 后旧 timer 已停（stopScheduler 恰命中首个实例）', async () => {
     const { pi, events } = createMockPi()
     schedulerExtension(pi)
     const sessionStart = events.get('session_start')
@@ -282,19 +283,19 @@ describe('F1: session_start 停旧 runtime（crash-fix U4）', () => {
     // 第一次 session_start：runtime1 + timer1 启动，初始渲染 1 次
     sessionStart!({ type: 'session_start', reason: 'startup' }, createFakeCtxWithTasks('/test/session-1.json'))
     expect(setSchedulerWidgetMock).toHaveBeenCalledTimes(1)
+    expect(runtimeInstances).toHaveLength(1)
 
-    // 前置因果锚点：静置越过保活窗口，timer1 推一帧保活帧（排除「timer 从未启动」的假绿；
-    // 也锁定跳推行为——窗口内其余 tick 零推送）
-    await vi.advanceTimersByTimeAsync(KEEPALIVE_INTERVAL_MS + TICK_INTERVAL_MS)
-    expect(setSchedulerWidgetMock).toHaveBeenCalledTimes(2)
+    // 前置因果锚点：静置数个 tick——timer1 在 tick（无异常），任务集静态零推送（D1 跳推）
+    await vi.advanceTimersByTimeAsync(2 * TICK_INTERVAL_MS)
+    expect(setSchedulerWidgetMock).toHaveBeenCalledTimes(1)
 
     // 第二次 session_start（session 替换）：F1 在装配新 runtime 前停掉 timer1
     sessionStart!({ type: 'session_start', reason: 'new_session' }, createFakeCtxWithTasks('/test/session-2.json'))
-    expect(setSchedulerWidgetMock).toHaveBeenCalledTimes(3) // runtime2 初始渲染（实例态重置，首帧必推）
+    expect(setSchedulerWidgetMock).toHaveBeenCalledTimes(2) // runtime2 初始渲染（实例态重置，首帧必推）
+    expect(runtimeInstances).toHaveLength(2)
 
-    // 行为断言（验收口径）：再静置一个保活窗口，只有 runtime2 的 timer 触发推送——恰 +1；
-    // F1 缺失时 timer1/timer2 都活着，此处为 +2
-    await vi.advanceTimersByTimeAsync(KEEPALIVE_INTERVAL_MS + TICK_INTERVAL_MS)
-    expect(setSchedulerWidgetMock).toHaveBeenCalledTimes(4)
+    // 行为断言（验收口径）：stopScheduler 恰被调一次且命中 runtime1；
+    // F1 缺失时旧 timer 不被停（数组为空或不含 runtime1）
+    expect(stopSchedulerCalls).toEqual([runtimeInstances[0]])
   })
 })

package/src/__tests__/runtime.test.ts

@@ -11,7 +11,7 @@ vi.mock('@zhushanwen/pi-extension-logger', () => ({
 }))
 
 import { MockSchedulerBackend } from './mock-backend.js'
-import { SchedulerRuntime } from '../runtime.js'
+import { TICK_INTERVAL_MS, SchedulerRuntime } from '../runtime.js'
 
 // MockSchedulerBackend 零 FS 副作用：runtime 不再触碰 store，无需 mock store.js。
 
@@ -48,16 +48,8 @@ describe('SchedulerRuntime', () => {
   })
 
   describe('listTasks', () => {
-    it('returns tasks sorted by nextRunAt', async () => {
-      await runtime.addTask('task 1', { mode: 'interval', intervalMs: 60000 })
-      await runtime.addTask('task 2', { mode: 'interval', intervalMs: 30000 })
-      const tasks = runtime.listTasks()
-      expect(tasks).toHaveLength(2)
-      // 30s interval 的 nextRunAt 早于 60s 的，应排前
-      expect(tasks[0]!.nextRunAt).toBeLessThan(tasks[1]!.nextRunAt)
-    })
-
-    // 强化断言：30s 任务 nextRunAt 更小（更早），应是 listTasks()[0]
+    // 排序契约：30s 任务 nextRunAt 更小（更早），应是 listTasks()[0]
+    //（含排序断言全集：tasks[0].id 定位 + nextRunAt 严格小于）
     it('orders shorter-interval task first', async () => {
       const t60 = await runtime.addTask('60s', { mode: 'interval', intervalMs: 60000 })
       const t30 = await runtime.addTask('30s', { mode: 'interval', intervalMs: 30000 })
@@ -115,7 +107,9 @@ describe('SchedulerRuntime', () => {
       const task = await runtime.addTask('test', { mode: 'interval', intervalMs: 60000 })
       await runtime.dispatchTask(task)
       expect(backend.sentMessages).toHaveLength(1)
-      expect(backend.sentMessages[0]!.msg).toEqual(expect.objectContaining({ content: 'test' }))
+      expect(backend.sentMessages[0]!.msg).toEqual(expect.objectContaining({ content: 'test', customType: 'pi-scheduler:dispatched' }))
+      // steer 直投契约（runtime.ts sendMessage 第二参）：丢 opts = pi idle 时定时任务静默不开轮次
+      expect(backend.sentMessages[0]!.opts).toEqual({ deliverAs: 'steer', triggerTurn: true })
     })
 
     it('skips disabled task', async () => {
@@ -565,7 +559,6 @@ describe('SchedulerRuntime', () => {
   // 自停；其他错误 → warn "tick error" 继续调度。修复前 tick 内异常无人接住 →
   // unhandledRejection → pi 主进程 exit 1。
   describe('tick 错误分诊（F2）', () => {
-    const TICK_INTERVAL_MS = 30_000
 
     beforeEach(() => {
       vi.useFakeTimers()
@@ -639,7 +632,6 @@ describe('SchedulerRuntime', () => {
   //   clearExtensionCache 后 jiti 重 import 全新模块环境，旧闭包的模块级代数冻结不再递增，
   //   只剩文案能识别 stale；模块级方案的装配级验证见 index-generation.test.ts factory 重跑用例）
   describe('G1: 代际检测分诊（S9）', () => {
-    const TICK_INTERVAL_MS = 30_000
     let staleFlag: boolean
     let genRuntime: SchedulerRuntime
 

package/src/__tests__/session-tree-registration.test.ts

@@ -0,0 +1,152 @@
+// src/__tests__/session-tree-registration.test.ts
+//
+// U6c session_tree 注册面契约：注册在 extension factory 顶层（每代恰一 handler），
+// 同代 session_start 复发不累积。回归背景：注册曾在 PiSchedulerBackend 构造函数内，
+// 而 pi RPC 模式下每次 session 替换 session_start 在同一代内触发两次
+// （agent-session-runtime finishSessionReplacement 内部 rebindSession + RPC handler
+// 再 rebindSession，0.84.4 实装核对），pi 的 on 是追加语义（loader.js list.push，
+// 无去重无 off）——handler 随替换线性累积，残留旧代 backend 在旧 ctx 上重复执行。
+//
+// mock pi 的 on 必须是追加语义（list.push，对齐 pi 实装）：覆盖式 Map.set 会掩盖
+// 累积回归，正是本套件要防的形态。
+
+import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent'
+import { describe, expect, it, vi } from 'vitest'
+
+// MF-3（与 sdk-contract.test.ts 同款）：mock importer，session_start 装配零 FS 副作用。
+vi.mock('../importer.js', () => ({ importLegacyStore: vi.fn(() => vi.fn()) }))
+
+// mock 共享 logger（与 widget-push.test.ts 同款）：防测试触碰真实日志目录。
+const { loggerMock } = vi.hoisted(() => ({
+  loggerMock: { debug: vi.fn(), warn: vi.fn(), error: vi.fn() },
+}))
+vi.mock('@zhushanwen/pi-extension-logger', () => ({
+  getLogger: () => loggerMock,
+  createLogger: () => loggerMock,
+  setPiHandle: vi.fn(),
+}))
+
+import schedulerExtension from '../index.js'
+import { TASK_ENTRY_TYPE } from '../types.js'
+
+type Handler = (...args: unknown[]) => unknown
+
+/** 追加语义 mock pi：on = list.push（对齐 pi loader.js on 实装，无去重无 off）。 */
+function createAppendPi(): {
+  pi: ExtensionAPI
+  handlers: Map<string, Handler[]>
+  tools: { name: string; execute: (...args: unknown[]) => Promise<{ content: { text: string }[] }> }[]
+} {
+  const handlers = new Map<string, Handler[]>()
+  const tools: { name: string; execute: (...args: unknown[]) => Promise<{ content: { text: string }[] }> }[] = []
+  const pi = {
+    registerTool: (tool: { name: string; execute: (...args: unknown[]) => Promise<{ content: { text: string }[] }> }) =>
+      tools.push(tool),
+    registerCommand: vi.fn(),
+    on: (event: string, handler: Handler) => {
+      const list = handlers.get(event) ?? []
+      list.push(handler)
+      handlers.set(event, list)
+    },
+    sendMessage: vi.fn(),
+    appendEntry: vi.fn(),
+  } as unknown as ExtensionAPI
+  return { pi, handlers, tools }
+}
+
+/** 远期到期的启用任务 upsert entry（owner = sessionFile；测试窗内无 dispatch 噪音）。 */
+function taskEntry(sessionFile: string, taskId: string) {
+  return {
+    type: 'custom',
+    customType: TASK_ENTRY_TYPE,
+    data: {
+      op: 'upsert',
+      taskId,
+      ownerSessionFile: sessionFile,
+      task: {
+        id: taskId,
+        name: taskId,
+        prompt: `${taskId} prompt`,
+        kind: 'recurring',
+        schedule: { mode: 'interval', intervalMs: 3_600_000 },
+        enabled: true,
+        createdAt: 0,
+        nextRunAt: Date.now() + 3_600_000,
+        runCount: 0,
+        history: [],
+      },
+    },
+  }
+}
+
+/** fake ctx：entries 经容器可变（模拟撤回前后 swap）；ui.setWidget 观测面。 */
+function createFakeCtx(sessionFile: string, entriesBox: { entries: unknown[] }): ExtensionContext {
+  return {
+    cwd: '/test-tree-reg',
+    isIdle: () => true,
+    hasPendingMessages: () => false,
+    ui: { setWidget: vi.fn() },
+    sessionManager: {
+      getEntries: () => entriesBox.entries,
+      getSessionFile: () => sessionFile,
+    },
+  } as unknown as ExtensionContext
+}
+
+describe('session_tree 注册面（factory 顶层恰一，同代 session_start 复发不累积）', () => {
+  it('factory 运行恰注册 1 个 session_tree handler', () => {
+    const { pi, handlers } = createAppendPi()
+    schedulerExtension(pi)
+    expect(handlers.get('session_tree')).toHaveLength(1)
+  })
+
+  it('同代 session_start 复发（RPC 模式每次替换触发 2 次）→ session_tree handler 恒恰 1', () => {
+    const { pi, handlers } = createAppendPi()
+    schedulerExtension(pi)
+    const entriesBox = { entries: [] as unknown[] }
+    const ctx = createFakeCtx('/test/tree-reg.json', entriesBox)
+    const sessionStart = handlers.get('session_start')![0]!
+
+    sessionStart({ type: 'session_start', reason: 'new' }, ctx)
+    sessionStart({ type: 'session_start', reason: 'resume' }, ctx)
+
+    expect(handlers.get('session_tree')).toHaveLength(1)
+
+    // 收尾停当代 runtime 的 tick interval（fake timers 未启用，interval 需显式清）
+    void handlers.get('session_shutdown')![0]()
+  })
+
+  it('复发后 session_tree 委托当代 backend：撤回后重折叠反映到任务查询', () => {
+    const file = '/test/tree-reg-delegate.json'
+    const entriesBox = { entries: [taskEntry(file, 't1')] as unknown[] }
+    const { pi, handlers, tools } = createAppendPi()
+    schedulerExtension(pi)
+    const ctx = createFakeCtx(file, entriesBox)
+    const sessionStart = handlers.get('session_start')![0]!
+
+    // 同代复发两次：第 2 个 backend 为当代（旧代已被 stopScheduler + 代数判 stale）
+    sessionStart({ type: 'session_start', reason: 'new' }, ctx)
+    sessionStart({ type: 'session_start', reason: 'resume' }, ctx)
+
+    // 基线：t1 在当代任务集内
+    const control = tools.find(t => t.name === 'schedule_control')!
+
+    return control
+      .execute('call-base', { action: 'list' }, undefined, undefined, ctx)
+      .then(result => {
+        expect(result.content[0]!.text).toContain('t1')
+
+        // 撤回：entry 移出（getEntries 变化）→ session_tree 事件 → 当代 backend 重折叠
+        entriesBox.entries = []
+        handlers.get('session_tree')![0]!({ type: 'session_tree' }, ctx)
+
+        return control.execute('call-after', { action: 'list' }, undefined, undefined, ctx)
+      })
+      .then(result => {
+        expect(result.content[0]!.text).not.toContain('t1')
+      })
+      .finally(() => {
+        void handlers.get('session_shutdown')![0]()
+      })
+  })
+})