@zhushanwen/pi-base-tool-enhance 0.2.0

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

@@ -0,0 +1,106 @@
+/**
+ * pi 进程退出收殓（D12：后台任务生命周期绑定 pi 进程，不绑定 session）。
+ *
+ * 绝不能挂在 extension dispose / session_shutdown 上——session 替换（fork/switch/new）
+ * 也触发它们，那会误杀全部后台任务（任务跨同进程 session 替换继续运行）。收殓只认
+ * process 级信号与进程退出：
+ *  - SIGTERM handler：只收殓不 exit（pi rpc-mode 自有 SIGTERM → shutdown 流程，抢
+ *    exit 会打断其 tracked-pid 清理与日志 flush），随后 process.exit 触发下方兜底
+ *  - process.on("exit")：同步兜底路径——kill-tree 同步 kill + registry 同步原子写
+ *  - 幂等：cleaned flag 保证信号 handler 先跑收殓后，exit 兜底再跑一次无害
+ *
+ * 不挂 SIGINT handler（pi 0.84.1 实装核实，2026-08 review 轮修复）：
+ *  - TUI 常态 raw mode，Ctrl+C 是按键不走信号；唯一收到 SIGINT 的 TUI 场景是挂起态
+ *    （cooked mode），而 pi 挂起态刻意注册 ignoreSigint 免疫 Ctrl+C
+ *    （interactive-mode.js「Ignore SIGINT while suspended」）。Node 对同一信号调用
+ *    全部 listener，本包任何 SIGINT listener（含 once）都会在此刻被触发——cleanup
+ *    杀光后台任务（违背 D15「interrupt 不传播后台任务」）再 exit 掐死本应存活的
+ *    挂起进程，pi 的 ignore 语义完全失效
+ *  - rpc/print 模式 Ctrl+C：pi 无 SIGINT listener（dist 全量 grep 唯一注册点在 TUI
+ *    挂起态）→ 默认处置进程即死。探针实测：无 listener 的信号默认终止**不触发
+ *    exit 事件**，同步收殓在该路径本就不可达；孤儿由 M5 reaper 属主判定收殓
+ *    （与 SIGKILL 强杀同类，设计内兜底）
+ *  - cleanup-only listener 更不可取：注册即抑制默认终止，rpc 前台 Ctrl+C 后 pi 变
+ *    成杀不死的僵尸进程
+ *
+ * 子进程死后 registry 目录无人再扫（reaper 是 M5）——本单元不管。
+ */
+
+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";
+import { finalizeTask, getActiveTasks } from "./task-store.ts";
+
+const logger = getLogger("base-tool-enhance");
+
+let installed = false;
+let cleaned = false;
+
+/**
+ * 安装进程级收殓（幂等，extension load 时调用一次；同进程 session 替换重新 load
+ * 不会重复挂 handler——模块级 installed flag）。
+ */
+export function installProcessExitGuard(): void {
+	if (installed) return;
+	installed = true;
+
+	const cleanup = () => {
+		if (cleaned) return;
+		cleaned = true;
+		reapBackgroundTasksNow();
+	};
+
+	// SIGTERM：只收殓不 exit——pi rpc-mode 的 SIGTERM handler（先注册先跑）走自己的
+	// shutdown 流程，最终 process.exit 触发下方 exit 兜底（幂等跳过）。
+	// SIGINT 刻意不挂 handler——会破坏 pi TUI 挂起态的 ignoreSigint 语义，且 rpc
+	// 默认终止路径 exit 事件本就不触发、孤儿归 M5 reaper 兜底（完整论证见文件头
+	// 「不挂 SIGINT handler」专段）
+	process.once("SIGTERM", cleanup);
+	// 同步兜底：exit handler 里只能做同步收殓（kill-tree 同步 + registry 同步原子写）
+	process.on("exit", cleanup);
+}
+
+/**
+ * 收殓动作（导出供测试直接调用，不真杀 pi 进程）：
+ * 轮询器停止 → 遍历**单例表**活跃条目 kill-tree（单例表 = 本进程任务全集，天然
+ * 不含他进程条目——不遍历 registry，否则 ephemeral 附着进程退出会误杀属主进程的
+ * 任务）→ registry 写终态 exited(reason:"process-exit")。
+ *
+ * 终态与轮询器边沿共用 finalizeTask（单一终态归属）。
+ */
+export function reapBackgroundTasksNow(): void {
+	stopPoller();
+	for (const task of getActiveTasks()) {
+		try {
+			killProcessTree(task.pid);
+		} catch (err) {
+			// 单条 kill 失败不阻断其余条目收殓；进程将退出，残余由 M5 reaper 兜底
+			logger.warn("kill-tree failed during process-exit reap", {
+				detail: { taskId: task.taskId, pid: task.pid, err: err instanceof Error ? err.message : String(err) },
+			});
+		}
+		const finalized = finalizeTask(task.taskId, {
+			exitCode: task.child?.exitCode ?? null,
+			reason: "process-exit",
+			endedAt: Date.now(),
+		});
+		if (finalized !== undefined) {
+			writeRegistryEntry(finalized.registryPath, taskToRegistryEntry(finalized));
+			// 尽力补 emit pending:unregister（§3.5「pi API 若仍可用」）：SIGTERM
+			// 信号路径 pi 引用尚活（emit 经模块级 notify 引用，bus 未 dispose 时送达
+			// pending listener 落盘）；process.on("exit") 同步路径 bus 可能已 dispose，
+			// emit throw 被 notify 内部捕获降级——残留由 session_start 对账兜底。
+			// **不 sendMessage**：进程都退了，无投递目标。
+			emitPendingUnregister(finalized.taskId, "process-exit", finalized.exitCode ?? null);
+		}
+	}
+}
+
+/** 测试专用：复位幂等 flag（clearTaskStoreForTest 配套）。 */
+export function resetProcessExitGuardForTest(): void {
+	installed = false;
+	cleaned = false;
+}

package/src/background/registry.ts

@@ -0,0 +1,203 @@
+/**
+ * registry.json 持久化读写（per-sessionId 目录，D8）。
+ *
+ * 路径：<dataDir>/base-tool-enhance/<sessionId>/registry.json（dataDir = pi
+ * getAgentDir() 同源路径，由调用方解析传入）。条目记 ownerPiPid——M5 reaper 属主
+ * 判定依据，M2 只负责写入。
+ *
+ * 写入协议：
+ *  - 原子写 temp+rename（tmp 名带 pid+随机段防并发碰撞，llm-shared saveConfig 范式）
+ *  - 锁内 RMW（@zhushanwen/pi-file-lock withFileLockSync）——同 sessionId 目录可能
+ *    被桌面端 ephemeral 附着进程与发起进程并发写，跨进程互斥只依赖同一 lockfile
+ *  - 锁获取失败不降级无锁写：返回 {success:false}，条目停留 running 由 M5 reaper
+ *    兜底（§3.5「registry/entry 写不进则条目停留 running」）
+ *  - 损坏读取防御（§3.6）：解析失败/形状非法 → 重命名 .corrupt 保留现场 + 按空表
+ *    重建 + warn 日志
+ *  - 终态条目 LRU 上限 50（与单例表对称）
+ */
+
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import { getLogger } from "@zhushanwen/pi-extension-logger";
+import { withFileLockSync } from "@zhushanwen/pi-file-lock";
+
+import { isTerminalState, type BackgroundTask, type RegistryEntry } from "./types.ts";
+
+const logger = getLogger("base-tool-enhance");
+
+/** registry 文件格式版本（未来结构变更时迁移判据）。 */
+const REGISTRY_VERSION = 1;
+/** 终态条目 LRU 上限（与 task-store MAX_TERMINAL_TASKS 对称，§3.5）。 */
+export const MAX_TERMINAL_REGISTRY_ENTRIES = 50;
+const JSON_INDENT = 2;
+// tmp 随机段参数（llm-shared uniqueTmpPath 同款：36 进制随机串，跳过 "0." 前缀）
+const TMP_RADIX = 36;
+const TMP_SLICE_START = 2;
+const TMP_SLICE_END = 10;
+
+export function getBaseToolEnhanceDir(dataDir: string): string {
+	return join(dataDir, "base-tool-enhance");
+}
+
+export function getRegistryPath(dataDir: string, sessionId: string): string {
+	return join(getBaseToolEnhanceDir(dataDir), sessionId, "registry.json");
+}
+
+interface RegistryFileShape {
+	version: number;
+	entries: RegistryEntry[];
+}
+
+/**
+ * 最低限度形状校验：核心标识字段缺失即整条丢弃（不因单条脏数据报废全表）。
+ */
+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): RegistryFileShape | 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 !== REGISTRY_VERSION || !Array.isArray(entries)) return undefined;
+	const valid: RegistryEntry[] = [];
+	for (const item of entries) {
+		if (isValidRegistryEntry(item)) valid.push(item);
+	}
+	return { version: REGISTRY_VERSION, entries: valid };
+}
+
+/** .corrupt 落点：固定名优先；已存在则带时间戳，不覆盖前一份现场。 */
+function corruptPathFor(registryPath: string): string {
+	const base = `${registryPath}.corrupt`;
+	return existsSync(base) ? `${base}-${Date.now()}` : base;
+}
+
+/**
+ * 读取 registry 全量条目。文件不存在 / 读失败 / 解析失败均返回空表（工具面不因
+ * registry 问题崩溃）；解析失败时重命名 .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]));
+}
+
+/** BackgroundTask → RegistryEntry（剥离运行时字段 intent/timeoutTimer/child/registryPath）。 */
+export function taskToRegistryEntry(task: BackgroundTask): RegistryEntry {
+	return {
+		taskId: task.taskId,
+		pid: task.pid,
+		command: task.command,
+		outputFile: task.outputFile,
+		startedAt: task.startedAt,
+		state: task.state,
+		ownerPiPid: task.ownerPiPid,
+		sessionId: task.sessionId,
+		...(task.exitCode !== undefined ? { exitCode: task.exitCode } : {}),
+		...(task.reason !== undefined ? { reason: task.reason } : {}),
+		...(task.endedAt !== undefined ? { endedAt: task.endedAt } : {}),
+		...(task.durationMs !== undefined ? { durationMs: task.durationMs } : {}),
+		...(task.tailSummary !== undefined ? { tailSummary: task.tailSummary } : {}),
+		...(task.pidStartTime !== undefined ? { pidStartTime: task.pidStartTime } : {}),
+	};
+}
+
+function serializeRegistry(entries: RegistryEntry[]): string {
+	const shape: RegistryFileShape = { version: 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、终态三条路径共用。
+ * 失败返回 {success:false}——调用方按「写不进则条目停留 running，M5 reaper 兜底」
+ * 处理（M2 只 warn，不重试不阻断主流程）。
+ */
+export function writeRegistryEntry(
+	registryPath: string,
+	entry: RegistryEntry,
+): { success: boolean; error?: string } {
+	const writeMerged = (): void => {
+		const merged = readRegistry(registryPath);
+		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()]));
+	};
+	try {
+		withFileLockSync(registryPath, writeMerged);
+		return { success: true };
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		logger.warn("registry write failed; entry stays as-is (M5 reaper will reconcile)", {
+			detail: { path: registryPath, taskId: entry.taskId, err: message },
+		});
+		return { success: false, error: message };
+	}
+}

package/src/background/spawn-background.ts

@@ -0,0 +1,275 @@
+/**
+ * 后台任务 spawn（D7/D10/D12/D15，设计文档 §3.5 后台任务生命周期数据流 ③④）。
+ *
+ * spawn 细节：detached（自成进程组，进程树 kill 的语义基础）+ stdio 直接落
+ * <dataDir>/base-tool-enhance/<sessionId>/<task_id>.log（append fd，不占内存、
+ * 无 pipe backpressure）+ child.unref()（pi 不等它）。abort/interrupt 不传播到
+ * 后台任务（D15）——execute 立即返回，本模块不接触 signal。
+ */
+
+import { spawn } from "node:child_process";
+import { mkdirSync, openSync, closeSync, accessSync, constants } from "node:fs";
+import { dirname, join } from "node:path";
+import { randomBytes } from "node:crypto";
+
+import { getLogger } from "@zhushanwen/pi-extension-logger";
+
+import { killProcessTree } from "../kill-tree.ts";
+import { getProcessStartTimeSec, pidStartMatchesRegistered } from "../reaper.ts";
+import { emitPendingRegister } from "./notify.ts";
+import { ensurePollerRunning } from "./poller.ts";
+import { getRegistryPath, taskToRegistryEntry, writeRegistryEntry } from "./registry.ts";
+import { countActiveTasks, markKillingIntent, oldestActiveTask, registerSpawnedTask } from "./task-store.ts";
+import type { BackgroundTask } from "./types.ts";
+
+/** task_id 随机段熵源字节数（crypto 大数采样，8 字节 = 64 bit）。 */
+const TASK_ID_ENTROPY_BYTES = 8;
+/** 秒 → 毫秒。 */
+const MS_PER_SECOND = 1000;
+
+const logger = getLogger("base-tool-enhance");
+
+/**
+ * 并发上限默认值（D10）。M4：取值来源已配置化——bash-tool execute 每次读
+ * maxConcurrentBackground 配置经 opts.maxConcurrent 传入；本常量仅在调用方未传时
+ * 兜底（与 config.ts DEFAULT_BASE_TOOL_ENHANCE_CONFIG.maxConcurrentBackground 同源）。
+ */
+export const DEFAULT_MAX_CONCURRENT_BACKGROUND = 8;
+
+/**
+ * task_id 随机段长度（base36 小写）。6 字符 ≈ 31 bit 熵：同毫秒内数百次 spawn 的
+ * 生日碰撞概率 ~1e-7（4 字符实测在 500 次内可撞——唯一性是 pending 差集前提，
+ * §2.3，熵按此约束取值）。
+ */
+const TASK_ID_RAND_LENGTH = 6;
+const TASK_ID_RADIX = 36;
+const TASK_ID_RAND_SPACE = TASK_ID_RADIX ** TASK_ID_RAND_LENGTH;
+
+/** 命令在错误文案中的展示长度上限。 */
+const COMMAND_DISPLAY_LIMIT = 80;
+
+/**
+ * task_id 生成：`bt-<ts>-<rand>`（前缀 bt- 刻意区别于 subagent-workflow 的
+ * bg-/run-，§2.3）。**禁止进程内自增序列**——pi 重启后撞旧 id 会破坏 pending
+ * 差集前提（register 被幂等忽略 / 旧 unregister 误消新任务）。
+ */
+export function generateTaskId(now: number = Date.now()): string {
+	return `bt-${now}-${randomRandSegment()}`;
+}
+
+/** 均匀 base36 随机段：crypto 随机大数取模，无 base64 字符集替换导致的采样偏置。 */
+function randomRandSegment(): string {
+	const value = randomBytes(TASK_ID_ENTROPY_BYTES).readBigUInt64BE() % BigInt(TASK_ID_RAND_SPACE);
+	return value.toString(TASK_ID_RADIX).padStart(TASK_ID_RAND_LENGTH, "0");
+}
+
+/**
+ * 后台 timeout 解析（秒），优先级 = LLM 显式值 > 配置默认值 > 不限（§3.5）：
+ *  - 显式值有效 → 显式值；显式值无效（非有限/≤0）→ 沿用 pi 内置文案抛错
+ *  - 显式值缺省 && 配置默认提供 → 配置默认（M4 注入接缝：调用侧传
+ *    backgroundTimeoutSeconds；已 normalize，必为正有限数）
+ *  - 双缺省 → undefined（不限）
+ * D13 例外由调用侧实现：白名单强转后台时传 explicitSec=undefined（显式值整体忽略）。
+ */
+export function resolveBackgroundTimeoutSec(
+	explicitSec: number | undefined,
+	defaultSec?: number,
+): number | undefined {
+	if (explicitSec === undefined) return defaultSec;
+	if (!Number.isFinite(explicitSec) || explicitSec <= 0) {
+		throw new Error("Invalid timeout: must be a finite number of seconds");
+	}
+	return explicitSec;
+}
+
+export interface SpawnBackgroundOptions {
+	command: string;
+	/** execute ctx.cwd（权威 cwd） */
+	cwd: string;
+	/** pi getAgentDir() 同源 dataDir */
+	dataDir: string;
+	sessionId: string;
+	/** LLM 显式 timeout（秒）；undefined 时若配置默认存在由调用侧注入（M4）。 */
+	timeoutSec?: number;
+	/** 并发上限（M4：bash-tool 从 maxConcurrentBackground 配置传入；缺省走默认常量）。 */
+	maxConcurrent?: number;
+}
+
+export type SpawnBackgroundResult =
+	| { ok: true; task: BackgroundTask }
+	| { ok: false; error: string };
+
+function shellForPlatform(): { shell: string; args: string[] } {
+	if (process.platform === "win32") {
+		return { shell: process.env.ComSpec || "cmd.exe", args: ["/c"] };
+	}
+	return { shell: process.env.SHELL || "/bin/sh", args: ["-c"] };
+}
+
+/**
+ * 启动后台任务：并发检查 → spawn（输出重定向 .log）→ 单例表登记 + registry 写
+ * running 条目 → 显式 timeout 定时器 → 启动轮询器。
+ * 立即返回，不等待命令退出（turn 不被占用，G1）。
+ */
+export function spawnBackgroundTask(opts: SpawnBackgroundOptions): SpawnBackgroundResult {
+	const maxConcurrent = opts.maxConcurrent ?? DEFAULT_MAX_CONCURRENT_BACKGROUND;
+	if (countActiveTasks() >= maxConcurrent) {
+		const oldest = oldestActiveTask();
+		if (oldest === undefined) {
+			// 防御缺口闭合：上限已满但找不出最老活跃任务 = maxConcurrent <= 0 且 0 活跃
+			// ——同样拒绝，否则上限静默失效。config normalize 保证 >= 1，此处兜底
+			// 绕过配置直传非法值的调用方（错误指向配置键，可操作）
+			return {
+				ok: false,
+				error:
+					`Background task concurrency limit configuration invalid (maxConcurrent=${maxConcurrent}, must be >= 1). ` +
+				"Fix maxConcurrentBackground in the base-tool-enhance config.",
+			};
+		}
+		const cmd = truncateCommand(oldest.command);
+		return {
+			ok: false,
+			error:
+				`Background task limit reached (max ${maxConcurrent} concurrent). ` +
+				`Oldest task: ${oldest.taskId} (${cmd}). ` +
+				`Kill it with bash_kill {task_id:"${oldest.taskId}"} or wait for it to finish.`,
+		};
+	}
+
+	// cwd 校验对齐 pi 内置文案（bash.js createLocalBashOperations）
+	try {
+		accessOrThrow(opts.cwd);
+	} catch {
+		return {
+			ok: false,
+			error: `Working directory does not exist: ${opts.cwd}\nCannot execute bash commands.`,
+		};
+	}
+
+	const taskId = generateTaskId();
+	const registryPath = getRegistryPath(opts.dataDir, opts.sessionId);
+	const outputFile = join(dirname(registryPath), `${taskId}.log`);
+	mkdirSync(dirname(outputFile), { recursive: true });
+
+	const { shell, args } = shellForPlatform();
+	let outputFd: number | undefined;
+	let child;
+	try {
+		outputFd = openSync(outputFile, "a");
+		child = spawn(shell, [...args, opts.command], {
+			cwd: opts.cwd,
+			detached: true,
+			stdio: ["ignore", outputFd, outputFd],
+		});
+		// 唯一的事件监听例外：no-op error listener 防 spawn 异步失败 emit error 无监听
+		// 导致进程崩溃（EventEmitter 语义）。不做任何状态推进——exit 感知归轮询器（D17）。
+		child.on("error", () => {});
+		child.unref();
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		return { ok: false, error: `Failed to start background command: ${message}` };
+	} finally {
+		// 子进程已继承 fd 副本（含 spawn 同步失败路径：fd 未被子进程持有），父进程侧
+		// 描述符统一在此关闭防句柄泄漏
+		if (outputFd !== undefined) {
+			try {
+				closeSync(outputFd);
+			} catch (err) {
+				// 已关闭/不可关闭均不掩盖主流程，仅留诊断
+				logger.debug("background spawn output fd close failed", {
+					detail: { outputFile, err: err instanceof Error ? err.message : String(err) },
+				});
+			}
+		}
+	}
+
+	if (child.pid === undefined) {
+		return { ok: false, error: "Failed to start background command: no pid acquired" };
+	}
+
+	// M3 补写 M5 预告字段：spawn 后立即读子进程 start time（epoch 秒），供 reaper
+	// 精确比较防 pid 复用误杀。读取失败省略（undefined 不进条目）——reaper 降级走
+	// startedAt 秒级校验兜底，不报错不阻断 spawn
+	const pidStartTime = getProcessStartTimeSec(child.pid);
+
+	const task: BackgroundTask = {
+		taskId,
+		pid: child.pid,
+		command: opts.command,
+		outputFile,
+		registryPath,
+		startedAt: Date.now(),
+		state: "running",
+		ownerPiPid: process.pid,
+		sessionId: opts.sessionId,
+		...(pidStartTime !== undefined ? { pidStartTime } : {}),
+		child,
+	};
+
+	if (opts.timeoutSec !== undefined) {
+		armBackgroundTimeout(task, opts.timeoutSec);
+	}
+
+	// 登记顺序（§3.5 数据流 ③④⑤）：单例表（运行时权威）→ registry（持久化）→
+	// pending:register emit。registry 写失败不阻断（条目停留 running 由 M5 reaper
+	// 兜底，§3.5）；emit 失败同样无害（peer 未加载/引用未注入时无 listener，通知
+	// 链路缺失不影响任务本体）
+	registerSpawnedTask(task);
+	writeRegistryEntry(registryPath, taskToRegistryEntry(task));
+	emitPendingRegister(task);
+	ensurePollerRunning();
+	return { ok: true, task };
+}
+
+/**
+ * 后台显式 timeout（D6：任务寿命可由使用者显式约束）。到点：pid 身份校验通过则
+ * kill-tree + 两侧标 killing intent（reason 候选 timeout）——实际终态由轮询器边沿
+ * 收尾写（单一终态归属），此处不写终态。
+ */
+function armBackgroundTimeout(task: BackgroundTask, timeoutSec: number): void {
+	const timer = setTimeout(() => {
+		// pid 复用防御（§3.6，同 reaper reapEntrySync / bash_kill 范式，宁不杀勿误杀）：
+		// 任务早已退出（exit 边沿未被轮询器收尾或竞态未及）且 pid 在到点前被系统复用
+		// 时，直接 killProcessTree 会杀掉复用 pid 上的无辜进程（整进程组 SIGKILL）。
+		if (!isRecordedPidStillOriginal(task)) {
+			logger.warn("background timeout: pid identity unverified (reuse suspected or start time unreadable), skipping kill", {
+				detail: {
+					taskId: task.taskId,
+					pid: task.pid,
+					pidStartTime: task.pidStartTime,
+					startedAt: task.startedAt,
+				},
+			});
+		} else {
+			killProcessTree(task.pid);
+		}
+		const marked = markKillingIntent(task.taskId, "timeout");
+		if (marked === undefined) return;
+		writeRegistryEntry(marked.registryPath, taskToRegistryEntry(marked));
+		ensurePollerRunning();
+	}, timeoutSec * MS_PER_SECOND);
+	timer.unref?.();
+	task.timeoutTimer = timer;
+}
+
+/**
+ * 到点 pid 身份校验：true = 登记时的原进程仍占用该 pid（可安全 kill-tree）。
+ * 判据（精确比较 / startedAt 秒级降级 / 读不到保守 false）单点定义于 reaper
+ * 的 pidStartMatchesRegistered，与 reapEntrySync 孤儿补杀共用同一份。
+ */
+function isRecordedPidStillOriginal(task: BackgroundTask): boolean {
+	const actualStartSec = getProcessStartTimeSec(task.pid);
+	if (actualStartSec === undefined) return false;
+	return pidStartMatchesRegistered(actualStartSec, task.pidStartTime, task.startedAt);
+}
+
+function accessOrThrow(cwd: string): void {
+	// 独立小函数：保持与内置 fsAccess(constants.F_OK) 语义一致的同步版本
+	accessSync(cwd, constants.F_OK);
+}
+
+export function truncateCommand(command: string): string {
+	return command.length > COMMAND_DISPLAY_LIMIT
+		? `${command.slice(0, COMMAND_DISPLAY_LIMIT)}…`
+		: command;
+}

package/src/background/subagent-guard.ts

@@ -0,0 +1,21 @@
+/**
+ * subagent 进程识别（D14 降级判据，探针 P5）。
+ *
+ * subagent-workflow 的 buildChildEnv（execution/session-runner.ts）对每个子 agent
+ * 进程**无条件**注入身份贯穿 env（PI_SUBAGENT_ROOT_SESSION_ID / SELF_RECORD_ID /
+ * DEPTH / ROOT_CWD，见其源码注释「无条件注入每个 subagent」）。任一存在 = 当前
+ * pi 进程是 subagent 子进程 → 本扩展降级：background:true 被忽略走前台同步语义。
+ *
+ * 为什么降级：子 agent 内后台化会破坏 workflow 结构化输出契约（预算耗尽时测试未
+ * 回）；且子进程死后其 registry 目录永远不会再有 session 启动，孤儿无人 reap。
+ */
+
+/** subagent-workflow 注入的身份贯穿 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);
+}