@zhushanwen/pi-base-tool-enhance 0.2.0

package/src/__tests__/config.test.ts

@@ -0,0 +1,193 @@
+// src/__tests__/config.test.ts —— M4 配置 normalize 全矩阵 + 读时刷新热重载
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+// logger mock：断言「单键回退默认 + warn」的可证伪性（真实 logger 行为不在本文件验证面）
+const { warnMock } = vi.hoisted(() => ({ warnMock: vi.fn() }));
+vi.mock("@zhushanwen/pi-extension-logger", () => ({
+	getLogger: () => ({ debug: vi.fn(), warn: warnMock, error: vi.fn() }),
+}));
+
+// getAgentDir → 测试临时目录（loadConfig 经 llm-shared getConfigPath 用它推导路径）
+const { agentDirRef } = vi.hoisted(() => ({ agentDirRef: { dir: "" } }));
+vi.mock("@earendil-works/pi-coding-agent", () => ({
+	getAgentDir: () => agentDirRef.dir,
+}));
+
+import { clearConfigCache } from "@zhushanwen/pi-llm-shared";
+
+import {
+	DEFAULT_BASE_TOOL_ENHANCE_CONFIG,
+	getConfigFilePath,
+	loadBaseToolEnhanceConfig,
+	normalizeBaseToolEnhanceConfig,
+} from "../config.ts";
+
+let tempDir: string;
+
+beforeEach(() => {
+	tempDir = mkdtempSync(join(tmpdir(), "bte-config-"));
+	agentDirRef.dir = tempDir;
+	warnMock.mockClear();
+	clearConfigCache();
+});
+
+afterEach(() => {
+	rmSync(tempDir, { recursive: true, force: true });
+});
+
+function writeConfigFile(content: string): void {
+	const path = getConfigFilePath();
+	mkdirSync(join(path, ".."), { recursive: true });
+	writeFileSync(path, content, "utf8");
+}
+
+describe("normalizeBaseToolEnhanceConfig（键级矩阵）", () => {
+	it("合法全量配置原样通过（含 null timeout 与正则数组）", () => {
+		const config = normalizeBaseToolEnhanceConfig({
+			forceBackgroundPatterns: ["sleep \\d+", "make .*"],
+			disableBuiltinForcePatterns: true,
+			foregroundTimeoutSeconds: 30,
+			backgroundTimeoutSeconds: 600,
+			maxConcurrentBackground: 16,
+		});
+		expect(config).toEqual({
+			forceBackgroundPatterns: ["sleep \\d+", "make .*"],
+			disableBuiltinForcePatterns: true,
+			foregroundTimeoutSeconds: 30,
+			backgroundTimeoutSeconds: 600,
+			maxConcurrentBackground: 16,
+		});
+		expect(warnMock).not.toHaveBeenCalled();
+	});
+
+	it("零输入（undefined/null/空对象）→ 全默认值", () => {
+		for (const raw of [undefined, null, {}]) {
+			expect(normalizeBaseToolEnhanceConfig(raw)).toEqual(DEFAULT_BASE_TOOL_ENHANCE_CONFIG);
+		}
+		// null/undefined 是合法缺省，不 warn；空对象也不 warn
+		expect(warnMock).not.toHaveBeenCalled();
+	});
+
+	it("根非对象（数组/字符串/数字）→ 全默认 + warn 指向路径", () => {
+		expect(normalizeBaseToolEnhanceConfig(["npm test"])).toEqual(DEFAULT_BASE_TOOL_ENHANCE_CONFIG);
+		expect(warnMock).toHaveBeenCalledTimes(1);
+		expect(warnMock.mock.calls[0]?.[0]).toContain("not a JSON object");
+		expect(warnMock.mock.calls[0]?.[0]).toContain("base-tool-enhance-ext-config.json");
+	});
+
+	it("timeout：负数/0/字符串/NaN/Infinity → 回退 null + warn", () => {
+		for (const bad of [-5, 0, "10", Number.NaN, Number.POSITIVE_INFINITY]) {
+			warnMock.mockClear();
+			const config = normalizeBaseToolEnhanceConfig({ foregroundTimeoutSeconds: bad });
+			expect(config.foregroundTimeoutSeconds).toBeNull();
+			expect(warnMock).toHaveBeenCalledTimes(1);
+		}
+		const config2 = normalizeBaseToolEnhanceConfig({ backgroundTimeoutSeconds: -1 });
+		expect(config2.backgroundTimeoutSeconds).toBeNull();
+		expect(warnMock).toHaveBeenCalled();
+	});
+
+	it("timeout：换算毫秒超 int32 上限 → clamp 至 int32 毫秒对应秒数 + warn", () => {
+		const config = normalizeBaseToolEnhanceConfig({ foregroundTimeoutSeconds: 1_000_000_000 });
+		// int32 ms 上限 2147483647 → 2147483.647s
+		expect(config.foregroundTimeoutSeconds).toBeCloseTo(2147483.647, 3);
+		expect(warnMock).toHaveBeenCalledTimes(1);
+		expect(warnMock.mock.calls[0]?.[0]).toContain("clamped");
+		// 上限内（2147483s = 2147483000ms < int32 max）不 clamp
+		expect(normalizeBaseToolEnhanceConfig({ foregroundTimeoutSeconds: 2_147_483 }).foregroundTimeoutSeconds).toBe(
+			2_147_483,
+		);
+	});
+
+	it("forceBackgroundPatterns：非数组 → 空 + warn；缺省/null → 空且不 warn", () => {
+		expect(normalizeBaseToolEnhanceConfig({ forceBackgroundPatterns: "sleep \\d+" }).forceBackgroundPatterns).toEqual(
+			[],
+		);
+		expect(warnMock).toHaveBeenCalledTimes(1);
+		warnMock.mockClear();
+		expect(normalizeBaseToolEnhanceConfig({}).forceBackgroundPatterns).toEqual([]);
+		expect(normalizeBaseToolEnhanceConfig({ forceBackgroundPatterns: null }).forceBackgroundPatterns).toEqual([]);
+		expect(warnMock).not.toHaveBeenCalled();
+	});
+
+	it("forceBackgroundPatterns：单条坏正则仅丢弃该条，其余保留（一条坏正则不拖垮全部）", () => {
+		const config = normalizeBaseToolEnhanceConfig({
+			forceBackgroundPatterns: ["sleep \\d+", "([bad", "make .*", 42],
+		});
+		expect(config.forceBackgroundPatterns).toEqual(["sleep \\d+", "make .*"]);
+		expect(warnMock).toHaveBeenCalledTimes(2); // 坏正则 + 非字符串各一条
+		expect(warnMock.mock.calls[0]?.[0]).toContain("not a valid regex");
+	});
+
+	it("disableBuiltinForcePatterns：非 boolean → false + warn；boolean 原样", () => {
+		expect(normalizeBaseToolEnhanceConfig({ disableBuiltinForcePatterns: true }).disableBuiltinForcePatterns).toBe(
+			true,
+		);
+		expect(normalizeBaseToolEnhanceConfig({ disableBuiltinForcePatterns: false }).disableBuiltinForcePatterns).toBe(
+			false,
+		);
+		const config = normalizeBaseToolEnhanceConfig({ disableBuiltinForcePatterns: "yes" });
+		expect(config.disableBuiltinForcePatterns).toBe(false);
+		expect(warnMock).toHaveBeenCalledTimes(1);
+	});
+
+	it("maxConcurrentBackground：0/负数/字符串 → 默认 8 + warn；小数 floor；合法整数原样", () => {
+		for (const bad of [0, -1, "8", Number.NaN]) {
+			warnMock.mockClear();
+			expect(normalizeBaseToolEnhanceConfig({ maxConcurrentBackground: bad }).maxConcurrentBackground).toBe(8);
+			expect(warnMock).toHaveBeenCalledTimes(1);
+		}
+		expect(normalizeBaseToolEnhanceConfig({ maxConcurrentBackground: 4.9 }).maxConcurrentBackground).toBe(4);
+		expect(normalizeBaseToolEnhanceConfig({ maxConcurrentBackground: 16 }).maxConcurrentBackground).toBe(16);
+	});
+
+	it("未知键忽略（前向兼容，不 warn 不拒载）", () => {
+		const config = normalizeBaseToolEnhanceConfig({ futureKey: "x", foregroundTimeoutSeconds: 5 });
+		expect(config.foregroundTimeoutSeconds).toBe(5);
+		expect(warnMock).not.toHaveBeenCalled();
+	});
+});
+
+describe("loadBaseToolEnhanceConfig（llm-shared loadConfig 集成）", () => {
+	it("文件不存在 → 全默认值（工具照常工作）", () => {
+		expect(loadBaseToolEnhanceConfig()).toEqual(DEFAULT_BASE_TOOL_ENHANCE_CONFIG);
+	});
+
+	it("文件整体损坏（坏 JSON）→ 全默认值 + warn 指向路径", () => {
+		writeConfigFile("{ not json !!!");
+		const config = loadBaseToolEnhanceConfig();
+		expect(config).toEqual(DEFAULT_BASE_TOOL_ENHANCE_CONFIG);
+		expect(warnMock).toHaveBeenCalledTimes(1);
+		expect(warnMock.mock.calls[0]?.[0]).toContain("base-tool-enhance-ext-config.json");
+	});
+
+	it("键级坏配置经 loadConfig 读取同样键级回退（normalize 永不整体拒载）", () => {
+		writeConfigFile(JSON.stringify({ foregroundTimeoutSeconds: -3, maxConcurrentBackground: 4 }));
+		const config = loadBaseToolEnhanceConfig();
+		expect(config.foregroundTimeoutSeconds).toBeNull();
+		expect(config.maxConcurrentBackground).toBe(4);
+	});
+
+	it("热重载：改配置文件后（不重启、不手动刷新）再次 load 拿到新值（mtime+size 读时刷新）", () => {
+		writeConfigFile(JSON.stringify({ foregroundTimeoutSeconds: 11 }));
+		expect(loadBaseToolEnhanceConfig().foregroundTimeoutSeconds).toBe(11);
+
+		// 内容变化（size 变化触发 mtime+size 缓存失效）
+		writeConfigFile(JSON.stringify({ foregroundTimeoutSeconds: 222 }));
+		expect(loadBaseToolEnhanceConfig().foregroundTimeoutSeconds).toBe(222);
+
+		// 删除文件 → 回默认（缓存同样失效）
+		rmSync(getConfigFilePath());
+		expect(loadBaseToolEnhanceConfig()).toEqual(DEFAULT_BASE_TOOL_ENHANCE_CONFIG);
+	});
+
+	it("配置文件路径 = <agentDir>/config/base-tool-enhance-ext-config.json", () => {
+		expect(getConfigFilePath()).toBe(join(tempDir, "config", "base-tool-enhance-ext-config.json"));
+		writeConfigFile("{}");
+		expect(existsSync(getConfigFilePath())).toBe(true);
+	});
+});

package/src/__tests__/force-patterns.test.ts

@@ -0,0 +1,230 @@
+// src/__tests__/force-patterns.test.ts —— M4 白名单：内置两组命中样例 / 锚定语义 /
+// 合并矩阵三态 / 用户正则。锚定四例（参数文本不误伤）是设计 §3.5 的强制断言。
+import { describe, expect, it } from "vitest";
+
+import {
+	compileForcePatterns,
+	describeForceMatch,
+	matchForceBackground,
+	type ForcePattern,
+} from "../force-patterns.ts";
+
+function match(command: string, patterns: ForcePattern[]) {
+	return matchForceBackground(command, patterns);
+}
+
+const DEFAULT_PATTERNS = compileForcePatterns([], false);
+
+describe("内置 force-test 组命中样例（迁自 unified-hooks test-timeout-guard）", () => {
+	const cases: Array<[string, string]> = [
+		["npm test", "npm test"],
+		["pnpm test", "npm test"],
+		["yarn test", "npm test"],
+		["bun test", "npm test"],
+		["npm run test:unit", "npm run test"],
+		["pnpm --filter @x/y run test", "npm run test"],
+		["npx vitest run src/foo.test.ts", "vitest"],
+		["npx jest --silent", "jest"],
+		["npx mocha test/", "mocha"],
+		["npx playwright test", "e2e runner"],
+		["npx cypress run", "e2e runner"],
+		["npx vue-cli-service test:unit", "vue-cli test"],
+		["npx react-scripts test", "react-scripts test"],
+		["./node_modules/.bin/vitest", "direct test runner"],
+		["pytest -q", "pytest"],
+		["python -m pytest", "python test"],
+		["python3 -m unittest discover", "python test"],
+		["uv run pytest", "uv/poetry pytest"],
+		["poetry run pytest -x", "uv/poetry pytest"],
+		["nosetests tests/", "nosetests"],
+		["mvn test", "maven test"],
+		["./mvnw test", "maven test"],
+		["mvn integration-test", "maven test"],
+		["gradle test --info", "gradle test"],
+		["./gradlew test", "gradle test"],
+		["sbt test", "sbt test"],
+		["go test ./...", "go test"],
+		["cargo test --all", "cargo test"],
+		["dotnet test", "dotnet test"],
+		["rspec spec/", "rspec"],
+		["bundle exec rspec", "rspec"],
+		["rake test", "rake test"],
+	];
+	for (const [command, label] of cases) {
+		it(`${command} → label '${label}'`, () => {
+			const result = match(command, DEFAULT_PATTERNS);
+			expect(result).toBeDefined();
+			expect(result?.source).toBe("builtin-test");
+			expect(result?.name).toBe("test");
+			expect(result?.label).toBe(label);
+		});
+	}
+});
+
+describe("内置 force-longrun 组命中样例（M4 定稿清单）", () => {
+	const hitCases: Array<[string, string]> = [
+		// dev server：npm run dev 系
+		["npm run dev", "package run dev"],
+		["pnpm run dev", "package run dev"],
+		["yarn run dev", "package run dev"],
+		["pnpm --filter web run dev", "package run dev"],
+		["npm run dev:web", "package run dev"],
+		["pnpm dev", "package dev"],
+		["yarn dev", "package dev"],
+		["bun dev", "package dev"],
+		// dev server：npx 直接调用
+		["npx vite", "vite"],
+		["npx vite --port 5173", "vite"],
+		["npx next dev", "next dev"],
+		["npx nuxt dev", "nuxt dev"],
+		["npx ng serve", "ng serve"],
+		["npx webpack serve", "webpack serve"],
+		["npx webpack-dev-server", "webpack-dev-server"],
+		// dev server：语言内置 serve
+		["python -m http.server 8080", "http.server"],
+		["python3 manage.py runserver", "runserver"],
+		["flask run", "flask run"],
+		["rails server", "rails server"],
+		["rails s -p 3001", "rails server"],
+		["php artisan serve", "artisan serve"],
+		// 显式 watch flags（直跑形态；npx vitest/jest --watch 会被 force-test 组先命中，
+		// 两组动作一致都是强制后台，此处用直跑形态验证 watch 条目本身）
+		["vitest --watch", "vitest/jest --watch"],
+		["jest --watchAll", "vitest/jest --watch"],
+		["tsc --watch", "tsc watch"],
+		["tsc -w", "tsc watch"],
+		["npx tsc --noEmit --watch", "tsc watch"],
+		["sass --watch src:dist", "build --watch"],
+		["webpack --watch", "build --watch"],
+		["npx esbuild src.js --watch --outdir=dist", "build --watch"],
+		// 天然长驻
+		["cargo watch -x test", "cargo watch"],
+		["watchexec make build", "watchexec"],
+		["nodemon server.js", "nodemon"],
+		["tail -f /var/log/system.log", "tail -f"],
+		["tail -n 100 -f app.log", "tail -f"],
+		["tail -F /var/log/syslog", "tail -f"],
+		["ngrok http 3000", "ngrok"],
+	];
+	for (const [command, label] of hitCases) {
+		it(`${command} → label '${label}'`, () => {
+			const result = match(command, DEFAULT_PATTERNS);
+			expect(result).toBeDefined();
+			expect(result?.source).toBe("builtin-longrun");
+			expect(result?.name).toBe("longrun");
+			expect(result?.label).toBe(label);
+		});
+	}
+
+	const missCases = [
+		// dev server 误伤排除：build 有自然退出点
+		"npm run build",
+		"npx vite build",
+		"vite build --watch", // 非 npx 直跑 vite build（罕见形态）不做工具名白名单外的猜测
+		"npm run lint",
+		"npm run deploy",
+		// watch flag 形态排除：显式关 watch / 无 watch flag
+		"vitest --watch=false",
+		"jest --watchAll=false",
+		"tsc --noEmit",
+		"sass src:dist",
+		// tail 无 -f
+		"tail -n 20 app.log",
+		"tail app.log",
+		// 相似词不误伤
+		"tailwind -i input.css",
+		"cargo build",
+		"watch_node_modules.sh",
+		"dev_setup.sh",
+	];
+	for (const command of missCases) {
+		it(`${command} 不命中任何组（build/lint/无 watch flag 有自然退出点或非命令文本）`, () => {
+			expect(match(command, DEFAULT_PATTERNS)).toBeUndefined();
+		});
+	}
+});
+
+describe("锚定语义（命令位置锚定，防参数文本误伤——§3.5 强制四例）", () => {
+	const cases: Array<{ command: string; hit: boolean; why: string }> = [
+		// ① 必须不命中：commit message 参数里的 "npm test" 是文本不是命令
+		{ command: `git commit -m "fix: npm test"`, hit: false, why: "参数文本不是命令位置" },
+		// ② 必须不命中：watch 是 grep 的参数值，不是 flag
+		{ command: "rg --files | grep watch", hit: false, why: "grep watch 的 watch 是参数不是 flag" },
+		// ③ 必须命中：&& 之后是新命令起始位
+		{ command: "echo hi && npm test", hit: true, why: "&& 之后是命令位置" },
+		// ④ 必须命中：行首
+		{ command: "npm test", hit: true, why: "行首命令位置" },
+	];
+	for (const { command, hit, why } of cases) {
+		it(`${JSON.stringify(command)} ${hit ? "命中" : "不命中"}（${why}）`, () => {
+			expect(match(command, DEFAULT_PATTERNS) !== undefined).toBe(hit);
+		});
+	}
+
+	it("其余命令位置分隔符（; / || / | / 换行）之后的命令同样命中", () => {
+		expect(match("cd /tmp; npm test", DEFAULT_PATTERNS)).toBeDefined();
+		expect(match("false || npx vitest", DEFAULT_PATTERNS)).toBeDefined();
+		expect(match("git pull\nnpm test", DEFAULT_PATTERNS)).toBeDefined();
+		expect(match("rg --files | npx jest", DEFAULT_PATTERNS)).toBeDefined();
+		// 引号内的命令文本不命中（引号不是命令分隔符）
+		expect(match(`echo "vitest --watch"`, DEFAULT_PATTERNS)).toBeUndefined();
+		expect(match(`echo "npm run dev"`, DEFAULT_PATTERNS)).toBeUndefined();
+		expect(match(`git commit -m "run dev server"`, DEFAULT_PATTERNS)).toBeUndefined();
+		expect(match(`grep tail -f README.md`, DEFAULT_PATTERNS)).toBeUndefined();
+		// 词中子串不命中
+		expect(match("npm testing", DEFAULT_PATTERNS)).toBeUndefined();
+		expect(match("mytsc --watchish", DEFAULT_PATTERNS)).toBeUndefined();
+	});
+});
+
+describe("合并矩阵（§3.5 配置开关 × 组）", () => {
+	it("零配置：两组内置均生效", () => {
+		const patterns = compileForcePatterns([], false);
+		expect(match("npm test", patterns)?.source).toBe("builtin-test");
+		expect(match("tail -f app.log", patterns)?.source).toBe("builtin-longrun");
+	});
+
+	it("disableBuiltinForcePatterns:true：两组内置关闭", () => {
+		const patterns = compileForcePatterns([], true);
+		expect(match("npm test", patterns)).toBeUndefined();
+		expect(match("tail -f app.log", patterns)).toBeUndefined();
+		expect(match("npx vite", patterns)).toBeUndefined();
+	});
+
+	it("用户正则追加（与内置并存，匹配任一即命中）", () => {
+		const patterns = compileForcePatterns(["sleep \\d+"], false);
+		expect(match("sleep 999", patterns)?.source).toBe("user");
+		// 内置两组不受影响
+		expect(match("npm test", patterns)?.source).toBe("builtin-test");
+		expect(match("ngrok http 3000", patterns)?.source).toBe("builtin-longrun");
+	});
+
+	it("disableBuiltin + 用户正则：仅用户正则生效", () => {
+		const patterns = compileForcePatterns(["sleep \\d+"], true);
+		expect(match("sleep 999", patterns)?.source).toBe("user");
+		expect(match("npm test", patterns)).toBeUndefined();
+	});
+
+	it("用户正则同样命令位置锚定：参数文本不误伤、链式后段命中", () => {
+		const patterns = compileForcePatterns(["sleep \\d+"], false);
+		expect(match("echo sleep 999", patterns)).toBeUndefined();
+		expect(match("git commit -m \"sleep 999\"", patterns)).toBeUndefined();
+		expect(match("echo hi && sleep 999", patterns)?.source).toBe("user");
+	});
+});
+
+describe("匹配结果报告（result 文案引用）", () => {
+	it("内置命中报组名 + 条目标签", () => {
+		expect(describeForceMatch(match("npm test", DEFAULT_PATTERNS)!)).toBe("pattern 'test' (npm test)");
+		expect(describeForceMatch(match("tail -f x", DEFAULT_PATTERNS)!)).toBe("pattern 'longrun' (tail -f)");
+	});
+
+	it("用户正则报字面量前 40 字符（超长截断加省略号）", () => {
+		const short = compileForcePatterns(["sleep \\d+"], true);
+		expect(describeForceMatch(match("sleep 1", short)!)).toBe("user pattern 'sleep \\d+'");
+		const longPattern = "a".repeat(45);
+		const long = compileForcePatterns([longPattern], true);
+		const described = describeForceMatch(match("a".repeat(45), long)!);
+		expect(described).toBe(`user pattern '${"a".repeat(40)}…'`);
+	});
+});

package/src/__tests__/index.test.ts

@@ -0,0 +1,133 @@
+// src/__tests__/index.test.ts —— 入口集成：工具注册（bash / bash_output / bash_kill）+
+// 审计 hook 挂载 + M3 接线（D17 引用刷新 / exit 边沿通知 / session_start 对账链）
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { describe, expect, it, vi } from "vitest";
+
+const { createBashToolDefinitionMock, dataDirRef } = vi.hoisted(() => ({
+	createBashToolDefinitionMock: vi.fn(),
+	dataDirRef: { dir: "/tmp/bte-fake-agent-dir" },
+}));
+vi.mock("@earendil-works/pi-coding-agent", () => ({
+	createBashToolDefinition: createBashToolDefinitionMock,
+	getAgentDir: () => dataDirRef.dir,
+}));
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { getRegistryPath, writeRegistryEntry } from "../background/registry.ts";
+import { resetNotifyForTest } from "../background/notify.ts";
+import baseToolEnhanceExtension from "../index.ts";
+
+function createMockPi() {
+	return {
+		registerTool: vi.fn(),
+		on: vi.fn(),
+		appendEntry: vi.fn(),
+		events: { emit: vi.fn(), on: vi.fn() },
+		sendMessage: vi.fn(),
+	};
+}
+
+function setupOfficialFactory() {
+	createBashToolDefinitionMock.mockReset();
+	createBashToolDefinitionMock.mockReturnValue({
+		name: "bash",
+		label: "bash",
+		description: "official",
+		parameters: {},
+		execute: vi.fn(),
+	});
+}
+
+describe("baseToolEnhanceExtension entry", () => {
+	it("registers bash (override), bash_output and bash_kill tools by name", () => {
+		setupOfficialFactory();
+		const pi = createMockPi();
+
+		baseToolEnhanceExtension(pi as unknown as ExtensionAPI);
+
+		expect(pi.registerTool).toHaveBeenCalledTimes(3);
+		const names = pi.registerTool.mock.calls.map((call) => (call[0] as { name: string }).name);
+		expect(names).toEqual(["bash", "bash_output", "bash_kill"]);
+	});
+
+	it("mounts the tool error audit hook", () => {
+		setupOfficialFactory();
+		const pi = createMockPi();
+
+		baseToolEnhanceExtension(pi as unknown as ExtensionAPI);
+
+		expect(pi.on).toHaveBeenCalledWith("tool_execution_end", expect.any(Function));
+	});
+
+	it("registers a session_start handler (reaper + reconcile chain, M5/M3)", () => {
+		setupOfficialFactory();
+		const pi = createMockPi();
+
+		baseToolEnhanceExtension(pi as unknown as ExtensionAPI);
+
+		expect(pi.on).toHaveBeenCalledWith("session_start", expect.any(Function));
+	});
+});
+
+describe("session_start chain: reaper first, reconcile after (M3)", () => {
+	it("settles a zombie register via appendEntry on the SAME pi reference after reaper", async () => {
+		setupOfficialFactory();
+		// 独立临时 dataDir：reaper 对空目录 no-op，registry 预置终态僵尸条目
+		const dataDir = mkdtempSync(join(tmpdir(), "bte-index-"));
+		dataDirRef.dir = dataDir;
+		try {
+			const sessionId = "sess-index";
+			writeRegistryEntry(getRegistryPath(dataDir, sessionId), {
+				taskId: "bt-1700000000-idx001",
+				pid: 12345,
+				command: "sleep 3600",
+				outputFile: "/tmp/idx.log",
+				startedAt: 1_700_000_000_000,
+				state: "orphaned",
+				ownerPiPid: 1,
+				sessionId,
+			});
+			const pi = createMockPi();
+			baseToolEnhanceExtension(pi as unknown as ExtensionAPI);
+
+			const handler = pi.on.mock.calls.find((call) => call[0] === "session_start")?.[1] as (
+				event: unknown,
+				ctx: { sessionManager: { getSessionId: () => string; getEntries: () => unknown[] } },
+			) => void;
+			expect(handler).toBeDefined();
+			handler(undefined, {
+				sessionManager: {
+					getSessionId: () => sessionId,
+					getEntries: () => [
+						{
+							customType: "pending:register",
+							data: { id: "bt-1700000000-idx001", type: "bash", name: "sleep 3600" },
+						},
+					],
+				},
+			});
+
+			// handler 是 fire-and-forget（内部 await reaper 后同步对账）——等待落定
+			await vi.waitFor(() =>
+				expect(pi.appendEntry).toHaveBeenCalledWith("pending:unregister", {
+					id: "bt-1700000000-idx001",
+					reason: "cancelled",
+					status: "cancelled",
+				}),
+			);
+			// 对账之外尽力补一次 emit（listener 内存视图同步，失败无害）
+			expect(pi.events.emit).toHaveBeenCalledWith("pending:unregister", {
+				id: "bt-1700000000-idx001",
+				reason: "cancelled",
+			});
+		} finally {
+			rmSync(dataDir, { recursive: true, force: true });
+			dataDirRef.dir = "/tmp/bte-fake-agent-dir";
+			resetNotifyForTest();
+		}
+	});
+});

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

@@ -0,0 +1,76 @@
+// src/__tests__/kill-tree.test.ts —— 进程树 kill 真实进程验证（POSIX 进程组语义）
+import { spawn } from "node:child_process";
+
+import { describe, expect, it, vi } from "vitest";
+
+vi.setConfig({ testTimeout: 20000 });
+
+import { isPidAlive, killProcessTree } from "../kill-tree.ts";
+
+function sleep(ms: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/** 真实 detached spawn（与本包后台任务同款形态：自成进程组）。 */
+function spawnDetached(command: string) {
+	const child = spawn("/bin/sh", ["-c", command], {
+		detached: true,
+		stdio: "ignore",
+	});
+	child.on("error", () => {});
+	child.unref();
+	return child;
+}
+
+describe("isPidAlive", () => {
+	it("current process is alive", () => {
+		expect(isPidAlive(process.pid)).toBe(true);
+	});
+
+	it("exited process is dead (pid freed after reap)", async () => {
+		const child = spawnDetached("true");
+		const pid = child.pid;
+		if (pid === undefined) throw new Error("no pid");
+		// 等退出 + libuv reap（SIGCHLD → waitpid 后 pid 释放）
+		await sleep(300);
+		expect(isPidAlive(pid)).toBe(false);
+	});
+
+	it("invalid pid (0/negative) is treated as dead", () => {
+		expect(isPidAlive(0)).toBe(false);
+		expect(isPidAlive(-1)).toBe(false);
+	});
+});
+
+describe("killProcessTree (process group semantics)", () => {
+	it("kills the whole detached process group including grandchildren", async () => {
+		// 组长 sh + 两个子 sleep：进程组 kill 必须全部覆盖
+		const child = spawnDetached("sleep 30 & sleep 30 & wait");
+		const pid = child.pid;
+		if (pid === undefined) throw new Error("no pid");
+		await sleep(300); // 让子 sleep 起来
+		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
+	});
+
+	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);
+		expect(() => killProcessTree(pid)).not.toThrow();
+	});
+});