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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zhushanwen/pi-base-tool-enhance",
-  "version": "0.5.1",
-  "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.8.2",
-    "@zhushanwen/pi-extension-logger": "0.4.1",
-    "@zhushanwen/pi-file-lock": "0.2.1",
-    "@zhushanwen/pi-llm-shared": "0.6.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.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.6.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（listener 内存视图同步，失败无害）
-			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,27 +1,27 @@
 // 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 累积的真实形态）
 //  - 触发面消失：reaper.ts 模块文件已删除（文件级断言，见首条用例）+ 维护链不再触发
-//    全局文件锁（withFileLock——原 reapOrphanedTasks 的 reaper.lock 路径）
+//    全局文件锁（原 reapOrphanedTasks 的 reaper.lock 路径随模块删除一并消失）
 //  - 入口无条件 debug 日志按派发次数出现，detail 仅含 reason（reapSkipped 字段
 //    随 reap 调用移除，S6 观测通道语义更新）
-// 断言方式：reconcile / logger / file-lock 全部间谍注入，观察调用次数与参数。
+// 断言方式：reconcile / logger 间谍注入观察调用次数与参数；file-lock 为 mock
+// 缺键守卫 + withFileLockSync throw 哨兵（不计数）。
 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 } =
+const { reconcileMock, loggerMock, officialBashFactoryMock, dataDirRef } =
 	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", () => ({
@@ -31,10 +31,10 @@ vi.mock("@earendil-works/pi-coding-agent", () => ({
 vi.mock("@zhushanwen/pi-extension-logger", () => ({
 	getLogger: () => loggerMock,
 }));
-// 全局扫描探针：withFileLock 是原 reapOrphanedTasks 持 reaper.lock 的唯一锁路径
-// （registry 写走的是 withFileLockSync）——维护链触发它 = 全局扫描回流
+// 守卫形态 = mock 工厂缺键：包入口已删除的 async 锁导出不在工厂注册——维护链若
+// 误回流，对已删导出的任何访问（调用与 typeof 均计）即抛错（vitest mock 缺键语义；
+// 模块导入本身不抛）。withFileLockSync 哨兵保留：registry 写路径误入维护链即抛
 vi.mock("@zhushanwen/pi-file-lock", () => ({
-	withFileLock: withFileLockMock,
 	withFileLockSync: vi.fn(() => {
 		throw new Error("unexpected registry write in maintenance chain");
 	}),
@@ -86,7 +86,6 @@ beforeEach(() => {
 		parameters: {},
 		execute: vi.fn(),
 	});
-	withFileLockMock.mockReset();
 	loggerMock.debug.mockClear();
 	loggerMock.warn.mockClear();
 	loggerMock.error.mockClear();
@@ -118,8 +117,7 @@ describe("session_start maintenance chain after reap sink (u-bte-remove)", () =>
 		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();
+		// 无全局扫描回流：误触发已删锁导出的任何访问会被 mock 缺键直接抛错（守卫见工厂注释），无告警
 		expect(loggerMock.warn).not.toHaveBeenCalled();
 	});
 

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;
 }