@zhushanwen/pi-base-tool-enhance 0.4.1 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-base-tool-enhance",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Base tool enhancement - override builtin bash tool: foreground delegates to pi official factory, incremental background mode (design: docs/design/base-tool-enhance.md)",
   "type": "module",
   "main": "src/index.ts",
@@ -28,7 +28,7 @@
     "skills/"
   ],
   "dependencies": {
-    "@xyz-agent/extension-protocol": "0.8.1",
+    "@xyz-agent/extension-protocol": "0.8.2",
     "@zhushanwen/pi-extension-logger": "0.4.1",
     "@zhushanwen/pi-file-lock": "0.2.1",
     "@zhushanwen/pi-llm-shared": "0.5.1"

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

@@ -1,11 +1,12 @@
 // src/__tests__/background-lifecycle.test.ts —— background 核心生命周期集成：
 // 真实 spawn 边沿收尾 / 轮询器自动收尾 / killing intent 双侧 / timeout / 并发上限 /
 // 收殓 / D15 abort / bash_output / bash_kill（黑盒：经工具 execute 断言使用者可见行为）
-import { existsSync, mkdtempSync, unlinkSync } from "node:fs";
+import { existsSync, mkdtempSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { afterAll, afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 vi.setConfig({ testTimeout: 20000 });
 
@@ -31,16 +32,15 @@ vi.mock("../kill-tree.ts", async (importOriginal) => {
 
 import { createBashKillToolDefinition } from "../bash-kill-tool.ts";
 import { createBashOutputToolDefinition } from "../bash-output-tool.ts";
+import { handleTaskExit, refreshPiReference, resetNotifyForTest } from "../background/notify.ts";
 import { pollTickForTest, setOnTaskExit, stopPoller } from "../background/poller.ts";
 import { getRegistryPath, readRegistry, taskToRegistryEntry, writeRegistryEntry } from "../background/registry.ts";
 import type { RegistryEntry } from "../background/types.ts";
 import { DEFAULT_MAX_CONCURRENT_BACKGROUND, spawnBackgroundTask } from "../background/spawn-background.ts";
-import { clearTaskStoreForTest, getActiveTasks, getTask } from "../background/task-store.ts";
+import { clearTaskStoreForTest, getActiveTasks, getTask, markKillingIntent } from "../background/task-store.ts";
 import { reapBackgroundTasksNow, resetProcessExitGuardForTest } from "../background/process-exit-guard.ts";
 import { isPidAlive } from "../kill-tree.ts";
 
-vi.setConfig({ testTimeout: 20000 });
-
 const DATA_DIR = mkdtempSync(join(tmpdir(), "bte-data-"));
 dataDirRef.dir = DATA_DIR;
 
@@ -68,6 +68,40 @@ function sleep(ms: number): Promise<void> {
 	return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+/**
+ * 真实子进程链（spawn+exec+sleep+exit）满载下延迟不可预估，deadline 放宽到 10s；
+ * timeout 路径 / 真实 poller 定时器路径单独放宽到 8s（任务语义内最慢的等待对象）。
+ */
+const POLL_DEADLINE_MS = 10_000;
+const POLL_DEADLINE_SLOW_MS = 8_000;
+
+/**
+ * 轮询直到期望状态出现或超时：每次迭代先 pollTickForTest()（手动 tick 推进状态机）
+ * 再检查——固定 sleep 后单次 tick 单次断言是满载 flake 源，等状态而非猜时刻。
+ */
+async function pollUntilTicked(check: () => boolean, deadlineMs: number, what: string): Promise<void> {
+	const deadline = Date.now() + deadlineMs;
+	for (;;) {
+		pollTickForTest();
+		if (check()) return;
+		if (Date.now() > deadline) {
+			throw new Error(`timed out after ${deadlineMs}ms waiting for ${what}`);
+		}
+		await sleep(25);
+	}
+}
+
+/** 同 pollUntilTicked 但不手动 tick：语义含「真实定时器/事件自行推进」的用例专用。 */
+async function pollUntil(check: () => boolean, deadlineMs: number, what: string): Promise<void> {
+	const deadline = Date.now() + deadlineMs;
+	while (!check()) {
+		if (Date.now() > deadline) {
+			throw new Error(`timed out after ${deadlineMs}ms waiting for ${what}`);
+		}
+		await sleep(25);
+	}
+}
+
 function spawnBg(command: string, extra: { timeoutSec?: number; maxConcurrent?: number } = {}) {
 	return spawnBackgroundTask({
 		command,
@@ -113,6 +147,15 @@ afterEach(() => {
 	stopPoller();
 	setOnTaskExit(undefined);
 	resetProcessExitGuardForTest();
+	// pi 引用（currentPi）统一在 afterEach 复位——用例体内不清：断言先失败时泄漏的
+	// currentPi 会被同文件后续用例的 emitPendingRegister 消费（发往死引用）
+	resetNotifyForTest();
+});
+
+// 测试红线：临时目录自建自删（模块级 DATA_DIR 全文件共用，最后统一清）
+// maxRetries 防 teardown 递归删除与在途异步写竞争的 ENOTEMPTY 满载 flake
+afterAll(() => {
+	rmSync(DATA_DIR, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
 });
 
 describe("real spawn lifecycle (poll edge finalization)", () => {
@@ -126,8 +169,8 @@ describe("real spawn lifecycle (poll edge finalization)", () => {
 		expect(readRegistry(REGISTRY_PATH).get(task.taskId)?.state).toBe("running");
 		expect(readRegistry(REGISTRY_PATH).get(task.taskId)?.ownerPiPid).toBe(process.pid);
 
-		await sleep(700); // 等命令退出 + libuv reap
-		pollTickForTest();
+		// 轮询等命令退出 + libuv reap（tick 收尾；满载下延迟不可预估）
+		await pollUntilTicked(() => getTask(task.taskId)?.state === "exited", POLL_DEADLINE_MS, "task finalization");
 
 		const finalized = getTask(task.taskId);
 		expect(finalized?.state).toBe("exited");
@@ -148,8 +191,9 @@ describe("real spawn lifecycle (poll edge finalization)", () => {
 		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 sleep(2800);
+		// 不手动 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);
@@ -159,8 +203,7 @@ describe("real spawn lifecycle (poll edge finalization)", () => {
 		const spawned = spawnBg("sleep 0.2; exit 3");
 		if (!spawned.ok) throw new Error(spawned.error);
 		const { task } = spawned;
-		await sleep(600);
-		pollTickForTest();
+		await pollUntilTicked(() => getTask(task.taskId)?.exitCode === 3, POLL_DEADLINE_MS, "exitCode to surface");
 		expect(getTask(task.taskId)?.exitCode).toBe(3);
 		const registryEntry = readRegistry(REGISTRY_PATH).get(task.taskId);
 		expect(registryEntry?.exitCode).toBe(3);
@@ -171,8 +214,7 @@ describe("real spawn lifecycle (poll edge finalization)", () => {
 		setOnTaskExit((task) => seen.push(`${task.taskId}:${task.state}:${task.reason}`));
 		const spawned = spawnBg("true");
 		if (!spawned.ok) throw new Error(spawned.error);
-		await sleep(500);
-		pollTickForTest();
+		await pollUntilTicked(() => seen.length === 1, POLL_DEADLINE_MS, "onTaskExit callback to fire");
 		expect(seen).toHaveLength(1);
 		expect(seen[0]).toBe(`${spawned.task.taskId}:exited:natural`);
 	});
@@ -264,8 +306,7 @@ describe("bash_output tool", () => {
 		const spawned = spawnBg("sleep 0.2 && echo gone");
 		if (!spawned.ok) throw new Error(spawned.error);
 		const { task } = spawned;
-		await sleep(500);
-		pollTickForTest();
+		await pollUntilTicked(() => getTask(task.taskId)?.state === "exited", POLL_DEADLINE_MS, "task finalization");
 		unlinkSync(task.outputFile);
 		const detail = JSON.parse(await outputTool({ task_id: task.taskId })) as {
 			output: string;
@@ -280,8 +321,8 @@ describe("bash_output tool", () => {
 		const spawned = spawnBg("for i in $(seq 1 2100); do echo line$i; done");
 		if (!spawned.ok) throw new Error(spawned.error);
 		const { task } = spawned;
-		await sleep(900);
-		pollTickForTest();
+		// 轮询等 2100 行输出跑完退出收尾（满载下 shell 循环耗时不可预估）
+		await pollUntilTicked(() => getTask(task.taskId)?.state === "exited", POLL_DEADLINE_MS, "output loop to finish");
 		const detail = JSON.parse(await outputTool({ task_id: task.taskId })) as {
 			output: string;
 			truncated: boolean;
@@ -315,8 +356,8 @@ describe("bash_kill tool (killing intent, single-point finalization)", () => {
 		if (!spawned.ok) throw new Error(spawned.error);
 		const { task } = spawned;
 		await killTool(task.taskId);
-		await sleep(500); // SIGKILL 生效
-		pollTickForTest();
+		// 轮询到 kill 边沿收尾（SIGKILL 生效 + tick 终态化）
+		await pollUntilTicked(() => getTask(task.taskId)?.reason === "killed", POLL_DEADLINE_MS, "killed finalization");
 		const finalized = getTask(task.taskId);
 		expect(finalized?.state).toBe("exited");
 		expect(finalized?.reason).toBe("killed");
@@ -338,8 +379,7 @@ describe("bash_kill tool (killing intent, single-point finalization)", () => {
 		const spawned = spawnBg("sleep 0.2");
 		if (!spawned.ok) throw new Error(spawned.error);
 		const { task } = spawned;
-		await sleep(500);
-		pollTickForTest();
+		await pollUntilTicked(() => getTask(task.taskId)?.state === "exited", POLL_DEADLINE_MS, "task finalization");
 		const result = JSON.parse(await killTool(task.taskId)) as { killed: boolean; reason: string };
 		expect(result.killed).toBe(false);
 		expect(result.reason).toBe("already exited (code 0)");
@@ -387,7 +427,8 @@ describe("bash_kill tool (killing intent, single-point finalization)", () => {
 		const spawned = spawnBg("sleep 0.2");
 		if (!spawned.ok) throw new Error(spawned.error);
 		const { task } = spawned;
-		await sleep(500); // 进程已死但不 tick——单例表仍 running
+		// 轮询进程死透（不 tick——单例表仍 running 是本用例前提）
+		await pollUntil(() => !isPidAlive(task.pid), 5000, "process to die without poll edge");
 		expect(getTask(task.taskId)?.state).toBe("running");
 
 		const result = JSON.parse(await killTool(task.taskId)) as { killed: boolean; reason: string };
@@ -476,14 +517,18 @@ describe("explicit background timeout (D6)", () => {
 		}
 
 		// SIGKILL 已真实发出：轮询边沿收尾 → exited(reason:"timeout")，终态由边沿写
-		await sleep(500);
-		pollTickForTest();
+		//（timeout 路径满载下 SIGKILL 生效延迟不可预估，deadline 放宽到 8s）
+		await pollUntilTicked(
+			() => getTask(taskId)?.state === "exited" && getTask(taskId)?.reason === "timeout",
+			POLL_DEADLINE_SLOW_MS,
+			"timeout finalization",
+		);
 		const finalized = getTask(taskId);
 		expect(finalized?.state).toBe("exited");
 		expect(finalized?.reason).toBe("timeout");
 	});
 
-	it("P0-4: pid reuse suspected at the deadline → skip kill, intent still marked", () => {
+	it("P0-4/D6-en R2-S1: pid reuse suspected at the deadline → skip kill AND skip intent mark", () => {
 		vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout"] });
 		try {
 			const spawned = spawnBg("sleep 30", { timeoutSec: 1 });
@@ -496,16 +541,18 @@ describe("explicit background timeout (D6)", () => {
 			vi.advanceTimersByTime(1000);
 			// 宁不杀勿误杀：到点不对复用嫌疑 pid 发 kill（整进程组 SIGKILL 会误杀无辜进程）
 			expect(killTreeCalls).not.toContain(task.pid);
-			// 仅标 killing intent（reason timeout）——终态归轮询边沿/对账收尾
-			expect(getTask(task.taskId)?.state).toBe("killing");
-			expect(getTask(task.taskId)?.intent?.reason).toBe("timeout");
-			expect(readRegistry(REGISTRY_PATH).get(task.taskId)?.state).toBe("killing");
+			// D6-en/R2-S1 加固：身份校验不过 = 登记原进程已不在（死亡或被复用），intent
+			// 标记一并跳过——无条件改写内存 intent 为 timeout 会冲掉 UI 代杀 / AI bash_kill
+			// 预写的 killed（误报 timed out 唤醒 AI）；终态归轮询边沿按事实收尾
+			expect(getTask(task.taskId)?.state).toBe("running");
+			expect(getTask(task.taskId)?.intent).toBeUndefined();
+			expect(readRegistry(REGISTRY_PATH).get(task.taskId)?.state).toBe("running");
 		} finally {
 			vi.useRealTimers();
 		}
 	});
 
-	it("P0-4: missing pidStartTime degrades to startedAt check (mismatch → skip kill)", () => {
+	it("P0-4/D6-en R2-S1: missing pidStartTime degrades to startedAt check (mismatch → skip kill and intent mark)", () => {
 		vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout"] });
 		try {
 			const spawned = spawnBg("sleep 30", { timeoutSec: 1 });
@@ -518,8 +565,10 @@ describe("explicit background timeout (D6)", () => {
 
 			vi.advanceTimersByTime(1000);
 			expect(killTreeCalls).not.toContain(task.pid);
-			expect(getTask(task.taskId)?.state).toBe("killing");
-			expect(getTask(task.taskId)?.intent?.reason).toBe("timeout");
+			// D6-en/R2-S1 加固：身份校验不过同样跳过 intent 标记（防冲掉 killed 预写）
+			expect(getTask(task.taskId)?.state).toBe("running");
+			expect(getTask(task.taskId)?.intent).toBeUndefined();
+			expect(readRegistry(REGISTRY_PATH).get(task.taskId)?.state).toBe("running");
 		} finally {
 			vi.useRealTimers();
 		}
@@ -550,18 +599,135 @@ describe("explicit background timeout (D6)", () => {
 		if (!spawned.ok) throw new Error(spawned.error);
 		const { task } = spawned;
 
-		await sleep(600); // 命令已退出（未到 1s deadline）
-		pollTickForTest();
+		// 轮询命令退出收尾（未到 1s 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）
-		await sleep(900);
+		// 越过 deadline 的时间窗内不得再补杀（终态化必须已清 timer）：轮询真实时钟
+		// 越过 deadline+余量后断言——这里等待的是时钟流逝本身，非子进程事件
+		await pollUntil(
+			() => Date.now() >= task.startedAt + 1_000 + 500,
+			POLL_DEADLINE_SLOW_MS,
+			"real clock to pass the deadline window",
+		);
 		expect(killTreeCalls.length).toBe(before);
 		expect(getTask(task.taskId)?.state).toBe("exited");
 	});
 });
 
+describe("D6-en: poller finalization reads back registry killing (cross-process UI kill)", () => {
+	it("memory intent missing + registry killing → reason killed; AI not woken (no sendMessage)", async () => {
+		const pi = { events: { emit: vi.fn() }, sendMessage: vi.fn(), appendEntry: vi.fn() };
+		refreshPiReference(pi as unknown as ExtensionAPI);
+		setOnTaskExit(handleTaskExit);
+		const spawned = spawnBg("sleep 30");
+		if (!spawned.ok) throw new Error(spawned.error);
+		const { task } = spawned;
+		// runtime UI 代杀形态：只写 registry 侧 killing（跨进程，pi 内存表不可见）+
+		// 杀进程树，不经本进程 markKillingIntent
+		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);
+		pollTickForTest();
+
+		const finalized = getTask(task.taskId);
+		expect(finalized?.state).toBe("exited");
+		expect(finalized?.reason).toBe("killed"); // 读回命中（无 intent 时旧实现得 natural）
+		expect(readRegistry(REGISTRY_PATH).get(task.taskId)?.reason).toBe("killed");
+		// 下游效果（P7 主路径口径）：killed → 只 emit unregister(cancelled)，不 sendMessage
+		expect(pi.events.emit).toHaveBeenCalledWith("pending:unregister", {
+			id: task.taskId,
+			reason: "cancelled",
+		});
+		expect(pi.sendMessage).not.toHaveBeenCalled();
+	});
+
+	it("memory intent present wins — registry NOT read back (killed kept while registry stays running)", async () => {
+		const spawned = spawnBg("sleep 30");
+		if (!spawned.ok) throw new Error(spawned.error);
+		const { task } = spawned;
+		// 内存预写 killed intent（AI bash_kill 形态），registry 刻意停留 running
+		//（模拟 intent 落盘失败）——若实现误读回，会按 running 判 natural
+		expect(markKillingIntent(task.taskId, "killed")).toBeDefined();
+		process.kill(task.pid, "SIGKILL");
+		await sleep(500);
+		expect(isPidAlive(task.pid)).toBe(false);
+		expect(readRegistry(REGISTRY_PATH).get(task.taskId)?.state).toBe("running"); // 前置成立
+		pollTickForTest();
+		expect(getTask(task.taskId)?.reason).toBe("killed"); // intent 优先，非 natural
+	});
+
+	it("registry read failure (corrupt file) degrades to no-intent natural; finalization not blocked", async () => {
+		const spawned = spawnBg("sleep 30");
+		if (!spawned.ok) throw new Error(spawned.error);
+		const { task } = spawned;
+		writeFileSync(REGISTRY_PATH, "{corrupted", "utf8"); // 读回路径解析失败
+		process.kill(task.pid, "SIGKILL");
+		await sleep(500);
+		pollTickForTest();
+		const finalized = getTask(task.taskId);
+		expect(finalized?.state).toBe("exited"); // 终态化未被阻塞
+		expect(finalized?.reason).toBe("natural"); // 读失败按无 intent 处理
+	});
+});
+
+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 });
+		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 之前）
+		// 加固生效：不补杀、不改写内存（无 intent）、不冲掉 registry 侧 killing 预写
+		expect(killTreeCalls).not.toContain(task.pid);
+		expect(getTask(task.taskId)?.state).toBe("running");
+		expect(getTask(task.taskId)?.intent).toBeUndefined();
+		expect(readRegistry(REGISTRY_PATH).get(task.taskId)?.state).toBe("killing");
+		pollTickForTest();
+		expect(getTask(task.taskId)?.state).toBe("exited");
+		expect(getTask(task.taskId)?.reason).toBe("killed"); // D6-en 读回（非 timeout）
+	});
+
+	it("AI bash_kill × timeout overlap: killed intent survives (no 'timed out' misreport)", async () => {
+		const spawned = spawnBg("sleep 30", { timeoutSec: 1 });
+		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
+		expect(getTask(task.taskId)?.intent?.reason).toBe("killed"); // 未被覆盖为 timeout
+		expect(killTreeCalls.filter((pid) => pid === task.pid)).toHaveLength(1); // 无第二次 kill
+		pollTickForTest();
+		expect(getTask(task.taskId)?.state).toBe("exited");
+		expect(getTask(task.taskId)?.reason).toBe("killed"); // 加固后保持 killed（无通知路径）
+	});
+
+	it("natural death before the deadline: no timeout mark; poll edge finalizes natural (accepted shift)", async () => {
+		const before = killTreeCalls.length;
+		const spawned = spawnBg("sleep 0.3", { timeoutSec: 1 });
+		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 之前）
+		expect(killTreeCalls.length).toBe(before); // 死任务不补杀
+		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();
+		expect(getTask(task.taskId)?.reason).toBe("natural"); // 语义微移：natural 非 timeout
+	});
+});
+
 describe("process-exit reap (D12)", () => {
 	it("reaps all active tasks with reason process-exit, kills pids, writes registry terminal", async () => {
 		const first = spawnBg("sleep 30");
@@ -571,7 +737,8 @@ describe("process-exit reap (D12)", () => {
 		expect(pids.every((pid) => isPidAlive(pid))).toBe(true);
 
 		reapBackgroundTasksNow();
-		await sleep(300); // SIGKILL 发出到进程表移除是异步的
+		// SIGKILL 发出到进程表移除是异步的：轮询等 pid 判死（满载下延迟不可预估）
+		await pollUntil(() => pids.every((pid) => !isPidAlive(pid)), 5000, "reaped pids to die");
 
 		for (const pid of pids) {
 			expect(isPidAlive(pid)).toBe(false);
@@ -596,6 +763,8 @@ describe("D15: abort signal does not propagate to background tasks", () => {
 		controller.abort();
 		expect(controller.signal.aborted).toBe(true);
 
+		// 非断言性观察窗口（留事件传播时间）：断言的是「任务不受 abort 影响」的
+		// 负向不变量，期望状态恒真，轮询语义不适用
 		await sleep(300);
 		// 任务不受中断影响：进程活、状态 running
 		expect(isPidAlive(task.pid)).toBe(true);

package/src/__tests__/bash-tool.test.ts

@@ -64,7 +64,7 @@ function useConfig(config: Record<string, unknown>): void {
 
 afterEach(() => {
 	for (const dir of configTempDirs.splice(0)) {
-		rmSync(dir, { recursive: true, force: true });
+		rmSync(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
 	}
 	agentDirRef.dir = "/tmp/bte-fake-agent-dir";
 	clearConfigCache();

package/src/__tests__/config.test.ts

@@ -36,7 +36,7 @@ beforeEach(() => {
 });
 
 afterEach(() => {
-	rmSync(tempDir, { recursive: true, force: true });
+	rmSync(tempDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
 });
 
 function writeConfigFile(content: string): void {

package/src/__tests__/index.test.ts

@@ -127,7 +127,7 @@ describe("session_start chain: reconcile (M3, reap sunk into runtime by u-bte-re
 				reason: "cancelled",
 			});
 		} finally {
-			rmSync(dataDir, { recursive: true, force: true });
+			rmSync(dataDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
 			dataDirRef.dir = "/tmp/bte-fake-agent-dir";
 			resetNotifyForTest();
 		}

package/src/__tests__/kill-tree.test.ts

@@ -1,7 +1,7 @@
 // src/__tests__/kill-tree.test.ts —— 进程树 kill 真实进程验证（POSIX 进程组语义）
 // + pid 身份判据（getProcessStartTimeSec / pidStartMatchesRegistered——原 reaper.test.ts
 // 覆盖平移：收殓下沉 runtime 后 helper 移入本文件，kill 侧自防御仍消费）
-import { spawn } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 
 import { describe, expect, it, vi } from "vitest";
 
@@ -18,6 +18,30 @@ function sleep(ms: number): Promise<void> {
 	return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+/**
+ * 轮询直到期望状态出现或超时：真实进程事件（退出 → libuv reap → pid 释放）在满载
+ * 下延迟不可预估，固定 sleep 后单次断言是满载 flake 源——等状态而非猜时刻。
+ */
+async function pollUntil(check: () => boolean, deadlineMs: number, what: string): Promise<void> {
+	const deadline = Date.now() + deadlineMs;
+	while (!check()) {
+		if (Date.now() > deadline) {
+			throw new Error(`timed out after ${deadlineMs}ms waiting for ${what}`);
+		}
+		await sleep(25);
+	}
+}
+
+/** pgrep -P 组内枚举：列组长直接子 pid（仅本进程组内，非全机扫描）。 */
+function listChildPids(pid: number): number[] {
+	const result = spawnSync("/usr/bin/pgrep", ["-P", String(pid)], { encoding: "utf8" });
+	// exit 1 = 无匹配（空表正常态）；解析失败按空表处理，由轮询重试兜住 spawn 竞态
+	return (result.stdout ?? "")
+		.split("\n")
+		.map((line) => Number.parseInt(line.trim(), 10))
+		.filter((n) => Number.isInteger(n) && n > 0);
+}
+
 /** 真实 detached spawn（与本包后台任务同款形态：自成进程组）。 */
 function spawnDetached(command: string) {
 	const child = spawn("/bin/sh", ["-c", command], {
@@ -38,8 +62,8 @@ describe("isPidAlive", () => {
 		const child = spawnDetached("true");
 		const pid = child.pid;
 		if (pid === undefined) throw new Error("no pid");
-		// 等退出 + libuv reap（SIGCHLD → waitpid 后 pid 释放）
-		await sleep(300);
+		// 轮询等退出 + libuv reap（SIGCHLD → waitpid 后 pid 释放）
+		await pollUntil(() => !isPidAlive(pid), 5000, "pid to be freed after reap");
 		expect(isPidAlive(pid)).toBe(false);
 	});
 
@@ -55,29 +79,41 @@ describe("killProcessTree (process group semantics)", () => {
 		const child = spawnDetached("sleep 30 & sleep 30 & wait");
 		const pid = child.pid;
 		if (pid === undefined) throw new Error("no pid");
-		await sleep(300); // 让子 sleep 起来
+		// 轮询等两个孙子 sleep 真正 fork 出来，并在 kill 之前用组内枚举（pgrep -P）
+		// 记录孙子 pid 快照——kill 后只对这些记录过的 pid 断言，禁止全机 pgrep -f
+		// 扫描（满载并行时其他包测试会真实 spawn 同名命令，跨包互踩）
+		let grandchildPids: number[] = [];
+		await pollUntil(
+			() => {
+				grandchildPids = listChildPids(pid);
+				return isPidAlive(pid) && grandchildPids.length >= 2;
+			},
+			5000,
+			"grandchildren to spawn inside the group",
+		);
 		expect(isPidAlive(pid)).toBe(true);
 
 		killProcessTree(pid);
-		await sleep(300);
-
-		expect(isPidAlive(pid)).toBe(false);
-		// 子进程也不得残留：枚举验证（pgrep -P 组长；组长死后 reparent，改为全 pgrep 命令串兜底）
-		const leftover = spawn("/usr/bin/pgrep", ["-f", "sleep 30"]);
-		const stdout: string[] = [];
-		leftover.stdout?.on("data", (d: Buffer) => stdout.push(d.toString()));
-		const status = await new Promise<number | null>((resolve) => leftover.on("close", resolve));
-		// pgrep 自身命令行含 "sleep 30" 会自匹配吗：pgrep -f 匹配其他进程，不匹配自身（pgrep 默认排除自己）
-		const others = stdout.join("").split("\n").filter((line) => line.trim() !== "");
-		expect(others).toEqual([]);
-		expect(status).not.toBe(0); // 无匹配 → pgrep exit 1
+		// 轮询组长死（等 libuv reap，deadline 5s）
+		await pollUntil(() => !isPidAlive(pid), 5000, "group leader to die");
+
+		// 记录过的孙子 pid 也不得残留。覆盖面说明：killProcessTree 是进程组 kill
+		// （POSIX kill -- -<pgid>），孙子与组长同组、组长死后 reparent 不换组，
+		// 故「组 kill + 组内 pid 记录」已覆盖「reparent 后孙子也能被杀」的原始意图；
+		// pid 复用概率在 5s 轮询窗口内可忽略
+		await pollUntil(
+			() => grandchildPids.every((gpid) => !isPidAlive(gpid)),
+			5000,
+			"recorded grandchildren to die",
+		);
 	});
 
 	it("killing an already-dead pid is a silent no-op", async () => {
 		const child = spawnDetached("true");
 		const pid = child.pid;
 		if (pid === undefined) throw new Error("no pid");
-		await sleep(300);
+		// 轮询等死透再 kill：断言语义是「对已死 pid 发令为无害 no-op」
+		await pollUntil(() => !isPidAlive(pid), 5000, "pid to die");
 		expect(() => killProcessTree(pid)).not.toThrow();
 	});
 });
@@ -96,7 +132,8 @@ describe("getProcessStartTimeSec (platform probe sanity)", () => {
 		const child = spawnDetached("sleep 0.1");
 		const pid = child.pid;
 		if (pid === undefined) throw new Error("no pid");
-		await sleep(500); // 等退出 + libuv reap
+		// 轮询等退出 + libuv reap（满载下延迟不可预估）
+		await pollUntil(() => getProcessStartTimeSec(pid) === undefined, 5000, "ps record to vanish");
 		expect(getProcessStartTimeSec(pid)).toBeUndefined();
 	});
 });

package/src/__tests__/notify.test.ts

@@ -50,6 +50,27 @@ function sleep(ms: number): Promise<void> {
 	return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+/**
+ * 真实子进程链（spawn+exec+sleep+exit）满载下延迟不可预估，deadline 放宽到 10s。
+ */
+const POLL_DEADLINE_MS = 10_000;
+
+/**
+ * 轮询直到期望状态出现或超时：每次迭代先 pollTickForTest()（手动 tick 推进状态机）
+ * 再检查——固定 sleep 后单次 tick 单次断言是满载 flake 源，等状态而非猜时刻。
+ */
+async function pollUntilTicked(check: () => boolean, what: string): Promise<void> {
+	const deadline = Date.now() + POLL_DEADLINE_MS;
+	for (;;) {
+		pollTickForTest();
+		if (check()) return;
+		if (Date.now() > deadline) {
+			throw new Error(`timed out after ${POLL_DEADLINE_MS}ms waiting for ${what}`);
+		}
+		await sleep(25);
+	}
+}
+
 function spawnBg(command: string) {
 	return spawnBackgroundTask({
 		command,
@@ -154,8 +175,11 @@ describe("exit-edge notification (⑧⑨, poll edge wiring)", () => {
 		if (!spawned.ok) throw new Error(spawned.error);
 		const { task } = spawned;
 
-		await sleep(700);
-		pollTickForTest();
+		// 轮询到 exit 边沿收尾（handleTaskExit 同步完成 unregister emit + sendMessage）
+		await pollUntilTicked(
+			() => pi.events.emit.mock.calls.some((c) => c[0] === "pending:unregister"),
+			"pending:unregister (completed)",
+		);
 
 		expect(pi.events.emit).toHaveBeenCalledWith("pending:unregister", {
 			id: task.taskId,
@@ -184,8 +208,8 @@ describe("exit-edge notification (⑧⑨, poll edge wiring)", () => {
 
 		markKillingIntent(task.taskId, "killed");
 		killProcessTree(task.pid);
-		await sleep(500);
-		pollTickForTest();
+		// 轮询到 kill 边沿收尾（SIGKILL 生效 + tick 终态化）
+		await pollUntilTicked(() => getTask(task.taskId)?.reason === "killed", "reason=killed finalization");
 
 		expect(getTask(task.taskId)?.reason).toBe("killed");
 		expect(pi.events.emit).toHaveBeenCalledWith("pending:unregister", {
@@ -218,8 +242,11 @@ describe("exit-edge notification (⑧⑨, poll edge wiring)", () => {
 		if (!spawned.ok) throw new Error(spawned.error);
 		const { task } = spawned;
 
-		await sleep(700);
-		pollTickForTest();
+		// 轮询到 exit 边沿收尾（reason failed）
+		await pollUntilTicked(
+			() => pi.events.emit.mock.calls.some((c) => c[0] === "pending:unregister"),
+			"pending:unregister (failed)",
+		);
 
 		expect(pi.events.emit).toHaveBeenCalledWith("pending:unregister", {
 			id: task.taskId,
@@ -297,8 +324,14 @@ describe("D17: pi reference refresh (session replacement takeover)", () => {
 		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 不抛，两条任务都完成终态化
+		// 边沿回调内部全捕获：轮询到两条任务都完成终态化（每迭代 tick 后查）
+		await pollUntilTicked(
+			() =>
+				getTask(first.task.taskId)?.state === "exited" &&
+				getTask(second.task.taskId)?.state === "exited",
+			"both tasks to finalize",
+		);
+		// tick 不抛（异常全捕获）
 		expect(() => pollTickForTest()).not.toThrow();
 		expect(getTask(first.task.taskId)?.state).toBe("exited");
 		expect(getTask(second.task.taskId)?.state).toBe("exited");

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

@@ -52,7 +52,7 @@ function registerEntry(id: string) {
 }
 
 afterEach(() => {
-	rmSync(DATA_DIR, { recursive: true, force: true });
+	rmSync(DATA_DIR, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
 	vi.restoreAllMocks();
 });
 

package/src/background/poller.ts

@@ -15,9 +15,9 @@
 
 import { isPidAlive } from "../kill-tree.ts";
 import { readTailSummary } from "./output-tail.ts";
-import { taskToRegistryEntry, writeRegistryEntry } from "./registry.ts";
+import { readRegistry, taskToRegistryEntry, writeRegistryEntry } from "./registry.ts";
 import { finalizeTask, getActiveTasks } from "./task-store.ts";
-import type { BackgroundTask } from "./types.ts";
+import type { BackgroundTask, BackgroundTaskEndReason } from "./types.ts";
 
 /** 轮询间隔（设计文档 §3.5：约 2s）。 */
 export const POLL_INTERVAL_MS = 2000;
@@ -71,13 +71,14 @@ export function pollTickForTest(): void {
 
 /**
  * exit 边沿收尾（单一终态归属）：读 exitCode → 组装 tail 摘要 → reason 判定
- * （intent.killed → "killed"、intent.timeout → "timeout"、无 intent → "natural"；
- * "process-exit" 由收殓路径直接调 finalizeTask，不经这里）→ 单例表 + registry
- * 两侧写终态 → 触发 onTaskExit 回调（M3 接入点）。
+ * （内存 intent 优先：intent.killed → "killed"、intent.timeout → "timeout"；intent
+ * 缺省 → 读回 registry：state==="killing" → "killed"（D6-en，跨进程 UI 代杀预写），
+ * 否则/读失败 → "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 reason = task.intent !== undefined ? task.intent.reason : readBackReasonFromRegistry(task);
 	const endedAt = Date.now();
 	const tailSummary = readTailSummary(task.outputFile);
 	const finalized = finalizeTask(task.taskId, { exitCode, reason, endedAt, tailSummary });
@@ -85,3 +86,19 @@ function finalizeExitedTask(task: BackgroundTask): void {
 	writeRegistryEntry(finalized.registryPath, taskToRegistryEntry(finalized));
 	onTaskExitCallback?.(finalized);
 }
+
+/**
+ * D6-en intent 读回：内存 intent 缺省时读回本条目的 registry 条目——
+ * state==="killing" ↔ reason=killed。跨进程 UI 代杀（runtime kill handler）只写
+ * registry 侧 killing（对 pi 内存表不可见），且 killing 条目落盘剥离 intent
+ * （taskToRegistryEntry），state 字段是唯一可读信号；判 killed 后 handleTaskExit
+ * 不 sendMessage → 主路径 AI 零感知（background-task-sidebar-view 设计 D6-en）。
+ * 读失败/条目缺失/状态非 killing → 按无 intent（"natural"）处理，不阻塞终态化
+ * （readRegistry 对读失败/损坏一律返回空表，读侧无锁依赖 tmp+rename 原子写）。
+ * 内存 intent 存在时不进入本函数（本进程 bash_kill/timeout 预写是内存权威，
+ * 不读回——见 task-store.ts 头部不变量登记）。
+ */
+function readBackReasonFromRegistry(task: BackgroundTask): BackgroundTaskEndReason {
+	const entry = readRegistry(task.registryPath).get(task.taskId);
+	return entry?.state === "killing" ? "killed" : "natural";
+}

package/src/background/spawn-background.ts

@@ -222,9 +222,15 @@ export function spawnBackgroundTask(opts: SpawnBackgroundOptions): SpawnBackgrou
 }
 
 /**
- * 后台显式 timeout（D6：任务寿命可由使用者显式约束）。到点：pid 身份校验通过则
+ * 后台显式 timeout（D6：任务寿命可由使用者显式约束）。到点：pid 身份校验通过 →
  * kill-tree + 两侧标 killing intent（reason 候选 timeout）——实际终态由轮询器边沿
- * 收尾写（单一终态归属），此处不写终态。
+ * 收尾写（单一终态归属），此处不写终态。身份校验不过（登记原进程已不在：已死或
+ * pid 复用嫌疑）→ 跳过 kill **且跳过 intent 标记**（D6-en/R2-S1 加固）：无条件
+ * markKillingIntent("timeout") 会把 UI 代杀 / AI bash_kill 刚预写的 killed 改写成
+ * timeout → reason=timeout → sendMessage 误报「timed out」唤醒 AI；跳过后由轮询器
+ * 边沿按事实收尾（自然死亡 → natural；registry 预写 killing → 经 D6-en 读回判
+ * killed）。接受语义微移：到期前 ~2s 内自然死亡的任务改标 natural（仅影响 AI
+ * 通知文案）。
  */
 function armBackgroundTimeout(task: BackgroundTask, timeoutSec: number): void {
 	const timer = setTimeout(() => {
@@ -240,9 +246,14 @@ function armBackgroundTimeout(task: BackgroundTask, timeoutSec: number): void {
 					startedAt: task.startedAt,
 				},
 			});
-		} else {
-			killProcessTree(task.pid);
+			// D6-en/R2-S1 加固：登记原进程已不在时同样跳过 intent 标记——内存 intent
+			// 是本进程权威（task-store.ts 头部不变量），被无条件改写为 timeout 即丢失
+			// killed 语义（D6-en 读回与 AI bash_kill 预写双双失效）。此处提前 return
+			// 时轮询器必在跑（本任务仍是活跃条目，惰性自停条件是活跃数为 0），边沿
+			// 收尾不受影响。
+			return;
 		}
+		killProcessTree(task.pid);
 		const marked = markKillingIntent(task.taskId, "timeout");
 		if (marked === undefined) return;
 		writeRegistryEntry(marked.registryPath, taskToRegistryEntry(marked));

package/src/background/task-store.ts

@@ -12,6 +12,20 @@
  *
  * 终态条目 LRU 上限 MAX_TERMINAL_ENTRIES（与 registry 对称），淘汰后 bash_output
  * 回落 registry 查询。
+ *
+ * 【不变量登记（D6-en，注释级）】extension 对某条目的**每次 registry 写都先经该
+ * 条目的内存状态更新**——registry 侧 killing 状态因此恒为内存态的投影，runtime
+ * 跨进程预写的 killing 不会被 stale 内存态冲回，D6-en intent 读回（poller.ts）的
+ * 正确性依赖此约束。全部 5 个 writeRegistryEntry 调用点逐一成立：
+ *   ① spawn-background.ts spawnBackgroundTask：registerSpawnedTask（新条目首登记）
+ *     先于 registry 写 running；
+ *   ② bash-kill-tool.ts：markKillingIntent(taskId,"killed") 先于 registry 写 killing；
+ *   ③ spawn-background.ts armBackgroundTimeout：markKillingIntent(taskId,"timeout")
+ *     先于 registry 写 killing（pid 已死路径提前 return，不触达写点）；
+ *   ④ poller.ts finalizeExitedTask：finalizeTask（内存终态化）先于 registry 写 exited；
+ *   ⑤ process-exit-guard.ts reapBackgroundTasksNow：finalizeTask 先于 registry 写
+ *     exited(process-exit)（设计枚举 4 点时未列本点，实际同序成立，一并登记）。
+ * 未来新增写路径（如 maintenance 类）必须保持该顺序，违反即 intent 可丢失。
  */
 
 import {
@@ -61,7 +75,8 @@ export function oldestActiveTask(): BackgroundTask | undefined {
 
 /**
  * 标 killing intent（瞬态 running→killing）。bash_kill 与后台 timeout 定时器共用；
- * 调用方负责同步写 registry 侧（两侧一致是查询面可见性前提）。
+ * 调用方负责同步写 registry 侧（两侧一致是查询面可见性前提；先内存后 registry
+ * 的顺序约束见文件头部不变量登记）。
  */
 export function markKillingIntent(
 	taskId: string,

package/src/bash-output-tool.ts

@@ -32,6 +32,8 @@ const JSON_INDENT = 2;
 const BASH_OUTPUT_DESCRIPTION = [
 	"Fetch output and status of a background bash task started with bash {background:true}.",
 	"Provide task_id to get task detail: state (running|killing|exited|orphaned), exitCode, reason, duration and tail output (last 2000 lines / 50KB).",
+	'reason "killed" means the task was terminated by the user from the UI — do not restart the command unless explicitly asked.',
+	'reason "orphaned" means the owner process died before the task finished — the task is no longer supervised.',
 	"Omit task_id to list known background tasks (process-wide; may include tasks started under earlier sessions).",
 ].join("\n");