@zhushanwen/pi-base-tool-enhance 0.10.3 → 0.11.0

package/bin/taiji-fg-wrap

@@ -0,0 +1,197 @@
+#!/usr/bin/env bash
+# taiji-fg-wrap —— 前台命令空闲转后台包装脚本
+#
+# 设计依据：foreground-idle-to-background 设计文档 §5 部件 1 / §2.5 关键术语 / 矩阵 B（包装期事件）。
+# 由 execute 改写层注入到前台命令外层执行（矩阵 A5 格）：
+#   taiji-fg-wrap --idle <秒> --task-id <id> --log <日志路径> --pidfile <pid文件路径> -- <cmd.sh>
+#
+# 行为（矩阵 B）：
+#   - spawn 真实命令 `bash <cmd.sh>`：同进程组（后台子进程继承本脚本进程组，官方中止杀
+#     本组时真实命令一并被杀——B4）、非 detached、stdin 重定向 /dev/null（对齐官方前台
+#     spawn stdio ["ignore","pipe","pipe"]——命令读 stdin 立即 EOF，而非挂住）、
+#     stdout/stderr 追加重定向 --log 文件（命令输出通道与本脚本 stdout 物理分离——
+#     本脚本退出无管道关闭副作用，真实命令继续落盘——SIGPIPE 规避，B3 结构性保证）。
+#   - 写 pidfile：真实命令 pid + 启动时间（epoch 秒，spawn 时刻近似）。读者 = execute
+#     改写层收尾判定（B2 已死不登记 / B3·B5 活则登记为后台任务）。
+#   - 监控循环（间隔 = sleep 0.15 + 单轮固定开销，实测单轮 182-193ms ≤ 200ms——设计
+#     §5 部件 1「循环间隔 ≤200ms 与抄送延迟上限（矩阵 B1）同源、两口径必须一致」；
+#     校准实测（2026-10-31 darwin arm64，§9 检查点）：单轮固定开销 = now_ms（perl
+#     fork ~6ms）+ log_size（wc fork ~8ms），有新增输出时 +tail ~5ms；sleep 0.2 实测
+#     单轮 236-238ms 系统性超 200ms 口径，故取 0.15；同轮外层已取的日志 size 经参数
+#     传入 flush_log 复用，省去第二次 wc fork）：每轮先查命令死活
+#     （B6 单进程内顺序判定，天然串行无竞态）→ 死则抄完剩余输出、exit 透传真实退出码
+#     （B2）；活且空闲累积超阈值（当前时刻 − 最后输出字节时刻 ≥ 阈值，真实时钟度量，
+#     非按轮次计数）→ 打印转后台标记行、exit 0（B3，不杀命令）；活且未超 → 抄送日志
+#     新增字节到自身 stdout（B1，官方管道流式显示）。
+#
+# 标记协议（§5 部件 3，三方契约逐字实现，主要消费者 = 模型）：
+#   [TAIJI-FG-BG] Command moved to background after Ns without output — still running,
+#   NOT finished (no exit code yet). Full log: <path> Check: bash_output {task_id:"<id>"};
+#   terminate: bash_kill {task_id:"<id>"}. It will notify on completion — DO NOT bash
+#   sleep while waiting.
+#
+# 已接受代价（设计登记，不加防）：spawn 与写 pidfile 之间的毫秒级窗口内本脚本被杀时
+# pidfile 缺失、B5 兜底对该次失效（命令可能残留，与现状 pi 原生执行中宿主崩溃残留同级）。
+#
+# 兼容性：bash 3.2（macOS /bin/bash）子集——无关联数组 / mapfile / ${var,,} 等特性。
+# 亚秒时钟源 = perl Time::HiRes（darwin/linux 自带；空闲阈值触发精度依赖亚秒时刻，
+# 秒级 date 会使 idle 2s 触发窗漂移至 3.2s）；perl 不可用时回退秒级粒度。
+
+set -u
+
+usage_exit() {
+	echo "taiji-fg-wrap: usage: taiji-fg-wrap --idle <sec> --task-id <id> --log <path> --pidfile <path> -- <cmd.sh>" >&2
+	exit 64
+}
+
+IDLE_SEC=""
+TASK_ID=""
+LOG_PATH=""
+PIDFILE_PATH=""
+CMD_SH=""
+
+while [ $# -gt 0 ]; do
+	case "$1" in
+	--idle)
+		[ $# -ge 2 ] || usage_exit
+		IDLE_SEC="$2"
+		shift 2
+		;;
+	--task-id)
+		[ $# -ge 2 ] || usage_exit
+		TASK_ID="$2"
+		shift 2
+		;;
+	--log)
+		[ $# -ge 2 ] || usage_exit
+		LOG_PATH="$2"
+		shift 2
+		;;
+	--pidfile)
+		[ $# -ge 2 ] || usage_exit
+		PIDFILE_PATH="$2"
+		shift 2
+		;;
+	--)
+		shift
+		break
+		;;
+	*)
+		echo "taiji-fg-wrap: unknown argument: $1" >&2
+		usage_exit
+		;;
+	esac
+done
+
+[ $# -ge 1 ] || {
+	echo "taiji-fg-wrap: missing cmd.sh path after --" >&2
+	exit 64
+}
+CMD_SH="$1"
+shift
+[ $# -eq 0 ] || {
+	echo "taiji-fg-wrap: unexpected extra arguments after cmd.sh" >&2
+	exit 64
+}
+
+case "$IDLE_SEC" in
+'' | *[!0-9]*)
+	echo "taiji-fg-wrap: --idle requires a non-negative integer (seconds), got: $IDLE_SEC" >&2
+	exit 64
+	;;
+esac
+for required in "$TASK_ID" "$LOG_PATH" "$PIDFILE_PATH"; do
+	[ -n "$required" ] || {
+		echo "taiji-fg-wrap: --task-id / --log / --pidfile are all required" >&2
+		usage_exit
+	}
+done
+[ -f "$CMD_SH" ] || {
+	echo "taiji-fg-wrap: cmd.sh not found: $CMD_SH (confirm the injector wrote the command file before invoking)" >&2
+	exit 66
+}
+
+# 毫秒时刻。perl 失败回退 date +%s 的秒级粒度（精度降级，功能不中断）。
+now_ms() {
+	local t
+	t=$(perl -MTime::HiRes=time -e 'printf("%d\n", time() * 1000)' 2>/dev/null) || t=""
+	[ -n "$t" ] || t=$(( $(date +%s) * 1000 ))
+	printf '%s\n' "$t"
+}
+
+# 日志当前字节数；读取失败保持传入基线（调用方传当前 offset）。
+# wc 输出按平台可能带前导空白（macOS BSD wc 对 stdin 输入补空格），先剥空白再校验。
+log_size() {
+	local size
+	size=$(wc -c <"$1" 2>/dev/null) || size="$2"
+	size="${size//[[:space:]]/}"
+	case "$size" in
+	'' | *[!0-9]*) size="$2" ;;
+	esac
+	printf '%s\n' "$size"
+}
+
+# 抄送日志新增字节到自身 stdout（B1），推进 offset。
+# 按字节 offset 接续 = 累积缓冲形态：UTF-8 多字节字符跨批次时字节流无损（管道字节
+# 拼接完整），仅中间批次的渲染可能临时切半，由后续批次补全——不丢不重。
+# 输出量以快照 size 为准（head -c 截断）：快照与 tail 执行之间存在毫秒级窗口，窗口内
+# 命令新写的字节会被 tail 一并读到 EOF——若照单输出而 offset 只推进到快照值，下一轮
+# 将重复抄送该段（同段字节两次进入抄送流）。head 按 $((size - log_offset)) 截断后，
+# 快照后新字节留给下一轮，不重不丢。head 读满即退，tail 后续写入收 SIGPIPE 是预期
+# （本脚本无 pipefail / errexit，不影响退出码透传）。
+# $1 可选 = 外层本轮已取的日志 size：复用可省同轮第二次 wc fork（单轮固定开销
+# 校准项，见文件头实测登记）；缺省时内部自取（B2 收尾路径仅调一次，开销不敏感）。
+flush_log() {
+	local size
+	if [ $# -ge 1 ]; then
+		size="$1"
+	else
+		size=$(log_size "$LOG_PATH" "$log_offset")
+	fi
+	if [ "$size" -gt "$log_offset" ]; then
+		tail -c +$((log_offset + 1)) "$LOG_PATH" | head -c $((size - log_offset))
+		log_offset="$size"
+	fi
+}
+
+# spawn 真实命令：同进程组（继承）、非 detached、stdin=/dev/null（读即 EOF）、
+# stdout/stderr 追加落日志。日志文件由改写层保证父目录存在；append 而非 truncate。
+bash "$CMD_SH" >>"$LOG_PATH" 2>&1 </dev/null &
+child_pid=$!
+
+# 写 pidfile（spawn 后毫秒级窗口内完成；该窗口被杀时 pidfile 缺失 = 设计已接受代价）。
+# pidStartTimeSec 为 spawn 时刻近似值（epoch 秒）——跨平台 ps lstart 解析（BSD/GNU
+# date 语法分裂 + locale 脆弱）不值当；秒级精度下近似值与进程真实启动时刻几乎总同秒，
+# pid 复用防御的精确身份校验由消费方按 getProcessStartTimeSec 复核。
+pid_spawn_ms=$(now_ms)
+printf '{"pid":%d,"pidStartTimeSec":%d}\n' "$child_pid" "$((pid_spawn_ms / 1000))" >"$PIDFILE_PATH"
+
+idle_threshold_ms=$((IDLE_SEC * 1000))
+log_offset=0
+last_byte_ms=$(now_ms)
+
+while true; do
+	sleep 0.15
+
+	# B6：每轮先查死活（判死 = kill -0 ESRCH = bash 已收割后台作业，wait 立即返回状态）
+	if ! kill -0 "$child_pid" 2>/dev/null; then
+		flush_log # B2：抄完剩余输出再透传
+		wait "$child_pid" 2>/dev/null
+		exit $?
+	fi
+
+	# B1：先感知新增输出刷新空闲计时（防「刚有输出未感知即误判空闲」），再判空闲
+	now=$(now_ms)
+	size=$(log_size "$LOG_PATH" "$log_offset")
+	if [ "$size" -gt "$log_offset" ]; then
+		flush_log "$size"
+		last_byte_ms="$now"
+	fi
+
+	# B3：空闲累积超阈值（真实时钟静默时长，非轮次计数）→ 不杀命令，打印标记行，exit 0
+	if [ $((now - last_byte_ms)) -ge "$idle_threshold_ms" ]; then
+		elapsed_s=$(( (now - last_byte_ms) / 1000 ))
+		printf '[TAIJI-FG-BG] Command moved to background after %ds without output — still running, NOT finished (no exit code yet). Full log: %s Check: bash_output {task_id:"%s"}; terminate: bash_kill {task_id:"%s"}. It will notify on completion — DO NOT bash sleep while waiting.\n' "$elapsed_s" "$LOG_PATH" "$TASK_ID" "$TASK_ID"
+		exit 0
+	fi
+done

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-base-tool-enhance",
-  "version": "0.10.3",
+  "version": "0.11.0",
   "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",
@@ -25,15 +25,17 @@
   "files": [
     "src/",
     "index.ts",
-    "skills/"
+    "skills/",
+    "bin/"
   ],
   "dependencies": {
-    "@zhushanwen/extension-protocol": "0.25.0",
-    "@zhushanwen/pi-delivery-port": "0.3.1",
-    "@zhushanwen/pi-ext-guards": "0.5.0",
+    "@zhushanwen/extension-protocol": "0.27.0",
+    "@zhushanwen/pi-delivery-port": "0.4.0",
+    "@zhushanwen/pi-ext-guards": "0.5.1",
     "@zhushanwen/pi-extension-logger": "0.6.2",
     "@zhushanwen/pi-file-lock": "0.4.1",
-    "@zhushanwen/pi-llm-shared": "0.12.0"
+    "@zhushanwen/pi-llm-shared": "0.12.1",
+    "@zhushanwen/subagent-core": "2.2.0"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.1.9",
@@ -43,7 +45,7 @@
     "@earendil-works/pi-coding-agent": "^1.0.0",
     "@earendil-works/pi-tui": "^1.0.0",
     "typebox": "1.3.27",
-    "@zhushanwen/pi-pending-notifications": "0.11.1"
+    "@zhushanwen/pi-pending-notifications": "0.11.3"
   },
   "peerDependenciesMeta": {
     "@earendil-works/pi-tui": {

package/skills/base-tool-enhance-ext-config/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: base-tool-enhance-ext-config
-description: "使用或排查 @zhushanwen/pi-base-tool-enhance 的 bash 后台/白名单配置时加载。说明配置文件路径与热重载生效时机、5 键 schema（forceBackgroundPatterns / disableBuiltinForcePatterns / foregroundTimeoutSeconds / backgroundTimeoutSeconds / maxConcurrentBackground）与默认值、force-background 白名单命中语义（测试命令自动转后台、忽略显式 timeout、返回 task_id）、用户正则自动命令位置锚定约定（无需自带 ^）。触发词：bash background、后台任务配置、force-background 白名单、测试命令自动后台、dev server 自动后台、backgroundTimeoutSeconds、foregroundTimeoutSeconds、maxConcurrentBackground、base-tool-enhance-ext-config。"
+description: "使用或排查 @zhushanwen/pi-base-tool-enhance 的 bash 后台/白名单配置时加载。说明配置文件路径与热重载生效时机、6 键 schema（forceBackgroundPatterns / disableBuiltinForcePatterns / foregroundTimeoutSeconds / backgroundTimeoutSeconds / idleBackgroundSec / maxConcurrentBackground）与默认值、force-background 白名单命中语义（测试命令自动转后台、忽略显式 timeout、返回 task_id）、用户正则自动命令位置锚定约定（无需自带 ^）。触发词：bash background、后台任务配置、force-background 白名单、测试命令自动后台、dev server 自动后台、backgroundTimeoutSeconds、foregroundTimeoutSeconds、idleBackgroundSec、maxConcurrentBackground、base-tool-enhance-ext-config。"
 ---
 
 # base-tool-enhance 配置指南
@@ -23,7 +23,7 @@ description: "使用或排查 @zhushanwen/pi-base-tool-enhance 的 bash 后台/
 
 文件不存在 / JSON 解析失败 → 全默认值继续工作（工具不报错，warn 落扩展日志）。单键类型错/非法值 → **仅该键**回退默认 + warn，不整体拒载；未知键忽略（前向兼容）。
 
-## 字段表（5 键）
+## 字段表（6 键）
 
 | 字段 | 类型 | 默认 | 说明 |
 |------|------|------|------|
@@ -31,6 +31,7 @@ description: "使用或排查 @zhushanwen/pi-base-tool-enhance 的 bash 后台/
 | `disableBuiltinForcePatterns` | boolean | `false` | `true` = 关闭内置 force-test / force-longrun 两组，只用用户正则 |
 | `foregroundTimeoutSeconds` | number \| null | `null` | `null` = 不注入（pi 原生不限时）；正数 = 前台命令未填 timeout 时注入的默认秒数。非正数/非有限数 → 回退 null + warn；超 int32 毫秒上限自动 clamp |
 | `backgroundTimeoutSeconds` | number \| null | `null` | 同上，后台任务未填 timeout 时的默认秒数 |
+| `idleBackgroundSec` | number \| null | `600` | 前台命令输出静默满此值转后台（不杀命令，只解除阻塞）；显式 null = 关闭机制；坏值回退默认 + warn，小数 floor 至 ≥1 |
 | `maxConcurrentBackground` | number | `8` | 后台任务并发上限，正整数（小数取 floor） |
 
 示例（最小可用——只关内置白名单 + 给用户正则 + 后台默认超时）：
@@ -41,6 +42,7 @@ description: "使用或排查 @zhushanwen/pi-base-tool-enhance 的 bash 后台/
   "forceBackgroundPatterns": ["pnpm\\s+typecheck", "make\\s+-j\\d+"],
   "foregroundTimeoutSeconds": null,
   "backgroundTimeoutSeconds": 600,
+  "idleBackgroundSec": 600,
   "maxConcurrentBackground": 8
 }
 ```

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

@@ -15,14 +15,17 @@
 //     属「代码 + OS 组合行为」，本地默认跳过（门控 SSOT = test-guard/integration-gate.ts）。
 //   - 预算：单测用例走 vitest 默认；集成组用例单独挂 20s（原文件级预算随拆组下沉到
 //     用例级，非抬升），轮询 deadline 常量（10s / 8s）仅集成组消费。
-import { existsSync, mkdtempSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import { EventEmitter } from "node:events";
 
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { BashOperations, ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { afterAll, afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
+import { clearConfigCache } from "@zhushanwen/pi-llm-shared";
+
 import { INTEGRATION_TESTS_ENABLED, INTEGRATION_TESTS_SKIP_REASON } from "../../../../../test-guard/integration-gate.ts";
 
 // getAgentDir → 测试临时数据目录（工具 execute 内部调用，不写真 ~/.pi/agent）。
@@ -86,6 +89,7 @@ import type { BackgroundTask, 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 { handleUserBash } from "../user-bash-interceptor.ts";
 
 const DATA_DIR = mkdtempSync(join(tmpdir(), "bte-data-"));
 
@@ -353,7 +357,7 @@ describe("bash_output tool", () => {
 		await expect(outputTool({ task_id: "bt-none" })).rejects.toThrow(/No such task/);
 	});
 
-	it("P0-1: list merges only TERMINAL registry entries — running entries stay invisible (§3.5)", async () => {
+	it("P0-1: list merges only TERMINAL registry entries — running entries stay invisible", async () => {
 		// 独立 session 目录：单例表空 + registry 含 running 与 exited 两条他进程条目
 		// （模拟 resume 被强杀 session：runtime 收殓转终态前的窗口里 registry 残留 running）
 		const sid = "sess-p0-list";
@@ -369,7 +373,7 @@ describe("bash_output tool", () => {
 		expect(ids).not.toContain("bt-xrun"); // running 条目不并入——无幻影 running 行
 	});
 
-	it("P0-1: detail registry fallback is terminal-only — cross-process running entry not queryable (§3.5)", async () => {
+	it("P0-1: detail registry fallback is terminal-only — cross-process running entry not queryable", async () => {
 		const sid = "sess-p0-detail";
 		const path = getRegistryPath(DATA_DIR, sid);
 		writeRegistryEntry(path, makeRegistryEntry({ taskId: "bt-xrun2", state: "running" }));
@@ -383,7 +387,7 @@ describe("bash_output tool", () => {
 		expect(detail.exitCode).toBe(3);
 	});
 
-	it("deleted output file degrades to <lost> without crashing (§3.6)", async () => {
+	it("deleted output file degrades to <lost> without crashing", async () => {
 		const task = spawnOk("sleep 0.1 && echo gone");
 		emitFakeExit(task, 0);
 		unlinkSync(task.outputFile);
@@ -816,9 +820,9 @@ describe("D15: abort signal does not propagate to background tasks", () => {
 	});
 });
 
-// ──────────────────────── 单测层：spawn 失败路径（§3.6） ────────────────────────
+// ──────────────────────── 单测层：spawn 失败路径 ────────────────────────
 
-describe("spawn failure paths (§3.6)", () => {
+describe("spawn failure paths", () => {
 	it("nonexistent cwd reports the builtin-style error", () => {
 		const result = spawnBackgroundTask({
 			command: "echo hi",
@@ -1007,3 +1011,213 @@ describe.skipIf(!INTEGRATION_TESTS_ENABLED)(
 		);
 	},
 );
+
+// ──────────────────────── 集成组：user_bash 拦截层真进程形态（M2/U2，RL4/RL5/B5）────────────────────────
+//
+// completion-signal-delivery M2 门控集成（testCommand 第二条精确覆盖本组）：真 spawn
+// taiji-fg-wrap + 真实时钟空闲触发（idleBackgroundSec=2 经配置注入）+ 真信号组杀。
+// RL4 转后台 = settled 的 exec 侧前提（resolve 不 reject）/ RL5 abort 通道组杀 / B5
+// wrapper 异常死亡兜底登记。真实时钟与进程信号时序无确定性完成信号——挂门控
+// （test-guard/integration-gate.ts），等待写法 = 等 exec promise + pollUntilTicked。
+describe.skipIf(!INTEGRATION_TESTS_ENABLED)(
+	`user_bash interceptor real process (M2/U2: idle-to-background / abort / B5)${INTEGRATION_TESTS_SKIP_REASON ? `｜skip：${INTEGRATION_TESTS_SKIP_REASON}` : ""}`,
+	() => {
+		const TASKS_DIR = dirname(REGISTRY_PATH);
+		const USER_MARKER_PREFIX = "[TAIJI-FG-BG] 已转后台";
+		// 空闲阈值注入：config 文件 idleBackgroundSec=2（门控用例秒级实测，先例 --idle 2 形态）
+		let configDir = "";
+		// 本组快照（相对断言基线）：同文件既有用例共享 DATA_DIR，磁盘 registry 与
+		// tasks 目录非空，「无本次残留」必须按快照差集断言，不能断言全空
+		let taskIdsBefore = new Set<string>();
+		let filesBefore = new Set<string>();
+
+		function createMockPi() {
+			return { events: { emit: vi.fn() }, sendMessage: vi.fn(), appendEntry: vi.fn() };
+		}
+
+		/** 轮询直到 getter 产出非 undefined 值（pidfile 出现等文件系统就绪信号）。 */
+		async function pollForValue<T>(get: () => T | undefined, deadlineMs: number, what: string): Promise<T> {
+			const deadline = Date.now() + deadlineMs;
+			for (;;) {
+				const value = get();
+				if (value !== undefined) return value;
+				if (Date.now() > deadline) {
+					throw new Error(`timed out after ${deadlineMs}ms waiting for ${what}`);
+				}
+				await sleep(25);
+			}
+		}
+
+		function snapshotBefore(): void {
+			taskIdsBefore = new Set(readRegistry(REGISTRY_PATH).keys());
+			filesBefore = new Set(existsSync(TASKS_DIR) ? readdirSync(TASKS_DIR) : []);
+		}
+
+		/** 本次 exec 新产生的磁盘文件（与快照差集）。 */
+		function newFilesSince(): string[] {
+			return (existsSync(TASKS_DIR) ? readdirSync(TASKS_DIR) : []).filter((f) => !filesBefore.has(f));
+		}
+
+		/**
+		 * 等 pidfile 出现并返回（wrapperPid, cmdPid）：pidfile 写的是真实命令 pid（wrapper
+		 * 协议），wrapper 自身 pid = 命令的进程组 id（wrapper detached 成组长）——经
+		 * ps 查 pgid 得组长（B5 单杀 wrapper 用）。
+		 */
+		async function waitForPidfile(): Promise<{ wrapperPid: number; cmdPid: number; pidfilePath: string }> {
+			const pidfilePath = await pollForValue(() => {
+				const file = readdirSync(TASKS_DIR).find((f) => f.endsWith(".pid") && !filesBefore.has(f));
+				return file === undefined ? undefined : join(TASKS_DIR, file);
+			}, POLL_DEADLINE_MS, "pidfile to appear");
+			const cmdPid = (JSON.parse(readFileSync(pidfilePath, "utf8")) as { pid: number }).pid;
+			const pgid = Number.parseInt(execFileSync("ps", ["-o", "pgid=", "-p", String(cmdPid)], { encoding: "utf8" }).trim(), 10);
+			return { wrapperPid: pgid, cmdPid, pidfilePath };
+		}
+
+		/** 经真实 handler（格判定 + 构造）取包装 ops（门控组默认档全命中）。 */
+		function wrappedOps(command: string): BashOperations["exec"] {
+			const handlerResult = handleUserBash(
+				{ type: "user_bash", command, excludeFromContext: false, cwd: process.cwd() },
+				makeCtx() as never,
+			);
+			if (handlerResult === undefined || !("operations" in handlerResult)) {
+				throw new Error(`expected wrapped operations for: ${command}`);
+			}
+			return handlerResult.operations.exec;
+		}
+
+		beforeEach(() => {
+			spawnMode.real = true;
+			snapshotBefore();
+			// idle 阈值 2s：config 注入（loadBaseToolEnhanceConfig 读时刷新即生效）
+			configDir = mkdtempSync(join(tmpdir(), "bte-ubash-cfg-"));
+			vi.stubEnv("PI_CODING_AGENT_DIR", configDir);
+			const configPath = join(configDir, "config", "base-tool-enhance-ext-config.json");
+			mkdirSync(dirname(configPath), { recursive: true });
+			writeFileSync(configPath, `${JSON.stringify({ idleBackgroundSec: 2 })}\n`, "utf8");
+			clearConfigCache();
+		});
+
+		afterEach(() => {
+			clearConfigCache();
+			if (configDir !== "") {
+				rmSync(configDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
+				configDir = "";
+			}
+		});
+
+		it(
+			"RL4 转后台形态：空闲阈值触发 → exec resolve({exitCode:null}) 不 reject + 登记运行态 + 用户向标记行 + 三文件保留（settled 已执行已收尾的 exec 侧前提）",
+			{ timeout: 20_000 },
+			async () => {
+				const pi = createMockPi();
+				refreshPiReference(pi as unknown as ExtensionAPI);
+				const chunks: Buffer[] = [];
+				// sleep 4 > idle 2：转后台后命令继续跑；输出静默 2s 触发 wrapper 标记行
+				const result = await wrappedOps("sleep 4 && echo done")("sleep 4 && echo done", process.cwd(), {
+					onData: (chunk: Buffer) => chunks.push(chunk),
+				});
+
+				// exec resolve 不 reject、exitCode null（官方组装层呈现 exitCode undefined +
+				// cancelled false，AS11 → rpc success → runtime settled 回执；bash 通道占用
+				// 随 RPC 返回复位——D3 V6 断言的通道复用前提）
+				expect(result).toEqual({ exitCode: null });
+
+				// 登记：单例表 running + registry running + pending:register emit
+				const task = getActiveTasks()[0];
+				expect(task).toBeDefined();
+				expect(task?.command).toBe("sleep 4 && echo done");
+				expect(readRegistry(REGISTRY_PATH).get(task!.taskId)?.state).toBe("running");
+				expect(pi.events.emit).toHaveBeenCalledWith(
+					"pending:register",
+					{ id: task!.taskId, type: "bash", name: "sleep 4 && echo done" },
+				);
+
+				// 用户向标记行经 onData 到达（D3 产品形态①）。禁词断言只约束 exec 补发的
+				// 用户向行——wrapper 协议标记行（模型向，含 bash_output/bash_kill 语法）经
+				// 抄送流先到是三方协议原样透传，不属于本断言对象
+				const output = Buffer.concat(chunks).toString("utf8");
+				const userMarker = output.split("\n").find((line) => line.startsWith(USER_MARKER_PREFIX));
+				expect(userMarker).toBeDefined();
+				expect(userMarker).toContain("侧边栏");
+				expect(userMarker).not.toContain("bash_output");
+				expect(userMarker).not.toContain("bash_kill");
+
+				// 三文件保留（转后台任务日志 = bash_output 数据源）
+				expect(existsSync(task!.outputFile)).toBe(true);
+				expect(existsSync(join(TASKS_DIR, `${task!.taskId}.sh`))).toBe(true);
+				expect(existsSync(join(TASKS_DIR, `${task!.taskId}.pid`))).toBe(true);
+
+				// 守望收尾链可达（先例设施零重建的端到端证据）：命令自然退出后 exited + 通知
+				await pollUntilTicked(() => getTask(task!.taskId)?.state === "exited", POLL_DEADLINE_MS, "watch finalization");
+				expect(getTask(task!.taskId)?.reason).toBe("natural");
+				expect(pi.sendMessage).toHaveBeenCalled();
+				const notified = pi.sendMessage.mock.calls[0]![0] as { customType: string };
+				expect(notified.customType).toBe("background-bash");
+			},
+		);
+
+		it(
+			"RL5 abort 通道：signal 中止 → wrapper 进程组整组被杀（真实命令无残留）+ exec 抛 aborted + 无登记 + 三文件清理",
+			{ timeout: 20_000 },
+			async () => {
+				const pi = createMockPi();
+				refreshPiReference(pi as unknown as ExtensionAPI);
+				const controller = new AbortController();
+				const execPromise = wrappedOps("sleep 300")("sleep 300", process.cwd(), {
+					onData: () => {},
+					signal: controller.signal,
+				});
+
+				// 等 wrapper 写 pidfile（spawn 后毫秒级窗口）取真实命令 pid，供组杀后判死断言
+				const { cmdPid } = await waitForPidfile();
+				expect(cmdPid).toBeGreaterThan(0);
+
+				controller.abort();
+				// 官方式 aborted 上抛（executor catch signal.aborted → cancelled: true 组装）
+				await expect(execPromise).rejects.toThrow("aborted");
+
+				// 组杀生效：真实命令（与 wrapper 同组）轮询判死（SIGKILL 生效延迟满载不可预估）
+				await pollUntilTicked(() => !isPidAlive(cmdPid), POLL_DEADLINE_MS, "aborted command group to die");
+
+				// 用户中止无登记（与 agent 侧 B4 同语义）：运行时权威（单例表）零新增 +
+				// 磁盘 registry 零新增条目 + 三文件零残留（同文件既有用例共享 DATA_DIR，
+				// 按快照差集断言）+ 通知链零接触
+				expect(getActiveTasks()).toHaveLength(0);
+				expect([...readRegistry(REGISTRY_PATH).keys()].filter((id) => !taskIdsBefore.has(id))).toEqual([]);
+				expect(newFilesSince()).toEqual([]);
+				expect(pi.events.emit).not.toHaveBeenCalled();
+				expect(pi.sendMessage).not.toHaveBeenCalled();
+			},
+		);
+
+		it(
+			"B5 兜底：wrapper 异常死亡（单杀 wrapper 自身）且命令进程存活 → 照常登记转后台 + 用户向标记行补发 + resolve({exitCode:null})",
+			{ timeout: 20_000 },
+			async () => {
+				const pi = createMockPi();
+				refreshPiReference(pi as unknown as ExtensionAPI);
+				const chunks: Buffer[] = [];
+				const execPromise = wrappedOps("sleep 30")("sleep 30", process.cwd(), {
+					onData: (chunk: Buffer) => chunks.push(chunk),
+				});
+
+				// 等 pidfile 出现后单杀 wrapper 自身（wrapper pid = 命令的 pgid，组长；单杀
+				// 组长非组杀——真实命令同组存活 = B5 判定形态「wrapper 异常死亡且命令进程活着」）
+				const { wrapperPid } = await waitForPidfile();
+				process.kill(wrapperPid, "SIGKILL");
+
+				const result = await execPromise;
+				expect(result).toEqual({ exitCode: null });
+
+				// 照常登记（命令进程活着 = 承诺在）+ 用户向标记行补发（wrapper 未及打印）
+				const task = getActiveTasks()[0];
+				expect(task).toBeDefined();
+				expect(task?.command).toBe("sleep 30");
+				expect(readRegistry(REGISTRY_PATH).get(task!.taskId)?.state).toBe("running");
+				expect(Buffer.concat(chunks).toString("utf8")).toContain(USER_MARKER_PREFIX);
+				// 登记的原 pid 仍是存活的命令进程（B5 兜底语义：任务接管不丢）
+				expect(isPidAlive(task!.pid)).toBe(true);
+			},
+		);
+	},
+);