@zhushanwen/pi-base-tool-enhance 0.2.0

package/src/__tests__/notify.test.ts

@@ -0,0 +1,335 @@
+// src/__tests__/notify.test.ts —— M3 通知通路单元：
+// register emit 形态（数据流 ⑤）/ exit 边沿通知（⑧⑨，含 killed 不 sendMessage）/
+// 通知文案 / D17 pi 引用刷新 / 收殓路径补 emit（process-exit 不 sendMessage）
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { killProcessTree } from "../kill-tree.ts";
+import {
+	BACKGROUND_BASH_CUSTOM_TYPE,
+	buildNotificationContent,
+	emitPendingRegister,
+	handleTaskExit,
+	refreshPiReference,
+	resetNotifyForTest,
+} from "../background/notify.ts";
+import { pollTickForTest, setOnTaskExit, stopPoller } from "../background/poller.ts";
+import { spawnBackgroundTask } from "../background/spawn-background.ts";
+import {
+	clearTaskStoreForTest,
+	getActiveTasks,
+	getTask,
+	markKillingIntent,
+} from "../background/task-store.ts";
+import type { BackgroundTask } from "../background/types.ts";
+
+vi.setConfig({ testTimeout: 20000 });
+
+const DATA_DIR = mkdtempSync(join(tmpdir(), "bte-notify-"));
+const SESSION_ID = "sess-notify";
+
+interface MockPi {
+	events: { emit: ReturnType<typeof vi.fn> };
+	sendMessage: ReturnType<typeof vi.fn>;
+	appendEntry: ReturnType<typeof vi.fn>;
+}
+
+function createMockPi(): MockPi {
+	return { events: { emit: vi.fn() }, sendMessage: vi.fn(), appendEntry: vi.fn() };
+}
+
+function attach(pi: MockPi): void {
+	refreshPiReference(pi as unknown as ExtensionAPI);
+}
+
+function sleep(ms: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function spawnBg(command: string) {
+	return spawnBackgroundTask({
+		command,
+		cwd: process.cwd(),
+		dataDir: DATA_DIR,
+		sessionId: SESSION_ID,
+	});
+}
+
+/** 构造终态条目直调 handleTaskExit（通知行为单元，不经真实轮询时序）。 */
+function finalizedTask(overrides: Partial<BackgroundTask> = {}): BackgroundTask {
+	return {
+		taskId: "bt-1700000000-test01",
+		pid: 4321,
+		command: "pnpm test",
+		outputFile: "/tmp/out/bt-1700000000-test01.log",
+		registryPath: "/tmp/out/registry.json",
+		startedAt: 1_700_000_000_000,
+		state: "exited",
+		ownerPiPid: process.pid,
+		sessionId: SESSION_ID,
+		exitCode: 0,
+		reason: "natural",
+		endedAt: 1_700_000_192_000,
+		durationMs: 192_000,
+		tailSummary: "Tests: 42 passed",
+		...overrides,
+	};
+}
+
+function killLeftoverTasks(): void {
+	for (const task of getActiveTasks()) {
+		try {
+			process.kill(-task.pid, "SIGKILL");
+		} catch {
+			try {
+				process.kill(task.pid, "SIGKILL");
+			} catch {
+				// already dead
+			}
+		}
+	}
+}
+
+afterEach(() => {
+	killLeftoverTasks();
+	clearTaskStoreForTest();
+	stopPoller();
+	setOnTaskExit(undefined);
+	resetNotifyForTest();
+	vi.restoreAllMocks();
+});
+
+describe("register emit (data flow ⑤)", () => {
+	it("emits pending:register {id, type:'bash', name} with NO expiresAt key after successful spawn", () => {
+		const pi = createMockPi();
+		attach(pi);
+		const spawned = spawnBg("sleep 0.5 && echo hi");
+		if (!spawned.ok) throw new Error(spawned.error);
+
+		expect(pi.events.emit).toHaveBeenCalledWith("pending:register", {
+			id: spawned.task.taskId,
+			type: "bash",
+			name: "sleep 0.5 && echo hi",
+		});
+		// process 档（D16）：emit 不携带 expiresAt——键级断言防字段悄悄混入
+		const payload = pi.events.emit.mock.calls.find((c) => c[0] === "pending:register")?.[1] as Record<
+			string,
+			unknown
+		>;
+		expect(Object.keys(payload)).not.toContain("expiresAt");
+	});
+
+	it("truncates name to 80 chars + ellipsis for long commands", () => {
+		const pi = createMockPi();
+		attach(pi);
+		const longCommand = `echo ${"x".repeat(200)}`;
+		const spawned = spawnBg(longCommand);
+		if (!spawned.ok) throw new Error(spawned.error);
+
+		const payload = pi.events.emit.mock.calls.find((c) => c[0] === "pending:register")?.[1] as {
+			name: string;
+		};
+		expect(payload.name).toBe(`${longCommand.slice(0, 80)}…`);
+		expect(payload.name.length).toBe(81);
+	});
+
+	it("skips emit silently (no throw) when pi reference is not attached", () => {
+		resetNotifyForTest();
+		const spawned = spawnBg("echo hi");
+		// 引用未注入（测试/极早期窗口）：emit 通路 no-op，spawn 本体不受影响
+		expect(spawned.ok).toBe(true);
+	});
+});
+
+describe("exit-edge notification (⑧⑨, poll edge wiring)", () => {
+	it("natural exit 0: unregister emit reason 'completed' + sendMessage steer with exact params", async () => {
+		const pi = createMockPi();
+		attach(pi);
+		setOnTaskExit(handleTaskExit);
+		const spawned = spawnBg("sleep 0.3 && echo done");
+		if (!spawned.ok) throw new Error(spawned.error);
+		const { task } = spawned;
+
+		await sleep(700);
+		pollTickForTest();
+
+		expect(pi.events.emit).toHaveBeenCalledWith("pending:unregister", {
+			id: task.taskId,
+			reason: "completed",
+		});
+		expect(pi.sendMessage).toHaveBeenCalledTimes(1);
+		const [message, options] = pi.sendMessage.mock.calls[0] as [
+			{ customType: string; content: string; display: boolean },
+			{ deliverAs: string; triggerTurn: boolean },
+		];
+		expect(message.customType).toBe(BACKGROUND_BASH_CUSTOM_TYPE);
+		expect(message.display).toBe(true);
+		expect(message.content).toContain(task.taskId);
+		expect(message.content).toContain("exit 0");
+		expect(message.content).toContain("done"); // tail 摘要
+		expect(options).toEqual({ deliverAs: "steer", triggerTurn: true });
+	});
+
+	it("killed: emits unregister reason 'cancelled' but does NOT sendMessage (single-point rule)", async () => {
+		const pi = createMockPi();
+		attach(pi);
+		setOnTaskExit(handleTaskExit);
+		const spawned = spawnBg("sleep 60");
+		if (!spawned.ok) throw new Error(spawned.error);
+		const { task } = spawned;
+
+		markKillingIntent(task.taskId, "killed");
+		killProcessTree(task.pid);
+		await sleep(500);
+		pollTickForTest();
+
+		expect(getTask(task.taskId)?.reason).toBe("killed");
+		expect(pi.events.emit).toHaveBeenCalledWith("pending:unregister", {
+			id: task.taskId,
+			reason: "cancelled",
+		});
+		// kill 调用方就在当前 turn 等结果：sendMessage 双发是噪音，绝不发送
+		expect(pi.sendMessage).not.toHaveBeenCalled();
+	});
+
+	it("timeout: still sends steer message with reason 'time_limited'", () => {
+		const pi = createMockPi();
+		attach(pi);
+		handleTaskExit(finalizedTask({ reason: "timeout", exitCode: null, durationMs: 15000 }));
+
+		expect(pi.events.emit).toHaveBeenCalledWith("pending:unregister", {
+			id: "bt-1700000000-test01",
+			reason: "time_limited",
+		});
+		expect(pi.sendMessage).toHaveBeenCalledTimes(1);
+		const [message] = pi.sendMessage.mock.calls[0] as [{ content: string }, unknown];
+		expect(message.content).toContain("timed out");
+	});
+
+	it("natural nonzero exit: reason 'failed', content marks failure", async () => {
+		const pi = createMockPi();
+		attach(pi);
+		setOnTaskExit(handleTaskExit);
+		const spawned = spawnBg("sleep 0.3; exit 3");
+		if (!spawned.ok) throw new Error(spawned.error);
+		const { task } = spawned;
+
+		await sleep(700);
+		pollTickForTest();
+
+		expect(pi.events.emit).toHaveBeenCalledWith("pending:unregister", {
+			id: task.taskId,
+			reason: "failed",
+		});
+		const [message] = pi.sendMessage.mock.calls[0] as [{ content: string }, unknown];
+		expect(message.content).toContain("failed (exit 3,");
+	});
+});
+
+describe("notification content (§3.1 sample)", () => {
+	it("finished: contains task_id, exit code, duration, command, Full output path, bash_output hint", () => {
+		const content = buildNotificationContent(finalizedTask());
+		expect(content).toContain("bt-1700000000-test01");
+		expect(content).toContain("exit 0");
+		expect(content).toContain("3m12s"); // 192000ms
+		expect(content).toContain("pnpm test");
+		expect(content).toContain("Last lines: Tests: 42 passed");
+		expect(content).toContain("Full output: /tmp/out/bt-1700000000-test01.log");
+		expect(content).toContain('bash_output {task_id:"bt-1700000000-test01"}');
+	});
+
+	it("failed: head marks failed with exit code; omits Last lines when tail empty", () => {
+		const content = buildNotificationContent(
+			finalizedTask({ exitCode: 3, tailSummary: undefined, durationMs: 5000 }),
+		);
+		expect(content).toContain("failed (exit 3, 5s)");
+		expect(content).not.toContain("Last lines");
+		expect(content).toContain("Full output:");
+	});
+
+	it("duration formatting: seconds / minutes / hours", () => {
+		expect(buildNotificationContent(finalizedTask({ durationMs: 45000 }))).toContain(", 45s):");
+		expect(buildNotificationContent(finalizedTask({ durationMs: 192000 }))).toContain("3m12s");
+		expect(buildNotificationContent(finalizedTask({ durationMs: 3_723_000 }))).toContain("1h02m03s");
+	});
+});
+
+describe("D17: pi reference refresh (session replacement takeover)", () => {
+	it("second load wins: notification goes through the NEW reference, old one untouched", () => {
+		const piA = createMockPi();
+		const piB = createMockPi();
+		attach(piA);
+		attach(piB); // session 替换 → 重新 load → 引用刷新
+		handleTaskExit(finalizedTask());
+		expect(piB.sendMessage).toHaveBeenCalledTimes(1);
+		expect(piA.sendMessage).not.toHaveBeenCalled();
+	});
+
+	it("stale reference throwing sendMessage does not break notification; later tasks still notify", () => {
+		const stale = createMockPi();
+		stale.sendMessage = vi.fn(() => {
+			throw new Error("stale bus disposed");
+		});
+		attach(stale);
+		expect(() => handleTaskExit(finalizedTask())).not.toThrow();
+
+		const fresh = createMockPi();
+		attach(fresh);
+		handleTaskExit(finalizedTask({ taskId: "bt-1700000000-test02" }));
+		expect(fresh.sendMessage).toHaveBeenCalledTimes(1);
+	});
+
+	it("poller keeps running when notification path throws inside the exit edge", async () => {
+		const stale = createMockPi();
+		stale.sendMessage = vi.fn(() => {
+			throw new Error("stale bus disposed");
+		});
+		stale.events.emit = vi.fn(() => {
+			throw new Error("stale bus emit");
+		});
+		attach(stale);
+		setOnTaskExit(handleTaskExit);
+
+		const first = spawnBg("sleep 0.3 && echo one");
+		const second = spawnBg("sleep 0.3 && echo two");
+		if (!first.ok || !second.ok) throw new Error("spawn failed");
+		await sleep(700);
+		// 边沿回调内部全捕获：pollTick 不抛，两条任务都完成终态化
+		expect(() => pollTickForTest()).not.toThrow();
+		expect(getTask(first.task.taskId)?.state).toBe("exited");
+		expect(getTask(second.task.taskId)?.state).toBe("exited");
+	});
+});
+
+describe("process-exit reap: best-effort unregister emit, no sendMessage", () => {
+	it("reapBackgroundTasksNow emits pending:unregister reason 'cancelled' (process-exit)", async () => {
+		const { reapBackgroundTasksNow, resetProcessExitGuardForTest } = await import(
+			"../background/process-exit-guard.ts"
+		);
+		const pi = createMockPi();
+		attach(pi);
+		const spawned = spawnBg("sleep 30");
+		if (!spawned.ok) throw new Error(spawned.error);
+
+		reapBackgroundTasksNow();
+
+		expect(pi.events.emit).toHaveBeenCalledWith("pending:unregister", {
+			id: spawned.task.taskId,
+			reason: "cancelled",
+		});
+		// 进程都退了，无投递目标：绝不 sendMessage
+		expect(pi.sendMessage).not.toHaveBeenCalled();
+		resetProcessExitGuardForTest();
+	});
+});
+
+describe("register emit direct unit (no spawn)", () => {
+	it("does nothing when reference unset; payload unchanged when attached late", () => {
+		resetNotifyForTest();
+		expect(() => emitPendingRegister(finalizedTask({ state: "running" }))).not.toThrow();
+	});
+});

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

@@ -0,0 +1,237 @@
+// src/__tests__/pending-reconcile.test.ts —— M3 session_start 对账单元（§3.5 接入细则 4）：
+// 差集收集 / 三类僵尸场景 appendEntry 权威路径 + 尽力 emit / 活任务与缺条目保守跳过
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import {
+	collectUnsettledTaskIds,
+	reconcilePendingEntries,
+	type ReconcilePi,
+} from "../background/pending-reconcile.ts";
+import { getRegistryPath, writeRegistryEntry } from "../background/registry.ts";
+import type { RegistryEntry } from "../background/types.ts";
+
+const DATA_DIR = mkdtempSync(join(tmpdir(), "bte-reconcile-"));
+const SESSION_ID = "sess-reconcile";
+
+function createMockPi(overrides: Partial<Pick<ReconcilePi, "appendEntry">> = {}): ReconcilePi {
+	return {
+		appendEntry: vi.fn(),
+		events: { emit: vi.fn() },
+		...overrides,
+	};
+}
+
+function makeRegistryEntry(overrides: Partial<RegistryEntry> = {}): RegistryEntry {
+	return {
+		taskId: "bt-1700000000-zomb01",
+		pid: 99999,
+		command: "sleep 3600",
+		outputFile: "/tmp/out.log",
+		startedAt: 1_700_000_000_000,
+		state: "orphaned",
+		ownerPiPid: 1,
+		sessionId: SESSION_ID,
+		...overrides,
+	};
+}
+
+/** 已死 pid：spawnSync 同步等待退出 + libuv reap，返回时 pid 必已终止。 */
+function deadPid(): number {
+	const result = spawnSync("true");
+	if (result.pid === undefined) throw new Error("no pid acquired for dead-pid probe");
+	return result.pid;
+}
+
+function registerEntry(id: string) {
+	return { customType: "pending:register", data: { id, type: "bash", name: "sleep 3600" } };
+}
+
+afterEach(() => {
+	rmSync(DATA_DIR, { recursive: true, force: true });
+	vi.restoreAllMocks();
+});
+
+describe("collectUnsettledTaskIds (bt- prefixed register/unregister diff)", () => {
+	it("collects bt- registers without a matching unregister", () => {
+		const ids = collectUnsettledTaskIds([
+			registerEntry("bt-a"),
+			registerEntry("bt-b"),
+			{ customType: "pending:unregister", data: { id: "bt-b", reason: "completed" } },
+		]);
+		expect([...ids]).toEqual(["bt-a"]);
+	});
+
+	it("ignores non-bt ids (subagent bg-/run- namespace not ours)", () => {
+		const ids = collectUnsettledTaskIds([
+			registerEntry("bg-1"),
+			registerEntry("run-x-1"),
+			registerEntry("bt-a"),
+		]);
+		expect([...ids]).toEqual(["bt-a"]);
+	});
+
+	it("dedupes repeated registers and tolerates malformed entries", () => {
+		const ids = collectUnsettledTaskIds([
+			null,
+			undefined,
+			{ customType: "pending:register" }, // data 缺失
+			{ customType: "pending:register", data: { id: 42 } }, // id 非字符串
+			registerEntry("bt-a"),
+			registerEntry("bt-a"),
+			{ customType: "other" },
+		]);
+		expect([...ids]).toEqual(["bt-a"]);
+	});
+});
+
+describe("reconcile scenario ①: graceful-exit leftover (registry exited, entry never written)", () => {
+	it("appends pending:unregister {id, reason, status} matching pending-notifications entry shape + best-effort emit", () => {
+		const entry = makeRegistryEntry({
+			taskId: "bt-1700000000-zomb01",
+			state: "exited",
+			reason: "natural",
+			exitCode: 0,
+		});
+		writeRegistryEntry(getRegistryPath(DATA_DIR, SESSION_ID), entry);
+		const pi = createMockPi();
+
+		const result = reconcilePendingEntries(pi, DATA_DIR, SESSION_ID, [registerEntry(entry.taskId)]);
+
+		expect(result.reconciled).toBe(1);
+		// 落盘形态逐字段对齐 pending-notifications index.ts unregister listener：{id, reason, status}
+		expect(pi.appendEntry).toHaveBeenCalledWith("pending:unregister", {
+			id: entry.taskId,
+			reason: "completed",
+			status: "completed",
+		});
+		// emit 形态 {id, reason}（status 由 listener mapReasonToStatus 计算）
+		expect(pi.events.emit).toHaveBeenCalledWith("pending:unregister", {
+			id: entry.taskId,
+			reason: "completed",
+		});
+	});
+
+	it("maps exited reason/exitCode through the same mapping as the exit edge", () => {
+		const cases: Array<[RegistryEntry, string]> = [
+			[makeRegistryEntry({ state: "exited", reason: "natural", exitCode: 3 }), "failed"],
+			[makeRegistryEntry({ state: "exited", reason: "timeout", exitCode: null }), "time_limited"],
+			[makeRegistryEntry({ state: "exited", reason: "killed", exitCode: null }), "cancelled"],
+			[makeRegistryEntry({ state: "exited", reason: "process-exit", exitCode: null }), "cancelled"],
+		];
+		for (const [entry, expectedReason] of cases) {
+			writeRegistryEntry(getRegistryPath(DATA_DIR, SESSION_ID), entry);
+			const pi = createMockPi();
+			reconcilePendingEntries(pi, DATA_DIR, SESSION_ID, [registerEntry(entry.taskId)]);
+			expect(pi.appendEntry).toHaveBeenCalledWith(
+				"pending:unregister",
+				{ id: entry.taskId, reason: expectedReason, status: expectedReason },
+			);
+		}
+	});
+});
+
+describe("reconcile scenario ②: reaper-only orphan (registry orphaned, session file untouched)", () => {
+	it("appends unregister with cancelled for orphaned entries", () => {
+		const entry = makeRegistryEntry({ state: "orphaned" });
+		writeRegistryEntry(getRegistryPath(DATA_DIR, SESSION_ID), entry);
+		const pi = createMockPi();
+
+		const result = reconcilePendingEntries(pi, DATA_DIR, SESSION_ID, [registerEntry(entry.taskId)]);
+
+		expect(result.reconciled).toBe(1);
+		expect(pi.appendEntry).toHaveBeenCalledWith("pending:unregister", {
+			id: entry.taskId,
+			reason: "cancelled",
+			status: "cancelled",
+		});
+	});
+});
+
+describe("reconcile scenario ③: running entry whose pid is already dead (fact-terminal)", () => {
+	it("appends unregister with cancelled when kill(pid,0) says dead", () => {
+		const entry = makeRegistryEntry({ state: "running", pid: deadPid() });
+		writeRegistryEntry(getRegistryPath(DATA_DIR, SESSION_ID), entry);
+		const pi = createMockPi();
+
+		const result = reconcilePendingEntries(pi, DATA_DIR, SESSION_ID, [registerEntry(entry.taskId)]);
+
+		expect(result.reconciled).toBe(1);
+		expect(pi.appendEntry).toHaveBeenCalledWith("pending:unregister", {
+			id: entry.taskId,
+			reason: "cancelled",
+			status: "cancelled",
+		});
+	});
+});
+
+describe("conservative no-op paths", () => {
+	it("running entry with LIVE pid is not settled (D12 task survives session replacement)", () => {
+		const entry = makeRegistryEntry({ state: "running", pid: process.pid }); // 当前测试进程 = 活 pid
+		writeRegistryEntry(getRegistryPath(DATA_DIR, SESSION_ID), entry);
+		const pi = createMockPi();
+
+		const result = reconcilePendingEntries(pi, DATA_DIR, SESSION_ID, [registerEntry(entry.taskId)]);
+
+		expect(result.reconciled).toBe(0);
+		expect(result.skipped).toEqual([entry.taskId]);
+		expect(pi.appendEntry).not.toHaveBeenCalled();
+	});
+
+	it("registry has no entry for the id → skip (terminal state unverifiable)", () => {
+		const pi = createMockPi();
+		const result = reconcilePendingEntries(pi, DATA_DIR, SESSION_ID, [registerEntry("bt-unknown")]);
+		expect(result.reconciled).toBe(0);
+		expect(result.skipped).toEqual(["bt-unknown"]);
+		expect(pi.appendEntry).not.toHaveBeenCalled();
+	});
+
+	it("entries with no bt- register → early no-op", () => {
+		const pi = createMockPi();
+		const result = reconcilePendingEntries(pi, DATA_DIR, SESSION_ID, [
+			{ customType: "pending:register", data: { id: "bg-1", type: "subagent" } },
+			{ customType: "user" },
+		]);
+		expect(result.reconciled).toBe(0);
+		expect(result.skipped).toEqual([]);
+		expect(pi.appendEntry).not.toHaveBeenCalled();
+	});
+
+	it("unsettled set empty (unregister already present) → no-op", () => {
+		const entry = makeRegistryEntry({ state: "orphaned" });
+		writeRegistryEntry(getRegistryPath(DATA_DIR, SESSION_ID), entry);
+		const pi = createMockPi();
+		const result = reconcilePendingEntries(pi, DATA_DIR, SESSION_ID, [
+			registerEntry(entry.taskId),
+			{ customType: "pending:unregister", data: { id: entry.taskId, reason: "cancelled" } },
+		]);
+		expect(result.reconciled).toBe(0);
+		expect(pi.appendEntry).not.toHaveBeenCalled();
+	});
+});
+
+describe("appendEntry failure tolerance", () => {
+	it("one appendEntry throw does not block the remaining zombie (count only successful)", () => {
+		const first = makeRegistryEntry({ taskId: "bt-1700000000-zomb01", state: "orphaned" });
+		const second = makeRegistryEntry({ taskId: "bt-1700000000-zomb02", state: "orphaned" });
+		writeRegistryEntry(getRegistryPath(DATA_DIR, SESSION_ID), first);
+		writeRegistryEntry(getRegistryPath(DATA_DIR, SESSION_ID), second);
+		const appendEntry = vi.fn((customType: string, data?: unknown) => {
+			if ((data as { id: string }).id === first.taskId) throw new Error("append failed");
+		});
+		const pi = createMockPi({ appendEntry });
+
+		const result = reconcilePendingEntries(pi, DATA_DIR, SESSION_ID, [
+			registerEntry(first.taskId),
+			registerEntry(second.taskId),
+		]);
+
+		expect(appendEntry).toHaveBeenCalledTimes(2);
+		expect(result.reconciled).toBe(1); // 仅第二条成功计数
+		expect(result.skipped).toEqual([]);
+	});
+});