@zhushanwen/pi-base-tool-enhance 0.2.0

package/src/__tests__/reaper.test.ts

@@ -0,0 +1,373 @@
+// src/__tests__/reaper.test.ts —— M5 reaper 孤儿收殓：三分支判定（属主活跳过 /
+// 属主死+任务活补杀 / 属主死+任务死终态收尾）+ pid 复用防御（start-time 匹配）+
+// 保守跳过路径 + file-lock 并发串行化 + 损坏目录容忍 + 多目录扫描 + 幂等。
+// 全程真进程（detached spawn——与生产 spawn 路径同构：pgid=pid，kill-tree 杀
+// 进程组不会波及测试进程组），无 mock getAgentDir（reaper 直收 dataDir 参数）。
+// 每用例独立 dataDir：残留 running 条目（afterEach 杀掉的进程）不污染后续用例
+// 的分支计数断言。
+import { spawn, type ChildProcess } from "node:child_process";
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+vi.setConfig({ testTimeout: 20000 });
+
+import { getRegistryPath, readRegistry, writeRegistryEntry } from "../background/registry.ts";
+import type { RegistryEntry } from "../background/types.ts";
+import { isPidAlive } from "../kill-tree.ts";
+import { getProcessStartTimeSec, reapOrphanedTasks, type RegistryEntryStartTime } from "../reaper.ts";
+
+let dataDir: string;
+
+/** 本测试 spawn 的全部进程（owner / task），afterEach 统一杀进程组清理。 */
+const spawnedPids: number[] = [];
+
+/** detached spawn（pgid=pid）：kill-tree 杀 -pid 精确命中，不波及测试进程组。 */
+function spawnDetached(command: string, args: string[]): ChildProcess {
+	const child = spawn(command, args, { detached: true, stdio: "ignore" });
+	child.unref();
+	if (child.pid === undefined) throw new Error(`spawn ${command} failed: no pid`);
+	spawnedPids.push(child.pid);
+	return child;
+}
+
+function sleep(ms: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/** 轮询等进程退出（测试里构造「已死属主 / 已死任务」用）。 */
+async function waitProcessExit(pid: number, timeoutMs = 10000): Promise<void> {
+	const deadline = Date.now() + timeoutMs;
+	while (isPidAlive(pid)) {
+		if (Date.now() > deadline) throw new Error(`process ${pid} did not exit within ${timeoutMs}ms`);
+		await sleep(50);
+	}
+}
+
+type EntryOverrides = Partial<RegistryEntry> & Partial<RegistryEntryStartTime> & {
+	pid: number;
+	ownerPiPid: number;
+	sessionId: string;
+};
+
+/** 手写 registry 条目（走真实 writeRegistryEntry——锁内 RMW + 原子写路径）。 */
+function writeTestEntry(overrides: EntryOverrides): string {
+	const taskId = overrides.taskId ?? `bt-test-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+	const entry: RegistryEntry & RegistryEntryStartTime = {
+		taskId,
+		pid: overrides.pid,
+		command: overrides.command ?? "sleep 60",
+		outputFile: overrides.outputFile ?? join(dataDir, "unused.log"),
+		startedAt: overrides.startedAt ?? Date.now(),
+		state: overrides.state ?? "running",
+		ownerPiPid: overrides.ownerPiPid,
+		sessionId: overrides.sessionId,
+		...(overrides.exitCode !== undefined ? { exitCode: overrides.exitCode } : {}),
+		...(overrides.pidStartTime !== undefined ? { pidStartTime: overrides.pidStartTime } : {}),
+	};
+	const written = writeRegistryEntry(getRegistryPath(dataDir, overrides.sessionId), entry);
+	if (!written.success) throw new Error(written.error);
+	return taskId;
+}
+
+function entryState(sessionId: string, taskId: string): string | undefined {
+	return readRegistry(getRegistryPath(dataDir, sessionId)).get(taskId)?.state;
+}
+
+beforeEach(() => {
+	dataDir = mkdtempSync(join(tmpdir(), "bte-reaper-"));
+});
+
+afterEach(() => {
+	// 杀干净全部探针进程（进程组优先，防 detached 子进程泄漏影响后续用例）
+	for (const pid of spawnedPids) {
+		if (!isPidAlive(pid)) continue;
+		try {
+			process.kill(-pid, "SIGKILL");
+		} catch {
+			try {
+				process.kill(pid, "SIGKILL");
+			} catch {
+				// already dead
+			}
+		}
+	}
+	spawnedPids.length = 0;
+});
+
+describe("getProcessStartTimeSec (platform probe sanity)", () => {
+	it("returns a sane epoch-seconds value for a live process", () => {
+		const sec = getProcessStartTimeSec(process.pid);
+		expect(sec).toBeDefined();
+		const nowSec = Math.floor(Date.now() / 1000);
+		// 本进程必然启动于 [now - 10min, now + 5s]（时钟容差）
+		expect(sec!).toBeGreaterThan(nowSec - 600);
+		expect(sec!).toBeLessThan(nowSec + 5);
+	});
+
+	it("returns undefined for a dead pid", async () => {
+		const short = spawnDetached("sleep", ["0.1"]);
+		await waitProcessExit(short.pid!);
+		expect(getProcessStartTimeSec(short.pid!)).toBeUndefined();
+	});
+});
+
+describe("branch ①: owner alive → skip (S8-B no-false-kill)", () => {
+	it("skips entries whose owner process is alive; task and owner both survive", async () => {
+		const owner = spawnDetached("sleep", ["30"]);
+		const task = spawnDetached("sleep", ["30"]);
+		const taskId = writeTestEntry({ pid: task.pid!, ownerPiPid: owner.pid!, sessionId: "s-owner-alive" });
+
+		const result = await reapOrphanedTasks(dataDir);
+
+		expect(result.ownerAliveSkipped).toBe(1);
+		expect(result.killedOrphans).toBe(0);
+		expect(result.finalizedOrphans).toBe(0);
+		// 防误杀断言：任务进程仍存活（reaper 不介入属主存活的任务）
+		expect(isPidAlive(task.pid!)).toBe(true);
+		expect(isPidAlive(owner.pid!)).toBe(true);
+		expect(entryState("s-owner-alive", taskId)).toBe("running");
+	});
+
+	it("treats ownerPiPid === current process pid as owner-alive (defensive)", async () => {
+		const task = spawnDetached("sleep", ["30"]);
+		const taskId = writeTestEntry({ pid: task.pid!, ownerPiPid: process.pid, sessionId: "s-self-owner" });
+
+		const result = await reapOrphanedTasks(dataDir);
+
+		expect(result.ownerAliveSkipped).toBe(1);
+		expect(isPidAlive(task.pid!)).toBe(true);
+		expect(entryState("s-self-owner", taskId)).toBe("running");
+	});
+
+	it("skips killing-intent entries while owner alive (owner's own poller finalizes)", async () => {
+		const owner = spawnDetached("sleep", ["30"]);
+		const task = spawnDetached("sleep", ["30"]);
+		const taskId = writeTestEntry({
+			pid: task.pid!,
+			ownerPiPid: owner.pid!,
+			sessionId: "s-killing-owner-alive",
+			state: "killing",
+		});
+
+		const result = await reapOrphanedTasks(dataDir);
+
+		expect(result.ownerAliveSkipped).toBe(1);
+		expect(isPidAlive(task.pid!)).toBe(true);
+		expect(entryState("s-killing-owner-alive", taskId)).toBe("killing");
+	});
+});
+
+describe("branch ②: owner dead + task alive → kill-tree + orphaned (S5)", () => {
+	it("kills the orphan task and marks the entry orphaned", async () => {
+		const owner = spawnDetached("sleep", ["0.1"]); // 短命属主
+		const task = spawnDetached("sleep", ["60"]); // 活孤儿任务
+		await waitProcessExit(owner.pid!);
+		// startedAt = 写条目时刻（晚于任务 spawn）→ 降级校验 actual <= floor(startedAt) 满足
+		const taskId = writeTestEntry({ pid: task.pid!, ownerPiPid: owner.pid!, sessionId: "s-orphan-kill" });
+
+		const result = await reapOrphanedTasks(dataDir);
+
+		expect(result.killedOrphans).toBe(1);
+		await sleep(300); // SIGKILL 发出到进程表移除是异步的
+		expect(isPidAlive(task.pid!)).toBe(false);
+		expect(entryState("s-orphan-kill", taskId)).toBe("orphaned");
+	});
+
+	it("reaps killing-intent entries the same way when owner is dead", async () => {
+		const owner = spawnDetached("sleep", ["0.1"]);
+		const task = spawnDetached("sleep", ["60"]);
+		await waitProcessExit(owner.pid!);
+		const taskId = writeTestEntry({
+			pid: task.pid!,
+			ownerPiPid: owner.pid!,
+			sessionId: "s-killing-orphan",
+			state: "killing",
+		});
+
+		const result = await reapOrphanedTasks(dataDir);
+
+		expect(result.killedOrphans).toBe(1);
+		await sleep(300);
+		expect(isPidAlive(task.pid!)).toBe(false);
+		expect(entryState("s-killing-orphan", taskId)).toBe("orphaned");
+	});
+
+	it("precise pidStartTime field match authorizes the kill (exact comparison path)", async () => {
+		const owner = spawnDetached("sleep", ["0.1"]);
+		const task = spawnDetached("sleep", ["60"]);
+		await waitProcessExit(owner.pid!);
+		const startSec = getProcessStartTimeSec(task.pid!);
+		expect(startSec).toBeDefined();
+		const taskId = writeTestEntry({
+			pid: task.pid!,
+			ownerPiPid: owner.pid!,
+			sessionId: "s-exact-match",
+			pidStartTime: startSec,
+		});
+
+		const result = await reapOrphanedTasks(dataDir);
+
+		expect(result.killedOrphans).toBe(1);
+		await sleep(300);
+		expect(isPidAlive(task.pid!)).toBe(false);
+		expect(entryState("s-exact-match", taskId)).toBe("orphaned");
+	});
+});
+
+describe("branch ③: owner dead + task dead → terminal-only (no kill)", () => {
+	it("marks the stale running entry orphaned without any kill", async () => {
+		const owner = spawnDetached("sleep", ["0.1"]);
+		const task = spawnDetached("sleep", ["0.1"]);
+		await waitProcessExit(owner.pid!);
+		await waitProcessExit(task.pid!);
+		const taskId = writeTestEntry({ pid: task.pid!, ownerPiPid: owner.pid!, sessionId: "s-terminal-only" });
+
+		const result = await reapOrphanedTasks(dataDir);
+
+		expect(result.finalizedOrphans).toBe(1);
+		expect(result.killedOrphans).toBe(0); // 不补杀
+		expect(result.conservativelySkipped).toBe(0);
+		expect(entryState("s-terminal-only", taskId)).toBe("orphaned");
+	});
+});
+
+describe("pid-reuse defense (§3.6 start-time verification)", () => {
+	it("does NOT kill when actual start time is newer than the entry (pid reuse suspicion)", async () => {
+		const owner = spawnDetached("sleep", ["0.1"]);
+		const task = spawnDetached("sleep", ["60"]);
+		await waitProcessExit(owner.pid!);
+		// startedAt 拨回很久以前（epoch 早期）：活任务进程 start time 必然晚于它
+		// → 降级判据 actual > floor(startedAt) → 复用嫌疑 → 不杀
+		const taskId = writeTestEntry({
+			pid: task.pid!,
+			ownerPiPid: owner.pid!,
+			sessionId: "s-reuse-degraded",
+			startedAt: 1000,
+		});
+
+		const result = await reapOrphanedTasks(dataDir);
+
+		expect(result.conservativelySkipped).toBe(1);
+		expect(result.killedOrphans).toBe(0);
+		expect(isPidAlive(task.pid!)).toBe(true); // 无辜进程未被误杀
+		expect(entryState("s-reuse-degraded", taskId)).toBe("running"); // 不转终态，交下一周期
+	});
+
+	it("does NOT kill when precise pidStartTime mismatches the live process", async () => {
+		const owner = spawnDetached("sleep", ["0.1"]);
+		const task = spawnDetached("sleep", ["60"]);
+		await waitProcessExit(owner.pid!);
+		const taskId = writeTestEntry({
+			pid: task.pid!,
+			ownerPiPid: owner.pid!,
+			sessionId: "s-reuse-exact",
+			pidStartTime: 1, // 1970 年：与实际进程 start time 必然不等 → 复用嫌疑
+		});
+
+		const result = await reapOrphanedTasks(dataDir);
+
+		expect(result.conservativelySkipped).toBe(1);
+		expect(isPidAlive(task.pid!)).toBe(true);
+		expect(entryState("s-reuse-exact", taskId)).toBe("running");
+	});
+
+	it("conservatively skips the whole disposal when start time is unreadable (platform without ps)", async () => {
+		const owner = spawnDetached("sleep", ["0.1"]);
+		const task = spawnDetached("sleep", ["60"]);
+		await waitProcessExit(owner.pid!);
+		const taskId = writeTestEntry({ pid: task.pid!, ownerPiPid: owner.pid!, sessionId: "s-no-starttime" });
+
+		// 注入「平台取不到 start time」：不补杀也不转终态（宁延迟勿误杀）
+		const result = await reapOrphanedTasks(dataDir, { getProcessStartTimeSec: () => undefined });
+
+		expect(result.conservativelySkipped).toBe(1);
+		expect(result.killedOrphans).toBe(0);
+		expect(result.finalizedOrphans).toBe(0);
+		expect(isPidAlive(task.pid!)).toBe(true);
+		expect(entryState("s-no-starttime", taskId)).toBe("running");
+	});
+});
+
+describe("file-lock serialization (concurrent reapers stay idempotent)", () => {
+	it("two concurrent reaper runs dispose each orphan exactly once", async () => {
+		const owner = spawnDetached("sleep", ["0.1"]);
+		const task = spawnDetached("sleep", ["60"]);
+		await waitProcessExit(owner.pid!);
+		const taskId = writeTestEntry({ pid: task.pid!, ownerPiPid: owner.pid!, sessionId: "s-concurrent" });
+
+		const [first, second] = await Promise.all([
+			reapOrphanedTasks(dataDir),
+			reapOrphanedTasks(dataDir),
+		]);
+
+		// 锁串行化 + 终态跳过：合计恰好处置一次（后进锁者见 orphaned 终态 no-op）
+		expect(first.killedOrphans + second.killedOrphans).toBe(1);
+		expect(first.conservativelySkipped + second.conservativelySkipped).toBe(0);
+		await sleep(300);
+		expect(isPidAlive(task.pid!)).toBe(false);
+		expect(entryState("s-concurrent", taskId)).toBe("orphaned");
+
+		// 幂等：第三遍扫描对已终态条目完全 no-op
+		const third = await reapOrphanedTasks(dataDir);
+		expect(third.killedOrphans).toBe(0);
+		expect(third.finalizedOrphans).toBe(0);
+		expect(third.ownerAliveSkipped).toBe(0);
+		expect(third.conservativelySkipped).toBe(0);
+	});
+});
+
+describe("scan robustness (corrupt dir tolerance + multi-dir)", () => {
+	it("skips a corrupt registry dir without breaking the scan of other dirs", async () => {
+		// 目录 A：损坏 registry.json（非法 JSON——readRegistry rename .corrupt + 空表重建）
+		const corruptDir = join(dataDir, "base-tool-enhance", "s-corrupt");
+		mkdirSync(corruptDir, { recursive: true });
+		writeFileSync(join(corruptDir, "registry.json"), "{ not valid json !!", "utf8");
+		// 目录 B：正常孤儿（分支②）
+		const owner = spawnDetached("sleep", ["0.1"]);
+		const task = spawnDetached("sleep", ["60"]);
+		await waitProcessExit(owner.pid!);
+		const taskId = writeTestEntry({ pid: task.pid!, ownerPiPid: owner.pid!, sessionId: "s-healthy-next-door" });
+
+		const result = await reapOrphanedTasks(dataDir);
+
+		expect(result.scannedDirs).toBeGreaterThanOrEqual(2);
+		expect(result.killedOrphans).toBe(1); // B 目录孤儿照常处置，A 目录损坏不中断
+		expect(entryState("s-healthy-next-door", taskId)).toBe("orphaned");
+	});
+
+	it("scans multiple session dirs and applies per-entry branches independently", async () => {
+		// 目录 A：属主活条目（跳过）；目录 B：孤儿（补杀）；目录 C：终态遗留（收尾）
+		const aliveOwner = spawnDetached("sleep", ["30"]);
+		const aliveTask = spawnDetached("sleep", ["30"]);
+		writeTestEntry({ pid: aliveTask.pid!, ownerPiPid: aliveOwner.pid!, sessionId: "s-multi-a" });
+
+		const deadOwner = spawnDetached("sleep", ["0.1"]);
+		const orphanTask = spawnDetached("sleep", ["60"]);
+		await waitProcessExit(deadOwner.pid!);
+		const orphanId = writeTestEntry({ pid: orphanTask.pid!, ownerPiPid: deadOwner.pid!, sessionId: "s-multi-b" });
+
+		const finOwner = spawnDetached("sleep", ["0.1"]);
+		const finTask = spawnDetached("sleep", ["0.1"]);
+		await waitProcessExit(finOwner.pid!);
+		await waitProcessExit(finTask.pid!);
+		const finId = writeTestEntry({ pid: finTask.pid!, ownerPiPid: finOwner.pid!, sessionId: "s-multi-c" });
+
+		const result = await reapOrphanedTasks(dataDir);
+
+		expect(result.ownerAliveSkipped).toBe(1);
+		expect(result.killedOrphans).toBe(1);
+		expect(result.finalizedOrphans).toBe(1);
+		expect(isPidAlive(aliveTask.pid!)).toBe(true); // 属主活的任务毫发无损
+		expect(entryState("s-multi-b", orphanId)).toBe("orphaned");
+		expect(entryState("s-multi-c", finId)).toBe("orphaned");
+	});
+
+	it("handles a missing base dir gracefully (no background tasks ever created)", async () => {
+		const result = await reapOrphanedTasks(join(dataDir, "never-exists"));
+		expect(result.scannedDirs).toBe(0);
+		expect(result.killedOrphans).toBe(0);
+	});
+});

package/src/__tests__/registry.test.ts

@@ -0,0 +1,149 @@
+// src/__tests__/registry.test.ts —— registry 持久化白盒：原子写 / 损坏防御 / LRU / 条目剥离
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { afterEach, describe, expect, it } from "vitest";
+
+import {
+	getRegistryPath,
+	MAX_TERMINAL_REGISTRY_ENTRIES,
+	readRegistry,
+	taskToRegistryEntry,
+	writeRegistryEntry,
+} from "../background/registry.ts";
+import type { BackgroundTask } from "../background/types.ts";
+
+let tmpRoot = "";
+
+function freshRegistryPath(): string {
+	tmpRoot = mkdtempSync(join(tmpdir(), "bte-registry-"));
+	return getRegistryPath(tmpRoot, "session-test");
+}
+
+function makeEntry(overrides: Partial<BackgroundTask> = {}) {
+	const task: BackgroundTask = {
+		taskId: "bt-1000-abcd",
+		pid: 111,
+		command: "echo hi",
+		outputFile: join(tmpRoot || tmpdir(), "bt-1000-abcd.log"),
+		registryPath: "/tmp/unused-registry.json",
+		startedAt: 1000,
+		state: "running",
+		ownerPiPid: 222,
+		sessionId: "session-test",
+		// 运行时字段：taskToRegistryEntry 必须剥离（intent/timeoutTimer/child/registryPath）
+		intent: { reason: "killed", at: 1234 },
+		child: undefined,
+		...overrides,
+	};
+	return task;
+}
+
+afterEach(() => {
+	tmpRoot = "";
+});
+
+describe("writeRegistryEntry / readRegistry roundtrip", () => {
+	it("creates the registry file with a valid entry and no tmp residue", () => {
+		const path = freshRegistryPath();
+		const result = writeRegistryEntry(path, taskToRegistryEntry(makeEntry()));
+		expect(result.success).toBe(true);
+		expect(existsSync(path)).toBe(true);
+		// 原子写不留 tmp 中间文件
+		const residues = readdirSync(join(path, "..")).filter((f) => f.includes(".tmp_"));
+		expect(residues).toEqual([]);
+
+		const map = readRegistry(path);
+		expect(map.get("bt-1000-abcd")?.pid).toBe(111);
+		expect(map.get("bt-1000-abcd")?.ownerPiPid).toBe(222);
+	});
+
+	it("serialized entry strips runtime-only fields (intent/child/registryPath)", () => {
+		const path = freshRegistryPath();
+		writeRegistryEntry(path, taskToRegistryEntry(makeEntry()));
+		const raw = JSON.parse(readFileSync(path, "utf8")) as {
+			version: number;
+			entries: Array<Record<string, unknown>>;
+		};
+		expect(raw.version).toBe(1);
+		const entry = raw.entries[0];
+		expect(entry.intent).toBeUndefined();
+		expect(entry.child).toBeUndefined();
+		expect(entry.registryPath).toBeUndefined();
+	});
+
+	it("same task_id merges as update (not duplicate)", () => {
+		const path = freshRegistryPath();
+		writeRegistryEntry(path, taskToRegistryEntry(makeEntry()));
+		writeRegistryEntry(
+			path,
+			taskToRegistryEntry(
+				makeEntry({ state: "exited", exitCode: 0, reason: "natural", endedAt: 2000, durationMs: 1000 }),
+			),
+		);
+		const map = readRegistry(path);
+		expect(map.size).toBe(1);
+		expect(map.get("bt-1000-abcd")?.state).toBe("exited");
+	});
+});
+
+describe("corruption defense (§3.6)", () => {
+	it("bad JSON → renamed .corrupt + empty table rebuild + no crash", () => {
+		const path = freshRegistryPath();
+		writeRegistryEntry(path, taskToRegistryEntry(makeEntry()));
+		// 外力写坏（半程写/手编坏 JSON）
+		writeFileSync(path, '{"version":1,"entries":[{ broken', "utf8");
+
+		const map = readRegistry(path);
+		expect(map.size).toBe(0);
+		expect(existsSync(`${path}.corrupt`)).toBe(true);
+		// 现场保留：.corrupt 里是坏内容本身
+		expect(readFileSync(`${path}.corrupt`, "utf8")).toContain("broken");
+		// 重建可写：下一次写入恢复工作
+		writeRegistryEntry(path, taskToRegistryEntry(makeEntry()));
+		expect(readRegistry(path).size).toBe(1);
+	});
+
+	it("shape-invalid content (entries not array) → same corrupt path", () => {
+		const path = freshRegistryPath();
+		mkdirSync(join(path, ".."), { recursive: true });
+		writeFileSync(path, '{"version":1,"entries":"not-an-array"}', "utf8");
+		const map = readRegistry(path);
+		expect(map.size).toBe(0);
+		expect(existsSync(`${path}.corrupt`)).toBe(true);
+	});
+
+	it("missing file → empty table (first spawn before any write)", () => {
+		const path = freshRegistryPath();
+		expect(readRegistry(path).size).toBe(0);
+	});
+});
+
+describe("terminal LRU (cap 50, symmetric with task store)", () => {
+	it("keeps newest 50 terminal entries, evicts oldest overflow", () => {
+		const path = freshRegistryPath();
+		const TOTAL = MAX_TERMINAL_REGISTRY_ENTRIES + 5;
+		for (let i = 0; i < TOTAL; i++) {
+			writeRegistryEntry(
+				path,
+				taskToRegistryEntry(
+					makeEntry({
+						taskId: `bt-${1000 + i}-aaaa`,
+						startedAt: 1000 + i,
+						state: "exited",
+						endedAt: 2000 + i,
+					}),
+				),
+			);
+		}
+		const map = readRegistry(path);
+		expect(map.size).toBe(MAX_TERMINAL_REGISTRY_ENTRIES);
+		expect(map.has("bt-1000-aaaa")).toBe(false);
+		expect(map.has("bt-1001-aaaa")).toBe(false);
+		expect(map.has("bt-1002-aaaa")).toBe(false);
+		expect(map.has("bt-1003-aaaa")).toBe(false);
+		expect(map.has("bt-1004-aaaa")).toBe(false);
+		expect(map.has(`bt-${1000 + TOTAL - 1}-aaaa`)).toBe(true);
+	});
+});

package/src/__tests__/task-store.test.ts

@@ -0,0 +1,156 @@
+// src/__tests__/task-store.test.ts —— 单例任务表白盒：task_id 唯一性 / 状态机 / LRU
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { afterEach, describe, expect, it } from "vitest";
+
+import { generateTaskId } from "../background/spawn-background.ts";
+import {
+	clearTaskStoreForTest,
+	finalizeTask,
+	MAX_TERMINAL_TASKS,
+	markKillingIntent,
+	registerSpawnedTask,
+	getAllTasks,
+	getActiveTasks,
+	getTask,
+} from "../background/task-store.ts";
+import type { BackgroundTask } from "../background/types.ts";
+
+function makeTask(overrides: Partial<BackgroundTask> = {}): BackgroundTask {
+	return {
+		taskId: overrides.taskId ?? generateTaskId(),
+		pid: overrides.pid ?? 424242,
+		command: overrides.command ?? "sleep 1",
+		outputFile: overrides.outputFile ?? join(mkdtempSync(join(tmpdir(), "bte-")), "out.log"),
+		registryPath: overrides.registryPath ?? "/tmp/registry.json",
+		startedAt: overrides.startedAt ?? Date.now(),
+		state: overrides.state ?? "running",
+		ownerPiPid: overrides.ownerPiPid ?? process.pid,
+		sessionId: overrides.sessionId ?? "session-a",
+		...overrides,
+	};
+}
+
+afterEach(() => {
+	clearTaskStoreForTest();
+});
+
+describe("generateTaskId", () => {
+	it("uses the bt- prefix with <ts>-<rand> shape", () => {
+		const id = generateTaskId(1_724_589_012_000);
+		expect(id).toMatch(/^bt-1724589012000-[a-z0-9]{6}$/);
+	});
+
+	it("generates unique ids across a burst (no process-local sequence)", () => {
+		const ids = new Set<string>();
+		const COUNT = 1000;
+		for (let i = 0; i < COUNT; i++) {
+			const id = generateTaskId();
+			ids.add(id);
+		}
+		// 连续生成无碰撞：自增序列在同 ts 也不碰撞是随机段职责（禁自增，§2.3）
+		expect(ids.size).toBe(COUNT);
+	});
+
+	it("uniqueness holds even with identical timestamps (rand segment disambiguates)", () => {
+		const fixedTs = 1_724_589_012_999;
+		const ids = new Set<string>();
+		const COUNT = 500;
+		for (let i = 0; i < COUNT; i++) {
+			ids.add(generateTaskId(fixedTs));
+		}
+		expect(ids.size).toBe(COUNT);
+	});
+});
+
+describe("task store state machine", () => {
+	it("register → get → active listing", () => {
+		const task = makeTask();
+		registerSpawnedTask(task);
+		expect(getTask(task.taskId)?.pid).toBe(task.pid);
+		expect(getActiveTasks().map((t) => t.taskId)).toEqual([task.taskId]);
+	});
+
+	it("markKillingIntent transitions running → killing and records intent", () => {
+		const task = makeTask();
+		registerSpawnedTask(task);
+		const marked = markKillingIntent(task.taskId, "killed");
+		expect(marked?.state).toBe("killing");
+		expect(marked?.intent).toEqual({ reason: "killed", at: expect.any(Number) });
+		// killing 仍属活跃态（轮询器监护对象）
+		expect(getActiveTasks().map((t) => t.taskId)).toEqual([task.taskId]);
+	});
+
+	it("markKillingIntent on terminal task is a no-op (undefined)", () => {
+		const task = makeTask();
+		registerSpawnedTask(task);
+		finalizeTask(task.taskId, { exitCode: 0, reason: "natural", endedAt: Date.now() });
+		expect(markKillingIntent(task.taskId, "killed")).toBeUndefined();
+	});
+
+	it("finalizeTask writes terminal fields, consumes intent, computes duration", () => {
+		const task = makeTask({ startedAt: Date.now() - 1500 });
+		registerSpawnedTask(task);
+		markKillingIntent(task.taskId, "timeout");
+		const finalized = finalizeTask(task.taskId, {
+			exitCode: null,
+			reason: "timeout",
+			endedAt: Date.now(),
+		});
+		expect(finalized?.state).toBe("exited");
+		expect(finalized?.reason).toBe("timeout");
+		expect(finalized?.exitCode).toBeNull();
+		expect(finalized?.intent).toBeUndefined();
+		expect(finalized?.durationMs).toBeGreaterThanOrEqual(1500);
+		expect(getActiveTasks()).toHaveLength(0);
+	});
+
+	it("finalizeTask is idempotent for terminal tasks (single ownership of terminal state)", () => {
+		const task = makeTask();
+		registerSpawnedTask(task);
+		const first = finalizeTask(task.taskId, { exitCode: 0, reason: "natural", endedAt: Date.now() });
+		const second = finalizeTask(task.taskId, { exitCode: 1, reason: "killed", endedAt: Date.now() });
+		// 第二次终态化不覆盖已定终态
+		expect(first?.reason).toBe("natural");
+		expect(second?.reason).toBe("natural");
+		expect(second?.exitCode).toBe(0);
+	});
+});
+
+describe("terminal LRU eviction (cap 50)", () => {
+	it("evicts oldest terminal entries beyond cap, keeps recent ones", () => {
+		const OVERFLOW = 5;
+		const total = MAX_TERMINAL_TASKS + OVERFLOW;
+		const created: BackgroundTask[] = [];
+		for (let i = 0; i < total; i++) {
+			const task = makeTask({ startedAt: 1000 + i });
+			created.push(task);
+			registerSpawnedTask(task);
+			finalizeTask(task.taskId, { exitCode: 0, reason: "natural", endedAt: 2000 + i });
+		}
+		const remaining = getAllTasks();
+		expect(remaining).toHaveLength(MAX_TERMINAL_TASKS);
+		// 最老的 OVERFLOW 条被淘汰
+		for (let i = 0; i < OVERFLOW; i++) {
+			expect(getTask(created[i].taskId)).toBeUndefined();
+		}
+		// 最新的 50 条保留
+		for (let i = OVERFLOW; i < total; i++) {
+			expect(getTask(created[i].taskId)).toBeDefined();
+		}
+	});
+
+	it("active tasks are never evicted by LRU", () => {
+		const active = makeTask({ startedAt: 1 });
+		registerSpawnedTask(active);
+		for (let i = 0; i < MAX_TERMINAL_TASKS + 10; i++) {
+			const task = makeTask({ startedAt: 1000 + i });
+			registerSpawnedTask(task);
+			finalizeTask(task.taskId, { exitCode: 0, reason: "natural", endedAt: 2000 + i });
+		}
+		expect(getTask(active.taskId)).toBeDefined();
+		expect(getTask(active.taskId)?.state).toBe("running");
+	});
+});