@zhushanwen/pi-pending-notifications 0.2.0

package/index.ts

@@ -0,0 +1 @@
+export { default } from "./src/index.ts";

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@zhushanwen/pi-pending-notifications",
+  "version": "0.2.0",
+  "description": "Cross-extension async operation registration/query mechanism for Pi — prevents message injection during long-running operations.",
+  "type": "module",
+  "main": "src/index.ts",
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "keywords": [
+    "pi-package",
+    "extension",
+    "notifications",
+    "async",
+    "pending"
+  ],
+  "license": "MIT",
+  "files": [
+    "src/",
+    "index.ts"
+  ],
+  "devDependencies": {
+    "vitest": "^4.1.8"
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*",
+    "@sinclair/typebox": "*"
+  },
+  "scripts": {
+    "typecheck": "npx tsc --noEmit",
+    "test": "vitest run"
+  }
+}

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

@@ -0,0 +1,415 @@
+// 测试框架：vitest
+// 运行命令：npx vitest run src/__tests__/pending-notifications.test.ts
+//
+// W1 核心实现测试。覆盖 plan.md U1-U11。
+//
+// 测试策略：
+// - 用最小 mock 的 ExtensionAPI（mock events.on/emit、appendEntry、on、registerTool）
+// - 用最小 mock 的 ExtensionContext（mock sessionManager.getEntries/getSessionId）
+// - 调 pendingNotificationsExtension(pi) 触发工厂注册 handler
+// - 手动触发 session_start / events / tool / session_shutdown，断言 state + appendEntry
+
+/* eslint-disable taste/no-unsafe-cast */
+
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import pendingNotificationsExtension from "../index";
+import type { PendingEntry } from "../state";
+import { createRegistry, getActive, rebuildFromEntries, register, unregister } from "../state";
+
+// ── Mock 工具 ───────────────────────────────────────
+
+interface HandlerRegistry {
+	sessionStart: ((event: unknown, ctx: ExtensionContext) => void | Promise<void>) | undefined;
+	sessionShutdown: ((event: unknown, ctx: ExtensionContext) => void | Promise<void>) | undefined;
+	pendingRegister: ((data: unknown) => void) | undefined;
+	pendingUnregister: ((data: unknown) => void) | undefined;
+}
+
+interface MockSessionEntry {
+	customType: string;
+	data: Record<string, unknown>;
+}
+
+interface MockSetup {
+	pi: ExtensionAPI;
+	handlers: HandlerRegistry;
+	appendEntryMock: ReturnType<typeof vi.fn>;
+	registerToolMock: ReturnType<typeof vi.fn>;
+}
+
+function createMockPi(): MockSetup {
+	const handlers: HandlerRegistry = {
+		sessionStart: undefined,
+		sessionShutdown: undefined,
+		pendingRegister: undefined,
+		pendingUnregister: undefined,
+	};
+	const appendEntryMock = vi.fn();
+	const registerToolMock = vi.fn();
+	const sendMessageMock = vi.fn();
+
+	const pi = {
+		appendEntry: appendEntryMock,
+		registerTool: registerToolMock,
+		sendMessage: sendMessageMock,
+		on: vi.fn((event: string, handler: (event: unknown, ctx: ExtensionContext) => void | Promise<void>) => {
+			if (event === "session_start") handlers.sessionStart = handler;
+			if (event === "session_shutdown") handlers.sessionShutdown = 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, appendEntryMock, registerToolMock };
+}
+
+function createMockCtx(entries: MockSessionEntry[], sessionId = "sess-current"): ExtensionContext {
+	return {
+		sessionManager: {
+			getEntries: () => entries as unknown[],
+			getSessionId: () => sessionId,
+		},
+	} as unknown as ExtensionContext;
+}
+
+function fireSessionStart(setup: MockSetup, ctx: ExtensionContext): void {
+	if (!setup.handlers.sessionStart) throw new Error("session_start handler not registered");
+	void setup.handlers.sessionStart({ type: "session_start", reason: "resume" }, ctx);
+}
+
+async function runTool(
+	setup: MockSetup,
+	params: Record<string, unknown>,
+): Promise<{ content: Array<{ type: string; text: string }>; details: unknown }> {
+	const tool = setup.registerToolMock.mock.calls[0][0] as {
+		execute: (p: unknown) => Promise<{ content: Array<{ type: string; text: string }>; details: unknown }>;
+	};
+	return tool.execute(params);
+}
+
+async function getCount(setup: MockSetup): Promise<number> {
+	const res = await runTool(setup, { action: "count" });
+	return Number(res.content[0].text.replace(/[^0-9]/g, ""));
+}
+
+// ── 共享 fixtures ───────────────────────────────────
+
+const NOW = 1_700_000_000_000;
+
+function makeRegisterEntry(id: string, extra: Partial<PendingEntry> = {}): MockSessionEntry {
+	return {
+		customType: "pending:register",
+		data: {
+			id,
+			type: "workflow",
+			name: `op-${id}`,
+			registeredAt: NOW,
+			expiresAt: NOW + 3_600_000,
+			sessionId: "sess-current",
+			...extra,
+		},
+	};
+}
+
+function makeUnregisterEntry(id: string): MockSessionEntry {
+	return { customType: "pending:unregister", data: { id } };
+}
+
+function rebuild(
+	entries: MockSessionEntry[],
+	currentSessionId: string,
+	now: number,
+): { activeIds: string[]; expiredToFlush: Array<{ id: string; status: string }> } {
+	return rebuildFromEntries(createRegistry(), entries as unknown[], currentSessionId, now);
+}
+
+// ────────────────────────────────────────────────────
+// state.ts 纯函数测试
+// ────────────────────────────────────────────────────
+
+describe("state pure functions", () => {
+	describe("register", () => {
+		it("registers a new active operation", () => {
+			const r = createRegistry();
+			const op: PendingEntry = {
+				id: "w-1", type: "workflow", name: "test", status: "active",
+				registeredAt: NOW, expiresAt: NOW + 3_600_000, sessionId: "s",
+			};
+			register(r, op);
+			expect(getActive(r).map((o) => o.id)).toEqual(["w-1"]);
+		});
+
+		it("ignores duplicate active id (U6)", () => {
+			const r = createRegistry();
+			const op: PendingEntry = {
+				id: "w-1", type: "workflow", name: "test", status: "active",
+				registeredAt: NOW, expiresAt: NOW + 3_600_000, sessionId: "s",
+			};
+			register(r, op);
+			register(r, { ...op, name: "dup" });
+			expect(getActive(r)).toHaveLength(1);
+			expect(getActive(r)[0].name).toBe("test");
+		});
+	});
+
+	describe("unregister", () => {
+		it("marks existing op non-active (U7)", () => {
+			const r = createRegistry();
+			register(r, {
+				id: "w-1", type: "workflow", name: "test", status: "active",
+				registeredAt: NOW, expiresAt: NOW + 3_600_000, sessionId: "s",
+			});
+			unregister(r, "w-1", "completed");
+			expect(getActive(r)).toHaveLength(0);
+		});
+
+		it("ignores unknown id without error (U8)", () => {
+			const r = createRegistry();
+			expect(() => unregister(r, "nope", "completed")).not.toThrow();
+		});
+	});
+
+	describe("rebuildFromEntries", () => {
+		it("U1: register without unregister → 1 active", () => {
+			const comp = rebuild([makeRegisterEntry("w-1")], "sess-current", NOW);
+			expect(comp.activeIds).toEqual(["w-1"]);
+			expect(comp.expiredToFlush).toEqual([]);
+		});
+
+		it("U2: register + matching unregister → 0 active", () => {
+			const comp = rebuild([makeRegisterEntry("w-1"), makeUnregisterEntry("w-1")], "sess-current", NOW);
+			expect(comp.activeIds).toEqual([]);
+			expect(comp.expiredToFlush).toEqual([]);
+		});
+
+		it("U3: register expired → flush unregister with status=expired", () => {
+			const comp = rebuild(
+				[makeRegisterEntry("w-1", { expiresAt: NOW - 1 })],
+				"sess-current",
+				NOW,
+			);
+			expect(comp.activeIds).toEqual([]);
+			expect(comp.expiredToFlush).toEqual([{ id: "w-1", status: "expired" }]);
+		});
+
+		it("U4: register with different sessionId → flush unregister with status=expired", () => {
+			const comp = rebuild(
+				[makeRegisterEntry("w-1", { sessionId: "sess-other" })],
+				"sess-current",
+				NOW,
+			);
+			expect(comp.activeIds).toEqual([]);
+			expect(comp.expiredToFlush).toEqual([{ id: "w-1", status: "expired" }]);
+		});
+	});
+
+	describe("normalizeRegisterEntry defaults (via rebuild)", () => {
+		it("entry with only {id} → type=workflow, name=id, sessionId=current, expiresAt=registeredAt+TTL", () => {
+			const r = createRegistry();
+			const result = rebuildFromEntries(
+				r,
+				[{ customType: "pending:register", data: { id: "w-min" } }],
+				"sess-current",
+				Date.now(),
+			);
+			expect(result.activeIds).toEqual(["w-min"]);
+			const entry = r.operations.get("w-min")!;
+			expect(entry.type).toBe("workflow");
+			expect(entry.name).toBe("w-min");
+			expect(entry.sessionId).toBe("sess-current");
+			expect(entry.status).toBe("active");
+			expect(entry.expiresAt).toBe(entry.registeredAt + 3_600_000);
+		});
+	});
+});
+
+// ────────────────────────────────────────────────────
+// index.ts 工厂集成测试（U1-U11）
+// ────────────────────────────────────────────────────
+
+describe("pendingNotificationsExtension factory", () => {
+	let setup: MockSetup;
+
+	beforeEach(() => {
+		vi.useFakeTimers();
+		vi.setSystemTime(NOW);
+		setup = createMockPi();
+		pendingNotificationsExtension(setup.pi);
+	});
+
+	afterEach(() => {
+		vi.useRealTimers();
+	});
+
+	describe("session_start rebuild (U1-U4)", () => {
+		it("U1: 1 register no unregister → 1 active, no flush", async () => {
+			fireSessionStart(setup, createMockCtx([makeRegisterEntry("w-1")]));
+			expect(await getCount(setup)).toBe(1);
+			const stateChangeCalls = setup.appendEntryMock.mock.calls.filter(
+				(c) => c[0] === "pending:register" || c[0] === "pending:unregister",
+			);
+			expect(stateChangeCalls).toHaveLength(0);
+		});
+
+		it("U2: register + unregister → 0 active", async () => {
+			fireSessionStart(setup, createMockCtx([makeRegisterEntry("w-1"), makeUnregisterEntry("w-1")]));
+			expect(await getCount(setup)).toBe(0);
+		});
+
+		it("U3: expired register → flush pending:unregister entry", async () => {
+			vi.setSystemTime(NOW + 3_700_000);
+			fireSessionStart(setup, createMockCtx([makeRegisterEntry("w-1", { expiresAt: NOW })]));
+			expect(await getCount(setup)).toBe(0);
+			expect(setup.appendEntryMock).toHaveBeenCalledWith(
+				"pending:unregister",
+				expect.objectContaining({ id: "w-1", status: "expired" }),
+			);
+		});
+
+		it("U4: different sessionId → flush pending:unregister entry", async () => {
+			fireSessionStart(setup, createMockCtx([makeRegisterEntry("w-1", { sessionId: "sess-old" })], "sess-current"));
+			expect(await getCount(setup)).toBe(0);
+			expect(setup.appendEntryMock).toHaveBeenCalledWith(
+				"pending:unregister",
+				expect.objectContaining({ id: "w-1", status: "expired" }),
+			);
+		});
+	});
+
+	describe("events.on pending:register (U5-U6)", () => {
+		it("U5: register event → active + appendEntry", async () => {
+			fireSessionStart(setup, createMockCtx([]));
+
+			setup.handlers.pendingRegister!({ id: "w-1", type: "workflow", name: "test" });
+
+			expect(await getCount(setup)).toBe(1);
+			expect(setup.appendEntryMock).toHaveBeenCalledWith(
+				"pending:register",
+				expect.objectContaining({ id: "w-1", type: "workflow", name: "test" }),
+			);
+		});
+
+		it("U6: duplicate register event → ignored", async () => {
+			fireSessionStart(setup, createMockCtx([]));
+
+			setup.handlers.pendingRegister!({ id: "w-1", type: "workflow", name: "first" });
+			setup.handlers.pendingRegister!({ id: "w-1", type: "workflow", name: "second" });
+
+			expect(await getCount(setup)).toBe(1);
+			const registerCalls = setup.appendEntryMock.mock.calls.filter((c) => c[0] === "pending:register");
+			expect(registerCalls).toHaveLength(1);
+		});
+	});
+
+	describe("events.on pending:unregister (U7-U8)", () => {
+		it("U7: unregister event → non-active + appendEntry", async () => {
+			fireSessionStart(setup, createMockCtx([]));
+
+			setup.handlers.pendingRegister!({ id: "w-1", type: "workflow", name: "test" });
+			setup.appendEntryMock.mockClear();
+			setup.handlers.pendingUnregister!({ id: "w-1", reason: "completed" });
+
+			expect(await getCount(setup)).toBe(0);
+			expect(setup.appendEntryMock).toHaveBeenCalledWith(
+				"pending:unregister",
+				expect.objectContaining({ id: "w-1", reason: "completed" }),
+			);
+		});
+
+		it("U8: unregister unknown id → ignored, no appendEntry, no throw", () => {
+			fireSessionStart(setup, createMockCtx([]));
+			setup.appendEntryMock.mockClear();
+
+			expect(() => setup.handlers.pendingUnregister!({ id: "nope", reason: "completed" })).not.toThrow();
+			const stateChangeCalls = setup.appendEntryMock.mock.calls.filter(
+				(c) => c[0] === "pending:register" || c[0] === "pending:unregister",
+			);
+			expect(stateChangeCalls).toHaveLength(0);
+		});
+	});
+
+	describe("tool count/list (U9-U10)", () => {
+		it("U9: count returns active count", async () => {
+			fireSessionStart(setup, createMockCtx([]));
+			setup.handlers.pendingRegister!({ id: "w-1", type: "workflow", name: "a" });
+
+			const res = await runTool(setup, { action: "count" });
+			expect(res.content[0].text).toContain("1");
+		});
+
+		it("U10: list returns active list", async () => {
+			fireSessionStart(setup, createMockCtx([]));
+			setup.handlers.pendingRegister!({ id: "w-1", type: "workflow", name: "a" });
+			setup.handlers.pendingRegister!({ id: "s-1", type: "subagent", name: "b" });
+
+			const res = await runTool(setup, { action: "list" });
+			const ids = (res.details as { items: PendingEntry[] }).items.map((i) => i.id);
+			expect(ids.sort()).toEqual(["s-1", "w-1"]);
+		});
+	});
+
+	describe("session_shutdown (U11)", () => {
+		it("U11: marks all active as cancelled + flushes unregister entries", () => {
+			fireSessionStart(setup, createMockCtx([]));
+			setup.handlers.pendingRegister!({ id: "w-1", type: "workflow", name: "a" });
+			setup.handlers.pendingRegister!({ id: "s-1", type: "subagent", name: "b" });
+			setup.appendEntryMock.mockClear();
+
+			if (!setup.handlers.sessionShutdown) throw new Error("session_shutdown not registered");
+			void setup.handlers.sessionShutdown({ type: "session_shutdown" }, createMockCtx([]));
+
+			const unregisterCalls = setup.appendEntryMock.mock.calls.filter((c) => c[0] === "pending:unregister");
+			expect(unregisterCalls).toHaveLength(2);
+			const flushedIds = unregisterCalls.map((c) => (c[1] as { id: string }).id).sort();
+			expect(flushedIds).toEqual(["s-1", "w-1"]);
+			for (const c of unregisterCalls) {
+				expect((c[1] as { status: string }).status).toBe("cancelled");
+			}
+		});
+	});
+
+	describe("safeAppendEntry error handling", () => {
+		it("appendEntry throwing (stale context) does not break register listener, registry still updated", async () => {
+			// listener 先 register(registry) 更新内存，再 safeAppendEntry；appendEntry 抛错被 catch，registry 仍已更新
+			fireSessionStart(setup, createMockCtx([]));
+			setup.appendEntryMock.mockImplementationOnce(() => {
+				throw new Error("stale context");
+			});
+
+			expect(() => setup.handlers.pendingRegister!({ id: "w-1", type: "workflow", name: "test" })).not.toThrow();
+
+			expect(await getCount(setup)).toBe(1);
+		});
+	});
+
+	describe("parse null/malformed events", () => {
+		it("parseRegisterEvent: null and missing-id data → no throw, no register entry", () => {
+			fireSessionStart(setup, createMockCtx([]));
+			setup.appendEntryMock.mockClear();
+
+			expect(() => setup.handlers.pendingRegister!(null)).not.toThrow();
+			expect(() => setup.handlers.pendingRegister!({ type: "workflow" })).not.toThrow();
+
+			const registerCalls = setup.appendEntryMock.mock.calls.filter((c) => c[0] === "pending:register");
+			expect(registerCalls).toHaveLength(0);
+		});
+
+		it("parseUnregisterEvent: null and missing-id data → no throw, no unregister entry", () => {
+			fireSessionStart(setup, createMockCtx([]));
+			setup.appendEntryMock.mockClear();
+
+			expect(() => setup.handlers.pendingUnregister!(null)).not.toThrow();
+			expect(() => setup.handlers.pendingUnregister!({ reason: "completed" })).not.toThrow();
+
+			const unregisterCalls = setup.appendEntryMock.mock.calls.filter((c) => c[0] === "pending:unregister");
+			expect(unregisterCalls).toHaveLength(0);
+		});
+	});
+});

package/src/index.ts

@@ -0,0 +1,298 @@
+/**
+ * Pending Notifications Extension — 跨 extension 的异步操作注册/查询机制。
+ *
+ * 设计定位：解决 workflow/subagent 运行时 goal 持续注入消息的悖论。
+ * workflow/subagent 运行时通过 EventBus（pi.events.emit）广播 register/unregister，
+ * 本扩展监听这些事件、将状态写入 session entries（pi.appendEntry），
+ * 让 goal 的 before_agent_start 从 entries 读取活跃异步操作并注入等待消息。
+ *
+ * 文件职责：
+ * - state.ts:    PendingEntry / PendingRegistry + 纯函数（register/unregister/rebuild）
+ * - index.ts（本文件）: 工厂入口（注册 events.on 监听 + session 生命周期 + 查询 tool）
+ *
+ * 事件契约（与 workflow launcher.ts / subagent-service.ts 对齐）：
+ * - emit("pending:register", { id, type, name })
+ * - emit("pending:unregister", { id, reason })
+ *
+ * entry 契约（与 goal before-agent-start.ts 对齐，读取端按 e.data.id 算差集）：
+ * - pending:register → { id, type, name, registeredAt, expiresAt, sessionId }
+ * - pending:unregister → { id, reason, status }
+ *
+ * 监听方式：pi.events.on（Pi 的 EventBus，真实 SDK 为 EventBus.on，非 optional）。
+ * workflow 侧通过 deps.eventBus 注入 pi.events（同一总线）。
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+
+import {
+	createRegistry,
+	getActive,
+	PENDING_TTL_MS,
+	type PendingEntry,
+	type PendingRegistry,
+	type PendingStatus,
+	type PendingType,
+	rebuildFromEntries,
+	register,
+	unregister,
+} from "./state.ts";
+
+/** 工具参数 schema */
+const PendingNotificationsParams = Type.Object({
+	action: Type.Union([
+		Type.Literal("count"),
+		Type.Literal("list"),
+	]),
+});
+
+/** tool 入参形状 */
+interface ToolParams {
+	action: "count" | "list";
+}
+
+/**
+ * 模块级 EventBus 监听器 unsubscribe 函数列表。
+ *
+ * EventBus 是进程级单例（真实 SDK resource-loader 构造一次，跨 /reload、会话切换复用）。
+ * 工厂函数 pendingNotificationsExtension 每次 reload 都重新执行，若不先移除旧监听器，
+ * N 次 reload 后 EventBus 上会累积 N 组监听器（>11 后抛 Possible EventEmitter memory leak）。
+ *
+ * 用模块级变量跨 reload 持久：工厂入口先调用上一轮的 unsubscribe 清理旧监听器，
+ * 再注册新的。这同时修复了多 session 串数据问题——reload 后只有当前闭包的监听器存活，
+ * currentSessionId 始终是最新 session（旧闭包的过期 currentSessionId 不会再给事件打戳）。
+ */
+let unsubscribers: Array<() => void> = [];
+
+/** 扩展入口 */
+export default function pendingNotificationsExtension(pi: ExtensionAPI): void {
+	// ── 清理上一轮 reload 的 EventBus 监听器（H2 防泄漏） ─────
+	for (const unsub of unsubscribers) {
+		try {
+			unsub();
+		} catch (err) {
+			// unsubscribe 失败不阻断初始化（监听器可能已被 EventBus 内部清理）
+			console.debug("[pending-notifications] unsubscribe failed during cleanup", err);
+		}
+	}
+	unsubscribers = [];
+
+	// ── 闭包内状态（session 隔离，每个 session_start 重建） ─────
+	let registry: PendingRegistry = createRegistry();
+	let currentSessionId: string = "";
+
+	// 安全写入 session entry：忽略 stale context 等不可恢复错误（如 subagent 子进程
+	// session replacement 后 listener 仍触发）。返回是否成功。
+	function safeAppendEntry(customType: string, data: unknown): boolean {
+		try {
+			pi.appendEntry(customType, data);
+			return true;
+		} catch {
+			// stale context 或 session 已关闭时，静默丢弃。entry 不是关键业务数据，
+			// 丢失不会破坏主流程。
+			return false;
+		}
+	}
+
+	// debug 日志：环境变量 PENDING_DEBUG=1 时输出到 console.debug。
+	// 不再写入 session entry（pending:log）——session entries 是 append-only 无法 GC，
+	// 12 处 debug 日志会让长 session 的 entries 线性膨胀，而 goal before-agent-start
+	// 每 turn 全量扫描 getEntries()。状态数据（pending:register/unregister）仍写 entry。
+	const debugEnabled = process.env.PENDING_DEBUG === "1";
+	function debugLog(level: string, message: string, data?: unknown): void {
+		if (!debugEnabled) return;
+		console.debug(`[pending-notifications:${level}] ${message}`, data ?? "");
+	}
+
+	// ── EventBus 监听：pending:register ─────────────────────
+	unsubscribers.push(pi.events.on("pending:register", (data: unknown) => {
+		debugLog("debug", "listener: pending:register received", data);
+		const parsed = parseRegisterEvent(data);
+		if (!parsed) {
+			debugLog("warn", "listener: pending:register parse failed", data);
+			return;
+		}
+
+		debugLog("debug", "listener: pending:register parsed", parsed);
+
+		const now = Date.now();
+		const entry: PendingEntry = {
+			id: parsed.id,
+			type: parsed.type,
+			name: parsed.name,
+			status: "active",
+			registeredAt: now,
+			expiresAt: now + PENDING_TTL_MS,
+			sessionId: currentSessionId,
+		};
+
+		// 重复注册忽略（U6）
+		const added = register(registry, entry);
+		if (!added) {
+			debugLog("debug", "listener: pending:register ignored (duplicate)", { id: parsed.id });
+			return;
+		}
+
+		safeAppendEntry("pending:register", {
+			id: entry.id,
+			type: entry.type,
+			name: entry.name,
+			registeredAt: entry.registeredAt,
+			expiresAt: entry.expiresAt,
+			sessionId: entry.sessionId,
+		});
+
+		debugLog("debug", "listener: pending:register appended", { id: parsed.id });
+	}));
+
+	// ── EventBus 监听：pending:unregister ───────────────────
+	unsubscribers.push(pi.events.on("pending:unregister", (data: unknown) => {
+		debugLog("debug", "listener: pending:unregister received", data);
+		const parsed = parseUnregisterEvent(data);
+		if (!parsed) {
+			debugLog("warn", "listener: pending:unregister parse failed", data);
+			return;
+		}
+
+		debugLog("debug", "listener: pending:unregister parsed", parsed);
+
+		const status = mapReasonToStatus(parsed.reason);
+		const changed = unregister(registry, parsed.id, status);
+		if (!changed) {
+			debugLog("debug", "listener: pending:unregister ignored (unknown id)", { id: parsed.id });
+			return;
+		}
+
+		safeAppendEntry("pending:unregister", {
+			id: parsed.id,
+			reason: parsed.reason,
+			status,
+		});
+
+		debugLog("debug", "listener: pending:unregister appended", { id: parsed.id });
+	}));
+
+	// ── session_start：从持久化 entries 重建 registry ────────
+	pi.on("session_start", (_event, ctx: ExtensionContext) => {
+		registry = createRegistry();
+		currentSessionId = ctx.sessionManager.getSessionId();
+
+		const entries = ctx.sessionManager.getEntries();
+		const now = Date.now();
+		const { expiredToFlush } = rebuildFromEntries(registry, entries, currentSessionId, now);
+
+		debugLog("debug", "session_start: registry rebuilt", {
+			sessionId: currentSessionId,
+			totalEntries: entries.length,
+			activeAfterRebuild: getActive(registry).length,
+			expiredToFlush: expiredToFlush.length,
+		});
+
+		// 补 expired/跨 session 残留的 unregister entry（U3/U4）
+		for (const item of expiredToFlush) {
+			safeAppendEntry("pending:unregister", {
+				id: item.id,
+				status: item.status,
+			});
+		}
+	});
+
+	// ── session_shutdown：所有 active → cancelled + 补 entry（U11） ──
+	pi.on("session_shutdown", (_event, _ctx: ExtensionContext) => {
+		const active = getActive(registry);
+		for (const op of active) {
+			const changed = unregister(registry, op.id, "cancelled");
+			if (changed) {
+				safeAppendEntry("pending:unregister", {
+					id: op.id,
+					status: "cancelled",
+				});
+			}
+		}
+	});
+
+	// ── 查询 tool ─────────────────────────────────────────
+	pi.registerTool({
+		name: "pending_notifications",
+		label: "Pending Notifications",
+		description:
+			"查询当前活跃的异步操作（workflow/subagent）。action=count 返回数量；action=list 返回列表。状态由 EventBus + session entries 维护，无需手动注册。",
+		parameters: PendingNotificationsParams,
+		execute: async (params: unknown) => {
+			const p = params as ToolParams;
+			const active = getActive(registry);
+
+			debugLog("debug", `tool ${p.action} requested`, { action: p.action, activeCount: active.length });
+
+			if (p.action === "count") {
+				return {
+					content: [{ type: "text" as const, text: `${active.length} pending operation(s)` }],
+					details: { action: "count", count: active.length },
+				};
+			}
+
+			// action === "list"
+			return {
+				content: [{ type: "text" as const, text: formatList(active) }],
+				details: { action: "list", count: active.length, items: active },
+			};
+		},
+	});
+}
+
+// ── 事件解析 helper ─────────────────────────────────
+
+interface ParsedRegister {
+	id: string;
+	type: PendingType;
+	name: string;
+}
+
+/** 解析 pending:register 事件 data（容错缺失/类型错误字段） */
+function parseRegisterEvent(data: unknown): ParsedRegister | null {
+	if (typeof data !== "object" || data === null) return null;
+	const d = data as Record<string, unknown>;
+	if (typeof d.id !== "string") return null;
+	return {
+		id: d.id,
+		type: d.type === "subagent" ? "subagent" : "workflow",
+		name: typeof d.name === "string" ? d.name : d.id,
+	};
+}
+
+interface ParsedUnregister {
+	id: string;
+	reason: string;
+}
+
+/** 解析 pending:unregister 事件 data（容错缺失/类型错误字段） */
+function parseUnregisterEvent(data: unknown): ParsedUnregister | null {
+	if (typeof data !== "object" || data === null) return null;
+	const d = data as Record<string, unknown>;
+	if (typeof d.id !== "string") return null;
+	return {
+		id: d.id,
+		reason: typeof d.reason === "string" ? d.reason : "completed",
+	};
+}
+
+/** 将事件 reason 映射为内部 PendingStatus */
+function mapReasonToStatus(reason: string): PendingStatus {
+	switch (reason) {
+		case "completed": return "completed";
+		case "failed": return "failed";
+		case "cancelled": return "cancelled";
+		case "expired": return "expired";
+		case "time_limited": return "time_limited";
+		case "budget_limited": return "failed";
+		case "aborted": return "aborted";
+		default: return "completed";
+	}
+}
+
+/** 格式化 active 列表为可读文本 */
+function formatList(active: PendingEntry[]): string {
+	if (active.length === 0) return "No pending operations";
+	const lines = active.map((op) => `- [${op.type}] ${op.name} (id=${op.id})`);
+	return `${active.length} pending operation(s):\n${lines.join("\n")}`;
+}

package/src/state.ts

@@ -0,0 +1,186 @@
+/**
+ * Pending Notifications State — 数据模型和纯函数。
+ *
+ * 职责：
+ * - PendingEntry: 一个异步操作的完整描述（与 pending:register entry data 对齐）
+ * - PendingRegistry: 内存中的活跃操作注册表（Map<id, PendingEntry>）
+ * - register/unregister: 运行时事件驱动的状态变更
+ * - rebuildFromEntries: session_start 从持久化 entries 重建 registry + 识别需要补注销的 expired/跨 session 残留
+ *
+ * 设计要点：
+ * - 纯函数，不依赖 Pi 运行时（ExtensionAPI/appendEntry），可独立单元测试
+ * - 所有时间戳由调用方传入（now），便于测试
+ * - rebuildFromEntries 返回 activeIds + expiredToFlush（需要 index.ts 补 appendEntry 的列表），
+ *   不直接写 entry —— 写 entry 是副作用，由 index.ts 负责
+ */
+
+/** 异步操作类型（来源：workflow / subagent） */
+export type PendingType = "workflow" | "subagent";
+
+/** 异步操作终态/过渡状态。active = 仍在运行；其他都视为已结束 */
+export type PendingStatus = "active" | "completed" | "failed" | "cancelled" | "expired" | "time_limited" | "aborted";
+
+/** 一个异步操作的完整描述（= pending:register entry 的 data 字段） */
+export interface PendingEntry {
+	/** 操作唯一标识（workflow runId / subagent id） */
+	id: string;
+	/** 操作来源类型 */
+	type: PendingType;
+	/** 可读名称（workflow name / subagent name） */
+	name: string;
+	/** 注册时状态（恒为 active，由 register 设置） */
+	status: PendingStatus;
+	/** 注册时间戳 ms */
+	registeredAt: number;
+	/** 过期时间戳 ms（registeredAt + TTL） */
+	expiresAt: number;
+	/** 注册时的 sessionId（用于跨 session 残留检测） */
+	sessionId: string;
+}
+
+/** pending:register entry 在 entries 里的最小可识别形状 */
+interface RegisterEntryData {
+	id: unknown;
+	type: unknown;
+	name: unknown;
+	registeredAt: unknown;
+	expiresAt: unknown;
+	sessionId: unknown;
+}
+
+/** pending:unregister entry 在 entries 里的最小可识别形状 */
+interface UnregisterEntryData {
+	id: unknown;
+}
+
+/** SessionEntry 的最小可识别形状（duck-typed，避免依赖 SDK 具体类型） */
+interface EntryLike {
+	customType?: string;
+	data?: unknown;
+}
+
+/** pending:register entry 的 TTL（1 小时） */
+export const PENDING_TTL_MS = 3_600_000;
+
+/** 注册表：内存中的活跃操作（session 隔离，由 index.ts 在闭包内持有） */
+export interface PendingRegistry {
+	/** 所有已注册操作（含已注销的，便于去重判断） */
+	operations: Map<string, PendingEntry>;
+}
+
+/** 创建空注册表 */
+export function createRegistry(): PendingRegistry {
+	return { operations: new Map() };
+}
+
+/**
+ * 注册操作。已存在（任何 status）的同 id 操作被忽略（U6 重复注册）。
+ * 返回是否实际新增（true = 新注册，false = 被忽略）。
+ */
+export function register(registry: PendingRegistry, entry: PendingEntry): boolean {
+	if (registry.operations.has(entry.id)) {
+		return false;
+	}
+	registry.operations.set(entry.id, entry);
+	return true;
+}
+
+/**
+ * 注销操作。不存在则忽略不报错（U8）。
+ * 返回是否实际变更（true = 注销了 active 操作，false = 不存在或已注销）。
+ */
+export function unregister(registry: PendingRegistry, id: string, status: PendingStatus): boolean {
+	const op = registry.operations.get(id);
+	if (!op || op.status !== "active") {
+		return false;
+	}
+	op.status = status;
+	return true;
+}
+
+/** 返回当前所有 active 操作（按注册顺序） */
+export function getActive(registry: PendingRegistry): PendingEntry[] {
+	return Array.from(registry.operations.values()).filter((op) => op.status === "active");
+}
+
+/** rebuildFromEntries 的结果：重建后的活跃列表 + 需要补注销的 entry */
+export interface RebuildResult {
+	/** 重建后识别为 active 的 id 列表（已写入 registry） */
+	activeIds: string[];
+	/** 需要补 pending:unregister entry 的操作（expired/跨 session 残留） */
+	expiredToFlush: Array<{ id: string; status: PendingStatus }>;
+}
+
+/**
+ * 从持久化 entries 重建 registry（session_start 时调用）。
+ *
+ * 算法（对齐 goal before-agent-start.ts 的读取契约）：
+ * 1. 收集所有 pending:register entry，按 id 算差集（减去 pending:unregister 的 id）
+ *    前提：id 全局唯一（workflow runId=`wf-<ts>-<rand>`、subagent id=`bg-/run-<tag>-<seq>-<ts>`）。
+ *    若未来 id 复用（register→unregister→register 同 id），全局 Set 差集会误跳第二次 register。
+ * 2. 对每个活跃的 register entry 检查：
+ *    - sessionId 不符当前 session → expired（U4 跨 session 残留）
+ *    - expiresAt <= now → expired（U3 过期）
+ * 3. 仍活跃的写入 registry，expired 的进入 expiredToFlush（由 index.ts 补 appendEntry）
+ *
+ * 注意：本函数只重建 registry + 计算需补的 entry，不写 entry（副作用归 index.ts）。
+ */
+export function rebuildFromEntries(
+	registry: PendingRegistry,
+	entries: unknown[],
+	currentSessionId: string,
+	now: number,
+): RebuildResult {
+	const registerEntries: Array<{ data: RegisterEntryData }> = [];
+	const unregisteredIds = new Set<string>();
+
+	for (const raw of entries as EntryLike[]) {
+		if (raw.customType === "pending:register") {
+			registerEntries.push({ data: (raw.data ?? {}) as RegisterEntryData });
+		} else if (raw.customType === "pending:unregister") {
+			const data = (raw.data ?? {}) as UnregisterEntryData;
+			if (typeof data.id === "string") {
+				unregisteredIds.add(data.id);
+			}
+		}
+	}
+
+	const activeIds: string[] = [];
+	const expiredToFlush: Array<{ id: string; status: PendingStatus }> = [];
+
+	for (const { data } of registerEntries) {
+		if (typeof data.id !== "string") continue;
+		if (unregisteredIds.has(data.id)) continue;
+
+		const entry = normalizeRegisterEntry(data, currentSessionId);
+		// 跨 session 残留（U4）
+		if (entry.sessionId !== currentSessionId) {
+			expiredToFlush.push({ id: entry.id, status: "expired" });
+			continue;
+		}
+		// 过期（U3）
+		if (entry.expiresAt <= now) {
+			expiredToFlush.push({ id: entry.id, status: "expired" });
+			continue;
+		}
+		// 仍活跃
+		registry.operations.set(entry.id, entry);
+		activeIds.push(entry.id);
+	}
+
+	return { activeIds, expiredToFlush };
+}
+
+/** 从 entry data 归一化为 PendingEntry（补默认值，容错缺失字段） */
+function normalizeRegisterEntry(data: RegisterEntryData, currentSessionId: string): PendingEntry {
+	const registeredAt = typeof data.registeredAt === "number" ? data.registeredAt : Date.now();
+	return {
+		id: data.id as string,
+		type: (data.type === "subagent" ? "subagent" : "workflow") as PendingType,
+		name: typeof data.name === "string" ? data.name : (data.id as string),
+		status: "active",
+		registeredAt,
+		expiresAt: typeof data.expiresAt === "number" ? data.expiresAt : registeredAt + PENDING_TTL_MS,
+		sessionId: typeof data.sessionId === "string" ? data.sessionId : currentSessionId,
+	};
+}