@zhushanwen/pi-base-tool-enhance 0.2.0

package/src/__tests__/tool-error-audit.test.ts

@@ -0,0 +1,92 @@
+// src/__tests__/tool-error-audit.test.ts
+// 审计 hook 等价迁移守卫：customType 与 entry 形态必须与 unified-hooks
+// tool-error-handler 逐字段一致（D11 落点，M1 验收点）。
+import { describe, expect, it, vi } from "vitest";
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { setupToolErrorAudit } from "../tool-error-audit.ts";
+
+interface MockPi {
+	on: ReturnType<typeof vi.fn>;
+	appendEntry: ReturnType<typeof vi.fn>;
+}
+
+function createMockPi(): MockPi {
+	return {
+		on: vi.fn(),
+		appendEntry: vi.fn(),
+	};
+}
+
+function getRegisteredHandler(pi: MockPi): (event: unknown) => Promise<void> {
+	const call = pi.on.mock.calls.find((c: unknown[]) => c[0] === "tool_execution_end");
+	expect(call).toBeDefined();
+	return call![1] as (event: unknown) => Promise<void>;
+}
+
+describe("setupToolErrorAudit", () => {
+	it("registers a handler on the tool_execution_end event (pi has no tool_error event)", () => {
+		const pi = createMockPi();
+		setupToolErrorAudit(pi as unknown as ExtensionAPI);
+		expect(pi.on).toHaveBeenCalledWith("tool_execution_end", expect.any(Function));
+		expect(pi.on).toHaveBeenCalledTimes(1);
+	});
+
+	it("appends audit entry with the unified-hooks customType and exact field shape on isError:true", async () => {
+		const pi = createMockPi();
+		setupToolErrorAudit(pi as unknown as ExtensionAPI);
+		const handler = getRegisteredHandler(pi);
+		const before = Date.now();
+
+		await handler({
+			isError: true,
+			toolName: "bash",
+			toolCallId: "call-42",
+			result: { content: [{ type: "text", text: "timeout:30" }] },
+		});
+
+		expect(pi.appendEntry).toHaveBeenCalledTimes(1);
+		const [customType, entry] = pi.appendEntry.mock.calls[0] as [string, Record<string, unknown>];
+		expect(customType).toBe("unified-hooks:tool-error");
+		// 逐字段一致：timestamp（毫秒区间内）/ toolName / toolCallId / errorText 从 result.content 提取
+		expect(typeof entry.timestamp).toBe("number");
+		expect(entry.timestamp).toBeGreaterThanOrEqual(before);
+		expect(entry.timestamp).toBeLessThanOrEqual(Date.now());
+		expect(entry.toolName).toBe("bash");
+		expect(entry.toolCallId).toBe("call-42");
+		expect(entry.errorText).toBe("timeout:30");
+	});
+
+	it("falls back to null errorText when result carries no extractable text", async () => {
+		const pi = createMockPi();
+		setupToolErrorAudit(pi as unknown as ExtensionAPI);
+		const handler = getRegisteredHandler(pi);
+
+		await handler({ isError: true, toolName: "read", toolCallId: "call-1" });
+
+		const [, entry] = pi.appendEntry.mock.calls[0] as [string, Record<string, unknown>];
+		expect(entry.errorText).toBeNull();
+	});
+
+	it("falls back to result.error string when content array is absent", async () => {
+		const pi = createMockPi();
+		setupToolErrorAudit(pi as unknown as ExtensionAPI);
+		const handler = getRegisteredHandler(pi);
+
+		await handler({ isError: true, toolName: "edit", toolCallId: "call-2", result: { error: "bad edit" } });
+
+		const [, entry] = pi.appendEntry.mock.calls[0] as [string, Record<string, unknown>];
+		expect(entry.errorText).toBe("bad edit");
+	});
+
+	it("does not appendEntry when isError is false", async () => {
+		const pi = createMockPi();
+		setupToolErrorAudit(pi as unknown as ExtensionAPI);
+		const handler = getRegisteredHandler(pi);
+
+		await handler({ isError: false, toolName: "bash", toolCallId: "call-3", result: { content: [] } });
+
+		expect(pi.appendEntry).not.toHaveBeenCalled();
+	});
+});

package/src/background/notify.ts

@@ -0,0 +1,218 @@
+/**
+ * 完成通知与 pending-notifications 接入（M3，设计 §3.5 数据流 ⑤⑧⑨ / §3.3 D5·D17）。
+ *
+ * 通道形态（与 pending-notifications index.ts listener / subagent-workflow notifier
+ * 先例对齐——先例经父进程 IPC 投递与本包同进程异步时机不同构，探针 P3 已实测）：
+ *  - register/unregister 经 pi.events.emit（EventBus，pending 侧 pi.events.on 消费）
+ *  - 完成通知经 pi.sendMessage({customType, content, display:true},
+ *    {deliverAs:"steer", triggerTurn:true}) 驱动新 turn
+ *
+ * D17 pi 引用刷新：轮询器与通知通路持模块级「当前 pi 引用」——同进程 session 替换
+ * （/fork、选择器切换、RPC session.*）会重建 eventBus 并重新 load extension，本
+ * 模块引用由新实例 load 时 refreshPiReference 刷新，完成通知投递新 session。
+ *
+ * 已知竞态（设计 §3.5 原样登记，不修）：dispose → 新实例 load 间毫秒窗口任务恰好
+ * 完成时，sendMessage/emit 落旧 bus 丢一条——对账在该 session 重开时补 unregister，
+ * 完成内容可由 bash_output 查询；窗口极窄且后果可恢复，不加同步握手。旧引用 throw
+ * （旧 bus 已 dispose）时捕获降级为日志，不中断轮询（后续任务仍可通知）。
+ *
+ * kill 路径不 sendMessage（§3.5「bash_kill 终态收尾的单点归属」）：reason:"killed"
+ * 只 emit unregister——kill 调用方就在当前 turn 等结果，双发是噪音。
+ *
+ * peer 版本门槛（D16 独立安装场景）——运行时检测**降级为静态声明**：pi 0.84.1 的
+ * ExtensionAPI/ExtensionContext 均无「枚举已加载 extensions」接口（types.d.ts 全文
+ * 核实，LoadExtensionsResult 是 loader 内部结果不经 pi 暴露），EventBus 探针式握手
+ * 属硬造检测机制（设计禁止）。登记落点：package.json peerDependencies（optional，
+ * 未装则通知链路缺失但 bash 后台功能完整）+ extension-dependencies.json dependsOn。
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { getLogger } from "@zhushanwen/pi-extension-logger";
+
+import type { BackgroundTask, BackgroundTaskEndReason } from "./types.ts";
+
+const logger = getLogger("base-tool-enhance");
+
+/**
+ * 通知消息 customType：桌面 custom_message 通用渲染通道（subagent-bg-notify 先例，
+ * §3.1 用户视角「对话流中以 custom entry 形式出现」）。
+ */
+export const BACKGROUND_BASH_CUSTOM_TYPE = "background-bash";
+
+/**
+ * pending register 的 name 截断长度（§3.5 数据流 ⑤「command 前 80 字符」）。
+ * 与 spawn-background COMMAND_DISPLAY_LIMIT 同值但刻意不共享 import——notify 被
+ * spawn-background import，反向 import 会造成 spawn ↔ notify 循环依赖；两处语义
+ * （pending 列表展示 / 错误文案展示）各自独立演化，仅数值对齐。
+ */
+const PENDING_NAME_LIMIT = 80;
+
+/** 模块级「当前 pi 引用」（D17 核心可变状态，见文件头）。 */
+let currentPi: ExtensionAPI | undefined;
+
+/**
+ * 刷新当前 pi 引用：extension 实例 load 时调用（index.ts 接线）。
+ * session 替换 → extension 重新 load → 引用指向新 pi → 完成通知投递新 session。
+ */
+export function refreshPiReference(pi: ExtensionAPI): void {
+	currentPi = pi;
+}
+
+/** 测试专用：复位模块级 pi 引用（跨测试文件残留清理）。 */
+export function resetNotifyForTest(): void {
+	currentPi = undefined;
+}
+
+/**
+ * 本包终态 reason → pending reason 字符串。
+ * 映射值全部落在 pending-notifications mapReasonToStatus 的已知分支（四个值在该
+ * switch 全部直通同名 status），保证 emit 后 listener 算出的 status 与本包预期一致：
+ *  - natural + exitCode 0 → "completed"（正常完成）
+ *  - natural + 非零/不可知 → "failed"（§3.1 失败路径：通知带 error 与末尾输出摘要）
+ *  - timeout   → "time_limited"
+ *  - killed    → "cancelled"
+ *  - process-exit → "cancelled"（进程退出收殓终止，非任务自身成败）
+ */
+export function toPendingReason(
+	reason: BackgroundTaskEndReason,
+	exitCode: number | null | undefined,
+): "completed" | "failed" | "time_limited" | "cancelled" {
+	switch (reason) {
+		case "timeout":
+			return "time_limited";
+		case "killed":
+		case "process-exit":
+			return "cancelled";
+		default:
+			// natural：exit 0 = 成功；非零（含 null 不可知，保守按失败处理引导查看输出）
+			return exitCode === 0 ? "completed" : "failed";
+	}
+}
+
+/**
+ * ⑤ 登记成功后 emit pending:register（§3.5 数据流 ⑤）。
+ * 形态对齐 pending-notifications parseRegisterEvent 期望：{id, type, name}——
+ * type:"bash" 经 D16 直通（process 档），**不携带 expiresAt**（该字段由 pending 侧
+ * listener 按分档决定，process 档落盘省略）。引用未注入或 emit throw（旧 bus）时
+ * 静默降级——pending 差集只影响通知链路，不影响任务本体。
+ */
+export function emitPendingRegister(task: BackgroundTask): void {
+	const pi = currentPi;
+	if (pi === undefined) return;
+	const name =
+		task.command.length > PENDING_NAME_LIMIT
+			? `${task.command.slice(0, PENDING_NAME_LIMIT)}…`
+			: task.command;
+	try {
+		pi.events.emit("pending:register", { id: task.taskId, type: "bash", name });
+	} catch (err) {
+		logger.warn("pending:register emit failed (stale bus?); task unaffected", {
+			detail: { taskId: task.taskId, err: err instanceof Error ? err.message : String(err) },
+		});
+	}
+}
+
+/**
+ * ⑧ emit pending:unregister（§3.5 数据流 ⑧）。
+ * data 形态对齐 pending-notifications parseUnregisterEvent 期望：{id, reason}——
+ * status 不在 emit data 里（listener 用 mapReasonToStatus(reason) 自行计算）；
+ * appendEntry 侧（对账/收殓）的落盘形态 {id, reason, status} 见 pending-reconcile.ts。
+ * 轮询器 exit 边沿与进程退出收殓两条路径共用。
+ */
+export function emitPendingUnregister(
+	taskId: string,
+	reason: BackgroundTaskEndReason,
+	exitCode: number | null | undefined,
+): void {
+	const pi = currentPi;
+	if (pi === undefined) return;
+	try {
+		pi.events.emit("pending:unregister", { id: taskId, reason: toPendingReason(reason, exitCode) });
+	} catch (err) {
+		logger.warn("pending:unregister emit failed (stale bus?); reconcile covers on next session_start", {
+			detail: { taskId, err: err instanceof Error ? err.message : String(err) },
+		});
+	}
+}
+
+/**
+ * ⑧⑨ 轮询器 exit 边沿的完成通知入口（poller setOnTaskExit 接线，index.ts load 时挂）。
+ * 入参是 finalizeTask 之后的终态条目（state=exited）。kill 路径不 sendMessage
+ * （文件头）；process-exit 不经过这里（收殓路径直接 finalizeTask + 只 emit）。
+ */
+export function handleTaskExit(task: BackgroundTask): void {
+	emitPendingUnregister(task.taskId, task.reason ?? "natural", task.exitCode ?? null);
+	if (task.reason === "killed") return;
+	sendTaskFinishedMessage(task);
+}
+
+/** ⑨ sendMessage steer 驱动新 turn（探针 P3 已实测同进程异步时机可用）。 */
+function sendTaskFinishedMessage(task: BackgroundTask): void {
+	const pi = currentPi;
+	if (pi === undefined) return;
+	try {
+		pi.sendMessage(
+			{ customType: BACKGROUND_BASH_CUSTOM_TYPE, content: buildNotificationContent(task), display: true },
+			{ deliverAs: "steer", triggerTurn: true },
+		);
+	} catch (err) {
+		// 旧 bus 已 dispose（session 替换毫秒窗口）——降级日志，不中断轮询（文件头已知竞态）
+		logger.warn("background task notify sendMessage failed; poll continues", {
+			detail: {
+				taskId: task.taskId,
+				err: err instanceof Error ? err.message : String(err),
+			},
+		});
+	}
+}
+
+/**
+ * 通知文案（§3.1 终态样例）：
+ *
+ *   [background-bash] bt-x finished (exit 0, 3m12s): pnpm test
+ *   Last lines: ... Tests: 42 passed ...
+ *   Full output: <path>; use bash_output {task_id:"bt-x"} for details.
+ *
+ * 失败任务 head 行标 failed（exit code 即 error 摘要，尾部输出佐证）；timeout 标
+ * timed out；tailSummary 为空（无输出/文件丢失）时省略 Last lines 行。
+ */
+export function buildNotificationContent(task: BackgroundTask): string {
+	const duration = formatDurationMs(task.durationMs ?? 0);
+	const command =
+		task.command.length > PENDING_NAME_LIMIT
+			? `${task.command.slice(0, PENDING_NAME_LIMIT)}…`
+			: task.command;
+	let head: string;
+	if (task.reason === "timeout") {
+		head = `[background-bash] ${task.taskId} timed out (${duration}): ${command}`;
+	} else if (task.exitCode === 0) {
+		head = `[background-bash] ${task.taskId} finished (exit 0, ${duration}): ${command}`;
+	} else {
+		head = `[background-bash] ${task.taskId} failed (exit ${task.exitCode ?? "unknown"}, ${duration}): ${command}`;
+	}
+	const lines = [head];
+	if (task.tailSummary !== undefined && task.tailSummary.length > 0) {
+		lines.push(`Last lines: ${task.tailSummary}`);
+	}
+	lines.push(`Full output: ${task.outputFile}; use bash_output {task_id:"${task.taskId}"} for details.`);
+	return lines.join("\n");
+}
+
+/** 耗时换算常量（毫秒/秒/分/时 + 时分两位补零宽度）。 */
+const MS_PER_SECOND = 1000;
+const SECONDS_PER_MINUTE = 60;
+const MINUTES_PER_HOUR = 60;
+const TWO_DIGIT_WIDTH = 2;
+
+/** 耗时格式：秒内 "45s" → 分 "3m12s" → 时 "1h02m03s"（时/分段补零两位）。 */
+function formatDurationMs(ms: number): string {
+	const totalSec = Math.max(0, Math.round(ms / MS_PER_SECOND));
+	const sec = totalSec % SECONDS_PER_MINUTE;
+	const min = Math.floor(totalSec / SECONDS_PER_MINUTE) % MINUTES_PER_HOUR;
+	const hour = Math.floor(totalSec / (SECONDS_PER_MINUTE * MINUTES_PER_HOUR));
+	if (hour > 0) {
+		return `${hour}h${String(min).padStart(TWO_DIGIT_WIDTH, "0")}m${String(sec).padStart(TWO_DIGIT_WIDTH, "0")}s`;
+	}
+	if (min > 0) return `${min}m${sec}s`;
+	return `${totalSec}s`;
+}

package/src/background/output-tail.ts

@@ -0,0 +1,84 @@
+/**
+ * 输出文件 tail 读取（D7：输出落文件不占内存，查询时按需读尾部）。
+ *
+ * 截断规则与 pi 内置 bash 一致：末尾 2000 行 / 50KB 先到为准（bash.js truncate.ts
+ * DEFAULT_MAX_LINES/DEFAULT_MAX_BYTES）。实现从文件末尾按字节窗口读（不整读大文件，
+ * O(maxBytes) 而非 O(fileSize)）。
+ */
+
+import { openSync, readSync, closeSync, statSync } from "node:fs";
+
+import { getLogger } from "@zhushanwen/pi-extension-logger";
+
+const logger = getLogger("base-tool-enhance");
+
+/** pi 内置 bash 同款截断上限（last 2000 lines / 50KB = 51200 bytes，先到为准）。 */
+export const TAIL_MAX_LINES = 2000;
+export const TAIL_MAX_BYTES = 51_200;
+/** 字节窗口余量：截窗口可能吞掉首行前半，余量降低残行概率。 */
+const TAIL_WINDOW_MARGIN_BYTES = 64;
+/** exit 边沿 tail 摘要参数（存条目/M3 通知用）。 */
+const SUMMARY_TAIL_LINES = 5;
+const SUMMARY_MAX_CHARS = 800;
+
+export interface TailResult {
+	output: string;
+	/** 读取窗口被截断（内容超上限）时 true。 */
+	truncated: boolean;
+}
+
+/**
+ * 读文件尾部（行/字节双上限）。文件不存在/不可读返回 undefined——bash_output 对
+ * 此降级为 {output:"<lost>"} 不崩溃（§3.6）。
+ */
+export function readOutputTail(
+	outputFile: string,
+	maxLines: number = TAIL_MAX_LINES,
+	maxBytes: number = TAIL_MAX_BYTES,
+): TailResult | undefined {
+	let size: number;
+	try {
+		size = statSync(outputFile).size;
+	} catch {
+		return undefined;
+	}
+	// 字节窗口从末尾取 maxBytes + 余量（截窗口可能吞掉首行前半，余量降低概率）
+	const windowSize = Math.min(size, maxBytes + TAIL_WINDOW_MARGIN_BYTES);
+	const buffer = Buffer.alloc(windowSize);
+	let fd: number | undefined;
+	try {
+		fd = openSync(outputFile, "r");
+		readSync(fd, buffer, 0, windowSize, size - windowSize);
+	} catch {
+		return undefined;
+	} finally {
+		if (fd !== undefined) {
+			try {
+				closeSync(fd);
+			} catch (err) {
+				// 已读完内容，close 失败不影响结果，仅留诊断
+				logger.debug("output tail close failed", {
+					detail: { outputFile, err: err instanceof Error ? err.message : String(err) },
+				});
+			}
+		}
+	}
+	const text = buffer.toString("utf8");
+	const lines = text.split("\n");
+	// 窗口起点可能落在行中间：首行是残行时丢弃（它必然不完整）
+	const firstLineIsPartial = windowSize < size && lines.length > 0;
+	const effectiveLines = firstLineIsPartial ? lines.slice(1) : lines;
+	const byteTruncated = size > maxBytes;
+	const shown = effectiveLines.slice(-maxLines).join("\n");
+	return { output: shown, truncated: byteTruncated || effectiveLines.length > maxLines };
+}
+
+/**
+ * 轮询器 exit 边沿的 tail 摘要（存进条目、M3 通知用）：末尾几行的紧凑文本。
+ */
+export function readTailSummary(outputFile: string, maxChars: number = SUMMARY_MAX_CHARS): string | undefined {
+	const tail = readOutputTail(outputFile, SUMMARY_TAIL_LINES, maxChars);
+	if (tail === undefined) return undefined;
+	const compact = tail.output.trim();
+	return compact.length > 0 ? compact.slice(-maxChars) : undefined;
+}

package/src/background/pending-reconcile.ts

@@ -0,0 +1,169 @@
+/**
+ * session_start pending 对账（M3，§3.5 接入细则第 4 条——pending 收尾的统一兜底）。
+ *
+ * 职责：对「session entries 差集显示 active、但任务已终态」的 bt- 任务补写
+ * pending:unregister entry。覆盖三类 otherwise 悬空场景（设计原文）：
+ *  ① 进程 graceful 退出收殓时 pi API 已不可用，unregister 没写成 entry；
+ *  ② 强杀后 reaper 只改 registry（标 orphaned），碰不了 session 文件；
+ *  ③ fork 后任务完成通知写进新 session，旧 session 文件的 register 成僵尸。
+ *
+ * 收尾写法（权威路径）：直接 pi.appendEntry("pending:unregister", {id, reason,
+ * status})——**不走 bus emit 作为权威**：pending-notifications 的 unregister listener
+ * 落盘条件是其内存 registry 该 id active（其 registry 只在自身 session_start rebuild
+ * 后非空），两个 extension 的加载/派发顺序（CLI --extension 顺序用户可控）无保障，
+ * 顺序反转时 emit 被静默吞、对账失效。差集消费方 goal 从持久化 entries 算差集
+ * （agent-end.ts getEntries()，不读 pending 内存 registry），appendEntry 对守卫直接
+ * 生效。appendEntry 之外尽力补一次 emit（listener 就绪时同步其内存视图，失败无害）。
+ *
+ * 终态判据：registry state ∈ {exited, orphaned}，或（state=running/killing 且
+ * kill(pid,0) 判死：收殓/写盘失败遗留的 running 条目按事实终态处理）。
+ * 不改 registry——终态写入归 reaper/轮询器（单点归属），对账只清 pending 侧。
+ *
+ * 执行顺序（index.ts session_start 链内）：reaper 先、对账后——先按属主判定处置
+ * 孤儿/补写 registry 终态，对账随后读到正确终态；即使颠倒也无静默错误（对账先见
+ * running+pid 活则不动作，下一 session_start 兜底）。
+ */
+
+import { getLogger } from "@zhushanwen/pi-extension-logger";
+
+import { isPidAlive } from "../kill-tree.ts";
+import { toPendingReason } from "./notify.ts";
+import { getRegistryPath, readRegistry } from "./registry.ts";
+import { isActiveState, isTerminalState, type RegistryEntry } from "./types.ts";
+
+const logger = getLogger("base-tool-enhance");
+
+/** 本包 task_id 前缀（§2.3，区别于 subagent-workflow 的 bg-/run-）。 */
+export const BTE_TASK_ID_PREFIX = "bt-";
+
+/**
+ * 对账依赖的最小 pi 面（结构兼容 ExtensionAPI 的子集；测试注入不造完整 pi）。
+ */
+export interface ReconcilePi {
+	appendEntry(customType: string, data?: unknown): void;
+	events: { emit(channel: string, data: unknown): void };
+}
+
+/** 对账结果（日志 + 测试断言面）。 */
+export interface ReconcileResult {
+	/** 补写 pending:unregister entry 的任务数。 */
+	reconciled: number;
+	/** 差集 active 但判据不满足（活任务 / registry 无条目）而保守跳过的 task_id。 */
+	skipped: string[];
+}
+
+/** entries 的最小可识别形状（duck-typed，与 pending-notifications state.ts EntryLike 同式）。 */
+interface EntryLike {
+	customType?: string;
+	data?: { id?: unknown } | null;
+}
+
+function readEntryId(raw: unknown): string | undefined {
+	if (!raw || typeof raw !== "object") return undefined;
+	const entry = raw as EntryLike;
+	const id = entry.data?.id;
+	return typeof id === "string" ? id : undefined;
+}
+
+/**
+ * 差集：bt- 前缀 pending:register 且无对应 pending:unregister 的 id 集合。
+ * 只认 bt- 前缀——workflow/subagent 的 register 不归本包对账（差集算法与
+ * pending-notifications countActiveFromEntries 同构：unregister 全局抵消 + register
+ * 去重，id 全局唯一前提）。
+ */
+export function collectUnsettledTaskIds(entries: unknown[]): Set<string> {
+	const unregistered = new Set<string>();
+	for (const raw of entries) {
+		if (!raw || typeof raw !== "object") continue;
+		if ((raw as EntryLike).customType !== "pending:unregister") continue;
+		const id = readEntryId(raw);
+		if (id !== undefined && id.startsWith(BTE_TASK_ID_PREFIX)) unregistered.add(id);
+	}
+	const active = new Set<string>();
+	for (const raw of entries) {
+		if (!raw || typeof raw !== "object") continue;
+		if ((raw as EntryLike).customType !== "pending:register") continue;
+		const id = readEntryId(raw);
+		if (id === undefined || !id.startsWith(BTE_TASK_ID_PREFIX)) continue;
+		if (unregistered.has(id) || active.has(id)) continue;
+		active.add(id);
+	}
+	return active;
+}
+
+/**
+ * 对账主体（同步：readRegistry / kill(pid,0) / appendEntry 均同步，session_start
+ * 链内毫秒级完成）。每个僵尸任务 appendEntry 一次 + 尽力 emit 一次。
+ */
+export function reconcilePendingEntries(
+	pi: ReconcilePi,
+	dataDir: string,
+	sessionId: string,
+	entries: unknown[],
+): ReconcileResult {
+	const result: ReconcileResult = { reconciled: 0, skipped: [] };
+	const unsettled = collectUnsettledTaskIds(entries);
+	if (unsettled.size === 0) return result;
+
+	const registry = readRegistry(getRegistryPath(dataDir, sessionId));
+	for (const id of unsettled) {
+		const entry = registry.get(id);
+		if (entry === undefined) {
+			// registry 无条目：终态无从判定（LRU 淘汰的终态条目其 unregister entry 应已
+			// 落盘，差集里还出现 = spawn 后 registry 写失败等罕见路径）——保守不动作，
+			// 差集残留交给 pending 自身 TTL 之外的 next-session 对账重查
+			result.skipped.push(id);
+			continue;
+		}
+		if (!isTerminalByRegistry(entry)) {
+			// D12 活任务（running/killing 且 pid 活）：任务跨 session 替换续存，不收尾
+			result.skipped.push(id);
+			continue;
+		}
+		const pendingReason = settledPendingReason(entry);
+		try {
+			pi.appendEntry("pending:unregister", { id, reason: pendingReason, status: pendingReason });
+		} catch (err) {
+			logger.warn("reconcile appendEntry failed; retry on next session_start", {
+				detail: { id, err: err instanceof Error ? err.message : String(err) },
+			});
+			continue;
+		}
+		// 尽力补 emit（listener 就绪时同步 pending 内存视图，缩短 pending_notifications
+		// 工具列表的不一致窗口；失败无害——appendEntry 已是权威路径）
+		try {
+			pi.events.emit("pending:unregister", { id, reason: pendingReason });
+		} catch (err) {
+			logger.debug("reconcile best-effort emit failed (harmless)", {
+				detail: { id, err: err instanceof Error ? err.message : String(err) },
+			});
+		}
+		result.reconciled++;
+	}
+	if (result.reconciled > 0) {
+		logger.debug("pending reconcile settled zombie registers", {
+			detail: { reconciled: result.reconciled, skipped: result.skipped.length },
+		});
+	}
+	return result;
+}
+
+/** 终态判据（§3.5 接入细则 4 原文）：registry 终态，或 active 状态但 pid 已判死。 */
+function isTerminalByRegistry(entry: RegistryEntry): boolean {
+	if (isTerminalState(entry.state)) return true;
+	return isActiveState(entry.state) && !isPidAlive(entry.pid);
+}
+
+/**
+ * 收尾 reason/status 映射：
+ *  - exited：按条目 reason/exitCode 走 toPendingReason（与 exit 边沿 emit 同一映射，
+ *    两路径写出的 entry 语义一致）；reason 缺失按 pending mapReasonToStatus 的
+ *    default=completed 语义处理（防御分支，正常路径 finalize 必写 reason）
+ *  - orphaned / running+判死：cancelled（任务非自身成败地终止/消失）
+ */
+function settledPendingReason(entry: RegistryEntry): "completed" | "failed" | "time_limited" | "cancelled" {
+	if (entry.state === "exited" && entry.reason !== undefined) {
+		return toPendingReason(entry.reason, entry.exitCode ?? null);
+	}
+	return "cancelled";
+}

package/src/background/poller.ts

@@ -0,0 +1,91 @@
+/**
+ * 模块级轮询器单例（D17：exit 感知靠轮询不靠 ChildProcess 闭包）。
+ *
+ * 为什么轮询：同进程 session 替换（fork/switch/new）会重建 eventBus 并重新 load
+ * extension，ChildProcess exit 闭包监听里的 bus/pi 引用全部 stale——完成通知在
+ * 新 session 不可达。kill(pid,0) 轮询 + 模块级单例跨替换免疫，2s 延迟对分钟级
+ * 任务无感。
+ *
+ * 惰性启停：无 running/killing 条目时清定时器（防空转泄漏），新任务登记时重启。
+ *
+ * 已知竞态（设计文档 §3.5 原样登记，不修）：同进程 session 替换 dispose → 新实例
+ * load 间毫秒窗口任务恰好完成时通知可能落旧 bus——窗口极窄且后果可恢复（bash_output
+ * 可查、对账可补），不加同步握手。
+ */
+
+import { isPidAlive } from "../kill-tree.ts";
+import { readTailSummary } from "./output-tail.ts";
+import { taskToRegistryEntry, writeRegistryEntry } from "./registry.ts";
+import { finalizeTask, getActiveTasks } from "./task-store.ts";
+import type { BackgroundTask } from "./types.ts";
+
+/** 轮询间隔（设计文档 §3.5：约 2s）。 */
+export const POLL_INTERVAL_MS = 2000;
+
+let pollTimer: ReturnType<typeof setInterval> | undefined;
+
+/**
+ * M3 通知接入点（本单元 no-op 占位）：exit 边沿收尾（单例表 + registry 终态写完）
+ * 之后同步回调。M3 在这里接 pending:unregister emit + sendMessage steer。
+ * 不在 M2 实现任何通知行为。
+ */
+let onTaskExitCallback: ((task: BackgroundTask) => void) | undefined;
+
+export function setOnTaskExit(callback: ((task: BackgroundTask) => void) | undefined): void {
+	onTaskExitCallback = callback;
+}
+
+/** 惰性启动：有活跃条目才跑定时器（spawn 登记与 kill/timeout 标记后调用）。 */
+export function ensurePollerRunning(): void {
+	if (pollTimer !== undefined) return;
+	pollTimer = setInterval(pollTick, POLL_INTERVAL_MS);
+	// 不阻止进程退出（收殓路径 stopPoller 统一清理）
+	pollTimer.unref?.();
+}
+
+export function stopPoller(): void {
+	if (pollTimer !== undefined) {
+		clearInterval(pollTimer);
+		pollTimer = undefined;
+	}
+}
+
+export function isPollerRunning(): boolean {
+	return pollTimer !== undefined;
+}
+
+function pollTick(): void {
+	const active = getActiveTasks();
+	if (active.length === 0) {
+		stopPoller();
+		return;
+	}
+	for (const task of active) {
+		// libuv 自动 reap 后 kill(pid,0) 报 ESRCH（判死），ChildProcess.exitCode 仍可读
+		if (!isPidAlive(task.pid)) {
+			finalizeExitedTask(task);
+		}
+	}
+}
+
+/** 测试专用：手动跑一轮轮询（不依赖 2s 定时器）。 */
+export function pollTickForTest(): void {
+	pollTick();
+}
+
+/**
+ * exit 边沿收尾（单一终态归属）：读 exitCode → 组装 tail 摘要 → reason 判定
+ * （intent.killed → "killed"、intent.timeout → "timeout"、无 intent → "natural"；
+ * "process-exit" 由收殓路径直接调 finalizeTask，不经这里）→ 单例表 + registry
+ * 两侧写终态 → 触发 onTaskExit 回调（M3 接入点）。
+ */
+function finalizeExitedTask(task: BackgroundTask): void {
+	const exitCode = task.child?.exitCode ?? null;
+	const reason = task.intent?.reason ?? "natural";
+	const endedAt = Date.now();
+	const tailSummary = readTailSummary(task.outputFile);
+	const finalized = finalizeTask(task.taskId, { exitCode, reason, endedAt, tailSummary });
+	if (finalized === undefined) return;
+	writeRegistryEntry(finalized.registryPath, taskToRegistryEntry(finalized));
+	onTaskExitCallback?.(finalized);
+}