@zhushanwen/pi-scheduler 0.9.1 → 0.9.3

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,13 @@ vi.mock('../runtime.js', async (importOriginal) => {
 })
 
 import schedulerExtension from '../index.js'
-
-const TICK_INTERVAL_MS = 30_000
+import { TICK_INTERVAL_MS } from '../runtime.js'
+import { TASK_ENTRY_TYPE } from '../types.js'
+/** 与 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 +199,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

@@ -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 () => {
@@ -149,6 +143,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 +208,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 ──
@@ -515,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()
@@ -589,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]()
+      })
+  })
+})

package/src/__tests__/widget-push.test.ts

@@ -35,9 +35,8 @@ vi.mock('@zhushanwen/pi-extension-logger', () => ({
 }))
 
 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 同值（10min；常量不导出，测试锚定同值）。 */
 const KEEPALIVE_INTERVAL_MS = 10 * 60 * 1000
 const BASE = Date.parse('2026-01-01T00:00:00Z')

package/src/backend.ts

@@ -1,4 +1,5 @@
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
+import { filterActivePath } from '@zhushanwen/pi-session-path'
 
 import { replayFoldEntries, type SchedulerEntryLike } from './replay.js'
 import { TASK_ENTRY_TYPE } from './types.js'
@@ -70,6 +71,14 @@ export interface SchedulerBackend {
    * 不触发任何写入（项目规则 #6）。
    */
   getEntries(): SchedulerEntryLike[]
+  /**
+   * U6c：session_tree（树回退）重折叠订阅。生产注册面在 extension factory 顶层
+   * （index.ts：pi.on('session_tree') 每代恰一，事件经 activeBackend 委托
+   * PiSchedulerBackend.refoldSessionTree），事件到达时按活跃路径重折叠任务集并回调
+   * listener——落点是 SchedulerRuntime 的内存任务 Map（runtime 构造时订阅，backend
+   * 不能反向持有 runtime）。测试替身可不实现（构造侧 ?. 订阅为 no-op，既有单测路径不变）。
+   */
+  onSessionTree?(listener: (tasks: ScheduledTask[]) => void): void
 }
 
 /**
@@ -81,6 +90,14 @@ export interface SchedulerBackendCtx {
   sessionManager: {
     getEntries(): SchedulerEntryLike[]
     getSessionFile(): string | undefined
+    /**
+     * 当前叶子 entry id（U6c 活跃路径回溯锚）。可选：真实 ExtensionContext 恒存在
+     * （ReadonlySessionManager Pick 清单含 getLeafId）；最小 duck-typed ctx（单测）
+     * 缺失时按文件尾回退——session_start 时点与 pi 树重放规则（叶子 = 文件最后
+     * 一条 entry）等价，session_tree 时点由生产 ctx 携带精确锚。
+     * （pi 树重放规则实锚登记 pi-semantics PS-60：dist/core/session-manager.js:673 _buildIndex）
+     */
+    getLeafId?(): string | null
   }
   /**
    * 会话是否空闲（not streaming）。真实 ExtensionContext 保证存在（SDK
@@ -96,6 +113,14 @@ export interface SchedulerBackendCtx {
   model?: SchedulerCurrentModel
 }
 
+// ── 活跃路径裁剪（U6c）──
+
+// 活跃路径裁剪（leafId 沿 parentId 回溯，撤回后被撤子树的任务 op 不进折叠输入，
+// 被撤任务不得恢复 pending、到点触发真实 turn——A14）收敛于
+// @zhushanwen/pi-session-path 单一实现（四包同构副本收编，防御语义与回退口径见
+// 该包 filterActivePath 注释；runtime 侧 entry-tree-builder 保持独立——extension
+// 不能 import runtime 包）。
+
 // ── 生产实现 ──
 
 /**
@@ -111,22 +136,47 @@ export class PiSchedulerBackend implements SchedulerBackend {
     ExtensionAPI,
     'sendMessage' | 'appendEntry' | 'registerProvider' | 'unregisterProvider'
   >
+  private sessionTreeListener: ((tasks: ScheduledTask[]) => void) | null = null
 
   constructor(
     ctx: SchedulerBackendCtx,
-    pi: Pick<ExtensionAPI, 'sendMessage' | 'appendEntry' | 'registerProvider' | 'unregisterProvider'>,
+    pi: Pick<
+      ExtensionAPI,
+      'sendMessage' | 'appendEntry' | 'registerProvider' | 'unregisterProvider'
+    >,
   ) {
     this.ctx = ctx
     this.pi = pi
   }
 
+  /** U6c：SchedulerRuntime 构造时订阅重折叠回调（见 SchedulerBackend.onSessionTree）。 */
+  onSessionTree(listener: (tasks: ScheduledTask[]) => void): void {
+    this.sessionTreeListener = listener
+  }
+
+  /**
+   * U6c：session_tree（树回退）事件委托体，由 extension factory 顶层注册的 handler
+   * 经 activeBackend 调用（index.ts；不在本类构造函数注册，注册面理由见该处注释）。
+   * 纯重建体：只按活跃路径重折叠任务集（loadTasks）并回调 runtime 换 Map——不做
+   * 任何 sendMessage / appendEntry / tickTimer 启停（tick 常驻循环照常消费新任务集，
+   * 被撤子树任务不在集内即到点不触发，A14）。
+   */
+  refoldSessionTree(): void {
+    this.sessionTreeListener?.(this.loadTasks())
+  }
+
   /**
    * 读路径：折叠当前 session 的 TASK_ENTRY_TYPE custom entries 恢复任务（非接口成员，
-   * 由装配点 session_start 调用）。replayFoldEntries 内部含 fork owner 过滤与异常兜底。
+   * 由装配点 session_start / session_tree 重折叠调用）。replayFoldEntries 内部含 fork
+   * owner 过滤与异常兜底。U6c：折叠输入接活跃路径裁剪——从 leafId 沿 parentId 回溯，
+   * 被撤子树的任务 op 不再恢复 pending（否则被撤任务到点照常触发真实 turn，A14）。
    */
   loadTasks(): ScheduledTask[] {
     return [
-      ...replayFoldEntries(this.ctx.sessionManager.getEntries(), this.ctx.sessionManager.getSessionFile()).values(),
+      ...replayFoldEntries(
+        filterActivePath(this.ctx.sessionManager),
+        this.ctx.sessionManager.getSessionFile(),
+      ).values(),
     ]
   }
 

package/src/index.ts

@@ -1,4 +1,4 @@
-import type { ExtensionAPI, ExtensionContext, TurnEndEvent } from '@earendil-works/pi-coding-agent'
+import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent'
 import type { GuiContext } from '@zhushanwen/extension-protocol'
 import { toErrorMessage } from '@zhushanwen/pi-ext-guards'
 import { getLogger } from '@zhushanwen/pi-extension-logger'
@@ -70,6 +70,9 @@ const WIDGET_KEEPALIVE_INTERVAL_MS = WIDGET_KEEPALIVE_MINUTES * MS_PER_MINUTE
  */
 export default function schedulerExtension(pi: ExtensionAPI): void {
   let service: SchedulerService | null = null
+  // U6c：当代 backend（session_start 装配点更新）。factory 顶层 session_tree handler
+  // 经它委托当代重折叠（注册面理由见下方 session_tree 注册点注释）。
+  let activeBackend: PiSchedulerBackend | null = null
   // IMPORT-FLUSH-GUARD（MF-1）：importLegacyStore 对未 flush 的新 session 返回延迟删除 .imported
   // 的 cleanup——turn_end / session_shutdown 时执行：确认 flush（sessionFile 已出现）则删，
   // 未 flush 保留供崩溃恢复重导入（否则未 flush 即退出 → 全部旧任务丢失且源文件已销毁）。
@@ -105,6 +108,9 @@ export default function schedulerExtension(pi: ExtensionAPI): void {
     service?.runtime.stopScheduler()
     // 装配点：backend（ctx.sessionManager 读 entries / pi.appendEntry 写 op）→ runtime（内存态 + 调度）→ service（业务入口）
     const backend = new PiSchedulerBackend(ctx, pi)
+    // U6c：同步给 factory 顶层 session_tree handler（下方注册）——同代 session_start
+    // 复发时本赋值覆盖为最新 backend，委托恒指当代 ctx 的实例。
+    activeBackend = backend
     // 旧 store 原子导入（CL3 方案A）：必须在 backend.loadTasks() 之前执行——
     // append 的 upsert entry 进入 pi 内存 fileEntries，紧接的 loadTasks replay 统一重放读到导入任务。
     // ctx.cwd 类型为 string（SDK ExtensionContext 必填），无需 ?? process.cwd() 兜底（CL2）。
@@ -186,37 +192,48 @@ export default function schedulerExtension(pi: ExtensionAPI): void {
     refreshWidget(ctx)
   })
 
+  // U6c：树回退（撤回 __taiji_nav__ → navigateTree / 用户树跳转）后重折叠任务集。
+  // 注册在 factory 顶层而非 PiSchedulerBackend 构造函数：pi 的 on 是追加语义（loader.js
+  // on 实现 list.push，无去重无 off，0.84.4 实装核对），且 RPC 模式下每次 session 替换
+  // session_start 在同一代内触发两次（agent-session-runtime finishSessionReplacement
+  // 内部 rebindSession 一路 + RPC handler 再 rebindSession 一路，均经 bindExtensions
+  // emit session_start）——构造函数注册会同代线性累积 handler（残留旧代 backend 在旧
+  // ctx 上重复执行幂等 loadTasks，handler 数随替换无界缓增）。factory 每代恰好运行一次
+  // （loader.js initializeExtension 每代新建 handlers Map 并重跑 factory），顶层注册
+  // 结构性保证每代恰一 handler；委托 activeBackend（session_start 装配点更新）保证折叠
+  // 输入恒为当代实例，事件早于首个 session_start 时 no-op。
+  // 纯重建体（goal/plan/todo 的 session_tree handler 同款）：只按活跃路径重折叠任务集
+  // 并回调 runtime 换 Map——不做任何 sendMessage / appendEntry / tickTimer 启停（tick
+  // 常驻循环照常消费新任务集，被撤子树任务不在集内即到点不触发，A14）。
+  pi.on('session_tree', (_event: unknown, _ctx: ExtensionContext) => {
+    activeBackend?.refoldSessionTree()
+  })
+
   // turn_end 单注册共用（U4 恢复挂点与 MF-1 cleanup 同事件）：真实 pi 的 on 是 handler 列表
   // 追加，但测试仿真 mock 为覆盖式单 handler，且同事件单注册与「listener 防重复注册」纪律一致。
-  pi.on('turn_end', (event?: TurnEndEvent) => {
+  // （U4 模型恢复不在本事件：D1 归属简化后恢复唯一事件通道 = agent_settled，见 runtime.handleRunSettled）
+  pi.on('turn_end', () => {
     // IMPORT-FLUSH-GUARD（MF-1）：延迟删除的主触发点——turn_end 前该轮所有 message_end 已持久化
     // （agent-session.js _handleAgentEvent 在 message_end 处理中调 appendMessage 触发 flush），
     // sessionFile 已出现 → cleanup 删 .imported；仍未 flush（无 assistant 消息的轮次）→ 静默保留，
     // 下次 turn_end / session_shutdown 重试。cleanup 幂等（importer.ts importFromFile）。
     importCleanup?.()
-    // U4 dispatch 模型切换恢复挂点（设计 D3 修订版）：状态机、恢复动作与 stale 代际守卫都在
-    // SchedulerRuntime。`event?.` 容错：pi 契约 payload 恒在，测试仿真可无参调用，缺省不匹配不动作。
-    service?.runtime.handleTurnEnd(event?.turnIndex)
     // ack 安全网注销（幂等）：正常路径已在 streamSimple 调用点自撤，这里覆盖「覆写未被调用」
     // 的轮次（E2）。
     ackController?.handleTurnEnd()
   })
 
-  // U4 dispatch 模型切换：归属状态机其余事件监听（P-MODEL-③④ 实测序态）。handler 只转发
-  // 事件数据；agent_settled = run 完全沉降（无 retry/compaction/queued continuation）后的
-  // 窗口封口 + awaiting-restore 模型恢复的即时兑现（区别于 agent_end 的纯封口）。
-  pi.on('agent_start', () => service?.runtime.handleAgentStart())
-  pi.on('turn_start', (event) => service?.runtime.handleTurnStart(event?.turnIndex))
+  // message_start 仅剩 ack 触发器判别（u-ack-turn）：只有我们注入的 custom 消息（前缀
+  // pi-scheduler-ack:）才同步武装覆写；外来/assistant 消息一律忽略。（U4 dispatch 归属匹配
+  // 已随 D1 归属简化删除）
   pi.on('message_start', (event) => {
-    service?.runtime.handleMessageStart(event?.message)
-    // ack 触发器判别（u-ack-turn）：只有我们注入的 custom 消息（前缀 pi-scheduler-ack:）
-    // 才同步武装覆写；外来/assistant 消息一律忽略。
     ackController?.handleMessageStart(event?.message)
   })
-  pi.on('agent_end', () => service?.runtime.handleRunClosed())
-  // agent_settled 除封口外兼作 awaiting-restore 模型恢复的即时兑现挂点（不与 agent_end
-  // 共用：end 后仍可能有自动续跑 turn，此时切回会把续跑 turn 的模型换掉，见
-  // runtime.handleRunSettled 注释）
+
+  // U4 dispatch 模型切换恢复的唯一事件挂点：agent_settled = run 完全沉降（无 retry/
+  // compaction/queued continuation）后的 isIdle 复核兑现（D1 归属简化——不挂 agent_start/
+  // turn_start/message_start/turn_end/agent_end，runtime 无 turnIndex 归属状态机；end 后仍
+  // 可能有自动续跑 turn，恢复只认 settled，见 runtime.handleRunSettled 注释）。
   pi.on('agent_settled', () => service?.runtime.handleRunSettled())
 
   pi.on('session_shutdown', async () => {