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

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 "@taiji/extension-protocol";
+import { isPidAlive } from "@taiji/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 "@taiji/extension-protocol/background-task";
+
 import { readTailSummary } from "./output-tail.ts";
 import { readRegistry, taskToRegistryEntry, writeRegistryEntry } from "./registry.ts";
 import { finalizeTask, getActiveTasks } from "./task-store.ts";

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

@@ -18,18 +18,19 @@
  *    挂起进程，pi 的 ignore 语义完全失效
  *  - rpc/print 模式 Ctrl+C：pi 无 SIGINT listener（dist 全量 grep 唯一注册点在 TUI
  *    挂起态）→ 默认处置进程即死。探针实测：无 listener 的信号默认终止**不触发
- *    exit 事件**，同步收殓在该路径本就不可达；孤儿由 xyz-agent runtime 收殓器按
+ *    exit 事件**，同步收殓在该路径本就不可达；孤儿由 taiji runtime 收殓器按
  *    属主判定收殓（u-bte-remove 下沉后；与 SIGKILL 强杀同类，设计内兜底）
  *  - cleanup-only listener 更不可取：注册即抑制默认终止，rpc 前台 Ctrl+C 后 pi 变
  *    成杀不死的僵尸进程
  *
- * 子进程死后 registry 目录由 xyz-agent runtime 启动期兜底扫描覆盖（收殓下沉）——
+ * 子进程死后 registry 目录由 taiji runtime 启动期兜底扫描覆盖（收殓下沉）——
  * 本单元不管。
  */
 
+import { killProcessTree } from "@taiji/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

@@ -3,44 +3,47 @@
  *
  * 路径：<dataDir>/base-tool-enhance/<sessionId>/registry.json（dataDir = pi
  * getAgentDir() 同源路径，由调用方解析传入）。条目记 ownerPiPid——收殓侧属主
- * 判定依据（u-bte-remove 后 = xyz-agent runtime background-task-reaper），M2 只负责
+ * 判定依据（u-bte-remove 后 = taiji runtime background-task-reaper），M2 只负责
  * 写入。
  *
+ * 行为原语单点（ext-simplify-13）：解析防御 / corrupt 隔离 / 原子写 / 序列化 /
+ * 终态 LRU 裁剪自 @taiji/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 互斥）
+ *    （runtime 收殓器写终态用 taiji 统一锁，与该 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 "@taiji/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 "@taiji/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 "@taiji/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（`TAIJI_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

@@ -7,7 +7,7 @@
  *
  * 条目唯一来源 = 本进程 execute 的 spawn（registerSpawnedTask 全仓唯一调用点 =
  * spawn-background.ts）。他进程 / 历史 session 的 running 条目**永不进表**——
- * 零恢复零接管，孤儿处置权统一归收殓侧（u-bte-remove 后 = xyz-agent runtime）
+ * 零恢复零接管，孤儿处置权统一归收殓侧（u-bte-remove 后 = taiji runtime）
  * 按属主裁决；终态条目可从 registry 读，仅供 bash_output 查历史。
  *
  * 终态条目 LRU 上限 MAX_TERMINAL_ENTRIES（与 registry 对称），淘汰后 bash_output
@@ -28,6 +28,8 @@
  * 未来新增写路径（如 maintenance 类）必须保持该顺序，违反即 intent 可丢失。
  */
 
+import { trimTerminalEntries } from "@taiji/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/background/types.ts

@@ -8,7 +8,7 @@
  *    条目记 ownerPiPid（M2 只负责写入）
  *
  * 契约改引（u-bte-remove）：registry 持久化形状（RegistryEntry / 状态机 / reason
- * 枚举 / active·terminal 判定）与 @xyz-agent/extension-protocol background-task.ts
+ * 枚举 / active·terminal 判定）与 @taiji/extension-protocol background-task.ts
  * 契约逐字段一致（契约文档头声明基线即本文件 + registry.ts），本地副本已删除、
  * 此处 re-export 并保留包内短名——消费方 import 路径与字段语义零变化。运行时
  * 对象类型（BackgroundTask / KillingIntent）不在契约内（剥离非持久字段前的形状），
@@ -19,18 +19,18 @@ import type { ChildProcess } from "node:child_process";
 import type {
 	BackgroundTaskEndReason as ContractEndReason,
 	BackgroundTaskState as ContractState,
-} from "@xyz-agent/extension-protocol";
+} from "@taiji/extension-protocol";
 
 /** 状态机与 reason 枚举 / 持久化条目 / active·terminal 判定：契约 SSOT re-export。 */
 export type {
 	BackgroundTaskRegistryEntry as RegistryEntry,
 	BackgroundTaskState,
 	BackgroundTaskEndReason,
-} from "@xyz-agent/extension-protocol";
+} from "@taiji/extension-protocol";
 export {
 	isActiveBackgroundTaskState as isActiveState,
 	isTerminalBackgroundTaskState as isTerminalState,
-} from "@xyz-agent/extension-protocol";
+} from "@taiji/extension-protocol";
 
 /**
  * killing intent：bash_kill / 后台 timeout 已发令、轮询器 exit 边沿未确认的瞬态标记。