@zhushanwen/pi-scheduler 0.5.0 → 0.5.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-scheduler",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "type": "module",
   "main": "index.ts",
   "xyz-agent": {
@@ -45,8 +45,9 @@
     }
   },
   "dependencies": {
-    "@xyz-agent/session-delivery": "0.3.0",
-    "@zhushanwen/pi-extension-logger": "0.4.0"
+    "@xyz-agent/session-delivery": "0.3.1",
+    "@zhushanwen/pi-ext-guards": "0.3.0",
+    "@zhushanwen/pi-extension-logger": "0.6.0"
   },
   "scripts": {
     "test": "vitest run",

package/src/__tests__/commands.test.ts

@@ -181,6 +181,17 @@ describe('/schedule command', () => {
     expect(result).toBe('Usage: /schedule <schedule> <prompt>')
   })
 
+  it('treats prototype-chain key names as unknown (Map lookup, no Object.prototype hit)', async () => {
+    // 路由表用 Map 查找的语义锚：普通对象下标会把 "constructor"/"toString"/"__proto__"
+    // 解析到 Object.prototype（constructor 被当 handler 调用返回对象、__proto__ 直接 TypeError），
+    // 这里必须与其它未知子命令同走创建任务分支（无 schedule 输入 → usage 文案）。
+    for (const key of ['constructor', 'toString', '__proto__']) {
+      expect(await executeScheduleCommand(service, key)).toBe(
+        'Usage: /schedule <schedule> <prompt>',
+      )
+    }
+  })
+
   it('no args returns TUI not-implemented message', async () => {
     const result = await executeScheduleCommand(service, '')
     expect(result).toContain('not yet implemented')

package/src/__tests__/replay.test.ts

@@ -310,6 +310,20 @@ describe('replayFoldEntries', () => {
     expect(msg).toContain('skipping corrupted scheduler entry')
   })
 
+  // ── fork 场景安全：未知 taskId 的 advance/toggle 为静默 no-op，不触发逐条 catch ──
+  it('advance/toggle 对不存在的 taskId 为 no-op（无 upsert 时不产生副作用、不触发逐条 catch warn）', () => {
+    loggerMock.warn.mockClear()
+    const entries = [
+      entry({ op: 'advance', taskId: 'ghost', nextRunAt: 200, at: 100, status: 'success' }),
+      entry({ op: 'toggle', taskId: 'ghost', enabled: false }),
+      entry({ op: 'delete', taskId: 'ghost' }),
+    ]
+    const result = replayFoldEntries(entries, '/s.json')
+    expect(result.size).toBe(0)
+    // no-op 提前返回路径不抛错——MF-2 的逐条跳过 warn 不应被触发
+    expect(loggerMock.warn).not.toHaveBeenCalled()
+  })
+
   afterEach(() => {
     vi.restoreAllMocks()
   })

package/src/commands.ts

@@ -84,11 +84,77 @@ export function registerScheduleCommand(
   })
 }
 
+/** 单个子命令处理器。service 非空由 executeScheduleCommand 前置保证；parts 为 tokenize 后参数。 */
+type SubcommandHandler = (service: SchedulerService, parts: string[]) => string | Promise<string>
+
+/**
+ * on/off 共享：取 <id>，缺失返回 usage（文案与原 ${first} 一致——handler 仅在
+ * first === 'on' | 'off' 时被查表命中，keyword 即 first 的小写值）。
+ */
+async function handleToggleKeyword(
+  service: SchedulerService,
+  parts: string[],
+  keyword: 'on' | 'off',
+): Promise<string> {
+  const id = parts[1]
+  if (!id) return `Usage: /schedule ${keyword} <id>`
+  const result = await service.toggle(id, keyword === 'on')
+  return result.message
+}
+
+/**
+ * 子命令路由表。查表未命中（落空）= 创建任务分支，与原 if 链的顺序语义一致。
+ * list/rm 保持同步返回、run 保持 await——不改变 async 边界内的微任务时序。
+ * 用 Map 而非普通对象：first 是外部输入（/schedule 命令参数），普通对象查表会命中
+ * Object.prototype 上的键（如 "constructor"/"__proto__"），导致错误路由；Map 只查自身键。
+ */
+const SUBCOMMAND_HANDLERS: ReadonlyMap<string, SubcommandHandler> = new Map<string, SubcommandHandler>([
+  ['list', service => service.list().message],
+  ['on', (service, parts) => handleToggleKeyword(service, parts, 'on')],
+  ['off', (service, parts) => handleToggleKeyword(service, parts, 'off')],
+  [
+    'rm',
+    (service, parts) => {
+      const id = parts[1]
+      if (!id) return 'Usage: /schedule rm <id>'
+      return service.delete(id).message
+    },
+  ],
+  [
+    'run',
+    async (service, parts) => {
+      const id = parts[1]
+      if (!id) return 'Usage: /schedule run <id>'
+      const result = await service.run(id)
+      return result.message
+    },
+  ],
+])
+
+/** 创建任务分支（路由落空）：once 前缀 → once 任务；cron 前缀 → recurring cron 任务；其余按 interval schedule 解析。 */
+async function createTaskFromArgs(
+  service: SchedulerService,
+  parts: string[],
+  first: string,
+): Promise<string> {
+  const kind = first === 'once' ? 'once' as const : first === 'cron' ? 'recurring' as const : undefined
+  const scheduleStart = kind ? 1 : 0
+  const scheduleInput = parts[scheduleStart]
+  if (!scheduleInput) return 'Usage: /schedule <schedule> <prompt>'
+
+  const prompt = parts.slice(scheduleStart + 1).join(' ')
+  if (!prompt) return 'Usage: /schedule <schedule> <prompt>'
+
+  const result = await service.create(prompt, scheduleInput, { kind })
+  return result.message
+}
+
 /**
  * Core logic for /schedule command. Extracted for testability (handler returns
  * void per SDK contract; tests call this function directly to assert output).
  *
  * 命令层只保留参数路由与 usage 文案（C6），业务调用全部走 SchedulerService。
+ * 主函数只留编排：service 守卫 → 空 args → tokenize → 查表分发 → 创建分支。
  */
 export async function executeScheduleCommand(
   service: SchedulerService | null,
@@ -105,40 +171,9 @@ export async function executeScheduleCommand(
   const parts = tokenizeQuoted(trimmed)
   const first = parts[0]!.toLowerCase()
 
-  // 子命令路由
-  if (first === 'list') {
-    return service.list().message
-  }
-
-  if (first === 'on' || first === 'off') {
-    const id = parts[1]
-    if (!id) return `Usage: /schedule ${first} <id>`
-    const result = await service.toggle(id, first === 'on')
-    return result.message
-  }
-
-  if (first === 'rm') {
-    const id = parts[1]
-    if (!id) return 'Usage: /schedule rm <id>'
-    return service.delete(id).message
-  }
-
-  if (first === 'run') {
-    const id = parts[1]
-    if (!id) return 'Usage: /schedule run <id>'
-    const result = await service.run(id)
-    return result.message
-  }
+  // 子命令路由：查表命中走对应分支，落空走创建任务分支
+  const handler = SUBCOMMAND_HANDLERS.get(first)
+  if (handler) return handler(service, parts)
 
-  // 创建任务分支
-  const kind = first === 'once' ? 'once' as const : first === 'cron' ? 'recurring' as const : undefined
-  const scheduleStart = kind ? 1 : 0
-  const scheduleInput = parts[scheduleStart]
-  if (!scheduleInput) return 'Usage: /schedule <schedule> <prompt>'
-
-  const prompt = parts.slice(scheduleStart + 1).join(' ')
-  if (!prompt) return 'Usage: /schedule <schedule> <prompt>'
-
-  const result = await service.create(prompt, scheduleInput, { kind })
-  return result.message
+  return createTaskFromArgs(service, parts, first)
 }

package/src/replay.ts

@@ -24,16 +24,16 @@ const HISTORY_LIMIT = 20
  * pi-scheduler:task custom entries 折叠成运行时任务 Map。
  *
  * 两步：
- * ① 全量折叠——遍历 customType==='pi-scheduler:task' 的 entries，按 op 类型折叠：
+ * ① 全量折叠（foldEntries）——遍历 customType==='pi-scheduler:task' 的 entries，按 op 类型折叠：
  *    - upsert → 用快照重建任务（ownerSessionFile 来自 op 顶层）
  *    - advance → nextRunAt=新值 / lastRunAt=at / runCount++ / history.push(裁20) / lastStatus=status（gap2）
  *    - toggle → enabled=新值
  *    - delete → 从 Map 移除（后续同 taskId 的 advance/toggle 对不存在 taskId 为 no-op，安全）
  *   advance/toggle/delete 对不存在的 taskId 为 no-op，因此 fork 继承的完整序列必须先全量折叠，
  *   不能在处理 upsert 时按 owner 跳过（否则后续无 owner 字段的 op 会作用于「不存在的 taskId」丢失）。
- * ② 折叠完成后按 task.ownerSessionFile !== currentSessionFile 整体过滤（gap1）：移除 fork
- *   继承的非 owner 任务——fork 出的 session B 继承了 owner=A 的 upsert+advance 序列，但 B
- *   不应拥有 A 的任务，重放后整体过滤掉。
+ * ② 折叠完成后按 task.ownerSessionFile !== currentSessionFile 整体过滤（gap1，filterNonOwnerTasks）：
+ *   移除 fork 继承的非 owner 任务——fork 出的 session B 继承了 owner=A 的 upsert+advance 序列，
+ *   但 B 不应拥有 A 的任务，重放后整体过滤掉。
  *
  * append-only 时序保证 nextRunAt 不回退（D1）：advance entry 按写入顺序折叠，自然取到最后推进值。
  *
@@ -45,61 +45,8 @@ export function replayFoldEntries(
 ): Map<string, ScheduledTask> {
   try {
     const tasks = new Map<string, ScheduledTask>()
-
-    for (const entry of entries) {
-      if (entry.type !== 'custom' || entry.customType !== 'pi-scheduler:task') continue
-      if (!isSchedulerEntryOp(entry.data)) continue
-      const op = entry.data // SchedulerEntryOp（守卫 isSchedulerEntryOp 收窄）
-
-      try {
-        switch (op.op) {
-          case 'upsert': {
-            tasks.set(op.taskId, { ...snapshotToTask(op.task), ownerSessionFile: op.ownerSessionFile })
-            break
-          }
-          case 'advance': {
-            const task = tasks.get(op.taskId)
-            if (!task) break // no-op for unknown taskId（fork 场景安全）
-            task.nextRunAt = op.nextRunAt
-            task.lastRunAt = op.at
-            task.runCount += 1
-            task.history.push({ at: op.at, status: op.status })
-            if (task.history.length > HISTORY_LIMIT) task.history.shift()
-            task.lastStatus = op.status // gap2：advance 必须恢复 lastStatus（不只 nextRunAt/lastRunAt/runCount/history）
-            break
-          }
-          case 'toggle': {
-            const task = tasks.get(op.taskId)
-            if (!task) break
-            task.enabled = op.enabled
-            // P1：enable 重算到未来的 nextRunAt 随 toggle op 持久化；重放时应用，
-            // 防 upsert 快照回退到旧过期值导致首个 tick 立即触发
-            if (op.nextRunAt !== undefined) task.nextRunAt = op.nextRunAt
-            break
-          }
-          case 'delete': {
-            tasks.delete(op.taskId)
-            break
-          }
-        }
-      } catch (err) {
-        // MF-2：守卫已按变体校验必填字段，但嵌套数据损坏（如 upsert task.history 非数组 →
-        // snapshotToTask 的 .map 抛）仍可能抛——逐条 try/catch 只跳过该条，
-        // 不让外层整体 catch 把全部任务清成空 Map（一条损坏 entry 不得清空全部任务）
-        logger.warn('skipping corrupted scheduler entry', { error: err instanceof Error ? err.message : String(err) })
-        continue
-      }
-    }
-
-    // 步骤② fork owner 过滤（gap1）：折叠完成后整体移除非 owner 任务。
-    // currentSessionFile 为 undefined（--no-session 模式）时，所有带 ownerSessionFile 的任务都被移除
-    // （无 session 文件可归属，等同空 session）——该模式下 addTask 用 '' 兜底 owner，此处比较仍一致。
-    for (const [id, task] of tasks) {
-      if (task.ownerSessionFile !== currentSessionFile) {
-        tasks.delete(id)
-      }
-    }
-
+    foldEntries(entries, tasks)
+    filterNonOwnerTasks(tasks, currentSessionFile)
     return tasks
   } catch (err) {
     // gap4：session JSONL 损坏 / 迭代器抛错时降级为无任务，不让 session_start 崩溃。
@@ -108,6 +55,97 @@ export function replayFoldEntries(
   }
 }
 
+/** 步骤① 全量折叠：跳过非本扩展 entry 与守卫不过的损坏 entry；单条折叠抛错只跳过该条（MF-2）。 */
+function foldEntries(entries: Iterable<SchedulerEntryLike>, tasks: Map<string, ScheduledTask>): void {
+  for (const entry of entries) {
+    if (entry.type !== 'custom' || entry.customType !== 'pi-scheduler:task') continue
+    if (!isSchedulerEntryOp(entry.data)) continue
+    const op = entry.data // SchedulerEntryOp（守卫 isSchedulerEntryOp 收窄）
+
+    try {
+      applyOp(tasks, op)
+    } catch (err) {
+      // MF-2：守卫已按变体校验必填字段，但嵌套数据损坏（如 upsert task.history 非数组 →
+      // snapshotToTask 的 .map 抛）仍可能抛——逐条 try/catch 只跳过该条，
+      // 不让外层整体 catch 把全部任务清成空 Map（一条损坏 entry 不得清空全部任务）
+      logger.warn('skipping corrupted scheduler entry', { error: err instanceof Error ? err.message : String(err) })
+      continue
+    }
+  }
+}
+
+/** 按 op 判别值分发到对应折叠函数；无 default——未知 op 静默跳过（守卫已排除，理论不可达）。 */
+function applyOp(tasks: Map<string, ScheduledTask>, op: SchedulerEntryOp): void {
+  switch (op.op) {
+    case 'upsert':
+      applyUpsert(tasks, op)
+      break
+    case 'advance':
+      applyAdvance(tasks, op)
+      break
+    case 'toggle':
+      applyToggle(tasks, op)
+      break
+    case 'delete':
+      applyDelete(tasks, op)
+      break
+  }
+}
+
+/** upsert → 用快照重建任务（ownerSessionFile 来自 op 顶层）。 */
+function applyUpsert(
+  tasks: Map<string, ScheduledTask>,
+  op: Extract<SchedulerEntryOp, { op: 'upsert' }>,
+): void {
+  tasks.set(op.taskId, { ...snapshotToTask(op.task), ownerSessionFile: op.ownerSessionFile })
+}
+
+/** advance → 推进运行末态；对不存在的 taskId 为 no-op（fork 场景安全）。 */
+function applyAdvance(
+  tasks: Map<string, ScheduledTask>,
+  op: Extract<SchedulerEntryOp, { op: 'advance' }>,
+): void {
+  const task = tasks.get(op.taskId)
+  if (!task) return // no-op for unknown taskId（fork 场景安全）
+  task.nextRunAt = op.nextRunAt
+  task.lastRunAt = op.at
+  task.runCount += 1
+  task.history.push({ at: op.at, status: op.status })
+  if (task.history.length > HISTORY_LIMIT) task.history.shift()
+  task.lastStatus = op.status // gap2：advance 必须恢复 lastStatus（不只 nextRunAt/lastRunAt/runCount/history）
+}
+
+/** toggle → enabled=新值；携带 nextRunAt 时一并应用（P1，防快照回退到旧过期值）。 */
+function applyToggle(
+  tasks: Map<string, ScheduledTask>,
+  op: Extract<SchedulerEntryOp, { op: 'toggle' }>,
+): void {
+  const task = tasks.get(op.taskId)
+  if (!task) return
+  task.enabled = op.enabled
+  // P1：enable 重算到未来的 nextRunAt 随 toggle op 持久化；重放时应用，
+  // 防 upsert 快照回退到旧过期值导致首个 tick 立即触发
+  if (op.nextRunAt !== undefined) task.nextRunAt = op.nextRunAt
+}
+
+/** delete → 从 Map 移除；taskId 不存在时 no-op。 */
+function applyDelete(tasks: Map<string, ScheduledTask>, op: Extract<SchedulerEntryOp, { op: 'delete' }>): void {
+  tasks.delete(op.taskId)
+}
+
+/**
+ * 步骤② fork owner 过滤（gap1）：折叠完成后整体移除非 owner 任务。
+ * currentSessionFile 为 undefined（--no-session 模式）时，所有带 ownerSessionFile 的任务都被移除
+ * （无 session 文件可归属，等同空 session）——该模式下 addTask 用 '' 兜底 owner，此处比较仍一致。
+ */
+function filterNonOwnerTasks(tasks: Map<string, ScheduledTask>, currentSessionFile: string | undefined): void {
+  for (const [id, task] of tasks) {
+    if (task.ownerSessionFile !== currentSessionFile) {
+      tasks.delete(id)
+    }
+  }
+}
+
 /**
  * 类型守卫：判断 entry.data 是否为合法 SchedulerEntryOp——按 op 变体校验必填字段，
  * 不只校验 op 判别值（MF-2 修复）。仅按判别值收窄时，损坏 entry `{op:'upsert'}`（缺 task）

package/src/runtime.ts

@@ -1,4 +1,5 @@
 import type { ExtensionContext } from '@earendil-works/pi-coding-agent'
+import { guardStaleCtx, toErrorMessage } from '@zhushanwen/pi-ext-guards'
 import { getLogger } from '@zhushanwen/pi-extension-logger'
 
 import type { DeliveryHandle, DeliveryMessage } from '@xyz-agent/session-delivery'
@@ -25,16 +26,13 @@ const TICK_INTERVAL_MS = 30_000
 const DEFAULT_EXPIRY_DAYS = 7
 const DEFAULT_EXPIRY_MS = DEFAULT_EXPIRY_DAYS * MS_PER_DAY // 7 days
 const HISTORY_LIMIT = 20 // 与 replayFoldEntries 的裁剪上限一致（advance 折叠 / dispatch 累积共用）
-// pi ExtensionRunner 在 session 替换后访问 stale ctx 时抛出的错误文案片段。
-// 兜底通道（防御纵深）：G1 模块级代际检测（isCtxStale）为主判，覆盖同模块环境内的 session
-// 替换路径（newSession/fork/switchSession：extensionCache 命中，factory 重跑但模块环境共享，
-// 模块级代数被新闭包递增）；本子串覆盖代际盲区——显式 reload / cwd 变化触发
-// clearExtensionCache 后 jiti 重新 import 产生全新模块环境，旧闭包引用的模块级代数冻结
-// 不再递增，isCtxStale 恒 false，此时除 session_shutdown teardown 主防线外只剩错误文案
-// 能识别 stale。
-// 注意：pi 非契约 API（Error message 非稳定接口），pi 升级需回归验证 runtime.test.ts 的
-// U1 / G1-d 文案锚定用例；文案变更时此兜底失效，后果为 timer 泄漏 + 每 30s warn（不 crash）。
-const STALE_CTX_MARKER = 'stale after session replacement'
+// STALE_CTX_MARKER（文案兜底分诊词）已迁移到 ext-guards 共享守卫（guardStaleCtx 内部
+// 引用，本文件不再直接持有）。语义：G1 模块级代际检测（isCtxStale）为主判；文案子串
+// 覆盖代际盲区——显式 reload / cwd 变化触发 clearExtensionCache 后 jiti 重新 import 产生
+// 全新模块环境，旧闭包引用的模块级代数冻结不再递增，isCtxStale 恒 false，只剩错误文案
+// 能识别 stale。pi 非契约 API（Error message 非稳定接口）：文案由 docs/pi-semantics.json
+// PS-30 探针随 pi 版本门禁自动重验；pi 升级仍需回归 runtime.test.ts 的 U1 / G1-d 文案
+// 锚定用例。文案变更时此兜底失效，后果为 timer 泄漏 + 每 30s warn（不 crash）。
 
 export class SchedulerRuntime {
   private tasks: Map<string, ScheduledTask> = new Map()
@@ -201,27 +199,28 @@ export class SchedulerRuntime {
   startScheduler(): void {
     if (this.tickTimer) return
     this.tickTimer = setInterval(() => {
-      // G1（代际前置检查，S9）：本 runtime 所属 session 已被替换 → timer 属泄漏资源，
-      // 自停退场且不进入本轮 tick（不触碰捕获的 stale ctx）。主防线是 F1（session_start
-      // 停旧 timer），此处覆盖 F1 未能触达的泄漏路径——且不依赖「stale ctx 访问恰好抛错」
-      // 或 pi 错误文案，代际一翻转即可静默退场。
-      if (this.isCtxStale?.()) {
-        this.retireStaleTimer()
-        return
-      }
-      // F2（防御兜底）：fire-and-forget 的 tick 链路必须自带 catch——tick 内任何异常
-      // （典型：session 替换后泄漏 timer 的 onAfterTick → refreshWidget 访问 stale ctx.ui 抛错）
-      // 若无人接住即 unhandledRejection，直接崩掉 pi 主进程。分诊：G1 模块级代数比对为主判
-      // （契约内，不受 pi 文案变更影响），STALE_CTX_MARKER 子串为兜底（覆盖 reload 产生全新
-      // 模块环境后旧闭包代数冻结、isCtxStale 恒 false 的盲区）。stale 类错误说明本 runtime
-      // 所属 session 已被替换，timer 属泄漏资源，自停退场；其他错误仅告警，不终止调度。
-      void this.tickScheduler().catch((err: unknown) => {
-        const message = err instanceof Error ? err.message : String(err)
-        if (this.isCtxStale?.() || message.includes(STALE_CTX_MARKER)) {
-          this.retireStaleTimer()
-        } else {
-          logger.warn('tick error', { error: message })
-        }
+      // 三件套语义等价迁移到共享守卫 guardStaleCtx（crash-resilience D1 / u1-ext-guard；
+      // 守卫语义 = 本处原地实现的泛化，迁移对照逐条可证）：
+      // 1. G1 前置检查（S9）：守卫的 isCtxStale 命中 → onStale（= retireStaleTimer）且
+      //    tickScheduler 不执行——与迁移前「前置分支 return」等价：本 runtime 所属 session
+      //    已被替换 → timer 属泄漏资源自停退场，不触碰捕获的 stale ctx，不依赖 pi 错误文案。
+      //    主防线仍是 F1（session_start 停旧 timer），此处覆盖 F1 未能触达的泄漏路径。
+      // 2. F2 catch 分诊（防御兜底）：守卫对 tickScheduler 的 rejection 挂同一分诊谓词
+      //    `isCtxStale() || 文案含 STALE_CTX_MARKER`（字面不变）——stale → retireStaleTimer；
+      //    非 stale → 原样 reject，由下方 .catch 仅告警不终止调度（'tick error' 文案不变，
+      //    U2/G1-c 锚定）。fire-and-forget 的 tick 链路必须自带 catch——tick 内任何异常
+      //    （典型：泄漏 timer 的 onAfterTick → refreshWidget 访问 stale ctx.ui 抛错）无人接住
+      //    即 unhandledRejection，直接崩掉 pi 主进程（E1 同机制）。
+      // 3. retireStaleTimer 自停：未改（'tick stopped' warn 口径与幂等 stopScheduler 原样，
+      //    U1/G1-b/G1-d 锚定）。
+      // `?.catch`：前置检查命中时守卫返回 undefined（fn 未执行、无 Promise、无 rejection
+      // 可接——retire 已由 onStale 完成）；非 stale 时返回 Promise，非 stale rejection
+      // 流到 .catch 仅告警。
+      void guardStaleCtx(() => this.tickScheduler(), {
+        isCtxStale: this.isCtxStale,
+        onStale: () => this.retireStaleTimer(),
+      })?.catch((err: unknown) => {
+        logger.warn('tick error', { error: toErrorMessage(err) })
       })
     }, TICK_INTERVAL_MS)
   }

package/vitest.config.ts

@@ -2,6 +2,8 @@ import { defineConfig } from 'vitest/config'
 
 export default defineConfig({
   test: {
+    reporters: ['default', 'junit'],
+    outputFile: { junit: './test-results/vitest-junit.xml' },
     include: ['src/__tests__/**/*.test.ts'],
   },
 })