@zhushanwen/pi-scheduler 0.11.0 → 0.11.2

package/README.md

@@ -28,15 +28,9 @@ npm install @zhushanwen/pi-scheduler
 
 安装后扩展在 pi 会话启动时自动装配（见下节），无需额外配置。
 
-## 工具激活（deferred）
+## 工具激活
 
-`schedule` / `schedule_control` 工具注册为 `exposure: "deferred"`——不占常驻工具声明，由 pi 内置 `tool_search` 工具检索命中后按需激活。taiji 宿主内开箱即用（宿主启动时已激活 `tool_search`）；独立 pi 使用需在 `<agentDir>/settings.json`（默认 `~/.pi/agent/settings.json`）开启：
-
-```json
-{ "defaultTools": ["+tool_search"] }
-```
-
-`+` 前缀是增量修饰（保留 read/bash/edit/write 默认集）。未开启 `tool_search` 时这两个工具对模型不可见。
+`schedule` / `schedule_control` 两工具均为 direct 常驻——注册不声明 `exposure` 字段（pi SDK 缺省 `direct`），工具声明随会话常驻、对模型默认可见，无需经 `tool_search` 检索激活，独立 pi 开箱即用。
 
 ## 激活方式
 
@@ -208,7 +202,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.11.0",
+  "version": "0.11.2",
   "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 注册逻辑的入口契约。
@@ -16,7 +17,7 @@
 // 读取——若在 factory 顶层捕获 service! 非空断言，注册时 service 为 null，
 // execute 调用会 NPE。此套件验证 session_start 前 execute 优雅 throw 而非 crash。
 
-import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent'
+import type { ExtensionAPI, ExtensionContext, Theme } from '@earendil-works/pi-coding-agent'
 import { describe, expect, it, vi } from 'vitest'
 
 // MF-3：session_start handler 会真实执行 importLegacyStore(ctx.cwd, ...) —— fakeCtx cwd='/test'
@@ -104,6 +105,40 @@ describe('pi-scheduler SDK contract', () => {
     }
   })
 
+  // exposure 重划终态锚（C-ext-05，2026-10-23 ADR-0136）：两工具保持 direct 常驻 =
+  // 注册时不写 exposure 字段（SDK 缺省 direct，pi-semantics PS-91）——误写 "deferred" 会把
+  // 触发入口从模型默认可见集收走（tool_search 才可激活），此处红。
+  it('exposure 注册终态：schedule / schedule_control 均 direct 常驻（不写 exposure 字段，SDK 缺省）', () => {
+    const { pi, tools } = createMockPi()
+    schedulerExtension(pi)
+    expect(tools.map(t => t.name).sort()).toEqual(['schedule', 'schedule_control'])
+    for (const tool of tools) {
+      expect(tool.exposure).toBeUndefined()
+    }
+  })
+
+  it('每个 tool 有 renderResult 函数成员（C-ext-05）+ 折叠态输出 details.summary 一行', () => {
+    const { pi, tools } = createMockPi()
+    schedulerExtension(pi)
+    for (const tool of tools) {
+      expect(typeof tool.renderResult).toBe('function')
+      const renderResult = tool.renderResult as (
+        result: unknown,
+        options: { expanded: boolean },
+        theme: Theme,
+      ) => { render: (width: number) => string[] }
+      const renderTheme = { fg: (_token: string, text: string) => text } as unknown as Theme
+      const result = {
+        content: [{ type: 'text', text: 'schedule output…' }],
+        details: { summary: 'Scheduled reminder in 5m' },
+      }
+      // Text.render 按宽度 pad，trim 后断言（折叠态 = details.summary 一行）
+      const lines = renderResult(result, { expanded: false }, renderTheme).render(400)
+      expect(lines.length).toBe(1)
+      expect(lines[0].trim()).toBe('Scheduled reminder in 5m')
+    }
+  })
+
   it('execute 是 async function', () => {
     const { pi, tools } = createMockPi()
     schedulerExtension(pi)
@@ -203,7 +238,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)
 

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

@@ -47,6 +47,13 @@ describe('buildScheduleSummary', () => {
     const r = toolResult({ task: { name: 'Odd', schedule: { mode: 'bogus' } } })
     expect(buildScheduleSummary(createParams, r)).toBe('Scheduled "Odd" · 5m')
   })
+
+  it('name / schedule 含换行 → 摘要归一单行（S-1）', () => {
+    const r = toolResult({ task: { name: 'Multi\nline', schedule: { mode: 'bogus' } } })
+    expect(buildScheduleSummary({ ...createParams, schedule: '5m\nextra' }, r)).toBe(
+      'Scheduled "Multi line" · 5m extra',
+    )
+  })
 })
 
 // ── buildScheduleControlSummary ──────────────────────

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')

package/src/__tests__/widget.test.ts

@@ -26,7 +26,7 @@ const makeTask = (overrides: Partial<ScheduledTask> = {}): ScheduledTask => ({
   ...overrides,
 })
 
-describe('renderSchedulerWidgetTui（D1 静态面契约）', () => {
+describe('renderSchedulerWidgetTui（D1 静态范围契约）', () => {
   it('returns empty array when no tasks', () => {
     expect(renderSchedulerWidgetTui([], 'en-US')).toEqual([])
   })
@@ -37,7 +37,7 @@ describe('renderSchedulerWidgetTui（D1 静态面契约）', () => {
     expect(result[0]).toContain('2 scheduled')
   })
 
-  // 静态面：最近任务行 = 任务名 + 静态调度描述（formatSchedule），无相对时间
+  // 静态范围：最近任务行 = 任务名 + 静态调度描述（formatSchedule），无相对时间
   it('renders nearest task with static schedule description, no relative time', () => {
     const tasks = [makeTask({ name: 'check build' })]
     const result = renderSchedulerWidgetTui(tasks, 'en-US')
@@ -48,7 +48,7 @@ describe('renderSchedulerWidgetTui（D1 静态面契约）', () => {
     expect(result[0]).not.toContain('now')
   })
 
-  // 逾期标记整体移除：nextRunAt 在过去也不产生 [!] 段（now 派生显示不进静态面）
+  // 逾期标记整体移除：nextRunAt 在过去也不产生 [!] 段（now 派生显示不进静态范围）
   it('omits overdue marker even when nextRunAt is in the past', () => {
     const tasks = [makeTask({ nextRunAt: Date.now() - 1000 })]
     const result = renderSchedulerWidgetTui(tasks, 'en-US')
@@ -120,7 +120,7 @@ describe('renderSchedulerWidgetTui（D1 静态面契约）', () => {
   })
 })
 
-describe('buildSchedulerWidgetGui（D1 静态面契约）', () => {
+describe('buildSchedulerWidgetGui（D1 静态范围契约）', () => {
   it('emits structured meta with self-owned localized title (en-US)', () => {
     const tasks = [makeTask(), makeTask({ id: 'def67890', name: 'another' })]
     const gui = buildSchedulerWidgetGui(tasks, 'en-US')
@@ -219,7 +219,7 @@ describe('setSchedulerWidget', () => {
 
 // ── D1-b 任务集指纹（computeTasksFingerprint 纯函数契约）──
 // 维护不变量：指纹字段集 ⊇ widget 显示决定因素全集（scheduler widget 推送修正设计 D1-b）。
-// 显示面 = f(id, name, schedule, kind, enabled, nextRunAt, locale)——以下用例逐字段锁定：
+// 显示侧 = f(id, name, schedule, kind, enabled, nextRunAt, locale)——以下用例逐字段锁定：
 // 变更任一显示决定因素必变指纹，字段不变必同指纹。
 
 describe('computeTasksFingerprint（字段集契约）', () => {
@@ -259,13 +259,17 @@ describe('computeTasksFingerprint（字段集契约）', () => {
 
   it('non-display runtime state does NOT alter the fingerprint', () => {
     // runCount/history/lastStatus/pending 不在指纹字段集（非显示决定因素——执行摘要只进
-    // 命令查询面）。它们变化不触发推送，否则静态期零推送承诺被破坏。
-    const base = makeTask()
+    // 命令查询结果）。它们变化不触发推送，否则静态期零推送承诺被破坏。
+    // nextRunAt 显式固定（nextRunAt 在指纹字段集内）：makeTask 缺省 Date.now() 两次调用
+    // 跨毫秒边界时差 1ms → 指纹不同 → 断言测到时钟而非字段集（coverage-gate 实测实例）。
+    const now = Date.now()
+    const base = makeTask({ nextRunAt: now })
     const busy = makeTask({
       runCount: 7,
       history: [{ at: base.createdAt, status: 'failed' }],
       lastStatus: 'failed',
       pending: true,
+      nextRunAt: now,
     })
     expect(computeTasksFingerprint([base], 'en-US')).toBe(computeTasksFingerprint([busy], 'en-US'))
   })

package/src/ack-notify.ts

@@ -12,7 +12,7 @@
 // （`notify-toast.ts` 对非前台 session 的 info 不弹窗），用 `info` 等于静默撒谎。
 //
 // 反向撒谎禁令：e1/e2/e4/e5（真实模型已应答 ⇒ 任务其实已落盘）与 e8b（hybrid ⇒ 覆写照常
-// 发生）一律不发「未写入」文案；e6（注销失败）与落盘无关，只在日志面登记。这些形态在
+// 发生）一律不发「未写入」文案；e6（注销失败）与落盘无关，只在日志侧登记。这些形态在
 // 类型层就不可传入通知路径（`AckNotifyReason` 只含两种可通知形态）。
 
 /**

package/src/ack-provider.ts

@@ -228,7 +228,7 @@ export async function computeAckAvailability(deps: AckAvailabilityDeps): Promise
   }
 }
 
-// ── 小守卫（禁 any / 免断言）──
+// ── 小检查（禁 any / 免断言）──
 
 /** 是否为带 `code` 的 Node errno 异常（ENOENT 判别用）。 */
 function isErrnoException(err: unknown): err is NodeJS.ErrnoException {
@@ -240,7 +240,7 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value)
 }
 
-/** 错误类型最小投影（name + 可选 code）——只取可安全入日志的字段。 */
+/** 错误类型最小派生视图（name + 可选 code）——只取可安全入日志的字段。 */
 function describeError(err: unknown): { name: string; code?: string } {
   if (err instanceof Error) {
     const code = isErrnoException(err) ? err.code : undefined

package/src/ack-turn.ts

@@ -78,7 +78,7 @@ export const ackState: AckState = getOrCreateAckState()
 /** 通知去重（模块级；resetAckState 全清——跨会话隔离）。 */
 const notifyDedup = createAckNotifyDedup()
 
-/** 编排依赖（注入面；backend 为 per-session 实例，状态经模块级单例跨代共享）。 */
+/** 编排依赖（注入点；backend 为 per-session 实例，状态经模块级单例跨代共享）。 */
 export interface AckTurnDeps {
   backend: SchedulerBackend
   log: {