@zhushanwen/pi-scheduler 0.2.0 → 0.3.1

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "@zhushanwen/pi-scheduler",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "type": "module",
   "main": "index.ts",
   "pi": {
     "extensions": [
       "./index.ts"
     ],
-    "skills": []
+    "skills": [
+      "./skills"
+    ]
   },
   "keywords": [
     "pi-package"
@@ -19,6 +21,7 @@
   "files": [
     "index.ts",
     "src/**/*.ts",
+    "skills/",
     "vitest.config.ts"
   ],
   "peerDependencies": {

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

@@ -0,0 +1,191 @@
+---
+name: scheduler-ext-config
+description: "使用或排查 @zhushanwen/pi-scheduler（定时任务调度）时加载。说明任务创建/管理方式（/schedule 命令与 schedule 工具）、调度格式（interval duration 与 cron）、数据存储机制（session JSONL 的 append-only event sourcing，无独立配置文件）、旧版 store 迁移、运行限制。触发词：配置定时任务、scheduler 配置、定时调度、cron 任务、interval 任务、scheduler 存储、scheduler 数据在哪、定时任务排查、scheduler-ext-config。"
+---
+
+# scheduler 使用与存储指南
+
+> @zhushanwen/pi-scheduler：定时任务调度扩展。任务到期时向当前 session 注入一条 message（`deliverAs: 'followUp'` + `triggerTurn: true`），唤醒 agent 开新一轮 turn 处理。
+
+**重要前提**：scheduler **没有独立的配置文件**。任务通过命令/工具交互创建，数据以 append-only event sourcing 方式存储在 session JSONL 中（见下文「数据存储位置」）。排查「任务存哪 / 为什么 resume 后任务变了 / fork 后任务是否继承」都必须基于此模型理解，不要去找独立的 `scheduler.json`（那是已废弃的旧版格式，仅迁移探测时使用）。
+
+## 如何创建/管理定时任务
+
+两条入口，底层都走 `SchedulerService`（单一业务实现，无双轨）：
+
+### 1. `/schedule` slash 命令（用户/AI 直接输入）
+
+| 用法 | 作用 |
+|------|------|
+| `/schedule <schedule> <prompt>` | 创建 recurring 任务（默认） |
+| `/schedule once <delay> <prompt>` | 创建一次性任务（执行一次后自动删除） |
+| `/schedule cron '<cron表达式>' <prompt>` | 创建 cron 任务（**必须用引号**包裹，否则空格会被 tokenize 拆散） |
+| `/schedule list` | 列出全部任务（按 nextRunAt 排序） |
+| `/schedule on <id>` / `/schedule off <id>` | 启用 / 禁用某任务 |
+| `/schedule rm <id>` | 删除某任务 |
+| `/schedule run <id>` | 立即触发一次某任务 |
+
+- 无参数 `/schedule`：当前返回「TUI 未实现」提示，用 `/schedule list` 查看任务。
+- `on`/`off`/`rm`/`run` 的 `<id>` 支持命令补全（`getArgumentCompletions` 会列出 `id · name · schedule`）。
+- cron 表达式含空格，**必须用单/双引号**包成一个 token，例：`/schedule cron '*/10 * * * *' 跑测试`。
+
+### 2. `schedule` / `schedule_control` 工具（AI 调用）
+
+- **`schedule`**（创建）：参数 `prompt`（必填，到期注入的消息）、`schedule`（必填，duration 或 cron）、`kind`（`once`/`recurring`，默认 `recurring`）、`name`（可选，缺省从 prompt 自动截取前 30 字）、`expires`（可选，默认 7 天；传 `"never"` 关闭过期）、`force`（可选，默认 `false`）。
+- **`schedule_control`**（管理）：`action` = `list`/`toggle`/`delete`/`run`，`id`（toggle/delete/run 必填），`enabled`（toggle 必填）。
+- 两个工具的返回都是结构化 `{content: [{type:'text', text}], details, isError?}`，业务失败返回 `isError:true` + `details.errorCode`（不抛异常）。
+
+> 创建/管理操作无需 agent idle——只有**到期 dispatch** 才受 idle/速率限制约束（见「运行限制与 dispatch 行为」）。
+
+## 调度格式
+
+`parseSchedule` 的分流规则：**输入不含空格 → duration（interval 模式）；含空格 → cron（cron 模式）**。
+
+### interval（duration 字符串）
+
+格式 `<数字><单位>`，单位不区分大小写、支持单复数：
+
+| 单位 | 别名 | 毫秒 |
+|------|------|------|
+| `s` | `sec`/`second`/`seconds` | 1000 |
+| `m` | `min`/`minute`/`minutes` | 60_000 |
+| `h` | `hr`/`hour`/`hours` | 3_600_000 |
+| `d` | `day`/`days` | 86_400_000 |
+
+示例：`5m`、`2h`、`1d`、`30seconds`。正则 `/^(\d+)\s*(s|sec|...)$/i`，不匹配则解析失败。
+
+### cron（cron 表达式）
+
+- **5 字段**（分 时 日 月 周）：自动在最前面补秒字段 `0`，变成 6 字段。例 `*/10 * * * *` → `0 */10 * * * *`（每 10 分钟）。
+- **6 字段**（秒 分 时 日 月 周）：原样使用。
+- 其他字段数（<5 或 >6）视为无效。
+- 底层用 `croner` 库（peerDependency，运行时动态 `import('croner')`；未安装时 cron 任务全部解析失败，interval 不受影响）。
+- 创建时即校验表达式有效性（算不出下次执行时间 → `INVALID_SCHEDULE`）；运行中表达式失效（极少见，如月份边界）→ 任务被停用并记 `lastError='cron expression invalid'`。
+
+示例：`*/30 * * * *`（每 30 分）、`0 9 * * 1-5`（工作日早 9 点）、`0 0 * * *`（每天 0 点）。
+
+## 数据存储位置（排查必读）
+
+**当前版本采用 session JSONL 的 append-only event sourcing，没有独立数据文件。**
+
+- 任务的所有变更以 custom entry 写入**创建该任务的 session 的 JSONL 文件**：
+  - 调用 `pi.appendEntry('pi-scheduler:task', op)`，`customType` 固定为 `pi-scheduler:task`。
+  - op 有四种：`upsert`（创建，携带全量 `TaskSnapshot`）、`advance`（recurring dispatch 成功后推进 `nextRunAt`）、`toggle`（启用/禁用）、`delete`（删除 / once 执行后 / 过期清理）。
+- session 启动时（`session_start` 事件），`PiSchedulerBackend.loadTasks()` 调 `replayFoldEntries` 折叠当前 session 的全部 `pi-scheduler:task` custom entries，重放出当前任务状态。**append-only 不做全量 persist**——没有「保存」动作，每次操作即时 append。
+- 因此「任务存哪」的答案是：**创建它的那个 session 的 JSONL 文件**。该文件位于 pi agent 目录下（`getAgentDir()` 读 `PI_CODING_AGENT_DIR`，默认 `~/.pi/agent`；xyz-agent 数据目录隔离时指向隔离目录如 `~/.xyz-agent/...`）。
+
+### owner 隔离（fork 行为）
+
+- 每个 `upsert` op 顶层带 `ownerSessionFile`（创建任务时所属 session 的 JSONL 路径）。
+- `replayFoldEntries` 重放时**过滤掉 owner 不是当前 session 的任务**（防 fork/branch 继承导致同一逻辑任务跨 session 重复触发）。
+- 含义：在 session A 创建的任务，fork 出 session B 后，B 的 replay 看不到 A 的任务（owner 不匹配）。任务「归属」于创建它的 session。
+
+### 为什么找不到 `scheduler.json`
+
+当前版本**不写** `scheduler.json`。如果你在文档或旧讨论里看到 `scheduler.json`，那是指**已废弃的旧版 store 格式**（npm 0.1.1 及更早），仅用于一次性迁移探测（见下文「旧版数据迁移」）。不要试图手动编辑或查找该文件来管理当前任务。
+
+## 旧版数据迁移
+
+旧版（npm ≤ 0.1.1）用独立 store 文件，按 **cwd 隔离**存储：
+
+```
+<agentDir>/scheduler/<root>/<segments>/scheduler.json
+```
+
+- `<agentDir>` = `getAgentDir()`（候选 1）或 `~/.pi/agent`（候选 2，旧版硬编码）。
+- `<root>` = cwd 根盘符 sanitize：mac/linux 的 `/` → `root`；Windows `C:\` → `c`（非字母数字转 `-`，trim 首尾，小写）。
+- `<segments>` = cwd 去根盘符后的路径段，按 `path.sep` 拆分。例 cwd `/Users/foo/project` → `Users/foo/project`。
+- 完整示例（mac）：`~/.pi/agent/scheduler/root/Users/foo/project/scheduler.json`。
+
+**迁移机制**（`importLegacyStore`，session_start 时自动执行，无需用户介入）：
+
+1. 双候选探测：优先 `getAgentDir()` 路径，不存在则 fallback `~/.pi/agent/scheduler/...`（兼容 xyz-agent 数据目录隔离前的旧版写入位置）。
+2. 原子 rename `scheduler.json` → `scheduler.json.imported` 独占迁移；rename 抛 ENOENT 说明并发/崩溃已被别人处理，走 `.imported` 残留恢复。
+3. 读取 `.imported`，逐任务 `appendEntry('pi-scheduler:task', upsert)` 写入当前 session（owner 归属当前 session）。
+4. 删除 `.imported`：**新 session 首次 flush 前（尚未收到 assistant 消息）延迟删除**，由首个 `turn_end` / `session_shutdown` 确认 flush 后再删（防未 flush 即退出导致任务永久丢失 + 源文件已毁）。
+5. 迁移失败（read/parse/append 异常）整体降级：`console.warn` + 不阻断 session 启动，`.imported` 保留供下次重试。
+
+迁移是一次性的：迁移完成后旧 `scheduler.json` 已被 rename 走并删除，后续 session 不再有旧格式数据。
+
+## 运行限制与 dispatch 行为
+
+| 限制 | 值 | 含义 |
+|------|-----|------|
+| 每 session 任务数上限 | 50（`MAX_TASKS`） | 超出创建报错 `Task limit reached` |
+| dispatch 速率 | 6 次/分钟（`RATE_LIMIT_PER_MINUTE`） | 滑动窗口计数，超出则当前 tick 跳过、下个 tick 重试 |
+| tick 间隔 | 30 秒（`TICK_INTERVAL_MS`） | 每 30 秒检查一次到期任务 |
+| 默认过期 | 7 天（`DEFAULT_EXPIRY_MS`） | 仅 recurring；`expires="never"` 关闭 |
+| 历史记录 | 最近 20 条（`HISTORY_LIMIT`） | 每任务的执行历史 |
+
+dispatch 触发条件（`dispatchTask`）：
+
+- **非 force 任务**：仅在 `ctx.isIdle() && !ctx.hasPendingMessages()` 时触发；否则**延迟到下个 tick**（不丢弃，标记 `pending`，下个 30s tick 重试）。
+- **force=true 任务**：即使 agent busy 也立即触发（用于必须准点执行的场景）。
+- dispatch 成功后：recurring 推进 `nextRunAt` 并 append `advance`；once 删除任务并 append `delete`；失败（`sendMessage` 抛错）记 `lastStatus='failed'` 不 rethrow，下个 tick 重试（transient 失败重试语义，不 append advance）。
+- 注入的消息：`{content: task.prompt, customType: 'pi-scheduler:dispatched', display: true}`，`deliverAs: 'followUp'` + `triggerTurn: true`（排进 followUp 队列并唤醒 agent 开新 turn）。
+
+## 任务数据结构
+
+`ScheduledTask`（内存态，`types.ts`）核心字段：
+
+- `id`：8 位 hex，自动生成。
+- `name`：可读名称（用户指定或从 prompt 自动截取前 30 字）。
+- `prompt`：到期注入的 message 内容。
+- `kind`：`once` | `recurring`。
+- `schedule`：`{mode:'cron', cronExpression}` | `{mode:'interval', intervalMs}`。
+- `enabled`：是否启用。
+- `force`：是否在 agent busy 时强制 dispatch。
+- `createdAt` / `nextRunAt` / `expiresAt?`：时间戳（ms）。
+- `runCount` / `lastRunAt?` / `lastStatus?`（`success`|`failed`）/ `lastError?`：执行统计。
+- `history`：最近 20 条 `ExecutionRecord`（`{at, status, snippet?}`，snippet 为 agent 回复前 100 字）。
+- `ownerSessionFile?`：归属 session JSONL 路径（fork 过滤用，非持久化业务字段）。
+- `pending?`：运行时标记「到期待 dispatch」，非持久化（与 `enabled` 正交）。
+
+持久化写入 session JSONL 的是 `TaskSnapshot`（剥离 `ownerSessionFile`/`pending` 后的 15 字段）。
+
+## 示例
+
+创建一个每 5 分钟检查构建状态的任务：
+
+```
+/schedule 5m 检查当前项目的构建状态，失败则报告原因
+```
+
+创建 2 小时后的一次性提醒：
+
+```
+/schedule once 2h 提醒我 review 这个 PR
+```
+
+创建每 30 分钟跑测试的 cron 任务（注意引号）：
+
+```
+/schedule cron '*/30 * * * *' 跑一次 vitest 并报告结果
+```
+
+创建工作日早 9 点的早会提醒（不过期、force）：
+
+```
+/schedule cron '0 9 * * 1-5' 早会时间到了，总结昨天进展和今天计划
+```
+（如需 force + 不过期，用 `schedule` 工具传 `force:true, expires:"never"`，命令行暂未暴露这两个开关）
+
+列出并禁用某任务：
+
+```
+/schedule list
+/schedule off abc12345
+```
+
+AI 通过工具创建（force + 永不过期）：
+
+```
+schedule({ prompt: "...", schedule: "1h", kind: "recurring", force: true, expires: "never", name: " hourly-check" })
+```
+
+## 备注
+
+- **croner 依赖**：cron 模式依赖 `croner`（peerDependency）。未安装时所有 cron 任务解析失败（返回 `INVALID_SCHEDULE`），interval 任务不受影响。集成方（如 xyz-agent mandatory 安装）需确保 `croner` 可用。
+- **数据目录隔离**：任务存储在 `getAgentDir()` 指向的 session JSONL。xyz-agent 通过 `XYZ_AGENT_DATA_DIR` / `PI_CODING_AGENT_DIR` 隔离实例时，任务随 session 落在隔离目录，与 `~/.pi/agent` 互不干扰。
+- **无配置 schema 可编辑**：scheduler 的所有状态都由运行时命令产生，没有可手动编辑的配置文件。要「批量预置任务」只能在 session 内逐条创建（或迁移旧 store）。
+- **TUI 管理器未实现**：无参 `/schedule` 当前只返回提示，任务管理请用 `list`/`on`/`off`/`rm`/`run` 子命令或 `schedule_control` 工具。

package/src/__tests__/importer.test.ts

@@ -1,4 +1,6 @@
 import * as fs from 'node:fs'
+import * as os from 'node:os'
+import * as path from 'node:path'
 
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
@@ -281,3 +283,29 @@ describe('importLegacyStore', () => {
     expect(cleanup).toBeUndefined()
   })
 })
+
+// ── getLegacyStorePath 双候选探测（合并 feat-auto-name-session-refactor 4b5513b5e 后落实）──
+// 候选 1：getAgentDir()（PI_CODING_AGENT_DIR 隔离目录）；候选 2：已发布版 npm 0.1.1 硬编码
+// ~/.pi/agent。getAgentDir() 每次调用读 process.env（非模块加载缓存），stubEnv 后直接调用即可。
+// fs 已 mock（模块顶部 vi.mock('node:fs')），existsSync 控制探测命中。
+describe('getLegacyStorePath 双候选探测', () => {
+  afterEach(() => {
+    vi.unstubAllEnvs()
+  })
+
+  it('TC10a: PI_CODING_AGENT_DIR 隔离目录下旧 store 存在 → 优先 getAgentDir() 路径', () => {
+    vi.stubEnv('PI_CODING_AGENT_DIR', '/tmp/iso-agent')
+    const isoPath = path.join('/tmp/iso-agent', 'scheduler', 'root', 'fake', 'workspace', 'scheduler.json')
+    vi.mocked(fs.existsSync).mockImplementation(p => p === isoPath)
+
+    expect(getLegacyStorePath(cwd)).toBe(isoPath)
+  })
+
+  it('TC10b: 隔离目录下旧 store 不存在 → fallback 已发布版 ~/.pi/agent 路径', () => {
+    vi.stubEnv('PI_CODING_AGENT_DIR', '/tmp/iso-agent')
+    vi.mocked(fs.existsSync).mockReturnValue(false)
+    const legacyPath = path.join(os.homedir(), '.pi', 'agent', 'scheduler', 'root', 'fake', 'workspace', 'scheduler.json')
+
+    expect(getLegacyStorePath(cwd)).toBe(legacyPath)
+  })
+})

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

@@ -0,0 +1,171 @@
+// src/__tests__/index-generation.test.ts
+//
+// G1（S9 review 修复 / R3-M1 模块级化）集成单测：index.ts 装配点为每代 SchedulerRuntime
+// 注入代际检测回调（模块级 sessionGeneration 比对），使 stale 分诊不依赖 pi 错误文案。
+//
+// 两类拓扑：
+// - 同闭包重复 fire session_start（rpc-mode bindExtensions 重调等次要路径）——第一组用例
+//   在同一 factory 闭包上连续触发验证代数接线。
+// - factory 重跑（生产主路径：pi 每次 session 替换 newSession/fork/switchSession 都重跑
+//   factory 函数体，loader.ts extensionCache 只缓存 factory 函数对象不缓存执行结果）——
+//   装配级用例模拟两次独立 factory() 调用（各自新闭包、共享模块级代数），实证模块级变量
+//   跨 factory 重跑保留：第二代 session_start 递增模块级计数器后，第一代 runtime 的
+//   isCtxStale 翻转为 true 且其泄漏 timer 在下个 tick 前置检查自停。闭包级实现（R3-M1
+//   修复前）在此拓扑下恒 false——正是被 R3 实测证伪的生产失效路径。
+//
+// 本文件用 InstrumentedRuntime（继承真实 SchedulerRuntime，仅记录构造第三参 isCtxStale）
+// 捕获注入回调。InstrumentedRuntime 全部行为继承父类，不影响装配链本身（F1 停旧 timer
+// 等行为由 index-session-start.test.ts U4 锚定，此处不重复）。
+
+import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+// 与 index-session-start.test.ts 同款（MF-3）：mock 掉 importer，装配路径仍被调用、FS 副作用为零。
+vi.mock('../importer.js', () => ({ importLegacyStore: vi.fn(() => vi.fn()) }))
+
+// vi.mock factory 会被提升，跨模块共享状态必须经 vi.hoisted。
+const { isCtxStaleCaptures, runtimeInstances } = vi.hoisted(() => ({
+  isCtxStaleCaptures: [] as Array<(() => boolean) | undefined>,
+  runtimeInstances: [] as Array<{ stopScheduler(): void }>,
+}))
+
+// InstrumentedRuntime 继承真实实现（loadTasks/onAfterTick/startScheduler 均真实执行），
+// 仅捕获构造第三参并登记实例（afterEach 统一停 timer，避免真实 setInterval 残留）。
+vi.mock('../runtime.js', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('../runtime.js')>()
+  const RealSchedulerRuntime = actual.SchedulerRuntime
+  class InstrumentedRuntime extends RealSchedulerRuntime {
+    constructor(
+      backend: ConstructorParameters<typeof RealSchedulerRuntime>[0],
+      ctx: ConstructorParameters<typeof RealSchedulerRuntime>[1],
+      isCtxStale?: () => boolean,
+    ) {
+      super(backend, ctx, isCtxStale)
+      isCtxStaleCaptures.push(isCtxStale)
+      runtimeInstances.push(this)
+    }
+  }
+  return { ...actual, SchedulerRuntime: InstrumentedRuntime }
+})
+
+import schedulerExtension from '../index.js'
+
+const TICK_INTERVAL_MS = 30_000
+
+/**
+ * 最小 fake pi：与 index-session-start.test.ts 同款，覆盖 factory 消费的 API 面
+ * （on 捕获事件 handler 供手动触发；registerTool/registerCommand/sendMessage/appendEntry 兜底）。
+ */
+function createMockPi(): {
+  pi: ExtensionAPI
+  events: Map<string, (...args: unknown[]) => void>
+} {
+  const events = new Map<string, (...args: unknown[]) => void>()
+  const pi = {
+    registerTool: vi.fn(),
+    registerCommand: vi.fn(),
+    on: (event: string, handler: (...args: unknown[]) => void) => events.set(event, handler),
+    sendMessage: vi.fn(),
+    appendEntry: vi.fn(),
+  } as unknown as ExtensionAPI
+  return { pi, events }
+}
+
+/** 最小 fake ctx：覆盖 session_start 装配链读到的全部字段（backend 构造 / runtime 构造 / refreshWidget）。 */
+function createFakeCtx(sessionFile: string): ExtensionContext {
+  return {
+    cwd: '/test-index-generation',
+    isIdle: () => true,
+    hasPendingMessages: () => false,
+    ui: { setWidget: vi.fn() },
+    sessionManager: {
+      getEntries: () => [],
+      getSessionFile: () => sessionFile,
+    },
+  } as unknown as ExtensionContext
+}
+
+describe('G1: index.ts 代际接线（S9）', () => {
+  beforeEach(() => {
+    isCtxStaleCaptures.length = 0
+    runtimeInstances.length = 0
+  })
+
+  afterEach(() => {
+    for (const rt of runtimeInstances) {
+      rt.stopScheduler()
+    }
+  })
+
+  it('每次 session_start 注入 isCtxStale：当前代 false、任意前代 true（跨三代）', () => {
+    const { pi, events } = createMockPi()
+    schedulerExtension(pi)
+    const sessionStart = events.get('session_start')
+    expect(sessionStart).toBeDefined()
+
+    // 第 1 代
+    sessionStart!({ type: 'session_start', reason: 'startup' }, createFakeCtx('/test/gen-1.json'))
+    expect(isCtxStaleCaptures[0]).toBeTypeOf('function')
+    expect(isCtxStaleCaptures[0]!()).toBe(false) // 当前代未替换
+
+    // 第 2 代（session 替换）：第 1 代自此 stale，第 2 代为当前代
+    sessionStart!({ type: 'session_start', reason: 'new_session' }, createFakeCtx('/test/gen-2.json'))
+    expect(isCtxStaleCaptures[0]!()).toBe(true)
+    expect(isCtxStaleCaptures[1]!()).toBe(false)
+
+    // 第 3 代（resume 重入）：前两代均 stale
+    sessionStart!({ type: 'session_start', reason: 'resume' }, createFakeCtx('/test/gen-3.json'))
+    expect(isCtxStaleCaptures[0]!()).toBe(true)
+    expect(isCtxStaleCaptures[1]!()).toBe(true)
+    expect(isCtxStaleCaptures[2]!()).toBe(false)
+  })
+
+  // ── R3-M1/R3-S5：factory 重跑装配级用例（生产主路径拓扑）──
+  // pi 每次 session 替换都重跑 factory 函数体（新闭包）。本用例模拟两次独立 factory()
+  // 调用 + 各 fire 一次 session_start，实证「模块级 sessionGeneration 跨 factory 重跑保留」：
+  // 闭包级实现（修复前）在第二代 session_start 后 firstStale() 仍恒 false——测试即失败。
+  it('factory 重跑：第二次 factory 执行 + session_start 后，第一代 runtime isCtxStale 为 true 且 tick 前置自停', async () => {
+    vi.useFakeTimers()
+    vi.setSystemTime(new Date('2026-01-01T00:00:00Z'))
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    try {
+      // 第一代：独立 factory 执行 + session_start 装配（runtime1 真实 startScheduler）
+      const first = createMockPi()
+      schedulerExtension(first.pi)
+      const firstSessionStart = first.events.get('session_start')
+      expect(firstSessionStart).toBeDefined()
+      firstSessionStart!({ type: 'session_start', reason: 'startup' }, createFakeCtx('/test/factory-rerun-1.json'))
+      const firstStale = isCtxStaleCaptures[0]!
+      expect(firstStale).toBeTypeOf('function')
+      expect(firstStale()).toBe(false) // 第一代是当前代
+
+      // 第二代：再次独立执行 factory（模拟 newSession/fork/switchSession 的 factory 重跑，
+      // 新闭包的 service 为 null——第一代闭包的 service 对它不可见，F1 停不到第一代 timer，
+      // 复现「F1 未能触达、只剩 G1 前置检查」的泄漏路径）+ session_start
+      const second = createMockPi()
+      schedulerExtension(second.pi)
+      const secondSessionStart = second.events.get('session_start')
+      expect(secondSessionStart).toBeDefined()
+      secondSessionStart!({ type: 'session_start', reason: 'new_session' }, createFakeCtx('/test/factory-rerun-2.json'))
+
+      // 核心断言：模块级计数器被第二代闭包的 session_start 递增，第一代 runtime 的
+      // isCtxStale 生效（闭包级实现在此恒 false——R3-M1 修复的生产失效路径）
+      expect(firstStale()).toBe(true)
+      expect(isCtxStaleCaptures[1]!()).toBe(false) // 第二代是当前代
+
+      // tick 前置自停：第一代 runtime 的泄漏 timer 在下个 tick 被代际前置检查拦截
+      // （G1-b 的生产路径验证：warn "tick stopped" + timer 自停，后续 tick 不再发生）
+      await vi.advanceTimersByTimeAsync(TICK_INTERVAL_MS)
+      const warnText = warnSpy.mock.calls.map(c => String(c[0])).join('\n')
+      expect(warnText).toContain('tick stopped')
+      expect(warnText).not.toContain('tick error')
+
+      const warnCountAfterSelfStop = warnSpy.mock.calls.length
+      await vi.advanceTimersByTimeAsync(TICK_INTERVAL_MS * 2) // timer 已停，无新 warn
+      expect(warnSpy.mock.calls.length).toBe(warnCountAfterSelfStop)
+    } finally {
+      warnSpy.mockRestore()
+      vi.useRealTimers()
+    }
+  })
+})

package/src/__tests__/index-session-start.test.ts

@@ -0,0 +1,107 @@
+// src/__tests__/index-session-start.test.ts
+//
+// F1 集成单测（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）：第二次 session_start 后 advance 30s，tick 引起的 widget 刷新
+// 增量恰 +1（只有新 runtime 的 timer 在跑）；F1 缺失时两个 timer 都活着，增量为 +2。
+// 观测面说明：session_start 硬编码 new PiSchedulerBackend（now() = Date.now()，无法注入计数），
+// 故用 onAfterTick → refreshWidget → ctx.ui.setWidget 的调用计数作为 tick 发生次数的
+// 行为观测面（每个 tick 恰好一次，与 backend.now 计数等价）。
+
+import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+// 与 sdk-contract.test.ts 同款（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()) }))
+
+import schedulerExtension from '../index.js'
+
+const TICK_INTERVAL_MS = 30_000
+
+/**
+ * 最小 fake pi：覆盖 index.ts factory + commands.ts 注册路径消费的 API 面
+ * （on / registerTool / registerCommand / sendMessage / appendEntry）。
+ * on 捕获事件 handler 供手动触发；sendMessage/appendEntry 为 vi.fn 兜底（本套件无任务 dispatch）。
+ */
+function createMockPi(): {
+  pi: ExtensionAPI
+  events: Map<string, (...args: unknown[]) => void>
+} {
+  const events = new Map<string, (...args: unknown[]) => void>()
+  const pi = {
+    registerTool: vi.fn(),
+    registerCommand: vi.fn(),
+    on: (event: string, handler: (...args: unknown[]) => void) => events.set(event, handler),
+    sendMessage: vi.fn(),
+    appendEntry: vi.fn(),
+  } as unknown as ExtensionAPI
+  return { pi, events }
+}
+
+/**
+ * 最小 fake ctx：覆盖 session_start 装配链读到的全部字段——PiSchedulerBackend 构造
+ * （sessionManager）、SchedulerRuntime 构造（isIdle/hasPendingMessages）、importLegacyStore
+ * （cwd，已 mock）、refreshWidget（ui.setWidget）。
+ * setWidget 以独立引用导出：session_start 初始渲染 + 每次 tick 末 onAfterTick 各调一次，
+ * 是「哪个 runtime 的 timer 还在 tick」的行为观测面。
+ */
+function createFakeCtx(sessionFile: string): {
+  ctx: ExtensionContext
+  setWidget: ReturnType<typeof vi.fn>
+} {
+  const setWidget = vi.fn()
+  const ctx = {
+    cwd: '/test-index-session-start',
+    isIdle: () => true,
+    hasPendingMessages: () => false,
+    ui: { setWidget },
+    sessionManager: {
+      getEntries: () => [],
+      getSessionFile: () => sessionFile,
+    },
+  } as unknown as ExtensionContext
+  return { ctx, setWidget }
+}
+
+describe('F1: session_start 停旧 runtime（crash-fix U4）', () => {
+  beforeEach(() => {
+    vi.useFakeTimers()
+    vi.setSystemTime(new Date('2026-01-01T00:00:00Z'))
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  it('U4: 双 session_start 后旧 timer 已停——advance 30s tick 引起的刷新恰 +1 而非 +2', async () => {
+    const { pi, events } = createMockPi()
+    schedulerExtension(pi)
+    const sessionStart = events.get('session_start')
+    expect(sessionStart).toBeDefined()
+
+    // 第一次 session_start：runtime1 + timer1 启动，初始渲染 1 次
+    const first = createFakeCtx('/test/session-1.json')
+    sessionStart!({ type: 'session_start', reason: 'startup' }, first.ctx)
+    expect(first.setWidget).toHaveBeenCalledTimes(1)
+
+    // 前置因果锚点：advance 30s，timer1 正常 tick 一次（排除「timer 从未启动」的假绿）
+    await vi.advanceTimersByTimeAsync(TICK_INTERVAL_MS)
+    expect(first.setWidget).toHaveBeenCalledTimes(2)
+
+    // 第二次 session_start（session 替换）：F1 在装配新 runtime 前停掉 timer1
+    const second = createFakeCtx('/test/session-2.json')
+    sessionStart!({ type: 'session_start', reason: 'new_session' }, second.ctx)
+    expect(second.setWidget).toHaveBeenCalledTimes(1) // runtime2 初始渲染
+
+    // 行为断言（验收口径）：再 advance 30s，只有 runtime2 的 timer 触发一次 tick——
+    // F1 缺失时 timer1/timer2 都活着，first 与 second 的 spy 各 +1（合计 +2）
+    await vi.advanceTimersByTimeAsync(TICK_INTERVAL_MS)
+    expect(second.setWidget).toHaveBeenCalledTimes(2) // 恰 +1：新 runtime 正常调度
+    expect(first.setWidget).toHaveBeenCalledTimes(2) // 旧 runtime 的 tick 不再发生（timer 已停）
+  })
+})

package/src/__tests__/runtime.test.ts

@@ -162,6 +162,77 @@ describe('SchedulerRuntime', () => {
     })
   })
 
+  // ── R3-S1：dispatchTask in-flight 守卫 ──
+  // tick 为 fire-and-forget：tick1 的 await sendMessage 挂起超过 TICK_INTERVAL_MS（如 pi
+  // 卡死）时，tick2 的 step2 再标 pending → step3 对同一 task 并发第二个 dispatch → 同一
+  // prompt 双注入（force 任务绕过 isIdle gate 直接受影响）。守卫：同任务在途（Set<taskId>）
+  // 时 skip 本轮并 warn；不同任务不受影响。
+  describe('dispatchTask in-flight 守卫（R3-S1）', () => {
+    beforeEach(() => {
+      vi.useFakeTimers()
+      vi.setSystemTime(new Date('2026-01-01T00:00:00Z'))
+    })
+
+    afterEach(() => {
+      vi.useRealTimers()
+    })
+
+    it('sendMessage 挂起期间下一 tick 同任务被跳过：不双注入、warn in-flight、完成后 runCount=1', async () => {
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+      let resolveSend: (() => void) | undefined
+      const sendPromise = new Promise<void>(resolve => { resolveSend = resolve })
+      backend.sendMessage = vi.fn(() => sendPromise)
+
+      const task = await runtime.addTask('in-flight', { mode: 'interval', intervalMs: 60000 }, { force: true })
+      task.nextRunAt = Date.now() - 1000
+
+      // tick1：dispatch 进入 sendMessage 挂起（同步段已置 in-flight 标记）
+      const tick1 = runtime.tickScheduler()
+      expect(backend.sendMessage).toHaveBeenCalledTimes(1)
+      expect(task.pending).toBe(true) // dispatch 未完成，pending 未清
+
+      // tick2（模拟 30s 后 pi 仍卡死）：同任务再标 pending → step3 dispatchTask 命中
+      // in-flight 守卫 → skip + warn（修复前：同一 prompt 双注入）
+      await runtime.tickScheduler()
+      expect(backend.sendMessage).toHaveBeenCalledTimes(1)
+      const warnText = warnSpy.mock.calls.map(c => String(c[0])).join('\n')
+      expect(warnText).toContain('already in flight')
+
+      // 放行挂起的 sendMessage：tick1 正常收尾（状态推进恰好一次）
+      resolveSend!()
+      await tick1
+      expect(backend.sendMessage).toHaveBeenCalledTimes(1)
+      expect(task.runCount).toBe(1)
+      expect(task.pending).toBe(false)
+      warnSpy.mockRestore()
+    })
+
+    it('挂起 dispatch 只挡同任务：其他任务在下一 tick 正常 dispatch 不受影响', async () => {
+      let resolveSend: (() => void) | undefined
+      const sendPromise = new Promise<void>(resolve => { resolveSend = resolve })
+      backend.sendMessage = vi.fn(() => sendPromise)
+
+      const task1 = await runtime.addTask('first', { mode: 'interval', intervalMs: 60000 }, { force: true })
+      const task2 = await runtime.addTask('second', { mode: 'interval', intervalMs: 60000 }, { force: true })
+      task1.nextRunAt = Date.now() - 1000
+      task2.nextRunAt = Date.now() - 1000
+
+      // tick1：task1 dispatch 挂起（step3 顺序 await，task2 尚未轮到）
+      const tick1 = runtime.tickScheduler()
+      expect(backend.sendMessage).toHaveBeenCalledTimes(1)
+
+      // tick2：task1 命中守卫跳过，task2 无在途 → 正常 dispatch（守卫按 taskId 粒度隔离）。
+      // 注：tick2 挂起在 task1 的 await dispatchTask（守卫命中即 resolved promise）与 task2
+      // 的 await sendMessage 上，先放行再 await，完成态统一断言
+      const tick2 = runtime.tickScheduler()
+      resolveSend!()
+      await Promise.all([tick1, tick2])
+      expect(backend.sendMessage).toHaveBeenCalledTimes(2)
+      expect(task1.runCount).toBe(1)
+      expect(task2.runCount).toBe(1)
+    })
+  })
+
   // ── M10b：rate-limit ──
   // dispatchTask 受 RATE_LIMIT_PER_MINUTE=6 限制。前 6 次成功（sendMessage 被调），
   // 第 7 次被 hasDispatchCapacity 拒绝（dispatchTimestamps.length 已达 6）。
@@ -463,4 +534,199 @@ describe('SchedulerRuntime', () => {
       expect(task.expiresAt).toBeUndefined()
     })
   })
+
+  // ── F2：tick 错误分诊（crash-fix）──
+  // startScheduler 的 interval 回调对 fire-and-forget 的 tickScheduler() 加 catch：
+  // stale 类错误（session 替换后泄漏 timer 访问 stale ctx）→ warn "tick stopped" + stopScheduler
+  // 自停；其他错误 → warn "tick error" 继续调度。修复前 tick 内异常无人接住 →
+  // unhandledRejection → pi 主进程 exit 1。
+  describe('tick 错误分诊（F2）', () => {
+    const TICK_INTERVAL_MS = 30_000
+
+    beforeEach(() => {
+      vi.useFakeTimers()
+      vi.setSystemTime(new Date('2026-01-01T00:00:00Z'))
+    })
+
+    afterEach(() => {
+      runtime.stopScheduler()
+      vi.useRealTimers()
+    })
+
+    it('U1: stale 错误 → warn "tick stopped" + timer 自停，后续 tick 不再发生', async () => {
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+      const nowSpy = vi.spyOn(backend, 'now')
+      runtime.onAfterTick(() => {
+        throw new Error('This extension ctx is stale after session replacement or reload.')
+      })
+
+      runtime.startScheduler()
+      await vi.advanceTimersByTimeAsync(TICK_INTERVAL_MS) // tick1：stale 抛 → catch 分诊 → 自停
+
+      const warnText = warnSpy.mock.calls.map(c => String(c[0])).join('\n')
+      expect(warnText).toContain('tick stopped')
+      expect(warnText).not.toContain('tick error')
+
+      const countAfterSelfStop = nowSpy.mock.calls.length
+      expect(countAfterSelfStop).toBeGreaterThan(0) // tick1 确实跑过（排除「timer 未启动」假绿）
+
+      await vi.advanceTimersByTimeAsync(TICK_INTERVAL_MS * 2) // 60s：timer 已停，无新 tick
+      expect(nowSpy.mock.calls.length).toBe(countAfterSelfStop) // now 计数不再增长
+      warnSpy.mockRestore()
+      nowSpy.mockRestore()
+    })
+
+    it('U2: 非 stale 错误 → warn "tick error" 且调度继续（advance 两次 now 计数 +2）', async () => {
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+      const nowSpy = vi.spyOn(backend, 'now')
+      runtime.onAfterTick(() => {
+        throw new Error('boom')
+      })
+
+      runtime.startScheduler()
+      await vi.advanceTimersByTimeAsync(TICK_INTERVAL_MS) // tick1：warn 但不停
+
+      const warnText = warnSpy.mock.calls.map(c => String(c[0])).join('\n')
+      expect(warnText).toContain('tick error')
+      expect(warnText).not.toContain('tick stopped')
+
+      const countAfterFirstTick = nowSpy.mock.calls.length
+      expect(countAfterFirstTick).toBeGreaterThan(0)
+
+      await vi.advanceTimersByTimeAsync(TICK_INTERVAL_MS * 2) // 2 个后续 tick 照常
+      expect(nowSpy.mock.calls.length).toBe(countAfterFirstTick + 2)
+      warnSpy.mockRestore()
+      nowSpy.mockRestore()
+    })
+
+    it('U5: stopScheduler 幂等——连续调用两次不抛、无副作用', () => {
+      runtime.startScheduler()
+      expect(() => {
+        runtime.stopScheduler()
+        runtime.stopScheduler()
+      }).not.toThrow()
+    })
+  })
+
+  // ── G1：代际检测分诊（S9 review 修复 / R3-M1 模块级化）──
+  // isCtxStale（index.ts 注入的模块级代数比对）为主判，替代对 pi 错误文案的依赖：
+  // - G1-a：in-flight tick 内代际翻转 + 任意非文案错误 → catch 分诊走 stale 自停（不依赖文案）
+  // - G1-b：代际翻转后（无任何错误）泄漏 timer 在下个 tick 前置检查自停，不进入 tick
+  // - G1-c：显式注入 isCtxStale=false + 非 stale 错误 → 仍 "tick error" 继续调度（不误伤）
+  // - G1-d：isCtxStale=false 但错误文案含 stale 片段 → 文案兜底仍自停（覆盖 reload 盲区：
+  //   clearExtensionCache 后 jiti 重 import 全新模块环境，旧闭包的模块级代数冻结不再递增，
+  //   只剩文案能识别 stale；模块级方案的装配级验证见 index-generation.test.ts factory 重跑用例）
+  describe('G1: 代际检测分诊（S9）', () => {
+    const TICK_INTERVAL_MS = 30_000
+    let staleFlag: boolean
+    let genRuntime: SchedulerRuntime
+
+    beforeEach(() => {
+      vi.useFakeTimers()
+      vi.setSystemTime(new Date('2026-01-01T00:00:00Z'))
+      staleFlag = false
+      genRuntime = new SchedulerRuntime(backend, mockCtx, () => staleFlag)
+    })
+
+    afterEach(() => {
+      genRuntime.stopScheduler()
+      vi.useRealTimers()
+    })
+
+    it('G1-a: in-flight tick 期间代际翻转 + 非文案错误 → warn "tick stopped" + 自停（不依赖 pi 错误文案）', async () => {
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+      const nowSpy = vi.spyOn(backend, 'now')
+      // tick 内先翻世代（模拟 session 替换交错发生在 dispatch await 窗口），再抛与
+      // pi 文案完全无关的错误——旧实现按文案分诊会误判为普通错误继续调度（若 pi 改文案）
+      genRuntime.onAfterTick(() => {
+        staleFlag = true
+        throw new Error('some unexpected failure')
+      })
+
+      genRuntime.startScheduler()
+      await vi.advanceTimersByTimeAsync(TICK_INTERVAL_MS) // tick1：catch 分诊走 G1 代际 → 自停
+
+      const warnText = warnSpy.mock.calls.map(c => String(c[0])).join('\n')
+      expect(warnText).toContain('tick stopped')
+      expect(warnText).not.toContain('tick error')
+
+      const countAfterSelfStop = nowSpy.mock.calls.length
+      expect(countAfterSelfStop).toBeGreaterThan(0) // tick1 确实跑过（排除「timer 未启动」假绿）
+
+      await vi.advanceTimersByTimeAsync(TICK_INTERVAL_MS * 2) // timer 已停，无新 tick
+      expect(nowSpy.mock.calls.length).toBe(countAfterSelfStop)
+      warnSpy.mockRestore()
+      nowSpy.mockRestore()
+    })
+
+    it('G1-b: 代际翻转后泄漏 timer 在下个 tick 前置检查自停——不进入 tick（backend.now 零调用）', async () => {
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+      const nowSpy = vi.spyOn(backend, 'now')
+      genRuntime.startScheduler()
+      // session 替换：代际翻转（F1 未能触达的泄漏 timer 场景；无任何错误发生）
+      staleFlag = true
+
+      await vi.advanceTimersByTimeAsync(TICK_INTERVAL_MS) // tick1：前置检查命中 → 自停
+
+      const warnText = warnSpy.mock.calls.map(c => String(c[0])).join('\n')
+      expect(warnText).toContain('tick stopped')
+      expect(warnText).not.toContain('tick error')
+      // 前置检查在 tickScheduler 之前拦截：tick 本体未执行（now 零调用，无 dispatch/append）
+      expect(nowSpy).not.toHaveBeenCalled()
+
+      await vi.advanceTimersByTimeAsync(TICK_INTERVAL_MS * 2) // timer 已停，仍零调用
+      expect(nowSpy).not.toHaveBeenCalled()
+      warnSpy.mockRestore()
+      nowSpy.mockRestore()
+    })
+
+    it('G1-c: isCtxStale 注入但返回 false + 非 stale 错误 → warn "tick error" 且调度继续', async () => {
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+      const nowSpy = vi.spyOn(backend, 'now')
+      // staleFlag 恒 false（beforeEach 初始化）：代际未翻转，注入存在不改变分诊结果
+      genRuntime.onAfterTick(() => {
+        throw new Error('boom')
+      })
+
+      genRuntime.startScheduler()
+      await vi.advanceTimersByTimeAsync(TICK_INTERVAL_MS) // tick1：非 stale → warn 继续调度
+
+      const warnText = warnSpy.mock.calls.map(c => String(c[0])).join('\n')
+      expect(warnText).toContain('tick error')
+      expect(warnText).not.toContain('tick stopped')
+
+      const countAfterFirstTick = nowSpy.mock.calls.length
+      expect(countAfterFirstTick).toBeGreaterThan(0)
+
+      await vi.advanceTimersByTimeAsync(TICK_INTERVAL_MS * 2) // 2 个后续 tick 照常
+      expect(nowSpy.mock.calls.length).toBe(countAfterFirstTick + 2)
+      warnSpy.mockRestore()
+      nowSpy.mockRestore()
+    })
+
+    it('G1-d: isCtxStale 返回 false 但错误文案含 stale 片段 → 文案兜底仍自停（覆盖 reload 盲区）', async () => {
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+      const nowSpy = vi.spyOn(backend, 'now')
+      // reload 场景模拟：factory 重跑后旧闭包代际计数不再递增（staleFlag 恒 false），
+      // 只有错误文案能识别 stale——兜底支必须独立于代际检测生效
+      genRuntime.onAfterTick(() => {
+        throw new Error('This extension ctx is stale after session replacement or reload.')
+      })
+
+      genRuntime.startScheduler()
+      await vi.advanceTimersByTimeAsync(TICK_INTERVAL_MS) // tick1：文案兜底 → 自停
+
+      const warnText = warnSpy.mock.calls.map(c => String(c[0])).join('\n')
+      expect(warnText).toContain('tick stopped')
+      expect(warnText).not.toContain('tick error')
+
+      const countAfterSelfStop = nowSpy.mock.calls.length
+      expect(countAfterSelfStop).toBeGreaterThan(0)
+
+      await vi.advanceTimersByTimeAsync(TICK_INTERVAL_MS * 2)
+      expect(nowSpy.mock.calls.length).toBe(countAfterSelfStop)
+      warnSpy.mockRestore()
+      nowSpy.mockRestore()
+    })
+  })
 })

package/src/__tests__/service.test.ts

@@ -188,7 +188,7 @@ describe('SchedulerService', () => {
       expect(result).toEqual({
         success: false,
         errorCode: 'DISPATCH_SKIPPED',
-        message: `Task ${id} not dispatched (busy, disabled, or rate-limited).`,
+        message: `Task ${id} not dispatched (busy, disabled, rate-limited, or a dispatch already in flight).`,
       })
     })
 

package/src/importer.ts

@@ -2,26 +2,26 @@ import * as fs from 'node:fs'
 import * as os from 'node:os'
 import * as path from 'node:path'
 
+import { getAgentDir } from '@earendil-works/pi-coding-agent'
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
 
 import type { ScheduledTask, SchedulerEntryOp, SchedulerStore, TaskSnapshot } from './types.js'
 
 /**
- * 获取旧 store 文件路径：~/.pi/agent/scheduler/<root>/<segments>/scheduler.json。
+ * 获取旧 store 文件路径：scheduler/<root>/<segments>/scheduler.json，双候选探测。
  *
  * 内联自 store.ts getStorePath——store.ts 本 wave 删除后此函数是旧路径的唯一推导实现，
  * 不能 import 已删 store。workspace 路径隔离，不同 cwd 存不同文件。
  *
  * export 供测试推导期望路径（断言 renameSync/unlinkSync 参数）。
  *
- * ⚠️ 路径硬编码说明：硬编码 `~/.pi/agent/scheduler/` 是因为已发布版（npm 0.1.1）的 store.ts
- * 即用此路径，旧数据确在此处，必须按此路径探测才能迁移。注意分支 `feat-auto-name-session-refactor`
- * 的 commit 4b5513b5e 把 store 路径改为 getAgentDir()（读 PI_CODING_AGENT_DIR，用于 xyz-agent
- * 数据目录隔离）；该分支合并后此处需改为双候选路径探测（先 getAgentDir() 再 fallback ~/.pi/agent），
- * 否则 xyz-agent 隔离目录下的旧任务探测不到。
+ * 双候选探测（合并 feat-auto-name-session-refactor 分支 4b5513b5e 后落实）：
+ * 候选 1 用 pi 的 getAgentDir()（读 PI_CODING_AGENT_DIR，xyz-agent 数据目录隔离时指向隔离目录），
+ * 候选 2 是已发布版（npm 0.1.1）store.ts 的硬编码 `~/.pi/agent/scheduler/`。探测规则：
+ * 候选 1 存在则用候选 1（隔离实例的旧任务），否则 fallback 候选 2（0.1.1 版写入的真实数据源，
+ * 必须按此路径探测才能迁移）。getAgentDir() 未设置 env 时默认 ~/.pi/agent，两候选同路径，探测无副作用。
  */
 export function getLegacyStorePath(cwd: string): string {
-  const home = os.homedir()
   const resolved = path.resolve(cwd)
   const parsed = path.parse(resolved)
   const segments = resolved.slice(parsed.root.length)
@@ -30,7 +30,9 @@ export function getLegacyStorePath(cwd: string): string {
     .replaceAll(/[^a-zA-Z0-9]+/g, '-')
     .replaceAll(/^-+|-+$/g, '')
     .toLowerCase() || 'root'
-  return path.join(home, '.pi', 'agent', 'scheduler', root, ...segments, 'scheduler.json')
+  const agentDirPath = path.join(getAgentDir(), 'scheduler', root, ...segments, 'scheduler.json')
+  const legacyPath = path.join(os.homedir(), '.pi', 'agent', 'scheduler', root, ...segments, 'scheduler.json')
+  return fs.existsSync(agentDirPath) ? agentDirPath : legacyPath
 }
 
 /**

package/src/index.ts

@@ -17,6 +17,22 @@ import {
 } from './tool.js'
 import { renderSchedulerWidget } from './widget.js'
 
+// G1（代际检测，S9/R3-M1）：session 代际计数器。必须声明在模块级而非 factory 体内：
+// pi 每次 session 替换（newSession/fork/switchSession）都重跑 extension factory 函数体
+// （loader.ts loadExtension 无条件 `await factory(api)`；extensionCache 只缓存 factory
+// 函数对象、不缓存执行结果）——闭包级声明每次重跑即重置，各代 runtime 的 isCtxStale 恒
+// false（R3 实测证伪的回归）。模块级声明下，extensionCache 命中期间（同 cwd 未 reload）
+// factory 是同一函数对象、共享同一模块环境绑定，计数器跨 factory 重跑保留递增：新闭包的
+// session_start 递增本计数器，各代 runtime 构造时捕获的代数从此小于模块值 → isCtxStale
+// 生效——stale 分诊不依赖 pi 错误文案（Error message 非契约 API，pi 升级改文案即静默失效）。
+//
+// 残余盲区（reload）：显式 reload / cwd 变化触发 clearExtensionCache → jiti 重新 import
+// （moduleCache:false）产生全新模块环境，本计数器随新环境重置；旧闭包引用的是旧模块环境的
+// 绑定，永不再递增 → 其 isCtxStale 恒 false。该盲区由两道既有防线覆盖：pi 在替换前 await
+// fire session_shutdown（F1 stopScheduler 主防线，teardownCurrent）+ runtime 侧
+// STALE_CTX_MARKER 文案兜底（F2 catch 分诊）。
+let sessionGeneration = 0
+
 /**
  * pi-scheduler extension factory。
  * 注册 schedule + schedule_control 两个 tool、/schedule command、session 事件。
@@ -41,13 +57,24 @@ export default function schedulerExtension(pi: ExtensionAPI): void {
   }
 
   pi.on('session_start', (_event, ctx: ExtensionContext) => {
+    // G1：先递增模块级代数再装配——自此同模块环境内所有前代 runtime 的 isCtxStale 返回
+    // true（stale）。myGeneration 是本 handler 的代数，注入的比对闭包读实时模块级
+    // sessionGeneration 与之比较（factory 重跑的新闭包与本闭包共享同一模块绑定）。
+    sessionGeneration += 1
+    const myGeneration = sessionGeneration
+    // F1（治本）：session 替换/重入时先停上一代 runtime 的 tick interval——dispatch 的 await sendMessage
+    // 窗口与 session 替换交错时旧 session_shutdown 可能永远等不到（timer 泄漏源头）。stopScheduler 幂等，
+    // shutdown 已停过再停一次无副作用。
+    service?.runtime.stopScheduler()
     // 装配点：backend（ctx.sessionManager 读 entries / pi.appendEntry 写 op）→ runtime（内存态 + 调度）→ service（业务入口）
     const backend = new PiSchedulerBackend(ctx, pi)
     // 旧 store 原子导入（CL3 方案A）：必须在 backend.loadTasks() 之前执行——
     // append 的 upsert entry 进入 pi 内存 fileEntries，紧接的 loadTasks replay 统一重放读到导入任务。
     // ctx.cwd 类型为 string（SDK ExtensionContext 必填），无需 ?? process.cwd() 兜底（CL2）。
     importCleanup = importLegacyStore(ctx.cwd, pi, ctx.sessionManager.getSessionFile())
-    const runtime = new SchedulerRuntime(backend, ctx)
+    // G1：注入代际比对（本 runtime 建立时的代数 vs 实时代数），供 tick 前置检查与
+    // F2 catch 分诊判定 stale——不依赖 pi 错误文案。
+    const runtime = new SchedulerRuntime(backend, ctx, () => sessionGeneration !== myGeneration)
     runtime.loadTasks(backend.loadTasks())
     // W2：tick 后回调刷新 widget（替代独立 widgetTimer + setInterval，节奏对齐 TICK_INTERVAL_MS）
     runtime.onAfterTick(() => refreshWidget(ctx))

package/src/runtime.ts

@@ -16,6 +16,16 @@ const RATE_LIMIT_PER_MINUTE = 6
 const TICK_INTERVAL_MS = 30_000
 const DEFAULT_EXPIRY_MS = 7 * 24 * 60 * 60 * 1000 // 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'
 
 export class SchedulerRuntime {
   private tasks: Map<string, ScheduledTask> = new Map()
@@ -24,17 +34,26 @@ export class SchedulerRuntime {
   private tickTimer: ReturnType<typeof setInterval> | null = null
   private dispatchTimestamps: number[] = []
   private onAfterTickCallback: (() => void) | null = null
+  private readonly isCtxStale: (() => boolean) | undefined
+  // R3-S1：同任务 dispatch 在途标记（Set<taskId>），见 dispatchTask 注释
+  private readonly dispatchesInFlight = new Set<string>()
 
   /**
    * 依赖反转构造：backend 承担 appendEntry/pi.sendMessage/时间源，runtime 只持有内存态。
    * 不触碰任何 FS / session JSONL（测试可用 MockSchedulerBackend 零副作用注入）。
+   *
+   * isCtxStale（G1 代际检测，S9/R3-M1）：返回 true 表示本 runtime 建立时的 session 已被
+   * 替换。index.ts 装配点注入（模块级代数比对，R3-M1），使 stale 分诊不依赖 pi 错误文案；
+   * 缺省（不注入）恒视为非 stale——纯 runtime 单测与旧装配路径行为不变。
    */
   constructor(
     backend: SchedulerBackend,
     ctx: Pick<ExtensionContext, 'isIdle' | 'hasPendingMessages'>,
+    isCtxStale?: () => boolean,
   ) {
     this.backend = backend
     this.ctx = ctx
+    this.isCtxStale = isCtxStale
   }
 
   // ── 任务 CRUD ──
@@ -160,7 +179,30 @@ export class SchedulerRuntime {
 
   startScheduler(): void {
     if (this.tickTimer) return
-    this.tickTimer = setInterval(() => void this.tickScheduler(), TICK_INTERVAL_MS)
+    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 {
+          console.warn(`[scheduler] tick error: ${message}`)
+        }
+      })
+    }, TICK_INTERVAL_MS)
   }
 
   stopScheduler(): void {
@@ -170,6 +212,16 @@ export class SchedulerRuntime {
     }
   }
 
+  /**
+   * stale 自停退场（G1 前置检查与 F2 catch 分诊共用）：warn 观测口径与 crash-fix 一致
+   * （含 "tick stopped"，U1 断言锚定）+ stopScheduler（幂等）。timer 自停后调度由
+   * session_start 重建的新一代 runtime 接管。
+   */
+  private retireStaleTimer(): void {
+    console.warn(`[scheduler] tick stopped: stale extension ctx (session replaced); timer self-retired`)
+    this.stopScheduler()
+  }
+
   /**
    * 注册 tick 后回调（W2）。index.ts 注册 refreshWidget 替代独立 widgetTimer——
    * 每次 tickScheduler 末尾调用，对齐 TICK_INTERVAL_MS 刷新 widget。
@@ -218,15 +270,38 @@ export class SchedulerRuntime {
 
   /**
    * dispatch 单个任务。返回 true 表示真的发送了 message，false 表示 no-op
-   * （task disabled / rate-limited / 非 force 且 busy）。
-   * sendMessage 抛错时记录 failed 状态但不 rethrow，让 tick 继续处理其他任务。
+   * （task disabled / 已有同任务在途 / rate-limited / 非 force 且 busy）。
    *
-   * 持久化（append-only）：recurring 成功推进 nextRunAt → append advance（status='success' CL8）；
-   * once 成功 → append delete。失败 dispatch 不 append（CL7 重试语义，transient 失败 nextRunAt 未推进）。
+   * R3-S1 in-flight 守卫：tick 为 fire-and-forget，若 tick1 的 `await backend.sendMessage`
+   * 挂起超过 TICK_INTERVAL_MS（如 pi 卡死），tick2 的 step2 会再标 pending、step3 对同一
+   * task 并发第二个 dispatch → 同一 prompt 双注入（force 任务绕过 isIdle gate 直接受影响）。
+   * 参照 subagent-workflow resumesInFlight 模式：入口同步置位、finally 清除（覆盖 gate /
+   * rate-limit / sendMessage 抛错 / 成功推进全部退出路径）；命中时 skip 本轮并 warn
+   * （不 throw——tick 继续处理其他任务，本任务 pending 保留到下轮重试）。
    */
   async dispatchTask(task: ScheduledTask): Promise<boolean> {
     if (!task.enabled) return false
+    if (this.dispatchesInFlight.has(task.id)) {
+      console.warn(`[scheduler] dispatch already in flight for task ${task.id}; skipping this tick`)
+      return false
+    }
+    this.dispatchesInFlight.add(task.id)
+    try {
+      return await this.dispatchTaskInner(task)
+    } finally {
+      this.dispatchesInFlight.delete(task.id)
+    }
+  }
 
+  /**
+   * dispatch 本体（dispatchTask 守卫置位后执行；runTaskNow 与 tick step3 共用入口，
+   * 手动 run-now 与挂起中的 tick dispatch 并发时同样被守卫拦截）。
+   * sendMessage 抛错时记录 failed 状态但不 rethrow，让 tick 继续处理其他任务。
+   *
+   * 持久化（append-only）：recurring 成功推进 nextRunAt → append advance（status='success' CL8）；
+   * once 成功 → append delete。失败 dispatch 不 append（CL7 重试语义，transient 失败 nextRunAt 未推进）。
+   */
+  private async dispatchTaskInner(task: ScheduledTask): Promise<boolean> {
     // 检查 force 或 idle
     if (!task.force) {
       if (!this.ctx.isIdle() || this.ctx.hasPendingMessages()) {

package/src/service.ts

@@ -133,7 +133,7 @@ export class SchedulerService {
   /**
    * 立即执行任务。语义细分：
    * 任务不存在 → TASK_NOT_FOUND；任务存在但 dispatch no-op
-   * （disabled / busy / rate-limited）→ DISPATCH_SKIPPED。
+   * （disabled / busy / rate-limited / 同任务 dispatch 在途）→ DISPATCH_SKIPPED。
    * 修复了旧实现把 no-op 误报为 not found 的混同。
    */
   async run(id: string | undefined): Promise<ServiceResult> {
@@ -148,7 +148,7 @@ export class SchedulerService {
       return {
         success: false,
         errorCode: 'DISPATCH_SKIPPED',
-        message: `Task ${id} not dispatched (busy, disabled, or rate-limited).`,
+        message: `Task ${id} not dispatched (busy, disabled, rate-limited, or a dispatch already in flight).`,
       }
     }
     return { success: true, message: `Task ${id} executed.` }