@zhushanwen/pi-base-tool-enhance 0.6.1 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-base-tool-enhance",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "Base tool enhancement - override builtin bash tool: foreground delegates to pi official factory, incremental background mode (design decisions documented in source comments)",
   "type": "module",
   "main": "src/index.ts",
@@ -28,11 +28,11 @@
     "skills/"
   ],
   "dependencies": {
-    "@zhushanwen/extension-protocol": "0.13.0",
-    "@zhushanwen/pi-ext-guards": "0.4.1",
+    "@zhushanwen/extension-protocol": "0.15.0",
+    "@zhushanwen/pi-ext-guards": "0.4.2",
     "@zhushanwen/pi-extension-logger": "0.6.1",
     "@zhushanwen/pi-file-lock": "0.4.1",
-    "@zhushanwen/pi-llm-shared": "0.9.0"
+    "@zhushanwen/pi-llm-shared": "0.10.1"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.1.9",
@@ -41,7 +41,7 @@
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.84.4",
     "typebox": "*",
-    "@zhushanwen/pi-pending-notifications": "0.7.6"
+    "@zhushanwen/pi-pending-notifications": "0.7.7"
   },
   "peerDependenciesMeta": {
     "@zhushanwen/pi-pending-notifications": {

package/src/__tests__/background-lifecycle.test.ts

@@ -164,7 +164,8 @@ afterAll(() => {
 
 describe("real spawn lifecycle (poll edge finalization)", () => {
 	it("short task: running → exited with exitCode 0, output file readable, registry terminal", async () => {
-		const spawned = spawnBg("sleep 0.3 && echo done");
+		// 断言只要求「poll 边沿前 state=running」与退出产物，不依赖命令时长（终态化只在 finalizeTask）
+		const spawned = spawnBg("sleep 0.1 && echo done");
 		if (!spawned.ok) throw new Error(spawned.error);
 		const { task } = spawned;
 		expect(task.state).toBe("running");
@@ -192,19 +193,30 @@ describe("real spawn lifecycle (poll edge finalization)", () => {
 	});
 
 	it("poller interval auto-finalizes without manual tick (lazy start/stop)", async () => {
-		const spawned = spawnBg("sleep 0.3 && echo auto");
-		if (!spawned.ok) throw new Error(spawned.error);
-		const { task } = spawned;
-		// 不手动 tick，等真实 2s 轮询边沿（命令 0.3s 已退出，首轮 tick 即收尾）：
-		// 轮询等终态出现（真实定时器 + 满载下轮询边沿延迟不可预估）
-		await pollUntil(() => getTask(task.taskId)?.state === "exited", POLL_DEADLINE_SLOW_MS, "poller auto-finalization");
-		expect(getTask(task.taskId)?.state).toBe("exited");
-		// 无活跃条目后轮询器自停（防空转）
-		expect(getActiveTasks()).toHaveLength(0);
+		// 只 fake setInterval/clearInterval（setTimeout 保持真实：命令退出与 pollUntil
+		// 的等待都真实流逝）——2s 轮询间隔定时器进 fake 队列，advanceTimersByTime 推进
+		// 即触发真实 pollTick 边沿。本用例是「真实间隔边沿自动收尾（lazy start/stop）」
+		// 语义的唯一集成探针：边沿推进逻辑（pollTick 本体）原样执行，仅等待被压缩。
+		vi.useFakeTimers({ toFake: ["setInterval", "clearInterval"] });
+		try {
+			const spawned = spawnBg("sleep 0.1 && echo auto");
+			if (!spawned.ok) throw new Error(spawned.error);
+			const { task } = spawned;
+			// 真实等命令退出（不手动 tick——收尾必须来自轮询器定时器边沿）
+			await pollUntil(() => !isPidAlive(task.pid), 5000, "process to die without poll edge");
+			// fake 队列推进一个完整轮询间隔 → 首个真实边沿收尾
+			vi.advanceTimersByTime(2000);
+			expect(getTask(task.taskId)?.state).toBe("exited");
+			// 无活跃条目后轮询器自停（防空转）
+			expect(getActiveTasks()).toHaveLength(0);
+		} finally {
+			vi.useRealTimers();
+		}
 	});
 
 	it("nonzero exit code is surfaced (exitCode 1)", async () => {
-		const spawned = spawnBg("sleep 0.2; exit 3");
+		// 断言只看 exitCode 透写，不依赖命令时长
+		const spawned = spawnBg("sleep 0.1; exit 3");
 		if (!spawned.ok) throw new Error(spawned.error);
 		const { task } = spawned;
 		await pollUntilTicked(() => getTask(task.taskId)?.exitCode === 3, POLL_DEADLINE_MS, "exitCode to surface");
@@ -313,7 +325,8 @@ describe("bash_output tool", () => {
 	});
 
 	it("deleted output file degrades to <lost> without crashing (§3.6)", async () => {
-		const spawned = spawnBg("sleep 0.2 && echo gone");
+		// 断言只看退出后输出文件缺失的降级路径，不依赖命令时长
+		const spawned = spawnBg("sleep 0.1 && echo gone");
 		if (!spawned.ok) throw new Error(spawned.error);
 		const { task } = spawned;
 		await pollUntilTicked(() => getTask(task.taskId)?.state === "exited", POLL_DEADLINE_MS, "task finalization");
@@ -386,7 +399,8 @@ describe("bash_kill tool (killing intent, single-point finalization)", () => {
 	});
 
 	it("already exited task → killed:false with exit code", async () => {
-		const spawned = spawnBg("sleep 0.2");
+		// 断言只看已终态条目的 kill 拒绝，不依赖命令时长
+		const spawned = spawnBg("sleep 0.1");
 		if (!spawned.ok) throw new Error(spawned.error);
 		const { task } = spawned;
 		await pollUntilTicked(() => getTask(task.taskId)?.state === "exited", POLL_DEADLINE_MS, "task finalization");
@@ -434,7 +448,8 @@ describe("bash_kill tool (killing intent, single-point finalization)", () => {
 	});
 
 	it("P0-2.2: store entry whose pid already died (poll edge not landed) → already exited style, no kill/intent", async () => {
-		const spawned = spawnBg("sleep 0.2");
+		// 死亡等待 ~0.1s 远小于 2s 真实轮询首轮（单例表仍 running 是本用例前提）
+		const spawned = spawnBg("sleep 0.1");
 		if (!spawned.ok) throw new Error(spawned.error);
 		const { task } = spawned;
 		// 轮询进程死透（不 tick——单例表仍 running 是本用例前提）
@@ -603,21 +618,22 @@ describe("explicit background timeout (D6)", () => {
 	});
 
 	it("natural completion before the deadline cancels the timer (no late kill)", async () => {
-		// 全程真实 timers：命令 0.2s 完成 < 1s 超时
+		// 全程真实 timers：命令 0.1s 完成 < 0.5s 超时（真实时间必须真实流过——
+		// 本用例证明「到点不补杀」，fake 时钟会让回调先于进程死亡触发）
 		const before = killTreeCalls.length;
-		const spawned = spawnBg("sleep 0.2 && echo quick", { timeoutSec: 1 });
+		const spawned = spawnBg("sleep 0.1 && echo quick", { timeoutSec: 0.5 });
 		if (!spawned.ok) throw new Error(spawned.error);
 		const { task } = spawned;
 
-		// 轮询命令退出收尾（未到 1s deadline）
+		// 轮询命令退出收尾（未到 0.5s deadline）
 		await pollUntilTicked(() => getTask(task.taskId)?.state === "exited", POLL_DEADLINE_SLOW_MS, "natural finalization");
 		expect(getTask(task.taskId)?.state).toBe("exited");
 		expect(getTask(task.taskId)?.reason).toBe("natural");
 
 		// 越过 deadline 的时间窗内不得再补杀（终态化必须已清 timer）：轮询真实时钟
-		// 越过 deadline+余量后断言——这里等待的是时钟流逝本身，非子进程事件
+		// 越过 deadline+200ms 余量后断言——这里等待的是时钟流逝本身，非子进程事件
 		await pollUntil(
-			() => Date.now() >= task.startedAt + 1_000 + 500,
+			() => Date.now() >= task.startedAt + 500 + 200,
 			POLL_DEADLINE_SLOW_MS,
 			"real clock to pass the deadline window",
 		);
@@ -639,8 +655,7 @@ describe("D6-en: poller finalization reads back registry killing (cross-process
 		writeRegistryEntry(REGISTRY_PATH, taskToRegistryEntry({ ...task, state: "killing" }));
 		expect(getTask(task.taskId)?.intent).toBeUndefined(); // 前置：内存无 intent
 		process.kill(task.pid, "SIGKILL");
-		await sleep(500);
-		expect(isPidAlive(task.pid)).toBe(false);
+		await pollUntil(() => !isPidAlive(task.pid), 5000, "process to die after SIGKILL");
 		pollTickForTest();
 
 		const finalized = getTask(task.taskId);
@@ -663,8 +678,7 @@ describe("D6-en: poller finalization reads back registry killing (cross-process
 		//（模拟 intent 落盘失败）——若实现误读回，会按 running 判 natural
 		expect(markKillingIntent(task.taskId, "killed")).toBeDefined();
 		process.kill(task.pid, "SIGKILL");
-		await sleep(500);
-		expect(isPidAlive(task.pid)).toBe(false);
+		await pollUntil(() => !isPidAlive(task.pid), 5000, "process to die after SIGKILL");
 		expect(readRegistry(REGISTRY_PATH).get(task.taskId)?.state).toBe("running"); // 前置成立
 		pollTickForTest();
 		expect(getTask(task.taskId)?.reason).toBe("killed"); // intent 优先，非 natural
@@ -676,7 +690,7 @@ describe("D6-en: poller finalization reads back registry killing (cross-process
 		const { task } = spawned;
 		writeFileSync(REGISTRY_PATH, "{corrupted", "utf8"); // 读回路径解析失败
 		process.kill(task.pid, "SIGKILL");
-		await sleep(500);
+		await pollUntil(() => !isPidAlive(task.pid), 5000, "process to die after SIGKILL");
 		pollTickForTest();
 		const finalized = getTask(task.taskId);
 		expect(finalized?.state).toBe("exited"); // 终态化未被阻塞
@@ -686,15 +700,21 @@ describe("D6-en: poller finalization reads back registry killing (cross-process
 
 describe("D6-en/R2-S1 hardening: armBackgroundTimeout skips kill+mark when recorded pid is gone", () => {
 	it("UI kill × timeout overlap: no timeout mark; poll edge reads back registry killing → killed", async () => {
-		const spawned = spawnBg("sleep 30", { timeoutSec: 1 });
+		// 真实时间必须真实流过（R2-S1 前提：到点时 pid 已死才有「跳过补杀」可言），
+		// fake 时钟会让 timeout 回调先于进程死亡触发
+		const spawned = spawnBg("sleep 30", { timeoutSec: 0.5 });
 		if (!spawned.ok) throw new Error(spawned.error);
 		const { task } = spawned;
 		// UI 代杀（跨进程形态）：registry 预写 killing + 直接杀进程，不经内存
 		writeRegistryEntry(REGISTRY_PATH, taskToRegistryEntry({ ...task, state: "killing" }));
 		process.kill(task.pid, "SIGKILL");
-		await sleep(500); // 进程死亡 + libuv reap（deadline 1s 之前）
-		expect(isPidAlive(task.pid)).toBe(false);
-		await sleep(700); // 越过 deadline（累计 ~1.2s，仍在 2s 轮询 tick 之前）
+		await pollUntil(() => !isPidAlive(task.pid), 5000, "process to die before the deadline");
+		// 越过 deadline（0.5s）+200ms 余量：轮询真实时钟，等待的是时钟流逝本身
+		await pollUntil(
+			() => Date.now() >= task.startedAt + 500 + 200,
+			POLL_DEADLINE_SLOW_MS,
+			"real clock to pass the deadline window",
+		);
 		// 加固生效：不补杀、不改写内存（无 intent）、不冲掉 registry 侧 killing 预写
 		expect(killTreeCalls).not.toContain(task.pid);
 		expect(getTask(task.taskId)?.state).toBe("running");
@@ -706,14 +726,18 @@ describe("D6-en/R2-S1 hardening: armBackgroundTimeout skips kill+mark when recor
 	});
 
 	it("AI bash_kill × timeout overlap: killed intent survives (no 'timed out' misreport)", async () => {
-		const spawned = spawnBg("sleep 30", { timeoutSec: 1 });
+		const spawned = spawnBg("sleep 30", { timeoutSec: 0.5 });
 		if (!spawned.ok) throw new Error(spawned.error);
 		const { task } = spawned;
 		const killed = JSON.parse(await killTool(task.taskId)) as { killed: boolean };
 		expect(killed.killed).toBe(true);
-		await sleep(500); // 进程死亡 + reap（deadline 之前）
-		expect(isPidAlive(task.pid)).toBe(false);
-		await sleep(700); // 越过 deadline：pid 已死 → 跳过 timeout mark
+		await pollUntil(() => !isPidAlive(task.pid), 5000, "process to die before the deadline");
+		// 越过 deadline（0.5s）+200ms 余量：轮询真实时钟——pid 已死 → 跳过 timeout mark
+		await pollUntil(
+			() => Date.now() >= task.startedAt + 500 + 200,
+			POLL_DEADLINE_SLOW_MS,
+			"real clock to pass the deadline window",
+		);
 		expect(getTask(task.taskId)?.intent?.reason).toBe("killed"); // 未被覆盖为 timeout
 		expect(killTreeCalls.filter((pid) => pid === task.pid)).toHaveLength(1); // 无第二次 kill
 		pollTickForTest();
@@ -722,15 +746,20 @@ describe("D6-en/R2-S1 hardening: armBackgroundTimeout skips kill+mark when recor
 	});
 
 	it("natural death before the deadline: no timeout mark; poll edge finalizes natural (accepted shift)", async () => {
+		// 命令 0.1s 自然退出 < 0.5s deadline；真实时间必须真实流过（fake 会先于死亡触发回调）
 		const before = killTreeCalls.length;
-		const spawned = spawnBg("sleep 0.3", { timeoutSec: 1 });
+		const spawned = spawnBg("sleep 0.1", { timeoutSec: 0.5 });
 		if (!spawned.ok) throw new Error(spawned.error);
 		const { task } = spawned;
-		await sleep(600); // 自然死亡 + reap，deadline(1s) 未到
-		expect(getTask(task.taskId)?.state).toBe("running"); // 轮询未收尾（不手动 tick）
-		await sleep(600); // 越过 deadline（累计 ~1.2s，仍在 2s 轮询 tick 之前）
+		await pollUntil(() => !isPidAlive(task.pid), 5000, "natural death before the deadline");
+		// 越过 deadline（0.5s）+200ms 余量（仍在 2s 真实轮询 tick 之前，不手动 tick）
+		await pollUntil(
+			() => Date.now() >= task.startedAt + 500 + 200,
+			POLL_DEADLINE_SLOW_MS,
+			"real clock to pass the deadline window",
+		);
 		expect(killTreeCalls.length).toBe(before); // 死任务不补杀
-		expect(getTask(task.taskId)?.state).toBe("running"); // 未被标 killing
+		expect(getTask(task.taskId)?.state).toBe("running"); // 轮询未收尾，未被标 killing
 		expect(getTask(task.taskId)?.intent).toBeUndefined();
 		expect(readRegistry(REGISTRY_PATH).get(task.taskId)?.state).toBe("running");
 		pollTickForTest();
@@ -766,16 +795,16 @@ describe("process-exit reap (D12)", () => {
 describe("D15: abort signal does not propagate to background tasks", () => {
 	it("aborted execute-signal leaves the task running", async () => {
 		const controller = new AbortController();
-		const spawned = spawnBg("sleep 5");
+		const spawned = spawnBg("sleep 1");
 		if (!spawned.ok) throw new Error(spawned.error);
 		const { task } = spawned;
 		// 模拟用户中断当前 turn：signal abort（后台分支不接触 signal，此处模拟上游已 abort）
 		controller.abort();
 		expect(controller.signal.aborted).toBe(true);
 
-		// 非断言性观察窗口（留事件传播时间）：断言的是「任务不受 abort 影响」的
-		// 负向不变量，期望状态恒真，轮询语义不适用
-		await sleep(300);
+		// 非断言性观察窗口（150ms，留事件传播时间；命令 sleep 1 未退出）：断言的是
+		// 「任务不受 abort 影响」的负向不变量，期望状态恒真，轮询语义不适用
+		await sleep(150);
 		// 任务不受中断影响：进程活、状态 running
 		expect(isPidAlive(task.pid)).toBe(true);
 		expect(getTask(task.taskId)?.state).toBe("running");

package/src/__tests__/index.test.ts

@@ -24,6 +24,7 @@ import baseToolEnhanceExtension from "../index.ts";
 function createMockPi() {
 	return {
 		registerTool: vi.fn(),
+		registerCommand: vi.fn(),
 		on: vi.fn(),
 		appendEntry: vi.fn(),
 		events: { emit: vi.fn(), on: vi.fn() },
@@ -71,6 +72,75 @@ describe("baseToolEnhanceExtension entry", () => {
 
 		expect(pi.on).toHaveBeenCalledWith("session_start", expect.any(Function));
 	});
+
+	it("registers the __taiji_bg_reconcile__ internal command with a non-empty description", () => {
+		setupOfficialFactory();
+		const pi = createMockPi();
+
+		baseToolEnhanceExtension(pi as unknown as ExtensionAPI);
+
+		expect(pi.registerCommand).toHaveBeenCalledTimes(1);
+		const [name, def] = pi.registerCommand.mock.calls[0] as [
+			string,
+			{ description: string; handler: (args: string, ctx: unknown) => Promise<void> },
+		];
+		expect(name).toBe("__taiji_bg_reconcile__");
+		expect(typeof def.description).toBe("string");
+		expect(def.description.length).toBeGreaterThan(0);
+		expect(typeof def.handler).toBe("function");
+	});
+});
+
+describe("__taiji_bg_reconcile__ command: runtime-resume trigger face (bg-task-notify-durability)", () => {
+	it("handler runs the same maintenance chain as session_start (zombie settle via appendEntry on the SAME pi reference)", async () => {
+		setupOfficialFactory();
+		// 独立临时 dataDir（同 session_start 用例：维护链只读不扫），registry 预置终态僵尸条目
+		const dataDir = mkdtempSync(join(tmpdir(), "bte-bgcmd-"));
+		dataDirRef.dir = dataDir;
+		try {
+			const sessionId = "sess-bgcmd";
+			writeRegistryEntry(getRegistryPath(dataDir, sessionId), {
+				taskId: "bt-1700000000-bgc001",
+				pid: 12345,
+				command: "sleep 3600",
+				outputFile: "/tmp/bgc.log",
+				startedAt: 1_700_000_000_000,
+				state: "orphaned",
+				ownerPiPid: 1,
+				sessionId,
+			});
+			const pi = createMockPi();
+			baseToolEnhanceExtension(pi as unknown as ExtensionAPI);
+
+			const [, def] = pi.registerCommand.mock.calls[0] as [
+				string,
+				{ description: string; handler: (args: string, ctx: unknown) => Promise<void> },
+			];
+			// handler 返回维护链 promise（runtime 侧 fire-and-forget 消费；本测试 await 落定）
+			await def.handler("", {
+				sessionManager: {
+					getSessionId: () => sessionId,
+					getEntries: () => [
+						{
+							customType: "pending:register",
+							data: { id: "bt-1700000000-bgc001", type: "bash", name: "sleep 3600" },
+						},
+					],
+				},
+			});
+
+			expect(pi.appendEntry).toHaveBeenCalledWith("pending:unregister", {
+				id: "bt-1700000000-bgc001",
+				reason: "cancelled",
+				status: "cancelled",
+			});
+			expect(pi.events.emit).not.toHaveBeenCalled();
+		} finally {
+			rmSync(dataDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
+			dataDirRef.dir = "/tmp/bte-fake-agent-dir";
+			resetNotifyForTest();
+		}
+	});
 });
 
 describe("session_start chain: reconcile (M3, reap sunk into runtime by u-bte-remove)", () => {

package/src/__tests__/maintenance-once.test.ts

@@ -47,6 +47,9 @@ import type { ExtensionAPI, SessionStartEvent } from "@earendil-works/pi-coding-
 function createMockPi() {
 	return {
 		registerTool: vi.fn(),
+		// __taiji_bg_reconcile__ 第二触发面（runtime 切回补投）注册桩——本文件只验证
+		// session_start 入口，命令注册面断言在 index.test.ts
+		registerCommand: vi.fn(),
 		on: vi.fn(),
 		appendEntry: vi.fn(),
 		events: { emit: vi.fn(), on: vi.fn() },
@@ -57,7 +60,8 @@ function createMockPi() {
 function getSessionStartHandler(pi: ReturnType<typeof createMockPi>) {
 	const handler = pi.on.mock.calls.find((call) => call[0] === "session_start")?.[1];
 	expect(handler).toBeTypeOf("function");
-	return handler as (event: SessionStartEvent, ctx: unknown) => void;
+	// handler 返回 promise（补投 await sendMessage 使维护链 async 化，bg-task-notify-durability）
+	return handler as (event: SessionStartEvent, ctx: unknown) => Promise<void>;
 }
 
 function makeEvent(reason: SessionStartEvent["reason"]): SessionStartEvent {
@@ -109,9 +113,9 @@ describe("session_start maintenance chain after reap sink (u-bte-remove)", () =>
 
 		// 多派发覆盖真实形态：startup + resume 双发（桌面端每次激活）+ new；
 		// factory 二调 handler 累积时同一事件被多组 handler 各跑一次，同理多次执行
-		handler(makeEvent("startup"), ctx);
-		handler(makeEvent("resume"), ctx);
-		handler(makeEvent("new"), ctx);
+		await handler(makeEvent("startup"), ctx);
+		await handler(makeEvent("resume"), ctx);
+		await handler(makeEvent("new"), ctx);
 
 		expect(reconcileMock).toHaveBeenCalledTimes(3);
 		expect(reconcileMock).toHaveBeenNthCalledWith(1, expect.anything(), dataDirRef.dir, "sid-once", []);
@@ -127,8 +131,8 @@ describe("session_start maintenance chain after reap sink (u-bte-remove)", () =>
 		const handler = getSessionStartHandler(pi);
 		const ctx = makeCtx();
 
-		handler(makeEvent("startup"), ctx);
-		handler(makeEvent("resume"), ctx);
+		await handler(makeEvent("startup"), ctx);
+		await handler(makeEvent("resume"), ctx);
 
 		// 每次派发恰好一条入口日志（无条件 = 不以任何条件短路），reason 取自事件；
 		// reapSkipped 字段已随 reap 下沉移除（u-bte-remove 变更登记，S6「批 2 后
@@ -142,20 +146,41 @@ describe("session_start maintenance chain after reap sink (u-bte-remove)", () =>
 		});
 	});
 
-	it("keeps reconcile failures non-fatal: warn logged, dispatch chain not throwing", async () => {
+	it("keeps reconcile failures non-fatal: handler promise resolves, warn logged", async () => {
+		// async 化后的非致命语义（bg-task-notify-durability U3 防假绿改写）：维护链已
+		// async——同步 not.toThrow() 断言恒真，改为显式断言「handler 的 promise resolve
+		//（错误在链内被 async 捕获，不向上传播成 unhandled rejection）+ warn 日志确实
+		// 记录」。两个断言缺一即红：吞掉后不打日志 = 观测丢失；打日志但 reject = fire
+		// 调用点 unhandled rejection。
+		reconcileMock.mockImplementation(() => Promise.reject(new Error("reconcile boom")));
+		const mod = await loadExtension();
+		const pi = createMockPi();
+		mod.default(pi as unknown as ExtensionAPI);
+		const handler = getSessionStartHandler(pi);
+
+		// 对账 reject 被维护链 async 捕获记 warn（僵尸停留差集，下一 session_start 幂等重查）
+		await expect(handler(makeEvent("resume"), makeCtx())).resolves.toBeUndefined();
+		expect(loggerMock.warn).toHaveBeenCalledWith(
+			"session_start pending reconcile failed; zombies retried next session start",
+			expect.objectContaining({ detail: expect.objectContaining({ err: "reconcile boom" }) }),
+		);
+	});
+
+	it("async chain surfaces synchronous setup errors through the same warn path", async () => {
+		// 同步 throw（非 promise reject）走同一 catch：覆盖 getSessionId 抛错等装配期异常，
+		// 锁定「try 块包住整个 await 链」不因 async 化出现裸同步段
 		reconcileMock.mockImplementation(() => {
-			throw new Error("reconcile boom");
+			throw new Error("sync boom");
 		});
 		const mod = await loadExtension();
 		const pi = createMockPi();
 		mod.default(pi as unknown as ExtensionAPI);
 		const handler = getSessionStartHandler(pi);
 
-		// 对账抛错被维护链吞掉记 warn（僵尸停留差集，下一 session_start 幂等重查）
-		expect(() => handler(makeEvent("resume"), makeCtx())).not.toThrow();
+		await expect(handler(makeEvent("resume"), makeCtx())).resolves.toBeUndefined();
 		expect(loggerMock.warn).toHaveBeenCalledWith(
 			"session_start pending reconcile failed; zombies retried next session start",
-			expect.objectContaining({ detail: expect.objectContaining({ err: "reconcile boom" }) }),
+			expect.objectContaining({ detail: expect.objectContaining({ err: "sync boom" }) }),
 		);
 	});
 });

package/src/__tests__/notify-reconcile-judgement.test.ts

@@ -0,0 +1,148 @@
+// src/__tests__/notify-reconcile-judgement.test.ts —— 补投判据纯函数（设计 §5 U1）：
+// ① collectDeliveredTaskIds 五形态（正常消息/fork 副本/缺 details 旧消息/非 bash
+// 通知/killed 无痕迹任务）+ content 双落盘形态容错；② 补投标记 entry 读写形态
+// （customType background-bash:reconciled，data {taskId, reconciledAt}）
+import { describe, expect, it } from "vitest";
+
+import { BACKGROUND_BASH_CUSTOM_TYPE } from "../background/notify.ts";
+import {
+	buildReconciledMarkerData,
+	collectDeliveredTaskIds,
+	collectReconciledTaskIds,
+	RECONCILED_MARKER_CUSTOM_TYPE,
+} from "../background/notify-reconcile-judgement.ts";
+
+const TASK_ID = "bt-1700000000-abcd12";
+const OTHER_TASK_ID = "bt-1700000000-efgh34";
+
+/** 送达消息 entry（pi CustomMessageEntry 落盘形态：type=custom_message + customType）。 */
+function deliveredEntry(overrides: {
+	taskId?: string;
+	details?: unknown;
+	content?: unknown;
+	customType?: string;
+} = {}): Record<string, unknown> {
+	const taskId = overrides.taskId ?? TASK_ID;
+	return {
+		type: "custom_message",
+		customType: overrides.customType ?? BACKGROUND_BASH_CUSTOM_TYPE,
+		content: overrides.content ?? `[background-bash] ${taskId} finished (exit 0, 3m12s): pnpm test\nFull output: /tmp/out/${taskId}.log`,
+		details: "details" in overrides ? overrides.details : { taskId, endReason: "natural", exitCode: 0 },
+		display: true,
+	};
+}
+
+describe("collectDeliveredTaskIds: five entry shapes (design §5 U1)", () => {
+	it("normal delivered message: hits via details.taskId and content both", () => {
+		const ids = collectDeliveredTaskIds([deliveredEntry()]);
+		expect([...ids]).toEqual([TASK_ID]);
+	});
+
+	it("fork copy (same shape carried into the forked session): hits identically", () => {
+		// fork 复制 session 文件时送达消息原样带走——同形态命中是决策 5 的构造性来源
+		const ids = collectDeliveredTaskIds([
+			{ type: "user", content: "hello" }, // fork 前的旧消息
+			deliveredEntry(), // 复制带来的送达消息
+			{ type: "user", content: "after fork" },
+		]);
+		expect([...ids]).toEqual([TASK_ID]);
+	});
+
+	it("legacy message without details: hits via content token alone", () => {
+		const ids = collectDeliveredTaskIds([
+			deliveredEntry({ details: undefined }),
+		]);
+		expect([...ids]).toEqual([TASK_ID]);
+	});
+
+	it("non-bash notification (different customType, content mentions bt- token): does NOT hit", () => {
+		const ids = collectDeliveredTaskIds([
+			deliveredEntry({ customType: "subagent-bg-notify" }),
+			deliveredEntry({ customType: "background-bash:reconciled", details: undefined }),
+		]);
+		expect(ids.size).toBe(0);
+	});
+
+	it("killed task with no delivery message: naturally absent (empty entries side)", () => {
+		// kill 路径不产通知（notify.ts 单点归属规则）——entries 无该任务消息，集合不含它，
+		// 补投判据的排除由 registry reason=killed 承担（执行器侧用例），此处锁定痕迹面为空
+		const ids = collectDeliveredTaskIds([
+			deliveredEntry(), // 只有别的任务的送达消息
+			{ type: "custom", customType: "pending:unregister", data: { id: OTHER_TASK_ID, reason: "cancelled" } },
+		]);
+		expect(ids.has(TASK_ID)).toBe(true);
+		expect(ids.has(OTHER_TASK_ID)).toBe(false);
+	});
+});
+
+describe("collectDeliveredTaskIds: content落盘形态与脏数据容错", () => {
+	it("TextContent[] content form (appendCustomMessageEntry accepts arrays) hits via text blocks", () => {
+		const ids = collectDeliveredTaskIds([
+			deliveredEntry({
+				details: undefined,
+				content: [{ type: "text", text: `[background-bash] ${TASK_ID} finished (exit 0, 5s): pnpm test` }],
+			}),
+		]);
+		expect([...ids]).toEqual([TASK_ID]);
+	});
+
+	it("malformed entries (null / primitives / wrong field types) are skipped, not fatal", () => {
+		const ids = collectDeliveredTaskIds([
+			null,
+			undefined,
+			42,
+			"custom_message",
+			{ customType: BACKGROUND_BASH_CUSTOM_TYPE }, // content/details 均缺
+			{ customType: BACKGROUND_BASH_CUSTOM_TYPE, content: 123, details: "no" },
+			deliveredEntry({ details: { taskId: 42 } }), // details.taskId 非字符串 → 只剩 content 通道
+		]);
+		expect([...ids]).toEqual([TASK_ID]);
+	});
+
+	it("multiple messages across tasks collect all ids", () => {
+		const ids = collectDeliveredTaskIds([
+			deliveredEntry(),
+			deliveredEntry({ taskId: OTHER_TASK_ID, details: undefined }),
+		]);
+		expect([...ids].sort()).toEqual([TASK_ID, OTHER_TASK_ID].sort());
+	});
+});
+
+describe("reconciled marker entry: write/read shape contract (design decision 1)", () => {
+	it("buildReconciledMarkerData produces {taskId, reconciledAt}", () => {
+		expect(buildReconciledMarkerData(TASK_ID, 1_700_000_000_000)).toEqual({
+			taskId: TASK_ID,
+			reconciledAt: 1_700_000_000_000,
+		});
+	});
+
+	it("marker customType is the plain-entry channel, distinct from the delivery customType", () => {
+		// 通道纪律：账务走 plain custom entry（appendEntry），送达消息走 sendMessage——
+		// 两者 customType 不得混用（NotifyLedger 同款纪律）
+		expect(RECONCILED_MARKER_CUSTOM_TYPE).toBe("background-bash:reconciled");
+		expect(RECONCILED_MARKER_CUSTOM_TYPE).not.toBe(BACKGROUND_BASH_CUSTOM_TYPE);
+	});
+
+	it("collectReconciledTaskIds picks marker entries and tolerates malformed data", () => {
+		const ids = collectReconciledTaskIds([
+			{ type: "custom", customType: RECONCILED_MARKER_CUSTOM_TYPE, data: { taskId: TASK_ID, reconciledAt: 1 } },
+			{ type: "custom", customType: RECONCILED_MARKER_CUSTOM_TYPE }, // data 缺失
+			{ type: "custom", customType: RECONCILED_MARKER_CUSTOM_TYPE, data: { reconciledAt: 2 } }, // taskId 缺
+			{ type: "custom", customType: RECONCILED_MARKER_CUSTOM_TYPE, data: { taskId: 42 } }, // 非字符串
+			{ type: "custom_message", customType: RECONCILED_MARKER_CUSTOM_TYPE, data: { taskId: OTHER_TASK_ID } }, // 误入消息通道的形态仍按 data 读
+			deliveredEntry(), // 送达消息不是标记
+			null,
+			7,
+		]);
+		expect([...ids].sort()).toEqual([TASK_ID, OTHER_TASK_ID].sort());
+	});
+
+	it("delivered and reconciled collectors partition the two anchors without cross-talk", () => {
+		const entries = [
+			deliveredEntry(), // TASK_ID 送达痕迹在
+			{ type: "custom", customType: RECONCILED_MARKER_CUSTOM_TYPE, data: { taskId: OTHER_TASK_ID, reconciledAt: 1 } },
+		];
+		expect(collectDeliveredTaskIds(entries).has(OTHER_TASK_ID)).toBe(false);
+		expect(collectReconciledTaskIds(entries).has(TASK_ID)).toBe(false);
+	});
+});

package/src/__tests__/notify.test.ts

@@ -135,13 +135,13 @@ 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");
+		const spawned = spawnBg("sleep 0.1 && 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",
+			name: "sleep 0.1 && echo hi",
 		});
 		// process 档（D16）：emit 不携带 expiresAt——键级断言防字段悄悄混入
 		const payload = pi.events.emit.mock.calls.find((c) => c[0] === "pending:register")?.[1] as Record<
@@ -178,7 +178,7 @@ describe("exit-edge notification (⑧⑨, poll edge wiring)", () => {
 		const pi = createMockPi();
 		attach(pi);
 		setOnTaskExit(handleTaskExit);
-		const spawned = spawnBg("sleep 0.3 && echo done");
+		const spawned = spawnBg("sleep 0.1 && echo done");
 		if (!spawned.ok) throw new Error(spawned.error);
 		const { task } = spawned;
 
@@ -207,7 +207,7 @@ describe("exit-edge notification (⑧⑨, poll edge wiring)", () => {
 		const finalizedEntry = getTask(task.taskId);
 		expect(message.details).toMatchObject({
 			taskId: task.taskId,
-			command: "sleep 0.3 && echo done",
+			command: "sleep 0.1 && echo done",
 			endReason: "natural",
 			exitCode: 0,
 		});
@@ -254,7 +254,8 @@ describe("exit-edge notification (⑧⑨, poll edge wiring)", () => {
 		const pi = createMockPi();
 		attach(pi);
 		setOnTaskExit(handleTaskExit);
-		const spawned = spawnBg("sleep 0.3; exit 3");
+		// 断言只看 reason=failed 与文案 exit code，不依赖命令时长
+		const spawned = spawnBg("sleep 0.1; exit 3");
 		if (!spawned.ok) throw new Error(spawned.error);
 		const { task } = spawned;
 
@@ -401,8 +402,9 @@ describe("D17: pi reference refresh (session replacement takeover)", () => {
 		attach(stale);
 		setOnTaskExit(handleTaskExit);
 
-		const first = spawnBg("sleep 0.3 && echo one");
-		const second = spawnBg("sleep 0.3 && echo two");
+		// 断言只看双任务终态化与异常吞没，不依赖命令时长
+		const first = spawnBg("sleep 0.1 && echo one");
+		const second = spawnBg("sleep 0.1 && echo two");
 		if (!first.ok || !second.ok) throw new Error("spawn failed");
 		// 边沿回调内部全捕获：轮询到两条任务都完成终态化（每迭代 tick 后查）
 		await pollUntilTicked(