@zhushanwen/pi-scheduler 0.10.4 → 0.11.1

package/README.md

@@ -208,7 +208,7 @@ pi -p "/schedule 5m 'check build'"
 | 默认过期 | **7 天**（`DEFAULT_EXPIRY_MS`） | recurring 任务缺省 `expires` 时；`expires: 'never'` 关闭 |
 | once 任务 | 触发后自动删除 | 不参与后续调度 |
 | cron 失效 | 任务停用 + `lastStatus=failed` + `lastError='cron expression invalid'` | 不会用 `now()` 兜底导致每 tick 重触发死循环 |
-| 忙时 dispatch | steer 直投（scheduler-steer-direct-dispatch） | busy 时消息插入当前 turn、idle 时开新 turn（`{deliverAs:'steer', triggerTurn:true}`），受理即记账不排队；同任务 in-flight 守卫防双投 |
+| 忙时 dispatch | steer 直投（scheduler-steer-direct-dispatch） | busy 时消息插入当前 turn、idle 时开新 turn（`{deliverAs:'steer', triggerTurn:true}`），受理即记账不排队；同任务 in-flight 检查防双投 |
 | history | 保留最近 **20** 条执行记录 | 超出丢弃最旧；重放折叠时同样裁剪 |
 | 持久化 | custom entry append 到 session JSONL（dispatch 成功后立即 append advance 记录执行） | 任务随 owner session 持久化，resume 后重放恢复，无需额外写盘 |
 | 交付语义 | **at-least-once**（至少一次） | dispatch 成功后内存更新 nextRunAt 并 append advance；append 之前若进程崩溃可能重复注入一次（无精确一次保证，可接受） |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-scheduler",
-  "version": "0.10.4",
+  "version": "0.11.1",
   "type": "module",
   "main": "index.ts",
   "taiji": {
@@ -51,10 +51,10 @@
   },
   "dependencies": {
     "croner": "^9.0.0",
-    "@zhushanwen/extension-protocol": "0.21.0",
+    "@zhushanwen/extension-protocol": "0.23.0",
     "@zhushanwen/pi-ext-guards": "0.5.0",
     "@zhushanwen/pi-extension-logger": "0.6.2",
-    "@zhushanwen/pi-llm-shared": "0.11.3",
+    "@zhushanwen/pi-llm-shared": "0.12.0",
     "@zhushanwen/pi-session-path": "0.1.0"
   },
   "scripts": {

package/skills/scheduler-ext-config/SKILL.md

@@ -35,7 +35,7 @@ description: "使用或排查 @zhushanwen/pi-scheduler（定时任务调度）
 - **`schedule_control`**（管理）：`action` = `list`/`toggle`/`delete`/`run`，`id`（toggle/delete/run 必填），`enabled`（toggle 必填）。
 - 两个工具的返回都是结构化 `{content: [{type:'text', text}], details}`；业务失败以异常抛出（pi 只对 execute throw 置 `isError:true`，错误 message 作为 toolResult content 返回），不通过返回值表达失败。
 
-> 创建/管理操作不受 agent 运行状态约束；**到期 dispatch** 也不等待 agent idle（steer 直投，busy 时插入当前 turn），仅受速率限制/同任务 in-flight 守卫约束（见「运行限制与 dispatch 行为」）。
+> 创建/管理操作不受 agent 运行状态约束；**到期 dispatch** 也不等待 agent idle（steer 直投，busy 时插入当前 turn），仅受速率限制/同任务 in-flight 检查约束（见「运行限制与 dispatch 行为」）。
 
 ### 3. 创建方式（触发反转）
 
@@ -127,7 +127,7 @@ dispatch 行为（`dispatchTask`，scheduler-steer-direct-dispatch 直投模型
 
 - **steer 直投**：到期任务 `backend.sendMessage(..., {deliverAs: 'steer', triggerTurn: true})` 直接投递——agent busy 时消息插入当前 turn（立即被模型看到）、idle 时开新 turn。不排队、不等 idle、不丢弃。
 - **受理即记账**：`sendMessage` 是 fire-and-forget（返回 void），await 立即通过，`nextRunAt` 调用即推进——无「入队未终态」窗口。
-- **同任务 in-flight 守卫**：该任务 dispatch 在途（如 `/schedule run` 与 tick dispatch 并发）时本 tick 跳过，防双投。
+- **同任务 in-flight 检查**：该任务 dispatch 在途（如 `/schedule run` 与 tick dispatch 并发）时本 tick 跳过，防双投。
 - **模型切换**（`task.model` 设定且 ≠ 会话当前模型）：sendMessage 前 `setModel` 切到目标任务模型、记未决切换记录，事件恢复（turn_end + isIdle 复核）后切回原模型；切换失败降级——照常 dispatch（模型字段不阻塞核心调度）。
 - dispatch 成功后：recurring 推进 `nextRunAt` 并 append `advance`；once 删除任务并 append `delete`；失败（`sendMessage` 同步抛错，如 session 关闭）记 `lastStatus='failed'` 不 rethrow，下个 tick 重试（transient 失败重试语义，不 append advance）。
 - 注入的消息：`{content: task.prompt, customType: 'pi-scheduler:dispatched', display: true}`，投递选项 `{deliverAs: 'steer', triggerTurn: true}`。

package/src/__tests__/U4-MODEL-SWITCH.test.ts

@@ -14,7 +14,7 @@
  *   任务的 setModel 排队等前序模型 op 完成（任意两个 setModel 不并发、双记录不叠写）
  * - tick 事实查询兜正确性（原 2-tick 计数对账已按 ADR-0122 删除）：严格先于同 tick
  *   dispatch 循环；记录存在 + idle 即恢复（agent_settled 丢失时由查询收敛——拉保证
- *   正确、事件只优化延迟）；未决记录守卫（无记录时模型漂移 = 用户自主行为不动作）
+ *   正确、事件只优化延迟）；未决记录检查（无记录时模型漂移 = 用户自主行为不动作）
  * - 降级与接管副作用：setModel false 不阻塞 dispatch；sendMessage 抛错 catch 先恢复；
  *   模型语义异常只走日志（不进持久化词表）
  *
@@ -40,7 +40,7 @@ const ORIG = 'prov-a/model-1'
 const TASK_M = 'prov-b/model-2'
 const OTHER_M = 'prov-c/model-3'
 
-/** 模型控制面 mock：setModelCalls 记录调用序（切换/恢复时序断言的核心观测点） */
+/** 模型控制接口 mock：setModelCalls 记录调用序（切换/恢复时序断言的核心观测点） */
 class ModelOpsMock implements SchedulerModelOps {
   currentRef: string | undefined = ORIG
   idle = true

package/src/__tests__/ack-contract.test.ts

@@ -1,7 +1,7 @@
-// ack 契约面测试（dev-flow u-foundation 单元）。
+// ack 契约范围测试（dev-flow u-foundation 单元）。
 //
-// 本单元只交付「依赖反转契约面」，不含 ack 业务逻辑，故测试只证明三件事：
-//   1. SchedulerBackend 扩面（registerProvider/unregisterProvider/getEntries）后可被纯对象
+// 本单元只交付「依赖反转契约范围」，不含 ack 业务逻辑，故测试只证明三件事：
+//   1. SchedulerBackend 接口扩大（registerProvider/unregisterProvider/getEntries）后可被纯对象
 //      夹具实现（isIdle/getCurrentModel 是 PiSchedulerBackend 类方法、非接口成员）；
 //   2. PiSchedulerBackend 对 pi / ctx 的转发语义（含缺字段兜底）；
 //   3. ack 契约常量/判别值锚定（防后续单元依赖字符串时不发现改动）。
@@ -24,14 +24,14 @@ import {
   type SchedulerProviderOverride,
 } from '../types.js'
 
-// ── 1. 扩面可被纯对象夹具实现（类型闭合）──
+// ── 1. 接口扩大可被纯对象夹具实现（类型完备）──
 
 /**
  * 纯对象夹具：只实现接口成员（sendMessage/appendEntry/getSessionFile/now +
  * registerProvider/unregisterProvider/getEntries）。
  * `satisfies SchedulerBackend` 的**编译期**效力以「测试被 typecheck」为前提——
  * `extensions/tsconfig.json` 的 exclude 覆盖全部测试目录，常态 `extensions:typecheck`
- * 不覆盖本文件（若将来把测试纳入 typecheck，这行才是编译期契约闭合证据）；当前至少保证
+ * 不覆盖本文件（若将来把测试纳入 typecheck，这行才是编译期契约完备证据）；当前至少保证
  * 运行期结构契约。
  */
 function createFixtureBackend(): SchedulerBackend {
@@ -65,8 +65,8 @@ function createFixtureBackend(): SchedulerBackend {
   } satisfies SchedulerBackend
 }
 
-describe('SchedulerBackend ack 扩面（纯对象夹具）', () => {
-  it('夹具实现既有 + 新增全部方法且类型闭合', () => {
+describe('SchedulerBackend ack 接口扩大（纯对象夹具）', () => {
+  it('夹具实现既有 + 新增全部方法且类型完备', () => {
     const backend = createFixtureBackend()
 
     expect(backend.getEntries()).toHaveLength(1)
@@ -83,7 +83,7 @@ describe('SchedulerBackend ack 扩面（纯对象夹具）', () => {
 
 // ── 2. PiSchedulerBackend 转发 / 归一 / 兜底 ──
 
-/** 最小假 pi 的记录面。 */
+/** 最小假 pi 的记录侧。 */
 interface FakePi {
   pi: Pick<
     ExtensionAPI,
@@ -118,7 +118,7 @@ function createFakePi(): FakePi {
   }
 }
 
-describe('PiSchedulerBackend ack 扩面转发', () => {
+describe('PiSchedulerBackend ack 接口扩大转发', () => {
   it('registerProvider 转发 pi 并零转换透传 (providerId, config)', () => {
     const { pi, providerCalls } = createFakePi()
     const ctx: SchedulerBackendCtx = {
@@ -230,7 +230,7 @@ describe('ack 契约常量与类型', () => {
     expect<AckAvailability>({ available: true }).toEqual({ available: true })
 
     // 可通知形态只有两种：其余 E 形态（e1/e2/e4/e5/e6/e8b）不发用户通知——真实轮已
-    // 应答或与落盘无关，提示即反向撒谎（设计 §3.4）；它们在日志面用字符串标签。
+    // 应答或与落盘无关，提示即反向撒谎（设计 §3.4）；它们在日志侧用字符串标签。
     const notifyReasons: AckNotifyReason[] = ['e3-no-turn', 'e8-no-base']
     expect(notifyReasons).toHaveLength(2)
 

package/src/__tests__/ack-provider.test.ts

@@ -1,6 +1,6 @@
 // ack 合成流 + 可用性判据测试（dev-flow u-ack-provider 单元）。
 //
-// 本单元只交付三件事的纯函数面：
+// 本单元只交付三件事的纯函数部分：
 //   1. buildAckStreamSimple —— 零 token 合成流（字段 = 会话真实模型 / usage 全 0 /
 //      aborted 走 error 终止 / onCalled 返回前同步自撤）；
 //   2. computeAckAvailability —— 预计算 + fail-closed 的可用性判据（内置含 radius）；

package/src/__tests__/ack-turn.test.ts

@@ -322,11 +322,11 @@ it('session 边界：未启动 ack 轮且文件不存在 ⇒ 补发通知；ack
   expect(b.notifyCalls).toHaveLength(0)
 })
 
-it('E3 后同会话再次创建可重试（无定时器清 pending，守卫只认 window）', async () => {
+it('E3 后同会话再次创建可重试（无定时器清 pending，检查只认 window）', async () => {
   const h = makeHarness({ builtinIds: new Set(['anthropic']) })
   await startAck(h.controller)
   expect(h.captured.sent).toHaveLength(1)
-  // 触发器未启动轮次 ⇒ window 从未置位 ⇒ 守卫不挡，下一次创建重新注入。
+  // 触发器未启动轮次 ⇒ window 从未置位 ⇒ 检查不挡，下一次创建重新注入。
   await h.controller.maybeStartAck({
     task: { ...TASK, id: 't2' },
     model: MODEL,
@@ -399,9 +399,9 @@ it('E3 后同会话再次创建可重试（无定时器清 pending，守卫只
   })
 })
 
-// ── 回归用例（一致性审查 F2/F3 + 去定时器后的守卫语义）──
+// ── 回归用例（一致性审查 F2/F3 + 去定时器后的检查语义）──
 
-describe('ack-turn 守卫与归因回归', () => {
+describe('ack-turn 检查与归因回归', () => {
   beforeEach(() => {
     vi.useFakeTimers()
     resetAckState()

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

@@ -79,9 +79,9 @@ function makeCtx(initialEntries: BranchEntry[], initialLeafId: string | null) {
   }
 }
 
-/** 捕获 pi.on 注册的 handler + 副作用记录面（sendMessage / appendEntry vi.fn）。
- * on 字段仅满足 ExtensionAPI 结构完整性：session_tree 注册面已迁至 factory 顶层
- * （index.ts），backend 构造不再调 pi.on（注册面契约见 session-tree-registration.test.ts）。 */
+/** 捕获 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 () => {})
@@ -201,7 +201,7 @@ describe('session_tree 重折叠（U6c）', () => {
     expect(runtime.getTask('t2')).toBeDefined()
 
     // 撤回：树回退（label 锚落尾 + leafId 指向它）→ session_tree 事件 → 重折叠
-    // （生产注册面在 factory 顶层 index.ts，此处直接驱动委托体）
+    // （生产注册点在 factory 顶层 index.ts，此处直接驱动委托体）
     setTree([...preRevoke, labelEntry('L', 'e1')], 'L')
     backend.refoldSessionTree()
 

package/src/__tests__/create-form-component.test.ts

@@ -394,7 +394,7 @@ describe('ScheduleCreateComponent — Submit 确认门与回传', () => {
 		})
 	})
 
-	it('S-5: 终态后继续按键 no-op（resolved 守卫）', () => {
+	it('S-5: 终态后继续按键 no-op（resolved 检查）', () => {
 		const { c, result } = make()
 		fillRecurringToSubmit(c)
 		c.handleInput(ENTER)

package/src/__tests__/importer.test.ts

@@ -243,7 +243,7 @@ describe('importLegacyStore', () => {
     expect(fs.unlinkSync).not.toHaveBeenCalled()
   })
 
-  // ── TC8b：cleanup 幂等 + unlink ENOENT 守卫（MF-2，R2 修复）──
+  // ── TC8b：cleanup 幂等 + unlink ENOENT 检查（MF-2，R2 修复）──
   it('TC8b: cleanup 幂等（已删后 no-op）+ unlink 仅静默 ENOENT，其他 fs 错误向上抛', () => {
     const taskA = makeTask({ id: 'ffff' })
     vi.mocked(fs.readFileSync).mockReturnValue(

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

@@ -39,7 +39,7 @@ vi.mock('@zhushanwen/pi-extension-logger', () => ({
 vi.mock('../importer.js', () => ({ importLegacyStore: vi.fn(() => vi.fn()) }))
 
 // u-p2b 接线断言：index.ts 的 refreshWidget 必须走结构化/双模入口 `setSchedulerWidget`
-// （取代旧 `renderSchedulerWidget` TUI 单形态）——mock 捕获调用面（任务数组直传）。
+// （取代旧 `renderSchedulerWidget` TUI 单形态）——mock 捕获调用（任务数组直传）。
 const { setSchedulerWidgetMock } = vi.hoisted(() => ({ setSchedulerWidgetMock: vi.fn() }))
 vi.mock('../widget.js', async (importOriginal) => {
   const actual = await importOriginal<typeof import('../widget.js')>()
@@ -55,7 +55,7 @@ const { isCtxStaleCaptures, runtimeInstances, stopSchedulerCalls } = vi.hoisted(
 
 // InstrumentedRuntime 继承真实实现（loadTasks/onAfterTick/startScheduler 均真实执行），
 // 仅捕获构造参（isCtxStale）并登记实例（afterEach 统一停 timer，避免真实 setInterval 残留）；
-// stopScheduler 调用按序记录（F1 验收断言面：新装配前旧实例必须被停）。
+// stopScheduler 调用按序记录（F1 验收断言范围：新装配前旧实例必须被停）。
 vi.mock('../runtime.js', async (importOriginal) => {
   const actual = await importOriginal<typeof import('../runtime.js')>()
   const RealSchedulerRuntime = actual.SchedulerRuntime
@@ -210,7 +210,7 @@ describe('G1: index.ts 代际接线（S9）', () => {
 // 下一 tick 的 refreshWidget 访问 stale ctx.ui 抛错 → unhandledRejection → pi 主进程 exit 1。
 // F1 在 session_start 开头幂等 stopScheduler，从源头消灭。
 //
-// 行为断言口径（验收 U4）：观测面 = InstrumentedRuntime 的 stopScheduler 调用序列
+// 行为断言口径（验收 U4）：观测范围 = InstrumentedRuntime 的 stopScheduler 调用序列
 // （widget 推送是 D1 指纹跳推语义——任务集静态期间零推送，不能靠推送计数区分新旧 timer；
 // stopScheduler 白盒断言直接锁定「新装配前旧实例必须被停」的 F1 语义本身）。
 describe('F1: session_start 停旧 runtime（crash-fix U4）', () => {
@@ -294,7 +294,7 @@ describe('F1: session_start 停旧 runtime（crash-fix U4）', () => {
     expect(setSchedulerWidgetMock).toHaveBeenCalledTimes(2) // runtime2 初始渲染（实例态重置，首帧必推）
     expect(runtimeInstances).toHaveLength(2)
 
-    // 行为断言（验收口径）：stopScheduler 恰被调一次且命中 runtime1；
+    // 行为断言（验收标准）：stopScheduler 恰被调一次且命中 runtime1；
     // F1 缺失时旧 timer 不被停（数组为空或不含 runtime1）
     expect(stopSchedulerCalls).toEqual([runtimeInstances[0]])
   })

package/src/__tests__/mock-backend.ts

@@ -2,7 +2,7 @@ import type { SchedulerBackend, SchedulerProviderOverride } from '../backend.js'
 import { replayFoldEntries, type SchedulerEntryLike } from '../replay.js'
 import type { ScheduledTask, SchedulerEntryOp } from '../types.js'
 
-// 测试专用 mock（ext-simplify-08 L9：从 backend.ts 迁出——导出面即测试面的收敛，
+// 测试专用 mock（ext-simplify-08 L9：从 backend.ts 迁出——导出范围即测试范围的收敛，
 // 生产模块不再携带测试脚手架；MockSchedulerBackend/SentMessage 零生产引用）。
 
 export interface SentMessage {

package/src/__tests__/replay.test.ts

@@ -263,7 +263,7 @@ describe('replayFoldEntries', () => {
     expect(a.nextRunAt).toBe(100) // 保持 upsert 快照值
   })
 
-  // ── MF-2：守卫按变体校验必填字段——损坏 entry 只跳过该条，不清空全部任务 ──
+  // ── MF-2：检查按变体校验必填字段——损坏 entry 只跳过该条，不清空全部任务 ──
   it('MF-2: op 合法但缺必填字段的损坏 entry 被跳过，其余任务保留', () => {
     const session = '/s.json'
     loggerMock.warn.mockClear()

package/src/__tests__/runtime.test.ts

@@ -138,14 +138,14 @@ describe('SchedulerRuntime', () => {
     })
   })
 
-  // ── R3-S1：dispatchTask in-flight 守卫 ──
+  // ── R3-S1：dispatchTask in-flight 检查 ──
   // tick 为 fire-and-forget：tick1 的 await sendMessage 挂起超过 TICK_INTERVAL_MS（如 pi
   // 卡死）时，tick2 的 step2 再标 pending → step3 对同一 task 并发第二个 dispatch → 同一
-  // prompt 双注入。守卫：同任务在途（Set<taskId>）
+  // prompt 双注入。检查：同任务在途（Set<taskId>）
   // 时 skip 本轮并 warn；不同任务不受影响。
   // 末两条为调用方 API 层验收：不经 tick，直接并发/串行调 dispatchTask，
-  // 验证守卫在调用方入口同样拦截（warn + 第二次 false）与完成后放行。
-  describe('dispatchTask in-flight 守卫（R3-S1）', () => {
+  // 验证检查在调用方入口同样拦截（warn + 第二次 false）与完成后放行。
+  describe('dispatchTask in-flight 检查（R3-S1）', () => {
     beforeEach(() => {
       vi.useFakeTimers()
       vi.setSystemTime(new Date('2026-01-01T00:00:00Z'))
@@ -170,7 +170,7 @@ describe('SchedulerRuntime', () => {
       expect(task.pending).toBe(true) // dispatch 未完成，pending 未清
 
       // tick2（模拟 30s 后 pi 仍卡死）：同任务再标 pending → step3 dispatchTask 命中
-      // in-flight 守卫 → skip + warn（修复前：同一 prompt 双注入）
+      // in-flight 检查 → skip + warn（修复前：同一 prompt 双注入）
       await runtime.tickScheduler()
       expect(backend.sendMessage).toHaveBeenCalledTimes(1)
       const warnText = loggerMock.warn.mock.calls.map(c => String(c[0])).join('\n')
@@ -198,8 +198,8 @@ describe('SchedulerRuntime', () => {
       const tick1 = runtime.tickScheduler()
       expect(backend.sendMessage).toHaveBeenCalledTimes(1)
 
-      // tick2：task1 命中守卫跳过，task2 无在途 → 正常 dispatch（守卫按 taskId 粒度隔离）。
-      // 注：tick2 挂起在 task1 的 await dispatchTask（守卫命中即 resolved promise）与 task2
+      // tick2：task1 命中检查跳过，task2 无在途 → 正常 dispatch（检查按 taskId 粒度隔离）。
+      // 注：tick2 挂起在 task1 的 await dispatchTask（检查命中即 resolved promise）与 task2
       // 的 await sendMessage 上，先放行再 await，完成态统一断言
       const tick2 = runtime.tickScheduler()
       resolveSend!()
@@ -210,7 +210,7 @@ describe('SchedulerRuntime', () => {
     })
 
     // ── 调用方 API 层 ──
-    it('调用方守卫：同一 taskId 并发 dispatchTask → 第二次被拦截（send 只调 1 次 + warn）', async () => {
+    it('调用方检查：同一 taskId 并发 dispatchTask → 第二次被拦截（send 只调 1 次 + warn）', async () => {
       loggerMock.warn.mockClear()
       // 可控延迟的 sendMessage：让第一次 dispatch 挂起
       let resolveSend: (() => void) | undefined
@@ -239,7 +239,7 @@ describe('SchedulerRuntime', () => {
       await first
     })
 
-    it('调用方守卫：第一次完成后 → 第二次 dispatchTask 正常执行（send 调 2 次）', async () => {
+    it('调用方检查：第一次完成后 → 第二次 dispatchTask 正常执行（send 调 2 次）', async () => {
       const task = await runtime.addTask('serial-inflight', { mode: 'interval', intervalMs: 60_000 })
 
       // 第一次 dispatch（串行等待完成）

package/src/__tests__/sdk-contract.test.ts

@@ -5,9 +5,10 @@
 //   1. tool 注册名为 schedule / schedule_control
 //   2. tool 有 execute 函数字段（不是 handler/fn）
 //   3. execute 是 async function（SDK 期望返回 Promise）
-//   4. 错误路径 throw（W4：pi-agent-core 只对 execute throw 置 isError:true，
-//      返回值里的 isError 字段被 agent-loop 丢弃——错误轮曾被标成功；
-//      锚点 agent-loop.js:453-483/525-547）
+//   4. 错误路径 throw（W4：execute throw → pi-agent-core agent-loop catch 置 isError:true
+//      ——pi-agent-core dist/agent-loop.js executePreparedToolCall，1.0.0 实读 catch :581-588；
+//      1.0.0 起正常 return 的 isError 也被尊重——:579 isError: result.isError === true，
+//      0.84.4 才硬编码 false、return 的错误轮曾被标成功——本包失败恒走 throw，行为不变）
 //
 // 不导入 SchedulerRuntime 的内部：只通过 index.ts 的 default export 测，
 // 保证 tool 注册逻辑的入口契约。
@@ -203,7 +204,7 @@ describe('pi-scheduler SDK contract', () => {
     const cleanup = vi.mocked(importLegacyStore).mock.results[0]!.value
     expect(typeof cleanup).toBe('function')
 
-    // turn_end（首个 turn 完成，flush 已发生）→ cleanup 被调用——跨 session 双导入窗口闭合点
+    // turn_end（首个 turn 完成，flush 已发生）→ cleanup 被调用——跨 session 双导入窗口封住点
     await events.get('turn_end')!()
     expect(cleanup).toHaveBeenCalledTimes(1)
 
@@ -212,3 +213,56 @@ describe('pi-scheduler SDK contract', () => {
     expect(cleanup).toHaveBeenCalledTimes(2)
   })
 })
+
+// ── execute 组装 details.summary（withScheduleSummary 包装线回归防线）──
+// 纯函数（buildScheduleSummary / buildScheduleControlSummary）已被 summary.test.ts 直测；
+// 本组护的是 index.ts execute 内的两处组装线（schedule → withScheduleSummary(result,
+// buildScheduleSummary(...))；schedule_control → buildScheduleControlSummary 同款）——
+// 组装行丢失时 details.summary 缺失，GUI 收起态与 TUI 折叠态双双退化为原始 JSON，此处红。
+
+/** execute 返回的 details 形状（组装线断言面：summary 恒为 string）。 */
+interface SummaryDetails {
+  summary: unknown
+}
+
+describe('execute 组装 details.summary（withScheduleSummary 包装线）', () => {
+  /** 装配 → 触发 session_start，返回捕获的两 tool 与事件表。调用方 finally 里 fire session_shutdown 停 tick timer。 */
+  async function setupWithSession(): Promise<{
+    tools: CapturedTool[]
+    events: Map<string, (...args: unknown[]) => void>
+    fakeCtx: ExtensionContext
+  }> {
+    const { pi, tools, events } = createMockPi()
+    schedulerExtension(pi)
+    const fakeCtx = createFakeCtx()
+    await events.get('session_start')!({ type: 'session_start', reason: 'startup' }, fakeCtx)
+    return { tools, events, fakeCtx }
+  }
+
+  it('schedule 创建 → details.summary = Scheduled "<name>" · every 5m（index.ts schedule 包装线）', async () => {
+    const { tools, events, fakeCtx } = await setupWithSession()
+    try {
+      const tool = tools.find(t => t.name === 'schedule')!
+      const result = await tool.execute('call-sum-1', { prompt: 'check build', schedule: '5m' }, undefined, undefined, fakeCtx)
+      // 期望文案锚点：summary.test.ts 直测口径（interval 规格化 every 5m + en-US）
+      expect((result.details as SummaryDetails).summary).toBe('Scheduled "check build" · every 5m')
+    } finally {
+      await events.get('session_shutdown')?.()
+    }
+  })
+
+  it('schedule_control list → details.summary = Listed N tasks（index.ts schedule_control 包装线）', async () => {
+    const { tools, events, fakeCtx } = await setupWithSession()
+    try {
+      // 先建 1 个任务，list 计数才有非零区分度
+      const scheduleTool = tools.find(t => t.name === 'schedule')!
+      await scheduleTool.execute('call-sum-2', { prompt: 'standup', schedule: '5m' }, undefined, undefined, fakeCtx)
+
+      const controlTool = tools.find(t => t.name === 'schedule_control')!
+      const result = await controlTool.execute('call-sum-3', { action: 'list' }, undefined, undefined, fakeCtx)
+      expect((result.details as SummaryDetails).summary).toBe('Listed 1 tasks')
+    } finally {
+      await events.get('session_shutdown')?.()
+    }
+  })
+})

package/src/__tests__/service.test.ts

@@ -315,7 +315,7 @@ describe('SchedulerService', () => {
       if (result.params === undefined || !('tasks' in result.params)) throw new Error('expected list params')
       const line = renderResult('task.list', result.params, 'zh-CN').split('\n')[1]!
       expect(line).toContain('上次: 失败×2')
-      // 命令变体保留相对时间（设计 D1-a：命令层按需呈现面不变）
+      // 命令变体保留相对时间（设计 D1-a：命令层按需呈现侧不变）
       expect(line).toMatch(/分钟后|分钟前|\d+m ago|in \d+m/)
       // params 携带 locale-neutral 原始值（摘要不预渲染）
       expect(result.params.tasks[0]!.lastExec).toEqual({ lastStatus: 'failed', recentFailures: 2 })

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

@@ -1,6 +1,6 @@
 // src/__tests__/session-tree-registration.test.ts
 //
-// U6c session_tree 注册面契约：注册在 extension factory 顶层（每代恰一 handler），
+// U6c session_tree 注册点契约：注册在 extension factory 顶层（每代恰一 handler），
 // 同代 session_start 复发不累积。回归背景：注册曾在 PiSchedulerBackend 构造函数内，
 // 而 pi RPC 模式下每次 session 替换 session_start 在同一代内触发两次
 // （agent-session-runtime finishSessionReplacement 内部 rebindSession + RPC handler
@@ -79,7 +79,7 @@ function taskEntry(sessionFile: string, taskId: string) {
   }
 }
 
-/** fake ctx：entries 经容器可变（模拟撤回前后 swap）；ui.setWidget 观测面。 */
+/** fake ctx：entries 经容器可变（模拟撤回前后 swap）；ui.setWidget 观测范围。 */
 function createFakeCtx(sessionFile: string, entriesBox: { entries: unknown[] }): ExtensionContext {
   return {
     cwd: '/test-tree-reg',
@@ -93,7 +93,7 @@ function createFakeCtx(sessionFile: string, entriesBox: { entries: unknown[] }):
   } as unknown as ExtensionContext
 }
 
-describe('session_tree 注册面（factory 顶层恰一，同代 session_start 复发不累积）', () => {
+describe('session_tree 注册点（factory 顶层恰一，同代 session_start 复发不累积）', () => {
   it('factory 运行恰注册 1 个 session_tree handler', () => {
     const { pi, handlers } = createAppendPi()
     schedulerExtension(pi)

package/src/__tests__/summary.test.ts

@@ -0,0 +1,135 @@
+import type { Theme } from '@earendil-works/pi-coding-agent'
+import { describe, expect, it } from 'vitest'
+
+import {
+  buildScheduleControlSummary,
+  buildScheduleSummary,
+  withScheduleSummary,
+  type ScheduleControlParamsT,
+  type ScheduleParamsT,
+} from '../tool.js'
+import { renderScheduleToolResult } from '../render-result.js'
+
+function toolResult(details: unknown, text = 'body'): { content: { type: 'text'; text: string }[]; details: unknown } {
+  return { content: [{ type: 'text', text }], details }
+}
+
+// ── buildScheduleSummary ─────────────────────────────
+
+describe('buildScheduleSummary', () => {
+  const createParams: ScheduleParamsT = { prompt: 'standup', schedule: '5m', name: 'Standup reminder' }
+
+  it('创建成功 → Scheduled "<name>" · <schedule>（interval 规格化文案，en-US）', () => {
+    const r = toolResult({
+      task: { name: 'Standup reminder', kind: 'recurring', schedule: { mode: 'interval', intervalMs: 300000 } },
+      nextRuns: [],
+    })
+    expect(buildScheduleSummary(createParams, r)).toBe('Scheduled "Standup reminder" · every 5m')
+  })
+
+  it('cron 规格 → 原样表达式', () => {
+    const r = toolResult({
+      task: { name: 'Nightly', kind: 'recurring', schedule: { mode: 'cron', cronExpression: '*/10 * * * *' } },
+      nextRuns: [],
+    })
+    expect(buildScheduleSummary(createParams, r)).toBe('Scheduled "Nightly" · */10 * * * *')
+  })
+
+  it('取消态 → Cancelled', () => {
+    expect(buildScheduleSummary(createParams, toolResult({ cancelled: true }))).toBe('Cancelled')
+  })
+
+  it('details 形态漂移（无 task）→ 降级 Scheduled 不抛错', () => {
+    expect(buildScheduleSummary(createParams, toolResult({}))).toBe('Scheduled')
+  })
+
+  it('task.schedule 非法形态 → 回落 params.schedule 原文', () => {
+    const r = toolResult({ task: { name: 'Odd', schedule: { mode: 'bogus' } } })
+    expect(buildScheduleSummary(createParams, r)).toBe('Scheduled "Odd" · 5m')
+  })
+})
+
+// ── buildScheduleControlSummary ──────────────────────
+
+describe('buildScheduleControlSummary', () => {
+  it('list → Listed N tasks', () => {
+    const params: ScheduleControlParamsT = { action: 'list' }
+    expect(buildScheduleControlSummary(params, toolResult({ tasks: [{}, {}] }))).toBe('Listed 2 tasks')
+    expect(buildScheduleControlSummary(params, toolResult({ tasks: [] }))).toBe('Listed 0 tasks')
+  })
+
+  it('toggle enabled=false → Paused；enabled=true → Resumed', () => {
+    expect(
+      buildScheduleControlSummary({ action: 'toggle', id: 'ab12cd34', enabled: false }, toolResult({})),
+    ).toBe('Paused task ab12cd34')
+    expect(
+      buildScheduleControlSummary({ action: 'toggle', id: 'ab12cd34', enabled: true }, toolResult({})),
+    ).toBe('Resumed task ab12cd34')
+  })
+
+  it('delete / run → 动作 + id', () => {
+    expect(buildScheduleControlSummary({ action: 'delete', id: 'ab12cd34' }, toolResult({}))).toBe(
+      'Deleted task ab12cd34',
+    )
+    expect(buildScheduleControlSummary({ action: 'run', id: 'ab12cd34' }, toolResult({}))).toBe(
+      'Ran task ab12cd34 now',
+    )
+  })
+})
+
+// ── withScheduleSummary ──────────────────────────────
+
+describe('withScheduleSummary', () => {
+  it('details 追加 summary，现有字段保留', () => {
+    const r = toolResult({ tasks: [{}] })
+    const out = withScheduleSummary(r, 'Listed 1 tasks')
+    expect(out.details).toEqual({ tasks: [{}], summary: 'Listed 1 tasks' })
+  })
+
+  it('非对象 details → 防御替换为 { summary }', () => {
+    const r = toolResult('legacy-string')
+    const out = withScheduleSummary(r, 'Done')
+    expect(out.details).toEqual({ summary: 'Done' })
+  })
+})
+
+// ── renderScheduleToolResult（TUI renderResult）──────
+
+const mockTheme = {
+  fg: (_color: string, text: string) => text,
+  bg: (_color: string, text: string) => text,
+  bold: (text: string) => text,
+  italic: (text: string) => text,
+  underline: (text: string) => text,
+  inverse: (text: string) => text,
+  strikethrough: (text: string) => text,
+  getFgAnsi: (_color: string) => '',
+  getBgAnsi: (_color: string) => '',
+  getColorMode: () => 'truecolor' as const,
+  getThinkingBorderColor: () => (text: string) => text,
+  getBashModeBorderColor: () => (text: string) => text,
+} as unknown as Theme
+
+function renderedText(result: unknown, expanded: boolean): string {
+  return renderScheduleToolResult(result, { expanded }, mockTheme)
+    .render(400)
+    .map((line) => line.trimEnd())
+    .join('\n')
+}
+
+describe('renderScheduleToolResult', () => {
+  it('折叠态 → details.summary 一行', () => {
+    const r = withScheduleSummary(toolResult({ tasks: [{}] }, 'multi\nline'), 'Listed 1 tasks')
+    expect(renderedText(r, false)).toBe('Listed 1 tasks')
+  })
+
+  it('展开态 → content 纯文本', () => {
+    const r = toolResult({}, 'line1\nline2')
+    expect(renderedText(r, true)).toBe('line1\nline2')
+  })
+
+  it('无 summary（旧 entry）→ 折叠态回退 content 首行', () => {
+    const r = toolResult({}, 'Header\nbody')
+    expect(renderedText(r, false)).toBe('Header')
+  })
+})

package/src/__tests__/types.test.ts

@@ -4,7 +4,7 @@ import { snapshotToTask, toTaskSnapshot } from '../types.js'
 import type { ScheduledTask, TaskSnapshot } from '../types.js'
 
 /**
- * B2 转换器收敛（ext-simplify-17）等价守卫：toTaskSnapshot canonical 取解构式，
+ * B2 转换器收敛（ext-simplify-17）等价检查：toTaskSnapshot canonical 取解构式，
  * 替换 importer 旧显式 14 字段式——期望值按旧显式式的输出形状逐字段锚定
  * （toEqual 严格比较键集合，解构式多带/漏带键即红），防字段演进中静默漂移。
  * 既有间接断言（importer/runtime 测试的 objectContaining）不覆盖键集合精确性与

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

@@ -2,7 +2,7 @@
 //
 // scheduler widget 推送（D1 指纹跳推）集成单测：
 // 走 index.ts 真实装配链（session_start → runtime.onAfterTick → refreshWidget），
-// 观测面 = ctx.ui.setWidget 调用序列（每个实际推送恰一次调用——跳推判定在
+// 观测范围 = ctx.ui.setWidget 调用序列（每个实际推送恰一次调用——跳推判定在
 // setSchedulerWidget 之前，setWidgetDual 的 TUI 分支与清屏分支都落 setWidget）。
 //
 // 行为契约（scheduler widget 推送修正设计 D1-b）：
@@ -79,7 +79,7 @@ function createMockPi(): { pi: ExtensionAPI; events: Map<string, (...args: unkno
   return { pi, events }
 }
 
-/** fake ctx：entries 注入任务（owner = sessionFile）；setWidget 独立导出作观测面。 */
+/** fake ctx：entries 注入任务（owner = sessionFile）；setWidget 独立导出作观测范围。 */
 function createFakeCtx(sessionFile: string, entries: unknown[] = []): {
   ctx: ExtensionContext
   setWidget: ReturnType<typeof vi.fn>
@@ -153,7 +153,7 @@ describe('widget 推送判定（D1 指纹跳推）', () => {
     stringifySpy.mockRestore()
 
     expect(setWidget).toHaveBeenCalledTimes(2) // fail-open：宁可多推不可漏显
-    // 用户可见面：fail-open 推出的帧内容正确（静态行完整，非空帧/异常串）
+    // 用户可见部分：fail-open 推出的帧内容正确（静态行完整，非空帧/异常串）
     const frame = String((setWidget.mock.calls[1]![1] as string[])[0] ?? '')
     expect(frame).toContain('keepalive probe')
     const warnText = loggerMock.warn.mock.calls.map(c => String(c[0])).join('\n')