@zhushanwen/pi-base-tool-enhance 0.2.0

package/src/index.ts

@@ -0,0 +1,90 @@
+/**
+ * @zhushanwen/pi-base-tool-enhance 入口。
+ *
+ * M1：同名 override pi 内置 bash 工具 + 前台委托官方工厂 + 工具报错审计 hook（D11）。
+ * M2：background 任务核心生命周期——bash background 分支（spawn 后台 + registry +
+ * 轮询器单例任务表）、bash_output / bash_kill 工具、进程退出收殓、subagent 降级。
+ * M3：pending-notifications 通知接入——load 时刷新轮询器通知通路的 pi 引用（D17
+ * session 替换接管）+ 挂 exit 边沿通知回调（unregister emit + sendMessage steer）+
+ * session_start 对账（reaper 先、对账后，appendEntry 权威路径兜底 pending 收尾）。
+ * 白名单与配置体系（M4 已交付）经 bash-tool execute 读时加载接入。
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { getLogger } from "@zhushanwen/pi-extension-logger";
+
+import { createBashOutputToolDefinition } from "./bash-output-tool.ts";
+import { createBashKillToolDefinition } from "./bash-kill-tool.ts";
+import { createBashOverrideToolDefinition } from "./bash-tool.ts";
+import { handleTaskExit, refreshPiReference } from "./background/notify.ts";
+import { installProcessExitGuard } from "./background/process-exit-guard.ts";
+import { reconcilePendingEntries } from "./background/pending-reconcile.ts";
+import { setOnTaskExit } from "./background/poller.ts";
+import { reapOrphanedTasks } from "./reaper.ts";
+import { setupToolErrorAudit } from "./tool-error-audit.ts";
+
+const logger = getLogger("base-tool-enhance");
+
+export default function baseToolEnhanceExtension(pi: ExtensionAPI): void {
+	// D17 pi 引用刷新：同进程 session 替换（/fork、选择器切换、RPC session.*）→ 新
+	// ResourceLoader/eventBus + extension 重新 load → 本调用把通知通路（notify.ts
+	// 模块级引用）切到新 pi——任务发起于旧 session 而完成通知投递新 session。
+	refreshPiReference(pi);
+	// ⑧⑨ 轮询器 exit 边沿 → pending:unregister emit + sendMessage steer（kill 路径
+	// 不 sendMessage，见 notify.ts 单点归属规则）。重复 load 幂等（覆盖同一回调）
+	setOnTaskExit(handleTaskExit);
+	// 同名 "bash" 覆盖内置工具（pi agent-session _refreshToolRegistry：custom 定义后注册者胜）
+	pi.registerTool(createBashOverrideToolDefinition());
+	// 查询 / 终止工具（D9：独立小工具，kill 与查询权限语义分离）
+	pi.registerTool(createBashOutputToolDefinition());
+	pi.registerTool(createBashKillToolDefinition());
+	// 进程级收殓（D12）：只认 process 信号/退出，绝不在 session_shutdown / dispose 路径
+	installProcessExitGuard();
+	// unified-hooks 退役承接：工具报错审计（D11 落点）
+	setupToolErrorAudit(pi);
+	// 孤儿收殓（M5）+ pending 对账（M3）：任意 session 启动触发（startup/reload/new/resume/fork 全 reason）
+	pi.on("session_start", (_event, ctx: ExtensionContext) => {
+		void runSessionStartMaintenance(pi, ctx);
+	});
+}
+
+/**
+ * session_start 维护链（M5 reaper + M3 对账，reaper 先、对账后）。
+ *
+ * 执行形态：fire-and-forget 而非 await——pi extension runner 对 session_start
+ * handler 是顺序 await（runner.js emit：逐 handler await），若本 handler await
+ * reaper，多进程锁竞争（reaper.lock 等待 + registry 写 busy-wait）会把秒级延迟
+ * 累计进 session 启动链。reaper 是兜底机制，不要求启动时序内完成，扔后台跑、
+ * 错误吞掉记 warn（孤儿保持原状，下一 session_start 幂等重试）。
+ *
+ * 对账同步毫秒级（readRegistry + kill(pid,0) + appendEntry），排在 reaper await
+ * 之后同一 async 函数体内顺序执行——先处置孤儿/补写 registry 终态，对账随后读到
+ * 正确终态；顺序颠倒也无静默错误（对账先见 running+pid 活则不动作，下一
+ * session_start 兜底），按设计约定维持 reaper 先行。
+ *
+ * 不节流（同进程多次 session_start——CLI /fork /switch 均触发，每次都扫）：
+ * 幂等性由三分支判定构造性保证（终态条目跳过、属主活跳过——二次扫描对已处置
+ * 孤儿天然 no-op）；无孤儿时扫描成本 = 目录枚举 + 每目录一次 JSON 读 + 每
+ * running 条目一次 kill(pid,0)，毫秒级且零子进程开销（ps 只在「属主死 + pid 活」
+ * 的孤儿判定时才调用）。节流反而引入「最近扫描后的新孤儿延迟收殓」窗口，不抵。
+ */
+async function runSessionStartMaintenance(pi: ExtensionAPI, ctx: ExtensionContext): Promise<void> {
+	const dataDir = getAgentDir();
+	try {
+		await reapOrphanedTasks(dataDir);
+	} catch (err) {
+		logger.warn("session_start reaper failed; orphans stay until next session start", {
+			detail: { err: err instanceof Error ? err.message : String(err) },
+		});
+	}
+	try {
+		const sessionId = ctx.sessionManager.getSessionId();
+		reconcilePendingEntries(pi, dataDir, sessionId, ctx.sessionManager.getEntries());
+	} catch (err) {
+		// 对账失败无害：僵尸 register 停留差集，下一 session_start 幂等重查
+		logger.warn("session_start pending reconcile failed; zombies retried next session start", {
+			detail: { err: err instanceof Error ? err.message : String(err) },
+		});
+	}
+}

package/src/kill-tree.ts

@@ -0,0 +1,100 @@
+/**
+ * 自实现进程树 kill 与 pid 判活（设计文档 §3.5 bash_kill）。
+ *
+ * 为什么不用 pi 的 killProcessTree：它未从主入口导出（pi package.json exports 仅
+ * `.`/`./rpc-entry`/`./client`，定义在 dist/utils/shell.d.ts 但子路径不暴露），不可
+ * import。分支语义与 pi 实装对齐：Windows `taskkill /F /T`、POSIX 杀进程组
+ * `kill -- -<pgid>`（本包后台任务 detached spawn 自成进程组，pgid = pid）；进程组
+ * 杀不到时回退单 pid + `pgrep -P` 递归杀残留子进程。
+ */
+
+import { spawnSync } from "node:child_process";
+
+import { getLogger } from "@zhushanwen/pi-extension-logger";
+
+const logger = getLogger("base-tool-enhance");
+
+/**
+ * pid 判活：kill(pid, 0) 不发信号只做权限校验。
+ * ESRCH = 已死（含 libuv 自动 reap 后）；EPERM = 进程存在但属其他用户，仍视为活。
+ */
+export function isPidAlive(pid: number): boolean {
+	if (!Number.isInteger(pid) || pid <= 0) return false;
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (err) {
+		return (err as NodeJS.ErrnoException).code === "EPERM";
+	}
+}
+
+/**
+ * 杀整棵进程树（同步；收殓路径在 process.on("exit") 里跑，必须同步）。
+ * 幂等：目标已死时静默成功。
+ */
+export function killProcessTree(pid: number): void {
+	if (!Number.isInteger(pid) || pid <= 0) return;
+	if (process.platform === "win32") {
+		killProcessTreeWindows(pid);
+		return;
+	}
+	// POSIX：detached spawn 自成进程组（pgid = pid），杀进程组一次性覆盖全部子孙
+	try {
+		process.kill(-pid, "SIGKILL");
+		return;
+	} catch (err) {
+		logger.debug("process group kill missed, falling back to single pid + descendants", {
+			detail: { pid, err: err instanceof Error ? err.message : String(err) },
+		});
+	}
+	// 回退：组长已死（进程组不复存在）时单杀 pid + pgrep -P 递归清理残留子进程
+	try {
+		process.kill(pid, "SIGKILL");
+	} catch (err) {
+		// 目标已死：kill 幂等语义，仅留诊断
+		logger.debug("single pid kill missed (already dead?)", {
+			detail: { pid, err: err instanceof Error ? err.message : String(err) },
+		});
+	}
+	killDescendantsRecursive(pid);
+}
+
+function killProcessTreeWindows(pid: number): void {
+	try {
+		const result = spawnSync("taskkill", ["/F", "/T", "/PID", String(pid)], {
+			stdio: "ignore",
+			windowsHide: true,
+		});
+		if (result.error) throw result.error;
+	} catch (err) {
+		logger.debug("taskkill failed", {
+			detail: { pid, err: err instanceof Error ? err.message : String(err) },
+		});
+	}
+}
+
+/** pgrep -P 递归：先杀孙辈再杀子辈（防孙辈在父死后被 reparent 逃逸枚举）。 */
+function killDescendantsRecursive(pid: number): void {
+	let stdout: string;
+	try {
+		const result = spawnSync("pgrep", ["-P", String(pid)], { encoding: "utf8" });
+		if (result.error || result.status !== 0 || !result.stdout) return;
+		stdout = result.stdout;
+	} catch {
+		return;
+	}
+	for (const line of stdout.split("\n")) {
+		const childPid = Number.parseInt(line.trim(), 10);
+		if (Number.isInteger(childPid) && childPid > 0) {
+			killDescendantsRecursive(childPid);
+			try {
+				process.kill(childPid, "SIGKILL");
+			} catch (err) {
+				// 已死：kill 幂等语义，仅留诊断
+				logger.debug("descendant kill missed (already dead?)", {
+					detail: { pid: childPid, err: err instanceof Error ? err.message : String(err) },
+				});
+			}
+		}
+	}
+}

package/src/reaper.ts

@@ -0,0 +1,313 @@
+/**
+ * reaper 孤儿收殓（M5，设计文档 docs/design/base-tool-enhance.md §3.5 数据流末段 /
+ * §2.3 术语 ownerPiPid·reaper / §3.3 D8·D12 / §3.6「reaper 误判防御」/ §4 S5·S8-B）。
+ *
+ * 职责：任意 session 启动时扫描 <dataDir>/base-tool-enhance/ 下全部 sessionId
+ * 目录的 registry.json，按**属主判定**处置孤儿——pi 被强杀（SIGKILL）/崩溃后
+ * detached 后台任务被 init 收养永久存活的兜底防线。R4 轮教训：「一律收殓」会
+ * 误杀桌面端并行 session（每 session 独立 pi 进程）的合法任务——**属主判定是
+ * 这道防线的全部依据，宁可漏杀不可误杀**。
+ *
+ * 三分支判定（§3.5 原文逐字落实）：
+ *  ①属主判定——条目 ownerPiPid 进程仍活 → 跳过（活进程的合法任务，桌面端并行
+ *    session 的常态；kill(pid,0) 判活，ESRCH=死）
+ *  ②孤儿补杀——属主已死 && 任务 pid 存活 → kill-tree 补杀（复用 kill-tree.ts）
+ *    + registry 标 state:"orphaned"
+ *  ③终态收尾——属主已死 && 任务 pid 已死 && 条目仍 running（graceful 收殓写盘
+ *    没完成的遗留）→ 不补杀，仅转终态 state:"orphaned"（registry 终态闭环，
+ *    M3 对账以此判据）
+ *
+ * killing 条目：属主死 → 一并按孤儿处理（bash_kill 已发令但属主死前没等到轮询
+ * 边沿确认，补杀幂等无害）；属主活 → 跳过（属主自己的轮询器正在收尾瞬态）。
+ * exited/orphaned 已终态跳过——这是二次扫描幂等 no-op 的构造性来源。
+ *
+ * pid 复用防御（§3.6）：判「任务 pid 存活」时校验进程 start time，与条目登记值
+ * 不匹配视为已死（防系统复用 pid 后误杀无辜进程）；无法取 start time 的平台
+ * 保守跳过整个处置（宁延迟勿误杀，worktree-manager 同原则）。终态收尾分支③
+ * 无需校验——kill(pid,0) ESRCH 无歧义，校验只服务「判活防复用」。
+ *
+ * 已知缺口→已闭合（M3 补写）：spawn 侧现已写入 pidStartTime（spawn-background.ts
+ * spawn 后读 ps start time，读取失败省略），新条目走精确比较（同单位 epoch 秒）。
+ * 存量旧条目（M3 之前登记、缺该字段）仍降级用 startedAt 秒级校验兜底：
+ * actualStartSec <= floor(startedAt/1000) 视为原进程——登记发生在 spawn 之后（进程
+ * 先启动、条目后登记），原进程必然满足降级判据（floor 单调性，零误跳）。误杀窗口
+ * 如实描述：原进程可在 spawn 与登记之间的毫秒窗口内死亡，pid 又被复用——复用进程
+ * 的 start time 只需晚于原进程死亡（不必然晚于登记时刻），故降级判据的实际误杀窗口
+ * 是「spawn 所在秒内原进程死亡且 pid 被复用」（含登记前死亡+复用与登记后同秒复用
+ * 两种形态），不止「登记后同秒」（概率趋零，方向已登记）。
+ *
+ * 多进程并发串行化：扫描/补杀/写 registry 全程持跨进程文件锁（固定名
+ * reaper.lock）——防两个 pi 进程同时 reap 同一批条目（kill 幂等无害，但 RMW
+ * 写会交错覆盖终态）。误杀防御不依赖锁（属主判定承担），锁只消灭扫描/写入
+ * 交错。fn 内全同步（readdir/read/kill/write 毫秒级），满足 file-lock
+ * 「fn 内禁止任何 await」契约；registry 条目写在 reaper 锁内再取 registry.json
+ * 自身的锁（writeRegistryEntry 内部）——锁序恒为 reaper.lock → registry 锁，
+ * spawn 侧只取 registry 锁，无环无死锁。
+ */
+
+import { spawnSync, type SpawnSyncReturns } from "node:child_process";
+import { readdirSync, type Dirent } from "node:fs";
+import { join } from "node:path";
+
+import { getLogger } from "@zhushanwen/pi-extension-logger";
+import { withFileLock } from "@zhushanwen/pi-file-lock";
+
+import { getBaseToolEnhanceDir, readRegistry, writeRegistryEntry } from "./background/registry.ts";
+import { isActiveState, type RegistryEntry } from "./background/types.ts";
+import { isPidAlive, killProcessTree } from "./kill-tree.ts";
+
+const logger = getLogger("base-tool-enhance");
+
+/** ps 调用超时：卡死的 ps 不拖垮 reaper（超时按取不到处理 → 保守跳过）。 */
+const PS_TIMEOUT_MS = 5000;
+/** 毫秒 → 秒（epoch 秒换算，spawn-background.ts 同名常量先例）。 */
+const MS_PER_SECOND = 1000;
+
+/**
+ * 锁目标名（proper-lockfile 落 <目标>.lock；4.x 实测锁文件是 **mkdir 目录**形态，
+ * 不是普通文件——扫描时须按名排除，否则每轮对锁目录做一次无谓 readRegistry
+ * 且计入 scannedDirs）。
+ */
+const REAPER_LOCK_TARGET = "reaper";
+
+/**
+ * registry 条目扩展字段（M5 reaper 引入；M3 起 spawn 侧已补写——types.ts
+ * RegistryEntry 直接携带 pidStartTime，本接口保留为 reaper 视角的显式声明与
+ * 存量条目（M3 前登记）的读取形状）。单位 epoch 秒（ps -o lstart= 解析值），
+ * 勿混用 /proc tick 毫秒值。
+ */
+export interface RegistryEntryStartTime {
+	pidStartTime?: number;
+}
+
+/** reaper 视角的 registry 条目（M2 RegistryEntry + start time 扩展字段）。 */
+export type ReaperRegistryEntry = RegistryEntry & RegistryEntryStartTime;
+
+/** 读条目扩展字段（运行时 guard：in + typeof + 有限性，防脏数据混入比较）。 */
+function readPidStartTimeSec(entry: RegistryEntry): number | undefined {
+	if ("pidStartTime" in entry) {
+		const registered = (entry as ReaperRegistryEntry).pidStartTime;
+		if (typeof registered === "number" && Number.isFinite(registered)) {
+			return registered;
+		}
+	}
+	return undefined;
+}
+
+/**
+ * 取进程 start time（epoch 秒）。ps -o lstart= 跨 macOS/Linux（Linux /proc/
+ * <pid>/stat 精度更高但 macOS 无 /proc，统一 ps 保跨平台一致）；= 号去表头。
+ * 返回 undefined：进程不存在 / ps 不可用 / 输出不可解析——调用方一律按
+ * 「无法校验 → 保守跳过」处理。
+ */
+export function getProcessStartTimeSec(pid: number): number | undefined {
+	let result: SpawnSyncReturns<string>;
+	try {
+		result = spawnSync("ps", ["-o", "lstart=", "-p", String(pid)], {
+			encoding: "utf8",
+			timeout: PS_TIMEOUT_MS,
+		});
+	} catch {
+		return undefined;
+	}
+	if (result.error || result.status !== 0 || !result.stdout) return undefined;
+	// lstart 形如 "Mon Aug 25 14:23:45 2026"（本地时区），Date.parse 按本地时区解释
+	const ms = Date.parse(result.stdout.trim());
+	return Number.isNaN(ms) ? undefined : Math.floor(ms / MS_PER_SECOND);
+}
+
+/**
+ * pid 身份判据（§3.6「宁不杀勿误杀」的唯一定义点；reaper 孤儿补杀与 background
+ * timeout 到点 kill 共用）。true = 当前占用该 pid 的进程 start time 与登记值匹配，
+ * 可安全 kill。
+ *  - 有登记 start time（spawn 时 ps 读取成功）→ 精确比较（同单位 epoch 秒）
+ *  - 缺登记 start time（M3 前登记的存量条目 / ps 不可用平台）→ startedAtMs 秒级
+ *    降级：登记发生在 spawn 之后（进程先启动、条目后登记），原进程 start time
+ *    必然 ≤ floor(startedAtMs/1000)——见文件头「已知缺口→已闭合」的误杀窗口描述
+ */
+export function pidStartMatchesRegistered(
+	actualStartSec: number,
+	registeredStartSec: number | undefined,
+	startedAtMs: number,
+): boolean {
+	return registeredStartSec !== undefined
+		? actualStartSec === registeredStartSec
+		: actualStartSec <= Math.floor(startedAtMs / MS_PER_SECOND);
+}
+
+/** 单轮扫描统计（日志 + 测试断言面；写失败单独计数保持守恒）。 */
+export interface ReapResult {
+	/** 扫描的 sessionId 目录数（含无 registry / 无活跃条目的目录）。 */
+	scannedDirs: number;
+	/** 分支①跳过：属主活（含 ownerPiPid === 本进程的防御性跳过）。 */
+	ownerAliveSkipped: number;
+	/** 分支②补杀成功：kill-tree 已发令 + orphaned 终态写入。 */
+	killedOrphans: number;
+	/** 分支③终态收尾成功：未补杀，仅转 orphaned。 */
+	finalizedOrphans: number;
+	/** 保守跳过：start time 无法获取 / 复用嫌疑不匹配（含锁内写失败条目停留 running）。 */
+	conservativelySkipped: number;
+}
+
+export interface ReapOptions {
+	/** 测试接缝：进程 start time 获取（epoch 秒）。默认真实 ps。 */
+	getProcessStartTimeSec?: (pid: number) => number | undefined;
+}
+
+/**
+ * 扫描并处置孤儿（跨进程文件锁内执行）。幂等：终态条目跳过 + 属主活跳过，
+ * 二次扫描对已处置孤儿天然 no-op。锁获取失败（重试耗尽）抛 ELOCKED 给调用方
+ * ——孤儿保持原状，下一 session_start 重试，无害。
+ */
+export async function reapOrphanedTasks(dataDir: string, opts: ReapOptions = {}): Promise<ReapResult> {
+	const getStartSec = opts.getProcessStartTimeSec ?? getProcessStartTimeSec;
+	const baseDir = getBaseToolEnhanceDir(dataDir);
+	// 锁目标传 reaper（proper-lockfile 落 <目标>.lock = reaper.lock，固定名）
+	return withFileLock(join(baseDir, REAPER_LOCK_TARGET), () =>
+		Promise.resolve(scanAndReapSync(baseDir, getStartSec)),
+	);
+}
+
+function emptyResult(): ReapResult {
+	return { scannedDirs: 0, ownerAliveSkipped: 0, killedOrphans: 0, finalizedOrphans: 0, conservativelySkipped: 0 };
+}
+
+function scanAndReapSync(
+	baseDir: string,
+	getStartSec: (pid: number) => number | undefined,
+): ReapResult {
+	const result = emptyResult();
+	let dirents: Dirent[];
+	try {
+		dirents = readdirSync(baseDir, { withFileTypes: true });
+	} catch (err) {
+		// baseDir 不存在（从未有过后台任务）是常态，不告警；读失败（权限等）warn 后放弃本轮
+		if ((err as NodeJS.ErrnoException).code !== "ENOENT") {
+			logger.warn("reaper: base dir unreadable, skipping this scan", {
+				detail: { dir: baseDir, err: err instanceof Error ? err.message : String(err) },
+			});
+		}
+		return result;
+	}
+	for (const dirent of dirents) {
+		// reaper.lock（proper-lockfile mkdir 目录形态）与 .DS_Store 等非 session 目录跳过
+		if (!dirent.isDirectory() || dirent.name === `${REAPER_LOCK_TARGET}.lock`) continue;
+		result.scannedDirs++;
+		try {
+			reapSessionDirSync(join(baseDir, dirent.name), getStartSec, result);
+		} catch (err) {
+			// 错误容忍：单目录失败跳过 + warn，不中断整体扫描（readRegistry 已内建
+			// 损坏防御 rename .corrupt + 空表重建，此处 catch 是目录级双保险）
+			logger.warn("reaper: session dir scan failed, skipping dir", {
+				detail: { dir: dirent.name, err: err instanceof Error ? err.message : String(err) },
+			});
+		}
+	}
+	return result;
+}
+
+function reapSessionDirSync(
+	sessionDir: string,
+	getStartSec: (pid: number) => number | undefined,
+	result: ReapResult,
+): void {
+	const registryPath = join(sessionDir, "registry.json");
+	// 不存在 → 空表；损坏 → .corrupt 保留现场 + 空表重建（M2 内建防御，双保险）
+	const entries = readRegistry(registryPath);
+	for (const entry of entries.values()) {
+		if (!isActiveState(entry.state)) continue; // exited/orphaned 终态跳过
+		reapEntrySync(entry, registryPath, getStartSec, result);
+	}
+}
+
+/** 三分支判定主体（§3.5 原文；注释里的 ①②③ 与文件头逐条对应）。 */
+function reapEntrySync(
+	entry: RegistryEntry,
+	registryPath: string,
+	getStartSec: (pid: number) => number | undefined,
+	result: ReapResult,
+): void {
+	// ①属主判定：ownerPiPid === 当前进程 pid = 自己进程的条目出现在别的 session
+	// 目录（理论不该发生——单例表条目唯一来源是本进程 spawn；防御性视为属主活）。
+	// ephemeral 短命附着进程触发 reaper 时，其他进程的任务属主活 → 此处天然
+	// 跳过，无需特判。reaper 永不介入属主存活的挂死任务（bash_kill / 用户职责）。
+	if (entry.ownerPiPid === process.pid || isPidAlive(entry.ownerPiPid)) {
+		result.ownerAliveSkipped++;
+		return;
+	}
+
+	// 属主已死 → 孤儿身份成立，按任务 pid 死活分流
+	if (!isPidAlive(entry.pid)) {
+		// ③终态收尾：任务 pid 已死但条目仍 running/killing（graceful 收殓的
+		// registry 写入没写完/写不进的遗留）→ 不补杀，仅转终态 orphaned——
+		// 保证 registry 终态闭环，对账判据才有依据。ESRCH 无歧义，无需
+		// start-time 校验（校验只服务「判活防复用」）
+		writeOrphanedTerminal(entry, registryPath, "finalized", result);
+		return;
+	}
+
+	// 任务 pid 存活 → ②孤儿补杀前先过 pid 复用防御（§3.6）
+	const actualStartSec = getStartSec(entry.pid);
+	if (actualStartSec === undefined) {
+		// 无法取 start time（平台无 ps / ps 失败 / 输出不可解析）→ 保守跳过
+		// 整个处置：不补杀（可能误杀复用 pid 上的无辜进程）也不转终态（条目
+		// 停留 running，下一 session_start 重试）。宁延迟勿误杀
+		result.conservativelySkipped++;
+		logger.warn("reaper: cannot read pid start time, conservatively skipping entry", {
+			detail: { taskId: entry.taskId, pid: entry.pid, ownerPiPid: entry.ownerPiPid },
+		});
+		return;
+	}
+	const registeredStartSec = readPidStartTimeSec(entry);
+	if (!pidStartMatchesRegistered(actualStartSec, registeredStartSec, entry.startedAt)) {
+		// start time 与登记值不匹配 = pid 已被系统复用，当前占用者是无关新进程
+		// → 视为已死：不误杀，也不转终态（任务真实死活未知，交下一周期）
+		result.conservativelySkipped++;
+		logger.warn("reaper: pid start time mismatch (likely pid reuse), skipping entry", {
+			detail: {
+				taskId: entry.taskId,
+				pid: entry.pid,
+				ownerPiPid: entry.ownerPiPid,
+				actualStartSec,
+				registeredStartSec,
+			},
+		});
+		return;
+	}
+
+	// ②孤儿补杀：属主已死 + 原进程身份成立（pid 活 + start time 匹配）
+	killProcessTree(entry.pid);
+	logger.warn("reaper: orphan task killed", {
+		detail: { taskId: entry.taskId, pid: entry.pid, ownerPiPid: entry.ownerPiPid, command: entry.command },
+	});
+	writeOrphanedTerminal(entry, registryPath, "killed", result);
+}
+
+/**
+ * 写 orphaned 终态（分支②③共用）。reason 不写：reason 枚举（natural/timeout/
+ * killed/process-exit）属 exited 语义，orphaned 的成因（属主强杀遗留）不在
+ * 枚举内，保持 undefined 而非造词。
+ */
+function writeOrphanedTerminal(
+	entry: RegistryEntry,
+	registryPath: string,
+	kind: "killed" | "finalized",
+	result: ReapResult,
+): void {
+	const endedAt = Date.now();
+	const orphaned: ReaperRegistryEntry = {
+		...entry,
+		state: "orphaned",
+		endedAt,
+		durationMs: endedAt - entry.startedAt,
+	};
+	const written = writeRegistryEntry(registryPath, orphaned);
+	if (!written.success) {
+		// 写失败：条目停留 running。补杀分支进程已死，下一轮 reap 走③收尾；
+		// 终态收尾分支下一轮重试——幂等闭环，无静默丢失
+		result.conservativelySkipped++;
+		return;
+	}
+	if (kind === "killed") result.killedOrphans++;
+	else result.finalizedOrphans++;
+}

package/src/tool-error-audit.ts

@@ -0,0 +1,78 @@
+/**
+ * 工具报错审计 hook —— 自 unified-hooks tool-error-handler 等价迁移（设计文档 D11 落点）。
+ *
+ * 迁移约定（与原实现逐字段一致，M1 验收点）：
+ *  - 事件名 = "tool_execution_end"（pi 0.84.1 实装无 "tool_error" 事件，工具报错以
+ *    ToolExecutionEndEvent.isError=true 表达——以 dist types.d.ts 为准）
+ *  - customType = "unified-hooks:tool-error"（保持原值，等价迁移不断链；unified-hooks
+ *    整包废弃后该 entry 由本包继续产出，M6 摘除旧包时消费方无感）
+ *  - entry 形态 = { timestamp, toolName, toolCallId, errorText }，errorText 取不到时 null
+ *
+ * 原实现的设计决策一并继承：不调 ctx.ui.notify——tool error 已在对话流里
+ * （pi 原生 tool result isError → error content 回灌 LLM），notify 会重复显示
+ * 且措辞误导；仅 appendEntry 留审计痕迹。
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+/**
+ * Subset of `ToolExecutionEndEvent` fields used by this hook.
+ * 局部最小接口沿自 unified-hooks 原实现：SDK 的完整事件类型经 CI ambient stub
+ * 不一定可达，宽松声明避免类型环境差异。
+ */
+interface ToolExecutionEndLikeEvent {
+	isError: boolean;
+	toolName: string;
+	toolCallId: string;
+	result?: unknown;
+}
+
+/**
+ * 从 tool 执行结果里提取错误文本。
+ *
+ * pi 在 tool execute 抛错时构造 `{ content: [{ type: "text", text }] }` 塞进
+ * result.content[0].text；事件结构无独立 errorMessage 字段。防御性取多种结构，
+ * 取不到返回 undefined（调用方降级为 null，不阻断）。
+ */
+function extractErrorText(result: unknown): string | undefined {
+	const contentArr = getContentArray(result);
+	if (contentArr) {
+		for (const item of contentArr) {
+			const text = getStringProperty(item, "text");
+			if (text) return text;
+		}
+	}
+	// 兜底：某些工具直接塞 { error: "..." }
+	return getStringProperty(result, "error");
+}
+
+/** 若 result.content 是数组则返回它，否则 undefined。 */
+function getContentArray(result: unknown): unknown[] | undefined {
+	if (typeof result !== "object" || result === null) return undefined;
+	const content = (result as Record<string, unknown>).content;
+	return Array.isArray(content) ? content : undefined;
+}
+
+/** 类型守卫：返回 obj[key] 当它是非空 string，否则 undefined。 */
+function getStringProperty(obj: unknown, key: string): string | undefined {
+	if (typeof obj !== "object" || obj === null) return undefined;
+	const val = (obj as Record<string, unknown>)[key];
+	return typeof val === "string" && val.length > 0 ? val : undefined;
+}
+
+export function setupToolErrorAudit(pi: ExtensionAPI): void {
+	pi.on("tool_execution_end", async (event: unknown) => {
+		const e = event as ToolExecutionEndLikeEvent;
+		if (!e.isError) return;
+
+		const errorText = extractErrorText(e.result);
+
+		const entry = {
+			timestamp: Date.now(),
+			toolName: e.toolName,
+			toolCallId: e.toolCallId,
+			errorText: errorText ?? null,
+		};
+		pi.appendEntry("unified-hooks:tool-error", entry);
+	});
+}