@zhushanwen/pi-pending-notifications 0.9.0 → 0.10.0

package/README.md

@@ -24,11 +24,11 @@
   - `pending:register { id, type, name }` —— 操作启动（`type` ∈ `workflow` / `subagent` / `bash`）
   - `pending:unregister { id, reason }` —— 操作结束（`reason` 映射为终态 status）
   - 发送方：subagent-core（subagent 与 workflow run 生命周期：启动注册 / 结束注销 / 崩溃恢复 sweep 补注销）、base-tool-enhance（bash 后台任务）、subagent-workflow（仅崩溃恢复补注销）
-- **session entries 唯一状态源**：register/unregister 经 `appendEntry` 落盘，无内存第二份状态；活跃集合 = register − unregister 差集，工具投影与写侧去重对同一份 entries 现算，结构上不可分歧
+- **session entries 唯一状态源**：register/unregister 经 `appendEntry` 落盘，无内存第二份状态；活跃集合 = register − unregister 差集，工具派生视图与写侧去重对同一份 entries 现算，结构上不可分歧
 - **写侧幂等**：重复 register、未知/已注销 id 的 unregister 均忽略，天然不重复落盘
 - **无 TTL**：三类操作均按进程存活口径处理，长任务（>1h）仍视为活跃
 - **跨 session 残留过滤**：查询按当前 session id 过滤 fork 继承的父级注册残留
-- **跨扩展导出**：`countActiveFromEntries()` 供 goal（continuation 守卫）、subagent-workflow（后代存活判定）直接复用差集计算；差集本体单点在 `@zhushanwen/extension-protocol`
+- **跨扩展导出**：`countActiveFromEntries()` 供 goal（continuation 检查）、subagent-workflow（后代存活判定）直接复用差集计算；差集本体单点在 `@zhushanwen/extension-protocol`
 
 ## 安装
 
@@ -55,7 +55,7 @@ LLM 在决定「继续推进还是等待异步操作」前主动查询：
 { "action": "list" }
 ```
 
-典型场景：agent 想确认是否真有后台任务在跑（workflow run / subagent / bash 后台命令），避免在异步操作未收口时提前下结论或重复派发。
+典型场景：agent 想确认是否真有后台任务在跑（workflow run / subagent / bash 后台命令），避免在异步操作未收尾时提前下结论或重复派发。
 
 ## 文件结构
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-pending-notifications",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Cross-extension async operation registration/query mechanism for Pi.",
   "type": "module",
   "main": "src/index.ts",
@@ -34,7 +34,8 @@
     "typebox": "1.3.27"
   },
   "dependencies": {
-    "@zhushanwen/extension-protocol": "0.21.0",
+    "@zhushanwen/extension-protocol": "0.22.0",
+    "@zhushanwen/pi-delivery-port": "0.2.0",
     "@zhushanwen/pi-extension-logger": "0.6.2"
   },
   "peerDependenciesMeta": {

package/src/__tests__/collect-results.test.ts

@@ -0,0 +1,630 @@
+// 测试框架：vitest
+// 运行命令：pnpm -C extensions/universal/pending-notifications test
+//
+// collect_results 工具单测（result-collect 设计 §3.1③ 工具面；设计 §5 拆分依据：
+// 工具面独立可测——mock port 句柄）。
+//
+// 测试策略：
+// - vi.mock("@zhushanwen/pi-delivery-port") 全模块 mock：工具经进程级槽消费投递端口，
+//   测试注入 mock handle（collectArm/consume/collectRelease/onCollectArrival 四方法 +
+//   存量面），与 u-p-port 实装解耦（不加载 delivery-port.ts 真实模块）
+// - mock 手法与 pending-notifications.test.ts 同款：最小 mock ExtensionAPI /
+//   ExtensionContext，共享 entries 数组 = session JSONL 的单测层镜像（appendEntry
+//   mock 同步入账）
+// - 覆盖（任务书目标 6）：lifetime 排除生效 / 跨 session 残留反向断言 / 未知 id
+//   errors / 第四态返回形态；另覆盖 sequential 声明、abort 正常返回、timeout、
+//   in-push-pipeline note、快照重收、port 缺席降级、kind 落盘透传、等待中同步到达
+//   的 outcome 回填（一致性修复 U1：managed 合批「deliver 先于注销」同步段时序）
+
+/* eslint-disable taste/no-unsafe-cast -- 测试 mock 构造（pending-notifications.test.ts:15 同款）：最小 mock ExtensionAPI/ExtensionContext 无法逐字段满足真实接口，cast 真值由测试断言兜底（mock 被被测代码真实调用，行为不符即红） */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import pendingNotificationsExtension from "../index";
+import { computeCollectWaitKeys, countActiveFromEntries } from "../state";
+
+// ── delivery-port 全模块 mock（vi.mock 工厂提升，经 vi.hoisted 共享引用） ──
+
+const portMocks = vi.hoisted(() => ({
+	getDeliveryPort: vi.fn<() => unknown>(),
+}));
+
+vi.mock("@zhushanwen/pi-delivery-port", () => portMocks);
+
+// ── Mock 工具（与 pending-notifications.test.ts 同款手法） ──────────────
+
+interface HandlerRegistry { // oe-exempt:20261016:test:测试 mock 类型单实现为测试基建常态（pending-notifications.test.ts 存量同款类型未登记为历史遗留）
+	sessionStart: ((event: unknown, ctx: ExtensionContext) => void | Promise<void>) | undefined;
+	pendingRegister: ((data: unknown) => void) | undefined;
+	pendingUnregister: ((data: unknown) => void) | undefined;
+}
+
+interface MockSessionEntry { // oe-exempt:20261016:test:测试 mock 类型单实现为测试基建常态（pending-notifications.test.ts 存量同款类型未登记为历史遗留）
+	customType: string;
+	data: Record<string, unknown>;
+}
+
+interface MockPort { // oe-exempt:20261016:test:测试 mock 类型单实现为测试基建常态（pending-notifications.test.ts 存量同款类型未登记为历史遗留）
+	collectArm: ReturnType<typeof vi.fn>;
+	consume: ReturnType<typeof vi.fn>;
+	collectRelease: ReturnType<typeof vi.fn>;
+	onCollectArrival: ReturnType<typeof vi.fn>;
+	deliver: ReturnType<typeof vi.fn>;
+	recover: ReturnType<typeof vi.fn>;
+	metrics: ReturnType<typeof vi.fn>;
+	flush: ReturnType<typeof vi.fn>;
+	dispose: ReturnType<typeof vi.fn>;
+}
+
+interface MockSetup { // oe-exempt:20261016:test:测试 mock 类型单实现为测试基建常态（pending-notifications.test.ts 存量同款类型未登记为历史遗留）
+	pi: ExtensionAPI;
+	handlers: HandlerRegistry;
+	entries: MockSessionEntry[];
+	appendEntryMock: ReturnType<typeof vi.fn>;
+	registerToolMock: ReturnType<typeof vi.fn>;
+	port: MockPort;
+}
+
+function createMockPort(): MockPort {
+	return {
+		collectArm: vi.fn(() => []),
+		consume: vi.fn(() => []),
+		collectRelease: vi.fn(),
+		onCollectArrival: vi.fn(() => vi.fn()),
+		deliver: vi.fn(),
+		recover: vi.fn(() => 0),
+		metrics: vi.fn(() => ({ settleRejected: 0, recoveryReplays: 0 })),
+		flush: vi.fn(),
+		dispose: vi.fn(),
+	};
+}
+
+function createMockSetup(): MockSetup {
+	const handlers: HandlerRegistry = {
+		sessionStart: undefined,
+		pendingRegister: undefined,
+		pendingUnregister: undefined,
+	};
+	// P1 单测层镜像：appendEntry mock 同步入账共享 entries
+	const entries: MockSessionEntry[] = [];
+	const appendEntryMock = vi.fn((customType: string, data: Record<string, unknown>) => {
+		entries.push({ customType, data });
+	});
+	const registerToolMock = vi.fn();
+	const port = createMockPort();
+	portMocks.getDeliveryPort.mockReturnValue(port);
+
+	const pi = {
+		appendEntry: appendEntryMock,
+		registerTool: registerToolMock,
+		sendMessage: vi.fn(),
+		on: vi.fn((event: string, handler: (event: unknown, ctx: ExtensionContext) => void | Promise<void>) => {
+			if (event === "session_start") handlers.sessionStart = handler;
+		}),
+		events: {
+			emit: vi.fn(),
+			on: vi.fn((channel: string, handler: (data: unknown) => void) => {
+				if (channel === "pending:register") handlers.pendingRegister = handler;
+				if (channel === "pending:unregister") handlers.pendingUnregister = handler;
+			}),
+		},
+	} as unknown as ExtensionAPI;
+
+	return { pi, handlers, entries, appendEntryMock, registerToolMock, port };
+}
+
+function createMockCtx(setup: MockSetup, sessionId = "sess-current"): ExtensionContext {
+	return {
+		sessionManager: {
+			getEntries: () => setup.entries as unknown[],
+			getSessionId: () => sessionId,
+		},
+	} as unknown as ExtensionContext;
+}
+
+function fireSessionStart(setup: MockSetup, sessionId?: string): void {
+	if (!setup.handlers.sessionStart) throw new Error("session_start handler not registered");
+	void setup.handlers.sessionStart({ type: "session_start", reason: "resume" }, createMockCtx(setup, sessionId));
+}
+
+interface CollectToolDef { // oe-exempt:20261016:test:测试 mock 类型单实现为测试基建常态（pending-notifications.test.ts 存量同款类型未登记为历史遗留）
+	executionMode?: string;
+	description?: string;
+	execute: (
+		toolCallId: string,
+		p: unknown,
+		signal: AbortSignal | undefined,
+		onUpdate: unknown,
+		ctx: ExtensionContext,
+	) => Promise<{
+		content: Array<{ type: string; text: string }>;
+		details: {
+			collected: Array<Record<string, unknown>>;
+			stillOpen: Array<{ id: string; note?: string }>;
+			errors?: Array<{ id: string; reason: string }>;
+		};
+	}>;
+}
+
+function getCollectTool(setup: MockSetup): CollectToolDef {
+	const call = setup.registerToolMock.mock.calls.find(
+		(c) => (c[0] as { name: string }).name === "collect_results",
+	);
+	if (!call) throw new Error("collect_results tool not registered");
+	return call[0] as CollectToolDef;
+}
+
+async function runCollect(
+	setup: MockSetup,
+	params: Record<string, unknown>,
+	signal?: AbortSignal,
+): ReturnType<CollectToolDef["execute"]> {
+	return getCollectTool(setup).execute("collect-call-id", params, signal, undefined, createMockCtx(setup));
+}
+
+// ── 共享 fixtures ───────────────────────────────────
+
+const NOW = 1_700_000_000_000;
+
+function makeRegisterEntry(id: string, extra: Record<string, unknown> = {}): MockSessionEntry {
+	return {
+		customType: "pending:register",
+		data: {
+			id,
+			type: "workflow",
+			name: `op-${id}`,
+			registeredAt: NOW,
+			sessionId: "sess-current",
+			...extra,
+		},
+	};
+}
+
+// ────────────────────────────────────────────────────
+// state.ts：缺省等待键集 + 曾注册集（collect 工具侧纯函数）
+// ────────────────────────────────────────────────────
+
+describe("computeCollectWaitKeys（collect_results 缺省等待集，工具侧减法）", () => {
+	it("lifetime 债权排除生效：kind=lifetime 的 session register 不入缺省集，其余照常", () => {
+		const entries = [
+			makeRegisterEntry("sm-life", { type: "session", kind: "lifetime" }),
+			makeRegisterEntry("sm-send", { type: "session" }),
+			makeRegisterEntry("bt-1", { type: "bash" }),
+		];
+		expect(computeCollectWaitKeys(entries, "sess-current")).toEqual(["sm-send", "bt-1"]);
+	});
+
+	it("升级边沿：无 kind 的旧 session register（send 债权缺省语义）不排除", () => {
+		const entries = [makeRegisterEntry("sm-legacy", { type: "session" })];
+		expect(computeCollectWaitKeys(entries, "sess-current")).toEqual(["sm-legacy"]);
+	});
+
+	it("[跨 session 残留反向断言] sessionId ≠ 当前的继承注册不入缺省集；本 session 计入", () => {
+		// fork 继承的父级注册残留：不滤则子 session 缺省 collect 恒挂继承残留（设计 §3.1③）
+		const entries = [
+			makeRegisterEntry("parent-bg", { sessionId: "sess-old" }),
+			makeRegisterEntry("own-bg"),
+		];
+		expect(computeCollectWaitKeys(entries, "sess-current")).toEqual(["own-bg"]);
+	});
+
+	it("entry 缺 sessionId 的旧形态条目视为本 session（不过滤，宁放行不误逐）", () => {
+		const legacy: MockSessionEntry = {
+			customType: "pending:register",
+			data: { id: "old-1", type: "subagent", name: "o", registeredAt: NOW },
+		};
+		expect(computeCollectWaitKeys([legacy], "sess-current")).toEqual(["old-1"]);
+	});
+
+	it("currentSessionId 空串回退（session_start 未到）：不过滤", () => {
+		const entries = [makeRegisterEntry("a", { sessionId: "s-other" }), makeRegisterEntry("b")];
+		expect(computeCollectWaitKeys(entries, "")).toEqual(["a", "b"]);
+	});
+
+	it("[共享函数缺省语义不动] countActiveFromEntries 仍计 lifetime 为活跃（goal/subagent-workflow 零变化）", () => {
+		// 排除只发生在 computeCollectWaitKeys（工具侧减法）——countActiveFromEntries
+		// 缺省语义不变是任务书机械判据③与设计 §3.4 排除归属显式约定的锁定面。
+		const entries = [makeRegisterEntry("sm-life", { type: "session", kind: "lifetime" })];
+		expect(countActiveFromEntries(entries).ids).toEqual(["sm-life"]);
+	});
+});
+
+// scanPendingFields（终局回填字段视图）的用例已随 MF-2-1 单点收敛移至 protocol：
+// packages/extension-protocol/src/pending-entries.test.ts「字段映射视图」describe
+// （register 首见 type + 注销 status 词表成员判定，同一规则供本包回填与
+// delivery-port 快照基线消费）。
+
+// ────────────────────────────────────────────────────
+// collect_results 工具（mock port 注入）
+// ────────────────────────────────────────────────────
+
+describe("collect_results tool", () => {
+	let setup: MockSetup;
+
+	beforeEach(() => {
+		vi.useFakeTimers();
+		vi.setSystemTime(NOW);
+		setup = createMockSetup();
+		pendingNotificationsExtension(setup.pi);
+		fireSessionStart(setup);
+	});
+
+	afterEach(() => {
+		portMocks.getDeliveryPort.mockReset();
+		vi.useRealTimers();
+	});
+
+	it("工具注册形态：name=collect_results、executionMode=sequential", () => {
+		const tool = getCollectTool(setup);
+		expect(tool.executionMode).toBe("sequential");
+		expect(tool.description).toBeTruthy();
+	});
+
+	it("无 ids 且无活跃 pending → 立即空返回，端口零触达（等待集为空不进入等待）", async () => {
+		const res = await runCollect(setup, {});
+
+		expect(res.details.collected).toEqual([]);
+		expect(res.details.stillOpen).toEqual([]);
+		expect(res.details.errors).toBeUndefined();
+		expect(portMocks.getDeliveryPort).not.toHaveBeenCalled();
+	});
+
+	it("缺省集 = 活跃 − lifetime 债权 − 跨 session 残留：collectArm 只收到本 session 非 lifetime 键", async () => {
+		setup.entries.push(
+			makeRegisterEntry("sm-life", { type: "session", kind: "lifetime" }),
+			makeRegisterEntry("parent-bg", { sessionId: "sess-old" }),
+			makeRegisterEntry("own-1"),
+		);
+
+		await runCollect(setup, {});
+
+		expect(setup.port.collectArm).toHaveBeenCalledWith(["own-1"]);
+	});
+
+	it("只有 lifetime 债权时缺省 collect 立即空返回（排除后等待集为空，不挂满超时）", async () => {
+		setup.entries.push(makeRegisterEntry("sm-life", { type: "session", kind: "lifetime" }));
+
+		const res = await runCollect(setup, {});
+
+		expect(res.details).toEqual({ collected: [], stillOpen: [] });
+		expect(setup.port.collectArm).not.toHaveBeenCalled();
+	});
+
+	it("快照 ready 合并进 collected（已完成收取，读侧快照；无等待则不订阅到达回调）", async () => {
+		setup.entries.push(makeRegisterEntry("w-1"));
+		setup.port.collectArm.mockReturnValue([
+			{ id: "w-1", state: "ready", entry: { type: "workflow", outcome: "completed", content: "done!" } },
+		]);
+
+		const res = await runCollect(setup, {});
+
+		expect(res.details.collected).toEqual([
+			{ id: "w-1", type: "workflow", outcome: "completed", content: "done!" },
+		]);
+		expect(res.details.stillOpen).toEqual([]);
+		expect(setup.port.onCollectArrival).not.toHaveBeenCalled();
+		// 快照收取不写新终局（读侧快照），但等待集登记须解散
+		expect(setup.port.consume).toHaveBeenCalled();
+		expect(setup.port.collectRelease).toHaveBeenCalled();
+	});
+
+	it("in-push-pipeline → stillOpen 附 note（不收取不等待）", async () => {
+		setup.entries.push(makeRegisterEntry("w-2"));
+		setup.port.collectArm.mockReturnValue([{ id: "w-2", state: "in-push-pipeline" }]);
+
+		const res = await runCollect(setup, {});
+
+		expect(res.details.collected).toEqual([]);
+		expect(res.details.stillOpen).toEqual([
+			{ id: "w-2", note: expect.stringContaining("push pipeline") },
+		]);
+		expect(setup.port.collectRelease).toHaveBeenCalled();
+	});
+
+	it("第四态 unregistered-no-entry 返回形态：outcome=注销 status + note、无 content、不虚构载荷", async () => {
+		setup.entries.push(makeRegisterEntry("sm-1"));
+		setup.port.collectArm.mockReturnValue([
+			{
+				id: "sm-1",
+				state: "unregistered-no-entry",
+				entry: { type: "session", outcome: "cancelled", note: "settled via unregister entry, no payload" },
+			},
+		]);
+
+		const res = await runCollect(setup, {});
+
+		expect(res.details.collected).toEqual([
+			{ id: "sm-1", type: "session", outcome: "cancelled", note: "settled via unregister entry, no payload" },
+		]);
+		expect("content" in res.details.collected[0]).toBe(false);
+	});
+
+	it("到达等待路径：collectArm 等待 → 到达回调 consume → 全键到齐返回 collected 并解散等待集", async () => {
+		setup.entries.push(makeRegisterEntry("w-1"));
+		setup.port.collectArm.mockReturnValue([{ id: "w-1", state: "waiting" }]);
+
+		const promise = runCollect(setup, {});
+		// execute 同步段已跑到 await（collectArm + onCollectArrival 订阅完成）
+		const arrivalCb = setup.port.onCollectArrival.mock.calls[0][0] as () => void;
+		const unsubscribe = setup.port.onCollectArrival.mock.results[0].value as ReturnType<typeof vi.fn>;
+		// 端口 consume 的真实返回形态（MF-1-6）：只含 {id, content, details}——type/outcome
+		// 由工具侧终局回填（register entry 在册 → type；注销不在册 → outcome 缺省）
+		setup.port.consume.mockReturnValueOnce([
+			{ id: "w-1", content: "payload" },
+		]);
+
+		arrivalCb();
+		const res = await promise;
+
+		expect(res.details.collected).toEqual([
+			{ id: "w-1", type: "workflow", content: "payload" },
+		]);
+		expect(res.details.stillOpen).toEqual([]);
+		expect(setup.port.collectRelease).toHaveBeenCalledTimes(1);
+		expect(unsubscribe).toHaveBeenCalledTimes(1);
+	});
+
+	it("[同步到达 outcome 回填] 等待中到达的条目：consume 时点注销未落盘 outcome 取空，返回组装前从注销 entry 回填（U1）", async () => {
+		// 时序镜像（managed flushBatch，watch-coordinator.ts:323-329）：deliver（到达
+		// 回调在 deliver 栈内同步触发 pullArrived→consume，此刻注销 entry 未落盘）→
+		// 同步段后半 unregisterPending 落盘 → await 恢复后回填生效。
+		setup.entries.push(makeRegisterEntry("sm-1", { type: "session" }));
+		setup.port.collectArm.mockReturnValue([{ id: "sm-1", state: "waiting" }]);
+
+		const promise = runCollect(setup, {});
+		const arrivalCb = setup.port.onCollectArrival.mock.calls[0][0] as () => void;
+		// 端口 consume 的真实返回形态：载荷在、type/outcome 取不到（注销尚未落盘——
+		// register 已落盘但本用例镜像 deliver 栈内时点，mock 按最简形态不给 type）
+		setup.port.consume.mockReturnValueOnce([
+			{ id: "sm-1", content: "2 queued messages done", details: { fulfills: 2 } },
+		]);
+
+		arrivalCb(); // deliver 同步栈前半：consume 取走载荷，outcome 缺失
+		setup.handlers.pendingUnregister!({ id: "sm-1", reason: "completed" }); // 同步栈后半：注销落盘（listener 走 mapReasonToStatus）
+
+		const res = await promise;
+
+		expect(res.details.collected).toEqual([
+			{ id: "sm-1", type: "session", outcome: "completed", content: "2 queued messages done", details: { fulfills: 2 } },
+		]);
+		// 注销 entry 已由真实 listener 落盘（回填源在本 session entries 现算）
+		expect(
+			setup.entries.some((e) => e.customType === "pending:unregister" && e.data.id === "sm-1"),
+		).toBe(true);
+	});
+
+	it("[outcome 回填反向断言] 注销 entry 不在册的收取条目 outcome 保持 undefined（不虚构终态）", async () => {
+		setup.entries.push(makeRegisterEntry("w-1"));
+		setup.port.collectArm.mockReturnValue([{ id: "w-1", state: "waiting" }]);
+
+		const promise = runCollect(setup, {});
+		const arrivalCb = setup.port.onCollectArrival.mock.calls[0][0] as () => void;
+		setup.port.consume.mockReturnValueOnce([
+			{ id: "w-1", content: "payload without unregister" },
+		]);
+
+		arrivalCb();
+		const res = await promise;
+
+		expect(res.details.collected).toEqual([
+			{ id: "w-1", type: "workflow", outcome: undefined, content: "payload without unregister" },
+		]);
+	});
+
+	it("超时路径：已收部分进 collected、未完成进 stillOpen（诚实返回，不抛错）", async () => {
+		setup.entries.push(makeRegisterEntry("fast"), makeRegisterEntry("slow"));
+		setup.port.collectArm.mockReturnValue([
+			{ id: "fast", state: "waiting" },
+			{ id: "slow", state: "waiting" },
+		]);
+
+		const promise = runCollect(setup, { timeout_ms: 5_000 });
+		const arrivalCb = setup.port.onCollectArrival.mock.calls[0][0] as () => void;
+		setup.port.consume
+			.mockReturnValueOnce([{ id: "fast", content: "fast done" }])
+			.mockReturnValue([]);
+
+		arrivalCb(); // fast 到达，slow 仍等
+		await vi.advanceTimersByTimeAsync(5_000);
+		const res = await promise;
+
+		expect(res.details.collected).toEqual([{ id: "fast", type: "workflow", content: "fast done" }]);
+		expect(res.details.stillOpen).toEqual([{ id: "slow" }]);
+		expect(setup.port.collectRelease).toHaveBeenCalledTimes(1);
+	});
+
+	it("timeout_ms 缺省 = 3_600_000（量级决策 §3.3：缺省 1h 前不判超时）", async () => {
+		setup.entries.push(makeRegisterEntry("w-1"));
+		setup.port.collectArm.mockReturnValue([{ id: "w-1", state: "waiting" }]);
+
+		const promise = runCollect(setup, {});
+		await vi.advanceTimersByTimeAsync(3_599_999);
+		// 最后一毫秒之前：缺省超时 timer 仍在（未判超时）
+		expect(vi.getTimerCount()).toBe(1);
+
+		await vi.advanceTimersByTimeAsync(1);
+		const res = await promise;
+		expect(res.details.stillOpen).toEqual([{ id: "w-1" }]);
+	});
+
+	it("abort 捕获后正常 return（禁抛错路径）：已收部分返回、未收进 stillOpen", async () => {
+		setup.entries.push(makeRegisterEntry("w-1"), makeRegisterEntry("w-2"));
+		setup.port.collectArm.mockReturnValue([
+			{ id: "w-1", state: "waiting" },
+			{ id: "w-2", state: "waiting" },
+		]);
+		const controller = new AbortController();
+
+		const promise = runCollect(setup, {}, controller.signal);
+		const arrivalCb = setup.port.onCollectArrival.mock.calls[0][0] as () => void;
+		setup.port.consume
+			.mockReturnValueOnce([{ id: "w-1", content: "partial" }])
+			.mockReturnValue([]);
+
+		arrivalCb(); // w-1 到达
+		controller.abort(); // 用户打断
+		const res = await promise; // 不抛错即通过
+
+		expect(res.details.collected).toEqual([{ id: "w-1", type: "workflow", content: "partial" }]);
+		expect(res.details.stillOpen).toEqual([{ id: "w-2" }]);
+		expect(setup.port.collectRelease).toHaveBeenCalledTimes(1);
+	});
+
+	it("调用前已 aborted 的 signal：直接返回、不订阅到达回调", async () => {
+		setup.entries.push(makeRegisterEntry("w-1"));
+		setup.port.collectArm.mockReturnValue([{ id: "w-1", state: "waiting" }]);
+		const controller = new AbortController();
+		controller.abort();
+
+		const res = await runCollect(setup, {}, controller.signal);
+
+		expect(res.details.stillOpen).toEqual([{ id: "w-1" }]);
+		expect(setup.port.onCollectArrival).not.toHaveBeenCalled();
+		expect(setup.port.collectRelease).toHaveBeenCalledTimes(1);
+	});
+
+	it("未知 id → errors 逐条列出、不阻断已知子集（collectArm 收全量键，unknown 态由端口定态回流）", async () => {
+		setup.entries.push(makeRegisterEntry("w-1"));
+		setup.port.collectArm.mockReturnValue([
+			{ id: "w-1", state: "waiting" },
+			{ id: "ghost", state: "unknown" },
+		]);
+
+		const promise = runCollect(setup, { ids: ["w-1", "ghost", "ghost"] });
+		const arrivalCb = setup.port.onCollectArrival.mock.calls[0][0] as () => void;
+		setup.port.consume.mockReturnValueOnce([{ id: "w-1", content: "ok" }]);
+
+		arrivalCb();
+		const res = await promise;
+
+		// 已知子集照常等待并收取；显式 ids 全量（去重）交端口定态（MF-1-5：未知判定单点在端口）
+		expect(setup.port.collectArm).toHaveBeenCalledWith(["w-1", "ghost"]);
+		expect(res.details.collected).toEqual([{ id: "w-1", type: "workflow", content: "ok" }]);
+		// 未知 id 去重后逐条列出
+		expect(res.details.errors).toEqual([
+			{ id: "ghost", reason: expect.stringContaining("unknown id") },
+		]);
+		expect(res.content[0].text).toContain("ghost");
+	});
+
+	it("全部 ids 未知 → 立即返回 errors（collectArm 定态全 unknown，不进入等待）", async () => {
+		setup.port.collectArm.mockReturnValue([
+			{ id: "ghost-a", state: "unknown" },
+			{ id: "ghost-b", state: "unknown" },
+		]);
+
+		const res = await runCollect(setup, { ids: ["ghost-a", "ghost-b"] });
+
+		expect(res.details.collected).toEqual([]);
+		expect(res.details.stillOpen).toEqual([]);
+		expect(res.details.errors).toHaveLength(2);
+		// 未知键不登记等待集：不订阅到达回调、不挂满超时
+		expect(setup.port.onCollectArrival).not.toHaveBeenCalled();
+		expect(setup.port.collectArm).toHaveBeenCalledWith(["ghost-a", "ghost-b"]);
+	});
+
+	it("已完结 id（register+unregister 在册）不算未知 → collectArm 收键（第四态/快照收取入口）", async () => {
+		setup.entries.push(
+			makeRegisterEntry("done-1"),
+			{ customType: "pending:unregister", data: { id: "done-1", reason: "completed", status: "completed" } },
+		);
+		setup.port.collectArm.mockReturnValue([
+			{
+				id: "done-1",
+				state: "unregistered-no-entry",
+				entry: { type: "workflow", outcome: "completed", note: "no payload" },
+			},
+		]);
+
+		const res = await runCollect(setup, { ids: ["done-1"] });
+
+		expect(setup.port.collectArm).toHaveBeenCalledWith(["done-1"]);
+		expect(res.details.errors).toBeUndefined();
+		expect(res.details.collected).toEqual([
+			{ id: "done-1", type: "workflow", outcome: "completed", note: "no payload" },
+		]);
+	});
+
+	it("重复收取 = 快照重收：同 id 二次 collect 再次返回原载荷（工具侧无拒绝分支）", async () => {
+		setup.entries.push(makeRegisterEntry("w-1"));
+		setup.port.collectArm.mockReturnValue([
+			{ id: "w-1", state: "ready", entry: { type: "workflow", outcome: "completed", content: "payload" } },
+		]);
+
+		const first = await runCollect(setup, { ids: ["w-1"] });
+		const second = await runCollect(setup, { ids: ["w-1"] });
+
+		expect(first.details.collected).toEqual(second.details.collected);
+	});
+
+	it("port 缺席（槽未装配）→ 正常返回不可用文案 + 不抛错", async () => {
+		portMocks.getDeliveryPort.mockReturnValue(undefined);
+		setup.entries.push(makeRegisterEntry("w-1"));
+
+		const res = await runCollect(setup, {});
+
+		expect(res.details.collected).toEqual([]);
+		expect(res.details.stillOpen).toEqual([]);
+		expect(res.content[0].text).toContain("unavailable");
+	});
+
+	it("content 文本承载收取载荷（collected content 随文本到达 agent）", async () => {
+		setup.entries.push(makeRegisterEntry("w-1"));
+		setup.port.collectArm.mockReturnValue([
+			{ id: "w-1", state: "ready", entry: { type: "workflow", outcome: "completed", content: "result body" } },
+		]);
+
+		const res = await runCollect(setup, {});
+
+		expect(res.content[0].text).toContain("w-1");
+		expect(res.content[0].text).toContain("result body");
+	});
+});
+
+// ────────────────────────────────────────────────────
+// kind 读取链写侧落点（pending:register listener 落盘透传）
+// ────────────────────────────────────────────────────
+
+describe("pending:register kind 透传（lifetime 标记落盘）", () => {
+	let setup: MockSetup;
+
+	beforeEach(() => {
+		vi.useFakeTimers();
+		vi.setSystemTime(NOW);
+		setup = createMockSetup();
+		pendingNotificationsExtension(setup.pi);
+		fireSessionStart(setup);
+	});
+
+	afterEach(() => {
+		portMocks.getDeliveryPort.mockReset();
+		vi.useRealTimers();
+	});
+
+	it("register event 带 kind=lifetime → 落盘 entry data 透传 kind；读取侧归一化回读", () => {
+		setup.handlers.pendingRegister!({ id: "sm-life", type: "session", name: "ms", kind: "lifetime" });
+
+		const regCall = setup.appendEntryMock.mock.calls.find((c) => c[0] === "pending:register");
+		expect(regCall).toBeDefined();
+		expect(regCall![1]).toMatchObject({ id: "sm-life", kind: "lifetime" });
+
+		// 读取链闭环：normalizeRegisterEntry 白名单透传后工具侧可读到 kind
+		const res = countActiveFromEntries(setup.entries as unknown[]);
+		expect(res.entries[0].kind).toBe("lifetime");
+	});
+
+	it("register event 不带 kind → 落盘 entry 无 kind 键（非 managed 注册零字段增量）", () => {
+		setup.handlers.pendingRegister!({ id: "w-1", type: "workflow", name: "op" });
+
+		const regCall = setup.appendEntryMock.mock.calls.find((c) => c[0] === "pending:register");
+		expect("kind" in regCall![1]).toBe(false);
+	});
+
+	it("register event kind 值不在白名单（如未来新值）→ 不透传（缺省 send 债权语义）", () => {
+		setup.handlers.pendingRegister!({ id: "w-x", type: "session", name: "ms", kind: "future-kind" });
+
+		const regCall = setup.appendEntryMock.mock.calls.find((c) => c[0] === "pending:register");
+		expect("kind" in regCall![1]).toBe(false);
+	});
+});

package/src/__tests__/pending-notifications.test.ts

@@ -157,7 +157,7 @@ describe("state pure functions", () => {
 	});
 });
 
-describe("countActiveFromEntries（纯差集，供 goal / subagent-workflow / 工具投影复用）", () => {
+describe("countActiveFromEntries（纯差集，供 goal / subagent-workflow / 工具派生视图复用）", () => {
 	const mkRegister = (id: string, type: "subagent" | "workflow" = "subagent", overrides: Record<string, unknown> = {}) => ({
 		type: "custom",
 		customType: "pending:register",
@@ -201,7 +201,7 @@ describe("countActiveFromEntries（纯差集，供 goal / subagent-workflow /
 		expect(countActiveFromEntries(entries, { types: ["subagent", "workflow"] }).count).toBe(2);
 	});
 
-	it("TTL 过期仍判活跃（刻意不校验 expiresAt，对齐 goal continuation 守卫语义）", () => {
+	it("TTL 过期仍判活跃（刻意不校验 expiresAt，对齐 goal continuation 检查语义）", () => {
 		const expired = mkRegister("bg-1", "subagent", { registeredAt: 0, expiresAt: 1 });
 		expect(countActiveFromEntries([expired]).count).toBe(1);
 	});
@@ -212,12 +212,12 @@ describe("countActiveFromEntries（纯差集，供 goal / subagent-workflow /
 
 	it("entries 含 null/undefined 元素 → 跳过不抛 TypeError（S-10）", () => {
 		// S-10 回归：外部调用方可能传入含 null/undefined 的 entries（session 文件坏行/脏数据），
-		// 遍历时访问 raw.customType 前必须守卫，否则 TypeError 炸掉整个差集判定。
+		// 遍历时访问 raw.customType 前必须检查，否则 TypeError 炸掉整个差集判定。
 		const withNulls = [null, undefined, mkRegister("bg-1"), mkUnregister("bg-1"), null];
 		expect(countActiveFromEntries(withNulls).count).toBe(0);
 		const mixed = [undefined, null, mkRegister("bg-2")];
 		expect(countActiveFromEntries(mixed).ids).toEqual(["bg-2"]);
-		// register 循环同样守卫：unregister 遍历前的 null 不污染差集
+		// register 循环同样检查：unregister 遍历前的 null 不污染差集
 		expect(countActiveFromEntries([null, undefined]).count).toBe(0);
 	});
 
@@ -323,8 +323,8 @@ describe("pendingNotificationsExtension factory", () => {
 			expect(await getCount(setup)).toBe(0);
 		});
 
-		it("[跨 session 残留] other session 的 register → 不进投影、不补 unregister entry", async () => {
-			// fork 继承的父级注册残留不进差集（currentSessionId 过滤），且落盘收口归
+		it("[跨 session 残留] other session 的 register → 不进派生视图、不补 unregister entry", async () => {
+			// fork 继承的父级注册残留不进差集（currentSessionId 过滤），且落盘收尾归
 			// 对账通道——本包不做任何补写。
 			setup.entries.push(makeRegisterEntry("w-1", { sessionId: "sess-old" }));
 			fireSessionStart(setup, "sess-current");
@@ -478,7 +478,7 @@ describe("pendingNotificationsExtension factory", () => {
 	describe("safeAppendEntry error handling", () => {
 		it("appendEntry throwing (stale context) does not break listener; entries and query stay consistent", async () => {
 			// 单一权威源语义：落盘失败 → entries 没有该注册 → 工具同样查不到（不再出现
-			// 「内存已收、盘上没有」的工具/守卫分裂）；listener 不被异常打断，后续注册正常。
+			// 「内存已收、盘上没有」的工具/检查分裂）；listener 不被异常打断，后续注册正常。
 			fireSessionStart(setup);
 			setup.appendEntryMock.mockImplementationOnce(() => {
 				throw new Error("stale context");
@@ -516,7 +516,7 @@ describe("pendingNotificationsExtension factory", () => {
 		});
 	});
 
-	describe("写入侧落盘契约与跨 session 投影", () => {
+	describe("写入侧落盘契约与跨 session 派生视图", () => {
 		it("register 落盘契约：data 含 id/type/name/registeredAt/sessionId，无条件无 expiresAt 键（bash）", async () => {
 			fireSessionStart(setup);
 
@@ -542,10 +542,10 @@ describe("pendingNotificationsExtension factory", () => {
 			expect("expiresAt" in data).toBe(false);
 		});
 
-		it("[fork 过滤] 子 session 工具投影不见父 session 注册，父残留不被补注销", async () => {
+		it("[fork 过滤] 子 session 工具派生视图不见父 session 注册，父残留不被补注销", async () => {
 			// fork 子 session（继承父 entries）：父级注册（sessionId=sess-parent）不进
-			// 子 session 投影（currentSessionId 过滤），且本包不为残留补写任何 entry
-			//（落盘收口归 core 对账 sweep / bte 对账通道）。
+			// 子 session 派生视图（currentSessionId 过滤），且本包不为残留补写任何 entry
+			//（落盘收尾归 core 对账 sweep / bte 对账通道）。
 			setup.entries.push({
 				customType: "pending:register",
 				data: { id: "bg-parent", type: "subagent", name: "p", registeredAt: NOW, sessionId: "sess-parent" },

package/src/index.ts

@@ -4,7 +4,8 @@
  * 设计定位：为长耗时异步操作（workflow/subagent/bash 后台任务）提供跨 extension 的
  * 活跃操作注册/查询机制。workflow/subagent/bash 运行时通过 EventBus（pi.events.emit）
  * 广播 register/unregister，本扩展监听这些事件、将状态写入 session entries（pi.appendEntry），
- * 供 LLM 通过 pending_notifications 工具主动查询当前活跃异步操作
+ * 供 LLM 通过 pending_notifications 工具主动查询当前活跃异步操作、通过 collect_results
+ * 工具批量阻塞收取结果（result-collect 设计 §3.1③）
  * （goal 不在 before_agent_start 注入等待消息——避免双信息源，pending 感知由 LLM 自行查询）。
  *
  * 文件职责：
@@ -16,7 +17,7 @@
  * ① subagent-core——notify-host.ts（register + record 终态化 unregister——finalizeRun
  *   直落后的残留发射面，观测通道 = sweep reconciled WARN）/ orchestration/lifecycle.ts
  *   （register 主链）；
- * ② base-tool-enhance——bash 投影（notify.ts register/unregister 主链 +
+ * ② base-tool-enhance——bash 派生视图（notify.ts register/unregister 主链 +
  *   process-exit-guard.ts 退出边沿尽力补 emit（pending-reconcile 对账走 appendEntry
  *   权威路径，不经 emit））；
  * ③ subagent-workflow——仅崩溃恢复时 emit pending:unregister（session-lifecycle.ts
@@ -34,10 +35,12 @@
  * - base-tool-enhance pending-reconcile.ts（session_start 对账，同款）。
  *
  * entry 契约（与 goal before-agent-start.ts 对齐，读取端按 e.data.id 算差集）：
- * - pending:register → { id, type, name, registeredAt, sessionId }
+ * - pending:register → { id, type, name, registeredAt, sessionId, kind? }
+ *   （kind 可选 = managed lifetime 债权标记，session-manager 写侧申报、本 listener
+ *   白名单透传落盘——collect_results 缺省等待集排除依据，result-collect 设计 §3.4）
  * - pending:unregister → { id, reason, status }
  *
- * 状态权威源：session entries 是唯一状态——工具投影与写侧去重/活跃判断全部对
+ * 状态权威源：session entries 是唯一状态——工具派生视图与写侧去重/活跃判断全部对
  * getEntries() 现算（appendEntry 同步入账，pi dist 实证，锚定 pi-semantics
  * PS-29 extensionAPI appendEntry 直委托 appendCustomEntry + PS-17 _appendEntry
  * 同步 push 无 debounce），无内存第二份状态；历史的内存 registry、
@@ -48,22 +51,33 @@
  */
 
 import type { ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
-import { mapReasonToStatus as mapReasonToStatusImpl } from "@zhushanwen/extension-protocol";
+import {
+	mapReasonToStatus as mapReasonToStatusImpl,
+	scanPendingFields,
+} from "@zhushanwen/extension-protocol";
+import {
+	getDeliveryPort,
+	type CollectedEntry,
+	type CollectSnapshot,
+	type DeliveryPortHandle,
+} from "@zhushanwen/pi-delivery-port";
 import { getLogger } from "@zhushanwen/pi-extension-logger";
 import { Type } from "typebox";
 
 import {
+	computeCollectWaitKeys,
 	countActiveFromEntries,
 	hasPendingId,
 	isPendingActive,
 	normalizePendingType,
 	type PendingEntry,
+	type PendingKind,
 	type PendingStatus,
 	type PendingType,
 } from "./state.ts";
 import { renderPendingNotificationsResult } from "./render-result.ts";
 
-// 跨扩展消费 API：goal（continuation 守卫）/ subagent-workflow（agent_end 后代判定）
+// 跨扩展消费 API：goal（continuation 检查）/ subagent-workflow（agent_end 后代判定）
 // 直接 import 本包导出的 countActiveFromEntries，避免各自复制差集逻辑。导出面只保留
 // 唯一消费函数 + 其签名所需类型（entries 是唯一状态源，包内不再导出状态机 API）。
 export {
@@ -94,6 +108,52 @@ interface PendingToolDetails {
 	summary: string;
 }
 
+// ── collect_results（批量收取，result-collect 设计 §3.1③）─────────────
+
+/** 缺省超时（设计 §3.3 量级决策：任务级对象 → 小时量级。非墙钟判死——超时是等待器的
+ *  诚实返回：任务不受影响、stillOpen 列出、恢复 push、可续 collect。偏离「任务级缺省
+ *  不限时」的原因与论证登记在设计 §3.3，工具描述引导 agent 按预期时长显式传参）。 */
+const COLLECT_DEFAULT_TIMEOUT_MS = 3_600_000;
+
+/** collect_results 工具参数 schema */
+const CollectResultsParams = Type.Object({
+	ids: Type.Optional(Type.Array(Type.String())),
+	timeout_ms: Type.Optional(Type.Number()),
+});
+
+/** stillOpen 条目：未收取的等待键（note 标记特殊态，如已入 push 管线）。 */
+interface StillOpenEntry {
+	id: string;
+	note?: string;
+}
+
+/** errors 条目：未知 id（判定源 = 活跃集 ∪ 投递日志键集 ∪ 曾注册集 的补集），逐条列出不阻断已知子集。 */
+interface CollectErrorEntry {
+	id: string;
+	reason: string;
+}
+
+/** collect_results 工具的 details 形状（与返回契约同构，结构化消费方）。 */
+interface CollectToolDetails {
+	collected: CollectedEntry[];
+	stillOpen: StillOpenEntry[];
+	errors?: CollectErrorEntry[];
+}
+
+/** collect_results 工具描述（缺省口径 + lifetime 排除 + managed 全键返回形态 + timeout
+ *  缺省值引导显式传参 + 反模式（勿当活性检查用、只关心特定操作勿省略 ids）+
+ *  与 pending_notifications 分工声明，result-collect 设计 §3.1③/§3.4 工具描述更新项）。 */
+const COLLECT_RESULTS_DESCRIPTION = [
+	"Block and batch-collect results of background async operations (workflow / subagent / bash background tasks / managed session claims), instead of receiving one notification per completion.",
+	"Returns collected (entries: {id, type, outcome, content, details}), stillOpen (not collected: {id, note?}) and errors (unknown ids, listed individually without blocking the known subset).",
+	"ids: target operation ids (as returned when dispatching background tasks). Omitted = every active pending operation of the current session, EXCLUDING managed-session lifetime claims (alive-markers that only settle when the session dies — waiting on them would hang until timeout) and registrations inherited from a forked parent session.",
+	"timeout_ms: max wait in milliseconds, default 3600000 (1 hour). Pass a value matched to the expected task duration (e.g. 120000 for short tasks). On timeout the already-arrived results are returned; the rest stay in stillOpen and notify normally (push) when they complete.",
+	"A managed-session batched notification matched by any of its keys returns one entry per key of that batch (same payload shared). Collecting an already-collected id again returns its snapshot (no duplicate injection). Interruption (timeout / user abort) returns normally with the arrived subset.",
+	"Do NOT use this tool as a liveness or status check — it blocks the current turn until results arrive or timeout_ms elapses. Immediate status queries go to pending_notifications (list).",
+	"DO NOT omit ids when you only care about specific operations — the default wait set blocks on every active non-lifetime pending operation of this session at once.",
+	"Division of labor: pending_notifications (list) is the immediate status query; collect_results is the blocking wait — use it only when the next step actually needs those results.",
+].join("\n");
+
 /**
  * 模块级 EventBus 监听器 unsubscribe 函数列表。
  *
@@ -122,7 +182,7 @@ export default function pendingNotificationsExtension(pi: ExtensionAPI): void {
 	unsubscribers = [];
 
 	// ── 闭包内状态 ─────
-	// entries 是唯一状态源（无内存状态副本）：currentSessionId 是查询投影的跨 session
+	// entries 是唯一状态源（无内存状态副本）：currentSessionId 是查询派生视图的跨 session
 	// 过滤基准；sessionManager 是 listener 写侧前置判断的 entries 读取通道（EventBus
 	// 回调无 ctx 参数，经 session_start 缓存持有）。
 	let currentSessionId: string = "";
@@ -183,6 +243,9 @@ export default function pendingNotificationsExtension(pi: ExtensionAPI): void {
 			name: parsed.name,
 			registeredAt: Date.now(),
 			sessionId: currentSessionId,
+			// lifetime 债权标记落盘透传（result-collect 设计 §3.4 kind 读取链写侧落点；
+			// 无标记条目形状不变——非 managed 注册零字段增量）
+			...(parsed.kind ? { kind: parsed.kind } : {}),
 		});
 
 		debugLog("debug", "listener: pending:register appended", { id: parsed.id });
@@ -268,6 +331,219 @@ export default function pendingNotificationsExtension(pi: ExtensionAPI): void {
 			return renderPendingNotificationsResult(result, options, theme);
 		},
 	});
+
+	// ── 批量收取 tool（result-collect 设计 §3.1③）─────────────────────
+	pi.registerTool({
+		name: "collect_results",
+		label: "Collect Results",
+		description: COLLECT_RESULTS_DESCRIPTION,
+		parameters: CollectResultsParams,
+		// 任一时刻至多一个在途 collect（设计前提 P2：同批任一工具声明 sequential 即整批
+		// 串行）——多在途等待集的跨集判重预案因此不需要。
+		executionMode: "sequential",
+		execute: async (
+			_toolCallId: string,
+			params: { ids?: string[]; timeout_ms?: number },
+			signal: AbortSignal | undefined,
+			_onUpdate: unknown,
+			ctx: ExtensionContext,
+		): Promise<{ content: { type: "text"; text: string }[]; details: CollectToolDetails }> =>
+			collectResults(params, signal, ctx),
+	});
+
+	/** collect_results 执行体（工厂闭包：读 currentSessionId 缺省集过滤基准）。
+	 *
+	 * 执行序（设计 §3.1③）：等待键集计算 → collectArm（端口同步段登记 + 五态快照）→
+	 * 快照合并组装（ready ∪ unregistered-no-entry 进 collected；in-push-pipeline 进
+	 * stillOpen 附 note；waiting 留守）→ await 到达/超时/abort 三者先到 → consume +
+	 * collectRelease → 返回。AbortSignal 捕获后正常 return（禁抛错路径——pi 契约下抛错
+	 * 会把已写 collected 终局的载荷随返回丢失，收取即丢失，设计 §3.1 [abort]）。
+	 */
+	async function collectResults(
+		params: { ids?: string[]; timeout_ms?: number },
+		signal: AbortSignal | undefined,
+		ctx: ExtensionContext,
+	): Promise<{ content: { type: "text"; text: string }[]; details: CollectToolDetails }> {
+		const entries = ctx.sessionManager.getEntries();
+		const timeoutMs = params.timeout_ms ?? COLLECT_DEFAULT_TIMEOUT_MS;
+
+		// 等待键集：显式 ids 全量交端口五态判决定态（unknown 态键由快照回流进
+		// errors，MF-1-5：未知判定单点在端口——工具侧不再重扫 entries 算「活跃集 ∪
+		// 曾注册集」补集）；缺省 = computeCollectWaitKeys（活跃 − lifetime 死亡债权
+		// − 跨 session 残留，currentSessionId 空串回退同款）。
+		let waitKeys: string[];
+		if (params.ids) {
+			waitKeys = [...new Set(params.ids)];
+		} else {
+			waitKeys = computeCollectWaitKeys(entries, currentSessionId);
+		}
+
+		// 等待集为空：立即返回，不进入等待、不触端口（设计 §3.1③ 边界语义）。显式
+		// ids 全量交端口定态后空集只剩两种形态（空数组 / 缺省集空），均不产 errors。
+		if (waitKeys.length === 0) {
+			const details: CollectToolDetails = { collected: [], stillOpen: [] };
+			debugLog("debug", "collect_results: empty wait set, returning immediately");
+			return { content: [{ type: "text" as const, text: formatCollectDetails(details) }], details };
+		}
+
+		// 槽缺席降级（base-tool-enhance session_start 装配缺失的异常窗口，生产不可达常态；
+		// STANDARDS §11.1 通知类接入点降级非静默吞）：warn 留痕 + 正常返回（不抛错，
+		// 错误文本指向恢复动作 = 下次 session_start 重试装配后重试）。
+		const port = getDeliveryPort();
+		if (!port) {
+			logger.warn(
+				"[pending-notifications] collect_results: delivery port not bound — collect unavailable (base-tool-enhance session_start 装配缺失)",
+				{ waitKeys },
+			);
+			return {
+				content: [
+					{
+						type: "text" as const,
+						text: "collect_results unavailable: delivery port not bound (assembly missing). Retry after the session finishes starting (session_start rebinds the port).",
+					},
+				],
+				details: { collected: [], stillOpen: [] },
+			};
+		}
+
+		// collectArm：端口同步段登记等待集 + 五态快照（每 key 一条；unknown 态 =
+		// 端口未知判定单点回流）。
+		const snapshot = port.collectArm(waitKeys);
+		const collected: CollectedEntry[] = [];
+		const stillOpen: StillOpenEntry[] = [];
+		const waitingIds: string[] = [];
+		const unknownIds: string[] = [];
+		partitionCollectSnapshot(snapshot, { collected, stillOpen, waitingIds, unknownIds });
+		const errors: CollectErrorEntry[] = unknownIds.map((id) => ({
+			id,
+			reason: "unknown id — not an active pending operation and never registered in this session",
+		}));
+
+		// 到达等待：事件驱动（onCollectArrival）不轮询；到达/超时/abort 三者先到。
+		// 完成判据 = 全部等待键出现在已收取集合（到达即 consume 取走载荷+终局）。
+		await awaitCollectArrivals(port, waitingIds, collected, timeoutMs, signal);
+
+		// 终局序列（设计 §3.1③）：consume 取走剩余已到达挂起条目（超时/abort 路径的
+		// 部分收取），collectRelease 解散等待集并把未收挂起条目直通内核 flush（跳过
+		// 合批窗口，恢复 push）。空等待路径不会走到这里（提前返回）。
+		collected.push(...port.consume());
+		port.collectRelease();
+
+		// type/outcome 缺失回填（字段来源见 backfillCollectFields 注释）。
+		backfillCollectFields(ctx, collected);
+
+		// 未收取的等待键进 stillOpen（无 note = 单纯未完成，完成时恢复 push）。
+		const collectedIds = new Set(collected.map((c) => c.id));
+		for (const id of waitingIds) {
+			if (!collectedIds.has(id)) stillOpen.push({ id });
+		}
+
+		const details: CollectToolDetails = { collected, stillOpen };
+		if (errors.length > 0) details.errors = errors;
+		debugLog("debug", "collect_results: returning", {
+			collected: collected.length,
+			stillOpen: stillOpen.length,
+			errors: errors.length,
+		});
+		return { content: [{ type: "text" as const, text: formatCollectDetails(details) }], details };
+	}
+
+	/** 快照五态分流（§3.1③）：ready ∪ unregistered-no-entry 进 collected；in-push-pipeline
+	 * 进 stillOpen 附 note；waiting 留守；unknown 逐条回流（错误组装在调用方）。 */
+	function partitionCollectSnapshot(
+		snapshot: CollectSnapshot,
+		buckets: {
+			collected: CollectedEntry[];
+			stillOpen: StillOpenEntry[];
+			waitingIds: string[];
+			unknownIds: string[];
+		},
+	): void {
+		for (const snap of snapshot) {
+			switch (snap.state) {
+				case "ready":
+				case "unregistered-no-entry":
+					// 快照收取：ready = 日志条目已有终局的读侧快照（不写新终局）；
+					// unregistered-no-entry = 第四态无载荷有限信息形态（outcome 取注销
+					// status、note 说明来源，端口侧组装）。两态的 entry 契约在册。
+					buckets.collected.push({ id: snap.id, ...(snap.entry ?? {}) });
+					break;
+				case "in-push-pipeline":
+					// 已过分流点、在 push 管线排队待注入：不收取（收取后再注入 = 双重呈现）
+					// 不等待（等其终局 = 等待源与阻塞源互等自锁）——附 note 进 stillOpen。
+					buckets.stillOpen.push({
+						id: snap.id,
+						note: "already queued in the push pipeline — will be delivered as a normal notification after this tool returns",
+					});
+					break;
+				case "waiting":
+					buckets.waitingIds.push(snap.id);
+					break;
+				case "unknown":
+					// 未知 id（端口五态判据单点判定）：逐条列出、不阻断已知子集。
+					buckets.unknownIds.push(snap.id);
+					break;
+			}
+		}
+	}
+
+	/** 到达等待段：等待键为空立即返回；否则 consume+到达判据（全部等待键已收取）/
+	 * 超时 / abort 三者先到解除（abort 捕获后正常 return，不抛错——抛错会把已写
+	 * collected 终局的载荷随返回丢失，§3.1 [abort]）。 */
+	async function awaitCollectArrivals(
+		port: DeliveryPortHandle,
+		waitingIds: readonly string[],
+		collected: CollectedEntry[],
+		timeoutMs: number,
+		signal: AbortSignal | undefined,
+	): Promise<void> {
+		if (waitingIds.length === 0) return;
+		await new Promise<void>((resolve) => {
+			let settled = false;
+			let timer: ReturnType<typeof setTimeout> | undefined = undefined;
+			let unsubscribeArrival: () => void = () => {};
+			const onAbort = () => finish();
+			const finish = () => {
+				if (settled) return;
+				settled = true;
+				if (timer !== undefined) clearTimeout(timer);
+				signal?.removeEventListener("abort", onAbort);
+				unsubscribeArrival();
+				resolve();
+			};
+			const pullArrived = () => {
+				collected.push(...port.consume());
+				const collectedIds = new Set(collected.map((c) => c.id));
+				if (waitingIds.every((id) => collectedIds.has(id))) finish();
+			};
+			if (signal?.aborted) {
+				finish();
+				return;
+			}
+			timer = setTimeout(finish, timeoutMs);
+			signal?.addEventListener("abort", onAbort, { once: true });
+			unsubscribeArrival = port.onCollectArrival(pullArrived);
+		});
+	}
+
+	/** type/outcome 缺失回填（设计 §3.1③ 字段来源表：type 与 pending:register 的
+	 * type 对齐、outcome 与 pending:unregister 的 status 对齐；MF-1-6：端口 consume
+	 * 只返回 {id, content, details}，终态字段统一由本处单遍扫描回填）：「等待中
+	 * 同步到达」的挂起条目在端口 consume 时点，生产方的注销 entry 尚未落盘
+	 * （managed flushBatch 的 deliver 与 unregisterPending 同步段相邻、deliver 先
+	 * 行；端口 consume 由到达回调在 deliver 栈内同步触发），outcome 恒取空。await
+	 * 恢复后生产方同步栈已完成（注销 entry 已落盘），按本 session entries 现算回填；
+	 * 注销不在册的条目保持 undefined（诚实缺省，不虚构终态）。快照收取条目
+	 * （ready / unregistered-no-entry）的 type/outcome 已由端口 collectArm 填充，
+	 * 回填只补缺不覆盖。 */
+	function backfillCollectFields(ctx: ExtensionContext, collected: CollectedEntry[]): void {
+		if (!collected.some((c) => c.outcome === undefined || c.type === undefined)) return;
+		const fields = scanPendingFields(ctx.sessionManager.getEntries());
+		for (const c of collected) {
+			if (c.type === undefined) c.type = fields.registerTypes.get(c.id);
+			if (c.outcome === undefined) c.outcome = fields.unregisterStatuses.get(c.id);
+		}
+	}
 }
 
 // ── 事件解析 helper ─────────────────────────────────
@@ -276,6 +552,7 @@ interface ParsedRegister {
 	id: string;
 	type: PendingType;
 	name: string;
+	kind?: PendingKind;
 }
 
 /** 解析 pending:register 事件 data（容错缺失/类型错误字段） */
@@ -288,6 +565,9 @@ function parseRegisterEvent(data: unknown): ParsedRegister | null {
 		// bash 类型直通（归一化映射与 state.ts 读取侧共用同一函数，防两侧漂移）
 		type: normalizePendingType(d.type),
 		name: typeof d.name === "string" ? d.name : d.id,
+		// lifetime 标记白名单解析（result-collect 设计 §3.4；未知值不透传 = 缺省
+		// send 债权语义，与 normalizeRegisterEntry 读取侧白名单同口径防漂移）
+		...(d.kind === "lifetime" ? { kind: "lifetime" as const } : {}),
 	};
 }
 
@@ -335,3 +615,27 @@ export function buildPendingNotificationsSummary(details: {
 		? `${details.count} pending operations`
 		: `${details.count} entries listed`;
 }
+
+/** collect_results 结果的可读文本（content 通道：载荷 content 随文本到达 agent，
+ *  details 承载结构化同构副本供程序消费）。 */
+function formatCollectDetails(details: CollectToolDetails): string {
+	const lines = [
+		`collect_results: ${details.collected.length} collected, ${details.stillOpen.length} still open${
+			details.errors ? `, ${details.errors.length} unknown id(s)` : ""
+		}`,
+	];
+	for (const c of details.collected) {
+		const typeTag = c.type ? `[${c.type}] ` : "";
+		const outcomeTag = c.outcome ? ` (${c.outcome})` : "";
+		const body = c.content ? `: ${c.content}` : "";
+		const noteTag = c.note ? ` — ${c.note}` : "";
+		lines.push(`- collected ${typeTag}${c.id}${outcomeTag}${body}${noteTag}`);
+	}
+	for (const s of details.stillOpen) {
+		lines.push(`- still open: ${s.id}${s.note ? ` (${s.note})` : ""}`);
+	}
+	for (const e of details.errors ?? []) {
+		lines.push(`- unknown id: ${e.id} — ${e.reason}`);
+	}
+	return lines.join("\n");
+}

package/src/state.ts

@@ -3,8 +3,8 @@
  *
  * 职责：
  * - PendingEntry: 一个异步操作的完整描述（与 pending:register entry data 对齐）
- * - countActiveFromEntries: register − unregister 差集 = 活跃集合（goal 守卫 /
- *   subagent-workflow 后代判定 / 本包 pending_notifications 工具投影共用）
+ * - countActiveFromEntries: register − unregister 差集 = 活跃集合（goal 检查 /
+ *   subagent-workflow 后代判定 / 本包 pending_notifications 工具派生视图共用）
  * - hasPendingId / isPendingActive: 写侧落盘前置判断（register 去重 / unregister 活跃判定）
  *
  * 设计要点：
@@ -17,14 +17,27 @@
  *   结构上不可分歧
  * - 纯函数，不依赖 Pi 运行时（ExtensionAPI/appendEntry），可独立单元测试
  * - 差集刻意不校验 expiresAt（四类型（workflow/subagent/bash/session）全 process 档，长任务 >1h 仍应视为活跃，
- *   对齐 goal continuation 守卫语义）；历史 session 文件中遗留的带 expiresAt 的
+ *   对齐 goal continuation 检查语义）；历史 session 文件中遗留的带 expiresAt 的
  *   register entry 无需迁移——差集语义不读该键
  */
-import { applyPendingDiff, scanPendingEntries } from "@zhushanwen/extension-protocol";
+import {
+	applyPendingDiff,
+	scanPendingEntries,
+} from "@zhushanwen/extension-protocol";
 
 /** 异步操作类型（来源：workflow / subagent / bash 后台任务 / session 完成通知债权） */
 export type PendingType = "workflow" | "subagent" | "bash" | "session";
 
+/**
+ * managed 债权分类标记（pending:register emit 可选字段 kind，session-manager 写侧
+ * 申报，result-collect 设计 §3.4）：lifetime = 生命周期死亡债权（create_session 返回的
+ * lifetimeNotifyId，仅 session exited/deleted 时兑现、存活期恒活跃）——collect_results
+ * 缺省等待集据此排除（排除只在工具侧 computeCollectWaitKeys 做减法，countActiveFromEntries
+ * 缺省语义不动：goal/subagent-workflow 消费方仍计 lifetime 为活跃）。
+ * 无 kind 缺省 = send 债权（消息完成即兑现，缺省主场景键，不排除）。
+ */
+export type PendingKind = "lifetime";
+
 /** 异步操作终态/过渡状态。active = 仍在运行；其他都视为已结束 */
 export type PendingStatus = "active" | "completed" | "failed" | "cancelled" | "expired" | "time_limited" | "aborted";
 
@@ -42,6 +55,8 @@ export interface PendingEntry {
 	registeredAt: number;
 	/** 注册时的 sessionId（用于跨 session 残留过滤） */
 	sessionId: string;
+	/** managed 债权分类标记（可选；无标记 = send 债权缺省语义，见 PendingKind） */
+	kind?: PendingKind;
 }
 
 /** countActiveFromEntries 的过滤选项。 */
@@ -51,7 +66,7 @@ export interface CountActiveOptions {
 	/**
 	 * [跨 session 残留过滤] 当前 session id（过滤基准）：传入时按「register entry 的
 	 * sessionId ≠ 当前 session → 跳过」过滤——fork 继承的父级注册残留（永久留存于子
-	 * session 文件，落盘收口归 core 对账 sweep / bte 对账通道）不进差集计数，守卫不幻
+	 * session 文件，落盘收尾归 core 对账 sweep / bte 对账通道）不进差集计数，检查不幻
 	 * defer。缺省（undefined）= 不过滤（向后兼容：既有调用方零改动行为不变）。
 	 * entry 缺 sessionId 字段的旧形态条目视为本 session（归一化兜底语义与
 	 * normalizeRegisterEntry 一致），不过滤。
@@ -71,13 +86,13 @@ export interface CountActiveResult {
  * 从持久化 entries 计算活跃 pending 数（register − unregister 差集）。
  *
  * 只做「有没有活跃 pending」的只读判断，不产生任何写入；TTL 刻意不校验
- * （长任务 subagent >1h 仍应视为活跃，对齐 goal agent-end 的 continuation 守卫语义）。
+ * （长任务 subagent >1h 仍应视为活跃，对齐 goal agent-end 的 continuation 检查语义）。
  * 调用方：goal（agent_end 时判断是否发 continuation）、subagent-workflow
  * （agent_end 时判断子进程是否有活跃后代，决定是否保持进程等 steer 唤醒）、
- * 本包 pending_notifications 工具投影。
+ * 本包 pending_notifications 工具派生视图。
  *
  * 跨 session 残留过滤：持有当前 session 概念的调用方应传入 opts.currentSessionId，
- * 使 fork 继承的父级注册残留不进差集（守卫不幻 defer）。
+ * 使 fork 继承的父级注册残留不进差集（检查不幻 defer）。
  */
 export function countActiveFromEntries(
 	entries: unknown[],
@@ -94,6 +109,27 @@ export function countActiveFromEntries(
 	};
 }
 
+/**
+ * collect_results 的缺省等待键集（result-collect 设计 §3.1③）：
+ * 当前 session 全部活跃 pending 项（countActiveFromEntries 同口径，currentSessionId
+ * 过滤含空串回退）− managed lifetime 死亡债权（kind 标记，本函数工具侧减法——
+ * countActiveFromEntries 缺省语义不动，goal/subagent-workflow 消费方零变化）。
+ */
+export function computeCollectWaitKeys(entries: unknown[], currentSessionId: string): string[] {
+	const active = countActiveFromEntries(
+		entries,
+		currentSessionId ? { currentSessionId } : undefined,
+	).entries;
+	return active.filter((entry) => entry.kind !== "lifetime").map((entry) => entry.id);
+}
+
+/**
+ * collect 终局回填的字段视图单点在 protocol scanPendingFields（register 首见
+ * type + 注销 status 的 MAPPED 成员，与 delivery-port 快照基线同一映射规则，
+ * MF-2-1；回填时序背景见 index.ts collectResults 回填段）——本文件不持有
+ * 字段映射实现。
+ */
+
 /**
  * 写侧前置判断①：entries 中是否已存在该 id 的 register entry（无论注销与否）。
  * register listener 落盘前去重用（U6 重复注册忽略）；id 全局唯一（时间戳+随机）
@@ -128,7 +164,7 @@ function filterActiveRegisters(
 		if (opts?.types && !opts.types.includes(entry.type)) continue;
 		// 跨 session 残留跳过（基准 = opts.currentSessionId）。判据读原始 data.sessionId
 		// 而非归一化值：entry 缺 sessionId 的旧形态条目（归一化兜底为 ""）视为本
-		// session——不过滤，与 normalizeRegisterEntry 的容错语义对齐（守卫漏计的危害
+		// session——不过滤，与 normalizeRegisterEntry 的容错语义对齐（检查漏计的危害
 		// 方向是幻 defer，宁放行不误杀活跃计数）。
 		if (
 			opts?.currentSessionId !== undefined &&
@@ -146,13 +182,13 @@ function filterActiveRegisters(
  * type 归一化：subagent/bash/session 原样保留，其余（含缺失/未知值）归 workflow。
  * state.ts 与 index.ts 两处归一化共用本函数，防止「写入侧直通、读取侧归并」漂移。
  *
- * [偏好显式化] 缺失/未知 type 默认归 workflow = 宁挂账不失明：未知类型照常进差集
- * （守卫不因类型畸形失明），收口通道按类型分流——workflow / 畸形条目由 core 注册
- * 对账 sweep 收口（查 WorkflowRun store：终态 ∪ state 文件不存在 → 补注销）；bash 无
+ * [偏好显式化] 缺失/未知 type 默认归 workflow = 宁挂着不处理也不失明：未知类型照常进差集
+ * （检查不因类型畸形失明），收尾通道按类型分流——workflow / 畸形条目由 core 注册
+ * 对账 sweep 收尾（查 WorkflowRun store：终态 ∪ state 文件不存在 → 补注销）；bash 无
  * record/store 可查——注册随进程退出注销，进程死亡窗口的丢失无补发通道，属显式
  * 边界（每孤儿 bash 注册至多 1 条静态虚报，熔断限损）；session（notify-once D6
  * 词表真身在此——否则写侧归一成 workflow 展示错标）由 watch 应答 unregister 与
- * extension session_start 重启收口腿（D7③）收口，reconcile-sweep 对该 raw type
+ * extension session_start 重启收尾路径（D7③）收尾，reconcile-sweep 对该 raw type
  * 显式 skip（不入 workflow run-state 判据，防误销活跃 claim）。
  */
 export function normalizePendingType(raw: unknown): PendingType {
@@ -163,10 +199,13 @@ export function normalizePendingType(raw: unknown): PendingType {
 }
 
 /** 从 entry data 归一化为 PendingEntry（补默认值，容错缺失字段）。
- *  id 的 string 合法性已由差集层（applyPendingDiff）判定，此处直接窄化。 */
+ *  id 的 string 合法性已由差集层（applyPendingDiff）判定，此处直接窄化。
+ *  kind 白名单构造透传（result-collect 设计 §3.4：现状白名单只取 id/type/name/
+ *  registeredAt/sessionId，额外字段被丢弃——不改则工具侧拿不到 kind、lifetime
+ *  排除静默失效；仅认得 "lifetime" 一个值，未知值不透传）。 */
 function normalizeRegisterEntry(data: Record<string, unknown>, currentSessionId: string): PendingEntry {
 	const registeredAt = typeof data.registeredAt === "number" ? data.registeredAt : Date.now();
-	return {
+	const entry: PendingEntry = {
 		id: data.id as string,
 		type: normalizePendingType(data.type),
 		name: typeof data.name === "string" ? data.name : (data.id as string),
@@ -174,4 +213,6 @@ function normalizeRegisterEntry(data: Record<string, unknown>, currentSessionId:
 		registeredAt,
 		sessionId: typeof data.sessionId === "string" ? data.sessionId : currentSessionId,
 	};
+	if (data.kind === "lifetime") entry.kind = "lifetime";
+	return entry;
 }