@zhushanwen/pi-scheduler 0.9.2 → 0.10.0

package/src/runtime.ts

@@ -16,16 +16,21 @@ const logger = getLogger('scheduler')
 
 const MAX_TASKS = 50
 const RATE_LIMIT_PER_MINUTE = 6
-// 导出：ack 写盘自检复用同一节奏常量（禁新造魔数），值 = tick 间隔。
+// tick 间隔（30s）。导出供测试 import 复用（fake timers 推进量与生产节奏同源——禁
+// 测试本地重造 30_000 魔数，改值即测试锚同步漂移）；ack 写盘自检为事件驱动
+//（maybeStartAck 由任务创建回调触发，见 index.ts 创建汇聚点；message_start /
+// turn_end 挂点只承载覆写武装与安全网注销），不引用本常量。
 export const TICK_INTERVAL_MS = 30_000
 const DEFAULT_EXPIRY_DAYS = 7
 const DEFAULT_EXPIRY_MS = DEFAULT_EXPIRY_DAYS * MS_PER_DAY // 7 days
-// U4 dispatch 模型切换（设计 D3 修订版）：
-// - dispatch 注入消息的 customType 标记前缀（dispatchTaskInner 的 sendMessage 与
-//   handleMessageStart 的归属匹配共用单点，字面漂移会静默断开事件恢复链路）
+// U4 dispatch 模型切换（设计 D3 修订版 + D1 归属简化 + ADR-0122 事实查询翻转）：
+// - dispatch 注入消息的 customType 标记前缀（sendMessage 的消息标记，供运维从 session 流
+//   识别 scheduler dispatch 注入；与 ack 触发器前缀 pi-scheduler-ack: 避让）
+// - 恢复判定锚点 = isIdle() 同步事实查询（判定层级最高）：agent_settled 确定性事件是
+//   提前触发的加速器（事件到达即查询并兑现）；每 tick 开头对未决记录做一次同步事实
+//   查询兜正确性（事件丢失时由查询收敛——拉保证正确、事件只优化延迟）。原 2-tick
+//   计数对账（时间窗猜测事件丢失）已按 ADR-0122 删除。
 const DISPATCH_CUSTOM_TYPE_PREFIX = 'pi-scheduler:'
-// - 在途标记强制开放的 tick 计数（D3 在途标记生命周期：超过 2 个 tick 未关闭即视为事件丢失）
-const MODEL_SWITCH_RECONCILE_TICKS = 2
 
 /**
  * 模型控制面（U4 dispatch 模型切换，依赖反转）：runtime 只见 'provider/id' 字符串 ref
@@ -47,37 +52,21 @@ export interface SchedulerModelOps {
 }
 
 /**
- * 未决模型切换记录（设计 D3 状态机三要素之一，纯内存态）。模型语义异常不进持久化词表
+ * 未决模型切换记录（纯内存态）。模型语义异常不进持久化词表
  * （replay 守卫对 advance.status 硬校验 'success'，旁路字段会炸重放推进）。
  *
- * phase 生命周期（在途标记三分）：
- * - 'in-flight'：等待 dispatched turn 的 turn_end 恢复；ticksOpen 计数超过
- *   MODEL_SWITCH_RECONCILE_TICKS → 事件丢失，对账强制开放
- * - 'awaiting-restore'：非 idle 推迟 / 强制开放转推迟；比对决策已在窗口内锁定，
- *   执行不受窗口过期限制——tick 重入 idle 即兑现（不设墙钟上界）
- * - 恢复成功 / restore-failed（setModel(原) false）→ 记录清除（终态只留日志）
+ * 生命周期（ADR-0122 事实查询翻转后）：dispatch 受理 → 记录创建（in-flight 等价语义：
+ * 等 run 落定）；恢复兑现锚点 = isIdle() 同步事实查询（agent_settled 事件提前触发 +
+ * tick 每轮查询兜正确性）→ 恢复成功 / restore-failed（setModel(原) false）→ 记录清除
+ * （终态只留日志）。记录存在 + idle 即恢复，无 phase 区分、无时间窗计数。
  */
 interface PendingModelSwitch {
   taskId: string
   /** 会话期望模型（dispatch 切换前抓取的原模型 'provider/id'） */
   expectedModelRef: string
   targetModelRef: string
-  phase: 'in-flight' | 'awaiting-restore'
-  ticksOpen: number
 }
 
-/**
- * message_start 的 custom message 形状守卫（unknown 收窄，无断言）：
- * role:'custom' 且 customType 以 pi-scheduler: 开头（dispatch 注入标记，P-MODEL-④）。
- */
-function matchesDispatchCustomType(message: unknown): boolean {
-  if (typeof message !== 'object' || message === null) return false
-  if (!('role' in message) || !('customType' in message)) return false
-  if (message.role !== 'custom') return false
-  return (
-    typeof message.customType === 'string' && message.customType.startsWith(DISPATCH_CUSTOM_TYPE_PREFIX)
-  )
-}
 // HISTORY_LIMIT 单点在 types.ts（ext-simplify-08 L5）——与 replay.ts 的 advance 折叠共用
 // STALE_CTX_MARKER（文案兜底分诊词）已迁移到 ext-guards 共享守卫（guardStaleCtx 内部
 // 引用，本文件不再直接持有）。语义：G1 模块级代际检测（isCtxStale）为主判；文案子串
@@ -107,11 +96,6 @@ export class SchedulerRuntime {
   // 结构性不可能（完成顺序不定 → turn 静默跑错模型的交错被消除）。链条引用恒吞错
   // 自愈（见 serializeModelOp），前序 op 失败不阻断后继。
   private modelOpChain: Promise<void> = Promise.resolve()
-  // 归属状态机 run 窗口（P-MODEL-③④：turnIndex per-run 归零，禁止裸 turnIndex 跨 run 当 id）：
-  // agent_start 起算（重置 turn 序态）、agent_end / agent_settled 封口
-  private runWindowActive = false
-  private currentTurnIndex = -1
-  private dispatchedTurnIndex: number | null = null
 
   /**
    * 依赖反转构造：backend 承担 appendEntry/pi.sendMessage/时间源，runtime 只持有内存态。
@@ -128,6 +112,13 @@ export class SchedulerRuntime {
     this.backend = backend
     this.isCtxStale = isCtxStale
     this.modelOps = modelOps
+    // U6c：session_tree（树回退）重折叠接线——生产 backend 在 pi.on('session_tree')
+    // 时按活跃路径重折叠任务集并回调；落点 = 本 tasks Map（loadTasks 换集）。
+    // 纯重建：不 dispatch、不 append op、不动 tickTimer 启停（常驻循环照常消费
+    // 新任务集，被撤子树任务不在集内即到点不触发）也不动 pendingModelSwitch
+    // （撤回编排前置 = 会话空闲，无在途模型切换记录）。测试替身不实现
+    // onSessionTree 时 ?. 订阅为 no-op，既有单测路径不变。
+    backend.onSessionTree?.((tasks) => this.loadTasks(tasks))
   }
 
   // ── 任务 CRUD ──
@@ -301,15 +292,15 @@ export class SchedulerRuntime {
   }
 
   async tickScheduler(): Promise<void> {
-    // U4 对账兜底（设计 D3）：严格先于本 tick 的 dispatch 循环。顺序约束：否则出现
-    // 「B dispatch 先切 Y → 对账持 A 旧记录把 Y 静默切回」的交错（Y 从未生效、全序列
-    // 无报错，G4 被绕过）。恢复执行时 await 完成，保证恢复 setModel 完成后 dispatch 循环
-    // 才开 setModel；更广的「任意两个 setModel 不并发」由模型 op 串行队列（modelOpChain）
-    // 结构保证——含 turn_end 恢复 fire-and-forget 挂点，dispatch 模型分支排在其后。
-    // 无未决记录的绝大多数 tick 同步返回、不引入 microtask 断点——dispatch 的同步段
-    // 契约（in-flight 守卫在 tickScheduler() 未 await 时同步可见）保持不变。
-    const reconciling = this.reconcileModelSwitch()
-    if (reconciling) await reconciling
+    // U4 未决模型切换记录的事实查询结算（严格先于本 tick 的 dispatch 循环）。顺序约束：
+    // 否则出现「B dispatch 先切 Y → 结算持 A 旧记录把 Y 静默切回」的交错（Y 从未生效、
+    // 全序列无报错，G4 被绕过）。恢复执行时 await 完成，保证恢复 setModel 完成后 dispatch
+    // 循环才开 setModel；更广的「任意两个 setModel 不并发」由模型 op 串行队列（modelOpChain）
+    // 结构保证——含 agent_settled 恢复 fire-and-forget 挂点，dispatch 模型分支排在其后。
+    // 无未决记录（或非 idle）的绝大多数 tick 同步返回、不引入 microtask 断点——dispatch
+    // 的同步段契约（in-flight 守卫在 tickScheduler() 未 await 时同步可见）保持不变。
+    const settling = this.settlePendingIfIdle('tick-reconcile')
+    if (settling) await settling
 
     const now = this.backend.now()
 
@@ -388,8 +379,8 @@ export class SchedulerRuntime {
    * 按序执行「互斥校验 → setModel(task.model) → 记未决切换记录 → sendMessage」，切换段
    * 整体入模型 op 串行队列（modelOpChain——与恢复 setModel 互斥，MF-2）。busy 亦照常 setModel
    * （P-MODEL-② 证伪「busy 切换不生效」——steer 消息消费时在同一 run 内开新 turn，turn
-   * 开始从 ctx.model 取当前模型，setModel 对 steer turn 生效。pi 实装锚点（0.84.4）：
-   * dist/core/agent-session.js:1258 setModel 同步写 agent.state.model + :304 每个 turn
+   * 开始从 ctx.model 取当前模型，setModel 对 steer turn 生效。pi 实装锚点（1.0.0 复核）：
+   * dist/core/agent-session.js setModel 同步写 agent.state.model + 每个 turn
    * 准备时从 agent.state.model 取模型快照——setModel 先于下一 turn 准备即生效）。
    * 失败降级（分级，不阻塞核心
    * 调度）：modelOps 缺省 / 会话无当前模型 / setModel false → 日志 + 放弃切换，照常 dispatch。
@@ -410,18 +401,18 @@ export class SchedulerRuntime {
       if (this.pendingModelSwitch) {
         // 互斥窗口（设计 D3，理由 = 切换秩序）：未决记录未关闭时，其他需切模型任务命中即
         // skip 本轮 + pending 留待下 tick 重试（复用现状 skip 语义，不建真队列；不需切模型
-        // 的任务不受互斥影响——检查只在本分支）。「dispatch 写新记录前先强制结算旧记录」
-        // 的落地：本分支结构性永不写新记录（杜绝新旧叠写），同时把已过窗口的 in-flight
-        // 残留先强制开放转移，保证新任务在旧记录结算后 ≤1 tick 内接管、不被过期残留无限阻塞。
-        // 强制结算的恢复必须 await（顺序约束，与 tickScheduler 的对账 await 同构）：恢复
+        // 的任务不受互斥影响——检查只在本分支）。「dispatch 写新记录前先结算旧记录」
+        // 的落地：本分支结构性永不写新记录（杜绝新旧叠写），skip 前做一次 isIdle() 事实
+        // 查询结算（idle 即恢复收口），保证新任务不被旧记录无限阻塞。
+        // 结算的恢复必须 await（顺序约束，与 tickScheduler 的结算 await 同构）：恢复
         // setModel(原) 完成后才放行 skip——恢复与紧随的需切模型任务 setModel(目标) 不得
         // 并发（串行由模型 op 队列结构保证，本 await 是调用方顺序语义：skip 放行前恢复
         // 已收口）；本分支随后即 skip，await 无额外延迟代价。
-        await this.forceSettleExpiredInFlight()
+        await this.settlePendingIfIdle('mutex-settle')
         skipped = true
       } else {
         // 模型 op 串行段（MF-2 收口，互斥窗口全程覆盖「setModel 起步 → 记录创建」）：
-        // 前序模型 op（turn_end 恢复 / 前序 dispatch 切换 / 错误路径恢复）可能仍在途——
+        // 前序模型 op（agent_settled 恢复 / 前序 dispatch 切换 / 错误路径恢复）可能仍在途——
         // 排队等待期间未决记录与当前模型均可能变化，禁止按排队前快照盲切（旧快照的
         // expectedModelRef 会把恢复锚点记错），串行段内重新校验后再切换。后来的需切模型
         // 任务同样排队、出队时重新校验命中互斥 skip——双记录叠写 / 两个 setModel 并发
@@ -448,17 +439,14 @@ export class SchedulerRuntime {
           const switched = await modelOps.setModelByRef(targetModelRef)
           if (switched) {
             // setModel 受理 → 记未决切换记录（会话期望模型 + 在途标记，内存态）；
-            // sendMessage 受理后等事件恢复（message_start 归属 → turn_end + isIdle 复核）。
+            // sendMessage 受理后等 run 落定（agent_settled + isIdle 复核）兑现恢复。
             // 记录创建收在同一串行段内：互斥窗口对后继模型任务即时可见，无「已切未记」
             // 的放行缺口。
             this.pendingModelSwitch = {
               taskId: task.id,
               expectedModelRef: currentNow,
               targetModelRef,
-              phase: 'in-flight',
-              ticksOpen: 0,
             }
-            this.dispatchedTurnIndex = null
           } else {
             // setModel false（无可用 API key 等）→ 按「恢复失败」同族处理：日志 + 放弃本次
             // 切换，任务照常 dispatch（模型字段不阻塞核心调度）
@@ -489,7 +477,6 @@ export class SchedulerRuntime {
       const ps = this.pendingModelSwitch
       if (ps && modelOps) {
         this.pendingModelSwitch = null
-        this.dispatchedTurnIndex = null
         // 恢复 setModel 入模型 op 串行队列（与其他 setModel 发起点互斥，不并发）；排队后
         // 复核「当前 == 期望」：等待期间已切回则不动作
         await this.serializeModelOp(async () => {
@@ -552,23 +539,23 @@ export class SchedulerRuntime {
     return this.dispatchTimestamps.length < RATE_LIMIT_PER_MINUTE
   }
 
-  // ── 模型切换：对账兜底与归属状态机（U4，设计 D3 修订版）──
+  // ── 模型切换：agent_settled 恢复与 tick 事实查询（U4，D3 修订版 + D1 归属简化
+  //    + ADR-0122 事实查询翻转）──
 
   /**
-   * 未决模型切换记录的对账探测（tickScheduler 开头调用，严格先于 dispatch 循环）。
-   * 同步推进状态机，仅在需要执行恢复时返回 Promise（调用方 await——顺序约束）。
-   * 对账守卫前置：仅当存在未决记录才比对恢复——无记录时「模型 ≠ 期望」是用户自主行为，
-   * 不动作（否则用户在任务间隙手动切模型会被静默回滚）。
-   * - in-flight：ticksOpen 计数超 MODEL_SWITCH_RECONCILE_TICKS → 恢复回调永不执行（事件
-   *   丢失），强制开放：idle 即恢复（返回恢复 Promise）；非 idle 转 awaiting-restore
-   *   （P-MODEL-② 证实 setModel 不影响 in-flight turn，但保守口径维持非 idle 推迟。
-   *   pi 实装锚点（0.84.4）：dist/core/agent-session.js:304 turn 模型在准备时一次性
-   *   快照，setModel 只写 state 不回写已在途 turn 的已快照模型）。
-   *   窗口内继续等事件。
-   * - awaiting-restore：比对决策已在窗口内锁定，执行不受窗口过期限制——idle 重入即兑现
-   *   （tick 为天然重入点，不设墙钟上界：任务级正常路径无墙钟超时）。
+   * 未决模型切换记录的事实查询结算：记录存在 + 会话 idle（isIdle() 同步查询，
+   * 判定层级最高的事实来源）→ 兑现恢复；非 idle → 不动作（不能把在途 run 的模型
+   * 换掉），记录保留等下一查询点。无记录时同步返回 undefined（调用方跳过 await，
+   * 保住 tick 无记录路径的同步契约——dispatch 的 in-flight 守卫在 tickScheduler()
+   * 未 await 时同步可见）。
+   *
+   * 调用点两处：① tickScheduler 开头（严格先于 dispatch 循环——顺序约束：否则
+   * 「B dispatch 先切 Y → 对账持 A 旧记录把 Y 静默切回」；agent_settled 事件丢失时
+   * 本查询点是正确性兜底，事件只作提前触发加速器）；② dispatchTaskInner 互斥分支
+   * （skip 前尽量把旧记录收口，恢复 setModel 与后续新任务的 setModel(目标) 不得并发
+   * ——串行由模型 op 队列结构保证，本 await 是调用方顺序语义）。
    */
-  private reconcileModelSwitch(): Promise<void> | undefined {
+  private settlePendingIfIdle(reason: string): Promise<void> | undefined {
     const ps = this.pendingModelSwitch
     if (!ps) return undefined
     if (this.isCtxStale?.()) {
@@ -578,44 +565,8 @@ export class SchedulerRuntime {
     }
     const ops = this.modelOps
     if (!ops) return undefined
-    if (ps.phase === 'in-flight') {
-      ps.ticksOpen += 1
-      if (ps.ticksOpen <= MODEL_SWITCH_RECONCILE_TICKS) return undefined
-      logger.warn('model switch in-flight mark expired, forcing reconciliation', {
-        taskId: ps.taskId,
-        expectedModelRef: ps.expectedModelRef,
-        targetModelRef: ps.targetModelRef,
-      })
-      if (!ops.isIdle()) {
-        ps.phase = 'awaiting-restore'
-        return undefined
-      }
-      return this.restoreExpectedModel('reconcile-forced')
-    }
     if (!ops.isIdle()) return undefined
-    return this.restoreExpectedModel('reconcile-idle')
-  }
-
-  /**
-   * 互斥命中时对已过窗口的 in-flight 残留做强制开放转移（idle 恢复 / 非 idle 转
-   * awaiting-restore）；未过窗口或已在 awaiting-restore 的记录不动（其结算由事件与
-   * tick 对账通道负责）。
-   *
-   * 返回 Promise 而非 fire-and-forget：idle 恢复路径透传 restoreExpectedModel，调用方
-   * （dispatchTaskInner 互斥分支）必须 await——恢复 setModel(原) 与后续新任务的
-   * setModel(目标) 不得并发（runTaskNow 直连路径下完成顺序不定，恢复后完成则该任务
-   * turn 用错模型；串行由模型 op 队列结构保证，本 await 是调用方顺序语义：skip 放行前
-   * 恢复已收口）；本分支随后即 skip，await 无额外延迟代价。
-   */
-  private forceSettleExpiredInFlight(): Promise<void> {
-    const ps = this.pendingModelSwitch
-    if (!ps || !this.modelOps) return Promise.resolve()
-    if (ps.phase !== 'in-flight' || ps.ticksOpen <= MODEL_SWITCH_RECONCILE_TICKS) return Promise.resolve()
-    if (this.modelOps.isIdle()) {
-      return this.restoreExpectedModel('mutex-forced')
-    }
-    ps.phase = 'awaiting-restore'
-    return Promise.resolve()
+    return this.restoreExpectedModel(reason)
   }
 
   /**
@@ -638,8 +589,8 @@ export class SchedulerRuntime {
    * 执行恢复（切回会话期望模型）并关闭未决记录（在途标记生命周期收口）：
    * 当前模型已等于期望（用户已手动切回）→ 清记录不动作；setModel(原) false →
    * restore-failed 终态（日志含恢复动作：会话停留在任务模型，需手动切回）+ 清记录。
-   * 记录先关后恢复——防 await setModel 期间 turn_end 与 tick 对账并发重入。
-   * 恢复 setModel 本体经模型 op 串行队列（serializeModelOp，MF-2）：turn_end 挂点的
+   * 记录先关后恢复——防 await setModel 期间 agent_settled 与 tick 对账并发重入。
+   * 恢复 setModel 本体经模型 op 串行队列（serializeModelOp，MF-2）：agent_settled 挂点的
    * fire-and-forget 调用由此变为安全——在途恢复持队，后续任何 setModel 发起点
    * （dispatch 切换 / 对账恢复）排队等待，两个 setModel 并发结构性不可能（完成顺序
    * 不定 → turn 静默跑错模型的交错被消除）。「当前 == 期望」复核移入串行段：排队
@@ -650,7 +601,6 @@ export class SchedulerRuntime {
     const ops = this.modelOps
     if (!ps || !ops) return Promise.resolve()
     this.pendingModelSwitch = null
-    this.dispatchedTurnIndex = null
     return this.serializeModelOp(async () => {
       if (ops.getCurrentModelRef() === ps.expectedModelRef) return
       const restored = await ops.setModelByRef(ps.expectedModelRef)
@@ -665,85 +615,28 @@ export class SchedulerRuntime {
     })
   }
 
-  // 归属状态机事件入口（index.ts 的 pi.on 转发；方法内不触碰捕获的 pi/ctx——恢复动作
-  // 经构造注入的 modelOps，stale 代际由 isCtxStale 入口检查拦下：清状态机、不执行恢复）。
-
-  /** agent run 开始：重置 run 窗口与 turn 序态（P-MODEL-③：turnIndex per-run 归零） */
-  handleAgentStart(): void {
-    if (this.isCtxStale?.()) return
-    this.runWindowActive = true
-    this.currentTurnIndex = -1
-  }
-
-  /** turn 开始：监听器维护「当前 turnIndex」（message_start 序态关联的基准，P-MODEL-④）。
-   *  turnIndex 缺省（pi 契约恒有；测试仿真可无参调 handler）→ 忽略本次序态更新。 */
-  handleTurnStart(turnIndex: number | undefined): void {
-    if (this.isCtxStale?.()) return
-    if (typeof turnIndex !== 'number') return
-    this.currentTurnIndex = turnIndex
-  }
+  // 模型恢复事件入口（index.ts 的 pi.on('agent_settled') 转发；方法内不触碰捕获的 pi/ctx
+  // ——恢复动作经构造注入的 modelOps，stale 代际由 isCtxStale 入口检查拦下：清状态机、
+  // 不执行恢复）。
 
   /**
-   * message_start 归属匹配（P-MODEL-④ 实测序态 turn_start(n) → message_start(custom) →
-   * … → turn_end(n)）：customType 前缀命中 → 记 dispatchedTurnIndex = 当前 turnIndex。
-   * 仅在未决记录在场且 run 窗口活跃时归属——避免陈旧索引在记录关闭后意外匹配后续 turn，
-   * 以及裸 turnIndex 跨 run 当 id。
-   */
-  handleMessageStart(message: unknown): void {
-    if (this.isCtxStale?.()) return
-    if (!this.pendingModelSwitch || !this.runWindowActive) return
-    if (!matchesDispatchCustomType(message)) return
-    this.dispatchedTurnIndex = this.currentTurnIndex
-  }
-
-  /**
-   * turn_end 恢复挂点（设计 D3 修订版）：turnIndex === dispatchedTurnIndex → isIdle 复核——
-   * idle 即恢复；非 idle（用户长 run 的后续 turn 在途）推迟（phase 转 awaiting-restore，
-   * tick 重入 idle 即兑现）。裸 turn_end 挂点会在用户 run 未结束时提前恢复、把该 run 后续
-   * turn 切回原模型，禁止（P-MODEL-② 实测形态）。turnIndex 缺省（同 handleTurnStart）不匹配。
-   */
-  handleTurnEnd(turnIndex: number | undefined): void {
-    if (this.isCtxStale?.()) return
-    const ps = this.pendingModelSwitch
-    if (
-      !ps ||
-      typeof turnIndex !== 'number' ||
-      this.dispatchedTurnIndex === null ||
-      turnIndex !== this.dispatchedTurnIndex
-    ) {
-      return
-    }
-    if (this.modelOps?.isIdle()) {
-      void this.restoreExpectedModel('turn-end')
-    } else {
-      ps.phase = 'awaiting-restore'
-    }
-  }
-
-  /** agent_end / agent_settled 封口 run 窗口（窗口外 turnIndex 不作归属 id） */
-  handleRunClosed(): void {
-    if (this.isCtxStale?.()) return
-    this.runWindowActive = false
-    this.currentTurnIndex = -1
-    this.dispatchedTurnIndex = null
-  }
-
-  /**
-   * agent_settled：封口 run 窗口（同 handleRunClosed）+ awaiting-restore 的即时兑现。
-   * settled = run 完全落定（无 retry/compaction/queued continuation；pi 实装
-   * agent-session.js _emitAgentSettled 先置 _isAgentRunActive=false 再 emit），正是
-   * awaiting-restore 推迟恢复所等的「真空闲」时刻——挂上后恢复延迟从「最长 1 tick
-   * （30s）」收敛到事件即时。只挂 settled 不挂 agent_end：end 后仍可能有自动续跑
-   * turn，此时切回会把续跑 turn 的模型换掉（P-MODEL-② 同族形态）。
-   * 不动 in-flight（turn_end 丢失的归属异常归 tick 对账——2 tick 强制开放既有兜底）；
-   * settled 与用户新 run 交错（isIdle false）不动作留给 tick，兜底语义不变。
+   * agent_settled：模型恢复的事件触发点（D1 归属简化——原 turnIndex 归属：4 状态字段 +
+   * 6 事件挂点 + customType 前缀匹配，绕路自造对 2-tick 对账的依赖）。settled = run
+   * 完全落定（无 retry/compaction/queued continuation；pi 实装 agent-session.js
+   * _emitAgentSettled 先置 _isAgentRunActive = false 再 emit），dispatched turn 必已
+   * 结束，无需 turnIndex 归属识别——事件到达即做 isIdle() 事实查询：
+   * - idle → 兑现恢复（事件是提前触发的加速器，恢复延迟 = 事件即时）
+   * - 非 idle（settled 与用户新 run 交错）→ 不能切：会把新 run 的模型换掉
+   *   （P-MODEL-② 同族形态）。记录保留，由 tick 的 isIdle() 查询在 idle 重入时兑现。
+   * 不挂 agent_end 恢复：end 后仍可能有自动续跑 turn，此时切回会把续跑 turn 的模型换掉
+   * （P-MODEL-② 同族形态）——恢复只认 settled。
    */
   handleRunSettled(): void {
     if (this.isCtxStale?.()) return
-    this.handleRunClosed()
-    const ps = this.pendingModelSwitch
-    if (ps?.phase !== 'awaiting-restore' || !this.modelOps?.isIdle()) return
-    void this.restoreExpectedModel('agent-settled')
+    if (!this.pendingModelSwitch || !this.modelOps) return
+    if (this.modelOps.isIdle()) {
+      void this.restoreExpectedModel('agent-settled')
+    }
   }
 
   /**
@@ -760,7 +653,10 @@ export class SchedulerRuntime {
 
   // ── 装配与回调 ──
 
-  /** 装配点注入初始任务数组（读盘/重放由 backend 完成，runtime 只持有内存态）。 */
+  /**
+   * 任务集换装入口（装配点 session_start 注入初始数组 + U6c session_tree 重折叠共用；
+   * 读盘/重放由 backend 完成，runtime 只持有内存态）。
+   */
   loadTasks(tasks: ScheduledTask[]): void {
     this.tasks = new Map(tasks.map(t => [t.id, t]))
   }

package/src/types.ts

@@ -69,7 +69,7 @@ export interface AddOptions {
 // 与单测夹具共同消费。
 
 /**
- * ack 触发器 custom message 的 customType 前缀：避让 dispatch 归属前缀 `pi-scheduler:`，
+ * ack 触发器 custom message 的 customType 前缀：避让 dispatch 消息标记前缀 `pi-scheduler:`，
  * 使 `message_start` 武装判别（startsWith）不会把 dispatch / 任务消息误识别为触发器。
  */
 export const ACK_CUSTOM_TYPE_PREFIX = 'pi-scheduler-ack:'