@zhushanwen/pi-subagent-workflow 8.1.0 → 8.2.0

package/src/execution/__tests__/status-refactor.test.ts

@@ -15,8 +15,8 @@
 import { describe, expect, it } from "vitest";
 
 import { completeRecord, createRecord, tryTransition } from "../execution-record.ts";
-import { BgNotifier } from "../notifier.ts";
-import type { BgNotifyRecord, NotifierHost } from "../notifier.ts";
+import { createNotifier } from "../notifier.ts";
+import type { BgNotifyRecord, BgNotifier, NotifierHost } from "../notifier.ts";
 import { mapExternalState } from "../../interface/subagent-actions.ts";
 import { statusGlyph } from "../../interface/format.ts";
 import type { ClosedReason, ExecutionRecord, ExecutionStatus } from "../types.ts";
@@ -205,7 +205,7 @@ describe("BgNotifier dedupKey", () => {
 
   it("同 id 不同 round 不被去重（round 参与 dedup key）", () => {
     const host = createMockHost(false);
-    const notifier = new BgNotifier(host);
+    const notifier = createNotifier(host);
     const sent: unknown[] = [];
     // 重写 sendMessage 捕获
     (host as { sendMessage: NotifierHost["sendMessage"] }).sendMessage = (msg) => { sent.push(msg); };
@@ -238,7 +238,7 @@ describe("BgNotifier dedupKey", () => {
 
   it("不同 id 不被去重", () => {
     const host = createMockHost(false);
-    const notifier = new BgNotifier(host);
+    const notifier = createNotifier(host);
     const sent: unknown[] = [];
     (host as { sendMessage: NotifierHost["sendMessage"] }).sendMessage = (msg) => { sent.push(msg); };
 
@@ -267,7 +267,7 @@ describe("BgNotifier dedupKey", () => {
 
   it("closed status 被正确入队", () => {
     const host = createMockHost(false);
-    const notifier = new BgNotifier(host);
+    const notifier = createNotifier(host);
     const sent: unknown[] = [];
     (host as { sendMessage: NotifierHost["sendMessage"] }).sendMessage = (msg) => { sent.push(msg); };
 

package/src/execution/__tests__/ui-channels.test.ts

@@ -2,7 +2,7 @@
 //
 // W1 红灯测试：ui-channels.ts — channel 提取（marker 解析）+ channel 注册表。
 //
-// 测试对象：extensions/subagent-workflow/src/execution/ui-channels.ts（新建）
+// 测试对象：extensions/universal/subagent-workflow/src/execution/ui-channels.ts（新建）
 // 契约来源：.fix-plans/00-master-summary.md §一 冲突 2「维度 2：channel 注册表」
 //
 // parseChannel(req): ExtensionUiRequest → { channel?, channelPayload? }

package/src/execution/__tests__/ui-interaction-model.test.ts

@@ -2,7 +2,7 @@
 //
 // W1 红灯测试：ui-interaction-model.ts — method 交互模型分类。
 //
-// 测试对象：extensions/subagent-workflow/src/execution/ui-interaction-model.ts（新建）
+// 测试对象：extensions/universal/subagent-workflow/src/execution/ui-interaction-model.ts（新建）
 // 契约来源：.fix-plans/00-master-summary.md §一 冲突 2「维度 1：透传判定规则」
 //
 // isDialogMethod(method):

package/src/execution/__tests__/ui-request-observability.test.ts

@@ -2,7 +2,7 @@
 //
 // M4 测试：ui-request-observability.ts — UiRequestObservability 纯逻辑类。
 //
-// 测试对象：extensions/subagent-workflow/src/execution/ui-request-observability.ts
+// 测试对象：extensions/universal/subagent-workflow/src/execution/ui-request-observability.ts
 // 契约来源：类注释（per-session 去重 + resetMissingHandlerWarnings 清洗 + setMode/getMode 往返）
 //
 // UiRequestObservability 职责：

package/src/execution/notifier.ts

@@ -2,11 +2,15 @@
 //
 // Background 完成回注主对话。sync 不用（调用方还在 await，结果直接返回）。
 //
-// 职责：
-//   - 合并窗口：MERGE_WINDOW_MS 内多个完成合并为一条通知
-//   - 去重 TTL：同 id 在 TTL 内不重复通知
-//   - 通过 pi.sendMessage({ deliverAs:"followUp", triggerTurn:true }) 注入——
-//     当前 turn 结束后唤醒父 agent 处理结果（followUp 不打断 streaming、不锁滚动）
+// 职责（迁移后，U3）：
+//   - buildLlmContent：格式化通知文案（本文件唯一逻辑职责）
+//   - createNotifier：薄工厂，装配 @xyz-agent/session-delivery 内核
+//   - 合并窗口 / 去重 / 退避 / flush 全部委托内核
+//
+// 投递通道：内核 → pi.sendMessage({ deliverAs:"steer", triggerTurn:true }) 注入——
+//   当前 turn 结束后唤醒父 agent 处理结果（steer 不打断 streaming、不锁滚动）
+
+import { createDelivery, type DeliveryHandle, type DeliveryPort } from "@xyz-agent/session-delivery";
 
 /**
  * 一条待发送的完成通知记录。
@@ -50,251 +54,207 @@ export interface BgNotifyRecord {
   totalRounds?: number;
 }
 
-/** notifier 依赖的 pi 最小接口（解耦，便于测试）。 */
+/** notifier 依赖的宿主最小接口（解耦，便于测试）。
+ *  迁移后：仅用于构造 DeliveryPort 的底层依赖。 */
 export interface NotifierHost {
-  /** 注入消息到主对话。
-   *  triggerTurn:true + deliverAs:"steer" → 空闲时立即 prompt 新 turn；streaming 时
-   *  进 steer 队列等下个 turn 边界 drain。
-   *
-   *  ⚠️ 竞态注意：triggerTurn 分支只在主 agent isStreaming===false 时生效。若调用时
-   *  主 agent 处于 agent_end → finishRun 的窄窗口（isStreaming 仍 true），消息会被
-   *  错误走 steer 分支入队，而 runLoop 已结束无人 drain → 通知静默丢失。flushPendingNotifications
-   *  通过 isIdle() 退避保证在 idle 后同步送达，规避此窗口。 */
+  /** 注入消息到主对话。 */
   sendMessage(
     message: { customType: string; content: string; display: boolean; details?: unknown },
     options?: { triggerTurn?: boolean; deliverAs?: "steer" | "followUp" | "nextTurn" },
   ): void;
   /** 是否还有 running 的 background 任务（用于滑动窗口立即 flush 判断）。 */
   hasRunningBackground(): boolean;
-  /** 主 agent 是否空闲（非 streaming）。flush 前 gate 用——避免在 agent_end→finishRun
-   *  竞态窗口里 sendMessage 走错分支（steer 入队无人 drain）。
-   *  可选：未注入（旧测试 host）时 flush 不 gate，保持原行为。 */
+  /** 主 agent 是否空闲（非 streaming）。可选：未注入时 flush 不 gate。 */
   isIdle?: () => boolean;
+  /**
+   * 原生 settled 事件订阅能力（D8）：注册 handler 监听主 agent settled 边沿。
+   * 无退订语义（pi 0.84.1 的 `pi.on(...)` 全部重载返回 void、无 off——实装锚点：
+   * node_modules `@earendil-works/pi-coding-agent` dist/core/extensions/types.d.ts
+   * `on()` 系列重载，0.84.1 实测）——退订由本模块的 disposed
+   * 标志包装兑现（见下方 port 装配）。可选：未注入时内核退化退避轮询（busy 消息
+   * 靠退避达上限强发，不走 settled 边沿驱动）。
+   */
+  onAgentSettled?(handler: () => void): void;
 }
 
-/** 合并窗口（ms）。窗口内多个完成合并为一条消息。 */
-const MERGE_WINDOW_MS = 60_000;
-/** 去重 TTL（ms）。同 id 在此窗口内不重复通知。 */
-const DEDUP_TTL_MS = 60_000;
-/** [竞态修复] flush 时若主 agent 仍 streaming，短退避重试间隔（ms）。
- *  场景：subagent 完成的 detached microtask 与主 agent agent_end→finishRun 竞态，
- *  isIdle()=false 时退避，等 idle 后再 sendMessage(triggerTurn)，避免走 steer 分支丢失。 */
-const FLUSH_BACKOFF_MS = 100;
-/** [竞态修复] flush 退避上限次数。防止主 agent 永久 busy 时无限重试——
- *  达上限后强制发送（fallthrough 到 pi 的 steer/triggerTurn 分支，至少不丢消息）。 */
-const FLUSH_BACKOFF_MAX = 50; // 50 × 100ms = 5s
-
 /** 发送给主对话的 customType（bg-notify-render 消费）。 */
 const NOTIFY_CUSTOM_TYPE = "subagent-bg-notify";
 
 /**
- * Background 完成通知器（滑动窗口合并）。
- *
- *   notify(record):
- *     1. dedup TTL 检查：同 id 在 TTL 内 → 跳过
- *     2. 入 pending 队列
- *     3. 清除旧 timer（滑动窗口重置）
- *     4. 已无 running background → 立即 flush（最后一批）
- *     5. 否则重启 MERGE_WINDOW_MS timer（等后续完成合并）
+ * 将 BgNotifyRecord 格式化为 LLM 可读的 notification content。
  *
- *   flushPendingNotifications():  timer 到期 / 无 running / shutdown 触发
- *     1. isIdle gate：主 agent 仍 streaming → 退避重试（scheduleFlush），等 idle 后再发
- *     2. doSend：取出 pending 全部 record
- *     3. 合并为一条消息（多条时列 bullet list）
- *     4. sendMessage({ customType:"subagent-bg-notify",
- *                     content, display:true,
- *                     triggerTurn:true, deliverAs:"steer" })
- *     5. 清空 pending + timer
- *
- * 滑动窗口：每次有新完成都重置 60s 计时器，密集完成的任务尽量合并到一条通知。
- * 无 running 时立即 flush——避免最后一条等满窗口。
+ * 模块内唯一消费方是下方 createNotifier 的 notify()（预格式化后传 delivery.send，
+ * 内核只做拼接——多条以 "\n\n---\n\n" join）。
  */
-export class BgNotifier {
-  private readonly pending: BgNotifyRecord[] = [];
-  /** dedup：id → 上次通知时间戳。 */
-  private readonly dedup = new Map<string, number>();
-  private timer: ReturnType<typeof setTimeout> | undefined;
-  private _disposed = false;
-  /** flush 重试计数（isIdle gate 退避用）。每次成功发送后清零。 */
-  private flushAttempts = 0;
-
-  constructor(private readonly host: NotifierHost) {}
-
-  /**
-   * 入队一条完成通知（去重 + 滑动窗口合并）。dispose 后短路。
-   */
-  notify(record: BgNotifyRecord): void {
-    if (this._disposed) return;
-
-    const now = Date.now();
-    // sweep 过期 dedup 条目（防 Map 无限增长）
-    if (this.dedup.size > 0) {
-      for (const [id, ts] of this.dedup) {
-        if (now - ts >= DEDUP_TTL_MS) this.dedup.delete(id);
+function buildLlmContent(record: BgNotifyRecord): string {
+  const agent = record.agent;
+  const id = record.id;
+  // [wave2 指针行] 增量语义下轮次通知只携带本轮增量，异步 flush 窗口丢失时不可重发
+  //（见 subagent-service.ts onRoundSettled 注释），恢复通道是 session 文件全文。
+  // 仅 chatMode 透传 sessionFile，one-shot 通知不含该行；cancelled/gc-failed 不追加
+  //（无成功结果可读，指针无意义）；缺失时省略整行（追加空串 = 输出逐字节不变）。
+  const transcriptPointer = record.sessionFile
+    ? `\n\nFull transcript: ${record.sessionFile}`
+    : "";
+  switch (record.status) {
+    case "closed": {
+      // v4 B-1: closed 统一终态（含 cancelled）。按 closedReason 派生通知文案。
+      const reason = record.closedReason ?? "gc";
+      if (reason === "cancelled") {
+        return `Subagent "${agent}" (${id}) cancelled.`;
       }
+      // 失败场景（gc + 有 error）：展示错误。判定必须先于 patchFile——失败轮也会写
+      // patchFile（doFinalizeRecord Step 0 对 worktreeHandle 无条件 collectPatch），若
+      // patch 分支在前，gc 失败 + worktree 并存时 LLM 被告知 completed。顺序与三处
+      // 同构契约的另外两处一致（shared/subagent.ts deriveClosedDisplay、
+      // bg-notify-render.ts renderRecordLines：cancelled → gc+error → patch/result）。
+      if (record.error && reason === "gc") {
+        return `Subagent "${agent}" (${id}) failed: ${record.error}`;
+      }
+      // 成功完成（user-close）或通用结束（gc/parent-shutdown 等）：展示结果。
+      // [C-2] chatMode close 终态通知附轮次统计（设计 D2 路径①"completed after N rounds"）。
+      // totalRounds 仅 close 语义携带（notifyClosed）；one-shot 完成通知不设置（round 无轮次
+      // 语义），文案保持 "completed. Result:" 逐字节（G4 硬约束，one-shot 字节锁测试锚定）。
+      const roundsSuffix =
+        record.totalRounds != null && record.totalRounds > 0
+          ? ` after ${record.totalRounds} round${record.totalRounds === 1 ? "" : "s"}`
+          : "";
+      const base = `Subagent "${agent}" (${id}) completed${roundsSuffix}. Result:\n${record.result ?? "(empty)"}`;
+      if (record.patchFile) {
+        // [wave2 review] 长 return 拆行：模板串内不可直接换行（会改变输出内容），提取 patchHint 中转变量
+        const patchHint = `\n\nThis subagent ran in an isolated worktree; its file changes were captured as a patch:\n  ${record.patchFile}\nTo bring these changes into the current repo, run: \`git apply ${record.patchFile}\``;
+        return `${base}${patchHint}${transcriptPointer}`;
+      }
+      return `${base}${transcriptPointer}`;
     }
-    // dedup key：idle（对话模式每轮完成）按 id:round 去重——不同轮次不互相掩蔽；
-    // 非 idle（closed/cancelled）round 恒定 undefined，key 同旧行为不变。
-    const dedupKey = record.round != null ? `${record.id}:${record.round}` : record.id;
-    const lastSeen = this.dedup.get(dedupKey);
-    if (lastSeen !== undefined && now - lastSeen < DEDUP_TTL_MS) return;
-    this.dedup.set(dedupKey, now);
-
-    this.pending.push(record);
-
-    if (this.timer !== undefined) {
-      clearTimeout(this.timer);
-      this.timer = undefined;
-    }
-
-    if (!this.host.hasRunningBackground()) {
-      this.flushPendingNotifications();
-      return;
-    }
-
-    this.timer = setTimeout(() => this.flushPendingNotifications(), MERGE_WINDOW_MS);
+    case "running":
+      // v4 B-1: 对话模式轮次完成（旧 idle 折入 running）：携带本轮结果送回主 agent，等待下一轮 message。
+      return `Subagent "${agent}" (${id}) finished a round. Reply:\n${record.result ?? "(empty)"}${transcriptPointer}`;
   }
+}
 
-  /** 立即 flush（session_shutdown 调用，防丢失）。
-   *  外部入口（notify 立即触发 / shutdown）。内部实际发送在 doSend 中，
-   *  外部入口不传 attempt，走 isIdle gate 退避逻辑。 */
-  flushPendingNotifications(): void {
-    this.scheduleFlush(0);
-  }
+/**
+ * Background 完成通知器接口（迁移后由内核实现）。
+ *
+ * 保持与旧 BgNotifier 类相同的公共 API，避免消费方（subagent-service）改动面过大。
+ */
+export interface BgNotifier {
+  /** 入队一条完成通知（去重 + 合批窗口合并）。dispose 后短路。 */
+  notify(record: BgNotifyRecord): void;
+  /** 立即 flush（session_shutdown 调用，防丢失）。 */
+  flushPendingNotifications(): void;
+  /** session 结束：清队列，dispose 内核 handle。 */
+  dispose(): void;
+  /** /resume /fork /new 后复活。 */
+  revive(): void;
+}
 
-  /**
-   * [竞态修复] 调度 flush：isIdle gate + 退避重试。
-   *
-   * 核心问题：sendMessage({triggerTurn:true}) 只在主 agent isStreaming===false 时
-   * 启动新 turn。若 flush 在 agent_end → finishRun 的窄窗口触发（isStreaming 仍 true），
-   * 消息走 steer 分支入队，runLoop 已结束无人 drain → 通知丢失（非必现，时序竞态）。
-   *
-   * 修复：isIdle() 可用时，busy 退避到 idle 后再发送。isIdle() 与 sendMessage 同步链
-   * （均读 agent.state.isStreaming，host.sendMessage 不 await），故一旦 isIdle=true，
-   * 同步调 sendMessage 必走 triggerTurn 分支。isIdle 未注入（旧 host）时不 gate，原行为。
-   *
-   * 退避上限：FLUSH_BACKOFF_MAX 次后强制发送——防主 agent 永久 busy（长 turn）时通知饿死，
-   * fallthrough 到 pi 的 steer/triggerTurn 分支，至少不丢消息（busy 时走 steer 会在该
-   * turn 结束后由 _handlePostAgentRun drain）。
-   */
-  private scheduleFlush(attempt: number): void {
-    if (this._disposed) return;
-    if (this.pending.length === 0) return;
+/**
+ * 创建 Background 完成通知器（薄工厂，装配 @xyz-agent/session-delivery 内核）。
+ *
+ * 内核接管：gate（isIdle 退避）/ 合批窗口（滑动 60s）/ dedup（按 id:round）/ flush / shutdown flush。
+ * 本函数职责：将 BgNotifyRecord → DeliveryMessage 映射 + buildLlmContent 预格式化。
+ *
+ * @param host 宿主能力注入（pi.sendMessage + hasRunningBackground + isIdle）
+ * @returns BgNotifier 接口（与旧类同形）
+ */
+export function createNotifier(host: NotifierHost): BgNotifier {
+  let disposed = false;
 
-    // isIdle gate：注入了 isIdle 且当前 busy → 退避重试（未达上限）
-    if (this.host.isIdle) {
-      let idle = true;
-      try {
-        idle = this.host.isIdle();
-      } catch {
-        // isIdle 内部 assertActive 可能抛（session 已关闭）——视为不可发送，丢弃。
-        // dispose 后本函数首行已短路，此处 catch 兜底极端时序。
-        this.pending.length = 0;
-        this.flushAttempts = 0;
-        return;
-      }
-      if (!idle && attempt < FLUSH_BACKOFF_MAX) {
-        this.timer = setTimeout(() => this.scheduleFlush(attempt + 1), FLUSH_BACKOFF_MS);
-        return;
+  // 构造 DeliveryPort：intent → pi 参数翻译在适配器内（D3）
+  const port: DeliveryPort = {
+    supportedPayloads: ["custom"],
+    isIdle: () => {
+      if (host.isIdle) {
+        return host.isIdle();
       }
-      // idle 或达上限 → 继续发送
-    }
+      // 未注入 isIdle → 视为 idle（不 gate，向后兼容旧 host）
+      return true;
+    },
+    hasPendingMessages: () => false, // notifier 不关心 hasPendingMessages
+    // D8（must-fix #4）：settled 边沿驱动装配——内核 busy 入队后由 settled 事件唤醒
+    // flush（watch-dog 兜底事件丢失），替代无订阅时的退避轮询。host 只注入原生订阅
+    // 能力；disposed 标志包装（兑现退订语义——pi.on 返回 void 且无 off）在此完成。
+    subscribeSettled:
+      host.onAgentSettled === undefined
+        ? undefined
+        : (cb) => {
+            let disposed = false;
+            host.onAgentSettled?.(() => {
+              if (!disposed) cb();
+            });
+            return () => {
+              disposed = true;
+            };
+          },
+    send: (msg, intent) => {
+      host.sendMessage(
+        {
+          customType: NOTIFY_CUSTOM_TYPE,
+          content: msg.payload.content,
+          display: true,
+          details: msg.payload.kind === "custom" ? msg.payload.details : undefined,
+        },
+        intent === "interrupt-at-turn-boundary"
+          ? { triggerTurn: true, deliverAs: "steer" }
+          : { triggerTurn: true, deliverAs: "followUp" },
+      );
+    },
+  };
 
-    this.doSend();
-  }
+  // #5（must-fix）：内核 handle 的 disposed 不可逆——dispose 后 revive 必须重建 handle，
+  // 否则 revive 后所有 notify() 被内核静默吞（外层标志复位救不回已销毁的内核）。
+  // revive = 新生命周期：合批窗口 / 在途批次 / dedup LRU 随重建自然复位（可接受）。
+  const createHandle = (): DeliveryHandle =>
+    createDelivery(port, {
+      intent: "interrupt-at-turn-boundary",    // D3：turn 边界抢占（F1 教训内化）
+      mergeWindowMs: 60_000,                   // 滑动窗口合批（继承 MERGE_WINDOW_MS=60s）
+      mergeHoldActive: () => host.hasRunningBackground(), // D4 must-fix #1：禁止用 isIdle 代替
+      busyPolicy: "retry-force",               // settled 边沿驱动 + 退避达上限强发
+      backoff: { ms: 100, max: 50 },           // 继承 FLUSH_BACKOFF_MS/MAX
+      // dedup LRU：语义与旧 DEDUP_TTL_MS=60s **不同**——按 key 永久去重（仅 LRU 逐出后
+      // 同 key 可再入）。当前 key 空间（id / id:round，id 每 spawn 唯一）无实际差异；
+      // 后续复用方勿按「60s 内不重复」假设接入（同 key 通知会被永久吞）。
+      dedupe: { maxKeys: 1000 },
+    });
+  let handle: DeliveryHandle = createHandle();
 
-  /** 实际发送（取出 pending + 合并 + sendMessage）。清 timer + 重试计数。 */
-  private doSend(): void {
-    if (this.timer !== undefined) {
-      clearTimeout(this.timer);
-      this.timer = undefined;
-    }
-    if (this.pending.length === 0) return;
-    this.flushAttempts = 0;
+  return {
+    notify(record: BgNotifyRecord): void {
+      if (disposed) return;
 
-    const records = this.pending.splice(0);
-    const content = records.length === 1
-      ? this.buildLlmContent(records[0])
-      : records.map((r) => this.buildLlmContent(r)).join("\n\n---\n\n");
-    const details = records.length === 1
-      ? records[0]
-      : { batch: true, items: records };
+      // dedup key：idle（对话模式每轮完成）按 id:round 去重——不同轮次不互相掩蔽；
+      // 非 idle（closed/cancelled）round 恒定 undefined，key 同旧行为不变。
+      const dedupeKey = record.round != null ? `${record.id}:${record.round}` : record.id;
 
-    this.host.sendMessage({
-      customType: NOTIFY_CUSTOM_TYPE,
-      content,
-      display: true,
-      details,
-      // [W2 修复] followUp → steer：subagent 完成通知需立即抢占主 agent 下一个 turn，
-      // 即使主 agent 处于轮询 subagent_list 的 processing 状态（followUp 永远排不上）。
-      // 与 workflow helpers.ts:151 同语义对齐（commit d214d0d83 验证 steer 能避免
-      // 'Agent is already processing' 错误）。
-      // [竞态修复] 配合 scheduleFlush 的 isIdle gate：此时主 agent 已确认 idle，
-      // triggerTurn 必走 _runAgentPrompt 启动新 turn，不会撞 steer 分支丢失。
-    }, { triggerTurn: true, deliverAs: "steer" });
-  }
+      handle.send({
+        payload: {
+          kind: "custom",
+          customType: NOTIFY_CUSTOM_TYPE,
+          content: buildLlmContent(record),
+          display: true,
+          details: record,
+        },
+        dedupeKey,
+      });
+    },
 
-  private buildLlmContent(record: BgNotifyRecord): string {
-    const agent = record.agent;
-    const id = record.id;
-    // [wave2 指针行] 增量语义下轮次通知只携带本轮增量，异步 flush 窗口丢失时不可重发
-    //（见 subagent-service.ts onRoundSettled 注释），恢复通道是 session 文件全文。
-    // 仅 chatMode 透传 sessionFile，one-shot 通知不含该行；cancelled/gc-failed 不追加
-    //（无成功结果可读，指针无意义）；缺失时省略整行（追加空串 = 输出逐字节不变）。
-    const transcriptPointer = record.sessionFile
-      ? `\n\nFull transcript: ${record.sessionFile}`
-      : "";
-    switch (record.status) {
-      case "closed": {
-        // v4 B-1: closed 统一终态（含 cancelled）。按 closedReason 派生通知文案。
-        const reason = record.closedReason ?? "gc";
-        if (reason === "cancelled") {
-          return `Subagent "${agent}" (${id}) cancelled.`;
-        }
-        // 失败场景（gc + 有 error）：展示错误。判定必须先于 patchFile——失败轮也会写
-        // patchFile（doFinalizeRecord Step 0 对 worktreeHandle 无条件 collectPatch），若
-        // patch 分支在前，gc 失败 + worktree 并存时 LLM 被告知 completed。顺序与三处
-        // 同构契约的另外两处一致（shared/subagent.ts deriveClosedDisplay、
-        // bg-notify-render.ts renderRecordLines：cancelled → gc+error → patch/result）。
-        if (record.error && reason === "gc") {
-          return `Subagent "${agent}" (${id}) failed: ${record.error}`;
-        }
-        // 成功完成（user-close）或通用结束（gc/parent-shutdown 等）：展示结果。
-        // [C-2] chatMode close 终态通知附轮次统计（设计 D2 路径①"completed after N rounds"）。
-        // totalRounds 仅 close 语义携带（notifyClosed）；one-shot 完成通知不设置（round 无轮次
-        // 语义），文案保持 "completed. Result:" 逐字节（G4 硬约束，one-shot 字节锁测试锚定）。
-        const roundsSuffix =
-          record.totalRounds != null && record.totalRounds > 0
-            ? ` after ${record.totalRounds} round${record.totalRounds === 1 ? "" : "s"}`
-            : "";
-        const base = `Subagent "${agent}" (${id}) completed${roundsSuffix}. Result:\n${record.result ?? "(empty)"}`;
-        if (record.patchFile) {
-          // [wave2 review] 长 return 拆行：模板串内不可直接换行（会改变输出内容），提取 patchHint 中转变量
-          const patchHint = `\n\nThis subagent ran in an isolated worktree; its file changes were captured as a patch:\n  ${record.patchFile}\nTo bring these changes into the current repo, run: \`git apply ${record.patchFile}\``;
-          return `${base}${patchHint}${transcriptPointer}`;
-        }
-        return `${base}${transcriptPointer}`;
-      }
-      case "running":
-        // v4 B-1: 对话模式轮次完成（旧 idle 折入 running）：携带本轮结果送回主 agent，等待下一轮 message。
-        return `Subagent "${agent}" (${id}) finished a round. Reply:\n${record.result ?? "(empty)"}${transcriptPointer}`;
-    }
-  }
+    flushPendingNotifications(): void {
+      handle.flush();
+    },
 
-  /** session 结束：清 timer，丢弃 pending。 */
-  dispose(): void {
-    this._disposed = true;
-    if (this.timer !== undefined) {
-      clearTimeout(this.timer);
-      this.timer = undefined;
-    }
-    this.pending.length = 0;
-    this.dedup.clear();
-    this.flushAttempts = 0;
-  }
+    dispose(): void {
+      disposed = true;
+      handle.dispose();
+    },
 
-  /** /resume /fork /new 后复活。 */
-  revive(): void {
-    this._disposed = false;
-  }
+    revive(): void {
+      disposed = false;
+      // #5：内核 disposed 不可逆——revive 必须重建 handle（/resume /fork /new 后的
+      // session_start 时序：disposeAll → initSession → revive）。旧 handle 若仍存活
+      // （首次 session_start 的 revive）dispose 为幂等清理，无副作用。
+      handle.dispose();
+      handle = createHandle();
+    },
+  };
 }

package/src/execution/session-runner.ts

@@ -181,7 +181,7 @@ const STDERR_MAX_CHARS = 65_536;
  *
  * [跨包契约 SSOT] 此字面量是两个独立 npm 包（@zhushanwen/pi-subagent-workflow 与
  * @zhushanwen/pi-structured-output）之间的隐式 env 契约。structured-output 包内同名常量为
- * `ENV_SCHEMA = "PI_WORKFLOW_SCHEMA"`（见 extensions/structured-output/src/index.ts）。
+ * `ENV_SCHEMA = "PI_WORKFLOW_SCHEMA"`（见 extensions/universal/structured-output/src/index.ts）。
  * 两包是独立 npm 包不能直接 import，故各自保留常量但显式标注此契约关系——
  * 任一端改名必须同步另一端，否则权威 schema 注入会静默断桥（子进程不注册 tool/hook）。
  */

package/src/execution/subagent-service.ts

@@ -32,8 +32,8 @@ import { doFinalizeRecord, doFinalizeRoundToIdle } from "./finalize-record.ts";
 import { ManifestStore } from "./manifest-store.ts";
 import type { ModelConfigService } from "./model-config-service.ts";
 import type { AgentConfig, ModelInfo, ResolvedModel } from "./model-resolver.ts";
-import type { BgNotifyRecord, NotifierHost } from "./notifier.ts";
-import { BgNotifier } from "./notifier.ts";
+import type { BgNotifyRecord, BgNotifier, NotifierHost } from "./notifier.ts";
+import { createNotifier } from "./notifier.ts";
 import { getSubagentRecordsDir, getSubagentSessionDir } from "./path-encoding.ts";
 import type { StatusFilter } from "./record-store.ts";
 import { RecordStore } from "./record-store.ts";
@@ -104,6 +104,10 @@ interface PiLike {
     message: { customType: string; content: string; display: boolean; details?: unknown },
     options?: { triggerTurn?: boolean; deliverAs?: "steer" | "followUp" | "nextTurn" },
   ): void;
+  /** 订阅 pi 事件（D8：notifier 的 settled 边沿订阅用 'agent_settled'）。
+   *  pi 0.84.1 的 on 返回 void 且无 off——退订语义由调用侧 disposed 标志包装兑现。
+   *  可选：旧测试 mock pi 可能未实现 on，缺省时 notifier 退化为内核退避路径。 */
+  on?(event: "agent_settled", handler: () => void): void;
 }
 
 /** UI streaming sink 的最小接口（ctx.ui.setWidget 的 duck-typed 子集）。
@@ -299,7 +303,7 @@ export class SubagentService {
     const recordsDir = getSubagentRecordsDir(this.modelService.getAgentDir(), this.rootCwd);
     this.manifestStore = new ManifestStore(recordsDir);
     this.store = new RecordStore(sessionsDir, this.manifestStore, this.pi ?? undefined);
-    this.notifier = new BgNotifier(this.piAdapter());
+    this.notifier = createNotifier(this.piAdapter());
     // #11：注册进程级 observability 单例——ui-request-queue.handleUiRequest 经
     // globalThis 桥接（notifyMissingHandlerGlobal）调到同一实例，共享
     // warnedMissingHandlerSessions 去重集合。未注册时 queue 走 fallback warn（不去重）。
@@ -586,7 +590,10 @@ export class SubagentService {
           (r) => r.mode === "background" && hasLiveProcessHandle(r.id) && !hasIdleTimer(r.id),
         );
       },
-      isIdle: this.isIdleFn,
+      isIdle: () => this.isIdleFn?.() ?? true,
+      // [must-fix #4 / D8] settled 边沿订阅，与 isIdle 同源（session_start 注入的 pi）。
+      // 只注入原生订阅能力；disposed 标志包装（退订语义）在 notifier 的 port 装配完成。
+      onAgentSettled: (handler) => { this.pi?.on?.("agent_settled", handler); },
     };
   }
 

package/src/index.ts

@@ -41,6 +41,7 @@ import {
 import { killAllSpawnedChildren } from "./execution/session-runner.ts";
 import { SubprocessAgentRunner } from "./execution/subprocess-agent-runner.ts";
 import { WorktreeManager } from "./execution/worktree-manager.ts";
+import { setupModelListInjector } from "./injectors/model-list-injector.ts";
 import { setupSubagentListInjector } from "./injectors/subagent-list-injector.ts";
 import { setupWorkflowListInjector } from "./injectors/workflow-list-injector.ts";
 import { renderBgNotifyMessage } from "./interface/bg-notify-render.ts";
@@ -168,6 +169,7 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
 
   // ════════════════════════════════════════════════════════════
   //  injectors：before_agent_start 注入 <available_subagents> + <available_workflows>
+  //  + <available_provider_models>（模型列表供派发时指定 model 参数；与 subagent/workflow 清单对称）
   //
   //  归位自 unified-hooks（subagent-list-injector）+ 新增 workflow-list-injector。
   //  injector 是 subagent-workflow 的内聚功能（让 LLM 知道有哪些 agent/workflow
@@ -176,6 +178,7 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
   // ════════════════════════════════════════════════════════════
   setupSubagentListInjector(pi);
   setupWorkflowListInjector(pi);
+  setupModelListInjector(pi);
 
   // 模块级缓存：主 session 的 sessionFile（fork source 解析用）。
   let cachedMainSessionFile: string | undefined;