@zhushanwen/pi-base-tool-enhance 0.5.2 → 0.5.3

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zhushanwen/pi-base-tool-enhance",
-  "version": "0.5.2",
-  "description": "Base tool enhancement - override builtin bash tool: foreground delegates to pi official factory, incremental background mode (design: docs/design/base-tool-enhance.md)",
+  "version": "0.5.3",
+  "description": "Base tool enhancement - override builtin bash tool: foreground delegates to pi official factory, incremental background mode (design decisions documented in source comments)",
   "type": "module",
   "main": "src/index.ts",
   "xyz-agent": {
@@ -28,10 +28,11 @@
     "skills/"
   ],
   "dependencies": {
-    "@xyz-agent/extension-protocol": "0.9.0",
+    "@xyz-agent/extension-protocol": "0.11.0",
+    "@zhushanwen/pi-ext-guards": "0.4.0",
     "@zhushanwen/pi-extension-logger": "0.6.0",
     "@zhushanwen/pi-file-lock": "0.4.0",
-    "@zhushanwen/pi-llm-shared": "0.7.0"
+    "@zhushanwen/pi-llm-shared": "0.8.0"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.1.9",
@@ -40,7 +41,7 @@
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.84.4",
     "typebox": "*",
-    "@zhushanwen/pi-pending-notifications": "0.7.0"
+    "@zhushanwen/pi-pending-notifications": "0.7.2"
   },
   "peerDependenciesMeta": {
     "@zhushanwen/pi-pending-notifications": {

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

@@ -17,19 +17,24 @@ vi.mock("@earendil-works/pi-coding-agent", () => ({
 	getAgentDir: () => dataDirRef.dir,
 }));
 
-// kill-tree 转发真实杀 + 记录调用（timeout 分支断言 killProcessTree 被调）
+// 进程原语（ext-simplify-13 后单点在 protocol 子出口）转发真实杀 + 记录调用
+//（timeout 分支断言 killProcessTree 被调）
 const { killTreeCalls } = vi.hoisted(() => ({ killTreeCalls: [] as number[] }));
-vi.mock("../kill-tree.ts", async (importOriginal) => {
-	const orig = await importOriginal<typeof import("../kill-tree.ts")>();
+vi.mock("@xyz-agent/extension-protocol/background-task", async (importOriginal) => {
+	const orig = await importOriginal<
+		typeof import("@xyz-agent/extension-protocol/background-task")
+	>();
 	return {
 		...orig,
-		killProcessTree: (pid: number): void => {
+		killProcessTree: (pid: number, onFallback?: (step: string, err: unknown) => void): void => {
 			killTreeCalls.push(pid);
-			orig.killProcessTree(pid);
+			orig.killProcessTree(pid, onFallback);
 		},
 	};
 });
 
+import { isPidAlive } from "@xyz-agent/extension-protocol/background-task";
+
 import { createBashKillToolDefinition } from "../bash-kill-tool.ts";
 import { createBashOutputToolDefinition } from "../bash-output-tool.ts";
 import { handleTaskExit, refreshPiReference, resetNotifyForTest } from "../background/notify.ts";
@@ -39,7 +44,6 @@ import type { RegistryEntry } from "../background/types.ts";
 import { DEFAULT_MAX_CONCURRENT_BACKGROUND, spawnBackgroundTask } from "../background/spawn-background.ts";
 import { clearTaskStoreForTest, getActiveTasks, getTask, markKillingIntent } from "../background/task-store.ts";
 import { reapBackgroundTasksNow, resetProcessExitGuardForTest } from "../background/process-exit-guard.ts";
-import { isPidAlive } from "../kill-tree.ts";
 
 const DATA_DIR = mkdtempSync(join(tmpdir(), "bte-data-"));
 dataDirRef.dir = DATA_DIR;

package/src/__tests__/index.test.ts

@@ -121,11 +121,9 @@ describe("session_start chain: reconcile (M3, reap sunk into runtime by u-bte-re
 					status: "cancelled",
 				}),
 			);
-			// 对账之外尽力补一次 emit（幂等兜底，纯日志性质；失败无害）
-			expect(pi.events.emit).toHaveBeenCalledWith("pending:unregister", {
-				id: "bt-1700000000-idx001",
-				reason: "cancelled",
-			});
+			// 尽力补 emit 已随 ext-simplify-13 删除（恒 no-op 死路径）——对账后不得有任何
+			// bus emit，appendEntry 即唯一权威路径
+			expect(pi.events.emit).not.toHaveBeenCalled();
 		} finally {
 			rmSync(dataDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
 			dataDirRef.dir = "/tmp/bte-fake-agent-dir";

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

@@ -1,6 +1,6 @@
 // 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
+// 语义（实施单元 u-bte-remove，设计 docs/architecture/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 累积的真实形态）

package/src/__tests__/notify.test.ts

@@ -8,7 +8,7 @@ import { join } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
-import { killProcessTree } from "../kill-tree.ts";
+import { killProcessTree } from "@xyz-agent/extension-protocol/background-task";
 import {
 	BACKGROUND_BASH_CUSTOM_TYPE,
 	buildNotificationContent,

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

@@ -1,14 +1,19 @@
 // src/__tests__/pending-reconcile.test.ts —— M3 session_start 对账单元（§3.5 接入细则 4）：
-// 差集收集 / 三类僵尸场景 appendEntry 权威路径 + 尽力 emit / 活任务与缺条目保守跳过
+// bt- 差集（protocol collectActivePendingIds 单点消费）/ 三类僵尸场景 appendEntry
+// 权威路径（唯一写路径，无 emit）/ 活任务与缺条目保守跳过
 import { spawnSync } from "node:child_process";
 import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
+import {
+	BACKGROUND_TASK_ID_PREFIX,
+	collectActivePendingIds,
+	mapReasonToStatus,
+} from "@xyz-agent/extension-protocol";
 import { afterEach, describe, expect, it, vi } from "vitest";
 
 import {
-	collectUnsettledTaskIds,
 	reconcilePendingEntries,
 	type ReconcilePi,
 } from "../background/pending-reconcile.ts";
@@ -18,9 +23,13 @@ import type { RegistryEntry } from "../background/types.ts";
 const DATA_DIR = mkdtempSync(join(tmpdir(), "bte-reconcile-"));
 const SESSION_ID = "sess-reconcile";
 
-function createMockPi(overrides: Partial<Pick<ReconcilePi, "appendEntry">> = {}): ReconcilePi {
+function createMockPi(overrides: Partial<Pick<ReconcilePi, "appendEntry">> = {}): ReconcilePi & {
+	events: { emit: ReturnType<typeof vi.fn> };
+} {
 	return {
 		appendEntry: vi.fn(),
+		// emit 路径已随 ext-simplify-13 删除（恒 no-op 死路径）：events spy 仅用于
+		// 断言实现不再触达 bus emit
 		events: { emit: vi.fn() },
 		...overrides,
 	};
@@ -56,41 +65,60 @@ afterEach(() => {
 	vi.restoreAllMocks();
 });
 
-describe("collectUnsettledTaskIds (bt- prefixed register/unregister diff)", () => {
+describe("bt- diff via protocol collectActivePendingIds (single-source diff core)", () => {
+	// 差集本体单点在 protocol pending-entries（ext-simplify-13 D3，与 pending 守卫
+	// 判据同源）；此处锁定 bte 对账消费面的语义（idPrefix = BACKGROUND_TASK_ID_PREFIX）
 	it("collects bt- registers without a matching unregister", () => {
-		const ids = collectUnsettledTaskIds([
-			registerEntry("bt-a"),
-			registerEntry("bt-b"),
-			{ customType: "pending:unregister", data: { id: "bt-b", reason: "completed" } },
-		]);
+		const ids = collectActivePendingIds(
+			[
+				registerEntry("bt-a"),
+				registerEntry("bt-b"),
+				{ customType: "pending:unregister", data: { id: "bt-b", reason: "completed" } },
+			],
+			{ idPrefix: BACKGROUND_TASK_ID_PREFIX },
+		);
 		expect([...ids]).toEqual(["bt-a"]);
 	});
 
 	it("ignores non-bt ids (subagent bg-/run- namespace not ours)", () => {
-		const ids = collectUnsettledTaskIds([
-			registerEntry("bg-1"),
-			registerEntry("run-x-1"),
-			registerEntry("bt-a"),
-		]);
+		const ids = collectActivePendingIds(
+			[registerEntry("bg-1"), registerEntry("run-x-1"), registerEntry("bt-a")],
+			{ idPrefix: BACKGROUND_TASK_ID_PREFIX },
+		);
 		expect([...ids]).toEqual(["bt-a"]);
 	});
 
 	it("dedupes repeated registers and tolerates malformed entries", () => {
-		const ids = collectUnsettledTaskIds([
-			null,
-			undefined,
-			{ customType: "pending:register" }, // data 缺失
-			{ customType: "pending:register", data: { id: 42 } }, // id 非字符串
-			registerEntry("bt-a"),
-			registerEntry("bt-a"),
-			{ customType: "other" },
-		]);
+		const ids = collectActivePendingIds(
+			[
+				null,
+				undefined,
+				{ customType: "pending:register" }, // data 缺失
+				{ customType: "pending:register", data: { id: 42 } }, // id 非字符串
+				registerEntry("bt-a"),
+				registerEntry("bt-a"),
+				{ customType: "other" },
+			],
+			{ idPrefix: BACKGROUND_TASK_ID_PREFIX },
+		);
 		expect([...ids]).toEqual(["bt-a"]);
 	});
+
+	it("register→unregister→register same id stays settled (global cancellation, §5.4①)", () => {
+		const ids = collectActivePendingIds(
+			[
+				registerEntry("bt-a"),
+				{ customType: "pending:unregister", data: { id: "bt-a", reason: "completed" } },
+				registerEntry("bt-a"),
+			],
+			{ idPrefix: BACKGROUND_TASK_ID_PREFIX },
+		);
+		expect(ids.size).toBe(0);
+	});
 });
 
 describe("reconcile scenario ①: graceful-exit leftover (registry exited, entry never written)", () => {
-	it("appends pending:unregister {id, reason, status} matching pending-notifications entry shape + best-effort emit", () => {
+	it("appends pending:unregister {id, reason, status} matching pending-notifications entry shape", () => {
 		const entry = makeRegistryEntry({
 			taskId: "bt-1700000000-zomb01",
 			state: "exited",
@@ -109,11 +137,6 @@ describe("reconcile scenario ①: graceful-exit leftover (registry exited, entry
 			reason: "completed",
 			status: "completed",
 		});
-		// emit 形态 {id, reason}（status 由 listener mapReasonToStatus 计算）
-		expect(pi.events.emit).toHaveBeenCalledWith("pending:unregister", {
-			id: entry.taskId,
-			reason: "completed",
-		});
 	});
 
 	it("maps exited reason/exitCode through the same mapping as the exit edge", () => {
@@ -127,14 +150,43 @@ describe("reconcile scenario ①: graceful-exit leftover (registry exited, entry
 			writeRegistryEntry(getRegistryPath(DATA_DIR, SESSION_ID), entry);
 			const pi = createMockPi();
 			reconcilePendingEntries(pi, DATA_DIR, SESSION_ID, [registerEntry(entry.taskId)]);
-			expect(pi.appendEntry).toHaveBeenCalledWith(
-				"pending:unregister",
-				{ id: entry.taskId, reason: expectedReason, status: expectedReason },
-			);
+			// status 断言按「权威映射(reason)」而非 reason 本身表述（D10：identity 假设消除）
+			expect(pi.appendEntry).toHaveBeenCalledWith("pending:unregister", {
+				id: entry.taskId,
+				reason: expectedReason,
+				status: mapReasonToStatus(expectedReason),
+			});
 		}
 	});
 });
 
+describe("entry status maps via protocol mapReasonToStatus (D10 single-source, identity assumption removed)", () => {
+	// bte 写侧 status 与 pending-notifications unregister listener 同引 protocol 单点
+	// （ext-simplify-17 D10）——原 status: reason 的 identity 假设在非 identity reason
+	// （budget_limited→failed 等）上会静默漂移，映射表演化时两写侧不再可能分叉。
+	// settle 产域四值当前恰为 identity 映射，但断言面按「status === mapReasonToStatus
+	// (reason)」表述：映射表日后改任何一行的口径，本组用例随实现同源自洽。
+	it("appended status equals the authoritative mapping for every reason the settle path can produce", () => {
+		// settledPendingReason 全产域：exited 三分支（natural/timeout/killed|process-exit
+		// 经 toPendingReason）+ orphaned/判死兜底 cancelled + reason 缺失防御分支
+		const settleReasons = ["completed", "failed", "time_limited", "cancelled"] as const;
+		for (const reason of settleReasons) {
+			expect(mapReasonToStatus(reason)).toBe(reason); // 当前口径下四值均为 identity 映射
+		}
+	});
+
+	it("non-identity reasons exist in the authoritative mapping — identity assumption is provably gone", () => {
+		// 这些 reason 上 status ≠ reason 本身：若写侧仍持 identity 假设（status: reason），
+		// settle 产域将来扩展到这些值时落盘 entry 会静默漂移；现实现单点映射自动正确
+		expect(mapReasonToStatus("budget_limited")).toBe("failed");
+		expect(mapReasonToStatus("interrupted")).toBe("aborted");
+		expect(mapReasonToStatus("interrupted-by-restart")).toBe("aborted");
+		expect(mapReasonToStatus("interrupted-by-parent")).toBe("aborted");
+		expect(mapReasonToStatus("reopened")).toBe("completed");
+		expect(mapReasonToStatus("some-future-reason")).toBe("completed");
+	});
+});
+
 describe("reconcile scenario ②: collector-only orphan (registry orphaned, session file untouched)", () => {
 	it("appends unregister with cancelled for orphaned entries", () => {
 		const entry = makeRegistryEntry({ state: "orphaned" });
@@ -214,6 +266,19 @@ describe("conservative no-op paths", () => {
 	});
 });
 
+describe("best-effort emit removed (ext-simplify-13 D5: appendEntry is the sole authority)", () => {
+	it("reconcile never touches pi.events (the emit path is deleted, not just disabled)", () => {
+		const entry = makeRegistryEntry({ state: "orphaned" });
+		writeRegistryEntry(getRegistryPath(DATA_DIR, SESSION_ID), entry);
+		const pi = createMockPi();
+
+		reconcilePendingEntries(pi, DATA_DIR, SESSION_ID, [registerEntry(entry.taskId)]);
+
+		expect(pi.appendEntry).toHaveBeenCalledTimes(1);
+		expect(pi.events.emit).not.toHaveBeenCalled();
+	});
+});
+
 describe("appendEntry failure tolerance", () => {
 	it("one appendEntry throw does not block the remaining zombie (count only successful)", () => {
 		const first = makeRegistryEntry({ taskId: "bt-1700000000-zomb01", state: "orphaned" });

package/src/__tests__/subagent-guard.test.ts

@@ -0,0 +1,29 @@
+// src/__tests__/subagent-guard.test.ts
+//
+// subagent-guard 判据钉值（ext-simplify-17 D4 重锚定后）：
+//   - XYZ_AGENT_SUBAGENT === "1" 命中（引擎 spawn 链恒注入的现行标记）
+//   - 其他值 / 缺失不命中（顶层会话不误降级，background 正常后台化）
+//
+// [HISTORICAL] 对照（D4 重锚前的旧行为）：旧判据查 PI_SUBAGENT_* 身份键族两枚、
+// 任一存在即命中——该键族已无写入方，旧判据实际恒 false（降级从未生效）。旧键
+// 不命中的钉值在 ext-guards predicates 测试（谓词实现方领地），此处只钉 bte
+// 消费面的现行语义。
+
+import { describe, expect, it } from "vitest";
+
+import { isSubagentProcess } from "../background/subagent-guard.ts";
+
+describe("isSubagentProcess（subagent-guard，D4 重锚后）", () => {
+	it("XYZ_AGENT_SUBAGENT=1 命中（引擎链 subagent → D14 background 降级前提恢复）", () => {
+		expect(isSubagentProcess({ XYZ_AGENT_SUBAGENT: "1" })).toBe(true);
+	});
+
+	it("值非 \"1\" 不命中", () => {
+		expect(isSubagentProcess({ XYZ_AGENT_SUBAGENT: "0" })).toBe(false);
+		expect(isSubagentProcess({ XYZ_AGENT_SUBAGENT: "" })).toBe(false);
+	});
+
+	it("缺失不命中（顶层会话 → background 正常后台化，guard 不误命中）", () => {
+		expect(isSubagentProcess({})).toBe(false);
+	});
+});

package/src/background/notify.ts

@@ -27,6 +27,7 @@
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { toErrorMessage } from "@zhushanwen/pi-ext-guards";
 import { getLogger } from "@zhushanwen/pi-extension-logger";
 
 import type { BackgroundTask, BackgroundTaskEndReason } from "./types.ts";
@@ -107,7 +108,7 @@ export function emitPendingRegister(task: BackgroundTask): void {
 		pi.events.emit("pending:register", { id: task.taskId, type: "bash", name });
 	} catch (err) {
 		logger.warn("pending:register emit failed (stale bus?); task unaffected", {
-			detail: { taskId: task.taskId, err: err instanceof Error ? err.message : String(err) },
+			detail: { taskId: task.taskId, err: toErrorMessage(err) },
 		});
 	}
 }
@@ -130,7 +131,7 @@ export function emitPendingUnregister(
 		pi.events.emit("pending:unregister", { id: taskId, reason: toPendingReason(reason, exitCode) });
 	} catch (err) {
 		logger.warn("pending:unregister emit failed (stale bus?); reconcile covers on next session_start", {
-			detail: { taskId, err: err instanceof Error ? err.message : String(err) },
+			detail: { taskId, err: toErrorMessage(err) },
 		});
 	}
 }
@@ -160,7 +161,7 @@ function sendTaskFinishedMessage(task: BackgroundTask): void {
 		logger.warn("background task notify sendMessage failed; poll continues", {
 			detail: {
 				taskId: task.taskId,
-				err: err instanceof Error ? err.message : String(err),
+				err: toErrorMessage(err),
 			},
 		});
 	}

package/src/background/output-tail.ts

@@ -1,84 +1,28 @@
 /**
- * 输出文件 tail 读取（D7：输出落文件不占内存，查询时按需读尾部）。
+ * 输出文件 tail 读取薄壳（D7：输出落文件不占内存，查询时按需读尾部）。
  *
- * 截断规则与 pi 内置 bash 一致：末尾 2000 行 / 50KB 先到为准（bash.js truncate.ts
- * DEFAULT_MAX_LINES/DEFAULT_MAX_BYTES）。实现从文件末尾按字节窗口读（不整读大文件，
- * O(maxBytes) 而非 O(fileSize)）。
+ * tail 算法单点在 extension-protocol（ext-simplify-13：与 runtime 桌面预览侧共用，
+ * 原两份同构实现签名已实际漂移）。本模块只保留 bte 私有需求：
+ *  - 50KB / 2000 行截断上限常量（pi 内置 bash 同款，bash.js truncate.ts）——口径是
+ *    本包产品决策，由调用方（bash-output-tool）传参给 protocol 原语
+ *  - readTailSummary：exit 边沿的 tail 摘要（存条目 / M3 通知用）
  */
 
-import { openSync, readSync, closeSync, statSync } from "node:fs";
-
-import { getLogger } from "@zhushanwen/pi-extension-logger";
-
-const logger = getLogger("base-tool-enhance");
+import { readOutputTail as readOutputTailPrimitive } from "@xyz-agent/extension-protocol/background-task";
 
 /** pi 内置 bash 同款截断上限（last 2000 lines / 50KB = 51200 bytes，先到为准）。 */
 export const TAIL_MAX_LINES = 2000;
 export const TAIL_MAX_BYTES = 51_200;
-/** 字节窗口余量：截窗口可能吞掉首行前半，余量降低残行概率。 */
-const TAIL_WINDOW_MARGIN_BYTES = 64;
 /** exit 边沿 tail 摘要参数（存条目/M3 通知用）。 */
 const SUMMARY_TAIL_LINES = 5;
 const SUMMARY_MAX_CHARS = 800;
 
-export interface TailResult {
-	output: string;
-	/** 读取窗口被截断（内容超上限）时 true。 */
-	truncated: boolean;
-}
-
-/**
- * 读文件尾部（行/字节双上限）。文件不存在/不可读返回 undefined——bash_output 对
- * 此降级为 {output:"<lost>"} 不崩溃（§3.6）。
- */
-export function readOutputTail(
-	outputFile: string,
-	maxLines: number = TAIL_MAX_LINES,
-	maxBytes: number = TAIL_MAX_BYTES,
-): TailResult | undefined {
-	let size: number;
-	try {
-		size = statSync(outputFile).size;
-	} catch {
-		return undefined;
-	}
-	// 字节窗口从末尾取 maxBytes + 余量（截窗口可能吞掉首行前半，余量降低概率）
-	const windowSize = Math.min(size, maxBytes + TAIL_WINDOW_MARGIN_BYTES);
-	const buffer = Buffer.alloc(windowSize);
-	let fd: number | undefined;
-	try {
-		fd = openSync(outputFile, "r");
-		readSync(fd, buffer, 0, windowSize, size - windowSize);
-	} catch {
-		return undefined;
-	} finally {
-		if (fd !== undefined) {
-			try {
-				closeSync(fd);
-			} catch (err) {
-				// 已读完内容，close 失败不影响结果，仅留诊断
-				logger.debug("output tail close failed", {
-					detail: { outputFile, err: err instanceof Error ? err.message : String(err) },
-				});
-			}
-		}
-	}
-	const text = buffer.toString("utf8");
-	const lines = text.split("\n");
-	// 窗口起点可能落在行中间：首行是残行时丢弃（它必然不完整）
-	const firstLineIsPartial = windowSize < size && lines.length > 0;
-	const effectiveLines = firstLineIsPartial ? lines.slice(1) : lines;
-	const byteTruncated = size > maxBytes;
-	const shown = effectiveLines.slice(-maxLines).join("\n");
-	return { output: shown, truncated: byteTruncated || effectiveLines.length > maxLines };
-}
-
 /**
  * 轮询器 exit 边沿的 tail 摘要（存进条目、M3 通知用）：末尾几行的紧凑文本。
  */
 export function readTailSummary(outputFile: string, maxChars: number = SUMMARY_MAX_CHARS): string | undefined {
-	const tail = readOutputTail(outputFile, SUMMARY_TAIL_LINES, maxChars);
+	const tail = readOutputTailPrimitive(outputFile, { maxLines: SUMMARY_TAIL_LINES, maxBytes: maxChars });
 	if (tail === undefined) return undefined;
-	const compact = tail.output.trim();
+	const compact = tail.text.trim();
 	return compact.length > 0 ? compact.slice(-maxChars) : undefined;
 }

package/src/background/pending-reconcile.ts

@@ -8,14 +8,18 @@
  *  ③ fork 后任务完成通知写进新 session，旧 session 文件的 register 成僵尸。
  *
  * 收尾写法（权威路径）：直接 pi.appendEntry("pending:unregister", {id, reason,
- * status})——**不走 bus emit 作为权威**：appendEntry 不依赖 listener 存活，两个
- * extension 的加载/派发顺序（CLI --extension 顺序用户可控）无保障，顺序反转时
- * emit 无人接收、对账失效。差集消费方 goal 从持久化 entries 算差集
- * （agent-end.ts getEntries()），appendEntry 同步入账（pi dist 实证）对守卫直接
- * 生效，无不一致窗口。appendEntry 之外尽力补一次 emit（幂等兜底，纯日志性质：
- * pending-notifications 的 unregister listener 落盘前置判断 isPendingActive 对
- * getEntries() 现算——其内存 registry/rebuild 已随 ext-simplify-12 删除，emit
- * 到达时该 id 已注销即跳过，失败无害）。
+ * status})——**appendEntry 即唯一权威路径**：appendEntry 同步入账（pi dist 实证）
+ * 且不依赖 listener 存活，差集消费方 goal 从持久化 entries 算差集
+ * （agent-end.ts getEntries()），对守卫直接生效，无不一致窗口。（尽力补 emit 的
+ * 第二写路径已随 ext-simplify-13 删除：pending unregister listener 的落盘前置
+ * isPendingActive 对 entries 现算——其内存 registry/rebuild 已随 ext-simplify-12
+ * 删除——而对账 appendEntry 同步入账先于 emit 执行，emit 到达时该 id 必已注销
+ * = 恒 no-op 死路径。）
+ *
+ * 差集判据单点（ext-simplify-13）：collectActivePendingIds（protocol
+ * pending-entries 模块，与 pending-notifications 守卫判据同源）+ bt- 前缀过滤；
+ * 本地差集副本已删除。task_id 前缀亦消费 protocol 契约常量
+ * BACKGROUND_TASK_ID_PREFIX（§2.3，区别于 subagent-workflow 的 bg-/run-）。
  *
  * 终态判据：registry state ∈ {exited, orphaned}，或（state=running/killing 且
  * kill(pid,0) 判死：收殓/写盘失败遗留的 running 条目按事实终态处理）。
@@ -27,24 +31,26 @@
  * 语义覆盖孤儿终态由 runtime 异步写入的时序窗口。
  */
 
+import {
+	BACKGROUND_TASK_ID_PREFIX,
+	collectActivePendingIds,
+	mapReasonToStatus,
+} from "@xyz-agent/extension-protocol";
+import { isPidAlive } from "@xyz-agent/extension-protocol/background-task";
+import { toErrorMessage } from "@zhushanwen/pi-ext-guards";
 import { getLogger } from "@zhushanwen/pi-extension-logger";
 
-import { isPidAlive } from "../kill-tree.ts";
 import { toPendingReason } from "./notify.ts";
 import { getRegistryPath, readRegistry } from "./registry.ts";
 import { isActiveState, isTerminalState, type RegistryEntry } from "./types.ts";
 
 const logger = getLogger("base-tool-enhance");
 
-/** 本包 task_id 前缀（§2.3，区别于 subagent-workflow 的 bg-/run-）。 */
-export const BTE_TASK_ID_PREFIX = "bt-";
-
 /**
  * 对账依赖的最小 pi 面（结构兼容 ExtensionAPI 的子集；测试注入不造完整 pi）。
  */
 export interface ReconcilePi {
 	appendEntry(customType: string, data?: unknown): void;
-	events: { emit(channel: string, data: unknown): void };
 }
 
 /** 对账结果（日志 + 测试断言面）。 */
@@ -55,48 +61,9 @@ export interface ReconcileResult {
 	skipped: string[];
 }
 
-/** entries 的最小可识别形状（duck-typed，与 pending-notifications state.ts EntryLike 同式）。 */
-interface EntryLike {
-	customType?: string;
-	data?: { id?: unknown } | null;
-}
-
-function readEntryId(raw: unknown): string | undefined {
-	if (!raw || typeof raw !== "object") return undefined;
-	const entry = raw as EntryLike;
-	const id = entry.data?.id;
-	return typeof id === "string" ? id : undefined;
-}
-
-/**
- * 差集：bt- 前缀 pending:register 且无对应 pending:unregister 的 id 集合。
- * 只认 bt- 前缀——workflow/subagent 的 register 不归本包对账（差集算法与
- * pending-notifications countActiveFromEntries 同构：unregister 全局抵消 + register
- * 去重，id 全局唯一前提）。
- */
-export function collectUnsettledTaskIds(entries: unknown[]): Set<string> {
-	const unregistered = new Set<string>();
-	for (const raw of entries) {
-		if (!raw || typeof raw !== "object") continue;
-		if ((raw as EntryLike).customType !== "pending:unregister") continue;
-		const id = readEntryId(raw);
-		if (id !== undefined && id.startsWith(BTE_TASK_ID_PREFIX)) unregistered.add(id);
-	}
-	const active = new Set<string>();
-	for (const raw of entries) {
-		if (!raw || typeof raw !== "object") continue;
-		if ((raw as EntryLike).customType !== "pending:register") continue;
-		const id = readEntryId(raw);
-		if (id === undefined || !id.startsWith(BTE_TASK_ID_PREFIX)) continue;
-		if (unregistered.has(id) || active.has(id)) continue;
-		active.add(id);
-	}
-	return active;
-}
-
 /**
  * 对账主体（同步：readRegistry / kill(pid,0) / appendEntry 均同步，session_start
- * 链内毫秒级完成）。每个僵尸任务 appendEntry 一次 + 尽力 emit 一次。
+ * 链内毫秒级完成）。每个僵尸任务 appendEntry 一次（唯一权威写路径）。
  */
 export function reconcilePendingEntries(
 	pi: ReconcilePi,
@@ -105,7 +72,7 @@ export function reconcilePendingEntries(
 	entries: unknown[],
 ): ReconcileResult {
 	const result: ReconcileResult = { reconciled: 0, skipped: [] };
-	const unsettled = collectUnsettledTaskIds(entries);
+	const unsettled = collectActivePendingIds(entries, { idPrefix: BACKGROUND_TASK_ID_PREFIX });
 	if (unsettled.size === 0) return result;
 
 	const registry = readRegistry(getRegistryPath(dataDir, sessionId));
@@ -125,23 +92,20 @@ export function reconcilePendingEntries(
 		}
 		const pendingReason = settledPendingReason(entry);
 		try {
-			pi.appendEntry("pending:unregister", { id, reason: pendingReason, status: pendingReason });
+			// status 经 protocol mapReasonToStatus 单点映射（ext-simplify-17 D10）：与
+			// pending-notifications unregister listener 同一函数——原 status === reason 的
+			// identity 假设在非 identity reason（budget_limited→failed 等）上会静默漂移
+			pi.appendEntry("pending:unregister", {
+				id,
+				reason: pendingReason,
+				status: mapReasonToStatus(pendingReason),
+			});
 		} catch (err) {
 			logger.warn("reconcile appendEntry failed; retry on next session_start", {
-				detail: { id, err: err instanceof Error ? err.message : String(err) },
+				detail: { id, err: toErrorMessage(err) },
 			});
 			continue;
 		}
-		// 尽力补 emit（幂等兜底，纯日志性质：listener 落盘前置 isPendingActive 对
-		// entries 现算，该 id 已注销即跳过——appendEntry 同步入账已无不一致窗口；
-		// 失败无害）
-		try {
-			pi.events.emit("pending:unregister", { id, reason: pendingReason });
-		} catch (err) {
-			logger.debug("reconcile best-effort emit failed (harmless)", {
-				detail: { id, err: err instanceof Error ? err.message : String(err) },
-			});
-		}
 		result.reconciled++;
 	}
 	if (result.reconciled > 0) {
@@ -159,10 +123,10 @@ function isTerminalByRegistry(entry: RegistryEntry): boolean {
 }
 
 /**
- * 收尾 reason/status 映射：
+ * 收尾 reason 映射（reason→status 的第二跳在写点经 protocol mapReasonToStatus 单点）：
  *  - exited：按条目 reason/exitCode 走 toPendingReason（与 exit 边沿 emit 同一映射，
- *    两路径写出的 entry 语义一致）；reason 缺失按 pending mapReasonToStatus 的
- *    default=completed 语义处理（防御分支，正常路径 finalize 必写 reason）
+ *    两路径写出的 entry 语义一致）；reason 缺失按 cancelled 处理（防御分支，正常路径
+ *    finalize 必写 reason）
  *  - orphaned / running+判死：cancelled（任务非自身成败地终止/消失）
  */
 function settledPendingReason(entry: RegistryEntry): "completed" | "failed" | "time_limited" | "cancelled" {

package/src/background/poller.ts

@@ -13,7 +13,8 @@
  * 可查、对账可补），不加同步握手。
  */
 
-import { isPidAlive } from "../kill-tree.ts";
+import { isPidAlive } from "@xyz-agent/extension-protocol/background-task";
+
 import { readTailSummary } from "./output-tail.ts";
 import { readRegistry, taskToRegistryEntry, writeRegistryEntry } from "./registry.ts";
 import { finalizeTask, getActiveTasks } from "./task-store.ts";