@zhushanwen/pi-subagent-workflow 8.1.0 → 8.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-subagent-workflow",
-  "version": "8.1.0",
+  "version": "8.2.0",
   "type": "module",
   "main": "index.ts",
   "description": "Unified subagent execution and multi-agent workflow orchestration for Pi — spawned-process agent runtime with sync/background modes, stateful workflow management with persistence, state machine, and execution tracing.",
@@ -30,6 +30,9 @@
     "src/interface/",
     "src/shared/"
   ],
+  "xyz-agent": {
+    "role": "universal"
+  },
   "pi": {
     "extensions": [
       "./index.ts"
@@ -44,17 +47,18 @@
   "dependencies": {
     "ajv": "^8.20.0",
     "yaml": "^2.9.0",
-    "@xyz-agent/extension-protocol": "0.5.0",
-    "@zhushanwen/pi-extension-logger": "0.2.1",
+    "@xyz-agent/extension-protocol": "0.6.0",
+    "@xyz-agent/session-delivery": "0.2.0",
+    "@zhushanwen/pi-extension-logger": "0.2.2",
     "@zhushanwen/pi-file-lock": "0.1.1"
   },
   "peerDependencies": {
-    "@earendil-works/pi-ai": "*",
-    "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-tui": "*",
+    "@earendil-works/pi-ai": "^0.84.1",
+    "@earendil-works/pi-coding-agent": "^0.84.1",
+    "@earendil-works/pi-tui": "^0.84.1",
     "typebox": "*",
-    "@zhushanwen/pi-pending-notifications": "0.3.3",
-    "@zhushanwen/pi-structured-output": "5.0.1"
+    "@zhushanwen/pi-pending-notifications": "0.3.4",
+    "@zhushanwen/pi-structured-output": "5.0.2"
   },
   "peerDependenciesMeta": {
     "@earendil-works/pi-coding-agent": {

package/skills/workflow-script-format/SKILL.md

@@ -201,7 +201,7 @@ const results = await parallel(
 );
 ```
 
-> 内置通用编排 workflow（chain / parallel / scatter-gather / map-reduce，可直接 `workflow run`，用 `agent()` 自包含实现）见 `extensions/subagent-workflow/workflows/`。本段教 `workflow()` 嵌套 API，workflows 目录是开箱即用的通用编排工具（用 `agent()` 而非 `workflow()` 嵌套）。
+> 内置通用编排 workflow（chain / parallel / scatter-gather / map-reduce，可直接 `workflow run`，用 `agent()` 自包含实现）见 `extensions/universal/subagent-workflow/workflows/`。本段教 `workflow()` 嵌套 API，workflows 目录是开箱即用的通用编排工具（用 `agent()` 而非 `workflow()` 嵌套）。
 
 ### Other globals
 

package/src/execution/__tests__/__fixtures__/notifier-golden-snapshots.json

@@ -0,0 +1,53 @@
+{
+  "_meta": "Golden snapshots for BgNotifier.buildLlmContent — captured pre-migration (commit HEAD at time of capture). Used by migration verification to ensure zero behavioral regression.",
+  "single_closed_success": {
+    "input": { "id": "sa-ptr-7", "status": "closed", "agent": "worker", "result": "done", "startedAt": 1, "endedAt": 2 },
+    "output": "Subagent \"worker\" (sa-ptr-7) completed. Result:\ndone"
+  },
+  "single_closed_with_sessionfile": {
+    "input": { "id": "sa-ptr-2", "status": "closed", "agent": "w", "result": "final result", "sessionFile": "/tmp/sessions/child-2.jsonl", "startedAt": 1, "endedAt": 2 },
+    "output": "Subagent \"w\" (sa-ptr-2) completed. Result:\nfinal result\n\nFull transcript: /tmp/sessions/child-2.jsonl"
+  },
+  "single_running_round": {
+    "input": { "id": "sa-ptr-4", "status": "running", "agent": "w", "round": 2, "result": "round2 text", "startedAt": 1, "endedAt": 2 },
+    "output": "Subagent \"w\" (sa-ptr-4) finished a round. Reply:\nround2 text"
+  },
+  "single_running_round_with_sessionfile": {
+    "input": { "id": "sa-ptr-1", "status": "running", "agent": "w", "round": 1, "result": "round1 text", "sessionFile": "/tmp/sessions/child-1.jsonl", "startedAt": 1, "endedAt": 2 },
+    "output": "Subagent \"w\" (sa-ptr-1) finished a round. Reply:\nround1 text\n\nFull transcript: /tmp/sessions/child-1.jsonl"
+  },
+  "single_cancelled": {
+    "input": { "id": "sa-ptr-5", "status": "closed", "closedReason": "cancelled", "agent": "w", "startedAt": 1, "endedAt": 2 },
+    "output": "Subagent \"w\" (sa-ptr-5) cancelled."
+  },
+  "single_gc_failed": {
+    "input": { "id": "sa-ptr-6", "status": "closed", "closedReason": "gc", "agent": "w", "error": "spawn EPIPE", "startedAt": 1, "endedAt": 2 },
+    "output": "Subagent \"w\" (sa-ptr-6) failed: spawn EPIPE"
+  },
+  "single_gc_failed_with_patchfile": {
+    "input": { "id": "sa-ptr-8", "status": "closed", "closedReason": "gc", "agent": "w", "error": "spawn EPIPE", "patchFile": "/tmp/patches/sa-ptr-8.patch", "startedAt": 1, "endedAt": 2 },
+    "output": "Subagent \"w\" (sa-ptr-8) failed: spawn EPIPE"
+  },
+  "single_closed_with_patchfile_and_sessionfile": {
+    "input": { "id": "sa-ptr-3", "status": "closed", "agent": "w", "result": "did work", "patchFile": "/tmp/patches/sa-ptr-3.patch", "sessionFile": "/tmp/sessions/child-3.jsonl", "startedAt": 1, "endedAt": 2 },
+    "output_contains": "git apply /tmp/patches/sa-ptr-3.patch",
+    "output_ends_with": "\n\nFull transcript: /tmp/sessions/child-3.jsonl"
+  },
+  "single_closed_totalrounds": {
+    "input": { "id": "sa-rounds-1", "status": "closed", "agent": "w", "totalRounds": 3, "result": "", "sessionFile": "/tmp/sessions/child-rounds.jsonl", "startedAt": 1, "endedAt": 2 },
+    "output": "Subagent \"w\" (sa-rounds-1) completed after 3 rounds. Result:\n\n\nFull transcript: /tmp/sessions/child-rounds.jsonl"
+  },
+  "single_closed_no_totalrounds": {
+    "input": { "id": "sa-rounds-2", "status": "closed", "agent": "w", "result": "done", "sessionFile": "/tmp/sessions/child-oneshot.jsonl", "startedAt": 1, "endedAt": 2 },
+    "output": "Subagent \"w\" (sa-rounds-2) completed. Result:\ndone\n\nFull transcript: /tmp/sessions/child-oneshot.jsonl"
+  },
+  "batch_two_closed": {
+    "description": "Two closed records merged in one message (simulating 60s merge window)",
+    "records": [
+      { "id": "batch-1", "status": "closed", "agent": "w1", "result": "result1", "startedAt": 1, "endedAt": 2 },
+      { "id": "batch-2", "status": "closed", "agent": "w2", "result": "result2", "startedAt": 3, "endedAt": 4 }
+    ],
+    "separator": "\n\n---\n\n",
+    "details_shape": { "batch": true, "items": "array-of-records" }
+  }
+}

package/src/execution/__tests__/channel-registry-handshake.test.ts

@@ -2,7 +2,7 @@
 //
 // 决策 D（修复 M4）：channel handshake 协议升级测试。
 //
-// 测试对象：extensions/subagent-workflow/src/execution/channel-registry-access.ts
+// 测试对象：extensions/universal/subagent-workflow/src/execution/channel-registry-access.ts
 //
 // 协议契约（与 ask-user 侧严格对齐）：
 //   key 字面量：     "@zhushanwen/pi-subagents.channelHandshake"

package/src/execution/__tests__/dialog-queue.test.ts

@@ -2,7 +2,7 @@
 //
 // W2 红灯测试：dialog-queue.ts — L2 跨子进程全局 dialog 串行队列。
 //
-// 测试对象：extensions/subagent-workflow/src/execution/dialog-queue.ts（新建）
+// 测试对象：extensions/universal/subagent-workflow/src/execution/dialog-queue.ts（新建）
 // 契约来源：.fix-plans/00-master-summary.md §一 冲突 3（L2 DialogGlobalQueue 设计）
 //
 // DialogGlobalQueue 设计要点：

package/src/execution/__tests__/host-mode.test.ts

@@ -2,7 +2,7 @@
 //
 // W1 红灯测试：host-mode.ts 主进程运行模式分类工具。
 //
-// 测试对象：extensions/subagent-workflow/src/execution/host-mode.ts（新建）
+// 测试对象：extensions/universal/subagent-workflow/src/execution/host-mode.ts（新建）
 // 契约来源：.fix-plans/00-master-summary.md §一 冲突 4 + §2.5（W4 守卫消费点）
 //
 // 三个导出：

package/src/execution/__tests__/notifier-flush.test.ts

@@ -12,7 +12,7 @@
 
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
-import { BgNotifier, type NotifierHost } from "../notifier.ts";
+import { createNotifier, type BgNotifier, type NotifierHost } from "../notifier.ts";
 
 /** mock host：捕获所有 sendMessage 调用 + 控制 hasRunningBackground + isIdle。 */
 function makeMockHost(): NotifierHost & {
@@ -35,11 +35,11 @@ function makeMockHost(): NotifierHost & {
 
 describe("BgNotifier.flushPendingNotifications — deliverAs 契约", () => {
 	let host: ReturnType<typeof makeMockHost>;
-	let notifier: BgNotifier;
+		let notifier: BgNotifier;
 
 	beforeEach(() => {
 		host = makeMockHost();
-		notifier = new BgNotifier(host);
+		notifier = createNotifier(host);
 	});
 
 	afterEach(() => {
@@ -87,7 +87,7 @@ describe("BgNotifier — isIdle gate 竞态修复", () => {
 	beforeEach(() => {
 		vi.useFakeTimers();
 		host = makeMockHost();
-		notifier = new BgNotifier(host);
+		notifier = createNotifier(host);
 	});
 
 	afterEach(() => {
@@ -152,7 +152,7 @@ describe("BgNotifier — isIdle gate 竞态修复", () => {
 			sendMessage: (message, options) => host.sendMessage(message, options),
 			hasRunningBackground: () => false,
 		};
-		const legacyNotifier = new BgNotifier(legacyHost);
+		const legacyNotifier = createNotifier(legacyHost);
 		legacyNotifier.notify({
 			id: "bg-legacy-1",
 			status: "closed",
@@ -192,7 +192,7 @@ describe("BgNotifier dedup 按轮次（G1 决策 9：对话模式豁免 60s dedu
 	beforeEach(() => {
 		host = makeMockHost();
 		// hasRunningBackground=false → notify 立即 flush（不排队）；dedup 仍在 push 前生效
-		notifier = new BgNotifier(host);
+		notifier = createNotifier(host);
 	});
 
 	afterEach(() => {
@@ -250,7 +250,7 @@ describe("BgNotifier buildLlmContent 指针行（wave2：chatMode sessionFile
 	beforeEach(() => {
 		host = makeMockHost();
 		// hasRunningBackground=false → notify 立即 flush，sendMessageCalls 恰 1 条
-		notifier = new BgNotifier(host);
+		notifier = createNotifier(host);
 	});
 
 	afterEach(() => {
@@ -386,3 +386,189 @@ describe("BgNotifier buildLlmContent 指针行（wave2：chatMode sessionFile
 		);
 	});
 });
+
+describe("BgNotifier — subscribeSettled 装配（must-fix #4 / D8 settled 边沿驱动）", () => {
+	let host: ReturnType<typeof makeMockHost>;
+	let notifier: BgNotifier;
+	/** 内核经 port.subscribeSettled 注册的 settled 边沿回调（测试手动触发模拟 pi 事件）。 */
+	let settledEdges: Array<() => void>;
+
+	beforeEach(() => {
+		vi.useFakeTimers();
+		host = makeMockHost();
+		settledEdges = [];
+		// host 注入原生订阅能力；notifier port 内部用 disposed 标志包装（D8 适配）
+		host.onAgentSettled = (handler) => {
+			settledEdges.push(handler);
+		};
+		notifier = createNotifier(host);
+	});
+
+	afterEach(() => {
+		notifier.dispose();
+		vi.useRealTimers();
+	});
+
+	it("busy 入队 → settled 事件触发 → flush 送达（不依赖退避轮询）", () => {
+		host.isIdle.mockReturnValue(false);
+		notifier.notify({
+			id: "bg-settled-1",
+			status: "closed",
+			agent: "worker",
+			result: "ok",
+			startedAt: Date.now(),
+			endedAt: Date.now(),
+		});
+
+		// busy 入队：内核装配了 subscribeSettled → settled 边沿驱动，注册过订阅
+		expect(host.sendMessageCalls).toHaveLength(0);
+		expect(settledEdges.length).toBeGreaterThanOrEqual(1);
+
+		// 有订阅装配下内核不走退避强发——推进远超退避上限（50 × 100ms）仍不发送
+		vi.advanceTimersByTime(10_000);
+		expect(host.sendMessageCalls).toHaveLength(0);
+
+		// settled 边沿（isIdle 已先于事件复位，agent-session.js:327-336）→ flush 送达
+		host.isIdle.mockReturnValue(true);
+		settledEdges[0]!();
+
+		expect(host.sendMessageCalls).toHaveLength(1);
+		expect(host.sendMessageCalls[0]!.options).toMatchObject({
+			triggerTurn: true,
+			deliverAs: "steer",
+		});
+	});
+
+	it("dispose 后 settled 边沿不再触发发送（内核 disposed 拦截）", () => {
+		host.isIdle.mockReturnValue(false);
+		notifier.notify({
+			id: "bg-settled-2",
+			status: "closed",
+			agent: "worker",
+			result: "ok",
+			startedAt: Date.now(),
+			endedAt: Date.now(),
+		});
+		notifier.dispose();
+
+		host.isIdle.mockReturnValue(true);
+		settledEdges[0]!();
+
+		expect(host.sendMessageCalls).toHaveLength(0);
+	});
+});
+
+describe("BgNotifier — revive 重建内核 handle（must-fix #5）", () => {
+	let host: ReturnType<typeof makeMockHost>;
+	let notifier: BgNotifier;
+
+	beforeEach(() => {
+		host = makeMockHost();
+		notifier = createNotifier(host);
+	});
+
+	afterEach(() => {
+		notifier.dispose();
+	});
+
+	it("dispose → notify 静默丢弃 → revive → notify 恢复送达", () => {
+		notifier.notify({
+			id: "bg-revive-1",
+			status: "closed",
+			agent: "worker",
+			result: "ok",
+			startedAt: 1,
+			endedAt: 2,
+		});
+		expect(host.sendMessageCalls).toHaveLength(1);
+
+		// session_shutdown：dispose（内核 handle 销毁，disposed 不可逆）
+		notifier.dispose();
+
+		// dispose 窗口内的 notify：外层 disposed 短路，静默丢弃（旧有语义）
+		notifier.notify({
+			id: "bg-revive-2",
+			status: "closed",
+			agent: "worker",
+			result: "dropped",
+			startedAt: 3,
+			endedAt: 4,
+		});
+		expect(host.sendMessageCalls).toHaveLength(1);
+
+		// /resume /fork /new 后的 revive：必须重建内核 handle——旧实现仅复位外层标志，
+		// 内核已 dispose，此后所有 notify 被内核静默吞（通知永久丢失）
+		notifier.revive();
+		notifier.notify({
+			id: "bg-revive-3",
+			status: "closed",
+			agent: "worker",
+			result: "alive again",
+			startedAt: 5,
+			endedAt: 6,
+		});
+
+		expect(host.sendMessageCalls).toHaveLength(2);
+		const msg = host.sendMessageCalls[1]!.message as { content: string };
+		expect(msg.content).toContain("bg-revive-3");
+	});
+
+	it("revive 后同 id 重复通知不被旧生命周期的 dedup LRU 吞（新 handle 状态复位）", () => {
+		notifier.notify({ id: "bg-revive-dup", status: "closed", agent: "w", result: "r1", startedAt: 1, endedAt: 2 });
+		notifier.dispose();
+		notifier.revive();
+		// 同 id 第二次：旧 handle 的 dedup LRU 已随 dispose 清空 + 重建，不被吞
+		notifier.notify({ id: "bg-revive-dup", status: "closed", agent: "w", result: "r2", startedAt: 3, endedAt: 4 });
+		expect(host.sendMessageCalls).toHaveLength(2);
+	});
+});
+
+describe("U3_UNIT: createNotifier unit verification", () => {
+	it("createNotifier returns object with notify/flush/dispose/revive", () => {
+		const host = makeMockHost();
+		const notifier = createNotifier(host);
+		expect(typeof notifier.notify).toBe("function");
+		expect(typeof notifier.flushPendingNotifications).toBe("function");
+		expect(typeof notifier.dispose).toBe("function");
+		expect(typeof notifier.revive).toBe("function");
+		notifier.dispose();
+	});
+
+	it("notify calls host.sendMessage with customType=subagent-bg-notify", () => {
+		const host = makeMockHost();
+		const notifier = createNotifier(host);
+		notifier.notify({
+			id: "u3-test-1", status: "closed", agent: "worker", result: "ok",
+			startedAt: 1, endedAt: 2,
+		});
+		expect(host.sendMessageCalls).toHaveLength(1);
+		const msg = host.sendMessageCalls[0]!.message as { customType: string };
+		expect(msg.customType).toBe("subagent-bg-notify");
+		notifier.dispose();
+	});
+
+	it("notify with mergeHoldActive=true defers flush until explicit call", () => {
+		const sendMessageCalls: unknown[] = [];
+		const host: NotifierHost = {
+			sendMessage: (msg) => { sendMessageCalls.push(msg); },
+			hasRunningBackground: () => true,
+			isIdle: () => true,
+		};
+		const notifier = createNotifier(host);
+		notifier.notify({
+			id: "u3-merge-1", status: "closed", agent: "w", result: "r1",
+			startedAt: 1, endedAt: 2,
+		});
+		notifier.notify({
+			id: "u3-merge-2", status: "closed", agent: "w", result: "r2",
+			startedAt: 3, endedAt: 4,
+		});
+		// mergeHoldActive=true → messages queued, not sent yet
+		expect(sendMessageCalls).toHaveLength(0);
+		notifier.flushPendingNotifications();
+		expect(sendMessageCalls).toHaveLength(1);
+		const content = (sendMessageCalls[0] as { content: string }).content;
+		expect(content).toContain("\n\n---\n\n");
+		notifier.dispose();
+	});
+});

package/src/execution/__tests__/notifier-golden-snapshot.test.ts

@@ -0,0 +1,261 @@
+/**
+ * Golden snapshot 固化测试：记录 notifier.buildLlmContent 在各种输入下的输出。
+ *
+ * 此测试在迁移**前**运行并固化结果——迁移后必须逐字节一致（G4）。
+ *
+ * 这些测试直接测试 BgNotifier 的输出内容，不涉及 send/handle 机制，
+ * 因此迁移后应通过内核装配 + 同一 buildLlmContent 产生相同输出。
+ */
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { describe, expect, it } from "vitest";
+import { createNotifier, type BgNotifyRecord, type NotifierHost } from "../notifier.ts";
+import { renderBgNotifyMessage } from "../../interface/bg-notify-render.ts";
+
+/** 渲染锁用 mock theme（与 bg-notify-render.test.ts 同款：透传文本，记录色 token）。 */
+function makeRenderTheme(): { theme: Theme } {
+  return {
+    theme: {
+      fg: (_tag: string, text: string) => text,
+      bold: (text: string) => text,
+      bg: (_color: string, text: string) => text,
+    } as unknown as Theme,
+  };
+}
+
+/** 创建 mock host，notifier 会立即 flush（hasRunningBackground=false）。 */
+function makeMockHost(): NotifierHost {
+  return {
+    sendMessage: () => {},
+    hasRunningBackground: () => false,
+    isIdle: () => true,
+  };
+}
+
+/**
+ * 调用 notifier.notify 并捕获 sendMessage 的 content 参数。
+ * 前置条件：hasRunningBackground=false → notify 立即 flush。
+ */
+function captureNotificationContent(record: BgNotifyRecord): string {
+  let capturedContent = "";
+  const host: NotifierHost = {
+    sendMessage: (msg) => {
+      capturedContent = (msg as { content: string }).content;
+    },
+    hasRunningBackground: () => false,
+    isIdle: () => true,
+  };
+  const notifier = createNotifier(host);
+  notifier.notify(record);
+  notifier.dispose();
+  return capturedContent;
+}
+
+describe("U3_UNIT notifier golden snapshots (pre-migration freeze)", () => {
+  it("single closed success — one-shot completed notification", () => {
+    const content = captureNotificationContent({
+      id: "sa-ptr-7",
+      status: "closed",
+      agent: "worker",
+      result: "done",
+      startedAt: 1,
+      endedAt: 2,
+    });
+    expect(content).toBe('Subagent "worker" (sa-ptr-7) completed. Result:\ndone');
+  });
+
+  it("single closed + sessionFile — pointer line appended", () => {
+    const content = captureNotificationContent({
+      id: "sa-ptr-2",
+      status: "closed",
+      agent: "w",
+      result: "final result",
+      sessionFile: "/tmp/sessions/child-2.jsonl",
+      startedAt: 1,
+      endedAt: 2,
+    });
+    expect(content).toBe(
+      'Subagent "w" (sa-ptr-2) completed. Result:\nfinal result\n\nFull transcript: /tmp/sessions/child-2.jsonl',
+    );
+  });
+
+  it("single running round (chatMode) — round notification", () => {
+    const content = captureNotificationContent({
+      id: "sa-ptr-4",
+      status: "running",
+      agent: "w",
+      round: 2,
+      result: "round2 text",
+      startedAt: 1,
+      endedAt: 2,
+    });
+    expect(content).toBe('Subagent "w" (sa-ptr-4) finished a round. Reply:\nround2 text');
+  });
+
+  it("single running round + sessionFile — pointer appended to round notification", () => {
+    const content = captureNotificationContent({
+      id: "sa-ptr-1",
+      status: "running",
+      agent: "w",
+      round: 1,
+      result: "round1 text",
+      sessionFile: "/tmp/sessions/child-1.jsonl",
+      startedAt: 1,
+      endedAt: 2,
+    });
+    expect(content).toBe(
+      'Subagent "w" (sa-ptr-1) finished a round. Reply:\nround1 text\n\nFull transcript: /tmp/sessions/child-1.jsonl',
+    );
+  });
+
+  it("single cancelled — cancelled message, no pointer", () => {
+    const content = captureNotificationContent({
+      id: "sa-ptr-5",
+      status: "closed",
+      closedReason: "cancelled",
+      agent: "w",
+      startedAt: 1,
+      endedAt: 2,
+    });
+    expect(content).toBe('Subagent "w" (sa-ptr-5) cancelled.');
+  });
+
+  it("single gc-failed — error message, no pointer", () => {
+    const content = captureNotificationContent({
+      id: "sa-ptr-6",
+      status: "closed",
+      closedReason: "gc",
+      agent: "w",
+      error: "spawn EPIPE",
+      startedAt: 1,
+      endedAt: 2,
+    });
+    expect(content).toBe('Subagent "w" (sa-ptr-6) failed: spawn EPIPE');
+  });
+
+  it("single gc-failed + patchFile — failed takes priority, no patch hint", () => {
+    const content = captureNotificationContent({
+      id: "sa-ptr-8",
+      status: "closed",
+      closedReason: "gc",
+      agent: "w",
+      error: "spawn EPIPE",
+      patchFile: "/tmp/patches/sa-ptr-8.patch",
+      startedAt: 1,
+      endedAt: 2,
+    });
+    expect(content).toBe('Subagent "w" (sa-ptr-8) failed: spawn EPIPE');
+  });
+
+  it("single closed + patchFile + sessionFile — patch hint + pointer", () => {
+    const content = captureNotificationContent({
+      id: "sa-ptr-3",
+      status: "closed",
+      agent: "w",
+      result: "did work",
+      patchFile: "/tmp/patches/sa-ptr-3.patch",
+      sessionFile: "/tmp/sessions/child-3.jsonl",
+      startedAt: 1,
+      endedAt: 2,
+    });
+    expect(content).toContain("git apply /tmp/patches/sa-ptr-3.patch");
+    expect(content.endsWith("\n\nFull transcript: /tmp/sessions/child-3.jsonl")).toBe(true);
+  });
+
+  it("closed + totalRounds — chatMode close with round stats", () => {
+    const content = captureNotificationContent({
+      id: "sa-rounds-1",
+      status: "closed",
+      agent: "w",
+      totalRounds: 3,
+      result: "",
+      sessionFile: "/tmp/sessions/child-rounds.jsonl",
+      startedAt: 1,
+      endedAt: 2,
+    });
+    expect(content).toBe(
+      "Subagent \"w\" (sa-rounds-1) completed after 3 rounds. Result:\n\n\nFull transcript: /tmp/sessions/child-rounds.jsonl",
+    );
+  });
+
+  it("closed no totalRounds — one-shot, no round stats", () => {
+    const content = captureNotificationContent({
+      id: "sa-rounds-2",
+      status: "closed",
+      agent: "w",
+      result: "done",
+      sessionFile: "/tmp/sessions/child-oneshot.jsonl",
+      startedAt: 1,
+      endedAt: 2,
+    });
+    expect(content).toBe(
+      'Subagent "w" (sa-rounds-2) completed. Result:\ndone\n\nFull transcript: /tmp/sessions/child-oneshot.jsonl',
+    );
+  });
+});
+
+describe("notifier golden — batch merge (60s window, two records)", () => {
+  it("two closed records joined with separator", () => {
+    let capturedContent = "";
+    let capturedDetails: unknown;
+    const host: NotifierHost = {
+      sendMessage: (msg) => {
+        capturedContent = (msg as { content: string }).content;
+        capturedDetails = (msg as { details: unknown }).details;
+      },
+      hasRunningBackground: () => true, // true → 合批窗口激活
+      isIdle: () => true,
+    };
+    const notifier = createNotifier(host);
+
+    // 两条通知入队（不立即 flush——hasRunningBackground=true）
+    notifier.notify({
+      id: "batch-1", status: "closed", agent: "w1", result: "result1",
+      startedAt: 1, endedAt: 2,
+    });
+    notifier.notify({
+      id: "batch-2", status: "closed", agent: "w2", result: "result2",
+      startedAt: 3, "endedAt": 4,
+    });
+
+    // 手动 flush（模拟窗口到期）
+    notifier.flushPendingNotifications();
+
+    expect(capturedContent).toBe(
+      'Subagent "w1" (batch-1) completed. Result:\nresult1\n\n---\n\nSubagent "w2" (batch-2) completed. Result:\nresult2',
+    );
+    // details 结构（must-fix #13 / #6 锁死）：items 元素必须是 record 本体（顶层
+    // status/agent/id/result——bg-notify-render 的 extractBgNotifyRecord 按此读取），
+    // 拦截内核 items 规则回归（曾错装 payload 导致渲染降级默认样式）。
+    const details = capturedDetails as { batch: boolean; items: unknown[] };
+    expect(details.batch).toBe(true);
+    expect(details.items).toHaveLength(2);
+    expect(details.items[0]).toMatchObject({
+      id: "batch-1",
+      status: "closed",
+      agent: "w1",
+      result: "result1",
+      startedAt: 1,
+      endedAt: 2,
+    });
+    expect(details.items[1]).toMatchObject({
+      id: "batch-2",
+      status: "closed",
+      agent: "w2",
+      result: "result2",
+    });
+    // 端到端渲染锁（#6）：合批 details 直接喂 bg-notify-render 必须走批量分支成功渲染
+    // （非 undefined 兜底），两条 agent 均可见。
+    const { theme } = makeRenderTheme();
+    const comp = renderBgNotifyMessage(
+      { details: capturedDetails },
+      { expanded: false },
+      theme,
+    );
+    expect(comp).toBeDefined();
+    const joined = comp!.render(80).join("\n");
+    expect(joined).toContain("w1");
+    expect(joined).toContain("w2");
+
+    notifier.dispose();
+  });
+});

package/src/execution/__tests__/spawn-event-adapter-rpc.test.ts

@@ -2,7 +2,7 @@
 //
 // W1 红灯测试：spawn-event-adapter.ts 协议层重写 — Pi 原生格式 + method 平铺。
 //
-// 测试对象：extensions/subagent-workflow/src/execution/spawn-event-adapter.ts（改造）
+// 测试对象：extensions/universal/subagent-workflow/src/execution/spawn-event-adapter.ts（改造）
 // 契约来源：.fix-plans/00-master-summary.md §二（统一接口契约）+ §一冲突 2/判定顺序
 //
 // 核心改动：