@zhushanwen/pi-base-tool-enhance 0.3.0 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # @zhushanwen/pi-base-tool-enhance
 
-同名 override pi 内置 bash 工具的增强层：前台行为 100% 委托 pi 官方工厂（`createBashToolDefinition`），增量提供 background 模式、强制后台白名单与双模式可配置超时。承接已废弃 unified-hooks 的全部能力（测试类拦截 → force-test 白名单；网络类挂死保护 → 可配置前台默认超时弱承接；工具报错审计 → tool_error 审计 hook，entry customType 保持 `unified-hooks:tool-error` 历史连续）。
+同名 override pi 内置 bash 工具的增强层：前台行为 100% 委托 pi 官方工厂（`createBashToolDefinition`），增量提供 background 模式、强制后台白名单与双模式可配置超时。承接已废弃 unified-hooks 的核心能力（测试类拦截式 guard → force-test 白名单命中自动转后台，匹配语义较原 guard 有调整、登记于 force-patterns.ts；网络类挂死保护 → 可配置前台默认超时，弱承接；工具报错审计 → tool_error 审计 hook，entry customType 保持 `unified-hooks:tool-error` 历史连续）。
 
 设计文档（SSOT）：`docs/design/base-tool-enhance.md`。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-base-tool-enhance",
-  "version": "0.3.0",
+  "version": "0.4.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,18 +28,19 @@
     "skills/"
   ],
   "dependencies": {
-    "@zhushanwen/pi-extension-logger": "0.3.0",
-    "@zhushanwen/pi-file-lock": "0.1.2",
-    "@zhushanwen/pi-llm-shared": "0.4.1"
+    "@xyz-agent/extension-protocol": "0.8.0",
+    "@zhushanwen/pi-extension-logger": "0.4.0",
+    "@zhushanwen/pi-file-lock": "0.2.0",
+    "@zhushanwen/pi-llm-shared": "0.5.0"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.1.9",
     "vitest": "^4.1.8"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.84.1",
+    "@earendil-works/pi-coding-agent": "^0.84.4",
     "typebox": "*",
-    "@zhushanwen/pi-pending-notifications": "0.5.0"
+    "@zhushanwen/pi-pending-notifications": "0.5.2"
   },
   "peerDependenciesMeta": {
     "@zhushanwen/pi-pending-notifications": {

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

@@ -177,7 +177,7 @@ describe("real spawn lifecycle (poll edge finalization)", () => {
 		expect(seen[0]).toBe(`${spawned.task.taskId}:exited:natural`);
 	});
 
-	it("spawned entry carries pidStartTime for reaper precise comparison (M5→M3)", async () => {
+	it("spawned entry carries pidStartTime for kill-side precise comparison (M5→M3)", async () => {
 		const spawned = spawnBg("sleep 30");
 		if (!spawned.ok) throw new Error(spawned.error);
 		const { task } = spawned;
@@ -232,7 +232,7 @@ describe("bash_output tool", () => {
 
 	it("P0-1: list merges only TERMINAL registry entries — running entries stay invisible (§3.5)", async () => {
 		// 独立 session 目录：单例表空 + registry 含 running 与 exited 两条他进程条目
-		// （模拟 resume 被强杀 session：reaper 转终态前的窗口里 registry 残留 running）
+		// （模拟 resume 被强杀 session：runtime 收殓转终态前的窗口里 registry 残留 running）
 		const sid = "sess-p0-list";
 		writeRegistryEntry(getRegistryPath(DATA_DIR, sid), makeRegistryEntry({ taskId: "bt-xrun", state: "running" }));
 		writeRegistryEntry(
@@ -361,7 +361,8 @@ describe("bash_kill tool (killing intent, single-point finalization)", () => {
 		};
 		expect(result.killed).toBe(false);
 		expect(result.reason).toBe("cross-process running task owned by another pi process");
-		expect(result.hint).toContain("reaper");
+		// 收殓已下沉 runtime（u-bte-remove）：hint 指向 runtime 收殓而非 reaper
+		expect(result.hint).toContain("xyz-agent runtime");
 		expect(killTreeCalls).not.toContain(foreignPid); // 未发 kill 信号
 	});
 

package/src/__tests__/index.test.ts

@@ -63,7 +63,7 @@ describe("baseToolEnhanceExtension entry", () => {
 		expect(pi.on).toHaveBeenCalledWith("tool_execution_end", expect.any(Function));
 	});
 
-	it("registers a session_start handler (reaper + reconcile chain, M5/M3)", () => {
+	it("registers a session_start handler (reconcile chain, M3)", () => {
 		setupOfficialFactory();
 		const pi = createMockPi();
 
@@ -73,10 +73,10 @@ describe("baseToolEnhanceExtension entry", () => {
 	});
 });
 
-describe("session_start chain: reaper first, reconcile after (M3)", () => {
-	it("settles a zombie register via appendEntry on the SAME pi reference after reaper", async () => {
+describe("session_start chain: reconcile (M3, reap sunk into runtime by u-bte-remove)", () => {
+	it("settles a zombie register via appendEntry on the SAME pi reference", async () => {
 		setupOfficialFactory();
-		// 独立临时 dataDir：reaper 对空目录 no-op，registry 预置终态僵尸条目
+		// 独立临时 dataDir（维护链只读不扫：收殓已下沉 runtime），registry 预置终态僵尸条目
 		const dataDir = mkdtempSync(join(tmpdir(), "bte-index-"));
 		dataDirRef.dir = dataDir;
 		try {
@@ -99,7 +99,9 @@ describe("session_start chain: reaper first, reconcile after (M3)", () => {
 				ctx: { sessionManager: { getSessionId: () => string; getEntries: () => unknown[] } },
 			) => void;
 			expect(handler).toBeDefined();
-			handler(undefined, {
+			// pi runner emit session_start 必带事件（SessionStartEvent.reason 必填，
+			// pi 0.84.4 实装核实）——维护链入口日志消费 reason
+			handler({ type: "session_start", reason: "resume" }, {
 				sessionManager: {
 					getSessionId: () => sessionId,
 					getEntries: () => [
@@ -111,7 +113,7 @@ describe("session_start chain: reaper first, reconcile after (M3)", () => {
 				},
 			});
 
-			// handler 是 fire-and-forget（内部 await reaper 后同步对账）——等待落定
+			// handler 同步直跑对账（u-bte-remove 后无 reap await）——等待落定
 			await vi.waitFor(() =>
 				expect(pi.appendEntry).toHaveBeenCalledWith("pending:unregister", {
 					id: "bt-1700000000-idx001",

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

@@ -1,11 +1,18 @@
 // src/__tests__/kill-tree.test.ts —— 进程树 kill 真实进程验证（POSIX 进程组语义）
+// + pid 身份判据（getProcessStartTimeSec / pidStartMatchesRegistered——原 reaper.test.ts
+// 覆盖平移：收殓下沉 runtime 后 helper 移入本文件，kill 侧自防御仍消费）
 import { spawn } from "node:child_process";
 
 import { describe, expect, it, vi } from "vitest";
 
 vi.setConfig({ testTimeout: 20000 });
 
-import { isPidAlive, killProcessTree } from "../kill-tree.ts";
+import {
+	getProcessStartTimeSec,
+	isPidAlive,
+	killProcessTree,
+	pidStartMatchesRegistered,
+} from "../kill-tree.ts";
 
 function sleep(ms: number): Promise<void> {
 	return new Promise((resolve) => setTimeout(resolve, ms));
@@ -74,3 +81,44 @@ describe("killProcessTree (process group semantics)", () => {
 		expect(() => killProcessTree(pid)).not.toThrow();
 	});
 });
+
+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 child = spawnDetached("sleep 0.1");
+		const pid = child.pid;
+		if (pid === undefined) throw new Error("no pid");
+		await sleep(500); // 等退出 + libuv reap
+		expect(getProcessStartTimeSec(pid)).toBeUndefined();
+	});
+});
+
+describe("pidStartMatchesRegistered (pid identity predicate, §3.6)", () => {
+	it("exact match on registered pidStartTime authorizes (precise path)", () => {
+		expect(pidStartMatchesRegistered(1000, 1000, 1_700_000_000_000)).toBe(true);
+	});
+
+	it("registered mismatch (pid reuse suspicion) rejects", () => {
+		expect(pidStartMatchesRegistered(2000, 1000, 1_700_000_000_000)).toBe(false);
+	});
+
+	it("missing registration degrades to startedAt-seconds bound: original process authorizes", () => {
+		// 登记发生在 spawn 之后 → 原进程 start time 必然 ≤ floor(startedAt/1000)
+		const startedAtMs = 1_700_000_123_456; // floor = 1_700_000_123
+		expect(pidStartMatchesRegistered(1_700_000_123, undefined, startedAtMs)).toBe(true);
+		expect(pidStartMatchesRegistered(1_700_000_122, undefined, startedAtMs)).toBe(true);
+	});
+
+	it("missing registration degrades: newer-than-registration start time rejects (reuse)", () => {
+		const startedAtMs = 1_700_000_123_456;
+		expect(pidStartMatchesRegistered(1_700_000_124, undefined, startedAtMs)).toBe(false);
+	});
+});

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

@@ -0,0 +1,164 @@
+// src/__tests__/maintenance-once.test.ts —— 收殓下沉后的 session_start 维护链
+// 语义（实施单元 u-bte-remove，设计 docs/design/file-lock-unification-and-reaper-
+// sink.md §3.2 D2「extension 删 session_start reaper」/ §3.3 D3 粒度段 / §4 S6
+// 「批 2 后 reap 类操作不再执行」）：
+//  - reconcilePendingEntries 是 session 级豁免类，每 session_start 派发都执行
+//    （startup/resume/new 多派发 ×N——含 factory 二调 handler 累积的真实形态）
+//  - 触发面消失：reaper.ts 模块文件已删除（文件级断言，见首条用例）+ 维护链不再触发
+//    全局文件锁（withFileLock——原 reapOrphanedTasks 的 reaper.lock 路径）
+//  - 入口无条件 debug 日志按派发次数出现，detail 仅含 reason（reapSkipped 字段
+//    随 reap 调用移除，S6 观测通道语义更新）
+// 断言方式：reconcile / logger / file-lock 全部间谍注入，观察调用次数与参数。
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { describe, expect, it, vi, beforeEach } from "vitest";
+
+const { reconcileMock, loggerMock, officialBashFactoryMock, dataDirRef, withFileLockMock } =
+	vi.hoisted(() => ({
+		reconcileMock: vi.fn(),
+		loggerMock: { debug: vi.fn(), warn: vi.fn(), error: vi.fn() },
+		officialBashFactoryMock: vi.fn(),
+		dataDirRef: { dir: "/tmp/bte-fake-agent-dir" },
+		withFileLockMock: vi.fn(),
+	}));
+
+vi.mock("@earendil-works/pi-coding-agent", () => ({
+	createBashToolDefinition: officialBashFactoryMock,
+	getAgentDir: () => dataDirRef.dir,
+}));
+vi.mock("@zhushanwen/pi-extension-logger", () => ({
+	getLogger: () => loggerMock,
+}));
+// 全局扫描探针：withFileLock 是原 reapOrphanedTasks 持 reaper.lock 的唯一锁路径
+// （registry 写走的是 withFileLockSync）——维护链触发它 = 全局扫描回流
+vi.mock("@zhushanwen/pi-file-lock", () => ({
+	withFileLock: withFileLockMock,
+	withFileLockSync: vi.fn(() => {
+		throw new Error("unexpected registry write in maintenance chain");
+	}),
+}));
+vi.mock("../background/pending-reconcile.ts", () => ({
+	reconcilePendingEntries: reconcileMock,
+}));
+
+import type { ExtensionAPI, SessionStartEvent } from "@earendil-works/pi-coding-agent";
+
+function createMockPi() {
+	return {
+		registerTool: vi.fn(),
+		on: vi.fn(),
+		appendEntry: vi.fn(),
+		events: { emit: vi.fn(), on: vi.fn() },
+		sendMessage: vi.fn(),
+	};
+}
+
+function getSessionStartHandler(pi: ReturnType<typeof createMockPi>) {
+	const handler = pi.on.mock.calls.find((call) => call[0] === "session_start")?.[1];
+	expect(handler).toBeTypeOf("function");
+	return handler as (event: SessionStartEvent, ctx: unknown) => void;
+}
+
+function makeEvent(reason: SessionStartEvent["reason"]): SessionStartEvent {
+	return { type: "session_start", reason };
+}
+
+function makeCtx() {
+	return {
+		sessionManager: { getSessionId: () => "sid-once", getEntries: () => [] },
+	};
+}
+
+async function loadExtension() {
+	return import("../index.ts");
+}
+
+beforeEach(() => {
+	reconcileMock.mockReset();
+	// 官方 bash 工厂返回最小工具定义（override 定义 spread initial.name）
+	officialBashFactoryMock.mockReset();
+	officialBashFactoryMock.mockReturnValue({
+		name: "bash",
+		label: "bash",
+		description: "official",
+		parameters: {},
+		execute: vi.fn(),
+	});
+	withFileLockMock.mockReset();
+	loggerMock.debug.mockClear();
+	loggerMock.warn.mockClear();
+	loggerMock.error.mockClear();
+});
+
+describe("session_start maintenance chain after reap sink (u-bte-remove)", () => {
+	it("no longer ships a reaper: the module is gone from the extension (trigger surface removed)", () => {
+		// 等价改写（fallow unresolved-import）：原断言动态 import 已删除模块期待
+		// rejects——静态分析无法理解故意性。模块文件不存在 ⟹ import 必 rejects，
+		// 蕴含成立，断言价值不变（触发面消失），文件级判定更直接。路径用 join 逐段
+		// 拼装：fallow 会把 ../reaper.ts 形态的相对路径字符串按 import specifier 扫描
+		const reaperModulePath = join(dirname(fileURLToPath(import.meta.url)), "..", "reaper.ts");
+		expect(existsSync(reaperModulePath)).toBe(false);
+	});
+
+	it("runs reconcilePendingEntries on EVERY session_start dispatch (session-scoped exempt, D3)", async () => {
+		const mod = await loadExtension();
+		const pi = createMockPi();
+		mod.default(pi as unknown as ExtensionAPI);
+		const handler = getSessionStartHandler(pi);
+		const ctx = makeCtx();
+
+		// 多派发覆盖真实形态：startup + resume 双发（桌面端每次激活）+ new；
+		// factory 二调 handler 累积时同一事件被多组 handler 各跑一次，同理多次执行
+		handler(makeEvent("startup"), ctx);
+		handler(makeEvent("resume"), ctx);
+		handler(makeEvent("new"), ctx);
+
+		expect(reconcileMock).toHaveBeenCalledTimes(3);
+		expect(reconcileMock).toHaveBeenNthCalledWith(1, expect.anything(), dataDirRef.dir, "sid-once", []);
+		expect(reconcileMock).toHaveBeenLastCalledWith(expect.anything(), dataDirRef.dir, "sid-once", []);
+		// 无全局扫描：维护链不触发原 reaper 的跨进程锁路径，也无告警
+		expect(withFileLockMock).not.toHaveBeenCalled();
+		expect(loggerMock.warn).not.toHaveBeenCalled();
+	});
+
+	it("emits the unconditional entry debug log per dispatch with reason only (S6 observation channel)", async () => {
+		const mod = await loadExtension();
+		const pi = createMockPi();
+		mod.default(pi as unknown as ExtensionAPI);
+		const handler = getSessionStartHandler(pi);
+		const ctx = makeCtx();
+
+		handler(makeEvent("startup"), ctx);
+		handler(makeEvent("resume"), ctx);
+
+		// 每次派发恰好一条入口日志（无条件 = 不以任何条件短路），reason 取自事件；
+		// reapSkipped 字段已随 reap 下沉移除（u-bte-remove 变更登记，S6「批 2 后
+		// reap 类操作不再执行」）
+		expect(loggerMock.debug).toHaveBeenCalledTimes(2);
+		expect(loggerMock.debug).toHaveBeenNthCalledWith(1, "session_start maintenance dispatch", {
+			detail: { reason: "startup" },
+		});
+		expect(loggerMock.debug).toHaveBeenNthCalledWith(2, "session_start maintenance dispatch", {
+			detail: { reason: "resume" },
+		});
+	});
+
+	it("keeps reconcile failures non-fatal: warn logged, dispatch chain not throwing", async () => {
+		reconcileMock.mockImplementation(() => {
+			throw new Error("reconcile boom");
+		});
+		const mod = await loadExtension();
+		const pi = createMockPi();
+		mod.default(pi as unknown as ExtensionAPI);
+		const handler = getSessionStartHandler(pi);
+
+		// 对账抛错被维护链吞掉记 warn（僵尸停留差集，下一 session_start 幂等重查）
+		expect(() => handler(makeEvent("resume"), makeCtx())).not.toThrow();
+		expect(loggerMock.warn).toHaveBeenCalledWith(
+			"session_start pending reconcile failed; zombies retried next session start",
+			expect.objectContaining({ detail: expect.objectContaining({ err: "reconcile boom" }) }),
+		);
+	});
+});

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

@@ -135,7 +135,7 @@ describe("reconcile scenario ①: graceful-exit leftover (registry exited, entry
 	});
 });
 
-describe("reconcile scenario ②: reaper-only orphan (registry orphaned, session file untouched)", () => {
+describe("reconcile scenario ②: collector-only orphan (registry orphaned, session file untouched)", () => {
 	it("appends unregister with cancelled for orphaned entries", () => {
 		const entry = makeRegistryEntry({ state: "orphaned" });
 		writeRegistryEntry(getRegistryPath(DATA_DIR, SESSION_ID), entry);

package/src/__tests__/registry.test.ts

@@ -5,9 +5,10 @@ import { join } from "node:path";
 
 import { afterEach, describe, expect, it } from "vitest";
 
+import { MAX_TERMINAL_REGISTRY_ENTRIES } from "@xyz-agent/extension-protocol";
+
 import {
 	getRegistryPath,
-	MAX_TERMINAL_REGISTRY_ENTRIES,
 	readRegistry,
 	taskToRegistryEntry,
 	writeRegistryEntry,

package/src/background/pending-reconcile.ts

@@ -4,7 +4,7 @@
  * 职责：对「session entries 差集显示 active、但任务已终态」的 bt- 任务补写
  * pending:unregister entry。覆盖三类 otherwise 悬空场景（设计原文）：
  *  ① 进程 graceful 退出收殓时 pi API 已不可用，unregister 没写成 entry；
- *  ② 强杀后 reaper 只改 registry（标 orphaned），碰不了 session 文件；
+ *  ② 强杀后收殓侧只改 registry（标 orphaned），碰不了 session 文件；
  *  ③ fork 后任务完成通知写进新 session，旧 session 文件的 register 成僵尸。
  *
  * 收尾写法（权威路径）：直接 pi.appendEntry("pending:unregister", {id, reason,
@@ -17,11 +17,12 @@
  *
  * 终态判据：registry state ∈ {exited, orphaned}，或（state=running/killing 且
  * kill(pid,0) 判死：收殓/写盘失败遗留的 running 条目按事实终态处理）。
- * 不改 registry——终态写入归 reaper/轮询器（单点归属），对账只清 pending 侧。
+ * 不改 registry——终态写入归收殓侧（runtime reaper）/轮询器（单点归属），对账只清
+ * pending 侧。
  *
- * 执行顺序（index.ts session_start 链内）：reaper 先、对账后——先按属主判定处置
- * 孤儿/补写 registry 终态，对账随后读到正确终态；即使颠倒也无静默错误（对账先见
- * running+pid 活则不动作，下一 session_start 兜底）。
+ * 执行链（index.ts session_start 链内）：收殓下沉 runtime 后（u-bte-remove）本链
+ * 仅剩对账——「对账见 running+pid 活则不动作，下一 session_start 兜底」的幂等
+ * 语义覆盖孤儿终态由 runtime 异步写入的时序窗口。
  */
 
 import { getLogger } from "@zhushanwen/pi-extension-logger";

package/src/background/poller.ts

@@ -50,10 +50,6 @@ export function stopPoller(): void {
 	}
 }
 
-export function isPollerRunning(): boolean {
-	return pollTimer !== undefined;
-}
-
 function pollTick(): void {
 	const active = getActiveTasks();
 	if (active.length === 0) {

package/src/background/process-exit-guard.ts

@@ -18,12 +18,13 @@
  *    挂起进程，pi 的 ignore 语义完全失效
  *  - rpc/print 模式 Ctrl+C：pi 无 SIGINT listener（dist 全量 grep 唯一注册点在 TUI
  *    挂起态）→ 默认处置进程即死。探针实测：无 listener 的信号默认终止**不触发
- *    exit 事件**，同步收殓在该路径本就不可达；孤儿由 M5 reaper 属主判定收殓
- *    （与 SIGKILL 强杀同类，设计内兜底）
+ *    exit 事件**，同步收殓在该路径本就不可达；孤儿由 xyz-agent runtime 收殓器按
+ *    属主判定收殓（u-bte-remove 下沉后；与 SIGKILL 强杀同类，设计内兜底）
  *  - cleanup-only listener 更不可取：注册即抑制默认终止，rpc 前台 Ctrl+C 后 pi 变
  *    成杀不死的僵尸进程
  *
- * 子进程死后 registry 目录无人再扫（reaper 是 M5）——本单元不管。
+ * 子进程死后 registry 目录由 xyz-agent runtime 启动期兜底扫描覆盖（收殓下沉）——
+ * 本单元不管。
  */
 
 import { getLogger } from "@zhushanwen/pi-extension-logger";
@@ -56,7 +57,7 @@ export function installProcessExitGuard(): void {
 	// SIGTERM：只收殓不 exit——pi rpc-mode 的 SIGTERM handler（先注册先跑）走自己的
 	// shutdown 流程，最终 process.exit 触发下方 exit 兜底（幂等跳过）。
 	// SIGINT 刻意不挂 handler——会破坏 pi TUI 挂起态的 ignoreSigint 语义，且 rpc
-	// 默认终止路径 exit 事件本就不触发、孤儿归 M5 reaper 兜底（完整论证见文件头
+	// 默认终止路径 exit 事件本就不触发、孤儿归 runtime 收殓兜底（完整论证见文件头
 	// 「不挂 SIGINT handler」专段）
 	process.once("SIGTERM", cleanup);
 	// 同步兜底：exit handler 里只能做同步收殓（kill-tree 同步 + registry 同步原子写）
@@ -77,7 +78,7 @@ export function reapBackgroundTasksNow(): void {
 		try {
 			killProcessTree(task.pid);
 		} catch (err) {
-			// 单条 kill 失败不阻断其余条目收殓；进程将退出，残余由 M5 reaper 兜底
+			// 单条 kill 失败不阻断其余条目收殓；进程将退出，残余由 runtime 收殓兜底
 			logger.warn("kill-tree failed during process-exit reap", {
 				detail: { taskId: task.taskId, pid: task.pid, err: err instanceof Error ? err.message : String(err) },
 			});

package/src/background/registry.ts

@@ -2,23 +2,33 @@
  * registry.json 持久化读写（per-sessionId 目录，D8）。
  *
  * 路径：<dataDir>/base-tool-enhance/<sessionId>/registry.json（dataDir = pi
- * getAgentDir() 同源路径，由调用方解析传入）。条目记 ownerPiPid——M5 reaper 属主
- * 判定依据，M2 只负责写入。
+ * getAgentDir() 同源路径，由调用方解析传入）。条目记 ownerPiPid——收殓侧属主
+ * 判定依据（u-bte-remove 后 = xyz-agent runtime background-task-reaper），M2 只负责
+ * 写入。
  *
  * 写入协议：
  *  - 原子写 temp+rename（tmp 名带 pid+随机段防并发碰撞，llm-shared saveConfig 范式）
  *  - 锁内 RMW（@zhushanwen/pi-file-lock withFileLockSync）——同 sessionId 目录可能
  *    被桌面端 ephemeral 附着进程与发起进程并发写，跨进程互斥只依赖同一 lockfile
- *  - 锁获取失败不降级无锁写：返回 {success:false}，条目停留 running 由 M5 reaper
- *    兜底（§3.5「registry/entry 写不进则条目停留 running」）
+ *    （runtime 收殓器写终态用 xyz-agent 统一锁，与该 lockfile 互斥）
+ *  - 锁获取失败不降级无锁写：返回 {success:false}，条目停留 running 由 runtime
+ *    收殓兜底（§3.5「registry/entry 写不进则条目停留 running」）
  *  - 损坏读取防御（§3.6）：解析失败/形状非法 → 重命名 .corrupt 保留现场 + 按空表
  *    重建 + warn 日志
  *  - 终态条目 LRU 上限 50（与单例表对称）
+ *
+ * 契约改引（u-bte-remove）：版本常量 / LRU 上限 / 文件形状自
+ * @xyz-agent/extension-protocol background-task.ts 契约引入（此前本地重复定义）。
  */
 
 import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 
+import {
+	BACKGROUND_TASK_REGISTRY_VERSION,
+	type BackgroundTaskRegistryFile,
+	MAX_TERMINAL_REGISTRY_ENTRIES,
+} from "@xyz-agent/extension-protocol";
 import { getLogger } from "@zhushanwen/pi-extension-logger";
 import { withFileLockSync } from "@zhushanwen/pi-file-lock";
 
@@ -26,10 +36,6 @@ import { isTerminalState, type BackgroundTask, type RegistryEntry } from "./type
 
 const logger = getLogger("base-tool-enhance");
 
-/** registry 文件格式版本（未来结构变更时迁移判据）。 */
-const REGISTRY_VERSION = 1;
-/** 终态条目 LRU 上限（与 task-store MAX_TERMINAL_TASKS 对称，§3.5）。 */
-export const MAX_TERMINAL_REGISTRY_ENTRIES = 50;
 const JSON_INDENT = 2;
 // tmp 随机段参数（llm-shared uniqueTmpPath 同款：36 进制随机串，跳过 "0." 前缀）
 const TMP_RADIX = 36;
@@ -44,11 +50,6 @@ export function getRegistryPath(dataDir: string, sessionId: string): string {
 	return join(getBaseToolEnhanceDir(dataDir), sessionId, "registry.json");
 }
 
-interface RegistryFileShape {
-	version: number;
-	entries: RegistryEntry[];
-}
-
 /**
  * 最低限度形状校验：核心标识字段缺失即整条丢弃（不因单条脏数据报废全表）。
  */
@@ -68,7 +69,7 @@ function isValidRegistryEntry(item: unknown): item is RegistryEntry {
 }
 
 /** 校验并归一化 registry 文件内容；形状非法返回 undefined（走 corrupt 路径）。 */
-function parseRegistryContent(raw: string): RegistryFileShape | undefined {
+function parseRegistryContent(raw: string): BackgroundTaskRegistryFile | undefined {
 	let parsed: unknown;
 	try {
 		parsed = JSON.parse(raw);
@@ -77,12 +78,12 @@ function parseRegistryContent(raw: string): RegistryFileShape | undefined {
 	}
 	if (typeof parsed !== "object" || parsed === null) return undefined;
 	const { version, entries } = parsed as Record<string, unknown>;
-	if (version !== REGISTRY_VERSION || !Array.isArray(entries)) return undefined;
+	if (version !== BACKGROUND_TASK_REGISTRY_VERSION || !Array.isArray(entries)) return undefined;
 	const valid: RegistryEntry[] = [];
 	for (const item of entries) {
 		if (isValidRegistryEntry(item)) valid.push(item);
 	}
-	return { version: REGISTRY_VERSION, entries: valid };
+	return { version: BACKGROUND_TASK_REGISTRY_VERSION, entries: valid };
 }
 
 /** .corrupt 落点：固定名优先；已存在则带时间戳，不覆盖前一份现场。 */
@@ -145,7 +146,7 @@ export function taskToRegistryEntry(task: BackgroundTask): RegistryEntry {
 }
 
 function serializeRegistry(entries: RegistryEntry[]): string {
-	const shape: RegistryFileShape = { version: REGISTRY_VERSION, entries };
+	const shape: BackgroundTaskRegistryFile = { version: BACKGROUND_TASK_REGISTRY_VERSION, entries };
 	return `${JSON.stringify(shape, null, JSON_INDENT)}\n`;
 }
 
@@ -172,8 +173,8 @@ function atomicWriteRegistry(registryPath: string, content: string): void {
 /**
  * 写入/更新单条 registry 条目（锁内 RMW：读全量 → 合并同 id 覆盖 → 终态 LRU 50 →
  * 原子写）。任务登记（running）、killing intent、终态三条路径共用。
- * 失败返回 {success:false}——调用方按「写不进则条目停留 running，M5 reaper 兜底」
- * 处理（M2 只 warn，不重试不阻断主流程）。
+ * 失败返回 {success:false}——调用方按「写不进则条目停留 running，runtime 收殓
+ * 兜底」处理（M2 只 warn，不重试不阻断主流程）。
  */
 export function writeRegistryEntry(
 	registryPath: string,
@@ -195,7 +196,7 @@ export function writeRegistryEntry(
 		return { success: true };
 	} catch (err) {
 		const message = err instanceof Error ? err.message : String(err);
-		logger.warn("registry write failed; entry stays as-is (M5 reaper will reconcile)", {
+		logger.warn("registry write failed; entry stays as-is (runtime reaper will collect the orphan)", {
 			detail: { path: registryPath, taskId: entry.taskId, err: message },
 		});
 		return { success: false, error: message };

package/src/background/spawn-background.ts

@@ -14,8 +14,7 @@ import { randomBytes } from "node:crypto";
 
 import { getLogger } from "@zhushanwen/pi-extension-logger";
 
-import { killProcessTree } from "../kill-tree.ts";
-import { getProcessStartTimeSec, pidStartMatchesRegistered } from "../reaper.ts";
+import { getProcessStartTimeSec, killProcessTree, pidStartMatchesRegistered } from "../kill-tree.ts";
 import { emitPendingRegister } from "./notify.ts";
 import { ensurePollerRunning } from "./poller.ts";
 import { getRegistryPath, taskToRegistryEntry, writeRegistryEntry } from "./registry.ts";
@@ -187,8 +186,8 @@ export function spawnBackgroundTask(opts: SpawnBackgroundOptions): SpawnBackgrou
 		return { ok: false, error: "Failed to start background command: no pid acquired" };
 	}
 
-	// M3 补写 M5 预告字段：spawn 后立即读子进程 start time（epoch 秒），供 reaper
-	// 精确比较防 pid 复用误杀。读取失败省略（undefined 不进条目）——reaper 降级走
+	// M3 补写字段：spawn 后立即读子进程 start time（epoch 秒），供收殓/kill 侧
+	// 精确比较防 pid 复用误杀。读取失败省略（undefined 不进条目）——消费方降级走
 	// startedAt 秒级校验兜底，不报错不阻断 spawn
 	const pidStartTime = getProcessStartTimeSec(child.pid);
 
@@ -211,8 +210,9 @@ export function spawnBackgroundTask(opts: SpawnBackgroundOptions): SpawnBackgrou
 	}
 
 	// 登记顺序（§3.5 数据流 ③④⑤）：单例表（运行时权威）→ registry（持久化）→
-	// pending:register emit。registry 写失败不阻断（条目停留 running 由 M5 reaper
-	// 兜底，§3.5）；emit 失败同样无害（peer 未加载/引用未注入时无 listener，通知
+	// pending:register emit。registry 写失败不阻断（条目停留 running 由 runtime
+	// 收殓器兜底——孤儿判定按 ownerPiPid，§3.5；u-bte-remove 下沉后不再依赖本包
+	// 扫描）；emit 失败同样无害（peer 未加载/引用未注入时无 listener，通知
 	// 链路缺失不影响任务本体）
 	registerSpawnedTask(task);
 	writeRegistryEntry(registryPath, taskToRegistryEntry(task));
@@ -228,7 +228,7 @@ export function spawnBackgroundTask(opts: SpawnBackgroundOptions): SpawnBackgrou
  */
 function armBackgroundTimeout(task: BackgroundTask, timeoutSec: number): void {
 	const timer = setTimeout(() => {
-		// pid 复用防御（§3.6，同 reaper reapEntrySync / bash_kill 范式，宁不杀勿误杀）：
+		// pid 复用防御（§3.6，同 bash_kill 范式，宁不杀勿误杀）：
 		// 任务早已退出（exit 边沿未被轮询器收尾或竞态未及）且 pid 在到点前被系统复用
 		// 时，直接 killProcessTree 会杀掉复用 pid 上的无辜进程（整进程组 SIGKILL）。
 		if (!isRecordedPidStillOriginal(task)) {
@@ -254,8 +254,8 @@ function armBackgroundTimeout(task: BackgroundTask, timeoutSec: number): void {
 
 /**
  * 到点 pid 身份校验：true = 登记时的原进程仍占用该 pid（可安全 kill-tree）。
- * 判据（精确比较 / startedAt 秒级降级 / 读不到保守 false）单点定义于 reaper
- * 的 pidStartMatchesRegistered，与 reapEntrySync 孤儿补杀共用同一份。
+ * 判据（精确比较 / startedAt 秒级降级 / 读不到保守 false）单点定义于 kill-tree.ts
+ * 的 pidStartMatchesRegistered（原 reaper.ts 单点，收殓下沉后随删除平移）。
  */
 function isRecordedPidStillOriginal(task: BackgroundTask): boolean {
 	const actualStartSec = getProcessStartTimeSec(task.pid);

package/src/background/subagent-guard.ts

@@ -1,8 +1,8 @@
 /**
  * subagent 进程识别（D14 降级判据，探针 P5）。
  *
- * subagent-workflow 的 buildChildEnv（execution/session-runner.ts）对每个子 agent
- * 进程**无条件**注入身份贯穿 env（PI_SUBAGENT_ROOT_SESSION_ID / SELF_RECORD_ID /
+ * subagent-core 的 buildChildEnv（packages/subagent-core/src/execution/session-runner.ts）
+ * 对每个子 agent 进程**无条件**注入身份贯穿 env（PI_SUBAGENT_ROOT_SESSION_ID / SELF_RECORD_ID /
  * DEPTH / ROOT_CWD，见其源码注释「无条件注入每个 subagent」）。任一存在 = 当前
  * pi 进程是 subagent 子进程 → 本扩展降级：background:true 被忽略走前台同步语义。
  *
@@ -10,7 +10,7 @@
  * 回）；且子进程死后其 registry 目录永远不会再有 session 启动，孤儿无人 reap。
  */
 
-/** subagent-workflow 注入的身份贯穿 env 前缀（跨包契约，P5 探针确认）。 */
+/** subagent-core（session-runner）注入的身份贯穿 env 前缀（跨包契约，P5 探针确认）。 */
 const SUBAGENT_ENV_KEYS = [
 	"PI_SUBAGENT_ROOT_SESSION_ID",
 	"PI_SUBAGENT_SELF_RECORD_ID",

package/src/background/task-store.ts

@@ -7,8 +7,8 @@
  *
  * 条目唯一来源 = 本进程 execute 的 spawn（registerSpawnedTask 全仓唯一调用点 =
  * spawn-background.ts）。他进程 / 历史 session 的 running 条目**永不进表**——
- * 零恢复零接管，处置权统一归 M5 reaper 属主裁决；终态条目可从 registry 读，
- * 仅供 bash_output 查历史。
+ * 零恢复零接管，孤儿处置权统一归收殓侧（u-bte-remove 后 = xyz-agent runtime）
+ * 按属主裁决；终态条目可从 registry 读，仅供 bash_output 查历史。
  *
  * 终态条目 LRU 上限 MAX_TERMINAL_ENTRIES（与 registry 对称），淘汰后 bash_output
  * 回落 registry 查询。