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

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

@@ -27,9 +27,10 @@
  * 本单元不管。
  */
 
+import { killProcessTree } from "@xyz-agent/extension-protocol/background-task";
+import { toErrorMessage } from "@zhushanwen/pi-ext-guards";
 import { getLogger } from "@zhushanwen/pi-extension-logger";
 
-import { killProcessTree } from "../kill-tree.ts";
 import { emitPendingUnregister } from "./notify.ts";
 import { stopPoller } from "./poller.ts";
 import { taskToRegistryEntry, writeRegistryEntry } from "./registry.ts";
@@ -76,11 +77,16 @@ export function reapBackgroundTasksNow(): void {
 	stopPoller();
 	for (const task of getActiveTasks()) {
 		try {
-			killProcessTree(task.pid);
+			// 回退路径诊断经 onFallback 注入 logger 适配（ext-simplify-13 D2）
+			killProcessTree(task.pid, (step, err) =>
+				logger.debug(step, {
+					detail: { pid: task.pid, err: toErrorMessage(err) },
+				}),
+			);
 		} catch (err) {
 			// 单条 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) },
+				detail: { taskId: task.taskId, pid: task.pid, err: toErrorMessage(err) },
 			});
 		}
 		const finalized = finalizeTask(task.taskId, {

package/src/background/registry.ts

@@ -6,41 +6,44 @@
  * 判定依据（u-bte-remove 后 = xyz-agent runtime background-task-reaper），M2 只负责
  * 写入。
  *
+ * 行为原语单点（ext-simplify-13）：解析防御 / corrupt 隔离 / 原子写 / 序列化 /
+ * 终态 LRU 裁剪自 @xyz-agent/extension-protocol background-task 子出口引入——此前
+ * 本地实现与 runtime 侧逐字同构、靠注释对齐；本模块只保留 bte 形态薄壳：Map 投影
+ * readRegistry 与锁内 RMW 写壳。
+ *
  * 写入协议：
- *  - 原子写 temp+rename（tmp 名带 pid+随机段防并发碰撞，llm-shared saveConfig 范式）
+ *  - 原子写 temp+rename、损坏读取防御（§3.6 重命名 .corrupt 保留现场 + 按空表
+ *    重建）、终态条目 LRU 上限 50 均由 protocol 原语承担；诊断日志（corrupt 隔离
+ *    warn 等）经 onLog 注入本包 logger，落盘通道不变
  *  - 锁内 RMW（@zhushanwen/pi-file-lock withFileLockSync）——同 sessionId 目录可能
  *    被桌面端 ephemeral 附着进程与发起进程并发写，跨进程互斥只依赖同一 lockfile
  *    （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 { join } from "node:path";
 
+// 契约常量（LRU 上限）走 index 出口（background-task.ts 契约面）；行为原语走
+// background-task 子出口（含 node 内建依赖，不进 index——renderer/core 零触达）
+import { MAX_TERMINAL_REGISTRY_ENTRIES } from "@xyz-agent/extension-protocol";
 import {
-	BACKGROUND_TASK_REGISTRY_VERSION,
-	type BackgroundTaskRegistryFile,
-	MAX_TERMINAL_REGISTRY_ENTRIES,
-} from "@xyz-agent/extension-protocol";
+	atomicWriteRegistry,
+	readRegistry as readRegistryEntries,
+	serializeRegistryFile,
+	trimTerminalEntries,
+	type RegistryFileLogFn,
+} from "@xyz-agent/extension-protocol/background-task";
+import { toErrorMessage } from "@zhushanwen/pi-ext-guards";
 import { getLogger } from "@zhushanwen/pi-extension-logger";
 import { withFileLockSync } from "@zhushanwen/pi-file-lock";
 
-import { isTerminalState, type BackgroundTask, type RegistryEntry } from "./types.ts";
+import type { BackgroundTask, RegistryEntry } from "./types.ts";
 
 const logger = getLogger("base-tool-enhance");
 
-const JSON_INDENT = 2;
-// tmp 随机段参数（llm-shared uniqueTmpPath 同款：36 进制随机串，跳过 "0." 前缀）
-const TMP_RADIX = 36;
-const TMP_SLICE_START = 2;
-const TMP_SLICE_END = 10;
+/** protocol registry 原语 → 本包 logger 适配（corrupt 隔离 warn 是排障生命线）。 */
+const registryFileLog: RegistryFileLogFn = (level, event, detail) => logger[level](event, { detail });
 
 export function getBaseToolEnhanceDir(dataDir: string): string {
 	return join(dataDir, "base-tool-enhance");
@@ -51,78 +54,13 @@ export function getRegistryPath(dataDir: string, sessionId: string): string {
 }
 
 /**
- * 最低限度形状校验：核心标识字段缺失即整条丢弃（不因单条脏数据报废全表）。
- */
-function isValidRegistryEntry(item: unknown): item is RegistryEntry {
-	if (typeof item !== "object" || item === null) return false;
-	const e = item as Record<string, unknown>;
-	return (
-		typeof e.taskId === "string" &&
-		typeof e.pid === "number" &&
-		typeof e.command === "string" &&
-		typeof e.outputFile === "string" &&
-		typeof e.startedAt === "number" &&
-		typeof e.state === "string" &&
-		typeof e.ownerPiPid === "number" &&
-		typeof e.sessionId === "string"
-	);
-}
-
-/** 校验并归一化 registry 文件内容；形状非法返回 undefined（走 corrupt 路径）。 */
-function parseRegistryContent(raw: string): BackgroundTaskRegistryFile | undefined {
-	let parsed: unknown;
-	try {
-		parsed = JSON.parse(raw);
-	} catch {
-		return undefined;
-	}
-	if (typeof parsed !== "object" || parsed === null) return undefined;
-	const { version, entries } = parsed as Record<string, unknown>;
-	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: BACKGROUND_TASK_REGISTRY_VERSION, entries: valid };
-}
-
-/** .corrupt 落点：固定名优先；已存在则带时间戳，不覆盖前一份现场。 */
-function corruptPathFor(registryPath: string): string {
-	const base = `${registryPath}.corrupt`;
-	return existsSync(base) ? `${base}-${Date.now()}` : base;
-}
-
-/**
- * 读取 registry 全量条目。文件不存在 / 读失败 / 解析失败均返回空表（工具面不因
- * registry 问题崩溃）；解析失败时重命名 .corrupt 保留现场 + warn（§3.6）。
+ * 读取 registry 全量条目（Map 投影薄壳）。文件不存在 / 读失败 / 解析失败均返回
+ * 空表（工具面不因 registry 问题崩溃）；解析失败由 protocol 原语重命名 .corrupt
+ * 保留现场 + warn（§3.6）。
  */
 export function readRegistry(registryPath: string): Map<string, RegistryEntry> {
-	if (!existsSync(registryPath)) return new Map();
-	let raw: string;
-	try {
-		raw = readFileSync(registryPath, "utf8");
-	} catch (err) {
-		logger.warn("registry read failed, treating as empty", {
-			detail: { path: registryPath, err: err instanceof Error ? err.message : String(err) },
-		});
-		return new Map();
-	}
-	const parsed = parseRegistryContent(raw);
-	if (parsed === undefined) {
-		const corruptPath = corruptPathFor(registryPath);
-		try {
-			renameSync(registryPath, corruptPath);
-			logger.warn("registry corrupted, renamed to preserve scene and rebuilt empty", {
-				detail: { path: registryPath, corruptPath },
-			});
-		} catch (err) {
-			logger.warn("registry corrupted and rename failed, rebuilding empty in place", {
-				detail: { path: registryPath, err: err instanceof Error ? err.message : String(err) },
-			});
-		}
-		return new Map();
-	}
-	return new Map(parsed.entries.map((e) => [e.taskId, e]));
+	const { entries } = readRegistryEntries(registryPath, registryFileLog);
+	return new Map(entries.map((e) => [e.taskId, e] as const));
 }
 
 /** BackgroundTask → RegistryEntry（剥离运行时字段 intent/timeoutTimer/child/registryPath）。 */
@@ -145,34 +83,10 @@ export function taskToRegistryEntry(task: BackgroundTask): RegistryEntry {
 	};
 }
 
-function serializeRegistry(entries: RegistryEntry[]): string {
-	const shape: BackgroundTaskRegistryFile = { version: BACKGROUND_TASK_REGISTRY_VERSION, entries };
-	return `${JSON.stringify(shape, null, JSON_INDENT)}\n`;
-}
-
-/** 原子写：tmp（pid+随机段唯一化）+ rename（POSIX/Windows 均原子）；失败清理 tmp。 */
-function atomicWriteRegistry(registryPath: string, content: string): void {
-	mkdirSync(dirname(registryPath), { recursive: true });
-	const tmpPath = `${registryPath}.tmp_${process.pid}_${Math.random().toString(TMP_RADIX).slice(TMP_SLICE_START, TMP_SLICE_END)}`;
-	try {
-		writeFileSync(tmpPath, content, "utf8");
-		renameSync(tmpPath, registryPath);
-	} catch (err) {
-		try {
-			if (existsSync(tmpPath)) unlinkSync(tmpPath);
-		} catch (cleanupErr) {
-			// tmp 清理失败不掩盖原错误，仅留诊断
-			logger.warn("registry tmp cleanup failed", {
-				detail: { tmpPath, err: cleanupErr instanceof Error ? cleanupErr.message : String(cleanupErr) },
-			});
-		}
-		throw err;
-	}
-}
-
 /**
  * 写入/更新单条 registry 条目（锁内 RMW：读全量 → 合并同 id 覆盖 → 终态 LRU 50 →
- * 原子写）。任务登记（running）、killing intent、终态三条路径共用。
+ * 原子写；读 / 裁剪 / 序列化 / 原子写由 protocol 原语承担）。任务登记（running）、
+ * killing intent、终态三条路径共用。
  * 失败返回 {success:false}——调用方按「写不进则条目停留 running，runtime 收殓
  * 兜底」处理（M2 只 warn，不重试不阻断主流程）。
  */
@@ -181,21 +95,19 @@ export function writeRegistryEntry(
 	entry: RegistryEntry,
 ): { success: boolean; error?: string } {
 	const writeMerged = (): void => {
-		const merged = readRegistry(registryPath);
+		const { entries } = readRegistryEntries(registryPath, registryFileLog);
+		const merged = new Map(entries.map((e) => [e.taskId, e] as const));
 		merged.set(entry.taskId, entry);
-		const all = [...merged.values()];
-		const terminal = all
-			.filter((e) => isTerminalState(e.state))
-			.sort((a, b) => (a.endedAt ?? a.startedAt) - (b.endedAt ?? b.startedAt));
-		const excess = terminal.length - MAX_TERMINAL_REGISTRY_ENTRIES;
-		for (let i = 0; i < excess; i++) merged.delete(terminal[i].taskId);
-		atomicWriteRegistry(registryPath, serializeRegistry([...merged.values()]));
+		const trimmed = trimTerminalEntries([...merged.values()], MAX_TERMINAL_REGISTRY_ENTRIES);
+		atomicWriteRegistry(registryPath, serializeRegistryFile(trimmed), registryFileLog);
 	};
 	try {
 		withFileLockSync(registryPath, writeMerged);
 		return { success: true };
 	} catch (err) {
-		const message = err instanceof Error ? err.message : String(err);
+		// 锁壳层写失败 warn 是本模块职责（protocol 原语不发该日志——写失败时的
+		// 「条目停留 running」降级决策在锁壳）
+		const message = toErrorMessage(err);
 		logger.warn("registry write failed; entry stays as-is (runtime reaper will collect the orphan)", {
 			detail: { path: registryPath, taskId: entry.taskId, err: message },
 		});

package/src/background/spawn-background.ts

@@ -5,6 +5,11 @@
  * <dataDir>/base-tool-enhance/<sessionId>/<task_id>.log（append fd，不占内存、
  * 无 pipe backpressure）+ child.unref()（pi 不等它）。abort/interrupt 不传播到
  * 后台任务（D15）——execute 立即返回，本模块不接触 signal。
+ *
+ * D6：本包不强加任务寿命上限（无 TTL/墙钟）——vitest watch、dev server 这类任务
+ * 的合法寿命就是「跑到用户叫停」，强加上限会把长任务误判死、完成通知链路随之失效。
+ * 寿命出口只有三个：自然退出 / 显式 timeout（LLM 传值或配置 backgroundTimeoutSeconds）
+ * / bash_kill。
  */
 
 import { spawn } from "node:child_process";
@@ -12,9 +17,10 @@ import { mkdirSync, openSync, closeSync, accessSync, constants } from "node:fs";
 import { dirname, join } from "node:path";
 import { randomBytes } from "node:crypto";
 
+import { getProcessStartTimeSec, killProcessTree, pidStartMatchesRegistered } from "@xyz-agent/extension-protocol/background-task";
+import { toErrorMessage } from "@zhushanwen/pi-ext-guards";
 import { getLogger } from "@zhushanwen/pi-extension-logger";
 
-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";
@@ -165,7 +171,7 @@ export function spawnBackgroundTask(opts: SpawnBackgroundOptions): SpawnBackgrou
 		child.on("error", () => {});
 		child.unref();
 	} catch (err) {
-		const message = err instanceof Error ? err.message : String(err);
+		const message = toErrorMessage(err);
 		return { ok: false, error: `Failed to start background command: ${message}` };
 	} finally {
 		// 子进程已继承 fd 副本（含 spawn 同步失败路径：fd 未被子进程持有），父进程侧
@@ -176,7 +182,7 @@ export function spawnBackgroundTask(opts: SpawnBackgroundOptions): SpawnBackgrou
 			} catch (err) {
 				// 已关闭/不可关闭均不掩盖主流程，仅留诊断
 				logger.debug("background spawn output fd close failed", {
-					detail: { outputFile, err: err instanceof Error ? err.message : String(err) },
+					detail: { outputFile, err: toErrorMessage(err) },
 				});
 			}
 		}
@@ -253,7 +259,12 @@ function armBackgroundTimeout(task: BackgroundTask, timeoutSec: number): void {
 			// 收尾不受影响。
 			return;
 		}
-		killProcessTree(task.pid);
+		// 回退路径诊断经 onFallback 注入 logger 适配（ext-simplify-13 D2）
+		killProcessTree(task.pid, (step, err) =>
+			logger.debug(step, {
+				detail: { pid: task.pid, err: toErrorMessage(err) },
+			}),
+		);
 		const marked = markKillingIntent(task.taskId, "timeout");
 		if (marked === undefined) return;
 		writeRegistryEntry(marked.registryPath, taskToRegistryEntry(marked));
@@ -265,8 +276,9 @@ function armBackgroundTimeout(task: BackgroundTask, timeoutSec: number): void {
 
 /**
  * 到点 pid 身份校验：true = 登记时的原进程仍占用该 pid（可安全 kill-tree）。
- * 判据（精确比较 / startedAt 秒级降级 / 读不到保守 false）单点定义于 kill-tree.ts
- * 的 pidStartMatchesRegistered（原 reaper.ts 单点，收殓下沉后随删除平移）。
+ * 判据（精确比较 / startedAt 秒级降级 / 读不到保守 false）单点定义于
+ * extension-protocol 的 pidStartMatchesRegistered（原 reaper.ts 单点，跨端原语
+ * 归一后经 background-task 子出口消费——ext-simplify-13）。
  */
 function isRecordedPidStillOriginal(task: BackgroundTask): boolean {
 	const actualStartSec = getProcessStartTimeSec(task.pid);

package/src/background/subagent-guard.ts

@@ -1,21 +1,17 @@
 /**
- * subagent 进程识别（D14 降级判据，探针 P5）。
+ * subagent 进程识别（bte background 降级判据——生命周期设计 D14 项，commit 8599abd0c）。
  *
- * subagent-core 的 buildChildEnv（packages/subagent-core/src/execution/engine/engines/pi/session-runner.ts）
- * 对每个子 agent 进程**无条件**注入身份贯穿 env（PI_SUBAGENT_ROOT_SESSION_ID / SELF_RECORD_ID /
- * DEPTH / ROOT_CWD，见其源码注释「无条件注入每个 subagent」）。任一存在 = 当前
- * pi 进程是 subagent 子进程 → 本扩展降级：background:true 被忽略走前台同步语义。
+ * 判据收敛于 ext-guards isSubagentProcess（`XYZ_AGENT_SUBAGENT === "1"`——引擎
+ * spawn 链恒注入的统一标记，ext-simplify-17 D4 重锚定）。命中 = 当前 pi 进程是
+ * 引擎链上的真 subagent → 本扩展降级：background:true 被忽略走前台同步语义。
+ *
+ * [HISTORICAL] 旧判据查 PI_SUBAGENT_* 身份键两枚（任一存在即命中）——引擎协议化
+ * 后该键族无写入方，判据失效态（降级实际从未生效），20260914 真机探针双断言证实
+ * 后随 D4 重锚。现行事实与口径详见 ext-guards isSubagentProcess JSDoc、设计
+ * docs/architecture/ext-simplify-17-shared-extraction.md §3.1 D4、探针报告
+ * .tmp/dev-flow/ext-simplify-17-d4-probe.md。
  *
  * 为什么降级：子 agent 内后台化会破坏 workflow 结构化输出契约（预算耗尽时测试未
  * 回）；且子进程死后其 registry 目录永远不会再有 session 启动，孤儿无人 reap。
  */
-
-/** subagent-core（session-runner）注入的身份贯穿 env 前缀（跨包契约，P5 探针确认）。 */
-const SUBAGENT_ENV_KEYS = [
-	"PI_SUBAGENT_ROOT_SESSION_ID",
-	"PI_SUBAGENT_SELF_RECORD_ID",
-] as const;
-
-export function isSubagentProcess(): boolean {
-	return SUBAGENT_ENV_KEYS.some((key) => process.env[key] !== undefined);
-}
+export { isSubagentProcess } from "@zhushanwen/pi-ext-guards";

package/src/background/task-store.ts

@@ -28,6 +28,8 @@
  * 未来新增写路径（如 maintenance 类）必须保持该顺序，违反即 intent 可丢失。
  */
 
+import { trimTerminalEntries } from "@xyz-agent/extension-protocol/background-task";
+
 import {
 	isActiveState,
 	isTerminalState,
@@ -120,14 +122,17 @@ export function finalizeTask(taskId: string, outcome: FinalizeOutcome): Backgrou
 	return task;
 }
 
-/** 终态条目超上限时按 endedAt 升序淘汰最老（LRU；endedAt 缺失退 startedAt）。 */
+/**
+ * 终态条目超上限时按 endedAt 升序淘汰最老（LRU；endedAt 缺失退 startedAt）。
+ * 裁剪纯函数单点在 protocol trimTerminalEntries（ext-simplify-13：与 registry 写侧、
+ * runtime registry-write 共用同一实现，本地上限经 MAX_TERMINAL_TASKS 传参）。
+ */
 function evictTerminalOverflow(): void {
-	const terminal = getAllTasks()
-		.filter((t) => isTerminalState(t.state))
-		.sort((a, b) => (a.endedAt ?? a.startedAt) - (b.endedAt ?? b.startedAt));
-	const excess = terminal.length - MAX_TERMINAL_TASKS;
-	for (let i = 0; i < excess; i++) {
-		taskTable.delete(terminal[i].taskId);
+	const kept = trimTerminalEntries(getAllTasks(), MAX_TERMINAL_TASKS);
+	if (kept.length === taskTable.size) return;
+	const keptIds = new Set(kept.map((t) => t.taskId));
+	for (const id of [...taskTable.keys()]) {
+		if (!keptIds.has(id)) taskTable.delete(id);
 	}
 }
 

package/src/bash-kill-tool.ts

@@ -18,9 +18,12 @@
 
 import type { AgentToolResult, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { getProcessStartTimeSec, isPidAlive, killProcessTree } from "@xyz-agent/extension-protocol/background-task";
 import { Type } from "typebox";
 
-import { getProcessStartTimeSec, isPidAlive, killProcessTree } from "./kill-tree.ts";
+import { toErrorMessage } from "@zhushanwen/pi-ext-guards";
+import { getLogger } from "@zhushanwen/pi-extension-logger";
+
 import { ensurePollerRunning } from "./background/poller.ts";
 import { getRegistryPath, readRegistry, taskToRegistryEntry, writeRegistryEntry } from "./background/registry.ts";
 import { getAllTasks, markKillingIntent } from "./background/task-store.ts";
@@ -38,6 +41,8 @@ const BASH_KILL_DESCRIPTION = [
 /** JSON 输出缩进（registry.ts 同款）。 */
 const JSON_INDENT = 2;
 
+const logger = getLogger("base-tool-enhance");
+
 function textResult(text: string): AgentToolResult<unknown> {
 	return { content: [{ type: "text", text }], details: undefined };
 }
@@ -77,11 +82,15 @@ export function createBashKillToolDefinition() {
 				}
 				// registry-only 活跃条目 = 他进程任务（本进程活跃任务必在单例表）——跨进程
 				// 不可 kill：处置权归发起进程；属主若已死，孤儿由 xyz-agent runtime 在
-				// session 销毁时或启动期兜底扫描时收殓（属主判定，u-bte-remove 下沉）
+				// session 销毁时或启动期兜底扫描时收殓（属主判定，u-bte-remove 下沉；
+				// 纯 CLI 独立安装无 runtime 收殓兜底，孤儿自然退出或手动杀——E11 已
+				// 接受边界，hint 按形态分流，不写死 runtime 承诺）
 				return killedFalse(
 					"cross-process running task owned by another pi process",
 					"the task is managed by the pi process that started it (bash_kill from that session); " +
-						"if that process is gone, the owning xyz-agent runtime will collect the orphan when its session ends or on app restart",
+						"if that process is gone, the orphan keeps running until it exits on its own; " +
+						"inside the xyz-agent runtime it is collected when the owner's session ends or on app restart; " +
+						"standalone pi: kill the process group manually (kill -- -<pgid>; the registered task pid is the pgid) if it lingers",
 				);
 			}
 			if (isTerminalState(fromStore.state)) {
@@ -125,7 +134,13 @@ export function createBashKillToolDefinition() {
 			if (marked !== undefined) {
 				writeRegistryEntry(marked.registryPath, taskToRegistryEntry(marked));
 			}
-			killProcessTree(fromStore.pid);
+			// 回退路径诊断经 onFallback 注入 logger 适配（ext-simplify-13 D2：进程原语
+			// 零日志依赖，协议侧 step 标识符 + 本包落盘通道）
+			killProcessTree(fromStore.pid, (step, err) =>
+				logger.debug(step, {
+					detail: { pid: fromStore.pid, err: toErrorMessage(err) },
+				}),
+			);
 			// 轮询器确保在跑：边沿收尾（写终态）依赖它
 			ensurePollerRunning();
 			return textResult(

package/src/bash-output-tool.ts

@@ -14,9 +14,10 @@
 
 import type { AgentToolResult, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { readOutputTail } from "@xyz-agent/extension-protocol/background-task";
 import { Type } from "typebox";
 
-import { readOutputTail } from "./background/output-tail.ts";
+import { TAIL_MAX_BYTES, TAIL_MAX_LINES } from "./background/output-tail.ts";
 import { getRegistryPath, readRegistry } from "./background/registry.ts";
 import { truncateCommand } from "./background/spawn-background.ts";
 import { getAllTasks } from "./background/task-store.ts";
@@ -88,7 +89,10 @@ function findTask(
 
 /** 详情视图：tail 输出（丢失时 "<lost>"，§3.6）+ 终态字段按存在性展开。 */
 function taskDetailText(task: BackgroundTask | RegistryEntry): string {
-	const tail = readOutputTail(task.outputFile);
+	// protocol 原语返回 {text, truncated}；50KB/2000 行口径（本包产品决策）在此传参。
+	// 返回 JSON 的 `output` 字段名是 LLM 可见契约（工具 schema/描述零变化），仅在
+	// 此处从原语的 text 投影，ext-simplify-13 D2 有意内部变化
+	const tail = readOutputTail(task.outputFile, { maxBytes: TAIL_MAX_BYTES, maxLines: TAIL_MAX_LINES });
 	const detail = {
 		task_id: task.taskId,
 		state: task.state,
@@ -96,7 +100,7 @@ function taskDetailText(task: BackgroundTask | RegistryEntry): string {
 		...(task.reason !== undefined ? { reason: task.reason } : {}),
 		startedAt: task.startedAt,
 		...(task.durationMs !== undefined ? { durationMs: task.durationMs } : {}),
-		output: tail?.output ?? "<lost>",
+		output: tail?.text ?? "<lost>",
 		truncated: tail?.truncated ?? false,
 		outputFile: task.outputFile,
 	};

package/src/bash-tool.ts

@@ -148,6 +148,9 @@ export function createBashOverrideToolDefinition() {
 		// （label/promptSnippet/promptGuidelines/renderCall/renderResult 等）全部随
 		// delegate 透传，cwd 重建 delegate 时静态闭包引用不变（render 闭包与 cwd 无关）
 		...initial,
+		// D2（禁止改名）：桌面侧六处按工具 key 'bash' 硬编码（truncate-tool-output、
+		// useToolMeta、block-icon、pi-preset BUILTIN_TOOLS 与 deniedTools、permission
+		// extractCommand）——改名后这些消费面全部失配，审批退化为逐次弹窗、渲染错位
 		name: initial.name, // "bash"：同名覆盖内置工具（agent-session _refreshToolRegistry 后注册者胜）
 		description: ENHANCED_BASH_DESCRIPTION,
 		parameters: enhancedBashSchema,

package/src/config.ts

@@ -11,6 +11,7 @@
  */
 
 import { getConfigPath as getLlmSharedConfigPath, loadConfig } from "@zhushanwen/pi-llm-shared";
+import { isRecord, toErrorMessage } from "@zhushanwen/pi-ext-guards";
 import { getLogger } from "@zhushanwen/pi-extension-logger";
 
 import { DEFAULT_MAX_CONCURRENT_BACKGROUND } from "./background/spawn-background.ts";
@@ -51,10 +52,6 @@ export function getConfigFilePath(): string {
 	return getLlmSharedConfigPath(CONFIG_PKG);
 }
 
-function isPlainObject(value: unknown): value is Record<string, unknown> {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 function describeValue(value: unknown): string {
 	return typeof value === "string" ? JSON.stringify(value) : String(value);
 }
@@ -109,7 +106,7 @@ function normalizeForceBackgroundPatterns(raw: unknown): string[] {
 		} catch (err) {
 			logger.warn(
 				`Config key 'forceBackgroundPatterns[${index}]' is not a valid regex (${item}), dropped: ` +
-					`${err instanceof Error ? err.message : String(err)} (${getLlmSharedConfigPath(CONFIG_PKG)}).`,
+					`${toErrorMessage(err)} (${getLlmSharedConfigPath(CONFIG_PKG)}).`,
 			);
 			return;
 		}
@@ -138,7 +135,7 @@ function normalizeMaxConcurrentBackground(raw: unknown): number {
  * 问题在这里就地消化）。未知键忽略（前向兼容）。
  */
 export function normalizeBaseToolEnhanceConfig(raw: unknown): BaseToolEnhanceConfig {
-	if (!isPlainObject(raw)) {
+	if (!isRecord(raw)) {
 		if (raw !== undefined && raw !== null) {
 			logger.warn(
 				`Config root is not a JSON object (${describeValue(raw)}), using all defaults ` +

package/src/index.ts

@@ -20,6 +20,7 @@ import type {
 	SessionStartEvent,
 } from "@earendil-works/pi-coding-agent";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { toErrorMessage } from "@zhushanwen/pi-ext-guards";
 import { getLogger } from "@zhushanwen/pi-extension-logger";
 
 import { createBashOutputToolDefinition } from "./bash-output-tool.ts";
@@ -90,7 +91,7 @@ function runSessionStartMaintenance(
 	} 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) },
+			detail: { err: toErrorMessage(err) },
 		});
 	}
 }

package/src/tool-error-audit.ts

@@ -4,8 +4,9 @@
  * 迁移约定（与原实现逐字段一致，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 摘除旧包时消费方无感）
+ *  - customType = "unified-hooks:tool-error"（保持原值：无代码消费方；保持旧名是
+ *    历史 entry 可查询性承诺（01 号设计 P-protocol / README 承接表），废弃包名残留
+ *    为已接受代价——ext-simplify-13 D4）
  *  - entry 形态 = { timestamp, toolName, toolCallId, errorText }，errorText 取不到时 null
  *
  * 原实现的设计决策一并继承：不调 ctx.ui.notify——tool error 已在对话流里